@dtlabs/ai-toolkit 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -1,4 +1,25 @@
 ## 0.1.4 (2026-07-21)
+## [0.17.3](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.2...v0.17.3) (2026-10-12)
+
+
+### Bug Fixes
+
+* **execution-ledger:** close PID-reuse gap in lock-staleness liveness check ([4a9a365](https://github.com/dtlab-tech/ai-toolkit/commit/4a9a3652bf8e7844accff46851b2e1286e24c0d7))
+* **task-executor:** session-list clutter and PID-reuse lock-liveness gap ([e000a6f](https://github.com/dtlab-tech/ai-toolkit/commit/e000a6faa2e75eac5bb65069eb9b37b102a14cf8))
+* **task-executor:** stop every dispatch from cluttering the Claude Code session list ([8676d66](https://github.com/dtlab-tech/ai-toolkit/commit/8676d66157bceeafb7fa225cabeb8a666dbac955))
+
+## [0.17.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.1...v0.17.2) (2026-10-12)
+
+
+### Bug Fixes
+
+* **am-phase1:** resume already-landed assessor output after a crash ([057916e](https://github.com/dtlab-tech/ai-toolkit/commit/057916e975cca4e98f838000309546bf2ceb8787))
+* **cli:** harden installer/CLI crash paths and fix several silent-failure bugs ([f93d18a](https://github.com/dtlab-tech/ai-toolkit/commit/f93d18a04cbea5a8d393102e3125170b170b6ae2))
+* **execution-ledger:** retry rename on transient EPERM instead of unlinking destination ([fc07a4c](https://github.com/dtlab-tech/ai-toolkit/commit/fc07a4c1fdad0f953dd38f7027bec96b0b8807c2))
+* **gaia-install-toolkit:** resolve self-contradiction on editing settings.local.json ([b385325](https://github.com/dtlab-tech/ai-toolkit/commit/b38532586f4661ef788b1178013991b81ecc0ea5))
+* harden workflow gates, CLI installer, and ledger durability ([a9e8b65](https://github.com/dtlab-tech/ai-toolkit/commit/a9e8b6509dea2ead6d63277835254eda8ba3e5e0))
+* **pm-phase:** bind Gate 1 approval to doc content, not just its text ([8f5b2f1](https://github.com/dtlab-tech/ai-toolkit/commit/8f5b2f1cbaa9262d1f11c559302b798dedcf4b4f))
+
 ## [0.17.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.0...v0.17.1) (2026-10-08)
 
 

package/bin/cli.js

@@ -322,8 +322,10 @@ function writeManifest(destRoot, fileList, installationMode, fileHashes) {
   try {
     ensureDir(manifestPath);
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    return true;
   } catch (err) {
     console.log(dim(`Warning: could not write manifest — ${err.message}`));
+    return false;
   }
 }
 
@@ -372,11 +374,19 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
   let keptCount    = 0;
 
   if (!dryRun) {
+    // A failed orphan removal (e.g. a locked file) must not abort the whole
+    // install — new/modified files still need copying and the manifest still
+    // needs writing. Warn and keep going; the orphan is left in place for a
+    // future run to retry.
     if (force) {
       for (const orphan of existingOrphans) {
-        moveToTrash(destRoot, orphan);
-        removedCount++;
-        console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+        try {
+          moveToTrash(destRoot, orphan);
+          removedCount++;
+          console.log(`     ${clr('red', '∅')} ${dim(orphan)}`);
+        } catch (err) {
+          console.log(`     ${clr('yellow', '⚠')} Could not remove ${dim(orphan)} — ${err.message}`);
+        }
       }
     } else {
       for (const orphan of existingOrphans) {
@@ -384,9 +394,13 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
         if (!fs.existsSync(fullPath)) continue;
         const ok = await askConfirm(`  Move to trash  ${clr('red', orphan)}?`);
         if (ok) {
-          moveToTrash(destRoot, orphan);
-          console.log(`     ${clr('green', '✔')} Moved to trash\n`);
-          removedCount++;
+          try {
+            moveToTrash(destRoot, orphan);
+            console.log(`     ${clr('green', '✔')} Moved to trash\n`);
+            removedCount++;
+          } catch (err) {
+            console.log(`     ${clr('yellow', '⚠')} Could not move to trash — ${err.message}\n`);
+          }
         } else {
           console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
           keptCount++;
@@ -432,8 +446,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
 
   if (modified.length === 0) {
     console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
-    writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
-    return;
+    return writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
   }
 
   if (force) {
@@ -443,8 +456,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
       fs.copyFileSync(e.src, e.dest);
       console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
     }
-    writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
-    return;
+    return writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
   }
 
   console.log(`  ${clr('yellow', 'These files differ from the toolkit version — decide for each:')}\n`);
@@ -472,7 +484,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
     `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
   );
 
-  writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
+  return writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
 }
 
 // Compute SHA-256 for every relative path in relPaths under destRoot.
@@ -1804,10 +1816,15 @@ async function installLocal(targetDir, force, dryRun = false) {
     { src: path.join(packageRoot, 'docs'),      dest: path.join(targetDir, 'docs') },
     { src: path.join(packageRoot, 'CLAUDE.md'), dest: path.join(targetDir, 'CLAUDE.md') },
   ];
-  await runInstall(`local project`, mappings, force, targetDir, dryRun, 'local');
+  const manifestWritten = await runInstall(`local project`, mappings, force, targetDir, dryRun, 'local');
   if (dryRun) return;
   writeInstalledVersion(targetDir);
-  console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  if (manifestWritten === false) {
+    console.log(`  ${clr('yellow', '⚠')}  ${bold('Install complete, but the manifest could not be written.')}\n` +
+      `     Reinstall/orphan-cleanup detection will not see these files until it is.\n`);
+  } else {
+    console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  }
   checkSpawnDepth(targetDir);
   console.log(divider());
   console.log(`\n  ${bold('Next steps:')}`);
@@ -1839,10 +1856,15 @@ async function installGlobal(force, dryRun = false, homeOverride = undefined) {
       { src: path.join(packageRoot, 'docs'),             dest: path.join(target, 'docs') },
       { src: path.join(packageRoot, 'CLAUDE.global.md'), dest: path.join(target, 'CLAUDE.md') },
     ];
-    await runInstall('global Claude folder', mappings, force, homedir, dryRun, 'global');
+    const manifestWritten = await runInstall('global Claude folder', mappings, force, homedir, dryRun, 'global');
     if (dryRun) return;
     writeInstalledVersion(homedir);
-    console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    if (manifestWritten === false) {
+      console.log(`  ${clr('yellow', '⚠')}  ${bold('Global install complete, but the manifest could not be written.')}\n` +
+        `     Reinstall/orphan-cleanup detection will not see these files until it is.\n`);
+    } else {
+      console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    }
     checkSpawnDepth(homedir);
     console.log(divider());
     console.log(`\n  ${bold('Next steps:')}`);
@@ -1891,7 +1913,9 @@ async function main() {
     if (sub === '--project') {
       await installLocal(argv[2] || '.', force, dryRun);
     } else if (sub === '--global') {
-      await installGlobal(force, dryRun);
+      const homeIdx = argv.indexOf('--home');
+      const homeOverride = homeIdx !== -1 ? argv[homeIdx + 1] : undefined;
+      await installGlobal(force, dryRun, homeOverride);
     } else {
       // No sub-flag: install into current directory (same as bare invocation)
       await installLocal(sub && !sub.startsWith('-') ? sub : '.', force, dryRun);
@@ -1955,6 +1979,10 @@ async function main() {
     const home       = homeIdx    !== -1 ? remaining[homeIdx    + 1] : undefined;
     runDoctorAgents({ projectDir, home });
     process.exit(0);
+  } else if (argv[0] === 'doctor') {
+    process.stderr.write(`Unknown doctor subcommand: ${argv[1] || '(none)'}\n` +
+      'Available: doctor resolution, doctor agents\n');
+    process.exit(1);
   } else if (argv[0] === 'validate-purity') {
     runValidatePurity(argv[1]);
   } else if (argv[0] === 'resolve-asset') {
@@ -2102,7 +2130,10 @@ async function main() {
     process.exit(0);
   } else if (argv[0] === 'resolve-features-root') {
     try {
-      const resolved = resolveFeaturesRoot(process.cwd());
+      const remaining = argv.slice(1);
+      const overrideIdx = remaining.indexOf('--features-root');
+      const featuresRoot = overrideIdx !== -1 ? remaining[overrideIdx + 1] : undefined;
+      const resolved = resolveFeaturesRoot(process.cwd(), { featuresRoot });
       process.stdout.write(resolved + '\n');
       process.exit(0);
     } catch (err) {
@@ -2495,17 +2526,31 @@ async function handleAgentsCommand(argv) {
     const effectiveHome    = home !== undefined ? path.resolve(home) : os.homedir();
     const effectiveProject = path.resolve(projectDir);
 
-    // Locate the active manifest (project-scoped takes precedence over global).
+    // Locate the active manifest. Both scopes present is ambiguous — matches
+    // agentRegistry.resolveAgent/listRegisteredAgents' own 'conflict' handling
+    // for the same dual-manifest case, rather than silently preferring project.
     const projectManifestPath = path.join(effectiveProject, '.claude', MANIFEST_FILE);
     const globalManifestPath  = path.join(effectiveHome,    '.claude', MANIFEST_FILE);
+    const hasProjectManifest  = fs.existsSync(projectManifestPath);
+    const hasGlobalManifest   = fs.existsSync(globalManifestPath);
+
+    if (hasProjectManifest && hasGlobalManifest) {
+      process.stdout.write(
+        JSON.stringify({ status: 'conflict', candidates: [], missing: [],
+          error: 'Both local and global toolkit installations found; installation is ambiguous. ' +
+                 'Remove one installation or reinstall to a single scope.' }, null, 2) + '\n'
+      );
+      process.exitCode = 0;
+      return;
+    }
 
     let installRoot    = null;
     let manifestData   = null;
 
-    if (fs.existsSync(projectManifestPath)) {
+    if (hasProjectManifest) {
       installRoot  = effectiveProject;
       manifestData = readJsonSafe(projectManifestPath);
-    } else if (fs.existsSync(globalManifestPath)) {
+    } else if (hasGlobalManifest) {
       installRoot  = effectiveHome;
       manifestData = readJsonSafe(globalManifestPath);
     }
@@ -2934,7 +2979,10 @@ async function handleExecutorCommand(argv) {
 // When required as a module (e.g., by Jest), skip main() and export pure
 // functions so they can be unit-tested without side effects.
 if (require.main === module) {
-  main();
+  main().catch(err => {
+    console.error(`\n  ${clr('red', '✖')}  ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  });
 } else {
   module.exports = {
     fileHash,
@@ -2947,6 +2995,7 @@ if (require.main === module) {
     moveToTrash,
     trashTimestamp,
     writeManifest,
+    runInstall,
     CANONICAL_ALLOW,
     CANONICAL_ASK,
     commandToPermission,

package/docs/task-executor-bootstrap.md

@@ -64,6 +64,32 @@ always throws `NOT_IMPLEMENTED` (exit 1, attributed to `US-06-TASK-BE-02`); unti
 deeper per-attempt evidence inspection means using `reconcile`/`resume`, both fully implemented
 and reporting each task's classification.
 
+**If the run ends up `blocked`: do not default to restarting from scratch.** `execute()` always
+mints a brand-new `runId` and resets every task to `pending` — a plain `start` on the same feature
+re-dispatches real, budget-consuming agents against tasks that already succeeded, re-proving work
+that is already correct and already committed. Found costing real budget on a real run across
+multiple restarts before anyone thought to check for an alternative: the alternative already
+exists, it is just never suggested at the one moment it matters.
+
+Before restarting, check whether `replan` + `start --from-replan-run-id` applies instead (full
+contract in `docs/task-executor-cli.md`'s `replan`/`start` sections):
+
+1. Confirm no worker from the blocked run is still live (`replan` itself refuses otherwise via
+   `LIVE_WORKER_BLOCKS_REPLAN` — this is enforced, not just advised).
+2. Call `replan` against the blocked run with a `--task-mapping-json` that maps every already-
+   `checkpointed`/`integrated` task to itself (or to its corrected ID, if the Work Breakdown
+   genuinely changed) — the successor plan does **not** need to differ from the original; "same
+   plan, just let me continue" is a valid, intended use, not only "the plan changed".
+3. Start the successor run with `--from-replan-run-id <the-blocked-run's-id>`. Every task
+   `replan` marked `carriesCompletion: true` is seeded straight to `checkpointed` — no
+   re-dispatch, no new commit, no re-spent budget — and only the tasks that genuinely still need
+   work are actually dispatched.
+
+This does **not** help a task that was completed by hand outside the executor entirely (direct
+subagent dispatch, no executor run ever recorded it) — `replan` can only carry forward evidence
+the executor itself already checkpointed. For that gap, see section 4c below
+("`resume()`/`reconcile()` only inspect and report").
+
 For the full flag reference, exit-code table, and JSON result schemas of every subcommand
 (`start`, `status`, `diagnose`, `stop`, `reconcile`, `resume`, `replan`), see
 `docs/task-executor-cli.md` — this document intentionally does not restate that contract.
@@ -205,6 +231,13 @@ the interrupted run will automatically finish its remaining tasks. `execute()` a
 brand-new run (a fresh `runId`, all tasks reset to pending); there is no run loop wired into
 `resume()`.
 
+**Update:** this gap now has a real, explicit (never automatic) partial workaround for the
+executor's own already-checkpointed work — see section 1's "If the run ends up `blocked`"
+guidance above (`replan` + `start --from-replan-run-id`). It still does not cover work completed
+entirely outside the executor (direct subagent dispatch that never recorded an attempt) — there
+is still no way to adopt that into the evidence trail short of a human/agent confirming it and
+deciding what to do by hand.
+
 ### d. Dormant concurrency gap in `dispatchTaskAttempt` (must be resolved before N>1 wiring)
 
 Confirmed by US-08-TASK-TEST-01 (`tests/task-executor/parallel.test.js`, commit `2f06883`),

package/lib/agent-registry.js

@@ -542,7 +542,12 @@ function _provenanceGuard(projectDir, agentId, platform, homeDir) {
       platform:   platform,
       nativeName: nativeName,
       status:     'manifest-missing',
-      error:      'No toolkit installation found; manifest absent at both project and global scope.',
+      // Precise claim: only the manifest is confirmed absent. Payload files or a
+      // version stamp may still be on disk (isToolkitInstalled in bin/cli.js checks
+      // those too) — this function cannot read agent registration data without a
+      // manifest, so it reports exactly that, not a broader "nothing is installed".
+      error:      'No installation manifest found at either project or global scope; ' +
+                  'agent registration data cannot be read.',
     };
   }
 

package/lib/execution-ledger.js

@@ -4,6 +4,10 @@ const fs     = require('fs');
 const path   = require('path');
 const os     = require('os');
 const crypto = require('crypto');
+// Namespaced (not destructured) so tests can jest.spyOn(ownership, '_queryProcessStartTimeSync')
+// — a destructured reference would capture the original function at require
+// time and bypass any later spy on the module's own export.
+const ownership = require('./task-executor/ownership');
 
 // ── Internal I/O helpers (stubs — implemented by INFRA-TASK-BE-03) ──────────
 
@@ -58,15 +62,59 @@ function _writeLedger(ledgerPath, entries) {
     throw err;
   }
 
-  try {
-    fs.renameSync(tmpPath, ledgerPath);
-  } catch (err) {
-    if (err.code === 'EEXIST' || err.code === 'EPERM') {
-      try { fs.unlinkSync(ledgerPath); } catch (_) {}
+  // Never unlink ledgerPath before/instead of the rename as a recovery step:
+  // fs.renameSync already atomically replaces an existing destination on every
+  // platform this runs on (POSIX rename(2); Windows via MoveFileEx with
+  // REPLACE_EXISTING). An EEXIST/EPERM-triggered unlink-then-rename "fallback"
+  // used to live here — if the process died in the window between that unlink
+  // succeeding and the rename completing (or if the rename then failed for an
+  // unrelated reason), the ledger file was simply gone, and _readLedger's
+  // ENOENT handling (above) treats a missing file as "empty, no error" — real,
+  // silent data loss, worse than the corrupt-ledger path this same module
+  // guards carefully via _backupCorruptFile.
+  //
+  // The EPERM/EEXIST this used to react to is real and transient, though
+  // (confirmed against a genuine, unmocked failure under parallel Windows test
+  // load, same "known environmental characteristic" docs/task-executor-
+  // bootstrap.md already documents for store.js's own rename) — something
+  // else briefly holds a handle on ledgerPath (antivirus, indexing, a
+  // concurrent reader). Retrying the SAME rename a bounded number of times
+  // with a short backoff gives that window a chance to close WITHOUT ever
+  // creating a moment where ledgerPath doesn't exist, unlike the old
+  // unlink-first approach.
+  let lastErr;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
       fs.renameSync(tmpPath, ledgerPath);
-    } else {
-      try { fs.unlinkSync(tmpPath); } catch (_) {}
-      throw err;
+      lastErr = null;
+      break;
+    } catch (err) {
+      lastErr = err;
+      if (err.code !== 'EPERM' && err.code !== 'EEXIST') break;
+      _sleepSync(20);
+    }
+  }
+  if (lastErr) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw lastErr;
+  }
+  _fsyncDirSync(dir);
+}
+
+// Best-effort directory fsync after a rename — identical to, and genuinely
+// mirroring this time, lib/task-executor/store.js's own _fsyncDirSync.
+function _fsyncDirSync(dir) {
+  let dfd;
+  try {
+    dfd = fs.openSync(dir, 'r');
+    fs.fsyncSync(dfd);
+  } catch (_) {
+    // Directory-handle fsync is not supported on every platform/filesystem
+    // (notably Windows). Best-effort only — file fsync + rename already
+    // happened before this call.
+  } finally {
+    if (dfd !== undefined) {
+      try { fs.closeSync(dfd); } catch (_) {}
     }
   }
 }
@@ -87,6 +135,78 @@ function _sleepSync(ms) {
   while (Date.now() < end) { /* busy-wait for synchronous cross-process backoff */ }
 }
 
+// This process's own OS-level start time, probed via ownership.js's
+// host:pid:startTime technique exactly ONCE per process lifetime (not once
+// per lock acquisition) and cached forever after — a process's own start
+// time never changes. Recording this in every lock token we write is what
+// later lets a CONTENDED acquisition attempt tell "the recorded owner is
+// still running" apart from "a recycled pid now belongs to someone else"
+// (see _confirmSameOwnerProcess). `undefined` means not yet probed;
+// `null` means the probe was inconclusive (non-Windows, or it failed) —
+// callers must treat that the same as "no evidence either way", never as
+// proof of death.
+let _selfProcessStartTime;
+function _getSelfProcessStartTime() {
+  if (_selfProcessStartTime === undefined) {
+    const probe = ownership._queryProcessStartTimeSync(process.pid);
+    _selfProcessStartTime = (probe && probe.found) ? probe.startTime : null;
+  }
+  return _selfProcessStartTime;
+}
+
+// Per-nonce verdict cache for the PID-reuse check below. A lock's nonce is
+// unique per acquisition (crypto.randomBytes at write time), so a verdict
+// for a given nonce never goes stale: either the recorded owner is
+// confirmed still the same OS process (forever, until it exits), or it was
+// already confirmed to be a different process that reused the pid
+// (forever — that fact doesn't change either). Caching here is what keeps
+// the expensive OS probe to once per contended lock episode instead of once
+// per ~100ms poll in _acquireLock's retry loop. Bounded defensively; a
+// single process is not expected to ever accumulate more than a handful of
+// distinct contended nonces in practice.
+const _ownerProcessVerdictCache = new Map();
+
+// Resolves whether `token.pid` is still the SAME OS process that wrote this
+// lock, using the host:pid:startTime identity technique (same one
+// ownership.js already uses for task leases) — `process.kill(pid, 0)` alone
+// cannot tell a still-alive original owner apart from an unrelated process
+// that reused a recycled pid after the owner crashed.
+//
+// Returns:
+//   true  — confirmed same process (startTime probes match)
+//   false — confirmed a DIFFERENT process now holds this pid (mismatch)
+//   null  — inconclusive (non-Windows, probe failed, or token predates this
+//           field) — caller must fall back to trusting process.kill() alone,
+//           exactly like before this check existed; never treated as death.
+function _confirmSameOwnerProcess(token) {
+  if (typeof token.processStartTime !== 'string' || !token.nonce) return null;
+
+  const cached = _ownerProcessVerdictCache.get(token.nonce);
+  if (cached !== undefined) return cached;
+
+  const probe = ownership._queryProcessStartTimeSync(token.pid);
+  // Inconclusive probe (non-Windows, or the query failed) or the OS
+  // confirms no such pid despite process.kill() saying alive (a narrow
+  // race): do not cache — there is nothing stable to remember, and a
+  // later retry might get a conclusive answer.
+  if (!probe) return null;
+  if (!probe.found) return null;
+
+  const verdict = probe.startTime === token.processStartTime;
+  if (_ownerProcessVerdictCache.size > 500) _ownerProcessVerdictCache.clear();
+  _ownerProcessVerdictCache.set(token.nonce, verdict);
+  return verdict;
+}
+
+// Test-only reset: both caches are intentionally process-lifetime-scoped in
+// production (see their own comments for why), which would otherwise leak
+// a mocked _queryProcessStartTimeSync's behavior across unrelated test cases
+// sharing the same Jest worker process.
+function _resetOwnerProcessCaches() {
+  _selfProcessStartTime = undefined;
+  _ownerProcessVerdictCache.clear();
+}
+
 function _acquireLock(lockPath, opts) {
   const deadlineMs = (opts && opts.deadlineMs != null) ? opts.deadlineMs : 5000;
   const retryIntervalMs = (opts && opts.retryIntervalMs != null) ? opts.retryIntervalMs : 100;
@@ -98,7 +218,12 @@ function _acquireLock(lockPath, opts) {
       fd = fs.openSync(lockPath, 'wx');
       const nonce = crypto.randomBytes(16).toString('hex');
       const startedAt = new Date().toISOString();
-      const ownerToken = { pid: process.pid, startedAt, nonce };
+      // processStartTime: this process's own OS start time (cached once per
+      // process lifetime, see _getSelfProcessStartTime) — null on non-Windows
+      // or when the probe is unavailable, matching ownership.js's own
+      // null-means-inconclusive convention. Lets a later contended acquirer
+      // tell "still us" apart from "a recycled pid, now someone else".
+      const ownerToken = { pid: process.pid, startedAt, nonce, processStartTime: _getSelfProcessStartTime() };
       fs.writeSync(fd, JSON.stringify(ownerToken));
       fs.fsyncSync(fd);
       fs.closeSync(fd);
@@ -226,7 +351,15 @@ function _isLockStale(content, stat) {
       }
     }
 
-    if (ownerAlive) {
+    // process.kill(pid, 0) alone cannot tell a still-alive original owner
+    // apart from an unrelated process that reused a recycled pid after the
+    // owner crashed. _confirmSameOwnerProcess returns false only when it has
+    // positive OS evidence that today's occupant of this pid started at a
+    // different time than the token recorded — a confirmed PID reuse, not a
+    // guess. true or null (inconclusive) both fall through to the original
+    // "trust process.kill()" behavior, so nothing regresses on non-Windows
+    // or for locks written before this field existed.
+    if (ownerAlive && _confirmSameOwnerProcess(token) !== false) {
       return 'live';
     }
 
@@ -783,6 +916,9 @@ module.exports = {
   _acquireLock,
   _releaseLock,
   _isLockStale,
+  _confirmSameOwnerProcess,
+  _getSelfProcessStartTime,
+  _resetOwnerProcessCaches,
   _validateMetadata,
   _extractStoredMetadata,
   _metadataEqual,

package/lib/task-executor/index.js

@@ -600,9 +600,16 @@ async function dispatchTaskAttempt(args) {
 
   // 4. Only now: dispatch the verified agent.
   const prompt = typeof args.prompt === 'string' ? args.prompt : _buildTaskPrompt(task);
+  // --no-session-persistence: this dispatch is a one-shot --print invocation
+  // that is never resumed (no code path in this codebase passes --resume /
+  // --continue / --session-id for a task-executor spawn; replan/resume
+  // re-dispatch with a fresh prompt, never reattach to a prior Claude
+  // conversation), so a saved, resumable session transcript has no purpose
+  // here — only cost: every dispatch would otherwise accumulate as its own
+  // entry in the user's Claude Code session list.
   const baseSpawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
-    : ['--print', '--output-format', 'json', '--agent', identity.nativeName].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
+    : ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
   // Append the same processIdentity tag already persisted above as one extra
   // trailing argv element, so it appears verbatim in the spawned process's
   // own command line — this is what makes _findLiveTaggedProcess's later OS
@@ -905,7 +912,7 @@ async function runReview(args) {
   const prompt = _buildReviewPrompt(task, diff);
   const spawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
-    : ['--print', '--output-format', 'json', '--agent', identity.nativeName].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
+    : ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
   const spawnResult = await claudeProcess.spawnClaudeAgent({
     claudePath: args.claudePath,
     args: spawnArgs,

package/lib/task-executor/ownership.js

@@ -587,4 +587,10 @@ module.exports = {
   reclaimLease,
   checkOwnerLiveness,
   createOwnershipGuard,
+  // Exported for execution-ledger.js's lock-staleness check (US-xx liveness
+  // parity): the same host:pid:startTime identity technique proven here is
+  // the only reliable defense against a recycled PID being misread as the
+  // original lock owner. See execution-ledger.js's own comment at its call
+  // site for why this is only invoked lazily/cached there, never per-poll.
+  _queryProcessStartTimeSync,
 };

package/lib/workflow-control.js

@@ -139,7 +139,12 @@ function createControl(options) {
     const identity = await resolve(id);
     const definition = definitionFields(read(identity.path));
     return activity(opts.label || id, async () => {
-      const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName];
+      // --no-session-persistence: this worker call is a one-shot --print
+      // invocation that is never resumed, so a saved session transcript has
+      // no purpose — only cost, accumulating as a stray entry in the user's
+      // Claude Code session list (see lib/task-executor/index.js's dispatch
+      // call sites for the same reasoning).
+      const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'];
       if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
       if (options.workerMaxBudgetUsd != null) cliArgs.push('--max-budget-usd', String(options.workerMaxBudgetUsd));
       const outputs = opts.outputs || [];
@@ -286,6 +291,10 @@ function createControl(options) {
     feature, parseArgs, tokenLedger, spent: () => spent,
     mtime: p => fs.statSync(full(p)).mtimeMs,
     json: p => JSON.parse(read(p)),
+    // Same 'sha256:'-prefixed format validateIdentity already uses for agent
+    // definition integrity (line ~40) — reused here to bind a Gate approval
+    // to the exact document content it approved, not just "a file exists".
+    hash: text => 'sha256:' + crypto.createHash('sha256').update(String(text), 'utf8').digest('hex'),
     log: text => (options.log || (() => {}))(String(text)),
     append: (p, text) => { fs.mkdirSync(path.dirname(full(p)), { recursive: true }); fs.appendFileSync(full(p), text); },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/gaia-generate-work-breakdown.md

@@ -55,6 +55,8 @@ The prefix is everything up to and including the second hyphen-separated segment
 
 **Do NOT write `{PREFIX}-Work-Breakdown.md` or `{PREFIX}-Work-Breakdown.csv`.** Those are generated deterministically from the JSON by `wb-render.js` in a later pipeline step.
 
+"Authoritative" above means authoritative **for this agent's own generation and for `wb-validate.js`'s structural checks** — it does not mean every downstream reader consumes the JSON. The rendered `.md` (plus the dispatch `.csv`) is the tested, complete deliverable for everything that reads a Work Breakdown afterward: `lib/task-executor/plan.js` (the real task executor parses `.md`+`.csv`, never the JSON) and the `gaia-developer-*` agents both read the `.md`, and `tests/wb-render.*.test.js` specifically guards that every field they need (dependencies, verification commands, acceptance criteria, etc.) survives the JSON→Markdown rendering byte-for-byte. Only `gaia-validate-work-breakdown-semantic` reads the JSON directly, for its own programmatic comparison against Requirements ACs.
+
 ---
 
 ## Atomicity Contract

package/src/claude/agents/gaia-install-toolkit.md

@@ -243,6 +243,6 @@ If any modified files were kept by the user (not overwritten), list them so they
 
 - **Never overwrite `docs/procedures/` files** regardless of `--force` — project overrides take priority
 - **Never copy `install-toolkit.md`** — it's a toolkit-internal utility
-- **Never copy or edit `settings.json` / `settings.local.json`** — user-owned config; only verify and advise (Step 4b)
+- **The installer (Step 2) never copies `settings.json` / `settings.local.json`**, and Step 4's spawn-depth check is read-only (verify and advise, never write). The ONE exception is Step 6's Bash allowlist, which edits `settings.local.json` — but only via the dedicated `merge-allowlist` CLI, and only after the user explicitly opts in; never edit either file directly or outside that step
 - **Create directories as needed** — destination may not have `.claude/` yet
 - **Abort cleanly** if destination path is invalid — do not create partial installs

package/src/claude/skills/implement-feature/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: <path-to-feature.md> [--force]
 
 Runs documentation and work breakdown through the deterministic Node workflow host, then implementation through the FTR-018 task executor. Approval gates remain in the main loop.
 
-Workflows are JavaScript assets, never agent types. Do not pass pm-phase1/2/3 or am-phase1/2 to agentType, subagent_type, or --agent. Use the workflow CLI below. Resolve the absolute Claude executable path as described in docs/task-executor-bootstrap.md.
+Workflows are JavaScript assets, never agent types. Do not pass pm-phase1/2/3 or am-phase1/2 to agentType, subagent_type, or --agent. Use the workflow CLI below. Resolve the absolute Claude executable path as described in `docs/task-executor-bootstrap.md` — never relative to this skill's own package directory (which holds only this `SKILL.md`, no `docs/` subfolder). That path is relative to wherever this toolkit's `docs/` landed for the install actually in use: the project root for a local install, or `~/.claude/` for a global install (`bin/cli.js`'s `installLocal`/`installGlobal` — a global install nests `docs/` under `~/.claude/docs/` alongside `skills/`/`agents/`; a local install places it at `<project-root>/docs/`, a sibling of `.claude/`, not inside it).
 
 ---
 
@@ -68,6 +68,8 @@ Extract from the result:
 - `requirements.summary` — requirements file summary
 - `tech_spec.summary` — tech-spec file summary
 - `validation.summary` — validation result (gaps or clean)
+- `docs_digest` — content digest binding this approval to the exact Requirements/Tech-Spec
+  bytes just produced; embed verbatim into `{PREFIX}-Approvals.md` in Step 2 below
 - `token_ledger` — array of per-agent token data from phase 1
 - `errors` — any agent failures during phase 1
 
@@ -117,6 +119,8 @@ The pipeline CANNOT continue until you reply directly.
 | {PREFIX}-Tech-Spec.md | ✅ Approved | {today} | {notes or —} |
 | {PREFIX}-Validation-Report.md | ✅ Approved | {today} | {notes or —} |
 
+**Docs Digest:** `{docs_digest}`
+
 ## Approval History
 
 | Cycle | Action | Date | Details |

package/src/claude/workflows/am-phase1.js

@@ -32,9 +32,21 @@ return c.run(meta.name, outputDir, prefix, async () => {
   // Neither assessor below has a Write tool: each returns its report as plain response
   // text, which the host persists to its declared `outputs` path (see worker()'s own
   // comment in lib/workflow-control.js for why — "Never ask an LLM to do I/O").
+  // Resume: unlike pm-phase1's own fresh() check, a crash between two assessors
+  // finishing and a third one still running used to force ALL of them to be
+  // re-dispatched from scratch on retry — c.parallel()'s own Promise.allSettled
+  // already lets the OTHER assessors' outputs land on disk even when one fails
+  // (confirmed in lib/workflow-control.js), but nothing here checked for that
+  // already-landed output before paying for a fresh dispatch. An assessor's own
+  // output is never partially written (worker() persists it only after a
+  // successful, fully-parsed response), so a non-empty existing file is safe to
+  // treat as already-done and skip.
   const assessmentResults = await c.parallel([...groups].map(([id, areas]) => async () => {
     const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
     const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
+    if (c.exists(output_file) && c.read(output_file).trim().length > 0) {
+      return { agent: id, scopes: areas, result: c.read(output_file), output_file }
+    }
     const result = await c.worker(id,
       `${targetPath} --prefix ${prefix} --output-dir ${outputDir}\n` +
       `Read-only assessment. Explicit scope: ${areas.join(', ')}. Inspect risks, evidence, severity and recommendations for EACH listed scope. ` +

package/src/claude/workflows/pm-phase1.js

@@ -31,24 +31,43 @@ return c.run(meta.name, featureDir, prefix, async () => {
   let validationSummary = 'skipped (fresh)'
   if (force || changed || !fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) {
     for (let cycle = 1; cycle <= 3; cycle++) {
-      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), and the full validation report content. Do not dispatch other agents.', { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, file('Requirements'), file('Tech-Spec')])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, report: { type: 'string' } }, required: ['valid', 'findings', 'report'] } })
-      const text = result.findings.join('\n')
-      if (result.valid && result.findings.length === 0) {
+      // needsRequirementsFix/needsTechSpecFix: explicit structured routing fields,
+      // not inferred by substring-matching the free-text `findings` array (which a
+      // finding mentioning both document names, or neither, would mis-route or
+      // silently skip). The validator agent itself decides which document(s) its
+      // own findings implicate.
+      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), needsRequirementsFix/needsTechSpecFix (true only if at least one finding implicates that document), and the full validation report content. Do not dispatch other agents.', { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, file('Requirements'), file('Tech-Spec')])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, needsRequirementsFix: { type: 'boolean' }, needsTechSpecFix: { type: 'boolean' }, report: { type: 'string' } }, required: ['valid', 'findings', 'needsRequirementsFix', 'needsTechSpecFix', 'report'] } })
+      // A model returning valid:true alongside non-empty findings (or valid:false
+      // with none) contradicts its own schema's intent — never silently treated as
+      // "not clean yet" and spent on another cycle without surfacing the
+      // inconsistency; fail closed instead of masking a confused response.
+      if (result.valid === (result.findings.length > 0)) {
+        throw new Error(`Validation agent returned a contradictory result on cycle ${cycle}: valid=${result.valid} with ${result.findings.length} finding(s)`)
+      }
+      if (result.valid) {
         if (!fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) throw new Error('Validation agent did not produce its report')
         validationSummary = `0 gaps (clean on cycle ${cycle})`
         break
       }
       if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
-      if (!text.includes('Tech-Spec') || text.includes('Requirements')) await requirements()
-      if (!text.includes('Requirements') || text.includes('Tech-Spec')) await techSpec()
+      if (!result.needsRequirementsFix && !result.needsTechSpecFix) throw new Error(`Validation agent reported gaps on cycle ${cycle} but flagged neither document for revision`)
+      if (result.needsRequirementsFix) await requirements()
+      if (result.needsTechSpecFix) await techSpec()
     }
   }
+  // Binds Gate 1's eventual approval to the EXACT Requirements/Tech-Spec bytes
+  // produced here, not just "a file named *-Requirements.md exists" — SKILL.md's
+  // Step 2 embeds this verbatim into Approvals.md, and pm-phase2.js's Gate 1 check
+  // fails closed if the current file content no longer matches it (content
+  // regenerated after approval, e.g. via a later --force run, must re-approve).
+  const docsDigest = c.hash(c.read(file('Requirements')) + '\u0000' + c.read(file('Tech-Spec')))
   c.append(`${featureDir}/${prefix}-process-log.txt`, `[${new Date().toISOString()}] pm-phase1: ${validationSummary}; Gate 1 approval requested\n`)
   return {
     prefix, feature_dir: featureDir, feature_path: featurePath,
     requirements: { path: file('Requirements'), summary: 'Requirements ready' },
     tech_spec: { path: file('Tech-Spec'), summary: 'Tech-Spec ready' },
     validation: { path: file('Validation-Report'), summary: validationSummary },
+    docs_digest: docsDigest,
     token_ledger: c.tokenLedger, errors: [],
   }
 })

package/src/claude/workflows/pm-phase2.js

@@ -14,6 +14,22 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const approvals = c.read(file('Approvals.md'))
   const gate = approvals.match(/^## Gate 1\b[^\n]*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m)
   if (!gate || !/✅\s*Approved/.test(gate[1])) throw new Error('Gate 1 approval evidence missing')
+  // Binds this approval to the EXACT Requirements/Tech-Spec content pm-phase1
+  // produced when it was approved (docs_digest, written into Approvals.md by
+  // SKILL.md's Step 2) — never just "a Gate 1 row says Approved". A missing
+  // digest (an approval recorded before this check existed) is not enforced,
+  // same null-compatible "unavailable, never fabricated" convention used
+  // throughout this toolkit; a PRESENT digest that no longer matches the
+  // current files fails closed — the approved documents changed since
+  // approval (e.g. a later --force re-run of pm-phase1) and must be
+  // re-approved, not silently carried forward on stale consent.
+  const digestMatch = gate[1].match(/\*\*Docs Digest:\*\*\s*`([^`]+)`/)
+  if (digestMatch) {
+    const currentDigest = c.hash(c.read(file('Requirements.md')) + '\u0000' + c.read(file('Tech-Spec.md')))
+    if (digestMatch[1] !== currentDigest) {
+      throw new Error('Gate 1 approval is stale: Requirements/Tech-Spec content no longer matches what was approved (docs digest mismatch) — re-approve Gate 1 before proceeding')
+    }
+  }
   const jsonPath = file('Work-Breakdown.json')
   await c.worker('gaia.agent.planner.work-breakdown', featurePath, {
     outputs: [{ path: jsonPath, inputs: [featurePath, file('Requirements.md'), file('Tech-Spec.md')] }],