@mstar-harness/cli 3.6.0-alpha.2 → 3.6.0-alpha.4

package/dist/mstar-harness.js

@@ -2415,6 +2415,7 @@ var require_picocolors2 = __commonJS((exports, module) => {
 
 // src/index.ts
 import { execFileSync as execFileSync10 } from "child_process";
+import { createHash, randomUUID as randomUUID3 } from "crypto";
 import fs8 from "fs";
 import path12 from "path";
 
@@ -8544,6 +8545,9 @@ function prReviewSeatPrompt(opts) {
   if (!isAbsolute9(worktreePath)) {
     throw new TypeError(`prReviewSeatPrompt: worktreePath must be an absolute path - got ${JSON.stringify(opts.worktreePath)}`);
   }
+  if (opts.diffFile !== undefined && opts.diffFile !== "" && !isAbsolute9(opts.diffFile)) {
+    throw new TypeError(`prReviewSeatPrompt: diffFile must be an absolute path - got ${JSON.stringify(opts.diffFile)}`);
+  }
   const slug = `${domain}-${seat}`;
   const lines = [];
   lines.push(`# PR review audit seat \u2014 Stage ${opts.stage}${opts.securitySeat === true ? " (security)" : ""}`);
@@ -8569,6 +8573,9 @@ function prReviewSeatPrompt(opts) {
   const sections = opts.stage === 1 ? tier === "quick" ? "Scoping, Evidence rules" : "Review pipeline, Worktree isolation, Scoping, Evidence rules" : "Merge class, Attack and vet, Evidence rules, Sizing & change shape";
   lines.push(`1. \`${prReviewRef}\` \u2014 read at least these sections: ${sections}.`);
   lines.push(`2. The review worktree: \`${worktreePath}\` \u2014 your ONLY working directory this session; read-only (no edits, no fixes, no stash, no commits, no posts).`);
+  if (opts.diffFile) {
+    lines.push(`- Read the pinned diff snapshot FIRST: \`${opts.diffFile}\` \u2014 it is the review's diff basis (already computed at setup); read it before opening files.`);
+  }
   if (opts.stage === 2) {
     lines.push(`3. \`${join15(skillRoot, "references", "finding-format.md")}\` \u2014 the template every finding follows.`);
     if (opts.securitySeat === true) {
@@ -10916,11 +10923,6 @@ import fs3 from "node:fs";
 import os2 from "node:os";
 import path5 from "node:path";
 
-// src/adapters/shared-install.ts
-import fs2 from "node:fs";
-import os from "node:os";
-import path4 from "node:path";
-
 // src/exec.ts
 import { execFileSync as execFileSync7 } from "node:child_process";
 function runCliCommand(command, opts = {}) {
@@ -10936,6 +10938,9 @@ function runCliCommand(command, opts = {}) {
 }
 
 // src/adapters/shared-install.ts
+import fs2 from "node:fs";
+import os from "node:os";
+import path4 from "node:path";
 var REPO_URL = "https://github.com/btspoony/mstar-harness.git";
 var PLUGIN_NAME = "morning-star-harness";
 var HARNESS_REPO_PATH = path4.join(os.homedir(), ".mstar", "harness");
@@ -11126,17 +11131,14 @@ function appendGitignore(projectRoot, entries, dryRun) {
 function appendHarnessProjectGitignore(projectRoot, dryRun) {
   return appendGitignore(projectRoot, HARNESS_PROCESS_GITIGNORE, dryRun);
 }
-function homeRelativeSourcePath(targetPath) {
-  const rel = path4.relative(os.homedir(), targetPath).split(path4.sep).join("/");
-  return rel.startsWith("..") ? targetPath : `./${rel}`;
-}
 
 // src/adapters/codex.ts
-var MARKETPLACE_NAME = "personal";
-var MARKETPLACE_DISPLAY_NAME = "Personal";
-var GLOBAL_MARKETPLACE_PATH = path5.join(os2.homedir(), ".agents", "plugins", "marketplace.json");
-var PLUGIN_CATEGORY = "Productivity";
-var CODEX_PLUGIN_LINK = ".codex/plugins/mstar-harness";
+var CODEX_BIN = "codex";
+var CODEX_LOCAL_TIMEOUT_MS = 1e4;
+var CODEX_MARKETPLACE_TIMEOUT_MS = 300000;
+var MARKETPLACE_GIT_SOURCE = "btspoony/mstar-harness";
+var MARKETPLACE_NAME = "mstar-repo";
+var CODEX_INSTALL_HINT = "Install the Codex CLI (https://github.com/openai/codex), e.g. `npm install -g @openai/codex`, then re-run init.";
 var CODEX_AGENT_NAMES = [
   "product-manager",
   "architect",
@@ -11159,11 +11161,50 @@ var CODEX_PROJECT_COMMAND_NAMES = [
   "amazing-pr-review"
 ];
 var GLOBAL_ITERATION_SKILLS_WARNING = "Codex project-scoped commands (iteration-start / iteration-drive / iteration-loop / codebase-audit / amazing-pr-review) are installed as project-local skills under .agents/skills/ only. Global install skips them to avoid polluting other code agents. Re-run with --scope project to enable.";
-function globalMarketplacePath() {
-  return GLOBAL_MARKETPLACE_PATH;
+function runCodex(args, dryRun, timeoutMs) {
+  return runCliCommand([CODEX_BIN, ...args], { dryRun, timeoutMs, env: process.env });
 }
-function projectMarketplacePath() {
-  return path5.join(resolveProjectRoot2(), ".agents", "plugins", "marketplace.json");
+function codexAvailable() {
+  try {
+    runCodex(["--version"], false, CODEX_LOCAL_TIMEOUT_MS);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function configuredMarketplaceNames(dryRun) {
+  if (dryRun)
+    return [];
+  const dump = runCodex(["plugin", "marketplace", "list", "--json"], false, CODEX_LOCAL_TIMEOUT_MS);
+  const parsed = JSON.parse(dump);
+  const list = Array.isArray(parsed.marketplaces) ? parsed.marketplaces : [];
+  return list.map((entry) => entry && typeof entry.name === "string" ? entry.name : "").filter((name) => name !== "");
+}
+function installedPluginIds(dryRun) {
+  if (dryRun)
+    return [];
+  const dump = runCodex(["plugin", "list", "--json"], false, CODEX_LOCAL_TIMEOUT_MS);
+  const parsed = JSON.parse(dump);
+  const list = Array.isArray(parsed.installed) ? parsed.installed : [];
+  return list.map((entry) => entry && typeof entry.pluginId === "string" ? entry.pluginId : "").filter((pluginId) => pluginId !== "");
+}
+function legacyPersonalMarketplaceNote() {
+  const legacyPath = path5.join(os2.homedir(), ".agents", "plugins", "marketplace.json");
+  let raw;
+  try {
+    raw = fs3.readFileSync(legacyPath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const plugins = Array.isArray(parsed.plugins) ? parsed.plugins : [];
+    const hasMstar = plugins.some((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry) && ("name" in entry) && entry.name === PLUGIN_NAME);
+    if (hasMstar) {
+      return `Legacy personal marketplace entry found at ${legacyPath} \u2014 the ${PLUGIN_NAME} plugin now installs from the repo marketplace (${MARKETPLACE_GIT_SOURCE}). Remove the entry, then install: codex plugin add ${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+    }
+  } catch {}
+  return null;
 }
 function agentSourcePath(agentName) {
   return path5.join(HARNESS_REPO_PATH, "codex", "agents", `${agentName}.toml`);
@@ -11174,76 +11215,6 @@ function globalAgentLinkPath(agentName) {
 function projectAgentLinkPath(agentName) {
   return path5.join(resolveProjectRoot2(), ".codex", "agents", `${agentName}.toml`);
 }
-function mstarEntry(scope) {
-  const sourcePath = scope === "global" ? homeRelativeSourcePath(HARNESS_REPO_PATH) : `./${CODEX_PLUGIN_LINK}`;
-  return {
-    name: PLUGIN_NAME,
-    source: {
-      source: "local",
-      path: sourcePath
-    },
-    policy: {
-      installation: "AVAILABLE",
-      authentication: "ON_INSTALL"
-    },
-    category: PLUGIN_CATEGORY
-  };
-}
-function normalizeMarketplace(raw) {
-  const next = ensureObject(raw);
-  next.name = MARKETPLACE_NAME;
-  const iface = ensureObject(next.interface);
-  if (typeof iface.displayName !== "string" || !iface.displayName.trim()) {
-    iface.displayName = MARKETPLACE_DISPLAY_NAME;
-  }
-  next.interface = iface;
-  if (!Array.isArray(next.plugins)) {
-    next.plugins = [];
-  }
-  return next;
-}
-function upsertEntry(raw, scope) {
-  const next = normalizeMarketplace(raw);
-  const plugins = next.plugins.filter((entry) => {
-    return !(entry && typeof entry === "object" && !Array.isArray(entry) && entry.name === PLUGIN_NAME);
-  });
-  plugins.push(mstarEntry(scope));
-  next.plugins = plugins;
-  return next;
-}
-function findEntry(raw) {
-  const plugins = Array.isArray(raw.plugins) ? raw.plugins : [];
-  return plugins.find((entry) => {
-    return entry && typeof entry === "object" && !Array.isArray(entry) && entry.name === PLUGIN_NAME;
-  });
-}
-function validateEntryShape(entry, scope, marketplacePath) {
-  const errors2 = [];
-  if (!entry) {
-    errors2.push(`Missing ${PLUGIN_NAME} entry in ${marketplacePath}.`);
-    return errors2;
-  }
-  const source = ensureObject(entry.source);
-  const expectedSourcePath = mstarEntry(scope).source.path;
-  if (source.source !== "local")
-    errors2.push("Codex marketplace entry source.source must be `local`.");
-  if (source.path !== expectedSourcePath) {
-    errors2.push(`Codex marketplace entry source.path must be ${expectedSourcePath}.`);
-  }
-  const policy = ensureObject(entry.policy);
-  if (policy.installation !== "AVAILABLE")
-    errors2.push("Codex marketplace entry policy.installation must be AVAILABLE.");
-  if (policy.authentication !== "ON_INSTALL")
-    errors2.push("Codex marketplace entry policy.authentication must be ON_INSTALL.");
-  if (entry.category !== PLUGIN_CATEGORY)
-    errors2.push(`Codex marketplace entry category must be ${PLUGIN_CATEGORY}.`);
-  return errors2;
-}
-function marketplacePath(scope) {
-  if (scope === "global")
-    return globalMarketplacePath();
-  return projectMarketplacePath();
-}
 function ensureAgentLinks(scope, dryRun) {
   const notes = [];
   for (const agentName of CODEX_AGENT_NAMES) {
@@ -11301,59 +11272,78 @@ function validateIterationSkillLinks() {
   return errors2;
 }
 function runInit(scope, dryRun) {
-  const pathToMarketplace = marketplacePath(scope);
-  const current = readJson2(pathToMarketplace);
-  const next = upsertEntry(current, scope);
-  const existingEntry = findEntry(current);
-  const notes = ensureLocalHarnessRepo(dryRun);
+  const notes = [];
+  notes.push(...ensureLocalHarnessRepo(dryRun));
+  const marketplaceArgs = ["plugin", "marketplace", "add", REPO_URL, "--ref", "main"];
+  if (dryRun) {
+    notes.push(`Would run: ${CODEX_BIN} ${marketplaceArgs.join(" ")}`);
+  } else {
+    if (!codexAvailable()) {
+      throw new Error(`${CODEX_BIN} CLI not found on PATH. ${CODEX_INSTALL_HINT}`);
+    }
+    try {
+      const already = configuredMarketplaceNames(false).includes(MARKETPLACE_NAME);
+      if (already) {
+        notes.push(`Marketplace ${MARKETPLACE_NAME} already configured.`);
+      } else {
+        runCodex(marketplaceArgs, false, CODEX_MARKETPLACE_TIMEOUT_MS);
+        notes.push(`Added marketplace ${MARKETPLACE_NAME} from ${REPO_URL} (ref main).`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to add marketplace via ${CODEX_BIN}: ${message}`);
+    }
+    notes.push(`Next: codex plugin add ${PLUGIN_NAME}@${MARKETPLACE_NAME}`);
+  }
   if (scope === "project") {
     const projectRoot = resolveProjectRoot2();
-    notes.push(ensureSymlink(HARNESS_REPO_PATH, path5.join(projectRoot, CODEX_PLUGIN_LINK), dryRun));
-    notes.push(...appendGitignore(projectRoot, [CODEX_PLUGIN_LINK, ".codex/agents/*.toml"], dryRun));
+    notes.push(...appendGitignore(projectRoot, [".codex/agents/*.toml"], dryRun));
     notes.push(...appendHarnessProjectGitignore(projectRoot, dryRun));
     notes.push(...ensureIterationSkillLinks(dryRun));
   } else {
     notes.push(GLOBAL_ITERATION_SKILLS_WARNING);
   }
   notes.push(...ensureAgentLinks(scope, dryRun));
-  if (!dryRun)
-    writeJson2(pathToMarketplace, next);
-  notes.push(existingEntry ? `Updated ${PLUGIN_NAME} local marketplace entry.` : `Added ${PLUGIN_NAME} local marketplace entry.`);
-  notes.push(`Source path: ${mstarEntry(scope).source.path}`);
-  notes.push(`Install after init: codex plugin add ${PLUGIN_NAME} --marketplace ${MARKETPLACE_NAME}`);
   return {
-    location: pathToMarketplace,
+    location: `${CODEX_BIN} marketplaces (config.toml)`,
     notes
   };
 }
 function runDoctor(scope) {
-  const pathToMarketplace = marketplacePath(scope);
   const errors2 = validateLocalHarnessRepo();
-  if (!fs3.existsSync(pathToMarketplace)) {
-    return { location: pathToMarketplace, errors: [...errors2, `Missing Codex marketplace: ${pathToMarketplace}`] };
+  const notes = [];
+  const legacyNote = legacyPersonalMarketplaceNote();
+  if (legacyNote)
+    notes.push(legacyNote);
+  if (!codexAvailable()) {
+    errors2.push(`${CODEX_BIN} CLI not found on PATH. ${CODEX_INSTALL_HINT}`);
+    return { location: `${CODEX_BIN} marketplaces (config.toml)`, errors: errors2, notes };
   }
-  const marketplace = readJson2(pathToMarketplace);
-  if (marketplace.name !== MARKETPLACE_NAME) {
-    errors2.push(`Codex personal marketplace name must be ${MARKETPLACE_NAME}.`);
+  try {
+    const marketplaces = configuredMarketplaceNames(false);
+    if (!marketplaces.includes(MARKETPLACE_NAME)) {
+      errors2.push(`Marketplace ${MARKETPLACE_NAME} not configured (run init, or: ${CODEX_BIN} plugin marketplace add ${REPO_URL} --ref main).`);
+    }
+    const installed = installedPluginIds(false);
+    const pluginId = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+    if (marketplaces.includes(MARKETPLACE_NAME) && !installed.includes(pluginId)) {
+      notes.push(`Plugin not installed yet: ${CODEX_BIN} plugin add ${pluginId}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    errors2.push(`Could not query ${CODEX_BIN} plugin marketplace list: ${message}`);
   }
-  errors2.push(...validateEntryShape(findEntry(marketplace), scope, pathToMarketplace));
   if (scope === "project") {
     const projectRoot = resolveProjectRoot2();
-    errors2.push(...validateSymlink(HARNESS_REPO_PATH, path5.join(projectRoot, CODEX_PLUGIN_LINK)));
     const gitignorePath = path5.join(projectRoot, ".gitignore");
     const gitignore = fs3.existsSync(gitignorePath) ? fs3.readFileSync(gitignorePath, "utf8") : "";
-    const lines = gitignore.split(/\r?\n/);
-    if (!lines.includes(CODEX_PLUGIN_LINK))
-      errors2.push(`Missing .gitignore entry: ${CODEX_PLUGIN_LINK}`);
-    if (!lines.includes(".codex/agents/*.toml"))
-      errors2.push("Missing .gitignore entry: .codex/agents/*.toml");
     for (const entry of missingHarnessProcessGitignoreEntries(gitignore)) {
       errors2.push(`Missing .gitignore entry: ${entry}`);
     }
     errors2.push(...validateIterationSkillLinks());
   }
   errors2.push(...validateAgentLinks(scope));
-  return { location: pathToMarketplace, errors: errors2 };
+  return { location: `${CODEX_BIN} marketplaces (config.toml)`, errors: errors2, notes };
 }
 var codexAdapter = {
   target: "codex",
@@ -11921,7 +11911,7 @@ var MARKETPLACE_ID = "mstar-local";
 var MARKETPLACE_NAME2 = "mstar-local";
 var MARKETPLACE_DESCRIPTION = "Morning Star harness marketplace (GitHub source).";
 var PLUGIN_DESCRIPTION = "Multi-agent code harness framework with unified skills for OpenCode, Cursor, Codex, Kimi Code, and ZCode.";
-var PLUGIN_CATEGORY2 = "Productivity";
+var PLUGIN_CATEGORY = "Productivity";
 var GITHUB_REPO = "btspoony/mstar-harness";
 var GITHUB_REF = "main";
 var ZCODE_PLUGIN_MARKER = ".zcode-plugin/plugin.json";
@@ -11941,7 +11931,7 @@ function marketplacePluginEntry() {
     source: { ...GITHUB_SOURCE },
     description: PLUGIN_DESCRIPTION,
     version: readHarnessVersion(),
-    category: PLUGIN_CATEGORY2
+    category: PLUGIN_CATEGORY
   };
 }
 function knownMarketplaceEntry(existing) {
@@ -14153,6 +14143,9 @@ prReviewCommand.command("validate-report").description("Validate a saved local P
 function gitSync(args, cwd) {
   return execFileSync10("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
 }
+function gitRaw(args, cwd) {
+  return execFileSync10("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_CAPTURE_MAX_BYTES });
+}
 function ghSync(args, input) {
   return execFileSync10("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...input !== undefined ? { input } : {} }).trim();
 }
@@ -14178,7 +14171,11 @@ function refResolves(ref, cwd) {
 }
 function probeChangesetEmpty(diffCmdArgs, cwd, worktreePath) {
   if (diffCmdArgs[0] === "__working_tree__") {
-    const dirty = gitIf(["diff"], worktreePath).length > 0 || gitIf(["diff", "--cached"], worktreePath).length > 0;
+    const diffOut = gitProbe(["diff"], worktreePath);
+    const cachedOut = gitProbe(["diff", "--cached"], worktreePath);
+    if (diffOut === null || cachedOut === null)
+      return false;
+    const dirty = diffOut.length > 0 || cachedOut.length > 0;
     if (dirty)
       return false;
     let untracked = "";
@@ -14195,17 +14192,26 @@ function probeChangesetEmpty(diffCmdArgs, cwd, worktreePath) {
     const sha = diffCmdArgs[1];
     const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
     const diffFrom = refResolves(`${sha}^`, worktreePath) ? `${sha}^` : EMPTY_TREE;
-    return gitIf(["diff", diffFrom, sha], worktreePath).trim().length === 0;
+    const probe2 = gitProbe(["diff", diffFrom, sha], worktreePath);
+    return probe2 === null ? false : probe2.trim().length === 0;
   }
-  return gitIf(diffCmdArgs, worktreePath).length === 0;
+  const probe = gitProbe(diffCmdArgs, worktreePath);
+  return probe === null ? false : probe.length === 0;
 }
 function gitIf(args, cwd) {
   try {
-    return execFileSync10("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return execFileSync10("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: GIT_CAPTURE_MAX_BYTES });
   } catch {
     return "";
   }
 }
+function gitProbe(args, cwd) {
+  try {
+    return execFileSync10("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: GIT_CAPTURE_MAX_BYTES });
+  } catch {
+    return null;
+  }
+}
 function probeChangesetEmptyPreworktree(mode, headSpec, cwd) {
   if (mode === "working-tree")
     return probeChangesetEmpty(["__working_tree__"], cwd, cwd);
@@ -14332,7 +14338,7 @@ function ghApi(apiPath, payload) {
     input: payload
   });
 }
-prReviewCommand.command("worktree-setup").description("Create the isolated review worktree per pr-review.md \xA7 Worktree isolation: resolves the real base, picks a " + "collision-free branch name, fetches with explicit refspecs, creates the worktree, computes the diff basis INSIDE it, " + "and records a sidecar json consumed by worktree-cleanup; prints {reviewBranch, worktreePath, base, mergeBase, diffCmd} " + "(input modes: --pr <n> | --branch <b> | --diff | --working-tree | --commit <sha>)").option("--pr <n>", "PR number input mode (pull/<n>/head via gh)").option("--branch <name>", "Bare remote-branch input mode").option("--diff", "Arbitrary diff input mode \u2014 no worktree, no refs").option("--working-tree", "Uncommitted working-tree input mode \u2014 no worktree, no refs").option("--commit <sha>", "Single-commit input mode").option("--path <dir>", "Worktree target directory (default: ../<repo-name>.review-pr<N> beside the repo)").action((options) => {
+prReviewCommand.command("worktree-setup").description("Create the isolated review worktree per pr-review.md \xA7 Worktree isolation: resolves the real base, picks a " + "collision-free branch name, fetches with explicit refspecs, creates the worktree, computes the diff basis INSIDE it, " + "and records a sidecar json consumed by worktree-cleanup; prints {reviewBranch, worktreePath, base, mergeBase, diffCmd, diffFile} " + "(input modes: --pr <n> | --branch <b> | --diff | --working-tree | --commit <sha>)").option("--pr <n>", "PR number input mode (pull/<n>/head via gh)").option("--branch <name>", "Bare remote-branch input mode").option("--diff", "Arbitrary diff input mode \u2014 no worktree, no refs").option("--working-tree", "Uncommitted working-tree input mode \u2014 no worktree, no refs").option("--commit <sha>", "Single-commit input mode").option("--path <dir>", "Worktree target directory (default: <repo>/.worktrees/review-<branch>)").action((options) => {
   try {
     const modesDeclared = [
       options.pr !== undefined,
@@ -14372,7 +14378,7 @@ prReviewCommand.command("worktree-setup").description("Create the isolated revie
         process.exitCode = 1;
         return;
       }
-      console.log(JSON.stringify({ reviewBranch: null, worktreePath: repoRoot, base: null, mergeBase: null, diffCmd: mode === "diff" ? "(provided changeset)" : "git diff + git diff --cached + ls-files --others" }, null, 2));
+      console.log(JSON.stringify({ reviewBranch: null, worktreePath: repoRoot, base: null, mergeBase: null, diffCmd: mode === "diff" ? "(provided changeset)" : "git diff + git diff --cached + ls-files --others", diffFile: null }, null, 2));
       return;
     }
     let prNumber = 0;
@@ -14422,7 +14428,21 @@ prReviewCommand.command("worktree-setup").description("Create the isolated revie
     const baseCandidate = mode === "pr" ? namePrNumber : Number(String(Math.abs([...headSpec].reduce((h, ch) => (h * 31 + ch.charCodeAt(0)) % 1000003, 7))));
     const reviewBranch = pickReviewBranchName(existing, baseCandidate === 0 ? 1 : baseCandidate, cliToday().replace(/-/g, ""));
     const branchSuffix = mode === "pr" ? "" : `-${headSpec.slice(0, 8)}`;
-    const worktreePath = path12.resolve(options.path ?? joinDirnameBeside(repoRoot, `.review-${reviewBranch}${branchSuffix}`));
+    const worktreePath = path12.resolve(options.path ?? path12.join(repoRoot, ".worktrees", `review-${reviewBranch}${branchSuffix}`));
+    if (options.path === undefined) {
+      fs8.mkdirSync(path12.join(repoRoot, ".worktrees"), { recursive: true });
+      if (gitIf(["check-ignore", ".worktrees/"], repoRoot) === "") {
+        const excludePath = path12.join(repoRoot, ".git", "info", "exclude");
+        const existing2 = fs8.existsSync(excludePath) ? fs8.readFileSync(excludePath, "utf8") : "";
+        if (!existing2.split(`
+`).some((line) => line.trim() === ".worktrees/")) {
+          fs8.appendFileSync(excludePath, `${existing2 === "" || existing2.endsWith(`
+`) ? "" : `
+`}.worktrees/
+`);
+        }
+      }
+    }
     const originUrl = gitIf(["remote", "get-url", "origin"], repoRoot);
     let fetched = true;
     try {
@@ -14438,7 +14458,11 @@ prReviewCommand.command("worktree-setup").description("Create the isolated revie
     } catch {
       fetched = false;
     }
-    const rollbackNewWorktree = (branchToDelete) => {
+    let wroteSnapshot = false;
+    let wroteSidecar = false;
+    let pendingSidecar;
+    let sidecarFd;
+    const cleanupOnFailure = (branchToDelete) => {
       try {
         if (fs8.existsSync(worktreePath))
           gitSync(["worktree", "remove", "--force", worktreePath], repoRoot);
@@ -14446,6 +14470,12 @@ prReviewCommand.command("worktree-setup").description("Create the isolated revie
         if (branchToDelete !== "" && !existing.has(branchToDelete)) {
           gitSync(["branch", "-D", branchToDelete], repoRoot);
         }
+        if (wroteSidecar && sidecarFd !== undefined) {
+          removeOwnedFreshSidecarFile(sidecarFd, worktreePath);
+          sidecarFd = undefined;
+        }
+        if (wroteSnapshot && pendingSidecar !== undefined)
+          removeOwnedSnapshotFile(worktreePath, pendingSidecar);
       } catch {}
     };
     const fetchedHeadResolves = mode === "pr" ? refResolves(reviewBranch, repoRoot) : mode === "branch" ? originUrl !== "" && refResolves(`origin/${options.branch}`, repoRoot) : mode === "commit" ? Boolean(gitIf(["rev-parse", "--verify", "--quiet", `${headSpec}^{commit}`], repoRoot).trim()) : refResolves(headSpec, repoRoot);
@@ -14478,48 +14508,222 @@ prReviewCommand.command("worktree-setup").description("Create the isolated revie
     const changesetEmpty = probeChangesetEmpty(diffArgs, worktreePath, worktreePath);
     const emptyGate = preflightChangeset(mode, { refsResolve: true, changesetEmpty });
     if (changesetEmpty) {
-      rollbackNewWorktree(mode === "pr" ? reviewBranch : "");
+      cleanupOnFailure(mode === "pr" ? reviewBranch : "");
     }
     if (!emptyGate.ok && emptyGate.violations.some((v) => v.code === "prreview.preflight.changeset-empty")) {
       printChecklist("pr-review worktree-setup preflight", emptyGate);
       process.exitCode = 1;
       return;
     }
-    const recordedBase = mode === "pr" || mode !== "commit" && !baseRef.startsWith("origin/") ? `origin/${baseRef}` : baseRef;
-    const sidecar = {
-      reviewBranch: mode === "pr" ? reviewBranch : "",
-      worktreePath,
-      base: recordedBase,
-      mergeBase,
-      diffCmd,
-      reportSaved: false,
-      createdAt: new Date().toISOString(),
-      repoRoot
+    const captureAndRecordSnapshot = () => {
+      const diffFile = prReviewArtifactPathFor(worktreePath, "diff");
+      const sidecarPath = prReviewArtifactPathFor(worktreePath, "json");
+      const snapshotParts = [];
+      if (mode === "commit") {
+        snapshotParts.push(Buffer.from(`# Review package: ${baseRef} (single commit)
+
+## Commits
+`), gitRaw(["log", "--oneline", "-1", headSpec], worktreePath), Buffer.from(`
+## Files changed
+`), gitRaw(["show", "--stat", headSpec], worktreePath), Buffer.from(`
+## Diff
+`), gitRaw(["show", "-U10", headSpec], worktreePath));
+      } else {
+        const range = diffArgs[1];
+        const [rangeBase, rangeHead] = range.split("...");
+        snapshotParts.push(Buffer.from(`# Review package: ${baseRef}..${headSpec}
+
+## Commits
+`), gitRaw(["log", "--oneline", `${rangeBase}..${rangeHead}`], worktreePath), Buffer.from(`
+## Files changed
+`), gitRaw(["diff", "--stat", range], worktreePath), Buffer.from(`
+## Diff
+`), gitRaw(["diff", "-U10", range], worktreePath));
+      }
+      const snapshot = Buffer.concat(snapshotParts);
+      const recordedBase = mode === "pr" || mode !== "commit" && !baseRef.startsWith("origin/") ? `origin/${baseRef}` : baseRef;
+      const sidecar2 = {
+        reviewBranch: mode === "pr" ? reviewBranch : "",
+        worktreePath,
+        base: recordedBase,
+        mergeBase,
+        diffCmd,
+        reportSaved: false,
+        createdAt: new Date().toISOString(),
+        repoRoot,
+        diffFile,
+        diffFileSha256: createHash("sha256").update(snapshot).digest("hex")
+      };
+      try {
+        sidecarFd = fs8.openSync(sidecarPath, "wx+");
+      } catch (error) {
+        if (error.code !== "EEXIST" && error.code !== "EISDIR")
+          throw error;
+        throw new Error(`cannot record setup sidecar at ${sidecarPath} - run mstar pr-review worktree-cleanup first (never cleaning a foreign review)`);
+      }
+      writeFdSync(sidecarFd, Buffer.from(JSON.stringify(sidecar2, null, 2), "utf8"));
+      wroteSidecar = true;
+      try {
+        fs8.writeFileSync(diffFile, snapshot, { flag: "wx" });
+      } catch (error) {
+        if (error.code !== "EEXIST" && error.code !== "EISDIR")
+          throw error;
+        throw new Error(`refusing to overwrite pre-existing non-snapshot path ${diffFile}`);
+      }
+      wroteSnapshot = true;
+      const snapshotStat = fs8.lstatSync(diffFile);
+      sidecar2.diffFileDev = snapshotStat.dev;
+      sidecar2.diffFileIno = String(snapshotStat.ino);
+      sidecar2.diffFileMtimeMs = snapshotStat.mtimeMs;
+      pendingSidecar = sidecar2;
+      fs8.ftruncateSync(sidecarFd, 0);
+      writeFdSync(sidecarFd, Buffer.from(JSON.stringify(sidecar2, null, 2), "utf8"));
+      fs8.closeSync(sidecarFd);
+      sidecarFd = undefined;
+      return sidecar2;
     };
-    fs8.writeFileSync(sidecarPathFor(worktreePath), JSON.stringify(sidecar, null, 2));
+    let sidecar;
+    try {
+      sidecar = captureAndRecordSnapshot();
+    } catch (error) {
+      cleanupOnFailure(mode === "pr" ? reviewBranch : "");
+      throw error;
+    }
     console.log(JSON.stringify({
       reviewBranch: sidecar.reviewBranch === "" ? null : sidecar.reviewBranch,
       worktreePath: sidecar.worktreePath,
       base: sidecar.base,
       mergeBase: sidecar.mergeBase === "" ? null : sidecar.mergeBase,
-      diffCmd: sidecar.diffCmd
+      diffCmd: sidecar.diffCmd,
+      diffFile: sidecar.diffFile
     }, null, 2));
   } catch (error) {
     failScript(error, "pr-review worktree-setup");
   }
 });
-function sidecarPathFor(worktreePath) {
+function prReviewArtifactPathFor(worktreePath, suffix) {
   const parent = path12.dirname(path12.resolve(worktreePath));
   const name = path12.basename(path12.resolve(worktreePath));
-  return path12.join(parent, `.${name}.prreview.json`);
+  return path12.join(parent, `.${name}.prreview.${suffix}`);
+}
+function writeFdSync(fd, buf) {
+  let written = 0;
+  while (written < buf.length)
+    written += fs8.writeSync(fd, buf, written, buf.length - written, written);
+}
+function removeOwnedSnapshotFile(worktreePath, sidecar) {
+  const snapshotPath = prReviewArtifactPathFor(worktreePath, "diff");
+  let fd;
+  try {
+    fd = fs8.openSync(snapshotPath, "r");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    console.error(import_picocolors2.default.yellow(`worktree-cleanup: snapshot at ${snapshotPath} left in place (cannot open: ${error.message})`));
+    return;
+  }
+  try {
+    const st = fs8.fstatSync(fd);
+    if (!st.isFile())
+      return;
+    const recordedIno = sidecar.diffFileIno;
+    const recordedDev = sidecar.diffFileDev;
+    const recordedMtimeMs = sidecar.diffFileMtimeMs;
+    const owned = typeof recordedIno === "string" && recordedIno !== "" && typeof recordedDev === "number" && Number.isFinite(recordedDev) && typeof recordedMtimeMs === "number" && Number.isFinite(recordedMtimeMs) && String(st.ino) === recordedIno && st.dev === recordedDev && st.mtimeMs === recordedMtimeMs;
+    if (!owned) {
+      console.error(import_picocolors2.default.yellow(`worktree-cleanup: snapshot at ${snapshotPath} left in place (file identity does not match the recorded snapshot)`));
+      return;
+    }
+    if (st.nlink !== 1) {
+      console.error(import_picocolors2.default.yellow(`worktree-cleanup: snapshot at ${snapshotPath} left in place (link count does not match the recorded snapshot)`));
+      return;
+    }
+    const tmp = `${snapshotPath}.cleanup.${process.pid}.${randomUUID3()}`;
+    try {
+      fs8.renameSync(snapshotPath, tmp);
+    } catch (error) {
+      console.error(import_picocolors2.default.yellow(`worktree-cleanup: snapshot at ${snapshotPath} left in place (cannot detach: ${error.message})`));
+      return;
+    }
+    const st2 = fs8.fstatSync(fd);
+    let tmpStat;
+    try {
+      tmpStat = fs8.lstatSync(tmp);
+    } catch {
+      tmpStat = undefined;
+    }
+    if (tmpStat !== undefined && tmpStat.ino === st2.ino && tmpStat.dev === st2.dev && st2.nlink === 1 && tmpStat.nlink === 1) {
+      fs8.unlinkSync(tmp);
+      const st3 = fs8.fstatSync(fd);
+      if (st3.nlink !== 0) {
+        console.error(import_picocolors2.default.yellow(`worktree-cleanup: unlink at ${tmp} detached a pathname replacement, not the verified snapshot inode (${snapshotPath} still holds ${st3.nlink} link(s)) - the replacement is gone, the verified snapshot was NOT deleted`));
+      }
+    } else {
+      try {
+        fs8.linkSync(tmp, snapshotPath);
+        fs8.unlinkSync(tmp);
+      } catch (error) {
+        if (error.code === "EEXIST") {
+          console.error(import_picocolors2.default.yellow(`worktree-cleanup: snapshot replacement left at ${tmp} (snapshot path was recreated concurrently)`));
+        } else {
+          console.error(import_picocolors2.default.yellow(`worktree-cleanup: snapshot replacement left at ${tmp} (restore failed: ${error.message})`));
+        }
+      }
+    }
+  } finally {
+    fs8.closeSync(fd);
+  }
 }
-function joinDirnameBeside(repoRoot, leaf) {
-  return path12.join(path12.dirname(path12.resolve(repoRoot)), leaf);
+function removeOwnedFreshSidecarFile(sidecarFd, worktreePath) {
+  const sidecarPath = prReviewArtifactPathFor(worktreePath, "json");
+  try {
+    const st = fs8.fstatSync(sidecarFd);
+    if (!st.isFile() || st.nlink !== 1) {
+      console.error(import_picocolors2.default.yellow(`worktree-setup rollback: sidecar at ${sidecarPath} left in place (identity no longer held)`));
+      return;
+    }
+    const tmp = `${sidecarPath}.cleanup.${process.pid}.${randomUUID3()}`;
+    try {
+      fs8.renameSync(sidecarPath, tmp);
+    } catch (error) {
+      console.error(import_picocolors2.default.yellow(`worktree-setup rollback: sidecar at ${sidecarPath} left in place (cannot detach: ${error.message})`));
+      return;
+    }
+    const st2 = fs8.fstatSync(sidecarFd);
+    let tmpStat;
+    try {
+      tmpStat = fs8.lstatSync(tmp);
+    } catch {
+      tmpStat = undefined;
+    }
+    if (tmpStat !== undefined && tmpStat.ino === st2.ino && tmpStat.dev === st2.dev) {
+      fs8.unlinkSync(tmp);
+      const st3 = fs8.fstatSync(sidecarFd);
+      if (st3.nlink !== 0) {
+        console.error(import_picocolors2.default.yellow(`worktree-setup rollback: unlink at ${tmp} detached a pathname replacement, not the verified sidecar inode (${sidecarPath} still holds ${st3.nlink} link(s)) - the replacement is gone, the verified sidecar was NOT deleted`));
+      }
+    } else {
+      try {
+        fs8.linkSync(tmp, sidecarPath);
+        fs8.unlinkSync(tmp);
+      } catch (error) {
+        if (error.code === "EEXIST") {
+          console.error(import_picocolors2.default.yellow(`worktree-setup rollback: sidecar replacement left at ${tmp} (sidecar path was recreated concurrently)`));
+        } else {
+          console.error(import_picocolors2.default.yellow(`worktree-setup rollback: sidecar replacement left at ${tmp} (restore failed: ${error.message})`));
+        }
+      }
+    }
+  } finally {
+    try {
+      fs8.closeSync(sidecarFd);
+    } catch {}
+  }
 }
 prReviewCommand.command("worktree-cleanup").description("Remove the review worktree per pr-review.md \xA7 Worktree isolation cleanup: refuses unless --report-saved is given OR the " + "setup sidecar records report-saved; removes the worktree, prunes, and deletes EXACTLY the recorded review branch \u2014 a " + "--branch argument that disagrees with the sidecar is refused (never delete a foreign/pre-existing branch)").requiredOption("--path <dir>", "Worktree directory created by worktree-setup").requiredOption("--branch <name>", "The recorded review branch (must match the setup sidecar for PR mode)").option("--report-saved", "Assert the local report has been saved before removal").action((options) => {
   try {
     const worktreePath = path12.resolve(resolveCliPath(options.path));
-    const sidecarPath = sidecarPathFor(worktreePath);
+    const sidecarPath = prReviewArtifactPathFor(worktreePath, "json");
     if (!fs8.existsSync(sidecarPath)) {
       throw new Error(`no setup sidecar found at ${sidecarPath} - run pr-review worktree-setup first (foreign worktrees are never cleaned here)`);
     }
@@ -14551,6 +14755,7 @@ prReviewCommand.command("worktree-cleanup").description("Remove the review workt
       }
       gitSync(["branch", "-D", sidecar.reviewBranch], gitRoot);
     }
+    removeOwnedSnapshotFile(worktreePath, sidecar);
     fs8.rmSync(sidecarPath, { force: true });
     console.log(import_picocolors2.default.green(`worktree-cleanup: removed ${worktreePath}${sidecar.reviewBranch !== "" ? ` + deleted ${sidecar.reviewBranch}` : " (no local branch to delete)"}`));
   } catch (error) {
@@ -14600,7 +14805,7 @@ function measureLargestTouchedTotal(diffOutput, headRef, cwd) {
   }
   return maxTotal;
 }
-prReviewCommand.command("seat-prompt").description("Generate the read-only audit-seat prompt per pr-review.md \xA7 Seat prompts (Hard Rules 4/5 verbatim, payload-return contract, " + "no-verdict/no-post clauses, slug <domain>-<seat>, Merge-class instruction on stage 2); prints the prompt").requiredOption("--stage <1|2>", "Pipeline stage (1 = collect, 2 = domain/security)").requiredOption("--domain <d>", "Review domain for this seat").requiredOption("--seat <id>", "Seat id (slug becomes <domain>-<seat>)").requiredOption("--worktree <path>", "Absolute review worktree path").option("--security", "Mark this seat as the security-lens seat (stage 2)").option("--skill-root <dir>", "Skill root containing references/pr-review.md (default: resolved skills/mstar-audit)").option("--recon <facts...>", "Recon facts (variadic: --recon fact1 fact2 ...)").option("--tier <quick|default|deep>", "Prompt tier (SP-A): quick shrinks read-first + folds the security lens in-seat; deep adds cross-domain security seat + stage-as-wave (default: default)").action((options) => {
+prReviewCommand.command("seat-prompt").description("Generate the read-only audit-seat prompt per pr-review.md \xA7 Seat prompts (Hard Rules 4/5 verbatim, payload-return contract, " + "no-verdict/no-post clauses, slug <domain>-<seat>, Merge-class instruction on stage 2); prints the prompt").requiredOption("--stage <1|2>", "Pipeline stage (1 = collect, 2 = domain/security)").requiredOption("--domain <d>", "Review domain for this seat").requiredOption("--seat <id>", "Seat id (slug becomes <domain>-<seat>)").requiredOption("--worktree <path>", "Absolute review worktree path").option("--security", "Mark this seat as the security-lens seat (stage 2)").option("--skill-root <dir>", "Skill root containing references/pr-review.md (default: resolved skills/mstar-audit)").option("--recon <facts...>", "Recon facts (variadic: --recon fact1 fact2 ...)").option("--tier <quick|default|deep>", "Prompt tier (SP-A): quick shrinks read-first + folds the security lens in-seat; deep adds cross-domain security seat + stage-as-wave (default: default)").option("--diff-file <path>", "Absolute path to the pinned diff snapshot written by worktree-setup (read-first ingredient)").action((options) => {
   try {
     if (options.stage !== "1" && options.stage !== "2") {
       throw new SddScriptError(`usage: pr-review seat-prompt \u2014 --stage must be 1 or 2, got ${JSON.stringify(options.stage)}`, 2);
@@ -14618,7 +14823,8 @@ prReviewCommand.command("seat-prompt").description("Generate the read-only audit
       worktreePath: path12.resolve(options.worktree),
       reconFacts: options.recon ?? [],
       ...options.security === true ? { securitySeat: true } : {},
-      ...tier !== undefined ? { tier } : {}
+      ...tier !== undefined ? { tier } : {},
+      ...options.diffFile !== undefined && options.diffFile !== "" ? { diffFile: path12.resolve(resolveCliPath(options.diffFile)) } : {}
     });
     console.log(prompt);
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/cli",
-  "version": "3.6.0-alpha.2",
+  "version": "3.6.0-alpha.4",
   "description": "Morning Star harness CLI — installer bootstrap + mstar workflow verbs (path/status/lease/sdd/iteration/dispatch/worktree/lint/design-md/audit/compound/host/skill).",
   "license": "MIT",
   "repository": {