akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/tasks/task-run-reserved-flags.js

@@ -0,0 +1,79 @@
+// 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 task run`'s own declared flag names, exposed as a dependency-free leaf
+ * module so `src/tasks/source/task-source-v4.ts` (the parser) can reject a
+ * declared `inputs:` name that collides with one, without creating an import
+ * cycle back through the CLI layer.
+ *
+ * Code-review finding (docs/plans/specs/p2b-input-bindings.md, P2b review
+ * round 2): `schedulerInputFlagTail` (`../tasks/scheduler-binding.ts`) and
+ * `akm task run <id> --<name> <value>` both let an authored/declared input
+ * NAME collide with a flag `akm task run` already binds to itself
+ * (`--bundle`, `--scheduled`, …). `parseTaskInputFlags`
+ * (`../commands/tasks/tasks-cli.ts`) always treats those names as its OWN
+ * flags, never as input flags — so a colliding name is either silently
+ * absorbed into the wrong flag (`--bundle other-bundle` re-targets which
+ * bundle the task loads from) or left as an orphaned positional token that
+ * throws `Unexpected positional task argument`. Rejecting the collision at
+ * DECLARATION time (in `parseInputDeclarations`) closes every path that can
+ * ever reach it — a bare `akm task run --<name>`, `akm task explain
+ * --<name>`, and a `schedule[i].inputs` entry (whose keys are already
+ * checked against the declared contract, so a name banned here can never
+ * appear there either) — instead of special-casing each caller separately.
+ *
+ * `src/commands/tasks/tasks-cli.ts` re-exports `TASK_RUN_VALUE_FLAGS` /
+ * `TASK_RUN_BOOLEAN_FLAGS` from here unchanged, so this module is the single
+ * source of truth both the CLI's own argv scanner and the source parser read
+ * — the two can never drift apart. `TASK_RUN_SELF_DIAGNOSED_FLAGS` (below)
+ * covers the third category the scanner sets cannot express: a name the CLI
+ * claims by REJECTING it rather than by declaring it. This file imports
+ * nothing, and nothing it
+ * exports depends on IO, config, or any other `src/tasks/**` module, so it
+ * can be imported from either side of that boundary without participating in
+ * a cycle.
+ */
+/** Every VALUE-taking flag `akm task run` declares (GLOBAL_OUTPUT_ARGS' value flags plus `--bundle`). */
+export const TASK_RUN_VALUE_FLAGS = ["bundle", "format", "detail", "shape", "output"];
+/** Every BOOLEAN flag `akm task run` declares, including citty's `--no-` negations of the boolean pair above. */
+export const TASK_RUN_BOOLEAN_FLAGS = [
+    "scheduled",
+    "quiet",
+    "verbose",
+    "help",
+    "no-quiet",
+    "no-verbose",
+];
+/**
+ * Flag names `akm task` claims WITHOUT declaring them as citty args, so they
+ * appear in neither list above and must be reserved separately.
+ *
+ * `target` is the only member: the 0.9 rename of `akm task --target` to
+ * `--bundle` (S8.4) is self-diagnosed rather than merely dropped —
+ * `rejectRetiredTaskTargetFlag` (`../commands/tasks/tasks-cli.ts`) throws the
+ * rename hint for a `--target` in ANY spelling, bare or `--target=<value>`,
+ * and the generic pre-dispatch gate exempts the name on every `task`
+ * subcommand precisely so that handler can answer (`../cli/unknown-flags.ts`'s
+ * `SELF_DIAGNOSED_FLAGS`). That rejection runs before `parseTaskInputFlags`
+ * ever scans argv, so a declared input named `target` is unreachable through
+ * every spelling of its own flag — the exact value-misrouting hole the union
+ * below exists to close, just reached from the CLI's diagnostic side instead
+ * of from its declared-arg side (0.9.2 review round 2). Rejecting the
+ * DECLARATION keeps the rename hint intact for everyone typing the retired
+ * spelling while making the unusable declaration impossible to author, rather
+ * than trading one silent failure for another.
+ *
+ * It deliberately stays OUT of `TASK_RUN_VALUE_FLAGS` /
+ * `TASK_RUN_BOOLEAN_FLAGS`: those two are `parseTaskInputFlags`' own scanner
+ * sets (a value flag makes the scanner swallow the following token), and
+ * `--target` must keep reaching the rename diagnostic rather than being
+ * silently consumed as one of `akm task run`'s own flags.
+ */
+export const TASK_RUN_SELF_DIAGNOSED_FLAGS = ["target"];
+/** The union of all three lists above, for a single membership check against a candidate input name. */
+export const TASK_RUN_RESERVED_FLAG_NAMES = new Set([
+    ...TASK_RUN_VALUE_FLAGS,
+    ...TASK_RUN_BOOLEAN_FLAGS,
+    ...TASK_RUN_SELF_DIAGNOSED_FLAGS,
+]);

package/dist/workflows/authoring/authoring.js

@@ -50,14 +50,23 @@ export function assertWorkflowMarkdownName(name) {
     throw new UsageError(`akm workflow create is markdown-only: it emits Markdown and cannot create "${name}". ` +
         `Use a plain name (no ".yaml"/".yml" suffix), or author a peer GitHub-shaped ".yml" workflow directly.`);
 }
+// 0.9.2 review round 2 (P4 sweep criterion-21 caveat, spec
+// docs/plans/specs/p4-deletions-closeout.md §4.1 row B-49): this return's
+// third member was `stashDir` through 0.9.1 and leaked verbatim into the
+// `akm workflow create` JSON envelope (Stable per STABILITY.md) via
+// `output("workflow-create", { ok: true, ...result })`
+// (src/commands/workflow-cli.ts). Renamed to `bundleDir` here — the same
+// value-preserving field rename `RunTaskOptions.stashDir` got in P1b (see
+// src/tasks/run/task-result.ts's header, F-3) — so the shipped envelope now
+// matches current bundle vocabulary. BREAKING vs 0.9.1's envelope shape.
 export function createWorkflowAsset(input) {
     assertWorkflowMarkdownName(input.name);
     const config = loadConfig();
     const resolvedTarget = resolveWriteTarget(config);
     const target = prepareWriteTargetForMutation(resolvedTarget, { allowedAdapters: ["akm", "akm-workflow"] });
-    const stashDir = target.source.path;
+    const bundleDir = target.source.path;
     const standaloneWorkflowBundle = target.source.adapterId === "akm-workflow";
-    const typeRoot = standaloneWorkflowBundle ? stashDir : path.join(stashDir, "workflows");
+    const typeRoot = standaloneWorkflowBundle ? bundleDir : path.join(bundleDir, "workflows");
     const normalizedName = normalizeWorkflowName(input.name);
     const conceptId = standaloneWorkflowBundle ? normalizedName : `workflows/${normalizedName}`;
     const assetPath = path.join(typeRoot, `${normalizedName}.md`);
@@ -73,7 +82,7 @@ export function createWorkflowAsset(input) {
     // target would silently clobber or shadow the existing asset.
     const shadowing = findExistingWorkflowPaths(typeRoot, normalizedName).find((p) => p !== assetPath);
     if (shadowing !== undefined) {
-        throw new UsageError(`Workflow "${normalizedName}" already exists as ${path.relative(stashDir, shadowing)} — the ` +
+        throw new UsageError(`Workflow "${normalizedName}" already exists as ${path.relative(bundleDir, shadowing)} — the ` +
             `\`${conceptId}\` ref resolves to that file, so creating this one would shadow it. ` +
             `Remove or rename the existing file first, or create the workflow under a different name.`, "RESOURCE_ALREADY_EXISTS");
     }
@@ -81,7 +90,7 @@ export function createWorkflowAsset(input) {
         throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
     const content = input.from
-        ? readWorkflowSource(input.from, stashDir)
+        ? readWorkflowSource(input.from, bundleDir)
         : (input.content ?? buildWorkflowTemplate(normalizedName));
     const sourcePath = input.from ?? `workflows/${normalizedName}.md`;
     validateWorkflowContent(content, sourcePath);
@@ -96,10 +105,10 @@ export function createWorkflowAsset(input) {
     return {
         ref,
         path: assetPath,
-        stashDir,
+        bundleDir,
     };
 }
-function readWorkflowSource(source, stashDir) {
+function readWorkflowSource(source, bundleDir) {
     const resolved = path.resolve(source);
     let stat;
     try {
@@ -114,9 +123,9 @@ function readWorkflowSource(source, stashDir) {
     // The user is allowed to import any readable file as a workflow body, but
     // an import from outside the stash is unusual enough to warn about. Anyone
     // running `akm workflow create --from /etc/passwd` deserves a heads-up.
-    if (!isWithin(resolved, stashDir)) {
+    if (!isWithin(resolved, bundleDir)) {
         warn(`Importing workflow content from outside the stash: ${resolved}\n  ` +
-            `If this was unintentional, abort and re-run with a --from path inside ${stashDir}.`);
+            `If this was unintentional, abort and re-run with a --from path inside ${bundleDir}.`);
     }
     return fs.readFileSync(resolved, "utf8");
 }

package/dist/workflows/exec/child-invocation.js

@@ -0,0 +1,34 @@
+// 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/.
+/**
+ * A child workflow run's idempotency key (spec
+ * docs/plans/specs/p3a-plan-v5-child-freeze.md §3.4, rows A-17…A-19). Pure:
+ * no IO, no config, no clock, no randomness — imports exactly node:crypto
+ * and canonicalJson.
+ *
+ * P3a has no production caller: P3b's child executor derives this key from
+ * the parent unit's `hashVersion` 7 input hash and passes it to
+ * `publishChildWorkflowRun` (src/storage/repositories/workflow-runs-repository.ts,
+ * Lane C) as the `(parent_run_id, invocation_key)` idempotency pair.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "../ir/plan-hash.js";
+/**
+ * `sha256hex("akm.workflow.child-invocation\0v1\0" + canonicalJson({parentRunId, parentUnitId, unitInputHash}))`.
+ *
+ * The `\0v1\0` here is this helper's OWN vocabulary version, deliberately
+ * independent of `hashVersion`: `unitInputHash` enters this preimage as an
+ * opaque value, so this key's preimage does not change when the unit-hash
+ * vocabulary itself bumps.
+ */
+export function computeChildInvocationKey(input) {
+    return createHash("sha256")
+        .update("akm.workflow.child-invocation\0v1\0")
+        .update(canonicalJson({
+        parentRunId: input.parentRunId,
+        parentUnitId: input.parentUnitId,
+        unitInputHash: input.unitInputHash,
+    }))
+        .digest("hex");
+}

package/dist/workflows/exec/child-workflow.js

@@ -0,0 +1,370 @@
+// 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 child workflow executor (P3b, spec docs/plans/specs/p3b-child-executor.md
+ * §3). `driveChildWorkflowUnit` is the ONE place a `child-workflow`-targeted
+ * unit is published (idempotently) and driven: no second executor, no second
+ * scheduler, no second journal writer. It is reached from the ONE dispatch
+ * seam in `native-executor.ts`'s `dispatchJournaledAttempt` (§3.2).
+ *
+ * Ordered algorithm (§3.3): (1) re-verify the embedded child plan's integrity;
+ * (2) validate the resolved `with:` bindings against the child's declared
+ * `params:`; (3) derive the deterministic invocation key; (4) publish the
+ * child run idempotently (`publishChildWorkflowRun`, P3a); (5) read the
+ * published row's status; (6) drive it with the SAME engine the top-level path
+ * uses (`runWorkflowSteps`) unless it is already terminal-for-this-invocation
+ * (`blocked`/`failed`, rows A-22/A-23); (7) map the child's FINAL status
+ * through §3.4's table onto this unit's outcome.
+ *
+ * ## Why `runWorkflowSteps` is reached through a LAZY dynamic import, not a
+ * static one (B-N5, and the §7 preservation-gate contingency)
+ *
+ * `native-executor.ts` must import `driveChildWorkflowUnit` FROM this file
+ * (the dispatch seam calls it inline, §3.2) — that edge is fixed. `run-
+ * workflow.ts` imports `native-executor.ts` (existing, load-bearing:
+ * `executeStepPlan`). If this file ALSO imported `runWorkflowSteps` from
+ * `./run-workflow` STATICALLY, the three edges would close a static cycle
+ * (native-executor.ts -> child-workflow.ts -> run-workflow.ts ->
+ * native-executor.ts), which `tests/architecture/import-cycle-ratchet.test.ts`
+ * (shrink-only, EMPTY baseline — an absolute gate) forbids outright; adding an
+ * entry to admit it is not an option the ratchet allows. Per this spec's own
+ * §7 checklist ("if the ratchet objects, the drive is reached through an
+ * injected function value, the pattern `ir/freeze-v4.ts`'s `ChildFreezeFn`
+ * already establishes"), the drive is instead reached through
+ * {@link driveWithRealEngine}'s `await import("./run-workflow.js")` — a
+ * DYNAMIC import, invisible to the static-graph cycle ratchet by design (its
+ * own doc: "dynamic `import()` is excluded because it is the repo's
+ * sanctioned lazy-loading escape hatch"), registered in
+ * `DYNAMIC_IMPORT_BASELINE` (scripts/lint-import-cycles.ts) as a genuine
+ * lazy-load: the vast majority of workflow runs compose no child at all, so
+ * loading `run-workflow.ts`'s full engine (lease heartbeat, retry loop) is
+ * deferred until a `child-workflow` unit is actually dispatched. Bun/Node
+ * cache a module on first dynamic import, so this costs nothing on repeat
+ * calls, and it resolves the SAME module namespace object a test's
+ * `import * as runWorkflowModule from "./run-workflow.js"` holds — a
+ * `spyOn(runWorkflowModule, "runWorkflowSteps")` is therefore observed
+ * exactly as if this module had imported it statically. Unlike a registered
+ * function value (which would depend on `run-workflow.ts` having already
+ * been loaded by SOME OTHER file — fragile for a test file exercising this
+ * seam in isolation), a dynamic import always resolves correctly regardless
+ * of what the rest of the process has loaded. This is the ONLY runtime
+ * indirection in the whole drive: no second executor is created, and
+ * `driveRun` itself is never exported (B-N5's "no second executor" holds).
+ */
+import { randomUUID } from "node:crypto";
+import { UsageError } from "../../core/errors.js";
+import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
+import { validateWorkflowParams } from "../ir/params.js";
+import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
+import { frozenStepRows } from "../runtime/plan-classifier.js";
+import { workflowRunExportedResult } from "../runtime/run-outputs.js";
+import { computeChildInvocationKey } from "./child-invocation.js";
+/**
+ * The real engine's `runWorkflowSteps`, reached ONLY through a dynamic
+ * import — see the module doc for why. The return value is deliberately
+ * unused by the caller: this module always RE-READS the child run row from
+ * the repository afterward (spec step 7) rather than trusting the driver's
+ * return value, so no result shape needs to be shared across the seam.
+ */
+async function driveWithRealEngine(options) {
+    const { runWorkflowSteps } = await import("./run-workflow.js");
+    await runWorkflowSteps(options);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** `acquireRunLease`'s exact refusal shape (run-workflow.ts) — matched by text, since this module cannot import that private helper. */
+function isLeaseBusyError(err) {
+    return err instanceof UsageError && err.message.includes("is already being driven by engine");
+}
+/** §3.4's exact `child_workflow_failed` message. */
+function childWorkflowFailedMessage(input) {
+    return (`Child workflow run ${input.childRunId} (${input.childRef}) failed at step "${input.childStepId}". ` +
+        `Inspect it with \`akm workflow status ${input.childRunId}\`; the parent run's step ` +
+        `"${input.parentStepId}" cannot advance until it succeeds.`);
+}
+/**
+ * Steps 1-3 (spec §3.3): integrity re-check, param validation, and the
+ * deterministic invocation key. Returns either the key or an already-shaped
+ * `child_workflow_publish_failed` outcome.
+ */
+function precheckAndDeriveInvocationKey(input) {
+    const { request, target, ctx, childParams, inputHash } = input;
+    // Step 1 — integrity re-check (row A-10).
+    const recomputedPlanHash = computePlanHash(target.frozenPlan);
+    if (recomputedPlanHash !== target.planHash) {
+        return {
+            ok: false,
+            outcome: {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_publish_failed",
+                error: `Workflow step "${request.stepId}" composes child workflow ${target.ref}, but its embedded plan's ` +
+                    `recomputed hash (${recomputedPlanHash}) does not match the frozen target's planHash (${target.planHash}). ` +
+                    "The frozen plan has been corrupted or tampered with.",
+            },
+        };
+    }
+    // Step 2 — resolved params against the child's declared param schemas (row A-11).
+    const paramErrors = validateWorkflowParams(target.frozenPlan, childParams);
+    if (paramErrors.length > 0) {
+        return {
+            ok: false,
+            outcome: {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_publish_failed",
+                error: `Workflow step "${request.stepId}" composes child workflow ${target.ref}, but the resolved params do not ` +
+                    `satisfy its declared param schemas:\n${paramErrors.map((e) => `  - ${e}`).join("\n")}`,
+            },
+        };
+    }
+    // Step 3 — the deterministic invocation key (B-N8: parentUnitId is request.unitId, the parent unit's journalBaseId).
+    return {
+        ok: true,
+        invocationKey: computeChildInvocationKey({
+            parentRunId: ctx.runId,
+            parentUnitId: request.unitId,
+            unitInputHash: inputHash,
+        }),
+    };
+}
+/**
+ * Step 4/5 (spec §3.3): publish the child run idempotently and return the
+ * pre-drive status read (the returned row IS that read). B-N16: no
+ * transaction open on this connection — this seam is reached from
+ * dispatchJournaledAttempt, outside resumeWorkflowRun's and
+ * completeWorkflowStep's own transactions.
+ */
+async function publishChildRun(input, invocationKey) {
+    const { request, target, ctx, childParams } = input;
+    try {
+        const parentRow = await withWorkflowRunsRepo((repo) => repo.getRunById(ctx.runId));
+        if (!parentRow) {
+            throw new Error(`parent run ${ctx.runId} was not found`);
+        }
+        const now = new Date().toISOString();
+        const childRunId = randomUUID();
+        const childRow = await withWorkflowRunsRepo((repo) => repo.publishChildWorkflowRun({
+            parentRunId: ctx.runId,
+            spawnedByUnitId: request.unitId,
+            invocationKey,
+            run: {
+                id: childRunId,
+                workflowRef: target.ref,
+                scopeKey: parentRow.scope_key,
+                workflowEntryId: null,
+                workflowTitle: target.frozenPlan.title,
+                paramsJson: JSON.stringify(childParams),
+                currentStepId: target.frozenPlan.steps[0]?.stepId ?? null,
+                createdAt: now,
+                updatedAt: now,
+                agentHarness: parentRow.agent_harness,
+                agentSessionId: parentRow.agent_session_id,
+                checkinArmedAt: now,
+            },
+            steps: frozenStepRows(target.frozenPlan).map((row) => ({ ...row, runId: childRunId })),
+            planJson: canonicalPlanJson(target.frozenPlan),
+            planHash: target.planHash,
+        }));
+        return { ok: true, childRow };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            outcome: {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_publish_failed",
+                error: `Workflow step "${request.stepId}" could not publish child workflow run for ${target.ref}: ${errorMessage(err)}`,
+            },
+        };
+    }
+}
+/**
+ * Step 6 (spec §3.3): drive the published child run with the real engine,
+ * unless it is already terminal-for-this-invocation (`blocked`/`failed`,
+ * rows A-22/A-23 — never re-driven, no lease taken). Returns the FINAL row
+ * (re-read after the drive) or an already-shaped `child_workflow_busy` /
+ * `child_workflow_drive_failed` outcome.
+ */
+async function driveChildRun(input, childRow) {
+    const { request, target, ctx } = input;
+    const shouldDrive = childRow.status !== "blocked" && childRow.status !== "failed";
+    if (!shouldDrive) {
+        return { ok: true, finalRow: childRow };
+    }
+    const driveOptions = {
+        target: childRow.id,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        ...(ctx.dispatcher ? { dispatcher: ctx.dispatcher } : {}),
+        ...(ctx.maxConcurrency !== undefined ? { maxConcurrency: ctx.maxConcurrency } : {}),
+        ...(ctx.eventSource !== undefined ? { eventSource: ctx.eventSource } : {}),
+        // B-N6: a no-op, distinct from the real registry drain — the PARENT's
+        // own `finally` remains the single owner of the process-lifecycle
+        // drain for the whole process (row A-24).
+        disposeDispatchResources: () => { },
+        // B-N7: deliberately no maxSteps, no maxRetries (rows A-25, A-26).
+    };
+    try {
+        // The re-read is INSIDE the same try as the drive (code-review round 4,
+        // finding 1; Review log R1): every throw between here and a mapped
+        // UnitOutcome — the drive itself, OR this immediately-following
+        // getRunById — must be caught. Left to escape, it skips past
+        // dispatchJournaledAttempt's finishJournaledDispatch (no try/catch
+        // wraps this seam there by design), so the parent's reserved attempt
+        // row is never finished; the throw then propagates through runUnit
+        // into concurrentMap's worker (src/core/concurrent.ts), which SWALLOWS
+        // it and leaves the unit's outcome slot `undefined`, which
+        // executeStepPlanInConnection then maps to the false diagnostic
+        // "unit was not dispatched (aborted or scheduler failure)" — losing
+        // the real cause and leaving the composing attempt row stuck
+        // `running` forever (unrecoverable by inspection; a resume + re-drive
+        // reproduces the identical false diagnostic).
+        await driveWithRealEngine(driveOptions);
+        const finalRow = (await withWorkflowRunsRepo((repo) => repo.getRunById(childRow.id))) ?? childRow;
+        return { ok: true, finalRow };
+    }
+    catch (err) {
+        if (isLeaseBusyError(err)) {
+            return {
+                ok: false,
+                outcome: {
+                    unitId: request.unitId,
+                    ok: false,
+                    failureReason: "child_workflow_busy",
+                    error: errorMessage(err),
+                    childRun: {
+                        runId: childRow.id,
+                        ref: childRow.workflow_ref,
+                        status: childRow.status,
+                        currentStepId: childRow.current_step_id,
+                    },
+                },
+            };
+        }
+        // EVERY other throw is mapped here too — never rethrown. §3.5's
+        // original premise ("classified by the existing dispatch_error
+        // handling") was false: no handling exists at this seam
+        // (dispatchJournaledAttempt awaits this call with no try of its own),
+        // so an uncaught throw here escaped all the way into the scheduler and
+        // was silently swallowed (R1, above). Reachable causes include the
+        // child's own LeaseHeartbeat.assertAlive() firing mid-drive, a Lane B
+        // UsageError out of the child's own completeWorkflowStep (e.g.
+        // WORKFLOW_OUTPUT_INVALID), requireExecutableWorkflowPlan rejecting a
+        // tampered child plan_json, and the child's status changing between
+        // this function's own step 5 read and the drive's internal
+        // getNextWorkflowStep re-read — none of which match
+        // isLeaseBusyError's text. child_workflow_drive_failed is a SIBLING of
+        // child_workflow_publish_failed (row A-10…A-12): same shape, same
+        // errorMessage(err) content, but naming the child run id and ref
+        // (already known at this point, unlike the publish arm above) since
+        // driving — not publishing — is what failed.
+        return {
+            ok: false,
+            outcome: {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_drive_failed",
+                error: `Workflow step "${request.stepId}" composes child workflow run ${childRow.id} (${target.ref}), ` +
+                    `but driving it failed: ${errorMessage(err)}`,
+                childRun: {
+                    runId: childRow.id,
+                    ref: childRow.workflow_ref,
+                    status: childRow.status,
+                    currentStepId: childRow.current_step_id,
+                },
+            },
+        };
+    }
+}
+/**
+ * `driveChildWorkflowUnit` — the ONE child drive (spec §3.3). Every failure
+ * before step 6 (publication) produces `child_workflow_publish_failed`.
+ */
+export async function driveChildWorkflowUnit(input) {
+    const { request, target, ctx } = input;
+    const precheck = precheckAndDeriveInvocationKey(input);
+    if (!precheck.ok) {
+        return precheck.outcome;
+    }
+    const published = await publishChildRun(input, precheck.invocationKey);
+    if (!published.ok) {
+        return published.outcome;
+    }
+    const { childRow } = published;
+    const driven = await driveChildRun(input, childRow);
+    if (!driven.ok) {
+        return driven.outcome;
+    }
+    const { finalRow } = driven;
+    const childRunSummary = {
+        runId: finalRow.id,
+        ref: finalRow.workflow_ref,
+        status: finalRow.status,
+        currentStepId: finalRow.current_step_id,
+    };
+    // A-28/A-29: the child did not reach a terminal state, and the parent's
+    // own dispatch signal is what aborted it — checked against the RE-READ
+    // status (not the signal alone) so an already-terminal child is never
+    // misreported as aborted.
+    if (finalRow.status === "active" && ctx.signal?.aborted) {
+        return {
+            unitId: request.unitId,
+            ok: false,
+            failureReason: "aborted",
+            error: `Child workflow run ${finalRow.id} (${finalRow.workflow_ref}) was not driven to completion: ` +
+                "the parent workflow invocation was interrupted.",
+            childRun: childRunSummary,
+        };
+    }
+    switch (finalRow.status) {
+        case "completed":
+            return {
+                unitId: request.unitId,
+                ok: true,
+                result: workflowRunExportedResult(finalRow),
+                childRun: childRunSummary,
+            };
+        case "failed": {
+            const childStepId = finalRow.current_step_id ?? "(unknown)";
+            return {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_failed",
+                error: childWorkflowFailedMessage({
+                    childRunId: finalRow.id,
+                    childRef: finalRow.workflow_ref,
+                    childStepId,
+                    parentStepId: request.stepId,
+                }),
+                childRun: childRunSummary,
+            };
+        }
+        case "blocked":
+            return {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_blocked",
+                error: `Child workflow run ${finalRow.id} (${finalRow.workflow_ref}) is blocked at its own step ` +
+                    `"${finalRow.current_step_id ?? "(unknown)"}". Inspect it with \`akm workflow status ${finalRow.id}\`.`,
+                childRun: childRunSummary,
+            };
+        default:
+            // The child's own gate loop exhausted without reaching a terminal
+            // status (a genuine gate rejection on the child's own step, never
+            // reached by this phase's fixtures — B-N7 forwards no maxSteps/
+            // maxRetries, so nothing else can leave a driven child non-terminal
+            // without an abort). Treated conservatively as a failure so the
+            // parent never silently advances on an unresolved child.
+            return {
+                unitId: request.unitId,
+                ok: false,
+                failureReason: "child_workflow_failed",
+                error: `Child workflow run ${finalRow.id} (${finalRow.workflow_ref}) did not reach a terminal state ` +
+                    `(status: ${finalRow.status}). Inspect it with \`akm workflow status ${finalRow.id}\`.`,
+                childRun: childRunSummary,
+            };
+    }
+}