@deftai/directive-core 0.86.0 → 0.87.0

package/dist/intake/issue-emit.js

@@ -1,17 +1,278 @@
-import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, constants, globSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
 export const GITHUB_ISSUE_REF_TYPE = "x-xbrief/github-issue";
 export const EXTERNAL_TRUST_LEVEL = "external";
 const ISSUE_URL_PATTERN = /https?:\/\/\S+?\/issues\/\d+/;
+/**
+ * Structured post-create failure: remote issue exists; local stamp/ledger may not.
+ * `createdUrl` is the durable handle for retry (also mirrored in process + OS-temp recovery).
+ */
 export class IssueEmitError extends Error {
-    constructor(message) {
+    createdUrl;
+    constructor(message, options) {
         super(message);
         this.name = "IssueEmitError";
+        if (options?.createdUrl !== undefined && options.createdUrl.length > 0) {
+            this.createdUrl = options.createdUrl;
+        }
+    }
+}
+/**
+ * Process-local fallback for post-create URL when project ledger and xBRIEF stamp both fail (#2880).
+ * Survives same-process retry without re-create; paired with private OS-temp sidecar for restarts.
+ */
+const processPendingUrls = new Map();
+/** Vitest-only failure injection via env (not a production export surface). */
+function testFailProjectLedger() {
+    return process.env.VITEST === "true" && process.env.DEFT_ISSUE_EMIT_TEST_FAIL_LEDGER === "1";
+}
+function testFailStamp() {
+    return process.env.VITEST === "true" && process.env.DEFT_ISSUE_EMIT_TEST_FAIL_STAMP === "1";
+}
+function privateRecoveryRoot() {
+    const base = typeof process.env.XDG_RUNTIME_DIR === "string" && process.env.XDG_RUNTIME_DIR.length > 0
+        ? process.env.XDG_RUNTIME_DIR
+        : tmpdir();
+    const uid = typeof process.getuid === "function" ? String(process.getuid()) : "u";
+    return join(base, `deft-issue-emit-recovery-${uid}`);
+}
+/** Refuse dirs/files we do not own or that are group/other-writable (forged recovery, #2880). */
+function isTrustedStat(st) {
+    if (st.isSymbolicLink()) {
+        return false;
+    }
+    if (typeof process.getuid === "function" && typeof st.uid === "number") {
+        if (st.uid !== process.getuid()) {
+            return false;
+        }
+    }
+    // Group/other write bits allow another local principal to rewrite recovery state.
+    const mode = Number(st.mode);
+    if ((mode & 0o022) !== 0) {
+        return false;
+    }
+    return true;
+}
+function ensureTrustedRecoveryDir() {
+    const dir = privateRecoveryRoot();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dirStat = lstatSync(dir);
+    if (!isTrustedStat(dirStat) || !dirStat.isDirectory()) {
+        throw new Error("issue-emit recovery dir is not a trusted directory owned by the current user");
+    }
+    if ((dirStat.mode & 0o777) !== 0o700) {
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // Best-effort tighten; isTrustedStat already refused group/other write.
+        }
+    }
+    return dir;
+}
+export function recoverySidecarPath(vbriefAbsPath) {
+    const key = createHash("sha256").update(resolve(vbriefAbsPath)).digest("hex").slice(0, 40);
+    return join(privateRecoveryRoot(), `${key}.json`);
+}
+/**
+ * Write recovery sidecar without following symlinks (#2880 Greptile P1).
+ * Trusted per-uid dir (ownership + mode) + O_EXCL|O_NOFOLLOW create.
+ */
+function writeRecoverySidecarSafe(sidePath, payload) {
+    const dir = ensureTrustedRecoveryDir();
+    if (resolve(dirname(sidePath)) !== resolve(dir)) {
+        // Always write under the validated recovery root.
+        throw new Error("issue-emit recovery path escapes trusted root");
+    }
+    try {
+        const existing = lstatSync(sidePath);
+        if (existing.isSymbolicLink() || existing.isFile()) {
+            // unlink of a symlink removes the link itself (does not follow).
+            unlinkSync(sidePath);
+        }
+        else {
+            throw new Error("issue-emit recovery path exists and is not a regular file");
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            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);
+    }
+}
+/**
+ * Always-on recovery after remote create: process memory + private OS-temp sidecar.
+ * Independent of project-contained ledger so dual local failure still reconciles on retry (#2880).
+ */
+export function rememberCreatedUrl(vbriefAbsPath, url) {
+    const key = resolve(vbriefAbsPath);
+    processPendingUrls.set(key, url);
+    try {
+        writeRecoverySidecarSafe(recoverySidecarPath(key), `${JSON.stringify({ path: key, url }, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort disk mirror; process map still holds the URL for same-process retry.
+    }
+}
+export function loadRecoveredUrl(vbriefAbsPath) {
+    const key = resolve(vbriefAbsPath);
+    const mem = processPendingUrls.get(key);
+    if (typeof mem === "string" && mem.length > 0) {
+        return mem;
+    }
+    try {
+        const side = recoverySidecarPath(key);
+        // Parent dir must be trusted before we read any sidecar (forged-dir attack, #2880).
+        const parent = dirname(side);
+        const parentStat = lstatSync(parent);
+        if (!isTrustedStat(parentStat) || !parentStat.isDirectory()) {
+            return undefined;
+        }
+        const st = lstatSync(side);
+        if (!st.isFile() || !isTrustedStat(st)) {
+            return undefined;
+        }
+        const raw = readFileSync(side, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const obj = parsed;
+            const url = obj.url;
+            const pathField = obj.path;
+            if (typeof url === "string" && url.length > 0 && ISSUE_URL_PATTERN.test(url)) {
+                if (typeof pathField === "string" && resolve(pathField) !== key) {
+                    return undefined;
+                }
+                processPendingUrls.set(key, url);
+                return url;
+            }
+        }
+    }
+    catch {
+        // Missing or untrusted recovery file is empty.
+    }
+    return undefined;
+}
+export function clearRecoveredUrl(vbriefAbsPath) {
+    const key = resolve(vbriefAbsPath);
+    processPendingUrls.delete(key);
+    try {
+        const side = recoverySidecarPath(key);
+        try {
+            const st = lstatSync(side);
+            if (st.isSymbolicLink() || st.isFile()) {
+                unlinkSync(side);
+            }
+        }
+        catch {
+            rmSync(side, { force: true });
+        }
+    }
+    catch {
+        // Best-effort clear.
+    }
+}
+/** Project ledger first, then process/OS-temp recovery (#2880). */
+export function resolvePriorCreatedUrl(projectRoot, vbriefAbsPath) {
+    const absPath = resolve(vbriefAbsPath);
+    const pending = loadPendingEmitUrls(projectRoot)[absPath];
+    if (typeof pending === "string" && pending.length > 0) {
+        return pending;
+    }
+    return loadRecoveredUrl(absPath);
+}
+/**
+ * Record URL immediately after remote create. Project ledger is best-effort;
+ * recovery layers always run first so dual local failure cannot force re-create (#2880).
+ */
+export function recordCreatedUrlDurable(projectRoot, vbriefAbsPath, url) {
+    rememberCreatedUrl(vbriefAbsPath, url);
+    if (testFailProjectLedger()) {
+        return;
+    }
+    try {
+        savePendingEmitUrl(projectRoot, vbriefAbsPath, url);
+    }
+    catch {
+        // Recovery layers already hold the URL.
+    }
+}
+function stampUrlOntoVbrief(path, data, url, projectRoot) {
+    if (testFailStamp()) {
+        throw new Error("issue-emit test hook: stamp failure");
+    }
+    addGithubIssueReference(data, url);
+    writeVbrief(path, data, projectRoot);
+    clearPendingEmitUrl(projectRoot, path);
+    clearRecoveredUrl(path);
+}
+/** Contained durable map: abs vbrief path -> issue URL for in-flight emits (#2871). */
+export function pendingEmitLedgerPath(projectRoot) {
+    return join(resolve(projectRoot), ".deft-cache", "issue-emit-pending.json");
+}
+export function loadPendingEmitUrls(projectRoot) {
+    const ledger = pendingEmitLedgerPath(projectRoot);
+    try {
+        assertWriteTargetSafe(projectRoot, ledger);
+        const raw = readFileSync(ledger, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const out = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === "string" && v.length > 0) {
+                    out[k] = v;
+                }
+            }
+            return out;
+        }
+    }
+    catch {
+        // Missing or unreadable ledger is empty.
+    }
+    return {};
+}
+export function savePendingEmitUrl(projectRoot, vbriefAbsPath, url) {
+    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");
+}
+export function clearPendingEmitUrl(projectRoot, vbriefAbsPath) {
+    const ledger = pendingEmitLedgerPath(projectRoot);
+    const key = resolve(vbriefAbsPath);
+    const map = loadPendingEmitUrls(projectRoot);
+    if (!(key in map)) {
+        return;
+    }
+    delete map[key];
+    try {
+        assertWriteTargetSafe(projectRoot, ledger);
+        mkdirSync(dirname(ledger), { recursive: true });
+        writeFileSync(ledger, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // Best-effort clear; next successful stamp still works via existingGithubIssueRef.
     }
 }
 export function loadVbrief(path) {
@@ -20,8 +281,39 @@ export function loadVbrief(path) {
         ? data
         : {};
 }
-export function writeVbrief(path, data) {
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+/**
+ * Resolve project root and refuse unsafe write targets before any emit side-effect.
+ * Callers that create remote issues MUST invoke this before `fileIssue` so a
+ * containment refusal cannot leave an orphan GitHub issue (#2869 / #2871).
+ *
+ * ⊗ Do not fall back to `dirname(path)` as the containment root — that trusts a
+ * possibly-symlinked parent and would re-open the escape (Greptile P1 on #2871).
+ */
+export function assertVbriefWriteTargetSafe(path, projectRoot) {
+    const absPath = resolve(path);
+    // Resolve root only from explicit projectRoot, DEFT_PROJECT_ROOT, or cwd walk-up.
+    // Never start discovery from dirname(absPath) — that trusts a possibly-symlinked parent
+    // of the write target as the containment root (Greptile/SLizard P1 on #2871).
+    const root = projectRoot !== undefined && projectRoot !== null && projectRoot.length > 0
+        ? resolve(projectRoot)
+        : resolveProjectRoot(null);
+    if (root === null) {
+        throw new ProjectionContainmentError(`projection write refused: could not resolve project root for ${absPath}; pass projectRoot or run from a project checkout`, {
+            projectDir: process.cwd(),
+            targetPath: absPath,
+            offendingPath: absPath,
+        });
+    }
+    assertWriteTargetSafe(root, absPath);
+    return root;
+}
+/**
+ * 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).
+ */
+export function writeVbrief(path, data, projectRoot) {
+    assertVbriefWriteTargetSafe(path, projectRoot);
+    writeFileSync(resolve(path), `${JSON.stringify(data, null, 2)}\n`, "utf8");
 }
 export function vbriefTitle(data) {
     const plan = (data.plan ?? {});
@@ -160,10 +452,37 @@ export function emitSingle(path, options) {
     if (options.noNetwork) {
         return { result: "dryrun", vbrief: shown, url: null, title };
     }
+    // Atomic emit contract (#2871 / #2880):
+    // 1) Resolve a trusted project root (never dirname of target).
+    // 2) Reconcile prior URL from project ledger OR process/OS-temp recovery (no re-create).
+    // 3) Pre-persist current payload so the write path is proven.
+    // 4) Create remote issue, then always record URL in recovery + best-effort project ledger.
+    // 5) Stamp the vbrief; clear recovery on success. Dual local failure still retries safely.
+    const root = assertVbriefWriteTargetSafe(path, options.projectRoot);
+    const absPath = resolve(path);
+    const priorUrl = resolvePriorCreatedUrl(root, absPath);
+    if (typeof priorUrl === "string" && priorUrl.length > 0) {
+        try {
+            stampUrlOntoVbrief(path, data, priorUrl, root);
+        }
+        catch (stampErr) {
+            throw new IssueEmitError(`reconcile ${priorUrl} but failed to stamp local vbrief: ${String(stampErr)}`, { createdUrl: priorUrl });
+        }
+        return { result: "created", vbrief: shown, url: priorUrl, title };
+    }
+    writeVbrief(path, data, root);
     const body = renderIssueBody(data);
+    assertVbriefWriteTargetSafe(path, root);
     const url = fileIssue(options.repo, title, body, options.scmCall);
-    addGithubIssueReference(data, url);
-    writeVbrief(path, data);
+    // Recovery layers first (process + OS-temp), then best-effort project ledger (#2880).
+    // Dual ledger+stamp failure still leaves URL for retry without re-create.
+    recordCreatedUrlDurable(root, absPath, url);
+    try {
+        stampUrlOntoVbrief(path, data, url, root);
+    }
+    catch (stampErr) {
+        throw new IssueEmitError(`created ${url} but failed to stamp local vbrief: ${String(stampErr)}`, { createdUrl: url });
+    }
     return { result: "created", vbrief: shown, url, title };
 }
 export function emitPerVbrief(paths, options) {
@@ -188,12 +507,22 @@ export function emitUmbrella(paths, options) {
         loaded.push([paths[i], shown[i], loadVbrief(paths[i])]);
     }
     const pending = loaded.filter(([, , data]) => existingGithubIssueRef(data) === undefined);
-    const already = loaded
-        .filter(([, , data]) => existingGithubIssueRef(data) !== undefined)
-        .map(([, disp]) => ({ vbrief: disp, result: "skipped" }));
+    const alreadyEntries = loaded.filter(([, , data]) => existingGithubIssueRef(data) !== undefined);
+    const already = alreadyEntries.map(([, disp]) => ({ vbrief: disp, result: "skipped" }));
+    // Already-stamped siblings seed the umbrella URL and participate in conflict checks (#2880).
+    let stampedSiblingUrl = null;
+    for (const [, , data] of alreadyEntries) {
+        const ref = existingGithubIssueRef(data);
+        if (typeof ref === "string" && ref.length > 0) {
+            if (stampedSiblingUrl !== null && stampedSiblingUrl !== ref) {
+                throw new IssueEmitError(`umbrella siblings already stamped with conflicting issue URLs: ${stampedSiblingUrl} vs ${ref}`, { createdUrl: stampedSiblingUrl });
+            }
+            stampedSiblingUrl = ref;
+        }
+    }
     const umbrellaTitle = options.title ?? defaultUmbrellaTitle(loaded.length);
     if (pending.length === 0) {
-        return { result: "skipped", url: null, title: umbrellaTitle, vbriefs: already };
+        return { result: "skipped", url: stampedSiblingUrl, title: umbrellaTitle, vbriefs: already };
     }
     if (options.noNetwork) {
         return {
@@ -203,13 +532,80 @@ export function emitUmbrella(paths, options) {
             vbriefs: [...pending.map(([, disp]) => ({ vbrief: disp, result: "dryrun" })), ...already],
         };
     }
-    const body = renderUmbrellaBody(pending.map(([, disp, data]) => [disp, data]));
-    const url = fileIssue(options.repo, umbrellaTitle, body, options.scmCall);
+    // Umbrella emit: same durability contract as emitSingle (#2871 / #2880).
+    // Reconcile pending/recovery URLs, pre-persist, create once, record all, stamp all.
+    // Mid-loop ledger/stamp failure must not force a second remote create on retry.
+    const root = options.projectRoot !== undefined &&
+        options.projectRoot !== null &&
+        options.projectRoot.length > 0
+        ? resolve(options.projectRoot)
+        : assertVbriefWriteTargetSafe(String(pending[0]?.[0] || ""), options.projectRoot);
     const written = [];
+    const stillNeedRemote = [];
+    // Pass 1: resolve recovered URLs and reject conflicts BEFORE any stamp (#2880).
+    // Include already-stamped sibling URLs so partial umbrella cohorts cannot split.
+    let reconciledUrl = stampedSiblingUrl;
+    const withPrior = [];
     for (const [path, disp, data] of pending) {
-        addGithubIssueReference(data, url);
-        writeVbrief(path, data);
-        written.push({ vbrief: disp, result: "created" });
+        const prior = resolvePriorCreatedUrl(root, path);
+        if (typeof prior === "string" && prior.length > 0) {
+            if (reconciledUrl !== null && reconciledUrl !== prior) {
+                throw new IssueEmitError(`umbrella recovered conflicting issue URLs: ${reconciledUrl} vs ${prior}; resolve local pending/recovery state before retry`, { createdUrl: reconciledUrl });
+            }
+            reconciledUrl = prior;
+            withPrior.push([path, disp, data, prior]);
+        }
+        else {
+            writeVbrief(path, data, root);
+            stillNeedRemote.push([path, disp, data]);
+        }
+    }
+    // Pass 2: stamp only after the recovered set is conflict-free.
+    for (const [path, disp, data, prior] of withPrior) {
+        try {
+            stampUrlOntoVbrief(path, data, prior, root);
+            written.push({ vbrief: disp, result: "created" });
+        }
+        catch {
+            // Leave recovery/ledger for retry; still surface URL via reconciledUrl.
+            written.push({ vbrief: disp, result: "pending-reconcile" });
+        }
+    }
+    if (stillNeedRemote.length === 0) {
+        const pendingLeft = written.some((w) => w.result === "pending-reconcile");
+        if (pendingLeft && reconciledUrl !== null) {
+            throw new IssueEmitError(`created ${reconciledUrl} but failed to stamp one or more umbrella vbriefs; retry to reconcile without re-create`, { createdUrl: reconciledUrl });
+        }
+        return {
+            result: "created",
+            url: reconciledUrl,
+            title: umbrellaTitle,
+            vbriefs: [...written, ...already],
+        };
+    }
+    // Sibling recovery: reuse recovered/stamped umbrella URL instead of a second remote create (#2880).
+    let url = reconciledUrl;
+    if (url === null || url.length === 0) {
+        const body = renderUmbrellaBody(stillNeedRemote.map(([, disp, data]) => [disp, data]));
+        url = fileIssue(options.repo, umbrellaTitle, body, options.scmCall);
+    }
+    // Record URL for every remaining artifact before any stamp can throw (#2880).
+    for (const [path] of stillNeedRemote) {
+        recordCreatedUrlDurable(root, path, url);
+    }
+    const stampErrors = [];
+    for (const [path, disp, data] of stillNeedRemote) {
+        try {
+            stampUrlOntoVbrief(path, data, url, root);
+            written.push({ vbrief: disp, result: "created" });
+        }
+        catch (stampErr) {
+            stampErrors.push(`${disp}: ${String(stampErr)}`);
+            written.push({ vbrief: disp, result: "pending-reconcile" });
+        }
+    }
+    if (stampErrors.length > 0) {
+        throw new IssueEmitError(`created ${url} but failed to stamp ${stampErrors.length} umbrella vbrief(s): ${stampErrors.join("; ")}`, { createdUrl: url });
     }
     return { result: "created", url, title: umbrellaTitle, vbriefs: [...written, ...already] };
 }
@@ -286,11 +682,17 @@ export function issueEmitMain(args) {
                 noNetwork,
                 title: args.title,
                 displayPaths: display,
+                projectRoot,
             });
             summary = { mode: "umbrella", no_network: noNetwork, umbrella: action };
         }
         else if (args.perVbrief) {
-            const actions = emitPerVbrief(paths, { repo, noNetwork, displayPaths: display });
+            const actions = emitPerVbrief(paths, {
+                repo,
+                noNetwork,
+                displayPaths: display,
+                projectRoot,
+            });
             summary = { mode: "per-vbrief", no_network: noNetwork, actions };
         }
         else {
@@ -302,6 +704,7 @@ export function issueEmitMain(args) {
                 repo,
                 noNetwork,
                 displayPath: display[0],
+                projectRoot,
             });
             summary = { mode: "single", no_network: noNetwork, actions: [action] };
         }

package/dist/intake/issue-ingest.js

@@ -1,7 +1,8 @@
-import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
 import { scan } from "../cache/scanner.js";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -537,6 +538,42 @@ export function fetchIssue(repo, number, options = {}) {
     const comments = fetchIssueComments(repo, number, options);
     return attachIssueCommentThread(cached, comments);
 }
+/**
+ * Resolve the containment root for ingest writes (#2869 / #2871).
+ *
+ * Precedence:
+ * 1. Explicit `cwd` (CLI project root)
+ * 2. Sentinel walk from vbriefDir (`xbrief` / `vbrief` / `.git`)
+ * 3. Parent of a layout-named lifecycle dir (`…/xbrief` or `…/vbrief`) — even when
+ *    that dir does not exist yet (mkdir is about to create it)
+ * 4. An already-existing non-symlink vbriefDir used as a bare lifecycle root (tests)
+ *
+ * ⊗ Never use a non-existent or symlink path as a silent dirname fallback.
+ */
+function resolveIngestProjectRoot(vbriefDir, cwd) {
+    if (cwd !== undefined && cwd !== null && cwd.length > 0) {
+        return resolve(cwd);
+    }
+    const walked = resolveProjectRoot(null, vbriefDir);
+    if (walked !== null) {
+        return walked;
+    }
+    const abs = resolve(vbriefDir);
+    const base = basename(abs);
+    if (base === "xbrief" || base === "vbrief" || base === "vBRIEF") {
+        return dirname(abs);
+    }
+    try {
+        const info = lstatSync(abs);
+        if (info.isDirectory() && !info.isSymbolicLink()) {
+            return abs;
+        }
+    }
+    catch {
+        // missing dir — cannot contain writes safely without an explicit root
+    }
+    return null;
+}
 export function ingestOne(issue, options) {
     const number = Number(issue.number);
     const refs = options.existingRefs ?? scanProvenanceRefs(options.vbriefDir);
@@ -559,11 +596,24 @@ export function ingestOne(issue, options) {
         infoVersion: emissionLayout.infoVersion,
     });
     const filename = targetFilename(number, String(issue.title ?? ""), emissionLayout.artifactSuffix);
-    const target = join(options.vbriefDir, folder, filename);
+    const folderPath = join(options.vbriefDir, folder);
+    const target = join(folderPath, filename);
     if (options.dryRun) {
         return ["dryrun", target, `DRY-RUN would write ${folder}/${filename}`];
     }
-    mkdirSync(join(options.vbriefDir, folder), { recursive: true });
+    // Gate lifecycle folder + leaf before mkdir/write so folder/parent symlinks
+    // cannot divert issue:ingest / triage:accept outside the project (#2869).
+    const projectRoot = resolveIngestProjectRoot(options.vbriefDir, options.cwd);
+    if (projectRoot === null) {
+        throw new ProjectionContainmentError(`projection write refused: could not resolve project root for ingest into ${options.vbriefDir}`, {
+            projectDir: options.vbriefDir,
+            targetPath: target,
+            offendingPath: options.vbriefDir,
+        });
+    }
+    assertWriteTargetSafe(projectRoot, folderPath);
+    assertWriteTargetSafe(projectRoot, target);
+    mkdirSync(folderPath, { recursive: true });
     writeFileSync(target, `${JSON.stringify(vbrief, null, 2)}\n`, "utf8");
     return ["created", target, `CREATED ${folder}/${filename}`];
 }

package/dist/platform/platform-capabilities.js

@@ -14,6 +14,9 @@ const CURSOR_SIGNAL_VARS = [
 const CLOUD_SIGNAL_VARS = [
     "CURSOR_AGENT",
     "GROK_BUILD",
+    "OPENCLAW",
+    "DEFT_HAS_SESSIONS_SPAWN",
+    "DEFT_PROBE_SESSIONS_SPAWN",
     "DEFT_AGENT_RUNTIME",
     "CI",
     "GITHUB_ACTIONS",

package/dist/review-monitor/constants.js

@@ -40,7 +40,7 @@ export const REVIEW_MONITOR_HELP = "usage: task verify:review-monitor -- --pr <N
     "\n" +
     "Claim a lease after spawning Approach 1:\n" +
     "  task review-monitor:register -- --pr <N> --monitor-agent-id <id> \\\n" +
-    "    --platform-primitive cursor-task|spawn_subagent|start_agent \\\n" +
+    "    --platform-primitive cursor-task|spawn_subagent|start_agent|sessions_spawn \\\n" +
     "    [--head-sha SHA] [--repo OWNER/REPO] [--force]\n" +
     "\n" +
     "Release when done:\n" +
@@ -54,7 +54,8 @@ export const REGISTER_HELP = "usage: task review-monitor:register -- --pr <N> --
     "required:\n" +
     "  --pr N                     Pull request number\n" +
     "  --monitor-agent-id ID      Stable poller agent id / Task handle\n" +
-    "  --platform-primitive P     start_agent | spawn_subagent | cursor-task\n" +
+    "  --platform-primitive P     start_agent | spawn_subagent | cursor-task |\n" +
+    "                             sessions_spawn | openclaw-sessions-spawn (#2876)\n" +
     "\n" +
     "options:\n" +
     "  --repo OWNER/REPO          Repository (default: origin / DEFT_TRIAGE_REPO)\n" +

package/dist/review-monitor/tier-detection.d.ts

@@ -1,5 +1,9 @@
 import { MONITORING_TIER_1, MONITORING_TIER_2, MONITORING_TIER_3 } from "./constants.js";
-export type PlatformPrimitive = "start_agent" | "spawn_subagent" | "cursor-task";
+/** Canonical Approach-1 platform primitives for review-monitor register/verify (#2655 / #2876). */
+export type PlatformPrimitive = "start_agent" | "spawn_subagent" | "cursor-task" | "sessions_spawn" | "openclaw-sessions-spawn";
+/** Accepted `--platform-primitive` values (register CLI + help text). */
+export declare const PLATFORM_PRIMITIVES: readonly PlatformPrimitive[];
+export declare const PLATFORM_PRIMITIVE_SET: Set<string>;
 export interface MonitoringTierProbe {
     readonly tier: typeof MONITORING_TIER_1 | typeof MONITORING_TIER_2 | typeof MONITORING_TIER_3;
     readonly primitive: PlatformPrimitive | null;
@@ -7,7 +11,7 @@ export interface MonitoringTierProbe {
 }
 /**
  * Inline Tier-1 detection aligned with the swarm Phase 3 / review-cycle matrix
- * (#1877 / #2655). Prefer `task platform:capabilities` when available (#1357);
+ * (#1877 / #2655 / #2876). Prefer `task platform:capabilities` when available (#1357);
  * this probe does not block MVP.
  */
 export declare function probeMonitoringTier(environ?: NodeJS.ProcessEnv): MonitoringTierProbe;