akm-cli 0.10.261012-beta → 0.10.261013-beta

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -3,16 +3,13 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { createHash } from "node:crypto";
 import fs from "node:fs";
-import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { COMPOSITION_INVALID_MULTI_JOB_HINT, NotFoundError, UsageError } from "../../core/errors.js";
-import { getDbPath } from "../../core/paths.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
-import { deriveInstallations } from "../../indexer/installations.js";
-import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
+import { resolveConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { compileWorkflowSource } from "../compile.js";
 /**
  * Build the canonical `workflow_runs.workflow_ref` for an AKM workflow asset.
@@ -31,71 +28,70 @@ export function parseWorkflowRefInput(ref) {
     }
     return parsed;
 }
-/** Resolve input sugar to the workflow's canonical run identity. */
+/** Resolve input sugar to the workflow's canonical run identity, without compiling it. */
 export async function canonicalizeWorkflowRefInput(ref) {
-    return (await loadWorkflowAsset(ref)).ref;
+    return resolveWorkflowAsset(ref).fullRef;
 }
-/**
- * Resolve a workflow ref and compile its authored bytes into a plan.
- */
-export async function loadWorkflowAsset(ref) {
+/** Resolve a workflow ref to its authored file and canonical run ref. */
+function resolveWorkflowAsset(ref) {
     const bundleRef = parseWorkflowRefInput(ref);
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const installations = deriveInstallations(allSources);
-    const searchSources = allSources.flatMap((source, index) => {
-        const bundleId = installations[index]?.id;
-        if (!bundleId || (bundleRef.bundle !== undefined && bundleRef.bundle !== bundleId))
-            return [];
-        return [{ source, bundleId }];
-    });
-    if (bundleRef.bundle && searchSources.length === 0) {
-        throw new UsageError(`Bundle "${bundleRef.bundle}" was not found among configured sources.`, "WORKFLOW_SOURCE_INVALID");
-    }
-    let assetPath;
-    let sourcePath;
-    let sourceBundleId;
-    let workflowName;
-    let workflowAdapterId;
-    let rejectedSource;
-    for (const candidateSource of searchSources) {
-        const { source, bundleId } = candidateSource;
-        const adapterId = source.adapterId ?? detectAdapterId(source.path);
-        const ownedSource = source.adapterId ? source : { ...source, adapterId };
-        const owner = resolveAdapterConceptOwner(source.path, adapterId, bundleRef.conceptId);
-        if (!owner)
-            continue;
-        if (!ownsNativeWorkflowRuntime(ownedSource) || !owner.workflowSource) {
-            rejectedSource ??= { source: ownedSource, bundleId };
-            break;
-        }
-        assetPath = owner.path;
-        sourcePath = source.path;
-        sourceBundleId = bundleId;
-        workflowName = owner.workflowSource.canonicalName;
-        workflowAdapterId = adapterId;
-        break;
-    }
-    if (!assetPath) {
-        if (rejectedSource) {
-            const sourceName = rejectedSource.bundleId;
-            const adapterId = rejectedSource.source.adapterId ?? "unassigned";
-            throw new UsageError(`Bundle "${sourceName}" uses adapter "${adapterId}", which does not support native workflow execution.`, "WORKFLOW_SOURCE_INVALID");
+    const sources = resolveSourceEntries(undefined, loadConfig());
+    const match = resolveConceptOwner(bundleRef, sources);
+    if (!match) {
+        if (bundleRef.bundle && resolveSourcesForOrigin(bundleRef.bundle, sources).length === 0) {
+            throw new UsageError(`Bundle "${bundleRef.bundle}" was not found among configured sources.`, "WORKFLOW_SOURCE_INVALID");
         }
         throw new NotFoundError(`Workflow not found for ref: ${ref}`);
     }
-    const resolvedSourcePath = sourcePath;
+    const { owner, source, bundleId, adapterId } = match;
+    if ((adapterId !== "akm" && adapterId !== "akm-workflow") || !owner.workflowSource) {
+        throw new UsageError(`Bundle "${bundleId}" uses adapter "${adapterId}", which does not support native workflow execution.`, "WORKFLOW_SOURCE_INVALID");
+    }
     // Canonicalize the stored ref: `workflows/foo.md` and `workflows/foo` resolve
     // to the same file, so they MUST share one run identity.
-    const canonicalName = canonicalizeWorkflowName(workflowName);
-    const fullRef = workflowAdapterId === "akm-workflow"
-        ? makeBundleRef(sourceBundleId, canonicalName)
-        : canonicalWorkflowRunRef(sourceBundleId, canonicalName);
+    const canonicalName = canonicalizeWorkflowName(owner.workflowSource.canonicalName);
+    const fullRef = adapterId === "akm-workflow"
+        ? makeBundleRef(bundleId, canonicalName)
+        : canonicalWorkflowRunRef(bundleId, canonicalName);
+    return { assetPath: owner.path, sourcePath: source.path, adapterId, canonicalName, fullRef };
+}
+/**
+ * The root of the bundle that owns a workflow ref right now: where the run's exec units and agents work.
+ * A bundle-qualified ref names its bundle, so the workflow file need not exist (a bundle update may have
+ * renamed or removed it; the frozen plan is the run's authority). An unqualified legacy ref finds its
+ * owner by the existing walk. When the bundle does not resolve, the error keeps its type (and exit code)
+ * and names the ref in its message.
+ */
+export function resolveRunBundleRoot(ref) {
+    const { bundle } = parseWorkflowRefInput(ref);
+    if (bundle === undefined) {
+        try {
+            return resolveWorkflowAsset(ref).sourcePath;
+        }
+        catch (err) {
+            // Only a miss means the bundle does not resolve; any other error (an
+            // unsupported adapter, a collision) is reported as itself.
+            if (err instanceof NotFoundError) {
+                throw new NotFoundError(`workflow ${ref} does not resolve to a bundle: ${err.message}`, err.code, err.hint());
+            }
+            throw err;
+        }
+    }
+    const source = resolveSourcesForOrigin(bundle, resolveSourceEntries(undefined, loadConfig()))[0];
+    if (!source) {
+        throw new UsageError(`workflow ${ref} does not resolve to a bundle: bundle "${bundle}" is not configured`, "WORKFLOW_SOURCE_INVALID");
+    }
+    return source.path;
+}
+/**
+ * Resolve a workflow ref and compile its authored bytes into a plan.
+ */
+export async function loadWorkflowAsset(ref) {
+    const { assetPath, adapterId, canonicalName, fullRef } = resolveWorkflowAsset(ref);
     const title = canonicalName.split("/").pop() || canonicalName;
     const bytes = fs.readFileSync(assetPath);
     const result = compileWorkflowSource(bytes.toString("utf8"), {
         path: assetPath,
-        workspaceRoot: resolvedSourcePath,
         title,
     });
     if (!result.ok) {
@@ -106,36 +102,9 @@ export async function loadWorkflowAsset(ref) {
     return {
         ref: fullRef,
         path: assetPath,
-        sourcePath: resolvedSourcePath,
-        adapterId: workflowAdapterId,
+        adapterId,
         title,
         plan: result.plan,
         sourceHash: createHash("sha256").update(bytes).digest("hex"),
     };
 }
-function ownsNativeWorkflowRuntime(source) {
-    return source.adapterId === "akm" || source.adapterId === "akm-workflow";
-}
-/**
- * Resolve the `entries.id` for an indexed workflow, or null when the index
- * database does not yet exist or has no matching entry.
- */
-export function resolveWorkflowEntryId(_sourcePath, ref, adapterId) {
-    if (!fs.existsSync(getDbPath()))
-        return null;
-    const parsed = parseBundleRef(ref);
-    if (!parsed.bundle)
-        throw new UsageError(`Expected a bundle-qualified workflow ref, got "${ref}".`);
-    const itemRef = makeBundleRef(parsed.bundle, parsed.conceptId);
-    return withIndexDb((db) => {
-        const row = db
-            .prepare(`SELECT id
-         FROM entries
-         WHERE type = 'workflow'
-           AND item_ref = ?
-           ${adapterId ? "AND adapter_id = ?" : ""}
-          LIMIT 1`)
-            .get(itemRef, ...(adapterId ? [adapterId] : []));
-        return row?.id ?? null;
-    });
-}

package/dist/workflows/source-files.js

@@ -66,15 +66,6 @@ export class WorkflowSourceLinkResolutionError extends WorkflowSourceRejectionEr
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-export class WorkflowSourcePathIdentityError extends WorkflowSourceRejectionError {
-    constructor(sourcePath, targetPath) {
-        super(`Workflow source ${sourcePath} resolves outside the bundle root to ${targetPath}.`, "PATH_ESCAPE_VIOLATION", [
-            sourcePath,
-        ]);
-        this.name = "WorkflowSourcePathIdentityError";
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
 /** Convert an adapter-owned concept id into its extensionless workflow name. */
 export function workflowNameForConceptId(adapterId, conceptId) {
     if (adapterId === "akm-workflow")
@@ -270,21 +261,18 @@ function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
         issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
         return { issues };
     }
+    // A symlink may point anywhere (installing a bundle is the trust decision),
+    // but it may not change the source's format.
     const targetPath = toPosix(path.relative(realRoot, realPath));
-    const contained = isWithinResolved(realPath, realRoot);
-    if (!contained)
-        issues.push(new WorkflowSourcePathIdentityError(candidate.relativePath, targetPath));
     if (isLink && path.extname(realPath).toLowerCase() !== candidate.lowerExtension) {
         issues.push(new WorkflowSourceLinkIdentityError(candidate.relativePath, targetPath));
     }
-    if (contained) {
-        try {
-            if (!fs.statSync(realPath).isFile())
-                issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
-        }
-        catch {
+    try {
+        if (!fs.statSync(realPath).isFile())
             issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
-        }
+    }
+    catch {
+        issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
     }
     if (issues.length > 0)
         return { issues };

package/docs/architecture/0.10-process-rules.md

@@ -770,13 +770,13 @@ Paths are relative to the rules-010 checkout. `repository.ts` is `src/commands/p
 - **Engine fields** — An `llm` engine requires `endpoint` (an `http(s)` URL; a path not ending in `/chat/completions` only warns) and `model`. Optional fields are `temperature`, `maxTokens`, `timeoutMs` (a positive integer up to 2^31−1, or `null`), `concurrency`, `contextLength`, `supportsJsonSchema`, `enableThinking`, `reasoningEffort`, `extraParams`. An unset temperature sends 0.3 at call time. `enableThinking` sends both `chat_template_kwargs.enable_thinking` and top-level `enable_thinking`. `reasoningEffort` sends `reasoning_effort`. *Why:* which wire form a backend honors varies (#949). (`src/core/config/schema/engines.ts:41-110`, `src/llm/client.ts:548-575`)
 - **Engine request fallbacks (per endpoint|model, per process)** — A 4xx naming `chat_template_kwargs`/`enable_thinking` triggers one retry without them, remembered. A 4xx naming `temperature` drops it for the connection. A "use `max_completion_tokens`" 4xx switches the token field. A schema 4xx, or a 5xx naming the response format, retries once without the schema, and the retry is recorded as one successful call. *Why:* #1045 (OpenAI rejects `chat_template_kwargs`) and #1150 (a gateway answered 502 `format_ignored`). (`src/llm/client.ts:343-480`, #1045, #1150)
 - **Agent-engine rules** — Agent engines need a `platform` that supports agent dispatch. LLM-only fields (`provider`, `endpoint`, `apiKey`, `temperature`, `maxTokens`, `extraParams`, `enableThinking`, `reasoningEffort` and others) are rejected on them. `llmEngine` is valid only on `opencode-sdk` and must name an `llm` engine. `args` is not valid on `opencode-sdk`. `agent` needs a harness with a native agent selector. Engine names are lowercase kebab, at most 63 chars, and must not start with `akm-`. (`src/core/config/schema/engines.ts:115-175`, `src/core/config/schema/primitives.ts:42`, `src/core/config/config-schema.ts:223-231`)
-- **`apiKey` must be a reference (enforced at write, only warned at load)** — `engines.<n>.apiKey`, `embedding.apiKey` and `search.curateRerank.apiKey` should be `$VAR`, `${VAR}` or `secret://<name>`. `akm config set` of a literal key is refused: for `engines.<n>.apiKey` and `embedding.apiKey` with `apiKey must be $VAR, ${VAR}, or secret://<name>`; the "apiKey cannot be persisted in config; export AKM_ENGINE_<NAME>_API_KEY instead" text belongs to `rejectApiKeyPath`, which skips those two paths. A literal already in `config.json` loads with a one-time warning and is used as configured. Git bundle `credential` is strictly `$VAR` or `secret://`, and a violation is a load error. `apiKey` and `apiKeyFile` cannot both be set. An unset `$VAR` warns once and sends an empty credential, and an unresolved `secret://` throws `SECRET_REFERENCE_UNRESOLVED`. *Why:* a literal key leaks through backups, logs and version control. (`src/core/config/schema/primitives.ts:48-60`, `src/core/config/config-walker.ts:242-248,319-345`, `src/core/config/schema/sources-bundles.ts:73,191`, `src/core/config/config.ts:1063-1098`, #454, #905, #953)
+- **`apiKey` must be a reference (enforced at write; a literal only warned at load, a non-`secrets/` ref refused at load)** — `engines.<n>.apiKey`, `embedding.apiKey` and `search.curateRerank.apiKey` should be `$VAR`, `${VAR}` or `${secrets/<name>}` (for example `${secrets/openai}`). `akm config set` of a literal key is refused: for `engines.<n>.apiKey` and `embedding.apiKey` with `apiKey must be $VAR, ${VAR}, or ${secrets/<name>}`; the "apiKey cannot be persisted in config; export AKM_ENGINE_<NAME>_API_KEY instead" text belongs to `rejectApiKeyPath`, which skips those two paths. A literal already in `config.json` loads with a one-time warning and is used as configured, but a `${...}` value must name a `secrets/` asset: any other asset ref (for example `${knowledge/x}`) is a load error. Git bundle `credential` is strictly `$VAR`, `${VAR}` or `${secrets/<name>}`, and a violation is a load error. `apiKey` and `apiKeyFile` cannot both be set. An unset `$VAR` warns once and sends an empty credential, and an unresolved `${ref}` throws `SECRET_REFERENCE_UNRESOLVED`. A `secret://<name>` value from an older release is still read, as `${secrets/<name>}`, and named once. *Why:* a literal key leaks through backups, logs and version control. (`src/core/config/schema/primitives.ts:48-60`, `src/core/config/config-walker.ts:242-248,319-345`, `src/core/config/schema/sources-bundles.ts:73,191`, `src/core/config/config.ts:1063-1098`, #454, #905, #953)
 - **`defaults.llmEngine` and model-work engine rule** — Every engine used for unattended model work must be able to confine the model-work tool policy: an `llm` engine, or an agent engine on a harness in `HARNESS_MODEL_WORK_IDS`. This is enforced at config load for `defaults.llmEngine`, `index.<pass>.engine`, improve strategy, process, judgment and `qualityGate` engines. The execution cascade is `defaults.llmEngine → strategy → index.<pass> → process → current invocation`. `defaults.engine` and `workflow.judgeEngine` must name a configured engine, and `defaults.improveStrategy` must be `default`, `consolidate` or a configured strategy, except that load exempts `graph-refresh` and the removed names (the error is raised at resolution; `graph-refresh` is refused there even with a user block and dropped only by `akm migrate apply`). The removed strategy names `quick, thorough, catchup, reflect-distill, proactive-maintenance` pass load but fail at resolution naming `default`. *Why:* unattended model work runs over generated content with no one watching; #1130. (`src/core/config/config-schema.ts:243-325`, `src/core/config/engine-semantics.ts`, `src/commands/improve/execution.ts:58-70`, #1130)
 - **`extends` inheritance strips host-local settings** — An inherited layer loses `bundles, defaultBundle, defaultWriteTarget, embedding, execution, experimental, registries, scheduler, setup`. It also loses engine `apiKey/apiKeyFile/bin/args/workspace`, `search.curateRerank`, and improve strategy `sync`. Each strip warns once. *Why:* shared config contributes portable behavior only; credentials, executables, endpoints and publication policy stay host-local. (`src/core/config/config.ts:399-485`, #945)
 - **Bundle entry shape** — A bundle needs exactly one of `path|git|website|npm`. `writable: true` is allowed only on `path` and `git`. `credential` is allowed only on `git`. `components` holds exactly one component. `defaultBundle` and `defaultWriteTarget` must name a configured, enabled bundle. Bundle keys must be legal slugs (no `/ : . #` or whitespace), and two bundles may not share one physical content root. (`src/core/config/schema/sources-bundles.ts:155-240`, `src/core/config/config-schema.ts:190-225`, `src/core/config/config.ts:290-297`)
 - **Autonomy opt-in is explicit** — `experimental.improveAutonomy` is off whether absent or `false`, and is never inferred. It gates memory cleanup, memory-inference writes, and triage promote when judgment is on. `sync.push` is deliberately not gated by it. (`src/core/config/schema/experimental.ts:19-32`, `src/commands/improve/autonomy-gate.ts:10-20`)
 - **Other defaults** — `feedback.requireReason` is true, output is `json`/`brief`, and the default registries are `akm-registry` (enabled) and `skills.sh` (disabled). `workflow.maxConcurrency`, `workflow.defaultMapConcurrency` and `workflow.judgeEngine` are described under Tasks, workflows and sync. (`src/core/config/config.ts:76-87`, `src/commands/feedback-cli.ts:644-648`)
-- **Persisted-data compat by format** — `index.db` is layout 26: older layouts migrate in place and never drop `embeddings`, `utility_scores*` or `llm_enrichment_cache`, and a newer layout is refused with "Upgrade akm", leaving the file untouched. Only `SQLITE_CORRUPT` deletes and rebuilds it. `state.db` migrations are append-only; an older binary on a newer ledger continues with a warning, and a `.pre-<id>.bak` copy is taken before schema-dropping migrations. Frozen workflow plans are irVersion 6, and the irVersion 5 shape is still decoded; a plan that cannot be decoded is abandoned (status `failed`), never thrown. The legacy `{kind, ref, sourceId}` `scheduler.enabled` form is still read. *Why:* the `docs/architecture/persisted-data-compat.md` contract; #865. (`docs/architecture/persisted-data-compat.md:33-44`, `src/storage/repositories/index-entry-schema.ts:32`, `src/storage/repositories/index-schema.ts:61,245`, `src/core/state-db.ts:105`, `src/workflows/runtime/run-plan.ts:46,113`)
+- **Persisted-data compat by format** — `index.db` is layout 26: older layouts migrate in place and never drop `embeddings`, `utility_scores*` or `llm_enrichment_cache`, and a newer layout is refused with "Upgrade akm", leaving the file untouched. Only `SQLITE_CORRUPT` deletes and rebuilds it. `state.db` migrations are append-only; an older binary on a newer ledger continues with a warning, and a `.pre-<id>.bak` copy is taken before schema-dropping migrations. Frozen workflow plans are irVersion 7; irVersion 5 and 6 plans still decode, with their location fields ignored; a plan that cannot be decoded is abandoned (status `failed`), never thrown. The legacy `{kind, ref, sourceId}` `scheduler.enabled` form is still read. *Why:* the `docs/architecture/persisted-data-compat.md` contract; #865. (`docs/architecture/persisted-data-compat.md:33-44`, `src/storage/repositories/index-entry-schema.ts:32`, `src/storage/repositories/index-schema.ts:61,245`, `src/core/state-db.ts:105`, `src/workflows/runtime/run-plan.ts:46,113`)
 
 ## Tasks, workflows and sync
 
@@ -801,13 +801,13 @@ Paths are relative to the rules-010 checkout. `repository.ts` is `src/commands/p
 **Workflows (the whole surface is Experimental; STABILITY.md)**
 
 - **Workflow source is Markdown only** — Step ids match `[A-Za-z_][A-Za-z0-9_-]*`. Every `##` heading must be a declared step id. An optional `### gate` section holds the rubric. A canonical ref must be owned by exactly one recognized `.md`. (`src/workflows/parser.ts:110`, `src/workflows/compile.ts:41-47`, `src/workflows/source-files.ts:69`, `docs/reference/workflow-schema.md:Body structure`)
-- **A run executes a frozen plan** — `akm workflow run <ref>` freezes an irVersion 6 plan (`plan_json`, `plan_hash`, `sourceHash`) at start. Resume reads only the frozen plan and never re-reads config, the index, or the source, other than to warn once if the source changed. A stored plan that does not decode is abandoned (status `failed`) with a message naming `akm workflow run <ref>`. Models, tools, working directory and runner are frozen. Workflow environment pass-through values and env/secret references are materialized at dispatch. *Why:* #919 (editing a workflow broke in-flight runs). (`src/workflows/plan.ts:28`, `src/workflows/freeze/freeze.ts:36-100`, `src/workflows/exec/run-workflow.ts:312-345`, `docs/architecture/workflow-engine.md:Frozen plans`, #919)
+- **A run executes a frozen plan** — `akm workflow run <ref>` freezes an irVersion 7 plan (`plan_json`, `plan_hash`, `sourceHash`) at start. Resume executes only the frozen plan and never re-reads the index or the workflow source, other than to warn once if the source changed; each dispatching step re-reads live config for the run's bundle root, its env bindings and its `${ref}` tokens. A stored plan that does not decode is abandoned (status `failed`) with a message naming `akm workflow run <ref>`. Models, tools and runner are frozen. The working directory is not: it is the root of the bundle that owns the run's workflow, found at each step, with `exec.cwd` joined onto it once. Workflow environment pass-through values and env/secret references are materialized at dispatch. *Why:* #919 (editing a workflow broke in-flight runs). (`src/workflows/plan.ts:31`, `src/workflows/freeze/freeze.ts:36-100`, `src/workflows/exec/run-workflow.ts:312-345`, `docs/architecture/workflow-engine.md:Frozen plans`, #919)
 - **Param defaults are applied at run start** — Every declared `default:` fills a param the run was not given, from flags, task inputs or an object. Explicit values win, params are never required, and supplied-plus-default values are schema-validated. Flags and an object cannot be mixed (`Workflow parameters must use either an object or per-parameter flags, not both`). Params are declared non-secret, with an advisory warning for secret-shaped values. *Why:* #1162, since defaults were previously accepted but never applied and prompts showed `Run parameters: {}`. (`src/workflows/ir/params.ts:89`, `src/workflows/runtime/runs.ts:241-262,337`, #1162)
-- **One active run per (ref, scope)** — Starting a ref with an active run in the same scope resumes it. `--new` starts a separate run and leaves the old one untouched. Scope is the nearest `.akm/config.json`, else git root, else the stash if cwd is inside it, else cwd. An active run of the same ref in another scope only produces a warning. *Why:* #485 (zero concurrency control) and #942 (a scheduled task's cwd differed from the shell's). (`src/workflows/authoring/scope-key.ts:12-33`, `src/workflows/runtime/runs.ts:286-306`, #485, #942, #919)
+- **A ref starts a run; a run id continues it** — `akm workflow run <ref>` always starts a new run and warns, naming `run <id>`/`abandon`, when other runs of the ref are active. `akm workflow run <run-id>` continues a run; `akm workflow resume <run-id>` re-activates a blocked or failed one. Runs are not scoped to a directory, so `list` and `status` see every run on the host. `--skip-if-locked` skips a ref start while an active run of the ref is held by a live process. `--new` and `--all-scopes` are deprecated no-ops through 0.10. *Why:* #485 (zero concurrency control), #942 (a scheduled task's cwd differed from the shell's) and #1239 (a run is a run id). (`src/workflows/runtime/runs.ts`, `src/commands/workflow-cli.ts`, #1239)
 - **One engine drives a run** — `workflow run` takes an O_EXCL lock file per run (`workflow-run-locks/<run id>.lock`). A second process gets `RUN_LEASE_HELD` (exit 75). A dead holder is reclaimed at once; nothing expires by age. A run that is not `active` is refused before dispatch, with a hint to `akm workflow resume`. (`src/workflows/exec/run-workflow.ts:226-239,312-330`)
 - **Dispatch is at-least-once with unit reuse** — Units are journaled under a content-derived id plus an input hash (`hashVersion` 7). A `completed` unit is reused on resume and never re-dispatched, while failed or missing units are dispatched. An ambiguous crash can duplicate a side effect. (`docs/architecture/workflow-engine.md:Resume skips completed units`, `src/workflows/exec/step-work.ts:513-521`)
 - **Map fan-out width** — A `map` step with no `concurrency:` freezes width 4. A step's real width is the minimum of its own `concurrency`, the run's frozen `workflow.maxConcurrency` (unset → `min(16, max(1, cores−2))`; set → clamped to [1, 64]), the LLM engine's concurrency (1 for loopback endpoints, 4 for remote, or `engines.<n>.concurrency`), and the host CPU cap re-derived at dispatch. Loopback detection is purely syntactic. *Why:* local model servers fail hard on concurrent inference; one config must work across machines. (`src/workflows/concurrency-policy.ts:12-59`, `src/workflows/resource-limits.ts:16`, `src/workflows/freeze/freeze.ts:96`, `docs/reference/workflow-schema.md:Fan-out`)
-- **Exec (shell) units** — `exec.command` is an argv array, never a shell string, and no engine, model or llm is allowed beside it. The default timeout is 600,000 ms unless the unit or `defaults.timeout` sets one (`timeout: none` opts out). Stdout and stderr retention is 8 MiB each: past that, a unit with no `output:` schema succeeds with a `__akm_exec_output_truncated__` marker appended, and a unit with an `output:` schema fails `exec_output_limit`. `exec_context_too_large`, `exec_cwd_escape` and `exec_capture_incomplete` are not retryable. (`src/workflows/resource-limits.ts:31,39`, `src/workflows/freeze/step-values.ts:83-95`, `docs/reference/workflow-schema.md:Exec units`)
+- **Exec (shell) units** — `exec.command` is an argv array, never a shell string, and no engine, model or llm is allowed beside it. The default timeout is 600,000 ms unless the unit or `defaults.timeout` sets one (`timeout: none` opts out). Stdout and stderr retention is 8 MiB each: past that, a unit with no `output:` schema succeeds with a `__akm_exec_output_truncated__` marker appended, and a unit with an `output:` schema fails `exec_output_limit`. `exec_context_too_large` and `exec_capture_incomplete` are not retryable. (`src/workflows/resource-limits.ts:31,39`, `src/workflows/freeze/step-values.ts:83-95`, `docs/reference/workflow-schema.md:Exec units`)
 - **Failure policy** — Fail-fast is the default, and `on_error: continue` lets the completion gate decide. `retry: {max, on}` requires `max ≥ 0` and a non-empty `on` list of failure reasons (`timeout, spawn_failed, non_zero_exit, parse_error, cooldown, llm_rate_limit, llm_content_filter, llm_invalid_json, content_policy_reject, unsupported_type, no_change, quality_rejected, aborted`). A unit `output` schema miss re-dispatches once with corrective feedback; an exec unit fails immediately instead. Budget ceilings (`max_units`, `max_tokens`) are run-lifetime counters seeded from the journal and are a hard stop that ignores `on_error: continue`. (`src/workflows/parser.ts:84-103,1155-1190`, `docs/reference/workflow-schema.md:Failure policy,Budget ceilings`)
 - **Gates are fail-closed** — A non-empty `### gate` rubric enables mandatory verification. The judge sees the step's artifact as canonical JSON clipped at 4,000 chars plus the byte-exact rubric. Only a well-formed `complete: true` verdict advances the step. A missing judge, a dispatch failure or a malformed verdict rejects or blocks. `gate.max_loops` (default 1) bounds the evaluator-optimizer retries, and only `command` targets loop. Shell and child-workflow steps are judged once. At freeze, a missing verification engine is a warning, not an error: the step blocks for `akm workflow resume` when reached. *Why:* a gate judging a machine summary like "Executed 3 units" proves nothing; re-running a frozen argv would repeat side effects. (`src/workflows/exec/step-work.ts:54,729-738,975-983,1237`, `src/workflows/freeze/freeze.ts:73-88,114-127`, `src/workflows/parser.ts:369,1115-1120`)
 - **Child workflows (Experimental, #1165)** — A step declares `unit: { workflow: workflows/<name>, with: {param: literal | {from: ref}} }`. The child is compiled and frozen whole, embedded in the parent's frozen target at freeze, and never re-read at dispatch. Only a composition cycle is checked (`COMPOSITION_INVALID`). `workflow` cannot sit beside `exec/engine/model/llm/env` or inside `map.unit`. The child is published idempotently, keyed by `{parentRunId, parentUnitId, unitInputHash}`, and driven inline with the same engine. A child already `blocked` or `failed` is not re-driven. The child's final status maps onto the composing step, and a completed child returns its last step's output. A top-level `outputs:` key no longer exists. Child runs are hidden from `workflow list` unless `--children`. *Why:* #1096 owner decision B: keep a simple, Experimental form. (`src/workflows/freeze/targets/child-workflow.ts:67-125`, `src/workflows/exec/child-workflow.ts:209-357`, `docs/reference/workflow-schema.md:Child workflows`, #1165)
@@ -824,7 +824,7 @@ Paths are relative to the rules-010 checkout. `repository.ts` is `src/commands/p
 - `docs/reference/workflow-schema.md` documents `gate.max_loops` as 1–100 and `retry.max` as 0–100. The parser and JSON schema enforce only `≥ 1` and `≥ 0`.
 - `docs/architecture/workflow-engine.md:65-66` claims three composition bounds (depth, cycle, aggregate embedded bytes) enforced at freeze; `docs/reference/workflow-schema.md:80-84` documents the cycle alone; `src/workflows/freeze` implements only the cycle check (`child-workflow.ts:67-76,88`; `freeze.ts:64` recurses unbounded).
 - `docs/reference/workflow-schema.md` says a gate rubric requires `workflow.judgeEngine` before freezing. The code falls back to default engine resolution and, if none is available, warns at freeze and blocks the step at run time.
-- `docs/guides/scheduling.md:63-64` says `irVersion: 5` (now 6); `workflow-engine.md:56-59` still lists removed `uses:` forms and the `script` target.
+- `workflow-engine.md:56-59` still lists removed `uses:` forms and the `script` target.
 - The shipped hint files (`cli-hints-short.md:11,42`, `cli-hints-full.md:96-104`) and `docs/reference/cli.md:1792-1795` tell agents to run `--positive` with no reason, which starves distill (a positive with no reason or note is skipped there); `cli.md:1793` shows `akm feedback agents/reviewer --negative` with no `--reason`, a usage error by default.
 - `docs/architecture/workflow-engine.md` still says "Markdown or GitHub-Actions-style YAML".
 - The `src/core/config/config-schema.ts` header says `scheduler`, `execution`, `experimental` and reranker policy are strict. All are `.passthrough()`.

package/docs/architecture/architecture.md

@@ -434,10 +434,10 @@ here; any other field the transport cannot carry becomes a secret-free
 `untranslated-field` notice and dispatch continues.
 
 Credentials stay symbolic (an env descriptor, an `apiKeyFile` path, or a
-`secret://` reference) in everything `resolveExecution` returns, so a request
-and runner can be journaled. `runExecution()` reads the current value at each
-dispatch and scrubs it, with every other secret-looking value the child could
-see, from the result. Workflow resume calls `buildExecutionFromWire()` on the
+`${ref}` reference such as `${secrets/openai}`) in everything
+`resolveExecution` returns, so a request and runner can be journaled.
+`runExecution()` reads the current value at each dispatch and scrubs it, with
+every other secret-looking value the child could see, from the result. Workflow resume calls `buildExecutionFromWire()` on the
 journaled `{ request, runner }` and never reads config, `models.json`, or
 credentials, so a config edit after the freeze cannot change a resumed unit.
 The prompt-free interactive `akm agent` launch resolves its engine directly.
@@ -446,7 +446,7 @@ through to another configured engine.
 
 Task-v3 execution and durable workflow-v4 dispatch use this runtime boundary.
 Markdown workflows compile through source IR v1; new starts freeze
-v4-family `irVersion: 5`. A stored plan that decodes runs whatever release
+v4-family `irVersion: 7` (plans frozen at `irVersion` 5 and 6 still decode). A stored plan that decodes runs whatever release
 froze it; one that does not is marked abandoned and `akm workflow run <ref>`
 starts afresh. Only a plan a newer akm froze is refused, naming the upgrade.
 AKM does not support full GitHub Actions semantics or arbitrary remote action
@@ -556,7 +556,7 @@ activity registry around them; `state.db` writers serialize on SQLite's own
 | `src/commands/agent/` | contribute/agent command surface |
 | `src/registry/providers/` | registry provider implementations (static-index, skills-sh) |
 | `src/output/shapes/`, `src/output/text/` | JSON-envelope and text-output registries per command (#490) — a parallel concern to `src/output/renderers.ts`'s per-asset-type `show` renderers, which is still live and self-registering, not replaced |
-| `src/workflows/authoring/` | workflow authoring + scope-key helpers |
+| `src/workflows/authoring/` | workflow authoring |
 | `src/workflows/runtime/runs.ts` | workflow run persistence (raw SQL lives in `src/storage/repositories/workflow-runs-repository.ts`) |
 | `src/workflows/runtime/` | run lifecycle: runs, checkin, agent-identity |
 | `src/llm/client.ts` | OpenAI-compatible chat completions client (stateless, single request/response) |

package/docs/architecture/comparisons/claude-code-vs-akm-workflows-full.md

@@ -11,7 +11,7 @@ The short version: they are not competitors. An akm workflow is a durable
 workflow asset authored in either of two peer source formats, Markdown `.md`
 or GitHub-shaped YAML `.yml`, and executed by the Stable
 `akm workflow run` command. Both adapters compile through source IR version 1.
-Every new start freezes the durable plan v4 family's executable `irVersion: 5`
+Every new start freezes the durable plan v4 family's executable `irVersion: 7`
 before execution. The native engine
 fans work out to concurrent runner units, retries, gates on typed artifacts,
 and enforces budget ceilings. Execution is native: akm dispatches each unit to
@@ -254,7 +254,7 @@ run lease), `008`/`009` (unit attempts / claim columns).
 
 `akm workflow run` is the one stable native execution surface. Peer source formats use the same source IR v1 before durable freezing: Markdown `.md` and YAML `.yml`.
 A new start by ref compiles source
-IR v1 and freezes the resulting durable-v4-family `irVersion: 5` plan on the
+IR v1 and freezes the resulting durable-v4-family `irVersion: 7` plan on the
 run row (`plan_json`/`plan_hash`); edits to the source file need a new run.
 Pre-`irVersion`-5
 stored plans are rejected rather than keeping a parallel runtime. The
@@ -292,20 +292,14 @@ agent session execute units itself; it was removed in favour of the single
 native path, since native dispatch already covers ten harnesses — Claude Code
 among them — for less code than the protocol cost.
 
-### B.5 Scoping & concurrency guards (two different guards)
-
-Runs are partitioned by **`scope_key`** — a `sha256` of the nearest project
-anchor (`.akm/config.json` root → git root → bundle dir → cwd),
-`src/workflows/authoring/scope-key.ts`. Within a `(workflow_ref, scope_key)`
-pair, `startWorkflowRun` enforces a **single active run** unless `--force` is
-passed internally. The public CLI exposes no parallel-start flag: invoking
-`workflow run` by ref continues the active run in that scope. This guard is
-scope-local by design (two unrelated projects sharing one `state.db` must be
-able to run the same-named workflow independently), so two *different*
-scopes can each hold their own active run of the same ref — starting one
-warns about an active run in another scope (naming its id and scope) rather
-than blocking it, and `akm workflow list --all-scopes` / `status` / `resume`
-/ `abandon <run-id>` see and act across scopes (#942).
+### B.5 Run identity & concurrency
+
+A run is identified by its run id and a workflow by its bundle-qualified ref;
+runs are not partitioned by directory. `workflow run <ref>` always starts a
+new run, so several runs of one ref can be active at once. A start that finds
+other active runs of the ref warns, naming their ids and the `resume` /
+`abandon` commands, and `--skip-if-locked` skips instead of starting when an
+active run of the ref is held by a live process (#1239).
 
 Orchestrated runs add a second, unrelated guard: the **run lease**. `akm
 workflow run` takes a lease (a random holder id, 90s expiry, renewed between
@@ -383,14 +377,14 @@ orchestration surface.
 
 | Dimension | Claude Code workflow | akm workflow |
 |---|---|---|
-| **Artifact** | Imperative JS program (`script`) | Declarative workflow asset (`.md` or `.yml`), compiled through source IR v1 to durable-v4-family `irVersion: 5` |
+| **Artifact** | Imperative JS program (`script`) | Declarative workflow asset (`.md` or `.yml`), compiled through source IR v1 to durable-v4-family `irVersion: 7` |
 | **Authored by** | The agent, inline, per-task, ephemeral | Human or agent, saved as a reusable bundle asset |
 | **Who executes work** | The harness runs the script; subagents do the work | The native engine, dispatching to a configured harness |
 | **Unit of work** | `agent()` — a fresh LLM subagent context | One dispatch or one `map` item under the engine |
 | **Concurrency** | Massively parallel (≤16 concurrent, ≤1000 total, `pipeline`/`parallel`) | Bounded map concurrency, frozen into the plan |
 | **Control flow** | Full JS: loops, conditionals, fan-out, budget-scaled | `unit`/`map`/`route`, bare reference strings, and bounded gate retries; no backward routes |
 | **State store** | Transcript dir (`journal.jsonl`, `agent-*.jsonl`) | SQLite `state.db`; native-engine runs add unit rows and a frozen `plan_json`/`plan_hash` |
-| **Scope / lifetime** | One session, one turn-shaped fan-out | Cross-session, per-project `scope_key`, resumable indefinitely |
+| **Scope / lifetime** | One session, one turn-shaped fan-out | Cross-session, host-wide (a run is identified by its id), resumable indefinitely |
 | **Progress model** | Push: live `/workflows` tree + `task-notification` | Pull via `status`, with near-live NDJSON event polling via `akm log` |
 | **Resume** | Prefix-cache replay keyed on `runId` (needs determinism) | Durable row resume; native-engine units add journaled replay keyed on content-derived identity |
 | **Quality gates** | Agent-authored (adversarial verify, judge panels, schemas) | Fail-closed LLM or agent verification of typed artifacts; `gate.max_loops` bounds retries |

package/docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md

@@ -29,10 +29,9 @@ Moved verbatim from `exec-unit.ts`'s module header:
 > - NO LEAKED CHILDREN. `runManagedSubprocess` spawns DETACHED and runs a
 >   SIGTERM→SIGKILL ladder against the whole process group, so `--timeout`
 >   and Ctrl-C really do stop a running command and its descendants.
-> - CONTAINMENT. `exec.cwd` is relative and `..`-free by construction
->   (parser and frozen-plan decoder), which is necessary but not sufficient:
->   a subdirectory can be a symlink. The RESOLVED path is therefore
->   re-checked against the RESOLVED base immediately before spawning.
+> - NO CONTAINMENT. `exec.cwd` is relative to the run's bundle root or
+>   absolute, and nothing checks where it leads: a command can reach any
+>   directory anyway, so a directory is not a security boundary.
 > - BOUNDED SPEND. A command is arbitrary code with no resource discipline
 >   of its own, so each resource it spends on akm's behalf has a ceiling in
 >   `workflows/resource-limits.ts`: wall clock (`DEFAULT_EXEC_TIMEOUT_MS` or
@@ -52,8 +51,7 @@ Moved verbatim from `exec-unit.ts`'s module header:
 > which is why this module may return raw stdout/stderr diagnostics without
 > knowing anything about redaction.
 >
-> Layering: a LEAF. Node built-ins, `core/common` (for `isWithinAsync`, the
-> CONTAINMENT recheck above), `core/spawn-env`, `core/subprocess`,
+> Layering: a LEAF. Node built-ins, `core/spawn-env`, `core/subprocess`,
 > `core/warn` and the import-free `workflows/resource-limits` (plus erased
 > types) only, so the executor can consume it without opening an import
 > cycle.
@@ -127,8 +125,8 @@ Moved verbatim from `runExecUnit`'s doc comment:
 > `timeout`, cancellation → `aborted`, a child that never started →
 > `spawn_failed`. All four are pre-existing `AgentFailureReason` members, so
 > `retry.on` keeps working unchanged. The out-of-taxonomy
-> `exec_cwd_escape`, `exec_output_limit`, `exec_context_too_large` and
-> `exec_capture_incomplete` are deliberate: each is tampering, a runaway, an
+> `exec_output_limit`, `exec_context_too_large` and
+> `exec_capture_incomplete` are deliberate: each is a runaway, an
 > authoring bug, or work that ALREADY RAN — never a transient — so no
 > `retry.on` value can ever re-dispatch one.
 >

package/docs/architecture/internals/storage-locations.md

@@ -332,7 +332,7 @@ explicit retention policy removes them.
 
 #### Table: `workflow_runs`
 
-New starts persist durable-v4-family plan `irVersion: 5`, the sole executable
+New starts persist durable-v4-family plan `irVersion: 7`, the sole executable
 plan format. Pre-`irVersion`-5 stored
 plans are rejected rather than upgraded or replayed through another runtime.
 
@@ -340,8 +340,8 @@ plans are rejected rather than upgraded or replayed through another runtime.
 |---|---|---|
 | `id` | TEXT PRIMARY KEY | UUID v4 |
 | `workflow_ref` | TEXT NOT NULL | e.g. `workflows/review-todos` |
-| `scope_key` | TEXT | Directory hash; isolates runs per project. Gates `list`'s default filter, `akm show`'s active-run nudge, and `startWorkflowRun`'s own-scope uniqueness guard (unchanged, still per-scope) — so two DIFFERENT scopes can each hold their own active run of the same ref; starting one warns about the other rather than blocking it (#942). `akm workflow list --all-scopes` sees across scopes, and `status`/`resume`/`abandon <run-id>` already act on a run regardless of which scope started it |
-| `workflow_entry_id` | INTEGER | Optional FK into `index.db entries.id` |
+| `scope_key` | TEXT | Legacy: a directory hash written by releases before 0.10. Never written or read now (NULL on new rows); the column and its index stay so older rows load |
+| `workflow_entry_id` | INTEGER | Legacy: an `index.db entries.id` written by releases before 0.10. Never written now (NULL on new rows) |
 | `workflow_title` | TEXT NOT NULL | Human-readable title |
 | `status` | TEXT NOT NULL | `active`, `completed`, `blocked`, `failed` |
 | `params_json` | TEXT NOT NULL DEFAULT '{}' | Run parameters |
@@ -618,7 +618,7 @@ The JSONL file at `$CACHE/events.jsonl` is no longer read or written by akm.
 | `curate` | `akm curate` | `query`, `itemCount`, `itemRefs[]` |
 | `show` | `akm show` | `type`, `name` |
 | `select` | `akm show`, when a search within the last 60s returned the ref | `query`, `searchTs`, `rankPosition` |
-| `env_access` | `akm env run`, and a workflow step's frozen environment | `keys`; `secretNames` from a workflow step (names only, never values) |
+| `env_access` | `akm env run`, and a workflow step's `env:` bindings (read at each step) | `keys` (names only, never values) |
 | `secret_access` | `akm secret run` | `var` (the variable name, never the value) |
 | `promoted` | `akm proposal accept`, and drain/triage promotion | `proposalId`, `source`, `sourceRun`, `assetPath`, `eligibilitySource`; `retired: true` for a retire proposal |
 | `rejected` | `akm proposal reject` | `proposalId`, `source`, `sourceRun`, `reason` |

package/docs/architecture/persisted-data-compat.md

@@ -36,11 +36,12 @@ and named once, round-trips through ordinary writes, and is dropped by
 
 | Format | Where written | Version marker | Older data | Newer data | Gate |
 | --- | --- | --- | --- | --- | --- |
-| `config.json` | `src/core/config/config.ts` | `configVersion` field | `configVersion` is read, never gated on (`readConfigVersion`, `src/core/config/config.ts`): a missing field or `"0.9.0"` — the only value akm has shipped — loads silently, and any other value is named once and read as `0.9.0`. Below the 0.9.15 floor the file is refused, not converted: the retired `stashDir`/`sources[]`/`installed[]` layout fails validation (`AkmConfigSchema`, `src/core/config/config-schema.ts`) and an `extraParams` key that shadows a first-class engine field (`temperature`, `maxTokens`, `enableThinking`, `reasoningEffort`) is rejected by `validateExtraParams`, each telling the user to run `akm migrate apply` under akm 0.9.x or to set the field. A config with no `scheduler.enabled` (0.9.15 wrote none) is read as "keep what is installed": `akm task sync` adopts the akm-written scheduler rows as the list (`tests/integration/upgrade-rehearsal/`'s 0.9.15 origin). 0.9.16's `{kind, ref, sourceId}` `scheduler.enabled` entries are still read, as their `ref`, and written back as plain refs; `akm migrate apply`'s `configFile` step (`normalizeConfigFile`) persists that — `configVersion: "0.9.0"`, unknown keys dropped — to the file once, under a backup | Same as older: the value is named once and the file is read as `0.9.0`; there is no `UNSUPPORTED_CONFIG_VERSION` refusal. `akm health`'s `binary-config-skew` advisory (`src/commands/health/config-skew.ts`) is what says "a newer akm wrote this config, upgrade this install" | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/config-v09.test.ts` |
+| `config.json` | `src/core/config/config.ts` | `configVersion` field | `configVersion` is read, never gated on (`readConfigVersion`, `src/core/config/config.ts`): a missing field or `"0.9.0"` — the only value akm has shipped — loads silently, and any other value is named once and read as `0.9.0`. Below the 0.9.15 floor the file is refused, not converted: the retired `stashDir`/`sources[]`/`installed[]` layout fails validation (`AkmConfigSchema`, `src/core/config/config-schema.ts`) and an `extraParams` key that shadows a first-class engine field (`temperature`, `maxTokens`, `enableThinking`, `reasoningEffort`) is rejected by `validateExtraParams`, each telling the user to run `akm migrate apply` under akm 0.9.x or to set the field. A config with no `scheduler.enabled` (0.9.15 wrote none) is read as "keep what is installed": `akm task sync` adopts the akm-written scheduler rows as the list (`tests/integration/upgrade-rehearsal/`'s 0.9.15 origin). 0.9.16's `{kind, ref, sourceId}` `scheduler.enabled` entries are still read, as their `ref`, and written back as plain refs. A `secret://<name>` credential (`engines.*.apiKey`, `embedding.apiKey`, a git bundle's `credential`, any config string) is retired: the reader (`readRetiredSecretRefs`, `src/core/config/config.ts`) takes it as `${<name>}` when `<name>` is already a full ref, else `${secrets/<name>}`, naming the key once. `akm migrate apply`'s `configFile` step (`normalizeConfigFile`) persists that — `configVersion: "0.9.0"`, `secret://` rewritten, unknown keys dropped — to the file once, under a backup | Same as older: the value is named once and the file is read as `0.9.0`; there is no `UNSUPPORTED_CONFIG_VERSION` refusal. `akm health`'s `binary-config-skew` advisory (`src/commands/health/config-skew.ts`) is what says "a newer akm wrote this config, upgrade this install" | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/config-v09.test.ts` (including the `secret://` read and rewrite) |
 | `state.db` | `src/core/state/migrations.ts` (append-only `MIGRATIONS` registry, applied by `src/storage/sqlite-migrations.ts`) | `schema_migrations` ledger table | `openStateDatabase` opens one connection (mkdir, open, standard pragmas), reads the ledger on it, and runs every migration not yet applied forward in one transaction; a missing/empty/table-less file is simply a fresh database. Before a migration that drops schema (`018-drop-dead-lane-schema`, `028-improve-ledger`; `STATE_MIGRATION_SAFETY_BY_ID`) runs against a database that already has migrations applied, the file is copied beside itself to `state.db.pre-<migration id>.bak` via `VACUUM INTO` on the same connection | An older binary opening a `state.db` migrated by a newer akm continues with the schema it knows and warns once (`warnNewerStateLedger`, `src/core/state-db.ts`); it does not refuse; only a ledger that diverges from this akm's registry is refused (`assertMigrationLedger`) | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`) |
 | `index.db` | `src/storage/repositories/index-schema.ts` (`ensureSchema`; `index-entry-schema.ts` for the DDL and the layout constant) | `index_meta.version` = `CANONICAL_INDEX_DB_VERSION` (26), a layout marker | Readers (`openExistingDatabase` / `openReadonlyExistingDatabase`) serve it as-is and name `akm index` once (`checkIndexLayout`); the writable opener migrates in place — added columns via `ALTER TABLE`, a one-time FTS rebuild from `entries` for the layout-23 content-copy tables, and for layout 24 the drops of the sqlite-vec mirror `entries_vec` (when sqlite-vec loads; dropping a vec0 table needs it) and `entry_fragments_fts`, with `entries.search_text` hashed into `embed_hash` before the column is dropped so no vector is re-embedded, and for layout 25 the declared links (`asset_links`, #935) derived from each entry's stored `document_json` with no file read (only the directories holding workflows and tasks, whose targets no earlier layout stored, lose their incremental cursor and re-drain on the next `akm index`) — never dropping `embeddings`, `utility_scores*`, or `llm_enrichment_cache`. It drops the lazy-extraction queue `graph_extraction_queue`, retired in 0.9.17, and, on any layout, the LLM entity graph (`graph_meta`, `graph_files`, `graph_file_*`) and its `llm_enrichment_cache` rows, retired in 0.9.17-alpha.9 — an older release's `CREATE TABLE IF NOT EXISTS` recreates the graph tables (empty) if it ever opens this index again. It also deletes `llm_enrichment_cache` rows at the default `cache_variant` — the metadata-enhance pass, retired in 0.9.17-alpha.9 — on any layout; memory inference uses its own named variant and is unaffected. A migration leaves `index_meta.vacuumPending`, and the next `akm index` VACUUMs the freed pages. An `entries` table older than layout 21 has its entries-keyed tables recreated: one that lacks a column this release reads, or that still has a transitional column layout 21 removed (`entry_key`, `dir_path`, `stash_dir`, `entry_json`, `entry_type`), as the table 0.9.1 wrote does, with `document_json` empty on every row. A reader finds such a table unservable (`hasCurrentEntriesTable`), so a read rebuilds it inline. Only `SQLITE_CORRUPT` deletes and rebuilds the file (#865) | Refused by readers and the writable opener alike (`INDEX_SCHEMA_INCOMPATIBLE`, "Upgrade akm to use this index.", `newerIndexLayoutError`), leaving the file untouched: a newer layout may lack a column this akm reads, as layout 25 lacks `search_text` | `tests/integration/indexer/index-layout-migration.test.ts` (layout-23 and layout-24 fixtures); `tests/integration/previous-release-corpus.test.ts` (the layout-25 index 0.9.17-alpha.7 wrote, `index-v25.sql`, and the layout-20 index 0.9.1 wrote, `index-v20.sql`); `tests/integration/storage/index-generation-read-boundary.test.ts`; upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`) |
 | Task source (`tasks/*.yml`) | `src/tasks/source/parse-task-source.ts` | `version: 4` (`TASK_SOURCE_V4_VERSION`) | **The named exception to the contract (#987): the runtime reads only v4.** `version: 2` or `version: 3` throws `TASK_SCHEMA_VERSION_UNSUPPORTED`, and a declared `version: 4` document whose `schedule[]` still carries 0.9.15's retired `enabled` key throws `TASK_SOURCE_INVALID`; both messages name `akm migrate apply`, the one place the conversion happens (`scripts/akm-migrate/migrate/task-files.ts`, planning every v2/v3/v4 file straight to v4 with the pure planner `scripts/akm-migrate/migrate/task-to-v4.ts`, rewriting under a backup; `akm upgrade` runs it after an install). It covers every stash the runtime reads tasks from: each enabled configured bundle, and the stash `AKM_BUNDLE_DIR` selects when no bundle names it; the `akm-task` probe still recognizes a root of v2/v3 task files, so one without a recorded adapter is found. Every caller reports the refusal for that one file: `akm task sync` keeps reconciling every other task and leaves the file's installed row as it is | Any other `version` throws `TASK_SCHEMA_VERSION_UNSUPPORTED` naming `akm migrate apply` | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`); `tests/integration/previous-release-corpus.test.ts` (each older shape is refused at runtime and converted by the migrator) |
-| Workflow IR (frozen plans) | `src/workflows/freeze/freeze.ts`, read back in `src/workflows/runtime/run-plan.ts` (`readRunPlan`, `decodeWorkflowPlan`) | `irVersion` (`WORKFLOW_PLAN_VERSION`, 6) on the plan and in `plan_ir_version`; `plan_hash` alongside | Every workflow compiles to one plan type. `decodeWorkflowPlan` reads the irVersion 5 shape 0.9.15 and 0.9.16 wrote (its `sourceReadSet` and host-identity fields included) as well as the current one, and keeps keys it does not know. Neither the version nor the hash gates a read: a stored plan that decodes runs whatever `irVersion` froze it, with one warning; one that cannot be decoded is abandoned by `akm workflow run` (status `failed`) with a message naming `akm workflow run <ref>` to start afresh — a status change, never an exception; `status`/`list`/`abandon` never read the plan | A newer akm's plan that still decodes runs the same way; one that does not decode is left untouched and refused with a message naming "Upgrade akm" (`readRunPlan`'s `newer`) | `tests/workflows/run-plan.test.ts`; `tests/integration/workflows/frozen-plan.test.ts` — the rehearsal builds no workflow run |
+| Workflow IR (frozen plans) | `src/workflows/freeze/freeze.ts`, read back in `src/workflows/runtime/run-plan.ts` (`readRunPlan`, `decodeWorkflowPlan`) | `irVersion` (`WORKFLOW_PLAN_VERSION`, 7) on the plan and in `plan_ir_version`; `plan_hash` alongside | Every workflow compiles to one plan type. `decodeWorkflowPlan` reads the irVersion 5 shape 0.9.15 and 0.9.16 wrote (its `sourceReadSet` and host-identity fields included) and the irVersion 6 shape (a shell or command target's `cwdIdentity`, an env-ref's `owner`, `keys` and `secretNames`) as well as the current one, and keeps keys it does not know. The irVersion 6 location fields are kept exactly as stored and never read: a v6 run dispatches by ref, finding the bundle root and the env asset again, but the unit `input_hash` and the child invocation key derive from the whole decoded target (an embedded child plan included), so dropping a field would give an interrupted v6 parent a new key after the upgrade and publish a second child (`irVersion` 7 writes none of them, and the inode and path fields left the shell `contentHash` preimage and the unit `input_hash` for new plans only; stored rows keep their hashes). A runner's `apiKeySecretRef` / `fallbackApiKeySecretRef` in the retired `secret://<name>` form is likewise kept as stored by `decodeFrozenRunnerSpec` and read as `${secrets/<name>}` where it is resolved (`lookupApiKeySecretRefValue`, `resolveLlmCredentialValue`, via `liftRetiredSecretRef`), with no warning. An `irVersion` 7 command target freezes `cwdIdentity: {}`, which the v7 decoder carries and ignores: akm 0.10.0 and earlier decode a command-only v7 plan (they only warn on a version mismatch, and read `cwdIdentity` loosely) and would run it in the invoking directory, but their dispatch (`prepareWorkflowExecution`) refuses an identity it cannot verify with `PATH_ESCAPE_VIOLATION` before anything is spawned. A v7 shell target or `env:` ref already fails their decode. The hash gates nothing and neither does an older version: a stored plan that decodes runs whatever older `irVersion` froze it, with one warning; one that cannot be decoded is abandoned by `akm workflow run` (status `failed`) with a message naming `akm workflow run <ref>` to start afresh — a status change, never an exception; `list`/`abandon` never read the plan, and `status --units` decodes it, read-only and without a warning, only to describe a failed unit | A plan whose `plan_ir_version` is above this release's is left untouched and refused, whether or not it would decode, with a message naming "Upgrade akm" (`readRunPlan`'s `newer`) | `tests/workflows/run-plan.test.ts`; `tests/integration/workflows/legacy-plan-child-identity.test.ts` (a v6 parent resumed after the upgrade recovers its child); `tests/integration/workflows/frozen-plan.test.ts`; `tests/integration/workflows/frozen-identities.test.ts` (a v6 `plan_json` row dispatches by ref) — the rehearsal builds no workflow run |
+| Workflow run rows (`workflow_runs.scope_key`, `workflow_entry_id`) | `src/storage/repositories/workflow-runs-repository.ts` (`insertRun`, `publishChildWorkflowRun`) | No marker; the columns stay in the schema | A row from before 0.10 carries a directory-hash `scope_key` (`dir:v1:…`) and, for a top-level run, an `index.db` `workflow_entry_id`. Neither is read: `list`, `status`, `resume`, `abandon` and the start warning select runs by run id and `workflow_ref` alone, so those rows stay visible from any directory. New rows (0.10, #1239) write NULL in both columns. `bundle rename` rewrites `workflow_ref` on every row naming the old bundle prefix (a legacy unqualified ref is left alone) and lists the renamed bundle's active and blocked runs, whose frozen `plan_json` keeps the old qualified refs | A 0.9.15 binary on the same `state.db` filters runs by `scope_key`, so it does not see runs 0.10 started (owner-accepted, #1239): finish or abandon them before downgrading | `tests/integration/state-db/state-migration-023.test.ts`, `state-migration-024.test.ts` (the column set); `tests/workflows/run-resume-and-new.test.ts` (new rows write NULL) |
 | Native scheduler rows (crontab, launchd plists, Task Scheduler) | `src/tasks/backends/cron.ts`, `launchd.ts`, `schtasks.ts`; the invocation grammar in `src/tasks/scheduler-invocation.ts` | The row's own invocation shape: current rows set their environment inline (a cron `VAR=value` prefix, a plist `EnvironmentVariables` entry, a PowerShell `$env:` assignment) — always `AKM_BUNDLE_DIR`, the syncing shell's working stash — and carry no `--scheduler-context`; 0.9.0 – 0.9.17-alpha.6 rows carry `--scheduler-context <descriptor>` holding the same values; older rows carry neither. A cron command over 1,000 bytes runs an akm wrapper script (`sh <log dir>/.akm-cron-wrapper-…sh`) that holds the same line | Every shape is listed and parsed (`parseScheduledInvocationArgv`; a spilled cron row from its wrapper script): a row inside akm's own `# akm:task` markers from before `--scheduler-context` (#881), and a `--scheduler-context` row, which keeps firing (the CLI applies its descriptor, below) until the next plain `akm task sync` rewrites it in place — an update that keeps the row's launcher and schedule, never an add or remove. The primary bundle proves a row by the `AKM_BUNDLE_DIR` it carries, inline or in its descriptor (#846); any other bundle owns rows by name. Rows that still carry the pre-0.9.17 workflow execution-evidence marker (`# akm:workflow-evidence` in the crontab, an `akm-workflow-evidence` plist comment or PowerShell literal) are listed like any other and rewritten once without it. Plain `akm task sync` keeps an installed row's own launcher (`installOptionsFor`, `src/tasks/scheduler-sync.ts`) and recomputes its environment; `akm task sync --rebind` repoints the launcher | A row inside akm's markers, `com.akm.task.` label namespace, or `\akm\` task folder whose argv this binary cannot parse (for example one a newer akm wrote) is not listed: sync leaves it alone unless an enabled source renders a row with the same native id, which then replaces it — the row is derived state and its source is the record. A crontab whose akm markers are malformed is refused unmodified (`parseBlocks`, `cron.ts`) | Upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`: the previous release's `--scheduler-context` rows fire under the candidate, then `task sync --dry-run` shows them only as updates); `tests/tasks-sync.test.ts` (`--scheduler-context` rows and spilled rows are updates, never adds) |
 | Scheduler-context descriptor (`$DATA/tasks/context/<sha256>.json`, written by 0.9.0 – 0.9.17-alpha.6) | No longer written: a row carries its own environment (#987). Read by `src/tasks/scheduler-invocation.ts` (`readLegacySchedulerContext`) | `version: 1`; the environment key set | When a row that names one fires, the CLI reads the file as plain JSON and applies its `AKM_*_DIR` keys and, in one written before 0.9.17, `PATH`; nothing else about the file (name, mode, owner, link) is checked. Sync reads its `AKM_BUNDLE_DIR` to attribute the row. A plain `akm task sync` that reconciles the row rewrites it without the argument; a row a sync leaves as it is (its source failed, a `--bundle` sync did not cover it) keeps naming the file | A key this binary does not know is ignored. A file that is gone or is not JSON fails the run with `INVALID_CONFIG_FILE` naming `akm task sync`; sync cannot attribute such a row to the primary bundle and leaves it in place, and `akm task prune` reports it as `invalid-context` | `tests/tasks-scheduler-invocation.test.ts`; `tests/integration/scheduler-context-launcher.test.ts`; upgrade rehearsal gate (`tests/integration/upgrade-rehearsal/`) fires the previous release's rows under the candidate before and after its plain `task sync` |
 | Proposal `metadata_json` | `src/storage/repositories/proposals-repository.ts` | No explicit version field; presence/absence of the `changes` key | Rows from before the `changes` key existed (~89% of archived rows on real installs) are treated as a known legacy gap — decoded with an empty change list rather than thrown (`proposals-repository.ts:47-56`). 0.9.17-alpha.9 adds a consolidate pair-pass `retire` proposal's `changes[0].op: "delete"` (no `after`, already a valid `FileChangeOp`) and its `retirement` / `retiredArchive` / `promotionSource` / `promotionSourceHash` metadata keys, plus the retirement continuity check's `retirement.continuityRisk` (rule R3, item 1) — a person can accept a proposal carrying it by id even though it is excluded from bulk accept; an older reader's `validatePresentMetadata` does not enumerate these keys, so it neither inspects nor rejects them — the row decodes with them silently absent, same as any other field an older release predates. 0.9.19 adds `reviewHistory` (the rejections `akm proposal reopen` undid, oldest first, each with its gate verdict) the same way: a proposal reopened by 0.9.19 and read by an older release is an ordinary pending proposal with its history absent, and that release drops the key if it rewrites the row. `retirement.judgedScope` (Unreleased, #1197) optionally records the shared normalized memory scope tuple; `{}` means known unscoped and absence means unknown. Older rows still decode unchanged; acceptance refuses an unknown tuple and asks for rejection/reassessment, rather than inferring judgment from live files. Staged stale decisions use the existing stale-target rejection/ledger retry path. Older readers carry this nested object through but do not enforce it, so do not downgrade before reviewing pending retirements. No format-version bump or database migration is needed for this additive metadata. The quality judge's evidence, `scores` and `judgeReason`, is added inside the existing `gateDecision` object (Unreleased): an older reader's `validatePresentMetadata` checks only the gate fields it knows and carries the object through whole, so the evidence survives a rewrite by an older release unread. An older release also counts a pending proposal's age (retention expiry, `--older-than`) from `createdAt`, so after a downgrade a reopened proposal can expire at the next `akm improve` run (a retire proposal never expires), or be swept by a scheduled `--older-than` bulk action or drain | 0.9.17-alpha.8 and earlier predate the retire proposal shape entirely — they were never taught to read a delete-primary change with no `after`. `akm proposal show` / `diff` / `drain` exit 70 on one, and drain's own nightly pre-pass failing on the first pending retire proposal it meets stops that run's auto-promotion for the whole stash, not just that one proposal. **Downgrade gate:** every pending retire proposal must be accepted or rejected (`akm proposal accept` / `reject`) before downgrading to 0.9.17-alpha.8 or earlier — once decided it is archived, out of the pending set `show`/`diff`/`drain` iterate, and no longer trips this. **Gap** otherwise (no code-level guard; this is operator guidance only). Downgrading also revives the starvation the second review round's B1 fixed forward-only: 0.9.17-alpha.8's `retrieval-scope.ts` counts a `consolidate-pair` ledger row as processed, so the pair pass's own nightly attempts crowd new material back out of every other improve lane's scope, the same way they did before B1 — measured on the real bundle, two alpha.9 nights left only 341 of 2,183 new-only assets still in scope once read under alpha.8. **Gap** here too (the ledger `source` string carries no version of its own; operator guidance only — do not downgrade across a pair-pass run without expecting this). | `tests/proposal-repository-pure.test.ts` — unit only; the rehearsal builds no proposal |

package/docs/architecture/specs/0.9.0-public-api-issue-backlog.md

@@ -727,7 +727,7 @@ split first). Recompute when those land.
 
 Under the agent-toolkit identity, the following were reviewed and are **not**
 defects of scope, only subject to the coherence/safety issues above:
-`akm env`/`akm secret` (including run-injection and `${secret:}` interpolation),
+`akm env`/`akm secret` (including run-injection and `${ref}` interpolation),
 `akm agent` and the ten harness integrations, the workflow engine including the
 `brief`/`report` external-driver protocol, `akm tasks` and its three OS
 backends, the improve/proposal/collapse-detector loop, and the health

package/docs/architecture/specs/akm-format-neutral-bundle-workspace-spec.md

@@ -1118,8 +1118,8 @@ Secret-bearing content MUST preserve current protections:
 - no values in output or telemetry;
 - no shell sourcing of untrusted dotenv content;
 - process injection without command substitution;
-- path containment;
-- dangerous environment-key policy;
+- write-side path containment;
+- the non-blocking `dangerous-env-key` lint rule (#1237 removed the install and injection gates);
 - redaction in logs and errors.
 
 ---
@@ -1677,7 +1677,7 @@ grant or silently reduce it.
 
 *(Two v0.2 clauses — untrusted presentation clamping and a catch-all sensitive-content refusal — were withdrawn in v0.3, deviation §4.3c. Catch-all adapters remain explicit-configuration-only and never auto-selected (§9.4): a user who mounts a root with `generic-files` indexes what they pointed it at, deliberately.)*
 
-The dangerous-environment-key policy keeps its origin asymmetry across the config migration **as a port of the existing rule** (today: `registryId`-bearing source → hard block; first-party → warn): an env export from a registry-installed source containing process-hijacking keys MUST still hard-error after `installed[]` is replaced, covered by a port-preservation conformance test. This is existing behavior surviving the migration, not new machinery.
+*(Amended 2026-10-22, #1237: the dangerous-environment-key policy and its origin asymmetry were removed. Installing a bundle is the trust decision, so env export and injection from any bundle neither block nor warn on process-hijacking keys. The `dangerous-env-key` lint rule remains, non-blocking.)*
 
 ### 28.3 Path safety