The terminal console — saphan cli

saphan cli opens Saphan's terminal console on the workspace you are standing in. From it, one command opens a live session of a role — Master, Advisor, Scribe, or your own — on one of the workspace's seats:

$ cd /path/to/your/workspace
$ saphan cli
saphan> /advisor advisor-main

You never type a workspace path, a key, a machine, a backend or a program path: Saphan reads each of them from the workspace's own record, and refuses by name when one is missing. From outside a workspace, name it with saphan cli --workspace <workspace>; without the flag the console uses the directory you stand in, the nearest one above it that holds .saphan, or $SAPHAN_WORKSPACE.

Seats on the claude-code, codex and qwen-code backends open from the console alike. Each session runs under its vendor's own restrictions, with a short preamble telling it which role it holds.

What you see

The welcome screen shows the workspace, whether the workspace key loads on this host, the machine, and for each of /master, /advisor, /scribe and /owner the seats it can open from here.

Commands

One session runs at a time. While it runs, another role command and /workspace are refused until you close it.

Keys inside a session

Ctrl+] opens the session menu on the last line; then one key:

At the saphan> prompt, Ctrl+] returns to the live session, and Tab completes commands and seats.

The last line: what the session runs under

While a session is open, the console keeps your terminal's last line and gives the session the rows above it. The line says, in plain words, what the engine resolved for the session — the role, the work it holds (or the seat), the machine, the model, the permission grant by name and the permission mode — and how long it has run:

 saphan ▸ MASTER · billing-service · build-01 · <model> · grant: master-grant · permission: auto · 3m  │  ^] menu

grant: none means the console composed no grant and the vendor reads the seat's own settings; grant: unavailable — see log means a grant should have been composed and could not be. The full statements — the grant's file and digest, the configuration key the mode came from, the backend and the model id — are in the session log and in saphan cli status --json.

When the seat's usage limit is spent, the line says so, with the reset time and the way out: ^] d, then /login <seat> to sign in to another account, then /resume to take the work back.

The start line and the session log

Opening a session can take a moment. While it does, the console shows one line, rewritten in place, saying what the start is doing and how long that step has taken:

  Preparing your session… · recording the session · 3 s

• The seconds count the current step and rise about once a second. A line whose seconds have stopped rising is stuck, not slow: close the tab and start again.
• A step that ends badly leaves one plain line on the screen, for example ⚠ This session is not recorded, so it cannot be resumed later — see log. The session still starts.
• When the vendor's program takes the terminal, the line becomes Session ready with a check mark, or ⚠ Guardrail not judging — see log when no guardrail judges the session.

Everything else goes to the session log, not onto your screen: every step, its time and its attempts, the guardrail's posture, what the session's network wall admits, and the grant. The log is <workspace>/.saphan/logs/session-<UTC time>.log; read it with cat.

While the session runs, the screen gets one plain line only for something a person must act on, said once: ⚠ Sign-in expired and was not renewed — sign in again., ⚠ Signed in again — type continue to go on., or a guardrail outage (⚠ Guardrail not judging — see log, and later Guardrail judging again with a check mark). How the session ended is written to the same log.

A script or a pipe (when standard error is not a terminal) sees no start line: it gets every note as a plain line on standard error.

Reopening a session

Every session the console opens on a seat of this host is recorded under the vendor's own session id. When a session ends while the console is open, the console prints resume it: /resume <id>.

• /resume lists the sessions to reopen, each by its name — the vendor's title for the session, or the first thing you typed in it — including a session lost with its terminal, looking back 30 days.
• /resume <id> or /resume <words of its name> reopens one on the seat and profile it ran on.
• One line per terminal tab: saphan cli sessions --workspace <workspace> --lines prints, for each session, the ready line saphan cli --workspace <workspace> --resume <id> with its name as a comment. Paste one into a tab to reopen that session there.

⚠ A session on a seat of another machine, reached over ssh, is not recorded and cannot be resumed from here. A session on the qwen-code backend is not recorded either; resume it with saphan run --interactive --role <role> --identity <seat> --resume <id>.

Your own seat — /owner

/owner opens your own interactive session, on a seat the fleet never dispatches work to. It is registered once with the role owner, with an account of your own:

saphan machine seat --role owner --identity owner-1 --machine <machine> --slot <free slot> \
  --backend claude-code --billing-class subscription \
  --config-dir $HOME/.claude-owner --added-by <you> --workspace <workspace>

Sign that profile in first with your own account (for example CLAUDE_CONFIG_DIR=$HOME/.claude-owner claude auth login), check it with saphan cli status --workspace <workspace>, and open it with /owner owner-1. Such a session is told no role: it is yours, not the fleet's.

When it refuses

Every refusal is one sentence plus the next thing to do. The common ones:

Not in this version

Several sessions at once (tabs), sessions on remote seats, and Windows.