Continuity
Continuity makes working state survive a session switch, a tool switch, and a
machine switch. The unit of continuity is not the conversation — it is the
session's beliefs and decisions, carried as portable artifacts with review
state, code anchors, and scope proof, so a destination can re-ground rather
than trust a claim blindly. Belief lifecycle belongs to
Memory; review-state vocabulary to
Trust. MCP profile portability is the separate
fleet capability.
Availability
| Surface | Tier | Residency | Notes |
|---|---|---|---|
zephr_session (MCP) | core | deferred | Create/list sessions; summarize beliefs for handoff |
zephr handoff (CLI) | — | — | Mint a signed Continuity v1.1 handoff packet |
zephr resume (CLI) | — | — | Import a packet via the shared import pipeline |
zephr prove (CLI) | — | — | Verify a packet and emit a provenance assertion |
zephr continuity (CLI) | — | — | Per-agent state + convergence score |
zephr receipts (CLI) | — | — | Export the installation's Slipstream audit receipts |
See the CLI reference for exact flags.
The Continuity Packet
The shipped packet is the v1 envelope (format: 'zephr-continuity',
formatVersion: 1, artifactKind: 'session-handoff'): a packet identity, a
source descriptor with scope, recipient intent, redaction and omission
manifests, retention metadata, an integrity manifest over the canonical
sections, and an authentication block. v1.1 additions stay inside
formatVersion: 1 — an optional envelope-level scope proof, activation
summary, and per-belief review state with code anchors. An envelope whose
formatVersion is not 1 fails validation with a structured
invalid_format_version error; no section is partially applied.
Shipped content is SessionHandoffContentV1:
- Session capsule — objective, completion criteria, accepted/rejected decisions with alternatives, constraints, changed files (with before/after content digests), verification evidence, open risks and questions, ordered next actions with blocking relationships, capture quality, limitations.
- Portable beliefs — belief content with review state and optional revalidation anchors (content hashes the destination re-checks on import).
- Portable artifacts — evidence sources and anchors, receipts, review events, and verification results.
- Transition and tool contract — the source-handoff transition and an
optional
allowedToolslist the destination MUST honor on resume.
Designed but not shipped content sections (see the continuity spec): the Dead-End Registry, World-state capture (worktree identity, dirty files with base blobs, untracked-file classification, environment fingerprint, running services, last-check results — by design an oversized dirty tree spills to artifacts rather than forcing the user to prune), the Attention map, and the Patch bundle applied by three-way merge. Handoffs today carry digests and receipt references, not those payloads.
Setup and data flow
zephr handoff <worktreeId> fetches the worktree's beliefs and mints a
session-handoff envelope signed with the installation's Ed25519 pack key,
then delivers it one of three ways: --file <path> writes a self-contained
offline packet, --registry publishes ciphertext to the cloud session
registry, and --claim-code prints a single-use code the recipient redeems.
Team-bound handoffs additionally require a recipient admission proof, and
PR/CI capsules (--capsule pr_resume|ci_resume) carry a workstream context
extension. Minting is fail-closed on secret material in belief content.
zephr resume <file|claim-code|packet-id> imports through the shared ordered
import pipeline: authenticate-before-parse (Ed25519 signature + recipient
HMAC over the raw bytes), single consumption, scope-proof verification,
destination tool contract, review-state rules, an instruction-injection
heuristic that demotes suspect beliefs, revalidation of code anchors, a
per-source belief import budget (40 by default), and apply. Non-confirmed
beliefs are surfaced as unverified notes, never silently promoted; moved
evidence demotes the affected belief and reports why. The pipeline ends by
emitting a signed transfer receipt, prints an honest degradation summary
(residue tools narrated or dropped, review-state notes, suspect or rejected
beliefs), and exits non-zero on a strict refusal. zephr prove verifies an
existing packet and emits a provenance assertion; zephr continuity reports
per-agent handoff state and a convergence score.
Persistence, security, observability
Packets are signed and human-readable — but not human-editable. Bytes that
no longer match the signature or the recomputed manifest root are refused with
a structured error (hmac_mismatch, fingerprint mismatch,
manifest_root_mismatch). Signing is the continuity format's own Ed25519
machinery over the installation pack key — it does not depend on the trust
capability's attestation primitives (which are not produced on any live path;
see Trust). issuedAt validation tolerates five
minutes of clock skew by default. Packet files live where you put them; the
local store they reference follows the topology in
Architecture and is
not encrypted by Zephr at rest. Observability: the
signed transfer receipts emitted on import are exportable via
zephr receipts.
Limits and failures
- The per-source belief import budget (40 by default) bounds a handoff: strict mode refuses an oversized packet before it is consumed; non-strict import truncates the excess and records the count on the receipt.
- Belief review state is respected on import: the default policy surfaces non-confirmed beliefs as unverified (never silently promoted); a refuse-unreviewed policy is available to adapters that require confirmed-only imports.
- Unknown
formatVersionmajor → structured refusal naming the required version; no section is partially applied. - Signature or manifest mismatch → refusal naming the failing check. There is no shipped "reseal" action — a hand-edited packet is refused, not repaired.
- Resume against moved evidence demotes the affected beliefs and reports why — nothing is silently dropped.
- Designed content (dead-end registry, world state, attention map, patch bundle) is absent from shipped packets — do not expect those sections on resume today.
Handoff and resume failures are covered in Troubleshooting.