@oddessentials/agent-guild 1.30.1 → 1.32.0

package/bin/agent-guild.mjs

@@ -66,17 +66,25 @@ function portOf(url) {
   return parsed.port ? Number(parsed.port) : parsed.protocol === 'https:' ? 443 : 80;
 }
 
-async function health(url, timeoutMs = 1000) {
+/** The manager's health, `{ busy: pid }` when the manager its runtime file names for `url` runs but did not answer in time, or null. */
+async function reach(url, timeoutMs = 1000) {
+  const signal = AbortSignal.timeout(timeoutMs);
   try {
-    const res = await fetch(`${url}/api/v1/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    const res = await fetch(`${url}/api/v1/health`, { signal });
     if (!res.ok) return null;
     const body = await res.json();
     return body?.name === 'agent-guild' ? body : null;
   } catch {
-    return null;
+    const owner = signal.aborted ? readRuntimeFile() : null;
+    return owner?.url === url && running(owner.pid) ? { busy: owner.pid } : null;
   }
 }
 
+async function health(url, timeoutMs = 1000) {
+  const found = await reach(url, timeoutMs);
+  return found?.busy ? null : found;
+}
+
 function pageUrl(url, token) {
   return `${url}/#token=${token}`;
 }
@@ -114,7 +122,7 @@ async function ensureManager({ port = null } = {}) {
   // A pinned port is the endpoint to serve, so it is also the one to check;
   // a manager found anywhere else is not the one asked for.
   const knownUrl = port === null ? baseUrl() : expectedUrl;
-  const answering = await health(knownUrl);
+  const answering = await reach(knownUrl);
   if (answering) return { url: knownUrl, started: false, version: answering.version };
 
   // Say why no manager can run here rather than start one that fails.
@@ -167,21 +175,23 @@ async function cmdOpen({ browser, signIn = false }) {
  * a successor itself (a manager from before restarts only stops).
  */
 async function requestShutdown(url, { restart = false } = {}) {
-  // `stop` and `restart` are documented as ending every session, so they do
-  // not ask; the web page's buttons are the ones that confirm first.
-  const res = await fetch(`${url}/api/v1/shutdown`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${loadOrCreateToken()}`, 'Content-Type': 'application/json' },
-    body: JSON.stringify(restart ? { force: true, restart: true } : { force: true }),
-  });
-  if (!res.ok) {
-    const { error } = await res.json().catch(() => ({}));
-    throw new Error(`${restart ? 'restart' : 'stop'} failed: ${error?.message ?? `HTTP ${res.status}`}`);
+  const signal = AbortSignal.timeout(5000);
+  try {
+    const res = await fetch(`${url}/api/v1/shutdown`, {
+      method: 'POST', signal,
+      headers: { Authorization: `Bearer ${loadOrCreateToken()}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(restart ? { force: true, restart: true } : { force: true }),
+    });
+    const body = await res.json().catch(() => ({}));
+    signal.throwIfAborted();
+    if (!res.ok) throw new Error(`${restart ? 'restart' : 'stop'} failed: ${body.error?.message ?? `HTTP ${res.status}`}`);
+    const running = body.running ?? 0;
+    if (running > 0) console.log(`Ending ${running} running session(s).`);
+    return { running, restart: body.restart === true };
+  } catch (err) {
+    if (signal.aborted) throw new Error(`the session manager did not answer the ${restart ? 'restart' : 'stop'} request within 5 seconds; its outcome could not be confirmed.`);
+    throw err;
   }
-  const body = await res.json().catch(() => ({}));
-  const running = body.running ?? 0;
-  if (running > 0) console.log(`Ending ${running} running session(s).`);
-  return { running, restart: body.restart === true };
 }
 
 function running(pid) {
@@ -209,13 +219,13 @@ async function waitForExit(pid, timeoutMs = 15000) {
 
 async function cmdStop() {
   const url = baseUrl();
-  const h = await health(url);
+  const h = await reach(url);
   if (!h) {
     console.log('Session manager is not running.');
     return;
   }
   await requestShutdown(url);
-  if (await waitForExit(h.pid)) {
+  if (await waitForExit(h.busy ?? h.pid)) {
     console.log('Session manager stopped.');
     return;
   }
@@ -225,13 +235,14 @@ async function cmdStop() {
 
 async function cmdRestart() {
   const url = baseUrl();
-  const before = await health(url);
-  if (!before) {
+  const found = await reach(url);
+  if (!found) {
     // Nothing to stop: a restart of a stopped manager is a start.
     const { url: started, version } = await ensureManager();
     console.log(`Session manager was not running; started Agent Guild ${version} at ${started}.`);
     return;
   }
+  const before = found.busy ? { pid: found.busy } : found;
   const { restart } = await requestShutdown(url, { restart: true });
   if (!restart) {
     // A manager from before restarts stops without starting a successor,
@@ -239,7 +250,7 @@ async function cmdRestart() {
     if (!(await waitForExit(before.pid))) throw new Error('the session manager did not stop, so it could not be restarted.');
     // On the port the old one served, which an ephemeral port setting would otherwise lose.
     const { url: started, version } = await ensureManager({ port: portOf(url) });
-    const changed = version !== before.version ? `, now Agent Guild ${version} (was ${before.version})` : '';
+    const changed = before.version && version !== before.version ? `, now Agent Guild ${version} (was ${before.version})` : '';
     console.log(`Session manager restarted at ${started}${changed}.`);
     return;
   }
@@ -250,7 +261,7 @@ async function cmdRestart() {
     await new Promise((r) => setTimeout(r, 250));
     const now = await health(url, 500);
     if (now && now.pid !== before.pid) {
-      const changed = now.version !== before.version ? `, now Agent Guild ${now.version} (was ${before.version})` : '';
+      const changed = before.version && now.version !== before.version ? `, now Agent Guild ${now.version} (was ${before.version})` : '';
       console.log(`Session manager restarted at ${url}${changed}.`);
       return;
     }
@@ -261,7 +272,12 @@ async function cmdRestart() {
 
 async function cmdStatus() {
   const url = baseUrl();
-  const h = await health(url);
+  const h = await reach(url);
+  if (h?.busy) {
+    console.log(`Session manager running at ${url} (pid ${h.busy}) did not answer in time.`);
+    process.exitCode = 1;
+    return;
+  }
   if (!h) {
     console.log('Session manager is not running.');
     // With no manager to ask, the boot service is read from systemd directly.
@@ -294,15 +310,21 @@ async function cmdStatus() {
 
 async function cmdFireworks() {
   const url = baseUrl();
-  if (!(await health(url))) {
+  if (!(await reach(url))) {
     console.log('Session manager is not running.');
     process.exitCode = 3;
     return;
   }
-  const res = await fetch(`${url}/api/v1/yard/fireworks`, { method: 'POST', headers: { Authorization: `Bearer ${loadOrCreateToken()}` } });
-  if (!res.ok) throw new Error(`the session manager answered ${res.status}.`);
-  const { pages } = await res.json();
-  console.log(pages ? `Fireworks sent to ${pages} open page(s); every Yard on show lights up.` : 'No page is open to see the fireworks.');
+  const signal = AbortSignal.timeout(5000);
+  try {
+    const res = await fetch(`${url}/api/v1/yard/fireworks`, { method: 'POST', signal, headers: { Authorization: `Bearer ${loadOrCreateToken()}` } });
+    if (!res.ok) throw new Error(`the session manager answered ${res.status}.`);
+    const { pages } = await res.json();
+    console.log(pages ? `Fireworks sent to ${pages} open page(s); every Yard on show lights up.` : 'No page is open to see the fireworks.');
+  } catch (err) {
+    if (signal.aborted) throw new Error('the session manager did not answer the fireworks request within 5 seconds; delivery could not be confirmed.');
+    throw err;
+  }
 }
 
 const MIN_NODE_MAJOR = 22;

package/docs/api.md

@@ -430,6 +430,8 @@ files. When the tool cannot be asked, `count` is null, `scopes` is empty and
   "toolSessionId": "581893e5-a93d-5e49-968b-1c1c277d3255",
   "context": { "compactions": 2, "resets": 0 },
   "reply": { "id": 3 },
+  "replyCursor": "00000000-0000-4000-8000-000000000001:3",
+  "inputInstance": "00000000-0000-4000-8000-000000000002",
   "reporting": { "state": "active", "reason": null },
   "agents": [ /* Agent */ ],
   "shells": [{ "id": "shell-3", "kind": "shell" }]
@@ -468,10 +470,17 @@ files. When the tool cannot be asked, `count` is null, `scopes` is empty and
   in a new session (`/clear`, `/new`) since the card started.
 * `reply` names the answer that ended the agent's last turn by `id`, or is
   null. Its text is read with `GET /sessions/:id/reply`.
+* `replyCursor` is an opaque position after the latest recorded answer, or
+  before the first answer when none exists. An empty turn clears `reply`
+  without changing this cursor or erasing history.
 * `reporting` says whether the tool's reporting hooks work, or is null for a
   tool Agent Guild supplies no hooks to. `state` is `pending`, `active`,
   `unavailable`, `setup_required` or `unsupported`; `reason` explains every
   state but `active`.
+* `inputInstance` identifies the current terminal attachment for keyed input.
+  It changes on reattachment, after every 4,096 new keys, and on session
+  replacement, including restoration after manager restart. It grants no
+  input authorization.
 * `shells` lists the shell commands the tool is running, each `{ id, kind }`
   with `kind` `shell` or `monitor`. Nothing about the command itself is
   included.
@@ -703,6 +712,7 @@ All paths are under `/api/v1`.
 | POST | `/sessions` | `{ providerId, account?, shell?, cwd?, cols?, rows?, name?, args?, resume? }` | `201 { session }`. 429 `too_many_sessions` at the session limit. |
 | GET | `/sessions/:id` | | `{ session }` |
 | GET | `/sessions/:id/reply` | | `{ reply: { id, text, spoken } }`, or `{ reply: null }`: the whole text of the answer `session.reply` names, and `spoken`, the words the page's Read aloud speaks for it: a line per paragraph line, heading, list item and table row, each fenced code block as `Code omitted.` |
+| GET | `/sessions/:id/replies?after=&limit=` | | `{ replies: [{ id, text, cursor }], nextCursor, hasMore, gap, firstCursor }`: retained answers in recorded order. `after` is an exclusive cursor; omit it to start at the oldest retained answer. `limit` defaults to 20, from 1 to 100. |
 | PATCH | `/sessions/:id` | `{ name }` | `{ session }`. |
 | POST | `/sessions/:id/stop` | | `{ session }`: ends the process. The session stays listed as exited. |
 | POST | `/sessions/:id/reattach` | | `{ session }`: runs an exited tmux or herdr session's multiplexer client again, keeping the session's id and screen. 409 `multiplexer_session_gone` while `multiplexer.reattachable` is false. |
@@ -738,6 +748,23 @@ Request bodies are limited to 64 KiB, except `PUT /notes`,
 1 MiB, and `POST /sessions/:id/hook`, which accepts 32 MiB and checks the token
 before reading the body. Messages a client sends on a WebSocket are limited to 1 MiB.
 
+### Reply history
+
+Reads are independent and never consume answers. Save each answer's `cursor`
+after handling it; `nextCursor` is the last returned cursor, or the starting
+position for an empty result. `hasMore` says whether more answers existed at
+read time. `firstCursor` names the oldest retained answer, or is null.
+`gap` is null normally, `evicted` when earlier requested answers were dropped,
+or `reset` when the cursor belongs to another session instance. A reset read
+starts at the oldest retained answer. Malformed cursors, positions ahead of
+the current instance, and invalid limits return 400.
+
+Each session retains at most 100 complete answers and 16 MiB of UTF-8 text,
+evicting oldest answers first. The newest answer is always kept whole, even
+if it alone exceeds 16 MiB. History remains after exit, but is lost on session
+removal or manager restart. A replacement session has a new cursor identity,
+even when its session id is reused. A removed session returns 404.
+
 ## WebSockets
 
 Messages in both directions are JSON text frames.
@@ -788,6 +815,7 @@ Server to client:
 | `{ type: "data", data }` | Terminal output, in order, directly after the snapshot. |
 | `{ type: "resize", cols, rows, generation, owner }` | The size changed or was claimed, or this page's own `resize` was refused or changed nothing. |
 | `{ type: "exit", exitCode, signal }` | The process ended. Also sent after the snapshot when attaching to an exited session. |
+| `{ type: "input-result", idempotencyKey, outcome, code? }` | A receipt for keyed input, sent only to its requesting connection. `outcome` is `accepted`, `rejected` or `uncertain`; see below. |
 | `{ type: "removed" }` | The session was removed. The socket then closes with code 4410. |
 | `{ type: "pong" }` | The answer to a client's `ping`. |
 | `{ type: "error", code: "not_found", message }` | The session does not exist. The socket then closes with code 4404. |
@@ -797,10 +825,46 @@ Client to server:
 | Message | Meaning |
 | --- | --- |
 | `{ type: "input", data }` | Keystrokes or pasted text, as a terminal would send them. Send a bracketed paste as one message: in a message that starts with `ESC[200~` and ends with `ESC[201~`, those markers inside the text reach the program with their ESC replaced by `␛`, so the text cannot end the paste. |
+| `{ type: "input", data, idempotencyKey }` | At most one write attempt per key. The key is the original `inputInstance`, a colon, and a caller-chosen ID of 1–128 ASCII letters, digits, underscores or hyphens. Save the full key before sending and reuse it unchanged for retries. |
 | `{ type: "claim", cols, rows }` | Take the size for this page and set it. Needs `page`. |
 | `{ type: "resize", generation, cols, rows }` | Resize the terminal. Refused unless this page owns the size and `generation` is the latest. |
 | `{ type: "ping" }` | Ask for a `pong`, to check that the link is alive. |
 
+### Keyed terminal input
+
+Only send keyed input after a snapshot supplies `session.inputInstance`;
+older managers do not support it. The manager records each valid request
+before attempting its write. Identical keys and `data` return the stored
+outcome, including after exit. Changed `data` returns `key_conflict` without
+altering the original receipt. Comparison includes all characters, including
+Enter, before bracketed-paste sanitization.
+
+| Outcome | Meaning |
+| --- | --- |
+| `accepted` | The terminal writer returned without a synchronous error. Input may still be buffered. This does not confirm consumption or command execution. |
+| `rejected` | This request made no write attempt. `code` identifies `invalid_key`, `invalid_input`, `key_conflict`, `stale_instance` or `not_writable` (exited/disposed session or empty input). A rejection does not undo a previous request. |
+| `uncertain` | `write_uncertain`: a write may have started. The receipt is kept and retries never attempt another write. |
+
+Receipts contain the key, input hash and outcome, not raw input. A Session
+keeps them in two generations of up to 4,096 receipts, through exit and
+reattachment. The receipt that fills a generation retires the current
+`inputInstance`: a new one is issued, the full generation becomes the
+previous one, and the generation before it is discarded. Keys in either
+kept generation return their receipts. Every other key whose instance is
+not current, including a discarded or never-recorded one, is rejected as
+`stale_instance` without a write, and its original outcome cannot be
+established. Reattachment also changes `inputInstance` and keeps both
+generations. After `stale_instance` on a new request, read the session again
+and form new keys from its current `inputInstance`. Removal or manager
+restart loses the receipts. Replacement instances reject old keys, even if the session id is
+reused; such a rejection cannot establish the old instance's outcome.
+
+If an acknowledgement is lost, reconnect and retry the identical input with
+the original full key. Never substitute a new instance prefix or key, or
+fall back to unkeyed input to resolve uncertainty. The guarantee is **at most
+one write attempt per keyed request within its valid session instance**,
+not exactly-once execution. Unkeyed input has no receipt or retry protection.
+
 ### Terminal queries: clients must not answer
 
 Programs ask the terminal questions by writing escape sequences, for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "1.30.1",
+  "version": "1.32.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "mcpName": "ai.oddessentials/agent-guild",
   "license": "AGPL-3.0-only",

package/src/manager/command-resolver.mjs

@@ -184,17 +184,19 @@ export function npmSpawnSpec(npm, args, env = process.env, platform = process.pl
 function runInOwnGroup(file, args, { env, cwd, timeoutMs, input, maxBuffer, signal }) {
   return new Promise((resolve, reject) => {
     let child;
+    // Registered before the spawn: a signal that lands once the command runs must find it.
+    const end = () => killGroup(child?.pid);
+    const release = endWithProcess(end);
     try {
       child = spawn(file, args, { env, cwd, detached: true });
     } catch (err) {
+      release();
       return reject(Object.assign(err, { stdout: '', stderr: '' }));
     }
     let stdout = '';
     let stderr = '';
     let timedOut = false;
     let settled = false;
-    const end = () => killGroup(child.pid);
-    const release = endWithProcess(end);
     const finish = (err) => {
       if (settled) return;
       settled = true;

package/src/manager/server.mjs

@@ -330,9 +330,6 @@ export function createManagerServer({
       return sendJson(res, 200, { ok: true, name: 'agent-guild', version, pid: process.pid });
     }
 
-    // Agent, model and tool-session reports may authenticate with the
-    // per-session report token that the manager injects into each tool's
-    // environment.
     const reportMatch = route.match(/^\/sessions\/([a-f0-9]+)\/(agents|model|tool-session|context|reporting|shells|docker|reply|hook)$/);
     if (reportMatch && method === 'POST') {
       const [, id, kind] = reportMatch;
@@ -627,7 +624,7 @@ export function createManagerServer({
       return undefined;
     }
 
-    const sessionMatch = route.match(/^\/sessions\/([a-f0-9]+)(\/stop|\/reattach|\/reply)?$/);
+    const sessionMatch = route.match(/^\/sessions\/([a-f0-9]+)(\/stop|\/reattach|\/reply|\/replies)?$/);
     if (sessionMatch) {
       const [, id, action] = sessionMatch;
       if (!action && method === 'GET') {
@@ -639,6 +636,12 @@ export function createManagerServer({
         const { reply } = manager.get(id);
         return sendJson(res, 200, { reply: reply && { ...reply, spoken: spokenText(reply.text) } });
       }
+      if (action === '/replies' && method === 'GET') {
+        const after = url.searchParams.get('after') ?? undefined;
+        const rawLimit = url.searchParams.get('limit');
+        if (rawLimit !== null && !/^[1-9][0-9]*$/.test(rawLimit)) throw new HttpError(400, 'limit must be an integer from 1 to 100', 'bad_request');
+        return sendJson(res, 200, manager.get(id).readReplies({ after, limit: rawLimit === null ? undefined : Number(rawLimit) }));
+      }
       if (!action && method === 'PATCH') {
         const body = await readJsonBody(req);
         const session = manager.get(id);
@@ -836,7 +839,9 @@ export function createManagerServer({
       if (isBinary || ws.revoked) return;
       let msg;
       try { msg = JSON.parse(raw.toString('utf8')); } catch { return; }
-      if (msg.type === 'input' && typeof msg.data === 'string') session.input(msg.data);
+      if (msg.type === 'input' && msg.idempotencyKey !== undefined) {
+        safeSend(ws, { type: 'input-result', idempotencyKey: msg.idempotencyKey, ...session.inputOnce(msg.data, msg.idempotencyKey) });
+      } else if (msg.type === 'input' && typeof msg.data === 'string') session.input(msg.data);
       else if (msg.type === 'claim') session.claimSize(page, msg.cols, msg.rows);
       else if (msg.type === 'resize') session.resizeFrom(page, msg.generation, msg.cols, msg.rows);
       else if (msg.type === 'ping') safeSend(ws, { type: 'pong' });

package/src/manager/session-hooks.mjs

@@ -214,6 +214,8 @@ export function codexHooksList(resolved, args, { env, platform = process.platfor
     const stopped = () => finish(new Error('The manager is stopping'));
     const timer = setTimeout(() => finish(new Error('Codex did not answer in time')), timeoutMs);
     timer.unref?.();
+    // Registered before the spawn: a signal that lands once Codex runs must find it.
+    if (platform !== 'win32') release = endWithProcess(() => killGroup(child?.pid));
     try {
       const verbatim = typeof spec.args === 'string';
       child = spawn(spec.file, verbatim ? [spec.args] : spec.args, {
@@ -222,7 +224,6 @@ export function codexHooksList(resolved, args, { env, platform = process.platfor
     } catch (err) {
       return finish(err);
     }
-    if (platform !== 'win32') release = endWithProcess(() => killGroup(child.pid));
     signal?.addEventListener('abort', stopped, { once: true });
     let stderr = '';
     let buffer = '';

package/src/manager/session.mjs

@@ -28,6 +28,9 @@ const SHELL_EVENTS = new Set(['start', 'waiting', 'asked', 'background', 'end',
 const SHELL_KINDS = new Set(['shell', 'monitor']);
 const MAX_SHELLS = 256;
 const MAX_ENDED_TASKS = 256;
+const MAX_REPLIES = 100;
+const MAX_REPLY_BYTES = 16 * 1024 * 1024;
+const MAX_INPUT_RECEIPTS = 4096;
 // Keys and reports a terminal sends as escape sequences: X10 mouse reports (three raw bytes after ESC [ M), other CSI
 // and SS3 sequences, OSC and DCS strings (to their end, or the next ESC, so a large paste is scanned once), and ESC
 // with one character (Alt+key). Bracketed paste markers are CSI, so pasted text is kept.
@@ -136,6 +139,12 @@ export class Session extends EventEmitter {
     this.toolSessionId = null;
     this.reply = null;
     this._replies = 0;
+    this._replyHistory = [];
+    this._replyBytes = 0;
+    this._replyInstance = crypto.randomUUID();
+    this.inputInstance = crypto.randomUUID();
+    this._inputReceipts = new Map();
+    this._previousReceipts = new Map();
     this.context = { compactions: count(opts.context?.compactions), resets: count(opts.context?.resets) };
     this.compactionRepeatMs = opts.compactionRepeatMs ?? 2000;
     this._compactionKeys = [];
@@ -226,6 +235,7 @@ export class Session extends EventEmitter {
   reattach(spawnSpec, { cwd = this.cwd } = {}) {
     if (this.disposed || this.status !== 'exited') throw Object.assign(new Error('only an exited session can be reattached'), { status: 409 });
     this._start(spawnSpec, cwd);
+    this.inputInstance = crypto.randomUUID();
     Object.assign(this, { status: 'running', exitCode: null, signal: null, exitedAt: null, activity: 'quiet', startedAt: new Date().toISOString() });
     this.exited = new Promise((resolve) => { this._resolveExited = resolve; });
     this._changed();
@@ -341,12 +351,17 @@ export class Session extends EventEmitter {
   }
 
   write(data) {
-    if (this.disposed || this.status !== 'running' || typeof data !== 'string' || data.length === 0) return;
-    try { this.pty.write(data); } catch { /* process is exiting */ }
+    if (this.disposed || this.status !== 'running' || typeof data !== 'string' || data.length === 0) return 'rejected';
+    try {
+      this.pty.write(data);
+      return 'accepted';
+    } catch {
+      return 'uncertain';
+    }
   }
 
   input(data) {
-    this.write(withoutInnerPasteMarkers(data));
+    const outcome = this.write(withoutInnerPasteMarkers(data));
     if (this.reporting?.state === 'pending' && !this._reportingTimer && typeof data === 'string' && this._sendsTypedLine(data)) {
       this._reportingTimer = setTimeout(() => {
         if (this.reporting?.state !== 'pending' || this.status !== 'running') return;
@@ -358,6 +373,32 @@ export class Session extends EventEmitter {
       }, this.reportingTimeoutMs);
       this._reportingTimer.unref?.();
     }
+    return outcome;
+  }
+
+  inputOnce(data, key) {
+    const match = typeof key === 'string' && key.match(/^([0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}):([A-Za-z0-9_-]{1,128})$/);
+    if (!match) return { outcome: 'rejected', code: 'invalid_key' };
+    if (typeof data !== 'string') return { outcome: 'rejected', code: 'invalid_input' };
+    const fingerprint = crypto.createHash('sha256').update(data, 'utf16le').digest('hex');
+    const previous = this._inputReceipts.get(key) ?? this._previousReceipts.get(key);
+    if (previous) return previous.fingerprint === fingerprint ? { ...previous.result } : { outcome: 'rejected', code: 'key_conflict' };
+    if (match[1] !== this.inputInstance) return { outcome: 'rejected', code: 'stale_instance' };
+    const receipt = { fingerprint, result: { outcome: 'uncertain', code: 'write_uncertain' } };
+    this._inputReceipts.set(key, receipt);
+    try {
+      const outcome = this.input(data);
+      if (outcome === 'accepted') receipt.result = { outcome };
+      else if (outcome === 'rejected') receipt.result = { outcome, code: 'not_writable' };
+    } catch {}
+    // A full generation retires its instance, so a key dropped with the generation before it can only be stale.
+    if (this._inputReceipts.size >= MAX_INPUT_RECEIPTS) {
+      this._previousReceipts = this._inputReceipts;
+      this._inputReceipts = new Map();
+      this.inputInstance = crypto.randomUUID();
+      this._changed();
+    }
+    return { ...receipt.result };
   }
 
   /**
@@ -788,7 +829,6 @@ export class Session extends EventEmitter {
     return this.context;
   }
 
-  /** The text of the agent's last answer, or null when its last turn ended without one. */
   reportReply(report) {
     if (!report || typeof report !== 'object') throw badRequest('reply report must be an object');
     if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
@@ -796,10 +836,49 @@ export class Session extends EventEmitter {
     this._reportingHeard();
     const text = report.reply?.trim() || null;
     this.reply = text ? { id: ++this._replies, text } : null;
+    if (this.reply) {
+      const bytes = Buffer.byteLength(text);
+      this._replyHistory.push({ ...this.reply, bytes });
+      this._replyBytes += bytes;
+      while (this._replyHistory.length > 1 && (this._replyHistory.length > MAX_REPLIES || this._replyBytes > MAX_REPLY_BYTES)) {
+        this._replyBytes -= this._replyHistory.shift().bytes;
+      }
+    }
     this._changed();
     return this.reply && { id: this.reply.id };
   }
 
+  replyCursor(id = this._replies) {
+    return `${this._replyInstance}:${id}`;
+  }
+
+  readReplies({ after, limit = 20 } = {}) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_REPLIES) throw badRequest('limit must be an integer from 1 to 100');
+    let id = 0;
+    let gap = null;
+    if (after !== undefined) {
+      const match = typeof after === 'string' && after.match(/^([0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}):(0|[1-9][0-9]*)$/);
+      if (!match || !Number.isSafeInteger(Number(match[2]))) throw badRequest('after must be a reply cursor');
+      if (match[1] !== this._replyInstance) gap = 'reset';
+      else {
+        id = Number(match[2]);
+        if (id > this._replies) throw badRequest('after is ahead of this session');
+      }
+    }
+    const first = this._replyHistory[0]?.id ?? this._replies + 1;
+    if (!gap && id < first - 1) gap = 'evicted';
+    const replies = this._replyHistory.filter((reply) => reply.id > id).slice(0, limit)
+      .map(({ id, text }) => ({ id, text, cursor: this.replyCursor(id) }));
+    const last = replies.at(-1)?.id ?? id;
+    return {
+      replies,
+      nextCursor: this.replyCursor(last),
+      hasMore: last < this._replies,
+      gap,
+      firstCursor: this._replyHistory.length ? this.replyCursor(first) : null,
+    };
+  }
+
   reportHello() {
     if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
     this._reportingHeard();
@@ -878,6 +957,8 @@ export class Session extends EventEmitter {
       toolSessionId: this.toolSessionId,
       context: { ...this.context },
       reply: this.reply && { id: this.reply.id },
+      replyCursor: this.replyCursor(),
+      inputInstance: this.inputInstance,
       reporting: this.reporting,
       agents: [...this.agents.values()],
       shells: [...this.shells.values()].filter((s) => s.visible).map((s) => ({ id: s.id, kind: s.kind })),

package/src/manager/shell-env.mjs

@@ -78,6 +78,9 @@ export function probeLoginShell({ shell, env = process.env, timeoutMs = LOGIN_SH
   if (process.platform === 'win32' || !shell) return Promise.resolve({ vars: null, failure: null });
   return new Promise((resolve) => {
     let child;
+    // Registered before the spawn: a signal that lands once the shell runs must find it.
+    const end = () => killGroup(child?.pid);
+    const release = endWithProcess(end);
     try {
       child = spawn(shell, LOGIN_SHELL_ARGS, {
         detached: true,
@@ -85,12 +88,11 @@ export function probeLoginShell({ shell, env = process.env, timeoutMs = LOGIN_SH
         env: { ...env, AGENT_GUILD_RESOLVING_ENV: '1' },
       });
     } catch (err) {
+      release();
       return resolve({ vars: null, failure: `could not start (${err.code || err.message})` });
     }
     let stdout = '';
     let settled = false;
-    const end = () => killGroup(child.pid);
-    const release = endWithProcess(end);
     const finish = (result) => {
       if (settled) return;
       settled = true;