@deftai/directive-core 0.107.0 → 0.109.0

package/dist/scm/gh-rest.js

@@ -3,8 +3,10 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
-import { resolveBinary } from "./binary.js";
+import { defaultWhich } from "./binary.js";
+import { classifyScmArgv, resolveBinaryForRole } from "./call-shape.js";
 import { pyRepr } from "./py-format.js";
+import { classifySpawnStatus, formatScmSpawnDiagnostic, isAvailabilitySpawnFailure, } from "./spawn-status.js";
 export const DEFAULT_TIMEOUT_S = 60;
 /** Raised when the `"owner/repo"` argument is malformed. */
 export class InvalidRepoError extends Error {
@@ -23,10 +25,16 @@ export class GhRestError extends Error {
     endpoint;
     payload;
     hint;
+    binary;
     constructor(options) {
         const hint = options.hint ?? "";
-        let msg = `gh api failed: endpoint=${pyRepr(options.endpoint)} ` +
-            `exit=${options.exitCode} stderr=${pyRepr(options.stderr)}`;
+        const binary = options.binary ?? "gh";
+        const statusClass = classifySpawnStatus(options.exitCode);
+        let msg = `${binary} api failed: endpoint=${pyRepr(options.endpoint)} ` + `exit=${options.exitCode}`;
+        if (statusClass !== `exit ${options.exitCode}`) {
+            msg += ` (${statusClass})`;
+        }
+        msg += ` stderr=${pyRepr(options.stderr)}`;
         if (hint.length > 0) {
             msg += `; hint: ${hint}`;
         }
@@ -37,30 +45,70 @@ export class GhRestError extends Error {
         this.endpoint = options.endpoint;
         this.payload = options.payload;
         this.hint = hint;
+        this.binary = binary;
+    }
+}
+function defaultGhSpawn(command, args, options) {
+    return spawnSync(command, [...args], options);
+}
+function finalizeGhApiResult(binary, result) {
+    const rawStderr = typeof result.stderr === "string" ? result.stderr : "";
+    let stderr = rawStderr;
+    if (result.status === null && result.error && stderr.trim().length === 0) {
+        stderr = result.error.message ?? "";
     }
+    if (isAvailabilitySpawnFailure({
+        status: result.status,
+        error: result.error,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: rawStderr,
+    }) &&
+        stderr.trim().length === 0) {
+        stderr = formatScmSpawnDiagnostic(binary, result.status, stderr, result.error);
+    }
+    return {
+        returncode: result.status ?? 1,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr,
+        binary,
+        rawStderr,
+        rawStatus: result.status,
+        error: result.error,
+    };
 }
 /** Single subprocess seam invoked by every helper. */
 export function runGhApi(args, options = {}) {
-    const binary = resolveBinary(options.whichFn);
+    const whichFn = options.whichFn ?? defaultWhich;
+    const spawnFn = options.spawnFn ?? defaultGhSpawn;
+    const role = classifyScmArgv("api", args);
+    let binary = resolveBinaryForRole(role, whichFn);
     const timeoutMs = options.timeout !== undefined ? Math.round(options.timeout * 1000) : DEFAULT_TIMEOUT_S * 1000;
-    const result = spawnSync(binary, ["api", ...args], {
+    const spawnOpts = {
         encoding: "utf8",
         timeout: timeoutMs,
         env: process.env,
         maxBuffer: SUBPROCESS_MAX_BUFFER,
         stdio: ["ignore", "pipe", "pipe"],
-    });
-    let stderr = typeof result.stderr === "string" ? result.stderr : "";
-    // A spawn-level failure (e.g. ENOBUFS when stdout exceeds maxBuffer) yields a
-    // null status and empty stderr; surface error.message so the GhRestError that
-    // wraps this never reports a blank reason (#1867).
-    if (result.status === null && result.error && stderr.trim().length === 0) {
-        stderr = result.error.message;
+    };
+    const spawnOnce = (bin) => finalizeGhApiResult(bin, spawnFn(bin, ["api", ...args], spawnOpts));
+    let first = spawnOnce(binary);
+    if (role === "cached-get" &&
+        binary === "ghx" &&
+        isAvailabilitySpawnFailure({
+            status: first.rawStatus,
+            error: first.error,
+            stdout: first.stdout,
+            stderr: first.rawStderr,
+        }) &&
+        whichFn("gh") !== null) {
+        binary = "gh";
+        first = spawnOnce(binary);
     }
     return {
-        returncode: result.status ?? 1,
-        stdout: typeof result.stdout === "string" ? result.stdout : "",
-        stderr,
+        returncode: first.returncode,
+        stdout: first.stdout,
+        stderr: first.stderr,
+        binary,
     };
 }
 export function splitRepo(repo) {
@@ -83,6 +131,7 @@ function execApi(args, options) {
             endpoint: options.endpoint,
             payload: options.payload,
             hint: options.hint ?? "",
+            binary: result.binary ?? "gh",
         });
     }
     const stdout = result.stdout.trim();
@@ -183,6 +232,7 @@ export const PUBLIC_HELPERS = [
     "restPrView",
     "restIssueList",
     "restIssueListPaginated",
+    "restIssueListOpenInventory",
 ];
 function writeJsonPayload(payload) {
     const dir = mkdtempSync(join(tmpdir(), "gh_rest_payload_"));
@@ -331,6 +381,109 @@ export function restPrView(repo, n, seams = {}) {
         whichFn: seams.whichFn,
     });
 }
+const OPEN_INVENTORY_MAX_ISSUES = REST_PAGINATION_MAX_PAGES * REST_MAX_PER_PAGE;
+function issueRowOrThrow(item, endpoint) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new GhRestError({
+            stderr: "open-issue inventory row is not an object",
+            exitCode: 0,
+            endpoint,
+            payload: null,
+            hint: "REST issue list rows must be objects",
+        });
+    }
+    return item;
+}
+/** Flatten `gh api --paginate --slurp` issue-list output (pages or single page). */
+export function flattenOpenInventoryPayload(parsed, endpoint) {
+    if (parsed.length === 0) {
+        return [];
+    }
+    const out = [];
+    const allPages = parsed.every((item) => Array.isArray(item));
+    if (allPages) {
+        for (const page of parsed) {
+            if (!Array.isArray(page)) {
+                continue;
+            }
+            for (const item of page) {
+                const row = issueRowOrThrow(item, endpoint);
+                if ("pull_request" in row) {
+                    continue;
+                }
+                out.push(row);
+            }
+        }
+        return out;
+    }
+    for (const item of parsed) {
+        const row = issueRowOrThrow(item, endpoint);
+        if ("pull_request" in row) {
+            continue;
+        }
+        out.push(row);
+    }
+    return out;
+}
+/**
+ * Complete open-issue inventory in one `gh api --paginate --slurp` subprocess (#3752).
+ * Fail-closed on command failure, non-array JSON, buffer exhaustion, or cap hit.
+ * Pull-request rows are excluded.
+ */
+export function restIssueListOpenInventory(repo, seams = {}) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/issues?state=open&per_page=${REST_MAX_PER_PAGE}`;
+    const runner = seams.runGhApiFn ?? runGhApi;
+    const result = runner(["--paginate", "--slurp", endpoint], { timeout: 120 });
+    if (result.returncode !== 0) {
+        throw new GhRestError({
+            stderr: result.stderr.trim(),
+            exitCode: result.returncode,
+            endpoint,
+            payload: null,
+            hint: "verify gh auth and core REST quota; open-issue inventory must be complete",
+            binary: result.binary ?? "gh",
+        });
+    }
+    const stdout = result.stdout.trim();
+    if (stdout.length === 0) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        throw new GhRestError({
+            stderr: `non-JSON open-issue inventory: ${message}`,
+            exitCode: 0,
+            endpoint,
+            payload: null,
+            hint: "gh api --paginate --slurp must return a JSON array",
+        });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new GhRestError({
+            stderr: `unexpected top-level type ${typeof parsed}`,
+            exitCode: 0,
+            endpoint,
+            payload: null,
+            hint: "open-issue inventory must be a JSON array",
+        });
+    }
+    const out = flattenOpenInventoryPayload(parsed, endpoint);
+    if (out.length >= OPEN_INVENTORY_MAX_ISSUES) {
+        throw new GhRestError({
+            stderr: `open-issue inventory reached cap ${OPEN_INVENTORY_MAX_ISSUES}; pagination may be incomplete`,
+            exitCode: 0,
+            endpoint,
+            payload: null,
+            hint: "repo may exceed supported open-issue count; fail closed rather than truncate",
+        });
+    }
+    return out;
+}
 export function restIssueListPaginated(repo, options = {}, seams = {}) {
     const cappedPerPage = Math.min(Math.max(1, options.perPage ?? REST_MAX_PER_PAGE), REST_MAX_PER_PAGE);
     const [owner, name] = splitRepo(repo);

package/dist/scm/index.d.ts

@@ -2,6 +2,7 @@ export * from "./argv.js";
 export * from "./binary.js";
 export * from "./build-command.js";
 export * from "./call.js";
+export * from "./call-shape.js";
 export * from "./constants.js";
 export * from "./design-critique-chip.js";
 export * from "./errors.js";
@@ -10,4 +11,5 @@ export * from "./main.js";
 export * from "./py-format.js";
 export * from "./readiness.js";
 export * from "./rest-dispatch.js";
+export * from "./spawn-status.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scm/index.js

@@ -2,6 +2,7 @@ export * from "./argv.js";
 export * from "./binary.js";
 export * from "./build-command.js";
 export * from "./call.js";
+export * from "./call-shape.js";
 export * from "./constants.js";
 export * from "./design-critique-chip.js";
 export * from "./errors.js";
@@ -10,4 +11,5 @@ export * from "./main.js";
 export * from "./py-format.js";
 export * from "./readiness.js";
 export * from "./rest-dispatch.js";
+export * from "./spawn-status.js";
 //# sourceMappingURL=index.js.map

package/dist/scm/readiness.d.ts

@@ -41,6 +41,8 @@ export interface ScmReadinessReport {
     readonly githubAuthMode: string;
     /** Runtime mode from the #1557a probe. */
     readonly runtimeMode: string;
+    /** Stable id naming why the runtime was classified that way (#3859). */
+    readonly runtimeModeReason: string | null;
     /** Whether an injected token env var is present (value never reported). */
     readonly injectedTokenPresent: boolean;
     /** Probe depth used for this report. */

package/dist/scm/readiness.js

@@ -21,6 +21,7 @@
 import { spawnSync } from "node:child_process";
 import { findInjectedToken, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN, inferGithubAuthMode, validateGithubAuthForWorker, } from "../intake/github-auth-modes.js";
 import { getPlatformCapabilities, probeRuntimeCapabilities, } from "../intake/platform-capabilities.js";
+import { EXPLICIT_SELECTION_REMEDIATION, GITHUB_AUTH_MODE_ENV, RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS, } from "../platform/cursor-managed-runtime.js";
 import { defaultWhich } from "./binary.js";
 import { BINARY_PREFERENCE } from "./constants.js";
 import { ScmStubError } from "./errors.js";
@@ -138,6 +139,7 @@ export function probeScmReadiness(options = {}) {
             authState: "binary-absent",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail,
@@ -149,9 +151,11 @@ export function probeScmReadiness(options = {}) {
     }
     // Injected-token mode without a token is a hard not-ready even before auth status.
     if (githubAuthMode === GITHUB_AUTH_MODE_INJECTED_TOKEN && !injectedTokenPresent) {
+        const ambiguousRuntime = runtimeReport.runtimeModeReason === RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS;
         const detail = "injected-token mode requires GH_TOKEN, GITHUB_TOKEN, or GH_ENTERPRISE_TOKEN; " +
             `binary=${binary} present but SCM-dependent gates skipped ` +
-            `(runtime_mode=${runtimeReport.runtimeMode})`;
+            `(runtime_mode=${runtimeReport.runtimeMode}` +
+            `${runtimeReport.runtimeModeReason ? `, reason=${runtimeReport.runtimeModeReason}` : ""})`;
         return {
             ready: false,
             binary,
@@ -159,10 +163,15 @@ export function probeScmReadiness(options = {}) {
             authState: "missing-token",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent: false,
             depth,
             detail,
-            remediation: REMEDIATION_MISSING_TOKEN,
+            // An ambiguous Cursor runtime is the #3859 case: name the explicit opt-in
+            // here, because this is where the operator actually meets the block.
+            remediation: ambiguousRuntime
+                ? `${EXPLICIT_SELECTION_REMEDIATION}\n\n${REMEDIATION_MISSING_TOKEN}`
+                : REMEDIATION_MISSING_TOKEN,
             skippedGates: [...SCM_DEPENDENT_GATES],
             login: null,
             failureKind: "missing_injected_token",
@@ -209,6 +218,7 @@ export function probeScmReadiness(options = {}) {
                 authState: "authenticated",
                 githubAuthMode: deep.githubAuthMode,
                 runtimeMode: runtimeReport.runtimeMode,
+                runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
                 injectedTokenPresent,
                 depth,
                 detail: `SCM ready: ${binary} present, ${deep.githubAuthMode} authenticated${loginPart} (deep)`,
@@ -226,6 +236,7 @@ export function probeScmReadiness(options = {}) {
             authState,
             githubAuthMode: deep.githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail: `SCM not ready: ${deep.detail}`,
@@ -247,6 +258,7 @@ export function probeScmReadiness(options = {}) {
             authState: "unknown",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail,
@@ -268,6 +280,7 @@ export function probeScmReadiness(options = {}) {
             authState: "unauthenticated",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail,
@@ -284,6 +297,7 @@ export function probeScmReadiness(options = {}) {
         authState: "authenticated",
         githubAuthMode,
         runtimeMode: runtimeReport.runtimeMode,
+        runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
         injectedTokenPresent,
         depth,
         detail: `SCM ready: ${binary} present, ${githubAuthMode} authenticated (shallow)`,
@@ -302,6 +316,7 @@ export function scmReadinessToDict(report) {
         auth_state: report.authState,
         github_auth_mode: report.githubAuthMode,
         runtime_mode: report.runtimeMode,
+        runtime_mode_reason: report.runtimeModeReason,
         injected_token_present: report.injectedTokenPresent,
         depth: report.depth,
         detail: report.detail,
@@ -324,7 +339,14 @@ export function formatScmReadinessLines(report) {
     }
     lines.push(`[deft scm] ${report.detail}`);
     if (report.skippedGates.length > 0) {
-        lines.push(`[deft scm] skipped gates: ${report.skippedGates.join(", ")}`);
+        // Name the classification reason next to the skip: a silent skip is what
+        // makes this failure costly, because work-selection surfaces go dark (#3859).
+        const reason = report.runtimeModeReason ? ` (reason: ${report.runtimeModeReason})` : "";
+        lines.push(`[deft scm] skipped gates: ${report.skippedGates.join(", ")}${reason}`);
+        if (report.runtimeModeReason === RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS) {
+            lines.push(`[deft scm] runtime is ambiguous; set ${GITHUB_AUTH_MODE_ENV}=host-gh to authorize ` +
+                "the host gh credential store on a machine you control (#3859)");
+        }
     }
     lines.push("[deft scm] run SCM-dependent gates only after auth is ready, or from a matched env; " +
         "see content/scm/github.md § Mismatched/headless SCM readiness (#2275)");
@@ -387,13 +409,15 @@ export function requireScmReady(options = {}) {
     if (hermeticAuthSkip) {
         // Production path uses assertScmBinaryPresent (not test-only).
         const binary = assertScmBinaryPresent(options.whichFn);
+        const hermeticRuntime = options.runtimeReport ?? getPlatformCapabilities();
         const report = {
             ready: true,
             binary,
             binaryPath: options.whichFn?.(binary) ?? null,
             authState: "unknown",
             githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
-            runtimeMode: (options.runtimeReport ?? getPlatformCapabilities()).runtimeMode,
+            runtimeMode: hermeticRuntime.runtimeMode,
+            runtimeModeReason: hermeticRuntime.runtimeModeReason ?? null,
             injectedTokenPresent: findInjectedToken(options.env ?? process.env) !== null,
             depth: "shallow",
             detail: `SCM binary present (${binary}); auth status not checked (hermetic)`,

package/dist/scm/spawn-status.d.ts

@@ -0,0 +1,33 @@
+import type { WhichFn } from "./binary.js";
+import type { ScmBinaryRole } from "./call-shape.js";
+/** Windows NTSTATUS STATUS_DLL_INIT_FAILED (#3737). Unsigned and signed 32-bit. */
+export declare const STATUS_DLL_INIT_FAILED = 3221225794;
+export declare function unsignedExitStatus(status: number): number;
+export declare function classifySpawnStatus(status: number | null | undefined, error?: {
+    readonly message?: string;
+    readonly code?: string;
+}): string;
+export declare function isAvailabilitySpawnFailure(result: {
+    readonly status: number | null | undefined;
+    readonly error?: {
+        readonly message?: string;
+        readonly code?: string;
+    };
+    readonly stdout?: string;
+    readonly stderr?: string;
+}): boolean;
+export declare function formatScmSpawnDiagnostic(binary: string, status: number | null | undefined, stderr: string, error?: {
+    readonly message?: string;
+    readonly code?: string;
+}): string;
+/** Return `gh` when a cached-get ghx spawn failed and live gh is on PATH. */
+export declare function ghxSpawnFallbackBinary(role: ScmBinaryRole, invoked: string, whichFn: WhichFn, failure: {
+    readonly status: number | null | undefined;
+    readonly error?: {
+        readonly message?: string;
+        readonly code?: string;
+    };
+    readonly stdout?: string;
+    readonly stderr?: string;
+}): string | null;
+//# sourceMappingURL=spawn-status.d.ts.map

package/dist/scm/spawn-status.js

@@ -0,0 +1,53 @@
+/** Windows NTSTATUS STATUS_DLL_INIT_FAILED (#3737). Unsigned and signed 32-bit. */
+export const STATUS_DLL_INIT_FAILED = 0xc0000142;
+const STATUS_DLL_INIT_FAILED_SIGNED = -1073741502;
+export function unsignedExitStatus(status) {
+    return status >>> 0;
+}
+export function classifySpawnStatus(status, error) {
+    if (typeof status !== "number") {
+        if (typeof error?.code === "string" && error.code.length > 0) {
+            return error.code;
+        }
+        if (typeof error?.message === "string" && error.message.trim().length > 0) {
+            return error.message.trim();
+        }
+        return "spawn-failed";
+    }
+    const unsigned = unsignedExitStatus(status);
+    if (unsigned === STATUS_DLL_INIT_FAILED || status === STATUS_DLL_INIT_FAILED_SIGNED) {
+        return "0xC0000142 STATUS_DLL_INIT_FAILED";
+    }
+    if (unsigned >= 0xc0000000) {
+        return `0x${unsigned.toString(16).toUpperCase()}`;
+    }
+    return `exit ${status}`;
+}
+export function isAvailabilitySpawnFailure(result) {
+    if (result.error !== undefined) {
+        return true;
+    }
+    if (typeof result.status !== "number") {
+        return true;
+    }
+    const unsigned = unsignedExitStatus(result.status);
+    const emptyOut = (result.stdout ?? "").trim().length === 0 && (result.stderr ?? "").trim().length === 0;
+    return (emptyOut &&
+        (unsigned === STATUS_DLL_INIT_FAILED || result.status === STATUS_DLL_INIT_FAILED_SIGNED));
+}
+export function formatScmSpawnDiagnostic(binary, status, stderr, error) {
+    const cls = classifySpawnStatus(status, error);
+    const err = stderr.trim();
+    if (err.length > 0) {
+        return `${binary} failed (${cls}): ${err}`;
+    }
+    return `${binary} failed (${cls}); stderr empty`;
+}
+/** Return `gh` when a cached-get ghx spawn failed and live gh is on PATH. */
+export function ghxSpawnFallbackBinary(role, invoked, whichFn, failure) {
+    if (role !== "cached-get" || invoked !== "ghx" || whichFn("gh") === null) {
+        return null;
+    }
+    return isAvailabilitySpawnFailure(failure) ? "gh" : null;
+}
+//# sourceMappingURL=spawn-status.js.map

package/dist/scope/acceptance-evidence.d.ts

@@ -58,7 +58,7 @@ export interface AcceptanceEvidenceGateResult {
     readonly message: string;
     readonly reports: readonly CriterionAcceptanceReport[];
     /** How the #3357 walk obtained AC (#3387). */
-    readonly servedFrom?: "bank" | "cache" | "executed";
+    readonly servedFrom?: "bank" | "cache" | "executed" | "refused";
     /** Which acceptance check decided the walk (#3497). Undefined when no walk ran. */
     readonly predicate?: AcceptancePredicate;
 }

package/dist/scope/project-definition-sync.js

@@ -1,16 +1,23 @@
 import { dirname, resolve } from "node:path";
-import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
 /** Fail-closed sync of PROJECT-DEFINITION after a lifecycle move (#1527 / #2131). */
 export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
     const projectRoot = dirname(resolve(vbriefRoot));
     try {
-        projectDefinitionMutationLock(projectRoot, () => {
-            const projectDefPath = resolveProjectDefinitionPath(projectRoot);
-            syncRegistryArtifactAfterScopeMove(projectDefPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus, {
-                loadForMutation: () => loadProjectDefinitionForMutation(projectRoot),
-                persist: (path, data) => atomicWriteProjectDefinition(path, data),
+        withProjectDefinitionMutation(projectRoot, (mutation) => {
+            syncRegistryArtifactAfterScopeMove(
+            // The artifact the lock captured, not an independent re-resolution (#3796).
+            mutation.artifactPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus, {
+                loadForMutation: () => [mutation.load(), mutation.artifactPath],
+                persist: (path, data) => {
+                    // The registry sync echoes back the path it was handed, so a
+                    // mismatch means something re-resolved the artifact mid-section.
+                    if (resolve(path) !== resolve(mutation.artifactPath)) {
+                        throw new Error("refusing to persist PROJECT-DEFINITION to a path other than the locked artifact");
+                    }
+                    mutation.persist(data);
+                },
             });
         });
         return null;

package/dist/scope/transition.js

@@ -5,6 +5,7 @@ import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemet
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { applyClauseDerivationToPlan, maybeEmitAcceptanceStampFromChange, } from "../intake/clause-derivation.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
+import { stampExistingEnvelopes } from "../lifecycle/brief-envelope.js";
 import { evaluateCompletedPlanConsistency } from "../lifecycle/completed-consistency.js";
 import { evaluateLiteralAcceptanceFromPlan } from "../literal-acceptance/index.js";
 import { evaluateAcceptanceActivateGate } from "./acceptance-activate-gate.js";
@@ -45,18 +46,6 @@ function advanceNonTerminalOwnItems(items, targetStatus) {
         advanceNonTerminalOwnItems(obj.items, targetStatus);
     }
 }
-/**
- * Refresh the document envelope `updated` stamp to match `plan.updated`.
- * Stamps whichever of xBRIEFInfo (v0.8) / vBRIEFInfo (v0.6) is present — never creates one (#2862 / #2346).
- */
-function stampEnvelopeUpdated(data, nowIso) {
-    for (const key of ["xBRIEFInfo", "vBRIEFInfo"]) {
-        const env = data[key];
-        if (typeof env === "object" && env !== null && !Array.isArray(env)) {
-            env.updated = nowIso;
-        }
-    }
-}
 export function runTransition(action, filePath, now = new Date(), options = {}) {
     if (!(action in TRANSITIONS)) {
         const valid = Object.keys(TRANSITIONS).sort().join(", ");
@@ -255,7 +244,8 @@ export function runTransition(action, filePath, now = new Date(), options = {})
     planObj.status = targetStatus;
     planObj.updated = nowIso;
     // Keep the envelope clock aligned with plan.updated on every mutating transition (#2862).
-    stampEnvelopeUpdated(data, nowIso);
+    // Stamps whichever envelope is present, never creates one (#3933 / #2346).
+    stampExistingEnvelopes(data, nowIso);
     // Reconcile the completing brief's own plan.items (mirrors #1527 / #2566 registry sync) (#2862).
     // On complete, items only reach here when #3240 evidence/disposition gate passed.
     if (OWN_ITEMS_RECONCILE_ACTIONS.has(act)) {
@@ -412,7 +402,7 @@ function restampCompletedBrief(args) {
     }
     planObj.status = "completed";
     planObj.updated = nowIso;
-    stampEnvelopeUpdated(data, nowIso);
+    stampExistingEnvelopes(data, nowIso);
     stampCompletionMetadata(planObj, projectRoot, nowIso, {
         completedSessionId: resolveCompletionSessionId(projectRoot),
     });

package/dist/session/ac-pass-banking.d.ts

@@ -12,8 +12,8 @@
  */
 import { type AcPassBankingConfig } from "../policy/ac-pass-banking.js";
 import type { HardEffortBudget, VerificationDepthPolicy } from "./effort-budget.js";
-/** Durable bank ledger directory (gitignored under `.deft/`). */
-export declare const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
+/** Durable bank ledger directory (under already-ignored `.deft/cache/`). */
+export declare const AC_PASS_BANK_DIR = ".deft/cache/ac-pass-banks";
 export declare const AC_PASS_BANK_SCHEMA_VERSION: 1;
 /** Env path for optional JSONL run summary (#3282). Unset = silent. */
 export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";

package/dist/session/ac-pass-banking.js

@@ -18,8 +18,8 @@ import { DEFAULT_SURPLUS_THRESHOLD, resolveAcPassBanking, } from "../policy/ac-p
 import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { detectHardEffortBudget, formatDeepeningSkippedNote, recommendVerificationDepth, } from "./effort-budget.js";
 import { gitHead } from "./git.js";
-/** Durable bank ledger directory (gitignored under `.deft/`). */
-export const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
+/** Durable bank ledger directory (under already-ignored `.deft/cache/`). */
+export const AC_PASS_BANK_DIR = ".deft/cache/ac-pass-banks";
 export const AC_PASS_BANK_SCHEMA_VERSION = 1;
 /** Env path for optional JSONL run summary (#3282). Unset = silent. */
 export const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";

package/dist/session/git.d.ts

@@ -5,11 +5,35 @@ export interface GitRunResult {
 }
 export type GitRunner = (projectRoot: string, args: readonly string[]) => GitRunResult;
 export declare const defaultGitRunner: GitRunner;
+/**
+ * Serve a dispatch's repeated ref reads from one `git` child (#3736).
+ *
+ * The host mutation gate resolved HEAD, the worktree root, and the branch with
+ * a separate spawn each, twice over; on a loaded Windows box a spawn measured a
+ * 2.2s p50, so every concurrent agent's hook slowed every other agent's hook.
+ * The probe is lazy on purpose: it only fires for a read it can actually
+ * answer, so a caller that never asks for context never pays for it.
+ */
+export declare function memoizeGitRunner(runGit?: GitRunner): GitRunner;
 export declare function gitHead(projectRoot: string, runGit?: GitRunner): {
     head: string | null;
     error: string | null;
 };
 export declare function worktreePath(projectRoot: string, runGit?: GitRunner): string;
+/**
+ * Walk from `targetPath` to the nearest existing directory. A write that
+ * creates a missing nested file is the common case; git cannot use a
+ * nonexistent cwd.
+ */
+export declare function existingAncestorDir(targetPath: string): string | null;
+/**
+ * Failure-expressing sibling of {@link worktreePath}. Returns null instead of
+ * falling back to `startDir` so a missing git tree is distinguishable from
+ * success (#3794).
+ */
+export declare function worktreePathOrNull(startDir: string, runGit?: GitRunner): string | null;
+/** Absolute `--git-common-dir` for `projectRoot`, or null on failure. */
+export declare function gitCommonDir(projectRoot: string, runGit?: GitRunner): string | null;
 /** True when `ancestor` is reachable from `descendant` (same commit counts). */
 export declare function gitIsAncestor(projectRoot: string, ancestor: string, descendant: string, runGit?: GitRunner): boolean | null;
 /**