akm-cli 0.9.17 → 0.9.19-alpha.1

package/dist/storage/repositories/proposals-repository.js

@@ -106,6 +106,20 @@ const GATE_OUTCOMES = {
     staged: true,
     "auto-rejected": true,
 };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One undone rejection in `metadata_json.reviewHistory` (see `ProposalReviewHistoryEntry`): only the fields readers rely on are checked. */
+function isReviewHistoryEntry(value) {
+    if (!isRecord(value))
+        return false;
+    const { review, gateDecision, reopenedAt, reopenReason } = value;
+    return (typeof reopenedAt === "string" &&
+        (reopenReason === undefined || typeof reopenReason === "string") &&
+        (review === undefined ||
+            (isRecord(review) && typeof review.outcome === "string" && typeof review.decidedAt === "string")) &&
+        (gateDecision === undefined || isRecord(gateDecision)));
+}
 function validatePresentMetadata(meta) {
     const stringFields = ["sourceRun", "beforeHash", "beforeHashNormalized", "backupContent"];
     for (const field of stringFields) {
@@ -129,6 +143,12 @@ function validatePresentMetadata(meta) {
             invalidPresentField("review");
         }
     }
+    if (Object.hasOwn(meta, "reviewHistory")) {
+        const history = meta.reviewHistory;
+        if (!Array.isArray(history) || history.some((entry) => !isReviewHistoryEntry(entry))) {
+            invalidPresentField("reviewHistory");
+        }
+    }
     if (Object.hasOwn(meta, "gateDecision")) {
         const gate = meta.gateDecision;
         if (typeof gate !== "object" ||
@@ -270,6 +290,7 @@ export function proposalRowToProposal(row) {
         ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
         ...(typeof meta.beforeHashNormalized === "string" ? { beforeHashNormalized: meta.beforeHashNormalized } : {}),
         ...(meta.review !== undefined ? { review: meta.review } : {}),
+        ...(meta.reviewHistory !== undefined ? { reviewHistory: meta.reviewHistory } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
@@ -332,6 +353,8 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.sourceRun = proposal.sourceRun;
     if (proposal.review !== undefined)
         metaObj.review = proposal.review;
+    if (proposal.reviewHistory !== undefined)
+        metaObj.reviewHistory = proposal.reviewHistory;
     if (proposal.confidence !== undefined)
         metaObj.confidence = proposal.confidence;
     if (proposal.gateDecision !== undefined)

package/dist/storage/sqlite-read-snapshot.js

@@ -9,7 +9,12 @@
  * must not do that. This helper copies a stable main/WAL pair and opens that
  * private copy, so SQLite never attaches to the operator's original
  * main/WAL/SHM files.
+ *
+ * The copy itself is made by a child process, never by this one: see
+ * {@link copyFileOutsideThisProcess} for why an in-process read of a live
+ * database is unsafe.
  */
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -57,6 +62,45 @@ function fingerprintsEqual(left, right) {
     const sameFile = (a, b) => a?.size === b?.size && a?.mtimeNs === b?.mtimeNs && a?.ctimeNs === b?.ctimeNs;
     return sameFile(left.main, right.main) && sameFile(left.wal, right.wal);
 }
+/**
+ * Copy `source` to `destination` without opening `source` in THIS process.
+ *
+ * POSIX advisory locks belong to the process, not to the descriptor: when a
+ * process closes ANY descriptor for a file, the kernel drops every lock that
+ * process holds on it, including the SHARED lock a live SQLite connection in
+ * this same process (`akm improve` keeps one on state.db for the whole run)
+ * holds. A peer using an older SQLite (< 3.51) read-write would then see no
+ * reader, take EXCLUSIVE when it closes, and delete the `-wal`/`-shm` this
+ * process is still using. The read therefore happens in a child `cp`, whose
+ * descriptors and locks are its own. Windows locks belong to the handle, so
+ * an in-process copy cannot release another handle's lock there (and there is
+ * no `cp`).
+ *
+ * A source that vanished (a WAL checkpointed away mid-copy) throws an
+ * `ENOENT` error, which {@link openSqliteReadSnapshot} retries.
+ */
+function copyFileOutsideThisProcess(source, destination) {
+    if (process.platform === "win32") {
+        fs.copyFileSync(source, destination);
+        return;
+    }
+    const result = spawnSync("cp", ["--", source, destination], {
+        encoding: "utf8",
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (result.error) {
+        throw new SqliteReadSnapshotUnavailableError(`cannot run cp to copy ${source}: ${result.error.message}`);
+    }
+    if (result.status === 0)
+        return;
+    // `cp` reports its errors as text, so the vanished-source case is recognised
+    // by looking at the source itself.
+    if (fileFingerprint(source) === undefined) {
+        throw Object.assign(new Error(`${source} disappeared while it was being copied`), { code: "ENOENT" });
+    }
+    const reason = result.stderr.trim() || (result.signal ? `killed by ${result.signal}` : `exit status ${result.status}`);
+    throw new Error(`cp could not copy ${source}: ${reason}`);
+}
 /**
  * Open an isolated copy of an existing SQLite database.
  *
@@ -82,9 +126,9 @@ export function openSqliteReadSnapshot(dbPath) {
                 if (pathExists(`${dbPath}-journal`))
                     continue;
                 const before = databaseFingerprint(dbPath);
-                fs.copyFileSync(dbPath, snapshotPath);
+                copyFileOutsideThisProcess(dbPath, snapshotPath);
                 if (before.wal)
-                    fs.copyFileSync(`${dbPath}-wal`, `${snapshotPath}-wal`);
+                    copyFileOutsideThisProcess(`${dbPath}-wal`, `${snapshotPath}-wal`);
                 else
                     fs.rmSync(`${snapshotPath}-wal`, { force: true });
                 const after = databaseFingerprint(dbPath);

package/dist/storage/state-db-integrity.js

@@ -7,7 +7,7 @@
  *
  * `akm health`'s `state-db-integrity` check (src/commands/health/checks.ts)
  * is a pure projection like every other check, so the actual IO lives here:
- * a read-only `PRAGMA quick_check` and a read-only freelist/page-count read.
+ * a read-only `PRAGMA integrity_check` and a read-only freelist/page-count read.
  * Both open their own short-lived read-only connection via the plain
  * {@link openDatabase} opener rather than `openStateDatabase`
  * (src/core/state-db.ts), since a corrupt database must not need a clean
@@ -27,8 +27,8 @@
 import { appendEvent } from "../core/events.js";
 import { openDatabase } from "./database.js";
 import { applyReadonlyPragmas } from "./sqlite-pragmas.js";
-/** How many corruption errors `PRAGMA quick_check` collects before it stops scanning and returns. */
-const QUICK_CHECK_ERROR_LIMIT = 10;
+/** How many corruption errors `PRAGMA integrity_check` collects before it stops scanning and returns. */
+const INTEGRITY_CHECK_ERROR_LIMIT = 10;
 /**
  * Above this fraction of free pages, `state-db-integrity` warns, and
  * {@link vacuumIfReclaimable} compacts state.db (after improve's retention
@@ -48,16 +48,19 @@ function openReadonlyStateDb(dbPath) {
     return db;
 }
 /**
- * Run `PRAGMA quick_check(N)` against `dbPath` read-only. Sub-second on a
- * healthy multi-hundred-MB file; on a corrupt one, `N` bounds how many errors
- * SQLite collects before it stops scanning, which keeps the check's runtime
- * bounded even against a badly corrupt file.
+ * Run `PRAGMA integrity_check(N)` against `dbPath` read-only. Unlike
+ * `quick_check`, it also verifies every index against its table ("row N
+ * missing from index", "wrong # of entries in index"): the damage a WAL
+ * deleted under a live connection leaves behind, which `quick_check` reports
+ * as `ok`. Sub-second on a healthy state.db of a few hundred MB; on a corrupt
+ * one, `N` bounds how many errors SQLite collects before it stops scanning,
+ * which keeps the check's runtime bounded even against a badly corrupt file.
  */
-export function runStateDbQuickCheck(dbPath) {
+export function runStateDbIntegrityCheck(dbPath) {
     let db;
     try {
         db = openReadonlyStateDb(dbPath);
-        const rows = db.prepare(`PRAGMA quick_check(${QUICK_CHECK_ERROR_LIMIT})`).all();
+        const rows = db.prepare(`PRAGMA integrity_check(${INTEGRITY_CHECK_ERROR_LIMIT})`).all();
         const lines = rows.map((row) => String(firstColumn(row)));
         const ok = lines.length === 1 && lines[0] === "ok";
         return { ok, lines };

package/dist/tasks/run/load-task.js

@@ -107,7 +107,11 @@ export async function loadPreparedTask(id, options) {
                 return { file: await resolveAssetPath(bundleDir, type, name), bundleRoot: bundleDir };
             }
             const resolutionConfig = requiresCommandConfig ? config : loadConfig();
-            const resolvedBundle = resolveWriteTarget(resolutionConfig, bundle, { requireWritable: false });
+            // `bundle` is the qualifier of an asset ref in the task, not a flag.
+            const resolvedBundle = resolveWriteTarget(resolutionConfig, bundle, {
+                requireWritable: false,
+                flag: "The asset ref's bundle",
+            });
             return {
                 file: await resolveAssetPath(resolvedBundle.source.path, type, name),
                 bundleRoot: resolvedBundle.source.path,

package/docs/migration/README.md

@@ -6,6 +6,7 @@ Upgrade guides and per-release migration notes.
 - [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) -- 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.9.19 release note](release-notes/0.9.19.md) -- `akm improve` scoped to the bundle it writes to (scheduled runs need one `--bundle` run per other bundle), `akm proposal reopen` and the retire-proposal diff, and fewer repeat consolidate promotions
 - [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.19.md

@@ -0,0 +1,134 @@
+Migration notes for akm v0.9.19
+
+Nothing has to run after upgrading from 0.9.18: 0.9.19 adds no config keys,
+changes no index layout, adds no state.db migration and leaves scheduler rows
+alone. (0.9.18 asked nothing either. From 0.9.16 or earlier, also read the
+0.9.17 note: akm help migrate 0.9.17.) What changes is which bundle akm
+improve works on, how a rejected proposal is undone, what consolidation and
+distill queue for review, and what akm proposal diff shows for a retirement.
+
+akm improve now improves one bundle: the one it writes to, which is --bundle
+when you pass it, else defaultWriteTarget, else your working bundle
+(AKM_BUNDLE_DIR when set, otherwise defaultBundle). Through 0.9.18 a run also
+picked assets out of your other writable bundles, read each one from the
+bundle that owned it, and filed the proposal in its own write target, so an
+asset that lived elsewhere came back either as a new copy in the write target
+or as an edit of the write target's own copy made from the other bundle's
+text. That no longer happens, and a rewrite filed outside the bundle that
+owns its asset is now refused. If everything you improve lives in one bundle,
+nothing changes for you. If you improve more than one, this is the one action
+in the release: a scheduled akm improve, the shipped akm-improve tasks
+included, now covers only its write target, so add one akm improve --bundle
+run for each other bundle you want improved:
+
+akm task add improve-team --schedule "15 3 * * *" \
+  --command "akm improve --bundle team --skip-if-locked --require-engines"
+
+(The --bundle inside the command string is akm improve's own; the --bundle of
+akm task add itself picks which bundle stores the task.) akm improve skills/x
+for an asset that lives only in another bundle now fails with a not-found
+error whose hint names that bundle, and akm improve team//skills/x works.
+Proposals an older run already queued stay in the queue, so review them with
+akm proposal list: one that creates an asset you already have in another
+bundle, or overwrites this bundle's copy with the other's text, is one of
+those. akm improve --dry-run and --plan now preview the bundle a live run
+improves; with no --bundle or defaultWriteTarget, a dry run used to read
+defaultBundle while a live run started from AKM_BUNDLE_DIR.
+
+A rejection is no longer final. akm proposal reopen <id> [<id> ...] puts
+rejected proposals back to pending and keeps each rejection in the proposal's
+reviewHistory, which akm proposal show prints; a proposal_reopened event goes
+into akm log. Reopen refuses a proposal that is not rejected or whose target
+changed since it was created, by the same rule accept applies: an update needs
+its target unchanged, a create needs the target still absent, and a retire
+proposal needs its successor present and both documents unchanged. It also
+refuses a retire proposal while another pending retire proposal involves
+either of its documents. Given several ids it reopens all of them or none and
+lists every refusal. It takes full ids, since a prefix only matches pending
+proposals (an asset ref works too, for the newest proposal on it while none
+is pending, but never for a retire proposal). The age that retention expiry
+and --older-than see starts over at the reopen, so a scheduled sweep does not
+take a proposal you just put back.
+
+The case that matters most is consolidate's retire proposals. Through 0.9.18,
+akm proposal diff drew a retirement as the file replaced by one blank line,
+so a correct retirement could pass for data loss. One reviewer rejected all
+65 of a bundle's retire proposals that way, and each rejection also kept the
+pair pass from proposing that retirement again while both documents stayed
+unchanged. To take them back, check each rejection's reason (akm proposal
+list --status rejected --generator consolidate-pair --detail normal --format
+json shows it as review.reason) and reopen only those rejected over the diff,
+one id at a time so a refusal skips only that one (the pattern matches the
+reason given here; change it to yours):
+
+akm proposal list --status rejected --generator consolidate-pair \
+  --detail normal --format json \
+  | jq -r '.proposals[] | select(.review.reason // "" | test("blank line"))
+      | .id' \
+  | xargs -r -n 1 akm proposal reopen --reason "diff was misrendered"
+
+A proposal refused because another pending retire proposal involves the same
+document can be reopened once that one is decided. A pair whose documents
+changed after the rejection needs no recovery, because the old rejection only
+held while both were unchanged and the pair pass may judge it afresh. Reopened
+retire proposals wait for you like any other. drain never accepts a retire
+proposal, so read each with akm proposal diff and accept or reject it.
+
+akm proposal diff now draws a retirement as one. The text output has a retire
+header, the pair's verdict (label, reason, and continuity risk when the pair
+was flagged), a note that accept archives the file and revert restores it byte
+for byte, and then only the removed lines under a
++++ /dev/null (retired: archived; successor <ref>) line. In JSON, a retire
+proposal's diff result gains op ("delete"), retirement (retiredRef,
+successorRef, judgeLabel, judgeReason, cosine, and continuityRisk when flagged)
+and note; the diff result of every other proposal is unchanged. A script that
+matched the old "(update: ...)" header on a retire proposal should expect
+"(retire: ...)". akm proposal show --detail full no longer ends a retire
+proposal with an empty payload heading, and a reopened proposal's JSON gains
+reviewHistory.
+
+Consolidation queues fewer repeat promotions. Before it queues a memory as a
+knowledge proposal, it compares the memory with the 20 knowledge docs in its
+bundle nearest to it by stored vector, and skips it, with skip reason
+dedup_covered_by_knowledge, when one of them already holds at least half of
+the memory's distinct 5-word runs. That needs stored vectors: with semantic
+search off the check does nothing and only the exact slug and whole-body
+checks apply. A memory whose promotion was accepted or rejected is now offered
+again only when its body changes (frontmatter edits do not count); it used to
+come back at once after an accept and after 7 days after a rejection. A
+decision an older release recorded has no body hash to compare and keeps
+those old windows. Expect a shorter promotion queue, with the skipped
+memories showing up as skip reasons and warnings in the run's result; to have
+a memory considered again, edit its text.
+
+Three changes keep a tool failure recorded as feedback from becoming a lesson
+about the error or a TODO placeholder in a memory. Reflect's feedback caveat no
+longer offers a TODO: verify placeholder: when feedback asks for something the
+asset lacks, reflect is told to leave the section unchanged. TODO lines earlier
+runs already put in your assets stay until you remove them; grep -rniE
+"TODO:? *verify" over the bundle finds them. Distill's quality judge now also
+scores whether a lesson is about what its source is about, and a lesson judged
+off-subject is dropped as quality_rejected (a ledger row and a distill_invoked
+event, no proposal) instead of passing or waiting in the queue as
+review_needed; the judge also reads the same first 3000 characters of the
+source body, without frontmatter, that the generator saw. The shipped agent
+guidance changed with it: akm help agents now says to record feedback about an
+asset's content, that it helped or turned out wrong, stale or unhelpful, and
+not a failed akm command such as akm show erroring, and akm feedback --help
+says the same of --reason. If you pasted that guide into an AGENTS.md or a
+system prompt, regenerate the block: the old text told agents to record
+--negative "when it fails".
+
+Downgrading to 0.9.18 needs no data change, since no schema moved, but it
+brings some of this back. 0.9.18 does not know reviewHistory: a proposal
+reopened under 0.9.19 reads as an ordinary pending proposal, and 0.9.18 drops
+its history if it rewrites the row (accepting or rejecting it, say). It also
+counts a pending proposal's age from its creation, so a reopened proposal can
+be expired by the next akm improve run (retire proposals never expire) or
+swept by a scheduled accept, reject or drain with --older-than. It does not
+hold a promoted memory either: 0.9.19 records a decided promotion with the
+memory's body hash and no retry time, which 0.9.18 reads as eligible now, so
+those memories go back to consolidation on the next run, a rejected one
+sooner than the 7 days 0.9.18 would have waited. Its improve plans assets
+from every writable bundle again, and its akm proposal diff draws a
+retirement as a blank replacement again.

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

@@ -7,6 +7,11 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
+- [0.9.19](0.9.19.md) — `akm improve` planning only the bundle it writes to
+  (a scheduled run needs one `--bundle` run per other bundle),
+  `akm proposal reopen` and the retire-proposal diff, consolidate's coverage
+  check and content-driven hold on decided promotions, distill's grounding
+  check, and what a downgrade to 0.9.18 undoes
 - [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,

package/docs/migration/v0.7-to-v0.8.md

@@ -988,7 +988,7 @@ akm-migrate storage --dry-run
 and look for import warnings. You can also inspect `state.db` directly:
 
 ```sh
-sqlite3 ~/.local/share/akm/state.db 'SELECT COUNT(*) FROM events;'
+sqlite3 -readonly ~/.local/share/akm/state.db 'SELECT COUNT(*) FROM events;'
 ```
 
 **`akm list` shows empty stashes.**
@@ -1039,7 +1039,7 @@ If you need to roll back to 0.7.x:
    wrote new events on 0.8.0 and need them in 0.7.x, export them:
 
    ```sh
-   sqlite3 ~/.local/share/akm/state.db \
+   sqlite3 -readonly ~/.local/share/akm/state.db \
      "SELECT json_object('schemaVersion', schema_version, 'ts', ts, 'eventType', event_type, 'ref', ref, 'metadata', json(metadata)) FROM events ORDER BY id;" \
      >> ~/.cache/akm/events.jsonl
    ```

package/docs/migration/v0.8-to-v0.9.md

@@ -140,7 +140,11 @@ paths (same-filesystem rename, or copy-then-delete across filesystems). A
 lock file is only ever deleted once the same staleness check `akm improve`
 itself uses says its holder is dead; a lock a live run still holds (or one
 this process cannot read) is left in place and reported instead. The whole
-step is idempotent — a second run reports nothing pending.
+step is idempotent — a second run reports nothing pending. 0.9.17-alpha.4
+removed that step: `akm migrate` no longer relocates these files, and one left
+at an old path is inert (nothing reads it). Two of the five writers no longer
+exist either — the improve ledger replaced `distill-rejected/`, and the
+write-only `eval-cases/` path was removed.
 `$STASH/.akm/memory-cleanup/` did not move; it is the one confirmed exception
 to the rule (see Storage locations, above).