@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/exec.js

@@ -17,6 +17,7 @@ import { isTierToken, resolveTier } from './model-tiers.js';
 import { createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
+import { expandLocalHome } from './project-root.js';
 import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
@@ -31,6 +32,7 @@ import { isTmuxInstalled } from './tmux/binary.js';
 import { shellQuote } from './ssh-exec.js';
 import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
+import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
@@ -287,43 +289,15 @@ export function buildExecEnv(options) {
         const version = options.version
             ? resolvedVersion
             : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            const versionHome = getVersionHomePath('claude', version);
+        // The per-account `claude setup-token` only resolves when there is a version
+        // home to key it to; version===null (claude unresolved / not installed) yields
+        // null, exactly as the routines path treats it (`runner.ts:1017-1021`). The
+        // token decision below runs even then, so an ambient inherited value is stripped
+        // on the routines/provisioned path regardless of whether a version resolved.
+        const versionHome = version ? getVersionHomePath('claude', version) : null;
+        const setupToken = versionHome ? resolveClaudeSetupToken(versionHome) : null;
+        if (versionHome) {
             result.CLAUDE_CONFIG_DIR = path.join(versionHome, '.claude');
-            const setupToken = resolveClaudeSetupToken(versionHome);
-            if (setupToken) {
-                // The `auth` bundle's setup-token exists so a run with NO human present
-                // authenticates without the Touch-ID-gated login item — usage probes,
-                // routines, dispatched runs (claude-account-token.ts). An interactive run
-                // has a human at the TTY, and their own per-version login is the credential
-                // they established and expect; overriding it made `/status` report
-                // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
-                // hand-driven session off that login. macOS cannot cheaply confirm a home's
-                // login first (probing the Keychain raises an authorization sheet per
-                // installed version on the `agents run` hot path — agents.ts
-                // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
-                // Code, which prompts a present human to log in if the login is missing.
-                if (resolveInteractive(options)) {
-                    // Drop an INHERITED copy of the same token too: an interactive launch from
-                    // inside a headless agent's shell inherits that agent's injected value via
-                    // sanitizeProcessEnv(process.env) and would keep authenticating as it.
-                    // Matched by VALUE, so a token the user exported deliberately is a
-                    // different string and is left alone. This is NARROWER than the routines
-                    // path, which overwrites-or-deletes unconditionally and never inspects the
-                    // inherited value (`runner.ts:1020-1021`) — the gap between the two is
-                    // what RUSH-2360 tracks, including a DIFFERENT account's inherited token,
-                    // which this equality check lets through.
-                    if (result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
-                        delete result.CLAUDE_CODE_OAUTH_TOKEN;
-                    }
-                }
-                else {
-                    // A token keyed to this version home's own account replaces any ambient
-                    // shared value inherited from the launcher. options.env still wins below
-                    // for explicit caller overrides.
-                    result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
-                }
-            }
             // A managed pin lives in a per-version dir; Claude Code's own background
             // auto-updater would rewrite that pinned binary in place (and has left it
             // half-swapped and broken). Disable it so a pin stays a pin. Honor an
@@ -333,6 +307,50 @@ export function buildExecEnv(options) {
                 result.DISABLE_AUTOUPDATER = '1';
             }
         }
+        // The `auth` bundle's setup-token exists so a run with NO human present
+        // authenticates without the Touch-ID-gated login item — usage probes,
+        // routines, dispatched runs (claude-account-token.ts). An interactive run
+        // has a human at the TTY, and their own per-version login is the credential
+        // they established and expect; overriding it made `/status` report
+        // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
+        // hand-driven session off that login. macOS cannot cheaply confirm a home's
+        // login first (probing the Keychain raises an authorization sheet per
+        // installed version on the `agents run` hot path — agents.ts
+        // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
+        // Code, which prompts a present human to log in if the login is missing.
+        if (resolveInteractive(options)) {
+            // Drop an INHERITED copy of OUR OWN setup-token: an interactive launch from
+            // inside a headless agent's shell inherits that agent's injected value via
+            // sanitizeProcessEnv(process.env) and would keep authenticating as it.
+            // Matched by VALUE, so a token the user exported deliberately is a different
+            // string and is left alone (#2383). This is NARROWER than the non-interactive
+            // path below, which overwrites-or-deletes unconditionally and never inspects
+            // the inherited value — a DIFFERENT account's inherited setup-token passing
+            // through this equality check is the adjacent hole RUSH-2360 leaves as
+            // follow-up (it does not silently run on a *shared, rotating* token, which is
+            // what caused the RUSH-1822 logout storm).
+            if (setupToken && result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
+                delete result.CLAUDE_CODE_OAUTH_TOKEN;
+            }
+        }
+        else {
+            // Non-interactive (routines, dispatched, provisioned box): mirror the routines
+            // path (`runner.ts:1017-1021`) UNCONDITIONALLY. Inject the per-account
+            // setup-token when one resolves — it replaces any ambient shared value
+            // inherited from the launcher. When NONE resolves, STRIP the ambient
+            // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
+            // authenticate as the shared, rotating token an earlier version of this path
+            // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.
+            // A missing login then fails loud (401) against this home's own credential
+            // instead of quietly borrowing another's. options.env still wins below for an
+            // explicit caller override.
+            if (setupToken) {
+                result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
+            }
+            else {
+                delete result.CLAUDE_CODE_OAUTH_TOKEN;
+            }
+        }
         delete result.CODEX_HOME;
         delete result.COPILOT_HOME;
         delete result.KIMI_CODE_HOME;
@@ -735,22 +753,22 @@ export const AGENT_COMMANDS = {
         // `resume` subcommand — special-cased in buildExecCommand.
         resume: { flag: '--session-id' },
     },
-    // Warp Agent CLI (`oz agent run`). Headless is `-p/--prompt "<task>"`; JSON is
-    // the global `--output-format json`. Autonomy comes from the selected agent
-    // profile (`--profile`), not a per-run permission flag, so the single `edit`
-    // mode maps to no flags (mirrors hermes). `--model` overrides the base model
-    // (`oz model list`). No `resume`: Oz's `oz agent run --conversation <id>`
-    // continues a SERVER-SIDE conversation by id, and warp is not session-tracked
-    // (absent from SESSION_AGENTS), so agents-cli has no local id to resume from —
-    // declaring it would make nativeResume(warp) true against an unreachable path.
+    // Warp Agent CLI (`warp`) — the interactive TUI. It has NO headless one-shot
+    // form: the documented flags are --api-key/--auto-approve/--resume <token>/
+    // --set-provider-api-key/--clear-provider-api-key/--version/--help — no
+    // -p/--prompt, no --model (model is the `/model` picker), no JSON output. So
+    // bare `warp` opens the TUI and the single `edit` mode maps to no flags
+    // (mirrors hermes); there are no jsonFlags/modelFlag to declare. No `resume`:
+    // `warp --resume <token>` reopens a SERVER-SIDE conversation by token, but
+    // warp is not session-tracked (absent from SESSION_AGENTS) so agents-cli has
+    // no local id to feed — declaring it would make nativeResume(warp) true
+    // against an unreachable path.
     warp: {
-        base: ['oz', 'agent', 'run'],
-        promptFlag: '-p',
+        base: ['warp'],
+        promptFlag: 'positional',
         modeFlags: {
             edit: [],
         },
-        jsonFlags: ['--output-format', 'json'],
-        modelFlag: '--model',
     },
 };
 /**
@@ -939,7 +957,10 @@ export function buildExecCommand(options) {
     }
     if (options.agent === 'codex') {
         const policyMode = resolvedMode === 'plan' || resolvedMode === 'skip' ? resolvedMode : 'edit';
-        const writableRoots = [...codexEditWritableRoots(options.cwd ?? process.cwd()), ...(options.addDirs ?? [])];
+        const writableRoots = [
+            ...codexEditWritableRoots(options.cwd ?? process.cwd()),
+            ...(options.addDirs ?? []).map(expandLocalHome),
+        ];
         cmd.push(...codexPolicyArgs(policyMode, writableRoots));
     }
     else if (resumeSpec && 'subcommand' in resumeSpec) {
@@ -1078,14 +1099,22 @@ export function buildExecCommand(options) {
             cmd.push(template.promptFlag, options.prompt);
         }
     }
-    // Codex add-dirs are folded into its named edit profile above, including on
-    // resume where the native CLI rejects --add-dir. Claude keeps its native flag.
-    const addDirs = [...new Set(options.addDirs ?? [])];
-    if (addDirs.length > 0 && options.agent === 'claude') {
-        for (const dir of addDirs) {
-            cmd.push('--add-dir', dir);
-        }
-    }
+    // Project / --add-dir grants. Codex folds them into the named edit profile
+    // above (workspace_roots); resume rejects the native --add-dir flag.
+    // Everything else is strategy-driven in applyAddDirs:
+    //   native-flag  — claude, kimi, cursor (`--add-dir`)
+    //   grok-sandbox — rules + project sandbox profile when sandboxed
+    //   none         — ignored (no multi-root surface)
+    //
+    // `~` is expanded in normalizeAddDirs (via expandLocalHome), because no shell
+    // does it for us: a forwarded grant crosses the SSH boundary single-quoted
+    // (`shellQuote` in ssh-exec.ts), so the remote login shell leaves `~/…`
+    // literal and the harness resolves it as a directory actually named `~`.
+    // Expanding on the side that runs the harness is what lets one home-relative
+    // grant re-root per machine.
+    applyAddDirs(options.agent, cmd, options.addDirs, {
+        cwd: options.cwd ?? process.cwd(),
+    });
     // Claude-specific: workflow capability scoping. WORKFLOW.md frontmatter
     // `tools:` / `mcpServers:` is translated to the headless flags that ACTUALLY
     // restrict the run (verified against `claude --help` on the installed CLI):
@@ -1251,6 +1280,32 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
 export function shouldRecapDeadPane(status, interactive) {
     return (status ?? 0) !== 0 || interactive;
 }
+/**
+ * The exit code a tmux-wrapped run resolves with (RUSH-2185 / EXEC-23b).
+ *
+ * Three inputs, one rule: report success ONLY for an outcome tmux actually told
+ * us about. A clean user detach (`knownAlive`) is 0; a dead pane reports the
+ * status tmux read off it; everything else — pane unreadable because the server
+ * or session went away, or dead with no status — is UNKNOWN and resolves to
+ * {@link UNKNOWN_OUTCOME_EXIT_CODE}, never 0.
+ *
+ * Why this is not `status ?? 0`: an interactive run whose tmux server died mid-
+ * work landed on exactly those unknown branches and returned 0, so `agents run`
+ * printed a failure banner while handing its caller a success code. The same
+ * "1 if unknown" rule already governs the `--host` follow path
+ * (`docs/specifications.md` §Agent execution, exit-code table).
+ *
+ * @param pane       What `paneExitStatus` read back for the agent pane.
+ * @param knownAlive Positive proof the pane is still alive (see
+ *                   {@link isPaneKnownAliveFromQueryResult}) — a clean detach.
+ */
+export function tmuxRunExitCode(pane, knownAlive) {
+    if (knownAlive)
+        return 0;
+    if (pane.dead && pane.status !== undefined)
+        return pane.status;
+    return UNKNOWN_OUTCOME_EXIT_CODE;
+}
 /**
  * True only when a `display-message #{pane_dead}` tmux query explicitly returned
  * "0" (pane alive). Used to distinguish "pane alive" from "query failed" in
@@ -1403,13 +1458,105 @@ async function runInTmux(options, executable, args) {
     const cwd = options.cwd || process.cwd();
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
+    const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
+    const NO_TMUX_TIP = `${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.${OFF}\n\n`;
+    // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
+    // detaches the client the instant the agent exits, so a fast failure (a
+    // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
+    // otherwise leave only a bare `[detached]` with no clue why. Must run BEFORE
+    // killSession — capture-pane needs the session still alive (remain-on-exit
+    // keeps the dead pane readable until we tear it down). Best-effort throughout.
+    const surfacePaneFailure = async (pane, status, headline) => {
+        if (!pane)
+            return;
+        let tail = '';
+        try {
+            const r = await runTmux({ socket, args: ['capture-pane', '-p', '-t', pane, '-S', '-200'], throwOnError: false });
+            if (r.code === 0)
+                tail = formatPaneTail(r.stdout);
+        }
+        catch { /* best-effort — a missing pane just means no recap */ }
+        process.stderr.write(`\n${RED}agents: ${headline} (exit ${status ?? UNKNOWN_OUTCOME_EXIT_CODE}).${OFF}\n`);
+        if (tail) {
+            process.stderr.write(`${GRAY}  ── last output from ${options.agent} ──${OFF}\n`);
+            process.stderr.write(tail.replace(/^/gm, '  ') + '\n');
+            process.stderr.write(`${GRAY}  ${'─'.repeat(30)}${OFF}\n`);
+        }
+        process.stderr.write(NO_TMUX_TIP);
+    };
+    // F3 (RUSH-2185 / EXEC-23a): paneExitStatus returns {dead:false} for BOTH
+    // "pane is alive" and "tmux query failed (race / pane already gone)". Require
+    // POSITIVE proof before taking the keep-session path — a separate direct query
+    // that only returns true when tmux explicitly confirms pane_dead=0.
+    const checkPaneKnownAlive = async (p) => {
+        try {
+            const r = await runTmux({ socket, args: ['display-message', '-pt', p, '-p', '#{pane_dead}'], throwOnError: false });
+            return isPaneKnownAliveFromQueryResult(r.code, r.stdout);
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * Resolve what an attach client's return actually means, for EVERY path that
+     * attaches (the fresh wrapper below AND the resume-attach above). Asking tmux
+     * is the only way to tell "the user detached" from "the agent exited" from
+     * "the session went away underneath us", so an attach that skips this cannot
+     * do better than assume success — which is exactly the defect EXEC-23b fixes.
+     */
+    const resolveAfterAttach = async (pane) => {
+        const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
+        if (after.dead) {
+            // Nonzero exit after attach → the agent crashed rather than the user
+            // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).
+            // F2: for interactive runs, also recap a clean exit-0 — the harness exited
+            // without error but without starting a REPL, which is still a failure.
+            if (shouldRecapDeadPane(after.status, resolveInteractive(options))) {
+                await surfacePaneFailure(pane, after.status, `${options.agent} exited`);
+            }
+            await killSession(name, socket).catch(() => { });
+            // A dead pane whose status tmux never reported is UNKNOWN, not success —
+            // and surfacePaneFailure already printed `exit 1` for it, so the old
+            // `?? 0` made the message and the returned code disagree (EXEC-23b).
+            return { exitCode: tmuxRunExitCode(after, false), stderr: '', stdout: '' };
+        }
+        // after.dead===false, but that could be a stale/unreadable-pane result.
+        // Require positive proof before keeping the session as "user detached".
+        if (pane && await checkPaneKnownAlive(pane)) {
+            // Confirmed alive: the user pressed Ctrl-b d; keep the session for `agents focus`.
+            return { exitCode: tmuxRunExitCode(after, true), stderr: '', stdout: '' };
+        }
+        // F4 (EXEC-23b): the outcome is UNKNOWN — tmux could not tell us whether the
+        // agent finished or was killed. MUST NOT be reported as success: a caller
+        // scripting `agents run` would count a run killed mid-work as a clean
+        // finish. Tear down so no orphan session is left, say so, and exit non-zero
+        // — the same "1 if unknown" rule the `--host` follow path already uses.
+        await killSession(name, socket).catch(() => { });
+        // One computation feeds both the banner and the return value — printing a
+        // code the caller does not receive is the same defect in miniature.
+        const exitCode = tmuxRunExitCode(after, false);
+        // Two distinct causes reach here, and the banner must not assert the wrong
+        // one: a pane we HAD (the session went away under it) versus a run whose
+        // pane id tmux never reported at creation, which had nothing to read from.
+        const cause = pane
+            ? 'The tmux session went away before its exit status could be read, so this run may have been killed mid-work.'
+            : 'This run had no readable tmux pane, so its exit status could never be read.';
+        process.stderr.write(`\n${RED}agents: ${options.agent} outcome unknown (exit ${exitCode}).${OFF}\n` +
+            `${GRAY}  ${cause}${OFF}\n` + NO_TMUX_TIP);
+        return { exitCode, stderr: '', stdout: '' };
+    };
     // A native resume must not create a competing wrapper for a live session.
     // A retained dead pane is reaped before the harness resumes normally.
-    if (options.resume && await prepareSessionForResume(name, socket) === 'attach') {
+    const resumePrep = options.resume ? await prepareSessionForResume(name, socket) : { decision: 'create' };
+    if (resumePrep.decision === 'attach') {
         if (options.sessionId)
             writeSessionAliasRecord(options.sessionId, name);
         await attachTmux({ socket, args: ['attach-session', '-t', name] });
-        return { exitCode: 0, stderr: '', stdout: '' };
+        // EXEC-23b: a resume-attach is an attach like any other — it must ask tmux
+        // what happened rather than assume 0. Before this it returned a hardcoded
+        // success, so a resumed run whose server died under it reported a clean
+        // finish, the identical defect on the identical shape.
+        return resolveAfterAttach(resumePrep.pane);
     }
     // SessionStart learns some harness IDs only after launch. Carry the wrapper
     // name into that hook so it can bind both identities durably.
@@ -1490,31 +1637,6 @@ async function runInTmux(options, executable, args) {
             });
         }
     }
-    // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
-    // detaches the client the instant the agent exits, so a fast failure (a
-    // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
-    // otherwise leave only a bare `[detached]` with no clue why. Must run BEFORE
-    // killSession — capture-pane needs the session still alive (remain-on-exit
-    // keeps the dead pane readable until we tear it down). Best-effort throughout.
-    const surfacePaneFailure = async (status, headline) => {
-        if (!pane)
-            return;
-        let tail = '';
-        try {
-            const r = await runTmux({ socket, args: ['capture-pane', '-p', '-t', pane, '-S', '-200'], throwOnError: false });
-            if (r.code === 0)
-                tail = formatPaneTail(r.stdout);
-        }
-        catch { /* best-effort — a missing pane just means no recap */ }
-        const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
-        process.stderr.write(`\n${RED}agents: ${headline} (exit ${status ?? 1}).${OFF}\n`);
-        if (tail) {
-            process.stderr.write(`${GRAY}  ── last output from ${options.agent} ──${OFF}\n`);
-            process.stderr.write(tail.replace(/^/gm, '  ') + '\n');
-            process.stderr.write(`${GRAY}  ${'─'.repeat(30)}${OFF}\n`);
-        }
-        process.stderr.write(`${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.${OFF}\n\n`);
-    };
     // The agent could exit before we attach (fast failure). Don't attach to an
     // already-dead pane — surface its output + status directly and tear down.
     const before = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
@@ -1524,47 +1646,16 @@ async function runInTmux(options, executable, args) {
         // user would see only a bare `[detached]` with no clue why. For headless
         // runs the old quiet behaviour stands: exit-0 is a successful quick run.
         if (shouldRecapDeadPane(before.status, resolveInteractive(options))) {
-            await surfacePaneFailure(before.status, `${options.agent} exited before it could start`);
+            await surfacePaneFailure(pane, before.status, `${options.agent} exited before it could start`);
         }
         await killSession(name, socket).catch(() => { });
-        return { exitCode: before.status ?? 0, stderr: '', stdout: '' };
+        // A dead pane whose status tmux never reported is an UNKNOWN outcome, not a
+        // success — and the banner one line up already printed `exit 1` for it, so
+        // the old `?? 0` also made the message and the returned code disagree.
+        return { exitCode: tmuxRunExitCode(before, false), stderr: '', stdout: '' };
     }
     await attachTmux({ socket, args: ['attach-session', '-t', name] });
-    // F3 (RUSH-2185 / EXEC-23a): paneExitStatus returns {dead:false} for BOTH
-    // "pane is alive" and "tmux query failed (race / pane already gone)". Require
-    // POSITIVE proof before taking the keep-session path — a separate direct query
-    // that only returns true when tmux explicitly confirms pane_dead=0.
-    const checkPaneKnownAlive = async (p) => {
-        try {
-            const r = await runTmux({ socket, args: ['display-message', '-pt', p, '-p', '#{pane_dead}'], throwOnError: false });
-            return isPaneKnownAliveFromQueryResult(r.code, r.stdout);
-        }
-        catch {
-            return false;
-        }
-    };
-    const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
-    if (after.dead) {
-        // Nonzero exit after attach → the agent crashed rather than the user
-        // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).
-        // F2: for interactive runs, also recap a clean exit-0 — the harness exited
-        // without error but without starting a REPL, which is still a failure.
-        if (shouldRecapDeadPane(after.status, resolveInteractive(options))) {
-            await surfacePaneFailure(after.status, `${options.agent} exited`);
-        }
-        await killSession(name, socket).catch(() => { });
-        return { exitCode: after.status ?? 0, stderr: '', stdout: '' };
-    }
-    // after.dead===false, but that could be a stale/unreadable-pane result.
-    // Require positive proof before keeping the session as "user detached".
-    if (pane && await checkPaneKnownAlive(pane)) {
-        // Confirmed alive: the user pressed Ctrl-b d; keep the session for `agents focus`.
-        return { exitCode: 0, stderr: '', stdout: '' };
-    }
-    // Ambiguous or unreadable pane (race between pane-died hook and our query) —
-    // tear down rather than leave an orphan session.
-    await killSession(name, socket).catch(() => { });
-    return { exitCode: 0, stderr: '', stdout: '' };
+    return resolveAfterAttach(pane);
 }
 /**
  * Print the run's resolved session id as a one-line stdout sentinel so a `--host`
@@ -1835,6 +1926,13 @@ async function spawnAgent(options) {
 }
 /** Exit code spawnAgent resolves with when a run is killed for crossing a budget cap. */
 export const BUDGET_KILL_EXIT_CODE = 7;
+/**
+ * Exit code a tmux-wrapped run resolves with when tmux cannot tell us how the
+ * agent finished — the pane is unreadable, or it is dead with no reported status
+ * (EXEC-23b). Never 0: an unknown outcome reported as success is how a run killed
+ * mid-work gets counted as a clean finish by whatever scripted it.
+ */
+export const UNKNOWN_OUTCOME_EXIT_CODE = 1;
 /**
  * Resolve the budget watcher for a run. Returns null (watcher dormant) when no
  * caps are configured, so non-budget users pay nothing. When caps exist, builds

package/dist/lib/feed-broadcast.d.ts

@@ -179,6 +179,31 @@ export declare function planFeedBroadcast(config: FeedBroadcastConfig | undefine
  * always wins outright; the fallback never layers on top of it.
  */
 export declare function effectiveBroadcastConfig(config: FeedBroadcastConfig | undefined, level: FeedPostLevel, meta: Meta): FeedBroadcastConfig | undefined;
+/** Sink name for the ephemeral local banner added by `feed post --notify`. */
+export declare const DESKTOP_NOTIFY_SINK = "notify";
+/**
+ * Add a local desktop-banner sink when `feed post --notify` is set — the same
+ * `notifyDesktop` banner `run --notify` raises, but for an authored post.
+ *
+ * `--notify` is a per-post opt-in that ADDS the local banner on top of whatever
+ * `feed.broadcast`/owner delivery already runs; it never replaces a configured
+ * sink. It carries no `minLevel`, so it fires for any level — a quiet milestone
+ * banner on this box does not touch the phone the way an `important` post does.
+ * And it routes through the `desktop` channel provider exactly like every other
+ * `channel:` sink, so it appears in the outcomes and the `--json` payload rather
+ * than a parallel code path the reporting cannot see.
+ *
+ * The desktop banner is inherently local — `notifyDesktop` reaches whoever is at
+ * THIS machine — so a post authored on a headless box notifies that box (a no-op
+ * with a stated reason where no notifier exists, per the desktop provider),
+ * never the operator's Mac. That is the same locality `run --notify` has; the
+ * phone hop stays the job of an `important`-level owner/broadcast sink.
+ *
+ * The banner is added under `DESKTOP_NOTIFY_SINK`, or the first free
+ * `notify-2`/`notify-3`/… when the operator already declared a sink by that
+ * name — so `--notify` can never silently overwrite a configured sink; both fire.
+ */
+export declare function withDesktopNotify(config: FeedBroadcastConfig | undefined, notify: boolean): FeedBroadcastConfig | undefined;
 /**
  * Run the planned sinks. A `command:` sink is a direct spawn with a bounded
  * lifetime; a `channel:` sink delivers in-process. Either way a sink that

package/dist/lib/feed-broadcast.js

@@ -394,6 +394,39 @@ export function effectiveBroadcastConfig(config, level, meta) {
         return undefined;
     return { owner: { channel: 'owner' } };
 }
+/** Sink name for the ephemeral local banner added by `feed post --notify`. */
+export const DESKTOP_NOTIFY_SINK = 'notify';
+/**
+ * Add a local desktop-banner sink when `feed post --notify` is set — the same
+ * `notifyDesktop` banner `run --notify` raises, but for an authored post.
+ *
+ * `--notify` is a per-post opt-in that ADDS the local banner on top of whatever
+ * `feed.broadcast`/owner delivery already runs; it never replaces a configured
+ * sink. It carries no `minLevel`, so it fires for any level — a quiet milestone
+ * banner on this box does not touch the phone the way an `important` post does.
+ * And it routes through the `desktop` channel provider exactly like every other
+ * `channel:` sink, so it appears in the outcomes and the `--json` payload rather
+ * than a parallel code path the reporting cannot see.
+ *
+ * The desktop banner is inherently local — `notifyDesktop` reaches whoever is at
+ * THIS machine — so a post authored on a headless box notifies that box (a no-op
+ * with a stated reason where no notifier exists, per the desktop provider),
+ * never the operator's Mac. That is the same locality `run --notify` has; the
+ * phone hop stays the job of an `important`-level owner/broadcast sink.
+ *
+ * The banner is added under `DESKTOP_NOTIFY_SINK`, or the first free
+ * `notify-2`/`notify-3`/… when the operator already declared a sink by that
+ * name — so `--notify` can never silently overwrite a configured sink; both fire.
+ */
+export function withDesktopNotify(config, notify) {
+    if (!notify)
+        return config;
+    const base = config ?? {};
+    let name = DESKTOP_NOTIFY_SINK;
+    for (let i = 2; name in base; i++)
+        name = `${DESKTOP_NOTIFY_SINK}-${i}`;
+    return { ...base, [name]: { channel: 'desktop', to: 'local' } };
+}
 function runCommandSink(name, argv, timeoutMs) {
     const result = spawnSync(argv[0], argv.slice(1), {
         encoding: 'utf-8',

package/dist/lib/feed.d.ts

@@ -225,7 +225,7 @@ export declare function removeBlock(blockId: string, root?: string): boolean;
  * Embedded so it ships with the compiled CLI and can be installed to the
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
-export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n# Codex emits a PermissionRequest event (not Claude's Notification) when it\n# blocks on an approval prompt. Claude never fires PermissionRequest, so the\n# same script handles both: PermissionRequest maps to an approval-class block\n# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef project_from_cwd(cwd):\n    \"\"\"Basename of cwd, with worktree paths resolved to their repo name.\"\"\"\n    if not cwd:\n        return None\n    norm = cwd.replace(\"\\\\\", \"/\").rstrip(\"/\")\n    if not norm:\n        return None\n    marker = \"/.agents/worktrees/\"\n    idx = norm.find(marker)\n    if idx > 0:\n        repo_path = norm[:idx]\n        base = repo_path[repo_path.rfind(\"/\") + 1:]\n        if base:\n            return base\n    base = norm[norm.rfind(\"/\") + 1:]\n    return base or None\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        # A declared block (`agents feed post --blocked`) is the agent explicitly\n        # saying it is stuck. Unlike a question/notification/approval block -- which\n        # tracks an in-flight harness prompt that a lifecycle event resolves -- a\n        # declared block stays open until it is actually ANSWERED. So while it is\n        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:\n        # otherwise the needs-you record vanishes the moment the agent parks the block\n        # and its turn ends -- exactly when the owner still needs to see and answer it.\n        # Once it IS answered (an answered marker exists), it clears like any other\n        # block by falling through below -- which frees that marker too, so a later\n        # `--blocked` in the same session is not falsely locked as already-answered\n        # (recordAnswer creates the marker with O_EXCL).\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            answered = os.path.exists(os.path.join(answered_dir, f\"{block_id}.json\"))\n            if existing.get(\"kind\") == \"declared\" and not answered:\n                return\n        except Exception:\n            pass\n        # A matcher-less PostToolUse clear (registered for Codex so an approved\n        # tool clears its approval card) must NOT wipe an open AskUserQuestion\n        # while an unrelated tool runs mid-question -- those are cleared only by\n        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a\n        # 'question' block; approval/notification blocks clear once the tool runs.\n        if hook_event == \"PostToolUse\":\n            try:\n                with open(target) as existing_file:\n                    existing = json.load(existing_file)\n                if existing.get(\"kind\") == \"question\" and payload.get(\"tool_name\") != \"AskUserQuestion\":\n                    return\n            except Exception:\n                pass\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    codex_approval = False\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    elif hook_event == \"PermissionRequest\":\n        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,\n        # tool_input) but carries no questions -- Codex is asking to run a tool,\n        # not asking the operator a multiple-choice question. Publish it as a\n        # notification-kind approval block naming the tool so the feed and the\n        # phone notifier can surface it, and so the Factory extension can bridge\n        # it to a VS Code notification.\n        tool_name = payload.get(\"tool_name\") or \"a tool\"\n        tool_input = payload.get(\"tool_input\", {})\n        command = \"\"\n        if isinstance(tool_input, dict):\n            command = (\n                tool_input.get(\"command\")\n                or tool_input.get(\"cmd\")\n                or tool_input.get(\"path\")\n                or \"\"\n            )\n            if isinstance(command, list):\n                command = \" \".join(str(c) for c in command)\n        detail = f\": {command}\" if command else \"\"\n        normalized_questions = [{\n            \"text\": f\"Codex needs approval to run {tool_name}{detail}\",\n            \"header\": \"Approval needed\",\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n        notification_type = \"permission_prompt\"\n        codex_approval = True\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    project = project_from_cwd(cwd)\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if project:\n        block[\"project\"] = project\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # A Codex PermissionRequest is a real approval gate: mark it approval-class\n    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent\n    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default\n    # 'medium') and pages the phone. A plain 'deny' is the safe default.\n    if codex_approval:\n        block[\"blockClass\"] = \"approval\"\n        block[\"costOfDelay\"] = \"high\"\n        block[\"safeDefault\"] = \"deny\"\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex\n    # PermissionRequest carries tool ARGS in tool_input (command/path), not\n    # operator controls, so it is excluded here -- its class/cost is stamped\n    # above from codex_approval.\n    controls = payload.get(\"tool_input\", {}) if hook_event not in (\"Notification\", \"PermissionRequest\") else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n# Codex emits a PermissionRequest event (not Claude's Notification) when it\n# blocks on an approval prompt. Claude never fires PermissionRequest, so the\n# same script handles both: PermissionRequest maps to an approval-class block\n# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef project_from_cwd(cwd):\n    \"\"\"Basename of cwd, with worktree paths resolved to their repo name.\"\"\"\n    if not cwd:\n        return None\n    norm = cwd.replace(\"\\\\\", \"/\").rstrip(\"/\")\n    if not norm:\n        return None\n    marker = \"/.agents/worktrees/\"\n    idx = norm.find(marker)\n    if idx > 0:\n        repo_path = norm[:idx]\n        base = repo_path[repo_path.rfind(\"/\") + 1:]\n        if base:\n            return base\n    base = norm[norm.rfind(\"/\") + 1:]\n    return base or None\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        # A declared block (`agents feed post --blocked`) is the agent explicitly\n        # saying it is stuck. Unlike a question/notification/approval block -- which\n        # tracks an in-flight harness prompt that a lifecycle event resolves -- a\n        # declared block stays open until it is actually ANSWERED. So while it is\n        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:\n        # otherwise the needs-you record vanishes the moment the agent parks the block\n        # and its turn ends -- exactly when the owner still needs to see and answer it.\n        # Once it IS answered (an answered marker exists), it clears like any other\n        # block by falling through below -- which frees that marker too, so a later\n        # `--blocked` in the same session is not falsely locked as already-answered\n        # (recordAnswer creates the marker with O_EXCL).\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            answered = os.path.exists(os.path.join(answered_dir, f\"{block_id}.json\"))\n            if existing.get(\"kind\") == \"declared\" and not answered:\n                return\n        except Exception:\n            pass\n        # A matcher-less PostToolUse clear (registered for Codex so an approved\n        # tool clears its approval card) must NOT wipe an open AskUserQuestion\n        # while an unrelated tool runs mid-question -- those are cleared only by\n        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a\n        # 'question' block; approval/notification blocks clear once the tool runs.\n        if hook_event == \"PostToolUse\":\n            try:\n                with open(target) as existing_file:\n                    existing = json.load(existing_file)\n                if existing.get(\"kind\") == \"question\" and payload.get(\"tool_name\") != \"AskUserQuestion\":\n                    return\n            except Exception:\n                pass\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    codex_approval = False\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    elif hook_event == \"PermissionRequest\":\n        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,\n        # tool_input) but carries no questions -- Codex is asking to run a tool,\n        # not asking the operator a multiple-choice question. Publish it as a\n        # notification-kind approval block naming the tool so the feed and the\n        # phone notifier can surface it, and so AGI EXT can bridge\n        # it to a VS Code notification.\n        tool_name = payload.get(\"tool_name\") or \"a tool\"\n        tool_input = payload.get(\"tool_input\", {})\n        command = \"\"\n        if isinstance(tool_input, dict):\n            command = (\n                tool_input.get(\"command\")\n                or tool_input.get(\"cmd\")\n                or tool_input.get(\"path\")\n                or \"\"\n            )\n            if isinstance(command, list):\n                command = \" \".join(str(c) for c in command)\n        detail = f\": {command}\" if command else \"\"\n        normalized_questions = [{\n            \"text\": f\"Codex needs approval to run {tool_name}{detail}\",\n            \"header\": \"Approval needed\",\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n        notification_type = \"permission_prompt\"\n        codex_approval = True\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    project = project_from_cwd(cwd)\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if project:\n        block[\"project\"] = project\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # A Codex PermissionRequest is a real approval gate: mark it approval-class\n    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent\n    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default\n    # 'medium') and pages the phone. A plain 'deny' is the safe default.\n    if codex_approval:\n        block[\"blockClass\"] = \"approval\"\n        block[\"costOfDelay\"] = \"high\"\n        block[\"safeDefault\"] = \"deny\"\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex\n    # PermissionRequest carries tool ARGS in tool_input (command/path), not\n    # operator controls, so it is excluded here -- its class/cost is stamped\n    # above from codex_approval.\n    controls = payload.get(\"tool_input\", {}) if hook_event not in (\"Notification\", \"PermissionRequest\") else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
 export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     name: string;

package/dist/lib/feed.js

@@ -24,6 +24,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
+import { stringifyDoc } from './yaml-io.js';
 import { getFeedDir, getUserAgentsDir } from './state.js';
 import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from './operator.js';
 import { projectKeyFromCwd } from './project-key.js';
@@ -569,7 +570,7 @@ def main():
         # tool_input) but carries no questions -- Codex is asking to run a tool,
         # not asking the operator a multiple-choice question. Publish it as a
         # notification-kind approval block naming the tool so the feed and the
-        # phone notifier can surface it, and so the Factory extension can bridge
+        # phone notifier can surface it, and so AGI EXT can bridge
         # it to a VS Code notification.
         tool_name = payload.get("tool_name") or "a tool"
         tool_input = payload.get("tool_input", {})
@@ -853,7 +854,16 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
         }
         if (installed) {
             const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
-            fs.writeFileSync(tmpYaml, String(yamlDoc));
+            // `flowCollectionPadding: false` matches the committed formatting. The yaml
+            // emitter defaults to padded flow sequences (`[ a, b ]`), but the tracked
+            // `agents.yaml` uses `[a, b]`. Re-emitting a committed flow node (e.g. a
+            // notify hook's `command: [agents, notify, "{message}"]`) with padding left
+            // the git-backed `~/.agents` tree permanently dirty on this file, so
+            // `agents repo pull` refused and seven boxes silently fell 37-52 commits
+            // behind fleet-wide (RUSH-2505). Preserve each node's committed block/flow
+            // style — do NOT force `collectionStyle`, which would flatten a committed
+            // flow hook to a block list and reintroduce a diff.
+            fs.writeFileSync(tmpYaml, stringifyDoc(yamlDoc));
             fs.renameSync(tmpYaml, agentsYamlPath);
         }
         return { installed };