@deksden-com/dd-flow-cli 0.9.0-beta.151 → 0.9.0-beta.155

package/dist/services/worktrees.js

@@ -57,7 +57,8 @@ export function prepareManagedWorktree(input) {
         if (typeof input[key] !== "string" || !input[key].trim() || input[key].includes("\0"))
             invalid(`--${key} must be a non-empty value without NUL`);
     const git = (args) => {
-        const result = spawnSync("git", ["-C", projectRoot, ...args], { encoding: "utf8", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+        const result = spawnSync("git", ["-C", projectRoot, ...args], { encoding: "utf8",
+            env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0" } });
         if (result.error)
             throw result.error;
         return result;
@@ -90,7 +91,9 @@ export async function createManagedWorktree(context, input, prepared = prepareMa
     // Worktrunk owns creation; the CLI supplies its project-scoped service path
     // as a one-shot config override rather than relying on a developer's user config.
     const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(prepared.path)}`, "switch", "--create", prepared.branch, "--base", prepared.base, "--no-cd", "--format=json", "-y"];
-    const result = await runExternal(command);
+    // commandResult overlays process.env, so explicitly clear inherited Git
+    // redirection instead of merely omitting it from the override object.
+    const result = await runExternal(command, Object.fromEntries(Object.keys(process.env).filter(key => key.startsWith("GIT_")).map(key => [key, undefined])));
     if (result.exit_code !== 0)
         throw new AppError("worktrunk_command_unavailable", "Worktrunk switch failed", 1, { command: sanitizeCommand(command), result });
     const response = parseWorktrunkResponse(result.stdout, command);
@@ -256,12 +259,12 @@ export function worktreeRecord(context, projectId, protocolId) {
 function activeWorktreeRecord(context, projectId, protocolId) {
     return context.db.get("SELECT * FROM worktree_records WHERE project_id = ? AND protocol_id = ? AND status = 'active'", [projectId, protocolId]);
 }
-async function runExternal(command) {
+async function runExternal(command, env = {}) {
     const [bin, ...args] = command;
     if (!bin) {
         return { exit_code: null, signal: null, stdout: "", stderr: "Missing executable." };
     }
-    const result = await commandResult(bin, args, { startupMs: SETUP_STARTUP_MS });
+    const result = await commandResult(bin, args, { startupMs: SETUP_STARTUP_MS, env });
     const evidence = processEvidence(result);
     return {
         exit_code: result.exit_code,

package/dist/storage/database.js

@@ -106,7 +106,7 @@ export function ensureLifecycleInvocationStorage(db) {
     CREATE TABLE IF NOT EXISTS lifecycle_invocations (
       id TEXT PRIMARY KEY, scope_json TEXT NOT NULL, command TEXT NOT NULL,
       fingerprint TEXT NOT NULL, status TEXT NOT NULL,
-      event_key TEXT UNIQUE, identity_json TEXT, deadline INTEGER, outcome_json TEXT,
+      event_key TEXT UNIQUE, identity_json TEXT, admission_json TEXT, deadline INTEGER, outcome_json TEXT,
       created_at TEXT NOT NULL, updated_at TEXT NOT NULL
     );
     CREATE INDEX IF NOT EXISTS idx_lifecycle_invocations_scope
@@ -117,6 +117,7 @@ export function ensureLifecycleInvocationStorage(db) {
       PRIMARY KEY(packet_sha256, invocation_id)
     );
   `);
+    ensureColumn(db, "lifecycle_invocations", "admission_json", "ALTER TABLE lifecycle_invocations ADD COLUMN admission_json TEXT");
 }
 /** RUN authority stays in its existing store; process leases stay in runtime.sqlite. */
 export function ensureRunControlStorage(db) {

package/dist/verification-components.json

@@ -18,11 +18,17 @@
       "cli/input-preparation.js",
       "cli/native-hook-preparation.js",
       "domain/contracts.js",
+      "domain/delivery-flows.js",
       "domain/diagnostic-aspects.js",
       "domain/diagnostic-flows.js",
+      "domain/distill-flow.js",
       "domain/entity-ids.js",
       "domain/flow-contract.js",
+      "domain/interactive-flow.js",
+      "domain/memory-fix-flow.js",
+      "domain/review-fix-flow.js",
       "domain/session-coverage.js",
+      "domain/source-snapshot-flows.js",
       "domain/stage-catalog.js",
       "domain/stage-handler-identities.js",
       "domain/validation.js",
@@ -45,6 +51,7 @@
       "schemas/stage-report.schema.json",
       "schemas/stage-start-response.schema.json",
       "services/accepted-intent.js",
+      "services/assigned-lifecycle.js",
       "services/audit.js",
       "services/branch-context.js",
       "services/build-info.js",
@@ -57,6 +64,20 @@
       "services/code-checks.js",
       "services/command-context.js",
       "services/config.js",
+      "services/controller-result-authority.js",
+      "services/delivery-access.js",
+      "services/delivery-approval.js",
+      "services/delivery-artifact.js",
+      "services/delivery-checks.js",
+      "services/delivery-execution.js",
+      "services/delivery-intents.js",
+      "services/delivery-policy.js",
+      "services/delivery-procedures.js",
+      "services/delivery-request.js",
+      "services/delivery-result.js",
+      "services/delivery-stage-entry.js",
+      "services/delivery-stage-handlers.js",
+      "services/delivery-stage-results.js",
       "services/descriptor-coordinator-session.js",
       "services/descriptor-root-work.js",
       "services/descriptor-run-settlement.js",
@@ -65,15 +86,28 @@
       "services/descriptor-stage-settlement.js",
       "services/descriptor-stage-start.js",
       "services/diagnostic-evidence.js",
+      "services/diagnostic-repair-intake.js",
+      "services/diagnostic-repair-source-intake.js",
       "services/diagnostic-report-publication.js",
       "services/diagnostic-report.js",
+      "services/diagnostic-run-bundle.js",
       "services/diagnostic-snapshot.js",
       "services/diagnostic-stage-handlers.js",
       "services/diagnostic-stage-results.js",
+      "services/diagnostic-start.js",
       "services/diagnostic-work-batch.js",
       "services/diagnostic-work-collection.js",
       "services/diagnostic-work-registration.js",
       "services/diagnostic-work-results.js",
+      "services/distill-document-publication.js",
+      "services/distill-publication-custody.js",
+      "services/distill-stage-handlers.js",
+      "services/distill-stage-results.js",
+      "services/distill-user-inputs.js",
+      "services/distill-work-batch.js",
+      "services/distill-work-collection.js",
+      "services/distill-work-registration.js",
+      "services/distill-work-results.js",
       "services/engines.js",
       "services/eval-snapshots.js",
       "services/execution-bundles.js",
@@ -93,11 +127,36 @@
       "services/ids.js",
       "services/installation-lock.js",
       "services/installed-flow-source.js",
+      "services/interactive-attached-session.js",
+      "services/interactive-baseline-custody.js",
+      "services/interactive-before-versions.js",
+      "services/interactive-bundle-data.js",
+      "services/interactive-checks.js",
+      "services/interactive-finish-integration.js",
+      "services/interactive-git-baseline.js",
+      "services/interactive-git-dispatch.js",
+      "services/interactive-mutation-scope.js",
+      "services/interactive-request.js",
+      "services/interactive-run-bundle.js",
+      "services/interactive-stage-entry.js",
+      "services/interactive-stage-handlers.js",
+      "services/interactive-stage-observation.js",
+      "services/interactive-stage-results.js",
+      "services/interactive-user-inputs.js",
+      "services/interactive-work-batch.js",
+      "services/interactive-work-collection.js",
+      "services/interactive-work-completion.js",
+      "services/interactive-work-context.js",
+      "services/interactive-work-history.js",
+      "services/interactive-work-registration.js",
+      "services/interactive-work-results.js",
+      "services/interactive-work-start.js",
       "services/lanes.js",
       "services/lifecycle-command.js",
       "services/lifecycle-contract.js",
       "services/lifecycle-invocations.js",
       "services/managed-daemon-binding.js",
+      "services/managed-lease-monitor.js",
       "services/managed-processes.js",
       "services/memory-accepted-composition.js",
       "services/memory-baseline-preservation.js",
@@ -123,6 +182,19 @@
       "services/memory-finish-handler.js",
       "services/memory-finish-integration.js",
       "services/memory-finish-readiness.js",
+      "services/memory-fix-finish-integration.js",
+      "services/memory-fix-intake-custody.js",
+      "services/memory-fix-intake-settlement.js",
+      "services/memory-fix-publication.js",
+      "services/memory-fix-repair-admission.js",
+      "services/memory-fix-request.js",
+      "services/memory-fix-run-bundle.js",
+      "services/memory-fix-scope.js",
+      "services/memory-fix-sources.js",
+      "services/memory-fix-stage-entry.js",
+      "services/memory-fix-stage-handlers.js",
+      "services/memory-fix-stage-results.js",
+      "services/memory-flow-user-inputs.js",
       "services/memory-git-integration.js",
       "services/memory-historical-corrected-review.js",
       "services/memory-historical-original-review.js",
@@ -210,8 +282,11 @@
       "services/migrations.js",
       "services/native-session-control.js",
       "services/operator-profiles.js",
+      "services/physical-startup.js",
       "services/plan-runtime.js",
       "services/portable-refs.js",
+      "services/project-flow-source.js",
+      "services/project-git-integration.js",
       "services/project-registry.js",
       "services/project-summary.js",
       "services/projects.js",
@@ -231,6 +306,11 @@
       "services/repair-receipt.js",
       "services/review-copy.js",
       "services/review-deferral.js",
+      "services/review-fix-handoff.js",
+      "services/review-fix-intake-custody.js",
+      "services/review-fix-stage-entry.js",
+      "services/review-fix-stage-handlers.js",
+      "services/review-fix-stage-results.js",
       "services/run-control-receipt.js",
       "services/run-control.js",
       "services/run-controller-state.js",
@@ -240,6 +320,7 @@
       "services/run-recovery-guard.js",
       "services/run-recovery.js",
       "services/run-start-custody.js",
+      "services/run-timeline.js",
       "services/runs.js",
       "services/runtime-budget.js",
       "services/runtime-command.js",
@@ -254,6 +335,7 @@
       "services/stage-pause.js",
       "services/stage-report-renderer.js",
       "services/stage-work-graph.js",
+      "services/technical-notes.js",
       "services/tooling.js",
       "services/usage.js",
       "services/verification-matrix.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.151",
+  "version": "0.9.0-beta.155",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "packageManager": "pnpm@10.23.0",
@@ -30,13 +30,14 @@
     "test": "node scripts/verification.mjs run",
     "gate:merge": "node scripts/verification.mjs run",
     "verify:plan": "node scripts/verification.mjs plan",
-    "test:verification": "node --test --test-concurrency=1 scripts/verification-policy.test.mjs scripts/generate-verification-components.test.mjs",
+    "test:verification": "node --test --test-concurrency=1 scripts/verification-policy.test.mjs scripts/generate-verification-components.test.mjs scripts/verification-jobs.test.mjs",
     "test:hybrid": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/hybrid-contracts.test.mjs",
     "test:hybrid:canon": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/hybrid-canon.test.mjs scripts/hybrid-inventory.test.mjs scripts/hybrid-consumers.test.mjs scripts/hybrid-schema-copies.test.mjs scripts/verify-e3-canon.test.mjs",
     "test:e2": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/e2-*.test.mjs",
     "test:e2:installed": "node --test scripts/verify-e2-built-cli.test.mjs scripts/verify-e2-installed-cli.test.mjs",
-    "test:e3": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/e3-*.test.mjs",
+    "test:e3": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/e3-*.test.mjs scripts/verify-e3-engine-storage.test.mjs",
     "test:e4": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/e4-*.test.mjs",
+    "test:e5": "node --import ./scripts/source-test-loader.mjs --test --test-concurrency=1 scripts/e5-*.test.mjs",
     "test:e3:canon": "node --import ./scripts/source-test-loader.mjs --test scripts/verify-e3-canon.test.mjs",
     "test:release": "node --test scripts/verify-release-build.test.mjs && vitest run --project=release",
     "test:release:build": "node --test --test-concurrency=1 scripts/verify-release-build.test.mjs scripts/verify-e2-built-cli.test.mjs scripts/verify-e2-installed-cli.test.mjs",

package/tools/verification-jobs.mjs

@@ -0,0 +1,342 @@
+// SSOT for the cooperating verification entrypoints. Standalone consumers vendor
+// this file byte-for-byte; contract catalogs and report validators stay local.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { setTimeout, clearTimeout } from 'node:timers';
+import process from 'node:process';
+
+const realHome = os.userInfo().homedir; // OS identity, never a fixture's HOME.
+const providerCredentials = ['OPENAI_API_KEY','OPENROUTER_API_KEY','OPENAI_DECISIONS_API_KEY','ANTHROPIC_API_KEY','GEMINI_API_KEY','GOOGLE_API_KEY','XAI_API_KEY','ZAI_API_KEY','NODE_AUTH_TOKEN','NPM_TOKEN','NPM_ACCESS_TOKEN'];
+const read = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+const optional = file => { try { return read(file); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } };
+const blocked = message => Object.assign(new Error(message), { code: 'verification_ownership_unknown' });
+export function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' }); fs.renameSync(temporary, file); }
+  catch (error) {
+    try { fs.unlinkSync(temporary); } catch (cleanup) { if (cleanup.code !== 'ENOENT') error.cleanup_error = cleanup; }
+    throw error;
+  }
+}
+
+// Same physical identity fields as EVAL's process-snapshot helper. Observation
+// failure is never interpreted as an empty process table.
+function snapshot() {
+  return execFileSync('ps', ['-axo', 'pid=,ppid=,pgid=,lstart=,stat='], {
+    encoding: 'utf8', timeout: 5000, env: { PATH: process.env.PATH, LC_ALL: 'C', TZ: 'UTC' },
+  }).trim().split('\n').flatMap(line => {
+    const p = line.trim().split(/\s+/);
+    return p.length >= 9 ? [{ pid: +p[0], ppid: +p[1], pgid: +p[2], birth: p.slice(3, 8).join(' '), zombie: p[8].startsWith('Z') }] : [];
+  });
+}
+const same = (a, b) => a && b && a.pid === b.pid && a.birth === b.birth && !b.zombie;
+function self() {
+  const identity = snapshot().find(p => p.pid === process.pid && !p.zombie);
+  if (!identity) throw blocked('Cannot establish verification owner identity');
+  return identity;
+}
+function alive(owner, processes = snapshot()) { return same(owner, processes.find(p => p.pid === owner?.pid)); }
+function producerSettled(attempt) {
+  const owner = attempt.owner, processes = snapshot();
+  return !alive(owner, processes) && Number.isSafeInteger(owner?.pgid) && owner.pgid > 0
+    && Array.isArray(owner.groups) && !processes.some(p => !p.zombie && p.pgid === owner.pgid)
+    && owner.groups.every(group => Number.isSafeInteger(group.pgid) && group.pgid > 0
+      && !processes.some(p => !p.zombie && p.pgid === group.pgid));
+}
+function release(lock, owner) {
+  // Only one reclaimer can remove this unique fence. A late reclaimer cannot
+  // unlink the next owner's record after the directory has been reacquired.
+  fs.unlinkSync(path.join(lock, `fence-${owner.token}`));
+  fs.unlinkSync(path.join(lock, 'owner.json')); fs.rmdirSync(lock);
+}
+async function claim(lock, signal) {
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+  const identity = self();
+  for (;;) {
+    signal?.throwIfAborted();
+    try {
+      fs.mkdirSync(lock);
+      const owner = { ...identity, token: randomUUID(), groups: [] };
+      fs.writeFileSync(path.join(lock, `fence-${owner.token}`), '', { flag: 'wx' });
+      atomicJson(path.join(lock, 'owner.json'), owner);
+      return owner;
+    } catch (e) { if (e.code !== 'EEXIST') throw e; }
+    const owner = optional(path.join(lock, 'owner.json'));
+    if (owner) {
+      const processes = snapshot();
+      if (!alive(owner, processes)) {
+        // A dead coordinator is NOT cleanup. A surviving process group keeps
+        // the whole lease until its physical absence is positively observed.
+        if (!Array.isArray(owner.groups)) throw blocked(`Unconfirmed lease groups: ${lock}`);
+        if (!owner.groups.some(g => !g.pgid || processes.some(p => p.pgid === g.pgid && !p.zombie))) {
+          // Recheck the immutable owner token before removing its record.
+          if (optional(path.join(lock, 'owner.json'))?.token === owner.token) {
+            try { release(lock, owner); } catch (e) { if (!['ENOENT', 'ENOTEMPTY'].includes(e.code)) throw e; }
+          }
+          continue;
+        }
+      }
+    }
+    await delay(50, undefined, { signal });
+  }
+}
+
+/** One immutable producer attempt. The index is scheduling state, not proof;
+ * callers must validate the returned report bytes and meaningful inputs. */
+export async function withContractAttempt(index, { rerun = false, failedOnly = false, reason, signal, validate, validationKey } = {}, action) {
+  if (rerun && !reason) throw new Error('Explicit rerun requires a reason');
+  const lock = `${index}.claim`;
+  const initial = optional(index);
+  if (initial?.status === 'running' && (!rerun || failedOnly)) {
+    try {
+      const result = await joinAttempt(initial, signal);
+      await validate?.(result.result, initial);
+      signal?.throwIfAborted();
+      return result;
+    } catch (error) {
+      signal?.throwIfAborted();
+      if (!rerun || !producerSettled(initial)) throw error;
+    }
+  }
+  let joined = null;
+  const owner = await claim(lock, signal);
+  let attempt;
+  try {
+    let current = optional(index); // Mandatory reread under claim.
+    if (rerun && current?.status === 'running' && producerSettled(current)) {
+      const terminal = optional(current.report);
+      if (terminal && (terminal.attemptId !== current.attemptId || !['passed', 'failed', 'interrupted'].includes(terminal.status))) throw blocked('Invalid terminal producer evidence');
+      signal?.throwIfAborted();
+      if (!terminal) atomicJson(current.report, { attemptId: current.attemptId, status: 'interrupted', error: 'Producer exited without terminal evidence; owner and owned process groups are absent', reason });
+      current = { ...current, status: terminal?.status ?? 'interrupted' };
+      atomicJson(index, current);
+    }
+    if (current?.status === 'running' && (!rerun || failedOnly)) { joined = current; }
+    else if (current && (!rerun || failedOnly && current.status === 'passed')) {
+      if (current.status !== 'passed') throw blocked(`Retained ${current.status} attempt requires explicit rerun: ${index}`);
+      try {
+        const terminal = read(current.report);
+        if (terminal.attemptId !== current.attemptId || terminal.status !== 'passed') throw new Error('Invalid terminal attempt');
+        await validate?.(terminal.result, current);
+        signal?.throwIfAborted();
+        return { ...terminal, reused: true, joined: false };
+      } catch (error) {
+        signal?.throwIfAborted(); // A cancelled reader never invalidates its producer.
+        atomicJson(index, { ...current, status: 'evidence_invalid', reason: String(error.message) });
+        reason = `Invalid evidence: ${error.message}`;
+      }
+    }
+    if (!joined) {
+      if (current?.status === 'running') throw blocked('Cannot supersede an active producer');
+      const attemptId = randomUUID();
+      const root = path.join(`${index}.attempts`, attemptId);
+      fs.mkdirSync(root, { recursive: true });
+      attempt = { attemptId, root, report: path.join(root, 'terminal.json'), owner, status: 'running', reason: reason ?? null, validationKey };
+      // Accepted rerun supersedes an old PASS before dispatch.
+      atomicJson(index, attempt);
+    }
+  } finally { release(lock, owner); }
+  if (joined) {
+    const result = await joinAttempt(joined, signal);
+    await validate?.(result.result, joined);
+    signal?.throwIfAborted();
+    return result;
+  }
+  try {
+    signal?.throwIfAborted();
+    const result = await action({ attemptId: attempt.attemptId, root: attempt.root });
+    await validate?.(result, attempt);
+    signal?.throwIfAborted();
+    const terminal = { attemptId: attempt.attemptId, result, status: 'passed' };
+    atomicJson(attempt.report, terminal);
+    atomicJson(index, { ...attempt, status: 'passed' });
+    return { ...terminal, reused: false, joined: false };
+  } catch (error) {
+    const terminal = { attemptId: attempt.attemptId, status: signal?.aborted ? 'interrupted' : 'failed', error: String(error.stack ?? error) };
+    atomicJson(attempt.report, terminal);
+    atomicJson(index, { ...attempt, status: terminal.status });
+    throw error;
+  }
+}
+async function joinAttempt(attempt, signal) {
+  for (;;) {
+    signal?.throwIfAborted(); // Cancels only this waiter.
+    const terminal = optional(attempt.report);
+    if (terminal) {
+      if (terminal.attemptId !== attempt.attemptId || terminal.status !== 'passed') throw blocked(`Producer attempt did not pass: ${attempt.attemptId}`);
+      return { ...terminal, reused: false, joined: true };
+    }
+    if (!alive(attempt.owner)) throw blocked(`Producer died without terminal evidence: ${attempt.attemptId}`);
+    await delay(50, undefined, { signal });
+  }
+}
+
+function isAncestor(identity, processes) {
+  let cursor = processes.find(p => p.pid === process.pid);
+  const seen = new Set();
+  while (cursor && !seen.has(cursor.pid)) {
+    if (same(identity, cursor)) return true;
+    seen.add(cursor.pid); cursor = processes.find(p => p.pid === cursor.ppid);
+  }
+  return false;
+}
+async function inheritedSlot(env, home, signal) {
+  if (!env.DD_FLOW_VERIFICATION_SLOT) return false;
+  let context;
+  try { context = JSON.parse(env.DD_FLOW_VERIFICATION_SLOT); } catch { throw blocked('Malformed inherited slot'); }
+  for (;;) {
+    const owner = optional(path.join(home, 'lease', 'owner.json')), processes = snapshot();
+    const group = owner?.groups?.find(g => g.token === context.token);
+    if (!group || owner.token !== context.owner || !alive(owner, processes)) break;
+    // A child may reach its first import before spawn() publishes its identity.
+    if (!group.pid) { await delay(10, undefined, { signal }); continue; }
+    if (isAncestor(group, processes)) return { owner, group };
+    break;
+  }
+  throw blocked('Inherited slot is not owned by an ancestor job');
+}
+async function nestedScope(env, home, outer, signal) {
+  if (!env.DD_FLOW_VERIFICATION_NESTED_SLOT) return outer ? `${outer.owner.token}-${outer.group.token}` : null;
+  let context;
+  try { context = JSON.parse(env.DD_FLOW_VERIFICATION_NESTED_SLOT); } catch { throw blocked('Malformed nested slot'); }
+  if (!outer || !/^[a-f0-9-]+$/.test(context.scope ?? '')) throw blocked('Invalid nested slot scope');
+  for (;;) {
+    const owner = optional(path.join(home, 'nested-slots', context.scope, 'owner.json')), processes = snapshot();
+    const child = owner?.groups?.find(group => group.token === context.child);
+    if (!child || owner.token !== context.owner || !alive(owner, processes)) break;
+    if (!child.pid) { await delay(10, undefined, { signal }); continue; }
+    if (isAncestor(child, processes)) return `${owner.token}-${child.token}`;
+    break;
+  }
+  throw blocked('Nested slot is not owned by an ancestor dispatch');
+}
+
+/** FIFO host-wide pool; descriptors are child commands, never callbacks sharing
+ * process.env. Exclusive drains both slots; inherited runners use one slot. */
+export async function runJobs(jobs, { jobs: budget = 2, signal, env = process.env, coordinationHome } = {}) {
+  const queuedAt = Date.now();
+  if (![1, 2].includes(budget)) throw new Error('Verification budget must be 1 or 2');
+  if (Array.isArray(jobs) && jobs.some(job => job?.credentialKeys !== undefined && (!Array.isArray(job.credentialKeys) || job.credentialKeys.some(name => typeof name !== 'string' || !providerCredentials.includes(name))))) throw new Error('Invalid credential allowlist');
+  if (!Array.isArray(jobs) || jobs.some(job=>!job || typeof job.id!=='string' || !job.id || typeof job.command!=='string' || !job.command || job.args && (!Array.isArray(job.args)||job.args.some(arg=>typeof arg!=='string')) || job.executionClass!==undefined && !['isolated','exclusive'].includes(job.executionClass)) || new Set(jobs.map(job=>job.id)).size!==jobs.length) throw new Error('Invalid/duplicate verification job descriptor');
+  const home = coordinationHome ?? env.DD_FLOW_VERIFICATION_COORDINATION_HOME ?? path.join(realHome, '.dd-flow', 'verification-coordinator');
+  const nested = await inheritedSlot(env, home, signal);
+  const scope = await nestedScope(env, home, nested, signal);
+  const lock = scope ? path.join(home, 'nested-slots', scope) : path.join(home, 'lease');
+  const owner = await claim(lock, signal);
+  // A dead nested coordinator cannot free this slot while its outer group lives.
+  if (nested) { owner.groups = [{ ...nested.group, token: 'outer-group' }]; atomicJson(path.join(lock, 'owner.json'), owner); }
+  const results = new Array(jobs.length);
+  const active = new Set();
+  let failure;
+  const save = () => { if (owner) atomicJson(path.join(lock, 'owner.json'), owner); };
+  const start = (job, index) => {
+    signal?.throwIfAborted();
+    if (failure) throw failure;
+    const promise = execute(job, { home, owner, nested, scope, signal, env, save, queuedAt }).then(result => { results[index] = result; }, error => { failure ??= error; }).finally(() => active.delete(promise));
+    active.add(promise); return promise;
+  };
+  try {
+    for (let i = 0; i < jobs.length; i++) {
+      signal?.throwIfAborted();
+      if (failure) throw failure;
+      if (jobs[i].executionClass === 'exclusive') { await Promise.all(active); await start(jobs[i], i); }
+      else { while (active.size >= (nested ? 1 : budget)) await Promise.race(active); start(jobs[i], i); }
+    }
+    await Promise.all(active);
+    if (failure) throw failure;
+    return results;
+  } finally {
+    await Promise.allSettled(active);
+    // Never release a lease after unknown cleanup.
+    if (nested && owner.groups.every(group => group.token === 'outer-group')) owner.groups = [];
+    if (owner.groups.length === 0) release(lock, owner);
+  }
+}
+
+async function execute(job, { home, owner, nested, scope, signal, env, save, queuedAt }) {
+  const started = Date.now();
+  const attemptId = randomUUID();
+  const root = path.join(home, 'jobs', attemptId);
+  fs.mkdirSync(root, { recursive: true });
+  const childEnv = { ...env, ...job.env };
+  for (const name of providerCredentials) if (!job.credentialKeys?.includes(name)) delete childEnv[name];
+  childEnv.DD_FLOW_VERIFICATION_COORDINATION_HOME = home;
+  // node:test sets this private flag for its own children; a separately managed
+  // test command must produce a standalone report, not use its parent's IPC.
+  delete childEnv.NODE_TEST_CONTEXT;
+  for (const name of ['HOME', 'XDG_CACHE_HOME', 'XDG_CONFIG_HOME', 'XDG_RUNTIME_DIR', 'CODEX_HOME', 'AGY_HOME', 'DD_FLOW_HOME', 'DD_FLOW_RESOURCE_HOME', 'DD_FLOW_CONFIG_HOME']) {
+    childEnv[name] = path.join(root, name.toLowerCase()); fs.mkdirSync(childEnv[name], { recursive: true });
+  }
+  // Unix socket paths have a small OS limit. Keep the per-attempt temporary
+  // world short even when the durable coordinator/report home is deeply nested.
+  const tempBase = process.platform === 'win32' ? os.tmpdir() : fs.realpathSync('/tmp');
+  childEnv.TMPDIR = fs.mkdtempSync(path.join(tempBase, 'ddv-'));
+  atomicJson(path.join(root, 'temporary.json'), { tmpdir: childEnv.TMPDIR });
+  // Only an explicit native/delivery descriptor may opt into provider credentials.
+  const token = randomUUID();
+  if (!nested) {
+    childEnv.DD_FLOW_VERIFICATION_SLOT = JSON.stringify({ owner: owner.token, token });
+    delete childEnv.DD_FLOW_VERIFICATION_NESTED_SLOT;
+  } else {
+    childEnv.DD_FLOW_VERIFICATION_SLOT = env.DD_FLOW_VERIFICATION_SLOT;
+    childEnv.DD_FLOW_VERIFICATION_NESTED_SLOT = JSON.stringify({ scope, owner: owner.token, child: token });
+  }
+  // Unknown spawn outcome must retain the lease after coordinator death.
+  owner.groups.push({ token, attemptId, root, pgid: null }); save();
+  const child = spawn(job.command, job.args ?? [], { cwd: job.cwd, env: childEnv, stdio: job.stdio ?? 'inherit', detached: !nested });
+  let spawnError;
+  const closed = new Promise(resolve => child.once('close', resolve));
+  const completion = new Promise(resolve => { child.once('error', error => { spawnError = error; resolve({ code: null, signal: null }); }); child.once('exit', (code, exitSignal) => resolve({ code, signal: exitSignal })); });
+  // A pipe is owned by this helper, not exposed to callers. Drain it while
+  // preserving output; an orphan holding it open must not hide direct exit.
+  for (const [name, stream] of [['stdout', child.stdout], ['stderr', child.stderr]]) stream?.on('data', bytes => fs.appendFileSync(path.join(root, `${name}.log`), bytes));
+  let identity;
+  if (child.pid) identity = snapshot().find(p => p.pid === child.pid && !p.zombie);
+  if (identity && owner) { identity = { ...identity, token, attemptId, root }; owner.groups = owner.groups.map(g => g.token === token ? identity : g); save(); }
+  let cleanupError;
+  const stop = (killSignal = 'SIGTERM') => {
+    if (!identity) return;
+    try {
+      const current = snapshot().find(p => p.pid === identity.pid);
+      if (same(identity, current)) process.kill(nested ? identity.pid : -identity.pgid, killSignal);
+    } catch (error) { if (error.code !== 'ESRCH') cleanupError = error; }
+  };
+  let forceTimer;
+  const cancel = () => { stop(); forceTimer = setTimeout(() => stop('SIGKILL'), 1000); };
+  signal?.addEventListener('abort', cancel, { once: true });
+  if (signal?.aborted) cancel();
+  const result = await completion;
+  clearTimeout(forceTimer);
+  signal?.removeEventListener('abort', cancel);
+  try {
+  if (cleanupError) throw cleanupError;
+  if (identity && !nested) {
+    for (let n = 0; n < 100 && snapshot().some(p => p.pgid === identity.pgid && !p.zombie); n++) {
+      stop(); await delay(50);
+    }
+    if (snapshot().some(p => p.pgid === identity.pgid && !p.zombie)) throw blocked(`Owned group cleanup unconfirmed: ${identity.pgid}`);
+  }
+  if (child.pid && !identity && snapshot().some(p => !p.zombie && (nested ? p.pid === child.pid : p.pgid === child.pid))) throw blocked(`Spawned process identity unconfirmed: ${child.pid}`);
+  const ioClosed = await Promise.race([closed.then(() => true), delay(5000, undefined, { ref: false }).then(() => false)]);
+  if (!ioClosed) {
+    owner.groups = owner.groups.map(group => group.token === token ? { ...group, pgid: null, reason: 'stdio_cleanup_unconfirmed' } : group); save();
+    throw blocked(`Owned stdio cleanup unconfirmed: ${child.pid}`);
+  }
+  // Missing startup identity is not an eternal unknown after actual exit plus
+  // positive absence of the exact spawned group. Never kill by an inferred PID.
+  owner.groups = owner.groups.filter(g => g.token !== token); save();
+  if (spawnError) throw spawnError;
+  const finished = Date.now();
+  const terminal = { id: job.id, attemptId, root, ...result, started_at: new Date(started).toISOString(), finished_at: new Date(finished).toISOString(), queue_ms: started - queuedAt, elapsed_ms: finished - started, status: signal?.aborted ? 'interrupted' : result.code === 0 ? 'passed' : 'failed' };
+  atomicJson(path.join(root, 'terminal.json'), terminal);
+  return terminal;
+  } catch (error) {
+    child.stdout?.destroy(); child.stderr?.destroy();
+    throw error;
+  }
+}