@reticlehq/server 2.7.0 → 2.9.0

package/dist/http-server.d.ts

@@ -11,6 +11,15 @@ export interface SharedServer {
     attachMcp(factory: () => McpServer): void;
     /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
     attachStatus(provider: () => unknown): void;
+    /**
+     * Register the handler behind POST /drive: open a driveable browser at `url` and answer with the
+     * session it registered.
+     *
+     * This is how `reticle drive` stops fighting the daemon for the bridge port. The daemon already
+     * owns the browser plane, so driving is a request to it — see cli/drive-attach.ts. Left
+     * unattached, the route 404s, which is exactly what a newer CLI needs to hear from an older daemon.
+     */
+    attachDrive(provider: (url: string) => Promise<unknown>): void;
     /**
      * Register a callback fired when the AGENT presence changes — true when the first MCP client (any
      * agent: Codex/OpenCode/Claude/Hermes) connects, false when the last one disconnects. Agent-
@@ -18,6 +27,15 @@ export interface SharedServer {
      * "is an agent attached?". The daemon uses this to tell the panel "agent live" vs "agent stopped".
      */
     attachAgentPresence(cb: (connected: boolean) => void): void;
+    /**
+     * Tell every attached MCP proxy that this daemon is retiring, BEFORE the sockets go.
+     *
+     * The proxy sees a clean stream end whether the daemon shut down on schedule or died under it, so
+     * without this the two are one row and the transport-stability metric is dominated by the designed
+     * case. Separate from `close()` because it must run before the shutdown work rather than during it:
+     * `close()` is also the cleanup path of a start that failed, where there is nobody to tell.
+     */
+    announceShutdown(): void;
     close(): Promise<void>;
 }
 /**
@@ -32,3 +50,4 @@ export interface SharedServer {
 export declare function createSharedServer(options?: {
     token?: string;
 }): SharedServer;
+export declare function driveSchemeRefusal(url: string): string | undefined;

package/dist/http-server.js

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { MCP_SSE_PATH, MCP_MESSAGE_PATH, STATUS_PATH } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, DRIVE_PATH, } from '@reticlehq/core';
 import { getSessionMetrics } from './telemetry/session-metrics.js';
 import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from './version/peer-announce.js';
 import { log } from './log.js';
@@ -18,8 +18,15 @@ import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensM
 export function createSharedServer(options = {}) {
     let mcpFactory;
     let statusProvider;
+    let driveProvider;
     let agentPresence;
     const transports = new Map();
+    /**
+     * The raw response behind each SSE session, so the shutdown announcement can be written as an SSE
+     * frame the proxy reads and the agent never sees. `SSEServerTransport.send` only speaks JSON-RPC,
+     * and this message is addressed to the proxy rather than to the client behind it.
+     */
+    const sseStreams = new Map();
     const token = options.token;
     // The agent control plane (MCP transport) and /status carry the same trust as the browser WS: a
     // loopback peer is trusted (the local stdio proxy and `reticle status` always dial 127.0.0.1), but any
@@ -45,9 +52,23 @@ export function createSharedServer(options = {}) {
     };
     const httpServer = http.createServer((req, res) => {
         const rawUrl = req.url ?? '/';
-        const url = new URL(rawUrl, 'http://localhost');
+        // Node's HTTP parser accepts request targets the WHATWG URL parser refuses (`//` among them), and
+        // a throw in a `request` listener is an uncaughtException — which the daemon answers by exiting,
+        // taking every agent and every browser session on this port with it, from whichever project. One
+        // malformed line on a loopback socket, and it lands BEFORE the authorization check below, so
+        // nothing had to be trusted to send it.
+        const url = parseRequestTarget(rawUrl);
+        if (null === url) {
+            log('http_bad_request_target', {});
+            res.writeHead(400, { 'Content-Type': 'text/plain' });
+            res.end('bad request target');
+            return;
+        }
         const path = url.pathname;
-        if (path === STATUS_PATH || path === MCP_SSE_PATH || path === MCP_MESSAGE_PATH) {
+        if (path === STATUS_PATH ||
+            path === DRIVE_PATH ||
+            path === MCP_SSE_PATH ||
+            path === MCP_MESSAGE_PATH) {
             if (!authorized(req, url)) {
                 res.writeHead(401, { 'Content-Type': 'text/plain' });
                 res.end('unauthorized');
@@ -60,6 +81,58 @@ export function createSharedServer(options = {}) {
             res.end(body);
             return;
         }
+        if ('POST' === req.method && path === DRIVE_PATH) {
+            if (driveProvider === undefined) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('not found');
+                return;
+            }
+            // A state-changing route must require a content type that a browser cannot send without a
+            // preflight. `text/plain`, `application/x-www-form-urlencoded` and `multipart/form-data` make
+            // a POST a CORS SIMPLE request: the browser sends it cross-origin with no preflight, and
+            // blocking the response afterwards does not un-drive the browser. Since loopback origins are
+            // authorized here by design, any page on any localhost port could otherwise reach this route
+            // by guessing ours, and drive a browser to a URL it chose.
+            //
+            // Requiring `application/json` forces a preflight, which the browser will not complete without
+            // our opt-in, and we do not opt in. One header check closes the whole class.
+            if (!isJsonRequest(req)) {
+                res.writeHead(415, { 'Content-Type': 'text/plain' });
+                res.end('expected content-type: application/json');
+                return;
+            }
+            const provider = driveProvider;
+            readBody(req)
+                .then(async (body) => {
+                const url = urlFromDriveRequest(body);
+                if (url === undefined) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end('drive requires a url');
+                    return;
+                }
+                // Before the browser is asked for anything. See driveSchemeRefusal.
+                const refusal = driveSchemeRefusal(url);
+                if (refusal !== undefined) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end(refusal);
+                    return;
+                }
+                // A refusal is an ANSWER. The caller is a foreground CLI waiting on this socket: a thrown
+                // handler that took the response down with it would hang `reticle drive` on a request
+                // that can never complete — the same shape of silence the raw EADDRINUSE bind had.
+                const payload = await provider(url).catch((err) => ({
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(payload));
+            })
+                .catch((err) => {
+                log('drive_request_error', { error: err instanceof Error ? err.message : String(err) });
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('drive failed');
+            });
+            return;
+        }
         if ('GET' === req.method && path === MCP_SSE_PATH) {
             // The agent's MCP server announces itself here, on the connect it already makes. The daemon is
             // the single judge of skew, so this is where the third pair is decided — and unlike the CLI's
@@ -79,10 +152,12 @@ export function createSharedServer(options = {}) {
             const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
             const sid = transport.sessionId;
             transports.set(sid, transport);
+            sseStreams.set(sid, res);
             if (1 === transports.size)
                 agentPresence?.(true); // first agent attached
             res.on('close', () => {
                 transports.delete(sid);
+                sseStreams.delete(sid);
                 transport.close().catch(() => undefined);
                 mcpServer.close().catch(() => undefined);
                 log('mcp_client_disconnected', { sessionId: sid });
@@ -137,17 +212,33 @@ export function createSharedServer(options = {}) {
     function attachStatus(provider) {
         statusProvider = provider;
     }
+    function attachDrive(provider) {
+        driveProvider = provider;
+    }
     function attachAgentPresence(cb) {
         agentPresence = cb;
     }
     function attachMcp(factory) {
         mcpFactory = factory;
     }
+    function announceShutdown() {
+        for (const [sid, stream] of sseStreams) {
+            try {
+                stream.write(`event: ${MCP_SHUTDOWN_EVENT}\ndata: {}\n\n`);
+            }
+            catch {
+                // A stream we cannot write to is a proxy that already left. Announcing a shutdown must never
+                // be the reason a shutdown fails.
+                log('mcp_shutdown_announce_failed', { sessionId: sid });
+            }
+        }
+    }
     async function close() {
         for (const transport of transports.values()) {
             await transport.close();
         }
         transports.clear();
+        sseStreams.clear();
         await new Promise((resolve, reject) => {
             httpServer.close((err) => {
                 // A server that never listened is already closed, and saying so is not an error worth
@@ -167,5 +258,112 @@ export function createSharedServer(options = {}) {
             });
         });
     }
-    return { httpServer, attachMcp, attachStatus, attachAgentPresence, close };
+    return {
+        httpServer,
+        attachMcp,
+        attachStatus,
+        attachDrive,
+        attachAgentPresence,
+        announceShutdown,
+        close,
+    };
+}
+/** Cap on a drive request body. A url is short; anything larger is not one. */
+const MAX_DRIVE_BODY_BYTES = 8 * 1024;
+/** Collect a request body, refusing one too large to be what this route accepts. */
+/**
+ * Is this a request a cross-origin page could NOT have sent without a preflight?
+ *
+ * The three CORS "simple" content types are the whole attack surface here, so anything that is not
+ * JSON is refused rather than sniffed. Parameters are allowed (`application/json; charset=utf-8`)
+ * because real clients send them.
+ */
+const JSON_MEDIA_TYPE = 'application/json';
+function isJsonRequest(req) {
+    // Read through the typed accessor rather than indexing the header bag: the index signature is
+    // `any`-shaped, and narrowing after an unsafe read is narrowing a lie.
+    const value = req.headersDistinct['content-type']?.[0];
+    if (undefined === value)
+        return false;
+    return JSON_MEDIA_TYPE === value.split(';')[0]?.trim().toLowerCase();
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => {
+            body += chunk;
+            if (body.length > MAX_DRIVE_BODY_BYTES) {
+                req.destroy();
+                reject(new Error('body too large'));
+            }
+        });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+/** The `url` out of a drive request body, or undefined when there isn't a usable one. Pure. */
+/**
+ * The schemes the daemon will open in a browser it owns.
+ *
+ * `drive` exists to drive a running web app, and nothing in the product hands this route anything
+ * else — the desktop paths have their own runtimes and never come through here. So the allowlist
+ * costs nothing real and closes a class outright.
+ *
+ * Kept deliberately small. `file:` reads the disk through a browser context WE opened, `data:` is a
+ * page that came from nowhere, and `javascript:` is not a document at all. None of them is a thing
+ * anybody drives.
+ *
+ * Worth stating what this is NOT: the CORS defence on the route already keeps a web page off it,
+ * because a JSON content type forces a preflight nobody opts into. The caller reaching this check is
+ * a local process, which already has broader access than the check removes. It is hygiene about what
+ * the daemon will open on request, not a security boundary — and a refusal here should read as a
+ * refusal, not an alarm.
+ */
+const DRIVEABLE_SCHEMES = ['http:', 'https:'];
+/** The scheme of `url`, or undefined when it is not a URL at all. */
+function schemeOf(url) {
+    try {
+        return new URL(url).protocol;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function driveSchemeRefusal(url) {
+    const scheme = schemeOf(url);
+    if (scheme !== undefined && DRIVEABLE_SCHEMES.includes(scheme))
+        return undefined;
+    // Names what it got, because the caller is a CLI printing this to somebody who typed the url and
+    // needs to see which part of it was the problem.
+    return (`unsupported scheme ${scheme ?? '(unparseable url)'} — reticle drive opens a running web app, ` +
+        `so it accepts ${DRIVEABLE_SCHEMES.join(' and ')} only`);
+}
+function urlFromDriveRequest(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || null === parsed)
+        return undefined;
+    const url = parsed['url'];
+    return 'string' === typeof url && url.length > 0 ? url : undefined;
+}
+/**
+ * The one URL parse on the daemon's request path, and the only place allowed to do it.
+ *
+ * `null` for anything the parser refuses, so the caller answers rather than throwing. Exported for
+ * nothing — it is here, next to its single caller, because a second copy of this parse elsewhere in
+ * the handler would reintroduce the crash the guard exists to remove.
+ */
+function parseRequestTarget(rawUrl) {
+    try {
+        return new URL(rawUrl, 'http://localhost');
+    }
+    catch {
+        return null;
+    }
 }

package/dist/impact/impact-recorder.d.ts

@@ -0,0 +1,23 @@
+import { type ImpactCounts, type ImpactSnapshot } from '@reticlehq/core';
+import { ImpactStore, type ImpactFoldMeta } from './impact-store.js';
+/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
+export declare function initImpact(opts: {
+    reticleRoot: string | undefined;
+    projectName?: string;
+    now?: () => number;
+}): ImpactStore | undefined;
+/** The live store, if one has been initialised. */
+export declare function impactStore(): ImpactStore | undefined;
+/** Test seam: drop the singleton so a suite can start from a clean record. */
+export declare function resetImpactForTest(): void;
+/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
+export declare function recordImpact(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta): void;
+export declare function impactSnapshot(): ImpactSnapshot | undefined;
+/**
+ * What one tool call did, as counters.
+ *
+ * Pure and exported so the shape is testable without a dispatch: given a result and a duration, it
+ * says what the record should gain. `verified` is the only field that can mint a verdict, which is
+ * the same rule the product states to agents - everything else moves or reads the app.
+ */
+export declare function deltaForToolResult(raw: unknown, durationMs: number, refused: boolean): Partial<ImpactCounts>;

package/dist/impact/impact-recorder.js

@@ -0,0 +1,76 @@
+import { Verified } from '@reticlehq/core';
+import { estimateTokens } from '../session/output-budget.js';
+import { ImpactStore } from './impact-store.js';
+/**
+ * The daemon's single impact recorder.
+ *
+ * One store per daemon, created on the first call that knows the project's `.reticle` root. A
+ * module singleton for the same reason the tool counters are: the dispatch chokepoint has to be
+ * able to record without every tool threading a store through its arguments, and a second recorder
+ * would silently split the user's own history in half.
+ */
+let store;
+/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
+export function initImpact(opts) {
+    // No root, no record. Programmatic callers and test doubles build their own deps and are not
+    // obliged to carry one, and a courtesy counter must never be the reason a tool call throws.
+    if (opts.reticleRoot === undefined || 0 === opts.reticleRoot.length)
+        return store;
+    store ??= new ImpactStore({ ...opts, reticleRoot: opts.reticleRoot });
+    return store;
+}
+/** The live store, if one has been initialised. */
+export function impactStore() {
+    return store;
+}
+/** Test seam: drop the singleton so a suite can start from a clean record. */
+export function resetImpactForTest() {
+    store = undefined;
+}
+/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
+export function recordImpact(delta, meta = {}) {
+    try {
+        store?.record(delta, meta);
+    }
+    catch {
+        // Counting is a courtesy to the user; failing to count is not worth failing their call over.
+    }
+}
+export function impactSnapshot() {
+    return store?.snapshot();
+}
+/**
+ * What one tool call did, as counters.
+ *
+ * Pure and exported so the shape is testable without a dispatch: given a result and a duration, it
+ * says what the record should gain. `verified` is the only field that can mint a verdict, which is
+ * the same rule the product states to agents - everything else moves or reads the app.
+ */
+export function deltaForToolResult(raw, durationMs, refused) {
+    const delta = {
+        calls: 1,
+        drivingMs: Math.max(0, Math.round(durationMs)),
+        tokensReturned: estimateTokens(JSON.stringify(raw) ?? ''),
+    };
+    if (refused) {
+        delta.refusals = 1;
+        return delta;
+    }
+    const verified = isRecord(raw) ? raw['verified'] : undefined;
+    if (verified === Verified.YES) {
+        delta.verdicts = 1;
+        delta.passed = 1;
+    }
+    else if (verified === Verified.NO) {
+        delta.verdicts = 1;
+        delta.failed = 1;
+    }
+    else if (verified === Verified.UNKNOWN) {
+        delta.verdicts = 1;
+        delta.unknown = 1;
+    }
+    return delta;
+}
+function isRecord(value) {
+    return 'object' === typeof value && null !== value;
+}

package/dist/impact/impact-store.d.ts

@@ -0,0 +1,47 @@
+import { type ImpactCounts, type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
+export interface ImpactPaths {
+    project: string;
+    global: string;
+}
+/**
+ * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
+ * the global scope always lives beside the daemon's own state in `~/.reticle`.
+ */
+export declare function impactPaths(reticleRoot: string): ImpactPaths;
+/** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
+export declare function readScope(path: string, now: number): ImpactScope;
+/** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
+export declare function isoDay(now: number): string;
+/**
+ * What a fold knows beyond the counters.
+ *
+ * `runMs` is a SESSION's lifetime, and it only ever feeds the "longest run" record. It is not a
+ * counter: adding it to a total would answer a question nobody asked, and the record used to be fed
+ * a single tool call's duration instead, which made the report's superlative a number of
+ * milliseconds that never grew past one click.
+ */
+export interface ImpactFoldMeta {
+    runMs?: number;
+}
+/** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
+export declare function applyDelta(scope: ImpactScope, delta: Partial<ImpactCounts>, now: number, meta?: ImpactFoldMeta): ImpactScope;
+/**
+ * The live impact record for one project.
+ *
+ * Holds both scopes in memory, folds deltas in synchronously (so a reader always sees the truth),
+ * and flushes to disk on a debounce.
+ */
+export declare class ImpactStore {
+    #private;
+    constructor(opts: {
+        reticleRoot: string;
+        projectName?: string;
+        now?: () => number;
+    });
+    /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
+    onChange(fn: () => void): void;
+    record(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta): void;
+    snapshot(): ImpactSnapshot;
+    /** Write now (process exit, tests). */
+    flush(): void;
+}

package/dist/impact/impact-store.js

@@ -0,0 +1,171 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_SCHEMA_VERSION, ImpactScopeSchema, addImpactCounts, emptyImpactCounts, emptyImpactRecords, estimateImpactSavings, } from '@reticlehq/core';
+/**
+ * Where Reticle keeps the record of what it has done for you.
+ *
+ * Two scopes, two files, both local and never uploaded: the project's own `.reticle/impact.json`,
+ * and a machine-wide `~/.reticle/impact.json` that answers "what has Reticle done for me overall"
+ * across every app you have instrumented.
+ *
+ * This is NOT telemetry. Telemetry answers our questions about the product and leaves the machine;
+ * this answers the user's question about their own work and never does.
+ */
+/** Writes are debounced: a verification loop is 50-200 calls, and each one is a counter bump. */
+const WRITE_DEBOUNCE_MS = 800;
+/**
+ * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
+ * the global scope always lives beside the daemon's own state in `~/.reticle`.
+ */
+export function impactPaths(reticleRoot) {
+    return {
+        project: join(reticleRoot, ReticleDir.IMPACT_FILE),
+        global: join(homedir(), ReticleDir.ROOT, ReticleDir.IMPACT_FILE),
+    };
+}
+function emptyScope(now) {
+    const counts = emptyImpactCounts();
+    return {
+        counts,
+        days: [],
+        records: emptyImpactRecords(),
+        savings: estimateImpactSavings(counts),
+        since: now,
+    };
+}
+/** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
+export function readScope(path, now) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const result = ImpactScopeSchema.safeParse(parsed);
+        return result.success ? result.data : emptyScope(now);
+    }
+    catch {
+        return emptyScope(now);
+    }
+}
+/**
+ * Write a scope atomically.
+ *
+ * tmp + rename, because two daemons can serve two apps in the same repo at once and a half-written
+ * counters file is one the next read discards - silently losing the whole history.
+ */
+function writeScope(path, scope) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, JSON.stringify(scope, null, 2), 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // A stats file that cannot be written must never break a tool call. The counters stay in
+        // memory and the next write attempt carries them.
+    }
+}
+/** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
+export function isoDay(now) {
+    const d = new Date(now);
+    const month = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${String(d.getFullYear())}-${month}-${day}`;
+}
+/** Whether `b` is the calendar day right after `a` - the streak rule. */
+function isNextDay(a, b) {
+    const prev = new Date(`${a}T00:00:00`);
+    const next = new Date(`${b}T00:00:00`);
+    return 1 === Math.round((next.getTime() - prev.getTime()) / 86_400_000);
+}
+/** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
+export function applyDelta(scope, delta, now, meta = {}) {
+    const today = isoDay(now);
+    const counts = addImpactCounts(scope.counts, delta);
+    const days = scope.days.slice();
+    const last = days[days.length - 1];
+    if (last !== undefined && last.date === today) {
+        days[days.length - 1] = { date: today, counts: addImpactCounts(last.counts, delta) };
+    }
+    else {
+        days.push({ date: today, counts: addImpactCounts(emptyImpactCounts(), delta) });
+    }
+    while (days.length > IMPACT_DAILY_BUCKETS)
+        days.shift();
+    const todayCounts = days[days.length - 1]?.counts ?? emptyImpactCounts();
+    const previousDay = days[days.length - 2];
+    const records = { ...scope.records };
+    records.bestVerdictDay = Math.max(records.bestVerdictDay, todayCounts.verdicts);
+    records.bestDefectDay = Math.max(records.bestDefectDay, todayCounts.failed);
+    if (last === undefined || last.date !== today) {
+        // A new day joins the streak only if it follows yesterday; otherwise it starts a new one.
+        records.streakDays =
+            previousDay !== undefined && isNextDay(previousDay.date, today) ? records.streakDays + 1 : 1;
+    }
+    else if (0 === records.streakDays) {
+        records.streakDays = 1;
+    }
+    records.bestStreakDays = Math.max(records.bestStreakDays, records.streakDays);
+    records.longestRunMs = Math.max(records.longestRunMs, meta.runMs ?? 0);
+    return { counts, days, records, savings: estimateImpactSavings(counts), since: scope.since };
+}
+/**
+ * The live impact record for one project.
+ *
+ * Holds both scopes in memory, folds deltas in synchronously (so a reader always sees the truth),
+ * and flushes to disk on a debounce.
+ */
+export class ImpactStore {
+    #paths;
+    #now;
+    #projectName;
+    #project;
+    #global;
+    #timer;
+    #onChange;
+    constructor(opts) {
+        this.#paths = impactPaths(opts.reticleRoot);
+        this.#now = opts.now ?? (() => Date.now());
+        this.#projectName = opts.projectName;
+        const now = this.#now();
+        this.#project = readScope(this.#paths.project, now);
+        this.#global = readScope(this.#paths.global, now);
+    }
+    /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
+    onChange(fn) {
+        this.#onChange = fn;
+    }
+    record(delta, meta = {}) {
+        const now = this.#now();
+        this.#project = applyDelta(this.#project, delta, now, meta);
+        this.#global = applyDelta(this.#global, delta, now, meta);
+        this.#scheduleFlush();
+        this.#onChange?.();
+    }
+    snapshot() {
+        const snap = {
+            schemaVersion: IMPACT_SCHEMA_VERSION,
+            project: this.#project,
+            global: this.#global,
+        };
+        if (this.#projectName !== undefined)
+            snap.projectName = this.#projectName;
+        return snap;
+    }
+    /** Write now (process exit, tests). */
+    flush() {
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+        writeScope(this.#paths.project, this.#project);
+        writeScope(this.#paths.global, this.#global);
+    }
+    #scheduleFlush() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.flush();
+        }, WRITE_DEBOUNCE_MS);
+        this.#timer.unref?.();
+    }
+}

package/dist/index.d.ts

@@ -123,6 +123,13 @@ export interface RunningServer {
     agentAttached?: () => boolean;
     /** The pairing token the bridge is enforcing (explicit, env, or auto-provisioned); undefined if none. */
     token?: string;
+    /**
+     * Tell every attached MCP proxy this daemon is retiring, before anything closes.
+     *
+     * Optional because only the daemon entry point serves MCP over SSE — `start()` speaks stdio, where
+     * the client owns the process and there is no stream to warn. See SharedServer.announceShutdown.
+     */
+    announceShutdown?: () => void;
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './bridge/bridge-security.js';