akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/commands/tasks/tasks.js

@@ -26,14 +26,19 @@ import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetFor
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
+import { prepareTaskV3Execution } from "../../tasks/prepare/prepare.js";
 import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
-import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
-import { prepareTaskV3Execution } from "../../tasks/runtime-v3.js";
+import { createExecutionProvenanceContext } from "../../tasks/run/provenance.js";
+import { runTask } from "../../tasks/run/run-task.js";
+import { readTaskHistory } from "../../tasks/run/task-history.js";
+import { exitCodeForStatus } from "../../tasks/run/task-result.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
 import { assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "../../tasks/scheduler-binding.js";
 import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
 import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
-import { parseTaskV3Yaml, TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
+import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
+import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
+import { TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
 import { normaliseTaskConceptId, normaliseTaskId } from "../../tasks/task-id.js";
 import { applyAutonomyGate, configuredDirectAutonomyLanes, describeGatedLanes } from "../improve/autonomy-gate.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
@@ -77,7 +82,8 @@ export async function akmTasksAdd(input, deps = {}) {
         tags: input.tags,
         enabled: input.disabled !== true,
     });
-    const task = parseTaskV3Yaml({ yaml, filePath: assetPath, workspaceRoot: stashDir });
+    const parsedTask = parseTaskSource({ yaml, filePath: assetPath, workspaceRoot: stashDir });
+    const task = projectTaskSourceV4(parsedTask.v4);
     const qualifiedRef = makeBundleRef(bundle.bundleName, `tasks/${id}`);
     await prepareTaskV3Execution(task, {
         taskId: id,
@@ -87,12 +93,27 @@ export async function akmTasksAdd(input, deps = {}) {
         config: bundle.config,
         resolveAsset: taskProjectionAssetResolver(bundle.config, bundle.bundleName, stashDir),
     });
+    // Bindings are compiled from the ORIGINAL parsed document, not the
+    // `task`/`projectTaskSourceV4` projection above — mirroring
+    // scheduler-sync.ts's compileTaskSources (spec §3.2.7's project-v4.ts
+    // header): the projection deliberately drops each schedule entry's own
+    // `enabled` (P4-N6), so building bindings from it would silently ignore
+    // `--disabled`. A task source v4 document has no document-level
+    // `akm.enabled`, so `enabled: true` is passed at the document level and
+    // every entry's own `enabled` (always present, defaulted at parse time)
+    // decides.
     const taskBindings = compileTaskSchedulerBindings({
         id,
         qualifiedRef,
         ...(bundle.installTarget ? { bundleTarget: bundle.installTarget } : {}),
-        enabled: task.akm?.enabled !== false,
-        schedules: task.triggers.schedules,
+        enabled: true,
+        schedules: parsedTask.v4.schedule.map((schedule) => ({
+            cron: schedule.cron,
+            ordinal: schedule.ordinal,
+            enabled: schedule.enabled,
+            source: schedule.source,
+            inputs: schedule.inputs,
+        })),
     });
     const taskBinding = taskBindings[0];
     if (!taskBinding)
@@ -227,20 +248,52 @@ export async function akmTasksRun(id, options = {}) {
     const bundle = resolveTaskReadBundle(parsed.bundle, options.target);
     const adapterId = bundle.source.adapterId ?? detectAdapterId(bundle.source.path);
     const resolvedId = taskIdForAdapter(parsed.id, adapterId);
+    const scheduled = options.scheduled === true;
+    // D5 "Construction" (spec docs/plans/specs/p1b-model-extraction.md §1.2/
+    // §5.2): built ONCE at this invocation boundary. eventSource is "task"
+    // whether or not --scheduled was passed (§1.6 D5-N1) — scheduled stays a
+    // separate field carrying its own pre-existing meaning (activation policy,
+    // scheduler env), never selecting the event source.
+    const provenance = createExecutionProvenanceContext(scheduled);
+    // F-3 (spec §5.4): RunTaskOptions.stashDir renamed to bundleDir — VALUE-
+    // preserving, no CLI flag change.
+    //
+    // P2a Lane C (spec docs/plans/specs/p2a-task-source-v4.md §5.1): the raw,
+    // exact-name input flags `tasks-cli.ts`'s Stage 1 captures ride through
+    // unchanged to `runTask` -> `loadPreparedTask`'s Stage 2 materializer,
+    // which owns declaring `inputFlags` on `RunTaskOptions` and attaching the
+    // materialized literals to the constructed `TaskInvocation`. This is only
+    // the pass-through surface: a valid flag set stays byte-identical to the
+    // same run without flags (§0), and P2a delivers nothing to the target.
+    //
+    // No `as` cast (test-review finding, spec §6 F-5): `RunTaskOptions` (this
+    // literal's inferred type is checked directly against it, below) declares
+    // every one of these fields, so the compiler — not a suppressed excess-
+    // property check — enforces this seam. A future rename or removal on
+    // either side now fails `tsc`, not silently at the `runTask` boundary.
     const runOptions = {
-        stashDir: bundle.source.path,
+        bundleDir: bundle.source.path,
         bundleName: bundle.source.name,
         adapterId,
-        scheduled: options.scheduled === true,
+        scheduled,
+        provenance,
+        inputFlags: options.inputFlags,
     };
     // The runner owns the prepare-before-reserve boundary. Invalid source,
     // projectability, and resolver failures therefore create no history row.
     const result = await runTask(resolvedId, runOptions);
-    const exitCode = result.status === "failed" && result.target.kind === "command" && result.detail?.exitCode === 78
+    // C-7 (spec §5.6): after D8's result-vocabulary re-code, "command" means
+    // the agent/LLM arm — the native shell/script arm now reports "shell" /
+    // "script". Rewired in the SAME commit as the vocabulary re-code so a
+    // shell/script task's process exit 78 still passes through as CLI exit 78
+    // (documented behavior, src/assets/hints/cli-hints-short.md:95).
+    const exitCode = result.status === "failed" &&
+        (result.target.kind === "shell" || result.target.kind === "script") &&
+        result.detail?.exitCode === 78
         ? 78
         : exitCodeForStatus(result.status);
     return {
-        ok: result.status === "completed" || result.status === "disabled",
+        ok: result.status === "completed",
         result,
         exitCode,
     };
@@ -284,18 +337,34 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
     }
     const inspection = await sched.inspectBindings({ rebind: options.rebind === true });
     const rawEntries = [...inspection.installed];
-    const allEntries = rawEntries.map((entry) => ({
-        ...entry,
-        ...(entry.nativeId !== undefined ? { nativeId: entry.nativeId } : {}),
-        ...(entry.invocation !== undefined ? { invocation: Object.freeze([...entry.invocation]) } : {}),
-        binding: "binding" in entry ? [...entry.binding] : [],
-        contextPath: "contextPath" in entry ? entry.contextPath : "",
-    }));
+    const allEntries = rawEntries.map((entry) => {
+        const contextPath = "contextPath" in entry ? entry.contextPath : "";
+        // #846: recover the resolved bundle path this entry was installed
+        // under from its own scheduler-context descriptor. Any failure (no
+        // descriptor, unreadable, corrupt, owned by another user) leaves
+        // ownerBundlePath unset — belongsToBundle must never treat that as
+        // "mine".
+        const ownerBundlePath = contextPath ? resolveInstalledOwnerPath(contextPath) : undefined;
+        return {
+            ...entry,
+            ...(entry.nativeId !== undefined ? { nativeId: entry.nativeId } : {}),
+            ...(entry.invocation !== undefined ? { invocation: Object.freeze([...entry.invocation]) } : {}),
+            binding: "binding" in entry ? [...entry.binding] : [],
+            contextPath,
+            ...(ownerBundlePath !== undefined ? { ownerBundlePath } : {}),
+        };
+    });
     const nativeArtifacts = inspection.artifacts;
     const common = {
         sourceRoot: stashDir,
         adapterId: resolved.source.adapterId ?? detectAdapterId(stashDir),
         bundleName: resolved.source.name,
+        // #846: only meaningful for a primary/unconfigured-bundle sync. A
+        // `--bundle <target>` entry's scheduler-context descriptor records the
+        // invoking process's OWN primary AKM_BUNDLE_DIR, not the targeted
+        // bundle's directory, so path-scoping stays gated on the case it's
+        // actually valid for (see belongsToBundle).
+        ...(syncTarget === undefined ? { bundlePath: path.resolve(stashDir) } : {}),
         ...(syncTarget ? { bundleTarget: syncTarget } : {}),
         backend: sched.name,
         installed: allEntries,
@@ -720,6 +789,15 @@ function groupInstalledBindings(entries, invocation) {
     }
     return [...groups.values()].map((group) => ({ ...group, taskIds: group.taskIds.sort() }));
 }
+/** Best-effort recovery of an installed binding's owning bundle path (#846). */
+function resolveInstalledOwnerPath(contextPath) {
+    try {
+        return validateSchedulerContextDescriptor(contextPath).environment.AKM_BUNDLE_DIR;
+    }
+    catch {
+        return undefined;
+    }
+}
 function inspectInstalledBinding(entry, invocation) {
     const status = [];
     const binding = entry.binding;
@@ -905,7 +983,14 @@ function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
         };
     };
 }
-function resolveTaskReadBundle(refBundle, flagBundle) {
+/**
+ * Exported for `src/commands/tasks/explain.ts` (P2b Lane B, spec
+ * docs/plans/specs/p2b-input-bindings.md §4.5, B-N4): `akm task explain`
+ * resolves its `--bundle` axis identically to every other read-only task
+ * verb here (`akm task history`, `akm task run`) — the SAME resolver, not a
+ * second one.
+ */
+export function resolveTaskReadBundle(refBundle, flagBundle) {
     if (refBundle && flagBundle && refBundle !== flagBundle) {
         throw new UsageError(`Task ref selects bundle ${JSON.stringify(refBundle)}, but --bundle selects ${JSON.stringify(flagBundle)}.`, "INVALID_FLAG_VALUE");
     }
@@ -983,12 +1068,43 @@ function assertNoForeignSchedule(entries, id, installTarget) {
     if (foreign)
         throw new UsageError(foreignScheduleMessage(id, foreign.target), "RESOURCE_ALREADY_EXISTS");
 }
+/**
+ * Infer a JSON-Schema-subset `type` keyword from one `--params` value's
+ * runtime shape (spec docs/plans/specs/p4-deletions-closeout.md §3.2.6, row
+ * B-20). `null` is not one of the five runtime types the spec enumerates
+ * (string/number/boolean/object/array) but is a value JSON.parse can still
+ * produce for a param; `src/core/json-schema.ts`'s subset validator accepts
+ * `"null"` as a `type`, so it is handled rather than mis-typed.
+ */
+function jsonSchemaTypeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * Render `--params` as typed `inputs:` declarations, one per key, each
+ * carrying a `default:` equal to the authored value and a `type:` inferred
+ * from its own JSON runtime shape (row B-20). Never emitted as `with:` —
+ * task source v4 accepts `with:` only on `uses: akm/command` (§3.2.6's
+ * `parseTarget`/`checkTopLevelKeys`), and a workflow target's declared
+ * inputs are what `load-task.ts`'s existing v4 delivery override binds into
+ * the child run's params.
+ */
+function renderInputsFromParams(params) {
+    const inputs = {};
+    for (const [name, value] of Object.entries(params)) {
+        inputs[name] = { type: jsonSchemaTypeOf(value), default: value };
+    }
+    return inputs;
+}
 function renderTaskYaml(input) {
-    const obj = { version: 3 };
+    const obj = { version: 4 };
     if (input.workflow) {
         obj.uses = input.workflow;
         if (input.params)
-            obj.with = parseJsonObjectArg(input.params);
+            obj.inputs = renderInputsFromParams(parseJsonObjectArg(input.params));
     }
     else if (input.prompt) {
         obj.uses = "akm/command";
@@ -996,22 +1112,40 @@ function renderTaskYaml(input) {
     }
     else if (input.command !== undefined) {
         if (Array.isArray(input.command)) {
-            throw new UsageError("Task v3 --command accepts one shell string; argv arrays require manual migration.", "INVALID_FLAG_VALUE");
+            throw new UsageError("--command accepts one shell string; argv arrays require manual migration.", "INVALID_FLAG_VALUE");
         }
         obj.run = input.command;
     }
     if (input.name)
         obj.name = input.name;
-    obj.akm = {
-        schedule: input.schedule,
-        enabled: input.enabled,
-        ...(input.description !== undefined ? { description: input.description } : {}),
-        ...(input.when_to_use !== undefined ? { when_to_use: input.when_to_use } : {}),
-        ...(input.tags && input.tags.length > 0 ? { tags: input.tags } : {}),
-        ...(input.engine !== undefined ? { engine: input.engine } : {}),
-        ...(input.model !== undefined ? { model: input.model } : {}),
-        ...(input.timeoutMs !== undefined ? { timeout: input.timeoutMs } : {}),
-    };
+    if (input.description !== undefined)
+        obj.description = input.description;
+    if (input.when_to_use !== undefined)
+        obj.when_to_use = input.when_to_use;
+    if (input.tags && input.tags.length > 0)
+        obj.tags = input.tags;
+    if (input.engine !== undefined)
+        obj.engine = input.engine;
+    if (input.model !== undefined)
+        obj.model = input.model;
+    if (input.timeoutMs !== undefined)
+        obj.timeout = input.timeoutMs;
+    // Task source v4's `enabled` is per schedule-binding, not document-level
+    // (P4-N6, row B-21): `--disabled` writes a one-entry schedule[] list
+    // carrying `enabled: false` rather than the v3 `akm.enabled: false` flag.
+    // `TasksAddInput.schedule`/the `add` CLI's `--schedule` are both still
+    // required, so the "no schedule to disable" usage error B-21 also
+    // describes is unreachable through this call site today; the check below
+    // still guards `renderTaskYaml` itself against ever being called with an
+    // empty schedule string.
+    if (input.schedule.length === 0) {
+        if (!input.enabled) {
+            throw new UsageError("--disabled requires --schedule; a task with no schedule is already manual-only.");
+        }
+    }
+    else {
+        obj.schedule = input.enabled ? input.schedule : [{ cron: input.schedule, enabled: false }];
+    }
     return yamlStringify(obj);
 }
 function assertInlineTaskPrompt(input) {
@@ -1036,38 +1170,116 @@ function parseJsonObjectArg(raw) {
     return parsed;
 }
 /**
- * Toggle the v3 `akm.enabled:` value in a task YAML file without a full
- * parse/render round-trip (which would reformat the file). Appends the key
- * if absent.
+ * Toggle a task source v4 YAML file's `enabled` state without a full
+ * parse/render round-trip (which would reformat the file). Task source v4
+ * has no document-level `enabled` flag — it lives on each `schedule[]` entry
+ * instead (D2-N5, P4-N6) — so this walks the top-level `schedule:` block,
+ * finds every list entry in it (each line starting with `-` at the block's
+ * item indent), and toggles that entry's own `enabled:` key, the closest v4
+ * equivalent of v3's single document-level flag broadcasting to every
+ * trigger. Each entry is handled independently — one entry already carrying
+ * `enabled:` and a sibling entry with no such key (D2-N3's `schedule[i]`
+ * shape: `{cron, enabled?, inputs?}`) toggles the first and inserts into the
+ * second, rather than one entry's existing key short-circuiting the other's
+ * insertion.
+ *
+ * A bare string-shorthand schedule (`schedule: "0 9 * * *"`) has nowhere for
+ * `enabled:` to live and is rewritten to the one-entry list form. A list
+ * entry with no explicit `enabled:` key (defaulting to `true` at parse) gets
+ * one inserted rather than being silently left unaffected. A document with
+ * no `schedule:` key at all throws — there is no trigger to enable or
+ * disable (mirrors `renderTaskYaml`'s `--disabled`-with-no-`--schedule`
+ * usage error, row B-21).
+ *
+ * Each entry's own key indent is taken from its `-` line (the indent before
+ * `-`, plus two spaces for the conventional single space after it), so a
+ * nested mapping inside an entry — e.g. `schedule[i].inputs` — sits deeper
+ * and is never mistaken for the entry's own `enabled:` key.
  *
  * Preserves inline comments (e.g. `enabled: true # important`) and uses
  * case-sensitive matching (YAML keys are case-sensitive).
  */
 export function setEnabledInYaml(yaml, enabled) {
     const lines = yaml.replace(/\r\n/g, "\n").split("\n");
-    const akmLine = lines.findIndex((line) => /^akm:\s*(?:#.*)?$/.test(line));
-    if (akmLine < 0)
-        return `${yaml.trimEnd()}\nakm:\n  enabled: ${enabled}\n`;
-    let insertAt = akmLine + 1;
-    for (let index = akmLine + 1; index < lines.length; index += 1) {
+    const scalarLine = lines.findIndex((line) => /^schedule:[ \t]+\S/.test(line));
+    if (scalarLine >= 0) {
+        const line = lines[scalarLine];
+        const match = line?.match(/^schedule:[ \t]+([^\r\n]+?)[ \t]*(#[^\r\n]*)?$/);
+        const cron = match?.[1] ?? "";
+        const comment = match?.[2] ? ` ${match[2]}` : "";
+        lines.splice(scalarLine, 1, "schedule:", `  - cron: ${cron}${comment}`, `    enabled: ${enabled}`);
+        return `${lines.join("\n").trimEnd()}\n`;
+    }
+    const blockLine = lines.findIndex((line) => /^schedule:\s*(?:#.*)?$/.test(line));
+    if (blockLine < 0) {
+        throw new UsageError("Task source v4 must declare a schedule before its enabled state can be toggled.");
+    }
+    // Find the block's extent and every top-level list item (`-`) within it.
+    // Only items at the *first* item's own indent count as entries — anything
+    // deeper belongs to a nested mapping/list inside an entry (e.g. an array
+    // input under `inputs:`) and must not be treated as a sibling entry.
+    let blockEnd = lines.length;
+    const itemStarts = [];
+    let topIndent = null;
+    for (let index = blockLine + 1; index < lines.length; index += 1) {
         const line = lines[index];
-        if (line === undefined)
+        if (line === undefined) {
+            blockEnd = index;
             break;
-        if (line !== "" && !/^[ \t]/.test(line))
+        }
+        if (line !== "" && !/^[ \t]/.test(line)) {
+            blockEnd = index;
             break;
-        insertAt = index + 1;
-        const match = line.match(/^([ \t]+enabled:\s*)([^\s#\r\n][^\r\n]*?)(\s*(?:#[^\r\n]*))?$/);
-        if (match) {
-            lines[index] = `${match[1]}${enabled}${match[3] ?? ""}`;
-            return `${lines.join("\n").trimEnd()}\n`;
         }
-        const bare = line.match(/^([ \t]+enabled:)\s*$/);
-        if (bare) {
-            lines[index] = `${bare[1]} ${enabled}`;
-            return `${lines.join("\n").trimEnd()}\n`;
+        const itemMatch = line.match(/^([ \t]*)-(?=[ \t]|$)/);
+        if (itemMatch) {
+            const itemIndent = itemMatch[1] ?? "";
+            if (topIndent === null)
+                topIndent = itemIndent;
+            if (itemIndent === topIndent)
+                itemStarts.push(index);
+        }
+    }
+    if (itemStarts.length === 0) {
+        throw new UsageError("Task source v4's schedule: block has no entries to toggle enabled on.");
+    }
+    // Walk entries back-to-front: inserting a missing `enabled:` line shifts
+    // every later line index by one, but never touches `itemStarts[j]` for
+    // j <= i (an insertion for entry i lands at `itemStarts[i] + 1`, which is
+    // at or after entry i's own start), so already-computed start/end bounds
+    // for entries processed later in this loop (earlier in the list) stay valid.
+    for (let i = itemStarts.length - 1; i >= 0; i -= 1) {
+        const start = itemStarts[i];
+        const end = i + 1 < itemStarts.length ? itemStarts[i + 1] : blockEnd;
+        const dashLead = lines[start]?.match(/^([ \t]*)-/)?.[1] ?? "";
+        const keyIndent = `${dashLead}  `;
+        let found = false;
+        for (let index = start; index < end; index += 1) {
+            const line = lines[index];
+            if (line === undefined)
+                continue;
+            const isStart = index === start;
+            const prefixMatch = isStart ? line.match(/^([ \t]*-[ \t]*)(.*)$/) : line.match(/^([ \t]*)(.*)$/);
+            const prefix = prefixMatch?.[1] ?? "";
+            const content = prefixMatch?.[2] ?? "";
+            if (prefix.length !== keyIndent.length)
+                continue;
+            const withValue = content.match(/^(enabled:[ \t]*)([^\s#\r\n][^\r\n]*?)([ \t]*(?:#[^\r\n]*))?$/);
+            if (withValue) {
+                lines[index] = `${prefix}${withValue[1]}${enabled}${withValue[3] ?? ""}`;
+                found = true;
+                continue;
+            }
+            const bare = content.match(/^(enabled:)[ \t]*$/);
+            if (bare) {
+                lines[index] = `${prefix}${bare[1]} ${enabled}`;
+                found = true;
+            }
+        }
+        if (!found) {
+            lines.splice(start + 1, 0, `${keyIndent}enabled: ${enabled}`);
         }
     }
-    lines.splice(insertAt, 0, `  enabled: ${enabled}`);
     return `${lines.join("\n").trimEnd()}\n`;
 }
 // Re-exported so tests can verify the validator path directly.
@@ -1096,7 +1308,8 @@ export function parseTaskRef(input) {
     }
     return { id: normaliseTaskId(trimmed) };
 }
-function taskIdForAdapter(parsedId, adapterId) {
+/** Exported for `src/commands/tasks/explain.ts` — see {@link resolveTaskReadBundle}'s header. */
+export function taskIdForAdapter(parsedId, adapterId) {
     if (adapterId === "akm-task")
         return normaliseTaskConceptId(parsedId);
     if (adapterId === "akm") {

package/dist/commands/workflow/plan.js

@@ -0,0 +1,159 @@
+// 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/.
+/**
+ * `akm workflow plan <ref>` — compile + freeze WITHOUT publishing (P3b, spec
+ * docs/plans/specs/p3b-child-executor.md §4.6). Zero durable writes, zero
+ * usage/event rows (row B-48): this module calls exactly the same two
+ * functions `startWorkflowRun` does to reach a frozen plan
+ * (`loadWorkflowAsset`, `compileResolveFreezeWorkflowV4`) and NOTHING else —
+ * never `publishWorkflowRunV4`, `startWorkflowRun`, `warn()`, `appendEvent`,
+ * or `akmIndex`.
+ *
+ * SECRET-FREE, by construction (§4.6's closed print list): a resolved
+ * reference VALUE is never printed (references resolve at pre-attempt, not
+ * here); a `literal` **environment** binding's value is never printed (only
+ * `environment[].kind`/`.name`, and an `env-ref`'s `.ref`/`.keys`/
+ * `.secretNames` — all NAMES); `request.command.content`,
+ * `request.persona`, `request.conversation`, `request.runtime.environment`,
+ * and a script target's `bytesBase64` are never read at all.
+ */
+import path from "node:path";
+import { loadConfig } from "../../core/config/config.js";
+import { lowerResolvedExecutionRequest } from "../../integrations/agent/execution-lowering.js";
+import { collectWorkflowWarnings } from "../../workflows/ir/compile.js";
+import { compileResolveFreezeWorkflowV4 } from "../../workflows/ir/freeze-v4.js";
+import { computePlanHash } from "../../workflows/ir/plan-hash.js";
+import { loadWorkflowAsset } from "../../workflows/runtime/workflow-asset-loader.js";
+/** The step's dispatch unit — the map template for a fan-out, else the root unit. Undefined for a route step. */
+function stepUnit(step) {
+    const root = step.root;
+    if (!root)
+        return undefined;
+    return root.kind === "map" ? root.template : root;
+}
+function projectEnvironmentBinding(binding) {
+    if (binding.kind === "env-ref") {
+        return { kind: binding.kind, ref: binding.ref, keys: binding.keys, secretNames: binding.secretNames };
+    }
+    // literal / pass-through: kind + name only — a literal's VALUE is never printed.
+    return { kind: binding.kind, name: binding.name };
+}
+function projectInputBinding(binding) {
+    return binding.kind === "literal"
+        ? { name: binding.name, kind: "literal", value: binding.value }
+        : { name: binding.name, kind: "reference", from: binding.from };
+}
+function childExportedOutputNames(frozenPlan) {
+    return frozenPlan.outputs ? Object.keys(frozenPlan.outputs) : ["runId", "status"];
+}
+/**
+ * A `child-workflow` target's `expansion`. Recurses into the embedded
+ * plan's own steps in the identical shape (§4.6) — `sourceStepsById` is
+ * omitted for the recursive call because a nested child's own authored
+ * source is not available here (only its already-frozen plan is), so a
+ * task-wrapped step nested inside a child conservatively reports `via:
+ * "direct"` rather than guessing at its authoring surface.
+ */
+function childExpansion(target) {
+    return {
+        via: "child",
+        childRef: target.ref,
+        childPlanHash: target.planHash,
+        childVia: target.via,
+        ...(target.taskRef !== undefined ? { childTaskRef: target.taskRef } : {}),
+        childOutputs: childExportedOutputNames(target.frozenPlan),
+        steps: target.frozenPlan.steps.map((step, index) => projectStep(step, index, undefined)),
+    };
+}
+/** The task/child expansion boundary for one step (§4.6). */
+function stepExpansion(step, frozenTarget, sourceStepsById) {
+    if (frozenTarget?.kind === "child-workflow")
+        return childExpansion(frozenTarget);
+    const uses = sourceStepsById?.get(step.stepId)?.uses;
+    if (uses?.startsWith("tasks/"))
+        return { via: "task", taskRef: uses };
+    return { via: "direct" };
+}
+function projectStep(step, sequenceIndex, sourceStepsById) {
+    const unit = stepUnit(step);
+    const frozenTarget = unit?.frozenTarget;
+    const kind = step.route ? "route" : step.root?.kind === "map" ? "map" : "unit";
+    const inputBindings = frozenTarget?.inputBindings;
+    return {
+        stepId: step.stepId,
+        sequenceIndex,
+        kind,
+        targetKind: frozenTarget?.kind ?? null,
+        ...(step.root?.kind === "map" ? { concurrency: step.root.concurrency } : {}),
+        inputs: unit?.inputs ?? [],
+        environment: (unit?.environment ?? []).map(projectEnvironmentBinding),
+        ...(inputBindings && inputBindings.length > 0 ? { inputBindings: inputBindings.map(projectInputBinding) } : {}),
+        gate: {
+            criteria: step.gate.criteria,
+            maxLoops: step.gate.maxLoops,
+            judgeEngine: step.gate.frozenJudge ? step.gate.frozenJudge.request.engine.name : null,
+        },
+        ...(step.outputSchema !== undefined ? { outputSchema: step.outputSchema } : {}),
+        expansion: stepExpansion(step, frozenTarget, sourceStepsById),
+    };
+}
+/**
+ * Every `command`-kind frozen target's lowering notices, recomputed PURELY
+ * from its own already-frozen `request` (the identical computation
+ * `freeze/targets/command.ts`'s `commandResult` already performs at freeze
+ * time and discards) — walked over the whole plan, including gate judges and
+ * recursively into every embedded child plan. Read-only: `lowerResolvedExecutionRequest`
+ * takes no config it could write through and dispatches nothing.
+ */
+function collectLoweringNotices(plan, config) {
+    const notices = [];
+    const lower = (request) => {
+        notices.push(...lowerResolvedExecutionRequest(request, config).notices);
+    };
+    for (const step of plan.steps) {
+        const unit = stepUnit(step);
+        if (unit) {
+            if (unit.frozenTarget.kind === "command")
+                lower(unit.frozenTarget.request);
+            else if (unit.frozenTarget.kind === "child-workflow")
+                notices.push(...collectLoweringNotices(unit.frozenTarget.frozenPlan, config));
+        }
+        if (step.gate.frozenJudge)
+            lower(step.gate.frozenJudge.request);
+    }
+    return notices;
+}
+function relativeSourceReadSet(plan) {
+    return plan.sourceReadSet.map((snapshot) => snapshot.identity.file);
+}
+/**
+ * Compile + freeze `ref` and project the frozen plan into the read-only
+ * `akm workflow plan` envelope. Never publishes, never writes, never warns.
+ */
+export async function akmWorkflowPlan(ref) {
+    const asset = await loadWorkflowAsset(ref);
+    const config = loadConfig();
+    const frozen = await compileResolveFreezeWorkflowV4(asset, config);
+    const plan = frozen.plan;
+    const sourceStepsById = new Map((asset.sourceIr.jobs[0]?.steps ?? []).map((step) => [step.id, step]));
+    const sourceFormat = path.extname(asset.path).toLowerCase() === ".md" ? "markdown" : "github-yaml";
+    return {
+        ok: true,
+        ref: asset.ref,
+        title: asset.title,
+        sourceFormat,
+        sourcePath: asset.path,
+        irVersion: plan.irVersion,
+        planHash: computePlanHash(plan),
+        published: false,
+        execution: plan.execution,
+        ...(plan.budget ? { budget: plan.budget } : {}),
+        ...(plan.params ? { params: plan.params } : {}),
+        ...(plan.outputs ? { outputs: plan.outputs } : {}),
+        steps: plan.steps.map((step, index) => projectStep(step, index, sourceStepsById)),
+        sourceReadSet: relativeSourceReadSet(plan),
+        notices: collectLoweringNotices(plan, config),
+        warnings: collectWorkflowWarnings(asset.sourceIr).map((warning) => warning.message),
+    };
+}