akm-cli 0.9.11 → 0.9.12

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,6 +613,32 @@ 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 run;
+}
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {

package/dist/workflows/source-files.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { compareCodePoints, toPosix } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../core/recognition-util.js";
+import { warnOnce } from "../core/warn.js";
 export class WorkflowSourceRejectionError extends UsageError {
     sourcePaths;
     constructor(message, code, sourcePaths) {
@@ -34,23 +35,6 @@ export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-export class WorkflowSourceDomainError extends WorkflowSourceRejectionError {
-    canonicalName;
-    constructor(canonicalName, sourcePaths, issues, collidingSourcePaths) {
-        const sortedPaths = [...sourcePaths].sort(compareCodePoints);
-        const sortedCollisions = [...collidingSourcePaths].sort(compareCodePoints);
-        const code = issues.some((issue) => issue.code === "PATH_ESCAPE_VIOLATION")
-            ? "PATH_ESCAPE_VIOLATION"
-            : "WORKFLOW_SOURCE_INVALID";
-        const collisionDetail = sortedCollisions.length > 1 ? ` Valid owners also collide: ${sortedCollisions.join(", ")}.` : "";
-        super(`Workflow "${canonicalName}" has an invalid source ownership domain across candidates: ${sortedPaths.join(", ")}. ` +
-            `Problems: ${issues.map((issue) => issue.message).join(" ")}${collisionDetail} ` +
-            "Every candidate in the canonical domain is rejected until all invalid or duplicate sources are removed.", code, sortedPaths);
-        this.name = "WorkflowSourceDomainError";
-        this.canonicalName = canonicalName;
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
 export class WorkflowSourceIdentityError extends UsageError {
     constructor(ref, indexedPath, authoritativePath) {
         super(`Indexed workflow source identity for "${ref}" points to ${indexedPath}, but the authoritative source is ${authoritativePath}. ` +
@@ -171,11 +155,7 @@ export function listWorkflowSourceFiles(sourceRoot, adapterId, name) {
         });
     }
     candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
-    const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
-    if (issues.length > 0) {
-        throw workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues);
-    }
-    return sources;
+    return inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
 }
 /**
  * Resolve a pre-enumerated set of authored workflow candidates in one batch.
@@ -233,47 +213,44 @@ export function resolveWorkflowSourceDomains(sourceRoot, adapterId, sourcePaths)
     for (const canonicalName of [...candidatesByName.keys()].sort(compareCodePoints)) {
         const candidates = candidatesByName.get(canonicalName) ?? [];
         candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
-        const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
+        const sources = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
         const sourcePaths = candidates.map((candidate) => candidate.relativePath);
-        if (issues.length > 0) {
-            resolutions.push({
-                canonicalName,
-                sourcePaths,
-                rejection: workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues),
-            });
-            continue;
-        }
-        if (sources.length > 1) {
-            resolutions.push({
-                canonicalName,
-                sourcePaths,
-                rejection: new WorkflowSourceCollisionError(adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath)),
-            });
-            continue;
-        }
-        resolutions.push({ canonicalName, sourcePaths, source: sources[0] });
+        resolutions.push({
+            canonicalName,
+            sourcePaths,
+            source: pickWorkflowSource(adapterId, canonicalName, sources),
+        });
     }
     return resolutions;
 }
 function inspectWorkflowSourceDomain(candidates, canonicalName, realRoot) {
     const sources = [];
-    const issues = [];
     for (const candidate of candidates) {
         const inspection = inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot);
-        if (inspection.source)
+        if (inspection.source) {
             sources.push(inspection.source);
-        issues.push(...inspection.issues);
+            continue;
+        }
+        for (const issue of inspection.issues) {
+            warnOnce(`workflow-source-invalid:${issue.sourcePaths.join(",")}`, issue.message);
+        }
     }
-    return { sources, issues };
+    return sources;
 }
-function workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues) {
-    return new WorkflowSourceDomainError(adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, candidates.map((candidate) => candidate.relativePath), issues, sources.map((source) => source.relativePath));
+function pickWorkflowSource(adapterId, canonicalName, sources) {
+    if (sources.length <= 1)
+        return sources[0];
+    const winner = [...sources].sort((left, right) => left.format === right.format ? 0 : left.format === "markdown" ? -1 : 1)[0];
+    const shadowed = sources.filter((source) => source !== winner);
+    const displayName = adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName;
+    warnOnce(`workflow-source-collision:${displayName}`, `Workflow "${displayName}" has both a .md and .yml source (${shadowed
+        .map((source) => source.relativePath)
+        .join(", ")} shadowed by ${winner?.relativePath}); using the .md source. Remove the shadowed sibling to ` +
+        "silence this warning.");
+    return winner;
 }
 function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
     const issues = [];
-    const nestedSuffix = WORKFLOW_EXTENSIONS.find((suffix) => candidate.extensionlessStem.toLowerCase().endsWith(suffix));
-    if (nestedSuffix)
-        issues.push(new WorkflowSourceNameError(candidate.relativePath, nestedSuffix));
     let authoredStat;
     try {
         authoredStat = fs.lstatSync(candidate.path);
@@ -327,11 +304,8 @@ function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
 /** Return the sole owner, throw on a collision, or return undefined when absent. */
 export function resolveUniqueWorkflowSource(sourceRoot, adapterId, name) {
     const sources = listWorkflowSourceFiles(sourceRoot, adapterId, name);
-    if (sources.length > 1) {
-        const canonicalName = sources[0]?.canonicalName ?? canonicalizeWorkflowName(normalizeName(name));
-        throw new WorkflowSourceCollisionError(adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));
-    }
-    return sources[0];
+    const canonicalName = sources[0]?.canonicalName ?? canonicalizeWorkflowName(normalizeName(name));
+    return pickWorkflowSource(adapterId, canonicalName, sources);
 }
 /** Compare an indexed path with the single authoritative on-disk source. */
 export function assertIndexedWorkflowSourceIdentity(ref, indexedPath, authoritative) {

package/dist/workflows/source-ir/program.js

@@ -2,7 +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 { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
-import { applyPortableCommandArguments } from "../../commands/command/portable-template.js";
+import { PORTABLE_ARGUMENTS_PLACEHOLDER } from "../../commands/command/portable-template.js";
 /** Lower one adapter-neutral source-IR step into the shared execution unit. */
 export function sourceStepProgramUnit(source) {
     const unit = {
@@ -32,7 +32,7 @@ export function sourceStepInstructions(source) {
         }
         if (source.commandMode === "literal")
             return action.content;
-        return applyPortableCommandArguments(action.content, action.arguments, "inline workflow command").content;
+        return action.content.split(PORTABLE_ARGUMENTS_PLACEHOLDER).join(action.arguments ?? "");
     }
     if (source.uses !== undefined)
         return `Invoke local target ${source.uses}.`;

package/dist/workflows/source-ir/semantics.js

@@ -5,10 +5,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
-import { validatePortableCommandTemplate } from "../../commands/command/portable-template.js";
 import { parseSchedule } from "../../tasks/schedule.js";
 import { classifyWorkflowSourceUses } from "./uses.js";
-const TOKEN_SAFE_RUN = /^[A-Za-z0-9_./:@+=,-]+(?: [A-Za-z0-9_./:@+=,-]+)*$/;
 export class WorkflowSourceSemanticError extends Error {
     code;
     constructor(code, message) {
@@ -34,17 +32,10 @@ export function canonicalizeWorkflowRun(value) {
     if (value.includes("${{")) {
         throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions and contexts are not supported.");
     }
-    if (value.includes("\n") || value.includes("\r")) {
-        throw new WorkflowSourceSemanticError("unsafe-run-syntax", "Local run accepts only whitespace-separated safe tokens; shell expansion and operators are unsupported.");
+    if (value.includes("\0")) {
+        throw new WorkflowSourceSemanticError("invalid-exec-argv", "Local run may not contain NUL bytes.");
     }
-    const canonical = value
-        .trim()
-        .split(/[ \t]+/)
-        .join(" ");
-    if (!TOKEN_SAFE_RUN.test(canonical)) {
-        throw new WorkflowSourceSemanticError("unsafe-run-syntax", "Local run accepts only whitespace-separated safe tokens; shell expansion and operators are unsupported.");
-    }
-    return canonical;
+    return value;
 }
 export function canonicalizeWorkflowWorkingDirectory(value, workspaceRoot) {
     if (hasControlCharacter(value)) {
@@ -125,17 +116,8 @@ export function validateWorkflowBuiltinCommand(value, mode) {
     if (effectiveMode === "stored-ref") {
         throw new WorkflowSourceSemanticError("builtin-command-inputs", "Inline akm/command content cannot use commandMode stored-ref.");
     }
-    if (effectiveMode === "literal") {
-        if (action.arguments !== undefined) {
-            throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
-        }
-        return action;
-    }
-    try {
-        validatePortableCommandTemplate(action.content, "inline workflow command");
-    }
-    catch (cause) {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", cause instanceof Error ? cause.message : "Invalid portable command template.");
+    if (effectiveMode === "literal" && action.arguments !== undefined) {
+        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
     }
     return action;
 }

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -303,6 +303,26 @@ one akm version reading a given `state.db` at a time; do not alternate
 versions against the same state directory, and do not downgrade below
 0.9.2 once a 0.9.2-or-later akm has recorded task history there.
 
+## Harness id rename: `claude-code` -> `claude`
+
+0.9.2 also renamed the Claude Code harness id from `claude-code` to
+`claude` — the id used for both agent dispatch and the per-session
+extraction ledger (`state.db`'s `extract_sessions_seen.harness` and
+`workflow_runs.agent_harness`). The 0.9.2 release did not carry a state
+migration for this rename, so any row a pre-0.9.2 akm wrote stayed
+keyed under `claude-code`, invisible to anything querying by the new
+name — a script or dashboard filtering `extract_sessions_seen` or
+`workflow_runs` on `harness = 'claude-code'` (or
+`agent_harness = 'claude-code'`) sees those rows disappear from that
+query, not deleted, once you're on a release carrying the 0.9.12 fix.
+0.9.12 adds state migration
+`027-extract-sessions-seen-harness-rename`, which runs automatically
+on the next managed `state.db` open (no separate command needed) and
+renames every such row to `claude` in place — conflict-tolerant
+against a session already recorded under `claude`, which is kept as
+the authoritative row. After upgrading to 0.9.12 or later, re-point
+any external query at `harness = 'claude'` / `agent_harness = 'claude'`.
+
 ## Workflow cutover
 
 Markdown `.md` and GitHub-shaped `.yml` are peer workflow source formats in