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 |
|---|---|---|---|
--effort | string | The effort level this leg runs at; overrides the order's - effort: line and the configured default for the role and backend. | |
--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 queue
Holds ready orders until a seat can take them: the engine places the highest-priority, oldest entry when a seat admits it, and messages the seat that queued it when the run starts and when it ends. Each entry is checked again just before it is placed (the order is unchanged, still signed and its base is still on the trunk); entries are marked, never deleted, and a stream with a live run keeps its next entry waiting until that run ends. Run it with a subcommand.
saphan dispatch queue cancel
Cancels a queued entry so it is never placed; an entry that is already being placed cannot be cancelled.
saphan dispatch queue drain
Runs one step of the queue: places the head entry if a seat admits it, and sends the start and end notices. saphan serverd does this on every tick; on a host that does not run it, call this regularly from any watcher. It never waits for a seat.
saphan dispatch queue enqueue
Puts one ready order on the dispatch queue; this is the coordinating agent's explicit act.
| flag | type | default | what it does |
|---|---|---|---|
--deadline | string | An RFC 3339 time after which an entry still waiting is marked expired and the seat that queued it is told. | |
--not-before | string | An RFC 3339 time before which the entry is not placed. | |
--order | string | The order to place (required). | |
--priority | int | 0 | Higher numbers are placed first and ties go to the oldest entry; a value below 0 lets the entry wait for an account whose weekly limit resets soon. |
--reviewed | string | The stream a review covers; required with --role review. | |
--role | string | executor or review (required). |
saphan dispatch queue list
Lists the queue's entries in the order they would be placed.
| flag | type | default | what it does |
|---|---|---|---|
--all | bool | false | Also list cancelled, refused and expired entries. |
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.