akm 0.9.9 × openpalm 0.13.2 — coordinated release plan

Status: proposed 2026-09-02. Branches: itlackey/akm release/0.9.9, itlackey/akm-plugins main (release workflow), itlackey/openpalm release/0.13.2. Work is done by Sonnet agents in isolated worktrees, reviewed and committed by the coordinator, and lands only on those branches.

1. The problem, from the top

Every failure in the last two OpenPalm upgrades traces to one shape: akm's migration was reachable only through machinery a bundled install could not run, so the bundler grew machinery of its own to reach around it — a --state-only helper, a grep on akm's error text, a boot marker vocabulary, a "never apply on boot" policy with its own docs — and each piece pinned a detail of akm that then moved.

openpalm 0.13.1 today                       akm 0.9.8
─────────────────────────────────────       ──────────────────────────────
akm migrate status ─ parse .status ─┐       state migration refused on open
  "ready"  → do nothing, log nudge  │       remedy: upgrade --force (npm -g)
  exit 1   → migrate apply ×2       │       or upgrade --state-only (0.9.8)
akm health ─ grep "upgrade --force" ─┼─►    health exits 78 on pending state
  → marker "state-upgrade-pending"  │
openpalm-akm-state-upgrade helper ──┘       (operator runs it by hand)

The fix is not more coordination. It is one contract, small enough to state in three lines, that any bundler (OpenPalm, a plugin's node_modules, a Docker image, a global npm install, a compiled binary) can follow without knowing anything else about akm:

Pin an exact akm-cli version and install it however you install things.
At boot, run akm migrate apply (or akm upgrade, which runs it). It is offline, idempotent, takes its own safety copies, prints one JSON plan, and exits 0 unless a file is genuinely blocked.
Read akm health --format json. Never grep error text.

Everything below either moves akm toward that contract or deletes OpenPalm machinery the contract makes unnecessary. Default is subtraction; every addition is named and justified.

2. What is already on `release/0.9.9`

akm-migrate runs every migration in one plan (config lift, state.db including 018 with the safety copy, task v2→v3→v4, residue sweeps). akm migrate wraps it; the per-generation verbs are gone.
akm upgrade runs akm-migrate apply after its install step on every run, and still runs it when the install fails or when there is nothing to install. --state-only is removed.
installMethod: "package-local" — an akm living in another package's node_modules is never npm install -g'd over (the databasin report).
Ordinary-open refusal text names akm upgrade / akm migrate apply.
Compiled-binary fix: the embedded migrator ran twice per invocation.

3. akm 0.9.9 — remaining scope

#	Item	Kind	Notes
A1	`akm health` reports pending state migrations as a check, not a crash	add (small)	New hard check `state-db-migrations`: `fail` with `pending: [ids]` and the remedy `akm migrate apply`; health exits its normal fail code, not 78 from a thrown open. Read-only via `listPendingStateMigrations`. This is what replaces OpenPalm's grep.
A2	#906 `task sync` `failures` vs `failed`	subtract	One key, `failures`, in both shapes. No alias — the only downstream reader already does `failures ?? failed`.
A3	#910 misleading `crontab` error under supercronic	fix	`crontab -l` exit 1 with empty/"no crontab" output is an empty crontab (that is cron's own contract), not a missing binary. Distinguish ENOENT from a non-zero exit; word the ENOENT case for a missing binary only. Investigate whether OpenPalm's shim needs anything else.
A4	#908 mixed-layout bundle auto-detects `agent-skills` and drops 73 docs	fix	Mixed layout detects as `akm` (the superset). `akm bundle list` reports `adapter` and `detected: true/false`. Warn once with a count when the chosen adapter skips top-level dirs that hold candidate files.
A5	#909 invalid adapter silently falls back	fix	Validate `components.*.adapter` against the registry: `INVALID_CONFIG_FILE` listing accepted names. Put the registry names in `akm bundle add --help` — no new subcommand.
A6	`task sync --rebind` warns every 60 s on an image-baked install (#868 residue)	subtract	A package-local invocation whose bound argv already equals the current one is steady state: no warning. Keep `--rebind` semantics; delete the nag.
A7	Bundling guide	docs	One page, `docs/integration/bundling-akm.md`: the three-line contract, the `migrate` plan shape, exit codes (`0` ok, `1` blocked, `4` health warn), the `package-local` rule, what `akm upgrade` does in an image. Retire the `--state-only`/`--force` prose everywhere else.
A8	Publish `0.9.9-beta.1`, then `0.9.9`	release	The beta exists so OpenPalm's pin smoke (which installs from npm) can run against the branch before either final.

Deferred, milestoned 0.10.0: #905 engine credentials (apiKeyFile), #907 single-file task validation. Both are additions; neither blocks the contract.

4. akm-plugins — one release

Regenerate opencode/bun.lock against akm-cli@0.9.9, dispatch the release workflow with akm_version: 0.9.9. No code change: ^0.9.8 already admits 0.9.9 and the plugin uses no removed surface. OpenPalm pins the resulting akm-opencode@0.9.9<stamp>.

5. openpalm 0.13.2 — scope

5a. Adopt the contract (subtract)

#	Item	Delete	Keep / add
B1	Pins	—	`containers/assistant/tools/package.json`, paperclip manifest, `opencode.jsonc`, the hard-coded `0.9.8` in the manual runbook. The lockstep test already enforces the triple.
B2	Boot runs `akm migrate apply`	`migrate status` parse + jq vocabulary, the `ready` branch and its "operator-apply-pending" policy, the double-apply retry, `grep -qF 'Run \`akm upgrade --force`'`,` state-upgrade-pending`,` openpalm-akm-state-upgrade` + its Dockerfile COPY, the docs sections and tests that pin each of these	`run_akm_migration_check` becomes: `akm migrate apply` → marker `migrate <rc> [blocked: n]` (blockers logged from the plan JSON) → `akm task sync --rebind` → `akm health`. Health degraded iff exit ∉ {0,4}, unchanged.
B3	Policy reversal, decide explicitly: boot converts operator task files to v4	the 0.13.0 promise "tasks you wrote yourself are left exactly as they are"	akm backs every rewritten file up (`/backups/task-v3
B4	#666 stale `tools/` volume runs akm 0.8.14 against a 0.9 config	—	Fail fast at boot: `akm --version` ≠ the pin in `/opt/openpalm/tools/package.json` → marker `akm-version <got> expected <pin>` + one log line naming the stale mount. Upgrade path: `reapRetiredVolumes` already runs; investigate why that host still mounted `_assistant-artifacts` (custom compose vs. old project prefix) and close that hole with the least code.

5b. Update robustness (0.13.2 milestone, openpalm-internal)

#	Issue	Approach
B5	#662 CLI older than the stack it manages	Minimum viable: `openpalm update` refuses when the CLI is older than the target release, names `openpalm self-update`, `--allow-version-skew` to override. Not the re-exec design — that is more machinery than the hole needs.
B6	#667 exit 0 after failed upgrade + failed rollback	Non-zero exit and a final state line.
B7	#669 failed rollback keeps migrated `state.env` and relocated secrets	Rollback restores the whole generation or reports exactly what it could not.
B8	#664 refused update burns a rollback generation	Refuse before writing the generation.
B9	#668 `--remove-orphans` deletes a running non-listed service	Never pass `--remove-orphans` for services outside the managed set, or list what would be removed and refuse.
B10	#670 `OP_WORKSPACE_PORT` has no migration entry	Add the migration entry; verify the sibling-instance case.
B11	#671 `validate` on a pre-0.13 home: unhelpful message	Name the layout and the command that migrates it.
B12	#663 secret-audit remediation text is wrong; shipped `akm-improve` has no credential route	Fix the text (point at `akm env run`), state that in-process plugin credentials are unsupported until akm#905, ship `akm-improve.yml` with the `akm env run` wrapper documented.
B13	#665 Slack keepalive `undici.ping`	Bug fix; unrelated to akm.
B14	#672, #673	Test-lane port override; AppImage `--version`. Small.
B15	#634 manual acceptance lane	Process item for the maintainer; not agent work.

6. Release order and gates

akm release/0.9.9: A1–A7 land as reviewed commits. Gate: lint, tsc, unit + integration, tests/release-check.sh --skip-docker, the three e2e smokes already scripted (source, dist/ launchers, compiled binary) against a ledger-017 state.db. Publish 0.9.9-beta.1 from the branch.
openpalm release/0.13.2: B1 pins to the beta, B2–B4, then B5–B14. Gate: bun test, scripts/akm-pin-integration-smoke.sh, scripts/upgrade-path-smoke.sh (Docker; run where Docker exists), rootless-ownership-smoke.sh. The pin smoke is the cross-repo gate: it installs the pinned akm from npm and drives the real boot contract.
akm merge to main, Release workflow → 0.9.9 on latest.
akm-plugins release workflow, akm_version: 0.9.9.
openpalm re-pin to 0.9.9 final + the new akm-opencode stamp, rerun the pin smoke, merge to main, Release workflow → 0.13.2.
Close every issue with the shipped version named; close both milestones.

7. Working agreement

One agent per row, in a worktree, with the issue text and this plan as its brief. It returns a diff and its evidence (which tests are red on the old code, green on the new).
The coordinator re-runs the tests, reads the diff adversarially, and either sends it back with specific changes or commits to the release branch and pushes. No agent pushes.
Subtract first. A row that ends with more lines than it started needs a sentence saying why the addition was the most correct option.