@phnx-labs/agents-cli 1.20.93 → 1.21.1

package/dist/lib/hooks.js

@@ -952,6 +952,44 @@ export function listCentralHooks() {
     }
     return results;
 }
+/**
+ * Normalize a hook `timeout` from agents.yaml into a whole number of seconds.
+ *
+ * A bare number stays seconds (`timeout: 30` → 30) for backward compatibility.
+ * A Go-style duration string is parsed into seconds: `5s`, `2m`, `1h30m`,
+ * `90s`, `1h`. This intentionally does NOT reuse {@link parseTimeout} from
+ * routines.ts — that one returns milliseconds, has no seconds (`s`) unit, and
+ * floors at one minute, none of which fit hook timeouts (typically 5–600s).
+ *
+ * Returns the seconds value, or `null` when the input is not a positive number
+ * or a parseable duration string — the caller decides how to surface that.
+ */
+export function normalizeHookTimeoutSeconds(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && value > 0 ? value : null;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (s === '')
+            return null;
+        // A bare integer string means seconds, matching the bare-number form.
+        if (/^\d+$/.test(s)) {
+            const n = Number(s);
+            return n > 0 ? n : null;
+        }
+        const m = s.match(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/i);
+        if (!m)
+            return null;
+        const weeks = Number(m[1] || 0);
+        const days = Number(m[2] || 0);
+        const hours = Number(m[3] || 0);
+        const minutes = Number(m[4] || 0);
+        const seconds = Number(m[5] || 0);
+        const total = ((weeks * 7 + days) * 24 + hours) * 3600 + minutes * 60 + seconds;
+        return total > 0 ? total : null;
+    }
+    return null;
+}
 /**
  * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
@@ -959,7 +997,9 @@ export function listCentralHooks() {
  * A user entry with `enabled: false` disables the system-shipped hook of
  * the same name without forking the system file.
  *
- * Hooks marked `enabled: false` are dropped from the returned map.
+ * Hooks marked `enabled: false` are dropped from the returned map. A hook
+ * `timeout` written as a duration string (`5s`, `2m`) is normalized to a
+ * seconds number here, so every downstream serializer keeps reading a number.
  */
 export function parseHookManifest(opts = {}) {
     const warn = opts.warn !== false;
@@ -1026,6 +1066,26 @@ export function parseHookManifest(opts = {}) {
         if (def.enabled === false)
             delete merged[name];
     }
+    // Normalize each surviving hook's timeout to a seconds number, so the raw
+    // agents.yaml can express it as a duration string (`5s`, `2m`) while every
+    // downstream serializer keeps consuming a plain number. An unparseable value
+    // is dropped with a warning rather than silently coerced to a wrong duration.
+    for (const [name, def] of Object.entries(merged)) {
+        const raw = def.timeout;
+        if (raw === undefined)
+            continue;
+        const seconds = normalizeHookTimeoutSeconds(raw);
+        if (seconds === null) {
+            if (warn) {
+                console.warn(`[agents hooks] Hook '${name}' has an invalid timeout ${JSON.stringify(raw)}; ` +
+                    `expected seconds or a duration string like '5s', '2m', '1h30m'. Ignoring it.`);
+            }
+            delete def.timeout;
+        }
+        else {
+            def.timeout = seconds;
+        }
+    }
     return merged;
 }
 export function selectHookManifest(manifest, selected) {

package/dist/lib/linear-project-counts.d.ts

@@ -7,6 +7,12 @@
  * TYPE (triage / backlog / unstarted / started / completed / canceled), never
  * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
  *
+ * The same fetch also yields the **next milestone** — the earliest-dated
+ * milestone with unfinished issues — because each issue node carries its
+ * `projectMilestone`. A percentage tells you how far along a project is; the
+ * milestone tells you what it is due to hit next, which is the thing a person
+ * actually plans around. Deriving it here costs no extra request.
+ *
  * This is a best-effort card enrichment, not an explicit command: every failure
  * (no credential, offline, API error, timeout) degrades to `undefined` and the
  * card simply omits the line — never a hang, never a throw. `--no-remote`
@@ -18,6 +24,32 @@
  * budget; a capped fetch reports `truncated: true` and the card renders the
  * total as a lower bound (`2500+ done`), never as the complete count.
  */
+/**
+ * The next checkpoint the project is working toward: the earliest-dated
+ * milestone that still has unfinished issues. A percentage says how far along
+ * the project is; this says what it is due to hit next.
+ */
+export interface LinearMilestone {
+    name: string;
+    /** `YYYY-MM-DD` as Linear stores it. Absent when the milestone has no date. */
+    targetDate?: string;
+    /** Issues in this milestone in a `completed`-type state. */
+    done: number;
+    /**
+     * Issues assigned to this milestone. Legitimately `0` — a milestone can be
+     * declared with a date long before any issue is filed under it (that is the
+     * state of every milestone in this repo's own Linear project), and such a
+     * milestone is still the next checkpoint. The card omits the fraction rather
+     * than printing a meaningless `0/0`.
+     */
+    total: number;
+}
+/** A milestone as the project declares it, independent of any issue. */
+export interface LinearMilestoneNode {
+    id?: string;
+    name?: string;
+    targetDate?: string | null;
+}
 /** The counts the card renders. `total` counts every issue in the project. */
 export interface LinearProjectCounts {
     /** Issues in a `completed`-type state. */
@@ -31,20 +63,40 @@ export interface LinearProjectCounts {
      * bound (rendered `2500+`), never presented as the complete count.
      */
     truncated?: boolean;
+    /**
+     * The next unfinished milestone, when the project has one. Derived from the
+     * SAME paged issue fetch as the counts — a milestone is only ever a grouping
+     * of these issues, so asking Linear again would spend a second round trip to
+     * learn what the first already said.
+     */
+    nextMilestone?: LinearMilestone;
+}
+/** One issue node as the query selects it. */
+export interface LinearIssueNode {
+    state?: {
+        type?: string;
+    } | null;
+    projectMilestone?: {
+        id?: string;
+        name?: string;
+        targetDate?: string | null;
+    } | null;
 }
 /** The GraphQL response shape this module consumes (recorded for the tests). */
 export interface LinearIssuesResponse {
     issues?: {
-        nodes?: Array<{
-            state?: {
-                type?: string;
-            } | null;
-        }>;
+        nodes?: LinearIssueNode[];
         pageInfo?: {
             hasNextPage?: boolean;
             endCursor?: string | null;
         };
     };
+    /** Only the FIRST page asks for this — the milestone list does not paginate. */
+    project?: {
+        projectMilestones?: {
+            nodes?: LinearMilestoneNode[];
+        };
+    } | null;
 }
 /**
  * Pure mapping: a Linear issues response → card counts, grouping by state
@@ -52,6 +104,21 @@ export interface LinearIssuesResponse {
  * an issue with no state still counts toward `total`.
  */
 export declare function countsFromIssuesResponse(data: LinearIssuesResponse): LinearProjectCounts;
+/**
+ * Pick the milestone the project is working toward next.
+ *
+ * The **declared** list is authoritative for which milestones exist, their
+ * names, and their dates; issues only supply progress. Deriving the list from
+ * issues instead looks tempting (it costs no extra request) and is wrong: a
+ * milestone with nothing filed under it yet would be invisible, and that is the
+ * common case — every milestone in this repo's own Linear project has zero
+ * issues assigned, so an issue-derived list showed nothing at all.
+ *
+ * Next = the earliest-dated milestone that is not finished. A milestone with no
+ * issues counts as unfinished (it is upcoming work, not completed work). Undated
+ * milestones sort last, ties break by declaration order, so the answer is stable.
+ */
+export declare function nextMilestone(declared: LinearMilestoneNode[], nodes: LinearIssueNode[]): LinearMilestone | undefined;
 /**
  * Fetch issue counts for one Linear project, paging `issues` filtered by
  * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;

package/dist/lib/linear-project-counts.js

@@ -7,6 +7,12 @@
  * TYPE (triage / backlog / unstarted / started / completed / canceled), never
  * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
  *
+ * The same fetch also yields the **next milestone** — the earliest-dated
+ * milestone with unfinished issues — because each issue node carries its
+ * `projectMilestone`. A percentage tells you how far along a project is; the
+ * milestone tells you what it is due to hit next, which is the thing a person
+ * actually plans around. Deriving it here costs no extra request.
+ *
  * This is a best-effort card enrichment, not an explicit command: every failure
  * (no credential, offline, API error, timeout) degrades to `undefined` and the
  * card simply omits the line — never a hang, never a throw. `--no-remote`
@@ -44,7 +50,65 @@ export function countsFromIssuesResponse(data) {
         else if (type === 'started')
             inProgress++;
     }
-    return { done, total: nodes.length, inProgress };
+    const counts = { done, total: nodes.length, inProgress };
+    const next = nextMilestone(data.project?.projectMilestones?.nodes ?? [], nodes);
+    if (next)
+        counts.nextMilestone = next;
+    return counts;
+}
+/**
+ * Pick the milestone the project is working toward next.
+ *
+ * The **declared** list is authoritative for which milestones exist, their
+ * names, and their dates; issues only supply progress. Deriving the list from
+ * issues instead looks tempting (it costs no extra request) and is wrong: a
+ * milestone with nothing filed under it yet would be invisible, and that is the
+ * common case — every milestone in this repo's own Linear project has zero
+ * issues assigned, so an issue-derived list showed nothing at all.
+ *
+ * Next = the earliest-dated milestone that is not finished. A milestone with no
+ * issues counts as unfinished (it is upcoming work, not completed work). Undated
+ * milestones sort last, ties break by declaration order, so the answer is stable.
+ */
+export function nextMilestone(declared, nodes) {
+    // Progress per milestone id, from whatever issues do carry one.
+    const progress = new Map();
+    for (const n of nodes) {
+        const id = n?.projectMilestone?.id;
+        if (!id)
+            continue;
+        const p = progress.get(id) ?? { done: 0, total: 0 };
+        p.total++;
+        if (n.state?.type === 'completed')
+            p.done++;
+        progress.set(id, p);
+    }
+    const candidates = declared
+        .map((d, order) => {
+        if (!d?.id || typeof d.name !== 'string' || !d.name)
+            return undefined;
+        const p = progress.get(d.id) ?? { done: 0, total: 0 };
+        const m = { name: d.name, done: p.done, total: p.total, order };
+        if (d.targetDate)
+            m.targetDate = d.targetDate;
+        return m;
+    })
+        .filter((m) => m !== undefined)
+        // total 0 means "declared, nothing filed yet" — unfinished, not done.
+        .filter((m) => m.total === 0 || m.done < m.total);
+    if (candidates.length === 0)
+        return undefined;
+    candidates.sort((a, b) => {
+        if (a.targetDate && b.targetDate)
+            return a.targetDate < b.targetDate ? -1 : a.targetDate > b.targetDate ? 1 : a.order - b.order;
+        if (a.targetDate)
+            return -1;
+        if (b.targetDate)
+            return 1;
+        return a.order - b.order;
+    });
+    const { order: _order, ...m } = candidates[0];
+    return m;
 }
 /** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
 function resolveApiKey() {
@@ -71,12 +135,16 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
     const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
     try {
         const all = [];
+        // Declared on the project, not on its issues — only page 0 asks for it.
+        let declared = [];
         let after;
         let truncated = false;
         for (let page = 0;; page++) {
             const data = await fetchPage(projectId, after, ctrl.signal);
             if (!data)
                 return undefined;
+            if (page === 0)
+                declared = data.project?.projectMilestones?.nodes ?? [];
             all.push(...(data.issues?.nodes ?? []));
             const pi = data.issues?.pageInfo;
             if (!pi?.hasNextPage || !pi.endCursor)
@@ -88,7 +156,13 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
             }
             after = pi.endCursor;
         }
-        return { ...countsFromIssuesResponse({ issues: { nodes: all } }), ...(truncated ? { truncated } : {}) };
+        return {
+            ...countsFromIssuesResponse({
+                issues: { nodes: all },
+                project: { projectMilestones: { nodes: declared } },
+            }),
+            ...(truncated ? { truncated } : {}),
+        };
     }
     catch {
         return undefined;
@@ -102,14 +176,24 @@ async function fetchLinearIssuesPage(projectId, after, signal) {
     const apiKey = resolveApiKey();
     if (!apiKey)
         return undefined;
+    // The declared-milestone list rides along on the FIRST page only — it does
+    // not paginate, and re-requesting it per page would spend up to MAX_PAGES
+    // copies of the same answer.
+    const issuesSelection = 'issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
+        PAGE_SIZE +
+        ', after:$after){ nodes{ state{ type } projectMilestone{ id } } pageInfo{ hasNextPage endCursor } }';
+    const milestonesSelection = 'project(id:$pid){ projectMilestones(first:50){ nodes{ id name targetDate } } }';
+    const first = after === undefined;
     const res = await fetch(LINEAR_API, {
         method: 'POST',
         headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
         body: JSON.stringify({
-            query: 'query($p:ID!, $after:String){ issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
-                PAGE_SIZE +
-                ', after:$after){ nodes{ state{ type } } pageInfo{ hasNextPage endCursor } } }',
-            variables: { p: projectId, after: after ?? null },
+            query: first
+                ? `query($p:ID!, $pid:String!, $after:String){ ${issuesSelection} ${milestonesSelection} }`
+                : `query($p:ID!, $after:String){ ${issuesSelection} }`,
+            variables: first
+                ? { p: projectId, pid: projectId, after: null }
+                : { p: projectId, after },
         }),
         signal,
     });

package/dist/lib/linear-projects.d.ts

@@ -24,6 +24,18 @@ export declare function normalizeProjectKey(s: string): string;
  * path.
  */
 export declare function matchLinearProject(slugOrName: string, projects: LinearProjectLite[]): LinearProjectLite | undefined;
+/**
+ * Find the local checkout directory a Linear project name refers to, on EXACT
+ * key equality only — never containment. `matchLinearProject`'s containment
+ * fallback is right for suggesting a link a human then confirms; this backs
+ * `projects import --from-linear`, which writes `root`/`repo` with nobody
+ * looking, and "Agents CLI" must not silently bind `agents-cli-web`.
+ *
+ * Returns `undefined` when nothing matches, and also when SEVERAL dirs key to
+ * the same value (`agents-cli` and `agents_cli`) — an ambiguous match is not a
+ * match.
+ */
+export declare function matchLocalCheckoutExact(name: string, dirNames: string[]): string | undefined;
 /** The outcome of picking one Linear project out of the workspace list. */
 export type LinearPick = {
     kind: 'match';

package/dist/lib/linear-projects.js

@@ -45,6 +45,36 @@ export function matchLinearProject(slugOrName, projects) {
         return pk.length > 0 && (pk.includes(key) || key.includes(pk));
     });
 }
+/**
+ * Collapse a Linear **display name** or a directory basename to one comparison
+ * key. Deliberately NOT `normalizeProjectKey`: that one keeps only the segment
+ * after the last `/`, which is right for an `owner/repo` slug or a filesystem
+ * path and wrong for a display name, where `/` is ordinary punctuation. Keying
+ * "Rush / Web" the path way yields `web`, which exact-matches an unrelated
+ * `web/` checkout — the precise silent mis-binding this whole match path exists
+ * to prevent.
+ */
+function checkoutMatchKey(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+/**
+ * Find the local checkout directory a Linear project name refers to, on EXACT
+ * key equality only — never containment. `matchLinearProject`'s containment
+ * fallback is right for suggesting a link a human then confirms; this backs
+ * `projects import --from-linear`, which writes `root`/`repo` with nobody
+ * looking, and "Agents CLI" must not silently bind `agents-cli-web`.
+ *
+ * Returns `undefined` when nothing matches, and also when SEVERAL dirs key to
+ * the same value (`agents-cli` and `agents_cli`) — an ambiguous match is not a
+ * match.
+ */
+export function matchLocalCheckoutExact(name, dirNames) {
+    const key = checkoutMatchKey(name);
+    if (!key)
+        return undefined;
+    const hits = dirNames.filter((d) => checkoutMatchKey(d) === key);
+    return hits.length === 1 ? hits[0] : undefined;
+}
 /**
  * Pick the Linear project a query refers to. An exact id or exact normalized
  * name match is confident enough to write; anything weaker (several exact-name

package/dist/lib/mailbox-gc.js

@@ -8,9 +8,9 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getMailboxRootDir } from './state.js';
+import { getFeedDir, getMailboxRootDir } from './state.js';
 import { mailboxDir, isValidMailboxId, readMessage, sweepExpired, } from './mailbox.js';
-import { listBlocks, removeBlock } from './feed.js';
+import { listBlocks, removeBlock, recordMessageReceipt } from './feed.js';
 const DEFAULT_MAX_CONSUMED_AGE_MINUTES = 24 * 60;
 function consumedAgeMinutes(file, now) {
     try {
@@ -31,7 +31,7 @@ function jsonFiles(dir) {
     }
     return names.filter((n) => n.endsWith('.json')).sort();
 }
-function archiveAllPending(boxDir, reason) {
+function archiveAllPending(boxDir, reason, feedRoot) {
     let n = 0;
     for (const dir of [path.join(boxDir, 'inbox'), path.join(boxDir, 'processing')]) {
         for (const name of jsonFiles(dir)) {
@@ -45,6 +45,14 @@ function archiveAllPending(boxDir, reason) {
                     fs.writeFileSync(tmp, JSON.stringify(msg, null, 2), 'utf-8');
                     fs.renameSync(tmp, dest);
                     fs.unlinkSync(src);
+                    if (msg.blockId) {
+                        try {
+                            recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: reason === 'expired' ? 'expired' : 'dropped', at: new Date().toISOString(), from: msg.from }, feedRoot);
+                        }
+                        catch {
+                            // Receipt surfacing is best-effort; never stall GC.
+                        }
+                    }
                 }
                 else {
                     fs.renameSync(src, dest);
@@ -58,6 +66,16 @@ function archiveAllPending(boxDir, reason) {
     }
     return n;
 }
+function blockAgeMinutes(blockId, feedRoot, now) {
+    const file = path.join(feedRoot ?? getFeedDir(), `${blockId}.json`);
+    try {
+        const stat = fs.statSync(file);
+        return (now.getTime() - stat.mtimeMs) / 60_000;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
 function pruneConsumed(boxDir, maxAgeMinutes, now) {
     let n = 0;
     const consumed = path.join(boxDir, 'consumed');
@@ -115,7 +133,7 @@ export function gcMailbox(activeBoxIds, options = {}) {
         const boxDir = mailboxDir(name, root);
         if (!activeBoxIds.has(name)) {
             result.deadBoxes++;
-            result.messagesDroppedDead += archiveAllPending(boxDir, 'dead');
+            result.messagesDroppedDead += archiveAllPending(boxDir, 'dead', feedRoot);
             result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
             // Also prune the empty box dir if it is now empty.
             try {
@@ -136,13 +154,18 @@ export function gcMailbox(activeBoxIds, options = {}) {
         else {
             // Live box: archive expired messages (same path as drain/peek) so GC does
             // not leave expired files in inbox/processing while only bumping metrics.
-            result.messagesDroppedExpired += sweepExpired(boxDir, name, now);
+            result.messagesDroppedExpired += sweepExpired(boxDir, name, now, feedRoot);
             result.consumedPruned += pruneConsumed(boxDir, maxConsumedAgeMinutes, now);
         }
     }
     for (const blockId of blocksToRemove) {
-        if (removeBlock(blockId, feedRoot)) {
-            result.blocksRemoved++;
+        // A dead box's block is kept for up to maxConsumedAgeMinutes after a bounce
+        // receipt is written so the operator/sender can see the failure. Stale blocks
+        // (older than the prune window) are removed.
+        if (blockAgeMinutes(blockId, feedRoot, now) >= maxConsumedAgeMinutes) {
+            if (removeBlock(blockId, feedRoot)) {
+                result.blocksRemoved++;
+            }
         }
     }
     return result;

package/dist/lib/mailbox.d.ts

@@ -1,3 +1,13 @@
+/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
+export declare const DEFAULT_TTL_SECONDS: number;
+/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
+export declare const MAILBOX_TTL_ENV = "AGENTS_MAILBOX_TTL";
+/**
+ * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
+ * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
+ * fails loud instead of silently disabling expiry.
+ */
+export declare function resolveDefaultTtlSeconds(): number;
 /** A single mailbox message. `text` may embed `host:/path` clip tokens. */
 export interface MailboxMessage {
     /** Unique, time-sortable id. Also the on-disk filename stem. */
@@ -54,8 +64,11 @@ export declare function isExpired(msg: MailboxMessage, now?: Date): boolean;
 /**
  * Move expired messages from inbox/ and processing/ into consumed/ with a
  * `dropped: expired` marker. Called by drain/peek before returning messages.
+ *
+ * When a dropped message carries a `blockId`, a failure receipt is surfaced
+ * back to the feed store so the sender sees the bounce.
  */
-export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date): number;
+export declare function sweepExpired(boxDir: string, boxId?: string, now?: Date, feedRoot?: string): number;
 /**
  * Drain the box: return every pending message addressed to it, in FIFO order,
  * removing them from the queue. Claim-first (inbox → processing → consumed) so

package/dist/lib/mailbox.js

@@ -20,6 +20,26 @@ import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { getMailboxRootDir } from './state.js';
 import { recordMessageReceipt } from './feed.js';
+import { parseDuration } from './hooks/cache.js';
+/** Default delivery TTL for messages enqueued without an explicit one (24 hours). */
+export const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+/** Env var that overrides {@link DEFAULT_TTL_SECONDS} with a duration like "24h" or "3600". */
+export const MAILBOX_TTL_ENV = 'AGENTS_MAILBOX_TTL';
+/**
+ * Resolve the default mailbox TTL in seconds. Honors `AGENTS_MAILBOX_TTL`
+ * (parsed by {@link parseDuration}); falls back to 24h. A malformed env value
+ * fails loud instead of silently disabling expiry.
+ */
+export function resolveDefaultTtlSeconds() {
+    const raw = process.env[MAILBOX_TTL_ENV];
+    if (raw == null || raw === '')
+        return DEFAULT_TTL_SECONDS;
+    const parsed = parseDuration(raw);
+    if (parsed == null || parsed <= 0) {
+        throw new Error(`Invalid ${MAILBOX_TTL_ENV}=${JSON.stringify(raw)}: expected a positive duration (e.g. 24h, 30m, 3600).`);
+    }
+    return parsed;
+}
 /**
  * A mailboxId must be a single, separator-free path segment. Real ids (session
  * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
@@ -78,8 +98,9 @@ export function enqueue(boxDir, msg) {
         text: msg.text,
         blockId: msg.blockId,
     };
-    if (msg.ttlSeconds != null && msg.ttlSeconds > 0) {
-        record.expiresAt = new Date(now.getTime() + msg.ttlSeconds * 1000).toISOString();
+    const ttlSeconds = msg.ttlSeconds ?? resolveDefaultTtlSeconds();
+    if (ttlSeconds > 0) {
+        record.expiresAt = new Date(now.getTime() + ttlSeconds * 1000).toISOString();
     }
     const target = path.join(inboxDir(boxDir), `${msgId}.json`);
     const tmp = `${target}.${process.pid}.tmp`;
@@ -139,8 +160,11 @@ function archiveDropped(boxDir, name, reason) {
 /**
  * Move expired messages from inbox/ and processing/ into consumed/ with a
  * `dropped: expired` marker. Called by drain/peek before returning messages.
+ *
+ * When a dropped message carries a `blockId`, a failure receipt is surfaced
+ * back to the feed store so the sender sees the bounce.
  */
-export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Date()) {
+export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Date(), feedRoot) {
     ensureDirs(boxDir);
     let n = 0;
     for (const dir of [inboxDir(boxDir), processingDir(boxDir)]) {
@@ -154,6 +178,14 @@ export function sweepExpired(boxDir, boxId = path.basename(boxDir), now = new Da
                     fs.writeFileSync(tmp, JSON.stringify(msg, null, 2), 'utf-8');
                     fs.renameSync(tmp, dest);
                     fs.unlinkSync(path.join(dir, name));
+                    if (msg.blockId) {
+                        try {
+                            recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: 'expired', at: new Date().toISOString(), from: msg.from }, feedRoot ?? process.env.AGENTS_FEED_DIR);
+                        }
+                        catch {
+                            // Receipt surfacing is best-effort; never stall expiry.
+                        }
+                    }
                     n++;
                 }
                 catch {

package/dist/lib/menubar/install-menubar.d.ts

@@ -34,29 +34,12 @@ export declare function codesignVerifies(appPath: string): boolean;
  * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
  * which macOS surfaces as "the app is damaged" and can crash AppKit during
  * launch. This is separate from `codesign --verify`: a signature can be valid
- * while Gatekeeper still refuses to run it.
+ * while Gatekeeper still refuses to run it. The release notarizes + staples the
+ * helper (menubar/scripts/build.sh, gated by verify-menubar-helper.sh), so a
+ * shipped bundle passes this; the launch guards use it to fail loud rather than
+ * bootstrap a helper macOS would reject.
  */
 export declare function gatekeeperAssesses(appPath: string): boolean;
-/**
- * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
- * machine.
- *
- * npm's pack/extract strips the ad-hoc/linker signature the release baked into
- * the helper, leaving `code object is not signed at all`. On macOS 26+ the
- * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
- * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
- * an ad-hoc release helper crash-loops forever and its unstable identity makes
- * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
- * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
- * matching cdhash, which the kernel accepts.
- *
- * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — but if the release was not notarized, Gatekeeper rejects it.
- * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
- * can launch locally. The stable fix is to notarize the release build; this
- * fallback just prevents a crash-loop while the user is on an un-notarized cut.
- */
-export declare function ensureValidSignature(appPath: string): boolean;
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
@@ -65,6 +48,7 @@ export declare function ensureValidSignature(appPath: string): boolean;
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;
 }): string | null;
+export declare function generateServicePlist(execPath: string): string;
 /**
  * Restart the menu-bar launchd agent from a clean state.
  *