@reticlehq/server 2.14.0 → 3.2.0

package/dist/runs/run-store.js

@@ -1,147 +0,0 @@
-/**
- * Persistence for verification-run artifacts at .reticle/runs/<runId>.json. Mirrors ProjectStore:
- * injected FileSystemPort, never-throws read, path-segment guard on the runId (the tool-arg attack
- * surface). One artifact per file (unlike project.json's single rolling file) so a host can attach an
- * individual run to a deploy. The run is already clock-stamped by buildVerificationRun, so the store
- * needs no clock.
- */
-import { asRunId, ReticleVerificationRunSchema, RUN_RETENTION, RUN_RETENTION_SLACK, RunReadError, } from '@reticlehq/core';
-import { reticleDirPaths, isValidRunId, runPath } from '../project/reticle-dir.js';
-const JSON_INDENT = 2;
-const JSON_EXT = '.json';
-const TMP_EXT = '.tmp';
-export class RunStore {
-    #fs;
-    #root;
-    #retention;
-    #slack;
-    #onWrote;
-    constructor(fs, root, opts = {}) {
-        this.#fs = fs;
-        this.#root = root;
-        this.#retention = opts.retention ?? RUN_RETENTION;
-        this.#slack = opts.slack ?? RUN_RETENTION_SLACK;
-        this.#onWrote = opts.onWrote;
-    }
-    /**
-     * Write one run artifact. Creates .reticle/runs/ first; byte-stable (fixed indent + trailing newline).
-     * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
-     * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
-     */
-    async write(run) {
-        if (!isValidRunId(run.runId)) {
-            throw new Error(`refusing to write run with unsafe runId: ${JSON.stringify(run.runId)}`);
-        }
-        await this.#fs.mkdir(reticleDirPaths(this.#root).runs);
-        // Atomic publish: write a temp file then rename, so a crash mid-write never leaves a half-written
-        // artifact (a partial.json would otherwise read back as MALFORMED).
-        const path = runPath(this.#root, run.runId);
-        const tmp = `${path}${TMP_EXT}`;
-        await this.#fs.writeFile(tmp, `${JSON.stringify(run, null, JSON_INDENT)}\n`);
-        await this.#fs.rename(tmp, path);
-        // AFTER the rename: a listener that reads the run back must find it there. Swallowed, because
-        // this is a notification — a sync that cannot be woken must never fail the write it followed.
-        try {
-            this.#onWrote?.();
-        }
-        catch {
-            // Not this store's problem, and not worth failing a durable write over.
-        }
-        await this.#pruneOld();
-    }
-    /**
-     * Keep .reticle/runs/ bounded. Only acts once the count exceeds RUN_RETENTION + SLACK, then deletes the
-     * oldest (by createdAt) back down to RUN_RETENTION — so the read-all is amortized, not per-write.
-     */
-    async #pruneOld() {
-        const ids = await this.list();
-        if (ids.length <= this.#retention + this.#slack)
-            return;
-        const stamped = [];
-        for (const id of ids) {
-            const result = await this.read(id);
-            stamped.push({ id, at: result.ok ? result.run.createdAt : 0 });
-        }
-        stamped.sort((a, b) => a.at - b.at);
-        for (const { id } of stamped.slice(0, stamped.length - this.#retention)) {
-            await this.#fs.rm(runPath(this.#root, id));
-        }
-    }
-    /** Never throws. Invalid id / missing → MISSING; bad JSON or failed schema → MALFORMED. */
-    async read(runId) {
-        if (!isValidRunId(runId))
-            return { ok: false, reason: RunReadError.MISSING };
-        const path = runPath(this.#root, runId);
-        if (!(await this.#fs.exists(path)))
-            return { ok: false, reason: RunReadError.MISSING };
-        let text;
-        try {
-            text = await this.#fs.readFile(path);
-        }
-        catch (error) {
-            return {
-                ok: false,
-                reason: this.#fs.isNotFound(error) ? RunReadError.MISSING : RunReadError.MALFORMED,
-            };
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            return { ok: false, reason: RunReadError.MALFORMED };
-        }
-        const result = ReticleVerificationRunSchema.safeParse(parsed);
-        if (!result.success)
-            return { ok: false, reason: RunReadError.MALFORMED };
-        return { ok: true, run: result.data };
-    }
-    /** List run ids on disk (filenames minus.json). Empty when the runs dir is absent. */
-    async list() {
-        const dir = reticleDirPaths(this.#root).runs;
-        if (!(await this.#fs.exists(dir)))
-            return [];
-        let entries;
-        try {
-            entries = await this.#fs.readdir(dir);
-        }
-        catch {
-            return [];
-        }
-        return entries
-            .filter((e) => e.endsWith(JSON_EXT))
-            .map((e) => asRunId(e.slice(0, -JSON_EXT.length)));
-    }
-    /** The most-recent run by createdAt (undefined when none). Powers reticle_run_export's default. */
-    async latest() {
-        const ids = await this.list();
-        let best;
-        for (const id of ids) {
-            const result = await this.read(id);
-            if (result.ok && (best === undefined || result.run.createdAt > best.createdAt)) {
-                best = result.run;
-            }
-        }
-        return best;
-    }
-    /**
-     * The two most-recent runs by createdAt as `[previous, current]` (oldest-first), or undefined when
-     * fewer than two readable runs exist. Powers reticle_run_export's `format:"diff"` (run-to-run deltas).
-     */
-    async latestTwo() {
-        const runs = [];
-        for (const id of await this.list()) {
-            const result = await this.read(id);
-            if (result.ok)
-                runs.push(result.run);
-        }
-        if (runs.length < 2)
-            return undefined;
-        runs.sort((a, b) => a.createdAt - b.createdAt);
-        const previous = runs[runs.length - 2];
-        const current = runs[runs.length - 1];
-        if (previous === undefined || current === undefined)
-            return undefined;
-        return [previous, current];
-    }
-}

package/dist/runs/run-tools.d.ts

@@ -1,9 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-/**
- * The verification-run export tool. `reticle_run_export` reads a persisted ReticleVerificationRun artifact
- * from .reticle/runs/ — the stable verdict a host platform (OEM/design partner) or CI consumes. With a
- * runId it returns that run; without one it returns the most recent. With format:"report" it returns a
- * legible ✓/✗ text report instead of raw JSON. The RunStore is built inline from the injected fs +
- * reticleRoot (it is stateless), so this needs no new ToolDeps wiring.
- */
-export declare const RUN_TOOLS: ToolDef[];

package/dist/runs/run-tools.js

@@ -1,82 +0,0 @@
-import { z } from 'zod';
-import { sessionRoot } from '../project/session-root.js';
-import { RunReadError } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { asString } from '../tools/tools-helpers.js';
-import { sessionIdShape } from '../tools/tool-kit.js';
-import { isValidRunId } from '../project/reticle-dir.js';
-import { RunStore } from './run-store.js';
-import { renderRunReport } from './render-report.js';
-import { diffRuns } from './run-diff.js';
-/**
- * The verification-run export tool. `reticle_run_export` reads a persisted ReticleVerificationRun artifact
- * from .reticle/runs/ — the stable verdict a host platform (OEM/design partner) or CI consumes. With a
- * runId it returns that run; without one it returns the most recent. With format:"report" it returns a
- * legible ✓/✗ text report instead of raw JSON. The RunStore is built inline from the injected fs +
- * reticleRoot (it is stateless), so this needs no new ToolDeps wiring.
- */
-export const RUN_TOOLS = [
-    {
-        name: ReticleTool.RUN_EXPORT,
-        description: 'Export a verification-run artifact (the OEM/CI-consumable verdict) from .reticle/runs/. With { runId } returns that specific run; without it returns the most recent. With { format: "report" } returns a legible ✓/✗ text summary; with { format: "diff" } returns the run-to-run delta between the two most-recent runs (per-flow duration deltas past a noise floor, status changes, new/removed flows, verdict change, headline). Returns { run } | { report } | { diff } or { error, reason } when none exists.',
-        inputSchema: {
-            runId: z
-                .string()
-                .optional()
-                .describe('The run id to export. Omit to return the most recent run.'),
-            format: z
-                .enum(['json', 'report', 'diff'])
-                .optional()
-                .describe('json (default) returns the full run; report returns a legible text summary; diff returns the delta vs the previous run.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            run: z.unknown().optional(),
-            report: z.string().optional(),
-            diff: z.unknown().optional(),
-            error: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const store = new RunStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
-            // format:"diff" is a whole-history operation (two most-recent runs), not a single-run read.
-            if ('diff' === asString(args['format'])) {
-                const pair = await store.latestTwo();
-                if (pair === undefined) {
-                    return {
-                        error: 'need at least two verification runs to diff — produce another with the verify flow',
-                        reason: RunReadError.MISSING,
-                    };
-                }
-                return { diff: diffRuns(pair[0], pair[1]) };
-            }
-            const runId = asString(args['runId']);
-            let run;
-            if (runId !== undefined) {
-                if (!isValidRunId(runId)) {
-                    return { error: `no run '${runId}' in .reticle/runs/`, reason: RunReadError.MISSING };
-                }
-                const read = await store.read(runId);
-                if (!read.ok) {
-                    return {
-                        error: read.reason === RunReadError.MISSING
-                            ? `no run '${runId}' in .reticle/runs/`
-                            : `run '${runId}' is malformed`,
-                        reason: read.reason,
-                    };
-                }
-                run = read.run;
-            }
-            else {
-                const latest = await store.latest();
-                if (latest === undefined) {
-                    return {
-                        error: 'no verification runs yet — produce one with the verify flow first',
-                        reason: RunReadError.MISSING,
-                    };
-                }
-                run = latest;
-            }
-            return 'report' === asString(args['format']) ? { report: renderRunReport(run) } : { run };
-        },
-    },
-];

package/dist/runs/runner-port.d.ts

@@ -1,13 +0,0 @@
-/**
- * The live adapter: build a RunnerPort from the real ToolDeps so ReticleRunner drives actual flow
- * replays against the connected app. Thin glue — it wires deps.flows.list, replayNamedFlow, deps.now,
- * and a uuid generator. The ReticleRunner core (tested with a fake port) holds all the orchestration and
- * verdict logic, so this layer carries no decisions.
- */
-import { type RunId } from '@reticlehq/core';
-import type { ToolDeps } from '../tools/tools.js';
-import type { RunnerPort } from './reticle-runner.js';
-/** The default run-id generator — a branded uuid. Isolated so it can be swapped/tested independently. */
-export declare function defaultRunId(): RunId;
-/** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
-export declare function createRunnerPort(deps: ToolDeps, sessionId?: string): RunnerPort;

package/dist/runs/runner-port.js

@@ -1,22 +0,0 @@
-/**
- * The live adapter: build a RunnerPort from the real ToolDeps so ReticleRunner drives actual flow
- * replays against the connected app. Thin glue — it wires deps.flows.list, replayNamedFlow, deps.now,
- * and a uuid generator. The ReticleRunner core (tested with a fake port) holds all the orchestration and
- * verdict logic, so this layer carries no decisions.
- */
-import { randomUUID } from 'node:crypto';
-import { asRunId } from '@reticlehq/core';
-import { replayNamedFlow } from '../flows/flow-tools.js';
-/** The default run-id generator — a branded uuid. Isolated so it can be swapped/tested independently. */
-export function defaultRunId() {
-    return asRunId(randomUUID());
-}
-/** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
-export function createRunnerPort(deps, sessionId) {
-    return {
-        listFlows: () => deps.flows.list(),
-        replayFlow: (name) => replayNamedFlow(deps, sessionId !== undefined ? { flowName: name, sessionId } : { flowName: name }),
-        now: () => deps.now(),
-        newRunId: defaultRunId,
-    };
-}

package/dist/runs/verification-sync.d.ts

@@ -1,12 +0,0 @@
-import { type FlowReplayResult } from '@reticlehq/core';
-import type { ToolDeps } from '../tools/tools.js';
-export interface TimedReplay {
-    replay: FlowReplayResult;
-    durationMs: number;
-}
-/**
- * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
- * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
- * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
- */
-export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], projectId: string | undefined): Promise<string | undefined>;

package/dist/runs/verification-sync.js

@@ -1,87 +0,0 @@
-/**
- * Turn an MCP verification (a `reticle_flow_verify` suite run) into a first-class ReticleVerificationRun:
- * assemble the artifact from the already-computed replays, persist it to .reticle/runs/ (so
- * `reticle_run_export` and CI can read it), and — when logged in (cloud creds set) — best-effort push it
- * to the cloud's `POST /v1/runs` so the team's dashboard Runs tab shows what the agent just verified.
- *
- * This is the artifact tier that maps to the dashboard's "Runs" (the OEM/CI-consumable verdict); the
- * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
- * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
- */
-import { mcpClientIdentity } from '../mcp/client-identity.js';
-import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
-import { homedir } from 'node:os';
-import { buildVerificationRun } from './build-verification-run.js';
-import { mapReplayToFlowResult } from './replay-mapping.js';
-import { defaultRunId } from './runner-port.js';
-import { RunStore } from './run-store.js';
-import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
-import { resolveProjectCloud } from '../cloud/cloud-config.js';
-import { log } from '../log.js';
-/** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
-/** The author of record when no MCP peer introduced itself — a CLI run, or a client that skipped the handshake. */
-const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
-/** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
-function assembleRun(deps, timed, projectId) {
-    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
-    const input = {
-        runId: defaultRunId(),
-        durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
-        profile: RunProfile.DEV,
-        project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
-        /*
-         * WHICH agent drove this, not merely THAT one did.
-         *
-         * This was hardcoded to 'reticle-mcp', so every run in every workspace claimed the same author.
-         * A dashboard built on it could say "an agent verified this" and never "Claude Code verified
-         * this, Cursor broke it" — which is the question a team actually has once more than one agent
-         * touches the repo. The name is the client's own claim from the MCP handshake; a plain CLI run
-         * with no MCP peer keeps the old id, because inventing a vendor there would be worse than
-         * admitting we do not know.
-         */
-        agent: {
-            id: mcpClientIdentity().name ?? RETICLE_MCP_AGENT_ID,
-            kind: RunAgentKind.CODING_AGENT,
-        },
-        trigger: { kind: RunTrigger.MANUAL },
-        changedFiles: [],
-        flows,
-        checks: [],
-        risks: [],
-        evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
-    };
-    return buildVerificationRun(input, () => deps.now());
-}
-/**
- * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
- * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
- * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
- */
-export async function persistAndSyncVerificationRun(deps, timed, projectId) {
-    if (0 === timed.length)
-        return undefined;
-    let run;
-    try {
-        run = assembleRun(deps, timed, projectId);
-        await new RunStore(deps.fs, deps.reticleRoot).write(run);
-    }
-    catch (error) {
-        log('verification-run-persist-failed', {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        return undefined;
-    }
-    // Per-project cloud: only push when THIS project has cloud attached AND its policy allows runs.
-    const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
-    if (null === cloud.config || !cloud.policy.runs)
-        return run.runId; // not attached / runs disabled → local only
-    const result = await syncRunToCloud(run, cloud.config, cloudFetch);
-    if (result.outcome !== SyncOutcome.SYNCED) {
-        log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
-    }
-    // The run is up; its CONTEXT is not. Nudged rather than pushed inline, so the counters and flows
-    // ride the ordinary cycle (with its cursor and its overlap guard) instead of growing a second,
-    // subtly different upload path here.
-    deps.onRunPersisted?.();
-    return run.runId;
-}

package/dist/session/command-timeout.d.ts

@@ -1,46 +0,0 @@
-import { AppRuntime } from '@reticlehq/core';
-/**
- * Turn a bare command timeout into something the reader can act on.
- *
- * The default message — `command 'snapshot' timed out after 8000ms` — is eight seconds of silence
- * followed by a fact with no cause. For a Tauri app the cause is usually not a bug in the app: its
- * window was hidden before the webview had ever been PRESENTED, and a webview that has never been
- * presented never loads its page. The session stays connected, so nothing looks wrong, and the
- * developer goes hunting through their own code for a fault that is not there.
- *
- * This advice previously blamed occlusion — "macOS suspends an occluded or off-Space WKWebView" —
- * which is false for those states, and was the kind of wrong steer this function exists to prevent.
- * A LOADED Tauri webview keeps answering while minimized, occluded, and on another Space. `hide()`
- * after load is the remaining headless path: a hidden macOS WKWebView has been observed to go quiet
- * after a pause, but that is not something every machine demonstrates, so this message names it as
- * a candidate rather than a fact.
- *
- * It then over-corrected: it asserted the hidden-before-load ordering as FACT. But the only evidence
- * here is `hidden === true` — the ordering is never observed. Measured on a Tauri shell pointed at an
- * external http origin, whose window nothing ever hid: the message confidently prescribed a fix for a
- * mistake that had not been made, and two rounds of debugging went into the wrong place. A diagnostic
- * that names the wrong cause is worse than a bare timeout, because the bare timeout at least sends
- * the reader looking. So this now reports what is KNOWN and ranks the causes rather than picking one.
- *
- * The advice is ADDED, never substituted — the original fact still leads — and only for a runtime
- * that can actually suffer it, since misdirecting an Electron user costs them the same hour.
- */
-/**
- * What the page told us about its shell, via PAGE_HEALTH. Undefined before the first report.
- *
- * An alias of core's AppRuntime rather than a second list of the same three strings: the SDK reports
- * this value, so it is a wire value, and two independent spellings of it is how one side gains a
- * runtime the other silently refuses to recognise.
- */
-export type PageRuntime = AppRuntime;
-interface TimeoutContext {
-    url: string;
-    /** The page's own last visibility report. */
-    hidden: boolean;
-    /** Reported by the SDK. A URL cannot distinguish a Tauri dev server from a plain localhost app. */
-    runtime?: PageRuntime;
-    /** ms since ANY inbound message from the SDK. Small = the page is demonstrably still running. */
-    lastSeenMs?: number;
-}
-export declare function commandTimeoutMessage(name: string, timeoutMs: number, context: TimeoutContext): string;
-export {};

package/dist/session/command-timeout.js

@@ -1,42 +0,0 @@
-import { AppRuntime, isOpaqueOrigin } from '@reticlehq/core';
-/**
- * Inbound silence beyond this means the page may genuinely be wedged; inside it, the SDK has spoken
- * recently enough that "the page is hung" is provably the wrong story. A page that is streaming
- * events is executing JavaScript by definition.
- */
-const RECENTLY_HEARD_MS = 2000;
-const ONE_WAY_ADVICE = 'The page is ALIVE — the SDK last reported to the bridge %MS%ms ago — but it is not answering ' +
-    'commands. A page that is still sending is executing JavaScript, so it is not hung, hidden or ' +
-    'suspended: messages are getting OUT and not back IN. Look at the bridge→page direction (a socket ' +
-    'replaced mid-session, a proxy buffering one way) rather than at your app.';
-const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWebView (Tauri) window, so the webview is ' +
-    'most likely not running the page at all. Two known causes, commonest first: (1) the window was ' +
-    'hidden BEFORE its first page load — a webview that has never been presented never loads, so park ' +
-    'it from `on_page_load` instead of `setup` (see `reticle_tauri::on_page_load`, which does this for ' +
-    'RETICLE_HEADLESS=1). (2) the window was hidden after load and then went quiet — that has been ' +
-    'observed on a hidden macOS WKWebView after a pause, even though capture still works; park it ' +
-    'off-screen rather than calling hide. If neither fits, the page is reachable but not executing, ' +
-    'which is worth reporting.';
-/** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
-function isWebKitDesktop(context) {
-    if (AppRuntime.TAURI === context.runtime)
-        return true;
-    // A `tauri://` origin is unambiguous even before the first health report lands.
-    if (context.runtime !== undefined)
-        return false;
-    return isOpaqueOrigin(context.url) && context.url.startsWith('tauri:');
-}
-export function commandTimeoutMessage(name, timeoutMs, context) {
-    const base = `command '${name}' timed out after ${String(timeoutMs)}ms`;
-    // Checked FIRST, and it overrides the visibility story: a page that was heard from moments ago is
-    // executing JavaScript, so "hidden, hung or never presented" cannot be the explanation whatever
-    // `hidden` says. Deduced from the invariant, not from a measured incident — the Tauri case that
-    // prompted it turned out to go fully silent instead, which this branch correctly does not claim.
-    const heard = context.lastSeenMs;
-    if (heard !== undefined && heard <= RECENTLY_HEARD_MS) {
-        return `${base}. ${ONE_WAY_ADVICE.replace('%MS%', String(heard))}`;
-    }
-    if (!context.hidden || !isWebKitDesktop(context))
-        return base;
-    return `${base}. ${HIDDEN_ADVICE}`;
-}

package/dist/session/connection-memory.d.ts

@@ -1,59 +0,0 @@
-/**
- * One durable bit: has an app ever connected to Reticle on this port, for this project?
- *
- * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
- * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
- * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
- * install has never worked, and sends them looking for a missing config file that was always there.
- * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
- * as evidence about the install, not as a fact about a process that booted four seconds ago.
- *
- * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
- * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
- * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
- * no diagnostic at all.
- */
-/**
- * Record that a session connected. Best-effort — a daemon must never fail to serve a session
- * because it could not write a hint about it.
- */
-export declare function rememberConnected(stateDir: string, port: number, projectId: string | undefined): void;
-/**
- * Whether an app has connected on this port before, for this project.
- *
- * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
- * that is the honest reading when the caller cannot name a project: the alternative is to answer
- * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
- * exists to remove.
- */
-export declare function hasConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
-/**
- * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
- *
- * Separate from `hasConnectedBefore` because they are genuinely different questions and only one of
- * them tolerates the untagged fallback. The no-session diagnosis wants "has this daemon ever served
- * an app", and answering "no" there when it plainly has is the over-confident claim this file
- * exists to remove. The first-move block claims something narrower and says so in its own first
- * sentence: "no app has ever connected to Reticle IN THIS PROJECT".
- *
- * Deciding that narrower claim with the weaker question inverted it for exactly the population it
- * was written for. An unwired project has no `.reticle.json`, so no projectId, so it fell into the
- * untagged branch — which is true as soon as any app has ever connected on this port. On any
- * machine where the default port has served anything at all, the guidance was suppressed and the
- * agent was told the setup was done.
- *
- * So an absent projectId answers `false` here: a project with no Reticle identity has nothing
- * recorded under another project's name that could be evidence about it. The cost of being wrong in
- * this direction is one guidance block, read once at handshake, by a setup that is already working.
- *
- * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
- * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
- * without writing that file. So a project wired by hand with the plugin and no `init` records a real
- * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
- * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
- * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
- * alternative — answering from the port — is the leak this function exists to close, which is the
- * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
- * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
- */
-export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;

package/dist/session/connection-memory.js

@@ -1,108 +0,0 @@
-/**
- * One durable bit: has an app ever connected to Reticle on this port, for this project?
- *
- * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
- * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
- * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
- * install has never worked, and sends them looking for a missing config file that was always there.
- * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
- * as evidence about the install, not as a fact about a process that booted four seconds ago.
- *
- * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
- * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
- * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
- * no diagnostic at all.
- */
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-/** Sessions from an SDK old enough not to stamp a projectId still count, under this key. */
-const UNTAGGED = '(untagged)';
-/**
- * Cap on remembered projects per port.
- *
- * A shared 4400 on a busy machine sees many projects over a week and this file is never garbage
- * collected, so the set is bounded and oldest-out. The bit it answers is only ever used to soften a
- * diagnosis, so losing the tail costs nothing.
- */
-const MAX_REMEMBERED_PROJECTS = 32;
-function memoryPath(stateDir, port) {
-    return join(stateDir, `connected-${String(port)}.json`);
-}
-/** The remembered project ids for a port. Empty on absent, unreadable, or malformed state. */
-function read(stateDir, port) {
-    try {
-        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
-        if (!Array.isArray(parsed))
-            return [];
-        return parsed.filter((entry) => 'string' === typeof entry);
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Record that a session connected. Best-effort — a daemon must never fail to serve a session
- * because it could not write a hint about it.
- */
-export function rememberConnected(stateDir, port, projectId) {
-    const key = projectId ?? UNTAGGED;
-    const known = read(stateDir, port);
-    if (known.includes(key))
-        return;
-    const next = [...known, key].slice(-MAX_REMEMBERED_PROJECTS);
-    try {
-        mkdirSync(stateDir, { recursive: true });
-        writeFileSync(memoryPath(stateDir, port), JSON.stringify(next), 'utf8');
-    }
-    catch {
-        // An unwritable state home is already reported elsewhere; it must not break the session path.
-    }
-}
-/**
- * Whether an app has connected on this port before, for this project.
- *
- * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
- * that is the honest reading when the caller cannot name a project: the alternative is to answer
- * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
- * exists to remove.
- */
-export function hasConnectedBefore(stateDir, port, projectId) {
-    const known = read(stateDir, port);
-    if (projectId === undefined)
-        return known.length > 0;
-    return known.includes(projectId);
-}
-/**
- * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
- *
- * Separate from `hasConnectedBefore` because they are genuinely different questions and only one of
- * them tolerates the untagged fallback. The no-session diagnosis wants "has this daemon ever served
- * an app", and answering "no" there when it plainly has is the over-confident claim this file
- * exists to remove. The first-move block claims something narrower and says so in its own first
- * sentence: "no app has ever connected to Reticle IN THIS PROJECT".
- *
- * Deciding that narrower claim with the weaker question inverted it for exactly the population it
- * was written for. An unwired project has no `.reticle.json`, so no projectId, so it fell into the
- * untagged branch — which is true as soon as any app has ever connected on this port. On any
- * machine where the default port has served anything at all, the guidance was suppressed and the
- * agent was told the setup was done.
- *
- * So an absent projectId answers `false` here: a project with no Reticle identity has nothing
- * recorded under another project's name that could be evidence about it. The cost of being wrong in
- * this direction is one guidance block, read once at handshake, by a setup that is already working.
- *
- * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
- * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
- * without writing that file. So a project wired by hand with the plugin and no `init` records a real
- * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
- * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
- * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
- * alternative — answering from the port — is the leak this function exists to close, which is the
- * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
- * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
- */
-export function hasProjectConnectedBefore(stateDir, port, projectId) {
-    if (projectId === undefined)
-        return false;
-    return hasConnectedBefore(stateDir, port, projectId);
-}