create-harness-vibe-coding 0.8.19 → 0.9.3

package/src/index.js

@@ -7,9 +7,12 @@ import pc from 'picocolors';
 import { askConflictPolicy, askInstallScope, askOptionalSelections, askProjectName, askTargetDir } from './prompts.js';
 import { generate, getOptionalCatalog } from './generator.js';
 
-const UPDATE_SUCCESS_STATUSES = new Set(['up-to-date', 'update-available', 'partial-update']);
-const UPDATE_FAILURE_STATUSES = new Set(['error', 'offline', 'template-remote', 'downgrade-refused']);
+const UPDATE_SUCCESS_STATUSES = new Set(['up-to-date', 'update-available', 'partial-update', 'ok']);
+const UPDATE_FAILURE_STATUSES = new Set(['error', 'offline', 'template-remote', 'downgrade-refused', 'timeout', 'locked', 'failed']);
 const CANONICAL_UPDATE_SOURCE_BASE = 'https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/';
+const DEFAULT_WF_UI_PORT = 56670;
+const DEFAULT_UPDATE_TIMEOUT_MS = 120000;
+const UPDATE_TIMEOUT_EXIT = 3;
 
 // ── CLI flags ──────────────────────────────────────────────
 const raw = process.argv.slice(2);
@@ -28,6 +31,16 @@ function hasFlag(args, flag) {
 // never fall through to the scaffold installer.
 if (raw[0] === 'wf-ui') {
   await runWfUi(raw.slice(1));
+  await flushStdout();
+  process.exit(0);
+}
+
+// init subcommand: bind an existing project to the global Harness runtime.
+// The global runtime (installed once via npm i -g) is the single version
+// source of truth; the project keeps only bridge docs plus its own state.
+if (raw[0] === 'init') {
+  runInit(raw.slice(1));
+  await flushStdout();
   process.exit(0);
 }
 
@@ -49,10 +62,13 @@ if (showHelp) {
   console.log('');
   console.log('  Usage:');
   console.log('    npx create-harness-vibe-coding@latest [project-name] [target-dir] [flags]');
+  console.log('    create-harness-vibe-coding init [target-dir] [flags]');
+  console.log('    create-harness-vibe-coding wf-ui --project . [flags]');
   console.log('');
   console.log('  Arguments:');
   console.log('    project-name   Name for the new project (default: my-vibe-project)');
   console.log('    target-dir     Directory to create the project in (default: ./<project-name>)');
+  console.log('    init           Bind an existing project to the global Harness runtime (thin bridge; global runtime is the single version source of truth)');
   console.log('');
   console.log('  Flags:');
   console.log('    -y, --yes                    Skip all prompts, use defaults or provided args');
@@ -63,7 +79,7 @@ if (showHelp) {
   console.log('    --without <id,id>            Remove optional workflow skills selected by --preset or --with');
   console.log('    --recommend <id,id>          Record recommendation-only external capabilities');
   console.log('    --preset <name>              Add a built-in optional workflow preset');
-  console.log('    --install-scope <scope>      project or global (default: project)');
+  console.log('    --install-scope <scope>      project or global (new project default: global; existing target keeps project compatibility)');
   console.log('    --global-dir <dir>           Global Harness runtime directory for --install-scope global');
   console.log('    --host-global-dir <dir>      Base directory for Claude/Codex/OpenCode global copies');
   console.log('    --list-options               Print optional workflow skills and presets');
@@ -82,6 +98,8 @@ if (showHelp) {
   console.log('    npx create-harness-vibe-coding@latest web ./web -y --preset web-app');
   console.log('    npx create-harness-vibe-coding@latest api ./api -y --preset fullstack --without github-pr-review');
   console.log('    npx create-harness-vibe-coding@latest app ./app -y --install-scope global');
+  console.log('    create-harness-vibe-coding init .             # Per-project init against the global runtime');
+  console.log('    create-harness-vibe-coding init . --dry-run');
   console.log('');
   process.exit(0);
 }
@@ -102,7 +120,10 @@ const generationOptions = {
   withoutOptions: parsed.flags.without || [],
   externalOptions: parsed.flags.recommend || [],
   preset: parsed.flags.preset,
-  installScope: parsed.flags.installScope || 'project',
+  // New repositories use the global runtime standard. Existing non-empty
+  // targets are switched back to project scope below unless the user chose a
+  // scope explicitly, preserving the historical installer behavior.
+  installScope: parsed.flags.installScope || 'global',
   globalDir: parsed.flags.globalDir,
   hostGlobalDir: parsed.flags.hostGlobalDir,
   json: Boolean(parsed.flags.json),
@@ -115,6 +136,9 @@ if (generationOptions.json) {
   const projectName = argName || DEFAULT_NAME;
   const targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
+  if (parsed.flags.installScope === undefined) {
+    generationOptions.installScope = defaultInstallScope(scan);
+  }
   if (needsScaffoldRecovery(scan)) {
     const recovery = createScaffoldRecoveryResult({ projectName, targetDir, options: generationOptions, scan });
     printJsonResult(recovery);
@@ -122,8 +146,9 @@ if (generationOptions.json) {
   }
 
   if (scan.hasHarness) {
-    printJsonResult(createUpdateSwitchResult(scan, { json: true }));
-    process.exit(0);
+    const updateResult = createUpdateSwitchResult(scan, { json: true });
+    printJsonResult(updateResult, { exitOnFailure: false });
+    process.exit(updateResult.success ? 0 : (updateResult.exitCode || 1));
   }
   const result = generate({ projectName, targetDir, ...generationOptions });
   result.scan = createJsonScan(scan);
@@ -154,6 +179,9 @@ if (argName || skipPrompts) {
   projectName = argName || DEFAULT_NAME;
   targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
+  if (parsed.flags.installScope === undefined) {
+    generationOptions.installScope = defaultInstallScope(scan);
+  }
 
   if (needsScaffoldRecovery(scan)) {
     process.exit(runScaffoldRecovery({ projectName, targetDir, options: generationOptions, scan }));
@@ -217,14 +245,15 @@ if (argName || skipPrompts) {
     console.log(pc.dim(`  Directory: ${targetDir} (default)`));
   }
 
+  const targetScan = scanTarget(targetDir);
   try {
-    generationOptions.installScope = await askInstallScope();
+    generationOptions.installScope = await askInstallScope(defaultInstallScope(targetScan));
   } catch {
-    generationOptions.installScope = 'project';
-    console.log(pc.dim('  Scope: project (default)'));
+    generationOptions.installScope = defaultInstallScope(targetScan);
+    console.log(pc.dim(`  Scope: ${generationOptions.installScope} (default)`));
   }
 
-  const scan = scanTarget(targetDir);
+  const scan = targetScan;
   printScan(scan);
 
   if (needsScaffoldRecovery(scan)) {
@@ -389,9 +418,11 @@ function printResult(result, targetDir) {
 async function runWfUi(args) {
   const projectRoot = extractFlag(args, '--project') || process.cwd();
   const host = extractFlag(args, '--host') || '127.0.0.1';
-  const rawPort = extractFlag(args, '--port') || '0';
+  const rawPort = extractFlag(args, '--port') || String(DEFAULT_WF_UI_PORT);
   const port = Number.parseInt(rawPort, 10);
   const openBrowser = !hasFlag(args, '--no-open');
+  const detach = hasFlag(args, '--detach');
+  const detachedChild = hasFlag(args, '--detached-child');
 
   if (host !== '127.0.0.1') {
     console.error('[wf-ui] host must be 127.0.0.1');
@@ -402,24 +433,36 @@ async function runWfUi(args) {
     process.exit(1);
   }
 
+  if (detach && !detachedChild) {
+    try {
+      await runDetachedWfUi(args);
+    } catch (err) {
+      console.error(`[wf-ui] ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   try {
     const serverModule = await import('./wf-ui-server/server.mjs');
     const { SessionRegistry } = await import('./wf-ui-server/session-registry.mjs');
-    const { attachEventsWs } = await import('./wf-ui-server/ws-events.mjs');
     const { attachTerminalWs } = await import('./wf-ui-server/ws-terminal.mjs');
+    const { attachWfBrowserWs } = await import('./wf-ui-server/ws-wf-browser.mjs');
     const { warmRuntimeCache } = await import('./wf-ui-server/runtime-detector.mjs');
     const { appendSessionEvent, appendTerminalData, persistSession, recordInputRequest } =
       await import('./wf-ui-server/terminal-store.mjs');
     const registry = new SessionRegistry();
     const terminalHub = {};
-    const started = await serverModule.startServer({
+    const wfBrowserHub = {};
+    const started = await startWfUiServerWithPortFallback(serverModule, {
       projectRoot,
       host,
       port,
       sessionRegistry: registry,
       terminalHub,
+      wfBrowserHub,
     });
-    attachEventsWs(started.server, started.token, projectRoot);
+    Object.assign(wfBrowserHub, attachWfBrowserWs(started.server, started.token, projectRoot));
     Object.assign(terminalHub, attachTerminalWs(started.server, started.token, registry, {
       onTerminalInput(session, data) {
         try {
@@ -439,15 +482,241 @@ async function runWfUi(args) {
       },
     }));
     warmRuntimeCache();
-    console.log(`[wf-ui] ${started.url}`);
+    await writeStdoutLine(`[wf-ui] ${started.url}`);
+    writeWfUiReadyFile(started.url, projectRoot);
     if (openBrowser) openLocalUrl(started.url);
-    await waitForWfUiShutdown(started.server);
+    try {
+      await waitForWfUiShutdown(started.server);
+    } finally {
+      cleanupWfUiLaunchDirFromReadyFile();
+    }
   } catch (err) {
     console.error(`[wf-ui] ${err.message}`);
     process.exit(1);
   }
 }
 
+async function startWfUiServerWithPortFallback(serverModule, options) {
+  const requestedPort = options.port;
+  let candidatePort = requestedPort;
+
+  while (true) {
+    try {
+      return await serverModule.startServer({ ...options, port: candidatePort });
+    } catch (err) {
+      if (requestedPort === 0 || err?.code !== 'EADDRINUSE') throw err;
+      if (candidatePort >= 65535) {
+        throw new Error(`ports ${requestedPort}-65535 are occupied`);
+      }
+      candidatePort += 1;
+    }
+  }
+}
+
+async function runDetachedWfUi(args) {
+  const projectRoot = extractFlag(args, '--project') || process.cwd();
+  const readyDir = process.env.HARNESS_WF_UI_READY_FILE
+    ? null
+    : makeProjectLocalWfUiLaunchDir(projectRoot);
+  const readyFile = process.env.HARNESS_WF_UI_READY_FILE || path.join(readyDir, 'ready.json');
+  const logFile = path.join(path.dirname(readyFile), 'wf-ui.log');
+  fs.mkdirSync(path.dirname(readyFile), { recursive: true });
+  try { fs.rmSync(readyFile, { force: true }); } catch {}
+
+  const childArgs = args.filter(arg => arg !== '--detach');
+  childArgs.push('--detached-child');
+  const child = spawnDetachedWfUiChild(childArgs, readyFile, logFile);
+
+  let childExit = null;
+  child.once('exit', (code, signal) => {
+    childExit = { code, signal };
+  });
+  child.unref();
+
+  const started = await waitForWfUiReadyFile(readyFile, () => {
+    if (process.platform === 'win32' && childExit?.code === 0) return null;
+    return childExit;
+  }, logFile);
+  spawnWfUiLaunchCleanupWatcher(started.pid, path.dirname(readyFile));
+  await writeStdoutLine(`[wf-ui] ${started.url}`);
+}
+
+function makeProjectLocalWfUiLaunchDir(projectRoot) {
+  const launchRoot = path.join(path.resolve(projectRoot || process.cwd()), 'Harness', '.temp', 'wf-ui-launch');
+  fs.mkdirSync(launchRoot, { recursive: true });
+  return fs.mkdtempSync(path.join(launchRoot, 'harness-wf-ui-'));
+}
+
+function spawnDetachedWfUiChild(childArgs, readyFile, logFile) {
+  if (process.platform === 'win32') {
+    const launcherScript = `
+const { spawn } = require('child_process');
+const fs = require('fs');
+const spec = JSON.parse(process.argv[1]);
+const logFd = fs.openSync(spec.logFile, 'a');
+const child = spawn(spec.execPath, spec.argv, {
+  cwd: spec.cwd,
+  detached: true,
+  env: { ...process.env, HARNESS_WF_UI_READY_FILE: spec.readyFile },
+  stdio: ['ignore', logFd, logFd],
+  windowsHide: true,
+});
+fs.closeSync(logFd);
+child.unref();
+`;
+    return spawn(process.execPath, ['-e', launcherScript, JSON.stringify({
+      execPath: process.execPath,
+      argv: [process.argv[1], 'wf-ui', ...childArgs],
+      cwd: process.cwd(),
+      readyFile,
+      logFile,
+    })], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+  }
+
+  const logFd = fs.openSync(logFile, 'a');
+  const child = spawn(process.execPath, [process.argv[1], 'wf-ui', ...childArgs], {
+    cwd: process.cwd(),
+    detached: true,
+    env: {
+      ...process.env,
+      HARNESS_WF_UI_READY_FILE: readyFile,
+    },
+    stdio: ['ignore', logFd, logFd],
+  });
+  fs.closeSync(logFd);
+  return child;
+}
+
+function writeWfUiReadyFile(url, projectRoot) {
+  const readyFile = process.env.HARNESS_WF_UI_READY_FILE;
+  if (!readyFile) return;
+  try {
+    fs.mkdirSync(path.dirname(readyFile), { recursive: true });
+    fs.writeFileSync(readyFile, `${JSON.stringify({
+      url,
+      pid: process.pid,
+      projectRoot: path.resolve(projectRoot),
+      startedAt: new Date().toISOString(),
+    })}\n`, 'utf8');
+  } catch (err) {
+    console.error(`[wf-ui] could not write ready file: ${err.message}`);
+  }
+}
+
+function isProjectLocalWfUiLaunchDir(dir) {
+  const resolved = path.resolve(dir);
+  const launchRoot = path.dirname(resolved);
+  return path.basename(resolved).startsWith('harness-wf-ui-')
+    && path.basename(launchRoot) === 'wf-ui-launch'
+    && path.basename(path.dirname(launchRoot)) === '.temp'
+    && path.basename(path.dirname(path.dirname(launchRoot))) === 'Harness';
+}
+
+function removeWfUiLaunchDir(dir) {
+  if (!isProjectLocalWfUiLaunchDir(dir)) return;
+  const resolved = path.resolve(dir);
+  const launchRoot = path.dirname(resolved);
+  try {
+    fs.rmSync(resolved, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup; the detached cleanup watcher also retries after process exit.
+  }
+  try {
+    if (fs.existsSync(launchRoot) && fs.readdirSync(launchRoot).length === 0) {
+      fs.rmdirSync(launchRoot);
+    }
+  } catch {
+    // no-op
+  }
+}
+
+function cleanupWfUiLaunchDirFromReadyFile() {
+  const readyFile = process.env.HARNESS_WF_UI_READY_FILE;
+  if (!readyFile) return;
+  removeWfUiLaunchDir(path.dirname(readyFile));
+}
+
+function spawnWfUiLaunchCleanupWatcher(pid, launchDir) {
+  if (!pid || !isProjectLocalWfUiLaunchDir(launchDir)) return;
+  const watcherScript = `
+const fs = require('fs');
+const path = require('path');
+const pid = Number(process.argv[1]);
+const dir = process.argv[2];
+const launchRoot = path.dirname(dir);
+function alive() {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function cleanup() {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+  try {
+    if (fs.existsSync(launchRoot) && fs.readdirSync(launchRoot).length === 0) {
+      fs.rmdirSync(launchRoot);
+    }
+  } catch {}
+}
+(function wait() {
+  if (!alive()) {
+    cleanup();
+    return;
+  }
+  setTimeout(wait, 1000);
+})();
+`;
+  try {
+    const watcher = spawn(process.execPath, ['-e', watcherScript, String(pid), path.resolve(launchDir)], {
+      cwd: process.cwd(),
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    watcher.unref();
+  } catch {
+    // no-op
+  }
+}
+
+function waitForWfUiReadyFile(readyFile, getChildExit, logFile) {
+  const deadline = Date.now() + 15000;
+  return new Promise((resolve, reject) => {
+    const poll = () => {
+      try {
+        if (fs.existsSync(readyFile)) {
+          const payload = JSON.parse(fs.readFileSync(readyFile, 'utf8'));
+          if (payload?.url) {
+            resolve(payload);
+            return;
+          }
+        }
+      } catch {
+        // The child may still be writing the handoff file.
+      }
+
+      const childExit = getChildExit();
+      if (childExit) {
+        reject(new Error(`detached server exited before startup (${childExit.signal || childExit.code}); log: ${logFile}`));
+        return;
+      }
+      if (Date.now() >= deadline) {
+        reject(new Error(`detached server did not report a URL within 15s; log: ${logFile}`));
+        return;
+      }
+      setTimeout(poll, 80);
+    };
+    poll();
+  });
+}
+
 function waitForWfUiShutdown(server) {
   return new Promise((resolve) => {
     let closing = false;
@@ -481,6 +750,135 @@ function openLocalUrl(url) {
   }
 }
 
+function flushStdout() {
+  return new Promise((resolve) => {
+    if (!process.stdout.writable || process.stdout.writableEnded) {
+      resolve();
+      return;
+    }
+    process.stdout.write('', resolve);
+  });
+}
+
+// init: bind an existing project to a Harness runtime (non-interactive).
+// Default scope `global`: the project gets thin bridge docs plus its own
+// state, while framework files/commands/skills/scripts live once in the
+// machine-level global runtime — the single version source of truth.
+// Scope `project` keeps the classic full project-level install: the whole
+// framework is copied into the project so it stays self-contained.
+// Safe to re-run: user-authored files are preserved under the default `skip`
+// conflict policy.
+function runInit(args) {
+  const valueFlags = new Set(['--global-dir', '--host-global-dir', '--on-conflict', '--scope']);
+  const scopeRaw = (extractFlag(args, '--scope') || 'global').trim().toLowerCase();
+  const installScope = scopeRaw === 'project' || scopeRaw === 'global' ? scopeRaw : null;
+  if (!installScope) {
+    console.error(pc.red(`[init] unknown --scope "${scopeRaw}". Use project or global.`));
+    process.exit(1);
+  }
+  const positional = args.find((arg, idx) => !arg.startsWith('-') && !valueFlags.has(args[idx - 1]));
+  const targetDir = positional || '.';
+  const scan = scanTarget(targetDir);
+
+  if (scan.hasHarness) {
+    if (hasFlag(args, '--json')) process.exit(runUpdateSwitch(scan, { json: true }));
+    console.log(pc.yellow(`\nHarness already detected in ${targetDir}. Nothing to init.`));
+    process.exit(runUpdateSwitch(scan, { json: false }));
+  }
+
+  const result = generate({
+    projectName: path.basename(path.resolve(process.cwd(), targetDir)),
+    targetDir,
+    dryRun: hasFlag(args, '--dry-run'),
+    onConflict: extractFlag(args, '--on-conflict') || 'skip',
+    withOptions: [],
+    withoutOptions: [],
+    externalOptions: [],
+    preset: undefined,
+    installScope,
+    globalDir: installScope === 'global' ? extractFlag(args, '--global-dir') : undefined,
+    hostGlobalDir: installScope === 'global' ? extractFlag(args, '--host-global-dir') : undefined,
+    json: hasFlag(args, '--json'),
+  });
+
+  if (hasFlag(args, '--json')) {
+    console.log(JSON.stringify({
+      success: result.success,
+      installScope: result.installScope,
+      globalDir: result.globalDir || null,
+      createdCount: result.created.length,
+      project: result.summary || null,
+      globalRuntime: result.globalSummary || null,
+      hosts: result.hostSummary || [],
+      errors: result.errors,
+      warnings: result.warnings,
+    }, null, 2));
+    if (!result.success) process.exit(1);
+    return;
+  }
+
+  if (!result.success) {
+    console.log(pc.red('\nInit failed:'));
+    for (const err of result.errors) {
+      console.log(pc.red(`  - ${err}`));
+    }
+    process.exit(1);
+  }
+
+  if (result.dryRun) {
+    console.log(pc.yellow('\nDry run: no files or directories were written.'));
+  } else {
+    console.log(pc.green(`\nInit complete (${installScope} scope).\n`));
+  }
+  console.log(pc.bold('Project install:'));
+  printInitSummary(result.summary);
+  if (result.globalSummary) {
+    console.log(pc.bold('\nGlobal runtime (single version source of truth):'));
+    console.log(`  Directory   ${pc.cyan(result.globalDir)}`);
+    printInitSummary(result.globalSummary);
+  }
+  for (const host of result.hostSummary || []) {
+    console.log(pc.bold(`\nHost copy (${host.host}):`));
+    console.log(`  Directory   ${pc.cyan(host.root)}`);
+    printInitSummary(host.summary);
+  }
+  printInitWarnings(result);
+
+  console.log(pc.bold('\nNext steps:'));
+  console.log(`  ${pc.cyan('/wf-ui')}            # Open the control panel${installScope === 'global' ? '; the global runtime serves this project' : ''}`);
+  console.log(`  ${pc.cyan('/wf <task>')}       # Start a workflow task in this project`);
+  if (installScope === 'global') {
+    console.log(pc.dim('\n  Project state (Harness/tasks, memory, PROGRESS.md) stays local to this project.'));
+    console.log(pc.dim('  Update the global runtime with /wf-update or `npm i -g create-harness-vibe-coding@latest`; every project picks it up.'));
+  } else {
+    console.log(pc.dim('\n  The full Harness framework lives in this project; update it per project with /wf-update.'));
+  }
+  console.log('');
+}
+
+function printInitSummary(summary) {
+  if (!summary) return;
+  console.log(`  Created ${summary.created}, skipped ${summary.skipped}, overwritten ${summary.overwritten}, backed up ${summary.backedUp}, conflicts ${summary.conflicts}`);
+}
+
+function printInitWarnings(result) {
+  if (!result.warnings || result.warnings.length === 0) return;
+  console.log(pc.yellow('\nWarning(s):'));
+  for (const warning of result.warnings) {
+    console.log(pc.yellow(`  - ${warning}`));
+  }
+}
+
+function writeStdoutLine(line) {
+  return new Promise((resolve) => {
+    if (!process.stdout.writable || process.stdout.writableEnded) {
+      resolve();
+      return;
+    }
+    process.stdout.write(`${line}\n`, resolve);
+  });
+}
+
 function parseArgs(args) {
   const flags = {
     with: [],
@@ -657,11 +1055,11 @@ function printWarnings(result) {
   }
 }
 
-function printJsonResult(result) {
+function printJsonResult(result, { exitOnFailure = true } = {}) {
   // Remove `created` array from output — it is already in the plan, avoid duplication
   const { created, globalCreated, hostCreated, ...rest } = result;
   console.log(JSON.stringify(rest, null, 2));
-  if (!result.success) {
+  if (exitOnFailure && !result.success) {
     process.exit(1);
   }
 }
@@ -670,6 +1068,59 @@ function updateScriptPath(scan) {
   return path.join(scan.resolvedDir, 'Harness', 'scripts', 'wf-update-check.mjs');
 }
 
+function updateTimeoutMs() {
+  const raw = process.env.WF_UPDATE_TIMEOUT_MS;
+  const parsed = raw ? Number.parseInt(raw, 10) : DEFAULT_UPDATE_TIMEOUT_MS;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_UPDATE_TIMEOUT_MS;
+}
+
+function readInstallMetadata(scan) {
+  const file = path.join(scan.resolvedDir, 'Harness', '.harness-version');
+  try {
+    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;
+  } catch {
+    return null;
+  }
+}
+
+function sameResolvedPath(left, right) {
+  if (!left || !right) return false;
+  const a = path.resolve(left);
+  const b = path.resolve(right);
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+function globalBridgeMetadata(scan) {
+  const metadata = readInstallMetadata(scan);
+  if (metadata?.installScope !== 'global' || !metadata.globalDir) return null;
+  const globalDir = path.resolve(metadata.globalDir);
+  if (sameResolvedPath(globalDir, scan.resolvedDir)) return null;
+  return { metadata, globalDir };
+}
+
+function globalBridgeUpdateTarget(scan) {
+  const bridge = globalBridgeMetadata(scan);
+  if (!bridge) return null;
+  const globalVersion = path.join(bridge.globalDir, 'Harness', '.harness-version');
+  const globalChecker = path.join(bridge.globalDir, 'Harness', 'scripts', 'wf-update-check.mjs');
+  const globalRunner = path.join(bridge.globalDir, 'Harness', 'scripts', 'wf-update-runner.mjs');
+  if (!fs.existsSync(globalVersion) || !fs.existsSync(globalChecker)) return null;
+  return {
+    root: bridge.globalDir,
+    scriptPath: fs.existsSync(globalRunner) ? globalRunner : globalChecker,
+    runner: fs.existsSync(globalRunner),
+    bridge: true,
+  };
+}
+
+function isGlobalBridge(scan) {
+  return Boolean(globalBridgeMetadata(scan));
+}
+
+function defaultInstallScope(scan) {
+  return scan.needsConflictPolicy && !isGlobalBridge(scan) ? 'project' : 'global';
+}
+
 function missingRecoveryReasons(scan) {
   const reasons = [];
   if (!fs.existsSync(updateScriptPath(scan))) reasons.push('Harness/scripts/wf-update-check.mjs');
@@ -677,7 +1128,9 @@ function missingRecoveryReasons(scan) {
 }
 
 function needsScaffoldRecovery(scan) {
-  return scan.hasHarness && missingRecoveryReasons(scan).length > 0;
+  // A global bridge intentionally omits local updater scripts. Do not turn it
+  // into a full project install just because its shared runtime is elsewhere.
+  return scan.hasHarness && !isGlobalBridge(scan) && missingRecoveryReasons(scan).length > 0;
 }
 
 function recoveryOptions(options) {
@@ -712,20 +1165,20 @@ function runScaffoldRecovery({ projectName, targetDir, options, scan }) {
 function runUpdateSwitch(scan, { json }) {
   const updateResult = createUpdateSwitchResult(scan, { json });
   if (json) {
-    printJsonResult(updateResult);
-    return updateResult.success ? 0 : 1;
+    printJsonResult(updateResult, { exitOnFailure: false });
+    return updateResult.success ? 0 : (updateResult.exitCode || 1);
   }
 
   console.log('');
   console.log(pc.yellow('Existing Harness detected. Switching to wf-update check.'));
   console.log(pc.dim(`Directory   ${scan.resolvedDir}`));
-  console.log(pc.dim('Command     node Harness/scripts/wf-update-check.mjs'));
+  console.log(pc.dim(`Command     ${updateResult.command || 'node Harness/scripts/wf-update-check.mjs'}`));
   console.log(pc.dim(`Source      ${CANONICAL_UPDATE_SOURCE_BASE}`));
   console.log('');
 
   if (!updateResult.success && updateResult.error) {
     console.error(pc.red(updateResult.error));
-    return 1;
+    return updateResult.exitCode ?? 1;
   }
 
   if (updateResult.stdout) process.stdout.write(updateResult.stdout);
@@ -747,35 +1200,64 @@ function getUpdateStatusError(update) {
 }
 
 function createUpdateSwitchResult(scan, { json }) {
-  const args = ['Harness/scripts/wf-update-check.mjs'];
+  const bridge = globalBridgeMetadata(scan);
+  const bridgeTarget = globalBridgeUpdateTarget(scan);
+  const target = bridgeTarget || (bridge ? {
+    root: bridge.globalDir,
+    scriptPath: path.join(bridge.globalDir, 'Harness', 'scripts', 'wf-update-check.mjs'),
+    runner: false,
+    bridge: true,
+  } : {
+    root: scan.resolvedDir,
+    scriptPath: updateScriptPath(scan),
+    runner: false,
+    bridge: false,
+  });
+  const args = target.runner
+    ? [target.scriptPath, '--project', scan.resolvedDir]
+    : [target.scriptPath];
   if (json) args.push('--json');
-
-  const scriptPath = path.join(scan.resolvedDir, 'Harness', 'scripts', 'wf-update-check.mjs');
-  const command = `node ${args.join(' ')}`;
+  const command = `node ${args.map(value => (/\s/.test(value) ? JSON.stringify(value) : value)).join(' ')}`;
   const base = {
     success: false,
     mode: 'update',
     scan: createJsonScan(scan),
     agent: {
       sourceOfTruth: 'Existing Harness detected; install automatically switched to the target update checker. Do not continue install writes.',
-      updateCommand: json
-        ? 'node Harness/scripts/wf-update-check.mjs --json'
-        : 'node Harness/scripts/wf-update-check.mjs',
+      updateCommand: command,
       updateSourceBase: CANONICAL_UPDATE_SOURCE_BASE,
       next: [
         {
           action: 'update',
-          command: json
-            ? 'node Harness/scripts/wf-update-check.mjs --json'
-            : 'node Harness/scripts/wf-update-check.mjs',
+          command,
           env: { WF_SOURCE_BASE: CANONICAL_UPDATE_SOURCE_BASE },
-          reason: 'Harness already exists, so updates must use the installed Harness update flow.',
+          reason: target.bridge
+            ? 'This project is a thin global bridge; the shared runtime is the single update source of truth.'
+            : 'Harness already exists, so updates must use the installed Harness update flow.',
         },
       ],
     },
   };
 
-  if (!fs.existsSync(scriptPath)) {
+  if (!fs.existsSync(target.scriptPath)) {
+    if (target.bridge) {
+      return {
+        ...base,
+        success: false,
+        exitCode: 1,
+        error: 'This project is a global Harness bridge, but its shared global runtime was not found. No project files were written. Reinstall or update the global create-harness-vibe-coding runtime, then retry.',
+        errors: ['global Harness runtime not found'],
+        agent: {
+          ...base.agent,
+          next: [{
+            action: 'global-runtime-recovery',
+            reason: 'The bridge must not be expanded into a project install when the shared runtime is unavailable.',
+            command: 'npm install --global create-harness-vibe-coding@latest',
+            note: 'The project bridge remains untouched; reinstalling the one global runtime restores the shared update source.',
+          }],
+        },
+      };
+    }
     return {
       ...base,
       success: false,
@@ -795,8 +1277,10 @@ function createUpdateSwitchResult(scan, { json }) {
   }
 
   const result = spawnSync(process.execPath, args, {
-    cwd: scan.resolvedDir,
+    cwd: target.root,
     encoding: 'utf8',
+    timeout: updateTimeoutMs(),
+    killSignal: 'SIGTERM',
     env: {
       ...process.env,
       WF_SOURCE_BASE: CANONICAL_UPDATE_SOURCE_BASE,
@@ -804,7 +1288,8 @@ function createUpdateSwitchResult(scan, { json }) {
   });
   const stdout = result.stdout || '';
   const stderr = result.stderr || '';
-  const status = result.status ?? 1;
+  const timedOut = result.error?.code === 'ETIMEDOUT';
+  const status = timedOut ? UPDATE_TIMEOUT_EXIT : (result.status ?? 1);
 
   let update = undefined;
   if (json && stdout.trim()) {
@@ -814,9 +1299,16 @@ function createUpdateSwitchResult(scan, { json }) {
       update = { rawOutput: stdout };
     }
   }
+  if (timedOut && !update) {
+    update = {
+      status: 'timeout',
+      code: 'UPDATE_TIMEOUT',
+      message: `Update command exceeded the ${updateTimeoutMs()}ms deadline.`,
+    };
+  }
 
   const errors = [];
-  if (status !== 0) errors.push(`Update checker exited with status ${status}`);
+  if (status !== 0) errors.push(timedOut ? `Update checker exceeded the ${updateTimeoutMs()}ms deadline` : `Update checker exited with status ${status}`);
   if (json) {
     const statusError = getUpdateStatusError(update);
     if (statusError) errors.push(statusError);
@@ -829,6 +1321,7 @@ function createUpdateSwitchResult(scan, { json }) {
     command,
     stdout,
     stderr,
+    ...(timedOut ? { timedOut: true, errorCode: 'UPDATE_TIMEOUT' } : {}),
     ...(json ? { update } : {}),
     ...(errors.length === 0 ? {} : { error: errors[0], errors }),
   };