robot-resources 1.14.2 → 1.15.1

package/bin/setup.js

@@ -25,13 +25,18 @@ if (args.includes('--uninstall')) {
   const scopeArg = args.find((a) => a.startsWith('--scope='));
   const scope = scopeArg ? scopeArg.slice('--scope='.length) : 'full';
 
+  // Phase 11: --auto-attach-source opts into source-edit injection in non-
+  // interactive contexts (CI). Default off — auto-rewriting source files
+  // without consent is too aggressive. Interactive runs always show Y/N.
+  const autoAttachSource = args.includes('--auto-attach-source');
+
   // Treat piped/CI runs (no TTY on stdin OR stdout) as non-interactive so the
   // wizard never blocks on a prompt that can't be answered. The interactive
   // menu is only opened when both stdin and stdout are real terminals.
   const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   const nonInteractive = explicitNonInteractive || !hasTty;
 
-  runWizard({ nonInteractive, target, scope }).catch((err) => {
+  runWizard({ nonInteractive, target, scope, autoAttachSource }).catch((err) => {
     console.error(`\n  ✗ Setup failed: ${err.message}\n`);
     process.exit(1);
   });

package/lib/detect.js

@@ -137,7 +137,10 @@ export function isCursorInstalled() {
 // means a generic project (e.g. just package.json, no LLM SDK deps yet) —
 // still picks the language but with low confidence.
 
-const NODE_AGENT_DEPS = [
+// Exported (Phase 11.1) so the SDK-import scanner in source-edit-attach.js
+// can reuse the same canonical list — single source of truth for "which npm
+// packages count as an AI SDK signal."
+export const NODE_AGENT_DEPS = [
   '@anthropic-ai/sdk',
   'openai',
   '@google/generative-ai',

package/lib/non-oc-wizard.js

@@ -1,12 +1,20 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { select } from '@inquirer/prompts';
+import { extname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { select, input } from '@inquirer/prompts';
 import { isClaudeCodeInstalled, isCursorInstalled, detectAgentRuntime } from './detect.js';
 import { configureClaudeCode, configureCursor } from './tool-config.js';
-import { header, info, success, warn, blank } from './ui.js';
+import { header, info, success, warn, blank, confirm } from './ui.js';
 import { readConfig } from './config.mjs';
 import { installNodeShim } from './install-node-shim.js';
 import { installPythonShim } from './install-python-shim.js';
+import {
+  findAgentSourceFile,
+  hasSourceMarker,
+  writeSourceMarker,
+  previewInjection,
+  pathForTelemetry,
+} from './source-edit-attach.js';
 
 const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
 
@@ -89,7 +97,259 @@ async function emitPathChosen(path) {
   }
 }
 
-async function showJsPath() {
+async function emitNodeEntryPatched(payload) {
+  const config = readConfig();
+  if (!config.api_key) return;
+  try {
+    await fetch(`${PLATFORM_URL}/v1/telemetry`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${config.api_key}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        product: 'cli',
+        event_type: 'node_entry_patched',
+        payload: { ...payload, platform: process.platform },
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    // Best-effort — never let telemetry break the install path.
+  }
+}
+
+const VALID_SOURCE_EXTS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
+
+/**
+ * Expand `~` to $HOME. Same trick shells use. Anything else (env vars,
+ * `..` segments) we leave to `path.resolve` to handle.
+ */
+function expandPath(raw, cwd) {
+  let p = raw.trim();
+  if (p === '~') p = homedir();
+  else if (p.startsWith('~/') || p.startsWith('~\\')) p = join(homedir(), p.slice(2));
+  if (!isAbsolute(p)) p = resolve(cwd, p);
+  return p;
+}
+
+/**
+ * Phase 11 + 11.1 — offer to inject `require('@robot-resources/router/auto')`
+ * (or ESM equivalent) at the top of the user's entry file. Phase 11 wrote
+ * the plumbing; Phase 11.1 swaps the package.json-gated detector for an
+ * SDK-import scanner that finds files actually talking to AI models.
+ *
+ * Why source-edit at all: NODE_OPTIONS in shell config never reaches cron /
+ * Docker / systemd / Lambda agents because those launchers don't read shell
+ * rc files. A line in the source survives any launcher.
+ *
+ * Decision matrix (now driven by findAgentSourceFile):
+ *   - 0 SDK files found → free-text path prompt (interactive) or skip (CI)
+ *   - 1 candidate            → preview + Y/N (skip the chooser)
+ *   - 2+, clear winner      → preview winner + Y/N (skip the chooser)
+ *   - 2+, ambiguous          → select() chooser, then Y/N
+ *   - Marker already present → skip silently
+ *   - Non-interactive without `autoAttachSource` → skip with a hint
+ *
+ * Source files are sacred — every accept path goes through Y/N (or the
+ * explicit `--auto-attach-source` opt-in for CI).
+ */
+async function maybeInjectSourceEdit({ nonInteractive, autoAttachSource, cwd = process.cwd() } = {}) {
+  const scan = findAgentSourceFile(cwd);
+  const baseTelemetry = {
+    candidates_scanned: scan.scanned,
+    total_files_walked: scan.walked,
+    winner_score: scan.candidates[0]?.score ?? null,
+    runner_up_score: scan.candidates[1]?.score ?? null,
+  };
+
+  // ── 0 candidates ───────────────────────────────────────────────────────
+  if (!scan.winner) {
+    if (nonInteractive) {
+      blank();
+      info(`We scanned ${scan.walked} source files and found no AI SDK imports.`);
+      info('Add this line manually at the top of your agent entry file:');
+      info("  require('@robot-resources/router/auto');   // CJS, or import '...' for ESM/TS");
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'no_sdk_imports_found' });
+      return;
+    }
+
+    // Interactive 0-candidate: ask the user to point us at the file.
+    blank();
+    info(`We scanned ${scan.walked} source files in this directory and found no AI SDK imports.`);
+    blank();
+    let raw;
+    try {
+      raw = await input({
+        message: 'Path to your agent file (or press Enter to skip):',
+        default: '',
+      });
+    } catch {
+      // Ctrl-C or terminal closed.
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'declined_path_prompt' });
+      return;
+    }
+    if (!raw || !raw.trim()) {
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'declined_path_prompt' });
+      return;
+    }
+
+    const target = expandPath(raw, cwd);
+    if (!existsSync(target)) {
+      warn(`File does not exist: ${target}`);
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'failed', error: 'path_missing' });
+      return;
+    }
+    if (!VALID_SOURCE_EXTS.has(extname(target).toLowerCase())) {
+      warn(`Refusing to edit ${extname(target)} — only .js/.mjs/.cjs/.ts/.tsx/.jsx are supported.`);
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'failed', error: 'invalid_extension' });
+      return;
+    }
+    if (hasSourceMarker(target)) {
+      info(`${pathForTelemetry(target, cwd)} already has the auto-attach line — leaving it as-is.`);
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'already_present', entry_path: pathForTelemetry(target, cwd) });
+      return;
+    }
+
+    // Outside-cwd: extra confirmation. The user meant a path relative to
+    // their project; if they typed something far away, double-check.
+    const isOutsideCwd = !target.startsWith(cwd + '/') && target !== cwd;
+    if (isOutsideCwd) {
+      const ok = await confirm(`${target} is outside your current directory. Edit it anyway?`, { defaultYes: false });
+      if (!ok) {
+        await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'declined_path_prompt' });
+        return;
+      }
+    }
+
+    return await applyInjection({
+      target,
+      cwd,
+      nonInteractive,
+      autoAttachSource,
+      baseTelemetry,
+      viaPrompt: true,
+    });
+  }
+
+  // ── 1+ candidates ──────────────────────────────────────────────────────
+  const winnerPath = scan.winner;
+
+  if (hasSourceMarker(winnerPath)) {
+    info(`${pathForTelemetry(winnerPath, cwd)} already has the auto-attach line — leaving it as-is.`);
+    await emitNodeEntryPatched({
+      ...baseTelemetry,
+      outcome: 'already_present',
+      entry_path: pathForTelemetry(winnerPath, cwd),
+    });
+    return;
+  }
+
+  if (nonInteractive && !autoAttachSource) {
+    blank();
+    info('Skipping source-attach in non-interactive mode (auto-rewriting source needs consent).');
+    info(`To enable it in CI, re-run with:  npx robot-resources --for=langchain --auto-attach-source`);
+    info(`Or add this line manually at the top of ${pathForTelemetry(winnerPath, cwd)}:`);
+    info("  require('@robot-resources/router/auto');   // CJS, or import '...' for ESM/TS");
+    await emitNodeEntryPatched({
+      ...baseTelemetry,
+      outcome: 'skipped_non_interactive',
+      entry_path: pathForTelemetry(winnerPath, cwd),
+    });
+    return;
+  }
+
+  // Resolve the actual target. Skip the chooser when winner is unambiguous —
+  // most users see exactly one Y/N.
+  let target = winnerPath;
+  if (!nonInteractive && scan.ambiguous && scan.candidates.length > 1) {
+    const choices = scan.candidates.slice(0, 6).map((c) => ({
+      name: `${pathForTelemetry(c.path, cwd)}  (score ${c.score})`,
+      value: c.path,
+    }));
+    choices.push({ name: 'Skip — I\'ll add the line manually', value: '__skip__' });
+    try {
+      target = await select({
+        message: 'Multiple files import an AI SDK. Which one is your agent?',
+        default: winnerPath,
+        choices,
+      });
+    } catch {
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'declined' });
+      return;
+    }
+    if (target === '__skip__') {
+      await emitNodeEntryPatched({ ...baseTelemetry, outcome: 'declined' });
+      return;
+    }
+  }
+
+  return await applyInjection({
+    target,
+    cwd,
+    nonInteractive,
+    autoAttachSource,
+    baseTelemetry,
+    viaPrompt: false,
+  });
+}
+
+/**
+ * Common write path used by both the "winner detected" and "user typed a
+ * path" branches. Shows the diff, asks Y/N (unless --auto-attach-source),
+ * writes the marker, emits telemetry. Single source of truth so the two
+ * branches can't drift.
+ */
+async function applyInjection({ target, cwd, nonInteractive, autoAttachSource, baseTelemetry, viaPrompt }) {
+  const preview = previewInjection(target);
+  blank();
+  success('Add the auto-attach line so routing also works under cron / Docker / systemd / Lambda?');
+  blank();
+  info(`File: ${pathForTelemetry(target, cwd)}`);
+  blank();
+  for (const line of preview.split('\n')) info(line);
+  blank();
+
+  let proceed = autoAttachSource;
+  if (!nonInteractive && !autoAttachSource) {
+    proceed = await confirm('Add the line?', { defaultYes: true });
+  }
+
+  if (!proceed) {
+    info('Skipped — you can re-run anytime.');
+    await emitNodeEntryPatched({
+      ...baseTelemetry,
+      outcome: 'declined',
+      entry_path: pathForTelemetry(target, cwd),
+    });
+    return;
+  }
+
+  const result = writeSourceMarker(target);
+  if (result.ok) {
+    success(`Added the auto-attach line to ${pathForTelemetry(target, cwd)} (${result.syntax}).`);
+    if (result.backupWritten) info(`  Backup written to ${pathForTelemetry(`${target}.rr-backup`, cwd)}`);
+    info('Now your agent loads the router on every startup — no env vars, no terminal restart.');
+    await emitNodeEntryPatched({
+      ...baseTelemetry,
+      outcome: viaPrompt ? 'patched_via_prompt' : 'patched',
+      entry_path: pathForTelemetry(target, cwd),
+      import_syntax: result.syntax,
+      backup_written: !!result.backupWritten,
+    });
+  } else {
+    warn(`Could not patch ${pathForTelemetry(target, cwd)}: ${result.error}`);
+    info('You can add the line yourself — see the snippet above.');
+    await emitNodeEntryPatched({
+      ...baseTelemetry,
+      outcome: 'failed',
+      entry_path: pathForTelemetry(target, cwd),
+      error: result.error,
+    });
+  }
+}
+
+async function showJsPath({ nonInteractive = false, autoAttachSource = false } = {}) {
   blank();
   success('JS/TS integration');
   blank();
@@ -105,14 +365,10 @@ async function showJsPath() {
       }
     }
     blank();
-    info('Once your shell picks up the new NODE_OPTIONS, every Node agent on');
-    info('this machine routes Anthropic, OpenAI, and Google SDK calls through');
-    info('Robot Resources.');
-    if (process.platform === 'win32') {
-      info('Open a new cmd / PowerShell window — current terminals will not see the change.');
-    } else {
-      info('Open a new terminal — or run:  source ~/.zshrc   (or your shell rc)');
-    }
+    info('Phase 3+ NODE_OPTIONS shim installed. Works for desktop dev sessions');
+    info('after a terminal restart, but does NOT reach cron / Docker / systemd /');
+    info('Lambda. The next step adds a one-line require to your agent source so');
+    info('routing works regardless of how the process is launched.');
   } else {
     warn(result.message);
     blank();
@@ -124,6 +380,11 @@ async function showJsPath() {
       info('  export NODE_OPTIONS="${NODE_OPTIONS:-} --require ~/.robot-resources/router/auto.cjs"');
     }
   }
+
+  // Phase 11 — source-edit injection. Reaches cron / Docker / systemd / Lambda
+  // since the line lives in the user's source, not in shell config.
+  await maybeInjectSourceEdit({ nonInteractive, autoAttachSource });
+
   blank();
   info('Docs: https://robotresources.ai/docs/langchain');
   blank();
@@ -204,9 +465,9 @@ function showInstallOcPath() {
   blank();
 }
 
-async function runPath(path) {
+async function runPath(path, opts = {}) {
   switch (path) {
-    case 'js': await showJsPath(); break;
+    case 'js': await showJsPath(opts); break;
     case 'python': await showPythonPath(); break;
     case 'mcp': showMcpPath(); break;
     case 'docs': showDocsPath(); break;
@@ -221,11 +482,11 @@ async function runPath(path) {
  * - non-interactive AND no target: print hint with --for= options and exit
  * - interactive: 5-option menu via @inquirer/prompts.select
  */
-export async function runNonOcWizard({ nonInteractive = false, target = null } = {}) {
+export async function runNonOcWizard({ nonInteractive = false, target = null, autoAttachSource = false } = {}) {
   const normalized = normalizeTarget(target);
 
   if (normalized) {
-    await runPath(normalized);
+    await runPath(normalized, { nonInteractive, autoAttachSource });
     await emitPathChosen(normalized);
     return;
   }
@@ -249,7 +510,7 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
       info(`Detected a ${autoTarget === 'js' ? 'Node' : 'Python'} project — installing the matching shim automatically.`);
       info('  Pass --for=<other> to override, or --uninstall to remove later.');
       blank();
-      await runPath(autoTarget);
+      await runPath(autoTarget, { nonInteractive, autoAttachSource });
       await emitPathChosen(autoTarget);
       return;
     }
@@ -334,7 +595,9 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
     if (autoTarget) {
       info(`Detected a ${autoTarget === 'js' ? 'Node' : 'Python'} project — installing the matching shim automatically.`);
       blank();
-      await runPath(autoTarget);
+      // Treat the timed-out interactive session as non-interactive for the
+      // source-edit step too — we don't have a TTY to ask the Y/N on.
+      await runPath(autoTarget, { nonInteractive: true, autoAttachSource });
       await emitPathChosen(autoTarget);
       return;
     }
@@ -347,6 +610,6 @@ export async function runNonOcWizard({ nonInteractive = false, target = null } =
     return;
   }
 
-  await runPath(chosen);
+  await runPath(chosen, { nonInteractive, autoAttachSource });
   await emitPathChosen(chosen);
 }

package/lib/source-edit-attach.js

@@ -0,0 +1,469 @@
+import { existsSync, readFileSync, writeFileSync, statSync, unlinkSync, readdirSync, openSync, readSync, closeSync } from 'node:fs';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { NODE_AGENT_DEPS } from './detect.js';
+
+/**
+ * Source-edit injection for non-OC Node agents (Phase 11).
+ *
+ * The Phase-3 NODE_OPTIONS approach only reaches processes that inherit
+ * from a shell that loaded ~/.bashrc or ~/.zshrc. Cron / Docker / systemd /
+ * Lambda / Cloud Run / serverless functions do NOT inherit shell rc files,
+ * so the shim never loads in the agents that matter most. Funnel data
+ * showed a 45-point cliff: 53% reach `node_shim_installed`, only 8.6% ever
+ * emit `adapter_attached`.
+ *
+ * This module injects ONE LINE at the top of the user's entry source file:
+ *
+ *   // >>> robot-resources: auto-attach >>>
+ *   require('@robot-resources/router/auto');
+ *   // <<< robot-resources <<<
+ *
+ * (or `import '@robot-resources/router/auto';` for ESM/TS files.)
+ *
+ * The line runs whenever the agent process starts, regardless of how it
+ * was launched. Cron, Docker, systemd, Lambda — all work the same.
+ *
+ * Marker-block convention mirrors shell-config.js exactly so an `--uninstall`
+ * remove pass is text-based and never destructive on partial state.
+ *
+ * Backup: a `.rr-backup` is written once on first inject (never overwritten
+ * on re-inject) so `--uninstall --purge` can restore the original source
+ * even if the marker block was tampered with.
+ */
+
+export const MARK_BEGIN = '// >>> robot-resources: auto-attach >>>';
+export const MARK_END = '// <<< robot-resources <<<';
+
+const REQUIRE_LINE = "require('@robot-resources/router/auto');";
+const IMPORT_LINE = "import '@robot-resources/router/auto';";
+
+/**
+ * Decide which import syntax to inject for a given source file.
+ * Implements Node's resolution rules verbatim:
+ *   .cjs → cjs
+ *   .mjs → esm
+ *   .ts / .tsx → emit `import` (works under both ts-node CJS and tsx/ESM)
+ *   .js / .jsx → walk up to nearest package.json, check "type" field.
+ *                "module" → esm; anything else (or absent) → cjs.
+ */
+export function detectImportSyntax(entryPath) {
+  const ext = extname(entryPath).toLowerCase();
+  if (ext === '.cjs') return 'cjs';
+  if (ext === '.mjs') return 'esm';
+  if (ext === '.ts' || ext === '.tsx') return 'esm';
+
+  // Walk up from the file's directory until we hit a package.json or
+  // exhaust the path. This is what Node itself does for `.js` files.
+  let dir = dirname(resolve(entryPath));
+  while (true) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.type === 'module' ? 'esm' : 'cjs';
+      } catch {
+        return 'cjs';
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return 'cjs';
+    dir = parent;
+  }
+}
+
+// Phase 11.1 — directories pruned during the recursive walk. Skipping these
+// is the difference between a 50ms walk and a 30s one. Hardcoded — chasing
+// `.gitignore` would add a transitive dep risk for marginal coverage gain
+// (real false-positive rate from these dirs is already ~0).
+const SKIP_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.next', 'out', 'coverage',
+  '.git', 'venv', '.venv', '__pycache__', '.svelte-kit', 'target',
+]);
+
+// Walker bounds. 4KB read because imports are always hoisted to the top of
+// the file — anything below isn't an import, and reading more is waste on
+// network filesystems / WSL. Depth 2 catches `src/agent.ts`,
+// `apps/api/src/index.ts`. File cap 500 stops huge monorepos from blowing
+// the wizard's budget.
+const WALK_DEPTH_MAX = 2;
+const WALK_FILE_CAP = 500;
+const READ_BYTES = 4096;
+
+const SCAN_EXTS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
+
+// Deliberately omits `index` — too generic to reliably signal "this is the
+// agent." A CLI tool's `cli.js` (matched via package.json `bin`) will lose
+// to a generic `index.js` if `index` is in this set, even though `bin` is
+// what the user actually runs. Names here are strong agent signals on
+// their own; `index` requires a complementary signal (`main`/`bin` match)
+// to be picked up.
+const ENTRY_NAME_PATTERN = /^(agent|bot|app|main|server|worker|handler)\./i;
+const TEST_FILENAME_PATTERN = /\.(test|spec)\./i;
+const TEST_PATH_FRAGMENT = /[\\/](?:test|tests|__tests__|spec|examples|scripts)[\\/]/i;
+
+/**
+ * Locate the user's agent source file under cwd by scanning for AI-SDK
+ * imports. Returns { winner, candidates, scanned, walked, ambiguous }.
+ *
+ * `winner` — absolute path of the highest-scoring file, or null if no file
+ *            in cwd imports any SDK from `NODE_AGENT_DEPS`.
+ * `candidates` — every file that scored > 0, sorted by score descending.
+ *            Each entry: { path, score, syntax, reasons: string[] }.
+ * `scanned` — count of files that imported any SDK (subset of `walked`).
+ * `walked` — total source files inspected (capped at WALK_FILE_CAP).
+ * `ambiguous` — true when winner's lead over runner-up is too narrow to
+ *            silently pick (`winner.score < runner_up.score + 2 &&
+ *            winner.score < runner_up.score * 1.5`). The wizard surfaces
+ *            a chooser only when this is true.
+ *
+ * Why this replaces the package.json-gated detector: production data after
+ * the Phase 11 release showed 5 of 5 fresh real users (JP/US/RU) failing
+ * with `outcome: 'no_entry_detected'` because they ran the wizard from
+ * a server's home dir, with no `package.json` at cwd. Real Node agents
+ * commonly look like a single `agent.js` next to a `node_modules/` —
+ * `package.json` is a project-shape signal, not an agent signal. The
+ * actual ground truth for "this is an agent" is "this file imports an
+ * AI SDK." `package.json` here downgrades to a *ranking hint*, used to
+ * boost candidates whose path matches `bin` or `main`, but never to
+ * gate detection.
+ */
+export function findAgentSourceFile(cwd = process.cwd()) {
+  let walked = 0;
+  const sdkFiles = [];
+
+  // Recursive walker with hard caps. Each recursion increments depth;
+  // depth 0 is cwd itself, depth 1 is direct children, etc.
+  const walk = (dir, depth) => {
+    if (walked >= WALK_FILE_CAP) return;
+    if (depth > WALK_DEPTH_MAX) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // Permission or read error — skip this directory silently.
+      return;
+    }
+    for (const entry of entries) {
+      if (walked >= WALK_FILE_CAP) return;
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+        walk(join(dir, entry.name), depth + 1);
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase();
+        if (!SCAN_EXTS.has(ext)) continue;
+        walked++;
+        const abs = join(dir, entry.name);
+        const head = readHead(abs);
+        if (!head) continue;
+        const sdks = sdksFoundIn(head);
+        if (sdks.size > 0) {
+          sdkFiles.push({ path: abs, head, sdks, depth });
+        }
+      }
+    }
+  };
+
+  walk(cwd, 0);
+
+  // Score each candidate. The scoring system — finalised after a design
+  // review — is:
+  //   +5  imports any NODE_AGENT_DEPS SDK (boolean per file; multiple
+  //       imports from the same file don't pile points, so a wrapper file
+  //       with 6 re-exports doesn't outrank an actual agent file)
+  //   +1  also has a constructor call (`new Anthropic(...)`, etc.)
+  //   +4  filename matches /^(agent|bot|index|app|main|server|worker|handler)\./
+  //   +1  file lives at cwd root (depth 0)
+  //   -3  file is under /test/, /tests/, /__tests__/, /spec/, /examples/, /scripts/
+  //   -3  filename matches *.test.* or *.spec.*
+  //   +5  file matches package.json `bin` (when present — `bin` strictly dominates `main`)
+  //   +3  file matches package.json `main` (when present and ≠ `bin`)
+  const pkg = readPkg(cwd);
+  const binPath = pkg ? resolveBinPath(pkg, cwd) : null;
+  const mainPath = pkg ? resolveMainPath(pkg, cwd) : null;
+
+  const candidates = sdkFiles.map(({ path, head, sdks, depth }) => {
+    const reasons = [];
+    let score = 0;
+
+    score += 5; reasons.push(`+5 imports SDK (${[...sdks].join(',')})`);
+
+    if (hasConstructor(head)) { score += 1; reasons.push('+1 constructor call'); }
+
+    if (ENTRY_NAME_PATTERN.test(basename(path))) { score += 4; reasons.push('+4 entry-name match'); }
+
+    if (depth === 0) { score += 1; reasons.push('+1 cwd root'); }
+
+    if (TEST_PATH_FRAGMENT.test(path)) { score -= 3; reasons.push('-3 test/spec/examples path'); }
+    if (TEST_FILENAME_PATTERN.test(basename(path))) { score -= 3; reasons.push('-3 test/spec filename'); }
+
+    if (binPath && path === binPath) { score += 5; reasons.push('+5 package.json bin'); }
+    else if (mainPath && path === mainPath) { score += 3; reasons.push('+3 package.json main'); }
+
+    return {
+      path,
+      score,
+      syntax: detectImportSyntax(path),
+      reasons,
+    };
+  }).sort((a, b) => b.score - a.score);
+
+  const winner = candidates[0] ?? null;
+  const runnerUp = candidates[1] ?? null;
+
+  // "Clear winner" threshold: lead ≥ 2 absolute OR ≥ 1.5x runner-up.
+  // Either condition means we silently pick `winner`. Both close → ambiguous.
+  let ambiguous = false;
+  if (runnerUp) {
+    const leadOk = winner.score >= runnerUp.score + 2;
+    const ratioOk = winner.score >= runnerUp.score * 1.5;
+    ambiguous = !(leadOk || ratioOk);
+  }
+
+  return {
+    winner: winner?.path ?? null,
+    candidates,
+    scanned: sdkFiles.length,
+    walked,
+    ambiguous,
+  };
+}
+
+/**
+ * Read the head of a file (first READ_BYTES bytes). Imports are always
+ * hoisted to the top of a Node module — TypeScript and ESM both enforce
+ * import hoisting, and CJS users put requires at the top by convention.
+ * Reading more is waste on slow filesystems.
+ */
+function readHead(filePath) {
+  let fd;
+  try {
+    fd = openSync(filePath, 'r');
+    const buf = Buffer.alloc(READ_BYTES);
+    const bytes = readSync(fd, buf, 0, READ_BYTES, 0);
+    return buf.slice(0, bytes).toString('utf-8');
+  } catch {
+    return null;
+  } finally {
+    if (fd != null) { try { closeSync(fd); } catch { /* ignore */ } }
+  }
+}
+
+/**
+ * Return the set of SDK package names found in `text`. Boolean per SDK —
+ * multiple `require('@anthropic-ai/sdk')` lines in the same file count
+ * once. Both CJS (`require('foo')`) and ESM (`from 'foo'`) shapes are
+ * checked; we don't care about quote style.
+ */
+function sdksFoundIn(text) {
+  const found = new Set();
+  for (const sdk of NODE_AGENT_DEPS) {
+    const escaped = sdk.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const requireRe = new RegExp(`require\\(\\s*['"]${escaped}['"]\\s*\\)`);
+    const importRe = new RegExp(`from\\s+['"]${escaped}['"]`);
+    if (requireRe.test(text) || importRe.test(text)) found.add(sdk);
+  }
+  return found;
+}
+
+function hasConstructor(text) {
+  // Cheap regex; over-matches `if (new Anthropic())` etc. — that's fine,
+  // they still count as evidence that this file talks to a model.
+  return /new\s+(Anthropic|OpenAI|GoogleGenerativeAI)\s*\(/.test(text);
+}
+
+function readPkg(cwd) {
+  const p = join(cwd, 'package.json');
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return null; }
+}
+
+function resolveBinPath(pkg, cwd) {
+  let raw = null;
+  if (typeof pkg.bin === 'string') raw = pkg.bin;
+  else if (pkg.bin && typeof pkg.bin === 'object') {
+    const vals = Object.values(pkg.bin).filter((v) => typeof v === 'string');
+    if (vals.length === 1) raw = vals[0];
+  }
+  if (!raw) return null;
+  const abs = join(cwd, raw.replace(/^\.\//, ''));
+  return existsSync(abs) ? abs : null;
+}
+
+function resolveMainPath(pkg, cwd) {
+  if (typeof pkg.main !== 'string') return null;
+  const abs = join(cwd, pkg.main.replace(/^\.\//, ''));
+  return existsSync(abs) ? abs : null;
+}
+
+/**
+ * Returns true if the given source file already contains our marker.
+ * Used to skip-if-already-installed and to gate uninstall.
+ */
+export function hasSourceMarker(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8').includes(MARK_BEGIN);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Idempotently inject the auto-attach marker block at the top of the file
+ * (after shebang, if present). Writes a one-time backup at `${filePath}.rr-backup`.
+ *
+ * Returns { ok, alreadyInstalled, path, syntax, backupPath, error }.
+ */
+export function writeSourceMarker(filePath, opts = {}) {
+  const syntax = opts.syntax ?? detectImportSyntax(filePath);
+
+  let original;
+  try { original = readFileSync(filePath, 'utf-8'); }
+  catch (err) {
+    return { ok: false, alreadyInstalled: false, path: filePath, syntax, error: `read_failed: ${err.message}` };
+  }
+
+  if (original.includes(MARK_BEGIN)) {
+    return { ok: true, alreadyInstalled: true, path: filePath, syntax, backupPath: backupPathFor(filePath) };
+  }
+
+  // Backup once. Never overwrite — preserves the user's pristine original
+  // even if they manually edit before our second pass.
+  const backupPath = backupPathFor(filePath);
+  let backupWritten = false;
+  if (!existsSync(backupPath)) {
+    try {
+      writeFileSync(backupPath, original, { mode: getMode(filePath) });
+      backupWritten = true;
+    } catch (err) {
+      return { ok: false, alreadyInstalled: false, path: filePath, syntax, error: `backup_failed: ${err.message}` };
+    }
+  }
+
+  // Insert position: after shebang line if present, otherwise at top.
+  // We do NOT try to skip past `"use strict";` — modern Node treats it as
+  // a normal directive; placing our require/import before it is harmless.
+  const line = syntax === 'esm' ? IMPORT_LINE : REQUIRE_LINE;
+  const block = `${MARK_BEGIN}\n${line}\n${MARK_END}\n`;
+
+  let next;
+  if (original.startsWith('#!')) {
+    const nl = original.indexOf('\n');
+    if (nl === -1) {
+      // single-line file, only a shebang — append our block on a new line
+      next = original + '\n' + block;
+    } else {
+      next = original.slice(0, nl + 1) + block + original.slice(nl + 1);
+    }
+  } else {
+    next = block + original;
+  }
+
+  try {
+    writeFileSync(filePath, next, { mode: getMode(filePath) });
+  } catch (err) {
+    return { ok: false, alreadyInstalled: false, path: filePath, syntax, error: `write_failed: ${err.message}`, backupPath, backupWritten };
+  }
+
+  return { ok: true, alreadyInstalled: false, path: filePath, syntax, backupPath, backupWritten };
+}
+
+/**
+ * Idempotently remove the marker block from the source file. Mirror of
+ * writeSourceMarker. Returns { ok, removed, restored, path, error }.
+ *
+ * If `restoreFromBackup` is true and a `.rr-backup` exists, restores from
+ * the backup instead of splicing. Used for `--purge`. The backup is
+ * deleted after a successful restore.
+ */
+export function removeSourceMarker(filePath, { restoreFromBackup = false } = {}) {
+  let original;
+  try { original = readFileSync(filePath, 'utf-8'); }
+  catch (err) {
+    return { ok: false, removed: false, restored: false, path: filePath, error: `read_failed: ${err.message}` };
+  }
+
+  if (restoreFromBackup) {
+    const backupPath = backupPathFor(filePath);
+    if (existsSync(backupPath)) {
+      try {
+        const pristine = readFileSync(backupPath, 'utf-8');
+        writeFileSync(filePath, pristine, { mode: getMode(filePath) });
+        unlinkSync(backupPath);
+        return { ok: true, removed: true, restored: true, path: filePath };
+      } catch (err) {
+        return { ok: false, removed: false, restored: false, path: filePath, error: `restore_failed: ${err.message}` };
+      }
+    }
+    // No backup → fall through to marker splice.
+  }
+
+  const startIdx = original.indexOf(MARK_BEGIN);
+  if (startIdx === -1) {
+    return { ok: true, removed: false, restored: false, path: filePath };
+  }
+  const endIdx = original.indexOf(MARK_END, startIdx);
+  if (endIdx === -1) {
+    return { ok: false, removed: false, restored: false, path: filePath, error: 'marker_end_missing' };
+  }
+
+  // Splice from MARK_BEGIN through end of MARK_END line + the trailing
+  // newline our writer added. Walk backward over leading newlines so
+  // repeated install/uninstall cycles don't accumulate blanks.
+  const afterEnd = original.indexOf('\n', endIdx);
+  const sliceEnd = afterEnd === -1 ? original.length : afterEnd + 1;
+
+  let sliceStart = startIdx;
+  while (sliceStart > 0 && original[sliceStart - 1] === '\n') sliceStart--;
+
+  const next = original.slice(0, sliceStart) +
+    (sliceStart > 0 ? '\n' : '') +
+    original.slice(sliceEnd);
+
+  try {
+    writeFileSync(filePath, next, { mode: getMode(filePath) });
+  } catch (err) {
+    return { ok: false, removed: false, restored: false, path: filePath, error: `write_failed: ${err.message}` };
+  }
+
+  return { ok: true, removed: true, restored: false, path: filePath };
+}
+
+/**
+ * Build the proposed diff a wizard can show before asking Y/N. Returns a
+ * UI-friendly string with the marker block + a few lines of context.
+ */
+export function previewInjection(filePath, opts = {}) {
+  const syntax = opts.syntax ?? detectImportSyntax(filePath);
+  const line = syntax === 'esm' ? IMPORT_LINE : REQUIRE_LINE;
+  let original = '';
+  try { original = readFileSync(filePath, 'utf-8'); } catch { /* ignore */ }
+  const firstLines = original.split('\n').slice(0, 3).join('\n');
+  return [
+    `+ ${MARK_BEGIN}`,
+    `+ ${line}`,
+    `+ ${MARK_END}`,
+    firstLines.split('\n').map((l) => `  ${l}`).join('\n'),
+  ].join('\n');
+}
+
+function backupPathFor(filePath) {
+  return `${filePath}.rr-backup`;
+}
+
+function getMode(filePath) {
+  try { return statSync(filePath).mode & 0o777; } catch { return 0o644; }
+}
+
+/**
+ * Best-effort cwd-relative path for telemetry, falling back to basename
+ * if the file is outside cwd. Used to avoid leaking absolute paths (which
+ * can contain usernames) into Supabase.
+ */
+export function pathForTelemetry(filePath, cwd = process.cwd()) {
+  const rel = relative(cwd, filePath);
+  if (rel.startsWith('..') || rel.includes(sep + '..' + sep)) {
+    // Outside cwd — basename only.
+    return filePath.split(sep).pop();
+  }
+  return rel;
+}

package/lib/uninstall.js

@@ -6,6 +6,7 @@ import { removeShellLine } from './shell-config.js';
 import { detectVenv } from './venv-detect.js';
 import { spawnSync } from 'node:child_process';
 import { removePersistedNodeOptions } from './windows-env.js';
+import { detectEntryFile, hasSourceMarker, removeSourceMarker } from './source-edit-attach.js';
 
 /**
  * Single source of truth for `npx robot-resources --uninstall`.
@@ -115,6 +116,36 @@ export function runUninstall({ purge = false } = {}) {
     }
   }
 
+  // 3a. Phase 11 — source-edit auto-attach line. If the wizard injected
+  //     `require('@robot-resources/router/auto')` at the top of the user's
+  //     entry file, peel the marker block out (or restore from .rr-backup
+  //     when --purge). Idempotent: no-op when no entry detected or marker
+  //     not present. Runs against cwd, so users who --uninstall from a
+  //     different repo won't accidentally wipe the wrong file.
+  try {
+    const detection = detectEntryFile();
+    if (detection.path && hasSourceMarker(detection.path)) {
+      const r = removeSourceMarker(detection.path, { restoreFromBackup: !!purge });
+      if (r.ok && (r.removed || r.restored)) {
+        components_removed.push(r.restored ? 'node_entry_restored_from_backup' : 'node_entry_marker_removed');
+      } else if (!r.ok) {
+        errors.push({ component: 'node_entry_source_edit', message: r.error || 'unknown' });
+      }
+    }
+    // --purge also wipes any leftover .rr-backup (covers the case where the
+    // user manually deleted the marker but kept the backup file around).
+    if (purge && detection.path && existsSync(`${detection.path}.rr-backup`)) {
+      try {
+        rmSync(`${detection.path}.rr-backup`, { force: true });
+        components_removed.push('node_entry_backup_purged');
+      } catch (err) {
+        errors.push({ component: 'node_entry_backup_purged', message: err.message });
+      }
+    }
+  } catch (err) {
+    errors.push({ component: 'node_entry_source_edit', message: err.message });
+  }
+
   // 3b. Copied router dir at ~/.robot-resources/router/ (Phase 8). The shell
   //     line points at this absolute path — once the line is gone, the
   //     copied files are dead weight. Remove them.

package/lib/wizard.js

@@ -26,6 +26,43 @@ const CLI_VERSION = (() => {
   }
 })();
 
+/**
+ * Fire `install_complete` once after the wizard finishes — for BOTH OC
+ * and non-OC paths. Phase 11 fix: previously this only fired on the OC
+ * path because the non-OC branch returned early. The 7-day funnel showed
+ * 0/58 non-OC users hitting this event for a week. Now both paths fire
+ * with a `path: 'oc' | 'non-oc'` discriminator so funnel queries can
+ * segment without a second event type.
+ *
+ * Best-effort with one retry. Total budget: ~20s. Telemetry never blocks
+ * the wizard exit beyond that.
+ */
+async function emitInstallComplete({ apiKey, payload }) {
+  if (!apiKey) return;
+  const platformUrl = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+  const body = JSON.stringify({
+    product: 'cli',
+    event_type: 'install_complete',
+    payload,
+  });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await fetch(`${platformUrl}/v1/telemetry`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body,
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (res.ok) break;
+    } catch {
+      // Try again on next iteration.
+    }
+  }
+}
+
 /**
  * Main setup wizard. In Option 4 (post-PR-2.5) the wizard does NOT install
  * a Python daemon, register a system service, or run a localhost health
@@ -43,7 +80,7 @@ const CLI_VERSION = (() => {
  *
  * No Python, no venv, no systemd, no port probe.
  */
-export async function runWizard({ nonInteractive = false, target = null, scope = 'full' } = {}) {
+export async function runWizard({ nonInteractive = false, target = null, scope = 'full', autoAttachSource = false } = {}) {
   header();
 
   // Detect OC once up front. Used both to branch into the non-OC wizard and
@@ -165,7 +202,31 @@ export async function runWizard({ nonInteractive = false, target = null, scope =
   // MCP config / docs / install-OC). The non-OC wizard's wizard_path_chosen
   // telemetry now fires too, since Step 0 above provisioned an api_key.
   if (!openclawDetected) {
-    await runNonOcWizard({ nonInteractive, target });
+    await runNonOcWizard({ nonInteractive, target, autoAttachSource });
+
+    // Phase 11: install_complete now fires for non-OC too. Closes the
+    // funnel signal that was 0/58 for a week.
+    if (results.auth) {
+      try {
+        const config = readConfig();
+        await emitInstallComplete({
+          apiKey: config.api_key,
+          payload: {
+            source: 'wizard',
+            path: 'non-oc',
+            cli_version: CLI_VERSION,
+            target: target ?? null,
+            scope,
+            auto_attach_source: !!autoAttachSource,
+            platform: process.platform,
+            os_release: osRelease(),
+            node_version: process.version,
+            install_duration_ms: Date.now() - wizardStartMs,
+            non_interactive: nonInteractive,
+          },
+        });
+      } catch { /* non-fatal */ }
+    }
     return;
   }
 
@@ -250,54 +311,32 @@ export async function runWizard({ nonInteractive = false, target = null, scope =
 
   // ── Install Complete Telemetry ───────────────────────────────────────────
   //
-  // Fire once after install, using the API key directly (not from config read-back).
-  // This immediately populates last_used_at and proves the key works end-to-end.
-  //
-  // Retry once with longer timeout — Cloudflare analytics showed client-side
-  // aborts on the original 5s single-attempt, leaving stranded signups with
-  // no telemetry. Two 10s attempts catch the long tail. Still fire-and-forget.
+  // Fire once after the OC install path completes. Non-OC fires its own
+  // install_complete higher up (right after runNonOcWizard returns), so
+  // both paths now produce this funnel signal — see emitInstallComplete().
 
   if (results.auth) {
     try {
       const config = readConfig();
-      const platformUrl = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
-      const installPayload = {
-        source: 'wizard',
-        cli_version: CLI_VERSION,
-        plugin_installed: results.pluginInstalled,
-        scraper: results.scraper || false,
-        platform: process.platform,
-        os_release: osRelease(),
-        node_version: process.version,
-        install_duration_ms: Date.now() - wizardStartMs,
-        openclaw_detected: results.openclawDetected,
-        openclaw_config_patched: results.openclawConfigPatched,
-        scraper_mcp_registered: results.scraperMcpRegistered,
-      };
-      const body = JSON.stringify({
-        product: 'cli',
-        event_type: 'install_complete',
-        payload: installPayload,
+      await emitInstallComplete({
+        apiKey: config.api_key,
+        payload: {
+          source: 'wizard',
+          path: 'oc',
+          cli_version: CLI_VERSION,
+          plugin_installed: results.pluginInstalled,
+          scraper: results.scraper || false,
+          platform: process.platform,
+          os_release: osRelease(),
+          node_version: process.version,
+          install_duration_ms: Date.now() - wizardStartMs,
+          openclaw_detected: results.openclawDetected,
+          openclaw_config_patched: results.openclawConfigPatched,
+          scraper_mcp_registered: results.scraperMcpRegistered,
+        },
       });
-
-      for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-          const res = await fetch(`${platformUrl}/v1/telemetry`, {
-            method: 'POST',
-            headers: {
-              'Authorization': `Bearer ${config.api_key}`,
-              'Content-Type': 'application/json',
-            },
-            body,
-            signal: AbortSignal.timeout(10_000),
-          });
-          if (res.ok) break;
-        } catch {
-          // Try again on next iteration; outer catch handles total failure
-        }
-      }
     } catch {
-      // Non-fatal — install_complete is best-effort
+      // Non-fatal — install_complete is best-effort.
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robot-resources",
-  "version": "1.14.2",
+  "version": "1.15.1",
   "description": "Robot Resources — AI agent tools. One command to install everything.",
   "type": "module",
   "bin": {