Move Session Log

---
name: move-session-log
description: Use when the user asks to relocate or import a session log into the current project, or to make session history and resume follow a renamed project directory in the current tool; not for merely opening or inspecting the current session log.
---

# Relocate Codex session metadata

Import one explicitly identified Codex session into a project, or relocate
metadata after a project-directory rename. Codex stores transcripts globally:
this changes metadata, not their physical project directory. It does not rename
the project, unarchive sessions, merge histories or operate on Claude stores.
Use `open-session-log` for simple inspection. Review, diagnosis and planning
requests remain read-only.

Use the bundled [adapter](scripts/move_session_log.py), its
[single-session importer](scripts/live_import.py), and
[offline safety helper](scripts/migration_safety.py). Do not invent an inline SQL or
transcript-rewrite fallback when the helpers or preflight fail.

## Establish identity and scope

- Resolve the actual active `CODEX_HOME`, defaulting to `~/.codex` only when
  unset. Inspect resolved store identities, not a guessed account or recent file.
  Import requires the exact UUID and one matching `session_meta.payload.id`;
  a filename substring is not identity evidence.
- Resolve the absolute target project; pass `--project` explicitly when it is
  not the shell directory. With no ID the adapter only lists candidates. Choose
  from reliable context or ask one identity question; do not select the newest.
- Rename takes absolute old and new paths, in that order. Mapping is exact, not
  prefix replacement. Report descendant contexts that also need relocation.
- Inventory active `sessions/`, associated `archived_sessions/`, and each
  discovered profile's history, session index and thread database. Discovery
  covers the active home and sibling `.codex*` homes sharing its resolved session
  store, not arbitrarily located profiles. Deduplicate resolved shared files.
  Report absent artifacts as unupdated; do not create a replacement index or
  claim complete coverage from this bounded discovery.

## Preview both modes

Use this skill's resolved directory for `SKILL_DIR`; pass literal quoted
arguments, not paths or IDs interpolated into SQL, Python or shell source.

```bash
python3 "$SKILL_DIR/scripts/move_session_log.py" --dry-run --project "$TARGET_PROJECT" "$SESSION_ID"
python3 "$SKILL_DIR/scripts/move_session_log.py" --dry-run --rename "$OLD_PROJECT" "$NEW_PROJECT"
```

Validate the selected inventory, JSONL identity and SQLite schemas before
any apply phase. Single-session imports inspect SQLite read transactions and
create consistent backups through its online backup API; offline operations capture the database and its WAL
before inspecting an owned copy. Refuse
malformed/truncated targeted files, identity conflicts, unsupported existing
schemas or unstable inputs. Resolve reversed paths or unexpected scope. Zero
matches do not prove the search was complete.

The database adapter supports the reviewed `state_5.sqlite` thread schema and
known triggers that do not fire on `cwd` updates. Unhandled generations or side effects
refuse before writes. Its database scope is thread `cwd`, not independent project
associations: observed `project_id`, project tables or project roots are reported
as unchanged. Do not claim those associations were migrated.

## Move one closed session while other sessions stay open

Single-session import uses the live-safe path by default. Establish that the
identified session is closed; a user report plus the helper's target-file
writer check supplies this boundary. When accessible, inspect the owning
app-server's `thread/loaded/list` too. Do not resume the target during migration.
The helper refuses the invoking session's ID and any open target-file writer.
An active session must not replace its own append-only transcript: its writer
could continue appending to an unlinked old file.

Unrelated Codex sessions and their database connections may remain open.
The importer uses SQLite transactions to lock and revalidate exact thread rows,
with consistent database backups and a recovery journal. It does not hash live
WAL or shared-memory files as if they were static transcripts. Shared history
and index files that need no change are not replaced or treated as offline
stores. If their selected metadata needs rewriting, their file writer guards
still apply; report the specific blocking file rather than demanding that all
Codex sessions stop.

Apply with a new absolute `--backup-dir` outside Google Drive:

```bash
python3 "$SKILL_DIR/scripts/move_session_log.py" --backup-dir "$NEW_PRIVATE_BACKUP" --project "$TARGET_PROJECT" "$SESSION_ID"
```

Do not kill unrelated sessions, close Emacs, restart Codex or switch accounts
to move a closed session. On a refusal, identify the actual target or input
that failed instead of inferring that the shared database must be closed.

## Bulk rename and explicitly offline import

Bulk `--rename` retains the full-store offline procedure. Establish that
affected sessions and every writer of shared files/databases are stopped.
If quiescence cannot be established, keep the preview and report that boundary.

Apply requires `--offline` and a new absolute `--backup-dir` outside Google Drive.
The flag asserts established quiescence; it does not stop writers. The helper
revalidates inputs and inspects kernel device/inode records using the supported
Darwin/libproc `lsof` 4.91 format. Unrecognized formats or diagnostics refuse the
operation. This can miss processes the OS hides and cannot exclude future writers;
it does not independently establish quiescence.

```bash
python3 "$SKILL_DIR/scripts/move_session_log.py" --offline --backup-dir "$NEW_PRIVATE_BACKUP" --project "$TARGET_PROJECT" "$SESSION_ID"
python3 "$SKILL_DIR/scripts/move_session_log.py" --offline --backup-dir "$NEW_PRIVATE_BACKUP" --rename "$OLD_PROJECT" "$NEW_PROJECT"
```

Choose a durable uniquely named location under a private off-Drive state root.
Protected originals and the recovery journal contain private user history, not
scratch or public repository artifacts. Do not publish or delete them as cleanup.

In either mode, only consumer-relevant `session_meta`/`turn_context` payload `cwd` and supported
top-level history/index metadata are eligible. Import maps the identified
original project to the target, preserving different contexts. SQLite updates
match exact thread IDs, never `rollout_path LIKE` or a nested arbitrary `id`.
Historical tool arguments, results, prose and unrelated records stay unchanged.
Archives remain archived; shell snapshots are not moved.

## Verify the right result

For Agent Log, test `agent-log-resume-session` from the user's rendered log.
Agent Log has its own persistent `agent-log-thread-catalog.json` and rendered
index, separate from Codex's SQLite database and Emacs session buffers. A stale
catalog can send resume back to the original project. Ensure resume resolves
the current project from the exact canonical transcript, refresh Agent Log's
catalog through its own refresh mechanism, and use its rendered-file maintenance
to relocate the indexed Markdown file and any visiting buffer. Keep the
original rendered path available until its resume command has been exercised.
Verify the newly resumed session's ID, restored history and actual directory;
renaming a previously running Codex buffer does not test this entry point.

When the user works in Emacs, relocation includes the buffer associated with
the exact session ID, not just disk metadata or the history picker. Inspect all
Codex buffers, including buffers whose processes have exited, before and after
the operation. Match `codex--app-server-thread-id` or `codex--session-id`; do not
infer identity from the buffer name. A buffer reopened during the operation can
retain the old directory even after the disk migration succeeds.

For an idle live app-server buffer whose persistent metadata is already moved,
send `thread/settings/update` with the exact `threadId` and target `cwd` through
that buffer's existing connection. Check the installed experimental schema and
the response before updating buffer state. Set `default-directory` and
`codex--buffer-directory` to the target, preserve the session ID, and update
`codex--buffer-instance-name` and the buffer name together. If the target's
instance name is occupied, choose a distinct instance such as `moved`; never
replace the other buffer. Do not interrupt an active turn or pretend changing
only the displayed name relocates the running session. Exited matching buffers
still need their directory and name synchronized.

Verify the resulting buffer name, directory, exact session ID and live server
`thread/read` cwd. Verify persistent metadata separately. A passing history
listing alone does not establish that an existing buffer moved.

Inspect exit status and journal; independently read back selected metadata,
exact thread rows and unchanged unrelated records. Compare the actual result
with the preview and explain changed inputs or coverage limits. Repeat a preview
for remaining intended changes: matching counts alone are not proof.

Files and profile-local SQLite transactions are not one atomic transaction. On
failure, stop and inspect completed operations and retained originals. Report
partial application and its recovery path. Do not blindly retry or roll back
over newer state.

The installed app-server interface accepts a `cwd` override for `thread/resume`,
and the Emacs client sends it. That alone does not establish durable relocation
of the original rollout header. Project-filtered listing also uses stored
metadata and can repair it from JSONL; changing only a database row is insufficient
consistency evidence.

Use `end-to-end` when claiming that the actual history/resume consumer now works.
Do not start a live session as part of a dry run or an audit of this skill.
Report the session/project, material outcome and any partial-state, coverage or
live-verification gap briefly.