guru-connect/specs/v2-stable-identity/plan.md

v2 Stable Machine Identity + Session Reaping + Operator Removal — Implementation Plan

Status: planned 2026-05-30. Parent: SPEC-004 (v2 Phase 1/2). Builds on the v2-secure-session-core per-agent cak_ keys. Unblocks the fleet per-agent-key migration (task #7) → retire shared key (task #5).

Why now

Live evidence of the problem: connect_machines holds 15 persistent rows for 5 real hosts (DESKTOP-I66IM5Q ×9) — the duplicate-registration bug. Until the fleet is deduped, you cannot mint one cak_ key per real machine, so the shared AGENT_API_KEY can't be retired.

The core integration: machine_uid vs. per-agent cak_ key

Worked out against the current code so this composes with the just-built auth, not against it:

• Today: agent_id = random UUID from generate_agent_id() (agent/src/config.rs:90), persisted in the config file. Lost/missing config → a fresh UUID → a new row, because connect_machines.agent_id is UNIQUE and upsert_machine dedups on ON CONFLICT (agent_id) (server/src/db/machines.rs:101,111). Unstable id → duplicates.
• Per-agent keys already prevent duplicates for KEYED agents: a cak_ key binds to a connect_machines row via connect_agent_keys.machine_id, and reattach uses the key's machine identity, ignoring a client-supplied agent_id. The duplicate problem is the shared-key / support-code / config-loss fleet, which has no stable identity.
• machine_uid = deterministic hardware identity (Windows MachineGuid from HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid, hashed; optionally folded with a board serial), recomputable so a lost config self-heals to the same id. It is the IDENTITY (who this box is); the cak_ key is the CREDENTIAL (proof it's authorized as that box). They compose: one cak_ key per machine_uid = one key per real machine — exactly what task #7 needs.
• Security stance (unchanged from SPEC-004): a client-asserted machine_uid is spoofable, so it is not a trust boundary on its own. For keyed agents the cak_ key stays authoritative (server uses the key's machine, not the claimed uid). For un-keyed agents machine_uid is dedup-only (correctness, not trust). Reimage/clone caveats per SPEC-004 (MachineGuid regenerates on sysprep, clones collide — caught by the key binding).

Tasks (ordered; each Coding Agent + Code Review, gates green)

Task 1 — Agent derives + reports machine_uid

• New agent/src/identity.rs: machine_uid() = stable hash of MachineGuid (Windows; registry read), recomputable; non-Windows fallback = a persisted random UUID. Cache in config but recompute if absent (don't depend on the config file for correctness).
• Send machine_uid in the connect handshake (agent/src/transport/websocket.rs:40 query) and on AgentStatus (proto). Keep the legacy random agent_id as a migration fallback only.
• Tests: deterministic (same machine inputs → same uid); a wiped config recomputes the same uid.

Task 2 — Server schema + dedup on machine_uid

• Migration 008_machine_uid.sql: add connect_machines.machine_uid TEXT (nullable for legacy) + a unique index WHERE machine_uid IS NOT NULL. Idempotent; startup-applied.
• upsert_machine keys on machine_uid when present (ON CONFLICT (machine_uid)), falling back to agent_id for legacy agents. Session reuse / reattach key on machine_uid. The cak_ key's machine binding stays authoritative for keyed agents.
• Tests: same machine_uid with varying agent_id → ONE row; legacy (no uid) path unchanged.

Task 3 — Reconcile existing duplicate rows

• Prefer age-out + operator removal over a risky backfill (per the #7 audit note): once Tasks 4/5 land, the 14 duplicate ghost rows reap/purge naturally. If a deterministic collapse is wanted later, map duplicates by hostname→machine_uid and repoint sessions/keys — but only as a separate, reviewed migration. v1 of this plan does NOT auto-collapse.

Task 4 — Session lifecycle reaping (server/src/session/mod.rs)

• reap_stale_persistent(ttl) on SessionManager: periodic sweep (spawned at startup, ~60s) removing persistent sessions offline (is_online == false) past a TTL (default 10 min, via last_heartbeat_instant).
• On reconnect, supersede prior same-machine (machine_uid) sessions so a fresh agent_id can't strand the old one.
• Tests: offline-past-TTL reaped; online / within-TTL spared; same-machine reconnect supersedes; never reap an online or viewer-attached session.

Task 5 — Operator removal API + dashboard

• deleted_at on connect_sessions (+ machines as needed); DELETE …?purge=true (in-memory remove + DB soft-delete) distinct from the live-only disconnect; a bulk endpoint; per-row + multi-select removal on the dashboard machines/sessions views. Admin-gated, audited to events.
• This is also the immediate fix for the live ghost rows — once it lands, purge the 14 duplicates.

Exit criteria

One machine = one record/session; a config-loss or portable run can't duplicate; admins can purge stale rows individually and in bulk; the fleet is deduped enough to mint one cak_ key per real machine — unblocking task #7 (fleet key migration) → task #5 (retire shared AGENT_API_KEY).

Open questions

1. machine_uid recipe — MachineGuid alone vs. folded with a board/BIOS serial? (Proposed: MachineGuid primary, hashed.)
2. Should machine_uid REPLACE agent_id as the primary key, or sit alongside it (legacy fallback)? (Proposed: alongside, dedup prefers machine_uid; agent_id retained for legacy + transition.)
3. Reap TTL default (10 min proposed) and whether managed vs. support sessions differ.