saphan dispatch
Prepares work for an agent: on its own it renders an executor brief from a dispatch template and refuses the brief if it breaks any of the five dispatch rules.
Prepares work for an agent: on its own it renders an executor brief from a dispatch template and refuses the brief if it breaks any of the five dispatch rules. Its subcommands check whether an order can be dispatched, compose the saphan run command for a stream, place a leg on the fleet, and print order templates. A leg is one agent run on one stream.
The five rules are: a role-lock preamble, a heading that is the bare stream slug, a clause forbidding work on other streams, a one-session-one-task marking with a close-signal section, and an absolute worktree path. A brief that fails any of them is not written; the command exits 2 naming the failed rules. --slug, --task and --template are required, and exactly one of --continuation or --fresh.
| flag | type | default | what it does |
|---|---|---|---|
--anchor | stringArray | A verified reference line to include in the brief; repeatable. | |
--base | string | The base branch or ref the worktree was forked from. | |
--branch | string | The work branch; defaults to feature/<slug>. | |
--commit-tag | string | The tag used in the brief's commit-message format; defaults to the slug. | |
--continuation | bool | false | Mark the brief as a fix to a live stream, to be pasted into that stream's existing session. |
--fresh | bool | false | Mark the brief as a new change off the base branch, in a fresh worktree and branch. |
--out | string | Write the brief to this file instead of standard output. | |
--repo | string | The code repository the worktree checks out. | |
--slug | string | The stream slug, in kebab-case; it is also the brief's heading and file name. | |
--task | string | The task's scope, in one line. | |
--template | string | The path to the dispatch-template manifest. | |
--worktrees-dir | string | The worktrees directory under the workspace root; defaults to SAPHAN_WORKTREES_DIR, then worktrees/. A project-configuration setting for it is not read yet. |
saphan dispatch check
Reads one order and evaluates every dispatch precondition in one pass, printing one line per check: pass, refused (with the rule that refused), unmeasured (with the reason), or not applicable. It only reports: nothing is started, reserved or relaxed, and each check uses the same test the real dispatch uses. ⚠ An all-pass list is not a guarantee: conditions can change between the check and the dispatch, and an unmeasured check is never a pass.
| flag | type | default | what it does |
|---|---|---|---|
--cost-estimate-usd | float64 | 0 | The declared cost quote, which the order's - cap-usd: must be twice; if omitted, that check reads unmeasured. |
--grant-class | string | A permission class that replaces the configured grant for this dispatch. | |
--identity | string | The seat identity on --machine; may be omitted only when the machine has exactly one seat. | |
--machine | string | The admitted machine the dispatch would run on; if omitted, every machine-dependent check reads unmeasured. | |
--model | string | The model the dispatch would use. | |
--no-dial | bool | false | Do not contact the execution host; the checks that need it then read unmeasured. |
--order | string | The path to the order the dispatch would carry; required. | |
--provision | stringArray | An extra <source>=<dest> file to provision into the run, judged alongside the configured grant; repeatable. | |
--role | string | The role the dispatch would declare (master, executor, review, design, scribe or advisor); defaults to the seat's registered role. | |
--wall-clock | string | 90m | The wall-clock limit to check against the backend's minimum; defaults to the order's - wall:, else 90m. A value given here overrides the order. |
--worktrees-dir | string | The worktrees directory under the workspace root, used to compute the sandbox boundary. |
saphan dispatch command
Composes the complete saphan run command for one stream from the record and prints it for the owner to paste; nothing is started. You supply the stream, order, machine, seat, model, role, permission class and cost quote; the backend, binary, environment, working directory and budget (twice the quote) are derived. For a machine reached over ssh it first checks the remote home, seat profile, binary and working directory, and any missing one is refused with the command that fixes it.
| flag | type | default | what it does |
|---|---|---|---|
--cost-estimate-usd | float64 | 0 | The declared cost quote for the run; the budget cap is set to twice this value. Required. |
--effort | string | The reasoning effort to request; if omitted, the composed command carries none. | |
--egress-policy | bool | false | Judge the run by your own egress policy document (<state dir>/egress/policy.json), which replaces the backend's baseline; the run is refused before it starts if the file is missing or invalid, or the machine cannot enforce it. |
--force-usage-reading | bool | false | Adds --force-usage-reading to the composed command, overriding the refusal for a seat whose latest usage reading shows its plan window spent while another seat has capacity; a missing reading is never refused. Nothing checks who passes it; the override and the actor are written on the run record. |
--grant-class | string | A permission class that replaces the configured grant for this dispatch, rather than adding to it; a relative path resolves from the workspace. | |
--identity | string | The seat identity on --machine; may be omitted only when the machine has exactly one seat. | |
--machine | string | The admitted machine the run will use; required. auto picks the first seat that may dispatch for the role, as a preview only — nothing is reserved until the command is run. | |
--model | string | The model for the run; may be omitted when the role has a configured default model for the seat's backend. | |
--no-preflight | bool | false | Do not check the remote machine first; the output says plainly that the host was not checked. |
--no-recording | bool | false | Run without session recording; the run record still states that it was not recorded, why and by whom, and a run the guardrail judges is recorded anyway. |
--order | string | The path to the stream's order; defaults to the role's order file in the worktree. | |
--profile | string | execute | The capability profile of the run, plan or execute; defaults to execute. |
--provision | stringArray | An extra <source>=<dest> file to provision into the run, added to the configured grant; repeatable. | |
--remote-workdir | string | The absolute working directory on the remote machine, overriding the one derived from the machine's registered layout; ssh machines only. | |
--review-topology | string | Where the review runs relative to the reviewed stream, direct or courier; required with --role review and refused otherwise. | |
--reviewed | string | The stream a review run reviews; required with --role review and refused otherwise. | |
--role | role | The role whose configured dispatch defaults apply (master, executor, review, design, scribe or advisor). | |
--slot | int | 0 | The slot index to state explicitly; if omitted, saphan run derives it from the seat. |
--stream | string | The stream slug to dispatch; required. | |
--wall-clock | string | 90m | The wall-clock limit of the run; defaults to the order's - wall:, else 90m. A value given here overrides the order, and a limit that is too tight produces false timeouts. |
saphan dispatch place
Places one leg from its order in a single command: checks the order and the files it provisions, picks the first seat that admits it, registers the stream (cutting the worktree for a local seat), starts the run in the background, and waits until the run passes or fails its preflight. It exits 0 when the leg started and non-zero with the refusal otherwise. A refused seat is retried on the next admissible seat or stopped, according to the refusal; every attempt is printed. The order, and every file it provisions, must be committed in its repository, and a stream that already has a live run is refused. ⚠ It starts a billed run without asking for any confirmation.
With --role review and --reviewed naming the stream, it places a review of that stream on its own review branch. Without --wait it returns when the review starts, which says nothing about its verdict.
| flag | type | default | what it does |
|---|---|---|---|
--host | string | Use only the seats on this one machine; a continuation otherwise goes to the machine of its newest remote run. | |
--max-seats | int | 0 | Try at most this many seats; 0, the default, tries every admissible seat. |
--order | string | The path to the leg's order; required, and the only input. | |
--reviewed | string | The stream a review covers; required with --role review and refused otherwise. | |
--role | string | executor or review; required. | |
--wait | duration | 0s | When no seat is free and every refusal is retryable, keep trying for up to this long (for example 30m); for a review, also wait for it to finish and read its verdict. |
saphan dispatch template
Prints the order template for a role (executor, review or tester), read from the workspace's bridge/governance/templates/ORDER_<ROLE>.md when the command runs. A template the workspace does not hold is refused, naming the path that was read.
Global options apply to every command — see Every command.