cool-workflow 0.1.80 → 0.1.82

package/dist/worker-isolation.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WORKER_ISOLATION_SCHEMA_VERSION = void 0;
-exports.createWorkerIsolation = createWorkerIsolation;
 exports.allocateWorkerScope = allocateWorkerScope;
 exports.writeWorkerManifest = writeWorkerManifest;
 exports.syncWorkerScopeFromTask = syncWorkerScopeFromTask;
@@ -33,21 +32,10 @@ const multi_agent_1 = require("./multi-agent");
 const telemetry_attestation_1 = require("./telemetry-attestation");
 const telemetry_ledger_1 = require("./telemetry-ledger");
 const coordinator_1 = require("./coordinator");
+const helpers_1 = require("./worker-isolation/helpers");
+const paths_1 = require("./worker-isolation/paths");
+const validation_1 = require("./validation");
 exports.WORKER_ISOLATION_SCHEMA_VERSION = 1;
-const WORKER_SCOPE_FILE = "worker.json";
-const WORKER_MANIFEST_FILE = "manifest.json";
-function createWorkerIsolation(options = {}) {
-    return {
-        allocateWorkerScope: (run, task, allocateOptions) => allocateWorkerScope(run, task, { ...options, ...allocateOptions }),
-        writeWorkerManifest,
-        listWorkerScopes: (run, listOptions) => listWorkerScopes(run, listOptions),
-        getWorkerScope,
-        recordWorkerOutput,
-        recordWorkerFailure,
-        validateWorkerBoundary,
-        summarizeWorkers
-    };
-}
 function allocateWorkerScope(run, task, options = {}) {
     ensureWorkerState(run);
     const existing = task.workerId ? getWorkerScope(run, task.workerId) : undefined;
@@ -64,7 +52,7 @@ function allocateWorkerScope(run, task, options = {}) {
         return existing;
     }
     const now = new Date().toISOString();
-    const workerId = options.workerId || createWorkerId(run, task.id);
+    const workerId = options.workerId || (0, paths_1.createWorkerId)(run, task.id);
     const workerDir = node_path_1.default.join(workerRoot(run), (0, state_1.safeFileName)(workerId));
     const inputPath = node_path_1.default.join(workerDir, "input.md");
     const resultPath = node_path_1.default.join(workerDir, "result.md");
@@ -82,7 +70,10 @@ function allocateWorkerScope(run, task, options = {}) {
         extraReadPaths: options.policy?.readPaths || [],
         extraWritePaths: [...(options.policy?.writePaths || []), ...(options.policy?.allowedPaths || [])],
         allowArtifacts: options.policy?.allowArtifacts,
-        allowLogs: options.policy?.allowLogs
+        allowLogs: options.policy?.allowLogs,
+        // H7: persisted custom profile definitions so a custom logical id resolves
+        // against THIS worker's context (worker-specific path tokens bind correctly).
+        customProfiles: run.customSandboxProfiles
     });
     const allowedPaths = (0, sandbox_profile_1.effectiveSandboxWritePaths)(sandboxPolicy);
     (0, sandbox_profile_1.upsertRunSandboxPolicy)(run, sandboxPolicy);
@@ -123,7 +114,7 @@ function allocateWorkerScope(run, task, options = {}) {
         feedbackIds: [],
         errors: [],
         multiAgent: options.multiAgent,
-        metadata: compactMetadata({
+        metadata: (0, helpers_1.compactMetadata)({
             ...options.metadata,
             multiAgent: options.multiAgent,
             phase: task.phase,
@@ -165,7 +156,7 @@ function allocateWorkerScope(run, task, options = {}) {
         });
     }
     task.workerId = scope.id;
-    task.workerManifestPath = manifestPath(scope);
+    task.workerManifestPath = (0, paths_1.manifestPath)(scope);
     task.sandboxProfileId = sandboxPolicy.id;
     task.sandboxPolicy = sandboxPolicy;
     task.backendId = backendId;
@@ -180,8 +171,8 @@ function writeWorkerManifest(run, scope) {
     const task = run.tasks.find((candidate) => candidate.id === scope.taskId);
     const sandboxPolicy = scope.sandboxPolicy || sandboxPolicyForBoundary(run, scope);
     const sandboxProfileId = scope.sandboxProfileId || sandboxPolicy.id;
-    const scopePath = workerScopePath(scope);
-    const workerManifestPath = manifestPath(scope);
+    const scopePath = (0, paths_1.workerScopePath)(scope);
+    const workerManifestPath = (0, paths_1.manifestPath)(scope);
     const manifest = {
         schemaVersion: exports.WORKER_ISOLATION_SCHEMA_VERSION,
         id: scope.id,
@@ -257,7 +248,7 @@ function syncWorkerScopeFromTask(run, workerId) {
         ...scope,
         updatedAt: new Date().toISOString(),
         multiAgent: task.multiAgent,
-        metadata: compactMetadata({
+        metadata: (0, helpers_1.compactMetadata)({
             ...(scope.metadata || {}),
             multiAgent: task.multiAgent
         })
@@ -267,7 +258,7 @@ function syncWorkerScopeFromTask(run, workerId) {
 function listWorkerScopes(run, options = {}) {
     ensureWorkerState(run);
     const scopes = loadWorkerScopesFromDisk(run);
-    run.workers = mergeScopes(run.workers || [], scopes);
+    run.workers = (0, helpers_1.mergeScopes)(run.workers || [], scopes);
     const listed = run.workers || [];
     return options.status ? listed.filter((scope) => scope.status === options.status) : listed;
 }
@@ -276,14 +267,34 @@ function getWorkerScope(run, workerId) {
     const existing = (run.workers || []).find((scope) => scope.id === workerId);
     if (existing)
         return existing;
-    const file = node_path_1.default.join(workerRoot(run), (0, state_1.safeFileName)(workerId), WORKER_SCOPE_FILE);
+    const file = node_path_1.default.join(workerRoot(run), (0, state_1.safeFileName)(workerId), paths_1.WORKER_SCOPE_FILE);
     if (!node_fs_1.default.existsSync(file))
         return undefined;
-    const scope = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    const scope = (0, validation_1.validateWorkerScope)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
     upsertWorkerScope(run, scope);
     return scope;
 }
 function recordWorkerOutput(run, workerId, resultPath, options = {}) {
+    // Accept-path orchestrator. The recorded order + side effects of these ordered
+    // steps are load-bearing (replay determinism + the hash-chained audit/telemetry
+    // ledgers cross-link by parent event ids), so each helper runs exactly where it
+    // did before and mutates the shared `accept` context in place. Do NOT reorder.
+    const accept = validateWorkerResult(run, workerId, resultPath, options);
+    const delegation = attestWorkerDelegation(accept);
+    acceptWorkerResult(accept, delegation);
+    recordWorkerDelegationLedger(accept, delegation);
+    runWorkerVerify(accept);
+    recordWorkerCompletion(accept, delegation);
+    fanOutWorkerOutput(accept);
+    if (options.persist !== false)
+        (0, state_1.saveCheckpoint)(run);
+    return accept.output;
+}
+/** Step 1 — validateResult: resolve scope/task, enforce the sandbox boundary, the
+ *  result-file existence, the envelope contract, and (opt-in) resolvable evidence.
+ *  Fail-closed: any guard records a worker failure and throws BEFORE accept-side
+ *  state mutation. Returns the partially-filled accept context on success. */
+function validateWorkerResult(run, workerId, resultPath, options) {
     const scope = requireWorkerScope(run, workerId);
     const task = requireWorkerTask(run, scope);
     const absoluteResultPath = node_path_1.default.resolve(resultPath);
@@ -302,7 +313,7 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         throw new Error(violation.message);
     }
     if (!node_fs_1.default.existsSync(absoluteResultPath)) {
-        const error = structuredError("worker-result-missing", `Worker result file does not exist: ${absoluteResultPath}`, {
+        const error = (0, helpers_1.structuredError)("worker-result-missing", `Worker result file does not exist: ${absoluteResultPath}`, {
             path: absoluteResultPath,
             retryable: true
         });
@@ -321,11 +332,35 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         const baseDirs = Array.from(new Set([run.cwd, process.cwd(), scope.workerDir, run.paths.runDir].filter(Boolean)));
         const unresolved = (0, evidence_grounding_1.unresolvedFileEvidence)(parsedResult.evidence, baseDirs);
         if (unresolved.length) {
-            const error = structuredError("worker-evidence-unresolvable", `Worker ${workerId} result cites file evidence that does not resolve on disk: ${unresolved.join(", ")}`, { path: absoluteResultPath, retryable: false });
+            const error = (0, helpers_1.structuredError)("worker-evidence-unresolvable", `Worker ${workerId} result cites file evidence that does not resolve on disk: ${unresolved.join(", ")}`, { path: absoluteResultPath, retryable: false });
             recordWorkerFailure(run, workerId, error, { ...options, persist: options.persist });
             throw new Error(error.message);
         }
     }
+    return {
+        run,
+        workerId,
+        options,
+        scope,
+        task,
+        absoluteResultPath,
+        rawResult,
+        parsedResult,
+        destination: "",
+        pathAuditId: "",
+        acceptedAuditId: "",
+        resultNode: undefined,
+        verifierNodeId: "",
+        verifierStatus: "",
+        output: undefined
+    };
+}
+/** Step 2 — attestSandbox/attestDelegation: verify the agent's signed telemetry
+ *  BEFORE recording it, enforce the opt-in require-attested-telemetry gate (still
+ *  fail-closed, pre-mutation), and build the agent-hop provenance. Non-agent hops
+ *  return an empty delegation. */
+function attestWorkerDelegation(accept) {
+    const { run, workerId, options, task, absoluteResultPath, rawResult } = accept;
     // Agent Delegation Drive (v0.1.38): if this worker's result.md was produced by an
     // EXTERNAL agent, record the agent-hop attestation AS PROVENANCE — the agent
     // (kind:process) handle, the agent-REPORTED model (never CW_AGENT_MODEL), the
@@ -345,7 +380,7 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
     // it instead of recording unverifiable usage. Default behavior is unchanged
     // (flag-and-surface). Non-agent hops carry no verdict and are never blocked.
     if (options.requireAttestedTelemetry && telemetry && telemetry.status !== "attested") {
-        const error = structuredError("telemetry-unattested-blocked", `Worker ${workerId} telemetry is ${telemetry.status} (${telemetry.reason || "unverified"}) and require-attested-telemetry is enabled — refusing to accept a hop whose usage cannot be cryptographically verified`, { path: absoluteResultPath, retryable: false });
+        const error = (0, helpers_1.structuredError)("telemetry-unattested-blocked", `Worker ${workerId} telemetry is ${telemetry.status} (${telemetry.reason || "unverified"}) and require-attested-telemetry is enabled — refusing to accept a hop whose usage cannot be cryptographically verified`, { path: absoluteResultPath, retryable: false });
         recordWorkerFailure(run, workerId, error, { ...options, persist: options.persist });
         throw new Error(error.message);
     }
@@ -365,6 +400,16 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
             ...(telemetry ? { usageAttestation: telemetry.status, usageAttestationReason: telemetry.reason } : {})
         }
         : undefined;
+    return { agentDelegation, telemetry };
+}
+/** Step 3 — recordStateNode/audit: the irreversible accept. Records the allowed
+ *  path decision, copies the result into the run results dir, completes the task,
+ *  builds + appends the result node, emits the accepted audit event, re-normalizes
+ *  node evidence against both audit ids, and surfaces the empty-capture warning.
+ *  Writes destination/pathAuditId/acceptedAuditId/resultNode back into `accept`. */
+function acceptWorkerResult(accept, delegation) {
+    const { run, workerId, scope, task, absoluteResultPath, parsedResult } = accept;
+    const { agentDelegation } = delegation;
     const pathAudit = (0, trust_audit_1.recordSandboxPathDecision)(run, {
         workerId,
         taskId: task.id,
@@ -453,58 +498,75 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
             metadata: { reason: "no findings or evidence captured from result.md", resultPath: destination }
         });
     }
+    accept.destination = destination;
+    accept.pathAuditId = pathAudit.id;
+    accept.acceptedAuditId = acceptedAudit.id;
+    accept.resultNode = resultNode;
+}
+/** Step 4 — recordTelemetryLedger: the agent-hop attestation. Binds the telemetry
+ *  verdict into the append-only hash-chained ledger BEFORE the audit event (so the
+ *  event can cross-link the record hash), then emits the worker.agent-delegation
+ *  audit event. No-op for non-agent hops. */
+function recordWorkerDelegationLedger(accept, delegation) {
+    const { agentDelegation } = delegation;
     // The agent-hop attestation event — hung off worker.output, alongside
     // worker.backend. Recorded in trust-audit/provenance, NEVER in node evidence.
-    if (agentDelegation) {
-        // Track 1 (tamper-evidence): bind this verdict into the append-only,
-        // hash-chained telemetry ledger BEFORE the audit event, so the event can
-        // cross-link the record hash. Editing the recorded verdict/usage later breaks
-        // the chain (verifyTelemetryLedger). Only when a verdict was computed.
-        const ledgerRecord = agentDelegation.usageAttestation
-            ? (0, telemetry_ledger_1.appendTelemetryAttestation)(run, {
-                workerId,
-                taskId: task.id,
-                promptDigest: agentDelegation.promptDigest,
-                reportedUsage: agentDelegation.reportedUsage,
-                usageSignature: agentDelegation.usageSignature,
-                attestation: agentDelegation.usageAttestation,
-                attestationReason: agentDelegation.usageAttestationReason
-            })
-            : undefined;
-        (0, trust_audit_1.recordTrustAuditEvent)(run, {
-            kind: "worker.agent-delegation",
-            decision: "recorded",
-            source: "host-attested",
+    if (!agentDelegation)
+        return;
+    const { run, workerId, scope, task, resultNode, acceptedAuditId } = accept;
+    // Track 1 (tamper-evidence): bind this verdict into the append-only,
+    // hash-chained telemetry ledger BEFORE the audit event, so the event can
+    // cross-link the record hash. Editing the recorded verdict/usage later breaks
+    // the chain (verifyTelemetryLedger). Only when a verdict was computed.
+    const ledgerRecord = agentDelegation.usageAttestation
+        ? (0, telemetry_ledger_1.appendTelemetryAttestation)(run, {
             workerId,
             taskId: task.id,
-            nodeId: resultNode.id,
-            sandboxProfileId: scope.sandboxProfileId,
-            policySnapshot: scope.sandboxPolicy,
-            parentEventIds: [acceptedAudit.id],
-            metadata: {
-                backendId: agentDelegation.backendId,
-                handleKind: agentDelegation.handle.kind,
-                handleRef: agentDelegation.handle.ref,
-                model: agentDelegation.model,
-                promptDigest: agentDelegation.promptDigest,
-                resultDigest: agentDelegation.resultDigest,
-                command: agentDelegation.command,
-                args: agentDelegation.args,
-                exitCode: agentDelegation.exitCode,
-                // Track 1: the telemetry verdict travels with the agent-hop event so the
-                // audit report can surface `unattested` usage loudly. Absent ⇒ no usage.
-                ...(agentDelegation.usageAttestation
-                    ? {
-                        telemetryAttestation: agentDelegation.usageAttestation,
-                        ...(agentDelegation.usageAttestationReason ? { telemetryAttestationReason: agentDelegation.usageAttestationReason } : {}),
-                        ...(agentDelegation.reportedUsage ? { reportedUsage: agentDelegation.reportedUsage } : {}),
-                        // Cross-link to the hash-chained ledger entry (tamper-evidence).
-                        ...(ledgerRecord ? { telemetryRecordId: ledgerRecord.recordId, telemetryRecordHash: ledgerRecord.recordHash, telemetryPrevHash: ledgerRecord.prevHash } : {})
-                    }
-                    : {})
-            }
-        });
-    }
+            promptDigest: agentDelegation.promptDigest,
+            reportedUsage: agentDelegation.reportedUsage,
+            usageSignature: agentDelegation.usageSignature,
+            attestation: agentDelegation.usageAttestation,
+            attestationReason: agentDelegation.usageAttestationReason
+        })
+        : undefined;
+    (0, trust_audit_1.recordTrustAuditEvent)(run, {
+        kind: "worker.agent-delegation",
+        decision: "recorded",
+        source: "host-attested",
+        workerId,
+        taskId: task.id,
+        nodeId: resultNode.id,
+        sandboxProfileId: scope.sandboxProfileId,
+        policySnapshot: scope.sandboxPolicy,
+        parentEventIds: [acceptedAuditId],
+        metadata: {
+            backendId: agentDelegation.backendId,
+            handleKind: agentDelegation.handle.kind,
+            handleRef: agentDelegation.handle.ref,
+            model: agentDelegation.model,
+            promptDigest: agentDelegation.promptDigest,
+            resultDigest: agentDelegation.resultDigest,
+            command: agentDelegation.command,
+            args: agentDelegation.args,
+            exitCode: agentDelegation.exitCode,
+            // Track 1: the telemetry verdict travels with the agent-hop event so the
+            // audit report can surface `unattested` usage loudly. Absent ⇒ no usage.
+            ...(agentDelegation.usageAttestation
+                ? {
+                    telemetryAttestation: agentDelegation.usageAttestation,
+                    ...(agentDelegation.usageAttestationReason ? { telemetryAttestationReason: agentDelegation.usageAttestationReason } : {}),
+                    ...(agentDelegation.reportedUsage ? { reportedUsage: agentDelegation.reportedUsage } : {}),
+                    // Cross-link to the hash-chained ledger entry (tamper-evidence).
+                    ...(ledgerRecord ? { telemetryRecordId: ledgerRecord.recordId, telemetryRecordHash: ledgerRecord.recordHash, telemetryPrevHash: ledgerRecord.prevHash } : {})
+                }
+                : {})
+        }
+    });
+}
+/** Step 5 — runVerify: drive the verify pipeline stage off the accepted result node
+ *  and record the verifier node id on the task + accept context. */
+function runWorkerVerify(accept) {
+    const { run, workerId, scope, task, parsedResult, destination, resultNode } = accept;
     const verifierResult = (0, pipeline_runner_1.createPipelineRunner)({ persist: false }).runPipelineStage(run, "verify", resultNode.id, {
         outputNodeId: `${run.id}:verifier:${task.id}`,
         outputStatus: "verified",
@@ -517,14 +579,24 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         metadata: { taskId: task.id, workerId, resultNodeId: resultNode.id, sandboxProfileId: scope.sandboxProfileId }
     });
     task.verifierNodeId = verifierResult.outputNodeId;
+    accept.verifierNodeId = verifierResult.outputNodeId;
+    // Carry the verify verdict for the scope-status transition in recordWorkerCompletion.
+    accept.verifierStatus = verifierResult.status;
+}
+/** Step 6 — recordStateNode (worker record): assemble the worker output record +
+ *  host-attested usage record, then persist the worker scope with the verify-derived
+ *  status, output digest/size, and (when present) usage. */
+function recordWorkerCompletion(accept, delegation) {
+    const { run, workerId, scope, task, absoluteResultPath, rawResult, resultNode, verifierNodeId, verifierStatus, pathAuditId, acceptedAuditId } = accept;
+    const { agentDelegation, telemetry } = delegation;
     const output = {
         workerId,
         taskId: task.id,
         resultPath: absoluteResultPath,
         recordedAt: new Date().toISOString(),
         stateNodeId: resultNode.id,
-        verifierNodeId: verifierResult.outputNodeId,
-        auditEventIds: [pathAudit.id, acceptedAudit.id]
+        verifierNodeId,
+        auditEventIds: [pathAuditId, acceptedAuditId]
     };
     // Host-attested usage rides on the worker record. Recorded when the agent
     // REPORTED a model OR token usage — `unreported`/absent stays ABSENT (never
@@ -547,7 +619,7 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
     updateWorkerScope(run, {
         ...scope,
         updatedAt: new Date().toISOString(),
-        status: verifierResult.status === "advanced" ? "verified" : "completed",
+        status: verifierStatus === "advanced" ? "verified" : "completed",
         resultNodeId: resultNode.id,
         output,
         // Output integrity (v0.1.63): SHA256 digest + file size
@@ -555,20 +627,23 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         outputSizeBytes: Buffer.byteLength(rawResult, "utf8"),
         ...(usageRecord ? { usage: usageRecord } : {})
     });
-    const blackboardLinks = publishWorkerOutputToBlackboard(run, scope, task, parsedResult.summary, destination, absoluteResultPath, resultNode.evidence, acceptedAudit.id);
+    accept.output = output;
+}
+/** Step 7 — fanOut: publish the accepted output to the blackboard and record the
+ *  multi-agent worker output (linking the blackboard message/artifact refs). */
+function fanOutWorkerOutput(accept) {
+    const { run, workerId, scope, task, absoluteResultPath, parsedResult, destination, resultNode, verifierNodeId, acceptedAuditId } = accept;
+    const blackboardLinks = publishWorkerOutputToBlackboard(run, scope, task, parsedResult.summary, destination, absoluteResultPath, resultNode.evidence, acceptedAuditId);
     (0, multi_agent_1.recordMultiAgentWorkerOutput)(run, {
         workerId,
         taskId: task.id,
         resultNodeId: resultNode.id,
-        verifierNodeId: verifierResult.outputNodeId,
+        verifierNodeId,
         evidence: resultNode.evidence,
         artifactPaths: [destination, absoluteResultPath],
         blackboardMessageIds: blackboardLinks.messageIds,
         blackboardArtifactRefIds: blackboardLinks.artifactRefIds
     });
-    if (options.persist !== false)
-        (0, state_1.saveCheckpoint)(run);
-    return output;
 }
 function recordWorkerFailure(run, workerId, error, options = {}) {
     const scope = requireWorkerScope(run, workerId);
@@ -581,7 +656,7 @@ function recordWorkerFailure(run, workerId, error, options = {}) {
         status: "pending",
         loopStage: "adjust",
         inputs: { workerId, taskId: task.id, dispatchId: scope.dispatchId },
-        artifacts: workerArtifacts(scope),
+        artifacts: (0, paths_1.workerArtifacts)(scope),
         parents: task.stateNodeId ? [task.stateNodeId] : [],
         contractId: pipeline_contract_1.DEFAULT_PIPELINE_CONTRACT_ID,
         metadata: { workerId, taskId: task.id, dispatchId: scope.dispatchId, workerDir: scope.workerDir, sandboxProfileId: scope.sandboxProfileId }
@@ -636,7 +711,7 @@ function recordWorkerFailure(run, workerId, error, options = {}) {
         updatedAt: new Date().toISOString(),
         status: structured.code === "worker-boundary-violation" || structured.code.startsWith("sandbox-") ? "rejected" : "failed",
         retryCount: typeof options.retryCount === "number" ? options.retryCount : scope.retryCount,
-        feedbackIds: unique([...(scope.feedbackIds || []), feedback.id]),
+        feedbackIds: (0, helpers_1.unique)([...(scope.feedbackIds || []), feedback.id]),
         errors: [...(scope.errors || []), structured]
     });
     if (options.persist !== false)
@@ -649,7 +724,7 @@ function recordWorkerRetryAttempt(run, workerId, attempts, reason, options = {})
         ...scope,
         updatedAt: new Date().toISOString(),
         retryCount: attempts,
-        metadata: compactMetadata({
+        metadata: (0, helpers_1.compactMetadata)({
             ...scope.metadata,
             agentDelegationAttempts: attempts,
             agentDelegationLastFailure: reason
@@ -668,8 +743,8 @@ function summarizeWorkers(run) {
     const workers = listWorkerScopes(run);
     return {
         total: workers.length,
-        byStatus: countBy(workers, (scope) => scope.status),
-        manifestPaths: workers.map(manifestPath),
+        byStatus: (0, helpers_1.countBy)(workers, (scope) => scope.status),
+        manifestPaths: workers.map(paths_1.manifestPath),
         failed: workers
             .filter((scope) => scope.status === "failed" || scope.status === "rejected")
             .map((scope) => ({ id: scope.id, status: scope.status, feedbackIds: scope.feedbackIds || [] }))
@@ -705,15 +780,9 @@ function reclaimOrphans(run, now) {
     }
     if (orphans.length) {
         writeWorkerIndex(run);
-        saveWorkerCheckpoint(run);
     }
     return { runId: run.id, reclaimed: orphans.length, orphans };
 }
-function saveWorkerCheckpoint(run) {
-    // Durable write via atomic temp+rename (same contract as saveCheckpoint)
-    // For worker index, the atomic write in writeWorkerIndex already handles it.
-    // This is a no-op wrapper that signals the checkpoint boundary.
-}
 function ensureWorkerState(run) {
     run.paths.workersDir = run.paths.workersDir || node_path_1.default.join(run.paths.runDir, "workers");
     node_fs_1.default.mkdirSync(run.paths.workersDir, { recursive: true });
@@ -771,7 +840,7 @@ function updateWorkerScope(run, scope) {
     return updated;
 }
 function writeWorkerScope(scope) {
-    (0, state_1.writeJson)(workerScopePath(scope), scope);
+    (0, state_1.writeJson)((0, paths_1.workerScopePath)(scope), scope);
 }
 function writeWorkerIndex(run) {
     ensureWorkerState(run);
@@ -784,7 +853,7 @@ function writeWorkerIndex(run) {
             dispatchId: scope.dispatchId,
             status: scope.status,
             workerDir: scope.workerDir,
-            manifestPath: manifestPath(scope),
+            manifestPath: (0, paths_1.manifestPath)(scope),
             resultPath: scope.resultPath,
             sandboxProfileId: scope.sandboxProfileId,
             backendId: scope.backendId,
@@ -800,9 +869,9 @@ function loadWorkerScopesFromDisk(run) {
     return node_fs_1.default
         .readdirSync(workerRoot(run), { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
-        .map((entry) => node_path_1.default.join(workerRoot(run), entry.name, WORKER_SCOPE_FILE))
+        .map((entry) => node_path_1.default.join(workerRoot(run), entry.name, paths_1.WORKER_SCOPE_FILE))
         .filter((file) => node_fs_1.default.existsSync(file))
-        .map((file) => JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
+        .map((file) => (0, validation_1.validateWorkerScope)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8"))));
 }
 function requireWorkerScope(run, workerId) {
     const scope = getWorkerScope(run, workerId);
@@ -823,6 +892,12 @@ function sandboxPolicyForBoundary(run, scope, options = {}) {
     if (scope.sandboxPolicy && !options.policy && !options.sandboxProfileId)
         return scope.sandboxPolicy;
     const profileId = options.sandboxProfileId || options.policy?.sandboxProfileId || scope.sandboxProfileId || sandbox_profile_1.DEFAULT_SANDBOX_PROFILE_ID;
+    // H7: when the scope.sandboxPolicy snapshot is LOST, this re-resolves the policy
+    // by its logical profileId against the WORKER's paths (scope.workerDir etc.). For
+    // a CUSTOM profile the bundled lookup would throw not-found; threading
+    // run.customSandboxProfiles lets resolveSandboxProfileById re-resolve the persisted
+    // DEFINITION here — re-enforcing the same policy with worker-correct path tokens
+    // (NOT the dispatch-time paths), so a legitimate worker write is not falsely denied.
     return (0, sandbox_profile_1.sandboxPolicyForWorker)(profileId, {
         cwd: run.cwd,
         runDir: run.paths.runDir,
@@ -838,7 +913,8 @@ function sandboxPolicyForBoundary(run, scope, options = {}) {
             ...(!scope.sandboxPolicy ? scope.allowedPaths || [] : [])
         ],
         allowArtifacts: options.policy?.allowArtifacts,
-        allowLogs: options.policy?.allowLogs
+        allowLogs: options.policy?.allowLogs,
+        customProfiles: run.customSandboxProfiles
     });
 }
 function blackboardManifest(run, scope) {
@@ -927,7 +1003,7 @@ function blackboardLinkage(run, scope) {
     const role = scope.multiAgent?.roleId ? run.multiAgent?.roles.find((entry) => entry.id === scope.multiAgent?.roleId) : undefined;
     const multiAgentRun = scope.multiAgent?.runId ? run.multiAgent?.runs.find((entry) => entry.id === scope.multiAgent?.runId) : undefined;
     const blackboardId = membership?.blackboardId || group?.blackboardId || role?.blackboardId || multiAgentRun?.blackboardId;
-    const topicIds = unique([
+    const topicIds = (0, helpers_1.unique)([
         ...(membership?.topicIds || []),
         ...(group?.topicIds || []),
         ...(role?.topicIds || []),
@@ -935,94 +1011,27 @@ function blackboardLinkage(run, scope) {
     ]);
     return { blackboardId, topicIds };
 }
-function manifestPath(scope) {
-    return node_path_1.default.join(scope.workerDir, WORKER_MANIFEST_FILE);
-}
-function workerScopePath(scope) {
-    return node_path_1.default.join(scope.workerDir, WORKER_SCOPE_FILE);
-}
-// Deterministic worker id (v0.1.40 self-audit P2): a wall-clock stamp + Math.random()
-// made every dispatch mint a different id, so audit references were not reproducible
-// across re-runs of the same inputs. The id is now derived from the task plus a
-// per-task sequence (count of worker scopes already allocated for that task + 1),
-// so re-running the same workflow yields byte-identical worker ids while retries of
-// the SAME task still get a fresh, unique id. (workerId is excluded from the
-// snapshot source fingerprint, so this does not change replay digests.)
-function createWorkerId(run, taskId) {
-    const prefix = `worker-${(0, state_1.safeFileName)(taskId)}-`;
-    const seq = (run.workers || []).filter((scope) => scope.id.startsWith(prefix)).length + 1;
-    return `${prefix}${String(seq).padStart(4, "0")}`;
-}
-function workerArtifacts(scope) {
-    return [
-        { id: "worker", kind: "json", path: workerScopePath(scope) },
-        { id: "worker-manifest", kind: "json", path: manifestPath(scope) },
-        { id: "worker-input", kind: "markdown", path: scope.inputPath }
-    ];
-}
 function normalizeWorkerError(error, scope, options) {
-    if (isBoundaryViolation(error)) {
-        return structuredError(error.code, error.message, {
+    if ((0, helpers_1.isBoundaryViolation)(error)) {
+        return (0, helpers_1.structuredError)(error.code, error.message, {
             path: error.path,
             retryable: false,
             details: { allowedPaths: error.allowedPaths, workerId: scope.id, taskId: scope.taskId, sandboxProfileId: scope.sandboxProfileId }
         });
     }
-    if (isStateNodeError(error)) {
+    if ((0, helpers_1.isStateNodeError)(error)) {
         return {
             ...error,
             at: error.at || new Date().toISOString(),
             path: options.path || error.path,
             retryable: options.retryable ?? error.retryable ?? false,
-            details: compactMetadata({ ...(error.details || {}), workerId: scope.id, taskId: scope.taskId })
+            details: (0, helpers_1.compactMetadata)({ ...(error.details || {}), workerId: scope.id, taskId: scope.taskId })
         };
     }
     const message = error instanceof Error ? error.message : String(error);
-    return structuredError(options.code || "worker-runtime-error", message, {
+    return (0, helpers_1.structuredError)(options.code || "worker-runtime-error", message, {
         path: options.path,
         retryable: options.retryable ?? false,
         details: { workerId: scope.id, taskId: scope.taskId }
     });
 }
-function structuredError(code, message, options = {}) {
-    return {
-        code,
-        message,
-        at: new Date().toISOString(),
-        path: options.path,
-        retryable: options.retryable,
-        details: options.details
-    };
-}
-function isBoundaryViolation(value) {
-    return Boolean(value && typeof value === "object" && "allowedPaths" in value && "message" in value);
-}
-function isStateNodeError(value) {
-    return Boolean(value && typeof value === "object" && "code" in value && "message" in value);
-}
-function mergeScopes(left, right) {
-    const merged = [...left];
-    for (const scope of right) {
-        const index = merged.findIndex((candidate) => candidate.id === scope.id);
-        if (index >= 0)
-            merged[index] = scope;
-        else
-            merged.push(scope);
-    }
-    return merged;
-}
-function unique(values) {
-    return Array.from(new Set(values.filter(Boolean)));
-}
-function compactMetadata(value) {
-    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
-    return entries.length ? Object.fromEntries(entries) : undefined;
-}
-function countBy(items, key) {
-    const counts = {};
-    for (const item of items) {
-        const value = key(item);
-        counts[value] = (counts[value] || 0) + 1;
-    }
-    return counts;
-}

package/docs/agent-delegation-drive.7.md

@@ -131,8 +131,17 @@ node dist/cli.js backend probe agent --json      # ready iff configured, else un
 node dist/cli.js run architecture-review --drive --repo /path/to/repo --question "Is the design sound?"
 node dist/cli.js run architecture-review --drive --once --repo /path/to/repo --question "..."   # one step
 node dist/cli.js run drive <run-id> --json       # read-only preview of the next step
+
+# quickstart --resume: a guided stop-then-resume a newcomer can WITNESS in <5 min
+node dist/cli.js quickstart --resume --repo /path/to/repo --question "..."   # advances ONE step, prints a continue line
+node dist/cli.js quickstart --run <run-id> --resume                          # continues that run to completion
 ```
 
+`quickstart --resume` with no `--run` drives a single step and prints a
+copy-pasteable `cw quickstart --run <id> --resume` continue line; rerun it with the
+`--run <id>` to finish. The continuing invocation echoes `resumedFrom: <id>`. Bare
+`quickstart` (no `--resume`) is unchanged — it drives straight to completion.
+
 For faster first results, use the opt-in fast app instead of changing the full
 review contract:
 
@@ -248,3 +257,8 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 ## Fast Architecture Review (v0.1.80)
 
 Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+
+## Resumable Drive & Resume Routing (v0.1.81)
+
+Adds `run resume <id> --drive/--once` alongside `quickstart --resume`: a stopped pipeline resumes in-place, advancing to completion (`--drive`) or one deterministic step (`--once`) over the same plan->dispatch->agent-fulfill->accept->commit lifecycle, echoing `resumedFrom: <id>`. Fixes the `run resume --drive` CLI routing so the drive flag reaches the resumed run instead of being read as an app name. Replay determinism and the agent evidence triple are unchanged.
+_No behavioral change in v0.1.82 (drive/quickstart resolve the run repo via an explicit base directory rather than process.chdir; delegation behavior is unchanged)._

package/docs/cli-mcp-parity.7.md

@@ -385,3 +385,8 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 ## Fast Architecture Review (v0.1.80)
 
 Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+
+## Re-Prove Verbs on Both Surfaces (v0.1.81)
+
+v0.1.81 grows the parity surface with two new both-surface, fail-closed verbs declared once in the capability registry: `cw audit verify` / `cw_audit_verify` re-proves the trust-audit chain and exits non-zero on any unverified or corrupt chain, and `cw run inspect-archive` / `cw_run_inspect_archive` is a read-only archive integrity check. Each `cw <cmd> --json` is schema-identical to its `cw_<tool>` and validated by the same parity gate.
+_No changes in v0.1.82._

package/docs/contract-migration-tooling.7.md

@@ -127,3 +127,6 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 ## Fast Architecture Review (v0.1.80)
 
 Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+
+_No changes to the contract-migration subsystem in v0.1.81._
+_No changes in v0.1.82._