This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Migrations

  • 1:
  • 2:

1 -

Lockfile schema bump v0.25.6 — what’s automatic, what to verify

aibox v0.25.6 extends aibox.lock with two new optional sections. The bump is fully automatic — aibox apply backfills the new fields on first run. No manual editing is required, and existing lockfiles remain valid (the new fields use #[serde(default)], so they are absent from old locks without causing parse errors).

What changed

cli/src/lock.rs adds:

  • AddonsLockSection::previous_selection (BTreeMap<String, BTreeSet<String>>) — records which tool names were enabled under each addon family at the time of the last apply. Written under [addons.previous_selection] in aibox.lock. Used on the next apply to compute a removal diff when a tool is disabled, so stale addon binaries baked into an earlier image layer can be purged cleanly.

  • [harnesses] section (HarnessLockSection) — records the set of AI harness names that were active (previous_selection: BTreeSet<String>) and the timestamp when the record was taken (recorded_at). Used by aibox apply to detect harnesses that were active last time but are no longer configured, enabling targeted cleanup of harness-specific state files (gated on [apply].purge_disabled_harness_state, default false).

Both fields are populated automatically on the first aibox apply that runs against an old v0.25.5 lockfile.

Troubleshooting

[addons.previous_selection] is absent after apply.

This is expected if no addon tools are enabled — the field serializes only when non-empty (skip_serializing_if = "BTreeMap::is_empty"). Enable at least one tool under [addons] in aibox.toml and re-run aibox apply to see it populated.

aibox apply reports a lockfile parse error after upgrading from v0.25.5.

A truncated or hand-edited aibox.lock may have a malformed [addons] section. Check that [addons].resolved_at is present and is a valid ISO 8601 timestamp. If the file is corrupt, delete aibox.lock and run aibox apply — the CLI regenerates it from scratch.

2 -

Zellij end-of-life migration (v0.25.5 → v0.25.6)

TL;DR

aibox v0.25.6 removes Zellij entirely. tmux is now the only supported terminal multiplexer. Any [customization.zellij_status] section in your aibox.toml causes schema validation to hard-reject aibox apply — you must remove it before upgrading. Stale Zellij directories and binaries are purged automatically on the first aibox apply that runs against a v0.25.6+ host CLI. No data from active work sessions is touched; only Zellij runtime artifacts are removed.

What changed

The following items are removed or rejected in v0.25.6 (commit faa9a88, decision DEC-20260508_1515-SilentAsh):

  • [customization.zellij_status] config key — the field is removed from the Customization struct in cli/src/config.rs. The TOML deserializer now hard-rejects any aibox.toml that still contains this section, with a descriptive error pointing to this document.

  • --forget-zellij-state CLI flag — removed from the argument parser in cli/src/cli.rs. Scripts or aliases that reference this flag will fail to parse.

  • Unconditional purge on aibox apply — the following paths under .aibox-home/ are deleted on every apply regardless of config:

    • .config/zellij/
    • .cache/zellij/
    • .local/share/zellij/
    • .local/bin/aibox-status (the shell-backed Zellij helper; superseded by the tmux PowerKit plugin set)

    The purge is performed by cleanup_legacy_zellij_files() in cli/src/seed.rs, which calls unconditionally via LEGACY_MUX_RELPATHS.

  • aibox doctor errors — any surviving artifact from the list above triggers an ERROR diagnostic (check_legacy_zellij_artifacts in cli/src/doctor.rs). The error is not advisory; it blocks a clean doctor run.

What you need to do

Complete these steps on the host before or immediately after upgrading to v0.25.6:

a. Remove [customization.zellij_status] from your aibox.toml. Open the file and delete the entire section (header and all keys beneath it). If you have no such section, skip this step.

b. Migrate any custom status configuration to tmux. If you previously used Zellij status customizations, set the tmux equivalent in aibox.toml:

[customization.tmux.status]
mode = "extended"   # or "minimal" for a compact single-line bar

The extended mode renders a two-line powerline bar with aibox metrics (log/OOM/proc/AI/MCP/migration counters). The minimal mode renders a single line. See docs-site/content/docs/customization/layouts.md for full reference.

c. Run aibox apply from a v0.25.6+ host CLI. This purges the stale Zellij artifacts listed above and records the new lockfile schema fields.

d. Verify with aibox doctor. After apply, run:

aibox doctor

A passing run reports no check_legacy_zellij_artifacts errors. If artifacts survive (e.g., because a volume mount shadowed the purge), the error output lists the exact paths to remove manually.

Why

Zellij was introduced as an aibox sidecar multiplexer, but the WASM plugin runtime, session-state model, and config schema diverged frequently from aibox’s tmux-native layout engine. The persistent vim-pane handoff through Zellij regressed every three to five releases, and the native Zellij status plugin required a WASM build step that added both CI complexity and binary supply-chain surface. tmux has been the canonical aibox multiplexer since v0.25.0; keeping a Zellij compatibility layer alongside it caused drift in every layout-generation codepath.

Decision DEC-20260508_1515-SilentAsh records the full rationale and the choice of scorched-earth excision (Variant 1 hard-purge) over a softer deprecation path.

Need help

Open an issue at https://github.com/projectious-work/aibox/issues and tag it zellij-migration. Include the output of aibox doctor and the relevant section of your aibox.toml.