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

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

@@ -8,18 +8,109 @@ installation, then migrate the affected assets deliberately.
 
 ## Engine And Task Assets
 
-Before editing a 0.8 configuration, create a recovery bundle:
+The 0.8 binary does not contain `akm migrate` or the
+`upgrade --migration-config` contract. Do not attempt to invoke either command
+with 0.8, and do not use 0.8 self-update to cross this boundary.
+
+Use this package-manager/manual boundary procedure instead:
+
+1. Stop AKM writers, schedulers, and workflow drivers.
+2. Prepare the complete 0.9 config in a separate file. Do not replace the live
+   0.8 config; AKM cannot infer names when old LLM and agent profiles collide.
+3. Take an independent filesystem backup of the live 0.8 `config.json`,
+   `state.db`, and `workflow.db` (including any SQLite `-wal`/`-shm` files).
+   Store it outside AKM's data directory and verify it before continuing.
+4. Install 0.9 with the package manager, or download, checksum, and stage the
+   0.9 standalone binary. A package-manager install replaces the managed 0.8
+   package; a standalone operator should retain the old executable. Keep the
+   independent data backup in either case.
+5. Invoke the newly installed or staged 0.9 binary, whose migration startup
+   bypass can read the old installation without loading its config normally.
+6. After apply succeeds, run `akm tasks sync` with that same 0.9 binary and
+   inspect `skipped` before restarting schedulers. Sync registers the migrated
+   task view and quarantines the obsolete published backup task described below.
+
+Package-manager installation examples for step 4:
+
+Package-manager installs require Node.js >= 20.12. If Bun >= 1.0 is also on
+`PATH`, the installed launcher prefers Bun after Node.js bootstraps it.
 
 ```sh
-akm backup create --for 0.9.0
+npm install -g akm-cli@0.9.0
+# or: pnpm add -g akm-cli@0.9.0
 ```
 
-The immutable bundle is stored under `$CACHE/migration-backups/0.9.0`
-(`$XDG_CACHE_HOME/akm` by default on Linux). It records both present and absent files for
-`config.json`, `state.db`, and `workflow.db`, verifies every captured file by
-SHA-256, and is created automatically before AKM first opens either canonical
-durable database for the 0.9 engine migrations. Do not move individual files
-into or out of the bundle; verification fails closed on any mismatch.
+Commands for steps 5 and 6:
+
+```sh
+# Package-manager install: this `akm` is now the 0.9 binary.
+akm migrate status --config ./prepared-0.9.json
+akm migrate apply --config ./prepared-0.9.json --dry-run
+akm migrate apply --config ./prepared-0.9.json
+akm tasks sync
+
+# Or invoke a checksummed staged standalone binary explicitly.
+./akm-0.9 migrate status --config ./prepared-0.9.json
+./akm-0.9 migrate apply --config ./prepared-0.9.json
+./akm-0.9 tasks sync
+```
+
+Status and dry-run perform the same read-only eligibility checks and report the
+source config plus target config explicitly. Apply validates the target in
+memory, creates a verified recovery run, applies pending `state.db` and
+`workflow.db` migrations one transaction at a time, and atomically installs the
+prepared config last. If any later artifact fails, apply restores config and
+both databases from the verified run before returning. Each artifact is
+classified independently, so a current config with pre-cutover databases can be
+recovered safely.
+
+Apply records durable `prepared`, `state-applied`, `workflow-applied`,
+`config-applied`, `rollback-prepared`, and `committed` phases. Every phase stores
+streaming size/SHA fingerprints for config, both databases, and SQLite sidecars;
+a resume or rollback first requires the exact live generation. After a process
+crash, ordinary config and canonical database access fail closed; `akm migrate
+status` reports the pending phase and `akm migrate apply` resumes idempotently
+from the retained target and verified backup. Apply also refuses before backup
+while managed database handles, maintenance activities, AKM mutation locks, or
+workflow claims are live.
+
+Canonical state/workflow opens check for pending recovery both before and after
+registering their maintenance activity. Config writers perform the second check
+while holding the same config lock used by migration, closing the check/start
+race without recreating files or accepting a write.
+
+Each database mutation also writes an operation-specific generation marker in
+the migration transaction. If the process dies after the durable mutation but
+before advancing the apply journal, recovery accepts only that authenticated
+one-artifact adjacent generation while every unaffected fingerprint remains
+exact. Config adjacency is authenticated against the exact serialized target.
+If rollback restore commits before the apply journal is removed, the next apply
+authenticates the live files against the backup generation and removes only the
+stale apply journal.
+
+Once already running a contract-capable 0.9 release, future self-upgrades may
+pass a prepared target through the coordinated upgrade path:
+
+```sh
+akm upgrade --migration-config ./prepared-0.9.json
+```
+
+This command is not the 0.8-to-0.9 procedure. The already-installed 0.8 binary
+cannot contain or enforce safeguards added in 0.9, so operators must follow the
+manual boundary above rather than relying on 0.8 self-update. For 0.9+ upgrades,
+the current binary preflights only its current artifact state; it does not parse
+a prepared config for the future release. After installation, only the new
+binary receives `--config` during apply. If the active config is already current,
+no migration-config flag is needed.
+
+Recovery runs are stored under
+`$DATA/backups/migrations/<installation-id>/<run-id>/`. They record present and
+absent `config.json`, `state.db`, and `workflow.db` artifacts, ordered migration
+ledgers, sizes, and streaming SHA-256 hashes. SQLite snapshots must also pass
+`PRAGMA quick_check` and ledger-prefix validation before the manifest is
+published. `akm backup create --for 0.9.0` creates an additional unique run when
+an operator wants a manual snapshot. Routine config writes, telemetry, and
+already-current database opens do not depend on any historical run.
 
 Replace `profiles.llm.<name>` and `profiles.agent.<name>` with one
 `engines.<name>` map. Replace `defaults.llm`, `defaults.agent`, and
@@ -31,8 +122,10 @@ Replace `profiles.llm.<name>` and `profiles.agent.<name>` with one
 Do not reuse a colliding LLM and agent profile name without deciding which new
 engine names make the distinction clear. AKM cannot safely infer that choice.
 
-Task files are strict YAML v2. Add `version: 2`, replace prompt `profile:` with
-`engine:`, and retain only fields valid for the target:
+New task files use strict YAML v2. Existing valid 0.8 task files continue to
+load without being rewritten: AKM normalizes their missing/`1` version,
+prompt `profile:` field, permissive scalar forms, and `akm improve --profile`
+commands in memory. Update user-authored files to `version: 2` when editing them:
 
 ```yaml
 version: 2
@@ -46,11 +139,55 @@ enabled: true
 
 Prompt tasks may use `engine`, `model`, `timeoutMs`, and `llm`; command tasks
 may use `timeoutMs`; workflow tasks may use `params`. Unknown and wrong-target
-keys are errors. `akm tasks list`, `sync`, and `doctor` report stale v1 files;
-`show`, `run`, `enable`, and `disable` reject them without mutation. Regenerate
-the known default improve tasks or replace `akm improve --profile <name>` with
-`akm improve --strategy <name>` yourself. AKM never rewrites arbitrary shell
-commands.
+keys are errors in v2. Unsupported future versions are reported by `akm tasks
+list`, `sync`, and `doctor`. The 0.8 reader normalization changes only the
+removed AKM spellings; arbitrary shell commands and task files are never
+rewritten.
+
+For 0.8 command tasks, syntax migration and self-invocation routing are separate.
+`--profile` is lowered only for a PATH-selected bare `akm`/`akm.exe`, including
+when it follows supported `env` options and assignments. The scanner recognizes
+citty-valid global forms before `improve`, including `--no-quiet`,
+`--no-verbose`, `--quiet=false`, `--verbose=false`, and value options such as
+`--format json`. An explicit `./akm`, `/opt/vendor/akm`, or other executable path
+is operator-owned: it keeps selecting that exact binary and its command argv is
+retained exactly. In particular, AKM does not change syntax sent to a retained
+0.8 binary. Version-2 commands receive no compatibility rewriting.
+
+The published 0.8 core `backup.yml` is a special unsafe legacy definition. It
+was enabled and ran `akm db backups`, but that command only listed snapshots; it
+did not create a recurring backup. In 0.9, `tasks add` refuses the enabled exact
+bare-self command before changing its source file or scheduler. `tasks sync`
+reports it in `skipped`, does not install a missing entry, and disables an
+existing scheduler entry while preserving the task file byte-for-byte. `tasks
+enable` also refuses to re-enable it. This quarantine applies only when bare
+`akm`/`akm.exe` is followed by exactly `db backups`; an explicit executable path
+is operator-owned and is not quarantined. Use `akm backup create --for 0.9.0`
+for an explicit migration recovery snapshot. Existing 0.8 data-directory backup
+folders are left untouched by migration.
+
+Task `enabled` state controls scheduler-originated execution, not explicit
+operator invocation. `akm tasks run <id>` intentionally runs a disabled task so
+manual catch-up definitions remain useful. Backend-generated invocations carry
+the internal `--scheduled` marker and record a `disabled` result without running
+the target. Do not use the manual command as a scheduler replacement.
+
+Canonical task IDs contain only letters, digits, dots, underscores, and dashes,
+start with a letter or digit, are at most 228 characters, omit `.yml`/`.yaml`,
+and cannot use Windows device aliases such as `CON`, `NUL`, `COM1`, or `LPT1`
+(including aliases followed by a dot). The 228-character limit is the final
+portable bound after scheduler and filename overhead. These portability checks
+apply on every platform. For command-line compatibility only, a trailing
+lowercase `.yml` or legacy `.md` is stripped from an ID; a filename discovered
+under `tasks/` must already be canonical and is never renamed. Sync skips a
+non-portable file and disables any matching installed entry rather than guessing
+a replacement ID.
+
+Canonical migration preserves 0.8 `state.db` task-history rows and their log
+paths. One historical detail cannot be recovered: published 0.8.14 stored
+command-task history with `target_kind=prompt`. Because the durable row contains
+no command marker, 0.9 preserves and exposes it as legacy prompt history rather
+than inventing a command classification. New runs use the correct target kind.
 
 ## CLI rename table (old → new, removed 0.9.0)
 
@@ -374,19 +511,42 @@ workflow lease exists. Then, while still running the 0.9 binary, restore the
 complete pre-cutover snapshot:
 
 ```sh
-akm backup restore --for 0.9.0 --confirm
+akm backup restore --for 0.9.0 --run <run-id> --confirm
 ```
 
-Restore verifies the manifest, permissions, sizes, and checksums before
-replacing anything. It restores each original file and removes a canonical DB
-that the manifest recorded as originally absent, including its WAL/SHM
-sidecars. Restore also holds the global maintenance barrier from its last
-lock/lease check through replacement, so a new index writer, improve/extract
-lock, lockfile writer, or workflow engine lease cannot start in that window.
-The recovery bundle itself remains in `$CACHE` for repeatable recovery. If
-verification reports corruption, preserve the bundle and recover
-from an independent backup; do not delete the manifest or regenerate it from a
-post-cutover config.
+Restore verifies the selected run before changing live files and then creates a
+second verified rescue run of the current installation. It stages every
+replacement beside its destination, writes a durable restore journal,
+quarantines each database together with its WAL/SHM sidecars, and only then
+publishes clean staged files. The journal records a durable committed phase
+before cleanup: an earlier interruption rolls back, while an interruption after
+commit finishes cleanup without mixing generations. While either recovery phase
+is pending, ordinary config and canonical database access fail closed before
+accepting writes or recreating absent files. The selected and rescue runs remain
+under `$DATA`; if verification reports corruption, preserve them and recover
+from an independent backup.
+
+Recovery validates the complete restore journal before removing or renaming any
+path: journal format and migration version, phase, exact artifact and SQLite
+sidecar set, operation-bound stage/quarantine names, path uniqueness, source
+backup, and the expected prepared/committed filesystem state. A malformed or
+stale journal remains in place and recovery fails closed for operator diagnosis.
+Committed recovery additionally authenticates each published artifact against
+the selected backup's byte size and streaming SHA-256, then reruns config-state
+validation or SQLite `quick_check` and ledger validation before deleting any
+quarantine or journal.
+
+Prepared rollback is itself crash-idempotent. The journal fingerprints the
+original config/database/sidecar generation before quarantine. If recovery dies
+after restoring a quarantine or deleting a stage but before journal deletion,
+the next recovery authenticates the already-restored destination and continues
+cleanup. A same-ledger but byte-different substitution fails closed.
+
+Migration config files, manifests, and apply/restore journals are read through
+bounded readers (1 MiB each). Oversized local control files fail closed rather
+than being loaded wholesale. Apply also measures the complete serialized journal
+before its first write; a near-limit config whose expanded target would exceed
+the same cap is rejected before any apply journal or artifact mutation.
 
 Only after restore succeeds should you install the older AKM binary. A 0.8
 binary must not run against a 0.9 config or against `state.db` migration 017 /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.2",
+  "version": "0.9.0-rc.4",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -52,7 +52,7 @@
     "akm-migrate-storage": "dist/akm-migrate-storage"
   },
   "scripts": {
-    "preinstall": "node -e \"var ua=process.env.npm_config_user_agent||'';var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>20||(v[0]===20&&(v[1]>12||(v[1]===12&&v[2]>=0)));if(process.versions.bun||ua.startsWith('bun/')||process.env.BUN_INSTALL||ok){process.exit(0)}console.error('\\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh), Node.js >= 20.12, or the prebuilt binary.\\n  Install options:\\n    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\\n    2. Node:   upgrade to Node.js 20.12 or newer (https://nodejs.org)\\n    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>20||(v[0]===20&&(v[1]>12||(v[1]===12&&v[2]>=0)));if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 20.12.\\n  A working Bun >= 1.0 on PATH is optional and preferred for execution.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -94,7 +94,6 @@
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
-    "bun": ">=1.0.0",
     "node": ">=20.12.0"
   },
   "dependencies": {