agentplane 0.3.22 → 0.3.24

package/dist/commands/task/migrate-doc.readme.js

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { atomicWriteFile } from "@agentplaneorg/core/fs";
+import { ensureDocSections, extractTaskDoc, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskDocFromSections, renderTaskReadme, setMarkdownSection, taskDocToSectionMap, } from "@agentplaneorg/core/tasks";
+import { decodeEscapedTaskTextNewlines, extractDocSection, extractTaskObservationSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, } from "./shared/docs.js";
+import { defaultTaskDocV3 } from "./doc-template.js";
+const V3_CANONICAL_ORDER = [
+    "Summary",
+    "Scope",
+    "Plan",
+    "Verify Steps",
+    "Verification",
+    "Rollback Plan",
+    "Findings",
+];
+const HUMAN_TEXT_SECTIONS = new Set(["summary", "context", "scope", "plan", "findings", "notes"]);
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeRevision(value) {
+    return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : null;
+}
+function normalizeCanonicalSections(value) {
+    if (!isRecord(value))
+        return null;
+    const out = {};
+    for (const [title, text] of Object.entries(value)) {
+        const normalizedTitle = title.trim();
+        if (!normalizedTitle || typeof text !== "string")
+            continue;
+        out[normalizedTitle] = text.replaceAll("\r\n", "\n").trimEnd();
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
+function normalizeSectionKey(section) {
+    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function parseMarkdownSections(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            if (current) {
+                current.text = current.text.trimEnd();
+                sections.push(current);
+            }
+            current = { title: (match[1] ?? "").trim(), text: "" };
+            continue;
+        }
+        if (current) {
+            current.text = current.text.length > 0 ? `${current.text}\n${line}` : line;
+        }
+    }
+    if (current) {
+        current.text = current.text.trimEnd();
+        sections.push(current);
+    }
+    return sections;
+}
+function renderMarkdownSections(sections) {
+    return sections
+        .map((section) => {
+        const text = section.text.trimEnd();
+        return text ? `## ${section.title}\n\n${text}` : `## ${section.title}\n`;
+    })
+        .join("\n\n")
+        .trimEnd();
+}
+function normalizeLiteralNewlinesInHumanSection(title, text) {
+    if (!HUMAN_TEXT_SECTIONS.has(normalizeSectionKey(title)))
+        return text.trimEnd();
+    return decodeEscapedTaskTextNewlines(text).trimEnd();
+}
+function firstSectionText(sections, title) {
+    const target = normalizeSectionKey(title);
+    return sections.find((section) => normalizeSectionKey(section.title) === target)?.text ?? null;
+}
+function mergeObservationText(doc, version) {
+    const preferred = extractTaskObservationSection(doc, version)?.trim() ?? "";
+    const notes = extractDocSection(doc, "Notes")?.trim() ?? "";
+    const findings = extractDocSection(doc, "Findings")?.trim() ?? "";
+    const out = [];
+    for (const candidate of [preferred, findings, notes]) {
+        if (!candidate)
+            continue;
+        if (out.includes(candidate))
+            continue;
+        out.push(candidate);
+    }
+    return out.join("\n\n").trim();
+}
+function migrateDocToV3(opts) {
+    const currentSections = parseMarkdownSections(opts.doc);
+    const defaultSections = parseMarkdownSections(defaultTaskDocV3({ title: opts.title, description: opts.description }));
+    const emitted = new Set();
+    const nextSections = [];
+    const observationText = mergeObservationText(opts.doc, 2);
+    for (const title of V3_CANONICAL_ORDER) {
+        const key = normalizeSectionKey(title);
+        const currentText = firstSectionText(currentSections, title);
+        const defaultText = firstSectionText(defaultSections, title) ?? "";
+        let nextText = currentText ?? defaultText;
+        if (title === "Verification") {
+            nextText = normalizeVerificationSectionLayout(currentText ?? defaultText, 3);
+        }
+        if (title === "Findings") {
+            nextText = observationText || defaultText;
+        }
+        if (nextText === null)
+            continue;
+        nextText = normalizeLiteralNewlinesInHumanSection(title, nextText);
+        nextSections.push({ title, text: nextText.trimEnd() });
+        emitted.add(key);
+        if (title === "Findings")
+            emitted.add("notes");
+    }
+    for (const section of currentSections) {
+        const key = normalizeSectionKey(section.title);
+        if (emitted.has(key))
+            continue;
+        nextSections.push({ title: section.title, text: section.text.trimEnd() });
+        emitted.add(key);
+    }
+    return renderMarkdownSections(nextSections);
+}
+function ensurePlanApprovalFrontmatter(frontmatter) {
+    const raw = frontmatter.plan_approval;
+    if (isRecord(raw) && typeof raw.state === "string")
+        return;
+    frontmatter.plan_approval = {
+        state: "pending",
+        updated_at: null,
+        updated_by: null,
+        note: null,
+    };
+}
+function ensureVerificationFrontmatter(frontmatter) {
+    const raw = frontmatter.verification;
+    if (isRecord(raw) && typeof raw.state === "string")
+        return;
+    frontmatter.verification = {
+        state: "pending",
+        updated_at: null,
+        updated_by: null,
+        note: null,
+    };
+}
+const DATE_ONLY_ON_RE = /\bon (\d{4}-\d{2}-\d{2})(?!T)\b/g;
+function isIsoTimestamp(value) {
+    if (!value.includes("T") || !value.endsWith("Z"))
+        return false;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms);
+}
+function normalizeNoteTimestamp(opts) {
+    if (!isIsoTimestamp(opts.updatedAt))
+        return opts.note;
+    const updatedDate = opts.updatedAt.slice(0, 10);
+    return opts.note.replaceAll(DATE_ONLY_ON_RE, (match, date) => {
+        if (date !== updatedDate)
+            return match;
+        return `on ${opts.updatedAt}`;
+    });
+}
+function normalizeFrontmatterNoteTimestamps(frontmatter) {
+    const plan = frontmatter.plan_approval;
+    if (isRecord(plan) && typeof plan.note === "string" && typeof plan.updated_at === "string") {
+        plan.note = normalizeNoteTimestamp({ note: plan.note, updatedAt: plan.updated_at });
+    }
+    const verification = frontmatter.verification;
+    if (isRecord(verification) &&
+        typeof verification.note === "string" &&
+        typeof verification.updated_at === "string") {
+        verification.note = normalizeNoteTimestamp({
+            note: verification.note,
+            updatedAt: verification.updated_at,
+        });
+    }
+}
+export async function migrateTaskReadmeDoc(opts) {
+    const originalRaw = await readFile(opts.readmePath, "utf8");
+    const original = originalRaw.endsWith("\n") ? originalRaw : `${originalRaw}\n`;
+    const parsed = parseTaskReadme(original);
+    const frontmatter = { ...parsed.frontmatter };
+    ensurePlanApprovalFrontmatter(frontmatter);
+    ensureVerificationFrontmatter(frontmatter);
+    normalizeFrontmatterNoteTimestamps(frontmatter);
+    const canonicalSections = normalizeCanonicalSections(frontmatter.sections);
+    const required = opts.config.tasks.doc.required_sections;
+    const extracted = extractTaskDoc(parsed.body);
+    const baseDoc = canonicalSections === null
+        ? extracted || parsed.body
+        : renderTaskDocFromSections(canonicalSections);
+    let nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
+    const docVersion = normalizeTaskDocVersion(frontmatter.doc_version);
+    if (docVersion === 2) {
+        frontmatter.doc_version = 3;
+        nextDoc = migrateDocToV3({
+            title: typeof frontmatter.title === "string" ? frontmatter.title : "",
+            description: typeof frontmatter.description === "string" ? frontmatter.description : "",
+            doc: nextDoc,
+        });
+    }
+    else {
+        const verificationSection = extractDocSection(nextDoc, "Verification");
+        const normalizedVerification = normalizeVerificationSectionLayout(verificationSection, docVersion);
+        nextDoc = setMarkdownSection(nextDoc, "Verification", normalizedVerification);
+        for (const sectionTitle of ["Summary", "Context", "Scope", "Plan", "Findings", "Notes"]) {
+            const sectionText = extractDocSection(nextDoc, sectionTitle);
+            if (sectionText == null)
+                continue;
+            nextDoc = setMarkdownSection(nextDoc, sectionTitle, normalizeLiteralNewlinesInHumanSection(sectionTitle, sectionText));
+        }
+    }
+    const nextBody = extracted ? mergeTaskDoc(parsed.body, nextDoc) : nextDoc;
+    frontmatter.sections = taskDocToSectionMap(nextDoc);
+    frontmatter.revision = normalizeRevision(frontmatter.revision) ?? 1;
+    const rendered = renderTaskReadme(frontmatter, nextBody);
+    const next = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
+    if (next === original)
+        return { changed: false };
+    await atomicWriteFile(opts.readmePath, next, "utf8");
+    return { changed: true };
+}

package/dist/runtime/prompt-modules/index.d.ts

@@ -0,0 +1,3 @@
+export { PROMPT_MODULE_CONTRACT_SCHEMA_VERSION, type PromptModule, type PromptModuleAddress, type PromptModuleConflictPolicy, type PromptModuleContentKind, type PromptModuleContractSchemaVersion, type PromptModuleDependency, type PromptModuleGraph, type PromptModuleGraphNode, type PromptModuleLoadCondition, type PromptModuleMergeMode, type PromptModuleMergePolicy, type PromptModuleMutability, type PromptModuleNamespace, type PromptModuleOwner, type PromptModuleProvenance, type PromptModuleReference, type PromptModuleSlot, type PromptModuleSourceKind, type PromptModuleSurface, type PromptModuleTarget, } from "./model.js";
+export type { PromptModuleAddMutation, PromptModuleBindMutation, PromptModuleBinding, PromptModuleBindingKind, PromptModuleDisableMutation, PromptModuleMutation, PromptModuleMutationBase, PromptModuleMutationSet, PromptModuleMutationSource, PromptModuleMutationWhen, PromptModulePatchMutation, PromptModuleReplaceMutation, PromptModuleSelector, PromptModuleStructuredPatch, PromptModuleValidator, PromptModuleValidatorMutation, PromptModuleValidatorPhase, } from "./mutations.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/prompt-modules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/prompt-modules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qCAAqC,EACrC,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,iCAAiC,EACtC,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC"}

package/dist/runtime/prompt-modules/index.js

@@ -0,0 +1 @@
+export { PROMPT_MODULE_CONTRACT_SCHEMA_VERSION, } from "./model.js";

package/dist/runtime/prompt-modules/model.d.ts

@@ -0,0 +1,89 @@
+export declare const PROMPT_MODULE_CONTRACT_SCHEMA_VERSION: 1;
+export type PromptModuleContractSchemaVersion = typeof PROMPT_MODULE_CONTRACT_SCHEMA_VERSION;
+export type PromptModuleNamespace = "framework" | "project" | "runtime" | `recipe.${string}`;
+export type PromptModuleSurface = "gateway" | "policy" | "agent_profile" | "runner" | "validator" | "template";
+export type PromptModuleTarget = "AGENTS.md" | "CLAUDE.md" | ".agentplane/policy" | ".agentplane/agents" | "runner.bundle" | "recipe.manifest" | "generated.artifact";
+export type PromptModuleSlot = "frontmatter" | "purpose" | "startup" | "commands" | "load_rules" | "source_of_truth" | "hard_constraint" | "body" | "example" | "identity" | "inputs" | "outputs" | "permissions" | "workflow" | "cli_notes" | "context" | "schema" | "check" | "partial" | "file";
+export type PromptModuleAddress = {
+    /**
+     * Canonical stable address, for example
+     * `framework/gateway/AGENTS.md/load_rules/base`.
+     */
+    value: string;
+    namespace: PromptModuleNamespace;
+    surface: PromptModuleSurface;
+    target: PromptModuleTarget;
+    slot: PromptModuleSlot;
+    name: string;
+};
+export type PromptModuleOwner = {
+    kind: "framework";
+    package_name: "agentplane";
+    version?: string;
+} | {
+    kind: "project";
+    project_root?: string;
+} | {
+    kind: "recipe";
+    recipe_id: string;
+    version?: string;
+} | {
+    kind: "runtime";
+    adapter_id?: string;
+};
+export type PromptModuleContentKind = "markdown" | "json" | "text" | "typescript" | "command";
+export type PromptModuleMutability = "locked" | "replaceable" | "extendable" | "append_only";
+export type PromptModuleMergeMode = "pick_one" | "replace" | "prepend" | "append" | "merge_object" | "union_by_id";
+export type PromptModuleConflictPolicy = "error" | "highest_precedence" | "last_writer_wins" | "keep_all";
+export type PromptModuleMergePolicy = {
+    mode: PromptModuleMergeMode;
+    conflict: PromptModuleConflictPolicy;
+    precedence?: number;
+};
+export type PromptModuleLoadCondition = {
+    workflow_modes?: ("direct" | "branch_pr")[];
+    policy_gateways?: ("codex" | "claude")[];
+    roles?: string[];
+    commands?: string[];
+    task_tags_any?: string[];
+    repo_types?: string[];
+    recipe_ids?: string[];
+};
+export type PromptModuleSourceKind = "framework_builtin" | "project_file" | "recipe_asset" | "generated" | "runtime";
+export type PromptModuleProvenance = {
+    source_kind: PromptModuleSourceKind;
+    source_ref: string;
+    recipe_id?: string;
+    recipe_version?: string;
+    generated_by?: string;
+    content_hash?: string;
+};
+export type PromptModuleDependency = {
+    address: string;
+    required: boolean;
+};
+export type PromptModule<TContent = string | Record<string, unknown>> = {
+    schema_version: PromptModuleContractSchemaVersion;
+    address: PromptModuleAddress;
+    owner: PromptModuleOwner;
+    title: string;
+    summary?: string;
+    content_kind: PromptModuleContentKind;
+    content: TContent;
+    mutability: PromptModuleMutability;
+    merge: PromptModuleMergePolicy;
+    load?: PromptModuleLoadCondition;
+    dependencies?: PromptModuleDependency[];
+    provenance: PromptModuleProvenance;
+};
+export type PromptModuleReference = Pick<PromptModule, "address" | "owner" | "provenance">;
+export type PromptModuleGraphNode = {
+    module: PromptModule;
+    replaces?: string[];
+    extends?: string[];
+};
+export type PromptModuleGraph = {
+    schema_version: PromptModuleContractSchemaVersion;
+    nodes: PromptModuleGraphNode[];
+};
+//# sourceMappingURL=model.d.ts.map

package/dist/runtime/prompt-modules/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/runtime/prompt-modules/model.ts"],"names":[],"mappings":"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"}

package/dist/runtime/prompt-modules/model.js

@@ -0,0 +1 @@
+export const PROMPT_MODULE_CONTRACT_SCHEMA_VERSION = 1;

package/dist/runtime/prompt-modules/mutations.d.ts

@@ -0,0 +1,103 @@
+import type { PromptModule, PromptModuleAddress, PromptModuleDependency, PromptModuleLoadCondition, PromptModuleMergePolicy, PromptModuleMutability, PromptModuleOwner, PromptModuleProvenance, PromptModuleSlot, PromptModuleSurface, PromptModuleTarget } from "./model.js";
+export type PromptModuleSelector = {
+    address?: string;
+    namespace?: PromptModuleAddress["namespace"];
+    surface?: PromptModuleSurface;
+    target?: PromptModuleTarget;
+    slot?: PromptModuleSlot;
+    owner?: PromptModuleOwner["kind"];
+    recipe_id?: string;
+};
+export type PromptModuleMutationWhen = PromptModuleLoadCondition & {
+    module_present?: string[];
+    module_absent?: string[];
+};
+export type PromptModuleMutationSource = {
+    owner: PromptModuleOwner;
+    provenance: PromptModuleProvenance;
+};
+export type PromptModuleStructuredPatch<TContent = string | Record<string, unknown>> = {
+    title?: string;
+    summary?: string | null;
+    content?: TContent;
+    mutability?: PromptModuleMutability;
+    merge?: PromptModuleMergePolicy;
+    load?: PromptModuleLoadCondition | null;
+    dependencies?: PromptModuleDependency[] | null;
+    provenance?: PromptModuleProvenance;
+};
+export type PromptModuleBindingKind = "extends" | "replaces" | "requires" | "feeds" | "validates";
+export type PromptModuleBinding = {
+    id: string;
+    kind: PromptModuleBindingKind;
+    from: string;
+    to: string;
+    order?: number;
+    required?: boolean;
+    when?: PromptModuleMutationWhen;
+};
+export type PromptModuleValidatorPhase = "resolve" | "compile" | "emit" | "doctor";
+export type PromptModuleValidator = {
+    id: string;
+    phase: PromptModuleValidatorPhase;
+    kind: "required_module";
+    target: PromptModuleSelector;
+    required: true;
+    when?: PromptModuleMutationWhen;
+} | {
+    id: string;
+    phase: PromptModuleValidatorPhase;
+    kind: "forbidden_module";
+    target: PromptModuleSelector;
+    required: true;
+    when?: PromptModuleMutationWhen;
+} | {
+    id: string;
+    phase: PromptModuleValidatorPhase;
+    kind: "required_command";
+    command: string;
+    required: boolean;
+    when?: PromptModuleMutationWhen;
+};
+export type PromptModuleMutationBase = {
+    id: string;
+    source: PromptModuleMutationSource;
+    when?: PromptModuleMutationWhen;
+    reason?: string;
+};
+export type PromptModuleAddMutation = PromptModuleMutationBase & {
+    op: "add_module";
+    module: PromptModule;
+};
+export type PromptModuleReplaceMutation = PromptModuleMutationBase & {
+    op: "replace_module";
+    target: PromptModuleSelector;
+    module: PromptModule;
+};
+export type PromptModulePatchMutation<TContent = string | Record<string, unknown>> = PromptModuleMutationBase & {
+    op: "patch_module";
+    target: PromptModuleSelector;
+    patch: PromptModuleStructuredPatch<TContent>;
+};
+export type PromptModuleDisableMutation = PromptModuleMutationBase & {
+    op: "disable_module";
+    target: PromptModuleSelector;
+};
+export type PromptModuleBindMutation = PromptModuleMutationBase & {
+    op: "bind_module";
+    binding: PromptModuleBinding;
+};
+export type PromptModuleValidatorMutation = PromptModuleMutationBase & ({
+    op: "add_validator";
+    validator: PromptModuleValidator;
+} | {
+    op: "disable_validator";
+    validator_id: string;
+});
+export type PromptModuleMutation = PromptModuleAddMutation | PromptModuleReplaceMutation | PromptModulePatchMutation | PromptModuleDisableMutation | PromptModuleBindMutation | PromptModuleValidatorMutation;
+export type PromptModuleMutationSet = {
+    schema_version: 1;
+    recipe_id?: string;
+    mutations: PromptModuleMutation[];
+};
+//# sourceMappingURL=mutations.d.ts.map

package/dist/runtime/prompt-modules/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/runtime/prompt-modules/mutations.ts"],"names":[],"mappings":"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"}

package/dist/runtime/prompt-modules/mutations.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/runtime-env.d.ts

@@ -0,0 +1,3 @@
+export declare function withPreferredRuntimePath(baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function resolvePreferredNodeExecutable(baseEnv?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=runtime-env.d.ts.map

package/dist/shared/runtime-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-env.d.ts","sourceRoot":"","sources":["../../src/shared/runtime-env.ts"],"names":[],"mappings":"AAUA,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,UAAU,CA0BnB;AA8BD,wBAAgB,8BAA8B,CAAC,OAAO,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAe/F"}

package/dist/shared/runtime-env.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function pushUnique(entries, value) {
+    const trimmed = value.trim();
+    if (!trimmed || entries.includes(trimmed))
+        return;
+    entries.push(trimmed);
+}
+export function withPreferredRuntimePath(baseEnv = process.env) {
+    const env = { ...baseEnv };
+    const pathEntries = String(baseEnv.PATH ?? "")
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const preferredEntries = [];
+    pushUnique(preferredEntries, path.dirname(resolvePreferredNodeExecutable(baseEnv)));
+    const bunInstallDir = String(baseEnv.BUN_INSTALL ?? "").trim();
+    if (bunInstallDir) {
+        pushUnique(preferredEntries, path.join(bunInstallDir, "bin"));
+    }
+    const homeDir = String(baseEnv.HOME ?? os.homedir() ?? "").trim();
+    if (homeDir) {
+        pushUnique(preferredEntries, path.join(homeDir, ".bun", "bin"));
+    }
+    for (const entry of pathEntries) {
+        pushUnique(preferredEntries, entry);
+    }
+    env.PATH = preferredEntries.join(path.delimiter);
+    return env;
+}
+function isExecutableFile(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function readLatestNvmNodeBin(homeDir) {
+    const versionsDir = path.join(homeDir, ".nvm", "versions", "node");
+    let entries = [];
+    try {
+        entries = fs.readdirSync(versionsDir);
+    }
+    catch {
+        return null;
+    }
+    const latest = entries
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .toSorted()
+        .at(-1);
+    if (!latest)
+        return null;
+    const candidate = path.join(versionsDir, latest, "bin", "node");
+    return isExecutableFile(candidate) ? candidate : null;
+}
+export function resolvePreferredNodeExecutable(baseEnv = process.env) {
+    const homeDir = String(baseEnv.HOME ?? os.homedir() ?? "").trim();
+    const candidates = [
+        path.join(String(baseEnv.NVM_BIN ?? "").trim(), "node"),
+        path.join(String(baseEnv.VOLTA_HOME ?? "").trim(), "bin", "node"),
+        homeDir ? readLatestNvmNodeBin(homeDir) : null,
+        process.execPath,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim() && isExecutableFile(candidate)) {
+            return candidate;
+        }
+    }
+    return process.execPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -56,8 +56,8 @@
     "prepublishOnly": "node ../../scripts/enforce-github-publish.mjs && npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.3.22",
-    "@agentplaneorg/recipes": "0.3.22",
+    "@agentplaneorg/core": "0.3.24",
+    "@agentplaneorg/recipes": "0.3.24",
     "@clack/prompts": "^1.2.0",
     "yauzl": "^2.10.0",
     "zod": "^3",