@kungfu-tech/buildchain 3.0.3 → 3.0.4-alpha.1

package/scripts/auditable-demo-renditions.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const TERMINAL_CAPTURE_NON_AUTHORITIES = [
+  "first-party-identity",
+  "system-identity",
+  "kfd-compliance",
+  "product-system-metadata",
+  "package-metadata",
+  "registry-history",
+  "scan-output",
+  "standalone-generation",
+];
+const RENDITION_SET_NON_AUTHORITIES = [
+  "publication-authority",
+  "runtime-authority",
+  ...TERMINAL_CAPTURE_NON_AUTHORITIES,
+];
+
+export function validateTerminalCapture(value, scene, helpers) {
+  const { decodeBase64, digestPattern, exactKeys, integer, invariant, maxBytes, maxEvents, text } = helpers;
+  exactKeys(
+    value,
+    ["schema", "command", "dimensions", "durationMs", "encoding", "events", "completion", "exitCode", "authority"],
+    [],
+    "terminalCapture",
+  );
+  invariant(value.schema === "kungfu.terminal-capture/v1", "unsupported terminal capture schema");
+  text(value.command, 1, 160, "terminalCapture.command");
+  exactKeys(value.dimensions, ["columns", "rows"], [], "terminalCapture.dimensions");
+  integer(value.dimensions.columns, 80, 200, "terminalCapture.dimensions.columns");
+  integer(value.dimensions.rows, 24, 80, "terminalCapture.dimensions.rows");
+  const durationMs = integer(value.durationMs, 500, 60000, "terminalCapture.durationMs");
+  invariant(
+    durationMs <= scene.durationMs && scene.durationMs - durationMs <= 2000,
+    "terminal capture duration must end within two seconds of the scene",
+  );
+  invariant(value.encoding === "base64", "terminalCapture.encoding must be base64");
+  invariant(
+    Array.isArray(value.events) && value.events.length > 0 && value.events.length <= maxEvents,
+    `terminalCapture.events must contain 1 through ${maxEvents} events`,
+  );
+  let previousAtMs = -1;
+  let totalBytes = 0;
+  for (const [index, event] of value.events.entries()) {
+    exactKeys(event, ["atMs", "data"], [], `terminalCapture.events[${index}]`);
+    const atMs = integer(event.atMs, 0, durationMs - 1, `terminalCapture.events[${index}].atMs`);
+    invariant(atMs >= previousAtMs, "terminal capture event timestamps must be monotonic");
+    invariant(index > 0 || atMs === 0, "the first terminal capture event must start at zero");
+    previousAtMs = atMs;
+    totalBytes += decodeBase64(event.data, `terminalCapture.events[${index}].data`).length;
+    invariant(totalBytes <= maxBytes, "terminal capture exceeds the 4 MiB byte bound");
+  }
+  exactKeys(value.completion, ["schema", "status", "reportRoot", "eventCount"], [], "terminalCapture.completion");
+  invariant(
+    value.completion.schema === "kungfu.agent-work-lab.tui-autoplay/v1"
+      && value.completion.status === "qualified"
+      && digestPattern.test(value.completion.reportRoot),
+    "terminal capture completion sentinel is not a qualified Agent Work Lab autoplay",
+  );
+  integer(value.completion.eventCount, 1, 100_000, "terminalCapture.completion.eventCount");
+  invariant(value.exitCode === 0, "terminal capture exitCode must be zero");
+  exactKeys(value.authority, ["classification", "grants", "nonAuthorities"], [], "terminalCapture.authority");
+  invariant(value.authority.classification === "volatile-terminal-observation", "terminal capture authority classification must remain observation-only");
+  invariant(Array.isArray(value.authority.grants) && value.authority.grants.length === 0, "terminal capture must not grant authority");
+  invariant(
+    JSON.stringify(value.authority.nonAuthorities) === JSON.stringify(TERMINAL_CAPTURE_NON_AUTHORITIES),
+    "terminal capture must declare every identity and metadata non-authority",
+  );
+  return value;
+}
+
+export function validateRenditionSet(output, helpers) {
+  const { decodeUtf8, exactKeys, invariant, maxBytes, readJson, readRegular, sha256, validateProjection, validateScene } = helpers;
+  const manifestPath = path.join(output, "rendition-set.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  const value = readJson(manifestPath, "rendition set");
+  exactKeys(value, ["schema", "renditions", "authority"], [], "renditionSet");
+  invariant(value.schema === "kungfu.auditable-demo.rendition-set/v1", "unsupported rendition set schema");
+  exactKeys(value.authority, ["classification", "grants", "nonAuthorities"], [], "renditionSet.authority");
+  invariant(
+    value.authority.classification === "capture-routing-metadata"
+      && Array.isArray(value.authority.grants)
+      && value.authority.grants.length === 0
+      && JSON.stringify(value.authority.nonAuthorities) === JSON.stringify(RENDITION_SET_NON_AUTHORITIES),
+    "rendition set authority boundary is invalid",
+  );
+  invariant(Array.isArray(value.renditions) && value.renditions.length === 2, "rendition set must contain exactly two captures");
+  const expected = [
+    {
+      id: "1080p", role: "primary", transcript: "complete-transcript.txt",
+      projection: "public-projection.json", scene: "scene.json", terminalCapture: "terminal-capture.json",
+      width: 1920, height: 1080,
+    },
+    {
+      id: "720p", role: "responsive", transcript: "complete-transcript-720p.txt",
+      projection: "public-projection-720p.json", scene: "scene-720p.json", terminalCapture: "terminal-capture-720p.json",
+      width: 1280, height: 720,
+    },
+  ];
+  const normalized = value.renditions.map((entry, index) => {
+    const label = `renditionSet.renditions[${index}]`;
+    exactKeys(entry, ["id", "role", "transcript", "projection", "scene", "terminalCapture", "captureRoot"], [], label);
+    const declaration = expected[index];
+    for (const key of ["id", "role", "transcript", "projection", "scene", "terminalCapture"]) {
+      invariant(entry[key] === declaration[key], `${label}.${key} is not the exact native rendition contract`);
+    }
+    const transcriptBytes = readRegular(path.join(output, entry.transcript), `${label} transcript`, 4 * 1024 * 1024);
+    const transcript = decodeUtf8(transcriptBytes, `${label} transcript`).replace(/\r\n/g, "\n");
+    invariant(transcript.trim().length > 0, `${label} transcript must not be empty`);
+    const lines = transcript.endsWith("\n") ? transcript.slice(0, -1).split("\n") : transcript.split("\n");
+    const scene = validateScene(readJson(path.join(output, entry.scene), `${label} scene`));
+    invariant(scene.width === declaration.width && scene.height === declaration.height, `${label} scene dimensions are not native`);
+    const projection = validateProjection(readJson(path.join(output, entry.projection), `${label} projection`), scene, lines.length);
+    const captureBytes = readRegular(path.join(output, entry.terminalCapture), `${label} terminal capture`, maxBytes);
+    const capture = validateTerminalCapture(JSON.parse(decodeUtf8(captureBytes, `${label} terminal capture`)), scene, helpers);
+    invariant(entry.captureRoot === sha256(captureBytes), `${label}.captureRoot mismatch`);
+    return { ...entry, transcript, lines, scene, projection, capture };
+  });
+  invariant(normalized[0].captureRoot !== normalized[1].captureRoot, "native rendition capture roots must be distinct");
+  invariant(
+    JSON.stringify(normalized[0].capture.dimensions) !== JSON.stringify(normalized[1].capture.dimensions),
+    "native rendition PTY dimensions must be distinct",
+  );
+  invariant(
+    normalized[0].projection.evidenceClass === normalized[1].projection.evidenceClass
+      && normalized[0].projection.claimBoundary === normalized[1].projection.claimBoundary,
+    "native rendition evidence boundaries must match",
+  );
+  return { schema: value.schema, renditions: normalized, authority: value.authority };
+}

package/scripts/auditable-demo.mjs

@@ -7,6 +7,10 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import {
+  validateRenditionSet,
+  validateTerminalCapture,
+} from "./auditable-demo-renditions.mjs";
 
 const UTF8 = new TextDecoder("utf-8", { fatal: true });
 const IMAGE_PATTERN = /^[a-z0-9][a-z0-9./_-]*@sha256:[0-9a-f]{64}$/;
@@ -22,19 +26,16 @@ const REQUIRED_ADAPTER_FILES = [
   "public-projection.json",
   "scene.json",
 ];
-const OPTIONAL_ADAPTER_FILES = ["terminal-capture.json"];
+const OPTIONAL_ADAPTER_FILES = [
+  "terminal-capture.json",
+  "complete-transcript-720p.txt",
+  "public-projection-720p.json",
+  "scene-720p.json",
+  "terminal-capture-720p.json",
+  "rendition-set.json",
+];
 const MAX_TERMINAL_CAPTURE_BYTES = 4 * 1024 * 1024;
 const MAX_TERMINAL_CAPTURE_EVENTS = 10_000;
-const TERMINAL_CAPTURE_NON_AUTHORITIES = [
-  "first-party-identity",
-  "system-identity",
-  "kfd-compliance",
-  "product-system-metadata",
-  "package-metadata",
-  "registry-history",
-  "scan-output",
-  "standalone-generation",
-];
 
 function invariant(condition, message) {
   if (!condition) throw new Error(message);
@@ -249,80 +250,11 @@ function validateProjection(value, scene, transcriptLineCount) {
   };
 }
 
-function validateTerminalCapture(value, scene) {
-  exactKeys(
-    value,
-    [
-      "schema",
-      "command",
-      "dimensions",
-      "durationMs",
-      "encoding",
-      "events",
-      "completion",
-      "exitCode",
-      "authority",
-    ],
-    [],
-    "terminalCapture",
-  );
-  invariant(value.schema === "kungfu.terminal-capture/v1", "unsupported terminal capture schema");
-  text(value.command, 1, 160, "terminalCapture.command");
-  exactKeys(value.dimensions, ["columns", "rows"], [], "terminalCapture.dimensions");
-  integer(value.dimensions.columns, 80, 200, "terminalCapture.dimensions.columns");
-  integer(value.dimensions.rows, 24, 80, "terminalCapture.dimensions.rows");
-  const durationMs = integer(value.durationMs, 500, 60000, "terminalCapture.durationMs");
-  invariant(
-    durationMs <= scene.durationMs && scene.durationMs - durationMs <= 2000,
-    "terminal capture duration must end within two seconds of the scene",
-  );
-  invariant(value.encoding === "base64", "terminalCapture.encoding must be base64");
-  invariant(
-    Array.isArray(value.events)
-      && value.events.length > 0
-      && value.events.length <= MAX_TERMINAL_CAPTURE_EVENTS,
-    `terminalCapture.events must contain 1 through ${MAX_TERMINAL_CAPTURE_EVENTS} events`,
-  );
-  let previousAtMs = -1;
-  let totalBytes = 0;
-  for (const [index, event] of value.events.entries()) {
-    exactKeys(event, ["atMs", "data"], [], `terminalCapture.events[${index}]`);
-    const atMs = integer(event.atMs, 0, durationMs - 1, `terminalCapture.events[${index}].atMs`);
-    invariant(atMs >= previousAtMs, "terminal capture event timestamps must be monotonic");
-    invariant(index > 0 || atMs === 0, "the first terminal capture event must start at zero");
-    previousAtMs = atMs;
-    totalBytes += decodeBase64(event.data, `terminalCapture.events[${index}].data`).length;
-    invariant(totalBytes <= MAX_TERMINAL_CAPTURE_BYTES, "terminal capture exceeds the 4 MiB byte bound");
-  }
-  exactKeys(
-    value.completion,
-    ["schema", "status", "reportRoot", "eventCount"],
-    [],
-    "terminalCapture.completion",
-  );
-  invariant(
-    value.completion.schema === "kungfu.agent-work-lab.tui-autoplay/v1"
-      && value.completion.status === "qualified"
-      && DIGEST_PATTERN.test(value.completion.reportRoot),
-    "terminal capture completion sentinel is not a qualified Agent Work Lab autoplay",
-  );
-  integer(value.completion.eventCount, 1, 100_000, "terminalCapture.completion.eventCount");
-  invariant(value.exitCode === 0, "terminal capture exitCode must be zero");
-  exactKeys(value.authority, ["classification", "grants", "nonAuthorities"], [], "terminalCapture.authority");
-  invariant(
-    value.authority.classification === "volatile-terminal-observation",
-    "terminal capture authority classification must remain observation-only",
-  );
-  invariant(
-    Array.isArray(value.authority.grants) && value.authority.grants.length === 0,
-    "terminal capture must not grant authority",
-  );
-  invariant(
-    JSON.stringify(value.authority.nonAuthorities) === JSON.stringify(TERMINAL_CAPTURE_NON_AUTHORITIES),
-    "terminal capture must declare every identity and metadata non-authority",
-  );
-  return value;
-}
+const RENDITION_VALIDATION_HELPERS = {
+  decodeBase64, decodeUtf8, digestPattern: DIGEST_PATTERN, exactKeys, integer, invariant,
+  maxBytes: MAX_TERMINAL_CAPTURE_BYTES, maxEvents: MAX_TERMINAL_CAPTURE_EVENTS,
+  readJson, readRegular, sha256, text, validateProjection, validateScene,
+};
 
 function validateSourceCoordinate(value) {
   exactKeys(
@@ -379,8 +311,17 @@ function validateAdapterOutput(output, strict = true) {
   );
   const terminalCapturePath = path.join(output, "terminal-capture.json");
   const terminalCapture = fs.existsSync(terminalCapturePath)
-    ? validateTerminalCapture(readJson(terminalCapturePath, "terminal capture"), scene)
+    ? validateTerminalCapture(
+      readJson(terminalCapturePath, "terminal capture"),
+      scene,
+      RENDITION_VALIDATION_HELPERS,
+    )
     : null;
+  const renditionSet = validateRenditionSet(output, RENDITION_VALIDATION_HELPERS);
+  invariant(
+    !renditionSet || terminalCapture,
+    "rendition set requires the primary terminal capture",
+  );
   if (strict) {
     const allowed = new Set([...REQUIRED_ADAPTER_FILES, ...OPTIONAL_ADAPTER_FILES]);
     for (const member of listFiles(output)) invariant(allowed.has(member), `undeclared adapter output: ${member}`);
@@ -391,6 +332,7 @@ function validateAdapterOutput(output, strict = true) {
     scene,
     projection,
     terminalCapture,
+    renditionSet,
   };
 }
 
@@ -1047,6 +989,21 @@ function verifyRendererOutput(renderOutput, expectedImage, expectedInputs, optio
     const observed = manifest.inputs?.[key]?.root;
     invariant(observed === sha256(readRegular(filePath, `${key} input`)), `renderer ${key} input root mismatch`);
   }
+  if (expectedInputs.renditionSet) {
+    invariant(
+      manifest.derivation?.policy === "independent-native-frame-sets/v1",
+      "renderer did not use independent native frame sets",
+    );
+    invariant(
+      Array.isArray(manifest.inputs?.renditions)
+        && manifest.inputs.renditions.length === 2
+        && manifest.inputs.renditions[0]?.role === "primary"
+        && manifest.inputs.renditions[1]?.role === "responsive"
+        && manifest.inputs.renditions[0]?.terminalCapture?.root
+          !== manifest.inputs.renditions[1]?.terminalCapture?.root,
+      "renderer native rendition inputs are not independently bound",
+    );
+  }
   const probe = readJson(path.join(renderOutput, "media-probe.json"), "media probe");
   invariant(probe.schema === "build-images.demo-media-probe/v1" && probe.passed === true, "renderer media probe failed");
   const qualification = qualifyRendererOutput(
@@ -1099,11 +1056,10 @@ function finalizeGate(values) {
   fs.writeFileSync(path.join(output, "complete-transcript.txt"), normalized.transcript);
   writeJson(path.join(output, "scene.json"), normalized.scene);
   writeJson(path.join(output, "public-projection.json"), normalized.projection);
-  if (normalized.terminalCapture) {
-    copyFile(
-      path.join(adapterOutput, "terminal-capture.json"),
-      path.join(output, "terminal-capture.json"),
-    );
+  for (const name of OPTIONAL_ADAPTER_FILES) {
+    if (fs.existsSync(path.join(adapterOutput, name))) {
+      copyFile(path.join(adapterOutput, name), path.join(output, name));
+    }
   }
   copyFile(sourceCoordinatePath, path.join(output, "source-artifact.json"));
   copyFile(path.join(diagnostics, "adapter.json"), path.join(output, "adapter.json"));
@@ -1148,6 +1104,22 @@ function finalizeGate(values) {
           },
         }
         : {}),
+      ...(normalized.renditionSet
+        ? {
+          renditionSet: {
+            schema: normalized.renditionSet.schema,
+            root: sha256(readRegular(path.join(output, "rendition-set.json"), "rendition set")),
+            renditions: normalized.renditionSet.renditions.map((rendition) => ({
+              id: rendition.id,
+              role: rendition.role,
+              captureRoot: rendition.captureRoot,
+              sceneRoot: sha256(readRegular(path.join(output, rendition.scene), `${rendition.id} scene`)),
+              transcriptRoot: sha256(readRegular(path.join(output, rendition.transcript), `${rendition.id} transcript`)),
+              projectionRoot: sha256(readRegular(path.join(output, rendition.projection), `${rendition.id} projection`)),
+            })),
+          },
+        }
+        : {}),
       evidenceClass: normalized.projection.evidenceClass,
       claimBoundary: normalized.projection.claimBoundary,
     },
@@ -1198,6 +1170,27 @@ function verifyGate(values) {
       "gate terminal capture root mismatch",
     );
   }
+  const qualifiedRenditionSet = receipt.qualifiedInputs?.renditionSet;
+  invariant(
+    Boolean(qualifiedRenditionSet) === Boolean(normalized.renditionSet),
+    "gate rendition set presence drifted",
+  );
+  if (normalized.renditionSet) {
+    invariant(
+      qualifiedRenditionSet.schema === normalized.renditionSet.schema
+        && qualifiedRenditionSet.root === sha256(readRegular(path.join(bundle, "rendition-set.json"), "rendition set"))
+        && JSON.stringify(qualifiedRenditionSet.renditions)
+          === JSON.stringify(normalized.renditionSet.renditions.map((rendition) => ({
+            id: rendition.id,
+            role: rendition.role,
+            captureRoot: rendition.captureRoot,
+            sceneRoot: sha256(readRegular(path.join(bundle, rendition.scene), `${rendition.id} scene`)),
+            transcriptRoot: sha256(readRegular(path.join(bundle, rendition.transcript), `${rendition.id} transcript`)),
+            projectionRoot: sha256(readRegular(path.join(bundle, rendition.projection), `${rendition.id} projection`)),
+          }))),
+      "gate native rendition roots mismatch",
+    );
+  }
   invariant(receipt.qualifiedInputs.evidenceClass === normalized.projection.evidenceClass, "gate evidence class drifted");
 }
 
@@ -1228,6 +1221,7 @@ function finalizeMedia(values) {
     "--media-profile": mediaProfile,
   });
   const terminalCapturePath = path.join(gateBundle, "terminal-capture.json");
+  const renditionSetPath = path.join(gateBundle, "rendition-set.json");
   const verifiedRenderer = verifyRendererOutput(renderOutput, rendererImage, {
     scene: path.join(gateBundle, "scene.json"),
     transcript: path.join(gateBundle, "complete-transcript.txt"),
@@ -1235,6 +1229,9 @@ function finalizeMedia(values) {
     ...(fs.existsSync(terminalCapturePath)
       ? { terminalCapture: terminalCapturePath }
       : {}),
+    ...(fs.existsSync(renditionSetPath)
+      ? { renditionSet: renditionSetPath }
+      : {}),
   }, {
     mediaProfile,
     inspectMedia: mediaInspection?.inspectMedia,

package/scripts/buildchain-cli-help.mjs

@@ -199,6 +199,7 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain paper work submit [--cwd <dir>] [--title <title>] [--body <body>] [--execute] [--json]
   buildchain paper fleet audit [--root <dir>] [--offline] [--json]
   buildchain paper fleet update [--root <dir>] [--write] [--json]
+  buildchain paper agent verify [--cwd <dir>] [--offline] [--json]
   buildchain paper preflight [--cwd <dir>] [--offline] [--json]
   buildchain paper bootstrap npm [--cwd <dir>] [--execute]
                                   [--confirm-public-package <name>] [--json]

package/scripts/paper-agent-cli.mjs

@@ -0,0 +1,35 @@
+import { collectPaperPreflight } from "../packages/core/paper.js";
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) return fallback;
+  return args[index + 1] || "";
+}
+
+export function runPaperAgentCli({
+  command,
+  subcommand,
+  args,
+  cwd,
+  buildchainRoot,
+  buildchainVersion,
+  buildchainRef,
+  buildchainSha,
+}) {
+  if (command !== "agent" || subcommand !== "verify") {
+    return { handled: false, result: null };
+  }
+  return {
+    handled: true,
+    result: collectPaperPreflight({
+      cwd,
+      buildchainRoot,
+      buildchainVersion,
+      buildchainRef: readFlag(args, "buildchain-ref", buildchainRef),
+      buildchainSha,
+      registry: readFlag(args, "registry", "https://registry.npmjs.org/"),
+      offline: args.includes("--offline"),
+      agentEntryMode: "local",
+    }),
+  };
+}

package/scripts/paper-work-fleet-cli.mjs

@@ -368,12 +368,13 @@ function githubGovernance(cwd, repository) {
   }
 }
 
-function runWorkStart({ args, cwd }) {
+function runWorkStart({ args, cwd, buildchainSha }) {
   const topic = args[0]?.startsWith("--") ? "" : args[0] || "";
   const plan = createPaperWorkStartPlan({
     cwd,
     topic,
     branch: readFlag(args, "branch"),
+    buildchainSha,
   });
   return args.includes("--execute") ? executePaperWorkStart(plan) : plan;
 }
@@ -382,7 +383,11 @@ function runScaffold(options) {
   const plan = planPaperScaffold({
     cwd: options.cwd,
     buildchainRoot: options.buildchainRoot,
-    buildchainVersion: options.buildchainVersion,
+    buildchainVersion: readFlag(
+      options.args,
+      "buildchain-version",
+      options.buildchainVersion,
+    ),
     buildchainRef: readFlag(
       options.args,
       "buildchain-ref",
@@ -405,7 +410,11 @@ function runMigration(options) {
   const plan = planPaperMigration({
     cwd: options.cwd,
     buildchainRoot: options.buildchainRoot,
-    buildchainVersion: options.buildchainVersion,
+    buildchainVersion: readFlag(
+      options.args,
+      "buildchain-version",
+      options.buildchainVersion,
+    ),
     buildchainSha: options.buildchainSha,
   });
   return options.args.some((entry) => ["--write", "--execute"].includes(entry))
@@ -413,7 +422,7 @@ function runMigration(options) {
     : plan;
 }
 
-function runWorkSubmit({ args, cwd }) {
+function runWorkSubmit({ args, cwd, buildchainSha }) {
   const repository = collectPaperStatus({ cwd }).identity.repository;
   const branch = commandResult("git", ["branch", "--show-current"], {
     cwd,
@@ -426,6 +435,7 @@ function runWorkSubmit({ args, cwd }) {
     cwd,
     pullRequests: observation.rows,
     pullRequestObservation: observation,
+    buildchainSha,
   });
   return args.includes("--execute") ? executeWorkSubmit(plan, args) : plan;
 }

package/scripts/paper.mjs

@@ -13,6 +13,7 @@ import {
   PAPER_SCAFFOLD_CONTRACT,
   PAPER_STATUS_CONTRACT,
   collectPaperPreflight,
+  resolvePaperBuildchainSha,
   collectPaperStatus,
   createPaperAlphaPlan,
   createPaperBuildPlan,
@@ -24,6 +25,7 @@ import {
   printPaperWorkFleetSummary,
   runPaperWorkFleetCli,
 } from "./paper-work-fleet-cli.mjs";
+import { runPaperAgentCli } from "./paper-agent-cli.mjs";
 
 function usage() {
   return `Usage:
@@ -38,6 +40,7 @@ function usage() {
                                [--execute] [--json]
   buildchain paper fleet audit [--root <dir>] [--offline] [--json]
   buildchain paper fleet update [--root <dir>] [--write] [--json]
+  buildchain paper agent verify [--cwd <dir>] [--offline] [--json]
   buildchain paper preflight [--cwd <dir>] [--offline] [--json]
   buildchain paper bootstrap npm [--cwd <dir>] [--package <name>]
                                   [--repository <owner/repo>] [--workflow <filename>]
@@ -455,6 +458,7 @@ export async function runPaperCli(
     buildchainSha = "",
   } = {},
 ) {
+  buildchainSha = resolvePaperBuildchainSha(buildchainRoot, buildchainSha);
   const [command = "", maybeSubcommand = "", ...rest] = args;
   const json = hasFlag(args, "json");
   try {
@@ -476,8 +480,12 @@ export async function runPaperCli(
       buildchainRef,
       buildchainSha,
     });
+    // prettier-ignore
+    const paperAgent = runPaperAgentCli({ command, subcommand: maybeSubcommand, args: effectiveArgs, cwd, buildchainRoot, buildchainVersion, buildchainRef, buildchainSha });
     let result;
-    if (workFleet.handled) {
+    if (paperAgent.handled) {
+      result = paperAgent.result;
+    } else if (workFleet.handled) {
       result = workFleet.result;
     } else if (command === "preflight") {
       result = collectPaperPreflight({
@@ -492,6 +500,11 @@ export async function runPaperCli(
           "https://registry.npmjs.org/",
         ),
         offline: hasFlag(effectiveArgs, "offline"),
+        agentEntryMode: hasFlag(effectiveArgs, "ci")
+          ? "ci"
+          : hasFlag(effectiveArgs, "agent-entry")
+            ? "local"
+            : "contract",
       });
     } else if (command === "bootstrap" && maybeSubcommand === "npm") {
       result = executePaperNpmBootstrap({
@@ -577,7 +590,7 @@ export async function runPaperCli(
         : plan;
     } else {
       throw new Error(
-        "usage: buildchain paper <scaffold|migrate|work start|work submit|fleet audit|fleet update|preflight|bootstrap npm|build|alpha|status|resume> ...",
+        "usage: buildchain paper <scaffold|migrate|work start|work submit|fleet audit|fleet update|agent verify|preflight|bootstrap npm|build|alpha|status|resume> ...",
       );
     }
     printResult(result, json);

package/scripts/site-capability-metadata.mjs

@@ -97,6 +97,7 @@ export function cliCommandMeta(id) {
     "portable-cache-receipt": { group: "observability-diagnostics", purpose: "Seal exact, compatible, miss, or corrupt provider evidence against one cache plan." },
     "npm-dry-run": { group: "release-passport-trust", purpose: "Verify npm publish shape before a release transaction." },
     paper: { group: "reusable-build", purpose: "Inspect the unified paper repository and publication command families." },
+    "paper-agent": { group: "getting-started", purpose: "Verify the mandatory managed Paper agent entry contract on an existing work branch." },
     "paper-alpha": { group: "release-passport-trust", purpose: "Plan or open the protected dev-to-alpha paper publication PR without direct publication." },
     "paper-bootstrap-npm": { group: "release-passport-trust", purpose: "Dry-run or explicitly bootstrap the public npm package and bind GitHub Trusted Publishing." },
     "paper-build": { group: "reusable-build", purpose: "Plan or execute the existing two-clean-build reproducibility gate for a paper." },
@@ -199,4 +200,3 @@ export function nodeApiMeta(exportName) {
   }
   return { capabilityGroup: capabilityGroup(meta.group), summary: meta.summary, audience: ["developer", "agent"], maturity: "stable" };
 }
-