archgen-mcp 0.0.6 → 0.0.7

package/src/core/harness-wiring.mjs

@@ -17,11 +17,11 @@
 //   - The per-platform file path + top-level key live in assets/harness-mcp.json
 //     — one source of truth, shared by the tool, the CLI and the docs.
 //   - Writes are atomic and refuse to go through a symlink.
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { assertNotSymlink, assertWithinRoot, writeFileAtomic } from './fs-safety.mjs';
- './errors.mjs';
+import { join, resolve, sep } from 'node:path';
+import { assertNotSymlink, assertWithinRoot, withFileLock, writeFileAtomic } from './fs-safety.mjs';
+import { invalidInput } from './errors.mjs';
 
 /**
  * Detect which harnesses are present in this environment.
@@ -45,6 +45,28 @@ export function expandHome(p, home = homedir()) {
   return p.startsWith('~/') ? join(home, p.slice(2)) : p;
 }
 
+/**
+ * True when `abs` resolves inside `root`.
+ *
+ * The path is compared lexically after normalization, and symlinks are
+ * resolved on both sides when they exist — a symlink pointing out of the
+ * root must not pass as "inside".
+ */
+export function pathIsWithin(abs, root) {
+  if (!abs || !root) return false;
+  const resolvedRoot = resolve(root);
+  const resolved = resolve(abs);
+  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + sep)) return false;
+  try {
+    const realRoot = realpathSync(resolvedRoot);
+    const real = realpathSync(resolved);
+    return real === realRoot || real.startsWith(realRoot + sep);
+  } catch {
+    // The path does not exist yet: the lexical check above stands.
+    return true;
+  }
+}
+
 /**
  * Build the server entry for a harness, substituting the resolved binary path.
  *
@@ -57,12 +79,53 @@ export function expandHome(p, home = homedir()) {
  * @param {string|null} binPath the resolved absolute binary path, or null for the npx form
  * @param {string} fallbackCommand the command used when binPath is null
  */
+/**
+ * Build the entry for one harness config.
+ *
+ * THE TWO FORMS ARE DIFFERENT COMMANDS, NOT ONE COMMAND WITH A SWAPPED
+ * EXECUTABLE.
+ *
+ *   installed  the server's own binary:  `codegraph serve --mcp`
+ *   npx        the same server, fetched:  `npx -y @colbymchenry/codegraph serve --mcp`
+ *
+ * When the binary was resolved, the installed form is used and its
+ * executable is replaced with the resolved absolute path. When it was NOT,
+ * the npx form is used VERBATIM — its executable is already `npx`, and
+ * rewriting it to the server's own name produced the nonsense command
+ * `codegraph -y @colbymchenry/codegraph serve --mcp`, which can never start.
+ *
+ * @param {any} entries the entries block (entries / archgenEntries)
+ * @param {any} npxEntries the npx fallback block (npxEntries / archgenNpxEntries)
+ * @param {string} entryKey the entry shape ('stdio' | 'stdioNoType' | …)
+ * @param {string|null} binPath the resolved absolute binary path, or null for the npx form
+ * @param {string} fallbackCommand the command used when no npx form exists
+ * @returns {any} a fresh entry object (the source is never mutated)
+ */
 export function buildEntry(entries, npxEntries, entryKey, binPath, fallbackCommand) {
-  const source = binPath ? entries[entryKey] : (npxEntries?.[entryKey] ?? entries[entryKey]);
-  const entry = JSON.parse(JSON.stringify(source));
-  const command = binPath ?? fallbackCommand;
-  if (Array.isArray(entry.command)) entry.command = [command, ...entry.command.slice(1)];
-  else entry.command = command;
+  const installed = entries?.[entryKey];
+  const npx = npxEntries?.[entryKey];
+  const useNpx = !binPath && Boolean(npx);
+  const source = useNpx ? npx : installed;
+
+  if (!source || typeof source !== 'object') {
+    // A registry entry naming a shape the writer does not know is a REGISTRY
+    // bug, not a user error. Say so plainly instead of crashing with a
+    // SyntaxError from JSON.parse(undefined).
+    throw invalidInput(
+      `unknown MCP entry shape '${entryKey}' — the harness registry and the writer disagree`,
+      { entryKey, available: Object.keys(entries ?? {}) },
+    );
+  }
+
+  const entry = structuredClone(source);
+  if (binPath) {
+    if (Array.isArray(entry.command)) entry.command = [binPath, ...entry.command.slice(1)];
+    else entry.command = binPath;
+  } else if (!useNpx) {
+    // No npx form for this shape: fall back to the server's own name.
+    if (Array.isArray(entry.command)) entry.command = [fallbackCommand, ...entry.command.slice(1)];
+    else entry.command = fallbackCommand;
+  }
   return entry;
 }
 
@@ -79,6 +142,12 @@ export function readJsonConfig(abs) {
 /**
  * Merge a server entry into a JSON MCP config.
  *
+ * The read-merge-write runs under an exclusive lock on the config file. The
+ * write itself is atomic, but that only stops a reader seeing a half-written
+ * file — two writers still lose each other's work: one merges the archgen
+ * entry, the other merges the codegraph entry, and whichever lands last
+ * discards the first.
+ *
  * @param {string} abs absolute config path
  * @param {string} key the top-level key ('mcpServers' | 'servers' | 'mcp' | 'context_servers')
  * @param {string} serverId the entry name inside the bucket ('codegraph' | 'archgen')
@@ -87,6 +156,16 @@ export function readJsonConfig(abs) {
  * @returns {{status:'written'|'unchanged'|'skipped'|'planned'|'error', detail?:string, path?:string}}
  */
 export function writeJsonConfig(abs, key, serverId, entry, opts) {
+  const { approved, dryRun = false, root } = opts;
+  try {
+    return withFileLock(abs, () => mergeJsonConfig(abs, key, serverId, entry, opts));
+  } catch (e) {
+    return { status: 'error', detail: e.message, path: abs };
+  }
+}
+
+/** The merge itself. Runs with the config file's lock held. */
+function mergeJsonConfig(abs, key, serverId, entry, opts) {
   const { approved, dryRun = false, root } = opts;
   const { data, existed, error } = readJsonConfig(abs);
   if (error) {
@@ -108,7 +187,7 @@ export function writeJsonConfig(abs, key, serverId, entry, opts) {
   try {
     if (root) assertWithinRoot(root, abs);
     assertNotSymlink(abs);
-    writeFileAtomic(abs, JSON.stringify(obj, null, 2) + '\n');
+    writeFileAtomic(abs, JSON.stringify(obj, null, 2) + '\n', { root });
   } catch (e) {
     return { status: 'error', detail: e.message, path: abs };
   }
@@ -155,6 +234,15 @@ export function entryToToml(entry) {
  * @param {{approved: boolean, dryRun?: boolean, root?: string}} opts
  */
 export function writeTomlConfig(abs, serverId, entry, opts) {
+  try {
+    return withFileLock(abs, () => mergeTomlConfig(abs, serverId, entry, opts));
+  } catch (e) {
+    return { status: 'error', detail: e.message, path: abs };
+  }
+}
+
+/** The merge itself. Runs with the config file's lock held. */
+function mergeTomlConfig(abs, serverId, entry, opts) {
   const { approved, dryRun = false, root } = opts;
   const existed = existsSync(abs);
   let raw = '';
@@ -197,7 +285,7 @@ export function writeTomlConfig(abs, serverId, entry, opts) {
   try {
     if (root) assertWithinRoot(root, abs);
     assertNotSymlink(abs);
-    writeFileAtomic(abs, out);
+    writeFileAtomic(abs, out, { root });
   } catch (e) {
     return { status: 'error', detail: e.message, path: abs };
   }
@@ -220,6 +308,7 @@ export function writeTomlConfig(abs, serverId, entry, opts) {
  *   binPath?: string|null,
  *   fallbackCommand?: string,
  *   skipHarnesses?: string[],
+ *   targets?: string[]|null,
  * }} opts
  * @returns {{detected: string[], wired: Array<Record<string, unknown>>, skipped: Array<Record<string, unknown>>, planned: boolean}}
  */
@@ -237,14 +326,19 @@ export function wireServer(opts) {
     binPath = null,
     fallbackCommand = serverId,
     skipHarnesses = [],
+    targets = null,
   } = opts;
 
   const detected = detectHarnesses(registry, projectRoot, home);
+  // A caller that narrowed the set of harnesses must get exactly that set.
+  // The native path honoured the filter and this one did not, so a request
+  // for two harnesses wired ten.
+  const selected = targets ? detected.filter((d) => targets.includes(d.id)) : detected;
   const wantedLocations = location === 'both' ? ['global', 'project'] : [location];
   const wired = [];
   const skipped = [];
 
-  for (const d of detected) {
+  for (const d of selected) {
     if (skipHarnesses.includes(d.id)) {
       skipped.push({ harness: d.id, reason: 'skipped by request' });
       continue;
@@ -262,12 +356,17 @@ export function wireServer(opts) {
         cfg.format === 'toml'
           ? writeTomlConfig(absPath, serverId, entry, { approved, dryRun, root })
           : writeJsonConfig(absPath, cfg.key, serverId, entry, { approved, dryRun, root });
-      wired.push({ harness: d.id, location: loc, path: absPath, key: cfg.key ?? `mcp_servers.${serverId}`, ...res });
+      // The key recorded here is the one the writer ACTUALLY used. A JSON
+      // config uses the registry's top-level key; a TOML config's section is
+      // derived from the server id. Recording the registry's key instead made
+      // uninstall search for the wrong section and leave the real one behind.
+      const writtenKey = cfg.format === 'toml' ? `mcp_servers.${serverId}` : cfg.key;
+      wired.push({ harness: d.id, location: loc, path: absPath, key: writtenKey, ...res });
     }
   }
 
   return {
-    detected: detected.map((d) => d.id),
+    detected: selected.map((d) => d.id),
     wired,
     skipped,
     planned: !approved && !dryRun && wired.some((w) => w.status === 'planned'),
@@ -291,7 +390,7 @@ export function recordWiring(projectRoot, serverId, entries) {
   }
   existing.servers[serverId] = { writtenAt: new Date().toISOString(), entries };
   try {
-    writeFileAtomic(p, JSON.stringify(existing, null, 2) + '\n');
+    writeFileAtomic(p, JSON.stringify(existing, null, 2) + '\n', { root: projectRoot });
   } catch {
     /* the manifest is a convenience, never a blocker */
   }
@@ -302,9 +401,10 @@ export function recordWiring(projectRoot, serverId, entries) {
  * @param {string} projectRoot
  * @param {string} serverId
  * @param {string} [home]
+ * @param {'project'|'global'|'both'} [location] which scope to remove
  * @returns {{removed: string[], skipped: string[]}}
  */
-export function removeWiring(projectRoot, serverId, home = homedir()) {
+export function removeWiring(projectRoot, serverId, home = homedir(), location = 'both') {
   const p = join(projectRoot, '.archgen', '.mcp-wiring.json');
   let manifest = null;
   try {
@@ -320,6 +420,20 @@ export function removeWiring(projectRoot, serverId, home = homedir()) {
   for (const entry of record.entries) {
     try {
       const abs = entry.path;
+      // The scope is honoured: a request to remove the global wiring leaves
+      // the project's wiring in place.
+      if (location !== 'both' && entry.location && entry.location !== location) {
+        skipped.push(`${abs} (${entry.location} scope)`);
+        continue;
+      }
+      // The manifest is a file ON DISK in the project — repository content.
+      // Its paths are therefore untrusted: a clone could ship a manifest
+      // naming any file on the machine. A recorded path must resolve inside
+      // the project root or the user's home, or it is refused.
+      if (!pathIsWithin(abs, projectRoot) && !pathIsWithin(abs, home)) {
+        skipped.push(`${abs} (outside the project and home directories)`);
+        continue;
+      }
       if (!existsSync(abs)) {
         skipped.push(`${entry.path} (absent)`);
         continue;
@@ -336,7 +450,7 @@ export function removeWiring(projectRoot, serverId, home = homedir()) {
         }
         let next = start + 1;
         while (next < lines.length && !/^\s*\[/.test(lines[next])) next++;
-        writeFileAtomic(abs, [...lines.slice(0, start), ...lines.slice(next)].join('\n'));
+        writeFileAtomic(abs, [...lines.slice(0, start), ...lines.slice(next)].join('\n'), { root: projectRoot });
         removed.push(abs);
       } else {
         const { data } = readJsonConfig(abs);
@@ -350,7 +464,7 @@ export function removeWiring(projectRoot, serverId, home = homedir()) {
           continue;
         }
         delete bucket[serverId];
-        writeFileAtomic(abs, JSON.stringify(data, null, 2) + '\n');
+        writeFileAtomic(abs, JSON.stringify(data, null, 2) + '\n', { root: projectRoot });
         removed.push(abs);
       }
     } catch (e) {

package/src/core/mcp-server-manager.mjs

@@ -18,7 +18,6 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { wireServer, recordWiring, removeWiring } from './harness-wiring.mjs';
 import { which } from './codegraph-manager.mjs';
- './errors.mjs';
 
 export const MCP_PACKAGE = 'archgen-mcp';
 
@@ -114,8 +113,8 @@ export function wireArchgenMcp(opts) {
  * @param {string} projectRoot
  * @param {string} [home]
  */
-export function uninstallArchgenMcp(projectRoot, home = homedir()) {
-  return removeWiring(projectRoot, 'archgen', home);
+export function uninstallArchgenMcp(projectRoot, home = homedir(), location = 'both') {
+  return removeWiring(projectRoot, 'archgen', home, location);
 }
 
 /**

package/src/core/plan-coverage.mjs

@@ -5,16 +5,39 @@
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-/** @returns {string[]} error findings (empty = coverage OK) */
+/**
+ * @param {string} planDir
+ * @param {any[]} tasks
+ * @returns {{findings: string[], referenced: Set<string>, mentionedInTasks: Set<string>}}
+ *   `findings`     error findings (empty = coverage OK)
+ *   `referenced`   task ids that a plan file mentions
+ *   `mentionedInTasks` task ids another task's text mentions
+ *
+ * The sets are RETURNED, not just used internally. A consumer that needs to
+ * know which tasks are covered must read them from here: re-deriving the
+ * answer from `findings` — which are NEGATIVE — inverts it, because an
+ * uncovered task's finding names the task.
+ */
 export function checkPlanCoverage(planDir, tasks) {
   const findings = [];
-  if (!existsSync(planDir)) return [`plans dir not found: ${planDir}`];
-  const files = readdirSync(planDir).filter((f) => f.endsWith('.md'));
-  const planText = files.map((f) => readFileSync(join(planDir, f), 'utf8')).join('\n');
+  const referenced = new Set();
+  const mentionedInTasks = new Set();
+  if (!existsSync(planDir)) return { findings: [`plans dir not found: ${planDir}`], referenced, mentionedInTasks };
+  let files;
+  try {
+    files = readdirSync(planDir).filter((f) => f.endsWith('.md'));
+  } catch (e) {
+    return { findings: [`cannot read plans dir ${planDir}: ${e.message}`], referenced, mentionedInTasks };
+  }
+  let planText = '';
+  try {
+    planText = files.map((f) => readFileSync(join(planDir, f), 'utf8')).join('\n');
+  } catch (e) {
+    return { findings: [`cannot read a plan file under ${planDir}: ${e.message}`], referenced, mentionedInTasks };
+  }
 
   const taskIds = new Set(tasks.map((t) => t.id));
   // Task ids referenced in plans: bare tokens that match an existing-or-not id pattern.
-  const referenced = new Set();
   for (const t of taskIds) {
     const re = new RegExp(`\\b${escapeRe(t)}\\b`);
     if (re.test(planText)) referenced.add(t);
@@ -22,11 +45,25 @@ export function checkPlanCoverage(planDir, tasks) {
   for (const t of tasks) {
     if (!referenced.has(t.id)) findings.push(`task '${t.id}' is not mentioned in any plan file under ${planDir}`);
   }
+  // A task may also be "covered" by ANOTHER task naming it — the dependency
+  // graph documents it.
+  for (const t of tasks) {
+    for (const other of tasks) {
+      if (other?.id === t.id) continue;
+      if (mentions(other, t.id)) mentionedInTasks.add(t.id);
+    }
+  }
   // Inverse: plan mentions ids like TASK-xx not present in tasks.yaml.
   for (const m of planText.matchAll(/\b[A-Z][A-Z0-9]+-[0-9]+\b/g)) {
     if (!taskIds.has(m[0])) findings.push(`plan references unknown task id '${m[0]}' (not in tasks.yaml)`);
   }
-  return findings;
+  return { findings, referenced, mentionedInTasks };
+}
+
+/** Does any task reference `id` in its artifacts / acceptance text? */
+function mentions(task, id) {
+  const hay = JSON.stringify([task?.artifacts ?? [], task?.acceptance ?? [], task?.title ?? '']);
+  return hay.includes(id);
 }
 
 function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/core/plan-grapher.mjs

@@ -85,10 +85,10 @@ function bfsDistances(start, adjacency) {
  * @param {string} input
  * @returns {{root: string, slug: string, tasksFile: string}}
  */
-export function resolvePlanScope(input) {
+export function resolvePlanScope(input, projectRoot = null) {
   let scoped;
   try {
-    scoped = resolveSlugInput(input);
+    scoped = resolveSlugInput(input, projectRoot);
   } catch (e) {
     if (e instanceof ScopeError) throw invalidInput(`plan-graph: ${e.message}`, { input });
     throw invalidInput(`cannot read ${input} (missing or unreadable)`, { input });
@@ -101,7 +101,7 @@ export function resolvePlanScope(input) {
  * @param {string} input slug dir or tasks.yaml path
  */
 function loadPlan(input) {
-  const { root, slug, tasksFile } = resolvePlanScope(input);
+  const { root, slug, tasksFile } = resolvePlanScope(input, opts.projectRoot ?? null);
 
   let raw;
   try {

package/src/core/platform-caps.mjs

@@ -67,12 +67,19 @@ export function detectHarness(registry, opts) {
   return { detected: found, primary: found[0], capabilities: platformCapabilities(registry, found[0].id) };
 }
 
-/** The rank of a harness in the detection order (unknown → last). */
+/**
+ * The rank of a harness in the detection order (unknown → last).
+ *
+ * The match is EXACT. A prefix match ranked `code` against `codex` — two
+ * different harnesses — and whichever came first in the registry won, so
+ * the detected platform depended on the registry's ordering rather than on
+ * what is actually installed.
+ */
 function rank(id, order) {
   const keys = Object.keys(order);
   const i = keys.findIndex((k) => {
     const clean = k.replace(/^\./, '').replace(/\/$/, '').replace(/\.json$/, '');
-    return clean === id || clean.startsWith(id);
+    return clean === id;
   });
   return i === -1 ? keys.length : i;
 }

package/src/core/resume-snapshot.mjs

@@ -21,6 +21,19 @@ import { writeFileAtomic } from './fs-safety.mjs';
  * @param {any[]} waves resolved waves
  * @returns {string}
  */
+/**
+ * The wave execution resumes at, 1-based.
+ *
+ * When every wave is done there is no NEXT wave, so the resume point is the
+ * LAST wave — not one past the end of the list. The file and the tool
+ * response used two different formulas, so the snapshot could say "wave 3 of
+ * 2" while the response said wave 2.
+ */
+export function resumeWaveIndex(waves, statusOf) {
+  const active = waves.findIndex((w) => w.some((t) => statusOf(t) !== 'done'));
+  return active === -1 ? waves.length : active + 1;
+}
+
 export function renderResume(slug, tasks, waves) {
   const byId = new Map(tasks.map((t) => [t?.id, t]));
   const statusOf = (t) => String(t?.status ?? 'pending');
@@ -32,14 +45,13 @@ export function renderResume(slug, tasks, waves) {
 
   // The first wave that still has work in it is where execution resumes.
   const activeWaveIndex = waves.findIndex((w) => w.some((t) => statusOf(t) !== 'done'));
-  const waveIndex = activeWaveIndex === -1 ? waves.length : activeWaveIndex;
   const remaining = waves[activeWaveIndex] ?? [];
 
   const lines = [];
   lines.push(`# Resume — ${slug}`);
   lines.push('');
   lines.push(`- slug: ${slug}`);
-  lines.push(`- wave: ${waveIndex + 1} of ${waves.length}`);
+  lines.push(`- wave: ${resumeWaveIndex(waves, statusOf)} of ${waves.length}`);
   lines.push(`- done: ${done.length ? done.join(', ') : 'none'}`);
   lines.push(`- failed: ${failed.length ? failed.join(', ') : 'none'}`);
   lines.push(`- blocked: ${blocked.length ? blocked.join(', ') : 'none'}`);
@@ -91,13 +103,13 @@ export function writeResumeSnapshot(slugDir, waves) {
   const body = renderResume(slug, tasks, waves);
   const out = join(slugDir, '.agent', 'resume.md');
   mkdirSync(dirname(out), { recursive: true });
-  writeFileAtomic(out, body);
+  writeFileAtomic(out, body, { root: slugDir });
 
   const statusOf = (t) => String(t?.status ?? 'pending');
   const activeWaveIndex = waves.findIndex((w) => w.some((t) => statusOf(t) !== 'done'));
   return {
     path: out,
-    waveIndex: activeWaveIndex === -1 ? waves.length : activeWaveIndex + 1,
+    waveIndex: resumeWaveIndex(waves, statusOf),
     done: tasks.filter((t) => statusOf(t) === 'done').map((t) => t.id),
     failed: tasks.filter((t) => statusOf(t) === 'failed').map((t) => t.id),
     blocked: tasks.filter((t) => statusOf(t) === 'blocked').map((t) => t.id),

package/src/core/scope.mjs

@@ -19,7 +19,7 @@
 //   - Everything else throws ScopeError. Missing/unreadable inputs surface as
 //     the underlying realpath/stat error so callers keep their own messages.
 import { realpathSync, statSync } from 'node:fs';
-import { basename, dirname, sep } from 'node:path';
+import { basename, dirname, resolve, sep } from 'node:path';
 
 export class ScopeError extends Error {
   constructor(input) {
@@ -34,7 +34,19 @@ function segmentsOf(abs) {
   return process.platform === 'win32' ? abs.split(/[\\/]+/).filter(Boolean) : abs.split(sep).filter(Boolean);
 }
 
-export function resolveSlugInput(rawInput) {
+/**
+ * Resolve a path to the artifact space it names.
+ *
+ * A path qualifies when it is a `.archgen/<slug>/` directory (or the
+ * `tasks.yaml` inside one). When `root` is given, the artifact space must
+ * also be INSIDE that root — otherwise the gate would accept
+ * `/somewhere/else/.archgen/demo`, which is not this project's artifacts.
+ *
+ * @param {string} rawInput
+ * @param {string|null} [root] the project root the artifact space must be inside
+ * @returns {{kind: 'dir'|'tasks', root: string, slug: string}}
+ */
+export function resolveSlugInput(rawInput, root = null) {
   let real;
   try {
     real = realpathSync(rawInput); // follows symlinks: judge the TARGET, not the link
@@ -53,13 +65,35 @@ export function resolveSlugInput(rawInput) {
     const depthFromArchgen = parts.length - 1 - i; // segments after this `.archgen`
     if (st.isDirectory() && depthFromArchgen === 1) {
       // (a) `<...>/.archgen/<slug>` — the slug dir itself
-      return { kind: 'dir', root: real, slug: parts[i + 1] };
+      const slugRoot = real;
+      if (root && !isWithin(slugRoot, root)) throw new ScopeError(rawInput);
+      return { kind: 'dir', root: slugRoot, slug: parts[i + 1] };
     }
     if (st.isFile() && basename(real) === 'tasks.yaml' && depthFromArchgen === 2) {
       // (b) `<...>/.archgen/<slug>/tasks.yaml` — direct tasks.yaml mode
-      const root = dirname(real);
-      return { kind: 'tasks', root, slug: basename(root) };
+      const slugRoot = dirname(real);
+      if (root && !isWithin(slugRoot, root)) throw new ScopeError(rawInput);
+      return { kind: 'tasks', root: slugRoot, slug: basename(slugRoot) };
     }
   }
   throw new ScopeError(rawInput);
 }
+
+/**
+ * True when `abs` is inside `root`.
+ *
+ * The REAL comparison is authoritative when both paths exist: it is what
+ * catches a symlinked parent pointing out of the tree. The lexical
+ * comparison only stands in when the target does not exist yet.
+ */
+function isWithin(abs, root) {
+  const resolvedRoot = resolve(root);
+  const resolved = resolve(abs);
+  try {
+    const realRoot = realpathSync(resolvedRoot);
+    const real = realpathSync(resolved);
+    return real === realRoot || real.startsWith(realRoot + sep);
+  } catch {
+    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + sep);
+  }
+}

package/src/core/status-mutator.mjs

@@ -17,7 +17,7 @@
 import { readFileSync } from 'node:fs';
 import { parseYaml, stringifyYaml } from './yaml.mjs';
 import { conflict, invalidInput } from './errors.mjs';
-import { writeFileAtomic } from './fs-safety.mjs';
+import { writeFileAtomic, withFileLock } from './fs-safety.mjs';
 
 export const STATUSES = ['pending', 'ready', 'running', 'blocked', 'done', 'failed'];
 
@@ -32,6 +32,23 @@ export function detectEol(raw) {
   return crlfCount > loneLfCount ? '\r\n' : '\n';
 }
 
+/**
+ * Do two task ids name the same task?
+ *
+ * Textually equal ids match. A NUMERIC id also matches by value, because
+ * YAML resolves `id: 007` to the number 7 — the agent holds the text it
+ * read and the parser holds the value. A QUOTED id is text and matches
+ * exactly: `id: "7"` and "07" are different tasks.
+ */
+export function sameId(a, b) {
+  const sa = String(a ?? '');
+  const sb = String(b ?? '');
+  if (sa === sb) return true;
+  if (typeof a !== 'number') return false;
+  const nb = Number(sb);
+  return sb.trim() !== '' && Number.isFinite(nb) && a === nb;
+}
+
 /**
  * Set a task's status atomically.
  *
@@ -48,6 +65,15 @@ export function setTaskStatus(file, taskId, nextStatus, opts = {}) {
     throw invalidInput(`invalid status '${nextStatus}' (allowed: ${STATUSES.join('|')})`, { status: nextStatus });
   }
 
+  // The whole read-modify-write runs under an exclusive lock. Atomic writes
+  // keep a reader from seeing a half-written file, but two writers still
+  // lose each other's changes without this: parallel workers in one wave
+  // each read the same bytes and each write its own status over the other's.
+  return withFileLock(file, () => mutateStatus(file, taskId, nextStatus, force));
+}
+
+/** The read-modify-write itself. Runs with the file's lock held. */
+function mutateStatus(file, taskId, nextStatus, force) {
   let raw;
   try {
     raw = readFileSync(file, 'utf8');
@@ -71,7 +97,11 @@ export function setTaskStatus(file, taskId, nextStatus, opts = {}) {
   const tasks = data?.tasks;
   if (!Array.isArray(tasks)) throw invalidInput(`${file}: missing 'tasks:' sequence`, { file });
 
-  const task = tasks.find((t) => t && t.id === taskId);
+  // Ids are matched as TEXT, and — when both sides are numeric — as NUMBERS.
+  // YAML reads `id: 007` as the number 7, so the id the agent holds ("007")
+  // and the id the file holds (7) are different strings for the same task.
+  // A strict comparison made such a task permanently unaddressable.
+  const task = tasks.find((t) => t && sameId(t.id, taskId));
   if (!task) throw invalidInput(`task '${taskId}' not found in ${file}`, { file, taskId });
 
   const prev = task.status ?? 'pending';
@@ -82,9 +112,10 @@ export function setTaskStatus(file, taskId, nextStatus, opts = {}) {
     );
   }
 
+  const changed = prev !== nextStatus;
   task.status = nextStatus;
   const content = stringifyYaml(data, comments, { eol });
   writeFileAtomic(file, content);
 
-  return { taskId, from: prev, to: nextStatus, changed: true, file };
+  return { taskId, from: prev, to: nextStatus, changed, file };
 }