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

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

@@ -27,20 +27,12 @@ export const ExperimentalConfigSchema = z
      */
     improveAutonomy: z.boolean().optional(),
     /**
-     * Allow the `akm workflow` native engine to run (Q-05).
+     * Allow the harness-neutral workflow external-driver protocol (Q-05).
      *
-     * OFF by default. Gates `akm workflow run` (the native step-execution
-     * engine) and `akm workflow brief`/`report` (the harness-neutral driver
-     * protocol).
-     *
-     * Deliberately NOT gated: authoring/linting the unified markdown format
-     * and the manual workflow CLI contract (`start`/`next`/`complete`/
-     * `status`/`list`/`create`/`resume`/`abandon`) remain stable regardless of
-     * this key.
-     *
-     * Unlike `improveAutonomy`, a gated call here REFUSES outright rather than
-     * degrading: a workflow step either executes or it does not, so there is
-     * no safe partial-execution fallback to fall back to.
+     * 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(),
 })

package/dist/core/config/schema/sources-bundles.js

@@ -80,6 +80,17 @@ const BundleWebsiteDescriptorSchema = z
     refresh: z.string().min(1).optional(),
     maxPages: positiveInt.optional(),
     maxDepth: positiveInt.optional(),
+    // Default true: crawl-scoped robots.txt compliance (Disallow/Crawl-delay
+    // for the akm/akm-cli product tokens or "*"). See
+    // src/sources/snapshot-fetchers/robots.ts. Opt out with `false` to
+    // restore pre-P1 behavior exactly (no /robots.txt request at all).
+    respectRobots: z.boolean().optional(),
+    // Hard wall-clock cap on the whole crawl, in milliseconds. Defaults to
+    // 10 minutes. Unlike a between-page check, this aborts work already in
+    // flight — including a `Retry-After` sleep, which a server can otherwise
+    // make arbitrarily long. Set to 0 to disable the cap entirely for a
+    // deliberately long-running crawl.
+    crawlTimeoutMs: z.number().int().min(0).optional(),
 })
     .passthrough();
 /** One component of a bundle (spec §10.1). Single-entry, transitional. */

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

@@ -6,7 +6,7 @@
  * `config-schema.ts` monolith — no behavior change.
  */
 import { z } from "zod";
-import { positiveInt } from "./primitives.js";
+import { engineName, positiveInt } from "./primitives.js";
 // ── Workflow engine ─────────────────────────────────────────────────────────
 /**
  * Workflow-engine settings (`workflow`).
@@ -25,5 +25,7 @@ import { positiveInt } from "./primitives.js";
 export const WorkflowConfigSchema = z
     .object({
     maxConcurrency: positiveInt.optional(),
+    /** Named LLM or agent engine frozen into every criteria-bearing gate. */
+    judgeEngine: engineName.optional(),
 })
     .passthrough();

package/dist/core/errors.js

@@ -29,12 +29,17 @@ const USAGE_HINTS = {
     TARGET_NOT_UPDATABLE: "Run `akm bundle list` to view your sources, then retry with one of those values.",
     MISSING_REQUIRED_ARGUMENT: "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.",
     UNKNOWN_COMMAND: "Run `akm --help` to see available commands.",
+    UNKNOWN_FLAG: "Run the command with `--help` to see its accepted flags.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {
     ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
     SOURCE_NOT_FOUND: "Run `akm bundle list` to view your sources, then retry with one of those values.",
     WORKFLOW_NOT_FOUND: "Run `akm workflow list --active` to see runs.",
+    // A proposal is addressed by id or ref, never by path — reusing
+    // FILE_NOT_FOUND here handed users "check the path exists and is readable"
+    // for a mistyped id, which points at the wrong thing entirely.
+    PROPOSAL_NOT_FOUND: "Run `akm proposal list` to see pending proposals and their ids.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
 };
 /**

package/dist/core/logs-db.js

@@ -38,7 +38,7 @@
  * @module logs-db
  */
 import path from "node:path";
-import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { assertMigrationRegistry, runMigrations as runSqliteMigrations, } from "../storage/engines/sqlite-migrations.js";
 import { openManagedDatabase } from "../storage/managed-db.js";
 import { getDataDir } from "./paths.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
@@ -130,6 +130,7 @@ const MIGRATIONS = [
     `,
     },
 ];
+assertMigrationRegistry(MIGRATIONS);
 /**
  * Apply every pending migration. Called automatically by
  * {@link openLogsDatabase}; exported for the same test seams state-db exposes.

package/dist/core/parse.js

@@ -23,7 +23,10 @@
  * models). Also strips leading/trailing whitespace.
  */
 export function stripThinkBlocks(raw) {
-    return raw.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+    return raw
+        .replace(/<think>[\s\S]*?<\/think>/gi, "")
+        .replace(/^[\s\S]*?<\/think>/i, "")
+        .trim();
 }
 /**
  * Strips markdown code fences (``` or ~~~, with optional language tag).

package/dist/core/state/migrations.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { runMigrations as runSqliteMigrations } from "../../storage/engines/sqlite-migrations.js";
+import { assertMigrationRegistry, runMigrations as runSqliteMigrations, } from "../../storage/engines/sqlite-migrations.js";
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
     {
@@ -59,7 +59,7 @@ export const STATE_MIGRATIONS = [
       --   id          TEXT PK     — UUID (crypto.randomUUID()); stable directory name.
       --   stash_dir   TEXT        — absolute stash root; multi-stash installs need
       --                             this to partition proposal lists per stash.
-      --   ref         TEXT        — target asset ref (e.g. "lesson:alpha");
+      --   ref         TEXT        — target asset ref (e.g. "lessons/alpha");
       --                             indexed for ref-scoped queue views.
       --   status      TEXT        — "pending" | "accepted" | "rejected"; indexed
       --                             so pending-queue queries are fast.
@@ -76,7 +76,7 @@ export const STATE_MIGRATIONS = [
       --   metadata_json TEXT      — JSON object for future proposal fields.
       --                             Current fields stored here: sourceRun,
       --                             review, confidence, gateDecision (#577),
-      --                             backupContent, eligibilitySource.
+      --                             backupContent.
       --
       -- ADD COLUMN extension points (future migrations):
       --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
@@ -353,9 +353,9 @@ export const STATE_MIGRATIONS = [
     // (`scripts/akm-migrate/migrate/legacy/proposal-fs-import.ts`, wired through
     // `akm-migrate apply`),
     // whose idempotency is INSERT OR IGNORE on the proposal UUID plus migrate-apply's
-    // own journal — it no longer reads or writes this ledger. The CREATE TABLE
-    // stays because the migration registry is APPEND-ONLY and checksum-sealed:
-    // removing a released fragment would make the schema_migrations ledger of an
+    // incomplete sentinel — it no longer reads or writes this ledger. The CREATE TABLE
+    // stays because migration IDs are append-only: removing a released migration
+    // would make the schema_migrations ledger of an
     // already-migrated rc database stop being an exact ordered prefix, and the
     // runner would refuse to open it. The empty table is harmless.
     //
@@ -833,12 +833,11 @@ export const STATE_MIGRATIONS = [
     //
     // The state.db half of the three-DB merge (plan §3.2/§8, normative §11.4,
     // chunk-8 cutover design §1). This migration is PURE,
-    // SEALABLE, IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
+    // IDEMPOTENT DDL ONLY — `CREATE TABLE IF NOT EXISTS` (+ indexes),
     // never a DROP or a data move. The actual data movement (the workflow.db merge,
     // the usage_events rescue from index.db, the full old-ref→item_ref re-key, and
-    // the workflow.db delete / index.db quarantine) is CODE — a journaled step of
-    // the migrate-apply flow (`scripts/akm-migrate/config-migrate.ts`
-    // `cutover-applied` phase), driven by
+    // the workflow.db delete / index.db quarantine) is idempotent migrate-apply
+    // code driven by
     // `scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`. See the no-DROP
     // contract carve-out note in `src/core/state-db.ts`.
     //
@@ -985,6 +984,7 @@ export const STATE_MIGRATIONS = [
     `,
     },
 ];
+assertMigrationRegistry(STATE_MIGRATIONS);
 /**
  * Apply every pending migration in a single transaction per migration.
  *
@@ -994,8 +994,5 @@ export const STATE_MIGRATIONS = [
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db, options) {
-    runSqliteMigrations(db, STATE_MIGRATIONS, {
-        applyPending: options?.applyPending,
-        generationMarker: options?.generationMarker,
-    });
+    runSqliteMigrations(db, STATE_MIGRATIONS, { applyPending: options?.applyPending });
 }

package/dist/core/state-db.js

@@ -45,12 +45,10 @@
  * merge-target tables at their final shape. The one-time, filesystem-derived,
  * fail-closed DATA movement (the workflow.db merge, the usage_events rescue, the
  * full old-ref→item_ref re-key, and the workflow.db unlink / index.db quarantine
- * rename) is deliberately NOT a sealed SQL migration body: it is a journaled step
- * of the migrate-apply coordinator (`scripts/akm-migrate/config-migrate.ts`
- * `cutover-applied` phase →
- * `scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`). So the no-DROP
- * contract here is intact — the physical workflow.db deletion happens outside
- * the ledger DDL, under the backup-verified-restorable fail-closed gate.
+ * rename) runs as idempotent code in the migrate-apply coordinator
+ * (`scripts/akm-migrate/migrate/legacy/three-db-cutover.ts`). So the no-DROP
+ * contract here is intact: physical workflow.db deletion happens outside the
+ * ledger DDL, after a verified backup and committed data transaction.
  *
  * ## Schema design: indexed columns vs. metadata_json
  *

package/dist/core/subprocess.js

@@ -148,6 +148,7 @@ export async function readStream(stream, opts) {
     }
 }
 const EMPTY_READ = { text: "", timedOut: false };
+const UNBOUNDED_STREAM_READ_SAFETY_MS = 60 * 60 * 1000;
 function toError(err) {
     return err instanceof Error ? err : new Error(String(err));
 }
@@ -238,10 +239,11 @@ export async function runManagedSubprocess(cmd, opts) {
         else
             abortSignal.addEventListener("abort", onAbort, { once: true });
     }
-    // Stream-drain timeout: the wall budget plus a 2 s grace, or 30 s when there
-    // is no kill timer. Ensures the caller never hangs past the budget even if a
-    // killed child leaves a pipe write-end open in a background thread.
-    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
+    // Stream-drain timeout: the wall budget plus a 2 s grace, or a one-hour
+    // safety bound when execution itself is unbounded. This timer starts with
+    // capture, so the null-timeout path must not impose a short hidden deadline
+    // on an otherwise healthy long-running process.
+    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : UNBOUNDED_STREAM_READ_SAFETY_MS;
     const stdoutPromise = capture
         ? readStream(proc.stdout ?? null, {
             timeoutMs: streamDrainTimeoutMs,

package/dist/core/type-presentation.js

@@ -38,7 +38,7 @@ function shellQuote(value) {
 }
 /** Reproduced from `output/renderers.ts#buildWorkflowAction` — the one function-valued `ACTION_BUILDERS.workflow` entry. */
 function buildWorkflowAction(ref) {
-    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+    return `Start or resume execution with \`akm workflow run ${shellQuote(ref)}\`.`;
 }
 /**
  * Exhaustive over {@link KnownType} — a HAND-WRITTEN literal, not derived

package/dist/indexer/indexer.js

@@ -419,12 +419,27 @@ async function akmIndexReal(options) {
         // Load config and resolve all stash sources
         const { loadConfig, mutateConfig } = await import("../core/config/config.js");
         let config = loadConfig();
+        // Durable state must be runtime-compatible before source hydration,
+        // adapter persistence, or index.db creation can mutate the installation.
+        onProgress({ phase: "preflight", message: "Validating durable state." });
+        withStateDb(() => undefined);
         // Ensure git stash caches are extracted before resolving stash dirs,
         // so their content directories exist on disk for the walker to discover.
         const sourceCacheStart = Date.now();
         onProgress({ phase: "preflight", message: "Hydrating source caches." });
         const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
-        await ensureSourceCaches(config, { force: full, materialize: options.hydrateSources !== false });
+        // Inject the store-backed secret resolver from here — a composition root
+        // ABOVE the provider/fetcher import cycle (this module reaches
+        // search-source only via dynamic import). This is what lets a website
+        // source's X fetcher resolve `secrets/x-bearer-token` during
+        // bundle-update / hydrate, not just from the command-layer URL-ingest
+        // path. `secret-seam` is imported here, never from inside the cycle.
+        const { storeSecretResolver } = await import("../sources/snapshot-fetchers/secret-seam.js");
+        await ensureSourceCaches(config, {
+            force: full,
+            materialize: options.hydrateSources !== false,
+            secrets: storeSecretResolver,
+        });
         const sourceCacheEnd = Date.now();
         const allSourceEntries = resolveSourceEntries(stashDir, config);
         const detected = detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig, {

package/dist/indexer/search/search-source.js

@@ -304,7 +304,7 @@ export async function ensureSourceCaches(config, options) {
             continue;
         }
         try {
-            await provider.sync({ force });
+            await provider.sync({ force, secrets: options?.secrets });
         }
         catch (err) {
             warn(`Warning: failed to refresh ${provider.kind} source "${provider.name}": ${err instanceof Error ? err.message : String(err)}`);

package/dist/indexer/walk/matchers.js

@@ -188,7 +188,9 @@ function classifyBySmartMd(ctx) {
         return { type: "workflow", specificity: 19 };
     }
     if (fm) {
-        if ("toolPolicy" in fm || "tools" in fm) {
+        // `tools` is the one authoring key for an agent's tool grant. Recognition
+        // covers only the key the renderer honors.
+        if ("tools" in fm) {
             return { type: "agent", specificity: 20 };
         }
         if ("agent" in fm) {

package/dist/integrations/agent/config.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/** Default hard timeout for an agent CLI when neither engine nor call overrides it. */
-export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
+/** Default agent CLI timeout; null means agents run until they finish. */
+export const DEFAULT_AGENT_TIMEOUT_MS = null;
 /** Default hard timeout for direct LLM calls when no engine/use override exists. */
 export const DEFAULT_LLM_TIMEOUT_MS = 600_000;

package/dist/integrations/agent/detect.js

@@ -15,26 +15,34 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getBuiltinAgentProfile, listBuiltinAgentProfiles } from "./profiles.js";
+import { getBuiltinAgentProfile, listBuiltinAgentProfiles, OPENCODE_SDK_SERVER_BIN, } from "./profiles.js";
 /**
  * Default PATH lookup. Walks `process.env.PATH` and returns the first
  * existing executable file. Returns `undefined` when the bin is not on
  * PATH or the env is empty.
  *
- * `process.env.PATH` is split on the platform-correct delimiter; on
- * Windows the binary may have an executable extension, but for v1 we
- * keep this Unix-flavoured (Bun's primary target) and look for an exact
- * match.
+ * `process.env.PATH` is split on the platform-correct delimiter. On Windows
+ * agent CLIs install as extension-bearing shims (`claude.cmd`, `q.exe`), so
+ * each PATH entry is probed for the bare name AND for `<bin><ext>` over
+ * PATHEXT — an exact-match-only probe reports every agent CLI as missing
+ * there, which silently hides the "installed CLI agent" option during setup.
  */
 export function defaultWhich(bin, envSource = process.env) {
+    // Computed once per call — not per PATH entry — since it never varies.
+    const suffixes = executableSuffixes(envSource);
     if (!bin || bin.includes("/") || bin.includes("\\")) {
         // Absolute / relative paths: caller already specified location.
-        try {
-            return fs.statSync(bin).isFile() ? bin : undefined;
-        }
-        catch {
-            return undefined;
+        for (const suffix of suffixes) {
+            const candidate = bin + suffix;
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                /* try the next extension */
+            }
         }
+        return undefined;
     }
     const pathVar = envSource.PATH ?? envSource.Path ?? envSource.path ?? "";
     if (!pathVar)
@@ -43,18 +51,40 @@ export function defaultWhich(bin, envSource = process.env) {
     for (const dir of pathVar.split(sep)) {
         if (!dir)
             continue;
-        const candidate = path.join(dir, bin);
-        try {
-            const st = fs.statSync(candidate);
-            if (st.isFile())
-                return candidate;
-        }
-        catch {
-            /* keep walking */
+        const base = path.join(dir, bin);
+        for (const suffix of suffixes) {
+            const candidate = base + suffix;
+            try {
+                const st = fs.statSync(candidate);
+                if (st.isFile())
+                    return candidate;
+            }
+            catch {
+                /* keep walking */
+            }
         }
     }
     return undefined;
 }
+/** Windows PATHEXT default, used when the env carries no explicit list. */
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/**
+ * Executable suffixes to try for each candidate path, bare name (`""`) first
+ * so POSIX resolution is byte-for-byte unchanged. Extensions are appended only
+ * on win32 or when the env supplies PATHEXT (which is also the seam tests use
+ * to cover Windows resolution from a POSIX runner).
+ */
+function executableSuffixes(envSource) {
+    const pathext = envSource.PATHEXT ?? envSource.Pathext ?? envSource.pathext;
+    if (process.platform !== "win32" && !pathext)
+        return [""];
+    const exts = (pathext ?? DEFAULT_PATHEXT)
+        .split(";")
+        .map((ext) => ext.trim())
+        .filter(Boolean)
+        .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
+    return ["", ...exts];
+}
 let detectOverrides;
 /** TEST-ONLY. Swap the detection implementations; pass undefined to restore. */
 export function _setAgentDetectForTests(fakes) {
@@ -79,7 +109,7 @@ export function detectAgentCliProfiles(agent, whichFn = defaultWhich) {
         profilesByName.set(name, {
             name,
             platform: engine.platform,
-            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? "opencode" : engine.platform),
+            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? OPENCODE_SDK_SERVER_BIN : engine.platform),
             args: engine.args ?? builtin?.args ?? [],
             stdio: "captured",
             envPassthrough: builtin?.envPassthrough ?? [],

package/dist/integrations/agent/profiles.js

@@ -91,6 +91,16 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
+/**
+ * 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.
+ * `opencode-sdk` deliberately has no {@link BUILTINS} entry — it dispatches
+ * without argv construction — so this is the one place that pairing lives.
+ */
+export const OPENCODE_SDK_SERVER_BIN = "opencode";
 /** Names of the canonical built-in harness descriptors. Stable, sorted. */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
 /** Returns the built-in descriptor for a canonical harness id. */

package/dist/integrations/agent/spawn.js

@@ -21,7 +21,6 @@ import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { runManagedSubprocess, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
 /**
  * Supplement `existingPath` with well-known user binary directories when
  * running in a scheduler context (cron/launchd) where PATH is stripped.
@@ -144,7 +143,7 @@ function streamFailureMessage(profileName, stdout, stderr) {
 export async function runAgent(profile, prompt, options = {}) {
     const stdioMode = options.stdio ?? profile.stdio;
     // null = explicitly disabled (no kill timer). undefined = runtime default.
-    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_AGENT_TIMEOUT_MS;
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;

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

@@ -4,9 +4,13 @@
 /**
  * OpenCode SDK agent runner (migrated from `agent/sdk-runner.ts`, #564).
  *
- * Uses the embedded `@opencode-ai/sdk` instead of `Bun.spawn`. Requires no
- * agent CLI binary to be installed. The user provides an OpenAI-compatible
- * endpoint (or inherits from the selected fallback LLM engine) for the SDK.
+ * Uses the embedded `@opencode-ai/sdk` instead of `Bun.spawn` for dispatch, so
+ * no agent CLI argv is ever constructed — but the SDK is not self-contained:
+ * {@link createManagedOpencode} spawns `opencode serve` and talks HTTP to it,
+ * so the `opencode` binary must be on PATH (which is why setup's
+ * `detectHarness` gates this harness on that probe). The user provides an
+ * OpenAI-compatible endpoint (or inherits from the selected fallback LLM
+ * engine) for the SDK.
  *
  * This is the runtime surface of the {@link OpencodeSdkHarness} (`id =
  * 'opencode-sdk'`). It is the dispatch path for SDK runner specs; it exposes

package/dist/integrations/lockfile.js

@@ -169,9 +169,7 @@ export async function upsertLockEntry(entry) {
  * migrate-apply's config lock + maintenance barrier) whose synchronous body
  * cannot await the sentinel's retry loop. No-op for an empty list.
  */
-export function mergeLockEntriesSync(entries) {
-    if (entries.length === 0)
-        return;
+function readLockEntriesForMigration() {
     let existing = [];
     const lockfilePath = getLockfilePath();
     if (fs.existsSync(lockfilePath)) {
@@ -187,6 +185,16 @@ export function mergeLockEntriesSync(entries) {
         }
         existing = raw;
     }
+    return existing;
+}
+/** Validate the current lockfile before migrate-apply creates its backup or sentinel. */
+export function assertMigrationLockfileReadable() {
+    readLockEntriesForMigration();
+}
+export function mergeLockEntriesSync(entries) {
+    const existing = readLockEntriesForMigration();
+    if (entries.length === 0)
+        return;
     // MERGE per id, never replace: the migrator's entries are sparse (id/source/
     // ref/localRoot), while an existing row may carry `resolvedVersion`,
     // `resolvedRevision`, `integrity`, `installedAt`, … from a real install.
@@ -202,59 +210,6 @@ export function mergeLockEntriesSync(entries) {
     const incomingIds = new Set(entries.map((e) => e.id));
     writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
 }
-/** Freeze exact old/desired lockfile bytes while the migration lifecycle lock is held. */
-export function planLockMergeSync(entries) {
-    const lockfilePath = getLockfilePath();
-    let oldBytes = null;
-    let existing = [];
-    try {
-        oldBytes = fs.readFileSync(lockfilePath, "utf8");
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
-    if (oldBytes !== null) {
-        let parsed;
-        try {
-            parsed = JSON.parse(oldBytes);
-        }
-        catch (error) {
-            throw new ConfigError(`Cannot plan migration lock entries from unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
-        }
-        if (!Array.isArray(parsed) || !parsed.every(isValidLockfileEntry)) {
-            throw new ConfigError(`Cannot plan migration lock entries from malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
-        }
-        existing = parsed;
-    }
-    if (entries.length === 0)
-        return { oldBytes, desiredBytes: oldBytes };
-    const byId = new Map(existing.map((entry) => [entry.id, entry]));
-    for (const entry of entries)
-        byId.set(entry.id, { ...byId.get(entry.id), ...entry });
-    return { oldBytes, desiredBytes: `${JSON.stringify([...byId.values()], null, 2)}\n` };
-}
-/** Publish a frozen migration lock generation, accepting only exact old or exact desired bytes. */
-export function publishPlannedLockMergeSync(plan) {
-    const lockfilePath = getLockfilePath();
-    let current = null;
-    try {
-        current = fs.readFileSync(lockfilePath, "utf8");
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
-    if (current === plan.desiredBytes)
-        return;
-    if (current !== plan.oldBytes) {
-        throw new ConfigError(`Refusing migration lockfile publication because ${lockfilePath} is a third generation, neither the journaled old nor desired bytes.`, "INVALID_CONFIG_FILE");
-    }
-    if (plan.desiredBytes === null)
-        return;
-    fs.mkdirSync(path.dirname(lockfilePath), { recursive: true });
-    writeFileAtomic(lockfilePath, plan.desiredBytes, 0o600);
-}
 export async function removeLockEntry(id) {
     if (!fs.existsSync(getDataDir()))
         return;

package/dist/output/shapes/passthrough.js

@@ -58,15 +58,11 @@ const PASSTHROUGH_COMMANDS = [
     "upgrade",
     "workflow-abandon",
     "workflow-brief",
-    "workflow-complete",
-    "workflow-complete-rejected",
     "workflow-create",
     "workflow-list",
-    "workflow-next",
     "workflow-report",
     "workflow-resume",
     "workflow-run",
-    "workflow-start",
     "workflow-status",
 ];
 export const passthroughShapes = PASSTHROUGH_COMMANDS.map((command) => ({

package/dist/output/text/command-format.js

@@ -289,12 +289,12 @@ export function formatSearchPlain(r, detail) {
             if (hasWorkflowHit) {
                 const workflowRef = hits.find((h) => h.type === "workflow");
                 const wfRef = workflowRef && typeof workflowRef.ref === "string" ? workflowRef.ref : topRef;
-                lines.push(`Next: akm show '${topRef}'  |  To start a workflow: akm workflow next '${wfRef}'`);
-                lines.push("After running workflow next: follow each step and run `akm workflow complete <run-id> --step <step-id>` when done.");
+                lines.push(`Next: akm show '${topRef}'  |  To execute a workflow: akm workflow run '${wfRef}'`);
+                lines.push("Inspect the workflow before running it; `workflow run` executes and verifies its steps automatically.");
             }
             else {
                 lines.push(`Next: akm show '${topRef}'`);
-                lines.push("After reading the asset: check whether a workflow applies before editing — if so, use `akm workflow next` instead.");
+                lines.push("After reading the asset: check whether a workflow applies before editing — if so, inspect it and use `akm workflow run`.");
             }
         }
     }

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, formatWorkflowCompleteRejectedPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowNextPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";
+export { formatWorkflowBriefPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./workflow-format.js";

package/dist/output/text/show-directives.js

@@ -45,9 +45,7 @@ export function appendShowDirectives(lines, r) {
     if (assetType === "skill" || assetType === "knowledge") {
         const activeRun = r.activeRun;
         if (activeRun) {
-            // Active workflow: redirect agent to workflow commands instead of direct apply
-            lines.unshift(`  akm workflow complete '${activeRun.runId}'${activeRun.stepId ? ` --step '${activeRun.stepId}'` : ""}`);
-            lines.unshift("Read this schema, then follow your workflow step's instructions to edit the workspace file. When done, mark the step complete:");
+            lines.unshift("Read this reference, follow the active unit's instructions, and return the result to the workflow runner. Step completion is automatic.");
             lines.unshift(`WORKFLOW ACTIVE — schema shown as reference (run: ${activeRun.runId})`);
             lines.unshift("---");
             lines.unshift("");
@@ -88,14 +86,14 @@ export function appendShowDirectives(lines, r) {
         const insertIdx = separatorIdx >= 0 ? separatorIdx + 1 : r.type || r.name ? 1 : 0;
         const actionDirective = [
             `ACTION REQUIRED: Do not execute steps manually from this output.`,
-            `Run \`akm workflow next '${workflowRef}'\` to get your current step with exact instructions.`,
+            `Run \`akm workflow run '${workflowRef}'\` to execute the workflow through its declared gates.`,
             "---",
         ];
         lines.splice(insertIdx, 0, "", ...actionDirective);
         lines.push("");
         lines.push("---");
-        lines.push(`NEXT STEP: Run \`akm workflow next '${workflowRef}'\` to see the current workflow step.`);
-        lines.push("Do not edit workspace files before completing each step with `akm workflow complete`.");
+        lines.push(`NEXT STEP: Run \`akm workflow run '${workflowRef}'\` to execute the workflow.`);
+        lines.push("Inspect the workflow first; the runner dispatches and completes each step automatically.");
     }
 }
 /**