@deftai/directive-core 0.76.0 → 0.78.0

package/dist/release/version.js

@@ -5,6 +5,12 @@ const PRE_KIND_MAP = {
     rc: "rc",
 };
 const NON_PUBLISHABLE_KINDS = new Set(["test"]);
+const PRERELEASE_RANK = {
+    alpha: 0,
+    beta: 1,
+    rc: 2,
+    "": 3,
+};
 export class NonPublishableVersionError extends Error {
     constructor(message) {
         super(message);
@@ -71,4 +77,40 @@ export function isPublishable(version) {
         return false;
     }
 }
+function publishableVersionSortKey(version) {
+    const candidate = version.trim();
+    const match = PEP440_TAG_RE.exec(candidate);
+    if (match?.groups === undefined) {
+        throw new Error(`Cannot compare '${candidate}': expected ` + "[v]X.Y.Z or [v]X.Y.Z-(rc|alpha|beta).N");
+    }
+    const kind = match.groups.kind ?? "";
+    if (NON_PUBLISHABLE_KINDS.has(kind)) {
+        throw new NonPublishableVersionError(`Version '${candidate}' carries non-publishable pre-release tag '${kind}'.${match.groups.num}.`);
+    }
+    const rank = PRERELEASE_RANK[kind];
+    if (rank === undefined) {
+        throw new Error(`Cannot compare '${candidate}': unsupported pre-release kind '${kind}'.`);
+    }
+    return [
+        Number(match.groups.major),
+        Number(match.groups.minor),
+        Number(match.groups.patch),
+        rank,
+        Number(match.groups.num ?? 0),
+    ];
+}
+/** Compare two publishable Deft release versions using stable/prerelease ordering. */
+export function comparePublishableVersions(left, right) {
+    const leftKey = publishableVersionSortKey(left);
+    const rightKey = publishableVersionSortKey(right);
+    for (let index = 0; index < leftKey.length; index += 1) {
+        const leftPart = leftKey[index] ?? 0;
+        const rightPart = rightKey[index] ?? 0;
+        if (leftPart < rightPart)
+            return -1;
+        if (leftPart > rightPart)
+            return 1;
+    }
+    return 0;
+}
 //# sourceMappingURL=version.js.map

package/dist/release-e2e/greenfield-python-free-smoke-cli.js

@@ -2,9 +2,48 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { rehearseGreenfieldPythonFreeSmoke } from "./greenfield-python-free-smoke.js";
+const DEFAULT_OVERALL_TIMEOUT_MS = 900_000;
+function parseOverallTimeoutMs() {
+    const raw = process.env.DEFT_GREENFIELD_OVERALL_TIMEOUT_MS?.trim();
+    if (!raw) {
+        return DEFAULT_OVERALL_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_OVERALL_TIMEOUT_MS;
+}
+function logProgress(message) {
+    process.stderr.write(`${message}\n`);
+}
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
 const skipWorkspacePrep = process.env.DEFT_GREENFIELD_SKIP_PREP === "1";
-const [ok, reason] = rehearseGreenfieldPythonFreeSmoke(repoRoot, {}, { skipWorkspacePrep });
+const overallTimeoutMs = parseOverallTimeoutMs();
+let lastProgress = "starting";
+let finished = false;
+const onProgress = (message) => {
+    lastProgress = message;
+    logProgress(message);
+};
+const failClosed = (reason, exitCode = 1) => {
+    if (finished) {
+        return;
+    }
+    finished = true;
+    process.stdout.write(`${reason}\n`);
+    process.exit(exitCode);
+};
+const overallTimer = setTimeout(() => {
+    failClosed(`greenfield-python-free-smoke FAIL: overall budget exceeded (${overallTimeoutMs}ms); last step: ${lastProgress}`, 1);
+}, overallTimeoutMs);
+process.on("SIGTERM", () => {
+    failClosed(`greenfield-python-free-smoke FAIL: received SIGTERM during "${lastProgress}" — likely runner kill after hang (root cause: spawn pipe deadlock fixed in engine-invoke #2554)`, 143);
+});
+process.on("SIGINT", () => {
+    failClosed(`greenfield-python-free-smoke FAIL: interrupted during "${lastProgress}"`, 130);
+});
+logProgress(`greenfield-python-free-smoke: starting (overall budget ${overallTimeoutMs}ms, skipPrep=${skipWorkspacePrep})`);
+const [ok, reason] = rehearseGreenfieldPythonFreeSmoke(repoRoot, {}, { skipWorkspacePrep, onProgress });
+clearTimeout(overallTimer);
+finished = true;
 process.stdout.write(`${reason}\n`);
 process.exit(ok ? 0 : 1);
 //# sourceMappingURL=greenfield-python-free-smoke-cli.js.map

package/dist/release-e2e/greenfield-python-free-smoke.d.ts

@@ -3,6 +3,8 @@ export interface GreenfieldSmokeSeams extends E2ESeams {
 }
 export interface GreenfieldSmokeOptions {
     skipWorkspacePrep?: boolean;
+    /** Emits step progress immediately (stderr in CLI) so CI logs are never empty on hang (#2554). */
+    onProgress?: (message: string) => void;
 }
 /**
  * Greenfield npm smoke (#2022 Phase 3): pack/install directive, run init +

package/dist/release-e2e/greenfield-python-free-smoke.js

@@ -46,12 +46,23 @@ function packTarballPath(packDir, pkgDir) {
     const scoped = manifest.name.replaceAll("@", "").replaceAll("/", "-");
     return join(packDir, `${scoped}-${manifest.version}.tgz`);
 }
-function runStep(spawn, label, cmd, args, options = {}) {
+function runStep(spawn, label, cmd, args, options = {}, onProgress) {
+    onProgress?.(`greenfield smoke: ${label} — starting`);
+    const startedMs = Date.now();
     const result = spawn(cmd, args, options);
+    const elapsedMs = Date.now() - startedMs;
     if (result.status !== 0) {
         const detail = (result.stderr || result.stdout || "").trim();
-        return [false, `${label} failed (exit ${result.status}): ${detail.slice(-800)}`];
+        const timeoutHint = options.timeoutMs !== undefined && result.status === 128
+            ? `; subprocess killed after ${elapsedMs}ms (spawn budget ${options.timeoutMs}ms — likely hang or timeout)`
+            : "";
+        onProgress?.(`greenfield smoke: ${label} — failed (exit ${result.status}) after ${elapsedMs}ms`);
+        return [
+            false,
+            `${label} failed (exit ${result.status})${timeoutHint}: ${detail.slice(-800) || "(no captured output)"}`,
+        ];
     }
+    onProgress?.(`greenfield smoke: ${label} — OK (${elapsedMs}ms)`);
     return [true, `${label} OK`];
 }
 /**
@@ -77,6 +88,8 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
         return [false, "greenfield-python-free-smoke FAIL: pnpm command prefix is empty"];
     }
     const spawn = seams.spawnText ?? spawnText;
+    const onProgress = options.onProgress;
+    onProgress?.("greenfield smoke: workspace prep starting");
     const work = mkdtempSync(join(tmpdir(), "deft-greenfield-smoke-"));
     const packDir = join(work, "packs");
     mkdirSync(packDir, { recursive: true });
@@ -98,24 +111,28 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
                 cwd: repoRoot,
                 env: envBase,
                 timeoutMs: 120_000,
-            });
+            }, onProgress);
             if (!ok)
                 return [false, `greenfield smoke: ${reason}`];
             [ok, reason] = runStep(spawn, "pnpm build", pnpmCmd, [...pnpmArgs, "run", "build"], {
                 cwd: repoRoot,
                 env: envBase,
                 timeoutMs: 120_000,
-            });
+            }, onProgress);
             if (!ok)
                 return [false, `greenfield smoke: ${reason}`];
         }
+        else {
+            onProgress?.("greenfield smoke: skipping workspace prep (DEFT_GREENFIELD_SKIP_PREP=1)");
+        }
+        onProgress?.("greenfield smoke: aligning npm package versions");
         [ok, reason] = alignNpmPackageVersions(repoRoot, SMOKE_VERSION);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
         const packed = [];
         for (const pkg of NPM_PUBLISH_PACKAGES) {
             const pkgDir = join(repoRoot, "packages", pkg);
-            [ok, reason] = runStep(spawn, `npm pack packages/${pkg}`, npm, ["pack", "--pack-destination", packDir], { cwd: pkgDir, env: envBase, timeoutMs: 120_000 });
+            [ok, reason] = runStep(spawn, `npm pack packages/${pkg}`, npm, ["pack", "--pack-destination", packDir], { cwd: pkgDir, env: envBase, timeoutMs: 120_000 }, onProgress);
             if (!ok)
                 return [false, `greenfield smoke: ${reason}`];
             const tgz = packTarballPath(packDir, pkgDir);
@@ -127,7 +144,7 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
         [ok, reason] = runStep(spawn, "npm install -g", npm, ["install", "-g", ...packed], {
             env: envBase,
             timeoutMs: 120_000,
-        });
+        }, onProgress);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
         const deft = join(npmPrefix, "bin", "deft");
@@ -139,9 +156,10 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
             cwd: work,
             env: pyFree,
             timeoutMs: 120_000,
-        });
+        }, onProgress);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
+        onProgress?.("greenfield smoke: seeding fixture PROJECT-DEFINITION");
         seedMinimalProjectDefinition(projectDir);
         const depositDir = join(projectDir, ".deft", "core");
         const artifacts = collectPythonArtifacts(depositDir);
@@ -159,13 +177,15 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
             PATH: `${join(npmPrefix, "bin")}:${pyFree.PATH ?? ""}`,
             DEFT_SESSION_RITUAL_SKIP: "1",
         };
+        onProgress?.("greenfield smoke: running consumer task deft:check (engine-invoke path)");
         [ok, reason] = runStep(spawn, "task deft:check", task, ["deft:check"], {
             cwd: projectDir,
             env: checkEnv,
             timeoutMs: 180_000,
-        });
+        }, onProgress);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
+        onProgress?.("greenfield smoke: all steps passed");
         return [
             true,
             "greenfield-python-free-smoke: directive init + task deft:check passed with Python absent from PATH",

package/dist/release-e2e/npm-ops.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { defaultWhich, spawnText } from "../release/spawn.js";
+import { defaultWhich } from "../release/spawn.js";
+import { resolveCommandOnPath, spawnCommandText } from "../verify-env/command-spawn.js";
 import { MODULE_NOT_FOUND_MARKERS, NPM_BUILD_TIMEOUT_SECONDS, NPM_E2E_REHEARSAL_TAG, NPM_INSTALL_RUN_TIMEOUT_SECONDS, NPM_INSTALL_TIMEOUT_SECONDS, NPM_PACK_TIMEOUT_SECONDS, NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS, NPM_PUBLISH_PACKAGES, } from "./constants.js";
 /**
  * npm publish dry-run rehearsal (#1910) -- the TS port of the
@@ -18,19 +19,32 @@ function resolveWhich(seams) {
  * available.
  */
 export function resolvePnpm(seams = {}) {
-    const which = resolveWhich(seams);
-    const pnpm = which("pnpm");
+    // Injected which seam wins for unit tests; production uses PATHEXT-aware PATH scan
+    // so `where pnpm` extensionless shims do not ENOENT under spawnSync (#2548 / #2467).
+    if (seams.which ?? seams.whichGh) {
+        const which = resolveWhich(seams);
+        const pnpm = which("pnpm");
+        if (pnpm) {
+            return [pnpm];
+        }
+        const corepack = which("corepack");
+        if (corepack) {
+            return [corepack, "pnpm"];
+        }
+        return null;
+    }
+    const pnpm = resolveCommandOnPath("pnpm");
     if (pnpm) {
         return [pnpm];
     }
-    const corepack = which("corepack");
+    const corepack = resolveCommandOnPath("corepack");
     if (corepack) {
         return [corepack, "pnpm"];
     }
     return null;
 }
 function runNpmStep(cmd, cwd, env, label, timeoutSeconds, seams) {
-    const spawn = seams.spawnText ?? spawnText;
+    const spawn = seams.spawnText ?? spawnCommandText;
     const head = cmd[0] ?? "";
     const result = spawn(head, cmd.slice(1), {
         cwd,
@@ -217,7 +231,7 @@ export function rehearseNpmInstallAndRun(cloneDir, version, seams = {}, options
     [ok, reason] = runNpmStep(installArgs, consumerDir, env, "npm install packed tarballs", NPM_INSTALL_RUN_TIMEOUT_SECONDS, seams);
     if (!ok)
         return [false, reason];
-    const spawn = seams.spawnText ?? spawnText;
+    const spawn = seams.spawnText ?? spawnCommandText;
     const cliBin = join(consumerDir, "node_modules", "@deftai", "directive", "dist", "bin.js");
     // Liveness probe (#2010): `--version` loads the cli + core engine via
     // engineInfo(), exercising the cross-package import path that #1993 broke,

package/dist/session/verify-session-ritual.d.ts

@@ -29,6 +29,22 @@ export interface VerifySessionRitualOptions {
     readonly envPosture?: string | undefined;
     readonly handoffText?: string | null;
 }
+export interface InspectSessionRitualOptions {
+    readonly tier?: "quick" | "gated";
+    readonly now?: Date;
+    readonly runGit?: GitRunner;
+    readonly posture?: DirectivePosture;
+    readonly envPosture?: string | undefined;
+    readonly handoffText?: string | null;
+}
+/**
+ * Read-only ritual-state inspection for host hooks.
+ *
+ * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
+ * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
+ * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ */
+export declare function inspectSessionRitual(projectRoot: string, options?: InspectSessionRitualOptions): VerifyResult;
 export declare function verifySessionRitual(projectRoot: string, options?: VerifySessionRitualOptions): VerifyResult;
 export declare function emitVerifyJson(result: VerifyResult): string;
 export declare function emitBypassWarning(result: VerifyResult): string;

package/dist/session/verify-session-ritual.js

@@ -105,6 +105,69 @@ function evaluateLoadedState(projectRoot, state, input) {
     }
     return [0, `OK session ritual ${input.tier} tier is fresh.`];
 }
+/**
+ * Read-only ritual-state inspection for host hooks.
+ *
+ * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
+ * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
+ * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ */
+export function inspectSessionRitual(projectRoot, options = {}) {
+    const tier = options.tier ?? "quick";
+    const posture = resolveSessionPosture({
+        explicitPosture: options.posture ?? null,
+        envPosture: options.envPosture ?? process.env.DEFT_SESSION_POSTURE,
+        handoffText: options.handoffText,
+        tier,
+    });
+    const ritualStateRequired = posture === "mutation" && !ritualStateIsPostureAuthority();
+    const statePath = ritualStatePath(projectRoot);
+    if (posture === "read-only") {
+        return {
+            code: 0,
+            message: readOnlyPostureMessage(tier),
+            tier,
+            statePath,
+            bypassed: false,
+            wouldFailCode: null,
+            posture,
+            ritualStateRequired: false,
+        };
+    }
+    const missingStateFile = !existsSync(statePath);
+    const [state, err] = readRitualState(projectRoot);
+    if (state === null) {
+        const code = missingStateFile ? 1 : 2;
+        const startCommand = formatFrameworkCommand(["session:start"]);
+        return {
+            code,
+            message: code === 1
+                ? `${err}. Run \`${startCommand}\` before implementation dispatch.`
+                : (err ?? "ritual state invalid"),
+            tier,
+            statePath,
+            bypassed: false,
+            wouldFailCode: null,
+            posture,
+            ritualStateRequired,
+        };
+    }
+    const [code, message] = evaluateLoadedState(projectRoot, state, {
+        tier,
+        now: options.now ?? new Date(),
+        runGit: options.runGit,
+    });
+    return {
+        code,
+        message,
+        tier,
+        statePath,
+        bypassed: false,
+        wouldFailCode: null,
+        posture,
+        ritualStateRequired,
+    };
+}
 export function verifySessionRitual(projectRoot, options = {}) {
     const tier = options.tier ?? "quick";
     const posture = resolveSessionPosture({

package/dist/triage/help/registry-data.d.ts

@@ -364,6 +364,17 @@ export declare const registryData: {
             readonly see_also: readonly ["task eval:run", "task eval:report", "#1703"];
             readonly placeholder: false;
         };
+        readonly "task eval:triggers": {
+            readonly name: "task eval:triggers";
+            readonly summary: "Trigger routing coverage for Skills Index rules";
+            readonly refs: "(#1586)";
+            readonly description: "Offline skill-pi-trigger-eval compatible routing check: grades evals/trigger-cases.jsonl against REFERENCES.md Skills Index triggers (should-fire / should-not-fire per skill).";
+            readonly usage: "task eval:triggers [-- --json] [--project-root PATH]";
+            readonly flags: readonly [readonly ["--json", "(off)", "Emit the TriggerEvalReport JSON."], readonly ["--project-root PATH", "(cwd)", "Project root override (Taskfile threads USER_WORKING_DIR)."]];
+            readonly examples: readonly ["task eval:triggers", "task eval:triggers -- --json"];
+            readonly see_also: readonly ["task eval:health", "task verify:eval-triggers-relocation", "#1862"];
+            readonly placeholder: false;
+        };
         readonly "task eval:run": {
             readonly name: "task eval:run";
             readonly summary: "Tier 2 golden corpus eval for a model";
@@ -508,7 +519,7 @@ export declare const registryData: {
             readonly placeholder: false;
         };
     };
-    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:run", "task eval:report"]]];
+    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"]]];
     readonly categoriesScope: readonly [readonly ["Promote / demote", readonly ["task scope:promote", "task scope:demote"]], readonly ["Activate / complete", readonly ["task scope:activate", "task scope:complete", "task scope:fail", "task scope:cancel", "task scope:block", "task scope:unblock"]], readonly ["Reversibility", readonly ["task scope:undo", "task scope:restore"]], readonly ["Decomposition", readonly ["task scope:decompose"]]];
     readonly scriptSubcommandMap: {
         readonly triage_actions: {

package/dist/triage/help/registry-data.js

@@ -548,6 +548,24 @@ export const registryData = {
             see_also: ["task eval:run", "task eval:report", "#1703"],
             placeholder: false,
         },
+        "task eval:triggers": {
+            name: "task eval:triggers",
+            summary: "Trigger routing coverage for Skills Index rules",
+            refs: "(#1586)",
+            description: "Offline skill-pi-trigger-eval compatible routing check: grades evals/trigger-cases.jsonl against REFERENCES.md Skills Index triggers (should-fire / should-not-fire per skill).",
+            usage: "task eval:triggers [-- --json] [--project-root PATH]",
+            flags: [
+                ["--json", "(off)", "Emit the TriggerEvalReport JSON."],
+                [
+                    "--project-root PATH",
+                    "(cwd)",
+                    "Project root override (Taskfile threads USER_WORKING_DIR).",
+                ],
+            ],
+            examples: ["task eval:triggers", "task eval:triggers -- --json"],
+            see_also: ["task eval:health", "task verify:eval-triggers-relocation", "#1862"],
+            placeholder: false,
+        },
         "task eval:run": {
             name: "task eval:run",
             summary: "Tier 2 golden corpus eval for a model",
@@ -829,7 +847,10 @@ export const registryData = {
                 "task triage:metrics",
             ],
         ],
-        ["Framework eval (#1703)", ["task eval:health", "task eval:run", "task eval:report"]],
+        [
+            "Framework eval (#1703)",
+            ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"],
+        ],
     ],
     categoriesScope: [
         ["Promote / demote", ["task scope:promote", "task scope:demote"]],

package/dist/verify-env/agent-hooks.d.ts

@@ -0,0 +1,11 @@
+import { type AgentHookInspection } from "../init-deposit/agent-hooks.js";
+import type { OutputStream } from "./verify-hooks-installed.js";
+export interface AgentHookHealthResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly registrations: readonly AgentHookInspection[];
+}
+/** Read-only P0 agent-host registration health, independent of git hooks. */
+export declare function evaluateAgentHooks(projectRoot: string): AgentHookHealthResult;
+//# sourceMappingURL=agent-hooks.d.ts.map

package/dist/verify-env/agent-hooks.js

@@ -0,0 +1,45 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { inspectAgentHookDeposit } from "../init-deposit/agent-hooks.js";
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Read-only P0 agent-host registration health, independent of git hooks. */
+export function evaluateAgentHooks(projectRoot) {
+    const root = resolve(projectRoot);
+    if (!isDirectory(root)) {
+        return {
+            code: 2,
+            message: `❌ deft agent hooks: project root ${root} does not exist (config error).`,
+            stream: "stderr",
+            registrations: [],
+        };
+    }
+    const registrations = inspectAgentHookDeposit(root);
+    const unhealthy = registrations.filter((entry) => entry.status !== "healthy");
+    if (unhealthy.length > 0) {
+        return {
+            code: 1,
+            message: "❌ deft agent hooks NON-FUNCTIONAL:\n" +
+                unhealthy
+                    .map((entry) => `  - ${entry.host}: ${entry.status} at ${entry.path} — ${entry.detail}`)
+                    .join("\n") +
+                "\n  Recovery: run `deft update` (or `directive init`) to refresh project hooks.",
+            stream: "stderr",
+            registrations,
+        };
+    }
+    return {
+        code: 0,
+        message: "✓ deft agent hooks installed and functional for Claude, Grok, Cursor " +
+            "(SessionStart + PreToolUse direct-write tools only; shell/MCP policy is deferred).",
+        stream: "stdout",
+        registrations,
+    };
+}
+//# sourceMappingURL=agent-hooks.js.map

package/dist/verify-env/command-spawn.d.ts

@@ -0,0 +1,29 @@
+import type { SpawnResult } from "../release/types.js";
+export interface ResolveCommandOnPathOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly exists?: (path: string) => boolean;
+}
+/** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
+export declare function shouldUseShellForCommand(command: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Quote a win32 executable path for `shell: true` spawns when it contains spaces.
+ * Without quoting, cmd.exe treats `C:\Program` as the command (#2555).
+ */
+export declare function quoteWin32CommandForShell(command: string, platform?: NodeJS.Platform): string;
+/**
+ * Resolve an executable on PATH with PATHEXT / Path awareness (#2467 / #2548).
+ * Mirrors ts-check-lane `resolvePnpm` and verify-tools `defaultProbe`.
+ */
+export declare function resolveCommandOnPath(command: string, options?: ResolveCommandOnPathOptions): string | null;
+export interface SpawnCommandTextOptions {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+}
+/**
+ * spawnSync wrapper that applies win32 PATHEXT / shell rules (#2467 / #2548).
+ * Retries with `shell: true` on win32 ENOENT (npm global `.cmd` shims).
+ */
+export declare function spawnCommandText(cmd: string, args: readonly string[], options?: SpawnCommandTextOptions): SpawnResult;
+//# sourceMappingURL=command-spawn.d.ts.map

package/dist/verify-env/command-spawn.js

@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
+/** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
+export function shouldUseShellForCommand(command, platform = process.platform) {
+    return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
+/**
+ * Quote a win32 executable path for `shell: true` spawns when it contains spaces.
+ * Without quoting, cmd.exe treats `C:\Program` as the command (#2555).
+ */
+export function quoteWin32CommandForShell(command, platform = process.platform) {
+    if (platform !== "win32" || !command.includes(" ")) {
+        return command;
+    }
+    if ((command.startsWith('"') && command.endsWith('"')) ||
+        (command.startsWith("'") && command.endsWith("'"))) {
+        return command;
+    }
+    return `"${command}"`;
+}
+/**
+ * Resolve an executable on PATH with PATHEXT / Path awareness (#2467 / #2548).
+ * Mirrors ts-check-lane `resolvePnpm` and verify-tools `defaultProbe`.
+ */
+export function resolveCommandOnPath(command, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const exists = options.exists ?? existsSync;
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (pathValue === "") {
+        return null;
+    }
+    const isWindows = platform === "win32";
+    const exts = isWindows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    const sep = isWindows ? ";" : ":";
+    const joinPath = isWindows ? win32.join : posix.join;
+    for (const dir of pathValue.split(sep)) {
+        if (dir === "")
+            continue;
+        for (const ext of exts) {
+            const candidate = joinPath(dir, `${command}${ext}`);
+            if (exists(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * spawnSync wrapper that applies win32 PATHEXT / shell rules (#2467 / #2548).
+ * Retries with `shell: true` on win32 ENOENT (npm global `.cmd` shims).
+ */
+export function spawnCommandText(cmd, args, options = {}) {
+    const trySpawn = (shell) => {
+        const spawnCmd = shell && process.platform === "win32" ? quoteWin32CommandForShell(cmd) : cmd;
+        return spawnSync(spawnCmd, [...args], {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            encoding: "utf8",
+            timeout: options.timeoutMs,
+            maxBuffer: SUBPROCESS_MAX_BUFFER,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell,
+            // CREATE_NO_WINDOW on win32; harmless elsewhere (#2563).
+            windowsHide: true,
+        });
+    };
+    let result = trySpawn(shouldUseShellForCommand(cmd));
+    const spawnErr = result.error;
+    if (spawnErr?.code === "ENOENT" && process.platform === "win32") {
+        result = trySpawn(true);
+    }
+    let status = result.status;
+    let stderr = typeof result.stderr === "string" ? result.stderr : "";
+    if (status === null) {
+        if (result.signal !== null && result.signal !== undefined) {
+            status = 128;
+        }
+        else if (result.error) {
+            status = 2;
+            if (stderr.trim().length === 0) {
+                stderr = result.error.message;
+            }
+        }
+        else {
+            status = 0;
+        }
+    }
+    return {
+        status,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr,
+    };
+}
+//# sourceMappingURL=command-spawn.js.map

package/dist/verify-env/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./agent-hooks.js";
+export * from "./command-spawn.js";
 export * from "./node-runtime.js";
 export * from "./toolchain-check.js";
 export * from "./verify-hooks-installed.js";

package/dist/verify-env/index.js

@@ -1,3 +1,5 @@
+export * from "./agent-hooks.js";
+export * from "./command-spawn.js";
 export * from "./node-runtime.js";
 export * from "./toolchain-check.js";
 export * from "./verify-hooks-installed.js";