@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/serve/server.js

@@ -1,33 +1,118 @@
-/**
- * Read-only localhost HTTP + Server-Sent-Events server for `agents serve`.
- *
- * There is deliberately NO framework and NO mutation surface:
- *  - binds 127.0.0.1 only (loopback) — never reachable off the machine;
- *  - answers GET only (every other method → 405);
- *  - routes: `GET /` → HTML page, `GET /api/state` → JSON snapshot,
- *    `GET /events` → SSE stream that re-pushes the snapshot on an interval.
- *
- * The whole thing is a viewer over data other commands already own
- * ({@link assembleState}); it writes nothing.
- */
-import http from 'http';
+import { createServer } from 'http';
 import { assembleState } from './data.js';
 import { renderPage } from './page.js';
 /** Loopback address — the server binds here and nowhere else. */
 export const SERVE_HOST = '127.0.0.1';
+/**
+ * DNS-rebinding guard. The socket binds loopback, but binding alone does not
+ * stop a remote page: an attacker can point a hostname's DNS at 127.0.0.1 and
+ * drive the victim's browser to `GET /api/state`, which exposes uncommitted
+ * `git diff HEAD` of every worktree plus routine + cloud config. A browser
+ * always sends a `Host` header naming the site it *thinks* it reached, so we
+ * trust only a Host that is itself loopback. A missing Host (HTTP/1.0 or a raw
+ * non-browser client like curl-without-Host) is not a rebind vector and is
+ * allowed; any explicit non-loopback Host is rejected.
+ */
+export function isAllowedServeHost(hostHeader) {
+    if (!hostHeader)
+        return true;
+    const host = hostHeader.replace(/:\d+$/, '').toLowerCase().replace(/^\[|\]$/g, '');
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+}
 /** Default port for `agents serve`. */
 export const DEFAULT_SERVE_PORT = 4477;
 /** Default SSE push cadence. */
 export const DEFAULT_INTERVAL_MS = 3000;
+/** Apply defaults to {@link ServeOptions}, producing a {@link ServeContext}. */
+export function resolveServeContext(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    return {
+        snapshot: opts.snapshot ?? (() => assembleState(cwd)),
+        intervalMs: opts.intervalMs ?? DEFAULT_INTERVAL_MS,
+    };
+}
+/**
+ * Handle the shared read-only GET surface (`/`, `/api/state`, `/events`).
+ * Returns `true` when the route was recognized and a response was written (or
+ * begun, for SSE); `false` when the path is unknown so the caller can 404 or
+ * try its own routes first. Extracted so the `--control` server reuses the
+ * exact same state/SSE behavior — including the load-bearing SSE close/timer
+ * ordering below — without duplicating it.
+ */
+export async function handleServeGet(url, req, res, ctx) {
+    if (url === '/' || url === '/index.html') {
+        const html = renderPage();
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(html);
+        return true;
+    }
+    if (url === '/api/state') {
+        try {
+            const state = await ctx.snapshot();
+            res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify(state));
+        }
+        catch (err) {
+            res.writeHead(500, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: String(err?.message ?? err) }));
+        }
+        return true;
+    }
+    if (url === '/events') {
+        res.writeHead(200, {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-cache',
+            connection: 'keep-alive',
+        });
+        let closed = false;
+        // Declare the timer first and register the disconnect cleanup BEFORE the
+        // first `await push()`. `assembleState()` (team scan + git diffs) can be
+        // slow; if the client disconnects during it, the one-shot 'close' must
+        // already have a listener — otherwise it fires into the void, the interval
+        // starts anyway, and we leak a timer writing to a destroyed socket forever.
+        let timer;
+        req.on('close', () => {
+            closed = true;
+            if (timer)
+                clearInterval(timer);
+        });
+        const push = async () => {
+            if (closed)
+                return;
+            try {
+                const state = await ctx.snapshot();
+                if (closed)
+                    return;
+                res.write(`event: state\ndata: ${JSON.stringify(state)}\n\n`);
+            }
+            catch (err) {
+                if (!closed)
+                    res.write(`event: error\ndata: ${JSON.stringify({ error: String(err) })}\n\n`);
+            }
+        };
+        await push(); // immediate first frame
+        // Only arm the interval if the client is still connected. If 'close' fired
+        // during the first push, `closed` is already true (and the handler ran
+        // while `timer` was undefined), so starting an interval here would leak.
+        if (!closed)
+            timer = setInterval(push, ctx.intervalMs);
+        return true;
+    }
+    return false;
+}
 /**
  * Create (but do not start) the read-only serve server. Caller invokes
  * `.listen(port, SERVE_HOST)`. Returned so tests can bind an ephemeral port.
  */
 export function createServeServer(opts = {}) {
-    const cwd = opts.cwd ?? process.cwd();
-    const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
-    const snapshot = opts.snapshot ?? (() => assembleState(cwd));
-    const server = http.createServer(async (req, res) => {
+    const ctx = resolveServeContext(opts);
+    const server = createServer(async (req, res) => {
+        // DNS-rebind guard: reject any explicit non-loopback Host before doing work.
+        if (!isAllowedServeHost(req.headers.host)) {
+            res.writeHead(403, { 'content-type': 'text/plain' });
+            res.end('forbidden: non-local Host');
+            return;
+        }
         // Read-only: reject anything that could mutate. Only GET is served.
         if (req.method !== 'GET') {
             res.writeHead(405, { 'content-type': 'text/plain', allow: 'GET' });
@@ -35,66 +120,11 @@ export function createServeServer(opts = {}) {
             return;
         }
         const url = (req.url || '/').split('?')[0];
-        if (url === '/' || url === '/index.html') {
-            const html = renderPage();
-            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-            res.end(html);
-            return;
-        }
-        if (url === '/api/state') {
-            try {
-                const state = await snapshot();
-                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
-                res.end(JSON.stringify(state));
-            }
-            catch (err) {
-                res.writeHead(500, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ error: String(err?.message ?? err) }));
-            }
-            return;
-        }
-        if (url === '/events') {
-            res.writeHead(200, {
-                'content-type': 'text/event-stream',
-                'cache-control': 'no-cache',
-                connection: 'keep-alive',
-            });
-            let closed = false;
-            // Declare the timer first and register the disconnect cleanup BEFORE the
-            // first `await push()`. `assembleState()` (team scan + git diffs) can be
-            // slow; if the client disconnects during it, the one-shot 'close' must
-            // already have a listener — otherwise it fires into the void, the interval
-            // starts anyway, and we leak a timer writing to a destroyed socket forever.
-            let timer;
-            req.on('close', () => {
-                closed = true;
-                if (timer)
-                    clearInterval(timer);
-            });
-            const push = async () => {
-                if (closed)
-                    return;
-                try {
-                    const state = await snapshot();
-                    if (closed)
-                        return;
-                    res.write(`event: state\ndata: ${JSON.stringify(state)}\n\n`);
-                }
-                catch (err) {
-                    if (!closed)
-                        res.write(`event: error\ndata: ${JSON.stringify({ error: String(err) })}\n\n`);
-                }
-            };
-            await push(); // immediate first frame
-            // Only arm the interval if the client is still connected. If 'close' fired
-            // during the first push, `closed` is already true (and the handler ran
-            // while `timer` was undefined), so starting an interval here would leak.
-            if (!closed)
-                timer = setInterval(push, intervalMs);
-            return;
+        const handled = await handleServeGet(url, req, res, ctx);
+        if (!handled) {
+            res.writeHead(404, { 'content-type': 'text/plain' });
+            res.end('not found');
         }
-        res.writeHead(404, { 'content-type': 'text/plain' });
-        res.end('not found');
     });
     return server;
 }

package/dist/lib/serve/stream.d.ts

@@ -0,0 +1,43 @@
+/** Directory holding per-session NDJSON capture files. */
+export declare function streamDir(): string;
+/** Capture-file path for a session id (id is sanitized to a safe filename). */
+export declare function streamLogPath(sessionId: string): string;
+/** A normalized event handed to the phone. `raw` is the untouched harness line. */
+export interface StreamEvent {
+    /** UI-facing discriminator: message | tool_use | tool_result | result | error | system | unknown. */
+    type: string;
+    raw: unknown;
+}
+/**
+ * Normalize one harness JSON line to a {@link StreamEvent}. Schemas differ per
+ * agent (there is no unified enum in the CLI), so we key off the common `type`
+ * field (Claude stream-json: `assistant` | `user` | `result` | `system`; a
+ * tool-use lives inside an `assistant` message's content) and carry `raw`
+ * through untouched so the client can render richer detail without the anchor
+ * having to model every agent.
+ */
+export declare function normalizeEvent(obj: unknown): StreamEvent;
+/** A parsed event paired with the byte offset immediately AFTER its line. */
+export interface OffsetEvent {
+    event: StreamEvent;
+    /** Resume point: absolute byte offset just past this event's newline. */
+    offset: number;
+}
+/** Result of one offset-tail read of a capture file. */
+export interface ReadResult {
+    events: OffsetEvent[];
+    /** Byte offset advanced ONLY past complete newline-terminated lines. */
+    newOffset: number;
+    /** True once a terminal event (result/error) has been parsed. */
+    done: boolean;
+}
+/**
+ * Read complete NDJSON lines from `fromOffset`, byte-accurately. Each event
+ * carries the exact byte offset past its own newline so an SSE client can set
+ * `Last-Event-ID` per event and resume with neither loss nor duplication even
+ * if the connection drops mid-batch. A trailing partial line (no newline yet)
+ * is left unconsumed so the offset never splits a multi-byte event — the next
+ * read picks it up once the harness flushes the newline. Non-JSON preamble
+ * lines are skipped, not fatal.
+ */
+export declare function readNewEvents(file: string, fromOffset: number): ReadResult;

package/dist/lib/serve/stream.js

@@ -0,0 +1,116 @@
+/**
+ * Live NDJSON event bridge for the iOS cockpit (RUSH-1732).
+ *
+ * A control-mode run (`defaultRunner`) is launched with `--json`, so the agent
+ * harness emits one JSON event per line. We capture that stream to a per-session
+ * logfile and replay it to the phone over SSE at `GET /api/session/:id/stream`,
+ * normalized to the small event set the UI needs. The read is **offset-tailed**
+ * — the same resumable pattern `hosts/progress.ts` uses for remote logs — so a
+ * phone that drops mid-run reconnects with `?offset=<bytes>` (or the standard
+ * `Last-Event-ID` header) and never loses or double-counts an event.
+ *
+ * Scope: this streams runs whose executor is the anchor itself (no `--host`).
+ * Streaming a run offloaded to another box reuses `pullRemoteLogDelta` and is a
+ * follow-up; see the changelog fragment.
+ */
+import fs from 'fs';
+import path from 'path';
+import { getCacheDir } from '../state.js';
+/** Directory holding per-session NDJSON capture files. */
+export function streamDir() {
+    return path.join(getCacheDir(), 'serve', 'streams');
+}
+/** Capture-file path for a session id (id is sanitized to a safe filename). */
+export function streamLogPath(sessionId) {
+    const safe = sessionId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    return path.join(streamDir(), `${safe}.ndjson`);
+}
+/** Event types that terminate a run's stream (close the SSE). */
+const TERMINAL = new Set(['result', 'error']);
+/**
+ * Whether the run has ended — i.e. the file's LAST complete (newline-terminated)
+ * line is a terminal event. This is independent of any read offset, so a client
+ * that resumes from an offset already at/past the terminal event still learns
+ * the run is done and the SSE closes (instead of hanging on a `done:false` read
+ * that finds no new lines). Cheap: `readNewEvents` already has the full buffer.
+ */
+function fileIsDone(buf) {
+    const lastNl = buf.lastIndexOf(0x0a);
+    if (lastNl < 0)
+        return false;
+    const lines = buf.subarray(0, lastNl + 1).toString('utf-8').split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const s = lines[i].trim();
+        if (!s)
+            continue; // skip trailing blank lines
+        try {
+            return TERMINAL.has(normalizeEvent(JSON.parse(s)).type);
+        }
+        catch {
+            return false; // last complete line is a partial/non-JSON write — not done
+        }
+    }
+    return false;
+}
+/**
+ * Normalize one harness JSON line to a {@link StreamEvent}. Schemas differ per
+ * agent (there is no unified enum in the CLI), so we key off the common `type`
+ * field (Claude stream-json: `assistant` | `user` | `result` | `system`; a
+ * tool-use lives inside an `assistant` message's content) and carry `raw`
+ * through untouched so the client can render richer detail without the anchor
+ * having to model every agent.
+ */
+export function normalizeEvent(obj) {
+    const rec = obj;
+    const t = rec && typeof rec.type === 'string' ? rec.type : 'unknown';
+    return { type: t, raw: obj };
+}
+/**
+ * Read complete NDJSON lines from `fromOffset`, byte-accurately. Each event
+ * carries the exact byte offset past its own newline so an SSE client can set
+ * `Last-Event-ID` per event and resume with neither loss nor duplication even
+ * if the connection drops mid-batch. A trailing partial line (no newline yet)
+ * is left unconsumed so the offset never splits a multi-byte event — the next
+ * read picks it up once the harness flushes the newline. Non-JSON preamble
+ * lines are skipped, not fatal.
+ */
+export function readNewEvents(file, fromOffset) {
+    let buf;
+    try {
+        buf = fs.readFileSync(file);
+    }
+    catch {
+        // File not created yet (run still starting) — nothing to read, hold offset.
+        return { events: [], newOffset: fromOffset, done: false };
+    }
+    // `done` reflects the whole file's terminal state, so a resume at/past the
+    // terminal event still closes the stream rather than hanging forever.
+    const done = fileIsDone(buf);
+    if (fromOffset >= buf.length)
+        return { events: [], newOffset: fromOffset, done };
+    const slice = buf.subarray(fromOffset);
+    const lastNl = slice.lastIndexOf(0x0a);
+    if (lastNl < 0)
+        return { events: [], newOffset: fromOffset, done }; // no complete line yet
+    const events = [];
+    let lineStart = 0; // byte index within slice
+    for (let i = 0; i <= lastNl; i++) {
+        if (slice[i] !== 0x0a)
+            continue;
+        const lineBuf = slice.subarray(lineStart, i); // excludes the newline
+        const endOffset = fromOffset + i + 1; // absolute byte offset just past '\n'
+        lineStart = i + 1;
+        const s = lineBuf.toString('utf-8').trim();
+        if (!s)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(s);
+        }
+        catch {
+            continue; // skip non-JSON (banner/preamble) lines
+        }
+        events.push({ event: normalizeEvent(obj), offset: endOffset });
+    }
+    return { events, newOffset: fromOffset + lastNl + 1, done };
+}

package/dist/lib/serve/token.d.ts

@@ -0,0 +1,35 @@
+/** One issued token, stored by hash only. */
+export interface ControlTokenRecord {
+    /** Short public id for display / revocation (not secret). */
+    id: string;
+    /** SHA-256 hex of the raw token. */
+    hash: string;
+    /** Human label, e.g. "muqsit-iphone". */
+    label: string;
+    createdAt: string;
+}
+/**
+ * Mint a new control token, persist its hash, and return the raw token ONCE.
+ * The caller must surface it to the operator immediately — it cannot be
+ * recovered later.
+ */
+export declare function addControlToken(label: string): {
+    id: string;
+    token: string;
+};
+/**
+ * Ensure at least one token exists. Returns the raw token only when it had to
+ * mint one (first `--control` boot); otherwise `{ created: false }` and the
+ * existing tokens stand.
+ */
+export declare function ensureControlToken(label?: string): {
+    created: true;
+    id: string;
+    token: string;
+} | {
+    created: false;
+};
+/** True when `presented` matches a stored token hash (constant-time compare). */
+export declare function verifyControlToken(presented: string | undefined): boolean;
+/** List issued tokens (hashes only — safe to display). */
+export declare function listControlTokens(): ControlTokenRecord[];

package/dist/lib/serve/token.js

@@ -0,0 +1,85 @@
+/**
+ * Bearer-token store for the authenticated `agents serve --control` server.
+ *
+ * Only the SHA-256 *hash* of each token is written to disk — the raw token is
+ * shown once at creation (like an API key) and never persisted, so a leaked
+ * store file cannot be replayed. This is the anchor-side credential the iOS
+ * cockpit presents on every request; `agents devices pair-ios` (Phase 3) mints
+ * additional per-device tokens through {@link addControlToken}.
+ *
+ * Store path: `<cache>/serve/control-tokens.json` — under `.cache/`, which is
+ * gitignored, so no credential material lands in a version-controlled repo.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import { getCacheDir } from '../state.js';
+function storePath() {
+    return path.join(getCacheDir(), 'serve', 'control-tokens.json');
+}
+function readStore() {
+    try {
+        const raw = fs.readFileSync(storePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.tokens))
+            return parsed;
+    }
+    catch {
+        // Missing/corrupt store → start empty; a fresh token gets minted below.
+    }
+    return { tokens: [] };
+}
+function writeStore(store) {
+    const p = storePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    // 0600: readable only by the owner — it holds token hashes. `mode` on
+    // writeFileSync is honored only at *creation*, so chmod every write to
+    // self-heal if the perms were ever widened externally (this is a credential
+    // file, even if only hashes).
+    fs.writeFileSync(p, JSON.stringify(store, null, 2), { mode: 0o600 });
+    fs.chmodSync(p, 0o600);
+}
+function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+/**
+ * Mint a new control token, persist its hash, and return the raw token ONCE.
+ * The caller must surface it to the operator immediately — it cannot be
+ * recovered later.
+ */
+export function addControlToken(label) {
+    const store = readStore();
+    const id = randomBytes(4).toString('hex');
+    const token = randomBytes(32).toString('hex');
+    store.tokens.push({ id, hash: sha256(token), label, createdAt: new Date().toISOString() });
+    writeStore(store);
+    return { id, token };
+}
+/**
+ * Ensure at least one token exists. Returns the raw token only when it had to
+ * mint one (first `--control` boot); otherwise `{ created: false }` and the
+ * existing tokens stand.
+ */
+export function ensureControlToken(label = 'default') {
+    const store = readStore();
+    if (store.tokens.length > 0)
+        return { created: false };
+    const { id, token } = addControlToken(label);
+    return { created: true, id, token };
+}
+/** True when `presented` matches a stored token hash (constant-time compare). */
+export function verifyControlToken(presented) {
+    if (!presented)
+        return false;
+    const want = Buffer.from(sha256(presented), 'hex');
+    for (const rec of readStore().tokens) {
+        const have = Buffer.from(rec.hash, 'hex');
+        if (have.length === want.length && timingSafeEqual(have, want))
+            return true;
+    }
+    return false;
+}
+/** List issued tokens (hashes only — safe to display). */
+export function listControlTokens() {
+    return readStore().tokens;
+}

package/dist/lib/session/bundle.d.ts

@@ -76,6 +76,12 @@ export interface BuildRecordOpts {
     redact: boolean;
     /** Non-null → seal each body with this key; null → plaintext bodies. */
     encryptKey: Buffer | null;
+    /**
+     * Literal secret values to mask verbatim during redaction (value-aware pass):
+     * e.g. live credentials from an injected secrets bundle, so they never leak in
+     * an exported transcript regardless of format. Only used when `redact` is set.
+     */
+    knownSecrets?: readonly string[];
 }
 /** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
 export declare function specForAgent(agentId: string): SyncAgentSpec | undefined;
@@ -104,6 +110,14 @@ export declare function makeHeader(args: {
 export declare function mergeRecords(sets: BundleRecord[][]): BundleRecord[];
 /** Serialize a bundle to its NDJSON wire form (header line + one line per record). */
 export declare function serializeBundle(header: BundleHeader, records: BundleRecord[]): string;
+/**
+ * Write a serialized bundle to disk owner-only (0600). A bundle carries raw
+ * transcript bodies — even redacted, never world/group-readable — and encryption
+ * is opt-in, so the file mode is the baseline confidentiality guard. `mode` on
+ * `writeFileSync` only applies when the file is created, so we `chmod` too to
+ * clamp an existing (possibly looser) file on overwrite.
+ */
+export declare function writeBundleFile(outPath: string, wire: string): void;
 /** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
 export declare function parseBundle(text: string): ParsedBundle;
 /** Placement outcome for one record, computed against what is already on disk. */

package/dist/lib/session/bundle.js

@@ -42,7 +42,7 @@ export function isExportableAgent(agentId) {
 export function buildRecord(file, opts) {
     let body = fs.readFileSync(file.absPath, 'utf-8');
     if (opts.redact)
-        body = redactSecrets(body);
+        body = redactSecrets(body, opts.knownSecrets);
     const hash = hashContent(body);
     const size = Buffer.byteLength(body, 'utf-8');
     let stored = body;
@@ -105,6 +105,17 @@ export function serializeBundle(header, records) {
         lines.push(JSON.stringify(r));
     return lines.join('\n') + '\n';
 }
+/**
+ * Write a serialized bundle to disk owner-only (0600). A bundle carries raw
+ * transcript bodies — even redacted, never world/group-readable — and encryption
+ * is opt-in, so the file mode is the baseline confidentiality guard. `mode` on
+ * `writeFileSync` only applies when the file is created, so we `chmod` too to
+ * clamp an existing (possibly looser) file on overwrite.
+ */
+export function writeBundleFile(outPath, wire) {
+    fs.writeFileSync(outPath, wire, { encoding: 'utf-8', mode: 0o600 });
+    fs.chmodSync(outPath, 0o600);
+}
 /** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
 export function parseBundle(text) {
     const lines = text.split('\n').filter(l => l.trim().length > 0);

package/dist/lib/session/remote-list.js

@@ -18,7 +18,7 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { resolveExplicitTargets } from '../devices/resolve-target.js';
-import { loadDevices } from '../devices/registry.js';
+import { loadDevices, isControlDevice } from '../devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
@@ -129,6 +129,10 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
                 continue;
             if (normalizeHost(d.name) === self)
                 continue;
+            // Control-only devices (a phone/tablet running the cockpit) drive the fleet
+            // but never run agents — never dial them, whatever their platform reads as.
+            if (isControlDevice(d))
+                continue;
             // Only machines that can actually run the CLI. iOS/tablet nodes register as
             // `unknown` platform and can never answer, so skip them rather than burn a
             // full ConnectTimeout on each.

package/dist/lib/session/state.d.ts

@@ -14,7 +14,8 @@
  * markers. Codex has no such tools, so it falls back to last-role + question
  * shape + mtime — same function, driven off the normalized events.
  */
-import type { SessionAttachment, SessionEvent } from './types.js';
+import type { SessionAttachment, SessionEvent, TodoItem, TodoProgress } from './types.js';
+export type { TodoItem, TodoProgress };
 export type SessionActivity = 'working' | 'waiting_input' | 'idle';
 export type AwaitingReason = 'question' | 'plan_review' | 'permission';
 /** One discrete choice the agent offered the user. */
@@ -41,28 +42,6 @@ export interface StructuredQuestion {
     reason: AwaitingReason;
     options?: QuestionOption[];
 }
-/** One `TodoWrite` checklist item, as Claude's plan tool emits it. */
-export interface TodoItem {
-    content: string;
-    status: 'pending' | 'in_progress' | 'completed';
-    /** Present-continuous label shown while this item is the active step. */
-    activeForm?: string;
-}
-/**
- * Live plan progress derived from the most recent `TodoWrite` in the transcript
- * (RUSH-1380). Lets the Factory Floor show "N/M done" + the current step for any
- * session — including remote / device-dispatched agents that carry no local
- * tool-call stream — instead of only a coarse working/idle verb.
- */
-export interface TodoProgress {
-    items: TodoItem[];
-    /** Count of completed items. */
-    done: number;
-    /** Total items. */
-    total: number;
-    /** The in-progress item's activeForm (falls back to its content). The live step. */
-    activeForm?: string;
-}
 export interface DetectedPr {
     url: string;
     number?: number;
@@ -140,8 +119,11 @@ export interface StateContext {
     activeWindowMs?: number;
 }
 /**
- * Derive live plan progress from a `TodoWrite` tool call's args. Returns undefined
- * when there is no usable list, so a session with no plan carries no `todos` field.
+ * Derive live plan progress from a checklist tool call's args. Accepts both
+ * Claude's `TodoWrite` (`todos: [{content,status,activeForm}]`) and Codex's
+ * `update_plan` (`plan: [{step,status}]`) shapes, so the CLI is the single source
+ * of checklist state for every agent. Returns undefined when there is no usable
+ * list, so a session with no plan carries no `todos` field.
  */
 export declare function extractTodoProgress(args?: Record<string, any>): TodoProgress | undefined;
 /** Detect a worktree from the session cwd, per the `.agents/worktrees/<slug>/` convention. */

package/dist/lib/session/state.js

@@ -47,14 +47,22 @@ const PROSE_QUESTION_FRESH_MS = 30 * 60_000;
 /** Claude tool names that structurally mean "the agent handed control back to you". */
 const PLAN_TOOL = 'ExitPlanMode';
 const ASK_TOOL = 'AskUserQuestion';
-/** Claude's live plan/checklist tool. */
+/** The live plan/checklist tools: Claude's `TodoWrite` and Codex's `update_plan`. */
 const TODO_TOOL = 'TodoWrite';
+const CODEX_PLAN_TOOL = 'update_plan';
 /**
- * Derive live plan progress from a `TodoWrite` tool call's args. Returns undefined
- * when there is no usable list, so a session with no plan carries no `todos` field.
+ * Derive live plan progress from a checklist tool call's args. Accepts both
+ * Claude's `TodoWrite` (`todos: [{content,status,activeForm}]`) and Codex's
+ * `update_plan` (`plan: [{step,status}]`) shapes, so the CLI is the single source
+ * of checklist state for every agent. Returns undefined when there is no usable
+ * list, so a session with no plan carries no `todos` field.
  */
 export function extractTodoProgress(args) {
-    const raw = args?.todos;
+    const raw = Array.isArray(args?.todos)
+        ? args.todos
+        : Array.isArray(args?.plan)
+            ? args.plan
+            : undefined;
     if (!Array.isArray(raw) || raw.length === 0)
         return undefined;
     const items = [];
@@ -64,7 +72,9 @@ export function extractTodoProgress(args) {
             ? t.content
             : typeof t?.text === 'string' && t.text
                 ? t.text
-                : activeForm ?? '';
+                : typeof t?.step === 'string' && t.step
+                    ? t.step
+                    : activeForm ?? '';
         if (!content)
             continue;
         const status = t?.status === 'completed' || t?.status === 'in_progress' ? t.status : 'pending';
@@ -318,7 +328,7 @@ export function inferActivity(events, ctx = {}) {
     // Live plan progress: the most recent TodoWrite's checklist (RUSH-1380). Attached
     // to `base` so every return path below carries it — a working, waiting, or idle
     // session all keep showing how far the plan got.
-    const lastTodo = lastOf(meaningful, e => e.type === 'tool_use' && e.tool === TODO_TOOL);
+    const lastTodo = lastOf(meaningful, e => e.type === 'tool_use' && (e.tool === TODO_TOOL || e.tool === CODEX_PLAN_TOOL));
     const todos = lastTodo ? extractTodoProgress(lastTodo.args) : undefined;
     const base = {
         activity: 'idle',