cool-workflow 0.2.0 → 0.2.2

package/dist/mcp/dispatch.js

@@ -2,7 +2,7 @@
 // mcp/dispatch.ts — the generic MCP tool-call reader over
 // core/capability-table.ts.
 //
-// MILESTONE 2 (v2/PLAN.md build order, step 2). Replaces the old build's
+// MILESTONE 2 (docs/rebuild/PLAN.md build order, step 2). Replaces the old build's
 // 196-arm `callTool` switch (src/mcp/tool-call.ts) with a data-driven
 // lookup: resolve the row by tool name, check its declared required-arg
 // groups (SPEC/mcp.md's `McpBinding.requiredArgs`), re-base `cwd` if

package/dist/mcp/server.js

@@ -2,7 +2,7 @@
 // mcp/server.ts — the stdio JSON-RPC loop: initialize / tools/list /
 // tools/call.
 //
-// MILESTONE 2 (v2/PLAN.md build order, step 2). Byte-exact port of the
+// MILESTONE 2 (docs/rebuild/PLAN.md build order, step 2). Byte-exact port of the
 // framing rules in SPEC/mcp.md's "JSON-RPC methods" / "Exact outputs" /
 // "Invariants and error behavior" #9 / "Edge cases" sections:
 //   - transport: stdin/stdout, ONE JSON object per line, no

package/dist/shell/agent-config.js

@@ -2,7 +2,7 @@
 // shell/agent-config.ts — agent delegation config: env/file/flag resolution
 // order, CW_HOME resolution, builtin:<name> expansion, PATH auto-detect.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/agent-config.ts.
 //
 // Resolution order per field: flags > env > a durable

package/dist/shell/audit-cli.js

@@ -44,6 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.auditVerifyCli = auditVerifyCli;
+exports.auditHeadCli = auditHeadCli;
 exports.auditSummaryCli = auditSummaryCli;
 exports.auditMultiAgentCli = auditMultiAgentCli;
 exports.auditPolicyCli = auditPolicyCli;
@@ -65,12 +66,36 @@ const sandbox_profile_1 = require("./sandbox-profile");
 function invocationCwd(args) {
     return typeof args.cwd === "string" && args.cwd.trim() ? path.resolve(args.cwd) : process.cwd();
 }
+/** Parse the optional truncation anchor off the CLI options / MCP args
+ *  (`--expect-head <hash>` / `--expect-count <n>`; MCP: expectHead /
+ *  expectCount). Fail-closed on a malformed count — a flag given without
+ *  a usable value must never silently weaken the check it asked for. */
+function anchorOption(args) {
+    const headRaw = args["expect-head"] ?? args.expectHead;
+    const countRaw = args["expect-count"] ?? args.expectCount;
+    const expectHead = optionalString(headRaw);
+    if (headRaw !== undefined && headRaw !== null && expectHead === undefined) {
+        throw new Error("audit verify: --expect-head requires a hash value");
+    }
+    let expectCount;
+    if (countRaw !== undefined && countRaw !== null) {
+        const parsed = Number(countRaw);
+        if (countRaw === true || !Number.isInteger(parsed) || parsed < 0) {
+            throw new Error("audit verify: --expect-count requires a non-negative integer");
+        }
+        expectCount = parsed;
+    }
+    if (expectHead === undefined && expectCount === undefined)
+        return undefined;
+    return { expectHead, expectCount };
+}
 function auditVerifyCli(runId, args) {
     if (!runId)
         throw new Error("audit verify requires a run id (cw audit verify <run-id>)");
+    const anchor = anchorOption(args);
     const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
-    const v = (0, trust_audit_1.verifyTrustAudit)(run);
-    return {
+    const v = (0, trust_audit_1.verifyTrustAudit)(run, anchor);
+    const result = {
         schemaVersion: 1,
         runId: run.id,
         present: v.present,
@@ -81,6 +106,25 @@ function auditVerifyCli(runId, args) {
         corruptLines: v.corruptLines,
         failedChecks: v.checks.filter((c) => !c.pass).map((c) => ({ name: c.name, code: c.code })),
     };
+    if (anchor) {
+        result.anchor = {
+            ...(anchor.expectHead !== undefined ? { expectHead: anchor.expectHead } : {}),
+            ...(anchor.expectCount !== undefined ? { expectCount: anchor.expectCount } : {}),
+            satisfied: !v.checks.some((c) => c.code === "trust-audit-truncated"),
+        };
+    }
+    return result;
+}
+/** `cw audit head <run>` — the chain head anchor (read-only projection).
+ *  Capture it after a run (or before publishing/exporting); later,
+ *  `cw audit verify <run> --expect-head <hash> --expect-count <n>`
+ *  re-proves the log was not shortened since the capture. */
+function auditHeadCli(runId, args) {
+    if (!runId)
+        throw new Error("audit head requires a run id (cw audit head <run-id>)");
+    const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
+    const head = (0, trust_audit_1.trustAuditHead)(run);
+    return { schemaVersion: 1, runId: run.id, eventCount: head.eventCount, headHash: head.headHash };
 }
 /** MILESTONE 11 (reporting/observability, workbench audit panels) —
  *  `cw audit summary`/`audit multi-agent`/`audit policy`/`audit judge`.

package/dist/shell/commit-summary.js

@@ -46,6 +46,7 @@ exports.commitSummaryCli = commitSummaryCli;
 exports.formatCommitSummaryText = formatCommitSummaryText;
 const path = __importStar(require("node:path"));
 const run_store_1 = require("./run-store");
+const collate_1 = require("../core/util/collate");
 function formatCommitRow(commit) {
     return {
         id: commit.id,
@@ -63,7 +64,7 @@ function formatCommitRow(commit) {
 /** Byte-exact port of the old build's `summarizeOperatorCommits`
  *  (src/operator-ux.ts:339-349). */
 function summarizeOperatorCommits(run) {
-    const commits = [...(run.commits || [])].sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+    const commits = [...(run.commits || [])].sort((left, right) => (0, collate_1.stableCompare)(left.createdAt, right.createdAt) || (0, collate_1.stableCompare)(left.id, right.id));
     const rows = commits.map(formatCommitRow);
     return {
         total: rows.length,

package/dist/shell/doctor.js

@@ -2,7 +2,7 @@
 // shell/doctor.ts — `cw doctor` environment diagnostics, in the spirit of
 // `brew doctor`.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/doctor.ts's checks this milestone needs
 // (node/agent/agent-binary/git/home-registry/repo-state). The `--onramp`
 // section (buildDoctorOnramp) is later-milestone (reporting) territory and
@@ -167,7 +167,20 @@ function runDoctor(args = {}, env = process.env, cwd = process.cwd()) {
                 });
         }
     }
-    // 3. git — only needed for commit provenance; a warn, not a hard fail.
+    // 3. Sandbox enforcement boundary — a fixed architectural fact (see
+    // docs/sandbox-profiles.7.md), not a host-specific problem to fix, so this
+    // is "ok" (informational), never "warn": CW validates sandbox policy and
+    // gates worker-output acceptance, but OS-level read/write/execute/network/
+    // env isolation is the execution host's responsibility, which this doctor
+    // run cannot itself verify. An "ok" check carries no `fix` line by
+    // convention (see the node/git checks above), so the pointer to the docs
+    // lives in `detail` instead.
+    checks.push({
+        name: "sandbox-enforceability",
+        status: "ok",
+        detail: "CW sandbox profiles validate policy and gate worker-output acceptance; OS-level read/write/execute/network/env isolation is the execution host's responsibility (see docs/sandbox-profiles.7.md's ENFORCEMENT section) — this doctor run cannot verify that host enforcement.",
+    });
+    // 4. git — only needed for commit provenance; a warn, not a hard fail.
     const git = (0, node_child_process_1.spawnSync)("git", ["--version"], { encoding: "utf8", timeout: 5000 });
     checks.push(!git.error && git.status === 0
         ? { name: "git", status: "ok", detail: `${String(git.stdout || "git").trim()}.` }
@@ -177,7 +190,7 @@ function runDoctor(args = {}, env = process.env, cwd = process.cwd()) {
             detail: "git is not available — commit provenance (git HEAD) is recorded as absent.",
             fix: "Install git (e.g. `brew install git`) if you want commit provenance.",
         });
-    // 4. Home registry — the cross-repo run index lives here; must be writable.
+    // 5. Home registry — the cross-repo run index lives here; must be writable.
     const home = env.CW_HOME && String(env.CW_HOME).trim() ? path.resolve(String(env.CW_HOME)) : path.join(os.homedir(), ".local", "state", "cool-workflow");
     checks.push(dirWritable(home)
         ? { name: "home-registry", status: "ok", detail: `Home registry location is writable (${home}).` }
@@ -187,7 +200,7 @@ function runDoctor(args = {}, env = process.env, cwd = process.cwd()) {
             detail: `Home registry location is not writable: ${home}`,
             fix: "Set $CW_HOME to a writable directory, or fix the permissions.",
         });
-    // 5. Working-dir state — per-repo runs land under <cwd>/.cw.
+    // 6. Working-dir state — per-repo runs land under <cwd>/.cw.
     const cwState = path.join(path.resolve(cwd), ".cw");
     checks.push(dirWritable(cwState)
         ? { name: "repo-state", status: "ok", detail: `Run state location is writable (${cwState}).` }

package/dist/shell/drive.js

@@ -3,19 +3,14 @@
 // once per step and performs the spawn/commit/cache-write IO the
 // decision names.
 //
-// MILESTONE 6+7 (combined; see v2/PLAN.md Open risk 9/10 — the LARGEST
+// MILESTONE 6+7 (combined; see docs/rebuild/PLAN.md Open risk 9/10 — the LARGEST
 // milestone). Byte-exact port of the old build's src/drive.ts's
 // imperative shell around the pure decision core now in
 // core/pipeline/drive-decide.ts. Sub-workflow nesting and `--incremental`
-// are ported; the concurrent-round driver (driveConcurrentRound) is
-// scoped down to the serial driver run through a width loop, since no
-// case in this milestone's combined gate exercises true concurrent-batch
-// recording order (that is `--concurrency`/parallel-phase-specific and is
-// authored as its own future conformance case per Open risk 5) — the
-// `mode:"parallel"` architecture-review phases still complete correctly
-// through the serial per-task loop, just without the wall-clock-parallel
-// spawn optimization; this is flagged here rather than silently ported as
-// if fully equivalent.
+// are ported; the concurrent-round driver (driveConcurrentRound, below)
+// dispatches and settles a whole round's tasks in one batch (see
+// `--concurrency`/`roundWidth`), pinned by
+// v2/conformance/cases/pipeline-concurrent-round.case.js.
 //
 // Evidence: SPEC/pipeline-run.md "Drive loop — src/drive.ts".
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -76,8 +71,8 @@ const trust_audit_1 = require("./trust-audit");
 const agent_config_1 = require("./agent-config");
 const registry_1 = require("./execution-backend/registry");
 const agent_1 = require("./execution-backend/agent");
-const local_1 = require("./execution-backend/local");
 const hash_1 = require("../core/hash");
+const collate_1 = require("../core/util/collate");
 const pipeline_1 = require("./pipeline");
 const reporter_1 = require("./reporter");
 const fs_atomic_1 = require("./fs-atomic");
@@ -192,7 +187,10 @@ function previousPhaseResultsDigest(run, task) {
         return undefined;
     const previousTaskIds = new Set(run.phases.slice(0, phaseIndex).flatMap((p) => p.taskIds));
     const records = [];
-    for (const candidate of run.tasks.filter((t) => previousTaskIds.has(t.id)).sort((a, b) => a.id.localeCompare(b.id))) {
+    // stableCompare (not a bare localeCompare): this order feeds the sha256
+    // digest below, which feeds the incremental cache key — a host-locale-
+    // dependent order would silently move the cache key across machines.
+    for (const candidate of run.tasks.filter((t) => previousTaskIds.has(t.id)).sort((a, b) => (0, collate_1.stableCompare)(a.id, b.id))) {
         if (candidate.status !== "completed" || !candidate.resultPath || !fs.existsSync(candidate.resultPath)) {
             records.push(undefined);
             continue;
@@ -304,7 +302,24 @@ function processSelectedTask(ctx, selectedId, preparedOutcome, deferPersist = fa
         emitProgress(`↺ ${selected.label || selected.id} (${selected.phase}) — accepting cached result`);
         try {
             fs.writeFileSync(manifest.resultPath, fs.readFileSync(cachePath, "utf8"), "utf8");
+            // Not gated by requireAttestedTelemetry here: the underlying result was
+            // already gated (attested or explicitly overridden) at its FIRST
+            // acceptance, before it was cached. Re-blocking a cache hit would only
+            // punish the operator for their own earlier, already-audited accept.
+            // Still made visible, not silent: when the operator requires attested
+            // telemetry, record that this particular accept came from the cache
+            // rather than a freshly re-verified hop.
             (0, worker_isolation_1.recordWorkerOutput)(run, workerId, manifest.resultPath);
+            if (ctx.config.requireAttestedTelemetry) {
+                (0, trust_audit_1.recordTrustAuditEvent)(run, {
+                    kind: "telemetry.cache-accept",
+                    decision: "recorded",
+                    source: "cw-validated",
+                    workerId,
+                    taskId: selected.id,
+                    metadata: { reason: "result-cache hit; original attestation gate applied at first acceptance, not re-verified here" },
+                });
+            }
             // Advance the run lifecycle stage on accept, as the old build's
             // recordWorkerOutput wrapper did (run.loopStage = "observe").
             run.loopStage = "observe";
@@ -384,6 +399,25 @@ function processSelectedTask(ctx, selectedId, preparedOutcome, deferPersist = fa
     catch (error) {
         return handleHop(ctx, selected, workerId, `result.md rejected: ${errMessage(error)}`, deferPersist, deferPersist ? run : undefined);
     }
+    // Trust visibility (purely additive, no execution-behavior change): when
+    // the agent backend forwarded provider-namespace env vars (CW_/ANTHROPIC_/
+    // etc.) to the delegated child, record the NAMES (never values) as their
+    // own tamper-evident audit event, mirroring the worker.sub-workflow event
+    // pattern above. Only ever populated by execution-backend/agent.ts's
+    // recordedAgentHandle() — a no-op for every other backend.
+    const forwardedEnvVars = handle?.metadata?.forwardedEnvVars || [];
+    if (forwardedEnvVars.length) {
+        (0, trust_audit_1.recordTrustAuditEvent)(run, {
+            kind: "worker.agent-env",
+            decision: "delegated",
+            source: "runtime-derived",
+            workerId,
+            taskId: selected.id,
+            nodeId: selected.resultNodeId,
+            envVars: forwardedEnvVars,
+            metadata: { reason: "provider-namespace env vars forwarded from host process env to the delegated agent child" },
+        });
+    }
     if (cachePath && fs.existsSync(manifest.resultPath)) {
         writeResultCache(cachePath, fs.readFileSync(manifest.resultPath, "utf8"));
     }
@@ -664,13 +698,7 @@ function prepareConcurrentOutcomes(ctx, batch) {
         if (job) {
             const sandboxPolicy = manifest.sandboxPolicy;
             if (sandboxPolicy) {
-                const filteredEnv = (0, local_1.buildChildEnv)(sandboxPolicy);
-                for (const key of Object.keys(process.env)) {
-                    if (/^(CW_|ANTHROPIC_|OPENAI_|GEMINI_|DEEPSEEK_|CODEX_|GOOGLE_|COHERE_|MISTRAL_|OLLAMA_|AZURE_|AWS_)/i.test(key)) {
-                        filteredEnv[key] = process.env[key];
-                    }
-                }
-                job.env = filteredEnv;
+                job.env = (0, agent_1.buildAgentChildEnv)(sandboxPolicy).env;
             }
             jobs.push(job);
             jobTaskIds.push(taskId);

package/dist/shell/evidence-reasoning.js

@@ -29,6 +29,7 @@ const fs_atomic_1 = require("./fs-atomic");
 const multi_agent_operator_ux_1 = require("./multi-agent-operator-ux");
 const trust_audit_1 = require("./trust-audit");
 const trust_policy_1 = require("../core/multi-agent/trust-policy");
+const collate_1 = require("../core/util/collate");
 exports.EVIDENCE_REASONING_SCHEMA_VERSION = 1;
 function candidatesOf(run) {
     return (run.candidates || []);
@@ -56,7 +57,7 @@ function buildEvidenceReasoningReport(run, options = {}) {
     const counterfactuals = deriveCounterfactuals(run, scores);
     const chains = operator.evidence
         .map((evidence) => buildChain(run, evidence, { scores, auditEvents, counterfactuals }))
-        .sort((left, right) => statusRank(left.evidenceStatus) - statusRank(right.evidenceStatus) || left.id.localeCompare(right.id));
+        .sort((left, right) => statusRank(left.evidenceStatus) - statusRank(right.evidenceStatus) || (0, collate_1.stableCompare)(left.id, right.id));
     const totals = summarizeTotals(chains);
     const currentFingerprint = fingerprintChains(chains);
     const persisted = options.index;
@@ -340,7 +341,7 @@ function refreshEvidenceReasoning(run) {
         generatedAt: new Date().toISOString(),
         sourceFingerprint: report.sourceFingerprint,
         totals: report.totals,
-        entries: entries.sort((a, b) => a.id.localeCompare(b.id)),
+        entries: entries.sort((a, b) => (0, collate_1.stableCompare)(a.id, b.id)),
         paths: { reasoningDir: dir, indexPath, reportPath },
         nextAction: `node scripts/cw.js multi-agent reasoning ${run.id}`,
     };
@@ -601,5 +602,5 @@ function unique(values) {
     return Array.from(new Set(values.filter(Boolean))).sort();
 }
 function byRef(a, b) {
-    return a.ref.localeCompare(b.ref);
+    return (0, collate_1.stableCompare)(a.ref, b.ref);
 }

package/dist/shell/execution-backend/agent.js

@@ -2,7 +2,7 @@
 // shell/execution-backend/agent.ts — agent-delegation pure helpers +
 // concurrent batch fulfillment.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/execution-backend/agent.ts. This module holds
 // the PURE data-transform helpers (invocation resolution, arg substitution,
 // secret redaction, report parsing) plus the batch delegate-child spawn.
@@ -49,6 +49,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentChildEnv = buildAgentChildEnv;
 exports.resolveAgentInvocation = resolveAgentInvocation;
 exports.stripSecretArgs = stripSecretArgs;
 exports.parseAgentReport = parseAgentReport;
@@ -70,6 +71,35 @@ const envelopes_1 = require("./envelopes");
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
+const AGENT_PROVIDER_KEY_ENV_RE = /^(CW_|ANTHROPIC_|OPENAI_|GEMINI_|DEEPSEEK_|CODEX_|GOOGLE_|COHERE_|MISTRAL_|OLLAMA_|AZURE_|AWS_)/i;
+/** Build the env for a REAL spawned agent child under a sandbox policy: the
+ *  policy's own PATH+HOME+expose/deny base (buildChildEnv), plus provider-key
+ *  vars (the CW_, ANTHROPIC_, etc. prefixes), plus USER. USER is not a provider key, but a
+ *  real vendor CLI (claude, at least) reads it to resolve its own OS-level
+ *  login/keychain credential in headless mode -- buildChildEnv alone keeps
+ *  only PATH+HOME under the readonly policy, so a spawned agent that IS
+ *  logged in interactively reported "Not logged in" here. Found live: PATH+
+ *  HOME alone reproduces it, adding USER back fixes it, LOGNAME alone does
+ *  not. This is the ONE place that builds this env -- the single-request
+ *  (runAgentProcess) and concurrent-batch (shell/drive.ts) spawn paths both
+ *  call it, so the allowlist cannot drift into a second silent copy again.
+ *  Returns the forwarded var NAMES too (never values) for the
+ *  worker.agent-env trust-audit event. */
+function buildAgentChildEnv(policy, baseEnv = process.env) {
+    const env = (0, local_1.buildChildEnv)(policy, baseEnv);
+    const forwarded = [];
+    for (const key of Object.keys(baseEnv)) {
+        if (AGENT_PROVIDER_KEY_ENV_RE.test(key)) {
+            env[key] = baseEnv[key];
+            forwarded.push(key);
+        }
+    }
+    if (baseEnv.USER !== undefined && env.USER === undefined) {
+        env.USER = baseEnv.USER;
+        forwarded.push("USER");
+    }
+    return { env, forwarded };
+}
 /** Resolve the agent invocation from the request delegation > env.
  *  Vendor-neutral; the durable file config is folded in by the drive layer
  *  before this point (see shell/agent-config.ts's resolveAgentConfig). */
@@ -203,7 +233,7 @@ function substituteAgentArg(arg, subst) {
 /** Build the recorded process handle for the envelope — secret-stripped +
  *  the agent-reported model. Same SHAPE that lands in provenance, never in
  *  evidence. */
-function recordedAgentHandle(binary, endpoint, recordedArgs, model, reportedModel, reportedUsage, usageSignature) {
+function recordedAgentHandle(binary, endpoint, recordedArgs, model, reportedModel, reportedUsage, usageSignature, forwardedEnvVars) {
     const ref = binary ? [binary, ...recordedArgs].join(" ") : endpoint || "";
     return {
         kind: "process",
@@ -217,6 +247,7 @@ function recordedAgentHandle(binary, endpoint, recordedArgs, model, reportedMode
             reportedModel,
             ...(reportedUsage ? { reportedUsage } : {}),
             ...(usageSignature ? { usageSignature } : {}),
+            ...(forwardedEnvVars && forwardedEnvVars.length ? { forwardedEnvVars } : {}),
         },
     };
 }
@@ -365,17 +396,18 @@ function runAgentProcess(descriptor, policy, request, label, attestation) {
         const realArgs = resolved.rawArgs.map((arg) => substituteAgentArg(arg, subst));
         const recordedArgs = stripSecretArgs(realArgs);
         let outcome;
+        // Names only, never values — for the worker.agent-env trust-audit event
+        // below. Stays empty for a preparedAgentOutcome (a batch-delegated child
+        // that already ran elsewhere; this code path forwards nothing itself).
+        let forwardedEnvVars = [];
         if (request.preparedAgentOutcome) {
             outcome = request.preparedAgentOutcome;
         }
         else {
             const streamStderr = shouldStreamAgentStderr(process.env, Boolean(process.stderr.isTTY));
-            const childEnv = (0, local_1.buildChildEnv)(policy);
-            for (const key of Object.keys(process.env)) {
-                if (/^(CW_|ANTHROPIC_|OPENAI_|GEMINI_|DEEPSEEK_|CODEX_|GOOGLE_|COHERE_|MISTRAL_|OLLAMA_|AZURE_|AWS_)/i.test(key)) {
-                    childEnv[key] = process.env[key];
-                }
-            }
+            const built = buildAgentChildEnv(policy);
+            const childEnv = built.env;
+            forwardedEnvVars = built.forwarded;
             const child = (0, node_child_process_1.spawnSync)(resolved.binary, realArgs, {
                 cwd: request.cwd,
                 env: childEnv,
@@ -392,7 +424,7 @@ function runAgentProcess(descriptor, policy, request, label, attestation) {
             };
         }
         if (outcome.spawnError) {
-            const handleOut = recordedAgentHandle(resolved.binary, undefined, recordedArgs, resolved.model, "unreported");
+            const handleOut = recordedAgentHandle(resolved.binary, undefined, recordedArgs, resolved.model, "unreported", undefined, undefined, forwardedEnvVars);
             return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "delegation-failed", `agent process failed to spawn: ${outcome.spawnError}`, {
                 ...attestation,
                 handle: handleOut,
@@ -402,7 +434,7 @@ function runAgentProcess(descriptor, policy, request, label, attestation) {
         const stdout = outcome.stdout;
         const report = parseAgentReport(stdout);
         const reportedModel = report.model && report.model.trim() ? report.model.trim() : "unreported";
-        const handleOut = recordedAgentHandle(resolved.binary, undefined, recordedArgs, resolved.model, reportedModel, report.usage, report.usageSignature);
+        const handleOut = recordedAgentHandle(resolved.binary, undefined, recordedArgs, resolved.model, reportedModel, report.usage, report.usageSignature, forwardedEnvVars);
         if (exitCode === null) {
             return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "delegation-failed", `agent process returned no exit code (timed out or killed)`, { ...attestation, handle: handleOut });
         }

package/dist/shell/execution-backend/ci.js

@@ -1,7 +1,7 @@
 "use strict";
 // shell/execution-backend/ci.ts — the ci delegating driver.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). The ci driver shares its
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). The ci driver shares its
 // entire HTTP-delegation body with the remote driver (byte-exact port of
 // plugins/cool-workflow/src/execution-backend.ts, which also shares
 // `runHttpDelegation` between the two); this file just re-exports the ci

package/dist/shell/execution-backend/container.js

@@ -1,7 +1,7 @@
 "use strict";
 // shell/execution-backend/container.ts — the container delegating driver.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/execution-backend.ts's container handle builder
 // (:1068-1075) and `runContainer` (:720-792).
 //

package/dist/shell/execution-backend/envelopes.js

@@ -3,7 +3,7 @@
 // every delegating driver (container/remote/ci/agent) plus the registry's
 // own refusal path.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of the
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of the
 // `delegatedEnvelope` (src/execution-backend.ts:680-713) and
 // `refusedEnvelope` (:1095-1126) helpers, factored into one shared module
 // since every delegating driver builds the identical shape (byte-stable

package/dist/shell/execution-backend/local.js

@@ -2,7 +2,7 @@
 // shell/execution-backend/local.ts — the local-execution driver body
 // (executeLocal) shared by the node/bun/shell built-in drivers.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/execution-backend.ts's `executeLocal` (lines
 // 547-626) plus the leaf helpers it needs (sha256/hasExecutable/messageOf).
 //

package/dist/shell/execution-backend/probes.js

@@ -1,7 +1,7 @@
 "use strict";
 // shell/execution-backend/probes.ts — per-backend readiness probe bodies.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/execution-backend/probes.ts. Each probe is a
 // pure free function of the host (PATH + configured env); the registry's
 // `probeBackend` wraps these with the descriptor-derived envelope.

package/dist/shell/execution-backend/registry.js

@@ -3,7 +3,7 @@
 // registerBackend, resolveBackendSelection, attestSandbox, probeBackend,
 // runBackend, and the CLI-facing inspection payloads.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/execution-backend.ts (the parts not carved into
 // local.ts/container.ts/remote.ts/ci.ts/agent.ts/probes.ts).
 //
@@ -33,6 +33,7 @@ const container_1 = require("./container");
 const remote_1 = require("./remote");
 const ci_1 = require("./ci");
 const agent_1 = require("./agent");
+const collate_1 = require("../../core/util/collate");
 exports.EXECUTION_BACKEND_SCHEMA_VERSION = 1;
 exports.DEFAULT_BACKEND_ID = "node";
 exports.SANDBOX_DIMENSIONS = ["read", "write", "command", "network", "env"];
@@ -159,7 +160,7 @@ function registeredDrivers() {
 function listBackendDescriptors() {
     return registeredDrivers()
         .map((driver) => specDescriptor(driver.spec))
-        .sort((left, right) => left.id.localeCompare(right.id));
+        .sort((left, right) => (0, collate_1.stableCompare)(left.id, right.id));
 }
 function backendIds() {
     return registeredDrivers()

package/dist/shell/execution-backend/remote.js

@@ -2,7 +2,7 @@
 // shell/execution-backend/remote.ts — remote/ci delegating drivers (shared
 // HTTP-delegation body) + handle builders.
 //
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of
+// MILESTONE 5 (docs/rebuild/PLAN.md build order, step 5). Byte-exact port of
 // plugins/cool-workflow/src/execution-backend.ts's `runHttpDelegation`
 // (:821-876), `remoteHandle` (:1077-1084), `ciHandle` (:1086-1093), and
 // `delegateChildScript` (:801-811).

package/dist/shell/execution-backend/types.js

@@ -1,11 +1,2 @@
 "use strict";
-// shell/execution-backend/types.ts — plain data shapes for the driver layer.
-//
-// MILESTONE 5 (v2/PLAN.md build order, step 5). Byte-exact port of the shapes
-// in the old build's src/types/execution-backend.ts and the sandbox slice of
-// src/types/sandbox.ts that this subsystem needs. Types only — no logic — so
-// this file is safe to import from both shell/ (impure) and any future core/
-// caller without violating the core/shell purity split.
-//
-// Evidence: SPEC/execution-backend.md.
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shell/fs-atomic.js

@@ -5,7 +5,7 @@
 // `writeJson` here, so the write bytes stay exactly one place.
 //
 // Evidence: SPEC/state-core.md "Write ordering and atomic rules", "Lock
-// protocol"; v2/PLAN.md byte-compat items 1 and 6.
+// protocol"; docs/rebuild/PLAN.md byte-compat items 1 and 6.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -198,14 +198,25 @@ function durableAppendFileSync(file, data) {
 // only when still owned by this pid.
 // ---------------------------------------------------------------------------
 const FILE_LOCK_STALE_MS = 30_000;
+// Lock paths this process holds right now. A nested withFileLock on the
+// SAME target runs its fn directly (re-entrant) instead of waiting on its
+// own lock file until the 240 tries run out — that lets a whole
+// load -> change -> save cycle hold one lock while the save path inside
+// it keeps its own withFileLock call unchanged.
+const HELD_LOCKS = new Set();
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 /** Run `fn` while holding an advisory lock for `targetPath`; always released
  *  (unless the lock was stolen mid-operation, in which case releasing would
- *  corrupt the thief's critical section, so it is deliberately NOT released). */
+ *  corrupt the thief's critical section, so it is deliberately NOT released).
+ *  Re-entrant inside one process: a nested call on the same target runs
+ *  `fn` under the already-held lock. */
 function withFileLock(targetPath, fn) {
     const lock = `${targetPath}.lock`;
+    const heldKey = path.resolve(lock);
+    if (HELD_LOCKS.has(heldKey))
+        return fn();
     fs.mkdirSync(path.dirname(lock), { recursive: true });
     const pid = String(process.pid);
     let acquired = false;
@@ -234,6 +245,7 @@ function withFileLock(targetPath, fn) {
     }
     if (!acquired)
         throw new Error(`could not acquire file lock for ${targetPath}`);
+    HELD_LOCKS.add(heldKey);
     // Refresh mtime right before the critical section.
     try {
         fs.utimesSync(lock, new Date(), new Date());
@@ -263,6 +275,7 @@ function withFileLock(targetPath, fn) {
         return result;
     }
     finally {
+        HELD_LOCKS.delete(heldKey);
         try {
             // Only release if we still own the lock.
             const current = fs.readFileSync(lock, "utf8");

package/dist/shell/ledger-io.js

@@ -5,7 +5,7 @@
 //
 // MILESTONE 8. Byte-exact port of the old build's src/ledger.ts stage-2
 // git-transport functions (listLedgerEntries, unionLedgerEntries), split
-// out per v2/PLAN.md's core/shell rule since these two functions are the
+// out per docs/rebuild/PLAN.md's core/shell rule since these two functions are the
 // ONLY impure ones in the old ledger.ts module.
 //
 // Evidence: SPEC/ledger-trust.md "Handoff ledger entry" (listLedgerEntries/

package/dist/shell/metrics-cli.js

@@ -72,12 +72,14 @@ function metricsShowCli(runId, args) {
     const policy = (0, observability_1.loadCostPolicy)(args, pluginRoot());
     return (0, observability_1.showMetricsReport)(run, { now: nowOf(args), policy });
 }
-/** `cw metrics summary [--scope repo|home] [--pricing ...] [--now ISO]`. */
+/** `cw metrics summary [--scope repo|home] [--pricing ...] [--now ISO] [--limit N]`.
+ *  `--limit` defaults to RunRegistry.list()'s own 50-record floor when omitted. */
 function metricsSummaryCli(args) {
     const cwd = invocationCwd(args);
     const scope = args.scope === "home" ? "home" : "repo";
     const registry = new run_registry_io_1.RunRegistry(cwd);
-    const listing = registry.list({ scope, includeArchived: true });
+    const limit = args.limit === undefined ? undefined : Number(args.limit);
+    const listing = registry.list({ scope, includeArchived: true, limit });
     const inputs = [];
     let unreadableRuns = 0;
     for (const record of listing.records) {

package/dist/shell/multi-agent-host.js

@@ -9,7 +9,7 @@
 // deterministic step order), hostBlackboard's action dispatch. The
 // `summaries.workers/candidates/feedback/commits/operator` blocks are
 // simplified real projections (not the full operator-ux/multi-agent-
-// operator-ux module — out of this milestone's scope per v2/PLAN.md's
+// operator-ux module — out of this milestone's scope per docs/rebuild/PLAN.md's
 // build-order list) — every FIELD the conformance cases actually assert
 // on (`summaries.topologies.officialTopologies`, the envelope's fixed key
 // set, `ids.*`) is still byte-exact; the parts no case reaches are