@volter/supercode-orchestrator 0.4.4

package/README.md

@@ -0,0 +1,532 @@
+# `@volter/supercode-orchestrator`
+
+This is currently a private workspace package. Examples assume the checkout's
+workspace dependencies and a built Volter Harness CLI; the package name is not a claim
+that an installable npm release exists.
+
+The orchestrator's runtime over the ontology: one typed operational model
+(`OrchestratorState` = an orchestration value plus a runtime half) whose folder is its serialization.
+`docs/ORCHESTRATOR-IR.md` is normative. The orchestration value and every codec are the ontology's, in
+Rust (`crates/interchange/src/orchestration/`); this package reads and writes its home through the
+harness's orchestration doors (`harness.v1.orchestration.*`), never a codec of its own.
+
+```js
+import { load, save, compile, importFrom, exportTo, closeWorld } from '@volter/supercode-orchestrator';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const root = process.env.SUPERCODE_ORCHESTRATOR_HOME || join(homedir(), '.supercode/orchestrator');
+const { state, vault } = await load(root);                        // strict; secrets in `vault`, never `state`
+await save(state, root);                                          // canonical, byte-stable when unchanged
+
+const { state: hermesState } = await compile('hermes', process.env.HERMES_HOME); // a home as a state value
+await closeWorld();                                              // close the shared door when done
+```
+
+The doors are `orchestration.mjs`: `load`/`save`/`compile`/`importFrom`/`exportTo`/`closeWorld` over one
+`SupercodeHarnessClient`. A secret VALUE never crosses the wire — `load` and `compile` answer with
+the `.env` KEY NAMES, and `load` reads the values out of the home's own `.env`. The door is held
+open while a loop runs (`retainWorld`/`releaseWorld`, the loop's `start`/`stop`) and closes itself
+when idle, so a one-shot verb (a test, a migration) exits on its own.
+
+Rules the codec keeps (enforced in Rust, observed here):
+
+- Unknown keys in an orchestrator-owned block (`worker`) fail the
+  load, naming the file and key. Hermes-shaped records keep unmodeled fields in `residue`, verbatim.
+- A file whose decoded record is unchanged is written back byte for byte; a changed record is
+  emitted canonically in Hermes's own field order.
+- Secret values live in the vault (`.env` in our folder; inline in a Hermes export because that
+  is where Hermes reads them). A value pasted inline into our folder is moved into `.env` on
+  first load and the file rewritten with the ref. `JSON.stringify(state)` never contains one.
+- Exporting to Hermes refuses to write Hermes's session store when bindings or obligations changed
+  since import (UNI-22); it copies the store byte for byte when they did not.
+- Files the IR does not model are never touched by `save` and are carried by path on a migration.
+
+## OpenClaw, and the two migration verbs (ORC-12)
+
+```js
+import { compile, importFrom, exportTo } from '@volter/supercode-orchestrator';
+
+const { state } = await compile('openclaw', process.env.OPENCLAW_STATE_DIR); // a home as a state value
+```
+
+```sh
+node bin/orchestrator.mjs import --from hermes|openclaw [--home <path>] [--into <root>]
+node bin/orchestrator.mjs export --to   hermes|openclaw [--from <root>] [--into <dest>]
+```
+
+`import` (`orchestration.import`) compiles that harness's home and saves ours, credentials along; `export`
+(`orchestration.export`) loads our folder and decompiles it back, printing the tier of every file it wrote.
+Because a migration moves credentials, both are composed inside the harness process, not from the
+value-level doors — a client composing them would have to send the secret over the wire. A refused
+write exits **2** with its reason — a partial migration is never reported as a whole one.
+
+What OpenClaw's state directory compiles to, at the pinned `v2026.7.1-2`:
+
+- `agents.*` → profiles. The DEFAULT agent (the entry flagged `default`, else the first declared,
+  else `main`) is the IR's `default` profile; every other agent keeps its id. Each is rooted at its
+  own `agents/<id>/`.
+- `channels.<name>[.accounts.<id>]` → one `ChannelConfig` per row `channels list` shows, keyed by
+  that row's name (`slack/T0FIXTURE`); the transport is `extra.kind` and the source blocks ride
+  verbatim in `extra.channel_block` / `extra.account_block`.
+- `bindings[]` → `Route`. The IR's match carries the three fields it has a noun for (`channel` →
+  `platform`, `guildId` → `guild_id`, `peer.id` → `chat_id` — the projection `routes list` makes);
+  `accountId`, `teamId`, `roles`, `peer.kind` and the binding's `type` ride in residue.
+- `hooks.mappings[]` → `WebhookSubscription`s (the inbound-trigger noun `triggers list` reports),
+  with the block's shared `token` as each subscription's secret.
+- `cron_jobs` → `Job`. `sessionTarget` has no IR field: it stays in residue verbatim AND surfaces
+  as `attach_to_session` when it names an existing conversation (`main` → `agent:<id>:main`,
+  `current` → the row's own session key, `session:<id>` → `<id>`; `isolated` opens a fresh one).
+- `cron_run_logs` → `Fire`. `ok | error | skipped` map to `succeeded | failed | unknown` and the
+  native word stays in residue. OpenClaw's run log is written once, at finish, and records no
+  claim, so the fire's start stands in for `claimed_at` and `residue.__no_claim` says so.
+  `delivery_status` / `delivery_error` / `delivered` ride in residue, and the queue entry on the
+  same conversation key becomes the fire's `obligation_id`.
+- `delivery_queue_entries` → `Obligation`, partitioned by the agent segment of its session key.
+- each agent's `sessions/*.jsonl` header key → a `Binding`. `agent:<id>:main` is OpenClaw's DM
+  COLLAPSE: it becomes `{platform: 'main', kind: 'dm', chat_id: 'main'}` and the collapse is
+  recorded in residue, because the IR cannot recover which transport a collapsed DM arrived on.
+
+Tiers on the way out:
+
+- **byte** — `state/openclaw.sqlite` when every record decoded from it is unchanged (the file is
+  copied); any row whose own record is unchanged when the store must be rewritten (its columns go
+  back verbatim, and `report.rows` counts them); every unmodeled file under the state directory;
+  and `openclaw.json` when its decoded record is unchanged.
+- **semantic** — a CHANGED `openclaw.json`. It is re-emitted as JSON, which openclaw's JSON5
+  parser reads, but the source's comments, trailing commas and key order are lost; `report.notes`
+  says so every time that path is taken.
+- **refused** — bindings. An OpenClaw conversation's surface lives in its session KEY inside the
+  transcript header, so writing them back is behind the UNI-22 stability gate, exactly as
+  the Hermes export refuses Hermes's session store. A credential ref the vault cannot resolve is refused
+  too, rather than written as its own reference.
+
+Secrets never enter the model: any string under a credential-shaped key — openclaw's own rule
+(`channels.rs::is_credential_key`: the lower-cased key ENDS WITH `token|key|secret|password|
+credential`), minus the names it spells that way for non-secrets (`sessionKey`, `store_key`, …) —
+moves to the vault as a `{dotenv}` ref and is re-inlined on export where openclaw reads it.
+
+Two limits worth naming. `save` writes our folder in the IR's own serialization, so a home
+imported from another harness loses that harness's file COMMENTS and, for fires, any run-log
+column our Hermes-shaped `cron/executions.db` has no room for (OpenClaw's `delivery_status`,
+`session_key`, `summary`, `model`, token counts): a direct compile-then-decompile of an OpenClaw
+home is byte tier, the same trip through our folder is not. And `import` carries the source home's
+unmodeled files by path, because `save` only ever writes the files the IR owns.
+
+## The loop (ORC-4)
+
+```js
+import { Orchestrator, LoopbackAdapter, events, load } from '@volter/supercode-orchestrator';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+
+const { state, vault } = await load(root);
+const orch = new Orchestrator({ state, vault, client: new SupercodeHarnessClient(), adapters: { loopback: new LoopbackAdapter() } });
+await orch.start();                      // adapters connect; inbound messages become events
+const now = new Date().toISOString();
+await orch.dispatch(events.tick(now));   // the clock is an event too
+```
+
+`step(state, event)` is the pure reducer (§4): it mutates the one state value and returns effects
+(§5); the `Orchestrator` performs them over the SDK (`runtimes.start|send_input|respond`) and the
+adapters (`deliver`). A worker runs with the profile folder as cwd and the profile's harness home
+inside it (`activationEnv`), so its AGENTS.md is in context by the ordinary instruction-file walk.
+
+## Cron and webhooks (ORC-5)
+
+```js
+await orch.dispatch(events.tick(now));       // §4.3: expiry, due jobs, obligation retry, breakers
+await orch.tick();                           // the same, on the orchestrator's own clock
+// POST /webhooks/<name> on orch.webhookPort (config `gateway.webhook_port`, else any free port)
+```
+
+- A due job is **claimed before it runs**: the fire row (`cron_<job_id>_<YYYYMMDD_HHMMSS>`, which is
+  both the fire's id and its session name) is saved before the `runtime_start` effect, and a second
+  tick that sees a `claimed`/`running` fire for that job does nothing.
+- The fire runs on a synthetic key `{platform: 'cron', kind: 'dm', chat_id: job_id}` with a
+  binding carrying `recurrence`. Its `final` delivers to the job's resolved target — `origin` →
+  `job.origin`, `home` → `profile.home`, `explicit` → as given, `local` → `cron/output/<fire_id>.md`
+  under the profile — never to the synthetic key. An error or timeout goes to `failure_deliver`,
+  else to `deliver` with a `Cron job <id> failed:` prefix.
+- `next_run_at` is recomputed after every fire: `once` is spent (unless a numeric `repeat` remains),
+  `interval` counts from the run, `cron` evaluates five fields in `schedule.tz`. `context_from`
+  prepends a note naming the session; the transcript is never loaded.
+- The daemon does not die on a failed event: a timer tick, an adapter's inbound, the webhook listener
+  or a queued follow-up whose effect fails (a save on a full disk) is logged, where before its
+  unhandled rejection ended the process. History is bounded as Hermes bounds it: run files per job
+  (`cron.output_retention`, 50), completed one-shots (`cron.completed_retention_days`, 7), 1000
+  finished fires, and obligations as its delivery ledger (7 days, 500 rows).
+- Slack, Telegram and Discord blocks from a Hermes home connect through the Chat SDK sidecar with
+  Hermes's own `.env` variables and ingress (Socket Mode, polling, the gateway); install the platform
+  package (`@chat-adapter/slack`, …) beside the orchestrator.
+- The agent-setup applier (`orchestrator apply plan|apply|adopt|provision --home-id <id> --hermes <home> | --orchestrator <root> --spec <setup.json>`):
+  a package's declared jobs and `Inference` reach one home through its own functions (Hermes's cron
+  and config functions under its own interpreter; the orchestrator's operator verbs), owned by
+  harness id against a base in the applier's own state. A home with no state is plan-only until
+  `provision` or `adopt`; `delete` runs only with `--reviewed`.
+- Limits as Hermes sets them: `cron.max_parallel_jobs` / `HERMES_CRON_MAX_PARALLEL` caps the fires in
+  flight across the daemon; an `agent.max_turns` a worker cannot take at launch is reported as not
+  enforced.
+- A webhook subscription with `deliver_only: true` (Hermes's direct-delivery mode) runs no agent: the
+  rendered prompt is delivered as the message.
+- A job's gate runs before any model, as in Hermes: `script` (its stdout leads the prompt, or skips
+  the model when empty or `{"wakeAgent": false}`), `no_agent` (the script IS the job), and
+  `monitor_script`/`monitor_url` (unchanged output suppresses the run; a change puts a diff in the
+  prompt). Scripts live under the profile's `scripts/`.
+- A fire whose explicit delivery target is on a platform no adapter serves is blocked before its
+  worker runs (Hermes's delivery preflight), alerting once until a healthy run. Each run resets the
+  job's `last_delivery_error`; a delivery that finally fails writes it.
+- A fire whose worker has been silent for `HERMES_CRON_TIMEOUT` seconds (600 by default, 0 for no
+  limit, as in Hermes) is closed as a timeout, its failure delivered, and its runtime closed; before,
+  a hung fire kept its job from ever running again.
+- A job's `model` (and a profile's, and `/model`'s) reaches the worker's launch (`claude --model`,
+  `codex app-server -c model=…`, `gemini -m`). For a harness with no such flag it is refused where it is
+  set (`/model`, `jobs.create|update`, `cronjob_create`) and again at the start, rather than run on
+  the harness's default. A job's `skills`
+  are invoked as Hermes invokes them: each is found through the worker harness's own skill loader, from
+  the fire's own working directory, and its `SKILL.md` (with `${HERMES_SKILL_DIR}` resolved) goes ahead
+  of the prompt, which follows Hermes's instruction marker; a skill that is not there is named in a
+  notice.
+- A schedule nothing can evaluate — a cron expression that does not parse, a `tz` that is not an IANA
+  zone (`America/New_Yrok`) — is refused by name at every door a job enters by (`jobs.create|update`,
+  `jobs.resume`, `cronjob_create`). One that reached the folder by hand is caught fail-closed: the
+  tick that finds it due, or the fire that cannot re-arm it, disables the job (`enabled: false`,
+  `next_run_at: null`, the reason in Hermes's `last_error`) and sends one notice to
+  `failure_deliver`, else `deliver`, else home. It is never left due.
+- A pending obligation is retried on the tick with a 1 / 2 / 4-minute backoff up to three attempts.
+  Three consecutive send failures on one adapter open its breaker for five minutes
+  (`state.runtime.adapters[platform].breaker`); while it is open, obligations stay `pending` and
+  their `attempts` are untouched. An adapter an `adapter` event has already declared `down`
+  (`state.runtime.adapters[platform].state`) is treated the same way before the breaker has counted
+  to three, so a single delivery cannot spend its three attempts inside a known outage and die
+  `failed` while the transport is still gone.
+- `POST /webhooks/<name>` verifies an HMAC-SHA256 `X-Signature-256` header against the
+  subscription's secret **from the vault** and is fail-closed: unverified is dropped and logged.
+  A verified call renders `prompt_template` with `{field}` substitution from the JSON payload,
+  opens a turn on `{platform: 'webhook', kind: 'dm', chat_id: name}` in the subscription's
+  profile, and delivers the answer per `subscription.deliver`.
+- A subscription's `events` filter on the event the SOURCE names: `X-GitHub-Event`, `X-GitLab-Event`,
+  `X-Event-Key` (Bitbucket), `X-Event-Type`, else the body's own `event`/`type`/`action`. An entry with
+  a dot names the action too (`pull_request.opened` matches `<event>.<payload.action>`); a call naming
+  no event is not a subscribed one. A delivery id (`X-GitHub-Delivery`, `X-GitLab-Event-UUID`,
+  `Webhook-Id`, `X-Request-Id`) already handled for that subscription — the last 200 are remembered —
+  is dropped with an info log, so a redelivery runs once. The memory is runtime state, as in
+  Hermes's own adapter: a daemon restart forgets it.
+- A permission prompt raised inside a fire or a webhook turn has nobody to ask, so it is answered
+  at once — never left to `worker.permission.timeout_seconds` — with `worker.permission.unattended`
+  (`deny`, the default, or `approve`; Hermes's `approvals.cron_mode`), and one line saying what was
+  decided goes to the job's `failure_deliver`, else `deliver`, else home (a webhook's: its
+  `deliver`). A chat's prompt is still relayed to the chat.
+- A Codex worker asks only when started with an approval policy: where the profile keeps Hermes's
+  approvals (`approvals.mode` unset or not `off`) it starts with `approval_policy: untrusted`, so it asks
+  before every command and Hermes's rule answers; with approvals off it asks nothing.
+
+```yaml
+worker:
+  harness: codex
+  permission:
+    unattended: approve   # deny | approve; what a cron fire or webhook turn's prompts get
+```
+
+Known gap: `Fire.session_id` and `Fire.obligation_id` are live-record fields with no column in
+Hermes's `executions` table, whose schema is frozen. They round-trip by construction instead — the
+fire's id **is** its session name (`fireSessionId`), its obligation is `obl-<fire_id>`, and the
+binding carries `residue.fire_id` — so `load()` still joins a fire to its session and its delivery.
+
+## The model-facing door (ORC-6)
+
+One stdio MCP server per worker session, spawned by the worker itself and bound to the conversation
+that spawned it (§7). `Orchestrator.start()` opens a Unix socket at `<root>/orchestrator.sock`
+(`mcp/bridge.mjs`); `startRuntime` mounts `mcp/server.mjs` through whatever door the worker's harness
+publishes (`mcp/mount.mjs`), with the binding in the server's environment — the three variables
+`activationEnv` already sets, plus `SUPERCODE_ORCHESTRATOR_SOCK`.
+
+| Harness | Door | What is written |
+|---|---|---|
+| claude-code | `--mcp-config <file>` in the launch arguments | `<profile>/claude-code/mcp-orchestrator-<surface>.json`, `.mcp.json`-shaped |
+| codex | `[mcp_servers.orchestrator]` | appended (idempotently) to `<profile>/codex/config.toml` |
+| opencode | `mcp.orchestrator` | `<profile>/opencode/opencode.json` |
+| pi | none | pi ships no MCP client by design; the mount refuses and says so |
+| hermes, openclaw, any other ACP agent | `session/new`'s `mcpServers` | `harness.v1.runtimes.start`'s `mcp_servers` |
+
+Only the flag and ACP doors are named per launch, so only they carry the per-session
+`SUPERCODE_ORCHESTRATOR_SURFACE`; under codex and opencode the server inherits it from the worker
+process the loop already activated for this session.
+
+Tools, one per verb, names and argument shapes transcribed from Hermes's `tools/cronjob_tools.py`
+(`cronjob_manage`) and `tools/send_message_tool.py` (`send_message`): `cronjob_create`,
+`cronjob_list`, `cronjob_delete`, `send_message`, `session_search`, `session_handoff`, `memory_show`,
+`skills_list`. Every result names what it did in `ran`.
+
+- `cronjob_create` captures `origin` from the binding, never from an argument, so a job created in a
+  conversation delivers back to it. Hermes's `name` has no IR field and rides the residue channel.
+- `schedule` takes the IR's typed `Schedule` or the four Hermes string forms that map onto it
+  exactly (`30m` / `every 2h`, `in 30m`, five-field cron, an ISO timestamp); natural day/time
+  phrasing is refused by name rather than re-implemented.
+- `send_message` defaults to this session's own surface; a target that routes to another profile is
+  refused, naming that profile.
+- `memory_show` and `skills_list` proxy `harness.v1.memory.show` / `skills.list` for the worker
+  harness against this profile's own config home.
+
+`supercode mcp serve` (the coding tools) is a different server for a different purpose and is
+untouched.
+
+## Acceptance (ORC-8)
+
+The bar of `docs/ORCHESTRATOR-IR.md` §8 — one scripted week of realistic use replayed against
+Hermes and against this package, compile-diffed, only zero defects done — closed on 2026-09-04 at
+defect 0 (61 scenes, 21/21 expectations, 28 seconds, both subjects on the scripted clock). §8
+carries the record, the defects fixed on the way and the Hermes evidence boundary; the instrument
+was deleted after its run (owner rule: the roadmap's one test run, then gone).
+
+## The two borrowed adapters (ORC-9)
+
+Every adapter is the same three methods — `connect(emit)` / `send(target, content)` / `close()` —
+and every one of them reaches the reducer through `inbound` and nothing else (§3: *"An adapter that
+cannot express something as an `inbound` event does not get a private path into the loop"*). A
+`platforms:` block picks its adapter by `extra.adapter` when it names one and by the block's own
+name otherwise:
+
+```yaml
+platforms:
+  slack:                      # one block = one (platform, account)
+    enabled: true
+    extra:
+      adapter: chat-sdk       # -> adapters/chat-sdk.mjs
+      botToken: ${SLACK_BOT_TOKEN}              # a reference, as Hermes writes one; the value lives in .env
+  api_server:                 # -> adapters/api-server.mjs, by the block's name
+    enabled: true
+    extra:
+      host: 127.0.0.1
+      port: 8090
+      key: ${API_SERVER_KEY}
+  rh2:                        # -> adapters/rh2.mjs: Runhuman Room conversations as a channel
+    enabled: true
+    token: ${RH2_SESSION_TOKEN}                 # the bot principal's automation session; a reference loads as a
+                                                # credential only at the block's top level or under extra:
+    extra:
+      api_url: https://pilot.runhuman.com
+      organization: peakhealth
+      principal_id: prn_…                       # the bot's own principal (is_me, mentions)
+```
+
+**The RH2 adapter** (`adapters/rh2.mjs`) holds an RH2 session, follows every active Room the bot is
+a member of (or `extra.rooms`), polls each conversation it may read (`GET …/messages?after=`), turns
+a person's line (`kind: human`, or a trigger's `automation`) into an `inbound` on the key
+`{platform: rh2, kind: channel, chat_id: <roomId>/<conversationId>}`, and posts the reply as an
+`agent`-kind message authored as the bot. Typing is RH2 conversation presence, tried once and
+forgotten if the deployment has no door for it.
+
+Both blocks show up in `supercode channels list --harness orchestrator` through the reader that was
+already there — `configured` by key *presence*, never by reading a value.
+
+**The Chat SDK sidecar** mounts `chat@4.39.0` (npm package `chat`, repo `vercel/chat`; a
+devDependency of this package, installed alongside `@chat-adapter/state-memory@4.39.0`). The
+platform packages (`@chat-adapter/slack`, …) are **not** dependencies: the one the block names is
+imported lazily at `connect`, and the credential **key names in the block are that factory's own
+option names** — Volter Harness renames nothing and resolves the refs out of the vault at connect, never
+earlier. Surface identity is read off the handler's `Thread` (`adapter.name`, `channelId`, `id`,
+`isDM`, `channelVisibility`) and content off the `Message` (`author.userId/userName/isMe/isBot`,
+`isMention`, `id`, `metadata.dateSent`, `attachments` with `fetchMetadata` as the IR's
+`Attachment.ref`) — ORC-1 F4's table, transcribed. Two decisions the IR left open are made in
+`adapters/chat-sdk.mjs` and nowhere else:
+
+- **`kind`** (the surface key's chat type) (F4 finding 4, which named this as a rule the IR "would have to invent"):
+  `isDM` → `dm`; else `channelVisibility: private` → `group`; else (`workspace` / `external` /
+  `unknown`) → `channel`. `thread` is never produced — a thread is the key's own `thread_id`.
+- **Queueing** (F4 finding 11): the SDK's per-thread concurrency is set to `concurrent`, so §4.1
+  step 5's queue is the only queue on a surface. `extra.concurrency` overrides it.
+
+`is_me` is now on the event and the reducer drops such an inbound at step 0 (§4.1): a platform that
+replays what we posted is not a turn. `send` returns the platform's handle and `deliver` records it
+as `Obligation.posted.message_id` (§2.6) — the thing §4.2's edit-in-place would edit.
+
+**The api_server surface** serves Hermes's own client API on its own `node:http` listener bound to
+`platforms.api_server.extra.host|port` (exactly Hermes's keys, `api_server.py:1515-1519`). It is
+deliberately *not* mounted on the webhook listener: that one binds `gateway.webhook_port`, a
+different key with a different meaning. Auth is `Authorization: Bearer <extra.key>` —
+Hermes's `_check_auth` (`:1916-1968`) — and every route quotes the handler it was matched against.
+Routes: `GET /v1/health` (the one unauthenticated one), `GET /v1/capabilities`,
+`POST /api/sessions`, `POST /api/sessions/{id}/chat`, `GET /api/sessions/{id}/messages`,
+`POST /v1/runs`, `GET /v1/runs/{id}`, `GET /v1/runs/{id}/events`, and
+`POST /v1/runs/{id}/approval|steer|stop`.
+
+Everything it makes the loop do is an `inbound`: a chat is one; a run is one on a fresh binding
+`{platform: 'api_server', kind: 'dm', chat_id: <run id>}`; a steer is one queued behind the
+running turn (§4.1 step 5); a stop is `/reset` (§2.7); and an approval is resolved to the worker's
+own option and answered as the **number** §4.2's permission prompt asked for. The run event stream
+is derived from §2.8 runtime state — the turn's text buffer, the pending permission requests, and
+the obligation the turn's `final` produces — because the loop publishes no event bus and ORC-9 does
+not add one.
+
+**Where Hermes's shape has a field the IR has no source for, it is returned empty**, never guessed:
+
+| route | empty field(s) | why |
+|---|---|---|
+| `POST /api/sessions/{id}/chat` | `usage`, `runtime` | the IR records no token accounting and no provider/model routing |
+| `GET /api/sessions/{id}/messages` | `token_count`, `tool_calls`, `tool_call_id`, `tool_name`, `finish_reason`, `reasoning` | §2.5 keeps no per-message tool or token record; the transcript stays native and is read through `sessions.load` |
+| `POST /api/sessions` (`session` object) | `user_id`, `model`, `tool_call_count`, `input_tokens`, `output_tokens`, `parent_session_id` | same |
+| `GET /v1/runs/{id}` | `model` | the run does not choose a provider model; `profile.worker` does |
+
+Four honest divergences, stated rather than hidden:
+
+- `platform` reads `supercode-orchestrator`, not `hermes-agent`, on `/v1/health` and
+  `/v1/capabilities`: it names the server that answered.
+- `X-Hermes-Session-Key` is **not** an auth credential in Hermes either — `_parse_session_key_header`
+  (`:2403-2440`) reads it as the caller-declared conversation scope, and it is read with that
+  meaning here. Bearer is the trust boundary.
+- `/v1/runs/{id}/approval` accepts Hermes's `once|session|always|deny` (with
+  `approve|approved|allow` aliasing to `once`), but the IR has no standing-grant store: `session`
+  and `always` resolve the pending request exactly as `once` does and no grant outlives it.
+- `/v1/chat/completions`, `/v1/responses`, `/api/sessions/{id}/chat/stream`, `/api/jobs/*`,
+  idempotency (`Idempotency-Key`) and the `/p/<profile>/` route mirrors are **not** served;
+  `/v1/capabilities` reports each as `false` rather than copying Hermes's `true`.
+- A run is `running` from the moment it is accepted (Hermes passes through `queued` first), and
+  `/stop` leaves it `cancelled` once the `/reset` lands rather than in `stopping`.
+
+Known gaps, named:
+
+- `Obligation.posted` lives on the in-memory record only. Hermes's `delivery_obligations` table has
+  no column for it and the store is byte-compatible with that schema, so a save/reload loses the
+  handle. Adding it is a schema change to §2.6's codec, not an adapter change.
+- `deliver` projects the obligation to `{ text, at }` before calling `send`, so
+  `OutboundContent.reply_to` and `attachments` never reach an adapter today even though §2.1
+  declares both and the Chat SDK sidecar honours both (`thread.reply`) when a caller supplies them.
+- The production path that builds a real platform adapter from a block (`@chat-adapter/*` →
+  `createSlackAdapter(...)`) is **not** exercised by the suite: the tests drive a hand-written
+  `Adapter` (the SDK's `packages/chat/src/mock-adapter.ts` shape, transcribed — that file is not
+  re-exported from the package entry, is outside its published `files` list, and imports `vitest`).
+  Evidence for the sidecar stops at the SDK boundary; the platform packages are extrapolation.
+
+## Access, the daemon's lease, and coming back (ORC-10)
+
+```sh
+node bin/orchestrator.mjs access pair-list                    --root <home> [--profile <name>]
+node bin/orchestrator.mjs access pair-approve <code>          --root <home>
+node bin/orchestrator.mjs access allow|revoke <platform> <user_id>          --root <home>
+node bin/orchestrator.mjs access admin-add|admin-remove <platform> <user_id> --root <home>
+```
+
+`supercode orchestrator pair approve|list` and `access allow|revoke|admin add|remove` spawn exactly
+these: the folder has one encoder (`save()`), and it is not in the Rust binary. Each verb loads the
+home, applies the reducer's own `operator` event and saves; a verb the reducer refuses exits
+non-zero with the reducer's own words and writes nothing it did not ask for. They are the COLD path
+— for a running daemon the same verbs go through its socket (ORC-13).
+
+- **Access lives in Hermes's own stores, and only there.** A platform is open when the profile's
+  own `.env` sets `<PLATFORM>_ALLOW_ALL_USERS=true` (or `GATEWAY_ALLOW_ALL_USERS=true` for every
+  platform); its allowlist is `<PLATFORM>_ALLOWED_USERS` plus the pairings Hermes approved
+  (`platforms/pairing/<platform>-approved.json`). **A platform with neither is allowlist-only.**
+  An unknown sender is answered with a pairing code from Hermes's own `PairingStore` (its expiry,
+  rate limit and lockout) and nothing else: no worker starts.
+- **Admins** are each platform's `allow_admin_from` / `group_allow_admin_from` in `config.yaml`:
+  the tier whose numeric reply resolves a relayed permission prompt (§4.2). An allowlisted
+  non-admin's number is an ordinary message.
+- No other file grants access. `approve`, `allow`, `revoke` and `admin` go through Hermes's store
+  and writers, live or cold.
+
+The **lease** `<home>/orchestrator.lock` is written by this daemon, not by `supercode orchestrator
+start`: one writer means a launchd/systemd-managed daemon reports the same lease a foreground one
+does. The lock names the process and its machine (hostname, and Linux's boot id). A home whose
+lock names a live process on this machine, since this boot, is refused; a lock naming a process
+that is **gone**, or one another machine or an earlier boot wrote (a home on a volume the
+sandbox before this one mounted), is the mark of a daemon that died, and the daemon dispatches
+`restart` (§4.7) before it accepts anything. Nothing is signalled on the word of a lock from
+elsewhere. `leaseIsLive` and `readLease` are the package's reading of it. A clean stop removes its own lock, so an ordinary start replays nothing.
+
+On `restart`: every pending obligation goes out again, and every binding that held a lease is
+re-opened. The lease table is never persisted (§2.8), so a lease start records `runtime_id` on the
+binding's residue; the loop tries `runtimes.attach_existing` where the harness's registry row says
+`attach_existing_process`, and otherwise marks the binding interrupted and tells its surface once
+(`Session interrupted by a restart; send your message again.`). Cron and webhook surfaces get the
+mark without the notice — nobody is reading them.
+
+Tests run against the repo's Hermes fixture home and a mock ACP worker, and need
+`target/debug/supercode` built: `npm test` in this directory.
+
+## The operator door (ORC-13)
+
+The orchestrator's WRITE door — what `supercode jobs|profiles|sessions <verb> --harness orchestrator`
+drives, the way Hermes's write door is `hermes cron …` (§4.6). Volter Harness writes no file of this
+folder: `save()` here stays the only writer, so the IR's byte-stability and residue rules hold by
+construction.
+
+Two doors, **one** implementation (`applyOperator` in `operator.mjs`); only how the event is
+dispatched differs.
+
+**Live** — the same socket the model-facing door uses, a second line family beside it, told apart by
+the `op` key:
+
+```
+in   {"op":"jobs.create","args":{"prompt":"…","schedule":"every 30m"},"profile":"coder"}
+out  {"ok":true,"result":{"ran":"created cron job job_… …","job_id":"…","job":{…}}}
+     {"ok":false,"error":"jobs_delete: no job job_x"}
+```
+
+`op` is one of `jobs.create|update|pause|resume|run|delete`, `profiles.create|delete`,
+`sessions.new|reset`, `access.pair_approve`. The verb dispatches its `events.operator(...)` on the
+**loop's own queue**, so an operator write is ordered against inbound messages and ticks like
+anything else and the running loop's state and the folder can never disagree. `result` re-reads the
+affected record out of state after the reducer ran.
+
+**Cold** — the same verbs when no daemon is serving the home:
+
+```
+node bin/orchestrator.mjs <op> --root <home> [--profile <p>] [--at <rfc3339>] --json '<args>'
+```
+
+It loads, applies through `applyOperator`, performs the effects the loop would (`save`,
+`remove_profile_dir`), prints the same `{ok, result}` line and exits 0, or 1 on a refusal.
+`crates/harness/src/orchestrator_door.rs` picks between the two: the socket when
+`<root>/orchestrator.lock` names a live pid *and* the socket answers, the CLI otherwise. A refusal on
+the live door is final — only a broken socket falls through, so a verb the daemon already answered is
+never run twice.
+
+- **A refusal names its reason.** The reducer refuses by emitting a `warn` log effect and no `save`;
+  that sentence becomes `{ok:false, error}` verbatim, and nothing is written.
+- **`sessions.new|reset` name a BINDING by its SURFACE** (`platform|kind|chat_id|thread_id|participant_id`),
+  not by a session id — a binding has none of its own. A surface with no live conversation refuses.
+- **`profiles.delete` never unlinks.** It removes the record and emits `remove_profile_dir`, which
+  renames the home to `profiles/.trash/<name>-<stamp>/`. A dot-prefixed folder is not a profile to
+  either loader, so a trashed home neither loads nor lists.
+
+
+## Hosted scheduled tasks
+
+A host can retain its existing conversation and deterministic action runtime while
+this package owns schedules, durable fire claims, run output and the operator socket:
+
+```sh
+supercode-orchestrator --root /instance/var/orchestrator \
+  --executor-url http://127.0.0.1:5200/os/scheduled-task \
+  --executor-token-file /instance/var/executor.token
+```
+
+The executor URL must be loopback HTTP. Its private token file contains at least
+32 characters. Each authenticated POST carries `{root, profile, job, fire}`; the
+host returns `{accepted: true, profile, fire_id, output, delivery?}` only after
+accepting that exact fire. A delivery receipt is `{platform, chat_id, id}` and
+confirms the submitted task, not a model's eventual answer. The output must say
+which milestone it confirms. `jobs.create` accepts opaque JSON `metadata`, stored
+in `job.residue.host`, and `enabled: false` for initially paused tasks.
+
+Hosted execution starts no worker and uses no channel adapter. The host must
+persist an idempotency record before its side effect, return the saved receipt
+on duplicates, and refuse to repeat an uncertain dispatch. The daemon records
+failed/timeout fires without replaying them; a restart advances a stale claim
+once. `callOperator` addresses the live socket, with no cold-write fallback.
+`Orchestrator({executeJob})` is the corresponding in-process API for embedders.
+
+The daemon acquires its exclusive lease before loading state. A crash during the
+short acquisition critical section leaves `orchestrator.acquire`; subsequent
+starts fail closed until an operator inspects and removes that guard. Normal
+stops remove only their own lease. Native `jobs.resume` computes the first fire
+for a job that was created paused with no next-run timestamp.
+
+## Hosted daemon lifecycle
+
+`stopHostedDaemon({ root, executorUrl?, timeoutMs? })` validates the hosted lease
+and signals this package's daemon through its native shutdown handler. A foreign
+root/executor is refused; the lease is retained until shutdown completes. The
+helper does not clear a live lease or escalate to SIGKILL. Embedders can stop their
+owned clock before disabling the integration and start it again on the next boot.
+Hosted HTTP refusal messages preserve the executor's bounded JSON error reason.