Versioning contract

Versioning contract

Each database records its published schema in two places:

• PRAGMA user_version is the SQLite schema version.
• The primary schema_meta row records role, agent_id, schema_version, and app_version. app_version is the OpenClaw build that last wrote the schema metadata.

OpenClaw applies forward-only migrations when it opens an older supported database. It refuses a database whose user_version is newer than the running build and reports a newer schema version error. The Gateway checks all registered databases before startup. openclaw update also refuses a package or source target whose declared schema support is older than an on-disk database. Known stable releases published before schema metadata was added are checked against their shipped schema-1 contract. Updates driven by the 2026.9.2 release line can temporarily defer publication of a shared-state schema version while the old updater finishes; see Schema bumps and older updaters.

When Gateway startup encounters a newer database schema, it exits with status 78 so the generated systemd service does not restart it repeatedly. On macOS, it also parks its managed LaunchAgent to stop KeepAlive retries. This applies to failures during CLI bootstrap as well as server startup and does not depend on the database-backed crash counter. Start the Gateway with a build that supports the existing schemas. The older install cannot repair them with openclaw doctor --fix; run openclaw doctor --fix from the compatible install if further migration is required, then restart through the service or deployment owner.

Read admission reports the newer published schema version even when this build cannot parse its catalog. A known legacy index defect must not replace that refusal with advice to repair the database using the older build. Doctor checks compatibility before stopping the Gateway service.

Target-release checks distinguish the target's schema support from the running inspector's capabilities. When shared state is too new for the target but still readable by the inspector, preflight continues checking agent stores and reports all incompatibilities without modifying the source files.

Changes may stay at the same schema version only when downgraded readers remain safe. New tables qualify because older builds ignore them. An explicitly compatible column on an existing table qualifies only when its declaration is exactly one bare nullable SQLite STRICT datatype: ANY, BLOB, INT, INTEGER, REAL, or TEXT. The declaration cannot have a default, NOT NULL, a primary or unique key, a check, a reference, a collation, a generated expression, or another suffix. Constrained existing-table additions require a schema-version bump or a companion table instead.

Linux Node worker cleanup uses the additive node_worker_launch_process_scopes companion table. Its launch-bound linux-subreaper certificate records kernel descendant extinction independently of node_worker_launch_cleanup.lineage_settled. The existing cleanup row retains owned-anchor with no synthetic lineage completion, so older readers retain uncertain custody rather than treating the new certificate as an older proof. Existing rows are not backfilled or reinterpreted. The companion row is pruned with its launch under the same retention policy; the schema version is unchanged.

Matching numeric versions are necessary but not sufficient. A release can add a lazy or startup-repairable table, column, index, or trigger without advancing user_version, so two databases at the same version can still have different shapes. OpenClaw validates the canonical table definitions, constraints, indexes, triggers, virtual tables, and table options owned by the running release.

The per-agent companion table session_reactions stores message reaction rows at the same schema version. The canonical database-open additive schema installs it on existing databases without changing user_version; older readers ignore the table. Rows bind the session key, transcript session ID, persisted message event ID, emoji, and reacting identity without changing transcript bytes. Deleting the session node cascades to its reactions. Transcript replacement and suffix removal delete reactions for removed message identities in the same transaction, while a reset makes old-instance rows inert. Downgrade leaves the table intact and disables Control UI reactions until a supporting build returns. No transcript backfill or rewrite is required.

The first admission validates each physical database's schema version and shape once per process load. Agent, shared-state, and other SQLite owners share those admitted facts with every later handle and worker, including reopens after idle close. A replaced file needs first admission for its new physical identity. Migration and repair owners validate their changes and publish new facts after successful DDL settlement; rollback cannot publish an uncommitted schema. The schema_meta role and agent ID describe the physical store's fixed schema owner. Creation and migration validate and publish them; changing that row through external SQL does not reassign an admitted store to another agent. Session permissions, leases, and other live authority remain current-row decisions.

Catalog shape equality cannot prove that the schema_meta primary row or the config_machine_state content-version marker survived DDL. Observed DDL without owner-published replacement facts expires these row-backed admissions. The next owner lookup validates them once; later handles and opens reuse the result. Historical metadata remains private to its snapshot unless the owner positively matches it to the current committed admission. Rollback restores both staged publication and connection-local version facts.

The Gateway owns runtime database state. Committed in-process write receipts invalidate cached rows across handles and workers without querying data_version, schema_version, user_version, or the catalog. Other processes must route writes through the Gateway or hold exclusive offline ownership. SQLite read snapshots retain their view until they end; statements outside an open snapshot see current committed rows. Initial admission still refuses unsupported versions. Doctor, explicit verification, migration, and snapshot consistency checks retain their own contracts. This changes no stored schema, migration, durability, or update behavior.

The nullable requester-authority columns on GitHub publication lifecycle and repository receipts require state schema 18. Shipped readers validate these optional tables exactly and reject additional columns even when bare and nullable. Migration preserves historical rows with unknown requester authority; the version bump also prevents older publishers from reopening requests without the new authority checks.

Session label lookups use a nonunique partial index on session_nodes(label, session_key) for non-null labels, without changing agent schema 20. The existing writable schema owner installs and repairs the index; read-only startup accepts its absence until that owner opens the database. A present but noncanonical definition still fails strict offline validation; Gateway startup admits canonical index repairs to the same writable schema owner before readiness and logs the rebuilt indexes and elapsed time. Missing tables and incompatible column definitions remain refusals. Canonical session JSON, label uniqueness checks, and retention remain unchanged. Older same-version readers can ignore the extra index, so binary rollback leaves it intact. The accepted design is recorded in the session label index decision.

ACP resume lookups use two nonunique expression indexes on the existing acp_sessions.identity_json agent and ACPX session IDs. The shared-state worker selects only matching identities, and canonical session reads retain requester, backend, and lifecycle checks. Duplicate IDs retain session-key ordering; stale lifecycles do not authorize resume. Unresolved aliases and internal sessions stay ineligible, as in the canonical session listing. The writable schema owner installs the indexes on existing databases without changing the schema version or canonical rows. Construction scans ACP metadata once and uses temporary disk; subsequent metadata writes maintain both indexes. Older same-version readers ignore the extra indexes, so downgrade and binary rollback preserve rows and indexes. No new cache, retention policy, or operator configuration is introduced.

Task and maintenance lookups added nonunique indexes without changing state schema 17 or agent schema 21: task requester sessions, worker placements by environment, and session entries whose validity is not yet confirmed. The task requester index remains in the physical schema after the Tasks runtime removal. Stored rows, retention, and ownership checks are unchanged. Read-only admission accepts missing indexes; the canonical writable schema owner installs or repairs them. Initial construction uses time and temporary disk proportional to the affected tables, and subsequent writes maintain the added indexes. Older same-version readers can ignore them, so binary rollback preserves both rows and indexes. See the accepted index design.

Failed-delivery health counts use the shared-state delivery queue's existing idx_delivery_queue_failed index with columns (status, queue_name, failed_at, id). This replaces the queue-first definition at the same schema version. Queue rows remain canonical; the nonunique index is derived. The canonical writable schema owner atomically rebuilds a mismatched definition during admission, including its integrity checks. No per-request repair or extra index is added. The rebuild uses startup I/O and temporary disk proportional to retained queue history, including a check index and its replacement. Subsequent writes maintain the same index count. Older same-version writable owners can rebuild their queue-first definition on downgrade or binary rollback without changing rows; strict read-only validation may reject the changed index until that writable owner repairs it. Counts, null failure timestamps, ordering, retention, permissions, and durability are unchanged; no schema-version bump is required.

Meeting caption retry lookups use a nonunique partial index on meeting_transcript_utterances(session_id, session_started_at, utterance_id) where utterance_id IS NOT NULL, without a schema-version bump. The transcript store owns the canonical caption rows; the index is derived and preserves same-ID revisions, exact-content retry matching, and append order. Read-only admission accepts a missing index; the shared-state canonical-index owner installs or repairs it on writable open, and the feature's first-use schema includes it. The schema fast path detects missing or drifted indexes before admitting the handle. Construction on existing databases scans the table and uses temporary disk for the repair owner's check and final index. Subsequent writes maintain index entries only for non-null IDs. Stored content, retention, permissions, and transaction ownership are unchanged. Older same-version readers ignore the additional nonunique index, so binary rollback leaves both caption rows and the index intact.

Logbook's plugin-local database keeps schema version 1 while replacing the unused batch-day index with a nonunique partial index on batches(start_ms, id) where status = 'pending'. The existing worker-owned schema open installs the index on populated databases before dropping the retired index. Batch rows remain canonical; the index is derived, and retention and recovery are unchanged. Initial construction scans batch history once and stores only pending entries. Older same-version builds can read and write the database safely, leaving the new index intact and recreating their day index; reopening with the current build retires it again. Binary rollback requires no row conversion or schema-version change.

Memory chunk admission retires the nonunique idx_memory_index_chunks_path index at the same agent schema version. Both schema publishers retain the (path, source) index for path and source lookups. Writable memory initialization drops the redundant index after legacy storage validation; agent-only and read-only admission tolerate either state without recreating it. Older writable builds may rebuild it on downgrade or rollback. Rows and constraints are unchanged; see the storage decision.

Trajectory retention replaces the existing idx_agent_trajectory_runtime_run definition with a full covering index on (session_id, run_id, created_at, octet_length(event_json)), including null run IDs. Agent schema 24 is unchanged. The canonical index owner rebuilds same-name drift on writable admission; initial construction reads trajectory history and uses temporary disk for its probe and replacement. Writes maintain the expression index. Older same-version writable owners can restore their prior definition on downgrade or rollback without changing event rows; strict read-only admission can require that repair first. During the v17 upgrade, Doctor normalizes legacy memory metadata and validates the legacy schema before creating target-schema objects. Missing required tables or triggers remain refusals. Canonical indexes are repaired after the remaining data migrations, with target-schema validation in the same transaction. A refusal rolls back the migration and leaves the database unavailable to runtime until repaired. See the storage design.

Removing the Tasks and TaskFlow runtime does not change the shared-state or agent schema. The existing tables, indexes, and optional execution-owner columns remain part of the released storage contract. Cron reads and writes its existing runtime = 'cron' history rows in task_runs through its own store. Non-Cron Task and TaskFlow rows remain untouched and unused by the runtime; they are not converted into a replacement ledger. The Codex plugin's Doctor migration preserves eligible native child recovery facts from owner-stamped legacy rows in existing parent binding metadata, with an atomic import marker preventing replay. Source rows stay byte-identical. No table drop, SQL schema change, or schema-version bump accompanies this removal.

Node worker recovery uses the private node_worker_launch_cleanup companion table in the existing launch journal. The launch owner adds it on first use and records the selected process-group or owned-anchor transport in cleanup_mode, in the same transaction as the worker identity, before allowing execution. An owned anchor can record lineage_settled = 1 only for its exact current running identity after its root exits and its inherited lineage reaches positive EOF. Recovery also verifies that the recorded process group has disappeared before releasing capacity. A missing or ambiguous lineage result remains unknown; an empty anchor group alone cannot prove that descendants in other groups have stopped.

The node recovery repair keeps the journal as the sole durable owner. Cleanup records contain no launch descriptor or credentials, do not enter public receipts, and share the launch's existing 24-hour terminal receipt retention through a cascading foreign key. The schema version stays unchanged; older readers ignore the new companion table without changing their launch-table contract. Missing cleanup records preserve the released 2026.9.4 process-group contract without backfilling guessed identities. Untagged intermediate builds that used unmarked anchors must drain their workers on that original build before replacement. Active modern workers must also drain before downgrade or rollback to an older writer, which cannot interpret anchor lineage completion.

Notification ownership uses bare nullable TEXT columns at the same schema version: session_watch_cursors.watcher_store_path, subagent_runs.requester_store_path, and subagent_runs.controller_store_path. Their writers ensure them idempotently on first use; reads do not install them. Older readers ignore the columns. NULL remains unknown, so Gateway notification delivery does not assign historical records to a current parent by key alone.

Subagent runs record the known owning agent for raw child keys such as global in the optional childAgentId field inside subagent_runs.payload_json. Agent-qualified child keys do not record this field. This is a payload-only addition: no DDL, new column, or schema-version bump is required. The session store is derived from the agent and current configuration, just as it is for agent-qualified keys. Legacy rows without that binding continue to resolve their agent through the current configuration, without migration or backfill. Cancellation clears queues only for the resolved agent. Downgraded writers retain the field in payload_json because normalizeSubagentRunState mutates the parsed record in place rather than rebuilding it from known fields.

Cron standing-grant definition generations use three bare nullable projections on cron_jobs: grant_definition_revision, grant_definition_generation, and grant_definition_updated_at. The canonical job remains job_json. Current writers update the projections atomically with it, advance the generation for a substantive definition change (including edit-and-restore), and preserve the generation across disable and re-enable.

The released operator_approval_standing_grants table keeps its exact shape. A first-use companion table, operator_approval_standing_grant_generations, binds each newly minted grant to its job generation and cascades with the grant. Older same-version readers ignore the companion and the bare nullable job columns, so they can reopen the database. After re-upgrade, a grant without a companion row is treated as legacy and requires approval again; it is never assigned a generation retroactively. A job recreation advances past retained companion generations, including when an older writer deleted the job row.

An older writer does not maintain these projections. Its edits make the projection stale, so a current reader fails closed after re-upgrade. While the older build is running it cannot enforce generation binding, and changes that preserve every observable job value and timestamp cannot be reconstructed later. No backfill or schema-version bump is required. The accepted design and rollback contract are recorded in #142153.

Retained ACP imports use the same-version additive-column exception for the bare nullable session_nodes.legacy_acp_migration_json TEXT column. Legacy session import ensures it on first use and records exact source-component provenance; ordinary session edits preserve it, and canonical-key repairs carry it with the session. Canonical ACP initialization or closure consumes those components in the existing shared-state migration ledger, atomically with the ACP mutation. A later Doctor retry reads that completion fact instead of treating an absent ACP row as permission to restore legacy metadata. Missing provenance remains unknown; readers do not create the column or reconstruct it from legacy files. The column follows its session's lifetime, while completed receipts retain the existing migration-ledger lifecycle. No schema-version bump is required.

Older same-version readers can ignore the nullable column and open the database. Older ACP writers do not record this supersession; complete pending migrations before returning to an older writer when that protection is needed.

Cold transcript storage requires agent schema 20 even though it adds a companion table. Older readers would interpret extracted transcript rows as missing history and cannot safely ignore the new representation. The supported updater's Doctor phase performs the schema migration; changing the cold-storage age setting afterward needs no Gateway restart. These are separate operations: live configuration reload does not authorize an active schema migration.

Agent schemas 21–24 require the canonical-validation pending table and its node, window, and main-key invalidation triggers. Schema 25 removes those triggers and the entry_valid reset triggers: canonical writers validate their final serialized inputs before SQL, while offline import and repair explicitly queue admission work. This needs a version bump because older schema inspectors require the retired triggers. Migration preserves payloads, seeds all existing nodes, and clears the old canonical receipt before publishing the new version. Admission still rejects invalid imported rows. Reopening with older code is refused; rollback uses the verified pre-migration backup and matching build. See canonical writer validation.

Agent schema 22 introduced exact transcript FTS row ownership with a nullable completeness count and lazy backfill. Schema 23 accepts that deployed shape as well as schema 21. It rebuilds the ownership map from existing FTS content, preserves pending reconciliation, and retires the old completeness counter.

Agent schema 23 changes existing payload representations: transcript events can use Zstd BLOBs, memory embeddings use Float64 BLOBs, and memory full-text maintenance uses stable integer chunk identities. Older writers cannot preserve these contracts, so this requires a bump despite retaining logical event and chunk IDs. Shared-state schema remains 17. The usage-rollup cache format changes with this migration but is independently rebuildable. See compact agent payload storage for conversion, runtime requirements, and recovery.

Agent schema 19 records collected input consumption in the nullable session_pending_inputs.consumed_event_id TEXT column. Doctor and the feature's first-use ensure add it when needed; the schema version stays 19. The column shipped in 2026.8.2 (#133457), so the supported beta upgrade runs Doctor from 2026.8.2 or newer. Intermediate builds that already validate the optional pending-input table may reject the added column despite sharing version 19. Consumed source receipts remain until their session window is deleted, so rewriting a transcript cannot make an old input runnable again.

Cron run receipts use the optional cron_run_trigger_state_retirements companion without changing state schema 17 or the released receipt table's shape. Its only column is receipt_id, a primary key referencing the existing receipt with ON DELETE CASCADE. A committed condition, script-payload, or shared-state edit creates a retirement row in the same transaction as the job edit. This includes an exact receipt already closed by an agent-owner edit but still awaiting run reconciliation. Normal completion and restart recovery preserve the replacement's state while retaining the old run's history. The first eligible edit creates the table; queued edits do not retire a future evaluation. The job's private runtime state retains the exact running receipt ID until scheduler reconciliation, including when an agent-owner edit closes the receipt first. Recovery and later state edits use that association even when run timestamps collide. Receipt pruning preserves that pending receipt; ordinary history retains its existing 64-receipt bound and deletes retirement rows with their receipts.

Rows written before this association was recorded retain their legacy recovery fallback. The association adds no SQL table, column, or schema version. Current builds omit it from public job state and the public state-patch schema.

A missing table or row means no recorded retirement; earlier edits cannot be reconstructed from the final job definition. Older compatible readers ignore the companion but do not enforce this protection. To preserve edited watcher state, complete active runs and pending scheduler reconciliation on the current build before downgrading. A terminal history result or receipt can still leave job state unreconciled.

Scheduling edits made while a run awaits reconciliation record a private runningScheduleChangeId in the existing job runtime state, in the same transaction as the edit. The fresh value distinguishes successive committed edits even when a passive editor's snapshot spans two runs. Completion and recovery preserve the edited scheduling state; a new run and pending-run cleanup clear the marker. This adds no table, column, or public job field.

Pending runs without this marker retain their previous recovery behavior. Edits acknowledged by older builds cannot be reconstructed reliably from timestamps or the final schedule. New edits to those pending jobs record the marker normally. Older compatible readers ignore it; finish pending runs before downgrading if their edited cadence must be preserved.

Worker preparation uses the same-version rule for the bare nullable worker_environments.preparation_purpose TEXT column in the shared state database. Shared state database startup repair adds it without changing state schema 17. New admissions write reserve or build; existing preparation rows retain NULL and read as reserve, without backfilling demand or changing expiry. Older readers ignore the column and apply their existing reserve policy to all prepared workers; stop pending builds before downgrading if they must complete. Reopening preserves purpose, consumption, demand, and cleanup ownership.

The placement-move table uses this same-version rule for its bare nullable abandon_source INTEGER, target_machine_class TEXT, and target_os TEXT columns. The feature ensures these columns only on first move use; database startup does not add them, and the schema version remains unchanged. target_machine_class and target_os retain explicit profile-target overrides; NULL means no override. For abandon_source, NULL means ordinary reconcile-first movement; 1 records the operator's explicit offline-device abandonment decision so restart recovery cannot accidentally resume remote reconciliation. Older readers ignore the added columns and can reopen the same database safely; they do not implement the newer operating-system override.

Conversation associations use the same rule for the nullable bare route_context_json TEXT column. The database-open repair ensures the column for updated binaries. Older readers ignore it and can reopen and update the same database safely; their association update invalidates context captured by a newer writer so it cannot be replayed after re-upgrade.

Retained conversation progress snapshots use the agent database's cache_entries table with scope conversation-progress and the delivery operation ID as the key. The Tasks-backed detached presenter is removed, but its stored snapshots and receipt cleanup contract are unchanged. No table, column, schema-version change, or migration accompanies this removal. Older receipts are not backfilled.

The receipt owns the known platform message identity and delivery status. The removed presenter no longer writes or reads progress snapshots. Existing snapshot bytes remain opaque retained data; desired presentation is not proof that a platform edit was delivered or that work completed.

Reopening does not restore the removed Tasks presenter from cached snapshots; a snapshot never grants execution or delivery authority. Canonical session repair carries snapshots with their receipt identities. The existing session delivery cleanup removes matching snapshot keys with their receipts, with no new expiry policy, cleanup loop, or completion owner.

Transcript context eligibility uses a bare nullable session_transcript_active_events.context_eligible INTEGER column without changing agent schema 18. Database open installs the column and a non-unique partial index of unclassified rows. 1 includes an entry in bounded context acquisition, 0 excludes display-only activity, and NULL means the projection still needs reconciliation. Bootstrap control markers remain eligible; history counts, positions, and cursors do not change. Raw transcript JSON stays canonical.

Older same-version writers can append or rebuild without supplying eligibility. The existing transcript reconciler detects their NULL rows even when its sequence watermark is current, then rebuilds from raw events before publishing readiness. Readers return a retryable projection-unavailable result while this work is pending; they do not parse every payload or guess eligibility. Initial index creation scans projection metadata once, and startup awaits reconciliation with off-thread parsing and bounded write chunks. Total rebuild cost remains proportional to history. Rewrites invalidate or rebuild the projection in their own transaction, and transcript deletion removes its eligibility rows. Downgrade leaves the additive column and index intact; re-upgrade reconciles unknown rows.

Multi-account person profiles add the bare nullable user_profiles.primary_github_account_id INTEGER column on first profile use, without changing the shared-state schema version. Existing single-account profiles have an unambiguous primary; explicit merges retain all verified account rows and keep the target primary. This deliberately accepts a downgrade limitation: older single-account writers can discard secondary account links or split a linked person again. Re-upgrading cannot reconstruct discarded links. Keep a backup before downgrading, and explicitly relink affected profiles after upgrading. The version number does not certify preservation of multi-account relationships.

User profiles use the same rule for the nullable bare user_profiles.role TEXT column in state schema 9. Operator-role assignment lazily ensures the column on first use. Older readers ignore the column and can reopen the same database safely.

Web Push subscription ownership uses the same rule for nullable bare web_push_subscriptions.device_id TEXT, user_profile_id TEXT, and preferences_json TEXT columns. Web Push lazily ensures all three columns on first use. Existing rows remain unbound and test-only until the browser reconnects; older readers ignore the columns and continue reading or updating the endpoint and key fields safely.

Approval-notification cleanup uses the same-version additive web_push_approval_deliveries table. It records the approval/subscription identifiers plus the request-time device/profile binding for notifications that may have reached a browser. A terminal or restarted Gateway sends only when the current subscription still has that binding. The table is lazily created on first use, rows cascade away with their approval or subscription, and older readers ignore it safely.

Installing OpenClaw manually through npm bypasses the updater guard. Database open checks still refuse an incompatible build.

Structured Goal controls use a lazy per-agent session_goal_operations table without changing the schema version. Goal start/resume commits the Goal transition, input turn, run lifecycle, and operation receipt in one transaction. Management operations commit the Goal transition and receipt together. Older readers ignore the added table. Receipts survive Goal clear and session reset/deletion until their 24-hour validity expires; later Goal writes prune expired rows. They retain the original result and a keyed request fingerprint, not a second raw request. There is no backfill or configuration switch. Downgrading preserves the table but disables the new structured controls; upgrading can read retained receipts.

Schema bumps and older updaters

OpenClaw 2026.9.2 introduced the update ledger but reopens it with old code after running the target's Doctor, including a final read after recording its terminal outcome. The shared state database runner lets this updater finish by applying migration content first and publishing the new schema version later. This rule applies to every writable open, including Doctor, the restarted Gateway, and other CLI processes.

The runner records the applied content version in the existing config_machine_state key state.schema.contentVersion. While publication is deferred, new code uses that content version, and both PRAGMA user_version and schema_meta.schema_version retain the previous published version. Content and its marker commit together. Reopening skips migration steps already covered by the marker; it does not infer completion from table shape or repeat a completed rebuild. This requires no new table, configuration option, or environment override.

Current content is ready for readers even while its version is unpublished. Read-only CLI operations and Gateway-routed mutations can run alongside the Gateway throughout this window. Independent SQLite writers require exclusive ownership while the Gateway is stopped; the older update driver retains the explicit handoff contract below. Publication alone does not trigger schema repair or require stopping the Gateway.

A subsequent update can run during this window. Its migration verification and rollback checks compare applied content versions from private database snapshots. Publishing already-applied content is not another migration; applying new content still blocks rollback even when the published number has not changed. Managed service stop, activation, and Doctor maintenance keep their normal ownership rules.

Publication waits until every update row whose before.version identifies the 2026.9.2 release line meets its applicable condition:

• A terminal row's finished_at_ms is at least five minutes old.
• A running row's updated_at_ms is more than 30 minutes old. The runner treats that driver as abandoned for publication purposes; it does not rewrite the run's outcome.

A missing ledger or no affected rows permits immediate publication. Deadlines come from the rows' timestamps, never the observing process's start time. The new Gateway's ledger watcher schedules publication at the applicable deadline without jitter. Publication holds the Gateway lifecycle fence: the owning Gateway can publish, and a later writable open can publish when no Gateway owns the state directory. Other processes silently leave publication to that owner. Publication rereads the content marker and all affected rows inside one synchronous write transaction before advancing both published schema markers. A new or refreshed running row blocks publication again. Restarting the Gateway does not shorten or restart the grace period.

The five-minute grace accommodates 2026.9.2's trailing ledger reads; that release records no driver process identity that would prove those reads have finished. An old CLI blocked for more than five minutes after committing its terminal row, for example on a stalled stdout pipe, can still fail its final render after publication. By then the package swap, any requested service restart, and terminal ledger outcome are complete. Downgrade protection for the 2026.9.2 line is delayed by the same grace, or by the 30-minute abandoned-driver bound. The retained version is not permission to run older code against migrated feature tables. Do not manually lower either version marker or delete the content marker.

Update-time Doctor checks shared and registered agent databases before other repairs. A state-only migration proceeds with deferred publication and reports schema content applied; version publication deferred until update run <id> finishes. Publication still observes the five-minute grace after that run finishes. Agent schema versions are not deferred or relabeled. For a supported 2026.9.2 package update, the early Doctor runs schema repair on private database copies while the old driver can still roll back its package installation. It reports success only after the private Doctor and its children settle successfully; live agent databases remain unchanged. Known pending agent databases without a registered canonical backup owner still refuse during this rollback window.

After the shipped driver commits the package and enters its fresh post-core phase, the current updater delegates Doctor under its executor and maintenance ownership. Doctor creates and verifies a retained recovery archive covering every pending agent database before normal live migration. Coverage requires matching agent owners and physical file identities, including registered custom paths; opaque archived bytes are not a verified SQLite snapshot. Authority and live file identities are checked again after backup work and at the versioned schema write and commit boundaries. Doctor reports the retained archive path; it does not automatically restore that archive on a later failure.

Doctor keeps the typed update-schema-bump-unfenced refusal when the phase or current owner cannot be verified, recoverable backup coverage is missing, or the required config_machine_state table is absent. Private rehearsal and backup failures leave live agent schemas unchanged. A failed content transaction rolls back. The refusal includes the affected database versions, driving updater version, and manual update commands. Package rollback cannot reverse a migration that already happened; recovery after live migration requires the verified backup and a matching build.

The driver check requires a valid semantic version and includes 2026.9.2 rebuilds. Earlier updaters, including 2026.9.1, have no ledger and keep normal publication behavior. Builds from 2026.9.3 onward, including prereleases, use transactional updates that fence old-process ledger access and let candidate code finish after migration; they also keep normal publication behavior. Same-schema repairs and ordinary Doctor runs remain available.

Profile-owned skill library

Personal and team skills use four first-use tables in the shared state database without changing its schema version: skill_library_entries, skill_library_revisions, skill_library_events, and skill_library_uploads. Ordinary workspace skills and unused-library discovery do not create these tables. Ownership, sharing, the current revision pointer, portable file manifests, and publication events are canonical SQLite data. Session selections remain in the existing per-agent session store; inherited cron selections remain in the existing private job record.

Complete skill bundles are product artifacts under <state-dir>/skill-library/<skill-id>/revisions/<revision-hash>/. Publication writes and verifies an immutable bundle before committing its current pointer and event in one synchronous database transaction. Concurrent edits require the expected revision. A crash before that commit can leave an unreferenced complete bundle, but not a pointer to partially written content. Sharing and transfer change metadata without moving revision files.

Removing a skill excludes it from future selections; existing sessions retain their selected revisions. Published history and complete orphan revisions are retained conservatively. Expired upload records are pruned when another upload begins; clearly abandoned staging directories are cleaned during later publication. Back up both the state databases and the skill-library directory, not just the current revision pointers.

Older same-schema readers ignore the new tables but cannot provide managed-library selection or authoring. Keep the tables and bundle directory intact when changing builds; do not lower schema markers or delete revisions to disable the feature. The accepted storage and ownership decision is recorded in the profile-owned skills design issue.