@deftai/directive-content 0.82.0 → 0.83.0

package/commands.md

@@ -187,12 +187,14 @@ Use `task --list` for the exact current verify namespace.
 
 ### Agent-host direct-write hooks (#2438, #2596)
 
-`directive init` and `deft update` idempotently merge Directive-owned entries into `.claude/settings.json`, `.grok/hooks/deft.json`, `.cursor/hooks.json`, and `.codex/hooks.json` while preserving unrelated settings. `SessionStart` refreshes resume bookkeeping on a non-blocking path. `PreToolUse` covers direct edit/write tools and denies them until both existing gates pass: a fresh gated session ritual and an active/running xBRIEF accepted by canonical preflight. A second `PreToolUse` matcher covers spawn/Task tools (`Task`, `SubagentStart`, `spawn_subagent`, `start_agent`, `CreateAgent`) with the same pre-`start_agent` gate stack; explore spawns (`subagent_type: explore`) pass without implementation gates.
+`directive init` and `deft update` idempotently merge Directive-owned entries into `.claude/settings.json`, `.grok/hooks/deft.json`, `.cursor/hooks.json`, and `.codex/hooks.json` while preserving unrelated settings. `SessionStart` refreshes resume bookkeeping on a non-blocking path. `PreToolUse` covers direct edit/write tools and denies them until both existing gates pass: a fresh gated session ritual and an active/running xBRIEF accepted by canonical preflight. Cursor `preToolUse` deposits set `failClosed: true`, so allow decisions emit `{"permission":"allow"}` — empty stdout is treated as hook failure and would block Write tools. A second `PreToolUse` matcher covers spawn/Task tools (`Task`, `SubagentStart`, `spawn_subagent`, `start_agent`, `CreateAgent`) with the same pre-`start_agent` gate stack; explore spawns (`subagent_type: explore`) pass without implementation gates.
 
 - **Read-only explore (#1185):** Prefer Grok role deposit `default_capability_mode = "read-only"` (see [issue #1185](https://github.com/deftai/directive/issues/1185)). Hooks also deny direct writes when `DEFT_HOOK_READ_ONLY=1` or the host payload signals read-only capability. Implementation spawns remain blocked in read-only posture unless explicitly marked explore.
 
 - Verify registration: `deft verify:hooks-installed --scope=agent` (or `--scope=all` for git + agent hooks).
 - Repair missing/drifted entries: `deft update`.
+- **Opt-out (#2752):** Set `plan.policy.hostHooks.<host>` to `false` in `xbrief/PROJECT-DEFINITION.xbrief.json` for any of the four deposited hosts (`claude`, `cursor`, `grok`, `codex`). Unset or `true` keeps the current fail-closed deposit. When a host is opted out, `deft update` / `directive init` skip creating or re-merging Directive-managed hook entries for that host; if a prior deposit left managed entries in the file, the next update strips only those entries and preserves unrelated settings. Inspect with `deft policy:show --field=hostHooks`. Doctor and `verify:hooks-installed --scope=agent` treat opted-out hosts as healthy — they do not recommend `deft update` to repair them.
+- **Claude matcher scope:** Once `.claude/settings.json` hooks are loaded, Claude's `PreToolUse` matcher keys on tool names (`Edit`, `Write`, …), not target paths — matched tools can be gated for the whole session, including writes outside the project tree. Opt out of Claude hook deposit when that posture is unwanted.
 - **Compact re-arm (#2113):** Cursor `preCompact` and Claude/Grok `PreCompact`/`PostCompact` call `deft hook:dispatch --event session.compact` to mark the gated session ritual stale after context compaction/resume; the existing PreToolUse gate then denies direct writes until `deft session:start` and `deft verify:session-ritual -- --tier=gated`. Codex has no native compact hook — operators must re-run the mutation ritual manually after compaction.
 - Codex project hooks are trust-gated by Codex. Directive verifies only that the registrations are structurally current; after an install or changed hook hash, open `/hooks` in Codex and review/approve the project hook commands. Runtime trust cannot be inferred from the file alone.
 - Directive writes only `.codex/hooks.json`; it does not parse or modify `.codex/config.toml`. Codex can also load inline hooks from `config.toml`, so avoid defining duplicate Directive commands there or they may run more than once. See the [Codex hooks documentation](https://learn.chatgpt.com/docs/hooks).

package/docs/product-signal.md

@@ -15,13 +15,15 @@ Capability-cost disclosure prints before `--confirm` applies `plan.policy.produc
 
 Consent file: `%APPDATA%\\deft\\product-signal-consent.json` (Windows) or `~/.config/deft/product-signal-consent.json` (Unix).
 
+Schema **v2** records the normalized `owner/repo` sink you authorize (#2767). Legacy v1 consent authorizes only the baked-in default `deftai/product-signal`; a custom `plan.policy.productSignal.sinkRepo` requires re-consent after grant.
+
 ```bash
-task product-signal:consent -- --grant
+task product-signal:consent -- --grant [--project-root .]
 task product-signal:consent -- --revoke
 task product-signal:status
 ```
 
-Outbound requires **both** enable and consent.
+`task product-signal:status` shows configured sink, consented sink, and whether they match. Outbound requires **both** enable and consent, and the configured sink must match the consented destination (including dry-run).
 
 ## Submit (ops / tests)
 
@@ -29,6 +31,8 @@ Outbound requires **both** enable and consent.
 task product-signal:submit -- --surface pulse|portrait [--dry-run] [--json] [--nps 0-10]
 ```
 
+Changing `sinkRepo` after consent soft-skips with `sink-unconsented` until you re-run consent for the new destination. Destination authorization cannot be bypassed with `skipGates`.
+
 ## Sink bootstrap (maintainers)
 
 Internal (org) inbox: `deftai/product-signal` (overridable via `plan.policy.productSignal.sinkRepo`). Not public.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [

package/packs/skills/skills-pack-0.1.json

@@ -187,7 +187,7 @@
       ],
       "path": "skills/deft-directive-product-signal/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Product Signal — consented check-in (#2693)\n\nAgent-driven qualitative product-improvement signal for partner/trial installs. Lightweight interview, minimized local summaries (value/health/helped), optional skillsSummary hook — submits to private `deftai/product-signal` when enable + consent gates pass.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- Operator says `product check-in`, `product pulse`, `partner feedback`, or `product signal`\n- Partner onboarding after ops enables `plan.policy.productSignal`\n- ⊗ Do NOT invoke from session:start or ambient rituals when disabled (#2693 D3)\n\n## Preconditions\n\n- ! `plan.policy.productSignal.enabled` MUST be true (`task policy:show --field=productSignal`)\n- ! Install-level consent MUST be recorded before outbound submit (`task product-signal:status`)\n- ⊗ Prompt or submit when `enabled` is false\n- ⊗ Block story work on sink errors — fail open (#2693 D16/D18)\n\n## Phase 1 — Gate\n\n```bash\ntask product-signal:status\ntask policy:show -- --field=productSignal\n```\n\n- ! If disabled: soft-skip with one line; exit skill\n- ! If headless/CI: fail open — no consent/interview prompts (#2693 D16)\n\n## Phase 2 — First-time consent (interactive only, D17)\n\nWhen enabled, interactive, and consent missing/revoked, ask:\n\n> May we collect usage metrics and related session signal from this install to improve Directive? This can include a short check-in plus minimized local summaries (value/health and related ledgers). Nothing is sent while this path is off or without your consent.\n>\n> If you are unsure, please check with your company before saying no — they are a Directive partner and may already expect this signal to be shared.\n>\n> Reply **yes** to consent, or **no** to decline.\n\n- **yes** → `task product-signal:consent -- --grant`; continue\n- **no** → soft-skip; do not badger every turn\n\n## Phase 3 — Interview (≤3 answers + optional NPS)\n\n- ! Ask at most three short questions plus optional NPS (0–10)\n- ~ Target ≤30s human time beyond first-time consent\n- ⊗ Paste secrets, paths, raw logs, or full USER.md into answers\n\n## Phase 4 — Assemble + validate + submit\n\n```bash\ntask product-signal:submit -- --surface pulse --dry-run\ntask product-signal:submit -- --surface pulse --nps 9\n```\n\n- ! On validation failure: show reason; no partial write\n- ! On sink ACL/network errors: soft-skip with hint; do not fail caller (#2693 D18)\n- ! Report issue URL on success\n\n## Private gaps (D19)\n\n- ! Record bugs/gaps as `Gap:` comments on the standing **pulse** thread (enable+consent sufficient)\n- ! Public promote to `deftai/directive` remains hard-confirm via `deft-directive-feedback` / `task feedback:file`\n\n## Revoke\n\n```bash\ntask product-signal:consent -- --revoke\n# and/or disable: set plan.policy.productSignal.enabled false\n```\n\n## Anti-Patterns\n\n- ⊗ Ambient consent nag when disabled\n- ⊗ Fail-closed headless behavior\n- ⊗ Sticky forever-fail when sink is down\n- ⊗ Auto-file public framework-gap issues from pulses\n\n## Exit\n\ndeft-directive-product-signal complete — exiting skill.\n",
+      "body": "# Deft Directive Product Signal — consented check-in (#2693)\n\nAgent-driven qualitative product-improvement signal for partner/trial installs. Lightweight interview, minimized local summaries (value/health/helped), optional skillsSummary hook — submits to private `deftai/product-signal` when enable + consent gates pass.\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n## When to Use\n\n- Operator says `product check-in`, `product pulse`, `partner feedback`, or `product signal`\n- Partner onboarding after ops enables `plan.policy.productSignal`\n- ⊗ Do NOT invoke from session:start or ambient rituals when disabled (#2693 D3)\n\n## Preconditions\n\n- ! `plan.policy.productSignal.enabled` MUST be true (`task policy:show --field=productSignal`)\n- ! Install-level consent MUST be recorded before outbound submit (`task product-signal:status`)\n- ! Consent schema v2 binds to the configured sinkRepo; legacy v1 consent authorizes only `deftai/product-signal` (#2767)\n- ! Re-consent after changing `plan.policy.productSignal.sinkRepo`; mismatch soft-skips as sink-unconsented\n- ⊗ Prompt or submit when `enabled` is false\n- ⊗ Block story work on sink errors — fail open (#2693 D16/D18)\n\n## Phase 1 — Gate\n\n```bash\ntask product-signal:status\ntask policy:show -- --field=productSignal\n```\n\n- ! If disabled: soft-skip with one line; exit skill\n- ! If headless/CI: fail open — no consent/interview prompts (#2693 D16)\n\n## Phase 2 — First-time consent (interactive only, D17)\n\nWhen enabled, interactive, and consent missing/revoked, ask:\n\n> May we collect usage metrics and related session signal from this install to improve Directive? This can include a short check-in plus minimized local summaries (value/health and related ledgers). Nothing is sent while this path is off or without your consent.\n>\n> If you are unsure, please check with your company before saying no — they are a Directive partner and may already expect this signal to be shared.\n>\n> Reply **yes** to consent, or **no** to decline.\n\n- **yes** → `task product-signal:consent -- --grant` (pass `--project-root` when using a custom sinkRepo); continue\n- **no** → soft-skip; do not badger every turn\n\n## Phase 3 — Interview (≤3 answers + optional NPS)\n\n- ! Ask at most three short questions plus optional NPS (0–10)\n- ~ Target ≤30s human time beyond first-time consent\n- ⊗ Paste secrets, paths, raw logs, or full USER.md into answers\n\n## Phase 4 — Assemble + validate + submit\n\n```bash\ntask product-signal:submit -- --surface pulse --dry-run\ntask product-signal:submit -- --surface pulse --nps 9\n```\n\n- ! On validation failure: show reason; no partial write\n- ! On sink ACL/network errors: soft-skip with hint; do not fail caller (#2693 D18)\n- ! Report issue URL on success\n\n## Private gaps (D19)\n\n- ! Record bugs/gaps as `Gap:` comments on the standing **pulse** thread (enable+consent sufficient)\n- ! Public promote to `deftai/directive` remains hard-confirm via `deft-directive-feedback` / `task feedback:file`\n\n## Revoke\n\n```bash\ntask product-signal:consent -- --revoke\n# and/or disable: set plan.policy.productSignal.enabled false\n```\n\n## Anti-Patterns\n\n- ⊗ Ambient consent nag when disabled\n- ⊗ Fail-closed headless behavior\n- ⊗ Sticky forever-fail when sink is down\n- ⊗ Auto-file public framework-gap issues from pulses\n\n## Exit\n\ndeft-directive-product-signal complete — exiting skill.\n",
       "frontmatter_extra": null
     },
     {

package/skills/deft-directive-product-signal/SKILL.md

@@ -27,6 +27,8 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 - ! `plan.policy.productSignal.enabled` MUST be true (`task policy:show --field=productSignal`)
 - ! Install-level consent MUST be recorded before outbound submit (`task product-signal:status`)
+- ! Consent schema v2 binds to the configured sinkRepo; legacy v1 consent authorizes only `deftai/product-signal` (#2767)
+- ! Re-consent after changing `plan.policy.productSignal.sinkRepo`; mismatch soft-skips as sink-unconsented
 - ⊗ Prompt or submit when `enabled` is false
 - ⊗ Block story work on sink errors — fail open (#2693 D16/D18)
 
@@ -50,7 +52,7 @@ When enabled, interactive, and consent missing/revoked, ask:
 >
 > Reply **yes** to consent, or **no** to decline.
 
-- **yes** → `task product-signal:consent -- --grant`; continue
+- **yes** → `task product-signal:consent -- --grant` (pass `--project-root` when using a custom sinkRepo); continue
 - **no** → soft-skip; do not badger every turn
 
 ## Phase 3 — Interview (≤3 answers + optional NPS)

package/tasks/engine-pm-run.cjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Run package.json scripts via pnpm / Corepack without shell-interpolating
+ * repository-controlled packageManager pins (#2765 / #2761).
+ *
+ * Consumed by tasks/engine.yml `:engine:pm-run` and `:engine:_ts-build`.
+ * Lives under tasks/ so @deftai/directive-content prepack ships it beside
+ * tasks/engine.yml (#2022 Phase 3).
+ */
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const WIN32_ALLOWLIST = new Set(["pnpm", "corepack", "npm"]);
+const SHELL_METACHAR_RE = /[;&|`$<>()\\'"!#\n\r\t]/;
+const SEMVER_RE =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+const SCRIPT_NAME_RE = /^[A-Za-z0-9:_-]+$/;
+
+/** @param {string | null | undefined} version */
+function isValidSemVer(version) {
+  return typeof version === "string" && SEMVER_RE.test(version);
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ ok: true, semver: string | null, pin: string | null } | { ok: false, reason: string }}
+ */
+function parsePnpmPin(raw) {
+  if (raw === undefined || raw === null || raw === "") {
+    return { ok: true, semver: null, pin: null };
+  }
+  const str = String(raw);
+  if (str !== str.trim()) {
+    return { ok: false, reason: "packageManager has leading/trailing whitespace" };
+  }
+  if (/\s/.test(str)) {
+    return { ok: false, reason: "packageManager contains whitespace" };
+  }
+  if (SHELL_METACHAR_RE.test(str)) {
+    return { ok: false, reason: "packageManager contains shell metacharacters" };
+  }
+  if (!str.startsWith("pnpm@")) {
+    return { ok: false, reason: "packageManager must be pnpm@<semver> when set" };
+  }
+  const semver = str.slice("pnpm@".length);
+  if (!semver || !isValidSemVer(semver)) {
+    return { ok: false, reason: "packageManager semver is invalid" };
+  }
+  if (str !== `pnpm@${semver}`) {
+    return { ok: false, reason: "packageManager pin malformed" };
+  }
+  return { ok: true, semver, pin: str };
+}
+
+/**
+ * @param {unknown} name
+ * @param {Record<string, unknown> | undefined} scripts
+ */
+function validateScriptName(name, scripts) {
+  if (typeof name !== "string" || !name || !SCRIPT_NAME_RE.test(name)) {
+    return false;
+  }
+  return !!scripts && Object.prototype.hasOwnProperty.call(scripts, name);
+}
+
+/** @param {string} arg */
+function quoteWin32Arg(arg) {
+  const s = String(arg);
+  if (!/[\s"]/.test(s)) {
+    return s;
+  }
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
+/**
+ * @param {typeof execFileSync} execFn
+ * @param {string} name
+ */
+function hasCmd(execFn, name) {
+  const spawnOpts = (/** @type {Record<string, unknown>} */ extra) => ({
+    stdio: "ignore",
+    windowsHide: true,
+    ...extra,
+  });
+  try {
+    execFn(name, ["--version"], spawnOpts({}));
+    return true;
+  } catch {
+    try {
+      execFn(name, ["--version"], spawnOpts({ shell: true }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * @param {typeof execFileSync} execFn
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd: string, spawn?: Record<string, unknown> }} opts
+ */
+function executeAllowlisted(execFn, cmd, args, opts) {
+  if (!WIN32_ALLOWLIST.has(cmd)) {
+    throw new Error(`deft: allowlisted shim required, got ${JSON.stringify(cmd)}`);
+  }
+  const spawnOverride = opts.spawn && typeof opts.spawn === "object" ? opts.spawn : {};
+  const base = {
+    cwd: opts.cwd,
+    stdio: "inherit",
+    windowsHide: true,
+    shell: false,
+    ...spawnOverride,
+    shell: false,
+  };
+  if (process.platform === "win32") {
+    const commandLine = [quoteWin32Arg(cmd), ...args.map(quoteWin32Arg)].join(" ");
+    execFn("cmd.exe", ["/d", "/s", "/c", commandLine], base);
+    return;
+  }
+  execFn(cmd, args, base);
+}
+
+/**
+ * @param {{ hasPnpm: boolean, hasCorepack: boolean, semver: string | null, script: string }} input
+ */
+function buildDispatchSteps(input) {
+  const steps = [];
+  if (input.hasPnpm) {
+    steps.push({ cmd: "pnpm", args: ["run", input.script] });
+  }
+  if (input.hasCorepack && input.semver) {
+    steps.push({ cmd: "corepack", args: [`pnpm@${input.semver}`, "run", input.script] });
+  }
+  if (input.hasCorepack) {
+    steps.push({ cmd: "corepack", args: ["pnpm", "run", input.script] });
+  }
+  return steps;
+}
+
+/** @param {string} root */
+function markWarm(root) {
+  try {
+    const dist = path.join(root, "packages", "cli", "dist");
+    fs.mkdirSync(dist, { recursive: true });
+    fs.writeFileSync(path.join(dist, ".deft-ts-build-stamp"), new Date().toISOString());
+  } catch {
+    // best-effort warm marker
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} script
+ * @param {{ execFileSync?: typeof execFileSync, markWarm?: boolean }} [deps]
+ */
+function runPackageScript(root, script, deps = {}) {
+  const execFn = deps.execFileSync || execFileSync;
+  const pkgPath = path.join(root, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    console.error(`deft: package.json missing at ${root}`);
+    return 2;
+  }
+  let pkg;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.error(`deft: package.json at ${root} is not a JSON object`);
+      return 2;
+    }
+    pkg = parsed;
+  } catch {
+    console.error(`deft: package.json at ${root} is not valid JSON`);
+    return 2;
+  }
+  if (!validateScriptName(script, pkg.scripts)) {
+    console.error(`deft: package.json has no script ${JSON.stringify(script)}`);
+    return 2;
+  }
+
+  const pinResult = parsePnpmPin(pkg.packageManager);
+  if (!pinResult.ok) {
+    console.error(`deft: invalid packageManager pin — ${pinResult.reason}`);
+    return 3;
+  }
+
+  const envPm = String(process.env.DEFT_PACKAGE_MANAGER || "")
+    .trim()
+    .toLowerCase();
+  if (envPm === "npm") {
+    try {
+      executeAllowlisted(execFn, "npm", ["run", script], { cwd: root });
+      if (deps.markWarm) {
+        markWarm(root);
+      }
+      return 0;
+    } catch {
+      console.error(`deft: npm run ${JSON.stringify(script)} failed`);
+      return 1;
+    }
+  }
+
+  const hasPnpm = hasCmd(execFn, "pnpm");
+  const hasCorepack = hasCmd(execFn, "corepack");
+  const steps = buildDispatchSteps({
+    hasPnpm,
+    hasCorepack,
+    semver: pinResult.semver,
+    script,
+  });
+
+  for (const step of steps) {
+    try {
+      executeAllowlisted(execFn, step.cmd, step.args, { cwd: root });
+      if (deps.markWarm) {
+        markWarm(root);
+      }
+      return 0;
+    } catch {
+      // fall through to Corepack / next resolver
+    }
+  }
+
+  console.error(`deft: neither pnpm nor corepack is available to run ${JSON.stringify(script)}.`);
+  if (pinResult.pin) {
+    console.error(
+      `  Enable Corepack for the pinned manager: corepack enable && corepack prepare ${pinResult.pin} --activate`,
+    );
+  } else {
+    console.error("  Install pnpm or enable Corepack (see package.json#packageManager).");
+  }
+  console.error("  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.");
+  return 127;
+}
+
+function main() {
+  const root = process.argv[2];
+  const script = process.argv[3];
+  const markWarmFlag = process.argv.includes("--mark-warm");
+  if (!root || !script) {
+    console.error("deft: engine-pm-run usage: engine-pm-run.cjs <DEFT_ROOT> <script> [--mark-warm]");
+    process.exit(2);
+  }
+  const code = runPackageScript(root, script, { markWarm: markWarmFlag });
+  process.exit(code);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  SHELL_METACHAR_RE,
+  WIN32_ALLOWLIST,
+  buildDispatchSteps,
+  executeAllowlisted,
+  hasCmd,
+  isValidSemVer,
+  markWarm,
+  parsePnpmPin,
+  quoteWin32Arg,
+  runPackageScript,
+  validateScriptName,
+};

package/tasks/engine-pm-run.test.cjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { describe, it } = require("node:test");
+const {
+  buildDispatchSteps,
+  executeAllowlisted,
+  hasCmd,
+  parsePnpmPin,
+  runPackageScript,
+  validateScriptName,
+} = require("./engine-pm-run.cjs");
+
+describe("parsePnpmPin", () => {
+  it("accepts stable, prerelease, and build-metadata pins", () => {
+    for (const pin of ["pnpm@11.8.0", "pnpm@1.0.0-alpha.1", "pnpm@1.0.0+build.1"]) {
+      const result = parsePnpmPin(pin);
+      assert.equal(result.ok, true);
+    }
+  });
+
+  it("accepts missing/empty pins for unpinned fallback", () => {
+    assert.deepEqual(parsePnpmPin(undefined), { ok: true, semver: null, pin: null });
+    assert.deepEqual(parsePnpmPin(""), { ok: true, semver: null, pin: null });
+  });
+
+  it("rejects shell metacharacters and malformed pins before spawn", () => {
+    for (const pin of [
+      "pnpm@9.0.0; echo pwned",
+      "pnpm@9.0.0 & echo pwned",
+      "pnpm@^1.0.0",
+      "npm@1.0.0",
+      "pnpm@1.0.0 extra",
+      " pnpm@1.0.0",
+      "pnpm@1.0.0 ",
+      "pnpm@1.0.0\n",
+    ]) {
+      const result = parsePnpmPin(pin);
+      assert.equal(result.ok, false, pin);
+    }
+  });
+});
+
+describe("validateScriptName", () => {
+  it("accepts only declared script keys with safe names", () => {
+    const scripts = { build: "tsc", "test:unit": "vitest" };
+    assert.equal(validateScriptName("build", scripts), true);
+    assert.equal(validateScriptName("test:unit", scripts), true);
+    assert.equal(validateScriptName("missing", scripts), false);
+    assert.equal(validateScriptName("build;rm", scripts), false);
+  });
+});
+
+describe("buildDispatchSteps", () => {
+  it("preserves installed pnpm -> pinned corepack -> unpinned corepack order", () => {
+    const steps = buildDispatchSteps({
+      hasPnpm: true,
+      hasCorepack: true,
+      semver: "11.8.0",
+      script: "build",
+    });
+    assert.deepEqual(steps, [
+      { cmd: "pnpm", args: ["run", "build"] },
+      { cmd: "corepack", args: ["pnpm@11.8.0", "run", "build"] },
+      { cmd: "corepack", args: ["pnpm", "run", "build"] },
+    ]);
+  });
+});
+
+describe("runPackageScript security", () => {
+  function mkFixture(/** @type {Record<string, unknown>} */ pkgExtra) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "deft-engine-pm-run-"));
+    fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify(pkgExtra, null, 2), "utf8");
+    return dir;
+  }
+
+  it("rejects malicious pins before any execution call", () => {
+    const dir = mkFixture({
+      packageManager: "pnpm@9.0.0; echo pwned",
+      scripts: { build: "node -e \"\"" },
+    });
+    const sentinel = path.join(dir, "sentinel.txt");
+    let execCalls = 0;
+    const code = runPackageScript(dir, "build", {
+      execFileSync() {
+        execCalls += 1;
+        fs.writeFileSync(sentinel, "pwned", "utf8");
+      },
+    });
+    assert.equal(code, 3);
+    assert.equal(execCalls, 0);
+    assert.equal(fs.existsSync(sentinel), false);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("records exact argv on execution without shell:true", () => {
+    const dir = mkFixture({
+      packageManager: "pnpm@11.8.0",
+      scripts: { build: "tsc" },
+    });
+    /** @type {Array<{ cmd: string, args: string[], shell?: boolean, stdio?: string }>} */
+    const calls = [];
+    const code = runPackageScript(dir, "build", {
+      execFileSync(cmd, args, opts) {
+        calls.push({ cmd, args: [...args], shell: opts?.shell, stdio: opts?.stdio });
+        if (opts?.stdio === "inherit") {
+          return;
+        }
+      },
+    });
+    assert.equal(code, 0);
+    const execCalls = calls.filter((c) => c.stdio === "inherit");
+    assert.equal(execCalls.length, 1);
+    assert.equal(execCalls[0].shell, false);
+    assert.equal(execCalls[0].stdio, "inherit");
+    if (process.platform === "win32") {
+      assert.equal(execCalls[0].cmd, "cmd.exe");
+      assert.deepEqual(execCalls[0].args.slice(0, 3), ["/d", "/s", "/c"]);
+      assert.match(execCalls[0].args[3], /pnpm.*run.*build/);
+    } else {
+      assert.deepEqual(execCalls[0], {
+        cmd: "pnpm",
+        args: ["run", "build"],
+        shell: false,
+        stdio: "inherit",
+      });
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("allows probe hasCmd to use shell:true separately from execution", () => {
+    /** @type {Array<{ shell?: boolean, stdio?: string }>} */
+    const calls = [];
+    let probeAttempts = 0;
+    const execFn = (/** @type {string} */ _cmd, /** @type {string[]} */ _args, /** @type {{ shell?: boolean, stdio?: string }} */ opts) => {
+      if (opts?.stdio === "ignore") {
+        probeAttempts += 1;
+        if (probeAttempts === 1 && !opts.shell) {
+          throw new Error("probe without shell failed");
+        }
+      }
+      calls.push({ shell: opts?.shell, stdio: opts?.stdio });
+    };
+    assert.equal(hasCmd(execFn, "pnpm"), true);
+    assert.ok(calls.some((c) => c.shell === true && c.stdio === "ignore"));
+    const execCalls = calls.filter((c) => c.stdio === "inherit");
+    assert.equal(execCalls.length, 0);
+  });
+
+  it("rejects invalid package.json before probing PATH", () => {
+    const dir = mkFixture({ packageManager: "pnpm@11.8.0", scripts: { build: "tsc" } });
+    fs.writeFileSync(path.join(dir, "package.json"), "null", "utf8");
+    let execCalls = 0;
+    const code = runPackageScript(dir, "build", {
+      execFileSync() {
+        execCalls += 1;
+      },
+    });
+    assert.equal(code, 2);
+    assert.equal(execCalls, 0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("rejects unknown scripts before probing PATH", () => {
+    const dir = mkFixture({ packageManager: "pnpm@11.8.0", scripts: { build: "tsc" } });
+    let execCalls = 0;
+    const code = runPackageScript(dir, "lint", {
+      execFileSync() {
+        execCalls += 1;
+      },
+    });
+    assert.equal(code, 2);
+    assert.equal(execCalls, 0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("uses cmd.exe on win32 without shell:true on the Node spawn", () => {
+    if (process.platform !== "win32") {
+      return;
+    }
+    /** @type {{ cmd?: string, args?: string[], shell?: boolean } | null} */
+    let recorded = null;
+    executeAllowlisted(
+      (cmd, args, opts) => {
+        recorded = { cmd, args: [...args], shell: opts?.shell };
+      },
+      "pnpm",
+      ["run", "build"],
+      { cwd: process.cwd() },
+    );
+    assert.ok(recorded);
+    assert.equal(recorded.cmd, "cmd.exe");
+    assert.equal(recorded.args[0], "/d");
+    assert.equal(recorded.shell, false);
+    assert.match(recorded.args[3], /^pnpm run build$|^"pnpm" "run" "build"$/);
+  });
+});

package/tasks/engine.yml

@@ -20,71 +20,7 @@ tasks:
     cmds:
       - |
         set -eu
-        node -e "
-          const {execFileSync}=require('child_process');
-          const fs=require('fs');
-          const root=process.argv[1];
-          const script=process.argv[2];
-          const pkgPath=root+'/package.json';
-          if(!fs.existsSync(pkgPath)){
-            console.error('deft: package.json missing at '+root);
-            process.exit(2);
-          }
-          const pkg=JSON.parse(fs.readFileSync(pkgPath,'utf8'));
-          // Cross-platform probe (#2415): do NOT use Unix `sh -c 'command -v'` —
-          // Windows native Task often has no `sh` on PATH, so Corepack.cmd was
-          // invisible after #2411. Prefer a direct spawn (POSIX / real binaries);
-          // fall back to shell:true so PATHEXT resolves .cmd/.exe on win32.
-          // windowsHide (#2563): CREATE_NO_WINDOW so Cursor Task shells do not
-          // flood visible cmd.exe/conhost windows on every probe/build.
-          const spawnOpts=(extra)=>({stdio:'ignore',windowsHide:true,...extra});
-          const hasCmd=(name)=>{
-            try{
-              execFileSync(name,['--version'],spawnOpts());
-              return true;
-            }catch{
-              try{
-                execFileSync(name,['--version'],spawnOpts({shell:true}));
-                return true;
-              }catch{
-                return false;
-              }
-            }
-          };
-          const run=(cmd,args)=>{
-            execFileSync(cmd,args,{cwd:root,stdio:'inherit',shell:true,windowsHide:true});
-          };
-          const trySteps=(steps)=>{
-            for(const [cmd,args] of steps){
-              try{
-                run(cmd,args);
-                process.exit(0);
-              }catch{
-                // fall through to Corepack / next resolver
-              }
-            }
-          };
-          const envPm=String(process.env.DEFT_PACKAGE_MANAGER||'').trim().toLowerCase();
-          if(envPm==='npm'){
-            run('npm',['run',script]);
-            process.exit(0);
-          }
-          const pin=String(pkg.packageManager||'').trim();
-          const match=pin.match(/^pnpm@(.+)$/);
-          const steps=[];
-          if(hasCmd('pnpm')) steps.push(['pnpm',['run',script]]);
-          if(hasCmd('corepack')&&match) steps.push(['corepack',['pnpm@'+match[1],'run',script]]);
-          if(hasCmd('corepack')) steps.push(['corepack',['pnpm','run',script]]);
-          trySteps(steps);
-          console.error('deft: neither pnpm nor corepack is available to run \"'+script+'\".');
-          if(pin){
-            console.error('  Enable Corepack for the pinned manager: corepack enable && corepack prepare '+pin+' --activate');
-          }else{
-            console.error('  Install pnpm or enable Corepack (see package.json#packageManager).');
-          }
-          console.error('  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.');
-          process.exit(127);
-        " "{{.DEFT_ROOT}}" "{{.PM_SCRIPT}}"
+        node "{{.TASKFILE_DIR}}/engine-pm-run.cjs" "{{.DEFT_ROOT}}" "{{.PM_SCRIPT}}"
 
   _ts-build:
     internal: true
@@ -115,76 +51,7 @@ tasks:
           if node "{{.TASKFILE_DIR}}/ts-build-fresh.cjs" "{{.DEFT_ROOT}}"; then
             exit 0
           fi
-          node -e "
-            const {execFileSync}=require('child_process');
-            const fs=require('fs');
-            const root=process.argv[1];
-            const script='build';
-            const pkgPath=root+'/package.json';
-            const pkg=JSON.parse(fs.readFileSync(pkgPath,'utf8'));
-            // Cross-platform probe (#2415): do NOT use Unix `sh -c 'command -v'` —
-            // Windows native Task often has no `sh` on PATH, so Corepack.cmd was
-            // invisible after #2411. Prefer a direct spawn (POSIX / real binaries);
-            // fall back to shell:true so PATHEXT resolves .cmd/.exe on win32.
-            // windowsHide (#2563): CREATE_NO_WINDOW so Cursor Task shells do not
-            // flood visible cmd.exe/conhost windows on every probe/build.
-            const spawnOpts=(extra)=>({stdio:'ignore',windowsHide:true,...extra});
-            const hasCmd=(name)=>{
-              try{
-                execFileSync(name,['--version'],spawnOpts());
-                return true;
-              }catch{
-                try{
-                  execFileSync(name,['--version'],spawnOpts({shell:true}));
-                  return true;
-                }catch{
-                  return false;
-                }
-              }
-            };
-            const run=(cmd,args)=>{
-              execFileSync(cmd,args,{cwd:root,stdio:'inherit',shell:true,windowsHide:true});
-            };
-            const markWarm=()=>{
-              try{
-                const dist=root+'/packages/cli/dist';
-                fs.mkdirSync(dist,{recursive:true});
-                fs.writeFileSync(dist+'/.deft-ts-build-stamp',new Date().toISOString());
-              }catch{}
-            };
-            const trySteps=(steps)=>{
-              for(const [cmd,args] of steps){
-                try{
-                  run(cmd,args);
-                  markWarm();
-                  process.exit(0);
-                }catch{
-                  // fall through to Corepack / next resolver
-                }
-              }
-            };
-            const envPm=String(process.env.DEFT_PACKAGE_MANAGER||'').trim().toLowerCase();
-            if(envPm==='npm'){
-              run('npm',['run',script]);
-              markWarm();
-              process.exit(0);
-            }
-            const pin=String(pkg.packageManager||'').trim();
-            const match=pin.match(/^pnpm@(.+)$/);
-            const steps=[];
-            if(hasCmd('pnpm')) steps.push(['pnpm',['run',script]]);
-            if(hasCmd('corepack')&&match) steps.push(['corepack',['pnpm@'+match[1],'run',script]]);
-            if(hasCmd('corepack')) steps.push(['corepack',['pnpm','run',script]]);
-            trySteps(steps);
-            console.error('deft: neither pnpm nor corepack is available to run \"'+script+'\".');
-            if(pin){
-              console.error('  Enable Corepack for the pinned manager: corepack enable && corepack prepare '+pin+' --activate');
-            }else{
-              console.error('  Install pnpm or enable Corepack (see package.json#packageManager).');
-            }
-            console.error('  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.');
-            process.exit(127);
-          " "{{.DEFT_ROOT}}"
+          node "{{.TASKFILE_DIR}}/engine-pm-run.cjs" "{{.DEFT_ROOT}}" build --mark-warm
         fi
 
   invoke: