quadwork 1.0.17 → 1.2.0

package/bin/quadwork.js

@@ -84,50 +84,178 @@ function findAgentChattr(dir) {
 }
 
 /**
- * Clone AgentChattr and set up its venv. Idempotent — safe to re-run.
- * Only removes existing directories that are identifiable as failed AgentChattr clones.
- * Returns the directory path on success, null on failure.
+ * Clone AgentChattr and set up its venv. Idempotent — safe to re-run on
+ * the same path, and safe to call repeatedly with different paths in
+ * the same process. Designed to support per-project clones (#181).
+ *
+ * Behavior on re-run:
+ *   - Fully-installed path → no-op (skips clone, skips venv create, skips pip)
+ *   - Missing run.py        → clones (only after refusing to overwrite
+ *                             unrelated content; see safety rules below)
+ *   - Missing venv          → creates venv and reinstalls requirements
+ *
+ * Safety rules — never accidentally clean up unrelated directories:
+ *   - Empty dir                                  → safe to remove
+ *   - Git repo whose origin contains "agentchattr" → safe to remove
+ *   - Anything else                              → refuse, return null
+ *
+ * On failure, returns null and stores a human-readable reason on
+ * `installAgentChattr.lastError` so callers can surface it without
+ * changing the return shape.
  */
+// Stale-lock thresholds for installAgentChattr().
+// Lock files older than this OR whose owning pid is no longer alive are
+// treated as crashed and reclaimed. Tuned to comfortably exceed the longest
+// step (pip install of agentchattr requirements, ~120s timeout).
+const INSTALL_LOCK_STALE_MS = 10 * 60 * 1000; // 10 min
+const INSTALL_LOCK_WAIT_TOTAL_MS = 30 * 1000;  // wait up to 30s for a peer
+const INSTALL_LOCK_POLL_MS = 500;
+
+function _isPidAlive(pid) {
+  if (!pid || !Number.isFinite(pid)) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === "EPERM"; }
+}
+
+function _readLock(lockFile) {
+  try {
+    const raw = fs.readFileSync(lockFile, "utf-8").trim();
+    const [pidStr, tsStr] = raw.split(":");
+    return { pid: parseInt(pidStr, 10), ts: parseInt(tsStr, 10) || 0 };
+  } catch { return null; }
+}
+
+function _isLockStale(lockFile) {
+  const info = _readLock(lockFile);
+  if (!info) return true; // unreadable → assume stale
+  if (Date.now() - info.ts > INSTALL_LOCK_STALE_MS) return true;
+  if (!_isPidAlive(info.pid)) return true;
+  return false;
+}
+
 function installAgentChattr(dir) {
   dir = dir || getAgentChattrDir();
-  // Clone if not already present
-  if (!fs.existsSync(path.join(dir, "run.py"))) {
+  installAgentChattr.lastError = null;
+  const setError = (msg) => { installAgentChattr.lastError = msg; return null; };
+
+  // --- Per-target lock to prevent concurrent clones from corrupting each
+  // other when two projects (or two web tabs) launch simultaneously. Lock
+  // file lives next to the install dir so it's scoped per-target.
+  const lockFile = `${dir}.install.lock`;
+  try { fs.mkdirSync(path.dirname(lockFile), { recursive: true }); }
+  catch (e) { return setError(`Cannot create parent of ${dir}: ${e.message}`); }
+
+  let acquired = false;
+  const deadline = Date.now() + INSTALL_LOCK_WAIT_TOTAL_MS;
+  while (!acquired) {
+    try {
+      // Atomic create: fails if file already exists, no TOCTOU race.
+      fs.writeFileSync(lockFile, `${process.pid}:${Date.now()}`, { flag: "wx" });
+      acquired = true;
+    } catch (e) {
+      if (e.code !== "EEXIST") return setError(`Cannot create install lock ${lockFile}: ${e.message}`);
+      // Reclaim if the existing lock is stale (crashed pid or too old).
+      // Use rename → unlink instead of unlink directly: rename is atomic,
+      // so only one racing process can move the stale lock aside. The
+      // others see ENOENT and just retry the wx create. Without this,
+      // two processes could both observe the same stale lock, both
+      // unlink it (one of those unlinks would target the *next* lock
+      // freshly acquired by a third process), and both proceed past the
+      // gate concurrently — see review on quadwork#193.
+      if (_isLockStale(lockFile)) {
+        const sideline = `${lockFile}.stale.${process.pid}.${Date.now()}`;
+        try {
+          fs.renameSync(lockFile, sideline);
+          try { fs.unlinkSync(sideline); } catch {}
+        } catch (renameErr) {
+          // ENOENT: another process already reclaimed it. Anything else:
+          // treat as transient and retry — the next iteration will read
+          // whatever is at lockFile now and decide again.
+          if (renameErr.code !== "ENOENT") {
+            return setError(`Cannot reclaim stale lock ${lockFile}: ${renameErr.message}`);
+          }
+        }
+        continue;
+      }
+      // Live peer install in progress. After it finishes, the install
+      // is likely already done — caller will see a fully-installed path
+      // on the next call. While waiting, poll until the lock disappears
+      // or we hit the wait deadline.
+      if (Date.now() >= deadline) {
+        const info = _readLock(lockFile) || { pid: "?", ts: 0 };
+        return setError(`Another install is in progress at ${dir} (pid ${info.pid}); timed out after ${INSTALL_LOCK_WAIT_TOTAL_MS}ms. Re-run after it finishes, or remove ${lockFile} if stale.`);
+      }
+      // Synchronous sleep — installAgentChattr is itself synchronous and
+      // is called from the CLI wizard, where blocking is acceptable.
+      // Use execSync('sleep') instead of a busy-wait so we don't pin a CPU.
+      try { require("child_process").execSync(`sleep ${INSTALL_LOCK_POLL_MS / 1000}`); }
+      catch { /* sleep interrupted; loop will recheck */ }
+    }
+  }
+
+  try {
+    return _installAgentChattrLocked(dir, setError);
+  } finally {
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+function _installAgentChattrLocked(dir, setError) {
+  const runPy = path.join(dir, "run.py");
+  const venvPython = path.join(dir, ".venv", "bin", "python");
+  let venvJustCreated = false;
+
+  // 1. Clone if run.py is missing.
+  if (!fs.existsSync(runPy)) {
     if (fs.existsSync(dir)) {
-      // Directory exists but no run.py — only clean up if positively identified
-      const isEmpty = fs.readdirSync(dir).length === 0;
+      let entries;
+      try { entries = fs.readdirSync(dir); }
+      catch (e) { return setError(`Cannot read ${dir}: ${e.message}`); }
+      const isEmpty = entries.length === 0;
       if (isEmpty) {
-        try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+        try { fs.rmSync(dir, { recursive: true, force: true }); }
+        catch (e) { return setError(`Cannot remove empty dir ${dir}: ${e.message}`); }
       } else if (fs.existsSync(path.join(dir, ".git"))) {
-        // Verify this is actually an AgentChattr repo by checking the remote
+        // Only remove if origin remote positively identifies this as agentchattr.
         const remote = run(`git -C "${dir}" remote get-url origin 2>/dev/null`);
         if (remote && remote.includes("agentchattr")) {
-          try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+          try { fs.rmSync(dir, { recursive: true, force: true }); }
+          catch (e) { return setError(`Cannot remove failed clone at ${dir}: ${e.message}`); }
         } else {
-          // Git repo but not AgentChattr — refuse to overwrite
-          return null;
+          return setError(`Refusing to overwrite ${dir}: contains a non-AgentChattr git repo`);
         }
       } else {
-        // Non-empty, non-git directory — refuse to overwrite
-        return null;
+        return setError(`Refusing to overwrite ${dir}: directory exists with unrelated content`);
       }
     }
-    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    // Ensure parent exists before clone (supports arbitrary nested paths).
+    try { fs.mkdirSync(path.dirname(dir), { recursive: true }); }
+    catch (e) { return setError(`Cannot create parent of ${dir}: ${e.message}`); }
     const cloneResult = run(`git clone "${AGENTCHATTR_REPO}" "${dir}" 2>&1`, { timeout: 60000 });
-    if (cloneResult === null || !fs.existsSync(path.join(dir, "run.py"))) return null;
+    if (cloneResult === null) return setError(`git clone of ${AGENTCHATTR_REPO} into ${dir} failed`);
+    if (!fs.existsSync(runPy)) return setError(`Clone completed but run.py missing at ${dir}`);
   }
-  // Create venv and install deps (always ensure venv is ready)
-  const venvPython = path.join(dir, ".venv", "bin", "python");
+
+  // 2. Create venv if missing.
   if (!fs.existsSync(venvPython)) {
     const venvResult = run(`python3 -m venv "${path.join(dir, ".venv")}" 2>&1`, { timeout: 60000 });
-    if (venvResult === null) return null;
+    if (venvResult === null) return setError(`python3 -m venv failed at ${dir}/.venv (is python3 installed?)`);
+    if (!fs.existsSync(venvPython)) return setError(`venv created but ${venvPython} missing`);
+    venvJustCreated = true;
   }
-  const reqFile = path.join(dir, "requirements.txt");
-  if (fs.existsSync(reqFile)) {
-    const pipResult = run(`"${venvPython}" -m pip install -r "${reqFile}" 2>&1`, { timeout: 120000 });
-    if (pipResult === null) return null;
+
+  // 3. Install requirements only when the venv was just (re)created.
+  //    This makes re-running on a fully-installed path a true no-op.
+  if (venvJustCreated) {
+    const reqFile = path.join(dir, "requirements.txt");
+    if (fs.existsSync(reqFile)) {
+      const pipResult = run(`"${venvPython}" -m pip install -r "${reqFile}" 2>&1`, { timeout: 120000 });
+      if (pipResult === null) return setError(`pip install -r ${reqFile} failed`);
+    }
   }
   return dir;
 }
+installAgentChattr.lastError = null;
 
 /**
  * Get spawn args for launching AgentChattr from its cloned directory.
@@ -725,6 +853,8 @@ async function setupAgents(rl, repo) {
         seedContent = seedContent.replace(/\{\{reviewer_github_user\}\}/g, "");
         seedContent = seedContent.replace(/\{\{reviewer_token_path\}\}/g, "");
       }
+      // Batch 25 / #205: substitute the per-project queue file path.
+      seedContent = seedContent.replace(/\{\{project_name\}\}/g, projectName);
       fs.writeFileSync(seedDst, seedContent);
     }
   }
@@ -801,25 +931,33 @@ function writeAgentChattrConfig(setup, configTomlPath, { skipInstall = false } =
   fs.writeFileSync(configTomlPath, tomlContent);
   ok(`Wrote ${configTomlPath}`);
 
-  // Start AgentChattr if available; optionally skip install attempt
-  const acDir = findAgentChattr();
+  // Phase 2C / #181: clone AgentChattr per-project at
+  // ~/.quadwork/{project_id}/agentchattr/. AgentChattr's run.py loads
+  // ROOT/config.toml, so each project needs its own clone to avoid
+  // multi-instance port conflicts (see master #181). The path is the
+  // same one writeQuadWorkConfig() persists in project.agentchattr_dir.
+  const perProjectDir = path.join(CONFIG_DIR, setup.projectName, "agentchattr");
+  let acDir = findAgentChattr(perProjectDir);
   let acAvailable = !!acDir;
   if (!acAvailable && !skipInstall) {
-    const acSpinner = spinner("Setting up AgentChattr...");
-    const installResult = installAgentChattr();
+    const acSpinner = spinner(`Setting up AgentChattr at ${perProjectDir}...`);
+    const installResult = installAgentChattr(perProjectDir);
     if (installResult) {
       acSpinner.stop(true);
+      acDir = installResult;
       acAvailable = true;
     } else {
       acSpinner.stop(false);
-      warn(`Install manually: git clone ${AGENTCHATTR_REPO} ${DEFAULT_AGENTCHATTR_DIR}`);
+      const reason = installAgentChattr.lastError || "unknown error";
+      warn(`AgentChattr install failed at ${perProjectDir}: ${reason}`);
+      warn(`Install manually: git clone ${AGENTCHATTR_REPO} ${perProjectDir}`);
     }
   }
 
   // Start AgentChattr server (only if installed)
   if (acAvailable) {
     log("Starting AgentChattr server...");
-    const acSpawn = chattrSpawnArgs(findAgentChattr(), ["--config", configTomlPath]);
+    const acSpawn = chattrSpawnArgs(acDir, ["--config", configTomlPath]);
     if (acSpawn) {
       const acProc = spawn(acSpawn.command, acSpawn.spawnArgs, {
         cwd: acSpawn.cwd,
@@ -836,14 +974,14 @@ function writeAgentChattrConfig(setup, configTomlPath, { skipInstall = false } =
         const pidFile = path.join(CONFIG_DIR, `agentchattr-${setup.projectName}.pid`);
         fs.writeFileSync(pidFile, String(acProc.pid));
       } else {
-        warn("Could not start AgentChattr — check logs in " + (findAgentChattr() || DEFAULT_AGENTCHATTR_DIR));
+        warn("Could not start AgentChattr — check logs in " + (acDir || perProjectDir));
       }
     } else {
       warn("AgentChattr run.py not found — skipping auto-start.");
     }
   } else {
     warn("AgentChattr not installed — skipping auto-start.");
-    log(`  → Install: git clone ${AGENTCHATTR_REPO} ${DEFAULT_AGENTCHATTR_DIR}`);
+    log(`  → Install: git clone ${AGENTCHATTR_REPO} ${perProjectDir}`);
   }
 
   return configTomlPath;
@@ -1006,6 +1144,30 @@ bridge_sender = "telegram-bridge"
 
 // ─── Write QuadWork Config ──────────────────────────────────────────────────
 
+/**
+ * Seed ~/.quadwork/{projectName}/OVERNIGHT-QUEUE.md from templates/.
+ * Idempotent — never overwrites an existing file so user and Head
+ * agent edits are preserved across re-runs.
+ */
+function writeOvernightQueueFile(projectName, repo) {
+  const queueDir = path.join(CONFIG_DIR, projectName);
+  const queuePath = path.join(queueDir, "OVERNIGHT-QUEUE.md");
+  if (fs.existsSync(queuePath)) return false;
+  try { fs.mkdirSync(queueDir, { recursive: true }); }
+  catch (e) { warn(`Could not create ${queueDir}: ${e.message}`); return false; }
+  const templatePath = path.join(TEMPLATES_DIR, "OVERNIGHT-QUEUE.md");
+  if (!fs.existsSync(templatePath)) {
+    warn(`OVERNIGHT-QUEUE.md template missing at ${templatePath}`);
+    return false;
+  }
+  let content = fs.readFileSync(templatePath, "utf-8");
+  content = content.replace(/\{\{project_name\}\}/g, projectName || "");
+  content = content.replace(/\{\{repo\}\}/g, repo || "");
+  fs.writeFileSync(queuePath, content);
+  ok(`Wrote ${queuePath}`);
+  return true;
+}
+
 function writeQuadWorkConfig(setup) {
   header("Writing QuadWork Config");
 
@@ -1061,6 +1223,15 @@ function writeQuadWorkConfig(setup) {
   project.agentchattr_token = require("crypto").randomBytes(16).toString("hex");
   project.mcp_http_port = mcp_http;
   project.mcp_sse_port = mcp_sse;
+  // Per-project AgentChattr clone path (Option B / #181). Each project gets
+  // its own clone so AgentChattr's ROOT/config.toml lookup picks up the right
+  // ports — see master ticket #181.
+  project.agentchattr_dir = path.join(os.homedir(), ".quadwork", setup.projectName, "agentchattr");
+
+  // Batch 25 / #204: seed the per-project OVERNIGHT-QUEUE.md at
+  // ~/.quadwork/{id}/OVERNIGHT-QUEUE.md. Idempotent — if the file
+  // already exists, preserve the user's / Head agent's edits.
+  writeOvernightQueueFile(setup.projectName, setup.repo);
 
   // Upsert project
   if (existingIdx >= 0) config.projects[existingIdx] = project;
@@ -1102,33 +1273,29 @@ async function cmdInit() {
     writeConfig(config);
     ok(`Wrote ${CONFIG_PATH}`);
 
-    // Step 3: Start server
+    // Step 3: Start server in the foreground (Batch 25 / #203).
+    //
+    // Previously cmdInit spawned the server detached and exited, which
+    // left users without logs, without a clear stop story, and
+    // inconsistent with `npx quadwork start` (#169). Now we print the
+    // welcome banner first, schedule the browser open, close the
+    // wizard readline, and then require() the server so it runs in
+    // the user's terminal — Ctrl+C stops it cleanly via the SIGINT
+    // handler below (same pattern cmdStart uses).
     header("Step 3: Starting Dashboard");
     const quadworkDir = path.join(__dirname, "..");
     const serverDir = path.join(quadworkDir, "server");
-    let serverPid = null;
-    if (fs.existsSync(path.join(serverDir, "index.js"))) {
-      const server = spawn("node", [serverDir], {
-        stdio: "ignore",
-        detached: true,
-        env: { ...process.env },
-      });
-      server.unref();
-      if (server.pid) {
-        serverPid = server.pid;
-        ok(`Server started (PID: ${serverPid})`);
-        const pidFile = path.join(CONFIG_DIR, "server.pid");
-        if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
-        fs.writeFileSync(pidFile, String(serverPid));
-      }
-    } else {
-      warn("Server not found — run from the quadwork directory");
+    if (!fs.existsSync(path.join(serverDir, "index.js"))) {
+      fail("Server not found. Run from the quadwork directory.");
+      rl.close();
+      process.exit(1);
     }
 
-    // Done — celebratory welcome
     const dashPort = parseInt(port, 10) || 8400;
     const dashboardUrl = `http://127.0.0.1:${dashPort}`;
 
+    // Celebratory welcome (printed BEFORE the server takes over stdout
+    // so it stays visible at the top of the scrollback).
     console.log("");
     console.log(`  ${c.cyan}${c.bold}╔══════════════════════════════════════════════════════════╗${c.reset}`);
     console.log(`  ${c.cyan}${c.bold}║${c.reset}                                                          ${c.cyan}${c.bold}║${c.reset}`);
@@ -1145,12 +1312,8 @@ async function cmdInit() {
     console.log(`  ${c.cyan}${c.bold}║${c.reset}                                                          ${c.cyan}${c.bold}║${c.reset}`);
     console.log(`  ${c.cyan}${c.bold}╚══════════════════════════════════════════════════════════╝${c.reset}`);
     console.log("");
-    if (serverPid) {
-      console.log(`  ${c.green}*${c.reset} Server running at ${c.cyan}${dashboardUrl}${c.reset} ${c.dim}(PID: ${serverPid})${c.reset}`);
-    } else {
-      console.log(`  ${c.yellow}*${c.reset} Server not started — run ${c.dim}npx quadwork start${c.reset} to launch`);
-    }
-    console.log(`  ${c.green}*${c.reset} Config saved to ${c.dim}${CONFIG_PATH}${c.reset}`);
+    console.log(`  ${c.green}*${c.reset} Dashboard: ${c.cyan}${dashboardUrl}${c.reset}`);
+    console.log(`  ${c.green}*${c.reset} Config:    ${c.dim}${CONFIG_PATH}${c.reset}`);
     console.log("");
     console.log(`  ${c.cyan}${c.bold}--- Create Your First Project ---${c.reset}`);
     console.log("");
@@ -1162,19 +1325,40 @@ async function cmdInit() {
     console.log(`    ${c.dim}2.${c.reset} Pick models for each agent`);
     console.log(`    ${c.dim}3.${c.reset} Hit Start — your team takes it from there`);
     console.log("");
-    console.log(`  ${c.dim}Commands:${c.reset}`);
-    console.log(`    ${c.dim}npx --yes quadwork start${c.reset}  — start the dashboard (Ctrl+C to stop)`);
-    console.log("");
-    console.log(`  ${c.green}${c.bold}Happy shipping!${c.reset}`);
+    console.log(`  ${c.green}${c.bold}Happy shipping!${c.reset}  ${c.dim}(Press Ctrl+C to stop.)${c.reset}`);
     console.log("");
 
-    // Open browser
+    // Close the wizard readline before requiring the server, otherwise
+    // stdin stays in raw/line-buffered mode and swallows Ctrl+C.
+    rl.close();
+
+    // Schedule browser open after the server has had a moment to bind.
     const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     setTimeout(() => {
       try { execSync(`${openCmd} ${dashboardUrl}/setup`, { stdio: "ignore" }); } catch {}
     }, 1500);
 
-    rl.close();
+    // Run the server in the foreground. require() starts the express
+    // listener in this process, so cmdInit stays alive until Ctrl+C.
+    // Capture the exports so the SIGINT handler can ask the server
+    // to SIGTERM any AgentChattr children it spawned after init (the
+    // user creates a project in /setup and clicks Start → the
+    // dashboard launches python run.py as a detached child and only
+    // the server knows its pid, via its in-memory `chattrProcesses`
+    // Map).
+    const serverExports = require(path.join(serverDir, "index.js"));
+
+    // Graceful shutdown on Ctrl+C. Kill any dashboard-spawned
+    // AgentChattr children first, then exit so the port is released
+    // and no python is orphaned.
+    process.on("SIGINT", () => {
+      console.log("");
+      log("Shutting down...");
+      try { serverExports && serverExports.shutdownChattrProcesses && serverExports.shutdownChattrProcesses(); }
+      catch (e) { warn(`shutdownChattrProcesses failed: ${e.message}`); }
+      ok("Stopped.");
+      process.exit(0);
+    });
   } catch (err) {
     fail(err.message);
     rl.close();
@@ -1184,6 +1368,118 @@ async function cmdInit() {
 
 // ─── Start Command ──────────────────────────────────────────────────────────
 
+/**
+ * Phase 3 / #181 sub-G: migrate legacy v1 projects to per-project clones.
+ *
+ * Runs eagerly at the top of cmdStart() so users see clear progress before
+ * any agents launch. For each project that doesn't yet have a working
+ * per-project clone:
+ *   1. Compute perProjectDir = ~/.quadwork/{project_id}/agentchattr
+ *   2. installAgentChattr(perProjectDir) — idempotent (#183 + #187)
+ *   3. Copy the existing legacy <working_dir>/agentchattr/config.toml into
+ *      the new clone ROOT if it exists. AgentChattr's run.py reads
+ *      ROOT/config.toml from the clone dir, so this is what makes the
+ *      project actually start from its own clone.
+ *   4. Set project.agentchattr_dir on the config entry and persist.
+ *
+ * Idempotent: if a project already has a working per-project clone with a
+ * config.toml at the ROOT and agentchattr_dir set, it is skipped silently.
+ * The legacy ~/.quadwork/agentchattr/ install is left alone — cleanup is
+ * sub-H (#189).
+ *
+ * The migration never touches worktrees, repo content, or token files;
+ * only the per-project AgentChattr install dir and config.json.
+ */
+function migrateLegacyProjects(config) {
+  if (!config.projects || config.projects.length === 0) return false;
+
+  const needsMigration = config.projects.filter((p) => {
+    if (!p.id) return false;
+    const target = p.agentchattr_dir || path.join(CONFIG_DIR, p.id, "agentchattr");
+    const hasClone = fs.existsSync(path.join(target, "run.py")) &&
+                     fs.existsSync(path.join(target, ".venv", "bin", "python"));
+    const hasToml = fs.existsSync(path.join(target, "config.toml"));
+    const hasField = !!p.agentchattr_dir;
+    return !(hasField && hasClone && hasToml);
+  });
+
+  if (needsMigration.length === 0) return false;
+
+  header("Migrating legacy projects to per-project AgentChattr clones");
+  let mutated = false;
+  for (const project of needsMigration) {
+    const perProjectDir = path.join(CONFIG_DIR, project.id, "agentchattr");
+    log(`  ${project.id} → ${perProjectDir}`);
+
+    // 1. Install (idempotent — no-op if clone is already valid).
+    if (!findAgentChattr(perProjectDir)) {
+      const acSpinner = spinner(`    Cloning AgentChattr for ${project.id}...`);
+      const installResult = installAgentChattr(perProjectDir);
+      if (!installResult) {
+        acSpinner.stop(false);
+        const reason = installAgentChattr.lastError || "unknown error";
+        warn(`    Migration failed for ${project.id}: ${reason}`);
+        warn(`    ${project.id} will keep using the legacy global install until this is resolved.`);
+        continue;
+      }
+      acSpinner.stop(true);
+    }
+
+    // 2. Seed config.toml at the clone ROOT from the legacy in-worktree
+    //    location if present. Do not overwrite an existing per-project
+    //    config.toml — re-running the migration must be a no-op.
+    //
+    //    If the legacy toml exists but the copy fails, we MUST NOT persist
+    //    agentchattr_dir — otherwise #186's resolver would switch this
+    //    project to a clone that lacks the project's real ports, and
+    //    AgentChattr would silently start on run.py defaults. Leaving
+    //    agentchattr_dir unset keeps the project on the legacy global
+    //    install via #186's fallback ladder until the next attempt.
+    const targetToml = path.join(perProjectDir, "config.toml");
+    let tomlReady = fs.existsSync(targetToml);
+    if (!tomlReady && project.working_dir) {
+      const legacyToml = path.join(project.working_dir, "agentchattr", "config.toml");
+      if (fs.existsSync(legacyToml)) {
+        try {
+          fs.copyFileSync(legacyToml, targetToml);
+          log(`    Copied legacy config.toml → ${targetToml}`);
+          tomlReady = true;
+        } catch (e) {
+          warn(`    Could not copy ${legacyToml}: ${e.message}`);
+          warn(`    ${project.id} migration aborted: legacy config.toml not transferred.`);
+          warn(`    ${project.id} will keep using the legacy global install via #186 fallback.`);
+          continue;
+        }
+      } else {
+        // No legacy toml at all (e.g. user removed it). Refuse to migrate
+        // — without a config.toml at the clone ROOT, run.py would start
+        // on built-in defaults and bind to the wrong ports.
+        warn(`    ${project.id} has no legacy config.toml at ${legacyToml}; skipping migration.`);
+        warn(`    Re-run setup to regenerate config.toml, then 'quadwork start' will retry migration.`);
+        continue;
+      }
+    }
+    if (!tomlReady) {
+      warn(`    ${project.id} migration aborted: no config.toml at ${targetToml}.`);
+      continue;
+    }
+
+    // 3. Persist agentchattr_dir on the project entry — only after the
+    //    clone has run.py + venv + config.toml all in place.
+    if (project.agentchattr_dir !== perProjectDir) {
+      project.agentchattr_dir = perProjectDir;
+      mutated = true;
+    }
+  }
+
+  if (mutated) {
+    try { writeConfig(config); ok("Updated config.json with per-project agentchattr_dir entries"); }
+    catch (e) { warn(`Failed to write config.json: ${e.message}`); }
+  }
+  log("  Legacy ~/.quadwork/agentchattr/ left in place; remove via cleanup script (#189).");
+  return true;
+}
+
 function cmdStart() {
   console.log("\n  QuadWork Start\n");
 
@@ -1192,6 +1488,11 @@ function cmdStart() {
     warn("No projects configured yet. Create one at the setup page.");
   }
 
+  // Phase 3 / #181: migrate legacy single-install projects to their
+  // own per-project clones before any AgentChattr spawn happens.
+  // Idempotent — a no-op once every project already has a working clone.
+  migrateLegacyProjects(config);
+
   const quadworkDir = path.join(__dirname, "..");
   const port = config.port || 8400;
 
@@ -1209,27 +1510,38 @@ function cmdStart() {
     process.exit(1);
   }
 
-  // Start AgentChattr for each project that has a config.toml
+  // Start AgentChattr for each project from its own per-project clone.
+  // Phase 2E / #181: each project entry now has agentchattr_dir, set by
+  // the wizards in #184/#185. Resolve per-project so two projects with
+  // their own clones (and their own ports) can run side by side without
+  // sharing a single global install. Falls back to the legacy global
+  // install dir for v1 entries that have not been migrated yet (#188).
   const acPids = [];
-  const acDir = findAgentChattr(config.agentchattr_dir);
-  if (acDir) {
-    for (const project of config.projects) {
-      if (!project.working_dir) continue;
-      const configToml = path.join(project.working_dir, "agentchattr", "config.toml");
-      if (!fs.existsSync(configToml)) continue;
-      const acSpawn = chattrSpawnArgs(acDir, ["--config", configToml]);
-      if (!acSpawn) continue;
-      const acProc = spawn(acSpawn.command, acSpawn.spawnArgs, {
-        cwd: acSpawn.cwd,
-        stdio: "ignore",
-        detached: true,
-      });
-      acProc.on("error", () => {});
-      acProc.unref();
-      if (acProc.pid) {
-        ok(`AgentChattr started for ${project.id} (PID: ${acProc.pid})`);
-        acPids.push(acProc.pid);
-      }
+  const legacyAcDir = findAgentChattr(config.agentchattr_dir);
+  for (const project of config.projects) {
+    if (!project.working_dir) continue;
+    const projectAcDir = findAgentChattr(project.agentchattr_dir) || legacyAcDir;
+    if (!projectAcDir) continue;
+    // config.toml lives at the clone ROOT for new projects; legacy v1
+    // setups still keep it under <working_dir>/agentchattr/config.toml.
+    const perProjectToml = path.join(projectAcDir, "config.toml");
+    const legacyToml = path.join(project.working_dir, "agentchattr", "config.toml");
+    const configToml = fs.existsSync(perProjectToml)
+      ? perProjectToml
+      : (fs.existsSync(legacyToml) ? legacyToml : null);
+    if (!configToml) continue;
+    const acSpawn = chattrSpawnArgs(projectAcDir, ["--config", configToml]);
+    if (!acSpawn) continue;
+    const acProc = spawn(acSpawn.command, acSpawn.spawnArgs, {
+      cwd: acSpawn.cwd,
+      stdio: "ignore",
+      detached: true,
+    });
+    acProc.on("error", () => {});
+    acProc.unref();
+    if (acProc.pid) {
+      ok(`AgentChattr started for ${project.id} from ${projectAcDir} (PID: ${acProc.pid})`);
+      acPids.push(acProc.pid);
     }
   }
 
@@ -1240,13 +1552,25 @@ function cmdStart() {
     try { execSync(`${openCmd} ${dashboardUrl}`, { stdio: "ignore" }); } catch {}
   }, 1500);
 
-  // Graceful shutdown on Ctrl+C
+  // Run server in foreground. Capture exports so the SIGINT handler
+  // can ask the server to SIGTERM its own chattrProcesses Map too
+  // (dashboard-spawned AgentChattr children aren't in cmdStart's
+  // acPids list).
+  log(`Dashboard: ${dashboardUrl}`);
+  log("Press Ctrl+C to stop.\n");
+  const serverExports = require(path.join(serverDir, "index.js"));
+
+  // Graceful shutdown on Ctrl+C — kills cmdStart's own spawned
+  // AgentChattrs AND anything the dashboard spawned via
+  // /api/agentchattr/{id}/start after init.
   process.on("SIGINT", () => {
     console.log("");
     log("Shutting down...");
     for (const pid of acPids) {
       try { process.kill(pid, "SIGTERM"); } catch {}
     }
+    try { serverExports && serverExports.shutdownChattrProcesses && serverExports.shutdownChattrProcesses(); }
+    catch (e) { warn(`shutdownChattrProcesses failed: ${e.message}`); }
     ok("Stopped.");
     console.log("");
     log("To restart:");
@@ -1254,11 +1578,6 @@ function cmdStart() {
     console.log("");
     process.exit(0);
   });
-
-  // Run server in foreground
-  log(`Dashboard: ${dashboardUrl}`);
-  log("Press Ctrl+C to stop.\n");
-  require(path.join(serverDir, "index.js"));
 }
 
 // ─── Stop Command ───────────────────────────────────────────────────────────
@@ -1329,7 +1648,11 @@ async function cmdAddProject() {
 
     writeQuadWorkConfig(setup);
 
-    const configTomlPath = path.join(setup.absDir, "agentchattr", "config.toml");
+    // Phase 2C / #181: config.toml lives at the per-project clone ROOT
+    // because AgentChattr's run.py loads ROOT/config.toml and ignores
+    // --config. Must match the install path used inside
+    // writeAgentChattrConfig(): CONFIG_DIR/{projectName}/agentchattr.
+    const configTomlPath = path.join(CONFIG_DIR, setup.projectName, "agentchattr", "config.toml");
     writeAgentChattrConfig(setup, configTomlPath);
 
     header("Project Added");
@@ -1346,6 +1669,112 @@ async function cmdAddProject() {
   }
 }
 
+// ─── Cleanup Command (#181 sub-H) ───────────────────────────────────────────
+
+/**
+ * Reclaim disk space taken by per-project AgentChattr clones (~77 MB each)
+ * or by the legacy shared install left behind after migration (#188).
+ *
+ * Usage:
+ *   npx quadwork cleanup --project <id>
+ *     Removes ~/.quadwork/{id}/ and the matching entry from config.json.
+ *     Leaves the user's worktrees and source repos completely alone.
+ *
+ *   npx quadwork cleanup --legacy
+ *     Removes the legacy shared ~/.quadwork/agentchattr/ install. Refuses
+ *     to run unless every project in config.json already has its own
+ *     working per-project clone (so nothing falls back onto the legacy
+ *     install via #186's resolution ladder).
+ *
+ * Both modes prompt for confirmation before deleting.
+ */
+async function cmdCleanup() {
+  const args = process.argv.slice(3);
+  const projectFlagIdx = args.indexOf("--project");
+  const projectId = projectFlagIdx >= 0 ? args[projectFlagIdx + 1] : null;
+  const legacy = args.includes("--legacy");
+
+  if (!projectId && !legacy) {
+    console.log(`
+  Usage:
+    npx quadwork cleanup --project <id>   Remove a project's AgentChattr clone + config entry
+    npx quadwork cleanup --legacy         Remove the legacy ~/.quadwork/agentchattr/ install
+`);
+    process.exit(1);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const config = readConfig();
+
+    // --- Per-project cleanup ---
+    if (projectId) {
+      const idx = (config.projects || []).findIndex((p) => p.id === projectId);
+      const projectDir = path.join(CONFIG_DIR, projectId);
+      if (idx < 0 && !fs.existsSync(projectDir)) {
+        warn(`No project '${projectId}' in config and no directory at ${projectDir}.`);
+        return;
+      }
+      header(`Cleanup: ${projectId}`);
+      if (fs.existsSync(projectDir)) log(`  Directory: ${projectDir}`);
+      if (idx >= 0) log(`  Config entry: ${projectId} (${config.projects[idx].repo || "no repo"})`);
+      log("  Worktrees and source repos will NOT be touched.");
+      const confirm = await askYN(rl, `Delete ${projectDir} and remove the config entry?`, false);
+      if (!confirm) { warn("Aborted."); return; }
+
+      if (fs.existsSync(projectDir)) {
+        try { fs.rmSync(projectDir, { recursive: true, force: true }); ok(`Removed ${projectDir}`); }
+        catch (e) { fail(`Could not remove ${projectDir}: ${e.message}`); return; }
+      }
+      if (idx >= 0) {
+        config.projects.splice(idx, 1);
+        try { writeConfig(config); ok(`Updated ${CONFIG_PATH}`); }
+        catch (e) { fail(`Could not write config: ${e.message}`); return; }
+      }
+      return;
+    }
+
+    // --- Legacy cleanup ---
+    if (legacy) {
+      const legacyDir = path.join(CONFIG_DIR, "agentchattr");
+      if (!fs.existsSync(legacyDir)) {
+        warn(`No legacy install at ${legacyDir}.`);
+        return;
+      }
+      header("Cleanup: legacy ~/.quadwork/agentchattr/");
+
+      // Refuse if any project still depends on the legacy install — i.e.
+      // any project without its own working per-project clone (run.py +
+      // venv + config.toml at ROOT). Mirrors #186's resolution ladder.
+      const stillDepends = [];
+      for (const p of config.projects || []) {
+        if (!p.id) continue;
+        const dir = p.agentchattr_dir || path.join(CONFIG_DIR, p.id, "agentchattr");
+        const ok = fs.existsSync(path.join(dir, "run.py")) &&
+                   fs.existsSync(path.join(dir, ".venv", "bin", "python")) &&
+                   fs.existsSync(path.join(dir, "config.toml"));
+        if (!ok) stillDepends.push(p.id);
+      }
+      if (stillDepends.length > 0) {
+        fail(`Refusing to remove legacy install — these projects still depend on it:`);
+        for (const id of stillDepends) console.log(`    - ${id}`);
+        warn(`Run 'npx quadwork start' to migrate them (#188), then re-run cleanup --legacy.`);
+        return;
+      }
+
+      log(`  Directory: ${legacyDir}`);
+      log("  All projects already have their own per-project clones.");
+      const confirm = await askYN(rl, `Delete ${legacyDir}?`, false);
+      if (!confirm) { warn("Aborted."); return; }
+
+      try { fs.rmSync(legacyDir, { recursive: true, force: true }); ok(`Removed ${legacyDir}`); }
+      catch (e) { fail(`Could not remove ${legacyDir}: ${e.message}`); return; }
+    }
+  } finally {
+    rl.close();
+  }
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 const command = process.argv[2];
@@ -1363,6 +1792,9 @@ switch (command) {
   case "add-project":
     cmdAddProject();
     break;
+  case "cleanup":
+    cmdCleanup();
+    break;
   default:
     console.log(`
   Usage: quadwork <command>
@@ -1372,6 +1804,7 @@ switch (command) {
     start         Start the QuadWork dashboard and backend
     stop          Stop all QuadWork processes
     add-project   Add a project via CLI (alternative to web UI /setup)
+    cleanup       Reclaim disk space (--project <id> or --legacy)
 
   Workflow:
     1. npx quadwork init     — one-time global setup, opens dashboard
@@ -1382,6 +1815,8 @@ switch (command) {
     npx quadwork init
     npx quadwork start
     npx quadwork stop
+    npx quadwork cleanup --project my-project
+    npx quadwork cleanup --legacy
 `);
     if (command) process.exit(1);
 }