@aitne/daemon 0.1.10 → 0.1.11

package/dist/services/background-task/background-task-tools.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Background-task worker tools — BACKGROUND_TASK_RUNNER_DESIGN.md §4.1 / §4.3.
+ *
+ * The generic worker's tool envelope. Unlike browser-task's 11-tool
+ * Playwright plane, the background worker gets exactly three tools:
+ *
+ *   - `read_memory(key)` — READ-ONLY access to an allowlisted set of
+ *     owner memory / profile files so the worker can personalize results
+ *     itself rather than the brief enumerating everything (§9 / §10.4).
+ *     The worker MUST NOT write shared memory — results come back as the
+ *     artifact and the DM agent persists anything memory-worthy.
+ *   - `ask_user(question, contextSummary)` — write a clarification
+ *     artifact, park the task (`awaiting_user`), and end the turn. The
+ *     runner surfaces it through the gated delivery boundary.
+ *   - `finish(result, draft, notify, significance?)` — WRITE THE ARTIFACT
+ *     (verbatim `result` + plain `draft` summary + the `notify`
+ *     disposition the worker evaluated against the spawn-time policy) and
+ *     complete the task. The runner's reconcile hook reads the artifact
+ *     and decides delivery.
+ *
+ * The tools do NOT send DMs or enqueue delivery — they only write to the
+ * task store + transition state. Delivery is the runner's job (it owns
+ * the `notify` gate + the `task.delivery` enqueue), keeping the
+ * disposition decision in one place. This module is store-write glue,
+ * excluded from the coverage gate; the pure decision (`notify` evaluation)
+ * is the worker's, and the budget arithmetic is covered separately.
+ */
+import type Database from "better-sqlite3";
+import { type McpSdkServerConfigWithInstance } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { type BackgroundTaskTransitionEmitter } from "./background-task-transition-events.js";
+export declare const BACKGROUND_TASK_MCP_SERVER_NAME = "aitne-task";
+export declare const BACKGROUND_TASK_TOOL_FQNS: readonly ["mcp__aitne-task__read_memory", "mcp__aitne-task__ask_user", "mcp__aitne-task__finish"];
+export declare const MEMORY_KEYS: readonly string[];
+export interface BackgroundTaskRuntime {
+    taskId: string;
+    db: Database.Database;
+    /** Vault root for `read_memory`. */
+    contextDir: string;
+    /** Clarification TTL in ms (from `backgroundTaskClarificationTtlMinutes`). */
+    clarificationTtlMs: number;
+    transitionEmitter: BackgroundTaskTransitionEmitter;
+    abortSignal: AbortSignal;
+    /** Set true once `ask_user` parks the task — read by the runner's
+     *  post-execute hook to distinguish a clean park from a hang. */
+    yieldFlag: {
+        current: boolean;
+    };
+    /** Set true once `finish` writes the artifact — read by the runner to
+     *  confirm a clean completion vs an SDK-side natural end. */
+    finishFlag: {
+        current: boolean;
+    };
+    nowFn?: () => number;
+}
+export declare function createBackgroundTaskRuntime(input: {
+    taskId: string;
+    db: Database.Database;
+    contextDir: string;
+    clarificationTtlMs: number;
+    abortSignal: AbortSignal;
+    transitionEmitter?: BackgroundTaskTransitionEmitter;
+    nowFn?: () => number;
+}): BackgroundTaskRuntime;
+/** The three worker tools, bound to a runtime. Exported so tests can
+ *  invoke a tool's `handler` directly without standing up the MCP
+ *  transport. */
+export declare function createBackgroundTaskTools(runtime: BackgroundTaskRuntime): (import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    key: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+}> | import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    question: z.ZodString;
+    contextSummary: z.ZodOptional<z.ZodString>;
+}> | import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    result: z.ZodString;
+    draft: z.ZodString;
+    notify: z.ZodBoolean;
+    significance: z.ZodOptional<z.ZodString>;
+}>)[];
+/** Construct the per-task MCP server. Returned config is passed verbatim
+ *  into `query({ options: { mcpServers: { [BACKGROUND_TASK_MCP_SERVER_NAME]:
+ *  <return value> } } })`. */
+export declare function createBackgroundTaskMcpServer(runtime: BackgroundTaskRuntime): McpSdkServerConfigWithInstance;

package/dist/services/background-task/background-task-tools.js

@@ -0,0 +1,247 @@
+/**
+ * Background-task worker tools — BACKGROUND_TASK_RUNNER_DESIGN.md §4.1 / §4.3.
+ *
+ * The generic worker's tool envelope. Unlike browser-task's 11-tool
+ * Playwright plane, the background worker gets exactly three tools:
+ *
+ *   - `read_memory(key)` — READ-ONLY access to an allowlisted set of
+ *     owner memory / profile files so the worker can personalize results
+ *     itself rather than the brief enumerating everything (§9 / §10.4).
+ *     The worker MUST NOT write shared memory — results come back as the
+ *     artifact and the DM agent persists anything memory-worthy.
+ *   - `ask_user(question, contextSummary)` — write a clarification
+ *     artifact, park the task (`awaiting_user`), and end the turn. The
+ *     runner surfaces it through the gated delivery boundary.
+ *   - `finish(result, draft, notify, significance?)` — WRITE THE ARTIFACT
+ *     (verbatim `result` + plain `draft` summary + the `notify`
+ *     disposition the worker evaluated against the spawn-time policy) and
+ *     complete the task. The runner's reconcile hook reads the artifact
+ *     and decides delivery.
+ *
+ * The tools do NOT send DMs or enqueue delivery — they only write to the
+ * task store + transition state. Delivery is the runner's job (it owns
+ * the `notify` gate + the `task.delivery` enqueue), keeping the
+ * disposition decision in one place. This module is store-write glue,
+ * excluded from the coverage gate; the pure decision (`notify` evaluation)
+ * is the worker's, and the budget arithmetic is covered separately.
+ */
+import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { createSdkMcpServer, tool, } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { createClarification } from "../../db/background-task-clarifications-store.js";
+import { markAwaitingUser, markTerminal, } from "../../db/background-task-store.js";
+import { CONTEXT_RELATIVE_PATHS, fullPath } from "../../core/context-paths.js";
+import { noopBackgroundTaskTransitionEmitter, } from "./background-task-transition-events.js";
+import { createLogger } from "../../logging.js";
+const logger = createLogger("background-task-tools");
+export const BACKGROUND_TASK_MCP_SERVER_NAME = "aitne-task";
+export const BACKGROUND_TASK_TOOL_FQNS = [
+    `mcp__${BACKGROUND_TASK_MCP_SERVER_NAME}__read_memory`,
+    `mcp__${BACKGROUND_TASK_MCP_SERVER_NAME}__ask_user`,
+    `mcp__${BACKGROUND_TASK_MCP_SERVER_NAME}__finish`,
+];
+/** Per-read output cap so a large memory file can't blow the worker's
+ *  context window or budget in one tool call. */
+const MEMORY_READ_CHAR_CAP = 8_000;
+/**
+ * Allowlist of READ-ONLY memory keys → vault-relative paths. A fixed
+ * enum (no user-controlled path component) so there is no traversal
+ * surface. Single files only; the worker reads what it needs to
+ * personalize a result (the owner's profile, today's state, project
+ * context, the management policy).
+ */
+const MEMORY_FILE_ALLOWLIST = {
+    today: CONTEXT_RELATIVE_PATHS.today,
+    profile: CONTEXT_RELATIVE_PATHS.user.profile,
+    people: CONTEXT_RELATIVE_PATHS.user.people,
+    work: CONTEXT_RELATIVE_PATHS.user.work,
+    goals: CONTEXT_RELATIVE_PATHS.user.goals,
+    projects: CONTEXT_RELATIVE_PATHS.projects.index,
+    management: CONTEXT_RELATIVE_PATHS.rules.management,
+    integrations: CONTEXT_RELATIVE_PATHS.integrations,
+};
+export const MEMORY_KEYS = Object.keys(MEMORY_FILE_ALLOWLIST);
+// The SDK `tool()` helper takes a Zod RAW SHAPE (a `{ key: ZodType }`
+// object), not a `z.object(...)` — mirroring browser-task's schemas.
+const readMemoryArgsSchema = {
+    key: z
+        .enum(Object.keys(MEMORY_FILE_ALLOWLIST))
+        .describe("Which owner memory file to read. One of: "
+        + MEMORY_KEYS.join(", ")
+        + ". Read-only."),
+};
+const askUserArgsSchema = {
+    question: z
+        .string()
+        .min(1)
+        .max(2_000)
+        .describe("The clarification you need from the owner, phrased plainly. The DM agent weaves this into the conversation."),
+    contextSummary: z
+        .string()
+        .max(2_000)
+        .optional()
+        .describe("Optional one-paragraph recap of where the task is and why you're stuck, so the owner can answer without re-reading the whole brief."),
+};
+const finishArgsSchema = {
+    result: z
+        .string()
+        .min(1)
+        .max(100_000)
+        .describe("The FULL, verbatim outcome — every finding, number, URL, and id. Persisted unchanged as the fidelity anchor; precise follow-ups read this. Do NOT summarize here."),
+    draft: z
+        .string()
+        .min(1)
+        .max(4_000)
+        .describe("A plain, human-readable summary in the owner's language. NOT the final DM — the DM agent uses this as grounding / the idle-send body. 1-4 short paragraphs."),
+    notify: z
+        .boolean()
+        .describe("Your disposition vs the spawn-time notification policy. always ⇒ true (even for a '0 issues' result — the owner asked). if_significant ⇒ true ONLY if the brief's concrete criteria are met. silent ⇒ false. When unsure on always, prefer true."),
+    significance: z
+        .string()
+        .max(500)
+        .optional()
+        .describe("One line on why notify is true/false (e.g. '2 repos red' / 'no criteria met'). Used in the filed-results digest + audit."),
+};
+export function createBackgroundTaskRuntime(input) {
+    return {
+        taskId: input.taskId,
+        db: input.db,
+        contextDir: input.contextDir,
+        clarificationTtlMs: input.clarificationTtlMs,
+        abortSignal: input.abortSignal,
+        transitionEmitter: input.transitionEmitter ?? noopBackgroundTaskTransitionEmitter,
+        yieldFlag: { current: false },
+        finishFlag: { current: false },
+        nowFn: input.nowFn,
+    };
+}
+function textResult(payload, isError = false) {
+    return {
+        isError,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+function makeReadMemoryTool(runtime) {
+    return tool("read_memory", "Read one owner memory / profile file (read-only) to personalize your result. Keys: "
+        + MEMORY_KEYS.join(", ")
+        + ". You cannot write memory — return everything memory-worthy in finish().", readMemoryArgsSchema, async (args) => {
+        const relative = MEMORY_FILE_ALLOWLIST[args.key];
+        if (!relative) {
+            return textResult({ ok: false, error: "unknown_key", detail: `key must be one of: ${MEMORY_KEYS.join(", ")}` }, true);
+        }
+        const path = fullPath(runtime.contextDir, relative);
+        try {
+            const raw = await readFile(path, "utf-8");
+            const truncated = raw.length > MEMORY_READ_CHAR_CAP;
+            const content = truncated ? raw.slice(0, MEMORY_READ_CHAR_CAP) : raw;
+            return textResult({
+                ok: true,
+                key: args.key,
+                truncated,
+                content: truncated
+                    ? `${content}\n\n[... truncated at ${MEMORY_READ_CHAR_CAP} chars]`
+                    : content,
+            });
+        }
+        catch {
+            // Missing file is normal (a fresh vault may not have every file).
+            return textResult({
+                ok: true,
+                key: args.key,
+                truncated: false,
+                content: "",
+                note: "file not present in the vault yet",
+            });
+        }
+    });
+}
+function makeAskUserTool(runtime) {
+    return tool("ask_user", "Pause for an owner clarification. Writes the question, parks your task, and ends the turn — the DM agent surfaces it and relays the answer back so you resume. Call this and then STOP; do not call further tools this turn.", askUserArgsSchema, async (args) => {
+        const now = (runtime.nowFn ?? (() => Date.now()))();
+        // running → awaiting_user CAS before writing the clarification row.
+        // On a CAS miss the task already transitioned (cancel-while-running)
+        // — bail without committing an orphan row the deadline tick would
+        // later process for a terminal task.
+        const parked = markAwaitingUser(runtime.db, runtime.taskId);
+        if (!parked) {
+            return textResult({
+                ok: false,
+                error: "task_not_running",
+                detail: "This task is no longer running (it may have been cancelled). Stop now.",
+            }, true);
+        }
+        const id = randomUUID();
+        const row = createClarification(runtime.db, {
+            id,
+            taskId: runtime.taskId,
+            question: args.question,
+            contextSummary: args.contextSummary ?? null,
+            askedAt: now,
+            ttlMs: runtime.clarificationTtlMs,
+        });
+        runtime.yieldFlag.current = true;
+        runtime.transitionEmitter.emitFromRow(parked, now);
+        return textResult({
+            ok: true,
+            status: "parked",
+            clarificationId: id,
+            deadlineAt: row.deadlineAt,
+            note: "Your task is parked. STOP now — the owner's answer will resume you.",
+        });
+    });
+}
+function makeFinishTool(runtime) {
+    return tool("finish", "Done. Writes your artifact (verbatim result + plain draft summary + the notify disposition) and completes the task. Do not call any tool after finish — your session ends here.", finishArgsSchema, async (args) => {
+        const now = (runtime.nowFn ?? (() => Date.now()))();
+        const terminal = markTerminal(runtime.db, {
+            id: runtime.taskId,
+            state: "completed",
+            outcomeDetail: null,
+            finishedAt: now,
+            report: args.result,
+            draft: args.draft,
+            notify: args.notify,
+            significance: args.significance ?? null,
+        });
+        if (!terminal) {
+            // CAS miss — the task was already cancelled / timed out. Surface
+            // it so the agent stops; the artifact is intentionally not forced
+            // onto a terminal row.
+            return textResult({
+                ok: false,
+                error: "task_not_active",
+                detail: "This task already reached a terminal state; the result was not stored. Stop now.",
+            }, true);
+        }
+        runtime.finishFlag.current = true;
+        runtime.transitionEmitter.emitFromRow(terminal, now);
+        return textResult({
+            ok: true,
+            completed: true,
+            notify: args.notify,
+            state: terminal.state,
+        });
+    });
+}
+/** The three worker tools, bound to a runtime. Exported so tests can
+ *  invoke a tool's `handler` directly without standing up the MCP
+ *  transport. */
+export function createBackgroundTaskTools(runtime) {
+    return [
+        makeReadMemoryTool(runtime),
+        makeAskUserTool(runtime),
+        makeFinishTool(runtime),
+    ];
+}
+/** Construct the per-task MCP server. Returned config is passed verbatim
+ *  into `query({ options: { mcpServers: { [BACKGROUND_TASK_MCP_SERVER_NAME]:
+ *  <return value> } } })`. */
+export function createBackgroundTaskMcpServer(runtime) {
+    return createSdkMcpServer({
+        name: BACKGROUND_TASK_MCP_SERVER_NAME,
+        version: "1.0.0",
+        tools: createBackgroundTaskTools(runtime),
+    });
+}
+void logger;

package/dist/services/background-task/background-task-transition-events.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Background-task SSE transition emitter — BACKGROUND_TASK_RUNNER_DESIGN.md
+ * §15 (dashboard). Emits a `background_task` named event on the global
+ * `/api/events/stream` on every state transition so a future dashboard
+ * surface can invalidate its list/detail queries without per-id polling.
+ *
+ * Per `project_dashboard_testing`: `background_task` arrives on the
+ * default `event` stream with a `kind` field — here the named-event
+ * channel is `"background_task"`, payload bounded and ASCII-safe.
+ *
+ * Mirrors `browser-task-transition-events.ts`: a thin telemetry interface
+ * separate from the delivery path (which fans user-facing DMs). The
+ * payload never carries the full report — only an 80-char title/brief.
+ */
+import type { BackgroundTaskRow } from "../../db/background-task-store.js";
+export interface BackgroundTaskTransitionPayload {
+    taskId: string;
+    state: BackgroundTaskRow["state"];
+    /** Epoch ms — finishedAt for terminal rows, startedAt for running,
+     *  createdAt for pending. Cache-busting timestamp only. */
+    transitionedAt: number;
+    /** First 80 chars of the title (or brief), control chars scrubbed. */
+    brief: string;
+    outcomeDetail: string | null;
+    /** Worker disposition once finished (null while in-flight). */
+    notify: boolean | null;
+    originatingChannel: string | null;
+}
+/** Minimal broadcaster surface — the impl lives in `api/routes/sse.ts`.
+ *  Declared structurally so the daemon's `services/background-task/*`
+ *  modules don't depend on the HTTP layer. */
+export interface BroadcastSink {
+    broadcastNamedEvent(event: string, data: unknown): Promise<void> | void;
+}
+export interface BackgroundTaskTransitionEmitter {
+    emit(payload: BackgroundTaskTransitionPayload): void;
+    /** Extract fields from a row + transitionedAt and emit. Returns the
+     *  payload (or null when row is null) for test chaining. */
+    emitFromRow(row: BackgroundTaskRow | null, transitionedAt: number): BackgroundTaskTransitionPayload | null;
+}
+export declare function briefPayload(row: BackgroundTaskRow, transitionedAt: number): BackgroundTaskTransitionPayload;
+export declare const noopBackgroundTaskTransitionEmitter: BackgroundTaskTransitionEmitter;
+export declare function createBackgroundTaskTransitionEmitter(sink: BroadcastSink | null | undefined): BackgroundTaskTransitionEmitter;

package/dist/services/background-task/background-task-transition-events.js

@@ -0,0 +1,54 @@
+/**
+ * Background-task SSE transition emitter — BACKGROUND_TASK_RUNNER_DESIGN.md
+ * §15 (dashboard). Emits a `background_task` named event on the global
+ * `/api/events/stream` on every state transition so a future dashboard
+ * surface can invalidate its list/detail queries without per-id polling.
+ *
+ * Per `project_dashboard_testing`: `background_task` arrives on the
+ * default `event` stream with a `kind` field — here the named-event
+ * channel is `"background_task"`, payload bounded and ASCII-safe.
+ *
+ * Mirrors `browser-task-transition-events.ts`: a thin telemetry interface
+ * separate from the delivery path (which fans user-facing DMs). The
+ * payload never carries the full report — only an 80-char title/brief.
+ */
+const CONTROL_CHAR_REGEX = new RegExp("[\\x00-\\x1f\\x7f]", "g");
+export function briefPayload(row, transitionedAt) {
+    const source = row.title && row.title.length > 0 ? row.title : row.brief;
+    const brief = source.replace(CONTROL_CHAR_REGEX, " ").slice(0, 80);
+    return {
+        taskId: row.id,
+        state: row.state,
+        transitionedAt,
+        brief,
+        outcomeDetail: row.outcomeDetail,
+        notify: row.notify,
+        originatingChannel: row.originatingChannel,
+    };
+}
+export const noopBackgroundTaskTransitionEmitter = {
+    emit() {
+        /* no-op */
+    },
+    emitFromRow(row, transitionedAt) {
+        if (!row)
+            return null;
+        return briefPayload(row, transitionedAt);
+    },
+};
+export function createBackgroundTaskTransitionEmitter(sink) {
+    if (!sink)
+        return noopBackgroundTaskTransitionEmitter;
+    return {
+        emit(payload) {
+            void sink.broadcastNamedEvent("background_task", payload);
+        },
+        emitFromRow(row, transitionedAt) {
+            if (!row)
+                return null;
+            const payload = briefPayload(row, transitionedAt);
+            void sink.broadcastNamedEvent("background_task", payload);
+            return payload;
+        },
+    };
+}

package/dist/services/browser-history/automation/egress-denylist.d.ts

@@ -161,7 +161,7 @@ export declare function shouldDenyEgress(url: string, opts?: {
     hostnameDenylist?: ReadonlyArray<RegExp>;
 }): Promise<{
     denied: true;
-    reason: "hostname" | "cidr" | "invalid_url";
+    reason: "hostname" | "cidr" | "invalid_url" | "resolve_error";
 } | {
     denied: false;
 }>;

package/dist/services/browser-history/automation/egress-denylist.js

@@ -437,16 +437,26 @@ export async function shouldDenyEgress(url, opts) {
         return { denied: false };
     }
     if (opts?.resolveIps) {
-        let resolved = [];
+        let resolved;
         try {
             resolved = await opts.resolveIps(hostname);
         }
         catch {
-            // DNS failure → let the request through; if the lookup is broken
-            // here it will fail at the network layer too. Failing closed
-            // (treating a DNS error as a block) would brick every workflow
-            // during a temporary resolver outage.
-            return { denied: false };
+            // Fail CLOSED. This CIDR gate is the primary defence against egress to
+            // private / link-local / cloud-metadata IPs (the browser sandbox shares
+            // the host network namespace, so there is no packet-layer block behind
+            // it). The guard and Chromium resolve the hostname independently — a
+            // name that Node's resolver fails on but Chromium's resolver succeeds on
+            // (SERVFAIL / timeout / search-domain / IDN differences) would otherwise
+            // reach an internal address completely unchecked. Blocking on resolve
+            // failure closes that differential-resolver gap; a host that is
+            // genuinely unresolvable would fail at the network layer regardless.
+            return { denied: true, reason: "resolve_error" };
+        }
+        if (resolved.length === 0) {
+            // No addresses to vet is as unverifiable as a thrown lookup — don't let
+            // the host through to Chromium's independent resolution.
+            return { denied: true, reason: "resolve_error" };
         }
         for (const ip of resolved) {
             if (matchesCidrDenylist(ip)) {

package/dist/services/browser-history/managed-chromium/sandbox-launcher.js

@@ -233,7 +233,6 @@ function loadWindowsHelper() {
     // a module-scope global — build one via `createRequire` to reach the
     // CommonJS loader. This branch only runs on win32.
     const req = createRequire(import.meta.url);
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const mod = req("../../../../native/win-appcontainer/loader.js");
     return mod.loadHelper();
 }

package/dist/services/browser-task/browser-task-runner.js

@@ -34,7 +34,7 @@ import { getBrowserTask, markRunning, markRunningFromParked, markTerminal, } fro
 import { resolveClarification } from "../../db/browser-task-clarifications-store.js";
 import { createLogger } from "../../logging.js";
 import { prepareDriverHandle, releaseDriverHandle, resumeDriver, runDriver, } from "./browser-task-driver.js";
-import { createInitialSlotState, decideAcquire, decidePark, decideRelease, decideUnpark, } from "./browser-task-slots.js";
+import { createInitialSlotState, decideAcquire, decideCancel, decidePark, decideRelease, decideUnpark, } from "./browser-task-slots.js";
 import { noopBrowserTaskTransitionEmitter, } from "./browser-task-transition-events.js";
 const logger = createLogger("browser-task-runner");
 /**
@@ -52,6 +52,16 @@ const logger = createLogger("browser-task-runner");
 function slotSiteKeyForRow(row) {
     return row.siteKey ?? `__open__:${row.id}`;
 }
+/** True when the slot manager already tracks `taskId` as an active
+ *  occupant (acquired a slot), even if the DB row still reads `pending`
+ *  in the narrow acquire→markRunning window. Mirrors the route helper. */
+function slotManagerHasActive(state, taskId) {
+    for (const entry of state.active.values()) {
+        if (entry.taskId === taskId)
+            return true;
+    }
+    return false;
+}
 export function createSlotStateRef(maxConcurrent) {
     return { state: createInitialSlotState(maxConcurrent) };
 }
@@ -494,15 +504,50 @@ export function createBrowserTaskRunner(deps) {
             // landing in that window is silently dropped and the SDK runs
             // anyway, burning turns / cost.
             //
-            // Other non-terminal states are deliberately excluded: `pending`
-            // is route-handled (decideCancel removes the FIFO entry) and the
-            // parked states (`awaiting_user`/`final_confirm`) always have a
-            // tracked handle, so they take the `handle` branch above. Recording
-            // a pending-abort for a `pending` row would leak the map entry —
-            // nothing ever consumes it (`runDriverFromPending` only drains it
-            // after `prepareDriverHandle`, which a pending row never reaches).
+            // The parked states (`awaiting_user`/`final_confirm`) always have a
+            // tracked handle, so they take the `handle` branch above.
             pendingAborts.set(taskId, reason || "cancel");
         }
+        else if (row.state === "pending") {
+            // Queued behind the concurrency cap (or in the narrow acquire→
+            // markRunning window). The HTTP `/cancel` route handles `pending`
+            // itself, but `!stop <id>` (Phase 4) calls `cancel()` directly — so
+            // the runner must own this state too, or the bang path reports a
+            // false "Stopping…" while the task keeps running.
+            if (slotManagerHasActive(deps.slotStateRef.state, taskId)) {
+                // `tryAcquire` already promoted the task (slot active) but
+                // `markRunning` hasn't flipped the DB row yet — `decideCancel`
+                // would throw on an active occupant. Record the abort intent like
+                // the running case; the handle registered at `runDriverFromPending`
+                // fires it before the SDK loop begins (and drains the map entry,
+                // so it does not leak).
+                pendingAborts.set(taskId, reason || "cancel");
+            }
+            else {
+                // Genuinely queued — drop the FIFO entry and write the terminal
+                // directly (no slot was held, so no release cascade). Mirrors the
+                // route's `isPending` path and the background runner.
+                try {
+                    deps.slotStateRef.state = decideCancel(deps.slotStateRef.state, taskId).state;
+                }
+                catch (err) {
+                    /* c8 ignore start -- defensive: slot promoted between the check and here */
+                    logger.warn({ err, taskId }, "decideCancel on pending row failed (continuing)");
+                    /* c8 ignore stop */
+                }
+                const finishedAt = now();
+                const terminal = markTerminal(deps.db, {
+                    id: taskId,
+                    state: "cancelled",
+                    outcomeDetail: `cancelled_in_queue:${reason}`,
+                    report: null,
+                    finishedAt,
+                });
+                emitter.emitFromRow(terminal, finishedAt);
+                logger.info({ taskId, reason }, "browser-task cancel (pending → cancelled)");
+                return true;
+            }
+        }
         if (handle) {
             // Cancel any pending lite-final-confirm tokens issued by this
             // task — otherwise a gate that was mid-flight leaves a token

package/dist/services/observations-batch.d.ts

@@ -58,7 +58,7 @@ export interface ProcessBatchResult {
 export declare function inferIntegrationKeyFromSource(source: string): IntegrationKey | null;
 /**
  * Normalize pre-pass mail payloads at the ingest chokepoint so the
- * hourly-check gate can read a canonical shape regardless of mode. See
+ * activity-scan gate can read a canonical shape regardless of mode. See
  * HOURLY_CHECK_GATE_REDESIGN_PLAN.md for the full rationale; the rules:
  *   - mail integration source AND `payload.raw.from` is a string → set
  *     `is_read = 0` and `from_email = <lowercased extracted address>`

package/dist/services/observations-batch.js

@@ -50,7 +50,7 @@ export function inferIntegrationKeyFromSource(source) {
 }
 /** Per-integration source prefixes whose pre-pass payload carries the
  *  mail shape (`payload.raw.from`, no `is_read`). Drives
- *  {@link normalizeMailObservationPayload} so the hourly-check gate can
+ *  {@link normalizeMailObservationPayload} so the activity-scan gate can
  *  read a canonical `is_read` + `from_email` shape regardless of mode. */
 const MAIL_OBSERVATION_INTEGRATION_KEYS = new Set(INTEGRATION_KEYS.filter((k) => {
     const partial = INTEGRATION_DESCRIPTORS[k].prePassPartial;
@@ -65,7 +65,7 @@ function extractEmailAddress(raw) {
 }
 /**
  * Normalize pre-pass mail payloads at the ingest chokepoint so the
- * hourly-check gate can read a canonical shape regardless of mode. See
+ * activity-scan gate can read a canonical shape regardless of mode. See
  * HOURLY_CHECK_GATE_REDESIGN_PLAN.md for the full rationale; the rules:
  *   - mail integration source AND `payload.raw.from` is a string → set
  *     `is_read = 0` and `from_email = <lowercased extracted address>`