akm-cli 0.9.6 → 0.9.8-beta.1

package/dist/workflows/exec/worktree.js

@@ -71,7 +71,22 @@ import { isProcessAlive, isWithinAsync, safeRealpathAsync } from "../../core/com
 import { serializeByKey } from "../../core/concurrent.js";
 import { runManagedSubprocess } from "../../core/subprocess.js";
 import { warn } from "../../core/warn.js";
-const GIT_TIMEOUT_MS = 30_000;
+/**
+ * Timeout for every `git worktree add|prune|remove|status` call this module
+ * makes. Was 30s; raised to 120s after #891 confirmed a real product gap:
+ * these calls run under {@link withRepoWorktreeLock}, a per-process,
+ * per-repository queue, so a machine also busy with OTHER git-heavy work
+ * (other akm runs, other agents' worktrees, a loaded CI runner) can genuinely
+ * push one `git worktree remove` past 30s without anything being stuck —
+ * plain CPU/fork/IO contention. At 30s that showed up as `{ removed: false,
+ * error: "... timed out after 30000ms" }` on a perfectly healthy op: a clean
+ * worktree left retained, or a create failing a unit outright, purely because
+ * the box was busy. 120s matches the same trade already made for
+ * {@link GIT_PUSH_TIMEOUT_MS} (`core/write-source.ts`,
+ * `sources/providers/git-stash.ts`) for the same class of administrative git
+ * call under load; a call that is truly hung (not just slow) is still caught.
+ */
+const GIT_TIMEOUT_MS = 120_000;
 /** Directory under `os.tmpdir()` that owns every run's worktree roots. */
 export const WORKTREES_DIR_NAME = "akm-worktrees";
 /**
@@ -89,12 +104,10 @@ function gitExitError(args, code, stderr, stdout) {
     return `git ${args.join(" ")} exited ${code}${detail ? `: ${detail}` : ""}`;
 }
 /**
- * Run one git command asynchronously; `ok` = exit 0. Never throws (spawn
- * errors and the 30 s timeout → ok: false). Async so a git lock wait parks a
- * promise instead of blocking the event loop; repo-mutating callers must hold
- * {@link withRepoWorktreeLock}.
+ * Run one git command asynchronously via the real `git` binary; `ok` = exit
+ * 0. Never throws (spawn errors and the timeout → ok: false).
  */
-async function git(cwd, args) {
+async function realGitExecutor(cwd, args) {
     const result = await runManagedSubprocess(["git", "-C", cwd, ...args], {
         capture: true,
         timeoutMs: GIT_TIMEOUT_MS,
@@ -114,6 +127,27 @@ async function git(cwd, args) {
     }
     return { ok: true, stdout: result.stdout };
 }
+let gitExecutor = realGitExecutor;
+/**
+ * TEST-ONLY seam (#891): swap the executor every repo-mutating git call in
+ * this module goes through. Lets a test prove those calls genuinely
+ * interleave with other event-loop work — the property the old "count
+ * setInterval ticks during real git calls" test asserted before it was
+ * deleted for timing on the real scheduler instead of on behavior — using a
+ * fake, deterministically-timed async git in place of the real subprocess.
+ * Call with `undefined` to restore the real spawn-based executor.
+ */
+export function setGitExecutorForTesting(executor) {
+    gitExecutor = executor ?? realGitExecutor;
+}
+/**
+ * Run one git command asynchronously; `ok` = exit 0. Never throws. Async so a
+ * git lock wait parks a promise instead of blocking the event loop;
+ * repo-mutating callers must hold {@link withRepoWorktreeLock}.
+ */
+async function git(cwd, args) {
+    return gitExecutor(cwd, args);
+}
 /**
  * Synchronous git for the two read-only probes that run before any unit is in
  * flight ({@link isGitAvailable}, {@link assertGitWorkTree}). They take no

package/dist/workflows/freeze/task-bindings.js

@@ -20,15 +20,13 @@
  * full design history, including why re-binding cannot reuse the
  * shape-driven normalizer (a code-review finding).
  */
+import { isRecord } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { validateInputs } from "../../execution/input-contract.js";
 import { parseReference } from "../program/expressions.js";
 function inputBindingInvalid(message) {
     return new UsageError(message, "INPUT_BINDING_INVALID");
 }
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function unknownBindingNameError(stepId, targetRef, name, declaredNames) {
     return inputBindingInvalid(`Workflow step ${stepId} targets ${targetRef} with.${name}, which is not a declared input. ` +
         `Declared inputs: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}.`);
@@ -152,7 +150,7 @@ function finalizeBindings(stepId, targetRef, contract, byName) {
  * reinterpreted as a literal.
  */
 function normalizeOneEntry(stepId, targetRef, name, value, schema, earlierStepIds, declaredParamNames) {
-    if (!isPlainObject(value) || !Object.hasOwn(value, "from")) {
+    if (!isRecord(value) || !Object.hasOwn(value, "from")) {
         return Object.freeze({ kind: "literal", name, value });
     }
     const keys = Object.keys(value);

package/dist/workflows/ir/compile.js

@@ -25,6 +25,7 @@
  * Returns accumulated `WorkflowError`s rather than throwing. Pure and
  * deterministic: the same document always compiles to the same plan.
  */
+import { compareCodePoints } from "../../core/common.js";
 import { formatReference, parseReference } from "../program/expressions.js";
 import { projectExecCore } from "../program/schema.js";
 import { sourceStepInstructions, sourceStepProgramUnit, sourceStepRef } from "../source-ir/program.js";
@@ -114,9 +115,6 @@ function sortedOutputs(outputs) {
     }
     return sorted;
 }
-function compareCodePoints(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
 function compileStep(step, sequenceIndex, defaults, resolved) {
     const gate = {
         kind: "gate",
@@ -269,14 +267,12 @@ function checkOutputReference(name, text, check) {
  * (human + JSON output, via `core/adapter/adapters/akm-lint.ts#
  * workflowCompileWarnings`) and as `warn()` lines at `workflow run`.
  *
- *   A. A unit/map step with NO step-level `output:` schema carries its units'
- *      raw results as an untyped artifact — permitted, but worth flagging.
- *   B. A `params.<name>` reference (in `map.over`/`route.input`) to an
+ *   A. A `params.<name>` reference (in `map.over`/`route.input`) to an
  *      UNDECLARED param, but ONLY when the document declares a `params:`
  *      block — a likely typo. Prose can no longer carry param references at
  *      all (it is never scanned), so this warning's surface shrinks to the
  *      two whole-value fields that can legally contain one.
- *   C. `gate.max_loops` above 1 on an `exec` step. The engine judges such a
+ *   B. `gate.max_loops` above 1 on an `exec` step. The engine judges such a
  *      step but never loops it (`exec/step-work.ts#effectiveGateMaxLoops`):
  *      a frozen argv cannot read the judge's feedback, so a second loop would
  *      only re-run the identical command — and its side effects. The declared
@@ -299,13 +295,6 @@ export function collectWorkflowWarnings(input) {
                         `can still fail the step.`,
                 });
             }
-            if ((step.map || step.route === undefined) && step.output === undefined) {
-                warnings.push({
-                    line: step.source.start,
-                    message: `Step "${step.id}" declares no \`output:\` schema — its unit results are carried as an untyped ` +
-                        `artifact (permitted). Add an \`output:\` JSON Schema to type and validate the step artifact.`,
-                });
-            }
             if (declaredParams) {
                 const declaredList = [...declaredParams].join(", ");
                 const scan = (text, label) => {

package/dist/workflows/ir/schema-v4.js

@@ -10,6 +10,7 @@
  */
 import { createHash } from "node:crypto";
 import path from "node:path";
+import { compareCodePoints } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { decodeFrozenExecutableIdentity } from "../../execution/executable-identity.js";
 import { INPUT_NAME_PATTERN } from "../../execution/input-contract.js";
@@ -38,7 +39,7 @@ export const WORKFLOW_IR_V5_VERSION = 5;
  * freeze-time `COMPOSITION_INVALID` gates live in
  * `src/workflows/freeze/targets/child-workflow.ts` (Lane B).
  */
-export function decodeWorkflowPlanV4(input, hooks = {}, depth = 0, budget = { embeddedBytes: 0 }) {
+export function decodeWorkflowPlanV4(input, depth = 0, budget = { embeddedBytes: 0 }) {
     const raw = record(input, "plan");
     if (raw.irVersion !== WORKFLOW_IR_V5_VERSION)
         fail("irVersion must be 5");
@@ -51,7 +52,7 @@ export function decodeWorkflowPlanV4(input, hooks = {}, depth = 0, budget = { em
         planExtraKeys: ["sourceReadSet", "outputs"],
         unitExtraKeys: ["frozenTarget", "environment"],
         gateExtraKeys: ["frozenJudge"],
-    }, hooks);
+    });
     const rawSteps = raw.steps;
     const stepIds = new Set(rawSteps.map((rawStep) => rawStep.stepId));
     const requiredSources = [];
@@ -232,7 +233,7 @@ function decodeChildWorkflowTarget(target, unit, depth, budget) {
         fail(`unit ${unit.id} child workflow contentHash does not match its frozen dispatch`);
     }
     const childDepth = depth + 1;
-    const frozenPlan = decodeWorkflowPlanV4(target.frozenPlan, {}, childDepth, budget);
+    const frozenPlan = decodeWorkflowPlanV4(target.frozenPlan, childDepth, budget);
     const embeddedPlanJson = canonicalJsonLocal(frozenPlan);
     const actualPlanHash = sha256(embeddedPlanJson);
     if (actualPlanHash !== planHash) {
@@ -711,9 +712,6 @@ function digest(value, label) {
 function sha256(value) {
     return createHash("sha256").update(value).digest("hex");
 }
-function compareCodePoints(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
 function canonicalJsonLocal(value) {
     const sort = (entry) => {
         if (Array.isArray(entry))

package/dist/workflows/ir/schema.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { isContainedRelativePath } from "../../core/common.js";
+import { isContainedRelativePath, isRecord } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { parseReference } from "../program/expressions.js";
 import { PROGRAM_PARAM_NAME_PATTERN, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN } from "../program/schema.js";
@@ -13,7 +13,7 @@ export { WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_TIMEOUT_MS };
 const MAX_LIST_ITEMS = 1024;
 const MAX_STRING_LENGTH = 1_000_000;
 /** Validate the current durable execution graph. */
-export function validateWorkflowPlanStructure(input, options, hooks = {}) {
+export function validateWorkflowPlanStructure(input, options) {
     if (!isRecord(input) || input.irVersion !== options.expectedVersion) {
         fail(`irVersion must be ${options.expectedVersion}`);
     }
@@ -351,9 +351,6 @@ function assertString(value, label) {
     if (typeof value !== "string" || value.length === 0 || value.length > MAX_STRING_LENGTH)
         fail(`${label} must be a non-empty bounded string`);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function fail(message) {
     throw new UsageError(`Invalid frozen workflow plan: ${message}.`);
 }

package/dist/workflows/parser.js

@@ -33,7 +33,7 @@
 import { LineCounter, parseDocument } from "yaml";
 import { parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { parseMarkdownToc } from "../core/asset/markdown.js";
-import { isContainedRelativePath } from "../core/common.js";
+import { isContainedRelativePath, isRecord } from "../core/common.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { checkJsonSchemaDefinition, JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS } from "../core/json-schema.js";
 import { parseReference } from "./program/expressions.js";
@@ -165,7 +165,7 @@ export function parseWorkflow(markdown, source) {
     };
     if (root === null || root === undefined)
         root = {};
-    if (!isPlainRecord(root)) {
+    if (!isRecord(root)) {
         return {
             ok: false,
             errors: [{ line: 2, message: `Workflow frontmatter must be a YAML mapping (key: value pairs).` }],
@@ -355,7 +355,7 @@ function checkEnvelopeFields(ctx, root, fmEndLine) {
             checkActorStamp(ctx, root.verified, ["verified"], `"verified"`);
         }
     }
-    if (root.provenance !== undefined && !isPlainRecord(root.provenance)) {
+    if (root.provenance !== undefined && !isRecord(root.provenance)) {
         ctx.err(["provenance"], `Workflow frontmatter "provenance" must be a mapping.`);
     }
     if (root.status !== undefined && (typeof root.status !== "string" || !LIFECYCLE_STATUSES.has(root.status))) {
@@ -368,7 +368,7 @@ function checkEnvelopeFields(ctx, root, fmEndLine) {
 function checkActorStamp(ctx, value, path, label) {
     if (value === undefined)
         return;
-    if (!isPlainRecord(value)) {
+    if (!isRecord(value)) {
         ctx.err(path, `Workflow frontmatter ${label} must be a mapping with a non-empty "by".`);
         return;
     }
@@ -402,7 +402,7 @@ function checkXrefs(ctx, value, fmEndLine) {
 function parseParams(ctx, raw) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(["params"], `"params" must be a mapping of param name to a JSON Schema object (e.g. changed_files: { type: array }).`);
         return undefined;
     }
@@ -412,7 +412,7 @@ function parseParams(ctx, raw) {
             ctx.err(["params", paramName], `Param name "${paramName}" is invalid. Use letters, digits, and underscores, starting with a letter or underscore, so "params.${paramName}" can address it.`);
             continue;
         }
-        if (!isPlainRecord(value)) {
+        if (!isRecord(value)) {
             ctx.err(["params", paramName], `Param "${paramName}" must be a JSON Schema object (e.g. { type: string }).`);
             continue;
         }
@@ -441,7 +441,7 @@ function parseParams(ctx, raw) {
 function parseOutputs(ctx, raw) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(["outputs"], `"outputs" must be a mapping of output name to { from, schema? } (e.g. report: { from: steps.summarize.output }).`);
         return undefined;
     }
@@ -453,7 +453,7 @@ function parseOutputs(ctx, raw) {
                 `underscore, so "steps.<child>.output.${outputName}" can address it.`);
             continue;
         }
-        if (!isPlainRecord(value)) {
+        if (!isRecord(value)) {
             ctx.err(path, `Output "${outputName}" must be a mapping with "from" (and optional "schema").`);
             continue;
         }
@@ -474,7 +474,7 @@ function parseOutputs(ctx, raw) {
         }
         const entry = { from: value.from };
         if (value.schema !== undefined) {
-            if (!isPlainRecord(value.schema)) {
+            if (!isRecord(value.schema)) {
                 ctx.err([...path, "schema"], `Output "${outputName}" "schema" must be a JSON Schema object.`);
             }
             else {
@@ -493,7 +493,7 @@ function parseDefaults(ctx, raw) {
     if (raw === undefined)
         return undefined;
     const path = ["defaults"];
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `"defaults" must be a mapping with any of: ${DEFAULTS_KEYS.join(", ")}.`);
         return undefined;
     }
@@ -525,7 +525,7 @@ function parseBudget(ctx, raw) {
     if (raw === undefined)
         return undefined;
     const path = ["budget"];
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `"budget" must be a mapping with any of: ${BUDGET_KEYS.join(", ")}.`);
         return undefined;
     }
@@ -558,7 +558,7 @@ function parseSteps(ctx, raw) {
     // (including ones that fail their own validation).
     const idIndex = new Map();
     raw.forEach((rawStep, index) => {
-        if (isPlainRecord(rawStep) && typeof rawStep.id === "string" && !idIndex.has(rawStep.id)) {
+        if (isRecord(rawStep) && typeof rawStep.id === "string" && !idIndex.has(rawStep.id)) {
             idIndex.set(rawStep.id, index);
         }
     });
@@ -567,7 +567,7 @@ function parseSteps(ctx, raw) {
     const routeChecks = [];
     raw.forEach((rawStep, index) => {
         const path = ["steps", index];
-        if (!isPlainRecord(rawStep)) {
+        if (!isRecord(rawStep)) {
             ctx.err(path, `Step ${index + 1} must be a mapping with an "id".`);
             return;
         }
@@ -655,7 +655,7 @@ function parseSteps(ctx, raw) {
 // Step blocks
 // ---------------------------------------------------------------------------
 function parseUnit(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "unit" must be a mapping (a dispatch-override bag).`);
         return undefined;
     }
@@ -733,7 +733,7 @@ function parseUnit(ctx, raw, path, stepLabel) {
  * keeps that decision visible in the frontmatter diff.
  */
 function parseExec(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "exec" must be a mapping with a "command" argv list.`);
         return undefined;
     }
@@ -832,7 +832,7 @@ function parseExecCwd(ctx, raw, path, stepLabel) {
     return value;
 }
 function parseMap(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "map" must be a mapping with an "over" key.`);
         return undefined;
     }
@@ -866,7 +866,7 @@ function parseMap(ctx, raw, path, stepLabel) {
     return map;
 }
 function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "route" must be a mapping with "input" and "when" keys.`);
         return undefined;
     }
@@ -888,7 +888,7 @@ function parseRoute(ctx, raw, path, stepLabel, stepIndex, routeChecks) {
         const seenMatches = new Map();
         raw.when.forEach((branch, i) => {
             const branchPath = [...whenPath, i];
-            if (!isPlainRecord(branch)) {
+            if (!isRecord(branch)) {
                 ctx.err(branchPath, `${stepLabel} "when[${i}]" must be a mapping: { match, step }.`);
                 return;
             }
@@ -967,7 +967,7 @@ function parseInputs(ctx, raw, path, stepLabel) {
     return out.length > 0 ? out : undefined;
 }
 function parseGate(ctx, raw, path, stepLabel) {
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "gate" must be a mapping with any of: ${GATE_KEYS.join(", ")}.`);
         return undefined;
     }
@@ -1009,7 +1009,7 @@ function parseEngineName(ctx, raw, path, label) {
 function parseRetry(ctx, raw, path, stepLabel) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${stepLabel} "retry" must be a mapping: { max: <n>, on: [<failure_reason>, …] }.`);
         return undefined;
     }
@@ -1092,7 +1092,7 @@ function parseEnumField(ctx, raw, path, label, allowed) {
 function parseLlmOverrides(ctx, raw, path, label) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${label} must be a mapping of LLM invocation overrides.`);
         return undefined;
     }
@@ -1127,7 +1127,7 @@ function parseLlmOverrides(ctx, raw, path, label) {
             ctx.err([...path, "supports_json_schema"], `${label}.supports_json_schema must be a boolean.`);
     }
     if (raw.extra_params !== undefined) {
-        if (!isPlainRecord(raw.extra_params)) {
+        if (!isRecord(raw.extra_params)) {
             ctx.err([...path, "extra_params"], `${label}.extra_params must be a JSON object.`);
         }
         else {
@@ -1168,7 +1168,7 @@ function parseLlmOverrides(ctx, raw, path, label) {
 function parseSchemaObject(ctx, raw, path, label) {
     if (raw === undefined)
         return undefined;
-    if (!isPlainRecord(raw)) {
+    if (!isRecord(raw)) {
         ctx.err(path, `${label} must be a JSON Schema object (e.g. { type: object, properties: { … } }).`);
         return undefined;
     }
@@ -1212,9 +1212,6 @@ function checkUnknownKeys(ctx, obj, path, allowed, label) {
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
-function isPlainRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function describeError(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }

package/dist/workflows/source-files.js

@@ -12,20 +12,21 @@
  */
 import fs from "node:fs";
 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";
 export class WorkflowSourceRejectionError extends UsageError {
     sourcePaths;
     constructor(message, code, sourcePaths) {
         super(message, code);
-        this.sourcePaths = [...sourcePaths].sort(comparePaths);
+        this.sourcePaths = [...sourcePaths].sort(compareCodePoints);
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
     canonicalName;
     constructor(canonicalName, sourcePaths) {
-        const sorted = [...sourcePaths].sort(comparePaths);
+        const sorted = [...sourcePaths].sort(compareCodePoints);
         super(`Workflow "${canonicalName}" resolves to multiple workflow source files: ${sorted.join(", ")}. ` +
             "A canonical workflow ref must be owned by exactly one recognized .md or .yml source; remove or rename the duplicate.", "RESOURCE_ALREADY_EXISTS", sorted);
         this.name = "WorkflowSourceCollisionError";
@@ -36,8 +37,8 @@ export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
 export class WorkflowSourceDomainError extends WorkflowSourceRejectionError {
     canonicalName;
     constructor(canonicalName, sourcePaths, issues, collidingSourcePaths) {
-        const sortedPaths = [...sourcePaths].sort(comparePaths);
-        const sortedCollisions = [...collidingSourcePaths].sort(comparePaths);
+        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";
@@ -169,7 +170,7 @@ export function listWorkflowSourceFiles(sourceRoot, adapterId, name) {
             extensionlessStem: entry.name.slice(0, -extension.length),
         });
     }
-    candidates.sort((left, right) => comparePaths(left.relativePath, right.relativePath));
+    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);
@@ -229,9 +230,9 @@ export function resolveWorkflowSourceDomains(sourceRoot, adapterId, sourcePaths)
         candidatesByName.set(canonicalName, domain);
     }
     const resolutions = [];
-    for (const canonicalName of [...candidatesByName.keys()].sort(comparePaths)) {
+    for (const canonicalName of [...candidatesByName.keys()].sort(compareCodePoints)) {
         const candidates = candidatesByName.get(canonicalName) ?? [];
-        candidates.sort((left, right) => comparePaths(left.relativePath, right.relativePath));
+        candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
         const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
         const sourcePaths = candidates.map((candidate) => candidate.relativePath);
         if (issues.length > 0) {
@@ -365,9 +366,3 @@ function isWithinResolved(candidate, root) {
     const relative = path.relative(root, path.resolve(candidate));
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
-function toPosix(value) {
-    return value.replaceAll("\\", "/");
-}
-function comparePaths(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}

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

@@ -10,12 +10,12 @@
  */
 import { types as utilTypes } from "node:util";
 import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { compareCodePoints, wellFormedUnicode } from "../../core/common.js";
 import { validateExtraParams } from "../../core/extra-params.js";
 import { checkJsonSchemaDefinition } from "../../core/json-schema.js";
 import { parseReference } from "../program/expressions.js";
 import { PROGRAM_RETRY_REASONS } from "../program/schema.js";
 import { jsonBytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
-import { compareWorkflowSourceCodePoints } from "./compare.js";
 import { canonicalizeWorkflowCron, canonicalizeWorkflowRun, canonicalizeWorkflowWorkingDirectory, classifyWorkflowStepUses, rejectNulInArgv, validateWorkflowBuiltinCommand, WorkflowSourceSemanticError, } from "./semantics.js";
 export const WORKFLOW_SOURCE_IR_VERSION = 1;
 export const WORKFLOW_SOURCE_IR_MAX_BYTES = 2 * 1024 * 1024;
@@ -269,9 +269,6 @@ function validateStep(value, jobId, index, stepIds, options) {
     extensions(step.extensions, `step ${id} extensions`);
     span(step.source, `step ${id} source`);
 }
-function compareCodePoints(left, right) {
-    return compareWorkflowSourceCodePoints(left, right);
-}
 function validateExec(value, location, options) {
     if (value === undefined)
         return;
@@ -692,21 +689,6 @@ function countJsonBytes(state, token) {
     if (state.bytes > WORKFLOW_SOURCE_IR_MAX_BYTES)
         fail("source IR exceeds the byte limit");
 }
-function wellFormedUnicode(value) {
-    for (let index = 0; index < value.length; index++) {
-        const code = value.charCodeAt(index);
-        if (code >= 0xd800 && code <= 0xdbff) {
-            const next = value.charCodeAt(index + 1);
-            if (!(next >= 0xdc00 && next <= 0xdfff))
-                return false;
-            index++;
-        }
-        else if (code >= 0xdc00 && code <= 0xdfff) {
-            return false;
-        }
-    }
-    return true;
-}
 function record(value, location) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         fail(`${location} must be an object`);

package/docs/migration/v0.9.0-troubleshooting.md

@@ -24,7 +24,17 @@ before that migration and tells you to run:
 akm upgrade --force
 ```
 
-Only a successful executable upgrade admits migration 018. Immediately before
+Where akm cannot reinstall itself — a container that ships the CLI globally,
+an unprivileged runtime user — that command fails at its install step
+(`EACCES` on the global module directory) before it ever reaches the
+migration. Use the install-free route instead:
+
+```sh
+akm upgrade --state-only
+```
+
+Both admit migration 018 and both take the same verified safety copy described
+below; `--state-only` simply skips the executable replacement. Immediately before
 the migration, AKM takes a SQLite writer-exclusion lock, rechecks the exact
 ledger, and writes a consistent SQLite snapshot beside the database as
 `state.db.pre-018-drop-dead-lane-schema.<UTC-digits>.<UUID>.bak`. The randomized
@@ -41,7 +51,7 @@ general storage migrator.
 
 An existing database with no applied migration IDs is never treated as a fresh
 install, whether its `schema_migrations` table is absent or empty. Ordinary
-commands reject it without writing. The explicit `akm upgrade --force` path
+commands reject it without writing. The explicit `akm upgrade --force` (or `--state-only`) path
 takes and verifies a descriptor-bound snapshot named
 `state.db.pre-001-initial-schema.<UTC-digits>.<UUID>.bak` before it creates the
 ledger or applies any migration from 001 through 022. A truly new database is

package/docs/reference/cli.md

@@ -1022,12 +1022,14 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 akm upgrade              # Download and replace the running binary
 akm upgrade --check      # Check for updates without installing
 akm upgrade --force      # Force upgrade even if already on latest
+akm upgrade --state-only # Apply pending state.db migrations; install nothing
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--check` | Check for updates without installing |
 | `--force` | Force upgrade even if on latest version |
+| `--state-only` | Apply pending `state.db` migrations without installing a new akm. For installs that cannot rewrite their own binary — a container shipping akm globally, an unprivileged runtime user — where the install step would fail `EACCES` before the migration could run. Takes the same verified safety copy as `--force`; it changes who may request the migration, not what it does. |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
 
 Checksum verification is not optional and has no flag. If a release's
@@ -2032,7 +2034,9 @@ when one exists.
 Scan bundle markdown files for structural issues: unquoted colons, missing
 `updated` field, orphaned stubs, placeholder stubs, missing `name`/`type`,
 stale paths, and broken refs — in body text and in
-`refs`/`xrefs`/`supersededBy`/`contradictedBy` frontmatter. Also reports
+`refs`/`xrefs`/`supersededBy`/`contradictedBy` frontmatter. A belief edge
+pointing at a memory that `akm improve` pruned resolves through the archive
+tombstone under `.akm/memory-cleanup/archive/` and is not reported (#884). Also reports
 `dangerous-env-key` findings for env files (the same key set `akm bundle add`
 enforces — see [Dangerous env key audit](#dangerous-env-key-audit) — but
 non-blocking here; `lint` only warns). `--type workflows` structurally parses
@@ -2046,6 +2050,7 @@ akm lint --fix                  # Auto-fix Tier-1 issues in place
 akm lint --type workflows       # Only lint one asset type
 akm lint --dir ~/other-bundle    # Override the bundle root (default: from config)
 akm lint --fail-on-flagged      # CI-friendly: exit non-zero when summary.flagged > 0
+akm lint --prune-dangling-edges # Opt-in: drop belief edges whose target is gone
 ```
 
 | Flag | Description |
@@ -2054,6 +2059,7 @@ akm lint --fail-on-flagged      # CI-friendly: exit non-zero when summary.flagge
 | `--dir` | Override the bundle root directory (default: from config) |
 | `--type` | Only lint assets of this type (e.g. `workflows`, `tasks`, `memories`). **akm bundles only** — every other adapter validates the whole bundle and warns on stderr that the flag had no effect. |
 | `--fail-on-flagged` | Exit non-zero when `summary.flagged > 0`. Default: exit 0 regardless of findings. |
+| `--prune-dangling-edges` | Opt-in repair (#884): drop `supersededBy`/`contradictedBy` entries whose target has neither a file nor a prune tombstone. **Not** implied by `--fix` — it edits well-formed files to delete a belief-graph claim, so review a plain `akm lint` report first. Clears the same `writable: false` gate `--fix` does. |
 
 Returns `fixed[]` and `flagged[]` arrays plus a `summary: { fixed, flagged }`
 count. Each entry carries `file`, `issue`, `detail`, and whether it was

package/docs/reference/workflow-schema.md

@@ -572,6 +572,30 @@ that declares an `output` schema is unaffected — an empty response is not
 valid JSON, so it fails as a parse error and can never satisfy a schema as a
 silent `null`.
 
+### When a step declares no `output:` schema
+
+A step-level `output:` schema is **optional**, and omitting it is a supported
+mode, not a deficiency. The step artifact is then exactly the value described
+above — the unit's result for a solo step, the collected array for a `map`
+step — carried untyped and never validated.
+
+The shape is stable either way: it does not depend on whether a schema is
+present, and it does not vary between a live run and a resume. `steps.<id>.output`
+resolves the same in both cases, so downstream references work with or without
+a schema.
+
+What a schema adds is **enforcement**, not shape. With one, the promoted
+artifact is checked against it and the step fails on mismatch; without one, a
+downstream reference to a field the artifact happens not to carry surfaces at
+resolution time instead (`steps.X.output is not an object — cannot resolve
+property "y"`). Declare `output:` when you want that mismatch caught at the
+producing step rather than at the consuming one.
+
+akm does not warn about a missing step `output:` schema. It briefly did, and
+the advisory was removed: it fired on essentially every step, could not be
+enforced (advisories never reach `--fail-on-flagged`), and flagged a state
+that is legitimate.
+
 ## Workflow outputs
 
 A workflow can declare a run-level export: the values a **completed run**