@phnx-labs/agents-cli 1.20.90 → 1.20.91

package/dist/lib/daemon.js

@@ -18,6 +18,7 @@ import { JobScheduler } from './scheduler.js';
 import { MonitorEngine } from './monitors/engine.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from './overdue.js';
+import { runCatchup } from './catchup.js';
 import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from './routine-notify.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
@@ -32,6 +33,14 @@ const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
 const MONITOR_TICK_MS = 60_000;
+/**
+ * How often to re-scan for missed fires. Deliberately slower than the monitor
+ * tick: detection walks a week of cron occurrences per routine
+ * (`previousExpectedFire`), and a fire that was already missed is not urgent to
+ * the second — five minutes bounds the cost while still recovering from a
+ * wedge or an OS suspend the process survived.
+ */
+const CATCHUP_TICK_MS = 5 * 60_000;
 const WEDGE_THRESHOLD_TICKS = 3;
 /**
  * RUSH-1817: decide whether the daemon should (re)take over hosting the secrets
@@ -477,25 +486,76 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Monitor engine failed to start: ${err.message}`);
     }
-    // Backlog detection: any enabled recurring job whose most-recent expected
-    // fire is older than its most-recent recorded run is overdue. Happens when
-    // the laptop was off or the daemon crashed through a scheduled fire.
-    // We log it and pop a native notification — the user can review with
-    // `agents routines list` and run them with `agents routines catchup`.
-    try {
-        const overdue = detectOverdueJobs();
-        if (overdue.length > 0) {
-            log('WARN', `${overdue.length} routine(s) overdue:`);
+    // Backlog recovery: any enabled recurring job whose most-recent expected fire
+    // is older than its most-recent recorded run was missed — the laptop slept,
+    // the machine was off, or the daemon crashed through the fire. croner only
+    // schedules forward from "now", so nothing replays it on its own.
+    //
+    // Every miss is RECORDED as a `missed` run and, unless the routine sets
+    // `catchup: false`, RUN late. Runs on a timer as well as at startup: a startup
+    // pass alone misses a fire lost while the daemon stayed up but its event loop
+    // was wedged, or one lost across an OS suspend that the process survived.
+    // Overlap guard, same shape as runSessionSync/runHealCheck below. A pass
+    // awaits executeJobDetached per job and an off-box (host/cloud) dispatch can
+    // block for a while, so a slow pass could still be working when the next tick
+    // fires. Both passes would then see a job the first has not yet reached as
+    // overdue — the miss is recorded before the await, but only for jobs already
+    // processed — and spawn it twice. The idempotency of the `missed` record
+    // guards across passes, not within one that is mid-flight.
+    let catchingUp = false;
+    const catchupPass = async () => {
+        if (catchingUp)
+            return;
+        catchingUp = true;
+        try {
+            const overdue = detectOverdueJobs();
+            if (overdue.length === 0)
+                return;
+            log('WARN', `${overdue.length} routine(s) missed their fire:`);
             for (const job of overdue) {
                 const last = job.lastRanAt ? job.lastRanAt.toISOString() : 'never';
                 log('WARN', `  ${job.name} -- expected ${job.expectedAt.toISOString()}, last ran ${last}`);
             }
             notifyOverdue(overdue);
+            const outcomes = await runCatchup({ overdue });
+            for (const o of outcomes) {
+                // Every variant handled explicitly: a catch-all else would log the
+                // benign 'claimed-elsewhere' (another process legitimately won the
+                // claim) as an ERROR with an undefined reason.
+                switch (o.result) {
+                    case 'ran':
+                        log('INFO', `Caught up '${o.name}' (run: ${o.runId})`);
+                        break;
+                    case 'recorded':
+                        log('INFO', `Recorded missed fire for '${o.name}' (catchup disabled)`);
+                        break;
+                    case 'claimed-elsewhere':
+                        log('INFO', `Missed fire for '${o.name}' already claimed by another catchup`);
+                        break;
+                    case 'error':
+                        log('ERROR', `Catchup for '${o.name}' failed: ${o.error}`);
+                        break;
+                    default: {
+                        // Compile-time exhaustiveness: a new CatchupOutcome variant fails
+                        // typecheck here rather than silently landing in the wrong log level,
+                        // which is exactly how 'claimed-elsewhere' was first missed.
+                        const unhandled = o.result;
+                        log('ERROR', `Catchup for '${o.name}' returned an unhandled result: ${String(unhandled)}`);
+                    }
+                }
+            }
         }
-    }
-    catch (err) {
-        log('ERROR', `Overdue detection failed: ${err.message}`);
-    }
+        catch (err) {
+            log('ERROR', `Catchup pass failed: ${err.message}`);
+        }
+        finally {
+            // finally, not a tail assignment: the no-overdue path returns early, and a
+            // throw must not leave the guard latched shut for the daemon's lifetime.
+            catchingUp = false;
+        }
+    };
+    await catchupPass();
+    const catchupInterval = setInterval(() => { void catchupPass(); }, CATCHUP_TICK_MS);
     // Before the BrowserService comes up, reap browser + tunnel processes
     // spawned by previous daemons that are no longer alive. Without this,
     // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH
@@ -834,6 +894,7 @@ export async function runDaemon() {
         monitorEngine.stop();
         await browserIPC.stop();
         clearInterval(monitorInterval);
+        clearInterval(catchupInterval);
         clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);

package/dist/lib/events.d.ts

@@ -20,6 +20,14 @@ export interface EventMeta {
     tz: string;
     tzName: string;
     hostname: string;
+    /**
+     * Normalized, joinable device id (`machine-id.ts::machineId()`) — the same key
+     * `agents devices`/session-sync use, so an event can be matched to a device.
+     * `hostname` is the raw `os.hostname()`; `machineId` is `zion` for `Zion.local`.
+     * Optional on the type so legacy records (pre-provenance-floor) and the activity
+     * stream still parse; `emit()` always stamps it on the operational log.
+     */
+    machineId?: string;
     platform: NodeJS.Platform;
     arch: string;
     pid: number;
@@ -40,6 +48,10 @@ export interface EventPayload {
     agent?: string;
     version?: string;
     sessionId?: string;
+    /** Spawn-time join key (AGENT_LAUNCH_ID) mapping this action to its launch. */
+    launchId?: string;
+    /** The session that spawned this one (AGENTS_PARENT_SESSION_ID) — lineage edge. */
+    parentSessionId?: string;
     cwd?: string;
     /** Top-level command group, e.g. 'teams', 'secrets' — the audit filter key. */
     module?: string;

package/dist/lib/events.js

@@ -20,6 +20,28 @@ import { parseSshConnection } from './session/provenance.js';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { getUserAgentsDir } from './state.js';
 import { resolveActor } from './actor.js';
+import { machineId } from './machine-id.js';
+/** Lazy perf warehouse write — avoids a hard cycle at module load. */
+function recordPerfTiming(payload) {
+    try {
+        // Dynamic import keeps events.ts free of a load-time dependency on perf/db.
+        void import('./perf/spool.js').then(({ recordSample }) => {
+            recordSample({
+                kind: 'perf.timing',
+                label: payload.label,
+                durationMs: payload.durationMs,
+                status: payload.status,
+                agent: payload.agent,
+                agentVersion: payload.version,
+                sessionId: payload.sessionId,
+                cwd: payload.cwd,
+            });
+        }).catch(() => { });
+    }
+    catch {
+        // fail soft
+    }
+}
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Resolved lazily: events.ts is imported transitively by most CLI surfaces, and
 // import itself must stay side-effect free. Tests may override the exact path.
@@ -118,7 +140,7 @@ const SECRET_PATH = /\/(secrets|credentials|\.env|user\.yaml)\b/i;
 const SENSITIVE_ARG_NAME = /password|secret|token|key|api[-_]?key|auth/i;
 const SENSITIVE_PAYLOAD_KEY = /password|secret|token|api[-_]?key|auth/i;
 const RESERVED_META_KEYS = new Set([
-    'ts', 'tz', 'tzName', 'hostname', 'platform', 'arch', 'pid', 'ppid',
+    'ts', 'tz', 'tzName', 'hostname', 'machineId', 'platform', 'arch', 'pid', 'ppid',
     'event', 'level', 'caller', 'session', 'osUser', 'transport', 'sshClientIp',
     'actor', 'kind',
 ]);
@@ -288,6 +310,24 @@ function auditOrigin() {
     };
     return _origin;
 }
+/** This machine's normalized device id, resolved once — it can't change mid-process. */
+let _machineId;
+function cachedMachineId() {
+    return (_machineId ??= machineId());
+}
+function resolveProvenance(env = process.env) {
+    const p = {};
+    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
+    if (sessionId)
+        p.sessionId = sessionId;
+    if (env.AGENTS_AGENT_NAME)
+        p.agent = env.AGENTS_AGENT_NAME;
+    if (env.AGENT_LAUNCH_ID)
+        p.launchId = env.AGENT_LAUNCH_ID;
+    if (env.AGENTS_PARENT_SESSION_ID)
+        p.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
+    return p;
+}
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the append-only audit log.
@@ -303,11 +343,14 @@ export function emit(event, payload = {}) {
         const caller = detectCaller();
         const safePayload = sanitizePayload(payload);
         const record = {
+            // Provenance floor first: env-sourced defaults an explicit payload overrides.
+            ...resolveProvenance(),
             ...safePayload,
             ts: new Date().toISOString(),
             tz: getTimezoneOffset(),
             tzName: getTimezoneName(),
             hostname: os.hostname(),
+            machineId: cachedMachineId(),
             platform: os.platform(),
             arch: os.arch(),
             pid: process.pid,
@@ -375,22 +418,42 @@ export function time(label, fn, payload = {}) {
     const start = Date.now();
     try {
         const result = fn();
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'success',
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'success',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         return result;
     }
     catch (err) {
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'error',
             error: err instanceof Error ? err.message : String(err),
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'error',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         throw err;
     }
 }
@@ -405,22 +468,42 @@ export async function timeAsync(label, fn, payload = {}) {
     const start = Date.now();
     try {
         const result = await fn();
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'success',
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'success',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         return result;
     }
     catch (err) {
+        const durationMs = Date.now() - start;
         emit('perf.timing', {
             ...payload,
             label,
-            durationMs: Date.now() - start,
+            durationMs,
             status: 'error',
             error: err instanceof Error ? err.message : String(err),
         });
+        recordPerfTiming({
+            label,
+            durationMs,
+            status: 'error',
+            agent: payload.agent,
+            version: payload.version,
+            sessionId: payload.sessionId,
+            cwd: payload.cwd,
+        });
         throw err;
     }
 }
@@ -449,13 +532,22 @@ export function createTimer(label, payload = {}) {
         },
         end(endPayload = {}) {
             const durationMs = Date.now() - start;
+            const merged = { ...payload, ...endPayload };
             emit('perf.timing', {
-                ...payload,
-                ...endPayload,
+                ...merged,
                 label,
                 durationMs,
                 phases: marks,
             });
+            recordPerfTiming({
+                label,
+                durationMs,
+                status: typeof merged.status === 'string' ? merged.status : undefined,
+                agent: merged.agent,
+                version: merged.version,
+                sessionId: merged.sessionId,
+                cwd: merged.cwd,
+            });
         },
     };
 }
@@ -472,22 +564,42 @@ export function withTiming(label, fn, basePayload = {}) {
         const start = Date.now();
         try {
             const result = await fn(...args);
+            const durationMs = Date.now() - start;
             emit('perf.timing', {
                 ...basePayload,
                 label,
-                durationMs: Date.now() - start,
+                durationMs,
                 status: 'success',
             });
+            recordPerfTiming({
+                label,
+                durationMs,
+                status: 'success',
+                agent: basePayload.agent,
+                version: basePayload.version,
+                sessionId: basePayload.sessionId,
+                cwd: basePayload.cwd,
+            });
             return result;
         }
         catch (err) {
+            const durationMs = Date.now() - start;
             emit('perf.timing', {
                 ...basePayload,
                 label,
-                durationMs: Date.now() - start,
+                durationMs,
                 status: 'error',
                 error: err instanceof Error ? err.message : String(err),
             });
+            recordPerfTiming({
+                label,
+                durationMs,
+                status: 'error',
+                agent: basePayload.agent,
+                version: basePayload.version,
+                sessionId: basePayload.sessionId,
+                cwd: basePayload.cwd,
+            });
             throw err;
         }
     };
@@ -756,6 +868,7 @@ export function getLogsPath() {
 export function _resetForTest(overrideEventsPath) {
     _eventsPath = overrideEventsPath;
     _origin = undefined;
+    _machineId = undefined;
     _chmoddedPath = undefined;
     lastRotationCheck = 0;
 }

package/dist/lib/exec.js

@@ -373,6 +373,16 @@ export function buildExecEnv(options) {
         result.AGENT_SESSION_ID = options.sessionId;
         result.AGENTS_SESSION_ID = options.sessionId;
     }
+    // Lineage edge: the child's parent is THIS process's session (the spawner), so a
+    // sub-agent's events carry a walkable edge back to who spawned it. The event floor
+    // (events.ts::resolveProvenance) reads AGENTS_PARENT_SESSION_ID and stamps it on
+    // every event the child emits. `options.sessionId` is the CHILD's id, so read the
+    // spawner from the live env; guard a same-session resume from naming itself parent.
+    // Local-spawn scope here; forwarding it across the `--host` SSH hop is Phase 4.
+    const spawnerSessionId = process.env.AGENTS_SESSION_ID || process.env.AGENT_SESSION_ID;
+    if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
+        result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
+    }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
     // So activity / feed posts stamp the right harness without re-detecting.
     if (options.agent) {

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

@@ -28,7 +28,54 @@ export interface FeedBroadcastContext {
     session?: string;
     /** URLs attached to the post — the PR, the ticket, a shared plan. */
     links?: string[];
+    /** Block-only: the block's stable id. Absent on a status post. */
+    blockId?: string;
+    /** Block-only: `approval` (has a safe default) or `decision` (needs a human). */
+    class?: string;
+    /** Block-only: cost-of-delay tag used by the urgency filter. */
+    cost?: string;
+    /** Block-only: the literal `agents focus <id>` command that unblocks it. */
+    focus?: string;
 }
+/**
+ * Map an open block onto the broadcast context, so a block reaches the same sinks
+ * a post does instead of dying in the ledger.
+ *
+ * The `text` is the ask itself, front-loaded — a notification banner shows roughly
+ * two lines, and a phone message is scanned, not read. `focus` carries the literal
+ * command that unblocks it, so the message the operator receives contains the one
+ * action they have to take rather than making them go find the session.
+ *
+ * Level is always `important`: a block is by definition an agent that has stopped
+ * making progress, so there is no per-block level flag to get wrong.
+ */
+export declare function blockBroadcastContext(block: {
+    blockId: string;
+    sessionId: string;
+    host?: string;
+    questions?: Array<{
+        text?: string;
+    }>;
+    blockClass?: string;
+    costOfDelay?: string;
+    ticket?: string;
+    pr?: string;
+}, extras?: {
+    project?: string;
+    agent?: string;
+}): FeedBroadcastContext;
+/**
+ * Why a declared block reached nobody, or undefined when it got through.
+ *
+ * Pure so the fail-loud contract is testable without driving the CLI — the
+ * original version lived inline in the command action and was consequently
+ * never covered, which is how a `--json` early-return quietly bypassed it.
+ *
+ * Only a TOTAL failure counts. One sink failing among several is a warning, not
+ * an error: the channels are redundant by design, and a dead `rush` login must
+ * not mask a delivered desktop notification.
+ */
+export declare function blockDeliveryFailure(blocked: boolean, outcomes: SinkOutcome[]): string | undefined;
 export interface PlannedSink {
     name: string;
     argv: string[];

package/dist/lib/feed-broadcast.js

@@ -35,6 +35,61 @@ export function parseFeedPostLevel(raw) {
         return 'important';
     throw new Error(`Unknown --level '${raw}'. Use milestone or important.`);
 }
+/**
+ * Map an open block onto the broadcast context, so a block reaches the same sinks
+ * a post does instead of dying in the ledger.
+ *
+ * The `text` is the ask itself, front-loaded — a notification banner shows roughly
+ * two lines, and a phone message is scanned, not read. `focus` carries the literal
+ * command that unblocks it, so the message the operator receives contains the one
+ * action they have to take rather than making them go find the session.
+ *
+ * Level is always `important`: a block is by definition an agent that has stopped
+ * making progress, so there is no per-block level flag to get wrong.
+ */
+export function blockBroadcastContext(block, extras = {}) {
+    const ask = block.questions?.[0]?.text?.trim() || 'agent is blocked';
+    const links = [block.pr].filter((l) => !!l && /^https?:\/\//i.test(l));
+    return {
+        text: ask,
+        level: 'important',
+        ticket: block.ticket,
+        project: extras.project,
+        agent: extras.agent,
+        host: block.host,
+        session: block.sessionId,
+        blockId: block.blockId,
+        class: block.blockClass,
+        cost: block.costOfDelay,
+        // Short id: `agents focus` matches on a prefix, and a full uuid in a phone
+        // message is noise the operator has to skip past to reach the verb.
+        focus: `agents focus ${block.sessionId.slice(0, 8)}`,
+        ...(links.length ? { links } : {}),
+    };
+}
+/**
+ * Why a declared block reached nobody, or undefined when it got through.
+ *
+ * Pure so the fail-loud contract is testable without driving the CLI — the
+ * original version lived inline in the command action and was consequently
+ * never covered, which is how a `--json` early-return quietly bypassed it.
+ *
+ * Only a TOTAL failure counts. One sink failing among several is a warning, not
+ * an error: the channels are redundant by design, and a dead `rush` login must
+ * not mask a delivered desktop notification.
+ */
+export function blockDeliveryFailure(blocked, outcomes) {
+    if (!blocked)
+        return undefined;
+    if (outcomes.length === 0) {
+        return 'Block recorded but NOT delivered — no feed.broadcast sink configured.';
+    }
+    if (outcomes.every((o) => !o.ok)) {
+        const why = outcomes.map((o) => `${o.name}: ${o.error ?? 'failed'}`).join('; ');
+        return `Block recorded but NOT delivered — every feed.broadcast sink failed (${why}).`;
+    }
+    return undefined;
+}
 const PLACEHOLDER = /\{([a-z]+)\}/g;
 /**
  * A human-facing one-liner for a messaging sink: what project, what happened,
@@ -45,7 +100,12 @@ const PLACEHOLDER = /\{([a-z]+)\}/g;
 export function composeBroadcastMessage(ctx) {
     const head = ctx.project ? `${ctx.project} · ${ctx.text}` : ctx.text;
     const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
-    return link ? `${head}\n${link}` : head;
+    // A block's second line is the command that unblocks it. The operator reading
+    // this on a phone should not have to go find the session — the one action they
+    // must take travels with the ask. A status post has no such action, so it keeps
+    // the link there instead.
+    const tail = [ctx.focus, link].filter(Boolean);
+    return tail.length ? `${head}\n${tail.join('\n')}` : head;
 }
 /** The values a template may reference, resolved once per post. */
 function templateVars(ctx) {
@@ -59,6 +119,10 @@ function templateVars(ctx) {
         level: ctx.level,
         links: ctx.links?.length ? ctx.links.join(' ') : undefined,
         message: composeBroadcastMessage(ctx),
+        block: ctx.blockId,
+        class: ctx.class,
+        cost: ctx.cost,
+        focus: ctx.focus,
     };
 }
 /**

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

@@ -9,6 +9,16 @@ export interface FeedPostInput {
     sessionId?: string;
     /** Generic artifacts to attach: local paths (copied for durability) or URLs. */
     attach?: string[];
+    /**
+     * The agent is STUCK, not merely reporting. Writes `status.blocked` instead of
+     * `status.posted`, and the caller pairs it with an OpenBlock so the ask stays
+     * answerable until someone resolves it.
+     *
+     * This is a state, not a volume: a blocked post is always broadcast at
+     * `important`, so an agent never has to decide the level as well. One thing to
+     * say is what makes the habit stick.
+     */
+    blocked?: boolean;
     /** Override activity root (tests). */
     activityRoot?: string;
     /**

package/dist/lib/feed-post.js

@@ -271,7 +271,7 @@ export function postFeedStatus(input) {
     });
     const event = {
         ts,
-        event: 'status.posted',
+        event: input.blocked ? 'status.blocked' : 'status.posted',
         sessionId: identity.sessionId,
         mailboxId: identity.mailboxId,
         host: identity.host,

package/dist/lib/feed.d.ts

@@ -38,7 +38,20 @@ export interface OpenBlock {
     runtime: string;
     ts: string;
     questions: BlockQuestion[];
-    kind?: 'question' | 'notification' | 'control';
+    /**
+     * How this block came to exist.
+     *   question     — an AskUserQuestion the harness surfaced
+     *   notification — a permission/idle prompt the harness raised
+     *   control      — a synthetic card the feed itself computed (runaway, needy)
+     *   declared     — the AGENT decided it is stuck and said so (`feed post --blocked`)
+     *
+     * `declared` is the only kind that does not depend on the harness noticing
+     * anything. Every other kind is inferred from a harness event, and hook events
+     * are not portable across harnesses (only Claude fires Notification, only Codex
+     * fires PermissionRequest), so a declared block is the one signal every agent
+     * can raise — it is just a shell command.
+     */
+    kind?: 'question' | 'notification' | 'control' | 'declared';
     notificationType?: string;
     ticket?: string;
     pr?: string;
@@ -159,6 +172,39 @@ export declare function recordNotified(blockId: string, root?: string): void;
 export declare function recordTerminalAnswer(blockId: string, root?: string): void;
 /** Remove answered marker and receipts for a block (used by block removal/GC). */
 export declare function clearBlockLifecycle(blockId: string, root?: string): void;
+/** Identity of the agent declaring a block — the subset of `PostIdentity` it needs. */
+export interface DeclaringAgent {
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+}
+export interface DeclareBlockInput {
+    /** What the agent needs from the user, front-loaded. */
+    text: string;
+    /** Answerable choices, if the ask is a pick-one. */
+    options?: string[];
+    /** A safe default makes this an approval; without one it is a decision. */
+    safeDefault?: string;
+    /** Minutes before the default-on-no-answer policy may fire. */
+    timeoutMinutes?: number;
+    ts?: string;
+}
+/**
+ * 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.
+ */
+export declare function buildDeclaredBlock(agent: DeclaringAgent, input: DeclareBlockInput): OpenBlock;
 /** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export declare function publishBlock(block: OpenBlock, root?: string): void;
 /** Read all block records. Returns them sorted by stable block filename. */