@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/unadvertised-help.js

@@ -0,0 +1,60 @@
+/**
+ * What to say when an agent calls a real Reticle tool that this profile does not advertise.
+ *
+ * The default surface is the verify loop plus the two meta-tools; the extended one is larger but
+ * still capped. Counts live in `surface-sizes.test.ts` — restating them here is how they drift.
+ * Everything omitted stays fully callable through `reticle_run`, which `surface-reachability.test.ts`
+ * guards.
+ *
+ * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
+ * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real
+ * sweep of a Next app-router project: the first pass scored 25 failures that were nothing of the
+ * kind — every one of those tools worked through `reticle_run` seconds later.
+ *
+ * So: a name Reticle owns never comes back as "not found". It comes back with the call that works
+ * and the switch that makes it stop being necessary.
+ */
+import { ReticleTool } from '@reticlehq/core';
+import { ADVERTISE_ALL_ENV } from './tool-surface.js';
+import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
+/**
+ * Guidance for `name`, or undefined when there is nothing useful to add — the tool IS advertised (so
+ * any error belongs to the call itself), or the name is not ours to explain.
+ */
+export function unadvertisedToolHelp(name, advertised, known) {
+    if (advertised.has(name))
+        return undefined;
+    // A name that MOVED gets the move, not a profile lecture — it is not un-advertised, it is gone.
+    const moved = mergedNameRedirect(name);
+    if (moved !== undefined)
+        return mergedNameMessage(name, moved, advertised.has(moved.tool));
+    if (!known.has(name))
+        return undefined;
+    /*
+     * The hatch is not on every profile, and advice that names a tool this surface does not have is
+     * the very failure this file exists to prevent.
+     *
+     * On the MERGED surface — a daemon started without the env below — `reticle_run` is un-advertised
+     * too, and `reticle_tools` states plainly that "there is no hidden tail and no dispatch hatch to
+     * reach one". Measured against a live daemon: `reticle_baseline` answered "invoke it with
+     * reticle_run", and `reticle_run` answered "Tool reticle_run not found". The one message whose
+     * whole job is to stop an agent concluding "this does not exist" spent its turn proving it.
+     */
+    if (!advertised.has(ReticleTool.RUN)) {
+        return (`${name} exists in this build but is not reachable on this tool surface, which advertises the ` +
+            `verify loop and nothing else — there is no dispatch tool here to route through. It is NOT a ` +
+            `missing feature and NOT a retired name. To use it, start the daemon with ` +
+            `${ADVERTISE_ALL_ENV}=1, which advertises the wider surface including ${name}; the daemon reads ` +
+            `that at startup, so it takes effect on the next one. Until then, prefer what this surface ` +
+            `does advertise — ${ReticleTool.TOOLS} {} lists it.`);
+    }
+    return (`${name} exists and works, but is not advertised under this tool profile — the schemas for all ` +
+        `tools are re-sent every turn, so the default advertises a subset and keeps the rest one call ` +
+        `away. It is NOT missing: invoke it with ` +
+        `${ReticleTool.RUN} { tool: "${name}", args: { ... } }. ` +
+        `Call ${ReticleTool.TOOLS} { names: ["${name}"] } for its parameters. ` +
+        `If you need it repeatedly, start the daemon with ${ADVERTISE_ALL_ENV}=1 for the extended ` +
+        `surface. That is read by the DAEMON at startup, so it takes effect on the next daemon, and it ` +
+        `advertises MORE tools rather than all of them — editors budget MCP tools as a shared count, so ` +
+        `${ReticleTool.RUN} stays the way to reach the rest.`);
+}

package/dist/surface/tools/verify-next-baton.js

@@ -0,0 +1,52 @@
+/**
+ * The verdict nudge, as a call the agent can make rather than a sentence it has to translate.
+ *
+ * `verify_next` already fires when an agent has driven the page several times and asked for no
+ * verdict, which is the commonest shape of a wasted session: almost every verdict-less session in
+ * the field never called a verdict-producing tool once. What it carried was prose. Prose has to be
+ * turned back into a call, and the translation is exactly where the agent was already going wrong —
+ * `until` omitted, arguments flat instead of nested under `args`, a predicate written as a bare
+ * array.
+ *
+ * So it carries the call. `ref` and `action` come from the act that actually dispatched, so the
+ * suggestion is about the element the agent really touched rather than a worked example from a
+ * document. `until` is deliberately left as a placeholder the agent must replace: naming the
+ * consequence is the one part nothing but the agent can know, and filling it in with a guess would
+ * be Reticle inventing the assertion — the failure `no-fault` exists to prevent.
+ *
+ * Emitted only when there is a real call to suggest. A baton with nothing behind it is the router
+ * failure in miniature: an agent that follows a fabricated next step follows it confidently.
+ */
+import { ReticleTool } from '@reticlehq/core';
+/**
+ * Set to `1` to withhold the baton from tool results — the control arm of its A/B, and nothing else.
+ *
+ * A measurement flag, not a product setting: it is read at one call site, documented here, and named
+ * loudly enough that nobody sets it by accident. It exists because this feature has shipped, been
+ * declared the largest lever on whether a session verifies at all, and never been measured — and a
+ * control arm is the only way to tell "agents that see it verify" from "agents that were going to
+ * verify anyway also saw it".
+ */
+export const SUPPRESS_VERIFY_NEXT_ENV = 'RETICLE_SUPPRESS_VERIFY_NEXT';
+/** What the agent must supply itself. Phrased as an instruction so it cannot be sent verbatim. */
+export const UNTIL_PLACEHOLDER = '<name the consequence this action causes>';
+/**
+ * Build the baton from what the session actually did.
+ *
+ * `ref` absent means no act dispatched under a ref this session — a navigation, or a run that only
+ * read. There is then no honest call to name, so the prose stands alone rather than pointing at an
+ * element nobody touched.
+ */
+export function verifyNextBaton(prose, lastAct) {
+    const { ref, action } = lastAct;
+    if (ref === undefined || action === undefined)
+        return { why: prose };
+    return {
+        why: prose,
+        call: {
+            tool: ReticleTool.ACT_AND_WAIT,
+            args: { ref, action, until: { kind: 'text', value: UNTIL_PLACEHOLDER } },
+        },
+        docs: `reticle_tools { names: ["${ReticleTool.ACT_AND_WAIT}"] }`,
+    };
+}

package/dist/telemetry/app-instrumented.d.ts

@@ -1,11 +1,9 @@
 /**
  * When an app carrying the SDK first reaches this daemon.
  *
- * This is the step the whole funnel turns on, and the one nothing could measure. Registering the MCP
- * server and instrumenting an app are separate acts, done by different commands, and the data says
- * almost everybody does the first and almost nobody does the second — but proving that required
- * inferring it from a window counter that resets on every flush, and which therefore reported fewer
- * instrumented users than there were users calling tools.
+ * Registering the MCP server and instrumenting an app are separate acts, done by different commands.
+ * This event marks the second one. It must not be inferred from a window counter, which resets on
+ * every flush and so reports fewer instrumented installs than there are installs calling tools.
  *
  * Once per daemon run, on the FIRST app connect only. A page that reloads, or an app that opens five
  * tabs, must not read as five instrumented installs — the question is "did this install ever get an

package/dist/telemetry/app-instrumented.js

@@ -1,11 +1,9 @@
 /**
  * When an app carrying the SDK first reaches this daemon.
  *
- * This is the step the whole funnel turns on, and the one nothing could measure. Registering the MCP
- * server and instrumenting an app are separate acts, done by different commands, and the data says
- * almost everybody does the first and almost nobody does the second — but proving that required
- * inferring it from a window counter that resets on every flush, and which therefore reported fewer
- * instrumented users than there were users calling tools.
+ * Registering the MCP server and instrumenting an app are separate acts, done by different commands.
+ * This event marks the second one. It must not be inferred from a window counter, which resets on
+ * every flush and so reports fewer instrumented installs than there are installs calling tools.
  *
  * Once per daemon run, on the FIRST app connect only. A page that reloads, or an app that opens five
  * tabs, must not read as five instrumented installs — the question is "did this install ever get an
@@ -15,8 +13,9 @@
  * project path, the URL, or anything from the page. The stack is deliberately NOT repeated here;
  * `project_profiled` already carries it on the same daemon run, so the two join on sessionId.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, OnboardingStepStatus, TelemetryEventKind, } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
+import { reportOnboardingStep } from './onboarding-funnel.js';
 let reported = false;
 /** Set at daemon start so the first connect can report how long the install sat un-instrumented. */
 let daemonStartedAt;
@@ -42,6 +41,18 @@ export function reportAppInstrumented(facts, now = () => Date.now()) {
                 msToFirstApp: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
             },
         });
+        // The same fact, as an ordered step rather than a once-per-run flag, so it sits in the same
+        // series as the steps either side of it. Reported here, at the one site that already knows,
+        // rather than by a second listener that could drift from it.
+        //
+        // `instrumented` means files were written; THIS means a page actually dialled the bridge. Every
+        // silent install bug so far has lived in the gap between those two.
+        void reportOnboardingStep({
+            phase: OnboardingPhase.FIRST_RUN,
+            step: 'app_connected',
+            status: OnboardingStepStatus.COMPLETED,
+            ...(daemonStartedAt === undefined ? {} : { elapsedMs: Math.max(0, now() - daemonStartedAt) }),
+        });
     }
     catch {
         /* never let a metric interfere with a page connecting */

package/dist/telemetry/argument-shape.js

@@ -60,10 +60,10 @@ export function describeParam(name, value) {
 /**
  * Parameters that carry no information about how the tool is USED, and so are not counted.
  *
- * `sessionId` is accepted by nearly every tool and passed on nearly every call, so counting it
- * produced a row per tool saying only "the agent addressed a session" — in one real day's export it
- * was a third of the toolParams block. This histogram exists to answer "is anyone using the argument
- * we shipped last release", and a parameter every call carries can never answer it.
+ * `sessionId` is accepted by nearly every tool and passed on nearly every call, so counting it adds
+ * a row per tool saying only "the agent addressed a session", for a large share of the whole
+ * `toolParams` block. This histogram exists to answer "is anyone using the argument shipped last
+ * release", and a parameter every call carries can never answer it.
  */
 const UNINFORMATIVE_PARAMS = new Set(['sessionId']);
 /** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */

package/dist/telemetry/bug-found.js

@@ -2,8 +2,7 @@
  * Counting the defects Reticle actually finds.
  *
  * Every other metric in this product measures whether Reticle is USED. This one measures whether it
- * WORKS — and it is the only number that can honestly be put in front of an investor or published,
- * because it counts outcomes for users rather than activity by them.
+ * WORKS, because it counts outcomes rather than activity.
  *
  * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
  * emitted from the four places that produce findings. That is deliberate: the detectors are pure
@@ -15,10 +14,16 @@
  * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
  * anyone's app: that a class of defect was found, never what it was found in.
  */
-import { ReticleTool } from '../tools/tool-names.js';
+import { ReticleTool } from '@reticlehq/core';
 import { BugAttribution, BugSource, ContradictionKind, isAbsenceDerived, } from '@reticlehq/core';
 /** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
 const MAX_BUGS_PER_CALL = 25;
+/** The kinds in a replay's `regressed` list — bare strings, not the `{ kind }` objects above. */
+function regressedKinds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((kind) => 'string' === typeof kind && kind.length > 0);
+}
 function kindsOf(value) {
     if (!Array.isArray(value))
         return [];
@@ -33,18 +38,16 @@ function kindsOf(value) {
  * The defects in one tool result.
  *
  * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
- * the case the product exists for — the screen looked right, the write failed, and every other tool
- * on the market would have called it green. That pairing is what `falseGreen` marks.
+ * the case the product exists for — the screen looked right and the write failed. That pairing is
+ * what `falseGreen` marks.
  */
 /**
  * The verdict this result carries, whatever envelope it arrived in.
  *
- * `reticle_assert` reports a top-level boolean `pass`. `reticle_act_and_wait` — the tool agents
- * actually reach for, and the one whose description calls it the act->observe->assert loop — reports
- * `verdict.pass` with the summary at `verified`. Reading only `result.pass` meant a FAILED
- * act_and_wait produced no bug at all, and a contradiction found next to a PASSING one was recorded
- * with `falseGreen: false` — deflating the single number this product exists to publish, by the
- * shape of its own envelope.
+ * `reticle_assert` reports a top-level boolean `pass`. `reticle_act_and_wait` reports `verdict.pass`
+ * with the summary at `verified`. Both shapes have to be read: taking only `result.pass` means a
+ * FAILED act_and_wait produces no bug at all, and a contradiction found next to a PASSING one is
+ * recorded with `falseGreen: false`.
  */
 function verdictOf(result) {
     if ('boolean' === typeof result['pass'])
@@ -92,21 +95,16 @@ function couldNotRun(failure) {
 /**
  * WHOSE fault a contradiction was.
  *
- * `attribution` shipped twice and was wrong both times. It stamped `app` on every contradiction,
- * including `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a
- * dev-overlay poll manufactured it with the app doing nothing wrong. Across two full real drives
- * EVERY `attribution: 'app'` was a misattribution, while the one defect that genuinely was a bad
- * agent predicate carried none. A metric confidently wrong about whose fault a defect is, is worse
- * than no metric: it is the number a founder steers on, and it points at the customer.
+ * A metric that is confidently wrong about fault is worse than no metric. Stamping `app` on every
+ * contradiction is wrong: `request-never-settled` is raised from the ABSENCE of a settle event, so a
+ * dev-overlay poll manufactures one with the app doing nothing wrong.
  *
- * The evidence that was missing then exists now, and it is already drawn in core for the verdict:
- * `ABSENCE_DERIVED_CONTRADICTIONS` separates the kinds inferred from something NOT having happened
- * inside a window Reticle chose the end of, from the kinds positively OBSERVED — a request that came
- * back failed, a signal the app fired that disagrees with its own screen, a written field echoed
- * back changed. Only the second class is evidence against the app, and it is the same line that
- * decides whether a verdict may say `no`. Reusing it rather than inventing a second judgement beside
- * it is the whole point: every historical misattribution was an absence-derived kind, so this rule
- * produces zero of them on the data that broke the last two versions.
+ * The line that decides is already drawn in core for the verdict. `ABSENCE_DERIVED_CONTRADICTIONS`
+ * separates the kinds inferred from something NOT having happened inside a window Reticle chose the
+ * end of, from the kinds positively OBSERVED — a request that came back failed, a signal the app
+ * fired that disagrees with its own screen, a written field echoed back changed. Only the second
+ * class is evidence against the app, and it is the same line that decides whether a verdict may say
+ * `no`. Reusing it rather than inventing a second judgement beside it is the point.
  *
  * Everything else — a failed assertion, a replay regression, a crawl anomaly that is not a
  * contradiction — is `unclassified`, which is a VALUE and not a gap. A failed `element.present`
@@ -135,7 +133,12 @@ export function bugsInResult(toolName, result) {
     const verdict = verdictOf(result);
     const passed = true === verdict;
     // 1. Contradictions — channels disagreeing. Invisible to a human watching the screen.
-    for (const kind of kindsOf(result['contradictions'])) {
+    //
+    // `crossStep` is read alongside `contradictions` because a flow replay spells them that way: a
+    // step's window closes when the step ends, so a request fired at step 2 and still unanswered at
+    // step 5 sits outside every per-step window and is exactly the shape a long journey produces.
+    // Every whole-span contradiction a replay found was unreportable for want of this one name.
+    for (const kind of [...kindsOf(result['contradictions']), ...kindsOf(result['crossStep'])]) {
         // A contradiction is two of the APP's own channels disagreeing — never the agent's phrasing.
         // Omitted for the one kind Reticle can produce on its own: see contradictionAttribution.
         bugs.push({
@@ -184,7 +187,26 @@ export function bugsInResult(toolName, result) {
             attribution: BugAttribution.UNCLASSIFIED,
         });
     }
-    // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
+    // 4. A guarded defect that came BACK. The flow observed it, then observed it gone, and the app
+    //    has now reacquired it — a claim no other detector in this file can make, because only a saved
+    //    flow carries what it has already seen. It is the replay feature's stated payoff and it was
+    //    counted nowhere: `regressed` is a list of KINDS, not of anomaly objects, so neither of the
+    //    array readers above could see it.
+    for (const kind of regressedKinds(result['regressed'])) {
+        bugs.push({
+            source: BugSource.REPLAY,
+            kind,
+            // The replay carries no assertion of its own, so there is no green for this to have hidden
+            // behind. Whether it was a false green is a question about the run that reacquired the defect,
+            // not about the run that noticed.
+            falseGreen: passed,
+            tool: toolName,
+            // Same kind, same owner, wherever it arrives — the line `attributionOf` draws is the one the
+            // verdict already uses, and a defect does not change whose fault it was by coming back.
+            attribution: attributionOf(kind),
+        });
+    }
+    // 5. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
     //    which is a different and stronger claim than "a check failed".
     if ('fail' === result['status'] && Array.isArray(result['failures'])) {
         for (const failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {

package/dist/telemetry/cli-telemetry.js

@@ -5,8 +5,13 @@
  * next to the explanation of why it exists rather than buried in a startup function.
  */
 import { TelemetryEventKind } from '@reticlehq/core/telemetry';
-import { DAEMON_INNER_COMMAND, knownCommand } from '../cli/cli-parse.js';
+import { DAEMON_INNER_COMMAND, knownCommand } from '../command/cli/cli-parse.js';
 import { getTelemetry } from './telemetry.js';
+import { drainInstallTrace } from './install-trace.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Where the installer left its breadcrumbs. Same directory the telemetry id and opt-out live in. */
+const RETICLE_STATE_DIR = process.env['RETICLE_STATE_DIR'] ?? join(homedir(), '.reticle');
 import { describeCliFlags } from './argument-shape.js';
 import { resolveInstallSource } from './install-source.js';
 /**
@@ -23,9 +28,9 @@ import { resolveInstallSource } from './install-source.js';
  */
 /**
  * The agent's MCP transport, not a person. `reticle mcp` is what an MCP client runs to open a stdio
- * connection — nobody types it. Measured over one real day it was 475 of 561 `cli_command_run`
- * events (85%), on an event whose whole purpose is human intent, and the agent attaching is already
- * reported by `mcp_client_connected` with strictly more detail (reconnect, daemon age, client).
+ * connection — nobody types it. Counted, it dominates an event whose whole purpose is human intent,
+ * and the agent attaching is already reported by `mcp_client_connected` with strictly more detail
+ * (reconnect, daemon age, client).
  *
  * `serve` is NOT excluded: nothing spawns it on a person's behalf, so typing it is a real act.
  */
@@ -36,14 +41,26 @@ export function isHumanCliCommand(command) {
 }
 export function reportCliRun(argv) {
     const firstArg = argv[0];
+    /*
+     * BEFORE the `_daemon` filter, deliberately.
+     *
+     * The installer's breadcrumbs have to be drained on the very next invocation whatever it is, and
+     * on most machines that is the agent spawning `reticle mcp`, which starts a daemon. Draining
+     * after the filter would leave the file sitting until somebody happened to run a human command —
+     * which on an agent-driven machine may be never.
+     *
+     * Idempotent by deletion rather than by a flag: the file is gone after the first drain, so a
+     * second invocation finds nothing. A flag would have to live somewhere, and somewhere is another
+     * file that can disagree with this one.
+     */
+    drainInstallTrace(RETICLE_STATE_DIR);
     if (firstArg === DAEMON_INNER_COMMAND)
         return;
     const command = knownCommand(firstArg);
     const telemetry = getTelemetry();
     // FIRST — before the human-command filter. The install happened whichever command ran, and on most
     // machines the very first contact is the agent spawning `reticle mcp`, which that filter excludes.
-    // Measured over one sweep: 15 `init_completed` and ZERO `reticle_installed`, in a run that
-    // installed the SDK into nine apps — the top of every funnel, missing.
+    // Behind the filter this event never fires at all on an install that only ever runs `reticle mcp`.
     // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
     if (telemetry.firstRun)
         void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, {
@@ -56,10 +73,10 @@ export function reportCliRun(argv) {
         return;
     void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {
         detach: true,
-        // No `actor`: with the agent's transport excluded, this event is human BY DEFINITION. It was
-        // constant `human` on all 561 events in a real day — zero information, and wrong for the 475
-        // that were the agent. `actor` stays where it earns its place: verification_completed and
-        // bug_found, where it splits the agent's own loop from a human/CI-triggered run.
+        // No `actor`: with the agent's transport excluded, this event is human BY DEFINITION, so the
+        // field would be constant here — zero information. `actor` stays where it earns its place:
+        // verification_completed and bug_found, where it splits the agent's own loop from a human or
+        // CI-triggered run.
         // A fixed, low-cardinality vocabulary WE define, so it is safe to send whole and it is the closest
         // honest read we have on intent: `verify` and `gate` mean something very different from `status`.
         // An unrecognized first arg reports as `unknown` rather than being echoed — an echo would put

package/dist/telemetry/daemon-telemetry.d.ts

@@ -2,19 +2,16 @@
  * The daemon's telemetry lifecycle, in one place: start, the periodic flush that survives a kill, the
  * one-shot project profile, and the rich summary on shutdown.
  *
- * Extracted from `cli.ts` because it is a cohesive unit with its own timers and its own failure rule
- * (nothing here may ever be able to fail a daemon start), and because `cli.ts` is a dispatcher — the
- * more of this that lives there, the harder it is to see what a command actually does.
+ * It lives apart from `cli.ts` because it has its own timers and its own failure rule — nothing here
+ * may ever be able to fail a daemon start — and because `cli.ts` is a dispatcher.
  */
 import { type SessionSummary } from '@reticlehq/core/telemetry';
 /**
  * How often a running daemon rolls up its window.
  *
  * Exported because it is the BOUND ON WHAT IS LOST: a daemon that has served a tool never
- * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. At 30
- * minutes against a median 28-minute session that meant the median session reported nothing at all.
- * Only non-empty windows emit, so a shorter interval costs nothing on the 74% of daemons that never
- * serve a tool.
+ * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. Only
+ * non-empty windows emit, so a shorter interval costs nothing on a daemon that never serves a tool.
  */
 export declare const SESSION_FLUSH_MS: number;
 /**
@@ -24,15 +21,12 @@ export declare const SESSION_FLUSH_MS: number;
  * tick — a closed laptop, OOM, `kill -9`, a force-quit editor — reaches no shutdown handler and has
  * emitted nothing, so the whole session is invisible.
  *
- * In the field `daemon_started` outran `daemon_stopped` by a wide margin: **a meaningful share of
- * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed only
- * on the sessions that did, and undercounts by an unknown amount, which is the one thing a funnel
- * metric must not do.
+ * A session that never reports a summary is invisible, so every count computed over the sessions
+ * that did undercounts by an unknown amount.
  *
  * Ninety seconds is chosen against what it protects: a session that did real work usually does it
  * early (snapshot -> act -> assert is seconds), so one early tick captures nearly all of it. It
- * costs nothing on the daemons that dominate the population, because only a NON-EMPTY window emits
- * and 74% of daemons never serve a tool at all.
+ * costs nothing on a daemon that never serves a tool, because only a NON-EMPTY window emits.
  */
 export declare const FIRST_FLUSH_MS: number;
 /** Stops the timers this installed. Called from the daemon's shutdown path. */

package/dist/telemetry/daemon-telemetry.js

@@ -2,29 +2,27 @@
  * The daemon's telemetry lifecycle, in one place: start, the periodic flush that survives a kill, the
  * one-shot project profile, and the rich summary on shutdown.
  *
- * Extracted from `cli.ts` because it is a cohesive unit with its own timers and its own failure rule
- * (nothing here may ever be able to fail a daemon start), and because `cli.ts` is a dispatcher — the
- * more of this that lives there, the harder it is to see what a command actually does.
+ * It lives apart from `cli.ts` because it has its own timers and its own failure rule — nothing here
+ * may ever be able to fail a daemon start — and because `cli.ts` is a dispatcher.
  */
 import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
 import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
-import { hasProjectConnectedBefore } from '../session/connection-memory.js';
-import { readProjectId } from '../cli/cli-port.js';
-import { reticleStateHome } from '../daemon/daemon.js';
-import { startUpdateCheck, updateNudgeState } from '../update/update-nudge.js';
+import { hasProjectConnectedBefore } from '../memory/recall/prior/connection-memory.js';
+import { readProjectId } from '../command/cli/ports/resolve/cli-port.js';
+import { reticleStateHome } from '../command/daemon/daemon.js';
+import { startUpdateCheck, updateNudgeState } from '../command/update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
 import { markInstrumentationClock } from './app-instrumented.js';
-import { markStallClock, STALL_AFTER_MS, stallUptime } from '../session/stall-clock.js';
+import { markStallClock, STALL_AFTER_MS, stallUptime } from '../portal/session/stall-clock.js';
 /**
  * Whether an app for this project has ever reached Reticle, read from the same durable memory the
  * no-session diagnosis and the server instructions read.
  *
- * Best-effort: an unreadable state home must never be the reason a daemon start emits nothing, and
- * `undefined` here means "not measured" rather than "no". A `false` invented from a read error is
- * exactly the lie this field exists to avoid — it would put the working installs into the cohort we
- * are trying to size.
+ * Best-effort: an unreadable state home must never be the reason a daemon start emits nothing.
+ * `undefined` means "not measured"; a `false` invented from a read error would be wrong, not merely
+ * missing.
  */
 function installFacts(cwd, port) {
     if (port === undefined)
@@ -44,10 +42,8 @@ const PROJECT_PROFILE_DELAY_MS = 5_000;
  * How often a running daemon rolls up its window.
  *
  * Exported because it is the BOUND ON WHAT IS LOST: a daemon that has served a tool never
- * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. At 30
- * minutes against a median 28-minute session that meant the median session reported nothing at all.
- * Only non-empty windows emit, so a shorter interval costs nothing on the 74% of daemons that never
- * serve a tool.
+ * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. Only
+ * non-empty windows emit, so a shorter interval costs nothing on a daemon that never serves a tool.
  */
 export const SESSION_FLUSH_MS = 5 * 60 * 1000;
 /**
@@ -57,15 +53,12 @@ export const SESSION_FLUSH_MS = 5 * 60 * 1000;
  * tick — a closed laptop, OOM, `kill -9`, a force-quit editor — reaches no shutdown handler and has
  * emitted nothing, so the whole session is invisible.
  *
- * In the field `daemon_started` outran `daemon_stopped` by a wide margin: **a meaningful share of
- * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed only
- * on the sessions that did, and undercounts by an unknown amount, which is the one thing a funnel
- * metric must not do.
+ * A session that never reports a summary is invisible, so every count computed over the sessions
+ * that did undercounts by an unknown amount.
  *
  * Ninety seconds is chosen against what it protects: a session that did real work usually does it
  * early (snapshot -> act -> assert is seconds), so one early tick captures nearly all of it. It
- * costs nothing on the daemons that dominate the population, because only a NON-EMPTY window emits
- * and 74% of daemons never serve a tool at all.
+ * costs nothing on a daemon that never serves a tool, because only a NON-EMPTY window emits.
  */
 export const FIRST_FLUSH_MS = 90 * 1000;
 /**

package/dist/telemetry/error-fingerprint.js

@@ -46,9 +46,34 @@ const VARIABLE_PARTS = [
     /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, // uuids
     /\d+/g, // any remaining number — ports, counts, timeouts
 ];
+/**
+ * How much of a message is even looked at.
+ *
+ * ── THE DEFECT ──────────────────────────────────────────────────────────────────────────────────
+ * Several patterns above are polynomial-ReDoS shapes, and CodeQL flagged this function `high`:
+ * `[\w.+-]+@` is the clearest — on a long run of `+` with no `@` anywhere, the engine retries the
+ * `+` from every start position and rescans to the end each time, so the cost is quadratic in the
+ * length of the run. `(?:\/[\w.-]+){2,}` and the 24-plus-character secret catch-all have the same
+ * shape. The input is an error message, and an error message is the most attacker-influenceable
+ * string this daemon handles: it comes from the page under test, which is somebody's app.
+ *
+ * The cap is the fix rather than twelve rewritten regexes, because these patterns are a PRIVACY
+ * boundary. Rewriting each one to be provably linear risks changing what gets redacted, and a
+ * mistake there leaks a credential rather than costing milliseconds.
+ *
+ * Capping the INPUT cannot leak anything the old code did not, and that is what makes it safe: the
+ * output was already `.slice(0, 200)`, so everything past this bound was being discarded after
+ * being scanned. Now it is discarded without being scanned. 1024 is five times the output bound,
+ * which leaves ample room for the masking to shrink text before the 200 chars are taken.
+ *
+ * The wire caps an error at `MAX_ERROR_LENGTH` (4096) so the worst case was bounded already; this
+ * is about the paths that do not come off the wire, and about not relying on a limit set elsewhere
+ * for a reason unrelated to this one.
+ */
+const MAX_SKELETON_INPUT = 1024;
 /** The skeleton of a message: variable parts blanked, whitespace collapsed, length bounded. */
 export function errorSkeleton(message) {
-    let skeleton = message;
+    let skeleton = message.slice(0, MAX_SKELETON_INPUT);
     for (const pattern of VARIABLE_PARTS)
         skeleton = skeleton.replace(pattern, '*');
     return skeleton.replace(/\s+/g, ' ').trim().slice(0, 200);

package/dist/telemetry/feedback-cli.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryAction } from '../cli/cli-parse.js';
+import { TelemetryAction } from '../command/cli/cli-parse.js';
 /**
  * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.
  *

package/dist/telemetry/feedback-cli.js

@@ -1,8 +1,8 @@
 import { FeedbackKind, FeedbackSource } from '@reticlehq/core/telemetry';
-import { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG } from '../cli/cli-parse.js';
+import { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '../command/cli/cli-parse.js';
 import { describeFeedbackPayload, submitFeedback } from './feedback.js';
 import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
-import { TelemetryAction } from '../cli/cli-parse.js';
+import { TelemetryAction } from '../command/cli/cli-parse.js';
 import { clearIdentity, IDENTIFY_NOTICE, readIdentity, saveIdentity, submitIdentity, UsageContextKind, } from './identify.js';
 /**
  * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.

package/dist/telemetry/feedback-context.js

@@ -9,7 +9,7 @@
  * holds to. Detection is entirely best-effort: an unreadable package.json or an SDK too old to report
  * its runtime yields `undefined`, never a throw and never a guess.
  */
-import { mcpClientIdentity, setMcpClientIdentityHook } from '../mcp/client-identity.js';
+import { mcpClientIdentity, setMcpClientIdentityHook } from '../surface/mcp/peer/client-identity.js';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { AppRuntime, McpScope, PageDriver, StackUnknownReason, } from '@reticlehq/core/telemetry';
@@ -78,9 +78,9 @@ export function detectStack(cwd, read = readFile) {
     }
     // Otherwise look for the app. The daemon's cwd is wherever the agent's client happened to launch,
     // which for a real repo is the ROOT while the app sits in `frontend/`, `web/`, or a declared
-    // workspace. Reading one directory and giving up is why this returned nothing for every project
-    // that actually had Reticle set up: 0 of 77 instrumented projects, and 0 of 166 `size: huge` ones.
-    // The bigger the repo, the more certainly we failed.
+    // workspace. Reading one directory and giving up is why this returned nothing for essentially
+    // every project that actually had Reticle set up, and why the bigger the repo, the more certainly
+    // we failed. (The measurement that established that came from the field and stays in `plan/`.)
     //
     // `findWorkspaceApps` is init's discovery, reused rather than reimplemented: it already reads
     // declared workspaces (pnpm-workspace.yaml, package.json `workspaces`) AND scans top-level

package/dist/telemetry/feedback.js

@@ -27,7 +27,7 @@ import { getTelemetry } from './telemetry.js';
 import { noteFeedbackUndelivered } from './feedback-delivery.js';
 import { isReticleSourceCheckout } from './dev-repo.js';
 import { saveFeedbackLocally } from './feedback-local.js';
-import { SERVER_VERSION } from '../version/server-version.js';
+import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 import { feedbackContext } from './feedback-context.js';
 import { markDelivered, outboxPath, queueFeedback } from './feedback-outbox.js';
 /** Kills the feedback channel ONLY — adoption counters keep flowing. */

package/dist/telemetry/harness-drive.d.ts

@@ -0,0 +1,6 @@
+/** Run `drive` with every verdict underneath it attributed to the harness. */
+export declare function withHarnessDrive<T>(drive: () => Promise<T>): Promise<T>;
+/** True while a harness drive is in progress. */
+export declare function harnessDriving(): boolean;
+/** Tests only — a leaked span would mis-attribute every verdict after it. */
+export declare function resetHarnessDrive(): void;