Repository navigation
Port peer/ to a plugin (P1.4), with durable delegation #127
Copy link
Copy link
Open
Description
Proposal
Parent: Phase 1a item P1.4 (2.7k LOC). Depends on plugin-repo-layout.
Why
peer/ is the agent-to-agent surface: the peer registry, message envelope, the Claude
Code sidecar (peer/claude/), and delegation (peer/delegate.ts). It works live today
(see the review-* finding worktrees), which makes it the least disposable of the fork
areas — porting it well matters more than porting it fast. Two known defects migrate
with it:
peer/delegate.ts's pending-task reply registry is process-local memory — it cannot
be the sole authority for durable delegation (charter §8.4). This is fixed during
the port, not after (evaluation P1.4).- Peer content is untrusted unless authority is verified (charter §14.1) — carried in
lead-authority; the port must not weaken envelope/session-identity checks along the way.
What Changes
- Port the peer tools into the
skein-peerplugin package via thetooldomain;
the sidecar process lifecycle becomes plugin-owned (spawn/cleanup rules move with it). - Move delegation correlation from the in-memory reply registry to durable storage
(plugin-owned; store choice recorded in design.md): durable task IDs, correlation
IDs, deadline, retry policy, and a committed outcome ledger. - Delivery semantics per charter §8.4: at-least-once when retries are involved,
idempotent processing, exactly-one committed outcome per work item via transactional
state change; duplicate deliveries deduplicated on replay. - Keep
peer-conversation-reliabilityas the reliability spec this implements; the
runtime it assumed (fork internals) is replaced by plugin surfaces with the same
guarantees.
Non-goals
- No new peer protocol format; the existing envelope works and rewriting it to claim
protocol compliance is charter-§5-forbidden. - No review/claims logic here (P1.5 owns loop/crew state systems).
Risks
- Sidecar orphaning on plugin reload — the fork learned this (
sidecar-orphan-cleanup
landed); the port must reproduce that cleanup or adopt its successor before going live. - Durable storage inside a plugin keeps the in-process coupling question real (K3); the
ledger writes must be crash-consistent under the isolation test evidence.
Impact
skein-peer plugin + durable delegation ledger + re-pointed peer tests. Removes one of
the two deepest fork-internals dependencies that autonomy depends on (the other is the
loop, P1.5).
Tasks
Depends on plugin-repo-layout (isolation proof) for the ledger design; do not invent
a second delegation mechanism.
- 1.1 Port peer registry and message envelope into
skein-peer; tools via the
tooldomain; keep session identity + verified-authority checks intact. - 1.2 Port
peer/claude/sidecar; absorb thesidecar-orphan-cleanup-era orphan
rules as plugin-owned lifecycle; kill-test orphaning on plugin reload. - 1.3 Replace the in-memory pending-reply registry: durable correlation record
(task ID, correlation ID, deadline, attempt count, committed outcome), written in
design.md and exercised with a crash-mid-round-trip test. - 1.4 Delivery semantics: at-least-once with dedup on replay; a repeated delivery of
the same task commits exactly one outcome (tests both directions). - 1.5 Re-point existing peer tests; adding durable semantics does not change
observed behavior for happy-path conversations (envelope unchanged). - 1.6 Record the ledger's storage choice + crash-consistency argument in design.md;
cite the P1.1 isolation evidence. - 1.7 Disposition of fork-side
peer/recorded for P1.7.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Activity