@deftai/directive-runtime 0.127.0 → 0.128.0

package/tasks/engine-invoke.test.cjs

@@ -533,3 +533,87 @@ describe("buildSpawnPlan — CodeQL absolute-path isolation (#3175 / alert #74)"
     assert.deepEqual(plan.args, [String.raw`C:\repo\packages\cli\dist\bin.js`, "session:start"]);
   });
 });
+
+describe("framework pin exclusive invoke (#5805)", () => {
+  const {
+    resolveFrameworkPinBin,
+    hasFrameworkPinBin,
+    resolveFrameworkSourceInvoke,
+    PIN_INSTALL_REMEDIATION,
+    PIN_MATERIALIZE_REMEDIATION,
+  } = require("./engine-invoke.cjs");
+  const pinRoots = [];
+  function pinTempRoot() {
+    const root = mkdtempSync(join(tmpdir(), "pin-inv-"));
+    pinRoots.push(root);
+    return root;
+  }
+  after(() => {
+    for (const root of pinRoots) {
+      try {
+        rmSync(root, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  it("resolveFrameworkPinBin joins checkout pin path", () => {
+    const pin = resolveFrameworkPinBin(join("C:", "repo"));
+    assert.match(pin.replace(/\\/g, "/"), /node_modules\/@deftai\/directive-runtime\/dist\/bin\.js$/);
+  });
+
+  it("hasFrameworkPinBin is false when missing", () => {
+    const root = pinTempRoot();
+    assert.equal(hasFrameworkPinBin(root), false);
+  });
+
+  it("hasFrameworkPinBin is true when pin bin exists", () => {
+    const root = pinTempRoot();
+    const pin = resolveFrameworkPinBin(root);
+    mkdirSync(require("node:path").dirname(pin), { recursive: true });
+    writeFileSync(pin, "module.exports={}\n");
+    assert.equal(hasFrameworkPinBin(root), true);
+  });
+
+  it("framework-source with pin selects vendored pin (not tip dist)", () => {
+    const plan = resolveFrameworkSourceInvoke({
+      hasBin: true,
+      isBuildableSource: true,
+      hasPinBin: true,
+    });
+    assert.deepEqual(plan, { action: "vendored", binKind: "pin" });
+  });
+
+  it("framework-source missing pin fails closed even when tip dist / global exist", () => {
+    const plan = resolveFrameworkSourceInvoke({
+      hasBin: true,
+      isBuildableSource: true,
+      hasPinBin: false,
+      hasGlobalCli: true,
+      isRuntimeVerb: true,
+    });
+    assert.equal(plan.action, "fail-closed");
+    assert.equal(plan.exitCode, 2);
+    assert.deepEqual(plan.remediations, [PIN_INSTALL_REMEDIATION, PIN_MATERIALIZE_REMEDIATION]);
+  });
+
+  it("deposit path keeps prior resolveInvokeDispatch behavior", () => {
+    const plan = resolveFrameworkSourceInvoke({
+      hasBin: false,
+      isBuildableSource: false,
+      hasPinBin: false,
+      hasGlobalCli: true,
+      isRuntimeVerb: false,
+    });
+    assert.deepEqual(plan, { action: "global" });
+  });
+
+  it("pin-bin CLI exits 2 when missing", () => {
+    const root = pinTempRoot();
+    const script = join(__dirname, "engine-invoke.cjs");
+    const r = spawnSync(process.execPath, [script, "pin-bin", root], { encoding: "utf8" });
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /missing checkout pin/);
+  });
+});

package/tasks/engine.yml

@@ -2,11 +2,13 @@ version: '3'
 
 # Consumer engine resolution (#2022 Phase 3).
 #
-# Framework-source checkouts invoke the vendored `packages/runtime/dist/bin.js`.
+# Framework-source checkouts invoke the checkout pin
+# `node_modules/@deftai/directive-runtime/dist/bin.js` exclusively (#5805 / AC9.9).
+# Tip dogfood without publish is `task materialize:runtime`, not packages/runtime/dist.
 # npm consumer deposits copy @deftai/directive-content only — no bundled CLI —
-# so tasks fall back to the globally installed `deft` / `directive` command.
+# so tasks fall back to OVPR DEFT_ROOT/dist/bin.js or global `deft` / `directive`.
 # A deposit marker (package.json deftConsumerDeposit / .deft-consumer-deposit /
-# @deftai/directive-content name) forces that fallback for every verb (#3324).
+# @deftai/directive-content name) forces that deposit path for every verb (#3324).
 
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
@@ -59,7 +61,7 @@ tasks:
 
   invoke:
     internal: true
-    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (deposit / runtime fallback #2409 / #3324). Runtime/session verbs must not trigger engine:_ts-build / pnpm (#2181)."
+    desc: "Run a deft-ts verb from the checkout pin (framework-source #5805) or OVPR/global deposit path (#2409 / #3324). Ordinary framework-source verbs never fall through to packages/runtime/dist."
     # Run from the operator project root so deft verbs resolve USER_WORKING_DIR
     # correctly; without this, included engine.yml defaults cwd to tasks/ (#2022).
     dir: '{{.USER_WORKING_DIR}}'
@@ -71,23 +73,18 @@ tasks:
     cmds:
       - |
         set -eu
-        # OVPR consumer: DEFT_ROOT is node_modules/@deftai/directive-runtime → dist/bin.js.
-        # Framework source / legacy .deft/core: DEFT_ROOT/packages/runtime/dist/bin.js.
-        bin=""
-        if [ -f "{{.DEFT_ROOT}}/dist/bin.js" ]; then
-          bin="{{.DEFT_ROOT}}/dist/bin.js"
-        elif [ -f "{{.DEFT_ROOT}}/packages/runtime/dist/bin.js" ]; then
-          bin="{{.DEFT_ROOT}}/packages/runtime/dist/bin.js"
-        fi
-        root_pkg="{{.DEFT_ROOT}}/package.json"
-        # #3324: deposit marker (package.json field / file / content-package
-        # name) forces is_buildable_source=0 so every verb uses global CLI.
+        # #3324: deposit marker forces is_buildable_source=0 (consumer / OVPR path).
         is_buildable_source=0
         if node "{{.TASKFILE_DIR}}/engine-invoke.cjs" is-buildable-source "{{.DEFT_ROOT}}"; then
           is_buildable_source=1
         fi
-        if [ -n "$bin" ] && [ -f "$bin" ]; then
-          if [ "$is_buildable_source" = 1 ] && [ -f "$root_pkg" ]; then
+        if [ "$is_buildable_source" = 1 ]; then
+          # #5805 Prefer-A Bound: framework-source ordinary invoke is pin-exclusive.
+          # No packages/runtime/dist fallthrough; missing pin fails closed.
+          # Resolve pin from DEFT_ROOT so subdirectory cwd still finds the checkout pin (#5805).
+          pin_bin=$(node "{{.TASKFILE_DIR}}/engine-invoke.cjs" pin-bin "{{.DEFT_ROOT}}" ) || exit $?
+          root_pkg="{{.DEFT_ROOT}}/package.json"
+          if [ -f "$root_pkg" ]; then
             node -e "
               const fs=require('fs');
               const pkg=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));
@@ -101,80 +98,22 @@ tasks:
               }
             " "$root_pkg" || exit $?
           fi
-          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" vendored "$bin"
-        elif [ "$is_buildable_source" = 1 ]; then
-          first_token=$(node -e "process.stdout.write(JSON.parse(process.env.DEFT_ENGINE_CMD_JSON||'\"\"').split(/\\s+/)[0]||'')")
-          is_runtime_verb=0
-          case " ${first_token} " in
-            " session:start "|" session-start "|\
-            " session:ready "|" session-ready "|\
-            " occupancy:steal "|" occupancy-steal "|\
-            " occupancy:release "|" occupancy-release "|\
-            " occupancy:heartbeat "|" occupancy-heartbeat "|\
-            " occupancy:grant "|" occupancy-grant "|\
-            " session:end "|" session-end "|\
-            " lifecycle:event "|" lifecycle-event "|\
-            " verify:session-ritual "|" verify-session-ritual "|\
-            " verify:tools "|" verify-tools "|\
-            " triage:summary "|" triage-summary "|\
-            " triage:welcome "|" triage-welcome "|\
-            " verify:cache-fresh "|" verify-cache-fresh "|\
-            " preflight-cache "|\
-            " ownership:doctor "|" ownership-doctor "|\
-            " ownership:fix "|" ownership-fix "|\
-            " verify:ownership "|" verify-ownership ")
-              is_runtime_verb=1
-              ;;
-          esac
-          if [ "${DEFT_USE_GLOBAL_CLI:-}" = "1" ]; then
-            is_runtime_verb=1
+          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" vendored "$pin_bin"
+        else
+          # OVPR consumer / deposit: DEFT_ROOT is often the runtime package itself.
+          bin=""
+          if [ -f "{{.DEFT_ROOT}}/dist/bin.js" ]; then
+            bin="{{.DEFT_ROOT}}/dist/bin.js"
           fi
-          global_cli=""
-          if command -v deft >/dev/null 2>&1; then
-            global_cli=deft
+          if [ -n "$bin" ] && [ -f "$bin" ]; then
+            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" vendored "$bin"
+          elif command -v deft >/dev/null 2>&1; then
+            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global deft
           elif command -v directive >/dev/null 2>&1; then
-            global_cli=directive
-          fi
-          if [ "$is_runtime_verb" = 1 ] && [ -n "$global_cli" ]; then
-            node -e "
-              const {execFileSync}=require('child_process');
-              const root=process.argv[1];
-              const cli=process.argv[2];
-              let srcVer='0.0.0-dev';
-              try{
-                if(process.env.DEFT_RELEASE_VERSION){
-                  srcVer=process.env.DEFT_RELEASE_VERSION;
-                }else{
-                  srcVer=execFileSync('git',['describe','--tags','--abbrev=0'],{cwd:root,encoding:'utf8'}).trim().replace(/^v/,'');
-                }
-              }catch{}
-              let globalVer='unknown';
-              try{
-                globalVer=execFileSync(cli,['--version'],{encoding:'utf8'}).trim();
-              }catch{}
-              const m=globalVer.match(/@([0-9]+\\.[0-9]+\\.[0-9]+)/)||globalVer.match(/([0-9]+\\.[0-9]+\\.[0-9]+)/);
-              const gv=m?m[1]:globalVer;
-              if(srcVer!=='0.0.0-dev'&&gv!=='unknown'&&gv!==srcVer){
-                console.error('deft: using global '+cli+' ('+gv+'); source checkout is v'+srcVer+' — run task build for a local engine match.');
-              }
-            " "{{.DEFT_ROOT}}" "$global_cli" >&2 || true
-            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global "$global_cli"
+            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global directive
           else
-            echo "deft: CLI artifact missing under {{.DEFT_ROOT}} (tried dist/bin.js and packages/runtime/dist/bin.js)" >&2
-            if [ "$is_runtime_verb" = 1 ]; then
-              echo "  Install global deft: npm i -g @deftai/directive" >&2
-              echo "  Or run \`task build\` first (framework source checkout)." >&2
-            else
-              echo "  Run \`task build\` first (framework source checkout)." >&2
-            fi
+            echo "deft: neither OVPR bin.js under {{.DEFT_ROOT}} nor a global deft command is available." >&2
+            echo "  Install with: npm i -g @deftai/directive" >&2
             exit 2
           fi
-        elif command -v deft >/dev/null 2>&1; then
-          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global deft
-        elif command -v directive >/dev/null 2>&1; then
-          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global directive
-        else
-          echo "deft: neither OVPR/legacy bin.js under {{.DEFT_ROOT}} nor a global deft command is available." >&2
-          echo "  Install with: npm i -g @deftai/directive" >&2
-          exit 2
         fi

package/tasks/eval.yml

@@ -6,8 +6,6 @@ vars:
 tasks:
   health:
     desc: "Tier 0 static self-consistency aggregation -- versioned framework health score (#1703). -- task eval:health [-- --json] [--no-persist] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -15,8 +13,6 @@ tasks:
 
   run:
     desc: "Tier 2 golden corpus champion-challenger eval (#1703). -- task eval:run -- --model MODEL [--seed N] [--directive-version V] [--harness NAME] [--json] [--no-persist] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -24,8 +20,6 @@ tasks:
 
   report:
     desc: "Tier 2 version-diff report with significance (#1703). -- task eval:report -- --champion V --challenger V --model MODEL [--json] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -33,8 +27,6 @@ tasks:
 
   triggers:
     desc: "Trigger routing coverage for AGENTS.md / Skills Index (#1586). Offline skill-pi-trigger-eval compatible eval over evals/trigger-cases.jsonl vs REFERENCES.md. -- task eval:triggers [-- --json] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/feedback.yml

@@ -6,8 +6,6 @@ vars:
 tasks:
   file:
     desc: "Draft or file a deduped framework-gap issue upstream (#1709 / #3713). -- task feedback:file -- [--summary TEXT | positional] [--context ...] [--blocker] [--confirm] [--dry-run] [--json]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/install.yml

@@ -20,8 +20,6 @@ tasks:
   uninstall:
     desc: Remove deft entry from AGENTS.md
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -62,8 +60,6 @@ tasks:
     # `task upgrade` failed on the primary npm consumer workflow. Framework-root is
     # intentionally omitted: install-upgrade auto-detects the consumer's
     # `.deft/core/VERSION` (#2053) when run from the global engine.
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/issue.yml

@@ -22,8 +22,6 @@ tasks:
   ingest:
     desc: "Ingest GitHub issues as scope vBRIEFs (single <N> or --all [--label L] [--status S] [--dry-run])"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -39,7 +37,6 @@ tasks:
   emit:
     desc: "File GitHub issue(s) from scope vBRIEF(s) (<path> | --umbrella <glob> | --per-vbrief <glob> [--dry-run])"
     dir: '{{.USER_WORKING_DIR}}'
-    deps: [":engine:_ts-build"]
     env:
       PYTHONUTF8: "1"
     cmds:

package/tasks/lifecycle.yml

@@ -27,7 +27,6 @@ tasks:
   stats:
     desc: "Local xBRIEF lifecycle folder counts for process rollups (#2995). -- task lifecycle:stats -- --since=7d [--json] [--project-root <path>]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps: [':engine:_ts-build']
     env:
       PYTHONUTF8: "1"
     cmds:

package/tasks/materialize.cjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Thin tip→pin materialize (#5805 Prefer-A Bound P3/P4).
+ * Stages + packs via existing scripts, then replaces this checkout's
+ * node_modules/@deftai/directive-runtime only. No package.json/lockfile
+ * location-spec mutation. Serializes via a lockfile under .deft-scratch.
+ */
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const PIN_PKG = path.join("node_modules", "@deftai", "directive-runtime");
+const LOCK_REL = path.join(".deft-scratch", "materialize-runtime.lock");
+const OVERLAY_REL = path.join(".deft-scratch", "materialize-runtime-overlay.json");
+
+function fail(msg, code = 2) {
+  console.error(`materialize:runtime: ${msg}`);
+  process.exit(code);
+}
+
+function runNode(script, args, opts = {}) {
+  const r = spawnSync(process.execPath, [script, ...args], {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+  });
+  if (r.status !== 0) {
+    const err = new Error(
+      `${path.basename(script)} failed (exit ${r.status}): ${r.stderr || r.stdout || ""}`.trim(),
+    );
+    err.code = r.status || 2;
+    throw err;
+  }
+  return (r.stdout || "").trim();
+}
+
+function acquireLock(projectRoot) {
+  const lockPath = path.join(projectRoot, LOCK_REL);
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  try {
+    const fd = fs.openSync(lockPath, "wx");
+    fs.writeFileSync(fd, `${process.pid}\n${new Date().toISOString()}\n`);
+    fs.closeSync(fd);
+    return lockPath;
+  } catch (err) {
+    if (err && err.code === "EEXIST") {
+      const locked = new Error(
+        `another materialize is in progress (lock ${lockPath}); reject second writer`,
+      );
+      locked.code = "EEXIST";
+      throw locked;
+    }
+    throw err;
+  }
+}
+
+function releaseLock(lockPath) {
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** True when dir is safe to replace: missing, or a real directory whose realpath is under checkoutRoot. */
+function isCheckoutOwnedDir(dir, checkoutRoot) {
+  try {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink()) {
+      // pnpm pin is often a symlink into the checkout store — allow when realpath stays in-tree.
+      if (!checkoutRoot) return false;
+      let real;
+      try {
+        real = fs.realpathSync(dir);
+      } catch {
+        return false;
+      }
+      const rootReal = fs.realpathSync(checkoutRoot);
+      const rel = path.relative(rootReal, real);
+      return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    }
+    if (!st.isDirectory()) return false;
+    if (!checkoutRoot) return true;
+    let real;
+    try {
+      real = fs.realpathSync(dir);
+    } catch {
+      return false;
+    }
+    const rootReal = fs.realpathSync(checkoutRoot);
+    const rel = path.relative(rootReal, real);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+  } catch {
+    return true; // missing is fine; we will create
+  }
+}
+
+function rmrf(target) {
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function movePath(src, dest) {
+  try {
+    fs.renameSync(src, dest);
+  } catch (err) {
+    if (err && err.code === "EXDEV") {
+      fs.cpSync(src, dest, { recursive: true, force: true });
+      rmrf(src);
+      return;
+    }
+    throw err;
+  }
+}
+
+function materialize(projectRoot, opts = {}) {
+  const root = path.resolve(projectRoot);
+  const stageScript = path.join(root, "packages", "runtime", "scripts", "stage-bundle.mjs");
+  const packScript = path.join(root, "packages", "runtime", "scripts", "pack-staged-runtime.mjs");
+  if (!fs.existsSync(stageScript) || !fs.existsSync(packScript)) {
+    throw new Error("stage-bundle/pack-staged-runtime scripts missing; run from framework-source checkout");
+  }
+
+  const pinDir = path.join(root, PIN_PKG);
+  if (fs.existsSync(pinDir) && !isCheckoutOwnedDir(pinDir, root)) {
+    throw new Error(`refusing to mutate linked/shared pin at ${pinDir}`);
+  }
+
+  const lockPath = acquireLock(root);
+  const priorPinUsable = fs.existsSync(path.join(pinDir, "dist", "bin.js"));
+  let priorBackup = null;
+  let stageDir;
+  let packDir;
+  let extractDir;
+  try {
+    stageDir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-materialize-stage-"));
+    packDir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-materialize-pack-"));
+    runNode(stageScript, [stageDir], { cwd: root });
+    const tgz = runNode(packScript, [stageDir, packDir], { cwd: root });
+    if (!tgz || !fs.existsSync(tgz)) fail(`pack did not emit tgz (got ${JSON.stringify(tgz)})`);
+
+    extractDir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-materialize-extract-"));
+    const tar = spawnSync(
+      process.platform === "win32" ? "tar.exe" : "tar",
+      ["-xzf", tgz, "-C", extractDir],
+      { encoding: "utf8" },
+    );
+    if (tar.status !== 0) {
+      throw Object.assign(new Error(`tar extract failed: ${tar.stderr || tar.stdout || ""}`.trim()), { code: tar.status || 2 });
+    }
+    const entries = fs.readdirSync(extractDir);
+    if (entries.length !== 1) throw new Error(`expected one package folder in tgz, got ${entries.join(",")}`);
+    const extracted = path.join(extractDir, entries[0]);
+
+    const parent = path.dirname(pinDir);
+    fs.mkdirSync(parent, { recursive: true });
+    const stagingPin = path.join(parent, `.directive-runtime-next-${process.pid}`);
+    rmrf(stagingPin);
+    movePath(extracted, stagingPin);
+    if (!fs.existsSync(path.join(stagingPin, "dist", "bin.js"))) {
+      throw new Error("staged pin bin missing before replacement");
+    }
+    // Keep recoverable backup until replacement succeeds.
+    if (fs.existsSync(pinDir)) {
+      priorBackup = path.join(parent, `.directive-runtime-prev-${process.pid}`);
+      rmrf(priorBackup);
+      movePath(pinDir, priorBackup);
+    }
+    try {
+      movePath(stagingPin, pinDir);
+    } catch (err) {
+      if (priorBackup && fs.existsSync(priorBackup)) {
+        try {
+          movePath(priorBackup, pinDir);
+          priorBackup = null;
+        } catch {
+          /* best-effort restore */
+        }
+      }
+      throw err;
+    }
+    if (priorBackup) {
+      rmrf(priorBackup);
+      priorBackup = null;
+    }
+
+    let head = "unknown";
+    try {
+      const g = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" });
+      if (g.status === 0) head = g.stdout.trim();
+    } catch {
+      /* ignore */
+    }
+    const overlay = {
+      schema: "deft.materialize.runtime.overlay.v1",
+      writtenAt: new Date().toISOString(),
+      projectRoot: root,
+      pinPath: pinDir,
+      sourceRevision: head,
+      tarball: path.basename(tgz),
+      note: "Local tip overlay into checkout pin; package.json/lockfile pins unchanged. Normal PM install restores registry pin.",
+    };
+    fs.writeFileSync(path.join(root, OVERLAY_REL), `${JSON.stringify(overlay, null, 2)}\n`);
+    if (!fs.existsSync(path.join(pinDir, "dist", "bin.js"))) {
+      throw new Error("materialize completed but pin bin missing");
+    }
+    process.stdout.write(`materialize:runtime: installed tip into ${pinDir}\n`);
+    process.stdout.write(`materialize:runtime: overlay ${path.join(root, OVERLAY_REL)}\n`);
+    return overlay;
+  } catch (err) {
+    if (priorPinUsable) {
+      console.error("materialize:runtime: failed after stage/pack; prior pin left in place");
+    }
+    throw err;
+  } finally {
+    releaseLock(lockPath);
+    if (stageDir) rmrf(stageDir);
+    if (packDir) rmrf(packDir);
+    if (extractDir) rmrf(extractDir);
+    if (priorBackup) rmrf(priorBackup);
+  }
+}
+
+if (require.main === module) {
+  const root = process.argv[2] || process.cwd();
+  try {
+    materialize(root);
+  } catch (err) {
+    fail(err && err.message ? err.message : String(err), err && err.code ? Number(err.code) || 2 : 2);
+  }
+}
+
+module.exports = {
+  materialize,
+  acquireLock,
+  releaseLock,
+  isCheckoutOwnedDir,
+  movePath,
+  PIN_PKG,
+  LOCK_REL,
+  OVERLAY_REL,
+};

package/tasks/materialize.test.cjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  symlinkSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+} = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const { describe, it, after } = require("node:test");
+const {
+  acquireLock,
+  releaseLock,
+  isCheckoutOwnedDir,
+  movePath,
+  materialize,
+  LOCK_REL,
+} = require("./materialize.cjs");
+
+const roots = [];
+function tempRoot() {
+  const root = mkdtempSync(join(tmpdir(), "mat-test-"));
+  roots.push(root);
+  return root;
+}
+after(() => {
+  for (const root of roots) {
+    try {
+      rmSync(root, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+});
+
+describe("materialize isolation (#5805 P4)", () => {
+  it("acquireLock rejects a second writer", () => {
+    const root = tempRoot();
+    const lock = acquireLock(root);
+    assert.ok(existsSync(join(root, LOCK_REL)));
+    assert.throws(() => acquireLock(root), /another materialize|second writer|EEXIST|in progress/i);
+    releaseLock(lock);
+  });
+
+  it("isCheckoutOwnedDir is false for a symlink outside the checkout", () => {
+    const root = tempRoot();
+    const outside = tempRoot();
+    const real = join(outside, "real-pkg");
+    const link = join(root, "linked-pkg");
+    mkdirSync(real, { recursive: true });
+    try {
+      symlinkSync(real, link, "junction");
+    } catch {
+      return;
+    }
+    assert.equal(isCheckoutOwnedDir(link, root), false);
+    assert.equal(isCheckoutOwnedDir(real, outside), true);
+  });
+
+  it("isCheckoutOwnedDir allows in-tree symlink (pnpm-style)", () => {
+    const root = tempRoot();
+    const store = join(root, ".pnpm", "pkg");
+    const link = join(root, "node_modules", "@deftai", "directive-runtime");
+    mkdirSync(store, { recursive: true });
+    mkdirSync(join(root, "node_modules", "@deftai"), { recursive: true });
+    try {
+      symlinkSync(store, link, "junction");
+    } catch {
+      return;
+    }
+    assert.equal(isCheckoutOwnedDir(link, root), true);
+  });
+
+  it("missing destination is treated as checkout-owned (creatable)", () => {
+    const root = tempRoot();
+    assert.equal(isCheckoutOwnedDir(join(root, "missing"), root), true);
+  });
+
+  it("movePath falls back when rename would need copy semantics", () => {
+    const root = tempRoot();
+    const src = join(root, "src-dir");
+    const dest = join(root, "dest-dir");
+    mkdirSync(src, { recursive: true });
+    writeFileSync(join(src, "f.txt"), "ok");
+    movePath(src, dest);
+    assert.equal(readFileSync(join(dest, "f.txt"), "utf8"), "ok");
+    assert.equal(existsSync(src), false);
+  });
+
+  it("failed materialize releases the lock so retries can proceed", () => {
+    const root = tempRoot();
+    assert.throws(() => materialize(root), /stage-bundle|pack-staged|missing/i);
+    assert.equal(existsSync(join(root, LOCK_REL)), false);
+    const lock = acquireLock(root);
+    releaseLock(lock);
+  });
+});