@phnx-labs/agents-cli 1.20.57 → 1.20.58

package/dist/lib/secrets/agent.js

@@ -132,127 +132,71 @@ function cliSpawn(sub) {
 function brokerSpawn() {
     return cliSpawn(['secrets', '_agent-run']);
 }
-// ─── Persistent launchd service ──────────────────────────────────────────────
-// On a heavily-loaded machine a freshly-spawned broker (a full CLI cold start)
-// can't get scheduled enough CPU to finish booting and bind its socket — so the
-// on-demand model fails exactly when there are many agents (the case we care
-// about). The fix is to run the broker as a launchd user service: started once
-// with RunAtLoad + KeepAlive, it stays up, and every read just connects. The
-// cold start happens once (and launchd retries until it wins), never per-read.
+// ─── Legacy standalone launchd service (retired, #416 step 2) ────────────────
+// Earlier versions ran the broker as its own launchd user service
+// (com.phnx-labs.agents-secrets-agent, shipped in 1.20.20) so a heavily-loaded
+// machine couldn't starve an on-demand cold start. That role now belongs to the
+// always-on daemon, which hosts the broker socket-first (#416 step 1) — one
+// supervised backbone instead of a second service. The functions below no
+// longer INSTALL the standalone service; they only DETECT and RETIRE a plist
+// left by an older version so the daemon can take over the socket. The upgrade
+// migration (postinstall) and `ensureAgentRunning` both drive the retire path.
 const SERVICE_LABEL = 'com.phnx-labs.agents-secrets-agent';
+// LaunchAgents dir is relocatable for tests via AGENTS_SECRETS_LAUNCHAGENTS_DIR.
+// A relocated dir is NOT launchd-managed (launchd only bootstraps plists from
+// the real ~/Library/LaunchAgents), so retirement there is a pure file removal.
+function launchAgentsDir() {
+    return process.env.AGENTS_SECRETS_LAUNCHAGENTS_DIR || path.join(os.homedir(), 'Library', 'LaunchAgents');
+}
 function servicePlistPath() {
-    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+    return path.join(launchAgentsDir(), `${SERVICE_LABEL}.plist`);
 }
-/** True if the launchd plist for the persistent broker is installed. */
+/** True if a legacy standalone-broker launchd plist is still installed. */
 export function secretsAgentServiceInstalled() {
     return onDarwin() && fs.existsSync(servicePlistPath());
 }
-function generateServicePlist() {
-    const { cmd, args } = cliSpawn(['secrets', '_agent-run', '--service']);
-    const progArgs = [cmd, ...args]
-        .map((a) => `    <string>${a.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</string>`)
-        .join('\n');
-    const logPath = path.join(agentDir(), 'service.log');
-    const home = os.homedir();
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>${SERVICE_LABEL}</string>
-  <key>ProgramArguments</key>
-  <array>
-${progArgs}
-  </array>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>ProcessType</key>
-  <string>Interactive</string>
-  <key>StandardOutPath</key>
-  <string>${logPath}</string>
-  <key>StandardErrorPath</key>
-  <string>${logPath}</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${home}/.bun/bin</string>
-  </dict>
-</dict>
-</plist>`;
-}
 /**
- * Install + start the persistent broker as a launchd user service (idempotent).
- * Writes the plist, bootstraps it into the GUI domain, and waits for the socket.
- * `ProcessType: Interactive` asks launchd to schedule it at foreground priority
- * so it can boot even when the machine is loaded. Returns true once reachable.
+ * Retire the legacy standalone secrets-agent launchd service: bootout the job
+ * (falling back to the legacy `unload`) and remove its plist so the always-on
+ * daemon owns the broker socket. Idempotent and best-effort — a no-op when no
+ * legacy plist is present. Does NOT wipe held bundles: the booted-out process's
+ * memory is gone anyway, and the daemon-hosted broker starts fresh.
  */
-export async function installSecretsAgentService(timeoutMs = 30000) {
-    if (!onDarwin())
-        return false;
+export function retireLegacySecretsAgentService() {
+    if (!onDarwin() || !secretsAgentServiceInstalled())
+        return;
     const plist = servicePlistPath();
-    fs.mkdirSync(path.dirname(plist), { recursive: true });
-    fs.writeFileSync(plist, generateServicePlist());
-    const uid = process.getuid?.() ?? 0;
-    // bootstrap is the modern API; fall back to legacy load. Both idempotent-ish.
-    try {
-        execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plist], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch {
+    // Only the real LaunchAgents dir is launchd-managed; a relocated (test) dir
+    // has no bootstrapped job, so skip launchctl and just remove the plist.
+    if (!process.env.AGENTS_SECRETS_LAUNCHAGENTS_DIR) {
+        const uid = process.getuid?.() ?? 0;
         try {
-            execFileSync('launchctl', ['load', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+            execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch {
+            try {
+                execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+            }
+            catch { /* not loaded */ }
         }
-        catch { /* may already be loaded */ }
     }
-    // kickstart to force an immediate start even if already bootstrapped.
     try {
-        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch { /* best effort */ }
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if ((await agentPing()).reachable)
-            return true;
-        await new Promise((r) => setTimeout(r, 200));
+        fs.unlinkSync(plist);
     }
-    return false;
+    catch { /* already gone */ }
 }
 /**
- * Kickstart the already-installed persistent broker so launchd relaunches it
- * onto the current on-disk code. Used by postinstall heal-on-upgrade. No-op if
- * the service isn't installed; never rewrites the plist or waits, so it's safe
- * and fast to call from an installer.
+ * Stop the persistent broker for `agents secrets stop`: wipe whatever the broker
+ * holds (forces Touch ID again on the next read), then retire any legacy
+ * standalone service. The daemon-hosted broker itself is left running — it is
+ * the always-on backbone, and stopping it would take down unrelated background
+ * work (routines, browser IPC, session-sync).
  */
-export function kickstartSecretsAgentService() {
-    if (!onDarwin() || !secretsAgentServiceInstalled())
-        return;
-    const uid = process.getuid?.() ?? 0;
-    try {
-        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch { /* best effort */ }
-}
-/** Stop + remove the persistent broker service, and wipe whatever it held. */
 export async function uninstallSecretsAgentService() {
     if (!onDarwin())
         return;
-    await agentLock(); // wipe the in-memory store before tearing down
-    const plist = servicePlistPath();
-    const uid = process.getuid?.() ?? 0;
-    try {
-        execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch {
-        try {
-            execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
-        }
-        catch { /* not loaded */ }
-    }
-    try {
-        fs.unlinkSync(plist);
-    }
-    catch { /* already gone */ }
+    await agentLock(); // wipe the in-memory store before retiring the legacy service
+    retireLegacySecretsAgentService();
 }
 // ─── Broker server (runs in the detached `secrets _agent-run` process) ───────
 /**
@@ -328,6 +272,46 @@ export function handleAgentRequest(store, req, now = Date.now()) {
 export function shouldWipeOnWatchEvent(chunk) {
     return /\bSLEEP\b/.test(chunk);
 }
+/**
+ * Bind the shared broker socket without stealing it from another live owner.
+ * Both the standalone service and daemon-hosted broker use this single path so
+ * either startup order is safe: a reachable owner wins, while an unreachable
+ * stale socket is reclaimed once.
+ */
+async function bindBrokerSocket(sock, onConnection) {
+    const listenOnce = () => new Promise((resolve, reject) => {
+        const server = net.createServer(onConnection);
+        const onError = (err) => {
+            if (err.code === 'EADDRINUSE')
+                resolve('inuse');
+            else
+                reject(err);
+        };
+        server.once('error', onError);
+        server.listen(sock, () => {
+            try {
+                fs.chmodSync(sock, 0o600);
+            }
+            catch { /* dir 0700 already gates it */ }
+            resolve(server);
+        });
+    });
+    let bound = await listenOnce();
+    if (bound !== 'inuse')
+        return bound;
+    if ((await agentPing()).reachable)
+        return null;
+    try {
+        fs.unlinkSync(sock);
+    }
+    catch { /* disappeared between probe and reclaim */ }
+    bound = await listenOnce();
+    if (bound !== 'inuse')
+        return bound;
+    if ((await agentPing()).reachable)
+        return null;
+    throw new Error(`Secrets broker socket is in use but unreachable: ${sock}`);
+}
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
@@ -335,7 +319,7 @@ export function shouldWipeOnWatchEvent(chunk) {
  */
 export async function runSecretsAgent(opts = {}) {
     if (!onDarwin())
-        return; // nothing to broker without biometry prompts
+        return null; // nothing to broker without biometry prompts
     // When launchd keeps us alive as a persistent service, never idle-exit:
     // exiting would just make launchd cold-start us again, reintroducing the
     // startup-under-load fragility the service exists to avoid.
@@ -352,7 +336,7 @@ export async function runSecretsAgent(opts = {}) {
         if (err?.code === 'EEXIST') {
             const holder = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
             if (!isNaN(holder) && isAlive(holder))
-                return; // another broker is live
+                return null; // another broker is live
             // Stale pid — reclaim it.
             try {
                 fs.unlinkSync(pidFile);
@@ -369,10 +353,42 @@ export async function runSecretsAgent(opts = {}) {
     // the process once it's been empty for IDLE_EXIT_MS so no idle broker lingers.
     let emptySince = Date.now();
     const sock = socketPath();
-    try {
-        fs.unlinkSync(sock);
-    }
-    catch { /* no stale socket */ }
+    const releasePid = () => {
+        try {
+            if (parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10) === process.pid) {
+                fs.unlinkSync(pidFile);
+            }
+        }
+        catch { /* gone or no longer ours */ }
+    };
+    // Register lifecycle handlers before socket arbitration. A persistent
+    // launchd service may spend its whole lifetime as the standby loser, and a
+    // kickstart/bootout during that wait must still release its pid-file lease.
+    let standbyTimer = null;
+    let cleanupActive = null;
+    let shuttingDown = false;
+    const onSigterm = () => shutdown(0);
+    const onSigint = () => shutdown(0);
+    const detachSignals = () => {
+        process.off('SIGTERM', onSigterm);
+        process.off('SIGINT', onSigint);
+    };
+    const shutdown = (code) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (standbyTimer) {
+            clearTimeout(standbyTimer);
+            standbyTimer = null;
+        }
+        if (cleanupActive)
+            cleanupActive();
+        else
+            releasePid();
+        process.exit(code);
+    };
+    process.on('SIGTERM', onSigterm);
+    process.on('SIGINT', onSigint);
     // Capture the version of the code we're running so the sweep can detect when
     // an in-place upgrade has landed and self-heal onto it. getCliVersion caches
     // this value for the process lifetime; getCliVersionFresh re-reads on disk.
@@ -412,7 +428,7 @@ export async function runSecretsAgent(opts = {}) {
             emptySince = Date.now();
         return resp;
     };
-    const server = net.createServer((conn) => {
+    const onConnection = (conn) => {
         conn.setEncoding('utf-8');
         let buf = '';
         conn.on('data', (chunk) => {
@@ -434,14 +450,40 @@ export async function runSecretsAgent(opts = {}) {
             }
         });
         conn.on('error', () => { });
-    });
+    };
+    let server = null;
+    do {
+        try {
+            server = await bindBrokerSocket(sock, onConnection);
+        }
+        catch (err) {
+            detachSignals();
+            releasePid();
+            throw err;
+        }
+        if (!server && persistent) {
+            // launchd KeepAlive would immediately relaunch a persistent loser if it
+            // returned here. Stay quiescent instead, then claim the socket if the
+            // daemon-hosted owner goes away. The pid file keeps launchd/manual starts
+            // from creating additional waiters while this process is standing by.
+            do {
+                await new Promise((resolve) => {
+                    standbyTimer = setTimeout(() => {
+                        standbyTimer = null;
+                        resolve();
+                    }, 1000);
+                });
+            } while ((await agentPing()).reachable);
+        }
+    } while (!server && persistent);
+    if (!server) {
+        detachSignals();
+        releasePid();
+        return null;
+    }
     let watcher = null;
     let sweepTimer = null;
-    let shuttingDown = false;
-    const shutdown = (code) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
+    cleanupActive = () => {
         store.clear();
         if (sweepTimer)
             clearInterval(sweepTimer);
@@ -457,25 +499,8 @@ export async function runSecretsAgent(opts = {}) {
             fs.unlinkSync(sock);
         }
         catch { /* gone */ }
-        try {
-            if (parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10) === process.pid)
-                fs.unlinkSync(pidFile);
-        }
-        catch { /* gone */ }
-        process.exit(code);
+        releasePid();
     };
-    process.on('SIGTERM', () => shutdown(0));
-    process.on('SIGINT', () => shutdown(0));
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(sock, () => {
-            try {
-                fs.chmodSync(sock, 0o600);
-            }
-            catch { /* dir 0700 already gates it */ }
-            resolve();
-        });
-    });
     sweepTimer = setInterval(sweep, SWEEP_INTERVAL_MS);
     // Auto-lock on sleep. The signed helper emits LOCK / SLEEP lines; we wipe
     // everything on SLEEP (and, implicitly, logout — that tears down the launchd
@@ -499,6 +524,15 @@ export async function runSecretsAgent(opts = {}) {
     catch {
         watcher = null;
     }
+    return {
+        close() {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            detachSignals();
+            cleanupActive?.();
+        },
+    };
 }
 /**
  * Host the secrets broker inside the always-on daemon (#416).
@@ -512,11 +546,11 @@ export async function runSecretsAgent(opts = {}) {
  *     (those would kill the daemon — the daemon is the always-on backbone and
  *     manages its own version/lifecycle). The sweep only TTL-evicts.
  *
- * The caller (`runDaemon`) must only invoke this when NO broker is already
- * reachable (ping first) — this function clears a stale socket before binding,
- * so calling it while a live standalone broker holds the socket would orphan
- * that broker's clients. Returns a handle the daemon closes on shutdown, or
- * null off-darwin (nothing to broker without biometry).
+ * The caller (`runDaemon`) normally invokes this only when no broker answers
+ * its initial ping. Binding still arbitrates ownership through the same shared
+ * path as the standalone service: a live owner wins, while only an unreachable
+ * stale socket is reclaimed. Returns a handle the daemon closes on shutdown,
+ * or null off-darwin (nothing to broker without biometry).
  */
 export async function startHostedBroker() {
     if (!onDarwin())
@@ -547,41 +581,9 @@ export async function startHostedBroker() {
         });
         conn.on('error', () => { });
     };
-    // Bind race-safely: never clobber a LIVE standalone broker. Try to listen; if
-    // the socket is already bound, a broker raced us after runDaemon's ping — if
-    // it answers, back off and let it serve (return null); if it's a stale socket
-    // file with no live listener, reclaim it and retry once. (Unconditionally
-    // unlinking before bind — as an earlier draft did — could remove a live
-    // broker's socket in the sub-ms window after runDaemon's reachability check.)
-    const listenOnce = () => new Promise((resolve, reject) => {
-        const s = net.createServer(onConn);
-        s.once('error', (err) => {
-            if (err.code === 'EADDRINUSE')
-                resolve('inuse');
-            else
-                reject(err);
-        });
-        s.listen(sock, () => {
-            try {
-                fs.chmodSync(sock, 0o600);
-            }
-            catch { /* dir 0700 already gates it */ }
-            resolve(s);
-        });
-    });
-    let bound = await listenOnce();
-    if (bound === 'inuse') {
-        if ((await agentPing()).reachable)
-            return null; // a live broker holds it — don't clobber
-        try {
-            fs.unlinkSync(sock);
-        }
-        catch { /* gone */ }
-        bound = await listenOnce();
-        if (bound === 'inuse')
-            return null; // still contended — the standalone fallback covers it
-    }
-    const server = bound;
+    const server = await bindBrokerSocket(sock, onConn);
+    if (!server)
+        return null;
     // TTL eviction ONLY. Unlike the standalone broker's sweep, there is no
     // self-heal-exit or idle-exit here — the daemon is always-on and owns the
     // upgrade/lifecycle path; a broker that called process.exit() would take the
@@ -905,11 +907,12 @@ export async function agentPing() {
  * Ensure a broker is running and reachable. Returns true once the socket answers
  * a ping. macOS only.
  *
- * Prefers the persistent launchd service: if it isn't installed we install it
- * (which makes the broker survive for the whole login session, so subsequent
- * reads never cold-start); if it's installed but unreachable we kickstart it.
- * Only when the service path can't be used do we fall back to a one-off detached
- * broker — that's the model that gets starved under heavy load, so it's last.
+ * Prefers the always-on daemon, which hosts the broker socket (#416): retire any
+ * legacy standalone launchd service so the daemon owns the socket, then bring the
+ * daemon up (Path 0) — one supervised backbone that survives the whole login
+ * session, so subsequent reads never cold-start. Only when the daemon can't be
+ * used do we fall back to a one-off detached broker (Path 1) — the model that
+ * gets starved under heavy load, so it's last.
  */
 export async function ensureAgentRunning(timeoutMs = 5000) {
     if (!onDarwin())
@@ -928,11 +931,15 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             return true;
         await teardownStaleBroker();
     }
-    // Path 0 (#416): prefer the always-on daemon — it hosts the broker socket
-    // (one supervised backbone rather than a separate launchd service). If
-    // bringing the daemon up makes the broker answer, we're done. Fall through to
-    // the standalone-service paths below when the daemon path isn't available
-    // (kept as a fallback until the standalone service is retired, #416 step 2).
+    // A legacy standalone secrets-agent service may still be installed from an
+    // older version. Retire it (#416 step 2) so the always-on daemon owns the
+    // broker socket rather than racing a launchd job for it. No-op when no legacy
+    // plist is present. We only reach here when nothing is already reachable, so
+    // retiring never disrupts a warm broker.
+    retireLegacySecretsAgentService();
+    // Path 0 (#416): the always-on daemon hosts the broker socket — one supervised
+    // backbone rather than a separate launchd service. If bringing the daemon up
+    // makes the broker answer, we're done.
     try {
         const { ensureDaemonStarted } = await import('../daemon.js');
         if (ensureDaemonStarted()) {
@@ -944,30 +951,9 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             }
         }
     }
-    catch { /* daemon path unavailable — fall through to the standalone service */ }
-    // Path 1: the persistent service. installSecretsAgentService is idempotent and
-    // waits for the socket; for an already-installed service we kickstart and wait.
-    try {
-        if (!secretsAgentServiceInstalled()) {
-            if (await installSecretsAgentService(Math.max(timeoutMs, 20000)))
-                return true;
-        }
-        else {
-            const uid = process.getuid?.() ?? 0;
-            try {
-                execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-            }
-            catch { /* may already be running */ }
-            const d = Date.now() + timeoutMs;
-            while (Date.now() < d) {
-                if ((await agentPing()).reachable)
-                    return true;
-                await new Promise((r) => setTimeout(r, 150));
-            }
-        }
-    }
-    catch { /* fall through to the one-off spawn */ }
-    // Path 2 (fallback): one-off detached broker. Clear a stale socket/pid first.
+    catch { /* daemon path unavailable — fall through to the one-off spawn */ }
+    // Path 1 (fallback): one-off detached broker when the daemon can't host it.
+    // Clear a stale socket/pid first.
     const stalePid = (() => {
         try {
             return parseInt(fs.readFileSync(pidPath(), 'utf-8').trim(), 10);
@@ -1002,18 +988,12 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
 }
 /**
  * Tear down a stale broker (running pre-upgrade code) so a fresh one can take
- * over. If the persistent service is installed, bootout makes launchd relaunch
- * it on the new code; otherwise kill the process and clear its socket/pid.
+ * over. Retire any legacy standalone service first (#416 step 2) so the daemon —
+ * not the old launchd job — hosts the fresh broker, then kill the process and
+ * clear its socket/pid. The caller then brings the daemon-hosted broker up.
  */
 async function teardownStaleBroker() {
-    if (secretsAgentServiceInstalled()) {
-        const uid = process.getuid?.() ?? 0;
-        try {
-            execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-        }
-        catch { /* best effort */ }
-        return; // kickstart -k restarts the service onto current code; socket/pid managed by it
-    }
+    retireLegacySecretsAgentService();
     const pid = (() => { try {
         return parseInt(fs.readFileSync(pidPath(), 'utf-8').trim(), 10);
     }

package/dist/lib/secrets/remote.js

@@ -91,6 +91,7 @@ export function remoteSecretsRaw(target, args, opts = {}) {
         timeoutMs: REMOTE_TIMEOUT_MS,
         input: opts.input,
         extraSshArgs: opts.tty ? ['-tt'] : undefined,
+        multiplex: opts.tty ? false : undefined,
     });
 }
 /**

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

@@ -1,6 +1,7 @@
 import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
 import { type SessionActivity, type AwaitingReason, type StructuredQuestion, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
+import type { SessionAttachment } from './types.js';
 import { type SessionProvenance } from './provenance.js';
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
@@ -59,6 +60,8 @@ export interface ActiveSession {
     createdTickets?: string[];
     /** Team name the session SPAWNED via `agents teams create/add`. */
     spawnedTeam?: string;
+    /** Files/screenshots attached to the session prompt. */
+    attachments?: SessionAttachment[];
     sessionFile?: string;
     startedAtMs?: number;
     status: ActiveStatus;

package/dist/lib/session/active.js

@@ -275,6 +275,7 @@ function applyState(base, state, fallbackFile) {
         ticket: state.ticket,
         createdTickets: state.createdTickets,
         spawnedTeam: state.spawnedTeam,
+        attachments: state.attachments,
         rateLimited: state.rateLimited,
     };
 }

package/dist/lib/session/parse.js

@@ -55,6 +55,8 @@ function sanitizeEvent(e) {
         e.command = sanitizeForTerminal(e.command);
     if (e.path)
         e.path = sanitizeForTerminal(e.path);
+    if (e.name)
+        e.name = sanitizeForTerminal(e.name);
     if (e.output)
         e.output = sanitizeForTerminal(e.output);
     if (e.tool)
@@ -66,6 +68,36 @@ function sanitizeEvent(e) {
     if (e.args)
         e.args = sanitizeArgsDeep(e.args);
 }
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function attachmentPath(block, source) {
+    return firstString(source?.path, source?.file_path, source?.filePath, source?.url, source?.ref, block?.path, block?.file_path, block?.filePath, block?.ref);
+}
+function attachmentName(block, source, filePath) {
+    return firstString(block?.name, block?.title, source?.name, source?.filename, source?.file_name, source?.fileName, filePath ? path.basename(filePath) : undefined);
+}
+function normalizedAttachmentEvent(agent, timestamp, block, source, defaultMediaType, sizeBytes) {
+    const filePath = attachmentPath(block, source);
+    const name = attachmentName(block, source, filePath);
+    const explicitSize = typeof source?.sizeBytes === 'number' ? source.sizeBytes :
+        typeof source?.size === 'number' ? source.size :
+            typeof block?.sizeBytes === 'number' ? block.sizeBytes :
+                undefined;
+    return {
+        type: 'attachment',
+        agent,
+        timestamp,
+        path: filePath,
+        name,
+        mediaType: firstString(source?.media_type, source?.mediaType, block?.media_type, block?.mediaType) || defaultMediaType,
+        sizeBytes: sizeBytes || explicitSize || 0,
+    };
+}
 /**
  * Read a session file, refusing files above maxBytes. Bounded read protects
  * against multi-GB session blobs that would OOM the CLI or exceed V8's
@@ -351,24 +383,15 @@ export function parseClaudeContent(content) {
                         const source = block.source || {};
                         if (source.type === 'base64') {
                             const sizeBytes = Math.ceil((source.data?.length || 0) * 0.75);
-                            events.push({
-                                type: 'attachment',
-                                agent: 'claude',
-                                timestamp,
-                                mediaType: source.media_type || 'image/png',
-                                sizeBytes,
-                            });
+                            events.push(normalizedAttachmentEvent('claude', timestamp, block, source, 'image/png', sizeBytes));
+                        }
+                        else {
+                            events.push(normalizedAttachmentEvent('claude', timestamp, block, source, 'image/png', 0));
                         }
                     }
                     else if (block.type === 'document') {
                         const source = block.source || {};
-                        events.push({
-                            type: 'attachment',
-                            agent: 'claude',
-                            timestamp,
-                            mediaType: source.media_type || 'application/pdf',
-                            sizeBytes: 0,
-                        });
+                        events.push(normalizedAttachmentEvent('claude', timestamp, block, source, 'application/pdf', 0));
                     }
                     else if (block.type === 'tool_result') {
                         const toolId = block.tool_use_id;
@@ -1554,7 +1577,7 @@ export function parseDroid(filePath) {
             else if (block.type === 'image') {
                 const source = block.source || {};
                 const sizeBytes = source.type === 'base64' ? Math.ceil((source.data?.length || 0) * 0.75) : 0;
-                events.push({ type: 'attachment', agent: 'droid', timestamp, mediaType: source.media_type || 'image/png', sizeBytes });
+                events.push(normalizedAttachmentEvent('droid', timestamp, block, source, 'image/png', sizeBytes));
             }
         }
     }