@phnx-labs/agents-cli 1.20.63 → 1.20.65

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',

package/dist/lib/session/sync/agents.d.ts

@@ -12,23 +12,54 @@
  * also exists locally always wins — the mirror only ever fills in sessions
  * originated on other machines.
  */
-export interface LocalTranscript {
+/** One constituent file of a session — a session has exactly one for file-shaped
+ *  agents (Claude, Codex, …), and many for directory-shaped ones (Kimi). */
+export interface SessionFile {
     /** Absolute path on this machine. */
     absPath: string;
-    /** Globally-unique session id (the grouping key across machines). */
-    sessionId: string;
     /** Path relative to the agent's subdir root — preserved in the mirror layout. */
     relKey: string;
 }
+export interface LocalTranscript {
+    /** Globally-unique session id (the grouping key across machines). */
+    sessionId: string;
+    /** Every file that makes up this session. Length 1 for file-shaped agents. */
+    files: SessionFile[];
+}
 export interface SyncAgentSpec {
     id: string;
     /** Config subdir under the agent home that holds transcripts. */
     subdir: string;
     /** File extension to walk for this agent (defaults to .jsonl). */
     ext?: string;
+    /**
+     * A session is a DIRECTORY of files (e.g. Kimi: state.json + agents/…/wire.jsonl
+     * + per-tool task sidecars), not a single transcript. When set, every file under
+     * the session dir (matching `exts`, passing `fileFilter`) syncs, is stored under
+     * its own R2 sub-key, and is mirrored at its own relative path — instead of the
+     * file-shaped "one transcript per session" model.
+     */
+    dirShaped?: boolean;
+    /** Extensions a dir-shaped agent walks (defaults to `[ext ?? '.jsonl']`). */
+    exts?: string[];
+    /** Optional per-file exclusion for dir-shaped agents (lock/scratch files, …). */
+    fileFilter?(relKey: string): boolean;
+    /**
+     * Extensions whose files are append-only event logs and therefore CRDT-mergeable
+     * (G-Set union across forked copies). A dir-shaped session usually mixes an
+     * append-only conversation log (`wire.jsonl`) with mutable metadata blobs
+     * (`state.json`) — line-unioning the latter would corrupt it, so any file NOT
+     * matching an entry here is reconciled last-writer-wins instead. Undefined (the
+     * file-shaped default) means every file is mergeable — the single `.jsonl`
+     * transcript keeps its existing union behaviour.
+     */
+    mergeableExts?: string[];
     /** Derive the session id from a storage-relative key. */
     sessionIdFromRelKey(relKey: string): string;
 }
+/** True when a file at `relKey` is an append-only log that CRDT-unions across
+ *  forks; false when it must be reconciled last-writer-wins (mutable blob). */
+export declare function isMergeableFile(spec: SyncAgentSpec, relKey: string): boolean;
 export declare const SYNC_AGENTS: SyncAgentSpec[];
 /**
  * List this machine's own transcript files for an agent, EXCLUDING the sync
@@ -38,10 +69,27 @@ export declare const SYNC_AGENTS: SyncAgentSpec[];
 export declare function listLocalTranscripts(spec: SyncAgentSpec): LocalTranscript[];
 /** Session ids this machine holds locally (live home), used to skip mirror writes. */
 export declare function localSessionIds(spec: SyncAgentSpec): Set<string>;
-/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+/**
+ * Absolute mirror path for a remote machine's transcript — lands in a scan root.
+ *
+ * `machine` and `relKey` come from a peer's manifest (untrusted: any peer with
+ * write access to the shared bucket controls them). Unlike the push side, which
+ * already drops `relKey` starting with `..` when building the manifest, the pull
+ * side would otherwise `fs.writeFileSync` at this path with peer-controlled
+ * content. `machine` is constrained to a single segment and `relKey` (which may
+ * legitimately nest, e.g. `projects/x/y.jsonl`) is contained beneath the
+ * per-machine mirror root, so a crafted `relKey` like `../../../.ssh/authorized_keys`
+ * cannot write outside `~/.agents/.history/backups/<agent>/<machine>/<subdir>`.
+ */
 export declare function mirrorPath(spec: SyncAgentSpec, machine: string, relKey: string): string;
-/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
-export declare function objectKey(machine: string, agentId: string, sessionId: string): string;
+/**
+ * R2 object key for a transcript.
+ *  - file-shaped (relKey omitted): sessions/<machine>/<agent>/<sessionId>.jsonl —
+ *    unchanged, so existing claude/codex/droid objects keep their keys.
+ *  - dir-shaped (relKey given): sessions/<machine>/<agent>/<sessionId>/<relKey> —
+ *    one object per constituent file of the session directory.
+ */
+export declare function objectKey(machine: string, agentId: string, sessionId: string, relKey?: string): string;
 /** R2 object key for a machine's manifest. */
 export declare function manifestKey(machine: string): string;
 /** Prefix under which all machine manifests live (for discovery). */

package/dist/lib/session/sync/config.js

@@ -3,7 +3,7 @@
  * machine's stable identity. Credentials come from the `r2.backups` secrets
  * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../../secrets/bundles.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
 /**
@@ -12,7 +12,13 @@ export const SYNC_BUNDLE = 'r2.backups';
  * without real credentials (no silent fallback).
  */
 function resolveR2Config() {
-    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync' });
+    // The daemon monitor loop is headless by construction (no TTY, ever), so
+    // isHeadlessSecretsContext() is true here and this resolves broker-only — a
+    // broker miss can never pop an unattended Touch ID sheet on the user's screen
+    // (same rationale as daemon.ts readDaemonClaudeOAuthToken). Using the shared
+    // predicate rather than a literal keeps it consistent with the other callers
+    // and lets any interactive caller of loadR2Config still prompt.
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync', agentOnly: isHeadlessSecretsContext() });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();

package/dist/lib/session/sync/manifest.d.ts

@@ -18,12 +18,23 @@ export interface ManifestEntry {
     /** Latest event timestamp in the transcript. */
     lastTs: string;
 }
-/** sessionId -> entry */
-export type AgentManifest = Record<string, ManifestEntry>;
+/**
+ * sessionId -> the session's file entries.
+ *  - file-shaped agents (claude/codex/droid) store a single `ManifestEntry`,
+ *    byte-identical to the pre-multi-file format, so a machine on an older CLI
+ *    reads them unchanged.
+ *  - dir-shaped agents (kimi) store a `ManifestEntry[]`, one per constituent file.
+ *    A machine that predates multi-file support skips these (an unknown agent is
+ *    skipped whole; a kimi-aware-but-file-shaped reader fails to find the flat
+ *    object key and simply retries — it never crashes or corrupts).
+ */
+export type AgentManifest = Record<string, ManifestEntry | ManifestEntry[]>;
+/** Normalize a manifest value to its file-entry list (single entry -> length-1). */
+export declare function manifestEntries(value: ManifestEntry | ManifestEntry[]): ManifestEntry[];
 export interface Manifest {
     machine: string;
     updatedAt: string;
-    /** agentId -> (sessionId -> entry) */
+    /** agentId -> (sessionId -> entry | entry[]) */
     agents: Record<string, AgentManifest>;
 }
 export declare function emptyManifest(machine: string, updatedAt: string): Manifest;

package/dist/lib/session/sync/manifest.js

@@ -13,6 +13,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { getCacheDir } from '../../state.js';
+/** Normalize a manifest value to its file-entry list (single entry -> length-1). */
+export function manifestEntries(value) {
+    return Array.isArray(value) ? value : [value];
+}
 export function emptyManifest(machine, updatedAt) {
     return { machine, updatedAt, agents: {} };
 }

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

@@ -55,10 +55,31 @@ export interface PendingSession {
  */
 export declare function selectSessionsToFetch(copies: Map<string, Map<string, RemoteCopy[]>>, localIdsByAgent: Map<string, Set<string>>, pullState: PullState): PendingSession[];
 /**
- * Resolve the mirror destination + merged content for one session. Pure.
+ * Resolve the mirror destination + reconciled content for ONE file across its
+ * copies (every copy here is the same file — same relKey — held by a different
+ * machine). Pure.
+ *
  * The canonical path comes from the lexicographically-smallest machine so every
- * puller derives an identical location; the content is the CRDT union of copies.
+ * puller derives an identical location. The content depends on the file's kind
+ * (see `isMergeableFile`):
+ *  - append-only logs (a transcript `.jsonl`) take the CRDT G-Set union — every
+ *    machine converges to byte-identical output regardless of order.
+ *  - mutable blobs (Kimi `state.json`) can't be line-unioned without corruption,
+ *    so they resolve **last-writer-wins**: the copy with the latest event
+ *    timestamp, tie-broken by content hash so the pick is deterministic fleet-wide.
+ */
+/**
+ * The `lastTs` a manifest entry carries for one file. Append-only logs (a
+ * conversation `.jsonl`) embed per-line event timestamps, so their recency is
+ * the latest line timestamp (`transcriptStats`). Mutable blobs (Kimi
+ * `state.json`, the per-tool `tasks/*.json` sidecars) carry no event timestamp —
+ * their own `updatedAt`/`createdAt` fields are agent-specific and unreliable — so
+ * their "last written" signal is the file mtime. Without this, `transcriptStats`
+ * returns `''` for every blob and the last-writer-wins branch in
+ * `resolveMirrorWrite` silently degrades to "highest-hash-wins", which can pick a
+ * stale copy over the genuinely newer one.
  */
+export declare function deriveLastTs(spec: SyncAgentSpec, relKey: string, content: string, mtimeMs: number): string;
 export declare function resolveMirrorWrite(spec: SyncAgentSpec, copies: RemoteCopy[], contents: string[]): {
     dest: string;
     content: string;

package/dist/lib/session/sync/sync.js

@@ -18,10 +18,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { R2Client } from './r2.js';
 import { loadR2Config, machineId } from './config.js';
-import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
+import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, isMergeableFile, SESSIONS_PREFIX, } from './agents.js';
 import { mergeTranscripts, transcriptStats } from './crdt.js';
 import { resolveSyncEncKey, encryptTranscript, decryptTranscriptBody } from './transcript-crypto.js';
-import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
+import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, manifestEntries, } from './manifest.js';
 const nowIso = () => new Date().toISOString();
 function specById(id) {
     return SYNC_AGENTS.find(s => s.id === id);
@@ -42,45 +42,59 @@ async function pushOwn(r2, me, encKey, opts, result) {
     for (const spec of SYNC_AGENTS) {
         const agentManifest = {};
         for (const t of listLocalTranscripts(spec)) {
-            let stat;
-            try {
-                stat = fs.statSync(t.absPath);
-            }
-            catch {
-                continue;
-            }
-            const prevEntry = prev?.agents?.[spec.id]?.[t.sessionId];
-            if (prevEntry && ledgerUnchanged(ledger, t.absPath, stat.size, stat.mtimeMs)) {
-                agentManifest[t.sessionId] = prevEntry; // unchanged: reuse, no read, no upload
-                result.pushSkipped++;
-                continue;
-            }
-            let content;
-            try {
-                content = fs.readFileSync(t.absPath, 'utf-8');
-            }
-            catch {
-                continue;
-            }
-            // Identity for CRDT merge is the PLAINTEXT hash (ciphertext is
-            // non-deterministic), so hash + manifest are computed on cleartext; only
-            // the stored object body is sealed.
-            const hash = hashContent(content);
-            const { lastTs } = transcriptStats(content);
-            const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
-            const body = encKey ? encryptTranscript(content, encKey) : content;
-            const contentType = encKey ? 'application/json' : 'application/x-ndjson';
-            try {
-                await r2.put(objectKey(me, spec.id, t.sessionId), body, contentType);
-                ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
-                agentManifest[t.sessionId] = entry;
-                result.pushed++;
-                if (opts.verbose)
-                    opts.log?.(`  push ${spec.id}/${t.sessionId.slice(0, 8)} (${stat.size}B)`);
-            }
-            catch (err) {
-                result.errors.push(`push ${spec.id}/${t.sessionId}: ${err.message}`);
+            // A session is one file (file-shaped) or many (dir-shaped). Push each file
+            // that changed, reusing the prior manifest entry (keyed by relKey) for the
+            // ones the ledger shows unchanged. Object keys nest under the session id for
+            // dir-shaped agents and stay flat for file-shaped ones (unchanged keys).
+            const prevVal = prev?.agents?.[spec.id]?.[t.sessionId];
+            const prevByRel = new Map((prevVal ? manifestEntries(prevVal) : []).map(e => [e.relKey, e]));
+            const entries = [];
+            for (const f of t.files) {
+                let stat;
+                try {
+                    stat = fs.statSync(f.absPath);
+                }
+                catch {
+                    continue;
+                }
+                const prevEntry = prevByRel.get(f.relKey);
+                if (prevEntry && ledgerUnchanged(ledger, f.absPath, stat.size, stat.mtimeMs)) {
+                    entries.push(prevEntry); // unchanged: reuse, no read, no upload
+                    result.pushSkipped++;
+                    continue;
+                }
+                let content;
+                try {
+                    content = fs.readFileSync(f.absPath, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                // Identity for CRDT merge is the PLAINTEXT hash (ciphertext is
+                // non-deterministic), so hash + manifest are computed on cleartext; only
+                // the stored object body is sealed.
+                const hash = hashContent(content);
+                const lastTs = deriveLastTs(spec, f.relKey, content, stat.mtimeMs);
+                const entry = { relKey: f.relKey, size: stat.size, hash, lastTs };
+                const body = encKey ? encryptTranscript(content, encKey) : content;
+                const contentType = encKey ? 'application/json' : 'application/x-ndjson';
+                try {
+                    await r2.put(objectKey(me, spec.id, t.sessionId, spec.dirShaped ? f.relKey : undefined), body, contentType);
+                    ledgerRecord(ledger, f.absPath, stat.size, stat.mtimeMs, hash);
+                    entries.push(entry);
+                    result.pushed++;
+                    const label = spec.dirShaped ? `${t.sessionId.slice(0, 8)}/${f.relKey}` : t.sessionId.slice(0, 8);
+                    if (opts.verbose)
+                        opts.log?.(`  push ${spec.id}/${label} (${stat.size}B)`);
+                }
+                catch (err) {
+                    result.errors.push(`push ${spec.id}/${t.sessionId}/${f.relKey}: ${err.message}`);
+                }
             }
+            // File-shaped: store the single entry (byte-identical to the old format so
+            // older CLIs read it unchanged). Dir-shaped: store the per-file array.
+            if (entries.length > 0)
+                agentManifest[t.sessionId] = spec.dirShaped ? entries : entries[0];
         }
         if (Object.keys(agentManifest).length > 0)
             manifest.agents[spec.id] = agentManifest;
@@ -115,17 +129,60 @@ export function selectSessionsToFetch(copies, localIdsByAgent, pullState) {
     return pending;
 }
 /**
- * Resolve the mirror destination + merged content for one session. Pure.
+ * Resolve the mirror destination + reconciled content for ONE file across its
+ * copies (every copy here is the same file — same relKey — held by a different
+ * machine). Pure.
+ *
  * The canonical path comes from the lexicographically-smallest machine so every
- * puller derives an identical location; the content is the CRDT union of copies.
+ * puller derives an identical location. The content depends on the file's kind
+ * (see `isMergeableFile`):
+ *  - append-only logs (a transcript `.jsonl`) take the CRDT G-Set union — every
+ *    machine converges to byte-identical output regardless of order.
+ *  - mutable blobs (Kimi `state.json`) can't be line-unioned without corruption,
+ *    so they resolve **last-writer-wins**: the copy with the latest event
+ *    timestamp, tie-broken by content hash so the pick is deterministic fleet-wide.
  */
+/**
+ * The `lastTs` a manifest entry carries for one file. Append-only logs (a
+ * conversation `.jsonl`) embed per-line event timestamps, so their recency is
+ * the latest line timestamp (`transcriptStats`). Mutable blobs (Kimi
+ * `state.json`, the per-tool `tasks/*.json` sidecars) carry no event timestamp —
+ * their own `updatedAt`/`createdAt` fields are agent-specific and unreliable — so
+ * their "last written" signal is the file mtime. Without this, `transcriptStats`
+ * returns `''` for every blob and the last-writer-wins branch in
+ * `resolveMirrorWrite` silently degrades to "highest-hash-wins", which can pick a
+ * stale copy over the genuinely newer one.
+ */
+export function deriveLastTs(spec, relKey, content, mtimeMs) {
+    if (isMergeableFile(spec, relKey))
+        return transcriptStats(content).lastTs;
+    return new Date(mtimeMs).toISOString();
+}
 export function resolveMirrorWrite(spec, copies, contents) {
     const canonical = [...copies].sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0))[0];
-    const content = contents.length === 1 ? contents[0] : mergeTranscripts(contents);
+    let content;
+    if (contents.length === 1) {
+        content = contents[0];
+    }
+    else if (isMergeableFile(spec, canonical.entry.relKey)) {
+        content = mergeTranscripts(contents);
+    }
+    else {
+        // Last-writer-wins: highest (lastTs, hash) among the copies.
+        let win = 0;
+        for (let i = 1; i < copies.length; i++) {
+            const a = copies[i].entry, b = copies[win].entry;
+            if (a.lastTs > b.lastTs || (a.lastTs === b.lastTs && a.hash > b.hash))
+                win = i;
+        }
+        content = contents[win];
+    }
     return {
         dest: mirrorPath(spec, canonical.machine, canonical.entry.relKey),
         content,
-        merged: contents.length > 1,
+        // "merged" means an actual CRDT line-union happened — not a last-writer-wins
+        // pick of one mutable blob over another (that discards a copy, it doesn't merge).
+        merged: contents.length > 1 && isMergeableFile(spec, canonical.entry.relKey),
     };
 }
 /**
@@ -176,9 +233,13 @@ async function pullAndReconcile(r2, me, encKey, opts, result) {
             let byAgent = copies.get(agentId);
             if (!byAgent)
                 copies.set(agentId, (byAgent = new Map()));
-            for (const [sessionId, entry] of Object.entries(sessions)) {
+            for (const [sessionId, value] of Object.entries(sessions)) {
                 const list = byAgent.get(sessionId) ?? [];
-                list.push({ machine: m, entry });
+                // One RemoteCopy per (machine, file): file-shaped sessions contribute one,
+                // dir-shaped ones contribute an entry per constituent file. `manifestEntries`
+                // also normalizes a single-object entry written by an older CLI.
+                for (const entry of manifestEntries(value))
+                    list.push({ machine: m, entry });
                 byAgent.set(sessionId, list);
             }
         }
@@ -197,43 +258,85 @@ async function pullAndReconcile(r2, me, encKey, opts, result) {
     result.pullSkipped += candidates - pending.length; // local-owned or unchanged
     for (const { agentId, sessionId, copies: list, sig } of pending) {
         const spec = specById(agentId);
-        // Download each copy (could be a fork across >1 machine), keeping the
-        // result positionally aligned to `list` — null marks a copy we couldn't
-        // fetch this tick (404 / consistency lag / error).
-        const fetched = [];
+        // A dir-shaped session spans several files; reconcile each file independently
+        // (its copies across machines share one relKey). File-shaped sessions have a
+        // single group, so this collapses to the original one-file path.
+        const byRel = new Map();
         for (const c of list) {
-            try {
-                const body = await r2.get(objectKey(c.machine, agentId, sessionId));
-                // Decrypt before the body reaches the CRDT union — the merge and the
-                // mirror always operate on plaintext. A legacy plaintext object passes
-                // through untouched; an envelope without a key throws (surfaced below).
-                fetched.push(body === null ? null : decryptTranscriptBody(body, encKey));
-            }
-            catch (err) {
-                result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
-                fetched.push(null);
+            const g = byRel.get(c.entry.relKey);
+            if (g)
+                g.push(c);
+            else
+                byRel.set(c.entry.relKey, [c]);
+        }
+        // Resolve every file's write before touching disk. If ANY file's fetch is
+        // incomplete (a copy 404s / consistency lag), abandon the WHOLE session this
+        // tick — no writes, no pull-state stamp — so it retries intact next time
+        // rather than materializing half a session and stamping it done.
+        const writes = [];
+        let incomplete = false;
+        try {
+            for (const group of byRel.values()) {
+                const fetched = [];
+                for (const c of group) {
+                    try {
+                        const body = await r2.get(objectKey(c.machine, agentId, sessionId, spec.dirShaped ? c.entry.relKey : undefined));
+                        // Decrypt before the body reaches the CRDT union — merge + mirror always
+                        // operate on plaintext. A legacy plaintext object passes through
+                        // untouched; an envelope without a key throws (surfaced below).
+                        fetched.push(body === null ? null : decryptTranscriptBody(body, encKey));
+                    }
+                    catch (err) {
+                        result.errors.push(`get ${c.machine}/${sessionId}/${c.entry.relKey}: ${err.message}`);
+                        fetched.push(null);
+                    }
+                }
+                const resolved = reconcileCopies(spec, group, fetched);
+                if (!resolved) {
+                    incomplete = true;
+                    break;
+                }
+                writes.push(resolved);
             }
         }
-        // null ⇒ an incomplete fetch: skip the write AND the pull-state stamp so we
-        // retry next tick instead of persisting a partial union / abandoning a branch.
-        const resolved = reconcileCopies(spec, list, fetched);
-        if (!resolved)
+        catch (err) {
+            // `reconcileCopies` -> `mirrorPath` now rejects unsafe peer-controlled
+            // machine/relKey (C1 containment). That rejection must stay scoped to this
+            // one session: without this catch a single malicious/malformed manifest
+            // entry would throw out of the whole `pending` loop, skip the
+            // `savePullState` below, and re-throw every tick — a peer-triggered DoS on
+            // everyone else's session-sync. Record it and skip; never stamp pull-state
+            // for a rejected entry (so nothing marks the bad session "done").
+            result.errors.push(`resolve mirror ${agentId}/${sessionId}: ${err.message}`);
             continue;
-        const { dest, content, merged } = resolved;
+        }
+        if (incomplete)
+            continue; // retry next tick, session intact
         try {
-            let existing = null;
-            try {
-                existing = fs.readFileSync(dest, 'utf-8');
+            let changed = false;
+            let mergedAny = false;
+            for (const { dest, content, merged } of writes) {
+                let existing = null;
+                try {
+                    existing = fs.readFileSync(dest, 'utf-8');
+                }
+                catch { /* not present yet */ }
+                if (existing !== content) {
+                    fs.mkdirSync(path.dirname(dest), { recursive: true });
+                    fs.writeFileSync(dest, content, 'utf-8');
+                    changed = true;
+                    if (merged)
+                        mergedAny = true;
+                }
             }
-            catch { /* not present yet */ }
-            if (existing !== content) {
-                fs.mkdirSync(path.dirname(dest), { recursive: true });
-                fs.writeFileSync(dest, content, 'utf-8');
-                if (merged)
+            if (changed) {
+                if (mergedAny)
                     result.merged++;
                 result.pulled++;
                 if (opts.verbose) {
-                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)} <- ${list.map(c => c.machine).join('+')}`);
+                    const machines = [...new Set(list.map(c => c.machine))].join('+');
+                    const files = byRel.size > 1 ? ` (${byRel.size} files)` : '';
+                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)}${files} <- ${machines}`);
                 }
             }
             else {

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

@@ -41,6 +41,29 @@ export interface SessionAttachment {
     mediaType: string;
     sizeBytes?: number;
 }
+/** One checklist item, as Claude's `TodoWrite` (`content`) or Codex's `update_plan` (`step`) 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 checklist write in the transcript
+ * (Claude `TodoWrite` / Codex `update_plan`, RUSH-1380). Lets consumers 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;
+}
 /** Metadata attached when a session was spawned by `agents teams`. */
 export interface TeamOrigin {
     /** Teammate name if set, otherwise first 8 chars of the agent UUID. */
@@ -116,6 +139,13 @@ export interface SessionMeta {
      * recover the plan text — the CLI now carries it on the metadata row.
      */
     plan?: string;
+    /**
+     * Live plan progress from the most recent checklist write (Claude `TodoWrite`
+     * / Codex `update_plan`, RUSH-1503). Populated on `agents sessions <id> --json`
+     * from the state engine so the Factory panel reads the CLI's computed checklist
+     * instead of re-parsing the transcript. Absent when the session wrote no list.
+     */
+    todos?: TodoProgress;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

package/dist/lib/ssh-tunnel.d.ts

@@ -49,6 +49,8 @@ export declare const REMOTE_HELPER_PORT = 8765;
 export declare const REMOTE_TASK_NAME = "AgentsComputerHelper";
 /** Basename of the cross-published exe under native/computer-win/dist. */
 export declare const WIN_HELPER_EXE = "computer-helper-win.exe";
+/** Basename of the daemon's shared-secret token file under %LOCALAPPDATA%\agents. */
+export declare const WIN_HELPER_TOKEN_FILE = "helper-token";
 /**
  * Locate a locally built Windows daemon exe — a repo-checkout build output from
  * `scripts/build-win.sh`, or one bundled next to the package. Local paths are
@@ -101,6 +103,16 @@ export declare function remoteStatePath(device: string): string;
 export declare function readRemoteState(device: string): RemoteTunnelState | null;
 export declare function writeRemoteState(state: RemoteTunnelState): void;
 export declare function clearRemoteState(device: string): void;
+/**
+ * Local file holding the shared-secret token for a device's helper daemon.
+ * Written at `setup --host` (0600), read at `start --host` so the RPC client
+ * authenticates. The remote daemon reads the same value from its own
+ * `--token-file`; the CLI is the source of truth and never round-trips it back.
+ */
+export declare function helperTokenPath(device: string): string;
+export declare function readHelperToken(device: string): string | null;
+export declare function writeHelperToken(device: string, token: string): void;
+export declare function clearHelperToken(device: string): void;
 /** Resolve a registered device to its ssh pieces, or throw a clear error. */
 export declare function resolveRemoteDevice(name: string): Promise<{
     device: DeviceProfile;
@@ -123,7 +135,13 @@ export declare function buildVerifyPushScript(remotePath: string, expectedBytes:
  * survives ssh disconnect — the same rationale as the browser WMI launch. The
  * task is started immediately so the caller need not log out/in.
  */
-export declare function buildRegisterTaskScript(port: number, taskName: string): string;
+/**
+ * PowerShell that writes the shared-secret token under %LOCALAPPDATA%\agents
+ * with an owner-only ACL (inheritance removed, read granted only to the current
+ * user) and echoes the resolved path so the caller can pass it to `--token-file`.
+ */
+export declare function buildWriteTokenScript(token: string): string;
+export declare function buildRegisterTaskScript(port: number, taskName: string, tokenPath: string): string;
 /** PowerShell that unregisters the task and stops any running daemon process. */
 export declare function buildUnregisterTaskScript(taskName: string): string;
 /** Convert a Windows path returned by PowerShell into the scp/SFTP path form. */