@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/dispatcher-prompt.d.ts

@@ -102,6 +102,8 @@ export declare class PromptAssembler {
      * Kept on the assembler (not in prompts.ts) because the attachment
      * rows are local state for this turn only.
      */
-    buildAttachmentPromptBlock(rows: StoreAttachmentRow[], transcripts?: Map<string, VoiceTranscriptionResult>): string;
+    buildAttachmentPromptBlock(rows: StoreAttachmentRow[], transcripts?: Map<string, VoiceTranscriptionResult>, missing?: ReadonlyArray<{
+        originalFilename: string;
+        missingReason?: string;
+    }>): string;
 }
-//# sourceMappingURL=dispatcher-prompt.d.ts.map

package/dist/core/dispatcher-prompt.js

@@ -69,7 +69,7 @@ export class PromptAssembler {
         if (!contextDir) {
             return base;
         }
-        // B-003 Phase 3 — the `rules/mcp.md` PolicyFileRef is registered with
+        // B-003 Phase 3 — the `policies/mcp.md` PolicyFileRef is registered with
         // `injectIf: ctx.flags?.mcpEnabled === true`. Compute the flag here so
         // every dispatch path (DM, routine, scheduled task, fallback reassembly)
         // injects the policy without each call site having to remember it.
@@ -133,6 +133,10 @@ export class PromptAssembler {
             return [];
         const staged = [];
         for (const ref of event.attachments) {
+            // Skip adapter-marked missing refs — they have no underlying row
+            // to stage, just metadata for the prompt builder.
+            if (ref.missing)
+                continue;
             const row = attachmentStore.get(ref.id);
             if (!row)
                 continue;
@@ -182,8 +186,8 @@ export class PromptAssembler {
      * Kept on the assembler (not in prompts.ts) because the attachment
      * rows are local state for this turn only.
      */
-    buildAttachmentPromptBlock(rows, transcripts) {
-        if (rows.length === 0)
+    buildAttachmentPromptBlock(rows, transcripts, missing = []) {
+        if (rows.length === 0 && missing.length === 0)
             return "";
         const lines = [
             "",
@@ -220,8 +224,19 @@ export class PromptAssembler {
                 lines.push("  (voice transcript unavailable — audio may be too long, untranscribable, or the local model is unavailable)");
             }
         }
+        if (missing.length > 0) {
+            // Adapter-reported attachments that couldn't be ingested
+            // (e.g. Discord CDN URL expired on a stale message). The agent
+            // can't see the bytes but should still acknowledge them and ask
+            // the user to resend rather than pretending nothing was attached.
+            lines.push("", "[Attached files that could not be fetched]");
+            for (const ref of missing) {
+                const reasonPart = ref.missingReason ? ` — ${ref.missingReason}` : "";
+                lines.push(`- ${ref.originalFilename}${reasonPart}`);
+            }
+            lines.push("Acknowledge these to the user and ask them to resend if the content", "matters for your reply. Do not pretend the bytes were available.");
+        }
         lines.push("", "If your reply should include a generated file (md/PDF/CSV/image/etc.),", "deliver it via the `attach` skill — write the bytes to a temp path, then", "POST /api/chat/outbound-attachments with `X-Turn-Token: $PA_TURN_TOKEN`.", "`_attachments/` is the read-only inbound staging area, not an output", "location. Never write a filesystem path into your reply and claim you", "created a file unless you actually uploaded it through that endpoint.");
         return lines.join("\n");
     }
 }
-//# sourceMappingURL=dispatcher-prompt.js.map

package/dist/core/dispatcher-repository-helpers.d.ts

@@ -36,4 +36,3 @@ export declare function safeRepositoryRunDirName(slug: string): string;
 export declare function parseGithubRepoSlug(value: string | null): [string | null, string | null];
 export declare function normalizeRepositoryClassification(value: unknown): RepositoryDTO["classification"];
 export declare function normalizeRepositoryCategory(value: unknown): RepositoryDTO["category"];
-//# sourceMappingURL=dispatcher-repository-helpers.d.ts.map

package/dist/core/dispatcher-repository-helpers.js

@@ -50,7 +50,11 @@ export function parseRepositoryRunTaskContext(taskCtx) {
     };
 }
 export function repositoryRunInstructionFilename(backendId) {
-    if (backendId === "codex")
+    // Keep this in lock-step with `cliInstructionFileName` in skills-compiler.ts:
+    // Codex and OpenCode both auto-discover AGENTS.md from cwd, Gemini reads
+    // GEMINI.md, Claude reads CLAUDE.md. Diverging here silently strands the
+    // backend without instructions at repository-run time.
+    if (backendId === "codex" || backendId === "opencode")
         return "AGENTS.md";
     if (backendId === "gemini")
         return "GEMINI.md";
@@ -83,4 +87,3 @@ export function normalizeRepositoryCategory(value) {
         ? value
         : "other";
 }
-//# sourceMappingURL=dispatcher-repository-helpers.js.map

package/dist/core/dispatcher-result-processor.d.ts

@@ -42,6 +42,7 @@ import type Database from "better-sqlite3";
 import type { Event, MessageEvent, AgentResult } from "@aitne/shared";
 import type { AgentConfig } from "../config.js";
 import type { IAuditLogger, INotificationManager, ISessionManager } from "./dispatcher-types.js";
+import type { AgentExecutionOutcome } from "./agents/agent-execution-tracker.js";
 /**
  * English-only patterns by CLAUDE.md convention. The disavowal tripwire
  * is a numerator over a `disavowed / injected` ratio (dm-channel-timeline.md
@@ -68,6 +69,13 @@ export interface ResultProcessorDeps {
      * upgradable.
      */
     hasMessageBackendMetadataColumns: boolean;
+    /**
+     * AGENT_DEFINITIONS_DESIGN.md §8.2 — feed the terminal LLM-level outcome
+     * (cost / soft-error) to the execution tracker so the dispatch boundary
+     * settles the `agent_executions` row with the accurate result. Optional so
+     * existing dispatcher unit tests construct the processor without it.
+     */
+    recordExecutionOutcome?: (event: Event, outcome: AgentExecutionOutcome) => void;
 }
 export declare class ResultProcessor {
     private readonly db;
@@ -78,6 +86,7 @@ export declare class ResultProcessor {
     private readonly notifiedEvents;
     private readonly isReactive;
     private readonly hasMessageBackendMetadataColumns;
+    private readonly recordExecutionOutcome?;
     constructor(deps: ResultProcessorDeps);
     processResult(result: AgentResult, event: Event, skipNotify?: boolean, options?: {
         originSessionId?: number;
@@ -89,6 +98,17 @@ export declare class ResultProcessor {
             refetchedToday: boolean;
             triggerMatched: boolean;
         };
+        /**
+         * docs/design/appendices/daily-journal-daemon-write.md §4.11 —
+         * daily journal compose outcome for Stage B
+         * (`routine.morning_routine_journal`). Threaded through the
+         * orchestrator's `persistStageAuditRows` so `detail.dailyWrite`
+         * lands on the same INSERT/UPSERT the result-processor's
+         * `audit.logAction` call performs. Optional on all other event
+         * types (and absent on Stage A); the audit logger skips the
+         * field when null/undefined.
+         */
+        dailyWrite?: import("./dispatcher-types.js").DailyWriteAuditDetail | null;
     }): Promise<void>;
     /**
      * P6 (git-lifecycle-and-triggers.md Decision 8) — restore in-flight
@@ -165,4 +185,3 @@ export declare class ResultProcessor {
      */
     private verifyWikiIngestWriteOrRewrite;
 }
-//# sourceMappingURL=dispatcher-result-processor.d.ts.map

package/dist/core/dispatcher-result-processor.js

@@ -42,10 +42,12 @@ import { isAgentTaskEvent, isDocsQAMessage, isMessageEvent, isRoutineEvent, isSc
 import { getContextDir } from "../config.js";
 import { finalizeRetemplate } from "./template-store.js";
 import { recordManagementInitDone, recordManagementScan, } from "../db/repositories-store.js";
-import { isProactiveForwardMetadata, parseMessageMetadata, } from "./channel-timeline.js";
+import { formatForwardSuffix, getProactiveForwardType, isProactiveForwardMetadata, parseMessageMetadata, recordProactiveForwardDeliveries, } from "./channel-timeline.js";
+import { randomUUID } from "node:crypto";
 import { OWNER_DM_SCOPE, OWNER_SCOPE_KEY, DASHBOARD_CHAT_SCOPE, DASHBOARD_SCOPE_KEY, getConversationScope, } from "../messaging/constants.js";
 import { readEventReplyTarget } from "./wiki/dispatcher.js";
 import { createLogger } from "../logging.js";
+import { assertOutboundAllowedForAgent, OutboundPurchaseTemplateError, } from "../safety/outbound-purchase-guard.js";
 const logger = createLogger("dispatcher-result");
 /**
  * English-only patterns by CLAUDE.md convention. The disavowal tripwire
@@ -70,6 +72,7 @@ export class ResultProcessor {
     notifiedEvents;
     isReactive;
     hasMessageBackendMetadataColumns;
+    recordExecutionOutcome;
     constructor(deps) {
         this.db = deps.db;
         this.config = deps.config;
@@ -79,6 +82,7 @@ export class ResultProcessor {
         this.notifiedEvents = deps.notifiedEvents;
         this.isReactive = deps.isReactive;
         this.hasMessageBackendMetadataColumns = deps.hasMessageBackendMetadataColumns;
+        this.recordExecutionOutcome = deps.recordExecutionOutcome;
     }
     async processResult(result, event, skipNotify = false, options = {}) {
         // Notify-dedup: consume the marker (if present) so this method also
@@ -134,12 +138,80 @@ export class ResultProcessor {
                     threadId: explicitReply.threadId ?? null,
                 };
             }
+            // MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §17.7 structural-anti-
+            // spoofing layer. The LLM's outbound text reaches the messaging
+            // adapter via this notificationMgr.send chokepoint; refuse any
+            // payload carrying the reserved purchase-confirmation markers
+            // ("🔐 Aitne purchase confirmation", "[purchase-verify:", "Approved
+            // on …"). Those templates are emitted exclusively by
+            // `purchase-system-message-sender` via the unforgeable handler
+            // capability — an LLM-originated text claiming to be a purchase
+            // confirmation is by definition a spoof attempt. The guard audits
+            // the refusal as an `agent_actions(purchase_template_refused)` row
+            // before swallowing — surfacing nothing to the user (the agent
+            // simply receives no DM rather than a structured error, mirroring
+            // the existing notification-suppression contract on this path).
+            try {
+                assertOutboundAllowedForAgent(output, "dispatcher.result", this.db);
+            }
+            catch (err) {
+                if (err instanceof OutboundPurchaseTemplateError) {
+                    logger.warn({
+                        marker: err.match.marker,
+                        eventType: event.type,
+                        correlationId: event.correlationId,
+                    }, "agent outbound refused — purchase-template marker detected");
+                    return;
+                }
+                throw err;
+            }
             if (Object.keys(sendOptions).length === 0) {
                 await this.notificationMgr.send(output, event);
             }
             else {
                 await this.notificationMgr.send(output, event, sendOptions);
             }
+            // BROWSER_HISTORY_INTEGRATION_PLAN §10.5 (seventh-pass) —
+            // conversation-injection invariant. Outbound DMs from routine
+            // sessions with a `reply_target` must land in the owner DM
+            // scope's `conversation_sessions` so the standard `message.dm`
+            // agent sees them in `<recent_dm_conversation>` on the user's
+            // reply turn. Without this, the natural-language acceptance
+            // flow (user replies "research please" to an offer DM) is
+            // structurally broken — the DM agent has no record of what
+            // offer was sent.
+            //
+            // Mirrors `scheduler.ts:handleDirectDm` which records
+            // `scheduled.dm` outputs the same way. `notificationMgr.send`
+            // by itself writes to `notification_log` (telemetry) only,
+            // not to `messages` (conversation history) — this call closes
+            // the gap. Best-effort: a recording failure must not break
+            // the send itself, so wrap in try/catch.
+            if (explicitReply && output.length > 0) {
+                try {
+                    recordProactiveForwardDeliveries({
+                        db: this.db,
+                        config: this.config,
+                        deliveries: [
+                            {
+                                platform: explicitReply.platform,
+                                channel: explicitReply.channel,
+                            },
+                        ],
+                        content: output,
+                        dispatchId: randomUUID(),
+                        ...(options.originSessionId !== undefined
+                            ? { originSessionIds: [options.originSessionId] }
+                            : {}),
+                        notificationType: "proactive_forward",
+                    });
+                }
+                catch (err) {
+                    logger.warn({ err, eventType: event.type }, "Failed to record outbound DM into channel timeline; "
+                        + "next message.dm session will not see this DM in "
+                        + "conversation_history. Send itself succeeded.");
+                }
+            }
         }
         this.audit.logAction({
             event,
@@ -155,6 +227,19 @@ export class ResultProcessor {
             contextUpdated: result.contextUpdated,
             advisorCallCount: result.advisorCallCount,
             ...(options.dmFreshness ? { dmFreshness: options.dmFreshness } : {}),
+            ...(options.dailyWrite ? { dailyWrite: options.dailyWrite } : {}),
+        });
+        // AGENT_DEFINITIONS_DESIGN.md §8.2 — record the terminal LLM-level outcome
+        // for the execution rollup. The dispatch boundary (dispatchSafe) later
+        // settles the row using this; a firing that never reaches here is settled
+        // as success (no thrown) or swept as crash by the boot janitor.
+        this.recordExecutionOutcome?.(event, {
+            isError: result.isError,
+            costUsd: result.costUsd,
+            tokensIn: result.usage.inputTokens,
+            tokensOut: result.usage.outputTokens,
+            turns: result.numTurns,
+            outputSummary: result.output.trim().slice(0, 500) || null,
         });
         // Observer-event observability: log whether an external-change
         // event actually produced a context-file update. Makes it obvious
@@ -362,8 +447,14 @@ export class ResultProcessor {
         }
     }
     formatSummaryRole(message) {
+        if (message.role !== "assistant")
+            return message.role;
         const metadata = parseMessageMetadata(message.metadata);
-        if (message.role === "assistant" && isProactiveForwardMetadata(metadata)) {
+        const type = getProactiveForwardType(metadata);
+        if (type === "scheduled_dm") {
+            return "assistant (scheduled DM dispatched)";
+        }
+        if (type !== null) {
             return "assistant (forwarded from autonomous run)";
         }
         return message.role;
@@ -410,8 +501,7 @@ export class ResultProcessor {
                     ? `[${row.role}/${row.backend}:${row.model_id ?? "?"}]`
                     : `[${row.role}/user]`;
                 const forwardSuffix = row.role === "assistant"
-                    && isProactiveForwardMetadata(parseMessageMetadata(row.metadata))
-                    ? " (forwarded from autonomous run)"
+                    ? formatForwardSuffix(parseMessageMetadata(row.metadata))
                     : "";
                 parts.push(`${tag}${forwardSuffix}: ${row.content}`);
             }
@@ -530,4 +620,3 @@ export class ResultProcessor {
         return `Failed ${url ?? "<url>"} — agent reported completion but no raw note was POSTed via the Wiki API; the vault is unchanged.`;
     }
 }
-//# sourceMappingURL=dispatcher-result-processor.js.map

package/dist/core/dispatcher-scheduled-browser-task.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dispatcher handler for `scheduled.browser_task` (BROWSER_TASK_REDESIGN_PLAN
+ * §6.2 + §7 + §12 Q#5).
+ *
+ * Lifts the fire-time row-creation + runner handoff out of `dispatcher.ts`
+ * so:
+ *   1. The decision logic is unit-testable without booting a real
+ *      dispatcher (the dispatcher itself is `Excluded` from the coverage
+ *      gate; this helper is on the covered path).
+ *   2. The shape (`event → outcome`) is documented as a single value
+ *      that every code path returns, instead of `void` + side-effect.
+ *
+ * Flow:
+ *   1. Parse + validate `event.taskContext` (re-runs the POST-time Zod
+ *      shape so a hand-crafted DB row cannot smuggle invalid fields
+ *      through the scheduler boundary).
+ *   2. Re-compose the allowlist regex against the current site
+ *      registry. The registry may have evolved between schedule-time
+ *      and fire-time; an unregistered siteKey is a clean
+ *      `site_unregistered` terminal.
+ *   3. Insert the `browser_task` row with the schedule-time
+ *      `preGeneratedTaskId` as its id, so the dashboard's
+ *      `/api/browser-task/<id>` poll switches from 404 to the real
+ *      row at exactly the fire moment.
+ *   4. Hand off to the runner. The runner's RunResult is the sole
+ *      determinant of the `browser_task` lifecycle from here; the
+ *      `agent_schedule` row's status is independent (mark `completed`
+ *      on successful dispatch + handoff, `failed` on rejection).
+ *
+ * **Test seam — `runner` is optional in `BrowserTaskDispatchDeps` so the
+ * Phase 3 wiring can land before Phase 2's full driver is plumbed.** When
+ * absent, the helper still creates the `browser_task` row + marks the
+ * schedule row completed; the runner-level fallback (`failed
+ * (not_implemented)` from the §5 stub) handles the row's terminal
+ * write on the next code-path that consults it.
+ */
+import type Database from "better-sqlite3";
+import type { ScheduledBrowserTaskEvent } from "@aitne/shared";
+import type { BrowserTaskNotifier, BrowserTaskRunner } from "../services/browser-task/browser-task-runner.js";
+export type ScheduledBrowserTaskOutcome = {
+    kind: "dispatched";
+    taskId: string;
+} | {
+    kind: "site_unregistered";
+    taskId: string;
+    siteKey: string | null;
+} | {
+    kind: "allowlist_rejected";
+    taskId: string;
+    reason: string;
+    offendingHost?: string;
+} | {
+    kind: "task_context_invalid";
+    reason: string;
+} | {
+    kind: "row_already_exists";
+    taskId: string;
+} | {
+    kind: "runner_unavailable";
+    taskId: string;
+};
+export interface BrowserTaskDispatchDeps {
+    db: Database.Database;
+    runner: BrowserTaskRunner | null;
+    /**
+     * §7 — "the user is DMed" on fire-time dispatch failure
+     * (`site_unregistered`, `allowlist_rejected`, `runner_unavailable`).
+     * Without this hook the user scheduled a task hours/days ago and
+     * gets no signal when it silently fails at fire time. The runner's
+     * own `notifyTerminal` only fires when the runner is reached, which
+     * is exactly NOT the case for these pre-runner failure paths.
+     *
+     * Fire-and-forget — the call is awaited only inside the handler's
+     * own `void ... .catch()` to keep failures observable without
+     * blocking dispatch. Optional so handler tests can omit it; the
+     * `task_context_invalid` / `row_already_exists` paths NEVER call it
+     * (no fresh row → no `originating_channel` to address).
+     */
+    notifier?: BrowserTaskNotifier | null;
+    /** Override for tests; production uses `Date.now`. */
+    nowFn?: () => number;
+}
+/**
+ * Handle a `scheduled.browser_task` event. Returns a discriminated
+ * outcome the caller (the dispatcher) consumes to mark the
+ * `agent_schedule` row status. Never throws on validation /
+ * registry-miss — those land as explicit outcomes the caller can
+ * audit. Throws on truly-unexpected DB errors so the dispatcher's
+ * `handleError` path can mark the schedule row `failed`.
+ */
+export declare function handleScheduledBrowserTask(deps: BrowserTaskDispatchDeps, event: ScheduledBrowserTaskEvent): Promise<ScheduledBrowserTaskOutcome>;

package/dist/core/dispatcher-scheduled-browser-task.js

@@ -0,0 +1,228 @@
+/**
+ * Dispatcher handler for `scheduled.browser_task` (BROWSER_TASK_REDESIGN_PLAN
+ * §6.2 + §7 + §12 Q#5).
+ *
+ * Lifts the fire-time row-creation + runner handoff out of `dispatcher.ts`
+ * so:
+ *   1. The decision logic is unit-testable without booting a real
+ *      dispatcher (the dispatcher itself is `Excluded` from the coverage
+ *      gate; this helper is on the covered path).
+ *   2. The shape (`event → outcome`) is documented as a single value
+ *      that every code path returns, instead of `void` + side-effect.
+ *
+ * Flow:
+ *   1. Parse + validate `event.taskContext` (re-runs the POST-time Zod
+ *      shape so a hand-crafted DB row cannot smuggle invalid fields
+ *      through the scheduler boundary).
+ *   2. Re-compose the allowlist regex against the current site
+ *      registry. The registry may have evolved between schedule-time
+ *      and fire-time; an unregistered siteKey is a clean
+ *      `site_unregistered` terminal.
+ *   3. Insert the `browser_task` row with the schedule-time
+ *      `preGeneratedTaskId` as its id, so the dashboard's
+ *      `/api/browser-task/<id>` poll switches from 404 to the real
+ *      row at exactly the fire moment.
+ *   4. Hand off to the runner. The runner's RunResult is the sole
+ *      determinant of the `browser_task` lifecycle from here; the
+ *      `agent_schedule` row's status is independent (mark `completed`
+ *      on successful dispatch + handoff, `failed` on rejection).
+ *
+ * **Test seam — `runner` is optional in `BrowserTaskDispatchDeps` so the
+ * Phase 3 wiring can land before Phase 2's full driver is plumbed.** When
+ * absent, the helper still creates the `browser_task` row + marks the
+ * schedule row completed; the runner-level fallback (`failed
+ * (not_implemented)` from the §5 stub) handles the row's terminal
+ * write on the next code-path that consults it.
+ */
+import { z } from "zod";
+import { createBrowserTask, getBrowserTask, markTerminal, } from "../db/browser-task-store.js";
+import { composeAllowlistRegex } from "../services/browser-task/browser-task-allowlist.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("dispatcher-scheduled-browser-task");
+/** Mirrors the validated POST body persisted into `agent_schedule.task_context`
+ *  by the `POST /api/browser-task` scheduleAt branch. Re-validated at fire
+ *  time so a hand-crafted DB row cannot bypass the schema.
+ *
+ *  2026-05-27 open-navigation revision — `siteKey` is now nullable (new
+ *  schedules write null because the API dropped the siteKey/extraAllowedHosts
+ *  request fields). Legacy schedule rows that still carry a real siteKey
+ *  string keep working through the same branches below. `extraAllowedHosts`
+ *  stays `.optional()` for the same reason; new rows write `[]`. */
+const taskContextSchema = z.object({
+    preGeneratedTaskId: z.string().uuid(),
+    description: z.string().min(1).max(4096),
+    siteKey: z.string().regex(/^[a-z][a-z0-9_]*$/).nullable(),
+    extraAllowedHosts: z.array(z.string()).max(5).optional(),
+    originatingChannel: z.string().nullable().optional(),
+    requireFinalConfirm: z.boolean().optional(),
+});
+/**
+ * Handle a `scheduled.browser_task` event. Returns a discriminated
+ * outcome the caller (the dispatcher) consumes to mark the
+ * `agent_schedule` row status. Never throws on validation /
+ * registry-miss — those land as explicit outcomes the caller can
+ * audit. Throws on truly-unexpected DB errors so the dispatcher's
+ * `handleError` path can mark the schedule row `failed`.
+ */
+export async function handleScheduledBrowserTask(deps, event) {
+    const now = deps.nowFn ?? (() => Date.now());
+    /** Fire-and-forget DM after a fresh failed-row write. Closes §7's
+     *  "user is DMed" gap for fire-time dispatch failures. The runner's
+     *  own `notifyTerminal` covers everything once the runner is reached;
+     *  these failure paths happen before that. */
+    function notifyDispatchFailure(taskId, originatingChannel, outcomeDetail) {
+        if (!deps.notifier)
+            return;
+        void deps.notifier
+            .notifyTerminal({
+            taskId,
+            originatingChannel,
+            state: "failed",
+            outcomeDetail,
+        })
+            .catch((err) => {
+            logger.warn({ err, taskId, outcomeDetail }, "scheduled.browser_task: failure-DM dispatch failed (continuing)");
+        });
+    }
+    // Step 1: re-validate the persisted task_context.
+    const parsed = taskContextSchema.safeParse(event.taskContext);
+    if (!parsed.success) {
+        const reason = parsed.error.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ");
+        logger.error({ scheduleId: event.scheduleId, reason }, "scheduled.browser_task: task_context failed schema validation");
+        return { kind: "task_context_invalid", reason };
+    }
+    const ctx = parsed.data;
+    // Step 2: dedup. If a previous tick already created the row (e.g.
+    // a scheduler/dispatcher restart between event.put and dispatch),
+    // the row's existing state machine is the source of truth — do
+    // NOT re-insert and do NOT re-fire the runner. The schedule row
+    // is still marked completed by the caller because the dispatch
+    // succeeded.
+    const existing = getBrowserTask(deps.db, ctx.preGeneratedTaskId);
+    if (existing) {
+        logger.warn({ taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId, state: existing.state }, "scheduled.browser_task: browser_task row already exists for preGeneratedTaskId — skipping re-dispatch");
+        return { kind: "row_already_exists", taskId: ctx.preGeneratedTaskId };
+    }
+    // Step 3: re-compose the allowlist against the live site registry.
+    const allowlist = composeAllowlistRegex({
+        siteKey: ctx.siteKey,
+        extraAllowedHosts: ctx.extraAllowedHosts,
+    });
+    if (!allowlist.ok) {
+        // site_unregistered is the documented soft failure (registry
+        // changed between schedule and fire). Other failures (too_many_extra_hosts,
+        // extra_host_must_be_hostname, extra_host_not_in_etld_set) are
+        // structural and would have been rejected at POST time; the only
+        // way they fire here is a runtime config change to
+        // EXTRA_ALLOWED_ETLD_HELPERS or a tampered schedule row. Both
+        // surface as a `failed` row with the explicit reason so the user
+        // sees what happened.
+        if (allowlist.reason === "site_unregistered") {
+            createBrowserTask(deps.db, {
+                id: ctx.preGeneratedTaskId,
+                description: ctx.description,
+                siteKey: ctx.siteKey,
+                extraAllowedHosts: [],
+                originatingChannel: ctx.originatingChannel ?? null,
+                scheduleRowId: event.scheduleId,
+                requireFinalConfirm: ctx.requireFinalConfirm ?? true,
+                effectiveAllowlistRegex: null,
+                createdAt: now(),
+            });
+            markTerminal(deps.db, {
+                id: ctx.preGeneratedTaskId,
+                state: "failed",
+                outcomeDetail: "site_unregistered",
+                report: null,
+                finishedAt: now(),
+            });
+            logger.warn({ taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId, siteKey: ctx.siteKey }, "scheduled.browser_task: siteKey unregistered at fire time — task marked failed");
+            notifyDispatchFailure(ctx.preGeneratedTaskId, ctx.originatingChannel ?? null, "site_unregistered");
+            return {
+                kind: "site_unregistered",
+                taskId: ctx.preGeneratedTaskId,
+                siteKey: ctx.siteKey,
+            };
+        }
+        createBrowserTask(deps.db, {
+            id: ctx.preGeneratedTaskId,
+            description: ctx.description,
+            siteKey: ctx.siteKey,
+            extraAllowedHosts: [],
+            originatingChannel: ctx.originatingChannel ?? null,
+            scheduleRowId: event.scheduleId,
+            requireFinalConfirm: ctx.requireFinalConfirm ?? true,
+            effectiveAllowlistRegex: null,
+            createdAt: now(),
+        });
+        markTerminal(deps.db, {
+            id: ctx.preGeneratedTaskId,
+            state: "failed",
+            outcomeDetail: `allowlist_rejected:${allowlist.reason}`,
+            report: null,
+            finishedAt: now(),
+        });
+        logger.warn({
+            taskId: ctx.preGeneratedTaskId,
+            scheduleId: event.scheduleId,
+            reason: allowlist.reason,
+            offendingHost: allowlist.offendingHost,
+        }, "scheduled.browser_task: allowlist rejected at fire time — task marked failed");
+        notifyDispatchFailure(ctx.preGeneratedTaskId, ctx.originatingChannel ?? null, `allowlist_rejected:${allowlist.reason}`);
+        return {
+            kind: "allowlist_rejected",
+            taskId: ctx.preGeneratedTaskId,
+            reason: allowlist.reason,
+            // The composer's only `offendingHost: undefined` branch is the
+            // `too_many_extra_hosts` failure, but Zod's `.max(5)` in the
+            // task_context schema rejects that shape upstream. The fallback
+            // is defence-in-depth against a future widening of the schema.
+            /* c8 ignore next 3 -- structurally unreachable: see comment above */
+            ...(allowlist.offendingHost !== undefined
+                ? { offendingHost: allowlist.offendingHost }
+                : {}),
+        };
+    }
+    // Step 4: create the `browser_task` row pinned to the pre-generated
+    // taskId. The runner picks it up from here.
+    createBrowserTask(deps.db, {
+        id: ctx.preGeneratedTaskId,
+        description: ctx.description,
+        siteKey: ctx.siteKey,
+        extraAllowedHosts: allowlist.acceptedExtras,
+        originatingChannel: ctx.originatingChannel ?? null,
+        scheduleRowId: event.scheduleId,
+        requireFinalConfirm: ctx.requireFinalConfirm ?? true,
+        effectiveAllowlistRegex: allowlist.composedSource,
+        createdAt: now(),
+    });
+    // Step 5: hand off to the runner. Fire-and-forget — `runFromScheduleRow`
+    // owns the BrowserContext + slot lifecycle from here; awaiting would
+    // block the EventBus loop for the duration of a 5-min task.
+    if (!deps.runner) {
+        // Mirror the route-layer fallback so the row doesn't park indefinitely
+        // when the runner factory hasn't landed.
+        markTerminal(deps.db, {
+            id: ctx.preGeneratedTaskId,
+            state: "failed",
+            outcomeDetail: "runner_unavailable",
+            report: null,
+            finishedAt: now(),
+        });
+        logger.warn({ taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId }, "scheduled.browser_task: runner not wired — task marked failed (runner_unavailable)");
+        notifyDispatchFailure(ctx.preGeneratedTaskId, ctx.originatingChannel ?? null, "runner_unavailable");
+        return { kind: "runner_unavailable", taskId: ctx.preGeneratedTaskId };
+    }
+    void deps.runner.runFromScheduleRow(ctx.preGeneratedTaskId).catch((err) => {
+        logger.error({ err, taskId: ctx.preGeneratedTaskId, scheduleId: event.scheduleId }, "browser-task runFromScheduleRow threw — task left in pending state");
+    });
+    logger.info({
+        taskId: ctx.preGeneratedTaskId,
+        scheduleId: event.scheduleId,
+        siteKey: ctx.siteKey,
+    }, "scheduled.browser_task dispatched to runner");
+    return { kind: "dispatched", taskId: ctx.preGeneratedTaskId };
+}