@deftai/directive-core 0.106.0 → 0.108.0

package/dist/platform/platform-capabilities.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
 import { IDENTITY_LOCAL_USER, IDENTITY_REAL_ROOT, IDENTITY_SANDBOX_REMAPPED_LOCAL_USER, IDENTITY_UNKNOWN, RUNTIME_MODE_CLOUD_HEADLESS, RUNTIME_MODE_CURSOR_NATIVE_SANDBOX, RUNTIME_MODE_LOCAL_UNSANDBOXED, } from "./constants.js";
+import { hasExplicitHostGhSelection, probeManagedRuntime, RUNTIME_REASON_CI_MARKER, RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS, RUNTIME_REASON_CURSOR_SANDBOX_MARKER, RUNTIME_REASON_EXPLICIT_HOST_GH, RUNTIME_REASON_MANAGED_RUNTIME_PROBE, RUNTIME_REASON_NO_RUNTIME_MARKER, } from "./cursor-managed-runtime.js";
 import { detectEnvironmentContext, environmentContextToDict, } from "./shell-context.js";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 const CURSOR_SIGNAL_VARS = [
@@ -69,16 +70,19 @@ export function classifyIdentityKind(options) {
     }
     return IDENTITY_LOCAL_USER;
 }
-function isCloudHeadless(environ) {
-    if (envTruthy(environ, "CURSOR_AGENT"))
-        return true;
+/** Reason id when a non-Cursor CI/cloud marker forces cloud-headless, else null. */
+function ciCloudReason(environ) {
     // GROK_BUILD / DEFT_AGENT_RUNTIME=grok-build identify a local TUI, not CI (#3469).
     const runtime = (environ.DEFT_AGENT_RUNTIME ?? "").trim().toLowerCase();
     if (runtime === "cloud" || runtime === "headless")
-        return true;
-    if (envTruthy(environ, "GITHUB_ACTIONS") || envTruthy(environ, "BUILDKITE"))
-        return true;
-    return envTruthy(environ, "CI") && !envTruthy(environ, "CURSOR_COMPOSER");
+        return RUNTIME_REASON_CI_MARKER;
+    if (envTruthy(environ, "GITHUB_ACTIONS") || envTruthy(environ, "BUILDKITE")) {
+        return RUNTIME_REASON_CI_MARKER;
+    }
+    if (envTruthy(environ, "CI") && !envTruthy(environ, "CURSOR_COMPOSER")) {
+        return RUNTIME_REASON_CI_MARKER;
+    }
+    return null;
 }
 function isCursorNativeSandbox(environ, sandboxUidRemap) {
     if (sandboxUidRemap)
@@ -87,12 +91,44 @@ function isCursorNativeSandbox(environ, sandboxUidRemap) {
         return true;
     return Boolean((environ.CURSOR_SANDBOX_LANDLOCK_STATUS ?? "").trim());
 }
-export function classifyRuntimeMode(environ, sandboxUidRemap) {
-    if (isCloudHeadless(environ))
-        return RUNTIME_MODE_CLOUD_HEADLESS;
-    if (isCursorNativeSandbox(environ, sandboxUidRemap))
-        return RUNTIME_MODE_CURSOR_NATIVE_SANDBOX;
-    return RUNTIME_MODE_LOCAL_UNSANDBOXED;
+/**
+ * Classify runtime mode and name the reason for the verdict (#3859).
+ *
+ * Ordering matches intake/platform-capabilities.ts: CI markers, then a positive
+ * managed-runtime read, then sandbox, then the ambiguous Cursor hop. The Cursor
+ * hop previously ran first here; it now runs last so neither a CI marker nor a
+ * managed read can be overridden by an explicit host-gh selection.
+ */
+export function classifyRuntime(environ, sandboxUidRemap, options = {}) {
+    const ciReason = ciCloudReason(environ);
+    if (ciReason !== null)
+        return { mode: RUNTIME_MODE_CLOUD_HEADLESS, reason: ciReason };
+    const managedProbe = options.managedRuntimeProbe ?? probeManagedRuntime;
+    if (managedProbe(environ).verdict === "managed") {
+        return {
+            mode: RUNTIME_MODE_CLOUD_HEADLESS,
+            reason: RUNTIME_REASON_MANAGED_RUNTIME_PROBE,
+        };
+    }
+    if (isCursorNativeSandbox(environ, sandboxUidRemap)) {
+        return {
+            mode: RUNTIME_MODE_CURSOR_NATIVE_SANDBOX,
+            reason: RUNTIME_REASON_CURSOR_SANDBOX_MARKER,
+        };
+    }
+    if (envTruthy(environ, "CURSOR_AGENT")) {
+        if (hasExplicitHostGhSelection(environ)) {
+            return { mode: RUNTIME_MODE_LOCAL_UNSANDBOXED, reason: RUNTIME_REASON_EXPLICIT_HOST_GH };
+        }
+        return {
+            mode: RUNTIME_MODE_CLOUD_HEADLESS,
+            reason: RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS,
+        };
+    }
+    return { mode: RUNTIME_MODE_LOCAL_UNSANDBOXED, reason: RUNTIME_REASON_NO_RUNTIME_MARKER };
+}
+export function classifyRuntimeMode(environ, sandboxUidRemap, options = {}) {
+    return classifyRuntime(environ, sandboxUidRemap, options).mode;
 }
 function readOwnership(path, sandboxUidRemap) {
     try {
@@ -151,13 +187,16 @@ export function probeRuntimeCapabilities(options = {}) {
     const uidMap = readUidMap(uidMapFile);
     const sandboxUidRemap = detectSandboxUidRemap(uidMap, { effectiveUid, cursorOrigUid });
     const identityKind = classifyIdentityKind({ effectiveUid, sandboxUidRemap });
-    const runtimeMode = classifyRuntimeMode(env, sandboxUidRemap);
+    const runtime = classifyRuntime(env, sandboxUidRemap, {
+        managedRuntimeProbe: options.managedRuntimeProbe,
+    });
     const cwdPath = options.cwd ?? process.cwd();
     const ownership = readOwnership(cwdPath, sandboxUidRemap);
     return {
         hostPlatform: environment.hostPlatform,
         shell: environment.shell,
-        runtimeMode,
+        runtimeMode: runtime.mode,
+        runtimeModeReason: runtime.reason,
         identityKind,
         effectiveUid,
         effectiveUsername,
@@ -176,6 +215,7 @@ export function reportToDict(report) {
     return {
         ...environmentContextToDict({ hostPlatform: report.hostPlatform, shell: report.shell }),
         runtime_mode: report.runtimeMode,
+        runtime_mode_reason: report.runtimeModeReason,
         identity_kind: report.identityKind,
         effective_uid: report.effectiveUid,
         effective_username: report.effectiveUsername,

package/dist/policy/ceremony-dial.js

@@ -20,7 +20,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { RunSummaryEmitter } from "../run-summary/emit.js";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
 import { appendAuditLog, loadProjectDefinition, POLICY_AUDIT_NOOP_STDOUT, projectDefinitionPath, } from "./resolve.js";
@@ -510,14 +510,10 @@ export function setCeremonyDial(projectRoot, options) {
             changed: false,
         };
     }
-    const path = projectDefinitionPath(projectRoot);
+    const _path = projectDefinitionPath(projectRoot);
     try {
-        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
-            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-            }
-            const data = parsed;
+        const { changed } = withProjectDefinitionMutation(projectRoot, (mutation) => {
+            const data = mutation.load();
             if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
                 if (data.plan === undefined) {
                     data.plan = {};
@@ -569,7 +565,7 @@ export function setCeremonyDial(projectRoot, options) {
                 legacyKeyMigrated;
             policyBlock.ceremonyDial = nextBlock;
             if (changedFlag) {
-                atomicWriteProjectDefinition(path, data);
+                mutation.persist(data);
             }
             const actor = options.actor ?? policyColonInvocation("set-ceremony-dial");
             const note = options.note ?? "";

package/dist/policy/host-hooks.js

@@ -1,6 +1,5 @@
-import { readFileSync } from "node:fs";
 import { HOOK_HOSTS } from "../hooks/dispatcher.js";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
 import { appendAuditLog, loadProjectDefinition, POLICY_AUDIT_NOOP_STDOUT, projectDefinitionPath, } from "./resolve.js";
@@ -145,12 +144,8 @@ export function disableHostHooks(projectRoot, options) {
     }
     const path = projectDefinitionPath(projectRoot);
     try {
-        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
-            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-            }
-            const data = parsed;
+        const { changed } = withProjectDefinitionMutation(projectRoot, (mutation) => {
+            const data = mutation.load();
             if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
                 if (data.plan === undefined) {
                     data.plan = {};
@@ -178,7 +173,7 @@ export function disableHostHooks(projectRoot, options) {
             const changedFlag = previous[options.host] !== false || legacyKeyMigrated;
             policyBlock.hostHooks = next;
             if (changedFlag) {
-                atomicWriteProjectDefinition(path, data);
+                mutation.persist(data);
             }
             const actor = options.actor ?? disableHostHooksInvocation();
             const note = options.note ?? "";

package/dist/policy/org-force-on-migration.js

@@ -3,10 +3,10 @@ import { join, resolve } from "node:path";
 import { sortKeysDeep } from "../codebase/json.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { containedWrite } from "../fs/contained-write.js";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { isNoDeftDirectivePresent } from "./no-deft-directive.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
-import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
+import { appendAuditLog, loadProjectDefinition } from "./resolve.js";
 import { detectOriginOrg, isTrustedOrgAutoEnable, } from "./value-feedback-autoenable.js";
 /** Durable once-per-checkout marker for #2822 trusted-org install force-on. */
 export const ORG_FORCE_ON_MARKER_REL = join(".deft-cache", "org-force-on-v2822.json");
@@ -331,18 +331,13 @@ export function runOrgForceOnMigration(projectRoot, options = {}) {
     return applyForceOn(projectRoot, options, { existingMarker: null });
 }
 function applyForceOn(projectRoot, options, intent) {
-    const path = projectDefinitionPath(projectRoot);
     let valueFeedbackChanged = false;
     let productSignalChanged = false;
     let ran = false;
     let skippedReason = null;
     const existing = intent.existingMarker;
-    projectDefinitionMutationLock(projectRoot, () => {
-        const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-        }
-        const rootData = parsed;
+    withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const rootData = mutation.load();
         if (typeof rootData.plan !== "object" ||
             rootData.plan === null ||
             Array.isArray(rootData.plan)) {
@@ -402,7 +397,7 @@ function applyForceOn(projectRoot, options, intent) {
             productSignalChanged = productSignalNeedsForceOn(previousPs);
         }
         if (valueFeedbackChanged || productSignalChanged) {
-            atomicWriteProjectDefinition(path, rootData);
+            mutation.persist(rootData);
         }
         // Marker previous*: forced fields record pre-apply current; unforced fields
         // keep the prior marker snapshot so intentional opt-outs are not rewritten

package/dist/policy/plan-extensions.d.ts

@@ -54,11 +54,23 @@ export interface ShadowedPlanExtension {
     /** The bare legacy key that is silently ignored (e.g. `policy`). */
     readonly legacyKey: string;
     /**
-     * Best-effort list of sub-keys present in the shadowed bare object (e.g.
-     * `["triageScope", "wipCap"]`). Empty when the bare value is not an object.
+     * Complete, sorted list of the exact sub-keys present in the shadowed bare
+     * object (e.g. `["triageScope", "wipCap"]`). Empty when the bare value is not
+     * an object.
+     *
+     * These are raw semantic keys, kept whole so machine-readable inventories
+     * (the doctor finding's `shadowed_sub_keys`) stay complete. Bounding and
+     * redaction belong at a display boundary -- see
+     * {@link summarizeShadowedPlanSubKeys} (#3796).
      */
     readonly shadowedSubKeys: readonly string[];
 }
+/**
+ * Bounded, redacted presentation of shadowed sub-keys for a human diagnostic.
+ * Callers keep the raw semantic inventory; only the rendered string is capped
+ * and sanitised (#3796).
+ */
+export declare function summarizeShadowedPlanSubKeys(keys: readonly string[]): string[];
 /**
  * Detect every plan-extension key where a bare (legacy) block coexists with the
  * namespaced form (#2301). Because `readPlanExtension` is namespace-first, the

package/dist/policy/plan-extensions.js

@@ -77,6 +77,26 @@ export const SHADOWABLE_PLAN_EXTENSIONS = [
     { namespacedKey: PLAN_POLICY_KEY, legacyKey: LEGACY_PLAN_POLICY_KEY },
     { namespacedKey: PLAN_COMPLETED_NOTE_KEY, legacyKey: LEGACY_PLAN_COMPLETED_NOTE_KEY },
 ];
+const SAFE_DIAGNOSTIC_KEY = /^[A-Za-z][A-Za-z0-9._/-]{0,31}$/;
+const SENSITIVE_DIAGNOSTIC_KEY = /(?:auth|credential|password|private|secret|token|api.?key)/i;
+const MAX_DIAGNOSTIC_KEYS = 8;
+/**
+ * Bounded, redacted presentation of shadowed sub-keys for a human diagnostic.
+ * Callers keep the raw semantic inventory; only the rendered string is capped
+ * and sanitised (#3796).
+ */
+export function summarizeShadowedPlanSubKeys(keys) {
+    const ordered = [...keys].sort();
+    const summary = ordered
+        .slice(0, MAX_DIAGNOSTIC_KEYS)
+        .map((key) => SAFE_DIAGNOSTIC_KEY.test(key) && !SENSITIVE_DIAGNOSTIC_KEY.test(key)
+        ? key
+        : `<redacted-key length=${[...key].length}>`);
+    if (ordered.length > MAX_DIAGNOSTIC_KEYS) {
+        summary.push(`<${ordered.length - MAX_DIAGNOSTIC_KEYS} more keys>`);
+    }
+    return summary;
+}
 /**
  * Detect every plan-extension key where a bare (legacy) block coexists with the
  * namespaced form (#2301). Because `readPlanExtension` is namespace-first, the
@@ -96,7 +116,7 @@ export function detectShadowedPlanExtensions(plan) {
         }
         const legacyValue = planObj[legacyKey];
         const shadowedSubKeys = typeof legacyValue === "object" && legacyValue !== null && !Array.isArray(legacyValue)
-            ? Object.keys(legacyValue)
+            ? Object.keys(legacyValue).sort()
             : [];
         shadows.push({ namespacedKey, legacyKey, shadowedSubKeys });
     }
@@ -108,8 +128,9 @@ export function detectShadowedPlanExtensions(plan) {
  * prefix it (`[policy:show]`, a doctor finding, ...).
  */
 export function describeShadowedPlanExtension(shadow) {
-    const subKeys = shadow.shadowedSubKeys.length > 0
-        ? ` Shadowed field(s): ${shadow.shadowedSubKeys
+    const displaySubKeys = summarizeShadowedPlanSubKeys(shadow.shadowedSubKeys);
+    const subKeys = displaySubKeys.length > 0
+        ? ` Shadowed field(s): ${displaySubKeys
             .map((k) => `plan.${shadow.legacyKey}.${k}`)
             .join(", ")}.`
         : "";

package/dist/policy/product-signal.js

@@ -1,5 +1,4 @@
-import { readFileSync } from "node:fs";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { productSignalInstallForceOnSource } from "./org-force-on-migration.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
@@ -140,14 +139,10 @@ export function enableProductSignal(projectRoot, options) {
             changed: false,
         };
     }
-    const path = projectDefinitionPath(projectRoot);
+    const _path = projectDefinitionPath(projectRoot);
     try {
-        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
-            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-            }
-            const data = parsed;
+        const { changed } = withProjectDefinitionMutation(projectRoot, (mutation) => {
+            const data = mutation.load();
             if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
                 if (data.plan === undefined) {
                     data.plan = {};
@@ -185,7 +180,7 @@ export function enableProductSignal(projectRoot, options) {
                 legacyKeyMigrated;
             policyBlock.productSignal = nextBlock;
             if (changedFlag) {
-                atomicWriteProjectDefinition(path, data);
+                mutation.persist(data);
             }
             const actor = options.actor ?? "task product-signal:enable";
             const note = options.note ?? "";

package/dist/policy/require-human-merge.js

@@ -14,8 +14,8 @@
  * `merge-approval-head.ts` (stale head → fail closed + disable auto-merge).
  * That gate is complementary to this policy surface and does not replace it.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { existsSync } from "node:fs";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
 import { appendAuditLog, loadProjectDefinition, projectDefinitionPath, stampChangedToken, } from "./resolve.js";
@@ -270,12 +270,8 @@ export function setRequireHumanMerge(projectRoot, options) {
     if (!existsSync(path)) {
         throw new Error(`PROJECT-DEFINITION not found at ${path}`);
     }
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-        }
-        const data = parsed;
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
             if (data.plan === undefined) {
                 data.plan = {};
@@ -322,7 +318,7 @@ export function setRequireHumanMerge(projectRoot, options) {
         }
         const auditEntry = stampChangedToken(parts.join(" "), changed);
         if (changed) {
-            atomicWriteProjectDefinition(path, data);
+            mutation.persist(data);
         }
         appendAuditLog(projectRoot, auditEntry, changed);
         return { changed, auditEntry };

package/dist/policy/resolve.js

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve as pathResolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
-import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
-import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { projectDefinitionPath as resolveProjectDefinitionArtifactPath } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
+import { describeShadowedPlanExtension, detectShadowedPlanExtensions, LEGACY_PLAN_POLICY_KEY, migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy, } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
 /** Filesystem-relative location of the project-definition xBRIEF (display/back-compat). */
 export const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.json";
@@ -32,11 +32,13 @@ const TRUTHY = new Set(["1", "true", "yes", "on"]);
 export function projectDefinitionPath(projectRoot) {
     const root = pathResolve(projectRoot);
     try {
-        return resolveProjectDefinitionPath(root);
+        return resolveProjectDefinitionArtifactPath(root);
     }
     catch {
-        // No xbrief/ layout; return canonical xbrief path so callers get a predictable
-        // "not found" result rather than a thrown error.
+        // Policy reads remain fail-closed on pre-migration trees. The shared resolver
+        // intentionally throws for legacy-only lifecycle layouts, but policy callers
+        // need a predictable missing canonical path rather than an exception while
+        // init/update is still responsible for reporting the migration requirement.
         return join(root, PROJECT_DEFINITION_REL_PATH);
     }
 }
@@ -70,6 +72,66 @@ function pythonRepr(value) {
         return value ? "True" : "False";
     return String(value);
 }
+/** Render configuration values without exposing arbitrary string/object content. */
+function diagnosticValue(value) {
+    if (value === undefined || value === null)
+        return "None";
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "<number>";
+    if (typeof value === "string")
+        return `<string length=${[...value].length}>`;
+    if (Array.isArray(value))
+        return `<list length=${value.length}>`;
+    if (typeof value === "object")
+        return `<dict keys=${Object.keys(value).length}>`;
+    return `<${typeof value}>`;
+}
+function objectKeys(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return [];
+    }
+    return Object.keys(value).sort();
+}
+function keyInventory(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? `<dict keys=${Object.keys(value).length}>`
+        : diagnosticValue(value);
+}
+function branchPolicyValue(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return diagnosticValue(value);
+    }
+    return diagnosticValue(value.allowDirectCommitsToMaster);
+}
+/**
+ * Refuse a policy write when the legacy and namespaced blocks coexist (#3609).
+ *
+ * A writer cannot safely decide how to combine arbitrary policy keys or resolve
+ * collisions. The diagnostic therefore inventories keys, exposes only the one
+ * value this writer owns, and gives the operator a lossless recovery sequence.
+ */
+function assertPolicyBlockIsUnambiguous(plan) {
+    const shadow = detectShadowedPlanExtensions(plan).find((candidate) => candidate.namespacedKey === PLAN_POLICY_KEY);
+    if (shadow === undefined) {
+        return;
+    }
+    const namespaced = plan[PLAN_POLICY_KEY];
+    const legacy = plan[LEGACY_PLAN_POLICY_KEY];
+    const namespacedKeys = objectKeys(namespaced);
+    const legacyKeys = objectKeys(legacy);
+    const namespacedKeySet = new Set(namespacedKeys);
+    const collisions = legacyKeys.filter((key) => namespacedKeySet.has(key));
+    throw new Error(`${describeShadowedPlanExtension(shadow)} ` +
+        `Key inventory: namespaced=${keyInventory(namespaced)}; ` +
+        `bare=${keyInventory(legacy)}; collisions=<list length=${collisions.length}>. ` +
+        `Relevant branch-policy values: namespaced=${branchPolicyValue(namespaced)}; ` +
+        `bare=${branchPolicyValue(legacy)}. ` +
+        `Recovery: inventory both blocks; fold every bare-only key into ` +
+        `\`plan.${PLAN_POLICY_KEY}\`; explicitly resolve every collision; delete ` +
+        `\`plan.${LEGACY_PLAN_POLICY_KEY}\`; then rerun the policy command. No changes were written.`);
+}
 /** Best-effort coerce a legacy narrative value to a boolean. */
 export function coerceLegacyNarrative(value) {
     if (typeof value === "boolean") {
@@ -147,7 +209,7 @@ export function resolvePolicy(projectRoot) {
                 allowDirectCommits: false,
                 source: "default-fail-closed",
                 deprecationWarning: null,
-                error: `plan.policy.allowDirectCommitsToMaster must be a boolean; got ${pythonTypeName(raw)} (${pythonRepr(raw)})`,
+                error: `plan.policy.allowDirectCommitsToMaster must be a boolean; got ${pythonTypeName(raw)} (${diagnosticValue(raw)})`,
             };
         }
         return {
@@ -164,7 +226,7 @@ export function resolvePolicy(projectRoot) {
         LEGACY_NARRATIVE_KEY in narratives) {
         const { allow, raw } = coerceLegacyNarrative(narratives[LEGACY_NARRATIVE_KEY]);
         const warn = `DEPRECATED: PROJECT-DEFINITION uses the legacy narrative key ` +
-            `'${LEGACY_NARRATIVE_KEY}' (${pythonRepr(raw)}). Migrate to typed ` +
+            `'${LEGACY_NARRATIVE_KEY}' (${diagnosticValue(raw)}). Migrate to typed ` +
             `plan.policy.allowDirectCommitsToMaster (#746). Run ` +
             `\`${policyColonInvocation("enforce-branches")}\` or ` +
             `\`${policyColonInvocation("allow-direct-commits", " -- --confirm")}\` ` +
@@ -224,12 +286,8 @@ export function setPolicy(projectRoot, options) {
     // Serialise the read-modify-write + audit-log append behind the shared
     // PROJECT-DEFINITION mutation lock so a concurrent policy/ritual mutator
     // cannot lose this update or desync the typed flag from the audit row (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-        }
-        const data = parsed;
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
             if (data.plan === undefined) {
                 data.plan = {};
@@ -239,6 +297,9 @@ export function setPolicy(projectRoot, options) {
             }
         }
         const plan = data.plan;
+        // Repeat the shadow check inside the mutation lock so a concurrent writer
+        // cannot create a dual-block state between validation and persistence.
+        assertPolicyBlockIsUnambiguous(plan);
         const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
         const existingPolicy = plan[PLAN_POLICY_KEY];
         if (typeof existingPolicy !== "object" ||
@@ -267,7 +328,7 @@ export function setPolicy(projectRoot, options) {
         const parts = [
             `actor=${actor}`,
             `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
-            `previous=${pythonRepr(previous)}`,
+            `previous=${diagnosticValue(previous)}`,
         ];
         if (legacyDropped) {
             parts.push("legacy-narrative-migrated=true");
@@ -277,7 +338,7 @@ export function setPolicy(projectRoot, options) {
         }
         const auditEntry = stampChangedToken(parts.join(" "), changed);
         if (changed) {
-            atomicWriteProjectDefinition(path, data);
+            mutation.persist(data);
         }
         appendAuditLog(projectRoot, auditEntry, changed);
         return { changed, auditEntry };

package/dist/policy/runtime-authority.d.ts

@@ -11,6 +11,22 @@ export interface RuntimeAuthorityScopes {
 }
 /** Layers that contribute to a resolved write fence (#516 / #2443 / #2948 Wave 3). */
 export type WriteFenceSource = "project" | "story";
+/**
+ * Whether recognized Shell dest-forms are enforced (#3438 / #3594).
+ *
+ * `off` (default) leaves Shell mutations exactly as they were before #3438:
+ * unrecognized and fail-open. `enforce` routes recognized dest-forms through
+ * `inspectMutationGates` and fail-closes targets it cannot prove.
+ *
+ * ! Default is `off` on purpose. Before #3438 Bash mutations were not gated at
+ * all, so defaulting to `enforce` would land new denials on every consumer with
+ * no opt-out. Opting IN via tracked project policy is a narrowing, which this
+ * fence model permits; a tracked switch that DISABLED enforcement would not be
+ * (see policy/deft-directive-disable.ts — repository-controlled content must
+ * not disable hooks for downstream clones).
+ */
+export type ShellDestFormsMode = "off" | "enforce";
+export declare const SHELL_DEST_FORMS_MODES: readonly ShellDestFormsMode[];
 export interface RuntimeAuthorityPolicy {
     readonly enabled: boolean;
     /** When non-empty, write targets must match at least one pattern. Empty = allow all paths. */
@@ -18,6 +34,8 @@ export interface RuntimeAuthorityPolicy {
     /** Deny wins over allow. */
     readonly denyPaths: readonly string[];
     readonly scopes: RuntimeAuthorityScopes;
+    /** Shell dest-form enforcement (#3438 / #3594). Default `off`. */
+    readonly shellDestForms: ShellDestFormsMode;
     /**
      * Optional story-layer allow globs from `plan.metadata.swarm.file_scope`
      * (populated by `resolveWriteFence` only). When non-empty, path must match

package/dist/policy/runtime-authority.js

@@ -3,6 +3,7 @@ import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
 export const FIELD_RUNTIME_AUTHORITY = "plan.policy.runtimeAuthority";
 export const FIELD_RUNTIME_AUTHORITY_CLI_ALIAS = "runtimeAuthority";
+export const SHELL_DEST_FORMS_MODES = ["off", "enforce"];
 export const DEFAULT_RUNTIME_AUTHORITY_SCOPES = {
     edits: true,
     push: false,
@@ -14,6 +15,7 @@ export const DEFAULT_RUNTIME_AUTHORITY_POLICY = {
     allowPaths: [],
     denyPaths: [],
     scopes: DEFAULT_RUNTIME_AUTHORITY_SCOPES,
+    shellDestForms: "off",
 };
 function readBoolean(rec, key, fallback) {
     if (key in rec && typeof rec[key] === "boolean") {
@@ -37,6 +39,11 @@ function readScopes(raw) {
         merge: readBoolean(rec, "merge", DEFAULT_RUNTIME_AUTHORITY_SCOPES.merge),
     };
 }
+function readShellDestForms(raw) {
+    // Unknown / malformed resolves to the safe default rather than throwing, but
+    // validateRuntimeAuthority reports it so a typo is not silent (#3594).
+    return raw === "enforce" ? "enforce" : DEFAULT_RUNTIME_AUTHORITY_POLICY.shellDestForms;
+}
 export function resolveRuntimeAuthorityPolicy(raw) {
     if (raw === null || raw === undefined) {
         return DEFAULT_RUNTIME_AUTHORITY_POLICY;
@@ -50,6 +57,7 @@ export function resolveRuntimeAuthorityPolicy(raw) {
         allowPaths: readStringArray(rec.allowPaths),
         denyPaths: readStringArray(rec.denyPaths),
         scopes: readScopes(rec.scopes),
+        shellDestForms: readShellDestForms(rec.shellDestForms),
     };
 }
 export function validateRuntimeAuthority(value) {
@@ -69,6 +77,9 @@ export function validateRuntimeAuthority(value) {
             errors.push(`${FIELD_RUNTIME_AUTHORITY}.${key} must be an array of path globs`);
         }
     }
+    if ("shellDestForms" in rec && !SHELL_DEST_FORMS_MODES.includes(rec.shellDestForms)) {
+        errors.push(`${FIELD_RUNTIME_AUTHORITY}.shellDestForms must be one of ${SHELL_DEST_FORMS_MODES.join(" | ")}`);
+    }
     if ("scopes" in rec) {
         const scopes = rec.scopes;
         if (typeof scopes !== "object" || scopes === null || Array.isArray(scopes)) {