saphan teardown
Archives a finished stream's channel files and records the teardown decision, the owner's recorded act that the stream's worktree may be removed.
Archives a finished stream's channel files and records the teardown decision, the owner's recorded act that the stream's worktree may be removed. The channel files (the order and status files at the worktree's root) are copied to .saphan/work/<stream>/channel-archive/ and verified against a generated SHA-256 manifest first; if archiving fails, nothing is recorded. Running it again with --verify-archive re-checks the archive and removes the worktree, on a remote (ssh) host too after bringing that host's leftovers home; such a removal is logged on the event log as a repair-path entry, readable with saphan bus events. Rehearse both acts with saphan dry-run teardown <stream> (add --verify-archive for the removal), which archives, records and removes nothing.
The decision is refused unless the stream is merged or closed without a merge, the worktree holds no untracked files outside the ignored ones, and every declared return has a disposition. ⚠ Both the decision and the removal are owner acts: each prints a one-time code on this terminal and waits for you to type it back. It is refused when no terminal is attached (for example from a script or a CI job), and in the console's browser terminal it is refused in favour of the console's passkey prompt.
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | The person performing the teardown; defaults to SAPHAN_ACTOR, then your configured identity.actor. The engine itself is never accepted as the actor. It must name an enrolled, active actor in this workspace's signed actor registry; a spelling that differs only in case or spacing is refused, not corrected. | |
--admit-pre-identity | bool | false | ⚠ Owner act: record a signed exception for an unsigned teardown decision, which only a workspace created by an earlier version holds, so its removal can proceed. It asks for the one-time terminal code, requires the workspace key, is reported as admitted by recorded exception rather than verified, removes nothing itself, and cannot be combined with --verify-archive. |
--note | string | A free-form audit note stored with the decision; names and references only, never secrets. | |
--provisioned-from | stringArray | Repeatable <dest>=<absolute path>: a known-good copy of a file provisioned into the run, for when neither the archive nor the repository history still holds it; it must hash-match the run record. Usually unnecessary. | |
--return | stringArray | Repeatable <manifest-file>=<disposition>: how each declared return was handled — landed, landed:<path> (hash-checked against the worktree's copy), consumed or discarded-by-decision; a bare landed is recorded as an unverified claim. When the worktree is already gone or is on a remote host, landed:<path> cannot be hash-checked: the local path must exist, and the claim is recorded as uncorroborated. | |
--round | stringArray | Repeatable, removal only: the run id of each remote place to remove, in order; required when the stream ran in more than one remote place. List the ids with saphan cost <stream>. | |
--verify-archive | bool | false | Perform the removal: refuses unless the teardown decision is recorded and every archived byte still matches its manifest, then removes the stream's worktree, locally or over ssh, and reports what is actually left at the path. ⚠ The removal is forced and cannot be undone: it uses git worktree remove --force and, if git refuses, deletes the directory from the filesystem, so anything in the worktree that was not archived is lost. On a remote host it also deletes the stream's incoming refs in that host's repositories. |
saphan teardown adoption
Handles channel archives whose teardown manifest carries no archive marker, which only a workspace created by an earlier version holds; the removal refuses such archives. An adoption is the owner's recorded approval to treat one of them as if its writer had stamped it, and it never removes anything. Run plan, read the file it writes, then approve it.
saphan teardown adoption approve
Adopts every archive in a batch file generated by saphan teardown adoption plan, behind one owner confirmation: it prints a one-time code on this terminal, on a screen that names the rows, and waits for you to type it back. Before asking anything it validates the whole file and re-measures each archive on disk, refusing by name any row whose facts changed or whose archive already carries a marker; the adoption is signed, permanent, and read only by saphan teardown <stream> --verify-archive. Rehearse it with saphan dry-run teardown adoption approve <manifest.json>.
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | The person approving; defaults to SAPHAN_ACTOR, then identity.actor. |
saphan teardown adoption plan
Walks this workspace's channel archives and writes one row for each archive without the archive marker, which are the ones the removal refuses. It asks nothing, signs nothing, opens no store and removes nothing. Check scope.counts.walked in the output: zero eligible out of zero walked means the walk found nothing, not that the workspace is clean.
| flag | type | default | what it does |
|---|---|---|---|
--include-excluded | bool | false | Also list the archives the batch does not adopt, each with the reason, so the counts can be audited. |
--out | string | Absolute path to write the batch to; without it the batch goes to standard output under --json, and a readable summary otherwise. |
saphan teardown batch
Tears down many streams from one JSON file holding a rows array, each row with its own stream, returns, provisioned files, rounds and note, behind a single owner confirmation: it prints a one-time code on this terminal, on a screen that names every row and both of its acts, and waits for you to type it back. It is refused when no terminal is attached (for example from a script or a CI job), and in the console's browser terminal it is refused in favour of the console's passkey prompt. ⚠ Every row's worktree is removed with the same forced, irreversible removal as --verify-archive. Every row is validated before any runs; each then runs both acts — archive and decision, then removal — exactly as the single command does, and a refused row is reported by name while the batch continues. Under --json the summary is the last JSON document on standard output, because the removal step prints text; rehearse with saphan dry-run teardown batch <rows.json>.
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | The person performing the batch; defaults to SAPHAN_ACTOR, then identity.actor. |
Global options apply to every command — see Every command.