mover-os 4.7.8 → 4.7.9

package/src/dashboard/lib/library-search.js

@@ -0,0 +1,290 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// library-search.js — ONE truthful search index for the Library route.
+//
+// Sol full product review (2026-07-11, Library 5.0/10): the "EVERYTHING"
+// search box indexed only the libraryV2 subset while the other shelves were
+// counts with no rows behind them. This module makes the coverage equal the
+// advertised shelves: every shelf the bento names is either content-searchable
+// here or explicitly reported as notIndexable with the reason (CLI commands
+// are usage counts, not files).
+//
+// Contract:
+//   - Read-only. Never writes. Never leaves the declared shelf roots.
+//   - Bounded: per-file size cap, per-shelf file cap, result cap, passage cap.
+//   - Results carry root + vault-relative (or root-relative) path + a 1-based
+//     line anchor + the matched passage, so the UI can open the real file AT
+//     the passage in the existing viewer.
+//   - Honest coverage: shelves whose directory does not exist are reported in
+//     coverage.missing; shelves with nothing to read are in
+//     coverage.notIndexable. Nothing is silently skipped.
+//   - Non-text files (PDFs, images) match by NAME only and say so
+//     (nameOnly: true, line/passage null) — never implied content coverage.
+
+const MAX_FILE_BYTES = 256 * 1024;      // matches /api/file/read cap
+const MAX_FILES_PER_SHELF = 2000;
+const MAX_DEPTH = 6;
+const MAX_LIMIT = 100;
+const DEFAULT_LIMIT = 40;
+const PASSAGE_CAP = 240;
+const EXCLUDED_DIRS = new Set([
+  "node_modules", "dist", ".git", ".obsidian", ".trash", "coverage",
+]);
+
+// Extensions whose CONTENT we read as text. Everything else is name-only.
+const TEXT_EXTS = new Set([".md", ".txt", ".sh", ".js", ".mjs", ".ps1", ".canvas", ".json"]);
+
+// ── shelf definitions — ids are stable API; labels mirror the bento ─────────
+// dirs(ctx) returns the roots to walk for that shelf, each tagged with the
+// serving root id the file-read endpoint understands (vault|skills|workflows|hooks).
+const SHELVES = [
+  {
+    id: "engine", label: "Engine files",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "02_Areas", "Engine"), depth: 1 }],
+  },
+  {
+    id: "projects", label: "Projects",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "01_Projects"), depth: MAX_DEPTH }],
+  },
+  {
+    id: "library", label: "Library notes",
+    dirs: (ctx) => [
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "MOCs"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Principles"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "SOPs"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Cheatsheets"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Scripts"), depth: 3 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "Decisions"), depth: 3 },
+    ],
+  },
+  {
+    id: "skills", label: "Skills",
+    dirs: (ctx) => [{ root: "skills", dir: path.join(ctx.claudeDir, "skills"), depth: 3 }],
+  },
+  {
+    id: "hooks", label: "Hooks",
+    dirs: (ctx) => [{ root: "hooks", dir: path.join(ctx.bundleRoot, "src", "hooks"), depth: 2 }],
+  },
+  {
+    id: "workflows", label: "Workflows",
+    dirs: (ctx) => [{ root: "workflows", dir: path.join(ctx.bundleRoot, "src", "workflows"), depth: 1 }],
+  },
+  {
+    id: "cli", label: "CLI commands",
+    notIndexable: "CLI commands are usage counts stored in your config, not files. There is no text to search.",
+  },
+  {
+    id: "people", label: "People",
+    dirs: (ctx) => [
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "People"), depth: 2 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "Organizations"), depth: 2 },
+      { root: "vault", dir: path.join(ctx.vault, "03_Library", "Entities", "Places"), depth: 2 },
+    ],
+  },
+  {
+    id: "captures", label: "Captures",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "03_Library", "Inputs"), depth: 3 }],
+  },
+  {
+    id: "archives", label: "Archives",
+    dirs: (ctx) => [{ root: "vault", dir: path.join(ctx.vault, "04_Archives"), depth: MAX_DEPTH }],
+  },
+];
+
+/** Map a serving-root id to its absolute directory. Used by the file-read
+ *  endpoint to resolve non-vault results with the same realpath containment
+ *  it already applies to the vault. Returns null for unknown roots. */
+function rootDirFor(ctx, root) {
+  if (root === "vault") return ctx.vault;
+  if (root === "skills") return path.join(ctx.claudeDir, "skills");
+  if (root === "workflows") return path.join(ctx.bundleRoot, "src", "workflows");
+  if (root === "hooks") return path.join(ctx.bundleRoot, "src", "hooks");
+  return null;
+}
+
+function walkFiles(dir, maxDepth, out, state) {
+  if (state.count >= MAX_FILES_PER_SHELF) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return; }
+  for (const ent of entries) {
+    if (state.count >= MAX_FILES_PER_SHELF) return;
+    if (ent.name.startsWith(".")) continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      if (EXCLUDED_DIRS.has(ent.name)) continue;
+      if (maxDepth > 1) walkFiles(full, maxDepth - 1, out, state);
+      continue;
+    }
+    if (!ent.isFile()) continue; // symlinks are not followed — containment stays real
+    out.push(full);
+    state.count += 1;
+  }
+}
+
+/** Collect the files behind one shelf. Returns { files: [{abs, root, rootDir}], missing } */
+function shelfFiles(shelf, ctx) {
+  const roots = shelf.dirs ? shelf.dirs(ctx) : [];
+  const files = [];
+  let anyDirExists = false;
+  const state = { count: 0 };
+  for (const r of roots) {
+    let stat = null;
+    try { stat = fs.statSync(r.dir); } catch (_e) { /* absent */ }
+    if (!stat || !stat.isDirectory()) continue;
+    anyDirExists = true;
+    const abs = [];
+    walkFiles(r.dir, r.depth || 1, abs, state);
+    for (const a of abs) files.push({ abs: a, root: r.root, rootDir: rootDirFor(ctx, r.root) });
+  }
+  return { files, missing: roots.length > 0 && !anyDirExists };
+}
+
+/** Build the passage around the first match inside a line, capped. */
+function passageFrom(line, matchIdx, qLen) {
+  const trimmed = line.trim();
+  if (trimmed.length <= PASSAGE_CAP) return trimmed;
+  // center the window on the match
+  const lead = Math.max(0, matchIdx - Math.floor((PASSAGE_CAP - qLen) / 2));
+  const slice = line.slice(lead, lead + PASSAGE_CAP).trim();
+  return slice;
+}
+
+/**
+ * searchLibrary(ctx, opts) — the one index.
+ *   ctx  = { vault, bundleRoot, claudeDir }
+ *   opts = { q, shelf, limit }
+ *     q     — case-insensitive substring; empty q + shelf = browse listing
+ *     shelf — shelf id to scope to ("" = every indexed shelf)
+ *     limit — max results (1..100)
+ * Returns { q, shelf, results, truncated, scanned, coverage }.
+ */
+function searchLibrary(ctx, opts = {}) {
+  const q = String(opts.q || "").slice(0, 200);
+  const scope = String(opts.shelf || "");
+  const limit = Math.max(1, Math.min(MAX_LIMIT, Number(opts.limit) || DEFAULT_LIMIT));
+  const lc = q.toLowerCase();
+
+  const coverage = { indexed: [], notIndexable: [], missing: [] };
+  const results = [];
+  let scannedFiles = 0;
+  let skippedLarge = 0;
+  let truncated = false;
+
+  for (const shelf of SHELVES) {
+    if (shelf.notIndexable) {
+      coverage.notIndexable.push({ id: shelf.id, label: shelf.label, reason: shelf.notIndexable });
+      continue;
+    }
+    const { files, missing } = shelfFiles(shelf, ctx);
+    if (missing) {
+      coverage.missing.push({ id: shelf.id, label: shelf.label });
+      continue;
+    }
+    coverage.indexed.push({ id: shelf.id, label: shelf.label, files: files.length });
+
+    if (scope && scope !== shelf.id) continue; // counted for coverage, never searched
+
+    for (const f of files) {
+      // Every skill's file is literally named SKILL.md — the skill's actual
+      // name is its folder. Rendering the basename made the whole Skills
+      // shelf read "SKILL.md, SKILL.md, ..." (owner report + terra CONFIRMED
+      // #1, 2026-07-12). Same rule for any convention-named container file.
+      const base = path.basename(f.abs);
+      let name = base;
+      if (/^(SKILL|README|INDEX)\.md$/i.test(base)) {
+        const folder = path.basename(path.dirname(f.abs));
+        if (folder && folder !== "." && folder !== path.basename(f.rootDir)) name = folder;
+      }
+      const relPath = path.relative(f.rootDir, f.abs).split(path.sep).join("/");
+      // ext/textReadable ALWAYS derive from the real file, never the display
+      // name — a folder-derived name has no extension and would silently
+      // demote the file to name-only search.
+      const ext = path.extname(base).toLowerCase();
+      const textReadable = TEXT_EXTS.has(ext);
+
+      let mtime = null;
+      let size = 0;
+      try { const st = fs.statSync(f.abs); mtime = st.mtime.toISOString(); size = st.size; } catch (_e) { continue; }
+
+      // Browse mode: empty query + a shelf scope lists the shelf's real files.
+      if (!lc) {
+        if (!scope) continue; // browsing "everything" is the catalog's job
+        results.push({
+          shelf: shelf.id, shelfLabel: shelf.label, name, relPath, root: f.root,
+          line: null, passage: null, matches: 0, nameOnly: !textReadable, mtime,
+        });
+        continue;
+      }
+
+      const nameHit = name.toLowerCase().includes(lc);
+
+      if (!textReadable) {
+        // Content is not text — a name match is the only honest match.
+        if (nameHit) {
+          results.push({
+            shelf: shelf.id, shelfLabel: shelf.label, name, relPath, root: f.root,
+            line: null, passage: null, matches: 0, nameOnly: true, mtime,
+          });
+        }
+        continue;
+      }
+
+      if (size > MAX_FILE_BYTES) { skippedLarge += 1; continue; }
+
+      let content = "";
+      try { content = fs.readFileSync(f.abs, "utf8"); } catch (_e) { continue; }
+      scannedFiles += 1;
+
+      let firstLine = null;
+      let firstPassage = null;
+      let matches = 0;
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const idx = lines[i].toLowerCase().indexOf(lc);
+        if (idx === -1) continue;
+        matches += 1;
+        if (firstLine === null) {
+          firstLine = i + 1;
+          firstPassage = passageFrom(lines[i], idx, lc.length);
+        }
+      }
+
+      if (!nameHit && matches === 0) continue;
+      results.push({
+        shelf: shelf.id, shelfLabel: shelf.label, name, relPath, root: f.root,
+        line: firstLine, passage: firstPassage, matches,
+        nameOnly: matches === 0, mtime,
+      });
+    }
+  }
+
+  // Rank: name matches first, then by match density, then recency.
+  if (lc) {
+    results.sort((a, b) => {
+      const an = a.name.toLowerCase().includes(lc) ? 1 : 0;
+      const bn = b.name.toLowerCase().includes(lc) ? 1 : 0;
+      if (an !== bn) return bn - an;
+      if (a.matches !== b.matches) return b.matches - a.matches;
+      return String(b.mtime || "").localeCompare(String(a.mtime || ""));
+    });
+  } else {
+    results.sort((a, b) => String(b.mtime || "").localeCompare(String(a.mtime || "")));
+  }
+
+  if (results.length > limit) {
+    results.length = limit;
+    truncated = true;
+  }
+
+  return {
+    q, shelf: scope || "all",
+    results, truncated,
+    scanned: { files: scannedFiles, skippedLarge },
+    coverage,
+  };
+}
+
+module.exports = { searchLibrary, rootDirFor, SHELVES };

package/src/dashboard/lib/memory-index.js

@@ -15,6 +15,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const { tokenize, termFreq, buildVocab } = require("./memory-text");
 const { enumerateSessions, parseTranscript, deriveProject } = require("./transcript-parser");
 const { parseSessionLogs } = require("./session-log-parser");
@@ -46,9 +47,34 @@ function ensureDirs() {
 }
 
 function atomicWrite(file, obj) {
-  const tmp = file + ".tmp";
+  // terra T-MH-2: a fixed `file + ".tmp"` name means two concurrent SessionEnd
+  // hooks writing the same segment/manifest share one temp path and can interleave
+  // into a torn file. A per-write unique temp name makes each write's rename
+  // independent (the last full write wins cleanly; no half-written temp survives).
+  const tmp = file + "." + process.pid + "-" + crypto.randomBytes(4).toString("hex") + ".tmp";
   fs.writeFileSync(tmp, JSON.stringify(obj));
-  fs.renameSync(tmp, file);
+  try { fs.renameSync(tmp, file); }
+  catch (e) { try { fs.unlinkSync(tmp); } catch (_) {} throw e; }
+}
+
+// terra T-MH-1: safeReadJson() collapses "file absent" and "file present but
+// MALFORMED" both to null, so `safeReadJson(segFile) || newSeg()` would overwrite
+// a corrupt segment with an empty one — discarding every indexed doc for that
+// month. Distinguish the two: a MISSING segment is a fresh newSeg(); a present-
+// but-unparseable segment THROWS, so the fail-open SessionEnd hook skips indexing
+// this one session and PRESERVES the existing file rather than nuking it.
+function readSegOrNew(segFile) {
+  let raw;
+  try { raw = fs.readFileSync(segFile, "utf8"); }
+  catch (e) { if (e.code === "ENOENT") return newSeg(); throw e; }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (_) { throw Object.assign(new Error("memory segment is malformed; refusing to overwrite it: " + segFile), { code: "ESEGCORRUPT" }); }
+  // A parsed-but-wrong-shape file is also not safe to fold into — treat as corrupt.
+  if (!parsed || typeof parsed !== "object" || !parsed.docs || !parsed.postings) {
+    throw Object.assign(new Error("memory segment has an unexpected shape; refusing to overwrite it: " + segFile), { code: "ESEGCORRUPT" });
+  }
+  return parsed;
 }
 
 function monthOf(ts, fallbackMs) {
@@ -377,19 +403,43 @@ async function indexSession(file, opts = {}) {
   if (!man) return { error: "no index — run --backfill first" };
   man.docFreq = man.docFreq || {}; man.linkFreq = man.linkFreq || {}; man.indexedSessions = man.indexedSessions || {};
   const vault = opts.vault || man.vault;
-  const sessionId = opts.sessionId || path.basename(file).replace(/\.jsonl$/, "");
-  // Derive the project from the transcript's parent dir (…/projects/<encoded-dir>/<uuid>.jsonl)
-  // when not passed — the SessionEnd hook calls indexSession(file, {}), and without this every
-  // live-indexed session would be project=null, making the cross-project scope guard a no-op.
-  const project = opts.project || deriveProject(path.basename(path.dirname(file))) || null;
+  const pathSessionId = path.basename(file).replace(/\.jsonl$/, "");
+  const pathProject = deriveProject(path.basename(path.dirname(file))) || null;
   let mtime = null, size = 0;
   try { const st = fs.statSync(file); mtime = st.mtimeMs; size = st.size; } catch {}
-  const prev = man.indexedSessions[sessionId];
-  if (prev && mtime && prev.mtime === mtime && !opts.force) return { skipped: true, sessionId };
 
-  const r = await parseTranscript(file, { vocab: buildVocab(vault), sessionId, project });
+  // Parse before selecting identity. Claude stores sessions under an encoded project directory, but
+  // Codex stores rollouts under date folders and carries the real session id + cwd in session_meta.
+  const r = await parseTranscript(file, {
+    vocab: buildVocab(vault),
+    sessionId: opts.sessionId,
+    project: opts.project,
+    agent: opts.agent,
+  });
+  const sessionId = opts.sessionId || r.sessionId || pathSessionId;
+  const project = opts.project || r.project || pathProject;
   if (r.error) return { error: "parse failed", sessionId };
 
+  let reindexed = false;
+  // Remove a pre-fix Codex entry keyed by the rollout filename. Without this migration the same
+  // transcript survives twice: once under rollout-* and once under its canonical session id.
+  if (pathSessionId !== sessionId) {
+    const legacy = man.indexedSessions[pathSessionId];
+    if (legacy && legacy.month) {
+      const legacyFile = path.join(SEG_DIR, "raw-" + legacy.month + ".json");
+      const legacySeg = safeReadJson(legacyFile);
+      if (legacySeg && legacySeg.docs["session:" + pathSessionId]) {
+        removeDocContribution(legacySeg, "session:" + pathSessionId, man);
+        atomicWrite(legacyFile, legacySeg);
+      }
+      delete man.indexedSessions[pathSessionId];
+      reindexed = true;
+    }
+  }
+
+  const prev = man.indexedSessions[sessionId];
+  if (prev && mtime && prev.mtime === mtime && !opts.force && !reindexed) return { skipped: true, sessionId };
+
   const month = monthOf(r.firstTs, mtime);
   const id = "session:" + sessionId;
 
@@ -398,7 +448,6 @@ async function indexSession(file, opts = {}) {
   // lives in the PREVIOUSLY recorded month's segment — remove it from THERE too, else it orphans
   // (ghost doc) and permanently inflates docFreq/totalDocs/linkFreq, degrading IDF until a full
   // --backfill. Only fires on a genuine month change; the common same-month re-index skips it.
-  let reindexed = false;
   const prevMonth = prev && prev.month;
   if (prevMonth && prevMonth !== month) {
     const prevSegFile = path.join(SEG_DIR, "raw-" + prevMonth + ".json");
@@ -411,7 +460,7 @@ async function indexSession(file, opts = {}) {
   }
 
   const segFile = path.join(SEG_DIR, "raw-" + month + ".json");
-  const seg = safeReadJson(segFile) || newSeg();
+  const seg = readSegOrNew(segFile); // terra T-MH-1: never clobber a malformed segment
 
   // remove old contribution (same-month re-index case) — scan only this segment's postings.
   if (seg.docs[id]) { removeDocContribution(seg, id, man); reindexed = true; }

package/src/dashboard/lib/pid-markers.js

@@ -0,0 +1,80 @@
+"use strict";
+
+/**
+ * pid-markers.js — crash-orphan bookkeeping shared by AgentSessionManager
+ * (Chat/onboarding) and RunRegistry (Run tab).
+ *
+ * Every dashboard-spawned agent child is detached into its own process group
+ * and recorded here as one marker file per pid, tagged with the owning
+ * dashboard's pid. On startup each manager reaps any group whose OWNER is
+ * gone — children escaped by a crashed dashboard (kill -9, OOM, update crash)
+ * that no graceful shutdown path could ever reach.
+ *
+ * Extracted verbatim from agent-session.js (MF2, Codex r2 hardening) so the
+ * Run tab gets the same guarantee. One file per pid: no shared-file
+ * read-modify-write race across concurrent dashboards; a corrupt write only
+ * loses its own marker. Writes are atomic (tmp + rename). Both managers share
+ * ONE directory on purpose: whichever starts first reaps the other's orphans.
+ */
+
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+
+const MARKERS_DIR = path.join(os.homedir(), ".mover", "dashboard", "agent-pids");
+
+function markerPath(pid) { return path.join(MARKERS_DIR, String(pid) + ".json"); }
+
+function writeMarker(pid, data) {
+  try {
+    fs.mkdirSync(MARKERS_DIR, { recursive: true });
+    const f = markerPath(pid), tmp = f + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(data));
+    fs.renameSync(tmp, f); // atomic: a reader never sees a half-written marker
+  } catch (_) {}
+}
+
+function removeMarker(pid) { try { fs.unlinkSync(markerPath(pid)); } catch (_) {} }
+
+function readMarkers() {
+  let files; try { files = fs.readdirSync(MARKERS_DIR); } catch (_) { return []; }
+  const out = [];
+  for (const fn of files) {
+    if (!fn.endsWith(".json")) continue;
+    try { out.push(JSON.parse(fs.readFileSync(path.join(MARKERS_DIR, fn), "utf8"))); } catch (_) {}
+  }
+  return out;
+}
+
+function isAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
+}
+
+// True if ANY member of the process group still exists (not just the leader) —
+// process.kill(-pid, 0) throws ESRCH only when the whole group is gone.
+function groupAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(-pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
+}
+
+function killGroup(pid, sig) {
+  if (!pid) return false;
+  try { process.kill(-pid, sig); return true; }
+  catch (_) { try { process.kill(pid, sig); return true; } catch (__) { return false; } }
+}
+
+// Reap any recorded group whose owning dashboard is gone. Idempotent; safe to
+// call from every manager's constructor (they share the directory).
+function reapOrphans() {
+  for (const m of readMarkers()) {
+    if (!m || !m.pid) continue;
+    // Keep markers whose owning dashboard is still alive (this process OR a
+    // concurrent one). Only a marker whose owner is GONE is a real orphan.
+    if (m.ownerPid && isAlive(m.ownerPid)) continue;
+    if (groupAlive(m.pid)) killGroup(m.pid, "SIGKILL"); // owner gone → orphaned group
+    removeMarker(m.pid);
+  }
+}
+
+module.exports = { MARKERS_DIR, writeMarker, removeMarker, readMarkers, isAlive, groupAlive, killGroup, reapOrphans };

package/src/dashboard/lib/run-registry.js

@@ -29,9 +29,11 @@
  */
 
 const { spawn } = require("child_process");
+const { writeMarker, removeMarker, groupAlive, killGroup, reapOrphans } = require("./pid-markers");
 
 const DEFAULTS = {
   maxRuns: 40,                       // retain at most N runs (live + finished)
+  maxConcurrent: 4,                  // live child processes at once; excess requests are refused
   maxBuffer: 1024 * 1024,            // 1 MB per-run output cap (head dropped, tail kept)
   finishedTtlMs: 6 * 60 * 60 * 1000, // evict finished runs 6h after they end
   idleSweepMs: 5 * 60 * 1000,        // sweep cadence
@@ -43,10 +45,21 @@ class RunRegistry {
     this.opt = { ...DEFAULTS, ...opts };
     this.runs = new Map(); // id -> run record
     this._seq = 0;
+    // R5-A: reap children escaped by a crashed dashboard (same MF2 guarantee
+    // AgentSessionManager has; the marker dir is shared so either manager's
+    // startup cleans up both kinds of orphan).
+    reapOrphans();
     this._sweep = setInterval(() => this._evict(), this.opt.idleSweepMs);
     if (this._sweep.unref) this._sweep.unref();
   }
 
+  /** Live (running/stopping) child count — the concurrency the cap guards. */
+  liveCount() {
+    let n = 0;
+    for (const r of this.runs.values()) if (r.status === "running" || r.status === "stopping") n++;
+    return n;
+  }
+
   /**
    * Spawn a tracked run. The CALLER builds the command (agentCommand) and the
    * final prompt (buildAgentPrompt); this owns the process + buffer lifecycle.
@@ -54,6 +67,13 @@ class RunRegistry {
    * Returns the run record (its `.id` is the handle for subscribe/get/stop).
    */
   start(spec) {
+    // Concurrency cap (R5-A): every run is a real long-lived CLI child with
+    // full tool access; a buggy retry loop must not fork-bomb the machine.
+    if (this.liveCount() >= this.opt.maxConcurrent) {
+      const err = new Error(`${this.opt.maxConcurrent} agents are already running. Stop one or let it finish first.`);
+      err.code = "RUN_LIMIT";
+      throw err;
+    }
     const id = `run_${process.pid}_${++this._seq}`;
     const run = {
       id,
@@ -73,17 +93,26 @@ class RunRegistry {
 
     let child;
     try {
-      child = spawn(spec.cmd, spec.args, { cwd: spec.cwd, env: spec.env, stdio: ["pipe", "pipe", "pipe"] });
+      // detached: own process group, so Stop/shutdown can signal the whole
+      // tree (a run's tool calls spawn grandchildren the bare child.kill()
+      // never reached), and the pid marker lets a post-crash startup reap it.
+      child = spawn(spec.cmd, spec.args, { cwd: spec.cwd, env: spec.env, stdio: ["pipe", "pipe", "pipe"], detached: true });
     } catch (e) {
       this._append(run, `\n[mover-studio] failed to start ${run.agent}: ${e && e.message}\n`);
       this._finish(run, "failed", null);
       return run;
     }
     run.child = child;
+    if (child.pid) writeMarker(child.pid, { pid: child.pid, ownerPid: process.pid, at: Date.now(), kind: "run" });
 
     const timeout = setTimeout(() => {
+      // Mark stopping BEFORE the kill so the close handler reports "stopped",
+      // not a false "done" (terra run-path F2).
+      run.status = "stopping";
       this._append(run, "\n[mover-studio] timeout after 10 minutes; stopping agent.\n", true);
-      try { child.kill("SIGTERM"); } catch (_) {}
+      killGroup(child.pid, "SIGTERM");
+      const esc = setTimeout(() => { if (groupAlive(child.pid)) killGroup(child.pid, "SIGKILL"); }, 2500);
+      if (esc.unref) esc.unref();
     }, this.opt.timeoutMs);
     if (timeout.unref) timeout.unref();
 
@@ -102,12 +131,14 @@ class RunRegistry {
       this._append(run, `\n[mover-studio] failed to start ${run.agent}: ${err && err.message}\n`, true);
       this._finish(run, "failed", null);
     });
-    child.on("close", (code) => {
+    child.on("close", (code, signal) => {
       clearTimeout(timeout);
-      this._append(run, `\n[mover-studio] agent exited with code ${code}\n`, true);
-      // A run we SIGTERM'd via stop() keeps its "stopped" status; otherwise
-      // derive from the exit code (0/null = done, non-zero = exited).
-      const status = run.status === "stopping" ? "stopped" : (code === 0 || code == null) ? "done" : "exited";
+      this._append(run, `\n[mover-studio] agent exited with code ${code}${signal ? ` (signal ${signal})` : ""}\n`, true);
+      // A run we SIGTERM'd (stop OR timeout) keeps "stopping" -> "stopped". A
+      // clean exit (code 0) is "done"; ANY other termination — a non-zero code OR
+      // code==null from a signal we did not send — is "exited", never a false
+      // "done" (terra run-path F2: a signal-killed run was reported as success).
+      const status = run.status === "stopping" ? "stopped" : code === 0 ? "done" : "exited";
       this._finish(run, status, code);
     });
 
@@ -123,6 +154,10 @@ class RunRegistry {
     // Snapshot + register atomically (no I/O between) so no chunk is lost.
     cb({ type: "replay", text: run.output, status: run.status, exit: run.exit });
     if (run.status === "running" || run.status === "stopping") {
+      // Cap live subscribers per run so a flood of stream connections can't pile
+      // up callbacks/sockets (terra run-path F3). Over the cap, the client still
+      // got the full replay above; end it rather than live-stream.
+      if (run.subscribers.size >= 64) { cb({ type: "end", status: run.status, exit: run.exit }); return () => {}; }
       run.subscribers.add(cb);
       return () => run.subscribers.delete(cb);
     }
@@ -130,15 +165,17 @@ class RunRegistry {
     return () => {};
   }
 
-  /** Really stop a run (SIGTERM the child). Distinct from a client merely
+  /** Really stop a run (SIGTERM the child's whole process group — a run's
+   *  tool calls spawn grandchildren). Distinct from a client merely
    *  detaching its stream ("stop watching"). */
   stop(id) {
     const run = this.runs.get(id);
     if (!run || !run.child || (run.status !== "running")) return false;
     run.status = "stopping";
-    try { run.child.kill("SIGTERM"); } catch (_) {}
-    // Escalate if the child ignores SIGTERM.
-    const t = setTimeout(() => { if (run.status === "stopping" && run.child) { try { run.child.kill("SIGKILL"); } catch (_) {} } }, 2500);
+    const pid = run.child.pid;
+    killGroup(pid, "SIGTERM");
+    // Escalate if the group ignores SIGTERM.
+    const t = setTimeout(() => { if (run.status === "stopping" && groupAlive(pid)) killGroup(pid, "SIGKILL"); }, 2500);
     if (t.unref) t.unref();
     return true;
   }
@@ -149,11 +186,30 @@ class RunRegistry {
     return [...this.runs.values()].sort((a, b) => b.started - a.started).map((r) => this._summary(r, false));
   }
 
-  shutdownAll() {
+  /** Kill every live run's process group and WAIT for it to die, escalating
+   *  to SIGKILL after graceMs — mirrors AgentSessionManager.shutdownAll (MF1)
+   *  so the server's hard-exit timer can't strand a stubborn child. If a
+   *  group somehow survives SIGKILL, its marker stays on disk so the next
+   *  startup reaps it — never a silent orphan. */
+  shutdownAll(graceMs = 1500) {
     if (this._sweep) { clearInterval(this._sweep); this._sweep = null; }
-    for (const r of [...this.runs.values()]) {
-      if (r.child && (r.status === "running" || r.status === "stopping")) { try { r.child.kill("SIGTERM"); } catch (_) {} }
-    }
+    const live = [...this.runs.values()].filter((r) => r.child && (r.status === "running" || r.status === "stopping"));
+    return Promise.all(live.map((r) => new Promise((resolve) => {
+      const pid = r.child.pid;
+      killGroup(pid, "SIGTERM");
+      const start = Date.now();
+      let killed = false;
+      const tick = () => {
+        if (!groupAlive(pid)) { removeMarker(pid); return resolve(); }
+        if (!killed && Date.now() - start >= graceMs) { killGroup(pid, "SIGKILL"); killed = true; }
+        if (killed && Date.now() - start >= graceMs + 700) {
+          if (!groupAlive(pid)) removeMarker(pid);
+          return resolve();
+        }
+        const t = setTimeout(tick, 150); if (t.unref) t.unref();
+      };
+      tick();
+    })));
   }
 
   // ── internals ──────────────────────────────────────────────────────────────
@@ -185,6 +241,10 @@ class RunRegistry {
     // "failed"/"stopped" with the close code (null -> "done") and emits a
     // second "end". First finish wins. (Found by a Codex review, 2026-06-30.)
     if (run.ended) return;
+    // Drop the crash marker only once the whole GROUP is gone; if a tool
+    // grandchild outlived the leader, the marker survives and the next
+    // dashboard startup reaps it.
+    if (run.child && run.child.pid && !groupAlive(run.child.pid)) removeMarker(run.child.pid);
     run.status = status;
     run.exit = exit;
     run.ended = Date.now();