@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/answer-router.js

@@ -1,24 +1,7 @@
-/**
- * Parked-agent answer router (RUSH-1474).
- *
- * `agents message` historically only enqueued into the mailbox (delivered at the
- * next PreToolUse). That steers a *running* agent between tool calls but never
- * unblocks a *parked* agent:
- *   - interactive TUI open on AskUserQuestion (needs keystrokes, not context)
- *   - headless run waiting on input (no next tool call; needs resume)
- *
- * This module picks the delivery mechanism from (open feed block × session
- * liveness × runtime rail). Pure — unit-testable without a live terminal.
- */
 import { deriveBlockState } from './feed/feed.js';
 import { addressabilityRecoveryHint } from './terminal/resolve.js';
 import { injectTargetFromReplyRail } from './session/inject.js';
-/** The Escape keystroke as its raw control byte — what a tmux/iterm rail reads as a real Escape. */
 const ESCAPE_KEY = '\u001b';
-/**
- * Match free-text answer against question options.
- * Exact (case-insensitive) > startsWith > includes. Returns 0-based index or -1.
- */
 export function matchOptionIndex(answer, options) {
     if (!options?.length)
         return -1;
@@ -35,36 +18,22 @@ export function matchOptionIndex(answer, options) {
     const includes = labels.findIndex((l) => l.toLowerCase().includes(needle));
     return includes;
 }
-/**
- * Build the keystroke payload that closes an AskUserQuestion TUI.
- * Numbered options are selected by digit (1-based) + Enter. Free text with an
- * "Other" option selects Other then types; without Other, types the answer.
- */
 export function keystrokesForAnswer(answer, options) {
     const idx = matchOptionIndex(answer, options);
     if (idx >= 0) {
-        // AskUserQuestion / plan select-lists are 1-indexed digits.
         return { payload: `${idx + 1}`, matched: 'option' };
     }
-    // A symbolic cancel token — the `esc` deliveryKey a deny / send-back choice
-    // carries — is the Escape KEY, not the letters "esc". Send the ESC control
-    // byte (a real cancel on every raw tmux/iterm rail) and suppress the
-    // trailing Enter, so the prompt is dismissed rather than confirmed by a stray
-    // newline. Runs after the option match so an option literally labelled "esc"
-    // still wins as a selection.
     if (/^(?:esc|escape)$/i.test(answer.trim())) {
         return { payload: ESCAPE_KEY, matched: 'other', enter: false };
     }
     if (options?.length) {
         const otherIdx = options.findIndex((o) => /^other$/i.test((o.label ?? '').trim()));
         if (otherIdx >= 0) {
-            // Select Other, then type the free text on the next field.
             return { payload: `${otherIdx + 1}\n${answer}`, matched: 'other' };
         }
     }
     return { payload: answer, matched: 'free-text' };
 }
-/** True when the session is waiting on user input (parked on a question/plan). */
 export function isParkedOnInput(session) {
     if (!session)
         return false;
@@ -77,16 +46,6 @@ export function isParkedOnInput(session) {
     }
     return false;
 }
-/**
- * True when an open feed block still needs an answer.
- *
- * Openness comes from {@link deriveBlockState}, not from `block.answer` being
- * truthy: a PENDING claim records the answer while deliberately leaving the
- * block `open` (feed.ts `recordAnswer`'s two-phase mode), so reading the field
- * directly would call a claimed-but-undelivered block "closed" — and a retry of
- * a stranded claim would then re-route a parked headless agent to the mailbox it
- * will never drain (PHNX-3999).
- */
 export function isOpenQuestionBlock(block) {
     if (!block)
         return false;
@@ -104,20 +63,10 @@ function injectTargetForSession(session) {
     }
     return null;
 }
-/**
- * Pick the delivery mechanism for one answer.
- *
- * Precedence:
- *   1. Parked on open question + injectable rail (tmux/iterm) → keystroke
- *   2. Parked on open question + headless (no rail) → resume with answer
- *   3. Parked on open question + no rail + interactive → refuse (don't mailbox-drop)
- *   4. Otherwise → mailbox (running agent between tool calls)
- */
 export function resolveAnswerRoute(input) {
     const { answer, block, session } = input;
     const openQ = isOpenQuestionBlock(block);
     const parked = isParkedOnInput(session);
-    // Options from the first question on the block (or the session's structured question).
     const options = block?.questions?.[0]?.options ??
         session?.question?.options?.map((o) => ({ label: o.label }));
     if (openQ && parked && session) {
@@ -135,7 +84,6 @@ export function resolveAnswerRoute(input) {
                 ...(enter === false ? { enter: false } : {}),
             };
         }
-        // Headless / no rail: re-enter via resume.
         if (session.context === 'headless' || session.context === 'teams' || !session.tty) {
             const sid = session.sessionId ?? input.mailboxId;
             if (!sid) {
@@ -157,8 +105,6 @@ export function resolveAnswerRoute(input) {
                 addressabilityRecoveryHint(session),
         };
     }
-    // Open block but agent is still looping between tool calls — mailbox is correct.
-    // No block — free-form mid-flight steer — mailbox.
     return {
         kind: 'mailbox',
         reason: openQ
@@ -167,14 +113,11 @@ export function resolveAnswerRoute(input) {
         payload: answer,
     };
 }
-/** Build argv for a headless resume that continues with the answer text. */
 export function resumeArgv(route) {
     if (route.kind !== 'resume' || !route.resume) {
         throw new Error('resumeArgv requires a resume route');
     }
     const { agent, sessionId } = route.resume;
     const text = route.payload ?? '';
-    // `agents run <agent> --resume <id> -- <answer>` — the trailing prompt is the
-    // next user turn after native resume (claude/codex) or /continue replay.
     return ['run', agent, '--resume', sessionId, '--', text];
 }

package/dist/lib/app-bundle-install.d.ts

@@ -1,17 +1,4 @@
-/**
- * Copy an `.app` bundle to `dest` atomically. Stages into a sibling dir, then
- * swaps with renames — the window where `dest` is absent shrinks from the
- * seconds-long `cp` to a single microsecond rename, and a failed copy leaves the
- * existing bundle untouched. Serialize concurrent callers with {@link withInstallLock}
- * so the two-step swap never races another swap.
- */
 export declare function copyAppBundle(src: string, dest: string, io?: {
     renameSync?: (from: string, to: string) => void;
 }): void;
-/**
- * Serialize installs across the many concurrent `agents` invocations that pass
- * through the helper-install path, so a burst copies once instead of stampeding
- * the atomic swap. Locks a sentinel file beside the bundle (the bundle itself may
- * not exist yet on first install) via the shared {@link withFileLock}.
- */
 export declare function withInstallLock(dest: string, fn: (heartbeat: () => void) => void): void;

package/dist/lib/app-bundle-install.js

@@ -1,41 +1,9 @@
-/**
- * Atomic, serialized install of a macOS `.app` bundle to a stable user path.
- *
- * Used by the menu-bar helper (`lib/menubar/install-menubar.ts`), which is
- * (re)installed on the hot path of ordinary `agents` invocations. (A second
- * helper this module used to also serve, the secrets keychain broker, moved
- * out of this repo entirely with the standalone `secrets` engine —
- * PHNX-3989 — and installs itself now.) It previously did a non-atomic
- * `rm -rf dest` + `cp -R src dest` straight onto the live bundle. That copy takes
- * long enough that a concurrent reader (Gatekeeper, or an exec of the bundle) sees
- * a half-written `.app` — a truncated Mach-O / mismatched `_CodeSignature` hash —
- * which macOS reports as **"is damaged and can't be opened."** On a busy box dozens
- * of concurrent invocations raced the same path, so the dialog fired intermittently.
- *
- * {@link copyAppBundle} stages the copy in a sibling directory and swaps it into
- * place with renames, so a reader sees either the old or the new complete bundle,
- * never a half-written one — the only moment `dest` is briefly absent is the
- * sub-millisecond gap between the two renames (vs the seconds-long `cp`), and a
- * failed copy never touches the live bundle. {@link withInstallLock} serializes concurrent
- * installers (via the shared `withFileLock`) so a burst of invocations installs
- * once instead of stampeding.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { withFileLock, ensureLockTarget } from './fs-atomic.js';
-// A helper `cp -R` under load can take a few seconds; the lock must outlast it so
-// a peer never treats a live installer as crashed and interleaves a second swap.
-// (fs-atomic's 5s default is tuned for sub-second read-modify-writes.)
 const INSTALL_LOCK_STALE_MS = 60_000;
 const INSTALL_LOCK_ACQUIRE_TIMEOUT_MS = 60_000;
-/**
- * Copy an `.app` bundle to `dest` atomically. Stages into a sibling dir, then
- * swaps with renames — the window where `dest` is absent shrinks from the
- * seconds-long `cp` to a single microsecond rename, and a failed copy leaves the
- * existing bundle untouched. Serialize concurrent callers with {@link withInstallLock}
- * so the two-step swap never races another swap.
- */
 export function copyAppBundle(src, dest, io = {}) {
     const rename = io.renameSync ?? fs.renameSync;
     fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -43,18 +11,12 @@ export function copyAppBundle(src, dest, io = {}) {
     const backup = `${dest}.replaced.${process.pid}`;
     fs.rmSync(staging, { recursive: true, force: true });
     fs.rmSync(backup, { recursive: true, force: true });
-    // `cp -R` preserves the bundle's signature, symlinks, and resource forks;
-    // `fs.cpSync({recursive:true})` has historically mishandled xattrs on `.app`
-    // bundles, breaking codesign.
     const r = spawnSync('cp', ['-R', src, staging], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
     if (r.status !== 0) {
         fs.rmSync(staging, { recursive: true, force: true });
         const msg = (r.stderr || r.stdout || '').toString().trim();
         throw new Error(`Failed to copy ${src} -> ${staging}: ${msg || 'unknown error'}`);
     }
-    // rename(2) cannot replace a non-empty directory, so move the current bundle
-    // aside, then move staging into place. If the second rename fails, restore the
-    // backup so `dest` is never left missing.
     try {
         if (fs.existsSync(dest))
             rename(dest, backup);
@@ -66,7 +28,6 @@ export function copyAppBundle(src, dest, io = {}) {
                 rename(backup, dest);
             }
             catch {
-                /* best-effort restore */
             }
         }
         fs.rmSync(staging, { recursive: true, force: true });
@@ -74,20 +35,9 @@ export function copyAppBundle(src, dest, io = {}) {
     }
     fs.rmSync(backup, { recursive: true, force: true });
 }
-/**
- * Serialize installs across the many concurrent `agents` invocations that pass
- * through the helper-install path, so a burst copies once instead of stampeding
- * the atomic swap. Locks a sentinel file beside the bundle (the bundle itself may
- * not exist yet on first install) via the shared {@link withFileLock}.
- */
 export function withInstallLock(dest, fn) {
     const lockTarget = `${dest}.install-lock`;
     ensureLockTarget(lockTarget);
-    // Pass proper-lockfile's `heartbeat` straight through: the install body is a
-    // fully SYNCHRONOUS chain of blocking `spawnSync`s (`cp -R`, then codesign /
-    // spctl), so the event loop never turns and proper-lockfile's own async mtime
-    // refresh can't fire. Callers invoke heartbeat() between those steps to keep a
-    // long hold from ageing past staleMs and being broken by a contending peer.
     withFileLock(lockTarget, (heartbeat) => fn(heartbeat), {
         staleMs: INSTALL_LOCK_STALE_MS,
         acquireTimeoutMs: INSTALL_LOCK_ACQUIRE_TIMEOUT_MS,

package/dist/lib/artifact-actions.d.ts

@@ -1,22 +1,7 @@
-/**
- * Artifact action types and validation.
- * Ported from the legacy agent CLI config helpers.
- *
- * Artifact actions map tool invocations to artifact labels, allowing agents to
- * trigger tools automatically when specific artifacts are produced.
- */
-/** A single action that binds a tool invocation to matching artifact labels. */
 export interface ArtifactAction {
     tool: string;
     label: string;
     matches?: string[];
     input?: Record<string, string>;
 }
-/**
- * Validate artifact actions configuration.
- * @param actions - List of artifact actions to validate
- * @param httpToolNames - Set of tool names defined in http_tools section
- * @param applicationTools - Set of valid application tool names
- * @returns Array of validation errors (empty if valid)
- */
 export declare function validateArtifactActions(actions: ArtifactAction[], httpToolNames: Set<string>, applicationTools: Set<string>): string[];

package/dist/lib/artifact-actions.js

@@ -1,17 +1,3 @@
-/**
- * Artifact action types and validation.
- * Ported from the legacy agent CLI config helpers.
- *
- * Artifact actions map tool invocations to artifact labels, allowing agents to
- * trigger tools automatically when specific artifacts are produced.
- */
-/**
- * Validate artifact actions configuration.
- * @param actions - List of artifact actions to validate
- * @param httpToolNames - Set of tool names defined in http_tools section
- * @param applicationTools - Set of valid application tool names
- * @returns Array of validation errors (empty if valid)
- */
 export function validateArtifactActions(actions, httpToolNames, applicationTools) {
     const errors = [];
     for (let i = 0; i < actions.length; i++) {
@@ -40,10 +26,6 @@ export function validateArtifactActions(actions, httpToolNames, applicationTools
     }
     return errors;
 }
-/**
- * Validate template string uses only allowed patterns.
- * Only allows {{artifact.X}} and {{preflight.X}} patterns.
- */
 function validateTemplate(tmpl) {
     const re = /\{\{(\w+)\.(\w+)\}\}/g;
     let match;

package/dist/lib/artifacts-client.d.ts

@@ -3,17 +3,7 @@ export declare class ArtifactsClientError extends Error {
     readonly code: 'ARTIFACTS_BIN_MISSING';
     constructor(code: 'ARTIFACTS_BIN_MISSING', message: string);
 }
-/**
- * Resolve the standalone `artifacts` executable. `ARTIFACTS_BIN` wins so a dev
- * build can be driven without touching PATH.
- *
- * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims` — the same
- * load-bearing skip the secrets/computer clients rely on, so a leftover alias
- * shim that execs back into this CLI can never be picked as the engine.
- */
 export declare function resolveArtifactsBin(): string;
-/** How to invoke the resolved binary: a `.js` entrypoint runs through this
- * runtime, a real executable is spawned directly. */
 export declare function invocation(bin: string): {
     command: string;
     prefix: string[];

package/dist/lib/artifacts-client.js

@@ -1,10 +1,3 @@
-// Thin client for the standalone `artifacts` CLI (`@phnx-labs/artifacts-cli`).
-//
-// The artifact render + share ENGINE lives in artifacts-cli, not this repo
-// (PHNX-3992, mirroring the secrets/computer extractions). agents-cli calls it
-// only where a `sessions` convenience wants to publish (`agents sessions share`).
-// A missing executable fails loud with install guidance — there is no fallback
-// to a retired in-repo engine.
 import { findInPath } from './agent-spec/agents.js';
 export const ARTIFACTS_INSTALL_HINT = 'npm i -g @phnx-labs/artifacts-cli';
 export class ArtifactsClientError extends Error {
@@ -16,14 +9,6 @@ export class ArtifactsClientError extends Error {
     }
 }
 let cachedBin = null;
-/**
- * Resolve the standalone `artifacts` executable. `ARTIFACTS_BIN` wins so a dev
- * build can be driven without touching PATH.
- *
- * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims` — the same
- * load-bearing skip the secrets/computer clients rely on, so a leftover alias
- * shim that execs back into this CLI can never be picked as the engine.
- */
 export function resolveArtifactsBin() {
     if (cachedBin)
         return cachedBin;
@@ -37,8 +22,6 @@ export function resolveArtifactsBin() {
     cachedBin = resolved;
     return resolved;
 }
-/** How to invoke the resolved binary: a `.js` entrypoint runs through this
- * runtime, a real executable is spawned directly. */
 export function invocation(bin) {
     if (/\.[mc]?js$/.test(bin))
         return { command: process.execPath, prefix: [bin] };

package/dist/lib/ask-classifier.d.ts

@@ -1,71 +1,33 @@
-/**
- * Ask classifier + stall suppression (RUSH-1477).
- *
- * ~39% of AskUserQuestion calls are workflow-stalls ("should I…?", "what's next?",
- * "merge now?"). The feed's first job is to make those disappear so real Decisions
- * and Approvals stay visible.
- *
- * Pipeline:
- *   1. Classify every block into Decision / Approval / Clarification / Stall / Fyi
- *   2. Suppress stalls (and pure FYIs) with an auto-answer so they never render
- *   3. Surface Decision + Approval (+ Clarification when it needs a real fact)
- *
- * Rules-based on stable high-volume shapes. Pure classify/match; suppression has
- * side effects via the feed store when applied.
- */
 import type { OpenBlock } from './feed/feed.js';
-/** Taxonomy for a published ask. Exactly one class per block. */
 export type AskClass = 'decision' | 'approval' | 'clarification' | 'stall' | 'fyi';
 export interface Classification {
     class: AskClass;
-    /** Why this class was chosen (rule name). */
     rule: string;
-    /** True when the feed should hide this block and auto-answer it. */
     suppress: boolean;
-    /** Auto-answer text when suppress is true. */
     autoAnswer?: string;
 }
-/**
- * Classify one ask from free text (+ optional explicit blockClass from the agent).
- * Explicit blockClass from the agent is honored as a floor: 'decision' never becomes
- * a suppressible stall (false-suppress rate ~0 for real Decisions).
- */
 export declare function classifyAsk(text: string, opts?: {
     header?: string;
     blockClass?: OpenBlock['blockClass'];
 }): Classification;
-/** Classify a full open block (all questions concatenated). */
 export declare function classifyBlock(block: OpenBlock): Classification;
 interface SuppressResult {
     blockId: string;
     class: AskClass;
     rule: string;
     autoAnswer: string;
-    /** True when the block was removed from the visible feed. */
     suppressed: boolean;
 }
-/**
- * Auto-answer + remove a suppressible block so it never renders as a card.
- * Logs the stall as answered by policy:stall-suppression.
- */
 export declare function suppressStallBlock(block: OpenBlock, root?: string, mailboxRoot?: string): SuppressResult;
 interface FeedFilterResult {
-    /** Blocks that should render as cards. */
     surfaced: OpenBlock[];
-    /** Suppression audit rows (stalls auto-resolved). */
     suppressed: SuppressResult[];
-    /** Per-class counts over the input set (before suppression). */
     counts: Record<AskClass, number>;
 }
-/**
- * Classify every block; optionally apply stall suppression (mutate store).
- * When `apply` is false, only classifies (dry run for --json audit).
- */
 export declare function filterBlocksForFeed(blocks: OpenBlock[], opts?: {
     apply?: boolean;
     root?: string;
     mailboxRoot?: string;
 }): FeedFilterResult;
-/** Human digest: "31 stalls auto-resolved by policy". */
 export declare function suppressionDigest(result: FeedFilterResult): string;
 export {};

package/dist/lib/ask-classifier.js

@@ -1,7 +1,6 @@
 import { recordAnswer, recordMessageReceipt, removeBlock } from './feed/feed.js';
 import { enqueue, mailboxDir } from './mailbox.js';
 const RULES = [
-    // FYI / done — no action needed
     {
         name: 'fyi-done',
         class: 'fyi',
@@ -10,7 +9,6 @@ const RULES = [
         test: (t) => /\b(fyi|for your information|just letting you know|heads.?up|no action needed|already done|completed successfully)\b/.test(t) ||
             /^(done|shipped|merged|complete)[.!]?$/.test(t.trim()),
     },
-    // Stall: "should I / want me to / shall I continue"
     {
         name: 'stall-should-i',
         class: 'stall',
@@ -18,7 +16,6 @@ const RULES = [
         autoAnswer: 'Yes, continue.',
         test: (t) => /\b(should i|shall i|want me to|would you like me to|do you want me to|can i go ahead|ok to proceed|okay to continue)\b/.test(t),
     },
-    // Stall: "what's next / continue?"
     {
         name: 'stall-whats-next',
         class: 'stall',
@@ -27,7 +24,6 @@ const RULES = [
         test: (t) => /\b(what('?s| is)? next|what now|continue\??|keep going\??|ready for the next|next step\??)\b/.test(t) ||
             /^continue\??$/.test(t.trim()),
     },
-    // Stall: verify-then-proceed / looks good?
     {
         name: 'stall-verify-proceed',
         class: 'stall',
@@ -35,7 +31,6 @@ const RULES = [
         autoAnswer: 'Looks good — proceed.',
         test: (t) => /\b(looks good\??|does this look (ok|right|good)|sound good\??|ready to (go|ship|land)\??|any objections\??)\b/.test(t),
     },
-    // Approval: merge/release/ship/commit yes-no (surfaces; policy can default later)
     {
         name: 'approval-merge-release',
         class: 'approval',
@@ -43,7 +38,6 @@ const RULES = [
         test: (t) => /\b(merge (now|this|the pr|it)\??|release\??|ship (it|now)\??|publish\??|cut (a )?release|tag (and )?release|commit (this|these changes)\??)\b/.test(t) ||
             /\b(approve|deny|allow|reject)\b.*\b(merge|release|deploy|pr)\b/.test(t),
     },
-    // Clarification: which X / which repo / pick one fact
     {
         name: 'clarification-which',
         class: 'clarification',
@@ -51,7 +45,6 @@ const RULES = [
         test: (t) => /\b(which (repo|branch|host|file|path|environment|env|project|package|version|account|device|machine)|what is the (path|url|id|name) of)\b/.test(t) ||
             /\b(missing (the )?(path|url|id|name|repo)|need (the )?(path|url|id|repo) for)\b/.test(t),
     },
-    // Decision: scope / approach / tradeoff (never auto-suppress)
     {
         name: 'decision-scope-approach',
         class: 'decision',
@@ -60,17 +53,11 @@ const RULES = [
             /\b(break(ing)? change|public api|migrate everyone|rewrite)\b/.test(t),
     },
 ];
-/**
- * Classify one ask from free text (+ optional explicit blockClass from the agent).
- * Explicit blockClass from the agent is honored as a floor: 'decision' never becomes
- * a suppressible stall (false-suppress rate ~0 for real Decisions).
- */
 export function classifyAsk(text, opts) {
     const scan = [opts?.header, text].filter(Boolean).join(' ').toLowerCase();
     for (const rule of RULES) {
         if (!rule.test(scan))
             continue;
-        // Safety: agent-tagged decisions never suppress.
         if (opts?.blockClass === 'decision' && rule.suppress) {
             return { class: 'decision', rule: 'agent-blockClass-decision', suppress: false };
         }
@@ -81,26 +68,19 @@ export function classifyAsk(text, opts) {
             autoAnswer: rule.autoAnswer,
         };
     }
-    // Explicit agent tag with no text rule.
     if (opts?.blockClass === 'decision') {
         return { class: 'decision', rule: 'agent-blockClass-decision', suppress: false };
     }
     if (opts?.blockClass === 'approval') {
         return { class: 'approval', rule: 'agent-blockClass-approval', suppress: false };
     }
-    // Default: surface as decision so we never silent-drop unknowns.
     return { class: 'decision', rule: 'default-decision', suppress: false };
 }
-/** Classify a full open block (all questions concatenated). */
 export function classifyBlock(block) {
     const text = block.questions.map((q) => q.text).join(' ');
     const header = block.questions.map((q) => q.header).filter(Boolean).join(' ');
     return classifyAsk(text, { header, blockClass: block.blockClass });
 }
-/**
- * Auto-answer + remove a suppressible block so it never renders as a card.
- * Logs the stall as answered by policy:stall-suppression.
- */
 export function suppressStallBlock(block, root, mailboxRoot) {
     const c = classifyBlock(block);
     if (!c.suppress || !c.autoAnswer) {
@@ -116,7 +96,6 @@ export function suppressStallBlock(block, root, mailboxRoot) {
         return { blockId: block.blockId, class: c.class, rule: c.rule, autoAnswer: c.autoAnswer, suppressed: false };
     }
     try {
-        // Mailbox lives under the global mailbox root (not the feed dir).
         const msgId = enqueue(mailboxDir(block.mailboxId, mailboxRoot), {
             to: block.mailboxId,
             text: c.autoAnswer,
@@ -126,7 +105,6 @@ export function suppressStallBlock(block, root, mailboxRoot) {
         recordMessageReceipt(block.blockId, { msgId, status: 'queued', at: new Date().toISOString(), from: 'stall-suppression' }, root);
     }
     catch {
-        // Mailbox write can fail if the box id is invalid; still drop the card.
     }
     removeBlock(block.blockId, root);
     return {
@@ -137,10 +115,6 @@ export function suppressStallBlock(block, root, mailboxRoot) {
         suppressed: true,
     };
 }
-/**
- * Classify every block; optionally apply stall suppression (mutate store).
- * When `apply` is false, only classifies (dry run for --json audit).
- */
 export function filterBlocksForFeed(blocks, opts) {
     const counts = {
         decision: 0,
@@ -178,7 +152,6 @@ export function filterBlocksForFeed(blocks, opts) {
     }
     return { surfaced, suppressed, counts };
 }
-/** Human digest: "31 stalls auto-resolved by policy". */
 export function suppressionDigest(result) {
     const n = result.suppressed.filter((s) => s.suppressed || s.class === 'stall' || s.class === 'fyi').length;
     if (n === 0)

package/dist/lib/audit/log.d.ts

@@ -1,18 +1,5 @@
-/**
- * Run-dispatch recording (issue #347) — now a thin write into the unified
- * event stream (`emit('run.dispatched', …)`). The historical hash-chained file
- * at `~/.agents/.history/audit/log.jsonl` is still readable via
- * `readAuditLog` / `verifyAuditChain` for pre-unification history; new runs do
- * NOT append there. Operators list run outcomes with:
- *
- *   agents events --include runs
- *   agents events audit          # nested alias of the above
- */
-/** First record's `prevHash` — a fixed anchor so the chain has a root. */
 export declare const GENESIS_HASH = "GENESIS";
-/** A run's outcome, derived from its process exit code. */
 export type AuditOutcome = 'ok' | 'fail';
-/** One immutable audit record. `hash` seals every other field, `prevHash` included. */
 export interface AuditRecord {
     ts: string;
     agent: string;
@@ -24,48 +11,14 @@ export interface AuditRecord {
     prevHash: string;
     hash: string;
 }
-/** The caller-supplied fields — the chain fields (`prevHash`/`hash`) are computed here. */
 export type AuditEntry = Omit<AuditRecord, 'prevHash' | 'hash'>;
-/**
- * Absolute path to the append-only audit log. Lives under `.history/` — the
- * durable-but-machine-local runtime bucket that is gitignored and never synced
- * by `agents repo push/pull`. Keeping it here (not under a top-level, tracked
- * `~/.agents/` path) means the token-bearing `repo` field can never leak into a
- * version-controlled DotAgents repo, and no cross-machine pull can fork the chain.
- */
 export declare function getAuditLogPath(): string;
-/**
- * Append one record to the hash chain and return it. Links to the previous
- * record's `hash` (or `GENESIS_HASH` for the first), computes the sealing
- * hash, and writes a single JSONL line. Synchronous so the record is durable
- * before the caller proceeds.
- *
- * Read-last-hash + append run under the canonical advisory file lock
- * (`withFileLock`, backed by proper-lockfile). Without it, two concurrent
- * writers — the norm under parallel teams/routines dispatch — both read the
- * same last hash and both write `prevHash=H`, forking the chain into a false
- * "tampered" verdict. The lock forces a total order so every record links off
- * the genuinely-previous one. `ensureLockTarget` creates the file first because
- * proper-lockfile locks an existing path.
- */
 export declare function appendAuditRecord(entry: AuditEntry, logPath?: string): AuditRecord;
-/**
- * Walk the chain and confirm every record reproduces. A record is valid when
- * (a) its `prevHash` matches the prior record's `hash` (GENESIS for the first)
- * AND (b) recomputing its sealing hash from its own fields reproduces the
- * stored `hash`. Returns the first failing index in `brokenAt`.
- */
 export declare function verifyAuditChain(logPath?: string): {
     ok: boolean;
     brokenAt?: number;
 };
-/** Read the whole chain, oldest-first. Exposed for `agents events audit verify`. */
 export declare function readAuditLog(logPath?: string): AuditRecord[];
-/**
- * Record ONE dispatched run at the single exec chokepoint into the unified
- * event stream. Non-fatal by contract: any failure is caught and warned, never
- * thrown — a log hiccup must not crash a run that already finished.
- */
 export declare function recordDispatchedRun(run: {
     agent: string;
     version: string;