@agent-delivery-harness/cli 0.1.0 → 0.5.0

package/src/commands/save-context.ts

@@ -0,0 +1,51 @@
+import { buildRunEvent } from "../run-surface.ts";
+import { installedRelease, ordinaryEventWriter, policyDigest, recoveryBlocker, recoveryRun, rejectionDetails } from "../ordinary-context.ts";
+import type { CommandDescriptor } from "../boundary.ts";
+
+const USAGE = "Usage: delivery-harness save-context --json '{\"contract\":{\"objective\":\"...\",\"acceptanceCriteria\":[\"...\"],\"finishLine\":\"merge-ready\"},\"stage\":\"work\"}'";
+
+export const saveContextCommand: CommandDescriptor = {
+  name: "save-context", sourceId: "delivery-harness.cli.save-context",
+  summary: "Save a bounded delivery contract and stage observation in the current run.",
+  usage: USAGE,
+  async run(context) {
+    if (context.args.length !== 2 || context.args[0] !== "--json") return { kind: "usage", message: USAGE };
+    let input: { contract?: unknown; stage?: unknown };
+    try {
+      const value: unknown = JSON.parse(context.args[1]!);
+      if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => key !== "contract" && key !== "stage")) throw new Error();
+      input = value;
+    } catch { return { kind: "usage", message: "Context must be a JSON object with only contract and stage." }; }
+    const run = await recoveryRun(context.rootDir);
+    if (!run.ok) return { kind: "blocked", blockers: [run.blocker] };
+    const wiring = await context.wire();
+    const capture = await wiring.captureCandidate();
+    if (!capture.ok) return { kind: "blocked", blockers: capture.blockers };
+    let release;
+    try { release = await installedRelease(context.rootDir); }
+    catch { return { kind: "blocked", blockers: [recoveryBlocker("resume_release_unreadable", "The installed workflow release identity cannot be read; restore a valid installation before saving context.")] }; }
+    const candidate = capture.candidate;
+    // An omitted member is absent, never present-and-undefined: the contract
+    // reports it as a missing member, and the v2 retry key stays derivable.
+    const payload = { spec: "ordinary-run-context/1",
+      ...(input.contract === undefined ? {} : { contract: input.contract }),
+      ...(input.stage === undefined ? {} : { stage: input.stage }),
+      candidateTreeSha: candidate.treeSha,
+      candidateBinding: { deliverableDigest: candidate.deliverable.digest, identity: candidate.deliverable.identity,
+        baseRef: candidate.base.ref, baseTipSha: candidate.base.tipSha, mergeBaseSha: candidate.base.mergeBaseSha, workspaceId: candidate.workspaceId },
+      policyDigest: policyDigest(context), release };
+    // The run's own writer version, never this command's: a v2 journal admits
+    // no v1 event, and a v2 event needs the retry key the writer derives.
+    const writer = ordinaryEventWriter(run.version, "context.saved", payload);
+    const appended = await run.surface.store.append(
+      run.runId,
+      buildRunEvent({ runId: run.runId, commonDir: run.surface.commonDir, kind: "context.saved", role: "executor", payload, ...writer }),
+      // An exact retry of one save is one observation, at its first instant.
+      { reuseExistingTimestamp: true },
+    );
+    if (!appended.ok) return { kind: "blocked", blockers: [recoveryBlocker("resume_context_invalid",
+      "Context was refused by the bounded run-event contract; inspect contract, stage, and secret-free inputs.",
+      `run ${run.runId}: ${rejectionDetails(appended.rejections)}`)] };
+    return { kind: "ok", summary: `saved ordinary context for ${run.runId}; stage is an observation, not evidence` };
+  },
+};

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

@@ -7,18 +7,124 @@
  * the pure `verifyDeliveryRecord` core. A missing record names the command that
  * writes it; a failed check surfaces the named drift class. When the base-movement
  * policy is `allow`, a passing check that relaxed base drift names the relaxation.
+ *
+ * THE RUN-JOURNAL ROW, AND WHY IT IS LOCAL ONLY. `verify` is the one caller
+ * that holds both halves of the question "was this candidate journaled": a
+ * record binding an exact tree sha, and a repository whose run store it can
+ * scan for a journal bound to the same one. So it resolves the row and reports
+ * it — and reporting is all it does by default. The row changes no exit code
+ * unless the operator asks for that with `--require-run-journal`, a LOCAL
+ * opt-in: it is not passed by the GitHub Action, not read by the gate, and not
+ * consulted by admission. A run journal is self-attested observability that
+ * anything the owner executes can append to, so a delivery that could be
+ * admitted or refused on one would be resting its gate on a file its own
+ * candidate scripts can write.
+ *
+ * `--mandated-lens <id>` is the second half of the same opt-in: supplied, the
+ * evaluator checks the journal's declared mandated pair against these ids
+ * rather than merely checking that it declared two non-empty ones. Repeatable,
+ * separate-argument form, and bounded to the run family's own id charset before
+ * it reaches the kernel.
  */
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { deliveryRecordPathFor, parseDeliveryRecord, verifyDeliveryRecord } from "@agent-delivery-harness/kernel";
+import {
+  MAX_RUN_PROVIDER_ID,
+  RUN_PROVIDER_ID,
+  deliveryRecordPathFor,
+  needsCommittedSymlinkTarget,
+  parseCandidateTreeListing,
+  parseDeliveryRecord,
+  runGitCommand,
+  verifyDeliveryRecord,
+  capturePortableVerificationInputs,
+  collectLiveProviderResults,
+  type CandidateTreeEntry,
+  type RunJournalRow,
+} from "@agent-delivery-harness/kernel";
 import { commandBlocker } from "../boundary.ts";
 import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { oneLine, resolveRunJournalRow, runJournalRows } from "../run-surface.ts";
+
+const USAGE = "Usage: delivery-harness verify [--require-run-journal] [--mandated-lens <id>]...";
+
+interface ParsedArgs {
+  readonly requireRunJournal: boolean;
+  readonly mandatedLensIds: readonly string[];
+}
+
+type ArgParse = { readonly ok: true; readonly args: ParsedArgs } | { readonly ok: false; readonly message: string };
+
+/**
+ * The separate-argument form every other command's flags take: `--flag value`,
+ * never `--flag=value`. The joined form is not silently split, because a
+ * `--mandated-lens=x` that quietly worked here and nowhere else would be a
+ * second grammar for the same CLI. It falls through to the unknown-flag arm,
+ * which is a usage error naming the token.
+ */
+function parseArgs(args: readonly string[]): ArgParse {
+  let requireRunJournal = false;
+  const mandatedLensIds: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (token === "--require-run-journal") {
+      requireRunJournal = true;
+      continue;
+    }
+    if (token === "--mandated-lens") {
+      const value = args[index + 1];
+      if (value === undefined) return { ok: false, message: `${token} needs a value.\n${USAGE}` };
+      // Bounded before the kernel sees it: an id is compared against journal
+      // content, and an unbounded one would be echoed into the row it produces.
+      if (value.length > MAX_RUN_PROVIDER_ID || !RUN_PROVIDER_ID.test(value)) {
+        return { ok: false, message: `${token} takes a bounded lens id, not ${oneLine(value, 64)}.\n${USAGE}` };
+      }
+      mandatedLensIds.push(value);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) return { ok: false, message: `Unknown flag ${oneLine(token, 64)}.\n${USAGE}` };
+    return { ok: false, message: `verify takes no positional arguments, and ${oneLine(token, 64)} is one.\n${USAGE}` };
+  }
+  return { ok: true, args: { requireRunJournal, mandatedLensIds } };
+}
+
+/**
+ * The opt-in's refusal. It names the status, the missing entries, and the
+ * violated constraints, all of them product-defined names from the evaluator's
+ * two closed sets — never journal-derived text.
+ */
+function runJournalBlocker(row: RunJournalRow) {
+  const missing = row.missing.length === 0 ? "(none)" : row.missing.join(", ");
+  const violations = row.violations === undefined || row.violations.length === 0 ? "(none)" : row.violations.join(", ");
+  return commandBlocker({
+    code: "run_journal_incomplete",
+    sourceId: "delivery-harness.cli.verify",
+    summary: "The run journal for this candidate is not complete, and --require-run-journal was given.",
+    details: `status ${row.status}${row.runId === undefined ? "" : ` (run ${oneLine(row.runId, 128)})`}; missing: ${missing}; violations: ${violations}`,
+    remediations: [
+      {
+        id: "emit-the-missing-run-events",
+        kind: "manual_action",
+        summary: "Emit the run events this delivery did not journal, or drop --require-run-journal: the row is observability, not evidence.",
+      },
+    ],
+  });
+}
 
 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);
+    if (!parsedArgs.ok) return { kind: "usage", message: parsedArgs.message };
+
     const wiring = await context.wire();
     const capture = await wiring.captureCandidate();
     if (!capture.ok) {
@@ -67,17 +173,79 @@ export const verifyCommand: CommandDescriptor = {
       return { kind: "blocked", blockers: [...parsed.blockers] };
     }
 
-    const check = verifyDeliveryRecord(context.config, parsed.record, identity, base);
-    if (!check.ok) {
-      return { kind: "blocked", blockers: [...check.blockers] };
+    // The tracked tree's own entries, so this command rejects a candidate
+    // carrying a projection or discovery-configuration path exactly as the
+    // Action does. An unreadable listing supplies no entries rather than a
+    // false clean bill: the check simply does not run.
+    //
+    // Mode and object, not just the name: the one admitted exception under
+    // `.claude/skills/` turns on the entry being a symlink and on where its
+    // committed target resolves, and both facts live in the tree.
+    const listing = await runGitCommand(["git", "ls-tree", "-r", "-z", "--full-tree", "HEAD"], {
+      cwd: context.rootDir,
+    });
+    const candidateTreePaths: CandidateTreeEntry[] = [];
+    if (listing.exitCode === 0) {
+      for (const entry of parseCandidateTreeListing(listing.stdout)) {
+        if (!needsCommittedSymlinkTarget(entry)) {
+          candidateTreePaths.push(entry);
+          continue;
+        }
+        // The target read out of the committed blob, never off the filesystem:
+        // the working tree's link may differ from the one under review. A blob
+        // that will not read leaves the target absent, and an entry with no
+        // target cannot reach the exception.
+        const blob = await runGitCommand(["git", "cat-file", "blob", entry.objectSha], { cwd: context.rootDir });
+        candidateTreePaths.push(blob.exitCode === 0 ? { ...entry, symlinkTarget: blob.stdout } : entry);
+      }
+    }
+
+    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, ...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.
+    if (parsedArgs.args.requireRunJournal && runJournal.status !== "complete") {
+      return { kind: "blocked", blockers: [runJournalBlocker(runJournal)] };
     }
 
     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}`,
+      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 seven-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,55 +12,91 @@
  * 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";
+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 { runCliBoundary, type CliRuntime, type CommandDescriptor } from "./boundary.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
  * follows the loop an operator walks: prepare, review, submit, gate, record,
- * verify — with `check` last as the standalone preflight.
+ * verify — with `check` as the standalone preflight and `managed` as the
+ * host-facing managed-delivery checkpoint surface and `maintain` as the
+ * installation-scoped maintenance lane.
+ *
+ * `emit` and `runs` come last because they are a different class: config-free
+ * commands, dispatched before `harness.config.ts` is loaded, that read and
+ * write the run store rather than anything a delivery decision depends on.
  */
-export const COMMANDS: readonly CommandDescriptor[] = [
+export const COMMANDS: readonly AnyCommandDescriptor[] = [
+  admitCommand,
   prepareCommand,
   reviewContextCommand,
+  emitReviewEvidenceCommand,
   submitEvidenceCommand,
   gateCommand,
   recordCommand,
   verifyCommand,
   checkCommand,
+  managedCommand,
+  maintainCommand,
+  emitCommand,
+  runsCommand,
+  saveContextCommand,
+  resumeCommand,
 ];
 
 export {
+  COMPLETION_WRAPPED_COMMANDS,
   EXIT_INTERRUPTED,
   EXIT_OK,
   EXIT_POLICY,
   EXIT_USAGE,
   CliInterruption,
+  isConfigFreeCommand,
   runCliBoundary,
   wireRepo,
   importHarnessConfig,
   commandBlocker,
+  type AnyCommandDescriptor,
   type CliRuntime,
   type CommandContext,
   type CommandDescriptor,
   type CommandResult,
+  type ConfigFreeCommandContext,
+  type ConfigFreeCommandDescriptor,
   type RepoWiring,
 } 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";
 export { verifyCommand } from "./commands/verify.ts";
 export { checkCommand } from "./commands/check.ts";
+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,43 +84,26 @@ 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.
+ * Reads the whole of stdin as UTF-8.
  *
- * 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.
+ * `emit` takes its payload here, and the one thing that must never happen is a
+ * hang: a terminal with no pipe attached would otherwise leave the command
+ * waiting forever for a line nobody is going to type. A TTY stdin therefore
+ * reads as empty, and the store refuses the empty payload with a diagnostic,
+ * which is a far better answer than silence.
  */
-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);
+export function readStdinText(input: NodeJS.ReadableStream & { isTTY?: boolean }): Promise<string> {
+  if (input.isTTY === true) return Promise.resolve("");
+  return new Promise((resolve) => {
+    let text = "";
+    input.setEncoding("utf8");
+    input.on("data", (chunk: string) => {
+      text += chunk;
+    });
+    input.once("error", () => resolve(text));
+    input.once("end", () => resolve(text));
+  });
 }
 
 export function defaultRuntime(): CliRuntime {
@@ -120,6 +115,7 @@ export function defaultRuntime(): CliRuntime {
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text),
     promptForWaiver: readlineWaiverPrompt,
+    readStdin: () => readStdinText(process.stdin),
   };
 }