@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/session/store.mjs

@@ -0,0 +1,299 @@
+/**
+ * lib/engine/session/store.mjs — JSONL session transcripts.
+ *
+ * One file per session: `<dir>/<sessionId>.jsonl`, keyed by a CALLER-SUPPLIED
+ * id (maestro's dispatcher chooses the id so it can resume a thread later).
+ * Append-only; each line is one record:
+ *
+ *   { type:'session', version:1, sessionId, ts, cwd, model, wire }   first line
+ *   { type:'resume',  sessionId, ts }                                 each resume
+ *   { type:'message', sessionId, ts, message }                        conversation
+ *   { type:'result',  sessionId, ts, result }                         per run summary
+ *
+ * Appends go through `appendJsonl` (one write per line), so a crash can at
+ * worst leave a torn LAST line. Parsing skips unparseable lines and counts
+ * them rather than refusing the session — losing one half-written message is
+ * recoverable; losing a thread is not. A tool call left unanswered by a crash
+ * is closed by `normaliseHistory` when the history is next sent.
+ *
+ * Parsing and reconstruction are pure; `openSession` / `append*` are the edge.
+ *
+ * One writer per session (W4 integration, conformance row 4): a run holds
+ * `<dir>/<sessionId>.lock` for its whole life (`acquireSessionLock`). The lock
+ * names the holder's pid and its process start time; a lock whose holder is no
+ * longer alive — or whose pid now belongs to a process that started at another
+ * time (pid reuse after a crash, W4-E1) — is stale and is taken over, so a
+ * crashed run never strands its thread. A live holder
+ * refuses a second writer (`session_locked`), whether it continues by
+ * `--session-id` or by `--resume`.
+ *
+ * @module lib/engine/session/store
+ */
+
+import { closeSync, linkSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { appendJsonl } from "../../fs-atomic.mjs";
+import { processAlive, processStartToken, sameStartTime } from "../process-identity.mjs";
+
+export const TRANSCRIPT_VERSION = 1;
+
+/** Ids become file names: no separators, no dot-dot, bounded length. */
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** @param {unknown} id @returns {id is string} */
+export function isValidSessionId(id) {
+  return typeof id === "string" && ID_RE.test(id) && !id.includes("..");
+}
+
+/** @param {string} dir @param {string} id */
+export function sessionPath(dir, id) {
+  return path.join(dir, `${id}.jsonl`);
+}
+
+/**
+ * @param {string} text
+ * @returns {{ records: any[], skipped: number }}
+ */
+export function parseTranscript(text) {
+  const records = [];
+  let skipped = 0;
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    try {
+      const r = JSON.parse(line);
+      if (r && typeof r === "object" && typeof r.type === "string") records.push(r);
+      else skipped++;
+    } catch {
+      skipped++; // a torn line from a crashed append; the rest of the thread is intact
+    }
+  }
+  return { records, skipped };
+}
+
+/** @param {any[]} records */
+export function messagesFromRecords(records) {
+  return records
+    .filter((r) => r.type === "message" && r.message && (r.message.role === "user" || r.message.role === "assistant"))
+    .map((r) => r.message);
+}
+
+/**
+ * @typedef {{ id:string, path:string, messages:any[], skipped:number, writeFailures:number }} Session
+ * @typedef {{ id:string, path:string, messages:any[], skipped:number, writeFailures:number, continued?:boolean }} OpenedSession
+ * @typedef {{ code:'invalid_session_id'|'session_exists'|'session_not_found'|'session_unreadable'|'session_unwritable'|'session_locked', message:string }} SessionError
+ */
+
+/**
+ * Open a session for a run.
+ *
+ *   new       claim a fresh id; an existing one is `session_exists`
+ *   resume    continue an existing id; a missing one is `session_not_found`
+ *   continue  claim the id, or continue it when it exists — what a caller-chosen
+ *             `--session-id` reused across turns means (maestro's dispatcher
+ *             crash recovery and responder continuation re-spawn the same id
+ *             with a new prompt). The caller holds the session lock first.
+ *
+ * @param {object} p
+ * @param {string} p.dir
+ * @param {string} p.sessionId
+ * @param {'new'|'resume'|'continue'} p.mode
+ * @param {{cwd:string, model:string, wire:string}} p.meta
+ * @param {() => number} [p.now]
+ * @returns {{ ok:true, session: Session } | { ok:false, error: SessionError }}
+ */
+export function openSession({ dir, sessionId, mode, meta, now = Date.now }) {
+  if (!isValidSessionId(sessionId)) {
+    return { ok: false, error: { code: "invalid_session_id", message: `invalid session id "${sessionId}"` } };
+  }
+  const file = sessionPath(dir, sessionId);
+  const ts = new Date(now()).toISOString();
+  if (mode === "new" || mode === "continue") {
+    // Claim the id with an exclusive create (O_EXCL), not exists-then-append:
+    // two runs started with the same --session-id would both pass an existence
+    // check and interleave one transcript. The claim writes no bytes; the
+    // header goes through the append seam like every other record.
+    try {
+      mkdirSync(dir, { recursive: true });
+      closeSync(openSync(file, "wx"));
+    } catch (e) {
+      if (/** @type any */ (e)?.code === "EEXIST") {
+        if (mode === "continue") return resumeSession({ file, dir, sessionId, ts, meta, continued: true });
+        return { ok: false, error: { code: "session_exists", message: `session ${sessionId} already exists; use --resume` } };
+      }
+      return { ok: false, error: { code: "session_unwritable", message: `cannot create ${file}: ${e instanceof Error ? e.message : e}` } };
+    }
+    const header = { type: "session", version: TRANSCRIPT_VERSION, sessionId, ts, ...meta };
+    if (!appendJsonl(file, header)) {
+      return { ok: false, error: { code: "session_unwritable", message: `cannot write ${file}` } };
+    }
+    return { ok: true, session: { id: sessionId, path: file, messages: [], skipped: 0, writeFailures: 0 } };
+  }
+  return resumeSession({ file, dir, sessionId, ts, meta, continued: false });
+}
+
+/**
+ * @param {{file:string, dir:string, sessionId:string, ts:string, meta:{cwd:string, model:string, wire:string}, continued:boolean}} p
+ * @returns {{ ok:true, session: OpenedSession } | { ok:false, error: SessionError }}
+ */
+function resumeSession({ file, dir, sessionId, ts, meta, continued }) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    const missing = /** @type any */ (e)?.code === "ENOENT";
+    return {
+      ok: false,
+      error: missing
+        ? { code: "session_not_found", message: `no session ${sessionId} in ${dir}` }
+        : { code: "session_unreadable", message: `cannot read ${file}: ${e instanceof Error ? e.message : e}` },
+    };
+  }
+  const { records, skipped } = parseTranscript(text);
+  /** @type {OpenedSession} */
+  const session = { id: sessionId, path: file, messages: messagesFromRecords(records), skipped, writeFailures: 0, ...(continued ? { continued: true } : {}) };
+  // A claim whose run died before its header was written: the continuing run writes it.
+  if (continued && !records.some((r) => r.type === "session")) {
+    if (!appendJsonl(file, { type: "session", version: TRANSCRIPT_VERSION, sessionId, ts, ...meta })) session.writeFailures++;
+    return { ok: true, session };
+  }
+  if (!appendJsonl(file, { type: "resume", sessionId, ts })) session.writeFailures++;
+  return { ok: true, session };
+}
+
+/** @param {string} dir @param {string} id */
+export function sessionLockPath(dir, id) {
+  return path.join(dir, `${id}.lock`);
+}
+
+// The process-identity primitives (the fixed `ps` probe environment, epoch parsing with its 1 s
+// tolerance, /proc on Linux) have one implementation, shared with task states and workflow
+// journals: ../process-identity.mjs. The session lock's own policy (`lockHolderLive`) stays here.
+/**
+ * Is the lock holder the process that took the lock? Pure over its inputs.
+ * A pid that is not alive is not the holder. A pid that is alive is the holder
+ * unless both start times are known, comparable, and differ — the pid was
+ * reused by an unrelated process after the holder died. An unknown or
+ * incomparable start time (an older lock, a platform with no answer) keeps the
+ * pid check alone: the safe direction is to refuse a second writer.
+ *
+ * Why not process-identity.mjs `judgeOwner`: that judgement treats a record from
+ * this PID with another nonce as a dead predecessor, which is right for a task
+ * state read back after a restart but wrong for a lock — a second run inside the
+ * same process (an in-process host, a test) is a second writer and must be
+ * refused. The primitives (probe, parsing, comparison) are the shared ones.
+ * @param {{pid:number, startedAt?:string|null}} holder
+ * @param {{isAlive:(pid:number)=>boolean, startTimeOf:(pid:number)=>string|null}} probe
+ */
+export function lockHolderLive(holder, { isAlive, startTimeOf }) {
+  if (!isAlive(holder.pid)) return false;
+  const recorded = typeof holder.startedAt === "string" && holder.startedAt ? holder.startedAt : null;
+  if (recorded === null) return true;
+  const current = startTimeOf(holder.pid);
+  if (current === null) return true;
+  return sameStartTime(recorded, current) !== false;
+}
+
+/**
+ * Hold a session's single-writer lock for the life of a run.
+ *
+ * The lock body is written to a private temp file and linked into place
+ * (`link` fails when the name exists), so a reader never sees a half-written
+ * lock. A lock that names a pid no longer alive, or that cannot be parsed, is
+ * stale: it is removed only if it still has the content that was judged stale,
+ * then claimed again. `release` removes the lock only while it is still ours.
+ *
+ * @param {object} p
+ * @param {string} p.dir
+ * @param {string} p.sessionId
+ * @param {number} [p.pid]
+ * @param {(pid:number) => boolean} [p.isAlive]
+ * @param {(pid:number) => string|null} [p.processStartTime]  a process's start time
+ *        (default process-identity.mjs `processStartToken`; when only `isAlive` is injected, none: the pid check alone)
+ * @param {() => number} [p.now]
+ * @returns {{ ok:true, release:() => void, tookOver:number|null } | { ok:false, error: SessionError }}
+ */
+export function acquireSessionLock({ dir, sessionId, pid = process.pid, isAlive = processAlive, processStartTime: startTimeOf, now = Date.now }) {
+  if (!isValidSessionId(sessionId)) {
+    return { ok: false, error: { code: "invalid_session_id", message: `invalid session id "${sessionId}"` } };
+  }
+  // Pid reuse: the lock records the holder's start time, and a holder is live only
+  // while the process with that pid still has it. A test that injects `isAlive`
+  // alone keeps a pure pid table (the real process table would answer for its fake pids).
+  const startOf = typeof startTimeOf === "function" ? startTimeOf : isAlive === processAlive ? processStartToken : () => null;
+  const file = sessionLockPath(dir, sessionId);
+  const body = JSON.stringify({ pid, startedAt: startOf(pid), sessionId, acquiredAt: new Date(now()).toISOString(), nonce: randomUUID() });
+  const unwritable = (/** @type unknown */ e) => ({ ok: /** @type {const} */ (false), error: /** @type {SessionError} */ ({ code: "session_unwritable", message: `cannot lock ${file}: ${e instanceof Error ? e.message : e}` }) });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(tmp, body, { mode: 0o600 });
+  } catch (e) {
+    return unwritable(e);
+  }
+  /** @type {number|null} */
+  let tookOver = null;
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        linkSync(tmp, file);
+        const release = () => {
+          try {
+            if (readFileSync(file, "utf8") === body) unlinkSync(file);
+          } catch {
+            /* already gone */
+          }
+        };
+        return { ok: true, release, tookOver };
+      } catch (e) {
+        if (/** @type any */ (e)?.code !== "EEXIST") return unwritable(e);
+      }
+      let held;
+      try {
+        held = readFileSync(file, "utf8");
+      } catch (e) {
+        if (/** @type any */ (e)?.code === "ENOENT") continue; // released between our link and read
+        return unwritable(e);
+      }
+      /** @type {any} */
+      let holder = null;
+      try {
+        holder = JSON.parse(held);
+      } catch {
+        holder = null;
+      }
+      const holderPid = holder && Number.isInteger(holder.pid) && holder.pid > 0 ? holder.pid : null;
+      if (holderPid !== null && lockHolderLive({ pid: holderPid, startedAt: holder.startedAt ?? null }, { isAlive, startTimeOf: startOf })) {
+        return { ok: false, error: { code: "session_locked", message: `session ${sessionId} is in use by a live process (pid ${holderPid}); a session has one writer at a time` } };
+      }
+      // Stale: remove it only if it is still the lock we judged.
+      try {
+        if (readFileSync(file, "utf8") === held) unlinkSync(file);
+      } catch {
+        /* gone already, or replaced: the next attempt decides */
+      }
+      tookOver = holderPid;
+    }
+    return { ok: false, error: { code: "session_locked", message: `session ${sessionId}: the lock kept changing hands; try again` } };
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+/** @param {Session} session @param {any} message @param {() => number} [now] */
+export function appendMessage(session, message, now = Date.now) {
+  const ok = appendJsonl(session.path, { type: "message", sessionId: session.id, ts: new Date(now()).toISOString(), message });
+  if (!ok) session.writeFailures++;
+  return ok;
+}
+
+/** @param {Session} session @param {any} result @param {() => number} [now] */
+export function appendResult(session, result, now = Date.now) {
+  const ok = appendJsonl(session.path, { type: "result", sessionId: session.id, ts: new Date(now()).toISOString(), result });
+  if (!ok) session.writeFailures++;
+  return ok;
+}

package/lib/engine/session-runtime/args.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/engine/session-runtime/args.mjs — the `cohort session` command line.
+ *
+ *   cohort session --name <name> [--session-id <uuid> | --resume <uuid>] [--replace]
+ *     [every `cohort run` flag except -p/--print, --output-format, --input-format,
+ *      --include-partial-messages] ["<initial prompt>"]
+ *
+ * The session's run is `cohort run` in multi-turn stream-json mode, so the
+ * shared flags are validated by `parseRunArgs` itself (one parser, no drift).
+ * A session with neither --session-id nor --resume gets a fresh id.
+ *
+ * Pure.
+ *
+ * @module lib/engine/session-runtime/args
+ */
+
+import { randomUUID } from "node:crypto";
+import { parseRunArgs, RUN_FLAGS } from "../cli.mjs";
+import { isValidSessionName } from "./registry.mjs";
+
+/** Flags the session sets itself. */
+export const SESSION_REFUSED_FLAGS = Object.freeze(["-p", "--print", "--output-format", "--input-format", "--include-partial-messages"]);
+/** Every flag `parseSessionArgs` accepts (the adapter's drift test reads this). */
+export const SESSION_FLAGS = Object.freeze([...RUN_FLAGS.filter((f) => !SESSION_REFUSED_FLAGS.includes(f)), "--name", "--replace"]);
+
+export const SESSION_USAGE = `Usage: cohort session --name <name> [--session-id <id> | --resume <id>] [flags] ["<initial prompt>"]
+
+A long-lived Cohort Engine session. In a terminal it is interactive: type a
+message and press Enter (paste keeps line breaks; end a line with \\ to continue
+it), Ctrl-C interrupts the current turn, Ctrl-D exits. It also listens on a local
+control socket (see docs/engine/README.md) for messages from other sessions and
+for interrupt / compact / status / shutdown. Without a terminal it runs from the
+socket and the initial prompt only, printing stream-json events.
+
+Session flags:
+  --name <name>                The session's unique name on this machine (required)
+  --replace                    Take the name from a running session (it is shut down)
+  --session-id <id>            Start a new transcript with this id (default: a new id)
+  --resume <id>                Continue a transcript; a pending wakeup is armed again
+
+Every other \`cohort run\` flag applies (model, permissions, MCP, settings, agents, …);
+see \`cohort run --help\`. --max-turns and --wall-clock-ms apply to each turn.
+
+Environment:
+  COHORT_SESSION_DIR           Session registry and sockets (default ~/.cohort/sessions)
+`;
+
+/**
+ * @param {string[]} argv  arguments after `session` (a leading `session` is tolerated)
+ * @param {{newId?:()=>string}} [o]
+ * @returns {{ok:true, help:true} | {ok:true, help:false, name:string, replace:boolean, sessionId:string, resume:boolean, prompt:string|null, runArgv:string[], opts:Record<string,any>} | {ok:false, error:string}}
+ */
+export function parseSessionArgs(argv, { newId = randomUUID } = {}) {
+  const args = [...argv];
+  if (args[0] === "session") args.shift();
+  let name = null;
+  let replace = false;
+  let help = false;
+  /** @type {string[]} */
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--") {
+      rest.push(...args.slice(i));
+      break;
+    }
+    const eq = a.startsWith("--") ? a.indexOf("=") : -1;
+    const flag = eq === -1 ? a : a.slice(0, eq);
+    if (flag === "--name") {
+      const v = eq === -1 ? args[++i] : a.slice(eq + 1);
+      if (v === undefined) return { ok: false, error: "--name needs a value" };
+      name = v;
+    } else if (flag === "--replace") {
+      replace = true;
+    } else if (flag === "-h" || flag === "--help") {
+      help = true;
+    } else if (SESSION_REFUSED_FLAGS.includes(flag)) {
+      return { ok: false, error: `${flag} is not a session flag: a session always reads and writes stream-json turns` };
+    } else {
+      rest.push(a);
+    }
+  }
+  if (help) return { ok: true, help: true };
+  if (name === null) return { ok: false, error: "--name is required" };
+  if (!isValidSessionName(name)) return { ok: false, error: `invalid --name "${name}" (letters, digits, dot, dash, underscore; at most 64)` };
+  const parsed = parseRunArgs(rest);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const o = parsed.opts;
+  const resume = typeof o.resume === "string";
+  const sessionId = o.resume ?? o.sessionId ?? newId();
+  const idFlags = o.resume || o.sessionId ? [] : ["--session-id", sessionId];
+  const cut = rest.indexOf("--");
+  const head = cut === -1 ? rest : rest.slice(0, cut);
+  const tail = cut === -1 ? [] : rest.slice(cut);
+  const runArgv = [...head, ...idFlags, "--input-format", "stream-json", "--output-format", "stream-json", "--include-partial-messages", ...tail];
+  return { ok: true, help: false, name, replace, sessionId, resume, prompt: o.prompt ?? null, runArgv, opts: o };
+}

package/lib/engine/session-runtime/host.mjs

@@ -0,0 +1,143 @@
+/**
+ * lib/engine/session-runtime/host.mjs — what `cohort session` plugs into a run.
+ *
+ * cli.mjs runs one session exactly like a multi-turn stream-json run; a host
+ * (passed as `deps.host`) adds the front-door parts:
+ *
+ *   notices        the event queue the loop drains (shell exits, monitor lines,
+ *                  background subagents' reports) — and that wakes the idle inbox
+ *   inbox          the turn source (inbox.mjs): typed input, socket messages,
+ *                  wakeups, event batches; one turn at a time
+ *   tools(ctx)     ListAgents, SendMessage, ScheduleWakeup, Monitor — created
+ *                  once the session is open (the scheduler writes its transcript,
+ *                  and re-arms a pending wakeup on --resume)
+ *   toolNames      their names, so `--tools` may name them
+ *   askPermission  the terminal's y / n / always answer to a standing `ask`
+ *                  (null when headless: asks are refused as in `cohort run`)
+ *   turnSignal()   a fresh abort signal per turn; `interrupt()` aborts it
+ *                  without ending the session
+ *
+ * In a session, background subagents are not stopped when a turn ends and a
+ * turn does not wait for them: their report arrives as an event.
+ *
+ * @module lib/engine/session-runtime/host
+ */
+
+import { readFileSync } from "node:fs";
+import { appendJsonl } from "../../fs-atomic.mjs";
+import { parseTranscript } from "../session/store.mjs";
+import { createNotificationQueue } from "./notifications.mjs";
+import { createSessionInbox } from "./inbox.mjs";
+import { createWakeupScheduler, pendingWakeup, wakeupTurnText } from "./wakeup.mjs";
+import { createListAgentsTool } from "../tools/list-agents.mjs";
+import { createSendMessageTool } from "../tools/send-message.mjs";
+import { createScheduleWakeupTool } from "../tools/schedule-wakeup.mjs";
+import { createMonitorTool } from "../tools/monitor.mjs";
+
+export const FRONT_DOOR_TOOL_NAMES = Object.freeze(["ListAgents", "SendMessage", "ScheduleWakeup", "Monitor"]);
+
+/**
+ * @param {{name:string, registry:any, busy?:boolean, signal?:AbortSignal,
+ *          ask?:((q:{toolName:string, input:unknown, reason:string, signal?:AbortSignal})=>Promise<'allow'|'deny'|'always'>)|null,
+ *          msPerSecond?:number, now?:()=>number, batchMs?:number,
+ *          onState?:(state:'idle'|'busy', why:any)=>void, onWakeup?:(w:{prompt:string, reason:string})=>void,
+ *          send?:any}} o
+ */
+export function createSessionHost({ name, registry, busy = false, signal, ask = null, msPerSecond = 1000, now = Date.now, batchMs, onState, onWakeup, send }) {
+  const notices = createNotificationQueue();
+  const inbox = createSessionInbox({ notices, busy, batchMs, onState });
+  /** @type {ReturnType<typeof createWakeupScheduler>|null} */
+  let wakeups = null;
+  /** @type {any} */
+  let shells = null;
+  /** @type {AbortController|null} */
+  let current = null;
+  /** @type {(() => void)|null} */
+  let unlink = null;
+  /**
+   * What the user allowed for the rest of the session, per asking agent and tool:
+   * "main:Bash", or "<subagent id>:Bash". An `a` given to the main loop does not
+   * also approve a background subagent's call, and the reverse.
+   */
+  const always = new Set();
+  const alwaysKey = (/** @type {{toolName:string, agentId?:string|null}} */ q) => `${q.agentId ?? "main"}:${q.toolName}`;
+
+  return {
+    notices,
+    inbox,
+    toolNames: FRONT_DOOR_TOOL_NAMES,
+    /**
+     * @param {{session:{id:string, path:string}, kit:any, checkCommand?:(command:string)=>{behavior:'allow'|'deny'|'ask', reason:string}}} ctx
+     */
+    tools({ session, kit, checkCommand }) {
+      shells = kit.shells;
+      wakeups = createWakeupScheduler({
+        append: (record) => appendJsonl(session.path, { ...record, sessionId: session.id }),
+        fire: (w, started) => {
+          if (inbox.state === "ended") return false;
+          onWakeup?.(w);
+          return inbox.deliver({ text: wakeupTurnText(w), kind: "wakeup", onStart: started }) !== "ended";
+        },
+        now,
+        msPerSecond,
+      });
+      let records = [];
+      try {
+        records = parseTranscript(readFileSync(session.path, "utf8")).records;
+      } catch {
+        /* a new transcript */
+      }
+      const pending = pendingWakeup(records);
+      if (pending) wakeups.arm(pending);
+      return [
+        createListAgentsTool({ selfName: name, registry, now }),
+        createSendMessageTool({ selfName: name, registry, ...(send ? { send } : {}) }),
+        createScheduleWakeupTool({ scheduler: wakeups }),
+        createMonitorTool({ shells: kit.shells, notices, cwd: () => kit.bash.cwd, checkCommand: checkCommand ?? null }),
+      ];
+    },
+    askPermission: ask
+      ? async (/** @type {{toolName:string, input:unknown, reason:string, signal?:AbortSignal, agentId?:string|null}} */ q) => {
+          if (always.has(alwaysKey(q))) return "allow";
+          const a = await ask(q);
+          if (a === "always") {
+            always.add(alwaysKey(q));
+            return "allow";
+          }
+          return a === "allow" ? "allow" : "deny";
+        }
+      : null,
+    /** A new signal for the turn that is starting. */
+    turnSignal() {
+      unlink?.();
+      const c = new AbortController();
+      current = c;
+      const onAbort = () => c.abort();
+      if (signal?.aborted) c.abort();
+      else signal?.addEventListener("abort", onAbort, { once: true });
+      unlink = () => signal?.removeEventListener("abort", onAbort);
+      return c.signal;
+    },
+    /** Stop the running turn; the session stays. @returns {boolean} whether a turn was running */
+    interrupt() {
+      if (inbox.state !== "busy" || !current || current.signal.aborted) return false;
+      current.abort();
+      return true;
+    },
+    status() {
+      const w = wakeups?.current() ?? null;
+      return {
+        state: inbox.state,
+        queued: inbox.queued,
+        pendingEvents: notices.size,
+        wakeup: w ? { dueAt: new Date(w.dueAt).toISOString(), reason: w.reason } : null,
+        monitors: shells ? shells.list().filter((/** @type any */ s) => s.kind === "monitor" && s.status === "running").map((/** @type any */ s) => ({ id: s.id, description: s.description })) : [],
+      };
+    },
+    dispose() {
+      wakeups?.dispose();
+      unlink?.();
+      inbox.end();
+    },
+  };
+}

package/lib/engine/session-runtime/inbox.mjs

@@ -0,0 +1,122 @@
+/**
+ * lib/engine/session-runtime/inbox.mjs — what a `cohort session` works on next.
+ *
+ * The session's run (cli.mjs, `--input-format stream-json`) reads user turns
+ * from `lines()`. The inbox hands it a turn only when the session is idle:
+ *
+ *   idle ──(a message, a wakeup, or a batch of events)──► busy ──(the turn's result)──► idle
+ *
+ *   · `deliver` — a user turn (typed, from the socket, a wakeup). Idle with
+ *     nothing waiting: it starts now ("delivered"). Otherwise it waits its turn
+ *     ("queued"), first in first out.
+ *   · events (notifications.mjs) — while busy they reach the running turn at
+ *     its next model request; while idle, events arriving within `batchMs` of
+ *     each other are gathered into one turn. Queued user turns go first.
+ *   · `control` — a compact request goes to the run at once; the run applies it
+ *     at the next turn boundary.
+ *   · `end` — no further turns; the run finishes after the current one.
+ *
+ * Nothing here calls a model: while idle the session makes no requests.
+ *
+ * @module lib/engine/session-runtime/inbox
+ */
+
+/**
+ * @param {{notices:ReturnType<typeof import('./notifications.mjs').createNotificationQueue>, busy?:boolean, batchMs?:number,
+ *          onState?:(state:'idle'|'busy', why:{kind:string, from?:string|null})=>void,
+ *          setTimer?:(fn:()=>void, ms:number)=>any, clearTimer?:(t:any)=>void}} o
+ */
+export function createSessionInbox({ notices, busy = false, batchMs = 150, onState = () => {}, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  /** @type {'idle'|'busy'|'ended'} */
+  let state = busy ? "busy" : "idle";
+  /** @type {Array<{text:string, kind:string, from:string|null, onStart?:()=>void}>} */
+  const waiting = [];
+  /** @type {string[]} */
+  const out = [];
+  /** @type {(() => void)|null} */
+  let wake = null;
+  /** @type {any} */
+  let batchTimer = null;
+
+  const emit = (/** @type string */ line) => {
+    out.push(line);
+    const w = wake;
+    wake = null;
+    w?.();
+  };
+  const startTurn = (/** @type string */ text, /** @type {{kind:string, from?:string|null}} */ why, /** @type {(() => void)|undefined} */ onStart = undefined) => {
+    state = "busy";
+    emit(JSON.stringify({ type: "user", message: { role: "user", content: text } }));
+    onStart?.();
+    onState("busy", why);
+  };
+  const pump = () => {
+    if (state !== "idle") return;
+    const next = waiting.shift();
+    if (next) {
+      startTurn(next.text, { kind: next.kind, from: next.from }, next.onStart);
+      return;
+    }
+    if (!notices.hasPending() || batchTimer) return;
+    batchTimer = setTimer(() => {
+      batchTimer = null;
+      if (state !== "idle") return;
+      if (waiting.length > 0) return pump();
+      const texts = notices.drain();
+      if (texts.length > 0) startTurn(texts.join("\n\n"), { kind: "events" });
+    }, batchMs);
+  };
+  const unsubscribe = notices.onAvailable(pump);
+
+  return {
+    get state() {
+      return state;
+    },
+    get queued() {
+      return waiting.length;
+    },
+    /**
+     * @param {{text:string, kind?:string, from?:string|null, onStart?:()=>void}} m
+     *   `onStart` runs when the turn actually starts (never, if the session ends first).
+     * @returns {'delivered'|'queued'|'ended'}
+     */
+    deliver({ text, kind = "user", from = null, onStart }) {
+      if (state === "ended") return "ended";
+      if (state === "idle" && waiting.length === 0) {
+        startTurn(text, { kind, from }, onStart);
+        return "delivered";
+      }
+      waiting.push({ text, kind, from, onStart });
+      return "queued";
+    },
+    /** A control line for the run (compact). @param {object} line */
+    control(line) {
+      if (state !== "ended") emit(JSON.stringify(line));
+    },
+    /** The run wrote a turn's result. */
+    turnEnded() {
+      if (state !== "busy") return;
+      state = "idle";
+      onState("idle", { kind: "result" });
+      pump();
+    },
+    end() {
+      if (state === "ended") return;
+      state = "ended";
+      if (batchTimer) clearTimer(batchTimer);
+      batchTimer = null;
+      unsubscribe();
+      const w = wake;
+      wake = null;
+      w?.();
+    },
+    /** The run's input: one NDJSON line per turn or control message, until `end`. */
+    async *lines() {
+      for (;;) {
+        while (out.length > 0) yield /** @type string */ (out.shift());
+        if (state === "ended") return;
+        await new Promise((resolve) => (wake = () => resolve(undefined)));
+      }
+    },
+  };
+}