@openthink/stamp 2.1.0 → 2.1.1

package/dist/index.js

@@ -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";
@@ -10218,6 +10219,15 @@ function parseEnvelope(bytes) {
   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) {
@@ -10290,6 +10300,414 @@ function readAttestationBlobBytes(patch_id, repoRoot) {
   return cat.stdout;
 }
 
+// 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" }
+  );
+  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()}`
+    };
+  }
+  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;
+  }
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      reason: "bootstrap diff is empty \u2014 nothing to activate"
+    };
+  }
+  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`
+        };
+      }
+      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`
+        };
+      }
+      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`
+        };
+      }
+      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();
@@ -10309,7 +10727,19 @@ function runAttest(opts) {
     repoRoot
   ).trim();
   const { keypair } = ensureUserKeypair();
-  const result = rule.review_server ? buildV3Envelope({
+  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,
@@ -10346,10 +10776,9 @@ function runAttest(opts) {
     `  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)"}`
-  );
+  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);
@@ -10608,18 +11037,197 @@ function buildV2Envelope(input) {
     // Phase-1 deliberate omission — see file-level comment.
     signer_key_id: input.operatorFingerprint
   };
-  const signature = signBytes(
-    input.operatorPrivateKeyPem,
-    serializePayload2(payload)
-  );
+  const signature = signBytes(
+    input.operatorPrivateKeyPem,
+    serializePayload2(payload)
+  );
+  return {
+    payload,
+    signature,
+    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: approvals.map((a) => a.reviewer)
+    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" }
@@ -10914,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,
@@ -10923,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";
@@ -11322,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);
     }
@@ -11583,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}`
@@ -11667,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);
@@ -11686,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) {
@@ -11720,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" }
@@ -11741,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 }
@@ -11960,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);
@@ -12002,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;
   }
@@ -12130,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 {
@@ -12140,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" }
@@ -12152,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" }
@@ -12170,7 +13087,7 @@ function loadPathRulesAtBase(base_sha, repoRoot) {
   }
   let raw;
   try {
-    raw = parseYaml11(yaml);
+    raw = parseYaml13(yaml);
   } catch {
     return [];
   }
@@ -12183,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" }
@@ -12199,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");
@@ -12601,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);
     }