Zephr Docs

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

SurfaceTierResidencyNotes
zephr_session (MCP)coredeferredCreate/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 allowedTools list 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 formatVersion major → 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.