---
id: SESS.1
status: ratified
ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
---

# SESS.1 — Session identity and mid-stream switching

## Requirement (Jason, 2026-08-31)

An agent session stays active on the system, tied to a **Stack session id**.
Changing harness, model, or provider mid-stream preserves the session id and
fully switches context from one provider/harness to another, with no user
intervention and no noticeable performance degradation.

## Two operations, two code paths — never merged

| | Harness / model / provider switch | Role switch |
|---|---|---|
| Session id | preserved | seat identity preserved; session is **clean** |
| Context | fully transferred | **ephemeral context discarded** (register OD-03) |
| Governed by | this section | [[SEAT.1-seat-profile]] §role-binding |
| Why | continuity requirement | an active session never switches roles (register OD-02) |

## The ratified mechanism already exists: register OD-57–OD-61

The 2026-08-28 register confirms the machinery this requirement needs:

- **OD-57 checkpoints** — atomic, schema-valid, revisioned seat checkpoints tied
  to incarnation and lease; freshness enforced mechanically.
- **OD-59 relaunch** — the coordinator requests and validates a checkpoint, stops
  the session, applies configuration, starts a **clean incarnation**, restores
  the assignment, verifies readiness.
- **OD-60 fencing** — leases, epochs, incarnation IDs, fencing tokens prevent a
  stale session from mutating state after the switch.
- **OD-61 restart recovery** — the relaunched seat restores role, mission, task,
  PRD pin, constraints, evidence, blockers, leases, dependencies, and next
  action **without prior conversation**.

A mid-stream harness switch is therefore an OD-59 relaunch keyed to a persistent
Stack session id: checkpoint → stop → reconfigure → new incarnation →
restore → resume. What OD-59 does not yet promise is the *experience* bar — no
user intervention, no noticeable degradation — which is this PRD's addition.

## Identity layering

`mosaic-core` mints a per-launch **incarnation id** and keys its journal on it,
deliberately not on any session id. A harness switch is a new process → new
incarnation → new journal, **while the Stack session id persists**. So:

```
Stack session id   (durable; user-facing continuity)
  └─ incarnation id (per launch; enforcement journal, fencing per OD-60)
```

The precise contract between the two ids — minting, custody, what the
coordinator records at each relaunch — must be specified before build:
[[GOV.5-open-questions]] Q-S1.

## Open hard problem

Context-transfer fidelity between harnesses with different context formats,
tool-call encodings, and system-prompt injection points. The checkpoint (OD-57)
is the transfer vehicle; whether a checkpoint alone meets "no noticeable
degradation" across harness families is unproven: [[GOV.5-open-questions]] Q-S3.
## Session lifecycle state machine (pulled 2026-08-31 from the session-lifecycle draft — with one required extension)

The operator draft (`workflows/session-lifecycle.md`, the densest
decision-register consumer: OD-03/OD-04/OD-08, OD-56–OD-65) supplies the checkpoint/
lease/fencing machinery this section's continuity requirement runs on:

- **States**: Active → Relaunch-requested (triggers per OD-59: context
  utilization, session age, milestone, drift, degraded health, role
  reconfiguration, authorized request) → Checkpointing (atomic, revisioned,
  bound to identity + incarnation + epoch + lease, OD-57) → Relaunching
  (validated checkpoint, old lease revoked → **new incarnation, new fencing
  token**, OD-59) → Restoring (readiness proof: role, task, PRD pin, blockers,
  next action, OD-61) → Active/Degraded. Role change routes through
  Reconfiguring first (old-role record, transition history, revoked lease,
  OD-03/OD-04).
- **Fencing**: a stale session cannot mutate after its replacement holds the
  new token (OD-60); mutation authority is lease-gated and not renewed while the
  checkpoint is stale. Coordinator outage fails closed for new
  assignments/relaunches/renewals; existing leases run to expiry; read-only
  work continues (OD-63).
- **Checkpoint contents** (required fields): role, config version, mission,
  outcome node, task, PRD pin, constraints, completed work with evidence refs,
  blockers and failed attempts, active leases/external ops, next action with
  required inputs. The checkpoint is an operational projection — mission truth
  stays in the ledger (OD-58). Telemetry is append-only and never the resumable
  checkpoint (OD-56).

**Structural gap found at extraction (must be fixed before this machine
ratifies):** the draft models exactly **one** relaunch mechanism — every
trigger, without exception, mints a new incarnation and fencing token. There is
no continuity-preserving path at all, and harness/model/provider switching does
not appear among the triggers. This PRD's two-operations rule (above) requires
**two code paths**: the state machine must gain a switch path that preserves
the Stack session id and full context per OD-57–OD-61 while still rotating the
fencing token safely. Adopting the draft's table verbatim would silently
collapse the two operations back into one — the exact defect register OD-02/OD-03
vs the continuity requirement exists to prevent.

## E2 inputs (triage 2026-08-31; see [[GOV.2-docs-inventory]])

**Canonical ground truth**: `DEVELOPER-GUIDE/architecture/compaction-revocation.md`
(the only current continuity/revocation lifecycle — observer/generation-fencing,
test-consumed), `channel-protocol.md`.
**Pending pulls**: brain `docs/guides/proposed/workflows/session-lifecycle.md`
(checkpoint/relaunch/recovery/role-reconfig — complements this section's
switching focus; its role-reconfig path must respect the OD-02/OD-03 clean-session rule).

## Two-path requirement ratified (Q-S4, Jason 2026-09-01)

The state-machine gap flagged above is now a binding requirement: the
session-lifecycle draft may not land with a single relaunch path. Role change
→ clean-session path (new incarnation + fencing token, context discarded,
OD-02/OD-03). Harness/model/provider change → continuity path (same Stack session
id, OD-57 checkpoint restored under OD-61, no noticeable degradation). The two
paths must not share a code path.