@reticlehq/server 2.2.0 → 2.3.0

package/dist/log.d.ts

@@ -3,4 +3,3 @@
  * write logs there.
  */
 export declare function log(event: string, fields?: Record<string, unknown>): void;
-//# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -6,4 +6,3 @@ export function log(event, fields = {}) {
     const line = JSON.stringify({ event, ...fields });
     process.stderr.write(`${line}\n`);
 }
-//# sourceMappingURL=log.js.map

package/dist/mcp-proxy.d.ts

@@ -33,4 +33,3 @@ export declare function buildSessionUrl(rawData: string, port: number): string;
  * Claude Code restarts the proxy fresh).
  */
 export declare function startMcpProxy(port: number): Promise<never>;
-//# sourceMappingURL=mcp-proxy.d.ts.map

package/dist/mcp-proxy.js

@@ -188,4 +188,3 @@ export function startMcpProxy(port) {
         process.stdin.on('end', () => process.exit(0));
     });
 }
-//# sourceMappingURL=mcp-proxy.js.map

package/dist/mcp.d.ts

@@ -10,6 +10,7 @@ import { type ToolProfile } from './tools/profiles.js';
  * Non-session-bound tools (and tools with no outputSchema) are returned unchanged.
  */
 export declare function withSessionEnvelope(name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
+export declare function firstSentence(description: string): string;
 /**
  * Serialize a tool result to the MCP `text` content block. The agent consumes this text — the
  * typed contract travels separately as `structuredContent`, unchanged by encoding — so the text
@@ -32,5 +33,18 @@ export declare function encodeResult(result: unknown, encoding: string): string;
  * call. `full` advertises everything and needs no hatch.
  */
 export declare function advertisedTools(profile: ToolProfile): ToolDef[];
+/**
+ * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
+ * and (non-lean only) the output schema.
+ *
+ * Exported so tests assert on the REAL advertised text rather than on the tool definitions, which
+ * are trimmed later and would make a guard that cannot fail — a mistake already made once here, with
+ * an abbreviation test that read raw defs and would have passed with the bug fully present.
+ */
+export declare function advertisedConfig(tool: ToolDef, advertised: readonly ToolDef[], profile: ToolProfile): {
+    description: string;
+    inputSchema: z.ZodRawShape;
+    outputSchema?: z.ZodRawShape;
+};
+export declare function installFriendlyArgErrors(server: McpServer, examples: Map<string, string>, allowedKeys?: Map<string, ReadonlySet<string>>): void;
 export declare function createMcpServer(deps: ToolDeps, profile?: ToolProfile): McpServer;
-//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { isToonable, resultToToon } from '@reticlehq/core';
 import { TOOLS } from './tools/tools.js';
@@ -10,6 +11,8 @@ import { buildErrorPayload } from './tools/error-recovery.js';
 import { log } from './log.js';
 import { SERVER_VERSION } from './server-version.js';
 import { MCP_SERVER_NAME } from './init/mcp.js';
+import { setMcpClientNameHook } from './telemetry/feedback-context.js';
+import { getSessionMetrics } from './telemetry/session-metrics.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
@@ -25,10 +28,31 @@ const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
 /** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
  * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
  * first clause retains the essentials (enum hints like "role | text | label" live there). */
-function firstSentence(description) {
+/**
+ * Append the tool's example call to whatever description survived trimming.
+ *
+ * Costs a handful of tokens per turn and buys back the failed round trips an agent spends guessing
+ * how the fields compose — which is a far worse trade in the other direction.
+ */
+function withExample(description, example) {
+    return example === undefined ? description : `${description} e.g. ${JSON.stringify(example)}`;
+}
+/**
+ * Abbreviations whose internal period is NOT a sentence end.
+ *
+ * The splitter looked for the first `". "`, which "e.g. " satisfies — so every lean-profile
+ * description containing one was cut off mid-abbreviation. `reticle_act`'s ref parameter reached the
+ * agent as "Element ref from reticle_snapshot or reticle_query (e.g." and stopped: the example gone,
+ * and any contract stated after it gone too. Silent, and it degraded the DEFAULT profile only, which
+ * is the one nobody reads the raw strings for.
+ */
+const ABBREVIATIONS = ['e.g.', 'i.e.', 'etc.', 'vs.', 'cf.'];
+export function firstSentence(description) {
     const nl = description.indexOf('\n');
     const base = nl >= 0 ? description.slice(0, nl) : description;
-    const dot = base.search(/\.\s/);
+    // Mask abbreviations with an equal-length filler so offsets stay valid in the original string.
+    const masked = ABBREVIATIONS.reduce((text, abbr) => text.split(abbr).join('\u0000'.repeat(abbr.length)), base);
+    const dot = masked.search(/\.\s/);
     const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
     return sentence.length > 160 ? `${sentence.slice(0, 159)}…` : sentence;
 }
@@ -52,9 +76,34 @@ const PREDICATE_PARAMS = new Set(['predicate', 'until']);
  * grammar up front versus letting the agent fetch it from `reticle_tools` when it needs a variant it
  * has not used before.
  */
-const COMPACT_PREDICATE_DESCRIPTION = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
-    'animation | signal | state | settled | allOf | anyOf | not. Call reticle_tools for the full ' +
-    'field grammar of a kind.';
+/**
+ * The kind list — the part an agent needs to WRITE a predicate. Carried on every predicate parameter.
+ *
+ * An earlier version put this on one tool and pointed the other five at it ("same grammar as
+ * reticle_act_and_wait's"), which saved 790 B/turn. It was the wrong trade: it made writing a
+ * predicate require joining two tool descriptions, and accuracy is worth more here than the bytes.
+ * Only the "where to get field details" sentence is stated once now — that one IS a pointer, so
+ * making it a pointer costs nothing.
+ */
+const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
+    'animation | signal | state | settled | allOf | anyOf | not.';
+/**
+ * Said once per turn: the bug-catching options, and where to get the rest of the field grammar.
+ *
+ * `net.count`, `console.absent` and `absent` are the three predicate options that catch a class of
+ * bug rather than confirm an expectation — a double-submit, an action that "worked" while logging a
+ * caught error, something that should have disappeared and did not. They sat behind a
+ * `reticle_tools` round trip, so an agent only found them if it already knew to look, which is the
+ * wrong way round for the checks most likely to catch what nobody suspected.
+ *
+ * Anchored to one tool rather than repeated on all six: these are ADDITIONAL capability, not what
+ * makes a basic predicate correct, so one mention per turn is enough to make them reachable without
+ * paying for six.
+ */
+const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
+    'console.absent:true (action completed with a CLEAN console), absent:true on element/text ' +
+    '(it should be gone). Call reticle_tools for the full field grammar of a kind.';
+const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMMAR_HINT}`;
 /**
  * Lean copy of a tool's zod input shape for lean profiles: each parameter's description is
  * truncated to its first sentence via zod's own `.describe` (which returns a new schema, so the
@@ -62,11 +111,14 @@ const COMPACT_PREDICATE_DESCRIPTION = 'Predicate object: { kind, ...fields }. ki
  * schema cost; the first clause keeps each param's purpose and any enum hints. Params without a
  * description pass through unchanged. Predicate params are replaced wholesale — see above.
  */
-function leanZodShape(shape) {
+function leanZodShape(shape, predicateAnchor) {
     const out = {};
     for (const [key, schema] of Object.entries(shape)) {
         if (PREDICATE_PARAMS.has(key)) {
-            const compact = z.record(z.unknown()).describe(COMPACT_PREDICATE_DESCRIPTION);
+            // Every tool keeps the kinds; only the navigation hint is anchored to one.
+            const compact = z
+                .record(z.unknown())
+                .describe(predicateAnchor === undefined ? COMPACT_PREDICATE_DESCRIPTION : PREDICATE_KINDS);
             out[key] = schema.isOptional() ? compact.optional() : compact;
             continue;
         }
@@ -112,9 +164,84 @@ export function advertisedTools(profile) {
     const base = filterTools(TOOLS, profile === TOOL_PROFILE.HYBRID ? TOOL_PROFILE.CORE : profile);
     return [...base, ...buildDynamicTools(TOOLS)];
 }
+/**
+ * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
+ * and (non-lean only) the output schema.
+ *
+ * Exported so tests assert on the REAL advertised text rather than on the tool definitions, which
+ * are trimmed later and would make a guard that cannot fail — a mistake already made once here, with
+ * an abbreviation test that read raw defs and would have passed with the bug fully present.
+ */
+export function advertisedConfig(tool, advertised, profile) {
+    const terse = profile === TOOL_PROFILE.CORE ||
+        profile === TOOL_PROFILE.STANDARD ||
+        profile === TOOL_PROFILE.HYBRID;
+    // The first advertised tool carrying a predicate spells the grammar out; the rest point at it.
+    const anchor = advertised.find((t) => Object.keys(t.inputSchema).some((k) => PREDICATE_PARAMS.has(k)))?.name;
+    const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
+    return {
+        description: withExample(terse ? firstSentence(tool.description) : tool.description, tool.example),
+        inputSchema: terse
+            ? leanZodShape(tool.inputSchema, tool.name === anchor ? undefined : anchor)
+            : tool.inputSchema,
+        ...(outputSchema !== undefined ? { outputSchema } : {}),
+    };
+}
+/** Argument keys the tool never declared. Empty when the tool's shape is unknown to us. */
+function unknownKeys(args, allowed) {
+    if (allowed === undefined || typeof args !== 'object' || args === null)
+        return [];
+    return Object.keys(args).filter((key) => !allowed.has(key));
+}
+export function installFriendlyArgErrors(server, examples, allowedKeys = new Map()) {
+    const target = server;
+    const original = target.validateToolInput;
+    if (typeof original !== 'function')
+        return;
+    target.validateToolInput = async (tool, args, toolName) => {
+        // An UNKNOWN key is the failure zod cannot catch, because object schemas are non-strict: the key
+        // is silently dropped and the tool answers as if it had not been asked. Measured live —
+        // `reticle_clock { action: "freeze" }` returned `{"frozen":false}`, which reads as a fact about
+        // the app ("the clock is not frozen") when it means "you named the parameter wrong". That is a
+        // false NEGATIVE the caller cannot detect from the reply, in every tool at once.
+        const unknown = unknownKeys(args, allowedKeys.get(toolName));
+        if (unknown.length > 0) {
+            const example = examples.get(toolName);
+            throw new McpError(ErrorCode.InvalidParams, `Unknown ${unknown.length === 1 ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
+                `They were NOT applied — a result computed without them would look like an answer. ` +
+                (example === undefined
+                    ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
+                    : `A valid call looks like: ${toolName} ${example}`));
+        }
+        try {
+            return await original.call(server, tool, args, toolName);
+        }
+        catch (error) {
+            // McpError.message already carries "MCP error -32602: "; re-wrapping would print it twice.
+            const raw = error instanceof Error ? error.message : String(error);
+            const detail = raw.replace(/^MCP error -?\d+:\s*/, '');
+            const example = examples.get(toolName);
+            const help = example === undefined
+                ? ` Call reticle_tools { names: ["${toolName}"] } for its parameters.`
+                : ` A valid call looks like: ${toolName} ${example}`;
+            throw new McpError(ErrorCode.InvalidParams, `${detail}${help}`);
+        }
+    };
+}
 export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     const server = new McpServer(SERVER_INFO);
+    // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
+    // hook rather than read here: the handshake has not happened yet at construction time, and a
+    // feedback report filed twenty tool calls later is exactly when we want the answer.
+    setMcpClientNameHook(() => {
+        const info = server.server.getClientVersion();
+        // Record it as a side effect of the first read so the session summary can report WHICH agents
+        // drove this daemon — the multi-agent story, visible without a second plumbing path.
+        if (info?.name !== undefined)
+            getSessionMetrics().recordClient(info.name);
+        return info === undefined ? undefined : { name: info.name, version: info.version };
+    });
     // Cast once to our bridge type so every per-tool call site is typed without `any`.
     const registerTool = server.registerTool.bind(server);
     // `dynamic` advertises only the 2 meta-tools (reticle_tools + reticle_run); real tools load on demand.
@@ -126,9 +253,12 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     // reticle_flow_save's own description instructs the agent to call. `full` advertises everything
     // directly and needs no hatch.
     const advertised = advertisedTools(profile);
-    const terse = profile === TOOL_PROFILE.CORE ||
-        profile === TOOL_PROFILE.STANDARD ||
-        profile === TOOL_PROFILE.HYBRID;
+    installFriendlyArgErrors(server, new Map(advertised
+        .filter((tool) => tool.example !== undefined)
+        .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
+    // Every tool in TOOLS, not just the advertised ones: reticle_run dispatches to the full table,
+    // so an unadvertised tool reached through the hatch must be just as strict.
+    new Map(TOOLS.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
     for (const tool of advertised) {
         // Output schemas are now the largest slice of the per-request tax (55.6% of the hybrid payload
         // after the predicate fix) and we are the only one of the three MCP servers that sends them.
@@ -150,12 +280,7 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
         // handler below is unchanged, so `full`/`dynamic` (non-terse) keep the schema for validating
         // clients. This removes the single largest remaining slice of the per-request tax (~36% of the
         // hybrid payload) with no loss the agent can observe.
-        const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
-        const config = {
-            description: terse ? firstSentence(tool.description) : tool.description,
-            inputSchema: terse ? leanZodShape(tool.inputSchema) : tool.inputSchema,
-            ...(outputSchema !== undefined ? { outputSchema } : {}),
-        };
+        const config = advertisedConfig(tool, advertised, profile);
         registerTool(tool.name, config, async (args) => {
             try {
                 const result = await runTool(tool, deps, args);
@@ -171,6 +296,10 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 log('tool_error', { tool: tool.name, error: message });
+                // Counted by FINGERPRINT, never by message — see error-fingerprint.ts. This is the single
+                // boundary every agent-visible tool failure crosses, so it is the one place "which error is
+                // hurting people most" can be answered without instrumenting every handler.
+                getSessionMetrics().recordToolError(message, tool.name);
                 // Every error the agent hits should answer "what next?", not just "what broke".
                 return {
                     isError: true,
@@ -181,4 +310,3 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     }
     return server;
 }
-//# sourceMappingURL=mcp.js.map

package/dist/oracles/flow-instrument-gaps.d.ts

@@ -16,4 +16,3 @@ export declare function lastSource(steps: readonly FlowStep[]): {
  * source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
  */
 export declare function instrumentationGapsForFlows(unassertedFlows: readonly string[], flowStepsByName: ReadonlyMap<string, readonly FlowStep[]>): InstrumentationGap[];
-//# sourceMappingURL=flow-instrument-gaps.d.ts.map

package/dist/oracles/flow-instrument-gaps.js

@@ -42,4 +42,3 @@ export function instrumentationGapsForFlows(unassertedFlows, flowStepsByName) {
     }
     return gaps;
 }
-//# sourceMappingURL=flow-instrument-gaps.js.map

package/dist/oracles/propose-consequences.d.ts

@@ -19,4 +19,3 @@ export interface ProposedConsequence {
 }
 /** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
 export declare function proposeConsequences(events: readonly ReticleEvent[]): ProposedConsequence[];
-//# sourceMappingURL=propose-consequences.d.ts.map

package/dist/oracles/propose-consequences.js

@@ -90,4 +90,3 @@ export function proposeConsequences(events) {
     }
     return proposals.sort((a, b) => a.tier - b.tier);
 }
-//# sourceMappingURL=propose-consequences.js.map

package/dist/oracles/self-instrument.d.ts

@@ -29,4 +29,3 @@ export interface InstrumentationProposal {
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
 export declare function proposeInstrumentation(gaps: readonly InstrumentationGap[]): InstrumentationProposal[];
-//# sourceMappingURL=self-instrument.d.ts.map

package/dist/oracles/self-instrument.js

@@ -41,4 +41,3 @@ export function proposeInstrumentation(gaps) {
         rationale: rationaleFor(gap),
     }));
 }
-//# sourceMappingURL=self-instrument.js.map

package/dist/pairing-token.d.ts

@@ -25,4 +25,3 @@ export declare function nodePairingTokenDeps(): PairingTokenDeps;
  * fails, so the caller degrades to the prior tokenless behavior rather than bricking the daemon.
  */
 export declare function readOrCreatePairingToken(dir: string, deps: PairingTokenDeps): Promise<string | undefined>;
-//# sourceMappingURL=pairing-token.d.ts.map

package/dist/pairing-token.js

@@ -59,4 +59,3 @@ export async function readOrCreatePairingToken(dir, deps) {
         return undefined;
     }
 }
-//# sourceMappingURL=pairing-token.js.map

package/dist/phenomena/phenomena.d.ts

@@ -24,4 +24,3 @@ export declare function detectPreHydrationClicks(events: readonly ReticleEvent[]
 export declare function detectSwallowedErrors(events: readonly ReticleEvent[]): Finding[];
 /** Run every journal-only matcher over a session's events + actions. */
 export declare function detectPhenomena(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
-//# sourceMappingURL=phenomena.d.ts.map

package/dist/phenomena/phenomena.js

@@ -99,4 +99,3 @@ export function detectPhenomena(events, actions) {
         ...detectSwallowedErrors(events),
     ];
 }
-//# sourceMappingURL=phenomena.js.map

package/dist/pool/browser-pool.d.ts

@@ -89,4 +89,3 @@ export declare class BrowserPool {
     shutdown(): Promise<void>;
 }
 export {};
-//# sourceMappingURL=browser-pool.d.ts.map

package/dist/pool/browser-pool.js

@@ -236,4 +236,3 @@ export class BrowserPool {
             waiter(); // let them re-claim + relaunch
     }
 }
-//# sourceMappingURL=browser-pool.js.map

package/dist/pool/lease-reaper.d.ts

@@ -13,4 +13,3 @@ export declare class LeaseReaper {
     start(): void;
     stop(): void;
 }
-//# sourceMappingURL=lease-reaper.d.ts.map

package/dist/pool/lease-reaper.js

@@ -38,4 +38,3 @@ export class LeaseReaper {
         this.#timer = undefined;
     }
 }
-//# sourceMappingURL=lease-reaper.js.map

package/dist/pool/playwright-launcher.d.ts

@@ -6,6 +6,8 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import type { Launcher } from './browser-pool.js';
+/** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
+export declare const CHROMIUM_MISSING_HINT = "Chromium is not installed for Playwright. Run: npx playwright install chromium";
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export declare function playwrightLauncher(opts?: {
     headless?: boolean;
@@ -16,4 +18,3 @@ export declare function playwrightLauncher(opts?: {
  * Pure (env value + cpu count passed in) so it's testable.
  */
 export declare function resolveMaxContexts(envValue: string | undefined, cpuCount: number): number;
-//# sourceMappingURL=playwright-launcher.d.ts.map

package/dist/pool/playwright-launcher.js

@@ -5,6 +5,9 @@
  *
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
+import { BrowserLaunchKind } from '@reticlehq/core';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
@@ -26,6 +29,8 @@ function wrapBrowser(browser) {
         onDisconnected: (handler) => browser.on('disconnected', handler),
     };
 }
+/** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
+export const CHROMIUM_MISSING_HINT = 'Chromium is not installed for Playwright. Run: npx playwright install chromium';
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export function playwrightLauncher(opts = {}) {
     const headless = opts.headless ?? true;
@@ -36,7 +41,23 @@ export function playwrightLauncher(opts = {}) {
     // (where it's meaningful) instead of at import-time (where it kills unrelated features).
     return async () => {
         const { chromium } = await import('playwright');
-        return wrapBrowser(await chromium.launch({ headless }));
+        // A pooled launch serves N parallel leases, so this counts BROWSERS, not contexts — which is the
+        // number that actually costs memory and the one that explains a slow machine.
+        const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
+        try {
+            const browser = wrapBrowser(await chromium.launch({ headless }));
+            settle();
+            return browser;
+        }
+        catch (err) {
+            settle(classifyConnectFailure(err));
+            // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
+                throw new Error(CHROMIUM_MISSING_HINT);
+            }
+            throw err;
+        }
     };
 }
 const MAX_CONTEXTS_CEILING = 8;
@@ -62,4 +83,3 @@ export function resolveMaxContexts(envValue, cpuCount) {
     const byCpu = Math.max(MAX_CONTEXTS_FLOOR, cpuCount - 1);
     return Math.min(MAX_CONTEXTS_CEILING, byCpu);
 }
-//# sourceMappingURL=playwright-launcher.js.map

package/dist/project/baselines.d.ts

@@ -19,4 +19,3 @@ export declare class BaselineStore {
     list(): string[];
 }
 export {};
-//# sourceMappingURL=baselines.d.ts.map

package/dist/project/baselines.js

@@ -1,9 +1,11 @@
 /** Strip volatile ref ids so snapshots compare by semantics, not by ref number. */
 export function normalizeLines(tree) {
-    return tree
+    return (tree
         .split('\n')
-        .map((line) => line.replace(/\s*\(ref=e\d+\)/, '').trim())
-        .filter((line) => line.length > 0);
+        // The separator before a ref marker is a single space; a bounded quantifier keeps this linear
+        // (an unbounded `\s*` here backtracks polynomially on a long whitespace run — a needless ReDoS).
+        .map((line) => line.replace(/\s?\(ref=e\d+\)/, '').trim())
+        .filter((line) => line.length > 0));
 }
 function frequency(lines) {
     const map = new Map();
@@ -42,4 +44,3 @@ export class BaselineStore {
         return [...this.#map.keys()];
     }
 }
-//# sourceMappingURL=baselines.js.map

package/dist/project/file-lock.d.ts

@@ -1,2 +1,3 @@
 export declare function withFileLock<T>(path: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=file-lock.d.ts.map
+/** Exposed for testing — returns the number of active chain entries. */
+export declare function chainSize(): number;

package/dist/project/file-lock.js

@@ -18,7 +18,17 @@ export function withFileLock(path, fn) {
     // Run after the previous holder settles, regardless of whether it resolved or rejected.
     const run = prev.then(fn, fn);
     // Keep the chain alive but swallow the outcome so one task's rejection never rejects the next waiter.
-    chains.set(path, run.then(() => undefined, () => undefined));
+    const settled = run.then(() => undefined, () => undefined);
+    chains.set(path, settled);
+    // Reclaim the entry once settled IF no successor queued behind us (the Map still points to our
+    // promise). Without this, every unique path leaks a Map slot for the daemon's lifetime.
+    void settled.then(() => {
+        if (chains.get(path) === settled)
+            chains.delete(path);
+    });
     return run;
 }
-//# sourceMappingURL=file-lock.js.map
+/** Exposed for testing — returns the number of active chain entries. */
+export function chainSize() {
+    return chains.size;
+}

package/dist/project/fs-port.d.ts

@@ -42,4 +42,3 @@ export interface FileSystemPort {
 }
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export declare function createNodeFileSystem(): FileSystemPort;
-//# sourceMappingURL=fs-port.d.ts.map

package/dist/project/fs-port.js

@@ -51,4 +51,3 @@ export function createNodeFileSystem() {
         isNotFound: (error) => error?.code === 'ENOENT',
     };
 }
-//# sourceMappingURL=fs-port.js.map

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

@@ -29,4 +29,3 @@ export declare class ProjectStore {
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }
-//# sourceMappingURL=project-store.d.ts.map

package/dist/project/project-store.js

@@ -110,24 +110,35 @@ function serializeLearned(learned) {
     };
 }
 /**
- * Keep at most PER_NAME most-recent runs of any single name, then cap the whole list to TOTAL
- * most-recent overall. Chronological order (oldest→newest) is preserved throughout.
+ * Cap project memory while GUARANTEEING each flow keeps its last-known-good. Pass 1 reserves the
+ * most-recent run of every distinct name (never evicted by the TOTAL cap), so a fresh session can always
+ * answer "did my last run of this flow pass?" locally — the durable, free regression memory the solo
+ * loop needs. Pass 2 fills the remaining budget with additional recent runs (PER_NAME per name, TOTAL
+ * overall). Chronological order (oldest→newest) is preserved.
  */
 function truncate(runs) {
     const perName = new Map();
-    const keptReversed = [];
+    const kept = new Set();
+    // Pass 1 (newest→oldest): reserve each name's latest run. Kept regardless of the TOTAL cap.
+    const seen = new Set();
     for (let i = runs.length - 1; i >= 0; i -= 1) {
         const run = runs[i];
-        if (run === undefined)
+        if (run === undefined || seen.has(run.name))
+            continue;
+        seen.add(run.name);
+        kept.add(i);
+        perName.set(run.name, 1);
+    }
+    // Pass 2 (newest→oldest): fill the rest with extra recent runs, respecting PER_NAME and TOTAL.
+    for (let i = runs.length - 1; i >= 0 && kept.size < PROJECT_RUN_CAP.TOTAL; i -= 1) {
+        const run = runs[i];
+        if (run === undefined || kept.has(i))
             continue;
         const count = perName.get(run.name) ?? 0;
         if (count >= PROJECT_RUN_CAP.PER_NAME)
             continue;
         perName.set(run.name, count + 1);
-        keptReversed.push(run);
-        if (keptReversed.length >= PROJECT_RUN_CAP.TOTAL)
-            break;
+        kept.add(i);
     }
-    return keptReversed.reverse();
+    return runs.filter((_, i) => kept.has(i));
 }
-//# sourceMappingURL=project-store.js.map

package/dist/project/project-tools.d.ts

@@ -1,3 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
 export declare const PROJECT_TOOLS: ToolDef[];
-//# sourceMappingURL=project-tools.d.ts.map