Session offline migration

Convert to Session v13 with full backups, verification and explicit recovery

Agent Session storage uses schema v13, with one sessions.db per Agent. SQL stores separate type and kind columns and creation facts in relations. Public Session summaries and info expose id, type, kind and optional parent; cross-object references keep session_id. Desktop verifies the storage structure at startup and before reading history. Tool disclosure uses version 1 and ResultRef uses version 2.

Convert v12 to v13

The converter maps v12 category to type and origin.type to kind, renaming only chat/agent to chat/main. Other custom kinds retain their values. Existing parent creation facts are projected into parent, and additional origin business metadata is retained in the stored relation facts. UUIDs, messages, Tool snapshots and ResultRefs, checkpoints, receipts and attachments are preserved. Framework input actors change their category field to type; business JSON and tool snapshots are not recursively rewritten.

The same command handles transitional databases created by session-descriptor-v12 batches. It checks the complete schema, moves descriptor.kind into its own column, and preserves the remaining relation and creation facts.

Use Node.js >=22.18 with installed checkout dependencies and run preflight from public. The tool loads current source modules and frozen historical protocols. Choose a new private batch directory outside the data root.

node scripts/migrate-session-sqlite-v13.mjs --preflight --root /data/downcity --batch /backup/session-v13

After preflight passes, quit every Desktop, CLI, and Agent writer. Apply and verify using the same batch.

node scripts/migrate-session-sqlite-v13.mjs --apply --root /data/downcity --batch /backup/session-v13 --writers-stopped
node scripts/migrate-session-sqlite-v13.mjs --verify --root /data/downcity --batch /backup/session-v13

The tool backs up every database and verifies the staged conversions before publishing them. Resume interruptions using the same batch. Keep original/ and manifest.json. Before any subsequent business write or attachment change, quit every writer and use --restore --writers-stopped with the same --root and --batch arguments to restore the original databases.

After converting the databases, migrate Agent completion and delegation records, Task delivery targets in definitions and run snapshots, and Memory delivery subscription recipients. Keep every writer stopped and use a new batch directory outside the data root.

node scripts/migrate-session-journals.mjs --preflight --root /data/downcity
node scripts/migrate-session-journals.mjs --apply --root /data/downcity --batch /backup/session-journals --writers-stopped
node scripts/migrate-session-journals.mjs --verify --root /data/downcity --batch /backup/session-journals

Task and Memory delivery references change only their Session category field to type; Memory Job sources, evidence categories, request keys, subscription IDs and pending delivery text remain unchanged. Completion records retain their event IDs, results, and delivery acknowledgments. Unacknowledged recipients can resume processing after the host starts. For older delegations without an execution identity, the tool preserves their Session relationships and any recorded results. A pending delegation is stopped and its result delivery cancelled only if the original tool call exists in the parent Turn, the child Session has no messages, and the delegation has no recorded result. Preflight reports how many delegations will stop and halts if a started delegation lacks its original execution identity.

Keep original/, staged/, and manifest.json. Resume interrupted work using the same batch. Before any subsequent writes to these records, stop all writers and use --restore --writers-stopped with the same --root and --batch arguments to restore the originals.

If the data root has an existing notification inbox, keep writers stopped, build the Powers package, and convert its Session targets. Choose a new backup directory outside the data root.

node scripts/migrate-notification-targets.mjs /data/downcity /backup/notification-targets --writers-stopped

This step preserves notification content, timestamps, and read status and saves a copy of the original notifications.json.

Convert v11 to v12

v12 renames runtime input Parts from inbox/inbox_id to input/input_id and display Parts from power to view. It preserves Session UUIDs, message identities and text, timestamps, stable watermarks, tool results and saved model views, configuration, Composer checkpoints, receipts and attachments. Matching field names or strings inside business JSON are unchanged. Do not edit only user_version or the root marker.

Run from the source repository's public directory with Node.js 22.18 or newer and installed workspace dependencies. Create a new private batch outside the data root:

node scripts/migrate-session-sqlite-v12.mjs --preflight --root /data/downcity --batch /backup/session-v12

Preflight reads the source and reports record counts, Part rename counts, source fingerprints, content digests and blockers. Once it passes, quit every Desktop, CLI and Agent writer, then run:

node scripts/migrate-session-sqlite-v12.mjs --apply --root /data/downcity --batch /backup/session-v12 --writers-stopped
node scripts/migrate-session-sqlite-v12.mjs --verify --root /data/downcity --batch /backup/session-v12
node scripts/migrate-session-sqlite-v12.mjs --status --root /data/downcity --batch /backup/session-v12

Apply holds exclusive root and Agent file leases, backs up every database, converts and validates all staged copies, then publishes each database. It writes v12 ready only after schema, foreign key, all-message decoding and business content digest checks pass. It does not call models, replay tools or move attachments. If the source changes after preflight, create a fresh plan after stopping writers.

Resume interruptions with the original command and batch. Keep original/, staged/ and manifest.json. Before any business write or attachment change, stop writers and restore the original databases and root marker with:

node scripts/migrate-session-sqlite-v12.mjs --restore --root /data/downcity --batch /backup/session-v12 --writers-stopped

Historical tools below retain their declared output versions. For older roots, complete the relevant steps in order, ending with v12→v13 and the journal/delivery conversion above.

Convert v10 to v11

v11 allows Agent messages to persist their current error state. Conversion preserves all messages, Parts, tool results, stable watermarks, Session UUIDs, configuration, Composer checkpoints, receipts and attachments. Only the message metadata constraint and storage version change. Do not edit only user_version or the root marker.

Run from the source checkout's public directory with Node.js 22.18 or newer and installed workspace dependencies. Save a new private review batch outside the data root:

node scripts/migrate-session-sqlite-v11.mjs --preflight --root /data/downcity --batch /backup/session-v11

Preflight only reads source data. It reports each Agent's Session, message and Part counts, complete source fingerprint, business content digest and blockers. Review the passing plan, then quit every Desktop, CLI and Agent writer before applying:

node scripts/migrate-session-sqlite-v11.mjs --apply --root /data/downcity --batch /backup/session-v11 --writers-stopped
node scripts/migrate-session-sqlite-v11.mjs --verify --root /data/downcity --batch /backup/session-v11
node scripts/migrate-session-sqlite-v11.mjs --status --root /data/downcity --batch /backup/session-v11

Apply holds root and Agent file leases, backs up ALL databases, converts and validates all staged targets, then publishes under the batch's migration marker. It writes v11 ready only after schema, foreign key, message decoding and full business content digest checks pass. Conversion does not call a model, replay tools or move attachments.

Resume an interruption with the same command and batch. Before any business write or attachment change, restore the original databases and root marker with --restore --root /data/downcity --batch /backup/session-v11 --writers-stopped. Keep original/, staged/ and manifest.json in the private batch. The tool does not stop processes or clean up backups.

Group Session metadata

Persistent GroupSession reads require metadata v2 with explicit session and Group ownership, valid timestamps and message count. Missing metadata in a directory with history blocks initialization. Reads never write metadata. Valid startup recovery can repair message summaries and a truncated final JSONL record. Archiving preserves the ID and moves the session directory.

For explicit metadata conversion, select one Group storage root containing sessions/ and/or archived-sessions/, using absolute canonical paths without symlinks. Run from public/:

node scripts/migrate-group-session-v2.mjs plan --root /data/groups/delivery
node scripts/migrate-group-session-v2.mjs apply --root /data/groups/delivery --expect PLAN_SHA256 --backup /backup/delivery-v2 --writers-stopped
node scripts/migrate-group-session-v2.mjs resume --root /data/groups/delivery --expect PLAN_SHA256 --backup /backup/delivery-v2 --writers-stopped

plan prints a read-only inventory and plan_hash without creating files. Review the identities and use that hash for apply. Keep all application writers stopped throughout; the declaration does not stop processes. Apply validates the full source, creates a new private backup outside the root, then publishes each metadata file atomically. Session/Group/member IDs, message bytes and dispatch logs are preserved. Only v1 metadata changes to v2, with an empty pending-message checkpoint when absent; valid v2 files remain unchanged. This tool does not open Agent databases or transfer packages.

Both IDs must already exist in metadata; directories only check location consistency. All records in the selected root and every message must agree on Group ownership. Missing ownership evidence, invalid required/optional fields, nonempty legacy pending dispatch state, malformed JSONL, symlinks, runtime locks or a changed source block conversion. There is no ownership override or log repair.

Retain the backup's source/ and manifest.json. The batch is not globally atomic. Resume uses the original hash and backup, accepting only original or exact planned metadata bytes and unchanged other files; business writes block it. A process crash can leave .group-session-v2.lock and a .group-v2-*.tmp beside metadata. These block resume: after confirming all writers and migrators are stopped, review the manifest and remove only the abandoned migration lease and staging files matching the exact planned target hash. A backup without a manifest has not published changes; retain it and choose a new backup path. Restore is a separate reviewed stopped-writer operation; do not copy backups over live data.

Convert v9 to v10

From the source checkout's public directory, use Node.js 22.18 or newer with installed workspace dependencies. Save a new private review plan outside the root:

node scripts/migrate-session-sqlite-v10.mjs --preflight --root /data/downcity --batch /backup/session-v10

The manifest records source fingerprints, each Tool's identity, stable watermark, saved view/reference evidence, affected checkpoint counts and blockers. Completed and failed Tools require a supported disclosure version, saved JSON model output (including explicit null), and a valid ResultRef matching the result. Missing evidence, unsupported versions and conflicting references block apply. The tool never reconstructs a first model view. Running Tools retain their running state for first recovery under v10.

After reviewing a passing plan, quit every Desktop, CLI and Agent writer yourself. Apply the same plan, then verify it:

node scripts/migrate-session-sqlite-v10.mjs --apply --root /data/downcity --batch /backup/session-v10 --writers-stopped
node scripts/migrate-session-sqlite-v10.mjs --verify --root /data/downcity --batch /backup/session-v10
node scripts/migrate-session-sqlite-v10.mjs --status --root /data/downcity --batch /backup/session-v10

Apply holds root and Agent file leases, backs up all databases, stages validated targets and publishes under an owned migration marker. Canonical rows, fixed model views and references, stable watermarks, Composer checkpoints, UUIDs, receipts and attachment files remain unchanged. Resume an interrupted apply with the same command and batch. A blocked plan cannot be applied; retain the source and review its evidence.

Before any business write or attachment change, a completed batch can be restored with --restore --root /data/downcity --batch /backup/session-v10 --writers-stopped. Restore verifies all targets and original backups first. Keep the private batch and backups. The tool neither manages processes nor cleans up backups automatically.

Explicit recovery of historical Tool snapshots

If preflight reports tool_terminal_snapshot_required or result_disclosure_budget_exceeded, and you accept changes to those Tools' historical model-visible output, create a new recovery batch with --recover-reviewed:

node scripts/migrate-session-sqlite-v10.mjs --preflight --root /data/downcity \
  --batch /backup/session-v10-recovery --recover-reviewed

Recovery generates model snapshots from the original tool results using current privacy handling and the 16 KiB budget. These are migration-time views, not proven historical first disclosures. Complete valid snapshots retain their exact values. Original tool results, message identities, Session UUIDs, stable watermarks and attachments remain unchanged. Old references in call arguments remain historical input; references in result fields still require validation. Missing original results, unsupported disclosure versions, conflicting digests and conflicting reference sources still block conversion.

The manifest marks every planned change as migration-rebuilt-snapshot and records its reason, original and target content hashes, result hash, whether a reference was created, and invalidated Composer checkpoints. Checkpoints covering changed Parts are removed; earlier unaffected checkpoints remain. Later input may rebuild summaries and initially use more context. Migration itself does not call a model or replay tools.

Review the passing manifest and quit all writers. Apply must explicitly select recovery again, matching the saved batch policy. Use the same command and batch after any interruption:

node scripts/migrate-session-sqlite-v10.mjs --apply --root /data/downcity \
  --batch /backup/session-v10-recovery --recover-reviewed --writers-stopped
node scripts/migrate-session-sqlite-v10.mjs --verify --root /data/downcity \
  --batch /backup/session-v10-recovery

Recovery backs up every original database before staging and validating targets. Apply rechecks source fingerprints and every rebuilt result; changed source data or reconstruction behavior invalidates the plan. Status, verify and restore use the saved batch policy without --recover-reviewed. Existing strict batches retain their original policy; recovery requires a new preflight batch.

Convert v8 to v9

Run the following from the source checkout's public directory with Node.js 22.18 or newer and installed workspace dependencies. Preflight converts and validates isolated temporary databases without changing the data root:

node scripts/migrate-session-sqlite-v9.mjs --preflight --root "$HOME/.downcity" \
  --report "$HOME/session-v9-preflight.json"

The tool includes every active and archived Agent Session and promotes each record's storage_id unchanged to its permanent session_id, preserving the record UUID. A private mapping records the source logical ID, source record UUID and target identity. Duplicate UUIDs or conflicting owners anywhere in the root block migration. It establishes the main pointer from the unique eligible active Agent main Session and converts canonical messages, Parts, configuration, fork references, result references and disclosure cursors. Completed legacy receipts and archive operations become audit digests rather than valid v9 idempotency receipts.

Derived Composer summaries may contain old identities. Original summaries remain in backups while target checkpoints are cleared. Later real input regenerates summaries and may initially use more context; migration itself does not call a model.

Attachments remain under session-files/<session_id>/ with the source record UUID, retaining their contents, inodes, modification times and media versions. Structured attachment URLs and ownership manifests are still converted and validated individually. Supported external references include completion journals, delegation records and closed parent Turns, Group member Sessions, Task delivery targets, Messenger/Chat routes, notification targets, Desktop pins and Session model preferences. Group Session IDs, prompts, user text and channel queue payloads retain their original meaning.

Missing or ambiguous references, unfinished streaming messages/archive operations/delegation deliveries, pending attachment cleanup, legacy import staging, unknown schemas and changed fingerprints block the entire batch. Existing Memory Job or subscription ledgers require separate conversion and explicitly block this tool. Review the private report's blockers; do not bypass them by editing user_version or choosing the latest record sharing an old ID.

After reviewing historical anomalies and accepting the following recovery behavior, explicitly add --recover-reviewed to preflight:

node scripts/migrate-session-sqlite-v9.mjs --preflight --root "$HOME/.downcity" \
  --recover-reviewed --report "$HOME/session-v9-reviewed-preflight.json"
  • Unfinished messages retain their text and completed results and close as interrupted with a diagnostic. Unfinished tools fail and pending interactions are cancelled; tools are never replayed.
  • Group metadata IDs that differ only in case use the existing directory ID. References to removed member Agents remain as non-executable history.
  • Completed ledgers and parent-Turn closure markers whose source cannot be established move into .session-v9-audit/<migration_id>/ under the data root. Their original bytes remain available, outside delivery processing.
  • Invalid Task deliveries pause scheduling; invalid legacy Chat routes pause. Original targets, task text and channel payloads remain available. Pending channel inbox and outbox records become failed to prevent automatic retries. Invalid Messenger bindings still block migration and require explicit rebinding first.

This policy handles only these anomalies. Pending deliveries, unknown formats and mismatched digests still block migration. The private report's recovery.entries binds every decision to its source digest, which apply checks again. After reviewing the report, pass --recover-reviewed on the first apply as well. Resuming the same batch uses its saved policy. Complete original database and file backups remain mandatory; audit files participate in verification and restore checks.

After preflight passes, quit every Desktop, CLI and Agent writer. This isolated identity conversion produces v9; complete the v10 evidence conversion, v11 message metadata conversion v12 input/view conversion, and v13 type/kind conversion before opening the root with the current host. Apply with a new private batch directory outside the data root:

node scripts/migrate-session-sqlite-v9.mjs --apply --root "$HOME/.downcity" \
  --batch "$HOME/.downcity-migration/session-v9" --writers-stopped \
  --report "$HOME/session-v9-apply.json"

--writers-stopped declares that writers have been stopped; the tool does not stop processes. Apply holds the root and Agent attachment leases, backs up every database through SQLite (including committed WAL) and copies attachments and reference files before staging validated targets. It publishes under a root migrating marker and marks v9 ready only after all targets pass verification. Keep backups and mappings private.

Batch manifests must declare identity_policy=preserve-record-uuid-v1; each target session_id must equal its source storage_id. Staging also checks every mapping against the source database. Missing or mismatched policies fail with batch_identity_policy_requires_review. Invalid mappings fail with identity_mapping_policy_mismatch or identity_mapping_source_mismatch and require separate batch review. Do not add policy markers or edit identity mappings manually. This tool does not rewrite already converted v9 data.

After interruption, repeat --apply --writers-stopped with the same batch. Keep the existing batch and staging files. Use status to inspect progress and verify for a read-only check of completed batches:

node scripts/migrate-session-sqlite-v9.mjs --status --root "$HOME/.downcity" --batch "$HOME/.downcity-migration/session-v9"
node scripts/migrate-session-sqlite-v9.mjs --verify --root "$HOME/.downcity" --batch "$HOME/.downcity-migration/session-v9"

A completed batch can be restored only while every target still matches its published fingerprint. New business writes, attachment changes or preference updates prevent restore. Quit all writers first; an interrupted restore resumes with the same command and batch, retaining original and staged copies:

node scripts/migrate-session-sqlite-v9.mjs --restore --root "$HOME/.downcity" \
  --batch "$HOME/.downcity-migration/session-v9" --writers-stopped

Offline format boundaries

The installed SDK opens Agent schema v13 only. The v11→v12 and v10→v11 tools use frozen target schema/codec/readiness bridges; historical tools retain their declared output versions, so continue each step through v13. The v9→v10 tool uses a frozen v10 bridge. Historical batches retain their original versions and identities across SDK upgrades. The v8→v9 tool uses an explicit frozen v9 schema/codec/readiness bridge and preserves its batch identity policy. scripts/lib/session-runtime.mjs loads current pure protocol modules and the Agent schema. Fixed v7 schema definitions and historical conversion entry points live under scripts/; they are not part of the SDK runtime. The v7 converter handles its declared source formats and produces v7, which the SDK does not open.

scripts/migrate-session-sqlite-v8.mjs requires a matching v8 runtime and rejects with v8_tool_runtime_version_mismatch before accessing data with current source. Do not change schema constants or package fields to bypass checks.

Export and import one Session

Current commands use schema v13, directory package format 3 and import batch format 3. They transfer a Session between roots owned by the same Agent, preserving its permanent session_id, active or archived state, messages, Parts, configuration and Composer checkpoints. Import does not select or replace the target main Session pointer. The target Agent must already have a ready v13 database.

Quit every source writer first. From public, export the exact UUID to a new private directory outside the data root. Package verification never reads the source database or the original attachment paths recorded in the package:

node scripts/export-session.mjs --export --root /source/downcity --agent writer \
  --session-id 9e23e440-11cc-43b6-b55f-7d3956d828ab --package /backup/session-package \
  --operation-id a223e440-11cc-43b6-b55f-7d3956d828ab --writers-stopped
node scripts/export-session.mjs --verify-package --package /backup/session-package

The package contains manifest.json, record.json and attachments/. Validation covers canonical records, stable Part watermarks and Step boundaries, checkpoint foreign keys, record digests, attachment hashes and source references. Export holds a read transaction and attachment lease. Ownership manifests must match; without a manifest, only reserved runtime-generated filenames are accepted. A Session participating in an unfinished archive plan cannot be exported alone.

Quit every target writer before importing. Choose a new private batch directory outside both the root and package:

node scripts/import-session.mjs --root /target/downcity --agent writer \
  --package /backup/session-package --batch /backup/session-import \
  --operation-id b223e440-11cc-43b6-b55f-7d3956d828ab --writers-stopped

Import rejects UUIDs already present under any Agent in the target root, as well as retired identities and identities reserved by cleanup, historical receipts, creation keys or archive plans. Operation IDs in legacy audit records cannot be replayed. Import never overwrites records or existing directories, remaps IDs, changes Agent ownership or creates an independent copy.

Fork sources, Session origins, Input/message sources and Tool ResultRefs must resolve precisely within the current Agent. Missing sources block the operation by default. To retain exact unavailable references, explicitly add --allow-unresolved-sources to the relevant export or import command. The policy binds to that operation's plan and returns an unresolved count. It does not guess a target or grant cross-Agent access. Existing sources with conflicting identity, type or result digests still fail.

Attachments are copied and verified in a private stage under the target Agent, then published together before a single database transaction inserts the record and receipt. After a copy, publish or commit acknowledgment failure, resume with the same arguments, operation ID and batch. Recovery verifies package hashes, stage ownership, published attachments and the committed record. A new operation cannot take over an existing stage. Unfinished batches remain for continuation or review; they are not deleted automatically. Only owned file URLs, media versions and exact attachment path hints are rebound; arbitrary text and disclosed Tool content are not replaced.

Convert a standalone package

convert-session-package.mjs validates format 3/schema 10, 11 or 12 and format 2/schema 9 packages through isolated historical loaders, or first converts self-contained format 1/schema 8 packages in temporary databases. It writes a new format 3/schema 13 package only when every terminal Tool has proven first-disclosure evidence. Formal import accepts format 3/schema 13 only:

node scripts/convert-session-package.mjs --package /backup/source-package \
  --output /backup/converted-package --operation-id c223e440-11cc-43b6-b55f-7d3956d828ab

Conversion validates the fixed source schema, canonical records, saved model views, result digests and attachments. Missing/unknown/conflicting Tool snapshots block before creating the requested output directory. Schema 9–11 records first rename inbox/inbox_id to input/input_id and power to view, then apply the v13 type, kind, relation and input-actor mappings; other canonical values and checkpoints are preserved. The schema 8 identity conversion clears derived Composer checkpoints and returns their count. The source package remains unchanged and its original data root is never accessed. Cross-record references without canonical evidence block conversion and require reviewed root conversion; same-name records or edited package fields do not supply evidence. Output must be a new directory. Interrupted output requires separate review; the converter does not overwrite or automatically take it over.