Add HRC-001 Handoff Reachability & Causal Basis

[safal207]

What changed

Introduces HRC-001 — Handoff Reachability & Causal Basis, a framework-neutral executable contract for multi-agent status transitions and handoffs.

Core separation

HRC-001 keeps four facts distinct:

ownership epoch
causal read basis
recipient reachability
predecessor CAS

Load-bearing invariants:

• Ownership does not imply reachability.
• Unread predecessor is not the same failure as a CAS conflict.
• A diagnostic that exists but is not surfaced to the sender is not an operational signal.
• A handoff is not complete merely because a new owner was named.

Executable behavior

The reference evaluator distinguishes:

BLOCKED_UNREAD_PREDECESSOR
BLOCKED_CAS_CONFLICT
PENDING_REACHABILITY_UNCHECKED
BLOCKED_REACHABILITY_NOT_SURFACED
PENDING_UNREACHABLE
HANDOFF_DELIVERABLE
PENDING_RECIPIENT_ACK
HANDOFF_COMMIT_ALLOWED

Handoffs are two-phase. The current owner remains authoritative while reachability is checked. A reachable target makes the handoff deliverable, but ownership advances only after the target acknowledges the exact handoff event, target ownership epoch and predecessor.

Evidence origin

The motivating Claude Code #24798 discussion produced an intentionally asymmetric result:

• a live reachability failure was found in one contributor's logs: a handoff targeted a session with no running watcher and was undeliverable until manual startup;
• the proposed CAS-race class did not reproduce in the same low-concurrency logs; most observed stale writes were writers that had not read the thread to the end.

The contract preserves that distinction instead of turning the non-reproduction into either a universal safety claim or a universal race claim.

Conformance

Adds four JSON Schemas, a reference evaluator, and a 24-test falsification suite covering ownership epochs, causal basis, true CAS conflicts, surfaced reachability, expiry/unavailability, two-phase handoff and exact recipient acknowledgement.

Scope / non-claims

This is a bounded reference/conformance model. It does not claim watcher processes are the only valid reachability primitive, that READY guarantees successful delivery, that an observation cursor is truthful without trusted read evidence, that CAS races are universal, or that Anthropic/Claude Code has adopted the model.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9ee46159-e54a-42a3-90c9-cc54e1f1f2c3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[safal207]

Exact-head executable evidence

Canonical HRC-001 conformance is green on the current PR head:

head:     f38d45a67430c393f040702b1c1c360dbf3b9343
workflow: HRC conformance
run:      31876678326
event:    pull_request
result:   SUCCESS
suite:    24/24 tests

CI:
https://github.com/safal207/pythiaLabs/actions/runs/31876678326

The log explicitly exercises both distinct stale-transition classes:

test_04_unread_predecessor_is_not_misclassified_as_cas ... ok
test_05_true_cas_conflict_requires_coherent_prior_read_basis ... ok

and the live reachability boundary:

test_09_unsurfaced_diagnostic_is_not_operational_signal ... ok
test_15_deliverable_handoff_without_ack_is_not_committed ... ok

RESONANCE Article 12:
https://github.com/safal207/RESONANCE/blob/main/issues/001-age-of-agents/articles/12-a-diagnostic-nobody-can-see-is-not-a-signal.md

Evidence / non-claims:
https://github.com/safal207/RESONANCE/blob/main/issues/001-age-of-agents/articles/12-a-diagnostic-nobody-can-see-is-not-a-signal.sources.md

Executable proof addendum:
https://github.com/safal207/RESONANCE/blob/main/issues/001-age-of-agents/articles/12-a-diagnostic-nobody-can-see-is-not-a-signal.hrc-001-proof.md

The upstream low-concurrency non-reproduction of the proposed CAS-race class remains a preserved negative observation. This PR does not rewrite it into a confirmed production race.