@deftai/directive-core 0.90.0 → 0.92.0

package/dist/cache/fetch.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
 import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
@@ -45,7 +45,8 @@ export function writeOpenInventoryStamp(options) {
         fetched_at: utcIso(clock, fetchedAt),
         open_count: 0,
     };
-    atomicWriteText(openInventoryStampPath(options.cacheRoot, options.source, options.repo), `${JSON.stringify(payload)}\n`);
+    // #3042: contain stamp write against project root (parent of cacheRoot).
+    atomicWriteText(openInventoryStampPath(options.cacheRoot, options.source, options.repo), `${JSON.stringify(payload)}\n`, { projectRoot: dirname(resolve(options.cacheRoot)) });
 }
 export const REST_MAX_PER_PAGE = 100;
 export const REST_PAGINATION_MAX_PAGES = 100;

package/dist/cache/io.d.ts

@@ -1,9 +1,20 @@
 import { tmpdir } from "node:os";
+export interface AtomicWriteTextOptions {
+    /**
+     * Project / checkout root used as the containment boundary (#3042).
+     * When set, refuses symlink parents and out-of-root targets before temp+rename.
+     * Prefer always passing this for product sinks (brief stay-path, agents refresh, cache).
+     * When omitted, falls back to parent-dir containment (legacy test / low-risk helpers).
+     */
+    readonly projectRoot?: string;
+}
 /**
  * Write text via tempfile + rename (mirrors Python `_atomic_write_text`).
- * #2951 Phase 2: temp payload write uses containedWrite under the parent dir.
+ * #2951 Phase 2: temp payload write uses containedWrite.
+ * #3042: when `projectRoot` is set, containment root is projectRoot (not dirname(path))
+ * so force-added lifecycle / cache directory symlinks fail closed.
  */
-export declare function atomicWriteText(path: string, text: string): void;
+export declare function atomicWriteText(path: string, text: string, options?: AtomicWriteTextOptions): void;
 /**
  * Append one JSON audit record (mirrors `_append_audit`).
  * #2951 Phase 2: product write sink routes through containedWrite.

package/dist/cache/io.js

@@ -3,24 +3,53 @@ import { mkdirSync, renameSync, rmSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { pythonJsonLine } from "./json.js";
 /**
  * Write text via tempfile + rename (mirrors Python `_atomic_write_text`).
- * #2951 Phase 2: temp payload write uses containedWrite under the parent dir.
+ * #2951 Phase 2: temp payload write uses containedWrite.
+ * #3042: when `projectRoot` is set, containment root is projectRoot (not dirname(path))
+ * so force-added lifecycle / cache directory symlinks fail closed.
  */
-export function atomicWriteText(path, text) {
-    const dir = dirname(path);
+export function atomicWriteText(path, text, options = {}) {
+    const targetAbs = resolve(path);
+    const dir = dirname(targetAbs);
+    const tmpBase = `${basename(targetAbs)}.${randomBytes(4).toString("hex")}.tmp`;
+    const tmp = join(dir, tmpBase);
+    if (options.projectRoot !== undefined) {
+        // Contain against projectRoot (parent-as-root fix #3042 / authz writeJsonContained pattern).
+        const root = resolve(options.projectRoot);
+        assertWriteTargetSafe(root, targetAbs);
+        try {
+            containedWrite({
+                root,
+                target: tmp,
+                data: text,
+                mode: "create",
+            });
+            renameSync(tmp, targetAbs);
+        }
+        catch (err) {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch {
+                /* v8 ignore next -- best-effort cleanup */
+            }
+            throw err;
+        }
+        return;
+    }
+    // Legacy: parent-dir containment when no projectRoot (unit helpers / transitional call sites).
     mkdirSync(dir, { recursive: true });
-    const tmpName = `${basename(path)}.${randomBytes(4).toString("hex")}.tmp`;
-    const tmp = join(dir, tmpName);
     try {
         containedWrite({
             root: resolve(dir),
-            target: tmpName,
+            target: tmpBase,
             data: text,
             mode: "create",
         });
-        renameSync(tmp, path);
+        renameSync(tmp, targetAbs);
     }
     catch (err) {
         try {

package/dist/cache/operations.js

@@ -129,14 +129,16 @@ export function cachePut(source, key, raw, options = {}) {
             incomingBytes: incomingDelta,
         });
     }
-    atomicWriteText(join(edir, "raw.json"), rawText);
+    // #3042: contain cache entry writes against project root (parent of cacheRoot).
+    const projectRoot = dirname(resolve(cacheRoot));
+    atomicWriteText(join(edir, "raw.json"), rawText, { projectRoot });
     const authoritativeSize = fileSize(join(edir, "raw.json"));
     const rendered = renderContent(source, raw);
     const scanResult = scan(rendered, utcIso(clock, fetched));
     const contentPath = join(edir, "content.md");
     let contentWritten = false;
     if (scanResult.passed) {
-        atomicWriteText(contentPath, scanResult.transformed_content);
+        atomicWriteText(contentPath, scanResult.transformed_content, { projectRoot });
         contentWritten = true;
     }
     else if (existsSync(contentPath)) {
@@ -158,7 +160,7 @@ export function cachePut(source, key, raw, options = {}) {
         clock,
     });
     validateMeta(meta);
-    atomicWriteText(join(edir, "meta.json"), pythonJsonDump(meta));
+    atomicWriteText(join(edir, "meta.json"), pythonJsonDump(meta), { projectRoot });
     appendAudit({
         event: "cache:put",
         source,

package/dist/doctor/main.js

@@ -4,6 +4,7 @@ import { VBRIEF_VERSION } from "@deftai/directive-types";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { contentRoot } from "../content-root.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { describeShadowedPlanExtension, detectShadowedPlanExtensions, } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
@@ -70,6 +71,42 @@ export function cmdDoctor(args, seams = {}) {
     const consumerContext = resolve(projectRoot) !== resolve(frameworkRoot);
     const whichFn = seams.whichFn ?? defaultWhich;
     const nowFn = seams.now ?? (() => new Date());
+    // #3039: temporary test kill-switch. Active (untracked) → disabled short-circuit.
+    // Tracked/committed flag → warn only and continue normal doctor (no enforcement bypass).
+    const killSwitch = detectDeftDirectiveDisable(projectRoot, { skipTrackedCache: true });
+    if (killSwitch.present &&
+        killSwitch.trackedByGit &&
+        !isDeftDirectiveDisableActive(projectRoot, { skipTrackedCache: true })) {
+        if (!jsonMode && !quietMode) {
+            process.stderr.write(`${DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING}\n`);
+        }
+        // Continue into full doctor; do not short-circuit.
+    }
+    else if (isDeftDirectiveDisableActive(projectRoot, { skipTrackedCache: true })) {
+        const optOutAlso = detectNoDeftDirective(projectRoot);
+        const message = formatDeftDirectiveDisableMessage({
+            permanentOptOutAlsoPresent: optOutAlso.present,
+            trackedByGit: false,
+        });
+        if (jsonMode) {
+            const payload = {
+                status: DEFT_DIRECTIVE_DISABLE_STATUS,
+                disabled: true,
+                disabled_via: DEFT_DIRECTIVE_DISABLE_FLAG_NAME,
+                kill_switch: true,
+                inconsistent: false,
+                deposit_present: killSwitch.depositPresent,
+                tracked_by_git: false,
+                permanent_opt_out_also_present: optOutAlso.present,
+                message,
+            };
+            process.stdout.write(`${pythonJsonDump(payload)}\n`);
+        }
+        else if (!quietMode) {
+            process.stdout.write(`${message}\n`);
+        }
+        return 0;
+    }
     // #2926: official root opt-out — short-circuit Directive doctor when clean;
     // diagnose flag+deposit inconsistency (warn; exit dirty).
     const optOut = detectNoDeftDirective(projectRoot);

package/dist/doctor/openclaw-skills.d.ts

@@ -1,10 +1,16 @@
 /**
- * OpenClaw always-pin skill detect + doctor --fix wire (#3001).
+ * OpenClaw always-pin skill detect + doctor --fix wire (#3001 / #3008).
  *
  * When OpenClaw signals are present, doctor checks the main workspace skills
  * root for the four always-pin skills (#2508). Missing pins emit a warning with
- * remediation `deft doctor --fix`. Under fixMode, pins are symlinked (preferred)
- * or copied from the installed content package into the target skills dir.
+ * remediation `deft doctor --fix`. Under fixMode, pins are **copied** into the
+ * workspace skills root (not symlinked into the npm content package).
+ *
+ * OpenClaw 2026.7.x rejects workspace skills that resolve outside the configured
+ * skills root (`reason=symlink-escape`). A pin that is only a symlink into
+ * `@deftai/directive-content` therefore looks "present" on disk while the host
+ * never loads it (#3008). Prefer real directory copies; treat escaping
+ * symlinks as divergent so `--fix` can replace them.
  *
  * Multi-seat (`workspace-*`) targets only when `--openclaw-all-agents` is set.
  */
@@ -29,6 +35,7 @@ export interface OpenClawSkillPinsSeams {
     readonly symlinkDir?: (target: string, path: string) => void;
     readonly copyDir?: (src: string, dst: string) => void;
     readonly removePath?: (path: string) => void;
+    readonly renamePath?: (from: string, to: string) => void;
     readonly contentRootFor?: (frameworkRoot: string) => string;
     readonly isTty?: () => boolean;
     readonly readYn?: (prompt: string, defaultYes: boolean) => boolean;
@@ -77,21 +84,48 @@ export declare function listInScopeSkillsDirs(stateDir: string, allAgents: boole
  * Resolve content package skills/<id> for a pin.
  */
 export declare function resolvePinSourceDir(contentBase: string, skillId: string): string;
+/**
+ * True when `path` is a symlink whose resolved real path is outside `skillsDir`
+ * (OpenClaw `symlink-escape` / #3008).
+ */
+export declare function isEscapingSkillSymlink(skillsDir: string, path: string, seams?: Pick<OpenClawSkillPinsSeams, "lstatKind">): boolean;
 /**
  * Assess which always-pins are present / missing / divergent in a skills root.
  *
- * - present: directory (or symlink) with SKILL.md
+ * - present: real directory (or non-escaping symlink) with SKILL.md matching
+ *   the content package when `contentBase` is supplied
  * - missing: path does not exist
- * - divergent: path exists but is not a usable pin (file, empty dir, broken link)
+ * - divergent: path exists but is not a usable OpenClaw pin (file, empty dir,
+ *   broken link, **escaping symlink**, or **stale SKILL.md** vs package — #3008)
  */
-export declare function assessOpenClawPins(skillsDir: string, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "isFile" | "pathExists" | "lstatKind">): OpenClawPinAssessment;
+export declare function assessOpenClawPins(skillsDir: string, seams?: Pick<OpenClawSkillPinsSeams, "isDir" | "isFile" | "pathExists" | "lstatKind">, options?: {
+    contentBase?: string;
+}): OpenClawPinAssessment;
 /**
- * Install one pin into a skills root. Prefer symlink; copy on failure.
- * Never deletes user skills. Divergent targets require force or TTY confirm.
+ * Install one pin into a skills root.
+ *
+ * Default: **copy** into the workspace skills root (#3008). OpenClaw rejects
+ * skills that resolve outside the workspace skills root via symlink-escape, so
+ * symlinking into the npm content package leaves pins unloaded while doctor
+ * reports "present". Opt into legacy symlink-first with `preferSymlink: true`
+ * (still falls back to copy). Never deletes unrelated user skills. Divergent
+ * targets (including escaping symlinks) require force or TTY confirm.
+ *
+ * Stale copies (SKILL.md differs from package) are not "already-present" —
+ * doctor --fix refreshes them so upgrades land without manual delete (#3008 P1).
+ * Forced replace stages into a sibling temp dir first so a failed copy does not
+ * leave the pin permanently deleted (#3008 P1).
  */
 export declare function installOpenClawPin(skillId: OpenClawAlwaysPinSkill, sourceDir: string, skillsDir: string, options?: {
     force?: boolean;
     allowOverwrite?: boolean;
+    /** When true, try symlink first (legacy #3001). Default false — copy (#3008). */
+    preferSymlink?: boolean;
+    /**
+     * When true, refresh copied pins whose SKILL.md no longer matches the
+     * package (package upgrade path). Doctor --fix sets this.
+     */
+    refreshStale?: boolean;
 }, seams?: OpenClawSkillPinsSeams): PinInstallResult;
 export interface RunOpenClawSkillPinsOptions {
     readonly frameworkRoot: string;