akm-cli 0.9.0-rc.2 → 0.9.0-rc.4

package/CHANGELOG.md

@@ -8,6 +8,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Explicit, crash-resumable 0.9 migration coordination.** `akm migrate
+  status` classifies config, `state.db`, and `workflow.db` independently;
+  `akm migrate apply [--config <prepared>]` creates a verified,
+  installation-scoped backup before sealing ledgers or applying pending
+  migrations. Apply and restore use authenticated phase journals, exact
+  artifact fingerprints, bounded streaming I/O, SQLite integrity checks,
+  active-writer barriers, WAL/SHM-safe publication, and idempotent recovery.
+  Routine reads and current database opens no longer depend on a historical
+  cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
 - **Workflow orchestration engine (experimental).** akm can now execute
   multi-step workflows as deterministic **YAML programs**, driven either by a
   native engine or by any agent session. This is a new, self-contained
@@ -283,17 +292,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   but never written — their citing files are reported in `readOnlyCiters` as
   manual follow-ups. Output:
   `{ok, from, to, rewrote: [{file, count}], readOnlyCiters, utilityPreserved}`;
-  a successful move appends an `mv` event. The operation spans FS + DB and is
-  not transactional, but its ordering (plan rewrites → apply citer edits →
-  rename last → re-key index last) makes an interrupted run safely
-  re-runnable; with no local index built, the rename still succeeds and the
-  next `akm index` picks it up, and `utilityPreserved: false` discloses when
-  an existing index could not be re-keyed (the ranking history then resets
-  on the next full index). Added to the v1 §9.4 command surface as an
-  Experimental-tier additive entry (see `STABILITY.md`).
+  a successful move appends an exactly-once `mv` event. A durable mutation
+  journal stages citer rewrites and the asset publication, preserves
+  source-qualified utility/salience history, and resumes index/state
+  finalization after interruption. Divergent citers and late-created targets
+  fail closed instead of being overwritten. Added to the v1 §9.4 command
+  surface as an Experimental-tier additive entry (see `STABILITY.md`).
 
 ### Changed
 
+- **Improve target identity is now end-to-end and source-qualified.** Explicit
+  targets govern reads, generated proposals, triage promotion, consolidation,
+  retrieval signals, cooldowns, and replay state. Duplicate bare refs in other
+  sources no longer affect the selected corpus. Generated lessons and
+  provenance follow stash placement conventions and canonical `xrefs`.
+- **Writable Git boundaries commit only operation-owned paths.** Improve,
+  proposal, supersedes, and direct write flows preserve unrelated staged or
+  dirty work, including files beside generated assets in `content/` layouts.
+
 - **Directory (scope/domain) tokens now always merge into `tags` at index
   time**, even when an asset sets explicit `tags:` frontmatter. Previously
   explicit tags suppressed all path-derived tags, so a nested asset like
@@ -334,6 +350,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **Proposal promotion, reversion, and rejection are durable and recoverable.**
+  Acceptance and reversion persist target ownership and content fingerprints,
+  publish atomically across filesystem layouts, index immediately, commit exact
+  Git paths, and emit idempotent lifecycle events. Crash recovery and legacy
+  accepted proposals fail closed on ambiguous targets instead of clobbering
+  another source.
+- **Engine/setup/health behavior now matches the effective improve plan.**
+  Built-in strategies compose over one baseline, setup preserves independent
+  general and LLM defaults, native OpenCode SDK execution does not require an
+  unused fallback, and health checks each enabled process and credential.
 - **Check-in directives now survive plain-text output and `workflow
   status`** (check-in review C2/M1): `formatWorkflowNextPlain` and
   `formatWorkflowStatusPlain` render the `CONTINUE` directive, and every
@@ -1208,14 +1234,16 @@ proposal and log storage, `--format html` output, and per-stage LLM telemetry.
 
 ### Added
 
-- **Cross-runtime: akm now runs on Node.js (≥ 20) in addition to Bun** (#560,
+- **Cross-runtime: akm now runs on Node.js >= 20.12 in addition to Bun** (#560,
   #465). A two-file runtime boundary (`src/storage/database.ts` owns SQLite via
   `bun:sqlite` on Bun / `better-sqlite3` on Node; `src/runtime.ts` owns every
   `Bun.*` API) contains all runtime-specific code, enforced by a lint guard so it
   cannot leak back out. A CI `node-smoke` matrix runs the built CLI under Node
-  20 and 22. **Minimum Node is 20** — the prompts dependency (`@clack/core`) uses
-  `node:util.styleText`, added in Node 20.12; Node 18 is EOL and unsupported.
-  Bun remains the primary/default runtime.
+  20 and 22. The prompts dependency (`@clack/core`) uses `node:util.styleText`,
+  added in Node 20.12; Node 18 is EOL and unsupported. The npm package uses Node
+  as its bootstrap and prefers a working Bun >= 1.0 for execution when both are
+  available. Old, unusable, or absent Bun installations fall back to Node.js;
+  standalone binaries remain runtime-free.
 - **`session` asset type — agent sessions are now searchable** (#561). The
   `extract` pass, after distilling memory proposals from a session, additionally
   writes the session itself as a first-class `session` asset

package/README.md

@@ -24,13 +24,7 @@ curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh |
 irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
 ```
 
-**Option 2 — Bun (requires [Bun](https://bun.sh) >= 1.0):**
-
-```sh
-bun install -g akm-cli
-```
-
-**Option 3 — Node.js (requires Node.js >= 20.12):**
+**Option 2 — npm package (requires [Node.js](https://nodejs.org) >= 20.12):**
 
 ```sh
 npm install -g akm-cli
@@ -38,7 +32,12 @@ npm install -g akm-cli
 
 Upgrade in place with `akm upgrade`.
 
-> **AKM 0.9.0 supports three install paths:** prebuilt binary, Bun, or Node.js >= 20.12.
+The npm package always uses Node.js to bootstrap its cross-platform command.
+If a working [Bun](https://bun.sh) >= 1.0 is also on `PATH`, the launcher
+prefers Bun for execution; old, unusable, or absent Bun installations fall back
+to Node.js. Node.js remains required for the npm package. The standalone
+binaries are runtime-free.
+
 > The old `vault` asset type was removed in 0.9.0; use `env` for whole `.env`
 > groups and `secret` for standalone sensitive values.
 

package/SECURITY.md

@@ -82,9 +82,11 @@ containing secrets or private notes.
 
 ## Known non-issues
 
-- **`akm` requires Bun, Node.js >= 20.12, or the prebuilt binary.** Older
-  Node.js versions are unsupported because required runtime APIs are missing.
-  This is a compatibility limitation, not a security risk.
+- **The `akm-cli` npm package requires Node.js >= 20.12 as its bootstrap.** A
+  working Bun >= 1.0 is preferred for execution when it is also on `PATH`; old,
+  unusable, or absent Bun installations fall back to Node.js. Bun does not
+  remove the package's Node.js requirement. Standalone binaries are
+  runtime-free. This is a compatibility limitation, not a security risk.
 - **Workflows can read any file the akm process can read.** This is not a
   bug — see "Threat model" above.
 - **Installing `akm-cli` runs the preinstall hook.** The hook only validates

package/dist/akm

@@ -1,38 +1,49 @@
-#!/bin/sh
-# 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/.
+#!/usr/bin/env node
+// 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/.
 
-case "$0" in
-	*/*) SCRIPT_PATH=$0 ;;
-	*)
-		SCRIPT_PATH=$(command -v -- "$0" 2>/dev/null || true)
-		if [ -z "$SCRIPT_PATH" ]; then
-			echo "akm launcher could not resolve its own path." >&2
-			exit 127
-		fi
-		;;
-esac
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
-if command -v readlink >/dev/null 2>&1; then
-	while [ -L "$SCRIPT_PATH" ]; do
-		LINK_TARGET=$(readlink "$SCRIPT_PATH")
-		case "$LINK_TARGET" in
-			/*) SCRIPT_PATH=$LINK_TARGET ;;
-			*) SCRIPT_PATH=${SCRIPT_PATH%/*}/$LINK_TARGET ;;
-		esac
-	done
-fi
+if (!process.versions.bun) {
+  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+  if (major < 20 || (major === 20 && minor < 12)) {
+    console.error("The akm-cli npm package requires Node.js >= 20.12 to bootstrap.");
+    process.exit(1);
+  }
+}
 
-SCRIPT_DIR=$(CDPATH= cd -- "${SCRIPT_PATH%/*}" && pwd)
+const bunProbe = process.versions.bun
+  ? { status: 0, stdout: process.versions.bun }
+  : spawnSync("bun", ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    });
+const [bunMajor = 0] = (bunProbe.status === 0 ? bunProbe.stdout.trim() : "").split(".").map(Number);
+const useBun = bunMajor >= 1;
+const bunEntry = fileURLToPath(new URL("./cli.js", import.meta.url));
+const nodeEntry = fileURLToPath(new URL("./cli-node.mjs", import.meta.url));
 
-if command -v bun >/dev/null 2>&1; then
-	exec bun "$SCRIPT_DIR/cli.js" "$@"
-fi
+if (!useBun && !process.versions.bun) {
+  await import("./cli-node.mjs");
+} else {
+  const command = useBun ? (process.versions.bun ? process.execPath : "bun") : "node";
+  const entry = useBun ? bunEntry : nodeEntry;
+  const runtime = useBun ? "Bun" : "Node.js";
+  const result = await new Promise((resolve) => {
+    const child = spawn(command, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+    child.once("error", (error) => resolve({ error }));
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
 
-if command -v node >/dev/null 2>&1; then
-	exec node "$SCRIPT_DIR/cli-node.mjs" "$@"
-fi
-
-echo "akm requires Bun or Node.js >= 20.12.0 on PATH." >&2
-exit 127
+  if (result.error) {
+    console.error(`akm launcher could not start ${runtime}: ${result.error.message}`);
+    process.exitCode = 127;
+  } else if (result.signal) {
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exitCode = result.code ?? 1;
+  }
+}

package/dist/akm-migrate-storage

@@ -1,38 +1,49 @@
-#!/bin/sh
-# 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/.
+#!/usr/bin/env node
+// 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/.
 
-case "$0" in
-	*/*) SCRIPT_PATH=$0 ;;
-	*)
-		SCRIPT_PATH=$(command -v -- "$0" 2>/dev/null || true)
-		if [ -z "$SCRIPT_PATH" ]; then
-			echo "akm-migrate-storage launcher could not resolve its own path." >&2
-			exit 127
-		fi
-		;;
-esac
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
-if command -v readlink >/dev/null 2>&1; then
-	while [ -L "$SCRIPT_PATH" ]; do
-		LINK_TARGET=$(readlink "$SCRIPT_PATH")
-		case "$LINK_TARGET" in
-			/*) SCRIPT_PATH=$LINK_TARGET ;;
-			*) SCRIPT_PATH=${SCRIPT_PATH%/*}/$LINK_TARGET ;;
-		esac
-	done
-fi
+if (!process.versions.bun) {
+  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+  if (major < 20 || (major === 20 && minor < 12)) {
+    console.error("The akm-cli npm package requires Node.js >= 20.12 to bootstrap.");
+    process.exit(1);
+  }
+}
 
-SCRIPT_DIR=$(CDPATH= cd -- "${SCRIPT_PATH%/*}" && pwd)
+const bunProbe = process.versions.bun
+  ? { status: 0, stdout: process.versions.bun }
+  : spawnSync("bun", ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    });
+const [bunMajor = 0] = (bunProbe.status === 0 ? bunProbe.stdout.trim() : "").split(".").map(Number);
+const useBun = bunMajor >= 1;
+const bunEntry = fileURLToPath(new URL("./scripts/migrate-storage.js", import.meta.url));
+const nodeEntry = fileURLToPath(new URL("./migrate-storage-node.mjs", import.meta.url));
 
-if command -v bun >/dev/null 2>&1; then
-	exec bun "$SCRIPT_DIR/scripts/migrate-storage.js" "$@"
-fi
+if (!useBun && !process.versions.bun) {
+  await import("./migrate-storage-node.mjs");
+} else {
+  const command = useBun ? (process.versions.bun ? process.execPath : "bun") : "node";
+  const entry = useBun ? bunEntry : nodeEntry;
+  const runtime = useBun ? "Bun" : "Node.js";
+  const result = await new Promise((resolve) => {
+    const child = spawn(command, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+    child.once("error", (error) => resolve({ error }));
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
 
-if command -v node >/dev/null 2>&1; then
-	exec node "$SCRIPT_DIR/migrate-storage-node.mjs" "$@"
-fi
-
-echo "akm-migrate-storage requires Bun or Node.js >= 20.12.0 on PATH." >&2
-exit 127
+  if (result.error) {
+    console.error(`akm-migrate-storage launcher could not start ${runtime}: ${result.error.message}`);
+    process.exitCode = 127;
+  } else if (result.signal) {
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exitCode = result.code ?? 1;
+  }
+}

package/dist/assets/backends/schtasks-template.xml

@@ -3,6 +3,8 @@
   <RegistrationInfo>
     <Description>akm scheduled task: {{TASK_ID}}</Description>
     <URI>{{FOLDER}}{{TASK_ID}}</URI>
+    <Source>{{SIGNATURE}}</Source>
+    <Documentation>Log target (informational only; schtasks doesn't redirect): {{LOG_PATH}}</Documentation>
   </RegistrationInfo>
   <Triggers>
 {{TRIGGER_XML}}
@@ -25,5 +27,4 @@
       <Arguments>{{ARGS}}</Arguments>
     </Exec>
   </Actions>
-  <!-- Log target (informational only; schtasks doesn't redirect): {{LOG_PATH}} -->
 </Task>

package/dist/assets/improve-strategies/catchup.json

@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
-    "triage": { "enabled": true, "applyMode": "queue", "policy": "personal-stash", "maxAcceptsPerRun": 100 }
+    "triage": { "enabled": true, "applyMode": "queue", "policy": "personal-stash", "maxAcceptsPerRun": 100 },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/consolidate.json

@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/frequent.json

@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": true },
     "extract": { "enabled": true, "minNewSessions": 3, "triage": { "enabled": true, "minScore": 2 } },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/graph-refresh.json

@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": true, "fullScan": true },
     "extract": { "enabled": false },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/memory-focus.json

@@ -6,7 +6,10 @@
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": false },
-    "triage": { "enabled": false }
+    "extract": { "enabled": false },
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/proactive-maintenance.json

@@ -10,6 +10,7 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
+    "validation": { "enabled": false },
     "triage": {
       "enabled": true,
       "applyMode": "promote",

package/dist/assets/improve-strategies/quick.json

@@ -10,7 +10,9 @@
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/recombine-only.json

@@ -8,6 +8,8 @@
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
     "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false },
     "recombine": {
       "enabled": true,
       "minClusterSize": 3,

package/dist/assets/improve-strategies/reflect-distill.json

@@ -15,6 +15,7 @@
       "triage": { "enabled": true, "minScore": 2 },
       "minNewSessions": 1
     },
+    "validation": { "enabled": false },
     "triage": {
       "enabled": true,
       "applyMode": "promote",

package/dist/assets/improve-strategies/synthesize.json

@@ -8,6 +8,8 @@
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
     "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false },
     "recombine": { "enabled": true },
     "procedural": { "enabled": false }
   },

package/dist/assets/tasks/core/backup.yml

@@ -1,5 +1,5 @@
 version: 2
 schedule: "0 3 * * 0"
 command: akm db backups
-enabled: true
-description: Weekly config/DB backup
+enabled: false
+description: Disabled until akm provides a general recurring backup command