@agentdeck/bridge 1.1.0 → 1.2.1

package/dist/claude-usage-recovery.js

@@ -0,0 +1,200 @@
+import { execFile } from 'child_process';
+import { createHash } from 'crypto';
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { delimiter, join, resolve } from 'path';
+import { logTagged } from './logger.js';
+const RECOVERY_TIMEOUT_MS = 25_000;
+const RETRY_MS = 30 * 60_000;
+const LONG_RETRY_MS = 6 * 60 * 60_000;
+/** The daemon's data directory — `AGENTDECK_DATA_DIR` when set, else
+ *  `~/.agentdeck`. Every other file in that directory resolves it this way; the
+ *  cooldown record did not, so two daemons pointed at different data dirs
+ *  silently shared one retry budget and each spent the other's quota. Kept
+ *  identical to `usage-api.ts`'s AGENTDECK_DIR — they are the same directory,
+ *  and item 5 of #286 is explicit that both move together or neither does. */
+const AGENTDECK_DIR = process.env.AGENTDECK_DATA_DIR || join(homedir(), '.agentdeck');
+export const CLAUDE_USAGE_RECOVERY_FILE = join(AGENTDECK_DIR, 'claude-usage-recovery.json');
+/** Claude owns the rotating refresh token and its interprocess lock. Never copy,
+ * rotate, or write those credentials ourselves. This bounded turn may consume a
+ * small amount of subscription quota; it carries no workspace or user content.
+ * --bare is NOT appropriate: that mode explicitly disables OAuth/keychain reads.
+ * An older CLI rejecting --safe-mode fails closed rather than loading hooks.
+ */
+export const CLAUDE_USAGE_RECOVERY_ARGS = [
+    '--safe-mode', '--print', '--tools', '', '--strict-mcp-config',
+    '--mcp-config', '{"mcpServers":{}}', '--settings', '{"disableAllHooks":true}',
+    '--no-session-persistence', '--disable-slash-commands', '--no-chrome',
+    '--model', 'haiku', '--max-turns', '1', '--max-budget-usd', '0.01',
+    '--system-prompt', 'Reply with OK.', '--output-format', 'json', 'Reply with OK.',
+];
+/** Keep the recovery CLI on the same credential store as usage-api.ts.
+ * On macOS that reader targets the default Keychain service; a custom config
+ * directory can select a DIFFERENT Keychain namespace in Claude. Fail closed
+ * rather than spend quota or renew an unrelated account. On other platforms,
+ * resolve relative paths before the child changes cwd to the temporary folder.
+ */
+export function buildClaudeUsageRecoveryEnv(source = process.env, platform = process.platform, home = homedir()) {
+    const env = { ...source, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' };
+    if (env.CLAUDE_CONFIG_DIR) {
+        const configDir = resolve(env.CLAUDE_CONFIG_DIR);
+        if (platform === 'darwin' && configDir !== join(home, '.claude'))
+            return null;
+        env.CLAUDE_CONFIG_DIR = configDir;
+    }
+    // A daemon started from an agent must not be mistaken for its nested session.
+    // API-key / provider overrides must not redirect an OAuth recovery request.
+    for (const key of Object.keys(env)) {
+        if (key === 'CLAUDECODE' || key === 'ANTHROPIC_API_KEY' || key === 'ANTHROPIC_AUTH_TOKEN'
+            || key === 'ANTHROPIC_BASE_URL' || key === 'CLAUDE_CODE_OAUTH_TOKEN'
+            || key.startsWith('CLAUDE_CODE_USE_') || key.startsWith('AGENTDECK_'))
+            delete env[key];
+    }
+    return env;
+}
+/** `execFile` runs one executable — it does not search PATHEXT and (since the
+ * Node 20.12/18.20 spawn hardening) will not run a `.cmd`/`.bat` shim without a
+ * shell. A bare `'claude'` was therefore ENOENT on every Windows install, and a
+ * LaunchAgent carries the installing shell's PATH, which may not contain the
+ * CLI at all — both surfaced only as a recurring generic failure line. Resolve
+ * the real file once so the unavailable case can SAY it is unavailable.
+ * Returns `{ shim: true }` for a Windows shell shim: shell-quoting a JSON
+ * argument through cmd.exe is a worse failure than declining, so recovery is
+ * skipped there and says so. */
+export function resolveClaudeCli(env = process.env, platform = process.platform) {
+    const isFile = (candidate) => {
+        try {
+            return statSync(candidate).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    const override = env.AGENTDECK_CLAUDE_CLI;
+    if (override)
+        return isFile(override) ? { path: override, shim: false } : null;
+    const exts = platform === 'win32'
+        ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+        : [''];
+    for (const dir of (env.PATH || '').split(delimiter).filter(Boolean)) {
+        for (const ext of exts) {
+            const candidate = join(dir, `claude${ext}`);
+            if (isFile(candidate))
+                return { path: candidate, shim: /\.(cmd|bat)$/i.test(ext) };
+        }
+    }
+    return null;
+}
+let reportedUnavailable = false;
+function reportUnavailableOnce(reason) {
+    if (reportedUnavailable)
+        return;
+    reportedUnavailable = true;
+    logTagged('usage', `Claude authorization recovery unavailable: ${reason}`);
+}
+export function runClaudeUsageRecovery() {
+    const env = buildClaudeUsageRecoveryEnv();
+    if (!env) {
+        logTagged('usage', 'Claude authorization recovery skipped: custom macOS credential namespace cannot be matched');
+        return Promise.resolve();
+    }
+    const cli = resolveClaudeCli(env);
+    if (!cli) {
+        reportUnavailableOnce('the claude CLI was not found on this daemon\'s PATH (set AGENTDECK_CLAUDE_CLI to its full path)');
+        return Promise.resolve();
+    }
+    if (cli.shim) {
+        reportUnavailableOnce(`only a shell shim is installed (${cli.path}); point AGENTDECK_CLAUDE_CLI at an executable`);
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const child = execFile(cli.path, CLAUDE_USAGE_RECOVERY_ARGS, {
+            cwd: tmpdir(), env, timeout: RECOVERY_TIMEOUT_MS, killSignal: 'SIGKILL',
+            maxBuffer: 64 * 1024, windowsHide: true,
+        }, (error) => {
+            if (error)
+                logTagged('usage', `Claude authorization recovery CLI ended (${error.killed ? 'timeout' : error.code ?? 'failed'})`);
+            resolve(); // Outcome is verified by re-reading credentials, never stdout.
+        });
+        child.stdin?.end();
+        // The child holds no port and gates no shutdown, but a clean stop that
+        // SIGKILLs the daemon takes `execFile`'s timeout with it — the orphan then
+        // runs unbounded. Track it so shutdown can end it, and unref it so it can
+        // never be the reason this process stays alive.
+        child.unref();
+        liveRecoveryChildren.add(child);
+        // `close`, not `exit`: a spawn that fails outright (the resolved binary
+        // vanished between the probe and the spawn) emits `error` + `close` and
+        // never `exit`, so an `exit` listener retains a dead ChildProcess for the
+        // life of the daemon — one per attempt, against a comment that says "at
+        // most one". `close` fires on both paths.
+        child.once('close', () => liveRecoveryChildren.delete(child));
+    });
+}
+/** Recovery children currently running. At most one — the class serializes on
+ *  `pending` — but a Set costs nothing and cannot go negative. */
+const liveRecoveryChildren = new Set();
+/** Kill any in-flight recovery child. Called from the daemon's shutdown path;
+ *  safe to call with none running. */
+export function stopClaudeUsageRecoveryChildren() {
+    for (const child of liveRecoveryChildren) {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch { /* already gone */ }
+    }
+    liveRecoveryChildren.clear();
+}
+/** Single daemon owner; persisted cooldown also survives daemon restart. */
+export class ClaudeUsageRecovery {
+    deps;
+    pending = null;
+    record = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async recover(accessToken) {
+        if (this.pending)
+            return this.pending;
+        const credentialHash = createHash('sha256').update(accessToken).digest('hex');
+        const previous = this.record ?? this.deps.read();
+        if (previous && this.deps.now() < previous.nextAttemptAt)
+            return;
+        const attempts = previous?.credentialHash === credentialHash ? previous.attempts + 1 : 1;
+        this.record = { credentialHash, attempts,
+            nextAttemptAt: this.deps.now() + (attempts >= 3 ? LONG_RETRY_MS : RETRY_MS) };
+        // Record BEFORE spawning: a crash/restart must not cause a recovery loop.
+        try {
+            this.deps.write(this.record);
+        }
+        catch {
+            return;
+        }
+        logTagged('usage', `Claude usage authorization expired — requesting bounded CLI recovery (attempt ${attempts})`);
+        this.pending = this.deps.run().catch(() => { }).finally(() => { this.pending = null; });
+        return this.pending;
+    }
+}
+export const claudeUsageRecovery = new ClaudeUsageRecovery({
+    now: Date.now,
+    read: () => {
+        try {
+            const r = JSON.parse(readFileSync(CLAUDE_USAGE_RECOVERY_FILE, 'utf8'));
+            return typeof r.credentialHash === 'string' && Number.isFinite(r.attempts)
+                && Number.isFinite(r.nextAttemptAt) ? r : null;
+        }
+        catch {
+            return null;
+        }
+    },
+    write: (record) => {
+        mkdirSync(AGENTDECK_DIR, { recursive: true });
+        // tmp+rename like every other file in this directory: a torn write reads
+        // back as "no cooldown", which is the one failure that spends quota.
+        const tmp = `${CLAUDE_USAGE_RECOVERY_FILE}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+        renameSync(tmp, CLAUDE_USAGE_RECOVERY_FILE);
+    },
+    run: runClaudeUsageRecovery,
+});
+//# sourceMappingURL=claude-usage-recovery.js.map

package/dist/claude-usage-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-usage-recovery.js","sourceRoot":"","sources":["../src/claude-usage-recovery.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+export type LegacySessionCommand = 'claude' | 'codex' | 'opencode' | 'monitor';
+/**
+ * User-visible compatibility notice for the legacy per-session bridge. Keep
+ * this pure so CLI tests can pin the public migration contract without starting
+ * a PTY or importing its native dependencies.
+ */
+export declare function managedPtyCompatibilityNotice(command: LegacySessionCommand): string[];
 export declare function daemonPostureArgs(opts: {
     local?: boolean;
     loopback?: boolean;
@@ -22,6 +29,10 @@ export interface CliOtaIdentity {
     board: string;
     updateChannel: string;
 }
+export declare function inlineOtaPayload(target: string, firmwareB64: string, opts?: {
+    stage?: boolean;
+    identity?: CliOtaIdentity;
+}): Record<string, unknown>;
 /** Resolve one exact OTA namespace from an integration manifest. Ambiguity is
  * an error: a release command must never guess which product or channel owns
  * an image. */

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AA6M1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CAQ/G;AAED,wBAAgB,UAAU,CAAC,SAAS,GAAE,MAAM,EAAO,GAAG,MAAM,CAmC3D;AAgGD,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAM,CAAC;AAOtF;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;eAEe;AACf,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,cAAc,CAmBhB;AA+BD,gFAAgF;AAChF,QAAA,MAAM,cAAc,EAAE,MAAM,CAAC,aAAa,GAAG,WAAW,GAAG,UAAU,EAAE,MAAM,CAI5E,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAsBjE;AAKD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAyBV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,OAAO,cAAc,EACtC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,OAAO,cAAc,EACtC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,OAAO,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER;AAID,QAAA,MAAM,OAAO,SAAgB,CAAC;AAyuB9B;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,EAC/D,cAAc,EAAE,MAAM;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EACjE,cAAc,EAAE,MAAM,MAAM,GAAG,IAAI,EACnC,SAAS,SAAS;AAClB;;;;;;;;;;;;;;;GAeG;AACH,YAAY,CAAC,EAAE,MAAM,OAAO,EAC5B,SAAS,SAAU,EACnB,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GACrC,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA4B/C;AA44ED,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -28,6 +28,25 @@ function warnIfDaemonHostIgnored(opts) {
         console.error('[agentdeck] --daemon-host / AGENTDECK_DAEMON_HOST is set but ignored: remote attach requires --remote-daemon (or AGENTDECK_REMOTE_DAEMON=1). Session stays local-only.');
     }
 }
+/**
+ * User-visible compatibility notice for the legacy per-session bridge. Keep
+ * this pure so CLI tests can pin the public migration contract without starting
+ * a PTY or importing its native dependencies.
+ */
+export function managedPtyCompatibilityNotice(command) {
+    const directLaunch = command === 'monitor'
+        ? 'run `claude`, `codex`, or `opencode` normally'
+        : `run \`${command}\` directly`;
+    return [
+        `[agentdeck] LEGACY COMPATIBILITY MODE: \`agentdeck ${command}\` uses the managed per-session bridge; daemon-first launch is the recommended default.`,
+        `[agentdeck] For ordinary local sessions, run \`agentdeck daemon install\`, then ${directLaunch}.`,
+        '[agentdeck] --remote-daemon, --weight, AGENTDECK_<AGENT>_ARGS, and terminal-only controls do not yet have daemon-first equivalents. No removal date is set. Design: https://github.com/puritysb/AgentDeck/discussions/278 Tracking: https://github.com/puritysb/AgentDeck/issues/273',
+    ];
+}
+function warnManagedPtyCompatibility(command) {
+    for (const line of managedPtyCompatibilityNotice(command))
+        console.error(line);
+}
 function log(msg) {
     process.stderr.write(msg + '\n');
 }
@@ -323,6 +342,14 @@ for (const b of ESP32_OTA_BOARDS) {
 export function resolveEsp32OtaDaemonTarget(target) {
     return ESP32_OTA_BY_TARGET[target]?.board ?? target;
 }
+export function inlineOtaPayload(target, firmwareB64, opts = {}) {
+    return {
+        target,
+        firmwareB64,
+        ...(opts.stage ? { stage: true } : {}),
+        ...(opts.identity ?? {}),
+    };
+}
 /** Resolve one exact OTA namespace from an integration manifest. Ambiguity is
  * an error: a release command must never guess which product or channel owns
  * an image. */
@@ -552,7 +579,7 @@ weatherCommand
 // ===== Agent session commands =====
 program
     .command('claude')
-    .description('Start Claude Code session (PTY + bridge)')
+    .description('[legacy compatibility] Start Claude Code in the managed PTY session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-c, --command <cmd>', 'Command to spawn', 'claude')
     .option('-d, --debug', 'Enable debug logging')
@@ -568,6 +595,7 @@ program
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnManagedPtyCompatibility('claude');
     warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     await startSession({
@@ -596,7 +624,7 @@ program
 });
 program
     .command('codex')
-    .description('Start Codex CLI session (PTY + bridge)')
+    .description('[legacy compatibility] Start Codex in the managed PTY session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-c, --command <cmd>', 'Command to spawn', 'codex')
     .option('-d, --debug', 'Enable debug logging')
@@ -610,6 +638,7 @@ program
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnManagedPtyCompatibility('codex');
     warnIfDaemonHostIgnored(opts);
     // Install Codex lifecycle hooks before starting the session so the
     // first prompt's UserPromptSubmit / Stop events reach the daemon.
@@ -657,7 +686,7 @@ program
 });
 program
     .command('opencode')
-    .description('Start OpenCode session (PTY + SSE bridge)')
+    .description('[legacy compatibility] Start OpenCode in the managed PTY/SSE session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-c, --command <cmd>', 'Command to spawn', 'opencode')
     .option('-d, --debug', 'Enable debug logging')
@@ -671,6 +700,7 @@ program
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnManagedPtyCompatibility('opencode');
     warnIfDaemonHostIgnored(opts);
     // Install the OpenCode observer plugin so standalone `opencode` runs
     // (outside this managed session) also reach the daemon timeline. The
@@ -715,7 +745,7 @@ program
 });
 program
     .command('monitor')
-    .description('Start hook-only bridge (no PTY — run claude separately)')
+    .description('[legacy compatibility] Start the managed hook-only per-session bridge')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-d, --debug', 'Enable debug logging')
     .option('--local', 'Disable all device modules')
@@ -726,6 +756,7 @@ program
     .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS for this invocation')
     .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnManagedPtyCompatibility('monitor');
     warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     const port = parseInt(opts.port, 10);
@@ -1246,8 +1277,13 @@ daemon
     const targetPort = registryPort ?? port;
     try {
         const res = await fetch(`http://127.0.0.1:${targetPort}/health`);
-        const data = await res.json();
+        const data = (await res.json());
         log(`Daemon status (port ${targetPort}): ${JSON.stringify(data, null, 2)}`);
+        const apmeHealth = data.apme;
+        if (apmeHealth?.enabled === false) {
+            log(`WARNING: APME evaluation is disabled${typeof apmeHealth.error === 'string' ? ` — ${apmeHealth.error}` : '.'}`);
+            log('Run `agentdeck diag native` for the exact Node executable, ABI, and recovery command.');
+        }
         // A daemon on a fallback port keeps working — clients resolve it from
         // daemon.json — so nothing else ever says it happened. Without this line
         // the only symptom is that the canonical port is owned by nobody.
@@ -1343,6 +1379,12 @@ daemon
     .option('--loopback', 'Alias for --enterprise')
     .action(async (opts) => {
     const postureArgs = daemonPostureArgs(opts);
+    const { collectNativeDependencyDiagnostic, formatNativeDependencyDiagnosticReport, } = await import('./native-dependency-diagnostics.js');
+    const nativeReport = collectNativeDependencyDiagnostic();
+    if (!nativeReport.ok) {
+        log('WARNING: daemon autostart will be registered, but APME evaluation cannot start under this runtime.');
+        log(formatNativeDependencyDiagnosticReport(nativeReport));
+    }
     if (postureArgs.length > 0) {
         log(`Autostart posture: ${postureArgs.join(' ')} (baked into the autostart unit's arguments).`);
     }
@@ -1889,7 +1931,17 @@ program
         // Pull-OTA staging: for wake-sync-sleep boards (XTeink X3/X4) that never
         // hold a live WS. The daemon adverts the build on the board's feed pulls;
         // the board downloads + flashes itself on its next wake.
-        const { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath, stage: true, ...(otaIdentity ?? {}) }, 30_000);
+        let { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath, stage: true, ...(otaIdentity ?? {}) }, 30_000);
+        if (body.ok === false && String(body.error ?? '').startsWith('firmware_unreadable')) {
+            // The App Store daemon cannot reopen an arbitrary CLI path. Preserve
+            // the stage bit and exact product namespace when retrying inline — the
+            // live-OTA retry below is a different operation and must not consume a
+            // pull-stage request by accident.
+            log('Daemon cannot read the firmware path (sandbox) — resending stage inline...');
+            const { readFileSync } = await import('fs');
+            const firmwareB64 = readFileSync(firmwarePath).toString('base64');
+            ({ statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, inlineOtaPayload(daemonTarget, firmwareB64, { stage: true, identity: otaIdentity }), 30_000));
+        }
         if (statusCode < 200 || statusCode >= 300 || body.ok === false) {
             throw new Error(String(body.error ?? `HTTP ${statusCode}`));
         }
@@ -1919,7 +1971,7 @@ program
         log('Daemon cannot read the firmware path (sandbox) — resending inline...');
         const { readFileSync } = await import('fs');
         const firmwareB64 = readFileSync(firmwarePath).toString('base64');
-        ({ statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwareB64 }, 15 * 60_000));
+        ({ statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, inlineOtaPayload(daemonTarget, firmwareB64), 15 * 60_000));
     }
     if (statusCode < 200 || statusCode >= 300 || body.ok === false) {
         throw new Error(String(body.error ?? `HTTP ${statusCode}`));
@@ -2337,15 +2389,15 @@ program
 });
 program
     .command('diag [target]')
-    .description('Generate a diagnostic dump, or a privacy-safe agent diagnostic')
+    .description('Generate a diagnostic dump, or a focused agent/native-runtime diagnostic')
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-a, --analyze', 'Run AI analysis on the dump')
     .option('-t, --tail <lines>', 'Number of journal entries', '200')
     .option('--json', 'Print target diagnostics as machine-readable JSON')
     .action(async (target, opts) => {
     if (target) {
-        if (target !== 'kiro') {
-            log(`Unknown diagnostic target: ${target}. Supported target: kiro`);
+        if (target !== 'kiro' && target !== 'agents' && target !== 'native') {
+            log(`Unknown diagnostic target: ${target}. Supported targets: agents, kiro, native`);
             process.exitCode = 1;
             return;
         }
@@ -2354,6 +2406,20 @@ program
             process.exitCode = 1;
             return;
         }
+        if (target === 'agents') {
+            const { collectAgentCliDiagnosticReport, formatAgentCliDiagnosticReport } = await import('./agent-cli-diagnostics.js');
+            const report = collectAgentCliDiagnosticReport();
+            process.stdout.write(`${opts.json ? JSON.stringify(report, null, 2) : formatAgentCliDiagnosticReport(report)}\n`);
+            return;
+        }
+        if (target === 'native') {
+            const { collectNativeDependencyDiagnostic, formatNativeDependencyDiagnosticReport, } = await import('./native-dependency-diagnostics.js');
+            const report = collectNativeDependencyDiagnostic();
+            process.stdout.write(`${opts.json ? JSON.stringify(report, null, 2) : formatNativeDependencyDiagnosticReport(report)}\n`);
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
         const { collectKiroDiagnosticReport, formatKiroDiagnosticReport } = await import('./kiro-diagnostics.js');
         const report = await collectKiroDiagnosticReport();
         process.stdout.write(`${opts.json ? JSON.stringify(report, null, 2) : formatKiroDiagnosticReport(report)}\n`);
@@ -3346,22 +3412,23 @@ apme
         return;
     }
     log(`\n  Turns started in the last ${opts.since} — how each one's end was learned`);
-    log(`  ${'Agent'.padEnd(14)} ${'Turns'.padEnd(7)} ${'Stop'.padEnd(7)} ${'Synth'.padEnd(7)} ${'NoStop'.padEnd(7)} ${'Esc'.padEnd(6)} ${'Abort'.padEnd(6)} ${'Folded'.padEnd(7)} ${'SessEnd'.padEnd(8)} ${'Open'.padEnd(6)} ${'?'.padEnd(6)} Stop loss`);
-    log(`  ${'─'.repeat(14)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(6)} ${'─'.repeat(6)} ${'─'.repeat(7)} ${'─'.repeat(8)} ${'─'.repeat(6)} ${'─'.repeat(6)} ${'─'.repeat(9)}`);
+    log(`  ${'Agent'.padEnd(14)} ${'Turns'.padEnd(7)} ${'Stop'.padEnd(7)} ${'Synth'.padEnd(7)} ${'NoStop'.padEnd(7)} ${'Esc'.padEnd(6)} ${'Abort'.padEnd(6)} ${'Folded'.padEnd(7)} ${'SessEnd'.padEnd(8)} ${'Reaped'.padEnd(7)} ${'Open'.padEnd(6)} ${'?'.padEnd(6)} Stop loss`);
+    log(`  ${'─'.repeat(14)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(7)} ${'─'.repeat(6)} ${'─'.repeat(6)} ${'─'.repeat(7)} ${'─'.repeat(8)} ${'─'.repeat(7)} ${'─'.repeat(6)} ${'─'.repeat(6)} ${'─'.repeat(9)}`);
     for (const r of rows) {
         // Which buckets the ratio may read is defined once, in shared — see
         // `stopDeliveryLoss`. Restating it here is how the instrument would come
         // to measure something other than what its legend claims.
         const { adjudicated, ratio } = stopDeliveryLoss(r);
         const rate = ratio != null ? `${(ratio * 100).toFixed(0)}% of ${adjudicated}` : '—';
-        log(`  ${r.agentType.slice(0, 14).padEnd(14)} ${String(r.total).padEnd(7)} ${String(r.stop).padEnd(7)} ${String(r.syntheticStop).padEnd(7)} ${String(r.nextPrompt).padEnd(7)} ${String(r.interrupted).padEnd(6)} ${String(r.aborted).padEnd(6)} ${String(r.superseded).padEnd(7)} ${String(r.sessionEnd).padEnd(8)} ${String(r.open).padEnd(6)} ${String(r.preInstrument).padEnd(6)} ${rate}`);
+        log(`  ${r.agentType.slice(0, 14).padEnd(14)} ${String(r.total).padEnd(7)} ${String(r.stop).padEnd(7)} ${String(r.syntheticStop).padEnd(7)} ${String(r.nextPrompt).padEnd(7)} ${String(r.interrupted).padEnd(6)} ${String(r.aborted).padEnd(6)} ${String(r.superseded).padEnd(7)} ${String(r.sessionEnd).padEnd(8)} ${String(r.runClose).padEnd(7)} ${String(r.open).padEnd(6)} ${String(r.preInstrument).padEnd(6)} ${rate}`);
     }
     log('');
-    log('  Synth  = Stop hook dropped, watchdog recovered it from the transcript');
+    log("  Synth  = Stop hook dropped, recovered from the agent's own record (transcript watchdog; rollout at the next prompt for Codex)");
     log('  NoStop = Stop hook dropped and nothing recovered it (closed by the next prompt)');
     log('  Esc    = user cancelled the turn — Claude Code owes no Stop, so not a loss');
     log('  Abort  = usage limit / auth / API error ended the turn — no Stop is fired for those');
     log('  Folded = a second prompt arrived before this one ran; one turn served both');
+    log('  Reaped = the run was reaped under the open turn — the daemon that would have taken its Stop was gone (a restart)');
     log('  ?      = closed before end_source existed — signal unknown, never guessed');
     log('');
 });