@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/feed/answer.js

@@ -0,0 +1,145 @@
+import { spawn } from 'node:child_process';
+import { getActiveSessions } from '../session/active.js';
+import { resolveAnswerRoute, resumeArgv } from '../answer-router.js';
+import { enqueue, mailboxDir } from '../mailbox.js';
+import { injectIntoTerminal } from '../terminal/index.js';
+import { verifyOperatorIdentity } from '../operator.js';
+import { blockIdForSession, getAnswerRecord, publishBlock, readBlock, readResolution, recordAnswer, recordMessageReceipt, rollbackAnswerClaim, } from './feed.js';
+import { reconcileAttention } from './attention.js';
+import { readPullRequestStatus } from './pr-status.js';
+import { getAgentsInvocation } from '../daemon/daemon.js';
+function sessionForBlock(block, sessions) {
+    return sessions.find((session) => session.sessionId === block.sessionId || session.agentId === block.mailboxId);
+}
+function blockFromAttention(attention, session) {
+    return {
+        blockId: blockIdForSession(attention.sessionId), sessionId: attention.sessionId,
+        mailboxId: attention.mailboxId, host: attention.host, runtime: session.kind,
+        generation: attention.key.slice(attention.key.lastIndexOf('/') + 1), source: attention.source,
+        state: 'open', sourceCursor: attention.sourceCursor, project: attention.project,
+        ts: attention.openedAt, questions: [attention.question ?? { text: 'Continue from this attention item.' }],
+        kind: attention.kind === 'permission' ? 'notification' : attention.kind === 'declared' ? 'declared' : attention.source === 'system' ? 'control' : 'question',
+        safeDefault: attention.safeDefault,
+    };
+}
+async function resolveBlock(attentionKey, sessions, root) {
+    const ownerHost = attentionKey.slice(0, attentionKey.indexOf('/'));
+    for (const session of sessions) {
+        if (!session.sessionId)
+            continue;
+        let block = readBlock(blockIdForSession(session.sessionId), root);
+        const projectedSession = { ...session, host: ownerHost };
+        const attention = reconcileAttention({ block, session: projectedSession, pullRequest: await readPullRequestStatus(session), resolution: readResolution(blockIdForSession(session.sessionId), root), nowMs: Date.now() });
+        if (attention?.key === attentionKey && block)
+            return { block, attention };
+        // The winning caller advances the block to answered before a concurrent
+        // loser resolves it. Reconstruct only this block's original generation so
+        // the loser can return already_answered without routing a second reply.
+        if (block) {
+            const original = reconcileAttention({ block: { ...block, state: 'open', answer: undefined }, session: projectedSession, nowMs: Date.now() });
+            if (original?.key === attentionKey && getAnswerRecord(block.blockId, root))
+                return { block, attention: original };
+        }
+        if (attention?.key === attentionKey) {
+            block = blockFromAttention(attention, session);
+            publishBlock(block, root);
+            return { block, attention };
+        }
+    }
+    throw new Error(`No open attention item matches '${attentionKey}'.`);
+}
+/** Atomically claim the first answer, then route it over the session's recorded reply rail. */
+export async function claimAndRouteAttentionAnswer(input) {
+    if ((input.choiceId == null) === (input.text == null))
+        throw new Error('Exactly one of choiceId or text is required.');
+    const sessions = input.sessions ?? await getActiveSessions();
+    const { block, attention } = await resolveBlock(input.attentionKey, sessions, input.feedRoot);
+    const choice = input.choiceId == null ? undefined : attention.choices?.find((item) => item.id === input.choiceId);
+    if (input.choiceId != null && !choice)
+        throw new Error(`Unknown choice '${input.choiceId}' for '${input.attentionKey}'.`);
+    const answer = input.text ?? choice?.deliveryKey ?? choice?.label;
+    if (!answer)
+        throw new Error('Answer is empty.');
+    const verified = input.operator.verified && verifyOperatorIdentity(input.operator.id);
+    const previousResolution = readResolution(block.blockId, input.feedRoot);
+    const claim = recordAnswer(block.blockId, {
+        answeredBy: input.operator.label,
+        answeredFrom: 'feed',
+        operatorId: input.operator.id,
+        verified,
+    }, input.feedRoot);
+    if (!claim.ok) {
+        if ('unauthorized' in claim)
+            throw new Error(claim.reason);
+        const existing = getAnswerRecord(block.blockId, input.feedRoot) ?? claim.existing;
+        return { status: 'already_answered', receipt: {
+                msgId: `answer-${block.blockId}`,
+                status: 'queued',
+                at: existing.answeredAt,
+                from: existing.answeredBy ?? existing.answeredFrom,
+            } };
+    }
+    const claimed = getAnswerRecord(block.blockId, input.feedRoot);
+    if (!claimed)
+        throw new Error(`Answer claim for '${input.attentionKey}' was not persisted.`);
+    const session = sessionForBlock(block, sessions);
+    const route = resolveAnswerRoute({ mailboxId: block.mailboxId, answer, block, session });
+    if (route.kind === 'refuse') {
+        rollbackAnswerClaim(block.blockId, claimed.answeredAt, block, previousResolution, input.feedRoot);
+        throw new Error(route.reason);
+    }
+    let msgId;
+    try {
+        if (route.kind === 'mailbox') {
+            msgId = enqueue(mailboxDir(block.mailboxId, input.mailboxRoot), {
+                to: block.mailboxId, text: answer, from: input.operator.label, blockId: block.blockId,
+            });
+        }
+        else if (route.kind === 'resume') {
+            const invocation = getAgentsInvocation(resumeArgv(route));
+            const child = spawn(invocation.command, invocation.args, { stdio: 'inherit', env: process.env });
+            const code = await new Promise((resolve) => { child.once('error', () => resolve(1)); child.once('close', (value) => resolve(value ?? 1)); });
+            if (code !== 0)
+                throw new Error(`Resume delivery for '${input.attentionKey}' exited ${code}.`);
+            msgId = `resume-${Date.now()}`;
+        }
+        else {
+            if (!route.inject || route.payload == null)
+                throw new Error(`Incomplete ${route.kind} reply rail.`);
+            const delivered = await injectIntoTerminal(route.inject, route.payload, { enter: true, combined: false });
+            if (!delivered.ok)
+                throw new Error(delivered.error ?? `Failed to deliver over ${route.kind}.`);
+            msgId = `inject-${Date.now()}`;
+        }
+    }
+    catch (error) {
+        rollbackAnswerClaim(block.blockId, claimed.answeredAt, block, previousResolution, input.feedRoot);
+        throw error;
+    }
+    const receipt = { msgId, status: 'queued', at: new Date().toISOString(), from: input.operator.label };
+    recordMessageReceipt(block.blockId, receipt, input.feedRoot);
+    return { status: 'delivered', receipt };
+}
+/** Forward a fleet attention answer to the device that owns its scope. */
+export async function forwardFeedAnswer(input) {
+    const remoteArgs = ['feed', 'answer', input.attentionKey, '--json'];
+    if (input.choiceId != null)
+        remoteArgs.push('--choice', input.choiceId);
+    if (input.text != null)
+        remoteArgs.push('--text', input.text);
+    if (input.operatorId)
+        remoteArgs.push('--as', input.operatorId);
+    const invocation = getAgentsInvocation(['ssh', input.host, 'agents', ...remoteArgs]);
+    const child = spawn(invocation.command, invocation.args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    const code = await new Promise((resolve) => { child.once('error', () => resolve(1)); child.once('close', (value) => resolve(value ?? 1)); });
+    if (code !== 0)
+        throw new Error(stderr.trim() || `Remote feed answer on '${input.host}' exited ${code}.`);
+    const line = stdout.trim().split('\n').reverse().find((value) => value.startsWith('{'));
+    if (!line)
+        throw new Error(`Remote feed answer on '${input.host}' returned no JSON receipt.`);
+    return JSON.parse(line);
+}

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

@@ -0,0 +1,83 @@
+import type { ActiveSession } from '../session/active.js';
+import { type AttentionResolution, type AttentionSource, type AttentionState, type BlockOption, type BlockQuestion, type OpenBlock, type SourceCursor } from './feed.js';
+/** What an attention item is asking of the operator. */
+export type AttentionKind = 'question' | 'permission' | 'plan_review' | 'declared' | 'failure' | 'stall' | 'review';
+/** How an answer can be routed back to the waiting agent. */
+export type ReplyCapability = 'terminal' | 'tmux' | 'cloud' | 'team' | 'none';
+/**
+ * One answerable choice on an attention item. Extends {@link BlockOption} with a
+ * stable `id` the UI echoes back when the operator picks it, and an optional
+ * `deliveryKey` (the harness-native keystroke / selection token) that Track B's
+ * answer router resolves the reply rail with.
+ */
+export interface AttentionChoice extends BlockOption {
+    id: string;
+    deliveryKey?: string;
+}
+/**
+ * The canonical operator-facing attention record. One reconciled thing that needs
+ * a human, whatever produced it. This is the public envelope Tracks B and C
+ * consume — a stability contract, not an internal shape.
+ */
+export interface AttentionItem {
+    /** Stable identity: `host/session/generation`. A new generation is a new item. */
+    key: string;
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    project?: string;
+    kind: AttentionKind;
+    source: AttentionSource;
+    state: AttentionState;
+    /** ISO-8601 timestamp the ask opened. */
+    openedAt: string;
+    question?: BlockQuestion;
+    choices?: AttentionChoice[];
+    replyCapability: ReplyCapability;
+    safeDefault?: string;
+    /**
+     * Clusters IDENTICAL asks across different agents for batch triage. It is a hash
+     * of the RAW question intent (kind + verbatim question text + option labels) —
+     * deliberately NOT the UI-normalized display text, so two agents asking the same
+     * thing collapse even when the floor renders them differently.
+     */
+    fingerprint: string;
+    /** Where in the source this generation sits — the fence a resolution compares against. */
+    sourceCursor?: SourceCursor;
+}
+/**
+ * A pull-request attention signal, supplied BY the CLI (Track B refreshes it on a
+ * bounded TTL and hands it in). Track A only consumes the computed `needsHuman`
+ * flag — it never reaches into the extension's PR board or recomputes review
+ * state. Fields mirror the `gh pr view` projection so Track B can populate it.
+ */
+export interface PullRequestAttentionSignal {
+    number: number;
+    title?: string;
+    url?: string;
+    /** True when the PR is in a state that needs a human decision (review / merge). */
+    needsHuman: boolean;
+    reviewDecision?: string;
+    mergeable?: string;
+    state?: string;
+    isDraft?: boolean;
+}
+/**
+ * Fingerprint of an ask's raw intent. Uses the verbatim question text and option
+ * labels (NOT display-normalized text) so identical asks from different agents
+ * share a fingerprint for batch triage.
+ */
+export declare function attentionFingerprint(kind: AttentionKind, question?: BlockQuestion): string;
+/**
+ * Reconcile the feed block ledger, the session lifecycle, a CLI-supplied PR
+ * signal, and the latest resolution tombstone into one attention item — or
+ * `undefined` when nothing needs a human. Pure; the extension never chooses
+ * authority.
+ */
+export declare function reconcileAttention(input: {
+    block?: OpenBlock;
+    session: ActiveSession;
+    pullRequest?: PullRequestAttentionSignal;
+    resolution?: AttentionResolution;
+    nowMs: number;
+}): AttentionItem | undefined;

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

@@ -30,12 +30,54 @@ export interface AnswerRecord {
     /** Whether the operator identity was verified against the registry. */
     verified?: boolean;
 }
+/**
+ * Where an attention record came from, strongest evidence first.
+ *   hook      — a harness event (AskUserQuestion / permission / notification).
+ *   declared  — the agent said it is stuck (`agents feed post --blocked`).
+ *   lifecycle — a structural session signal (plan handoff / permission wait).
+ *   heuristic — an inferred prose question that decays.
+ *   system    — a synthetic card the feed computed (runaway / needy / PR review).
+ */
+export type AttentionSource = 'hook' | 'declared' | 'lifecycle' | 'heuristic' | 'system';
+/**
+ * The lifecycle state of an attention record. A block is `open` until it is
+ * answered from some surface, `answered` once a surface claimed it, `consumed`
+ * once the agent read the reply, `continued` once the agent moved on, and
+ * `resolved` for a terminal clear (the block file is being removed). This is the
+ * axis the operator projection ranks on — only `open` needs a human.
+ */
+export type AttentionState = 'open' | 'answered' | 'consumed' | 'continued' | 'resolved';
+/**
+ * A cursor into the source that produced a block — the transcript's last write
+ * (`lastActivityMs`) or a specific transcript `eventId`. It is what lets a
+ * resolution tombstone say "this generation was resolved at THIS point" so a
+ * stale lifecycle re-read cannot resurrect it while the session sits still, yet
+ * a genuinely newer turn (a strictly later cursor) is allowed through as a new
+ * generation. See {@link AttentionResolution} and `reconcileAttention`.
+ */
+export interface SourceCursor {
+    lastActivityMs?: number;
+    eventId?: string;
+}
 export interface OpenBlock {
     blockId: string;
     sessionId: string;
     mailboxId: string;
     host: string;
     runtime: string;
+    /**
+     * Generation key for this block's CURRENT question. A new AskUserQuestion (or a
+     * new `--blocked` post) in the same session mints a new generation, so a
+     * resolution tombstone for the previous generation cannot suppress the fresh
+     * ask. Derived from `ts` when a writer did not stamp it — see {@link blockGeneration}.
+     */
+    generation?: string;
+    /** How this block came to exist. Derived from {@link kind} when absent — see {@link blockSource}. */
+    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. */
+    sourceCursor?: SourceCursor;
     /** Indexed launch origin, added at read time when the live session is known. */
     origin?: 'cli' | 'routine';
     /** Routine definition name when origin is `routine`. */
@@ -121,6 +163,66 @@ export interface FeedAskStats {
     totalAskCount: number;
     recentAskTimestamps: string[];
 }
+/**
+ * Why an attention generation stopped needing a human — a resolution tombstone.
+ *   answered        — a surface recorded an answer.
+ *   continued       — the agent consumed the answer and moved on.
+ *   tool_completed  — the tool an approval gated finished (permission cleared).
+ *   expired         — a decaying heuristic ask aged out.
+ *   session_advanced— the transcript moved past the block (Stop/PostToolUse clear).
+ */
+export type ResolutionReason = 'answered' | 'continued' | 'tool_completed' | 'expired' | 'session_advanced';
+/**
+ * A resolution tombstone. It is recorded BEFORE the open-block view is cleared so
+ * a resolved generation can never silently resurrect from a stale lifecycle
+ * re-read (the RUSH-1522 stale-flag class): the reconciler suppresses a
+ * lifecycle candidate whose generation the tombstone already covers, until the
+ * session advances strictly past `sourceCursor`. One tombstone per block id,
+ * latest-wins — the block id is stable per session, so this never grows unbounded.
+ */
+export interface AttentionResolution {
+    blockId: string;
+    /** The generation this tombstone resolved — matched against a fresh candidate's generation. */
+    generation: string;
+    /** ISO-8601 timestamp of the resolution. */
+    resolvedAt: string;
+    /** Where in the source the resolved generation sat; the reconciler compares a candidate's cursor against it. */
+    sourceCursor?: SourceCursor;
+    reason: ResolutionReason;
+}
+/**
+ * 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 declare function blockGeneration(block: OpenBlock): string;
+/**
+ * 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 declare function blockSource(block: OpenBlock): AttentionSource;
+/**
+ * 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 declare function deriveBlockState(block: OpenBlock): AttentionState;
+/**
+ * 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 declare function recordResolution(resolution: AttentionResolution, root?: string): void;
+/** Read the latest resolution tombstone for a block, if one exists. */
+export declare function readResolution(blockId: string, root?: string): AttentionResolution | undefined;
+/** Read every resolution tombstone. Returns them sorted by stable block filename. */
+export declare function listResolutions(root?: string): AttentionResolution[];
 /**
  * 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).
@@ -155,6 +257,13 @@ export declare function recordAnswer(blockId: string, answer: {
 }, root?: string): RecordAnswerResult;
 /** Read the answer record for a block, if one exists. */
 export declare function getAnswerRecord(blockId: string, root?: string): AnswerRecord | undefined;
+/**
+ * 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 declare function rollbackAnswerClaim(blockId: string, answeredAt: string, previousBlock: OpenBlock, previousResolution: AttentionResolution | undefined, root?: string): boolean;
 /** True when the block has already been answered. */
 export declare function isBlockAnswered(blockId: string, root?: string): boolean;
 /**

package/dist/lib/feed/feed.js

@@ -29,6 +29,80 @@ 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';
+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;
+    switch (block.kind) {
+        case 'declared': return 'declared';
+        case 'control': return 'system';
+        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;
+    if (block.continuedAt)
+        return 'continued';
+    if (block.answer)
+        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`));
+}
+/** Read every resolution tombstone. Returns them sorted by stable block filename. */
+export function listResolutions(root) {
+    const dir = resolutionDir(root ?? getFeedDir());
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.filter(n => n.endsWith('.json')).sort()) {
+        const parsed = safeReadJson(path.join(dir, name));
+        if (parsed?.blockId && parsed.generation && parsed.reason)
+            out.push(parsed);
+    }
+    return out;
+}
 /**
  * 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).
@@ -131,9 +205,20 @@ export function recordAnswer(blockId, answer, root) {
         }
         throw err;
     }
-    // Marker created successfully -- mirror the answer into the block file.
+    // 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.
     if (block) {
+        recordResolution({
+            blockId,
+            generation: blockGeneration(block),
+            resolvedAt: record.answeredAt,
+            sourceCursor: block.sourceCursor,
+            reason: 'answered',
+        }, dir);
         block.answer = record;
+        block.state = 'answered';
         publishBlock(block, dir);
     }
     return { ok: true };
@@ -142,6 +227,37 @@ export function recordAnswer(blockId, answer, root) {
 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;
+    // 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)
+        recordResolution(previousResolution, dir);
+    else {
+        try {
+            fs.unlinkSync(resolutionFile);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    fs.unlinkSync(marker);
+    return true;
+}
 /** True when the block has already been answered. */
 export function isBlockAnswered(blockId, root) {
     return fs.existsSync(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
@@ -190,7 +306,16 @@ export function recordContinued(blockId, root) {
     const block = readBlock(blockId, dir);
     if (!block)
         return;
-    block.continuedAt = new Date().toISOString();
+    const now = new Date().toISOString();
+    block.continuedAt = now;
+    block.state = 'continued';
+    recordResolution({
+        blockId,
+        generation: blockGeneration(block),
+        resolvedAt: now,
+        sourceCursor: block.sourceCursor,
+        reason: 'continued',
+    }, dir);
     publishBlock(block, dir);
 }
 /** Mark a decision-class block as hard-parked (no safe default existed). */
@@ -260,13 +385,20 @@ export function buildDeclaredBlock(agent, input) {
         .filter(Boolean)
         .map((label) => ({ label }));
     const project = projectKeyFromCwd(agent.cwd);
+    const ts = input.ts ?? new Date().toISOString();
     return {
         blockId: blockIdForSession(agent.sessionId),
         sessionId: agent.sessionId,
         mailboxId: agent.mailboxId,
         host: agent.host,
         runtime: agent.runtime,
-        ts: input.ts ?? new Date().toISOString(),
+        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',
         kind: 'declared',
         questions: [{ text, header: 'Needs you', ...(options.length ? { options } : {}) }],
         blockClass: input.safeDefault ? 'approval' : 'decision',
@@ -337,6 +469,25 @@ export function listAskStats(root) {
 /** 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)
+            ? 'answered'
+            : block.continuedAt ? 'continued' : 'session_advanced';
+        recordResolution({
+            blockId,
+            generation: blockGeneration(block),
+            resolvedAt: new Date().toISOString(),
+            sourceCursor: block.sourceCursor,
+            reason,
+        }, dir);
+    }
     clearBlockLifecycle(blockId, dir);
     try {
         fs.unlinkSync(blockPath(dir, blockId));

package/dist/lib/feed/pr-status.d.ts

@@ -0,0 +1,14 @@
+import type { ActiveSession } from '../session/active.js';
+import type { PullRequestAttentionSignal } from './attention.js';
+export declare const PR_STATUS_TTL_MS = 45000;
+export declare const PR_STATUS_FIELDS = "number,title,state,isDraft,reviewDecision,mergeable,statusCheckRollup";
+export interface PullRequestStatus extends PullRequestAttentionSignal {
+    statusCheckRollup?: unknown[];
+}
+/** CLI-owned bounded-TTL source shared by feed attention and PR-board consumers. */
+export declare function readPullRequestStatus(session: ActiveSession, options?: {
+    nowMs?: number;
+    ttlMs?: number;
+}): Promise<PullRequestStatus | undefined>;
+export declare function projectPullRequestBoard(sessions: ActiveSession[]): Promise<PullRequestStatus[]>;
+export declare function resetPullRequestStatusCache(): void;

package/dist/lib/feed/pr-status.js

@@ -0,0 +1,47 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const PR_STATUS_TTL_MS = 45_000;
+export const PR_STATUS_FIELDS = 'number,title,state,isDraft,reviewDecision,mergeable,statusCheckRollup';
+const cache = new Map();
+function needsHuman(value) {
+    if (value.state !== 'OPEN' || value.isDraft)
+        return false;
+    const checks = value.statusCheckRollup ?? [];
+    const checksSettled = checks.every((check) => {
+        const row = check;
+        return row.conclusion === 'SUCCESS' || row.conclusion === 'NEUTRAL' || row.status === 'COMPLETED';
+    });
+    return value.reviewDecision !== 'APPROVED' || (value.mergeable === 'MERGEABLE' && checksSettled);
+}
+/** CLI-owned bounded-TTL source shared by feed attention and PR-board consumers. */
+export async function readPullRequestStatus(session, options = {}) {
+    const ref = session.pr?.url ?? session.pr?.number;
+    if (!ref || !session.cwd)
+        return undefined;
+    const key = `${session.cwd}\0${String(ref)}`;
+    const now = options.nowMs ?? Date.now();
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt > now)
+        return hit.value;
+    try {
+        const { stdout } = await execFileAsync('gh', ['pr', 'view', String(ref), '--json', PR_STATUS_FIELDS], {
+            cwd: session.cwd,
+            timeout: 15_000,
+            maxBuffer: 1024 * 1024,
+        });
+        const raw = JSON.parse(stdout);
+        const value = { ...raw, url: session.pr?.url, needsHuman: needsHuman(raw) };
+        cache.set(key, { expiresAt: now + (options.ttlMs ?? PR_STATUS_TTL_MS), value });
+        return value;
+    }
+    catch {
+        cache.set(key, { expiresAt: now + (options.ttlMs ?? PR_STATUS_TTL_MS) });
+        return undefined;
+    }
+}
+export async function projectPullRequestBoard(sessions) {
+    const rows = await Promise.all(sessions.map((session) => readPullRequestStatus(session)));
+    return rows.filter((row) => row !== undefined);
+}
+export function resetPullRequestStatusCache() { cache.clear(); }