saphan run

saphan run

Spawn one mandated run through the engine's spawn door (runner-v1; operator verb)

saphan run [flags]

Spawn a process under mandate and record the run: one door for agent sessions and arbitrary executables alike — one mandate enforcement, one transcript discipline, one cost ledger, one identity seam.

Backends (CONTRACT_runner.md §5, PLAN_OPENAI_COMPAT.md, PLAN_agent-loop_v0): proc (substrate — any executable), claude-code (headless Claude Code CLI), codex (headless Codex CLI), openai-compat (in-process HTTP to a local craftsman speaking the OpenAI chat-completions dialect — LiteLLM proxy, or Ollama/vLLM directly; --base-url replaces --binary, which this backend does not use), agent-loop ('saphan-agent loop' — our own tool-calling agent loop, no vendor binary on its critical path; --lane names the config-ladder alias whose credential it resolves on ITS OWN execution host, --max-tokens/ --max-iterations/--inner-budget mirror its own flags). The model is mandatory for LLM backends and set by the runner, never left to session defaults; effort is enforced where the backend exposes it and its absence is recorded, never silently defaulted (agent-loop exposes no wire field for it at all, same class as openai-compat).

Refusals R1–R7 are RECORDED RunRecords (exit 3), never fallbacks: a plan-profile dispatch to a backend without two-pass refuses (R1, including openai-compat — chat completions are stateless); ephemeral modes are illegal for two-pass (R2); a resume targets the recorded session key only (R3, openai-compat has none to target); a missing model or a pinned-digest mismatch refuses (R4); bypass flags are outside the mandate vocabulary (R5); an effort-strict mandate refuses on codex until probe P4 lands, and always on openai-compat, which has no wire field for effort (R6); write access outside the workdir without a signed disposition refuses (R7, adr-0020); a --config permission class's commands.allow, present only for proc, refuses a binary+argv it does not list (R9) — a class only NARROWS what proc could already do, it never grants (T1 deny-by-default; internal/permissions). A schema-v2 class's Path/EnvMint is not R9's proc-only narrowing: it mints PATH and any declared env_mint into EVERY backend's composed environment, uniformly (spawn-capability-reach §1, adapter.go's compose() chokepoint).

--laws names the standing-law index every LLM spawn must deliver to the head (headless-law-injection L0): a headless dispatch fires no SessionStart hook of its own, so the engine reads the file FRESH at every spawn — including every resume — inlines it into the prompt, and records its SHA-256. A file that is missing, unreadable, not a regular file, or ZERO BYTES refuses R12 (recorded, exit 3, no process spawned): a head that cannot be handed its laws is not dispatched at all — an empty floor is not a floor. An OMITTED --laws on an LLM backend is a malformation (exit 1, the same class as an omitted brief), not a refusal; --laws on proc is unrepresentable (there is no head to bind).

Spawn authority (order §3): v0 = THIS operator verb. Timestamps are machine clock only. Captures land under .saphan/work/<stream>/runs/<run-id>/ with an engine-written gitignore cover. Secret VALUES never appear on any surface (§1.6): --env passes variable NAMES through, values are read at spawn and stored nowhere.

Options

Examples

Everything below this line is written by hand and is not regenerated.

The smallest useful run: an ordinary program under mandate

saphan run --stream nightly-suite --backend proc \
  --binary /usr/local/go/bin/go --arg test --arg ./... \
  --workdir /srv/checkouts/api --profile execute --wall-clock 20m \
  --workspace /srv/saphan

This runs a program, not an agent: no model, no brief, no laws. It exists on the record with its own transcript, its exit status and its cost, which is the point — the same door, the same accounting, whether the work was done by a model or by go test.

An agent session

saphan run --stream add-rate-limits --backend claude-code \
  --binary /usr/local/bin/claude --model <a model your configuration declares> \
  --brief /srv/worktrees/wt-add-rate-limits/_MASTER_ORDER.md \
  --workdir /srv/worktrees/wt-add-rate-limits \
  --laws /srv/saphan/laws/LAWS_INDEX.md \
  --profile execute --wall-clock 90m --cost-estimate-usd 8 \
  --env HOME --env PATH --env USER --workspace /srv/saphan

Four things about that line are worth reading twice.

• --model is mandatory and is never a session default. The run records which source answered for it, so a model choice is always attributable.
• --laws is required for an agent backend and is read fresh at every spawn, including a resume; its digest lands on the record. An unreadable or empty file refuses before anything is spawned — an empty floor is not a floor.
• --brief must live inside the workdir. The session receives only its path and reads it from inside its own confinement; a brief outside is refused by name.
• --cost-estimate-usd is your quote, and the spend cap is derived from it rather than chosen separately.

⚠ A refusal here is a recorded outcome, not a fallback. If a precondition is missing the run refuses by name and nothing spawns — read the name rather than retrying blind.