@reticlehq/server 3.7.0 → 3.8.1

package/dist/features/harness/platform-config.d.ts

@@ -45,7 +45,7 @@ export interface PlatformModelConfig {
      */
     providerReady: boolean;
     /**
-     * Harness credits used and held this 30 days, and when the grant ends (`endsAt`, epoch ms) when
+     * Credits used and held this 30 days, and when the grant ends (`endsAt`, epoch ms) when
      * the platform says. Absent when the plan is unbounded or the API is older.
      */
     credits?: Credits & {
@@ -59,8 +59,6 @@ export interface PlatformModelConfig {
      * the API's origin 404s. Absent from an older platform.
      */
     planUrl?: string;
-    /** The platform's coverage gate (`harnessUnlocked`, `coverageScore`, `harnessLock`), when it sent one. */
-    gate?: PlatformGate;
     /** The plan in force (`plan`), for the HUD's account menu. */
     plan?: PlatformPlan;
     /** Harness runs the platform holds for this project (`harnessRuns.total`). */
@@ -74,13 +72,6 @@ export interface PlatformPlan {
     daysLeft?: number;
     seats?: number;
 }
-/** The platform's Harness coverage gate, as the HUD is pushed it. */
-export interface PlatformGate {
-    unlocked: boolean;
-    percent?: number;
-    reason?: string;
-    prompt?: string;
-}
 /** A GET, narrowed to what this file uses, so a test can answer it without a network. */
 export type ConfigFetch = (url: string, init: {
     method: string;

package/dist/features/harness/platform-config.js

@@ -66,24 +66,6 @@ function webUrl(value, key) {
         return {};
     }
 }
-/** The gate out of `/v1/model/config`, or undefined from a platform that does not send one. */
-function gateOf(record) {
-    const unlocked = record['harnessUnlocked'];
-    if ('boolean' !== typeof unlocked)
-        return undefined;
-    const score = record['coverageScore'];
-    const lock = record['harnessLock'];
-    const lockRecord = 'object' === typeof lock && null !== lock ? lock : {};
-    const reason = lockRecord['reason'];
-    const prompt = lockRecord['prompt'];
-    return {
-        unlocked,
-        // Rounded down, as core's rule is: a locked app never shows 80%.
-        ...('number' === typeof score ? { percent: Math.floor(score * 100 + 1e-9) } : {}),
-        ...('string' === typeof reason ? { reason } : {}),
-        ...('string' === typeof prompt ? { prompt } : {}),
-    };
-}
 /** When the grant ends, epoch ms, from an ISO date or a number. Anything else: not said. */
 function endsAtOf(value) {
     const at = 'number' === typeof value ? value : 'string' === typeof value ? Date.parse(value) : NaN;
@@ -121,7 +103,6 @@ function parse(body) {
         const kind = 'object' === typeof credits && null !== credits
             ? Object.values(CreditKind).find((k) => k === credits['kind'])
             : undefined;
-        const gate = gateOf(record);
         const endsAt = endsAtOf('object' === typeof credits && null !== credits
             ? credits['endsAt']
             : undefined);
@@ -130,7 +111,6 @@ function parse(body) {
             harnessEnabled: true === enabled,
             harnessEntitled: 'boolean' === typeof entitled ? entitled : true,
             providerReady: 'boolean' === typeof ready ? ready : true,
-            ...(gate === undefined ? {} : { gate }),
             ...hudFieldsOf(record),
             ...webUrl(record['planUrl'], 'planUrl'),
             ...('number' === typeof used && 'number' === typeof limit

package/dist/features/license/license.d.ts

@@ -37,20 +37,8 @@ declare const LicensePayloadSchema: z.ZodObject<{
     org: z.ZodString;
     plan: z.ZodString;
     exp: z.ZodNumber;
-    features: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    plan: string;
-    org: string;
-    lid: string;
-    exp: number;
-    features?: string[] | undefined;
-}, {
-    plan: string;
-    org: string;
-    lid: string;
-    exp: number;
-    features?: string[] | undefined;
-}>;
+    features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export type LicensePayload = z.infer<typeof LicensePayloadSchema>;
 type LicenseCheck = {
     status: typeof LicenseStatus.VALID;

package/dist/features/visual/step-shots.d.ts

@@ -4,10 +4,15 @@ export interface ShotOptions {
     step?: string;
     verdict?: boolean;
 }
-/** What a tool result carries: where the picture is and how it was taken, or why there is none. */
+/**
+ * What a tool result carries: where the picture is and how it was taken, or why there is none.
+ *
+ * `pending: true` means the path is reserved and the capture has started, but the file may not yet be on disk. This happens on the fast path when a prior capture on the same tab proved the source works: the step does not wait for the write to land. Copy the file only after a short delay, or poll until it appears.
+ */
 export type ScreenshotField = {
     path: string;
     source: ScreenshotSource;
+    pending?: true;
 } | {
     error: string;
 };
@@ -29,3 +34,30 @@ export declare function jpegSize(bytes: Uint8Array): {
 export declare function takeStepShot(deps: ToolDeps, sessionId: string, tool: string, opts?: ShotOptions): Promise<ScreenshotField>;
 /** The replay hook that gives every reported flow step its screenshot, filed as `<flow>#<step>`. */
 export declare function replayStepShooter(deps: ToolDeps, sessionId: string): (result: FlowStepResult, flow: string) => Promise<void>;
+/**
+ * Frames: the pictures between the steps.
+ *
+ * A run had one picture per step, so the cloud replay jumped from step to step and showed nothing of
+ * what happened between them. A tab that Reticle drives (a leased tab, or the page `reticle drive`
+ * opened) is filmed about once a second into the run of its last step. The frames go in the same
+ * directory and record as the step shots, with the tool `frame`, so the existing upload sends them
+ * and the replay plays them in `seq` order.
+ *
+ * Bounded twice. A page that did not change is not filmed again. A run keeps at most
+ * `FRAME.MAX_PER_RUN` frames, and the gap between frames doubles each quarter of that budget, so a
+ * long run is thinned, not cut off at its start. The step shots keep the rest of the per-run limit.
+ *
+ * ponytail: a desktop shell is not filmed (its capture is a PNG, see the header), and an undriven
+ * tab is not filmed (only the page could draw itself, once a second, in the user's own tab).
+ */
+export declare const FRAME: {
+    readonly TOOL: "frame";
+    readonly EVERY_MS: 1000;
+    readonly MAX_PER_RUN: 100;
+    /** CDP quality for a frame: lower than a step shot, as for the chat's live view. */
+    readonly JPEG_QUALITY: 50;
+};
+/** Stop filming a tab. Safe to call for a tab that is not filmed. */
+export declare function stopFilming(sessionId: string): void;
+/** One tick of a tab's film: one frame, when the budget, the gap and the page allow. Never throws. */
+export declare function filmNow(sessionId: string): Promise<void>;

package/dist/features/visual/step-shots.js

@@ -171,6 +171,7 @@ async function shoot(deps, session, tool, { step, verdict }) {
     if (!isValidRunId(runId))
         return { error: `no screenshot: unusable run id ${runId}` };
     const dir = stepShotDir(root, runId);
+    void filmTab(deps, session, dir);
     const seq = await allocate(deps.fs, dir);
     if (seq > STEP_SCREENSHOT.MAX_PER_RUN) {
         return {
@@ -215,7 +216,7 @@ async function shoot(deps, session, tool, { step, verdict }) {
     });
     noteLanding(dir, land);
     if (predicted !== undefined)
-        return { path, source: predicted };
+        return { path, source: predicted, pending: true };
     // Nothing worked last time: wait, and tell the truth either way.
     const pixels = await taken;
     await land;
@@ -229,3 +230,156 @@ export function replayStepShooter(deps, sessionId) {
         });
     };
 }
+/**
+ * Frames: the pictures between the steps.
+ *
+ * A run had one picture per step, so the cloud replay jumped from step to step and showed nothing of
+ * what happened between them. A tab that Reticle drives (a leased tab, or the page `reticle drive`
+ * opened) is filmed about once a second into the run of its last step. The frames go in the same
+ * directory and record as the step shots, with the tool `frame`, so the existing upload sends them
+ * and the replay plays them in `seq` order.
+ *
+ * Bounded twice. A page that did not change is not filmed again. A run keeps at most
+ * `FRAME.MAX_PER_RUN` frames, and the gap between frames doubles each quarter of that budget, so a
+ * long run is thinned, not cut off at its start. The step shots keep the rest of the per-run limit.
+ *
+ * ponytail: a desktop shell is not filmed (its capture is a PNG, see the header), and an undriven
+ * tab is not filmed (only the page could draw itself, once a second, in the user's own tab).
+ */
+export const FRAME = {
+    TOOL: STEP_SCREENSHOT.FRAME_TOOL,
+    EVERY_MS: 1_000,
+    MAX_PER_RUN: 100,
+    /** CDP quality for a frame: lower than a step shot, as for the chat's live view. */
+    JPEG_QUALITY: 50,
+};
+/** The quarters the budget is split into: the gap between frames doubles at each. */
+const FRAME_STAGES = 4;
+/**
+ * The frames a new one is compared with. A page that flips between a few looks (a blinking caret,
+ * a spinner) is unchanged, not a new frame every tick.
+ */
+const RECENT_FRAMES = 4;
+/** The longest wait, in ticks, between captures of a page that keeps looking the same. */
+const MAX_STILL_TICKS = 32;
+const films = new Map();
+/** Frames kept per run directory. */
+const framesIn = new Map();
+/** Is this a tab Reticle drives, with a real browser behind it? */
+async function driven(deps, session) {
+    if (true === deps.pool?.leasedSessionIds().includes(session.id))
+        return true;
+    return (deps.realInput?.screenshot !== undefined &&
+        true === (await deps.realInput.isAvailableFor(session.url)));
+}
+/** Start filming a driven tab, or point its film at the run its newest step went to. */
+async function filmTab(deps, session, dir) {
+    const film = films.get(session.id);
+    if (film !== undefined) {
+        film.dir = dir;
+        // A step usually changes the page: look again at the next tick.
+        film.still = 1;
+        return;
+    }
+    if (!(await driven(deps, session).catch(() => false)))
+        return;
+    if (films.has(session.id))
+        return;
+    const timer = setInterval(() => {
+        void filmNow(session.id);
+    }, FRAME.EVERY_MS);
+    // A film never holds a process open.
+    timer.unref?.();
+    films.set(session.id, { deps, dir, timer, busy: undefined, recent: [], idle: 0, still: 1 });
+}
+/** Stop filming a tab. Safe to call for a tab that is not filmed. */
+export function stopFilming(sessionId) {
+    const film = films.get(sessionId);
+    if (film === undefined)
+        return;
+    clearInterval(film.timer);
+    films.delete(sessionId);
+}
+/** One tick of a tab's film: one frame, when the budget, the gap and the page allow. Never throws. */
+export async function filmNow(sessionId) {
+    const film = films.get(sessionId);
+    if (film === undefined || film.busy !== undefined)
+        return;
+    film.busy = frame(sessionId, film).finally(() => {
+        film.busy = undefined;
+    });
+    await film.busy;
+}
+async function frame(sessionId, film) {
+    let session;
+    try {
+        session = film.deps.sessions.resolve(sessionId);
+        // An ended tab has nothing more to show.
+        if (session.isEnded())
+            session = undefined;
+    }
+    catch {
+        session = undefined;
+    }
+    if (session === undefined) {
+        stopFilming(sessionId);
+        return;
+    }
+    const dir = film.dir;
+    const kept = framesIn.get(dir) ?? 0;
+    if (kept >= FRAME.MAX_PER_RUN)
+        return;
+    film.idle += 1;
+    const gap = 2 ** Math.floor(kept / (FRAME.MAX_PER_RUN / FRAME_STAGES));
+    if (film.idle < Math.max(gap, film.still))
+        return;
+    film.idle = 0;
+    try {
+        const bytes = await framePixels(film.deps, session);
+        const size = bytes === undefined ? undefined : jpegSize(bytes);
+        if (bytes === undefined || size === undefined)
+            return;
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        if (film.recent.includes(sha256)) {
+            film.still = Math.min(film.still * 2, MAX_STILL_TICKS);
+            return;
+        }
+        film.recent = [...film.recent, sha256].slice(-RECENT_FRAMES);
+        film.still = 1;
+        const seq = await allocate(film.deps.fs, dir);
+        // The step shots' own limit is the platform's: a frame never takes the last of it.
+        if (seq > STEP_SCREENSHOT.MAX_PER_RUN)
+            return;
+        framesIn.set(dir, kept + 1);
+        const file = `${String(seq).padStart(SEQ_WIDTH, '0')}-${FRAME.TOOL}${JPEG_EXT}`;
+        const record = {
+            seq,
+            file,
+            tool: FRAME.TOOL,
+            source: ScreenshotSource.BROWSER,
+            ...size,
+            sha256,
+        };
+        const fs = film.deps.fs;
+        const land = (async () => {
+            await fs.mkdir(dir);
+            await fs.writeFileBytes(join(dir, file), bytes);
+            await fs.appendFile(join(dir, STEP_SCREENSHOT.MANIFEST_FILE), `${JSON.stringify(record)}\n`);
+        })().catch(() => undefined);
+        noteLanding(dir, land);
+        await land;
+    }
+    catch {
+        // A frame is a courtesy: the next tick tries again.
+    }
+}
+/** The real pixels of a driven tab, as a frame. */
+async function framePixels(deps, session) {
+    const opts = { jpegQuality: FRAME.JPEG_QUALITY, cssScale: true };
+    const leased = await deps.pool?.screenshotLease(session.id, opts);
+    if (leased !== undefined)
+        return leased;
+    if (true !== (await deps.realInput?.isAvailableFor(session.url)))
+        return undefined;
+    return deps.realInput?.screenshot?.(session.url, opts);
+}

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

@@ -205,8 +205,8 @@ function runtimeOf(deps, sessionId) {
  * 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.
+ * CDP and leased pages honor `clip`/`ref`. The desktop shell photographs the whole window,
+ * so scoped desktop captures are refused instead of saved or compared as full-window images.
  *
  * `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
@@ -238,8 +238,14 @@ async function capture(deps, sessionId, args) {
     // 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)
+    if (desktop.png !== undefined) {
+        // Check the route that supplied the pixels, not the session runtime: a desktop session can
+        // use CDP, and a page without desktop capture can still fall back to a leased browser.
+        if (args['clip'] !== undefined || args['ref'] !== undefined) {
+            return { reason: VisualReason.CROP_UNSUPPORTED };
+        }
         return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
+    }
     if (desktop.reason !== undefined)
         return desktop;
     /*
@@ -251,7 +257,9 @@ async function capture(deps, sessionId, args) {
      */
     const leased = sessionId === undefined
         ? undefined
-        : await deps.pool?.screenshotLease(sessionId, { fullPage: true === args['fullPage'] });
+        : // The same scope as the provider route: `clip` and `ref` were dropped here, so a scoped
+            // shot of a lease saved the whole viewport and answered `saved: true`.
+            await deps.pool?.screenshotLease(sessionId, await buildOpts(deps, sessionId, args));
     // A leased page is a real browser page, whatever the session is.
     if (leased !== undefined)
         return { png: leased, runtime: AppRuntime.WEB };

package/dist/hooks/coding-agents.d.ts

@@ -4,6 +4,12 @@ export declare function agentLabel(name: string): string;
 export declare function agentClientOf(name: string | undefined): AgentClient | undefined;
 /** An MCP connection finished its handshake as `name`. */
 export declare function noteAgentAttached(attachId: string, name: string): void;
+/** Connection `attachId` announced the agent session `session`. */
+export declare function noteAgentSession(attachId: string, session: string): void;
+/** The agent session connection `attachId` announced, if any. */
+export declare function agentSessionOf(attachId: string | undefined): string | undefined;
+/** The name connection `attachId` gave in its handshake, while it is attached. */
+export declare function agentNameOf(attachId: string | undefined): string | undefined;
 /** That connection closed. */
 export declare function noteAgentDetached(attachId: string): void;
 /** The friendly names of the agents attached now, each once. */

package/dist/hooks/coding-agents.js

@@ -40,8 +40,9 @@ export function agentLabel(name) {
 }
 /** The closed telemetry value for a client name: never the name itself, which is the client's text. */
 export function agentClientOf(name) {
-    if (name === undefined || 0 === name.trim().length)
+    if (name === undefined || 0 === name.trim().length) {
         return undefined;
+    }
     return knownAgent(name)?.[2] ?? AgentClient.OTHER;
 }
 /** An MCP connection finished its handshake as `name`. */
@@ -49,10 +50,29 @@ export function noteAgentAttached(attachId, name) {
     byAttach.set(attachId, name);
     changed();
 }
+/**
+ * The agent's own session id per connection, as its MCP server announced it. Kept after the
+ * connection closes: a run written at a session's end still needs it.
+ * ponytail: never pruned; one short string per MCP connect for the daemon's lifetime.
+ */
+const sessionByAttach = new Map();
+/** Connection `attachId` announced the agent session `session`. */
+export function noteAgentSession(attachId, session) {
+    sessionByAttach.set(attachId, session);
+}
+/** The agent session connection `attachId` announced, if any. */
+export function agentSessionOf(attachId) {
+    return attachId === undefined ? undefined : sessionByAttach.get(attachId);
+}
+/** The name connection `attachId` gave in its handshake, while it is attached. */
+export function agentNameOf(attachId) {
+    return attachId === undefined ? undefined : byAttach.get(attachId);
+}
 /** That connection closed. */
 export function noteAgentDetached(attachId) {
-    if (byAttach.delete(attachId))
+    if (byAttach.delete(attachId)) {
         changed();
+    }
 }
 /** The friendly names of the agents attached now, each once. */
 export function connectedAgents() {
@@ -95,8 +115,9 @@ export function callerClientName() {
 export function callingClientName() {
     const own = calling.getStore();
     const name = own === undefined ? undefined : byAttach.get(own);
-    if (name !== undefined)
+    if (name !== undefined) {
         return name;
+    }
     const all = [...new Set(byAttach.values())];
     return 1 === all.length ? all[0] : undefined;
 }

package/dist/hooks/episode-stamp.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which episode a run belongs to, the commit it ran against, and the agent session behind it.
+ *
+ * The episode log notes each episode here as it writes; the run store reads it back to stamp a run
+ * with `episodeId`, `agentSession` and `project.commit`, so a run joins to the agent's trajectory
+ * exactly instead of by time and file. A leaf: it imports nothing, so both sides can reach it.
+ */
+export interface EpisodeStamp {
+    episodeId: string;
+    /** The git HEAD at the episode's start, once git has answered. */
+    head?: string;
+    /**
+     * The coding agent's own session id, as its MCP server announced it (Claude Code's
+     * `CLAUDE_CODE_SESSION_ID`, which is the `session_id` its hooks receive). Names the
+     * `agent-<session>.jsonl` the agent hooks write.
+     */
+    agentSession?: string;
+}
+/** What one write to an episode says. Every field may be absent: a HEAD arrives later, alone. */
+export interface EpisodeNote {
+    head?: string;
+    sessionId?: string;
+    agentSession?: string;
+}
+/** An episode wrote to `root`. */
+export declare function noteEpisode(root: string, episodeId: string, note?: EpisodeNote): void;
+/**
+ * The episode a run written to `root` belongs to: the calling connection's; else, outside a call,
+ * the one whose calls last drove the run's tab; else the project's only episode. Two episodes and
+ * nothing to tell them apart is undefined, never the newest one.
+ */
+export declare function episodeStampFor(root: string, attachId?: string, sessionId?: string): EpisodeStamp | undefined;

package/dist/hooks/episode-stamp.js

@@ -0,0 +1,61 @@
+/**
+ * Which episode a run belongs to, the commit it ran against, and the agent session behind it.
+ *
+ * The episode log notes each episode here as it writes; the run store reads it back to stamp a run
+ * with `episodeId`, `agentSession` and `project.commit`, so a run joins to the agent's trajectory
+ * exactly instead of by time and file. A leaf: it imports nothing, so both sides can reach it.
+ */
+/** Per project root, each episode by id. */
+const byRoot = new Map();
+/** Orders calls across episodes, so "the last episode to drive a tab" is well defined. */
+let tick = 0;
+/** An episode wrote to `root`. */
+export function noteEpisode(root, episodeId, note = {}) {
+    const episodes = byRoot.get(root) ?? new Map();
+    const known = episodes.get(episodeId) ?? { episodeId, tabs: new Map() };
+    if (note.head !== undefined) {
+        known.head = note.head;
+    }
+    if (note.agentSession !== undefined) {
+        known.agentSession = note.agentSession;
+    }
+    if (note.sessionId !== undefined) {
+        known.tabs.set(note.sessionId, (tick += 1));
+    }
+    episodes.set(episodeId, known);
+    byRoot.set(root, episodes);
+}
+const stampOf = ({ episodeId, head, agentSession }) => ({
+    episodeId,
+    ...(head === undefined ? {} : { head }),
+    ...(agentSession === undefined ? {} : { agentSession }),
+});
+/**
+ * The episode a run written to `root` belongs to: the calling connection's; else, outside a call,
+ * the one whose calls last drove the run's tab; else the project's only episode. Two episodes and
+ * nothing to tell them apart is undefined, never the newest one.
+ */
+export function episodeStampFor(root, attachId, sessionId) {
+    const episodes = byRoot.get(root);
+    if (episodes === undefined) {
+        return undefined;
+    }
+    const own = attachId === undefined ? undefined : episodes.get(attachId);
+    if (own !== undefined) {
+        return stampOf(own);
+    }
+    if (sessionId !== undefined) {
+        let driver;
+        for (const episode of episodes.values()) {
+            const at = episode.tabs.get(sessionId);
+            if (at !== undefined && (driver === undefined || at > (driver.tabs.get(sessionId) ?? 0))) {
+                driver = episode;
+            }
+        }
+        if (driver !== undefined) {
+            return stampOf(driver);
+        }
+    }
+    const [only, ...more] = episodes.values();
+    return only !== undefined && 0 === more.length ? stampOf(only) : undefined;
+}

package/dist/hooks/hook-commands.js

@@ -49,12 +49,20 @@ const MAX_IN_FLIGHT = 8;
 let inFlight = 0;
 const reported = new Set();
 function reportOnce(key, message) {
-    if (reported.has(key))
+    if (reported.has(key)) {
         return;
+    }
     reported.add(key);
     log(`hook: ${message}`);
 }
-/** Cached config plus the mtime it was read at, so an edit takes effect without a daemon restart. */
+/**
+ * Cached config plus the file and mtime it was read at, so an edit takes effect without a
+ * daemon restart.
+ *
+ * The path is part of the key. Two roots can share an mtime — a coarse filesystem stamps
+ * every write in the same millisecond — and a cache that remembers only the time returns
+ * the other root's commands.
+ */
 let cached;
 /**
  * Read `.reticle/hooks.json`, or nothing.
@@ -76,21 +84,22 @@ export function readHookConfig(reticleRoot) {
         return {};
     }
     try {
-        return readOpenHookConfig(fd);
+        return readOpenHookConfig(fd, path);
     }
     finally {
         closeSync(fd);
     }
 }
-function readOpenHookConfig(fd) {
+function readOpenHookConfig(fd, path) {
     const mtime = fstatSync(fd).mtimeMs;
-    if (cached !== undefined && cached.at === mtime)
+    if (cached !== undefined && cached.path === path && cached.at === mtime) {
         return cached.config;
+    }
     try {
         const parsed = HookConfigSchema.safeParse(JSON.parse(readFileSync(fd, 'utf8')));
         if (!parsed.success) {
             reportOnce(`config:${String(mtime)}`, `${ReticleDir.HOOKS_FILE} is not a map of event→command`);
-            cached = { at: mtime, config: {} };
+            cached = { path, at: mtime, config: {} };
             return {};
         }
         // An unknown event name is the likeliest mistake in this file and the one that is otherwise
@@ -103,12 +112,12 @@ function readOpenHookConfig(fd) {
             }
             reportOnce(`unknown:${event}`, `${ReticleDir.HOOKS_FILE} names "${event}", which is not a Reticle event. Known events: ${HOOK_EVENT_NAMES.join(', ')}`);
         }
-        cached = { at: mtime, config: known };
+        cached = { path, at: mtime, config: known };
         return known;
     }
     catch (error) {
         reportOnce(`parse:${String(mtime)}`, `${ReticleDir.HOOKS_FILE} could not be read: ${error instanceof Error ? error.message : String(error)}`);
-        cached = { at: mtime, config: {} };
+        cached = { path, at: mtime, config: {} };
         return {};
     }
 }
@@ -167,8 +176,9 @@ export function runHookCommand(command, payload, cwd) {
 export function installCommandHooks(reticleRoot) {
     return onHook(undefined, (payload) => {
         const command = readHookConfig(reticleRoot)[payload.event];
-        if (command === undefined || 0 === command.trim().length)
+        if (command === undefined || 0 === command.trim().length) {
             return;
+        }
         runHookCommand(command, payload, reticleRoot);
     });
 }

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { replayVerdictLine } from './language/flows/replay-from-hud.js';
 export { ReticleTool } from '@reticlehq/core';
 export { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
 export { Bridge } from './portal/bridge/bridge.js';
+export type { FollowNavigation, OriginFollowRequest, } from './portal/bridge/origin/origin-follow.js';
 export { Session } from './portal/session/session.js';
 export { SessionManager } from './portal/session/session-manager.js';
 export type { SessionInfo, SessionHealth } from './portal/session/session.js';
@@ -14,7 +15,8 @@ export type { RecommendationInputs } from './portal/session/presence/session-rec
 export { TOOLS } from './surface/tools/tools.js';
 export type { ToolDeps, ToolDef } from './surface/tools/tools.js';
 export { createToolInvoker, UNKNOWN_TOOL_ERROR } from './surface/tools/tool-invoker.js';
-export { runTool, SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/tools/invoke-tool.js';
+export { runTool } from './surface/tools/invoke-tool.js';
+export { SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/tools/tool-kit.js';
 export type { ToolInvoker } from './surface/tools/tool-invoker.js';
 /**
  * The port-presence check the CLI commands (`drive`, `verify`, `status`, `doctor`, `kill`) all share,
@@ -72,6 +74,8 @@ export interface RunningServer {
      * the client owns the process and there is no stream to warn. See SharedServer.announceShutdown.
      */
     announceShutdown?: () => void;
+    /** Daemon only: run `handler` when a caller with the pairing token POSTs SHUTDOWN_PATH. */
+    onShutdownRequest?: (handler: () => void) => void;
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './portal/bridge/bridge-security.js';