@phnx-labs/agents-cli 1.22.52 → 1.22.54

package/dist/lib/exec.js

@@ -32,6 +32,7 @@ import { isTmuxEnabled, selfConfiguredDeviceRole } from './device-config.js';
 import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
+import { probeUnprivilegedUserns } from './linux-userns.js';
 import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
@@ -181,6 +182,69 @@ export function defaultModeFor(agent) {
 export function implicitModeFor(agent) {
     return agent === 'codex' ? 'edit' : 'plan';
 }
+/**
+ * Preflight for Codex's Linux sandbox. Codex ≥0.146 sandboxes `read-only` and
+ * `workspace-write` runs with a bundled bubblewrap that needs an unprivileged
+ * user namespace; on a box that restricts it (Ubuntu 24.04
+ * `apparmor_restrict_unprivileged_userns=1`) bwrap dies with "setting up uid map:
+ * Permission denied" and a HEADLESS codex run lands zero tools — no file writes,
+ * no shell — while still reporting a completed turn. That silent under-delivery
+ * is what breaks `agents teams` codex teammates (always headless + workspace-write)
+ * and headless `agents run codex` alike on the fleet. Returns a loud, actionable
+ * message to fail the launch with instead of spawning that doomed run; returns
+ * null when the run is fine to proceed.
+ *
+ * Deliberately scoped: only `codex`, only Linux, only a HEADLESS run (an
+ * interactive TUI surfaces the bwrap error to the operator itself), and only a
+ * SANDBOXED mode — `skip` is codex `--dangerously-bypass-approvals-and-sandbox`,
+ * which uses no bwrap and is unaffected. The intended auto=workspace-write config
+ * is never weakened here; the run fails loud rather than silently downgrading.
+ * PHNX-3285.
+ */
+export function codexSandboxPreflight(args) {
+    if (args.agent !== 'codex')
+        return null;
+    if (args.platform !== 'linux')
+        return null;
+    if (args.interactive)
+        return null;
+    if (args.mode === 'skip')
+        return null;
+    if (args.userns.state !== 'blocked')
+        return null;
+    const reason = args.userns.reason ?? 'unprivileged user namespaces are restricted';
+    return (`codex's Linux sandbox can't start on ${args.machine}: ${reason}, so codex's ` +
+        `bundled bubblewrap fails with "bwrap: setting up uid map: Permission denied" ` +
+        `and a headless run lands zero tools. (PHNX-3285)\n` +
+        `\n` +
+        `Enable it once on this box — keeps codex's workspace-write sandbox intact:\n` +
+        `  echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-codex-userns.conf\n` +
+        `  sudo sysctl --system\n` +
+        `  # verify: unshare --user --map-root-user true   (exit 0 = fixed)\n` +
+        `(agents-cli ships cli/scripts/enable-codex-sandbox.sh to apply + verify this.)\n` +
+        `\n` +
+        `Or run codex WITHOUT a filesystem sandbox instead: add --mode skip.`);
+}
+/**
+ * Identity a custom-harness run stamps on env / pid-registry / sidecars.
+ * `agent` is the host CLI; `harnessName` is the profile the user launched.
+ * Empty/whitespace harness names fall back to the host so a blank stamp
+ * never hides a real agent.
+ */
+export function stampedAgentName(options) {
+    const harness = options.harnessName?.trim();
+    return harness || options.agent;
+}
+/**
+ * Profile name when it differs from the host agent. Undefined for a native
+ * run, so pid-registry / sidecar records stay sparse.
+ */
+export function customHarnessName(options) {
+    const harness = options.harnessName?.trim();
+    if (!harness || harness === options.agent)
+        return undefined;
+    return harness;
+}
 /**
  * Resolve interactive vs headless. Explicit flags are definitive and win over
  * inference: `--interactive` forces interactive, `--headless` forces headless.
@@ -346,8 +410,11 @@ export function buildExecEnv(options) {
     result.AGENTS_RUN_MODE = resolveHeadlessMode(options.agent, normalizeMode(options.mode), resolveInteractive(options), options.modeWarningContext, options.modeWarningState);
     result.AGENTS_HISTORY_DIR = getHistoryDir();
     // So activity / feed posts stamp the right harness without re-detecting.
+    // A custom-harness run (`agents run deepseek`) must stamp the PROFILE name,
+    // not the host CLI (`claude`) — otherwise sessions and feed posts cannot
+    // tell the two apart (PHNX-2935).
     if (options.agent) {
-        result.AGENTS_AGENT_NAME = options.agent;
+        result.AGENTS_AGENT_NAME = stampedAgentName(options);
     }
     if (options.cwd) {
         result.AGENTS_CWD = options.cwd;
@@ -774,8 +841,13 @@ export function buildExecCommand(options) {
     // that maps to reasoning effort on a single-model harness (e.g. Grok, where the
     // tier IS the effort dial). `modelVersion` is null when no version resolves;
     // `tierModel` is the concrete model a tier resolved to (null => drop the flag).
+    // Prefer the user's explicit --model. Codex falls back to ~/.codex/config.toml
+    // (per-version CODEX_HOME may not carry that setting). OpenCode has no model
+    // env var — a custom-harness pin lives in OPENCODE_MODEL and must become
+    // `--model` here, or the host silently uses its configured default (PHNX-2577).
     const effectiveModel = options.model
-        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined);
+        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined)
+        ?? (options.agent === 'opencode' ? options.env?.OPENCODE_MODEL : undefined);
     const modelVersion = effectiveModel && template.modelFlag
         ? (options.version || resolveVersion(options.agent, options.cwd || process.cwd()))
         : null;
@@ -883,12 +955,8 @@ export function buildExecCommand(options) {
     else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
-    // Add model. Prefer the user's explicit --model. Otherwise, for Codex, fall
-    // back to the model configured in the user's active ~/.codex/config.toml:
-    // Codex runs under a per-version CODEX_HOME (see buildExecEnv) that may not
-    // carry that setting, so without this it silently defaults to gpt-5.3-codex,
-    // which a ChatGPT-tier account can't use (HTTP 400). Forwarding keeps the
-    // user's default model setup for both `agents run` and `agents teams`.
+    // Add model. `effectiveModel` already preferred --model, then Codex's
+    // configured default, then an OpenCode custom-harness pin (OPENCODE_MODEL).
     if (effectiveModel && template.modelFlag) {
         if (tierResolved) {
             // Cost tier (cheap|default|best|ultra) -> a concrete model this harness+
@@ -1176,36 +1244,38 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * Wrapping serves two independent purposes, and they are gated differently:
+ * The wrap is opt-in via this device's `tmux.enabled` (`configEnabled`): a
+ * unique `%pane` handle so `agents sessions --active` can tell co-located
+ * agents apart and `agents focus` re-attaches without forking, plus scrollback
+ * and mouse at the operator's keyboard. Off means OFF, for local and remote
+ * runs alike (PHNX-3316) — a followed `--device` run left bare is protected by
+ * reconnect-and-resume (lib/hosts/reconnect.ts), which rejoins the live pane
+ * when one exists and resumes the harness session from disk when it does not.
+ * The RUSH-3125 forced remote wrap conflated durability with that preference
+ * and surprised every operator who had explicitly left tmux off.
  *
- *  - **Addressability** (`configEnabled`): a unique `%pane` handle so
- *    `agents sessions --active` can tell co-located agents apart and `agents
- *    focus` re-attaches without forking. That is a local preference — the
- *    operator turns it on once tmux's mouse/clipboard/scrollback suits them.
- *  - **Durability** (`remoteDispatch`): a run that arrived over SSH must outlive
- *    the SSH client, because a bare remote spawn dies of SIGHUP the moment the
- *    link blinks. That is not a preference, so it does not consult
- *    `configEnabled` (RUSH-3125 — see {@link TmuxWrapContext.remoteDispatch}).
+ * One case still wraps regardless: a followed remote run whose launcher has
+ * no TTY (CI, scripts, another agent) gives the peer nothing to attach to —
+ * the detached pane is the run's only interface, not an ergonomics choice.
  *
- * The per-run opt-outs bind BOTH: `--raw` / `--no-tmux` / `AGENTS_NO_TMUX=1` are
- * explicit "I want the bare process" requests, and honouring them over the
- * durability rule keeps one escape hatch that always works.
+ * The per-run opt-outs bind everything: `--raw` / `--no-tmux` /
+ * `AGENTS_NO_TMUX=1` are explicit "I want the bare process" requests, and an
+ * escape hatch that silently stopped applying over `--device` would be worse
+ * than the bare run the user asked for.
  *
  * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
  */
 export function resolveTmuxWrap(ctx) {
     // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
-    // nesting tmux-in-tmux is pointless — none of these can wrap, and none of them
-    // is a remote interactive agent whose life depends on it.
+    // nesting tmux-in-tmux is pointless.
     if (!ctx.interactive)
         return { kind: 'bare' };
     if (ctx.platform === 'win32')
         return { kind: 'bare' };
     if (ctx.inTmux)
         return { kind: 'bare' };
-    // Explicit opt-outs win over the durability rule: `--raw` exists precisely to
-    // get the unwrapped process, and a flag that silently stopped working on a
-    // remote box would be worse than an undurable run the user asked for.
+    // Explicit opt-outs win over every other rule: `--raw` exists precisely to
+    // get the unwrapped process.
     if (ctx.raw)
         return { kind: 'bare' };
     if (ctx.noTmuxEnv)
@@ -1213,10 +1283,13 @@ export function resolveTmuxWrap(ctx) {
     // Local interactive with no TTY cannot attach. Wrapping anyway creates a
     // detached pane, attach returns immediately, and resolveAfterAttach treats
     // the still-alive pane as Ctrl-b d — the session-tracker test leak.
-    // Remote dispatch is the exception: --no-follow *intends* a detached pane.
     if (!ctx.hasTty && !ctx.remoteDispatch)
         return { kind: 'bare' };
-    if (!ctx.configEnabled && !ctx.remoteDispatch)
+    // tmux.enabled gates the wrap for local AND followed remote runs. The one
+    // exception: a followed remote run whose launcher has no TTY (CI, scripts)
+    // gives the peer nothing to attach to — the detached pane is its only
+    // interface, infrastructure rather than ergonomics.
+    if (!ctx.configEnabled && !(ctx.remoteDispatch && !ctx.hasTty))
         return { kind: 'bare' };
     // Fail loud rather than launch a remote agent that a blink would kill: the
     // caller refuses the run instead of starting work that cannot be recovered.
@@ -1520,6 +1593,7 @@ async function runInTmux(options, executable, args) {
         writePidSessionEntry({
             pid: panePid,
             agent: options.agent,
+            harness: customHarnessName(options),
             sessionId: options.sessionId,
             cwd,
             actor: resolveActor().id,
@@ -1538,6 +1612,7 @@ async function runInTmux(options, executable, args) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });
         }
@@ -1623,6 +1698,27 @@ async function spawnAgent(options) {
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
     const interactive = resolveInteractive(options);
+    // Fail loud before spawning a headless codex whose Linux sandbox can't start —
+    // otherwise it burns a turn and lands zero tools (PHNX-3285). Cheap gate first
+    // so the userns probe (one `unshare`) runs only for the exact case it applies to
+    // (codex + Linux + headless + a sandboxed mode), never for every spawn.
+    if (options.agent === 'codex' && process.platform === 'linux' && !interactive) {
+        const codexMode = options.mode ? normalizeMode(options.mode) : defaultModeFor(options.agent);
+        if (codexMode !== 'skip') {
+            const message = codexSandboxPreflight({
+                agent: options.agent,
+                platform: process.platform,
+                interactive,
+                mode: codexMode,
+                userns: probeUnprivilegedUserns(),
+                machine: machineId(),
+            });
+            if (message) {
+                process.stderr.write(`\x1b[31m${message}\x1b[0m\n`);
+                return { exitCode: 1, stdout: '', stderr: message };
+            }
+        }
+    }
     // Budget live kill-switch (issue #346). For headless runs we incrementally
     // parse stream-json usage off stdout, accumulate cost, and kill the child the
     // moment a configured cap is crossed — exactly like the --timeout path, but
@@ -1662,9 +1758,10 @@ async function spawnAgent(options) {
         args: redactArgs(args.slice(0, 10)),
     });
     // Interactive spawn-wrap: run the agent INSIDE a shared-socket tmux session
-    // (then attach this TTY) so it gets a unique, addressable %pane — and, when
-    // the run arrived over `--device`, so it survives the SSH link that carries
-    // it. Every failed guard keeps the bare spawn below.
+    // (then attach this TTY) so it gets a unique, addressable %pane. Opt-in via
+    // this device's tmux.enabled, local and remote alike (PHNX-3316); a followed
+    // remote run left bare relies on reconnect-and-resume, not a pane. Every
+    // failed guard keeps the bare spawn below.
     const tmuxWrap = resolveTmuxWrap({
         interactive,
         platform: process.platform,
@@ -1683,10 +1780,15 @@ async function spawnAgent(options) {
         // there is no launcher-side probe ahead of this one. Failing here still
         // fails before the agent starts, which is what matters; a pre-dispatch
         // probe would only move the message earlier, at the cost of a round trip on
-        // every launch.
-        const msg = `agents: ${machineId()} has no tmux, so a --device run here could not survive a dropped connection.\n`
-            + `  install it:            (apt|dnf|brew) install tmux\n`
-            + `  or accept the risk:    agents run … --device ${machineId()} --raw\n`;
+        // every launch. Reached only when the wrap was wanted: the device opted in
+        // via tmux.enabled, or a followed run whose launcher had no TTY (CI,
+        // scripts) left the peer nothing to attach to, so the pane is its stdout.
+        // The config tip uses the ssh form because tmux.enabled is machine-local:
+        // setting it from the launcher throws (assertLocalTarget).
+        const msg = `agents: ${machineId()} has no tmux, so this --device run cannot get the pane it needs.\n`
+            + `  install it:              (apt|dnf|brew) install tmux\n`
+            + `  or turn the wrap off:    agents ssh ${machineId()} 'agents devices config ${machineId()} tmux.enabled off'\n`
+            + `  or accept a bare run:    agents run … --device ${machineId()} --raw\n`;
         process.stderr.write(`\x1b[31m${msg}\x1b[0m`);
         timer.end({ exitCode: 1, status: 'failed', error: 'remote interactive run has no tmux for durability' });
         return { exitCode: 1, stdout: '', stderr: msg };
@@ -1737,6 +1839,7 @@ async function spawnAgent(options) {
         writePidSessionEntry({
             pid: child.pid ?? 0,
             agent: options.agent,
+            harness: customHarnessName(options),
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
             actor: resolveActor().id,
@@ -1751,6 +1854,7 @@ async function spawnAgent(options) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });
         }

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

@@ -76,7 +76,12 @@ export interface OpenBlock {
     source?: AttentionSource;
     /** Lifecycle state. Derived from the answer/continue markers when absent — see {@link deriveBlockState}. */
     state?: AttentionState;
-    /** Where in the source this block's generation sits — carried onto its resolution tombstone. */
+    /**
+     * Where in the source this block's generation sits — stamped at write time
+     * (`buildDeclaredBlock`, the feed-publish hook) and carried onto its resolution
+     * tombstone. Without a write-time cursor a new generation is suppressed whenever
+     * `session.lastActivityMs` is unresolvable (cloud / remote / index-lag).
+     */
     sourceCursor?: SourceCursor;
     /** Indexed launch origin, added at read time when the live session is known. */
     origin?: 'cli' | 'routine';
@@ -319,6 +324,9 @@ export interface DeclareBlockInput {
  * `costOfDelay: high` because a declared block is, by definition, an agent that
  * has already stopped making progress — that is what makes it worth interrupting
  * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ *
+ * `sourceCursor` is stamped from `ts` at write time so a fresh generation is
+ * comparable even when the live session's `lastActivityMs` is unresolvable.
  */
 export declare function buildDeclaredBlock(agent: DeclaringAgent, input: DeclareBlockInput): OpenBlock;
 /** Atomic write a block record to the feed store. Clears stale lifecycle state. */
@@ -334,7 +342,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 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";
+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    # A resolution tombstone is written BEFORE unlink (matching TS recordAnswer)\n    # so a stale lifecycle re-read cannot resurrect this generation.\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        now_iso = datetime.now(timezone.utc).isoformat()\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": now_iso,\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        # Tombstone first, then drop the open-block view. A missing/corrupt\n        # block means there is nothing to resolve; fail open.\n        existing = read_json(target)\n        if isinstance(existing, dict):\n            generation = existing.get(\"generation\") or existing.get(\"ts\")\n            if generation:\n                tombstone = {\n                    \"blockId\": block_id,\n                    \"generation\": generation,\n                    \"resolvedAt\": now_iso,\n                    \"reason\": \"answered\",\n                }\n                source_cursor = existing.get(\"sourceCursor\")\n                if source_cursor:\n                    tombstone[\"sourceCursor\"] = source_cursor\n                write_json(\n                    os.path.join(feed_dir, \"resolutions\", f\"{block_id}.json\"),\n                    tombstone,\n                )\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 = datetime.now(timezone.utc)\n    now_iso = now.isoformat()\n    now_ms = int(now.timestamp() * 1000)\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        # Write-time cursor so a new generation is not suppressed when\n        # session.lastActivityMs is unresolvable (cloud / remote / index-lag).\n        \"sourceCursor\": {\"lastActivityMs\": now_ms},\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/feed.js

@@ -374,6 +374,9 @@ export function clearBlockLifecycle(blockId, root) {
  * `costOfDelay: high` because a declared block is, by definition, an agent that
  * has already stopped making progress — that is what makes it worth interrupting
  * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ *
+ * `sourceCursor` is stamped from `ts` at write time so a fresh generation is
+ * comparable even when the live session's `lastActivityMs` is unresolvable.
  */
 export function buildDeclaredBlock(agent, input) {
     const text = input.text.trim().replace(/\s+/g, ' ');
@@ -399,6 +402,9 @@ export function buildDeclaredBlock(agent, input) {
         generation: ts,
         source: 'declared',
         state: 'open',
+        // Write-time cursor so a new generation is not suppressed when
+        // session.lastActivityMs is unresolvable (cloud / remote / index-lag).
+        sourceCursor: { lastActivityMs: Date.parse(ts) },
         kind: 'declared',
         questions: [{ text, header: 'Needs you', ...(options.length ? { options } : {}) }],
         blockClass: input.safeDefault ? 'approval' : 'decision',
@@ -660,13 +666,16 @@ def main():
     # Terminal answers (human typed in the TUI) record an answered marker and
     # remove the block file so the feed stops showing it within one poll cycle.
     # The marker stays behind so a concurrent surface cannot double-answer.
+    # A resolution tombstone is written BEFORE unlink (matching TS recordAnswer)
+    # so a stale lifecycle re-read cannot resurrect this generation.
     if hook_event == "UserPromptSubmit":
         os.makedirs(answered_dir, exist_ok=True)
         marker = os.path.join(answered_dir, f"{block_id}.json")
+        now_iso = datetime.now(timezone.utc).isoformat()
         try:
             fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
             record = {
-                "answeredAt": datetime.now(timezone.utc).isoformat(),
+                "answeredAt": now_iso,
                 "answeredFrom": "terminal",
             }
             with os.fdopen(fd, "w") as f:
@@ -675,6 +684,25 @@ def main():
             pass
         except Exception:
             pass
+        # Tombstone first, then drop the open-block view. A missing/corrupt
+        # block means there is nothing to resolve; fail open.
+        existing = read_json(target)
+        if isinstance(existing, dict):
+            generation = existing.get("generation") or existing.get("ts")
+            if generation:
+                tombstone = {
+                    "blockId": block_id,
+                    "generation": generation,
+                    "resolvedAt": now_iso,
+                    "reason": "answered",
+                }
+                source_cursor = existing.get("sourceCursor")
+                if source_cursor:
+                    tombstone["sourceCursor"] = source_cursor
+                write_json(
+                    os.path.join(feed_dir, "resolutions", f"{block_id}.json"),
+                    tombstone,
+                )
         # Remove the visible block so the feed drops the answered question.
         try:
             os.unlink(target)
@@ -769,7 +797,9 @@ def main():
         os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
     ) or session_id
 
-    now_iso = datetime.now(timezone.utc).isoformat()
+    now = datetime.now(timezone.utc)
+    now_iso = now.isoformat()
+    now_ms = int(now.timestamp() * 1000)
     stats_path = os.path.join(asks_dir, f"{safe_session_id}.json")
     stats = read_json(stats_path) or {}
     recent = stats.get("recentAskTimestamps") if isinstance(stats, dict) else []
@@ -803,6 +833,9 @@ def main():
         "host": host,
         "runtime": runtime,
         "ts": now_iso,
+        # Write-time cursor so a new generation is not suppressed when
+        # session.lastActivityMs is unresolvable (cloud / remote / index-lag).
+        "sourceCursor": {"lastActivityMs": now_ms},
         "questions": normalized_questions,
         "kind": kind,
     }

package/dist/lib/feed-broadcast.js

@@ -7,7 +7,7 @@
  * a GitHub issue) hears nothing at all. So a post can also be mirrored outward.
  *
  * Sinks are **argv templates from config**, never hardcoded integrations. This
- * CLI ships Apache-2.0 and must not depend on one person's tracker or messaging
+ * CLI ships under FSL-1.1-Apache-2.0 and must not depend on one person's tracker or messaging
  * stack; declaring `[linear, update, "{ticket}", --comment, "{text}"]` in
  * `agents.yaml` keeps the coupling in the operator's config where it belongs,
  * and lets someone else point the same mechanism at `jira`, `gh issue comment`,

package/dist/lib/fleet/apply.d.ts

@@ -45,6 +45,13 @@ export interface SourceAuth {
     /** The captured file payloads, keyed by agent. */
     filesByAgent: Map<string, AuthFilePayload[]>;
 }
+/**
+ * Bundles `fleet apply` considers for push. The reserved file-backed `auth`
+ * bundle is always included when it exists locally — it is the fleet-shared
+ * setup-token store and must not wait on `--provision-secrets` / a manifest
+ * list (PHNX-2371).
+ */
+export declare function fleetSecretsBundles(declared: string[] | undefined): string[];
 export interface DiffContext {
     /** agents-cli version the source is on — the fleet target version. */
     targetCliVersion: string;
@@ -95,6 +102,10 @@ export interface SecretPushDecision {
  * auto-provisions its OWN machine-local key — so each box ends up with an
  * unshared at-rest key and NO passphrase is forwarded. That is the direct
  * alternative to the fleet-wide shared secret this ticket exists to remove.
+ *
+ * The reserved `auth` bundle is the exception: it is always file-backed
+ * (SEC-GAP-3) and is pushed even without `--provision-secrets`, because it is
+ * the one fleet-shared setup-token store (PHNX-2371).
  */
 export declare function decideSecretPush(bundle: string, desired: DeviceDesired, probe: DeviceProbe, ctx: DiffContext): SecretPushDecision;
 export interface ProbeOptions {

package/dist/lib/fleet/apply.js

@@ -9,6 +9,7 @@
  */
 import * as os from 'os';
 import { pushBundleToHost } from '../secrets/push.js';
+import { AUTH_BUNDLE_NAME, inspectReservedAuthBundle, isReservedBundleName } from '../secrets/bundles.js';
 import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
 import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
@@ -88,6 +89,20 @@ export function parseInstalledVersions(stdout) {
         return undefined;
     }
 }
+/**
+ * Bundles `fleet apply` considers for push. The reserved file-backed `auth`
+ * bundle is always included when it exists locally — it is the fleet-shared
+ * setup-token store and must not wait on `--provision-secrets` / a manifest
+ * list (PHNX-2371).
+ */
+export function fleetSecretsBundles(declared) {
+    const out = [...(declared ?? [])];
+    const auth = inspectReservedAuthBundle();
+    if (auth.exists && auth.ok && !out.includes(AUTH_BUNDLE_NAME)) {
+        out.push(AUTH_BUNDLE_NAME);
+    }
+    return out;
+}
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export function diffFleet(desired, probes, ctx) {
     const devices = [];
@@ -208,12 +223,17 @@ export function diffFleet(desired, probes, ctx) {
  * auto-provisions its OWN machine-local key — so each box ends up with an
  * unshared at-rest key and NO passphrase is forwarded. That is the direct
  * alternative to the fleet-wide shared secret this ticket exists to remove.
+ *
+ * The reserved `auth` bundle is the exception: it is always file-backed
+ * (SEC-GAP-3) and is pushed even without `--provision-secrets`, because it is
+ * the one fleet-shared setup-token store (PHNX-2371).
  */
 export function decideSecretPush(bundle, desired, probe, ctx) {
     const device = desired.device;
-    const backend = probe.platform === 'linux' ? 'file' : 'keychain';
+    const reserved = isReservedBundleName(bundle);
+    const backend = reserved || probe.platform === 'linux' ? 'file' : 'keychain';
     const manual = `recreate secrets bundle '${bundle}' (\`agents ssh ${device} -- secrets create ${bundle}\`)`;
-    if (!ctx.provisionSecrets) {
+    if (!ctx.provisionSecrets && !reserved) {
         return { push: false, backend, reason: `${manual} — or re-run with --provision-secrets to push it` };
     }
     if (!probe.reachable) {
@@ -416,7 +436,7 @@ export function reconcileDevice(row, device, ctx) {
             ok = false;
             continue;
         }
-        const backend = device.platform === 'linux' ? 'file' : 'keychain';
+        const backend = isReservedBundleName(bundle) || device.platform === 'linux' ? 'file' : 'keychain';
         try {
             const out = pushBundleToHost(bundle, target, {
                 remoteBackend: backend,

package/dist/lib/fleet/auth-sync.js

@@ -136,9 +136,11 @@ export const FLEET_LOGIN_FLOWS = {
         successFile: successFileFor('opencode'),
     },
     // claude: interactive `/login` inside the TUI is a loopback browser flow, and
-    // the token is keychain-bound on macOS. A headless `claude setup-token` device
-    // variant exists (TODO: wire as a device-code flow with a captured pattern);
-    // until then claude is flagged non-remotable.
+    // the token is keychain-bound on macOS. That native login stays per-box and
+    // is never copied. The shareable `claude setup-token` mint is a different
+    // credential class — wired as `agents accounts mint claude` / `agents auth mint`
+    // (`lib/auth-mint.ts`), not as a fleet-login device-code flow (a setup-token
+    // is account-scoped, not per-machine).
     claude: {
         loginCommand: 'claude',
         flowType: 'loopback',

package/dist/lib/help.d.ts

@@ -18,6 +18,15 @@ export interface CommandGroup {
  * any group fall back to a plain "Commands:" section below the groups.
  */
 export declare function registerCommandGroups(parent: Command, groups: readonly CommandGroup[]): void;
+/**
+ * Front-door command groups shown on `agents --help`. Derived from measured
+ * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
+ * devices/accounts/add. The remaining groups stay discoverable through the
+ * pointer rendered below these groups.
+ */
+export declare const FRONT_DOOR_COMMAND_GROUPS: readonly CommandGroup[];
+/** Mark the root program so its help only renders front-door groups + a pointer. */
+export declare function setCompactRootHelp(program: Command): void;
 /** Examples + Notes blocks attached to a command via setHelpSections. */
 export interface HelpSections {
     examples?: string;