@agent-delivery-harness/cli 0.2.0 → 0.5.0

package/src/commands/submit-evidence.ts

@@ -9,21 +9,60 @@
  */
 import { submitManifest } from "@agent-delivery-harness/kernel";
 import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { oneLine } from "../run-surface.ts";
 
-function manifestPathFrom(args: readonly string[]): string | undefined {
-  const flagIndex = args.indexOf("--manifest");
-  if (flagIndex !== -1) return args[flagIndex + 1];
-  // A lone positional is accepted too, but never a flag mistaken for a path.
-  const positional = args.find((argument) => !argument.startsWith("-"));
-  return positional;
+function manifestPathsFrom(args: readonly string[]): string[] | undefined {
+  const paths: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (token === "--manifest") {
+      const value = args[++index];
+      if (value === undefined || value === "") return undefined;
+      paths.push(value);
+    } else if (!token.startsWith("-")) paths.push(token);
+  }
+  return paths;
+}
+
+/**
+ * The one flag this command has, and everything else that looks like a flag.
+ * `--manifest`'s VALUE is skipped rather than scanned, so a path that happens
+ * to begin with a hyphen is still that flag's value and not an unknown flag —
+ * rejecting legitimate arguments generically is the failure mode this guard
+ * has to avoid while it closes the silently-ignored one.
+ */
+function unknownFlagIn(args: readonly string[]): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (token === "--manifest") {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) return token;
+  }
+  return undefined;
 }
 
 export const submitEvidenceCommand: CommandDescriptor = {
   name: "submit-evidence",
   sourceId: "delivery-harness.cli.submit-evidence",
   summary: "Validate a provider manifest and publish its evidence records.",
+  usage: "Usage: delivery-harness submit-evidence --manifest <path>",
   async run(context: CommandContext): Promise<CommandResult> {
-    const manifestPath = manifestPathFrom(context.args);
+    // An unrecognized flag is refused before the manifest is looked for, so a
+    // mistyped flag can never be ignored into a positional read of the argv.
+    const unknown = unknownFlagIn(context.args);
+    if (unknown !== undefined) {
+      return { kind: "usage", message: `Unknown flag ${oneLine(unknown, 64)}.\n${submitEvidenceCommand.usage}` };
+    }
+    const paths = manifestPathsFrom(context.args);
+    if (paths === undefined) {
+      return { kind: "usage", message: "submit-evidence requires --manifest <path>." };
+    }
+    if (paths.length > 1) {
+      return { kind: "usage", message: `submit-evidence requires one manifest path; received ${paths.map(value => oneLine(value, 256)).join(", ")}.` };
+    }
+    const manifestPath = paths[0];
     if (manifestPath === undefined || manifestPath === "") {
       return { kind: "usage", message: "submit-evidence requires --manifest <path>." };
     }

package/src/commands/verify.ts

@@ -37,6 +37,8 @@ import {
   parseDeliveryRecord,
   runGitCommand,
   verifyDeliveryRecord,
+  capturePortableVerificationInputs,
+  collectLiveProviderResults,
   type CandidateTreeEntry,
   type RunJournalRow,
 } from "@agent-delivery-harness/kernel";
@@ -115,7 +117,9 @@ export const verifyCommand: CommandDescriptor = {
   name: "verify",
   sourceId: "delivery-harness.cli.verify",
   summary: "Verify the tracked delivery record against the current candidate.",
+  usage: USAGE,
   async run(context: CommandContext): Promise<CommandResult> {
+    const observedAt = `${new Date().toISOString().slice(0, 19)}Z`;
     // Arguments first: a malformed invocation is a usage error and captures
     // nothing, exactly as `emit` and `submit-evidence` order it.
     const parsedArgs = parseArgs(context.args);
@@ -196,19 +200,29 @@ export const verifyCommand: CommandDescriptor = {
       }
     }
 
-    // The row is resolved from the RECORD'S tree sha, not the recomputed
-    // identity: the identity digest excludes the review-neutral paths, and what
-    // a review round and a `pr.opened` bind is the raw tree the record carries.
+    const inputs = await capturePortableVerificationInputs(context.rootDir, context.config, capture.candidate, parsed.record);
+    const live = await collectLiveProviderResults({rootDir:context.rootDir,config:context.config,candidate:capture.candidate,
+      projection:inputs.projection,evidenceContext:inputs.evidenceContext,env:context.env,...(context.signal===undefined?{}:{signal:context.signal})});
+    // Verify the portable record before letting any retained projection widen
+    // the observational tree coordinates. Corrupt or invented projection bytes
+    // therefore fail as record evidence and never influence journal matching.
+    const verified = verifyDeliveryRecord(context.config, parsed.record, identity, base,
+      { candidateTreePaths, ...inputs, observedAt, liveResults:live.liveResults, executionContext: context.classifyContext() });
+    if (!verified.ok) {
+      return { kind: "blocked", blockers: [...live.blockers, ...verified.blockers] };
+    }
+
+    // The record tree remains the primary coordinate. A product-validated
+    // review-neutral projection may additionally name the earlier raw tree the
+    // reviewers actually read; the journal stays observational either way.
     const runJournal = await resolveRunJournalRow({
       cwd: context.rootDir,
       treeSha: parsed.record.candidateBinding.treeSha,
+      reviewedCandidateTreeShas: verified.reviewedCandidateTreeShas,
       ...(parsedArgs.args.mandatedLensIds.length === 0 ? {} : { mandatedLensIds: parsedArgs.args.mandatedLensIds }),
     });
-
-    const check = verifyDeliveryRecord(context.config, parsed.record, identity, base, { candidateTreePaths, runJournal });
-    if (!check.ok) {
-      return { kind: "blocked", blockers: [...check.blockers] };
-    }
+    const check = verifyDeliveryRecord(context.config, parsed.record, identity, base,
+      { candidateTreePaths, runJournal, ...inputs, observedAt, liveResults:live.liveResults, executionContext: context.classifyContext() });
 
     // The opt-in is judged AFTER the record's own verification, so a delivery
     // whose record is bad is never told its journal is the problem.
@@ -219,10 +233,17 @@ export const verifyCommand: CommandDescriptor = {
     const relaxation = check.baseMovementRelaxed
       ? ` (base movement relaxed by policy: ${check.relaxedDriftClasses.join(", ")})`
       : "";
+    const exemption = check.hostedChecks.exemption;
+    const hostedCheckRow = exemption === undefined ? [] : [
+      `hosted checks: exempted for ${oneLine(exemption.scope.repositoryId, 128)} at ${oneLine(exemption.scope.baseRef, 256)}; granted by ${oneLine(exemption.grantedBy, 256)}; until ${exemption.until}; reason: ${oneLine(exemption.reason, 512)}`,
+    ];
     return {
       kind: "ok",
       summary: [
         `verified ${relativePath}${relaxation}; attestation: ${check.attestationLabel}`,
+        `recorded base: ${oneLine(parsed.record.candidateBinding.baseRef, 256)} at ${parsed.record.candidateBinding.baseTipSha}`,
+        `observed base: ${oneLine(base.ref, 256)} at ${base.tipSha}`,
+        ...hostedCheckRow,
         ...runJournalRows(runJournal),
       ].join("\n"),
     };

package/src/declared-checks.ts

@@ -0,0 +1,50 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { captureCheckBindings, captureCheckOutputSnapshots, digestCanonical, classifyCandidateDrift, computeCheckWiringFingerprint, createBlocker, createExecPort, sha256Hex, submitManifest, type Blocker, type CandidateBinding, type ProviderRegistration } from "@agent-delivery-harness/kernel";
+import type { CommandContext } from "./boundary.ts";
+
+/** Runs one declared argv check and submits its product-constructed terminal evidence. */
+export async function runDeclaredCheck(context: CommandContext, provider: ProviderRegistration, obligationIds: readonly string[], before: CandidateBinding): Promise<readonly Blocker[]> {
+  const check = provider.check!;
+  const wiring = await context.wire();
+  const fail = (code: string, summary: string, details?: string): readonly Blocker[] => [createBlocker({ code, source: { kind: "command", id: "delivery-harness.cli.gate" }, summary,
+    ...(details === undefined ? {} : { details }), remediations: [{ id: "repair-declared-check", kind: "manual_action", summary: "Fix the declared check or its inputs, prepare the stable candidate and run gate again." }] })];
+  const start = await wiring.captureCandidate();
+  if (!start.ok) return start.blockers;
+  if (classifyCandidateDrift(before, start.candidate).length) return fail("check_candidate_changed", "The candidate changed after review admission and before the check started.");
+  const fingerprint = await computeCheckWiringFingerprint(context.rootDir, context.config, wiring.storageOptions);
+  context.write(`checking ${provider.id}`);
+  const result = await createExecPort().run({ command: check.command[0], args: check.command.slice(1), cwd: context.rootDir,
+    env: Object.fromEntries(Object.entries(context.env).filter((entry): entry is [string, string] => entry[1] !== undefined)),
+    timeoutMs: check.timeoutMs, maxBuffer: 1024 * 1024, ...(context.signal === undefined ? {} : { signal: context.signal }) });
+  if (result.code !== 0 || context.signal?.aborted) return fail("check_command_failed", `Declared check ${provider.id} did not complete successfully.`, `exit ${result.code}${result.errorCode === undefined ? "" : ` (${result.errorCode})`}\n${`${result.stdout}\n${result.stderr}`.slice(-4000)}`);
+  const captured = await wiring.captureCandidate();
+  if (!captured.ok) return captured.blockers;
+  if (classifyCandidateDrift(before, captured.candidate).length || start.candidate.headSha !== captured.candidate.headSha || fingerprint !== await computeCheckWiringFingerprint(context.rootDir, context.config, wiring.storageOptions)) return fail("check_candidate_changed", "The candidate, base or wiring changed while the check ran.");
+  const binding = (await captureCheckBindings(context.rootDir, context.config, captured.candidate, wiring.storageOptions))[provider.id];
+  if (binding === undefined) return fail("check_output_missing", `Declared check ${provider.id} has a missing, unreadable, oversized or escaped output.`);
+  const runId = randomUUID(), finalPassId = "pass-1";
+  const allocation = await context.artifacts.allocateRunRoot({ providerId: provider.id, runId });
+  if (!allocation.ok) return fail("check_artifact_unavailable", "Cannot allocate the declared check evidence root.");
+  const snapshots = await captureCheckOutputSnapshots(context.rootDir, check.outputs ?? []);
+  if (snapshots === undefined || digestCanonical(snapshots.map(({ path, sha256 }) => ({ path, sha256 }))) !== binding.outputsDigest) return fail("check_output_missing", "Declared outputs changed before evidence retention.");
+  const outputArtifacts: { path: string; sha256: string; role: string }[] = [];
+  for (const [index, output] of snapshots.entries()) {
+    const contents = JSON.stringify({ path: output.path, base64: output.base64 });
+    const artifactPath = `check-output-${index}.json`;
+    await context.artifacts.writeTextFile(path.join(allocation.runRoot.path, artifactPath), contents);
+    outputArtifacts.push({ path: artifactPath, sha256: sha256Hex(contents), role: "check-output" });
+  }
+  const payload = { verdict: "green", exitCode: 0, binding };
+  const terminal = JSON.stringify({ providerId: provider.id, runId, finalPassId, ...payload });
+  await context.artifacts.writeTextFile(path.join(allocation.runRoot.path, "check-result.json"), terminal);
+  const candidate = captured.candidate;
+  const manifest = { spec: "delivery-evidence/1", provider: { id: provider.id, runId, finalPassId },
+    candidate: { vcs: "git", treeSha: candidate.treeSha, headSha: candidate.headSha, deliverable: candidate.deliverable, base: candidate.base, workspaceId: candidate.workspaceId },
+    runHistory: [{ preparedTreeSha: candidate.treeSha, evaluatedInPassId: finalPassId }], artifacts: [{ path: "check-result.json", sha256: sha256Hex(terminal), role: "check-result" }, ...outputArtifacts],
+    attestation: { level: "self", signatures: [] }, recordedAt: new Date().toISOString(), claims: obligationIds.map(obligation => ({ obligation, payloadSpec: "checks.passed/1", payload })) };
+  const manifestPath = path.join(allocation.runRoot.path, "manifest.json");
+  await context.artifacts.writeTextFile(manifestPath, JSON.stringify(manifest));
+  const outcome = await submitManifest({ rootDir: context.rootDir, config: context.config, manifestPath }, { captureCandidate: wiring.captureCandidate, artifacts: context.artifacts, ...wiring.storageOptions });
+  return outcome.status === "accepted" ? [] : outcome.blockers;
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * Delivery harness CLI: the eleven-command operator surface.
+ * Delivery harness CLI: the fifteen-command operator surface.
  *
  * THE COMMAND REGISTRY. `COMMANDS` is the single source of truth for which
  * commands exist. Every command module under `commands/` must appear here, and
@@ -12,6 +12,7 @@
  * in `boundary.ts`; each command is a thin, testable unit behind it.
  */
 import { checkCommand } from "./commands/check.ts";
+import { admitCommand } from "./commands/admit.ts";
 import { emitCommand } from "./commands/emit.ts";
 import { gateCommand } from "./commands/gate.ts";
 import { maintainCommand } from "./commands/maintain.ts";
@@ -19,12 +20,16 @@ import { managedCommand } from "./commands/managed.ts";
 import { prepareCommand } from "./commands/prepare.ts";
 import { recordCommand } from "./commands/record.ts";
 import { reviewContextCommand } from "./commands/review-context.ts";
+import { emitReviewEvidenceCommand } from "./commands/emit-review-evidence.ts";
 import { runsCommand } from "./commands/runs.ts";
 import { submitEvidenceCommand } from "./commands/submit-evidence.ts";
 import { verifyCommand } from "./commands/verify.ts";
+import { saveContextCommand } from "./commands/save-context.ts";
+import { resumeCommand } from "./commands/resume.ts";
 import { runCliBoundary, type AnyCommandDescriptor, type CliRuntime } from "./boundary.ts";
 
 export const PACKAGE_NAME = "@agent-delivery-harness/cli";
+export { buildRunExport, parseRunExport, type DeliveryRunExport, type RunExportParseResult } from "./run-export.ts";
 
 /**
  * The command registry. The order here is the order `--help` lists them, and it
@@ -38,8 +43,10 @@ export const PACKAGE_NAME = "@agent-delivery-harness/cli";
  * write the run store rather than anything a delivery decision depends on.
  */
 export const COMMANDS: readonly AnyCommandDescriptor[] = [
+  admitCommand,
   prepareCommand,
   reviewContextCommand,
+  emitReviewEvidenceCommand,
   submitEvidenceCommand,
   gateCommand,
   recordCommand,
@@ -49,6 +56,8 @@ export const COMMANDS: readonly AnyCommandDescriptor[] = [
   maintainCommand,
   emitCommand,
   runsCommand,
+  saveContextCommand,
+  resumeCommand,
 ];
 
 export {
@@ -74,7 +83,9 @@ export {
 } from "./boundary.ts";
 
 export { prepareCommand } from "./commands/prepare.ts";
+export { admitCommand } from "./commands/admit.ts";
 export { reviewContextCommand } from "./commands/review-context.ts";
+export { emitReviewEvidenceCommand } from "./commands/emit-review-evidence.ts";
 export { submitEvidenceCommand } from "./commands/submit-evidence.ts";
 export { gateCommand } from "./commands/gate.ts";
 export { recordCommand } from "./commands/record.ts";
@@ -84,6 +95,8 @@ export { managedCommand } from "./commands/managed.ts";
 export { maintainCommand } from "./commands/maintain.ts";
 export { emitCommand } from "./commands/emit.ts";
 export { runsCommand } from "./commands/runs.ts";
+export { saveContextCommand } from "./commands/save-context.ts";
+export { resumeCommand } from "./commands/resume.ts";
 
 /** Runs the CLI against a runtime and returns the process exit code. */
 export function runCli(argv: readonly string[], runtime: CliRuntime): Promise<number> {

package/src/main.ts

@@ -8,11 +8,9 @@
  * prints every obligation one "yes" would cover, reads a single line, and turns
  * a Ctrl-C into the typed {@link CliInterruption} the boundary maps to exit 130.
  */
-import { realpathSync } from "node:fs";
 import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
 import { CliInterruption, EXIT_POLICY, runCli, type CliRuntime } from "./index.ts";
-import type { WaiverPrompt } from "@agent-delivery-harness/kernel";
+import { invokedDirectly, type WaiverPrompt } from "@agent-delivery-harness/kernel";
 
 /**
  * Reads a yes/no answer after naming every obligation the waiver would cover.
@@ -38,8 +36,8 @@ import type { WaiverPrompt } from "@agent-delivery-harness/kernel";
  * second settlement is exactly how this class of bug hides.
  */
 export function createWaiverPrompt(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): WaiverPrompt {
-  return (_decision, obligationIds) =>
-    new Promise<boolean>((resolve, reject) => {
+  return (decision, obligationIds) =>
+    new Promise<Awaited<ReturnType<WaiverPrompt>>>((resolve, reject) => {
       const rl = createInterface({ input, output });
       let settled = false;
       const settle = (action: () => void): void => {
@@ -60,10 +58,24 @@ export function createWaiverPrompt(input: NodeJS.ReadableStream, output: NodeJS.
       });
 
       output.write(`Waiving covers ${obligationIds.length} obligation(s): ${obligationIds.join(", ")}.\n`);
+      output.write(`Candidate: ${decision.candidate.treeSha}. Approval covers only these findings under the current policy; live obligations require new approval each invocation.\n`);
+      for (const resolution of decision.resolutions) {
+        if (resolution.kind === "blocked" && obligationIds.includes(resolution.obligationId)) {
+          for (const blocker of resolution.blockers) output.write(`${resolution.obligationId}: [${blocker.code}] ${blocker.summary}\n`);
+        }
+      }
+      const finish = (value: Awaited<ReturnType<WaiverPrompt>>) => settle(() => {
+        rl.close();
+        resolve(value);
+      });
       rl.question("Waive all of them? [y/N] ", (answer) => {
-        settle(() => {
-          rl.close();
-          resolve(/^\s*y(es)?\s*$/i.test(answer));
+        if (!/^\s*y(es)?\s*$/i.test(answer)) return finish(false);
+        rl.question("Author: ", (author) => {
+          if (!author.trim() || author.length > 256) return finish(false);
+          rl.question("Reason: ", (reason) => {
+            if (!reason.trim() || reason.length > 4096) return finish(false);
+            finish({ author: author.trim(), reason: reason.trim() });
+          });
         });
       });
     });
@@ -72,45 +84,6 @@ export function createWaiverPrompt(input: NodeJS.ReadableStream, output: NodeJS.
 export const readlineWaiverPrompt: WaiverPrompt = (decision, obligationIds) =>
   createWaiverPrompt(process.stdin, process.stderr)(decision, obligationIds);
 
-/** The spelling the filesystem can vouch for: the realpath where it can answer, the spelling itself where it cannot. */
-function canonicalEntryPath(entryPath: string): string {
-  try {
-    return realpathSync(entryPath);
-  } catch {
-    return entryPath;
-  }
-}
-
-/**
- * Whether this module is the entry the process was started with.
- *
- * argv and `import.meta.url` may spell the same file differently: argv is the
- * caller's spelling, and Node builds the module URL from the realpath by
- * default but from the caller's spelling under `--preserve-symlinks-main`. So
- * each side is canonicalized independently and the canonical forms compared:
- * a symlinked spelling matches its realpath whenever the link can be read
- * (`/tmp` → `/private/tmp` on macOS, a wrapper script's stored path, a pnpm
- * workspace link), and equal spellings still match when neither side resolves.
- *
- * What is NOT claimed: a symlink the filesystem cannot resolve cannot be seen
- * through, and the failing-exit-code floor below sits inside this guard, so an
- * under-match exits 0 in silence — the CLI reporting success having verified
- * nothing. The floor cannot be hoisted above the guard: that would stamp a
- * failing exit code on every process that merely *imports* this module. And a
- * non-`file:` module href (a bundled or single-executable build) never
- * matches — such a build must invoke `main` explicitly.
- */
-export function invokedDirectly(argvEntry: string | undefined, moduleHref: string): boolean {
-  if (argvEntry === undefined) return false;
-  let modulePath: string;
-  try {
-    modulePath = fileURLToPath(moduleHref);
-  } catch {
-    return false;
-  }
-  return canonicalEntryPath(argvEntry) === canonicalEntryPath(modulePath);
-}
-
 /**
  * Reads the whole of stdin as UTF-8.
  *

package/src/ordinary-context.ts

@@ -0,0 +1,99 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { HARNESS_VERSION, digestCanonical, type Blocker, type RunEvent, type RunEventVersion } from "@agent-delivery-harness/kernel";
+import { commandBlocker, type CommandContext } from "./boundary.ts";
+import { oneLine, resolveRunSurface, type RunSurface } from "./run-surface.ts";
+
+export function recoveryBlocker(code: string, summary: string, details?: string): Blocker {
+  return commandBlocker({ code, sourceId: "delivery-harness.cli.resume", summary,
+    ...(details === undefined ? {} : { details }),
+    remediations: [{ id: "reconcile-delivery-context", kind: "manual_action", summary: "Inspect the saved context and actual workspace/external state with host tools; rerun preparation and gates where evidence is not current. Never replay an uncertain action automatically." }],
+  });
+}
+
+/**
+ * What a store rejection may say to an operator: the store's own code, the
+ * JSON pointer at the offending member, and the store's own message. All three
+ * are written by the store rather than taken from the refused payload, so the
+ * diagnostic names the field without ever echoing its value — a contract a
+ * caller must keep, because the payload it refused is the one place a
+ * credential could have been.
+ */
+export function rejectionDetails(rejections: readonly { readonly code: string; readonly pointer: string; readonly message: string }[]): string {
+  const first = rejections[0];
+  if (first === undefined) return "the store refused the append";
+  return `${oneLine(first.code, 64)} at ${oneLine(first.pointer, 128) || "/"}: ${oneLine(first.message, 200)}`;
+}
+
+/**
+ * The writer members an ordinary-context event carries, for the version the
+ * selected run was started at.
+ *
+ * WHY THE ID IS DERIVED FROM THE OBSERVATION. A v2 event id is a retry key:
+ * the store admits a repeat of an id only when the whole event matches, and
+ * refuses the id outright for different content. An id derived from the
+ * payload's canonical digest is therefore exactly the key the contract wants —
+ * the same save repeated is the same event and appends nothing new, while a
+ * changed observation is a different id and a new entry, so neither an
+ * interrupted retry nor a genuine second save can produce a refusal an
+ * operator has to reason about. It is also stable across processes and hosts,
+ * which a random id is not.
+ */
+export function ordinaryEventWriter(version: RunEventVersion, kind: "context.saved", payload: unknown): {
+  readonly version: RunEventVersion;
+  readonly eventId?: string;
+} {
+  if (version !== "run-event/2") return { version };
+  // `kind` is narrowed to the one kind this writer serves, so the prefix is a
+  // constant that keeps the id readable and inside the store's 128-character
+  // run-id charset. It is deliberately not a general scoping claim: dots are
+  // folded to hyphens, which is not injective over arbitrary kinds, so a
+  // second kind must not be added here without an injective encoding.
+  return { version, eventId: `${kind.replaceAll(".", "-")}-${digestCanonical(payload)}` };
+}
+
+export async function recoveryRun(rootDir: string, named?: string): Promise<
+  { ok: true; surface: RunSurface; runId: string; events: readonly RunEvent[]; version: RunEventVersion } | { ok: false; blocker: Blocker }
+> {
+  const resolved = await resolveRunSurface(rootDir);
+  if (!resolved.ok) return { ok: false, blocker: recoveryBlocker("resume_context_invalid", "The repository run store cannot be read.") };
+  const current = await resolved.surface.store.current(resolved.surface.worktreeKey);
+  const runId = named ?? (current.ok ? current.runId : undefined);
+  if (!runId) return { ok: false, blocker: recoveryBlocker("resume_context_missing", "No current delivery run was found; start a run or name its existing id with --run.") };
+  const read = await resolved.surface.store.read(runId);
+  if (!read.ok) return { ok: false, blocker: recoveryBlocker("resume_context_invalid", "The delivery journal is missing, corrupt, or inaccessible.", rejectionDetails(read.rejections)) };
+  // The writer version is selected when the run starts and never upgraded, so
+  // every writer into this journal reads it from the journal's first event.
+  return { ok: true, surface: resolved.surface, runId, events: read.events, version: read.events[0]?.version ?? "run-event/1" };
+}
+
+export async function installedRelease(rootDir: string) {
+  const document: unknown = JSON.parse(await readFile(path.join(rootDir, ".agent-skills/active.json"), "utf8"));
+  const release = (document as { release?: { releaseId?: unknown; profile?: unknown; archiveSha256?: unknown } } | null)?.release;
+  if (!release || typeof release.releaseId !== "string" || typeof release.profile !== "string" ||
+      typeof release.archiveSha256 !== "string" || !/^[0-9a-f]{64}$/.test(release.archiveSha256)) {
+    throw new Error("Installed workflow release identity is missing or malformed.");
+  }
+  return { runtimeVersion: HARNESS_VERSION, releaseId: release.releaseId, profile: release.profile, archiveSha256: release.archiveSha256 };
+}
+
+export const policyDigest = (context: CommandContext) => digestCanonical({ config: context.config, policyBinding: context.policyBinding ?? null });
+
+/** Observed action outcomes are a host handoff, never permission to invoke an action. */
+export function reconciliationActions(events: readonly RunEvent[]) {
+  const actions = new Map<string, { actionId: string; operation?: unknown; reference: unknown; outcome: string; inconsistent?: boolean }>();
+  for (const event of events) {
+    const p = event.payload;
+    if (event.kind === "action.intent") {
+      const actionId = p["actionId"] as string;
+      const prior = actions.get(actionId);
+      actions.set(actionId, { actionId, operation: p["operation"], reference: p["reference"], outcome: "unknown", ...(prior ? { inconsistent: true } : {}) });
+    } else if (event.kind === "action.observed") {
+      const actionId = p["actionId"] as string;
+      const prior = actions.get(actionId);
+      actions.set(actionId, { ...prior, actionId, reference: p["reference"], outcome: p["outcome"] as string,
+        ...(!prior || prior.inconsistent || (prior.outcome !== "unknown" && prior.outcome !== p["outcome"]) ? { inconsistent: true } : {}) });
+    }
+  }
+  return [...actions.values()];
+}