@cohortapp/agent-sdk 2.17.0 → 2.18.4

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

@@ -0,0 +1,344 @@
+/**
+ * lib/engine/session-runtime/runner.mjs — `cohort session`, the engine's
+ * long-lived front door.
+ *
+ *   node lib/engine/cli.mjs session --name olivia-main --session-id <uuid> \
+ *     --permission-mode default --mcp-config .mcp.json "<bootstrap prompt>"
+ *
+ * One process, one named session:
+ *
+ *   1. claims its name in the registry (registry.mjs; `--replace` shuts the
+ *      holder down first — and signals it only once it has confirmed the pid
+ *      really is that session), then listens on its own control socket
+ *      (socket.mjs; `<name>.<nonce>.sock`);
+ *   2. sets its process title to `cohort-session:<name>` and heartbeats,
+ *      restoring its registry entry if something removed it;
+ *   3. runs `cohort run` in multi-turn stream-json mode with a session host
+ *      (host.mjs): turns come from the inbox — the terminal (tui/), the socket,
+ *      wakeups, event batches — one at a time; while idle it makes no requests;
+ *   4. renders events in the terminal, or writes them as NDJSON when headless;
+ *   5. on Ctrl-D, a `shutdown` control, SIGTERM/SIGHUP (and SIGINT headless):
+ *      the running turn is interrupted, the run ends, monitors and background
+ *      shells are killed, the socket and registry entry are removed.
+ *
+ * `--max-turns` and `--wall-clock-ms` bound each turn (the loop runs once per
+ * turn). Every effect is a dependency, so tests run two sessions in-process.
+ *
+ * @module lib/engine/session-runtime/runner
+ */
+
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import { runCli } from "../cli.mjs";
+import { parseSessionArgs, SESSION_USAGE } from "./args.mjs";
+import { createRegistry, defaultRegistryDir, socketPathFor, HEARTBEAT_MS, isPidAlive } from "./registry.mjs";
+import { formatInbound, sendControl, startControlServer } from "./socket.mjs";
+import { createSessionHost } from "./host.mjs";
+import { createTui } from "../tui/tui.mjs";
+
+/**
+ * @typedef {Object} SessionDeps
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {string} [cwd]
+ * @property {any} [stdin]               the terminal's input (interactive)
+ * @property {{write:(s:string)=>unknown, isTTY?:boolean}} [stdout]
+ * @property {{write:(s:string)=>unknown}} [stderr]
+ * @property {boolean} [interactive]     default: stdin and stdout are TTYs
+ * @property {string} [homedir]
+ * @property {number} [pid]
+ * @property {(pid:number)=>boolean} [isAlive]
+ * @property {() => number} [now]
+ * @property {() => string} [newId]
+ * @property {AbortSignal} [signal]      shuts the session down
+ * @property {number} [heartbeatMs]
+ * @property {number} [msPerSecond]      ScheduleWakeup's second (tests)
+ * @property {number} [batchMs]          idle event batching window
+ * @property {number} [replaceWaitMs]
+ * @property {number} [askGraceMs]       the terminal's approval grace (tests)
+ * @property {(pid:number, signal:NodeJS.Signals)=>void} [kill]     --replace's SIGTERM (tests)
+ * @property {(pid:number)=>string} [psCommand]                     a pid's command line, as ps shows it (tests)
+ * @property {(title:string)=>void} [setTitle]
+ * @property {(info:{name:string, sessionId:string, socketPath:string}) => void} [onReady]
+ * @property {Record<string, any>} [cli] further runCli deps (fetchImpl, managedSettingsPath, …)
+ */
+
+/**
+ * @param {string[]} argv  arguments after `session`
+ * @param {SessionDeps} [deps]
+ * @returns {Promise<number>} exit code
+ */
+export async function runSession(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const cwd = deps.cwd ?? process.cwd();
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const stdin = deps.stdin ?? process.stdin;
+  const now = deps.now ?? Date.now;
+  const pid = deps.pid ?? process.pid;
+  const say = (/** @type string */ l) => stderr.write(`cohort session: ${l}\n`);
+
+  const parsed = parseSessionArgs(argv, deps.newId ? { newId: deps.newId } : {});
+  if (!parsed.ok) {
+    stderr.write(`cohort session: ${parsed.error}\n\n${SESSION_USAGE}`);
+    return 2;
+  }
+  if (parsed.help) {
+    stdout.write(SESSION_USAGE);
+    return 0;
+  }
+  const { name, sessionId } = parsed;
+  const homedir = deps.homedir ?? env.HOME ?? os.homedir();
+  const isAlive = deps.isAlive ?? isPidAlive;
+  const registry = createRegistry({ dir: defaultRegistryDir({ env, homedir }), isAlive, now });
+  // A socket file of this instance's own: removing an old instance's socket can never unlink it.
+  const socketPath = socketPathFor(registry.dir, name, { nonce: `${pid.toString(36)}${randomBytes(3).toString("hex")}` });
+  const iso = () => new Date(now()).toISOString();
+  const heartbeatMs = deps.heartbeatMs ?? HEARTBEAT_MS;
+
+  // ── the name ───────────────────────────────────────────────────────────────
+  /** This instance's registry entry; heartbeats and state changes rewrite it whole. */
+  const entry = { name, sessionId, pid, cwd, socketPath, startedAt: iso(), heartbeatAt: iso(), heartbeatMs, engine: "cohort", state: "starting", ...(env.AGENT_ROOT ? { agentRoot: env.AGENT_ROOT } : {}) };
+  let claim = registry.claim(entry);
+  if (!claim.ok && claim.code === "session_name_taken") {
+    if (!parsed.replace) {
+      say(`${claim.message}; pass --replace to take its place`);
+      return 1;
+    }
+    const holder = claim.entry;
+    const retired = await retire(holder, { name, isAlive, waitMs: deps.replaceWaitMs ?? 5_000, ...(deps.kill ? { kill: deps.kill } : {}), ...(deps.psCommand ? { psCommand: deps.psCommand } : {}) });
+    if (!retired.ok) {
+      say(`the session "${name}" (pid ${holder.pid}) was not replaced: ${retired.reason}`);
+      return 1;
+    }
+    claim = registry.claim(entry, { force: true });
+  }
+  if (!claim.ok) {
+    say(claim.message);
+    return 1;
+  }
+
+  let replacedNoted = false;
+  /** @param {Record<string, unknown>} patch */
+  const writeEntry = (patch) => {
+    Object.assign(entry, patch, { heartbeatAt: iso() });
+    const r = registry.refresh(entry);
+    if (r === "replaced" && !replacedNoted) {
+      replacedNoted = true;
+      say(`another live session now holds the name "${name}"; this one no longer appears in the registry`);
+    }
+    return r;
+  };
+
+  // ── the host, the terminal, the socket ────────────────────────────────────
+  const interactive = deps.interactive ?? Boolean(stdin?.isTTY && stdout.isTTY);
+  /** @type {ReturnType<typeof createTui>|null} */
+  let ui = null;
+  const sessionAbort = new AbortController();
+  let shuttingDown = false;
+  const host = createSessionHost({
+    name,
+    registry,
+    busy: parsed.prompt !== null && parsed.prompt !== "-",
+    signal: sessionAbort.signal,
+    ask: interactive ? (q) => (ui ? ui.ask(q) : Promise.resolve("deny")) : null,
+    msPerSecond: deps.msPerSecond,
+    now,
+    batchMs: deps.batchMs,
+    onState: (state) => {
+      writeEntry({ state });
+      ui?.setBusy(state === "busy");
+    },
+    onWakeup: (w) => ui?.note(`wakeup${w.reason ? `: ${w.reason}` : ""}`),
+  });
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    host.interrupt();
+    sessionAbort.abort();
+    host.inbox.end();
+  };
+  if (deps.signal?.aborted) shutdown();
+  else deps.signal?.addEventListener("abort", shutdown, { once: true });
+
+  /** Headless: a line for the NDJSON output. @param {object} ev */
+  const emit = (ev) => {
+    if (!ui) stdout.write(`${JSON.stringify({ ...ev, session_id: sessionId })}\n`);
+  };
+  /** @param {any} item */
+  const onMessage = async (item) => {
+    if (item.kind === "user") {
+      const status = host.inbox.deliver({ text: formatInbound(item), kind: item.from ? "peer" : "socket", from: item.from });
+      if (status === "ended") return { ok: false, status, error: "the session is shutting down" };
+      ui?.inbound({ from: item.from, summary: item.summary, text: item.text, status });
+      emit({ type: "system", subtype: "cohort_inbound", from: item.from, summary: item.summary, status });
+      return { ok: true, status, name };
+    }
+    switch (item.subtype) {
+      case "interrupt":
+        return { ok: true, interrupted: host.interrupt() };
+      case "compact":
+        host.inbox.control({ type: "control", subtype: "compact", ...(item.customInstructions ? { custom_instructions: item.customInstructions } : {}) });
+        return { ok: true, status: "queued" };
+      case "status":
+        return { ok: true, name, sessionId, pid, cwd, ...host.status() };
+      case "shutdown":
+        setImmediate(shutdown);
+        return { ok: true, status: "shutting_down" };
+      default:
+        return { ok: false, error: `unknown control ${item.subtype}` };
+    }
+  };
+  /** @type {Awaited<ReturnType<typeof startControlServer>>} */
+  let server;
+  try {
+    server = await startControlServer({ socketPath, onMessage, log: say });
+  } catch (e) {
+    registry.release(name, pid, entry);
+    say(`cannot listen on ${socketPath}: ${e instanceof Error ? e.message : e}`);
+    return 1;
+  }
+  writeEntry({ state: host.inbox.state });
+  (deps.setTitle ?? setProcessTitle)(`cohort-session:${name}`);
+  const beat = setInterval(() => writeEntry({ state: host.inbox.state === "busy" ? "busy" : "idle" }), heartbeatMs);
+  beat.unref?.();
+
+  // ── the run ───────────────────────────────────────────────────────────────
+  let pendingOut = "";
+  const onEventLine = (/** @type string */ line) => {
+    /** @type any */
+    let ev = null;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      /* not an event */
+    }
+    if (ui) {
+      if (ev) ui.event(ev);
+    } else if (!(ev?.type === "result" && ev.cohort?.error?.code === "no_input")) {
+      stdout.write(`${line}\n`);
+    }
+    if (ev?.type === "result") host.inbox.turnEnded();
+  };
+  const events = {
+    write(/** @type string */ s) {
+      pendingOut += s;
+      let nl;
+      while ((nl = pendingOut.indexOf("\n")) !== -1) {
+        const line = pendingOut.slice(0, nl);
+        pendingOut = pendingOut.slice(nl + 1);
+        onEventLine(line);
+      }
+      return true;
+    },
+  };
+  if (interactive) {
+    ui = createTui({ input: stdin, output: stdout, name, sessionId, onSubmit: (text) => host.inbox.deliver({ text }), onInterrupt: () => host.interrupt(), onExit: shutdown, ...(deps.askGraceMs != null ? { askGraceMs: deps.askGraceMs } : {}) });
+    ui.start();
+    ui.setBusy(host.inbox.state === "busy");
+  }
+  const runStderr = ui ? { write: (/** @type string */ s) => (ui?.note(String(s)), true) } : stderr;
+  deps.onReady?.({ name, sessionId, socketPath });
+
+  let code = 1;
+  try {
+    code = await runCli(parsed.runArgv, { ...(deps.cli ?? {}), env, cwd, stdout: events, stderr: runStderr, signal: sessionAbort.signal, host, stdinLines: host.inbox.lines() });
+  } finally {
+    clearInterval(beat);
+    host.dispose();
+    ui?.close();
+    await server.close();
+    registry.release(name, pid, entry);
+  }
+  return shuttingDown ? 0 : code;
+}
+
+/** Does a ps command line show a `cohort session` of this name? Pure. @param {string} command @param {string} name */
+export function isSessionTitle(command, name) {
+  const t = String(command ?? "").trim();
+  return t === `cohort-session:${name}` || t.startsWith(`cohort-session:${name} `);
+}
+
+/** @param {number} pid */
+function readPsCommand(pid) {
+  try {
+    return execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Shut down the session holding a name, for `--replace`.
+ *
+ * A pid read from a registry file is only a claim — after a crash the number
+ * may belong to any other process — so nothing is signalled until the holder
+ * is confirmed to be that session: its control socket answers `status` with
+ * the entry's pid and sessionId, or ps shows the title `cohort-session:<name>`
+ * for that pid. Then: a `shutdown` control, and SIGTERM (re-confirmed) if it is
+ * still alive when half the wait is over.
+ *
+ * @param {any} holder
+ * @param {{name:string, isAlive:(pid:number)=>boolean, waitMs:number,
+ *          send?:typeof sendControl, kill?:(pid:number, signal:NodeJS.Signals)=>void, psCommand?:(pid:number)=>string}} o
+ * @returns {Promise<{ok:true}|{ok:false, reason:string}>}
+ */
+export async function retire(holder, { name, isAlive, waitMs, send = sendControl, kill = (p, s) => process.kill(p, s), psCommand = readPsCommand }) {
+  const timeoutMs = Math.max(100, Math.min(2_000, waitMs / 2));
+  const confirmBySocket = async () => {
+    const r = await send(holder.socketPath, { type: "control", subtype: "status" }, { timeoutMs });
+    return r.ok && r.response?.ok === true && r.response.pid === holder.pid && r.response.sessionId === holder.sessionId;
+  };
+  const confirm = async () => (await confirmBySocket()) || isSessionTitle(psCommand(holder.pid), name);
+
+  const bySocket = await confirmBySocket();
+  if (!bySocket && !isSessionTitle(psCommand(holder.pid), name)) {
+    if (!isAlive(holder.pid)) return { ok: true };
+    return { ok: false, reason: `pid ${holder.pid} could not be confirmed as that session (its socket does not answer for it and ps does not show cohort-session:${name}); nothing was signalled` };
+  }
+  if (bySocket) await send(holder.socketPath, { type: "control", subtype: "shutdown" }, { timeoutMs });
+  const deadline = Date.now() + waitMs;
+  let termed = false;
+  while (Date.now() < deadline) {
+    if (!isAlive(holder.pid)) return { ok: true };
+    if (!termed && Date.now() > deadline - waitMs / 2) {
+      termed = true;
+      if (await confirm()) {
+        try {
+          kill(holder.pid, "SIGTERM");
+        } catch {
+          /* gone */
+        }
+      }
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return isAlive(holder.pid) ? { ok: false, reason: "it did not stop" } : { ok: true };
+}
+
+/** @param {string} title */
+function setProcessTitle(title) {
+  try {
+    process.title = title;
+  } catch {
+    /* some platforms refuse */
+  }
+}
+
+/**
+ * The process edge: SIGTERM and SIGHUP (and SIGINT when there is no terminal —
+ * in a terminal Ctrl-C is a key) shut the session down.
+ * @param {string[]} argv
+ */
+export async function runSessionFromProcess(argv) {
+  const controller = new AbortController();
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const signals = /** @type {NodeJS.Signals[]} */ (interactive ? ["SIGTERM", "SIGHUP"] : ["SIGTERM", "SIGHUP", "SIGINT"]);
+  const onSignal = () => controller.abort();
+  for (const s of signals) process.once(s, onSignal);
+  try {
+    return await runSession(argv, { signal: controller.signal, interactive });
+  } finally {
+    for (const s of signals) process.removeListener(s, onSignal);
+  }
+}

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

@@ -0,0 +1,212 @@
+/**
+ * lib/engine/session-runtime/socket.mjs — a session's local control socket.
+ *
+ * A Unix domain socket (mode 0600, in the registry directory, which is 0700)
+ * that takes one JSON object per line and answers each with one JSON line:
+ *
+ *   {"type":"user", "message":"…" | {role:"user", content}, "from"?, "summary"?}
+ *        → {"ok":true, "status":"delivered"|"queued"}
+ *   {"type":"control", "subtype":"interrupt"}  → {"ok":true, "interrupted":bool}
+ *   {"type":"control", "subtype":"compact", "custom_instructions"?}
+ *   {"type":"control", "subtype":"status"}     → {"ok":true, name, sessionId, state, queued, …}
+ *   {"type":"control", "subtype":"shutdown"}
+ *   anything else                              → {"ok":false, "error":"…"}
+ *
+ * `from` names the sending session. It is the sender's own claim: anyone who
+ * can open the socket (the same OS user) can write any name.
+ *
+ * `parseControlLine` and `formatInbound` are pure; `startControlServer` and
+ * `sendControl` are the edge.
+ *
+ * @module lib/engine/session-runtime/socket
+ */
+
+import net from "node:net";
+import { chmodSync, lstatSync, mkdirSync, unlinkSync } from "node:fs";
+import path from "node:path";
+
+export const MAX_LINE_BYTES = 1024 * 1024;
+export const CONTROL_SUBTYPES = Object.freeze(["interrupt", "compact", "status", "shutdown"]);
+const FROM_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * @typedef {{kind:'user', text:string, from:string|null, summary:string|null}
+ *   | {kind:'control', subtype:'interrupt'|'compact'|'status'|'shutdown', customInstructions?:string}
+ *   | {kind:'invalid', error:string} | {kind:'empty'}} ControlItem
+ */
+
+/** @param {string} line @returns {ControlItem} */
+export function parseControlLine(line) {
+  const s = String(line ?? "").trim();
+  if (s === "") return { kind: "empty" };
+  let o;
+  try {
+    o = JSON.parse(s);
+  } catch {
+    return { kind: "invalid", error: "not JSON" };
+  }
+  if (!o || typeof o !== "object" || Array.isArray(o)) return { kind: "invalid", error: "not a JSON object" };
+  if (o.type === "control") {
+    if (!CONTROL_SUBTYPES.includes(o.subtype)) return { kind: "invalid", error: `control subtype must be one of ${CONTROL_SUBTYPES.join(", ")}` };
+    /** @type {ControlItem} */
+    const item = { kind: "control", subtype: o.subtype };
+    if (o.subtype === "compact" && typeof o.custom_instructions === "string" && o.custom_instructions.trim() !== "") item.customInstructions = o.custom_instructions.trim();
+    return item;
+  }
+  if (o.type === "user") {
+    const m = o.message;
+    const content = typeof m === "string" ? m : m && typeof m === "object" ? m.content : undefined;
+    const text =
+      typeof content === "string"
+        ? content
+        : Array.isArray(content)
+          ? content
+              .filter((b) => b && b.type === "text" && typeof b.text === "string")
+              .map((b) => b.text)
+              .join("\n\n")
+          : "";
+    if (text.trim() === "") return { kind: "invalid", error: "a user message needs text" };
+    if (o.from != null && (typeof o.from !== "string" || !FROM_RE.test(o.from))) return { kind: "invalid", error: "from must be a session name" };
+    const summary = typeof o.summary === "string" && o.summary.trim() !== "" ? o.summary.trim().slice(0, 200) : null;
+    return { kind: "user", text, from: o.from ?? null, summary };
+  }
+  return { kind: "invalid", error: `unsupported type ${JSON.stringify(o.type)}` };
+}
+
+/** The text a delivered message becomes: tagged with its sender. Pure. @param {{text:string, from:string|null}} m */
+export function formatInbound({ text, from }) {
+  return from ? `[from ${from}] ${text}` : text;
+}
+
+/**
+ * Make (or accept) the directory a control socket lives in: a real directory —
+ * not a symlink — owned by this user, and 0700. A directory another local user
+ * made first (in a shared /tmp, say) is refused rather than trusted, since its
+ * owner could swap the socket file. Throws on refusal.
+ * @param {string} dir @param {{uid?:number|null}} [o]
+ */
+export function ensurePrivateDir(dir, { uid = typeof process.getuid === "function" ? process.getuid() : null } = {}) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  let st = lstatSync(dir);
+  if (st.isSymbolicLink() || !st.isDirectory()) throw new Error(`${dir} is not a plain directory; a control socket will not be placed there`);
+  if (uid != null && st.uid !== uid) throw new Error(`${dir} belongs to another user (uid ${st.uid}); a control socket will not be placed there`);
+  if ((st.mode & 0o077) !== 0) {
+    chmodSync(dir, 0o700);
+    st = lstatSync(dir);
+    if ((st.mode & 0o077) !== 0) throw new Error(`${dir} could not be made private (mode ${(st.mode & 0o777).toString(8)})`);
+  }
+}
+
+/**
+ * @param {{socketPath:string, onMessage:(item:Exclude<ControlItem,{kind:'empty'}|{kind:'invalid'}>) => Promise<object>|object, log?:(l:string)=>void}} o
+ * @returns {Promise<{path:string, close:()=>Promise<void>}>}
+ */
+export async function startControlServer({ socketPath, onMessage, log = () => {} }) {
+  ensurePrivateDir(path.dirname(socketPath));
+  // The caller holds the name in the registry: a socket file left here belongs to a dead session.
+  try {
+    if (lstatSync(socketPath).isSocket()) unlinkSync(socketPath);
+  } catch {
+    /* none */
+  }
+  /** @type {Set<net.Socket>} */
+  const conns = new Set();
+  const server = net.createServer((conn) => {
+    conns.add(conn);
+    conn.on("close", () => conns.delete(conn));
+    conn.on("error", () => {});
+    conn.setEncoding("utf8");
+    let buf = "";
+    let chain = Promise.resolve();
+    const reply = (/** @type object */ o) => {
+      if (!conn.destroyed) conn.write(`${JSON.stringify(o)}\n`);
+    };
+    conn.on("data", (chunk) => {
+      buf += chunk;
+      if (Buffer.byteLength(buf) > MAX_LINE_BYTES && !buf.includes("\n")) {
+        reply({ ok: false, error: `a line may be at most ${MAX_LINE_BYTES} bytes` });
+        conn.destroy();
+        return;
+      }
+      let nl;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const item = parseControlLine(line);
+        if (item.kind === "empty") continue;
+        // Lines on one connection are answered in order.
+        chain = chain.then(async () => {
+          if (item.kind === "invalid") return reply({ ok: false, error: item.error });
+          try {
+            reply(await onMessage(item));
+          } catch (e) {
+            log(`control socket: ${e instanceof Error ? e.message : e}`);
+            reply({ ok: false, error: "the session could not handle the message" });
+          }
+        });
+      }
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    // Bind with a restrictive umask so the socket is never reachable by others, then pin 0600.
+    const old = process.umask(0o177);
+    try {
+      server.listen(socketPath, () => resolve(undefined));
+    } finally {
+      process.umask(old);
+    }
+  });
+  chmodSync(socketPath, 0o600);
+  server.on("error", (e) => log(`control socket: ${e.message}`));
+  return {
+    path: socketPath,
+    close: () =>
+      new Promise((resolve) => {
+        for (const c of conns) c.destroy();
+        server.close(() => {
+          try {
+            unlinkSync(socketPath);
+          } catch {
+            /* already removed */
+          }
+          resolve(undefined);
+        });
+      }),
+  };
+}
+
+/**
+ * Send one object to a session's socket and read its one-line answer.
+ * @param {string} socketPath @param {object} message @param {{timeoutMs?:number}} [o]
+ * @returns {Promise<{ok:true, response:any}|{ok:false, error:{code:'not_running'|'timeout'|'bad_response', message:string}}>}
+ */
+export function sendControl(socketPath, message, { timeoutMs = 5_000 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let buf = "";
+    const conn = net.createConnection(socketPath);
+    const finish = (/** @type any */ r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      conn.destroy();
+      resolve(r);
+    };
+    const timer = setTimeout(() => finish({ ok: false, error: { code: "timeout", message: `no answer from ${socketPath} within ${timeoutMs} ms` } }), timeoutMs);
+    conn.setEncoding("utf8");
+    conn.on("connect", () => conn.write(`${JSON.stringify(message)}\n`));
+    conn.on("data", (d) => {
+      buf += d;
+      const nl = buf.indexOf("\n");
+      if (nl === -1) return;
+      try {
+        finish({ ok: true, response: JSON.parse(buf.slice(0, nl)) });
+      } catch {
+        finish({ ok: false, error: { code: "bad_response", message: "the session answered with something that is not JSON" } });
+      }
+    });
+    conn.on("error", (e) => finish({ ok: false, error: { code: "not_running", message: e.message } }));
+    conn.on("close", () => finish({ ok: false, error: { code: "not_running", message: "the connection closed without an answer" } }));
+  });
+}

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

@@ -0,0 +1,115 @@
+/**
+ * lib/engine/session-runtime/wakeup.mjs — ScheduleWakeup's scheduler.
+ *
+ * A session holds at most one pending wakeup; scheduling another replaces it.
+ * Each change is appended to the session transcript, so `--resume` finds the
+ * pending one and arms it again:
+ *
+ *   {type:"wakeup", sessionId, ts, id, dueAt, delaySeconds, prompt, reason}
+ *   {type:"wakeup_fired", sessionId, ts, id}
+ *
+ * The last `wakeup` record is the pending one unless a `wakeup_fired` names it
+ * (an earlier `wakeup` is replaced by the later one). A wakeup whose time
+ * passed while no session ran fires as soon as the session is back.
+ *
+ * When it fires, its prompt becomes a turn of the session (queued behind the
+ * current turn if one is running). `wakeup_fired` is written when that turn
+ * STARTS, not when it is queued: a session that ends (or dies) with the wakeup
+ * still waiting in its queue re-arms it on `--resume`.
+ *
+ * `clampDelaySeconds`, `pendingWakeup` and `wakeupTurnText` are pure.
+ *
+ * @module lib/engine/session-runtime/wakeup
+ */
+
+import { randomUUID } from "node:crypto";
+
+export const WAKEUP_MIN_SECONDS = 60;
+export const WAKEUP_MAX_SECONDS = 3600;
+
+/** @param {number} n @returns {{seconds:number, clamped:boolean}} */
+export function clampDelaySeconds(n) {
+  const v = Number.isFinite(n) ? Math.round(n) : WAKEUP_MIN_SECONDS;
+  const seconds = Math.min(WAKEUP_MAX_SECONDS, Math.max(WAKEUP_MIN_SECONDS, v));
+  return { seconds, clamped: seconds !== v };
+}
+
+/**
+ * The pending wakeup in a transcript's records, or null.
+ * @param {any[]} records
+ * @returns {{id:string, dueAt:number, prompt:string, reason:string}|null}
+ */
+export function pendingWakeup(records) {
+  let pending = null;
+  for (const r of records) {
+    if (r?.type === "wakeup" && typeof r.id === "string" && Number.isFinite(r.dueAt) && typeof r.prompt === "string") {
+      pending = { id: r.id, dueAt: r.dueAt, prompt: r.prompt, reason: typeof r.reason === "string" ? r.reason : "" };
+    } else if (r?.type === "wakeup_fired" && pending && r.id === pending.id) {
+      pending = null;
+    }
+  }
+  return pending;
+}
+
+/** The turn a wakeup becomes. @param {{prompt:string, reason:string}} w */
+export function wakeupTurnText({ prompt, reason }) {
+  return `[Scheduled wakeup${reason ? `: ${reason}` : ""}]\n${prompt}`;
+}
+
+/**
+ * @param {{append:(record:object)=>void,
+ *          fire:(w:{id:string, prompt:string, reason:string}, started:()=>void)=>boolean|void,
+ *          now?:()=>number, msPerSecond?:number, newId?:()=>string,
+ *          setTimer?:(fn:()=>void, ms:number)=>any, clearTimer?:(t:any)=>void}} o
+ *   `fire` queues the wakeup's turn and calls `started` when that turn begins
+ *   (which records `wakeup_fired`); returning false means it was not taken.
+ *   `msPerSecond` shortens a delay's second (tests); default 1000.
+ */
+export function createWakeupScheduler({ append, fire, now = Date.now, msPerSecond = 1000, newId = randomUUID, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  /** @type {{id:string, dueAt:number, prompt:string, reason:string}|null} */
+  let current = null;
+  /** @type {any} */
+  let timer = null;
+
+  const arm = (/** @type {{id:string, dueAt:number, prompt:string, reason:string}} */ w) => {
+    if (timer) clearTimer(timer);
+    current = w;
+    timer = setTimer(() => {
+      timer = null;
+      if (!current || current.id !== w.id) return;
+      current = null;
+      // Recorded only once the turn starts: a session that is ending, or ends before the
+      // queued turn runs, records nothing, so --resume arms it again.
+      let recorded = false;
+      const started = () => {
+        if (recorded) return;
+        recorded = true;
+        append({ type: "wakeup_fired", ts: new Date(now()).toISOString(), id: w.id });
+      };
+      fire(w, started);
+    }, Math.max(0, w.dueAt - now()));
+    timer?.unref?.();
+  };
+
+  return {
+    /**
+     * @param {{delaySeconds:number, prompt:string, reason?:string}} p
+     */
+    schedule({ delaySeconds, prompt, reason = "" }) {
+      const { seconds, clamped } = clampDelaySeconds(delaySeconds);
+      const replaced = current;
+      const w = { id: newId(), dueAt: now() + seconds * msPerSecond, prompt, reason };
+      append({ type: "wakeup", ts: new Date(now()).toISOString(), id: w.id, dueAt: w.dueAt, delaySeconds: seconds, prompt, reason });
+      arm(w);
+      return { ...w, seconds, clamped, replaced };
+    },
+    /** Arm a wakeup found in the transcript (resume). @param {{id:string, dueAt:number, prompt:string, reason:string}} w */
+    arm,
+    current: () => current,
+    /** Stop the timer without recording anything (the session is ending; resume re-arms it). */
+    dispose() {
+      if (timer) clearTimer(timer);
+      timer = null;
+    },
+  };
+}