akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/core/subprocess.js

@@ -8,8 +8,9 @@
  * CLI spawn wrapper so non-agent subprocess callers (task commands, setup
  * probes/installers) get the same guarantees the agent path already had:
  *
- *   • Process-GROUP spawn (`detached: true` when capturing) so a negative-pid
- *     kill reaps the whole descendant tree — no orphaned children.
+ *   • Process-GROUP spawn (`detached: true` when capturing ON POSIX) so a
+ *     negative-pid kill reaps the whole descendant tree — no orphaned children.
+ *     See {@link spawnsOwnProcessGroup} for why Windows is excluded.
  *   • A SIGTERM→SIGKILL kill ladder on timeout/abort — a child that ignores
  *     SIGTERM is force-killed after a grace period instead of wedging forever.
  *   • Time-bounded output capture ({@link readStream}) that cannot block past
@@ -33,6 +34,49 @@ import { spawn as runtimeSpawn } from "../runtime.js";
  * reaped alongside the node wrapper. The fallback keeps test fakes working
  * without modification.
  */
+/**
+ * Whether a captured spawn should ask for its own process group.
+ *
+ * POSIX: yes. `detached` is `setsid()`, which is what makes {@link killGroup}'s
+ * `process.kill(-pid, …)` reap the whole descendant tree. It does not touch the
+ * child's stdio.
+ *
+ * Windows: no — the same flag means something unrelated and actively harmful.
+ * There it maps to `DETACHED_PROCESS`, so the child is created WITHOUT A
+ * CONSOLE; a console host started that way (powershell.exe, cmd.exe) allocates
+ * its own console during startup, which REPLACES the std handles it was handed,
+ * and everything it writes goes to that phantom console instead of our pipe.
+ * The command still runs and its exit code still propagates — the output just
+ * vanishes, which is exactly how it failed: a scheduled `akm --version` logged
+ * `exit_code=0` with both captured streams empty. Windows gains nothing in
+ * return, because `process.kill(-pid, …)` is a POSIX process-group call that
+ * throws there; {@link killGroup} already falls back to `proc.kill(signal)`.
+ *
+ * Exported for direct unit testing with an explicit platform.
+ */
+export function spawnsOwnProcessGroup(platform = process.platform) {
+    return platform !== "win32";
+}
+/**
+ * The exact options one managed run hands its spawn — pure, so the platform
+ * dependency above is testable on any host rather than only on the platform
+ * that would break.
+ */
+export function buildSpawnOptions(opts, platform = process.platform) {
+    const capture = opts.capture;
+    return {
+        stdin: capture ? (opts.stdin !== undefined ? "pipe" : "ignore") : "inherit",
+        stdout: capture ? "pipe" : "inherit",
+        stderr: capture ? "pipe" : "inherit",
+        ...(opts.env ? { env: opts.env } : {}),
+        ...(opts.cwd ? { cwd: opts.cwd } : {}),
+        // Only in captured mode — interactive mode inherits the parent terminal's
+        // process group intentionally — and only where the flag means a process
+        // group at all (see spawnsOwnProcessGroup).
+        ...(capture && spawnsOwnProcessGroup(platform) ? { detached: true } : {}),
+        ...(opts.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+    };
+}
 export function killGroup(proc, signal) {
     if (typeof proc.pid === "number") {
         try {
@@ -296,17 +340,7 @@ export async function runManagedSubprocess(cmd, opts) {
     }
     let proc;
     try {
-        proc = spawnFn(cmd, {
-            stdin: capture ? (opts.stdin !== undefined ? "pipe" : "ignore") : "inherit",
-            stdout: capture ? "pipe" : "inherit",
-            stderr: capture ? "pipe" : "inherit",
-            ...(opts.env ? { env: opts.env } : {}),
-            ...(opts.cwd ? { cwd: opts.cwd } : {}),
-            // Spawn in its own process group so killGroup(-pid, signal) reaches all
-            // descendants. Only in captured mode — interactive mode inherits the
-            // parent terminal's process group intentionally.
-            ...(capture ? { detached: true } : {}),
-        });
+        proc = spawnFn(cmd, buildSpawnOptions(opts));
     }
     catch (err) {
         return {

package/dist/execution/guarded-source.js

@@ -352,6 +352,50 @@ export class GuardedExecutionSourceCollector {
             directoryManifests: Object.freeze([...this.#directories.values()].sort((left, right) => compareCodePoints(directorySortKey(left), directorySortKey(right)))),
         });
     }
+    /**
+     * Merge another collector's captured sources and directory manifests into
+     * this one (A-N7, spec docs/plans/specs/p3a-plan-v5-child-freeze.md §4.2
+     * step 6). The recursive child-workflow freeze gives each child its OWN
+     * fresh collector, so a child's plan (and therefore its `planHash`) is a
+     * pure function of its own source, independent of its position in the
+     * parent (A-N7's rejected alternative: sharing the parent's collector,
+     * which would make an identical child hash differently depending on what
+     * the parent had already captured). The parent then absorbs the child's
+     * records so its own final pre-publication CAS ({@link revalidate}) covers
+     * every child file too.
+     *
+     * Re-runs `#assertNoPhysicalOwnerAlias` for each newly-absorbed source
+     * record, so the shared-physical-owner authority holds ACROSS the
+     * composition, not just within one workflow's own freeze. A record whose
+     * key (resolved source path) is already present is required to be
+     * byte-identical to the one already held — two DISJOINT branches
+     * composing the SAME child (a diamond, not a cycle) absorb the same file
+     * twice with identical content and pass silently; two branches that
+     * somehow captured the same path with different content fail closed.
+     */
+    absorb(other) {
+        for (const [key, record] of other.#sources) {
+            const existing = this.#sources.get(key);
+            if (existing) {
+                if (!sameSnapshotValue(existing.source, record.source)) {
+                    throw new UsageError(`${record.source.sourcePath} was captured with conflicting content across a composed workflow freeze.`, "RESOURCE_ALREADY_EXISTS");
+                }
+                continue;
+            }
+            this.#assertNoPhysicalOwnerAlias(record.source);
+            this.#sources.set(key, record);
+        }
+        for (const [key, manifest] of other.#directories) {
+            const existing = this.#directories.get(key);
+            if (existing) {
+                if (!sameSnapshotValue(existing, manifest)) {
+                    throw new UsageError(`${manifest.directoryPath} changed between guarded directory reads across a composed workflow freeze.`, "RESOURCE_ALREADY_EXISTS");
+                }
+                continue;
+            }
+            this.#directories.set(key, manifest);
+        }
+    }
     revalidate() {
         for (const record of this.#sources.values()) {
             let current;

package/dist/execution/input-contract.js

@@ -0,0 +1,250 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/**
+ * The shared input contract, generalizing the pure module
+ * `src/workflows/ir/params.ts` (workflow parameters) into a contract-shaped
+ * vocabulary both workflow params AND task source v4's `inputs:`
+ * declarations consume — one validation/coercion implementation, injected
+ * per-caller diagnostics (D3-N3). Binding boundary: `src/execution/**` must
+ * never import `src/workflows/**` (D3-N1) — `INPUT_NAME_PATTERN` and the
+ * canonical-JSON helpers are therefore defined locally rather than imported
+ * from the workflow side (D3-N1/D3-N2), verified by
+ * `tests/execution/input-contract.test.ts`'s purity/byte-equality scans.
+ * Pure module: no IO, no engine imports.
+ *
+ * See docs/architecture/decisions/0004-task-input-contract-and-flag-coercion.md
+ * for the full generalization history and the D3-N1/D3-N2/D3-N3 rationale.
+ */
+import { createHash } from "node:crypto";
+import { validateJsonSchemaSubset } from "../core/json-schema.js";
+/**
+ * Input/param names must be addressable as a plain identifier
+ * (`params.<ident>` / `inputs.<ident>`): a letter or underscore, then
+ * letters, digits, or underscores. Byte-identical source/flags to
+ * `src/workflows/program/schema.ts`'s `PROGRAM_PARAM_NAME_PATTERN`, which
+ * re-exports this constant (D3-N1) rather than defining its own copy.
+ */
+export const INPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Apply declared defaults on top of supplied values. A supplied value always
+ * wins, including an explicit falsy one (`false`, `0`, `""`) — PRESENCE, not
+ * truthiness, decides. A declared input with no `default` that is absent from
+ * `values` is left absent from the result (never filled with `undefined`); a
+ * value not named by the contract passes through unchanged — defaults are
+ * additive, not a filter. Returns a NEW object; `values` is never mutated.
+ */
+export function applyInputDefaults(contract, values) {
+    const result = { ...values };
+    for (const [name, declaration] of Object.entries(contract)) {
+        if (Object.hasOwn(result, name))
+            continue;
+        if (Object.hasOwn(declaration, "default"))
+            result[name] = declaration.default;
+    }
+    return result;
+}
+/**
+ * Validate `values` against the contract's declared schemas plus its
+ * `required` flags. Builds the same synthetic `{type:"object",
+ * properties:<schemas>}` object schema the workflow param validator built,
+ * re-roots {@link validateJsonSchemaSubset}'s leading `$` at `pathRoot`
+ * (default `"$"`), and additionally appends one
+ * `"<pathRoot>.<name>: is required"` string per declared-required input
+ * absent from `values` (schema violations first, missing-required after). A
+ * name absent from the contract is never constrained. Returns `[]` when
+ * `values` fully satisfies the contract.
+ */
+export function validateInputs(contract, values, options) {
+    const pathRoot = options?.pathRoot ?? "$";
+    const properties = {};
+    for (const [name, declaration] of Object.entries(contract))
+        properties[name] = declaration.schema;
+    const schemaErrors = Object.keys(properties).length === 0
+        ? []
+        : // redactValues: true — declared inputs can carry credentials, and this
+            // contract-violation text lands in stderr envelopes that get pasted into
+            // CI logs. See `coerceFlagValue`'s matching comment above.
+            validateJsonSchemaSubset(values, { type: "object", properties }, { redactValues: true }).map((error) => error.replace(/^\$/, pathRoot));
+    const missingRequired = [];
+    for (const [name, declaration] of Object.entries(contract)) {
+        if (declaration.required && !Object.hasOwn(values, name)) {
+            missingRequired.push(`${pathRoot}.${name}: is required`);
+        }
+    }
+    return [...schemaErrors, ...missingRequired];
+}
+/**
+ * Materialize exact-name CLI input flags against a contract. The CLI
+ * deliberately carries RAW string/boolean flag values to this one boundary
+ * so type coercion cannot race or drift from the declared contract:
+ * exact-name matching (a mistyped or undeclared flag name, or one that fails
+ * {@link INPUT_NAME_PATTERN}, is `diagnostics.unknownFlag` — the full
+ * declared set, sorted), array grouping (repeated flags on an array-declared
+ * input collect into an array in supplied order), the `[`-prefixed
+ * JSON-array shorthand, repeated-flag rejection on a non-array declaration
+ * (`diagnostics.duplicateNonArray`), and string-preserving coercion (a union
+ * type that permits `string` keeps the caller's exact text — `--version 001`
+ * on `type:"string"` stays the string `"001"`, never a silently-converted
+ * number, B-30). Ends by running {@link validateInputs} over the
+ * materialized result and raising `diagnostics.contractViolation` with its
+ * (still `"$"`-rooted) errors when non-empty.
+ *
+ * Returns `{}` immediately for zero flags, regardless of the contract, and
+ * calls no diagnostic — callers combine this with
+ * {@link applyInputDefaults} and a separate {@link validateInputs} call
+ * (after defaults are applied) to catch a `required` input that was never
+ * supplied as a flag at all.
+ */
+export function materializeInputFlags(contract, flags, diagnostics) {
+    if (flags.length === 0)
+        return {};
+    const declared = new Set(Object.keys(contract));
+    const grouped = new Map();
+    for (const flag of flags) {
+        if (!INPUT_NAME_PATTERN.test(flag.name) || !declared.has(flag.name)) {
+            throw diagnostics.unknownFlag(flag.name, [...declared].sort());
+        }
+        const values = grouped.get(flag.name) ?? [];
+        values.push(flag.value);
+        grouped.set(flag.name, values);
+    }
+    const entries = [];
+    for (const [name, rawValues] of grouped) {
+        entries.push([name, materializeFlagValues(name, rawValues, contract[name]?.schema, diagnostics)]);
+    }
+    const values = Object.fromEntries(entries);
+    const errors = validateInputs(contract, values);
+    if (errors.length > 0)
+        throw diagnostics.contractViolation(errors);
+    return values;
+}
+function materializeFlagValues(name, values, schema, diagnostics) {
+    const types = schemaTypes(schema);
+    if (types.includes("array")) {
+        if (values.length === 1 && typeof values[0] === "string" && values[0].trim().startsWith("[")) {
+            const parsed = parseJsonFlag(name, values[0], diagnostics);
+            if (!Array.isArray(parsed))
+                throw diagnostics.invalidValue(name, "must be a JSON array");
+            return parsed;
+        }
+        // "array" is the sole declared type, or there is more than one supplied
+        // flag occurrence: a lone-array declaration always wraps its value(s),
+        // and repeated flags on an array-CAPABLE declaration always group,
+        // regardless of what else the type union permits. A union that ALSO
+        // permits a scalar type (e.g. `["array","string"]`) must not force a
+        // single, non-bracketed value into this branch, though — F1: without
+        // this guard, `--x hello` against `type:["array","string"]` silently
+        // became `["hello"]` instead of staying the string "hello", because the
+        // per-element map below coerces each value against `items` (or nothing)
+        // rather than trying the union's scalar alternatives first. Route that
+        // single-value case through `coerceFlagValue` with the FULL schema
+        // instead, so its string-preservation (B-30) and null/number/boolean/
+        // object arms run before "array" is ever assumed.
+        if (types.length === 1 || values.length > 1) {
+            const itemSchema = isRecord(schema?.items) ? schema.items : undefined;
+            return values.map((value) => coerceFlagValue(name, value, itemSchema, diagnostics));
+        }
+        return coerceFlagValue(name, values[0], schema, diagnostics);
+    }
+    if (values.length > 1)
+        throw diagnostics.duplicateNonArray(name);
+    return coerceFlagValue(name, values[0], schema, diagnostics);
+}
+function coerceFlagValue(name, raw, schema, diagnostics) {
+    const types = schemaTypes(schema);
+    if (types.length === 0)
+        return raw;
+    if (typeof raw === "boolean") {
+        if (types.includes("boolean"))
+            return raw;
+        if (types.includes("string"))
+            return String(raw);
+        throw diagnostics.invalidValue(name, `requires a value of type ${types.join(" | ")}`);
+    }
+    // A union that permits strings keeps the caller's exact text. This
+    // prevents a value such as "001" from being silently converted to a
+    // number (B-30).
+    if (types.includes("string"))
+        return raw;
+    for (const type of types) {
+        switch (type) {
+            case "boolean":
+                if (raw === "true")
+                    return true;
+                if (raw === "false")
+                    return false;
+                break;
+            case "number": {
+                const value = Number(raw);
+                if (raw.trim() !== "" && Number.isFinite(value))
+                    return value;
+                break;
+            }
+            case "integer": {
+                const value = Number(raw);
+                if (raw.trim() !== "" && Number.isSafeInteger(value))
+                    return value;
+                break;
+            }
+            case "null":
+                if (raw === "null")
+                    return null;
+                break;
+            case "object": {
+                const parsed = parseJsonFlag(name, raw, diagnostics);
+                if (isRecord(parsed))
+                    return parsed;
+                break;
+            }
+            case "array": {
+                const parsed = parseJsonFlag(name, raw, diagnostics);
+                if (Array.isArray(parsed))
+                    return parsed;
+                break;
+            }
+        }
+    }
+    // Never echo the supplied value: typed-input flags can carry credentials,
+    // and this detail lands in stderr envelopes that get pasted into CI logs.
+    throw diagnostics.invalidValue(name, `must be ${types.join(" | ")}`);
+}
+function schemaTypes(schema) {
+    const declared = schema?.type;
+    if (typeof declared === "string")
+        return [declared];
+    return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
+}
+function parseJsonFlag(name, raw, diagnostics) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw diagnostics.malformedJson(name);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Canonical JSON used for input hashing: object keys recursively sorted, so
+ * two structurally-equal input value sets hash identically regardless of key
+ * insertion order. Byte-equal to `canonicalJson`
+ * (`src/workflows/ir/plan-hash.ts`) — see D3-N2 above.
+ */
+export function canonicalInputJson(value) {
+    return JSON.stringify(sortInputJsonKeys(value));
+}
+/** sha256 hex digest of {@link canonicalInputJson}'s output — a stable input-value fingerprint (B-39, for P2b execution identity). */
+export function canonicalInputHash(value) {
+    return createHash("sha256").update(canonicalInputJson(value)).digest("hex");
+}
+function sortInputJsonKeys(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => sortInputJsonKeys(item));
+    return Object.fromEntries(Object.entries(value)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, child]) => [key, sortInputJsonKeys(child)]));
+}

package/dist/execution/target-ref.js

@@ -0,0 +1,63 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/**
+ * The target-ref classifier (P1a Lane B, docs/plans/specs/p1a-with-rejection-classifier.md §4.1).
+ *
+ * `classifyTargetRef` is the canonical classifier for a canonical asset ref
+ * used as an execution target: `commands/<name>`, `scripts/<name>`,
+ * `tasks/<name>`, or `workflows/<name>`, each optionally bundle-qualified
+ * (`<bundle>//commands/<name>`). It reuses the repo's one ref parser
+ * (`parseBundleRef` / `bundleRefToString`, src/core/asset/asset-ref.ts) and
+ * accepts a value only when all of the following hold:
+ *
+ *   1. `parseBundleRef(value)` does not throw;
+ *   2. the parsed ref carries no `#fragment`;
+ *   3. `bundleRefToString(parsed) === value` — the value round-trips, which
+ *      rejects non-canonical spellings (`akm:commands/review`,
+ *      `bad.bundle//commands/review`) even when they happen to parse;
+ *   4. the concept id contains a `/`, and the family segment before the
+ *      first `/` is one of `commands`, `scripts`, `tasks`, `workflows`;
+ *   5. the name segment after the first `/` is non-empty.
+ *
+ * Explicit non-goals (binding, spec §4.1): no GitHub locator grammar, no
+ * `akm/command` builtin special case, no resolution, no filesystem access, no
+ * guessing. Callers layer builtin detection on top (see
+ * `classifyWorkflowSourceUses` in src/workflows/source-ir/uses.ts).
+ */
+import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
+import { UsageError } from "../core/errors.js";
+const FAMILY_KIND = {
+    commands: "command",
+    scripts: "script",
+    tasks: "task",
+    workflows: "workflow",
+};
+function targetRefInvalid(value) {
+    return new UsageError(`Target ref ${JSON.stringify(value)} must be a canonical commands/, scripts/, tasks/, or workflows/ asset ref.`, "TARGET_REF_INVALID");
+}
+/** Classify one exact canonical asset ref as an execution target. Never resolves or guesses. */
+export function classifyTargetRef(value) {
+    let parsed;
+    try {
+        parsed = parseBundleRef(value);
+    }
+    catch {
+        throw targetRefInvalid(value);
+    }
+    if (parsed.fragment !== undefined)
+        throw targetRefInvalid(value);
+    if (bundleRefToString(parsed) !== value)
+        throw targetRefInvalid(value);
+    const slash = parsed.conceptId.indexOf("/");
+    if (slash < 0)
+        throw targetRefInvalid(value);
+    const family = parsed.conceptId.slice(0, slash);
+    const name = parsed.conceptId.slice(slash + 1);
+    if (name.length === 0)
+        throw targetRefInvalid(value);
+    const kind = FAMILY_KIND[family];
+    if (kind === undefined)
+        throw targetRefInvalid(value);
+    return Object.freeze({ kind, ref: value });
+}

package/dist/indexer/usage/usage-events.js

@@ -2,11 +2,22 @@
 // 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/.
 const USAGE_EVENT_SOURCES = new Set(["user", "improve", "task", "audit", "unknown"]);
-/** Resolve subprocess provenance without treating an invalid value as user demand. */
-export function resolveUsageEventSource(env = process.env) {
+/**
+ * Resolve subprocess provenance without treating an invalid value as user
+ * demand.
+ *
+ * `fallback` (spec docs/plans/specs/p1b-model-extraction.md §5.2, F-1) is what
+ * an unset/empty ambient value resolves to — it defaults to `"user"`, which
+ * reproduces every pre-P1b call site byte-for-byte (P-07). A caller that
+ * already knows the invocation's provenance (the task runner, threading its
+ * `ExecutionProvenanceContext`) passes its resolved value as the fallback
+ * instead, so a recognized ambient `AKM_EVENT_SOURCE` still wins everywhere it
+ * won before, and only the *default* changes.
+ */
+export function resolveUsageEventSource(env = process.env, fallback = "user") {
     const raw = env.AKM_EVENT_SOURCE;
     if (raw === undefined || raw === "")
-        return "user";
+        return fallback;
     return USAGE_EVENT_SOURCES.has(raw) ? raw : "unknown";
 }
 // ── Schema ──────────────────────────────────────────────────────────────────

package/dist/integrations/agent/execution-lowering.js

@@ -723,11 +723,14 @@ export async function executeInteractiveAgentInvocation(input, seams = {}) {
 export async function dispatchLoweredExecutionRequest(lowered, options = {}) {
     requireLoweredExecutionProvenance(lowered);
     const optionSnapshot = snapshotStrictRecord(options, "lowered execution dispatch options");
-    assertSnapshotKeys(optionSnapshot, ["executeRunner", "chat", "onRetryAttempt", "runAgent", "runSdk", "lease", "runOptions"], "lowered execution dispatch options");
+    assertSnapshotKeys(optionSnapshot, ["executeRunner", "chat", "onRetryAttempt", "runAgent", "runSdk", "lease", "runOptions", "eventSource"], "lowered execution dispatch options");
     const strictOptions = optionSnapshot;
     if (strictOptions.onRetryAttempt !== undefined && typeof strictOptions.onRetryAttempt !== "function") {
         throw new TypeError("lowered execution dispatch options.onRetryAttempt must be a function");
     }
+    if (strictOptions.eventSource !== undefined && typeof strictOptions.eventSource !== "string") {
+        throw new TypeError("lowered execution dispatch options.eventSource must be a string");
+    }
     const usesDefaultRunner = strictOptions.executeRunner === undefined;
     const run = runnerDispatcher(strictOptions.executeRunner);
     const operationalSnapshot = snapshotStrictRecord(strictOptions.runOptions ?? {}, "lowered execution operational options");
@@ -759,6 +762,14 @@ export async function dispatchLoweredExecutionRequest(lowered, options = {}) {
         ...(operational.setTimeoutFn !== undefined ? { setTimeoutFn: operational.setTimeoutFn } : {}),
         ...(operational.clearTimeoutFn !== undefined ? { clearTimeoutFn: operational.clearTimeoutFn } : {}),
         ...(operational.onEvent !== undefined ? { onEvent: operational.onEvent } : {}),
+        // F-1 (spec docs/plans/specs/p1b-model-extraction.md §5.2 point 3): the
+        // ONE narrowly-scoped exception to "resolved content cannot be
+        // overridden" — sets exactly the one named key, never a caller-supplied
+        // env bag (runOptions.env stays unhonored, same as before P1b; see
+        // DispatchLoweredExecutionOptions.eventSource's doc).
+        ...(strictOptions.eventSource !== undefined
+            ? { env: { ...lowered.options.env, AKM_EVENT_SOURCE: strictOptions.eventSource } }
+            : {}),
     });
     const ownedLease = strictOptions.lease === undefined && usesDefaultRunner;
     const lease = strictOptions.lease ??

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 = [