@reticlehq/server 2.4.0 → 2.6.0

package/dist/init/run.js

@@ -4,16 +4,52 @@
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
 import { dirname, join } from 'node:path';
-import { detect, Framework } from './detect.js';
-import { DEPS_TARGET, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
+import { spanSync } from '../trace.js';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { detect, Framework, namesAPackageManager } from './detect.js';
+import { wasMcpRegistered } from './mcp-registered.js';
+import { pickAstroHost } from './astro-host.js';
+import { workspaceParents } from './workspace-apps.js';
+import { chooseWorkspaceApp } from './app-choice.js';
+import { isConnectStep } from './plan.js';
+import { CLI, CURSOR_RULE_PATH } from './agent-rules.js';
+import { CRA_ENV_PATH } from './cra.js';
+/** CRA's bundled entry, in the order create-react-app itself generates them. */
+const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
+function craEntryOf(io) {
+    for (const path of CRA_ENTRY_CANDIDATES) {
+        const source = io.readFile(path);
+        if (source !== null)
+            return { path, source };
+    }
+    return null;
+}
+/**
+ * The daemon's pairing token, for the one stack that cannot read it at build time.
+ *
+ * Every other framework's snippet reads this file in Node when the dev server starts, so the token
+ * is never written into the project. CRA bundles browser code and inlines only REACT_APP_*, so it
+ * has to be materialised into .env.development.local — which CRA's own template gitignores.
+ */
+function readPairingToken() {
+    try {
+        return readFileSync(join(homedir(), '.reticle', 'pairing-token'), 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
+}
+import { DEPS_TARGET, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
 import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
 import { reticleDevLocation } from './next-patch.js';
 import { scanTestids, storeHints } from './capabilities.js';
 import { CURSOR_DIR_RELPATH, CURSOR_MCP_RELPATH } from './cursor.js';
+import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient } from './mcp-clients.js';
 import { deriveProjectId, packageName } from './project-id.js';
 import { VITE_DEV_MODULE_PATH } from './snippets.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './slash-command.js';
-import { SERVER_VERSION } from '../server-version.js';
+import { SERVER_VERSION } from '../version/server-version.js';
 import { InitFailure, reportInitOutcome } from '../telemetry/init-telemetry.js';
 /** Lockfile basenames, in package-manager preference order (mirrors detect.ts). */
 const LOCKFILE_NAMES = [
@@ -27,11 +63,20 @@ const LOCKFILE_NAMES = [
  * 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) {
+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) {
@@ -48,6 +93,7 @@ export function resolveLockfiles(rootFiles, cwd, io) {
     return set;
 }
 const PACKAGE_JSON = 'package.json';
+const NODE_MODULES_DIR = 'node_modules';
 /**
  * Root-layout candidates, App Router only. `--src-dir` apps keep theirs under `src/app`, and the
  * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
@@ -108,6 +154,16 @@ const VITE_CONFIG_CANDIDATES = [
     'vite.config.mjs',
     'vite.config.mts',
 ];
+const ASTRO_CONFIG_CANDIDATES = [
+    'astro.config.mjs',
+    'astro.config.js',
+    'astro.config.ts',
+    'astro.config.cjs',
+];
+/** Where a conventional Astro app keeps the layout every page wraps itself in. */
+const ASTRO_LAYOUTS_DIR = 'src/layouts';
+/** Also searched: an app with no layouts directory renders the document straight from a page. */
+const ASTRO_PAGES_DIR = 'src/pages';
 const NEXT_CONFIG_CANDIDATES = [
     'next.config.mjs',
     'next.config.js',
@@ -119,6 +175,21 @@ const NEXT_CONFIG_CANDIDATES = [
  * decide whether the install finished. A notice gets its own mark so "steps remaining" can reach zero
  * on a working install that happens to be on an ungated stack.
  */
+/**
+ * A step's status AFTER the run, which is what actually happened to it.
+ *
+ * `report` applies the same downgrade when printing: a step that failed or was skipped is shown as
+ * MANUAL whatever it planned to be. Reading the planned status alone would say a step applied when
+ * the run had already given up on it.
+ */
+function resolvedStatus(plan, target, failed, skipped) {
+    const step = plan.steps.find((s) => s.target === target);
+    if (step === undefined)
+        return undefined;
+    if (failed.has(target) || skipped.has(target))
+        return StepStatus.MANUAL;
+    return step.status;
+}
 const STATUS_SYMBOL = {
     [StepStatus.APPLY]: '✓',
     [StepStatus.MANUAL]: '⚠',
@@ -137,17 +208,19 @@ function gatherPlanInput(options, io, pkgRaw) {
     // Stable identity derived from the app's package.json name + root, so it survives port changes.
     const projectId = deriveProjectId(packageName(pkg), options.cwd);
     const rootFiles = new Set(io.rootFiles());
+    const nodeModulesMarkers = new Set(io.listFiles('node_modules'));
     const detectInput = {
-        pkg: typeof pkg === 'object' && pkg !== null ? pkg : {},
+        pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
-        // Walk up for the lockfile so a monorepo sub-package picks the workspace's package manager.
-        lockfiles: resolveLockfiles(rootFiles, options.cwd, io),
+        // Walk up for the lockfile so a monorepo sub-package picks the workspace's package manager —
+        // unless this package's own installed tree already answers it, which outranks an inherited one.
+        lockfiles: resolveLockfiles(rootFiles, options.cwd, io, nodeModulesMarkers),
         // An already-installed tree names its own manager, which matters when no lockfile is committed.
-        nodeModulesMarkers: new Set(io.listFiles('node_modules')),
+        nodeModulesMarkers,
     };
     const detection = detect(detectInput);
     const vitePath = firstPresent(rootFiles, VITE_CONFIG_CANDIDATES);
-    const viteSource = vitePath === null ? null : io.readFile(vitePath);
+    const viteSource = null === vitePath ? null : io.readFile(vitePath);
     const viteConfig = vitePath !== null && viteSource !== null ? { path: vitePath, source: viteSource } : null;
     // Global MCP registration targets each agent that's present: Claude via its CLI, Cursor via its
     // global config file. Only probe when the MCP step is in play.
@@ -155,16 +228,57 @@ function gatherPlanInput(options, io, pkgRaw) {
     const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
     const existsProbe = claudeExistsProbe();
     const mcpExists = claudeCli ? io.probe(existsProbe.command, existsProbe.args) : false;
-    const cursorDir = `${io.homeDir()}/${CURSOR_DIR_RELPATH}`;
-    const cursorConfigPath = `${io.homeDir()}/${CURSOR_MCP_RELPATH}`;
-    const cursorPresent = options.mcp && io.exists(cursorDir);
+    // join(), not a literal '/': this path is checked and WRITTEN on the user's machine, and a
+    // backslash platform silently misses the config it is meant to find.
+    const cursorDir = join(io.homeDir(), CURSOR_DIR_RELPATH);
+    const cursorConfigPath = join(io.homeDir(), CURSOR_MCP_RELPATH);
+    // Cursor is "present" if its global config directory exists OR the project carries a `.cursor/`.
+    // The directory alone missed a real case: Cursor installed with a FRESH profile has not written
+    // ~/.cursor yet, so a user who had it open got no Cursor step and no message about one. A
+    // project-level .cursor/ is unambiguous evidence somebody uses it here.
+    const cursorPresent = options.mcp && (io.exists(cursorDir) || io.exists(CURSOR_DIR_RELPATH));
     const cursorConfig = cursorPresent ? io.readFile(cursorConfigPath) : null;
+    // Every OTHER MCP client this machine shows evidence of. Conservative and one-directional: we
+    // write into a config a client ALREADY has, and never create ~/.gemini or ~/.codeium for somebody
+    // who does not use them. Cursor and Claude are handled above by their own steps.
+    const detectedClients = options.mcp
+        ? fileBackedClients()
+            .filter((spec) => spec.id !== McpClient.CURSOR)
+            .map((spec) => {
+            const marker = clientMarkerRelPath(spec);
+            const absolute = spec.scope === ConfigScope.HOME ? join(io.homeDir(), spec.relPath) : spec.relPath;
+            const markerPath = spec.scope === ConfigScope.HOME ? join(io.homeDir(), marker) : marker;
+            if (!io.exists(markerPath))
+                return null;
+            return {
+                id: spec.id,
+                configPath: absolute,
+                // io.readFile passes absolute paths through unchanged, so one call covers both scopes.
+                existing: io.readFile(absolute),
+            };
+        })
+            .filter((entry) => entry !== null)
+        : [];
+    const astroPath = firstPresent(rootFiles, ASTRO_CONFIG_CANDIDATES);
+    const astroSource = null === astroPath ? null : io.readFile(astroPath);
+    // Which file owns the DOCUMENT, not how many files sit in a directory. The old rule ("exactly one
+    // .astro in src/layouts") fired on neither real Astro app: one has no layouts directory and
+    // renders from src/pages/index.astro, the other has three files there of which two are partials.
+    // `</body>` is the discriminator — see astro-host.
+    const astroCandidates = [ASTRO_LAYOUTS_DIR, ASTRO_PAGES_DIR].flatMap((dir) => io
+        .listFiles(dir)
+        .filter((f) => f.endsWith('.astro'))
+        .map((f) => ({ path: `${dir}/${f}`, source: io.readFile(`${dir}/${f}`) }))
+        .filter((c) => c.source !== null));
+    const astroHost = pickAstroHost(astroCandidates);
+    const layoutRelPath = astroHost?.path ?? null;
+    const astroLayoutSource = astroHost?.source ?? null;
     const nextConfigFile = firstPresent(rootFiles, NEXT_CONFIG_CANDIDATES);
     // App Router first; a Pages Router app has no layout, and its mount point is pages/_app.
-    const layoutPath = (NEXT_LAYOUT_CANDIDATES.find((p) => io.exists(p)) ??
-        NEXT_PAGES_APP_CANDIDATES.find((p) => io.exists(p))) ??
+    const layoutPath = NEXT_LAYOUT_CANDIDATES.find((p) => io.exists(p)) ??
+        NEXT_PAGES_APP_CANDIDATES.find((p) => io.exists(p)) ??
         null;
-    const layoutSource = layoutPath === null ? null : io.readFile(layoutPath);
+    const layoutSource = null === layoutPath ? null : io.readFile(layoutPath);
     // Where the component goes depends on WHICH router mounts it: `pages/` routes on presence, so a
     // component there becomes a broken route; `app/` routes on filename, so a sibling is inert.
     const devLocation = reticleDevLocation(layoutPath ?? 'app/layout.tsx', detection.typescript);
@@ -173,12 +287,17 @@ function gatherPlanInput(options, io, pkgRaw) {
         claudeCli,
         mcpExists,
         cursorPresent,
+        detectedClients,
         cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
         cursorConfig,
         cursorConfigPath,
         viteConfig,
+        astroConfig: astroPath !== null && astroSource !== null ? { path: astroPath, source: astroSource } : null,
+        astroLayout: layoutRelPath !== null && astroLayoutSource !== null
+            ? { path: layoutRelPath, source: astroLayoutSource }
+            : null,
         nextConfigFile,
-        nextConfigSource: nextConfigFile === null ? null : io.readFile(nextConfigFile),
+        nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
         nextLayout: layoutPath !== null && layoutSource !== null
             ? { path: layoutPath, source: layoutSource }
             : null,
@@ -190,13 +309,16 @@ function gatherPlanInput(options, io, pkgRaw) {
         nextReticleDevImport: devLocation.importSpecifier,
         nextReticleDevExists: io.exists(devLocation.path),
         svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
+        craEntry: craEntryOf(io),
+        craEnv: io.readFile(CRA_ENV_PATH),
+        pairingToken: readPairingToken(),
         reticleConfigExists: io.exists('.reticle.json'),
         // Read the agent instruction files so the rule merge stays idempotent across re-runs.
         claudeMdContent: io.readFile('CLAUDE.md'),
         agentsMdContent: io.readFile('AGENTS.md'),
-        cursorRuleExists: io.exists('.cursor/rules/reticle.mdc'),
-        claudeCommandExists: io.exists(CLAUDE_COMMAND_PATH),
-        cursorCommandExists: io.exists(CURSOR_COMMAND_PATH),
+        cursorRuleContent: io.readFile(CURSOR_RULE_PATH),
+        claudeCommandContent: io.readFile(CLAUDE_COMMAND_PATH),
+        cursorCommandContent: io.readFile(CURSOR_COMMAND_PATH),
         options: {
             port: options.port,
             mcp: options.mcp,
@@ -208,12 +330,13 @@ function gatherPlanInput(options, io, pkgRaw) {
     };
 }
 /** Where workspace tooling conventionally puts packages. */
-const WORKSPACE_PARENTS = ['apps', 'packages'];
+/** pnpm's workspace declaration, read when present — it is authoritative about where packages live. */
+const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
 /** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
 const APP_DEPS = ['next', 'vite'];
 function looksLikeApp(dir, io) {
     const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
-    if (pkgRaw === null)
+    if (null === pkgRaw)
         return false;
     const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
     if (configs.some((c) => io.exists(`${dir}/${c}`)))
@@ -231,15 +354,54 @@ function looksLikeApp(dir, io) {
  */
 export function findWorkspaceApps(io) {
     const found = [];
-    for (const parent of WORKSPACE_PARENTS) {
+    // A workspace DECLARES its packages; `['apps','packages']` was a guess that missed a real repo
+    // with three Next apps at web/, admin/ and space/ — and missing them meant init ran against the
+    // root and reported ✓ for a file Next never compiles. See workspace-apps.
+    const pkgRaw = io.readFile(PACKAGE_JSON);
+    let pkgWorkspaces;
+    try {
+        const parsed = null === pkgRaw ? undefined : JSON.parse(pkgRaw);
+        pkgWorkspaces =
+            'object' === typeof parsed && parsed !== null
+                ? parsed.workspaces
+                : undefined;
+    }
+    catch {
+        pkgWorkspaces = undefined;
+    }
+    const parents = workspaceParents({
+        ...(null === io.readFile(PNPM_WORKSPACE)
+            ? {}
+            : { pnpmWorkspace: io.readFile(PNPM_WORKSPACE) ?? '' }),
+        ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
+        topLevelDirs: io.listDirs('.'),
+    });
+    // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
+    // its children rather than assuming one level of nesting.
+    for (const parent of parents) {
+        if (looksLikeApp(parent, io))
+            found.push(parent);
         for (const name of io.listDirs(parent)) {
             const dir = `${parent}/${name}`;
             if (looksLikeApp(dir, io))
                 found.push(dir);
         }
     }
-    return found;
+    return [...new Set(found)];
 }
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
+    'one thing that decides what gets fixed:\n' +
+    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
+    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
 function restartHint(framework) {
     if (framework === Framework.NEXT)
         return 'Restart `next dev`, then ask your agent: "List Reticle sessions".';
@@ -253,13 +415,31 @@ function restartHint(framework) {
 }
 const SKIPPED_DETAIL = 'skipped — the dependency install above failed, and wiring the app to a package that is not ' +
     'installed stops it booting. Run that install, then re-run `reticle init`.';
-function report(plan, dryRun, failed, skipped, io) {
+function report(plan, dryRun, failed, skipped, degraded, io, projectDir) {
     io.print(dryRun ? 'reticle init (dry run — no files written)' : 'reticle init');
+    // Every path below is printed RELATIVE, and until now nothing said what to. Reported from the
+    // field as "[✓] Reticle config → .reticle.json" followed by the file not being there: the app was
+    // in `frontend/`, init redirected into it, and the report's `.reticle.json` was true about a
+    // directory the reader was not standing in. One line makes every path in the report unambiguous.
+    io.print(`  in ${projectDir}`);
     io.print('');
     let applied = 0;
     let manual = 0;
+    // A ⚠ on a CONNECT step is a guaranteed failure, not a caveat: nothing performs the manual step, so
+    // the app never dials the daemon and every tool answers "no browser session connected". `ok` was
+    // hardcoded true, so a run that could not possibly work reported success.
+    let connectPending = false;
     for (const s of plan.steps) {
         // A side effect that failed to apply is reported as a manual step with its fallback command.
+        const note = degraded.get(s.target);
+        if (note !== undefined) {
+            // Applied, but not the way it was asked for. A NOTICE, not work — the install did happen.
+            io.print(`  [${STATUS_SYMBOL[StepStatus.NOTICE]}] ${s.title} → ${s.target}`);
+            for (const line of note.split('\n'))
+                io.print(`      ${line}`);
+            applied++;
+            continue;
+        }
         const downgraded = failed.has(s.target) || skipped.has(s.target);
         const status = downgraded ? StepStatus.MANUAL : s.status;
         const detail = skipped.has(s.target)
@@ -272,8 +452,11 @@ function report(plan, dryRun, failed, skipped, io) {
             applied++;
         if (status === StepStatus.MANUAL || status === StepStatus.NOTICE) {
             // A notice prints in full like a manual step — it is worth reading — but is NOT counted as work.
-            if (status === StepStatus.MANUAL)
+            if (status === StepStatus.MANUAL) {
                 manual++;
+                if (isConnectStep(s.title))
+                    connectPending = true;
+            }
             for (const line of detail.split('\n'))
                 io.print(`      ${line}`);
         }
@@ -282,8 +465,13 @@ function report(plan, dryRun, failed, skipped, io) {
         }
     }
     io.print('');
+    if (connectPending) {
+        io.print('This app will NOT connect until the ⚠ step above is done by hand — Reticle tools will report ' +
+            '"no browser session connected" until then. Everything else is already in place.');
+        io.print('');
+    }
     io.print(restartHint(plan.framework));
-    return { ok: true, applied, manual };
+    return { ok: !connectPending, applied, manual };
 }
 /**
  * Perform the apply-step side effects; return the targets whose side effect failed.
@@ -294,26 +482,87 @@ function report(plan, dryRun, failed, skipped, io) {
  * MODULE_NOT_FOUND, so the app stops booting *because* Reticle was installed. A skipped step is a
  * message; a half-wired app is a broken project.
  */
+/**
+ * Are the SDK packages actually on disk, whatever the install step reported?
+ *
+ * `dependsOnInstall` exists to stop init writing a `next.config.ts` that imports a package which is
+ * not there — that took a dev server down once, and installing Reticle must never be why an app
+ * stops booting. The invariant it protects is "the import RESOLVES", but it was gated on "our
+ * install subprocess exited 0", and those come apart in exactly the situation the failure creates:
+ * init tells the user to install by hand, they do, they re-run init, the install step fails again
+ * (wrong package manager, not on PATH) and every wiring step is skipped a second time. Reported from
+ * a Next 16 app where npm had already installed both packages successfully — leaving an init that
+ * could not be retried into working, which is the shape this guard was written to prevent.
+ *
+ * Reading node_modules answers the real question and costs one `exists` call per package.
+ */
+function sdkPackagesPresent(framework, io) {
+    const packages = frameworkPackages(framework);
+    return (packages.length > 0 &&
+        packages.every((p) => io.exists(`${NODE_MODULES_DIR}/${p}/${PACKAGE_JSON}`)));
+}
 function applyEffects(plan, io) {
     const failed = new Set();
     const skipped = new Set();
+    const degraded = new Map();
     let installFailed = false;
     for (const s of plan.steps) {
         if (s.status !== StepStatus.APPLY)
             continue;
-        if (installFailed && s.dependsOnInstall === true) {
+        if (installFailed && true === s.dependsOnInstall) {
             skipped.add(s.target);
             continue;
         }
-        if (s.write !== undefined)
-            io.writeFile(s.write.path, s.write.content);
-        if (s.exec !== undefined && !io.exec(s.exec.command, s.exec.args)) {
+        const write = s.write;
+        if (write !== undefined) {
+            // Confirm the EFFECT, not the intention. Reported from the field (#160): init printed
+            // `[✓] Reticle config → .reticle.json` and the file was not there afterward. Nothing checked —
+            // no arrangement of the filesystem (a read-only mount, a full disk, an antivirus quarantining
+            // a new dotfile) could have turned that tick into anything else. A checkmark that cannot fail
+            // is decoration, and this one is the first thing a new user reads. Same shape as #139.
+            const wrote = spanSync('init.write', { target: s.target, path: write.path }, () => {
+                try {
+                    io.writeFile(write.path, write.content);
+                }
+                catch {
+                    return false; // a throw is the loud version of the same failure
+                }
+                return io.exists(write.path);
+            });
+            if (!wrote) {
+                failed.add(s.target);
+                continue; // do not run this step's exec against a file that is not there
+            }
+        }
+        // Bound once so the traced call cannot need a `?? ''` fallback — a default there would turn a
+        // narrowing mistake into an empty command that silently "succeeds".
+        const exec = s.exec;
+        // Per-step, because the interesting part of init's wall-clock is WHICH step spent it: a
+        // package-manager install and a `claude mcp add` are both subprocesses, and one of them being
+        // slow is a completely different problem from the other.
+        if (exec !== undefined &&
+            !spanSync('init.exec', { target: s.target, command: exec.command }, () => io.exec(exec.command, exec.args))) {
+            // A weaker second attempt beats no install at all — but only when it is REPORTED, because the
+            // thing it gives up is the version pin that keeps SDK and daemon in step.
+            //
+            // Traced separately, and it is the reason init can take twice as long as it looks like it
+            // should: this is a SECOND full package-manager run, and until it had its own span 1.6 of
+            // init's 2.3 seconds simply vanished — the span above accounted for the first attempt and
+            // nothing accounted for this one.
+            const retry = s.retry;
+            if (retry !== undefined &&
+                spanSync('init.exec.retry', { target: s.target, command: retry.command }, () => io.exec(retry.command, retry.args))) {
+                degraded.set(s.target, retry.note);
+                continue;
+            }
             failed.add(s.target);
-            if (s.target === DEPS_TARGET)
+            // A failed install only blocks the wiring when the packages are genuinely ABSENT. See
+            // sdkPackagesPresent: the guard protects "the import resolves", not "our subprocess exited 0".
+            if (s.target === DEPS_TARGET && !sdkPackagesPresent(plan.framework, io))
                 installFailed = true;
         }
     }
-    return { failed, skipped };
+    return { failed, skipped, degraded };
 }
 /**
  * Which STEP failed, from the step targets — not from an error string, which would carry paths.
@@ -338,25 +587,35 @@ const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle
  * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
  */
 function redirectToWorkspaceApp(options, io, pkgRaw) {
-    if (options.redirected === true)
+    if (true === options.redirected)
         return null;
     const pkg = JSON.parse(pkgRaw);
     const rootFiles = new Set(io.rootFiles());
     const here = detect({
-        pkg: typeof pkg === 'object' && pkg !== null ? pkg : {},
+        pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
         lockfiles: new Set(),
     });
     if (here.framework !== Framework.HTML)
         return null; // this directory IS the app
     const apps = findWorkspaceApps(io);
-    const target = apps.length === 1 ? apps[0] : undefined;
+    // An explicitly named app answers the ambiguity. Refusing to guess is right, but "re-run inside the
+    // one you want" is not something a script, a CI step, or an agent that cannot change directory can
+    // act on — so the refusal was a dead end for exactly the callers most likely to hit it.
+    const chosen = chooseWorkspaceApp(options.app, apps);
+    if (!chosen.ok) {
+        io.print(chosen.message);
+        return { ok: false, applied: 0, manual: 1 };
+    }
+    const target = chosen.app ?? (1 === apps.length ? apps[0] : undefined);
     if (target === undefined) {
-        if (apps.length === 0)
+        if (0 === apps.length)
             return null; // not a workspace — fall through to the normal HTML plan
         io.print(AMBIGUOUS_HEADER);
         for (const a of apps)
             io.print(`  ${a}`);
+        io.print('');
+        io.print(`Or name one without changing directory:  reticle init --app ${apps[0] ?? '<dir>'}`);
         return { ok: false, applied: 0, manual: apps.length };
     }
     io.print(`No app in this directory — wiring ${target} instead.`);
@@ -364,30 +623,62 @@ function redirectToWorkspaceApp(options, io, pkgRaw) {
     return runInit({ ...options, cwd: join(options.cwd, target), redirected: true }, io.scoped(target));
 }
 export function runInit(options, io) {
+    const result = runInitSteps(options, io);
+    // The ask goes here, not in report(): report() is only the success-shaped path, and the exits that
+    // matter most are the ones that never reach it — no package.json, an ambiguous workspace — where
+    // setup died before anything ran and the person holding the report has the least to go on. This
+    // wrapper is the one point every exit passes through.
+    //
+    // `redirected` is what keeps it to ONE print: wiring an app in a monorepo re-enters runInit for the
+    // chosen directory, and the inner call must not ask again.
+    if (true !== options.redirected) {
+        io.print('');
+        io.print(FEEDBACK_HINT);
+    }
+    return result;
+}
+function runInitSteps(options, io) {
     const pkgRaw = io.readFile(PACKAGE_JSON);
-    if (pkgRaw === null) {
-        io.print('No package.json found. Run `reticle init` from your project root.');
+    // Look for the app BEFORE concluding there isn't one.
+    //
+    // A root with no package.json is not a dead end — it is the ordinary shape of a repo whose app
+    // lives one directory down (`frontend/`, `web/`, `client/`) with no manifest at the top. Bailing
+    // first made that repo un-instrumentable: `reticle init` said "No package.json found", and
+    // `--app frontend`, the flag that exists for exactly this, was never read because the bail came
+    // first. Reported twice by the same user, who tried the documented workaround and hit the same
+    // wall. Discovery already handles the case (it scans top-level directories, not just declared
+    // workspaces); it was simply unreachable.
+    //
+    // `'{}'` because the redirect only needs the manifest to ask "is THIS directory the app", and a
+    // directory with no package.json is definitively not.
+    const redirectedEarly = redirectToWorkspaceApp(options, io, pkgRaw ?? '{}');
+    if (redirectedEarly !== null)
+        return redirectedEarly;
+    if (null === pkgRaw) {
+        io.print('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
+            "your app's directory, or from a repo root that contains it.");
         // The onboarding funnel had NO instrumentation, so a setup that died here was indistinguishable
         // from someone who never ran the command — the two failure modes with the most different fixes.
         reportInitOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
         return { ok: false, applied: 0, manual: 0 };
     }
-    const redirected = redirectToWorkspaceApp(options, io, pkgRaw);
-    if (redirected !== null)
-        return redirected;
-    const plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
+    // Init is the flow a user experiences the wait of personally, and the fixture gate measures it at
+    // 1–6s per app with no explanation of the spread. These three spans split that number into detect
+    // (filesystem probing), plan (pure), and apply (writes + package-manager and CLI subprocesses).
+    const plan = spanSync('init.plan', {}, () => buildPlan(gatherPlanInput(options, io, pkgRaw)));
     const effects = options.dryRun
-        ? { failed: new Set(), skipped: new Set() }
-        : applyEffects(plan, io);
-    const { failed, skipped } = effects;
-    const result = report(plan, options.dryRun, failed, skipped, io);
+        ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
+        : spanSync('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io));
+    const { failed, skipped, degraded } = effects;
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (!options.dryRun) {
         reportInitOutcome({
             ok: result.ok,
             ...(result.ok ? {} : { reason: classifyInitFailure(failed) }),
             stack: plan.framework,
-            mcpRegistered: !failed.has(MCP_TARGET),
+            // The step's REAL final status, not the absence of a failure — see mcp-registered.
+            mcpRegistered: wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped)),
         });
     }
     return result;

package/dist/init/slash-command.d.ts

@@ -15,4 +15,13 @@
 export declare const CLAUDE_COMMAND_PATH = ".claude/commands/reticle.md";
 /** Cursor reads them from `.cursor/commands/<name>.md`. */
 export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
+/**
+ * The frontmatter line that marks a command file as OURS.
+ *
+ * A stale command has to be refreshable — a file frozen at whatever release created it can never be
+ * improved for anyone who already ran init — but the path is one a human may have claimed for their
+ * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
+ * are told apart.
+ */
+export declare const SLASH_COMMAND_SIGNATURE = "description: Verify this app in the browser with Reticle";
 export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_sessions` \u2014 find the connected tab. None? Tell the user to run their dev server and open\n   the app, then stop. Reticle never starts a dev server.\n2. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n3. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n4. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n5. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n";

package/dist/init/slash-command.js

@@ -15,8 +15,17 @@
 export const CLAUDE_COMMAND_PATH = '.claude/commands/reticle.md';
 /** Cursor reads them from `.cursor/commands/<name>.md`. */
 export const CURSOR_COMMAND_PATH = '.cursor/commands/reticle.md';
+/**
+ * The frontmatter line that marks a command file as OURS.
+ *
+ * A stale command has to be refreshable — a file frozen at whatever release created it can never be
+ * improved for anyone who already ran init — but the path is one a human may have claimed for their
+ * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
+ * are told apart.
+ */
+export const SLASH_COMMAND_SIGNATURE = 'description: Verify this app in the browser with Reticle';
 export const SLASH_COMMAND_BODY = `---
-description: Verify this app in the browser with Reticle — drive one real flow and report what happened.
+${SLASH_COMMAND_SIGNATURE} — drive one real flow and report what happened.
 ---
 
 Verify this running app with Reticle. Drive it; do not read the code and guess.