@deftai/directive-core 0.107.0 → 0.109.0

package/dist/swarm/subagent-status-dir.js

@@ -0,0 +1,42 @@
+/**
+ * Arm the shipped sub-agent heartbeat path (#3730 / #1365 / #2824).
+ *
+ * `verify:subagent-alive` exits 2 when the scratch directory is missing, which
+ * looks like "never started" instead of REDISPATCH_OK. Parents mkdir at
+ * worktree create and at pre-dispatch begin so a later missing record is
+ * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { defaultScratchDir } from "../orchestration/subagent-monitor.js";
+/**
+ * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
+ * entry (a file for `git worktree add` trees, a directory for the main clone).
+ *
+ * Arming cannot key off `looksLikeFilesystemTarget` alone: that predicate exists
+ * to keep branch refs opaque and so answers false for a bare relative worktree
+ * name like `b3730`, leaving the liveness gate at its exit-2 config error for a
+ * supported dispatch form. Existence alone is too loose in the other direction —
+ * a branch named `docs` resolves onto the real `docs/` tree and would mkdir a
+ * stray scratch dir in the source checkout. The `.git` marker separates the two.
+ */
+export function looksLikeWorktreeDir(resolvedPath) {
+    const trimmed = resolvedPath.trim();
+    if (trimmed.length === 0)
+        return false;
+    return existsSync(join(trimmed, ".git"));
+}
+/**
+ * Create `<worktree>/.deft-scratch/subagent-status/` when the worktree exists.
+ * Returns the directory path, or null when the worktree is not on disk yet
+ * (do not mkdir a stray tree for a branch-name target).
+ */
+export function ensureSubagentStatusDir(worktreeRoot) {
+    const trimmed = worktreeRoot.trim();
+    if (trimmed.length === 0 || !existsSync(trimmed))
+        return null;
+    const dir = defaultScratchDir(trimmed);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+//# sourceMappingURL=subagent-status-dir.js.map

package/dist/swarm/worktrees.d.ts

@@ -21,6 +21,9 @@ export declare class WorktreeMapConfigError extends Error {
 export declare class WorktreePathEscapeError extends WorktreeMapError {
     name: string;
 }
+export declare class WorktreeRevisionMismatchError extends WorktreeMapError {
+    name: string;
+}
 export type GitRunner = (args: readonly string[], cwd: string) => TextCaptureResult;
 export declare const defaultGitRunner: GitRunner;
 /** Case-normalized comparison key for worktree-path equality. */
@@ -30,9 +33,20 @@ export interface WorktreeRecord {
     readonly worktree_path: string;
     readonly base_branch: string;
 }
-/** Parse `git worktree list --porcelain` into `{compareKey: branch|null}`. */
-export declare function parseWorktreePorcelain(text: string): Map<string, string | null>;
-/** Resolve a story-to-worktree mapping into normalized C3 records (frozen contract). */
+/** One `git worktree list --porcelain` record. `head` is the commit OID or null. */
+export interface WorktreePorcelainEntry {
+    readonly branch: string | null;
+    readonly head: string | null;
+}
+/** Parse `git worktree list --porcelain` into `{compareKey: {branch, head}}`. */
+export declare function parseWorktreePorcelain(text: string): Map<string, WorktreePorcelainEntry>;
+/**
+ * Resolve a story-to-worktree mapping into normalized C3 records (frozen contract).
+ *
+ * Registered paths are reused only when their porcelain HEAD OID matches the
+ * requested base OID. That comparison is a snapshot at resolution time — not a
+ * pin on the worker's start revision (`swarm:launch` emits a manifest and stops).
+ */
 export declare function resolveWorktreeMap(mapping: readonly Record<string, unknown>[], baseBranch: string, createMissing?: boolean, options?: {
     repoRoot?: string;
     git?: GitRunner;

package/dist/swarm/worktrees.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { isAbsolute, resolve as pathResolve } from "node:path";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { C3_FIELDS } from "./constants.js";
+import { ensureSubagentStatusDir } from "./subagent-status-dir.js";
 import { runText } from "./subprocess.js";
 export class WorktreeMapError extends Error {
     name = "WorktreeMapError";
@@ -24,6 +25,9 @@ export class WorktreeMapConfigError extends Error {
 export class WorktreePathEscapeError extends WorktreeMapError {
     name = "WorktreePathEscapeError";
 }
+export class WorktreeRevisionMismatchError extends WorktreeMapError {
+    name = "WorktreeRevisionMismatchError";
+}
 export const defaultGitRunner = (args, cwd) => runText(["git", ...args], { cwd });
 function resolvePath(raw, repoRoot) {
     const candidate = isAbsolute(raw) ? raw : pathResolve(repoRoot, raw);
@@ -44,14 +48,15 @@ function assertWorktreePathContained(repoRoot, worktreePath) {
 export function compareKey(pathStr) {
     return pathStr.replace(/\\/g, "/").toLowerCase();
 }
-/** Parse `git worktree list --porcelain` into `{compareKey: branch|null}`. */
+/** Parse `git worktree list --porcelain` into `{compareKey: {branch, head}}`. */
 export function parseWorktreePorcelain(text) {
     const registered = new Map();
     let currentPath = null;
     let currentBranch = null;
+    let currentHead = null;
     const flush = () => {
         if (currentPath !== null) {
-            registered.set(compareKey(currentPath), currentBranch);
+            registered.set(compareKey(currentPath), { branch: currentBranch, head: currentHead });
         }
     };
     for (const line of text.split("\n")) {
@@ -59,6 +64,11 @@ export function parseWorktreePorcelain(text) {
             flush();
             currentPath = pathResolve(line.slice("worktree ".length).trim());
             currentBranch = null;
+            currentHead = null;
+        }
+        else if (line.startsWith("HEAD ")) {
+            const oid = line.slice("HEAD ".length).trim().toLowerCase();
+            currentHead = oid.length > 0 ? oid : null;
         }
         else if (line.startsWith("branch ")) {
             const ref = line.slice("branch ".length).trim();
@@ -82,6 +92,24 @@ function gitWorktreeList(repoRoot, git) {
     }
     return parseWorktreePorcelain(proc.stdout);
 }
+function resolveCommitOid(repoRoot, revision, git) {
+    let proc;
+    try {
+        proc = git(["rev-parse", "--verify", "--end-of-options", `${revision}^{commit}`], repoRoot);
+    }
+    catch (exc) {
+        throw new WorktreeMapConfigError(`could not resolve base '${revision}' to a commit OID in ${repoRoot}: ${String(exc)}`);
+    }
+    if (proc.returncode !== 0) {
+        throw new WorktreeMapConfigError(`could not resolve base '${revision}' to a commit OID in ${repoRoot} ` +
+            `(rc=${proc.returncode}): ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    const oid = (proc.stdout.trim().split(/\s+/)[0] ?? "").toLowerCase();
+    if (!/^[0-9a-f]{40,64}$/.test(oid)) {
+        throw new WorktreeMapConfigError(`git rev-parse for base '${revision}' did not return a commit OID: ${JSON.stringify(oid)}`);
+    }
+    return oid;
+}
 function createWorktree(repoRoot, worktreePath, baseBranch, git) {
     mkdirSync(pathResolve(worktreePath, ".."), { recursive: true });
     let proc;
@@ -96,7 +124,13 @@ function createWorktree(repoRoot, worktreePath, baseBranch, git) {
             `(rc=${proc.returncode}): ${proc.stderr.trim() || "<no stderr>"}`);
     }
 }
-/** Resolve a story-to-worktree mapping into normalized C3 records (frozen contract). */
+/**
+ * Resolve a story-to-worktree mapping into normalized C3 records (frozen contract).
+ *
+ * Registered paths are reused only when their porcelain HEAD OID matches the
+ * requested base OID. That comparison is a snapshot at resolution time — not a
+ * pin on the worker's start revision (`swarm:launch` emits a manifest and stops).
+ */
 export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, options = {}) {
     if (!Array.isArray(mapping)) {
         throw new WorktreeMapConfigError(`worktree map must be a list of records, got ${typeof mapping}`);
@@ -154,14 +188,24 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
         });
     }
     const registered = gitWorktreeList(root, git);
+    const requestedOid = resolveCommitOid(root, trimmedBase, git);
     for (const entry of resolved) {
-        if (registered.has(entry._key)) {
+        const existing = registered.get(entry._key);
+        if (existing !== undefined) {
+            const actualOid = existing.head ?? "";
+            if (actualOid !== requestedOid) {
+                throw new WorktreeRevisionMismatchError(`registered worktree '${entry.worktree_path}' HEAD OID is ${actualOid || "(missing)"} ` +
+                    `but requested base '${trimmedBase}' resolves to ${requestedOid}; ` +
+                    `this is a snapshot check at resolution time, not a pin on the worker's start revision`);
+            }
+            ensureSubagentStatusDir(entry._abs);
             continue;
         }
         if (!createMissing) {
             throw new MissingWorktreeError(`story '${entry.story_id}' maps to '${entry.worktree_path}' which is not a registered git worktree and create_missing is disabled`);
         }
         createWorktree(root, entry._abs, trimmedBase, git);
+        ensureSubagentStatusDir(entry._abs);
     }
     return resolved.map(({ story_id, worktree_path, base_branch }) => ({
         story_id,

package/dist/triage/evaluate/worktrees.js

@@ -1,5 +1,7 @@
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { containedRemove, containedWrite } from "../../fs/contained-write.js";
 import { defaultGitRunner as swarmGitRunner, } from "../../swarm/worktrees.js";
 import { evaluatorWorktreePath } from "./paths.js";
 export class EvaluatorWorktreeError extends Error {
@@ -27,17 +29,162 @@ function forceDeleteWorktreeDir(worktreePath) {
     }
     rmSync(worktreePath, { recursive: true, force: true });
 }
+const caseInsensitiveDirCache = new Map();
+function slashResolve(path) {
+    return resolve(path).replace(/\\/g, "/");
+}
+function directoryIgnoresCase(dir) {
+    let existing = resolve(dir);
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing) {
+            return process.platform === "win32";
+        }
+        existing = parent;
+    }
+    const cached = caseInsensitiveDirCache.get(existing);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const tag = randomBytes(6).toString("hex");
+    const lower = join(existing, `.deft-cs-${tag}a`);
+    const upper = join(existing, `.deft-cs-${tag}A`);
+    let ignores = false;
+    let probed = false;
+    try {
+        containedWrite({
+            root: existing,
+            target: lower,
+            data: "",
+            mode: "create",
+            mkdir: false,
+            mutation: false,
+        });
+        ignores = existsSync(upper);
+        probed = true;
+    }
+    catch {
+        // Fail closed: do not fold unless the probe proved case-insensitivity.
+    }
+    finally {
+        try {
+            containedRemove({ root: existing, target: lower, mutation: false });
+        }
+        catch {
+            // ignore
+        }
+        try {
+            containedRemove({ root: existing, target: upper, mutation: false });
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (probed) {
+        caseInsensitiveDirCache.set(existing, ignores);
+    }
+    return ignores;
+}
+function canonicalizeWorktreePath(path) {
+    const resolved = slashResolve(path);
+    let existing = "";
+    if (existsSync(path)) {
+        existing = path;
+    }
+    else if (existsSync(resolved)) {
+        existing = resolved;
+    }
+    if (existing.length > 0) {
+        try {
+            return realpathSync.native(existing).replace(/\\/g, "/");
+        }
+        catch {
+            // Path vanished between exists and realpath.
+        }
+    }
+    const parent = dirname(resolved);
+    const base = basename(resolved);
+    let parentCanon = slashResolve(parent);
+    try {
+        if (existsSync(parent)) {
+            parentCanon = realpathSync.native(parent).replace(/\\/g, "/");
+        }
+    }
+    catch {
+        // Keep slash-resolved parent.
+    }
+    const leaf = directoryIgnoresCase(parent) ? base.toLowerCase() : base;
+    return `${parentCanon}/${leaf}`;
+}
+/**
+ * Unregister one missing worktree by deleting only its `$GIT_DIR/worktrees/<id>`
+ * admin directory. Containment root is that worktrees dir (the git common dir
+ * may sit outside a linked-worktree projectRoot). `git worktree prune` has no
+ * path argument and operates on every registration, including concurrent
+ * agents' reflogs.
+ *
+ * Path identity uses on-disk realpath when the worktree exists, and otherwise
+ * folds case only when the parent directory is case-insensitive. A case-sensitive
+ * Windows directory can host two worktrees that differ only by case; those
+ * must not share an admin entry.
+ */
+function pruneEvaluatorWorktreeAdmin(git, projectRoot, worktreePath) {
+    const common = git(["rev-parse", "--git-common-dir"], projectRoot);
+    const trimmed = common.stdout.trim();
+    if (common.returncode !== 0 || trimmed.length === 0) {
+        return;
+    }
+    const commonDir = isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+    const worktreesDir = join(commonDir, "worktrees");
+    if (!existsSync(worktreesDir)) {
+        return;
+    }
+    const needle = canonicalizeWorktreePath(worktreePath);
+    let names = [];
+    try {
+        names = readdirSync(worktreesDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+            continue;
+        }
+        const gitdirFile = join(worktreesDir, name, "gitdir");
+        if (!existsSync(gitdirFile)) {
+            continue;
+        }
+        let recorded = "";
+        try {
+            recorded = readFileSync(gitdirFile, "utf8").trim();
+        }
+        catch {
+            continue;
+        }
+        const recordedWorktree = recorded.replace(/\\/g, "/").replace(/\/\.git$/u, "");
+        if (canonicalizeWorktreePath(recordedWorktree) === needle) {
+            containedRemove({
+                root: resolve(worktreesDir),
+                target: join(worktreesDir, name),
+                recursive: true,
+                mutation: false,
+            });
+            return;
+        }
+    }
+}
 function worktreeStillRegistered(git, projectRoot, worktreePath) {
     const listed = git(["worktree", "list", "--porcelain"], projectRoot);
     if (listed.returncode !== 0) {
         return true;
     }
-    const needle = resolve(worktreePath).replace(/\\/g, "/").toLowerCase();
+    const needle = canonicalizeWorktreePath(worktreePath);
     for (const line of listed.stdout.split(/\r?\n/u)) {
         if (!line.startsWith("worktree ")) {
             continue;
         }
-        const listedPath = line.slice("worktree ".length).replace(/\\/g, "/").toLowerCase();
+        const listedPath = canonicalizeWorktreePath(line.slice("worktree ".length));
         if (listedPath === needle) {
             return true;
         }
@@ -53,13 +200,13 @@ export function removeEvaluatorWorktree(projectRoot, worktreePath, git = swarmGi
     }
     const firstError = proc.stderr.trim() || "<no stderr>";
     forceDeleteWorktreeDir(worktreePath);
-    runner(["worktree", "prune"], projectRoot);
+    pruneEvaluatorWorktreeAdmin(runner, projectRoot, worktreePath);
     const retry = runner(["worktree", "remove", "--force", worktreePath], projectRoot);
     if (retry.returncode === 0) {
         return;
     }
     forceDeleteWorktreeDir(worktreePath);
-    runner(["worktree", "prune"], projectRoot);
+    pruneEvaluatorWorktreeAdmin(runner, projectRoot, worktreePath);
     if (!worktreeStillRegistered(runner, projectRoot, worktreePath) && !existsSync(worktreePath)) {
         return;
     }

package/dist/triage/scope/mutations-core.d.ts

@@ -1,9 +1,5 @@
-export declare class ProjectDefinitionIOError extends Error {
-    readonly name = "ProjectDefinitionIOError";
-}
-export declare function projectDefinitionPath(projectRoot: string): string;
-export declare function loadProjectDefinitionForMutation(projectRoot: string): [Record<string, unknown>, string];
-export declare function atomicWriteProjectDefinition(path: string, data: Record<string, unknown>): void;
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 export declare function recordSubscriptionChange(projectRoot: string, options: {
     op: string;
     label?: string | null;

package/dist/triage/scope/mutations-core.js

@@ -1,52 +1,20 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
-import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../../vbrief-build/project-definition-mutation.js";
 import { resolveTriageCachePath } from "../cache-path.js";
 import { SUBSCRIPTION_HISTORY_SCHEMA } from "./constants.js";
 import { pyStrRepr } from "./python-repr.js";
 import { utcIso } from "./time.js";
-export class ProjectDefinitionIOError extends Error {
-    name = "ProjectDefinitionIOError";
-}
-export function projectDefinitionPath(projectRoot) {
-    return resolveProjectDefinitionPath(projectRoot);
-}
-export function loadProjectDefinitionForMutation(projectRoot) {
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / ` +
-            "task triage:bootstrap to scaffold one first.");
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (err) {
-        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${path}: ${String(err)}`);
-    }
-    let data;
-    try {
-        data = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(err)}`);
-    }
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-    }
-    return [data, path];
-}
-export function atomicWriteProjectDefinition(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
-    const payload = `${JSON.stringify(data, null, 2)}\n`;
-    const tmp = join(tmpdir(), `${randomUUID()}.tmp`);
-    writeFileSync(tmp, payload, "utf8");
-    renameSync(tmp, path);
-}
+// One canonical PROJECT-DEFINITION identity (#3796). The resolver, loader,
+// error type, and write sink are the shared implementations the mutation
+// capability binds. Module-local duplicates used to resolve the layout path
+// directly -- ignoring the `DEFT_PROJECT_PATH` override the lock honours -- and
+// wrote through an uncontained temp sink, so a caller could lock one artifact
+// and load or persist another.
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 function resolveActor(actor) {
     if (typeof actor === "string" && actor.trim())
         return actor;
@@ -133,11 +101,11 @@ export function subscribe(projectRoot, options) {
     // Serialise the read-modify-write + subscription-history append under the
     // shared PROJECT-DEFINITION mutation lock so concurrent mutators cannot lose
     // an update or emit out-of-order audit rows (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadProjectDefinitionForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const planRec = plan;
         migrateLegacyPolicyKey(planRec);
@@ -145,14 +113,14 @@ export function subscribe(projectRoot, options) {
             planRec[PLAN_POLICY_KEY] = {};
         const policy = planRec[PLAN_POLICY_KEY];
         if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan.policy' key`);
         }
         const policyRec = policy;
         if (policyRec.triageScope === undefined)
             policyRec.triageScope = [];
         const rules = policyRec.triageScope;
         if (!Array.isArray(rules)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScope'`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-list 'plan.policy.triageScope'`);
         }
         const before = snapshotRules(rules);
         let changed;
@@ -168,7 +136,7 @@ export function subscribe(projectRoot, options) {
         }
         if (!changed)
             return [false, message];
-        atomicWriteProjectDefinition(path, data);
+        mutation.persist(data);
         recordSubscriptionChange(projectRoot, {
             op: "subscribe",
             label: options.label ?? null,
@@ -185,11 +153,11 @@ export function addIgnore(projectRoot, label) {
         throw new Error(`label must be a non-empty string; got ${JSON.stringify(label)}`);
     // Serialise the read-modify-write + subscription-history append under the
     // shared PROJECT-DEFINITION mutation lock (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadProjectDefinitionForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const planRec = plan;
         migrateLegacyPolicyKey(planRec);
@@ -197,14 +165,14 @@ export function addIgnore(projectRoot, label) {
             planRec[PLAN_POLICY_KEY] = {};
         const policy = planRec[PLAN_POLICY_KEY];
         if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan.policy' key`);
         }
         const policyRec = policy;
         if (policyRec.triageScopeIgnores === undefined)
             policyRec.triageScopeIgnores = [];
         const raw = policyRec.triageScopeIgnores;
         if (!Array.isArray(raw)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScopeIgnores'`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-list 'plan.policy.triageScopeIgnores'`);
         }
         const before = snapshotRules(raw);
         for (const entry of raw) {
@@ -216,7 +184,7 @@ export function addIgnore(projectRoot, label) {
             }
         }
         raw.push({ label });
-        atomicWriteProjectDefinition(path, data);
+        mutation.persist(data);
         const after = snapshotRules(raw);
         recordSubscriptionChange(projectRoot, {
             op: "ignore-label",

package/dist/triage/scope-drift/add-ignore.js

@@ -1,39 +1,5 @@
-import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
-import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
-function loadForMutation(projectRoot) {
-    const path = resolveProjectDefinitionPath(resolve(projectRoot));
-    if (!existsSync(path)) {
-        throw new Error(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / task triage:bootstrap to scaffold one first.`);
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (err) {
-        throw new Error(`Could not read PROJECT-DEFINITION at ${path}: ${String(err)}`);
-    }
-    let data;
-    try {
-        data = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new Error(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(err)}`);
-    }
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-    }
-    return [data, path];
-}
-function atomicWrite(path, data) {
-    const dir = dirname(path);
-    const payload = `${JSON.stringify(data, null, 2)}\n`;
-    const tmp = join(dir, `.${Date.now()}.tmp`);
-    writeFileSync(tmp, payload, "utf8");
-    renameSync(tmp, path);
-}
+import { withProjectDefinitionMutation } from "../../vbrief-build/project-definition-mutation.js";
 /** Append a label/milestone ignore entry — mirrors Python `add_ignore`. */
 export function addIgnore(projectRoot, options) {
     const hasLabel = options.label !== undefined;
@@ -48,11 +14,11 @@ export function addIgnore(projectRoot, options) {
     }
     // Serialise the read-modify-write under the shared PROJECT-DEFINITION
     // mutation lock so concurrent mutators cannot lose an update (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const planRec = plan;
         migrateLegacyPolicyKey(planRec);
@@ -74,7 +40,7 @@ export function addIgnore(projectRoot, options) {
             }
         }
         raw.push({ [key]: value });
-        atomicWrite(path, data);
+        mutation.persist(data);
         return { changed: true, message: `added ignore (${key}=${value})` };
     });
 }

package/dist/triage/subscribe/index.d.ts

@@ -3,12 +3,9 @@ export declare const SUBSCRIPTION_HISTORY_SCHEMA = "deft.triage.subscription-cha
 export declare const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.json";
 /** Python ``!r``-style quoting for parity with triage_subscribe.py messages. */
 export declare function pyRepr(value: string): string;
-export declare class ProjectDefinitionIOError extends Error {
-    constructor(message: string);
-}
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 type TriageRule = Record<string, unknown>;
-export declare function loadProjectDefinitionForMutation(projectRoot: string): [Record<string, unknown>, string];
-export declare function atomicWriteProjectDefinition(path: string, data: Record<string, unknown>): void;
 export declare function recordSubscriptionChange(projectRoot: string, options: {
     op: string;
     label?: string | null;
@@ -34,5 +31,4 @@ export declare function unsubscribe(projectRoot: string, options?: {
     actor?: string | null;
 }): [boolean, string];
 export declare const RECONCILE_HINT: string;
-export {};
 //# sourceMappingURL=index.d.ts.map