@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/feed/feed.js

@@ -1,26 +1,3 @@
-/**
- * Feed store -- structured block records published by agents waiting on user
- * input (AskUserQuestion). The outbound counterpart to the inbound mailbox:
- * the mailbox delivers messages TO agents; the feed surfaces decisions agents
- * need FROM the user.
- *
- * Layout: <feedDir>/<blockId>.json
- *   Each file is one open block -- a question the agent asked. One block per
- *   session: a new AskUserQuestion in the same session replaces the previous
- *   block (an agent can only ask one question at a time). Removed when the
- *   session advances past the block.
- *
- * A block carries enough identity (sessionId, mailboxId, host, runtime) for
- * `agents feed` to aggregate across hosts and for `agents message` to route
- * a reply back to the right agent.
- *
- * Answer lifecycle:
- *   - A block may be answered from any surface (feed, terminal, tmux, cloud).
- *   - The first answer wins: `recordAnswer` atomically checks an answered
- *     marker so exactly one surface can claim the block.
- *   - Answered blocks stay visible until the agent consumes the message and
- *     continues, so the UI can show delivered/consumed/continued receipts.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -30,42 +7,15 @@ import { getFeedDir, getUserAgentsDir } from '../state.js';
 import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from '../operator.js';
 import { projectKeyFromCwd } from '../project-key.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
-/**
- * Whether a receipt describes THIS ask.
- *
- * Identity is the GENERATION alone, never the attempt. The question is "does
- * this receipt answer this ask?", and a second attempt on the same ask carries
- * the same answer -- so a stranded claim that is adopted (which necessarily
- * mints a new attempt) must still recognise the message its predecessor queued,
- * or it enqueues a duplicate. `attempt` rides along as provenance for the
- * delivery check, not as part of identity.
- *
- * An UNBOUND receipt (written before these fields existed) matches NOTHING: it
- * cannot name an ask, so attributing it to one would let a message queued for an
- * earlier question resolve whichever question is current (PHNX-3999).
- */
 export function receiptMatchesOrigin(receipt, origin) {
     if (receipt.generation === undefined)
         return false;
     return receipt.generation === origin.generation;
 }
 function resolutionDir(root) { return path.join(root, 'resolutions'); }
-/**
- * Canonical generation for a block. A writer that stamped `generation` wins;
- * otherwise the publish timestamp `ts` is the generation, because the feed
- * rewrites `ts` only when a NEW question replaces the old one (an answer/continue
- * update to the same block keeps `ts`). So `ts` changes exactly when the ask
- * changes — which is what a generation must track.
- */
 export function blockGeneration(block) {
     return block.generation ?? block.ts;
 }
-/**
- * Canonical source for a block. A writer that stamped `source` wins; otherwise it
- * is derived from `kind`: a declared block is `declared`, a synthetic control card
- * is `system`, everything else (question / notification, written by a harness hook)
- * is `hook`.
- */
 export function blockSource(block) {
     if (block.source)
         return block.source;
@@ -75,13 +25,6 @@ export function blockSource(block) {
         default: return 'hook';
     }
 }
-/**
- * Canonical lifecycle state for a block. A writer that stamped `state` wins;
- * otherwise it is derived from the markers already on the block: `continuedAt`
- * means `continued`, a recorded `answer` means `answered`, and anything else is
- * still `open`. This is the ONE place that turns the historical marker fields into
- * the lifecycle axis, so no consumer re-derives it and drifts.
- */
 export function deriveBlockState(block) {
     if (block.state)
         return block.state;
@@ -91,24 +34,14 @@ export function deriveBlockState(block) {
         return 'answered';
     return 'open';
 }
-/**
- * Record a resolution tombstone (latest-wins per block id). Called from the
- * answer / continue / clear paths BEFORE the open-block view is removed, so the
- * reconciler always has the tombstone by the time the block file is gone.
- */
 export function recordResolution(resolution, root) {
     const dir = resolutionDir(root ?? getFeedDir());
     ensureDir(dir);
     atomicWriteJsonSync(path.join(dir, `${resolution.blockId}.json`), resolution);
 }
-/** Read the latest resolution tombstone for a block, if one exists. */
 export function readResolution(blockId, root) {
     return safeReadJson(path.join(resolutionDir(root ?? getFeedDir()), `${blockId}.json`));
 }
-/**
- * Stable block id for a session. One block per session -- a new question
- * replaces the previous one (the agent can only ask one question at a time).
- */
 export function blockIdForSession(sessionId) {
     const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '-');
     return `block-${safeSessionId}`;
@@ -133,28 +66,17 @@ function safeReadJson(file) {
         return undefined;
     }
 }
-/** Read one block record. Returns undefined when missing or corrupt. */
 export function readBlock(blockId, root) {
     const parsed = safeReadJson(blockPath(root ?? getFeedDir(), blockId));
     if (!parsed || !parsed.blockId || !parsed.sessionId || !parsed.questions?.length)
         return undefined;
     return parsed;
 }
-/**
- * Atomically claim the first answer for a block. Returns `{ ok: true }` when
- * this call is the first to answer; returns `{ ok: false, existing }` when a
- * different surface already answered the block. The marker file is created
- * with `O_EXCL` so two concurrent claimers cannot both succeed.
- *
- * High-consequence blocks require a verified operator identity. Unverified
- * answers (no operatorId or not in the registry/allowed list) are refused.
- */
 export function recordAnswer(blockId, answer, root, options = {}) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
     const operatorId = answer.operatorId;
     if (block?.consequence && block.consequence !== 'normal') {
-        // Operators live in ~/.agents/operators.yaml — never the feed store root.
         if (!operatorId || answer.verified !== true || !isKnownOperator(operatorId)) {
             return {
                 ok: false,
@@ -188,7 +110,6 @@ export function recordAnswer(blockId, answer, root, options = {}) {
         operatorId: answer.operatorId,
         verified: answer.verified,
     };
-    // Try to create the answered marker atomically.
     try {
         const fd = fs.openSync(marker, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
         try {
@@ -207,21 +128,6 @@ export function recordAnswer(blockId, answer, root, options = {}) {
         }
         throw err;
     }
-    // Marker created successfully -- mirror the answer into the block file.
-    //
-    // A `pending` claim stops there: the claim is recorded so no second surface
-    // can take it, but the generation is NOT resolved and the lifecycle stays
-    // `open`, so the card remains in the operator's feed until a rail reports a
-    // real receipt (`confirmAnswerResolution`). A claim is not a delivery, and a
-    // claim whose delivery is never confirmed must not silently remove the item
-    // (PHNX-3999). `state` wins over `answer` in `deriveBlockState`, so the
-    // explicit `open` is what keeps the claimed block visible.
-    //
-    // The default one-phase path advances straight to `answered` for surfaces
-    // that resolve atomically (a policy default, a synchronous enqueue). The
-    // resolution tombstone is written first, so if a stale lifecycle re-read races
-    // the block-file update the reconciler already refuses to resurrect this
-    // generation.
     if (block) {
         if (!options.pending) {
             recordResolution({
@@ -238,29 +144,12 @@ export function recordAnswer(blockId, answer, root, options = {}) {
     }
     return { ok: true };
 }
-/**
- * Promote a pending claim to a resolved answer — the second half of the
- * two-phase answer protocol (see `recordAnswer`'s `pending` option).
- *
- * Called only once a rail has reported a real {@link MessageReceipt}: that is
- * the point the item stops needing a human, so that is the point the tombstone
- * is written and the card may leave the feed. An unconfirmed delivery never
- * reaches here, so its card stays up.
- */
 export function confirmAnswerResolution(blockId, root, expected) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
     const record = getAnswerRecord(blockId, dir);
     if (!block || !record)
         return false;
-    // One block id serves every generation of a session's asks, so a slow
-    // delivery for the PREVIOUS question must not resolve the one the agent has
-    // moved on to. A caller that knows which ask and which attempt it is
-    // confirming says so, and a mismatch is a no-op rather than a wrong tombstone.
-    // Bound to the ASK. The attempt is deliberately NOT compared: adopting a
-    // stranded claim mints a new attempt for the same question, and that adoption
-    // must still be able to resolve the ask it completed. The generation is what
-    // distinguishes one question from the next, which is the actual hazard.
     if (expected && blockGeneration(block) !== expected.generation)
         return false;
     recordResolution({
@@ -275,28 +164,15 @@ export function confirmAnswerResolution(blockId, root, expected) {
     publishBlock(block, dir);
     return true;
 }
-/** Read the answer record for a block, if one exists. */
 export function getAnswerRecord(blockId, root) {
     return safeReadJson(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
 }
-/**
- * Release one specific answer claim after its reply rail failed. The compare on
- * `answeredAt` makes this a conditional rollback: it can never erase a newer
- * claimant. The caller supplies the exact pre-claim block/resolution snapshots,
- * restoring the attention lifecycle to the state another surface observed.
- */
 export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previousResolution, root) {
     const dir = root ?? getFeedDir();
     const marker = path.join(answeredDir(dir), `${blockId}.json`);
     const current = safeReadJson(marker);
     if (!current || current.answeredAt !== answeredAt)
         return false;
-    // Read-compare-then-unlink is NOT atomic, and two callers releasing the SAME
-    // claim is a real interleaving: both pass the compare, the first unlinks and
-    // re-claims, then the second unlinks the FIRST'S fresh marker and both end up
-    // holding a claim. The release is therefore gated on an O_EXCL token keyed by
-    // the exact claim being released -- the same primitive `recordAnswer` uses, so
-    // exactly one caller can ever release a given `answeredAt` (PHNX-3999).
     const release = path.join(answeredDir(dir), `${blockId}.${answeredAt.replace(/[^0-9A-Za-z]/g, '')}.release`);
     if (!acquireReleaseToken(release))
         return false;
@@ -309,16 +185,11 @@ export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previous
                 throw error;
         }
     };
-    // Re-read INSIDE the token: a racer that released-and-re-claimed between our
-    // first read and the token acquisition would otherwise be clobbered.
     const held = safeReadJson(marker);
     if (!held || held.answeredAt !== answeredAt) {
         dropToken();
         return false;
     }
-    // Restore while the O_EXCL marker still excludes every other claimant. The
-    // marker is removed LAST; once another writer can win recordAnswer, this
-    // rollback has no state left to overwrite.
     publishBlock(previousBlock, dir);
     const resolutionFile = path.join(resolutionDir(dir), `${blockId}.json`);
     if (previousResolution)
@@ -339,38 +210,17 @@ export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previous
         if (error.code !== 'ENOENT')
             throw error;
     }
-    // The token has done its job: this exact claim can never be released again,
-    // because the claim it names no longer exists. Leaving it would accumulate one
-    // dead file per released claim forever.
     dropToken();
     return true;
 }
-/**
- * How long a release token may sit before it is treated as abandoned. A release
- * is a handful of synchronous file operations, so anything this old belongs to a
- * process that died holding it.
- */
 export const RELEASE_TOKEN_STALE_MS = 60_000;
-/**
- * Take the O_EXCL token that serialises releasing one specific claim.
- *
- * The token MUST be recoverable: a process killed between creating it and
- * finishing would otherwise wedge that claim forever, and "the answer can never
- * be released again" is a worse failure than the race the token prevents. So the
- * token records its owner and its age, and a token whose owner is provably gone
- * (same host, no such pid) or which is simply stale is reclaimed once.
- */
 function acquireReleaseToken(release) {
     const mine = { pid: process.pid, host: os.hostname(), at: Date.now() };
     const create = () => {
+        const staged = `${release}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
         try {
-            const fd = fs.openSync(release, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
-            try {
-                fs.writeSync(fd, Buffer.from(JSON.stringify(mine), 'utf-8'));
-            }
-            finally {
-                fs.closeSync(fd);
-            }
+            fs.writeFileSync(staged, JSON.stringify(mine), { mode: 0o644 });
+            fs.linkSync(staged, release);
             return true;
         }
         catch (error) {
@@ -378,14 +228,28 @@ function acquireReleaseToken(release) {
                 return false;
             throw error;
         }
+        finally {
+            fs.rmSync(staged, { force: true });
+        }
     };
     if (create())
         return true;
     const held = safeReadJson(release);
-    const ageMs = held?.at ? Date.now() - held.at : Number.POSITIVE_INFINITY;
+    let ageMs;
+    if (held?.at)
+        ageMs = Date.now() - held.at;
+    else {
+        try {
+            ageMs = Date.now() - fs.statSync(release).mtimeMs;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return create();
+            throw error;
+        }
+    }
     let ownerGone = false;
     if (held?.host === mine.host && typeof held.pid === 'number') {
-        // Signal 0 probes liveness without delivering anything.
         try {
             process.kill(held.pid, 0);
         }
@@ -394,7 +258,7 @@ function acquireReleaseToken(release) {
         }
     }
     if (!ownerGone && ageMs < RELEASE_TOKEN_STALE_MS)
-        return false; // a live peer owns it
+        return false;
     try {
         fs.unlinkSync(release);
     }
@@ -402,14 +266,11 @@ function acquireReleaseToken(release) {
         if (error.code !== 'ENOENT')
             throw error;
     }
-    // Exactly one reclaimer wins the re-create; the rest see EEXIST and back off.
     return create();
 }
-/** True when the block has already been answered. */
 export function isBlockAnswered(blockId, root) {
     return fs.existsSync(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
 }
-/** Receipt lifecycle rank — higher means further along; never regress. */
 const RECEIPT_STATUS_RANK = {
     queued: 0,
     consumed: 1,
@@ -417,12 +278,6 @@ const RECEIPT_STATUS_RANK = {
     dropped: 3,
     expired: 3,
 };
-/**
- * Record a delivery-receipt transition for a message tied to a block.
- * Updates the receipts list in the block file. Status is monotonic
- * (queued → consumed → continued): a late `queued` write cannot overwrite
- * an already-recorded `consumed`/`continued` (race with mailbox drain).
- */
 export function recordMessageReceipt(blockId, receipt, root) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
@@ -433,7 +288,7 @@ export function recordMessageReceipt(blockId, receipt, root) {
     if (idx >= 0) {
         const prev = receipts[idx];
         if (RECEIPT_STATUS_RANK[receipt.status] < RECEIPT_STATUS_RANK[prev.status]) {
-            return; // do not regress
+            return;
         }
         receipts[idx] = receipt;
     }
@@ -442,21 +297,6 @@ export function recordMessageReceipt(blockId, receipt, root) {
     }
     block.receipts = receipts;
     publishBlock(block, dir);
-    // The AGENT's own acknowledgement is what resolves a pending claim: `queued`
-    // only says a rail took the answer, so it must never remove the card
-    // (PHNX-3999).
-    //
-    // The promotion is bound to the RECEIPT's own origin, not to whatever the
-    // block happens to hold now. Checking `block.answer` alone was not enough: if
-    // the agent moved to question N+1 AND that ask was itself claimed, a late
-    // acknowledgement for question N found a live claim and resolved the wrong
-    // question. `confirmAnswerResolution`'s own compare is what rejects it.
-    //
-    // An UNBOUND receipt never resolves. It cannot say which ask it acknowledges,
-    // so promoting it against whatever claim happens to be live would resolve the
-    // wrong question -- the exact failure this binding exists to prevent. Its
-    // delivery evidence is still recorded above; the card then clears through the
-    // ordinary session-advance path instead.
     if ((receipt.status === 'consumed' || receipt.status === 'continued')
         && receipt.generation !== undefined && block.answer) {
         confirmAnswerResolution(blockId, dir, {
@@ -464,23 +304,11 @@ export function recordMessageReceipt(blockId, receipt, root) {
         });
     }
 }
-/** Read the receipt list for a block. */
 export function getBlockReceipts(blockId, root) {
     return readBlock(blockId, root)?.receipts ?? [];
 }
-/**
- * The furthest-along receipt recorded for a block, or undefined when no rail
- * ever reported one. This is the ONLY truthful evidence that an answer reached
- * a delivery rail: an answer marker alone proves a claim was taken, not that
- * anything was delivered, so a caller reporting on a block it did not deliver
- * must read this rather than synthesize a receipt (PHNX-3999).
- */
 export function latestMessageReceipt(blockId, root, origin) {
     const all = getBlockReceipts(blockId, root);
-    // A block id is per SESSION, so its receipt list accumulates across every
-    // generation of that session's asks. Reading it unfiltered lets question N's
-    // receipt answer for question N+1 -- so a caller that knows which ask it is
-    // asking about passes the origin and sees only that ask's evidence.
     const receipts = origin ? all.filter((receipt) => receiptMatchesOrigin(receipt, origin)) : all;
     let best;
     for (const receipt of receipts) {
@@ -494,7 +322,6 @@ export function latestMessageReceipt(blockId, root, origin) {
     }
     return best;
 }
-/** Mark a block as "continued" -- the agent consumed the answer and moved on. */
 export function recordContinued(blockId, root) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
@@ -512,7 +339,6 @@ export function recordContinued(blockId, root) {
     }, dir);
     publishBlock(block, dir);
 }
-/** Mark a decision-class block as hard-parked (no safe default existed). */
 export function recordParked(blockId, root) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
@@ -521,7 +347,6 @@ export function recordParked(blockId, root) {
     block.parkedAt = new Date().toISOString();
     publishBlock(block, dir);
 }
-/** Mark that the approval safe-default was applied by policy. */
 export function recordDefaulted(blockId, root) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
@@ -530,7 +355,6 @@ export function recordDefaulted(blockId, root) {
     block.defaultedAt = new Date().toISOString();
     publishBlock(block, dir);
 }
-/** Mark that an urgent block was paged to the phone. */
 export function recordNotified(blockId, root) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
@@ -539,7 +363,6 @@ export function recordNotified(blockId, root) {
     block.notifiedAt = new Date().toISOString();
     publishBlock(block, dir);
 }
-/** Remove answered marker and receipts for a block (used by block removal/GC). */
 function clearBlockLifecycle(blockId, root) {
     const dir = root ?? getFeedDir();
     for (const sub of [answeredDir(dir), receiptDir(dir)]) {
@@ -547,27 +370,9 @@ function clearBlockLifecycle(blockId, root) {
             fs.unlinkSync(path.join(sub, `${blockId}.json`));
         }
         catch {
-            // ignore missing
         }
     }
 }
-/**
- * Build the block record for `agents feed post --blocked` — pure, so the shape is testable
- * without touching the store or the broadcast layer.
- *
- * Class is derived, not asked for: a `--default` means the user could be absent
- * and policy could still resolve it (approval); no default means only a human can
- * choose (decision). `feed-policy.ts` reads exactly that distinction, so deriving
- * it here keeps one rule in one place instead of letting a caller set a class that
- * contradicts its own safeDefault.
- *
- * `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, ' ');
     if (!text) {
@@ -586,14 +391,9 @@ export function buildDeclaredBlock(agent, input) {
         host: agent.host,
         runtime: agent.runtime,
         ts,
-        // A declared block is an explicit, agent-raised attention record: it opens the
-        // lifecycle here, sourced `declared`, with `ts` as its generation so a later
-        // `--blocked` in the same session mints a fresh generation past any tombstone.
         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 } : {}) }],
@@ -604,14 +404,12 @@ export function buildDeclaredBlock(agent, input) {
         ...(input.timeoutMinutes !== undefined ? { timeoutMinutes: input.timeoutMinutes } : {}),
     };
 }
-/** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export function publishBlock(block, root) {
     const dir = root ?? getFeedDir();
     fs.mkdirSync(dir, { recursive: true });
     const target = blockPath(dir, block.blockId);
     atomicWriteJsonSync(target, block);
 }
-/** Read all block records. Returns them sorted by stable block filename. */
 export function listBlocks(root) {
     const dir = root ?? getFeedDir();
     let names;
@@ -631,12 +429,10 @@ export function listBlocks(root) {
             }
         }
         catch {
-            // skip corrupt / partial files
         }
     }
     return blocks;
 }
-/** Read per-session ask history written by the feed publish hook. */
 export function listAskStats(root) {
     const dir = askStatsDir(root ?? getFeedDir());
     let names;
@@ -662,15 +458,8 @@ export function listAskStats(root) {
     }
     return stats;
 }
-/** Remove a block record and its lifecycle sidecars. Returns true if the file was deleted. */
 export function removeBlock(blockId, root) {
     const dir = root ?? getFeedDir();
-    // Record a resolution tombstone BEFORE the block file and answered marker are
-    // gone, so a stale lifecycle re-read of the same session cannot resurrect this
-    // cleared generation. The reason names how it closed: an answered marker means
-    // the operator answered, `continuedAt` means the agent moved on, otherwise the
-    // transcript advanced past it (a Stop/PostToolUse clear). The tombstone itself
-    // is deliberately NOT cleared — it must outlive the block to do its job.
     const block = readBlock(blockId, dir);
     if (block) {
         const reason = isBlockAnswered(blockId, dir)
@@ -693,14 +482,6 @@ export function removeBlock(blockId, root) {
         return false;
     }
 }
-// ---------------------------------------------------------------------------
-// Hook installation
-// ---------------------------------------------------------------------------
-/**
- * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
- * 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 const FEED_PUBLISH_HOOK_SCRIPT = `#!/usr/bin/env python3
 """Publish and clear open-block records for \`agents feed\`.
 
@@ -723,10 +504,6 @@ import socket
 import tempfile
 from datetime import datetime, timezone
 
-# Notification subtypes that mean something is PENDING. Claude's idle_prompt is
-# deliberately absent: it fires a minute after the turn ended with the operator
-# idle, which is a finished turn, not a request -- publishing it put an
-# Approve/Deny banner on a session that had already answered "pong" (PHNX-3999).
 WAITING_NOTIFICATION_TYPES = {
     "permission_prompt",
     "elicitation_dialog",
@@ -736,10 +513,6 @@ CLEAR_EVENTS = {
     "Stop",
     "SessionEnd",
 }
-# Codex emits a PermissionRequest event (not Claude's Notification) when it
-# blocks on an approval prompt. Claude never fires PermissionRequest, so the
-# same script handles both: PermissionRequest maps to an approval-class block
-# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.
 
 
 def read_json(path):
@@ -790,7 +563,6 @@ def main():
     except Exception:
         return
 
-    # Sub-agent gate.
     if payload.get("agent_type"):
         return
 
@@ -808,30 +580,16 @@ def main():
     hook_event = payload.get("hook_event_name", "PreToolUse")
 
     if hook_event in CLEAR_EVENTS:
-        # A declared block (\`agents feed post --blocked\`) is the agent explicitly
-        # saying it is stuck. Unlike a question/notification/approval block -- which
-        # tracks an in-flight harness prompt that a lifecycle event resolves -- a
-        # declared block stays open until it is actually ANSWERED. So while it is
-        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:
-        # otherwise the needs-you record vanishes the moment the agent parks the block
-        # and its turn ends -- exactly when the owner still needs to see and answer it.
-        # Once it IS answered (an answered marker exists), it clears like any other
-        # block by falling through below -- which frees that marker too, so a later
-        # \`--blocked\` in the same session is not falsely locked as already-answered
-        # (recordAnswer creates the marker with O_EXCL).
         try:
             with open(target) as existing_file:
                 existing = json.load(existing_file)
             answered = os.path.exists(os.path.join(answered_dir, f"{block_id}.json"))
+
+            # Ordinary lifecycle hooks cannot clear a declared block before it is answered.
             if existing.get("kind") == "declared" and not answered:
                 return
         except Exception:
             pass
-        # A matcher-less PostToolUse clear (registered for Codex so an approved
-        # tool clears its approval card) must NOT wipe an open AskUserQuestion
-        # while an unrelated tool runs mid-question -- those are cleared only by
-        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a
-        # 'question' block; approval/notification blocks clear once the tool runs.
         if hook_event == "PostToolUse":
             try:
                 with open(target) as existing_file:
@@ -846,8 +604,6 @@ def main():
             pass
         except Exception:
             pass
-        # Also clear the answered marker so a future question for this session
-        # is not permanently locked.
         try:
             os.unlink(os.path.join(answered_dir, f"{block_id}.json"))
         except FileNotFoundError:
@@ -856,11 +612,6 @@ def main():
             pass
         return
 
-    # 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")
@@ -877,8 +628,6 @@ 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")
@@ -896,7 +645,6 @@ def main():
                     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)
         except FileNotFoundError:
@@ -911,10 +659,6 @@ def main():
         notification_type = payload.get("notification_type", "")
         if notification_type not in WAITING_NOTIFICATION_TYPES:
             return
-        # Claude emits a generic permission notification after presenting an
-        # AskUserQuestion. Keep the structured questions and options already
-        # published for this session instead of replacing them with that less
-        # useful notification text.
         try:
             with open(target) as existing_file:
                 existing = json.load(existing_file)
@@ -932,12 +676,6 @@ def main():
         }]
         kind = "notification"
     elif hook_event == "PermissionRequest":
-        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,
-        # 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 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", {})
         command = ""
@@ -985,7 +723,6 @@ def main():
             return
         kind = "question"
 
-    # Identity from env (set by agents-cli at spawn).
     mailbox_id = os.path.basename(
         os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
     ) or session_id
@@ -999,8 +736,6 @@ def main():
     if not isinstance(recent, list):
         recent = []
     recent.append(now_iso)
-    # Keep enough history for rolling one-hour needy detection without unbounded
-    # per-session files. The TypeScript reader applies the exact time window.
     recent = recent[-200:]
     write_json(stats_path, {
         "sessionId": session_id,
@@ -1026,8 +761,6 @@ 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,
@@ -1037,20 +770,11 @@ def main():
     if notification_type:
         block["notificationType"] = notification_type
 
-    # A Codex PermissionRequest is a real approval gate: mark it approval-class
-    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent
-    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default
-    # 'medium') and pages the phone. A plain 'deny' is the safe default.
     if codex_approval:
         block["blockClass"] = "approval"
         block["costOfDelay"] = "high"
         block["safeDefault"] = "deny"
 
-    # Optional multi-operator control metadata passed by the agent in the
-    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex
-    # PermissionRequest carries tool ARGS in tool_input (command/path), not
-    # operator controls, so it is excluded here -- its class/cost is stamped
-    # above from codex_approval.
     controls = payload.get("tool_input", {}) if hook_event not in ("Notification", "PermissionRequest") else {}
     block_class = controls.get("blockClass") if isinstance(controls, dict) else None
     if block_class in ("approval", "decision"):
@@ -1071,8 +795,6 @@ def main():
     if cost in ("low", "medium", "high"):
         block["costOfDelay"] = cost
 
-    # Publishing a new question clears any stale answered marker from the
-    # previous question in this session.
     try:
         os.unlink(os.path.join(answered_dir, f"{block_id}.json"))
     except FileNotFoundError:
@@ -1080,9 +802,6 @@ def main():
     except Exception:
         pass
 
-    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a
-    # HOME override on every platform. Use the same anchor so hooks and the CLI
-    # always read/write one feed store (including temp-home and sandbox runs).
     os.makedirs(feed_dir, exist_ok=True)
 
     fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=".tmp")
@@ -1101,14 +820,8 @@ if __name__ == "__main__":
     try:
         main()
     except Exception:
-        pass  # fail open
+        pass
 `;
-/**
- * Install the feed-publish hook script into the user hooks dir and add its
- * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
- * read-only mirror, so runtime-managed hooks must never write there.
- * Idempotent -- skips if the script is already present and up to date.
- */
 export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
     try {
         const hooksDir = path.join(userAgentsDir, 'hooks');
@@ -1136,9 +849,6 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
                 script: '10-feed-publish.py',
                 timeout: 5,
             },
-            // idle_prompt is not matched: an idle reminder is a finished turn, not a
-            // pending request (PHNX-3999). An installed agents.yaml that still carries
-            // the old matcher is harmless -- the script drops the subtype itself.
             'feed-publish-notification': {
                 agents: ['claude', 'codex'],
                 events: ['Notification'],
@@ -1146,8 +856,6 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
                 script: '10-feed-publish.py',
                 timeout: 5,
             },
-            // Codex-specific approval gate: Codex emits PermissionRequest (Claude does
-            // not), so this hook is where a blocked Codex agent surfaces to the feed.
             'feed-publish-permission': {
                 agents: ['claude', 'codex'],
                 events: ['PermissionRequest'],
@@ -1161,15 +869,6 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
                 script: '10-feed-publish.py',
                 timeout: 5,
             },
-            // Matcher-less PostToolUse clear: after Codex runs an approved tool, the
-            // approval card is stale, so clear it. Codex-only on purpose -- Claude
-            // never fires PermissionRequest, so it has no approval card to clear here,
-            // and a matcher-less PostToolUse for Claude would (1) re-run the script on
-            // every tool completion and (2) wipe Claude's notification-kind blocks
-            // (permission_prompt/elicitation_dialog) the moment any later
-            // tool runs, instead of letting them persist to Stop/SessionEnd like they
-            // did before RUSH-2039. Registering it for codex alone keeps Claude's
-            // card lifetime exactly as it was.
             'feed-clear-permission': {
                 agents: ['codex'],
                 events: ['PostToolUse'],
@@ -1191,15 +890,6 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
         }
         if (installed) {
             const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
-            // `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);
         }