@reticlehq/server 2.6.0 → 2.8.0

package/dist/session/ref-provenance.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which tab a ref came out of, so the call that spends it cannot be routed to a different one.
+ *
+ * Reported from the field: three tabs of one project were connected, a snapshot was taken against a
+ * named session, and the act that followed omitted `sessionId`. Auto-selection picked a different
+ * tab, the ref legitimately did not exist there, and the refusal read "that ref is stale: refs are
+ * invalidated whenever the DOM re-renders" — a confident diagnosis of the wrong thing, and one that
+ * accuses the app under test. The recovery text then sends the agent to re-snapshot, which mints a
+ * fresh ref in whichever tab is chosen next, so the lesson it teaches is wrong either way.
+ *
+ * The quiet outcome is the worse one. Refs are minted from a per-document block, so the same number
+ * is a real, live, DIFFERENT element in the tab that was guessed: the identical call on a luckier day
+ * drives the wrong tab and returns a green about a page nobody asked about. That is a false green
+ * with extra steps, and it is the failure class this product exists to remove.
+ *
+ * Every `sessionId` description on the surface already promises that Reticle "refuses rather than
+ * guesses when ambiguous". This is the fact that makes the ambiguity visible: the tab a ref was
+ * handed out of is known at the moment it is handed out. Resolution is otherwise untouched — a call
+ * that names a session, carries no ref, or lands on the tab it looked at resolves silently, which is
+ * the cost the surface wording was rewritten to avoid.
+ *
+ * ponytail: one slot, not a per-ref map. It answers the reported shape — look at one tab, act on
+ * what you saw — for the cost of an assignment. A drive that interleaves refs from several tabs
+ * inside one turn needs per-ref provenance, and that is the upgrade if it ever shows up.
+ */
+/** Record that a tool handed out refs from this session. */
+export declare function noteRefsMinted(sessionId: string): void;
+export declare function refsLastMintedIn(): string | undefined;
+/** Test seam: the module holds one slot for the process, so a test has to be able to clear it. */
+export declare function forgetRefProvenance(): void;
+interface RefRouting {
+    /** The ref this call is about to spend, if it carries one. */
+    ref: string | undefined;
+    /** The `sessionId` the CALLER passed — when present, nothing was guessed. */
+    explicitSessionId: string | undefined;
+    /** The session resolution actually picked. */
+    chosenSessionId: string;
+    /**
+     * The connected sessions, read ONLY once a refusal is certain. A thunk because listing them walks
+     * every session and builds a health block each time, and the answer is wanted on the rare path.
+     */
+    connected: () => readonly {
+        sessionId: string;
+        url: string;
+    }[];
+}
+/**
+ * The refusal for a ref that belongs to another tab, or undefined when there is no ambiguity.
+ *
+ * Silent when the minting tab is no longer connected: that ref really is dead, and the stale-ref
+ * refusal that already exists is the honest answer for it.
+ */
+export declare function wrongTabRefusal(routing: RefRouting): string | undefined;
+export {};

package/dist/session/ref-provenance.js

@@ -0,0 +1,61 @@
+/**
+ * Which tab a ref came out of, so the call that spends it cannot be routed to a different one.
+ *
+ * Reported from the field: three tabs of one project were connected, a snapshot was taken against a
+ * named session, and the act that followed omitted `sessionId`. Auto-selection picked a different
+ * tab, the ref legitimately did not exist there, and the refusal read "that ref is stale: refs are
+ * invalidated whenever the DOM re-renders" — a confident diagnosis of the wrong thing, and one that
+ * accuses the app under test. The recovery text then sends the agent to re-snapshot, which mints a
+ * fresh ref in whichever tab is chosen next, so the lesson it teaches is wrong either way.
+ *
+ * The quiet outcome is the worse one. Refs are minted from a per-document block, so the same number
+ * is a real, live, DIFFERENT element in the tab that was guessed: the identical call on a luckier day
+ * drives the wrong tab and returns a green about a page nobody asked about. That is a false green
+ * with extra steps, and it is the failure class this product exists to remove.
+ *
+ * Every `sessionId` description on the surface already promises that Reticle "refuses rather than
+ * guesses when ambiguous". This is the fact that makes the ambiguity visible: the tab a ref was
+ * handed out of is known at the moment it is handed out. Resolution is otherwise untouched — a call
+ * that names a session, carries no ref, or lands on the tab it looked at resolves silently, which is
+ * the cost the surface wording was rewritten to avoid.
+ *
+ * ponytail: one slot, not a per-ref map. It answers the reported shape — look at one tab, act on
+ * what you saw — for the cost of an assignment. A drive that interleaves refs from several tabs
+ * inside one turn needs per-ref provenance, and that is the upgrade if it ever shows up.
+ */
+/** The session the last ref-bearing result was produced from. Undefined until something mints one. */
+let mintedIn;
+/** Record that a tool handed out refs from this session. */
+export function noteRefsMinted(sessionId) {
+    mintedIn = sessionId;
+}
+export function refsLastMintedIn() {
+    return mintedIn;
+}
+/** Test seam: the module holds one slot for the process, so a test has to be able to clear it. */
+export function forgetRefProvenance() {
+    mintedIn = undefined;
+}
+/**
+ * The refusal for a ref that belongs to another tab, or undefined when there is no ambiguity.
+ *
+ * Silent when the minting tab is no longer connected: that ref really is dead, and the stale-ref
+ * refusal that already exists is the honest answer for it.
+ */
+export function wrongTabRefusal(routing) {
+    if (routing.ref === undefined || routing.explicitSessionId !== undefined)
+        return undefined;
+    const source = mintedIn;
+    if (source === undefined || source === routing.chosenSessionId)
+        return undefined;
+    const connected = routing.connected();
+    if (!connected.some((s) => s.sessionId === source))
+        return undefined;
+    const listed = connected.map((s) => `'${s.sessionId}' (${s.url})`).join(', ');
+    return (`ref '${routing.ref}' was handed out by session '${source}', and this call named no sessionId so ` +
+        `it resolved to '${routing.chosenSessionId}'. A ref only means something in the tab it was taken ` +
+        'in — refs are minted per document, so the same one can point at a different element in another ' +
+        'tab — and Reticle refuses rather than guessing which tab you meant. Connected right now: ' +
+        `${listed}. Pass sessionId: '${source}' to act on the tab you looked at, or re-read the tab you ` +
+        'actually want first. Nothing was driven.');
+}

package/dist/session/review-store.d.ts

@@ -21,6 +21,15 @@ export interface ReviewMark {
     at: number;
     status: MarkStatus;
 }
+/** Tests only — assertions on `m1` must not depend on which test ran first. */
+export declare function resetMarkIdsForTest(): void;
+/** What `resolve` actually did, including WHICH mark — so a caller can verify it hit the right one. */
+export interface ResolveOutcome {
+    resolved: boolean;
+    id: string;
+    /** The retired mark's note. Absent when nothing was resolved. */
+    note?: string;
+}
 export declare class ReviewStore {
     #private;
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
@@ -36,4 +45,14 @@ export declare class ReviewStore {
      * false for an unknown id or an already-resolved mark (so resolve is idempotent).
      */
     resolve(id: string): boolean;
+    /**
+     * Resolve, and say WHICH mark was retired.
+     *
+     * The bare boolean is what made the misattribution silent: `{"resolved":true}` is equally
+     * consistent with "I retired the bug you fixed" and "I retired somebody else's". Echoing the note
+     * lets a caller check the answer against what it believed it was resolving, which is exactly what
+     * the agent that hit this asked for — it had been re-reading the whole list after every resolve
+     * and hand-diffing the notes to get the same assurance.
+     */
+    resolveDetail(id: string): ResolveOutcome;
 }

package/dist/session/review-store.js

@@ -11,14 +11,31 @@ import { MarkStatus } from '@reticlehq/core';
  */
 /** Prefix on review-mark ids (m1, m2, …) — distinguishes them from command ids. */
 const MARK_ID_PREFIX = 'm';
+/**
+ * Shared by every store in the process, so an id is never reissued.
+ *
+ * The sequence used to live on the instance, which looked right and was not: a store is created per
+ * Session, and a Session is recreated on every page reload and socket reattach. Each new store began
+ * again at `m1`, so an id an agent was still holding silently came to denote a DIFFERENT mark — and
+ * `resolve` retired that one instead, reporting success. Reported from the field by an agent that
+ * closed a bug nobody had fixed while the two it had fixed vanished unrecorded.
+ *
+ * Process-wide is deliberately not "forever": a daemon restart resets it, but a restart also
+ * destroys every session, so any id from before it resolves to nothing and `resolve` correctly
+ * returns false. The identity echo below covers what remains.
+ */
+let nextMarkId = 0;
+/** Tests only — assertions on `m1` must not depend on which test ran first. */
+export function resetMarkIdsForTest() {
+    nextMarkId = 0;
+}
 export class ReviewStore {
     #marks = [];
-    #seq = 0;
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data, at) {
-        this.#seq += 1;
+        nextMarkId += 1;
         const mark = {
-            id: `${MARK_ID_PREFIX}${String(this.#seq)}`,
+            id: `${MARK_ID_PREFIX}${String(nextMarkId)}`,
             note: data.note,
             anchor: data.anchor,
             strategy: data.strategy,
@@ -51,10 +68,22 @@ export class ReviewStore {
      * false for an unknown id or an already-resolved mark (so resolve is idempotent).
      */
     resolve(id) {
+        return this.resolveDetail(id).resolved;
+    }
+    /**
+     * Resolve, and say WHICH mark was retired.
+     *
+     * The bare boolean is what made the misattribution silent: `{"resolved":true}` is equally
+     * consistent with "I retired the bug you fixed" and "I retired somebody else's". Echoing the note
+     * lets a caller check the answer against what it believed it was resolving, which is exactly what
+     * the agent that hit this asked for — it had been re-reading the whole list after every resolve
+     * and hand-diffing the notes to get the same assurance.
+     */
+    resolveDetail(id) {
         const mark = this.#marks.find((m) => m.id === id);
         if (mark === undefined || mark.status === MarkStatus.RESOLVED)
-            return false;
+            return { resolved: false, id };
         mark.status = MarkStatus.RESOLVED;
-        return true;
+        return { resolved: true, id, note: mark.note };
     }
 }

package/dist/session/session-lease.js

@@ -8,7 +8,7 @@
  *
  * Any edit here is a per-session tax on every user: say it in as few words as still work.
  */
-const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"} — the panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
+const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {action:"yield", mode:"waiting"|"ask"}. The panel reads "live" until you do. {action:"end"} when the task is done; it revives on your next action.';
 export function buildSessionLease(sessionId, openedAt) {
     return { sessionId, opened_at: openedAt, IMPORTANT: SESSION_LEASE_NOTICE };
 }

package/dist/session/session-manager.d.ts

@@ -26,6 +26,15 @@ export declare class SessionManager {
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint(): string | undefined;
     everConnected(): boolean;
     /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
     noteClosure(reason: string, at: number): void;

package/dist/session/session-manager.js

@@ -161,6 +161,17 @@ export class SessionManager {
     setNoSessionHint(hint) {
         this.#noSessionHint = hint;
     }
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint() {
+        return this.#noSessionHint?.();
+    }
     /** Whether any session has connected since this daemon booted — half the diagnosis. */
     #everConnected = false;
     everConnected() {

package/dist/session/session.d.ts

@@ -135,6 +135,12 @@ export declare class Session {
         total: number;
         dropped: number;
     };
+    /**
+     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously.
+     */
+    lostSince(cursor: number): boolean;
     onEvent(listener: (event: ReticleEvent) => void): () => void;
     onDisconnect(listener: () => void): () => void;
     /** Send a command to the browser and await its reply (or time out). */
@@ -159,6 +165,8 @@ export declare class Session {
     drainInbox(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */
     inboxSize(): number;
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory(): readonly InboxMessage[];
     /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
     pendingMarks(): ReviewMark[];
     /** Full mark history (pending + resolved), oldest first. */

package/dist/session/session.js

@@ -370,6 +370,14 @@ export class Session {
     bufferHealth() {
         return this.#buffer.bufferHealth();
     }
+    /**
+     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously.
+     */
+    lostSince(cursor) {
+        return this.#buffer.lostSince(cursor);
+    }
     onEvent(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
@@ -470,6 +478,10 @@ export class Session {
     inboxSize() {
         return this.#live.size();
     }
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory() {
+        return this.#live.history();
+    }
     // ── Human review marks: the "annotate the bug where you see it" inbox (server-owned) ──────────
     /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
     pendingMarks() {

package/dist/status-payload.d.ts

@@ -14,6 +14,18 @@ interface StatusPayload {
     contract: string;
     sessionCount: number;
     sessions: SessionInfo[];
+    /**
+     * Why nothing is connected — present ONLY when `sessionCount` is 0.
+     *
+     * `reticle status` is the most-run command in the field, and with no sessions it answered
+     * `sessionCount: 0` and stopped. That is the same dead end `reticle_sessions` used to be for
+     * agents, at the same point in the funnel — the daemon is up, the agent is attached, and the app
+     * never arrived — and it is where most installs stop. Agents got the diagnosis in 2.7.0; a human
+     * running the command we tell them to run in `init`'s closing line deserves the same sentence.
+     */
+    why?: string;
 }
-export declare function statusPayload(sessionCount: number, sessions: SessionInfo[]): StatusPayload;
+export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
+/** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
+why?: string): StatusPayload;
 export {};

package/dist/status-payload.js

@@ -1,11 +1,16 @@
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './version/server-version.js';
-export function statusPayload(sessionCount, sessions) {
+export function statusPayload(sessionCount, sessions, 
+/** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
+why) {
     return {
         running: true,
         version: SERVER_VERSION,
         contract: CONTRACT_FINGERPRINT,
         sessionCount,
         sessions,
+        // Only when there is nothing to explain away: a diagnosis printed beside a live session would
+        // contradict it.
+        ...(0 === sessionCount && why !== undefined ? { why } : {}),
     };
 }

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

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ *
+ * 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
+ * app wired", and it has one answer per run.
+ *
+ * Names, never values: whether `init` had been run and whether an agent was attached — never the
+ * 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.
+ */
+export declare function markInstrumentationClock(now: number): void;
+export interface InstrumentationFacts {
+    /** Whether this project has a projectId stamped — i.e. `init` has run here. */
+    initialized: boolean;
+    /**
+     * Whether an MCP client was attached when the app arrived.
+     *
+     * Both halves present is the only state in which Reticle can do anything, and it is worth being
+     * able to see the two orders apart: an app that connects with no agent attached is a person
+     * setting up, while an agent that has been waiting is a session about to do work.
+     */
+    agentAttached: boolean;
+}
+/**
+ * Report the first instrumented app of this daemon run. Best-effort and idempotent — a metric must
+ * never be the reason a session fails to register.
+ */
+export declare function reportAppInstrumented(facts: InstrumentationFacts, now?: () => number): void;
+/** Tests only. */
+export declare function resetAppInstrumented(): void;

package/dist/telemetry/app-instrumented.js

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ *
+ * 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
+ * app wired", and it has one answer per run.
+ *
+ * Names, never values: whether `init` had been run and whether an agent was attached — never the
+ * 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';
+import { getTelemetry } from './telemetry.js';
+let reported = false;
+/** Set at daemon start so the first connect can report how long the install sat un-instrumented. */
+let daemonStartedAt;
+export function markInstrumentationClock(now) {
+    daemonStartedAt = now;
+    reported = false;
+}
+/**
+ * Report the first instrumented app of this daemon run. Best-effort and idempotent — a metric must
+ * never be the reason a session fails to register.
+ */
+export function reportAppInstrumented(facts, now = () => Date.now()) {
+    if (reported)
+        return;
+    reported = true;
+    try {
+        void getTelemetry().emit(TelemetryEventKind.APP_INSTRUMENTED, {
+            instrumentation: {
+                initialized: facts.initialized,
+                agentAttached: facts.agentAttached,
+                // How long the daemon ran before an app showed up. Large values are the interesting ones:
+                // Reticle was up, the agent had the tools, and nothing was wired for that whole time.
+                msToFirstApp: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
+            },
+        });
+    }
+    catch {
+        /* never let a metric interfere with a page connecting */
+    }
+}
+/** Tests only. */
+export function resetAppInstrumented() {
+    reported = false;
+    daemonStartedAt = undefined;
+}

package/dist/telemetry/automation-hint.d.ts

@@ -0,0 +1,17 @@
+import { AutomationHint } from '@reticlehq/core';
+export interface AutomationInput {
+    env: NodeJS.ProcessEnv;
+    fileExists: (path: string) => boolean;
+    hasTty: boolean;
+}
+/**
+ * The most specific signal that fires, or undefined.
+ *
+ * Ordered most specific first: a container inside a Codespace with no terminal is one fact about the
+ * run, and sending the weakest of the three would waste the field. Omitted rather than sent as a
+ * "none" value, so its presence is itself the signal — the convention every other advisory field
+ * here follows.
+ */
+export declare function resolveAutomationHint(input: AutomationInput): AutomationHint | undefined;
+/** The real reading, taken once per process. */
+export declare function currentAutomationHint(env: NodeJS.ProcessEnv): AutomationHint | undefined;

package/dist/telemetry/automation-hint.js

@@ -0,0 +1,71 @@
+/**
+ * An ADVISORY marker that a run looks automated, for the runs `ci` cannot see.
+ *
+ * `ci` is a single environment variable, which is exactly right for a GitHub Actions runner and
+ * blind to everything else: our own gate has run from a datacenter and landed in the user data
+ * indistinguishable from somebody at a laptop.
+ *
+ * ADVISORY, and never a filter. A real person works inside a container, inside a Codespace, and over
+ * an ssh session with no terminal attached, and every one of them is a user. Nothing may drop a row
+ * because this is set; it exists so a surprising number can be looked at from a second angle, and a
+ * hint that starts being used as an exclusion has stopped being a hint. Absent means "nothing here
+ * looked automated", never "a human was present".
+ *
+ * WHAT WAS REJECTED, so nobody re-proposes it:
+ *  - IP address, ASN or datacenter geolocation. Not knowable client-side, and it is a stronger
+ *    identifier than anything else we collect. The one signal that would actually separate a cloud
+ *    sandbox from a laptop is the one we will not collect.
+ *  - Hostname patterns (`runner-*`, `ip-10-*`). A hostname is user data, and matching names is
+ *    guesswork dressed as a measurement — a guessed dimension and a measured one are
+ *    indistinguishable once they are in the same column.
+ *  - Process ancestry. Costs a spawn on a path that must never tax a command, and reads the name of
+ *    somebody else's program to classify our own user.
+ *  - `npm_config_user_agent`. Says which package manager ran us, which every route shares.
+ *  - An absent `$DISPLAY`. Every Linux server, every ssh session, and a large share of genuine
+ *    developer machines trip it; it separates nothing.
+ */
+import { existsSync } from 'node:fs';
+import { AutomationHint } from '@reticlehq/core';
+/** Container runtimes drop one of these at the filesystem root. */
+const CONTAINER_MARKERS = ['/.dockerenv', '/run/.containerenv'];
+/** Hosted dev environments that declare themselves. Self-declared, never inferred. */
+const HOSTED_WORKSPACE_ENV = [
+    'CODESPACES',
+    'GITPOD_WORKSPACE_ID',
+    'CLOUD_SHELL',
+    'REMOTE_CONTAINERS',
+];
+/**
+ * The most specific signal that fires, or undefined.
+ *
+ * Ordered most specific first: a container inside a Codespace with no terminal is one fact about the
+ * run, and sending the weakest of the three would waste the field. Omitted rather than sent as a
+ * "none" value, so its presence is itself the signal — the convention every other advisory field
+ * here follows.
+ */
+export function resolveAutomationHint(input) {
+    if (CONTAINER_MARKERS.some((m) => input.fileExists(m)))
+        return AutomationHint.CONTAINER;
+    if (HOSTED_WORKSPACE_ENV.some((k) => (input.env[k] ?? '') !== ''))
+        return AutomationHint.HOSTED_WORKSPACE;
+    if (!input.hasTty)
+        return AutomationHint.NO_TTY;
+    return undefined;
+}
+/** The real reading, taken once per process. */
+export function currentAutomationHint(env) {
+    return resolveAutomationHint({
+        env,
+        fileExists: (p) => {
+            try {
+                return existsSync(p);
+            }
+            catch {
+                return false; // an unreadable root is not evidence of anything
+            }
+        },
+        // Both ends, because a piped stdout alone is how `reticle status | jq` looks, and that is a
+        // person typing.
+        hasTty: true === process.stdout.isTTY || true === process.stdin.isTTY,
+    });
+}

package/dist/telemetry/bug-found.d.ts

@@ -6,24 +6,4 @@ import { type BugFound } from '@reticlehq/core';
  * nothing about sessions and should stay that way. The emission site owns the dedup flag.
  */
 export type BugCandidate = Omit<BugFound, 'repeat'>;
-/**
- * `bug.attribution` was REMOVED, deliberately, and this note is here so it is not re-added casually.
- *
- * It shipped twice and was wrong both times. First 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. That was fixed, and a real drive then found
- * it still inverted: across two full runs, EVERY `attribution: 'app'` was a misattribution, while the
- * one defect that genuinely was a bad agent predicate carried none. One session would have published
- * "2 defects in the app" against a true count of 0.
- *
- * A metric that is 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. Counting nothing is recoverable;
- * publishing a false accusation about somebody's product is not.
- *
- * Bringing it back needs evidence that actually separates the cases. It does not exist in the payload
- * today: `element.present` covers "the button is missing", "the API is down" and "the agent mistyped
- * a testid" identically, and `signal.absent` covers both a signal the app never fired and a ref
- * Reticle drove into nothing. Until a verdict carries the reason it came out that way, the honest
- * output is no owner at all.
- */
 export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];