@aitne/daemon 0.1.7 → 0.1.9

package/dist/services/browser-history/automation/browser-task-tools/dom-snapshot-output.js

@@ -0,0 +1,98 @@
+/**
+ * Pure helpers for the `dom_snapshot` tool —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5.
+ *
+ * Playwright's `page.accessibility.snapshot()` returns a tree shape
+ * `{ role, name, value, children, ... }`. The runner serialises that
+ * into a compact text outline (one node per indented line) and
+ * truncates the result to fit the per-call budget:
+ *
+ *   - Hard cap: 32 KB (the tool table in §5 says "≤ 32 KB").
+ *   - Default node cap: 1500 (peak `maxNodes` schema-side is 5000).
+ *
+ * The serialiser is a pure tree walk + render. No I/O. 100% covered.
+ */
+/** §5 — hard byte cap on the rendered output. */
+export const DOM_SNAPSHOT_MAX_BYTES = 32 * 1024;
+/** Default `maxNodes` when the caller does not pass one. */
+export const DOM_SNAPSHOT_DEFAULT_MAX_NODES = 1500;
+export function renderAccessibilityTree(input) {
+    if (!input.root) {
+        return { ariaTree: "", nodesRendered: 0, truncated: false };
+    }
+    const maxNodes = clampMaxNodes(input.maxNodes ?? DOM_SNAPSHOT_DEFAULT_MAX_NODES);
+    const lines = [];
+    let nodesRendered = 0;
+    let truncated = false;
+    let byteBudget = DOM_SNAPSHOT_MAX_BYTES;
+    const stack = [
+        { node: input.root, depth: 0 },
+    ];
+    while (stack.length > 0) {
+        const top = stack.shift();
+        if (nodesRendered >= maxNodes) {
+            truncated = true;
+            break;
+        }
+        const line = renderNode(top.node, top.depth);
+        // Each line carries its trailing `\n` for the byte budget.
+        const lineLen = Buffer.byteLength(line, "utf8") + 1;
+        if (lineLen > byteBudget) {
+            truncated = true;
+            break;
+        }
+        lines.push(line);
+        nodesRendered += 1;
+        byteBudget -= lineLen;
+        if (top.node.children) {
+            // BFS-ish: append children to the front so order is preserved
+            // and the depth label is correct. Walking DFS-then-children
+            // keeps the output readable (each subtree appears contiguous).
+            const childEntries = top.node.children.map((child) => ({
+                node: child,
+                depth: top.depth + 1,
+            }));
+            stack.unshift(...childEntries);
+        }
+    }
+    return {
+        ariaTree: lines.join("\n"),
+        nodesRendered,
+        truncated,
+    };
+}
+function renderNode(node, depth) {
+    const indent = "  ".repeat(depth);
+    const role = (node.role ?? "node").trim() || "node";
+    const fragments = [role];
+    if (typeof node.name === "string" && node.name.length > 0) {
+        fragments.push(`"${truncateLabel(node.name)}"`);
+    }
+    if (node.value !== null && node.value !== undefined && `${node.value}`.length > 0) {
+        fragments.push(`value="${truncateLabel(`${node.value}`)}"`);
+    }
+    if (node.description && node.description.length > 0) {
+        fragments.push(`desc="${truncateLabel(node.description)}"`);
+    }
+    if (node.focused === true)
+        fragments.push("focused");
+    if (node.checked === true)
+        fragments.push("checked");
+    if (node.checked === "mixed")
+        fragments.push("checked=mixed");
+    if (node.expanded === true)
+        fragments.push("expanded");
+    return `${indent}- ${fragments.join(" ")}`;
+}
+function truncateLabel(s) {
+    const trimmed = s.replace(/\s+/g, " ").trim();
+    return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+}
+/** Clamp `maxNodes` to the schema range. */
+export function clampMaxNodes(value) {
+    if (!Number.isFinite(value) || value < 1)
+        return 1;
+    if (value > 5000)
+        return 5000;
+    return Math.floor(value);
+}

package/dist/services/browser-history/automation/browser-task-tools/extract-cap.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Per-task cumulative extract cap — BROWSER_TASK_REDESIGN_PLAN.md §14.6.
+ *
+ * The `extract` tool already caps each call's output at `maxChars`
+ * (default 8 KB). §14.6 adds a CUMULATIVE cap so a page that returns
+ * 8 KB of attacker prose 30 times can't erode the
+ * `<external-content>` wrapper's "treat as data" instruction through
+ * sheer volume.
+ *
+ * Cap: `EXTRACT_CUMULATIVE_CAP_CHARS = 128 * 1024` (128 KB).
+ *
+ * Pure decision module. The runner allocates one `ExtractCapState`
+ * per task and threads it through every `extract` call. When the
+ * cumulative counter would exceed the cap, the helper returns the
+ * sentinel string per §14.6 and `outcome='extract_cap_exceeded'` so
+ * the audit row is unambiguous. The cap does NOT abort the task —
+ * the model can still call `finish` with what it already has.
+ *
+ * 100% coverage gate per §14.12.
+ */
+/** §14.6 — 128 KB cumulative cap. */
+export declare const EXTRACT_CUMULATIVE_CAP_CHARS: number;
+/** §5 — default per-call cap (8 KB). Mirrors the tool spec. */
+export declare const EXTRACT_PER_CALL_DEFAULT_CHARS: number;
+/** §5 — upper bound the per-call `maxChars` arg may request. The Zod
+ *  schema caps at this; the cumulative cap then runs on top. */
+export declare const EXTRACT_PER_CALL_MAX_CHARS: number;
+/** Per-task counter. The runner replaces the state after every
+ *  successful extract; the cumulative cap helper is the only thing
+ *  that mutates it. */
+export interface ExtractCapState {
+    readonly accumulatedChars: number;
+}
+export declare function createExtractCapState(): ExtractCapState;
+export type ExtractCapDecision = {
+    kind: "ok";
+    state: ExtractCapState;
+    /** Number of characters the runner should actually accept into
+     *  the response after the per-call cap has been applied. May be
+     *  less than `requestedChars` when the request would have
+     *  pushed the cumulative counter past the cap; in that case
+     *  the caller clamps the output and records a normal `ok`
+     *  outcome — only a HARD overflow (zero room left) returns
+     *  the `cap_exceeded` sentinel. */
+    acceptedChars: number;
+} | {
+    kind: "cap_exceeded";
+    state: ExtractCapState;
+    /** Sentinel content body per §14.6 — wrapped by the tool body
+     *  in `<external-content>` before being returned to the agent. */
+    sentinel: string;
+};
+/**
+ * Decide how to handle a fresh extract.
+ *
+ * Inputs:
+ *   - `state`: current per-task cumulative counter.
+ *   - `requestedChars`: number of characters the tool body wants to
+ *     return after the per-call `maxChars` clamp has been applied.
+ *
+ * Output:
+ *   - `kind: 'ok'` — accepted; state advances by `acceptedChars`. The
+ *     caller writes its real content (truncated to `acceptedChars` if
+ *     necessary) into the `<external-content>` wrapper.
+ *   - `kind: 'cap_exceeded'` — no room left; the caller returns the
+ *     sentinel verbatim and writes an `outcome='extract_cap_exceeded'`
+ *     audit row. State counter does NOT advance (the sentinel itself
+ *     is not user data).
+ */
+export declare function decideExtractCap(state: ExtractCapState, requestedChars: number): ExtractCapDecision;
+/**
+ * The exact body the tool returns inside `<external-content>` when
+ * the cumulative cap trips. Tests pin the literal so a future
+ * widening cannot silently break agent-side parsing.
+ */
+export declare function renderCapExceededSentinel(accumulatedChars: number): string;

package/dist/services/browser-history/automation/browser-task-tools/extract-cap.js

@@ -0,0 +1,79 @@
+/**
+ * Per-task cumulative extract cap — BROWSER_TASK_REDESIGN_PLAN.md §14.6.
+ *
+ * The `extract` tool already caps each call's output at `maxChars`
+ * (default 8 KB). §14.6 adds a CUMULATIVE cap so a page that returns
+ * 8 KB of attacker prose 30 times can't erode the
+ * `<external-content>` wrapper's "treat as data" instruction through
+ * sheer volume.
+ *
+ * Cap: `EXTRACT_CUMULATIVE_CAP_CHARS = 128 * 1024` (128 KB).
+ *
+ * Pure decision module. The runner allocates one `ExtractCapState`
+ * per task and threads it through every `extract` call. When the
+ * cumulative counter would exceed the cap, the helper returns the
+ * sentinel string per §14.6 and `outcome='extract_cap_exceeded'` so
+ * the audit row is unambiguous. The cap does NOT abort the task —
+ * the model can still call `finish` with what it already has.
+ *
+ * 100% coverage gate per §14.12.
+ */
+/** §14.6 — 128 KB cumulative cap. */
+export const EXTRACT_CUMULATIVE_CAP_CHARS = 128 * 1024;
+/** §5 — default per-call cap (8 KB). Mirrors the tool spec. */
+export const EXTRACT_PER_CALL_DEFAULT_CHARS = 8 * 1024;
+/** §5 — upper bound the per-call `maxChars` arg may request. The Zod
+ *  schema caps at this; the cumulative cap then runs on top. */
+export const EXTRACT_PER_CALL_MAX_CHARS = 32 * 1024;
+export function createExtractCapState() {
+    return { accumulatedChars: 0 };
+}
+/**
+ * Decide how to handle a fresh extract.
+ *
+ * Inputs:
+ *   - `state`: current per-task cumulative counter.
+ *   - `requestedChars`: number of characters the tool body wants to
+ *     return after the per-call `maxChars` clamp has been applied.
+ *
+ * Output:
+ *   - `kind: 'ok'` — accepted; state advances by `acceptedChars`. The
+ *     caller writes its real content (truncated to `acceptedChars` if
+ *     necessary) into the `<external-content>` wrapper.
+ *   - `kind: 'cap_exceeded'` — no room left; the caller returns the
+ *     sentinel verbatim and writes an `outcome='extract_cap_exceeded'`
+ *     audit row. State counter does NOT advance (the sentinel itself
+ *     is not user data).
+ */
+export function decideExtractCap(state, requestedChars) {
+    if (!Number.isFinite(requestedChars) || requestedChars < 0) {
+        // Defensive — a caller passing NaN or a negative would corrupt
+        // the counter. Treat as zero-byte extract and return `ok` so the
+        // tool body can finish its happy path.
+        return { kind: "ok", state, acceptedChars: 0 };
+    }
+    const remaining = EXTRACT_CUMULATIVE_CAP_CHARS - state.accumulatedChars;
+    if (remaining <= 0) {
+        return {
+            kind: "cap_exceeded",
+            state,
+            sentinel: renderCapExceededSentinel(state.accumulatedChars),
+        };
+    }
+    const accepted = Math.min(Math.floor(requestedChars), remaining);
+    return {
+        kind: "ok",
+        state: { accumulatedChars: state.accumulatedChars + accepted },
+        acceptedChars: accepted,
+    };
+}
+/**
+ * The exact body the tool returns inside `<external-content>` when
+ * the cumulative cap trips. Tests pin the literal so a future
+ * widening cannot silently break agent-side parsing.
+ */
+export function renderCapExceededSentinel(accumulatedChars) {
+    const kb = Math.round((accumulatedChars / 1024) * 10) / 10;
+    return (`[EXTRACT_CAP_EXCEEDED — accumulated ${kb}KB of untrusted content `
+        + "in this task; further reads denied until task ends]");
+}

package/dist/services/browser-history/automation/browser-task-tools/extract-output.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure output builder for the `extract` tool —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.6.
+ *
+ * Given:
+ *   - raw page text (extractor output BEFORE per-call clamp)
+ *   - per-call `maxChars` clamp
+ *   - per-task cumulative cap state
+ *   - origin URL
+ *
+ * Produce:
+ *   - the `<external-content origin="…">…</external-content>` string
+ *     the runner returns to the agent
+ *   - the new cumulative-cap state
+ *   - the audit outcome (`ok` | `extract_cap_exceeded`)
+ *   - the number of accepted characters (audit telemetry)
+ *
+ * The single output composer pulls together three concerns that all
+ * matter for safety: per-call clamp, cumulative cap (§14.6), and
+ * secret-shape redaction (`redactSecretShapes`). Keeping the
+ * composition pure lets the test suite drive every combination
+ * without booting a Playwright page.
+ *
+ * 100% coverage gate.
+ */
+import { type ExtractCapState } from "./extract-cap.js";
+export interface BuildExtractOutputInput {
+    /** Raw extractor output — never wrapped, never redacted. */
+    rawText: string;
+    /** Per-call cap. The composer clamps `rawText.length` to this BEFORE
+     *  consulting the cumulative cap. Default 8 KB per §5. */
+    maxChars?: number;
+    /** Per-task cumulative-cap state. The composer returns the updated
+     *  state for the runner to thread back into the task. */
+    capState: ExtractCapState;
+    /** Origin URL — embedded in the `<external-content>` attribute so
+     *  the agent (and a future auditor) can trace odd content back to a
+     *  page. */
+    origin: string;
+}
+export interface BuildExtractOutputResult {
+    /** Wrapped output the tool body returns. */
+    content: string;
+    /** Updated cumulative-cap state. */
+    capState: ExtractCapState;
+    /** Number of characters of real content accepted (excluding the
+     *  wrapper bytes and the cap-exceeded sentinel). */
+    acceptedChars: number;
+    /** Audit outcome for the action-log row. */
+    outcome: "ok" | "extract_cap_exceeded";
+}
+/**
+ * Apply the per-call clamp → cumulative-cap → secret-redaction →
+ * wrap pipeline. Order matters:
+ *
+ *   1. Per-call clamp first — the cumulative-cap counter must reflect
+ *      what we'd ACTUALLY return, not the upstream raw length.
+ *   2. Cumulative cap second — when the per-task counter is saturated,
+ *      we return the sentinel verbatim (no further redaction needed).
+ *   3. Secret redaction third — applied to the clamped slice before
+ *      wrapping so leaked tokens never reach the agent.
+ *   4. `<external-content>` wrap last — the runner is the only writer
+ *      of this tag and the agent's system prompt treats the body as
+ *      data.
+ */
+export declare function buildExtractOutput(input: BuildExtractOutputInput): BuildExtractOutputResult;

package/dist/services/browser-history/automation/browser-task-tools/extract-output.js

@@ -0,0 +1,69 @@
+/**
+ * Pure output builder for the `extract` tool —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.6.
+ *
+ * Given:
+ *   - raw page text (extractor output BEFORE per-call clamp)
+ *   - per-call `maxChars` clamp
+ *   - per-task cumulative cap state
+ *   - origin URL
+ *
+ * Produce:
+ *   - the `<external-content origin="…">…</external-content>` string
+ *     the runner returns to the agent
+ *   - the new cumulative-cap state
+ *   - the audit outcome (`ok` | `extract_cap_exceeded`)
+ *   - the number of accepted characters (audit telemetry)
+ *
+ * The single output composer pulls together three concerns that all
+ * matter for safety: per-call clamp, cumulative cap (§14.6), and
+ * secret-shape redaction (`redactSecretShapes`). Keeping the
+ * composition pure lets the test suite drive every combination
+ * without booting a Playwright page.
+ *
+ * 100% coverage gate.
+ */
+import { redactSecretShapes, renderExternalContentTag, } from "../external-content.js";
+import { decideExtractCap, EXTRACT_PER_CALL_DEFAULT_CHARS, } from "./extract-cap.js";
+/**
+ * Apply the per-call clamp → cumulative-cap → secret-redaction →
+ * wrap pipeline. Order matters:
+ *
+ *   1. Per-call clamp first — the cumulative-cap counter must reflect
+ *      what we'd ACTUALLY return, not the upstream raw length.
+ *   2. Cumulative cap second — when the per-task counter is saturated,
+ *      we return the sentinel verbatim (no further redaction needed).
+ *   3. Secret redaction third — applied to the clamped slice before
+ *      wrapping so leaked tokens never reach the agent.
+ *   4. `<external-content>` wrap last — the runner is the only writer
+ *      of this tag and the agent's system prompt treats the body as
+ *      data.
+ */
+export function buildExtractOutput(input) {
+    const perCallCap = input.maxChars ?? EXTRACT_PER_CALL_DEFAULT_CHARS;
+    const safeRaw = typeof input.rawText === "string" ? input.rawText : "";
+    const clamped = safeRaw.length > perCallCap ? safeRaw.slice(0, perCallCap) : safeRaw;
+    const decision = decideExtractCap(input.capState, clamped.length);
+    if (decision.kind === "cap_exceeded") {
+        return {
+            content: renderExternalContentTag(input.origin, decision.sentinel),
+            capState: decision.state,
+            acceptedChars: 0,
+            outcome: "extract_cap_exceeded",
+        };
+    }
+    // Real content path. Apply secret-shape redaction (best-effort
+    // defence in depth — §8.5.1) on the clamped slice before wrapping.
+    // If the cumulative cap accepts fewer chars than the clamp gave,
+    // truncate to the accepted budget.
+    const acceptedSlice = decision.acceptedChars < clamped.length
+        ? clamped.slice(0, decision.acceptedChars)
+        : clamped;
+    const redacted = redactSecretShapes(acceptedSlice);
+    return {
+        content: renderExternalContentTag(input.origin, redacted),
+        capState: decision.state,
+        acceptedChars: decision.acceptedChars,
+        outcome: "ok",
+    };
+}

package/dist/services/browser-history/automation/browser-task-tools/final-confirm-gate.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Final-confirm gate heuristic — BROWSER_TASK_REDESIGN_PLAN.md §5.
+ *
+ * Pure decision: given the description of a click / press_key target,
+ * does the runner need to interpose a `!~xxxxxxxx` lite-final-confirm
+ * round-trip before the activation materialises?
+ *
+ * The gate trips when `requireFinalConfirm === true` AND any of:
+ *
+ *   (a) The element is a `<button type="submit">` or
+ *       `<input type="submit">`.
+ *   (b) The element is inside a `<form>` AND the activation submits it
+ *       (button without explicit `type`, or `Enter` keypress in any
+ *        form field).
+ *   (c) The element's role is `button` AND its visible text or
+ *       `aria-label` matches an "irreversible action" vocabulary —
+ *       English + Japanese covered at minimum.
+ *
+ * Legs (a) and (b) are STRUCTURAL — they reflect what the browser
+ * would do without intervention. Leg (c) is HEURISTIC — site authors
+ * choose any label they want. We keep the regex narrow enough that a
+ * benign "Sign in" / "Confirm phone number" sequence does not pop a
+ * token on every step, while still catching "Post", "Submit", "Buy",
+ * "Confirm", "Publish" and their JP counterparts.
+ *
+ * The shape the runner passes is a `FinalConfirmGateInput` — pure JSON,
+ * built by the tool body from a Playwright `ElementHandle` snapshot.
+ * Keeping the decision pure means the I/O-bound tool implementations
+ * can stay thin and the gate's regex / form-submit logic earns 100%
+ * coverage in a peer test.
+ *
+ * Per the plan §14.10 "Hardcoded button-text denylist for every click
+ * was REJECTED" — we deliberately scope leg (c) to vocabulary that
+ * implies a commit / publish / send. A button labelled "Sign in" or
+ * "Continue" passes the gate freely.
+ */
+/**
+ * Input shape consumed by `decideFinalConfirmGate`. The runner builds
+ * this from the live element snapshot; the gate decision is a pure
+ * function of the snapshot.
+ */
+export interface FinalConfirmGateInput {
+    /** Source of the activation — distinguishes "click" from "Enter
+     *  press" semantics so the runner can apply the form-Enter rule
+     *  only to keyboard input. */
+    trigger: "click" | "press_key";
+    /** For `press_key`: the literal key name. Only "Enter" trips the
+     *  form-submit rule. */
+    key?: string;
+    /** Tag name of the focused element (`button`, `input`, `a`,
+     *  `textarea`, …). Lower-case is assumed. */
+    tagName: string;
+    /** ARIA role of the focused element. `null` when none declared. */
+    role: string | null;
+    /** `type` attribute for buttons / inputs (`submit`, `button`,
+     *  `reset`, `text`, `checkbox`, …). `null` when unset. */
+    type: string | null;
+    /** True when the element is inside a `<form>` ancestor. Drives the
+     *  form-submit detection. */
+    insideForm: boolean;
+    /** Visible text content of the element, normalised (trimmed,
+     *  collapsed whitespace). Used by leg (c). */
+    visibleText: string;
+    /** `aria-label` attribute value, normalised. Used by leg (c). */
+    ariaLabel: string | null;
+}
+export type FinalConfirmGateDecision = {
+    trip: false;
+} | {
+    trip: true;
+    /** Which leg fired — surfaced in the audit row so dashboards can
+     *  show "structural submit" vs. "label heuristic" without
+     *  guessing. */
+    reason: "submit_button" | "form_submit_enter" | "form_submit_click" | "action_vocab";
+    /** Normalised text/label that matched leg (c), or the activation
+     *  description for legs (a) / (b). Surfaced in the DM body. */
+    matched: string;
+};
+/**
+ * English-only "irreversible action" vocabulary. The gate is otherwise
+ * locale-blind — the rest of the heuristic (form submit detection,
+ * role=button + insideForm tightening) handles non-English UIs through
+ * structural shape, not button text.
+ *
+ * Tests pin the exact pattern source so a future widening cannot silently
+ * break a fixture.
+ *
+ * Vocab selection rationale (resolves F12 from the Phase 2 review):
+ *
+ *   - **Spec baseline (§5):** `post|submit|send|buy|confirm|publish` +
+ *     `reserve|book`. These are the irreversible commit actions the
+ *     original design pinned. `reserve` and `book` cover the booking-
+ *     flow surface (travel / restaurant / appointment) that would
+ *     otherwise rely on `confirm`.
+ *   - **Added — destructive-by-name (low false-positive):** `delete`.
+ *     Deleting a post / account / record is irreversible and the word
+ *     almost never appears on benign UI controls in a non-destructive
+ *     sense; gating it costs one extra DM token on true destructive
+ *     flows but practically never on incidental clicks.
+ *   - **Added — narrow compound:** `cancel order`. Order-cancellation
+ *     UIs are destructive (no easy undo, may incur fees, may cancel a
+ *     ship-already-in-progress). The 2-word literal means "cancel
+ *     dialog" / "cancel filter" / standalone "cancel" do NOT trip —
+ *     only the specific irreversible action does.
+ *   - **Deliberately NOT added — `remove`:** UI buttons read "Remove
+ *     filter", "Remove from cart", "Remove tag" — all reversible.
+ *     Adding `remove` would fire the gate on every cart edit, which
+ *     §14.10's "Hardcoded button-text denylist for every click" trade-
+ *     off rejected for exactly this reason.
+ *   - **Deliberately NOT added — `place order`:** commit-money flow
+ *     blocked at the `payment-path-blocker.ts` layer (path regex on
+ *     `/checkout`, `/buy`, `/place-order`). The gate is redundant with
+ *     the structural block and would fire on the legitimate cart-view
+ *     button (the actual checkout URL is the one denied, not the click).
+ *
+ * Non-English UIs: covered by the structural legs (a) submit-button
+ * tag-shape and (b) Enter-in-form-field — both of which fire regardless
+ * of the visible label. Adding locale-specific vocabulary back into the
+ * regex requires the same "low false-positive on benign UI" judgment
+ * applied above. Prior revisions enumerated Japanese verbs here; the
+ * 2026-05-27 revision removed them so the framework no longer bakes
+ * any single non-English locale's vocabulary into the safety floor
+ * (`feedback_no_jp_special_no_hardcoded_domains`).
+ */
+export declare const ACTION_VOCAB_REGEX: RegExp;
+/** Pure gate decision. Returns `{trip:false}` when no rule fires;
+ *  otherwise the structured trip reason + the matched fragment for
+ *  audit / DM body. */
+export declare function decideFinalConfirmGate(input: FinalConfirmGateInput): FinalConfirmGateDecision;

package/dist/services/browser-history/automation/browser-task-tools/final-confirm-gate.js

@@ -0,0 +1,150 @@
+/**
+ * Final-confirm gate heuristic — BROWSER_TASK_REDESIGN_PLAN.md §5.
+ *
+ * Pure decision: given the description of a click / press_key target,
+ * does the runner need to interpose a `!~xxxxxxxx` lite-final-confirm
+ * round-trip before the activation materialises?
+ *
+ * The gate trips when `requireFinalConfirm === true` AND any of:
+ *
+ *   (a) The element is a `<button type="submit">` or
+ *       `<input type="submit">`.
+ *   (b) The element is inside a `<form>` AND the activation submits it
+ *       (button without explicit `type`, or `Enter` keypress in any
+ *        form field).
+ *   (c) The element's role is `button` AND its visible text or
+ *       `aria-label` matches an "irreversible action" vocabulary —
+ *       English + Japanese covered at minimum.
+ *
+ * Legs (a) and (b) are STRUCTURAL — they reflect what the browser
+ * would do without intervention. Leg (c) is HEURISTIC — site authors
+ * choose any label they want. We keep the regex narrow enough that a
+ * benign "Sign in" / "Confirm phone number" sequence does not pop a
+ * token on every step, while still catching "Post", "Submit", "Buy",
+ * "Confirm", "Publish" and their JP counterparts.
+ *
+ * The shape the runner passes is a `FinalConfirmGateInput` — pure JSON,
+ * built by the tool body from a Playwright `ElementHandle` snapshot.
+ * Keeping the decision pure means the I/O-bound tool implementations
+ * can stay thin and the gate's regex / form-submit logic earns 100%
+ * coverage in a peer test.
+ *
+ * Per the plan §14.10 "Hardcoded button-text denylist for every click
+ * was REJECTED" — we deliberately scope leg (c) to vocabulary that
+ * implies a commit / publish / send. A button labelled "Sign in" or
+ * "Continue" passes the gate freely.
+ */
+/**
+ * English-only "irreversible action" vocabulary. The gate is otherwise
+ * locale-blind — the rest of the heuristic (form submit detection,
+ * role=button + insideForm tightening) handles non-English UIs through
+ * structural shape, not button text.
+ *
+ * Tests pin the exact pattern source so a future widening cannot silently
+ * break a fixture.
+ *
+ * Vocab selection rationale (resolves F12 from the Phase 2 review):
+ *
+ *   - **Spec baseline (§5):** `post|submit|send|buy|confirm|publish` +
+ *     `reserve|book`. These are the irreversible commit actions the
+ *     original design pinned. `reserve` and `book` cover the booking-
+ *     flow surface (travel / restaurant / appointment) that would
+ *     otherwise rely on `confirm`.
+ *   - **Added — destructive-by-name (low false-positive):** `delete`.
+ *     Deleting a post / account / record is irreversible and the word
+ *     almost never appears on benign UI controls in a non-destructive
+ *     sense; gating it costs one extra DM token on true destructive
+ *     flows but practically never on incidental clicks.
+ *   - **Added — narrow compound:** `cancel order`. Order-cancellation
+ *     UIs are destructive (no easy undo, may incur fees, may cancel a
+ *     ship-already-in-progress). The 2-word literal means "cancel
+ *     dialog" / "cancel filter" / standalone "cancel" do NOT trip —
+ *     only the specific irreversible action does.
+ *   - **Deliberately NOT added — `remove`:** UI buttons read "Remove
+ *     filter", "Remove from cart", "Remove tag" — all reversible.
+ *     Adding `remove` would fire the gate on every cart edit, which
+ *     §14.10's "Hardcoded button-text denylist for every click" trade-
+ *     off rejected for exactly this reason.
+ *   - **Deliberately NOT added — `place order`:** commit-money flow
+ *     blocked at the `payment-path-blocker.ts` layer (path regex on
+ *     `/checkout`, `/buy`, `/place-order`). The gate is redundant with
+ *     the structural block and would fire on the legitimate cart-view
+ *     button (the actual checkout URL is the one denied, not the click).
+ *
+ * Non-English UIs: covered by the structural legs (a) submit-button
+ * tag-shape and (b) Enter-in-form-field — both of which fire regardless
+ * of the visible label. Adding locale-specific vocabulary back into the
+ * regex requires the same "low false-positive on benign UI" judgment
+ * applied above. Prior revisions enumerated Japanese verbs here; the
+ * 2026-05-27 revision removed them so the framework no longer bakes
+ * any single non-English locale's vocabulary into the safety floor
+ * (`feedback_no_jp_special_no_hardcoded_domains`).
+ */
+export const ACTION_VOCAB_REGEX = /post|submit|send|buy|reserve|book|confirm|publish|delete|cancel order/i;
+/** Tag names whose default activation submits an enclosing form when
+ *  `type` is unset / `type='submit'`. Lower-case is assumed. */
+const FORM_SUBMITTING_TAGS = new Set(["button"]);
+/** Pure gate decision. Returns `{trip:false}` when no rule fires;
+ *  otherwise the structured trip reason + the matched fragment for
+ *  audit / DM body. */
+export function decideFinalConfirmGate(input) {
+    // Leg (a): structural submit. <button type="submit"> or <input type="submit">.
+    if ((input.tagName === "button" || input.tagName === "input")
+        && input.type === "submit") {
+        return {
+            trip: true,
+            reason: "submit_button",
+            matched: deriveLabelForAudit(input) || "<submit>",
+        };
+    }
+    // Leg (b1): Enter inside a form. Any form field would submit on Enter
+    // unless the page swallows the event — fail closed.
+    if (input.trigger === "press_key"
+        && (input.key ?? "").toLowerCase() === "enter"
+        && input.insideForm) {
+        return {
+            trip: true,
+            reason: "form_submit_enter",
+            matched: deriveLabelForAudit(input) || "<form Enter>",
+        };
+    }
+    // Leg (b2): click on a <button> with no explicit type inside a form
+    // (HTML default is type="submit"). `type="button"` opts out.
+    if (input.trigger === "click"
+        && FORM_SUBMITTING_TAGS.has(input.tagName)
+        && input.insideForm
+        && (input.type === null || input.type === "submit")) {
+        return {
+            trip: true,
+            reason: "form_submit_click",
+            matched: deriveLabelForAudit(input) || "<form button>",
+        };
+    }
+    // Leg (c): role-button with action-vocab visible text or aria-label.
+    // Active for both click and press_key — Space/Enter on a role=button
+    // commits the same way a click does.
+    const looksLikeButton = input.role === "button"
+        || input.tagName === "button"
+        || (input.tagName === "a" && input.role === "button");
+    if (looksLikeButton) {
+        const text = (input.visibleText || "").trim();
+        const aria = (input.ariaLabel || "").trim();
+        const haystack = aria.length > 0 ? `${text} ${aria}` : text;
+        if (haystack.length > 0 && ACTION_VOCAB_REGEX.test(haystack)) {
+            return {
+                trip: true,
+                reason: "action_vocab",
+                matched: (aria.length > 0 ? aria : text).slice(0, 80),
+            };
+        }
+    }
+    return { trip: false };
+}
+/** Surface a short label for the audit row / DM body. Prefers
+ *  aria-label, falls back to visible text, finally to empty. */
+function deriveLabelForAudit(input) {
+    if (input.ariaLabel && input.ariaLabel.trim().length > 0) {
+        return input.ariaLabel.trim().slice(0, 80);
+    }
+    return (input.visibleText || "").trim().slice(0, 80);
+}