akm-cli 0.9.28-alpha.5 → 0.9.28-alpha.7

package/CHANGELOG.md

@@ -6,6 +6,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.7] - 2026-10-08
+
+### Added
+
+- **An agent engine can name a default `agent`.** `engines.<name>.agent` (`opencode`, `opencode-sdk`, `claude`)
+  is the native agent the engine runs when a request names none, so an `opencode-sdk` engine, which takes no
+  `args`, can run e.g. `akm-workflow` for workflows and tasks. A request's own agent wins, a persona is kept,
+  and model work keeps its confined agent. See [Configuration](docs/reference/configuration.md) (#1049).
+
+### Changed
+
+- **Stability tiers for 0.10's stabilization work.** Experimental: the built-in
+  improve strategies other than `default` and `consolidate` (`quick`,
+  `reflect-distill`, `thorough`, `catchup`), the proactive-maintenance and
+  high-salience lanes, and session extraction (`akm proposal extract`).
+  Evolving and now listed: `akm command run` and `akm models`; every agent
+  harness (the `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`,
+  `amazonq`, `openhands` included) and the `okf`, `llm-wiki` and
+  `generic-files` adapters are named Evolving. `akm upgrade`'s plugin step and
+  `--next` are targeted to become Stable before the 0.9 series ends.
+
+- **Workflows are Experimental.** The `akm workflow` commands (`run`, `status`,
+  `list`, `create`, `resume`, `abandon`, `plan`), the workflow asset format and
+  the engine move to Experimental in STABILITY.md and the help text, for the rest
+  of 0.9 and all of 0.10, which stabilizes the feature and then promotes it or
+  removes it. Nothing changes in how they run.
+
+### Fixed
+
+- **Consolidate's pair pass no longer retires a knowledge note in favour of a memory (#1092).** Knowledge is the
+  reviewed form and a memory is raw capture, often the very memory the note was promoted from, yet a `duplicate`,
+  `supersedes` or `subsumed` verdict could retire `knowledge/...` for `memories/...` (a `.derived` memory counts as a
+  memory). When the verdict would do that and the judge lists no claim held only by the memory, the memory is retired
+  in favour of the note instead, through the same guards and staging as any memory retirement; when the memory holds
+  a claim of its own, nothing is minted and the pair is counted as a no-action verdict. A memory is still retired in
+  favour of a knowledge note, and knowledge against knowledge is unchanged.
+
+## [0.9.28-alpha.6] - 2026-10-08
+
+### Fixed
+
+- **The #1063 fix now reaches files that have not changed (#1063).** An incremental `akm index` skips a
+  directory whose files are unchanged, so a reference file already filed as a command stayed
+  `commands/skills/<name>/...` until `akm index --full`. The `akm` adapter's version, which is part of each
+  directory's freshness, is bumped, so the next `akm index` after upgrading re-files those rows once (about 18
+  entries in a 18,000-entry library) and drops their old refs. Reading every directory once makes that run slower
+  (about 27 s against 2 s on that library) and re-embeds the entries whose embedding hash was written by an older
+  release (about 8,000 of them); later runs cost what they did before.
+
 ## [0.9.28-alpha.5] - 2026-10-08
 
 ### Added

package/STABILITY.md

@@ -54,17 +54,17 @@ enumeration of the whole `proposal` noun group.
 | `akm bundle show` | Evolving | See note above. |
 | `akm bundle remove` | Stable | |
 | `akm bundle update` | Stable | |
-| `akm upgrade` | Evolving | |
+| `akm upgrade` | Evolving | The plugin step and `--next` (0.9.28) are being verified on real hosts to become Stable before the 0.9 series ends. |
 | `akm search` | Stable | |
 | `akm curate` | Stable | |
 | `akm show` | Stable | |
-| `akm workflow status` | Stable | `--all-scopes` added in 0.9.15 (#942), additive. |
-| `akm workflow plan` | Evolving | New in 0.9.2; secret-free provenance output; envelope shape may change. |
-| `akm workflow list` | Stable | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942), both additive. |
-| `akm workflow create` | Stable | |
-| `akm workflow resume` | Stable | |
-| `akm workflow abandon` | Stable | |
-| `akm workflow run` | Stable | Canonical start/resume/execute command. |
+| `akm workflow status` | Experimental | `--all-scopes` added in 0.9.15 (#942), additive. |
+| `akm workflow plan` | Experimental | New in 0.9.2; secret-free provenance output; envelope shape may change. |
+| `akm workflow list` | Experimental | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942), both additive. |
+| `akm workflow create` | Experimental | |
+| `akm workflow resume` | Experimental | |
+| `akm workflow abandon` | Experimental | |
+| `akm workflow run` | Experimental | Canonical start/resume/execute command. |
 | `akm remember` | Stable | |
 | `akm import` | Stable | |
 | `akm sync` | Stable | |
@@ -83,6 +83,8 @@ enumeration of the whole `proposal` noun group.
 | `akm feedback` | Stable | |
 | `akm log` | Evolving | |
 | `akm agent` | Evolving | |
+| `akm command run` | Evolving | Runs stored command templates through the same agent dispatch as `akm agent`. |
+| `akm models` | Evolving | `list` and `copy-defaults` for model intent aliases. |
 | `akm lint` | Evolving | |
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
 | `akm proposal list` | Stable | See reconciliation note above. |
@@ -93,7 +95,7 @@ enumeration of the whole `proposal` noun group.
 | `akm proposal reopen` | Evolving | New in 0.9.19; undoes a rejection. |
 | `akm proposal revert` | Evolving | |
 | `akm proposal drain` | Evolving | |
-| `akm proposal extract` | Evolving | Former top-level `akm extract`. |
+| `akm proposal extract` | Experimental | Former top-level `akm extract`. Session extraction quality is still being measured (0.10, #1094). |
 | `akm proposal new` | Evolving | Former top-level `akm propose`. |
 | `akm help` | Stable | |
 | `akm help agents` | Stable | |
@@ -291,9 +293,8 @@ CHANGELOG with a migration note.
 - **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
   compile+freeze introspection (the canonical step graph, task/child
   expansion, input bindings, and lowering notices for a workflow, without
-  starting or publishing a run). The envelope shape may still change; the
-  five long-Stable `workflow` verbs (`status`, `list`, `create`, `resume`,
-  `abandon`) and `run` are unaffected.
+  starting or publishing a run). The envelope shape may still change. Like every
+  `workflow` verb it is Experimental from 0.9.28 (see Experimental below).
 - **Events / log** — `akm log` is the event-stream surface (0.9.0: the
   asset-scoped `akm history` surface, and `log`'s own `tail` subcommand, were
   both removed; `log` is now a leaf command — the former `list` surface).
@@ -302,7 +303,8 @@ CHANGELOG with a migration note.
   commands/agents, knowledge, YAML workflows, tasks, env/secret files, scripts,
   OKF and LLM-wiki knowledge bases). Config is keyed by `bundles` and
   `defaultBundle`. The adapter set, bundle-recognition rules, and the
-  `bundles` config shape may still shift. Bundles are inspected through
+  `bundles` config shape may still shift; the `okf`, `llm-wiki` and
+  `generic-files` adapters in particular are Evolving. Bundles are inspected through
   `akm bundle list` / `akm bundle show <name>` and enumerated through
   `akm search "bundle//"`. (An earlier `akm bundle items` noun group was
   removed in 0.9.0 as duplicative of `akm search`; the current `akm bundle`
@@ -318,9 +320,15 @@ CHANGELOG with a migration note.
   `log.md` / `raw/` / `pages/` and its ingest flow); wiki pages are addressed
   as ordinary concepts inside their bundle. Adapter behavior and page
   conventions are still iterating.
-- **Agent dispatch** — `akm agent` subcommand. Supported backends: `claude`,
-  `opencode`, `opencode-sdk`, `codex`, `copilot`, `pi`, `gemini`, `aider`,
-  `amazonq`, `openhands`. The set will grow.
+- **Agent dispatch** — `akm agent` and `akm command run`. Supported backends:
+  `claude`, `opencode-sdk` (the primary OpenCode interface), `codex`, and the
+  `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`, `amazonq`,
+  `openhands`. Every harness is Evolving: the harness implementation is being
+  reworked so harnesses are easy to add, remove and update (0.10), and the
+  `opencode` CLI dispatch path is a deprecation candidate once `opencode-sdk`
+  covers it. The set will grow.
+- **Model aliases** — `akm models list|copy-defaults` and the intent-alias
+  defaults they expose.
 - **Proposal queue** — quality classifications (`accepted`, `pending`,
   `proposed`, `rejected`, `archived`) are stable; the JSON shape of a
   proposal record may add fields.
@@ -330,7 +338,9 @@ CHANGELOG with a migration note.
   lives outside the CLI, in `scripts/build-registry-index.ts`.
 - **Upgrade** — `akm upgrade`. Checksum verification is not optional; the
   recovery hatch is the `AKM_UPGRADE_SKIP_CHECKSUM` environment variable
-  (Internal), not a flag.
+  (Internal), not a flag. The harness plugin step and `--next` (new in 0.9.28)
+  are targeted to become Stable before the 0.9 series ends, once verified on
+  real hosts.
 - **Lint** — `akm lint`. The rule set and finding shapes iterate; the
   `--fail-on-flagged` CI contract and the exit codes are stable.
 - **Health** — `akm health` and its exit codes (0 pass / 4 warn / 1 fail) are
@@ -342,6 +352,12 @@ CHANGELOG with a migration note.
 Subject to change without notice within minor releases. Not yet recommended
 for scripted use.
 
+- **Workflows** — the whole `akm workflow` surface (`run`, `status`, `list`,
+  `create`, `resume`, `abandon`, `plan`), the workflow asset format and the
+  workflow engine are Experimental from 0.9.28 and throughout 0.10. The 0.10
+  series stabilizes the feature and trims what is not useful, then either
+  promotes it out of Experimental or removes it if stabilization does not
+  produce a quality feature.
 - **`akm metrics`** — new in 0.9.28. What it reports, its JSON shape and the
   `--format html` dashboard may change in any release; do not script against
   them.
@@ -361,6 +377,13 @@ for scripted use.
 - **Memory belief-state transitions** — `captureMode`, `beliefState`,
   contradiction edges, and the consolidate journal are observable but
   the algorithm that writes them is tuning across patch releases.
+- **Improve built-in strategies and lanes** — the built-in strategies other
+  than `default` and `consolidate` (`quick`, `reflect-distill`, `thorough`,
+  `catchup`) and the proactive-maintenance and high-salience lanes. 0.10
+  measures each and keeps, folds or removes it (#1094).
+- **Session extraction** — `akm proposal extract` and the `extract` process:
+  what it extracts, its quality gates and its output may change while 0.10
+  measures it (#1094).
 - **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
   engines, limits, gates, and the anti-collapse / CLS / fidelity knobs) and
   the `index.*` per-pass config. The 0.9.x series is explicitly still settling

package/dist/commands/improve/consolidate/pair-pass.js

@@ -581,7 +581,15 @@ async function judgeOne(ctx, candidate) {
     const decision = decideRetirement(verdict.relation, verdict.redundant, older, newer, verdict);
     if (!decision)
         return { failed: false };
-    const { retired, successor } = decision;
+    let { retired, successor } = decision;
+    // Owner rule (#1092): knowledge is never replaced with a memory (a `.derived` memory is a memory). When the memory
+    // holds nothing the note lacks, retire the memory in favour of the note instead; otherwise leave the pair alone.
+    // The flipped pair then runs every guard below like any memory retirement.
+    if (retired.asset.type === "knowledge" && successor.asset.type === "memory") {
+        if ((successor === older ? verdict.onlyInA : verdict.onlyInB).length > 0)
+            return { failed: false };
+        [retired, successor] = [successor, retired];
+    }
     // Guards (plan §5.2 step 4 / brief §A "Guards").
     if (retired.asset.type === "memory" && isHotCapturedMemory(retired.asset.filePath)) {
         return { failed: false }; // never propose retiring a captureMode: hot memory — leave the pair alone

package/dist/commands/improve/extract-cli.js

@@ -26,7 +26,7 @@ import { akmExtract, resolveStandaloneExtractPlan } from "./extract.js";
 export const extractCommand = defineJsonCommand({
     meta: {
         name: "extract",
-        description: "Extract durable insights from native session files (claude, codex, opencode) and queue them as proposals.",
+        description: "Experimental: extract durable insights from native session files (claude, codex, opencode) and queue them as proposals.",
     },
     args: {
         type: {

package/dist/commands/workflow-cli.js

@@ -432,7 +432,7 @@ const workflowResumeCommand = defineJsonCommand({
 export const workflowCommand = defineGroupCommand({
     meta: {
         name: "workflow",
-        description: "Author, inspect, and execute step-by-step workflow assets",
+        description: "Experimental: author, inspect, and execute step-by-step workflow assets",
     },
     subCommands: {
         status: workflowStatusCommand,

package/dist/core/adapter/adapters/akm-adapter.js

@@ -453,7 +453,11 @@ async function validate(c, changes, ctx) {
 }
 export const akmAdapter = {
     id: "akm",
-    version: "0.9.0",
+    // Bump when a change to the matchers (or `recognize`) can retype or re-ref a
+    // file that has not changed: the version is folded into each directory's
+    // freshness, so the next incremental `akm index` re-drains it and re-files
+    // those rows (#1063). 0.9.1: a skill's resource is never retyped by a `$1`.
+    version: "0.9.1",
     // Recognized-extension HINT, derived from what the matchers accept (§6):
     // `.md` (Markdown types + workflow peer), `.yml` (task and workflow YAML),
     // `.yaml` (task near-miss diagnostics), `.env` (env files), and the 16

package/dist/core/config/schema/engines.js

@@ -13,7 +13,7 @@ import { z } from "zod";
 // `config-types`, which type-derives from this barrel via
 // `typeof import("./config-schema")` — routing through config-types would mint
 // a config-schema ↔ config-types type cycle that collapses inference.
-import { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS } from "../../../integrations/harnesses/ids.js";
+import { HARNESS_AGENT_DISPATCH_IDS, HARNESS_NATIVE_AGENT_IDS, VALID_HARNESS_IDS, } from "../../../integrations/harnesses/ids.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../../../workflows/resource-limits.js";
 import { chatCompletionsEndpoint, ExtraParamsSchema, engineName, nonEmptyString, positiveInt, symbolicOrWarnApiKey, } from "./primitives.js";
 /**
@@ -89,7 +89,7 @@ const LlmEngineSchema = z
 })
     .passthrough()
     .superRefine((value, ctx) => {
-    for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine"]) {
+    for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine", "agent"]) {
         if (key in value)
             ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: `${key} is not valid on an LLM engine` });
     }
@@ -115,6 +115,7 @@ const AgentEngineSchema = z
     args: z.array(z.string()).optional(),
     workspace: nonEmptyString.optional(),
     model: nonEmptyString.optional(),
+    agent: nonEmptyString.optional(),
     timeoutMs: timeoutMsField,
     llmEngine: engineName.optional(),
 })
@@ -144,6 +145,13 @@ const AgentEngineSchema = z
             message: "llmEngine is only valid on opencode-sdk",
         });
     }
+    if (value.agent !== undefined && !HARNESS_NATIVE_AGENT_IDS.has(value.platform)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["agent"],
+            message: `agent is not valid on ${value.platform}: it has no native agent selector`,
+        });
+    }
     if (value.platform === "opencode-sdk" && value.args !== undefined) {
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["args"], message: "args is not valid on opencode-sdk" });
     }

package/dist/integrations/agent/engine-resolution.js

@@ -285,6 +285,7 @@ function lowerAgentEngine(name, engine, config) {
         parseOutput: "text",
         ...(engine.workspace ? { workspace: path.resolve(engine.workspace) } : {}),
         ...(engine.model ? { model: engine.model } : {}),
+        ...(engine.agent ? { agent: engine.agent } : {}),
     };
     // An engine that sets no timeoutMs leaves it unset, so a caller's own default
     // (model work's 600 s) can apply; a dispatch with none runs unbounded.

package/dist/integrations/agent/execution.js

@@ -59,6 +59,8 @@ function engineDefaults(name, engine, config) {
         return { kind: "llm", platform: engine.provider ?? name, modelMapKey: name, values };
     if (engine.workspace !== undefined)
         values.workspace = engine.workspace;
+    if (engine.agent !== undefined)
+        values.agent = engine.agent;
     if (engine.platform !== "opencode-sdk") {
         return { kind: "agent", platform: engine.platform, modelMapKey: engine.platform, values };
     }
@@ -120,6 +122,7 @@ function runnerDefaults(runner) {
             ...(inference ? { inference } : {}),
             ...timeout,
             ...(runner.profile.workspace !== undefined ? { workspace: runner.profile.workspace } : {}),
+            ...(runner.profile.agent !== undefined ? { agent: runner.profile.agent } : {}),
         },
     };
 }
@@ -345,7 +348,12 @@ export function resolveExecution(input) {
     const layers = [{ id: name, kind: "engine", values: defaults.values }, ...callerLayers];
     provenance.command = { layer: command.source?.ref ?? "inline", kind: "command", via: "source" };
     let persona = input.persona;
-    const agentLayer = nearest(layers, "agent");
+    // The engine's own `agent` is only a default for a request that names none: it never replaces a
+    // persona, and model work keeps its confined agent.
+    const engineAgentApplies = !persona && input.modelWork !== true;
+    let agentLayer = nearest(layers, "agent");
+    if (agentLayer?.kind === "engine" && !engineAgentApplies)
+        agentLayer = undefined;
     const agent = agentLayer?.values.agent;
     if (agentLayer) {
         provenance.agent = explicit(agentLayer);

package/dist/integrations/agent/request-lowering.js

@@ -4,7 +4,7 @@
 import { ConfigError } from "../../core/errors.js";
 import { withSchemaInstruction } from "../../core/structured.js";
 import { MODEL_WORK_POLICY_ID } from "../../execution/source.js";
-import { HARNESS_MODEL_WORK_IDS } from "../harnesses/ids.js";
+import { HARNESS_MODEL_WORK_IDS, HARNESS_NATIVE_AGENT_IDS } from "../harnesses/ids.js";
 import { composeConversationFallbackPrompt } from "./conversation-fallback.js";
 import { composePersonaFallbackPrompt } from "./persona-fallback.js";
 /** A tool selection that actually names tools (not omitted, null, or empty). */
@@ -77,7 +77,7 @@ export function createAgentRequestLowerer(options) {
             }
         }
         else if (typeof request.agent === "string") {
-            if (!options.nativeAgentSelector) {
+            if (!HARNESS_NATIVE_AGENT_IDS.has(options.adapter)) {
                 throw new ConfigError(`The ${options.adapter} transport cannot consume native agent selector ${JSON.stringify(request.agent)}.`, "INVALID_CONFIG_FILE");
             }
             dispatch.agent = request.agent;

package/dist/integrations/harnesses/claude/agent-builder.js

@@ -69,7 +69,6 @@ export const claudeBuilder = {
     lower: createAgentRequestLowerer({
         adapter: "claude",
         personaChannel: "native",
-        nativeAgentSelector: true,
         tools: "all",
     }),
     build(profile, req) {

package/dist/integrations/harnesses/ids.js

@@ -2,16 +2,16 @@
 // 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/.
 export const HARNESS_ID_TABLE = [
-    { id: "opencode", agentDispatch: true, enforcesModelWorkTools: true },
-    { id: "claude", agentDispatch: true, enforcesModelWorkTools: true },
-    { id: "opencode-sdk", agentDispatch: true, enforcesModelWorkTools: true },
-    { id: "codex", agentDispatch: true, enforcesModelWorkTools: false },
-    { id: "copilot", agentDispatch: true, enforcesModelWorkTools: false },
-    { id: "pi", agentDispatch: true, enforcesModelWorkTools: false },
-    { id: "gemini", agentDispatch: true, enforcesModelWorkTools: false },
-    { id: "aider", agentDispatch: true, enforcesModelWorkTools: false },
-    { id: "amazonq", agentDispatch: true, enforcesModelWorkTools: false },
-    { id: "openhands", agentDispatch: true, enforcesModelWorkTools: false },
+    { id: "opencode", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+    { id: "claude", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+    { id: "opencode-sdk", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+    { id: "codex", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+    { id: "copilot", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+    { id: "pi", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+    { id: "gemini", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+    { id: "aider", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+    { id: "amazonq", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+    { id: "openhands", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
 ];
 /**
  * Canonical, ordered list of valid harness / platform ids — the
@@ -24,3 +24,5 @@ export const VALID_HARNESS_IDS = Object.freeze(HARNESS_ID_TABLE.map((h) => h.id)
 export const HARNESS_AGENT_DISPATCH_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.agentDispatch).map((h) => h.id));
 /** Harness ids that confine the model-work tool policy, so unattended model work may run on them. */
 export const HARNESS_MODEL_WORK_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.enforcesModelWorkTools).map((h) => h.id));
+/** Harness ids that can run a named native agent, so an engine may name a default `agent`. */
+export const HARNESS_NATIVE_AGENT_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.nativeAgentSelector).map((h) => h.id));

package/dist/integrations/harnesses/opencode/agent-builder.js

@@ -45,7 +45,6 @@ export const opencodeBuilder = {
     lower: createAgentRequestLowerer({
         adapter: "opencode",
         personaChannel: "prompt",
-        nativeAgentSelector: true,
         tools: "none",
         inference: MODEL_WORK_AGENT_INFERENCE,
     }),

package/dist/integrations/harnesses/opencode-sdk/harness.js

@@ -40,7 +40,6 @@ export class OpencodeSdkHarness extends BaseHarness {
         lower: createAgentRequestLowerer({
             adapter: "opencode-sdk",
             personaChannel: "native",
-            nativeAgentSelector: true,
             tools: "sdk",
             inference: MODEL_WORK_AGENT_INFERENCE,
         }),

package/dist/scripts/akm-migrate-node.js

@@ -35729,20 +35729,21 @@ var coerce = {
 var NEVER = INVALID;
 // src/integrations/harnesses/ids.ts
 var HARNESS_ID_TABLE = [
-  { id: "opencode", agentDispatch: true, enforcesModelWorkTools: true },
-  { id: "claude", agentDispatch: true, enforcesModelWorkTools: true },
-  { id: "opencode-sdk", agentDispatch: true, enforcesModelWorkTools: true },
-  { id: "codex", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "copilot", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "pi", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "gemini", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "aider", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "amazonq", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "openhands", agentDispatch: true, enforcesModelWorkTools: false }
+  { id: "opencode", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+  { id: "claude", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+  { id: "opencode-sdk", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+  { id: "codex", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "copilot", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "pi", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "gemini", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "aider", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "amazonq", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "openhands", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false }
 ];
 var VALID_HARNESS_IDS = Object.freeze(HARNESS_ID_TABLE.map((h) => h.id));
 var HARNESS_AGENT_DISPATCH_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.agentDispatch).map((h) => h.id));
 var HARNESS_MODEL_WORK_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.enforcesModelWorkTools).map((h) => h.id));
+var HARNESS_NATIVE_AGENT_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.nativeAgentSelector).map((h) => h.id));
 
 // src/core/extra-params.ts
 var EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS = [
@@ -36035,7 +36036,7 @@ var LlmEngineSchema = exports_external.object({
   enableThinking: exports_external.boolean().optional(),
   reasoningEffort: nonEmptyString.optional()
 }).passthrough().superRefine((value, ctx) => {
-  for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine"]) {
+  for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine", "agent"]) {
     if (key in value)
       ctx.addIssue({ code: exports_external.ZodIssueCode.custom, path: [key], message: `${key} is not valid on an LLM engine` });
   }
@@ -36056,6 +36057,7 @@ var AgentEngineSchema = exports_external.object({
   args: exports_external.array(exports_external.string()).optional(),
   workspace: nonEmptyString.optional(),
   model: nonEmptyString.optional(),
+  agent: nonEmptyString.optional(),
   timeoutMs: timeoutMsField,
   llmEngine: engineName.optional()
 }).passthrough().superRefine((value, ctx) => {
@@ -36083,6 +36085,13 @@ var AgentEngineSchema = exports_external.object({
       message: "llmEngine is only valid on opencode-sdk"
     });
   }
+  if (value.agent !== undefined && !HARNESS_NATIVE_AGENT_IDS.has(value.platform)) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: ["agent"],
+      message: `agent is not valid on ${value.platform}: it has no native agent selector`
+    });
+  }
   if (value.platform === "opencode-sdk" && value.args !== undefined) {
     ctx.addIssue({ code: exports_external.ZodIssueCode.custom, path: ["args"], message: "args is not valid on opencode-sdk" });
   }
@@ -45086,7 +45095,7 @@ async function validate2(c, changes, ctx) {
 }
 var akmAdapter = {
   id: "akm",
-  version: "0.9.0",
+  version: "0.9.1",
   extensions: [
     ".md",
     ".yaml",
@@ -51340,7 +51349,7 @@ function createAgentRequestLowerer(options) {
         notices.push(...composed.notices);
       }
     } else if (typeof request.agent === "string") {
-      if (!options.nativeAgentSelector) {
+      if (!HARNESS_NATIVE_AGENT_IDS.has(options.adapter)) {
         throw new ConfigError(`The ${options.adapter} transport cannot consume native agent selector ${JSON.stringify(request.agent)}.`, "INVALID_CONFIG_FILE");
       }
       dispatch.agent = request.agent;
@@ -51561,7 +51570,6 @@ var claudeBuilder = {
   lower: createAgentRequestLowerer({
     adapter: "claude",
     personaChannel: "native",
-    nativeAgentSelector: true,
     tools: "all"
   }),
   build(profile, req) {
@@ -52603,7 +52611,6 @@ var opencodeBuilder = {
   lower: createAgentRequestLowerer({
     adapter: "opencode",
     personaChannel: "prompt",
-    nativeAgentSelector: true,
     tools: "none",
     inference: MODEL_WORK_AGENT_INFERENCE
   }),
@@ -52947,7 +52954,6 @@ class OpencodeSdkHarness extends BaseHarness {
     lower: createAgentRequestLowerer({
       adapter: "opencode-sdk",
       personaChannel: "native",
-      nativeAgentSelector: true,
       tools: "sdk",
       inference: MODEL_WORK_AGENT_INFERENCE
     })

package/dist/scripts/akm-migrate.js

@@ -35057,20 +35057,21 @@ var coerce = {
 var NEVER = INVALID;
 // src/integrations/harnesses/ids.ts
 var HARNESS_ID_TABLE = [
-  { id: "opencode", agentDispatch: true, enforcesModelWorkTools: true },
-  { id: "claude", agentDispatch: true, enforcesModelWorkTools: true },
-  { id: "opencode-sdk", agentDispatch: true, enforcesModelWorkTools: true },
-  { id: "codex", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "copilot", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "pi", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "gemini", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "aider", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "amazonq", agentDispatch: true, enforcesModelWorkTools: false },
-  { id: "openhands", agentDispatch: true, enforcesModelWorkTools: false }
+  { id: "opencode", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+  { id: "claude", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+  { id: "opencode-sdk", agentDispatch: true, enforcesModelWorkTools: true, nativeAgentSelector: true },
+  { id: "codex", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "copilot", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "pi", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "gemini", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "aider", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "amazonq", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false },
+  { id: "openhands", agentDispatch: true, enforcesModelWorkTools: false, nativeAgentSelector: false }
 ];
 var VALID_HARNESS_IDS = Object.freeze(HARNESS_ID_TABLE.map((h) => h.id));
 var HARNESS_AGENT_DISPATCH_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.agentDispatch).map((h) => h.id));
 var HARNESS_MODEL_WORK_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.enforcesModelWorkTools).map((h) => h.id));
+var HARNESS_NATIVE_AGENT_IDS = new Set(HARNESS_ID_TABLE.filter((h) => h.nativeAgentSelector).map((h) => h.id));
 
 // src/core/extra-params.ts
 var EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS = [
@@ -35363,7 +35364,7 @@ var LlmEngineSchema = exports_external.object({
   enableThinking: exports_external.boolean().optional(),
   reasoningEffort: nonEmptyString.optional()
 }).passthrough().superRefine((value, ctx) => {
-  for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine"]) {
+  for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine", "agent"]) {
     if (key in value)
       ctx.addIssue({ code: exports_external.ZodIssueCode.custom, path: [key], message: `${key} is not valid on an LLM engine` });
   }
@@ -35384,6 +35385,7 @@ var AgentEngineSchema = exports_external.object({
   args: exports_external.array(exports_external.string()).optional(),
   workspace: nonEmptyString.optional(),
   model: nonEmptyString.optional(),
+  agent: nonEmptyString.optional(),
   timeoutMs: timeoutMsField,
   llmEngine: engineName.optional()
 }).passthrough().superRefine((value, ctx) => {
@@ -35411,6 +35413,13 @@ var AgentEngineSchema = exports_external.object({
       message: "llmEngine is only valid on opencode-sdk"
     });
   }
+  if (value.agent !== undefined && !HARNESS_NATIVE_AGENT_IDS.has(value.platform)) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      path: ["agent"],
+      message: `agent is not valid on ${value.platform}: it has no native agent selector`
+    });
+  }
   if (value.platform === "opencode-sdk" && value.args !== undefined) {
     ctx.addIssue({ code: exports_external.ZodIssueCode.custom, path: ["args"], message: "args is not valid on opencode-sdk" });
   }
@@ -44414,7 +44423,7 @@ async function validate2(c, changes, ctx) {
 }
 var akmAdapter = {
   id: "akm",
-  version: "0.9.0",
+  version: "0.9.1",
   extensions: [
     ".md",
     ".yaml",
@@ -51335,7 +51344,7 @@ function createAgentRequestLowerer(options) {
         notices.push(...composed.notices);
       }
     } else if (typeof request.agent === "string") {
-      if (!options.nativeAgentSelector) {
+      if (!HARNESS_NATIVE_AGENT_IDS.has(options.adapter)) {
         throw new ConfigError(`The ${options.adapter} transport cannot consume native agent selector ${JSON.stringify(request.agent)}.`, "INVALID_CONFIG_FILE");
       }
       dispatch.agent = request.agent;
@@ -51556,7 +51565,6 @@ var claudeBuilder = {
   lower: createAgentRequestLowerer({
     adapter: "claude",
     personaChannel: "native",
-    nativeAgentSelector: true,
     tools: "all"
   }),
   build(profile, req) {
@@ -52598,7 +52606,6 @@ var opencodeBuilder = {
   lower: createAgentRequestLowerer({
     adapter: "opencode",
     personaChannel: "prompt",
-    nativeAgentSelector: true,
     tools: "none",
     inference: MODEL_WORK_AGENT_INFERENCE
   }),
@@ -52942,7 +52949,6 @@ class OpencodeSdkHarness extends BaseHarness {
     lower: createAgentRequestLowerer({
       adapter: "opencode-sdk",
       personaChannel: "native",
-      nativeAgentSelector: true,
       tools: "sdk",
       inference: MODEL_WORK_AGENT_INFERENCE
     })

package/docs/README.md

@@ -12,6 +12,7 @@ Full per-directory indexes: [Guides](https://github.com/itlackey/akm/blob/main/d
 
 ## Start
 
+- [Product Surface](https://github.com/itlackey/akm/blob/main/docs/product-surface.md) -- Every feature and its status
 - [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md) -- Install akm, connect a source, and pull a curated shortlist in five to seven minutes
 - [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) -- Capabilities, bundles, adapters, asset types, and refs -- the mental model in one page
 - [Agent Install Guide](https://github.com/itlackey/akm/blob/main/docs/agents/agent-install.md) -- Step-by-step automated (non-interactive) install for agents

package/docs/reference/cli.md

@@ -799,6 +799,9 @@ to run `akm bundle add <origin>` first.
 
 ### workflow
 
+**Experimental** (see [STABILITY.md](../../STABILITY.md)): the workflow commands, asset format and engine may
+change in any release through the 0.10 series, which decides whether the feature is stabilized or removed.
+
 Author, inspect, and execute structured workflow assets.
 
 ```sh
@@ -2892,6 +2895,8 @@ authenticates its root; it never falls back to an ambient write target.
 
 #### proposal extract
 
+**Experimental** (see [STABILITY.md](../../STABILITY.md)): session extraction is still being measured in 0.10.
+
 Extract durable insights from native coding-agent session files (claude-code,
 codex, opencode) and queue them as proposals. This is the standalone
 entrypoint for session extraction — it replaces the legacy session-checkpoint

package/docs/reference/configuration.md

@@ -129,9 +129,13 @@ value matching this JSON Schema (no prose, no code fences):` followed by the
 schema), plus the harness's own schema channel where it has one (codex
 `--output-schema`).
 
-An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`;
+An agent engine may set `bin`, `args`, `workspace`, `model`, `agent`, and `timeoutMs`;
 it takes no inference of its own (see
-[Inference on an agent engine](#inference-on-an-agent-engine)). Only `platform: "opencode-sdk"` may set `llmEngine`; it names
+[Inference on an agent engine](#inference-on-an-agent-engine)). `agent` names the
+engine's default native agent (`opencode`, `opencode-sdk` and `claude` only): it
+runs when a request names no agent, e.g. `{"kind":"agent","platform":"opencode-sdk","model":"openai/gpt-5.6-terra","agent":"akm-workflow"}`.
+A request's own agent wins, an agent asset's persona is kept, and model work keeps its confined
+agent. `opencode-sdk` takes no `args`, so `agent` is how an SDK engine names one. Only `platform: "opencode-sdk"` may set `llmEngine`; it names
 the LLM engine used as that SDK engine's fallback connection. With no
 `llmEngine`, an SDK engine has no fallback connection and opencode resolves
 provider, model and auth from its own configuration. `defaults.llmEngine` is
@@ -440,7 +444,9 @@ An improve process's engine follows
 [the one rule](#engines-for-unattended-model-work); an explicit invalid or
 incompatible engine never falls back to another engine. Built-in strategies
 are complete presets. User-defined strategies inherit omitted fields from the
-built-in `default` strategy before applying their own overrides.
+built-in `default` strategy before applying their own overrides. The built-in
+strategies other than `default` and `consolidate` are Experimental (see
+[STABILITY.md](../../STABILITY.md)): 0.10 measures each and keeps, folds or removes it.
 
 `processes.triage.judgment` explicitly controls the optional judgment tier.
 Use `true` to enable it, `false` to disable it, or an object with `enabled`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.28-alpha.5",
+  "version": "0.9.28-alpha.7",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -130,6 +130,10 @@
                 "type": "string",
                 "minLength": 1
               },
+              "agent": {
+                "type": "string",
+                "minLength": 1
+              },
               "timeoutMs": {
                 "anyOf": [
                   {
@@ -1802,6 +1806,10 @@
                     "type": "string",
                     "minLength": 1
                   },
+                  "agent": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "timeoutMs": {
                     "anyOf": [
                       {