@mstar-harness/engine 3.4.0 → 3.5.0

package/dist/audit.js

@@ -1,7 +1,7 @@
 // src/audit.ts
-import { execFileSync } from "node:child_process";
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
-import { basename as basename2, join as join4, resolve as resolve4, sep as sep2 } from "node:path";
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync5, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename3, join as join7, resolve as resolve7, sep as sep2 } from "node:path";
 
 // src/core.ts
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -92,7 +92,16 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   }
 }
 
+// src/path.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { basename as basename2, dirname as dirname5, isAbsolute as isAbsolute4, join as join6, relative as relative2, resolve as resolve6 } from "node:path";
+
 // src/mstarc.ts
+import { readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve3 } from "node:path";
+var MSTARC_FILE = ".mstarc";
+var MSTARC_SECTION = "config";
 var MSTARC_HARNESS_DIR_KEY = "harness_dir";
 var MSTARC_PLAN_DIR_KEY = "plan_dir";
 var MSTARC_SDD_DIR_KEY = "sdd_dir";
@@ -113,10 +122,205 @@ var CONFIG_KEYS = {
   [MSTARC_PROJECT_DIR_KEY]: "projectDir",
   [MSTARC_ENFORCEMENT_KEY]: "enforcement"
 };
+function parseMstarc(text) {
+  let section = null;
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith(";"))
+      continue;
+    const header = /^\[([^\]]+)\]$/.exec(line);
+    if (header !== null) {
+      section = header[1].trim();
+      continue;
+    }
+    if (section !== MSTARC_SECTION)
+      continue;
+    const eq = line.indexOf("=");
+    if (eq === -1)
+      continue;
+    const field = CONFIG_KEYS[line.slice(0, eq).trim()];
+    if (field === undefined)
+      continue;
+    const value = line.slice(eq + 1).trim();
+    if (value === "")
+      continue;
+    if (field === "enforcement" && value !== "hard" && value !== "soft")
+      continue;
+    out[field] = value;
+  }
+  return out;
+}
+function isFile(file) {
+  try {
+    return statSync2(file).isFile();
+  } catch {
+    return false;
+  }
+}
+function findMstarc(startDir, boundary) {
+  let dir = resolve3(startDir);
+  const bound = resolve3(boundary);
+  for (;; ) {
+    if (!isAtOrBelow(dir, bound))
+      return null;
+    const candidate = join3(dir, MSTARC_FILE);
+    if (isFile(candidate))
+      return candidate;
+    if (dir === bound)
+      return null;
+    const parent = dirname3(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function loadMstarc(startDir, boundary) {
+  const file = findMstarc(startDir, boundary);
+  if (file === null)
+    return null;
+  return { file, dir: dirname3(file), config: parseMstarc(readFileSync2(file, "utf8")) };
+}
+function isAtOrBelow(dir, root) {
+  const rel = relative(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
+
+// src/store.ts
+import { existsSync as existsSync2, readdirSync, unlinkSync as unlinkSync3 } from "node:fs";
+import { isAbsolute as isAbsolute3, join as join4, resolve as resolve4 } from "node:path";
+var PLAN_SHAPED_KEY_RE = /^[0-9]{8}-[a-z0-9-]+$/;
+function resolveArtifactPath(harnessRoot, ref) {
+  const { kind, key } = ref;
+  if (kind === "json") {
+    if (!isAbsolute3(key)) {
+      throw new Error(`ArtifactStore json key must be an absolute path — got ${JSON.stringify(key)}`);
+    }
+    if (key.split(/[\\/]+/).includes("..")) {
+      throw new Error(`ArtifactStore json key must not contain ".." segments — got ${JSON.stringify(key)}`);
+    }
+    return key;
+  }
+  assertSafePathComponent(key, "ArtifactStore key");
+  if (kind === "status") {
+    if (key !== "root") {
+      throw new Error(`ArtifactStore status key must be "root" — got ${JSON.stringify(key)}`);
+    }
+    return join4(harnessRoot, "status.json");
+  }
+  if (kind === "snapshot") {
+    return join4(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), key, "snapshot.json");
+  }
+  if (kind === "residuals") {
+    return join4(resolveProjectDir(harnessRoot, { harnessDir: harnessRoot }), key, "residuals.json");
+  }
+  if (PLAN_SHAPED_KEY_RE.test(key)) {
+    return join4(harnessRoot, "sdd", key, "review", "report.json");
+  }
+  return join4(harnessRoot, "sdd", "_reviews", `${key}.json`);
+}
+function listDirNames(dir) {
+  return readDirEntries(dir).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+function listJsonKeys(dir) {
+  return readDirEntries(dir).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => entry.name.slice(0, -".json".length));
+}
+function readDirEntries(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return [];
+    throw error;
+  }
+}
+function tryResolveGetPath(root, kind, key) {
+  try {
+    return resolveArtifactPath(root, { kind, key });
+  } catch {
+    return;
+  }
+}
+function createFsStore(harnessRoot) {
+  const root = resolve4(harnessRoot);
+  return {
+    root,
+    async put(doc) {
+      if (doc.schema !== undefined) {
+        throw new Error("FsStore does not persist schema ids — omit --schema or inject a store module that persists it");
+      }
+      writeJson(resolveArtifactPath(root, doc), doc.payload);
+    },
+    async get(ref) {
+      const filePath = resolveArtifactPath(root, ref);
+      if (!existsSync2(filePath))
+        return;
+      return readJson(filePath);
+    },
+    async delete(ref) {
+      const filePath = resolveArtifactPath(root, ref);
+      if (existsSync2(filePath))
+        unlinkSync3(filePath);
+    },
+    async list(kind) {
+      if (kind === "json") {
+        throw new Error("ArtifactStore json keys are absolute paths and cannot be listed");
+      }
+      const keys = [];
+      if (kind === "status") {
+        if (existsSync2(resolveArtifactPath(root, { kind, key: "root" })))
+          keys.push("root");
+      } else if (kind === "snapshot" || kind === "residuals") {
+        const baseDir = kind === "snapshot" ? resolveWorkflowDir(root, { harnessDir: root }) : resolveProjectDir(root, { harnessDir: root });
+        for (const name of listDirNames(baseDir)) {
+          const getPath = tryResolveGetPath(root, kind, name);
+          if (getPath !== undefined && existsSync2(getPath))
+            keys.push(name);
+        }
+      } else {
+        const sddDir = join4(root, "sdd");
+        for (const key of listJsonKeys(join4(sddDir, "_reviews"))) {
+          if (!PLAN_SHAPED_KEY_RE.test(key) && tryResolveGetPath(root, kind, key) !== undefined) {
+            keys.push(key);
+          }
+        }
+        for (const name of listDirNames(sddDir)) {
+          if (PLAN_SHAPED_KEY_RE.test(name)) {
+            const getPath = tryResolveGetPath(root, kind, name);
+            if (getPath !== undefined && existsSync2(getPath))
+              keys.push(name);
+          }
+        }
+      }
+      return keys.sort().map((key) => ({ kind, key }));
+    }
+  };
+}
+var injectedStore;
+function getArtifactStore() {
+  if (injectedStore !== undefined)
+    return injectedStore;
+  const root = resolveHarnessDir(process.cwd());
+  if (root === null) {
+    throw new Error(`harness dir not found from ${resolve4(process.cwd())} — cannot create the default FsStore (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+  }
+  return createFsStore(root);
+}
+function assertFsStorePath(store, ref, expectedPath) {
+  const root = store.root;
+  if (typeof root !== "string")
+    return;
+  const storePath = resolveArtifactPath(root, ref);
+  const expected = resolve4(expectedPath);
+  if (storePath !== expected) {
+    throw new Error(`routed writer path mismatch: the active FsStore resolves ${ref.kind}/${JSON.stringify(ref.key)} to ${JSON.stringify(storePath)} but the caller's target is ${JSON.stringify(expected)} — call setArtifactStore(createFsStore(<root>)) first when the write target differs from the active store's root`);
+  }
+}
 
 // src/status.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, realpathSync } from "node:fs";
-import { dirname as dirname3, join as join3, resolve as resolve3, sep } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync } from "node:fs";
+import { dirname as dirname4, join as join5, resolve as resolve5, sep } from "node:path";
 
 // src/workflow.ts
 var WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
@@ -181,7 +385,7 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (typeof docOrPath === "string") {
     try {
       doc = readJson(docOrPath);
-      harnessDir = dirname3(resolve3(docOrPath));
+      harnessDir = dirname4(resolve5(docOrPath));
     } catch (error) {
       return {
         ok: false,
@@ -248,8 +452,8 @@ function validateStatusV2(docOrPath, opts = {}) {
     for (const entry of doc.workflows) {
       if (!isPlainObject(entry) || typeof entry.dir !== "string")
         continue;
-      const relSnapshot = join3(entry.dir, WORKFLOW_SNAPSHOT_FILE);
-      const snapshotPath = join3(harnessDir, relSnapshot);
+      const relSnapshot = join5(entry.dir, WORKFLOW_SNAPSHOT_FILE);
+      const snapshotPath = join5(harnessDir, relSnapshot);
       const label = typeof entry.id === "string" ? entry.id : relSnapshot;
       let physical;
       try {
@@ -282,8 +486,10 @@ function validateStatusV2(docOrPath, opts = {}) {
   }
   return { ok: violations.length === 0, violations };
 }
-function registerWorkflowEntryLocked(statusPath, entry) {
-  const harnessDir = dirname3(statusPath);
+async function registerWorkflowEntryLocked(statusPath, entry) {
+  const harnessDir = dirname4(statusPath);
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "status", key: "root" }, statusPath);
   const current = readJson(statusPath);
   const fresh = Object.keys(current).length === 0;
   const doc = fresh ? { version: 2, updated_at: todayString(), workflows: [] } : current;
@@ -301,16 +507,83 @@ function registerWorkflowEntryLocked(statusPath, entry) {
   if (!gate.ok) {
     throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
   }
-  writeJson(statusPath, doc);
+  await store.put({ kind: "status", key: "root", payload: doc });
   return doc;
 }
 
 // src/path.ts
+function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
+  const start = resolve6(startDir);
+  const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
+  if (explicit)
+    return resolve6(start, explicit);
+  const boundary = resolve6(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
+  const rc = loadMstarc(start, boundary);
+  if (rc !== null && rc.config.harnessDir)
+    return resolve6(rc.dir, rc.config.harnessDir);
+  let dir = start;
+  for (;; ) {
+    if (!isAtOrBelow2(dir, boundary))
+      return null;
+    for (const candidate of [join6(dir, ".mstar"), join6(dir, ".agents"), join6(dir, ".plans"), join6(dir, "plans")]) {
+      if (isDirectory(candidate))
+        return candidate;
+    }
+    if (dir === boundary)
+      return null;
+    const parent = dirname5(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function defaultWorkspaceRoot(startDir) {
+  try {
+    const cdup = execFileSync("git", ["rev-parse", "--show-cdup"], {
+      cwd: startDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (!cdup)
+      return startDir;
+    let boundary = startDir;
+    for (const segment of cdup.split(/[\\/]/)) {
+      if (segment && segment !== ".")
+        boundary = dirname5(boundary);
+    }
+    return resolve6(boundary);
+  } catch {}
+  return startDir;
+}
+function isAtOrBelow2(dir, root) {
+  const rel = relative2(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute4(rel);
+}
+function mstarcDirOverride(harnessDir, key) {
+  const dir = resolve6(harnessDir);
+  const rc = loadMstarc(dir, dirname5(dir));
+  const declared = rc?.config[key];
+  return declared ? resolve6(rc.dir, declared) : null;
+}
 function assertSafePathComponent(value, what) {
   if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
     throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
   }
 }
+function resolveHarnessSubdir(startDir, opts, key, fallback) {
+  const harness = resolveHarnessDir(startDir, opts);
+  if (harness === null) {
+    throw new Error(`harness dir not found from ${resolve6(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+  }
+  const declared = mstarcDirOverride(harness, key);
+  return declared !== null ? declared : join6(resolve6(harness), fallback);
+}
+function resolveWorkflowDir(startDir = process.cwd(), opts = {}) {
+  return resolveHarnessSubdir(startDir, opts, "workflowDir", "workflows");
+}
+function resolveProjectDir(startDir = process.cwd(), opts = {}) {
+  return resolveHarnessSubdir(startDir, opts, "projectDir", "projects");
+}
 var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
 # Principle: process stays local; results are shared with the team.
 # Default-ignore everything under .mstar/, then re-include the tracked results.
@@ -336,6 +609,13 @@ var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
 `).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
 var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
 `).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
+function isDirectory(dir) {
+  try {
+    return statSync3(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
 
 // src/audit.ts
 function violation2(severity, code, message, fix) {
@@ -633,12 +913,12 @@ function scanSecrets(files) {
   for (const file of files) {
     let text;
     try {
-      text = readFileSync3(file, "utf8");
+      text = readFileSync5(file, "utf8");
     } catch {
       unreadableFiles++;
       continue;
     }
-    const base = basename2(file);
+    const base = basename3(file);
     for (const entry of NEVER_COMMIT_FILENAMES) {
       if (entry.re.test(base))
         findings.push({ file, line: 1, type: entry.type });
@@ -690,21 +970,21 @@ var LOCKFILE_NAMES = [
 function rootLockfiles(root) {
   let entries;
   try {
-    entries = readdirSync2(root, { withFileTypes: true });
+    entries = readdirSync4(root, { withFileTypes: true });
   } catch {
     return [];
   }
   const names = new Set(LOCKFILE_NAMES);
-  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join4(root, entry.name));
+  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join7(root, entry.name));
   if (present.length === 0)
     return [];
   try {
-    const tracked = new Set(execFileSync("git", ["ls-files", "-z", "--", "."], {
+    const tracked = new Set(execFileSync2("git", ["ls-files", "-z", "--", "."], {
       cwd: root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).split("\x00").filter((f) => f !== ""));
-    return present.filter((p) => tracked.has(basename2(p)));
+    return present.filter((p) => tracked.has(basename3(p)));
   } catch {
     return present;
   }
@@ -720,21 +1000,21 @@ function supplyChainChecks(repoRoot) {
     findings.push({ kind: "lockfile-duplicate", file: lockfiles.map((f) => f.replace(`${repoRoot}/`, "")).join(", ") });
     violations.push(violation2("medium", "audit.supply.lockfile-duplicate", `multiple lockfiles at ${repoRoot}: ${lockfiles.join(", ")}`, "keep exactly one lockfile per package manager"));
   }
-  const workflowsDir = join4(repoRoot, ".github", "workflows");
+  const workflowsDir = join7(repoRoot, ".github", "workflows");
   let wfEntries = [];
   try {
-    wfEntries = readdirSync2(workflowsDir, { withFileTypes: true });
+    wfEntries = readdirSync4(workflowsDir, { withFileTypes: true });
   } catch {
     wfEntries = [];
   }
   for (const entry of wfEntries) {
     if (!entry.isFile() || !/\.(?:ya?ml)$/.test(entry.name))
       continue;
-    const wfPath = join4(workflowsDir, entry.name);
+    const wfPath = join7(workflowsDir, entry.name);
     const relPath = `.github/workflows/${entry.name}`;
     let text;
     try {
-      text = readFileSync3(wfPath, "utf8");
+      text = readFileSync5(wfPath, "utf8");
     } catch {
       continue;
     }
@@ -832,7 +1112,7 @@ function redactFinding(finding) {
   };
 }
 function readPlanFileSummary(filePath) {
-  const text = readFileSync3(filePath, "utf8");
+  const text = readFileSync5(filePath, "utf8");
   const title = (text.match(/^# (.+)$/m) ?? [])[1] ?? filePath;
   const blocks = parseStatusBlocks(text);
   return { title: title.trim(), fields: blocks.length > 0 ? blocks[0].fields : new Map };
@@ -886,10 +1166,10 @@ function renderIndex(params) {
 function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
-  mkdirSync3(outDir, { recursive: true });
-  const existingReadme = join4(outDir, "README.md");
-  const carried = existsSync3(existingReadme) ? extractSecurityDispositionSections(readFileSync3(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
-  const existing = readdirSync2(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
+  mkdirSync4(outDir, { recursive: true });
+  const existingReadme = join7(outDir, "README.md");
+  const carried = existsSync5(existingReadme) ? extractSecurityDispositionSections(readFileSync5(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
+  const existing = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
   const redactedFindings = findings.map(redactFinding);
   const written = [];
@@ -905,13 +1185,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     }
     usedSlugs.add(slug);
     const file = `${num}-${slug}.md`;
-    writeFileSync3(join4(outDir, file), renderPlanFile(finding, plannedAt));
+    writeFileSync4(join7(outDir, file), renderPlanFile(finding, plannedAt));
     written.push(file);
     next++;
   }
   const all = [...existing, ...written].sort();
   const rows = all.map((file) => {
-    const summary = readPlanFileSummary(join4(outDir, file));
+    const summary = readPlanFileSummary(join7(outDir, file));
     const fields = summary.fields;
     return {
       num: file.slice(0, 3),
@@ -945,7 +1225,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   });
   const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
   const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(redactText(hc.text))}`) : carried.hardeningChecked;
-  writeFileSync3(join4(outDir, "README.md"), renderIndex({
+  writeFileSync4(join7(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
@@ -954,7 +1234,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     needsVerification: needsVerificationLines,
     hardeningChecked: hardeningCheckedLines
   }));
-  return { outDir: resolve4(outDir), date, files: written, nextNumber: next };
+  return { outDir: resolve7(outDir), date, files: written, nextNumber: next };
 }
 async function promoteAuditPlans(outDir, selected, options) {
   if (selected.length === 0) {
@@ -963,19 +1243,19 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (typeof options.harnessDir !== "string" || options.harnessDir.trim() === "") {
     throw new Error("promoteAuditPlans: options.harnessDir is required (must contain status.json + workflows/)");
   }
-  const workflowId = options.workflowId ?? basename2(resolve4(outDir));
+  const workflowId = options.workflowId ?? basename3(resolve7(outDir));
   assertSafePathComponent(workflowId, "workflow id");
-  const harnessDir = resolve4(options.harnessDir);
-  const statusPath = join4(harnessDir, "status.json");
-  const workflowDir = join4(harnessDir, "workflows", workflowId);
-  const snapshotPath = join4(workflowDir, WORKFLOW_SNAPSHOT_FILE);
+  const harnessDir = resolve7(options.harnessDir);
+  const statusPath = join7(harnessDir, "status.json");
+  const workflowDir = join7(harnessDir, "workflows", workflowId);
+  const snapshotPath = join7(workflowDir, WORKFLOW_SNAPSHOT_FILE);
   const planFiles = resolveSelectedPlanFiles(outDir, selected);
   const indexRows = readExecutionOrderIndex(outDir);
   const plans = planFiles.map((planFile) => {
     const stem = planFile.replace(/\.md$/, "");
     const num = stem.slice(0, 3);
     const indexRow = indexRows.get(num);
-    const title = indexRow?.title ?? readPlanFileSummary(join4(outDir, planFile)).title;
+    const title = indexRow?.title ?? readPlanFileSummary(join7(outDir, planFile)).title;
     return {
       id: stem,
       title,
@@ -1003,18 +1283,18 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (!entryGate.ok) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
-  await withStatusWriteLock(statusPath, () => {
-    if (existsSync3(snapshotPath)) {
+  await withStatusWriteLock(statusPath, async () => {
+    if (existsSync5(snapshotPath)) {
       throw new Error(`refusing to promote audit plans: workflow ${JSON.stringify(workflowId)} already exists ` + `(snapshot at ${snapshotPath}) — re-promote would drop its registered plan rows; ` + `remove that workflow before promoting again`);
     }
-    mkdirSync3(workflowDir, { recursive: true });
+    mkdirSync4(workflowDir, { recursive: true });
     try {
       writeJson(snapshotPath, snapshot);
-      registerWorkflowEntryLocked(statusPath, entry);
+      await registerWorkflowEntryLocked(statusPath, entry);
     } catch (error) {
       rmSync(snapshotPath, { force: true });
       try {
-        if (readdirSync2(workflowDir).length === 0) {
+        if (readdirSync4(workflowDir).length === 0) {
           rmdirSync2(workflowDir);
         }
       } catch {}
@@ -1025,7 +1305,7 @@ async function promoteAuditPlans(outDir, selected, options) {
   return { workflowId, snapshotPath };
 }
 function resolveSelectedPlanFiles(outDir, selected) {
-  const files = readdirSync2(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
+  const files = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
   const byNum = new Map;
   const byStem = new Map;
   for (const file of files) {
@@ -1040,7 +1320,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   for (const id of selected) {
     const file = byNum.get(id) ?? byStem.get(id) ?? byStem.get(id.replace(/\.md$/, ""));
     if (file === undefined) {
-      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve4(outDir)}`);
+      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve7(outDir)}`);
     }
     if (!seen.has(file)) {
       seen.add(file);
@@ -1050,10 +1330,10 @@ function resolveSelectedPlanFiles(outDir, selected) {
   return resolved;
 }
 function readExecutionOrderIndex(outDir) {
-  const readmePath = join4(outDir, "README.md");
+  const readmePath = join7(outDir, "README.md");
   let text;
   try {
-    text = readFileSync3(readmePath, "utf8");
+    text = readFileSync5(readmePath, "utf8");
   } catch {
     return new Map;
   }
@@ -1079,7 +1359,7 @@ function readExecutionOrderIndex(outDir) {
   return rows;
 }
 function planFileRel(outDir, planFile) {
-  const resolved = resolve4(outDir);
+  const resolved = resolve7(outDir);
   const parts = resolved.split(sep2);
   const plansIdx = parts.lastIndexOf("plans");
   if (plansIdx >= 0) {

package/dist/dispatch.d.ts

@@ -172,13 +172,24 @@ export declare function assertTriIdentity(reviewerRoles: readonly string[]): Gat
  */
 export type ComposeDispatchGateOptions = {
     /**
-     * Host role-binding field (omp task entry `agent` / opencode `subagent` /
-     * cursor `subagent_type` / dsh `dispatchBinding`). The anti-recursion
-     * precheck runs for EVERY Assignment-shaped text: an empty or omitted
-     * binding fails closed (`dispatch.anti-recursion.empty-binding`) — the
-     * host cannot prove the dispatching agent is not recursing.
+     * Dispatching agent's OWN harness role (dsh `Config.dispatchBinding`).
+     * When non-empty, the anti-recursion precheck compares it against the
+     * Assignment's `Execute as` — equality is self-recursion
+     * (`dispatch.anti-recursion.self-type`, critical). Leave unset on hosts
+     * whose tool-call event cannot report the dispatching agent's identity
+     * (omp/opencode/cursor): the precheck is skipped there and the NEVER red
+     * line stays prompt-level (mstar-dispatch-gates).
      */
-    agent?: string;
+    caller?: string;
+    /**
+     * True on hosts whose contract declares the caller binding mandatory
+     * (dsh): an empty/missing `caller` then fails closed with
+     * `dispatch.anti-recursion.empty-binding` (critical) — the host could
+     * have declared the binding, so an absent one proves nothing and the
+     * dispatch must not proceed as if the NEVER red line held. Default
+     * `false`: the precheck is skipped entirely when `caller` is empty.
+     */
+    callerRequired?: boolean;
     /**
      * `false` for read-only roles (scout/explore) — skips the branch-form and
      * default-branch gates. Default: `true` (writable).
@@ -206,10 +217,14 @@ export type ComposeDispatchGateResult = GateResult & {
  *    Assignment-shaped passes silently (`shaped: false`).
  * 2. `validateAssignmentFields` with `writable: false` when `opts.writable
  *    === false` (read-only roles), else the writable default.
- * 3. Anti-recursion precheck — runs for every Assignment-shaped text; an
- *    empty/omitted host binding fails closed (`dispatch.anti-recursion.
- *    empty-binding`), a binding equal to `Execute as` is the existing
- *    `dispatch.anti-recursion.self-type` critical.
+ * 3. Anti-recursion precheck — CALLER semantics (issue #156): runs only
+ *    when the host supplies its own role binding (`caller`), or fails
+ *    closed on an empty one when the host contract requires it
+ *    (`callerRequired`, dsh). A caller equal to `Execute as` is the
+ *    `dispatch.anti-recursion.self-type` critical; a required-but-empty
+ *    caller is `dispatch.anti-recursion.empty-binding`. Target-only hosts
+ *    (omp/opencode/cursor) skip the leg — their binding field carries the
+ *    spawn TARGET, which equals `Execute as` on every compliant dispatch.
  * 4. Default-branch gate for writable text: the branch comes from the
  *    Assignment's own branch forms (create-form name / Working branch /
  *    Branch policy branch), else `$MSTAR_WORKING_BRANCH`; a well-formed
@@ -224,13 +239,17 @@ export type ComposeDispatchGateResult = GateResult & {
 export declare function composeDispatchGate(text: string, opts?: ComposeDispatchGateOptions): ComposeDispatchGateResult;
 /**
  * Anti-recursion precheck (NEVER red line, mstar-dispatch-gates § 承接方反递归
- * 红线): a leaf executor MUST NOT invoke a Task/subagent whose role-binding
- * field (`subagent_type` / `agent` / `subagent`) equals its own `Execute as`.
- * Comparison is case-insensitive after trim. An EMPTY binding fails closed
- * (`dispatch.anti-recursion.empty-binding`, critical): the host cannot
- * report which agent is calling, so anti-recursion cannot be proven — the
- * dispatch must not proceed as if the NEVER red line held. An empty
- * `executeAs` with a set binding stays ok (field presence is
- * `validateAssignmentFields`' job, not this precheck).
+ * 红线): a leaf executor MUST NOT dispatch a Task/subagent whose target role
+ * (the new Assignment's `Execute as`) equals its OWN role. `subagentType`
+ * is therefore the DISPATCHING agent's own role binding (dsh
+ * `Config.dispatchBinding`) — never the spawn-target field (omp `agent` /
+ * opencode `subagent`), which equals `Execute as` on every compliant
+ * dispatch (issue #156). Comparison is case-insensitive after trim. An
+ * EMPTY binding fails closed (`dispatch.anti-recursion.empty-binding`,
+ * critical): the host cannot report which agent is calling, so
+ * anti-recursion cannot be proven — the dispatch must not proceed as if
+ * the NEVER red line held. An empty `executeAs` with a set binding stays
+ * ok (field presence is `validateAssignmentFields`' job, not this
+ * precheck).
  */
 export declare function antiRecursionPrecheck(subagentType: string, executeAs: string): GateResult;