Kestrel 0.8 is an exact-contract upgrade. Use the versions in the compatibility matrix together: Runtime 0.8.8 consumes the exact 0.8.5 Protocol, Conversation, Files, SDK, Memory, and Workspace Skills packages, while the other public adapters remain 0.8.5.
Adopt strict job preflight
Runtime/CLI 0.8.8 keeps job_input_v1 for existing direct clients and adds job_input_v2 for clients that require proof before assignment. Submit V2 to kestrel job preflight --json-in <file> --json-out <file>, preserve the returned job_execution_profile_binding_v1, and submit that binding unchanged with job run. A missing or altered fingerprint, policy, preset, authoring profile, approval pack, digest, or required tool is a COMPATIBILITY_ERROR before job or worktree creation.
Kestrel state isolation still uses KESTREL_HOME. There is no Kestrel --state-dir option; wrappers that expose such an option must map it to the child process environment.
Who must upgrade
Upgrade applications that import a Kestrel package, parse runner events or results, call project-state APIs, resume waiting work, authorize external effects, persist memory, or deploy a runner compatible with the application.
Before upgrading
Record the current versions, runner revision, persistence stores, event consumers, project APIs, and any code that assumes a particular wait or terminal-result shape. Back up application-owned stores before applying migrations.
Move every Kestrel package to 0.8
Use exact versions, not mixed minor lines. Install only the packages the application needs and regenerate the lockfile from the same release revision.
Removed project and SDK APIs
Legacy Board/Task project action types, project.snapshot.update, and SDK updateProjectSnapshot are not 0.8 write surfaces. Remove those callers instead of adding a compatibility shim. The read-only project.snapshot.get command, SDK getProjectSnapshot, and Git-only project.action command remain available and should not be removed as part of this migration.
Adopt Mission Control
Read authoritative project state through mission_control.project.get and execute supported changes through mission_control.action.execute. Keep project, execution, review, and migration authority distinct.
Update waits, recovery, and approvals
Resume the exact pending request using its request and option identifiers. Bind external authorization to the exact action/effect being executed; a broad approval token is not a substitute.
Replace workflow Apps with executable plugins
Consume the executable plugin manifest and its installed, configured, enabled, driver, version, and capability state. Remove callers that select workflow Apps, inspect workflow dependencies, or inject workflow instructions. Installing a plugin exposes governed capabilities; it does not grant an effect or add a conversation procedure.
Adopt public Memory where applicable
Use @kestrel-agents/memory@0.8.5 for governed memory contracts and gateways. Preserve tenant, subject, issuer, query authority, provenance, and application-owned persistence decisions.
Update event and observability consumers
Handle the exported 0.8 event set exhaustively, preserve correlation identifiers, and separate provider reasoning, agent progress, tool activity, visible assistant text, and terminal outcomes.
Preserve and migrate local or hosted data
Apply only pending migrations for the actual store. Preserve Desktop and Local Core settings, sessions, credentials, and project records. Hosted operators must verify application and worker compatibility before promotion.
Verify the upgraded integration
Run one successful turn, one waiting-and-resume path, one cancellation, one denied external effect, one Mission Control read/action, and one reconnect from persisted history.
Rollback and fix-forward constraints
Package versions and signed artifacts are immutable. Do not unpublish or overwrite earlier artifacts. Do not reverse a data migration destructively; roll application code back only when compatibility is proven, otherwise stop and fix forward.