saphan channel

Inspects and repairs the channel documents of a stream: the orders, status reports and review notes exchanged between Saphan Studio and the agents working on it, kept in the channel store. The store is append-only, so a document that lands there is never edited afterwards. Most documents are written automatically by saphan run and saphan return; the subcommands here list them, count them, and land the few that a person writes or that an outage kept out of the store.

saphan channel backfill

Lands the channel documents a finished stream's teardown archived but the store does not hold, so saphan teardown can proceed. It reads only the stream's own archive under the workspace, checks every file against the archive's checksum manifest, and refuses the whole act on any mismatch. A backfilled document is marked as such and never reads as a returned one. Prefix with saphan dry-run to see what would land without writing anything.

saphan channel backfill --stream <slug>

saphan channel census

Counts, for each kind of channel document, whether anything writes it, how many documents exist, how many of them carry a valid signature this machine can verify, and how many of the documents found in worktrees on disk also reached the store. Every unreadable document is listed by id with the reason. A second table shows, per store bucket and write method, whether anything in this build writes it.

saphan channel census

saphan channel close

Closes the channel of an executor whose process has died, so the stream is no longer shown as running. The check and the closing write to the executor's status file are made on the host that ran it: a process that is still alive is refused, and so is a host that cannot be reached, since neither proves the process is gone. A stream with no running entry in the run record, or more than one, is refused.

saphan channel close <stream>

saphan channel ls

Lists the channel documents stored for one stream.

saphan channel ls <stream>

saphan channel put

Lands a hand-written document in the channel store: a train order (train-order, a plan spanning several streams), a coordinator's order for one stream (master-order) or a verification note (master-verify, which needs --round). Documents of a kind that has a grammar are checked in full first, and a malformed one is refused with the first error and the smallest document that would pass. Kinds Saphan Studio writes itself are refused, naming the command that writes them. Re-running with identical content is harmless.

saphan channel put --stream payments-refactor --kind master-verify --round 2 VERIFY.md

saphan channel put --stream <slug> --kind <doc-type> [--round <N>] <path>

saphan channel recover

Lands channel documents that exist in a stream's worktree but never reached the store, for example because the store was unreachable when the round ran, so the stream can move again. It reads only the stream's own worktree; you choose the stream, never a path. Each recovered document carries a mark stating only that these bytes were in the worktree when read. A later saphan return will accept a recovered order, but a gate will not accept a recovered review verdict.

saphan channel recover --stream <slug>

Global options apply to every command — see Every command.