akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/commands/workflow-cli.js

@@ -7,15 +7,22 @@
  * `create --print` emits Markdown; execution accepts peer `.md` and
  * GitHub-shaped `.yml` workflow sources. Validate with `akm lint --type workflows`.
  */
+import { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
+import { getOutputMode } from "../output/context.js";
+import { renderGenericText } from "../output/generic-render.js";
+import { deliverRendered } from "../output/html-render.js";
+import { shapeForCommand } from "../output/shapes.js";
+import { formatPlain } from "../output/text.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
 import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
+import { akmWorkflowPlan } from "./workflow/plan.js";
 const workflowStatusCommand = defineJsonCommand({
     meta: {
         name: "status",
@@ -63,9 +70,18 @@ const workflowListCommand = defineJsonCommand({
     args: {
         ref: { type: "string", description: "Filter to one workflow ref" },
         active: { type: "boolean", description: "Only show active runs", default: false },
+        children: {
+            type: "boolean",
+            description: "Also include child workflow runs (hidden by default, P3b)",
+            default: false,
+        },
     },
     async run({ args }) {
-        const result = await listWorkflowRuns({ workflowRef: args.ref, activeOnly: args.active });
+        const result = await listWorkflowRuns({
+            workflowRef: args.ref,
+            activeOnly: args.active,
+            includeChildren: args.children,
+        });
         output("workflow-list", result);
     },
 });
@@ -131,7 +147,9 @@ const workflowCreateCommand = defineJsonCommand({
         // Index the newly-written workflow so `akm workflow run` can resolve
         // a workflowEntryId without requiring an explicit `akm index` call
         // first. Uses the same incremental index path that `akm add` uses.
-        await akmIndex({ stashDir: result.stashDir });
+        // `result.bundleDir` — the indexer's own `IndexOptions.stashDir` field
+        // name is unchanged (indexer vocabulary is out of scope, P4 row B-50).
+        await akmIndex({ stashDir: result.bundleDir });
         output("workflow-create", { ok: true, ...result });
     },
 });
@@ -286,6 +304,79 @@ function parseWorkflowTimeout(raw) {
     }
     return timeoutMs;
 }
+// P3b Lane B (spec docs/plans/specs/p3b-child-executor.md §4.6): read-only
+// compile+freeze introspection — zero durable writes, zero usage/event rows
+// (row B-48). `--json` is deliberately NOT a flag anywhere in this CLI
+// (B-N9); the global `--format json` is spliced on by `defineJsonCommand`.
+const workflowPlanCommand = defineJsonCommand({
+    meta: {
+        name: "plan",
+        description: "Compile and freeze a workflow WITHOUT publishing it: the canonical step graph, per-step frozen target " +
+            "kinds, task/child expansion, input bindings, source read set, and lowering notices. Zero durable writes.",
+    },
+    args: {
+        ref: { type: "positional", description: "Workflow ref (workflows/<name>)", required: true },
+    },
+    async run({ args }) {
+        const result = await akmWorkflowPlan(args.ref);
+        // B-46/B-57: `akm workflow plan` is read-only introspection whose UNMARKED
+        // default is a human summary — `--format json` (B-N9) is the opt-in for
+        // the full structure, the mirror image of every other verb's json-by-
+        // default (DEFAULT_CONFIG.output.format).
+        //
+        // Detecting "the caller named no format at all" MUST NOT read
+        // `args.format` (code-review round 4, finding 3 / Review log R3):
+        // citty's one-parse rule (GLOBAL_OUTPUT_ARGS's own doc comment, "no
+        // command body may read these args") isn't just style here — reading it
+        // is actively wrong. citty parses each command level against only that
+        // level's own remaining argv, so a GLOBAL, pre-subcommand `--format json`
+        // (e.g. `akm --format json workflow plan <ref>`) is consumed by the ROOT
+        // command's own declared `format` arg before the `workflow`/`plan`
+        // subcommand tokens are even resolved — this LEAF's `args.format` reads
+        // `undefined` in exactly that case too, indistinguishable from "no
+        // format was named anywhere". Reproduced live: that invocation printed
+        // the human TEXT summary at exit 0 even though `getOutputMode().format`
+        // was already `"json"` (the control, `akm --format json workflow list`,
+        // correctly emitted JSON — only this leaf's own arg-read was wrong).
+        // Detect it instead off the process-wide invocation singleton
+        // (`getParsedInvocation`, src/cli/invocation.ts) — the same canonical,
+        // position-independent argv parse `src/cli.ts` mints ONCE at startup
+        // (`setParsedInvocation`, immediately before `initOutputMode` builds the
+        // `getOutputMode()` singleton from that identical argv), so this agrees
+        // with `getOutputMode()` regardless of where `--format` appeared. A bare
+        // `process.argv` read is reserved for `src/cli.ts`/`cli/invocation.ts`
+        // themselves (`lint-process-argv.ts`); every other module reads through
+        // this singleton instead. When explicit, this defers to the normal
+        // `output()` path (json/yaml/text/md/html/jsonl, `--output <path>`)
+        // unchanged; when absent, it reproduces `output()`'s OWN "text" branch
+        // verbatim (same shape/detail projection, same registered-formatter-or-
+        // generic-fallback, same `--output <path>` handling) without touching
+        // the shared dispatcher other commands rely on.
+        //
+        // "No format named anywhere" also has to check the RESOLVED mode, not
+        // just argv: `getOutputMode().format` already folds a persisted
+        // `output.format` config default in ahead of the hardcoded "json"
+        // fallback (`resolveOutputMode`, src/output/context.ts — argv ?? config
+        // default ?? "json"). A user who has configured e.g. `output.format:
+        // "yaml"` gets yaml from every other command with no `--format` on the
+        // line; `workflow plan` must honor that too instead of forcing its
+        // human-text branch over a real persisted default. A resolved format of
+        // exactly "json" is deliberately left on the text branch below: it's
+        // indistinguishable from "nothing configured" (DEFAULT_CONFIG.output.format
+        // is also "json" — OutputConfigSchema's `format` carries no independent
+        // zod default, so the merge is the only source), and collapsing that case
+        // onto the JSON envelope would erase the documented unmarked-default text
+        // summary for the overwhelmingly common "user configured nothing" case.
+        const mode = getOutputMode();
+        if (getParsedInvocation().getFlagValue("--format") === undefined && mode.format === "json") {
+            const shaped = shapeForCommand("workflow-plan", result, mode.detail, mode.shape);
+            const plain = formatPlain("workflow-plan", shaped, mode.detail);
+            deliverRendered(plain ?? renderGenericText("workflow-plan", shaped), mode.outputPath);
+            return;
+        }
+        output("workflow-plan", result);
+    },
+});
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
         name: "abandon",
@@ -324,6 +415,7 @@ export const workflowCommand = defineGroupCommand({
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
         run: workflowRunCommand,
+        plan: workflowPlanCommand,
     },
     // No `defaultRun`: bare `akm workflow` is a usage error (exit 2), the
     // canonical bare-group behavior — owner ruling 12. Run `akm workflow list

package/dist/core/activation-policy.js

@@ -27,22 +27,12 @@ export function decideDangerousKeyInstall(input) {
         return "allow";
     return input.allowInsecure ? "warn-allow" : "gate";
 }
-// ── Rule 3: task activation (tasks/runner.ts) ────────────────────────────────
-/**
- * Whether a scheduler-generated task invocation must be skipped because the
- * task is not activated (its `enabled:` is false). Manual (non-scheduled) runs
- * are always dispatched — installing a task grants nothing until enabled, but
- * the operator may still run it by hand for catch-up / testing. See rule 3.
- */
-export function shouldSkipUnactivatedTask(input) {
-    return !input.enabled && input.scheduled;
-}
-// ── Rule 4: write activation (search-source.ts, installations.ts) ────────────
+// ── Rule 3: write activation (search-source.ts, installations.ts) ────────────
 /**
  * Whether a resolved source is write-activated. Only the primary stash and
  * sources explicitly marked `writable: true` are writable; registry-cached
  * (installed, read-only) sources are never written in place because
- * `akm update` overwrites them. See rule 4 above.
+ * `akm update` overwrites them. See rule 3 above.
  */
 export function isSourceWriteActivated(source) {
     return source.writable === true;

package/dist/core/adapter/adapters/akm-lint.js

@@ -52,7 +52,8 @@
  */
 import path from "node:path";
 import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
-import { parseTaskV3Yaml, taskV3SourceErrorDetail } from "../../../tasks/source-v3.js";
+import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
+import { taskSourceErrorDetail } from "../../../tasks/source-v3.js";
 import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
 import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
 import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
@@ -271,13 +272,15 @@ export function factDiagnostics(relPath, data) {
     return [];
 }
 /**
- * Task validation has one semantic owner: the strict task-v3 source parser.
+ * Task validation has one semantic owner: the version-routed task source
+ * parser (spec docs/plans/specs/p2a-task-source-v4.md §3.6) — `version: 3`
+ * through the strict task-v3 grammar, `version: 4` through task source v4.
  * Keeping raw YAML at this boundary preserves duplicate-key, alias/tag,
  * source-location, descriptor, resource-bound, and migration-hint behavior.
  */
 export function taskDiagnostics(relPath, raw, workspaceRoot) {
     try {
-        parseTaskV3Yaml({
+        parseTaskSource({
             filePath: relPath,
             yaml: raw,
             ...(workspaceRoot ? { workspaceRoot } : {}),
@@ -289,7 +292,7 @@ export function taskDiagnostics(relPath, raw, workspaceRoot) {
             {
                 file: relPath,
                 issue: "invalid-task-yaml",
-                detail: taskV3SourceErrorDetail(cause),
+                detail: taskSourceErrorDetail(cause),
                 fixed: false,
             },
         ];

package/dist/core/adapter/adapters/akm-metadata.js

@@ -55,7 +55,7 @@
  * distinction never triggers.
  */
 import { scanEnvKeyNames } from "../../../commands/env/env.js";
-import { parseTaskV3Yaml } from "../../../tasks/source-v3.js";
+import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { compileWorkflowSource } from "../../../workflows/source-ir/compile.js";
 import { sourceStepInstructions } from "../../../workflows/source-ir/program.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
@@ -229,25 +229,37 @@ export function foldRecognizedMetadata(rendererName, file) {
         case "task-yaml": {
             out.tags = Array.from(new Set([...(out.tags ?? []), "task", "scheduled"]));
             try {
-                const task = parseTaskV3Yaml({ yaml: file.content(), filePath: file.absPath, workspaceRoot: file.stashRoot });
+                const parsed = parseTaskSource({ yaml: file.content(), filePath: file.absPath, workspaceRoot: file.stashRoot });
+                const v4 = parsed.v4;
+                const target = v4.target;
                 const hints = new Set();
-                for (const binding of task.triggers.schedules)
+                for (const binding of v4.schedule)
                     hints.add(`schedule:${binding.cron}`);
-                if (task.target.kind === "uses") {
-                    if (task.target.uses.kind === "workflow")
-                        hints.add(`workflow:${task.target.uses.ref}`);
-                    else if (task.target.uses.kind === "command")
-                        hints.add(`prompt:${task.target.uses.ref}`);
-                    else if (task.target.command?.kind === "inline")
-                        hints.add(`prompt:${task.target.command.content}`);
-                    else if (task.target.command?.kind === "stored")
-                        hints.add(`prompt:${task.target.command.ref}`);
+                if (target.kind === "uses") {
+                    if (target.uses.kind === "workflow")
+                        hints.add(`workflow:${target.uses.ref}`);
+                    else if (target.uses.kind === "command")
+                        hints.add(`prompt:${target.uses.ref}`);
+                    else if (target.command?.kind === "inline")
+                        hints.add(`prompt:${target.command.content}`);
+                    else if (target.command?.kind === "stored")
+                        hints.add(`prompt:${target.command.ref}`);
                     else
-                        hints.add(`uses:${task.target.uses.ref}`);
+                        hints.add(`uses:${target.uses.ref}`);
                 }
                 else {
-                    hints.add(`run:${task.target.run}`);
+                    hints.add(`run:${target.run}`);
                 }
+                if (v4.description && !out.description) {
+                    out.description = v4.description;
+                    out.source = "task-source";
+                    out.confidence = 0.9;
+                }
+                if (v4.tags && v4.tags.length > 0) {
+                    out.tags = Array.from(new Set([...(out.tags ?? []), ...v4.tags]));
+                }
+                if (v4.when_to_use)
+                    hints.add(`when_to_use:${v4.when_to_use}`);
                 finalizeHints(out, hints);
             }
             catch {

package/dist/core/adapter/adapters/akm-task-adapter.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/.
 /**
- * The `akm-task` adapter for strict task-v3 `.yml` sources.
+ * The `akm-task` adapter for task `.yml` sources.
  *
  * A native akm task-YAML bundle (spec §6/§7). A `.yml` file derives
  * `type: task`; conceptId strips the `.yml` extension. Tasks are AKM-native
@@ -16,11 +16,13 @@
  *
  * ── validate (spec §6 task validation column) ──
  *
- * Validation enters the canonical task-v3 source parser. That parser owns the
- * closed key sets, executable-selector XOR, scheduling-source XOR, hostile
- * YAML policy, trigger classification, built-in action validation, bounds,
- * and physical `working-directory` containment. The adapter only translates a
- * parser failure into the format-family diagnostic shape.
+ * Validation enters the canonical task source parser (`parseTaskSource`,
+ * task source v4 only as of P4 — a `version: 3` or `version: 2` document now
+ * fails closed with `TASK_SCHEMA_VERSION_UNSUPPORTED`). That parser owns the
+ * closed key sets, the executable-selector XOR, hostile YAML policy, the
+ * `akm/command` builtin, bounds, and physical `working-directory`
+ * containment. The adapter only translates a parser failure into the
+ * format-family diagnostic shape.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -28,7 +30,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseTaskV3Yaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskV3SourceErrorDetail, } from "../../../tasks/source-v3.js";
+import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
+import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskSourceErrorDetail, } from "../../../tasks/source-v3.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
@@ -83,13 +86,13 @@ async function validate(c, changes, ctx) {
             continue;
         }
         try {
-            parseTaskV3Yaml({ yaml: raw, filePath: relPath, workspaceRoot: c.root });
+            parseTaskSource({ yaml: raw, filePath: relPath, workspaceRoot: c.root });
         }
         catch (cause) {
             diagnostics.push({
                 file: relPath,
                 issue: "invalid-task-yaml",
-                detail: taskV3SourceErrorDetail(cause),
+                detail: taskSourceErrorDetail(cause),
                 fixed: false,
             });
         }
@@ -146,7 +149,7 @@ export const akmTaskAdapter = {
                 continue;
             }
             try {
-                parseTaskV3Yaml({ yaml: raw, filePath: entry.name, workspaceRoot: root });
+                parseTaskSource({ yaml: raw, filePath: entry.name, workspaceRoot: root });
                 return true;
             }
             catch {

package/dist/core/errors.js

@@ -19,6 +19,20 @@ const CONFIG_HINTS = {
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
     EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
 };
+// Code-review finding: COMPOSITION_INVALID covers several unrelated causes
+// (a rejected with:, a multi-job source, a composition cycle/depth/size
+// violation, an invalid child-output reference). USAGE_HINTS below carries
+// only the with:-rejection text — accurate for every with:-rejection throw
+// site (none of which pass an explicit constructor hint), but wrong for the
+// others. Those throw sites pass their OWN explicit hint (the constructor's
+// 3rd argument overrides USAGE_HINTS, per errors-usage-hints.test.ts's
+// "explicit constructor hint still overrides the USAGE_HINTS default").
+// Multi-job rejection is thrown from 5 separate call sites across
+// src/tasks/prepare/prepare-support.ts and src/workflows/**, so its hint is
+// centralized here as the one shared string all 5 import, rather than
+// duplicated at each site and risking drift.
+export const COMPOSITION_INVALID_MULTI_JOB_HINT = "AKM workflows support exactly one job per source, with no needs: between jobs. Split the extra job(s) into " +
+    "their own workflow file, and compose them with uses: workflows/<ref> instead.";
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {
     INVALID_FLAG_VALUE: "Run `akm <command> --help` to see accepted values.",
@@ -32,6 +46,37 @@ const USAGE_HINTS = {
     MISSING_REQUIRED_ARGUMENT: "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.",
     UNKNOWN_COMMAND: "Run `akm --help` to see available commands.",
     UNKNOWN_FLAG: "Run the command with `--help` to see its accepted flags.",
+    // P2b (docs/plans/specs/p2b-input-bindings.md §1.7 A-N5, §7 F-A3): the
+    // "arrives in a later 0.9.x release" promise is gone now that task-call
+    // inputs are implemented. Names the two real rejection causes instead:
+    // (1) a task target that declares no inputs: at all, (2) commands/<ref> /
+    // scripts/<ref>, which are never binding surfaces. F-A3 authorizes this
+    // edit and the matching pinned-string update in
+    // tests/core/errors-usage-hints.test.ts in the same commit.
+    //
+    // Code-review finding: this default is reached ONLY by with:-rejection
+    // throw sites (the ones above, plus task.ts's noDeclaredInputsError and
+    // resolve-steps.ts's rejectNonTaskBindingWith) — every other
+    // COMPOSITION_INVALID throw site (multi-job source, composition
+    // cycle/depth/size, invalid child-output reference, an env: on a
+    // composing step) passes its own explicit constructor hint instead of
+    // falling through to this text, so this stays scoped and accurate rather
+    // than generalized into something vaguer.
+    COMPOSITION_INVALID: "Remove the with: block, or target a tasks/<ref> whose source declares inputs: — commands/<ref> and scripts/<ref> steps are not binding surfaces.",
+    TASK_SOURCE_INVALID: "Fix the task source at the reported path and line, then re-run.",
+    TARGET_REF_INVALID: "Targets are canonical asset refs: `commands/review`, `scripts/build.sh`, `tasks/nightly`, `workflows/release`.",
+    // P4 (docs/plans/specs/p4-deletions-closeout.md §4.1, row B-53, R-R5): the
+    // original hint named `akm workflow validate`, a verb that was never
+    // implemented. Points at the two verbs that actually inspect a workflow
+    // source without executing it.
+    WORKFLOW_SOURCE_INVALID: "Run `akm lint` to see the failing source location, or `akm workflow plan <ref>` to compile it without writing.",
+    INPUT_BINDING_INVALID: "Check the step's with: keys against the target's declared inputs.",
+    TASK_TARGET_UNSUPPORTED: "Task definitions support command, script, workflow, and shell (run:) targets; akm/command is layered by callers.",
+    // P3a (docs/plans/specs/p3a-plan-v5-child-freeze.md §3.2, A-N2): the
+    // complete-or-abandon policy for a stored pre-irVersion-5 run.
+    WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — pre-0.9.2 frozen plans are not re-executable.",
+    // P3b (docs/plans/specs/p3b-child-executor.md §4.3).
+    WORKFLOW_OUTPUT_INVALID: "Check each `outputs:` entry's `from:` against the step artifact it names, and its `schema:` against the value that step actually promotes.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

package/dist/core/json-schema.js

@@ -62,10 +62,10 @@
 const MAX_DEFINITION_DEPTH = 64;
 /** Total (schema node × value node) visits one {@link validateJsonSchemaSubset} call may make. */
 const MAX_VALIDATION_NODES = 100_000;
-export function validateJsonSchemaSubset(value, schema) {
+export function validateJsonSchemaSubset(value, schema, options) {
     const errors = [];
     const budget = { nodes: MAX_VALIDATION_NODES };
-    validateNode(value, schema, "$", { errors, budget, depth: 0 });
+    validateNode(value, schema, "$", { errors, budget, depth: 0, redactValues: options?.redactValues ?? false });
     if (budget.nodes < 0) {
         errors.push(`$: schema evaluation exceeded the limit of ${MAX_VALIDATION_NODES} checks and was stopped`);
     }
@@ -390,7 +390,13 @@ function validateNode(value, schema, path, ctx) {
     if (Array.isArray(schema.enum) && schema.enum.length > 0) {
         const allowed = schema.enum;
         if (!allowed.some((candidate) => candidate === value)) {
-            errors.push(`${path}: value ${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`);
+            // Never echo the supplied value when redacting: enum-constrained inputs
+            // can carry credentials, and this detail lands in stderr envelopes that
+            // get pasted into CI logs. The allowed list is safe — it comes from the
+            // author-declared schema, not from user-supplied data.
+            errors.push(ctx.redactValues
+                ? `${path}: value is not one of ${JSON.stringify(allowed)}`
+                : `${path}: value ${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`);
             return;
         }
     }
@@ -409,10 +415,14 @@ function validateNode(value, schema, path, ctx) {
     }
     if ((actual === "number" || actual === "integer") && typeof value === "number") {
         if (typeof schema.minimum === "number" && value < schema.minimum) {
-            errors.push(`${path}: ${value} is below minimum ${schema.minimum}`);
+            errors.push(ctx.redactValues
+                ? `${path}: value is below minimum ${schema.minimum}`
+                : `${path}: ${value} is below minimum ${schema.minimum}`);
         }
         if (typeof schema.maximum === "number" && value > schema.maximum) {
-            errors.push(`${path}: ${value} is above maximum ${schema.maximum}`);
+            errors.push(ctx.redactValues
+                ? `${path}: value is above maximum ${schema.maximum}`
+                : `${path}: ${value} is above maximum ${schema.maximum}`);
         }
         return;
     }

package/dist/core/state/migrations.js

@@ -33,6 +33,8 @@ export const STATE_MIGRATION_SAFETY_BY_ID = Object.freeze({
     "020-three-db-cutover": "additive",
     "021-asset-state-missing-since": "additive",
     "022-workflow-unit-attempts": "additive",
+    "023-child-workflow-runs": "additive",
+    "024-workflow-run-outputs": "additive",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1022,6 +1024,61 @@ export const STATE_MIGRATIONS = [
         ON workflow_run_unit_attempts(run_id, status, claim_expires_at);
     `,
     },
+    // ── Migration 023 — child workflow run parentage (P3a) ────────────────────
+    //
+    // Adds the columns and partial unique index `publishChildWorkflowRun`
+    // (src/storage/repositories/workflow-runs-repository.ts) needs to record a
+    // durable child workflow run under the parent unit that spawned it, and to
+    // make that publication idempotent per invocation
+    // (docs/plans/specs/p3a-plan-v5-child-freeze.md §5.1).
+    //
+    // Disambiguation: this migration's `workflow_runs.parent_unit_id` is the
+    // PARENT RUN's unit that spawned this CHILD RUN — a cross-run composition
+    // edge, new in P3a. It is NOT the same concept as the pre-existing
+    // `workflow_run_units.parent_unit_id` (migration 004, consolidated above
+    // into migration 020's `workflow_run_units` table, migrations.ts:934),
+    // which records MAP FAN-OUT TEMPLATE PARENTAGE — one expanded unit's row
+    // pointing back at the map-template unit it fanned out from, WITHIN a
+    // single run. Same column name, two tables, two different concepts. So the
+    // two are never confused at a call site, the TypeScript repository API
+    // deliberately never spells this one `parentUnitId`: it is always
+    // `spawnedByUnitId` on `PublishChildWorkflowRunInput` and on every child
+    // run row the repository returns.
+    //
+    // `invocation_key` is the deterministic identity of one spawn attempt
+    // (`computeChildInvocationKey`, src/workflows/exec/child-invocation.ts).
+    // The unique index is partial (`WHERE parent_run_id IS NOT NULL`) because a
+    // top-level run — every run before this migration, and every run started
+    // directly by `akm workflow run` — has no parent and no invocation key, and
+    // must never be constrained by this uniqueness rule.
+    {
+        id: "023-child-workflow-runs",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN parent_run_id  TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN parent_unit_id TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN invocation_key TEXT;
+      CREATE INDEX idx_workflow_runs_parent ON workflow_runs(parent_run_id);
+      CREATE UNIQUE INDEX idx_workflow_runs_invocation_key
+        ON workflow_runs(parent_run_id, invocation_key)
+        WHERE parent_run_id IS NOT NULL;
+    `,
+    },
+    // ── Migration 024 — workflow run outputs (P3b) ─────────────────────────────
+    //
+    // Adds workflow_runs.outputs_json — the resolved map of a plan's declared
+    // outputs:, persisted once at run completion in the SAME transaction as the
+    // final step's completion (docs/plans/specs/p3b-child-executor.md §4.3,
+    // B-N13). NULL for every run whose plan declares no outputs: (the
+    // overwhelming majority, including every run before this migration) and for
+    // every run that fails or blocks before completing — never `{}`.
+    // `WorkflowRunsRepository.setRunOutputs` is the only writer;
+    // `src/workflows/runtime/run-outputs.ts` is the only resolver.
+    {
+        id: "024-workflow-run-outputs",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN outputs_json TEXT;
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {

package/dist/core/state-db.js

@@ -158,15 +158,17 @@ function descriptorAlias(handle) {
     }
     return undefined;
 }
-function sqliteBoundFilePath(handle, label) {
-    const alias = descriptorAlias(handle);
-    if (alias)
-        return alias;
-    // SQLite's Windows VFS keeps an open database pathname from being replaced;
-    // the caller still performs identity checks immediately around every open.
-    if (process.platform === "win32")
-        return handle.path;
-    throw new Error(`${label} cannot be bound to its held inode: this platform has no descriptor-backed path.`);
+function sqliteBoundFilePath(handle) {
+    // A descriptor-backed alias (/proc/self/fd, /dev/fd) lets SQLite open the
+    // exact held inode even if its path gets swapped out from under it. It is
+    // an optimization, not the actual protection: every caller re-verifies the
+    // held identity (dev/ino/uid) immediately before and after every open that
+    // uses this path, so a plain path is safe whenever no alias is available —
+    // Windows never has one, and macOS's /dev/fd is a small fixed-size devfs
+    // table that a process holding higher fd numbers (as a bundled standalone
+    // binary routinely does) can miss entirely. Either way, a swap in that
+    // window is still caught by the surrounding identity checks.
+    return descriptorAlias(handle) ?? handle.path;
 }
 function closeFileIdentity(handle) {
     try {
@@ -301,16 +303,16 @@ function createHistoricalStateSafetyCopy(source, migrationId) {
         // The migration connection already holds BEGIN IMMEDIATE. A distinct
         // read-only connection bound to the held source inode can snapshot the
         // committed WAL view without trying to VACUUM from inside that transaction.
-        reader = openDatabase(sqliteBoundFilePath(source, "state.db snapshot source"), { readonly: true });
+        reader = openDatabase(sqliteBoundFilePath(source), { readonly: true });
         assertStateDatabaseSource(source);
-        reader.prepare("VACUUM INTO ?").run(sqliteBoundFilePath(reservation, "Reserved state.db safety-copy target"));
+        reader.prepare("VACUUM INTO ?").run(sqliteBoundFilePath(reservation));
         assertStateDatabaseSource(source);
         reader.close();
         reader = undefined;
         assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
         fs.fsyncSync(reservation.fd);
         assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-        const verified = openDatabase(sqliteBoundFilePath(reservation, "Reserved state.db safety-copy target"), {
+        const verified = openDatabase(sqliteBoundFilePath(reservation), {
             readonly: true,
         });
         try {
@@ -403,7 +405,7 @@ export function openStateDatabase(dbPath, options) {
         if (!freshReservation) {
             existingSource = openExistingStateDatabaseSource(resolvedPath);
             assertStateDatabaseSource(existingSource);
-            const preflight = openDatabase(sqliteBoundFilePath(existingSource, "Existing state.db preflight"), {
+            const preflight = openDatabase(sqliteBoundFilePath(existingSource), {
                 readonly: true,
             });
             try {
@@ -425,7 +427,7 @@ export function openStateDatabase(dbPath, options) {
         if (boundSource)
             assertStateDatabaseSource(boundSource);
         openedDb = openManagedDatabase({
-            path: boundSource ? sqliteBoundFilePath(boundSource, "Managed state.db writer") : resolvedPath,
+            path: boundSource ? sqliteBoundFilePath(boundSource) : resolvedPath,
             pragmas: { dataDir: path.dirname(resolvedPath) },
             init: (db) => {
                 if (boundSource)