akm-cli 0.9.0-rc.14 → 0.9.0-rc.15

package/CHANGELOG.md

@@ -6,8 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Removed
+
+- **The experimental `akm workflow brief` / `akm workflow report`
+  external-driver protocol is removed**, along with the
+  `experimental.workflowEngine` config key that gated it, its
+  `WORKFLOW_ENGINE_NOT_ENABLED` error code, and the `workflowEngine` block in
+  `akm task doctor`. `akm workflow run` is now the single execution surface.
+
+  The protocol let a calling agent session execute a run's units itself
+  instead of akm dispatching them. Its stated justification was harness
+  neutrality, which measurement did not support: native dispatch already
+  covers **ten** harnesses (opencode, claude, opencode-sdk, codex, copilot,
+  pi, gemini, aider, amazonq, openhands) in 2,214 LOC total, while the
+  protocol cost 2,690 LOC on its own — more than supporting every harness
+  natively — and an eleventh harness is ~220 lines, not a protocol. Removing
+  it also drops the second consumer of `workflow_run_units` and the
+  cross-surface parity obligation on `step-work.ts`, both of which
+  constrained every future engine change. The analysis is recorded in
+  `docs/architecture/specs/driver-protocol-keep-or-cut.md`.
+
+  Legacy configs setting `experimental.workflowEngine` remain valid — the
+  config schema is `.passthrough()`, so the key is accepted and ignored.
+
 ### Added
 
+- **`akm workflow run` and prompt tasks fall back to `opencode-sdk` instead of
+  refusing when no engine is configured.** A clean install that never ran
+  `akm setup` — a bare container, a CI image, an agent-operated session — used
+  to fail closed with `INVALID_CONFIG_FILE` (exit 78). When the `opencode`
+  binary is on PATH, akm now synthesizes a **config-free** `opencode-sdk`
+  engine: it carries no model, endpoint, or credential, so provider, model,
+  and auth all resolve from opencode's own configuration and akm never mirrors
+  or validates it. With `opencode` absent the failure is unchanged, and its
+  remedy now names both routes. An operator-configured `opencode-sdk` engine
+  always wins over the synthesized one.
+
+  The requirement is the **binary**, not the npm package: `@opencode-ai/sdk`
+  is an HTTP client that declares no dependencies and whose own
+  `createOpencodeServer` spawns `opencode serve`, so a host with the package
+  and no binary has no server to reach. Install it with `npm i -g opencode-ai`
+  or opencode's own installer.
+
+  The fallback is **announced, never silent**: a workflow run surfaces it once
+  at run creation in the result's `warnings`, and a prompt task writes it to
+  the task run log. The frozen plan records the engine actually used, so a
+  resume never re-announces a decision it did not make.
+
 - **RSS, Bluesky, and X sources.** `akm bundle add` now recognizes three new
   kinds of URL and snapshots them as knowledge assets instead of crawling
   them as ordinary web pages:

package/dist/cli/retired-commands.js

@@ -56,7 +56,9 @@ const RETIRED_COMMAND_HINTS = {
     "workflow watch": "`akm workflow watch` was removed in 0.9 — use `akm log --run <run-id>`.",
     "workflow start": "`akm workflow start` was removed in 0.9 — use `akm workflow run <ref>`.",
     "workflow next": "`akm workflow next` was removed in 0.9 — use `akm workflow status <target>` to inspect or `akm workflow run <target>` to execute.",
-    "workflow complete": "`akm workflow complete` was removed in 0.9 — native runs complete steps automatically; external drivers use `akm workflow brief` and `akm workflow report`.",
+    "workflow complete": "`akm workflow complete` was removed in 0.9 — `akm workflow run <target>` completes steps automatically; use `akm workflow status <target>` to inspect.",
+    "workflow brief": "`akm workflow brief` was removed — the external-driver protocol is gone; `akm workflow run <target>` executes the run and `akm workflow status <target>` inspects it.",
+    "workflow report": "`akm workflow report` was removed — the external-driver protocol is gone; `akm workflow run <target>` dispatches and records units itself.",
     "config show": "`akm config show` was removed in 0.9 — use `akm config list`.",
     "config validate": "`akm config validate` was removed in 0.9 — the config file is validated on every load.",
     "task enable": "`akm task enable` was removed in 0.9 — set `enabled: true` in the task YAML, then `akm task sync`.",

package/dist/commands/agent/agent-dispatch.js

@@ -16,6 +16,7 @@
 import fs from "node:fs";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
 /**
@@ -60,10 +61,13 @@ async function resolveAssetBody(ref) {
 export async function akmAgentDispatch(options) {
     if (!options.agentConfig)
         throw new UsageError("agent requires a valid config with an agent engine.", "MISSING_REQUIRED_ARGUMENT");
-    const engineName = options.engine ?? options.agentConfig.defaults?.engine;
+    // Same implicit opencode-sdk fallback the workflow and task surfaces apply,
+    // so an engine-less install is usable everywhere or nowhere — not a mix.
+    const { config: agentConfig } = withEngineFallback(options.agentConfig);
+    const engineName = options.engine ?? agentConfig.defaults?.engine;
     if (!engineName)
-        throw new UsageError("agent requires --engine or defaults.engine.", "MISSING_REQUIRED_ARGUMENT");
-    const runner = resolveEngine(engineName, options.agentConfig);
+        throw new UsageError(`agent ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "MISSING_REQUIRED_ARGUMENT");
+    const runner = resolveEngine(engineName, agentConfig);
     if (runner.kind === "llm") {
         throw new UsageError(`Engine "${engineName}" is an LLM engine; akm agent requires an agent engine.`, "INVALID_FLAG_VALUE");
     }

package/dist/commands/health/checks.js

@@ -2,8 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
 import { loadConfig } from "../../core/config/config.js";
+import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { resolveModel } from "../../integrations/agent/model-aliases.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
@@ -28,7 +28,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     if (configuredEngine?.kind === "agent" && configuredEngine.platform === "opencode-sdk") {
         let packageAvailable = false;
         try {
-            const resolvePackage = deps.resolvePackage ?? ((name) => createRequire(import.meta.url).resolve(name));
+            const resolvePackage = deps.resolvePackage ?? ((name) => import.meta.resolve(name));
             resolvePackage("@opencode-ai/sdk");
             packageAvailable = true;
         }
@@ -170,7 +170,10 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     }
 }
 export function runDefaultEngineProbe(deps = {}) {
-    const config = deps.loadConfig?.() ?? loadConfig();
+    // Probe the effective view: an install with no `defaults.engine` but a usable
+    // opencode binary DOES have a working default, and reporting otherwise would
+    // contradict what `workflow run` / `task run` actually do.
+    const { config } = withEngineFallback(deps.loadConfig?.() ?? loadConfig(), deps.which);
     return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
 }
 export function runDefaultLlmEngineProbe(deps = {}) {

package/dist/commands/improve/reflect.js

@@ -37,6 +37,7 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { lookup } from "../../indexer/indexer.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
 import { materializeLlmRunnerConnection, resolveImproveProcessRunner, runnerIsLlm, runnerSupportsFileWrite, } from "../../integrations/agent/runner.js";
@@ -1185,11 +1186,12 @@ function resolveReflectRunner(options) {
         runnerSpec = processRunner;
     }
     else {
-        const defaultEngine = config.defaults?.engine;
+        const { config: engineConfig } = withEngineFallback(config);
+        const defaultEngine = engineConfig.defaults?.engine;
         if (!defaultEngine) {
-            throw new ConfigError("reflect requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
+            throw new ConfigError(`reflect ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
         }
-        runnerSpec = resolveEngine(defaultEngine, config);
+        runnerSpec = resolveEngine(defaultEngine, engineConfig);
     }
     if (options.eventSource === "improve" && !runnerIsLlm(runnerSpec)) {
         throw new ConfigError(`Unattended improve requires an LLM engine for reflect; engine "${runnerSpec.engine ?? options.engine ?? "unknown"}" is tool-capable.`, "INVALID_CONFIG_FILE", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine to an LLM engine.");

package/dist/commands/proposal/propose.js

@@ -21,6 +21,7 @@ import { appendEvent } from "../../core/events.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { deriveEntryProvenance } from "../../indexer/installations.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
 import { collectDispatchSensitiveValues, executeRunner } from "../../integrations/agent/runner-dispatch.js";
@@ -83,10 +84,11 @@ export async function akmPropose(options) {
     const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
     const target = resolveProposalQueueTarget(stash, config);
     emitProposeInvoked(target.source, options);
-    const engineName = options.engine ?? config.defaults?.engine;
+    const { config: engineConfig } = withEngineFallback(config);
+    const engineName = options.engine ?? engineConfig.defaults?.engine;
     if (!engineName)
-        throw new ConfigError("propose requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
-    const runner = resolveEngine(engineName, config);
+        throw new ConfigError(`propose ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
+    const runner = resolveEngine(engineName, engineConfig);
     const profile = runner.kind === "llm" ? undefined : runner.profile;
     // 3. Build prompt.
     // Synthesize a temp draft path so opencode can write the asset content

package/dist/commands/sources/init.js

@@ -87,7 +87,7 @@ async function akmInitReal(options) {
     for (const sub of stashDirNames()) {
         const subDir = path.join(stashDir, sub);
         if (!fs.existsSync(subDir)) {
-            fs.mkdirSync(subDir, { recursive: true });
+            fs.mkdirSync(subDir, { recursive: true, mode: sub === "env" || sub === "secrets" ? 0o700 : undefined });
         }
     }
     // Ensure the default stash is a local git repo (no remote required)

package/dist/commands/tasks/tasks.js

@@ -19,6 +19,7 @@ import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../cor
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { parseTaskDocument } from "../../tasks/parser.js";
 import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
@@ -27,7 +28,6 @@ import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/sched
 import { schedulerContextDescriptor, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
 import { normaliseTaskId } from "../../tasks/task-id.js";
 import { validateTaskDocument } from "../../tasks/validator.js";
-import { isWorkflowEngineEnabled, WORKFLOW_ENGINE_CONFIG_KEY } from "../../workflows/exec/workflow-engine-gate.js";
 import { applyAutonomyGate, configuredDirectAutonomyLanes, describeGatedLanes } from "../improve/autonomy-gate.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 export async function akmTasksAdd(input, deps = {}) {
@@ -392,7 +392,9 @@ export async function akmTasksDoctor(deps = {}) {
         }
     }
     const bindings = groupInstalledBindings(installed, invocation);
-    const config = loadConfig();
+    // Report the EFFECTIVE engine view — the same one the runner resolves —
+    // so doctor never says "no engine" on an install where tasks actually run.
+    const { config } = withEngineFallback(loadConfig());
     const defaultEngine = config.defaults?.engine;
     const engines = Object.keys(config.engines ?? {});
     // §6.1: surface the effective triage settings for the default improve
@@ -413,12 +415,6 @@ export async function akmTasksDoctor(deps = {}) {
         configKey: IMPROVE_AUTONOMY_CONFIG_KEY,
         gatedLanes: allGated.map((entry) => ({ lane: entry.lane, reason: entry.reason })),
     };
-    // Q-05 — report the external-driver gate alongside the autonomy gate: both
-    // are `experimental.*` opt-ins doctor exists to surface.
-    const workflowEngine = {
-        enabled: isWorkflowEngineEnabled(config),
-        configKey: WORKFLOW_ENGINE_CONFIG_KEY,
-    };
     const triage = effectiveStrategy.processes?.triage;
     const improveTriage = triage
         ? {
@@ -442,7 +438,6 @@ export async function akmTasksDoctor(deps = {}) {
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
         improveAutonomy,
-        workflowEngine,
         ...(improveTriage ? { improveTriage } : {}),
     };
 }

package/dist/commands/workflow-cli.js

@@ -4,18 +4,15 @@
 /**
  * `akm workflow` command family. `run` is the canonical start/resume/execute
  * surface; the former public `start`, `next`, and `complete` lifecycle is gone.
- * `brief`/`report` retain the experimental harness-neutral driver protocol.
  * Workflows are markdown-only; authoring uses `create --print` and validation
  * uses `akm lint --type workflows`.
  */
 import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
-import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
-import { requireWorkflowEngineEnabled } from "../workflows/exec/workflow-engine-gate.js";
 import { WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
 import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStatusCommand = defineJsonCommand({
@@ -283,150 +280,6 @@ function parseWorkflowTimeout(raw) {
     }
     return timeoutMs;
 }
-const workflowBriefCommand = defineJsonCommand({
-    meta: {
-        name: "brief",
-        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: describe a run's active step as an executable " +
-            "work-list for ANY agent session (the harness-neutral driver protocol) — read-only, takes no engine lease, " +
-            "mutates nothing; prints per-unit instructions, output schema, env binding names, and the exact " +
-            "`akm workflow report` command lines",
-    },
-    args: {
-        target: {
-            type: "positional",
-            description: "Workflow run id (or a workflow ref with an active run)",
-            required: true,
-        },
-    },
-    async run({ args }) {
-        requireWorkflowEngineEnabled(loadConfig(), "brief");
-        const { buildWorkflowBrief } = await import("../workflows/exec/brief.js");
-        const result = await buildWorkflowBrief(args.target);
-        output("workflow-brief", result);
-    },
-});
-const WORKFLOW_REPORT_STATES = ["completed", "failed", "running"];
-const workflowReportCommand = defineJsonCommand({
-    meta: {
-        name: "report",
-        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: report a unit's result back into a run (the " +
-            "mutating half of the harness-neutral driver protocol) — ingested through the SAME shared step semantics " +
-            "the engine uses. --status running claims/" +
-            "heartbeats a unit; completed/failed records it and, when the step's work-list is fully terminal, runs the " +
-            "engine's completion path (reducer, artifact + schema validation, gate). --settle (no --unit) advances a run " +
-            "parked on a route-only/empty step. Refused while a live engine lease exists",
-    },
-    args: {
-        target: {
-            type: "positional",
-            description: "Workflow run id (or a workflow ref with an active run)",
-            required: true,
-        },
-        unit: {
-            type: "string",
-            description: "Content-derived unit id from `akm workflow brief` (copy it verbatim). Omit with --settle.",
-        },
-        settle: {
-            type: "boolean",
-            description: "Advance/finalize a run whose active step has NO unit left to report: a non-dispatching step (params-based route, empty fan-out, all-unresolvable) OR a fully-terminal step still needing finalization (every unit ran but the gate never judged — e.g. after resuming a required-gate block). Runs the deterministic completion path. Mutually exclusive with --unit; refused when the step still has genuinely pending units",
-            default: false,
-        },
-        "expect-step": {
-            type: "string",
-            description: "Guard: the step id you briefed against. Refuses the report if the run's active step has since moved (from the `brief` report/settle command line)",
-        },
-        status: { type: "string", description: `Unit status: ${WORKFLOW_REPORT_STATES.join(", ")}` },
-        result: { type: "string", description: "Result payload (JSON for a schema unit, else text). completed only." },
-        "result-file": { type: "string", description: "Read the result payload from this file instead of --result/stdin" },
-        tokens: { type: "string", description: "Tokens spent on this unit (counts against a declared budget)" },
-        "session-id": { type: "string", description: "Harness-native session id revealed while executing the unit" },
-        "failure-reason": { type: "string", description: "Structured failure vocabulary for a --status failed report" },
-        note: { type: "string", description: "Short progress note for a --status running heartbeat (not persisted)" },
-        rerun: {
-            type: "boolean",
-            description: "Re-run an already-FAILED unit: record a NEW attempt (re-applies budget) instead of refusing a differing re-report",
-            default: false,
-        },
-    },
-    async run({ args }) {
-        requireWorkflowEngineEnabled(loadConfig(), "report");
-        // --settle: the unit-less verb that advances a run parked on a
-        // non-dispatching step. Mutually exclusive with the per-unit report flags.
-        if (args.settle === true) {
-            if (getStringArg(args, "unit") !== undefined || getStringArg(args, "status") !== undefined) {
-                throw new UsageError("--settle advances a route-only/empty step and takes no --unit or --status. Drop them, or report a " +
-                    "specific unit with `--unit <id> --status <state>` instead.", "INVALID_FLAG_VALUE");
-            }
-            const { settleWorkflowSpine } = await import("../workflows/exec/report.js");
-            const result = await settleWorkflowSpine({
-                target: args.target,
-                ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
-            });
-            output("workflow-report", result);
-            return;
-        }
-        const status = args.status;
-        if (!status) {
-            throw new UsageError("--status is required (completed | failed | running), or pass --settle to advance a non-dispatching step.", "MISSING_REQUIRED_ARGUMENT");
-        }
-        if (!WORKFLOW_REPORT_STATES.includes(status)) {
-            throw new UsageError(`Invalid --status "${status}". Expected one of: ${WORKFLOW_REPORT_STATES.join(", ")}.`, "INVALID_FLAG_VALUE");
-        }
-        const unitId = getStringArg(args, "unit");
-        if (!unitId) {
-            throw new UsageError("--unit is required (the content-derived unit id from `akm workflow brief`), or pass --settle for a route-only/empty step.", "MISSING_REQUIRED_ARGUMENT");
-        }
-        let tokens;
-        const rawTokens = getStringArg(args, "tokens");
-        if (rawTokens !== undefined) {
-            tokens = Number.parseInt(rawTokens, 10);
-            if (!/^\d+$/.test(rawTokens)) {
-                throw new UsageError(`--tokens must be a non-negative integer, got "${rawTokens}".`, "INVALID_FLAG_VALUE");
-            }
-        }
-        // Result payload precedence: --result, then --result-file, then stdin
-        // (completed/failed only; a running heartbeat carries no result).
-        let resultRaw;
-        if (status !== "running") {
-            const resultFile = getStringArg(args, "result-file");
-            if (args.result !== undefined && resultFile !== undefined) {
-                throw new UsageError("Pass at most one of --result or --result-file.", "INVALID_FLAG_VALUE");
-            }
-            if (args.result !== undefined) {
-                resultRaw = String(args.result);
-            }
-            else if (resultFile !== undefined) {
-                const fs = await import("node:fs");
-                resultRaw = fs.readFileSync(resultFile, "utf8");
-            }
-            else if (!process.stdin.isTTY) {
-                resultRaw = await readStdin();
-            }
-        }
-        const { reportWorkflowUnit } = await import("../workflows/exec/report.js");
-        const result = await reportWorkflowUnit({
-            target: args.target,
-            unitId,
-            status: status,
-            ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
-            ...(resultRaw !== undefined ? { resultRaw } : {}),
-            ...(tokens !== undefined ? { tokens } : {}),
-            ...(args.rerun === true ? { rerun: true } : {}),
-            ...(getStringArg(args, "session-id") !== undefined ? { sessionId: getStringArg(args, "session-id") } : {}),
-            ...(getStringArg(args, "failure-reason") !== undefined
-                ? { failureReason: getStringArg(args, "failure-reason") }
-                : {}),
-            ...(getStringArg(args, "note") !== undefined ? { note: getStringArg(args, "note") } : {}),
-        });
-        output("workflow-report", result);
-    },
-});
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
-    return Buffer.concat(chunks).toString("utf8");
-}
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
         name: "abandon",
@@ -465,8 +318,6 @@ export const workflowCommand = defineGroupCommand({
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
         run: workflowRunCommand,
-        brief: workflowBriefCommand,
-        report: workflowReportCommand,
     },
     // No `defaultRun`: bare `akm workflow` is a usage error (exit 2), the
     // canonical bare-group behavior — owner ruling 12. Run `akm workflow list

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

@@ -26,14 +26,5 @@ export const ExperimentalConfigSchema = z
      * purpose, and it has its own `sync.push: false` / `--no-push` controls.
      */
     improveAutonomy: z.boolean().optional(),
-    /**
-     * Allow the harness-neutral workflow external-driver protocol (Q-05).
-     *
-     * OFF by default. Gates only `akm workflow brief`/`report`. Stable native
-     * orchestration through `workflow run`, authoring/linting, inspection, and
-     * recovery remain available regardless of this key. A gated driver call
-     * refuses outright rather than degrading.
-     */
-    workflowEngine: z.boolean().optional(),
 })
     .passthrough();

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

@@ -19,8 +19,6 @@ import { engineName, positiveInt } from "./primitives.js";
  *     `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]` (64). Values above the ceiling
  *     are clamped, not rejected, so a config shared across machines with wildly
  *     different core counts never hard-fails validation.
- * The R3 brief/report driver surface does NOT consult this — drivers own their
- * own parallelism (the engine only caps native dispatch).
  */
 export const WorkflowConfigSchema = z
     .object({

package/dist/core/errors.js

@@ -15,7 +15,6 @@ const CONFIG_HINTS = {
     SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_BUNDLE_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
-    WORKFLOW_ENGINE_NOT_ENABLED: "Run `akm config set experimental.workflowEngine true` to enable it.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {

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

@@ -0,0 +1,76 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { defaultWhich } from "./detect.js";
+import { OPENCODE_SDK_SERVER_BIN } from "./profiles.js";
+/**
+ * Engine name used for the synthesized entry. Matches the platform id so it
+ * reads correctly in `akm workflow status`, frozen plans, and error messages.
+ * A user-configured engine of the same name is preferred over synthesizing.
+ */
+export const FALLBACK_ENGINE_NAME = "opencode-sdk";
+/** Announcement text, surfaced once per run/dispatch. */
+export const FALLBACK_ANNOUNCEMENT = `No engine is configured; falling back to \`${FALLBACK_ENGINE_NAME}\` via the ` +
+    `\`${OPENCODE_SDK_SERVER_BIN}\` binary on PATH — provider, model, and auth come ` +
+    "from opencode's own configuration. " +
+    "Run `akm setup`, or set `defaults.engine`, to choose explicitly.";
+/**
+ * Failure suffix for every surface that needs an engine and found none.
+ * Owned HERE, beside the probe whose outcome it describes: the probe follows a
+ * configured `bin` when one is pinned, so a consumer restating "not on PATH"
+ * would misdescribe a missing absolute path.
+ */
+export const NO_ENGINE_MESSAGE_SUFFIX = `has no selected engine, and no usable \`${OPENCODE_SDK_SERVER_BIN}\` binary was found to fall back to.`;
+/**
+ * Guidance used when the fallback itself is unavailable.
+ *
+ * The opencode route names a BINARY install, not `npm i @opencode-ai/sdk`:
+ * that package is an HTTP client with no dependencies and cannot serve
+ * anything on its own (see the module doc).
+ */
+export const NO_ENGINE_REMEDY = "Run `akm setup` to detect an installed agent, or set one explicitly: " +
+    '`akm config set engines.claude \'{"kind":"agent","platform":"claude"}\'` ' +
+    "then `akm config set defaults.engine claude`. " +
+    `Installing the \`${OPENCODE_SDK_SERVER_BIN}\` binary also works ` +
+    "(`npm i -g opencode-ai`) — akm falls back to it automatically.";
+/**
+ * Return a config whose `defaults.engine` resolves, applying the implicit
+ * `opencode-sdk` fallback when it does not and an opencode binary is present.
+ *
+ * Pure with respect to the input: never mutates `config`. Returns the input
+ * object identity unchanged when no fallback is needed, so callers can cheaply
+ * detect the common case.
+ */
+export function withEngineFallback(config, whichFn = defaultWhich) {
+    if (config.defaults?.engine)
+        return { config };
+    // An operator-configured engine of this name wins over a synthesized one —
+    // theirs may carry a model, an llmEngine fallback, or a pinned bin. Probe
+    // THAT bin rather than the bare command: a configured absolute path outside
+    // PATH is still a usable engine, and reporting it as missing would contradict
+    // the operator-configured-wins rule.
+    const existing = config.engines?.[FALLBACK_ENGINE_NAME];
+    if (!whichFn(existing?.bin ?? OPENCODE_SDK_SERVER_BIN))
+        return { config };
+    const engines = existing
+        ? config.engines
+        : { ...(config.engines ?? {}), [FALLBACK_ENGINE_NAME]: { kind: "agent", platform: "opencode-sdk" } };
+    return {
+        config: {
+            ...config,
+            engines,
+            defaults: { ...(config.defaults ?? {}), engine: FALLBACK_ENGINE_NAME },
+        },
+        fallbackEngineName: FALLBACK_ENGINE_NAME,
+    };
+}
+/**
+ * The announcement, but only when the fallback candidate is the engine that
+ * actually won selection. Returns `undefined` otherwise, so an explicitly
+ * selected engine never triggers a claim that opencode supplied the model.
+ */
+export function fallbackAnnouncement(fallbackEngineName, selectedEngineName) {
+    if (!fallbackEngineName || selectedEngineName !== fallbackEngineName)
+        return undefined;
+    return FALLBACK_ANNOUNCEMENT;
+}

package/dist/integrations/agent/profiles.js

@@ -94,9 +94,13 @@ const BUILTINS = {
 /**
  * Binary the `opencode-sdk` harness needs on PATH.
  *
- * The embedded SDK is not self-contained: its runner spawns `opencode serve`
- * and talks HTTP to it (see `harnesses/opencode-sdk/sdk-runner.ts`), so the
- * `opencode` binary gates the SDK path exactly as it gates the CLI path.
+ * The embedded SDK is not self-contained, and that is the SDK's own design
+ * rather than a consequence of how akm drives it: `@opencode-ai/sdk` ships
+ * with `"dependencies": {}` and its `createOpencodeServer` is itself a
+ * `spawn("opencode", ["serve", ...])`. akm's runner spawns the same binary
+ * directly and talks HTTP to it (see `harnesses/opencode-sdk/sdk-runner.ts`),
+ * so the `opencode` binary gates the SDK path exactly as it gates the CLI
+ * path — a host with the npm package but no binary can dispatch neither.
  * `opencode-sdk` deliberately has no {@link BUILTINS} entry — it dispatches
  * without argv construction — so this is the one place that pairing lives.
  */

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

@@ -74,7 +74,12 @@
  * until the child ACTUALLY exits — and a real `opencode serve` (a live HTTP
  * server with provider children) can outlive SIGTERM long enough to hang the
  * caller indefinitely. {@link createManagedOpencode} therefore owns the spawn
- * (the SDK package is used only for `createOpencodeClient`):
+ * (the SDK package is used only for `createOpencodeClient`).
+ *
+ * Owning the spawn changes the LIFECYCLE, not the REQUIREMENT: the SDK's
+ * `createOpencodeServer` is itself a `spawn("opencode", ["serve", ...])`, and
+ * the package declares `"dependencies": {}`, so `opencode` must be on PATH
+ * either way. akm's version differs only in how it supervises the child:
  *
  *   - after the URL handshake, the child and its stdio are `unref()`ed /
  *     destroyed, so the handle can never hold akm open;

package/dist/output/shapes/passthrough.js

@@ -57,10 +57,8 @@ const PASSTHROUGH_COMMANDS = [
     "update",
     "upgrade",
     "workflow-abandon",
-    "workflow-brief",
     "workflow-create",
     "workflow-list",
-    "workflow-report",
     "workflow-resume",
     "workflow-run",
     "workflow-status",

package/dist/output/text/helpers.js

@@ -18,4 +18,4 @@
 export { formatAddPlain, formatBundleShowPlain, formatClonePlain, formatConfigPlain, formatCuratePlain, formatEnvCreatePlain, formatEnvExportPlain, formatEnvListPlain, formatEnvRemovePlain, formatEventLine, formatEventsPlain, formatFeedbackPlain, formatImportPlain, formatIndexPlain, formatInfoPlain, formatInitPlain, formatListPlain, formatRegistryAddPlain, formatRegistryListPlain, formatRegistryRemovePlain, formatRegistrySearchPlain, formatRememberPlain, formatRemovePlain, formatSearchPlain, formatSyncPlain, formatUpdatePlain, formatUpgradePlain, } from "./command-format.js";
 export { formatGateDecisionSummary, formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalDrainPlain, formatProposalListPlain, formatProposalProducerPlain, formatProposalRejectPlain, formatProposalShowPlain, } from "./proposal-format.js";
 export { formatShowPlain } from "./show-format.js";
-export { formatWorkflowBriefPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";
+export { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";