akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/workflows/exec/brief.js

@@ -0,0 +1,478 @@
+// 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 { frozenStepRows, requireExecutableWorkflowPlan } from "../runtime/plan-classifier.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, 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;
+        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;
+    });
+}

package/dist/workflows/exec/frozen-judge.js

@@ -0,0 +1,47 @@
+// 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 { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError } from "../../core/errors.js";
+/** Build a gate judge from a v3 catalog entry without consulting live config. */
+export function frozenSummaryJudge(plan, invocation) {
+    if (!invocation)
+        return null;
+    const engine = plan.execution?.engines[invocation.engine];
+    if (!engine || engine.kind !== "llm")
+        throw new ConfigError(`Frozen gate engine "${invocation.engine}" is unavailable.`, "INVALID_CONFIG_FILE");
+    return async ({ system, user }) => {
+        const { chatCompletion } = await import("../../llm/client.js");
+        return chatCompletion(materialize(engine, invocation), [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ], {
+            timeoutMs: invocation.timeoutMs,
+        });
+    };
+}
+function materialize(engine, invocation) {
+    let apiKey;
+    for (const name of engine.credential?.names ?? []) {
+        const value = process.env[name]?.trim();
+        if (value) {
+            apiKey = value;
+            break;
+        }
+    }
+    if (engine.credential?.required && !apiKey)
+        throw new ConfigError(`Required engine credential ${engine.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    const base = {
+        provider: engine.provider,
+        endpoint: engine.endpoint,
+        model: invocation.model ?? engine.model,
+        ...(engine.temperature !== undefined ? { temperature: engine.temperature } : {}),
+        ...(engine.maxTokens !== undefined ? { maxTokens: engine.maxTokens } : {}),
+        ...(engine.supportsJsonSchema !== undefined ? { supportsJsonSchema: engine.supportsJsonSchema } : {}),
+        ...(engine.extraParams ? { extraParams: engine.extraParams } : {}),
+        ...(engine.contextLength !== undefined ? { contextLength: engine.contextLength } : {}),
+        ...(engine.enableThinking !== undefined ? { enableThinking: engine.enableThinking } : {}),
+        ...(apiKey ? { apiKey } : {}),
+    };
+    return (invocation.llm ? deepMergeConfig(base, invocation.llm) : base);
+}