akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/workflows/db.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { getWorkflowDbPath } from "../core/paths.js";
 import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
 /**
  * workflow.db — Durable SQLite database for workflow run state.
  *
@@ -46,12 +47,10 @@ export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
         fs.mkdirSync(dir, { recursive: true });
     }
     const db = openDatabase(dbPath);
-    db.exec("PRAGMA journal_mode = WAL");
     // #589: 30 s busy timeout, matching index.db / state.db. Without it the
     // default is 0 ms, so any concurrent writer fails immediately with
-    // SQLITE_BUSY.
-    db.exec("PRAGMA busy_timeout = 30000");
-    db.exec("PRAGMA foreign_keys = ON");
+    // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
+    applyStandardPragmas(db, { dataDir: dir });
     ensureBaseSchema(db);
     runMigrations(db);
     return db;
@@ -166,6 +165,141 @@ const MIGRATIONS = [
       ALTER TABLE workflow_run_steps ADD COLUMN summary TEXT;
     `,
     },
+    // ── Migration 004 — per-unit run state (orchestration plan P1) ──────────────
+    //
+    // A step's execution may now fan out into N concurrent units (native
+    // executor, docs/technical/akm-workflows-orchestration-plan.md). Units hang
+    // off the gated step spine: `workflow_run_steps` stays the durable top-level
+    // record; each dispatched unit gets its own row here so a crash-and-resume
+    // re-dispatches only incomplete units (durable-row resume) and budget/usage
+    // is attributable per unit. `input_hash` is reserved for the P5 deterministic
+    // replay mode; `failure_reason` carries runAgent's structured failure
+    // vocabulary so retry/continue-on-error policy has semantics to act on.
+    {
+        id: "004-workflow-run-units",
+        up: `
+      CREATE TABLE IF NOT EXISTS workflow_run_units (
+        run_id         TEXT NOT NULL,
+        unit_id        TEXT NOT NULL,
+        step_id        TEXT,
+        node_id        TEXT NOT NULL,
+        parent_unit_id TEXT,
+        phase          TEXT,
+        runner         TEXT,
+        model          TEXT,
+        status         TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped')),
+        input_hash     TEXT,
+        result_json    TEXT,
+        tokens         INTEGER,
+        failure_reason TEXT,
+        worktree_path  TEXT,
+        started_at     TEXT,
+        finished_at    TEXT,
+        PRIMARY KEY (run_id, unit_id),
+        FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_workflow_run_units_run_step
+        ON workflow_run_units(run_id, step_id);
+    `,
+    },
+    // ── Migration 005 — harness-native unit session id (plan P2) ────────────────
+    //
+    // The P2 harness adapters' result extractors reveal the harness-native
+    // session id of a dispatched unit (codex `session_configured`, gemini/pi
+    // JSON envelopes, the opencode SDK session). It is stored opportunistically
+    // on the unit row so resume can replay the harness's own context cache
+    // (e.g. `codex exec resume <id>`, `gemini --resume <id>`); akm never
+    // *depends* on it — `workflow_run_units` remains the durable source of
+    // truth (plan §"Session, MCP, and identity across harnesses").
+    {
+        id: "005-unit-session-id",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN session_id TEXT;
+    `,
+    },
+    // ── Migration 006 — frozen plan + engine lease (redesign addendum, R1) ──────
+    //
+    // `workflow start` now compiles the workflow into its plan graph ONCE and
+    // freezes it on the run row: `plan_json` holds the canonical plan JSON
+    // (`ir/plan-hash.ts`) and `plan_hash` its sha256, so every subsequent
+    // invocation executes the frozen snapshot with an integrity check — the
+    // source file is never re-read for an in-flight run. Runs created before
+    // this migration have NULL plan_json (legacy) and fall back to
+    // compile-from-asset with a warning.
+    //
+    // `engine_lease_until` / `engine_lease_holder` reserve the run-lease columns
+    // (a second `workflow run` on a leased run refuses up front). TODO(R2):
+    // lease ENFORCEMENT is engine-rework scope — only the columns land now.
+    {
+        id: "006-frozen-plan-and-lease",
+        up: `
+      ALTER TABLE workflow_runs ADD COLUMN plan_json TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN plan_hash TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN engine_lease_until TEXT;
+      ALTER TABLE workflow_runs ADD COLUMN engine_lease_holder TEXT;
+    `,
+    },
+    // ── Migration 007 — unit-level check-in heartbeat (redesign addendum, R3) ────
+    //
+    // The harness-neutral driver protocol lets ANY agent session claim and
+    // heartbeat a unit it is executing via `akm workflow report --status running`.
+    // `last_checkin_at` records the most recent heartbeat (distinct from
+    // `started_at`, the first claim) so a pure timestamp evaluator
+    // (`runtime/unit-checkin.ts`) can surface a claimed-but-silent unit as stale
+    // in `workflow brief` without any background thread. Nullable and additive;
+    // engine-dispatched rows never set it (they finish before a heartbeat window
+    // could elapse), so their transient `running` state is judged from
+    // `started_at`.
+    {
+        id: "007-unit-last-checkin",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN last_checkin_at TEXT;
+    `,
+    },
+    // ── Migration 008 — per-unit dispatch-attempt counter (PR #714 review, P2) ───
+    //
+    // `workflow_run_units.unit_id` is CONTENT-derived and stable across
+    // crash/resume (retries/loops carry `~r<n>`/`~l<loop>` suffixes, so they are
+    // DISTINCT rows). A crash between a unit's dispatch (`insertUnit`, status
+    // `running`) and its finish leaves a stale `running` row; durable-row resume
+    // re-dispatches the SAME unit_id and `insertUnit` REPLACES that single row.
+    // Because the run's budget/lifetime seed was derived from the NUMBER of unit
+    // rows, each crash/resume of one unit erased the prior dispatch from
+    // `budget.max_units` / lifetime-cap accounting, letting a run spend past its
+    // declared ceiling. `attempts` counts how many times a row was (re)dispatched
+    // — incremented by `insertUnit` on every REPLACE of an existing row — so both
+    // budget seeds sum `attempts` instead of counting rows and crash-retried
+    // dispatches are charged. Existing rows back-fill to 1 (one dispatch each).
+    {
+        id: "008-unit-attempts",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN attempts INTEGER NOT NULL DEFAULT 1;
+    `,
+    },
+    // ── Migration 009 — per-unit claim ownership (PR #714 review round 2) ─────────
+    //
+    // `akm workflow report --status running` claims a unit before executing it.
+    // Round-2 review (#3): a running row had no claim owner, no compare-and-set,
+    // and no stale-hash guard, so a stale/tampered `running` row could be
+    // finalized by anyone with a fresh result while keeping an old input_hash.
+    // These columns record who holds the claim (`claim_holder` — the driver's
+    // `--session-id` or a token report mints and returns) and until when
+    // (`claim_expires_at`, ISO-8601 UTC). Heartbeating or finishing a live-claimed
+    // running row requires the matching holder; an EXPIRED claim is reclaimable by
+    // a new holder (crash recovery). The TTL equals the unit-checkin stale window
+    // (`runtime/unit-checkin.UNIT_STALE_MS`), so an expired claim is exactly a unit
+    // that `workflow brief` already surfaces as stale. Both columns are nullable
+    // and additive: engine-dispatched rows and simple claimless drivers leave them
+    // NULL, and finishing a never-claimed unit stays allowed (input_hash is still
+    // validated always).
+    {
+        id: "009-unit-claim",
+        up: `
+      ALTER TABLE workflow_run_units ADD COLUMN claim_holder TEXT;
+      ALTER TABLE workflow_run_units ADD COLUMN claim_expires_at TEXT;
+    `,
+    },
 ];
 /**
  * Stable id of the scope_key migration. Exported for bootstrap detection and

package/dist/workflows/exec/brief.js

@@ -0,0 +1,484 @@
+// 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 { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
+import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
+import { assertRunParamsSatisfyPlan } from "../ir/params.js";
+import { snapshotRunForDriver } from "../runtime/runs.js";
+import { evaluateStaleUnits } from "../runtime/unit-checkin.js";
+import { detectSecretShapedParams } from "./param-secrets.js";
+import { activeGateLoop, assertJournaledRouteSelectionsValid, computeStepWorkList, evaluateRoute, GATE_EVALUATION_PHASE, isWorkListFullyTerminal, parseFrozenPlan, 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 planJson = runRow.plan_json;
+    const planHash = runRow.plan_hash;
+    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 = loadFrozenPlanForBrief(run.id, planJson, planHash);
+    // 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 = stepState.completionCriteria ?? [];
+    const step = {
+        stepId: stepState.id,
+        title: stepState.title,
+        sequenceIndex: stepState.sequenceIndex ?? 0,
+        kind,
+        instructions: stepState.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,
+            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) {
+    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,
+        runner: unit.runner,
+        ...(unit.profile ? { profile: unit.profile } : {}),
+        ...(unit.model ? { model: unit.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.`;
+}
+/**
+ * brief-specific frozen-plan loader: unlike the engine's loader, a NULL
+ * plan_json is a hard, actionable error rather than a warn-and-compile — brief
+ * describes the frozen plan the engine executes, and a legacy run has none.
+ */
+function loadFrozenPlanForBrief(runId, planJson, planHash) {
+    if (!planJson) {
+        throw new UsageError(`Workflow run ${runId} predates frozen plans (no plan_json on the run row) and cannot be described by ` +
+            `\`akm workflow brief\`. Drive it with engine-driven mode instead: \`akm workflow run ${runId}\` ` +
+            `(which compiles a legacy run's plan from the live asset).`);
+    }
+    return parseFrozenPlan(runId, planJson, planHash);
+}
+/**
+ * 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;
+        if (!target.includes(":")) {
+            throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
+        }
+        const parsed = parseAssetRef(target);
+        if (parsed.type !== "workflow") {
+            throw new UsageError(`Expected a workflow run id or workflow ref (workflow:<name>), got "${target}".`);
+        }
+        const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${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;
+    });
+}