@agent-delivery-harness/cli 0.2.0 → 0.5.0

package/src/commands/prepare.ts

@@ -5,34 +5,135 @@
  * admission. Capturing an unprepared tree (dirty or with untracked files) is a
  * typed block, not a silent skip.
  */
-import { publishPreparationReceipt } from "@agent-delivery-harness/kernel";
-import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import {
+  classifyCandidateDrift,
+  computePreparationFingerprint,
+  computeDeliverableIdentity,
+  evaluatePreparationReceipt,
+  createBlocker,
+  createExecPort,
+  invalidatePreparationReceipt,
+  revokePreparationAttempt,
+  publishPreparationReceipt,
+  type RunPreparationObservation,
+} from "@agent-delivery-harness/kernel";
+import { CliInterruption, type CommandContext, type CommandDescriptor, type CommandResult } from "../boundary.ts";
+
+const USAGE = "Usage: delivery-harness prepare [--refresh-record-neutral]";
 
 export const prepareCommand: CommandDescriptor = {
   name: "prepare",
   sourceId: "delivery-harness.cli.prepare",
-  summary: "Capture the candidate and publish its preparation receipt.",
+  summary: "Run preparation checks; --refresh-record-neutral permits proven artifact-only receipt refresh.",
+  // The text prepare has always answered `--help` with, unchanged; the
+  // boundary is what prints it now, for every command rather than this one.
+  usage: `${USAGE}\nOrdinary prepare always runs mechanical checks. The refresh flag reuses prior success only when strict validation, policy, wiring and base are unchanged; otherwise it runs the checks.`,
   async run(context: CommandContext): Promise<CommandResult> {
+    if (context.args.length > 1 || (context.args.length === 1 && context.args[0] !== "--refresh-record-neutral")) {
+      return { kind: "usage", message: USAGE };
+    }
+    const refreshRecordNeutral = context.args[0] === "--refresh-record-neutral";
     const wiring = await context.wire();
-    const capture = await wiring.captureCandidate();
-    if (!capture.ok) {
-      return { kind: "blocked", blockers: [...capture.blockers] };
+    let retainedAttemptId: string | undefined;
+    let ownedAttemptId: string | undefined;
+    let refreshed = false;
+    try {
+      let capture: Awaited<ReturnType<typeof wiring.captureCandidate>>;
+      // A refresh continues the successful attempt it evaluated. It cannot
+      // transfer that success to new ownership after another attempt revokes it.
+      let reusableFingerprint: string | undefined;
+      let attemptId: string;
+      try {
+        capture = await wiring.captureCandidate();
+        if (capture.ok && refreshRecordNeutral) {
+          const previous = await evaluatePreparationReceipt(context.rootDir,
+            { config: context.config, candidate: capture.candidate }, { ...wiring.storageOptions, allowValidationEquivalent: true });
+          if (previous.prepared && previous.receipt.attemptId !== undefined) {
+            reusableFingerprint = previous.receipt.preparationFingerprint;
+            retainedAttemptId = previous.receipt.attemptId;
+          }
+        }
+      } finally {
+        attemptId = retainedAttemptId ?? await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
+        ownedAttemptId = attemptId;
+      }
+      if (!capture.ok) {
+        return { kind: "blocked", blockers: [...capture.blockers] };
+      }
+      const fingerprint = await computePreparationFingerprint(context.rootDir, context.config, wiring.storageOptions);
+      const reusable = reusableFingerprint === fingerprint;
+      const preparation: RunPreparationObservation = reusable
+        ? { checks: "reused", reason: "validation-equivalent" }
+        : { checks: "executed", reason: !refreshRecordNeutral ? "ordinary"
+          : retainedAttemptId === undefined ? "receipt-not-reusable" : "preparation-fingerprint-changed" };
+      if (!reusable && retainedAttemptId !== undefined) {
+        attemptId = await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
+        ownedAttemptId = attemptId;
+        retainedAttemptId = undefined;
+      }
+      const validationDigest = await computeDeliverableIdentity({ rootDir: context.rootDir, treeSha: capture.candidate.treeSha,
+        config: { ...context.config, computingIdentityVersion: "validation-tree/v1", reviewNeutral: context.config.recordNeutral } });
+      if (reusable) context.write("reusing preparation checks: strict validation projection, base, policy and wiring unchanged");
+      const exec = createExecPort();
+      const env = Object.fromEntries(Object.entries(context.env).filter((entry): entry is [string, string] => entry[1] !== undefined));
+      for (const check of reusable ? [] : context.config.preparationCommands ?? []) {
+        context.write(`preparing ${check.id}`);
+        const result = await exec.run({
+          command: check.command[0], args: check.command.slice(1), cwd: context.rootDir,
+          env, timeoutMs: check.timeoutMs, maxBuffer: 1024 * 1024,
+          ...(context.signal === undefined ? {} : { signal: context.signal }),
+        });
+        if (result.code !== 0 || context.signal?.aborted) {
+          return {
+            kind: "blocked",
+            blockers: [createBlocker({
+              code: "preparation_command_failed", source: { kind: "command", id: "delivery-harness.cli.prepare" },
+              summary: `Preparation check ${check.id} failed; no receipt was published.`,
+              details: `exit ${result.code}${result.errorCode === undefined ? "" : ` (${result.errorCode})`}\n${`${result.stdout}\n${result.stderr}`.slice(-4000)}`,
+              remediations: [{ id: "repair-preparation-check", kind: "manual_action", summary: `Fix ${check.id}, then run prepare again.` }],
+            })],
+          };
+        }
+      }
+      if (context.signal?.aborted) throw new CliInterruption();
+      const finalCapture = await wiring.captureCandidate();
+      if (!finalCapture.ok) return { kind: "blocked", blockers: [...finalCapture.blockers] };
+      const after = finalCapture.candidate;
+      if (classifyCandidateDrift(capture.candidate, after).length > 0 ||
+          capture.candidate.headSha !== after.headSha || capture.candidate.mode !== after.mode ||
+          fingerprint !== await computePreparationFingerprint(context.rootDir, context.config, wiring.storageOptions)) {
+        return {
+          kind: "blocked",
+          blockers: [createBlocker({
+            code: "preparation_candidate_changed", source: { kind: "command", id: "delivery-harness.cli.prepare" },
+            summary: "The candidate, base, or preparation wiring changed while checks ran; no receipt was published.",
+            remediations: [{ id: "prepare-stable-candidate", kind: "manual_action", summary: "Commit any intended changes and prepare the stable candidate again." }],
+          })],
+        };
+      }
+      const published = await publishPreparationReceipt(
+        context.rootDir,
+        { config: context.config, candidate: capture.candidate, attemptId, validationDigest },
+        wiring.storageOptions,
+      );
+      if (context.signal?.aborted) throw new CliInterruption();
+      refreshed = true;
+      // The labelled line exists so a reader — an operator or a review round
+      // about to bind itself to this candidate — has one unambiguous token to
+      // copy. It is the same value the record carries as `treeSha` and the same
+      // value `review-context` reports as `candidate tree`.
+      return {
+        kind: "ok",
+        preparation,
+        summary: [
+          `prepared ${context.config.gateId}: tree ${capture.candidate.treeSha} (${capture.candidate.mode}); receipt ${published.path}`,
+          `  treeSha ${capture.candidate.treeSha}`,
+        ].join("\n"),
+      };
+    } finally {
+      if (ownedAttemptId !== undefined && !refreshed) {
+        await revokePreparationAttempt(context.rootDir, context.config, ownedAttemptId, wiring.storageOptions);
+      }
     }
-    const published = await publishPreparationReceipt(
-      context.rootDir,
-      { config: context.config, candidate: capture.candidate },
-      wiring.storageOptions,
-    );
-    // The labelled line exists so a reader — an operator or a review round
-    // about to bind itself to this candidate — has one unambiguous token to
-    // copy. It is the same value the record carries as `treeSha` and the same
-    // value `review-context` reports as `candidate tree`.
-    return {
-      kind: "ok",
-      summary: [
-        `prepared ${context.config.gateId}: tree ${capture.candidate.treeSha} (${capture.candidate.mode}); receipt ${published.path}`,
-        `  treeSha ${capture.candidate.treeSha}`,
-      ].join("\n"),
-    };
   },
 };

package/src/commands/record.ts

@@ -13,21 +13,64 @@
  */
 import {
   buildDeliveryRecord,
+  candidateTreeEvidenceReader,
+  computePreparationFingerprint, capturePortableEvidenceContext, repositoryEvidenceReader, capturePortableVerificationInputs, verifyDeliveryRecord,
   deliveryRecordBytes,
   deliveryRecordPathFor,
   discoverRecords,
   type EvidenceRecord,
+  readCompiledRepositoryPolicy,
 } from "@agent-delivery-harness/kernel";
 import path from "node:path";
 import { commandBlocker } from "../boundary.ts";
 import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { oneLine } from "../run-surface.ts";
+import { applyDeliveryRecordRetention } from "../record-retention.ts";
 import { runProviderBackedAdmission } from "./gate.ts";
 
+interface RetentionOptions {
+  readonly scope: string;
+  readonly keepSuperseded: number;
+}
+
+function parseRetentionOptions(args: readonly string[]): RetentionOptions | undefined | string {
+  if (args.length === 0) return undefined;
+  let scope: string | undefined;
+  let keepSuperseded: number | undefined;
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (value === undefined) return `${flag ?? "record option"} requires a value`;
+    if (flag === "--retention-scope" && scope === undefined) scope = value;
+    else if (flag === "--keep-superseded" && keepSuperseded === undefined) {
+      if (!/^\d+$/.test(value)) return "--keep-superseded must be an integer from 0 through 100";
+      keepSuperseded = Number(value);
+    } else return `${oneLine(flag ?? "record option", 64)} is not a valid record retention option`;
+  }
+  if (scope === undefined || keepSuperseded === undefined) {
+    return "--retention-scope and --keep-superseded must be supplied together";
+  }
+  if (!Number.isSafeInteger(keepSuperseded) || keepSuperseded > 100) {
+    return "--keep-superseded must be an integer from 0 through 100";
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(scope)) {
+    return "--retention-scope must be a plain 1-128 character delivery key";
+  }
+  return { scope, keepSuperseded };
+}
+
 export const recordCommand: CommandDescriptor = {
   name: "record",
   sourceId: "delivery-harness.cli.record",
   summary: "Write the tracked delivery record for an admitted gate.",
+  usage: "Usage: delivery-harness record [--retention-scope <delivery-key> --keep-superseded <0-100>]\nRetention is opt-in; run gate first if a waiver is needed.",
   async run(context: CommandContext): Promise<CommandResult> {
+    const observedAt = `${new Date().toISOString().slice(0, 19)}Z`;
+    // Arguments before anything is wired, admitted, or written.
+    const retention = parseRetentionOptions(context.args);
+    if (typeof retention === "string") {
+      return { kind: "usage", message: `${retention}.\n${recordCommand.usage}` };
+    }
     const wiring = await context.wire();
 
     // The gate is run without a prompt: `record` is not the waiver surface. If a
@@ -79,15 +122,67 @@ export const recordCommand: CommandDescriptor = {
       evidenceRecords.push(...discovery.records);
     }
 
-    const built = buildDeliveryRecord({ config: context.config, decision, evidenceRecords });
+    const evidenceReader = repositoryEvidenceReader(context.rootDir, context.artifacts);
+    const evidenceContext = await capturePortableEvidenceContext(context.config, evidenceReader,
+      await computePreparationFingerprint(context.rootDir, context.config));
+    const compiledPolicy = context.policyBinding?.compiledPolicy ??
+      await readCompiledRepositoryPolicy(await candidateTreeEvidenceReader(context.rootDir, recheck.candidate.treeSha));
+    const built = buildDeliveryRecord({ config: context.config, decision, evidenceRecords, context: evidenceContext,
+      ...(compiledPolicy === null ? {} : { compiledPolicy, observedAt }) });
     if (!built.ok) {
       return { kind: "blocked", blockers: [...built.blockers] };
     }
 
+    const verificationInputs = await capturePortableVerificationInputs(context.rootDir, context.config, recheck.candidate, built.record);
+    const checked = verifyDeliveryRecord(context.config, built.record,
+      { deliverableDigest: recheck.candidate.deliverable.digest, identityToken: recheck.candidate.deliverable.identity }, recheck.candidate.base,
+      { ...verificationInputs, observedAt, liveResults: admission.observedLiveResults ?? [], executionContext: context.classifyContext() });
+    if (!checked.ok) return { kind: "blocked", blockers: [...checked.blockers] };
     const relativePath = deliveryRecordPathFor(context.config, decision.candidate.deliverable.digest);
     const absolutePath = path.join(context.rootDir, relativePath);
-    await context.artifacts.writeTextFile(absolutePath, deliveryRecordBytes(built.record));
+    const bytes = deliveryRecordBytes(built.record);
+    if (retention === undefined) {
+      await context.artifacts.writeTextFile(absolutePath, bytes);
+      return { kind: "ok", summary: `recorded ${relativePath}` };
+    }
+
+    const retained = await applyDeliveryRecordRetention({
+      rootDir: context.rootDir,
+      storageNamespace: context.config.storageNamespace,
+      scope: retention.scope,
+      keepSuperseded: retention.keepSuperseded,
+      recordBasePath: context.config.deliveryRecordPath,
+      current: {
+        relativePath,
+        deliverableDigest: decision.candidate.deliverable.digest,
+        bytes,
+      },
+      writeCurrent: () => context.artifacts.writeTextFile(absolutePath, bytes),
+    });
+    if (!retained.ok) {
+      return {
+        kind: "blocked",
+        blockers: [
+          commandBlocker({
+            code: retained.code,
+            sourceId: "delivery-harness.cli.record",
+            summary: "Tracked delivery-record retention did not complete.",
+            details: retained.detail,
+            remediations: [
+              {
+                id: "repair-record-retention",
+                kind: "manual_action",
+                summary: "Preserve the exact owned record bytes in Git, repair the named ownership conflict, then retry record with the same scope and bound.",
+              },
+            ],
+          }),
+        ],
+      };
+    }
 
-    return { kind: "ok", summary: `recorded ${relativePath}` };
+    return {
+      kind: "ok",
+      summary: `recorded ${relativePath}${retained.pruned.length === 0 ? "" : `; pruned Git-preserved ${retained.pruned.join(", ")}`}`,
+    };
   },
 };

package/src/commands/resume.ts

@@ -0,0 +1,53 @@
+import { classifyCandidateDrift, digestCanonical, evaluatePreparationReceipt, runAdmission, type CandidateBinding } from "@agent-delivery-harness/kernel";
+import { installedRelease, policyDigest, reconciliationActions, recoveryBlocker, recoveryRun } from "../ordinary-context.ts";
+import type { CommandDescriptor } from "../boundary.ts";
+
+const USAGE = "Usage: delivery-harness resume [--run <run-id>]";
+
+export const resumeCommand: CommandDescriptor = {
+  name: "resume", sourceId: "delivery-harness.cli.resume",
+  summary: "Read saved ordinary context and recheck evidence without executing or replaying work.",
+  usage: USAGE,
+  async run(context) {
+    if (context.args.length !== 0 && (context.args.length !== 2 || context.args[0] !== "--run")) return { kind: "usage", message: USAGE };
+    const run = await recoveryRun(context.rootDir, context.args[1]);
+    if (!run.ok) return { kind: "blocked", blockers: [run.blocker] };
+    const saved = [...run.events].reverse().find(event => event.kind === "context.saved");
+    if (!saved) return { kind: "blocked", blockers: [recoveryBlocker("resume_context_missing", "This run has no saved ordinary context. Recover the contract from its work item and save it explicitly.")] };
+    const p = saved.payload;
+    const actions = reconciliationActions(run.events);
+    const blockers = actions.some(action => action.outcome === "unknown" || action.inconsistent)
+      ? [recoveryBlocker("resume_action_unreconciled", "An external action has no consistent observed outcome. Reconcile its reference with host tools before any repeat.")] : [];
+    const wiring = await context.wire();
+    const capture = await wiring.captureCandidate();
+    const drift: string[] = [];
+    if (p["policyDigest"] !== policyDigest(context)) drift.push("policy_changed");
+    try { if (digestCanonical(p["release"]) !== digestCanonical(await installedRelease(context.rootDir))) drift.push("release_changed"); }
+    catch { drift.push("release_unreadable"); }
+    if (capture.ok) {
+      const binding = p["candidateBinding"] as Record<string, string>;
+      const expected: CandidateBinding = { treeSha: saved.candidateTreeSha!, deliverable: { digest: binding["deliverableDigest"]!, identity: binding["identity"]! },
+        base: { ref: binding["baseRef"]!, tipSha: binding["baseTipSha"]!, mergeBaseSha: binding["mergeBaseSha"]! }, workspaceId: binding["workspaceId"]! };
+      drift.push(...classifyCandidateDrift(expected, capture.candidate));
+      if (expected.deliverable.identity !== capture.candidate.deliverable.identity) drift.push("identity_changed");
+      if (expected.base.ref !== capture.candidate.base.ref) drift.push("base_ref_changed");
+    } else blockers.push(...capture.blockers);
+    // Reuse the ordinary sensors, with no prompt, live-result injection, or
+    // provider invocation. They read receipts/evidence; this journal grants nothing.
+    const preparation = capture.ok ? await evaluatePreparationReceipt(context.rootDir, { config: context.config, candidate: capture.candidate }, wiring.storageOptions) : undefined;
+    const admission = capture.ok ? await runAdmission({ rootDir: context.rootDir, config: context.config, context: context.classifyContext() },
+      { captureCandidate: wiring.captureCandidate, projectActivation: wiring.projectActivation, ...wiring.storageOptions }) : undefined;
+    if (capture.ok && admission?.candidate && classifyCandidateDrift(capture.candidate, admission.candidate).length > 0) drift.push("candidate_observation_changed");
+    try { if (digestCanonical(p["release"]) !== digestCanonical(await installedRelease(context.rootDir)) && !drift.includes("release_changed")) drift.push("release_changed"); }
+    catch { if (!drift.includes("release_unreadable")) drift.push("release_unreadable"); }
+    if (admission) blockers.push(...admission.blockers);
+    // Raw-tree movement alone is reported, but existing sensors decide whether
+    // the change is neutral. No new identity or freshness rule is introduced.
+    if (drift.some(item => item !== "raw_tree_changed")) blockers.push(recoveryBlocker("resume_context_stale", "Saved candidate, policy, or release bindings changed; revalidate the contract and affected work before saving fresh context."));
+    const reuseAllowed = blockers.length === 0 && admission?.admitted === true;
+    context.write(JSON.stringify({ spec: "ordinary-resume/1", runId: run.runId,
+      observationOnly: true, automaticReplay: false, savedContext: p, actions, drift,
+      preparation: preparation ?? { prepared: false }, admission: admission ?? { admitted: false }, reuseAllowed }));
+    return blockers.length > 0 ? { kind: "blocked", blockers } : { kind: "ok" };
+  },
+};

package/src/commands/review-context.ts

@@ -8,12 +8,19 @@
 import { evaluatePreparationReceipt } from "@agent-delivery-harness/kernel";
 import { commandBlocker } from "../boundary.ts";
 import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { buildReviewContext, OutcomeError } from "../review-evidence.ts";
+
+const USAGE = "Usage: delivery-harness review-context [--json]";
 
 export const reviewContextCommand: CommandDescriptor = {
   name: "review-context",
   sourceId: "delivery-harness.cli.review-context",
   summary: "Show the reviewable-change context for the prepared candidate.",
+  usage: USAGE,
   async run(context: CommandContext): Promise<CommandResult> {
+    if (context.args.length > 0 && !(context.args.length === 1 && context.args[0] === "--json")) {
+      return { kind: "usage", message: `review-context accepts only --json.\n${USAGE}` };
+    }
     const wiring = await context.wire();
     const capture = await wiring.captureCandidate();
     if (!capture.ok) {
@@ -49,6 +56,18 @@ export const reviewContextCommand: CommandDescriptor = {
       return { kind: "blocked", blockers };
     }
 
+    if (context.args[0] === "--json") {
+      try {
+        const document = await buildReviewContext(context.rootDir, context.config, capture.candidate, evaluation.receipt);
+        return { kind: "ok", summary: JSON.stringify(document, null, 2) };
+      } catch (error) {
+        if (!(error instanceof OutcomeError)) throw error;
+        return { kind: "blocked", blockers: [commandBlocker({
+          code: "review_context_unavailable", sourceId: "delivery-harness.cli.review-context", summary: error.message,
+          remediations: [{ id: "restore-review-inputs", kind: "manual_action", summary: "Restore the installed workflow release and compiled policy charters before acquiring review." }],
+        })] };
+      }
+    }
     const projection = await wiring.projectActivation(capture.candidate);
     const active = projection.relevantLineCount >= context.config.activationThreshold || projection.hasRelevantBinaryChange;
     return {