@reticlehq/server 2.12.0 → 2.13.0

package/dist/setup/setup-options.js

@@ -0,0 +1,67 @@
+/**
+ * The contract between the agent and the script.
+ *
+ * Everything setup does is deterministic except for the handful of things that require reading a
+ * repository and a human's request and understanding both. Those are exactly what an agent is good
+ * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
+ * the agent decides, the script executes, and neither does the other's job.
+ *
+ * What only an agent can know, and therefore what belongs in this type:
+ *
+ *   --flow      which journey proves the thing the user cares about. Code can enumerate buttons; it
+ *               cannot know that checkout matters and the theme toggle does not. Measured, naming
+ *               it took one app's drive from a ten-minute timeout to 138 seconds, because the turns
+ *               go into FINDING a flow and naming one removes that search.
+ *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
+ *               only the request says which of them is being worked on.
+ *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
+ *               backend named in the README, the variable that skips an auth wall: all readable by
+ *               an agent, none inferable by a script. Without this a real app sits on a login
+ *               screen and there is no flow to drive at all.
+ *   --dev-cmd   the command, when the project's own scripts do not say it plainly.
+ *   --url       the app is already running here, so do not start anything.
+ *
+ * Everything else on this type is an operator's dial, not an agent's judgement.
+ */
+/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
+export const DEFAULT_BRIDGE_PORT = 4400;
+/** Per-phase budget. The drive gets its own, much larger one. */
+export const DEFAULT_PHASE_TIMEOUT_MS = 120_000;
+/** What the drive may spend before it is stopped. */
+export const DEFAULT_DRIVE_BUDGET_USD = 3;
+export const DEFAULT_SETUP_OPTIONS = {
+    bridgePort: DEFAULT_BRIDGE_PORT,
+    phaseTimeoutMs: DEFAULT_PHASE_TIMEOUT_MS,
+    driveBudgetUsd: DEFAULT_DRIVE_BUDGET_USD,
+    registerAgents: true,
+    openBrowser: true,
+    drive: true,
+    escalateWeakFlow: true,
+    restartStaleDevServer: true,
+    filesOnly: false,
+};
+/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
+export function parseEnvAssignment(pair) {
+    const at = pair.indexOf('=');
+    if (0 >= at)
+        return null;
+    const key = pair.slice(0, at).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        return null;
+    return { key, value: pair.slice(at + 1) };
+}
+/**
+ * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
+ *
+ * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
+ * something else should see its variable missing, not see setup invent one.
+ */
+export function collectEnv(pairs) {
+    const env = {};
+    for (const pair of pairs) {
+        const parsed = parseEnvAssignment(pair);
+        if (null !== parsed)
+            env[parsed.key] = parsed.value;
+    }
+    return env;
+}

package/dist/setup/transcripts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Does a transcript exist for this Claude Code session.
+ *
+ * Two roots, because a shared-config install writes elsewhere and a restart that checks only one of
+ * them refuses a session that is perfectly real.
+ */
+export declare function claudeTranscriptExists(sessionId: string): boolean;
+/**
+ * The codex conversation running in `cwd`, when one is.
+ *
+ * Codex names no session in the environment — unlike Claude Code — so it is recognised from the
+ * rollout file it is writing. Not yet wired to a reader here: returning undefined means "no codex
+ * session identified", which is the honest answer until one exists, and the decision it feeds says
+ * plainly that the client identified no conversation.
+ */
+export declare function codexSessionFor(_cwd: string): string | undefined;

package/dist/setup/transcripts.js

@@ -0,0 +1,43 @@
+/**
+ * Which conversation is asking, and does it really exist.
+ *
+ * Both answers come off the filesystem, so they are kept away from the pure decision in relaunch.ts
+ * — that is the part worth testing, and it is the part that can be wrong without anybody noticing.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Does a transcript exist for this Claude Code session.
+ *
+ * Two roots, because a shared-config install writes elsewhere and a restart that checks only one of
+ * them refuses a session that is perfectly real.
+ */
+export function claudeTranscriptExists(sessionId) {
+    for (const base of [
+        join(homedir(), '.claude-shared', 'projects'),
+        join(homedir(), '.claude', 'projects'),
+    ]) {
+        try {
+            for (const project of readdirSync(base)) {
+                if (existsSync(join(base, project, `${sessionId}.jsonl`)))
+                    return true;
+            }
+        }
+        catch {
+            /* that history directory does not exist on this machine */
+        }
+    }
+    return false;
+}
+/**
+ * The codex conversation running in `cwd`, when one is.
+ *
+ * Codex names no session in the environment — unlike Claude Code — so it is recognised from the
+ * rollout file it is writing. Not yet wired to a reader here: returning undefined means "no codex
+ * session identified", which is the honest answer until one exists, and the decision it feeds says
+ * plainly that the client identified no conversation.
+ */
+export function codexSessionFor(_cwd) {
+    return undefined;
+}

package/dist/status-payload.d.ts

@@ -24,8 +24,21 @@ interface StatusPayload {
      * running the command we tell them to run in `init`'s closing line deserves the same sentence.
      */
     why?: string;
+    /** Port of the verify HTTP endpoint this daemon serves — present only when started with `--http`. */
+    verifyPort?: number;
 }
 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;
+why?: string, verifyPort?: number): StatusPayload;
+/**
+ * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
+ * that daemon already serves the verify HTTP endpoint on the wanted port.
+ *
+ * `serve` never hands flags to a daemon that is already up, so `--http`/`--http-port` against one
+ * used to be accepted, dropped, and reported as success (#687). This is the read side of the
+ * `verifyPort` field above: the daemon says which port it serves, and `serve` compares. A daemon
+ * too old to report the field — or one that did not answer /status — reads as "not honoured",
+ * which errs loud rather than green.
+ */
+export declare function verifyEndpointMismatch(status: unknown, wantedPort: number): string | undefined;
 export {};

package/dist/status-payload.js

@@ -2,7 +2,7 @@ import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './version/server-version.js';
 export function statusPayload(sessionCount, sessions, 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why) {
+why, verifyPort) {
     return {
         running: true,
         version: SERVER_VERSION,
@@ -12,5 +12,27 @@ why) {
         // Only when there is nothing to explain away: a diagnosis printed beside a live session would
         // contradict it.
         ...(0 === sessionCount && why !== undefined ? { why } : {}),
+        ...(verifyPort === undefined ? {} : { verifyPort }),
     };
 }
+/**
+ * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
+ * that daemon already serves the verify HTTP endpoint on the wanted port.
+ *
+ * `serve` never hands flags to a daemon that is already up, so `--http`/`--http-port` against one
+ * used to be accepted, dropped, and reported as success (#687). This is the read side of the
+ * `verifyPort` field above: the daemon says which port it serves, and `serve` compares. A daemon
+ * too old to report the field — or one that did not answer /status — reads as "not honoured",
+ * which errs loud rather than green.
+ */
+export function verifyEndpointMismatch(status, wantedPort) {
+    const served = 'object' === typeof status && status !== null
+        ? status['verifyPort']
+        : undefined;
+    if (served === wantedPort)
+        return undefined;
+    const fix = 'stop it (`reticle stop`) and run `reticle serve --http` again';
+    return 'number' === typeof served
+        ? `the daemon already running serves the verify HTTP endpoint on :${String(served)}, not :${String(wantedPort)} — ${fix}`
+        : `a daemon is already running without the verify HTTP endpoint — \`--http\` cannot be applied to it; ${fix}`;
+}

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

@@ -53,4 +53,11 @@ export interface DaemonTelemetry {
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
  */
-export declare function installDaemonTelemetry(cwd: string, now?: () => number): DaemonTelemetry;
+export declare function installDaemonTelemetry(cwd: string, now?: () => number, 
+/**
+ * The bridge port this daemon bound, so the profile can say whether an app for this project has
+ * EVER connected. Optional: a caller that does not know the port gets a profile without that bit
+ * rather than one with a guessed `false`, which is the value the whole field exists to make
+ * trustworthy.
+ */
+port?: number): DaemonTelemetry;

package/dist/telemetry/daemon-telemetry.js

@@ -10,10 +10,34 @@ import { TelemetryEventKind } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
 import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
-import { startUpdateCheck } from '../update/update-nudge.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 { markDaemonStart } from './mcp-connection.js';
 import { markInstrumentationClock } from './app-instrumented.js';
 import { markStallClock, STALL_AFTER_MS, stallUptime } from '../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.
+ */
+function installFacts(cwd, port) {
+    if (port === undefined)
+        return undefined;
+    try {
+        return {
+            appConnectedBefore: hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(cwd)),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -44,11 +68,34 @@ export const SESSION_FLUSH_MS = 5 * 60 * 1000;
  * and 74% of daemons never serve a tool at all.
  */
 export const FIRST_FLUSH_MS = 90 * 1000;
+/**
+ * Attach what the update nudge did to a summary that is about to be sent.
+ *
+ * Merged HERE rather than inside `SessionMetrics` deliberately: the nudge's state lives in the
+ * update module, and a second copy of it in the metrics object would be one more thing that can
+ * drift from the flag the delivery path actually reads. `summarize()` stays a pure roll-up of
+ * counters.
+ */
+function withNudgeState(summary) {
+    const nudge = updateNudgeState();
+    return {
+        ...summary,
+        updateNudged: nudge.shown,
+        ...(nudge.offered === undefined ? {} : { updateOffered: nudge.offered }),
+    };
+}
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
  */
-export function installDaemonTelemetry(cwd, now = () => Date.now()) {
+export function installDaemonTelemetry(cwd, now = () => Date.now(), 
+/**
+ * The bridge port this daemon bound, so the profile can say whether an app for this project has
+ * EVER connected. Optional: a caller that does not know the port gets a profile without that bit
+ * rather than one with a guessed `false`, which is the value the whole field exists to make
+ * trustworthy.
+ */
+port) {
     const metrics = getSessionMetrics(now);
     void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED);
     // Ask npm whether a newer Reticle exists, so the agent can tell the human. Nothing checked before
@@ -66,7 +113,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     setTimeout(() => {
         try {
             void getTelemetry().emit(TelemetryEventKind.PROJECT_PROFILED, {
-                project: profileProject(cwd, now()),
+                project: profileProject(cwd, now(), installFacts(cwd, port)),
             });
         }
         catch {
@@ -93,7 +140,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
         void getTelemetry().emit(TelemetryEventKind.SESSION_PROGRESS, {
-            session: metrics.summarize(false),
+            session: withNudgeState(metrics.summarize(false)),
         });
         metrics.reset();
     };
@@ -114,7 +161,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
                 // The rich one: the whole session in a single event — duration, the tool histogram, error
                 // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
                 await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
-                    session: metrics.summarize(true, exit),
+                    session: withNudgeState(metrics.summarize(true, exit)),
                 });
             })();
             return stopped;

package/dist/telemetry/error-class.js

@@ -30,7 +30,7 @@ export const ErrorClass = {
 const PATTERNS = [
     [/confirmdangerous|destructive action blocked/i, ErrorClass.REFUSAL],
     [
-        /\brefus(e|ed|es|ing)\b|not supported|unsupported|cannot .* a <|contenteditable/i,
+        /\brefus(e|ed|es|ing)\b|not supported|unsupported|cannot .* a <|contenteditable|cannot hover/i,
         ErrorClass.REFUSAL,
     ],
     [

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

@@ -1,10 +1,11 @@
-import { McpScope, type Feedback } from '@reticlehq/core';
+import { McpScope, StackUnknownReason, type Feedback } from '@reticlehq/core';
 /** The context fields — the whole `Feedback` shape minus what the author supplies. */
 export type FeedbackContext = Pick<Feedback, 'stack' | 'stackMajor' | 'runtime' | 'engine' | 'driver' | 'client' | 'clientVersion' | 'mcpScope'>;
 export declare function detectStack(cwd: string, read?: (path: string) => string): {
     stack?: string;
     stackMajor?: number;
     stackSource?: 'cwd' | 'workspace';
+    stackUnknownReason?: StackUnknownReason;
 };
 /**
  * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
@@ -12,6 +13,13 @@ export declare function detectStack(cwd: string, read?: (path: string) => string
  * itself the interesting signal.
  */
 export declare function detectMcpScope(cwd: string, exists?: (path: string) => boolean): McpScope;
+/**
+ * The MCP client on the other end, self-reported in its `initialize` handshake (`claude-code`,
+ * `cursor-vscode`, …). Read through a HOOK rather than sniffing env vars: the handshake is the
+ * client's own claim about itself, while an env-var table is a guess that silently rots every time a
+ * vendor renames a variable. Unset (a CLI run with no MCP peer) simply reports no client.
+ */
+/** Kept as the telemetry-facing name; the mechanism itself lives in mcp/client-identity.ts. */
 export declare function setMcpClientNameHook(hook: () => {
     name?: string;
     version?: string;

package/dist/telemetry/feedback-context.js

@@ -9,11 +9,12 @@
  * 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 { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
-import { AppRuntime, McpScope, PageDriver } from '@reticlehq/core';
+import { AppRuntime, McpScope, PageDriver, StackUnknownReason, } from '@reticlehq/core';
 import { parseMajor } from '../init/detect.js';
-import { findWorkspaceApps } from '../init/run.js';
+import { findWorkspaceApps } from '../init/workspace-apps.js';
 /**
  * Dependency → reported stack, in resolution order. Meta-frameworks come FIRST: a Next app also
  * depends on react, and reporting `react` for it would collapse the single most important segment
@@ -40,10 +41,14 @@ const PACKAGE_JSON = 'package.json';
 /** A project-scoped MCP registration lives in one of these; `reticle init` writes user scope instead. */
 const PROJECT_MCP_FILES = ['.mcp.json', join('.cursor', 'mcp.json'), join('.vscode', 'mcp.json')];
 /**
- * The project's framework and its MAJOR version, or `{}` when package.json is absent, unreadable, or
- * names nothing we recognize. The major comes from `parseMajor` — the same range parser `reticle init`
- * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
- * both places instead of via a second, subtly different reader.
+ * The project's framework and its MAJOR version. The major comes from `parseMajor` — the same range
+ * parser `reticle init` uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3`
+ * narrows the same way in both places instead of via a second, subtly different reader.
+ *
+ * `no-manifest` covers absent AND unreadable: both mean this directory could not answer, which is
+ * the distinction that matters to the caller. Unreadable is not separated because a manifest we
+ * cannot parse is not evidence about the app, and a reason nobody can act on is noise in a closed
+ * vocabulary.
  */
 function stackOfManifest(dir, read) {
     let pkg;
@@ -51,7 +56,7 @@ function stackOfManifest(dir, read) {
         pkg = JSON.parse(read(join(dir, PACKAGE_JSON)));
     }
     catch {
-        return {};
+        return { kind: 'no-manifest' };
     }
     const deps = { ...pkg.devDependencies, ...pkg.dependencies };
     for (const [dep, stack] of STACK_BY_DEP) {
@@ -59,15 +64,17 @@ function stackOfManifest(dir, read) {
         if (range === undefined)
             continue;
         const stackMajor = parseMajor(range);
-        return { stack, ...(stackMajor !== undefined ? { stackMajor } : {}) };
+        return { kind: 'found', stack, ...(stackMajor !== undefined ? { stackMajor } : {}) };
     }
-    return {};
+    return { kind: 'unrecognised', declaresWorkspaces: pkg.workspaces !== undefined };
 }
 export function detectStack(cwd, read = readFile) {
     // The cwd wins when it IS an app — never redirect away from the real answer.
     const here = stackOfManifest(cwd, read);
-    if (here.stack !== undefined)
-        return { ...here, stackSource: 'cwd' };
+    if ('found' === here.kind) {
+        const { stack, stackMajor } = here;
+        return { stack, ...(stackMajor !== undefined ? { stackMajor } : {}), stackSource: 'cwd' };
+    }
     // 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
@@ -78,19 +85,53 @@ export function detectStack(cwd, read = readFile) {
     // declared workspaces (pnpm-workspace.yaml, package.json `workspaces`) AND scans top-level
     // directories, and it was widened once already for a repo shape a user hit twice. A second
     // detector here would drift from it the first time either changed.
+    //
+    // Every exit below carries WHY, because an empty result is not a cause. Four different facts used
+    // to arrive as one `{}`: no app anywhere, an app we read and did not recognise, workspace apps
+    // that were all unrecognised, and discovery erroring. They have different fixes, and the bucket
+    // was unusable while they were indistinguishable (#617).
+    let sawWorkspaceApp = false;
     try {
         for (const app of findWorkspaceApps(profileIo(cwd))) {
             const found = stackOfManifest(join(cwd, app), read);
             // Reported as `workspace` so the share of projects needing discovery is measurable — that
             // number is what says whether our inference needs an agent to correct it.
-            if (found.stack !== undefined)
-                return { ...found, stackSource: 'workspace' };
+            if ('found' === found.kind) {
+                const { stack, stackMajor } = found;
+                return {
+                    stack,
+                    ...(stackMajor !== undefined ? { stackMajor } : {}),
+                    stackSource: 'workspace',
+                };
+            }
+            // A manifest we READ and did not recognise is evidence about the app; a directory with no
+            // manifest is not an app at all and says nothing either way.
+            if ('unrecognised' === found.kind)
+                sawWorkspaceApp = true;
         }
     }
     catch {
         // Discovery touches the filesystem; a permission error must never cost us the profile event.
+        // Named rather than folded into "found nothing": an error is not an absence, and a detector
+        // that reports one as the other sends the reader looking for a project that was there.
+        return { stackUnknownReason: StackUnknownReason.DISCOVERY_FAILED };
+    }
+    if (sawWorkspaceApp) {
+        return { stackUnknownReason: StackUnknownReason.WORKSPACE_APPS_UNRECOGNISED };
     }
-    return {};
+    // The cwd's own manifest is the stronger statement when it exists: we read this app and did not
+    // know it. Ranked below the workspace answer only because discovery may have found the REAL app.
+    if ('unrecognised' === here.kind) {
+        // A monorepo root naming no framework is not an unrecognised APP — the app is a directory down
+        // and discovery did not surface it. Reporting MANIFEST_UNRECOGNISED here would read as "add
+        // this framework to the table" about a manifest that describes no framework at all.
+        return {
+            stackUnknownReason: here.declaresWorkspaces
+                ? StackUnknownReason.WORKSPACE_ROOT_NO_APPS
+                : StackUnknownReason.MANIFEST_UNRECOGNISED,
+        };
+    }
+    return { stackUnknownReason: StackUnknownReason.NO_APP_FOUND };
 }
 /**
  * The three filesystem methods `findWorkspaceApps` needs, rooted at `cwd`.
@@ -150,26 +191,16 @@ function fileExists(path) {
  * client's own claim about itself, while an env-var table is a guess that silently rots every time a
  * vendor renames a variable. Unset (a CLI run with no MCP peer) simply reports no client.
  */
-let clientNameHook;
+/** Kept as the telemetry-facing name; the mechanism itself lives in mcp/client-identity.ts. */
 export function setMcpClientNameHook(hook) {
-    clientNameHook = hook;
+    setMcpClientIdentityHook(hook);
 }
-/**
- * The client's own name and version from its handshake.
- *
- * Note what is NOT here and cannot be: the MODEL. MCP's `clientInfo` carries a name, a title and a
- * version and has no concept of a model, so the transport genuinely cannot tell us. The agent
- * self-reports it on the feedback itself, which is the only mechanism available and a reliable one
- * given the report is already something the agent authored.
- */
 function detectClient() {
     try {
-        const info = clientNameHook?.();
-        const name = info?.name;
-        const version = info?.version;
+        const info = mcpClientIdentity();
         return {
-            ...(name !== undefined && name !== '' ? { client: name.slice(0, 64) } : {}),
-            ...(version !== undefined && version !== '' ? { clientVersion: version.slice(0, 32) } : {}),
+            ...(info.name === undefined ? {} : { client: info.name }),
+            ...(info.version === undefined ? {} : { clientVersion: info.version }),
         };
     }
     catch {

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

@@ -0,0 +1,15 @@
+import type { Feedback } from '@reticlehq/core';
+export interface SavedFeedback {
+    path: string;
+    /** A ready-to-run command that turns the file into an issue. */
+    command: string;
+}
+/**
+ * Write the report under `<cwd>/.reticle/feedback/`. Returns undefined if it cannot be written —
+ * a feedback save that throws would take down the tool call that was reporting a problem, which is
+ * the one outcome worse than losing the report.
+ */
+export declare function saveFeedbackLocally(cwd: string, input: {
+    kind?: string;
+    source?: string;
+}, text: string, context: Partial<Feedback>, now?: number): SavedFeedback | undefined;

package/dist/telemetry/feedback-local.js

@@ -0,0 +1,56 @@
+/**
+ * Where a feedback report goes when it cannot be sent.
+ *
+ * The report is fully written and redacted by the time delivery is refused. Throwing it away
+ * punishes exactly the behaviour the channel exists to encourage — and it hits hardest where the
+ * reports are best, because a Reticle source checkout disables telemetry by cwd, so the contributor
+ * who can name the file and the line is the one person who cannot file at all.
+ *
+ * Writing it down costs nothing and loses nothing. The receipt then carries a path and a command,
+ * so the human is handed one thing to run instead of being asked to retype what an agent already
+ * wrote.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
+const FEEDBACK_SUBDIR = 'feedback';
+/** Filesystem-safe, sortable, and unique enough for one report per second per kind. */
+const stamp = (now) => new Date(now).toISOString().replace(/[:.]/g, '-').replace('Z', '');
+const asMarkdown = (input, text, context) => {
+    const title = `Reticle feedback: ${input.kind ?? 'note'}`;
+    return [
+        `# ${title}`,
+        '',
+        text.trim(),
+        '',
+        '## Context',
+        '',
+        '```json',
+        JSON.stringify(context, null, 2),
+        '```',
+        '',
+    ].join('\n');
+};
+/**
+ * Write the report under `<cwd>/.reticle/feedback/`. Returns undefined if it cannot be written —
+ * a feedback save that throws would take down the tool call that was reporting a problem, which is
+ * the one outcome worse than losing the report.
+ */
+export function saveFeedbackLocally(cwd, input, text, context, now = Date.now()) {
+    try {
+        const dir = join(cwd, ReticleDir.ROOT, FEEDBACK_SUBDIR);
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${stamp(now)}-${input.kind ?? 'note'}.md`);
+        writeFileSync(path, asMarkdown(input, text, context), 'utf8');
+        return {
+            path,
+            // `--body-file` rather than an inlined body: the report contains newlines, quotes and JSON,
+            // and a command somebody has to repair before running is a command they do not run.
+            command: `gh issue create --repo reticlehq/reticle --title "Reticle feedback: ${input.kind ?? 'note'}" --body-file "${path}"`,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/telemetry/feedback.d.ts

@@ -55,6 +55,17 @@ export interface FeedbackReceipt {
      */
     accepted: boolean;
     reason?: string;
+    /**
+     * Where the report was written when it could not be SENT.
+     *
+     * A refusal used to be the end of the road: the report was already written by then, and throwing
+     * it away punished exactly the behaviour this channel exists to encourage. Worse, the commonest
+     * refusal is a Reticle SOURCE CHECKOUT — so the reporter best placed to name a file and a line was
+     * the only one who could not file at all.
+     */
+    savedTo?: string;
+    /** A ready-to-run command that turns the saved file into an issue. */
+    fileWith?: string;
     /** Which redaction rules fired. Empty when nothing needed removing. */
     redacted: string[];
     /** The exact context that went with it, echoed back so the send is never a black box. */

package/dist/telemetry/feedback.js

@@ -26,6 +26,7 @@ import { platform } from 'node:os';
 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 { feedbackContext } from './feedback-context.js';
 import { markDelivered, outboxPath, queueFeedback } from './feedback-outbox.js';
@@ -140,15 +141,27 @@ export async function submitFeedback(input, opts = {}) {
     }
     const telemetry = getTelemetry();
     if (!telemetry.enabled) {
+        /*
+         * Cannot SEND is not the same as cannot FILE.
+         *
+         * The report is fully written and redacted by this point. Discarding it punishes the exact
+         * behaviour this channel exists to encourage, and it hits hardest where the reports are best: a
+         * Reticle source checkout disables telemetry by cwd, so a contributor who can name the file and
+         * the line was the one person who could not file at all.
+         *
+         * So it goes to disk and the receipt says where, plus a command that turns it into an issue.
+         * Nothing is lost, and the human is handed one thing to run rather than asked to retype it.
+         */
+        const cwd = opts.cwd ?? process.cwd();
+        const saved = saveFeedbackLocally(cwd, input, body.text, context);
         return {
             sent: false,
             accepted: false,
-            // Named precisely, because the commonest cause is not what the old wording suggested: a
-            // Reticle SOURCE CHECKOUT disables telemetry by cwd, and that is exactly where release runs and
-            // contributor sessions happen — so the reports most worth having were the ones silently lost.
-            reason: isReticleSourceCheckout(opts.cwd ?? process.cwd())
-                ? 'this is a Reticle source checkout, where telemetry is disabled by design, so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead, or run from the app you are verifying.'
-                : `telemetry is disabled on this machine, so feedback has nowhere to go. Re-enable with \`reticle telemetry enable\`, or open an issue at https://github.com/reticlehq/reticle/issues.`,
+            // Named precisely, because the commonest cause is not what the old wording suggested.
+            reason: isReticleSourceCheckout(cwd)
+                ? 'this is a Reticle source checkout, where telemetry is disabled by design, so this could not be sent — it has been written to disk instead, and nothing was lost.'
+                : `telemetry is disabled on this machine, so this could not be sent — it has been written to disk instead. Re-enable with \`reticle telemetry enable\` to send directly.`,
+            ...(saved === undefined ? {} : { savedTo: saved.path, fileWith: saved.command }),
             redacted,
             context,
         };

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

@@ -15,6 +15,8 @@ import { type InitOutcome } from '@reticlehq/core';
 export declare const InitFailure: {
     /** Run outside a project root. The single most common first-run mistake. */
     readonly NO_PACKAGE_JSON: "no_package_json";
+    /** The manifest exists and is not valid JSON — a trailing comma, usually. Never a stack trace. */
+    readonly MALFORMED_PACKAGE_JSON: "malformed_package_json";
     /** The package manager failed: offline, a locked registry, a broken install. */
     readonly DEPENDENCY_INSTALL: "dependency_install";
     /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */

package/dist/telemetry/init-telemetry.js

@@ -17,6 +17,8 @@ import { resolveInstallSource } from './install-source.js';
 export const InitFailure = {
     /** Run outside a project root. The single most common first-run mistake. */
     NO_PACKAGE_JSON: 'no_package_json',
+    /** The manifest exists and is not valid JSON — a trailing comma, usually. Never a stack trace. */
+    MALFORMED_PACKAGE_JSON: 'malformed_package_json',
     /** The package manager failed: offline, a locked registry, a broken install. */
     DEPENDENCY_INSTALL: 'dependency_install',
     /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */