@openthink/stamp 2.0.2 → 2.1.1

package/dist/index.js

@@ -52,7 +52,7 @@ import {
   userKeysDir,
   userServerConfigPath,
   verifyBytes
-} from "./chunk-4PFD2DSY.js";
+} from "./chunk-MJULVH4B.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -541,8 +541,12 @@ function validateConfig(input) {
       throw new Error(`config.reviewers.${name} must be an object`);
     }
     const d = def;
-    if (typeof d.prompt !== "string") {
-      throw new Error(`config.reviewers.${name}.prompt must be a string`);
+    let prompt2;
+    if (d.prompt !== void 0) {
+      if (typeof d.prompt !== "string") {
+        throw new Error(`config.reviewers.${name}.prompt must be a string`);
+      }
+      prompt2 = d.prompt;
     }
     const tools = parseTools(d.tools, name);
     const mcp_servers = parseMcpServers(d.mcp_servers, name);
@@ -564,7 +568,7 @@ function validateConfig(input) {
       `config.reviewers.${name}.timeout_ms`
     );
     reviewers2[name] = {
-      prompt: d.prompt,
+      ...prompt2 !== void 0 ? { prompt: prompt2 } : {},
       ...tools ? { tools } : {},
       ...mcp_servers ? { mcp_servers } : {},
       ...enforce_reads_on_dotstamp !== void 0 ? { enforce_reads_on_dotstamp } : {},
@@ -1412,8 +1416,8 @@ import { createHash as createHash3, createPublicKey, verify } from "crypto";
 import { spawn } from "child_process";
 
 // src/lib/attestationV4.ts
-var CURRENT_V4_SCHEMA_VERSION = 4;
-var MIN_ACCEPTED_V4_SCHEMA_VERSION = 4;
+var CURRENT_V4_SCHEMA_VERSION = 5;
+var MIN_ACCEPTED_V4_SCHEMA_VERSION = 5;
 var MAX_V4_ENVELOPE_BYTES = 64 * 1024;
 function sortKeysDeep(value) {
   if (value === null || typeof value !== "object") return value;
@@ -1547,7 +1551,6 @@ function parseResponseJson(raw) {
     "diff_sha256",
     "base_sha",
     "head_sha",
-    "trusted_keys_snapshot_sha256",
     "issued_at",
     "server_key_id"
   ]) {
@@ -1945,6 +1948,7 @@ function buildTrustAnchorPayload(input) {
     head_sha: input.headSha,
     target_branch: input.targetBranch,
     diff_sha256: input.diffSha256,
+    manifest_snapshot_sha256: input.manifestSnapshotSha256,
     approvals: input.approvals,
     checks: input.checks,
     trust_anchor_signatures: [],
@@ -2027,6 +2031,11 @@ var COMMIT_PHASES_V4 = [
   { name: "verifyV4TargetBranch", fn: verifyV4TargetBranch },
   { name: "verifyV4SignerTrust", fn: verifyV4SignerTrust },
   { name: "verifyV4OuterSignature", fn: verifyV4OuterSignature },
+  // AGT-370: envelope-level manifest snapshot binding (lifted from
+  // the per-approval slot in v4). Runs once before the per-approval
+  // loop in verifyV4ApprovalSignatures — a single check replaces the
+  // N-checks per envelope the v4 verifier did.
+  { name: "verifyV4ManifestSnapshot", fn: verifyV4ManifestSnapshot },
   { name: "verifyV4Approvals", fn: verifyV4Approvals },
   { name: "verifyV4DiffHash", fn: verifyV4DiffHash },
   { name: "verifyV4ApprovalSignatures", fn: verifyV4ApprovalSignatures },
@@ -2159,10 +2168,19 @@ function verifyV4DiffHash(input) {
   }
   return { ok: true };
 }
+function verifyV4ManifestSnapshot(input) {
+  const { sha, payload, manifest } = input;
+  const computed = snapshotSha256(manifest);
+  if (payload.manifest_snapshot_sha256 !== computed) {
+    return {
+      ok: false,
+      reason: `commit ${sha.slice(0, 8)}: v4 manifest_snapshot_sha256 (${payload.manifest_snapshot_sha256.slice(0, 16)}\u2026) does not match the manifest at base ${payload.base_sha.slice(0, 8)} (${computed.slice(0, 16)}\u2026). The envelope was signed against a different snapshot of the trust set than the one committed at the merge base. Re-run \`stamp merge\` (or \`stamp attest\`) so the outer signature binds to the current manifest.`
+    };
+  }
+  return { ok: true };
+}
 function verifyV4ApprovalSignatures(input) {
   const { sha, payload, manifest, pubkeyByFingerprint } = input;
-  const manifestSnapshot = snapshotSha256(manifest);
-  const reviewerDefs = readReviewerDefsAtRef(payload.base_sha);
   for (const entry of payload.approvals) {
     const a = entry.approval;
     const reviewerLabel = `"${a.reviewer}"`;
@@ -2184,12 +2202,6 @@ function verifyV4ApprovalSignatures(input) {
         reason: `commit ${sha.slice(0, 8)}: v4 approval ${reviewerLabel}: server_attestation.server_key_id (${entry.server_attestation.server_key_id}) does not match inner approval.server_key_id (${a.server_key_id}). The inner signed payload is authoritative; one of the two was tampered with after signing.`
       };
     }
-    if (a.trusted_keys_snapshot_sha256 !== manifestSnapshot) {
-      return {
-        ok: false,
-        reason: `commit ${sha.slice(0, 8)}: v4 approval ${reviewerLabel}: trusted_keys_snapshot_sha256 (${a.trusted_keys_snapshot_sha256.slice(0, 16)}\u2026) does not match the manifest at base ${payload.base_sha.slice(0, 8)} (${manifestSnapshot.slice(0, 16)}\u2026). The server signed against a different snapshot of the trust set than the one committed at the merge base.`
-      };
-    }
     const caps = resolveCapability(manifest, a.server_key_id);
     if (caps === null) {
       return {
@@ -2229,29 +2241,6 @@ function verifyV4ApprovalSignatures(input) {
         reason: `commit ${sha.slice(0, 8)}: v4 approval ${reviewerLabel}: server signature does not verify against ${a.server_key_id} over canonical approval bytes`
       };
     }
-    const def = reviewerDefs[a.reviewer];
-    if (!def) {
-      return {
-        ok: false,
-        reason: `commit ${sha.slice(0, 8)}: v4 approval ${reviewerLabel}: reviewer is not defined in .stamp/config.yml at base ${payload.base_sha.slice(0, 8)}`
-      };
-    }
-    let promptText;
-    try {
-      promptText = run(["show", `${payload.base_sha}:${def.prompt}`]);
-    } catch {
-      return {
-        ok: false,
-        reason: `commit ${sha.slice(0, 8)}: v4 approval ${reviewerLabel}: prompt "${def.prompt}" is unreadable at base ${payload.base_sha.slice(0, 8)}`
-      };
-    }
-    const recomputedPromptSha = hashPromptBytes(Buffer.from(promptText, "utf8"));
-    if (recomputedPromptSha !== a.prompt_sha256) {
-      return {
-        ok: false,
-        reason: `commit ${sha.slice(0, 8)}: v4 approval ${reviewerLabel}: prompt_sha256 mismatch \u2014 server signed ${a.prompt_sha256.slice(0, 12)}\u2026 but prompt file at base hashes to ${recomputedPromptSha.slice(0, 12)}\u2026. The reviewer prompt the server reviewed differs from the one in the merge-base tree.`
-      };
-    }
   }
   return { ok: true };
 }
@@ -2417,22 +2406,6 @@ function readPubkeyMapAt(ref) {
   }
   return buildPubkeyMap(names, (relPath) => run(["show", `${ref}:${relPath}`]));
 }
-function readReviewerDefsAtRef(ref) {
-  let yaml;
-  try {
-    yaml = run(["show", `${ref}:.stamp/config.yml`]);
-  } catch {
-    return {};
-  }
-  const defs = readReviewersFromYaml(yaml);
-  const out = {};
-  for (const [name, def] of Object.entries(defs)) {
-    if (def && typeof def.prompt === "string") {
-      out[name] = { prompt: def.prompt };
-    }
-  }
-  return out;
-}
 function readChangedFilesAtRef(baseSha, headSha) {
   let out;
   try {
@@ -2820,6 +2793,12 @@ function verifyReviewerHashesAtMergeBase(input) {
         reason: `${prefix} reviewer "${approval.reviewer}" not defined in .stamp/config.yml at merge-base`
       };
     }
+    if (def.prompt === void 0) {
+      return {
+        ok: false,
+        reason: `${prefix} reviewer "${approval.reviewer}" has no \`prompt:\` in .stamp/config.yml at merge-base; v3 attestation references prompt_sha256 but the producer flow for server-bundled prompts is v4 (server-attested). The attestation envelope and the config shape are inconsistent.`
+      };
+    }
     let promptBytes;
     try {
       promptBytes = run2(["show", `${baseSha}:${def.prompt}`]);
@@ -3403,6 +3382,11 @@ function buildV3Trailers(input) {
         `reviewer "${a.reviewer}" approved the diff but is not defined in .stamp/config.yml at base ${input.baseSha.slice(0, 8)}. This shouldn't happen \u2014 runReview reads from the same base. File a bug at https://github.com/OpenThinkAi/stamp-cli/issues. Merge rolled back.`
       );
     }
+    if (def.prompt === void 0) {
+      throw new Error(
+        `reviewer "${a.reviewer}": no \`prompt:\` configured and no \`review_server:\` on branch rule \u2014 set \`reviewers.${a.reviewer}.prompt\` in .stamp/config.yml or configure a \`review_server:\` for server-attested mode. Merge rolled back.`
+      );
+    }
     const promptText = showAtRef(input.baseSha, def.prompt, input.repoRoot);
     const source = readReviewerSource(a.reviewer, input.repoRoot);
     return {
@@ -3489,7 +3473,6 @@ function buildV4Trailers(input) {
         "diff_sha256",
         "base_sha",
         "head_sha",
-        "trusted_keys_snapshot_sha256",
         "issued_at",
         "server_key_id"
       ]) {
@@ -3569,12 +3552,14 @@ function buildV4Trailers(input) {
     exit_code: c.exit_code,
     output_sha: c.output_sha
   }));
+  const manifestSnapshot = snapshotSha256(manifest);
   const trustAnchorSigs = collectTrustAnchorSignatures({
     repoRoot: input.repoRoot,
     baseSha: input.baseSha,
     headSha: input.headSha,
     targetBranch: input.targetBranch,
     diffSha256,
+    manifestSnapshotSha256: manifestSnapshot,
     approvals: entries,
     checks: v4Checks,
     operatorFingerprint: input.operatorFingerprint,
@@ -3587,6 +3572,7 @@ function buildV4Trailers(input) {
     head_sha: input.headSha,
     target_branch: input.targetBranch,
     diff_sha256: diffSha256,
+    manifest_snapshot_sha256: manifestSnapshot,
     approvals: entries,
     checks: v4Checks,
     trust_anchor_signatures: trustAnchorSigs,
@@ -3638,6 +3624,7 @@ function collectTrustAnchorSignatures(input) {
     headSha: input.headSha,
     targetBranch: input.targetBranch,
     diffSha256: input.diffSha256,
+    manifestSnapshotSha256: input.manifestSnapshotSha256,
     approvals: input.approvals,
     checks: input.checks,
     signerKeyId: input.operatorFingerprint
@@ -4731,6 +4718,11 @@ function buildReviewPlan(opts) {
   const reviewers2 = [];
   for (const name of reviewerNames) {
     const def = config2.reviewers[name];
+    if (def.prompt === void 0) {
+      throw new Error(
+        `reviewer "${name}": no \`prompt:\` configured and no \`review_server:\` on branch rule \u2014 set \`reviewers.${name}.prompt\` in .stamp/config.yml or configure a \`review_server:\` for server-attested mode.`
+      );
+    }
     let prompt2;
     try {
       prompt2 = showAtRef(resolved.base_sha, def.prompt, opts.repoRoot);
@@ -5340,19 +5332,6 @@ async function runReview(opts) {
       `no reviewers to run at base ${resolved.base_sha.slice(0, 8)} (config there has ${Object.keys(config2.reviewers).length} configured). If this branch ADDS a new reviewer, the new reviewer cannot review its own introduction \u2014 that's a deliberate security boundary. Land the reviewer in a separate PR first, then it can review subsequent diffs.`
     );
   }
-  const promptBytesByReviewer = /* @__PURE__ */ new Map();
-  for (const name of reviewerNames) {
-    const def = config2.reviewers[name];
-    let bytes;
-    try {
-      bytes = showAtRef(resolved.base_sha, def.prompt, repoRoot);
-    } catch (err) {
-      throw new Error(
-        `failed to read prompt for reviewer "${name}" from base ${resolved.base_sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}. (The reviewer is configured at the base but its prompt file is missing there.)`
-      );
-    }
-    promptBytesByReviewer.set(name, bytes);
-  }
   const targetBranch = opts.into ?? inferTargetBranch(opts.diff);
   const branchRule = targetBranch ? findBranchRule(config2.branches, targetBranch) : void 0;
   if (branchRule?.review_server) {
@@ -5360,7 +5339,7 @@ async function runReview(opts) {
       opts,
       config: config2,
       reviewerNames,
-      promptBytesByReviewer,
+      promptBytesByReviewer: /* @__PURE__ */ new Map(),
       resolved,
       repoRoot,
       reviewServerUrl: branchRule.review_server,
@@ -5368,6 +5347,24 @@ async function runReview(opts) {
     });
     return;
   }
+  const promptBytesByReviewer = /* @__PURE__ */ new Map();
+  for (const name of reviewerNames) {
+    const def = config2.reviewers[name];
+    if (def.prompt === void 0) {
+      throw new Error(
+        `reviewer "${name}": no \`prompt:\` configured and no \`review_server:\` on branch rule \u2014 set \`reviewers.${name}.prompt\` in .stamp/config.yml or configure a \`review_server:\` for server-attested mode.`
+      );
+    }
+    let bytes;
+    try {
+      bytes = showAtRef(resolved.base_sha, def.prompt, repoRoot);
+    } catch (err) {
+      throw new Error(
+        `failed to read prompt for reviewer "${name}" from base ${resolved.base_sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}. (The reviewer is configured at the base but its prompt file is missing there.)`
+      );
+    }
+    promptBytesByReviewer.set(name, bytes);
+  }
   maybePrintLlmNotice(repoRoot);
   const userCfg = loadOrCreateUserConfig();
   if (userCfg.created) {
@@ -5896,6 +5893,7 @@ function buildPlan(current, targetBranch, targetRule, opts) {
     }
     newReviewersConfig = seed.config.reviewers;
     for (const [name, def] of Object.entries(seed.config.reviewers)) {
+      if (def.prompt === void 0) continue;
       const promptBody = seed.reviewerFiles.get(def.prompt);
       if (promptBody === void 0) {
         throw new Error(
@@ -9487,11 +9485,13 @@ function signPending(repoRoot, rawSha, opts) {
     }
     predictedSigner = opts.signerKeyId;
   }
+  const manifestSnapshotSha256 = snapshotSha256(manifest);
   const signingBytes = trustAnchorSigningBytes({
     baseSha,
     headSha,
     targetBranch,
     diffSha256,
+    manifestSnapshotSha256,
     approvals,
     checks: [],
     // see trustAnchorPayload.ts "Operational caveat"
@@ -10140,8 +10140,9 @@ function printReviewHistory(repoRoot, limit, diff) {
 }
 
 // src/commands/attest.ts
-import { spawnSync as spawnSync14 } from "child_process";
+import { spawnSync as spawnSync15 } from "child_process";
 import { createHash as createHash12 } from "crypto";
+import { parse as parseYaml11 } from "yaml";
 
 // src/lib/patchId.ts
 import { spawnSync as spawnSync12 } from "child_process";
@@ -10215,8 +10216,18 @@ function parseEnvelope(bytes) {
     return null;
   }
   if (typeof p.diff_sha256 !== "string") return null;
+  if (typeof p.manifest_snapshot_sha256 !== "string") return null;
   if (!Array.isArray(p.trust_anchor_signatures)) return null;
   if (typeof p.target_branch_tip_sha !== "string") return null;
+  if (p.migration_bootstrap !== void 0) {
+    const m = p.migration_bootstrap;
+    if (!m || typeof m !== "object" || Array.isArray(m)) return null;
+    if (!Array.isArray(m.activated_paths)) return null;
+    if (m.activated_paths.length === 0) return null;
+    for (const ap of m.activated_paths) {
+      if (typeof ap !== "string" || ap.length === 0) return null;
+    }
+  }
   return env;
 }
 function peekSchemaVersion(bytes) {
@@ -10289,154 +10300,572 @@ function readAttestationBlobBytes(patch_id, repoRoot) {
   return cat.stdout;
 }
 
-// src/commands/attest.ts
-function runAttest(opts) {
-  const repoRoot = findRepoRoot();
-  const config2 = loadConfig(stampConfigFile(repoRoot));
-  const rule = findBranchRule(config2.branches, opts.into);
-  if (!rule) {
-    throw new Error(
-      `no branch rule for "${opts.into}" in .stamp/config.yml. Configured branches: ${Object.keys(config2.branches).join(", ") || "(none)"}.`
-    );
-  }
-  const branchRef = opts.branch ?? "HEAD";
-  const revspec = `${opts.into}..${branchRef}`;
-  const resolved = resolveDiff(revspec, repoRoot);
-  const patch_id = patchIdForSpan(resolved.base_sha, resolved.head_sha, repoRoot);
-  const target_branch_tip_sha = runGit(
-    ["rev-parse", `${opts.into}^{commit}`],
-    repoRoot
-  ).trim();
-  const { keypair } = ensureUserKeypair();
-  const result = rule.review_server ? buildV3Envelope({
-    repoRoot,
-    revspec,
-    baseSha: resolved.base_sha,
-    headSha: resolved.head_sha,
-    diff: resolved.diff,
-    targetBranch: opts.into,
-    targetBranchTipSha: target_branch_tip_sha,
-    patchId: patch_id,
-    requiredReviewers: rule.required,
-    operatorPrivateKeyPem: keypair.privateKeyPem,
-    operatorFingerprint: keypair.fingerprint
-  }) : buildV2Envelope({
-    repoRoot,
-    revspec,
-    baseSha: resolved.base_sha,
-    headSha: resolved.head_sha,
-    targetBranch: opts.into,
-    targetBranchTipSha: target_branch_tip_sha,
-    patchId: patch_id,
-    requiredReviewers: rule.required,
-    operatorPrivateKeyPem: keypair.privateKeyPem,
-    operatorFingerprint: keypair.fingerprint
-  });
-  const { ref, blob_sha } = writeAttestationRef(
-    { payload: result.payload, signature: result.signature },
-    repoRoot
-  );
-  const bar = "\u2500".repeat(72);
-  console.log(bar);
-  console.log(`attested ${branchRef} for merge into '${opts.into}'`);
-  console.log(bar);
-  console.log(`  patch-id:   ${patch_id}`);
-  console.log(
-    `  base\u2192head:  ${resolved.base_sha.slice(0, 8)} \u2192 ${resolved.head_sha.slice(0, 8)}`
-  );
-  console.log(`  signed by:  ${keypair.fingerprint}`);
-  console.log(`  approvals:  ${result.reviewerNames.join(", ")}`);
-  console.log(
-    `  schema:     v${result.payload.schema_version}${result.payload.schema_version === PR_ATTESTATION_SCHEMA_VERSION ? " (server-attested)" : " (legacy)"}`
+// src/lib/migrationBootstrap.ts
+import { spawnSync as spawnSync14 } from "child_process";
+import { parse as parseYaml10 } from "yaml";
+function validateShape4ActivationDiff(input) {
+  const { repoRoot, baseSha, headSha } = input;
+  const changedFilesResult = spawnSync14(
+    "git",
+    ["diff", "-z", "--name-status", `${baseSha}...${headSha}`],
+    { cwd: repoRoot, encoding: "utf8" }
   );
-  console.log(`  ref:        ${ref}`);
-  console.log(`  blob:       ${blob_sha.slice(0, 12)}`);
-  console.log(bar);
-  if (opts.pushTo) {
-    pushBranchAndAttestation(opts.pushTo, ref, repoRoot);
-    console.log(
-      `
-\u2713 pushed branch + attestation ref to ${opts.pushTo}. Open the PR; stamp/verify-attestation@v1 will look up refs/stamp/attestations/<patch-id> from your head SHA's diff against the base.`
-    );
-  } else {
-    console.log(
-      `
-Next: push the branch + attestation ref to your remote, open a PR, and let stamp/verify-attestation@v1 (the GH Action) confirm it. To do both pushes in one shot:
-
-    git push <remote> HEAD ${ref}
-
-Or re-run with --push <remote> next time.`
-    );
+  if (changedFilesResult.status !== 0) {
+    return {
+      ok: false,
+      reason: `could not enumerate diff between ${baseSha.slice(0, 8)} and ${headSha.slice(0, 8)}: ${(changedFilesResult.stderr ?? "").trim()}`
+    };
   }
-}
-function buildV3Envelope(input) {
-  const diffBytes = Buffer.from(input.diff, "utf8");
-  const diffSha256 = createHash12("sha256").update(diffBytes).digest("hex");
-  let manifestYaml;
-  try {
-    manifestYaml = showAtRef(
-      input.baseSha,
-      ".stamp/trusted-keys/manifest.yml",
-      input.repoRoot
-    );
-  } catch (err) {
-    throw new Error(
-      `review_server is configured but .stamp/trusted-keys/manifest.yml is missing at base ${input.baseSha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}. Server-attested PR mode requires the manifest in the merge-base tree so each approval's server signature can be checked against the keys the repo trusted at attestation time. Commit a manifest with capabilities: [server] entries for the review server before attesting.`
-    );
+  const tokens = (changedFilesResult.stdout ?? "").split("\0").filter((s) => s.length > 0);
+  const entries = [];
+  for (let i = 0; i < tokens.length; ) {
+    const status = tokens[i];
+    if (/^[RC]\d*$/.test(status)) {
+      return {
+        ok: false,
+        reason: `bootstrap diff contains a rename/copy change (status "${status}") \u2014 only add/modify is permitted in a Shape 4 activation`
+      };
+    }
+    const path2 = tokens[i + 1];
+    if (path2 === void 0) {
+      return {
+        ok: false,
+        reason: `bootstrap diff: malformed git output (status "${status}" with no path)`
+      };
+    }
+    entries.push({ status, path: path2 });
+    i += 2;
   }
-  const manifest = parseManifest(manifestYaml);
-  if (!manifest) {
-    throw new Error(
-      `.stamp/trusted-keys/manifest.yml at base ${input.baseSha.slice(0, 8)} failed to parse as a valid trusted-keys manifest. Fix the YAML (syntax error, duplicate fingerprint, unknown capability, etc.) and re-run \`stamp attest\`.`
-    );
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      reason: "bootstrap diff is empty \u2014 nothing to activate"
+    };
   }
-  const pubFilenames = listFilesAtRef(
-    input.baseSha,
-    ".stamp/trusted-keys",
-    input.repoRoot
-  );
-  const pubkeyByFingerprint = buildPubkeyMap(
-    pubFilenames,
-    (relPath) => showAtRef(input.baseSha, relPath, input.repoRoot)
-  );
-  const db = openDb(stampStateDbPath(input.repoRoot));
-  let entries;
-  try {
-    const rows = serverApprovalsFor(db, input.baseSha, input.headSha);
-    const byReviewer = new Map(rows.map((r) => [r.reviewer, r]));
-    entries = input.requiredReviewers.map((reviewerName) => {
-      const row = byReviewer.get(reviewerName);
-      if (!row) {
-        throw new Error(
-          `missing server signature for reviewer "${reviewerName}" at base\u2192head ${input.baseSha.slice(0, 8)}\u2192${input.headSha.slice(0, 8)}. Server-attested PR mode requires every required reviewer to have a stamp-server-signed approval in the local DB. Possible causes:
-  \u2022 the stamp-server is older than 2.0.1 and doesn't produce PR-attestation v3 payloads (upgrade the server)
-  \u2022 \`stamp review --diff ${input.revspec}\` hasn't been run against this exact (base, head) pair yet
-  \u2022 the review was run in local-mode (no \`review_server\` configured at review time)
-Run \`stamp review --diff ${input.revspec}\` to populate the signed row, then re-run \`stamp attest\`.`
-        );
+  for (const e of entries) {
+    if (!e.path.startsWith(".stamp/")) {
+      return {
+        ok: false,
+        reason: `bootstrap diff touches "${e.path}" outside .stamp/ \u2014 the bootstrap flag accepts only Shape-4-activation changes under .stamp/**. Use the normal flow for non-bootstrap changes.`
+      };
+    }
+  }
+  let sawReviewServerAdd = false;
+  for (const e of entries) {
+    if (e.path === ".stamp/config.yml") {
+      if (e.status !== "M" && e.status !== "A") {
+        return {
+          ok: false,
+          reason: `bootstrap diff has unexpected status "${e.status}" on .stamp/config.yml \u2014 only modification (M) or initial add (A) is permitted`
+        };
       }
-      let parsedJson;
-      try {
-        parsedJson = JSON.parse(row.approval_json);
-      } catch (err) {
-        throw new Error(
-          `server approval row for reviewer "${reviewerName}" has malformed JSON in server_approval_json \u2014 DB corruption or a writer-side bug. Re-run \`stamp review --diff ${input.revspec}\` to write a fresh row. (parse error: ${err instanceof Error ? err.message : String(err)})`
-        );
+      const cfgResult = validateConfigYamlChange({
+        repoRoot,
+        baseSha,
+        headSha,
+        statusAdd: e.status === "A"
+      });
+      if (!cfgResult.ok) return cfgResult;
+      sawReviewServerAdd = sawReviewServerAdd || cfgResult.activatesReviewServer;
+      continue;
+    }
+    if (e.path === ".stamp/trusted-keys/manifest.yml") {
+      if (e.status !== "M" && e.status !== "A") {
+        return {
+          ok: false,
+          reason: `bootstrap diff has unexpected status "${e.status}" on .stamp/trusted-keys/manifest.yml \u2014 only modification (M) or initial add (A) is permitted`
+        };
       }
-      if (!parsedJson || typeof parsedJson !== "object" || Array.isArray(parsedJson)) {
-        throw new Error(
-          `server approval row for reviewer "${reviewerName}" parsed to a non-object value \u2014 DB corruption or a writer-side bug. Re-run \`stamp review --diff ${input.revspec}\` to write a fresh row.`
-        );
+      const manifestResult = validateManifestChange({
+        repoRoot,
+        baseSha,
+        headSha,
+        statusAdd: e.status === "A"
+      });
+      if (!manifestResult.ok) return manifestResult;
+      continue;
+    }
+    if (e.path.startsWith(".stamp/trusted-keys/") && e.path.endsWith(".pub")) {
+      if (e.status !== "A") {
+        return {
+          ok: false,
+          reason: `bootstrap diff modifies or removes "${e.path}" (status "${e.status}") \u2014 the bootstrap flag only permits adding new .pub files, never modifying or removing existing ones`
+        };
       }
-      const obj = parsedJson;
-      for (const field of [
-        "reviewer",
-        "verdict",
-        "prompt_sha256",
-        "diff_sha256",
-        "base_sha",
-        "head_sha",
-        "trusted_keys_snapshot_sha256",
+      continue;
+    }
+    return {
+      ok: false,
+      reason: `bootstrap diff touches "${e.path}" (status "${e.status}") which is not in the Shape-4-activation whitelist (.stamp/config.yml, .stamp/trusted-keys/manifest.yml, or new .stamp/trusted-keys/*.pub files)`
+    };
+  }
+  if (!sawReviewServerAdd) {
+    return {
+      ok: false,
+      reason: `bootstrap diff does not add review_server: to any branch rule in .stamp/config.yml \u2014 a Shape 4 activation must add review_server. If your diff only adds trust-anchor keys, use the normal admin-sign flow.`
+    };
+  }
+  const activatedPaths = entries.map((e) => e.path).sort();
+  return { ok: true, activatedPaths };
+}
+function validateConfigYamlChange(args) {
+  if (args.statusAdd) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml does not exist at base ${args.baseSha.slice(0, 8)} \u2014 the bootstrap flag is for activating Shape 4 on an existing stamp-gated repo, not for first-time stamp init`,
+      activatesReviewServer: false
+    };
+  }
+  const baseYaml = readAtRef(args.repoRoot, args.baseSha, ".stamp/config.yml");
+  const headYaml = readAtRef(args.repoRoot, args.headSha, ".stamp/config.yml");
+  if (baseYaml === null || headYaml === null) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml is unreadable at base ${args.baseSha.slice(0, 8)} or head ${args.headSha.slice(0, 8)}`,
+      activatesReviewServer: false
+    };
+  }
+  let baseParsed;
+  let headParsed;
+  try {
+    baseParsed = parseYaml10(baseYaml);
+    headParsed = parseYaml10(headYaml);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml parse error: ${err instanceof Error ? err.message : String(err)}`,
+      activatesReviewServer: false
+    };
+  }
+  if (!baseParsed || typeof baseParsed !== "object" || Array.isArray(baseParsed) || !headParsed || typeof headParsed !== "object" || Array.isArray(headParsed)) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml at base or head did not parse to an object`,
+      activatesReviewServer: false
+    };
+  }
+  const baseObj = baseParsed;
+  const headObj = headParsed;
+  const allowedDiffKeys = /* @__PURE__ */ new Set(["branches", "reviewers"]);
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(baseObj), ...Object.keys(headObj)]);
+  for (const k of allKeys) {
+    if (allowedDiffKeys.has(k)) continue;
+    if (!deepEqual(baseObj[k], headObj[k])) {
+      return {
+        ok: false,
+        reason: `.stamp/config.yml: bootstrap diff modifies "${k}" outside the allowed (branches, reviewers) set \u2014 refused`,
+        activatesReviewServer: false
+      };
+    }
+  }
+  const baseBranches = baseObj.branches ?? {};
+  const headBranches = headObj.branches ?? {};
+  if (typeof baseBranches !== "object" || baseBranches === null || Array.isArray(baseBranches) || typeof headBranches !== "object" || headBranches === null || Array.isArray(headBranches)) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml: branches must be objects at both base and head`,
+      activatesReviewServer: false
+    };
+  }
+  const baseBranchKeys = Object.keys(baseBranches);
+  const headBranchKeys = Object.keys(headBranches);
+  if (baseBranchKeys.length !== headBranchKeys.length || !baseBranchKeys.every((k) => headBranchKeys.includes(k))) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml: bootstrap diff adds or removes branch entries (base: [${baseBranchKeys.join(", ")}], head: [${headBranchKeys.join(", ")}]) \u2014 only review_server addition on existing branches is permitted`,
+      activatesReviewServer: false
+    };
+  }
+  let anyBranchActivatesReviewServer = false;
+  for (const name of baseBranchKeys) {
+    const baseRule = baseBranches[name];
+    const headRule = headBranches[name];
+    if (!baseRule || !headRule) {
+      return {
+        ok: false,
+        reason: `.stamp/config.yml: branch "${name}" is missing at base or head`,
+        activatesReviewServer: false
+      };
+    }
+    if (Array.isArray(baseRule) || Array.isArray(headRule)) {
+      return {
+        ok: false,
+        reason: `.stamp/config.yml: branch "${name}" must be an object`,
+        activatesReviewServer: false
+      };
+    }
+    const baseKeys = Object.keys(baseRule);
+    const headKeys = Object.keys(headRule);
+    for (const k of baseKeys) {
+      if (!(k in headRule)) {
+        return {
+          ok: false,
+          reason: `.stamp/config.yml: branch "${name}" removes field "${k}" \u2014 bootstrap diff cannot remove branch-rule fields`,
+          activatesReviewServer: false
+        };
+      }
+      if (!deepEqual(baseRule[k], headRule[k])) {
+        return {
+          ok: false,
+          reason: `.stamp/config.yml: branch "${name}" modifies field "${k}" \u2014 bootstrap diff can only ADD review_server, not modify existing fields`,
+          activatesReviewServer: false
+        };
+      }
+    }
+    for (const k of headKeys) {
+      if (k in baseRule) continue;
+      if (k !== "review_server") {
+        return {
+          ok: false,
+          reason: `.stamp/config.yml: branch "${name}" adds field "${k}" \u2014 bootstrap diff can only add "review_server"`,
+          activatesReviewServer: false
+        };
+      }
+      if (typeof headRule.review_server !== "string" || !headRule.review_server) {
+        return {
+          ok: false,
+          reason: `.stamp/config.yml: branch "${name}".review_server must be a non-empty string`,
+          activatesReviewServer: false
+        };
+      }
+      anyBranchActivatesReviewServer = true;
+    }
+  }
+  const baseReviewers = baseObj.reviewers ?? {};
+  const headReviewers = headObj.reviewers ?? {};
+  if (typeof baseReviewers !== "object" || baseReviewers === null || Array.isArray(baseReviewers) || typeof headReviewers !== "object" || headReviewers === null || Array.isArray(headReviewers)) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml: reviewers must be objects at both base and head`,
+      activatesReviewServer: false
+    };
+  }
+  const baseRevKeys = Object.keys(baseReviewers).sort();
+  const headRevKeys = Object.keys(headReviewers).sort();
+  if (baseRevKeys.length !== headRevKeys.length || !baseRevKeys.every((k, i) => k === headRevKeys[i])) {
+    return {
+      ok: false,
+      reason: `.stamp/config.yml: bootstrap diff adds or removes reviewer entries (base: [${baseRevKeys.join(", ")}], head: [${headRevKeys.join(", ")}]) \u2014 Shape 4 activation may only cleanup prompt paths, not add or remove reviewers`,
+      activatesReviewServer: false
+    };
+  }
+  for (const name of baseRevKeys) {
+    const baseRev = baseReviewers[name];
+    const headRev = headReviewers[name];
+    if (deepEqual(baseRev, headRev)) continue;
+    if (headRev !== null && typeof headRev === "object" && !Array.isArray(headRev) && Object.keys(headRev).length === 0) {
+      continue;
+    }
+    return {
+      ok: false,
+      reason: `.stamp/config.yml: reviewer "${name}" modified outside the Shape-4 cleanup pattern (HEAD must equal BASE or be {}); refused`,
+      activatesReviewServer: false
+    };
+  }
+  return { ok: true, activatedPaths: [], activatesReviewServer: anyBranchActivatesReviewServer };
+}
+function validateManifestChange(args) {
+  const headYaml = readAtRef(args.repoRoot, args.headSha, ".stamp/trusted-keys/manifest.yml");
+  if (headYaml === null) {
+    return {
+      ok: false,
+      reason: `.stamp/trusted-keys/manifest.yml unreadable at head ${args.headSha.slice(0, 8)}`
+    };
+  }
+  let headParsed;
+  try {
+    headParsed = parseYaml10(headYaml);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `.stamp/trusted-keys/manifest.yml parse error at head: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  if (!headParsed || typeof headParsed !== "object" || Array.isArray(headParsed) || !headParsed.keys || typeof headParsed.keys !== "object") {
+    return {
+      ok: false,
+      reason: `.stamp/trusted-keys/manifest.yml: missing or malformed top-level "keys" map at head`
+    };
+  }
+  const headKeys = headParsed.keys;
+  let baseKeys = {};
+  if (!args.statusAdd) {
+    const baseYaml = readAtRef(args.repoRoot, args.baseSha, ".stamp/trusted-keys/manifest.yml");
+    if (baseYaml === null) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml unreadable at base ${args.baseSha.slice(0, 8)}`
+      };
+    }
+    let baseParsed;
+    try {
+      baseParsed = parseYaml10(baseYaml);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml parse error at base: ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+    if (!baseParsed || typeof baseParsed !== "object" || Array.isArray(baseParsed) || !baseParsed.keys || typeof baseParsed.keys !== "object") {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: missing or malformed top-level "keys" map at base`
+      };
+    }
+    baseKeys = baseParsed.keys;
+  }
+  for (const name of Object.keys(baseKeys)) {
+    if (!(name in headKeys)) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: bootstrap diff removes entry "${name}" \u2014 refused (only additions of [server]+role_source:server entries are permitted)`
+      };
+    }
+    if (!deepEqual(baseKeys[name], headKeys[name])) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: bootstrap diff modifies existing entry "${name}" \u2014 refused (only additions are permitted)`
+      };
+    }
+  }
+  for (const name of Object.keys(headKeys)) {
+    if (name in baseKeys) continue;
+    const entry = headKeys[name];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: new entry "${name}" is not a YAML object`
+      };
+    }
+    const e = entry;
+    if (!Array.isArray(e.capabilities)) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: new entry "${name}" missing capabilities array`
+      };
+    }
+    const caps = e.capabilities.filter((c) => typeof c === "string");
+    if (caps.length !== 1 || caps[0] !== "server") {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: new entry "${name}" has capabilities [${caps.join(", ")}] \u2014 bootstrap diff only permits adding entries with capabilities: [server] exactly`
+      };
+    }
+    if (e.role_source !== "server") {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: new entry "${name}" must have role_source: server (got ${JSON.stringify(e.role_source)}). This invariant flags entries auto-published by stamp-server.`
+      };
+    }
+    if (typeof e.fingerprint !== "string" || !/^sha256:[0-9a-f]{64}$/.test(e.fingerprint)) {
+      return {
+        ok: false,
+        reason: `.stamp/trusted-keys/manifest.yml: new entry "${name}" has invalid fingerprint`
+      };
+    }
+  }
+  return { ok: true, activatedPaths: [] };
+}
+var MIGRATION_BOOTSTRAP_KEY = "migration_bootstrap";
+function bootstrapAdminSigningBytes(args) {
+  const augmented = {
+    ...args.payloadV4,
+    [MIGRATION_BOOTSTRAP_KEY]: args.marker,
+    trust_anchor_signatures: []
+  };
+  return canonicalSerializePayload(augmented);
+}
+function readAtRef(repoRoot, ref, relPath) {
+  const result = spawnSync14("git", ["show", `${ref}:${relPath}`], {
+    cwd: repoRoot,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) return null;
+  return result.stdout ?? "";
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const ao = a;
+  const bo = b;
+  const aKeys = Object.keys(ao).sort();
+  const bKeys = Object.keys(bo).sort();
+  if (aKeys.length !== bKeys.length) return false;
+  for (let i = 0; i < aKeys.length; i++) {
+    if (aKeys[i] !== bKeys[i]) return false;
+    if (!deepEqual(ao[aKeys[i]], bo[bKeys[i]])) return false;
+  }
+  return true;
+}
+
+// src/commands/attest.ts
+function runAttest(opts) {
+  const repoRoot = findRepoRoot();
+  const config2 = loadConfig(stampConfigFile(repoRoot));
+  const rule = findBranchRule(config2.branches, opts.into);
+  if (!rule) {
+    throw new Error(
+      `no branch rule for "${opts.into}" in .stamp/config.yml. Configured branches: ${Object.keys(config2.branches).join(", ") || "(none)"}.`
+    );
+  }
+  const branchRef = opts.branch ?? "HEAD";
+  const revspec = `${opts.into}..${branchRef}`;
+  const resolved = resolveDiff(revspec, repoRoot);
+  const patch_id = patchIdForSpan(resolved.base_sha, resolved.head_sha, repoRoot);
+  const target_branch_tip_sha = runGit(
+    ["rev-parse", `${opts.into}^{commit}`],
+    repoRoot
+  ).trim();
+  const { keypair } = ensureUserKeypair();
+  const result = opts.migrateExisting ? buildBootstrapEnvelope({
+    repoRoot,
+    revspec,
+    baseSha: resolved.base_sha,
+    headSha: resolved.head_sha,
+    diff: resolved.diff,
+    targetBranch: opts.into,
+    targetBranchTipSha: target_branch_tip_sha,
+    patchId: patch_id,
+    operatorPrivateKeyPem: keypair.privateKeyPem,
+    operatorPublicKeyPem: keypair.publicKeyPem,
+    operatorFingerprint: keypair.fingerprint
+  }) : rule.review_server ? buildV3Envelope({
+    repoRoot,
+    revspec,
+    baseSha: resolved.base_sha,
+    headSha: resolved.head_sha,
+    diff: resolved.diff,
+    targetBranch: opts.into,
+    targetBranchTipSha: target_branch_tip_sha,
+    patchId: patch_id,
+    requiredReviewers: rule.required,
+    operatorPrivateKeyPem: keypair.privateKeyPem,
+    operatorFingerprint: keypair.fingerprint
+  }) : buildV2Envelope({
+    repoRoot,
+    revspec,
+    baseSha: resolved.base_sha,
+    headSha: resolved.head_sha,
+    targetBranch: opts.into,
+    targetBranchTipSha: target_branch_tip_sha,
+    patchId: patch_id,
+    requiredReviewers: rule.required,
+    operatorPrivateKeyPem: keypair.privateKeyPem,
+    operatorFingerprint: keypair.fingerprint
+  });
+  const { ref, blob_sha } = writeAttestationRef(
+    { payload: result.payload, signature: result.signature },
+    repoRoot
+  );
+  const bar = "\u2500".repeat(72);
+  console.log(bar);
+  console.log(`attested ${branchRef} for merge into '${opts.into}'`);
+  console.log(bar);
+  console.log(`  patch-id:   ${patch_id}`);
+  console.log(
+    `  base\u2192head:  ${resolved.base_sha.slice(0, 8)} \u2192 ${resolved.head_sha.slice(0, 8)}`
+  );
+  console.log(`  signed by:  ${keypair.fingerprint}`);
+  console.log(`  approvals:  ${result.reviewerNames.length > 0 ? result.reviewerNames.join(", ") : "(none \u2014 bootstrap envelope)"}`);
+  const schemaLabel = result.payload.migration_bootstrap ? " (Shape 4 migration bootstrap)" : result.payload.schema_version === PR_ATTESTATION_SCHEMA_VERSION ? " (server-attested)" : " (legacy)";
+  console.log(`  schema:     v${result.payload.schema_version}${schemaLabel}`);
+  console.log(`  ref:        ${ref}`);
+  console.log(`  blob:       ${blob_sha.slice(0, 12)}`);
+  console.log(bar);
+  if (opts.pushTo) {
+    pushBranchAndAttestation(opts.pushTo, ref, repoRoot);
+    console.log(
+      `
+\u2713 pushed branch + attestation ref to ${opts.pushTo}. Open the PR; stamp/verify-attestation@v1 will look up refs/stamp/attestations/<patch-id> from your head SHA's diff against the base.`
+    );
+  } else {
+    console.log(
+      `
+Next: push the branch + attestation ref to your remote, open a PR, and let stamp/verify-attestation@v1 (the GH Action) confirm it. To do both pushes in one shot:
+
+    git push <remote> HEAD ${ref}
+
+Or re-run with --push <remote> next time.`
+    );
+  }
+}
+function buildV3Envelope(input) {
+  const diffBytes = Buffer.from(input.diff, "utf8");
+  const diffSha256 = createHash12("sha256").update(diffBytes).digest("hex");
+  let manifestYaml;
+  try {
+    manifestYaml = showAtRef(
+      input.baseSha,
+      ".stamp/trusted-keys/manifest.yml",
+      input.repoRoot
+    );
+  } catch (err) {
+    throw new Error(
+      `review_server is configured but .stamp/trusted-keys/manifest.yml is missing at base ${input.baseSha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}. Server-attested PR mode requires the manifest in the merge-base tree so each approval's server signature can be checked against the keys the repo trusted at attestation time. Commit a manifest with capabilities: [server] entries for the review server before attesting.`
+    );
+  }
+  const manifest = parseManifest(manifestYaml);
+  if (!manifest) {
+    throw new Error(
+      `.stamp/trusted-keys/manifest.yml at base ${input.baseSha.slice(0, 8)} failed to parse as a valid trusted-keys manifest. Fix the YAML (syntax error, duplicate fingerprint, unknown capability, etc.) and re-run \`stamp attest\`.`
+    );
+  }
+  const pubFilenames = listFilesAtRef(
+    input.baseSha,
+    ".stamp/trusted-keys",
+    input.repoRoot
+  );
+  const pubkeyByFingerprint = buildPubkeyMap(
+    pubFilenames,
+    (relPath) => showAtRef(input.baseSha, relPath, input.repoRoot)
+  );
+  const db = openDb(stampStateDbPath(input.repoRoot));
+  let entries;
+  try {
+    const rows = serverApprovalsFor(db, input.baseSha, input.headSha);
+    const byReviewer = new Map(rows.map((r) => [r.reviewer, r]));
+    entries = input.requiredReviewers.map((reviewerName) => {
+      const row = byReviewer.get(reviewerName);
+      if (!row) {
+        throw new Error(
+          `missing server signature for reviewer "${reviewerName}" at base\u2192head ${input.baseSha.slice(0, 8)}\u2192${input.headSha.slice(0, 8)}. Server-attested PR mode requires every required reviewer to have a stamp-server-signed approval in the local DB. Possible causes:
+  \u2022 the stamp-server is older than 2.0.1 and doesn't produce PR-attestation v3 payloads (upgrade the server)
+  \u2022 \`stamp review --diff ${input.revspec}\` hasn't been run against this exact (base, head) pair yet
+  \u2022 the review was run in local-mode (no \`review_server\` configured at review time)
+Run \`stamp review --diff ${input.revspec}\` to populate the signed row, then re-run \`stamp attest\`.`
+        );
+      }
+      let parsedJson;
+      try {
+        parsedJson = JSON.parse(row.approval_json);
+      } catch (err) {
+        throw new Error(
+          `server approval row for reviewer "${reviewerName}" has malformed JSON in server_approval_json \u2014 DB corruption or a writer-side bug. Re-run \`stamp review --diff ${input.revspec}\` to write a fresh row. (parse error: ${err instanceof Error ? err.message : String(err)})`
+        );
+      }
+      if (!parsedJson || typeof parsedJson !== "object" || Array.isArray(parsedJson)) {
+        throw new Error(
+          `server approval row for reviewer "${reviewerName}" parsed to a non-object value \u2014 DB corruption or a writer-side bug. Re-run \`stamp review --diff ${input.revspec}\` to write a fresh row.`
+        );
+      }
+      const obj = parsedJson;
+      for (const field of [
+        "reviewer",
+        "verdict",
+        "prompt_sha256",
+        "diff_sha256",
+        "base_sha",
+        "head_sha",
         "issued_at",
         "server_key_id"
       ]) {
@@ -10511,6 +10940,7 @@ Run \`stamp review --diff ${input.revspec}\` to populate the signed row, then re
     db.close();
   }
   const trustAnchorSignatures = [];
+  const manifestSnapshot = snapshotSha256(manifest);
   const payload = {
     schema_version: PR_ATTESTATION_SCHEMA_VERSION,
     patch_id: input.patchId,
@@ -10519,6 +10949,7 @@ Run \`stamp review --diff ${input.revspec}\` to populate the signed row, then re
     target_branch: input.targetBranch,
     target_branch_tip_sha: input.targetBranchTipSha,
     diff_sha256: diffSha256,
+    manifest_snapshot_sha256: manifestSnapshot,
     approvals: entries,
     checks: [],
     // Phase-1 deliberate omission — see file-level comment.
@@ -10579,6 +11010,11 @@ function buildV2Envelope(input) {
         `reviewer "${a.reviewer}" approved the diff but is not defined in .stamp/config.yml at base ${input.baseSha.slice(0, 8)}. This shouldn't happen \u2014 runReview reads from the same base. File a bug at https://github.com/OpenThinkAi/stamp-cli/issues.`
       );
     }
+    if (def.prompt === void 0) {
+      throw new Error(
+        `reviewer "${a.reviewer}": no \`prompt:\` configured and no \`review_server:\` on branch rule \u2014 set \`reviewers.${a.reviewer}.prompt\` in .stamp/config.yml or configure a \`review_server:\` for server-attested PR mode.`
+      );
+    }
     const promptText = showAtRef(input.baseSha, def.prompt, input.repoRoot);
     const source = readReviewerSource2(a.reviewer, input.repoRoot);
     return {
@@ -10611,8 +11047,187 @@ function buildV2Envelope(input) {
     reviewerNames: approvals.map((a) => a.reviewer)
   };
 }
+function buildBootstrapEnvelope(input) {
+  const validation = validateShape4ActivationDiff({
+    repoRoot: input.repoRoot,
+    baseSha: input.baseSha,
+    headSha: input.headSha
+  });
+  if (!validation.ok) {
+    throw new Error(
+      `--migrate-existing refused: ${validation.reason}
+
+The bootstrap flag accepts ONLY a narrow Shape 4 activation diff: adding \`review_server:\` to a branch rule in .stamp/config.yml, adding new [server]+role_source:server entries to .stamp/trusted-keys/manifest.yml, and adding the corresponding new .pub files. Land any unrelated changes through the normal \`stamp attest\` flow AFTER the bootstrap PR merges.`
+    );
+  }
+  const activatedPaths = validation.activatedPaths;
+  const baseConfigYaml = readAtBaseSha(
+    input.repoRoot,
+    input.baseSha,
+    ".stamp/config.yml"
+  );
+  if (baseConfigYaml === null) {
+    throw new Error(
+      `--migrate-existing refused: .stamp/config.yml is missing at base ${input.baseSha.slice(0, 8)}. Bootstrap requires the config file in the merge-base tree (the activation diff modifies it).`
+    );
+  }
+  const baseRules = extractPathRulesFromYaml(baseConfigYaml);
+  if (baseRules.length === 0) {
+    throw new Error(
+      `--migrate-existing refused: no \`path_rules\` configured at base ${input.baseSha.slice(0, 8)}. The bootstrap path needs a path_rules entry covering the activated paths with \`bypass_review_cycle: true\` so the verifier knows the reviewer cycle is intentionally skipped for this PR. Add a \`path_rules\` entry for \`.stamp/**\` in a separate prior PR before bootstrapping.`
+    );
+  }
+  const matchedRule = matchAnyCoveringRule(activatedPaths, baseRules);
+  if (!matchedRule) {
+    throw new Error(
+      `--migrate-existing refused: \`path_rules\` at base ${input.baseSha.slice(0, 8)} does not cover every activated path. Activated: ${activatedPaths.join(", ")}. Configured patterns: ${baseRules.map((r) => `"${r.pattern}"`).join(", ")}. Add or widen a path_rules entry that matches these paths (in a separate prior PR \u2014 the bootstrap diff cannot modify path_rules).`
+    );
+  }
+  if (!matchedRule.bypass_review_cycle) {
+    throw new Error(
+      `--migrate-existing refused: matched path_rule "${matchedRule.pattern}" at base has \`bypass_review_cycle: false\` \u2014 bootstrap requires the rule to \`bypass_review_cycle: true\` (otherwise the reviewer cycle is still nominally required and the bootstrap envelope is structurally invalid).`
+    );
+  }
+  if (matchedRule.minimum_signatures > 1) {
+    throw new Error(
+      `--migrate-existing refused: matched path_rule "${matchedRule.pattern}" at base requires \`minimum_signatures: ${matchedRule.minimum_signatures}\` admin signatures, but the bootstrap path only collects a single operator-self admin signature today. Options: (a) temporarily lower the rule to \`minimum_signatures: 1\` in a prior PR; (b) for the migration commit only, use the standard \`stamp admin sign\` flow against the eventual landed commit.`
+    );
+  }
+  const workingTreeManifestYaml = readWorkingTreeManifestYaml(input.repoRoot);
+  if (workingTreeManifestYaml === null) {
+    throw new Error(
+      `--migrate-existing refused: .stamp/trusted-keys/manifest.yml is missing from the working tree. Bootstrap requires the working-tree manifest to bind the operator's local stamp key to the \`admin\` capability.`
+    );
+  }
+  const workingTreeManifest = parseManifest(workingTreeManifestYaml);
+  if (!workingTreeManifest) {
+    throw new Error(
+      `--migrate-existing refused: .stamp/trusted-keys/manifest.yml in the working tree failed to parse (bad YAML, duplicate fingerprint, unknown capability, etc.).`
+    );
+  }
+  const operatorCaps = resolveCapability(workingTreeManifest, input.operatorFingerprint);
+  if (operatorCaps === null) {
+    throw new Error(
+      `--migrate-existing refused: your local stamp key (${input.operatorFingerprint}) is not listed in the working-tree .stamp/trusted-keys/manifest.yml. Add your key with \`capabilities: [admin]\` (in a separate prior PR) before bootstrapping the Shape 4 migration.`
+    );
+  }
+  if (!operatorCaps.includes("admin")) {
+    throw new Error(
+      `--migrate-existing refused: your local stamp key (${input.operatorFingerprint}) has capabilities [${operatorCaps.join(", ")}] in the working-tree manifest \u2014 needs \`admin\` for bootstrap. Either grant your key admin capability (in a separate prior PR) or have a different admin run \`stamp attest --migrate-existing\`.`
+    );
+  }
+  const baseManifestYaml = readAtBaseSha(
+    input.repoRoot,
+    input.baseSha,
+    ".stamp/trusted-keys/manifest.yml"
+  );
+  if (baseManifestYaml === null) {
+    throw new Error(
+      `--migrate-existing refused: .stamp/trusted-keys/manifest.yml is missing at base ${input.baseSha.slice(0, 8)}. Bootstrap requires the manifest in the merge-base tree (the operator's outer signature commits to its snapshot hash). Run \`stamp init --migrate-to-server-attested\` first to seed the manifest.`
+    );
+  }
+  const baseManifest = parseManifest(baseManifestYaml);
+  if (!baseManifest) {
+    throw new Error(
+      `--migrate-existing refused: .stamp/trusted-keys/manifest.yml at base ${input.baseSha.slice(0, 8)} failed to parse.`
+    );
+  }
+  const manifestSnapshot = snapshotSha256(baseManifest);
+  const diffBytes = Buffer.from(input.diff, "utf8");
+  const diffSha256 = createHash12("sha256").update(diffBytes).digest("hex");
+  const marker = {
+    activated_paths: activatedPaths
+  };
+  const payloadV4Shape = {
+    schema_version: PR_ATTESTATION_SCHEMA_VERSION,
+    base_sha: input.baseSha,
+    head_sha: input.headSha,
+    target_branch: input.targetBranch,
+    diff_sha256: diffSha256,
+    manifest_snapshot_sha256: manifestSnapshot,
+    approvals: [],
+    // bootstrap: no server signatures
+    checks: [],
+    trust_anchor_signatures: [],
+    signer_key_id: input.operatorFingerprint
+  };
+  const adminSigningBytes = bootstrapAdminSigningBytes({
+    payloadV4: payloadV4Shape,
+    marker
+  });
+  const adminSignatureB64 = signBytes(input.operatorPrivateKeyPem, adminSigningBytes);
+  const selfOk = verifyBytes(
+    input.operatorPublicKeyPem,
+    adminSigningBytes,
+    adminSignatureB64
+  );
+  if (!selfOk) {
+    throw new Error(
+      `internal error: just-produced bootstrap admin signature failed self-verification. Refusing to write a bad envelope. File a bug at https://github.com/OpenThinkAi/stamp-cli/issues.`
+    );
+  }
+  const trustAnchorSignatures = [
+    {
+      signer_key_id: input.operatorFingerprint,
+      signature: adminSignatureB64
+    }
+  ];
+  const payload = {
+    schema_version: PR_ATTESTATION_SCHEMA_VERSION,
+    patch_id: input.patchId,
+    base_sha: input.baseSha,
+    head_sha: input.headSha,
+    target_branch: input.targetBranch,
+    target_branch_tip_sha: input.targetBranchTipSha,
+    diff_sha256: diffSha256,
+    manifest_snapshot_sha256: manifestSnapshot,
+    approvals: [],
+    checks: [],
+    trust_anchor_signatures: trustAnchorSignatures,
+    signer_key_id: input.operatorFingerprint,
+    migration_bootstrap: marker
+  };
+  const signature = signBytes(input.operatorPrivateKeyPem, serializePayload2(payload));
+  return {
+    payload,
+    signature,
+    reviewerNames: []
+  };
+}
+function readWorkingTreeManifestYaml(repoRoot) {
+  try {
+    return showAtRef("HEAD", ".stamp/trusted-keys/manifest.yml", repoRoot);
+  } catch {
+    return null;
+  }
+}
+function readAtBaseSha(repoRoot, baseSha, relPath) {
+  try {
+    return showAtRef(baseSha, relPath, repoRoot);
+  } catch {
+    return null;
+  }
+}
+function extractPathRulesFromYaml(yamlText) {
+  let parsed;
+  try {
+    parsed = parseYaml11(yamlText);
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object") return [];
+  const { rules } = parsePathRules(parsed.path_rules);
+  return rules;
+}
+function matchAnyCoveringRule(activatedPaths, rules) {
+  for (const rule of rules) {
+    const allMatch = activatedPaths.every((p) => pathMatchesAny(p, [rule.pattern]));
+    if (allMatch) return rule;
+  }
+  return null;
+}
 function pushBranchAndAttestation(remote, attestationRef, repoRoot) {
-  const result = spawnSync14(
+  const result = spawnSync15(
     "git",
     ["push", "--atomic", remote, "HEAD", attestationRef],
     { cwd: repoRoot, stdio: "inherit" }
@@ -10907,7 +11522,7 @@ function loadOrEmpty() {
 }
 
 // src/commands/reviewers.ts
-import { spawnSync as spawnSync15 } from "child_process";
+import { spawnSync as spawnSync16 } from "child_process";
 import {
   existsSync as existsSync21,
   readFileSync as readFileSync18,
@@ -10916,7 +11531,7 @@ import {
   writeFileSync as writeFileSync15
 } from "fs";
 import { join as join16, relative as relative3, resolve as resolve2 } from "path";
-import { parse as parseYaml10, stringify as stringifyYaml3 } from "yaml";
+import { parse as parseYaml12, stringify as stringifyYaml3 } from "yaml";
 
 // src/lib/reviewerLock.ts
 import { existsSync as existsSync20, readFileSync as readFileSync17, writeFileSync as writeFileSync14 } from "fs";
@@ -10951,6 +11566,11 @@ function checkReviewerDrift(repoRoot, reviewerName, def) {
   if (!lock) {
     return unpinnedResult();
   }
+  if (def.prompt === void 0) {
+    throw new Error(
+      `reviewer "${reviewerName}" has a lock file but no \`prompt:\` configured (server-bundled in Shape 4). Lock files pin local prompt bytes and don't apply in server-attested mode. Delete .stamp/reviewers/${reviewerName}.lock.json to un-pin, or set \`reviewers.${reviewerName}.prompt\` in .stamp/config.yml if you intend to author the prompt locally.`
+    );
+  }
   const promptPath = join15(repoRoot, def.prompt);
   if (!existsSync20(promptPath)) {
     throw new Error(
@@ -11036,6 +11656,10 @@ function reviewersList() {
   const maxNameLen = Math.max(...names.map((n) => n.length));
   for (const name of names) {
     const def = config2.reviewers[name];
+    if (def.prompt === void 0) {
+      console.log(`  ${name.padEnd(maxNameLen)}   (server-bundled \u2014 no local prompt)`);
+      continue;
+    }
     const abs = resolve2(repoRoot, def.prompt);
     let annotation = "";
     if (!existsSync21(abs)) {
@@ -11062,6 +11686,11 @@ function reviewersEdit(name) {
       `reviewer "${name}" is not configured. Run \`stamp reviewers list\` to see available reviewers.`
     );
   }
+  if (def.prompt === void 0) {
+    throw new Error(
+      `reviewer "${name}" has no \`prompt:\` configured (server-bundled in Shape 4). There is no local prompt file to edit. To author the prompt locally, set \`reviewers.${name}.prompt\` to a path under .stamp/reviewers/ in .stamp/config.yml.`
+    );
+  }
   const target = resolve2(repoRoot, def.prompt);
   launchEditor(target);
 }
@@ -11126,6 +11755,10 @@ function reviewersRemove(name, opts = {}) {
   delete config2.reviewers[name];
   writeFileSync15(configPath, stringifyConfig(config2));
   console.log(`reviewer "${name}" removed from .stamp/config.yml`);
+  if (def.prompt === void 0) {
+    console.log(`(no local prompt file \u2014 reviewer was server-bundled)`);
+    return;
+  }
   if (opts.deleteFile) {
     const promptAbs = resolve2(repoRoot, def.prompt);
     if (existsSync21(promptAbs)) {
@@ -11159,6 +11792,11 @@ async function reviewersTest(name, diff) {
   console.log(`  prompt sourced from working tree (test/iteration use case)`);
   console.log();
   const def = config2.reviewers[name];
+  if (def.prompt === void 0) {
+    throw new Error(
+      `reviewer "${name}" has no \`prompt:\` configured (server-bundled in Shape 4). \`stamp reviewers test\` is a local prompt-iteration helper and needs a local prompt file to invoke. Set \`reviewers.${name}.prompt\` in .stamp/config.yml to a path under .stamp/reviewers/ to use this command.`
+    );
+  }
   const promptPath = join16(repoRoot, def.prompt);
   const systemPrompt = readFileSync18(promptPath, "utf8");
   const result = await invokeReviewer({
@@ -11203,7 +11841,9 @@ function reviewersShow(name, opts) {
   const bar = "\u2500".repeat(72);
   console.log(bar);
   console.log(`reviewer: ${name}`);
-  console.log(`prompt:   ${config2.reviewers[name].prompt}`);
+  console.log(
+    `prompt:   ${config2.reviewers[name].prompt ?? "(server-bundled \u2014 no local prompt)"}`
+  );
   console.log(bar);
   if (stats.total === 0) {
     console.log("  no verdicts recorded yet");
@@ -11290,7 +11930,7 @@ async function reviewersFetch(reviewerName, opts) {
   let tools;
   let mcpServers;
   if (configYaml !== null) {
-    const parsed = parseYaml10(configYaml) ?? {};
+    const parsed = parseYaml12(configYaml) ?? {};
     if (Array.isArray(parsed.tools)) {
       tools = parseToolsLoose(parsed.tools);
     }
@@ -11551,7 +12191,7 @@ function buildConfigYamlHint(reviewerName, tools, mcpServers) {
 }
 function launchEditor(path2) {
   const editor = process.env["EDITOR"] ?? process.env["VISUAL"] ?? (process.platform === "win32" ? "notepad" : "vi");
-  const result = spawnSync15(editor, [path2], { stdio: "inherit" });
+  const result = spawnSync16(editor, [path2], { stdio: "inherit" });
   if (result.error) {
     throw new Error(
       `failed to launch editor "${editor}": ${result.error.message}`
@@ -11635,7 +12275,7 @@ function printGate(result, base_sha, head_sha) {
 }
 
 // src/commands/update.ts
-import { spawnSync as spawnSync16 } from "child_process";
+import { spawnSync as spawnSync17 } from "child_process";
 var PKG_NAME = "@openthink/stamp";
 function compareSemver(a, b) {
   const parse2 = (v) => (v.split("-")[0] ?? "0.0.0").split(".").map((n) => parseInt(n, 10) || 0);
@@ -11654,7 +12294,7 @@ function runUpdate() {
 `);
   process.stdout.write(`checking npm registry for latest...
 `);
-  const viewResult = spawnSync16("npm", ["view", PKG_NAME, "version"], {
+  const viewResult = spawnSync17("npm", ["view", PKG_NAME, "version"], {
     encoding: "utf8"
   });
   if (viewResult.error || viewResult.status !== 0) {
@@ -11688,7 +12328,7 @@ function runUpdate() {
   }
   process.stdout.write(`installing ${PKG_NAME}@${latest}...
 `);
-  const installResult = spawnSync16(
+  const installResult = spawnSync17(
     "npm",
     ["install", "-g", `${PKG_NAME}@${latest}`],
     { stdio: "inherit" }
@@ -11709,9 +12349,9 @@ through that tool instead \u2014 this command only uses 'npm install -g'.`
 }
 
 // src/commands/verify.ts
-import { execFileSync as execFileSync7, spawnSync as spawnSync17 } from "child_process";
+import { execFileSync as execFileSync7, spawnSync as spawnSync18 } from "child_process";
 function loadConfigAtSha(sha, repoRoot) {
-  const result = spawnSync17(
+  const result = spawnSync18(
     "git",
     ["show", `${sha}:.stamp/config.yml`],
     { cwd: repoRoot, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }
@@ -11849,6 +12489,12 @@ function verifyReviewerHashes(sha, payload, repoRoot, config2) {
         `v2 attestation: reviewer "${approval.reviewer}" is in payload but not defined in config.reviewers at the merge commit`
       );
     }
+    if (def.prompt === void 0) {
+      fail(
+        sha,
+        `v2 attestation: reviewer "${approval.reviewer}" has no \`prompt:\` in .stamp/config.yml at the merge commit. v2 attestations cite prompt_sha256 over the on-tree prompt file, but the producer flow for server-bundled prompts is v4 (server-attested) \u2014 the envelope and config shape are inconsistent.`
+      );
+    }
     const promptBytes = tryGitShow(`${sha}:${def.prompt}`, repoRoot);
     if (promptBytes === null) {
       fail(
@@ -11922,8 +12568,9 @@ function git2(args, cwd) {
 }
 
 // src/commands/verifyPr.ts
-import { spawnSync as spawnSync18 } from "child_process";
-import { parse as parseYaml11 } from "yaml";
+import { spawnSync as spawnSync19 } from "child_process";
+import { createHash as createHash13 } from "crypto";
+import { parse as parseYaml13 } from "yaml";
 function runVerifyPr(opts) {
   const repoRoot = opts.repoPath ?? findRepoRoot();
   const resolved = resolveDiff(`${opts.base}..${opts.head}`, repoRoot);
@@ -11964,6 +12611,10 @@ function runVerifyPr(opts) {
     );
   }
   if (envelope.payload.schema_version >= MIN_ACCEPTED_PR_ATTESTATION_VERSION) {
+    if (envelope.payload.migration_bootstrap !== void 0) {
+      verifyBootstrapEnvelope(envelope, opts, resolved, patch_id, repoRoot);
+      return;
+    }
     verifyV3Envelope(envelope, opts, resolved, patch_id, repoRoot);
     return;
   }
@@ -11981,6 +12632,7 @@ function verifyV3Envelope(envelope, opts, resolved, patch_id, repoRoot) {
     head_sha: envelope.payload.head_sha,
     target_branch: envelope.payload.target_branch,
     diff_sha256: envelope.payload.diff_sha256,
+    manifest_snapshot_sha256: envelope.payload.manifest_snapshot_sha256,
     approvals: envelope.payload.approvals,
     checks: envelope.payload.checks,
     trust_anchor_signatures: envelope.payload.trust_anchor_signatures,
@@ -12091,6 +12743,310 @@ function verifyV3Envelope(envelope, opts, resolved, patch_id, repoRoot) {
     schema_version: envelope.payload.schema_version
   });
 }
+function verifyBootstrapEnvelope(envelope, opts, resolved, patch_id, repoRoot) {
+  const payload = envelope.payload;
+  const marker = payload.migration_bootstrap;
+  if (!marker) {
+    fail2(
+      `internal error: bootstrap dispatch with no marker (should be unreachable)`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (payload.approvals.length !== 0) {
+    fail2(
+      `bootstrap envelope has ${payload.approvals.length} approvals \u2014 bootstrap envelopes MUST have approvals: []. Non-empty server signatures should go through the normal (non-bootstrap) attest flow.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const validation = validateShape4ActivationDiff({
+    repoRoot,
+    baseSha: payload.base_sha,
+    headSha: payload.head_sha
+  });
+  if (!validation.ok) {
+    fail2(
+      `bootstrap envelope rejected: diff does not match the Shape 4 activation whitelist \u2014 ${validation.reason}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const claimed = [...marker.activated_paths].sort();
+  const actual = [...validation.activatedPaths].sort();
+  if (claimed.length !== actual.length || !claimed.every((p, i) => p === actual[i])) {
+    fail2(
+      `bootstrap envelope's migration_bootstrap.activated_paths (${claimed.join(", ")}) does not match the actual changed-files set (${actual.join(", ")}). The marker must declare exactly the paths the bootstrap PR activates.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const baseManifest = loadManifestAtBase(payload.base_sha, repoRoot);
+  if (!baseManifest) {
+    fail2(
+      `bootstrap envelope rejected: .stamp/trusted-keys/manifest.yml is missing or malformed at base ${payload.base_sha.slice(0, 8)}. Bootstrap requires the manifest in the merge-base tree (it's the trust root for the operator's outer signature and the admin counter-signature).`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (!payload.manifest_snapshot_sha256) {
+    fail2(
+      `bootstrap envelope is missing manifest_snapshot_sha256 \u2014 required for v3+ envelopes`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const computedSnapshot = snapshotSha256(baseManifest);
+  if (payload.manifest_snapshot_sha256 !== computedSnapshot) {
+    fail2(
+      `bootstrap envelope manifest_snapshot_sha256 (${payload.manifest_snapshot_sha256.slice(0, 16)}\u2026) does not match the manifest at base ${payload.base_sha.slice(0, 8)} (${computedSnapshot.slice(0, 16)}\u2026)`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const pubkeyByFingerprint = loadPubkeysAtBase(payload.base_sha, repoRoot);
+  const operatorCaps = resolveCapability(baseManifest, payload.signer_key_id);
+  if (operatorCaps === null) {
+    fail2(
+      `bootstrap envelope signer ${payload.signer_key_id} is not listed in the manifest at base ${payload.base_sha.slice(0, 8)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (!operatorCaps.includes("operator") && !operatorCaps.includes("admin")) {
+    fail2(
+      `bootstrap envelope signer ${payload.signer_key_id} has capabilities [${operatorCaps.join(", ")}] at base ${payload.base_sha.slice(0, 8)} \u2014 needs operator or admin`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const operatorPem = pubkeyByFingerprint.get(payload.signer_key_id);
+  if (!operatorPem) {
+    fail2(
+      `bootstrap envelope signer ${payload.signer_key_id} has no matching .pub file in .stamp/trusted-keys/ at base ${payload.base_sha.slice(0, 8)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const operatorBytes = serializePayload2(payload);
+  let operatorSigOk = false;
+  try {
+    operatorSigOk = verifyBytes(operatorPem, operatorBytes, envelope.signature);
+  } catch (err) {
+    fail2(
+      `bootstrap envelope operator-signature verification threw: ${err instanceof Error ? err.message : String(err)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (!operatorSigOk) {
+    fail2(
+      `bootstrap envelope operator signature does not verify against the operator's pubkey ${payload.signer_key_id}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const sigs = payload.trust_anchor_signatures ?? [];
+  if (sigs.length !== 1) {
+    fail2(
+      `bootstrap envelope must carry exactly one trust_anchor_signatures entry (got ${sigs.length}) \u2014 multi-admin bootstrap collection is not supported by the bootstrap path. Lower path_rules minimum_signatures or use the standard admin-sign flow.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const adminSig = sigs[0];
+  const adminCaps = resolveCapability(baseManifest, adminSig.signer_key_id);
+  if (adminCaps === null) {
+    fail2(
+      `bootstrap envelope admin signer ${adminSig.signer_key_id} is not listed in the manifest at base ${payload.base_sha.slice(0, 8)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (!adminCaps.includes("admin")) {
+    fail2(
+      `bootstrap envelope admin signer ${adminSig.signer_key_id} has capabilities [${adminCaps.join(", ")}] at base ${payload.base_sha.slice(0, 8)} \u2014 needs admin`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const adminPem = pubkeyByFingerprint.get(adminSig.signer_key_id);
+  if (!adminPem) {
+    fail2(
+      `bootstrap envelope admin signer ${adminSig.signer_key_id} has no matching .pub file in .stamp/trusted-keys/ at base ${payload.base_sha.slice(0, 8)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const v4View = {
+    schema_version: payload.schema_version,
+    base_sha: payload.base_sha,
+    head_sha: payload.head_sha,
+    target_branch: payload.target_branch,
+    diff_sha256: payload.diff_sha256,
+    manifest_snapshot_sha256: payload.manifest_snapshot_sha256,
+    approvals: [],
+    checks: payload.checks,
+    trust_anchor_signatures: [],
+    signer_key_id: payload.signer_key_id
+  };
+  const adminBytes = bootstrapAdminSigningBytes({ payloadV4: v4View, marker });
+  let adminSigOk = false;
+  try {
+    adminSigOk = verifyBytes(adminPem, adminBytes, adminSig.signature);
+  } catch (err) {
+    fail2(
+      `bootstrap envelope admin-signature verification threw: ${err instanceof Error ? err.message : String(err)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (!adminSigOk) {
+    fail2(
+      `bootstrap envelope admin signature by ${adminSig.signer_key_id} does not verify against the bootstrap signing-bytes (payload-with-marker, trust_anchor_signatures: []).`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const pathRules = loadPathRulesAtBase(payload.base_sha, repoRoot);
+  if (pathRules.length === 0) {
+    fail2(
+      `bootstrap envelope rejected: no path_rules configured at base ${payload.base_sha.slice(0, 8)}. The bootstrap path requires path_rules covering the activated paths with bypass_review_cycle: true \u2014 typically already in place from a prior Shape 2 migration.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  for (const p of marker.activated_paths) {
+    let coveredBy = null;
+    for (const rule2 of pathRules) {
+      if (pathMatchesAny(p, [rule2.pattern])) {
+        coveredBy = rule2;
+        break;
+      }
+    }
+    if (!coveredBy) {
+      fail2(
+        `bootstrap envelope rejected: path_rules at base ${payload.base_sha.slice(0, 8)} does not cover activated path "${p}". Configured patterns: ${pathRules.map((r) => `"${r.pattern}"`).join(", ")}.`,
+        patch_id,
+        resolved.base_sha,
+        resolved.head_sha
+      );
+    }
+    if (!coveredBy.bypass_review_cycle) {
+      fail2(
+        `bootstrap envelope rejected: path_rule "${coveredBy.pattern}" at base ${payload.base_sha.slice(0, 8)} has bypass_review_cycle: false. Bootstrap requires the matched rule to opt out of the reviewer cycle.`,
+        patch_id,
+        resolved.base_sha,
+        resolved.head_sha
+      );
+    }
+  }
+  if (payload.target_branch !== opts.into) {
+    fail2(
+      `bootstrap envelope target_branch ("${payload.target_branch}") does not match --into ("${opts.into}")`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (!payload.diff_sha256) {
+    fail2(
+      `bootstrap envelope is missing diff_sha256 \u2014 required for v3+ envelopes`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const actualDiff = spawnSync19(
+    "git",
+    ["diff", `${payload.base_sha}...${payload.head_sha}`],
+    { cwd: repoRoot, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }
+  );
+  if (actualDiff.status !== 0) {
+    fail2(
+      `bootstrap envelope rejected: could not compute base...head diff for diff_sha256 check`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const diffText = actualDiff.stdout ?? "";
+  const actualDiffSha256 = createHash13("sha256").update(Buffer.from(diffText, "utf8")).digest("hex");
+  if (actualDiffSha256 !== payload.diff_sha256) {
+    fail2(
+      `bootstrap envelope diff_sha256 mismatch \u2014 payload claims ${payload.diff_sha256.slice(0, 12)}\u2026 but base...head hashes to ${actualDiffSha256.slice(0, 12)}\u2026. The operator signed against a different diff.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  let configYaml;
+  try {
+    configYaml = showAtRef(payload.base_sha, ".stamp/config.yml", repoRoot);
+  } catch (e) {
+    fail2(
+      `bootstrap envelope rejected: could not read .stamp/config.yml at base ${payload.base_sha.slice(0, 8)}: ${e.message}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const config2 = parseConfigFromYaml(configYaml);
+  const rule = findBranchRule(config2.branches, opts.into);
+  if (!rule) {
+    fail2(
+      `bootstrap envelope rejected: no branch rule for "${opts.into}" in .stamp/config.yml at base ${payload.base_sha.slice(0, 8)}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (rule.strict_base) {
+    const currentTip = runGit(
+      ["rev-parse", `${opts.into}^{commit}`],
+      repoRoot
+    ).trim();
+    if (envelope.payload.target_branch_tip_sha !== currentTip) {
+      fail2(
+        `bootstrap strict_base check failed: attestation was signed when ${opts.into} was at ${envelope.payload.target_branch_tip_sha?.slice(0, 8)}, but ${opts.into} is now at ${currentTip.slice(0, 8)}`,
+        patch_id,
+        resolved.base_sha,
+        resolved.head_sha
+      );
+    }
+  }
+  printSuccess3({
+    patch_id,
+    base_sha: resolved.base_sha,
+    head_sha: resolved.head_sha,
+    target_branch: opts.into,
+    signer_key_id: payload.signer_key_id,
+    approvals: [],
+    strict_base: rule.strict_base ?? false,
+    schema_version: envelope.payload.schema_version,
+    bootstrap: true,
+    activated_paths: marker.activated_paths
+  });
+}
 function loadManifestAtBase(base_sha, repoRoot) {
   let yaml;
   try {
@@ -12101,7 +13057,7 @@ function loadManifestAtBase(base_sha, repoRoot) {
   return parseManifest(yaml);
 }
 function loadPubkeysAtBase(base_sha, repoRoot) {
-  const lsResult = spawnSync18(
+  const lsResult = spawnSync19(
     "git",
     ["ls-tree", "--name-only", base_sha, ".stamp/trusted-keys/"],
     { cwd: repoRoot, encoding: "utf8" }
@@ -12113,7 +13069,7 @@ function loadPubkeysAtBase(base_sha, repoRoot) {
     return l.startsWith(prefix) ? l.slice(prefix.length) : l;
   }).filter((n) => n.endsWith(".pub"));
   return buildPubkeyMap(pubFiles, (relPath) => {
-    const show = spawnSync18(
+    const show = spawnSync19(
       "git",
       ["show", `${base_sha}:${relPath}`],
       { cwd: repoRoot, encoding: "utf8" }
@@ -12131,7 +13087,7 @@ function loadPathRulesAtBase(base_sha, repoRoot) {
   }
   let raw;
   try {
-    raw = parseYaml11(yaml);
+    raw = parseYaml13(yaml);
   } catch {
     return [];
   }
@@ -12144,7 +13100,7 @@ function loadPathRulesAtBase(base_sha, repoRoot) {
   return parsedRules.rules;
 }
 function loadChangedFiles(base_sha, head_sha, repoRoot) {
-  const result = spawnSync18(
+  const result = spawnSync19(
     "git",
     ["diff", "-z", "--name-only", `${base_sha}...${head_sha}`],
     { cwd: repoRoot, encoding: "utf8" }
@@ -12160,12 +13116,18 @@ function printSuccess3(s) {
   );
   console.log(bar);
   console.log(`  patch-id:        ${s.patch_id}`);
-  console.log(`  schema:          v${s.schema_version} (v4-trust)`);
+  console.log(
+    `  schema:          v${s.schema_version}${s.bootstrap ? " (Shape 4 migration bootstrap)" : " (v4-trust)"}`
+  );
   console.log(`  signer:          ${s.signer_key_id}`);
   console.log(`  base mode:       ${s.strict_base ? "strict" : "loose"}`);
-  for (const a of s.approvals) {
-    const mark = a.verdict === "approved" ? "\u2713" : "\u2717";
-    console.log(`  ${mark}  ${a.reviewer.padEnd(16)} ${a.verdict}`);
+  if (s.bootstrap && s.activated_paths) {
+    console.log(`  activated:       ${s.activated_paths.join(", ")}`);
+  } else {
+    for (const a of s.approvals) {
+      const mark = a.verdict === "approved" ? "\u2713" : "\u2717";
+      console.log(`  ${mark}  ${a.reviewer.padEnd(16)} ${a.verdict}`);
+    }
   }
   console.log(bar);
   console.log("result: VERIFIED");
@@ -12562,11 +13524,19 @@ program.command("attest [branch]").description(
 ).requiredOption("--into <target>", "target branch whose rule the gate is checked against").option(
   "--push [remote]",
   "after attesting locally, push the current branch + the attestation ref to <remote> in one atomic git push (default remote: origin)"
+).option(
+  "--migrate-existing",
+  "Shape 4 migration bootstrap (AGT-398): attest a narrowly-scoped diff that ADDS `review_server:` + `[server]`-capability trust-anchor entries (the chicken-and-egg PR that activates server-attested reviews on an existing repo). Produces a v3 envelope with empty server_signatures, a migration-bootstrap marker in the operator-signed payload, and exactly one operator-self admin counter-signature in `trust_anchor_signatures`. The flag is REFUSED on any diff outside the narrow Shape-4-activation whitelist (no files outside .stamp/, no modifications to existing trust-anchor entries, no removals). Requires the operator's local key to have `admin` capability in the working-tree manifest and `path_rules` to cover the activated paths with `bypass_review_cycle: true` and `minimum_signatures: 1`. See docs/migration-1.x-to-2.x.md for the full Shape 4 bootstrap walkthrough."
 ).action(
   (branch, opts) => {
     try {
       const pushTo = opts.push === true ? "origin" : typeof opts.push === "string" ? opts.push : void 0;
-      runAttest({ branch, into: opts.into, pushTo });
+      runAttest({
+        branch,
+        into: opts.into,
+        pushTo,
+        migrateExisting: opts.migrateExisting === true
+      });
     } catch (err) {
       handleCliError(err);
     }
@@ -12618,7 +13588,7 @@ program.command("prune").description(
 });
 program.command("ui").description("launch the interactive terminal UI").action(async () => {
   try {
-    const { runUi } = await import("./ui-P5DRAT3P.js");
+    const { runUi } = await import("./ui-67BDQPER.js");
     runUi();
   } catch (err) {
     handleCliError(err);