@deftai/directive-core 0.88.0 → 0.90.0

package/dist/intake/github-body.js

@@ -1,11 +1,19 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { renderFinding, scanLine } from "../encoding/scan.js";
+import { pythonSplitlines, stripMarkdownQuotes } from "../encoding/text.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { defaultWhich } from "../scm/binary.js";
 import { call } from "../scm/call.js";
 export const DEFAULT_TIMEOUT_SECONDS = 60;
+/** Stable error code for CP1252/CP437-as-UTF-8 / U+FFFD body corruption (#2960). */
+export const SCM_BODY_ENCODING_CODE = "scm-body-encoding";
 export class GitHubBodyError extends Error {
-    constructor(message) {
+    code;
+    constructor(message, options) {
         super(message);
         this.name = "GitHubBodyError";
+        this.code = options?.code;
     }
 }
 function splitRepo(repo) {
@@ -24,9 +32,54 @@ export function resolveLiveGh() {
 }
 export function readBody(bodyFile, stdinText) {
     if (bodyFile === "-") {
-        return stdinText ?? "";
+        return stripUtf8Bom(stdinText ?? "");
     }
-    return readFileSync(bodyFile, "utf8");
+    return stripUtf8Bom(readFileSync(bodyFile, "utf8"));
+}
+/** Strip a leading UTF-8 BOM so body-file writers stay UTF-8 no BOM (#2960 / #798). */
+export function stripUtf8Bom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * 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 function scanBodyText(body, source = "body") {
+    const findings = [];
+    const scanText = stripMarkdownQuotes(body);
+    const originalLines = pythonSplitlines(body);
+    const strippedLines = pythonSplitlines(scanText);
+    if (originalLines.length === 0 && body.length > 0) {
+        findings.push(...scanLine(source, 1, scanText, body));
+        return findings;
+    }
+    // Preserve line alignment when strip blanks fenced blocks (newline-for-newline).
+    while (strippedLines.length < originalLines.length) {
+        strippedLines.push("");
+    }
+    originalLines.forEach((orig, idx) => {
+        const stripped = strippedLines[idx] ?? "";
+        findings.push(...scanLine(source, idx + 1, stripped, orig));
+    });
+    return findings;
+}
+function formatEncodingFindings(findings) {
+    return findings.map((f) => renderFinding(f).trim()).join("; ");
+}
+/**
+ * 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 function assertBodyEncoding(body, phase) {
+    const findings = scanBodyText(body, phase);
+    if (findings.length === 0) {
+        return;
+    }
+    const detail = formatEncodingFindings(findings);
+    throw new GitHubBodyError(`body encoding failed (${phase}): ${detail}. Repair: task scm:body:issue:fetch -- --repo OWNER/REPO --issue N --out-file <path>, fix as UTF-8 (no BOM), task scm:body:issue:edit -- --body-file <path> (#2960 / #2948 / #2944).`, { code: SCM_BODY_ENCODING_CODE });
 }
 function jsonInput(payload) {
     return JSON.stringify(payload);
@@ -73,10 +126,14 @@ function requireIntField(obj, field) {
     }
     return value;
 }
-function requireStringField(obj, field) {
-    const value = obj[field];
+/** Body may be null on empty GitHub issues/PRs — treat as empty string for lint/fetch. */
+function bodyFieldOrEmpty(obj) {
+    const value = obj.body;
+    if (value === null || value === undefined) {
+        return "";
+    }
     if (typeof value !== "string") {
-        throw new GitHubBodyError(`response did not include string field ${JSON.stringify(field)}`);
+        throw new GitHubBodyError(`response did not include string field "body"`);
     }
     return value;
 }
@@ -91,7 +148,7 @@ function countNewlines(text) {
 function normalizeNewlines(text) {
     return text.replace(/\r\n/g, "\n");
 }
-/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607). */
+/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607 / #2960). */
 export function verifyBodyPostcondition(intended, live) {
     if (intended === live) {
         return;
@@ -103,6 +160,11 @@ export function verifyBodyPostcondition(intended, live) {
     if (live.includes("\uFFFD") && !intended.includes("\uFFFD")) {
         diagnoses.push("live body contains U+FFFD replacement character not present in intended payload");
     }
+    const liveFindings = scanBodyText(live, "live");
+    const intendedFindings = scanBodyText(intended, "intended");
+    if (liveFindings.length > 0 && intendedFindings.length === 0) {
+        diagnoses.push(`live body contains mojibake not present in intended payload (${formatEncodingFindings(liveFindings)})`);
+    }
     const intendedNl = countNewlines(intended);
     const liveNl = countNewlines(live);
     if (intendedNl > 0 && liveNl < intendedNl) {
@@ -112,12 +174,19 @@ export function verifyBodyPostcondition(intended, live) {
         diagnoses.push("live body looks like intended newlines were collapsed to spaces (PowerShell string[] join)");
     }
     if (diagnoses.length > 0) {
-        throw new GitHubBodyError(`body postcondition failed: ${diagnoses.join("; ")}`);
+        const isEncoding = diagnoses.some((d) => d.includes("U+FFFD") || d.includes("mojibake") || d.includes("encoding"));
+        throw new GitHubBodyError(`body postcondition failed: ${diagnoses.join("; ")}`, {
+            code: isEncoding ? SCM_BODY_ENCODING_CODE : undefined,
+        });
     }
     throw new GitHubBodyError(`body postcondition failed: re-fetched body does not match intended payload (length intended=${intended.length}, live=${live.length})`);
 }
 function mutateWithReadback(mutationEndpoint, method, payload, readbackEndpoint, options = {}) {
     const intendedBody = typeof payload.body === "string" ? payload.body : undefined;
+    if (intendedBody !== undefined) {
+        // Fail closed before PATCH when the intended payload is already corrupted (#2960).
+        assertBodyEncoding(intendedBody, "pre-write");
+    }
     const mutation = runGhApiJson([mutationEndpoint, "--method", method, "--input", "-"], {
         inputText: jsonInput(payload),
         binary: options.binary,
@@ -126,7 +195,10 @@ function mutateWithReadback(mutationEndpoint, method, payload, readbackEndpoint,
     const endpoint = typeof readbackEndpoint === "function" ? readbackEndpoint(mutation) : readbackEndpoint;
     const readback = runGhApiJson([endpoint], { binary: options.binary, runFn: options.runFn });
     if (intendedBody !== undefined) {
-        verifyBodyPostcondition(intendedBody, requireStringField(readback, "body"));
+        const liveBody = bodyFieldOrEmpty(readback);
+        verifyBodyPostcondition(intendedBody, liveBody);
+        // Defense in depth: live body must also be free of encoding corruption.
+        assertBodyEncoding(liveBody, "post-write-readback");
     }
     return readback;
 }
@@ -168,14 +240,52 @@ export function fetchIssueBody(repo, issue, options = {}) {
     const [owner, name] = splitRepo(repo);
     const endpoint = `repos/${owner}/${name}/issues/${issue}`;
     const response = runGhApiJson([endpoint], { binary: options.binary, runFn: options.runFn });
-    return requireStringField(response, "body");
+    return bodyFieldOrEmpty(response);
+}
+export function fetchPrBody(repo, pr, options = {}) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/pulls/${pr}`;
+    const response = runGhApiJson([endpoint], { binary: options.binary, runFn: options.runFn });
+    return bodyFieldOrEmpty(response);
 }
 export function writeIssueBodyToFile(repo, issue, outFile, options = {}) {
     const body = fetchIssueBody(repo, issue, options);
-    writeFileSync(outFile, body, { encoding: "utf8" });
+    // UTF-8 no BOM (Node default for encoding: "utf8").
+    // #2980 wave B: product write sink routes through containedWrite under out-file parent.
+    const abs = resolve(outFile);
+    const parent = dirname(abs);
+    mkdirSync(parent, { recursive: true });
+    containedWrite({
+        root: parent,
+        target: abs,
+        data: body,
+        mode: "replace",
+    });
     return body;
 }
-export function githubBodyMain(args) {
+/**
+ * Lint a live issue body for mojibake. Returns findings (empty = clean).
+ * Does not throw on hits — callers decide exit code.
+ */
+export function lintIssueBody(repo, issue, options = {}) {
+    const body = fetchIssueBody(repo, issue, options);
+    return scanBodyText(body, `issue/${issue}`);
+}
+/**
+ * Lint a live PR body for mojibake. Returns findings (empty = clean).
+ */
+export function lintPrBody(repo, pr, options = {}) {
+    const body = fetchPrBody(repo, pr, options);
+    return scanBodyText(body, `pr/${pr}`);
+}
+function writeLintFailure(kind, id, findings) {
+    process.stderr.write(`error [${SCM_BODY_ENCODING_CODE}]: ${kind} #${id} body contains encoding mojibake (${findings.length} hit(s)):\n`);
+    for (const f of findings) {
+        process.stderr.write(`${renderFinding(f)}\n`);
+    }
+    process.stderr.write(`Repair: task scm:body:issue:fetch -- --repo OWNER/REPO --issue ${id} --out-file <path>, fix as UTF-8 (no BOM), task scm:body:issue:edit -- --body-file <path>. After non-scm:body mutations, re-run lint (#2960; recurrence #2948/#2944).\n`);
+}
+export function githubBodyMain(args, options = {}) {
     try {
         switch (args.command) {
             case "issue-fetch": {
@@ -183,7 +293,42 @@ export function githubBodyMain(args) {
                     process.stderr.write("error: issue-fetch requires --repo, --issue, and --out-file\n");
                     return 1;
                 }
-                writeIssueBodyToFile(args.repo, args.issue, args.outFile);
+                writeIssueBodyToFile(args.repo, args.issue, args.outFile, {
+                    runFn: options.runFn,
+                    binary: options.binary,
+                });
+                return 0;
+            }
+            case "issue-lint": {
+                if (args.repo === undefined || args.issue === undefined) {
+                    process.stderr.write("error: issue-lint requires --repo and --issue\n");
+                    return 1;
+                }
+                const findings = lintIssueBody(args.repo, args.issue, {
+                    runFn: options.runFn,
+                    binary: options.binary,
+                });
+                if (findings.length > 0) {
+                    writeLintFailure("issue", args.issue, findings);
+                    return 1;
+                }
+                process.stdout.write(`ok: issue #${args.issue} body has no CP1252/CP437-as-UTF-8 mojibake\n`);
+                return 0;
+            }
+            case "pr-lint": {
+                if (args.repo === undefined || args.pr === undefined) {
+                    process.stderr.write("error: pr-lint requires --repo and --pr\n");
+                    return 1;
+                }
+                const findings = lintPrBody(args.repo, args.pr, {
+                    runFn: options.runFn,
+                    binary: options.binary,
+                });
+                if (findings.length > 0) {
+                    writeLintFailure("pr", args.pr, findings);
+                    return 1;
+                }
+                process.stdout.write(`ok: pr #${args.pr} body has no CP1252/CP437-as-UTF-8 mojibake\n`);
                 return 0;
             }
             default: {
@@ -191,19 +336,40 @@ export function githubBodyMain(args) {
                 let result;
                 switch (args.command) {
                     case "issue-create":
-                        result = createIssue(args.repo, { title: args.title, body });
+                        result = createIssue(args.repo, {
+                            title: args.title,
+                            body,
+                            runFn: options.runFn,
+                            binary: options.binary,
+                        });
                         break;
                     case "issue-edit":
-                        result = editIssueBody(args.repo, args.issue, { body });
+                        result = editIssueBody(args.repo, args.issue, {
+                            body,
+                            runFn: options.runFn,
+                            binary: options.binary,
+                        });
                         break;
                     case "comment-create":
-                        result = createIssueComment(args.repo, args.issue, { body });
+                        result = createIssueComment(args.repo, args.issue, {
+                            body,
+                            runFn: options.runFn,
+                            binary: options.binary,
+                        });
                         break;
                     case "comment-edit":
-                        result = editIssueCommentBody(args.repo, args.comment, { body });
+                        result = editIssueCommentBody(args.repo, args.comment, {
+                            body,
+                            runFn: options.runFn,
+                            binary: options.binary,
+                        });
                         break;
                     case "pr-edit":
-                        result = editPrBody(args.repo, args.pr, { body });
+                        result = editPrBody(args.repo, args.pr, {
+                            body,
+                            runFn: options.runFn,
+                            binary: options.binary,
+                        });
                         break;
                     default:
                         process.stderr.write(`error: unknown command ${JSON.stringify(args.command)}\n`);
@@ -215,7 +381,12 @@ export function githubBodyMain(args) {
         }
     }
     catch (exc) {
-        process.stderr.write(`error: ${String(exc)}\n`);
+        if (exc instanceof GitHubBodyError && exc.code !== undefined) {
+            process.stderr.write(`error [${exc.code}]: ${exc.message}\n`);
+        }
+        else {
+            process.stderr.write(`error: ${String(exc)}\n`);
+        }
         return 1;
     }
 }

package/dist/intake/issue-emit.d.ts

@@ -44,6 +44,7 @@ export declare function assertVbriefWriteTargetSafe(path: string, projectRoot?:
 /**
  * Persist an xBRIEF/vBRIEF JSON document. Gates the write target so a leaf or
  * parent-directory symlink cannot divert the stamped file outside the project (#2869).
+ * #2980 wave B: product write sink routes through containedWrite.
  */
 export declare function writeVbrief(path: string, data: Record<string, unknown>, projectRoot?: string | null): void;
 export declare function vbriefTitle(data: Record<string, unknown>): string;

package/dist/intake/issue-emit.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
-import { chmodSync, closeSync, constants, globSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import { chmodSync, globSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -83,7 +84,8 @@ export function recoverySidecarPath(vbriefAbsPath) {
 }
 /**
  * Write recovery sidecar without following symlinks (#2880 Greptile P1).
- * Trusted per-uid dir (ownership + mode) + O_EXCL|O_NOFOLLOW create.
+ * Trusted per-uid dir (ownership + mode) + containedWrite create (O_EXCL|O_NOFOLLOW).
+ * #2980 wave B: product write sink routes through containedWrite.
  */
 function writeRecoverySidecarSafe(sidePath, payload) {
     const dir = ensureTrustedRecoveryDir();
@@ -107,17 +109,12 @@ function writeRecoverySidecarSafe(sidePath, payload) {
             throw err;
         }
     }
-    let flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
-    if (typeof constants.O_NOFOLLOW === "number") {
-        flags |= constants.O_NOFOLLOW;
-    }
-    const fd = openSync(sidePath, flags, 0o600);
-    try {
-        writeSync(fd, payload, undefined, "utf8");
-    }
-    finally {
-        closeSync(fd);
-    }
+    containedWrite({
+        root: dir,
+        target: sidePath,
+        data: payload,
+        mode: "create",
+    });
 }
 /**
  * Always-on recovery after remote create: process memory + private OS-temp sidecar.
@@ -250,15 +247,20 @@ export function loadPendingEmitUrls(projectRoot) {
     return {};
 }
 export function savePendingEmitUrl(projectRoot, vbriefAbsPath, url) {
+    const root = resolve(projectRoot);
     const ledger = pendingEmitLedgerPath(projectRoot);
-    assertWriteTargetSafe(projectRoot, ledger);
-    mkdirSync(dirname(ledger), { recursive: true });
     const map = loadPendingEmitUrls(projectRoot);
     map[resolve(vbriefAbsPath)] = url;
-    assertWriteTargetSafe(projectRoot, ledger);
-    writeFileSync(ledger, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+    // #2980 wave B: product write sink routes through containedWrite.
+    containedWrite({
+        root,
+        target: ledger,
+        data: `${JSON.stringify(map, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 export function clearPendingEmitUrl(projectRoot, vbriefAbsPath) {
+    const root = resolve(projectRoot);
     const ledger = pendingEmitLedgerPath(projectRoot);
     const key = resolve(vbriefAbsPath);
     const map = loadPendingEmitUrls(projectRoot);
@@ -267,9 +269,13 @@ export function clearPendingEmitUrl(projectRoot, vbriefAbsPath) {
     }
     delete map[key];
     try {
-        assertWriteTargetSafe(projectRoot, ledger);
-        mkdirSync(dirname(ledger), { recursive: true });
-        writeFileSync(ledger, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+        // #2980 wave B: product write sink routes through containedWrite.
+        containedWrite({
+            root,
+            target: ledger,
+            data: `${JSON.stringify(map, null, 2)}\n`,
+            mode: "replace",
+        });
     }
     catch {
         // Best-effort clear; next successful stamp still works via existingGithubIssueRef.
@@ -310,10 +316,16 @@ export function assertVbriefWriteTargetSafe(path, projectRoot) {
 /**
  * Persist an xBRIEF/vBRIEF JSON document. Gates the write target so a leaf or
  * parent-directory symlink cannot divert the stamped file outside the project (#2869).
+ * #2980 wave B: product write sink routes through containedWrite.
  */
 export function writeVbrief(path, data, projectRoot) {
-    assertVbriefWriteTargetSafe(path, projectRoot);
-    writeFileSync(resolve(path), `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    const root = assertVbriefWriteTargetSafe(path, projectRoot);
+    containedWrite({
+        root,
+        target: resolve(path),
+        data: `${JSON.stringify(data, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 export function vbriefTitle(data) {
     const plan = (data.plan ?? {});
@@ -417,7 +429,13 @@ export function fileIssue(repo, title, body, scmCall = call) {
     const tmpDir = mkdtempSync(join(tmpdir(), "deft-issue-emit-"));
     const bodyPath = join(tmpDir, "body.md");
     try {
-        writeFileSync(bodyPath, body, "utf8");
+        // #2980 wave B: temp body file via containedWrite under the OS-temp dir.
+        containedWrite({
+            root: tmpDir,
+            target: "body.md",
+            data: body,
+            mode: "create",
+        });
         const result = scmCall("github-issue", "issue", ["create", "--repo", repo, "--title", title, "--body-file", bodyPath], { timeout: 60 });
         if (result.returncode !== 0) {
             throw new IssueEmitError(`gh issue create failed (exit ${result.returncode}): ${(result.stderr ?? "").trim()}`);

package/dist/lifecycle/event-detect.js

@@ -1,7 +1,8 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
 /** Sentinel used by SKILL.md redirect stubs. */
 export const DEPRECATED_SKILL_REDIRECT_SENTINEL = "<!-- deft:deprecated-skill-redirect -->";
@@ -87,9 +88,16 @@ export function emit(name, payload = null, options = {}) {
     const logTarget = process.env[logPathEnv];
     if (logTarget !== undefined && logTarget.length > 0) {
         try {
+            // #2980 wave D: product write sink routes through containedWrite.
             const logPath = resolve(logTarget);
-            mkdirSync(dirname(logPath), { recursive: true });
-            appendFileSync(logPath, `${JSON.stringify(record)}\n`, "utf8");
+            const dir = dirname(logPath);
+            mkdirSync(dir, { recursive: true });
+            containedWrite({
+                root: dir,
+                target: basename(logPath),
+                data: `${JSON.stringify(record)}\n`,
+                mode: "append",
+            });
         }
         catch {
             // Swallow log-write failures.

package/dist/lifecycle/events.js

@@ -1,15 +1,18 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync, } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
 import { ATTRIBUTION_REQUIRED_PAYLOAD } from "../events/attribution-constants.js";
-import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
+import { PROCESS_COST_REQUIRED_PAYLOAD } from "../session/process-cost-constants.js";
 /** Default event log location (project-local). */
 export const DEFAULT_EVENT_LOG = join(".deft-cache", "events.jsonl");
 const BEHAVIORAL_CATEGORY = "behavioral";
 const REQUIRED_BEHAVIORAL_PAYLOAD = {
     ...ATTRIBUTION_REQUIRED_PAYLOAD,
+    ...PROCESS_COST_REQUIRED_PAYLOAD,
     "session:interrupted": ["session_id", "reason"],
     "session:resumed": ["session_id", "interrupted_id"],
     "plan:approved": ["plan_ref", "approver"],
@@ -166,22 +169,32 @@ function assertPathComponentsNotSymlinks(projectDir, targetPath) {
         }
     }
 }
-/** Refuse symlink write targets for project-owned and explicit event logs (#2766). */
-function assertEventLogTargetSafe(projectRoot, targetPath) {
-    if (isNestedUnder(projectRoot, targetPath)) {
-        assertWriteTargetSafe(projectRoot, targetPath);
+/**
+ * Append one event log line via containedWrite (#2951 Phase 2).
+ * Project-nested logs use projectRoot as containment root; explicit external
+ * logs still refuse symlink path components, then contain under the log parent.
+ */
+function appendEventLogLine(projectRoot, targetPath, line) {
+    const targetAbs = resolve(targetPath);
+    if (isNestedUnder(projectRoot, targetAbs)) {
+        containedWrite({
+            root: resolve(projectRoot),
+            target: targetAbs,
+            data: line,
+            mode: "append",
+        });
         return;
     }
-    assertPathComponentsNotSymlinks(projectRoot, targetPath);
-}
-function appendLineNoFollow(target, line) {
-    const fd = openSync(target, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 0o644);
-    try {
-        writeSync(fd, Buffer.from(line, "utf8"));
-    }
-    finally {
-        closeSync(fd);
-    }
+    // Explicit --log / DEFT_EVENT_LOG outside the project tree.
+    assertPathComponentsNotSymlinks(projectRoot, targetAbs);
+    const parent = dirname(targetAbs);
+    mkdirSync(parent, { recursive: true });
+    containedWrite({
+        root: resolve(parent),
+        target: basename(targetAbs),
+        data: line,
+        mode: "append",
+    });
 }
 function newEventId() {
     const wallNs = BigInt(Date.now()) * 1000000n;
@@ -210,9 +223,7 @@ export function emit(name, payload, options = {}) {
     };
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
     const target = resolveLogPath(options.logPath, projectRoot);
-    assertEventLogTargetSafe(projectRoot, target);
-    mkdirSync(dirname(target), { recursive: true });
-    appendLineNoFollow(target, `${jsonStringifySorted(record)}\n`);
+    appendEventLogLine(projectRoot, target, `${jsonStringifySorted(record)}\n`);
     return record;
 }
 /** Return all events from the log in emission order. */

package/dist/lifecycle/index.d.ts

@@ -2,4 +2,5 @@ export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";
 export * as lifecycleHygiene from "./lifecycle-hygiene.js";
+export * from "./stats.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.js

@@ -2,4 +2,5 @@ export * from "./event.js";
 export * as eventDetect from "./event-detect.js";
 export * as events from "./events.js";
 export * as lifecycleHygiene from "./lifecycle-hygiene.js";
+export * from "./stats.js";
 //# sourceMappingURL=index.js.map

package/dist/lifecycle/lifecycle-hygiene.js

@@ -1,7 +1,8 @@
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { computeReport } from "../capacity/show.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { resolveCapacityAllocation } from "../policy/capacity.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
@@ -202,14 +203,19 @@ export function recordTechDebtAcceptance(projectRoot, epic, options) {
         throw new Error("follow_up_ref must be a non-empty reference string");
     }
     const path = techDebtLedgerPath(projectRoot);
-    mkdirSync(resolve(path, ".."), { recursive: true });
     const record = {
         accepted_at: utcIso(options.now ?? null),
         actor: options.actor ?? DEFAULT_ACTOR,
         epic: epicKey,
         follow_up_ref: followUpRef.trim(),
     };
-    appendFileSync(path, `${JSON.stringify(sortKeys(record))}\n`, "utf8");
+    // #2980 wave D: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: `${JSON.stringify(sortKeys(record))}\n`,
+        mode: "append",
+    });
     return path;
 }
 /** Return the set of epic basenames already accepted as tech-debt. */

package/dist/lifecycle/stats.d.ts

@@ -0,0 +1,53 @@
+import { parseDurationMs } from "../triage/scope/duration.js";
+/** Lifecycle folders scanned for stats. */
+export declare const STATS_LIFECYCLE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+export type StatsLifecycleFolder = (typeof STATS_LIFECYCLE_FOLDERS)[number];
+/** Count semantics for WWYSYDH / process forms (stable strings for --json). */
+export declare const LIFECYCLE_STATS_SEMANTICS: {
+    readonly promoted: string;
+    readonly activated: string;
+    readonly completed: string;
+    readonly cancelled_or_failed: string;
+    readonly still_active: "snapshot count of all xbriefs currently in active/ (not filtered by --since).";
+    readonly event_time: string;
+    readonly note: string;
+};
+export interface LifecycleFolderTotals {
+    readonly proposed: number;
+    readonly pending: number;
+    readonly active: number;
+    readonly completed: number;
+    readonly cancelled: number;
+}
+export interface LifecycleStats {
+    readonly since: string;
+    readonly since_ms: number;
+    readonly as_of: string;
+    readonly window_start: string;
+    readonly project_root: string;
+    readonly lifecycle_root: string;
+    readonly promoted: number;
+    readonly activated: number;
+    readonly completed: number;
+    readonly cancelled_or_failed: number;
+    readonly still_active: number;
+    readonly folder_totals: LifecycleFolderTotals;
+    readonly semantics: typeof LIFECYCLE_STATS_SEMANTICS;
+}
+export interface CollectLifecycleStatsOptions {
+    readonly projectRoot: string;
+    /** Window duration string, e.g. "7d", "24h", "1w". Default "7d". */
+    readonly since?: string;
+    /** Clock for window end (tests inject a fixed Date). */
+    readonly now?: Date;
+}
+/**
+ * Collect lifecycle folder stats for a project root.
+ * Offline / filesystem only.
+ */
+export declare function collectLifecycleStats(options: CollectLifecycleStatsOptions): LifecycleStats;
+/** Format human-readable lifecycle stats text. */
+export declare function formatLifecycleStatsText(stats: LifecycleStats): string;
+/** Re-export duration parse for CLI error messaging. */
+export { parseDurationMs };
+//# sourceMappingURL=stats.d.ts.map