feat(identity): add durable principal identity primitive

[zane668]

Summary

• add the v18 durable principal schema and exact principal-to-instance binding primitive
• assign a fresh principal on every successful instance creation path and expose exact lookup/list fields
• fail closed on torn or conflicting claims, and roll back provisional principals when a launch never becomes live
• preserve existing v17/v18 data and keep older v18 binaries able to read and use the database

Scope

This is the P1 data and creation layer from #86. It intentionally does not add send authorization, vanilla re-attachment, tracked-resume retention, or stop semantics. Those remain separate follow-ups, including #87.

The branch is based on current main. Existing upstream CI baseline failures are isolated in #91; this PR does not duplicate those unrelated fixes.

Verification

• cargo test --locked: 2013 passed, 0 failed, 15 ignored
• cargo fmt --check
• cargo clippy --all-targets -- -D warnings
• v17 to v18 in-place migration and existing v18 principal-row preservation
• hcom 0.7.23 binary against a new v18 database: list, send, and events pass without changing principal rows
• failure injection for process binding, backend launch, principal creation, and conflicting/missing binding states

Closes #86

[aannoo]

@zane668 Thanks for the pr but I don't get like what's the point of the principal identity thing - isn't it the same as what the name is? what do you need it for?

---

AI review:

Review — PR #92: durable principal identity (P1)

feat(identity): add durable principal identity primitive · zane668 · +1275/−57
Closes #86 (RFC). Stacked follow-up: #93 (retains principal on tracked resume, closes #87). Motivated by #85 (stale session_id on peer queries).
Reviewed at pull/92/head. Findings are from code reading; cargo not re-run.

Verdict

Do not merge — close with #86/#87. Even with the bugs below fixed, this is 1275 lines of permanent, non-reconstructible data machinery with no runtime consumer. Its cost is front-loaded and irreversible; its only present capability is one inspection field. The problem that actually prompted it (#85) is fixable directly without any of this.

If a concrete consumer that needs exact-incarnation identity is already committed and imminent, "fix then merge" becomes defensible. Absent that on the roadmap, the sequencing is inverted: build the primitive after the thing that needs it, not before.

Why not, even bug-free

• Cost is permanent and front-loaded. A v18 schema migration that can't be cleanly undone; a principal_bindings table that is self-generated and not re-derivable from anything (so it becomes a backup/retention obligation forever); a second identity namespace to document alongside process_id/session_id; and a mint invariant smeared across five creation paths (launcher / start / instance_binding / pidtrack / hooks) that the next path will also forget — findings 1 and 3 below are that failure mode already happening.
• Benefit today is zero. principal drives nothing — not send, routing, stop, kill, or authorization. The whole consumer surface is hcom list --principal (src/commands/list.rs). The "which incarnation was this" question it answers is already answerable from (device_id, creation_event_id) or the name.
• Sequencing is inverted. hcom list --json session_id can diverge from a session's live session id (after /resume or fork) #85's real pain is that list --json <peer> returns a launch-time session_id snapshot that drifts. That's fixable directly (expose last-observed value + freshness/source) with no new namespace. PR feat(identity): add durable principal identity primitive #92 builds the RFC: durable principal ID and session mapping #86 foundation perfectly before the consumer exists, and feat(resume): retain principal on tracked resume #93/RFC: tracked hcom resume retains principal #87 stack more on top of it.

If it is fixed anyway — three blocking findings

All three confirmed at source.

1. [P1] Recreated instance rows lose their principal, unrepairably

src/instance_binding.rs:372 recreate_instance_from_placeholder rebuilds the canonical row via initialize_instance_in_position_file with no principal → instances.principal = NULL. Called on both rebind paths in bind_session_to_process (:460 canonical-exists, :559 restore-stopped). The SessionStart hook (src/hooks/claude.rs:599) invokes it and mints nothing afterward for regular agents (ensure_subagent_principal is subagent-only).

After a stopped-session resume or session-switch merge, the live row has principal = NULL while the durable principal_bindings row survives — a torn state that is stuck: create_principal_binding (src/db/principals.rs:51) bails when a binding exists but the column disagrees, so nothing repairs the column later. list --principal then reports the live instance as principal-less. Breaks the stated invariant that every creation path persists a principal.

Reachability caveat: the tracked-resume-same-name case short-circuits at :411 and is fine; the gap is on restore-after-stop and session-switch paths.

2. [P1] Concurrent v17→v18 migration can archive freshly-written v18 data

The v18 migration SQL (src/db/mod.rs:53-63) is not idempotent — bare ALTER TABLE instances ADD COLUMN principal, CREATE TABLE principal_bindings, CREATE INDEX, none with IF NOT EXISTS (contrast init_db at :226-233, which guards all three). try_apply_migrations (:657) runs a deferred transaction and never re-reads user_version.

Race: processes A and B both read v17; A migrates and commits v18; B — already past its check_schema_compat v17 read — runs try_apply_migrations(17), hits duplicate column name: principal → Err → ensure_schema (:393-405) falls straight through to snapshot + archive with no schema re-check between the failed migration and the archive. B archives A's valid v18 DB, destroying the non-reconstructible principal_bindings. Realistic in hcom, where many agents/hooks open the DB at once on first upgrade. Fix: idempotent v18 statements and re-check user_version immediately before archiving.

3. [P2] ensure_subagent_principal trusts the column, not a Resolved lookup

src/hooks/claude.rs:1665 returns Ok(()) as soon as principal_for_instance finds a non-empty instances.principal column — it never confirms principal_bindings agrees. In a torn state (e.g. from finding 1, or corruption) it treats a claim-without-binding as satisfied and skips minting. Same shape in the orphan path (src/commands/start.rs:373). Lower severity because create_principal_binding writes column+binding atomically, so they can't diverge under normal operation — this is fail-closed hardening; gate on lookup_principal(...) == Resolved.

Secondary design notes

• Doesn't fix hcom list --json session_id can diverge from a session's live session id (after /resume or fork) #85. PR feat(identity): add durable principal identity primitive #92 adds a parallel id rather than refreshing session_id; hcom list --json session_id can diverge from a session's live session id (after /resume or fork) #85 remains open and should be solved on its own.
• "Fork" is underspecified. The RFC's "every fork gets a new principal" means hcom fork (new process). In-tool native forks (codex /fork, omp /branch) rotate the session within one process/instance and keep the principal. Not a code bug, but the term needs pinning down before the model is called complete — and feat(resume): retain principal on tracked resume #93/RFC: tracked hcom resume retains principal #87 layer retention semantics on the same ambiguity.
• Central admission gate. Minting scattered across five paths is exactly what produced findings 1 and 3. A single validated admission gate (create + bind + rollback in one place) would prevent the next path from omitting the invariant.