jason.woltje
13968e9a8b
ci/woodpecker/pr/ci Pipeline failed
Addresses CPS-PRD-REV1-REVIEW-Q90 findings F1 and F3 on PR #1491: F1 (format gate): `prettier --write` on the 18 rev1 bundle documents. Whitespace, table padding, list markers and emphasis delimiters only — a normalized token comparison of every file before/after shows zero content difference, so the ratified text is unchanged and no re-ratification applies. F3 (rev0 relative links): the archived rev0 PRD stays byte-identical (sha256 60cc2f98...36afdf verified) per GOV.1 archive-never-edit. A sibling docs/PRDs/2026-08-26_PRD_rev0/README.md records the digest, the original location, the owner disposition that the in-file links are intentionally historical, and a resolution table for all 9 targets (11 occurrences), each verified to exist. Future relocated archives ship the same README instead of edited bytes. F2 (test step) is investigated separately against the CI log.
122 lines
6.5 KiB
Markdown
122 lines
6.5 KiB
Markdown
---
|
||
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.
|