akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -8,6 +8,7 @@
  */
 import { z } from "zod";
 import { isBundleSlug } from "../../asset/asset-ref.js";
+import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../../registry-url.js";
 import { httpUrl, nonEmptyString, positiveInt } from "./primitives.js";
 // ── Sources / registries / installed ────────────────────────────────────────
 const SourceConfigEntryOptionsSchema = z.record(z.unknown());
@@ -49,7 +50,11 @@ export const SourceConfigEntrySchema = z
 });
 export const RegistryConfigEntrySchema = z
     .object({
-    url: httpUrl,
+    url: httpUrl.superRefine((value, ctx) => {
+        if (hasRegistryUrlCredentials(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: REGISTRY_CREDENTIALS_UNSUPPORTED });
+        }
+    }),
     name: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
     provider: z.string().min(1).optional(),
@@ -58,9 +63,8 @@ export const RegistryConfigEntrySchema = z
     .passthrough();
 // ── Bundles (0.9.0 config-shape cutover, spec §10.1 / D-R5) ─────────────────
 //
-// `bundles` + `defaultBundle` are the 0.9.0 desired-configuration shape that
-// supersedes the pre-cutover `stashDir` / `sources[]` / `installed[]` trio. Each
-// bundle entry carries ONE source descriptor (`path` | `git` | `website` | `npm`
+// `bundles` + `defaultBundle` are the desired-configuration shape. Each bundle
+// entry carries ONE source descriptor (`path` | `git` | `website` | `npm`
 // — mirroring today's source types), an optional `writable`, an optional
 // `registryId` locator (the original registry install id, preserved verbatim so
 // a non-slug-legal id like `github:owner/repo` is not lost when its slug-legal
@@ -69,10 +73,7 @@ export const RegistryConfigEntrySchema = z
 // machinery). The map KEY is the workspace bundle slug (spec §11.1 charset: no
 // `/`, `:`, `.`, `#`, whitespace), validated with {@link isBundleSlug}.
 //
-// The config migrator ({@link migrateConfigSourcesToBundles}) emits these keyed
-// by exactly what `deriveInstallations` derives today (D-R5). `bindings` (spec
-// §10.1) is Tier B and is NEVER accepted here (the top-level superRefine rejects
-// it) — it is not part of the 0.9.0 config-shape cutover.
+// `bindings` is not accepted here; the top-level schema rejects it.
 /** Website source descriptor for a bundle entry (spec §10.1). */
 const BundleWebsiteDescriptorSchema = z
     .object({
@@ -110,15 +111,11 @@ export const BundleConfigEntrySchema = z
     npm: z.string().min(1).optional(),
     writable: z.boolean().optional(),
     // Opt a bundle out of indexing, search, refresh, and write targeting
-    // without deleting it. Carried over from the pre-cutover `sources[].enabled`
-    // flag, which the runtime still honors on the derived source entry
-    // (`write-source.ts`, `search-source.ts`); without it here, migrating a
-    // disabled source would silently reactivate it.
+    // without deleting it. The runtime honors the derived value in write and
+    // search source selection.
     enabled: z.boolean().optional(),
-    // The original registry install id when the bundle KEY was slug-derived from
-    // it (e.g. registryId `github:owner/repo` → key `repo`). Preserved so the
-    // source locator survives the config-shape migration (D-R5). Absent when the
-    // bundle key already equals the source's stable id.
+    // The registry install id when the bundle key was slug-derived from it
+    // (e.g. registryId `github:owner/repo` → key `repo`).
     registryId: z.string().min(1).optional(),
     components: z.record(z.string().min(1), BundleComponentConfigSchema).optional(),
 })

package/dist/core/errors.js

@@ -10,12 +10,14 @@ const CONFIG_HINTS = {
     STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
     DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
+    INDEX_SCHEMA_INCOMPATIBLE: "Run `akm index --full` to rebuild the derived index from the currently materialized sources.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
     LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
     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.",
+    EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {

package/dist/core/events.js

@@ -1,10 +1,34 @@
 // 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/.
+/**
+ * Append-only events stream — backed by state.db (#204, Phase 3).
+ *
+ * Every mutating CLI verb funnels through `appendEvent` so external
+ * observers (sync, replication, audit, dashboards) can react to stash
+ * changes. Events are stored in the `events` table in `state.db`
+ * (SQLite, WAL mode) instead of a flat `events.jsonl` file.
+ *
+ * The helper is the only thing in akm that writes to the events table. It
+ * accepts an injectable `dbPath` (via `EventsContext`) so tests can pin a
+ * tmpdir without any global mutation.
+ *
+ * Format (each EventEnvelope):
+ *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
+ *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
+ *
+ * - `id` is a monotonic SQLite AUTOINCREMENT rowid. Callers can persist it
+ *   as a durable cursor for `--since` resumption. The public API surfaces this
+ *   as the opaque `nextOffset` number.
+ * - `ts` is ISO-8601 (UTC, millisecond precision).
+ */
+import fs from "node:fs";
+import { openDatabase } from "../storage/database.js";
 import { insertEvent, readStateEvents } from "../storage/repositories/events-repository.js";
 import { rethrowIfTestIsolationError } from "./errors.js";
 import { getStateDbPath, openStateDatabase, withStateDb } from "./state-db.js";
 import { borrowScopedStateDb } from "./state-db-scope.js";
+import { isReadOnlyFilesystemError } from "./system-error.js";
 import { error } from "./warn.js";
 /**
  * Resolve the state.db path from context:
@@ -39,6 +63,8 @@ function resolveNow(ctx) {
  * connection.
  */
 export function appendEvent(input, ctx) {
+    if (ctx?.readOnly)
+        return;
     const now = resolveNow(ctx);
     const ts = new Date(now()).toISOString();
     const row = { eventType: input.eventType, ts, ref: input.ref, metadata: input.metadata };
@@ -68,31 +94,40 @@ export function appendEvent(input, ctx) {
     catch (err) {
         // Never mask the bun-test isolation guard as a silent "events failed".
         rethrowIfTestIsolationError(err);
+        // Read-only sandboxes can serve an existing index but cannot create the
+        // maintenance lock or state DB used by best-effort usage tracking. That is
+        // expected for a read verb; unrelated storage failures remain visible.
+        if (isReadOnlyFilesystemError(err))
+            return;
         // Best-effort: events stream failures must not break the mutating verb.
         // Surface once to stderr so operators can diagnose.
         error(`akm: appendEvent failed: ${String(err)}`);
     }
 }
-/**
- * 0.9.0 breaking change (owner ruling 12): `akm sync` used to persist
- * `eventType: "save"`; it now writes `"sync"` instead (matching the command
- * name). Existing `state.db` rows — and any user script running
- * `akm log --type save` — still carry the old spelling. Rather than
- * rewriting historical rows (a migration users never asked for, on data we
- * don't get to touch at rest), reads treat the two names as synonyms: asking
- * for either "save" or "sync" returns rows written under both names. Only
- * the WRITE path (sources-cli.ts's `runSyncBody`) changed.
- */
-const SAVE_SYNC_EVENT_TYPE_ALIASES = new Set(["save", "sync"]);
 /**
  * Read all events matching the filter. Returns a `nextOffset` that callers
  * can persist between processes for monotonic resumption.
  */
 export function readEvents(options = {}, ctx) {
+    if (ctx?.readOnlySnapshotUnavailable)
+        return { events: [], nextOffset: 0 };
     const dbPath = resolveDbPath(ctx);
     let db;
+    let ownsDb = false;
     try {
-        db = openStateDatabase(dbPath);
+        if (ctx?.db) {
+            db = ctx.db;
+        }
+        else if (ctx?.readOnly) {
+            if (!fs.existsSync(dbPath))
+                return { events: [], nextOffset: 0 };
+            db = openDatabase(dbPath, { readonly: true, create: false });
+            ownsDb = true;
+        }
+        else {
+            db = openStateDatabase(dbPath);
+            ownsDb = true;
+        }
     }
     catch (err) {
         // Never mask the bun-test isolation guard as "no events".
@@ -101,12 +136,7 @@ export function readEvents(options = {}, ctx) {
         return { events: [], nextOffset: 0 };
     }
     try {
-        // A "save"/"sync" query can't be expressed as a single SQL `event_type =
-        // ?` match (see SAVE_SYNC_EVENT_TYPE_ALIASES above), so widen the SQL
-        // filter to "no type filter" for that one case and apply the alias match
-        // client-side alongside the existing tag post-filter below.
-        const typeIsAliased = options.type !== undefined && SAVE_SYNC_EVENT_TYPE_ALIASES.has(options.type);
-        // D-38: a JS-side post-filter (the type alias above, or the tag filters
+        // D-38: a JS-side post-filter (the tag filters
         // below) runs AFTER the SQL read, so a SQL-level LIMIT applied before it
         // could drop rows the post-filter would have kept out anyway, silently
         // returning fewer than `limit` (or the wrong — oldest-in-the-SQL-window —
@@ -114,21 +144,26 @@ export function readEvents(options = {}, ctx) {
         // downstream can shrink the result further; otherwise read unbounded (the
         // pre-existing behavior) and apply `limit` ourselves, below, AFTER the
         // post-filter runs.
-        const needsPostFilter = typeIsAliased ||
-            (options.excludeTags?.length ?? 0) > 0 ||
-            (options.includeTags?.length ?? 0) > 0 ||
-            options.runId !== undefined;
+        const needsPostFilter = (options.excludeTags?.length ?? 0) > 0 || (options.includeTags?.length ?? 0) > 0 || options.runId !== undefined;
         const pushLimitToSql = options.limit !== undefined && !needsPostFilter;
-        const { events: rawEvents, nextId } = readStateEvents(db, {
-            sinceId: options.sinceOffset,
-            since: options.since,
-            type: typeIsAliased ? undefined : options.type,
-            ref: options.ref,
-            ...(pushLimitToSql ? { limit: options.limit } : {}),
-        });
+        let rawEvents;
+        let nextId;
+        try {
+            ({ events: rawEvents, nextId } = readStateEvents(db, {
+                sinceId: options.sinceOffset,
+                since: options.since,
+                type: options.type,
+                ref: options.ref,
+                ...(pushLimitToSql ? { limit: options.limit } : {}),
+            }));
+        }
+        catch (error) {
+            if (ctx?.readOnly && error instanceof Error && /no such table:/i.test(error.message)) {
+                return { events: [], nextOffset: options.sinceOffset ?? 0 };
+            }
+            throw error;
+        }
         const filtered = rawEvents.filter((envelope) => {
-            if (typeIsAliased && !SAVE_SYNC_EVENT_TYPE_ALIASES.has(envelope.eventType))
-                return false;
             if (options.runId !== undefined && envelope.metadata?.runId !== options.runId)
                 return false;
             // Apply tag filters after the indexed state.db read.
@@ -148,6 +183,7 @@ export function readEvents(options = {}, ctx) {
         return { events, nextOffset: nextId };
     }
     finally {
-        db.close();
+        if (ownsDb)
+            db.close();
     }
 }

package/dist/core/extra-params.js

@@ -10,6 +10,7 @@ export const EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS = [
     "stream",
     "streamoptions",
     "enablethinking",
+    "reasoningeffort",
     "chattemplatekwargs",
 ];
 export const EXTRA_PARAMS_CREDENTIAL_KEYS = [

package/dist/core/improve-result.js

@@ -1,17 +1,20 @@
 // 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 { cloneExecutionJsonObject } from "../execution/json.js";
 const COMMON_FIELDS = [
     "schemaVersion",
     "ok",
     "scope",
     "dryRun",
+    "notices",
     "skipped",
     "guidance",
     "memorySummary",
     "memoryCleanup",
     "cyclesRun",
     "plannedRefs",
+    "plan",
     "actions",
     "distillSkipped",
     "validationFailures",
@@ -55,6 +58,308 @@ function requireExactFields(value, allowed) {
     if (unknown.length > 0)
         fail(`unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.sort().join(", ")}`);
 }
+function requireNumber(value, field, path) {
+    if (typeof value[field] !== "number" || !Number.isFinite(value[field]))
+        fail(`${path}.${field} must be a number`);
+}
+function requireCount(value, field, path) {
+    requireNumber(value, field, path);
+    if (!Number.isSafeInteger(value[field]) || value[field] < 0) {
+        fail(`${path}.${field} must be a non-negative integer`);
+    }
+}
+function validateLoweringNotices(value) {
+    if (!Array.isArray(value))
+        fail("notices must be an array");
+    for (let index = 0; index < value.length; index += 1) {
+        const notice = value[index];
+        if (!isRecord(notice))
+            fail(`notices[${index}] must be an object`);
+        requireExactFields(notice, new Set(["code", "severity", "adapter", "field", "message", "details"]));
+        for (const field of ["code", "adapter", "message"]) {
+            if (typeof notice[field] !== "string")
+                fail(`notices[${index}].${field} must be a string`);
+        }
+        if (notice.severity !== "info" && notice.severity !== "warning") {
+            fail(`notices[${index}].severity is invalid`);
+        }
+        if (notice.field !== undefined && notice.field !== null && typeof notice.field !== "string") {
+            fail(`notices[${index}].field must be a string or null`);
+        }
+        if (notice.details !== undefined && notice.details !== null) {
+            try {
+                cloneExecutionJsonObject(notice.details, `notices[${index}].details`);
+            }
+            catch {
+                fail(`notices[${index}].details must be a JSON object or null`);
+            }
+        }
+    }
+}
+function validateConsolidationPlan(value) {
+    if (!isRecord(value))
+        fail("plan.consolidation must be an object");
+    requireExactFields(value, new Set([
+        "configured",
+        "effective",
+        "poolSize",
+        "candidatePoolSize",
+        "gates",
+        "wouldRun",
+        "reason",
+        "estimatedChunks",
+    ]));
+    if (!isRecord(value.configured))
+        fail("plan.consolidation.configured must be an object");
+    requireExactFields(value.configured, new Set(["enabled", "minPoolSize", "limit", "maxChunkSize", "incrementalSince"]));
+    if (value.configured.enabled !== undefined && typeof value.configured.enabled !== "boolean") {
+        fail("plan.consolidation.configured.enabled must be a boolean");
+    }
+    for (const field of ["minPoolSize", "limit", "maxChunkSize"]) {
+        if (value.configured[field] !== undefined && typeof value.configured[field] !== "number") {
+            fail(`plan.consolidation.configured.${field} must be a number`);
+        }
+    }
+    if (value.configured.incrementalSince !== undefined && typeof value.configured.incrementalSince !== "string") {
+        fail("plan.consolidation.configured.incrementalSince must be a string");
+    }
+    if (!isRecord(value.effective))
+        fail("plan.consolidation.effective must be an object");
+    requireExactFields(value.effective, new Set(["enabled", "minPoolSize", "limit", "chunkSize"]));
+    if (typeof value.effective.enabled !== "boolean")
+        fail("plan.consolidation.effective.enabled must be a boolean");
+    requireCount(value.effective, "minPoolSize", "plan.consolidation.effective");
+    requireCount(value.effective, "chunkSize", "plan.consolidation.effective");
+    if (value.effective.limit !== undefined && typeof value.effective.limit !== "number") {
+        fail("plan.consolidation.effective.limit must be a number");
+    }
+    requireCount(value, "poolSize", "plan.consolidation");
+    requireCount(value, "candidatePoolSize", "plan.consolidation");
+    requireCount(value, "estimatedChunks", "plan.consolidation");
+    if (typeof value.wouldRun !== "boolean")
+        fail("plan.consolidation.wouldRun must be a boolean");
+    if (typeof value.reason !== "string")
+        fail("plan.consolidation.reason must be a string");
+    if (!isRecord(value.gates))
+        fail("plan.consolidation.gates must be an object");
+    requireExactFields(value.gates, new Set(["profile", "minimumPool", "delta"]));
+    for (const gateName of ["profile", "minimumPool", "delta"]) {
+        const gate = value.gates[gateName];
+        if (!isRecord(gate))
+            fail(`plan.consolidation.gates.${gateName} must be an object`);
+        requireExactFields(gate, new Set(["passed", "reason"]));
+        if (typeof gate.passed !== "boolean" || typeof gate.reason !== "string") {
+            fail(`plan.consolidation.gates.${gateName} must contain boolean passed and string reason`);
+        }
+    }
+}
+function validateProactivePlan(value) {
+    if (!isRecord(value))
+        fail("plan.proactive must be an object");
+    requireExactFields(value, new Set(["configured", "effective", "candidatePool", "dueTotal", "neverReflected", "selected", "selectedRefs"]));
+    if (!isRecord(value.configured))
+        fail("plan.proactive.configured must be an object");
+    requireExactFields(value.configured, new Set(["dueDays", "maxPerRun", "limit"]));
+    for (const field of ["dueDays", "maxPerRun", "limit"]) {
+        if (value.configured[field] !== undefined && typeof value.configured[field] !== "number") {
+            fail(`plan.proactive.configured.${field} must be a number`);
+        }
+    }
+    if (!isRecord(value.effective))
+        fail("plan.proactive.effective must be an object");
+    requireExactFields(value.effective, new Set(["dueDays", "maxPerRun"]));
+    requireNumber(value.effective, "dueDays", "plan.proactive.effective");
+    requireNumber(value.effective, "maxPerRun", "plan.proactive.effective");
+    for (const field of ["candidatePool", "dueTotal", "neverReflected", "selected"]) {
+        requireCount(value, field, "plan.proactive");
+    }
+    if (!Array.isArray(value.selectedRefs) || value.selectedRefs.some((ref) => typeof ref !== "string")) {
+        fail("plan.proactive.selectedRefs must be an array of strings");
+    }
+    if (value.selected !== value.selectedRefs.length) {
+        fail("plan.proactive.selected must equal plan.proactive.selectedRefs.length");
+    }
+}
+function validateImprovePlan(value, dryRun, plannedRefNames) {
+    if (!isRecord(value))
+        fail("plan must be an object");
+    requireExactFields(value, new Set([
+        "mode",
+        "dispatch",
+        "snapshot",
+        "candidates",
+        "limits",
+        "gates",
+        "effectiveRefs",
+        "proactive",
+        "consolidation",
+        "stages",
+        "triage",
+    ]));
+    if (value.mode !== "estimate" && value.mode !== "execution")
+        fail('plan.mode must be "estimate" or "execution"');
+    if (typeof value.dispatch !== "boolean")
+        fail("plan.dispatch must be a boolean");
+    if ((value.mode === "estimate" && value.dispatch) || (value.mode === "execution" && !value.dispatch)) {
+        fail("plan.dispatch must be false for estimate mode and true for execution mode");
+    }
+    if (dryRun && (value.mode !== "estimate" || value.dispatch !== false)) {
+        fail("dryRun=true requires estimate mode with dispatch=false");
+    }
+    if (!dryRun && (value.mode !== "execution" || value.dispatch !== true)) {
+        fail("dryRun=false requires execution mode with dispatch=true");
+    }
+    if (!isRecord(value.snapshot))
+        fail("plan.snapshot must be an object");
+    requireExactFields(value.snapshot, new Set(["status", "reason"]));
+    if (typeof value.snapshot.status !== "string" ||
+        !new Set(["ready", "missing", "incompatible", "unknown"]).has(value.snapshot.status)) {
+        fail("plan.snapshot.status is invalid");
+    }
+    if (typeof value.snapshot.reason !== "string")
+        fail("plan.snapshot.reason must be a string");
+    if (!isRecord(value.candidates))
+        fail("plan.candidates must be an object");
+    requireExactFields(value.candidates, new Set(["rawInScope", "selected", "effective"]));
+    for (const field of ["rawInScope", "selected", "effective"]) {
+        requireCount(value.candidates, field, "plan.candidates");
+    }
+    if (value.candidates.rawInScope < value.candidates.selected) {
+        fail("plan.candidates.rawInScope cannot be less than plan.candidates.selected");
+    }
+    if (value.candidates.selected < value.candidates.effective) {
+        fail("plan.candidates.selected cannot be less than plan.candidates.effective");
+    }
+    if (!isRecord(value.limits))
+        fail("plan.limits must be an object");
+    requireExactFields(value.limits, new Set(["configured", "effective", "additiveReplayAllowance", "totalCeiling"]));
+    if (!isRecord(value.limits.configured))
+        fail("plan.limits.configured must be an object");
+    requireExactFields(value.limits.configured, new Set(["cli", "profile", "reflect"]));
+    for (const field of ["cli", "profile", "reflect"]) {
+        if (value.limits.configured[field] !== undefined)
+            requireCount(value.limits.configured, field, "plan.limits.configured");
+    }
+    if (value.limits.effective !== undefined)
+        requireCount(value.limits, "effective", "plan.limits");
+    requireCount(value.limits, "additiveReplayAllowance", "plan.limits");
+    if (value.limits.totalCeiling !== undefined)
+        requireCount(value.limits, "totalCeiling", "plan.limits");
+    if (value.limits.effective === undefined && value.limits.totalCeiling !== undefined) {
+        fail("plan.limits.totalCeiling must be omitted when plan.limits.effective is unbounded");
+    }
+    if (value.limits.effective !== undefined &&
+        value.limits.totalCeiling !== value.limits.effective + value.limits.additiveReplayAllowance) {
+        fail("plan.limits.totalCeiling must equal plan.limits.effective + plan.limits.additiveReplayAllowance");
+    }
+    const gateNames = new Set(["profile", "cleanup", "validation", "signal", "disk", "limit"]);
+    if (!Array.isArray(value.gates))
+        fail("plan.gates must be an array");
+    const gateRemovedByName = new Map();
+    for (const gate of value.gates) {
+        if (!isRecord(gate))
+            fail("plan.gates entries must be objects");
+        requireExactFields(gate, new Set(["name", "removed", "reason"]));
+        if (typeof gate.name !== "string" || !gateNames.has(gate.name))
+            fail("plan.gates.name is invalid");
+        requireCount(gate, "removed", "plan.gates entry");
+        if (typeof gate.reason !== "string")
+            fail("plan.gates.reason must be a string");
+        if (gateRemovedByName.has(gate.name))
+            fail(`plan.gates must contain exactly one ${gate.name} gate`);
+        gateRemovedByName.set(gate.name, gate.removed);
+    }
+    for (const gateName of gateNames) {
+        if (!gateRemovedByName.has(gateName))
+            fail(`plan.gates must contain exactly one ${gateName} gate`);
+    }
+    const preLimitRemoved = [...gateRemovedByName]
+        .filter(([gateName]) => gateName !== "limit")
+        .reduce((total, [, removed]) => total + removed, 0);
+    if (preLimitRemoved !== value.candidates.rawInScope - value.candidates.selected) {
+        fail("plan pre-limit gate removals must equal plan.candidates.rawInScope - plan.candidates.selected");
+    }
+    if (gateRemovedByName.get("limit") !==
+        value.candidates.selected - value.candidates.effective) {
+        fail("plan limit removal must equal plan.candidates.selected - plan.candidates.effective");
+    }
+    const lanes = new Set([
+        "scope",
+        "signal-delta",
+        "proactive",
+        "high-salience",
+        "distill-only",
+        "forgetting-safety",
+        "replay",
+        "unknown",
+    ]);
+    const reasons = new Set(["scope-ref", "scope-type", "memory-cleanup", "strategy_filtered_all_passes"]);
+    if (!Array.isArray(value.effectiveRefs))
+        fail("plan.effectiveRefs must be an array");
+    for (const entry of value.effectiveRefs) {
+        if (!isRecord(entry))
+            fail("plan.effectiveRefs entries must be objects");
+        requireExactFields(entry, new Set(["ref", "lane", "reason"]));
+        if (typeof entry.ref !== "string")
+            fail("plan.effectiveRefs.ref must be a string");
+        if (typeof entry.lane !== "string" || !lanes.has(entry.lane))
+            fail("plan.effectiveRefs.lane is invalid");
+        if (typeof entry.reason !== "string" || !reasons.has(entry.reason))
+            fail("plan.effectiveRefs.reason is invalid");
+    }
+    if (value.candidates.effective !== value.effectiveRefs.length) {
+        fail("plan.candidates.effective must equal plan.effectiveRefs.length");
+    }
+    const effectiveRefNames = value.effectiveRefs.map((entry) => entry.ref);
+    if (new Set(effectiveRefNames).size !== effectiveRefNames.length) {
+        fail("plan.effectiveRefs must not contain duplicate refs");
+    }
+    if (plannedRefNames.length !== effectiveRefNames.length ||
+        plannedRefNames.some((ref, index) => ref !== effectiveRefNames[index])) {
+        fail("plannedRefs must contain the same refs in the same order as plan.effectiveRefs");
+    }
+    const replayCount = value.effectiveRefs.filter((entry) => entry.lane === "replay").length;
+    const ordinaryCount = value.effectiveRefs.length - replayCount;
+    if (replayCount > value.limits.additiveReplayAllowance) {
+        fail("plan replay refs cannot exceed plan.limits.additiveReplayAllowance");
+    }
+    if (value.limits.effective !== undefined && ordinaryCount > value.limits.effective) {
+        fail("plan ordinary refs cannot exceed plan.limits.effective");
+    }
+    if (value.limits.totalCeiling !== undefined && value.effectiveRefs.length > value.limits.totalCeiling) {
+        fail("plan.effectiveRefs cannot exceed plan.limits.totalCeiling");
+    }
+    if (value.proactive !== undefined)
+        validateProactivePlan(value.proactive);
+    validateConsolidationPlan(value.consolidation);
+    const stageNames = new Set(["consolidation", "extract", "graph-extraction", "memory-inference"]);
+    if (!Array.isArray(value.stages))
+        fail("plan.stages must be an array");
+    for (const stage of value.stages) {
+        if (!isRecord(stage))
+            fail("plan.stages entries must be objects");
+        requireExactFields(stage, new Set(["name", "wouldRun", "reason"]));
+        if (typeof stage.name !== "string" || !stageNames.has(stage.name))
+            fail("plan.stages.name is invalid");
+        if (typeof stage.wouldRun !== "boolean" || typeof stage.reason !== "string") {
+            fail("plan.stages entries must contain boolean wouldRun and string reason");
+        }
+    }
+    if (!isRecord(value.triage))
+        fail("plan.triage must be an object");
+    requireExactFields(value.triage, new Set(["enabled", "configuredMode", "mode", "maxAcceptsPerRun", "maxDiffLines"]));
+    if (typeof value.triage.enabled !== "boolean")
+        fail("plan.triage.enabled must be a boolean");
+    for (const field of ["configuredMode", "mode"]) {
+        if (value.triage[field] !== "queue" && value.triage[field] !== "promote") {
+            fail(`plan.triage.${field} must be queue or promote`);
+        }
+    }
+    requireCount(value.triage, "maxAcceptsPerRun", "plan.triage");
+    if (value.triage.maxDiffLines !== undefined && typeof value.triage.maxDiffLines !== "number") {
+        fail("plan.triage.maxDiffLines must be a number");
+    }
+}
 function validateCommon(value) {
     if (typeof value.ok !== "boolean")
         fail("ok must be a boolean");
@@ -62,6 +367,15 @@ function validateCommon(value) {
         fail("dryRun must be a boolean");
     if (!Array.isArray(value.plannedRefs))
         fail("plannedRefs must be an array");
+    if (value.notices !== undefined)
+        validateLoweringNotices(value.notices);
+    const plannedRefNames = value.plannedRefs.map((entry, index) => {
+        if (!isRecord(entry) || typeof entry.ref !== "string")
+            fail(`plannedRefs[${index}].ref must be a string`);
+        return entry.ref;
+    });
+    if (value.plan !== undefined)
+        validateImprovePlan(value.plan, value.dryRun, plannedRefNames);
     if (!isRecord(value.scope))
         fail("scope must be an object");
     requireExactFields(value.scope, new Set(["mode", "value"]));
@@ -127,6 +441,7 @@ function validateCommon(value) {
         "cycleMetrics",
         "sync",
         "terminated",
+        "plan",
     ]) {
         if (value[field] !== undefined && !isRecord(value[field]))
             fail(`${field} must be an object`);

package/dist/core/lesson-lint.js

@@ -20,7 +20,6 @@
  * lets it run from any code path (CLI, proposal-accept, asset-spec tests)
  * without dragging in the rest of the runtime.
  */
-import fs from "node:fs";
 import { parseFrontmatter } from "./asset/frontmatter.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
@@ -66,8 +65,3 @@ export function lintLessonContent(raw, pathForMessages) {
     }
     return { path: pathForMessages, findings };
 }
-/** Lint a lesson file on disk. Throws if the file cannot be read. */
-export function lintLessonFile(filePath) {
-    const raw = fs.readFileSync(filePath, "utf8");
-    return lintLessonContent(raw, filePath);
-}

package/dist/core/maintenance-barrier.js

@@ -10,9 +10,9 @@ import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquire
 import { getMaintenanceBarrierPath } from "./paths.js";
 const heldBarrierContext = new AsyncLocalStorage();
 /**
- * Serialize restore with the short critical section that creates every
- * long-lived AKM lock or workflow lease. The long operation keeps its own
- * lock/lease; this barrier is released immediately after acquisition.
+ * Serialize the short critical section that creates each long-lived AKM lock,
+ * lease, or state activity. The operation keeps its own ownership record; this
+ * barrier is released immediately after acquisition.
  */
 export function tryAcquireMaintenanceBarrier() {
     const lockPath = getMaintenanceBarrierPath();
@@ -107,7 +107,7 @@ function withMaintenanceStartBarrierSyncWait(run) {
         release();
     }
 }
-/** Register a long-lived operation atomically with restore's blocker scan. */
+/** Register a long-lived state operation atomically with other start acquisitions. */
 export async function acquireMaintenanceActivity(name) {
     return withMaintenanceStartBarrierAsync(async () => {
         const directory = path.join(path.dirname(getMaintenanceBarrierPath()), "maintenance-activities");