Module sessions_control

Expand description

Controlled-tier conversations (Domain 11, concept 5) — new, reset, archive, delete over one uniform door.

Charter (docs/plans/orchestration-domain-11-2026-09-02.md §0.4): every mutation here is the harness’s OWN verb. supercode never writes another harness’s session store by hand; it runs the harness’s CLI, calls the harness’s HTTP API, or types the harness’s slash command into a LIVE driven session, then re-reads the row the harness’s own store now holds.

The doors, per harness, at the pinned versions:

harness	new	reset	archive	delete
claude-code	refused → `runtimes.start`	refused	refused	refused
codex	refused → `runtimes.start`	refused	`codex archive <id>`	`codex delete <id>`
opencode	refused → `runtimes.start`	refused	`PATCH /session/<id>`	`DELETE /session/<id>`
hermes	refused (gateway-only)	`/reset` in a live session	refused	`hermes sessions delete <id>`
openclaw	`/new` in a live session	`/reset` in a live session	refused	refused
orchestrator	its daemon’s operator door	its daemon’s operator door	refused	refused
supercode	refused → `runtimes.start`	refused	own store	own store

Three rules the whole tier inherits from crate::jobs_control:

The harness’s answer is the answer. After the door reports success the conversation is re-read through the ORCH-6 discovery loader and returned. A delete that leaves the row behind, or an archive the store did not record, is a FAILURE — never a silent success.
The door is narrated. Every outcome carries ran: the exact argv, HTTP request line, slash command, or store call that was performed, with any credential rendered as <redacted>.
A verb the harness has no door for is refused (SessionControlError::Unsupported → UnsupportedAction), with the reason and the door that DOES exist, never a silent no-op.

§Why some cells are refused at the pin

hermes sessions archive exists but is a BULK filter verb (--older-than, --title, --cwd, …) with no per-session selector, so a uniform “archive THIS conversation” cannot be expressed through it. hermes sessions delete <id> is per-session and IS used. (Pinned help fixture: crates/harness/src/parity/fixtures/hermes-help.txt, section $ hermes sessions --help.)
OpenClaw registers only sessions list | cleanup | tail | export-trajectory | compact at v2026.7.1-2 — no archive, no delete.
Claude Code publishes no conversation lifecycle verb at all: its sessions expire on a retention window it owns.
The orchestrator has no archive and no delete BY MODEL: a binding (docs/ORCHESTRATOR-IR.md §2.5) ends, and the transcript belongs to the worker harness the binding addresses. new and reset DO exist — they are the two chat commands its reducer applies to a binding (§4.5) — and ORC-13 opened the door that reaches them from outside a chat: the daemon’s operator socket, or the package’s own CLI when it is down (crate::orchestrator_door). The orchestrator’s conversation is a BINDING, so it is named by its SURFACE key (platform|chat_type|chat_id|thread_id|participant_id), never by a worker session id — --surface, not --session.
new / reset on the file-store harnesses is not a missing verb — it is a DIFFERENT door that already exists: harness.v1.runtimes.start. Refusing while naming it keeps one way to do one thing.

§A slash command is only sent when the harness’s door advertises it

Both gateway harnesses expose /new and /reset IN CHAT, but the door supercode drives is each one’s ACP adapter, and the two adapters do not carry the same set. Read from the harnesses themselves, 2026-09-03:

OpenClaw (openclaw@2026.7.1-2, dist/commands-*.js BASE_AVAILABLE_COMMANDS) advertises BOTH new (“Reset the session (/reset)”) and reset on its ACP door. Both are supported.
Hermes (acp_adapter/server.py _SLASH_COMMANDS / _handle_slash_command) advertises reset and NOT new — /new lives only in gateway/slash_commands.py, and the adapter comments that an unrecognized command “falls through to the LLM (the user may have typed /something as prose)”. sessions.new on hermes is therefore refused: sending it would put the literal text /new in front of the model, which is the silent no-op this tier exists to prevent.

The two doors also differ in EFFECT, and neither is re-interpreted here: hermes’s ACP /reset clears the conversation and keeps the session row, while the gateway’s /reset rotates the session id. supercode drives the door it can reach and reports what that door did.

Structs§

SessionMutation: One mutating request, in the uniform Domain 11 vocabulary.
SessionMutationOutcome: What one mutation did, with the conversation re-read afterwards.

Enums§

SessionControlError: Why a mutation could not be performed.
SessionDoor: The door one (harness, verb) pair goes through.
SessionVerb: One uniform conversation-lifecycle verb.

Constants§

ALL_SESSION_VERBS: Every uniform verb, in declaration order.
CODEX_BIN_ENV: Environment variable overriding the codex executable (tests).
CONTROLLED_SESSION_HARNESSES: Harnesses whose conversations supercode can mutate through at least one of their own doors. Strictly narrower than the set it can READ.
HERMES_BIN_ENV: Environment variable overriding the hermes executable (tests).

Functions§

controlled_methods: The RPC methods harness actually answers for the controlled tier. This is what the registry block advertises, so a method can never appear in the descriptor without a door behind it.
controlled_verbs: Every uniform verb harness can actually perform, in declaration order. Empty for a harness with no door at all.
door: Which door this (harness, verb) pair goes through, or WHY the harness refuses it.
harness_program: The harness’s own executable, with a SUPERCODE_<HARNESS>_BIN override so a fake CLI can stand in under test without touching PATH. The registry names each harness’s binary family in its runtime launch; the lifecycle verbs live on the base CLI, so an -acp bridge suffix is stripped.
live_outcome: Build the outcome for a slash-command door the SERVICE performed, so the live path and the subprocess path publish exactly the same shape.
mutate: Perform one conversation mutation through the harness’s own door.
supports_session_control: Whether harness publishes a door for at least one conversation verb.