DreamLake

Sessions control plane — batch 2 (server side)

Status (2026-10-31): source on branch feat/sessions-batch2-server, not merged, not deployed. Server half of "Batch 2 — Ge's must-haves" in the session-integration master list (items 1, 4, 5, 8). The CLI / TypeScript API adapter and the hook relay are written from this page; the built-in agent reaches every verb below only through these routes (light integration: no fork of Claude Code or Codex, no shell on the server).

Every path is under the caller's personal namespace and takes the owner's bearer token. Runners authenticate as the same human. The built-in agent adds the usual attribution headers (x-dreamlake-agent-id, x-dreamlake-agent-turn, x-dreamlake-agent-tool-call); they decide origin, never authority. Errors are {error: <code>} with the status shown; unexpected failures are 503 session_control_unavailable.

Schema: TerminalSession gains permissionHistory, permissionChangedAt, permissionRevision (bumped by every authority change), observedPermissionLevel, liveState, liveStateAt, liveStateReceivedAt, liveStateSource, liveCurrent, sessionIsolation (plus permissionFence, a raw counter the parent-ceiling fence bumps, and ancestryFence, bumped by the parent-cycle walk; neither is read); SessionRunner gains offlineAt; new collection SessionSubagent with unique (sessionId, subagentId) and index (userId, updatedAt) (SessionSubagent_sessionId_subagentId_key, SessionSubagent_userId_updatedAt_idx). The deploy index preflight proposes those two indexes and refuses to create them during a deploy: apply them first through the schema-indexes workflow (plan, then apply), exactly as for NoteCommand (#1544). PRISMA_SCHEMA_REV=agent-memory-sessions-batch2-20261031 (shared with the agent-memory schema change that landed on main alongside). SessionCommand gains permissionRevision (a restart's snapshot). No data migration: an unset revision reads as 0.

1. Permission restart path (item 5)

Levels, origins, the rule

  • Levels, ordered: read-only < workspace-write < full-access.
  • Origins of a recorded change:
    • agent — the built-in agent, recognised only by attribution headers that name a conversation turn lease and that lease being fenced (conditional write) in the same transaction as the change. Header presence alone proves nothing.
    • token — every other holder of the owner's bearer token: the CLI, a script, a native agent that omitted the headers. The server cannot tell a token holder from a person, and no longer pretends to: there is no human origin inferred from absent headers.
    • runner — never a change of authority; it only appears on a permission_mismatch entry (see receipts below).
  • Rule (assertPermissionChange): lowering or keeping is always allowed. Raising: only the token origin may raise, only with an explicit raise: true in the request (the CLI asks the person and sets it; without it 403 session_permission_raise_unconfirmed), and only up to the executing runner's advertised capabilities.humanPermissionCap; no cap advertised, no raise (403 session_permission_cap). The agent origin never raises (403 session_permission_ceiling). A child session never passes its parent's level, whoever asks (403 parent_permission_ceiling); the parent is re-checked by a conditional write inside the restart / start / PATCH transaction, so a parent lowered meanwhile fails the request with 409 parent_permission_changed and nothing is enqueued or written.
  • What this does and does not guarantee. An agent that holds the owner's token and omits its attribution cannot be told from the owner's own CLI; the raise therefore needs the explicit raise: true, which a well-behaved CLI only sets after a person confirmed. That is a narrower guarantee than "an agent can never raise": it is "nothing raises without a request that says a person asked, and the built-in agent (the one path the server can identify) never raises at all".
  • send / resume keep today's rule unchanged: permissionLevel must be lower than or equal to the recorded level, else 403 session_permission_ceiling; they never change the record.

Runner registration

POST /namespaces/:slug/session-runners — capabilities accepts an optional humanPermissionCap: read-only | workspace-write | full-access. This is the runner-wide human cap (dl sessions serve --max-human-permission … on the CLI side). Absent means the old behaviour: the start level is a hard ceiling.

The runner view (POST / GET …/session-runners) carries online, lastSeenAt and offlineAt (see retirement below).

Runner retirement

DELETE /namespaces/:slug/session-runners/:id — the runner says goodbye (dl sessions serve calls it on exit) and is offline at once for routing (409 session_runner_offline for new commands) and for online in the runner list, instead of after 90 s of silence. Owner bearer token, as for register and heartbeat (the runner's credential is the owner's). Response { runner: <runner view> } with online: false and offlineAt set; 404 session_runner_not_found for an unknown or foreign id; idempotent — a second call answers 200 and keeps the first offlineAt. Any later sign of life (register, claim, renew, receipt, heartbeat / event with runnerId) clears offlineAt. Commands already routed to the runner stay pending until it registers again or the owner cancels them; running leases expire to uncertain on their own.

New command kind restart

POST /namespaces/:slug/session-commands

json
{ "kind": "restart", "input": { "sessionId": "<24-hex>", "permissionLevel": "workspace-write",
  "prompt": "optional, 1..16000", "mode": "tmux | headless (optional)", "reason": "optional, 1..200",
  "raise": true } }

permissionLevel is required; raise (boolean, optional) is the person's explicit confirmation and is only consulted when the level goes up. Routed like resume (bound runner, else the single online runner; the runner must advertise the provider and, when mode is given, that mode). The raise rule is evaluated against that runner's cap at submission; a refusal enqueues nothing. Archived sessions: 409 terminal_session_archived.

Runner contract (CLI side): stop the provider process, then resume the same native session under the new level, and post the receipt with the final command line:

json
{ "leaseToken": "…", "status": "completed",
  "result": { "sessionId": "<24-hex>", "permissionLevel": "workspace-write",
              "argv": ["claude", "--resume", "<native-id>", "--permission-mode", "acceptEdits"],
              "mode": "headless", "nativeSessionId": "<uuid>", "runState": "running" } }

A receipt never changes authority. On a completed start or restart receipt the server sets permissionLevel to the input's level — the one validated at submission — and appends one permissionHistory entry (the submitter's origin, reason from the input) when that differs from the recorded level; sets permissionChangedAt. The level the runner echoes is stored separately as observedPermissionLevel, for diagnostics only. When the echo disagrees with the authorized level (any difference on start / restart; a higher echo on resume / send), a second entry {level: <authority, unchanged>, origin: "runner", reason: "permission_mismatch", observedLevel: <echo>} is appended and authority stays where it was. A runner echoing full-access for a read-only restart therefore gets read-only recorded, a mismatch entry, and later resumes still capped at read-only.

Settlement is revision-based. Every change of authority (PATCH, an applied start / restart) bumps the session's permissionRevision. A restart is validated at enqueue against the authority of one revision and carries that number; when its receipt lands, inside the receipt transaction, the queued level is applied only if the session is still at that revision. Any change in between — a PATCH that lowered it, one that raised it, another restart — voids the queued level outright, whichever way it points: authority is left exactly where the later change put it, a mismatch entry {level: <current>, origin: "runner", reason: "authority_changed_during_restart", observedLevel: <what the runner ran>} is appended, and the receipt's result.effectivePermissionLevel says what the session is authorized at. So an agent restart queued at workspace-write then PATCHed to read-only stays read-only (whatever raise said), and a person's PATCH up to full-access is not undone by a queued read-only restart. A start may register a session that already holds authority; its level is then validated at completion exactly as a restart's is at enqueue (origin, cap, parent; a start carries no raise, so it never raises an existing authority) and, when refused, the refusal code is the entry's reason. The parent that bounds a start is the one it names, else the one the session already has (a start that re-registers a child names none; the child is still beneath its parent). Applying a level to a child also fences the parent's ceiling; a parent lowered meanwhile leaves authority untouched with reason parent_permission_changed. Every completed start / restart receipt carries result.effectivePermissionLevel; a runner whose process runs above it should treat the next resume / restart as the point where the record is re-applied. The session write is fenced on the revision it was decided against: a receipt racing a PATCH is refused with 409 session_permission_conflict and may be re-posted. Failed / uncertain receipts change nothing.

PATCH /namespaces/:slug/terminal-sessions/:id/permission

Body { "permissionLevel": "<level>", "reason"?: "1..200", "raise"?: boolean } (closed shape, 1 KB). Same rule as restart; the cap comes from the session's bound runner, else the owner's single online runner, else no cap. Only the record moves: the running process keeps its level until the next resume / restart re-applies the record (which is exactly why the rule has to be identical). The write is fenced on the authority revision the caller validated against (409 session_permission_conflict), on the parent's ceiling for a child (409 parent_permission_changed) and, for the agent, on the turn lease (409 agent_turn_not_current). Built-in agent conversations: 409 session_command_unsupported_provider.

Response { "session": <descriptor>, "changed": boolean }.

Descriptor fields

permissionLevel, observedPermissionLevel, permissionHistory (array of {level, origin, at, byUserId, reason?, observedLevel?}, oldest first, last 50) and permissionChangedAt are visible to the owner only; other viewers get null.

2. Hook-fed live state (item 1)

POST /namespaces/:slug/terminal-sessions/:id/heartbeat

json
{ "liveState": "starting | running | waiting-for-user | idle | stopped | uncertain",
  "current": { "tool": "<=128 chars, optional", "promptHead": "<=200 chars, optional" },
  "at": "<ISO-8601, 2000 <= at <= now+5min>", "source": "hook | runner (optional)", "runnerId": "<24-hex, optional>" }
  • Body limit 2 KB; closed shape; 400 session_live_invalid otherwise. The payload is never logged, and promptHead is run through the session redaction patterns on ingest.
  • at is the relay's own clock. It may run up to five minutes ahead of the server's and is clamped to the server's now on ingest, so a fast clock can neither block later beats nor look fresh; the server also stamps liveStateReceivedAt with its own clock, and freshness is judged on that.
  • Monotonic on at: a beat older than the stored liveStateAt is not written and the response says accepted: false. An active beat (starting, running, waiting-for-user) also advances lastActivityAt (monotonic), so --sort recent follows real activity.
  • Runner isolation. Who is reporting follows from runnerId: present, the beat comes from that runner (source: runner); absent, from the owner's non-runner context — the session's own hook relay (source: hook). A source in the body is optional and may only agree (400 otherwise). A runner may report only on a session bound to it (the start / resume receipt binds runnerId): the runner must be the owner's (404 session_runner_not_found) and must be the session's bound runner (409 session_runner_mismatch — another of the owner's runners, or a session nobody has bound yet). Same-owner runners therefore cannot speak for each other's sessions, while the hook relay, which names no runner, may report on any owned session. A runner beat also refreshes that runner's lastSeenAt. Runner cadence: 10 s.
  • 404 terminal_session_not_found (unknown or not owned), 409 session_command_unsupported_provider (built-in agent conversation).

Response: { accepted, liveState, liveStateReported, liveStateAt, liveStateReceivedAt, liveStateSource, current }.

Reads and the staleness rule

Every session descriptor (GET /namespaces/:slug/terminal-sessions, GET /terminal-sessions/available, GET …/:id/metadata, GET …/:id) now carries liveState, liveStateReported, liveStateAt, liveStateReceivedAt, liveStateSource, current. liveState is the effective state: a reported starting or running whose liveStateReceivedAt (the server's receipt clock; liveStateAt for rows written before it existed) is older than 60 s reads as uncertain (liveStateReported keeps the raw value). waiting-for-user, idle, stopped do not go stale. Other viewers see current.tool but not promptHead. runState (Nymph / runner observation) is unchanged and still present.

GET …/:id/metadata needs no terminal-gateway binding, so sessions status can show the live state for native and runner sessions instead of 409 / 503 (CLI change).

3. Subagent events and the tree (items 4 / 8)

POST /namespaces/:slug/terminal-sessions/:id/events

json
{ "kind": "SubagentStart | SubagentStop", "subagentId": "^[A-Za-z0-9._:-]{1,128}$",
  "name": "optional, <=128", "at": "<ISO-8601>", "finished": "<ISO-8601, optional>",
  "tokens": 0, "source": "hook | runner (optional)", "runnerId": "<24-hex, optional>" }

runnerId / source follow the heartbeat's runner-isolation rule exactly (404 session_runner_not_found, 409 session_runner_mismatch).

Closed shape, 2 KB, 400 session_event_invalid; at / finished are clamped like heartbeat clocks; tokens is an integer total in 0..2147483647 (the column is a 32-bit Int). One child row per (session, subagentId), merged by one atomic pipeline update (no read, no second step) whose expressions all see the row as it was, so interleaved relays cannot overwrite each other and a watcher never sees a lifecycle change without its metadata: a Start only lowers startedAt; a Stop only raises finishedAt (finished, default at); a replayed or late Start never clears a recorded finish; lastEvent, source, tokens and name follow the newest event by its own at, so an older event landing late (a replay, a slower relay) never overwrites a newer total or name; updatedAt is stamped by every accepted event in that same write. A Stop with no Start seen still records a finished child. Two first events racing for one new row: one inserts, the other retries once as an update, then 409 session_event_contended. Response { sessionId, subagent: <subagent node> }.

GET /namespaces/:slug/terminal-sessions/:id/tree

json
{ "session": <node>, "nodeCount": n, "subagentCount": n, "truncated": false, "cycleDetected": false }

Session node: { id, kind: "session", name, provider, parentSessionId, liveState, liveStateAt, current, permissionLevel, isolation, pod, cwd, repositoryRoot, runnerId, tokens: null, finishedAt, createdAt, children: [...] } — isolation is what the runner recorded at start ({kind: repo|worktree|pod, repo, branch?, baseRef?, cwd?, mode?}; null for sessions started before this change or registered by Nymph), pod is the sandbox binding, finishedAt is archivedAt or the stopped beat. Children are managed child sessions (by parentSessionId, breadth-first, depth ≤ 3, ≤ 200 nodes) followed by native subagents of that node.

Subagent node: { id: subagentId, kind: "subagent", name, liveState, startedAt, finishedAt, tokens, lastEvent, lastEventAt, source } — liveState is stopped when finished, uncertain when open under a stopped/uncertain parent, else running.

Beyond the bounds (depth, nodes, 500 subagents) the read says truncated: true. A parent link that loops back is cut at the first repeat and reported as cycleDetected: true; a start receipt whose parentSessionId would make the registered session its own ancestor is refused with 409 session_parent_cycle. The walk runs only when the receipt sets or changes the link (a completion that keeps the recorded parent writes no ancestor) and then fence-writes every ancestor it reads (ancestryFence, a raw counter) inside the receipt transaction, so two reciprocal start receipts completing at once cannot both link: one aborts on a write conflict, is run again (the control-plane transactions retry a MongoDB write conflict up to three times with a short random pause) and, seeing the committed link, is refused.

4. Watch stream (item 1)

GET /namespaces/:slug/terminal-sessions/watch[?sessionId=<24-hex>] — text/event-stream. Any other query key: 400 session_watch_invalid; unknown session: 404. Frames are event: <type> + data: <json>:

typedata
ready{at, sessionId, quietMs: 2000, maxDelayMs: 5000, timeoutMs: 900000, catchUp: false}
liveStatethe effective state differs from the last one this stream emitted: {sessionId, liveState, liveStateReported, liveStateAt, liveStateReceivedAt, liveStateSource, current, at}. This includes the lapse into uncertain 60 s after the last starting / running beat, emitted once from the stream's own memory with no new write behind it, and the revival when the next beat arrives
heartbeatsame state, newer beat (including an accepted re-beat with an unchanged at, which refreshes liveStateReceivedAt); same fields. The stream's expiry clock follows the stored receipt time, so it never calls uncertain what the descriptor still reads as running
subagent{sessionId, subagent: <subagent node>, at}
receiptany control command reaching completed / failed / cancelled / uncertain: {sessionId, command: <command view incl. result>, at} (a restart's echoed argv arrives here)
permission{sessionId, permissionLevel, permissionChangedAt, entry: <last history entry>, at}
end{reason: "timeout", at} after 15 minutes; the client reconnects
error{error: access_expired | access_unavailable | session_watch_unavailable, at}, then close

Batching: events are held until 2 s of quiet or 5 s after the first held one, then written together. : keepalive comment and re-authorization every 15 s. Implementation: the server polls its own tables once a second behind a 5-minute skew window and dedupes per subject, so a write on any replica reaches every watcher. Live changes are found and keyed on the server's receipt clock (liveStateReceivedAt), never on the relayed at: a relay that keeps re-posting the same observation stays visible to the stream however old its at is, and the stream's expiry judges the same clock the descriptor does. Each poll reads its tables to the end (id-ordered pages of 200, up to 25 pages per tick; a longer pass continues from its cursor on the next tick) before it moves its watermark, so a burst larger than one page is delivered, never skipped.

No durable catch-up this phase, and no accidental one either. Before any header goes out, the server reads the whole skew window into the connection's memory (the baseline, up to four passes) and discards it, so the stream carries exactly what happens after ready.at — a reconnect does not replay the receipts, permission changes, subagent rows or beats from the last five minutes. A session already uncertain at connection is not announced again; one still running at connection lapses later as a real transition. If the window cannot be read within those passes the request is refused with 503 session_watch_unavailable as a plain JSON error (no half-open stream). After end or a disconnect the client re-reads GET …/terminal-sessions (and /tree for subagents) before reconnecting. There are no event ids and no since cursor.

Not done here

  • Nymph fixes (macOS Claude process detection, staleness cap, synthetic tmuxSession, file logging, relaunch loop): untouched; runState from Nymph keeps its 45 s freshness rule and is separate from liveState.
  • Runner / CLI: the restart verb, --max-human-permission, the hook relay (sessions heartbeat, SubagentStart/Stop), runner heartbeats, sessions watch, sessions tree, sessions status falling back to live state — all written from this contract on the CLI side.
  • On-the-fly permission change (PreToolUse hook reading a per-session policy): not started; PATCH …/permission moves the record only.
  • Durable catch-up / event ids for the watch stream; team-scope watch (the stream is owner-scoped like the rest of the control plane).
  • Tokens for session nodes (tokens: null): only subagent tokens are relayed.

Validation

Server only: tsc clean; src/session-control/*.test.ts (store, routes, live, live-routes), src/routes/terminal-sessions.test.ts, src/routes/session-registration.test.ts, src/ci/changeClassifier.test.ts pass with mocked Prisma. No database run, no deployment, no production evidence.