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 nohumanorigin inferred from absent headers.runner— never a change of authority; it only appears on apermission_mismatchentry (see receipts below).
- Rule (
assertPermissionChange): lowering or keeping is always allowed. Raising: only thetokenorigin may raise, only with an explicitraise: truein the request (the CLI asks the person and sets it; without it403 session_permission_raise_unconfirmed), and only up to the executing runner's advertisedcapabilities.humanPermissionCap; no cap advertised, no raise (403 session_permission_cap). Theagentorigin 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 with409 parent_permission_changedand 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/resumekeep today's rule unchanged:permissionLevelmust be lower than or equal to the recorded level, else403 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
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:
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
- Body limit 2 KB; closed shape;
400 session_live_invalidotherwise. The payload is never logged, andpromptHeadis run through the session redaction patterns on ingest. atis 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 stampsliveStateReceivedAtwith its own clock, and freshness is judged on that.- Monotonic on
at: a beat older than the storedliveStateAtis not written and the response saysaccepted: false. An active beat (starting,running,waiting-for-user) also advanceslastActivityAt(monotonic), so--sort recentfollows 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). Asourcein the body is optional and may only agree (400otherwise). A runner may report only on a session bound to it (thestart/resumereceipt bindsrunnerId): 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'slastSeenAt. 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
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
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>:
| type | data |
|---|---|
ready | {at, sessionId, quietMs: 2000, maxDelayMs: 5000, timeoutMs: 900000, catchUp: false} |
liveState | the 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 |
heartbeat | same 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} |
receipt | any 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;
runStatefrom Nymph keeps its 45 s freshness rule and is separate fromliveState. - Runner / CLI: the
restartverb,--max-human-permission, the hook relay (sessions heartbeat, SubagentStart/Stop), runner heartbeats,sessions watch,sessions tree,sessions statusfalling 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 …/permissionmoves 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.