akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

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

@@ -37,14 +37,14 @@
  * row (`plan_json`, persisted by `startWorkflowRun` under migration 006) with
  * a `plan_hash` integrity check — the workflow asset file is NEVER re-read
  * for an in-flight run, so a mid-run asset edit cannot change behavior.
- * Legacy runs (created before migration 006, NULL plan_json) fall back to
- * compile-from-asset with a warning. Durable-row resume: re-invoking a
- * partially-executed run re-dispatches only work that never completed.
+ * Durable-row resume: re-invoking a partially-executed run re-dispatches only
+ * work that never completed.
  *
  * Run lease (redesign addendum, R2): exactly one engine invocation drives a
  * run at a time. The lease (random holder id + 90s expiry on the run row) is
  * acquired before any dispatch, renewed between steps, and released in a
- * `finally`; a second `workflow run` on a live-leased run refuses up front,
+ * `finally` unless a failed run retains it as forensic state; a second
+ * `workflow run` on a live-leased run refuses up front,
  * and an expired lease is claimable (crash recovery). While the lease is
  * live, manual `workflow complete` is refused too — the engine owns the
  * spine while driving (enforced inside `completeWorkflowStep`).
@@ -62,20 +62,34 @@
  */
 import { randomUUID } from "node:crypto";
 import { UsageError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
+import { withMaintenanceStartBarrierAsync } from "../../core/maintenance-barrier.js";
 import { disposeDispatchResources } from "../../integrations/agent/runner-dispatch.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
 import { assertRunParamsSatisfyPlan } from "../ir/params.js";
+import { computePlanHash } from "../ir/plan-hash.js";
+import { decodeWorkflowPlanV3 } from "../ir/schema.js";
+import { requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
 import { completeWorkflowStep, getNextWorkflowStep } from "../runtime/runs.js";
-import { compileWorkflowAssetPlan, loadWorkflowAsset } from "../runtime/workflow-asset-loader.js";
+import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
+import { frozenSummaryJudge } from "./frozen-judge.js";
 import { executeStepPlan } from "./native-executor.js";
 // Shared step semantics — route evaluation + cascaded-skip bookkeeping,
 // gate-evaluation journaling, and the whole step-completion path
 // (`finalizeExecutedStep`) live in step-work.ts so the engine loop and the R3
 // brief/report driver protocol share ONE implementation (no drift).
-import { activeGateLoop, cascadeSkippedRouter, finalizeExecutedStep, GATE_EVALUATION_PHASE, parseFrozenPlan, recoverGateFeedback, seedJournaledRouteDecisions, } from "./step-work.js";
+import { activeGateLoop, cascadeSkippedRouter, finalizeExecutedStep, recoverGateFeedback, seedJournaledRouteDecisions, } from "./step-work.js";
 export async function runWorkflowSteps(options) {
     const next = await getNextWorkflowStep(options.target, options.params);
+    // Version/canonical/hash validation precedes every executable mutation,
+    // including lease acquisition. Historical rows remain inspectable/abandonable.
+    if (!next.done && !options.loadPlan) {
+        await withWorkflowRunsRepo((repo) => {
+            const row = repo.getRunById(next.run.id);
+            if (!row)
+                throw new UsageError(`Workflow run ${next.run.id} was not found.`);
+            requireExecutableWorkflowPlan(row);
+        });
+    }
     // Refuse non-active runs BEFORE any dispatch — completeWorkflowStep would
     // reject the completion anyway, but only after the units already ran (and
     // cost money). Mirror its preflight up front.
@@ -128,7 +142,7 @@ export async function runWorkflowSteps(options) {
             // hanging on the leaked handle. Runs even if lease release itself fails;
             // a teardown-time repository error must not skip dispatch cleanup.
             try {
-                (options.disposeDispatchResources ?? disposeDispatchResources)();
+                await (options.disposeDispatchResources ?? disposeDispatchResources)();
             }
             catch {
                 /* disposal is best-effort; never let cleanup mask the run outcome */
@@ -148,14 +162,14 @@ function leaseExpiry() {
  * arbiter — two racing invocations cannot both win.
  */
 async function acquireRunLease(runId, holder) {
-    await withWorkflowRunsRepo((repo) => {
+    await withMaintenanceStartBarrierAsync(() => withWorkflowRunsRepo((repo) => {
         if (repo.acquireEngineLease(runId, holder, leaseExpiry(), new Date().toISOString()))
             return;
         const row = repo.getRunById(runId);
         throw new UsageError(`Workflow run ${runId} is already being driven by engine ${row?.engine_lease_holder ?? "(unknown)"} ` +
             `(run lease expires ${row?.engine_lease_until ?? "(unknown)"}). A second \`akm workflow run\` would race it — ` +
             `wait for that invocation to finish or for the lease to expire.`);
-    });
+    }));
 }
 /**
  * Renew the lease between steps. Losing the lease mid-run (it expired during
@@ -333,11 +347,14 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
     const journaledDispatches = journaledUnits.filter((row) => row.phase !== GATE_EVALUATION_PHASE);
     let unitsDispatched = journaledDispatches.reduce((sum, row) => sum + row.attempts, 0);
     let tokensUsed = journaledDispatches.reduce((sum, row) => sum + (row.tokens ?? 0), 0);
-    // One plan per invocation: the test seam receives the workflow ref; the
-    // default reads the run's frozen plan and never touches the asset file.
-    const plan = options.loadPlan
-        ? await options.loadPlan(next.run.workflowRef)
-        : await loadFrozenPlan(next.run.id, next.run.workflowRef);
+    // The decoded/hash-verified row plan is the sole execution authority. The
+    // loader seam may assert an expected plan in tests, but can never replace it.
+    const plan = await loadFrozenPlan(next.run.id);
+    if (options.loadPlan) {
+        const expected = decodeWorkflowPlanV3(await options.loadPlan(next.run.workflowRef));
+        if (computePlanHash(expected) !== computePlanHash(plan))
+            throw new UsageError(`Injected workflow plan for run ${next.run.id} differs from its frozen plan.`);
+    }
     // Reviewer #12: the journaled params row must still satisfy the frozen param
     // schemas before the engine resolves any unit prompt from it. Applied on ALL
     // THREE driver surfaces (engine here, brief, report) so schema-violating
@@ -356,7 +373,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
     // the unselected targets with empty in-memory state and execute the wrong
     // branch. Decisions stay pure functions of (frozen plan, params, journaled
     // results) — the addendum determinism bar. A done run skips the seeding:
-    // nothing will dispatch, so an unrecoverable historical decision must not
+    // nothing will dispatch, so an unrecoverable prior decision must not
     // block the no-op status return below.
     if (!next.done) {
         seedJournaledRouteDecisions(plan, next, routeSelected, routeUnselected);
@@ -397,7 +414,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
             next = await getNextWorkflowStep(next.run.id);
             continue;
         }
-        // `dependsOn` edges (reserved in IR v2 — no frontend emits them today,
+        // `dependsOn` edges (no frontend emits them today,
         // but a frozen plan may carry them) are a declared ordering contract:
         // every dependency must already be resolved before this step dispatches.
         // Execution is sequential (spine order), so a violation means the plan
@@ -467,6 +484,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
                 }
                 : await executeStepPlan(stepPlan, {
                     runId: next.run.id,
+                    leaseHolder,
                     workflowRef: next.run.workflowRef,
                     params: next.run.params ?? {},
                     evidence,
@@ -475,13 +493,14 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
                     // Budget ceilings ride the FROZEN plan (addendum R2): a mid-run
                     // asset edit can never loosen or tighten a run's budget.
                     ...(plan.budget ? { budget: plan.budget } : {}),
+                    ...(plan.execution ? { engines: plan.execution.engines } : {}),
                     gateLoop,
                     ...(gateFeedback ? { gateFeedback } : {}),
                     // The heartbeat's signal is the effective dispatch signal: a lost
                     // lease (or a caller abort) aborts in-flight units promptly.
                     ...(dispatchSignal ? { signal: dispatchSignal } : {}),
                     ...(options.dispatcher ? { dispatcher: options.dispatcher } : {}),
-                    ...(options.maxConcurrency !== undefined ? { maxConcurrency: options.maxConcurrency } : {}),
+                    maxConcurrency: Math.min(options.maxConcurrency ?? Number.POSITIVE_INFINITY, plan.execution?.maxConcurrency ?? 1),
                 });
             // If the heartbeat lost the lease WHILE this step dispatched, another
             // engine now owns the run — stop loudly BEFORE finalizing the step
@@ -510,7 +529,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
                 workflowRef: next.run.workflowRef,
                 stepId: step.id,
                 stepPlan,
-                completionCriteria: step.completionCriteria ?? [],
+                completionCriteria: stepPlan.gate.criteria,
                 gateLoop,
                 loopsRemaining: gateLoop < maxLoops,
                 result,
@@ -518,8 +537,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
                 params: next.run.params ?? {},
                 routeSelected,
                 routeUnselected,
-                summaryJudge: options.summaryJudge,
-                ...(options.requireGates ? { requireGates: true } : {}),
+                summaryJudge: options.summaryJudge === undefined ? frozenSummaryJudge(plan, stepPlan.gate.judge) : options.summaryJudge,
                 leaseHolder,
             });
             if (finalize.kind === "retry") {
@@ -546,14 +564,6 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
                 stopEngine = true;
                 break;
             }
-            if (finalize.kind === "blocked") {
-                // Reviewer #18: a required gate with no judge available — the step is
-                // BLOCKED (not failed) for a human. The units succeeded, so overwrite the
-                // report's ok/summary to reflect the block, then stop this invocation.
-                executed[executed.length - 1] = { ...executed[executed.length - 1], ok: false, summary: finalize.summary };
-                stopEngine = true;
-                break;
-            }
             // gate-exhausted: rejected with no loop budget left — stop with feedback.
             gateRejection = finalize.gateRejection;
             stopEngine = true;
@@ -578,19 +588,15 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
  *     canonical JSON). A mismatch means the journaled plan was tampered with
  *     or corrupted — fail loudly, never silently recompile. The workflow
  *     asset file is NEVER touched on this path.
- *   - `plan_json` NULL → the run predates frozen plans (created before
- *     migration 006). Warn and fall back to compiling from the live asset,
- *     preserving pre-006 behavior for in-flight legacy runs.
+ * Missing and non-current plans fail validation and are never rebuilt from a
+ * mutable source asset.
  */
-async function loadFrozenPlan(runId, workflowRef) {
+async function loadFrozenPlan(runId) {
     const row = await withWorkflowRunsRepo((repo) => {
         const run = repo.getRunById(runId);
-        return run ? { planJson: run.plan_json, planHash: run.plan_hash } : undefined;
+        return run;
     });
-    if (row?.planJson) {
-        return parseFrozenPlan(runId, row.planJson, row.planHash);
-    }
-    warn(`Workflow run ${runId} predates frozen plans (no plan_json on the run row); ` +
-        `compiling the plan from the live asset ${workflowRef}. New runs freeze their plan at start.`);
-    return compileWorkflowAssetPlan(await loadWorkflowAsset(workflowRef));
+    if (!row)
+        throw new UsageError(`Workflow run ${runId} was not found.`);
+    return requireExecutableWorkflowPlan(row);
 }

package/dist/workflows/exec/scheduler.js

@@ -6,13 +6,12 @@
  *
  * A thin policy layer over `core/concurrent.ts` (`concurrentMap`) — the
  * existing semaphore-bounded pool is generalized, not forked. The scheduler
- * owns the engine-wide limits the plan requires:
+ * owns the limits the plan requires:
  *
- *   - Engine-wide concurrency cap, applied on top of whatever per-step
- *     concurrency the workflow declares. The cap is the `workflow.maxConcurrency`
- *     akm config setting when set (clamped to
- *     `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]`), else the CPU-derived default
- *     `min(16, cores − 2)` (the original Claude-Code-matching formula).
+ *   - The effective width is the minimum of the map request, the frozen
+ *     workflow cap, the selected LLM engine's frozen cap (when applicable),
+ *     and the current host's CPU-derived safety cap. Reapplying host safety at
+ *     dispatch matters when a frozen run resumes on a smaller machine.
  *   - Cooperative cancellation via AbortSignal (workers stop claiming items;
  *     the same signal is passed into each dispatch so in-flight units can be
  *     preempted too).
@@ -24,9 +23,10 @@
  * units impossible to resume (peer review R1). Only work that really
  * dispatches consumes the cap.
  */
-import os from "node:os";
 import { concurrentMap } from "../../core/concurrent.js";
-import { loadConfig } from "../../core/config/config.js";
+import { cpuDerivedUnitConcurrency, workflowMaxConcurrency } from "../concurrency-policy.js";
+import { WORKFLOW_MAX_MAP_EXPANSION } from "../resource-limits.js";
+export { clampMaxConcurrency, cpuDerivedUnitConcurrency, WORKFLOW_MAX_CONCURRENCY_CEILING, } from "../concurrency-policy.js";
 /**
  * Hard ceiling on an EXPLICIT `workflow.maxConcurrency`. A user value above
  * this is clamped down (not rejected) so a config shared across machines with
@@ -34,32 +34,6 @@ import { loadConfig } from "../../core/config/config.js";
  * 64 is deliberately far above any sane fan-out width — it exists only to keep
  * a fat-fingered `100000` from spawning a runaway pool.
  */
-export const WORKFLOW_MAX_CONCURRENCY_CEILING = 64;
-/**
- * CPU-derived engine cap used when `workflow.maxConcurrency` is unset — the
- * original `min(16, cores−2)` formula (matching Claude Code), floored at 1.
- */
-export function cpuDerivedUnitConcurrency(cpuCount = os.cpus()?.length ?? 4) {
-    return Math.min(16, Math.max(1, cpuCount - 2));
-}
-/** Clamp an explicit configured value into `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]`. */
-export function clampMaxConcurrency(value) {
-    return Math.min(WORKFLOW_MAX_CONCURRENCY_CEILING, Math.max(1, Math.floor(value)));
-}
-/**
- * Read `workflow.maxConcurrency` from config, fail-open to `undefined` (use the
- * CPU default) on any load error or a non-numeric value. Kept side-effect-free
- * and defensive: the scheduler must never fail a run because config is unwell.
- */
-function configuredMaxConcurrency() {
-    try {
-        const value = loadConfig().workflow?.maxConcurrency;
-        return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Engine-wide ceiling on concurrent units. Precedence:
  *   1. An explicit `workflow.maxConcurrency` config value, clamped to
@@ -72,13 +46,11 @@ function configuredMaxConcurrency() {
  * @param configured Explicit config value seam (defaults to reading config);
  *                   pass `undefined` explicitly to force the CPU path in a test.
  */
-export function maxUnitConcurrency(cpuCount = os.cpus()?.length ?? 4, configured = configuredMaxConcurrency()) {
-    if (configured !== undefined)
-        return clampMaxConcurrency(configured);
-    return cpuDerivedUnitConcurrency(cpuCount);
+export function maxUnitConcurrency(cpuCount, configured) {
+    return workflowMaxConcurrency(configured, cpuCount);
 }
 /** Lifetime unit cap per run — a runaway-loop backstop, far above real use. */
-export const LIFETIME_UNIT_CAP = 1000;
+export const LIFETIME_UNIT_CAP = WORKFLOW_MAX_MAP_EXPANSION;
 export class UnitCapExceededError extends Error {
     constructor(cap) {
         super(`workflow run exceeded the lifetime unit cap (${cap}). Aborting dispatch — check for a runaway fan-out.`);
@@ -94,7 +66,6 @@ export class UnitCapExceededError extends Error {
  * resume stay free.
  */
 export async function scheduleUnits(items, dispatch, options = {}) {
-    const cap = options.maxConcurrency ?? maxUnitConcurrency();
-    const concurrency = Math.max(1, Math.min(options.concurrency ?? 1, cap));
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 1, options.maxConcurrency ?? Number.POSITIVE_INFINITY, options.llmConcurrency ?? Number.POSITIVE_INFINITY, options.hostConcurrency ?? cpuDerivedUnitConcurrency()));
     return concurrentMap(items, dispatch, concurrency, { signal: options.signal });
 }