@deftai/directive-core 0.76.0 → 0.77.0

package/dist/index.js

@@ -25,6 +25,7 @@ export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
+export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
 export * as platform from "./platform/index.js";

package/dist/metrics/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./resolve-metrics-home.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.js

@@ -0,0 +1,2 @@
+export * from "./resolve-metrics-home.js";
+//# sourceMappingURL=index.js.map

package/dist/metrics/resolve-metrics-home.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared metrics home resolver (#2545).
+ *
+ * Helped (value / CRUD) and health (eval:health) append logs are machine-local
+ * telemetry — not project source. They resolve outside the git worktree via an
+ * explicit ladder shared with USER.md platform discovery (#2271 / #2544):
+ *
+ *   1. `DEFT_METRICS_HOME` or `DEFT_EVAL_HOME` — explicit override (CI / headless)
+ *   2. `<projectRoot>/.deft/metrics/` — workspace-local opt-in when
+ *      `DEFT_METRICS_PROJECT_LOCAL=1`
+ *   3. Platform user-data (`%APPDATA%\deft\metrics` / `~/.config/deft/metrics`)
+ *   4. Soft-disable when the resolved root is not writable — never fall back to
+ *      `xbrief/.eval/results/`.
+ */
+export declare const METRICS_DISABLED_DIAGNOSTIC = "metrics persistence disabled";
+export declare const DEFT_METRICS_HOME_ENV = "DEFT_METRICS_HOME";
+export declare const DEFT_EVAL_HOME_ENV = "DEFT_EVAL_HOME";
+export declare const DEFT_METRICS_PROJECT_LOCAL_ENV = "DEFT_METRICS_PROJECT_LOCAL";
+export declare const PROJECT_LOCAL_METRICS_DIR = ".deft/metrics";
+export declare const HELPED_METRICS_FILENAME = "crud-metrics.jsonl";
+export declare const HEALTH_METRICS_FILENAME = "health-history.jsonl";
+export type MetricsHomeRung = "env-override" | "project-local" | "platform-user-data" | "disabled";
+export interface ResolveMetricsHomeResult {
+    /** Absolute metrics root, or null when persistence is disabled. */
+    readonly root: string | null;
+    readonly rung: MetricsHomeRung;
+    /** False when no writable metrics root could be resolved. */
+    readonly enabled: boolean;
+    readonly diagnostic: string;
+}
+export interface ResolveMetricsHomeOptions {
+    readonly projectRoot?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly homeDir?: string;
+    /** Writable probe. Defaults to mkdir + W_OK access check. */
+    readonly probeWritable?: (path: string) => boolean;
+}
+/**
+ * Resolve the platform user-data metrics directory (`%APPDATA%\deft\metrics` /
+ * `~/.config/deft/metrics`).
+ */
+export declare function platformMetricsDir(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, homeDir: string): string;
+/** Resolve the metrics home root across the first-hit-wins ladder (#2545). */
+export declare function resolveMetricsHome(options?: ResolveMetricsHomeOptions): ResolveMetricsHomeResult;
+/** Absolute path to the helped / value metrics ledger (`helped/crud-metrics.jsonl`). */
+export declare function helpedMetricsHistoryPath(projectRoot: string, options?: ResolveMetricsHomeOptions): string | null;
+/** Absolute path to the health metrics ledger (`health/health-history.jsonl`). */
+export declare function healthMetricsHistoryPath(projectRoot: string, options?: ResolveMetricsHomeOptions): string | null;
+//# sourceMappingURL=resolve-metrics-home.d.ts.map

package/dist/metrics/resolve-metrics-home.js

@@ -0,0 +1,125 @@
+/**
+ * Shared metrics home resolver (#2545).
+ *
+ * Helped (value / CRUD) and health (eval:health) append logs are machine-local
+ * telemetry — not project source. They resolve outside the git worktree via an
+ * explicit ladder shared with USER.md platform discovery (#2271 / #2544):
+ *
+ *   1. `DEFT_METRICS_HOME` or `DEFT_EVAL_HOME` — explicit override (CI / headless)
+ *   2. `<projectRoot>/.deft/metrics/` — workspace-local opt-in when
+ *      `DEFT_METRICS_PROJECT_LOCAL=1`
+ *   3. Platform user-data (`%APPDATA%\deft\metrics` / `~/.config/deft/metrics`)
+ *   4. Soft-disable when the resolved root is not writable — never fall back to
+ *      `xbrief/.eval/results/`.
+ */
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { platformUserConfigDir } from "../user-config/resolve-user-md.js";
+export const METRICS_DISABLED_DIAGNOSTIC = "metrics persistence disabled";
+export const DEFT_METRICS_HOME_ENV = "DEFT_METRICS_HOME";
+export const DEFT_EVAL_HOME_ENV = "DEFT_EVAL_HOME";
+export const DEFT_METRICS_PROJECT_LOCAL_ENV = "DEFT_METRICS_PROJECT_LOCAL";
+export const PROJECT_LOCAL_METRICS_DIR = ".deft/metrics";
+export const HELPED_METRICS_FILENAME = "crud-metrics.jsonl";
+export const HEALTH_METRICS_FILENAME = "health-history.jsonl";
+function defaultProbeWritable(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+        accessSync(path, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function metricsEnvOverride(env) {
+    const primary = env[DEFT_METRICS_HOME_ENV]?.trim();
+    if (primary) {
+        return primary;
+    }
+    const legacy = env[DEFT_EVAL_HOME_ENV]?.trim();
+    return legacy || null;
+}
+/**
+ * Resolve the platform user-data metrics directory (`%APPDATA%\deft\metrics` /
+ * `~/.config/deft/metrics`).
+ */
+export function platformMetricsDir(platform, env, homeDir) {
+    return join(platformUserConfigDir(platform, env, homeDir), "metrics");
+}
+/** Resolve the metrics home root across the first-hit-wins ladder (#2545). */
+export function resolveMetricsHome(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? homedir();
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const probeWritable = options.probeWritable ?? defaultProbeWritable;
+    const override = metricsEnvOverride(env);
+    if (override) {
+        const root = resolve(override);
+        if (probeWritable(root)) {
+            return {
+                root,
+                rung: "env-override",
+                enabled: true,
+                diagnostic: `metrics home resolved from ${DEFT_METRICS_HOME_ENV}/${DEFT_EVAL_HOME_ENV}: ${root}`,
+            };
+        }
+        return {
+            root: null,
+            rung: "disabled",
+            enabled: false,
+            diagnostic: `${METRICS_DISABLED_DIAGNOSTIC} (${DEFT_METRICS_HOME_ENV} not writable: ${root})`,
+        };
+    }
+    if (env[DEFT_METRICS_PROJECT_LOCAL_ENV] === "1") {
+        const root = resolve(join(projectRoot, PROJECT_LOCAL_METRICS_DIR));
+        if (probeWritable(root)) {
+            return {
+                root,
+                rung: "project-local",
+                enabled: true,
+                diagnostic: `metrics home resolved from workspace-local opt-in: ${root}`,
+            };
+        }
+        return {
+            root: null,
+            rung: "disabled",
+            enabled: false,
+            diagnostic: `${METRICS_DISABLED_DIAGNOSTIC} (workspace-local metrics dir not writable: ${root})`,
+        };
+    }
+    const root = platformMetricsDir(platform, env, homeDir);
+    if (probeWritable(root)) {
+        return {
+            root,
+            rung: "platform-user-data",
+            enabled: true,
+            diagnostic: `metrics home resolved from platform user-data: ${root}`,
+        };
+    }
+    return {
+        root: null,
+        rung: "disabled",
+        enabled: false,
+        diagnostic: `${METRICS_DISABLED_DIAGNOSTIC} (platform user-data not writable: ${root})`,
+    };
+}
+/** Absolute path to the helped / value metrics ledger (`helped/crud-metrics.jsonl`). */
+export function helpedMetricsHistoryPath(projectRoot, options = {}) {
+    const home = resolveMetricsHome({ ...options, projectRoot });
+    if (!home.enabled || home.root === null) {
+        return null;
+    }
+    return join(home.root, "helped", HELPED_METRICS_FILENAME);
+}
+/** Absolute path to the health metrics ledger (`health/health-history.jsonl`). */
+export function healthMetricsHistoryPath(projectRoot, options = {}) {
+    const home = resolveMetricsHome({ ...options, projectRoot });
+    if (!home.enabled || home.root === null) {
+        return null;
+    }
+    return join(home.root, "health", HEALTH_METRICS_FILENAME);
+}
+//# sourceMappingURL=resolve-metrics-home.js.map

package/dist/plan-sequence/index.d.ts

@@ -0,0 +1,3 @@
+export { clearPlanSequence, planSequencePath, readPlanSequence, writePlanSequence, } from "./store.js";
+export { advancePlanSequence, type ContinuationResolution, createPlanSequence, EXHAUSTED_FAIL_CLOSED_MESSAGE, EXPLICIT_QUEUE_PHRASES, isExplicitQueueAsk, isPlanFirstPhrase, PLAN_FIRST_PHRASES, PLAN_SEQUENCE_CONTRACT, PLAN_SEQUENCE_FILENAME, type PlanSequence, type PlanSequenceEntry, type PlanSequenceKind, type PlanSequenceVerifyInput, type PlanSequenceVerifyResult, type PlanTargetKind, parsePlanSequence, resolveContinuation, verifyPlanTarget, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plan-sequence/index.js

@@ -0,0 +1,3 @@
+export { clearPlanSequence, planSequencePath, readPlanSequence, writePlanSequence, } from "./store.js";
+export { advancePlanSequence, createPlanSequence, EXHAUSTED_FAIL_CLOSED_MESSAGE, EXPLICIT_QUEUE_PHRASES, isExplicitQueueAsk, isPlanFirstPhrase, PLAN_FIRST_PHRASES, PLAN_SEQUENCE_CONTRACT, PLAN_SEQUENCE_FILENAME, parsePlanSequence, resolveContinuation, verifyPlanTarget, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/plan-sequence/store.d.ts

@@ -0,0 +1,6 @@
+import { type PlanSequence } from "./types.js";
+export declare function planSequencePath(projectRoot: string): string;
+export declare function readPlanSequence(projectRoot: string): PlanSequence | null;
+export declare function writePlanSequence(projectRoot: string, sequence: PlanSequence): string;
+export declare function clearPlanSequence(projectRoot: string): boolean;
+//# sourceMappingURL=store.d.ts.map

package/dist/plan-sequence/store.js

@@ -0,0 +1,29 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { PLAN_SEQUENCE_FILENAME, parsePlanSequence } from "./types.js";
+export function planSequencePath(projectRoot) {
+    return join(projectRoot, ".deft", PLAN_SEQUENCE_FILENAME);
+}
+export function readPlanSequence(projectRoot) {
+    const path = planSequencePath(projectRoot);
+    if (!existsSync(path)) {
+        return null;
+    }
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return parsePlanSequence(raw);
+}
+export function writePlanSequence(projectRoot, sequence) {
+    const path = planSequencePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(sequence, null, 2)}\n`, "utf8");
+    return path;
+}
+export function clearPlanSequence(projectRoot) {
+    const path = planSequencePath(projectRoot);
+    if (!existsSync(path)) {
+        return false;
+    }
+    unlinkSync(path);
+    return true;
+}
+//# sourceMappingURL=store.js.map

package/dist/plan-sequence/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Ordered-plan continuation boundary (#2402).
+ *
+ * Continuation words ("next", "resume", "proceed") advance only within the
+ * narrowest operator-approved sequence. Exhaustion fails closed. Separate from
+ * triage queue continuationNumbers / continuationOrder.
+ */
+export declare const PLAN_SEQUENCE_FILENAME = "plan-sequence.json";
+export declare const PLAN_SEQUENCE_CONTRACT: "ordered-plan-continuation";
+export type PlanSequenceKind = "delivery" | "review" | "implementation" | "swarm" | "triage" | "cohort" | "checklist";
+export type PlanTargetKind = "pr" | "issue" | "story" | "task" | "phase" | "checklist" | "review";
+export interface PlanSequenceEntry {
+    readonly id: string;
+    readonly kind: PlanTargetKind;
+    readonly title?: string;
+    readonly issue?: number;
+    readonly status?: "pending" | "completed" | "skipped";
+}
+export interface PlanSequence {
+    readonly sequence_id: string;
+    readonly sequence_kind: PlanSequenceKind;
+    readonly entries: readonly PlanSequenceEntry[];
+    readonly current_index: number;
+    readonly batching_allowed: boolean;
+    /** Default false — exhausted sequences require fresh operator approval. */
+    readonly continuation_past_final: boolean;
+    readonly exhausted: boolean;
+    readonly authorized_by: string;
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+export interface PlanSequenceVerifyInput {
+    readonly targetKind: PlanTargetKind;
+    readonly target: string;
+}
+export type PlanSequenceVerifyResult = {
+    readonly ok: true;
+    readonly entry: PlanSequenceEntry;
+    readonly index: number;
+} | {
+    readonly ok: false;
+    readonly code: "missing" | "exhausted" | "mismatch" | "kind-mismatch";
+    readonly message: string;
+};
+export type ContinuationResolution = {
+    readonly action: "advance";
+    readonly entry: PlanSequenceEntry;
+    readonly index: number;
+} | {
+    readonly action: "queue";
+    readonly reason: "no-active-sequence" | "explicit-queue-override" | "not-plan-first-phrase";
+} | {
+    readonly action: "ask";
+    readonly reason: "exhausted" | "ambiguous-sequences";
+    readonly message: string;
+};
+/** Phrases that are explicit queue/backlog selection even mid-plan. */
+export declare const EXPLICIT_QUEUE_PHRASES: readonly ["what's the queue", "whats the queue", "what is the queue", "build a cohort", "triage queue", "show the queue", "queue-driven", "from the backlog"];
+/** Bare continuation / selection phrases that bind to ordered-plan when active. */
+export declare const PLAN_FIRST_PHRASES: readonly ["what's next", "whats next", "what next", "what should i work on next", "next task", "next pr", "next issue", "next story", "move on", "proceed", "resume", "next"];
+export declare const EXHAUSTED_FAIL_CLOSED_MESSAGE = "I have completed the approved sequence. Starting another item would exceed the current authorization. Please name the next target or approve queue-driven selection.";
+export declare function isExplicitQueueAsk(text: string): boolean;
+export declare function isPlanFirstPhrase(text: string): boolean;
+/** Resolve how continuation/selection language should be handled. */
+export declare function resolveContinuation(text: string, sequence: PlanSequence | null): ContinuationResolution;
+export declare function verifyPlanTarget(sequence: PlanSequence | null, input: PlanSequenceVerifyInput): PlanSequenceVerifyResult;
+export declare function createPlanSequence(input: {
+    sequence_id: string;
+    sequence_kind: PlanSequenceKind;
+    entries: readonly PlanSequenceEntry[];
+    authorized_by: string;
+    batching_allowed?: boolean;
+    continuation_past_final?: boolean;
+    now?: string;
+}): PlanSequence;
+/** Mark current entry completed and advance index; may set exhausted. */
+export declare function advancePlanSequence(sequence: PlanSequence, now?: string): PlanSequence;
+export declare function parsePlanSequence(raw: unknown): PlanSequence;
+//# sourceMappingURL=types.d.ts.map

package/dist/plan-sequence/types.js

@@ -0,0 +1,220 @@
+/**
+ * Ordered-plan continuation boundary (#2402).
+ *
+ * Continuation words ("next", "resume", "proceed") advance only within the
+ * narrowest operator-approved sequence. Exhaustion fails closed. Separate from
+ * triage queue continuationNumbers / continuationOrder.
+ */
+export const PLAN_SEQUENCE_FILENAME = "plan-sequence.json";
+export const PLAN_SEQUENCE_CONTRACT = "ordered-plan-continuation";
+/** Phrases that are explicit queue/backlog selection even mid-plan. */
+export const EXPLICIT_QUEUE_PHRASES = [
+    "what's the queue",
+    "whats the queue",
+    "what is the queue",
+    "build a cohort",
+    "triage queue",
+    "show the queue",
+    "queue-driven",
+    "from the backlog",
+];
+/** Bare continuation / selection phrases that bind to ordered-plan when active. */
+export const PLAN_FIRST_PHRASES = [
+    "what's next",
+    "whats next",
+    "what next",
+    "what should i work on next",
+    "next task",
+    "next pr",
+    "next issue",
+    "next story",
+    "move on",
+    "proceed",
+    "resume",
+    "next",
+];
+export const EXHAUSTED_FAIL_CLOSED_MESSAGE = "I have completed the approved sequence. Starting another item would exceed the current authorization. Please name the next target or approve queue-driven selection.";
+function normalizeTarget(raw) {
+    return raw.trim().toLowerCase().replace(/^#/, "");
+}
+function entryMatches(entry, targetKind, target) {
+    if (entry.kind !== targetKind) {
+        return false;
+    }
+    const needle = normalizeTarget(target);
+    if (normalizeTarget(entry.id) === needle) {
+        return true;
+    }
+    if (entry.issue !== undefined && String(entry.issue) === needle) {
+        return true;
+    }
+    if (entry.title !== undefined && normalizeTarget(entry.title) === needle) {
+        return true;
+    }
+    return false;
+}
+export function isExplicitQueueAsk(text) {
+    const lower = text.toLowerCase();
+    return EXPLICIT_QUEUE_PHRASES.some((p) => lower.includes(p));
+}
+export function isPlanFirstPhrase(text) {
+    const lower = text.toLowerCase();
+    return PLAN_FIRST_PHRASES.some((p) => lower.includes(p));
+}
+/** Resolve how continuation/selection language should be handled. */
+export function resolveContinuation(text, sequence) {
+    // Explicit backlog/cohort asks always select from the queue, even mid-plan.
+    if (isExplicitQueueAsk(text)) {
+        return { action: "queue", reason: "explicit-queue-override" };
+    }
+    // No active sequence → queue (same as today's #1149 path).
+    if (sequence === null) {
+        return { action: "queue", reason: "no-active-sequence" };
+    }
+    // Active sequence + plan-first / continuation phrase → bind to current entry.
+    if (!isPlanFirstPhrase(text)) {
+        return { action: "queue", reason: "not-plan-first-phrase" };
+    }
+    if (sequence.exhausted || sequence.current_index >= sequence.entries.length) {
+        if (sequence.continuation_past_final) {
+            return { action: "queue", reason: "no-active-sequence" };
+        }
+        return {
+            action: "ask",
+            reason: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    const index = sequence.current_index;
+    const entry = sequence.entries[index];
+    if (entry === undefined) {
+        return {
+            action: "ask",
+            reason: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    return { action: "advance", entry, index };
+}
+export function verifyPlanTarget(sequence, input) {
+    if (sequence === null) {
+        return {
+            ok: false,
+            code: "missing",
+            message: "No active ordered-plan sequence. Set one with plan-sequence:set, or obtain explicit operator approval for this target.",
+        };
+    }
+    if (sequence.exhausted || sequence.current_index >= sequence.entries.length) {
+        return {
+            ok: false,
+            code: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    const index = sequence.current_index;
+    const entry = sequence.entries[index];
+    if (entry === undefined) {
+        return {
+            ok: false,
+            code: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    if (entry.kind !== input.targetKind) {
+        return {
+            ok: false,
+            code: "kind-mismatch",
+            message: `Current ordered-plan entry is kind=${entry.kind} id=${entry.id}; requested kind=${input.targetKind} target=${input.target}.`,
+        };
+    }
+    if (!entryMatches(entry, input.targetKind, input.target)) {
+        return {
+            ok: false,
+            code: "mismatch",
+            message: `Target ${input.targetKind}:${input.target} is not the current ordered-plan entry (${entry.kind}:${entry.id}).`,
+        };
+    }
+    return { ok: true, entry, index };
+}
+export function createPlanSequence(input) {
+    if (input.entries.length === 0) {
+        throw new Error("plan-sequence: entries must be non-empty");
+    }
+    const now = input.now ?? new Date().toISOString();
+    return {
+        sequence_id: input.sequence_id,
+        sequence_kind: input.sequence_kind,
+        entries: input.entries.map((e) => ({ ...e, status: e.status ?? "pending" })),
+        current_index: 0,
+        batching_allowed: input.batching_allowed ?? false,
+        continuation_past_final: input.continuation_past_final ?? false,
+        exhausted: false,
+        authorized_by: input.authorized_by,
+        created_at: now,
+        updated_at: now,
+    };
+}
+/** Mark current entry completed and advance index; may set exhausted. */
+export function advancePlanSequence(sequence, now = new Date().toISOString()) {
+    if (sequence.exhausted || sequence.current_index >= sequence.entries.length) {
+        return { ...sequence, exhausted: true, updated_at: now };
+    }
+    const entries = sequence.entries.map((e, i) => i === sequence.current_index ? { ...e, status: "completed" } : e);
+    const nextIndex = sequence.current_index + 1;
+    const exhausted = nextIndex >= entries.length;
+    return {
+        ...sequence,
+        entries,
+        current_index: exhausted ? sequence.current_index : nextIndex,
+        exhausted,
+        updated_at: now,
+    };
+}
+export function parsePlanSequence(raw) {
+    if (raw === null || typeof raw !== "object") {
+        throw new Error("plan-sequence: expected object");
+    }
+    const obj = raw;
+    if (typeof obj.sequence_id !== "string" || obj.sequence_id.length === 0) {
+        throw new Error("plan-sequence: sequence_id required");
+    }
+    if (typeof obj.sequence_kind !== "string") {
+        throw new Error("plan-sequence: sequence_kind required");
+    }
+    if (!Array.isArray(obj.entries) || obj.entries.length === 0) {
+        throw new Error("plan-sequence: entries must be a non-empty array");
+    }
+    const entries = obj.entries.map((item, i) => {
+        if (item === null || typeof item !== "object") {
+            throw new Error(`plan-sequence: entries[${i}] must be an object`);
+        }
+        const e = item;
+        if (typeof e.id !== "string" || typeof e.kind !== "string") {
+            throw new Error(`plan-sequence: entries[${i}] requires id and kind`);
+        }
+        return {
+            id: e.id,
+            kind: e.kind,
+            title: typeof e.title === "string" ? e.title : undefined,
+            issue: typeof e.issue === "number" ? e.issue : undefined,
+            status: e.status === "completed" || e.status === "skipped" || e.status === "pending"
+                ? e.status
+                : "pending",
+        };
+    });
+    const current_index = typeof obj.current_index === "number" ? obj.current_index : 0;
+    const exhausted = obj.exhausted === true || current_index >= entries.length;
+    return {
+        sequence_id: obj.sequence_id,
+        sequence_kind: obj.sequence_kind,
+        entries,
+        current_index,
+        batching_allowed: obj.batching_allowed === true,
+        continuation_past_final: obj.continuation_past_final === true,
+        exhausted,
+        authorized_by: typeof obj.authorized_by === "string" ? obj.authorized_by : "",
+        created_at: typeof obj.created_at === "string" ? obj.created_at : new Date().toISOString(),
+        updated_at: typeof obj.updated_at === "string" ? obj.updated_at : new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/release/version.d.ts

@@ -8,4 +8,6 @@ export declare function isPrereleaseTag(version: string): boolean;
 /** Normalize a semver-shaped release tag to a PEP 440 version string (#771). */
 export declare function toPep440(version: string): string;
 export declare function isPublishable(version: string): boolean;
+/** Compare two publishable Deft release versions using stable/prerelease ordering. */
+export declare function comparePublishableVersions(left: string, right: string): -1 | 0 | 1;
 //# sourceMappingURL=version.d.ts.map

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/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,