cool-workflow 0.2.1 → 0.2.3

package/dist/shell/audit-cli.js

@@ -44,6 +44,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.auditVerifyCli = auditVerifyCli;
+exports.auditHeadCli = auditHeadCli;
+exports.auditRepairCli = auditRepairCli;
 exports.auditSummaryCli = auditSummaryCli;
 exports.auditMultiAgentCli = auditMultiAgentCli;
 exports.auditPolicyCli = auditPolicyCli;
@@ -65,12 +67,39 @@ 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.
+ *  `command` names the actual caller (`audit verify`/`audit repair`) in
+ *  the thrown message, so a bad flag always points at the command the
+ *  operator really ran. */
+function anchorOption(args, command = "audit verify") {
+    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(`${command}: --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(`${command}: --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 +110,48 @@ 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 };
+}
+/** `cw audit repair <run> [--write] [--expect-head <hash>] [--expect-count <n>]`
+ *  — repairs a torn TRAILING write in the run's trust-audit event log (the
+ *  one corruption shape a crash mid-append can produce). Default is
+ *  dry-run (report only), matching this codebase's `cw state check
+ *  [--write]` convention: pass `--write` to actually replace the log on
+ *  disk. The SAME anchor flags `cw audit verify` accepts are honored here
+ *  too: without one, a truncated-then-torn log (real history deleted,
+ *  leaving only a torn-looking fragment) can "verify" as an empty chain
+ *  and be silently accepted — passing a `--expect-head`/`--expect-count`
+ *  captured before the corruption closes that hole, exactly like it does
+ *  for verify. Fails closed (outcome:"refused") when the corruption isn't
+ *  confined to exactly the trailing line, or the anchor isn't met — see
+ *  `repairTrustAuditTornTail`'s own doc comment for the full fail-closed
+ *  contract. */
+function auditRepairCli(runId, args) {
+    if (!runId)
+        throw new Error("audit repair requires a run id (cw audit repair <run-id>)");
+    const write = Boolean(args.write);
+    const anchor = anchorOption(args, "audit repair");
+    const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
+    const result = (0, trust_audit_1.repairTrustAuditTornTail)(run, { write, anchor });
+    return { schemaVersion: 1, runId: run.id, write, ...result };
 }
 /** MILESTONE 11 (reporting/observability, workbench audit panels) —
  *  `cw audit summary`/`audit multi-agent`/`audit policy`/`audit judge`.
@@ -161,7 +232,7 @@ function auditRoleCli(runId, roleId, args) {
         panelDecisions: events.filter((event) => event.kind === "judge.panel-decision"),
         policyViolations: events.filter((event) => event.kind === "policy.violation"),
         events,
-        nextAction: `node scripts/cw.js audit multi-agent ${run.id} --json`,
+        nextAction: `cw audit multi-agent ${run.id} --json`,
     };
 }
 /** `cw audit blackboard <run>` — blackboard write/provenance audit. */
@@ -180,33 +251,38 @@ function auditBlackboardCli(runId, args) {
 /** `cw audit attest <run> [--worker …] [--command|--network|--env|--note …]`
  *  — record a host/operator sandbox attestation. */
 function auditAttestCli(runId, args) {
-    const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
-    const workerId = optionalString(args.worker ?? args.workerId);
-    const worker = workerId ? (0, worker_isolation_1.getWorkerScope)(run, workerId) : undefined;
-    const event = (0, audit_provenance_1.recordHostAttestation)(run, {
-        actor: optionalString(args.actor) || "host",
-        workerId,
-        taskId: worker?.taskId || optionalString(args.task ?? args.taskId),
-        sandboxProfileId: worker?.sandboxProfileId || optionalString(args.sandboxProfileId),
-        policySnapshot: worker?.sandboxPolicy,
-        command: optionalString(args.command),
-        networkTarget: optionalString(args.network ?? args.networkTarget),
-        metadata: {
-            note: optionalString(args.note ?? args.message),
-            hostEnforced: args.hostEnforced === undefined ? undefined : Boolean(args.hostEnforced),
-            envVars: valuesOption(args.env ?? args.envVar ?? args.envVars),
-        },
+    // Hold the state.json lock across the whole load -> record -> save so a
+    // concurrent run mutation cannot drop this attestation (lost-update class).
+    return (0, run_store_1.withRunStateLock)(runId, invocationCwd(args), (run) => {
+        const workerId = optionalString(args.worker ?? args.workerId);
+        const worker = workerId ? (0, worker_isolation_1.getWorkerScope)(run, workerId) : undefined;
+        const event = (0, audit_provenance_1.recordHostAttestation)(run, {
+            actor: optionalString(args.actor) || "host",
+            workerId,
+            taskId: worker?.taskId || optionalString(args.task ?? args.taskId),
+            sandboxProfileId: worker?.sandboxProfileId || optionalString(args.sandboxProfileId),
+            policySnapshot: worker?.sandboxPolicy,
+            command: optionalString(args.command),
+            networkTarget: optionalString(args.network ?? args.networkTarget),
+            metadata: {
+                note: optionalString(args.note ?? args.message),
+                hostEnforced: args.hostEnforced === undefined ? undefined : Boolean(args.hostEnforced),
+                envVars: valuesOption(args.env ?? args.envVar ?? args.envVars),
+            },
+        });
+        (0, run_store_1.saveCheckpoint)(run);
+        return event;
     });
-    (0, run_store_1.saveCheckpoint)(run);
-    return event;
 }
 /** `cw audit decision <run> <worker> --path|--command|--network|--env <t>`
  *  — validate a sandbox decision against the worker's policy, record it
  *  (fail-closed: a denied decision records a structured worker failure), and
  *  return the audit event. Byte-behavior port of the old recordAuditDecision. */
 function auditDecisionCli(runId, workerId, args) {
-    const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
-    return recordAuditDecision(run, workerId, args);
+    // recordAuditDecision does a load -> mutate -> saveCheckpoint; hold the
+    // state.json lock across the whole cycle so a concurrent run mutation
+    // cannot drop the recorded decision/failure (lost-update class).
+    return (0, run_store_1.withRunStateLock)(runId, invocationCwd(args), (run) => recordAuditDecision(run, workerId, args));
 }
 function recordAuditDecision(run, workerId, options) {
     const worker = (0, worker_isolation_1.getWorkerScope)(run, workerId);

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/coordinator-io.js

@@ -124,21 +124,40 @@ function requireContext(run, id) {
 }
 function requireArtifactRefs(run, ids) {
     const state = ensureBlackboardState(run);
+    // state.artifacts grows monotonically with run activity and this runs on
+    // essentially every blackboard write -- a Set built once here replaces
+    // re-scanning the whole (growing) artifacts array per referenced id
+    // (the same array-scan-per-item shape 024b007 fixed for phase/task
+    // selection).
+    const artifactIds = new Set(state.artifacts.map((artifact) => artifact.id));
     for (const id of ids)
-        if (!state.artifacts.some((artifact) => artifact.id === id))
+        if (!artifactIds.has(id))
             throw new Error(`Unknown BlackboardArtifactRef id: ${id}`);
     return cb.unique(ids);
 }
 function requireMessages(run, ids) {
     const state = ensureBlackboardState(run);
+    const messageIds = new Set(state.messages.map((message) => message.id));
     for (const id of ids)
-        if (!state.messages.some((message) => message.id === id))
+        if (!messageIds.has(id))
             throw new Error(`Unknown BlackboardMessage id: ${id}`);
     return cb.unique(ids);
 }
 function checksumFile(file) {
     return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex")}`;
 }
+const blackboardDirtySets = new WeakMap();
+function dirtySetsFor(state) {
+    let sets = blackboardDirtySets.get(state);
+    if (!sets) {
+        sets = { topics: new Set(), contexts: new Set(), artifacts: new Set(), snapshots: new Set(), decisions: new Set() };
+        blackboardDirtySets.set(state, sets);
+    }
+    return sets;
+}
+function markBlackboardDirty(state, kind, id) {
+    dirtySetsFor(state)[kind].add(id);
+}
 function linkMultiAgent(run, blackboardId, topicIds, input) {
     const groupId = input.agentGroupId ?? input.groupId;
     const roleId = input.agentRoleId ?? input.roleId;
@@ -200,16 +219,37 @@ function persistBlackboardState(run) {
         messages: state.messages.map((message) => ({ id: message.id, blackboardId: message.blackboardId, topicId: message.topicId, createdAt: message.createdAt, status: message.status, author: message.author, evidenceRefs: message.linkedEvidenceRefs, artifactRefIds: message.linkedArtifactRefIds })),
     });
     fs.writeFileSync(messagesPath(run), state.messages.sort(cb.compareRecords).map((message) => JSON.stringify(message)).join("\n") + (state.messages.length ? "\n" : ""), "utf8");
-    for (const topic of state.topics)
-        (0, fs_atomic_1.writeJson)(recordPath(run, "topics", topic.id), topic);
-    for (const context of state.contexts)
-        (0, fs_atomic_1.writeJson)(recordPath(run, "contexts", context.id), context);
-    for (const artifact of state.artifacts)
-        (0, fs_atomic_1.writeJson)(recordPath(run, "artifacts", artifact.id), artifact);
-    for (const snapshot of state.snapshots)
-        (0, fs_atomic_1.writeJson)(recordPath(run, "snapshots", snapshot.id), snapshot);
-    for (const decision of state.decisions)
-        (0, fs_atomic_1.writeJson)(recordPath(run, "decisions", decision.id), decision);
+    const dirty = dirtySetsFor(state);
+    for (const id of dirty.topics) {
+        const record = state.topics.find((entry) => entry.id === id);
+        if (record)
+            (0, fs_atomic_1.writeJson)(recordPath(run, "topics", id), record);
+    }
+    for (const id of dirty.contexts) {
+        const record = state.contexts.find((entry) => entry.id === id);
+        if (record)
+            (0, fs_atomic_1.writeJson)(recordPath(run, "contexts", id), record);
+    }
+    for (const id of dirty.artifacts) {
+        const record = state.artifacts.find((entry) => entry.id === id);
+        if (record)
+            (0, fs_atomic_1.writeJson)(recordPath(run, "artifacts", id), record);
+    }
+    for (const id of dirty.snapshots) {
+        const record = state.snapshots.find((entry) => entry.id === id);
+        if (record)
+            (0, fs_atomic_1.writeJson)(recordPath(run, "snapshots", id), record);
+    }
+    for (const id of dirty.decisions) {
+        const record = state.decisions.find((entry) => entry.id === id);
+        if (record)
+            (0, fs_atomic_1.writeJson)(recordPath(run, "decisions", id), record);
+    }
+    dirty.topics.clear();
+    dirty.contexts.clear();
+    dirty.artifacts.clear();
+    dirty.snapshots.clear();
+    dirty.decisions.clear();
 }
 function resolveBlackboard(run, input = {}) {
     const state = ensureBlackboardState(run);
@@ -238,6 +278,7 @@ function createBlackboardTopic(run, input) {
     cb.assertUnique(state.topics, id, "BlackboardTopic");
     const topic = cb.buildTopic(run.id, board, input, id, now());
     state.topics.push(topic);
+    markBlackboardDirty(state, "topics", topic.id);
     board.topicIds = cb.unique([...board.topicIds, topic.id]);
     cb.touch(board, now());
     linkMultiAgent(run, board.id, [topic.id], board.links);
@@ -270,6 +311,7 @@ function postBlackboardMessage(run, input) {
     topic.messageIds = cb.unique([...topic.messageIds, message.id]);
     board.messageCount = state.messages.filter((entry) => entry.blackboardId === board.id).length;
     cb.touch(topic, now());
+    markBlackboardDirty(state, "topics", topic.id);
     cb.touch(board, now());
     appendBlackboardNode(run, "blackboard-message", message.id, "completed", cb.truncate(message.body), messagesPath(run), [`${run.id}:blackboard:topic:${topic.id}`]);
     const audit = (0, trust_audit_1.recordTrustAuditEvent)(run, {
@@ -353,17 +395,21 @@ function putBlackboardContext(run, input) {
         superseded.status = "superseded";
         superseded.supersededByContextId = id;
         cb.touch(superseded, now());
+        markBlackboardDirty(state, "contexts", superseded.id);
     }
     const { context, conflicts } = cb.buildContext(run.id, board, topic, input, id, now(), state.contexts);
     for (const conflict of conflicts) {
         conflict.status = "conflicting";
         conflict.conflictingContextIds = cb.unique([...conflict.conflictingContextIds, context.id]);
         cb.touch(conflict, now());
+        markBlackboardDirty(state, "contexts", conflict.id);
     }
     state.contexts.push(context);
+    markBlackboardDirty(state, "contexts", context.id);
     topic.contextIds = cb.unique([...topic.contextIds, context.id]);
     board.contextIds = cb.unique([...board.contextIds, context.id]);
     cb.touch(topic, now());
+    markBlackboardDirty(state, "topics", topic.id);
     cb.touch(board, now());
     const decision = recordCoordinatorDecision(run, {
         blackboardId: board.id,
@@ -385,6 +431,11 @@ function putBlackboardContext(run, input) {
     const writeAudit = (0, trust_policy_io_1.recordBlackboardWriteAudit)(run, { operation: "context", status: context.status, actor: context.author, multiAgentRunId: context.links.multiAgentRunId, agentGroupId: context.links.agentGroupId, agentRoleId: context.links.agentRoleId, agentMembershipId: context.links.agentMembershipId, blackboardId: board.id, blackboardTopicId: topic.id, blackboardContextId: context.id, coordinatorDecisionId: decision.id, evidenceRefs: context.evidenceRefs, parentEventIds: cb.unique([...(permission ? [permission.event.id] : []), audit.id]), policyRef: permission?.policyRef, metadata: { kind: context.kind, key: context.key, conflicts: context.conflictingContextIds } });
     context.links.auditEventIds = cb.unique([...(context.links.auditEventIds || []), audit.id]);
     context.links.auditEventIds = cb.unique([...(context.links.auditEventIds || []), writeAudit.id]);
+    // context.decisionId (above) and both auditEventIds assignments happen AFTER
+    // recordCoordinatorDecision's own nested persistBlackboardState call already
+    // flushed and cleared the dirty set, so context must be re-marked here or
+    // this call's final persist would skip rewriting it.
+    markBlackboardDirty(state, "contexts", context.id);
     persistBlackboardState(run);
     return context;
 }
@@ -405,17 +456,24 @@ function addBlackboardArtifact(run, input) {
     const checksum = absolutePath && fs.existsSync(absolutePath) && fs.statSync(absolutePath).isFile() ? checksumFile(absolutePath) : undefined;
     const artifact = cb.buildArtifact(run.id, board, topic, input, id, now(), absolutePath, checksum);
     state.artifacts.push(artifact);
+    markBlackboardDirty(state, "artifacts", artifact.id);
     board.artifactRefIds = cb.unique([...board.artifactRefIds, artifact.id]);
     if (topic)
         topic.artifactRefIds = cb.unique([...topic.artifactRefIds, artifact.id]);
     cb.touch(board, now());
-    if (topic)
+    if (topic) {
         cb.touch(topic, now());
+        markBlackboardDirty(state, "topics", topic.id);
+    }
     const decision = recordCoordinatorDecision(run, { blackboardId: board.id, topicId: topic?.id, kind: "artifact-index", outcome: "accepted", reason: `Indexed ${artifact.kind} artifact ${artifact.id}`, subjectIds: [artifact.id], evidenceRefs: artifact.evidenceRefs, artifactRefIds: [artifact.id], author: { kind: "coordinator", id: "cw" }, scope: artifact.scope, tags: ["artifact", artifact.kind] });
     appendBlackboardNode(run, "blackboard-artifact", artifact.id, "completed", artifact.kind, recordPath(run, "artifacts", artifact.id), [topic ? `${run.id}:blackboard:topic:${topic.id}` : `${run.id}:blackboard:${board.id}`]);
     const audit = (0, trust_audit_1.recordTrustAuditEvent)(run, { kind: "blackboard.artifact", decision: "accepted", source: cb.sourceForAuthor(artifact.author), actor: artifact.author.id, blackboardId: board.id, blackboardTopicId: topic?.id, blackboardArtifactRefId: artifact.id, coordinatorDecisionId: decision.id, workerId: artifact.provenance.workerId, taskId: artifact.provenance.taskId, candidateId: artifact.provenance.candidateId, commitId: artifact.provenance.commitId, normalizedPath: absolutePath, evidenceRefs: artifact.evidenceRefs, parentEventIds: artifact.trustAuditEventIds, metadata: { kind: artifact.kind, locator: artifact.locator, checksum: artifact.checksum } });
     const writeAudit = (0, trust_policy_io_1.recordBlackboardWriteAudit)(run, { operation: "artifact", status: artifact.status, actor: artifact.author, multiAgentRunId: artifact.provenance.multiAgentRunId, agentGroupId: artifact.provenance.agentGroupId, agentRoleId: artifact.provenance.agentRoleId, agentMembershipId: artifact.provenance.agentMembershipId, blackboardId: board.id, blackboardTopicId: topic?.id, blackboardArtifactRefId: artifact.id, coordinatorDecisionId: decision.id, evidenceRefs: artifact.evidenceRefs, parentEventIds: cb.unique([...(permission ? [permission.event.id] : []), audit.id]), policyRef: permission?.policyRef, metadata: { kind: artifact.kind, locator: artifact.locator, checksum: artifact.checksum } });
     artifact.trustAuditEventIds = cb.unique([...artifact.trustAuditEventIds, audit.id, writeAudit.id]);
+    // Happens AFTER recordCoordinatorDecision's own nested persist already
+    // flushed and cleared the dirty set — re-mark or this call's final persist
+    // would skip rewriting the artifact.
+    markBlackboardDirty(state, "artifacts", artifact.id);
     persistBlackboardState(run);
     return artifact;
 }
@@ -428,6 +486,7 @@ function createBlackboardSnapshot(run, blackboardId) {
     const messageIds = state.messages.filter((entry) => entry.blackboardId === board.id).map((entry) => entry.id);
     const snapshot = cb.buildSnapshot(run.id, board, id, now(), snapshotPath, board.paths.index, summary, messageIds);
     state.snapshots.push(snapshot);
+    markBlackboardDirty(state, "snapshots", snapshot.id);
     board.snapshotIds = cb.unique([...board.snapshotIds, snapshot.id]);
     cb.touch(board, now());
     appendBlackboardNode(run, "blackboard-snapshot", snapshot.id, "completed", snapshot.id, snapshotPath, [`${run.id}:blackboard:${board.id}`]);
@@ -447,6 +506,7 @@ function recordCoordinatorDecision(run, input) {
     requireMessages(run, input.messageIds || []);
     const decision = cb.buildDecision(run.id, board, input, id, now());
     state.decisions.push(decision);
+    markBlackboardDirty(state, "decisions", decision.id);
     board.decisionIds = cb.unique([...board.decisionIds, decision.id]);
     cb.touch(board, now());
     appendBlackboardNode(run, "coordinator-decision", decision.id, cb.coordinatorStatusToNodeStatus(decision.status), `${decision.kind}:${decision.outcome}`, recordPath(run, "decisions", decision.id), [`${run.id}:blackboard:${board.id}`, ...(input.topicId ? [`${run.id}:blackboard:topic:${input.topicId}`] : [])]);

package/dist/shell/dispatch.js

@@ -145,7 +145,7 @@ function createDispatchManifest(run, limit, options = {}) {
         dispatchId,
         createdAt: now,
         phase: tasks[0].phase,
-        instructions: "Spawn one worker per task when the user explicitly authorized agent/parallel/background work. Save each final summary as Markdown and record it with `cw.js result <run-id> <task-id> <file>`.",
+        instructions: "Spawn one worker per task when the user explicitly authorized agent/parallel/background work. Save each final summary as Markdown and record it with `cw result <run-id> <task-id> <file>`.",
         tasks: selectedRunTasks.map(dispatch_1.formatDispatchTask),
         manifestPath,
         stateNodeId: dispatchNode.id,

package/dist/shell/doctor.js

@@ -64,6 +64,8 @@ const path = __importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const agent_config_1 = require("./agent-config");
 const onramp_1 = require("./onramp");
+const run_store_1 = require("./run-store");
+const trust_audit_1 = require("./trust-audit");
 const term_1 = require("./term");
 function whichBinary(bin, env) {
     if (bin.includes("/") || bin.includes("\\")) {
@@ -210,6 +212,75 @@ function runDoctor(args = {}, env = process.env, cwd = process.cwd()) {
             detail: `Cannot write run state under ${cwState}.`,
             fix: "Run from a writable working directory, or pass --cwd PATH.",
         });
+    // 7. Run-state integrity — every run under <cwd>/.cw/runs must have a
+    //    LOADABLE state.json: not corrupt, not an unsupported schema, not
+    //    suspected data loss (a wiped state.json next to real task/commit/
+    //    audit content). READ-ONLY: only dry-run loads each run's state,
+    //    same as `cw status`/`cw run show` would — never writes or repairs.
+    const runsDir = path.join(path.resolve(cwd), ".cw", "runs");
+    let runDirs = [];
+    try {
+        runDirs = fs.readdirSync(runsDir).filter((name) => !name.startsWith("."));
+    }
+    catch {
+        runDirs = [];
+    }
+    const runStateProblems = [];
+    let runsScanned = 0;
+    const loadedRuns = [];
+    for (const runId of runDirs) {
+        const statePath = path.join(runsDir, runId, "state.json");
+        if (!fs.existsSync(statePath))
+            continue;
+        runsScanned += 1;
+        try {
+            const result = (0, run_store_1.loadRunStateFile)(statePath, { dryRun: true });
+            if (result.report.status === "unsupported") {
+                runStateProblems.push(`${runId}: ${result.report.errors.join("; ") || "unsupported run state"}`);
+                continue;
+            }
+            (0, run_store_1.assertNotSuspectedDataLoss)(runId, result);
+            loadedRuns.push({ runId, run: result.run });
+        }
+        catch (error) {
+            runStateProblems.push(`${runId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    checks.push(runStateProblems.length === 0
+        ? {
+            name: "run-state-integrity",
+            status: "ok",
+            detail: runsScanned > 0 ? `${runsScanned} run(s) under .cw/runs all have a loadable state.json.` : "No runs under .cw/runs yet.",
+        }
+        : {
+            name: "run-state-integrity",
+            status: "warn",
+            detail: `${runStateProblems.length} of ${runsScanned} run(s) have a state.json problem: ${runStateProblems.slice(0, 3).join(" | ")}${runStateProblems.length > 3 ? ` (+${runStateProblems.length - 3} more)` : ""}`,
+            fix: "Inspect with `cw status <run-id>` for the specific reason; restore state.json from a backup, or remove the run directory to start over.",
+        });
+    // 8. Trust-audit integrity — a torn trailing write from a crash mid-append
+    //    can make a run's audit chain fail verification forever with no
+    //    repair path. Only checked for runs that passed check 7 (a run whose
+    //    state.json itself won't load has no `run` object to check audit for).
+    const auditProblems = [];
+    for (const { runId, run } of loadedRuns) {
+        const integrity = (0, trust_audit_1.verifyTrustAudit)(run);
+        if (integrity.present && !integrity.verified) {
+            auditProblems.push(`${runId}: ${integrity.checks.filter((c) => !c.pass).map((c) => c.code).join(", ")}`);
+        }
+    }
+    checks.push(auditProblems.length === 0
+        ? {
+            name: "audit-integrity",
+            status: "ok",
+            detail: loadedRuns.length > 0 ? `Trust-audit log for all ${loadedRuns.length} loadable run(s) verifies clean.` : "No runs to check.",
+        }
+        : {
+            name: "audit-integrity",
+            status: "warn",
+            detail: `${auditProblems.length} run(s) fail trust-audit verification: ${auditProblems.slice(0, 3).join(" | ")}${auditProblems.length > 3 ? ` (+${auditProblems.length - 3} more)` : ""}`,
+            fix: "Run `cw audit repair <run-id>` to check for a repairable torn trailing write (a crash mid-append); anything else needs manual investigation, not an auto-fix.",
+        });
     const fails = checks.filter((c) => c.status === "fail").length;
     const warns = checks.filter((c) => c.status === "warn").length;
     const ok = fails === 0;
@@ -248,7 +319,15 @@ function formatDoctorReport(report) {
     lines.push("");
     const summaryGlyph = report.ok ? (0, term_1.green)("✓") : (0, term_1.red)("✗");
     lines.push(`${summaryGlyph} ${report.summary}`);
-    if (report.onramp) {
+    if (!report.onramp) {
+        // A first-time (or just not-yet-discovered) `cw doctor` never mentions
+        // the richer onramp content below without this pointer — the "Quick
+        // start (3 steps)"/"Recommended Checks"/per-scenario sections only ever
+        // render behind the `--onramp` opt-in flag, so a user who never reads
+        // `cw help doctor` has no way to find them otherwise.
+        lines.push(`  ${(0, term_1.nextHint)("cw doctor --onramp")} for the 3-step quick start`);
+    }
+    else {
         lines.push("");
         lines.push("Quick start (3 steps):");
         lines.push("  1. cw demo tamper        — prove trust checks work (30s)");