create-byan-agent 2.29.1 → 2.29.2

package/CHANGELOG.md

@@ -9,6 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.29.2] - 2026-06-23
+
+### Fixed - RTK optional install: fail-proof, off-PATH, shell-aware
+
+The 2.29.x RTK installer could hang silently and mis-report a successful build.
+
+- **Bounded + visible.** The delegated install now runs with a per-strategy
+  timeout (brew/script 5min, cargo 20min; override via `BYAN_RTK_TIMEOUT_MS`,
+  positive integers only) and inherited stdio, so progress streams live instead
+  of a frozen line. Inherited stdio also sidesteps execSync's 1MB maxBuffer cap a
+  verbose build would blow.
+- **Off-PATH resolution.** `cargo install` drops the binary in `~/.cargo/bin`,
+  which a Debian non-login PATH does not include — the install succeeded but
+  `rtk --version` reported "unverified". The installer now resolves rtk across
+  known dirs (PATH, `~/.cargo/bin`, `~/.local/bin`, `/usr/local/bin`, brew prefix,
+  `CARGO_HOME`), verifies + wires the hook by the resolved path, and prints a
+  shell-correct PATH hint (`fish_add_path` on fish, `export` on bash/zsh,
+  `$env:PATH` on Windows).
+- **Prebuilt preferred.** Strategy order is now brew > script > cargo: the
+  prebuilt-binary script (pinned to the immutable tag ref, which SHA-256-verifies
+  the binary per refs/tags/v0.42.4/install.sh) is fast and PATH-stable; cargo
+  (from-source, off-PATH, slow) becomes the last-resort fallback.
+- **Stays graceful.** Hardened the no-throw contract: a HOME-less environment
+  (`os.homedir()` throwing) no longer propagates out of `setup-rtk.js`.
+
+Reviewed by an adversarial workflow (correctness + supply-chain + mantras) plus a
+compliance pass; 2375/2375 tests green (49 dedicated to RTK).
+
 ## [2.29.1] - 2026-06-23
 
 ### Fixed - Republish (the 2.29.0 npm tarball was missing)

package/install/bin/create-byan-agent-v2.js

@@ -1383,11 +1383,14 @@ async function install(options = {}) {
         },
       ]);
       if (proceed) {
+        console.log(chalk.gray('  Installing... progress streams below. The cargo fallback compiles from source (can take minutes); Ctrl+C is safe — BYAN is already installed.'));
         const r = setupRtkIntegration({ log: (m) => console.log(chalk.gray('  ' + m)) });
         if (r.synced) {
           console.log(chalk.green(`  ✓ rtk ready (${r.installedVia}, v${r.version || '?'}) — restart Claude Code to activate`));
+          if (r.pathHint) console.log(chalk.yellow(`  ⚠ rtk is not on your PATH — add it: ${r.pathHint}`));
         } else {
-          console.log(chalk.yellow(`  ⚠ rtk not wired (${r.reason}) — BYAN unaffected`));
+          console.log(chalk.yellow(`  ⚠ rtk not wired (${r.reason}) — BYAN unaffected; re-run \`npm run setup-rtk\` anytime`));
+          if (r.pathHint) console.log(chalk.yellow(`  ⚠ rtk found off-PATH — add it then re-run: ${r.pathHint}`));
         }
       } else {
         console.log(chalk.gray('  rtk skipped — run `npm run setup-rtk` anytime to enable.'));

package/install/lib/native-helper.js

@@ -11,6 +11,9 @@
  */
 
 const { execSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 
 /**
  * commandExists(cmd) -> boolean. Is an executable resolvable on PATH?
@@ -26,6 +29,70 @@ function commandExists(cmd, { run = execSync, platform = process.platform } = {}
   }
 }
 
+/**
+ * safeHomedir() -> the home directory, or '' if it cannot be determined. WHY:
+ * os.homedir() THROWS on an env with no $HOME/$USERPROFILE AND no passwd entry
+ * for the effective uid (distroless / random-uid containers). An optional install
+ * helper must never throw on that — it degrades to "no home dir to scan".
+ */
+function safeHomedir() {
+  try {
+    return os.homedir();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * knownBinDirs() -> ordered list of directories where installers commonly drop a
+ * binary that is NOT on a non-login shell's PATH. The canonical case: `cargo
+ * install` lands in ~/.cargo/bin, which Debian's apt-packaged cargo does NOT add
+ * to PATH — so a freshly built binary is present yet invisible to a bare probe.
+ * fs/env/home are injectable for tests. `home` defaults via safeHomedir so a
+ * HOME-less environment yields a shorter scan instead of a throw.
+ */
+function knownBinDirs({ env = process.env, home = safeHomedir(), platform = process.platform } = {}) {
+  const dirs = [];
+  if (env && env.CARGO_HOME) dirs.push(path.join(env.CARGO_HOME, 'bin'));
+  dirs.push(path.join(home, '.cargo', 'bin')); // cargo install
+  dirs.push(path.join(home, '.local', 'bin')); // pip/pipx + many curl scripts
+  if (platform === 'win32') {
+    if (env && env.LOCALAPPDATA) dirs.push(path.join(env.LOCALAPPDATA, 'Programs'));
+  } else {
+    dirs.push('/usr/local/bin'); // common script target + brew (intel mac)
+    dirs.push('/opt/homebrew/bin'); // brew (apple silicon)
+    dirs.push('/usr/bin');
+  }
+  return dirs;
+}
+
+/**
+ * resolveBinary(name) -> the command to invoke the executable, or null if it
+ * cannot be located. Returns the BARE name when it is on PATH (let the shell
+ * resolve it), else an ABSOLUTE path found in a knownBinDir. WHY: an optional
+ * native install can succeed yet leave the binary off PATH; callers must verify
+ * and wire it by its real location, not declare failure. All I/O is injectable.
+ */
+function resolveBinary(name, {
+  has = commandExists,
+  existsSync = fs.existsSync,
+  env = process.env,
+  home = safeHomedir(),
+  platform = process.platform,
+} = {}) {
+  if (has(name)) return name;
+  const exe = platform === 'win32' ? `${name}.exe` : name;
+  for (const dir of knownBinDirs({ env, home, platform })) {
+    const full = path.join(dir, exe);
+    try {
+      if (existsSync(full)) return full;
+    } catch {
+      // a stat error on one candidate must not abort the scan
+    }
+  }
+  return null;
+}
+
 /**
  * detectPlatform() -> 'mac' | 'windows' | 'linux'. Coarse bucket for choosing an
  * install strategy. Keeps the platform string in ONE place.
@@ -47,4 +114,4 @@ function firstAvailable(candidates, { has = commandExists } = {}) {
   return candidates.find((c) => c && c.tool && has(c.tool)) || null;
 }
 
-module.exports = { commandExists, detectPlatform, firstAvailable };
+module.exports = { commandExists, detectPlatform, firstAvailable, knownBinDirs, resolveBinary, safeHomedir };

package/install/lib/rtk-integration.js

@@ -9,18 +9,32 @@
  *
  * MAINTAINABILITY by design (the whole point of choosing this shape):
  *  - We do NOT reimplement per-OS download / checksum / version pinning. We
- *    DELEGATE the install to rtk's own canonical installer (brew / cargo / the
- *    official install.sh), and DELEGATE the Claude Code hook wiring to rtk's own
- *    `rtk init -g`. BYAN maintains only "pick the available installer, run it,
- *    verify, ask rtk to wire its hook" — a tiny surface, bumped via one constant.
+ *    DELEGATE the install to rtk's own canonical installer (brew / the official
+ *    install.sh / cargo), and DELEGATE the Claude Code hook wiring to rtk's own
+ *    `rtk init -g`. BYAN maintains only "pick the available installer, run it
+ *    bounded + visible, locate the binary, ask rtk to wire its hook" — a tiny
+ *    surface, bumped via one constant.
  *  - SUPPLY-CHAIN: we pin to a TAG, never a moving branch. cargo builds the
- *    tagged source (`--tag`), and install.sh is fetched from the IMMUTABLE tag ref
- *    (and that script itself checksum-verifies the binary it downloads). So the
- *    fetched artifacts are reproducible, not "whatever master is today".
- *  - Everything is graceful: a missing installer or a failed step is a no-op that
- *    NEVER breaks the BYAN install (returns { ok:true, synced:false, reason }).
- *  - The command runner + the PATH probe are injectable, so the whole flow is
- *    unit-tested without shelling out (see install/__tests__/rtk-integration.test.js).
+ *    tagged source (`--tag`), and install.sh is fetched from the IMMUTABLE tag ref.
+ *    That script verifies a SHA-256 of the downloaded binary against a published
+ *    checksums.txt and aborts on mismatch (source: refs/tags/v0.42.4/install.sh,
+ *    fetched + verified 2026-06-23). So the fetched artifacts are reproducible and
+ *    integrity-checked, not "whatever master is today".
+ *  - FAIL-PROOF: the delegated install runs with a per-strategy TIMEOUT (a hung
+ *    network/build is bounded, not infinite) and with INHERITED stdio (the user
+ *    SEES the installer's progress instead of staring at a frozen line; this also
+ *    sidesteps execSync's 1MB maxBuffer cap that a verbose build would blow). Any
+ *    missing installer / failed / timed-out step is a logged no-op that NEVER
+ *    breaks the BYAN install (returns { ok:true, synced:false, reason }).
+ *  - OFF-PATH SAFE: a successful install can leave the binary off PATH (the
+ *    classic: cargo drops it in ~/.cargo/bin, which Debian's apt-cargo does not
+ *    add to PATH). We RESOLVE the binary across known install dirs before
+ *    declaring "unverified", verify + wire it by its real path, and hand the user
+ *    a one-line PATH hint. The user's own report (rtk installed at ~/.cargo/bin,
+ *    invisible to a bare probe) is exactly this case.
+ *  - The command runner + the PATH probe + the resolver are injectable, so the
+ *    whole flow is unit-tested without shelling out (see
+ *    install/__tests__/rtk-integration.test.js).
  *
  * Mirrors the ENTRY-POINT shape of byan-web-integration.js / byan-leantime-
  * integration.js (one `setup*Integration`); the return contract is { ok, synced,
@@ -29,7 +43,8 @@
  */
 
 const { execSync } = require('child_process');
-const { commandExists, firstAvailable } = require('./native-helper');
+const path = require('path');
+const { commandExists, resolveBinary, firstAvailable } = require('./native-helper');
 
 // Pinned install target. Bumping rtk = change these two constants only. We pin a
 // TAG so the install is reproducible and supply-chain-bounded (see header).
@@ -38,20 +53,37 @@ const RTK_TAG = `v${RTK_VERSION}`;
 const RTK_REPO = 'https://github.com/rtk-ai/rtk';
 const RTK_INSTALL_SH = `https://raw.githubusercontent.com/rtk-ai/rtk/refs/tags/${RTK_TAG}/install.sh`;
 
+// Per-strategy timeout (ms). A prebuilt-binary path (brew / script) should be
+// quick; cargo COMPILES from source and is legitimately slow, so it gets a wide
+// budget. The bound exists to cap a genuine HANG, not to race a normal build.
+const MIN = 60 * 1000;
+const RTK_TIMEOUT_MS = { brew: 5 * MIN, script: 5 * MIN, cargo: 20 * MIN };
+const RTK_DEFAULT_TIMEOUT_MS = 10 * MIN;
+
 /**
  * Ordered install strategies — each DELEGATES to rtk's own canonical installer,
- * pinned to RTK_TAG where the mechanism allows. Preference: brew (cleanest
- * upgrades, vetted formula) > cargo (any Rust dev, pinned --tag) > the official
- * install.sh at the immutable tag ref (universal fallback, self-checksumming).
+ * pinned to RTK_TAG where the mechanism allows.
+ *
+ * Order = brew > script > cargo. WHY this order (not brew > cargo > script):
+ *  - brew first: vetted formula, cleanest upgrades, prebuilt.
+ *  - script second: the official install.sh downloads a PREBUILT binary to a
+ *    PATH-stable location in seconds. It is pinned to the immutable tag ref and
+ *    verifies the binary's SHA-256 before installing (see the cited check above)
+ *    — a bounded supply-chain surface.
+ *  - cargo LAST: it COMPILES from source (minutes) AND drops the binary in
+ *    ~/.cargo/bin, frequently off a non-login PATH. It stays as a build-from-
+ *    source fallback for machines without brew/curl, not the default path.
  */
 function installStrategies() {
   return [
-    { id: 'brew', tool: 'brew', cmd: 'brew install rtk' },
-    { id: 'cargo', tool: 'cargo', cmd: `cargo install --git ${RTK_REPO} --tag ${RTK_TAG}` },
+    { id: 'brew', tool: 'brew', cmd: 'brew install rtk', timeoutMs: RTK_TIMEOUT_MS.brew },
     // Pass RTK_VERSION into the script so it pins the BINARY too (the script
     // builds releases/download/${VERSION}/...; without it, it resolves
     // releases/latest). Pinning the URL alone is not enough — this pins both.
-    { id: 'script', tool: 'curl', cmd: `curl -fsSL ${RTK_INSTALL_SH} | RTK_VERSION=${RTK_TAG} sh` },
+    // The script verifies a SHA-256 of the binary (vs checksums.txt) before
+    // installing — verified at refs/tags/v0.42.4/install.sh, 2026-06-23.
+    { id: 'script', tool: 'curl', cmd: `curl -fsSL ${RTK_INSTALL_SH} | RTK_VERSION=${RTK_TAG} sh`, timeoutMs: RTK_TIMEOUT_MS.script },
+    { id: 'cargo', tool: 'cargo', cmd: `cargo install --git ${RTK_REPO} --tag ${RTK_TAG}`, timeoutMs: RTK_TIMEOUT_MS.cargo },
   ];
 }
 
@@ -59,19 +91,78 @@ function oneLine(err) {
   return String((err && err.message) || err).split('\n')[0];
 }
 
+// A bounded, env-overridable timeout for a strategy. BYAN_RTK_TIMEOUT_MS (ms)
+// lets a user widen the bound (e.g. a slow machine compiling via cargo). Only a
+// POSITIVE integer is honored: Node treats timeout:0 as "no timeout", so a 0
+// override would silently re-introduce the unbounded hang the bound exists to
+// prevent — it falls back to the strategy budget instead.
+function timeoutFor(strat, { env = process.env } = {}) {
+  const raw = env && env.BYAN_RTK_TIMEOUT_MS;
+  if (raw != null && /^[0-9]+$/.test(String(raw))) {
+    const n = Number(raw);
+    if (n > 0) return n;
+  }
+  return (strat && strat.timeoutMs) || RTK_DEFAULT_TIMEOUT_MS;
+}
+
+// Did execSync throw because WE killed it on timeout (vs the command failing on
+// its own)? Node sets `killed=true` and code 'ETIMEDOUT' when it kills the child
+// on timeout; a build error sets a non-zero exit status with killed=false. We do
+// NOT match a bare 'SIGTERM' signal: a sub-process self-terminating with SIGTERM
+// for an unrelated reason would otherwise be mislabelled a timeout.
+function isTimeout(err) {
+  return Boolean(err && (err.killed === true || err.code === 'ETIMEDOUT'));
+}
+
+// A shell/platform-correct "add this dir to PATH" hint. The resolved binary can
+// live off PATH (cargo -> ~/.cargo/bin); the user needs the line that actually
+// works in THEIR shell — fish rejects POSIX `export`, Windows rejects both.
+function pathHintFor(bin, { env = process.env, platform = process.platform } = {}) {
+  // Parse the dir with the TARGET platform's rules, not the host's — so a win32
+  // path yields the right dir even when this code runs on a POSIX CI host.
+  const dir = (platform === 'win32' ? path.win32 : path.posix).dirname(bin);
+  if (platform === 'win32') return `$env:PATH = "${dir};$env:PATH"`;
+  const shell = String((env && env.SHELL) || '');
+  if (/(^|\/)fish$/.test(shell)) return `fish_add_path ${dir}`;
+  return `export PATH="${dir}:$PATH"`;
+}
+
 /**
- * rtkStatus() -> { installed, version }. Never throws. Parses `rtk --version`
- * ("rtk 0.42.4"). An installed-but-unparseable build yields { installed:true,
- * version:null } (a real runtime possibility, handled downstream).
+ * rtkStatus() -> { installed, version, bin }. Never throws. Probes `<bin>
+ * --version` ("rtk 0.42.4"), default bin "rtk" (on PATH). An installed-but-
+ * unparseable build yields { installed:true, version:null }.
  */
-function rtkStatus({ run = execSync } = {}) {
+function rtkStatus({ run = execSync, bin = 'rtk' } = {}) {
   try {
-    const out = String(run('rtk --version', { stdio: 'pipe' }) || '');
+    const out = String(run(`${bin} --version`, { stdio: 'pipe' }) || '');
     const m = out.match(/rtk\s+v?([0-9]+\.[0-9]+\.[0-9]+)/i);
-    return { installed: true, version: m ? m[1] : null };
+    return { installed: true, version: m ? m[1] : null, bin };
   } catch {
-    return { installed: false, version: null };
+    return { installed: false, version: null, bin: null };
+  }
+}
+
+/**
+ * locateRtk() -> a verified { installed, version, bin } by trying the bare name
+ * first (on PATH), then resolving across known install dirs (off-PATH). Returns
+ * the off-PATH absolute path in `bin` when that is where it was found.
+ */
+function locateRtk({ run = execSync, has = commandExists, resolve = resolveBinary, env = process.env } = {}) {
+  const onPath = rtkStatus({ run, bin: 'rtk' });
+  if (onPath.installed) return onPath;
+  // The resolver must never break the never-throws contract; degrade to not-found
+  // if it (or a misbehaving injected resolver) throws.
+  let resolved = null;
+  try {
+    resolved = resolve('rtk', { has, env });
+  } catch {
+    resolved = null;
+  }
+  if (resolved && resolved !== 'rtk') {
+    const s = rtkStatus({ run, bin: resolved });
+    if (s.installed) return s;
   }
+  return { installed: false, version: null, bin: null };
 }
 
 /**
@@ -82,16 +173,18 @@ function pickStrategy({ has = commandExists } = {}) {
 }
 
 /**
- * doctor() -> a status report for diagnostics / a `byan` doctor surface. `pinned`
- * is the version BYAN installs/targets — NOT an enforced floor on a pre-existing
- * rtk (we do not break a user's own older rtk).
+ * doctor() -> a status report for diagnostics / a `byan` doctor surface. Resolves
+ * the binary across known dirs so an off-PATH install is reported as installed
+ * (with its real path), not as missing. `pinned` is the version BYAN targets —
+ * NOT an enforced floor on a pre-existing rtk.
  */
-function doctor({ run = execSync } = {}) {
-  const s = rtkStatus({ run });
+function doctor({ run = execSync, has = commandExists, resolve = resolveBinary, env = process.env } = {}) {
+  const s = locateRtk({ run, has, resolve, env });
   return {
     component: 'rtk',
     installed: s.installed,
     version: s.version,
+    bin: s.bin,
     pinned: RTK_VERSION,
     repo: RTK_REPO,
     hookCommand: 'rtk init -g',
@@ -99,61 +192,88 @@ function doctor({ run = execSync } = {}) {
 }
 
 // Delegate the Claude Code hook wiring to rtk's OWN command (idempotent). This is
-// the maintainability win: no manual settings.json merge to keep in sync.
-function wireHook({ run, log, installedVia, version }) {
+// the maintainability win: no manual settings.json merge to keep in sync. Wires
+// via the resolved `bin` so an off-PATH install still gets its hook.
+function wireHook({ run, log, installedVia, version, bin = 'rtk', env = process.env, platform = process.platform }) {
+  const offPath = bin !== 'rtk';
   try {
-    run('rtk init -g', { stdio: 'pipe' });
-    log(`rtk: ready (${installedVia}, v${version || '?'}) — hook wired via 'rtk init -g'. Restart Claude Code to activate.`);
-    return { ok: true, synced: true, reason: 'wired', installed: true, installedVia, version, hook: true };
+    run(`${bin} init -g`, { stdio: 'pipe' });
+    log(`rtk: ready (${installedVia}, v${version || '?'}) — hook wired via '${bin} init -g'. Restart Claude Code to activate.`);
+    const r = { ok: true, synced: true, reason: 'wired', installed: true, installedVia, version, hook: true, bin };
+    if (offPath) {
+      r.pathHint = pathHintFor(bin, { env, platform });
+      log(`rtk: note — installed at ${bin}, not on your PATH. Add it: ${r.pathHint}`);
+    }
+    return r;
   } catch (err) {
-    log(`rtk: installed (${installedVia}) but 'rtk init -g' failed (${oneLine(err)}) — run it manually, BYAN unaffected.`);
-    return { ok: true, synced: false, reason: 'hook-failed', installed: true, installedVia, version, hook: false };
+    log(`rtk: installed (${installedVia}) but '${bin} init -g' failed (${oneLine(err)}) — run it manually, BYAN unaffected.`);
+    const r = { ok: true, synced: false, reason: 'hook-failed', installed: true, installedVia, version, hook: false, bin };
+    if (offPath) r.pathHint = pathHintFor(bin, { env, platform });
+    return r;
   }
 }
 
 /**
  * setupRtkIntegration(options) -> { ok, synced, reason, ... }. The single entry.
  *
- * Flow: if rtk is already present, just (re)wire the hook (idempotent). Otherwise
- * pick an available installer, delegate the install to rtk, verify, then wire the
- * hook. Any missing tool / failed step degrades to a logged no-op — it NEVER
- * throws and NEVER fails the surrounding BYAN install. `ok` is therefore always
- * true; `synced` says whether rtk ended up wired.
+ * Flow: if rtk is already present (on PATH or off-PATH in a known dir), just
+ * (re)wire the hook (idempotent). Otherwise pick an available installer, delegate
+ * the install (BOUNDED by a timeout + VISIBLE via inherited stdio), LOCATE the
+ * binary, verify, then wire the hook. Any missing tool / failed / timed-out step
+ * degrades to a logged no-op — it NEVER throws and NEVER fails the surrounding
+ * BYAN install. `ok` is therefore always true; `synced` says whether rtk ended
+ * up wired. An off-PATH install carries a `pathHint`.
  *
  * @param {object} [o]
- * @param {Function} [o.run]  command runner (default execSync) — injected in tests
- * @param {Function} [o.has]  PATH probe (default commandExists) — injected in tests
- * @param {Function} [o.log]  one-line breadcrumb sink (default no-op)
+ * @param {Function} [o.run]      command runner (default execSync) — injected in tests
+ * @param {Function} [o.has]      PATH probe (default commandExists) — injected in tests
+ * @param {Function} [o.resolve]  binary resolver (default resolveBinary) — injected in tests
+ * @param {Function} [o.log]      one-line breadcrumb sink (default no-op)
+ * @param {object}   [o.env]      environment (default process.env) — for the timeout override
  */
-function setupRtkIntegration({ run = execSync, has = commandExists, log = () => {} } = {}) {
-  const before = rtkStatus({ run });
+function setupRtkIntegration({
+  run = execSync,
+  has = commandExists,
+  resolve = resolveBinary,
+  log = () => {},
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const before = locateRtk({ run, has, resolve, env });
   if (before.installed) {
-    return wireHook({ run, log, installedVia: 'already-present', version: before.version });
+    return wireHook({ run, log, installedVia: 'already-present', version: before.version, bin: before.bin, env, platform });
   }
 
   const strat = pickStrategy({ has });
   if (!strat) {
-    log('rtk: no installer found (brew / cargo / curl) — skipped. BYAN install unaffected.');
+    log('rtk: no installer found (brew / curl / cargo) — skipped. BYAN install unaffected.');
     return { ok: true, synced: false, reason: 'no-installer', installed: false, hook: false };
   }
 
-  // Breadcrumb BEFORE the (silent, possibly slow) delegated install so the user
-  // is not left staring at a frozen prompt while rtk's installer runs.
-  log(`rtk: installing via ${strat.id} (pinned ${RTK_TAG}; this can take a moment)...`);
+  // Breadcrumb BEFORE the delegated install. stdio is INHERITED so the installer's
+  // own progress streams to the user (no frozen line), bounded by a timeout.
+  const timeoutMs = timeoutFor(strat, { env });
+  log(`rtk: installing via ${strat.id} (pinned ${RTK_TAG}; up to ${Math.round(timeoutMs / MIN)}min, Ctrl+C is safe)...`);
   try {
-    run(strat.cmd, { stdio: 'pipe' });
+    run(strat.cmd, { stdio: 'inherit', timeout: timeoutMs });
   } catch (err) {
+    if (isTimeout(err)) {
+      log(`rtk: install via ${strat.id} exceeded ${Math.round(timeoutMs / MIN)}min — stopped (a background build may still continue). Retry with 'npm run setup-rtk' (or widen BYAN_RTK_TIMEOUT_MS). BYAN unaffected.`);
+      return { ok: true, synced: false, reason: `install-timeout:${strat.id}`, installed: false, hook: false };
+    }
     log(`rtk: install via ${strat.id} failed (${oneLine(err)}) — skipped gracefully.`);
     return { ok: true, synced: false, reason: `install-failed:${strat.id}`, installed: false, hook: false };
   }
 
-  const after = rtkStatus({ run });
+  // The binary may be installed but OFF PATH (cargo -> ~/.cargo/bin). Resolve it
+  // before declaring failure, and wire it by its real location.
+  const after = locateRtk({ run, has, resolve, env });
   if (!after.installed) {
     log(`rtk: install via ${strat.id} ran but 'rtk --version' did not confirm — skipped.`);
     return { ok: true, synced: false, reason: 'install-unverified', installed: false, hook: false };
   }
 
-  return wireHook({ run, log, installedVia: strat.id, version: after.version });
+  return wireHook({ run, log, installedVia: strat.id, version: after.version, bin: after.bin, env, platform });
 }
 
 /**
@@ -171,12 +291,18 @@ function shouldOfferRtk({ env = process.env, isTTY = !!(process.stdin && process
 module.exports = {
   setupRtkIntegration,
   rtkStatus,
+  locateRtk,
   pickStrategy,
   installStrategies,
+  timeoutFor,
+  isTimeout,
+  pathHintFor,
   doctor,
   shouldOfferRtk,
   RTK_VERSION,
   RTK_TAG,
   RTK_INSTALL_SH,
   RTK_REPO,
+  RTK_TIMEOUT_MS,
+  RTK_DEFAULT_TIMEOUT_MS,
 };

package/install/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.29.1",
+  "version": "2.29.2",
   "description": "BYAN - Intelligent AI agent installer with multi-platform native support (Claude Code, Codex/OpenCode)",
   "bin": {
     "create-byan-agent": "bin/create-byan-agent-v2.js"

package/install/setup-rtk.js

@@ -16,14 +16,18 @@ const { setupRtkIntegration, doctor } = require('./lib/rtk-integration');
 
 function main() {
   console.log(chalk.cyan('\nRTK token optimizer (rtk-ai/rtk) — optional native component'));
-  console.log(chalk.gray('  Cuts dev-command tokens 60-90%; wires its own Claude Code hook.\n'));
+  console.log(chalk.gray('  Cuts dev-command tokens 60-90%; wires its own Claude Code hook.'));
+  console.log(chalk.gray('  Progress streams below. The cargo fallback compiles from source (minutes); Ctrl+C is safe.\n'));
 
   const result = setupRtkIntegration({ log: (m) => console.log(chalk.gray('  ' + m)) });
 
   if (result.synced) {
     console.log(chalk.green(`\n  rtk ready (${result.installedVia}, v${result.version || '?'}). Restart Claude Code to activate.`));
+    if (result.pathHint) console.log(chalk.yellow(`  rtk is not on your PATH — add it: ${result.pathHint}`));
   } else if (result.reason === 'no-installer') {
-    console.log(chalk.yellow('\n  No installer found (brew / cargo / curl). Install one, then re-run `npm run setup-rtk`.'));
+    console.log(chalk.yellow('\n  No installer found (brew / curl / cargo). Install one, then re-run `npm run setup-rtk`.'));
+  } else if (result.pathHint) {
+    console.log(chalk.yellow(`\n  rtk found off-PATH (${result.reason}) — add it then re-run: ${result.pathHint}`));
   } else {
     console.log(chalk.yellow(`\n  rtk not wired (${result.reason}). BYAN is unaffected; you can retry later.`));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.29.1",
+  "version": "2.29.2",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {