@phnx-labs/agents-cli 1.20.63 → 1.20.65

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

@@ -0,0 +1,164 @@
+/**
+ * Portable session bundle — the on-the-wire format behind `agents sessions
+ * export` / `import` (RUSH-1710 / RUSH-1711).
+ *
+ * A bundle is a self-describing NDJSON stream: the FIRST line is a
+ * {@link BundleHeader}, every subsequent line is one {@link BundleRecord} (one
+ * constituent file of a session). NDJSON — not tar — because the bundle has to
+ * pipe cleanly over `agents ssh … export --stdout | … import -` (RUSH-1712)
+ * without any external archiver on either box, stays inspectable with `head`,
+ * and lets each file body carry its own encryption envelope.
+ *
+ * This module owns the FORMAT and the import PLACEMENT only; selecting which
+ * sessions to export (which needs the session DB) lives in the export command.
+ * Placement reuses the sync mirror model verbatim: a foreign machine's session
+ * lands at {@link mirrorPath}(spec, originMachine, relKey), exactly where the
+ * cross-machine sync writes it — so the existing scanner indexes it as a
+ * machine-tagged row and "local always wins" falls out of the scanner's
+ * live-home-first dedup with no extra logic here.
+ */
+import { type SyncAgentSpec } from './sync/agents.js';
+export declare const BUNDLE_KIND = "agents-session-bundle";
+export declare const BUNDLE_VERSION = 1;
+/** First line of a bundle: what it is and how the bodies are encoded. */
+export interface BundleHeader {
+    kind: typeof BUNDLE_KIND;
+    version: number;
+    /** ISO timestamp the bundle was produced. */
+    exportedAt: string;
+    /** Machine that produced the bundle (informational; per-record `machine` is authoritative for placement). */
+    origin: string;
+    /** True when record bodies are AES-256-GCM envelopes (see transcript-crypto). */
+    encrypted: boolean;
+    /** True when bodies were secret-scrubbed before hashing/sealing. */
+    redacted: boolean;
+    /** Number of file records that follow. */
+    count: number;
+    /** Distinct session count across those records. */
+    sessions: number;
+}
+/** One constituent file of one session. Dir-shaped sessions emit several, sharing `sessionId`. */
+export interface BundleRecord {
+    /** SYNC_AGENTS id (claude, codex, kimi, …). */
+    agent: string;
+    /** ORIGIN machine of this session — where placement mirrors it to. */
+    machine: string;
+    sessionId: string;
+    /** Storage-relative key within the agent's subdir (preserved on import). */
+    relKey: string;
+    /** Byte length of the plaintext body. */
+    size: number;
+    /** SHA-256 of the plaintext body — identity + byte-exact dedup. */
+    hash: string;
+    /** Human label carried from SessionMeta, if any. */
+    label?: string;
+    /** True when `body` is an encryption envelope rather than plaintext. */
+    encrypted: boolean;
+    /** File content: plaintext, or a transcript-crypto envelope when `encrypted`. */
+    body: string;
+}
+export interface ParsedBundle {
+    header: BundleHeader;
+    records: BundleRecord[];
+}
+/** A single file selected for export, resolved to an absolute on-disk path. */
+export interface FileToExport {
+    agent: string;
+    /** Origin machine of the session (self for live-home, the peer for a mirror). */
+    machine: string;
+    sessionId: string;
+    relKey: string;
+    absPath: string;
+    label?: string;
+}
+export interface BuildRecordOpts {
+    /** Scrub secrets from the body before hashing/sealing (default-on at the command layer). */
+    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;
+/** True when an agent's sessions can be represented in a bundle (has a sync spec). */
+export declare function isExportableAgent(agentId: string): boolean;
+/**
+ * Read one file and turn it into a bundle record. The hash and size are always
+ * computed over the PLAINTEXT (post-redaction) body, so they equal what lands on
+ * disk after import — keeping dedup byte-exact whether or not the bundle is
+ * encrypted.
+ */
+export declare function buildRecord(file: FileToExport, opts: BuildRecordOpts): BundleRecord;
+/** Build the header for a set of records. */
+export declare function makeHeader(args: {
+    origin: string;
+    exportedAt: string;
+    encrypted: boolean;
+    redacted: boolean;
+    records: BundleRecord[];
+}): BundleHeader;
+/**
+ * Merge record sets from several bundles (e.g. a fan-out pull across hosts),
+ * deduping by agent + origin machine + session + file so the same session seen
+ * from two peers lands once. First occurrence wins.
+ */
+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. */
+export type ImportStatus = 'new' | 'dup' | 'conflict' | 'unknown';
+export interface ImportPlanItem {
+    record: BundleRecord;
+    /** Absolute path the file lands at (empty for `unknown` agents). */
+    targetPath: string;
+    status: ImportStatus;
+}
+export interface PlanImportOpts {
+    /** Key to open encrypted record bodies (null → only plaintext bodies readable). */
+    decryptKey: Buffer | null;
+}
+/**
+ * Compute where each record lands and whether it duplicates / conflicts with an
+ * existing file. Pure w.r.t. the filesystem it reads (no writes). Dedup is
+ * byte-exact: a target that already holds an identical body is `dup`; a target
+ * that holds a DIFFERENT body is `conflict` (only overwritten with --overwrite).
+ * An agent with no sync spec is `unknown` and never placed.
+ */
+export declare function planImport(bundle: ParsedBundle, opts: PlanImportOpts): ImportPlanItem[];
+export interface WriteResult {
+    /** New files written. */
+    placed: number;
+    /** Byte-exact dups skipped. */
+    skipped: number;
+    /** Conflicts replaced (only with overwrite). */
+    overwritten: number;
+    /** Conflicts left in place (overwrite off). */
+    conflicts: number;
+    /** Records for agents with no sync spec. */
+    unknown: number;
+}
+export interface WriteImportOpts {
+    overwrite: boolean;
+    decryptKey: Buffer | null;
+}
+/**
+ * Materialize a plan to disk. `dup` records are always skipped (local wins);
+ * `conflict` records are replaced only when `overwrite` is set; `unknown` records
+ * are counted and skipped.
+ */
+export declare function writeImport(plan: ImportPlanItem[], opts: WriteImportOpts): WriteResult;

package/dist/lib/session/bundle.js

@@ -0,0 +1,200 @@
+/**
+ * Portable session bundle — the on-the-wire format behind `agents sessions
+ * export` / `import` (RUSH-1710 / RUSH-1711).
+ *
+ * A bundle is a self-describing NDJSON stream: the FIRST line is a
+ * {@link BundleHeader}, every subsequent line is one {@link BundleRecord} (one
+ * constituent file of a session). NDJSON — not tar — because the bundle has to
+ * pipe cleanly over `agents ssh … export --stdout | … import -` (RUSH-1712)
+ * without any external archiver on either box, stays inspectable with `head`,
+ * and lets each file body carry its own encryption envelope.
+ *
+ * This module owns the FORMAT and the import PLACEMENT only; selecting which
+ * sessions to export (which needs the session DB) lives in the export command.
+ * Placement reuses the sync mirror model verbatim: a foreign machine's session
+ * lands at {@link mirrorPath}(spec, originMachine, relKey), exactly where the
+ * cross-machine sync writes it — so the existing scanner indexes it as a
+ * machine-tagged row and "local always wins" falls out of the scanner's
+ * live-home-first dedup with no extra logic here.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { SYNC_AGENTS, mirrorPath } from './sync/agents.js';
+import { hashContent } from './sync/manifest.js';
+import { redactSecrets } from '../redact.js';
+import { encryptTranscript, decryptTranscriptBody } from './sync/transcript-crypto.js';
+export const BUNDLE_KIND = 'agents-session-bundle';
+export const BUNDLE_VERSION = 1;
+/** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
+export function specForAgent(agentId) {
+    return SYNC_AGENTS.find(s => s.id === agentId);
+}
+/** True when an agent's sessions can be represented in a bundle (has a sync spec). */
+export function isExportableAgent(agentId) {
+    return specForAgent(agentId) !== undefined;
+}
+/**
+ * Read one file and turn it into a bundle record. The hash and size are always
+ * computed over the PLAINTEXT (post-redaction) body, so they equal what lands on
+ * disk after import — keeping dedup byte-exact whether or not the bundle is
+ * encrypted.
+ */
+export function buildRecord(file, opts) {
+    let body = fs.readFileSync(file.absPath, 'utf-8');
+    if (opts.redact)
+        body = redactSecrets(body, opts.knownSecrets);
+    const hash = hashContent(body);
+    const size = Buffer.byteLength(body, 'utf-8');
+    let stored = body;
+    let encrypted = false;
+    if (opts.encryptKey) {
+        stored = encryptTranscript(body, opts.encryptKey);
+        encrypted = true;
+    }
+    const rec = {
+        agent: file.agent,
+        machine: file.machine,
+        sessionId: file.sessionId,
+        relKey: file.relKey,
+        size,
+        hash,
+        encrypted,
+        body: stored,
+    };
+    if (file.label)
+        rec.label = file.label;
+    return rec;
+}
+/** Build the header for a set of records. */
+export function makeHeader(args) {
+    const sessions = new Set(args.records.map(r => `${r.agent}:${r.machine}:${r.sessionId}`)).size;
+    return {
+        kind: BUNDLE_KIND,
+        version: BUNDLE_VERSION,
+        exportedAt: args.exportedAt,
+        origin: args.origin,
+        encrypted: args.encrypted,
+        redacted: args.redacted,
+        count: args.records.length,
+        sessions,
+    };
+}
+/**
+ * Merge record sets from several bundles (e.g. a fan-out pull across hosts),
+ * deduping by agent + origin machine + session + file so the same session seen
+ * from two peers lands once. First occurrence wins.
+ */
+export function mergeRecords(sets) {
+    const seen = new Set();
+    const out = [];
+    for (const set of sets) {
+        for (const r of set) {
+            const key = `${r.agent}:${r.machine}:${r.sessionId}:${r.relKey}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(r);
+        }
+    }
+    return out;
+}
+/** Serialize a bundle to its NDJSON wire form (header line + one line per record). */
+export function serializeBundle(header, records) {
+    const lines = [JSON.stringify(header)];
+    for (const r of 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);
+    if (lines.length === 0)
+        throw new Error('Empty session bundle.');
+    let header;
+    try {
+        header = JSON.parse(lines[0]);
+    }
+    catch {
+        throw new Error('Malformed session bundle: first line is not JSON.');
+    }
+    if (!header || header.kind !== BUNDLE_KIND) {
+        throw new Error(`Not an agents session bundle (kind=${header?.kind ?? 'missing'}).`);
+    }
+    if (header.version !== BUNDLE_VERSION) {
+        throw new Error(`Unsupported bundle version ${header.version} — this CLI reads v${BUNDLE_VERSION}.`);
+    }
+    const records = [];
+    for (let i = 1; i < lines.length; i++) {
+        try {
+            records.push(JSON.parse(lines[i]));
+        }
+        catch {
+            throw new Error(`Malformed session bundle: record on line ${i + 1} is not JSON.`);
+        }
+    }
+    return { header, records };
+}
+/**
+ * Compute where each record lands and whether it duplicates / conflicts with an
+ * existing file. Pure w.r.t. the filesystem it reads (no writes). Dedup is
+ * byte-exact: a target that already holds an identical body is `dup`; a target
+ * that holds a DIFFERENT body is `conflict` (only overwritten with --overwrite).
+ * An agent with no sync spec is `unknown` and never placed.
+ */
+export function planImport(bundle, opts) {
+    return bundle.records.map((record) => {
+        const spec = specForAgent(record.agent);
+        if (!spec)
+            return { record, targetPath: '', status: 'unknown' };
+        const body = decryptTranscriptBody(record.body, opts.decryptKey);
+        const bodyHash = hashContent(body);
+        const targetPath = mirrorPath(spec, record.machine, record.relKey);
+        let status = 'new';
+        if (fs.existsSync(targetPath)) {
+            const existing = fs.readFileSync(targetPath, 'utf-8');
+            status = hashContent(existing) === bodyHash ? 'dup' : 'conflict';
+        }
+        return { record, targetPath, status };
+    });
+}
+/**
+ * Materialize a plan to disk. `dup` records are always skipped (local wins);
+ * `conflict` records are replaced only when `overwrite` is set; `unknown` records
+ * are counted and skipped.
+ */
+export function writeImport(plan, opts) {
+    const res = { placed: 0, skipped: 0, overwritten: 0, conflicts: 0, unknown: 0 };
+    for (const item of plan) {
+        if (item.status === 'unknown') {
+            res.unknown++;
+            continue;
+        }
+        if (item.status === 'dup') {
+            res.skipped++;
+            continue;
+        }
+        if (item.status === 'conflict' && !opts.overwrite) {
+            res.conflicts++;
+            continue;
+        }
+        const body = decryptTranscriptBody(item.record.body, opts.decryptKey);
+        fs.mkdirSync(path.dirname(item.targetPath), { recursive: true });
+        fs.writeFileSync(item.targetPath, body, 'utf-8');
+        if (item.status === 'conflict')
+            res.overwritten++;
+        else
+            res.placed++;
+    }
+    return res;
+}

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

@@ -0,0 +1,12 @@
+import { type ParsedBundle } from './bundle.js';
+export interface RemotePullResult {
+    bundles: ParsedBundle[];
+    errors: string[];
+}
+/**
+ * Run `agents sessions export …exportArgs --stdout` on each host and parse the
+ * streamed bundle. A host that fails (unreachable, remote error, bad output) is
+ * collected in `errors` and skipped — one asleep peer never aborts the pull.
+ * `exportArgs` must NOT contain --host (the remote export runs for itself only).
+ */
+export declare function pullBundlesFromHosts(hosts: string[], exportArgs: string[]): Promise<RemotePullResult>;

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

@@ -0,0 +1,61 @@
+/**
+ * Multi-device session transfer over the EXISTING SSH fleet transport
+ * (RUSH-1712) — no R2, no daemon. `agents sessions export --host <h>` and
+ * `agents sessions import --from-host <h>` both run `agents sessions export
+ * … --stdout` ON the peer and stream the bundle back over the same SSH path the
+ * cross-machine listing already uses (resolveExplicitTargets + ssh-exec), then
+ * either write it (export) or import it (import) locally.
+ *
+ * This deliberately reuses ssh-exec / resolve-target rather than adding a second
+ * transport: the raw form `agents ssh boxA 'agents sessions export --stdout' |
+ * agents sessions import -` works with plain export/import; this module is just
+ * the one-shot wrapper around it.
+ */
+import chalk from 'chalk';
+import { sshExec } from '../ssh-exec.js';
+import { shellQuote } from '../ssh-exec.js';
+import { resolveExplicitTargets } from '../devices/resolve-target.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { parseBundle } from './bundle.js';
+/** Remote export can traverse many sessions; give it a generous ceiling. */
+const REMOTE_EXPORT_TIMEOUT_MS = 300_000;
+/** Build `agents <args>` for the peer's login shell (bash or PowerShell). */
+function remoteAgentsCommand(args, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({ args });
+    }
+    const inner = ['agents', ...args].map((t, i) => (i === 0 ? t : shellQuote(t))).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
+/**
+ * Run `agents sessions export …exportArgs --stdout` on each host and parse the
+ * streamed bundle. A host that fails (unreachable, remote error, bad output) is
+ * collected in `errors` and skipped — one asleep peer never aborts the pull.
+ * `exportArgs` must NOT contain --host (the remote export runs for itself only).
+ */
+export async function pullBundlesFromHosts(hosts, exportArgs) {
+    const targets = await resolveExplicitTargets(hosts);
+    const bundles = [];
+    const errors = [];
+    for (const t of targets) {
+        const cmd = remoteAgentsCommand(['sessions', 'export', ...exportArgs, '--stdout'], t.os);
+        process.stderr.write(chalk.dim(`Pulling sessions from ${t.name}…\n`));
+        const res = sshExec(t.target, cmd, { timeoutMs: REMOTE_EXPORT_TIMEOUT_MS });
+        if (res.timedOut) {
+            errors.push(`${t.name}: timed out after ${Math.round(REMOTE_EXPORT_TIMEOUT_MS / 1000)}s`);
+            continue;
+        }
+        if (res.code !== 0) {
+            const tail = res.stderr.trim().split('\n').filter(Boolean).pop();
+            errors.push(`${t.name}: remote export failed (${res.code ?? 'ssh error'})${tail ? ': ' + tail : ''}`);
+            continue;
+        }
+        try {
+            bundles.push(parseBundle(res.stdout));
+        }
+        catch (err) {
+            errors.push(`${t.name}: ${err.message}`);
+        }
+    }
+    return { bundles, errors };
+}

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. */