@stackwright-pro/raft 1.0.0-alpha.12 → 1.0.0-alpha.120

package/dist/index.js

@@ -1,44 +1,78 @@
 #!/usr/bin/env node
 "use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 
 // src/index.ts
-var import_fs2 = require("fs");
-var import_path2 = require("path");
-var import_child_process2 = require("child_process");
+var import_fs3 = require("fs");
+var import_path3 = require("path");
+var import_child_process3 = require("child_process");
 var import_integrity = require("@stackwright-pro/mcp/integrity");
+var import_type_schemas = require("@stackwright-pro/mcp/type-schemas");
 
 // src/lib.ts
 var import_child_process = require("child_process");
 var import_fs = require("fs");
 var import_path = require("path");
 var import_os = require("os");
+var CODE_PUPPY_ENV_ALLOWLIST = /* @__PURE__ */ new Set([
+  // Shell / execution environment
+  "PATH",
+  "HOME",
+  "USER",
+  "USERNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  // Terminal
+  "TERM",
+  "COLORTERM",
+  "COLUMNS",
+  "LINES",
+  "NO_COLOR",
+  "FORCE_COLOR",
+  // Language / locale
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "LC_MESSAGES",
+  // Network proxy — needed for outbound LLM API calls behind corporate proxies
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  // LLM API keys — the only credentials code-puppy should have
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_BASE_URL",
+  "OPENAI_API_KEY",
+  // Node runtime
+  "NODE_ENV",
+  // Stackwright-specific
+  "STACKWRIGHT_PROJECT_ROOT",
+  "STACKWRIGHT_SKIP_PREFLIGHT",
+  "STACKWRIGHT_CODE_PUPPY_PATH",
+  // Telemetry vars (swp-bhw1): NDJSON path is force-injected by the launcher (see index.ts),
+  // but listing here allows user override via shell env. DISABLED/DEBUG are opt-in toggles.
+  "STACKWRIGHT_TELEMETRY_NDJSON",
+  "STACKWRIGHT_TELEMETRY_DISABLED",
+  "STACKWRIGHT_TELEMETRY_DEBUG"
+]);
+var CODE_PUPPY_ENV_PREFIXES = ["PYTHON", "LC_"];
+var MIN_SUPPORTED_CODE_PUPPY_VERSION = "0.0.575";
 function parseArgs(argv) {
   const args = {
     projectRoot: process.cwd(),
     verbose: false,
-    help: false
+    help: false,
+    passEnvKeys: [],
+    nonInteractive: false,
+    devOnly: false,
+    useCasePath: null,
+    skipQa: false,
+    qaOnly: false,
+    qaDevServerTimeoutMs: 6e4,
+    parallelPhases: false
   };
   const raw = argv.slice(2);
   for (let i = 0; i < raw.length; i++) {
@@ -54,7 +88,36 @@ function parseArgs(argv) {
       case "-h":
         args.help = true;
         break;
+      case "--pass-env":
+        args.passEnvKeys.push(raw[++i] ?? die("--pass-env requires a KEY argument"));
+        break;
+      case "--non-interactive":
+        args.nonInteractive = true;
+        break;
+      case "--dev-only":
+        args.devOnly = true;
+        break;
+      case "--use-case":
+        args.useCasePath = raw[++i] ?? die("--use-case requires a file path argument");
+        break;
+      case "--skip-qa":
+        args.skipQa = true;
+        break;
+      case "--qa-only":
+        args.qaOnly = true;
+        break;
+      case "--parallel-phases":
+        args.parallelPhases = true;
+        break;
       default:
+        if (token.startsWith("--qa-dev-server-timeout-ms=")) {
+          const val = parseInt(token.split("=")[1] ?? "", 10);
+          if (isNaN(val) || val <= 0) {
+            die("--qa-dev-server-timeout-ms requires a positive integer (ms)");
+          }
+          args.qaDevServerTimeoutMs = val;
+          break;
+        }
         die(`Unknown option: ${token}
 Run with --help for usage.`);
     }
@@ -69,9 +132,17 @@ function printHelp() {
 Usage: launch-raft [options]
 
 Options:
-  --project-root <path>   Project root directory (default: cwd)
-  --verbose               Enable verbose logging
-  --help, -h              Show this help
+  --project-root <path>             Project root directory (default: cwd)
+  --verbose                         Enable verbose logging
+  --pass-env <KEY>                  Forward an additional env var to code-puppy (repeatable)
+  --non-interactive                 Skip all TUI prompts, use sane defaults for questions
+  --dev-only                        Mock auth only \u2014 roles derived from use case, no real providers
+  --use-case <file>                 Seed "what to build" from a file (plain text or markdown)
+  --skip-qa                         Skip the visual QA gate (useful for CI or fast iterations)
+  --qa-only                         Skip the otter pipeline; spawn dev server and run QA directly
+  --qa-dev-server-timeout-ms=<n>   Dev server startup timeout in ms for QA gate (default: 60000)
+  --parallel-phases                 Enable parallel specialist invocation within dependency waves (~40% wall-time reduction). Default: off (serial).
+  --help, -h                        Show this help
 
 Prerequisites:
   pip install stackwright-puppy   # provides raft-puppy + code-puppy alias
@@ -91,6 +162,29 @@ function verbose(message, isVerbose) {
     console.log(`   ${message}`);
   }
 }
+function buildCodePuppyEnv(extraVars = {}, passEnvKeys = []) {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === void 0) continue;
+    const allowed = CODE_PUPPY_ENV_ALLOWLIST.has(key) || CODE_PUPPY_ENV_PREFIXES.some((prefix) => key.startsWith(prefix)) || passEnvKeys.includes(key);
+    if (allowed) {
+      env[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(extraVars)) {
+    env[key] = value;
+  }
+  return env;
+}
+function buildLauncherEnvOverrides(projectRoot) {
+  return {
+    STACKWRIGHT_PROJECT_ROOT: projectRoot,
+    // swp-bhw1: route raft-puppy telemetry to a SEPARATE file from Pro telemetry.
+    // Two-file separation paves the way for the eventual message-bus architecture
+    // (distributed deployments, restart, replay). User can override via shell env.
+    STACKWRIGHT_TELEMETRY_NDJSON: (0, import_path.join)(projectRoot, ".stackwright", "raft-puppy-events.ndjson")
+  };
+}
 var LOCK_FILE = ".stackwright/.lock";
 function acquireLock(projectRoot) {
   const lockPath = (0, import_path.join)(projectRoot, LOCK_FILE);
@@ -137,6 +231,26 @@ function releaseLock(projectRoot) {
   } catch {
   }
 }
+function migrateWorkspaceDir(projectRoot) {
+  const oldDir = (0, import_path.join)(projectRoot, ".code-puppy");
+  const newDir = (0, import_path.join)(projectRoot, ".code_puppy");
+  const oldExists = (0, import_fs.existsSync)(oldDir);
+  const newExists = (0, import_fs.existsSync)(newDir);
+  if (!oldExists) return;
+  if ((0, import_fs.lstatSync)(oldDir).isSymbolicLink()) {
+    die(".code-puppy/ is a symlink \u2014 refusing to migrate. Check for tampering.");
+  }
+  if (newExists && (0, import_fs.lstatSync)(newDir).isSymbolicLink()) {
+    die(".code_puppy/ is a symlink \u2014 refusing to migrate. Check for tampering.");
+  }
+  if (!newExists) {
+    (0, import_fs.renameSync)(oldDir, newDir);
+    log("Migrated .code-puppy/ \u2192 .code_puppy/ (underscore convention)");
+  } else {
+    (0, import_fs.rmSync)(oldDir, { recursive: true });
+    log("Removed stale .code-puppy/ (underscore version already exists)");
+  }
+}
 function writeInitContext(projectRoot) {
   if (!acquireLock(projectRoot)) {
     let existingPid = "unknown";
@@ -144,7 +258,8 @@ function writeInitContext(projectRoot) {
       const lockPath = (0, import_path.join)(projectRoot, LOCK_FILE);
       if ((0, import_fs.existsSync)(lockPath)) {
         const lockData = JSON.parse((0, import_fs.readFileSync)(lockPath, "utf8"));
-        existingPid = lockData["pid"] ?? "unknown";
+        const rawPid = lockData["pid"];
+        existingPid = typeof rawPid === "string" || typeof rawPid === "number" ? rawPid : "unknown";
       }
     } catch {
     }
@@ -232,18 +347,42 @@ process.on("SIGTERM", () => {
   }
   process.exit(0);
 });
-function findCodePuppy() {
+function getTrustedBinaryDirs() {
+  return [
+    (0, import_path.join)((0, import_os.homedir)(), ".local", "bin"),
+    // pip user install, uvx, pipx (Linux/macOS)
+    "/opt/homebrew/bin",
+    //              brew Apple Silicon
+    "/usr/local/bin",
+    //                 brew Intel, pip system install
+    "/usr/bin"
+    //                       system package managers (apt, dnf)
+  ];
+}
+function findCodePuppy(trustedDirsOverride) {
   let candidate = null;
   const envPath = process.env["STACKWRIGHT_CODE_PUPPY_PATH"];
   if (envPath) {
     candidate = envPath;
   }
+  if (!candidate) {
+    const trustedDirs = trustedDirsOverride ?? getTrustedBinaryDirs();
+    outer: for (const bin of ["raft-puppy", "code-puppy"]) {
+      for (const dir of trustedDirs) {
+        const p = (0, import_path.join)(dir, bin);
+        if ((0, import_fs.existsSync)(p)) {
+          candidate = p;
+          break outer;
+        }
+      }
+    }
+  }
   if (!candidate) {
     for (const bin of ["raft-puppy", "code-puppy"]) {
-      try {
-        candidate = (0, import_child_process.execSync)(`which ${bin}`, { encoding: "utf-8" }).trim();
+      const whichResult = (0, import_child_process.spawnSync)("which", [bin], { encoding: "utf-8" });
+      if (whichResult.status === 0 && whichResult.stdout) {
+        candidate = whichResult.stdout.trim();
         if (candidate) break;
-      } catch {
       }
     }
   }
@@ -267,39 +406,116 @@ function findCodePuppy() {
   if (!(0, import_fs.existsSync)(realBinary)) {
     die(`raft-puppy symlink at ${resolved} points to a missing file: ${realBinary}`);
   }
-  const stat = (0, import_fs.lstatSync)(realBinary);
+  let fd;
+  try {
+    fd = (0, import_fs.openSync)(realBinary, "r");
+  } catch (err) {
+    die(
+      `Cannot open raft-puppy at ${realBinary} for validation: ${String(err)}. Try reinstalling stackwright-puppy or set STACKWRIGHT_CODE_PUPPY_PATH.`
+    );
+  }
+  const stat = (0, import_fs.fstatSync)(fd);
   if (stat.mode & 18) {
+    (0, import_fs.closeSync)(fd);
     die(
       `raft-puppy at ${realBinary} is group- or world-writable (mode: ${(stat.mode & 511).toString(8)}) \u2014 refusing to exec.`
     );
   }
   if (stat.mode & 3072) {
+    (0, import_fs.closeSync)(fd);
     die(`raft-puppy at ${realBinary} has setuid/setgid bits \u2014 refusing to exec.`);
   }
-  return realBinary;
+  return { path: realBinary, fd };
+}
+function parseSemver(version) {
+  const parts = version.split("-")[0].split(".").map(Number);
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+function semverGte(a, b) {
+  const [aMaj, aMin, aPatch] = parseSemver(a);
+  const [bMaj, bMin, bPatch] = parseSemver(b);
+  if (aMaj !== bMaj) return aMaj > bMaj;
+  if (aMin !== bMin) return aMin > bMin;
+  return aPatch >= bPatch;
+}
+function validateBinaryVersion(binaryPath) {
+  if (process.env["STACKWRIGHT_SKIP_PREFLIGHT"] === "true") {
+    log("Pre-flight checks skipped via STACKWRIGHT_SKIP_PREFLIGHT");
+    return;
+  }
+  const versionStartTime = Date.now();
+  const versionResult = (0, import_child_process.spawnSync)(binaryPath, ["--version"], {
+    encoding: "utf-8",
+    // 15s: uv-installed Python tools cold-start (venv activation + interpreter
+    // startup) can take 5-10s on first invocation; subsequent runs are ms.
+    timeout: 15e3,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const versionElapsed = Date.now() - versionStartTime;
+  if (versionResult.error !== void 0 || versionResult.status !== 0) {
+    const errorDetail = versionResult.error ? `${versionResult.error.code ?? "unknown"}: ${versionResult.error.message}` : `exit status ${String(versionResult.status)}`;
+    const stdoutSnip = (versionResult.stdout ?? "").trim() || "<empty>";
+    const stderrSnip = (versionResult.stderr ?? "").trim() || "<empty>";
+    die(
+      `Could not determine raft-puppy / code-puppy version.
+  Binary:   ${binaryPath}
+  Failure:  ${errorDetail}
+  Elapsed:  ${String(versionElapsed)}ms (timeout: 15000ms)
+  Stdout:   ${stdoutSnip}
+  Stderr:   ${stderrSnip}
+  Required: ${MIN_SUPPORTED_CODE_PUPPY_VERSION}
+
+  Run: pip install --upgrade stackwright-puppy
+  Or:  pip install --upgrade code-puppy
+
+  If the binary works manually but fails here, set
+  STACKWRIGHT_SKIP_PREFLIGHT=true to bypass this check.`
+    );
+  }
+  const versionStdout = versionResult.stdout.trim();
+  const versionStderr = versionResult.stderr.trim();
+  const versionOutput = versionStdout || versionStderr;
+  const match = /(\d+\.\d+\.\d+(?:-[^\s]+)?)/.exec(versionOutput);
+  if (!match || !match[1]) {
+    die(
+      `Could not parse version from raft-puppy / code-puppy output.
+  Binary:   ${binaryPath}
+  Stdout:   ${JSON.stringify(versionStdout) || "<empty>"}
+  Stderr:   ${JSON.stringify(versionStderr) || "<empty>"}
+  Required: ${MIN_SUPPORTED_CODE_PUPPY_VERSION}
+
+  Run: pip install --upgrade stackwright-puppy
+  Or:  pip install --upgrade code-puppy`
+    );
+  }
+  const installedVersion = match[1];
+  const isDevBuild = installedVersion === "0.0.0" || /^0\.0\.0-.+$/.test(installedVersion);
+  if (isDevBuild) {
+    console.warn(
+      `\u26A0\uFE0F  Dev build detected (${installedVersion}) \u2014 skipping minimum version check.
+   Minimum required for production: ${MIN_SUPPORTED_CODE_PUPPY_VERSION}
+   To suppress this warning in CI: set STACKWRIGHT_SKIP_PREFLIGHT=true`
+    );
+    return;
+  }
+  if (!semverGte(installedVersion, MIN_SUPPORTED_CODE_PUPPY_VERSION)) {
+    die(
+      `raft-puppy / code-puppy ${installedVersion} is below the minimum required version.
+  Installed: ${installedVersion}
+  Minimum required: ${MIN_SUPPORTED_CODE_PUPPY_VERSION}
+
+  Run: pip install --upgrade stackwright-puppy
+  Or:  pip install --upgrade code-puppy`
+    );
+  }
 }
 function ensureMcpConfig(projectRoot) {
-  const xdgConfigHome = process.env["XDG_CONFIG_HOME"];
-  const configDir = xdgConfigHome ? (0, import_path.join)(xdgConfigHome, "code_puppy") : (0, import_path.join)((0, import_os.homedir)(), ".code_puppy");
-  const configPath = (0, import_path.join)(configDir, "mcp_servers.json");
+  const workspaceDir = (0, import_path.join)(projectRoot, ".code_puppy");
+  const configPath = (0, import_path.join)(workspaceDir, "mcp_servers.json");
   if ((0, import_fs.existsSync)(configPath) && (0, import_fs.lstatSync)(configPath).isSymbolicLink()) {
-    die("`~/.code_puppy/mcp_servers.json` is a symlink \u2014 refusing to write. Check for tampering.");
-  }
-  (0, import_fs.mkdirSync)(configDir, { recursive: true });
-  const localServerPath = (0, import_path.join)(
-    projectRoot,
-    "node_modules",
-    "@stackwright-pro",
-    "mcp",
-    "dist",
-    "server.js"
-  );
-  let raftOwnServerPath = null;
-  try {
-    raftOwnServerPath = require.resolve("@stackwright-pro/mcp");
-  } catch {
+    die(".code_puppy/mcp_servers.json is a symlink \u2014 refusing to write. Check for tampering.");
   }
-  const serverConfig = (0, import_fs.existsSync)(localServerPath) ? { type: "stdio", command: "node", args: [localServerPath] } : raftOwnServerPath !== null ? { type: "stdio", command: "node", args: [raftOwnServerPath] } : { type: "stdio", command: "npx", args: ["--yes", "@stackwright-pro/mcp@latest"] };
+  (0, import_fs.mkdirSync)(workspaceDir, { recursive: true });
   let existing = {};
   if ((0, import_fs.existsSync)(configPath)) {
     try {
@@ -308,28 +524,59 @@ function ensureMcpConfig(projectRoot) {
     } catch {
     }
   }
+  const shimName = (0, import_os.platform)() === "win32" ? "stackwright-pro-mcp.cmd" : "stackwright-pro-mcp";
+  const shimPath = (0, import_path.join)(projectRoot, "node_modules", ".bin", shimName);
+  if (!(0, import_fs.existsSync)(shimPath)) {
+    die(
+      `MCP server shim not found: ${shimPath}
+  Run \`pnpm install\` (or your package manager equivalent) before \`raft\`.`
+    );
+  }
+  const serverConfig = {
+    type: "stdio",
+    command: shimPath,
+    args: [],
+    enabled: true,
+    cwd: projectRoot
+  };
   const merged = {
     ...existing,
     mcp_servers: {
       ...existing.mcp_servers ?? {},
-      "stackwright-pro": serverConfig
+      "stackwright-pro-mcp": serverConfig
     }
   };
-  if (merged.mcp_servers && "stackwright" in merged.mcp_servers) {
-    const stale = merged.mcp_servers["stackwright"];
-    const args = stale?.["args"];
-    const isPlaceholder = args?.includes("/path/to/dir") || stale?.["command"] === "npx" && args?.some((a) => String(a).includes("server-filesystem"));
-    if (isPlaceholder) {
-      delete merged.mcp_servers["stackwright"];
-      log(
-        "Removed stale `stackwright` placeholder from mcp_servers.json (was: @modelcontextprotocol/server-filesystem /path/to/dir \u2014 not a real server)"
-      );
+  const tmpPath = `${configPath}.tmp`;
+  (0, import_fs.writeFileSync)(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+  (0, import_fs.renameSync)(tmpPath, configPath);
+  log("MCP server registered \u2192 .code_puppy/mcp_servers.json");
+}
+function ensureWorkspaceConfig(projectRoot) {
+  const workspaceDir = (0, import_path.join)(projectRoot, ".code_puppy");
+  const configPath = (0, import_path.join)(workspaceDir, "config.json");
+  if ((0, import_fs.existsSync)(workspaceDir) && (0, import_fs.lstatSync)(workspaceDir).isSymbolicLink()) {
+    die(".code_puppy/ is a symlink \u2014 refusing to write. Check for tampering.");
+  }
+  (0, import_fs.mkdirSync)(workspaceDir, { recursive: true });
+  if ((0, import_fs.existsSync)(configPath) && (0, import_fs.lstatSync)(configPath).isSymbolicLink()) {
+    die(".code_puppy/config.json is a symlink \u2014 refusing to write. Check for tampering.");
+  }
+  let existing = {};
+  if ((0, import_fs.existsSync)(configPath)) {
+    try {
+      existing = JSON.parse((0, import_fs.readFileSync)(configPath, "utf-8"));
+    } catch {
     }
   }
+  const merged = {
+    ...existing,
+    $schema: "https://stackwright.dev/schemas/workspace-config/v2.json",
+    profile: "strict-local"
+  };
   const tmpPath = `${configPath}.tmp`;
   (0, import_fs.writeFileSync)(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
   (0, import_fs.renameSync)(tmpPath, configPath);
-  log("MCP server registered \u2192 ~/.code_puppy/mcp_servers.json");
+  log("Workspace config written \u2192 .code_puppy/config.json (profile: strict-local)");
 }
 function printResumeStatus(projectRoot) {
   const pipelineStatePath = (0, import_path.join)(projectRoot, ".stackwright", "pipeline-state.json");
@@ -366,6 +613,17 @@ function printResumeStatus(projectRoot) {
   } catch {
   }
 }
+function isPipelineResumable(projectRoot) {
+  const pipelineStatePath = (0, import_path.join)(projectRoot, ".stackwright", "pipeline-state.json");
+  try {
+    const raw = (0, import_fs.readFileSync)(pipelineStatePath, "utf-8");
+    const state = JSON.parse(raw);
+    const status = state["status"];
+    return status === "questions" || status === "execution";
+  } catch {
+    return false;
+  }
+}
 function resolveOtterDir(projectRoot) {
   const candidates = [
     (0, import_path.join)(projectRoot, "node_modules", "@stackwright-pro", "otters", "src"),
@@ -378,25 +636,324 @@ function resolveOtterDir(projectRoot) {
   }
   return null;
 }
+function syncAgents(projectRoot, isVerbose = false) {
+  const agentsDir = (0, import_path.join)(projectRoot, ".code_puppy", "agents");
+  const otterDir = resolveOtterDir(projectRoot);
+  if (!otterDir) {
+    verbose("No otters directory found \u2014 skipping agent sync", isVerbose);
+    return;
+  }
+  if ((0, import_fs.existsSync)(agentsDir) && (0, import_fs.lstatSync)(agentsDir).isSymbolicLink()) {
+    die(".code_puppy/agents is a symlink \u2014 refusing to write. Check for tampering.");
+  }
+  (0, import_fs.mkdirSync)(agentsDir, { recursive: true });
+  let synced = 0;
+  let skipped = 0;
+  try {
+    const files = (0, import_fs.readdirSync)(otterDir);
+    for (const file of files) {
+      if (!file.endsWith("-otter.json")) continue;
+      const src = (0, import_path.join)(otterDir, file);
+      const dest = (0, import_path.join)(agentsDir, file);
+      if ((0, import_fs.existsSync)(dest) && (0, import_fs.lstatSync)(dest).isSymbolicLink()) {
+        verbose(`Skipping ${file} \u2014 dest is a symlink`, isVerbose);
+        skipped++;
+        continue;
+      }
+      const tmp = `${dest}.tmp`;
+      const content = (0, import_fs.readFileSync)(src);
+      (0, import_fs.writeFileSync)(tmp, content);
+      (0, import_fs.renameSync)(tmp, dest);
+      verbose(`Synced: ${file}`, isVerbose);
+      synced++;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`\u26A0\uFE0F  Agent sync partial failure: ${msg}`);
+    return;
+  }
+  if (synced > 0) {
+    log(
+      `Agents synced \u2192 .code_puppy/agents/ (${synced} otters${skipped > 0 ? `, ${skipped} skipped` : ""})`
+    );
+  }
+}
+function buildSpawnConfig(platform2, executable, binaryFd) {
+  const PINNED_CHILD_FD = 3;
+  if (platform2 === "linux") {
+    return {
+      spawnTarget: `/proc/self/fd/${PINNED_CHILD_FD}`,
+      stdioConfig: ["inherit", "inherit", "inherit", binaryFd]
+    };
+  }
+  return {
+    spawnTarget: executable,
+    stdioConfig: "inherit"
+  };
+}
+
+// src/dev-server.ts
+var import_child_process2 = require("child_process");
+var import_fs2 = require("fs");
+var import_path2 = require("path");
+var DevServerStartupError = class extends Error {
+  constructor(message, logTail, elapsedMs) {
+    super(message);
+    this.logTail = logTail;
+    this.elapsedMs = elapsedMs;
+    this.name = "DevServerStartupError";
+  }
+};
+function detectPrismConfig(projectRoot, defaultPrismUrl = "http://localhost:4010") {
+  try {
+    const pkgPath = (0, import_path2.join)(projectRoot, "package.json");
+    const raw = (0, import_fs2.readFileSync)(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw);
+    const scripts = pkg["scripts"];
+    const devScript = typeof scripts?.["dev"] === "string" ? scripts["dev"] : "";
+    const hasConcurrently = devScript.includes("concurrently");
+    const hasPrism = /prism/i.test(devScript);
+    return { hasPrism: hasConcurrently && hasPrism, prismUrl: defaultPrismUrl };
+  } catch {
+    return { hasPrism: false, prismUrl: defaultPrismUrl };
+  }
+}
+function tailLog(logPath, maxLines) {
+  try {
+    const content = (0, import_fs2.readFileSync)(logPath, "utf-8");
+    const lines = content.split("\n").filter((l) => l.length > 0);
+    return lines.slice(-maxLines);
+  } catch {
+    return [];
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+async function singleFetch(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await globalThis.fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    return res.status >= 200 && res.status < 300;
+  } catch {
+    clearTimeout(timer);
+    return false;
+  }
+}
+async function pollUntilAllReady(urls, timeoutMs, pollIntervalMs, perRequestTimeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const perReq = Math.min(perRequestTimeoutMs, remaining);
+    const results = await Promise.all(urls.map((url) => singleFetch(url, perReq)));
+    if (results.every(Boolean)) return true;
+    const sleepMs = Math.min(pollIntervalMs, deadline - Date.now());
+    if (sleepMs <= 0) break;
+    await sleep(sleepMs);
+  }
+  return false;
+}
+async function killChildProcess(child, pid) {
+  return new Promise((resolve3) => {
+    let settled = false;
+    const settle = () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(escalateTimer);
+        resolve3();
+      }
+    };
+    child.once("exit", settle);
+    const escalateTimer = setTimeout(() => {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+      }
+      settle();
+    }, 5e3);
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      settle();
+    }
+  });
+}
+async function withDevServer(projectRoot, options, body) {
+  const {
+    timeoutMs = 6e4,
+    baseUrl: baseUrlOpt,
+    prismUrl: prismUrlOpt,
+    detectPrism: shouldDetectPrism = true
+  } = options;
+  const baseUrl = baseUrlOpt ?? "http://localhost:3000";
+  let prismUrl;
+  if (prismUrlOpt !== void 0) {
+    prismUrl = prismUrlOpt;
+  } else if (shouldDetectPrism) {
+    const cfg = detectPrismConfig(projectRoot);
+    prismUrl = cfg.hasPrism ? cfg.prismUrl : void 0;
+  }
+  const stackwrightDir = (0, import_path2.join)(projectRoot, ".stackwright");
+  (0, import_fs2.mkdirSync)(stackwrightDir, { recursive: true });
+  const logPath = (0, import_path2.join)(stackwrightDir, "dev-server.log");
+  const logFd = (0, import_fs2.openSync)(logPath, "w");
+  const readyFilePath = (0, import_path2.join)(stackwrightDir, "dev-server-ready.json");
+  const startedAt = Date.now();
+  let child;
+  let pid;
+  let spawnErr;
+  try {
+    child = (0, import_child_process2.spawn)("pnpm", ["dev"], {
+      cwd: projectRoot,
+      detached: false,
+      stdio: ["ignore", logFd, logFd]
+    });
+    pid = child.pid;
+    child.on("error", (err) => {
+      spawnErr = err;
+    });
+    if (pid === void 0) {
+      throw new DevServerStartupError(
+        "pnpm dev failed to spawn (no PID)",
+        tailLog(logPath, 50),
+        Date.now() - startedAt
+      );
+    }
+    const urlsToProbe = [baseUrl, ...prismUrl ? [prismUrl] : []];
+    const ready = await pollUntilAllReady(urlsToProbe, timeoutMs, 2e3, 1e3);
+    if (!ready) {
+      const elapsedMs = Date.now() - startedAt;
+      const tail = tailLog(logPath, 50);
+      const spawnErrMsg = spawnErr ? ` Spawn error: ${spawnErr.message}.` : "";
+      throw new DevServerStartupError(
+        `Dev server did not become ready within ${timeoutMs}ms.${spawnErrMsg}`,
+        tail,
+        elapsedMs
+      );
+    }
+    const info = {
+      pid,
+      baseUrl,
+      ...prismUrl ? { prismUrl } : {},
+      startedAt,
+      logPath
+    };
+    (0, import_fs2.writeFileSync)(
+      readyFilePath,
+      JSON.stringify({ ...info, readyAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n"
+    );
+    return await body(info);
+  } finally {
+    if (child && pid !== void 0) {
+      await killChildProcess(child, pid);
+    }
+    try {
+      (0, import_fs2.unlinkSync)(readyFilePath);
+    } catch {
+    }
+    try {
+      (0, import_fs2.closeSync)(logFd);
+    } catch {
+    }
+  }
+}
 
 // src/index.ts
-function main() {
+var MAX_RETRIES = 3;
+var BACKOFF_INITIAL_MS = 5e3;
+var BACKOFF_MAX_MS = 6e4;
+function backoffMs(attempt) {
+  return Math.min(BACKOFF_INITIAL_MS * Math.pow(2, attempt), BACKOFF_MAX_MS);
+}
+async function main() {
   const args = parseArgs(process.argv);
   if (args.help) {
     printHelp();
     process.exit(0);
   }
-  const projectRoot = (0, import_path2.resolve)(args.projectRoot);
-  if (!(0, import_fs2.existsSync)(projectRoot)) {
+  const projectRoot = (0, import_path3.resolve)(args.projectRoot);
+  if (!(0, import_fs3.existsSync)(projectRoot)) {
     die(`Project root does not exist: ${projectRoot}`);
   }
-  if (!(0, import_fs2.existsSync)((0, import_path2.join)(projectRoot, "package.json"))) {
+  if (!(0, import_fs3.existsSync)((0, import_path3.join)(projectRoot, "package.json"))) {
     die("No package.json found. Run npx @stackwright-pro/launch-stackwright-pro first.");
   }
   log("Launching Pro Otter Raft...");
   writeInitContext(projectRoot);
   verbose("Init context written", args.verbose);
+  try {
+    const stackwrightDir = (0, import_path3.join)(projectRoot, ".stackwright");
+    (0, import_fs3.mkdirSync)(stackwrightDir, { recursive: true });
+    const schemaSummary = (0, import_type_schemas.buildTypeSchemaSummary)();
+    (0, import_fs3.writeFileSync)(
+      (0, import_path3.join)(stackwrightDir, "type-schemas.json"),
+      JSON.stringify(schemaSummary, null, 2) + "\n"
+    );
+    verbose("Type schemas sink written", args.verbose);
+  } catch (err) {
+    console.warn("\u26A0\uFE0F  Could not write type-schemas.json:", String(err));
+  }
+  {
+    const stackwrightDir = (0, import_path3.join)(projectRoot, ".stackwright");
+    const initContextPath = (0, import_path3.join)(stackwrightDir, "init-context.json");
+    const initRaw = (0, import_fs3.readFileSync)(initContextPath, "utf-8");
+    const initCtx = JSON.parse(initRaw);
+    if (args.nonInteractive) initCtx["nonInteractive"] = true;
+    if (args.devOnly) initCtx["devOnly"] = true;
+    if (args.parallelPhases) initCtx["parallelPhases"] = true;
+    initCtx["skipQa"] = args.skipQa;
+    initCtx["qaOnly"] = args.qaOnly;
+    initCtx["devServer"] = {
+      managed: true,
+      baseUrl: "http://localhost:3000",
+      timeoutMs: args.qaDevServerTimeoutMs
+    };
+    (0, import_fs3.writeFileSync)(initContextPath, JSON.stringify(initCtx, null, 2) + "\n", "utf-8");
+    verbose("Raft flags written to init-context", args.verbose);
+  }
+  {
+    const buildContextPath = (0, import_path3.join)(projectRoot, ".stackwright", "build-context.json");
+    const MAX_USE_CASE_BYTES = 1 * 1024 * 1024;
+    const WARN_USE_CASE_BYTES = 200 * 1024;
+    if (args.useCasePath) {
+      const resolvedPath = (0, import_path3.resolve)(args.useCasePath);
+      if (!(0, import_fs3.existsSync)(resolvedPath)) {
+        die(`Use-case file not found: ${resolvedPath}`);
+      }
+      const content = (0, import_fs3.readFileSync)(resolvedPath, "utf-8");
+      if (content.length > MAX_USE_CASE_BYTES) {
+        die(
+          `Use-case file exceeds ${(MAX_USE_CASE_BYTES / 1024 / 1024).toFixed(0)}MB (got ${(content.length / 1024).toFixed(0)}KB). Trim the file or split into sections.`
+        );
+      }
+      if (content.length > WARN_USE_CASE_BYTES) {
+        console.warn(
+          `\u26A0\uFE0F  Large use-case file (${(content.length / 1024).toFixed(0)}KB) \u2014 specialist otters will receive the full context via build prompts.`
+        );
+      }
+      const payload = {
+        version: "1.0",
+        savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        buildContext: content
+      };
+      (0, import_fs3.writeFileSync)(buildContextPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+      log(`Build context seeded from ${args.useCasePath}`);
+    } else if (args.nonInteractive && !(0, import_fs3.existsSync)(buildContextPath)) {
+      const payload = {
+        version: "1.0",
+        savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        buildContext: "Build a sample application from the available API specs and data sources with default settings. Use all available endpoints and standard page layouts."
+      };
+      (0, import_fs3.writeFileSync)(buildContextPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+      log("Build context seeded with generic defaults (--non-interactive, no --use-case)");
+    }
+  }
+  migrateWorkspaceDir(projectRoot);
+  ensureWorkspaceConfig(projectRoot);
   ensureMcpConfig(projectRoot);
+  syncAgents(projectRoot, args.verbose);
   const otterDir = resolveOtterDir(projectRoot);
   if (!otterDir) {
     die(
@@ -417,36 +974,107 @@ function main() {
     log(`\u2705 All ${result.verified.length} otters verified`);
   }
   printResumeStatus(projectRoot);
-  const executable = findCodePuppy();
+  const { path: executable, fd: initialFd } = findCodePuppy();
   verbose(`Resolved raft-puppy / code-puppy: ${executable}`, args.verbose);
+  try {
+    (0, import_fs3.closeSync)(initialFd);
+  } catch {
+  }
+  validateBinaryVersion(executable);
+  if (args.qaOnly) {
+    log("--qa-only mode: skipping otter pipeline, spawning dev server for visual QA...");
+    await withDevServer(projectRoot, { timeoutMs: args.qaDevServerTimeoutMs }, async (info) => {
+      log("--qa-only: dev server ready \u2705");
+      log(`  pid:      ${info.pid}`);
+      log(`  baseUrl:  ${info.baseUrl}`);
+      if (info.prismUrl) log(`  prismUrl: ${info.prismUrl}`);
+      log(`  logPath:  ${info.logPath}`);
+      log("\u23F8 QA otter invocation not yet implemented (blocked on swp-wde8 + swp-kjkg)");
+    });
+    process.exit(0);
+  }
   log("Spawning raft-puppy / code-puppy raft session...");
-  const spawnArgs = ["Begin", "--interactive", "--agent", "stackwright-pro-foreman-otter"];
-  verbose(`cmd: ${executable} ${spawnArgs.join(" ")}`, args.verbose);
-  const child = (0, import_child_process2.spawn)(executable, spawnArgs, {
-    stdio: "inherit",
-    cwd: projectRoot,
-    env: {
-      ...process.env,
-      STACKWRIGHT_PROJECT_ROOT: projectRoot
+  let retryCount = 0;
+  let userInterrupted = false;
+  function spawnSession(isResume) {
+    const { path: resolvedBinary, fd: binaryFd } = findCodePuppy();
+    if (process.platform !== "linux") {
+      verbose(
+        `macOS/other: spawning via path (residual TOCTOU \u2014 /proc unavailable). See GH#128 for threat model documentation.`,
+        args.verbose
+      );
     }
-  });
-  const forward = (signal) => {
-    if (child.pid) child.kill(signal);
-  };
-  const onSigint = () => forward("SIGINT");
-  const onSigterm = () => forward("SIGTERM");
-  process.on("SIGINT", onSigint);
-  process.on("SIGTERM", onSigterm);
-  child.on("error", (err) => die(`Failed to spawn raft-puppy / code-puppy: ${err.message}`));
-  child.on("close", (code, signal) => {
-    process.off("SIGINT", onSigint);
-    process.off("SIGTERM", onSigterm);
-    if (signal) {
-      process.kill(process.pid, signal);
-    } else {
-      process.exit(code ?? 1);
+    const prompt = isResume ? "Resume" : "Begin";
+    const spawnArgs = [prompt, "--interactive", "--agent", "stackwright-pro-foreman-otter"];
+    const { spawnTarget, stdioConfig } = buildSpawnConfig(
+      process.platform,
+      resolvedBinary,
+      binaryFd
+    );
+    verbose(
+      `cmd: ${spawnTarget} ${spawnArgs.join(" ")}${spawnTarget !== resolvedBinary ? ` (real: ${resolvedBinary})` : ""}${isResume ? ` [retry ${retryCount}/${MAX_RETRIES}]` : ""}`,
+      args.verbose
+    );
+    const child = (0, import_child_process3.spawn)(spawnTarget, spawnArgs, {
+      stdio: stdioConfig,
+      cwd: projectRoot,
+      env: buildCodePuppyEnv(buildLauncherEnvOverrides(projectRoot), args.passEnvKeys)
+    });
+    try {
+      (0, import_fs3.closeSync)(binaryFd);
+    } catch {
     }
-  });
+    const forward = (signal) => {
+      if (child.pid) child.kill(signal);
+    };
+    const onSigint = () => {
+      userInterrupted = true;
+      forward("SIGINT");
+    };
+    const onSigterm = () => {
+      userInterrupted = true;
+      forward("SIGTERM");
+    };
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    child.on("error", (err) => die(`Failed to spawn raft-puppy / code-puppy: ${err.message}`));
+    child.on("close", (code, signal) => {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      if (code === 0 || userInterrupted) {
+        process.exit(code ?? 0);
+        return;
+      }
+      if (retryCount < MAX_RETRIES && isPipelineResumable(projectRoot)) {
+        retryCount++;
+        const delay = backoffMs(retryCount - 1);
+        log(
+          `\u26A0\uFE0F  Raft session exited unexpectedly (code ${code ?? "?"}). Pipeline is mid-run \u2014 retrying in ${delay / 1e3}s\u2026 (attempt ${retryCount}/${MAX_RETRIES})`
+        );
+        setTimeout(() => spawnSession(true), delay);
+      } else {
+        if (retryCount >= MAX_RETRIES) {
+          log(`\u274C Max retries (${MAX_RETRIES}) reached \u2014 giving up. Check logs above for errors.`);
+        }
+        process.exit(code ?? 1);
+      }
+    });
+  }
+  if (args.skipQa) {
+    log("\u26A0\uFE0F  Visual QA skipped by --skip-qa flag");
+  } else {
+    log(
+      "\u23F8 Visual QA stub \u2014 dev server lifecycle is wired, QA otter invocation lands in swp-wde8/swp-kjkg"
+    );
+  }
+  spawnSession(false);
 }
-main();
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  die(`Unexpected fatal error: ${msg}`);
+});
 //# sourceMappingURL=index.js.map