halfcycle 0.3.26 → 0.3.28

package/dist/index.js

@@ -1,6 +1,8 @@
 // dist/install.js
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync4, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2, join as join5, relative } from "node:path";
+import { dirname as dirname2, join as join5, posix, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // ../events/dist/result.js
@@ -28,6 +30,11 @@ var HALFCYCLE_DIR_NAME = ".halfcycle";
 var ENGAGEMENTS_DIR_NAME = "engagements";
 var ENGAGEMENT_ENV_FILENAME = "env";
 var NOT_THIS_ACCOUNT_MARKER_FILENAME = "not-this-account";
+var ENGAGEMENT_ID_PATTERN = "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
+var ENGAGEMENT_ID_SHAPE = new RegExp(ENGAGEMENT_ID_PATTERN);
+function isEngagementId(value) {
+  return typeof value === "string" && ENGAGEMENT_ID_SHAPE.test(value);
+}
 var ENGAGEMENT_ENV_HEADER = "# Halfcycle per-engagement credential \u2014 machine level, owner-only, never in a repository.";
 function shq(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -328,6 +335,18 @@ var artefactRefSchema = z4.object({
   name: z4.string(),
   parent: z4.string()
 }).strict();
+var coverageSchema = z4.object({
+  asked: z4.number().int().nonnegative(),
+  answered: z4.number().int().nonnegative()
+}).strict().superRefine((coverage, ctx) => {
+  if (coverage.answered > coverage.asked) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      path: ["answered"],
+      message: "answered cannot be more than asked"
+    });
+  }
+});
 var artefactRecordSchema = stateRecordEnvelopeSchema.extend({
   recordKind: z4.literal("artefact"),
   artefactRef: artefactRefSchema,
@@ -366,7 +385,8 @@ var gateRecordSchema = stateRecordEnvelopeSchema.extend({
   gateKind: gateKindSchema,
   verdict: gateVerdictSchema,
   actor: z4.string(),
-  outcomeReason: z4.string().max(2e3).optional()
+  outcomeReason: z4.string().max(2e3).optional(),
+  coverage: coverageSchema.optional()
 }).strict().superRefine((rec, ctx) => {
   const issue = outcomeReasonIssue(rec.verdict, rec.outcomeReason);
   if (issue) {
@@ -379,7 +399,8 @@ var interventionRecordSchema = stateRecordEnvelopeSchema.extend({
   mechanism: mechanismSchema,
   severity: severitySchema,
   disposition: dispositionSchema,
-  summary: z4.string().max(2e3)
+  summary: z4.string().max(2e3),
+  coverage: coverageSchema.optional()
 }).strict();
 var stateRecordSchema = z4.discriminatedUnion("recordKind", [
   artefactRecordSchema,
@@ -675,7 +696,19 @@ var ENGAGEMENTS_DIR = ENGAGEMENTS_DIR_NAME;
 var ENV_FILENAME = ENGAGEMENT_ENV_FILENAME;
 var HALFCYCLE_DIR = HALFCYCLE_DIR_NAME;
 var PIN_ENGAGEMENT_ID_FIELD = "engagementId";
+var InvalidEngagementIdError = class extends Error {
+  constructor(engagementId) {
+    const shown = JSON.stringify(engagementId.length > 80 ? `${engagementId.slice(0, 80)}\u2026` : engagementId);
+    super(`${shown} is not a Halfcycle project id, so it cannot name a folder on this machine and nothing was written. A project id looks like 3f2a1c4e-8b7d-4e2f-9a61-0c5d7e8f9b10. If it is the "${PIN_ENGAGEMENT_ID_FIELD}" in .halfcycle/bundle.json, delete that file and run "npx halfcycle" again: this repository is then set up as a new Halfcycle project.`);
+    this.name = "InvalidEngagementIdError";
+  }
+};
+function assertEngagementId(engagementId) {
+  if (!isEngagementId(engagementId))
+    throw new InvalidEngagementIdError(engagementId);
+}
 function engagementStateDir(engagementId, home) {
+  assertEngagementId(engagementId);
   return join2(halfcycleHome(home), ENGAGEMENTS_DIR, engagementId);
 }
 function engagementEnvPath(engagementId, home) {
@@ -766,6 +799,14 @@ halfcycle_env_file() {
     HALFCYCLE_ENV_PROBLEM="no-id"
     return 1
   fi
+  # The id is about to become a path under $HOME, and it came from a committed
+  # file: anything that is not a project id (a "../", a "/") is refused here,
+  # before the path exists. hc_id holds no newline (the pin was flattened above),
+  # so grep sees exactly one line.
+  if ! printf '%s\\n' "$hc_id" | grep -Eq '${ENGAGEMENT_ID_PATTERN}'; then
+    HALFCYCLE_ENV_PROBLEM="bad-id"
+    return 1
+  fi
   HALFCYCLE_ENV_ENGAGEMENT="$hc_id"
   if [ -z "\${HOME:-}" ]; then
     HALFCYCLE_ENV_PROBLEM="no-home"
@@ -834,6 +875,264 @@ function mintOrReadIdentity(targetRepoRoot) {
   return { identity, minted: true };
 }
 
+// dist/install-manifest.js
+import { createHash } from "node:crypto";
+var INSTALL_MANIFEST_REL = ".halfcycle/install-manifest.json";
+var INSTALL_MANIFEST_FORMAT = "halfcycle-install-manifest/v1";
+function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function canonicalJson(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalJson);
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, canonicalJson(v)]);
+    return Object.fromEntries(entries);
+  }
+  return value;
+}
+function canonicalSha256(value) {
+  return sha256Hex(JSON.stringify(canonicalJson(value)));
+}
+function byString(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function serializeManifest(manifest) {
+  const settings = {
+    ...manifest.settings,
+    hookCommands: [...manifest.settings.hookCommands].sort(byString),
+    denyAddedSha256: [...manifest.settings.denyAddedSha256].sort(byString),
+    eventsCreated: [...manifest.settings.eventsCreated].sort(byString)
+  };
+  const ordered = {
+    ...manifest,
+    files: [...manifest.files].sort((a, b) => byString(a.path, b.path)),
+    createdDirs: [...manifest.createdDirs].sort(byString),
+    leftAlone: [...manifest.leftAlone].sort(byString),
+    settings
+  };
+  return JSON.stringify(canonicalJson(ordered), null, 2) + "\n";
+}
+var UnreadableManifestError = class extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "UnreadableManifestError";
+  }
+};
+var HEX64 = /^[0-9a-f]{64}$/;
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringArray(value, field) {
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+    throw new UnreadableManifestError(`"${field}" is not a list of strings`);
+  }
+  return value;
+}
+function hashArray(value, field) {
+  const list = stringArray(value, field);
+  if (!list.every((v) => HEX64.test(v)))
+    throw new UnreadableManifestError(`"${field}" holds a value that is not a hash`);
+  return list;
+}
+function bool(value, field) {
+  if (typeof value !== "boolean")
+    throw new UnreadableManifestError(`"${field}" is not true or false`);
+  return value;
+}
+function onlyKeys(value, allowed, where) {
+  const extra = Object.keys(value).filter((k) => !allowed.includes(k));
+  if (extra.length > 0)
+    throw new UnreadableManifestError(`${where} has a field this version does not know: ${extra.join(", ")}`);
+}
+function parseManifest(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new UnreadableManifestError("it is not valid JSON");
+  }
+  if (!isRecord(raw))
+    throw new UnreadableManifestError("it is not a JSON object");
+  onlyKeys(raw, ["format", "files", "createdDirs", "leftAlone", "settings", "mcp", "gitignore"], "the manifest");
+  if (raw["format"] !== INSTALL_MANIFEST_FORMAT) {
+    throw new UnreadableManifestError(`its format is not ${INSTALL_MANIFEST_FORMAT}`);
+  }
+  if (!Array.isArray(raw["files"]))
+    throw new UnreadableManifestError('"files" is not a list');
+  const files = raw["files"].map((entry) => {
+    if (!isRecord(entry) || typeof entry["path"] !== "string") {
+      throw new UnreadableManifestError('a "files" entry has no path');
+    }
+    if (entry["perMachine"] === true) {
+      onlyKeys(entry, ["path", "perMachine"], `the "files" entry for ${entry["path"]}`);
+      return { path: entry["path"], perMachine: true };
+    }
+    onlyKeys(entry, ["path", "sha256"], `the "files" entry for ${entry["path"]}`);
+    if (typeof entry["sha256"] !== "string" || !HEX64.test(entry["sha256"])) {
+      throw new UnreadableManifestError(`the "files" entry for ${entry["path"]} has no valid hash`);
+    }
+    return { path: entry["path"], sha256: entry["sha256"] };
+  });
+  const s = raw["settings"];
+  if (!isRecord(s))
+    throw new UnreadableManifestError('"settings" is missing');
+  onlyKeys(s, [
+    "created",
+    "adopted",
+    "hookCommands",
+    "denyAddedSha256",
+    "schemaBefore",
+    "eventsCreated",
+    "hooksCreated",
+    "permissionsCreated",
+    "denyCreated"
+  ], '"settings"');
+  const settings = {
+    created: bool(s["created"], "settings.created"),
+    adopted: bool(s["adopted"], "settings.adopted"),
+    hookCommands: stringArray(s["hookCommands"], "settings.hookCommands"),
+    denyAddedSha256: hashArray(s["denyAddedSha256"], "settings.denyAddedSha256"),
+    ..."schemaBefore" in s ? { schemaBefore: s["schemaBefore"] } : {},
+    eventsCreated: stringArray(s["eventsCreated"], "settings.eventsCreated"),
+    hooksCreated: bool(s["hooksCreated"], "settings.hooksCreated"),
+    permissionsCreated: bool(s["permissionsCreated"], "settings.permissionsCreated"),
+    denyCreated: bool(s["denyCreated"], "settings.denyCreated")
+  };
+  let mcp;
+  if (raw["mcp"] !== void 0) {
+    const m = raw["mcp"];
+    if (!isRecord(m))
+      throw new UnreadableManifestError('"mcp" is not an object');
+    onlyKeys(m, ["created", "adopted", "mcpServersCreated", "entrySha256"], '"mcp"');
+    if (m["entrySha256"] !== void 0 && (typeof m["entrySha256"] !== "string" || !HEX64.test(m["entrySha256"]))) {
+      throw new UnreadableManifestError('"mcp.entrySha256" is not a hash');
+    }
+    mcp = {
+      created: bool(m["created"], "mcp.created"),
+      adopted: bool(m["adopted"], "mcp.adopted"),
+      mcpServersCreated: bool(m["mcpServersCreated"], "mcp.mcpServersCreated"),
+      ...typeof m["entrySha256"] === "string" ? { entrySha256: m["entrySha256"] } : {}
+    };
+  }
+  const g = raw["gitignore"];
+  if (!isRecord(g))
+    throw new UnreadableManifestError('"gitignore" is missing');
+  onlyKeys(g, ["created", "appended"], '"gitignore"');
+  const gitignore = {
+    created: bool(g["created"], "gitignore.created"),
+    appended: stringArray(g["appended"], "gitignore.appended")
+  };
+  const paths = files.map((f) => f.path);
+  if (new Set(paths).size !== paths.length)
+    throw new UnreadableManifestError('"files" names a path twice');
+  const leftAlone = stringArray(raw["leftAlone"], "leftAlone");
+  if (leftAlone.some((p) => paths.includes(p))) {
+    throw new UnreadableManifestError('a path is in both "files" and "leftAlone"');
+  }
+  return {
+    format: INSTALL_MANIFEST_FORMAT,
+    files,
+    createdDirs: stringArray(raw["createdDirs"], "createdDirs"),
+    leftAlone,
+    settings,
+    ...mcp !== void 0 ? { mcp } : {},
+    gitignore
+  };
+}
+function startManifest(previous, isMember, isMemberDir) {
+  const files = /* @__PURE__ */ new Map();
+  for (const entry of previous?.files ?? []) {
+    if (isMember(entry.path))
+      files.set(entry.path, entry);
+  }
+  return {
+    previous,
+    files,
+    collided: /* @__PURE__ */ new Set(),
+    createdDirs: new Set((previous?.createdDirs ?? []).filter(isMemberDir)),
+    settings: previous?.settings,
+    mcp: previous?.mcp,
+    gitignore: previous?.gitignore
+  };
+}
+function recordInstalledFile(draft, path, bytes) {
+  draft.files.set(path, { path, sha256: sha256Hex(bytes) });
+}
+function recordPerMachineFile(draft, path) {
+  draft.files.set(path, { path, perMachine: true });
+}
+function recordCollision(draft, path) {
+  draft.collided.add(path);
+}
+function recordCreatedDir(draft, path) {
+  draft.createdDirs.add(path);
+}
+function recordSettings(draft, observed) {
+  const prev = draft.settings;
+  if (prev === void 0) {
+    draft.settings = observed;
+    return;
+  }
+  draft.settings = {
+    created: prev.created,
+    adopted: prev.adopted,
+    hookCommands: union(prev.hookCommands, observed.hookCommands),
+    denyAddedSha256: union(prev.denyAddedSha256, observed.denyAddedSha256),
+    ..."schemaBefore" in prev ? { schemaBefore: prev.schemaBefore } : "schemaBefore" in observed ? { schemaBefore: observed.schemaBefore } : {},
+    eventsCreated: union(prev.eventsCreated, observed.eventsCreated),
+    hooksCreated: prev.hooksCreated,
+    permissionsCreated: prev.permissionsCreated,
+    denyCreated: prev.denyCreated
+  };
+}
+function recordMcp(draft, observed) {
+  const prev = draft.mcp;
+  if (prev === void 0) {
+    draft.mcp = observed;
+    return;
+  }
+  const entrySha256 = observed.entrySha256 ?? prev.entrySha256;
+  draft.mcp = {
+    created: prev.created,
+    adopted: prev.adopted,
+    mcpServersCreated: prev.mcpServersCreated,
+    ...entrySha256 !== void 0 ? { entrySha256 } : {}
+  };
+}
+function recordGitignore(draft, created, appended) {
+  const prev = draft.gitignore;
+  draft.gitignore = {
+    created: prev?.created ?? created,
+    appended: [...prev?.appended ?? [], ...appended.filter((a) => a !== "")]
+  };
+}
+function finishManifest(draft) {
+  const files = [...draft.files.values()];
+  const leftAlone = [...draft.collided].filter((p) => !draft.files.has(p));
+  return {
+    format: INSTALL_MANIFEST_FORMAT,
+    files,
+    createdDirs: [...draft.createdDirs],
+    leftAlone,
+    settings: draft.settings ?? {
+      created: false,
+      adopted: false,
+      hookCommands: [],
+      denyAddedSha256: [],
+      eventsCreated: [],
+      hooksCreated: false,
+      permissionsCreated: false,
+      denyCreated: false
+    },
+    ...draft.mcp !== void 0 ? { mcp: draft.mcp } : {},
+    gitignore: draft.gitignore ?? { created: false, appended: [] }
+  };
+}
+function union(a, b) {
+  return [.../* @__PURE__ */ new Set([...a, ...b])];
+}
+
 // dist/mcp-endpoint.js
 var MCP_ENDPOINT_PATH = "/mcp";
 function mcpEndpointUrl(origin) {
@@ -919,8 +1218,9 @@ function scanLayers(targetRepo, scannedAt = (/* @__PURE__ */ new Date()).toISOSt
   }
   return { format: HALFCYCLE_STATE_FORMAT, note: HALFCYCLE_STATE_NOTE, layers };
 }
+var BOOTSTRAP_STATE_REL = ".halfcycle/state.json";
 function runBootstrapScan(targetRepo) {
-  const statePath = join4(targetRepo, ".halfcycle", "state.json");
+  const statePath = join4(targetRepo, BOOTSTRAP_STATE_REL);
   if (existsSync2(statePath)) {
     const existing = JSON.parse(readFileSync3(statePath, "utf-8"));
     return { state: existing, ran: false };
@@ -994,22 +1294,152 @@ function isAllowlisted(targetRelPath) {
     return normalised === p || normalised.startsWith(p + "/");
   });
 }
+var BUNDLE_PIN_REL = ".halfcycle/bundle.json";
+var PROJECT_IDENTITY_REL = ".halfcycle/project.json";
+var CREW_ROSTER_REL = ".halfcycle/crew.json";
+var CAPTURED_INDEX_REL = "test/fixtures/captured/manifest.json";
+var SETTINGS_REL = ".claude/settings.json";
+var GITIGNORE_REL = ".gitignore";
+function commandStubRel(name) {
+  return `.claude/commands/${name}.md`;
+}
+var RETIRED_WRITE_SET_FILES = [];
+var RETIRED_HOOK_COMMANDS = [];
+var RETIRED_DENY_PATTERNS = [];
+function installerHookCommands() {
+  const settings = JSON.parse(generateSettingsJson());
+  return Object.values(settings.hooks ?? {}).flatMap((entries) => entries.flatMap((entry) => entry.hooks.map((h) => h.command)));
+}
+function closedWriteSet() {
+  const files = /* @__PURE__ */ new Set([
+    ...(readPluginManifest().commands ?? []).map((cmd) => commandStubRel(cmd.name)),
+    ...Object.keys(OWNED_GENERATED_HEADERS),
+    VENDORED_BIN_REL,
+    CREW_ROSTER_REL,
+    BUNDLE_PIN_REL,
+    PROJECT_IDENTITY_REL,
+    BOOTSTRAP_STATE_REL,
+    CAPTURED_INDEX_REL,
+    INSTALL_MANIFEST_REL,
+    ...RETIRED_WRITE_SET_FILES
+  ]);
+  const merged = /* @__PURE__ */ new Set([SETTINGS_REL, MCP_REGISTRATION_REL, GITIGNORE_REL]);
+  const dirs = /* @__PURE__ */ new Set();
+  for (const path of [...files, ...merged]) {
+    for (let dir = posix.dirname(path); dir !== "."; dir = posix.dirname(dir))
+      dirs.add(dir);
+  }
+  const ownedDirs = new Set([...dirs].filter((dir) => `${dir}/`.startsWith(INSTALLER_OWNED_DIR)));
+  return {
+    files,
+    merged,
+    dirs,
+    ownedDirs,
+    hookCommands: /* @__PURE__ */ new Set([...installerHookCommands(), ...RETIRED_HOOK_COMMANDS]),
+    denyRuleSha256: new Set([...DENY_PATTERNS, ...RETIRED_DENY_PATTERNS].map((rule) => sha256Hex(rule))),
+    gitignoreLines: /* @__PURE__ */ new Set([GITIGNORE_HEADER, ...REQUIRED_GITIGNORE_ENTRIES, LEGACY_ENV_LOCAL_REL])
+  };
+}
+function readPreviousManifest(targetRepo) {
+  try {
+    return parseManifest(readFileSync4(join5(targetRepo, INSTALL_MANIFEST_REL), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function noteFile(draft, targetRepo, rel, outcome) {
+  if (outcome === "collided") {
+    recordCollision(draft, rel);
+    return;
+  }
+  recordInstalledFile(draft, rel, readFileSync4(join5(targetRepo, rel)));
+}
+function recordSettingsMerge(draft, existing, generated, preexisted) {
+  const generatedHooks = generated.hooks ?? {};
+  const hookCommands = Object.values(generatedHooks).flatMap((entries) => entries.flatMap((entry) => entry.hooks.map((h) => h.command)));
+  const ours = new Set(hookCommands);
+  const existingHooks = isPlainObject(existing.hooks) ? existing.hooks : void 0;
+  const heldOurs = Object.values(existingHooks ?? {}).some((entries) => Array.isArray(entries) && entries.some((entry) => isHalfcycleEntry(entry, ours)));
+  const existingDeny = Array.isArray(existing.permissions?.deny) ? existing.permissions.deny : [];
+  const schemaChanged = generated.$schema !== void 0 && existing.$schema !== generated.$schema;
+  recordSettings(draft, {
+    created: !preexisted,
+    adopted: draft.previous === null && heldOurs,
+    hookCommands,
+    denyAddedSha256: (generated.permissions?.deny ?? []).filter((rule) => !existingDeny.includes(rule)).map((rule) => sha256Hex(rule)),
+    ...schemaChanged ? { schemaBefore: existing.$schema ?? null } : {},
+    eventsCreated: Object.keys(generatedHooks).filter((event) => !(existingHooks && event in existingHooks)),
+    hooksCreated: existing.hooks === void 0,
+    permissionsCreated: existing.permissions === void 0,
+    denyCreated: existing.permissions?.deny === void 0
+  });
+}
+function recordMcpMerge(draft, existingText, writtenText) {
+  const before = existingText === null ? void 0 : JSON.parse(existingText);
+  const servers = isPlainObject(before) ? before["mcpServers"] : void 0;
+  const written = JSON.parse(writtenText);
+  recordMcp(draft, {
+    created: existingText === null,
+    adopted: draft.previous === null && isPlainObject(servers) && MCP_SERVER_KEY in servers,
+    mcpServersCreated: !(isPlainObject(before) && "mcpServers" in before),
+    entrySha256: canonicalSha256(written.mcpServers[MCP_SERVER_KEY])
+  });
+}
+function recordMcpAdoptionOnly(draft, existingText) {
+  if (draft.previous !== null || draft.mcp !== void 0)
+    return;
+  let before;
+  try {
+    before = JSON.parse(existingText);
+  } catch {
+    return;
+  }
+  const servers = isPlainObject(before) ? before["mcpServers"] : void 0;
+  if (!isPlainObject(servers) || !(MCP_SERVER_KEY in servers))
+    return;
+  recordMcp(draft, { created: false, adopted: true, mcpServersCreated: false });
+}
+function recordGitignoreReconcile(draft, before, after) {
+  const adopted = draft.gitignore === void 0 && before !== null ? adoptOlderGitignoreBlock(before) : "";
+  let appended = "";
+  if (after !== null && after !== before) {
+    if (before === null)
+      appended = after;
+    else if (after.startsWith(before))
+      appended = after.slice(before.length);
+  }
+  recordGitignore(draft, before === null && after !== null, [adopted, appended]);
+}
+function assertManifestInWriteSet(manifest, writeSet) {
+  const strays = [
+    ...manifest.files.map((f) => f.path).filter((p) => !writeSet.files.has(p)),
+    ...manifest.leftAlone.filter((p) => !writeSet.files.has(p)),
+    ...manifest.createdDirs.filter((p) => !writeSet.dirs.has(p))
+  ];
+  if (strays.length > 0) {
+    throw new Error(`[bundle install] the install record names paths outside the write set: ${strays.join(", ")}`);
+  }
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function readPluginManifest() {
   const manifestPath = join5(BUNDLE_ROOT, ".claude-plugin", "plugin.json");
   const raw = readFileSync4(manifestPath, "utf-8");
   return JSON.parse(raw);
 }
-function copyManifestCommands(manifest, targetRepo, report) {
-  const commandsTargetDir = join5(targetRepo, ".claude", "commands");
+function copyManifestCommands(manifest, targetRepo, report, draft) {
   for (const cmd of manifest.commands ?? []) {
     const srcFile = join5(BUNDLE_ROOT, ".claude-plugin", cmd.path);
     if (!existsSync3(srcFile)) {
       throw new Error(`[bundle install] plugin.json declares command "${cmd.name}" at "${cmd.path}", but no file exists there (${srcFile}). The manifest and commands/ must agree.`);
     }
-    const destFile = join5(commandsTargetDir, `${cmd.name}.md`);
+    const rel = commandStubRel(cmd.name);
+    const destFile = join5(targetRepo, rel);
     const content = readFileSync4(srcFile, "utf-8");
-    const rel = relative(targetRepo, destFile).replace(/\\/g, "/");
-    record(report, writeCollisionSafe(destFile, targetRepo, content), rel);
+    const outcome = writeCollisionSafe(destFile, targetRepo, content);
+    record(report, outcome, rel);
+    noteFile(draft, targetRepo, rel, outcome);
   }
 }
 function writeAllowlisted(targetAbsPath, targetRepoRoot, content, writtenPaths) {
@@ -1075,6 +1505,7 @@ function recordOwnedGenerated(report, targetAbsPath, targetRepoRoot, content, ge
   record(report, outcome, rel);
   if (replacedExisting)
     report.replacedPaths.push(rel);
+  return outcome;
 }
 function recordOwned(report, targetAbsPath, targetRepoRoot, content, rel) {
   const existedBefore = existsSync3(targetAbsPath);
@@ -1082,6 +1513,7 @@ function recordOwned(report, targetAbsPath, targetRepoRoot, content, rel) {
   record(report, outcome, rel);
   if (outcome === "written" && existedBefore)
     report.replacedPaths.push(rel);
+  return outcome;
 }
 function record(report, outcome, rel) {
   const bucket = {
@@ -1406,101 +1838,53 @@ printf '%s\\n' '${USER_PROMPT_REMINDER_SENTENCE}'
 exit 0
 `;
 }
-function generateCiStanza() {
-  return `# Halfcycle guard CI job \u2014 generated by the Halfcycle installer.
-# Below is a complete GitHub Actions workflow: a name, the events it runs on, and
-# one job. It assumes no package manager and no monorepo tooling: it runs the
-# self-contained guard binary vendored at .halfcycle/bin/, so it works in a Python
-# or Go repository as well as a Node one \u2014 the only prerequisite is Node 20 to run
-# the bundled binary.
-#
-# NO WORKFLOW YET? Copy everything from the \`name:\` line to the end of the job
-# into a new file, .github/workflows/halfcycle-guard.yml, without the leading
-# "# " on each line. That file is complete as it stands: commit it, and the check
-# runs on the next push and on every pull request.
-#
-# ALREADY HAVE A WORKFLOW? Copy only the job \u2014 from \`halfcycle-guard-ci:\` down to
-# its \`run:\` line \u2014 under the \`jobs:\` key of the workflow you have, keeping the
-# indentation. The job carries its own \`permissions\` block, so it needs nothing
-# from the rest of that file.
-#
-# THERE IS NOTHING TO STORE. No token in your repository's secrets, no project id
-# to look up, and no address to set. The \`permissions\` block below is the whole
-# configuration: it lets the job ask GitHub for a short-lived signed token naming
-# the repository it is running in, and Halfcycle trusts the name GitHub signs
-# rather than anything the job says about itself. That token is traded for a
-# credential that lives for minutes, and nothing is kept at either end.
-#
-# BOTH PERMISSION LINES, NOT JUST THE SECOND. Declaring any permission
-# replaces the defaults rather than adding to them, so a block naming only
-# \`id-token\` takes read access away from the checkout step and a private
-# repository stops checking out before the guard is reached. If your workflow
-# already has a \`permissions\` block, add \`id-token: write\` to it and leave the
-# rest alone.
-#
-# ONE THING TO DO FIRST, ONCE, ON YOUR OWN MACHINE. In this project, run
-#
-#     npx halfcycle ci bind <owner>/<repo>
-#
-# naming this repository as GitHub spells it (for example acme/widgets). That
-# tells Halfcycle this project's CI runs from that repository, and it is the only
-# thing that makes a run mean anything: without it, Halfcycle has a signed
-# statement of which repository the job is in and no idea whose project that is.
-# The check says exactly that, and names the command, if you skip it.
-#
-# THERE IS NO ADDRESS TO CONFIGURE ANYWHERE IN HALFCYCLE. Every service this
-# product talks to has one address, the same for every user, and it ships in the
-# tools you already have: the installer, the guard hook and the binary this job
-# runs each know where to go. If something tells you to set a Halfcycle URL, it is
-# out of date.
-#
-# WHICH BRANCH MODEL THIS ASSUMES: none. It works on pull-request branches AND on
-# commits pushed straight to the default branch, which is the shape most
-# Halfcycle engagements settle on. The \`on:\` block is what runs it in both
-# places: every push, and every pull request. Narrow it if you want (for example
-# \`branches: [main]\` under \`push:\`), but keep \`pull_request\`, or a change is
-# first checked after it has merged. \`fetch-depth\` is what makes the check work
-# there: it needs the commit BEFORE the one it is evaluating, and the default
-# shallow checkout does not have it. With \`fetch-depth: 0\` the check fails loudly
-# if it cannot work out what to evaluate \u2014 it will not pass quietly having
-# evaluated nothing.
-#
-# name: Halfcycle guard
-# on:
-#   push:
-#   pull_request:
-# jobs:
-#   halfcycle-guard-ci:
-#     runs-on: ubuntu-latest
-#     permissions:
-#       contents: read
-#       id-token: write
-#     steps:
-#       - uses: actions/checkout@v4
-#         with:
-#           # REQUIRED. 0 = full history. The check diffs against the commit before
-#           # HEAD (or the fork point on a branch); the default depth of 1 has
-#           # neither. Do not lower this.
-#           fetch-depth: 0
-#       - uses: actions/setup-node@v4
-#         with:
-#           node-version: '20'
-#       - name: Halfcycle guard CI check
-#         # No env block, on purpose: this step holds no secret. The permissions
-#         # above are what authenticate it.
-#         run: node ./.halfcycle/bin/bin.bundle.mjs ci
-#
-# The job prints the diff base it used and how many files it evaluated, on every
-# run. If that line says 0 files on a commit that changed something, the base is
-# wrong \u2014 set HALFCYCLE_DIFF_BASE in an env block OF YOUR COPY of the check step,
-# to name it explicitly (on a GitHub push event, \${{ github.event.before }} is the
-# right value).
-#
-# EDIT YOUR COPY, NOT THIS FILE. This one is regenerated by the installer and your
-# changes to it would be replaced the next time you run \`npx halfcycle\`. It is
-# also inert where it sits: no CI system reads this path. Copy the workflow above
-# \u2014 or just its job \u2014 into .github/workflows/ and change it there.
-`;
+var CI_STANZA_KNOWN_HEADER_HASHES = [
+  "b225800b2d699811f32ac213238cbf81c35b5e6a74114bdf55e39cd9d7e2928f",
+  "674181735460f051af7c157222cf851fc3000fb3b8af3a10ea0bde9fe5eaba1f",
+  "d17bde608a6fec54a63cb934a28d88acc8babc205334b5ee84d4ed6ee219d340",
+  "85e71d3f6551977b241a28468f121ee4d1c4edef40a2c4dc1aa6f2f737ebd037"
+];
+function isTrackedAndClean(targetRepo, relPath) {
+  try {
+    execFileSync2("git", ["-C", targetRepo, "ls-files", "--error-unmatch", "--", relPath], {
+      stdio: "ignore"
+    });
+  } catch {
+    return false;
+  }
+  try {
+    execFileSync2("git", ["-C", targetRepo, "diff", "--quiet", "HEAD", "--", relPath], {
+      stdio: "ignore"
+    });
+  } catch {
+    return false;
+  }
+  return true;
+}
+function removeLegacyCiStanza(targetRepo) {
+  const rel = ".halfcycle/ci-stanza.yml";
+  const path = join5(targetRepo, rel);
+  if (!existsSync3(path))
+    return "absent";
+  let raw;
+  try {
+    raw = readFileSync4(path, "utf-8");
+  } catch {
+    return "failed";
+  }
+  const headerLine = raw.split("\n")[0] ?? "";
+  const digest = createHash2("sha256").update(headerLine, "utf-8").digest("hex");
+  const ours = CI_STANZA_KNOWN_HEADER_HASHES.includes(digest);
+  if (!ours)
+    return "kept-foreign";
+  if (!isTrackedAndClean(targetRepo, rel))
+    return "kept-uncommitted";
+  try {
+    rmSync(path);
+  } catch {
+    return "failed";
+  }
+  return "removed";
 }
 var MCP_REGISTRATION_REL = ".mcp.json";
 var MCP_SERVER_KEY = "halfcycle";
@@ -1542,13 +1926,81 @@ PROJECT_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
 
 ${engagementResolutionShell()}
 
+# Read one KEY's value out of the credential store into HC_VALUE, in the CALLER's
+# shell (call it as a statement, never inside $(...)). Last assignment wins,
+# matching the shell's own \`.\` semantics. An optional leading \`export \` is
+# tolerated because a hand-edited store may use one.
+halfcycle_store_value() {
+  HC_VALUE=""
+  hc_line=$(grep "^[[:space:]]*\\(export[[:space:]][[:space:]]*\\)\\{0,1\\}$2=" "$1" | tail -n 1)
+  hc_v=\${hc_line#*"$2="}
+  hc_v=$(printf '%s' "$hc_v" | tr -d '\\r')
+
+  # Strip one layer of matching quotes. The store is WRITTEN single-quoted (both
+  # writers use the same shq: this installer and Studio's provider), because
+  # guard-runner.sh SOURCES the same file and an unquoted value carrying a space
+  # would execute its own remainder. This reader greps rather than sources, so it
+  # has to undo the quoting itself \u2014 and it must land on the same value the
+  # sourcing consumer gets, or one file has two answers.
+  case $hc_v in
+    '"'*'"') hc_v=\${hc_v#'"'}; hc_v=\${hc_v%'"'} ;;
+    "'"*"'")
+      hc_v=\${hc_v#"'"}; hc_v=\${hc_v%"'"}
+      # \u2026and undo shq's embedded-quote escape, '\\'' -> '. The backslash is matched
+      # through a BRACKET EXPRESSION on purpose. MEASURED, on GNU sed 4.9 (Linux,
+      # the CI platform) and BSD sed (macOS), feeding each the script from a file so
+      # no shell quoting is in the way:
+      #
+      #   s/'[\\]''/'/g   a'\\''b -> a'b     both      <- shipped
+      #   s/'\\''/'/g     a'\\''b -> a'\\''b   both      <- matches NOTHING, exit 0
+      #
+      # A bare \\' in a BRE is undefined by POSIX, and the obvious pattern therefore
+      # does not fail loudly \u2014 it silently substitutes nothing, on BOTH platforms,
+      # and the token then travels with four stray characters in it. The bracket
+      # expression makes the backslash literal by a construction POSIX does define.
+      hc_v=$(printf '%s' "$hc_v" | sed "s/'[\\]''/'/g") ;;
+  esac
+  HC_VALUE=$hc_v
+}
+
+# The scheme and host[:port] of a URL, lowercased \u2014 or NOTHING when the URL holds
+# a space or a control character anywhere. That refusal is the load-bearing part:
+# a URL parser drops tabs and newlines before it reads the host, so
+# "https://ours<newline>@elsewhere/" is a request to "elsewhere", while a
+# line-by-line reading here would see only "https://ours". The host ends at the
+# first / ? # or backslash, which is where a URL parser ends it for http(s).
+halfcycle_origin() {
+  hc_u=$1
+  if [ "$(printf '%s' "$hc_u" | tr -d '[:cntrl:][:space:]')" != "$hc_u" ]; then
+    return 0
+  fi
+  printf '%s\\n' "$hc_u" | sed -n 's|^\\([A-Za-z][A-Za-z0-9+.-]*://[^/?#\\\\]*\\).*$|\\1|p' | tr '[:upper:]' '[:lower:]'
+}
+
 # HALFCYCLE_TOKEN in the environment WINS, and it is the CI arm: a job with no
 # browser and no per-user store exports the credential, and a stale store on a
 # long-lived runner must not silently win over it. Same order, and the same reason,
-# as the CLI's own resolver (\`resolve-credential.ts\`).
+# as the CLI's own resolver (\`resolve-credential.ts\`). The server it may be sent
+# to is NOT taken from the environment: it is read from this machine's store in
+# both arms, so a token supplied this way still goes only where this machine was
+# set up to send it.
+# The pin names an id that is not a project id. Re-running the installer against
+# that pin refuses it too, so the one remedy that works is a fresh pin.
+halfcycle_bad_id_message() {
+  echo "halfcycle: $PROJECT_ROOT/.halfcycle/bundle.json names an engagement id that is not a Halfcycle project id," >&2
+  echo "halfcycle: so no credential was read. Delete that file and run \\"npx halfcycle\\" again: this repository" >&2
+  echo "halfcycle: is then set up as a new Halfcycle project." >&2
+}
+
 TOKEN=\${HALFCYCLE_TOKEN:-}
+MCP_URL=""
 
-if [ -z "$TOKEN" ]; then
+if [ -n "$TOKEN" ]; then
+  if halfcycle_env_file "$PROJECT_ROOT"; then
+    halfcycle_store_value "$HALFCYCLE_ENV_FILE" HALFCYCLE_MCP_URL
+    MCP_URL=$HC_VALUE
+  fi
+else
   if ! halfcycle_env_file "$PROJECT_ROOT"; then
     case $HALFCYCLE_ENV_PROBLEM in
       no-pin)
@@ -1557,6 +2009,8 @@ if [ -z "$TOKEN" ]; then
       no-id)
         echo "halfcycle: $PROJECT_ROOT/.halfcycle/bundle.json names no engagement id." >&2
         echo "halfcycle: run \\"npx halfcycle\\" here to rewrite it." >&2 ;;
+      bad-id)
+        halfcycle_bad_id_message ;;
       no-home)
         echo "halfcycle: HOME is not set, so the credential store cannot be located." >&2 ;;
       *)
@@ -1579,42 +2033,48 @@ if [ -z "$TOKEN" ]; then
   fi
   ENV_FILE="$HALFCYCLE_ENV_FILE"
 
-  # Last assignment wins, matching the shell's own \`.\` semantics. An optional
-  # leading \`export \` is tolerated because a hand-edited store may use one.
-  LINE=$(grep '^[[:space:]]*\\(export[[:space:]][[:space:]]*\\)\\{0,1\\}HALFCYCLE_TOKEN=' "$ENV_FILE" | tail -n 1)
-  TOKEN=\${LINE#*HALFCYCLE_TOKEN=}
-  TOKEN=$(printf '%s' "$TOKEN" | tr -d '\\r')
-
-  # Strip one layer of matching quotes. The store is WRITTEN single-quoted (both
-  # writers use the same shq: this installer and Studio's provider), because
-  # guard-runner.sh SOURCES the same file and an unquoted value carrying a space
-  # would execute its own remainder. This reader greps rather than sources, so it
-  # has to undo the quoting itself \u2014 and it must land on the same value the
-  # sourcing consumer gets, or one file has two answers.
-  case $TOKEN in
-    '"'*'"') TOKEN=\${TOKEN#'"'}; TOKEN=\${TOKEN%'"'} ;;
-    "'"*"'")
-      TOKEN=\${TOKEN#"'"}; TOKEN=\${TOKEN%"'"}
-      # \u2026and undo shq's embedded-quote escape, '\\'' -> '. The backslash is matched
-      # through a BRACKET EXPRESSION on purpose. MEASURED, on GNU sed 4.9 (Linux,
-      # the CI platform) and BSD sed (macOS), feeding each the script from a file so
-      # no shell quoting is in the way:
-      #
-      #   s/'[\\]''/'/g   a'\\''b -> a'b     both      <- shipped
-      #   s/'\\''/'/g     a'\\''b -> a'\\''b   both      <- matches NOTHING, exit 0
-      #
-      # A bare \\' in a BRE is undefined by POSIX, and the obvious pattern therefore
-      # does not fail loudly \u2014 it silently substitutes nothing, on BOTH platforms,
-      # and the token then travels with four stray characters in it. The bracket
-      # expression makes the backslash literal by a construction POSIX does define.
-      TOKEN=$(printf '%s' "$TOKEN" | sed "s/'[\\]''/'/g") ;;
-  esac
-
+  halfcycle_store_value "$ENV_FILE" HALFCYCLE_TOKEN
+  TOKEN=$HC_VALUE
   if [ -z "$TOKEN" ]; then
     echo "halfcycle: HALFCYCLE_TOKEN is absent or empty in $ENV_FILE." >&2
     echo "halfcycle: run \\"npx halfcycle\\" in this repository to rewrite this machine's credential." >&2
     exit 1
   fi
+  halfcycle_store_value "$ENV_FILE" HALFCYCLE_MCP_URL
+  MCP_URL=$HC_VALUE
+fi
+
+# THE TOKEN GOES ONLY TO THIS MACHINE'S HALFCYCLE SERVER. .mcp.json is a tracked
+# file: anyone who can land a commit can change the server's url, and this script
+# would then hand the credential to whatever it names. Claude Code tells the helper
+# which url it is about to connect to (CLAUDE_CODE_MCP_SERVER_URL); the server this
+# machine was set up against is recorded OUTSIDE the repository, beside the
+# credential. The two must share scheme, host and port, or nothing is printed.
+# No url at all is a refusal too: sending the credential without knowing where it
+# is going is the thing this check exists to stop.
+REQUESTED=\${CLAUDE_CODE_MCP_SERVER_URL:-}
+if [ -z "$REQUESTED" ]; then
+  echo "halfcycle: Claude Code did not say which server it is connecting to, so the Halfcycle credential was not sent." >&2
+  echo "halfcycle: update Claude Code, then reconnect." >&2
+  exit 1
+fi
+if [ -z "$MCP_URL" ] && [ "\${HALFCYCLE_ENV_PROBLEM:-}" = "bad-id" ]; then
+  halfcycle_bad_id_message
+  exit 1
+fi
+if [ -z "$MCP_URL" ]; then
+  echo "halfcycle: this machine has no Halfcycle server address recorded for this repository, so the credential was not sent." >&2
+  echo "halfcycle: run \\"npx halfcycle\\" in this repository on this machine to record it." >&2
+  exit 1
+fi
+WANT=$(halfcycle_origin "$MCP_URL")
+GOT=$(halfcycle_origin "$REQUESTED")
+if [ -z "$WANT" ] || [ "$GOT" != "$WANT" ]; then
+  SHOWN=$(printf '%s' "$REQUESTED" | tr -cd '[:graph:]' | cut -c1-200)
+  echo "halfcycle: .mcp.json asks for this repository's Halfcycle credential to be sent to $SHOWN," >&2
+  echo "halfcycle: which is not this machine's Halfcycle server (\${WANT:-none recorded}). The credential was NOT sent." >&2
+  echo "halfcycle: if nobody meant to change .mcp.json, treat that change as suspect; \\"npx halfcycle\\" restores the entry." >&2
+  exit 1
 fi
 
 # JSON-escape: backslash first, then double quote. A token carrying either would
@@ -1630,7 +2090,7 @@ function generateMcpRegistration(existing, mcpOrigin) {
   if (existing !== null) {
     const parsed = JSON.parse(existing);
     if (parsed !== null && typeof parsed === "object") {
-      base = { mcpServers: {}, ...parsed };
+      base = { ...parsed };
     }
   }
   if (typeof base.mcpServers !== "object" || base.mcpServers === null) {
@@ -1644,13 +2104,33 @@ function generateMcpRegistration(existing, mcpOrigin) {
   return JSON.stringify(base, null, 2) + "\n";
 }
 var REQUIRED_GITIGNORE_ENTRIES = [".halfcycle/state.json", `${ZONE_B_DIR}/`];
+var GITIGNORE_HEADER = "# Halfcycle \u2014 machine-local secrets/state and Zone-B (never push to client remote)";
+function adoptOlderGitignoreBlock(before) {
+  const claimable = /* @__PURE__ */ new Set([...REQUIRED_GITIGNORE_ENTRIES, LEGACY_ENV_LOCAL_REL]);
+  const claimed = [];
+  let underHeader = false;
+  const lines = before.split("\n");
+  for (const [i, line] of lines.entries()) {
+    if (line === GITIGNORE_HEADER) {
+      if (i > 0 && lines[i - 1] === "")
+        claimed.push("");
+      claimed.push(line);
+      underHeader = true;
+    } else if (line.trim() === "") {
+      underHeader = false;
+    } else if (underHeader && claimable.has(line)) {
+      claimed.push(line);
+    }
+  }
+  return claimed.length > 0 ? claimed.join("\n") + "\n" : "";
+}
 function gitignoreCovers(content) {
   const lines = new Set(content.split("\n").map((l) => l.trim()));
   return REQUIRED_GITIGNORE_ENTRIES.every((entry) => lines.has(entry));
 }
 function reconcileGitignore(targetRepo) {
-  const gitignorePath = join5(targetRepo, ".gitignore");
-  const header = "# Halfcycle \u2014 machine-local secrets/state and Zone-B (never push to client remote)";
+  const gitignorePath = join5(targetRepo, GITIGNORE_REL);
+  const header = GITIGNORE_HEADER;
   try {
     if (!existsSync3(gitignorePath)) {
       const body = [header, ...REQUIRED_GITIGNORE_ENTRIES].join("\n") + "\n";
@@ -1695,7 +2175,7 @@ function writeBundlePin(targetRepoRoot, version, engagementId, engagementType, a
     installedAt,
     ...carried !== void 0 ? { accountId: carried } : {}
   };
-  const pinPath = join5(targetRepoRoot, ".halfcycle", "bundle.json");
+  const pinPath = join5(targetRepoRoot, BUNDLE_PIN_REL);
   writeAllowlisted(pinPath, targetRepoRoot, JSON.stringify(pin, null, 2) + "\n", writtenPaths);
 }
 function writeCrewRoster(targetRepoRoot, report) {
@@ -1705,11 +2185,11 @@ function writeCrewRoster(targetRepoRoot, report) {
   };
   const rendered = `${JSON.stringify(doc, null, 2)}
 `;
-  const crewPath = join5(targetRepoRoot, ".halfcycle", "crew.json");
-  recordOwned(report, crewPath, targetRepoRoot, rendered, ".halfcycle/crew.json");
+  const crewPath = join5(targetRepoRoot, CREW_ROSTER_REL);
+  return recordOwned(report, crewPath, targetRepoRoot, rendered, CREW_ROSTER_REL);
 }
 function readBundlePin(targetRepoRoot) {
-  const pinPath = join5(targetRepoRoot, ".halfcycle", "bundle.json");
+  const pinPath = join5(targetRepoRoot, BUNDLE_PIN_REL);
   if (!existsSync3(pinPath))
     return null;
   return JSON.parse(readFileSync4(pinPath, "utf-8"));
@@ -1733,7 +2213,7 @@ function checkDrift(targetRepoRoot) {
   return { drifted: installed !== current, installed, current };
 }
 function writeProjectIdentity(targetRepo) {
-  const path = join5(targetRepo, ".halfcycle", "project.json");
+  const path = join5(targetRepo, PROJECT_IDENTITY_REL);
   const { identity } = mintOrReadIdentity(targetRepo);
   const serialized = JSON.stringify(identity, null, 2) + "\n";
   if (existsSync3(path) && readFileSync4(path, "utf-8") === serialized)
@@ -1812,6 +2292,7 @@ function migrateLegacyEnvLocal(targetRepo, stored) {
 }
 async function install(options) {
   const { targetRepo, engagementId, engagementType, credential, home, accountId } = options;
+  assertEngagementId(engagementId);
   if (!existsSync3(targetRepo)) {
     throw new Error(`[bundle install] Target repo does not exist: ${targetRepo}`);
   }
@@ -1823,22 +2304,30 @@ async function install(options) {
     collidedPaths: [],
     replacedPaths: []
   };
-  copyManifestCommands(manifest, targetRepo, report);
-  const capturedDir = join5(targetRepo, "test", "fixtures", "captured");
-  const capturedManifest = join5(capturedDir, "manifest.json");
+  const writeSet = closedWriteSet();
+  const draft = startManifest(readPreviousManifest(targetRepo), (path) => writeSet.files.has(path), (path) => writeSet.dirs.has(path));
+  const dirsBefore = new Set([...writeSet.dirs].filter((dir) => existsSync3(join5(targetRepo, dir))));
+  copyManifestCommands(manifest, targetRepo, report, draft);
+  const capturedManifest = join5(targetRepo, CAPTURED_INDEX_REL);
+  const srcManifest = join5(BUNDLE_ROOT, "scaffolding", "test", "fixtures", "captured", "manifest.json");
   if (!existsSync3(capturedManifest)) {
-    const srcManifest = join5(BUNDLE_ROOT, "scaffolding", "test", "fixtures", "captured", "manifest.json");
     writeAllowlisted(capturedManifest, targetRepo, readFileSync4(srcManifest, "utf-8"), report.writtenPaths);
+    noteFile(draft, targetRepo, CAPTURED_INDEX_REL, "written");
   } else {
-    report.skippedPaths.push("test/fixtures/captured/manifest.json");
+    report.skippedPaths.push(CAPTURED_INDEX_REL);
+    if (readFileSync4(capturedManifest).equals(readFileSync4(srcManifest))) {
+      noteFile(draft, targetRepo, CAPTURED_INDEX_REL, "skipped");
+    }
   }
   const vendoredBinSrc = resolveVendoredBinary();
   const vendoredBinDest = join5(targetRepo, ".halfcycle", "bin", "bin.bundle.mjs");
-  recordOwned(report, vendoredBinDest, targetRepo, readFileSync4(vendoredBinSrc, "utf-8"), ".halfcycle/bin/bin.bundle.mjs");
-  const settingsPath = join5(targetRepo, ".claude", "settings.json");
+  const vendoredOutcome = recordOwned(report, vendoredBinDest, targetRepo, readFileSync4(vendoredBinSrc, "utf-8"), VENDORED_BIN_REL);
+  noteFile(draft, targetRepo, VENDORED_BIN_REL, vendoredOutcome);
+  const settingsPath = join5(targetRepo, SETTINGS_REL);
   const settingsPreexisted = existsSync3(settingsPath);
   const generatedSettings = JSON.parse(generateSettingsJson());
   const existingSettings = settingsPreexisted ? JSON.parse(readFileSync4(settingsPath, "utf-8")) : {};
+  recordSettingsMerge(draft, existingSettings, generatedSettings, settingsPreexisted);
   const mergedSettings = mergeSettings(existingSettings, generatedSettings);
   const mergedSettingsText = JSON.stringify(mergedSettings, null, 2) + "\n";
   mkdirSync3(dirname2(settingsPath), { recursive: true });
@@ -1852,16 +2341,33 @@ async function install(options) {
   ]) {
     const rel = `.claude/hooks/${name}`;
     const hookPath = join5(targetRepo, ".claude", "hooks", name);
-    recordOwnedGenerated(report, hookPath, targetRepo, content, OWNED_GENERATED_HEADERS[rel], rel);
+    const outcome = recordOwnedGenerated(report, hookPath, targetRepo, content, OWNED_GENERATED_HEADERS[rel], rel);
+    noteFile(draft, targetRepo, rel, outcome);
+  }
+  switch (removeLegacyCiStanza(targetRepo)) {
+    case "removed":
+      report.writtenPaths.push(".halfcycle/ci-stanza.yml (REMOVED \u2014 Halfcycle no longer generates this file)");
+      break;
+    case "kept-foreign":
+      report.skippedPaths.push(".halfcycle/ci-stanza.yml (KEPT \u2014 this file was not generated by Halfcycle, so it was left alone)");
+      break;
+    case "kept-uncommitted":
+      report.skippedPaths.push(".halfcycle/ci-stanza.yml (KEPT \u2014 this looks like a Halfcycle-generated file, but it is not a clean, committed copy in this repository, so it was left alone rather than risk losing an edit)");
+      break;
+    case "failed":
+      report.skippedPaths.push(".halfcycle/ci-stanza.yml (could not be removed \u2014 DELETE IT BY HAND: Halfcycle no longer uses this file)");
+      break;
+    case "absent":
+      break;
   }
-  const ciStanzaPath = join5(targetRepo, ".halfcycle", "ci-stanza.yml");
-  recordOwned(report, ciStanzaPath, targetRepo, generateCiStanza(), ".halfcycle/ci-stanza.yml");
   if (credential) {
     const helperPath = join5(targetRepo, MCP_HEADERS_HELPER_REL);
-    recordOwnedGenerated(report, helperPath, targetRepo, generateMcpHeadersHelper(), OWNED_GENERATED_HEADERS[MCP_HEADERS_HELPER_REL], MCP_HEADERS_HELPER_REL);
+    const helperOutcome = recordOwnedGenerated(report, helperPath, targetRepo, generateMcpHeadersHelper(), OWNED_GENERATED_HEADERS[MCP_HEADERS_HELPER_REL], MCP_HEADERS_HELPER_REL);
+    noteFile(draft, targetRepo, MCP_HEADERS_HELPER_REL, helperOutcome);
     const mcpPath = join5(targetRepo, MCP_REGISTRATION_REL);
     const existingMcp = existsSync3(mcpPath) ? readFileSync4(mcpPath, "utf-8") : null;
     const mcpContent = generateMcpRegistration(existingMcp, credential.mcpUrl);
+    recordMcpMerge(draft, existingMcp, mcpContent);
     if (existingMcp === null) {
       writeAllowlisted(mcpPath, targetRepo, mcpContent, report.writtenPaths);
     } else if (existingMcp !== mcpContent) {
@@ -1871,14 +2377,22 @@ async function install(options) {
     }
   } else {
     report.skippedPaths.push(`${MCP_REGISTRATION_REL} (no MCP origin \u2014 no credential supplied)`);
+    const mcpPath = join5(targetRepo, MCP_REGISTRATION_REL);
+    if (existsSync3(mcpPath))
+      recordMcpAdoptionOnly(draft, readFileSync4(mcpPath, "utf-8"));
   }
+  const gitignorePath = join5(targetRepo, GITIGNORE_REL);
+  const gitignoreBefore = existsSync3(gitignorePath) ? readFileSync4(gitignorePath, "utf-8") : null;
   const gitignoreOutcome = reconcileGitignore(targetRepo);
+  recordGitignoreReconcile(draft, gitignoreBefore, existsSync3(gitignorePath) ? readFileSync4(gitignorePath, "utf-8") : null);
   if (gitignoreOutcome === "failed") {
     report.skippedPaths.push(".gitignore (write failed \u2014 see credential refusal)");
   } else {
     record(report, gitignoreOutcome, ".gitignore");
   }
-  record(report, writeProjectIdentity(targetRepo), ".halfcycle/project.json");
+  const identityOutcome = writeProjectIdentity(targetRepo);
+  record(report, identityOutcome, PROJECT_IDENTITY_REL);
+  noteFile(draft, targetRepo, PROJECT_IDENTITY_REL, identityOutcome);
   const credentialPath = engagementEnvPath(engagementId, home);
   if (credential) {
     record(report, writeEngagementCredential(credential, engagementId, home), credentialPath);
@@ -1904,8 +2418,18 @@ async function install(options) {
       break;
   }
   writeBundlePin(targetRepo, manifest.version, engagementId, engagementType, accountId, report.writtenPaths);
-  writeCrewRoster(targetRepo, report);
+  noteFile(draft, targetRepo, BUNDLE_PIN_REL, "written");
+  noteFile(draft, targetRepo, CREW_ROSTER_REL, writeCrewRoster(targetRepo, report));
   const scanResult = runBootstrapScan(targetRepo);
+  if (existsSync3(join5(targetRepo, BOOTSTRAP_STATE_REL)))
+    recordPerMachineFile(draft, BOOTSTRAP_STATE_REL);
+  for (const dir of writeSet.dirs) {
+    if (!dirsBefore.has(dir) && existsSync3(join5(targetRepo, dir)))
+      recordCreatedDir(draft, dir);
+  }
+  const installManifest = finishManifest(draft);
+  assertManifestInWriteSet(installManifest, writeSet);
+  recordOwned(report, join5(targetRepo, INSTALL_MANIFEST_REL), targetRepo, serializeManifest(installManifest), INSTALL_MANIFEST_REL);
   return {
     version: manifest.version,
     writtenPaths: report.writtenPaths,
@@ -2096,7 +2620,7 @@ async function mintBoardEnterCode(baseUrl, sessionToken) {
 
 // dist/setup/manifest.js
 import { existsSync as existsSync4, lstatSync, mkdirSync as mkdirSync4, readFileSync as readFileSync5, statSync, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname3, join as join6, posix } from "node:path";
+import { dirname as dirname3, join as join6, posix as posix2 } from "node:path";
 var DECLARED_ROOT_FILES = ["CLAUDE.md", "AGENTS.md", "ENGAGEMENT.md"];
 var DECLARED_DIR_PREFIX = "docs";
 var RESERVED_METHOD_PATH = "docs/method";
@@ -2107,7 +2631,7 @@ function normalise(path) {
   const slashed = path.replace(/\\/g, "/");
   if (slashed.trim() === "")
     return "";
-  return posix.normalize(slashed).replace(/\/+$/, "");
+  return posix2.normalize(slashed).replace(/\/+$/, "");
 }
 function isUnder(candidate, prefix) {
   return candidate === prefix || candidate.startsWith(prefix + "/");
@@ -2557,11 +3081,11 @@ function projectSeedGuard(fired, includeExplanation) {
 
 // dist/build-record/sources.js
 import { readFileSync as readFileSync7, existsSync as existsSync6 } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import { join as join10 } from "node:path";
 
 // dist/build-record/close-record.js
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname4, join as join8 } from "node:path";
 var CLOSE_RECORD_FORMAT = "halfcycle-phase-close/v1";
@@ -2578,11 +3102,11 @@ function closeRecordPath(repoRoot, phase) {
 }
 function resolveCloseAtHead(repoRoot) {
   try {
-    const closeCommit = execFileSync2("git", ["-C", repoRoot, "rev-parse", "--short", "HEAD"], {
+    const closeCommit = execFileSync3("git", ["-C", repoRoot, "rev-parse", "--short", "HEAD"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
-    const closedDate = execFileSync2("git", ["-C", repoRoot, "show", "-s", "--format=%cs", "HEAD"], {
+    const closedDate = execFileSync3("git", ["-C", repoRoot, "show", "-s", "--format=%cs", "HEAD"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
@@ -2806,7 +3330,7 @@ function syntheticRunId(record2) {
     record2["runType"],
     record2["phase"]
   ].join("|");
-  const hex = createHash("sha256").update(`legacy-guard-eval-run:${key}`).digest("hex");
+  const hex = createHash3("sha256").update(`legacy-guard-eval-run:${key}`).digest("hex");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
 }
 function readGuardEvalLog(logDir, phaseId) {