@phnx-labs/agents-cli 1.22.115 → 1.22.116

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

@@ -23,7 +23,38 @@ export interface MessageReceipt {
     at: string;
     /** Optional sender label for the message. */
     from?: string;
+    /**
+     * The ask this receipt is ABOUT — the block generation live when the answer
+     * was sent. A block id is per SESSION, so it is reused by every generation of
+     * that session's questions; without this a late acknowledgement for question N
+     * is indistinguishable from one for question N+1 and would resolve the wrong
+     * ask (PHNX-3999). Carried durably on the queued message so it survives the
+     * process that sent it.
+     */
+    generation?: string;
+    /** The claim (attempt) this receipt is about — `AnswerRecord.answeredAt`. */
+    attempt?: string;
+}
+/** The ask a receipt or queued message belongs to, plus the attempt that sent it. */
+export interface ReceiptOrigin {
+    generation: string;
+    attempt: string;
 }
+/**
+ * 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 declare function receiptMatchesOrigin(receipt: MessageReceipt, origin: ReceiptOrigin): boolean;
 export interface AnswerRecord {
     /** ISO-8601 timestamp of when the answer was recorded. */
     answeredAt: string;
@@ -267,7 +298,22 @@ export declare function recordAnswer(blockId: string, answer: {
     answeredFrom: string;
     operatorId?: string;
     verified?: boolean;
-}, root?: string): RecordAnswerResult;
+}, root?: string, options?: {
+    pending?: boolean;
+}): RecordAnswerResult;
+/**
+ * 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 declare function confirmAnswerResolution(blockId: string, root?: string, expected?: {
+    generation: string;
+    answeredAt: string;
+}): boolean;
 /** Read the answer record for a block, if one exists. */
 export declare function getAnswerRecord(blockId: string, root?: string): AnswerRecord | undefined;
 /**
@@ -277,6 +323,12 @@ export declare function getAnswerRecord(blockId: string, root?: string): AnswerR
  * restoring the attention lifecycle to the state another surface observed.
  */
 export declare function rollbackAnswerClaim(blockId: string, answeredAt: string, previousBlock: OpenBlock, previousResolution: AttentionResolution | undefined, root?: string): boolean;
+/**
+ * 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 declare const RELEASE_TOKEN_STALE_MS = 60000;
 /** True when the block has already been answered. */
 export declare function isBlockAnswered(blockId: string, root?: string): boolean;
 /**
@@ -288,6 +340,14 @@ export declare function isBlockAnswered(blockId: string, root?: string): boolean
 export declare function recordMessageReceipt(blockId: string, receipt: MessageReceipt, root?: string): void;
 /** Read the receipt list for a block. */
 export declare function getBlockReceipts(blockId: string, root?: string): MessageReceipt[];
+/**
+ * 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 declare function latestMessageReceipt(blockId: string, root?: string, origin?: ReceiptOrigin): MessageReceipt | undefined;
 /** Mark a block as "continued" -- the agent consumed the answer and moved on. */
 export declare function recordContinued(blockId: string, root?: string): void;
 /** Mark a decision-class block as hard-parked (no safe default existed). */

package/dist/lib/feed/feed.js

@@ -23,12 +23,32 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import * as yaml from 'yaml';
 import { stringifyDoc } from '../yaml-io.js';
 import { getFeedDir, getUserAgentsDir } from '../state.js';
 import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from '../operator.js';
 import { projectKeyFromCwd } from '../project-key.js';
 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;
@@ -129,7 +149,7 @@ export function readBlock(blockId, root) {
  * 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) {
+export function recordAnswer(blockId, answer, root, options = {}) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
     const operatorId = answer.operatorId;
@@ -187,24 +207,74 @@ export function recordAnswer(blockId, answer, root) {
         }
         throw err;
     }
-    // Marker created successfully -- mirror the answer into the block file and
-    // advance the lifecycle to `answered`. 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.
+    // 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) {
-        recordResolution({
-            blockId,
-            generation: blockGeneration(block),
-            resolvedAt: record.answeredAt,
-            sourceCursor: block.sourceCursor,
-            reason: 'answered',
-        }, dir);
+        if (!options.pending) {
+            recordResolution({
+                blockId,
+                generation: blockGeneration(block),
+                resolvedAt: record.answeredAt,
+                sourceCursor: block.sourceCursor,
+                reason: 'answered',
+            }, dir);
+        }
         block.answer = record;
-        block.state = 'answered';
+        block.state = options.pending ? 'open' : 'answered';
         publishBlock(block, dir);
     }
     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({
+        blockId,
+        generation: blockGeneration(block),
+        resolvedAt: record.answeredAt,
+        sourceCursor: block.sourceCursor,
+        reason: 'answered',
+    }, dir);
+    block.answer = record;
+    block.state = 'answered';
+    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`));
@@ -221,6 +291,31 @@ export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previous
     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;
+    const dropToken = () => {
+        try {
+            fs.unlinkSync(release);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                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.
@@ -237,9 +332,79 @@ export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previous
                 throw error;
         }
     }
-    fs.unlinkSync(marker);
+    try {
+        fs.unlinkSync(marker);
+    }
+    catch (error) {
+        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 = () => {
+        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);
+            }
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    };
+    if (create())
+        return true;
+    const held = safeReadJson(release);
+    const ageMs = held?.at ? Date.now() - held.at : Number.POSITIVE_INFINITY;
+    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);
+        }
+        catch {
+            ownerGone = true;
+        }
+    }
+    if (!ownerGone && ageMs < RELEASE_TOKEN_STALE_MS)
+        return false; // a live peer owns it
+    try {
+        fs.unlinkSync(release);
+    }
+    catch (error) {
+        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`));
@@ -277,11 +442,58 @@ 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, {
+            generation: receipt.generation, answeredAt: block.answer.answeredAt,
+        });
+    }
 }
 /** 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) {
+        if (!best) {
+            best = receipt;
+            continue;
+        }
+        const rank = RECEIPT_STATUS_RANK[receipt.status] - RECEIPT_STATUS_RANK[best.status];
+        if (rank > 0 || (rank === 0 && receipt.at >= best.at))
+            best = receipt;
+    }
+    return best;
+}
 /** Mark a block as "continued" -- the agent consumed the answer and moved on. */
 export function recordContinued(blockId, root) {
     const dir = root ?? getFeedDir();

package/dist/lib/feed/hub-server.d.ts

@@ -1,7 +1,8 @@
 import { FeedHub } from './hub.js';
 import type { FeedWatchEnvelope } from './envelope.js';
 /**
- * Outbound bytes a single reader may leave unflushed before it is dropped.
+ * Live bytes a reader may leave queued, sustained past {@link HUB_BACKLOG_GRACE_MS},
+ * before it is dropped.
  *
  * `socket.write()` never blocks: when a reader stops draining — a stopped
  * process, a suspended laptop, a debugger paused on a breakpoint — node buffers
@@ -10,8 +11,49 @@ import type { FeedWatchEnvelope } from './envelope.js';
  * can never reclaim, and the daemon is the process every other surface depends
  * on. A reader that cannot keep up is dropped loudly instead: it can reconnect
  * and be caught up from held state, which is cheaper than the backlog.
+ *
+ * The budget is a SUSTAINED condition on queued live events, never a verdict on
+ * one envelope or one burst. A cold collector delivers every peer's reset as a
+ * live event, thirteen of them inside one tick, and a healthy reader drains
+ * that in milliseconds; judging the budget the instant an envelope was written
+ * is how a 5 MB fleet reset was cut off after 8 KiB and delivered as one
+ * unterminated line (the Menu activation failure this module's writer fixes).
+ * The catch-up snapshot is never counted: it is bounded by the held state and is
+ * exactly what a fresh reader is waiting for.
  */
 export declare const HUB_CLIENT_BACKLOG_LIMIT: number;
+/**
+ * How long a reader may stay past {@link HUB_CLIENT_BACKLOG_LIMIT} before it is
+ * dropped. A healthy reader on a unix socket clears the whole budget in well
+ * under this; one still over it after this long is not keeping up. The live
+ * bytes queued for a reader are therefore bounded by the budget plus what the
+ * stream produces in this window; the snapshot and the frame in flight sit
+ * outside that figure.
+ */
+export declare const HUB_BACKLOG_GRACE_MS = 2000;
+/**
+ * How long a reader may leave one chunk unaccepted before it is dropped.
+ *
+ * A write that returned `false` is a kernel buffer full of bytes the reader has
+ * not read. A healthy reader — even one on a busy laptop — clears it in
+ * milliseconds; one that has not in this long is not reading at all, and the
+ * live-bytes budget alone would let a paused reader hold a large snapshot's
+ * remainder in the daemon's heap forever.
+ */
+export declare const HUB_DRAIN_STALL_MS = 30000;
+/**
+ * Bytes handed to the socket per write. Small enough that a reader's own
+ * backpressure (`write()` returning `false`, then `'drain'`) paces a multi-MB
+ * snapshot instead of dumping it into the daemon's heap in one copy.
+ */
+export declare const HUB_WRITE_CHUNK_BYTES: number;
+/** Optional overrides for the transport bounds. Tests exercise both bounds fast. */
+export type FeedHubLimits = {
+    backlogBytes?: number;
+    backlogGraceMs?: number;
+    drainStallMs?: number;
+    chunkBytes?: number;
+};
 /**
  * How long a reader gets to send its scope line before it is REJECTED.
  *
@@ -40,8 +82,12 @@ export declare class FeedHubServer {
     private readonly detachers;
     /** Which collector each reader is attached to, so a failure reaches only its own. */
     private readonly attachedTo;
-    /** Readers dropped for exceeding {@link HUB_CLIENT_BACKLOG_LIMIT}. Observability. */
+    private readonly writers;
+    private readonly limits;
+    /** Readers dropped for queueing live bytes past the budget. Observability. */
     droppedForBacklog: number;
+    /** Readers dropped for not draining a chunk within the stall deadline. Observability. */
+    droppedForStall: number;
     /** Readers refused for a missing, invalid, or late scope line. Observability. */
     rejectedHandshakes: number;
     /**
@@ -51,11 +97,13 @@ export declare class FeedHubServer {
      *                 every reader from the fleet hub, which is what the fleet
      *                 stream already contained.
      */
-    constructor(hub: FeedHub, socketPathOverride?: string | undefined, localHub?: FeedHub | undefined);
+    constructor(hub: FeedHub, socketPathOverride?: string | undefined, localHub?: FeedHub | undefined, limits?: FeedHubLimits);
     /** Report a collector failure to its readers and end those connections. */
     private failReaders;
     /** Subscribers currently connected. Observability + tests. */
     get clientCount(): number;
+    /** Bytes queued for every reader and not yet handed to a socket. Observability + tests. */
+    get pendingBytes(): number;
     start(): Promise<void>;
     stop(): Promise<void>;
 }
@@ -76,6 +124,13 @@ export declare function waitForHub(endpoint?: string, deadlineMs?: number, inter
  * quietly ran its own `watchFleetFeed` instead would restore the per-caller
  * ssh fan-out, so the caller starts the daemon and retries rather than
  * degrading into the thing this replaced.
+ *
+ * Also rejects on any close the caller did not ask for. The stream has no end
+ * of its own — the hub serves it until the reader leaves — so a FIN that
+ * arrives before `signal` aborts is the hub refusing, failing, or dropping this
+ * reader, and a FIN inside a line is a frame the hub never finished. Resolving
+ * there let `agents feed watch --json` exit 0 after 8 KiB of a 5 MB reset,
+ * which is indistinguishable from an empty fleet.
  */
 export declare function streamFeedFromHub(options: {
     signal: AbortSignal;