@reticlehq/server 2.5.0 → 2.6.0

package/dist/init/plan.d.ts

@@ -4,6 +4,7 @@
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
 import { Framework, type Detection } from './detect.js';
+import { type McpClient } from './mcp-clients.js';
 /**
  * Pin the SDK to the CLI's own version.
  *
@@ -14,6 +15,8 @@ import { Framework, type Detection } from './detect.js';
  * irrelevant, and a skewed pair impossible to install by accident.
  */
 export declare function pinnedPackages(packages: readonly string[], version: string | undefined): readonly string[];
+/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
+export declare function frameworkPackages(framework: Framework): readonly string[];
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
 /** True when this step is what makes the app dial the daemon. */
@@ -90,6 +93,17 @@ export interface PlanInput {
     cursorConfig: string | null;
     /** Absolute path of ~/.cursor/mcp.json (the write target). */
     cursorConfigPath: string;
+    /**
+     * Every OTHER MCP client detected on this machine, with its config path and current content.
+     *
+     * Claude Code and Cursor keep their own steps — Claude registers through its CLI, and Cursor's
+     * predates this. Everything else is uniform: read the file, merge, write.
+     */
+    detectedClients?: readonly {
+        id: McpClient;
+        configPath: string;
+        existing: string | null;
+    }[] | undefined;
     /** Discovered Vite config: its path + source, or null if none found. */
     viteConfig: {
         path: string;

package/dist/init/plan.js

@@ -6,6 +6,7 @@
 import { Framework, PackageManager, UiLibrary, installCommand, installCommandParts, } from './detect.js';
 import { claudeAddCommand, mcpManual } from './mcp.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
+import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
 import { mergeMarkedInstruction, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
 import { viteSteps, nextSteps, craSteps, svelteKitSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
@@ -32,7 +33,7 @@ export function pinnedPackages(packages, version) {
     return packages.map((p) => `${p}@${version}`);
 }
 /** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-function frameworkPackages(framework) {
+export function frameworkPackages(framework) {
     switch (framework) {
         case Framework.NEXT:
             return [RETICLE_REACT_KIT, RETICLE_NEXT_PLUGIN];
@@ -142,6 +143,49 @@ function cursorMcpStep(input) {
         write: { path: input.cursorConfigPath, content: r.content },
     };
 }
+/**
+ * One step per OTHER detected client.
+ *
+ * The shapes differ enough that a shared "write mcp.json" would be wrong for three of them — see
+ * mcp-clients.ts. What is shared is the DECISION: already-correct is left alone, a file we cannot
+ * parse is reported with a paste-able block rather than overwritten, and everything else is written.
+ */
+function otherClientSteps(input) {
+    const steps = [];
+    for (const detected of input.detectedClients ?? []) {
+        const spec = clientSpec(detected.id);
+        const merged = mergeClientConfig(spec, detected.existing);
+        const title = `MCP server (${spec.label})`;
+        if (merged.status === ClientMergeStatus.ALREADY) {
+            steps.push({
+                title,
+                target: detected.configPath,
+                status: StepStatus.ALREADY,
+                detail: `reticle already registered with ${spec.label}`,
+            });
+            continue;
+        }
+        if (merged.status === ClientMergeStatus.MANUAL) {
+            // Either the file did not parse, or the format is one we refuse to edit blind (TOML). Both
+            // end the same way: say so, and hand over the exact block.
+            steps.push({
+                title,
+                target: detected.configPath,
+                status: StepStatus.MANUAL,
+                detail: `add this to ${detected.configPath} by hand:\n${clientSnippet(spec)}`,
+            });
+            continue;
+        }
+        steps.push({
+            title,
+            target: detected.configPath,
+            status: StepStatus.APPLY,
+            detail: `register reticle with ${spec.label}`,
+            write: { path: detected.configPath, content: merged.content },
+        });
+    }
+    return steps;
+}
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
     if (!input.options.mcp) {
@@ -157,7 +201,10 @@ function mcpSteps(input) {
             },
         ];
     }
-    const steps = stepsForAgents(input, (a) => a.mcpStep);
+    // Claude and Cursor first (they have their own registration paths), then every other detected
+    // client. A machine with Cursor AND Windsurf gets both — registering only the first one found is
+    // how a user ends up with Reticle in the editor they were not using.
+    const steps = [...stepsForAgents(input, (a) => a.mcpStep), ...otherClientSteps(input)];
     if (steps.length > 0)
         return steps;
     // No supported agent detected — print the one-time global instructions. Reached when the `claude`
@@ -348,13 +395,30 @@ function agentRuleSteps(input) {
  * with nothing naming a version. Pinning turns that into this loud failure, which is the better
  * trade — but only if the message says what to do about it.
  */
-/** Said out loud when the exact-version install was refused and the unpinned one worked. */
-function unpinnedRetryNote(version) {
+/**
+ * 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;
-    return (`the registry refused ${wanted} (pnpm's minimumReleaseAge holds new releases back), so the ` +
-        `newest ACCEPTED version was installed instead. That may not match the daemon — if the agent ` +
-        `reports protocol errors, check \`versionSkew\` in reticle_sessions, then either wait out the ` +
-        `window or allow these packages: pnpm config set minimumReleaseAgeExclude "@reticlehq/*"`);
+    // 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}`);
 }
 function installFailureHint(pm) {
     if (pm !== PackageManager.PNPM)
@@ -392,7 +456,7 @@ function installStep(input) {
         // release-age hold gets a working install instead of no install.
         retry: {
             ...installCommandParts(pm, frameworkPackages(input.detection.framework)),
-            note: unpinnedRetryNote(input.options.sdkVersion),
+            note: unpinnedRetryNote(input.options.sdkVersion, pm),
         },
     };
 }

package/dist/init/run.d.ts

@@ -7,8 +7,15 @@
  * 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'>): Set<string>;
+export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>, nodeModulesMarkers?: ReadonlySet<string>): Set<string>;
 export interface InitOptions {
     cwd: string;
     port: number | undefined;
@@ -59,5 +66,15 @@ interface InitResult {
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+/**
+ * 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 declare const FEEDBACK_HINT: string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
 export {};

package/dist/init/run.js

@@ -7,13 +7,13 @@ import { dirname, join } from 'node:path';
 import { spanSync } from '../trace.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { detect, Framework } from './detect.js';
+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 { CURSOR_RULE_PATH } from './agent-rules.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'];
@@ -40,11 +40,12 @@ function readPairingToken() {
         return '';
     }
 }
-import { DEPS_TARGET, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
+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';
@@ -62,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) {
@@ -83,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.
@@ -197,13 +208,15 @@ 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: '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);
@@ -225,6 +238,27 @@ function gatherPlanInput(options, io, pkgRaw) {
     // 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
@@ -253,6 +287,7 @@ function gatherPlanInput(options, io, pkgRaw) {
         claudeCli,
         mcpExists,
         cursorPresent,
+        detectedClients,
         cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
         cursorConfig,
         cursorConfigPath,
@@ -354,6 +389,19 @@ export function findWorkspaceApps(io) {
     }
     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".';
@@ -367,8 +415,13 @@ 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, degraded, 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;
@@ -429,6 +482,25 @@ function report(plan, dryRun, failed, skipped, degraded, 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();
@@ -443,9 +515,24 @@ function applyEffects(plan, io) {
         }
         const write = s.write;
         if (write !== undefined) {
-            spanSync('init.write', { target: s.target, path: write.path }, () => {
-                io.writeFile(write.path, write.content);
+            // 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".
@@ -469,7 +556,9 @@ function applyEffects(plan, io) {
                 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;
         }
     }
@@ -534,17 +623,45 @@ 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);
+    // 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. Run `reticle init` from your project root.');
+        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;
     // 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).
@@ -553,7 +670,7 @@ export function runInit(options, 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);
+    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({

package/dist/init/windows-quote.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+export declare function windowsShellArg(arg: string): string;

package/dist/init/windows-quote.js

@@ -0,0 +1,70 @@
+/**
+ * Quote one argument for a Windows command line. Pure, and deliberately NOT platform-gated.
+ *
+ * The rule used to live inside a `process.platform === WINDOWS` branch in node-io.ts, which meant
+ * the Windows path could not be exercised on a mac or in CI's Linux job — so it stayed wrong. A
+ * pure function is most of the fix: it can be asserted anywhere, and it is.
+ *
+ * ## What was wrong
+ *
+ * ```ts
+ * /[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg
+ * ```
+ *
+ * Two independent holes, both reachable from an ordinary directory path:
+ *
+ * 1. **Backslashes were not escaped.** `C:\Users\ada\My Projects\` became
+ *    `"C:\Users\ada\My Projects\"`, whose trailing `\"` reads as an ESCAPED quote — the quoted
+ *    region never closes and the rest of the line is re-parsed by cmd.exe. CodeQL flagged this one
+ *    (`js/incomplete-sanitization`, high).
+ * 2. **The predicate only looked for whitespace and quotes.** An argument like `foo&whoami` has
+ *    neither, so it was handed to cmd.exe completely unquoted. Correct backslash escaping does
+ *    nothing for that; it needs the metacharacters in the trigger.
+ *
+ * ## The rule implemented here
+ *
+ * `CommandLineToArgvW`: a run of backslashes is literal unless it precedes a `"`, in which case the
+ * run is doubled and the quote escaped; a run at the very end sits before the closing quote we add,
+ * so it is doubled too. Correctly-terminated quotes also neutralise cmd.exe's metacharacters, which
+ * it does not interpret inside a quoted region.
+ *
+ * ## Known limit, stated rather than papered over
+ *
+ * `%VAR%` is expanded by cmd.exe even inside quotes, and no quoting prevents it — only avoiding
+ * `shell: true` does, which Windows needs so `pnpm.cmd`/`npx.cmd` resolve (see `shellOpt`). That is
+ * variable substitution, not command execution, and every caller here passes paths and package
+ * names rather than user prose.
+ */
+/**
+ * Characters that make cmd.exe do something other than pass the text along.
+ *
+ * Whitespace and `"` split or delimit; the rest are the shell's control operators. An argument
+ * containing any of them must be quoted, not just one containing a space.
+ */
+const NEEDS_QUOTING = /[\s"&|<>^()!%,;=]/;
+export function windowsShellArg(arg) {
+    // An empty argument must still occupy a slot in argv. Unquoted it disappears entirely, silently
+    // shifting every argument after it by one.
+    if (0 === arg.length)
+        return '""';
+    if (!NEEDS_QUOTING.test(arg))
+        return arg;
+    let out = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if ('\\' === ch) {
+            backslashes += 1;
+            continue;
+        }
+        if ('"' === ch) {
+            // 2n+1 backslashes → n literal backslashes and an escaped quote.
+            out += '\\'.repeat(2 * backslashes + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        out += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // A trailing run sits immediately before the closing quote, so it must be doubled or it escapes it.
+    return `${out}${'\\'.repeat(2 * backslashes)}"`;
+}

package/dist/mcp/mcp-outage.d.ts

@@ -28,4 +28,5 @@ export declare function resetOutageReporting(): void;
 export declare function reportMcpOutage(stage: OutageStage, facts: {
     reason: string;
     attempts: number;
+    pendingLost?: number;
 }): void;

package/dist/mcp/mcp-outage.js

@@ -43,6 +43,13 @@ export function reportMcpOutage(stage, facts) {
         return;
     reported.add(stage);
     void getTelemetry().emit(TelemetryEventKind.MCP_CONNECTION_LOST, {
-        outage: { stage, reason: outageReason(facts.reason), attempts: facts.attempts },
+        outage: {
+            stage,
+            reason: outageReason(facts.reason),
+            attempts: facts.attempts,
+            // Always sent, including zero: zero is the finding — a drop no agent could feel. See
+            // McpOutageSchema.pendingLost.
+            pendingLost: facts.pendingLost ?? 0,
+        },
     });
 }

package/dist/mcp/mcp-proxy.d.ts

@@ -104,7 +104,17 @@ export declare class SseFrameParser {
 export declare function probeDaemon(port: number): Promise<boolean>;
 /** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
 export declare function waitForDaemon(port: number): Promise<void>;
-export declare function buildSessionUrl(rawData: string, port: number): string;
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * to reconnect and how to answer what it cannot send.
+ */
+export declare function buildSessionUrl(rawData: string, port: number): string | null;
 /**
  * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
  * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until stdin closes.