@agentskit/harness 0.3.0 → 0.4.0

package/compatibility/report.json

@@ -0,0 +1,23 @@
+{
+  "type": "agentskit-harness-compatibility-report",
+  "schemaVersion": 1,
+  "harnessVersion": "0.4.0",
+  "harnessSourceRevision": "a18b57d43f037b7a34b134e01baf913ae2341fd7",
+  "capturedAt": "2026-09-10T18:30:00Z",
+  "status": "blocked",
+  "components": [
+    { "id": "core", "package": "@agentskit/core", "version": "1.12.9", "revision": "d89a2d74108c29f2c6227948265449e985af3a0a", "status": "passed", "command": "pnpm --filter @agentskit/core test", "evidence": "34 files, 498 tests passed" },
+    { "id": "memory", "package": "@agentskit/memory", "version": "0.11.9", "revision": "d89a2d74108c29f2c6227948265449e985af3a0a", "status": "passed", "command": "pnpm --filter @agentskit/memory test", "evidence": "31 files, 228 tests passed" },
+    { "id": "eval", "package": "@agentskit/eval", "version": "0.6.5", "revision": "d89a2d74108c29f2c6227948265449e985af3a0a", "status": "passed", "command": "pnpm --filter @agentskit/eval test", "evidence": "9 files, 105 tests passed; build and bundler preparation passed" },
+    { "id": "doc-bridge", "package": "@agentskit/doc-bridge", "version": "1.7.45", "revision": "9f9e9ddd4f736981c2bea243fef33b68be2b5002", "status": "passed", "command": "pnpm build && pnpm test && pnpm typecheck", "evidence": "50 files, 351 tests passed; Cursor/Claude/Copilot/portable plugin contracts passed; typecheck passed" },
+    { "id": "code-review", "package": "@agentskit/code-review", "version": "0.30.8", "revision": "c993f9a9359157a767d738d60c30add2b02fd09a", "status": "failed", "command": "npm test; npm run quality:matrix -- --input <real-runner-artifact>", "evidence": "241 tests passed. Real run ceaf007a-ea6e-4dc9-a601-f816702b301c reached BLOCKED: detection 1/4, precision 1/4, batch-efficiency 1/4, integration 1/4; no comparable baseline." },
+    { "id": "adapter-boundary", "package": "@agentskit/harness", "version": "0.4.0", "revision": "a18b57d43f037b7a34b134e01baf913ae2341fd7", "status": "passed", "command": "pnpm test:adapters", "evidence": "covered by ak-verify run 1789063362018-21016-775q93" },
+    { "id": "runtime", "package": "@agentskit/harness", "version": "0.4.0", "revision": "a18b57d43f037b7a34b134e01baf913ae2341fd7", "status": "passed", "command": "pnpm test:runtime && pnpm test:runtime-attestation", "evidence": "covered by ak-verify run 1789063362018-21016-775q93" }
+  ],
+  "blockers": [
+    "code-review real-run quality matrix has no passing detection/precision/baseline evidence",
+    "harness-vs-no-Harness cohort is not yet comparable (10-task owner-approved cohort required)",
+    "published-registry smoke is pending the main-branch release"
+  ],
+  "baseline": { "path": "benchmarks/harness-0.4.0-baseline.json", "status": "not-run", "doNotInfer": true }
+}

package/compatibility/report.md

@@ -0,0 +1,22 @@
+# Compatibility report
+
+**Release:** `@agentskit/harness@0.4.0`  
+**Harness revision:** `a18b57d43f037b7a34b134e01baf913ae2341fd7`  
+**Captured:** 2026-09-10  
+**Decision:** BLOCKED (fail closed)
+
+## Passed boundaries
+
+- `@agentskit/core@1.12.9` at `d89a2d7`: 498/498 tests.
+- `@agentskit/memory@0.11.9` at `d89a2d7`: 228/228 tests.
+- `@agentskit/eval@0.6.5` at `d89a2d7`: 105/105 tests, including build/bundler preparation.
+- `@agentskit/doc-bridge@1.7.45` at `9f9e9d`: 351/351 tests plus plugin contracts and typecheck.
+- Harness adapter and runtime boundaries: covered by `ak-verify` run `1789063362018-21016-775q93` (21/21 checks).
+
+## Blocked evidence
+
+`@agentskit/code-review@0.30.8` passed its 241-test suite. A real fixed-provider run (`codex-cli`, `gpt-5.6-luna`, high, run `ceaf007a-ea6e-4dc9-a601-f816702b301c`) completed coverage, safety, reliability, memory, configuration, and actionability checks, but the quality matrix blocked on detection, precision, batch efficiency, integration, and missing comparable baselines. The result is retained as evidence, not promoted to a pass.
+
+The 0.4.0 no-Harness comparison remains unavailable because the owner-approved ten-task cohort and matching criterion-level logs have not been captured. Registry smoke can only run after the main Trusted Publishing workflow publishes the package.
+
+See [`migration.md`](migration.md), [`rollback.md`](rollback.md), and the machine-readable [`report.json`](report.json).

package/compatibility/rollback.md

@@ -0,0 +1,8 @@
+# Compatibility rollback rehearsal
+
+Rollback is a clean checkout at the pinned `previousVersion`, followed by the
+same adapter-boundary smoke and eval commands. Record the resulting revision,
+commands, exit codes, and evidence digest in `compatibility/report.json`.
+
+No external mutation is performed by the Harness. A missing rehearsal record
+is `unknown` and blocks release rather than being inferred as a pass.

package/dist/cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { createHash, randomUUID, createPrivateKey, createPublicKey, sign, verify } from 'crypto';
-import { readFileSync, mkdirSync, existsSync, unlinkSync, openSync, writeFileSync, closeSync, writeSync, appendFileSync, mkdtempSync, renameSync, rmSync, readdirSync } from 'fs';
+import { readFileSync, mkdirSync, existsSync, unlinkSync, openSync, writeFileSync, closeSync, readdirSync, writeSync, appendFileSync, mkdtempSync, renameSync, rmSync } from 'fs';
 import { Command } from 'commander';
 import { resolve, dirname, relative, basename, join, extname, sep } from 'path';
 import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import { tmpdir, cpus, loadavg, freemem, totalmem } from 'os';
 
-// src/constants.ts
+// src/kernel/constants.ts
 var STATES = [
   "CLARIFYING",
   "PLANNED",
@@ -37,7 +37,7 @@ var LEGAL_TRANSITIONS = {
 var REAL_CATEGORIES = /* @__PURE__ */ new Set(["endpoint", "database", "cli", "mcp", "ui"]);
 var DECISIONS = /* @__PURE__ */ new Set(["approved", "approve", "yes", "ok", "rejected", "reject", "no"]);
 
-// src/errors.ts
+// src/kernel/errors.ts
 var HarnessError = class extends Error {
   code;
   constructor(message, code = "HARNESS_ERROR") {
@@ -50,7 +50,7 @@ var fail = (message, code = "HARNESS_ERROR") => {
   throw new HarnessError(message, code);
 };
 
-// src/profiles.ts
+// src/profiles/index.ts
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var record = (value, label) => {
   if (!isRecord(value)) fail(`${label} must be an object.`, "INVALID_CONFIG");
@@ -140,7 +140,7 @@ var cleanConfiguredArtifacts = (loaded) => {
 };
 var fileContents = (path) => readFileSync(path, "utf8");
 
-// src/types.ts
+// src/kernel/types.ts
 var SURFACE_NAMES = ["logic", "endpoint", "database", "cli", "mcp", "ui", "docs"];
 var CHECK_CATEGORIES = ["build", "test", "lint", ...SURFACE_NAMES, "custom"];
 var RUN_STATES = [
@@ -157,7 +157,7 @@ var RUN_STATES = [
   "SUPERSEDED"
 ];
 
-// src/config.ts
+// src/execution/config.ts
 var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var stringValue = (value, label) => {
   if (typeof value !== "string") return fail(`${label} is required.`, "INVALID_CONFIG");
@@ -271,7 +271,7 @@ var loadConfig = (configPath = ".codex/verification.json") => {
   return { absolute, root, stateDir, config, configHash: hashJson(config) };
 };
 
-// src/state-machine.ts
+// src/kernel/state-machine.ts
 var transition = (run, to, reason, actor = "harness") => {
   if (!STATES.includes(to)) fail(`Unknown state ${to}.`, "INVALID_STATE");
   if (run.state !== to && !LEGAL_TRANSITIONS[run.state].some((state) => state === to)) fail(`Illegal transition ${run.state} -> ${to}.`, "INVALID_STATE");
@@ -287,7 +287,7 @@ var approvedDecision = (decision) => {
 };
 var HARNESS_EVENT_SCHEMA_VERSION = 1;
 var EVENT_LOG_GENESIS = "GENESIS";
-var HARNESS_EVENT_TYPES = ["run.created", "state.transitioned", "context.attached", "verification.completed", "approval.recorded", "authorization.recorded", "session.started", "session.resumed", "agent.turn.started", "policy.evaluated", "tool.approval.requested", "tool.approval.recorded", "tool.requested", "tool.execution.started", "tool.recovery.recorded", "tool.blocked", "tool.completed", "tool.failed", "session.ended"];
+var HARNESS_EVENT_TYPES = ["run.created", "state.transitioned", "context.attached", "verification.completed", "artifact.recorded", "approval.recorded", "authorization.recorded", "session.started", "session.resumed", "agent.turn.started", "policy.evaluated", "tool.approval.requested", "tool.approval.recorded", "tool.requested", "tool.execution.started", "tool.recovery.recorded", "tool.blocked", "tool.completed", "tool.failed", "session.ended"];
 var SESSION_EVENT_TYPES = /* @__PURE__ */ new Set(["session.started", "session.resumed", "agent.turn.started", "policy.evaluated", "tool.approval.requested", "tool.approval.recorded", "tool.requested", "tool.execution.started", "tool.recovery.recorded", "tool.blocked", "tool.completed", "tool.failed", "session.ended"]);
 var eventPath = (stateDir, runId) => join(stateDir, "runs", runId, "events.ndjson");
 var lockPath = (stateDir, runId) => `${eventPath(stateDir, runId)}.lock`;
@@ -416,13 +416,16 @@ var recoverEventLogLock = ({ stateDir, runId, actor, maxAgeMs = 3e5 }) => {
   return fail("Event log lock owner is still alive.", "HARNESS_ERROR");
 };
 
-// src/plugins.ts
+// src/kernel/plugins.ts
 var createPluginSlot = (id2) => {
   if (!id2.trim()) fail("Plugin slot id is required.", "INVALID_INPUT");
-  return { id: id2 };
+  return { id: id2.trim() };
 };
 
-// src/context.ts
+// src/kernel/adapter-contract.ts
+var ASSURANCE_LEVELS = ["unverified", "contract-tested", "runtime-attested"];
+
+// src/context/index.ts
 var hashContextSnapshot = ({ providerId, query, references, sourceHash: sourceHash2 }) => hashJson({ providerId, query, references, sourceHash: sourceHash2 });
 var hashContextSnapshots = (snapshots) => hashJson(snapshots.map(({ providerId, query, references, sourceHash: sourceHash2, snapshotHash }) => ({ providerId, query, references, sourceHash: sourceHash2, snapshotHash })));
 var record2 = (value, label) => {
@@ -445,17 +448,23 @@ var validateContextSnapshot = (value, index2 = 0) => {
       uri: requiredString(rawReference["uri"], `context snapshot ${index2}.references[${referenceIndex}].uri`),
       ...typeof rawReference["title"] === "string" ? { title: rawReference["title"] } : {},
       ...typeof rawReference["version"] === "string" ? { version: rawReference["version"] } : {},
-      ...typeof rawReference["contentHash"] === "string" ? { contentHash: rawReference["contentHash"] } : {}
+      ...typeof rawReference["contentHash"] === "string" ? { contentHash: rawReference["contentHash"] } : {},
+      ...rawReference["relevance"] === void 0 ? {} : typeof rawReference["relevance"] === "number" && rawReference["relevance"] >= 0 && rawReference["relevance"] <= 1 ? { relevance: rawReference["relevance"] } : fail(`context snapshot ${index2}.references[${referenceIndex}].relevance must be between 0 and 1.`, "INVALID_INPUT")
     };
   });
   const scope = rawQuery["scope"] === void 0 ? void 0 : Array.isArray(rawQuery["scope"]) && rawQuery["scope"].every((item) => typeof item === "string") ? rawQuery["scope"] : fail(`context snapshot ${index2}.query.scope must be an array of strings.`, "INVALID_INPUT");
+  const assurance = raw["assurance"] === void 0 ? void 0 : ASSURANCE_LEVELS.includes(raw["assurance"]) ? raw["assurance"] : fail(`context snapshot ${index2}.assurance is invalid.`, "INVALID_INPUT");
+  const telemetry = raw["telemetry"] === void 0 ? void 0 : record2(raw["telemetry"], `context snapshot ${index2}.telemetry`);
+  if (telemetry && telemetry["status"] !== "measured" && telemetry["status"] !== "unknown") fail(`context snapshot ${index2}.telemetry.status is invalid.`, "INVALID_INPUT");
   const snapshot = {
     providerId: requiredString(raw["providerId"], `context snapshot ${index2}.providerId`),
     query: { query: requiredString(rawQuery["query"], `context snapshot ${index2}.query.query`), ...scope ? { scope } : {}, ...typeof rawQuery["sourceRevision"] === "string" ? { sourceRevision: rawQuery["sourceRevision"] } : {} },
     references,
     sourceHash: requiredString(raw["sourceHash"], `context snapshot ${index2}.sourceHash`),
     snapshotHash: requiredString(raw["snapshotHash"], `context snapshot ${index2}.snapshotHash`),
-    resolvedAt: requiredString(raw["resolvedAt"], `context snapshot ${index2}.resolvedAt`)
+    resolvedAt: requiredString(raw["resolvedAt"], `context snapshot ${index2}.resolvedAt`),
+    ...assurance === void 0 ? {} : { assurance },
+    ...telemetry === void 0 ? {} : { telemetry }
   };
   if (snapshot.snapshotHash !== hashContextSnapshot(snapshot)) fail(`context snapshot ${index2}.snapshotHash does not match its contents.`, "INVALID_INPUT");
   return snapshot;
@@ -467,7 +476,7 @@ var readContextSnapshots = (path) => {
 var validateContextSnapshots = (snapshots) => snapshots.map((snapshot, index2) => validateContextSnapshot(snapshot, index2));
 createPluginSlot("context.provider");
 
-// src/runs.ts
+// src/execution/runs.ts
 var now = () => (/* @__PURE__ */ new Date()).toISOString();
 var newRunId = () => `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
 var saveRun2 = (stateDir, run) => {
@@ -534,8 +543,8 @@ var validateEvidence = (root, check, evidence, outcomeIds) => {
     if (evidence.capability !== "real-browser") failures.push("UI evidence must declare capability real-browser");
     if (!Array.isArray(evidence.artifacts) || evidence.artifacts.length === 0) failures.push("UI evidence requires screenshot artifacts");
   }
-  const artifacts = Array.isArray(evidence.artifacts) ? evidence.artifacts : [];
-  for (const artifactValue of artifacts) {
+  const artifacts2 = Array.isArray(evidence.artifacts) ? evidence.artifacts : [];
+  for (const artifactValue of artifacts2) {
     if (!isRecord3(artifactValue) || typeof artifactValue["path"] !== "string" || typeof artifactValue["sha256"] !== "string") {
       failures.push("artifact requires string path and sha256");
       continue;
@@ -651,7 +660,7 @@ var createMachineMonitor = (sampleIntervalMs = 5e3, options2 = {}) => {
   };
 };
 
-// src/verification.ts
+// src/execution/verification.ts
 var now2 = () => (/* @__PURE__ */ new Date()).toISOString();
 var requireRun = (run) => run ?? fail("No verification run exists.", "NO_RUN");
 var verificationProjection = (run) => ({ checks: run.checks, outcomes: run.outcomes, metrics: run.metrics });
@@ -796,10 +805,10 @@ var verifyRun = async ({ configPath }) => {
     const required8 = outcome.checks.filter((id2) => loaded.config.checks.find((check) => check.id === id2)?.required);
     return { ...outcome, status: required8.length === 0 ? "not-applicable" : required8.every((id2) => statuses.get(id2) === "passed") ? "passed" : "failed" };
   }), metrics: { totalDurationMs, wallDurationMs: Date.now() - verificationStarted, peakConcurrency: observedPeakConcurrency, budgetExceeded, machine: machineMonitor.stop() } };
-  const digest3 = verificationDigest(current);
-  current = { ...current, verificationDigest: digest3 };
+  const digest4 = verificationDigest(current);
+  current = { ...current, verificationDigest: digest4 };
   saveRun2(loaded.stateDir, current);
-  new FileEventStore(loaded.stateDir).append({ runId: current.runId, sourceRevision: current.sourceRevision, configHash: current.configHash, type: "verification.completed", payload: { verificationDigest: digest3, checkCount: current.checks.length, outcomeCount: current.outcomes.length, totalDurationMs, budgetExceeded } });
+  new FileEventStore(loaded.stateDir).append({ runId: current.runId, sourceRevision: current.sourceRevision, configHash: current.configHash, type: "verification.completed", payload: { verificationDigest: digest4, checkCount: current.checks.length, outcomeCount: current.outcomes.length, totalDurationMs, budgetExceeded } });
   const automatic = allPassed && current.autonomy === "yolo" && !loaded.config.tracking.required && loaded.config.contract.ambiguities.length === 0;
   const nextState = allPassed ? automatic ? "COMPLETE" : "AWAITING_HUMAN_APPROVAL" : "BLOCKED";
   current = { ...transition(current, nextState, automatic ? "All applicable checks passed; YOLO policy permits automatic completion." : allPassed ? "All configured checks passed; human approval is required." : budgetExceeded ? "Verification budget was exceeded." : "A configured check failed or lacked structured evidence.", "harness") };
@@ -917,15 +926,17 @@ var createDocBridgeContextProvider = ({ root, indexPath = ".doc-bridge/index.jso
   id: "doc-bridge",
   version: "1.0.0",
   resolve: async (query) => {
+    const started = Date.now();
     const document = index(root, indexPath);
     const contentHash = sourceHash(document);
     const entries = Array.isArray(document.knowledge) ? document.knowledge.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value)).filter((entry) => matches(entry, query)).sort((left, right) => String(left.id ?? "").localeCompare(String(right.id ?? ""))).slice(0, 8) : [];
-    const references = entries.flatMap((entry) => typeof entry.id === "string" && typeof entry.path === "string" ? [{ id: entry.id, uri: `doc-bridge://${entry.path}`, ...typeof entry.title === "string" ? { title: entry.title } : {}, contentHash }] : []);
-    return { providerId: "doc-bridge", query, references, sourceHash: contentHash, snapshotHash: hashContextSnapshot({ providerId: "doc-bridge", query, references, sourceHash: contentHash }), resolvedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    const references = entries.flatMap((entry) => typeof entry.id === "string" && typeof entry.path === "string" ? [{ id: entry.id, uri: `doc-bridge://${entry.path}`, ...typeof entry.title === "string" ? { title: entry.title } : {}, contentHash: typeof entry.contentHash === "string" ? entry.contentHash : contentHash, relevance: 1 }] : []);
+    const telemetry = { status: "measured", durationMs: Date.now() - started, contextReferences: references.length, contextCostTokens: Math.max(1, Math.ceil(JSON.stringify(references).length / 4)) };
+    return { providerId: "doc-bridge", query, references, sourceHash: contentHash, snapshotHash: hashContextSnapshot({ providerId: "doc-bridge", query, references, sourceHash: contentHash }), resolvedAt: (/* @__PURE__ */ new Date()).toISOString(), assurance: "contract-tested", telemetry };
   }
 });
 
-// src/discovery.ts
+// src/kernel/discovery.ts
 var required = (value, label) => {
   if (typeof value !== "string" || !value.trim()) fail(`${label} is required.`, "INVALID_INPUT");
   return value.trim();
@@ -987,7 +998,7 @@ var assessDiscovery = (input) => {
   return { ...base, digest: digest2(base) };
 };
 
-// src/wip.ts
+// src/kernel/wip.ts
 var WIP_STATES = ["ready", "implementing", "blocked", "awaiting-decision", "awaiting-acceptance", "done", "cancelled"];
 var terminal = /* @__PURE__ */ new Set(["done", "cancelled"]);
 var required2 = (value, label) => {
@@ -1019,7 +1030,7 @@ var assessWip = ({ entries, candidate, maxInFlight = 3 }) => {
   return { decision: "admit", inFlight, counts, reason: `WIP slot available (${inFlight.length}/${maxInFlight}).` };
 };
 
-// src/experiment.ts
+// src/kernel/experiment.ts
 var required3 = (value, label) => {
   if (typeof value !== "string" || !value.trim()) fail(`${label} is required.`, "INVALID_INPUT");
   return value.trim();
@@ -1046,7 +1057,7 @@ var selectRuntime = (candidates) => {
   return { decision: "selected", selected, eligible, reason: "Selected by human minutes, duration, cost, then Orca tie-break." };
 };
 
-// src/delivery.ts
+// src/delivery/index.ts
 var required4 = (value, label) => {
   if (typeof value !== "string" || !value.trim()) fail(`${label} is required.`, "INVALID_INPUT");
   return value.trim();
@@ -1141,7 +1152,7 @@ var assessAcceptance = ({ production, acceptanceRequired, accepted, notApplicabl
   return assessed("G5", "approved", acceptanceRequired ? [] : [`Acceptance is not applicable: ${notApplicableReason}.`], production.binding);
 };
 
-// src/pilot.ts
+// src/kernel/pilot.ts
 var required5 = (value, label) => {
   if (typeof value !== "string" || !value.trim()) fail(`${label} is required.`, "INVALID_INPUT");
   return value.trim();
@@ -1216,9 +1227,131 @@ var assessImprovementCycle = (input) => {
   const reasons = complete ? ["All five cycle steps passed."] : iterations.length >= input.maxIterations ? ["Maximum cycle iterations reached; human adjustment is required."] : latest.adjustment ? ["A failed or blocked step remains; repeat with the recorded adjustment."] : ["A failed or blocked step remains; an explicit adjustment is required before repeating."];
   const decision = complete ? "complete" : iterations.length >= input.maxIterations || !latest.adjustment ? "blocked" : "repeat";
   const result = { type: "agentskit-harness-improvement-cycle", cycleId, decision, ...decision === "repeat" ? { nextIteration: latest.iteration + 1 } : {}, reasons, matrix };
-  const digest3 = createHash("sha256").update(JSON.stringify(result)).digest("hex");
-  return { ...result, digest: digest3 };
+  const digest4 = createHash("sha256").update(JSON.stringify(result)).digest("hex");
+  return { ...result, digest: digest4 };
+};
+var ARTIFACT_SCHEMA_VERSION = 1;
+var ARTIFACT_TYPES = ["plan", "finding", "decision", "repair", "blocker", "approval", "phase"];
+var text2 = (value, label) => {
+  if (typeof value !== "string" || !value.trim()) return fail(`${label} is required.`, "INVALID_INPUT");
+  return value.trim();
+};
+var digest3 = (value, label) => {
+  const result = text2(value, label);
+  if (!/^[a-f0-9]{64}$/.test(result)) fail(`${label} must be a lowercase SHA-256 digest.`, "INVALID_INPUT");
+  return result;
+};
+var artifactId = (value) => {
+  const result = text2(value, "Artifact artifactId");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(result)) fail("Artifact artifactId is invalid.", "INVALID_INPUT");
+  return result;
+};
+var isRecord4 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var artifactBody = (artifact) => ({
+  type: artifact.type,
+  schemaVersion: artifact.schemaVersion,
+  artifactId: artifact.artifactId,
+  artifactType: artifact.artifactType,
+  artifactVersion: artifact.artifactVersion,
+  runId: artifact.runId,
+  issueRef: artifact.issueRef,
+  sourceRevision: artifact.sourceRevision,
+  contractHash: artifact.contractHash,
+  configHash: artifact.configHash,
+  contextHash: artifact.contextHash,
+  phase: artifact.phase,
+  payload: artifact.payload,
+  payloadHash: artifact.payloadHash
+});
+var expectedArtifactHash = (artifact) => hashJson(artifactBody(artifact));
+var validateArtifactEnvelope = (value) => {
+  if (!isRecord4(value)) return fail("Artifact envelope must be an object.", "INVALID_INPUT");
+  if (value["type"] !== "agentskit-harness-artifact" || value["schemaVersion"] !== ARTIFACT_SCHEMA_VERSION) fail("Artifact envelope type or schemaVersion is invalid.", "INVALID_INPUT");
+  if (!ARTIFACT_TYPES.includes(value["artifactType"])) fail("Artifact artifactType is invalid.", "INVALID_INPUT");
+  if (!Number.isInteger(value["artifactVersion"]) || value["artifactVersion"] < 1) fail("Artifact artifactVersion must be a positive integer.", "INVALID_INPUT");
+  const createdAt = text2(value["createdAt"], "Artifact createdAt");
+  if (!Number.isFinite(Date.parse(createdAt))) fail("Artifact createdAt must be a valid timestamp.", "INVALID_INPUT");
+  const payloadHash = digest3(value["payloadHash"], "Artifact payloadHash");
+  if (hashJson(value["payload"]) !== payloadHash) fail("Artifact payloadHash does not match payload.", "INVALID_INPUT");
+  const artifact = {
+    type: "agentskit-harness-artifact",
+    schemaVersion: ARTIFACT_SCHEMA_VERSION,
+    artifactId: artifactId(value["artifactId"]),
+    artifactType: value["artifactType"],
+    artifactVersion: value["artifactVersion"],
+    runId: text2(value["runId"], "Artifact runId"),
+    issueRef: text2(value["issueRef"], "Artifact issueRef"),
+    sourceRevision: text2(value["sourceRevision"], "Artifact sourceRevision"),
+    contractHash: digest3(value["contractHash"], "Artifact contractHash"),
+    configHash: digest3(value["configHash"], "Artifact configHash"),
+    contextHash: digest3(value["contextHash"], "Artifact contextHash"),
+    phase: text2(value["phase"], "Artifact phase"),
+    createdAt,
+    payload: value["payload"],
+    payloadHash
+  };
+  if (digest3(value["artifactHash"], "Artifact artifactHash") !== expectedArtifactHash(artifact)) fail("Artifact artifactHash does not match envelope.", "INVALID_INPUT");
+  return { ...artifact, artifactHash: value["artifactHash"] };
+};
+var renderArtifactMarkdown = (artifact) => [
+  `# ${artifact.artifactType} artifact ${artifact.artifactId}`,
+  "",
+  `- Schema: ${artifact.schemaVersion}`,
+  `- Version: ${artifact.artifactVersion}`,
+  `- Run: ${artifact.runId}`,
+  `- Issue: ${artifact.issueRef}`,
+  `- Phase: ${artifact.phase}`,
+  `- Source revision: ${artifact.sourceRevision}`,
+  `- Contract hash: ${artifact.contractHash}`,
+  `- Configuration hash: ${artifact.configHash}`,
+  `- Context hash: ${artifact.contextHash}`,
+  `- Artifact hash: ${artifact.artifactHash}`,
+  "",
+  "## Payload",
+  "",
+  "```json",
+  JSON.stringify(artifact.payload, null, 2),
+  "```",
+  ""
+].join("\n");
+var artifactFilePath = (stateDir, runId, id2) => join(stateDir, "runs", runId, "artifacts", `${id2}.json`);
+var artifactMarkdownPath = (stateDir, runId, id2) => join(stateDir, "runs", runId, "artifacts", `${id2}.md`);
+var FileArtifactStore = class {
+  constructor(stateDir) {
+    this.stateDir = stateDir;
+  }
+  stateDir;
+  write(input) {
+    const artifact = validateArtifactEnvelope(input);
+    const path = artifactFilePath(this.stateDir, artifact.runId, artifact.artifactId);
+    mkdirSync(join(this.stateDir, "runs", artifact.runId, "artifacts"), { recursive: true });
+    if (existsSync(path)) {
+      const existing = validateArtifactEnvelope(JSON.parse(readFileSync(path, "utf8")));
+      if (existing.artifactHash !== artifact.artifactHash) fail(`Artifact ${artifact.artifactId} already exists with different content.`, "HARNESS_ERROR");
+      return existing;
+    }
+    writeFileSync(path, `${JSON.stringify(artifact, null, 2)}
+`, "utf8");
+    writeFileSync(artifactMarkdownPath(this.stateDir, artifact.runId, artifact.artifactId), renderArtifactMarkdown(artifact), "utf8");
+    new FileEventStore(this.stateDir).append({
+      runId: artifact.runId,
+      sourceRevision: artifact.sourceRevision,
+      configHash: artifact.configHash,
+      type: "artifact.recorded",
+      payload: { artifactId: artifact.artifactId, artifactType: artifact.artifactType, artifactVersion: artifact.artifactVersion, artifactHash: artifact.artifactHash, phase: artifact.phase, representation: "json+markdown" }
+    });
+    return artifact;
+  }
+  read(runId, id2) {
+    return validateArtifactEnvelope(JSON.parse(readFileSync(artifactFilePath(this.stateDir, runId, artifactId(id2)), "utf8")));
+  }
+  list(runId) {
+    const directory = join(this.stateDir, "runs", runId, "artifacts");
+    if (!existsSync(directory)) return [];
+    return readdirSync(directory).filter((name) => name.endsWith(".json")).sort().map((name) => validateArtifactEnvelope(JSON.parse(readFileSync(join(directory, name), "utf8"))));
+  }
 };
+var readArtifactFile = (path) => validateArtifactEnvelope(JSON.parse(readFileSync(path, "utf8")));
 var BENCHMARK_SCHEMA_VERSION = 1;
 var percentage = (part, total) => total ? Number((part / total).toFixed(4)) : null;
 var improvementRate = (baseline, current) => baseline === void 0 || current === void 0 || baseline === 0 ? null : Number(((baseline - current) / baseline).toFixed(4));
@@ -1504,10 +1637,10 @@ var createDispatchLedger = (stateDir) => {
     },
     recordDispatch: ({ lease, idempotencyKey, commandDigest }) => {
       const id2 = required6(idempotencyKey, "idempotencyKey");
-      const digest3 = required6(commandDigest, "commandDigest");
+      const digest4 = required6(commandDigest, "commandDigest");
       const existing = records().find((record4) => record4.action === "dispatch" && record4.idempotencyKey === id2);
       if (existing) return { decision: "duplicate", record: existing };
-      const record3 = { ...lease, action: "dispatch", at: now3(), idempotencyKey: id2, commandDigest: digest3 };
+      const record3 = { ...lease, action: "dispatch", at: now3(), idempotencyKey: id2, commandDigest: digest4 };
       append(record3);
       return { decision: "recorded", record: record3 };
     },
@@ -1566,9 +1699,9 @@ var planFilePreflight = (files, options2 = {}) => {
   return { files: unique2, codeFiles, testFiles, docsOnly, checks: docsOnly ? [] : ["lint", "typecheck", ...testFiles.length ? ["test"] : []] };
 };
 
-// src/block.ts
+// src/kernel/block.ts
 var BLOCK_STATUSES = ["todo", "picked", "development", "validation", "pr-open", "merged", "post-merge", "done", "blocked", "scope-cut"];
-var text2 = (value, label) => {
+var text3 = (value, label) => {
   return typeof value === "string" && value.trim() ? value.trim() : fail(`${label} must be a non-empty string.`, "INVALID_INPUT");
 };
 var list = (value, label) => {
@@ -1595,16 +1728,16 @@ var validateBlockManifest = (value) => {
     for (const key of ["maxMinutes", "maxAttempts"]) if (candidate[key] !== void 0 && (!Number.isInteger(candidate[key]) || candidate[key] < 1)) fail(`budget.${key} must be a positive integer.`, "INVALID_INPUT");
     budget = { ...candidate["maxMinutes"] === void 0 ? {} : { maxMinutes: candidate["maxMinutes"] }, ...candidate["maxAttempts"] === void 0 ? {} : { maxAttempts: candidate["maxAttempts"] } };
   }
-  return { schemaVersion: 1, id: text2(raw["id"], "id"), title: text2(raw["title"], "title"), tracker: text2(raw["tracker"], "tracker"), repository: text2(raw["repository"], "repository"), acceptanceCriteria: criteria, dependencies, wave, status: status2, ...budget ? { budget } : {}, ...raw["humanGates"] === void 0 ? {} : { humanGates: list(raw["humanGates"], "humanGates") }, ...raw["sourceHash"] === void 0 ? {} : { sourceHash: text2(raw["sourceHash"], "sourceHash") } };
+  return { schemaVersion: 1, id: text3(raw["id"], "id"), title: text3(raw["title"], "title"), tracker: text3(raw["tracker"], "tracker"), repository: text3(raw["repository"], "repository"), acceptanceCriteria: criteria, dependencies, wave, status: status2, ...budget ? { budget } : {}, ...raw["humanGates"] === void 0 ? {} : { humanGates: list(raw["humanGates"], "humanGates") }, ...raw["sourceHash"] === void 0 ? {} : { sourceHash: text3(raw["sourceHash"], "sourceHash") } };
 };
 var assessBlock = (manifest, completedDependencies = []) => {
   const value = validateBlockManifest(manifest);
-  const completed = new Set(completedDependencies.map((item) => text2(item, "completedDependencies[]")));
+  const completed = new Set(completedDependencies.map((item) => text3(item, "completedDependencies[]")));
   const blockers = value.dependencies.filter((dependency) => !completed.has(dependency));
   const next = blockers.length ? [`Complete dependencies: ${blockers.join(", ")}`] : value.status === "blocked" ? ["Resolve the recorded blocker before dispatch."] : ["Dispatch the block with the frozen acceptance criteria."];
   return { status: blockers.length || value.status === "blocked" ? "blocked" : "ready", manifestHash: hashJson(value), blockers, next };
 };
-var text3 = (value, label) => {
+var text4 = (value, label) => {
   return typeof value === "string" && value.trim() ? value.trim() : fail(`${label} must be a non-empty string.`, "INVALID_INPUT");
 };
 var category = (heading) => {
@@ -1615,8 +1748,8 @@ var category = (heading) => {
   return "other";
 };
 var parseRetro = (markdown, source, recordedAt = (/* @__PURE__ */ new Date()).toISOString()) => {
-  const input = text3(markdown, "markdown");
-  const origin = text3(source, "source");
+  const input = text4(markdown, "markdown");
+  const origin = text4(source, "source");
   if (!Number.isFinite(Date.parse(recordedAt))) fail("recordedAt must be a valid timestamp.", "INVALID_INPUT");
   const records = [];
   let current = "other";
@@ -1635,7 +1768,7 @@ var parseRetro = (markdown, source, recordedAt = (/* @__PURE__ */ new Date()).to
   return records;
 };
 
-// src/status.ts
+// src/kernel/status.ts
 var required7 = (value, label) => {
   return typeof value === "string" && value.trim() ? value.trim() : fail(`${label} must be a non-empty string.`, "INVALID_INPUT");
 };
@@ -1687,7 +1820,7 @@ var exportEvidenceBundle = async ({ configPath, runId, outputPath, privateKeyPat
   const loaded = loadConfig(configPath);
   const run = requireRun2(runId ? readJson(join(loaded.stateDir, "runs", runId, "run.json")) : loadLatestRun(loaded.stateDir));
   const reconciliation = await reconcileRun({ configPath, runId: run.runId });
-  const digest3 = run.verificationDigest ?? fail("Only a reconciled COMPLETE run can be exported.", "INVALID_STATE");
+  const digest4 = run.verificationDigest ?? fail("Only a reconciled COMPLETE run can be exported.", "INVALID_STATE");
   if (reconciliation.state !== "COMPLETE") fail("Only a reconciled COMPLETE run can be exported.", "INVALID_STATE");
   const eventLog = new FileEventStore(loaded.stateDir);
   eventLog.read(run.runId);
@@ -1702,7 +1835,7 @@ var exportEvidenceBundle = async ({ configPath, runId, outputPath, privateKeyPat
     return bundleFile(loaded.stateDir, path);
   });
   const privateKey = createPrivateKey(readFileSync(privateKeyPath));
-  const unsigned = { type: "agentskit-harness-evidence-bundle", schemaVersion: EVIDENCE_BUNDLE_SCHEMA_VERSION, runId: run.runId, signerKeyId: keyId, sourceRevision: run.sourceRevision, configHash: run.configHash, contractHash: run.contractHash, verificationDigest: digest3, eventLog: eventVerification, files };
+  const unsigned = { type: "agentskit-harness-evidence-bundle", schemaVersion: EVIDENCE_BUNDLE_SCHEMA_VERSION, runId: run.runId, signerKeyId: keyId, sourceRevision: run.sourceRevision, configHash: run.configHash, contractHash: run.contractHash, verificationDigest: digest4, eventLog: eventVerification, files };
   const payloadHash = sha256(JSON.stringify(unsigned));
   const publicKeyPem = createPublicKey(privateKey).export({ type: "spki", format: "pem" }).toString();
   const bundle = { ...unsigned, payloadHash, signature: { algorithm: "ed25519", keyId, publicKeyPem, signatureBase64: sign(null, Buffer.from(payloadHash), privateKey).toString("base64") } };
@@ -1816,6 +1949,17 @@ coordination.command("claim <input>").action((input) => {
   const loaded = loadConfig(options().config);
   print(createDispatchLedger(loaded.stateDir).claim(readJsonInput(input, "coordination identity")));
 });
+var artifacts = program.command("artifacts").description("Inspect versioned, provenance-bound run artifacts.");
+artifacts.command("inspect <path>").description("Validate and print one artifact as JSON or Markdown.").action((path) => {
+  const artifact = readArtifactFile(path);
+  print(options().json ? artifact : renderArtifactMarkdown(artifact));
+});
+artifacts.command("list [run-id]").description("List artifacts for the latest or selected run.").action((runId) => {
+  const loaded = loadConfig(options().config);
+  const run = runId ? { runId } : loadLatestRun(loaded.stateDir);
+  print(new FileArtifactStore(loaded.stateDir).list(run?.runId ?? fail("No verification run exists.", "NO_RUN")));
+});
+artifacts.command("schema").description("Print the artifact schema version.").action(() => print({ schemaVersion: ARTIFACT_SCHEMA_VERSION, types: ["plan", "finding", "decision", "repair", "blocker", "approval", "phase"] }));
 program.command("start").description("Move a planned run into implementation.").action(() => print(startRun(loadConfig(options().config))));
 program.command("verify").description("Execute every configured check and record evidence.").action(async () => print(await verifyRun({ configPath: options().config })));
 program.command("run").description("Alias for verify, compatible with the common protocol.").action(async () => print(await verifyRun({ configPath: options().config })));