@phnx-labs/agents-cli 1.22.40 → 1.22.41

package/dist/lib/share/publish.d.ts

@@ -129,6 +129,25 @@ export declare function assertMetadataSize(customMetadata: Record<string, string
  * an unhandled `TypeError: Invalid value` and crashes the publish outright.
  */
 export declare function sanitizeLabel(text: string): string;
+/**
+ * Make a free-text value safe to put in an HTTP header.
+ *
+ * `fetch` encodes header values as a **ByteString**, so any code point above 255
+ * throws `TypeError: Cannot convert argument to a ByteString` — an unhandled
+ * crash with a stack trace, mid-publish, after the body has already been read.
+ * Reproduced by publishing a session whose title ended in `…` (U+2026), and
+ * reachable by any emoji, curly quote, accented name, or CJK text in a `--label`,
+ * a `--meta` value, or a repo name.
+ *
+ * The transliterations above cover what actually shows up; anything else outside
+ * latin1 is dropped, and a value that transliterates to nothing at all (a title
+ * written entirely in a non-latin script) degrades to a marker rather than an
+ * empty header. Lossy on purpose: carrying full Unicode needs percent-encoding
+ * here AND a matching decode in the Worker, which every already-deployed Worker
+ * would render as `%E2%80%A6` until its operator ran `agents artifacts share
+ * update` — tracked as RUSH-2786.
+ */
+export declare function toHeaderValue(text: string): string;
 /**
  * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
  * Markdown frontmatter `title:`, else the filename. Always returns something —
@@ -150,6 +169,25 @@ export interface SensitiveHit {
     /** Short redacted sample so the error names *what* was found without dumping it. */
     sample: string;
 }
+/**
+ * Mask every email address in `text`, so a page can be published without tripping
+ * {@link scanShareContent}.
+ *
+ * Lives here, beside the scanner, rather than in `lib/redact.ts`: it exists solely
+ * to satisfy this gate, and sharing {@link EMAIL_RE} is what makes the masking
+ * *sufficient* to clear it rather than merely reducing the hit count. Two copies of
+ * the pattern in two modules would drift, and the failure mode of that drift is a
+ * refused publish at runtime.
+ *
+ * Deliberately NOT part of `redactSecrets`: an email is not a credential, and a
+ * transcript rendered for a private gist or local review reads better with the real
+ * author addresses intact. It only becomes a leak once the text is PUBLISHED — a
+ * world-readable page carrying seven of them is the RUSH-2428 incident.
+ *
+ * The whole address goes, domain included — a personal domain identifies its owner
+ * as surely as the local part does, and keeping it would buy the reader nothing.
+ */
+export declare function redactEmails(text: string): string;
 /**
  * Scan a text body for email addresses and credential-shaped strings. Returns
  * the first few hits (deduped by kind+sample). Binary / non-text bodies yield

package/dist/lib/share/publish.js

@@ -91,6 +91,49 @@ export function assertMetadataSize(customMetadata) {
 export function sanitizeLabel(text) {
     return text.replace(/\s+/g, ' ').trim();
 }
+/**
+ * Typographic characters that reach a header constantly — a curly quote from a
+ * pasted prompt, an em dash from prose, the ellipsis a truncated title ends on —
+ * each mapped to the ASCII form a reader loses nothing by seeing.
+ */
+const HEADER_TRANSLITERATIONS = [
+    [/[‘’‚‛]/g, "'"],
+    [/[“”„‟]/g, '"'],
+    [/[–—―]/g, '-'],
+    [/…/g, '...'],
+    [/[    ]/g, ' '],
+    [/[•·]/g, '-'],
+];
+/**
+ * Make a free-text value safe to put in an HTTP header.
+ *
+ * `fetch` encodes header values as a **ByteString**, so any code point above 255
+ * throws `TypeError: Cannot convert argument to a ByteString` — an unhandled
+ * crash with a stack trace, mid-publish, after the body has already been read.
+ * Reproduced by publishing a session whose title ended in `…` (U+2026), and
+ * reachable by any emoji, curly quote, accented name, or CJK text in a `--label`,
+ * a `--meta` value, or a repo name.
+ *
+ * The transliterations above cover what actually shows up; anything else outside
+ * latin1 is dropped, and a value that transliterates to nothing at all (a title
+ * written entirely in a non-latin script) degrades to a marker rather than an
+ * empty header. Lossy on purpose: carrying full Unicode needs percent-encoding
+ * here AND a matching decode in the Worker, which every already-deployed Worker
+ * would render as `%E2%80%A6` until its operator ran `agents artifacts share
+ * update` — tracked as RUSH-2786.
+ */
+export function toHeaderValue(text) {
+    let safe = text;
+    for (const [pattern, replacement] of HEADER_TRANSLITERATIONS)
+        safe = safe.replace(pattern, replacement);
+    safe = safe.replace(/[^\x20-\x7E\xA0-\xFF]/g, '').replace(/\s+/g, ' ').trim();
+    // An input that was empty to begin with stays empty — `--meta note=` means an
+    // empty note, not an unnamed one. The marker is only for a value that HAD
+    // content and lost all of it to the latin1 fold.
+    if (safe)
+        return safe;
+    return text.trim() ? '(unnamed)' : '';
+}
 /**
  * Best-effort human title when `--label` is omitted: the HTML `<title>`, else a
  * Markdown frontmatter `title:`, else the filename. Always returns something —
@@ -141,6 +184,27 @@ export function resolveExpire(spec) {
 }
 /** Email addresses — the RUSH-2428 incident page carried seven of these. */
 const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+/**
+ * Mask every email address in `text`, so a page can be published without tripping
+ * {@link scanShareContent}.
+ *
+ * Lives here, beside the scanner, rather than in `lib/redact.ts`: it exists solely
+ * to satisfy this gate, and sharing {@link EMAIL_RE} is what makes the masking
+ * *sufficient* to clear it rather than merely reducing the hit count. Two copies of
+ * the pattern in two modules would drift, and the failure mode of that drift is a
+ * refused publish at runtime.
+ *
+ * Deliberately NOT part of `redactSecrets`: an email is not a credential, and a
+ * transcript rendered for a private gist or local review reads better with the real
+ * author addresses intact. It only becomes a leak once the text is PUBLISHED — a
+ * world-readable page carrying seven of them is the RUSH-2428 incident.
+ *
+ * The whole address goes, domain included — a personal domain identifies its owner
+ * as surely as the local part does, and keeping it would buy the reader nothing.
+ */
+export function redactEmails(text) {
+    return text.replace(EMAIL_RE, '[EMAIL]');
+}
 /**
  * Credential-shaped strings that an agent routinely dumps into reports: GitHub
  * PATs, OpenAI/Anthropic/etc. API keys, AWS access keys, Slack tokens, and a
@@ -430,20 +494,29 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
             h['x-share-expires-at'] = expiresAt;
         if (unlisted)
             h['x-share-visibility'] = 'unlisted';
+        // Every free-text header goes through toHeaderValue: a non-latin1 code point
+        // anywhere in a label, a repo name, or a --meta value throws inside fetch and
+        // crashes the publish outright.
         if (provenance.agent)
-            h['x-share-agent'] = provenance.agent;
+            h['x-share-agent'] = toHeaderValue(provenance.agent);
         if (provenance.session)
-            h['x-share-session'] = provenance.session;
+            h['x-share-session'] = toHeaderValue(provenance.session);
         if (provenance.host)
-            h['x-share-host'] = provenance.host;
+            h['x-share-host'] = toHeaderValue(provenance.host);
         if (provenance.repo)
-            h['x-share-repo'] = provenance.repo;
+            h['x-share-repo'] = toHeaderValue(provenance.repo);
         if (provenance.date)
-            h['x-share-date'] = provenance.date;
-        h['x-share-label'] = label;
+            h['x-share-date'] = toHeaderValue(provenance.date);
+        h['x-share-label'] = toHeaderValue(label);
         h['x-share-label-source'] = labelSource;
-        if (Object.keys(meta).length > 0)
-            h['x-share-meta'] = JSON.stringify(meta);
+        // Per VALUE, before JSON.stringify — folding the serialized form would rewrite
+        // a curly quote inside a value into a bare `"`, which is structural in JSON and
+        // makes the Worker's JSON.parse throw. It swallows that error, so every --meta
+        // key would silently vanish on a 200.
+        if (Object.keys(meta).length > 0) {
+            const headerMeta = Object.fromEntries(Object.entries(meta).map(([k, v]) => [toHeaderValue(k), toHeaderValue(v)]));
+            h['x-share-meta'] = JSON.stringify(headerMeta);
+        }
         if (opts.noRevision)
             h['x-share-no-revision'] = '1';
         return h;

package/dist/lib/startup/command-registry.d.ts

@@ -20,7 +20,8 @@ export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
  * `set` moved under `agents models`/`agents config` (RUSH-2579); `share` moved
  * under `agents artifacts share` (RUSH-2580). login/logout/budget/bench/mine/
  * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
- * (cli-surface-consolidate).
+ * (cli-surface-consolidate). `timeline` was removed as a duplicated surface —
+ * use `agents feed --filter updates` (RUSH-2692).
  */
 export declare const RETIRED_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 export declare function isKnownTopLevelCommand(name: string): boolean;

package/dist/lib/startup/command-registry.js

@@ -9,7 +9,7 @@ const LOADED_COMMAND_NAMES = [
     'alias', 'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'tickets', 'cloud', 'message', 'send', 'notify', 'feed', 'inbox',
-    'timeline', 'mailboxes', 'mailbox', 'serve', 'artifacts', 'unshare', 'audit', 'webhooks',
+    'mailboxes', 'mailbox', 'serve', 'artifacts', 'unshare', 'audit', 'webhooks',
     'humans', 'daemon',
 ];
 const INLINE_COMMAND_NAMES = [
@@ -40,7 +40,8 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
  * `set` moved under `agents models`/`agents config` (RUSH-2579); `share` moved
  * under `agents artifacts share` (RUSH-2580). login/logout/budget/bench/mine/
  * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
- * (cli-surface-consolidate).
+ * (cli-surface-consolidate). `timeline` was removed as a duplicated surface —
+ * use `agents feed --filter updates` (RUSH-2692).
  */
 export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'webhook',
@@ -58,6 +59,7 @@ export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'roster',
     'set',
     'share',
+    'timeline',
 ]);
 export function isKnownTopLevelCommand(name) {
     return KNOWN_TOP_LEVEL_COMMANDS.has(name);

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

@@ -7,7 +7,7 @@
  */
 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

@@ -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

@@ -15,13 +15,15 @@ import * as http from 'http';
 import type { IncomingHttpHeaders } from 'http';
 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;
@@ -140,11 +195,25 @@ export interface WebhookServerOptions {
     secrets: WebhookSecrets;
     /** Override the fire options (mainly for tests). */
     fire?: FireWebhookOptions;
+    /**
+     * 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. 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 outcome.
+     * 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;
     /**
@@ -183,6 +252,11 @@ export interface WebhookServerOptions {
  * 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;