@reticlehq/init 2.14.0

package/dist/framework-adapter.js

@@ -0,0 +1,138 @@
+/**
+ * One record per framework, in one table the compiler refuses to leave a hole in.
+ *
+ * Adding a framework used to mean editing nine places — the enum, the detection globs, the
+ * detection chain, the package switch, an ad-hoc `SVELTEKIT || NUXT` pair test, the step switch,
+ * the step builder, the connect snippet, the connect-step title set — and only two of them went
+ * red when missed. The rest failed the way this whole area fails: `init` printed a clean plan and
+ * the app never dialled the daemon.
+ *
+ * Everything that is per-framework AND mechanical lives here. What is NOT here is deliberate:
+ *
+ * - Detection (`FRAMEWORK_SIGNALS` / `DETECTION_ORDER` in `detect.ts`). The step builders below
+ *   import `detect.ts` transitively, so folding detection in would make the module that answers
+ *   "what is this project" depend on the module that answers "how do we wire it". It is a
+ *   `Record<Framework, …>` of its own there, so it is completed by the compiler just the same.
+ * - The snippet builders (`snippets.ts`). Each is a different recipe in a different language, and
+ *   they are reached through the `steps` builder anyway.
+ *
+ * `framework-adapter.test.ts` asserts the seam between the two halves.
+ */
+import { Framework } from './detect.js';
+import { StepTitle } from './connect-steps.js';
+import { VITE_PLUGIN_DETAIL, astroSteps, craSteps, htmlSteps, nextSteps, nuxtSteps, reactRouterSteps, svelteKitSteps, tanstackStartSteps, viteSteps, } from './plan-framework.js';
+import { electronViteSteps } from './plan-electron-vite.js';
+// An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
+// `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
+// framework adapter (it re-exports the browser sensor), paired with that framework's dev-only build
+// plugin for source mapping + connect injection.
+export const RETICLE_REACT_KIT = '@reticlehq/react';
+/** The framework-neutral sensor, for stacks the React adapter has nothing to attach to. */
+export const RETICLE_BROWSER_SDK = '@reticlehq/browser';
+export const RETICLE_VITE_PLUGIN = '@reticlehq/vite-plugin';
+export const RETICLE_NEXT_PLUGIN = '@reticlehq/next';
+/** The Electron main/preload helper — what makes IPC and screenshots exist at all. */
+export const RETICLE_ELECTRON = '@reticlehq/electron';
+export const FRAMEWORK_ADAPTERS = {
+    [Framework.NEXT]: {
+        // Next is React by construction, so the detection cannot disagree in a way worth honouring.
+        packages: () => [RETICLE_REACT_KIT, RETICLE_NEXT_PLUGIN],
+        steps: nextSteps,
+        connectStepTitles: [StepTitle.RETICLE_DEV_COMPONENT, StepTitle.MOUNT_RETICLE_DEV],
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.NUXT]: {
+        // The framework-neutral sensor, NOT the React kit. Nuxt renders Vue, and installing a package
+        // named @reticlehq/react — with `react` in its peer dependencies — into a Vue codebase is the
+        // single thing most likely to make someone abandon the setup, whether or not it works.
+        packages: () => [RETICLE_BROWSER_SDK],
+        steps: nuxtSteps,
+        // BOTH halves. The config is the only thing in a Nuxt app that can inline the pairing token,
+        // and the bridge refuses a connect without one even on localhost — so a ⚠ on it is a guaranteed
+        // non-connection, not a caveat.
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET_NUXT, StepTitle.NUXT_CONFIG],
+        // FALSE since `init` started writing the plugin itself. The Nuxt recipe carries an UNVERIFIED
+        // line and is now only the fallback for a config we could not patch — so on the path everybody
+        // takes, suppressing the generic note left a Vue app with no honesty line at all. The generic
+        // one is also the more accurate of the two now: the install gate scaffolds Nuxt from scratch on
+        // every change, so the SETUP is proven and only the drive is not, which is what it says.
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.VITE]: {
+        // The build plugin stamps `data-reticle-source` regardless of UI library, so a Vue or Svelte
+        // app still gets source pointers — it is only component identity that needs the React kit.
+        packages: (kit) => [kit, RETICLE_VITE_PLUGIN],
+        steps: (input) => viteSteps(input),
+        connectStepTitles: [StepTitle.VITE_PLUGIN],
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.REACT_ROUTER]: {
+        // React Router framework mode is a Vite app that renders React, so the kit and the plugin are
+        // both right for it too — only the connect INJECTION differs, and that is the plan's business.
+        packages: (kit) => [kit, RETICLE_VITE_PLUGIN],
+        // The Vite plugin too, for the reason SvelteKit gets it: React Router framework mode IS a Vite
+        // app, and the plugin is what stamps data-reticle-source. Without it the app connects and every
+        // verdict comes back with no file:line.
+        steps: (input) => [
+            ...reactRouterSteps(input),
+            ...viteSteps(input, VITE_PLUGIN_DETAIL.REACT_ROUTER),
+        ],
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET_REACT_ROUTER, StepTitle.VITE_PLUGIN],
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.SVELTEKIT]: {
+        // SvelteKit builds on Vite; until a dedicated Svelte kit exists it uses the Vite build plugin.
+        packages: (kit) => [kit, RETICLE_VITE_PLUGIN],
+        // The Vite plugin as well as the client hook. `init` already INSTALLS @reticlehq/vite-plugin for
+        // SvelteKit and then never wired it into the config, so it sat in package.json doing nothing —
+        // which is why a SvelteKit app connected fine and every verdict had no file:line.
+        steps: (input) => [...svelteKitSteps(input), ...viteSteps(input, VITE_PLUGIN_DETAIL.SVELTEKIT)],
+        connectStepTitles: [StepTitle.CLIENT_HOOK, StepTitle.VITE_PLUGIN],
+        carriesOwnUnverifiedNote: true,
+    },
+    [Framework.ASTRO]: {
+        // Astro owns its own Vite instance and renders its own HTML, so there is no config for the
+        // plugin to attach to — the kit alone, connected from a page <script> (see astroManual).
+        packages: (kit) => [kit],
+        steps: astroSteps,
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET_ASTRO],
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.ELECTRON_VITE]: {
+        // Same kit + Vite plugin as a plain Vite app, plus the Electron main/preload helper. The plugin
+        // still stamps and injects; `@reticlehq/electron` is what makes IPC and screenshots exist.
+        packages: (kit) => [kit, RETICLE_VITE_PLUGIN, RETICLE_ELECTRON],
+        steps: electronViteSteps,
+        // electron-vite's connect IS the renderer plugin. The preload and capture steps add IPC and
+        // screenshots to a session; without the plugin there is no session to add them to.
+        connectStepTitles: [StepTitle.ELECTRON_VITE_PLUGIN],
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.TANSTACK_START]: {
+        // Start IS a Vite app, so the plugin still stamps `data-reticle-source` — only the connect
+        // injection is inapplicable, and that is the plan's business (`inject: false`).
+        packages: (kit) => [kit, RETICLE_VITE_PLUGIN],
+        steps: (input) => [
+            ...tanstackStartSteps(input),
+            ...viteSteps(input, VITE_PLUGIN_DETAIL.TANSTACK_START, false),
+        ],
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET_TANSTACK_START, StepTitle.VITE_PLUGIN],
+        // The Start recipe carries its own UNVERIFIED line; a second generic notice would argue with it.
+        carriesOwnUnverifiedNote: true,
+    },
+    [Framework.CRA]: {
+        // react-scripts owns its webpack config and cannot be extended without ejecting, so there is no
+        // build plugin — the kit alone, imported from src/index.tsx (see cra.ts).
+        packages: () => [RETICLE_REACT_KIT],
+        steps: craSteps,
+        connectStepTitles: [StepTitle.CONNECT_MODULE, StepTitle.CONNECT_SNIPPET_CRA],
+        carriesOwnUnverifiedNote: false,
+    },
+    [Framework.HTML]: {
+        // No bundler plugin to install — just the kit; connect is wired by hand (see htmlManual).
+        packages: (kit) => [kit],
+        steps: htmlSteps,
+        connectStepTitles: [StepTitle.CONNECT_SNIPPET],
+        carriesOwnUnverifiedNote: false,
+    },
+};

package/dist/host.d.ts

@@ -0,0 +1,41 @@
+import type { InitOutcome } from '@reticlehq/core/telemetry';
+/**
+ * Everything the scaffolder needs that only the daemon knows.
+ *
+ * `@reticlehq/init` writes files and runs a package manager; it never opens a socket, reads the
+ * bridge's state directory or emits an event. Those four capabilities used to arrive as imports
+ * from `@reticlehq/server`, which is exactly what made the scaffolder impossible to release on its
+ * own. They arrive as this object instead, carried on `InitIo` so every internal stage that already
+ * threads the IO gets it for free rather than growing a second parameter.
+ *
+ * Every member is REQUIRED. `reportOutcome` in particular: telemetry fails silently, and an optional
+ * reporter is a reporter somebody forgets to pass and nobody ever notices is missing. A caller with
+ * genuinely nothing to report says so out loud with `SILENT_HOST`.
+ */
+export interface InitHost {
+    /**
+     * Wrap one internal stage so it can be traced. Must call `fn` exactly once and return its value.
+     * The daemon passes `spanSync`; everything else passes the identity below.
+     */
+    span<T>(name: string, fields: Record<string, unknown>, fn: () => T): T;
+    /** Report how the run went. Best-effort — setup must never fail because a metric did. */
+    reportOutcome(outcome: InitOutcome): void;
+    /**
+     * The daemon's pairing token, minted if nothing has written one yet.
+     *
+     * `init` inlines this into the CDN snippet, which has no build step — so an empty value there is a
+     * page that can never authenticate, and a token regenerated later makes the pasted literal stale.
+     * Minting belongs to the bridge, which owns the file; the scaffolder only asks for it.
+     */
+    pairingToken(): string;
+    /** The install channel the environment declares, or undefined when nothing declared one. */
+    installSource(): string | undefined;
+}
+/**
+ * A host that does nothing, for callers that drive `init`'s file surface without running an install
+ * — `reticle update`'s agent-rules refresh, and the in-memory IO the unit tests build.
+ *
+ * Named rather than spelled inline at each call site so "this run reports nothing" is a decision
+ * somebody made once and can grep for, instead of four independently-forgotten reporters.
+ */
+export declare const SILENT_HOST: InitHost;

package/dist/host.js

@@ -0,0 +1,21 @@
+/**
+ * A host that does nothing, for callers that drive `init`'s file surface without running an install
+ * — `reticle update`'s agent-rules refresh, and the in-memory IO the unit tests build.
+ *
+ * Named rather than spelled inline at each call site so "this run reports nothing" is a decision
+ * somebody made once and can grep for, instead of four independently-forgotten reporters.
+ */
+export const SILENT_HOST = {
+    span(_name, _fields, fn) {
+        return fn();
+    },
+    reportOutcome() {
+        /* nothing to report to */
+    },
+    pairingToken() {
+        return '';
+    },
+    installSource() {
+        return undefined;
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The public surface of the Reticle scaffolder.
+ *
+ * `@reticlehq/server` is the only consumer today and reaches for a handful of things: the runner
+ * and its IO, the framework/package-manager detection its doctor and self-update reuse, the two
+ * diagnostics, and the leaf vocabulary (platform names, dev-server ports, the init-failure reasons)
+ * that both halves of the old single package shared. One entry point rather than a dozen subpath
+ * exports: the module layout inside here is not a contract, and pinning it as one is how a package
+ * ends up unable to move a file.
+ */
+export { runInit, resolveLockfiles, type InitIo, type InitOptions, type InitResult, } from './run.js';
+export { buildNodeIo } from './node-io.js';
+export { type InitHost, SILENT_HOST } from './host.js';
+export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
+export { InitFailure } from './init-failure.js';
+export { NodePlatform } from './platform.js';
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './dev-server-ports.js';
+export { configWithInstallSource } from './install-source-config.js';
+export { projectIdOf, rememberProjectOnDisk, type RegistryIo } from './remember-project.js';
+export { detectPackageManager, installCommandParts, parseMajor, PackageManager } from './detect.js';
+export { findWorkspaceApps } from './workspace-apps.js';
+export { refreshAgentRules } from './refresh-rules.js';
+export { diagnoseDesktop, isDesktopProject } from './desktop-doctor.js';
+export { diagnoseWebCsp } from './csp-doctor.js';
+export { reticleConfigContent } from './snippets.js';

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * The public surface of the Reticle scaffolder.
+ *
+ * `@reticlehq/server` is the only consumer today and reaches for a handful of things: the runner
+ * and its IO, the framework/package-manager detection its doctor and self-update reuse, the two
+ * diagnostics, and the leaf vocabulary (platform names, dev-server ports, the init-failure reasons)
+ * that both halves of the old single package shared. One entry point rather than a dozen subpath
+ * exports: the module layout inside here is not a contract, and pinning it as one is how a package
+ * ends up unable to move a file.
+ */
+export { runInit, resolveLockfiles, } from './run.js';
+export { buildNodeIo } from './node-io.js';
+export { SILENT_HOST } from './host.js';
+export { RETICLE_VERSION, RETICLE_NPM_PACKAGE } from './version.js';
+export { InitFailure } from './init-failure.js';
+export { NodePlatform } from './platform.js';
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning, } from './dev-server-ports.js';
+export { configWithInstallSource } from './install-source-config.js';
+export { projectIdOf, rememberProjectOnDisk } from './remember-project.js';
+export { detectPackageManager, installCommandParts, parseMajor, PackageManager } from './detect.js';
+export { findWorkspaceApps } from './workspace-apps.js';
+export { refreshAgentRules } from './refresh-rules.js';
+export { diagnoseDesktop, isDesktopProject } from './desktop-doctor.js';
+export { diagnoseWebCsp } from './csp-doctor.js';
+export { reticleConfigContent } from './snippets.js';

package/dist/init-failure.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Classified `reticle init` failures — our own vocabulary, never a raw error or a path.
+ *
+ * Lives here rather than beside the telemetry client because `run.ts` is what classifies a failed
+ * run, and `@reticlehq/init` must not depend on the daemon. `@reticlehq/server`'s
+ * `telemetry/init-telemetry.ts` re-exports it, so every existing consumer is unchanged.
+ */
+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. */
+    readonly MCP_REGISTRATION: "mcp_registration";
+    readonly OTHER: "other";
+};
+export type InitFailure = (typeof InitFailure)[keyof typeof InitFailure];

package/dist/init-failure.js

@@ -0,0 +1,18 @@
+/**
+ * Classified `reticle init` failures — our own vocabulary, never a raw error or a path.
+ *
+ * Lives here rather than beside the telemetry client because `run.ts` is what classifies a failed
+ * run, and `@reticlehq/init` must not depend on the daemon. `@reticlehq/server`'s
+ * `telemetry/init-telemetry.ts` re-exports it, so every existing consumer is unchanged.
+ */
+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. */
+    MCP_REGISTRATION: 'mcp_registration',
+    OTHER: 'other',
+};

package/dist/init-opt-out.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An explicit "do not instrument this" in a file `init` would otherwise edit.
+ *
+ * `init` runs unattended, usually by an agent, in a repo it has just met. Reported from a monorepo
+ * audit: it added the plugin to an app whose `vite.config` carried a comment saying Reticle was
+ * deliberately excluded, and in the same run appended to `CLAUDE.md` — the file every agent in that
+ * repo reads first. The reporter reverted all of it.
+ *
+ * A tool that overrides an explicit "no" is one nobody lets near a monorepo twice, and a SILENT
+ * override is worse than a refusal because the file it edited is the file that said not to.
+ *
+ * One marker for every surface. A user should learn `@reticle-ignore` once, not once per file type.
+ */
+/** The marker, exported so no caller restates the string. */
+export declare const OPT_OUT_MARKER = "@reticle-ignore";
+/** True when `source` carries the opt-out marker. Absent or empty source is not an opt-out. */
+export declare function hasOptOut(source: string | undefined): boolean;

package/dist/init-opt-out.js

@@ -0,0 +1,30 @@
+/**
+ * An explicit "do not instrument this" in a file `init` would otherwise edit.
+ *
+ * `init` runs unattended, usually by an agent, in a repo it has just met. Reported from a monorepo
+ * audit: it added the plugin to an app whose `vite.config` carried a comment saying Reticle was
+ * deliberately excluded, and in the same run appended to `CLAUDE.md` — the file every agent in that
+ * repo reads first. The reporter reverted all of it.
+ *
+ * A tool that overrides an explicit "no" is one nobody lets near a monorepo twice, and a SILENT
+ * override is worse than a refusal because the file it edited is the file that said not to.
+ *
+ * One marker for every surface. A user should learn `@reticle-ignore` once, not once per file type.
+ */
+/** The marker, exported so no caller restates the string. */
+export const OPT_OUT_MARKER = '@reticle-ignore';
+/**
+ * Matched as a whole token so neighbouring text cannot trigger it.
+ *
+ * `@reticle-ignored-paths` in a doc link, or prose mentioning reticle and ignore in one sentence,
+ * must not read as an opt-out — a false positive here silently declines to instrument an app that
+ * wanted instrumenting, which is the same silent-wrong-outcome failure in the other direction.
+ *
+ * Case-insensitive: a marker people type by hand gets typed how they like, and refusing
+ * `@Reticle-Ignore` would be a rule that exists only to be tripped over.
+ */
+const OPT_OUT_TOKEN = new RegExp(`${OPT_OUT_MARKER}(?![\\w-])`, 'i');
+/** True when `source` carries the opt-out marker. Absent or empty source is not an opt-out. */
+export function hasOptOut(source) {
+    return source !== undefined && OPT_OUT_TOKEN.test(source);
+}

package/dist/install-hint.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What to say when the dependency install fails.
+ *
+ * Split out of plan.ts, which was at the 1000-line backstop. A cohesive unit rather than an
+ * arbitrary cut: it is prose about one step's failure modes, and the only thing it needs is which
+ * package manager was used.
+ */
+import { PackageManager } from './detect.js';
+export declare function installFailureHint(pm: PackageManager): string;

package/dist/install-hint.js

@@ -0,0 +1,41 @@
+/**
+ * What to say when the dependency install fails.
+ *
+ * Split out of plan.ts, which was at the 1000-line backstop. A cohesive unit rather than an
+ * arbitrary cut: it is prose about one step's failure modes, and the only thing it needs is which
+ * package manager was used.
+ */
+import { PackageManager } from './detect.js';
+/**
+ * Every package manager fetches, so every one of them can fail for a reason that is nothing to do
+ * with the project: offline, a proxy that blocks npmjs, a corporate mirror that is down.
+ *
+ * The hint used to name only version pinning and pnpm's maturity window. Both are real causes, and
+ * neither is that one — so a blocked registry sent the reader through their own dependency versions
+ * looking for a problem that was entirely about reachability.
+ */
+const REGISTRY_HINT = 'If it could not reach the registry at all (offline, a proxy, a mirror that is down), that is ' +
+    'about reachability and not about this project: check `npm config get registry` and whether this ' +
+    'machine can reach it.';
+/**
+ * A checkout whose `node_modules` is symlinked into another checkout's `.pnpm` store — a git
+ * worktree, or an A/B harness running two copies of the same repo — makes pnpm refuse to add a
+ * package with ERR_PNPM_UNEXPECTED_VIRTUAL_STORE, because it will not silently repoint an
+ * existing virtual store. The original hint named only the maturity-window cause, so this one
+ * sent the reader through their dependency versions looking for a problem that was actually
+ * about where the store lives (#683).
+ */
+const VIRTUAL_STORE_HINT = "If pnpm reported ERR_PNPM_UNEXPECTED_VIRTUAL_STORE, this checkout's node_modules is " +
+    "symlinked into another checkout's pnpm store (a git worktree, or an A/B harness). Either run " +
+    '`pnpm install` once in that other checkout first, or point this one at its own store:\n' +
+    '  pnpm add -D --config.virtual-store-dir=node_modules/.pnpm <packages>';
+export function installFailureHint(pm) {
+    if (pm !== PackageManager.PNPM) {
+        return `If the version was refused, install the SDK yourself. ${REGISTRY_HINT}`;
+    }
+    return ('If pnpm reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, its minimumReleaseAge setting is holding ' +
+        'this release back. Either wait out the window, or allow these packages explicitly:\n' +
+        '  pnpm config set minimumReleaseAgeExclude "@reticlehq/*"\n' +
+        'Do NOT drop the version pin — unpinned, pnpm installs an older SDK against a newer daemon, and ' +
+        `that mismatch surfaces as a -32000 with nothing naming a version.\n${VIRTUAL_STORE_HINT}\n${REGISTRY_HINT}`);
+}

package/dist/install-retries.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The weaker install attempts, in the order they are tried.
+ *
+ * Ordered by how much each one gives up, cheapest concession first, because the first that succeeds
+ * is the one that stands. Split out of plan.ts: the ladder is its own subject — two unrelated
+ * install failures, each with a different cost and a different sentence to say afterwards — and
+ * plan.ts is at its file cap.
+ */
+import { PackageManager } from './detect.js';
+export interface InstallRetry {
+    command: string;
+    args: string[];
+    note: string;
+}
+/**
+ * Build the ladder for one package manager.
+ *
+ * `--legacy-peer-deps` is npm-only, and deliberately so: it is the only manager with the flag, and
+ * pnpm, yarn and bun would reject an unknown argument — turning one failed install into two, with
+ * the second failure blaming a flag the user never asked for.
+ */
+export declare function installRetries(pm: PackageManager, pinned: readonly string[], unpinned: readonly string[], sdkVersion: string | undefined): InstallRetry[];

package/dist/install-retries.js

@@ -0,0 +1,65 @@
+/**
+ * The weaker install attempts, in the order they are tried.
+ *
+ * Ordered by how much each one gives up, cheapest concession first, because the first that succeeds
+ * is the one that stands. Split out of plan.ts: the ladder is its own subject — two unrelated
+ * install failures, each with a different cost and a different sentence to say afterwards — and
+ * plan.ts is at its file cap.
+ */
+import { PackageManager, installCommandParts } from './detect.js';
+const LEGACY_PEER_DEPS = '--legacy-peer-deps';
+/**
+ * What the peer-conflict retry gives up, said out loud.
+ *
+ * npm's default peer resolution is a real check, and overriding it can leave a tree npm would not
+ * have built. That is still better than no install — with no install there is no wiring at all —
+ * but it is the user's tree and they get to know it was relaxed, and why we thought that was right.
+ */
+const LEGACY_PEER_NOTE = `the pinned install failed and succeeded with ${LEGACY_PEER_DEPS} — this project has a peer ` +
+    'dependency conflict npm will not resolve on its own. The Reticle version is still pinned; only ' +
+    'peer resolution was relaxed, and only for this install. If your project already builds with ' +
+    `${LEGACY_PEER_DEPS} everywhere else this is the same tree you always get; if it does not, the ` +
+    'conflict is worth looking at on its own terms.';
+/**
+ * Said out loud when the exact-version install failed and the unpinned one worked.
+ *
+ * It used to assert a cause it cannot know. Every one of nine fixture apps got the same sentence —
+ * "the registry refused 2.5.0 (pnpm's minimumReleaseAge holds new releases back)" — when the actual
+ * cause on that run was that the version did not exist yet, and the remedy offered was a `pnpm
+ * config` command handed to a yarn 1 project that will never read it.
+ *
+ * This note is built at PLAN time, before anything runs, and `io.exec` returns a bare boolean, so
+ * the apply layer has no failure text to hand back either. The honest move is therefore to report
+ * the CONSEQUENCE (which is certain and is the part that bites) and offer the remedy that belongs to
+ * the manager actually in use — rather than name a cause that is one possibility among several.
+ */
+function unpinnedRetryNote(version, pm) {
+    const wanted = version === undefined ? 'the exact version' : version;
+    // Kept verbatim for pnpm, where minimumReleaseAge is a real and common cause with a real remedy.
+    const remedy = pm === PackageManager.PNPM
+        ? ' One common cause on pnpm is minimumReleaseAge holding a new release back; if pnpm ' +
+            'reported ERR_PNPM_NO_MATURE_MATCHING_VERSION, either wait out the window or allow these ' +
+            'packages: pnpm config set minimumReleaseAgeExclude "@reticlehq/*"'
+        : '';
+    return (`the pinned install of ${wanted} failed, so the newest version the registry WOULD accept was ` +
+        `installed instead. That may not match the daemon — if the agent reports protocol errors, check ` +
+        `\`versionSkew\` in reticle_sessions.${remedy}`);
+}
+/**
+ * Build the ladder for one package manager.
+ *
+ * `--legacy-peer-deps` is npm-only, and deliberately so: it is the only manager with the flag, and
+ * pnpm, yarn and bun would reject an unknown argument — turning one failed install into two, with
+ * the second failure blaming a flag the user never asked for.
+ */
+export function installRetries(pm, pinned, unpinned, sdkVersion) {
+    return [
+        // Peers first: concedes only peer resolution and KEEPS the version pin.
+        ...(pm === PackageManager.NPM
+            ? [{ ...installCommandParts(pm, pinned, [LEGACY_PEER_DEPS]), note: LEGACY_PEER_NOTE }]
+            : []),
+        // Unpinned, last. pnpm resolves the newest MATURE version there, which is how a project with a
+        // release-age hold gets a working install instead of no install.
+        { ...installCommandParts(pm, unpinned), note: unpinnedRetryNote(sdkVersion, pm) },
+    ];
+}

package/dist/install-source-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The same `.reticle.json` with `installSource` added, or `undefined` when there is nothing to add.
+ *
+ * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
+ * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
+ * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
+ * most of the population the field exists to describe.
+ *
+ * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
+ * a later `init` through a different route must not take credit for an acquisition it did not make.
+ * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
+ * it could not read would be a far worse failure than a missing dimension.
+ *
+ * Lives here because `init` is the only thing that writes this file. Deciding WHICH channel declared
+ * itself stays in the server's `telemetry/install-source.ts`, which re-exports this for its own
+ * tests; the value arrives as `PlanInput.installSource`.
+ */
+export declare function configWithInstallSource(source: string | null | undefined, declared: string | undefined): string | undefined;

package/dist/install-source-config.js

@@ -0,0 +1,34 @@
+/**
+ * The same `.reticle.json` with `installSource` added, or `undefined` when there is nothing to add.
+ *
+ * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
+ * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
+ * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
+ * most of the population the field exists to describe.
+ *
+ * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
+ * a later `init` through a different route must not take credit for an acquisition it did not make.
+ * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
+ * it could not read would be a far worse failure than a missing dimension.
+ *
+ * Lives here because `init` is the only thing that writes this file. Deciding WHICH channel declared
+ * itself stays in the server's `telemetry/install-source.ts`, which re-exports this for its own
+ * tests; the value arrives as `PlanInput.installSource`.
+ */
+export function configWithInstallSource(source, declared) {
+    if (undefined === declared || null === source || undefined === source)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+    if (null === parsed || 'object' !== typeof parsed || Array.isArray(parsed))
+        return undefined;
+    const fields = parsed;
+    if (undefined !== fields['installSource'])
+        return undefined;
+    return `${JSON.stringify({ ...fields, installSource: declared }, null, 2)}\n`;
+}

package/dist/lockfiles.d.ts

@@ -0,0 +1,14 @@
+import type { InitIo } from './run.js';
+/**
+ * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
+ * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
+ * each package) so `reticle init` in a sub-package suggests `pnpm add` instead of defaulting to `npm i`.
+ *
+ * The walk is skipped when the project has its own installed tree, because an INHERITED lockfile is
+ * weaker evidence than a `node_modules` sitting right there — the ancestor describes the workspace,
+ * the tree describes THIS package. Reported from the field: `init` in a `frontend/` app installed
+ * with npm emitted `pnpm add -D` off a repo-root `pnpm-lock.yaml`, pnpm was not on PATH, and the
+ * failed install took every downstream wiring step with it. A LOCAL lockfile still wins over the
+ * tree — it is a deliberate statement about this package, not an inheritance.
+ */
+export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>, nodeModulesMarkers?: ReadonlySet<string>): Set<string>;

package/dist/lockfiles.js

@@ -0,0 +1,49 @@
+/**
+ * Which lockfile decides the package manager `init` will tell the user to run.
+ *
+ * Split out of `run.ts` when that file crossed the 1000-line cap: this is one self-contained
+ * question with its own test block, and `run.ts` is the orchestration around it.
+ */
+import { dirname, join } from 'node:path';
+import { namesAPackageManager } from './detect.js';
+/** Lockfile basenames, in package-manager preference order (mirrors detect.ts). */
+const LOCKFILE_NAMES = [
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'bun.lockb',
+    'bun.lock',
+    'package-lock.json',
+];
+/**
+ * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
+ * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
+ * each package) so `reticle init` in a sub-package suggests `pnpm add` instead of defaulting to `npm i`.
+ *
+ * The walk is skipped when the project has its own installed tree, because an INHERITED lockfile is
+ * weaker evidence than a `node_modules` sitting right there — the ancestor describes the workspace,
+ * the tree describes THIS package. Reported from the field: `init` in a `frontend/` app installed
+ * with npm emitted `pnpm add -D` off a repo-root `pnpm-lock.yaml`, pnpm was not on PATH, and the
+ * failed install took every downstream wiring step with it. A LOCAL lockfile still wins over the
+ * tree — it is a deliberate statement about this package, not an inheritance.
+ */
+export function resolveLockfiles(rootFiles, cwd, io, nodeModulesMarkers = new Set()) {
+    const set = new Set(rootFiles);
+    if (LOCKFILE_NAMES.some((name) => set.has(name)))
+        return set; // local lockfile is authoritative
+    if (namesAPackageManager(nodeModulesMarkers))
+        return set;
+    let dir = cwd;
+    for (let depth = 0; depth < 50; depth++) {
+        for (const name of LOCKFILE_NAMES) {
+            if (io.exists(join(dir, name))) {
+                set.add(name);
+                return set;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return set;
+}