akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/workflows/exec/param-secrets.js

@@ -8,20 +8,20 @@
  *
  * A workflow's run params are interpolated into every unit prompt
  * (`buildUnitPrompt` → `{{PARAMS_JSON}}` + `${{ params.* }}` references) and,
- * critically, are part of the unit's **input hash**. The harness-neutral driver
- * protocol (`akm workflow brief`) MUST surface the byte-identical prompt an
- * external driver has to execute — redacting a param would change the prompt the
- * driver runs, break the input-hash contract, and defeat cross-surface parity.
- * So params CANNOT be redacted and are declared **non-secret**: secrets belong
- * in **env bindings** (`env:` refs), which `brief` surfaces by NAME ONLY and
- * never resolves.
+ * critically, are part of the unit's **input hash**. The prompt an executor runs
+ * must be byte-identical to the one the hash was taken over — redacting a param
+ * would change the prompt, break the input-hash contract, and make a resumed or
+ * replayed run diverge from the original. So params CANNOT be redacted and are
+ * declared **non-secret**: secrets belong in **env bindings** (`env:` refs),
+ * which are carried by NAME ONLY through the plan and the hash preimage and are
+ * resolved from the process environment at dispatch.
  *
  * This module is the loud, best-effort guardrail on top of that contract: it
  * scans params for values that LOOK like credentials (secret-suggesting key
  * names, long high-entropy strings, known token prefixes) and returns WARNING
  * strings. It is purely advisory — it NEVER blocks a run and NEVER mutates
- * params — and is surfaced both at `start` and in every `brief`. False positives
- * and false negatives are expected; it is a nudge, not a scanner.
+ * params — and is surfaced when a run starts. False positives and false
+ * negatives are expected; it is a nudge, not a scanner.
  */
 /**
  * Substrings that, when present in a param KEY (case-insensitive), suggest the

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

@@ -2,10 +2,9 @@
 // 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/.
 /**
- * Engine-driven workflow execution — `akm workflow run` (orchestration plan
- * P1, owner decision 5). akm itself walks the plan and dispatches units; the
- * existing `next`/`complete` loop remains for manual/agent-driven advancement
- * of the same runs.
+ * Engine-driven workflow execution — the `akm workflow run`
+ * start/resume/execute path, and the single execution surface for a run: akm
+ * walks the frozen plan and dispatches every unit itself.
  *
  * Invariant (plan §*Never bypass the gate spine*): every step advances
  * through `completeWorkflowStep`, never by writing step rows directly, so the
@@ -37,17 +36,17 @@
  * 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`).
+ * live, any competing spine advance is refused — the engine owns the run while
+ * driving (enforced inside `completeWorkflowStep`).
  *
  * Process-lifecycle contract (owner finding 4 — no leaked handles): the SDK
  * dispatch path caches `opencode serve` CHILD PROCESSES in a per-env registry
@@ -69,17 +68,51 @@ 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 { completeWorkflowStep, getNextWorkflowStep, resumeWorkflowRun } from "../runtime/runs.js";
 import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
 import { frozenSummaryJudge } from "./frozen-judge.js";
-import { executeStepPlan } from "./native-executor.js";
+import { defaultUnitDispatcher, 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).
+// (`finalizeExecutedStep`) live in step-work.ts as ONE implementation, so the
+// fresh-execution and resume paths cannot drift from each other.
 import { activeGateLoop, cascadeSkippedRouter, finalizeExecutedStep, recoverGateFeedback, seedJournaledRouteDecisions, } from "./step-work.js";
 export async function runWorkflowSteps(options) {
-    const next = await getNextWorkflowStep(options.target, options.params);
+    let target = options.target;
+    let params = options.params;
+    let parameterFlags = options.parameterFlags;
+    let remainingRetries = options.maxRetries ?? 0;
+    let remainingSteps = options.maxSteps;
+    const executed = [];
+    for (;;) {
+        const result = await runWorkflowAttempt({
+            ...options,
+            target,
+            ...(params !== undefined ? { params } : { params: undefined }),
+            ...(parameterFlags !== undefined ? { parameterFlags } : { parameterFlags: undefined }),
+            ...(remainingSteps !== undefined ? { maxSteps: remainingSteps } : { maxSteps: undefined }),
+        });
+        executed.push(...result.executed);
+        const aggregate = { ...result, executed };
+        if (result.run.status !== "failed" || result.aborted || result.gateRejection || remainingRetries <= 0) {
+            return aggregate;
+        }
+        if (remainingSteps !== undefined) {
+            remainingSteps -= result.executed.length;
+            if (remainingSteps <= 0)
+                return aggregate;
+        }
+        await resumeWorkflowRun(result.run.id);
+        target = result.run.id;
+        params = undefined;
+        parameterFlags = undefined;
+        remainingRetries -= 1;
+    }
+}
+async function runWorkflowAttempt(options) {
+    const next = await getNextWorkflowStep(options.target, options.params, {
+        parameterFlags: options.parameterFlags,
+    });
     // Version/canonical/hash validation precedes every executable mutation,
     // including lease acquisition. Historical rows remain inspectable/abandonable.
     if (!next.done && !options.loadPlan) {
@@ -125,7 +158,11 @@ export async function runWorkflowSteps(options) {
         : undefined;
     heartbeat?.start();
     try {
-        return await driveRun(options, next, leaseHolder, heartbeat);
+        const result = await driveRun(options, next, leaseHolder, heartbeat);
+        // Creation-time notices reach the caller only here: the run row has no
+        // warnings column, and a later invocation of the same run must stay silent
+        // about a decision it did not make. `driveRun` never sets `warnings`.
+        return next.startWarnings?.length ? { ...result, warnings: next.startWarnings } : result;
     }
     finally {
         heartbeat?.stop();
@@ -294,30 +331,34 @@ class LeaseHeartbeat {
         this.detachUpstream?.();
     }
 }
+/**
+ * A terminal run is a pure no-op: do not load or integrity-check its frozen
+ * plan, because post-completion plan corruption cannot change finished work.
+ */
+async function completedRunResult(runId) {
+    const doneState = await getNextWorkflowStep(runId);
+    return {
+        run: doneState.run,
+        executed: [],
+        ...(doneState.run.status === "completed" ? { done: true } : {}),
+    };
+}
+function workflowSummaryJudge(options, plan, stepPlan, signal) {
+    if (options.summaryJudge !== undefined)
+        return options.summaryJudge;
+    return frozenSummaryJudge(plan, stepPlan.gate.judge, signal, options.dispatcher ?? defaultUnitDispatcher);
+}
 /** The engine loop proper — runs under the lease held by `runWorkflowSteps`. */
 async function driveRun(options, initial, leaseHolder, heartbeat) {
     let next = initial;
-    // A terminal (completed) run is a PURE no-op. `runWorkflowSteps` already
-    // skipped lease acquisition for a done run (`leased = !next.done`), and this
-    // path must ALSO refuse to read the journal or load/integrity-check the
-    // frozen plan: a run that finished cleanly, then had its `plan_json` corrupted
-    // or tampered afterwards, must still report `done` here rather than throwing a
-    // frozen-plan integrity error (loadFrozenPlan would). Nothing will dispatch
-    // and the engine_lease_* columns stay exactly as they were, so return the
-    // fresh run state immediately.
-    if (initial.done) {
-        const doneState = await getNextWorkflowStep(initial.run.id);
-        return {
-            run: doneState.run,
-            executed: [],
-            ...(doneState.run.status === "completed" ? { done: true } : {}),
-        };
-    }
+    if (initial.done)
+        return completedRunResult(initial.run.id);
     // The effective dispatch signal: the heartbeat's controller (a lost lease or
     // a caller abort aborts it) while leased, else the raw caller signal.
     const dispatchSignal = heartbeat?.signal ?? options.signal;
     const executed = [];
     let gateRejection;
+    let aborted = false;
     const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY;
     // Seed the lifetime unit cap AND the budget ceilings from the journal so
     // both are truly per-RUN: a resumed or re-invoked run must not restart the
@@ -349,17 +390,16 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
     let tokensUsed = journaledDispatches.reduce((sum, row) => sum + (row.tokens ?? 0), 0);
     // 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, next.run.workflowRef);
+    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
-    // params — post-start corruption — fail loudly and IDENTICALLY, preserving
-    // cross-surface parity (start already validated the params it stored).
+    // schemas before the engine resolves any unit prompt from it, so
+    // schema-violating params — post-start corruption — fail loudly BEFORE any
+    // unit is dispatched (start already validated the params it stored).
     assertRunParamsSatisfyPlan(next.run.id, plan, next.run.params ?? {});
     // Route bookkeeping: targets a completed router did NOT select are skipped
     // when the spine reaches them; a target ANY router selected is protected
@@ -373,7 +413,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);
@@ -383,8 +423,10 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
         // another engine owns the spine now. A caller abort (options.signal) is a
         // graceful break, distinct from a lost lease.
         heartbeat?.assertAlive();
-        if (options.signal?.aborted)
+        if (options.signal?.aborted) {
+            aborted = true;
             break;
+        }
         // Renew the run lease between steps (a fresh 90s window per iteration).
         // Losing it (expired mid-step + claimed by another engine) throws — the
         // new owner drives the spine now.
@@ -392,8 +434,8 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
         const step = next.step;
         const stepPlan = plan.steps.find((s) => s.stepId === step.id);
         if (!stepPlan) {
-            throw new UsageError(`Step "${step.id}" of run ${next.run.id} is not present in the current workflow asset (${next.run.workflowRef}). ` +
-                `The source file changed since the run started — advance this step manually with \`akm workflow complete\`.`);
+            throw new UsageError(`Step "${step.id}" of run ${next.run.id} is not present in its frozen workflow plan (${next.run.workflowRef}). ` +
+                "The run journal is inconsistent; abandon this run and start a new one.");
         }
         // A branch target no completed router selected → auto-skip, no dispatch.
         const skipInfo = routeUnselected.get(step.id);
@@ -414,7 +456,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
@@ -437,13 +479,13 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
         // final rejection — this invocation is done.
         const maxLoops = Math.max(1, stepPlan.gate.maxLoops ?? 1);
         // Crash-resume gate state (Codex P1): SEED the starting gate loop from the
-        // journal exactly as the brief/report surfaces do — the SAME shared helpers,
-        // no fork. A run interrupted after a rejected gate was journaled
+        // journal through the SAME shared helpers the first pass used — no fork.
+        // A run interrupted after a rejected gate was journaled
         // (`<step>.gate:l<n>`, complete:false) must resume at loop n+1 with the
         // stored corrective feedback threaded into the unit prompts; without this
         // the engine restarts at loop 1, reuses the rejected loop-1 rows, overwrites
         // `<step>.gate:l1`, and re-judges the stale artifact — breaking journaled
-        // replay and diverging from what brief computes for the same run. The rows
+        // replay and making the resumed run diverge from the interrupted one. The rows
         // are re-read here (NOT the once-at-start `journaledUnits` budget seed) so a
         // step reached later within THIS same invocation still starts fresh at loop 1.
         const stepJournal = await withWorkflowRunsRepo((repo) => repo.getUnitsForRun(next.run.id));
@@ -484,6 +526,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,
@@ -508,6 +551,11 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
             unitsDispatched = result.unitsDispatched;
             if (result.tokensUsed !== undefined)
                 tokensUsed = result.tokensUsed;
+            if (options.signal?.aborted) {
+                aborted = true;
+                stopEngine = true;
+                break;
+            }
             executed.push({
                 stepId: step.id,
                 ok: result.ok,
@@ -517,29 +565,42 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
             });
             // Route evaluation + artifact-judged completion gate + gate-row
             // journaling + the bounded-loop rejection contract are the SHARED
-            // completion path (`finalizeExecutedStep`): the R3 report surface drives
-            // the identical sequence, so an engine-driven and a report-driven run of
-            // the same frozen plan promote the same artifact and advance (or reject)
-            // the spine identically. The engine owns only the loop control the result
-            // maps onto (retry re-executes; advanced moves on; failure/exhaustion
-            // stops this invocation).
-            const finalize = await finalizeExecutedStep({
-                runId: next.run.id,
-                workflowRef: next.run.workflowRef,
-                stepId: step.id,
-                stepPlan,
-                completionCriteria: stepPlan.gate.criteria,
-                gateLoop,
-                loopsRemaining: gateLoop < maxLoops,
-                result,
-                priorEvidence: evidence,
-                params: next.run.params ?? {},
-                routeSelected,
-                routeUnselected,
-                summaryJudge: options.summaryJudge === undefined ? frozenSummaryJudge(plan, stepPlan.gate.judge) : options.summaryJudge,
-                ...(options.requireGates ? { requireGates: true } : {}),
-                leaseHolder,
-            });
+            // completion path (`finalizeExecutedStep`): every step advances through
+            // that one sequence, whether its units were just dispatched or rehydrated
+            // from the journal on resume, so the same frozen plan always promotes the
+            // same artifact and advances (or rejects) the spine identically. The
+            // engine owns only the loop control the result maps onto (retry
+            // re-executes; advanced moves on; failure/exhaustion stops this invocation).
+            let finalize;
+            try {
+                finalize = await finalizeExecutedStep({
+                    runId: next.run.id,
+                    workflowRef: next.run.workflowRef,
+                    stepId: step.id,
+                    stepPlan,
+                    completionCriteria: stepPlan.gate.criteria,
+                    gateLoop,
+                    loopsRemaining: gateLoop < maxLoops,
+                    result,
+                    priorEvidence: evidence,
+                    params: next.run.params ?? {},
+                    routeSelected,
+                    routeUnselected,
+                    summaryJudge: workflowSummaryJudge(options, plan, stepPlan, dispatchSignal),
+                    signal: options.signal,
+                    leaseHolder,
+                });
+            }
+            catch (error) {
+                heartbeat?.assertAlive();
+                if (options.signal?.aborted) {
+                    aborted = true;
+                    stopEngine = true;
+                    break;
+                }
+                throw error;
+            }
+            heartbeat?.assertAlive();
             if (finalize.kind === "retry") {
                 // Re-execute the subgraph with the judge/validation feedback threaded
                 // into unit prompts — the changed prompt changes each unit's input
@@ -564,14 +625,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;
@@ -587,6 +640,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
         executed,
         ...(finalState.run.status === "completed" ? { done: true } : {}),
         ...(gateRejection ? { gateRejection } : {}),
+        ...(aborted ? { aborted: true } : {}),
     };
 }
 /**
@@ -596,10 +650,10 @@ 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.
- * Historical v2/null rows are inspection-only in the engine cutover. They are
- * never recompiled from a mutable source asset.
+ * 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;