@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/tmux/session.js

@@ -367,13 +367,14 @@ export async function paneExitStatus(pane, socket) {
  * Best-effort — returns false when tmux rejects the hook so callers do not
  * stamp a schema marker and daemon reconciliation can retry later.
  */
-export async function setSessionHook(name, hook, command, socket) {
+export async function setSessionHook(name, hook, command, socket, timeoutMs) {
     assertValidSessionName(name);
     const sock = socket ?? getDefaultSocketPath();
     const result = await runTmux({
         socket: sock,
         args: ['set-hook', '-t', name, hook, command],
         throwOnError: false,
+        timeoutMs,
     }).catch(() => null);
     return result?.code === 0;
 }
@@ -405,6 +406,15 @@ export async function setSessionHook(name, hook, command, socket) {
 export const AGENT_HOOK_SCHEMA = 5;
 /** Per-session tmux user-option that records which AGENT_HOOK_SCHEMA a session's hook is at. */
 const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
+/**
+ * Bound on every tmux call made by the hook-repair path (daemon startup,
+ * upgrade migration, and single-session repair-before-attach). A wedged tmux
+ * server would otherwise hang the caller indefinitely — exactly the class of
+ * bug RUSH-2507 fixed for `listTmuxAgentSessions`'s `list-panes` call, applied
+ * here to `reconcileSessionHooks`/`repairSessionHookIfStale`'s calls so a
+ * wedged shared socket can no longer wedge daemon startup (RUSH-2435 review).
+ */
+const TMUX_HOOK_REPAIR_TIMEOUT_MS = 5_000;
 /**
  * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
  * (so the blocking attach in runInTmux returns and the exit status can be read);
@@ -423,13 +433,13 @@ export function agentPaneDiedHook(sessionName, agentPane) {
     return `if -F '#{==:#{hook_pane},${agentPane}}' 'detach-client -s =${sessionName}' 'run-shell -b -C "kill-pane -t #{hook_pane}"'`;
 }
 /** Stamp a session's hook-schema marker to the current version. */
-export async function markSessionHookSchema(name, socket) {
+export async function markSessionHookSchema(name, socket, timeoutMs) {
     const sock = socket ?? getDefaultSocketPath();
-    await runTmux({ socket: sock, args: ['set-option', '-t', name, HOOK_SCHEMA_OPTION, String(AGENT_HOOK_SCHEMA)], throwOnError: false }).catch(() => { });
+    await runTmux({ socket: sock, args: ['set-option', '-t', name, HOOK_SCHEMA_OPTION, String(AGENT_HOOK_SCHEMA)], throwOnError: false, timeoutMs }).catch(() => { });
 }
 /** Read a session's hook-schema marker; undefined when unset (pre-marker sessions). */
-async function readHookSchema(name, socket) {
-    const res = await runTmux({ socket, args: ['show-options', '-v', '-t', name, HOOK_SCHEMA_OPTION], throwOnError: false }).catch(() => null);
+async function readHookSchema(name, socket, timeoutMs) {
+    const res = await runTmux({ socket, args: ['show-options', '-v', '-t', name, HOOK_SCHEMA_OPTION], throwOnError: false, timeoutMs }).catch(() => null);
     if (!res || res.code !== 0)
         return undefined;
     const v = res.stdout.trim();
@@ -441,8 +451,8 @@ async function readHookSchema(name, socket) {
  * for sessions whose SessionMeta (which records the agent pane) predates meta
  * persistence. Undefined when the session has no panes (already torn down).
  */
-async function lowestPaneId(name, socket) {
-    const res = await runTmux({ socket, args: ['list-panes', '-t', name, '-F', '#{pane_id}'], throwOnError: false }).catch(() => null);
+async function lowestPaneId(name, socket, timeoutMs) {
+    const res = await runTmux({ socket, args: ['list-panes', '-t', name, '-F', '#{pane_id}'], throwOnError: false, timeoutMs }).catch(() => null);
     if (!res || res.code !== 0)
         return undefined;
     const ids = res.stdout.split('\n').map(l => l.trim()).filter(id => /^%\d+$/.test(id));
@@ -467,11 +477,35 @@ export async function prepareSessionForResume(name, socket) {
         ? recordedPane
         : await lowestPaneId(name, sock);
     const state = pane ? await paneExitStatus(pane, sock) : undefined;
-    if (pane && state?.found && !state.dead)
+    if (pane && state?.found && !state.dead) {
+        // Self-heal a legacy/stale hook right before handing the session back to
+        // an attach client — the steady-state repair point between the daemon's
+        // startup and upgrade one-shots (RUSH-2435).
+        await ensureSessionHookRepaired(name, sock);
         return { decision: 'attach', pane };
+    }
     await killSession(name, sock);
     return { decision: 'create' };
 }
+/**
+ * Repair ONE session's `pane-died` hook if it predates AGENT_HOOK_SCHEMA.
+ * Idempotent and NON-DESTRUCTIVE — only `set-hook`s, never kills a pane or
+ * detaches a client. Shared by {@link reconcileSessionHooks} (full sweep) and
+ * {@link ensureSessionHookRepaired} (single session, called before attach) so
+ * the two can never drift on what counts as "repaired" (RUSH-2435).
+ */
+async function repairSessionHookIfStale(name, sock, meta, timeoutMs = TMUX_HOOK_REPAIR_TIMEOUT_MS) {
+    if (await readHookSchema(name, sock, timeoutMs) === String(AGENT_HOOK_SCHEMA))
+        return false;
+    const agentPane = meta?.pane ?? await lowestPaneId(name, sock, timeoutMs);
+    if (!agentPane)
+        return false;
+    const installed = await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, agentPane), sock, timeoutMs);
+    if (!installed)
+        return false;
+    await markSessionHookSchema(name, sock, timeoutMs);
+    return true;
+}
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:
@@ -481,9 +515,15 @@ export async function prepareSessionForResume(name, socket) {
  * exited a split — self-heals in place, without waiting for those agents to exit
  * or for the server to be recycled.
  *
- * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
- * marker makes steady-state a cheap no-op: a session already at the current
- * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * NOT a daemon poll — the 5-minute `tmux-reconcile` routine that used to call this
+ * was deleted (RUSH-2495). It survives as the version-skew ONE-SHOT: the daemon
+ * calls it once at startup (`runDaemon` in `../daemon.js`) and once from the
+ * upgrade-time migration (`runMigration` in `../migrate.js`), so a session a
+ * pre-fix binary left with a stale hook still self-heals without a live poller.
+ * `ensureSessionHookRepaired` covers the steady-state gap between those two
+ * points by repairing a single session right before it's attached to. The
+ * per-session `@ag_hook_schema` marker makes both paths a cheap no-op once a
+ * session is current. Only run-wrapped sessions (`ag-` prefix) are touched — an
  * externally-created session on the socket keeps whatever hook it set.
  */
 export async function reconcileSessionHooks(socket) {
@@ -492,7 +532,7 @@ export async function reconcileSessionHooks(socket) {
         return { scanned: 0, reconciled: 0 };
     let sessions;
     try {
-        sessions = await listSessions({ socket: sock });
+        sessions = await listSessions({ socket: sock, timeoutMs: TMUX_HOOK_REPAIR_TIMEOUT_MS });
     }
     catch {
         return { scanned: 0, reconciled: 0 };
@@ -501,19 +541,32 @@ export async function reconcileSessionHooks(socket) {
     for (const s of sessions) {
         if (!s.name.startsWith('ag-'))
             continue; // only run-wrapped sessions
-        if (await readHookSchema(s.name, sock) === String(AGENT_HOOK_SCHEMA))
-            continue;
-        const agentPane = s.meta?.pane ?? await lowestPaneId(s.name, sock);
-        if (!agentPane)
-            continue;
-        const installed = await setSessionHook(s.name, 'pane-died', agentPaneDiedHook(s.name, agentPane), sock);
-        if (!installed)
-            continue;
-        await markSessionHookSchema(s.name, sock);
-        reconciled++;
+        if (await repairSessionHookIfStale(s.name, sock, s.meta))
+            reconciled++;
     }
     return { scanned: sessions.length, reconciled };
 }
+/**
+ * Repair a single managed session's `pane-died` hook right before it is
+ * attached to, so a legacy session left by a pre-fix binary self-heals on the
+ * next touch instead of waiting for the next daemon-startup/upgrade one-shot
+ * (RUSH-2435). Only `ag-`-prefixed (run-wrapped) sessions are touched; a no-op
+ * for anything else. Best-effort — never throws, so a repair failure can never
+ * block the attach it is protecting.
+ */
+export async function ensureSessionHookRepaired(name, socket) {
+    if (!name.startsWith('ag-'))
+        return;
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return;
+    try {
+        await repairSessionHookIfStale(name, sock, readSessionMeta(name) ?? undefined);
+    }
+    catch {
+        // best-effort — an attach must never fail because a repair attempt did
+    }
+}
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)
@@ -532,6 +585,7 @@ export async function listSessions(opts = {}) {
         socket,
         args: ['list-sessions', '-F', fmt],
         throwOnError: false,
+        timeoutMs: opts.timeoutMs,
     });
     // tmux returns nonzero with "no server running" or "no sessions" — both mean empty.
     if (res.code !== 0) {

package/dist/lib/triggers/handlers.d.ts

@@ -5,9 +5,9 @@
  * project/system layers). They complement routine triggers: a matching webhook
  * can run an agent, workflow, shell command, or delegate to a routine.
  */
-import type { JobConfig, RunMeta, WebhookContext } from '../routines.js';
+import type { JobConfig, RunMeta, WebhookContext } from '../scheduling/routines.js';
 import type { AgentId } from '../types.js';
-import type { IncomingWebhook, WebhookSource } from './webhook.js';
+import type { IncomingWebhook, SlackPayload, WebhookSource } from './webhook.js';
 export interface WebhookHandler {
     name: string;
     enabled?: boolean;
@@ -21,6 +21,11 @@ export interface WebhookHandler {
     label?: string;
     repo?: string;
     branch?: string;
+    /** Slack (source: slack) only — match one slash command, e.g. `/agents`. */
+    command?: string;
+    /** Slack (source: slack) only — restrict to one channel id (`C0…`). Lets a
+     *  channel imply a project via a per-channel handler. */
+    channel?: string;
     /**
      * Where to run the action. A device name (`yosemite-s0`) runs there over SSH;
      * `fleet` picks any eligible online worker; `fleet/<platform>` (or
@@ -92,10 +97,40 @@ export declare function resolveHandlerHost(host: string | undefined): HandlerHos
 export declare function listHandlers(cwd?: string): WebhookHandler[];
 /** Pure matcher: does this handler match the incoming webhook? */
 export declare function handlerMatchesWebhook(handler: WebhookHandler, webhook: IncomingWebhook): boolean;
+/**
+ * The `{{slack.*}}` substitution namespace: a Slack message split into an
+ * agent-actionable project + prompt, plus the coordinates a reply threads into.
+ */
+export interface SlackMessageContext {
+    /** The message with a leading bot mention stripped. */
+    text: string;
+    /** The `PROJECT:` token at the head of the message, or '' when absent. */
+    project: string;
+    /** The request — the text after `PROJECT:`, or the whole message. */
+    prompt: string;
+    /** Channel id to reply into (`C0…`). */
+    channel: string;
+    /** Thread ts to reply into (empty for a slash command → reply to the channel). */
+    thread_ts: string;
+    /** Invoking user id (`U0…`). */
+    user: string;
+    /** Slash command name (`/agents`), or '' for an event delivery. */
+    command: string;
+}
+/**
+ * Split a Slack message into a `{{slack.*}}` context. Strips a leading bot
+ * mention (`<@U0BOT> …`), then reads an optional `PROJECT:` prefix — a single
+ * bare token followed by a colon and a space — as the project, with the
+ * remainder the prompt. `AGI: rebase my PR` → project `AGI`, prompt
+ * `rebase my PR`; a message with no such prefix leaves `project` empty and the
+ * whole text as the prompt. The token pattern forbids slashes, so a project
+ * value can never carry a path into a `cwd`/`project` substitution.
+ */
+export declare function parseSlackMessage(payload: SlackPayload): SlackMessageContext;
 /**
  * Build the variable-substitution context for a webhook. Linear events expose
  * `issue` and `updatedFrom`; GitHub events expose `repository`, `pull_request`,
- * and `issue`.
+ * and `issue`; Slack events expose the `{{slack.*}}` namespace above.
  */
 export declare function buildWebhookContext(webhook: IncomingWebhook): WebhookContext;
 export interface ExecuteHandlerOptions {

package/dist/lib/triggers/handlers.js

@@ -9,11 +9,11 @@ import { exec } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 import { machineId, normalizeHost } from '../machine-id.js';
 import { safeJoin } from '../paths.js';
 import { pickFleetDevice } from '../routines-placement.js';
-import { assertShellSubstitutionSupported, readJob, substituteWebhookCommand, substituteWebhookPrompt, } from '../routines.js';
+import { assertShellSubstitutionSupported, readJob, substituteWebhookCommand, substituteWebhookPrompt, } from '../scheduling/routines.js';
 import { ensureAgentsDir, getProjectWebhooksDir, getSystemWebhooksDir, getWebhooksDir } from '../state.js';
 const HANDLER_DEFAULTS = {
     enabled: true,
@@ -208,6 +208,17 @@ export function handlerMatchesWebhook(handler, webhook) {
         return false;
     if (!handlerRunsOnThisDevice(handler))
         return false;
+    // Slack has no GitHub/Linear action/label/branch vocabulary; it matches on the
+    // slash command and (optionally) the channel. `event` already pinned the
+    // subtype (`app_mention`) or the slash command name above.
+    if (webhook.source === 'slack') {
+        const slack = webhook.payload;
+        if (handler.command && slack.command !== handler.command)
+            return false;
+        if (handler.channel && slack.channel !== handler.channel)
+            return false;
+        return true;
+    }
     if (handler.action) {
         const action = webhook.source === 'github' ? githubAction(webhook.payload) : linearAction(webhook.payload);
         if (action !== handler.action)
@@ -262,12 +273,47 @@ export function handlerMatchesWebhook(handler, webhook) {
     }
     return true;
 }
+const asString = (v) => (typeof v === 'string' ? v : '');
+/**
+ * Split a Slack message into a `{{slack.*}}` context. Strips a leading bot
+ * mention (`<@U0BOT> …`), then reads an optional `PROJECT:` prefix — a single
+ * bare token followed by a colon and a space — as the project, with the
+ * remainder the prompt. `AGI: rebase my PR` → project `AGI`, prompt
+ * `rebase my PR`; a message with no such prefix leaves `project` empty and the
+ * whole text as the prompt. The token pattern forbids slashes, so a project
+ * value can never carry a path into a `cwd`/`project` substitution.
+ */
+export function parseSlackMessage(payload) {
+    const cleaned = asString(payload.text).replace(/^\s*<@[^>]+>\s*/, '').trim();
+    const m = /^([A-Za-z0-9][\w.-]*)\s*:\s+([\s\S]+)$/.exec(cleaned);
+    return {
+        text: cleaned,
+        project: m ? m[1] : '',
+        prompt: m ? m[2].trim() : cleaned,
+        channel: asString(payload.channel),
+        thread_ts: asString(payload.thread_ts),
+        user: asString(payload.user),
+        command: asString(payload.command),
+    };
+}
 /**
  * Build the variable-substitution context for a webhook. Linear events expose
  * `issue` and `updatedFrom`; GitHub events expose `repository`, `pull_request`,
- * and `issue`.
+ * and `issue`; Slack events expose the `{{slack.*}}` namespace above.
  */
 export function buildWebhookContext(webhook) {
+    if (webhook.source === 'slack') {
+        // The `{{slack.*}}` namespace rides an intersection over WebhookContext (a
+        // subtype of it) rather than a field on the shared type, so a Slack-only
+        // addition never touches the scheduling hub every routine test depends on.
+        // `substituteWebhookPrompt`/`getPath` read it dynamically at runtime.
+        const ctx = {
+            source: webhook.source,
+            event: webhook.event,
+            slack: parseSlackMessage(webhook.payload),
+        };
+        return ctx;
+    }
     const action = webhook.source === 'github'
         ? githubAction(webhook.payload) ?? undefined
         : linearAction(webhook.payload) ?? undefined;
@@ -346,6 +392,11 @@ export async function executeHandler(handler, webhook, opts = {}) {
 }
 async function executeHandlerAction(handler, webhook, context, opts) {
     const substitutedPrompt = handler.run?.prompt ? substituteWebhookPrompt(handler.run.prompt, context) : '';
+    // Slack routes the project per-message (`AGI: …`), so a handler may template
+    // its project/cwd — e.g. `project: "{{slack.project}}"`. Substitute + trim; an
+    // empty result omits the field (falls back to the run's default cwd / $HOME).
+    const substitutedProject = handler.project ? substituteWebhookPrompt(handler.project, context).trim() : '';
+    const substitutedCwd = handler.cwd ? substituteWebhookPrompt(handler.cwd, context).trim() : '';
     // Resolved once so a fleet pick can't differ between the two dispatch paths.
     const hostFields = resolveHandlerHost(handler.host);
     if (handler.run?.agent || handler.run?.workflow) {
@@ -359,8 +410,8 @@ async function executeHandlerAction(handler, webhook, context, opts) {
             ...(handler.run.agent ? { agent: handler.run.agent } : { workflow: handler.run.workflow }),
             ...(handler.devices ? { devices: handler.devices } : {}),
             ...(handler.run.env ? { env: handler.run.env } : {}),
-            ...(handler.project ? { project: handler.project } : {}),
-            ...(handler.cwd ? { cwd: handler.cwd } : {}),
+            ...(substitutedProject ? { project: substitutedProject } : {}),
+            ...(substitutedCwd ? { cwd: substitutedCwd } : {}),
             ...(hostFields.host ? { host: hostFields.host } : {}),
             ...(hostFields.hostStrategy ? { hostStrategy: hostFields.hostStrategy } : {}),
         };
@@ -385,8 +436,8 @@ async function executeHandlerAction(handler, webhook, context, opts) {
             ...routine,
             prompt: substituteWebhookPrompt(routine.prompt, context),
             ...(handler.devices ? { devices: handler.devices } : {}),
-            ...(handler.project ? { project: handler.project } : {}),
-            ...(handler.cwd ? { cwd: handler.cwd } : {}),
+            ...(substitutedProject ? { project: substitutedProject } : {}),
+            ...(substitutedCwd ? { cwd: substitutedCwd } : {}),
             ...(handler.mode ? { mode: handler.mode } : {}),
             ...(hostFields.host ? { host: hostFields.host } : {}),
             ...(hostFields.hostStrategy ? { hostStrategy: hostFields.hostStrategy } : {}),

package/dist/lib/triggers/webhook.d.ts

@@ -13,15 +13,17 @@
  */
 import * as http from 'http';
 import type { IncomingHttpHeaders } from 'http';
-import type { JobConfig, RunMeta, WebhookContext } from '../routines.js';
+import type { JobConfig, RunMeta, WebhookContext } from '../scheduling/routines.js';
 import { type FiredHandler } from './handlers.js';
-export type WebhookSource = 'github' | 'linear';
+export type WebhookSource = 'github' | 'linear' | 'slack';
 export interface IncomingWebhook {
     /** Delivery source, derived from `/hooks/<source>` or one-shot command flags. */
     source: WebhookSource;
-    /** Source event name: GitHub header event or Linear payload `type`. */
+    /** Source event name: GitHub header event, Linear payload `type`, or the Slack
+     *  event subtype (`app_mention`) / slash command (`/agents`). */
     event: string;
-    /** Decoded JSON request body. */
+    /** Decoded request body (JSON for GitHub/Linear/Slack-events; the normalized
+     *  {@link SlackPayload} for a Slack slash command's form body). */
     payload: Record<string, unknown>;
 }
 export type GithubWebhook = IncomingWebhook & {
@@ -30,6 +32,9 @@ export type GithubWebhook = IncomingWebhook & {
 export type LinearWebhook = IncomingWebhook & {
     source: 'linear';
 };
+export type SlackWebhook = IncomingWebhook & {
+    source: 'slack';
+};
 /** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
 export declare function webhookRepo(payload: Record<string, unknown>): string | null;
 /**
@@ -96,9 +101,59 @@ export declare function fireWebhookJobs(webhook: IncomingWebhook, options?: Fire
 export declare function verifyGithubSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string): boolean;
 export declare function verifyLinearSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string): boolean;
 export declare function verifyLinearTimestamp(payload: Record<string, unknown>, now?: number, toleranceMs?: number): boolean;
+/**
+ * Verify a Slack request signature (the `v0` scheme). Slack signs the base
+ * string `v0:${timestamp}:${rawBody}` with the app's signing secret and sends
+ * the hex digest as `X-Slack-Signature: v0=<hex>`, alongside the unix
+ * `X-Slack-Request-Timestamp`. The timestamp is BOTH part of the signed base
+ * string AND checked for freshness here — a request older than `toleranceSec`
+ * (default 5 min) is rejected, so a captured, correctly-signed body cannot be
+ * replayed later. Fails closed on any missing/malformed header.
+ */
+export declare function verifySlackSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string, now?: number, toleranceSec?: number): boolean;
+/**
+ * Normalized fields extracted from a Slack slash-command or Events API delivery.
+ * This is the `payload` of a Slack {@link IncomingWebhook}: transport-level
+ * parsing lives here, message *semantics* (splitting the mention text into an
+ * agent / project / prompt) live in `handlers.ts` `buildWebhookContext`.
+ */
+export interface SlackPayload extends Record<string, unknown> {
+    /** `url_verification` | `event_callback` | `slash_command`. */
+    type: string;
+    /** Echoed back for the one-time Events API URL-verification handshake. */
+    challenge?: string;
+    /** Slack event id (Events API) — the dedup key when present. */
+    event_id?: string;
+    /** Event subtype, e.g. `app_mention` (Events API). */
+    event_type?: string;
+    /** Raw message text (the mention body, or the slash-command text). */
+    text?: string;
+    /** Channel id (`C0…`) the message arrived in. */
+    channel?: string;
+    /** Thread to reply into: an existing thread's parent ts, else the message ts. */
+    thread_ts?: string;
+    /** Invoking user id (`U0…`). */
+    user?: string;
+    /** Slash command name, e.g. `/agents`. */
+    command?: string;
+    /** Slash-command `response_url` (valid ~30 min, 5 uses). */
+    response_url?: string;
+    /** Slack team / workspace id. */
+    team?: string;
+}
+/**
+ * Parse a Slack delivery body into a normalized {@link SlackPayload}. Slack
+ * sends slash commands as `application/x-www-form-urlencoded` and Events API
+ * deliveries (including the `url_verification` handshake) as
+ * `application/json` — this is the one place that content-type branch lives.
+ */
+export declare function parseSlackBody(contentType: string | undefined, rawBody: Buffer): SlackPayload;
+/** The `event` name a Slack delivery fires under: the slash command, or the event subtype. */
+export declare function slackEventName(payload: SlackPayload): string;
 export interface WebhookSecrets {
     github?: string;
     linear?: string;
+    slack?: string;
 }
 export interface DeliveryStore {
     seen(id: string): boolean;
@@ -123,6 +178,15 @@ export interface RateLimiter {
     take(key: string): boolean;
 }
 export declare function createMemoryRateLimiter(limit: number, windowMs: number): RateLimiter;
+/**
+ * Resolve once a receiver is actually accepting connections, REJECT if the bind
+ * failed. `server.listen()` reports a bind failure (EADDRINUSE, EACCES) as an
+ * asynchronous `'error'` event, never a throw — so a `try/catch` around
+ * `startWebhookServer` cannot see it, and without this the event reaches Node's
+ * default handler and takes the whole process down. Every caller that hosts a
+ * receiver MUST await this rather than assuming the return means "bound".
+ */
+export declare function waitForListening(server: http.Server): Promise<void>;
 /** Options for the local webhook http listener. */
 export interface WebhookServerOptions {
     port?: number;
@@ -131,8 +195,33 @@ export interface WebhookServerOptions {
     secrets: WebhookSecrets;
     /** Override the fire options (mainly for tests). */
     fire?: FireWebhookOptions;
-    /** Called after each delivery is handled (mainly for tests/observability). */
+    /**
+     * Called the moment a delivery's matches are known — BEFORE any routine or
+     * handler is dispatched. Matching is a pure, synchronous lookup (no I/O), so
+     * this fires immediately after the ack, regardless of how long the matched
+     * work then takes to run. This is the right hook for a "webhook X fired Y"
+     * log line: a `run.command` handler that shells out a long agent session
+     * (`exec()`, which only resolves on process exit) used to hold that log back
+     * for as long as the session ran — `ps` would show the agent already running
+     * while the log still implied nothing had matched (RUSH-2722). Names only
+     * (no runId/exitCode yet — those aren't known until dispatch settles).
+     */
+    onMatch?: (webhook: IncomingWebhook, matchedJobNames: string[], matchedHandlerNames: string[]) => void;
+    /**
+     * Called after a delivery has fully settled — every matched routine and
+     * handler dispatched (and, for `run.command` handlers, exited). Because the
+     * receiver acks the HTTP response BEFORE dispatch (see `startWebhookServer`),
+     * this fires strictly after the response has been written, and is the only
+     * way a caller observes the dispatch outcome (runId/exitCode/output). It is
+     * NOT the right hook for "did this webhook match" logging — use `onMatch`.
+     */
     onDelivery?: (webhook: IncomingWebhook, fired: FiredJob[], handlers: FiredHandler[]) => void;
+    /**
+     * Called when settling an already-acked delivery threw. The HTTP status can
+     * no longer carry the failure, so this is the loud path — the daemon host and
+     * `agents webhooks serve` both log it. Never swallowed silently.
+     */
+    onDeliveryError?: (webhook: IncomingWebhook, error: Error) => void;
     deliveryStore?: DeliveryStore;
     rateLimiter?: RateLimiter;
     rateLimitPerMinute?: number;
@@ -149,6 +238,25 @@ export interface WebhookServerOptions {
  *   POST /hooks/github  with X-Hub-Signature-256
  *   POST /hooks/linear  with Linear-Signature + fresh webhookTimestamp
  *
+ * **The ack is asynchronous (RUSH-2548).** Once a delivery has passed signature
+ * verification, freshness, dedup, and rate limiting, the receiver writes
+ * `202 {ok:true, accepted:true}` IMMEDIATELY and dispatches the matched routines
+ * and handlers afterwards. Dispatch starts an agent run and takes 15-20s, which
+ * exceeds Linear's delivery timeout — holding the socket open across it made
+ * every real delivery log a timeout + retry on Linear's side. Nothing about the
+ * dedup ledger changes: the `<source>:<delivery-id>` key is still what makes a
+ * retry a no-op, per-job `markJob` still lets a retry finish only the matches
+ * that failed, and the delivery is marked complete only after it settles.
+ *
+ * A retry that lands WHILE the first is still settling is answered as a
+ * duplicate from an in-flight set, since `deliveryStore.seen` only reports
+ * completed deliveries and would otherwise let a mid-flight retry double-fire.
+ *
+ * `onMatch` fires as soon as matching is known, before any dispatch; `onDelivery`
+ * fires only once every matched routine/handler has settled — see their docs on
+ * `WebhookServerOptions`. A caller that wants a prompt "this fired" log uses
+ * `onMatch`, not `onDelivery` (RUSH-2722).
+ *
  * Returns the underlying server so callers can `close()` it.
  */
 export declare function startWebhookServer(options: WebhookServerOptions): http.Server;