akm-cli 0.9.11 → 0.9.13

package/dist/workflows/runtime/plan-classifier.js

@@ -2,6 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { UsageError } from "../../core/errors.js";
+import { warnOnce } from "../../core/warn.js";
 import { decodeCanonicalPlan } from "../ir/plan-hash.js";
 import { WORKFLOW_IR_V5_VERSION } from "../ir/schema-v4.js";
 /** Validate that a live run carries exactly the current frozen-plan format. */
@@ -21,31 +22,33 @@ export function classifyWorkflowRunPlan(row) {
             support: "unsupported-version",
             irVersion: row.plan_ir_version,
             // §3.2's exact complete-or-abandon policy string (A-N2): pre-irVersion-5
-            // plans keep status/list/abandon working but can no longer execute.
-            error: `Workflow run ${runId} was frozen as workflow plan irVersion ${row.plan_ir_version}; pre-irVersion-5 ` +
-                `plans cannot execute after the 0.9.2 upgrade. Complete them before upgrading, or run ` +
-                `'akm workflow abandon ${runId}' and start a new run from the authored workflow. ` +
-                `'akm workflow status' and 'akm workflow list' still work on this run.`,
-        };
-    }
-    if (row.plan_ir_version !== WORKFLOW_IR_V5_VERSION) {
-        return {
-            support: "corrupt-plan",
-            irVersion: null,
-            error: `Workflow run ${runId} does not declare a supported workflow IR version.`,
+            // plans keep status/list/abandon working but can no longer execute. A
+            // version ABOVE the current one (#919) is a distinct situation — never
+            // an "upgrade" problem — so it gets its own text below rather than
+            // being folded into the pre-5 wording.
+            error: row.plan_ir_version < WORKFLOW_IR_V5_VERSION
+                ? // Issue 8: leads with the remedy available to a user who has
+                    `Workflow run ${runId} was frozen as workflow plan irVersion ${row.plan_ir_version}; pre-irVersion-5 ` +
+                        `plans cannot execute after the 0.9.2 upgrade. Run 'akm workflow abandon ${runId}' and start a new ` +
+                        `run from the authored workflow to continue. 'akm workflow status' and 'akm workflow list' still ` +
+                        `work on this run.`
+                : `Workflow run ${runId} was frozen with workflow plan irVersion ${row.plan_ir_version}, which this akm ` +
+                    `(irVersion ${WORKFLOW_IR_V5_VERSION}) does not understand; it was probably written by a newer akm. ` +
+                    `Complete it with that akm version, or run 'akm workflow abandon ${runId}' and start a new run from ` +
+                    `the authored workflow. 'akm workflow status' and 'akm workflow list' still work on this run.`,
         };
     }
     try {
         return {
             support: "supported",
-            irVersion: row.plan_ir_version,
+            irVersion: WORKFLOW_IR_V5_VERSION,
             plan: decodeCanonicalPlan(runId, row.plan_json, row.plan_hash, row.plan_ir_version),
         };
     }
     catch (cause) {
         return {
             support: "corrupt-plan",
-            irVersion: row.plan_ir_version,
+            irVersion: row.plan_ir_version ?? null,
             error: cause instanceof Error ? cause.message : String(cause),
         };
     }
@@ -80,37 +83,82 @@ export function frozenStepRows(plan) {
         sequenceIndex: step.sequenceIndex,
     }));
 }
-/** Verify the durable spine still agrees with the decoded/hash-verified plan before any mutation. */
-export function assertWorkflowSpineMatchesPlan(plan, run, rows) {
-    const expected = frozenStepRows(plan);
+/**
+ * Verify the durable spine's STEP IDENTITY still agrees with the
+ * decoded/hash-verified plan: the same number of steps, and the same set of
+ * step ids. A published plan's own step ids are fixed forever at freeze
+ * time, so a mismatch here means the row set itself is wrong — genuine
+ * corruption, not something a later akm release could have caused by
+ * changing how a field is FORMATTED (that is
+ * {@link reconcileWorkflowSpineWithPlan}'s concern, issue 7).
+ */
+function assertSpineIdentityMatchesPlan(runId, expected, rows) {
     if (rows.length !== expected.length)
-        corruptSpine(run.id, "step count differs from the frozen plan");
-    for (let index = 0; index < expected.length; index++) {
-        const actual = rows[index];
-        const planned = expected[index];
-        // The length check above (corruptSpine returns `never`) guarantees both are
-        // present; the guard narrows them and preserves the "missing row" message.
-        if (!actual || !planned) {
-            corruptSpine(run.id, `step row ${index} differs from the frozen plan (missing row)`);
-        }
-        if (actual.step_id !== planned.stepId ||
-            actual.step_title !== planned.stepTitle ||
-            actual.instructions !== planned.instructions ||
-            actual.completion_json !== planned.completionJson ||
-            actual.sequence_index !== planned.sequenceIndex) {
-            const fields = [
-                actual.step_id !== planned.stepId ? "step_id" : "",
-                actual.step_title !== planned.stepTitle ? "step_title" : "",
-                actual.instructions !== planned.instructions ? "instructions" : "",
-                actual.completion_json !== planned.completionJson ? "completion_json" : "",
-                actual.sequence_index !== planned.sequenceIndex ? "sequence_index" : "",
-            ].filter(Boolean);
-            corruptSpine(run.id, `step row ${index} differs from the frozen plan (${fields.join(", ")})`);
+        corruptSpine(runId, "step count differs from the frozen plan");
+    const expectedIds = new Set(expected.map((step) => step.stepId));
+    for (const row of rows) {
+        if (!expectedIds.has(row.step_id))
+            corruptSpine(runId, `step "${row.step_id}" is not in the frozen plan`);
+    }
+}
+/**
+ * Reconcile the durable spine's PURE-DERIVATION fields (title, instructions,
+ * completion criteria, sequence position) against the plan (issue 7).
+ *
+ * These are recomputed from the plan by {@link frozenStepRows} on every
+ * read; a later akm release changing how one of them is FORMATTED from the
+ * SAME plan data used to mark every in-flight run from the previous release
+ * "corrupt" the moment anything (`akm workflow status`, `resume`, a step
+ * completion) touched it. A mismatch here is warned about, once per run,
+ * rather than blocking the caller — never step identity (row count, which
+ * step ids exist), which stays a hard failure in
+ * {@link assertSpineIdentityMatchesPlan} because the plan cannot have
+ * produced a different step id for an already-frozen run.
+ *
+ * The durable row — not the plan — is what a driving agent actually acts
+ * on: `getNextWorkflowStep` reads `instructions` straight off this row
+ * (`toWorkflowRunStepState`/`projectNextResult` in `runtime/runs.ts`), and
+ * `exec/run-workflow.ts`/`exec/step-work.ts` dispatch from that result. So
+ * warning and proceeding with the STORED row (rather than rewriting it to
+ * match the plan's current formatting) is the conservative choice: the
+ * durable spine is the contract this run has been executing against since
+ * freeze, and a newer akm formatting the same plan data differently should
+ * not retroactively change an in-flight run's instructions out from under
+ * it mid-execution. This module has no write path for that anyway
+ * (`workflow_run_steps` is owned by
+ * `storage/repositories/workflow-runs-repository.ts`) — and it should not
+ * gain one for this purpose. Step
+ * identity (row count, which step ids exist) is the part that would
+ * actually desynchronize execution from the plan, which is exactly why
+ * {@link assertSpineIdentityMatchesPlan} keeps that a hard failure.
+ */
+export function reconcileWorkflowSpineWithPlan(plan, run, rows) {
+    const expected = frozenStepRows(plan);
+    assertSpineIdentityMatchesPlan(run.id, expected, rows);
+    const expectedById = new Map(expected.map((step) => [step.stepId, step]));
+    const drifted = [];
+    for (const row of rows) {
+        const planned = expectedById.get(row.step_id);
+        if (!planned)
+            continue; // unreachable after assertSpineIdentityMatchesPlan; kept defensive.
+        if (row.step_title !== planned.stepTitle ||
+            row.instructions !== planned.instructions ||
+            row.completion_json !== planned.completionJson ||
+            row.sequence_index !== planned.sequenceIndex) {
+            drifted.push(row.step_id);
         }
     }
-    if (run.current_step_id !== null && !expected.some((step) => step.stepId === run.current_step_id))
-        corruptSpine(run.id, `current step ${run.current_step_id} is not in the frozen plan`);
+    if (drifted.length > 0) {
+        warnOnce(`workflow-spine-drift:${run.id}`, `Workflow run ${run.id}: durable step row(s) [${drifted.join(", ")}] no longer match the frozen plan's ` +
+            "title/instructions/completion-criteria/sequence derivation (an akm upgrade likely changed how one of " +
+            "these is formatted from the same plan data). Continuing with the stored row(s) as-is — this run keeps " +
+            "executing against the instructions it was frozen with, rather than having them rewritten mid-flight.");
+    }
+}
+export function assertRunStatusMatchesSpine(run, rows) {
     const current = run.current_step_id ? rows.find((row) => row.step_id === run.current_step_id) : undefined;
+    if (run.current_step_id !== null && !current)
+        corruptSpine(run.id, `current step ${run.current_step_id} is not in the frozen plan`);
     if (run.status === "active") {
         const firstPending = rows.find((row) => row.status === "pending");
         if (!current || current.status !== "pending" || firstPending?.step_id !== current.step_id)

package/dist/workflows/runtime/run-outputs.js

@@ -19,13 +19,6 @@
  */
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
 import { parseReference, resolveReferenceString } from "../program/expressions.js";
-/** Mirrors `runs.ts`'s `WORKFLOW_EVIDENCE_TRUNCATED_MARKER` byte-for-byte — see this file's header for why it is reproduced, not imported. */
-const EVIDENCE_TRUNCATED_MARKER = "__akm_evidence_truncated__";
-function isTruncatedEvidenceValue(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value[EVIDENCE_TRUNCATED_MARKER] === true);
-}
 /** Project a step artifact out of its persisted evidence — mirrors `exec/step-work.ts`'s `projectStepOutput`. */
 function projectStepOutput(evidence) {
     return Object.hasOwn(evidence, "output") ? evidence.output : evidence;
@@ -60,22 +53,11 @@ export function resolveWorkflowRunOutputs(plan, steps) {
             errors.push(`output "${name}": "${declaration.from}" is not a valid step-output reference.`);
             continue;
         }
-        const rootValue = Object.hasOwn(stepOutputs, parsed.expr.stepId) ? stepOutputs[parsed.expr.stepId] : undefined;
-        if (isTruncatedEvidenceValue(rootValue)) {
-            errors.push(`output "${name}" reads step "${parsed.expr.stepId}"'s artifact, which was truncated — it exceeded the ` +
-                `evidence persistence cap and was not stored.`);
-            continue;
-        }
         const resolved = resolveReferenceString(declaration.from, scope);
         if (!resolved.ok) {
             errors.push(`output "${name}": ${resolved.error.message}`);
             continue;
         }
-        if (isTruncatedEvidenceValue(resolved.value)) {
-            errors.push(`output "${name}" reads step "${parsed.expr.stepId}"'s artifact, which was truncated — it exceeded the ` +
-                `evidence persistence cap and was not stored.`);
-            continue;
-        }
         if (declaration.schema) {
             const schemaErrors = validateJsonSchemaSubset(resolved.value, declaration.schema);
             if (schemaErrors.length > 0) {
@@ -86,9 +68,7 @@ export function resolveWorkflowRunOutputs(plan, steps) {
         }
         outputs[name] = resolved.value;
     }
-    if (errors.length > 0)
-        return { ok: false, errors };
-    return { ok: true, outputs };
+    return { outputs, errors };
 }
 /**
  * What a completed run EXPORTS: the resolved declared outputs, or

package/dist/workflows/runtime/runs.js

@@ -16,11 +16,11 @@ import { collectWorkflowWarnings } from "../ir/compile.js";
 import { compileResolveFreezeWorkflowV4 } from "../ir/freeze-v4.js";
 import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
-import { clip, utf8Bytes, WORKFLOW_EVIDENCE_TRUNCATION_PREVIEW_CHARS, WORKFLOW_MAX_EVIDENCE_JSON_BYTES, WORKFLOW_UNIT_DIAGNOSTIC_CLIP, } from "../resource-limits.js";
+import { clip, WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
-import { assertWorkflowSpineMatchesPlan, classifyWorkflowRunPlan, frozenStepRows, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
+import { assertRunStatusMatchesSpine, classifyWorkflowRunPlan, frozenStepRows, reconcileWorkflowSpineWithPlan, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
 import { resolveWorkflowRunOutputs } from "./run-outputs.js";
 import { evaluateStaleUnits } from "./unit-checkin.js";
 import { canonicalizeWorkflowRefInput, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
@@ -192,9 +192,6 @@ export async function getWorkflowStatus(runId, opts) {
         return detail;
     });
 }
-export async function hasWorkflowRun(runId) {
-    return withWorkflowRunsRepo((repo) => repo.hasRun(runId));
-}
 export async function listWorkflowRuns(input) {
     const scopeKey = getCurrentWorkflowScopeKey();
     const activeOnly = input?.activeOnly === true;
@@ -248,13 +245,15 @@ export async function listWorkflowRuns(input) {
 }
 export async function getNextWorkflowStep(specifier, params, options) {
     return withWorkflowRunsRepo(async (repo) => {
-        const { run, autoStarted, startWarnings } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags);
+        const { run, autoStarted, resumed, startWarnings } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags, options?.newRun);
         const steps = readWorkflowRunSteps(repo, run.id);
         const plan = requireExecutableWorkflowPlan(run);
-        assertWorkflowSpineMatchesPlan(plan, run, steps);
+        reconcileWorkflowSpineWithPlan(plan, run, steps);
+        assertRunStatusMatchesSpine(run, steps);
         return {
             ...projectNextResult(run, steps),
             ...(autoStarted ? { autoStarted: true } : {}),
+            ...(resumed ? { resumed: true } : {}),
             ...(startWarnings?.length ? { startWarnings } : {}),
         };
     });
@@ -291,14 +290,15 @@ function projectNextResult(run, steps) {
 }
 export async function resumeWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
-        const run = readWorkflowRun(repo, runId);
+        const run = readWorkflowRunOrPrefix(repo, runId);
         const storedPlan = requireExecutableWorkflowPlan(run);
         const steps = readWorkflowRunSteps(repo, run.id);
-        assertWorkflowSpineMatchesPlan(storedPlan, run, steps);
+        reconcileWorkflowSpineWithPlan(storedPlan, run, steps);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
+            assertRunStatusMatchesSpine(run, steps);
             return buildWorkflowRunDetail(repo, run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
@@ -312,6 +312,7 @@ export async function resumeWorkflowRun(runId) {
         });
         const updated = { ...run, status: "active", updated_at: now };
         const refreshedSteps = readWorkflowRunSteps(repo, run.id);
+        assertRunStatusMatchesSpine(updated, refreshedSteps);
         return buildWorkflowRunDetail(repo, updated, refreshedSteps);
     });
 }
@@ -325,7 +326,7 @@ export async function abandonWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const now = new Date().toISOString();
         const run = repo.immediateTransaction((db) => {
-            const current = readWorkflowRun(repo, runId);
+            const current = readWorkflowRunOrPrefix(repo, runId);
             if (current.status === "completed" || current.status === "failed") {
                 throw new UsageError(`Workflow run ${current.id} is already ${current.status}.`);
             }
@@ -354,115 +355,6 @@ export async function abandonWorkflowRun(runId) {
         return detail;
     });
 }
-// ── Step-evidence persistence bound (issue C) ────────────────────────────────
-/**
- * Marker key stamped on every value this module replaced because it did not fit
- * in `workflow_run_steps.evidence_json`. It is deliberately ugly and unique so a
- * truncated value can NEVER be mistaken for real workflow data by a downstream
- * `steps.<id>.output…` reference, by `akm workflow status`, or by a human
- * reading the row.
- */
-export const WORKFLOW_EVIDENCE_TRUNCATED_MARKER = "__akm_evidence_truncated__";
-function truncatedEvidenceValue(json, what, limitBytes, withPreview) {
-    return {
-        [WORKFLOW_EVIDENCE_TRUNCATED_MARKER]: true,
-        reason: `${what} exceeded the ${limitBytes}-byte evidence_json persistence cap and was NOT stored. ` +
-            `The complete value existed only in the live step result; it cannot be recovered from this row. ` +
-            `Reduce the step's fan-out or have it emit a reference (path, id) instead of inline bulk data.`,
-        originalBytes: utf8Bytes(json),
-        limitBytes,
-        ...(withPreview ? { preview: json.slice(0, WORKFLOW_EVIDENCE_TRUNCATION_PREVIEW_CHARS) } : {}),
-    };
-}
-/**
- * True when `value` is the {@link TruncatedEvidenceValue} envelope persisted in
- * place of an over-cap evidence entry.
- *
- * A LIVE invocation never sees one: the engine threads each step's complete
- * in-memory evidence to the rest of its own run. A RESUMED invocation rebuilds
- * the downstream scope from these rows, so `exec/step-work.ts` tests every
- * whole-value reference with this predicate — otherwise a reference INTO the
- * envelope reports a generic missing property and a reference AT it silently
- * hands the envelope to a unit as if it were the artifact.
- */
-export function isTruncatedEvidence(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value[WORKFLOW_EVIDENCE_TRUNCATED_MARKER] === true);
-}
-/**
- * Bound what a step's evidence costs in ONE SQLite row.
- *
- * `buildEvidence` (exec/step-work.ts) promotes `evidence.output` UNCLIPPED by
- * design: gates judge the full promoted artifact and the in-memory
- * {@link StepExecutionResult} carries it to the caller intact. Nothing bounded
- * the PERSISTED form, though — a `collect` reducer over an unbounded fan-out
- * can serialize to hundreds of megabytes. This is the write boundary, so the
- * bound lives here rather than in the shared step-semantics module.
- *
- * Over-cap values are REPLACED (largest top-level entry BY UTF-8 BYTES first —
- * the unit the cap is measured in — until the row fits) with a
- * {@link TruncatedEvidenceValue} envelope. Nothing is silently shortened: a
- * consumer either sees the real value or sees an object whose marker key says
- * the data is gone. `preview` is intentionally not shaped like the original, so
- * an expression reaching INTO a truncated artifact (`steps.x.output.files`)
- * cannot quietly resolve against a half-array; a resumed run's reference is
- * rejected by name through {@link isTruncatedEvidence}.
- *
- * Returns the JSON to persist plus the keys that were replaced (empty in the
- * overwhelmingly common case, where nothing is copied or re-serialized twice).
- */
-export function clipStepEvidenceForPersistence(evidence, limitBytes = WORKFLOW_MAX_EVIDENCE_JSON_BYTES) {
-    if (!evidence)
-        return { json: null, truncatedKeys: [] };
-    // Throws exactly as the previous inline `JSON.stringify` did on unserializable
-    // evidence — that contract is unchanged. Every stringify below operates on a
-    // subtree of a value already proven serializable here.
-    let json = JSON.stringify(evidence);
-    if (json === undefined)
-        return { json: null, truncatedKeys: [] };
-    let bytes = utf8Bytes(json);
-    if (bytes <= limitBytes)
-        return { json, truncatedKeys: [] };
-    const clipped = { ...evidence };
-    const truncatedKeys = [];
-    // Ordered by UTF-8 BYTES, the unit the cap itself is measured in: ordering by
-    // `json.length` (UTF-16 code units) sacrifices the char-largest key rather
-    // than the byte-largest one, so multibyte-heavy evidence loses extra keys the
-    // cap never required.
-    const bySizeDesc = Object.keys(evidence)
-        .map((key) => {
-        const json = JSON.stringify(evidence[key]) ?? "null";
-        return { key, json, bytes: utf8Bytes(json) };
-    })
-        .sort((a, b) => b.bytes - a.bytes);
-    for (const [index, entry] of bySizeDesc.entries()) {
-        const envelope = truncatedEvidenceValue(entry.json, `Step evidence "${entry.key}"`, limitBytes, true);
-        clipped[entry.key] = envelope;
-        truncatedKeys.push(entry.key);
-        // Track the row size arithmetically from the per-key sizes already computed
-        // for the sort, so a run of replacements costs ONE whole-object
-        // serialization rather than one per replaced key. The total is an ESTIMATE
-        // — a key whose value is `undefined` is charged the `"null"` the sort used
-        // but is OMITTED from the serialized row — so it decides only WHEN to
-        // measure. Whether the row FITS is settled by an exact serialization every
-        // time, the last key included, so an exhausted loop falls through to the
-        // whole-object marker on measurement rather than on drift.
-        bytes += utf8Bytes(JSON.stringify(envelope)) - entry.bytes;
-        if (bytes > limitBytes && index < bySizeDesc.length - 1)
-            continue;
-        json = JSON.stringify(clipped);
-        bytes = utf8Bytes(json);
-        if (bytes <= limitBytes)
-            return { json, truncatedKeys };
-    }
-    // Pathological shape (so many keys that even the envelopes overflow): persist
-    // ONE whole-object marker. Still unambiguous, still bounded.
-    return {
-        json: JSON.stringify(truncatedEvidenceValue(JSON.stringify(evidence), "Step evidence", limitBytes, false)),
-        truncatedKeys: Object.keys(evidence),
-    };
-}
 export async function completeWorkflowStep(input) {
     // Read the step (read-only) up front so the LLM validation gate runs OUTSIDE
     // the write transaction — a slow/hung LLM must never hold a db write lock.
@@ -470,7 +362,8 @@ export async function completeWorkflowStep(input) {
         const run = readWorkflowRun(repo, input.runId);
         const storedPlan = requireExecutableWorkflowPlan(run);
         const steps = readWorkflowRunSteps(repo, run.id);
-        assertWorkflowSpineMatchesPlan(storedPlan, run, steps);
+        reconcileWorkflowSpineWithPlan(storedPlan, run, steps);
+        assertRunStatusMatchesSpine(run, steps);
         if (run.status !== "active") {
             throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
         }
@@ -535,11 +428,13 @@ export async function completeWorkflowStep(input) {
     return withWorkflowRunsRepo((repo) => {
         let updatedRun;
         let refreshedSteps = [];
+        let outputWarnings;
         repo.transaction(() => {
             const run = readWorkflowRun(repo, input.runId);
             const plan = requireExecutableWorkflowPlan(run);
             const spine = readWorkflowRunSteps(repo, run.id);
-            assertWorkflowSpineMatchesPlan(plan, run, spine);
+            reconcileWorkflowSpineWithPlan(plan, run, spine);
+            assertRunStatusMatchesSpine(run, spine);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
@@ -560,26 +455,18 @@ export async function completeWorkflowStep(input) {
             if (input.signal?.aborted)
                 throw interruptionReason(input.signal);
             const completedAt = new Date().toISOString();
-            // Bound the single-row cost of the promoted artifact (issue C). The
-            // caller's in-memory evidence object is never mutated — a clipped COPY is
-            // serialized — so the live step result and the gate's artifact judging
-            // keep the complete value. The DOWNSTREAM scope keeps it only because the
-            // engine threads this same in-memory evidence forward (`driveRun` prefers
-            // it over the re-read row): what the clip actually costs is a LATER
-            // invocation, which has nothing but these rows to rebuild the scope from.
-            const persistedEvidence = clipStepEvidenceForPersistence(input.evidence);
-            if (persistedEvidence.truncatedKeys.length > 0) {
-                warn(`Workflow run ${run.id} step "${input.stepId}": evidence exceeded the ` +
-                    `${WORKFLOW_MAX_EVIDENCE_JSON_BYTES}-byte persistence cap; ` +
-                    `${persistedEvidence.truncatedKeys.map((k) => `"${k}"`).join(", ")} ` +
-                    `${persistedEvidence.truncatedKeys.length === 1 ? "was" : "were"} stored as a truncation marker. ` +
-                    `The rest of THIS invocation still reads the complete value, but a run resumed from these rows will ` +
-                    `fail loudly when a later step references this step's output rather than read partial data.`);
-            }
+            // The promoted artifact is persisted WHOLE, unclipped (issue C): a
+            // step artifact that does not fit some cap used to be replaced by a
+            // truncation marker at this exact write, and the run looked fine right
+            // up until a LATER invocation (a resume, or any downstream step
+            // referencing it) found the marker instead of the value and failed
+            // permanently, with every prior paid step now unrecoverable. Persisting
+            // the real value here is what makes it readable again on resume.
+            const evidenceJson = input.evidence ? JSON.stringify(input.evidence) : null;
             repo.updateStepCompletion({
                 status: input.status,
                 notes: input.notes?.trim() || null,
-                evidenceJson: persistedEvidence.json,
+                evidenceJson,
                 summary: summary || null,
                 completedAt,
                 runId: run.id,
@@ -597,12 +484,9 @@ export async function completeWorkflowStep(input) {
             let outputsJson; // undefined = untouched, keep the row's existing value
             if (state.status === "completed" && plan.outputs) {
                 const resolved = resolveWorkflowRunOutputs(plan, refreshedSteps);
-                if (!resolved.ok) {
-                    throw new UsageError(`Workflow run ${run.id} completed its final step but its declared outputs could not be resolved:\n` +
-                        resolved.errors.map((e) => `  - ${e}`).join("\n"), "WORKFLOW_OUTPUT_INVALID");
-                }
                 outputsJson = JSON.stringify(resolved.outputs);
                 repo.setRunOutputs(run.id, outputsJson);
+                outputWarnings = resolved.errors;
             }
             // Re-arm the check-in on every state change: a healthy, progressing run
             // keeps pushing the stall window forward so the directive never fires.
@@ -625,6 +509,12 @@ export async function completeWorkflowStep(input) {
             };
         });
         const detail = buildWorkflowRunDetail(repo, updatedRun, refreshedSteps);
+        if (outputWarnings?.length) {
+            const messages = outputWarnings.map((e) => `Workflow run ${input.runId} declared ${e}`);
+            for (const message of messages)
+                warn(message);
+            detail.warnings = [...(detail.warnings ?? []), ...messages];
+        }
         // #11: emit `workflow_step_completed` ONLY for a genuine `completed`
         // transition; every other non-pending status (failed/skipped/blocked)
         // carries the honest `workflow_step_updated` name. The status is ALWAYS
@@ -642,10 +532,15 @@ export async function completeWorkflowStep(input) {
         return detail;
     });
 }
-async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
+async function resolveRunSpecifier(repo, specifier, params, parameterFlags, forceNew) {
     const hasParameters = (params && Object.keys(params).length > 0) || (parameterFlags?.length ?? 0) > 0;
-    const explicitRun = repo.getRunById(specifier);
+    const explicitRun = findRunByIdOrPrefix(repo, specifier);
     if (explicitRun) {
+        // `--new` starts a fresh run FROM A REF; it never makes sense against a
+        // run id (or an id prefix), which already names the run to act on (#919).
+        if (forceNew) {
+            throw new UsageError(`--new starts a fresh run from a workflow ref; "${specifier}" already names a run id.`, "INVALID_FLAG_VALUE");
+        }
         if (hasParameters) {
             throw new UsageError(`Workflow parameter flags can only be used when starting a new run, not with existing run id "${specifier}".`);
         }
@@ -655,7 +550,7 @@ async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
     const exactRef = specifier.trim();
     const parsedExact = parseBundleRef(exactRef);
     const qualifiedExact = parsedExact.bundle !== undefined && parsedExact.fragment === undefined;
-    const detached = qualifiedExact ? repo.getActiveRunRowForScope(exactRef, scopeKey) : undefined;
+    const detached = qualifiedExact && !forceNew ? repo.getActiveRunRowForScope(exactRef, scopeKey) : undefined;
     let ref;
     try {
         ref = await canonicalizeWorkflowSpecifier(specifier);
@@ -663,24 +558,29 @@ async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
     catch (error) {
         if (detached) {
             if (hasParameters) {
-                throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active.`);
+                throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active.`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${detached.id}" to free up ${specifier} first.`);
             }
-            return { run: detached, autoStarted: false };
+            return { run: detached, autoStarted: false, resumed: true };
         }
         if (error instanceof NotFoundError && !specifier.includes(":") && !specifier.includes("/")) {
             throw new NotFoundError(`Workflow run or workflow "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
         }
         throw error;
     }
-    const active = repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
+    const active = forceNew ? undefined : repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
     if (active) {
         if (hasParameters) {
-            throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active.`);
+            throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active.`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${active.id}" to free up ${ref} first.`);
         }
-        return { run: active, autoStarted: false };
+        return { run: active, autoStarted: false, resumed: true };
     }
+    // `force` (#485's own escape hatch) is what lets `--new` create a second
+    // active run for this (ref, scope) pair instead of the concurrency guard
+    // refusing it — the caller explicitly asked for a fresh run, so the guard
+    // that exists to catch an ACCIDENTAL second run does not apply (#919).
     const started = await startWorkflowRun(ref, params ?? {}, {
         ...(parameterFlags !== undefined ? { parameterFlags } : {}),
+        ...(forceNew ? { force: true } : {}),
     });
     return {
         run: readWorkflowRun(repo, started.run.id),
@@ -713,12 +613,57 @@ async function workflowRunRefSet(canonicalRef, exactRef) {
     }
     return [...refs];
 }
+/**
+ * A workflow run id (or an accepted prefix of one, #919) is hex digits and
+ * hyphens, 8+ characters. A workflow ref always contains at least one
+ * character outside that set (a `/` path segment, at minimum), so this
+ * never mistakes a ref for an id — matching input is ALWAYS resolved as an
+ * id/prefix, never falls through to ref resolution.
+ */
+const RUN_ID_PREFIX_PATTERN = /^[0-9a-f-]{8,}$/;
+/** The run `specifier` names: by exact id, or by unique id prefix (#919) when it is id-shaped; `undefined` for a workflow ref. */
+function findRunByIdOrPrefix(repo, specifier) {
+    const exact = repo.getRunById(specifier);
+    if (exact || !RUN_ID_PREFIX_PATTERN.test(specifier))
+        return exact;
+    return repo.getRunById(repo.resolveRunIdPrefix(specifier));
+}
+/** For verbs that take a run id/prefix OR a workflow ref (`status`): the run id, or `undefined` to fall through to ref resolution. */
+export async function resolveWorkflowRunTarget(specifier) {
+    return withWorkflowRunsRepo((repo) => findRunByIdOrPrefix(repo, specifier)?.id);
+}
+/** User-facing read: accepts an id prefix. Internal reads use {@link readWorkflowRun} with an exact id. */
+function readWorkflowRunOrPrefix(repo, specifier) {
+    const run = findRunByIdOrPrefix(repo, specifier);
+    if (!run)
+        throw new NotFoundError(`Workflow run "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
+    return reclaimOrphanedEngineLease(repo, run);
+}
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {
         throw new NotFoundError(`Workflow run "${runId}" not found.`, "WORKFLOW_NOT_FOUND");
     }
-    return run;
+    return reclaimOrphanedEngineLease(repo, run);
+}
+/**
+ * Self-heal a run's engine lease once it has expired — the orphaned-lease
+ * case where an engine crashed without releasing it — mirroring the
+ * maintenance barrier's self-reclaim of a wedged sentinel, applied at the
+ * points a caller actually asks "what is this run's state". Never touches a
+ * live lease: {@link WorkflowRunsRepository.reclaimExpiredEngineLease} is a
+ * compare-and-swap on the exact (holder, until) this call observed, so a
+ * lease renewed or re-acquired between the read and this write is left alone.
+ */
+function reclaimOrphanedEngineLease(repo, run) {
+    const { engine_lease_holder: holder, engine_lease_until: until } = run;
+    if (!holder || !until)
+        return run;
+    const now = new Date().toISOString();
+    if (until >= now)
+        return run;
+    repo.reclaimExpiredEngineLease(run.id, holder, until, now);
+    return { ...run, engine_lease_holder: null, engine_lease_until: null };
 }
 function readWorkflowRunSteps(repo, runId) {
     return repo.getStepsForRun(runId);
@@ -832,8 +777,13 @@ function toWorkflowRunSummary(run) {
         executionSupport: plan.support,
         // Surface the engine lease (holder id + expiry — never workflow-authored
         // content) so `workflow run`/`status` show which native execution
-        // invocation currently holds the run lease.
-        ...(run.engine_lease_holder && run.engine_lease_until
+        // invocation currently holds the run lease. Gated on `until` still being
+        // in the future: a crashed engine's lease self-expires, and a run
+        // whose holder is provably gone must stop reading as engine-driven the
+        // instant that happens, not just once something next attempts to acquire
+        // it (`readWorkflowRun`/`readWorkflowRunOrPrefix` also reclaim the DB
+        // columns outright on the same condition).
+        ...(run.engine_lease_holder && run.engine_lease_until && run.engine_lease_until >= new Date().toISOString()
             ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
             : {}),
         // P3b (spec §4.5): all three optional and conditionally spread, so every
@@ -860,7 +810,7 @@ function assertLeaseAllowsSpineAdvance(run, leaseHolder) {
         return; // expired ⇒ claimable, not live
     throw new UsageError(`Workflow run ${run.id} is being driven by engine ${run.engine_lease_holder} ` +
         `(run lease expires ${run.engine_lease_until}). The engine owns the step spine while it runs — ` +
-        `wait for it to finish or for the lease to expire before advancing steps manually.`);
+        `wait for it to finish or for the lease to expire before advancing steps manually.`, "RUN_LEASE_HELD");
 }
 function toWorkflowRunStepState(step) {
     return {