@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/worktree.js

@@ -27,6 +27,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFileSync } = require('node:child_process');
+const { memoGit } = require('./git-memo.js');
 
 /** Worktree ids become branch names and directory names, so anything outside this set is a
  * potential argument-injection or path-traversal vector. Rejecting loudly beats sanitising
@@ -56,30 +57,67 @@ function sha256File(file        )         {
   return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 }
 
-function git(args          , cwd        , { allowFailure = false }                             = {})                                                   {
+/** Bounds for git children (082 IC-016). Null fields leave execFileSync's defaults, which is the
+ * bench behaviour: no timeout and the parent's environment. */
+                                                                                                  
+
+/** What `removeVerified` observed after removing (082 IC-021). `errors` holds exit codes or error
+ * codes only, never git's output, so a record can carry it without leaking repository text. */
+                   
+                               
+                                                                                   
+                   
+ 
+
+function git(
+  args          ,
+  cwd        ,
+  { allowFailure = false, timeoutMs = null, env = null }                                         = {},
+)                                                                  {
+  const opts      = { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] };
+  if (timeoutMs != null) opts.timeout = timeoutMs;
+  if (env != null) opts.env = env;
   try {
-    return {
-      ok: true,
-      stdout: execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }),
-    };
+    return { ok: true, stdout: execFileSync('git', args, opts) };
   } catch (err     ) {
     if (!allowFailure) throw err;
-    return { ok: false, stdout: '', stderr: err.stderr ? String(err.stderr) : String(err.message) };
+    return {
+      ok: false,
+      stdout: '',
+      stderr: err.stderr ? String(err.stderr) : String(err.message),
+      // Exit status, else the signal of a timed-out child, else the spawn error code.
+      code: String(err.status ?? err.signal ?? err.code ?? 'unknown'),
+    };
   }
 }
 
 class WorktreeManager {
   repoRoot        ;
   worktreesDir        ;
+  branchPrefix        ;
+  gitBounds           ;
 
   /**
    * @param {string} repoRoot repository whose worktrees are managed
    * @param {string} [worktreesDir] override the sandbox root; defaults to `<repo>/.doflow/worktrees`,
    *   which is gitignored so sandboxes never appear as untracked noise in the parent tree.
+   * @param {object} [options] 082 IC-016: `branchPrefix` (default `task/`), and `timeoutMs` and
+   *   `env` passed to every git child when given. Omitted, every bench path is unchanged.
    */
-  constructor(repoRoot        , worktreesDir         ) {
+  constructor(
+    repoRoot        ,
+    worktreesDir         ,
+    { branchPrefix = 'task/', timeoutMs = null, env = null }                                        = {},
+  ) {
     this.repoRoot = repoRoot;
     this.worktreesDir = worktreesDir || path.join(repoRoot, '.doflow', 'worktrees');
+    this.branchPrefix = branchPrefix;
+    this.gitBounds = { timeoutMs, env };
+  }
+
+  /** The module's git helper with this manager's bounds applied. */
+  git(args          , cwd        , opts                             = {}) {
+    return git(args, cwd, { ...opts, ...this.gitBounds });
   }
 
   static assertSafeId(taskId     )       {
@@ -95,13 +133,13 @@ class WorktreeManager {
 
   branchFor(taskId        )         {
     WorktreeManager.assertSafeId(taskId);
-    return `task/${taskId}`;
+    return `${this.branchPrefix}${taskId}`;
   }
 
   /** Whether git itself considers this path a registered worktree — the directory existing on disk
    * is not the same question, which is the bug fixed here. */
   isRegistered(wtPath        )          {
-    const res = git(['worktree', 'list', '--porcelain'], this.repoRoot, { allowFailure: true });
+    const res = this.git(['worktree', 'list', '--porcelain'], this.repoRoot, { allowFailure: true });
     if (!res.ok) return false;
     const resolved = path.resolve(wtPath);
     return res.stdout
@@ -110,6 +148,52 @@ class WorktreeManager {
       .some((l        ) => path.resolve(l.slice('worktree '.length).trim()) === resolved);
   }
 
+  /**
+   * Drops git's administrative record for `wtPath` when its directory is gone, and no other. A
+   * blanket `git worktree prune` also forgets every unrelated worktree of the user's whose directory
+   * is merely missing (an unmounted drive, a directory deleted by hand), which is not this
+   * manager's to decide. Git has no per-path prune, so this reads `<common-dir>/worktrees/<name>/gitdir`
+   * (the file git itself reads to decide a record is prunable) and removes only the matching record.
+   * A locked record, or one whose `.git` file is still present, is left alone.
+   */
+  dropStaleRecord(wtPath        )       {
+    // The repository's common directory does not move while one call runs; a failed read is not kept.
+    const routing = this.gitBounds.env ?? process.env;
+    const common = memoGit(`commonDir:${this.repoRoot}:${routing.GIT_DIR ?? ''}:${routing.GIT_COMMON_DIR ?? ''}`, () => {
+      const res = this.git(['rev-parse', '--git-common-dir'], this.repoRoot, { allowFailure: true });
+      return res.ok ? res.stdout.trim() : undefined;
+    });
+    if (common === undefined) return;
+    const admin = path.join(path.resolve(this.repoRoot, common), 'worktrees');
+    let names          ;
+    try {
+      names = fs.readdirSync(admin);
+    } catch {
+      return;
+    }
+    // git writes the real path of the parent, so compare with that of the worktree's parent too.
+    const target = path.resolve(wtPath);
+    let realTarget = target;
+    try {
+      realTarget = path.join(fs.realpathSync(path.dirname(target)), path.basename(target));
+    } catch {
+      // The parent is gone as well: only the plain form can match.
+    }
+    for (const name of names) {
+      const record = path.join(admin, name);
+      try {
+        if (fs.existsSync(path.join(record, 'locked'))) continue;
+        // A relative gitdir (worktree.useRelativePaths) is relative to the record directory.
+        const dotGit = path.resolve(record, fs.readFileSync(path.join(record, 'gitdir'), 'utf8').trim());
+        if (path.dirname(dotGit) !== target && path.dirname(dotGit) !== realTarget) continue;
+        if (fs.existsSync(dotGit)) continue;
+        fs.rmSync(record, { recursive: true, force: true });
+      } catch {
+        // An unreadable record is not ours to judge.
+      }
+    }
+  }
+
   /**
    * Create an isolated worktree, reusing it only when git agrees it is registered. Returns the
    * absolute path.
@@ -120,23 +204,23 @@ class WorktreeManager {
 
     if (this.isRegistered(wtPath)) return wtPath;
 
-    // A leftover directory that git does not know about blocks `worktree add`. Clear it, and
-    // prune git's stale administrative records, before trying.
+    // A leftover directory that git does not know about blocks `worktree add`. Clear it, and this
+    // path's stale administrative record, before trying; other worktrees' records are not touched.
     if (fs.existsSync(wtPath)) fs.rmSync(wtPath, { recursive: true, force: true });
-    git(['worktree', 'prune'], this.repoRoot, { allowFailure: true });
+    this.dropStaleRecord(wtPath);
 
     fs.mkdirSync(this.worktreesDir, { recursive: true });
 
-    const branchExists = git(['rev-parse', '--verify', '--quiet', branch], this.repoRoot, { allowFailure: true }).ok;
+    const branchExists = this.git(['rev-parse', '--verify', '--quiet', branch], this.repoRoot, { allowFailure: true }).ok;
     const args = branchExists
       ? ['worktree', 'add', wtPath, branch]
       : ['worktree', 'add', '-b', branch, wtPath, baseRef];
-    git(args, this.repoRoot);
+    this.git(args, this.repoRoot);
 
     // Persist the base as a resolved SHA. A symbolic ref is useless later: inside the worktree
     // `HEAD` moves with every commit the task makes, so diffing against it reports nothing. The
     // file also survives a process boundary, since grading may run separately from execution.
-    const baseSha = git(['rev-parse', baseRef], this.repoRoot).stdout.trim();
+    const baseSha = this.git(['rev-parse', baseRef], this.repoRoot).stdout.trim();
     fs.writeFileSync(path.join(wtPath, BASE_FILE), `${baseSha}\n`);
     return wtPath;
   }
@@ -250,7 +334,7 @@ class WorktreeManager {
   /** Repo HEAD, or null outside a repository. Recorded for readability; the per-skill hashes are
    * the actual provenance, and they stay correct on a dirty tree where a commit id does not. */
   headCommit()                {
-    const res = git(['rev-parse', 'HEAD'], this.repoRoot, { allowFailure: true });
+    const res = this.git(['rev-parse', 'HEAD'], this.repoRoot, { allowFailure: true });
     return res.ok ? res.stdout.trim() : null;
   }
 
@@ -269,11 +353,54 @@ class WorktreeManager {
     const wtPath = this.pathFor(taskId);
     const branch = this.branchFor(taskId);
 
-    git(['worktree', 'remove', '--force', wtPath], this.repoRoot, { allowFailure: true });
+    this.git(['worktree', 'remove', '--force', wtPath], this.repoRoot, { allowFailure: true });
     if (fs.existsSync(wtPath)) fs.rmSync(wtPath, { recursive: true, force: true });
-    git(['worktree', 'prune'], this.repoRoot, { allowFailure: true });
+    this.dropStaleRecord(wtPath);
     // Deleting the branch is what keeps repeated bench runs from accumulating one branch per case.
-    git(['branch', '-D', branch], this.repoRoot, { allowFailure: true });
+    this.git(['branch', '-D', branch], this.repoRoot, { allowFailure: true });
+  }
+
+  /**
+   * `remove`'s steps, then a reading of what is actually gone (082 IC-021). Never throws for a
+   * failed step: the failure is an entry in `errors` and a false `verified`, so a caller can keep
+   * the worktree and list it by path instead of assuming it was removed.
+   */
+  removeVerified(taskId        )          {
+    const wtPath = this.pathFor(taskId);
+    const branch = this.branchFor(taskId);
+    const errors           = [];
+    let threw = false;
+    const step = (args          ) => {
+      const res = this.git(args, this.repoRoot, { allowFailure: true });
+      if (!res.ok) errors.push(res.code          );
+      return res;
+    };
+
+    step(['worktree', 'remove', '--force', wtPath]);
+    if (fs.existsSync(wtPath)) {
+      try {
+        fs.rmSync(wtPath, { recursive: true, force: true });
+      } catch (err     ) {
+        threw = true;
+        errors.push(String(err?.code ?? 'unknown'));
+      }
+    }
+    this.dropStaleRecord(wtPath);
+    // `branch -D` fails harmlessly when the branch never existed; only the reading below decides.
+    step(['branch', '-D', branch]);
+
+    const pathGone = !fs.existsSync(wtPath);
+    const branchGone = !this.git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], this.repoRoot, { allowFailure: true }).ok;
+    const unregistered = !this.isRegistered(wtPath);
+    return {
+      path: wtPath,
+      branch,
+      pathGone,
+      branchGone,
+      unregistered,
+      verified: !threw && pathGone && branchGone && unregistered,
+      errors,
+    };
   }
 
   /**
@@ -292,9 +419,9 @@ class WorktreeManager {
     if (!base) {
       return { diff: null, untracked: [], error: `no recorded base for ${taskId}; pass baseRef explicitly` };
     }
-    const committed = git(['diff', `${base}...HEAD`], wtPath, { allowFailure: true });
-    const working = git(['diff', 'HEAD'], wtPath, { allowFailure: true });
-    const untracked = git(['ls-files', '--others', '--exclude-standard'], wtPath, { allowFailure: true });
+    const committed = this.git(['diff', `${base}...HEAD`], wtPath, { allowFailure: true });
+    const working = this.git(['diff', 'HEAD'], wtPath, { allowFailure: true });
+    const untracked = this.git(['ls-files', '--others', '--exclude-standard'], wtPath, { allowFailure: true });
 
     if (!committed.ok && !working.ok) {
       return { diff: null, untracked: [], error: committed.stderr || working.stderr };

package/src/state/index.js

@@ -174,7 +174,7 @@ function migrateLegacyManifest({ root, scope, scopeRoot, claudeDir, now = new Da
   for (const resource of resources) if (!existing.has(ownershipKey(resource))) current.resources.push(resource);
 
   // The legacy manifest's MCP selection was owned by Claude's config flow.  Do not infer an
-  // equivalent selection for Codex or Gemini merely because they happened to share the old file.
+  // equivalent selection for Codex merely because it happened to share the old file.
   if (Array.isArray(legacy.mcpServers) && !Object.hasOwn(current.mcpSelections, 'claude')) current.mcpSelections.claude = [...legacy.mcpServers];
   for (const [harness, status] of Object.entries(legacy.tools)                   ) {
     if (status?.installed && !current.targets[harness]) current.targets[harness] = { installed: true, lastUpdated: status.last_updated ?? null, imported: true };

package/src/state/lockfile.js

@@ -11,8 +11,13 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { atomicJsonWrite } = require('./index.js');
+const { isPackageId } = require('../helper/package-ids.js');
 
-const LOCK_VERSION = 1;
+// Version plan (122 IC-007): a lock holding no third-party package stays version 1, byte for byte what
+// every earlier DoFlow wrote and reads; one holding packages is version 2, which an older DoFlow
+// refuses with its existing `Unsupported doflow.lock version` (the fail-closed direction).
+const LOCK_VERSION = 2;
+const LOCK_VERSION_BASE = 1;
 const LOCK_FILE = 'doflow.lock';
 
 function lockRoot({ scope, projectRoot = '.', homeDir = os.homedir() }                                                        )         {
@@ -31,7 +36,7 @@ function stable(value     )      {
 function defaultLock({ scope, scopeRoot }                                   )      {
   if (scope !== 'project' && scope !== 'global') throw new Error(`Invalid lock scope: '${scope}'`);
   return {
-    version: LOCK_VERSION,
+    version: LOCK_VERSION_BASE,
     scope,
     scopeRoot: path.resolve(scopeRoot),
     generatedAt: null,
@@ -42,9 +47,46 @@ function defaultLock({ scope, scopeRoot }                                   )
   };
 }
 
+const DIGEST = /^[0-9a-f]{64}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+const SOURCE_TYPES = ['local', 'git', 'npm', 'bundled'];
+const PACKAGE_FIELDS = ['id', 'version', 'source', 'contentDigest', 'capabilityDigest', 'enabled', 'addedAt'];
+
+/** The package rows of a lock: a v1 lock, an absent section and no lock all read as `[]`. */
+function lockPackages(lock     )        {
+  return Array.isArray(lock?.packages) ? lock.packages : [];
+}
+
+/** Refuse a malformed `packages` section, naming the field. The row is a closed shape (IC-007). */
+function validatePackages(value     )       {
+  if (value.scope === 'project') throw new Error('Invalid doflow.lock: packages is not allowed in a project-scope lock');
+  if (!Array.isArray(value.packages)) throw new Error('Invalid doflow.lock: packages must be an array');
+  const seen = new Set        ();
+  value.packages.forEach((row     , index        ) => {
+    const at = `packages[${index}]`;
+    const bad = (field        , why        ) => new Error(`Invalid doflow.lock: ${at}.${field} ${why}`);
+    if (!row || typeof row !== 'object' || Array.isArray(row)) throw new Error(`Invalid doflow.lock: ${at} must be an object`);
+    for (const key of Object.keys(row)) if (!PACKAGE_FIELDS.includes(key)) throw bad(key, 'is not a package field');
+    if (!isPackageId(row.id)) throw bad('id', 'must be a package id');
+    if (seen.has(row.id)) throw bad('id', `'${row.id}' is a duplicate`);
+    seen.add(row.id);
+    if (typeof row.version !== 'string' || row.version === '') throw bad('version', 'must be a non-empty string');
+    if (!row.source || typeof row.source !== 'object' || Array.isArray(row.source) || !SOURCE_TYPES.includes(row.source.type)) {
+      throw bad('source', `must be an object whose type is one of ${SOURCE_TYPES.join(', ')}`);
+    }
+    for (const field of ['contentDigest', 'capabilityDigest']) {
+      if (typeof row[field] !== 'string' || !DIGEST.test(row[field])) throw bad(field, 'must be 64 lowercase hex characters');
+    }
+    if (typeof row.enabled !== 'boolean') throw bad('enabled', 'must be a boolean');
+    if (typeof row.addedAt !== 'string' || !ISO_UTC.test(row.addedAt) || Number.isNaN(Date.parse(row.addedAt))) {
+      throw bad('addedAt', 'must be an ISO 8601 UTC time');
+    }
+  });
+}
+
 function validateLock(value     )      {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid doflow.lock: expected object');
-  if (value.version !== LOCK_VERSION) throw new Error(`Unsupported doflow.lock version: '${value.version}'`);
+  if (value.version !== LOCK_VERSION_BASE && value.version !== LOCK_VERSION) throw new Error(`Unsupported doflow.lock version: '${value.version}'`);
   if (value.scope !== 'project' && value.scope !== 'global') throw new Error(`Invalid doflow.lock scope: '${value.scope}'`);
   if (typeof value.scopeRoot !== 'string' || !path.isAbsolute(value.scopeRoot)) throw new Error('Invalid doflow.lock: scopeRoot must be absolute');
   for (const field of ['targets', 'assets']) {
@@ -58,6 +100,7 @@ function validateLock(value     )      {
       throw new Error(`Invalid doflow.lock: mcpSelections.${harness} must be an array of server ids`);
     }
   }
+  if ('packages' in value) validatePackages(value);
   return value;
 }
 
@@ -72,7 +115,14 @@ function writeLock(options     , lock     , { fsImpl = fs }                   =
   // Validate the caller's document first so a foreign version fails loudly here rather than
   // being silently normalized into something no future reader can distinguish.
   validateLock(lock);
-  return atomicJsonWrite(lockPath(options), stable({ ...lock, version: LOCK_VERSION }), { fsImpl });
+  // The `packages` key is written only when a package is recorded, and then the file is version 2;
+  // otherwise it is the version 1 bytes every earlier DoFlow wrote. `stable` orders arrays by their
+  // JSON text, so the rows are put back in `id` order afterwards.
+  const packages = lockPackages(lock);
+  const { packages: _omit, ...rest } = lock;
+  const document = stable(packages.length ? { ...rest, version: LOCK_VERSION, packages } : { ...rest, version: LOCK_VERSION_BASE });
+  if (packages.length) document.packages = document.packages.sort((a     , b     ) => (a.id < b.id ? -1 : 1));
+  return atomicJsonWrite(lockPath(options), document, { fsImpl });
 }
 
 /** The lock's MCP rows for the harnesses it targets. A row naming a harness outside `targets` is
@@ -82,8 +132,11 @@ function pinnedSelections(lock     )                      {
   return Object.fromEntries(Object.entries(lock?.mcpSelections ?? {}).filter(([harness]) => targets.has(harness)));
 }
 
-/** Compare two lock documents. Arrays are keyed by identity (assets by id, targets by harness,
- * fallback to full JSON), mcpSelections by harness, where an absent row (`null`) and a recorded
+/** The facts of a package row that make drift: its source and the time it was added are record keeping. */
+const packageFacts = (row     ) => ({ version: row.version, contentDigest: row.contentDigest, capabilityDigest: row.capabilityDigest, enabled: row.enabled });
+
+/** Compare two lock documents. Arrays are keyed by identity (assets and packages by id, targets by
+ * harness, fallback to full JSON), packages on their `packageFacts` only, mcpSelections by harness, where an absent row (`null`) and a recorded
  * empty selection (`[]`) differ. Returns {added, removed, changed} per section plus a clean flag. */
 function diffLocks(previousLock     , nextLock     )      {
   // Compare in the order writeLock stores, so a document built in memory never differs from the
@@ -91,13 +144,13 @@ function diffLocks(previousLock     , nextLock     )      {
   const previous = previousLock && stable(previousLock);
   const next = nextLock && stable(nextLock);
   const key = (entry     ) => entry?.id ?? entry?.harness ?? JSON.stringify(entry);
-  const sectionDiff = (before     , after     ) => {
+  const sectionDiff = (before     , after     , compared                      = (entry) => entry) => {
     const beforeKeys = new Map             ((before || []).map((entry     )                => [key(entry), entry]));
     const afterKeys = new Map             ((after || []).map((entry     )                => [key(entry), entry]));
     const added = [...afterKeys].filter(([k]) => !beforeKeys.has(k)).map(([, v]) => v);
     const removed = [...beforeKeys].filter(([k]) => !afterKeys.has(k)).map(([, v]) => v);
     const changed = [...afterKeys]
-      .filter(([k, v]) => beforeKeys.has(k) && JSON.stringify(beforeKeys.get(k)) !== JSON.stringify(v))
+      .filter(([k, v]) => beforeKeys.has(k) && JSON.stringify(compared(beforeKeys.get(k))) !== JSON.stringify(compared(v)))
       .map(([, v]) => v);
     return { added, removed, changed };
   };
@@ -110,13 +163,14 @@ function diffLocks(previousLock     , nextLock     )      {
   const result      = {
     targets: sectionDiff(previous?.targets, next?.targets),
     assets: sectionDiff(previous?.assets, next?.assets),
+    packages: sectionDiff(previous?.packages, next?.packages, (row) => stable(packageFacts(row))),
     mcpSelections: { changed: mcpChanged },
     meta: {
       sourceVersion: (previous?.sourceVersion ?? null) !== (next?.sourceVersion ?? null)
         ? { before: previous?.sourceVersion ?? null, after: next?.sourceVersion ?? null } : null,
     },
   };
-  result.clean = ['targets', 'assets'].every((name) => {
+  result.clean = ['targets', 'assets', 'packages'].every((name) => {
     const section = result[name];
     return section.added.length === 0 && section.removed.length === 0 && section.changed.length === 0;
   }) && result.mcpSelections.changed.length === 0 && result.meta.sourceVersion === null;
@@ -132,5 +186,5 @@ function removeLock(options     , { fsImpl = fs }                   = {})
 }
 
 module.exports = {
-  LOCK_VERSION, LOCK_FILE, lockRoot, lockPath, defaultLock, validateLock, readLock, writeLock, pinnedSelections, diffLocks, removeLock,
+  LOCK_VERSION, LOCK_VERSION_BASE, LOCK_FILE, lockRoot, lockPath, defaultLock, validateLock, lockPackages, readLock, writeLock, pinnedSelections, diffLocks, removeLock,
 };

package/src/state/run-lock.js

@@ -404,5 +404,5 @@ function holdHandle({ fsImpl, root, stateDir, lockPath, token, hostname, firstCr
 }
 
 module.exports = {
-  acquireRunLock, RunLockTimeoutError, RunLockError, RunLockLostError, runLockPath, formatRunLockMessage,
+  acquireRunLock, RunLockTimeoutError, RunLockError, RunLockLostError, runLockPath, formatRunLockMessage, defaultIsAlive,
 };

package/types/node-commonjs.d.ts

@@ -5,26 +5,80 @@
 // the surface the migrated modules actually touch. Extend it as more modules migrate, not ahead of
 // need. See agent-docs/BRIEF_GOAL_DOFLOW.md for the migration roadmap.
 
-declare var require: { (id: string): any; main: any };
+type TestCallback = (t?: any, done?: any) => any;
+interface TestFn {
+  (name: string, fn?: TestCallback): any;
+  (name: string, opts: any, fn?: TestCallback): any;
+  (fn: TestCallback): any;
+  skip: TestFn;
+  todo: TestFn;
+  only: TestFn;
+}
+interface NodeTestModule extends TestFn {
+  test: TestFn;
+  describe: TestFn;
+  it: TestFn;
+  suite: TestFn;
+  before(fn: TestCallback, opts?: any): void;
+  after(fn: TestCallback, opts?: any): void;
+  beforeEach(fn: TestCallback, opts?: any): void;
+  afterEach(fn: TestCallback, opts?: any): void;
+  mock: any;
+  run: any;
+  [key: string]: any;
+}
+interface NodeHttpModule {
+  createServer(listener?: (req?: any, res?: any) => any): any;
+  [key: string]: any;
+}
+interface NodeNetModule {
+  createServer(opts?: any, listener?: (socket?: any) => any): any;
+  [key: string]: any;
+}
+
+declare var require: {
+  (id: 'node:test'): NodeTestModule;
+  (id: 'node:http' | 'http'): NodeHttpModule;
+  (id: 'node:net' | 'net'): NodeNetModule;
+  (id: string): any;
+  main: any;
+  resolve(id: string, options?: any): string;
+  cache: Record<string, any>;
+};
 
-declare var module: { exports: any };
+declare var module: { exports: any; parent?: any; filename?: string; [key: string]: any };
 
 declare var process: {
   features?: { typescript?: false | 'strip' | 'transform' };
   env: Record<string, string | undefined>;
   platform: string;
   execPath: string;
+  execArgv: string[];
   version: string;
   pid: number;
+  ppid: number;
   argv: string[];
   cwd(): string;
   exit(code?: number): never;
   exitCode?: number;
   kill(pid: number, signal?: string | number): void;
   hrtime: { (time?: [number, number]): [number, number]; bigint(): bigint };
-  stdin: { isTTY?: boolean; isRaw?: boolean; setRawMode(mode: boolean): void };
-  stdout: { write(chunk: string): boolean; isTTY?: boolean };
-  stderr: { write(chunk: string): boolean };
+  stdin: { isTTY?: boolean; isRaw?: boolean; setRawMode(mode: boolean): void; [key: string]: any };
+  stdout: { write(chunk: any, ...rest: any[]): boolean; isTTY?: boolean; columns?: number; [key: string]: any };
+  stderr: { write(chunk: any, ...rest: any[]): boolean; [key: string]: any };
+  arch: string;
+  versions: Record<string, string>;
+  memoryUsage(): { rss: number; heapTotal: number; heapUsed: number; external: number; [key: string]: number };
+  resourceUsage(): Record<string, number>;
+  uptime(): number;
+  umask(mask?: number): number;
+  getuid?(): number;
+  nextTick(callback: (...args: any[]) => void, ...args: any[]): void;
+  emitWarning(warning: any, ...rest: any[]): void;
+  once(event: string, listener: (...args: any[]) => void): any;
+  off(event: string, listener: (...args: any[]) => void): any;
+  emit(event: string, ...args: any[]): boolean;
+  chdir(directory: string): void;
   on(event: string, listener: (...args: any[]) => void): any;
   removeListener(event: string, listener: (...args: any[]) => void): any;
 };
@@ -38,25 +92,47 @@ declare var console: {
   log(...args: any[]): void;
   error(...args: any[]): void;
   warn(...args: any[]): void;
+  info(...args: any[]): void;
+  debug(...args: any[]): void;
+  table(...args: any[]): void;
+  [key: string]: any;
 };
 
 interface Buffer extends Uint8Array {
   toString(encoding?: string, start?: number, end?: number): string;
   equals(other: Uint8Array): boolean;
   subarray(begin?: number, end?: number): Buffer;
+  readUInt16LE(offset?: number): number;
+  readUInt32LE(offset?: number): number;
+  readInt32LE(offset?: number): number;
+  readBigInt64LE(offset?: number): bigint;
+  readUInt8(offset?: number): number;
+  readUInt16BE(offset?: number): number;
+  readUInt32BE(offset?: number): number;
+  writeUInt8(value: number, offset?: number): number;
+  writeUInt16LE(value: number, offset?: number): number;
+  writeUInt32LE(value: number, offset?: number): number;
+  writeUInt32BE(value: number, offset?: number): number;
+  write(string: string, offset?: number, length?: number, encoding?: string): number;
+  slice(begin?: number, end?: number): Buffer;
+  toJSON(): { type: 'Buffer'; data: number[] };
 }
 declare var Buffer: {
-  alloc(size: number): Buffer;
-  from(data: any, encoding?: string): Buffer;
+  alloc(size: number, fill?: any, encoding?: string): Buffer;
+  from(data: any, encodingOrOffset?: any, length?: number): Buffer;
   byteLength(string: string, encoding?: string): number;
   isBuffer(value: any): boolean;
   allocUnsafe(size: number): Buffer;
   concat(list: Uint8Array[], totalLength?: number): Buffer;
+  compare(a: Uint8Array, b: Uint8Array): number;
+  prototype: Buffer;
 };
 
 // Timers and WHATWG URL, as the migrated .ts modules use them (opaque handle; parsed URL fields only).
 declare function setTimeout(callback: (...args: any[]) => void, ms?: number, ...args: any[]): any;
 declare function clearTimeout(handle: any): void;
+declare function setInterval(callback: (...args: any[]) => void, ms?: number, ...args: any[]): any;
+declare function clearInterval(handle: any): void;
 declare var URL: {
   new (input: string, base?: string): { protocol: string; username: string; password: string; hostname: string; [key: string]: any };
 };
@@ -66,3 +142,26 @@ declare var performance: { now(): number };
 
 // structuredClone (workflow-orchestrator previewHandoff deep-copies a run program).
 declare function structuredClone<T>(value: T): T;
+
+// Ambient globals used by test/ and bench/ (all present in Node >=24; declared loosely, no @types/node).
+declare function setImmediate(callback: (...args: any[]) => void, ...args: any[]): any;
+declare function clearImmediate(handle: any): void;
+declare function queueMicrotask(callback: () => void): void;
+declare function fetch(input: any, init?: any): Promise<any>;
+declare var AbortController: { new (): { signal: any; abort(reason?: any): void }; prototype: any };
+declare var AbortSignal: { new (): any; abort(reason?: any): any; timeout(ms: number): any; any(signals: any[]): any; prototype: any };
+declare var TextEncoder: { new (): { encode(input?: string): Uint8Array; encoding: string } };
+declare var TextDecoder: { new (label?: string, options?: any): { decode(input?: any, options?: any): string; encoding: string } };
+declare var URLSearchParams: { new (init?: any): any; prototype: any };
+declare var EventTarget: { new (): any; prototype: any };
+declare var Event: { new (type: string, init?: any): any; prototype: any };
+
+interface ObjectConstructor {
+  entries(o: any): [string, any][];
+  values(o: any): any[];
+  fromEntries(entries: any): any;
+}
+
+interface ErrorConstructor {
+  stackTraceLimit?: number;
+}

package/core/harnesses/claude/hooks/pre-bash-guard.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# Claude front door: pre-bash-guard through the shared lifecycle bridge.
-set -uo pipefail
-export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
-if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t claude"}}'
-  exit 0
-fi
-doflow_bridge claude PreToolUse pre-bash-guard
-exit $?

package/core/harnesses/codex/hooks/pre-bash-guard.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# Codex front door: pre-bash-guard through the shared lifecycle bridge.
-set -uo pipefail
-export DOFLOW_AGENT="${DOFLOW_AGENT:-codex}"
-if ! . "$(dirname "$0")/../../.doflow/shared/hooks/bridge/bridge.sh" 2>/dev/null; then
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"[doflow] shared hooks lack the bridge; run: doflow update -t codex"}}'
-  exit 0
-fi
-doflow_bridge codex PreToolUse pre-bash-guard
-exit $?