@agent-delivery-harness/cli 0.1.0 → 0.2.0

package/src/commands/emit.ts

@@ -0,0 +1,351 @@
+/**
+ * `emit` — append one run event to the current delivery run's journal.
+ *
+ * THE EXECUTOR'S ONE WRITE PATH. Everything an executor knows that the product
+ * cannot observe — which lenses it chose and why, what it decided at a fork,
+ * what a review round cost — arrives here or is lost to a transcript. The
+ * command is deliberately small: a kind, a JSON payload, and the store.
+ *
+ * WHAT `emit` MAY NOT SET. Not `seq`, which is the store's, taken inside its
+ * critical section. Not `at`, which is this process's own instant. Not
+ * `actor`, which is always `executor` here — the boundary wrap is the only
+ * writer of `cli`, and the store refuses `cli` on any other kind. And not
+ * `command.completed` at all: a completion is a claim that the product ran a
+ * command, and only the product may make it. That refusal is noted in the
+ * run's note exactly like any other refused append, so an executor that tries
+ * leaves a trace rather than nothing.
+ *
+ * ORDER OF OPERATIONS, AND WHY IT IS THIS ORDER.
+ *   1. Arguments. A malformed invocation is a usage error and touches nothing.
+ *   2. The repository. Outside one there is no store, so there is nowhere to
+ *      write and nowhere to note.
+ *   3. The run. Resolution precedes kind validation, because a refused append
+ *      is recorded against a run — with no run there is nothing to note
+ *      against, and inventing one would create a journal for a typo.
+ *      `run.started` is the single exception: it allocates the run it needs.
+ *   4. The store. Kind and payload validation, the secret discipline, and the
+ *      note on refusal are all the store's, so there is exactly one
+ *      implementation of each.
+ */
+import {
+  RUN_STORE_ID,
+  reduceToProviderId,
+  type RunStore,
+} from "@agent-delivery-harness/kernel";
+import {
+  buildRunEvent,
+  oneLine,
+  resolveRunSurface,
+  runSurfaceBlocker,
+  type RunSurface,
+} from "../run-surface.ts";
+import type { CommandResult, ConfigFreeCommandContext, ConfigFreeCommandDescriptor } from "../boundary.ts";
+
+const USAGE = "Usage: delivery-harness emit <kind> [--run <id>] [--json <payload>] [--force]";
+
+interface ParsedArgs {
+  readonly kind: string;
+  readonly run?: string;
+  readonly json?: string;
+  readonly force: boolean;
+}
+
+type ArgParse = { readonly ok: true; readonly args: ParsedArgs } | { readonly ok: false; readonly message: string };
+
+function parseArgs(args: readonly string[]): ArgParse {
+  let kind: string | undefined;
+  let run: string | undefined;
+  let json: string | undefined;
+  let force = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (token === "--force") {
+      force = true;
+      continue;
+    }
+    if (token === "--run" || token === "--json") {
+      const value = args[index + 1];
+      if (value === undefined) return { ok: false, message: `${token} needs a value.\n${USAGE}` };
+      if (token === "--run") run = value;
+      else json = value;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--")) return { ok: false, message: `Unknown flag ${oneLine(token, 64)}.\n${USAGE}` };
+    if (kind !== undefined) return { ok: false, message: `emit takes one kind.\n${USAGE}` };
+    kind = token;
+  }
+
+  if (kind === undefined) return { ok: false, message: `emit needs a kind.\n${USAGE}` };
+  return { ok: true, args: { kind, force, ...(run === undefined ? {} : { run }), ...(json === undefined ? {} : { json }) } };
+}
+
+/**
+ * The payload as the caller supplied it. Text that is not JSON is passed
+ * through as-is rather than rejected here: the store owns payload validation,
+ * and routing it there is what puts the refusal in the run's note.
+ */
+function parsePayload(text: string): unknown {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return {};
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return trimmed;
+  }
+}
+
+const noRun = (details: string) =>
+  runSurfaceBlocker({
+    code: "run_unresolvable",
+    summary: "There is no current run to emit against.",
+    details,
+    remediation: {
+      id: "start-a-run",
+      summary: "Run `delivery-harness emit run.started` in this worktree, or name an existing run with --run.",
+    },
+  });
+
+/**
+ * Resolves the run this event belongs to: `--run` when given, else the
+ * invoking worktree's pointer. An explicit `--run` resolves only when the id
+ * passes the charset check AND its journal exists, so no arbitrary id ever
+ * causes a journal or a note to be created.
+ */
+async function resolveRun(store: RunStore, surface: RunSurface, named: string | undefined): Promise<string | undefined> {
+  if (named !== undefined) {
+    if (named.length > 128 || !RUN_STORE_ID.test(named)) return undefined;
+    const read = await store.read(named);
+    return read.ok ? named : undefined;
+  }
+  const current = await store.current(surface.worktreeKey);
+  return current.ok ? current.runId : undefined;
+}
+
+export const emitCommand: ConfigFreeCommandDescriptor = {
+  name: "emit",
+  sourceId: "delivery-harness.cli.emit",
+  summary: "Append one run event to the current delivery run's journal.",
+  configFree: true,
+  async run(context: ConfigFreeCommandContext): Promise<CommandResult> {
+    const parsed = parseArgs(context.args);
+    if (!parsed.ok) return { kind: "usage", message: parsed.message };
+    const { kind, run: named, force } = parsed.args;
+
+    const resolved = await resolveRunSurface(context.rootDir);
+    if (!resolved.ok) {
+      return {
+        kind: "blocked",
+        blockers: [
+          runSurfaceBlocker({
+            code: "run_store_unresolvable",
+            summary: "The run store could not be resolved.",
+            details: oneLine(resolved.reason, 200),
+            remediation: {
+              id: "run-inside-a-repository",
+              summary: "Run this command inside a git repository; the run store lives under its common directory.",
+            },
+          }),
+        ],
+      };
+    }
+    const surface = resolved.surface;
+    const store = surface.store;
+
+    if (kind === "run.started") {
+      return startRun(surface, force, parsePayload(parsed.args.json ?? (await context.readStdin())));
+    }
+
+    const runId = await resolveRun(store, surface, named);
+    if (runId === undefined) {
+      return {
+        kind: "blocked",
+        blockers: [
+          noRun(
+            named === undefined
+              ? "no current run is pointed at from this worktree, and no --run was given"
+              : `--run ${oneLine(named, 128)} names no readable journal in this store`,
+          ),
+        ],
+      };
+    }
+
+    const payload = parsePayload(parsed.args.json ?? (await context.readStdin()));
+    const event = buildRunEvent({ runId, commonDir: surface.commonDir, kind, role: "executor", payload });
+
+    // `command.completed` is the CLI's to write. The refusal is recorded in the
+    // run's note through the store's one bounded note writer, so an attempt
+    // leaves the same trace as any other refused append.
+    if (kind === "command.completed") {
+      await store.noteRefusal(runId, event, {
+        code: "unsupported_combination",
+        pointer: "/kind",
+        message: "command.completed is written by the CLI; emit may not write it",
+      });
+      return {
+        kind: "blocked",
+        blockers: [
+          runSurfaceBlocker({
+            code: "run_event_refused",
+            summary: "command.completed is written by the CLI, never by emit.",
+            details: `run ${runId}: the product's own commands append their completions; an executor reports a non-product gate with gate.reported`,
+            remediation: {
+              id: "use-gate-reported",
+              summary: "Emit gate.reported when the repository's gate is not a product command.",
+            },
+          }),
+        ],
+      };
+    }
+
+    const appended = await store.append(runId, event);
+    if (!appended.ok) {
+      const first = appended.rejections[0];
+      return {
+        kind: "blocked",
+        blockers: [
+          runSurfaceBlocker({
+            code: "run_event_refused",
+            // The rejected kind is echoed reduced to the bound the note records
+            // it at, so the diagnostic and the durable line say the same thing
+            // and neither can carry an escape sequence to the terminal.
+            summary: `The run event was refused: ${reduceToProviderId(kind)}`,
+            details: `run ${runId}: ${first === undefined ? "the store refused the append" : `${first.code} at ${oneLine(first.pointer, 64) || "/"}: ${oneLine(first.message, 200)}`}`,
+            remediation: {
+              id: "correct-the-event",
+              summary: "Correct the kind or the payload against the run-event/1 contract and emit again.",
+            },
+          }),
+        ],
+      };
+    }
+
+    if (kind === "run.ended") await store.clearCurrent(surface.worktreeKey, runId);
+    return { kind: "ok", summary: `emitted ${appended.event.kind} seq ${appended.event.seq} to run ${runId}` };
+  },
+};
+
+/**
+ * `run.started` is the one kind that allocates rather than resolves.
+ *
+ * The pointer is read BEFORE the journal is allocated, so the ordinary refusal
+ * — a run is already current and no `--force` was given — leaves no orphan
+ * journal behind. `--force` carries the displaced run's id into the new run's
+ * own `run.started` payload, which is what makes a restarted delivery legible
+ * afterwards.
+ */
+async function startRun(surface: RunSurface, force: boolean, supplied: unknown): Promise<CommandResult> {
+  const store = surface.store;
+  const existing = await store.current(surface.worktreeKey);
+  const displaced = existing.ok ? existing.runId : undefined;
+  if (displaced !== undefined && !force) {
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_already_current",
+          summary: "A run is already current for this worktree.",
+          details: `run ${displaced} is current; --force displaces it and records it as displacedRunId`,
+          remediation: {
+            id: "end-or-force",
+            summary: "End the current run with `emit run.ended`, or start this one with --force.",
+          },
+        }),
+      ],
+    };
+  }
+
+  const allocated = await store.allocate();
+  if (!allocated.ok) {
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_not_allocated",
+          summary: "A run journal could not be allocated.",
+          details: oneLine(allocated.rejections[0]?.message ?? "the store refused to allocate", 200),
+          remediation: { id: "check-the-store", summary: "Check that the repository's git common directory is writable." },
+        }),
+      ],
+    };
+  }
+  const runId = allocated.runId;
+
+  const payload =
+    typeof supplied === "object" && supplied !== null && displaced !== undefined
+      ? { ...(supplied as Record<string, unknown>), displacedRunId: displaced }
+      : supplied;
+
+  const appended = await store.append(
+    runId,
+    buildRunEvent({ runId, commonDir: surface.commonDir, kind: "run.started", role: "executor", payload }),
+  );
+  if (!appended.ok) {
+    const first = appended.rejections[0];
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_event_refused",
+          summary: "The run event was refused: run.started",
+          details: `run ${runId}: ${first === undefined ? "the store refused the append" : `${first.code} at ${oneLine(first.pointer, 64) || "/"}: ${oneLine(first.message, 200)}`}`,
+          remediation: {
+            id: "correct-the-event",
+            summary: "Correct the payload against the run-event/1 contract and emit again.",
+          },
+        }),
+      ],
+    };
+  }
+
+  let pointed = await store.setCurrent(surface.worktreeKey, runId, { force });
+  let displacedStale = false;
+  // A STALE POINTER IS NOT A CONFLICT. `current` answers `undefined` both when
+  // no pointer exists and when one exists naming a journal this store can no
+  // longer read — a pruned store, a restored `.git`. In the second case the
+  // exclusive create below refuses, and without this the caller's only recourse
+  // is to retry, allocating one more orphan journal per attempt. Re-reading the
+  // pointer separates the two: a run that is now current is a genuine race and
+  // is still refused; a pointer that still names nothing is stale and is
+  // displaced, which is what the operator meant.
+  if (!pointed.ok && !force) {
+    const recheck = await store.current(surface.worktreeKey);
+    if (recheck.ok && recheck.runId === undefined) {
+      pointed = await store.setCurrent(surface.worktreeKey, runId, { force: true });
+      displacedStale = pointed.ok;
+    }
+  }
+  if (!pointed.ok) {
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_pointer_refused",
+          summary: "The worktree pointer could not be written.",
+          details: `run ${runId}: ${oneLine(pointed.rejections[0]?.message ?? "the pointer was refused", 200)}`,
+          // `--run` cannot help here: `run.started` allocates rather than
+          // resolves, so it never reads that flag. `--force` is the one thing
+          // that displaces a pointer this command refused to overwrite.
+          remediation: { id: "force-the-start", summary: "Start the run with --force to displace the pointer that is already current." },
+        }),
+      ],
+    };
+  }
+
+  // A stale displacement has no id to record — the pointer named nothing this
+  // store could read, which is why it was displaceable at all — so the summary
+  // is the only place the operator learns it happened. It is also the only
+  // signal that the store itself needs attention: a pointer reaches this state
+  // through a pruned journal, a truncated write, or a permissions fault.
+  return {
+    kind: "ok",
+    summary: `started run ${runId}${
+      displaced === undefined
+        ? displacedStale
+          ? " (displaced a stale pointer naming no readable run; the run store may need attention)"
+          : ""
+        : ` (displaced ${displaced})`
+    }`,
+  };
+}

package/src/commands/gate.ts

@@ -9,29 +9,113 @@
  * only ever offers a waiver to a `human` context, all-or-nothing over waivable
  * findings; the CLI adds no waiver logic of its own.
  */
-import { runAdmission } from "@agent-delivery-harness/kernel";
-import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { runAdmission, type AdmissionResult, type Blocker, type LiveProviderResult } from "@agent-delivery-harness/kernel";
+import { CliInterruption, type CommandContext, type CommandDescriptor, type CommandResult } from "../boundary.ts";
+
+/**
+ * Runs the ordinary admission first, invokes only configured providers that can
+ * answer the resulting missing-evidence/live-result blocks, then re-evaluates
+ * through the same admission adapter. Configs without provider commands take
+ * the pre-existing path unchanged.
+ */
+export async function runProviderBackedAdmission(
+  context: CommandContext,
+  options: { readonly allowPrompt: boolean; readonly includeInjectedLiveResults: boolean },
+): Promise<AdmissionResult> {
+  const wiring = await context.wire();
+  const admissionOptions = {
+    captureCandidate: wiring.captureCandidate,
+    projectActivation: wiring.projectActivation,
+    ...wiring.storageOptions,
+  };
+  const input = {
+    rootDir: context.rootDir,
+    config: context.config,
+    context: context.classifyContext(),
+    ...(options.includeInjectedLiveResults && context.liveResults !== undefined ? { liveResults: context.liveResults } : {}),
+  };
+  const finalAdmissionOptions = {
+    ...admissionOptions,
+    ...(options.allowPrompt && context.promptForWaiver !== undefined ? { promptForWaiver: context.promptForWaiver } : {}),
+  };
+
+  if (!context.config.providers.some((provider) => provider.command !== undefined)) {
+    return runAdmission(input, finalAdmissionOptions);
+  }
+
+  const liveResults: LiveProviderResult[] = options.includeInjectedLiveResults ? [...(context.liveResults ?? [])] : [];
+  const attempted = new Set<string>();
+  const attemptBlockers: Blocker[] = [];
+  let admission = await runAdmission(input, admissionOptions);
+
+  while (!admission.admitted && admission.decision !== undefined && admission.candidate !== undefined) {
+    const requested = new Map<string, { obligationIds: string[]; requiresEvidence: boolean; needsLiveResult: boolean }>();
+    for (const resolution of admission.decision.resolutions) {
+      if (resolution.kind !== "blocked") continue;
+      const obligation = context.config.obligations.find((entry) => entry.id === resolution.obligationId);
+      if (obligation === undefined) continue;
+      const missingCode = obligation.freshness === "live" ? "live_provider_missing" : "review_evidence_missing";
+      for (const finding of resolution.providerFindings ?? []) {
+        if (finding.code !== missingCode || finding.providerId === undefined || attempted.has(finding.providerId)) continue;
+        const registration = context.config.providers.find((provider) => provider.id === finding.providerId);
+        if (registration?.command === undefined || !obligation.providers.includes(registration.id)) continue;
+        const entry = requested.get(registration.id) ?? { obligationIds: [], requiresEvidence: false, needsLiveResult: false };
+        entry.obligationIds.push(obligation.id);
+        entry.requiresEvidence ||= obligation.freshness === "exact_candidate";
+        entry.needsLiveResult ||= obligation.freshness === "live";
+        requested.set(registration.id, entry);
+      }
+    }
+
+    const next = requested.entries().next().value as
+      | [string, { obligationIds: string[]; requiresEvidence: boolean; needsLiveResult: boolean }]
+      | undefined;
+    if (next === undefined) break;
+    const [providerId, request] = next;
+    attempted.add(providerId);
+    const result = await context.invokeProvider?.({
+      providerId,
+      requiresEvidence: request.requiresEvidence,
+      payload: {
+        gateId: context.config.gateId,
+        providerId,
+        obligationIds: [...new Set(request.obligationIds)].sort(),
+        candidate: admission.candidate,
+      },
+    });
+    if (result === undefined) continue;
+    if (result.kind === "interrupted") throw new CliInterruption("Provider invocation interrupted before a trustworthy terminal outcome.");
+    if (result.kind === "blocked") {
+      attemptBlockers.push(...result.blockers);
+      if (request.needsLiveResult) {
+        liveResults.push({ providerId, runId: result.runId, status: "failed", findings: [] });
+      }
+    } else if (request.needsLiveResult) {
+      liveResults.push(result.liveResult);
+    }
+
+    admission = await runAdmission(
+      { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
+      admissionOptions,
+    );
+  }
+
+  if (admission.admitted) return admission;
+  const final = await runAdmission(
+    { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
+    finalAdmissionOptions,
+  );
+  return attemptBlockers.length === 0 || final.admitted
+    ? final
+    : { ...final, blockers: [...attemptBlockers, ...final.blockers] };
+}
 
 export const gateCommand: CommandDescriptor = {
   name: "gate",
   sourceId: "delivery-harness.cli.gate",
   summary: "Evaluate the delivery gate for the current candidate.",
   async run(context: CommandContext): Promise<CommandResult> {
-    const wiring = await context.wire();
-    const result = await runAdmission(
-      {
-        rootDir: context.rootDir,
-        config: context.config,
-        context: context.classifyContext(),
-        ...(context.liveResults === undefined ? {} : { liveResults: context.liveResults }),
-      },
-      {
-        captureCandidate: wiring.captureCandidate,
-        projectActivation: wiring.projectActivation,
-        ...(context.promptForWaiver === undefined ? {} : { promptForWaiver: context.promptForWaiver }),
-        ...wiring.storageOptions,
-      },
-    );
+    const result = await runProviderBackedAdmission(context, { allowPrompt: true, includeInjectedLiveResults: true });
 
     if (result.admitted) {
       const waiverNote =

package/src/commands/maintain.ts

@@ -0,0 +1,202 @@
+/**
+ * `maintain` — the installation-scoped maintenance lane: update, rollback, and
+ * trust-state maintenance.
+ *
+ * WHY THIS IS A SEPARATE COMMAND. `managed` addresses one delivery and its
+ * checkpoints; these operations address the installation itself and touch no
+ * delivery journal at all. Folding them into `managed` would have made a
+ * delivery resolve before an operator could repair the installation that
+ * delivery is blocked on — the wrong order for exactly the case the lane
+ * exists to serve.
+ *
+ * WHAT DEFENDS THIS SURFACE, PRECISELY. Every operation here consumes a
+ * maintenance-lane sensitive assertion bound to the target installation and
+ * generation identities, evaluated by the installation's configured assertion
+ * source in the model-external lane, and consumed BEFORE any byte moves. The
+ * caller cannot mint that assertion and cannot answer the evaluation: the
+ * operating system evaluates it and the product never sees a credential. So a
+ * model that invokes one of these cannot complete it.
+ *
+ * WHAT IT DOES NOT DEFEND, STATED PLAINLY BECAUSE IT IS EASY TO ASSUME
+ * OTHERWISE. It does not stop the prompt from being raised. Probing an
+ * OS-native source checks that the platform's authentication surfaces exist,
+ * and existence is independent of whether the caller holds a terminal — so on a
+ * desktop platform a non-interactive session can still reach `evaluate`, which
+ * raises an interactive dialog in the operator's own session. Authorization
+ * holds, because nobody but the operator can answer it; what is not defended is
+ * the operator's attention. Prompt fatigue is the residual risk on this surface,
+ * and it is the reason to keep the lane narrow rather than to believe it closed.
+ *
+ * Operator confirmations are the class that must never be nameable on a shell
+ * surface, and none of them appear here.
+ *
+ * The installation is located the same way `managed` locates it: from the
+ * product namespace's pointer under the common git directory, never a
+ * candidate-writable path.
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { compiledAdopterPolicyBindingDigest, createManagedDeliveryFacade, type CompiledAdopterPolicyBinding, type ManagedDeliveryFacade } from "@agent-delivery-harness/kernel";
+import { commandBlocker } from "../boundary.ts";
+import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+
+const SOURCE_ID = "delivery-harness.cli.maintain";
+
+/** Every operation this command answers, in the order its usage lists them. */
+const MAINTAIN_OPERATIONS: readonly string[] = Object.freeze([
+  "update",
+  "rollback",
+  "pin",
+  "revoke",
+  "unrevoke",
+  "advance-high-water-mark",
+]);
+
+const blocked = (code: string, summary: string, remediation: string): CommandResult => ({
+  kind: "blocked",
+  blockers: [
+    commandBlocker({
+      code,
+      sourceId: SOURCE_ID,
+      summary,
+      remediations: [{ id: `${code.replaceAll("_", "-")}-remediation`, kind: "manual_action", summary: remediation }],
+    }),
+  ],
+});
+
+const gitCommonDir = (cwd: string): Promise<string | undefined> =>
+  new Promise((resolve) => {
+    execFile("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd, encoding: "utf8" }, (error, stdout) => {
+      resolve(error === null ? stdout.trim() : undefined);
+    });
+  });
+
+const flag = (args: readonly string[], name: string): string | undefined => {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+};
+
+function nowInstant(): string {
+  return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+
+async function resolveFacade(context: CommandContext): Promise<ManagedDeliveryFacade | CommandResult> {
+  const common = await gitCommonDir(context.rootDir);
+  if (common === undefined) {
+    return blocked("not_a_repository", "The working directory is not a git repository.", "Run from the repository the product is installed for.");
+  }
+  let pointer: { installationPath: string; receiptDir: string; hostVersion: string; policyBindingDigest: string };
+  try {
+    pointer = JSON.parse(await readFile(path.join(common, "managed-delivery", "facade.json"), "utf8")) as typeof pointer;
+  } catch {
+    return blocked(
+      "no_managed_installation",
+      "No managed installation is registered for this repository.",
+      "Install the composition and register a delivery first.",
+    );
+  }
+  let policyBinding: CompiledAdopterPolicyBinding | undefined = context.policyBinding;
+  if (policyBinding === undefined) {
+    try {
+      policyBinding = JSON.parse(await readFile(path.join(common, "managed-delivery", "policy-binding.json"), "utf8")) as CompiledAdopterPolicyBinding;
+    } catch {
+      return blocked(
+        "policy_binding_missing",
+        "No compiled adopter policy binding is retained for this installation.",
+        "Register a delivery through an adopter binding, or pass one through the embedding runtime.",
+      );
+    }
+  }
+  if (pointer.policyBindingDigest !== compiledAdopterPolicyBindingDigest(policyBinding)) {
+    return blocked(
+      "policy_binding_mismatch",
+      "The retained compiled adopter policy binding does not match the product namespace pointer.",
+      "Restore the exact binding captured at registration; drift requires a new owner-approved delivery.",
+    );
+  }
+  return createManagedDeliveryFacade({
+    repoDir: context.rootDir,
+    policyBinding,
+    installation: { installationPath: pointer.installationPath, receiptDir: pointer.receiptDir },
+    hostVersion: pointer.hostVersion,
+  });
+}
+
+const isCommandResult = (value: ManagedDeliveryFacade | CommandResult): value is CommandResult => "kind" in value;
+
+export const maintainCommand: CommandDescriptor = {
+  name: "maintain",
+  sourceId: SOURCE_ID,
+  summary: "Maintain the product installation (update, rollback, trust-state pin/revoke/unrevoke/high-water-mark).",
+  async run(context: CommandContext): Promise<CommandResult> {
+    const [operation, ...rest] = context.args;
+    if (operation === undefined) {
+      return { kind: "usage", message: `maintain requires an operation: ${MAINTAIN_OPERATIONS.join(" | ")}` };
+    }
+    // A typo is a usage error about the call, answered before the repository
+    // or the installation is consulted.
+    if (!MAINTAIN_OPERATIONS.includes(operation)) {
+      return { kind: "usage", message: `Unknown maintain operation: ${operation}.` };
+    }
+    const resolved = await resolveFacade(context);
+    if (isCommandResult(resolved)) return resolved;
+    const facade = resolved;
+    const now = nowInstant();
+    const emit = (value: unknown): void => context.write(`${JSON.stringify(value, null, 2)}\n`);
+
+    switch (operation) {
+      case "update": {
+        const packedDir = flag(rest, "--packed");
+        if (packedDir === undefined) {
+          return { kind: "usage", message: "update requires --packed <dir> naming the verified packed generation to install." };
+        }
+        const outcome = await facade.updateComposition({ packedDir: path.resolve(context.rootDir, packedDir), now });
+        if (!outcome.ok) return { kind: "blocked", blockers: [...outcome.blockers] };
+        emit(outcome);
+        return {
+          kind: "ok",
+          summary: outcome.noOp
+            ? `already at ${outcome.generationDigest}`
+            : `updated ${outcome.priorGenerationDigest} -> ${outcome.generationDigest}`,
+        };
+      }
+      case "rollback": {
+        const target = flag(rest, "--generation");
+        if (target === undefined) {
+          return { kind: "usage", message: "rollback requires --generation <digest> naming a previously accepted generation." };
+        }
+        const outcome = await facade.rollbackComposition({ targetGenerationDigest: target, now });
+        if (!outcome.ok) return { kind: "blocked", blockers: [...outcome.blockers] };
+        return { kind: "ok", summary: `rolled back to ${outcome.generationDigest}` };
+      }
+      case "pin":
+      case "revoke":
+      case "unrevoke": {
+        const generationDigest = flag(rest, "--generation");
+        if (generationDigest === undefined) {
+          return { kind: "usage", message: `${operation} requires --generation <digest>.` };
+        }
+        const outcome = await facade.maintainTrustState({ operation, generationDigest, now });
+        if (!outcome.ok) return { kind: "blocked", blockers: [...outcome.blockers] };
+        emit(outcome.state);
+        return { kind: "ok", summary: `${operation} recorded at revocation epoch ${outcome.state.revocationEpoch}` };
+      }
+      case "advance-high-water-mark": {
+        const raw = flag(rest, "--to");
+        const highWaterMark = raw === undefined ? Number.NaN : Number.parseInt(raw, 10);
+        if (!Number.isInteger(highWaterMark)) {
+          return { kind: "usage", message: "advance-high-water-mark requires --to <integer>." };
+        }
+        const outcome = await facade.maintainTrustState({ operation: "advance-high-water-mark", highWaterMark, now });
+        if (!outcome.ok) return { kind: "blocked", blockers: [...outcome.blockers] };
+        emit(outcome.state);
+        return { kind: "ok", summary: `high-water mark is ${outcome.state.highWaterMark}` };
+      }
+      default:
+        // Unreachable: checked against MAINTAIN_OPERATIONS above. Kept so a
+        // name added to that list without a case here fails loudly.
+        return { kind: "usage", message: `Unknown maintain operation: ${operation}.` };
+    }
+  },
+};