akm-cli 0.9.17-alpha.9 → 0.9.17

package/dist/storage/repositories/index-connection.js

@@ -180,9 +180,12 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     // never block — but in the DELETE/TRUNCATE modes the network-FS fallback and
     // AKM_SQLITE_JOURNAL_MODE can select, a concurrent writer makes every read
     // fail instantly with SQLITE_BUSY. busy_timeout is legal on a read-only
-    // connection, so apply just that one.
+    // connection, so apply just that one. `busyTimeoutMs` defaults to the
+    // shared 30s constant; a caller that must never sit behind another akm
+    // process's write lock for long (e.g. `akm info`) can pass a much shorter
+    // bound instead.
     try {
-        db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+        db.exec(`PRAGMA busy_timeout = ${options?.busyTimeoutMs ?? SQLITE_BUSY_TIMEOUT_MS}`);
         checkIndexLayout(db, resolvedPath);
         return db;
     }

package/docs/migration/README.md

@@ -5,7 +5,7 @@ Upgrade guides and per-release migration notes.
 - [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
-- [v0.9.17 release note](release-notes/0.9.17.md) -- Tolerant readers, one config migration step, a plain scheduler list, less machinery, and the upgrade rehearsal gate
+- [v0.9.17 release note](release-notes/0.9.17.md) -- Consolidate's retire proposals and index layout 26, replacing the LLM entity graph with declared links, and `akm improve` scoped to what retrieval actually returns
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
 - [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes

package/docs/migration/release-notes/0.9.17.md

@@ -1,43 +1,132 @@
 Migration notes for akm v0.9.17
 
-Upgrading no longer needs a manual step to keep working, and there is less
-machinery to break.
-
-Readers tolerate what older releases wrote, except task sources. A
-`version: 2` or `version: 3` task source fails on its own with
-`TASK_SCHEMA_VERSION_UNSUPPORTED`, naming `akm migrate apply`, which converts
-it to `version: 4` once; the other tasks keep running. A config key this
-release does not know -- retired, misspelled, or written by a newer release --
-is kept in memory and named once, never a reason to refuse the config;
-ordinary writes round-trip it, and `akm migrate apply` drops it.
-`akm migrate apply` has one config step (`configFile`): read config.json
-through the same pipeline every load runs and write the current shape back,
-under a backup.
-
-Scheduling is one list. `scheduler.enabled` in config.json holds the
-fully-qualified refs this host schedules (`bundle//tasks/x`). The
-0.9.17-alpha `{kind, ref, sourceId}` grant objects are read as their ref. A
-config with no list at all -- every release before 0.9.17 -- means "keep
-what is installed": the first `akm task sync` (or `setup`, `task enable`,
-`task disable`, `task add`) after the upgrade takes the akm-written rows
-already in the native scheduler as the host's choice, writes the list, and
-says so. An explicit list, empty or not, is never second-guessed. There are
-no grants, no source identities, no carry-forward and no fire-time gate.
-
-Removed machinery: filesystem transaction journals for proposal accept/revert
-(the asset is written, then the proposal row and its event are recorded in
-one state.db transaction; a crash in between leaves a re-acceptable pending
-proposal); the maintenance barrier, its per-process activity registry (the
-source of the lock-sidecar leak) and the SQLite lock-operation mutex (a lock
-file is one `O_EXCL` create); startup version reconciliation and
-`--host-local`; the akm-install enumerator and `akm upgrade --version/--tag`;
-the upgrade and transaction health advisories; the `akm info` compat
-manifest. `akm migrate apply` removes the files those left under `$DATA`,
-`$STATE` and `$CONFIG`.
-
-Every historical shape akm has written is exercised by the upgrade rehearsal
-(`tests/integration/upgrade-rehearsal/`) before each release: a real previous
-release builds a home, the candidate installs over it in place, and the
-rehearsal drives migrate, bundle list, search, show, task sync, health and a
-scheduled task's generated cron command, then confirms the previous release
-still runs against the candidate-written home.
+Run this after upgrading:
+
+```sh
+akm migrate apply
+akm task sync
+```
+
+akm migrate apply reads config.json through the normal load pipeline and
+writes its current shape back under a backup, dropping every retired key it
+finds -- run it with --dry-run first to see the exact list for your config.
+From 0.9.16, that includes index.graph.*, index.metadataEnhance,
+search.minScore, search.graphBoost.*, improve.utilityDecay.*, and a dozen
+smaller ones. None of them do anything any more -- leaving them in
+config.json is harmless until you run migrate apply, which drops them for
+good. It also deletes files nothing reads any more: 0.9.16's transaction
+journals ($DATA/txn/ and $DATA/txn-quarantine/), its maintenance barrier
+lock, and the maintenance-activities/ registry, which leaked an entry per
+process and reached 927 MB on one host. It also drops a leftover
+improve.strategies["graph-refresh"] override block, but not
+defaults.improveStrategy: "graph-refresh" itself -- if you set that, change
+it to a different strategy by hand, since graph-refresh now refuses
+outright, naming the retirement, rather than quietly running as a no-op. The
+shipped akm-graph-refresh-weekly task template is gone; remove or repoint
+any task that used it. Separately, akm search --no-project-context and akm
+proposal drain --policy/--max-diff-lines now fail as unknown flags; drop
+them from any script or task that still passes them.
+
+The first akm index after upgrading migrates index.db to layout 26 in
+place -- for a 0.9.16 index this includes a one-time full-text rebuild it
+was already due for, so budget a few seconds for a 24k-entry index rather
+than a fraction of one. This also drops the LLM entity-graph tables -- the
+per-file entity/relation extraction that fed akm show's old related list is
+retired -- and ends with a VACUUM that reclaims the space both steps free;
+akm index has never VACUUMed index.db before, so this is the first time it
+happens at all, not a repeat of something 0.9.16 already did. Nothing is
+re-embedded by this migration.
+
+Embeddings are a separate matter if you use a nomic-embed or E5 model:
+akm index now sends the model's own document template (nomic:
+"search_document: ", E5: "passage: ") instead of the raw text, which changes
+what gets embedded, so every entry re-embeds once on the next akm index.
+Qwen3, the BGE/mxbai/arctic family, and the default local model have no
+document template and keep their stored vectors untouched. Set
+embedding.documentTemplate: "" if you'd rather keep the old vectors than pay
+for a full re-embed. If you had index.metadataEnhance on before upgrading
+(it defaulted off), run akm index --full once afterward to replace the
+LLM-written descriptions it left behind with the plain deterministic ones --
+an ordinary incremental akm index does not touch them.
+
+The first akm task sync after upgrading rewrites every akm-managed
+scheduler row once, in place. Each row now sets its own AKM_BUNDLE_DIR
+(plus any AKM_CONFIG_DIR/AKM_DATA_DIR/AKM_CACHE_DIR/AKM_STATE_DIR the
+syncing shell had set explicitly) inline, instead of pointing at a
+--scheduler-context <file> descriptor, and a crontab's PATH moves the same
+way, into a # akm:env block next to the task rows. The rewrite keeps each
+row's existing launcher and schedule -- it is reported as an update, never
+an add or a remove -- and rows written by 0.9.0 through 0.9.16 keep firing
+normally until that sync runs. Once akm task doctor lists no binding still
+pointing at a descriptor file, the old $DATA/tasks/context/ files can be
+deleted.
+
+akm improve now reworks only what retrieval actually returned -- an asset a
+real search, curate, show, or feedback touched in the last 90 days -- plus
+material no improve stage has processed yet. The proactive-maintenance and
+high-salience lanes, and the memory consolidation judge, no longer reach
+into the unread tail of a stash; an asset left out this way shows up under a
+new retrieval gate in akm improve --dry-run and under akm health's
+not_retrieved skip reason, not silently.
+
+Consolidation gets a second pass. It compares each new-or-changed memory,
+flat knowledge/ file, or lesson against its nearest neighbours, and where an
+LLM judge calls a pair duplicate, subsumed, or superseding, it mints a
+reviewed retire proposal for the losing side -- nothing is retired
+automatically. Review these like any other proposal: akm proposal list
+--generator consolidate-pair (or just akm proposal list, which flags one
+carrying continuity risk inline), show, diff, then accept or reject.
+Accepting one archives the losing file instead of deleting it, and akm
+proposal revert restores it exactly; archived files are only deleted 30 days
+after retirement, and only once git holds them clean and unmodified.
+Accepting a promotion (a consolidate promote proposal, by a person or by
+triage auto-promotion) now also archives the source memory it was promoted
+from, so a promotion no longer leaves a duplicate sitting next to the
+knowledge doc it produced.
+
+akm proposal drain, and improve's own triage pre-pass, no longer take a
+policy. Both now accept only a proposal the quality judge passed on its
+exact content and reject an empty diff; everything else goes to
+processes.triage.judgment or waits for review -- including extract and
+consolidate proposals, which used to be auto-accepted on size alone under
+the personal-stash default.
+
+akm show no longer has a related field. It lists an asset's links instead:
+the relations a bundle already declares -- cross-references, supersededBy,
+a .derived memory's parent, a wiki's citations, resolved page links, a
+workflow's or task's target -- grouped outgoing/incoming/unresolved,
+computed with no LLM call. Curate's support refs are drawn from the same
+links now, not from the retired entity graph.
+
+akm info always exits 0 and always prints a report, even when something is
+wrong: an invalid config.json, a missing or unreadable bundle directory, or
+a locked/newer/corrupt index.db is named in the report (configError,
+bundleDirError, indexStats.unavailable) instead of failing the command or
+showing unexplained zeros. It also reports link counts per kind, including
+how many are unresolved.
+
+Decide every pending retire proposal -- akm proposal accept or reject --
+before downgrading to 0.9.16. Older releases predate the retire proposal
+shape entirely: akm proposal show/diff/drain exits 70 on one it doesn't
+recognize, and drain's own nightly pre-pass failing on the first pending
+retire proposal it meets stops that run's auto-promotion for the whole
+stash, not just for the one proposal.
+
+0.9.16 already refuses to open a newer-layout index.db outright
+(INDEX_SCHEMA_INCOMPATIBLE, naming the upgrade) and leaves the file
+untouched, so downgrading needs a fresh index: move index.db aside and run
+akm index --full under 0.9.16, which re-embeds everything from scratch.
+
+A workflow run started under 0.9.17 freezes its plan as irVersion 6,
+which 0.9.16 does not understand and refuses to resume
+(WORKFLOW_IR_VERSION_UNSUPPORTED) -- let any in-flight workflow runs finish
+before downgrading, or plan to restart them fresh under 0.9.16.
+
+The state.db migration that adds the improve ledger
+(028-improve-ledger) drops six tables 0.9.16 and earlier used
+(proposal_fingerprints and friends). Because it drops schema, the akm that
+runs it first copies the database to state.db.pre-028-improve-ledger.bak
+before making the change. That backup is a snapshot from the moment of
+upgrade -- restoring it to downgrade discards every proposal, event, and run
+state.db has recorded since, not just the ledger's own six tables, so treat
+it as a last resort rather than routine.

package/docs/migration/release-notes/README.md

@@ -7,6 +7,13 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
+- [0.9.17](0.9.17.md) — consolidate's retire proposals and continuity check,
+  promotions archiving their source memory, declared links replacing the LLM
+  entity graph, index layout 26, scheduler rows carrying their own context,
+  and `akm improve` scoped to what retrieval actually returns
+- [0.9.16](0.9.16.md) — source-bound scheduler grants, local execution
+  authority, config inheritance's portable-data boundary, and split unsafe
+  overrides
 - [0.9.15](0.9.15.md) — exit-code 75 for lease/state.db contention,
   `--require-engines` scheduled task templates, `--no-probe` cli-version
   skip, thinking-control wire forms, embedding re-embed safety and

package/docs/reference/cli.md

@@ -318,8 +318,10 @@ Returns a JSON object with:
 | Field | Description |
 | --- | --- |
 | `version` | Current akm version |
-| `bundleDir` | Primary bundle directory — same resolution `akm bundle list` uses |
+| `bundleDir` | Primary bundle directory — same resolution `akm bundle list` uses. Falls back to the platform-default location when no bundle resolves. |
 | `defaultBundle` | Name of the primary bundle from config, or `null` when none is configured |
+| `configError` | Present only when `config.json` exists but could not be loaded (parse or schema failure); every config-derived field falls back to the same defaults a fresh install reports |
+| `bundleDirError` | Present when a bundle IS configured (an env override or `bundles.*` in config) but its path doesn't resolve, OR when the platform-default fallback itself can't resolve (e.g. `HOME` unset) — absent for the ordinary "no bundle created yet" state, where `bundleDir` needs no explanation |
 | `dataDir` | Resolved data directory (`getDataDir()`) |
 | `configDir` | Resolved config directory (`getConfigDir()`) |
 | `cacheDir` | Resolved cache directory (`getCacheDir()`) |
@@ -329,7 +331,14 @@ Returns a JSON object with:
 | `semanticSearch` | Semantic search status: `mode`, `status`, and optional `reason`/`message` |
 | `registries` | Configured registries |
 | `sourceProviders` | Configured sources (filesystem, git, website, npm) |
-| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `links` (declared links per kind with `total` and `unresolved`; absent when the index holds none), `lastBuiltAt`, `hasEmbeddings` |
+| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `links` (declared links per kind with `total` and `unresolved`; absent when the index holds none), `lastBuiltAt`, `hasEmbeddings`, `unreadable` (index.db exists but the filesystem refuses to read it — a permissions problem), `unavailable` (index.db is readable but the SQLite-level read didn't complete: locked by another akm process, a newer layout this akm can't understand, or a corrupt file) |
+
+`akm info` never refuses: an unreadable config, an unresolvable bundle
+directory, or an index.db that's locked, newer, older, corrupt, missing, or
+empty each degrade the relevant field(s) above instead of failing the
+command. It also never waits more than about 1.5s on a locked index.db,
+regardless of the shared 30s lock-wait every write command otherwise uses,
+and warns rather than refusing on an unrecognized flag.
 
 `semanticSearch.status` values:
 - `"ready-js"` — every entry has a vector; semantic search is active (the name is historical: `"ready-vec"`, the sqlite-vec variant, is gone)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.17-alpha.9",
+  "version": "0.9.17",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [