@agent-delivery-harness/cli 0.2.0 → 0.7.3

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, resolveRunSpan } 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,76 @@ 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));
+    // The delivery's own span, read off the run journal rather than off a
+    // clock: `startedAt` is the journal's first instant and `endedAt` the last
+    // it had reached by this write, which is the time this delivery had spent
+    // when it recorded. A delivery with no journal records exactly as it always
+    // did — the member is simply absent — because the record is evidence about
+    // a candidate and this is a cycle-time reading beside it, never a condition
+    // on writing one.
+    const runSpan = await resolveRunSpan({ cwd: context.rootDir, treeSha: recheck.candidate.treeSha, allowCurrentRun: true });
+    const built = buildDeliveryRecord({ config: context.config, decision, evidenceRecords, context: evidenceContext,
+      ...(runSpan === undefined ? {} : { runSpan: { startedAt: runSpan.startedAt, endedAt: runSpan.endedAt } }),
+      ...(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 {