​

SPEC-100 v0.1 — Loopback Diagnostic Verb + signal_type=Loopback

• Postmortem 07942a99 (2026-05-10) — Cherry signal 5b4a3344 sat in pending queue 40 min while drain returned empty; found via prism_signal_trace.
• This-session: Texi signal 3a241bdc reported delivered to Donna’s WS but never surfaced as a doorbell; only seen via operator-prompted prism_signals_pending drain.

​

Summary

​

Scope (v0.1)

1. New first-class signal_type=Loopback (added to _AGENT_SIGNAL_TYPES).
2. New verb prism_loopback_test(pid) — operator-invoked, runs against the calling persona’s session.
3. New CLI subcommand prism loopback-test — thin wrapper over the verb.
4. Shim-side ephemeral ring buffer that records metadata only for every received WS frame (so the verb has shim-receipt evidence to read).
5. Per-layer timestamp capture and a stable diagnostic envelope returned to the caller.

• Fix #1: receipt-at-shim guarantee — backend retries push until shim acks. Not in this SPEC; this SPEC only measures shim receipt.
• Fix #3: redis-first hot-path ordering — flipping signal_send SOR from PG to Redis per ADR-27. Not in this SPEC.
• Cross-surface differential probe (claude_code vs codex vs cursor) — single-persona scope here; surface comparison is a follow-up.

​

Background — the layer model

​

Contract — minimum (per Texi 2026-05-10)

​

C1 — Loopback envelope shape

​

C2 — Cross-layer correlation

• loopback_id (from payload)
• signal_id (assigned by backend on insert)
• trace_id (assigned by backend on dispatch)
• layer (one of the five above)
• observed_at (UTC ISO-8601)

​

C3 — Reply correlation

​

C4 — Result envelope (returned by prism_loopback_test)

{
  "loopback_id": "<uuid>",
  "outcome": "complete | partial | timeout",
  "missing_layers": ["shim_tee_receipt", ...],
  "layers": {
    "backend_write":         { "observed": true, "at": "<ts>" },
    "redis_publish":         { "observed": true, "at": "<ts>" },
    "shim_tee_receipt":      { "observed": false, "at": null  },
    "model_ack":             { "observed": false, "at": null  },
    "drain_seen":            { "observed": false, "at": null  },
    "reply_received":        { "observed": false, "at": null  }
  },
  "latencies_ms": {
    "write_to_publish":      12,
    "publish_to_shim":       null,
    "shim_to_drain":         null,
    "drain_to_reply":        null,
    "end_to_end":            null
  },
  "context": {
    "loopback_signal_id":  "<uuid>",
    "loopback_trace_id":   "<uuid>",
    "requested_by":        "Donna",
    "session":             "<uuid>",
    "surface":             "claude_code",
    "machine_id":          "mini3.home.lan",
    "started_at":          "<ts>",
    "completed_at":        "<ts>",
    "spec":                "SPEC-100"
  }
}

​

C5 — Shim tee log (ephemeral ring buffer)

​

C6 — CLI polls local shim for receipt evidence (v0.1 split orchestration)

• Backend issues the probe (POST /{pid}/signal/loopback-issue) and returns a partial envelope with backend_write + redis_publish populated.
• Shim exposes a local-only HTTP endpoint GET /tee-frames?loopback_id=<uuid> returning the matching ring entry or 404.
• CLI receives the partial envelope, polls the local shim endpoint up to shim_poll_timeout_ms (default 2000ms), waits up to drain_timeout_ms for evidence of drain (optional, model-side), and assembles the full SPEC-100 §C4 envelope.
• A successful shim match populates layers.shim_tee_receipt.observed=true. A timeout populates false and adds "shim_tee_receipt" to missing_layers.

​

C7 — CLI surface

prism loopback-test
  loopback_id: 7f3e2b94-...
  outcome:     partial
  layers:
    backend_write       ✓  +0ms
    redis_publish       ✓  +12ms
    shim_tee_receipt    ✗  (timeout after 2000ms)
    model_ack           —  (n/a)
    drain_seen          —  (not observed in 5000ms)
    reply_received      —  (not observed)
  end-to-end:           5012ms (timeout)
  missing layers:       shim_tee_receipt, drain_seen, reply_received

• 0 — outcome == "complete" (every required layer observed within timeouts)
• 1 — outcome ∈ {"partial", "timeout"} (one or more required layers missing)
• 2 — invocation/config error (auth, network unreachable, missing pid, etc.)

​

Implementation surfaces

​

Testing

• Backend: round-trip a Loopback signal in-process, assert all five layer entries in the result envelope, assert ring buffer matches.
• Shim: tee buffer rotation at 100 frames + 10 min boundary; metadata-only assertion (regression test against payload leakage).
• CLI: exit-code matrix (0/1/2) under all outcome states.

• Operator runs prism loopback-test from each surface (claude_code Donna session, codex Texi session, etc.) and captures the result envelope. Per-surface drop-rate baseline establishes the empirical layer-attribution dataset that motivates Fix #1 and Fix #3.

​

Migration / rollout

• v0.1 ships behind no flag (diagnostic verb, idempotent, observability-only).
• Backwards-compat: existing signal types unaffected; tee buffer is additive.
• Default-off invariant intact (Plan #10 gate): Loopback enum is always-on but verb produces no side effects beyond a single self-addressed signal per invocation.

​

Out of scope — explicit (pinned)

​

Cross-references

• SPEC-034 — agent-to-agent signal delivery (referenced baseline; not amended)
• ADR-27 — runtime state through SM (Redis-as-SOR for runtime state)
• docs/architecture/multi-store-writes.md — line 102 (signal_send SOR; reconciliation pinned to Fix #3)
• Postmortem 07942a99 — signals_pending vs trace divergence
• Memory: feedback_in_reply_to_uses_signal_id.md
• Memory: project_doorbell_render_miss_filed_2026-05-03.md

​

Open questions for v0.2

1. Push vs poll for shim-receipt evidence (C6). v0.1 polls; v0.2 may flip to push if Fix #1 is sequenced immediately after this SPEC. Texi to call.
2. Should Loopback delivery be exempt from coalescing? The shim today coalesces non-system signal types in the doorbell renderer. A Loopback that gets coalesced behind another doorbell would falsify a “shim received but didn’t surface” diagnosis. Default proposal: Loopback bypasses coalescing (treat as system-priority). Texi to call.
3. Multi-instance shim (worktrees). If a persona has multiple coder sessions running in different worktrees, which shim’s tee log is canonical? Default proposal: backend resolves via requested_by_session, polls only that session’s shim. Document the answer.