create-harness-vibe-coding 0.8.17 → 0.8.19

package/src/index.js

@@ -2,90 +2,115 @@
 import * as p from '@clack/prompts';
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import pc from 'picocolors';
-import { askConflictPolicy, askOptionalSelections, askProjectName, askTargetDir } from './prompts.js';
+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 CANONICAL_UPDATE_SOURCE_BASE = 'https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/';
-
-// ── CLI flags ──────────────────────────────────────────────
-const raw = process.argv.slice(2);
+
+// ── CLI flags ──────────────────────────────────────────────
+const raw = process.argv.slice(2);
+function extractFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  const withEquals = args.find(arg => arg.startsWith(`${flag}=`));
+  if (withEquals) return withEquals.slice(flag.length + 1);
+  return null;
+}
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+// wf-ui subcommand: handle before parseArgs so --project/--port/--open flags
+// never fall through to the scaffold installer.
+if (raw[0] === 'wf-ui') {
+  await runWfUi(raw.slice(1));
+  process.exit(0);
+}
+
 const parsed = parseArgs(raw);
 const showHelp = parsed.flags.help || parsed.flags.h;
 const skipPrompts = parsed.flags.yes || parsed.flags.y;
 const conflictPolicyProvided = parsed.flags.onConflict !== undefined;
-
-if (parsed.errors.length > 0) {
-  for (const err of parsed.errors) {
-    console.error(pc.red(`Error: ${err}`));
-  }
-  process.exit(1);
-}
-
-if (showHelp) {
-  console.log('');
-  console.log('  create-harness-vibe-coding');
-  console.log('');
-  console.log('  Usage:');
-  console.log('    npx create-harness-vibe-coding@latest [project-name] [target-dir] [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('');
-  console.log('  Flags:');
-  console.log('    -y, --yes                    Skip all prompts, use defaults or provided args');
-  console.log('    -h, --help                   Show this help');
-  console.log('    --dry-run                    Print the planned writes without creating files');
-  console.log('    --on-conflict <policy>       fail, skip, backup, or overwrite (default: fail)');
+
+if (parsed.errors.length > 0 && raw[0] !== 'wf-ui') {
+  for (const err of parsed.errors) {
+    console.error(pc.red(`Error: ${err}`));
+  }
+  process.exit(1);
+}
+
+if (showHelp) {
+  console.log('');
+  console.log('  create-harness-vibe-coding');
+  console.log('');
+  console.log('  Usage:');
+  console.log('    npx create-harness-vibe-coding@latest [project-name] [target-dir] [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('');
+  console.log('  Flags:');
+  console.log('    -y, --yes                    Skip all prompts, use defaults or provided args');
+  console.log('    -h, --help                   Show this help');
+  console.log('    --dry-run                    Print the planned writes without creating files');
+  console.log('    --on-conflict <policy>       fail, skip, backup, or overwrite (default: fail)');
   console.log('    --with <id,id>               Add optional local workflow skills');
   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('    --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');
   console.log('    --json                       Output machine-readable JSON (use with --dry-run for planning)');
   console.log('');
   console.log('  Interactive mode offers checkbox selection for optional workflows and external recommendations.');
-  console.log('');
-  console.log('  Examples:');
-  console.log('    npx create-harness-vibe-coding@latest');
-  console.log('    npx create-harness-vibe-coding@latest -y');
-  console.log('    npx create-harness-vibe-coding@latest my-project');
-  console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
-  console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --dry-run');
-  console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --on-conflict skip');
+  console.log('');
+  console.log('  Examples:');
+  console.log('    npx create-harness-vibe-coding@latest');
+  console.log('    npx create-harness-vibe-coding@latest -y');
+  console.log('    npx create-harness-vibe-coding@latest my-project');
+  console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
+  console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --dry-run');
+  console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --on-conflict skip');
   console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,ui-ux-review');
-  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('');
-  process.exit(0);
-}
-
-if (parsed.flags.listOptions) {
-  printOptions();
-  process.exit(0);
-}
-
-// Positional args (non-flag)
-const positional = parsed.positionals;
-const argName = positional[0];
-const argDir = positional[1];
-const generationOptions = {
-  dryRun: Boolean(parsed.flags.dryRun),
-  onConflict: parsed.flags.onConflict || 'fail',
-  withOptions: parsed.flags.with || [],
+  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('');
+  process.exit(0);
+}
+
+if (parsed.flags.listOptions) {
+  printOptions();
+  process.exit(0);
+}
+
+// Positional args (non-flag)
+const positional = parsed.positionals;
+const argName = positional[0];
+const argDir = positional[1];
+const generationOptions = {
+  dryRun: Boolean(parsed.flags.dryRun),
+  onConflict: parsed.flags.onConflict || 'fail',
+  withOptions: parsed.flags.with || [],
   withoutOptions: parsed.flags.without || [],
   externalOptions: parsed.flags.recommend || [],
   preset: parsed.flags.preset,
+  installScope: parsed.flags.installScope || 'project',
+  globalDir: parsed.flags.globalDir,
+  hostGlobalDir: parsed.flags.hostGlobalDir,
   json: Boolean(parsed.flags.json),
 };
-
-const DEFAULT_NAME = 'my-vibe-project';
-
-// --json: machine-readable output, no prompts, no decorative output
+
+const DEFAULT_NAME = 'my-vibe-project';
+
+// --json: machine-readable output, no prompts, no decorative output
 if (generationOptions.json) {
   const projectName = argName || DEFAULT_NAME;
   const targetDir = argDir || `./${projectName}`;
@@ -109,20 +134,22 @@ if (generationOptions.json) {
     scan,
   });
   printJsonResult(result);
-  // printJsonResult exits with 1 on failure; we only reach here on success
-  process.exit(0);
-}
-
-console.log('');
-console.log(pc.magenta('╔══════════════════════════════════════════╗'));
-console.log(pc.magenta('║   create-harness-vibe-coding             ║'));
-console.log(pc.magenta('║   0-1 Product Harness Scaffold           ║'));
-console.log(pc.magenta('╚══════════════════════════════════════════╝'));
-console.log('');
-
-let projectName, targetDir;
-
-// Non-interactive: positionals provided OR -y/--yes flag set
+  // printJsonResult exits with 1 on failure; we only reach here on success
+  process.exit(0);
+}
+
+console.log('');
+console.log(pc.magenta('╔══════════════════════════════════════════╗'));
+console.log(pc.magenta('║   create-harness-vibe-coding             ║'));
+console.log(pc.magenta('║   0-1 Product Harness Scaffold           ║'));
+console.log(pc.magenta('╚══════════════════════════════════════════╝'));
+console.log('');
+
+let projectName, targetDir;
+
+// wf-ui: server already running, skip the scaffold/update flow
+if (raw[0] !== 'wf-ui') {
+// Non-interactive: positionals provided OR -y/--yes flag set
 if (argName || skipPrompts) {
   projectName = argName || DEFAULT_NAME;
   targetDir = argDir || `./${projectName}`;
@@ -137,47 +164,64 @@ if (argName || skipPrompts) {
   }
 
   console.log(pc.dim('────────────────────────────────────────────'));
-  console.log(`  Project     ${pc.green(projectName)}`);
+  console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/')}`);
-  if (generationOptions.dryRun) {
+  console.log(`  Scope       ${pc.green(generationOptions.installScope)}`);
+  if (generationOptions.globalDir) {
+    console.log(`  Global dir  ${pc.green(generationOptions.globalDir)}`);
+  }
+  if (generationOptions.hostGlobalDir) {
+    console.log(`  Host dir    ${pc.green(generationOptions.hostGlobalDir)}`);
+  }
+  const creates = generationOptions.installScope === 'global'
+    ? 'project bridge/state/settings + global runtime + Claude/Codex/OpenCode host copies'
+    : 'CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/';
+  console.log(`  Creates     ${pc.cyan(creates)}`);
+  if (generationOptions.dryRun) {
     console.log(`  Mode        ${pc.yellow('dry-run')}`);
-  }
-  console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
-  if (generationOptions.withOptions.length > 0) {
-    console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
-  }
+  }
+  console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
+  if (generationOptions.withOptions.length > 0) {
+    console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
+  }
   if (generationOptions.withoutOptions.length > 0) {
     console.log(`  Without     ${pc.cyan(generationOptions.withoutOptions.join(','))}`);
   }
   if (generationOptions.externalOptions.length > 0) {
     console.log(`  Recommend   ${pc.cyan(generationOptions.externalOptions.join(','))}`);
   }
-  if (generationOptions.preset) {
-    console.log(`  Preset      ${pc.cyan(generationOptions.preset)}`);
-  }
-  if (skipPrompts) {
-    console.log(`  Mode        ${pc.dim('non-interactive (-y)')}`);
-  }
-  console.log(pc.dim('────────────────────────────────────────────'));
-  console.log('');
-
-  const result = generate({ projectName, targetDir, ...generationOptions });
-  printResult(result, targetDir);
-} else {
-  // Interactive mode
-  try {
-    projectName = await askProjectName();
-  } catch {
-    projectName = 'my-vibe-project';
-    console.log(pc.dim(`  Project: ${projectName} (default)`));
-  }
-
+  if (generationOptions.preset) {
+    console.log(`  Preset      ${pc.cyan(generationOptions.preset)}`);
+  }
+  if (skipPrompts) {
+    console.log(`  Mode        ${pc.dim('non-interactive (-y)')}`);
+  }
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log('');
+
+  const result = generate({ projectName, targetDir, ...generationOptions });
+  printResult(result, targetDir);
+} else {
+  // Interactive mode
+  try {
+    projectName = await askProjectName();
+  } catch {
+    projectName = 'my-vibe-project';
+    console.log(pc.dim(`  Project: ${projectName} (default)`));
+  }
+
   try {
     targetDir = await askTargetDir(projectName);
   } catch {
-    targetDir = `./${projectName}`;
-    console.log(pc.dim(`  Directory: ${targetDir} (default)`));
+    targetDir = `./${projectName}`;
+    console.log(pc.dim(`  Directory: ${targetDir} (default)`));
+  }
+
+  try {
+    generationOptions.installScope = await askInstallScope();
+  } catch {
+    generationOptions.installScope = 'project';
+    console.log(pc.dim('  Scope: project (default)'));
   }
 
   const scan = scanTarget(targetDir);
@@ -216,12 +260,22 @@ if (argName || skipPrompts) {
       console.log(pc.dim('  Optional: none (default)'));
     }
   }
-
-  console.log('');
-  console.log(pc.dim('────────────────────────────────────────────'));
-  console.log(`  Project     ${pc.green(projectName)}`);
+
+  console.log('');
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/')}`);
+  console.log(`  Scope       ${pc.green(generationOptions.installScope)}`);
+  if (generationOptions.globalDir) {
+    console.log(`  Global dir  ${pc.green(generationOptions.globalDir)}`);
+  }
+  if (generationOptions.hostGlobalDir) {
+    console.log(`  Host dir    ${pc.green(generationOptions.hostGlobalDir)}`);
+  }
+  const creates = generationOptions.installScope === 'global'
+    ? 'project bridge/state + global runtime + Claude/Codex/OpenCode host copies'
+    : 'CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/';
+  console.log(`  Creates     ${pc.cyan(creates)}`);
   console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
   if (generationOptions.withOptions.length > 0) {
     console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
@@ -229,145 +283,264 @@ if (argName || skipPrompts) {
   if (generationOptions.externalOptions.length > 0) {
     console.log(`  Recommend   ${pc.cyan(generationOptions.externalOptions.join(','))}`);
   }
-  console.log(pc.dim('────────────────────────────────────────────'));
-  console.log('');
-
-  const preview = generate({ projectName, targetDir, ...generationOptions, dryRun: true });
-  if (!preview.success) {
-    printResult(preview, targetDir);
-  }
-
-  console.log(pc.yellow('Planned changes: no files have been written yet.'));
-  printSummary(preview.summary);
-  printPlan(preview.plan);
-  printWarnings(preview);
-  console.log('');
-
-  if (generationOptions.dryRun) {
-    process.exit(0);
-  }
-
-  let proceed = true;
-  try {
-    proceed = await p.confirm({
-      message: 'Confirm generation with this plan?',
-      initialValue: true,
-    });
-    if (p.isCancel(proceed)) proceed = false;
-  } catch {
-    proceed = true;
-  }
-
-  if (!proceed) {
-    p.cancel('Cancelled');
-    process.exit(0);
-  }
-
-  console.log('');
-  const result = generate({ projectName, targetDir, ...generationOptions });
-  printResult(result, targetDir);
-}
-
-function printResult(result, targetDir) {
-  if (result.success) {
-    if (result.dryRun) {
-      console.log(pc.yellow('\nDry run: no files or directories were written.'));
-      printSummary(result.summary);
-      printPlan(result.plan);
-      if (result.warnings.length > 0) {
-        console.log(pc.yellow('\nWarning(s):'));
-        for (const warning of result.warnings) {
-          console.log(pc.yellow(`  - ${warning}`));
-        }
-      }
-      console.log('');
-      return;
-    }
-
-    console.log(pc.green('\nGeneration complete.\n'));
-    printSummary(result.summary);
-
-    printWarnings(result);
-
+  console.log(pc.dim('────────────────────────────────────────────'));
+  console.log('');
+
+  const preview = generate({ projectName, targetDir, ...generationOptions, dryRun: true });
+  if (!preview.success) {
+    printResult(preview, targetDir);
+  }
+
+  console.log(pc.yellow('Planned changes: no files have been written yet.'));
+  console.log(pc.bold('Project plan:'));
+  printSummary(preview.summary);
+  printPlan(preview.plan);
+  if (preview.globalPlan) {
+    console.log(pc.bold('\nGlobal runtime plan:'));
+    console.log(`  Directory   ${pc.cyan(preview.globalDir)}`);
+    printSummary(preview.globalSummary);
+    printPlan(preview.globalPlan);
+  }
+  printHostPlans(preview.hostPlans, preview.hostSummary);
+  printWarnings(preview);
+  console.log('');
+
+  if (generationOptions.dryRun) {
+    process.exit(0);
+  }
+
+  let proceed = true;
+  try {
+    proceed = await p.confirm({
+      message: 'Confirm generation with this plan?',
+      initialValue: true,
+    });
+    if (p.isCancel(proceed)) proceed = false;
+  } catch {
+    proceed = true;
+  }
+
+  if (!proceed) {
+    p.cancel('Cancelled');
+    process.exit(0);
+  }
+
+  console.log('');
+  const result = generate({ projectName, targetDir, ...generationOptions });
+  printResult(result, targetDir);
+}
+
+function printResult(result, targetDir) {
+  if (result.success) {
+    if (result.dryRun) {
+      console.log(pc.yellow('\nDry run: no files or directories were written.'));
+      console.log(pc.bold('Project plan:'));
+      printSummary(result.summary);
+      printPlan(result.plan);
+      if (result.globalPlan) {
+        console.log(pc.bold('\nGlobal runtime plan:'));
+        console.log(`  Directory   ${pc.cyan(result.globalDir)}`);
+        printSummary(result.globalSummary);
+        printPlan(result.globalPlan);
+      }
+      printHostPlans(result.hostPlans, result.hostSummary);
+      if (result.warnings.length > 0) {
+        console.log(pc.yellow('\nWarning(s):'));
+        for (const warning of result.warnings) {
+          console.log(pc.yellow(`  - ${warning}`));
+        }
+      }
+      console.log('');
+      return;
+    }
+
+    console.log(pc.green('\nGeneration complete.\n'));
+    console.log(pc.bold('Project install:'));
+    printSummary(result.summary);
+    if (result.globalSummary) {
+      console.log(pc.bold('Global runtime:'));
+      console.log(`  Directory   ${pc.cyan(result.globalDir)}`);
+      printSummary(result.globalSummary);
+    }
+    printHostPlans(result.hostPlans, result.hostSummary, { summaryOnly: true });
+
+    printWarnings(result);
+
     console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
-    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
-    console.log(`  ${pc.cyan('codex')}                           # Or start Codex`);
-    console.log(`  ${pc.cyan('opencode')}                        # Or start OpenCode`);
+    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
+    console.log(`  ${pc.cyan('codex')}                           # Or start Codex`);
+    console.log(`  ${pc.cyan('opencode')}                        # Or start OpenCode`);
     console.log(`  Tell your agent: "${pc.yellow('Read Harness/specs/guides/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
-    console.log('');
+    console.log('');
     console.log(pc.dim('  Keep Harness/specs/guides/SETUP.md as a setup reference; normal sessions start at CLAUDE.md, with Harness/README.md as the routed workflow router.'));
-    console.log('');
-
-  } else {
-    console.log(pc.red('\nGeneration failed:'));
-    for (const err of result.errors) {
-      console.log(pc.red(`  - ${err}`));
-    }
-    process.exit(1);
-  }
-}
-
-function parseArgs(args) {
-  const flags = {
-    with: [],
-    without: [],
-  };
-  const positionals = [];
-  const errors = [];
-
-  function readValue(flagName, index) {
-    const value = args[index + 1];
-    if (!value || value.startsWith('-')) {
-      errors.push(`${flagName} requires a value`);
-      return { value: undefined, nextIndex: index };
-    }
-    return { value, nextIndex: index + 1 };
-  }
-
-  function readEqualsValue(flagName, value) {
-    if (!value || value.startsWith('-')) {
-      errors.push(`${flagName} requires a value`);
-      return undefined;
-    }
-    return value;
-  }
-
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-
-    if (arg === '-h') {
-      flags.h = true;
-    } else if (arg === '--help') {
-      flags.help = true;
-    } else if (arg === '-y') {
-      flags.y = true;
-    } else if (arg === '--yes') {
-      flags.yes = true;
-    } else if (arg === '--dry-run') {
-      flags.dryRun = true;
+    console.log('');
+
+  } else {
+    console.log(pc.red('\nGeneration failed:'));
+    for (const err of result.errors) {
+      console.log(pc.red(`  - ${err}`));
+    }
+    process.exit(1);
+  }
+}
+} // wf-ui skip block end — functions below are module-scoped
+
+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 port = Number.parseInt(rawPort, 10);
+  const openBrowser = !hasFlag(args, '--no-open');
+
+  if (host !== '127.0.0.1') {
+    console.error('[wf-ui] host must be 127.0.0.1');
+    process.exit(1);
+  }
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error('[wf-ui] port must be an integer from 0 to 65535');
+    process.exit(1);
+  }
+
+  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 { 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({
+      projectRoot,
+      host,
+      port,
+      sessionRegistry: registry,
+      terminalHub,
+    });
+    attachEventsWs(started.server, started.token, projectRoot);
+    Object.assign(terminalHub, attachTerminalWs(started.server, started.token, registry, {
+      onTerminalInput(session, data) {
+        try {
+          recordInputRequest(projectRoot, session.sessionId, data);
+        } catch {
+          // The session may not have been persisted yet; stdout/stderr capture still remains authoritative.
+        }
+        appendTerminalData(projectRoot, session, data, 'stdin');
+      },
+      onAttachModeChange(session, attachMode) {
+        persistSession(projectRoot, session);
+        appendSessionEvent(projectRoot, session, { type: 'session.attach-mode', attachMode });
+      },
+      onSessionState(session, state) {
+        persistSession(projectRoot, session);
+        appendSessionEvent(projectRoot, session, { type: 'session.state', state });
+      },
+    }));
+    warmRuntimeCache();
+    console.log(`[wf-ui] ${started.url}`);
+    if (openBrowser) openLocalUrl(started.url);
+    await waitForWfUiShutdown(started.server);
+  } catch (err) {
+    console.error(`[wf-ui] ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function waitForWfUiShutdown(server) {
+  return new Promise((resolve) => {
+    let closing = false;
+    const shutdown = () => {
+      if (closing) return;
+      closing = true;
+      server.close(() => resolve());
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    server.once('close', resolve);
+  });
+}
+
+function openLocalUrl(url) {
+  const command = process.platform === 'win32'
+    ? { file: 'cmd', args: ['/c', 'start', '', url] }
+    : process.platform === 'darwin'
+      ? { file: 'open', args: [url] }
+      : { file: 'xdg-open', args: [url] };
+
+  try {
+    const child = spawn(command.file, command.args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+  } catch (err) {
+    console.error(`[wf-ui] could not open browser automatically: ${err.message}`);
+  }
+}
+
+function parseArgs(args) {
+  const flags = {
+    with: [],
+    without: [],
+  };
+  const positionals = [];
+  const errors = [];
+
+  function readValue(flagName, index) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('-')) {
+      errors.push(`${flagName} requires a value`);
+      return { value: undefined, nextIndex: index };
+    }
+    return { value, nextIndex: index + 1 };
+  }
+
+  function readEqualsValue(flagName, value) {
+    if (!value || value.startsWith('-')) {
+      errors.push(`${flagName} requires a value`);
+      return undefined;
+    }
+    return value;
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '-h') {
+      flags.h = true;
+    } else if (arg === '--help') {
+      flags.help = true;
+    } else if (arg === '-y') {
+      flags.y = true;
+    } else if (arg === '--yes') {
+      flags.yes = true;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
     } else if (arg === '--list-options') {
       flags.listOptions = true;
     } else if (arg === '--json') {
       flags.json = true;
-    } else if (arg === '--on-conflict') {
-      const parsedValue = readValue('--on-conflict', i);
-      flags.onConflict = parsedValue.value;
-      i = parsedValue.nextIndex;
-    } else if (arg.startsWith('--on-conflict=')) {
-      flags.onConflict = readEqualsValue('--on-conflict', arg.slice('--on-conflict='.length));
-    } else if (arg === '--with') {
-      const parsedValue = readValue('--with', i);
-      if (parsedValue.value !== undefined) flags.with.push(parsedValue.value);
-      i = parsedValue.nextIndex;
-    } else if (arg.startsWith('--with=')) {
-      const value = readEqualsValue('--with', arg.slice('--with='.length));
-      if (value !== undefined) flags.with.push(value);
-    } else if (arg === '--without') {
-      const parsedValue = readValue('--without', i);
-      if (parsedValue.value !== undefined) flags.without.push(parsedValue.value);
-      i = parsedValue.nextIndex;
-    } else if (arg.startsWith('--without=')) {
+    } else if (arg === '--on-conflict') {
+      const parsedValue = readValue('--on-conflict', i);
+      flags.onConflict = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--on-conflict=')) {
+      flags.onConflict = readEqualsValue('--on-conflict', arg.slice('--on-conflict='.length));
+    } else if (arg === '--with') {
+      const parsedValue = readValue('--with', i);
+      if (parsedValue.value !== undefined) flags.with.push(parsedValue.value);
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--with=')) {
+      const value = readEqualsValue('--with', arg.slice('--with='.length));
+      if (value !== undefined) flags.with.push(value);
+    } else if (arg === '--without') {
+      const parsedValue = readValue('--without', i);
+      if (parsedValue.value !== undefined) flags.without.push(parsedValue.value);
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--without=')) {
       const value = readEqualsValue('--without', arg.slice('--without='.length));
       if (value !== undefined) flags.without.push(value);
     } else if (arg === '--recommend') {
@@ -384,30 +557,48 @@ function parseArgs(args) {
         flags.recommend.push(value);
       }
     } else if (arg === '--preset') {
-      const parsedValue = readValue('--preset', i);
-      flags.preset = parsedValue.value;
-      i = parsedValue.nextIndex;
-    } else if (arg.startsWith('--preset=')) {
-      flags.preset = readEqualsValue('--preset', arg.slice('--preset='.length));
-    } else if (arg.startsWith('-')) {
-      errors.push(`Unknown flag "${arg}"`);
-    } else {
-      positionals.push(arg);
-    }
-  }
-
-  return { flags, positionals, errors };
-}
-
-function printOptions() {
-  const catalog = getOptionalCatalog();
-
-  console.log('');
-  console.log(pc.bold('Optional workflow skills:'));
-  for (const skill of catalog.skills) {
-    console.log(`  ${pc.cyan(skill.id)} - ${skill.description}`);
-  }
-
+      const parsedValue = readValue('--preset', i);
+      flags.preset = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--preset=')) {
+      flags.preset = readEqualsValue('--preset', arg.slice('--preset='.length));
+    } else if (arg === '--install-scope') {
+      const parsedValue = readValue('--install-scope', i);
+      flags.installScope = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--install-scope=')) {
+      flags.installScope = readEqualsValue('--install-scope', arg.slice('--install-scope='.length));
+    } else if (arg === '--global-dir') {
+      const parsedValue = readValue('--global-dir', i);
+      flags.globalDir = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--global-dir=')) {
+      flags.globalDir = readEqualsValue('--global-dir', arg.slice('--global-dir='.length));
+    } else if (arg === '--host-global-dir') {
+      const parsedValue = readValue('--host-global-dir', i);
+      flags.hostGlobalDir = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--host-global-dir=')) {
+      flags.hostGlobalDir = readEqualsValue('--host-global-dir', arg.slice('--host-global-dir='.length));
+    } else if (arg.startsWith('-')) {
+      errors.push(`Unknown flag "${arg}"`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  return { flags, positionals, errors };
+}
+
+function printOptions() {
+  const catalog = getOptionalCatalog();
+
+  console.log('');
+  console.log(pc.bold('Optional workflow skills:'));
+  for (const skill of catalog.skills) {
+    console.log(`  ${pc.cyan(skill.id)} - ${skill.description}`);
+  }
+
   console.log('');
   console.log(pc.bold('Presets:'));
   for (const [name, skills] of Object.entries(catalog.presets)) {
@@ -423,42 +614,55 @@ function printOptions() {
   }
   console.log('');
 }
-
-function printSummary(summary) {
-  console.log(`  created     ${pc.green(summary.created)}`);
-  console.log(`  skipped     ${pc.yellow(summary.skipped)}`);
-  console.log(`  backed up   ${pc.cyan(summary.backedUp)}`);
-  console.log(`  overwritten ${pc.cyan(summary.overwritten)}`);
-  console.log(`  conflicts   ${summary.conflicts > 0 ? pc.red(summary.conflicts) : pc.dim(summary.conflicts)}`);
-  console.log(`  directories ${pc.dim(summary.mkdir)}`);
-  console.log('');
-}
-
-function printPlan(plan) {
-  for (const [label, files] of Object.entries(plan)) {
-    if (!files.length) continue;
-    console.log(`  ${label}:`);
-    for (const file of files) {
-      console.log(`    - ${file}`);
-    }
-  }
-}
-
-function printWarnings(result) {
-  if (!result.warnings.length) return;
-
-  console.log(pc.yellow('\nWarning(s):'));
-  for (const warning of result.warnings) {
-    console.log(pc.yellow(`  - ${warning}`));
-  }
-}
-
+
+function printSummary(summary) {
+  console.log(`  created     ${pc.green(summary.created)}`);
+  console.log(`  skipped     ${pc.yellow(summary.skipped)}`);
+  console.log(`  backed up   ${pc.cyan(summary.backedUp)}`);
+  console.log(`  overwritten ${pc.cyan(summary.overwritten)}`);
+  console.log(`  conflicts   ${summary.conflicts > 0 ? pc.red(summary.conflicts) : pc.dim(summary.conflicts)}`);
+  console.log(`  directories ${pc.dim(summary.mkdir)}`);
+  console.log('');
+}
+
+function printPlan(plan) {
+  for (const [label, files] of Object.entries(plan)) {
+    if (!files.length) continue;
+    console.log(`  ${label}:`);
+    for (const file of files) {
+      console.log(`    - ${file}`);
+    }
+  }
+}
+
+function printHostPlans(hostPlans = [], hostSummary = [], { summaryOnly = false } = {}) {
+  if (!hostPlans?.length) return;
+
+  const summariesByHost = new Map((hostSummary || []).map(item => [item.host, item.summary]));
+  console.log(pc.bold('\nHost-global copies:'));
+  for (const hostPlan of hostPlans) {
+    console.log(`  ${hostPlan.host}   ${pc.cyan(hostPlan.root)}`);
+    const summary = summariesByHost.get(hostPlan.host);
+    if (summary) printSummary(summary);
+    if (!summaryOnly) printPlan(hostPlan.plan);
+  }
+}
+
+function printWarnings(result) {
+  if (!result.warnings.length) return;
+
+  console.log(pc.yellow('\nWarning(s):'));
+  for (const warning of result.warnings) {
+    console.log(pc.yellow(`  - ${warning}`));
+  }
+}
+
 function printJsonResult(result) {
   // Remove `created` array from output — it is already in the plan, avoid duplication
-  const { created, ...rest } = result;
-  console.log(JSON.stringify(rest, null, 2));
-  if (!result.success) {
-    process.exit(1);
+  const { created, globalCreated, hostCreated, ...rest } = result;
+  console.log(JSON.stringify(rest, null, 2));
+  if (!result.success) {
+    process.exit(1);
   }
 }
 
@@ -641,8 +845,8 @@ function scanTarget(targetDir) {
   const hasClaude = isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md'));
   const hasAgents = isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md'));
   const hasAgentSkills = isDirectory && fs.existsSync(path.join(resolvedDir, '.agents'));
-  const hasCodex = isDirectory && fs.existsSync(path.join(resolvedDir, '.codex'));
-  const hasOpencode = isDirectory && (fs.existsSync(path.join(resolvedDir, '.opencode')) || fs.existsSync(path.join(resolvedDir, 'opencode.json')));
+  const hasCodex = isDirectory && fs.existsSync(path.join(resolvedDir, '.codex'));
+  const hasOpencode = isDirectory && (fs.existsSync(path.join(resolvedDir, '.opencode')) || fs.existsSync(path.join(resolvedDir, 'opencode.json')));
   const hasDocs = isDirectory && fs.existsSync(path.join(resolvedDir, 'docs'));
   const hasReadme = isDirectory && fs.existsSync(path.join(resolvedDir, 'README.md'));
   const hasPackageJson = isDirectory && fs.existsSync(path.join(resolvedDir, 'package.json'));
@@ -660,8 +864,8 @@ function scanTarget(targetDir) {
     hasClaude,
     hasAgents,
     hasAgentSkills,
-    hasCodex,
-    hasOpencode,
+    hasCodex,
+    hasOpencode,
     hasDocs,
     hasReadme,
     hasPackageJson,
@@ -689,8 +893,8 @@ function createJsonScan(scan) {
       hasClaude: scan.hasClaude,
       hasAgents: scan.hasAgents,
       hasAgentSkills: scan.hasAgentSkills,
-      hasCodex: scan.hasCodex,
-      hasOpencode: scan.hasOpencode,
+      hasCodex: scan.hasCodex,
+      hasOpencode: scan.hasOpencode,
       hasDocs: scan.hasDocs,
       hasReadme: scan.hasReadme,
       hasPackageJson: scan.hasPackageJson,
@@ -703,12 +907,44 @@ function createJsonScan(scan) {
 }
 
 function createAgentGuidance(result, { projectName, targetDir, options, scan }) {
-  const attentionFiles = [...new Set([
+  const projectAttentionFiles = [...new Set([
     ...(result.plan?.conflict || []),
     ...(result.plan?.skip || []),
   ])].sort();
-  const aiMergeRequired = attentionFiles.map(file => createFileGuidance(file));
-  const hasBlockingConflicts = (result.plan?.conflict || []).length > 0;
+  const globalAttentionFiles = [...new Set([
+    ...(result.globalPlan?.conflict || []),
+    ...(result.globalPlan?.skip || []),
+  ])].sort();
+  const hostAttentionFiles = (result.hostPlans || []).flatMap(hostPlan => (
+    [...new Set([
+      ...(hostPlan.plan?.conflict || []),
+      ...(hostPlan.plan?.skip || []),
+    ])].sort().map(file => ({ host: hostPlan.host, root: hostPlan.root, file }))
+  ));
+  const aiMergeRequired = [
+    ...projectAttentionFiles.map(file => createFileGuidance(file)),
+    ...globalAttentionFiles.map(file => {
+      const guidance = createFileGuidance(file);
+      return {
+        ...guidance,
+        file: `global:${guidance.file}`,
+        scope: 'global-runtime',
+        reason: `Global runtime file in ${result.globalDir || 'the selected global directory'} needs review. ${guidance.reason}`,
+      };
+    }),
+    ...hostAttentionFiles.map(({ host, root, file }) => {
+      const guidance = createFileGuidance(file);
+      return {
+        ...guidance,
+        file: `host:${host}:${guidance.file}`,
+        scope: `host-global:${host}`,
+        reason: `Host-global ${host} file in ${root} needs review. ${guidance.reason}`,
+      };
+    }),
+  ];
+  const hasBlockingConflicts = (result.plan?.conflict || []).length > 0
+    || (result.globalPlan?.conflict || []).length > 0
+    || (result.hostPlans || []).some(hostPlan => (hostPlan.plan?.conflict || []).length > 0);
   const safeMergeCommand = commandFor(projectName, targetDir, {
     ...options,
     dryRun: false,
@@ -769,6 +1005,14 @@ function createAgentGuidance(result, { projectName, targetDir, options, scan })
       mkdir: result.plan?.mkdir?.length || 0,
       backup: result.plan?.backup?.length || 0,
       overwrite: result.plan?.overwrite?.length || 0,
+      globalCreate: result.globalPlan?.create?.length || 0,
+      globalMkdir: result.globalPlan?.mkdir?.length || 0,
+      globalBackup: result.globalPlan?.backup?.length || 0,
+      globalOverwrite: result.globalPlan?.overwrite?.length || 0,
+      hostCreate: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.create?.length || 0), 0),
+      hostMkdir: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.mkdir?.length || 0), 0),
+      hostBackup: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.backup?.length || 0), 0),
+      hostOverwrite: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.overwrite?.length || 0), 0),
     },
     aiMergeRequired,
     next,
@@ -839,6 +1083,9 @@ function commandFor(projectName, targetDir, options) {
   if (options.withoutOptions?.length) args.push('--without', options.withoutOptions.join(','));
   if (options.externalOptions?.length) args.push('--recommend', options.externalOptions.join(','));
   if (options.preset) args.push('--preset', options.preset);
+  if (options.installScope && options.installScope !== 'project') args.push('--install-scope', options.installScope);
+  if (options.globalDir) args.push('--global-dir', options.globalDir);
+  if (options.hostGlobalDir) args.push('--host-global-dir', options.hostGlobalDir);
   if (options.json) args.push('--json');
 
   return args.map(shellQuoteArg).join(' ');
@@ -864,7 +1111,7 @@ function printScan(scan) {
   if (scan.hasClaude) console.log(`  CLAUDE.md   ${pc.yellow('exists')}`);
   if (scan.hasAgents) console.log(`  AGENTS.md   ${pc.yellow('exists')}`);
   if (scan.hasAgentSkills) console.log(`  .agents/    ${pc.yellow('exists')}`);
-  if (scan.hasCodex) console.log(`  .codex/     ${pc.yellow('exists')}`);
-  if (scan.hasOpencode) console.log(`  opencode     ${pc.yellow('exists')}  ${pc.dim('(.opencode/ or opencode.json)')}`);
+  if (scan.hasCodex) console.log(`  .codex/     ${pc.yellow('exists')}`);
+  if (scan.hasOpencode) console.log(`  opencode     ${pc.yellow('exists')}  ${pc.dim('(.opencode/ or opencode.json)')}`);
   if (scan.hasDocs) console.log(`  docs/       ${pc.dim('project-owned; Harness stays in Harness/')}`);
 }