Arguments:

• <SOURCES> — Source molecule IDs to merge (space-separated)

Options:

• --formula <FORMULA> — Formula for the product molecule

• --product-kind <PRODUCT_KIND> — Kind for the product molecule (default: decision)

  Default value: decision

• --reason <REASON> — Reason for the merge

cs transform

Transform a molecule's kind (idea → task, etc.)

Usage: cs transform --to <TO> --reason <REASON> <MOLECULE>

EXAMPLES: cs transform --to task # idea → task cs transform --to decision

Preserves molecule ID; rewrites kind + formula bindings.

Arguments:

• <MOLECULE> — Molecule ID to transform

Options:

• --to <TO> — Target kind: idea, task, decision, issue
• --reason <REASON> — Reason for the transform

cs tag

Tag — add or remove typed labels on a molecule

Usage: cs tag [OPTIONS] <MOLECULE_ID>

EXAMPLES: cs tag --add temp:hot cs tag --remove temp:warm --add temp:frozen

Temperature tags govern backlog curation — see CLAUDE.md § Molecule Temperature Tags.

Arguments:

• <MOLECULE_ID> — Molecule ID to retag

Options:

• --add <TAG> — Tag to add (repeatable). Format: key or key:value
• --remove <TAG> — Tag to remove (repeatable). Matched by exact string

Fleet management commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs ensemble

Display ensemble status — observe the fleet at a glance

Usage: cs ensemble [OPTIONS]

EXAMPLES: cs ensemble # all molecules, all fleets cs ensemble --tag temp:hot # actionable backlog snapshot cs ensemble --fleet research # one fleet only cs ensemble --json # NDJSON for scripting

Options:

• --all — Show molecules from all projects, not just the current one

• --cluster [alias: cluster] — Walk every .cosmon/-bearing galaxy under $COSMON_CLUSTER_ROOT (default $HOME/galaxies) and print one aggregated table.

  This is the cross-galaxy extension of --all. Where --all drops the project-id filter within the current state dir, --cluster visits every sibling galaxy on disk and prints their workers + molecule counts. Works in tandem with --all (implicitly drops the project filter because the scope is now the whole cluster).

  Also prints one host reading — memory, swap, the kernel's own pressure level, CPUs and load, with units — and the machine-wide totals derived from the galaxies scanned, including harvests holding a galaxy's trunk lock (a cs done in its post-merge gate phase has no live worker). Observations only: no threshold is applied and nothing is refused. A counter that could not be read prints unavailable, never 0; if the host cannot be read at all the galaxy view still renders and the reason goes to stderr.

• --cluster-root <DIR> — Override the cluster root directory when --cluster is set. Defaults to $COSMON_CLUSTER_ROOT env var, then $HOME/galaxies

• --tag <GLOB> — Filter molecules by tag glob pattern (repeatable, any-match).

  Patterns support * as wildcard. Example: --tag deferred:*. Molecules without a matching tag are excluded from the molecule summary counts.

cs purge

Purge dead workers from fleet state without changing molecule status

Usage: cs purge [OPTIONS] [WORKER]

EXAMPLES: cs purge # sweep: remove Stopped / Error / Stale workers cs purge worker-3 # targeted: remove a single worker (graceful path) cs purge worker-3 --force # targeted + SIGKILL tmux (supersedes cs kill)

ADR-052 §D3 collapses cs kill + cs purge into this one verb: both are infrastructure teardown. Sweep mode (no argument) stays unchanged; targeted mode with --force replaces cs kill.

SEE ALSO: cs freeze (graceful + state preservation), cs teardown (fleet-wide graceful shutdown).

Arguments:

• <WORKER> — Optional worker ID — when given, targeted purge of that worker only.

  Without a worker the command sweeps every terminal-state worker from fleet state (the pre-ADR-052 behaviour). With a worker, only that worker is removed; pair with --force to SIGKILL its tmux session first (formerly cs kill).

Options:

• --force — In targeted mode, SIGKILL the tmux session before removing the fleet entry. Ignored in sweep mode. Supersedes the stand-alone cs kill verb (ADR-052 §D3)

• --status <STATUS> — Only purge workers matching this desired state (default: sweep all workers — Stopped ones and Running/Paused ones whose tmux session is gone)

• --role <ROLE> — Restrict the purge to workers matching this role discriminator — either cognition or runtime (see WorkerRole). Without this flag cs purge removes both runtime and cognition workers that meet the status predicate; with it, operators can clean up one half of a runtime+cognition pair without collapsing the other

• --allow-unharvested — Permit reclaiming a worker whose molecule has unharvested changes.

  Without this flag cs purge fails closed: a worker whose pane is gone but whose branch still carries commits — or whose worktree still has uncommitted files — is left in the fleet, its molecule left running, and the commits and files at stake are named in an alert. With this flag the worker is removed but the molecule stays Running. A dead tmux session is evidence about the pane, not about the work (incident 2026-08-02, where four molecules were silently collapsed after a reboot with up to three commits each still unmerged).

• --worktrees — Also run the .worktrees/ reclamation pass (issue 61).

  Enumerates readdir(.worktrees/) ∪ git worktree list --porcelain — the filesystem and Git's own registry, not the worker roster, which is keyed by molecule and could not see a directory that has none. Reports every candidate: the reclaimable derived output on one side, and on the other every worktree withheld with its reason.

  Reclamation is opt-in and one tier deep. On its own this flag removes nothing; --allow-unharvested — the same gesture the sweep already uses, not a second one — executes the derived half. Durable content is never removed by any path in this command, whatever the flags (ADR-178): the eligibility verdict is advisory and is printed, not acted on.

• --sessions — Also run the tmux session reclamation pass (ADR-179).

  Enumerates the galaxy's tmux socket — list-panes -a, not the worker roster. The roster is precisely what cannot see this population: the sweep above removes a terminal molecule's worker entry and the session it named lives on, unattributable, holding an agent process and its whole heap for as long as the machine is up. Each session is attributed by computing every known molecule's session name forward and matching, never by parsing a molecule id back out of a session name.

  Reclamation is opt-in exactly as --worktrees is: on its own this flag kills nothing, and --allow-unharvested — the same gesture, not a second one — executes it. A session is reclaimed only when its molecule is terminal, no client is attached, and its scrollback has been captured to that molecule's directory first.

• --dry-run — Report what would change and change nothing.

  Applies to the whole command: no fleet entry is removed, no molecule is changed, no event is emitted and no byte is reclaimed. The --worktrees pass is dry by default and stays dry here.

cs kill

Kill a worker — immediate termination (no state flush)

Usage: cs kill <WORKER>

EXAMPLES: cs kill worker-3 # DEPRECATED — see below

DEPRECATED (ADR-052 §D3): use cs purge worker-3 --force instead. This alias will be removed after one release cycle.

SEE ALSO: cs purge (canonical), cs freeze (preserve state), cs done (teardown after a molecule completes).

Arguments:

• <WORKER> — ID of the worker to terminate

cs quench

Quench a worker — graceful shutdown with state preservation

Usage: cs quench [OPTIONS] <WORKER>

EXAMPLES: cs quench worker-3 # DEPRECATED — see below

DEPRECATED (ADR-052 §D3): use cs freeze worker-3 --reason quench instead. Graceful shutdown with state preservation IS freeze; --reason captures operator intent. Note: the canonical path lands in Paused (resumable via cs thaw) rather than Stopped. This alias will be removed after one release cycle.

SEE ALSO: cs freeze (canonical), cs purge (fleet teardown), cs teardown (fleet-wide graceful shutdown).

Arguments:

• <WORKER> — ID of the worker to gracefully shut down

Options:

• --timeout <TIMEOUT> — Grace period in seconds before force-killing (default: 30)

  Default value: 30

• --force — Skip graceful exit — go straight to force-kill (same as kill)

• --no-tmux — Skip tmux interaction (state-only transition, for testing)

cs teardown

Teardown a fleet — gracefully stop all fleet workers

Usage: cs teardown [OPTIONS] <FLEET>

EXAMPLES: cs teardown # gracefully stop every worker in the default fleet cs teardown --fleet research

SEE ALSO: cs kill (single worker, hard), cs quench (single worker, graceful).

Arguments:

• <FLEET> — Name of the fleet to tear down (matches fleet.toml fleet = "..." name)

Options:

• --force — Force-kill instead of graceful quench
• --no-tmux — Skip tmux interaction (state-only, for testing)

cs resume

Resume — convenience alias for cs patrol --propel --molecule <id>

Usage: cs resume [OPTIONS]

EXAMPLES: cs resume # nudge all idle workers cs resume worker-3 # nudge one

Convenience alias for cs patrol --propel --molecule <id> — maintains the Propelled regime by re-delivering the propulsion signal. Does NOT change state or advance molecules.

SEE ALSO: cs patrol --propel (canonical command), cs thaw (frozen workers).

Options:

• --fleet <FLEET> — Only resume workers in this fleet
• --agent <AGENT> — Only resume this specific agent (by name, across all fleets)
• -c, --message <MESSAGE> — Custom resume message (default: standard RESUME signal)

cs patrol

Patrol the fleet — health checks and anomaly detection

Usage: cs patrol [OPTIONS]

EXAMPLES: cs patrol # run one health sweep cs patrol --propel # nudge stale molecules cs patrol --respawn # restart dead workers cs patrol --harvest # close Completed-but-unmerged molecules cs patrol --silence-detect # flag workers that stopped heartbeating cs patrol --livelock # detect circular blocked-on waits cs patrol --event-age # flag Running molecules with a quiet event log cs patrol --heal # remediate safe anomaly classes, each §5-guarded cs patrol --heal --dry-run # preview the Deacon's actions, mutate nothing

Designed to be run by an external scheduler (cron, launchd) in the Propelled regime. --harvest is the belt-and-suspenders sweep that complements the tmux pane-died hook installed at cs tackle time. --silence-detect, --livelock, and --event-age are the runtime-independent stall detectors: they read state from disk only, so they fire even when cosmon-runtime is dead (the watchdog's liveness is independent of the thing it watches). --event-age is the external-modal backstop — it keys on the age of any event-log append, so it catches a worker parked at a Claude Code AskUserQuestion modal that emits no cosmon-visible state. Alerts are tiered by irreversibility: only an irreversible-class block (signature/push/publish) fires cs notify.

Options:

• --respawn — Auto-respawn: restart dead workers by re-creating tmux sessions

• --no-tmux — Skip tmux liveness checks and respawn (state-only mode, for testing)

• --propel — Propel: detect running molecules with stale progress and nudge their workers via transport. The cognitive safety net that complements the new propulsion prompt — if a worker falls silent mid-molecule, patrol re-engages it. A worker whose terminal is still producing output is thinking, not idle, and is never nudged; a genuinely silent one is nudged with exponential backoff, at most 4 times, after which the molecule is tagged propel-exhausted for --heal. A worker that lost its briefing (orphaned by a crash / machine-sleep) cannot evolve, so it is never nudged at all: it is tagged propel-orphaned, the operator is paged via cs notify, and the brief must be re-delivered (cs tackle --force) or the molecule collapsed — closing the 2026-07-21 money-pump where a brief-less worker was nudged for six hours

• --propel-api-stall — Propel on a typed provider stall — the narrow channel. Consults each live worker's provider session journal and re-engages one only when its last assistant record carries the provider's own transport-failure flag (Claude's isApiErrorMessage), the molecule is still Running, and no human is piloting it. Distinct from --propel, whose trigger is the inference "this worker looks idle" — the trigger that had to be turned off on 2026-07-23 because a worker that is thinking is not a worker that is stuck. The flag is a fact the provider wrote down; a worker parked on it has no turn in flight to interrupt. Never keys on pane text or on the error sentence: a user record quoting that sentence verbatim carries no flag and is never propelled (the be1e SEV-1 use/mention trap). Keeps every --propel guardrail — exponential backoff to propel-exhausted, the propel-orphaned escalation, the ADR-137 §5 no-interference guard and the ~/.cosmon/health.off kill-switch. ~/.cosmon/stand-down.lock stops every cs patrol sweep, this one included

• --stale-after <STALE_AFTER> — Staleness threshold in seconds for --propel (default: 300). A molecule is a candidate if updated_at is older than this AND its worker's terminal has been silent at least as long. Also the first backoff window, doubling per nudge up to 30 min. --propel-api-stall reuses it for the terminal-silence bar and the backoff base, but never as a candidacy test: there, candidacy is the provider's typed flag

  Default value: 300

• --nudge — Nudge: per-step stall remediation. Like --propel, but classifies stalls from last_progress_at against the active step's timeout_minutes budget (M3, default 30 min) and guards idempotence — a worker won't be nudged twice within 60 s. Also covers the boot-stall class (task-20260718-ac03): a Running molecule with NO progress signal at all — the stuck bootstrap paste whose Enter was lost at spawn — is nudged once tackled more than [BOOT_STALL_GRACE] ago, the same grace used by cs health. The nudge text references briefing.md so the re-engaged worker re-reads its contract before continuing. Increments [cosmon_state::MoleculeData::nudge_count] (M5). This flag does not freeze or collapse molecules; those transitions require the separate --auto-freeze or --auto-collapse flag

• --expire — Expire sweep: scan molecules whose expires_at is in the past and apply their [ExpiryPolicy] (ADR-029). Idempotent — safe to run repeatedly on the same state. Warn tags the molecule with expired and emits a surface alert; Collapse transitions pending → collapsed with reason expired (TTL); Escalate tags escalated and emits the canonical Expired event for downstream transforms

• --auto-freeze — Transition orphaned molecules with a retained stopped worker to Frozen after the spawn grace. A purged worker leaves its Running molecule available for re-tackle. Without this flag, patrol reports orphans and leaves lifecycle state unchanged. --auto-collapse selects a terminal transition instead

• --auto-collapse — Aggressive orphan remediation: transition orphaned molecules with a retained stopped worker to Collapsed after the spawn grace. A purged worker leaves its Running molecule available for re-tackle. Use --auto-freeze for a recoverable transition

• --dead-worker-grace-secs <DEAD_WORKER_GRACE_SECS> — Minimum seconds after a tackle before patrol may call its worker dead or freeze/collapse its molecule. Covers spawn and forced re-tackle

  Default value: 120

• --harvest — Harvest sweep: scan every Completed molecule with merged_at = None and invoke cs harvest --molecule <id> on each one. Belt-and- suspenders safety net for cases where the tmux pane-died hook never armed (tmux server restart, brutal crash, molecule completed before the hook was installed, …). Idempotent: already-merged molecules are silent no-ops inside cs harvest

• --livelock — Livelock sweep: read .cosmon/state/presence/<sid>/blocked_on.json for every live session, build the session-wait graph, and report any non-trivial strongly connected component. Emits a temp:hot issue molecule tagged livelock-detected per cycle. Never auto-resolves (turing §6, §8b: propose, don't impose)

• --livelock-stale-after <LIVELOCK_STALE_AFTER> — Staleness threshold for --livelock, in seconds. blocked_on.json entries older than this are considered crashed-session residue rather than live waits and are excluded from the graph. Defaults to one hour — the cost of a false negative (missing a real lock) is lower than the cost of a false positive (nuisance issue)

  Default value: 3600

• --silence-detect — Silence-detect: scan running molecules for those whose worker has not emitted a WorkerHeartbeat in silence_after seconds. Tags temp:frozen, emits WorkerSilenceDetected, and fires cs notify ("absence of signal must itself be a signal"). Does not kill the worker

• --silence-after <SILENCE_AFTER> — Threshold in seconds for --silence-detect (default: 90). Roughly 3 × the recommended 30-second heartbeat cadence; raise it for fleets with longer steps or noisy networks

  Default value: 90

• --event-age — Event-age check: for every Running molecule, raise an ALERT-only signal when the most recent entry in the event log for that molecule is older than event_age_after seconds. Unlike --silence-detect (which keys specifically on WorkerHeartbeat), this keys on any event append, so it catches the external-modal case — a Claude Code AskUserQuestion modal that emits no cosmon-visible state at all. It never tags, never kills, never touches transport: it is a pure read over molecules + events.jsonl, so it works even when cosmon-runtime is dead (CV-5 — the watchdog's liveness must be independent of the thing it watches). Alerts are tiered by irreversibility (CV-6): only an irreversible-class block (signature / push / publish) fires cs notify; operational stalls are report-only, to keep the one load-bearing alert out of an alert-fatigue flood

• --event-age-after <EVENT_AGE_AFTER> — Threshold in seconds for --event-age (default: 900 = 15 min). The panel's suggested floor — long enough that a worker genuinely thinking between event appends is not mistaken for a stall

  Default value: 900

• --abandon — Abandon sweep (patrouille-abandon): fold traces an instance has ALREADY emitted (audit envelopes, phone-home reports, PKCE auth sessions, instance ledgers) into named abandonment motifs per tenant — nucleate-sans-tackle, pkce-start-sans-completed, incarne-sans-login, rafale-4xx-puis-silence, decroissance-de-signalement (the Dave rule, gravity HIGH: losing the client who talks loses the only human sensor). Read-only: reports, never remediates

• --abandon-root <ABANDON_ROOT> — Instance root for --abandon — the instance's .cosmon/ directory (containing whispers/inbox/ and state/). Defaults to the parent of the resolved state dir

• --abandon-quiet-hours <ABANDON_QUIET_HOURS> — Quiet window in hours for the "puis silence" motifs of --abandon (default 24 — one daily patrol cadence)

  Default value: 24

• --heal — Heal (the Deacon, ADR-137 §11 P3): run one detect → guard → remediate pass over the molecule-health anomaly catalog, mutating only the safe, reversible classes, each behind the §5 no-interference guard: A1 unsent-paste (delegate to the transport submit-retry), A4/A8 idle-after-complete / completed-unharvested (cs done harvest from the orchestrator — never a worker self-done), A5 idle-no-progress (nudge), A6 overloaded (backoff hold). The collapse / integrity classes (A3/A7/A9) are reported but never auto-collapsed here (that is P4). Detection is keyed off control-plane state only — never a pane glyph (the be1e SEV-1 lesson). Pair with --dry-run for a zero-mutation preview. Use cs health for the read-only, federation-wide catalog

• --dry-run — Dry-run: with --heal, compute and print the health report + the guarded actions the Deacon would take, but mutate nothing. The safe default for earning operator trust before enabling a scheduled heal pass

• --dialogue-scan — Capture each running worker's pane and classify any blocking dialogue sitting in it (tool-permission prompt vs. the Claude Code spend-/usage-limit dialog vs. a codex interactive dialog — update prompt, reasoning-level picker, rate-limit "switch model" menu; issue #85). The motivating incident: ten synthetic workers blocked on the spend-limit dialog with no human to press Enter. Per the be1e discipline (ADR-137 §2) pane text is read only to surface a finding — a money_stake class always pages the operator via cs notify and is never auto-confirmed; an unknown block or a login_required screen (expired session, login menu) alerts too; a safe permission prompt is auto-confirmed only when --auto-confirm-safe is also passed. A recognised codex dialog (read on codex panes only) is reported alongside its class (codex_dialog in --json) so the finding says why the worker is blocked, not only how severe. Runs on every patrol by default; the flag remains accepted for existing scheduled invocations. No keystroke is sent by default

  Default value: true

• --auto-confirm-safe — Opt in to firing the default-accept keystroke (Enter) on safe permission-class prompts only. Money stakes and unrecognised blocks are still never auto-confirmed — that refusal is encoded in the classifier, not in this flag. Off by default: the safe posture is to surface every block to a human

• --dialogue-lines <DIALOGUE_LINES> — Number of pane lines the dialogue scan captures per worker (default 40). The live prompt sits at the bottom of the pane, so a small tail is enough; raise it for TUIs that render tall dialogs

  Default value: 40

• --dialogue-blocked-after <DIALOGUE_BLOCKED_AFTER> — Blocked-duration threshold in seconds for the dialogue scan (default 900 = 15 min). A molecule whose progress has been frozen longer than this and is still sitting on a blocking dialogue escalates to a canary RED operator page — the heartbeat half of the primitive: "blocked > X min despite detection ⇒ RED"

  Default value: 900

cs fleet

Fleet template discovery and initialization

Usage: cs fleet <COMMAND>

EXAMPLES: cs fleet list-templates # installed templates cs fleet init research # scaffold a .fleet.toml from a template cs fleet resolve # flatten a composable fleet.toml (ADR-038) cs fleet resolve --json # NDJSON for scripting

SEE ALSO: cs deploy (instantiate a fleet from the .fleet.toml).

Subcommands:

• list-templates — List available fleet templates
• init — Initialize a fleet from a template (copies to .cosmon/fleet.toml)
• resolve — Resolve a fleet.toml (follow [[fleet.include]]) and print the flattened fleet

cs fleet list-templates

List available fleet templates

Usage: cs fleet list-templates

cs fleet init

Initialize a fleet from a template (copies to .cosmon/fleet.toml)

Usage: cs fleet init [OPTIONS] <TEMPLATE>

Arguments:

• <TEMPLATE> — Template name (from cs fleet list-templates)

Options:

• -o, --output <PATH> — Output path (default: .cosmon/fleet.toml)

cs fleet resolve

Resolve a fleet.toml (follow [[fleet.include]]) and print the flattened fleet

Usage: cs fleet resolve [PATH]

Arguments:

• <PATH> — Path to the master fleet.toml (default: .cosmon/fleet.toml via walk-up)

cs wait

Wait — block until a molecule reaches a terminal (or requested) status

Usage: cs wait [OPTIONS] <MOLECULE>

EXAMPLES: cs wait # block until terminal cs wait --timeout 600 # 10-minute cap cs wait --for completed # custom target set cs wait & # background wait, notified on exit cs whisper -f fix.md; cs wait # wait for the correction

This is kubectl-wait, not kubectl-watch. One molecule, bounded poll, exits on target. Never poll cs observe in a shell loop.

After a whisper to a molecule already in the target status, the wait also covers the worker's answer: it returns once feat/ has moved past the HEAD the whisper recorded and the pane is no longer working. A whisper answered without a commit ends on --timeout (exit 124).

SEE ALSO: cs observe (snapshot), cs peek (live fleet view).

Arguments:

• <MOLECULE> — Molecule ID to wait on. Must be an exact ID — we never want a prefix to match the wrong molecule under a long-running wait

Options:

• --for <FOR> — Statuses to wait for, comma-separated. Defaults to the terminal set so cs tackle M && cs wait M && cs done M just works

  Default value: completed,collapsed

• --timeout <TIMEOUT> — Maximum seconds to wait before giving up

  Default value: 600

• --poll-interval <POLL_INTERVAL> — Seconds between polls. Clamped internally to the remaining budget, so setting this larger than --timeout still terminates on time

  Default value: 5

• --quiet — Suppress per-poll progress lines — only emit the final result. Implied when --json is set

Execution commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs tackle

Tackle a molecule — claim before model selection and spawn ONE worker (for DAG walks use cs run)

Usage: cs tackle [OPTIONS] <MOLECULE>

EXAMPLES: cs tackle task-example-0001 # worktree + tmux + Claude (one node) cs tackle --dry-run # print the bootstrap prompt cs tackle --no-worktree # reuse current directory cs tackle --base release/2.0 # cut from — and merge back to — that trunk

--base makes the integration branch a property of the MOLECULE: the worker's branch is cut from it, the name is persisted in the molecule's state, and cs done merges back into it with no COSMON_BASE_BRANCH in the environment. Without --base, the branch is cut from the ambient HEAD and cs done falls back to COSMON_BASE_BRANCH → origin/HEAD → main, exactly as before.

cs tackle is ALWAYS leaf — it spawns one worker on the named node and never walks the DAG. To walk a DAG of N≥1 nodes (1 = leaf, N = full orchestration), use cs run instead. Human only. Workers never self-tackle. Pairs with cs done.

Dispatch claims are per molecule and precede model selection. If another tackle wins, this command exits non-zero and names its worker, adapter and selected model. An unpinned adapter default is reported as unrecorded.

The historical --leaf and --force-runtime flags are deprecated no-ops since the verb-unification: the routing decision is now the verb itself, not a flag on a polymorphic command.

SEE ALSO: cs run (DAG walk), cs done (teardown), cs wait (block on completion).

Arguments:

• <MOLECULE> — Molecule ID, prefix, or fuzzy name (e.g. "ADR-15", "idea-2026")

Options:

• --fleet <FLEET> — Fleet to use (default: molecule's fleet)

• --workdir <WORKDIR> — Working directory override (default: .worktrees/{mol-id})

• --base <BRANCH> — Integration base branch for this molecule (default: the ambient HEAD of the main checkout).

  The worker's feat/{mol-id} branch is cut from this ref instead of whatever the main checkout has checked out, and the branch name is persisted on the molecule so cs done merges back into it without any COSMON_BASE_BRANCH in the environment. Makes the base a property of the molecule rather than of the session that launched it.

• --no-worktree — Skip git worktree creation (use current directory)

• --dry-run — Skip tmux session — print the prompt to stdout instead

• --permission-mode <PERMISSION_MODE> — Permission mode for Claude (default: based on molecule kind)

• --force — Boolean flag: reclaim the molecule's live tmux session and respawn the worker. Also thaws a frozen molecule, returning it to running. A session left behind by a dead worker is reclaimed without this flag

• --resume — Continue the molecule's interrupted in-process (openai / anthropic) attempt from its last complete tool-result checkpoint instead of starting a fresh log. Use with --force to thaw a frozen molecule.

  Continuation reads the durable turn evidence on disk and nothing else. It is refused, with the reason, when the evidence does not prove it safe: a tool with no receipt (its effect is unknown and is never repeated), a request with no outcome (it may have been billed), a shell session whose state no record captures, no complete checkpoint, a changed formula, model, tool registry, briefing, worktree or loop ceiling, a spent wall-clock budget, or damaged evidence. Tool calls and turns already spent stay spent. Without this flag a dispatch starts a fresh attempt, as before.

• --name <NAME> — Override the tmux session name. ASCII alphanumerics and hyphens are kept; everything else is replaced with -. Max 50 chars. Default: {slug}-{shortid} derived from the molecule topic + id

• --bypass-seal — Override the ADR-085 stress-test seal at dispatch (Layer 1).

  Without this flag, cs tackle of a --class stress-test molecule refuses dispatch unless prior.md + prior.b3 exist on disk and a matching cs witness attest event has been emitted. With it, the runtime writes a typed BypassReceipt to <molecule_dir>/bypass-receipt.json and emits EventV2::SealBypassed, then proceeds with dispatch. Requires --bypass-reason "<…>" — silent overrides are forbidden by ADR-085 §3.5.

• --bypass-reason <TEXT> — One-line reason recorded in the BypassReceipt when --bypass-seal is used.

  Free-text but non-empty; the runtime refuses a blank reason because the entire point of the receipt is to surface accountability for the override (ADR-085 §3.5).

• --adapter <NAME> — Worker-Spawn Port Adapter to dispatch (ADR-097 / C6; ADR-108 Q5a chain).

  Resolution order (highest priority first): this flag → durable molecule pin stamped by cs nucleate --adapter → formula-step adapter = "<name>" pin → $COSMON_DEFAULT_ADAPTER env var → per-galaxy .cosmon/config.toml::[adapters] default = "…" → global ~/.config/cosmon/config.toml::[adapters] default = "…" → built-in "local" (the Ollama-backed in-process loop). Values are looked up against the registered Adapter table (claude, aider, openai, anthropic, llama-cpp, local, …). An unknown name aborts the dispatch with a typed AdapterNotFound carrying the list of available names — no silent fallback. To restore the legacy Claude-Code default pass --adapter claude, export COSMON_DEFAULT_ADAPTER=claude, or set [adapters] then default = "claude" in either config file.

  Capability gate (noogram/cosmon #4)

  A formula may declare what its steps need of a worker (requires_capabilities = ["shell", "vcs"]). A local adapter (local / ollama / llama-cpp / llama) is an in-process chat loop with no shell, no VCS and no cs command, so such a pairing is refused with exit code 17 — before any worktree, pane or model preflight, and under --dry-run too. The molecule stays pending and re-tacklable. Re-run with a coding-agent adapter, or set COSMON_SKIP_CAPABILITY_GATE=1 to dispatch anyway. Formulas that declare nothing are unaffected on every adapter.

  Every invocation (with or without the flag) emits an EventV2::AdapterSelected envelope so the cat-test (jq -c 'select(.type == "adapter_selected")') can answer "which Adapter ran for this molecule?" without parsing shell history.

  Composition with cs run --resident (issue-#21, reconciled)

  The resident loop (cs run --resident) is not a second resolver; it is a composer that delegates to this one chain. Its scheduler owns only the two dispatch intents — a per-molecule pin and the opt-in cs run --adapter <name> run directive — and stamps them onto the shelled cs tackle. When neither is present it stamps no --adapter flag, so the remaining six-level chain runs unchanged in the child: formula step → $COSMON_DEFAULT_ADAPTER → per-galaxy config → global config → the local floor. The floor is therefore reached under --resident iff it is reached under a bare cs tackle, and the operator's env and committed config are honoured identically on both paths — the #21 fix removed the resident-only --adapter local stamp that used to mask them. See cs run --help (--adapter) and cosmon_runtime::resident.

• --model <MODEL_ID> — Per-molecule model pin — the model sibling of --adapter (see ADR-097).

  Resolution order (highest priority first): this flag → molecule cosmon_model variable set at nucleation → formula-step model = "<id>" pin → $COSMON_DEFAULT_MODEL (else the legacy $ANTHROPIC_MODEL) env var → per-galaxy .cosmon/config.toml::[adapters.<name>].default_model → global ~/.config/cosmon/config.toml::[adapters.<name>].default_model → floor None (cosmon pins no model; the adapter's own default applies — byte-identical to today's no-pin behaviour).

  Strong is never inherited. Every dispatch resolves the model fresh; a strong (frontier) model is reachable only from this flag, a child pin, or a formula-step pin — a positive per-molecule act — never from a config/env default that could silently make an entire fleet expensive (the /model-hack leak this axis exists to close).

  The id is carried opaquely: cosmon keeps no model allowlist. When both the resolved adapter and model identify different named provider families, however, the pair is refused before spawn because the stock adapter cannot run it. Self-hosted endpoints and unrecognised model ids remain opaque and pass through. Config default_model rows are scoped per adapter because a model id only has meaning inside its adapter.

• --role-hint <ROLE> — Forensic-only role-of-origin hint propagated through to EventV2::AdapterSelected (ADR-097 / C6).

  Cosmon does not interpret this value — it is the academy-shim's channel for preserving the driver's vocabulary (a --role researcher invocation on the driver side becomes role_hint: "researcher" on the cosmon event), so the role of origin survives the seam between driver (roles) and cosmon (adapters). Optional; absent for direct operator invocations.

• --reclaim-derived — Reclaim derived build output from other worktrees before spawning (issue 61, ADR-178).

  The pre-spawn pressure check. A dispatch is the one moment cosmon is guaranteed to be running and the moment disk demand grows — a new worktree and a new build directory — so it is where the actor that creates the leak pays for it. Nothing runs it on a timer: there is no daemon, no LRU and no background sweep, because nothing destructive may run unobserved.

  It governs tier 1 only: rebuildable payload under the [worktree_reclaim].evict roots of worktrees whose molecule is terminal (or absent) and whose build lock it could acquire. It cannot reach durable content — cs tackle never consults durable eligibility, and no path in this workspace removes a worktree.

• --fallback-from-local <CAUSE> — Loud opt-in fallback from the local default to a remote oracle after a decidable local hard-failure (Q5b).

  Pass a LocalFailureCause token — crash, oom, timeout, connection-refused, or any bespoke string (recorded verbatim as Other). This flag is the ONLY path from a local hard-failure to a remote oracle: there is no automatic in-loop fallback. It is meaningful only alongside a remote --adapter (claude / openai / anthropic / aider) — combining it with a local adapter is a contradiction and aborts the dispatch.

  When set, cs tackle mints an EventV2::LocalFallback line in the same atom as the RemoteEgressOptIn egress grant, so a remote call carrying a fallback cause can never reach the wire without a matching loud audit record — silent fallback is impossible by construction. Soft "the output looked bad" judgement is NOT a valid cause: that is undecidable (Rice) and belongs to acceptance tests, not this routing flag.

• --by <ACTOR> — Actor class recording who dispatched this molecule — the anti-preemption lease.

  Accepts human (the default when the flag is absent — a direct operator invocation) or runtime:<pid> (the resident runtime cs run passes its own process id). The value is stamped onto the molecule's tackled_by field when the molecule flips to Running, so the walker can preserve a prior human claim: a human-claimed molecule is never raffled by the runtime, even if it briefly returns to Pending on a revision. This is cs tackle's only role in the lease — recording the claim; honouring it is the walker's job.

  Default value: human

• --harness <KEY=VALUE> — Per-dispatch harness setting — key=value, repeatable (ADR-177 / issue #65).

  --model pins which model runs; this pins how it runs, by handing the pair to the adapter's own override channel:

  • codex → one -c key=value per entry, e.g. --harness model_reasoning_effort=high. To pin the service tier for this dispatch, use --harness service_tier=default for Standard processing (Fast off), or --harness service_tier=priority for Fast processing. fast is also accepted as the Fast spelling; Fast availability depends on the selected model and account; - claude → --<key> <value> per entry, e.g. --harness effort=xhigh; - any other adapter → the dispatch fails at launch, naming the adapter. A setting is never silently dropped.

  cosmon recognises no keys

  The pair is carried verbatim to the harness and logged verbatim as sent. cosmon never normalises a key, rewrites a value, or keeps an allowlist — an unknown key fails in the harness's own parser, at launch, loudly, which is where knowledge about that harness's keys lives and stays current. A key cosmon recognised would become public API carried in files on other people's disks, with no mechanism by which its removal could be announced.

  Precedence, merged per key

  This flag → the executing step's [steps.harness] table → the harness's own config. Merged key by key, never wholesale: overriding one key leaves every other key the step pinned exactly where it was. Rank 3 is not a cosmon surface — cosmon passing no key is the only way the harness's own default can apply.

  What the audit trail claims, and what it does not

  Each resolved key lands on events.jsonl as a harness_setting_selected line carrying its source, the realized argv fragment, the channel, the harness version and the launch status. That receipt is ex-ante: it records what cosmon dispatched, minted before the process exists. Paired with the harness's own echo, the strongest true sentence is "cosmon requested E through channel C; the harness's own log reported E" — a two-party agreement, not a proof of behaviour. Nothing here supports "the step ran at E".

cs done

Done — terminal teardown for a molecule (merge + cleanup, human-callable)

A failed merge reports the merge error and any dirty checkout paths. [project] merge_subject may set the merge commit subject per galaxy; its template must include {mol_id}. Unset, the subject is unchanged. Tracked harvest state, including archive and event files, is committed before the next sibling merge; ignored molecule directories are skipped.

Usage: cs done [OPTIONS] <MOLECULE>

EXAMPLES: cs done task-example-0001 # merge + teardown cs done --strategy ff-only # linear history; attribution off cs done --force # skip completion check cs done --if-completed # silent no-op if not Completed

Not-the-worker. Legitimate callers: humans, external schedulers (cron/launchd), and transport watchdogs (tmux pane-died hooks via cs done --if-completed). Required to close the nucleate → tackle → wait → done cycle: without it the branch never merges and the tmux worktree persists.

--if-completed is the hook-friendly gate: exits success without touching state when the molecule is not Completed or already merged; behaves identically to plain cs done otherwise. Supersedes the former cs harvest verb (ADR-052 §D3).

BASE BRANCH — the branch this merge lands on is resolved once per run, in this order (first that answers wins):

1. the molecule's own base, stamped by cs tackle --base <branch>
2. the COSMON_BASE_BRANCH environment variable
3. git symbolic-ref refs/remotes/origin/HEAD
4. the literal main

Rung 1 is why a cs done fired from a tmux hook — whose environment froze when the tmux server started and never saw a later export — still merges onto the right trunk. Molecules tackled without --base resolve through rungs 2-4 exactly as they always did. cs done still refuses (NotOnBase) when HEAD is not the resolved base: git merges into the current HEAD, never into a branch by name.

SEE ALSO: cs complete (state transition only), cs tackle (counterpart).

Arguments:

• <MOLECULE> — Molecule ID to tear down

Options:

• --reason <REASON> — Why this molecule is being closed. Traced trunk-side on the molecule.

  Optional here and mandatory over the wire (POST /v1/molecules/{id}/done), and the asymmetry is deliberate. An operator standing at their own terminal is the author of the git history this harvest writes; a requester reaching the door over §8p is not, and the trunk-side reason is the only account a later reader has of why someone else's molecule was closed. Making it mandatory here too would break every hook, patrol sweep and cs run teardown that legitimately closes a molecule without a sentence to add — a usability amputation with no safety property behind it.

  What is not optional anywhere is honesty: when no reason is given, none is recorded. The withdrawn land gesture fabricated a generic one, and a fabricated reason is indistinguishable, a year later, from one somebody meant.

• --force — Proceed even if the molecule is not in a terminal state

• --if-completed — Silent no-op when the molecule is not Completed or already merged.

  Hook-friendly gate for callers that do not know whether the molecule is ready for teardown — tmux pane-died hooks, patrol sweeps, and the legacy cs harvest alias. Exits success without touching state when the precondition is not met; otherwise, behaves exactly like cs done. Supersedes the stand-alone cs harvest verb (ADR-052).

• --dry-run — Compute and display the teardown plan without executing any steps.

  Reports what cs done would do: worktree state (clean/dirty), whether a merge is needed, whether the tmux session is alive, whether a fleet worker is registered, and whether the branch exists.

• --no-merge — Skip merging the worker's branch into the base branch

• --review-shell — Review a merge's changed shell surface and grant trust over the merged files before the post-merge gate. Requires an explicit operator reply; declining rolls the merge back and preserves the branch

• --no-worktree-remove — Skip removing the git worktree

• --no-branch-delete — Skip deleting the worker's branch after merge

• --no-kill — Skip killing the tmux session

• --strategy <STRATEGY> — Merge strategy for the worker's branch.

  merge (default) creates a merge commit (git merge --no-ff) so parallel workers can land independently even when main has moved. ff-only preserves a strictly linear history and refuses anything that is not a fast-forward; it is refused when native attribution is configured because a fast-forward creates no trailer carrier.

  Default value: merge

  Possible values:

  • merge: Non-fast-forward merge (git merge --no-ff --no-edit)
  • ff-only: Fast-forward-only merge (git merge --ff-only)

• --no-auto-propel — Disable auto-propel escalation on merge conflict.

  By default, when a merge conflict is detected, cs done escalates by sending a resume signal to the worker with rebase instructions, then retries the merge after a backoff delay. This flag restores the old behavior: abort immediately and print a manual-resolution message.

  Mechanical-first escalation: see docs/architectural-invariants.md

• --propel-message <PROPEL_MESSAGE> — Custom message sent to the worker during auto-propel escalation.

  The default instructs the worker to rebase onto the base branch, resolve conflicts, run tests, and NOT call cs done itself.

• --max-retries <MAX_RETRIES> — Maximum number of auto-propel escalation retries before giving up

  Default value: 3

• --skip-pre-done-hook — Skip the blocking [hooks] pre_done gate for this invocation.

  The pre_done hook (when configured) runs before the merge and aborts teardown on a non-zero exit — the galaxy-owned Definition-of- Done gate. This flag is the human operator's kill-switch: it bypasses the gate entirely for a deliverable the operator knows is good but the script cannot see (e.g. evidence living outside the repo). Equivalent to setting the COSMON_SKIP_PRE_DONE_HOOK environment variable. No effect when no pre_done hook is configured.

• --deploy-off-trunk — Run the [hooks] post_merge deploy hook even when this harvest merges into a parked work branch rather than the reference trunk.

  By default the post_merge hook is bounded to the trunk: it fires only when the resolved integration base is the galaxy's reference trunk (origin/HEAD, or main as a last resort). The hook deploys — the canonical just install refreshes the on-disk cs binary — so running it after a merge into an older parked branch would silently rejuvenate the operator's tool, dropping whatever the parked branch predates (task-20260725-b64f). When the merge targets a parked branch the hook is skipped with a warning naming the reason.

  This flag is the operator's explicit escape hatch for the rare-but- legitimate case of deploying from a parked branch on purpose. No effect when no post_merge hook is configured or when the merge already targets the trunk.

• --allow-protected-change — Merge even though the worker branch changed a path the molecule declared protected (cs nucleate --protect, issue #94).

  Without it, cs done refuses such a branch (protected_path_modified, exit 78) and names each protected path it changed. Protected paths are reference inputs; a branch that rewrites them can make any result "match". Pass this flag only when you, the operator, have read the change and it is intended — for example a reference dataset that was itself wrong. No effect on a molecule that declared no protected path.

cs sync

Sync — base-sync the current worktree from main, stamping a Base-Sync trailer

Usage: cs sync [OPTIONS]

Options:

• --base <BASE> — Base branch to sync from (defaults to main)

  Default value: main

• --dry-run — Report what would happen without performing the merge

cs harvest

Harvest — close a completed-but-unmerged molecule by invoking cs done

Usage: cs harvest [OPTIONS] --molecule <MOLECULE>

EXAMPLES: cs harvest --molecule task-example-0001 # DEPRECATED — see below

DEPRECATED (ADR-052 §D3): use cs done --if-completed <mol> instead. The canonical path carries byte-identical semantics: silent no-op when the molecule is not Completed or already merged; full teardown otherwise. This alias will be removed after one release cycle.

SEE ALSO: cs done --if-completed (canonical), cs patrol --harvest (belt-and-suspenders sweep).

Options:

• --molecule <MOLECULE> — Molecule to harvest. Required — cs harvest operates on one molecule per invocation. Use cs patrol --harvest for the sweep variant

• --dry-run — Print what cs harvest would do without exec'ing cs done

• --from-pane-died — Flag the invocation as caused by a tmux pane-died hook.

  ADR-052 child #4 (I4 + I8 + I10): the probe must emit its observation before acting on it. When set, cs harvest first appends a EventV2::WorkerExited event to events.jsonl (reason = pane_died) and then runs the normal harvest logic. Absent this flag, no WorkerExited is emitted — periodic cs patrol --harvest sweeps observe via witness, not via the kernel-level pane-died channel.

• --exit-code <EXIT_CODE> — Exit code reported by tmux #{pane_dead_status} when the pane died.

  Only meaningful together with --from-pane-died. Accepts any signed 32-bit integer so the wait-status (which may encode signals) survives round-trip. Strings that fail to parse are treated as "no information" (None in the emitted event).

cs run

Run — walk a molecule DAG of N≥1 nodes via the resident runtime (ADR-016 Layer B)

Usage: cs run [OPTIONS] [MOLECULE]

EXAMPLES: tmux new -d -s runtime cs run --poll-interval 5 cs run # also valid: 1-node DAG = single dispatch cs run --force-runtime # bypass the ADR-048 backlog-sanity guard

Resident runtime — walks a DAG of N≥1 nodes. Calls cs tackle for each ready node and cs done automatically as predecessors complete. The single-node case (1 = leaf) is the same code path as the N-node case; cs tackle <id> is the no-walk equivalent if the operator wants exactly one worker without any runtime ceremony.

NEVER run cs run in the foreground; always detach via tmux so the pilot stays responsive.

SEE ALSO: cs tackle (single node, no runtime), docs/handbook.md#one-primitive.

Arguments:

• <MOLECULE> — Root molecule ID (supports prefix matching like other commands).

  Required for the legacy DAG-policy mode. With --resident the loop walks the whole ensemble, so this argument is optional (any value, including _, is accepted and ignored).

  Default value: ``

Options:

• --policy <POLICY> — Scheduling policy to use

  Default value: dag

  Possible values: dag, noop

• --timeout <TIMEOUT> — Maximum seconds before the runtime exits. 0 means no timeout (default)

  Default value: 0

• --poll-interval <POLL_INTERVAL> — Seconds between runtime ticks. Lower values are more responsive but increase store I/O

  Default value: 1

• --no-teardown — Skip automatic teardown of completed molecules after the run.

  Teardown runs cs done on every molecule that reached Completed — and only those. A Collapsed molecule is explicitly-abandoned work: it is terminal, but cs done also merges the molecule's branch onto the trunk, so a collapsed branch must never be handed to it. A teardown that fails exits with the NAMED code 93 (teardown_failed): the branch is unmerged and the worktree / session is still standing, which a detached caller cannot learn any other way.

• --sweep-every <SWEEP_EVERY> — ADR-038 Limit 1: re-walk the store every N ticks to absorb descendants nucleated dynamically by workers (mission-controller decompose, deep-think step 4, etc.) that are not reachable from the runtime's root via pre-existing typed links. Zero disables the sweep (default) — the scope is frozen at compile-plan time, which is the pre-2026-04-14 behavior

  Default value: 0

• --force-runtime — Override the ADR-048 backlog-sanity guard on runtime bootstrap.

  When a dirty backlog would normally refuse runtime bootstrap (sediment ≥ threshold, default 5), --force-runtime bypasses the refusal and writes a runtime_guard_override audit event to events.jsonl so the override leaves a durable trail.

• --max-actions <MAX_ACTIONS> — B3 — decreasing action budget (moussage bounds). Each applied runtime action costs one unit; when the budget floor is reached the loop exits with the NAMED reason budget_exhausted (exit code 90) instead of dispatching further. This is the well-founded measure that makes an unbounded moussage total. 0 = unbounded (default, operator-local behaviour unchanged). Server-side callers (the tenant drain path) pass the binding-derived value — the bound is never client-writable

  Default value: 0

• --max-depth <MAX_DEPTH> — B1 — maximum DAG depth (longest dependency chain, in molecules). Checked at compile-plan time, BEFORE the loop starts: a plan deeper than the bound is refused with the NAMED error max_depth_exceeded (exit code 92), never started. 0 = unbounded (default)

  Default value: 0

• --max-molecules <MAX_MOLECULES> — B2 — maximum molecules tolerated in the fleet while draining. Checked at compile-plan time AND on every loop tick (so mid-run nucleations count); exceeding it exits with the NAMED reason molecule_quota_exceeded (exit code 91). 0 = unbounded (default)

  Default value: 0

• --resident — ADR-095 — switch to the fully event-sourced Resident Runtime loop.

  When set, the legacy in-process DagPolicy is bypassed and the new [cosmon_runtime::RuntimeLoop] takes over. The loop:

  • Shells out to cs ensemble --json, cs tackle, cs done exactly as a human operator would (RR-1). - Wakes on FS changes under .cosmon/state/ (notify backend) plus a --poll-interval heartbeat. - Writes an NDJSON trace line per loop iteration to .cosmon/state/runtime-trace.jsonl (RR-5). - Exits cleanly on SIGTERM / Ctrl-C. - Drains when the ensemble has no pending and no running.

  Config-honoring dispatch (ADR-016 delib-20260531-c761, refined by issue #91). The loop seals .cosmon/config.toml (+ the global ~/.config/cosmon/config.toml) at launch and re-checks it before every dispatch. An on-disk edit is then one of:

  • Reloaded (no halt) — no running molecule's effective adapter settings changed. This includes edits outside [adapters], edits to an adapter no running worker uses, and edits while none is running. The loop adopts the fresh config for its next dispatch and records a config-reloaded trace line and summary count. - Halted fail-closed — a running molecule's effective adapter settings changed, or its adapter cannot be identified. The loop refuses to form its next dispatch, emits EventV2::ConfigDriftDetected, and exits non-zero (EX_TEMPFAIL, 75) so a supervisor relaunches a fresh process that re-derives everything from disk — it never merges the new config into a live process.

  The cs binary image itself is never sealed (a cs done merge reinstalls it on every successful drain by design).

  Does not require <molecule> — the loop walks the whole ensemble. The positional argument is accepted but ignored in resident mode; pass _ if you have nothing to name.

• --affinity — ADR-145 — model-affinity ordering of the ready frontier.

  On a single-resident-model local oracle (ollama-g5: 48 GB ≈ one 120 B model in VRAM), an alternating frontier reloads the model (~40 GB off disk) on every dispatch. With --affinity the runtime clusters same-model molecules contiguously and drains the resident model first, so a same-model batch pays the load cost once. The per-molecule model is PRE-RESOLVED from its cosmon_model variable, then its formula-step model = pin, since a pending frontier molecule has no ModelSelected event yet.

  Off by default: cloud dispatch (many models, no resident constraint) keeps pure critical-path order. The reorder is a permutation — the DAG semantics and the set of dispatched molecules are unchanged; only the order within a ready batch differs. Legacy DAG-policy mode only (not --resident).

• --resident-model <RESIDENT_MODEL> — Model already warm in the oracle's VRAM at runtime start, so the affinity reorder drains its bucket first with no reload. Only read when --affinity is set; a cold start (unset) simply pays one extra load for the first bucket

• --adapter <NAME> — Opt-in run-wide adapter directive (resident mode only).

  The resident scheduler owns exactly one run-wide flag intent — this flag — and nothing below it (COSMON-DEV #21). Passing --adapter <name> is the operator's explicit, conscious choice to spend on that adapter for this run: it stamps every pin-less molecule dispatched — both static frontier nodes and children a worker nucleates dynamically mid-run (the converge/committee loop). A per-molecule pin still wins over it.

  When this flag is absent, the scheduler stamps nothing: the shelled cs tackle inherits the environment and runs the full canonical resolution chain itself (formula step → $COSMON_DEFAULT_ADAPTER → per-galaxy config → global config → the built-in local floor). So the operator's live env, session hammer, and committed config are all honoured under --resident exactly as they are under a bare cs tackle — the resident loop no longer masks them with a rung-1 --adapter local floor (the #21 defect). The local floor is still reached iff nothing higher speaks, so an inadvertent paid dispatch remains impossible: a paid adapter is chosen only by a conscious flag, formula step, env export, or committed config. See docs/adr (ADR-095) and the cs tackle adapter-chain docs for the single canonical resolution order.

• --base <BRANCH> — Opt-in run-wide integration base (resident mode only).

  The base twin of --adapter, with the same two-rung precedence: every pin-less molecule this run dispatches — one with no persisted base — is tackled with --base <BRANCH>, which persists the base on the molecule so its cs done merges into <BRANCH> rather than the ambient HEAD. A molecule that already carries a base (cs nucleate --base, an earlier cs tackle --base) keeps it: the per-molecule base wins.

  This is how a germinated polymer (cs spore run, cs nucleate --from) is aimed at an integration branch without tackling each node by hand. The branch must exist locally; a dangling base is refused before the loop starts.

• --harness <KEY=VALUE> — Opt-in run-wide harness-settings directive (resident mode only, repeatable — ADR-177 / issue #86).

  The harness twin of --adapter, but occupying rung 1 of the harness chain rather than the adapter chain: cs tackle --harness k=v's rung, applied run-wide. Unlike --adapter and --base there is no per-molecule pin to defer to — [steps.harness] lives on the executing formula step, not the molecule — so this directive is stamped onto every dispatch the run makes (static frontier nodes and dynamically-nucleated children alike) as one --harness k=v per key, and merged per key with the step's own [steps.harness] table by the shelled cs tackle, the operator's flag winning (ADR-177 Decision 2). Grammar and semantics are exactly cs tackle --harness's: key=value, cosmon recognises no keys and carries the pair verbatim to the adapter's native override channel. Absent (the default), no --harness flag reaches any dispatch and each step's own [steps.harness] pin, if any, is unmasked.

cs spore

Spore germinates a whole polymer from a shareable spore.toml template (validate / run / export, ADR-140)

Usage: cs spore <COMMAND>

EXAMPLES: cs spore install github:noogram/cosmon/spores/cosmon-dev # fetch + place cs spore validate ./spore.toml --var subject="octopus cognition" cs spore run ./bundle/ --var subject="..." --var axes=a,b,c cs spore run ./spore.toml --allow-unchecked-seal # sealed, no TLC cs spore export ./spore.toml --out dist/ # bundle hash + ASTRA cs spore validate ./spore.toml --json # NDJSON expansion

VERBS: install fetch a shareable bundle and place it in this project, copying its recipes into .cosmon/formulas/ so their pins reach dispatch. validate parse + expand as a dry run; prints the ordered nucleate call list, germinates nothing. run parse + expand + seal gate, then germinate the polymer into the live state store. --json emits one NDJSON line per molecule. export content-addressed bundle hash + ASTRA descriptive layer (D6).

SEAL (ADR-140 D4): a sealed spore fails closed unless --allow-unchecked-seal is passed; the status line never claims 'verified' when TLC did not run.

SEE ALSO: cs nucleate (one molecule), ADR-140, docs/design/spore-impl-dag-manifest.md.

Subcommands:

• validate — Parse + expand a spore as a dry run; print the ordered nucleate call list without germinating anything
• run — Germinate the polymer: parse + expand + seal gate, then replay the call list against the live state store
• export — Emit a content-addressed bundle id and an ASTRA descriptive layer (ADR-140 D6) for sharing the spore
• install — Fetch a shareable bundle and place it into this project, installing its recipes into .cosmon/formulas/ so their per-step pins reach dispatch

cs spore validate

Parse + expand a spore as a dry run; print the ordered nucleate call list without germinating anything

Usage: cs spore validate [OPTIONS] <REF>

EXAMPLES: cs spore validate ./spore.toml --var subject="octopus cognition" cs spore validate ./bundle/ --var axes=a,b,c # directory ref cs spore validate ./spore.toml --json # NDJSON expansion

Dry run only: parse (N2) + expand (N3), print the ordered 'cs nucleate ... --blocked-by ...' call list, germinate nothing. The seal is reported but never gated here; use it to inspect what 'cs spore run' would create. Each --var is coerced into its declared ParamSchema type before expansion; a list param splits on commas.

SEE ALSO: cs spore run, cs spore export, ADR-140 D3.

Arguments:

• <REF> — Path to a spore.toml manifest (or a directory containing one)

Options:

• --var <KEY=VALUE> — Bind a parameter (repeatable: --var key=value). Values are coerced into the declared ParamSchema type before expansion
• --admission <FILE> — TOML admission evidence for a spore that declares [spore.admission]

cs spore run

Germinate the polymer: parse + expand + seal gate, then replay the call list against the live state store

Usage: cs spore run [OPTIONS] <REF>

EXAMPLES: cs spore run ./spore.toml --var subject="..." --var axes=a,b,c cs spore run ./bundle/ --fleet default # directory ref cs spore run ./spore.toml --allow-unchecked-seal # sealed, no TLC cs spore run ./spore.toml --json # one NDJSON line/molecule

Germinates the whole polymer: parse + expand + seal gate, then replays the call list against the live state store via the canonical 'cs nucleate' path. Every germinated molecule is tagged temp:warm and wired to its blocked-by predecessors. The seal status note goes to stderr so --json stdout stays clean NDJSON.

SEAL (ADR-140 D4): a spore with no [spore.seal] germinates freely. A sealed spore fails closed unless --allow-unchecked-seal is passed, in which case the status line reads 'seal: present, NOT verified' and never 'verified'.

SEE ALSO: cs spore validate (dry run), cs run (DAG of existing molecules).

Arguments:

• <REF> — Path to a spore.toml manifest (or a directory containing one)

Options:

• --var <KEY=VALUE> — Bind a parameter (repeatable: --var key=value)

• --admission <FILE> — TOML admission evidence, checked before any molecule is nucleated

• --allow-unchecked-seal — Germinate a sealed spore even though its .tla proof was not verified this run (TLC unavailable). The status line stays honest: seal: present, NOT verified (ADR-140 D4). Without this flag a sealed spore fails closed

• --fleet <FLEET> — Fleet to germinate the polymer into

  Default value: default

• --store-dir <DIR> — State store root (default: walk-up .cosmon)

cs spore export

Emit a content-addressed bundle id and an ASTRA descriptive layer (ADR-140 D6) for sharing the spore

Usage: cs spore export [OPTIONS] <REF>

EXAMPLES: cs spore export ./spore.toml # bundle hash to stdout cs spore export ./spore.toml --out dist/ # ASTRA into dist/ cs spore export ./bundle/ --json # machine-readable

Emits a content-addressed bundle id over the manifest and every recipe and seal file it references (BLAKE3, sorted paths), plus an ASTRA-compatible RO-Crate descriptive layer (ADR-140 D6) when [spore.astra].emit is true. The seal verdict is attached honestly: marked present/absent and never claimed verified. The bundle hash is stable: the same bundle content always yields the same id (content-addressing is the registry, ADR-039).

SEE ALSO: cs spore run, ADR-140 D6, ADR-039.

Arguments:

• <REF> — Path to a spore.toml manifest (or a directory containing one)

Options:

• --out <DIR> — Output directory for the ASTRA descriptive layer. Defaults to the manifest directory. The crate is always written here as ro-crate-metadata.json unless [spore.astra].output names a different (manifest-relative) path

cs spore install

Fetch a shareable bundle and place it into this project, installing its recipes into .cosmon/formulas/ so their per-step pins reach dispatch

Usage: cs spore install [OPTIONS] <SOURCE>

EXAMPLES: cs spore install github:noogram/cosmon/spores/cosmon-dev cs spore install https://github.com/noogram/cosmon/tree/main/spores/cosmon-dev cs spore install ../shared/bundle --dest spores/shared # local copy cs spore install github:o/r@v1 --expect-hash blake3:... # verified fetch cs spore install github:o/r --dry-run --json # plan only

Fetches the bundle (git remote or local path), places it under /spores// unless --dest says otherwise, and copies each [spore.formulas.*] recipe into .cosmon/formulas/ under the name the recipe DECLARES — which is the name 'cs tackle' resolves at dispatch. That second half is why the verb is called install and not add: without it a bundle germinates fine and then runs with every per-step adapter/model pin silently inert (task-20260725-eb3b).

SOURCE: a local path, 'github:owner/repo[/subdir][@ref]', a GitHub tree/blob URL, or any other git remote (use --git-ref / --subdir to pin one).

REFUSALS, all before anything is written: a bundle whose hash does not match --expect-hash; a bundle missing a file its manifest declares; a symlink inside the fetched tree; a non-empty destination (without --force); and a registry that already holds a DIFFERENT recipe of the same name (without --force), since overwriting changes what already-germinated molecules run. An identical recipe is a no-op, so re-installing is idempotent.

SEE ALSO: cs spore validate (inspect what was installed), cs spore export (the id --expect-hash checks), docs/cs-spore.md.

Arguments:

• <SOURCE> — Where the bundle comes from: a local path, github:owner/repo[/dir][@ref], a GitHub tree/blob URL, or any other git remote

Options:

• --dest <DIR> — Where to place the bundle. Defaults to <project>/spores/<spore-name>/
• --git-ref <REF> — Branch, tag, or commit to fetch. Overrides a ref encoded in the source
• --subdir <PATH> — Path to the bundle inside the checkout. Overrides one encoded in the source; the way to install from a subdirectory of a non-GitHub remote
• --expect-hash <BLAKE3> — Refuse unless the fetched bundle hashes to exactly this id (as printed by cs spore export). Checked before anything is written
• --no-formulas — Place the bundle but do not copy its recipes into .cosmon/formulas/. The bundle then germinates without its per-step adapter/model pins
• --force — Overwrite a non-empty destination and replace conflicting recipes already in the registry. The copy is a merge: a file the new bundle carries replaces the one there, and a file it does not carry is left alone — nothing is deleted on your behalf
• --dry-run — Report what would be installed and write nothing
• --formulas-dir <DIR> — Formula registry to install recipes into (default: walk-up .cosmon/formulas)

Project commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs init

Bootstrap a project-local .cosmon/ directory (creates the target dir if missing)

Usage: cs init [OPTIONS] [PATH]

EXAMPLES: cs init # bootstrap .cosmon/ in the current directory cs init ./new-galaxy # create ./new-galaxy/, then populate .cosmon/ cs init --soft # generate only CLAUDE.md (no .cosmon/) cs init --soft --template rust # Rust-specific conventions cs init --soft --template data # data/research conventions cs init --upgrade # backfill missing canonical formulas

Creates .cosmon/{config.toml, state/, formulas/, …}. The target path may not exist — cs init runs mkdir -p before populating. Running twice on the same path is a strict no-op.

Does NOT run git init (that is git's job) and does NOT write CLAUDE.md by default — pass --soft to generate an agent template. Refuses to nest: if an ancestor already carries .cosmon/, exits non-zero — no --force.

On a terminal, the first cs init of your life also asks the one-time developer-share question (deny-by-default, cs opt-in-share --status to review). Never asked under --json, never asked when stdout is captured.

Symmetric undo: removing the .cosmon/ directory it created deletes every artifact cs init wrote.

Arguments:

• <PATH> — Directory to initialize (default: current directory).

  Need not exist. If it does not, cs init creates it with mkdir -p. If it exists and already contains .cosmon/, the command is a no-op (strict idempotency).

  Default value: .

Options:

• --upgrade — Upgrade an existing .cosmon/ project by backfilling missing canonical formulas AND project_id without overwriting existing files

• --soft — Generate only a minimal CLAUDE.md (≤50 lines) without creating .cosmon/.

  Constitutional projection: conventions propagated via a single file that any agent can read independently. No orchestration infrastructure, no runtime state, no external dependency.

• --template <TEMPLATE> — Project-type template for --soft (default: generic)

  Default value: generic

  Possible values:

  • generic: Generic project — language-agnostic conventions
  • rust: Rust project — cargo-based conventions
  • data: Data/research project — notebook + pipeline conventions

• -y, --yes — Assume "yes" to any confirmation prompt (non-interactive mode).

  cs init is already fully non-interactive today, so this flag is accepted and ignored. It is reserved so that README quickstarts (cs init --yes) stay paste-testable if prompts are ever added — per the knuth paste-testability invariant and tolnay's semver rule that reserving a flag now makes adding prompts later a non-breaking elaboration.

• --tenant <NOYAU> — Tenant (noyau) this galaxy belongs to. Records the ADR-063 layer-3 label in config.toml and provisions the .cosmon/state/nucleons/ directory where ADR-080 OIDC identity mappings (oidc-identity.toml) and future YubiKey keyring entries land.

  Convention: one tenant per galaxy below the configured cluster root. This flag records the label but does not enforce a path. Downstream tools read the noyau to verify the galaxy belongs to its tenant.

cs trust

Trust — grant this repository permission to run its own formulas/hooks (the direnv allow of cosmon; refuses repo-supplied shell until granted)

Usage: cs trust [OPTIONS]

Options:

• --status — Report the current trust status without changing anything
• --revoke — Revoke this repository's trust grant
• --dir <DIR> — Operate on this directory instead of the current working directory

cs config

Config — inspect .cosmon/config.toml (show adapters, adapters)

Usage: cs config <COMMAND>

Subcommands:

• show — Show resolved configuration for a topic (currently: adapters)
• adapters — List every adapter name the dispatch registry would accept (union of compile-time built-ins and [adapters.<name>] rows from .cosmon/config.toml)

cs config show

Show resolved configuration for a topic (currently: adapters)

Usage: cs config show <COMMAND>

Subcommands:

• adapters — Print the effective [adapters.*] resolution for Direct-API adapters (openai, anthropic)

cs config show adapters

Print the effective [adapters.*] resolution for Direct-API adapters (openai, anthropic)

Usage: cs config show adapters

cs config adapters

List every adapter name the dispatch registry would accept (union of compile-time built-ins and [adapters.<name>] rows from .cosmon/config.toml)

Usage: cs config adapters

cs status

Project pulse — quick DAG overview like git status; with a molecule id, that one molecule's status

Usage: cs status [MOLECULE]

EXAMPLES: cs status # pulse + staleness: age, reconcile, unmerged growth; a dead worker is named, never counted alive cs status --verbose # the same, as a dashboard with a Backlog section cs status --fleet research cs status --json # adds backlog, unmerged, galaxies, hygiene, missing_blockers; molecules.dead_workers / alive_healthy cs status task-20260907-b25f # one molecule: status/phase/updated_at/terminal cs status task-20260907-b25f --json # same four fields, machine-readable

BLOCKED-BY: only completion satisfies a dependency. A collapsed or frozen blocker keeps pending dependents held. Human status names those dependents; finish and harvest a frozen blocker (cs complete, then cs done), or collapse and re-nucleate a dependent with a new --blocked-by edge after its blocker collapses. The pulse also names pending dependents of absent blockers and blockers outside the current project. Re-nucleate the dependent with a valid --blocked-by edge, or omit the edge. A referenced legacy blocker without project_id remains visible to the resident scheduler.

STALENESS: the pulse carries derivatives, not only levels — oldest 39d · 2 >48h is the age of the oldest waiting molecule and how many are past the threshold, from the same arithmetic cs peek renders in its vitals line. surfaces ✅ reconciled 2h ago tells hash-drift from projection age: the tick is about the hashes and has never said anything about when the projection ran. 3🔀 branch residue (+1 in 3h) counts unresolved molecule branches (feat/<id>, never backup/* or spore/*). Active branches and retained branches with a recorded lifecycle disposition remain visible but do not inflate that gauge. It compares against <state>/status-gauge.json, refreshed at most hourly.

HYGIENE: a clean token (or, in --verbose, a Hygiene: line) reports whether finishing left residue behind — a zombie session, an un-harvested Completed molecule, or an unresolved molecule branch. --json's hygiene.clean is the same verdict for a script to poll; human output names every unresolved item. Active work is not residue; retained branches show the lifecycle audit disposition that justified keeping them.

LEASES: a molecule named by the pilot-lease ledger carries the cockpit between sessions and converges by design never, so it is excluded from every backlog counter and reported on its own (+1 lease). Discovered from the ledger, never from an id. In --json, molecules.alive still counts it; molecules.alive_excluding_leases and backlog.count do not.

NOTE: with a molecule id the answer is the cheap read — no coupling report, no token totals, no model attribution, and none of the staleness work above. cs observe <id> is the full one. The id is exact, never a prefix.

SEE ALSO: cs observe (full molecule read), cs wait (block until it moves), cs peek (fractal TUI — same staleness definition), cs reconcile (what the freshness signal asks for), cs ensemble (full snapshot), cs galaxies list (four-family taxonomy).

Arguments:

• <MOLECULE> — Molecule id — without it, the DAG-wide pulse; with it, that one molecule

cs project

Project — materialize views from the ledger (STATUS.md, ISSUES.md, GitHub Issues)

Usage: cs project [OPTIONS]

EXAMPLES: cs project # materialize surfaces from the ledger cs project --check # dry-run; exit 1 if surfaces are stale cs project --fetch # pull current GitHub Issue state before comparing

Pure projection. Writes STATUS.md / ISSUES.md / GitHub issues per .cosmon/surfaces.toml. Always safe to rerun. Reads as "materialize views from the ledger" (ADR-052 §D3).

Options:

• --check — Dry-run: check if surfaces are up to date without writing

• --fetch — Fetch current GitHub Issue state before comparing (detect remote edits)

• --force — Deprecated no-op. Surfaces are always overwritten from authoritative state (derived-view semantics), so there is no longer a non-force mode to override. Accepted for backward compatibility

• --no-escalate — Deprecated no-op. Surface conflicts no longer escalate or write git-style conflict blocks — surfaces are derived views and are always regenerated. Accepted for backward compatibility

• --wait — Deprecated no-op. Reconcile never nucleates resolver molecules, so there is nothing to wait for. Accepted for backward compatibility

• --heal-invariants — Heal the archived ⇒ status.is_terminal() invariant on disk.

  Default reconcile is a pure projection onto surfaces and never mutates molecule state (architectural-invariants.md). This flag opts into a one-shot migration: every molecule that is archived but carries a non-terminal status (a ghost, e.g. {archived: true, status: running}) is rewritten to status = Collapsed with reason archived-but-alive heal, and a MoleculeStatusChanged + MoleculeCollapsed event pair is appended so the heal survives a cache rebuild from events.jsonl.

  Idempotent: once healed, a second --heal-invariants pass finds nothing to do. Detect the violations first with cs verify --invariants.

cs reconcile

Reconcile — deprecated alias for cs project (ADR-052 §D3)

Usage: cs reconcile [OPTIONS]

EXAMPLES: cs reconcile # DEPRECATED — see below

DEPRECATED (ADR-052 §D3): use cs project instead. The new verb reads as "materialize views from the ledger"; reconcile read as "patch something that drifted", which is the framing ADR-052 retires. This alias will be removed after one release cycle.

SEE ALSO: cs project (canonical).

Options:

• --check — Dry-run: check if surfaces are up to date without writing

• --fetch — Fetch current GitHub Issue state before comparing (detect remote edits)

• --force — Deprecated no-op. Surfaces are always overwritten from authoritative state (derived-view semantics), so there is no longer a non-force mode to override. Accepted for backward compatibility

• --no-escalate — Deprecated no-op. Surface conflicts no longer escalate or write git-style conflict blocks — surfaces are derived views and are always regenerated. Accepted for backward compatibility

• --wait — Deprecated no-op. Reconcile never nucleates resolver molecules, so there is nothing to wait for. Accepted for backward compatibility

• --heal-invariants — Heal the archived ⇒ status.is_terminal() invariant on disk.

  Default reconcile is a pure projection onto surfaces and never mutates molecule state (architectural-invariants.md). This flag opts into a one-shot migration: every molecule that is archived but carries a non-terminal status (a ghost, e.g. {archived: true, status: running}) is rewritten to status = Collapsed with reason archived-but-alive heal, and a MoleculeStatusChanged + MoleculeCollapsed event pair is appended so the heal survives a cache rebuild from events.jsonl.

  Idempotent: once healed, a second --heal-invariants pass finds nothing to do. Detect the violations first with cs verify --invariants.

cs scheduler

Scheduler — read-only view onto cosmon-scheduler's state (patrols, last fires, log)

Usage: cs scheduler <COMMAND>

IMAGE: cosmon-scheduler is the house's alarm clock. It looks at the wall clock every 60s, reads its tablet (~/.config/cosmon/patrols.toml), and asks: 'was anything supposed to ring now?'. If yes, it fires a short-lived command, the command finishes, it dies. Cron-like.

(See the seven-clocks chronicle and the '2026-04-19 — Deux métiers, deux outils' chronicle for the full réveil/veilleur-de-nuit image.)

WHEN TO USE THE SCHEDULER:

• periodic gesture, short burst (executor-pulse every 2h, mailroom-sync every 15min, chronicle-lint every Sunday morning)
• fire-and-forget: the command finishes on its own
• no persistent connection to maintain If the command must stay alive between fires, use cs daemons instead.

EXAMPLES — operator-facing (cs scheduler): cs scheduler status # pretty table of patrol last-fires cs scheduler status --json # NDJSON, one object per patrol cs scheduler status --log-lines 20 # also tail last 20 log lines cs scheduler status --state-file /tmp/state.json cs scheduler validate # lint ~/.config/cosmon/patrols.toml cs scheduler validate --config cand.toml # pre-flight a candidate file

CARDINAL PATROLS (copy-ready reference): docs/guides/patrols-cardinal.md cosmon-ward-mayor, reading-club-tick, leaks-watchdog, backlog-frontier-rot, digest-personnel — one [[patrol]] block each.

MINIMAL patrols.toml (/.config/cosmon/patrols.toml): [scheduler] state_file = "/.cosmon/scheduler.state.json" log_file = "/.cosmon/scheduler.log" kill_switch = "/.cosmon/stand-down.lock" tick_interval_seconds = 60

[[patrol]] name = "executor-pulse" interval_seconds = 7200 # cadence: every 2h command = ["mailroom", "executor-pulse"] enabled = true

[[patrol]] name = "chronicle-lint-weekly" cron = "0 9 * * 0" # cadence: Sundays 09:00 command = ["cs", "nucleate", "chronicle-lint"] working_dir = "~/galaxies/example-project" enabled = true

HOT-RELOAD: The scheduler re-reads patrols.toml on every tick (default 60s). Edit the file, save it, and the change takes effect within one tick — no signal, no reload command. Add a patrol = it fires on the next tick; disable one = it stops.

KILL-SWITCH: touch ~/.cosmon/stand-down.lock — the scheduler observes the lock at the next tick and quietly skips every patrol until the file is removed. No child is killed; already-firing patrols finish on their own. Same lock convention as cs daemons (one lockfile silences both worlds).

SEE ALSO: cs daemons (long-running processes), ADR-050 (unified patrol scheduler).

Subcommands:

• status — Show the last-known state of every patrol the scheduler has observed
• validate — Lint patrols.toml without firing anything — the safe pre-flight when adding or editing a patrol (success criterion (i) of the autopilot primitive). Zero side-effects: no state read, no dispatch, no kill-switch touch. Exits 0 when the file parses and validates, 1 otherwise — so it doubles as a CI gate. Mirrors cosmon-scheduler validate

cs scheduler status

Show the last-known state of every patrol the scheduler has observed

Usage: cs scheduler status [OPTIONS]

Options:

• --state-file <PATH> — Path to the scheduler state file
• --log-file <PATH> — Path to the aggregate scheduler log
• --log-lines <N> — Tail the last N lines of the scheduler log after the status table. Omit the flag for no log output

cs scheduler validate

Lint patrols.toml without firing anything — the safe pre-flight when adding or editing a patrol (success criterion (i) of the autopilot primitive). Zero side-effects: no state read, no dispatch, no kill-switch touch. Exits 0 when the file parses and validates, 1 otherwise — so it doubles as a CI gate. Mirrors cosmon-scheduler validate

Usage: cs scheduler validate [OPTIONS]

Options:

• --config <PATH> — Path to the patrol config TOML to lint

cs daemons

Daemons — operator view over cosmon-daemon-supervisor (list/status/reload/logs)

Usage: cs daemons <COMMAND>

IMAGE: cosmon-daemon-supervisor is the night watchman. It does not look at the clock. It looks at the dogs — processes that must always be alive. It reads its tablet (~/.config/cosmon/daemons.toml), keeps each dog alive; if one dies, it calls it back. Dogs never die voluntarily; if they die, it is an accident.

(See the '2026-04-19 — Le gardien des chiens, et le gardien des portes' and '2026-04-19 — Deux métiers, deux outils' chronicles for the full gardien-de-chiens / veilleur-de-nuit image.)

WHEN TO USE THE SUPERVISOR:

• long-running process, persistent connection (Telegram long-polling, IMAP IDLE, MCP stdio server, Emacs daemon)
• must be restarted if it dies
• throttle respawns to avoid crashloops Synthetic examples: notification-bot, archive-service, editor-daemon, metrics-dashboard. If the command should run once-and-exit on a cadence, use cs scheduler instead.

EXAMPLES — operator-facing (cs daemons): cs daemons list # declared daemons (from daemons.toml) cs daemons status # per-daemon status + last spawn age cs daemons status --json # NDJSON, one object per daemon cs daemons reload # touch config → supervisor hot-reload cs daemons logs --lines 100 # tail the supervisor aggregate log

MINIMAL daemons.toml (/.config/cosmon/daemons.toml): [supervisor] state_file = "/.cosmon/daemon-supervisor.state.json" log_file = "/.cosmon/daemon-supervisor.log" kill_switch = "/.cosmon/stand-down.lock"

[[daemon]] name = "notification-bot" binary = "/.local/bin/notification-bot" args = [] throttle_seconds = 30 env = { RUST_LOG = "info" } log_stdout = "/.local/state/notification-bot/stdout.log" log_stderr = "~/.local/state/notification-bot/stderr.log" enabled = true

HOT-RELOAD: cs daemons reload touches ~/.config/cosmon/daemons.toml. The supervisor's notify watcher picks up the modification, runs the diff, and restarts ONLY the daemons whose spec actually changed (debounce ~200ms). Adding a new [[daemon]] block makes that daemon appear; removing one makes it exit gracefully. No signal sent to the supervisor itself.

SUPERVISOR-OF-THE-SUPERVISOR: The supervisor itself is a long-running process — it needs its own watchman. That is launchd (macOS): scripts/install-daemon-supervisor.sh installs one LaunchAgent for the supervisor, and launchd keeps it alive. The supervisor keeps N dogs alive. One plist, N dogs.

Install the LaunchAgent: scripts/install-daemon-supervisor.sh install scripts/install-daemon-supervisor.sh status scripts/install-daemon-supervisor.sh uninstall

KILL-SWITCH: touch ~/.cosmon/stand-down.lock — the supervisor SIGTERMs every child and parks them until the file disappears. Same convention as cs scheduler (one lockfile silences both).

SEE ALSO: cs scheduler (tick-based patrols), ADR-053 (cosmon-daemon-supervisor), ADR-016 §Autonomous (the regime this lives in).

Subcommands:

• list — List declared daemons (reads daemons.toml, no state)
• status — Show current status of each supervised child (reads state.json)
• reload — Trigger a hot-reload by touching the config file
• logs — Tail the supervisor log (the aggregate one, not per-daemon stdout)

cs daemons list

List declared daemons (reads daemons.toml, no state)

Usage: cs daemons list [OPTIONS]

Options:

• --config <PATH> — Path to the daemons config file. Defaults to ~/.config/cosmon/daemons.toml

cs daemons status

Show current status of each supervised child (reads state.json)

Usage: cs daemons status [OPTIONS]

Options:

• --config <PATH> — Path to the daemons config file. Defaults to ~/.config/cosmon/daemons.toml. Used to resolve the state file
• --state-file <PATH> — Path to the supervisor state file. Overrides the state_file declared in the config

cs daemons reload

Trigger a hot-reload by touching the config file.

The supervisor's notify watcher picks up the modification and runs diff; no signal is sent and no child is restarted unless its DaemonSpec actually changed.

Usage: cs daemons reload [OPTIONS]

Options:

• --config <PATH> — Path to the daemons config file. Defaults to ~/.config/cosmon/daemons.toml

cs daemons logs

Tail the supervisor log (the aggregate one, not per-daemon stdout)

Usage: cs daemons logs [OPTIONS]

Options:

• --config <PATH> — Path to the daemons config file. Defaults to ~/.config/cosmon/daemons.toml. Used to resolve the log file

• --log-file <PATH> — Path to the supervisor log file. Overrides the log_file declared in the config

• --lines <N> — Number of trailing lines to print. Defaults to 50

  Default value: 50

cs migrate

Migrate the galaxy's memory — legacy flat→fleet, or residence-to-residence

Usage: cs migrate [OPTIONS] [COMMAND]

EXAMPLES: cs migrate # legacy flat→fleet migration (pre-residence galaxies) cs migrate to solo # atomic data+git migration to solo residence cs migrate to team # move to team residence (seal → stage → verify → flip + git-side) cs migrate to team --dry-run # seal manifest, print plan, touch no state cs migrate to solo --no-git # skip the git-side half (data only — outside a git repo) cs migrate to solo --no-commit # stage git-side changes, let operator commit cs migrate verify # re-walk state, compare against sealed manifest cs migrate rollback # inverse rename + restore git index / ignore files cs migrate rollback --dry-run # preview the rename pair, touch nothing cs migrate genre github-surface --to solo --yes # scoped: apply solo to one genre (ADR-057) cs migrate genre chronicle --to team --yes # seed orphan branch cosmon/chronicle cs migrate genre github-surface --to solo --dry-run # preview the plan, touch nothing

RESIDENCE VALUES: solo local, single operator (default layout) — state goes into .git/info/exclude team local, shared via git (cosmon-le-repo) — state goes into .gitignore encrypted local, encrypted at rest — same gitignore rule as team remote server-backed, network transport — same gitignore rule as team

EXIT CODES (cs migrate verify, mirrors cs verify): 0 manifest matches current state (A_pre ⊆ A_post, seal intact) 1 divergence: offending entries listed on stderr 2 no manifest on record (pre-migration galaxy or stale state)

The residence migration writes migration-manifest.pre.json at the galaxy root before touching any state, then stages the new tree alongside as state.next/, verifies it against the manifest, performs two atomic rename(2) calls to flip, and finally runs the git-side half: git rm -r --cached on the state directory, appends the state path to the residence's ignore file (.git/info/exclude for solo, .gitignore for team-class), and commits chore(cosmon): migrate to <residence> residence (git-side) unless --no-commit is passed. state.prev/ is kept as the rollback anchor; the pre-migration manifest also carries a snapshot of the git HEAD and ignore files so rollback restores the git side byte-for-byte. Orphan files (not tied to any molecule) are carried in a distinct bucket and never silently discarded.

Subcommands:

• to — Perform a residence migration: seal manifest → stage next tree → verify staged tree → atomic rename pair to flip
• verify — Verify the pre-migration BLAKE3 manifest against the current state. Exit codes mirror cs verify: 0 match, 1 divergence, 2 no manifest on record
• rollback — Roll back the last migration by re-materializing state.prev/
• genre — Apply a residence to every tracked path classified under a single genre (ADR-057 artifact-map). Composes artifact-map + git-side migration

Options:

• --dry-run — Legacy mode: preview what would be migrated without moving anything
• --cleanup — Legacy mode: remove the legacy ops/molecules/ directory after migration
• --archive-past — Legacy mode: backfill the archive for existing terminal molecules (Completed, Collapsed, Frozen). Idempotent: molecules already carrying archived = true are skipped

cs migrate to

Perform a residence migration: seal manifest → stage next tree → verify staged tree → atomic rename pair to flip.

Atomic data-and-git residence flip. After the data-side phases (seal → stage → verify → rename), the git-side half runs (untrack + ignore-file update + path-scoped auto-commit) unless --no-git / --no-commit opt out.

Per-residence behavior (the four places the galaxy's memory can live):

solo Writes .cosmon/ to .git/info/exclude (per-clone notebook, never pushed). Sweeps any legacy .cosmon/ / .worktrees/ lines still present in the tracked .gitignore so the shared bulletin board doesn't override the local rule. Total local invisibility (ADR-055 §3.1).

team Appends .cosmon/state/ to the tracked .gitignore (shared with the code repo) and untracks any state files previously committed. Structural files (config.toml, formulas/*.toml, surfaces.toml, .gitignore) stay trackable. Orphan-branch-backed state sharing (cosmon/state) is the cosmon-le-repo backend target.

encrypted Same gitignore footprint as team today. The age-wrap backend (requires age on PATH and a --recipient recipient key) is deferred to cosmon-le-repo.

remote Same gitignore footprint as team. The server-backed transport backend is not yet implemented.

The pre-migration manifest snapshots git HEAD + ignore files so cs migrate rollback can restore the git side byte-for-byte. Orphan files (not tied to any molecule id) are carried in a distinct bucket and never silently discarded.

Usage: cs migrate to [OPTIONS] <RESIDENCE>

Arguments:

• <RESIDENCE> — Target residence: solo, team, encrypted, or remote

  Possible values:

  • solo: Solo — local, single operator. Writes the whole .cosmon/ directory to .git/info/exclude (per-clone notebook, never pushed) and sweeps any legacy .cosmon/ / .worktrees/ lines from the tracked .gitignore (ADR-055 §3.1)
  • team: Team — local, shared across operators via git. Appends .cosmon/state/ to the tracked .gitignore (shared bulletin board) and untracks any previously committed state files. Structural files (config.toml, formulas/*.toml, surfaces.toml) stay trackable on main. Orphan-branch-based state sharing (cosmon/state) is the cosmon-le-repo backend target
  • encrypted: Encrypted — local, encrypted at rest. Same gitignore footprint as team today; the age-wrap backend (requires age on PATH and a --recipient key) is deferred to cosmon-le-repo
  • remote: Remote — server-backed state accessed via network transport. Same gitignore footprint as team; the transport backend is not yet implemented (tracked by cosmon-le-repo)

Options:

• --dry-run — Preview the plan (seal + staging path) without renaming anything
• --no-git — Skip the git-side half of the migration (no git rm --cached, no gitignore/exclude update, no auto-commit). Useful for tests and for galaxies that live outside a git repository
• --no-commit — Apply git-side changes to the index + ignore file but do not create the chore(cosmon): migrate to <residence> residence (git-side) commit. The operator can inspect git status and commit manually

cs migrate verify

Verify the pre-migration BLAKE3 manifest against the current state. Exit codes mirror cs verify: 0 match, 1 divergence, 2 no manifest on record

Usage: cs migrate verify

cs migrate rollback

Roll back the last migration by re-materializing state.prev/

Usage: cs migrate rollback [OPTIONS]

Options:

• --dry-run — Preview which rename would run without touching disk

cs migrate genre

Apply a residence to every tracked path classified under a single genre (ADR-057 artifact-map). Composes artifact-map + git-side migration

Usage: cs migrate genre [OPTIONS] --to <RESIDENCE> <NAME>

Arguments:

• <NAME> — Genre name (must match a [<name>] table in .cosmon/artifact-map.toml)

Options:

• --to <RESIDENCE> — Target residence

  Possible values:

  • solo: Solo — local, single operator. Writes the whole .cosmon/ directory to .git/info/exclude (per-clone notebook, never pushed) and sweeps any legacy .cosmon/ / .worktrees/ lines from the tracked .gitignore (ADR-055 §3.1)
  • team: Team — local, shared across operators via git. Appends .cosmon/state/ to the tracked .gitignore (shared bulletin board) and untracks any previously committed state files. Structural files (config.toml, formulas/*.toml, surfaces.toml) stay trackable on main. Orphan-branch-based state sharing (cosmon/state) is the cosmon-le-repo backend target
  • encrypted: Encrypted — local, encrypted at rest. Same gitignore footprint as team today; the age-wrap backend (requires age on PATH and a --recipient key) is deferred to cosmon-le-repo
  • remote: Remote — server-backed state accessed via network transport. Same gitignore footprint as team; the transport backend is not yet implemented (tracked by cosmon-le-repo)

• --scrub-history — After the residence transition, invoke cs git scrub-history --path <paths> (when available) to rewrite prior commits that touched the matched paths.

  Soft dependency on cs git scrub-history. When the subcommand is not yet implemented, this flag degrades to a one-line warning and the migration still succeeds on the current tree.

• --recipient <AGE_RECIPIENT> — age recipient to wrap the narration for, when --to encrypted is set. Required for the encrypted path

• --dry-run — Preview the plan without writing to disk or touching git

• -y, --yes — Skip the interactive confirmation prompt

cs deps

Deps — show blocking, lineage, and citation links for a molecule

Usage: cs deps [OPTIONS] <MOLECULE>

EXAMPLES: cs deps # blocking, lineage, citation links cs deps --transitive # planned children and pipeline closure cs --json deps # for scripting

Walks Blocks / BlockedBy, DecayProduct / DecayedFrom, and citation links. Only BlockedBy is a completion prerequisite; a planner can freeze after verification while its lineage-linked first child becomes dispatchable.

Arguments:

• <MOLECULE> — Molecule ID (exact or prefix) whose dependencies should be shown

Options:

• --transitive — Walk the full transitive closure instead of only direct edges

cs mission

Mission — read-only DAG view joining ledger edges to completion merge commits

Usage: cs mission <COMMAND>

Subcommands:

• graph — Render the mission DAG rooted at a molecule, joining ledger edges to their completion merge commits

cs mission graph

Render the mission DAG rooted at a molecule, joining ledger edges to their completion merge commits

Usage: cs mission graph <ROOT>

Arguments:

• <ROOT> — Mission root molecule ID (exact or unambiguous prefix)

cs diverge

Diverge — structural agreement check between two sessions on a molecule (turing §5)

Usage: cs diverge [OPTIONS] <A> <B>

EXAMPLES: cs diverge <mol_id> # structural agreement check between two sessions

A structural-agreement primitive: two independent sessions on the same molecule are compared for divergence on the artifacts they produced. Used by livelock detection and consensus checks.

SEE ALSO: cs observe, cs deps.

Arguments:

• <A> — First session — a session id or a path to a galaxy root
• <B> — Second session — a session id or a path to a galaxy root

Options:

• -m, --molecule <MOLECULE> — Molecule id (or prefix) whose views to compare. If omitted, only the git merge-base clause is evaluated and all molecule clauses are marked inconclusive

cs galaxies

Galaxies — inspect the four-family taxonomy

Usage: cs galaxies <COMMAND>

IMAGE: The fleet of repositories is not a flat list — it is four families, classified by the direction the bits flow across the galaxy's boundary:

infra        bits flow inward    the galaxy enables its sisters
project      bits flow through   artefacts + illuminated principles
social-hub   bits flow laterally human-to-human coordination
editorial    bits flow outward   one-way publication to strangers
nascent      not yet classified  awaiting W=28d observable tests

EXAMPLES: cs galaxies list # grouped view, one section per family cs galaxies list --json # flat array + by_kind totals

SEE ALSO: cs status --json (embeds the same galaxies block).

Subcommands:

• list — List every galaxy grouped by its galaxy_kind family
• registry — Inspect the stateless galaxy-name registry (~/.config/cosmon/galaxies.toml) used by cs ask

cs galaxies list

List every galaxy grouped by its galaxy_kind family

Usage: cs galaxies list

cs galaxies registry

Inspect the stateless galaxy-name registry (~/.config/cosmon/galaxies.toml) used by cs ask

Usage: cs galaxies registry <COMMAND>

Subcommands:

• list — List every galaxy declared in the registry TOML
• resolve — Resolve a single galaxy by name. Exits with status 1 if the name is not registered, so scripts can use it as a gate

cs galaxies registry list

List every galaxy declared in the registry TOML.

With --json, emits NDJSON (one entry per line) — the shape cs ask and other pilot agents can pipe into jq without extra envelope parsing.

Usage: cs galaxies registry list

cs galaxies registry resolve

Resolve a single galaxy by name. Exits with status 1 if the name is not registered, so scripts can use it as a gate

Usage: cs galaxies registry resolve <NAME>

Arguments:

• <NAME> — Galaxy name to look up (exact match, case-sensitive)

cs topology

Topology — structural maps of the workspace (wraps the topon CLI)

Usage: cs topology <COMMAND>

EXAMPLES: cs topology map # PageRank-ranked module graph cs topology outline crates/cosmon-core/src/lib.rs cs topology symbols MoleculeId

Thin wrapper over the topon CLI. Structural view, not runtime state.

Subcommands:

• map — PageRank-ranked structural map of a Rust project
• outline — Symbol outline of a single Rust file
• symbols — Search symbols by name across a Rust project

cs topology map

PageRank-ranked structural map of a Rust project

Usage: cs topology map [OPTIONS] [PATH]

Arguments:

• <PATH> — Path to the project root (defaults to current directory)

  Default value: .

Options:

• --max-symbols <MAX_SYMBOLS> — Maximum symbols per module (0 = unlimited)

  Default value: 0

cs topology outline

Symbol outline of a single Rust file

Usage: cs topology outline <FILE>

Arguments:

• <FILE> — Path to the .rs file

cs topology symbols

Search symbols by name across a Rust project

Usage: cs topology symbols <PATH> <QUERY>

Arguments:

• <PATH> — Path to the project root
• <QUERY> — Search query (case-insensitive substring match)

Observability commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs peek

Peek — canonical fleet observation command (TUI default; --no-tui for plaintext stream)

The context gauge uses the latest reported turn's input over the model window. Unknown occupancy has no percentage; token columns stay cumulative.

Usage: cs peek [OPTIONS]

EXAMPLES: cs peek # TUI over the current .cosmon/ cs peek --phase done,failed # + the archive; project scope unchanged cs peek --phase harvestable # the harvest queue: finished work still # owed a cs done (completed, unarchived) cs peek --all-galaxies # same phases, every .cosmon/ + tmux socket cs peek --all # sugar for --all-galaxies --phase all cs peek --no-tui # plaintext event stream cs peek --snapshot # byte-deterministic 120-col canonical view cs peek --snapshot > /tmp/a # capture from any device, then diff two # captures and expect zero bytes (see # docs/guides/peek-snapshot.md)

The context gauge uses the latest reported turn's input tokens over the model window. An unknown turn or window shows no percentage; IN/CACHED/OUT/RSN remain cumulative session counters. Snapshot follows the same rule. JSON keeps its existing cumulative usage schema and exposes no context percentage.

The selected dependent's blocked-by detail names a collapsed or frozen blocker and the operator gesture that can release or replace the edge.

Keys in the TUI: j/k navigate, p tmux pane capture, b/l/e/s/r/n/g briefing/log/events/synthesis/responses/notes/git tabs.

Options:

• --no-tui — Disable the TUI and render plaintext events to stdout. Required until the Phase 1 ratatui TUI lands

• --once — Run a single poll + diff + propel pass and exit. Implies --no-tui

• --follow — Follow the event stream until interrupted (the default for --no-tui when --once is not set)

• --stale-after <STALE_AFTER> — Staleness threshold in seconds, passed to the propel pass

  Default value: 300

• --poll-ms <POLL_MS> — State poll cadence in milliseconds

  Default value: 1000

• --propel-every <PROPEL_EVERY> — Propel nudge cadence in seconds. Defaults to min(60, stale_after/5)

• --no-tmux — Disable tmux propulsion. State is still read and diffed, but no nudges are sent

• --all — Sugar for --all-galaxies --phase all, and exactly that. Both axes at their widest: every project AND every phase, archive included. --all means all, literally; it never narrows. Conflicts with the two flags it expands to — sugar and its expansion are one way of saying one thing, not two ways of saying it twice. See docs/guides/peek-temporalities.md

• --all-galaxies — Perimeter axis: scan every project under $COSMON_CLUSTER_ROOT instead of the current one. Opt-in — cross-project reach is never implicit. Says nothing about which phases you see. Same spelling as cs tail --all-galaxies: one word, one meaning, across the binary. In TUI mode the a key toggles this at runtime

• --phase <PHASE> — Temporality axis: which phases to surface. Repeatable and comma-separated; the values union. Says nothing about the perimeter. Defaults to unfinished — every molecule whose story is not over. --phase unfinished,done,failed is what --past used to mean; --phase harvestable is the harvest queue — finished work still owed a cs done. In TUI mode the A key cycles this at runtime

  Possible values:

  • live: A worker is on it right now
  • waiting: Nucleated, not yet started
  • blocked: An external authority is refusing service (ADR-062)
  • parked: Frozen by an operator gesture; one cs thaw from running
  • failed: Collapsed
  • done: Completed — the whole archive, harvested or not
  • harvestable: The harvest queue: completed and not yet archived, i.e. still owed a cs done. A strict subset of done
  • unfinished: Every phase whose story is not over — the default view
  • all: Every phase, archive included. All of this axis, and only this axis: it does not touch the perimeter

• --energy-tick-interval <ENERGY_TICK_INTERVAL> — Cadence in seconds for emitting UsageObserved events into events.jsonl. Zero disables emission. Only active in --no-tui mode

  Default value: 30

• --snapshot — Emit a byte-deterministic, fixed-width (120-col) ASCII snapshot of the fleet and exit. The same fleet state produces byte-identical output across every device — iPhone SSH, iPad Blink, MacBook, tmux pane — so a PR reviewer can diff two captures and expect zero differences. Implies --no-tui and disables propulsion; no clock or environment ($COLUMNS, $TERM) affects the output

cs tail

Tail — live notify-driven reader over events.jsonl (fleet or --all-galaxies)

Usage: cs tail [OPTIONS]

EXAMPLES: cs tail # live tail of the current galaxy events.jsonl cs tail --all-galaxies # multiplex all known galaxies

Live notify-driven reader over events.jsonl. Default scope is the current fleet; --all-galaxies multiplexes across the registered cosmon roots.

SEE ALSO: cs events (one-shot dump), cs ensemble (snapshot view).

Options:

• --all-galaxies — Scan every project under $COSMON_CLUSTER_ROOT. Opt-in — cross-project reach is never implicit

• -f, --follow — Stay attached and stream new events via notify

• --since <SINCE> — Only show events at or after this timestamp. Accepts ISO-8601 (2026-04-24T12:00:00Z) or relative (-5m, -1h, -2d). allow_hyphen_values lets the relative form be written without --since=

• --kind <KIND> — Only show events whose type tag matches (e.g. molecule_nucleated)

• -n, --tail <TAIL> — Number of most-recent lines to print before follow (like tail -n)

  Default value: 20

• --cluster-root <CLUSTER_ROOT> — Override the cluster root used by --all-galaxies

cs errors

Errors — aggregate molecule-collapse events into one failure overview: what is breaking the fleet, and which molecules are hit

Usage: cs errors [OPTIONS]

Options:

• --since <SINCE> — Time window — accepts a relative duration (<N>d, <N>h, <N>m, <N>s) or an RFC-3339 absolute timestamp. Defaults to 7 days

  Default value: 7d

• --kind <VARIANT> — Filter to one CollapseReason variant. Accepts the on-wire strings: worker_crashed, gate_failed, blocker_stuck, manual_abort, resource_exhausted. Any other value is treated as a substring match on the free-form Other payload

• --reason <TEXT> — Substring match on the free-form reason text. Case-sensitive

• --top <TOP> — Maximum number of variant rows to display in the summary

  Default value: 10

• --ops-dir <OPS_DIR> — Path to the state store root (overrides walk-up discovery)

• --json — Emit JSON instead of the tabular summary. The global --json flag also enables this

cs health

Health — read-only molecule-health anomaly catalog, federation-wide (ADR-137 §7)

Usage: cs health [OPTIONS]

EXAMPLES: cs health # read-only anomaly catalog, current galaxy cs health --all # every project below the configured root cs health --json # NDJSON: one header line, one line per finding cs health --no-tmux # state-only (skip the tmux liveness probe)

The Witness (ADR-137 Phase 1): a zero-mutation, control-plane-only scan that surfaces the molecule-health anomaly catalog (A1 unsent-paste, A3 auth-dead, A4 idle-after-complete, A5 idle-running-zombie, A6 overloaded, A7 ghost-merge, A8 completed-unharvested, A9 crash-zombie) the way cs peek surfaces fleet state. Every signal is read from the state machine — molecule status, liveness lease, transport probe — NEVER from a pane glyph (the be1e use/mention guard). It heals nothing; the remedies it prints are advisory. Exit code: 0 all-healthy, 1 findings present (CI/monitor-friendly).

Options:

• --all — Scan every .cosmon/state/ below the configured cluster root, the way cs peek --all aggregates. Without it, only the current galaxy's state store is scanned
• --no-tmux — Skip the tmux liveness probe (state-only mode, for tests / headless). Session liveness is reported as unknown, so session-dependent classes (A1/A4/A5/A9) are conservatively not flagged

cs pulse

Pulse — runtime-vitality reading: RPM tachometer, six-voyant strip (ADR-138 P1)

Usage: cs pulse [OPTIONS]

EXAMPLES: cs pulse # runtime-vitality: RPM tachometer + six voyants cs pulse --window 10m # widen observation window (default 5m) cs pulse --json # cosmon.pulse/v1 NDJSON line (CI/scripting)

Pulse (ADR-138 Phase 1): a zero-mutation, stateless projection of fleet liveness onto a single tachometer headline + six-voyant strip.

Headline: RPM = dΦ/dt = completions/min in the observation window W. The event log is the pre-integrated derivative — no stored Φ, no new state store (IFBDD). A word replaces the number when magnitude lies: SPINNING — tokens burn, Φ flat (P==0, B>b_min) → RED DRAINAGE OFF — no forward tick in τ → RED

Traffic light (first-match wins): RED — subsystem dead (H_sched>τ) OR fuel exhausted OR spinning AMBER — stalled (P==0, L>0, ¬dead) OR starved molecules present GREEN — doing work (P>0) OR quiescent (L==0)

Voyant strip: scheduler / drainage / propel / heal / fuel / workers A dead subsystem serializes 'off' (red-class) — never silently absent.

Exit code: always 0 (read-only, non-blocking — callers use --json state).

Options:

• --window <WINDOW> — Observation window — accepts <N>d / <N>h / <N>m / <N>s. Defaults to 5 minutes (5m)

  Default value: 5m

• --sched-tau <SCHED_TAU> — Scheduler-dead threshold — age beyond which H_sched triggers RED. Defaults to 10 minutes (10m)

  Default value: 10m

• --sched-log <SCHED_LOG> — Path to the launchd-scheduler heartbeat log.

  Defaults to ~/.cosmon/scheduler.state.json.events.jsonl (derived from the scheduler state file by appending .events.jsonl).

  Override with COSMON_SCHED_LOG env var or this flag for testability or non-standard launchd setups.

• --sched-state <SCHED_STATE> — Path to scheduler.state.json.

  The drainage, propel, and heal voyants read patrols.<name>.last_fired_at from this file — the authoritative per-patrol fire time written by the scheduler on every dispatch, regardless of what the patrol command does.

  Defaults to ~/.cosmon/scheduler.state.json. Override with COSMON_SCHED_STATE env var or this flag for testability.

• --json — Emit the aggregate as a single cosmon.pulse/v1 NDJSON line. The global --json flag also enables this

• --swiftbar — Emit SwiftBar/BitBar formatted output for the macOS menubar plugin.

  First line = menubar face (colored dot + headline + SwiftBar params). Below ---: the six voyant lines, fuel%, scanned, separator, action items. Consumed by menubar/cosmon-pulse.10s.sh which execs cs pulse --swiftbar. See ADR-068: cs pulse --swiftbar is the UI surface for cs pulse.

cs doctor

Doctor — diagnostic probes (whisper channel, …)

Usage: cs doctor <COMMAND>

Subcommands:

• whisper — Probe the whisper channel of a molecule's assigned worker
• leaks — Scan tracked files for leaked secrets and non-public state (blocking)
• worktrees — Audit .worktrees/ for perm/symlink/untracked hazards
• mcp — Audit MCP servers registered in the configured service registry
• deps — Flag unpinned or mutable dependency declarations
• gitignore — Check that .cosmon/.gitignore tracks the archive it claims to
• supervision — Detect binaries supervised by both cosmon and a LaunchAgent
• security — Run every security probe and aggregate findings

cs doctor whisper

Probe the whisper channel of a molecule's assigned worker

Usage: cs doctor whisper <MOLECULE_ID>

Arguments:

• <MOLECULE_ID> — Molecule ID (full or unambiguous prefix)

cs doctor leaks

Scan tracked files for leaked secrets and non-public state (blocking)

Usage: cs doctor leaks [OPTIONS]

Options:

• --path <PATH> — Limit scanning to this subdirectory (relative to repo root)
• --include-untracked — Also scan untracked working-tree files (use when pre-commit check)
• --corpus <FILE> — Byte-literal patterns, one per line (UTF-8, # comments)

cs doctor worktrees

Audit .worktrees/ for perm/symlink/untracked hazards

Usage: cs doctor worktrees [OPTIONS]

Options:

• --root <ROOT> — Override the project root (default: git top-level)

cs doctor mcp

Audit MCP servers registered in the configured service registry

Usage: cs doctor mcp [OPTIONS]

Options:

• --registry <REGISTRY> — Override the path to the service registry database.

  Defaults to the platform data dir used by the service registry.

cs doctor deps

Flag unpinned or mutable dependency declarations

Usage: cs doctor deps [OPTIONS]

Options:

• --root <ROOT> — Override the workspace root

cs doctor gitignore

Check that .cosmon/.gitignore tracks the archive it claims to

Usage: cs doctor gitignore [OPTIONS]

Options:

• --root <ROOT> — Override the galaxy root (the directory containing .cosmon/)

cs doctor supervision

Detect binaries supervised by both cosmon and a LaunchAgent

Usage: cs doctor supervision [OPTIONS]

Options:

• --patrols <PATROLS> — Override the patrols config (~/.config/cosmon/patrols.toml)
• --daemons <DAEMONS> — Override the daemons config (~/.config/cosmon/daemons.toml)
• --launch-agents-dir <LAUNCH_AGENTS_DIR> — Override the LaunchAgents directory to scan

cs doctor security

Run every security probe and aggregate findings

Usage: cs doctor security [OPTIONS]

Options:

• --root <ROOT> — Override the workspace/git root
• --registry <REGISTRY> — Override the path to the service registry database
• --include-untracked — Also include untracked files in the leak scan

Integrity & audit commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs verify

Verify — walk a molecule's event hash chain (plumbing v2)

Usage: cs verify [OPTIONS] [MOLECULE_ID]

EXAMPLES: cs verify # walk the event hash chain cs verify --strict # also replay gates

Proof-of-work chain integrity check.

Arguments:

• <MOLECULE_ID> — Molecule ID (or prefix) whose proof-of-work chain should be verified.

  Optional when --federation is set — the federation provenance scan is a fleet-wide audit and does not target a single molecule.

Options:

• --no-replay — Skip gate replay (shell/native step re-execution). Artifact hash check and event chain check still run

• --step <N> — Verify the briefing seal for a specific zero-based step index.

  When omitted, the most recent briefing seal (if any) is checked against the current briefing.md. When specified, the corresponding entry from MoleculeData::briefing_seals is used. If no seal exists for the requested step, the check is reported as SKIP (inconclusive), never as FAIL.

• --federation — Scan the fleet-wide event log for cross-galaxy events missing federation provenance (ADR-105, I9' machinery).

  When set, walks <state_dir>/events.jsonl and reports every cross-galaxy event whose federation_provenance is None:

  • MergeDispatched / MergeCompleted whose molecule_id or branch carries a foreign galaxy alias (Oracle B subject-mark per ADR-105 §D3). - ChronicleAdded whose cites_galaxies mentions a non-cosmon peer (Oracle B'' delegation-dispatched per ADR-105 §D3). - AdrInscribed whose cites_galaxies mentions a non-cosmon peer (same Oracle B'' channel for ADR-grade citations).

  Missing provenance is a hard FAIL — the federation discipline is detect-on-write, cs verify --federation is the audit oracle.

  The flag stacks with molecule_id: when both are given, the scan is restricted to the molecule's local events.jsonl. When molecule_id is omitted, the fleet-wide log is scanned.

• --legacy-tolerate-before <DATE> — Tolerate cross-galaxy events emitted before a specific date that lack federation provenance.

  Format: ISO8601 date (e.g. 2026-05-19). Events whose envelope timestamp is strictly before the date are downgraded from FAIL to SKIP with a tracing::warn!-equivalent detail line. Only meaningful in combination with --federation.

  Default: not set — every cross-galaxy event without provenance is a hard FAIL. ADR-105 §"Backfill discipline" recommends option (a) (backfill the field by reading the existing citation format); this flag is option (b), the legacy-tolerate escape hatch for the migration window.

• --invariants — Check structural state-machine invariants over molecule rows.

  Currently a single invariant is enforced: archived ⇒ status.is_terminal() — an archived molecule must carry a terminal status (Completed or Collapsed). A row with {archived: true, status: running} is a ghost: it was torn down out-of-band (e.g. cs done --force on a never-completed molecule) without terminalizing its status, so it keeps rendering as live work.

  Detection only — cs verify --invariants never mutates state; it exits non-zero when any violation is found. To heal the on-disk rows (rewrite status → Collapsed), run cs reconcile --heal-invariants.

  Like --federation, the flag stacks with molecule_id: with a molecule given, only that row is checked; without one, every molecule in the fleet is swept (the galaxy-wide audit).

cs verify-trace

verify-trace — replay events.jsonl against the scheduler spec (Phase 3 CI gate)

Usage: cs verify-trace [OPTIONS] <TRACE>

Arguments:

• <TRACE> — Path to the events.jsonl trace. Use - to read from stdin

Options:

• --skip-unknown — Tolerate lines whose shape is not recognised by EventV2 or the legacy migration helper — they are counted and skipped instead of failing the whole replay. Required when replaying historical fleet logs that pre-date the canonical schema

cs verify-graph

verify-graph — Tarjan SCC check on the subgraph induced by a typed relation (substrate, ADR-016)

Usage: cs verify-graph [OPTIONS]

EXAMPLES: cs verify-graph --relation blocks # check the Blocks subgraph for cycles cs verify-graph --relation refines # check Refines (cycles permitted, reported as WARN) cs verify-graph --all # every registered relation cs verify-graph --all --json # NDJSON, one row per relation

Tarjan SCC check on the subgraph induced by a typed MoleculeLink relation. Substrate primitive for the organization-twin programme. Read-only — does not mutate state.

Exit code: 0 every DAG-required relation is acyclic 1 at least one DAG-required relation contained a cycle Cycles in non-DAG-required relations (e.g. refines) are reported but do not flip the exit code.

Options:

• --relation <KIND> — Single relation to check (e.g. blocks, decay-product, merged-from, refines, refutes). Mutually exclusive with --all
• --all — Check every registered relation kind in turn

cs spec-audit

spec-audit — ledger audit against the TLA+ spec (catches c1cb bypass_merge)

Usage: cs spec-audit [OPTIONS]

EXAMPLES: cs spec-audit # default: cosmon-run × events.jsonl cs spec-audit --fleet default # explicit fleet (advisory today) cs spec-audit --events path/to/events.jsonl cs spec-audit --json # NDJSON drift report cs spec-audit --no-git-probe # skip the c1cb merge-topology probe

Multi-spec: cs spec-audit --spec mycelial-gate --events .cosmon/state/attestor-events.jsonl cs spec-audit --spec attestor-graph --events .cosmon/state/attestor-events.jsonl cs spec-audit --spec witness-freshness --events .cosmon/state/attestor-events.jsonl cs spec-audit --spec noogram/specs/MycelialGate.tla # path also accepted

Ledger audit: replays events through the TLA+ spec and flags drifts. For --spec cosmon-run (default), drifts include c1cb bypass_merge and disabled-action-fired. For the noogram specs, drifts are emitted as spec_invariant_violation with stable (spec, invariant) tags — see crates/cosmon-core/src/attestor_audit.rs for the full taxonomy and docs/specs/attestor-events.schema.json for the AttestorEventV1 NDJSON schema. One-shot, not a daemon. Exit 0 if clean, 1 if any drift is found.

Options:

• --fleet <FLEET> — Fleet id whose ledger should be audited. Defaults to the fleet resolved from the walk-up config (default for single-fleet projects). The fleet id is advisory today — the canonical events.jsonl lives at .cosmon/state/events.jsonl regardless of fleet — but the flag is accepted so future multi-ledger layouts stay backward-compatible

• --spec <SPEC> — Which spec to audit against. Defaults to cosmon-run (historical behaviour). Other accepted values: mycelial-gate, attestor-graph, witness-freshness. A path to a .tla file is also accepted; the basename (snake/Camel-case normalised) is looked up in the registry

  Default value: cosmon-run

• --events <PATH> — Explicit path to the events file to audit. Overrides --fleet and the walk-up state-dir discovery. The expected format depends on --spec:

  • cosmon-run → .cosmon/state/events.jsonl (EventV2 envelopes). * Noogram specs → .cosmon/state/attestor-events.jsonl (AttestorEventV1 envelopes, see cosmon/docs/specs/attestor-events.schema.json).

• --repo <PATH> — Repository whose branch topology should be probed for the c1cb out-of-band check. Defaults to the current working directory. Pass --no-git-probe to disable the probe entirely (useful when git is not available, e.g. inside CI sandboxes). Only meaningful when --spec cosmon-run

• --no-git-probe — Disable the git-topology probe. When set, the audit still flags disabled-action-fired drifts but does not emit bypass_merge findings. The switch exists so the audit stays useful in environments without git (containers, strict sandboxes). Only meaningful when --spec cosmon-run

• --target-ref <REF> — Target branch for the merge-topology probe. Defaults to origin/main; pass main to check the local branch when no remote tracking is configured. Only meaningful when --spec cosmon-run

  Default value: origin/main

cs release-audit

release-audit — dry-run drift detector for the public distribution (analogue of reconcile --check)

Usage: cs release-audit [OPTIONS]

EXAMPLES: cs release-audit --dry-run # simulate the release chain on the live tree cs release-audit --dry-run --json # machine report for CI / jq cs release-audit --repo /path/to/clone # audit an explicit repo root

Dry-run drift detector for the public cosmon distribution — the release-side analogue of cs reconcile --check.

PRIMARY MEMBRANE — deny-by-default allowlist (ADR-127). Ship nothing except positively-cleared paths: every tracked, non-purged path must carry a per-path permit in .cosmon/release-allowlist.toml, or it is a path-not-permitted regression. A new confidential file is caught BY CONSTRUCTION (new = unpermitted = refused), instead of slipping past a frozen denylist. Content-bound permits (with a blake3 seal) go permit-stale when the file changes — cleanliness-now, not freshness-at-t0. The membrane is ARMED by the presence of the allowlist file; absent it, the audit runs in legacy denylist mode and says so LOUDLY (a warning, never a silent pass). Bless paths with scripts/release/ bless-allowlist.sh (a separate tool — the audit stays read-only).

CONTENT BACKSTOP — the legacy detectors still run on permitted files:

• a private-sibling path dependency reappeared (the claudion vendoring case);
• a client name reintroduced in a tracked path the rename chain misses;
• a structural string the chain does not scrub (operator homeserver, etc.);
• a live instance oidc-identity.toml re-tracked under a non-purged path. The confidential detector literals live in the PRIVATE, purged-from-release .cosmon/release-rules.toml (Bucket-3) — not in the shipped source, so the detector is no longer its own leak. Absent that file the backstop is inert and the audit warns.

Exit 0 if the distribution is clean, 1 if it would regress. One-shot, not a daemon; reports, does not remediate. See ADR-127.

The audited repo may exempt structural strings that are intentionally public in it (e.g. a maintainer-contact domain) via .cosmon/release-audit.toml, each with a mandatory justification — the same exemption list its own forbid-strings CI gate should read, so both referees agree.

Options:

• --dry-run — Simulate the release-resync transformation chain against the live working tree (no scratch clone) and report regressions. This is currently the only mode; the flag is accepted so the documented invocation cs release-audit --dry-run is exact
• --repo <PATH> — Repository root to audit. Defaults to the toplevel discovered by git rev-parse --show-toplevel from the current directory

cs notarize

Notarize — issue or verify an operator-signed attestation for a molecule (ADR-056)

Usage: cs notarize [OPTIONS] [MOLECULE_ID] [COMMAND]

Subcommands:

• issue — Issue a new seal — build the commitment, sign with Ed25519, write mint.json
• verify — Verify an existing seal — full Ed25519 + canonical commitment bytes

Arguments:

• <MOLECULE_ID> — Legacy: molecule ID (or prefix) to notarize. Equivalent to cs notarize issue <MOLECULE_ID>

Options:

• --dry-run — Legacy: skip signing — compute and print the commitment only
• --key <PATH> — Legacy: path to an Ed25519 secret-key file
• --cosmon-version <COSMON_VERSION> — Legacy: override cosmon_version in the commitment

cs notarize issue

Issue a new seal — build the commitment, sign with Ed25519, write mint.json

Usage: cs notarize issue [OPTIONS] <MOLECULE_ID>

Arguments:

• <MOLECULE_ID> — Molecule ID (or prefix) to notarize

Options:

• --dry-run — Skip signing — compute and print the commitment only. Default when --key is not provided
• --key <PATH> — Path to an Ed25519 secret-key file (raw 32 bytes or 64-char lowercase hex). Required for a real notarization
• --cosmon-version <COSMON_VERSION> — Override cosmon_version in the commitment (defaults to the crate-level CARGO_PKG_VERSION). Mostly useful for tests

cs notarize verify

Verify an existing seal — full Ed25519 + canonical commitment bytes

Usage: cs notarize verify <PATH>

Arguments:

• <PATH> — Path to a seal JSON file (e.g. <mol_dir>/mint.json or theater/pitch-*/notary/slides.notarization.json)

cs witness

Witness — Layer-2 witness-quorum seal for stress-test molecules (ADR-085 §3)

Usage: cs witness <COMMAND>

EXAMPLES: cs witness attest # default prior path: <mol_dir>/prior.md cs witness attest --prior-path prior.md # explicit prior file cs witness attest --witness-id ci-bot # deterministic identity (LaunchAgent/CI) cs witness attest --json # NDJSON for scripting

Layer-2 witness-quorum seal for stress-test molecules (ADR-085 §3). A separate cosmon agent reads the prior file's bytes, computes its BLAKE3 hash, and emits a SealAttested event distinct from the molecule's tackler session. Refuses if the molecule's class is not stress-test, or if the witness identity matches the tackler's session_name (cheap structural-independence check).

SEE ALSO: cs notarize (operator Ed25519 attestation, ADR-056).

Subcommands:

• attest — Attest a stress-test molecule's prior seal — emit SealAttested

cs witness attest

Attest a stress-test molecule's prior seal — emit SealAttested

Usage: cs witness attest [OPTIONS] <MOLECULE_ID>

Arguments:

• <MOLECULE_ID> — Molecule ID (or prefix) to attest. Must be a stress-test class molecule (ADR-085 §1); standard-class molecules are refused so a witness cannot accidentally lend weight to a tactical deliberation

Options:

• --prior-path <PATH> — Path to the operator-sealed prior. Defaults to <molecule_dir>/prior.md. The witness opens this file, computes its BLAKE3 hash, and records that hash in the EventV2::SealAttested::prior_b3 field. The witness never inspects the file's content beyond the bytes-to-hash transformation.
• --witness-id <ID> — Override the witness identity. Defaults to the [cosmon_runtime::resolve_witness_id] heuristic ($TMUX first, then <host>-<pid>). Useful for LaunchAgent / CI invocations that want a deterministic identity

cs key

Key — manage the operator's Ed25519 notary key (generate, show)

Usage: cs key <COMMAND>

EXAMPLES: cs key generate # ~/.config/cosmon/operator.key (0600) cs key generate --output /tmp/dev.key # alternate destination cs key generate --force # overwrite an existing key cs key show # print pubkey hex of the default key

Generates a fresh Ed25519 secret (32 bytes of OS randomness, 64-char lowercase hex) at the path cs notarize --key already expects. Silent rotation is forbidden: without --force the command refuses to clobber an existing key file. For retirement / successor publication, see ADR-060 (cs rotate-key, deferred post-S4).

SEE ALSO: cs notarize (sign a molecule under the operator key), docs/guides/notary-operator-guide.md, ADR-056, ADR-060.

Subcommands:

• generate — Generate a fresh Ed25519 operator key (32 bytes OS randomness, hex-encoded)
• show — Print the public key (and its path) for an existing operator key file

cs key generate

Generate a fresh Ed25519 operator key (32 bytes OS randomness, hex-encoded)

Usage: cs key generate [OPTIONS]

Options:

• --output <PATH> — Destination path. Defaults to ~/.config/cosmon/operator.key
• --force — Overwrite an existing key file. Without this flag, refuses to clobber any pre-existing key — silent rotation is forbidden (ADR-060 §Alternatives-rejected)

cs key show

Print the public key (and its path) for an existing operator key file

Usage: cs key show [OPTIONS]

Options:

• --key <PATH> — Path to the operator key file. Defaults to ~/.config/cosmon/operator.key

Tools commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs pilot

Pilot — interactive cognitive pilot REPL over a client-side model (--experimental). --remote pilots an avatar over the §8p wire (ADR-115)

Usage: cs pilot [OPTIONS]

Options:

• --experimental — Enable the experimental verb. While the interactive loop matures, cs pilot without this flag prints a safety notice and does nothing — no REPL, no model call, no side effects (mirrors cs ask, ADR-071)
• --model <TAG> — Ollama model tag to drive the loop (default: llama3.2). Falls back to the COSMON_PILOT_MODEL environment variable when the flag is omitted
• --base-url <URL> — Override the model endpoint (default: the local Ollama OpenAI-compatible endpoint http://localhost:11434/v1). Falls back to COSMON_PILOT_BASE_URL when the flag is omitted
• --transcript <PATH> — Path the on-disk transcript is appended to (default: pilot-transcript.md in the current directory). Falls back to COSMON_PILOT_TRANSCRIPT when the flag is omitted
• --timeout <SECS> — Per-request timeout in seconds for each model round-trip (default: 300). The pilot defaults far above the provider's 60s library default because it injects the full repo CLAUDE.md (~36 KB) as bootstrap context, so a large local model (e.g. qwen2.5:32b) legitimately spends minutes on the first prefill. Falls back to COSMON_PILOT_TIMEOUT (also in seconds) when the flag is omitted
• --remote — Pilot a REMOTE avatar over the network instead of the local cosmon instance (ADR-115 §6). The model still runs client-side (this box); only cosmon operations cross the wire, via the avatar's cosmon-rpp-adapter §8p routes (ADR-080). Read-only unless --write
• --profile <NAME> — Which cosmon-remote profile to use in --remote mode (the avatar's host + JWT identity). Defaults to the configured default profile (~/.config/cosmon-remote/). Ignored without --remote
• --write — In --remote mode, expose the write tools (nucleate / tackle) in addition to the read tools. Off by default — a remote session sees the fleet but cannot change it unless asked. done / evolve are never available regardless (ADR-080 §5). Ignored without --remote

cs prime

Prime the system — load .cosmon/config.toml and self-check gates

Usage: cs prime [OPTIONS] [MOLECULE]

EXAMPLES: cs prime # load .cosmon/config.toml, report gates

Boot-time self-check. No network calls; verifies the local project is well-formed.

Arguments:

• <MOLECULE> — Molecule ID to prime (optional — auto-detects from running molecule)

Options:

• --hook — Check hook and prime if work is assigned

cs paths

Paths — project the write-path taxonomy (--writes), a pure derived view

Usage: cs paths [OPTIONS]

Options:

• --writes — Emit the set of paths cosmon writes under the state root.

  Currently the only projection mode; the flag is explicit so future projections (e.g. --reads) can be added without changing the default behaviour. Omitting it is equivalent to passing it.

cs archive

Archive — operator view over durable terminal snapshots (list/show/verify/prune, ADR-030)

Usage: cs archive <COMMAND>

EXAMPLES: cs archive list # every archived molecule, all months cs archive list --year 2026 # scoped to one year cs archive list --year 2026 --month 04 # scoped to one month cs archive list --json # NDJSON for scripting cs archive show # manifest + artifact inventory cs archive verify # recompute hashes (exit 1 if tampered) cs archive prune --dry-run # what retention policy would delete cs archive prune # execute the retention policy

Operator view onto .cosmon/state/archive/. Terminal transitions (cs done / cs collapse / cs freeze / cs stuck) populate the archive when [archive] enabled = true in the project config — the default since 2026-09; set enabled = false to opt out. Enabling is not retroactive. The archive outlives worktree teardown and branch deletion — a fresh clone sees every merged molecule's canonical snapshot. If entries never reach git status, run cs doctor gitignore.

Retention is controlled by [archive.retention] in config.toml: keep_all (default true) — safety switch; must be false to delete max_age_days (default 0) — 0 disables the age rule max_total_mb (default 0) — 0 disables the size rule keep_kinds (default decision, deliberation)

Hash-chain integrity is enforced: a molecule referenced as parent (DecayedFrom / BlockedBy / MergedFrom) by a kept entry is never deleted.

Subcommands:

• list — List archived molecules (optionally filtered by year / month)
• show — Show the manifest + artifact inventory for one archived molecule
• verify — Verify artifact hashes — exits non-zero if tampered
• prune — Apply the [archive.retention] policy; --dry-run shows the plan

cs archive list

List archived molecules (optionally filtered by year / month)

Usage: cs archive list [OPTIONS]

Options:

• --year <YYYY> — Restrict the scan to a single year (e.g. 2026)
• --month <MM> — Restrict the scan to a single month (01..=12). Must be used with --year to be meaningful; standalone --month still filters across whichever years contain that month
• --since-days <N> — Keep only entries whose directory was modified within the last N days. 0 means no limit. Combines with --year/--month. Used by the CI gate (.github/workflows/archive-verify.yml)
• --ids-only — Emit one molecule id per line, skipping the table header / JSON envelope. Intended for shell pipelines (xargs cs archive verify)

cs archive show

Show the manifest + artifact inventory for one archived molecule

Usage: cs archive show <MOLECULE>

Arguments:

• <MOLECULE> — Molecule id or unique prefix

cs archive verify

Verify artifact hashes — exits non-zero if tampered

Usage: cs archive verify <MOLECULE>

Arguments:

• <MOLECULE> — Molecule id or unique prefix

cs archive prune

Apply the [archive.retention] policy; --dry-run shows the plan

Usage: cs archive prune [OPTIONS]

Options:

• --dry-run — Show what would be deleted and exit — never touch disk

cs journal

Write down what you notice while you work; anything worth doing becomes a task without you stopping to file it

Usage: cs journal <COMMAND>

EXAMPLES: cs journal start # open a carnet cs journal start --galaxy example --root delib-example-0001 cs journal note "Torvalds elected path a" cs journal note --tag insight "the carnet is the primitive" cs journal note "!spark implémenter session-to-spark" # prefix auto-promotes cs journal end # seal with BLAKE3 + auto-commit cs journal end --no-seal # ephemeral scratch close

PROMOTE — turn journal notes into spark molecules: cs journal promote 10:46:55 # promote one note by timestamp cs journal promote 10:46:55 10:47:01 # promote several cs journal promote --all-spark-prefix # promote every !spark-prefixed note cs journal promote --dry-run # show what would be promoted cs journal promote --session session-2026-04-22T10-31-31Z 10:46:55

Notes beginning with !spark are automatically promoted by the session-to-spark LaunchAgent (when installed, fires every 5 min). Explicit cs journal promote <ts> works regardless of prefix and is idempotent — sidecar markers under .cosmon/state/journals/.promoted/ prevent duplicate sparks.

Exit codes: 2 a session is already open (on cs journal start) 3 no open session (on cs journal note / cs journal end)

Journals live under .cosmon/state/journals/ as append-only markdown files. The seal is a BLAKE3 hash of the body between the frontmatter and footer — a trace, not a lock (architectural-invariants.md §8b). Promotion never mutates a sealed journal — markers are sidecar-only.

Subcommands:

• start — Open a journal — every note you take lands in it until you end it
• note — Append a timestamped note to the open journal
• end — Close the open journal, optionally sealing it with BLAKE3
• promote — Turn journal notes into spark molecules (via the session-to-spark tick)
• route — Route journal notes through the Tier-1 regex classifier (ADR-072)
• review — Review router-staged molecules (verdict-door)

cs journal start

Open a journal — every note you take lands in it until you end it

Usage: cs journal start [OPTIONS]

Options:

• --galaxy <GALAXY> — Galaxy this session belongs to (free-form label)
• --root <MOL_ID> — Root molecule(s) this session is anchored on (repeatable)

cs journal note

Append a timestamped note to the open journal

Usage: cs journal note [OPTIONS] <TEXT>

Arguments:

• <TEXT> — Free-form note body

Options:

• --tag <TAG> — Optional tag rendered alongside the timestamp (e.g. insight, todo)
• --cause-kind <KIND> — How the note was produced. One of direct (human typed), transcription (human spoke, agent transcribed), oracle-suggestion (agent proposed, human accepted), autonomous (agent authored alone). Omit to skip the cause: subline entirely — the note renders in the pre-schema format. Supplying any --cause-* flag enables the subline with defaults kind=direct, agent=null, channel=keyboard
• --cause-agent <AGENT> — Identity of the mediating agent (e.g. apfel-oracle-<host>, matrix:@tenant_auditor:hs). Leave unset when --cause-kind direct
• --cause-channel <CHANNEL> — Physical channel the note arrived on. Known variants: keyboard, voice, matrix, webhook. Any other value is accepted verbatim and round-trips as Other(<value>)

cs journal end

Close the open journal, optionally sealing it with BLAKE3

Usage: cs journal end [OPTIONS]

Options:

• --no-seal — Skip the BLAKE3 seal — ephemeral scratch close. By default the session body is sealed (mirrors prompt_seal / briefing_seals)

cs journal promote

Turn journal notes into spark molecules (via the session-to-spark tick)

Usage: cs journal promote [OPTIONS] [NOTE_TIMESTAMPS]...

Arguments:

• <NOTE_TIMESTAMPS> — Note timestamp to promote (HH:MM:SS, optionally prefixed by <session_id>@ to disambiguate across sessions). Repeatable.

  When omitted, behaviour depends on --all-spark-prefix (default: on) and --dry-run.

Options:

• --session <SESSION> — Session file stem (e.g. session-2026-04-22T10-31-31Z) or an absolute path. Defaults to the currently open session; if no session is open, defaults to scanning every session file
• --all-spark-prefix — Promote every note whose body begins with !spark . Default behaviour when no explicit timestamps are passed; when timestamps ARE passed, this is additive (promote both the prefixed notes and the explicit ones)
• --dry-run — Print what would be promoted without nucleating or writing sidecars. Forwarded to the tick script
• --tick-script <PATH> — Override the tick script location. Defaults to walk-up discovery from $PWD looking for scripts/session-to-spark-tick.sh

cs journal route

Route journal notes through the Tier-1 regex classifier (ADR-072).

Walks a journal file, computes blake3(body) for each note, applies the Tier-1 cascade, writes a sidecar under .cosmon/state/journals/.route/<sid>/<body_hash>.json, and (when confidence warrants) nucleates a temp:proposed molecule via cs nucleate. Tiers 2–4 are future work; low-confidence notes are marked tier4_pending and escalate to the verdict-door.

Usage: cs journal route [OPTIONS] [SESSION]

Arguments:

• <SESSION> — Session file stem (e.g. session-2026-04-22T10-31-31Z) or an absolute path. When omitted, defaults to scanning every session file if --all is passed, or the currently-open session otherwise

Options:

• --all — Process every session file under .cosmon/state/journals/

• --dry-run — Print what would be classified without writing sidecars or nucleating molecules

• --no-stage — Skip auto-nucleation of high-confidence temp:proposed molecules — write sidecars only. Useful when backfilling or debugging

• --max <MAX> — Cap sidecars emitted this run (safety net for batch backfills)

  Default value: 500

cs journal review

Review router-staged molecules (verdict-door).

Renders temp:proposed molecules as a markdown review file at .cosmon/state/journals/.review/<sid>.md, opens it in $EDITOR, and — on --apply — translates each verdict: line into a keep / dismiss / undo transition. Silent when nothing is pending (no editor opens). See ADR-072 §7.

Usage: cs journal review [OPTIONS] [SESSION]

Arguments:

• <SESSION> — Session id (e.g. session-2026-04-22T10-31-31Z). When omitted, review every session that has pending staged molecules

Options:

• --apply — Parse the previously-composed review file and apply the verdicts. Without this flag, the verb composes the markdown review file and opens it in $EDITOR
• --editor <CMD> — Override the editor (defaults to $EDITOR, then vi). Ignored with --apply and with --json

cs sessions

Two agent sessions — a Claude and a Codex, or two of either — work the same mission on this machine. One holds the controls and may change the mission; the other reads the same material, compares, and advises, and can change nothing. Both see each other, can write to each other, and leave a hand-over note when they stop, so the next session resumes without re-reading the whole conversation.

Passing the controls is never automatic. A session may ASK for them; only you, the human, hand them over, by signing the request with your key. No quota, timeout or heuristic moves them.

The verbs come in the order you meet them: find a session (discover, show), take a seat (attach, list, peers), talk (send, inbox), hand over (checkpoint, drift, takeover). hook wires the routine ones into the agent itself, so they happen without being typed.

Both seats are live sessions of the SAME mission, and only a human signature moves the controls between them. For separate molecules — each with its own lifecycle, visible in cs peek and harvested on its own — exchanging bounded findings instead, see cs work (ADR-182).

Usage: cs sessions <COMMAND>

EXAMPLES: cs sessions discover # provider sessions in this repo cs sessions discover --all --provider codex # every Codex session on the host cs sessions show claude:4940f28e --tail 5 # one session, named exactly cs sessions attach --role copilot --follow claude-sid
--as codex:0198aabb --capability observe cs sessions list --role primary # who holds a seat cs sessions peers # who is around me, and which way cs sessions send --to claude-sid --message 'that evidence ref is circular' cs sessions inbox # read and consume; --peek to look

HAND-OVER: cs sessions checkpoint publish --mission task-20260731-e4d0
--include 'the cockpit' --exclude 'the probe'
--next 'merge-strategy:deny=do not merge before the doc gate'
--evidence 'merge-strategy=docs/adr/168.md' cs sessions checkpoint list --mission task-20260731-e4d0 cs sessions drift claude-sid codex-sid --mission task-20260731-e4d0 cs sessions takeover show --mission task-20260731-e4d0 cs sessions takeover trust # which key may seat a pilot cs sessions takeover request --mission task-20260731-e4d0 --reason 'quota'

THE OPERATOR GESTURE (the part an agent cannot type for itself): cs sessions takeover challenge --mission task-20260731-e4d0 --request req-… --by emmanuel > takeover.txt minisign -Sm takeover.txt # your passphrase, your gesture cs sessions takeover grant --mission task-20260731-e4d0 --request req-… --by emmanuel --attestation takeover.txt.minisig

--by is a label; the signature is the authority. A grant with no valid attestation seats nobody — including one appended straight into the ledger, because every line is checked when it is read. Pin the public key at .cosmon/takeover.pub and commit it, so a swapped trust root is a diff.

WITHOUT TYPING ANYTHING (the hook, mission M6): cs sessions hook install --provider claude # .claude/settings.local.json cs sessions hook install --provider codex # ~/.codex/config.toml notify cs sessions hook status # wired? and what has it cost cs sessions checkpoint stage --mission task-20260731-0d49
--next 'gate:affirm=run just gates before done' cs sessions hook uninstall --provider claude # leaves no residue COSMON_COPILOT_HOOK_OFF=1 # quiet now, still wired

The hook pings presence, drains the mailbox where the pilot can read it and publishes a staged checkpoint at a transition. It never claims a seat and never writes a checkpoint's content: a hand-over record is the pilot's own words, and only its moment is the hook's.

The canonical name of a session is <provider>:<native-session-id>, and nothing else ever breaks a tie: a title, a cwd and a modification time help you recognise a session, never choose one. A selector that matches zero or two sessions prints the candidates and refuses.

Exit codes (drift, matching cs diverge): 0 AGREE — the compared positions match 1 FINDING — a decidable test fired, both sides cited 2 INCONCLUSIVE — not comparable; never rendered as agreement

Authority is a lease with an epoch (ADR-168 §D6). A co-pilot may observe, message and checkpoint; only the operator grants the controls, and no quota reading transfers them.

SEE ALSO: cs presence (the substrate), cs journal (operator carnet), cs pilot (cognitive REPL), cs diverge.

Subcommands:

• discover — Which agent conversations exist on this machine, and the exact name to refer to one by
• list — Which of them have taken a seat, and in which role
• show — Look inside one conversation — its last events, read-only
• attach — Take a seat: say "I am here, in this role". Until you do, the others cannot see you
• peers — Who is seated around this session, and which way each one faces
• send — Write one message to another session. Delivered, and consumed, once
• inbox — Read the messages addressed to this session (--peek to look without consuming them)
• checkpoint — Leave — or read — the note that lets someone else resume this mission
• drift — Compare what two sessions concluded — AGREE, FINDING or INCONCLUSIVE, never a score
• takeover — The controls: who may change the mission, who asked for them, and the signature that hands them over
• hook — Wire the routine gestures — take a seat, read the mailbox, leave a note — into the agent itself, so they happen without being typed

cs sessions discover

Which agent conversations exist on this machine, and the exact name to refer to one by

Usage: cs sessions discover [OPTIONS]

Options:

• --repo <PATH> — Repository whose sessions to show. Defaults to the repository the current directory is in. Resolved to an exact checkout — a worktree is never its canonical checkout (REPO-EXACT)
• --cwd <PATH> — Show sessions whose recorded working directory is exactly this path
• --all — Show every session every adapter can see, from any repository
• --provider <NAME> — Restrict to one provider (claude, codex, …)

cs sessions list

Which of them have taken a seat, and in which role

Usage: cs sessions list [OPTIONS]

Options:

• --galaxy <GALAXY> — Filter to one galaxy
• --role <ROLE> — Show only pilots in this seat (primary or copilot)
• --follows <SID> — Show only pilots co-piloting this session
• --all — Include snapshots whose heartbeat has gone stale

cs sessions show

Look inside one conversation — its last events, read-only

Usage: cs sessions show [OPTIONS] <SELECTOR>

Arguments:

• <SELECTOR> — The canonical selector, <provider>:<native-session-id>

Options:

• --tail <N> — Print the last N normalised events (kinds and sizes — never content)

  Default value: 0

• --no-read — Skip reading the log; show only what discovery already knows

cs sessions attach

Take a seat: say "I am here, in this role". Until you do, the others cannot see you

Usage: cs sessions attach [OPTIONS]

Options:

• --role <ROLE> — Seat to take: copilot (default) or primary. A primary seat is checked against the mission's lease ledger and refused if it is not this session's to take

  Default value: copilot

• --follow <SID_OR_SELECTOR> — The pilot this session is co-piloting — a cosmon session id, or a <provider>:<native-session-id> selector that a live pilot advertises

• --session <SID> — This session's cosmon id. Defaults to $COSMON_SESSION_ID

• --as <SELECTOR> — The provider session this pilot is driving, as a canonical selector. Equivalent to --provider + --native-session-id

• --provider <NAME> — Provider half of this session's key, when not using --as

• --native-session-id <ID> — Native id half of this session's key, when not using --as

• --mission <MOLECULE_ID> — Mission this seat is about. Required for a primary seat

• --epoch <N> — The lease epoch this pilot believes it holds. Required for a primary seat: a claim that names no generation is not a claim

• --capability <TOKEN> — A capability this pilot advertises. Repeatable

• --headline <HEADLINE> — One line describing what this pilot is doing

• --galaxy <GALAXY> — Galaxy label to record

  Default value: cosmon

cs sessions peers

Who is seated around this session, and which way each one faces

Usage: cs sessions peers [OPTIONS]

Options:

• --session <SID> — The session whose neighbourhood to show. Defaults to $COSMON_SESSION_ID
• --all — Include snapshots whose heartbeat has gone stale

cs sessions send

Write one message to another session. Delivered, and consumed, once

Usage: cs sessions send [OPTIONS] --to <SID_OR_SELECTOR> --message <TEXT>

Options:

• --to <SID_OR_SELECTOR> — Destination — a cosmon session id, or a selector a live pilot advertises
• --message <TEXT> — The message. Stored content-addressed; the envelope carries its hash
• --from <SID> — Sender session id. Defaults to $COSMON_SESSION_ID
• --expires-in <SECONDS> — Seconds after which an unread envelope reads as expired rather than as a fresh instruction

cs sessions inbox

Read the messages addressed to this session (--peek to look without consuming them)

Usage: cs sessions inbox [OPTIONS]

Options:

• --session <SID> — Mailbox to read. Defaults to $COSMON_SESSION_ID

• --peek — Show pending envelopes without acknowledging them

• --all — Include already-acknowledged envelopes

• --follow — Keep reading, printing each envelope as it arrives, until interrupted

• --interval <SECONDS> — Seconds between polls under --follow

  Default value: 2

cs sessions checkpoint

Leave — or read — the note that lets someone else resume this mission

Usage: cs sessions checkpoint <COMMAND>

Subcommands:

• publish — Publish this pilot's hand-over record for a mission
• stage — Write the same record as a draft, for the hook to publish at the next natural transition. Takes exactly the flags publish takes
• list — List the checkpoints published for a mission
• show — Show one checkpoint in full

cs sessions checkpoint publish

Publish this pilot's hand-over record for a mission

Usage: cs sessions checkpoint publish [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — The mission being flown
• --session <SID> — Publishing session. Defaults to $COSMON_SESSION_ID
• --epoch <N> — The authority epoch the publisher believes it is under. Defaults to the epoch on its own presence snapshot, then to 0
• --id <ID> — Identifier for this checkpoint. Defaults to a timestamped id
• --include <TEXT> — Something this mission covers. Repeatable
• --exclude <TEXT> — Something this mission explicitly does not cover. Repeatable
• --hypothesis <CLAIM> — A position currently held, as SUBJECT[:affirm|deny]=STATEMENT. Repeatable
• --next <CLAIM> — An intended next move, in the same SUBJECT[:STANCE]=STATEMENT form. Repeatable — this is the list a co-pilot's contradiction is found in
• --done <TEXT> — Something already done, in the pilot's words. Repeatable
• --risk <TEXT> — A known risk. Repeatable
• --question <TEXT> — A question the pilot could not answer. Repeatable — this is where uncertainty belongs, never inside a stance
• --evidence <SUBJECT=LOCATOR> — Evidence for one claim, as SUBJECT=LOCATOR[#DIGEST]. Repeatable
• --checkpoint-evidence <LOCATOR> — Evidence for the checkpoint as a whole, as LOCATOR[#DIGEST]. Repeatable

cs sessions checkpoint stage

Write the same record as a draft, for the hook to publish at the next natural transition. Takes exactly the flags publish takes

Usage: cs sessions checkpoint stage [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — The mission being flown
• --session <SID> — Publishing session. Defaults to $COSMON_SESSION_ID
• --epoch <N> — The authority epoch the publisher believes it is under. Defaults to the epoch on its own presence snapshot, then to 0
• --id <ID> — Identifier for this checkpoint. Defaults to a timestamped id
• --include <TEXT> — Something this mission covers. Repeatable
• --exclude <TEXT> — Something this mission explicitly does not cover. Repeatable
• --hypothesis <CLAIM> — A position currently held, as SUBJECT[:affirm|deny]=STATEMENT. Repeatable
• --next <CLAIM> — An intended next move, in the same SUBJECT[:STANCE]=STATEMENT form. Repeatable — this is the list a co-pilot's contradiction is found in
• --done <TEXT> — Something already done, in the pilot's words. Repeatable
• --risk <TEXT> — A known risk. Repeatable
• --question <TEXT> — A question the pilot could not answer. Repeatable — this is where uncertainty belongs, never inside a stance
• --evidence <SUBJECT=LOCATOR> — Evidence for one claim, as SUBJECT=LOCATOR[#DIGEST]. Repeatable
• --checkpoint-evidence <LOCATOR> — Evidence for the checkpoint as a whole, as LOCATOR[#DIGEST]. Repeatable

cs sessions checkpoint list

List the checkpoints published for a mission

Usage: cs sessions checkpoint list [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — The mission whose checkpoints to list
• --session <SID> — Show only what this session published

cs sessions checkpoint show

Show one checkpoint in full

Usage: cs sessions checkpoint show [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — The mission the checkpoint belongs to
• --id <ID> — The checkpoint id. Omit to take the latest published by --session
• --session <SID> — The publishing session, when selecting by recency rather than by id

cs sessions drift

Compare what two sessions concluded — AGREE, FINDING or INCONCLUSIVE, never a score

Usage: cs sessions drift [OPTIONS] --mission <MOLECULE_ID> <SESSION_A> <SESSION_B>

Arguments:

• <SESSION_A> — The first session
• <SESSION_B> — The second session

Options:

• --mission <MOLECULE_ID> — The mission both sides checkpointed

• --checkpoint <latest> — Which checkpoint of each session to compare. Only latest is a selector; name an exact record with --checkpoint-a / --checkpoint-b

  Default value: latest

• --checkpoint-a <ID> — Exact checkpoint id for side A

• --checkpoint-b <ID> — Exact checkpoint id for side B

cs sessions takeover

The controls: who may change the mission, who asked for them, and the signature that hands them over

Usage: cs sessions takeover <COMMAND>

Subcommands:

• show — Who holds the controls, at which epoch, and what has been asked
• request — Ask for the controls. Writes a request and confers nothing
• grant — Hand the controls over — your signature, which no agent can produce
• challenge — Print the exact bytes an operator signs to authorise one transfer
• trust — Show which operator key this galaxy trusts to authorise a transfer
• check — Ask whether a session may pilot: the ledger's verdict, plus whether its seat would actually present that epoch. Exits 0 or 1

cs sessions takeover show

Who holds the controls, at which epoch, and what has been asked

Usage: cs sessions takeover show [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — Mission whose lease to inspect
• --history — Print every grant ever recorded instead of only the head

cs sessions takeover request

Ask for the controls. Writes a request and confers nothing

Usage: cs sessions takeover request [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — Mission the controls are being asked for

• --to <SID> — Session that would become PRIMARY. Defaults to the requester

• --from <SID> — Session doing the asking. Defaults to $COSMON_SESSION_ID

• --reason <TEXT> — One line the operator reads before deciding

  Default value: ``

cs sessions takeover grant

Hand the controls over — your signature, which no agent can produce

Usage: cs sessions takeover grant [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — Mission whose controls are being handed over
• --request <REQUEST_ID> — Request being answered. The holder is taken from the request
• --to <SID> — Session to seat, when granting without a request
• --ttl <SECONDS> — Seconds after which the lease authorises nothing
• --by <NAME> — Operator identity to record. Defaults to $USER. Covered by the attestation, so it is a signed claim and not a free string
• --attestation <PATH> — The operator's detached minisign signature over the challenge, or - for stdin. Required: --by is a label, the signature is the gesture
• --sign-with <PATH> — The operator's minisign secret key. Folds challenge, signature and grant into this one command: the transfer is printed for you to read, minisign(1) asks for your passphrase, and no .minisig is left behind. cosmon still owns no signer — it relays to yours

cs sessions takeover challenge

Print the exact bytes an operator signs to authorise one transfer

Usage: cs sessions takeover challenge [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — Mission whose controls would be handed over
• --request <REQUEST_ID> — Request being answered. The holder is taken from the request
• --to <SID> — Session that would be seated, when there is no request to answer
• --ttl <SECONDS> — Seconds after which the lease would authorise nothing
• --by <NAME> — Operator identity the grant would claim. Defaults to $USER

cs sessions takeover trust

Show which operator key this galaxy trusts to authorise a transfer

Usage: cs sessions takeover trust

cs sessions takeover check

Ask whether a session may pilot: the ledger's verdict, plus whether its seat would actually present that epoch. Exits 0 or 1

Usage: cs sessions takeover check [OPTIONS] --mission <MOLECULE_ID>

Options:

• --mission <MOLECULE_ID> — Mission the gesture would touch
• --session <SID> — Session issuing the gesture. Defaults to $COSMON_SESSION_ID
• --epoch <N> — The epoch the caller believes it holds. Omitting it is itself a refusal

cs sessions hook

Wire the routine gestures — take a seat, read the mailbox, leave a note — into the agent itself, so they happen without being typed

Usage: cs sessions hook <COMMAND>

Subcommands:

• install — Wire this pilot's provider to run the co-pilotage hook
• uninstall — Remove the co-pilotage hook, leaving the rest of the file untouched
• status — Report whether the hook is wired, and what it has cost
• run — The hook body — invoked by the provider, not usually by a human