akm-cli 0.9.2-alpha.3 → 0.9.2-alpha.5

package/dist/integrations/session-logs/pre-filter.js

@@ -90,12 +90,155 @@ function classifyEvent(event, akmReadOnlyOps, maxLen) {
     }
     return { keep: true, event, truncated: false };
 }
+/**
+ * A parent-side `<task-notification>` event, as Claude Code writes it into a
+ * session's own transcript: a `role: "user"` event whose text is (or wraps)
+ * `<task-notification>...<task-id>ID</task-id>...<result>TEXT</result>...</task-notification>`.
+ * Matched on the tags themselves (not a dedicated field) because
+ * {@link SessionEvent} carries no structural provenance beyond `text`/`role`/
+ * `filePath` — the same constraint #830 (subagent provenance) worked within.
+ */
+const TASK_NOTIFICATION_RE = /<task-notification>[\s\S]*<\/task-notification>/;
+const TASK_ID_RE = /<task-id>([^<]+)<\/task-id>/;
+const RESULT_RE = /<result>([\s\S]*)<\/result>/;
+const SUMMARY_RE = /<summary>([^<]*)<\/summary>/;
+/** Claude Code's own `<summary>` phrasing for a finished agent: `Agent "<description>" finished`. */
+const AGENT_SUMMARY_DESCRIPTION_RE = /^Agent "(.*)" finished$/;
+/** Provenance {@link subagentProvenance} stamps on every folded subagent event; stripped before comparison. */
+const PROVENANCE_PREFIX_RE = /^\[subagent:[^\]]*\][^\n]*\n/;
+/** Claude Code's own agentId file naming: `<...>/subagents/<...>agent-<agentId>.jsonl`. */
+const SUBAGENT_FILEPATH_RE = /agent-([^/\\]+?)\.jsonl$/;
+/** Dice (bigram) similarity at/above this counts as "the same content" (#839). */
+const DEDUPE_SIMILARITY_THRESHOLD = 0.9;
+/** A handful of named-entity decodes — enough for what Claude Code escapes when it wraps `<result>` text in XML. */
+function decodeXmlEntities(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/** Sørensen–Dice coefficient over character bigrams — a cheap, symmetric textual-overlap measure. */
+function diceSimilarity(a, b) {
+    if (a.length < 2 || b.length < 2)
+        return a === b ? 1 : 0;
+    const bigrams = (s) => {
+        const counts = new Map();
+        for (let i = 0; i < s.length - 1; i++) {
+            const bg = s.slice(i, i + 2);
+            counts.set(bg, (counts.get(bg) ?? 0) + 1);
+        }
+        return counts;
+    };
+    const bigramsA = bigrams(a);
+    const bigramsB = bigrams(b);
+    let intersection = 0;
+    let totalA = 0;
+    let totalB = 0;
+    for (const count of bigramsA.values())
+        totalA += count;
+    for (const count of bigramsB.values())
+        totalB += count;
+    for (const [bg, count] of bigramsA) {
+        const other = bigramsB.get(bg);
+        if (other)
+            intersection += Math.min(count, other);
+    }
+    return totalA + totalB === 0 ? 1 : (2 * intersection) / (totalA + totalB);
+}
+/**
+ * Stub out a parent's `<task-notification>` event when its `<result>` is a
+ * near-duplicate of a subagent transcript's own event that ALSO survived
+ * into this same kept set (#839).
+ *
+ * After #830 folds a session's subagent transcripts into its event stream,
+ * a completed subagent's report can appear twice: once as the subagent's own
+ * folded final event, once as the parent's `<task-notification>` record of
+ * that same call — the notification wraps the subagent's own text almost
+ * verbatim (Claude Code XML-escapes `<`/`>`/`&`/quotes in the `<result>`
+ * body, which {@link decodeXmlEntities} reverses before comparing). Direction
+ * is owner-decided (#839): drop the parent's copy, keep the subagent's
+ * original — the inverse was evaluated and rejected in #836 because some
+ * subagent transcripts consist ONLY of their terminal event, so dropping it
+ * would destroy the harvesting #830 added.
+ *
+ * **Runs on `kept` — the FINAL post-budget list — not the raw stream**, and
+ * only stubs a notification when a matching subagent event is ALSO present
+ * in that same `kept` list. This is required, not incidental: the recency-
+ * biased budget already evicts one side of most raw duplicate pairs before
+ * dedupe would matter (#840's design doc measured zero pairs where both
+ * copies reached the pre-dedupe prompt across four real sessions), and any
+ * future prompt-composition design that stops including subagent-origin
+ * events in the prompt at all (#840's recommended "harvest-without-
+ * prompting hybrid") makes the parent's `<task-notification>` the ONLY
+ * surviving trace of that delegated work. An unconditional raw-stream stub
+ * would delete that sole copy the moment the subagent's own event is absent
+ * for ANY reason — evicted by budget today, or never present by design
+ * tomorrow. Scoping to "both sides survived into the same kept set" makes
+ * this dedupe a no-op whenever there is only one copy left to dedupe
+ * against, which is exactly the case where deleting it would be a bug, not
+ * a fix.
+ *
+ * Matching is scoped by `<task-id>` (which is the subagent's agentId) to the
+ * SPECIFIC subagent transcript it names, via the `agent-<agentId>.jsonl`
+ * filename #830's folding already stamps onto every folded event's
+ * `filePath` — then requires the decoded `<result>` to be a near-duplicate
+ * (Dice similarity ≥ {@link DEDUPE_SIMILARITY_THRESHOLD}) of that subagent's
+ * text, not merely a same-agent match. This matters because a task-notification
+ * fires every time an agent stops (Claude Code's own note in the event: "the
+ * same task-id may notify more than once") — an EARLIER notification for a
+ * resumed agent can carry a genuinely different (intermediate) result that
+ * must NOT be stubbed just because the ids line up.
+ *
+ * The event is kept (not dropped) so event counts/timestamps stay stable and
+ * the parent's narrative — *why* it delegated — survives as a short stub:
+ * `[subagent <agentId> completed: <description>]`.
+ */
+function dedupeTaskNotifications(kept) {
+    // Index the KEPT subagent events by the agentId embedded in their
+    // transcript's filename, so a notification's <task-id> narrows the
+    // comparison to the ONE subagent it reports on — and so an agentId with no
+    // surviving event here means "nothing to dedupe against", not "assume it
+    // exists upstream".
+    const byAgentId = new Map();
+    for (const event of kept) {
+        const agentId = event.filePath?.match(SUBAGENT_FILEPATH_RE)?.[1];
+        if (!agentId)
+            continue;
+        const list = byAgentId.get(agentId);
+        if (list)
+            list.push(event);
+        else
+            byAgentId.set(agentId, [event]);
+    }
+    if (byAgentId.size === 0)
+        return kept; // no folded subagent survived the budget — nothing to dedupe
+    return kept.map((event) => {
+        if (event.role !== "user" || !TASK_NOTIFICATION_RE.test(event.text))
+            return event;
+        const taskId = event.text.match(TASK_ID_RE)?.[1];
+        const resultRaw = event.text.match(RESULT_RE)?.[1];
+        if (!taskId || !resultRaw)
+            return event; // no <result> (e.g. a background-command notification) — nothing to compare
+        const candidates = byAgentId.get(taskId);
+        if (!candidates || candidates.length === 0)
+            return event; // that subagent's own event didn't survive into this kept set
+        const decodedResult = decodeXmlEntities(resultRaw);
+        const isDuplicate = candidates.some((c) => diceSimilarity(decodedResult, c.text.replace(PROVENANCE_PREFIX_RE, "")) >= DEDUPE_SIMILARITY_THRESHOLD);
+        if (!isDuplicate)
+            return event;
+        const summary = event.text.match(SUMMARY_RE)?.[1]?.trim();
+        const description = (summary && (summary.match(AGENT_SUMMARY_DESCRIPTION_RE)?.[1] ?? summary)) || "completed";
+        return { ...event, text: `[subagent ${taskId} completed: ${description}]` };
+    });
+}
 export function preFilterSession(data, options = {}) {
     const akmReadOnlyOps = options.akmReadOnlyOps ?? DEFAULT_AKM_READONLY_OPS;
     const maxLen = options.maxEventTextLength ?? DEFAULT_MAX_EVENT_LENGTH;
     const maxTotalChars = options.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
     const droppedByRule = {};
-    const kept = [];
+    let kept = [];
     let truncatedCount = 0;
     const candidates = [];
     for (const event of data.events) {
@@ -138,6 +281,13 @@ export function preFilterSession(data, options = {}) {
         if (c.truncated)
             truncatedCount += 1;
     }
+    // Post-pass (#839): dedupe a task-notification against a subagent event
+    // ONLY when both survived into this exact kept set — see
+    // dedupeTaskNotifications's doc for why that scoping is required. Recompute
+    // totalChars afterward since stubbing can only shrink kept text, never move
+    // anything across the budget boundary already decided above.
+    kept = dedupeTaskNotifications(kept);
+    const finalTotalChars = kept.reduce((sum, e) => sum + e.text.length, 0);
     return {
         events: kept,
         stats: {
@@ -145,7 +295,7 @@ export function preFilterSession(data, options = {}) {
             outputCount: kept.length,
             droppedByRule,
             truncatedCount,
-            totalChars,
+            totalChars: finalTotalChars,
             budgetDroppedCount,
         },
     };

package/dist/output/shapes/passthrough.js

@@ -53,6 +53,7 @@ const PASSTHROUGH_COMMANDS = [
     "sync",
     "task-add",
     "task-doctor",
+    "task-explain",
     "task-history",
     "task-run",
     "task-sync",
@@ -61,6 +62,7 @@ const PASSTHROUGH_COMMANDS = [
     "workflow-abandon",
     "workflow-create",
     "workflow-list",
+    "workflow-plan",
     "workflow-resume",
     "workflow-run",
     "workflow-status",

package/dist/output/text/helpers.js

@@ -20,4 +20,4 @@ export { formatHealthPlain } from "./health-format.js";
 export { formatLintPlain } from "./lint-format.js";
 export { formatGateDecisionSummary, formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalProducerPlain, formatProposalRejectPlain, formatProposalShowPlain, } from "./proposal-format.js";
 export { formatShowPlain } from "./show-format.js";
-export { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";
+export { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowPlanPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";

package/dist/output/text/migrate.js

@@ -20,16 +20,25 @@ export function formatMigratePlain(result) {
     const lines = [`${planGlyph(plan.status)} ${plan.status}`];
     if (plan.taskV3Migration) {
         const tasks = plan.taskV3Migration;
-        lines.push(`    tasks: ${tasks.changed} change, ${tasks.skipped} current, ${tasks.blocked} blocked`);
+        lines.push(`    task-v2->v3: ${tasks.changed} change, ${tasks.skipped} current, ${tasks.blocked} blocked`);
+    }
+    if (plan.taskV4Migration) {
+        const tasks = plan.taskV4Migration;
+        lines.push(`    task-v3->v4: ${tasks.changed} change, ${tasks.skipped} current, ${tasks.blocked} blocked`);
     }
     if (plan.blockers?.length) {
         lines.push("", "blockers:", ...plan.blockers.map((blocker) => `  - ${blocker}`));
     }
     if (plan.backupPath) {
-        lines.push("", `backup: ${plan.backupPath}`);
+        lines.push("", `backup (v2->v3): ${plan.backupPath}`);
     }
     if (plan.applied !== undefined)
-        lines.push(`applied: ${plan.applied}`);
+        lines.push(`applied (v2->v3): ${plan.applied}`);
+    if (plan.taskV4BackupPath) {
+        lines.push(`backup (v3->v4): ${plan.taskV4BackupPath}`);
+    }
+    if (plan.taskV4Applied !== undefined)
+        lines.push(`applied (v3->v4): ${plan.taskV4Applied}`);
     return lines.join("\n");
 }
 export const migrateFormatters = [

package/dist/output/text/workflow-format.js

@@ -27,6 +27,35 @@ export function formatWorkflowListPlain(result) {
     })
         .join("\n");
 }
+/** §4.5's glyph table (P3b) — drawn from the repo's existing vocabulary (status-list.ts's ✗/✓, proposal-format.ts's →). */
+const CHILD_STATUS_GLYPHS = {
+    completed: "✓",
+    active: "→",
+    blocked: "⚠",
+    failed: "✗",
+};
+/**
+ * Render one `children:` tree node (P3b, spec §4.5) plus its own children,
+ * recursively, indenting two spaces per level. Order is SPAWN order (the
+ * envelope's own array order) — the tree is structural, never severity-sorted.
+ */
+function renderChildNode(child, depth, lines) {
+    const indent = "  ".repeat(depth + 1);
+    const runId = typeof child.runId === "string" ? child.runId : "unknown";
+    const ref = typeof child.workflowRef === "string" ? child.workflowRef : "unknown";
+    const status = typeof child.status === "string" ? child.status : "unknown";
+    const glyph = CHILD_STATUS_GLYPHS[status] ?? "?";
+    const stepId = typeof child.stepId === "string" ? ` (step "${child.stepId}")` : "";
+    lines.push(`${indent}- ${glyph} ${runId} ${ref} [${status}]${stepId}`);
+    const resume = typeof child.resume === "object" && child.resume !== null ? child.resume : undefined;
+    if (resume) {
+        lines.push(`${indent}    resume: ${typeof resume.command === "string" ? resume.command : ""}`);
+        lines.push(`${indent}    then:   ${typeof resume.then === "string" ? resume.then : ""}`);
+    }
+    const nested = Array.isArray(child.children) ? child.children : [];
+    for (const grandchild of nested)
+        renderChildNode(grandchild, depth + 1, lines);
+}
 export function formatWorkflowStatusPlain(result) {
     const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
     const workflow = typeof result.workflow === "object" && result.workflow !== null
@@ -55,6 +84,16 @@ export function formatWorkflowStatusPlain(result) {
             }
         }
     }
+    // The parent-child status tree (P3b, spec §4.5): renders ONLY when
+    // `children` is a non-empty array, immediately after `steps:` and before
+    // `units:`. Absent for a childless run — byte-identical to pre-P3b text
+    // (row B-33, PRESERVE).
+    const children = Array.isArray(result.children) ? result.children : undefined;
+    if (children && children.length > 0) {
+        lines.push("children:");
+        for (const child of children)
+            renderChildNode(child, 0, lines);
+    }
     // `workflow status --units` (#22): the honest per-unit diagnostic surface —
     // failure_reason plus any journaled result/error text. Diagnostics only; the
     // deterministic step evidence above is unaffected.
@@ -108,6 +147,27 @@ function formatWorkflowCheckinLine(result) {
         return null;
     return checkin.directive.trim();
 }
+/**
+ * One `! lowering[<severity>] <code> (<adapter>[; <field>]): <message>` line
+ * from a `{code, severity, adapter, field?, message}` lowering notice, or
+ * `null` when `value` does not carry that shape. Shared by
+ * `formatWorkflowRunPlain` (dispatch-time notices) and `formatWorkflowPlanPlain`
+ * (freeze-time notices, P3b §4.6, B-57) — ONE projection, rendered the same
+ * way regardless of which invocation computed the notice.
+ */
+function renderLoweringNoticeLine(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const notice = value;
+    if (typeof notice.code !== "string" ||
+        typeof notice.severity !== "string" ||
+        typeof notice.adapter !== "string" ||
+        typeof notice.message !== "string") {
+        return null;
+    }
+    const field = typeof notice.field === "string" && notice.field ? `; ${notice.field}` : "";
+    return `! lowering[${notice.severity}] ${notice.code} (${notice.adapter}${field}): ${notice.message}`;
+}
 export function formatWorkflowRunPlain(result) {
     const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
     if (!run)
@@ -123,16 +183,9 @@ export function formatWorkflowRunPlain(result) {
     // default text output has the same observability as JSON without widening a
     // durable workflow schema.
     for (const value of Array.isArray(result.notices) ? result.notices : []) {
-        if (typeof value !== "object" || value === null)
-            continue;
-        const notice = value;
-        if (typeof notice.code !== "string" ||
-            typeof notice.severity !== "string" ||
-            typeof notice.adapter !== "string" ||
-            typeof notice.message !== "string")
-            continue;
-        const field = typeof notice.field === "string" && notice.field ? `; ${notice.field}` : "";
-        lines.push(`! lowering[${notice.severity}] ${notice.code} (${notice.adapter}${field}): ${notice.message}`);
+        const line = renderLoweringNoticeLine(value);
+        if (line)
+            lines.push(line);
     }
     const executed = Array.isArray(result.executed) ? result.executed : [];
     if (executed.length === 0) {
@@ -180,3 +233,132 @@ export function formatWorkflowCreatePlain(r) {
 export function formatWorkflowResumePlain(r) {
     return formatWorkflowStatusPlain(r) ?? `Resumed workflow run ${String(r.id ?? r.runId ?? "?")}`;
 }
+/**
+ * A step's `inputBindings[]` (P3b §4.6's `with:` line) — a literal shows its
+ * value, a reference shows only its unresolved `from` (never a resolved
+ * value; B-52/B-53's closed print list explicitly allows a literal *task/
+ * child* input binding's `.value`, unlike a literal **environment** binding's).
+ */
+function formatInputBindingsList(bindings) {
+    return bindings
+        .map((binding) => {
+        const name = String(binding.name ?? "");
+        return binding.kind === "literal"
+            ? `${name}=${JSON.stringify(binding.value)} (literal)`
+            : `${name} <- ${String(binding.from ?? "")} (reference)`;
+    })
+        .join(", ");
+}
+/**
+ * One `akm workflow plan` step line (P3b, spec §4.6), plus its child-workflow
+ * expansion's own steps, recursively, indented one level per composition
+ * boundary. A child step also carries the child's `planHash` on the step
+ * line itself, and (when present) a `with:` line for the step's own
+ * `inputBindings[]` and an `exports:` line for the child's declared output
+ * names — §4.6's worked example.
+ */
+function renderPlanStepLines(step, ordinal, lines, prefix = "  ") {
+    const stepId = typeof step.stepId === "string" ? step.stepId : "unknown";
+    const targetKind = typeof step.targetKind === "string" ? `[${step.targetKind}]` : "";
+    const expansion = typeof step.expansion === "object" && step.expansion !== null ? step.expansion : {};
+    const via = typeof expansion.via === "string" ? expansion.via : "direct";
+    const childPlanHash = typeof expansion.childPlanHash === "string" ? expansion.childPlanHash : undefined;
+    const viaText = via === "task"
+        ? `via ${String(expansion.taskRef ?? "")}`
+        : via === "child"
+            ? `-> ${String(expansion.childRef ?? "")}${childPlanHash ? ` (plan ${childPlanHash})` : ""}`
+            : "direct";
+    lines.push(`${prefix}${ordinal}. ${stepId} ${targetKind} ${viaText}`.replace(/ +/g, " ").trimEnd());
+    const detailPrefix = `${prefix}  `;
+    const inputBindings = Array.isArray(step.inputBindings) ? step.inputBindings : [];
+    if (inputBindings.length > 0) {
+        lines.push(`${detailPrefix}with: ${formatInputBindingsList(inputBindings)}`);
+    }
+    if (via === "child") {
+        const childOutputs = Array.isArray(expansion.childOutputs) ? expansion.childOutputs : [];
+        if (childOutputs.length > 0) {
+            lines.push(`${detailPrefix}exports: ${childOutputs.map(String).join(", ")}`);
+        }
+        const childSteps = Array.isArray(expansion.steps) ? expansion.steps : [];
+        for (const [index, childStep] of childSteps.entries()) {
+            renderPlanStepLines(childStep, index + 1, lines, `${prefix}  ${ordinal}.`);
+        }
+    }
+}
+/**
+ * `akm workflow plan <ref>` text mode (P3b, spec §4.6): a human summary of
+ * the same compile+freeze data `--format json` returns — never a resolved
+ * env/secret value (B-52, B-53).
+ */
+export function formatWorkflowPlanPlain(result) {
+    if (typeof result.ref !== "string")
+        return null;
+    const sourceFormat = typeof result.sourceFormat === "string" ? result.sourceFormat : "unknown";
+    const irVersion = typeof result.irVersion === "number" ? result.irVersion : "unknown";
+    const planHash = typeof result.planHash === "string" ? result.planHash : "unknown";
+    const execution = typeof result.execution === "object" && result.execution !== null
+        ? result.execution
+        : {};
+    const budget = typeof result.budget === "object" && result.budget !== null
+        ? result.budget
+        : undefined;
+    const lines = [
+        `workflow: ${result.ref} (${sourceFormat})`,
+        `source:   ${typeof result.sourcePath === "string" ? result.sourcePath : "unknown"}`,
+        `plan:     irVersion ${irVersion}, hash ${planHash} (not published)`,
+    ];
+    const limitsParts = [
+        `maxConcurrency ${typeof execution.maxConcurrency === "number" ? execution.maxConcurrency : "?"}`,
+    ];
+    if (budget) {
+        const budgetParts = [];
+        if (typeof budget.maxUnits === "number")
+            budgetParts.push(`max_units ${budget.maxUnits}`);
+        if (typeof budget.maxTokens === "number")
+            budgetParts.push(`max_tokens ${budget.maxTokens}`);
+        if (budgetParts.length > 0)
+            limitsParts.push(`budget ${budgetParts.join(", ")}`);
+    }
+    lines.push(`limits:   ${limitsParts.join("; ")}`);
+    const params = Array.isArray(result.params) ? result.params : undefined;
+    if (params && params.length > 0)
+        lines.push(`params:   ${params.join(", ")}`);
+    const outputs = typeof result.outputs === "object" && result.outputs !== null
+        ? result.outputs
+        : undefined;
+    if (outputs) {
+        for (const [name, declaration] of Object.entries(outputs)) {
+            const from = typeof declaration === "object" && declaration !== null
+                ? String(declaration.from ?? "")
+                : "";
+            lines.push(`outputs:  ${name} <- ${from}`);
+        }
+    }
+    const steps = Array.isArray(result.steps) ? result.steps : [];
+    lines.push("steps:");
+    for (const [index, step] of steps.entries()) {
+        renderPlanStepLines(step, index + 1, lines);
+    }
+    const sourceReadSet = Array.isArray(result.sourceReadSet) ? result.sourceReadSet : [];
+    if (sourceReadSet.length > 0) {
+        lines.push("read set:");
+        for (const entry of sourceReadSet)
+            lines.push(`  ${String(entry)}`);
+    }
+    const notices = Array.isArray(result.notices) ? result.notices : [];
+    if (notices.length > 0) {
+        lines.push("notices:");
+        for (const value of notices) {
+            const line = renderLoweringNoticeLine(value);
+            if (line)
+                lines.push(`  ${line}`);
+        }
+    }
+    const warnings = Array.isArray(result.warnings) ? result.warnings : [];
+    if (warnings.length > 0) {
+        lines.push("warnings:");
+        for (const warning of warnings)
+            lines.push(`  ! ${String(warning)}`);
+    }
+    return lines.join("\n");
+}

package/dist/output/text/workflow.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 // Output text formatters for all `akm workflow *` commands.
-import { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./helpers.js";
+import { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowPlanPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./helpers.js";
 export const workflowFormatters = [
     { command: "workflow-status", handler: (r) => formatWorkflowStatusPlain(r) },
     { command: "workflow-list", handler: (r) => formatWorkflowListPlain(r) },
@@ -10,4 +10,5 @@ export const workflowFormatters = [
     { command: "workflow-resume", handler: (r) => formatWorkflowResumePlain(r) },
     { command: "workflow-abandon", handler: (r) => formatWorkflowStatusPlain(r) },
     { command: "workflow-run", handler: (r) => formatWorkflowRunPlain(r) },
+    { command: "workflow-plan", handler: (r) => formatWorkflowPlanPlain(r) },
 ];

package/dist/registry/semver.js

@@ -41,3 +41,7 @@ export function isSemverRange(input) {
 export function maxSatisfying(versions, range) {
     return semver.maxSatisfying(versions, range) ?? undefined;
 }
+/** True when `version` satisfies `range` (both real semver forms). False for an invalid version or range. */
+export function satisfiesRange(version, range) {
+    return semver.satisfies(version, range);
+}

package/dist/runtime.js

@@ -77,6 +77,7 @@ function nodeSpawnAdapter(cmd, options) {
         env: options.env ?? process.env,
         detached: options.detached,
         stdio: [stdioFor(options.stdin), stdioFor(options.stdout), stdioFor(options.stderr)],
+        windowsVerbatimArguments: options.windowsVerbatimArguments,
     });
     // Node's 'exit' fires (null, signal) when the child dies from a signal.
     // Resolving `code ?? 0` reported that as SUCCESS, so an OOM-killed or