akm-cli 0.9.11 → 0.9.13

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

@@ -7,6 +7,7 @@
  * change.
  */
 import { z } from "zod";
+import { warnOnce } from "../../warn.js";
 import { engineName, LlmInvocationOverridesSchema, nonEmptyString, positiveInt } from "./primitives.js";
 // ── Index / per-pass ────────────────────────────────────────────────────────
 //
@@ -53,26 +54,23 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
         return raw; // let z.object below produce the type error
     }
     const obj = raw;
+    let cleaned;
     for (const key of Object.keys(obj)) {
+        const dotted = [...(ctx.path ?? []), key].join(".");
         if (INDEX_PASS_RETIRED_KEYS.has(key)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `Retired or misplaced engine setting: \`${[...(ctx.path ?? []), key].join(".")}\` is not allowed. ` +
-                    "Select a named engine and use typed invocation fields instead.",
-            });
-            return raw;
+            warnOnce(`index-pass:retired:${dotted}`, `\`${dotted}\` is a retired engine setting and is ignored; select a named engine and use typed invocation fields instead.`);
+            cleaned ??= { ...obj };
+            delete cleaned[key];
         }
-        if (!INDEX_PASS_KNOWN_KEYS.has(key)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `Unknown key \`${[...(ctx.path ?? []), key].join(".")}\`. Per-pass entries support ` +
-                    "`engine`, `model`, `timeoutMs`, `enabled`, `llm`, `graphExtractionBatchSize`, " +
-                    "`graphExtractionIncludeTypes`, and `lazyGraphExtraction`.",
-            });
-            return raw;
+        else if (!INDEX_PASS_KNOWN_KEYS.has(key)) {
+            warnOnce(`index-pass:unknown:${dotted}`, `Unknown key \`${dotted}\` ignored. Per-pass entries support ` +
+                "`engine`, `model`, `timeoutMs`, `enabled`, `llm`, `graphExtractionBatchSize`, " +
+                "`graphExtractionIncludeTypes`, and `lazyGraphExtraction`.");
+            cleaned ??= { ...obj };
+            delete cleaned[key];
         }
     }
-    return raw;
+    return cleaned ?? raw;
 }, z
     .object({
     engine: engineName.optional(),
@@ -120,13 +118,13 @@ const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
     }
     if (typeof raw !== "object")
         return raw;
+    let cleaned;
     for (const [passName, value] of Object.entries(raw)) {
         if (passName === "stalenessDetection") {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: "Invalid `index.stalenessDetection`: the removed pass is not supported.",
-            });
-            return raw;
+            warnOnce("index:stalenessDetection", "`index.stalenessDetection` is a retired pass and is ignored.");
+            cleaned ??= { ...raw };
+            delete cleaned.stalenessDetection;
+            continue;
         }
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
             ctx.addIssue({
@@ -136,7 +134,7 @@ const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
             return raw;
         }
     }
-    return raw;
+    return cleaned ?? raw;
 }, z
     .object({
     defaults: IndexDefaultsSchema.optional(),

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

@@ -8,6 +8,7 @@
  */
 import { z } from "zod";
 import { validateExtraParams } from "../../extra-params.js";
+import { warnOnce } from "../../warn.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../engine-semantics.js";
 /** Persisted config schema version. Package prerelease/patch versions do not change this value. */
 export const CURRENT_CONFIG_VERSION = "0.9.0";
@@ -27,25 +28,41 @@ export const httpUrl = z.string().refine((v) => v.startsWith("http://") || v.sta
 });
 const ENGINE_NAME_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 export const ENV_REFERENCE_PATTERN = /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+/** `secret://<name>` — an apiKey reference into the akm secret store, resolved via `resolveSecretFromStore`. */
+export const SECRET_STORE_REFERENCE_PATTERN = /^secret:\/\/(.+)$/;
 export const engineName = z
     .string()
     .max(63)
     .regex(ENGINE_NAME_PATTERN, "names must be lowercase kebab-case and must not begin with reserved akm-");
+/** The two symbolic apiKey forms akm accepts: an env-var reference or a secret-store reference. Never matches a literal key. */
+export function isApiKeyReference(value) {
+    return ENV_REFERENCE_PATTERN.test(value) || SECRET_STORE_REFERENCE_PATTERN.test(value);
+}
+export function symbolicOrWarnApiKey(label) {
+    return z.string().superRefine((value) => {
+        if (isApiKeyReference(value))
+            return;
+        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR}/secret:// reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) or \`secret://<name>\` (with \`akm secret set <name> ...\`) — see docs/reference/data-and-telemetry.md.`);
+    });
+}
 export const chatCompletionsEndpoint = z.string().superRefine((value, ctx) => {
+    let url;
     try {
-        const url = new URL(value);
-        if (url.protocol !== "http:" && url.protocol !== "https:") {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must use http:// or https://" });
-        }
-        if (url.username || url.password || url.search || url.hash || !url.pathname.endsWith("/chat/completions")) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: "endpoint must be a credential-free OpenAI chat-completions URL without query or fragment",
-            });
-        }
+        url = new URL(value);
     }
     catch {
         ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must be a complete URL" });
+        return;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must use http:// or https://" });
+        return;
+    }
+    if (url.username || url.password) {
+        warnOnce(`chatCompletionsEndpoint:userinfo:${value}`, `Config endpoint "${value}" embeds a username/password; consider moving the credential to the engine's apiKey field instead.`);
+    }
+    if (!url.pathname.endsWith("/chat/completions")) {
+        warnOnce(`chatCompletionsEndpoint:path:${value}`, `Config endpoint "${value}" does not end in /chat/completions; using it as configured.`);
     }
 });
 export const ExtraParamsSchema = z.record(z.unknown()).superRefine((value, ctx) => {

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

@@ -13,7 +13,6 @@ import { z } from "zod";
 // and, transitively, the indexer modules they delegate to).
 import { VALID_ADAPTER_IDS } from "../../adapter/adapter-ids.js";
 import { isBundleSlug } from "../../asset/asset-ref.js";
-import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../../registry-url.js";
 import { httpUrl, nonEmptyString, positiveInt } from "./primitives.js";
 const VALID_ADAPTER_IDS_SET = new Set(VALID_ADAPTER_IDS);
 // ── Sources / registries / installed ────────────────────────────────────────
@@ -56,11 +55,7 @@ export const SourceConfigEntrySchema = z
 });
 export const RegistryConfigEntrySchema = z
     .object({
-    url: httpUrl.superRefine((value, ctx) => {
-        if (hasRegistryUrlCredentials(value)) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: REGISTRY_CREDENTIALS_UNSUPPORTED });
-        }
-    }),
+    url: httpUrl,
     name: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
     provider: z.string().min(1).optional(),

package/dist/core/errors.js

@@ -14,10 +14,10 @@ const CONFIG_HINTS = {
     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.",
+    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the name after `secret://` matches, or run `akm secret set <name> <value>` to store it.",
 };
 // Code-review finding: COMPOSITION_INVALID covers several unrelated causes
 // (a rejected with:, a multi-job source, a composition cycle/depth/size
@@ -39,7 +39,7 @@ const USAGE_HINTS = {
     INVALID_SOURCE_VALUE: "Pick one of: local, registry, all, or a configured source name.",
     INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, yaml, text, md, html.",
     INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full. For agent/summary projections use --shape.",
-    INVALID_SHAPE_VALUE: "Pick one of: human, agent, summary (summary is only valid on `akm show`).",
+    INVALID_SHAPE_VALUE: "Pick one of: human, agent, summary (summary falls back to agent, with a warning, on commands with no summary projection).",
     INVALID_JSON_CONFIG_VALUE: 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.',
     MISSING_OR_AMBIGUOUS_TARGET: "Use `akm bundle update --all` or pass a target like `akm bundle update npm:@scope/pkg` (not both).",
     TARGET_NOT_UPDATABLE: "Run `akm bundle list` to view your sources, then retry with one of those values.",
@@ -74,9 +74,10 @@ const USAGE_HINTS = {
     TASK_TARGET_UNSUPPORTED: "Task definitions support command, script, workflow, and shell (run:) targets; akm/command is layered by callers.",
     // P3a (docs/plans/specs/p3a-plan-v5-child-freeze.md §3.2, A-N2): the
     // complete-or-abandon policy for a stored pre-irVersion-5 run.
-    WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — pre-0.9.2 frozen plans are not re-executable.",
+    WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — a frozen plan this akm cannot execute is not re-executable in place.",
     // P3b (docs/plans/specs/p3b-child-executor.md §4.3).
     WORKFLOW_OUTPUT_INVALID: "Check each `outputs:` entry's `from:` against the step artifact it names, and its `schema:` against the value that step actually promotes.",
+    RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

package/dist/core/improve-types.js

@@ -49,6 +49,23 @@ export function classifyImproveAction(mode) {
             return assertNever(mode);
     }
 }
+/**
+ * #912 — skip reasons that mean infrastructure failed to run the extraction,
+ * not that a session was legitimately uninteresting. `already_extracted`,
+ * `too_short`, and `triaged_out` are the ledger and pre-filter doing their
+ * job and are deliberately excluded; `malformed_model_output` already gets
+ * its own per-session forwarding into the envelope's `warnings[]` and is
+ * excluded here to avoid double-reporting the same failure two ways.
+ *
+ * Typed against `ExtractedSessionResult["skipReason"]` so a future reason
+ * cannot be added to one union without a compiler error surfacing here.
+ */
+export const EXTRACT_INFRASTRUCTURE_SKIP_REASONS = [
+    "llm_unavailable",
+    "read_failed",
+    "exception",
+    "locked_concurrent",
+];
 /** Upper bound on retained sample refs PER reason in {@link DistillSkippedAggregate}. */
 export const DISTILL_SKIPPED_SAMPLE_CAP_PER_REASON = 3;
 /**

package/dist/core/json-schema.js

@@ -61,15 +61,9 @@ import { isRecord } from "./common.js";
  * same schema tree, so they share one bound.
  */
 const MAX_DEFINITION_DEPTH = 64;
-/** Total (schema node × value node) visits one {@link validateJsonSchemaSubset} call may make. */
-const MAX_VALIDATION_NODES = 100_000;
 export function validateJsonSchemaSubset(value, schema, options) {
     const errors = [];
-    const budget = { nodes: MAX_VALIDATION_NODES };
-    validateNode(value, schema, "$", { errors, budget, depth: 0, redactValues: options?.redactValues ?? false });
-    if (budget.nodes < 0) {
-        errors.push(`$: schema evaluation exceeded the limit of ${MAX_VALIDATION_NODES} checks and was stopped`);
-    }
+    validateNode(value, schema, "$", { errors, depth: 0, redactValues: options?.redactValues ?? false });
     return errors;
 }
 /** Human-readable list of the keywords {@link validateJsonSchemaSubset} enforces (for error messages). */
@@ -372,10 +366,6 @@ function validateNode(value, schema, path, ctx) {
         errors.push(`${path}: schema nesting exceeds the depth limit of ${MAX_DEFINITION_DEPTH}`);
         return;
     }
-    // Fail CLOSED: a truncated evaluation never returns "valid" — the counter
-    // going negative is what the wrapper turns into a top-level error.
-    if (--ctx.budget.nodes < 0)
-        return;
     const actual = typeOf(value);
     const declared = schema.type;
     if (typeof declared === "string" || Array.isArray(declared)) {

package/dist/core/maintenance-barrier.js

@@ -10,6 +10,20 @@ import { ConfigError } from "./errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "./file-lock.js";
 import { getMaintenanceBarrierPath } from "./paths.js";
 const heldBarrierContext = new AsyncLocalStorage();
+/**
+ * The barrier is meant to be held only for the short critical section that
+ * registers one lock/lease/activity — a process that still holds it past
+ * this age is wedged (crashed mid-section, deadlocked, killed without
+ * cleanup), not doing legitimate long-running work. Without an age bound, a
+ * probe only reclaims a lock whose holder PID has verifiably died; a wedged
+ * — but still-alive — holder (or a PID a container/namespace boundary
+ * reused, making `isProcessAlive` see the wrong process as live) locked
+ * every other akm invocation out of ANY maintenance registration forever,
+ * with no recovery but killing the holder by hand.  5 minutes matches the
+ * stale-lock window already used for the improve extract-session lock
+ * (`commands/improve/extract.ts`).
+ */
+const MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
 /**
  * Serialize the short critical section that creates each long-lived AKM lock,
  * lease, or state activity. The operation keeps its own ownership record; this
@@ -23,7 +37,7 @@ export function tryAcquireMaintenanceBarrier() {
         if (ownership) {
             return () => releaseLock(ownership);
         }
-        const probe = probeLock(lockPath);
+        const probe = probeLock(lockPath, { staleAfterMs: MAINTENANCE_BARRIER_STALE_AFTER_MS });
         if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
             return undefined;
     }
@@ -33,7 +47,8 @@ export function acquireMaintenanceBarrier() {
     const release = tryAcquireMaintenanceBarrier();
     if (release)
         return release;
-    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes.`, "INVALID_CONFIG_FILE");
+    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes. ` +
+        `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60_000} minute(s) is reclaimed automatically on the next attempt.`, "INVALID_CONFIG_FILE");
 }
 export function withMaintenanceStartBarrier(run) {
     if (heldBarrierContext.getStore()?.active)

package/dist/core/paths.js

@@ -13,6 +13,7 @@ import path from "node:path";
 import { shortHash } from "./bundle-id.js";
 import { ConfigError } from "./errors.js";
 import { IS_WINDOWS } from "./platform.js";
+import { warnOnce } from "./warn.js";
 /**
  * Returns true when the current process appears to be running under
  * `bun test` (either via the BUN_TEST sentinel Bun sets on the test
@@ -424,7 +425,6 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     const SYSTEM_ROOTS = new Set([
         "/etc",
         "/var",
-        "/var/tmp",
         "/usr",
         "/usr/local",
         "/opt",
@@ -448,6 +448,9 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     if (SYSTEM_ROOTS.has(resolved)) {
         throw new ConfigError(`Refusing stashDir at system path (${resolved}). Pick a path inside your home directory.`, "UNSAFE_STASH_DIR");
     }
+    if (resolved === "/var/tmp") {
+        warnOnce("stash-dir:var-tmp", `Stash directory is at ${resolved}, a shared scratch directory system cleanup jobs may periodically empty; using it as configured.`);
+    }
     // User home — exact match only. Subdirs (~/akm, ~/work/stash) are fine.
     // Check BOTH the env-controlled home and the OS-reported home, so the
     // refusal can't be bypassed by unsetting HOME, and so it still fires
@@ -465,27 +468,21 @@ export function assertSafeStashDir(stashDir, env = process.env) {
     catch {
         // os.homedir() can throw on misconfigured systems; ignore.
     }
-    const HIDDEN_USER_PARENTS = [
-        ".config",
-        ".local",
-        ".cache",
-        ".ssh",
-        ".gnupg",
-        ".aws",
-        ".kube",
-        ".docker",
-        "Documents",
-        "Downloads",
-        "AppData",
-    ];
+    const CREDENTIAL_USER_PARENTS = [".config", ".local", ".cache", ".ssh", ".gnupg", ".aws", ".kube", ".docker"];
+    const PLAIN_USER_DATA_PARENTS = ["Documents", "Downloads", "AppData"];
     for (const home of candidateHomes) {
         if (resolved === home) {
             throw new ConfigError(`Refusing stashDir at your home directory (${resolved}). Pick a subdirectory like ~/akm.`, "UNSAFE_STASH_DIR");
         }
-        for (const sub of HIDDEN_USER_PARENTS) {
+        for (const sub of CREDENTIAL_USER_PARENTS) {
             if (resolved === path.join(home, sub)) {
                 throw new ConfigError(`Refusing stashDir at sensitive user directory (${resolved}). Pick a subdirectory or a dedicated workspace.`, "UNSAFE_STASH_DIR");
             }
         }
+        for (const sub of PLAIN_USER_DATA_PARENTS) {
+            if (resolved === path.join(home, sub)) {
+                warnOnce(`stash-dir:plain-user-data:${sub}`, `Stash directory is at ${resolved}, your ${sub} folder; using it as configured, though it is usually a large, unrelated-content directory to index.`);
+            }
+        }
     }
 }

package/dist/core/state/migrations.js

@@ -37,6 +37,7 @@ export const STATE_MIGRATION_SAFETY_BY_ID = Object.freeze({
     "024-workflow-run-outputs": "additive",
     "025-task-history-vocabulary-backfill": "data-preserving-rebuild",
     "026-proposals-strip-legacy-fragment-refs": "data-preserving-rebuild",
+    "027-extract-sessions-seen-harness-rename": "data-preserving-rebuild",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1149,6 +1150,33 @@ export const STATE_MIGRATIONS = [
       WHERE ref LIKE '%#%';
     `,
     },
+    // ── Migration 027 — claude-code -> claude harness rename (#915) ──
+    //
+    // The 0.9.2 rename shipped without a data migration, so rows written under
+    // the old key were invisible to every reader keyed on "claude".
+    //
+    // `extract_sessions_seen` has PRIMARY KEY (harness, session_id), so a
+    // session already recorded under "claude" (written by a run that really
+    // happened post-rename) collides with its "claude-code" counterpart on
+    // rename. `UPDATE OR IGNORE` keeps the newer "claude" row exactly as it
+    // was — the older row's outcome is superseded, not more correct — and the
+    // trailing DELETE drops that now-unreachable duplicate so the "claude-code"
+    // key space is fully empty afterwards, not just mostly-migrated.
+    //
+    // `workflow_runs.agent_harness` (migration 020) has no uniqueness
+    // constraint on that column, so a plain UPDATE is sufficient there. Both
+    // statements are kept in one migration so the rename is a single ledger
+    // event. `improve_runs.result_json` is deliberately untouched: the harness
+    // name embedded in those JSON blobs is reporting data about a past run, not
+    // a lookup key, so rewriting it would not fix anything a reader depends on.
+    {
+        id: "027-extract-sessions-seen-harness-rename",
+        up: `
+      UPDATE OR IGNORE extract_sessions_seen SET harness = 'claude' WHERE harness = 'claude-code';
+      DELETE FROM extract_sessions_seen WHERE harness = 'claude-code';
+      UPDATE workflow_runs SET agent_harness = 'claude' WHERE agent_harness = 'claude-code';
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {

package/dist/core/state-db.js

@@ -69,9 +69,11 @@ import { sleepSync } from "../runtime.js";
 import { openDatabase } from "../storage/database.js";
 import { assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
 import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
+import { pkgVersion } from "../version.js";
 import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
 import { getDataDir } from "./paths.js";
 import { runMigrations, STATE_MIGRATIONS } from "./state/migrations.js";
+import { warnOnce } from "./warn.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -370,6 +372,25 @@ function createHistoricalStateSafetyCopy(source, migrationId) {
  *     matches the value used in openDatabase() for index.db; 5 s proved too
  *     narrow when a post-inference reindex overlapped a parallel event write.
  */
+/**
+ * Tell the operator once when state.db was migrated by a newer akm than the
+ * one running. The open proceeds: every migration this binary knows is already
+ * applied, so it reads and writes the tables it knows. Commands that depend on
+ * something a later migration changed may still report less than the truth,
+ * which is why this is said out loud rather than swallowed.
+ */
+function warnNewerStateLedger(ledger) {
+    if (ledger.status !== "newer")
+        return;
+    warnOnce("state-db-newer-ledger", `[state.db] This akm (v${pkgVersion}) is older than the state database: ${ledger.detail}. ` +
+        "Continuing with the schema this version knows; upgrade akm if its output looks incomplete.");
+}
+function unversionedDatabaseHasNoTables(db) {
+    const tables = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != ?")
+        .get("schema_migrations");
+    return !tables;
+}
 export function openStateDatabase(dbPath, options) {
     const canonicalPath = getStateDbPath();
     const resolvedPath = dbPath ?? canonicalPath;
@@ -392,6 +413,7 @@ export function openStateDatabase(dbPath, options) {
     let existingSource;
     let openedDb;
     let existingUnversionedDatabase = false;
+    let treatUnversionedAsFresh = false;
     let stateSafetyCopyCreated = false;
     try {
         fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
@@ -404,7 +426,12 @@ export function openStateDatabase(dbPath, options) {
             try {
                 preflight.exec("PRAGMA busy_timeout = 30000");
                 const ledger = assertMigrationLedger(preflight, STATE_MIGRATIONS);
+                warnNewerStateLedger(ledger);
                 existingUnversionedDatabase = ledger.migrationIds.length === 0;
+                if (existingUnversionedDatabase && unversionedDatabaseHasNoTables(preflight)) {
+                    existingUnversionedDatabase = false;
+                    treatUnversionedAsFresh = true;
+                }
                 if (existingUnversionedDatabase && !options?.allowHistoricalDestructiveStateUpgrade) {
                     throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
                         "Run `akm upgrade` (or `akm migrate apply`) to create a verified snapshot before migration 001 " +
@@ -421,7 +448,7 @@ export function openStateDatabase(dbPath, options) {
             pragmas: { dataDir: path.dirname(resolvedPath) },
             init: (db) => {
                 runMigrations(db, {
-                    freshDatabase: !!freshReservation,
+                    freshDatabase: !!freshReservation || treatUnversionedAsFresh,
                     existingUnversionedDatabase,
                     allowHistoricalDestructiveStateUpgrade: options?.allowHistoricalDestructiveStateUpgrade,
                     beforeExistingUnversionedStateMigration: options?.allowHistoricalDestructiveStateUpgrade

package/dist/core/write-source.js

@@ -37,7 +37,7 @@ import { existingFileMode, isWithin, resolveStashDir, writeFileAtomic } from "./
 import { bundleContentRoot, resolveConfiguredSources } from "./config/config.js";
 import { ConfigError, UsageError } from "./errors.js";
 import { sanitizeCommitMessage } from "./git-message.js";
-import { warn } from "./warn.js";
+import { warn, warnOnce } from "./warn.js";
 import { recordWrittenPath } from "./write-provenance.js";
 /**
  * Source kinds that the loader is allowed to mark `writable: true`. Anything
@@ -872,10 +872,10 @@ export function prepareWriteTargetForMutation(target, options = {}) {
     }
     const upstream = inspectGitUpstream(repoPath);
     if (upstream.behind > 0) {
-        throw new UsageError(`Writable Git target "${target.source.name}" is behind ${upstream.upstream}; run \`akm bundle update ${target.source.name}\` before writing.`, "INVALID_FLAG_VALUE");
+        warnOnce(`write-source:git-behind:${realRepoPath}`, `Writable Git target "${target.source.name}" is ${upstream.behind} commit(s) behind ${upstream.upstream}; writing anyway. Run \`akm bundle update ${target.source.name}\` to catch up.`);
     }
-    if (upstream.ahead > 0 && options.allowAhead !== true) {
-        throw new UsageError(`Writable Git target "${target.source.name}" has unpushed commits; push or reconcile them before AKM writes another commit.`, "INVALID_FLAG_VALUE");
+    if (upstream.ahead > 0) {
+        warnOnce(`write-source:git-ahead:${realRepoPath}`, `Writable Git target "${target.source.name}" has ${upstream.ahead} unpushed commit(s); writing another on top. Push or reconcile them when convenient.`);
     }
     return {
         ...target,
@@ -997,7 +997,7 @@ const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
 function resolveAssetFilePath(source, ref) {
     const basename = path.posix.basename(ref.name.replaceAll("\\", "/")).replace(/\.md$/i, "").toLowerCase();
     if (basename === "index" || basename === "log") {
-        throw new UsageError(`Reserved concept name "${basename}" cannot be written.`, "INVALID_FLAG_VALUE");
+        warnOnce(`write-source:reserved-basename:${basename}`, `Concept name "${basename}" collides with a reserved word some tooling treats specially; writing it anyway.`);
     }
     // Windows resolves these names as DEVICES no matter the directory or the
     // extension, so `CON.md` is not a file — a write goes to the console and a
@@ -1005,7 +1005,7 @@ function resolveAssetFilePath(source, ref) {
     // portable: an asset authored on Linux must not become unopenable when the
     // same bundle is used on Windows.
     if (WINDOWS_RESERVED_DEVICE_NAMES.has(basename)) {
-        throw new UsageError(`Asset name "${basename}" is a reserved Windows device name and cannot be written.`, "INVALID_FLAG_VALUE");
+        warnOnce(`write-source:windows-device-name:${basename}`, `Asset name "${basename}" is a reserved Windows device name; writing it anyway, but this bundle will not be portable to Windows.`);
     }
     const typeDir = stashDirFor(ref.type);
     if (!typeDir) {

package/dist/indexer/bundle-identity-guard.js

@@ -33,6 +33,7 @@ import { rethrowIfTestIsolationError } from "../core/errors.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
+import { isCanonicalIndexGeneration } from "../storage/repositories/index-entry-schema.js";
 let guardSettled = false;
 /** TEST-ONLY: re-arm the once-per-process guard between cases. */
 export function resetBundleIdentityGuardForTests() {
@@ -47,6 +48,8 @@ function indexBundlePrefixes(dbPath) {
         db = openReadonlyExistingDatabase(dbPath);
         if (!db)
             return undefined;
+        if (!isCanonicalIndexGeneration(db))
+            return undefined;
         return db
             .prepare("SELECT DISTINCT bundle_id AS b FROM entries WHERE bundle_id IS NOT NULL AND bundle_id != ''")
             .all().map((row) => row.b);

package/dist/indexer/ensure-index.js

@@ -26,6 +26,7 @@ import { classifyPathAccess } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getEntryCount, getIndexedFilePaths } from "../storage/repositories/index-entries-repository.js";
+import { isCanonicalIndexGeneration } from "../storage/repositories/index-entry-schema.js";
 import { getMeta } from "../storage/repositories/index-meta-repository.js";
 import { warnOnBundleRenameDrift } from "./bundle-identity-guard.js";
 function getIndexableFiles(root, spec) {
@@ -118,6 +119,8 @@ export function isIndexStale(stashDir) {
     let db;
     try {
         db = openExistingDatabase(dbPath);
+        if (!isCanonicalIndexGeneration(db))
+            return true;
         const entryCount = getEntryCount(db);
         if (entryCount === 0)
             return true;
@@ -164,6 +167,8 @@ function indexCanServeStash(stashDir) {
     let db;
     try {
         db = openExistingDatabase(dbPath);
+        if (!isCanonicalIndexGeneration(db))
+            return false;
         if (getEntryCount(db) === 0)
             return false;
         const storedStashDir = getMeta(db, "stashDir");

package/dist/indexer/indexer.js

@@ -1770,9 +1770,17 @@ async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
                 const entry = readLookupEntry(db, id, ref.conceptId, source.path);
                 if (entry) {
                     if (owner.workflowSource) {
-                        assertIndexedWorkflowSourceIdentity(inputRef, entry.filePath, owner.workflowSource);
-                        if (entry.adapterId !== adapterId) {
-                            throw new WorkflowSourceIdentityError(inputRef, entry.filePath, owner.path);
+                        try {
+                            assertIndexedWorkflowSourceIdentity(inputRef, entry.filePath, owner.workflowSource);
+                            if (entry.adapterId !== adapterId) {
+                                throw new WorkflowSourceIdentityError(inputRef, entry.filePath, owner.path);
+                            }
+                        }
+                        catch (error) {
+                            if (!(error instanceof WorkflowSourceIdentityError))
+                                throw error;
+                            warn(`${error.message} Falling back to the physical owner.`);
+                            return { entry: null, owner, ...(indexError === undefined ? {} : { indexError }) };
                         }
                     }
                     else if (entry.adapterId !== adapterId || !indexedPathMatchesOwner(entry.filePath, owner)) {

package/dist/indexer/lookup/adapter-concept-owner.js

@@ -7,6 +7,7 @@ import { adapterForId } from "../../core/adapter/registry.js";
 import { compareCodePoints, hasErrnoCode, isWithin } from "../../core/common.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
+import { warnOnce } from "../../core/warn.js";
 import { resolveUniqueWorkflowSource, workflowNameForConceptId, } from "../../workflows/source-files.js";
 import { buildFileContext } from "../walk/file-context.js";
 const CONTENT_READ_REQUIRED = Symbol("adapter ownership probe requires content");
@@ -123,7 +124,7 @@ function claimsWithoutContent(adapter, component, owner) {
  * adapter supplies its own read placements and is probed with a byte-denying
  * FileContext so path-level abstention remains authoritative.
  */
-export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
+export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId, options) {
     const adapter = adapterForId(adapterId);
     const normalized = normalizedConceptId(conceptId);
     if (!adapter || !normalized)
@@ -185,9 +186,19 @@ export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
         if (claimsWithoutContent(adapter, component, candidate))
             ownersByIdentity.set(identity, candidate);
     }
-    const owners = [...ownersByIdentity.values()].filter((owner) => owner.conceptId === resolutionConceptId);
+    const owners = [...ownersByIdentity.values()]
+        .filter((owner) => owner.conceptId === resolutionConceptId)
+        .sort((left, right) => compareCodePoints(left.path, right.path));
     if (owners.length > 1) {
-        throw new AdapterConceptCollisionError(adapterId, resolutionConceptId, owners.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")));
+        if (options?.mode !== "read") {
+            throw new AdapterConceptCollisionError(adapterId, resolutionConceptId, owners.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")));
+        }
+        const [winner, ...losers] = owners;
+        warnOnce(`adapter-concept-collision:${adapterId}:${resolutionConceptId}`, `Adapter "${adapterId}" has multiple physical owners for "${resolutionConceptId}": ` +
+            `${owners.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")).join(", ")}. ` +
+            `Reading "${path.relative(sourcePath, winner.path).replaceAll("\\", "/")}" and ignoring ` +
+            `${losers.map((owner) => path.relative(sourcePath, owner.path).replaceAll("\\", "/")).join(", ")}.`);
+        return winner;
     }
     return owners[0];
 }