Session Continuity

Purpose

Turn manual "summarize this session, open a new session, paste the summary" work into a file-backed checkpoint and resume workflow.

Authoritative state must live in .agent/continuity/, not in chat history. Do not claim a restored session is trustworthy until validation passes.

Workflow

1. Locate the workstream root. Use the current working directory unless the user names another workspace.
2. Inspect existing .agent/continuity/current.yml, manifest.json, and handoff.md if present.
3. Choose the operation:
   • Checkpoint: create or update continuity state for the current session.
   • Targeted handoff: create a next-session handoff for one selected goal or content slice, without carrying the whole session.
   • Resume: validate and load the latest handoff, then continue from it.
   • Guard: evaluate context pressure and decide whether to watch, checkpoint, or roll over.
   • New thread handoff: checkpoint, validate, create a new Codex thread, and send the bootstrap there.
   • Validate: audit the handoff without changing it.
   • Redact: sanitize text before it enters any continuity file.
4. Run the bundled scripts from this skill rather than rewriting checkpoint logic.
5. Report the validation status, key paths, and any gate that is not ready.

New Thread Handoff

Use this when the user wants automatic session rollover, says the current Codex context is long, asks to "新建会话接入", or invokes the slash palette entry expecting continuity.

1. Run checkpoint.py or sc save for the current workspace.
2. Run validate.py or sc v. Stop if hash, redaction, or active-lock validation fails.
3. Generate bootstrap text with bootstrap.py or sc b.
4. If Codex App thread tools are available, call create_thread with the bootstrap as the initial prompt.
5. Prefer a project/local target when a valid project id is available. If no project id is discoverable, create a projectless thread and include the absolute workspace root in the prompt so the new thread can resume from .agent/continuity/.
6. After a successful create_thread, emit the required ::created-thread{...} directive in the final response and include the human-readable thread id.
7. If thread tools are unavailable, return the bootstrap text and label the result as "manual thread creation required".

The new thread prompt should tell the next session to run:

sc v
sc h

Then continue from .agent/continuity/handoff.md.

Automatic Rollover Guard

Use this during long-running work at phase boundaries, after major evidence, before long Figma/codegen/probe loops, and before final reporting.

The guard reads the current Codex rollout log when CODEX_THREAD_ID is available, then combines:

• token_count context ratio when present.
• fallback signals such as compaction markers, large session logs, large tool outputs, declared large reads, phase boundaries, major evidence, long-loop warnings, artifacts, and blocked items.

Shortcut commands:

sc context
sc maybe-rollover --latest-user-request "..." --active-goal "..." --next-task "..."
sc rollover --target "target name" --latest-user-request "..." --active-goal "..." --next-task "..."

Statuses are:

• ok: keep working.
• watch: context pressure is visible; avoid broad new reads.
• checkpoint_recommended: write or refresh .agent/continuity/.
• rollover_required: stop expanding the current session, checkpoint, validate, generate rollover-request.json, and create or fork a fresh thread when thread tools are available.

rollover-request.json is a creation request, not proof that a thread exists. After a successful create_thread or fork_thread, record the result:

sc receipt --created-thread-id "<thread-id>"

If thread tools are unavailable, return the request path and label the result as manual thread creation required. Never claim automatic rollover succeeded until thread-receipt.json contains the created thread id or pending worktree id and was recorded against a ready rollover-request.json whose revision and bootstrap hash still match the current continuity package.

Targeted Handoff

Use this when the user wants to carry forward only a selected topic, target, file, issue, PR, design, or decision set instead of the whole current session.

1. Ask or infer the target scope: what content is included, what is excluded, and what the next session should do.
2. Summarize only durable facts for that target. Do not include unrelated current-session history.
3. Write the targeted state under .agent/continuity/targets/<target>/.
4. Generate the new-thread bootstrap from that target by passing --target <target>.
5. If thread tools are available, create the new Codex thread from that targeted bootstrap.

Shortcut:

sc target "target name" "target summary" "next task"
sc v --target "target name"
sc b --target "target name"
sc h --target "target name"

For slash usage, the user can say: "只针对 <目标> 生成下个会话待办". Treat that as targeted handoff.

Script Commands

Use these from any project root:

Codex slash palette:

• Type /.
• Choose Session Continuity.
• The inserted prompt checkpoints the workspace and creates a new Codex thread when thread tools are available.

Shortcut commands are installed when available:

sc save "latest request" "active goal" "next task"
sc target "target name" "target summary" "next task"
sc v
sc b
sc h
sc context
sc maybe-rollover
sc rollover
sc receipt --created-thread-id "<thread-id>"
sc test

sc defaults to the git root when available, otherwise the current directory. Set SESSION_CONTINUITY_ROOT=/path/to/workspace to override.

Equivalent global command names, when installed: sc, session-continuity, and codex-continuity.

python3 ~/.codex/skills/session-continuity/scripts/checkpoint.py \
  --workstream "name" \
  --latest-user-request "what the user asked" \
  --active-goal "current objective" \
  --decision "stable fact or decision" \
  --open-task "next action"

python3 ~/.codex/skills/session-continuity/scripts/validate.py
python3 ~/.codex/skills/session-continuity/scripts/bootstrap.py
python3 ~/.codex/skills/session-continuity/scripts/guard.py
python3 ~/.codex/skills/session-continuity/scripts/thread_receipt.py --created-thread-id "<thread-id>"
python3 ~/.codex/skills/session-continuity/scripts/redact.py --text "raw text"
python3 ~/.codex/skills/session-continuity/scripts/self_test.py

All scripts accept --root <path> to target another workspace.

Gates

Every resume must check these gates:

If hash_status or redaction_status fails, stop and explain the failure. Do not resume from unsafe state.

If review_status is partial, label the restored context as partial. Do not call it a true tri-party result.

Tri-party Integration

When the active workstream is governed by the Codex + Claude + Gemini framework:

• Prefer running the tri-party review before finalizing a major checkpoint.
• Pass --triparty-run-dir <run-dir> to checkpoint.py when a run directory exists.
• Preserve Claude/Gemini outputs as evidence paths; never replace them with Codex summaries.
• Keep probe_status and review_status separate. File existence is not review completion.

Read references/triparty.md only when tri-party status or review provenance matters.

State Rules

• Store durable facts, not full chat logs.
• Redact before writing.
• Use monotonic revision; updated_at alone is not enough for concurrency safety.
• Keep a single writer lock under .agent/continuity/locks/writer.lock.
• Record hashes in manifest.json.
• Keep detailed schemas in references/schema.md.

Failure Rules

Read references/failure-modes.md when validation fails or the user asks why auto-resume is blocked.

Common hard stops:

• Missing or stale lock from another active writer.
• Hash mismatch after a checkpoint.
• Suspected secret in any continuity file.
• Missing current.yml or unreadable manifest.
• Tri-party workstream claims true synthesis without completed Claude and Gemini evidence.