Skip to content

AOI v0.2 migration

AOI v0.2 adds a durable single-Chief lease and fences project lifecycle mutations by session, epoch, credential, and expiry. Do not enable it on a live shared state tree while older AOI processes or overlapping Chief turns remain.

Existing v0.1.3 project

  1. Finish or checkpoint active work and stop all AOI writers.
  2. Preserve an exact state backup and the current aoi.toml digest.
  3. Install the reviewed AOI v0.2 artifact in the controlling environment.
  4. Run aoi doctor --json. An uninitialized Chief authority is a warning; any layout, lock-domain, policy-identity, or config error must be resolved first.
  5. Acquire authority without force:
aoi chief-acquire --session-id <new-chief-session-id> --json
  1. Set AOI_CHIEF_SESSION_ID, AOI_CHIEF_EPOCH, and AOI_CHIEF_CREDENTIAL_FILE from the non-secret acquisition result. Keep the credential file outside the repository.
  2. Run authenticated aoi init --json. Exact v0.1.3 managed policy bytes are upgraded automatically. A custom policy requires its reviewed digest via --replace-policy-sha256.
  3. Run aoi doctor --json and aoi chief-status --json, then start new work.

Packet and execution records migrate progressively:

  • new tasks bind task_execution_schema_version=2 to execution_policy_version=2 plus independent legacy_execution_policy=false provenance; new packets use schema v5 and new execution selections use schema v2;
  • a ready v4 packet is upgraded when it is armed or uses the explicitly marked manual migration exception, but only if its immutable contract lacks the native-v5 origin marker and the task is sealed as pre-marker legacy. A native policy-v2 task is rejected even if packet marker/origin fields are rewritten;
  • a new schema-v5 manual fallback must be armed first; direct ready -> dispatched registration is rejected, and an expired/stale arm is revalidated and rejected rather than consumed;
  • legacy terminal packet timing remains legacy_unverified and is never rewritten as a hook observation;
  • an execution-selection v1 record is preserved as legacy evidence and is not accepted as authority for new v0.2 packet activation. Finish only work already authorized under the legacy task, then start a new task; v0.2 does not create a v2 successor inside a task that already has legacy selections;
  • on a new task, a v2 parallel/hybrid selection with terminal specialist results needs one terminal Steward synthesis packet and an execution-brief-record --steward-packet-id ... before supersession or task close. New specialist packets/jobs are frozen once that synthesis begins;
  • standalone active jobs consume a task-global execution slot. Use job-start --owner-packet-id ... only when the exact dispatched depth-one mutation packet owns the job, its locks/command cover the launch, and it will remain active until the job is terminal. Its physical contract, canonical output locks, and exact-command SHA are rechecked at creation, running, and doctor;
  • pre-marker tasks retain their explicitly legacy existing work. A task with no legacy selections or active records adopts policy v2 before creating new v0.2 packets, selections, or jobs; otherwise finish the legacy task or start a new one.

AOI state remains cooperative: the independent provenance bit catches ordinary task/selection marker downgrade, but a same-OS writer that deletes all policy markers, provenance, and v2 artifacts is outside monotonic detection without an external witness.

Codex hook protocol v6 replaces protocol v5. Regenerate/update the hook command, review it again through /hooks, then test one pre-armed packet. Until that review is complete, issue the same short-lived arm before manual dispatch; AOI will record manual_unverified rather than inventing a start time.

An expired authority requires expected-epoch takeover with a reason. Replacing a live authority additionally requires --force-live; migration is not a valid reason to auto-steal an active lease.

ARISE activation boundary

AOI v0.2 may be developed and tested while ARISE uses its current harness, but do not switch the live ARISE state tree until its active sessions are quiescent and a migration window is explicit. Protocol v6 has narrow write authority only to consume an existing Chief-issued arm or append an unmanaged-start incident. It is still a post-start, fail-open procedural guardrail rather than an all-write or pre-spawn enforcement boundary, and it does not remove the need for user /hooks review.

Keep the pre-migration backup until the upgraded state, policy, credential handoff, Windows/WSL lock domain, and representative task workflow have all been verified. Downgrade is not an automatic state migration.