@reticlehq/server 2.14.0 → 3.2.0

package/dist/features/visual/visual-tools.js

@@ -0,0 +1,352 @@
+import { z } from 'zod';
+import { AppRuntime, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { ratioSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { asNumber, asRecord, asString } from '@reticlehq/core';
+import { diffPng } from './visual-diff.js';
+import { VisualStore } from './visual-store.js';
+/**
+ * The `.reticle` a capture belongs beside: the driven session's own, stamped when it connected.
+ *
+ * Falls back to the daemon's root only when there is no session to ask — the same fallback the
+ * journal and the run artifact use, and for the same reason: a picture of somebody's app has no
+ * business in a directory that has nothing to do with it.
+ */
+function captureRoot(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).artifactRoot ?? deps.reticleRoot;
+    }
+    catch {
+        return deps.reticleRoot;
+    }
+}
+import { trackCaptureDirectory } from './capture-cleanup.js';
+import { readFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname } from 'node:path';
+const rectShape = z.object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number(),
+    height: z.number(),
+});
+function screenshotProvider(deps) {
+    const p = deps.realInput;
+    return p !== undefined && 'function' === typeof p.screenshot
+        ? p
+        : undefined;
+}
+/** The "you need a driven browser" envelope, shared by both visual tools. */
+const noProvider = {
+    ok: false,
+    reason: VisualReason.NO_PROVIDER,
+    recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
+};
+function asBox(value) {
+    const b = asRecord(asRecord(value)['box']);
+    const x = asNumber(b['x']);
+    const y = asNumber(b['y']);
+    const w = asNumber(b['width']);
+    const h = asNumber(b['height']);
+    if (x === undefined || y === undefined || w === undefined || h === undefined)
+        return undefined;
+    if (w <= 0 || h <= 0)
+        return undefined;
+    return { x, y, width: w, height: h };
+}
+/** Build capture options from args: explicit clip > ref (resolved via INSPECT) > fullPage. */
+async function buildOpts(deps, sessionId, args) {
+    const clipArg = args['clip'];
+    if (clipArg !== undefined) {
+        const c = asRecord(clipArg);
+        const box = asBox({ box: c });
+        if (box !== undefined)
+            return { clip: box };
+    }
+    const ref = asString(args['ref']);
+    if (ref !== undefined) {
+        const session = deps.sessions.resolve(sessionId);
+        const res = await session.command(ReticleCommand.INSPECT, { ref });
+        const box = res.ok ? asBox(res.result) : undefined;
+        if (box !== undefined)
+            return { clip: box };
+    }
+    return true === args['fullPage'] ? { fullPage: true } : {};
+}
+/**
+ * Ask the desktop shell to photograph its own window.
+ *
+ * Returns undefined for a plain web page (no capture helper) and for a desktop app that did not
+ * install `@reticlehq/electron/main`. Deliberately NOT a screen-region capture: photographing
+ * the glass returns whatever window is on top, which would save a picture of the user's editor as a
+ * visual baseline — the exact false green Reticle exists to eliminate.
+ */
+async function desktopCapture(deps, sessionId, fullPage) {
+    const session = deps.sessions.resolve(sessionId);
+    // A session that cannot take commands (no live browser behind it) simply has no pixels to give.
+    if (typeof session.command !== 'function')
+        return {};
+    const res = await session.command(ReticleCommand.CAPTURE, { fullPage });
+    if (!res.ok)
+        return {};
+    const r = asRecord(res.result);
+    if (r['ok'] !== true) {
+        // The shell refused a full-page capture it cannot do. That is a different answer from "capture
+        // broke", and the caller has to hear it — otherwise they read `fullPage` as honoured.
+        return r['reason'] === VisualReason.FULL_PAGE_UNSUPPORTED
+            ? { reason: VisualReason.FULL_PAGE_UNSUPPORTED }
+            : {};
+    }
+    const path = asString(r['path']);
+    if (path === undefined || !isCapturePath(path))
+        return {};
+    try {
+        const bytes = await readFile(path);
+        await unlink(path).catch(() => undefined);
+        trackCaptureDirectory(path);
+        return isCompletePng(bytes) ? { png: new Uint8Array(bytes) } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export function isCapturePath(path) {
+    if (!basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX))
+        return false;
+    const parent = dirname(path);
+    if (parent === tmpdir())
+        return true;
+    return dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
+}
+/**
+ * A PNG is complete only if it ends with IEND. This check exists because a truncated image once
+ * sailed through as a saved baseline: the tool answered `saved: true` with a path, and the file was
+ * undecodable. A screenshot that cannot be read must fail loudly, never bank a corrupt baseline that
+ * a later visual_diff will compare against.
+ */
+function isCompletePng(bytes) {
+    if (bytes.byteLength < 12)
+        return false;
+    return 'IEND' === bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii');
+}
+/**
+ * Which runtime this session is, for scoping a visual artifact.
+ *
+ * Undefined when the session cannot be resolved or its SDK never reported one — and undefined means
+ * the flat legacy path, so a baseline captured before any of this keeps matching.
+ */
+function runtimeOf(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).runtime;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get pixels for a session, by whichever route exists.
+ *
+ * A driven/attached browser is captured through CDP — exact, and the only route that can do
+ * `fullPage`. A desktop app has no CDP endpoint, so its own shell is asked instead. CDP is tried
+ * FIRST and the desktop path is a genuine fallback, not an either/or: with a CDP endpoint attached
+ * to one app and the screenshot aimed at a different (desktop) session, CDP fails and the shell
+ * capture is still correct.
+ *
+ * `clip`/`ref` are honoured only on the CDP path — the shell photographs the whole window. Scoping is
+ * left to the caller rather than cropped here, so a clip never silently becomes a full-window image.
+ *
+ * `fullPage` is different, because it cannot be emulated by cropping: only WebKitGTK (Tauri on Linux)
+ * can render a full document offscreen. Where the shell cannot, it REFUSES and this reports
+ * `full-page-unsupported` — a viewport image returned as though it were the whole scroll height is a
+ * baseline that says nothing about the content below the fold, and a later diff would call it green.
+ */
+async function capture(deps, sessionId, args) {
+    const provider = screenshotProvider(deps);
+    if (provider !== undefined) {
+        const session = deps.sessions.resolve(sessionId);
+        const png = await provider.screenshot(session.url, await buildOpts(deps, sessionId, args));
+        // A driven browser renders the session's URL in a BROWSER — so the pixels are web even when the
+        // session named is a desktop window. Scoping those under the desktop runtime would corrupt that
+        // runtime's baseline with a picture of a different renderer.
+        if (png !== undefined)
+            return { png, runtime: AppRuntime.WEB };
+    }
+    // The window's own backing store, via the Electron/Tauri adapter — the only route whose pixels
+    // really are the desktop app.
+    const desktop = await desktopCapture(deps, sessionId, true === args['fullPage']);
+    if (desktop.png !== undefined)
+        return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
+    if (desktop.reason !== undefined)
+        return { reason: desktop.reason };
+    /*
+     * A LEASED page is a real browser page, so the pixels were always there — the visual tools simply
+     * had no route to them. Without this, `reticle_screenshot` answered "no provider" for every context
+     * an agent can actually acquire, which made visual regression impossible on exactly the isolated
+     * contexts the pool exists to hand out. Tried last: a CDP provider, when there is one, is driving
+     * the page the caller means, and a lease is the fallback rather than a competitor.
+     */
+    const leased = sessionId === undefined
+        ? undefined
+        : await deps.pool?.screenshotLease(sessionId, { fullPage: true === args['fullPage'] });
+    // A leased page is a real browser page, whatever the session is.
+    if (leased !== undefined)
+        return { png: leased, runtime: AppRuntime.WEB };
+    return {
+        reason: provider === undefined ? VisualReason.NO_PROVIDER : VisualReason.CAPTURE_FAILED,
+    };
+}
+function rectsFrom(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const rects = [];
+    for (const r of value) {
+        const box = asBox({ box: r });
+        if (box !== undefined)
+            rects.push(box);
+    }
+    return rects.length > 0 ? rects : undefined;
+}
+/**
+ * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
+ * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER
+ * envelope (with a recommendation) instead of throwing when none is attached. Behavioral checks
+ * stay the default; this is the complementary "does it look right" surface, never bundled in.
+ */
+export const VISUAL_TOOLS = [
+    {
+        name: ReticleTool.SCREENSHOT,
+        example: { name: 'home' },
+        description: 'Capture a pixel screenshot of the DRIVEN page (needs `reticle drive`/RETICLE_CDP_URL — the SDK has no screenshotter) and save it as a visual baseline at .reticle/visual/<name>.png. { fullPage } for the whole scroll height, { ref } or { clip:{x,y,width,height} } for one element/region. Returns { saved:true, name, path, bytes } or { ok:false, reason } when no driven browser is attached.',
+        inputSchema: {
+            name: z
+                .string()
+                .describe('Baseline name — saved as .reticle/visual/<name>.png. Use the same name in reticle_visual_diff to compare.'),
+            fullPage: z
+                .boolean()
+                .optional()
+                .describe('Capture the full scroll height. Default: viewport only.'),
+            ref: z
+                .string()
+                .optional()
+                .describe('Element ref to screenshot (scopes to element bounding box). Omit for full page.'),
+            clip: rectShape
+                .optional()
+                .describe('Explicit { x, y, width, height } clip rectangle in page coordinates.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            saved: z.boolean().optional(),
+            name: z.string().optional(),
+            path: z.string().optional(),
+            bytes: z.number().optional(),
+            reason: z.string().optional(),
+            recommendation: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const sessionId = asString(args['sessionId']);
+            const { png, reason, runtime } = await capture(deps, sessionId, args);
+            if (png === undefined) {
+                return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
+            }
+            const name = asString(args['name']) ?? 'default';
+            // Beside the app that was captured. The tool RETURNS this path to the agent, so a wrong root
+            // is not only a stray PNG — it is a path the agent is told to look at in a tree that has
+            // nothing to do with the screenshot.
+            //
+            // Taken from the SESSION's own stamp rather than re-resolved, which is what `attach-journal`
+            // and the run artifact already do: the capture came from that session, so the answer is
+            // already in hand, and a second resolution is a second chance to disagree. It also keeps this
+            // directory from reaching into `project` for an address it was deliberately freed from
+            // needing — see `directory-reach`.
+            const store = new VisualStore(deps.fs, captureRoot(deps, sessionId));
+            // Scoped to the runtime that produced it: an Electron window, a Tauri webview and a browser
+            // tab do not render the same url the same way, and one shared baseline makes every
+            // cross-runtime diff wrong. See visualDir.
+            const path = await store.saveBaseline(name, png, runtime);
+            return { ok: true, saved: true, name, path, bytes: png.length };
+        },
+    },
+    {
+        name: ReticleTool.VISUAL_DIFF,
+        example: { baseline: 'home' },
+        description: 'Perceptually diff the DRIVEN page against a saved visual baseline (see reticle_screenshot). { masks:[{x,y,width,height}] } neutralizes volatile regions; { maxRatio } sets the pass tolerance (default 0). Returns { matched, changedPixels, totalPixels, ratio, region?, diffPath, dimensionMismatch } — the overlay diff is written to .reticle/visual/<baseline>.diff.png — or { ok:false, reason } (no-provider / baseline-missing).',
+        inputSchema: {
+            baseline: z
+                .string()
+                .describe('Baseline screenshot name (from reticle_screenshot). Used to compare with the current screenshot.'),
+            fullPage: z.boolean().optional(),
+            ref: z.string().optional(),
+            clip: rectShape.optional(),
+            masks: z.array(rectShape).optional(),
+            maxRatio: ratioSchema.optional(),
+            threshold: ratioSchema
+                .optional()
+                .describe('Pixel difference threshold (0–1). Default: 0.01.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            matched: z.boolean().optional(),
+            changedPixels: z.number().optional(),
+            totalPixels: z.number().optional(),
+            ratio: z.number().optional(),
+            region: rectShape.optional(),
+            dimensionMismatch: z.boolean().optional(),
+            diffPath: z.string().optional(),
+            reason: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const baseline = asString(args['baseline']) ?? '';
+            const store = new VisualStore(deps.fs, captureRoot(deps, asString(args['sessionId'])));
+            // Capture FIRST, then fetch the baseline for the runtime that produced these pixels. Reading it
+            // by the session's runtime looked equivalent and is not: the route decides the renderer, so a
+            // desktop session captured through a driven browser must be compared against the WEB baseline,
+            // not the desktop one. Comparing across renderers is a confident wrong diff in one direction
+            // and a silently overwritten baseline in the other.
+            const sessionId = asString(args['sessionId']);
+            const { png: current, reason, runtime } = await capture(deps, sessionId, args);
+            if (current === undefined) {
+                return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
+            }
+            // A baseline from another runtime is not missing by accident — it is a different rendering, and
+            // "no baseline for this one" is the honest answer.
+            const baselineBytes = await store.readBaseline(baseline, runtime);
+            if (baselineBytes === undefined)
+                return { ok: false, reason: VisualReason.BASELINE_MISSING };
+            const masks = rectsFrom(args['masks']);
+            const threshold = asNumber(args['threshold']);
+            const maxRatio = asNumber(args['maxRatio']);
+            const result = await diffPng(baselineBytes, current, {
+                ...(threshold !== undefined ? { threshold } : {}),
+                ...(maxRatio !== undefined ? { maxRatio } : {}),
+                ...(masks !== undefined ? { masks } : {}),
+            });
+            // Omit the raw diff bytes from the JSON result; persist them and return the path instead.
+            const { diffPng: diffBytes, ...verdict } = result;
+            if (diffBytes === undefined) {
+                return { ok: false, ...verdict, reason: VisualReason.DIMENSION_MISMATCH };
+            }
+            const diffPath = await store.saveDiff(baseline, diffBytes, runtime);
+            return { ok: true, ...verdict, diffPath };
+        },
+    },
+];

package/dist/hooks/hook-bus.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One place Reticle says what happened, and everything that wants to know listens here.
+ *
+ * Two surfaces sit on this and neither is the mechanism: `onReticleEvent` hands the payload to code
+ * running in this process, and the command runner spawns whatever `.reticle/hooks.json` names. They
+ * are adapters.
+ *
+ * ── THE ONE RULE ────────────────────────────────────────────────────────────────────────────────
+ * A HOOK MUST NEVER BREAK OR SLOW A VERIFICATION. The verdict is the product; a user's notification
+ * script is not, and a product where adding a Slack webhook can turn a passing check into a failing
+ * one is a product where the honest advice is to not use hooks. So `emit` is synchronous, returns
+ * `void`, awaits nothing, and cannot throw: a subscriber that throws is caught, a subscriber that
+ * hangs is left hanging, and the caller has already moved on either way.
+ *
+ * This is the same discipline the sync daemon states for itself — "nothing here is awaited by a tool
+ * call" — and for the same reason.
+ *
+ * ── WHY A MODULE-LEVEL BUS ──────────────────────────────────────────────────────────────────────
+ * Deliberately process-global, unlike the snapshot cache which was just moved off module scope for
+ * being shared when it should have been per-client. The opposite is true here: a hook is a property
+ * of THE MACHINE's configuration, not of whichever agent happens to be connected, and a user who
+ * writes `bug_found` in their repo means "when Reticle finds a bug", not "when the third MCP client
+ * to attach finds a bug". Scoping this per connection would silently drop events for a repo whose
+ * daemon was started by someone else.
+ */
+import { type HookEventName, type HookPayload } from '@reticlehq/core/hooks';
+/** What a listener is handed. Never awaited — see the rule above. */
+export type HookListener = (payload: HookPayload) => void;
+/**
+ * Listen for one event, or for every event when `event` is omitted.
+ *
+ * Returns the unsubscribe function rather than taking an `off(event, fn)` pair, because the pair
+ * requires the caller to keep the identical function reference and silently does nothing when they
+ * do not — a leak that looks exactly like working code.
+ */
+export declare function onHook(event: HookEventName | undefined, listener: HookListener): () => void;
+/**
+ * Say that something happened.
+ *
+ * VALIDATED before delivery, and that is not ceremony: the payload is built from internal objects at
+ * each call site, and parsing it here is what stops a field nobody meant to publish from reaching a
+ * consumer. zod strips unknown keys, so a caller that spreads a wider internal record into a payload
+ * gets only the declared fields out — which is the mechanism the secret-shape guard in core relies
+ * on rather than trusting every future call site to be careful.
+ *
+ * An INVALID payload is dropped and reported once. Throwing would push a bug in our own event
+ * construction into the caller's verdict path, which is the one thing this file promises not to do.
+ */
+export declare function emitHook(payload: HookPayload): void;
+/** How many listeners an event has. For the daemon's own status output, and for tests. */
+export declare function hookListenerCount(event: HookEventName): number;
+/** Drop every listener. Tests, and a daemon tearing down its own wiring. */
+export declare function resetHooks(): void;

package/dist/hooks/hook-bus.js

@@ -0,0 +1,106 @@
+/**
+ * One place Reticle says what happened, and everything that wants to know listens here.
+ *
+ * Two surfaces sit on this and neither is the mechanism: `onReticleEvent` hands the payload to code
+ * running in this process, and the command runner spawns whatever `.reticle/hooks.json` names. They
+ * are adapters.
+ *
+ * ── THE ONE RULE ────────────────────────────────────────────────────────────────────────────────
+ * A HOOK MUST NEVER BREAK OR SLOW A VERIFICATION. The verdict is the product; a user's notification
+ * script is not, and a product where adding a Slack webhook can turn a passing check into a failing
+ * one is a product where the honest advice is to not use hooks. So `emit` is synchronous, returns
+ * `void`, awaits nothing, and cannot throw: a subscriber that throws is caught, a subscriber that
+ * hangs is left hanging, and the caller has already moved on either way.
+ *
+ * This is the same discipline the sync daemon states for itself — "nothing here is awaited by a tool
+ * call" — and for the same reason.
+ *
+ * ── WHY A MODULE-LEVEL BUS ──────────────────────────────────────────────────────────────────────
+ * Deliberately process-global, unlike the snapshot cache which was just moved off module scope for
+ * being shared when it should have been per-client. The opposite is true here: a hook is a property
+ * of THE MACHINE's configuration, not of whichever agent happens to be connected, and a user who
+ * writes `bug_found` in their repo means "when Reticle finds a bug", not "when the third MCP client
+ * to attach finds a bug". Scoping this per connection would silently drop events for a repo whose
+ * daemon was started by someone else.
+ */
+import { HookPayloadSchema } from '@reticlehq/core/hooks';
+import { log } from '../log.js';
+/** Listeners by event, plus the ones that asked for everything. */
+const listeners = new Map();
+const everyEvent = new Set();
+/**
+ * Errors already reported, so a broken hook says so once instead of once per verdict.
+ *
+ * A laptop with a typo in `hooks.json` would otherwise write the same line a few hundred times in a
+ * morning and teach its owner to ignore the log — the failure mode the sync daemon calls out by
+ * name, arrived at independently here because the shape of the problem is identical.
+ */
+const reported = new Set();
+function reportOnce(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const key = `${context}:${message}`;
+    if (reported.has(key))
+        return;
+    reported.add(key);
+    log(`hook failed (${context}): ${message}`);
+}
+/**
+ * Listen for one event, or for every event when `event` is omitted.
+ *
+ * Returns the unsubscribe function rather than taking an `off(event, fn)` pair, because the pair
+ * requires the caller to keep the identical function reference and silently does nothing when they
+ * do not — a leak that looks exactly like working code.
+ */
+export function onHook(event, listener) {
+    if (event === undefined) {
+        everyEvent.add(listener);
+        return () => {
+            everyEvent.delete(listener);
+        };
+    }
+    const set = listeners.get(event) ?? new Set();
+    set.add(listener);
+    listeners.set(event, set);
+    return () => {
+        set.delete(listener);
+    };
+}
+/**
+ * Say that something happened.
+ *
+ * VALIDATED before delivery, and that is not ceremony: the payload is built from internal objects at
+ * each call site, and parsing it here is what stops a field nobody meant to publish from reaching a
+ * consumer. zod strips unknown keys, so a caller that spreads a wider internal record into a payload
+ * gets only the declared fields out — which is the mechanism the secret-shape guard in core relies
+ * on rather than trusting every future call site to be careful.
+ *
+ * An INVALID payload is dropped and reported once. Throwing would push a bug in our own event
+ * construction into the caller's verdict path, which is the one thing this file promises not to do.
+ */
+export function emitHook(payload) {
+    const parsed = HookPayloadSchema.safeParse(payload);
+    if (!parsed.success) {
+        reportOnce(`emit:${String(payload.event)}`, parsed.error.message);
+        return;
+    }
+    const safe = parsed.data;
+    const targets = [...(listeners.get(safe.event) ?? []), ...everyEvent];
+    for (const listener of targets) {
+        try {
+            listener(safe);
+        }
+        catch (error) {
+            reportOnce(`listener:${safe.event}`, error);
+        }
+    }
+}
+/** How many listeners an event has. For the daemon's own status output, and for tests. */
+export function hookListenerCount(event) {
+    return (listeners.get(event)?.size ?? 0) + everyEvent.size;
+}
+/** Drop every listener. Tests, and a daemon tearing down its own wiring. */
+export function resetHooks() {
+    listeners.clear();
+    everyEvent.clear();
+    reported.clear();
+}

package/dist/hooks/hook-commands.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The config surface: `.reticle/hooks.json` says what to run, this runs it.
+ *
+ * A subscriber on the bus like any other, which is the point — it has no privileges the in-process
+ * API does not have, and if this file were deleted the bus would carry on. That is what keeps the
+ * two surfaces honest about being adapters rather than two half-implementations of one idea.
+ *
+ * ── TRUST ───────────────────────────────────────────────────────────────────────────────────────
+ * The command is read from a file inside the user's own repository and run with a shell, which is
+ * exactly the trust level `package.json` scripts and git hooks already have there: cloning a repo
+ * runs nothing, and a command runs only when the event it is attached to actually happens.
+ *
+ * The payload NEVER touches the command line. It is written to the child's stdin as JSON, so a
+ * defect's own text — a page title, an assertion message, anything the app under test produced —
+ * cannot become part of a command. That is the one place a plausible injection could enter, and it
+ * is closed by construction rather than by escaping, because escaping is a thing you get wrong once.
+ *
+ * ── NEVER IN THE WAY ────────────────────────────────────────────────────────────────────────────
+ * Detached from the caller entirely: nothing awaits the child, a non-zero exit is reported and not
+ * raised, and a child that hangs is killed on a timeout rather than held. A user whose script is
+ * broken gets a log line; their verdicts keep working.
+ */
+import { type HookPayload } from '@reticlehq/core/hooks';
+/**
+ * Read `.reticle/hooks.json`, or nothing.
+ *
+ * Re-read when the file's mtime moves. A `stat` per event is nothing next to spawning a process,
+ * and the alternative — read once at startup — means a user editing their hooks has to know to
+ * restart a daemon they never started by hand.
+ */
+export declare function readHookConfig(reticleRoot: string): Record<string, string>;
+/** Run one command with the payload on stdin. Returns immediately; nothing here is awaited. */
+export declare function runHookCommand(command: string, payload: HookPayload, cwd: string): void;
+/**
+ * Attach the config surface to the bus.
+ *
+ * Subscribes once, for every event, and decides per payload — rather than reading the config now
+ * and subscribing to the events it names. Those differ the moment somebody edits the file: the
+ * eager version would keep running yesterday's hooks and ignore today's.
+ */
+export declare function installCommandHooks(reticleRoot: string): () => void;
+/**
+ * Wire BOTH halves of hooks for one entry point: the config surface, and the project id payloads
+ * carry.
+ *
+ * Exists because `start()` and `startDaemon()` each wire their own world, and a line added to one
+ * of them is not added to the other. `installCommandHooks` was in `startDaemon` alone, so
+ * `.reticle/hooks.json` did nothing under `reticle drive`, `reticle verify` and `reticle demo` —
+ * three commands that run a whole verification and emit every event a hook subscribes to. The
+ * in-process surface (`onHook`) worked on both, so the feature looked wired; only the
+ * file-configured half was dead, and it is the half a user who has not written code can reach.
+ *
+ * `initImpact` had already been fixed for exactly this, one line at a time, and the comment left
+ * beside it in `startDaemon` says so. One function is what stops the next one.
+ *
+ * Costs nothing when unused: with no `.reticle/hooks.json` the listener reads an absent file, gets
+ * an empty map and returns.
+ */
+export declare function wireHooks(reticleRoot: string, projectId: string | undefined): () => void;