@reticlehq/server 2.11.0 → 2.13.0

package/dist/init/run.js

@@ -4,19 +4,23 @@
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
 import { dirname, join } from 'node:path';
+import { CSP_FILES } from './csp-doctor.js';
+import { preflightRefusal } from './preflight.js';
 import { noPackageJsonMessage } from './non-js-project.js';
+import { devCommandFrom } from './dev-script.js';
+import { restartHint, FEEDBACK_HINT } from './closing-hint.js';
 import { spanSync } from '../trace.js';
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { projectIdOf, rememberProjectOnDisk } from '../project/remember-project.js';
 import { detect, Framework, namesAPackageManager, UiLibrary } from './detect.js';
 import { wasMcpRegistered } from './mcp-registered.js';
 import { pickAstroHost } from './astro-host.js';
-import { workspaceParents } from './workspace-apps.js';
+import { findWorkspaceApps, NEXT_CONFIG_CANDIDATES, PACKAGE_JSON, VITE_CONFIG_CANDIDATES, } from './workspace-apps.js';
 import { chooseWorkspaceApp } from './app-choice.js';
 import { isConnectStep } from './connect-steps.js';
-import { CLI, CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
+import { CURSOR_RULE_PATH, RETICLE_MD_PATH } from './agent-rules.js';
 import { CRA_ENV_PATH } from './cra.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync } from '../bridge/pairing-token.js';
+import { formatGeneratedSource } from './format-generated.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) {
@@ -28,26 +32,20 @@ function craEntryOf(io) {
     return null;
 }
 /**
- * The daemon's pairing token, for the one stack that cannot read it at build time.
+ * The daemon's pairing token, minted here if nothing has written it yet.
  *
- * 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.
+ * `init` used to READ the file and return empty when the daemon had never started. The CDN snippet
+ * inlined that empty value permanently, and regenerating the token made the pasted literal stale.
+ * Same mint as the daemon (`readOrCreatePairingToken`), honours `RETICLE_PAIRING_TOKEN_DIR`.
  */
 function readPairingToken() {
-    try {
-        return readFileSync(join(homedir(), '.reticle', 'pairing-token'), 'utf8').trim();
-    }
-    catch {
-        return '';
-    }
+    return readOrCreatePairingTokenSync(defaultPairingTokenDir()) ?? '';
 }
 import { DEPS_TARGET, RETICLE_CONFIG_FILE, frameworkPackages, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
 import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
 import { reticleDevLocation } from './next-patch.js';
 import { scanTestids, storeHints, scanStores } from './capabilities.js';
-import { CURSOR_DIR_RELPATH, CURSOR_MCP_RELPATH } from './cursor.js';
-import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient } from './mcp-clients.js';
+import { fileBackedClients, clientMarkerRelPath, ConfigScope, McpClient, CURSOR_PROJECT_MARKER, } from './mcp-clients.js';
 import { deriveProjectId, packageName } from './project-id.js';
 import { VITE_DEV_MODULE_PATH, connectArgWithToken, staticPageSnippet } from './snippets.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './slash-command.js';
@@ -94,7 +92,6 @@ export function resolveLockfiles(rootFiles, cwd, io, nodeModulesMarkers = new Se
     }
     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
@@ -198,12 +195,6 @@ function dependencyNames(pkg) {
         ...Object.keys(p['devDependencies'] ?? {}),
     ]);
 }
-const VITE_CONFIG_CANDIDATES = [
-    'vite.config.ts',
-    'vite.config.js',
-    'vite.config.mjs',
-    'vite.config.mts',
-];
 const ASTRO_CONFIG_CANDIDATES = [
     'astro.config.mjs',
     'astro.config.js',
@@ -214,12 +205,6 @@ const ASTRO_CONFIG_CANDIDATES = [
 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',
-    'next.config.ts',
-    'next.config.cjs',
-];
 /**
  * `⚠` means WORK LEFT TO DO and nothing else — it is what an agent (and the release gate) counts to
  * decide whether the install finished. A notice gets its own mark so "steps remaining" can reach zero
@@ -264,8 +249,7 @@ function agentRootOf(options) {
     const root = options.agentRoot;
     return root === undefined || root === options.cwd ? undefined : root;
 }
-function gatherPlanInput(options, io, pkgRaw) {
-    const pkg = JSON.parse(pkgRaw);
+function gatherPlanInput(options, io, pkg) {
     // 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());
@@ -289,32 +273,25 @@ 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;
-    // 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.
+    // Every 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.
     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))
+            // A fresh Cursor profile has not written ~/.cursor yet; the project-level .cursor/ is the
+            // fallback that kept that real case working. Same signal, project scope.
+            const projectFallback = spec.id === McpClient.CURSOR && !io.exists(markerPath)
+                ? io.exists(CURSOR_PROJECT_MARKER)
+                : false;
+            if (!io.exists(markerPath) && !projectFallback)
                 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),
             };
         })
@@ -347,20 +324,27 @@ function gatherPlanInput(options, io, pkgRaw) {
     const sourceFiles = readSourceFiles(io);
     const agentRoot = agentRootOf(options);
     const agentFile = (relPath) => agentRoot === undefined ? relPath : join(agentRoot, relPath);
+    const cspSources = {};
+    for (const file of CSP_FILES) {
+        const source = io.readFile(file);
+        if (null !== source)
+            cspSources[file] = source;
+    }
     return {
         detection,
+        captureBodies: options.captureBodies,
+        cspSources,
         claudeCli,
         mcpExists,
-        cursorPresent,
+        platform: process.platform,
         detectedClients,
-        cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
-        cursorConfig,
-        cursorConfigPath,
+        cursorProjectPresent: io.exists(CURSOR_PROJECT_MARKER),
         viteConfig,
         astroConfig: astroPath !== null && astroSource !== null ? { path: astroPath, source: astroSource } : null,
         astroLayout: layoutRelPath !== null && astroLayoutSource !== null
             ? { path: layoutRelPath, source: astroLayoutSource }
             : null,
+        astroEnvDts: io.readFile('src/env.d.ts'),
         nextConfigFile,
         nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
         nextLayout: layoutPath !== null && layoutSource !== null
@@ -375,6 +359,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         nextReticleDevPath: devLocation.path,
         nextReticleDevImport: devLocation.importSpecifier,
         nextReticleDevExists: io.exists(devLocation.path),
+        nextReticleDevSource: io.readFile(devLocation.path),
         svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
         craEntry: craEntryOf(io),
         craEnv: io.readFile(CRA_ENV_PATH),
@@ -410,149 +395,19 @@ function gatherPlanInput(options, io, pkgRaw) {
 }
 /** Where workspace tooling conventionally puts 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 (null === pkgRaw)
-        return false;
-    const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
-    if (configs.some((c) => io.exists(`${dir}/${c}`)))
-        return true;
-    // `next.config` is optional in Next, so the dependency list is the other half of the signal.
-    return APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`));
-}
-/**
- * App directories under a workspace root.
- *
- * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
- * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
- * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
- * it knows it is in a workspace; this is the matching walk DOWN.
- */
-export function findWorkspaceApps(io) {
-    const found = [];
-    // 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 [...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 devServerRestart(framework) {
-    if (framework === Framework.NEXT)
-        return 'Restart `next dev`';
-    if (framework === Framework.VITE)
-        return 'Restart `vite`';
-    if (framework === Framework.ASTRO)
-        return 'Restart `astro dev`';
-    if (framework === Framework.SVELTEKIT)
-        return 'Restart your dev server (`npm run dev`)';
-    return 'Reload your app on localhost';
-}
+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, degraded, io, projectDir, agentRoot, 
+/** The project's own dev command, so the closing line names what a human would type. */
+devCommand, 
 /**
- * The last two lines a user reads, and the order matters.
+ * Whether this run continues into the phases that boot the app and drive it.
  *
- * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
- * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
- * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
- * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
- * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
- * failed.
- *
- * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
- * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ * The closing hint tells the reader to restart their dev server and then drive a flow. When those
+ * are the very next things this command does, printing them is worse than noise: it is an
+ * instruction to do by hand what is about to happen automatically, three lines before it happens.
  */
-export function restartHint(framework, mcpStatus) {
-    const dev = `${devServerRestart(framework)}.`;
-    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
-    //
-    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
-    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
-    // people complete the agent half, never complete the app half, and keep a daemon running for
-    // weeks with nothing to drive — so this is the last instruction most of them read.
-    //
-    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
-    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
-    // running, an app running that never dialled us, a tab that closed — with the fix for each.
-    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
-        'it has not.';
-    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
-    // up nothing, so advice about one would be advice about something we did not do.
-    if (!wasMcpRegistered(mcpStatus))
-        return `${dev} ${prove}`;
-    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
-    //
-    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
-    // was written for and wrong here, because the two cases have opposite answers to "must anybody
-    // restart". Every second project on a machine, and every Claude Code plugin install, took the
-    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
-    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
-    // stops with the project wired and nothing driven, which is the exact failure the install path
-    // exists to prevent, caused by the install path itself.
-    if (mcpStatus === StepStatus.ALREADY) {
-        return (`${dev}\n` +
-            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
-            'and the tools are available now.\n' +
-            `${prove}\n` +
-            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
-            'nothing here is waiting on a human.');
-    }
-    return (`${dev}\n` +
-        'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
-        'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
-        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
-        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
-        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
-        'project starts with the tools already there.\n' +
-        `${prove}\n` +
-        'Once it shows a session, ask your agent to drive a flow — that is the install finished.');
-}
-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, degraded, io, projectDir, agentRoot) {
+continuesToRuntime = false) {
     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
@@ -612,7 +467,9 @@ function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRo
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
-    io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped)));
+    if (!continuesToRuntime) {
+        io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped), devCommand));
+    }
     return { ok: !connectPending, applied, manual };
 }
 /**
@@ -664,7 +521,10 @@ function applyEffects(plan, io) {
             // 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);
+                    // Format connect modules with the project's Prettier when present (#684) — a clean
+                    // install must not fail the project's own lint on a file we just wrote.
+                    const content = formatGeneratedSource(write.content, write.path, io.cwd());
+                    io.writeFile(write.path, content);
                 }
                 catch {
                     return false; // a throw is the loud version of the same failure
@@ -739,16 +599,36 @@ const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle
  * guessing which app someone meant is worse than one line of output.
  * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
  */
-function redirectToWorkspaceApp(options, io, pkgRaw) {
+function redirectToWorkspaceApp(options, io, pkg) {
     if (true === options.redirected)
         return null;
-    const pkg = JSON.parse(pkgRaw);
     const rootFiles = new Set(io.rootFiles());
     const here = detect({
         pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
         lockfiles: new Set(),
     });
+    // `--app` is an INSTRUCTION, and it is read before the guess below. The guess answers "where is
+    // the app?" for somebody who did not say; when somebody said, there is nothing left to infer.
+    //
+    // It used to be read after, and the check underneath returns early for any directory that looks
+    // like an app — which a JS monorepo ROOT does, because shared tooling puts `vite` in its
+    // devDependencies. So on a real pnpm+turbo monorepo (measured on nuclear, a Tauri v2 app at
+    // product scale) `reticle init --app packages/player` silently ignored the flag, installed the
+    // SDK into the root's package.json, wrote `.reticle.json` and a whole `src/reticle-dev.ts` into a
+    // repository root that has no `src/`, left `packages/player` untouched — and reported three ✓ and
+    // one ⚠. The one flag documented for this shape wired the wrong directory and said it worked.
+    //
+    // Existence is the test, not membership of the discovered list: discovery scans conventional
+    // directories, and somebody who names a path knows their own layout better than the scan does.
+    const named = options.app === undefined || '' === options.app ? undefined : options.app;
+    if (named !== undefined) {
+        const wanted = named.replace(/\/+$/, '');
+        if (io.exists(`${wanted}/${PACKAGE_JSON}`))
+            return enterApp(options, io, wanted, 'Wiring');
+        io.print(`--app ${named} does not name a directory with a package.json in it.`);
+        return { ok: false, applied: 0, manual: 1 };
+    }
     if (here.framework !== Framework.HTML)
         return null; // this directory IS the app
     const apps = findWorkspaceApps(io);
@@ -771,7 +651,18 @@ function redirectToWorkspaceApp(options, io, pkgRaw) {
         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.`);
+    return enterApp(options, io, target, 'No app in this directory — wiring');
+}
+/**
+ * Re-enter `init` scoped to one directory of a workspace.
+ *
+ * One implementation for both routes in — the app somebody NAMED and the app discovery found when
+ * nobody did. They differ only in the sentence printed; scoping the io, moving the cwd and keeping
+ * the agent root has to be identical for both, and was worth having twice for exactly as long as it
+ * took to get one of them wrong.
+ */
+function enterApp(options, io, target, lead) {
+    io.print(`${lead} ${target}.`);
     io.print('');
     return runInit({
         ...options,
@@ -797,8 +688,42 @@ export function runInit(options, io) {
     }
     return result;
 }
+/**
+ * The manifest, parsed once, or the reason it could not be.
+ *
+ * It used to be parsed in three places from the same raw string, and two of them were unguarded —
+ * so `reticle init` on a `package.json` with a trailing comma died with a raw `SyntaxError` and a
+ * stack through `redirectToWorkspaceApp`. A stack trace in front of a user is a bug whatever caused
+ * it, and this one lands on the very first thing the command does, before it has said anything.
+ *
+ * `setup/reticle.mjs` has always got this right ("… is not valid JSON (…). Fix it and re-run"). The
+ * shipped CLI did not, which is the shape of every divergence between the two: the prototype refuses
+ * politely, `init` throws. Parsing once at the single point the file enters means no later caller
+ * CAN reintroduce it — a guard per call site would have been three guards and a fourth one waiting.
+ */
+function readManifest(io) {
+    const raw = io.readFile(PACKAGE_JSON);
+    if (null === raw)
+        return { pkg: null };
+    try {
+        return { pkg: JSON.parse(raw) };
+    }
+    catch (err) {
+        // First line only: JSON.parse's message carries the offending position, and the rest is noise.
+        const detail = String(err instanceof Error ? err.message : err).split('\n')[0] ?? 'unparseable';
+        return { error: detail };
+    }
+}
 function runInitSteps(options, io) {
-    const pkgRaw = io.readFile(PACKAGE_JSON);
+    const manifest = readManifest(io);
+    if ('error' in manifest) {
+        io.print(`${PACKAGE_JSON} is not valid JSON (${manifest.error}). Fix it and re-run — init reads the ` +
+            'framework, the dev script and the package manager from it, and will not guess at any of ' +
+            'them from a file it cannot read.');
+        reportInitOutcome({ ok: false, reason: InitFailure.MALFORMED_PACKAGE_JSON });
+        return { ok: false, applied: 0, manual: 0 };
+    }
+    const pkgRaw = manifest.pkg;
     // 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
@@ -811,7 +736,7 @@ function runInitSteps(options, io) {
     //
     // `'{}'` 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 ?? '{}');
+    const redirectedEarly = redirectToWorkspaceApp(options, io, pkgRaw ?? {});
     if (redirectedEarly !== null)
         return redirectedEarly;
     if (null === pkgRaw) {
@@ -834,12 +759,29 @@ function runInitSteps(options, io) {
     // 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 planInput = gatherPlanInput(options, io, pkgRaw);
+    // Before anything is written, and AFTER detection — the package manager to check is the one init
+    // RESOLVED, not a raw lockfile read. An inherited pnpm-lock.yaml at a monorepo root does not mean
+    // the app in frontend/ uses pnpm, and checking the file refused a scaffold the install gate proves
+    // must succeed. Both conditions make every later phase fail, and each arrives far from its cause
+    // when it is not checked here. See preflight.ts.
+    const refusal = preflightRefusal({
+        cwd: () => io.cwd(),
+        canWrite: () => io.canWrite(),
+        probe: (command, args) => io.probe(command, args),
+    }, planInput.detection.packageManager);
+    if (refusal !== undefined) {
+        io.print(refusal);
+        return { ok: false, applied: 0, manual: 1 };
+    }
+    const plan = spanSync('init.plan', {}, () => buildPlan(planInput));
     const effects = options.dryRun
         ? { 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, agentRootOf(options));
+    // The project's own dev command, so the closing line names what a human would actually type.
+    const devCommand = devCommandFrom(pkgRaw, planInput.detection.packageManager);
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io, options.cwd, agentRootOf(options), devCommand, true === options.continuesToRuntime);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (options.dryRun)
         return result;
@@ -850,8 +792,15 @@ function runInitSteps(options, io) {
         // The step's REAL final status, not the absence of a failure — see mcp-registered.
         mcpRegistered: wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped)),
     };
+    const context = {
+        appDir: options.cwd,
+        framework: plan.framework,
+        packageManager: planInput.detection.packageManager,
+        ...(undefined === devCommand ? {} : { devCommand }),
+        ...(true === options.redirected ? { redirectedTo: options.cwd } : {}),
+    };
     if (true === options.deferOutcome)
-        return { ...result, outcome };
+        return { ...result, context, outcome };
     reportInitOutcome(outcome);
-    return result;
+    return { ...result, context };
 }

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

@@ -24,4 +24,4 @@ export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
  * 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## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\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_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.\n2. 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.\n3. 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.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\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\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";
+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## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\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_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.\n2. 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.\n3. 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.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\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\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";