akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/workflows/authoring/workflow-program-template.yaml

@@ -1,31 +0,0 @@
-# akm YAML workflow program (binding YAML v2).
-# Save under workflows/<name>.yaml and lint with:
-#   akm workflow validate workflows/<name>.yaml
-version: 2
-name: example-workflow
-description: Describe what this workflow accomplishes.
-
-params:
-  example_param: { type: string, description: Explain this parameter }
-
-defaults: # run-level defaults, overridable per unit
-  # engine: my-engine # optional; otherwise defaults.engine from config
-  timeout: 10m # "<n>ms" | "<n>s" | "<n>m" | "none"
-  on_error: fail # fail | continue
-
-steps:
-  - id: first-step
-    title: First Step
-    unit:
-      instructions: |
-        Describe what to do in this step.
-        Reference run parameters explicitly: ${{ params.example_param }}.
-    gate:
-      criteria:
-        - Confirm the first step is complete
-
-  - id: second-step
-    title: Second Step
-    unit:
-      instructions: |
-        Describe what happens next.

package/dist/workflows/cli.js

@@ -1,53 +0,0 @@
-// 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/.
-import { UsageError } from "../core/errors.js";
-export const WORKFLOW_STEP_STATES = [
-    "completed",
-    "blocked",
-    "failed",
-    "skipped",
-];
-export const WORKFLOW_SUBCOMMANDS = new Set([
-    "start",
-    "next",
-    "complete",
-    "status",
-    "list",
-    "create",
-    "template",
-    "resume",
-    "abandon",
-    "validate",
-    "run",
-    "brief",
-    "report",
-    "watch",
-]);
-export function parseWorkflowJsonObject(raw, flagName) {
-    if (!raw)
-        return {};
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new UsageError(`${flagName} must be valid JSON.`);
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new UsageError(`${flagName} must be a JSON object.`);
-    }
-    return parsed;
-}
-export function parseWorkflowStepState(value) {
-    if (!value)
-        return "completed";
-    if (WORKFLOW_STEP_STATES.includes(value)) {
-        return value;
-    }
-    throw new UsageError(`Invalid workflow step state "${value}". Expected one of: ${WORKFLOW_STEP_STATES.join(", ")}`);
-}
-export function hasWorkflowSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && WORKFLOW_SUBCOMMANDS.has(command);
-}

package/dist/workflows/exec/brief.js

@@ -1,481 +0,0 @@
-// 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 brief <run>` — the read-only half of the harness-neutral driver
- * protocol (redesign addendum R3). It tells ANY agent session (Claude Code,
- * opencode, Codex, a human at a shell) exactly what units the native engine
- * would dispatch for a run's active step, and how to report the results back
- * through `akm workflow report` (the mutating half, R3 step 3).
- *
- * ## Read-only, no lease, no dispatch, no mutation
- *
- * `brief` computes; it never writes. It takes no engine lease, dispatches no
- * units, and never advances the gate spine. The only database access is
- * SELECTs (`getNextWorkflowStep` + the run row + the unit journal). A test
- * proves the workflow.db file is byte-identical before and after a `brief`.
- *
- * ## No duplicated semantics (the cardinal rule)
- *
- * The expected work-list is computed by the SAME shared functions the engine
- * uses (`step-work.ts`): {@link computeStepWorkList} for item resolution +
- * content-derived unit ids + input hashes + prompt assembly,
- * {@link activeGateLoop} / {@link recoverGateFeedback} to recover the gate-loop
- * number and the judge feedback the engine threads into loop-N prompts (so a
- * loop-2 brief's unit ids/hashes equal what the engine would compute),
- * {@link stepOutputsFromEvidence} for the expression scope, and
- * {@link evaluateRoute} for the deterministic route decision. Because both
- * surfaces call one implementation, an engine-driven run and a brief/report
- * driven run of the same frozen plan produce byte-identical unit graphs — the
- * invariant R4 asserts.
- */
-import { parseRefInput } from "../../core/asset/resolve-ref.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
-import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
-import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
-import { assertRunParamsSatisfyPlan } from "../ir/params.js";
-import { frozenStepRows, requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
-import { snapshotRunForDriver } from "../runtime/runs.js";
-import { evaluateStaleUnits } from "../runtime/unit-checkin.js";
-import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
-import { canonicalWorkflowRunRef } from "../runtime/workflow-asset-loader.js";
-import { detectSecretShapedParams } from "./param-secrets.js";
-import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, isWorkListFullyTerminal, recoverGateFeedback, selectUnitAttemptRow, stepOutputsFromEvidence, } from "./step-work.js";
-const EMPTY_WORK_LIST = { isFanOut: false, reducer: null, itemCount: 0, units: [] };
-// ── Entry point ──────────────────────────────────────────────────────────────
-/**
- * Build the read-only brief for a run. `target` is a run id (preferred) or a
- * workflow ref that ALREADY has an active run in the current scope — brief
- * never auto-starts a run (that would mutate), so a ref with no active run is a
- * NotFoundError, not a silent start.
- */
-export async function buildWorkflowBrief(target) {
-    const runId = await resolveRunId(target);
-    // Read-only spine walk. #14: read the run row, its steps, AND its unit journal
-    // in ONE transaction so a concurrent report/run/manual completion cannot change
-    // the active step between the spine read and the unit-journal read. A bare run
-    // id never auto-starts (we resolved to a concrete id above).
-    const { next, run: runRow, units } = await snapshotRunForDriver(runId);
-    const leaseHolder = runRow.engine_lease_holder;
-    const leaseUntil = runRow.engine_lease_until;
-    const run = {
-        id: next.run.id,
-        workflowRef: next.run.workflowRef,
-        workflowTitle: next.run.workflowTitle,
-        status: next.run.status,
-        currentStepId: next.run.currentStepId ?? null,
-        params: next.run.params ?? {},
-    };
-    const warnings = [];
-    // #13: params are declared NON-SECRET. They are interpolated into every unit
-    // prompt AND hashed into the unit identity, so `brief` cannot redact them
-    // without breaking the byte-identical-prompt contract a driver executes
-    // against. Surface the standing advisory (whenever the run carries params) plus
-    // any best-effort secret-shaped-value hits, so an author moves credentials to
-    // an env binding (which `brief` only ever names).
-    if (Object.keys(run.params).length > 0) {
-        warnings.push("Workflow params are copied verbatim into every unit prompt shown to any driver and are hashed into the unit " +
-            "identity — they are NOT secret. Never put credentials in params; put secrets in env bindings (`env:` refs), " +
-            "which `brief` surfaces by name only and never resolves.");
-    }
-    warnings.push(...detectSecretShapedParams(run.params));
-    const lease = buildLease(leaseHolder, leaseUntil);
-    if (lease?.live) {
-        warnings.push(`Engine ${lease.holder} holds a LIVE run lease (expires ${lease.until}). This run is being driven by the ` +
-            `native engine right now — \`akm workflow report\` is REFUSED while the lease is live. Do NOT execute these ` +
-            `units; wait for the engine to finish or for the lease to expire.`);
-    }
-    // Stale claimed units (pure timestamp evaluation): a driver claimed these via
-    // `report --status running` but has not heartbeated within the window — flag
-    // them so another driver can reclaim the abandoned work.
-    const staleUnits = evaluateStaleUnits(units);
-    if (staleUnits.length > 0) {
-        warnings.push(`${staleUnits.length} unit(s) were claimed with \`report --status running\` but have gone silent past the ` +
-            `check-in window (${staleUnits.map((u) => u.unitId).join(", ")}). Their driver may have died — you can ` +
-            `reclaim and re-execute them.`);
-    }
-    const reportGuidance = {
-        checkin: `akm workflow report ${run.id} --unit <unit_id> --status running --note "<short progress note>"`,
-        failure: `akm workflow report ${run.id} --unit <unit_id> --status failed --failure-reason <vocab>`,
-        note: "Run each unit, then report its result. A unit belongs to the active step's work-list; its unit_id is content-derived — copy it verbatim.",
-    };
-    // Spine watermark (#14): run-mutation counter shared by every return below.
-    // The active branch re-stamps it with the real gate loop + active step id.
-    const watermark = `${runRow.updated_at}:u${units.length}`;
-    const base = {
-        ok: true,
-        run,
-        spineToken: makeSpineToken(run.id, run.currentStepId, 1, watermark),
-        ...(lease ? { engineLease: lease } : {}),
-        reportGuidance,
-        staleUnits,
-        warnings,
-    };
-    // Completed run: nothing to do.
-    if (next.done || run.status === "completed") {
-        return {
-            ...base,
-            done: true,
-            active: false,
-            workList: EMPTY_WORK_LIST,
-            message: "Workflow run is completed — no work remains.",
-        };
-    }
-    // Blocked / failed: not active, so the engine dispatches nothing. Point the
-    // driver at `resume` rather than inventing a work-list for a dead run.
-    if (run.status !== "active") {
-        warnings.push(`Workflow run is ${run.status}, not active — no work-list. Reopen it first: \`akm workflow resume ${run.id}\`.`);
-        return {
-            ...base,
-            active: false,
-            workList: EMPTY_WORK_LIST,
-            message: `Workflow run is ${run.status} — resume it to continue.`,
-        };
-    }
-    const stepState = next.step;
-    if (!stepState) {
-        return {
-            ...base,
-            active: false,
-            workList: EMPTY_WORK_LIST,
-            message: "Workflow run is active but has no current step.",
-        };
-    }
-    // Load the FROZEN plan the engine executes (migration 006). A legacy run
-    // (NULL plan_json) has no plan for brief to read — point at engine-driven
-    // mode, which still handles pre-006 runs by compiling from the asset.
-    const plan = requireExecutableWorkflowPlan(runRow);
-    // Reviewer #12: the journaled params row must still satisfy the frozen param
-    // schemas — a violation is post-start corruption, loud on the brief surface
-    // too (mirrors the frozen-plan hash check and the tampered-params divergence).
-    assertRunParamsSatisfyPlan(run.id, plan, next.run.params ?? {});
-    // Reviewer #7: a completed route step whose journaled decision names a target
-    // the route never declared is tampered evidence — fail loudly on the read-only
-    // brief surface too, not just on the resume/report surfaces that replay it.
-    assertJournaledRouteSelectionsValid(plan, next);
-    const stepPlan = plan.steps.find((s) => s.stepId === stepState.id);
-    if (!stepPlan) {
-        throw new UsageError(`Step "${stepState.id}" of run ${run.id} is not present in the run's frozen plan. The plan and the step ` +
-            `journal disagree — this run cannot be described; drive it manually with \`akm workflow complete\`.`);
-    }
-    // Expression scope: prior steps' promoted artifacts + run params, projected
-    // exactly as the engine does (stepOutputsFromEvidence). The current (pending)
-    // step contributes no output yet.
-    const evidence = {};
-    for (const s of next.workflow.steps)
-        evidence[s.id] = s.evidence;
-    const stepOutputs = stepOutputsFromEvidence(evidence);
-    // Gate loop + recovered feedback — the journal-derived state that makes a
-    // loop-N brief predict the engine's loop-N dispatch (unit ids + hashes).
-    const gateLoop = activeGateLoop(units, stepState.id);
-    const gateFeedback = recoverGateFeedback(units, stepState.id, gateLoop);
-    const isRouteOnly = !!stepPlan.route && !stepPlan.root;
-    const kind = isRouteOnly ? "route" : stepPlan.route ? "execute-and-route" : "execute";
-    const criteria = stepPlan.gate.criteria;
-    const instructions = frozenStepRows(plan).find((step) => step.stepId === stepState.id)?.instructions;
-    if (instructions === undefined)
-        throw new UsageError(`Step "${stepState.id}" has no frozen instructions.`);
-    const step = {
-        stepId: stepState.id,
-        title: stepPlan.title,
-        sequenceIndex: stepPlan.sequenceIndex,
-        kind,
-        instructions,
-        gate: {
-            criteria,
-            maxLoops: Math.max(1, stepPlan.gate.maxLoops ?? 1),
-            currentLoop: gateLoop,
-            judgesArtifact: !isRouteOnly && criteria.length > 0,
-            required: stepPlan.gate.required === true,
-        },
-        ...(stepPlan.outputSchema ? { outputSchema: stepPlan.outputSchema } : {}),
-    };
-    // Journaled dispatch rows for THIS step, keyed by unit id (exclude gate rows).
-    const journaledByUnit = new Map();
-    for (const row of units) {
-        if (row.step_id === stepState.id && row.phase !== GATE_EVALUATION_PHASE) {
-            journaledByUnit.set(row.unit_id, row);
-        }
-    }
-    // #15 action derivation inputs: the stale-claim set (by unit id) and whether a
-    // live engine lease means the whole work-list is `do_not_run` right now.
-    const staleIds = new Set(staleUnits.map((u) => u.unitId));
-    const leaseLive = lease?.live === true;
-    // The work-list — the SAME computation the engine runs (no drift).
-    let workList = EMPTY_WORK_LIST;
-    // True when every resolvable unit ran to a terminal state but the step never
-    // finalized (a required-gate block that was resumed, or a crash between the
-    // last unit write and completion) — the fully-terminal recovery state.
-    let fullyTerminal = false;
-    if (!isRouteOnly) {
-        const computed = computeStepWorkList(stepPlan, {
-            runId: run.id,
-            params: run.params,
-            stepOutputs,
-            engines: plan.execution.engines,
-            gateLoop,
-            ...(gateFeedback ? { gateFeedback } : {}),
-        });
-        if (!computed.ok) {
-            workList = { ...EMPTY_WORK_LIST, error: computed.error };
-        }
-        else {
-            const list = computed.list;
-            fullyTerminal = !leaseLive && isWorkListFullyTerminal(list, journaledByUnit);
-            // #21: a worktree-isolated unit runs in a throwaway git worktree that is
-            // auto-removed when clean. Files it writes to a `.gitignore`d path are
-            // treated as disposable and discarded — warn any driver so collectible
-            // artifacts go to a non-ignored path or come back as a reported result.
-            if (list.units.some((u) => u.isolation === "worktree")) {
-                warnings.push("This step runs unit(s) in an isolated git worktree (`isolation: worktree`). Outputs matched by the " +
-                    "repository's `.gitignore` are treated as DISPOSABLE — a clean worktree is auto-removed, discarding them. " +
-                    "Write any artifact that must survive to a NON-ignored path (a tracked or untracked-unignored file), or " +
-                    "report it as the unit's result. Do not leave collectible work under `node_modules`/`dist`/build/cache paths.");
-            }
-            workList = {
-                isFanOut: list.isFanOut,
-                reducer: list.reducer,
-                ...(list.concurrency !== undefined ? { concurrency: list.concurrency } : {}),
-                itemCount: list.items.length,
-                units: list.units.map((u) => 
-                // Resolve the unit's journaled state by its BEST terminal attempt
-                // (base + `~r<n>` retries), the SAME reuse the engine and report
-                // surfaces apply (shared selectUnitAttemptRow, finding C): a unit whose
-                // base attempt failed but whose retry completed surfaces as `done`, not
-                // `failed`, so brief never advertises re-running work a prior retry
-                // already finished — keeping the read-only surface consistent with what
-                // report/resume would reduce.
-                toBriefUnit(run.id, u, stepState.id, selectUnitAttemptRow(u, journaledByUnit), {
-                    stale: staleIds.has(u.journalBaseId),
-                    leaseLive,
-                })),
-            };
-        }
-    }
-    // Route contract. A route-only step's decision depends solely on prior step
-    // outputs, so brief evaluates it deterministically NOW. An execute-and-route
-    // step's decision needs the current step's fresh output, which does not exist
-    // until the units run — so brief surfaces the contract without a decision.
-    let route;
-    if (stepPlan.route) {
-        route = {
-            input: stepPlan.route.input,
-            when: stepPlan.route.when,
-            ...(stepPlan.route.defaultStepId ? { defaultStepId: stepPlan.route.defaultStepId } : {}),
-            evaluatedNow: isRouteOnly,
-        };
-        if (isRouteOnly) {
-            const scope = { params: run.params, stepOutputs };
-            const decision = evaluateRoute(stepPlan.route, scope);
-            if (decision.ok)
-                route.decision = { value: decision.value, selected: decision.selected };
-            else
-                route.decisionError = decision.error;
-        }
-    }
-    // A step the driver cannot advance with a per-unit `report --unit` gets the
-    // `--settle` verb instead. TWO cases:
-    //   - NON-DISPATCHING (finding D): a route-only step, an empty fan-out, an
-    //     all-unresolvable work-list, or a whole-list failure — nothing was ever
-    //     dispatchable.
-    //   - FULLY TERMINAL (owner manual-validation finding 3): every resolvable
-    //     unit already ran to a terminal state, but the step never finalized (a
-    //     required-gate block that was resumed, or a crash before completion). The
-    //     units show `done`/`failed` with no report command, so without this the
-    //     driver is stranded — `--settle` runs the shared completion path.
-    // Never while a live engine lease owns the spine (a report/settle is refused
-    // then anyway). `--expect-step` guards a stale copy once the spine moves.
-    const hasReportableWork = !isRouteOnly && !workList.error && workList.units.some((u) => u.resolved.ok);
-    const nonDispatching = !hasReportableWork;
-    const settleable = !leaseLive && (nonDispatching || fullyTerminal);
-    const settleCommand = settleable ? `akm workflow report ${run.id} --settle --expect-step ${stepState.id}` : undefined;
-    const settleState = !settleable
-        ? "none"
-        : fullyTerminal
-            ? "finalize"
-            : "non-dispatching";
-    const message = buildMessage(step, workList, route, gateLoop, settleState);
-    return {
-        ...base,
-        // Re-stamp the spine token with the resolved active step + real gate loop.
-        spineToken: makeSpineToken(run.id, stepState.id, gateLoop, watermark),
-        active: true,
-        step,
-        ...(gateFeedback ? { gateFeedback } : {}),
-        workList,
-        ...(route ? { route } : {}),
-        ...(settleCommand ? { settleCommand } : {}),
-        message,
-    };
-}
-/**
- * The spine watermark stamped on every brief (#14): run id, active step id,
- * gate loop, and a run-mutation watermark (`updated_at` + journal row count). A
- * driver diffs it across polls to notice the spine moved; `report --expect-step`
- * enforces the step half server-side.
- */
-function makeSpineToken(runId, stepId, gateLoop, watermark) {
-    return `${runId}#${stepId ?? "-"}#l${gateLoop}#${watermark}`;
-}
-// ── Helpers ──────────────────────────────────────────────────────────────────
-function toBriefUnit(runId, unit, stepId, journaled, ctx) {
-    if (!unit.engine || !unit.invocation) {
-        throw new UsageError(`Unit "${unit.unitId}" has no complete frozen engine attribution.`);
-    }
-    const action = deriveUnitAction(unit, journaled, ctx);
-    const report = reportCommandForAction(runId, unit, stepId, action, journaled?.claim_holder ?? null);
-    return {
-        unitId: unit.unitId,
-        nodeId: unit.nodeId,
-        index: unit.index,
-        engine: unit.invocation.engine,
-        runtimeKind: unit.runner,
-        platform: unit.engine.kind === "agent" ? unit.engine.platform : null,
-        model: unit.invocation.model,
-        timeoutMs: unit.timeoutMs,
-        ...(unit.schema ? { outputSchema: unit.schema } : {}),
-        // Env asset REF names only — brief never resolves bindings, so no secret
-        // value can ever reach this output.
-        ...(unit.env ? { env: unit.env } : {}),
-        ...(unit.retry ? { retry: unit.retry } : {}),
-        onError: unit.onError,
-        ...(unit.isFanOut ? { item: unit.item } : {}),
-        resolved: unit.resolved.ok
-            ? { ok: true, instructions: unit.resolved.prompt, inputHash: unit.resolved.inputHash }
-            : { ok: false, error: unit.resolved.error },
-        ...(journaled ? { journaled: toBriefJournaled(journaled) } : {}),
-        action,
-        ...(report ? { report } : {}),
-    };
-}
-/**
- * Fold the journaled row + engine lease + resolvability into ONE driver-facing
- * action (#15). A live engine lease or an unresolvable unit is `do_not_run`; a
- * terminal row is `done`/`failed`; a live claim is `claimed` (or `stale` once
- * silent); no row is `pending`.
- */
-function deriveUnitAction(unit, journaled, ctx) {
-    if (!unit.resolved.ok)
-        return "do_not_run";
-    if (ctx.leaseLive)
-        return "do_not_run";
-    if (!journaled)
-        return "pending";
-    if (journaled.status === "completed")
-        return "done";
-    if (journaled.status === "failed")
-        return "failed";
-    if (journaled.status === "running")
-        return ctx.stale ? "stale" : "claimed";
-    return "pending";
-}
-function toBriefJournaled(row) {
-    // Claim state is meaningful only while the unit is still running; a terminal
-    // row keeps its claim columns but they are no longer actionable.
-    const claim = row.status === "running"
-        ? {
-            ...(row.claim_holder ? { claimedBy: row.claim_holder } : {}),
-            ...(row.claim_expires_at ? { claimExpiresAt: row.claim_expires_at } : {}),
-        }
-        : {};
-    return {
-        unitId: row.unit_id,
-        status: row.status,
-        ...(row.failure_reason ? { failureReason: row.failure_reason } : {}),
-        ...(row.tokens !== null ? { tokens: row.tokens } : {}),
-        ...(row.started_at ? { startedAt: row.started_at } : {}),
-        ...(row.finished_at ? { finishedAt: row.finished_at } : {}),
-        ...claim,
-    };
-}
-/**
- * The `report` command line for a unit, tailored to its action (#15). Terminal
- * `done` and `do_not_run` units get NO command; a `failed` unit gets the
- * `--rerun` form (records a fresh attempt, per #25); `pending`/`stale`/`claimed`
- * get the completed form. Every command carries `--expect-step` (#14) so a
- * copy-pasted command from a stale brief is refused once the spine moves on.
- *
- * A `claimed` unit is held by a LIVE `--status running` claim (`claimHolder`):
- * ONLY that holder can finish it — the report path's claim compare-and-set
- * refuses any other `--session-id`. So its command carries `--session-id
- * <holder>`, which (a) is the exact form the holding driver must use to finish
- * its OWN claim, and (b) makes it unmistakable to a SECOND driver that the unit
- * is spoken for rather than free, runnable work (owner manual-validation
- * finding 2: two drivers must not both treat a live-claimed unit as free). A
- * `stale` unit's claim has expired and is freely reclaimable/finishable by
- * anyone, so it keeps the plain completed form (no `--session-id`).
- */
-function reportCommandForAction(runId, unit, stepId, action, claimHolder) {
-    if (action === "done" || action === "do_not_run")
-        return undefined;
-    const resultHint = unit.schema
-        ? "--result-file <result.json>   # JSON matching the unit's outputSchema"
-        : "--result-file <result.txt>    # or --result '<text>' / pipe via stdin";
-    const rerun = action === "failed" ? " --rerun" : "";
-    // A live claim requires its holder's --session-id to finish; surface it so the
-    // holder's command is correct and other drivers see the unit is claimed.
-    const session = action === "claimed" && claimHolder ? ` --session-id ${claimHolder}` : "";
-    return `akm workflow report ${runId} --unit ${unit.unitId} --expect-step ${stepId} --status completed${rerun}${session} ${resultHint}`;
-}
-export function buildLease(holder, until) {
-    if (!holder || !until)
-        return undefined;
-    return { holder, until, live: until >= new Date().toISOString() };
-}
-function buildMessage(step, workList, route, gateLoop, settleState) {
-    const loopNote = gateLoop > 1 ? ` (gate loop ${gateLoop}, addressing prior rejection feedback)` : "";
-    const settleNote = settleState !== "none" ? " Advance it with `akm workflow report --settle` (see settleCommand)." : "";
-    if (step.kind === "route") {
-        const decided = route?.decision ? ` → selects step "${route.decision.selected}"` : "";
-        return `Active step "${step.stepId}" is a route step — no units to execute${decided}.${settleNote || " Advances deterministically."}`;
-    }
-    if (workList.error) {
-        return `Active step "${step.stepId}" could not compute a work-list: ${workList.error}${settleNote}`;
-    }
-    const n = workList.units.length;
-    if (settleState === "finalize") {
-        // Fully-terminal work-list on a still-active step: everything ran, nothing
-        // remains to execute — the step only needs finalization (the run was
-        // gate-blocked then resumed, or a crash interrupted completion). A required
-        // gate with no judge available will re-block, which is correct behavior.
-        const gateNote = step.gate.required && step.gate.criteria.length > 0
-            ? " If this step's REQUIRED gate has no judge available it will re-block, pending a configured judge or a manual `akm workflow complete`."
-            : "";
-        return (`Active step "${step.stepId}" has run all ${n} unit(s) to a terminal state${loopNote} — nothing remains to ` +
-            `execute or report. Finalize it with \`akm workflow report --settle\` (see settleCommand): the gate is judged ` +
-            `and the step advances.${gateNote}`);
-    }
-    if (settleState === "non-dispatching") {
-        return `Active step "${step.stepId}" dispatches no reportable units${loopNote}.${settleNote}`;
-    }
-    return `Active step "${step.stepId}" expects ${n} unit(s)${loopNote}. Execute them, then report each result.`;
-}
-/**
- * Resolve `target` to a concrete run id WITHOUT starting anything. A run id
- * resolves directly; a workflow ref resolves to its active run in the current
- * scope, and NO active run is a NotFoundError (brief never auto-starts — that
- * would mutate).
- */
-export async function resolveRunId(target) {
-    return withWorkflowRunsRepo((repo) => {
-        const byId = repo.getRunById(target);
-        if (byId)
-            return byId.id;
-        // Run-id vs workflow-ref: a run id has no `/`; canonical workflow refs do.
-        if (!target.includes(":") && !target.includes("/")) {
-            throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
-        }
-        const parsed = parseRefInput(target);
-        if (parsed.type !== "workflow") {
-            throw new UsageError(`Expected a workflow run id or workflow ref (workflows/<name>), got "${target}".`);
-        }
-        const ref = canonicalWorkflowRunRef(parsed.origin, canonicalizeWorkflowName(parsed.name));
-        const active = repo.getActiveRunRowForScope(ref, getCurrentWorkflowScopeKey());
-        if (!active) {
-            throw new NotFoundError(`No active workflow run for ${ref} in this scope. \`akm workflow brief\` describes an existing run and never ` +
-                `starts one — run \`akm workflow start ${ref}\` (or \`akm workflow run ${ref}\`) first.`, "WORKFLOW_NOT_FOUND");
-        }
-        return active.id;
-    });
-}