@deftai/directive-core 0.88.0 → 0.90.0

package/dist/init-deposit/agent-hooks.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 import { isHostHookDepositEnabled, loadHostHooksPolicyFromProject, } from "../policy/host-hooks.js";
 export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
@@ -184,14 +185,32 @@ function mergeCursorConfig(config, path) {
     hooks.preCompact = [...preCompact, { command: command("cursor", "session.compact"), timeout: 5 }];
     return { ...config, version: 1, hooks };
 }
-function writeJsonIfChanged(path, payload) {
+function writeJsonIfChanged(projectRoot, path, payload) {
     const next = `${JSON.stringify(payload, null, 2)}\n`;
     if (existsSync(path) && readFileSync(path, "utf8") === next)
         return false;
-    mkdirSync(dirname(path), { recursive: true });
-    const temporary = `${path}.deft-${process.pid}.tmp`;
-    writeFileSync(temporary, next, "utf8");
-    renameSync(temporary, path);
+    // Atomic replace via temp under project root (#2951 / #2980 wave A).
+    const parent = dirname(path);
+    const tmpName = `${basename(path)}.deft-${process.pid}.tmp`;
+    const temporary = join(parent, tmpName);
+    try {
+        containedWrite({
+            root: resolve(projectRoot),
+            target: temporary,
+            data: next,
+            mode: "replace",
+        });
+        renameSync(temporary, path);
+    }
+    catch (err) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
     return true;
 }
 /** Merge Directive-owned project hook entries without replacing user configuration. */
@@ -247,7 +266,7 @@ export function writeAgentHookDeposit(projectRoot, io = { printf: () => undefine
     for (const item of prepared) {
         if (item.mode === "skip")
             continue;
-        if (writeJsonIfChanged(item.absolute, item.payload)) {
+        if (writeJsonIfChanged(projectRoot, item.absolute, item.payload)) {
             if (item.mode === "strip")
                 strippedPaths.push(item.path);
             else

package/dist/init-deposit/gitignore.js

@@ -9,8 +9,9 @@
  * Refs #1942, #1941, #1015, #1464, #1672.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { FORBIDDEN_BLANKET_EVAL_LINES, stripGitignoreInlineComment, } from "../triage/bootstrap/gitignore.js";
 /** Directory ignore entry for the hybrid deposit (greenfield only). */
@@ -196,8 +197,15 @@ function reconcileGitignoreFile(projectDir, targetLines, includeDeftCoreRational
         }
     }
     try {
+        // Keep early containment so ProjectionContainmentError type is preserved for callers/tests.
         assertWriteTargetSafe(projectDir, path);
-        writeFileSync(path, body, { encoding: "utf8", mode: 0o644 });
+        // #2980 wave A: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectDir),
+            target: path,
+            data: body,
+            mode: "replace",
+        });
     }
     catch (cause) {
         if (cause instanceof ProjectionContainmentError) {

package/dist/init-deposit/headless-manifest.js

@@ -22,10 +22,11 @@
  * emits a JSON error object so the calling backend can treat it as non-fatal
  * (never a crash or a partial write).
  */
-import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { ContentPackageNotFoundError, resolveInstalledContentRoot, } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { plan } from "../resolution/plan.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
@@ -233,8 +234,15 @@ export async function runInitHeadlessCli(options) {
             const abs = resolve(options.outputPath);
             const writeFile = options.writeFile ??
                 ((path, data) => {
-                    mkdirSync(dirname(path), { recursive: true });
-                    writeFileSync(path, data);
+                    // Contain under the output parent (arbitrary --output path; #2980 wave A).
+                    const parent = dirname(path);
+                    mkdirSync(parent, { recursive: true });
+                    containedWrite({
+                        root: resolve(parent),
+                        target: basename(path),
+                        data,
+                        mode: "replace",
+                    });
                 });
             writeFile(abs, serialized);
             options.writeErr(`directive init --headless: wrote ${manifest.files.length}-file manifest (v${manifest.version}) to ${abs}\n`);

package/dist/init-deposit/migrate.d.ts

@@ -49,7 +49,7 @@ export interface MigrateSeams {
     isFile?: (path: string) => boolean;
     /** Text read returning null on failure (default: node:fs readFileSync, utf8). */
     readText?: (path: string) => string | null;
-    /** Text write (default: node:fs writeFileSync, utf8). */
+    /** Text write (default: containedWrite under projectRoot; #2980 wave A). */
     writeText?: (path: string, text: string) => void;
     /** ISO-8601 UTC timestamp source for the backup filename (default: Date.now). */
     nowIso?: () => string;

package/dist/init-deposit/migrate.js

@@ -24,11 +24,12 @@
  *
  * Refs #1941, #1912 (freeze prerequisite b), #1933 (never-first-start), #1670.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveContentPackageRoot } from "../content-root.js";
 import { locateManifest, parseInstallManifest } from "../doctor/manifest.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { CANONICAL_INSTALL_ROOT } from "./scaffold.js";
 /**
  * The npm-managed handshake sentinel. `directive migrate` adds this key/value to
@@ -99,7 +100,16 @@ function engineMissingMessage() {
 export function runMigrate(projectRoot, seams = {}) {
     const isFile = seams.isFile ?? existsSync;
     const readText = seams.readText ?? defaultReadText;
-    const writeText = seams.writeText ?? ((path, text) => writeFileSync(path, text, "utf8"));
+    const writeText = seams.writeText ??
+        ((path, text) => {
+            // #2980 wave A: product write sink routes through containedWrite.
+            containedWrite({
+                root: resolve(projectRoot),
+                target: path,
+                data: text,
+                mode: "replace",
+            });
+        });
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
     const resolveEngine = seams.resolveEngine ?? defaultResolveEngine;
     const manifestPath = detectCanonicalVendoredManifest(projectRoot, isFile);

package/dist/init-deposit/prettierignore.js

@@ -7,8 +7,9 @@
  *
  * Refs #2534, #670.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
 /** Directory ignore entry for the hybrid deposit. */
@@ -72,7 +73,13 @@ export function ensurePrettierIgnoreLines(projectDir, io) {
         body += `${add}\n`;
     }
     try {
-        writeFileSync(path, body, { encoding: "utf8", mode: 0o644 });
+        // #2980 wave A: product write sink routes through containedWrite.
+        containedWrite({
+            root: resolve(projectDir),
+            target: path,
+            data: body,
+            mode: "replace",
+        });
     }
     catch (cause) {
         throw new Error(`could not write .prettierignore: ${String(cause)}`);

package/dist/init-deposit/scaffold.js

@@ -5,10 +5,11 @@
  * Refs #1942, #1430, #1463, #1179.
  */
 import { execFileSync } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
-import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { platform } from "node:os";
-import { dirname, join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertDestinationNotSymlink, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
@@ -27,6 +28,19 @@ function projectionTarget(projectDir, ...relSegments) {
     assertDestinationNotSymlink(projectDir, target);
     return target;
 }
+/**
+ * Product write sink: containment root is the project, then containedWrite
+ * (#2951 / #2980 wave A). Call after projectionTarget / assertDestinationNotSymlink
+ * when the early ProjectionContainmentError type is required by tests.
+ */
+function containedProjectWrite(projectDir, target, data) {
+    containedWrite({
+        root: resolve(projectDir),
+        target,
+        data,
+        mode: "replace",
+    });
+}
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
 const FRAMEWORK_SELF_TEST_REL = ".deft/core/tests";
@@ -219,9 +233,9 @@ export function writeInstallManifest(projectDir, deftDir, fields) {
         relative(projectDir, deftDir).split("\\").join("/") ||
         CANONICAL_INSTALL_ROOT;
     const body = buildInstallManifestText({ ...fields, installRoot });
-    mkdirSync(deftDir, { recursive: true });
     const path = join(deftDir, "VERSION");
-    writeFileSync(path, body, "utf8");
+    // #2980 wave A: product write sink routes through containedWrite.
+    containedProjectWrite(projectDir, path, body);
     return path;
 }
 /** Canonical committed pin dependency name (mirrors resolution/pin.ts). */
@@ -275,7 +289,7 @@ export function ensurePackageJsonPin(projectDir, version, io) {
     }
     devDeps[PIN_DEPENDENCY_NAME] = pinVersion;
     pkg.devDependencies = devDeps;
-    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+    containedProjectWrite(projectDir, path, `${JSON.stringify(pkg, null, 2)}\n`);
     io.printf(existed
         ? `package.json updated: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact).\n`
         : `package.json created: pinned ${PIN_DEPENDENCY_NAME}@${pinVersion} (exact, private).\n`);
@@ -296,7 +310,7 @@ export function writeAgentsMd(projectDir, deftDir, io) {
         throw new Error("AGENTS.md render produced no content");
     }
     const path = projectionTarget(projectDir, "AGENTS.md");
-    writeFileSync(path, newContent, "utf8");
+    containedProjectWrite(projectDir, path, newContent);
     if (state === "absent") {
         io.printf("AGENTS.md created.\n");
     }
@@ -320,7 +334,7 @@ async function ensureVbriefLifecycleDirs(projectDir) {
         const entries = await readdir(dir);
         if (entries.length > 0)
             continue;
-        await writeFile(gitkeep, VBRIEF_LIFECYCLE_GITKEEP, "utf8");
+        containedProjectWrite(projectDir, gitkeep, VBRIEF_LIFECYCLE_GITKEEP);
     }
 }
 function vbriefLifecycleDirsPresent(consumerVbrief) {
@@ -354,7 +368,7 @@ export async function writeConsumerVbrief(projectDir, deftDir, io) {
             copyFileSync(fwVbriefMd, vbriefMdDst);
         }
         else {
-            writeFileSync(vbriefMdDst, VBRIEF_README_BODY, "utf8");
+            containedProjectWrite(projectDir, vbriefMdDst, VBRIEF_README_BODY);
         }
     }
     await ensureVbriefLifecycleDirs(projectDir);
@@ -369,12 +383,10 @@ export function writeAgentsSkills(projectDir, io) {
         return false;
     }
     for (const skill of AGENTS_SKILLS) {
-        const dir = projectionTarget(projectDir, ".agents", "skills", skill.dir);
-        mkdirSync(dir, { recursive: true });
         const path = projectionTarget(projectDir, ".agents", "skills", skill.dir, "SKILL.md");
         if (existsSync(path))
             continue;
-        writeFileSync(path, skill.content, "utf8");
+        containedProjectWrite(projectDir, path, skill.content);
     }
     io.printf(".agents/skills/ created — deft skills will be auto-discovered.\n");
     return true;
@@ -459,21 +471,20 @@ export function ensureTaskfile(projectDir, io) {
                 "    optional: true\n";
         io.printf("Appended new `includes:` block with deft entry to Taskfile.yml (Epic-4).\n");
     }
-    writeFileSync(path, resultText, "utf8");
+    containedProjectWrite(projectDir, path, resultText);
     return true;
 }
 const HOOK_FILENAMES = ["pre-commit", "pre-push"];
 const HOOK_SUPPORT_FILENAMES = ["_deft-run.sh"];
 const HOOK_FILE_MODE = 0o755;
-const HOOK_SUPPORT_FILE_MODE = 0o644;
 export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
     const srcDir = join(deftDir, ".githooks");
     if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) {
         io.printf(`git hooks source ${srcDir} absent — skipping hook wiring.\n`);
         return false;
     }
-    const dstDir = projectionTarget(projectDir, ".githooks");
-    mkdirSync(dstDir, { recursive: true });
+    // Ensure parent path is containment-checked before any file write.
+    projectionTarget(projectDir, ".githooks");
     let filesDeposited = false;
     for (const name of [...HOOK_FILENAMES, ...HOOK_SUPPORT_FILENAMES]) {
         const src = join(srcDir, name);
@@ -484,8 +495,8 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
         const existing = existsSync(dst) ? readFileSync(dst) : null;
         const isHookScript = HOOK_FILENAMES.includes(name);
         if (!existing?.equals(data)) {
-            const mode = isHookScript ? HOOK_FILE_MODE : HOOK_SUPPORT_FILE_MODE;
-            writeFileSync(dst, data, { mode });
+            // #2980 wave A: containedWrite (mode is applied via chmod below for hooks).
+            containedProjectWrite(projectDir, dst, data);
             filesDeposited = true;
         }
         if (platform() !== "win32" && isHookScript) {
@@ -682,7 +693,7 @@ export function ensureGitattributes(projectDir, io) {
     for (const add of additions) {
         body += `${add}\n`;
     }
-    writeFileSync(path, body, "utf8");
+    containedProjectWrite(projectDir, path, body);
     io.printf(`.gitattributes updated with Deft core markers: ${additions.join(", ")}\n`);
     return true;
 }
@@ -725,7 +736,7 @@ export function ensureGreptileIgnore(projectDir, io) {
         return false;
     }
     obj.ignorePatterns = appendGreptilePattern(patterns, CORE_GLOB);
-    writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, "utf8");
+    containedProjectWrite(projectDir, path, `${JSON.stringify(obj, null, 2)}\n`);
     io.printf(fileExisted
         ? `greptile.json updated: bot review now ignores ${CORE_GLOB}.\n`
         : `greptile.json created: bot review ignores ${CORE_GLOB}.\n`);
@@ -774,8 +785,7 @@ function insertCodeqlPathsIgnore(content, glob) {
 export function ensureCodeqlPathsIgnore(projectDir, io) {
     const path = projectionTarget(projectDir, CODEQL_CONFIG_REL);
     if (!existsSync(path)) {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, codeqlConfigDefault(), "utf8");
+        containedProjectWrite(projectDir, path, codeqlConfigDefault());
         io.printf(`${CODEQL_CONFIG_REL} created: CodeQL ignores ${CORE_GLOB}.\n`);
         return true;
     }
@@ -788,7 +798,7 @@ export function ensureCodeqlPathsIgnore(projectDir, io) {
     const updated = inserted.ok
         ? inserted.content
         : `${existing}${existing.endsWith("\n") ? "" : "\n"}paths-ignore:\n  - '${CORE_GLOB}'\n`;
-    writeFileSync(path, updated, "utf8");
+    containedProjectWrite(projectDir, path, updated);
     io.printf(`${CODEQL_CONFIG_REL} updated: CodeQL now ignores ${CORE_GLOB}.\n`);
     return true;
 }
@@ -806,12 +816,11 @@ export function ensureCoreGuardWorkflow(projectDir, io) {
             io.printf(`${CORE_GUARD_WORKFLOW_REL} already current — skipping.\n`);
             return false;
         }
-        writeFileSync(path, refreshed, "utf8");
+        containedProjectWrite(projectDir, path, refreshed);
         io.printf(`${CORE_GUARD_WORKFLOW_REL} refreshed: deft-core-guard allowlist updated (#1478).\n`);
         return true;
     }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, desired, "utf8");
+    containedProjectWrite(projectDir, path, desired);
     io.printf(`${CORE_GUARD_WORKFLOW_REL} created: CI refuses PRs mixing ${CORE_GLOB} with app files.\n`);
     return true;
 }

package/dist/init-deposit/xbrief-projections.js

@@ -5,8 +5,9 @@
  * freshness. A current `.deft/core/VERSION` therefore cannot short-circuit
  * these repairs.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
@@ -66,6 +67,7 @@ export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationD
     }
 }
 function writeFileIfChanged(projectDir, target, content) {
+    // Keep early containment so ProjectionContainmentError type is preserved for callers/tests.
     assertDestinationNotSymlink(projectDir, target);
     const desired = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
     try {
@@ -75,8 +77,13 @@ function writeFileIfChanged(projectDir, target, content) {
     catch {
         // Missing or unreadable target is replaced below.
     }
-    mkdirSync(join(target, ".."), { recursive: true });
-    writeFileSync(target, desired);
+    // #2980 wave A: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectDir),
+        target,
+        data: desired,
+        mode: "replace",
+    });
     return true;
 }
 /**

package/dist/intake/candidates-log.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, containedWrite, } from "../fs/contained-write.js";
 import { pyRepr } from "../scm/py-format.js";
 import { resolveCandidatesLogPath } from "../triage/cache-path.js";
 function defaultLogPath() {
@@ -110,40 +111,45 @@ function validateEntry(entry) {
 function resolvePath(path) {
     return path !== undefined && path !== null ? resolve(path) : defaultLogPath();
 }
-function acquireAppendLock(logPath) {
+/**
+ * Cross-process exclusive lock via containedWrite mode=create (O_EXCL).
+ * #2980 wave B: lock + product appends route through containedWrite.
+ */
+function acquireAppendLock(logPath, containmentRoot) {
     while (threadLocked) {
         // spin-wait for in-process serialization
     }
     threadLocked = true;
-    const lockPath = join(dirname(logPath), `${logPath.split(/[/\\]/).pop()}.lock`);
+    const lockPath = resolve(dirname(logPath), `${basename(logPath)}.lock`);
     mkdirSync(dirname(lockPath), { recursive: true });
     const deadline = Date.now() + 30_000;
-    let fd = null;
-    while (fd === null) {
+    while (true) {
         try {
-            fd = openSync(lockPath, "wx");
-        }
-        catch {
-            if (Date.now() > deadline) {
-                threadLocked = false;
-                throw new CandidatesLogError("timed out acquiring candidates log lock");
-            }
-            const spinEnd = Date.now() + 20;
-            while (Date.now() < spinEnd) {
-                // brief spin
+            containedWrite({
+                root: containmentRoot,
+                target: lockPath,
+                data: "\0",
+                mode: "create",
+            });
+            break;
+        }
+        catch (err) {
+            if (err instanceof ContainedWriteError && err.code === ContainedWriteErrorCode.EXISTS) {
+                if (Date.now() > deadline) {
+                    threadLocked = false;
+                    throw new CandidatesLogError("timed out acquiring candidates log lock");
+                }
+                const spinEnd = Date.now() + 20;
+                while (Date.now() < spinEnd) {
+                    // brief spin
+                }
+                continue;
             }
+            threadLocked = false;
+            throw err;
         }
     }
-    writeSync(fd, Buffer.from("\0"));
     return () => {
-        try {
-            if (fd !== null) {
-                closeSync(fd);
-            }
-        }
-        catch {
-            // ignore
-        }
         try {
             unlinkSync(lockPath);
         }
@@ -153,24 +159,29 @@ function acquireAppendLock(logPath) {
         threadLocked = false;
     };
 }
+/** Ensure parent exists and return it as the containment root for log writes. */
+function containmentRootForLog(logPath) {
+    const parent = dirname(logPath);
+    mkdirSync(parent, { recursive: true });
+    return resolve(parent);
+}
 export function validateCandidatesEntry(entry) {
     validateEntry(entry);
 }
 export function append(entry, options = {}) {
     validateEntry(entry);
     const logPath = resolvePath(options.path);
-    mkdirSync(dirname(logPath), { recursive: true });
+    const root = containmentRootForLog(logPath);
     const line = JSON.stringify(entry, Object.keys(entry).sort());
-    const release = acquireAppendLock(logPath);
+    const release = acquireAppendLock(logPath, root);
     try {
-        const fd = openSync(logPath, "a");
-        try {
-            writeSync(fd, Buffer.from(`${line}\n`, "utf8"));
-            fsyncSync(fd);
-        }
-        finally {
-            closeSync(fd);
-        }
+        // #2980 wave B: product write sink routes through containedWrite.
+        containedWrite({
+            root,
+            target: logPath,
+            data: `${line}\n`,
+            mode: "append",
+        });
     }
     finally {
         release();

package/dist/intake/github-body-cli.d.ts

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
+/**
+ * Production entry for `task scm:body:*` / `directive github-body <subcommand>`.
+ * Dispatch peels the `github-body` verb; argv[0] is the subcommand
+ * (`issue-lint`, `pr-lint`, `issue-edit`, …). Wired through githubBodyMain
+ * so create/edit fail closed and lint commands share one encoding gate (#2960).
+ */
 export declare function mainEntry(argv?: string[]): number;
 //# sourceMappingURL=github-body-cli.d.ts.map

package/dist/intake/github-body-cli.js

@@ -19,9 +19,26 @@ function parseArgs(argv) {
             out.bodyFile = argv[++i];
         else if (arg === "--out-file")
             out.outFile = argv[++i];
+        else if (/^\d+$/.test(arg)) {
+            // Positional number: issue-lint / issue-* use --issue; pr-lint / pr-* use --pr (#2960).
+            const n = Number.parseInt(arg, 10);
+            if (out.command.startsWith("pr-")) {
+                if (out.pr === undefined)
+                    out.pr = n;
+            }
+            else if (out.issue === undefined) {
+                out.issue = n;
+            }
+        }
     }
     return out;
 }
+/**
+ * Production entry for `task scm:body:*` / `directive github-body <subcommand>`.
+ * Dispatch peels the `github-body` verb; argv[0] is the subcommand
+ * (`issue-lint`, `pr-lint`, `issue-edit`, …). Wired through githubBodyMain
+ * so create/edit fail closed and lint commands share one encoding gate (#2960).
+ */
 export function mainEntry(argv = process.argv.slice(2)) {
     const parsed = parseArgs(argv);
     return githubBodyMain(parsed);

package/dist/intake/github-body.d.ts

@@ -1,6 +1,12 @@
+import { type Finding } from "../encoding/scan.js";
 export declare const DEFAULT_TIMEOUT_SECONDS = 60;
+/** Stable error code for CP1252/CP437-as-UTF-8 / U+FFFD body corruption (#2960). */
+export declare const SCM_BODY_ENCODING_CODE = "scm-body-encoding";
 export declare class GitHubBodyError extends Error {
-    constructor(message: string);
+    readonly code?: string;
+    constructor(message: string, options?: {
+        code?: string;
+    });
 }
 export type RunGhApiFn = (args: readonly string[], options?: {
     inputText?: string | null;
@@ -9,7 +15,22 @@ export type RunGhApiFn = (args: readonly string[], options?: {
 /** Resolve the live GitHub CLI used for writes and mutation read-back. */
 export declare function resolveLiveGh(): string;
 export declare function readBody(bodyFile: string, stdinText?: string | null): string;
-/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607). */
+/** Strip a leading UTF-8 BOM so body-file writers stay UTF-8 no BOM (#2960 / #798). */
+export declare function stripUtf8Bom(text: string): string;
+/**
+ * Scan body text with the same mojibake pattern set as verify:encoding
+ * (`packages/core/src/encoding/patterns.ts` / scanLine). Issue/PR bodies are
+ * Markdown: strip fenced blocks and inline code spans so documented examples
+ * of the corruption class (e.g. `#2960` fixtures) are not false positives —
+ * matches `scanFile` .md behavior.
+ */
+export declare function scanBodyText(body: string, source?: string): Finding[];
+/**
+ * Fail closed when body text already contains CP1252/CP437-as-UTF-8 mojibake
+ * or U+FFFD (before PATCH and as a live-body diagnostic).
+ */
+export declare function assertBodyEncoding(body: string, phase: string): void;
+/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607 / #2960). */
 export declare function verifyBodyPostcondition(intended: string, live: string): void;
 export declare function createIssue(repo: string, options: {
     title: string;
@@ -41,10 +62,29 @@ export declare function fetchIssueBody(repo: string, issue: number, options?: {
     binary?: string | null;
     runFn?: RunGhApiFn;
 }): string;
+export declare function fetchPrBody(repo: string, pr: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): string;
 export declare function writeIssueBodyToFile(repo: string, issue: number, outFile: string, options?: {
     binary?: string | null;
     runFn?: RunGhApiFn;
 }): string;
+/**
+ * Lint a live issue body for mojibake. Returns findings (empty = clean).
+ * Does not throw on hits — callers decide exit code.
+ */
+export declare function lintIssueBody(repo: string, issue: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): Finding[];
+/**
+ * Lint a live PR body for mojibake. Returns findings (empty = clean).
+ */
+export declare function lintPrBody(repo: string, pr: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): Finding[];
 export interface GitHubBodyCliArgs {
     command: string;
     repo?: string;
@@ -55,5 +95,8 @@ export interface GitHubBodyCliArgs {
     bodyFile?: string;
     outFile?: string;
 }
-export declare function githubBodyMain(args: GitHubBodyCliArgs): number;
+export declare function githubBodyMain(args: GitHubBodyCliArgs, options?: {
+    runFn?: RunGhApiFn;
+    binary?: string | null;
+}): number;
 //# sourceMappingURL=github-body.d.ts.map