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

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

@@ -52,8 +52,10 @@
  */
 import path from "node:path";
 import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
+import { taskFieldProblems } from "../../../tasks/schema.js";
 import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
 import { parseWorkflow } from "../../../workflows/parser.js";
+import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
 /** Recommended `category` values for facts — `commands/lint/fact-linter.ts:9`. */
 const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
 /** Placeholder markers a workflow stub carries — `commands/lint/workflow-linter.ts:10`. */
@@ -152,8 +154,12 @@ function collectSuppressedKeys(raw) {
 /**
  * env/secret dangerous-key scan (`lint/index.ts:191-218` + `env-key-rules.ts#checkEnvForDangerousKeys`),
  * keyed on `type` and preserving the `.env`-suffix narrowness (see file header).
- * Reads the overlay `raw`, not disk. `type`==="env" ⇒ ref prefix `env:`;
- * `type`==="secret" ⇒ `secret:` (`lint/index.ts:201-204`).
+ * Reads the overlay `raw`, not disk.
+ *
+ * The emitted `Ref:` comes from `conceptIdForStashFile` — the one place that
+ * spells a diagnostic ref the way `akm show` accepts it. It used to be
+ * hand-built as `env:<base>` / `secret:<base>`, a colon grammar the 0.9.0 ref
+ * parser rejects outright — a dead-end ref on a *security* finding.
  */
 export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     if (type !== "env" && type !== "secret")
@@ -161,9 +167,8 @@ export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     const baseNameWithExt = path.basename(relPath);
     if (!baseNameWithExt.endsWith(".env"))
         return []; // NARROWNESS: collectEnvFiles only visits *.env
-    const refPrefix = type === "env" ? "env" : "secret";
-    const baseName = path.basename(relPath, ".env");
-    const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+    // `relPath` is already stash-root-relative, so "." IS the stash root here.
+    const ref = conceptIdForStashFile(type, ".", relPath);
     const keys = scanKeys(raw);
     const suppressed = collectSuppressedKeys(raw);
     const diagnostics = [];
@@ -259,17 +264,16 @@ export function factDiagnostics(relPath, data) {
     }
     return [];
 }
-/** TaskLinter extra check (`task-linter.ts:25-58`). `data` is the parsed YAML. */
+/**
+ * TaskLinter extra check (`task-linter.ts:25-58`). `data` is the parsed YAML.
+ * Field rules come from the shared {@link taskFieldProblems} (see its doc for
+ * the lint-vs-parser reconciliation story); this sweep additionally requires
+ * at least one target.
+ */
 export function taskDiagnostics(relPath, data) {
     if (data === null || Object.keys(data).length === 0)
         return [];
-    const missing = [];
-    if (!("schedule" in data) || typeof data.schedule !== "string" || data.schedule.trim() === "") {
-        missing.push("schedule");
-    }
-    if (!("enabled" in data) || typeof data.enabled !== "boolean") {
-        missing.push("enabled (must be a boolean)");
-    }
+    const missing = taskFieldProblems(data);
     const hasTarget = "prompt" in data || "workflow" in data || "command" in data;
     if (!hasTarget)
         missing.push("prompt, workflow, or command");

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

@@ -12,11 +12,13 @@
  *
  * ── validate (spec §6 task validation column) ──
  *
- * A task must declare a `schedule`, an `enabled` boolean, and EXACTLY ONE
- * target (`prompt` XOR `workflow` XOR `command`). The akm adapter's
- * `TaskLinter` port checks "at least one" target; the native task family here is
- * STRICTER — declaring two targets is `invalid-task-yaml`. So this adapter owns
- * a purpose-built one-target check rather than reusing that port.
+ * A task must declare `version: 2`, a `schedule`, and EXACTLY ONE target
+ * (`prompt` XOR `workflow` XOR `command`). `enabled` is OPTIONAL — the parser
+ * defaults it to `true`, so an omitted field means an ACTIVE task — but must
+ * be a boolean when present. The akm adapter's `TaskLinter` port checks
+ * "at least one" target; the native task family here is STRICTER — declaring
+ * two targets is `invalid-task-yaml`. So this adapter owns a purpose-built
+ * one-target check rather than reusing that port.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -25,6 +27,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { taskFieldProblems } from "../../../tasks/schema.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
@@ -68,15 +71,15 @@ function parseTaskYaml(raw) {
     }
     return {};
 }
-/** The native `invalid-task-yaml` check: schedule + enabled(boolean) + EXACTLY ONE target. */
+/**
+ * The native `invalid-task-yaml` check: the shared field rules
+ * ({@link taskFieldProblems} — see its doc for the lint-vs-parser
+ * reconciliation story) plus this adapter's stricter EXACTLY-ONE-target rule.
+ */
 function taskDiagnostics(relPath, data) {
     if (Object.keys(data).length === 0)
         return [];
-    const problems = [];
-    if (typeof data.schedule !== "string" || data.schedule.trim() === "")
-        problems.push("schedule");
-    if (typeof data.enabled !== "boolean")
-        problems.push("enabled (must be a boolean)");
+    const problems = taskFieldProblems(data);
     const targets = TARGET_KEYS.filter((k) => k in data && data[k] !== undefined && data[k] !== null);
     if (targets.length === 0)
         problems.push("exactly one target (prompt, workflow, or command)");

package/dist/core/asset/akm-markdown.js

@@ -2,14 +2,36 @@
 // 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 { parse as parseYaml } from "yaml";
+import { localDateStamp } from "../common.js";
 import { UsageError } from "../errors.js";
 import { serializeFrontmatter } from "./asset-serialize.js";
-import { parseFrontmatterBlock } from "./frontmatter.js";
-/** Ensure an AKM-authored Markdown concept is also a conformant OKF concept. */
-export function ensureAkmMarkdownType(content, type) {
+import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
+/**
+ * Ensure an AKM-authored Markdown concept is also a conformant OKF concept.
+ *
+ * Stamps BOTH `type` and `updated`, because both are required of a conformant
+ * document and this is the one chokepoint every `.md` write passes through
+ * (`core/write-source.ts`). Without the `updated` stamp, every asset akm
+ * created for you — `akm remember`, `akm import`, accepted proposals,
+ * authored workflows — was immediately flagged `missing-updated` by akm's own
+ * `akm lint`, so the tool disagreed with itself about its own output.
+ *
+ * An existing `updated` is left alone: this fills a gap, it does not
+ * re-stamp on every write (which would churn timestamps and manufacture
+ * needless diffs in git-backed bundles).
+ *
+ * Source preservation: when the type already matches and the ONLY change is
+ * adding `updated`, the line is spliced into the original block textually —
+ * round-tripping through the YAML serializer would drop user-authored
+ * comments and normalize formatting just to contribute one field. Only a
+ * document whose `type` must actually be corrected takes the re-serialize
+ * path (as it always has).
+ */
+export function ensureAkmMarkdownType(content, type, now = new Date()) {
     const block = parseFrontmatterBlock(content);
-    if (!block)
-        return `---\ntype: ${type}\n---\n${content}`;
+    if (!block) {
+        return `---\n${serializeFrontmatter({ type, updated: localDateStamp(now) })}\n---\n${content}`;
+    }
     let parsed;
     try {
         parsed = block.frontmatter.trim() ? parseYaml(block.frontmatter) : {};
@@ -23,8 +45,19 @@ export function ensureAkmMarkdownType(content, type) {
         throw new UsageError("AKM Markdown frontmatter must be a YAML mapping.", "INVALID_FLAG_VALUE");
     }
     const data = parsed;
-    if (data.type === type)
-        return content;
+    const needsUpdated = !("updated" in data);
+    if (data.type === type) {
+        if (!needsUpdated)
+            return content;
+        const spliced = spliceFrontmatterLine(content, `updated: ${localDateStamp(now)}`);
+        if (spliced !== null)
+            return spliced;
+        // Unreachable in practice (parseFrontmatterBlock succeeded above), but a
+        // re-serialized document beats a non-conformant one.
+    }
     const { type: _priorType, ...rest } = data;
-    return `---\n${serializeFrontmatter({ type, ...rest })}\n---\n${block.content}`;
+    const next = { type, ...rest };
+    if (needsUpdated)
+        next.updated = localDateStamp(now);
+    return `---\n${serializeFrontmatter(next)}\n---\n${block.content}`;
 }

package/dist/core/asset/frontmatter.js

@@ -176,6 +176,28 @@ function countLines(text) {
         return 0;
     return text.split(/\r?\n/).length - 1;
 }
+/**
+ * Insert one `key: value` line just before the closing `---` of an existing
+ * frontmatter block, leaving every other byte — YAML comments, quoting, key
+ * order, line endings — untouched. Returns null when `raw` has no well-formed
+ * block, so callers can fall back to a parse-and-serialize path.
+ *
+ * This is the source-preserving way to ADD a field to user-authored
+ * frontmatter: round-tripping the mapping through the YAML serializer drops
+ * comments and normalizes formatting, which is unacceptable for a write that
+ * only needs to contribute one line. Shared by `ensureAkmMarkdownType`
+ * (stamping `updated:` on write) and lint's `--fix` for `missing-updated`.
+ */
+export function spliceFrontmatterLine(raw, line) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    lines.splice(closeIdx, 0, line);
+    return lines.join("\n");
+}
 /**
  * Parse a YAML scalar value (string, boolean, or number).
  *

package/dist/core/asset/resolve-ref.js

@@ -34,7 +34,7 @@
  * grammar to bridge any more.
  */
 import { NotFoundError, UsageError } from "../errors.js";
-import { placementSpecFor, stashDirFor, typeForStashDir } from "./asset-placement.js";
+import { deriveCanonicalAssetNameFromStashRoot, placementSpecFor, stashDirFor, typeForStashDir, } from "./asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "./asset-ref.js";
 /**
  * Resolve a maybe-short input ref to a fully-qualified {@link ResolvedRef}
@@ -97,6 +97,19 @@ export function conceptIdFromTypeName(type, name) {
     const stashDir = stashDirFor(type);
     return stashDir !== undefined ? `${stashDir}/${name}` : name;
 }
+/**
+ * User-facing conceptId for a file on disk, derived through the placement
+ * spec's canonical-name rule — the ONE way a diagnostic should spell a ref it
+ * expects the user to paste into `akm show`. (The dangerous-env-key lint used
+ * to hand-build `env:<base>` colon refs the parser rejects; both its emission
+ * sites now route through here.) For a type with no placement spec — which no
+ * built-in caller passes — falls back to the raw name so the output is still
+ * informative rather than empty.
+ */
+export function conceptIdForStashFile(type, stashRoot, filePath) {
+    const name = deriveCanonicalAssetNameFromStashRoot(type, stashRoot, filePath);
+    return name === undefined ? filePath : conceptIdFromTypeName(type, name);
+}
 /**
  * Build the USER-FACING / envelope ref string for an indexed item, applying the
  * Chunk-5 flip F4b output-spelling rule (orchestrator decision; ref-grammar
@@ -116,8 +129,15 @@ export function conceptIdFromTypeName(type, name) {
  *     derived slug bundle id, never the retired `origin//type:name` spelling.
  */
 export function displayRef(item, defaultBundleId) {
-    const conceptId = item.conceptId ?? conceptIdFromTypeName(item.type, item.name);
-    const { bundleId } = item;
+    return displayRefForConceptId(item.conceptId ?? conceptIdFromTypeName(item.type, item.name), item.bundleId, defaultBundleId);
+}
+/**
+ * The F4b output-spelling flip itself, for a caller that already holds the
+ * conceptId (no `type`/`name` derivation needed — e.g. lint findings built
+ * from {@link conceptIdForStashFile}). {@link displayRef} delegates here, so
+ * the short-default / qualified-secondary rule still has exactly one home.
+ */
+export function displayRefForConceptId(conceptId, bundleId, defaultBundleId) {
     // Default/primary bundle → SHORT conceptId (the flip).
     if (bundleId === undefined || bundleId === defaultBundleId)
         return conceptId;

package/dist/core/common.js

@@ -409,7 +409,7 @@ export async function fetchWithRetry(url, init, options) {
             if (attempt < maxRetries && shouldRetry(response.status)) {
                 const retryAfter = parseRetryAfter(response);
                 const delay = retryAfter ?? baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-                await new Promise((r) => setTimeout(r, delay));
+                await abortableDelay(delay, init?.signal);
                 continue;
             }
             return response;
@@ -417,12 +417,41 @@ export async function fetchWithRetry(url, init, options) {
         catch (err) {
             if (attempt >= maxRetries)
                 throw err;
+            // A caller-supplied abort is terminal: never keep retrying past it.
+            if (init?.signal?.aborted)
+                throw err;
             const delay = baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-            await new Promise((r) => setTimeout(r, delay));
+            await abortableDelay(delay, init?.signal);
         }
     }
     throw new Error("fetchWithRetry: unreachable");
 }
+/**
+ * Sleep, but wake immediately if `signal` aborts.
+ *
+ * A server-supplied `Retry-After` is honored verbatim and can be arbitrarily
+ * large. Sleeping it out with a bare `setTimeout` ignored the caller's abort
+ * signal entirely, so a single `429` could park an operation far past any
+ * deadline its caller believed it had imposed — the request timeout bounds
+ * only the request, never the wait between attempts.
+ */
+function abortableDelay(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("Aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("Aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 function shouldRetry(status) {
     return status === 429 || status >= 500;
 }
@@ -628,6 +657,20 @@ export function toErrorMessage(error) {
 export function todayIso() {
     return new Date().toISOString().slice(0, 10);
 }
+/**
+ * `YYYY-MM-DD` in LOCAL time — deliberately not {@link todayIso}, which is
+ * UTC and can differ near midnight. This is the spelling the `updated:`
+ * frontmatter stampers share (`core/asset/akm-markdown.ts` on write,
+ * `commands/lint/base-linter.ts` on `--fix`), so the field's format has one
+ * definition even though the two stampers pick different instants (now vs
+ * file mtime).
+ */
+export function localDateStamp(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
 /**
  * Return a filesystem-safe timestamp string derived from the current instant.
  * Colons and dots are replaced with hyphens so the result is safe as a

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

@@ -234,6 +234,14 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
             message: "llmEngine must name an LLM engine",
         });
     }
+    const workflowJudge = config.workflow?.judgeEngine;
+    if (workflowJudge && !config.engines?.[workflowJudge]) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["workflow", "judgeEngine"],
+            message: "judgeEngine does not name a configured engine",
+        });
+    }
     const defaultStrategy = config.defaults?.improveStrategy;
     if (defaultStrategy &&
         !BUILTIN_IMPROVE_STRATEGY_NAMES.includes(defaultStrategy) &&

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

@@ -26,22 +26,5 @@ export const ExperimentalConfigSchema = z
      * purpose, and it has its own `sync.push: false` / `--no-push` controls.
      */
     improveAutonomy: z.boolean().optional(),
-    /**
-     * Allow the `akm workflow` native engine to run (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.
-     */
-    workflowEngine: z.boolean().optional(),
 })
     .passthrough();

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`).
@@ -19,11 +19,11 @@ import { 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({
     maxConcurrency: positiveInt.optional(),
+    /** Named LLM or agent engine frozen into every criteria-bearing gate. */
+    judgeEngine: engineName.optional(),
 })
     .passthrough();

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 = {
@@ -29,12 +28,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)}`);