​

SPEC-038: Identity Resolution Guardrails — Bot Sentinel + Active-Session Exclusion + Reconnect & Operator-Gated Force

​

Version

​

Status

​

Origin

• A terminal restart within the 90s SessionStore TTL leaves the prior registration alive; the new Lafonda session was rejected with identity_conflict even though it was the same operator on the same machine. Pure UX friction — no security signal.
• The backend already accepted force=true on the register payload (since v0.1 §2.3) but the verb signature didn’t expose it AND there was no authorization gate. Any agent with the API key could silently preempt any other session by claiming an identity. That’s not “operator-only”.
• prism_start’s identity_conflict instruction text mentions a force path but the verb schema didn’t expose it, so agents got stuck.

​

§1 — Bot Sentinel Default (unchanged from v0.1)

​

§2 — Active-Session Identity Exclusion (amended)

​

§2.1 — Registration fingerprint

• machine_id already lives on controller_registrations (v0.1).
• process_pid is added in this revision: the OS PID of the MCP process at registration time, sourced from os.getpid().

​

§2.2 — Same-machine reconnect (silent)

• If process_pid matches: idempotent; refresh heartbeat, return existing registration. (Same MCP process re-entering — possible after a WS reconnect. No new session minted.)
• If process_pid differs: silent release-and-replace. The prior registration is marked released_at = now, release_reason = 'reconnect'. The new registration is inserted. No 409, no force required, no log spam — this is the terminal-restart path and should be invisible.

​

§2.3 — Cross-machine conflict (structured)

{
  "error": "identity_conflict",
  "identity": "Lafonda",
  "active_session": "<sid>",
  "registered_at": "...",
  "agent_surface": "claude_code",
  "machine_id": "mini1.home.lan",
  "same_machine": false,
  "suggestion": "Lafonda is active on mini1. Pick a different --as, wait for that session to wrap, or retry with force=true and operator credentials."
}

​

§2.4 — Operator-gated force preempt

• Request payload adds operator_id: str | None, operator_password: str | None (paired — both must be present when force=true).
• Backend stores per-tenant credentials: tenants.force_operator_id + tenants.force_password_hash (bcrypt). One pair per tenant for the Personal Install; multi-operator tenancy is a future spec.
• Validation: bcrypt-compare the presented password against the stored hash. The operator_id must equal the stored value (case-sensitive).
• Outcomes when force=true:
  • Credentials valid + cross-machine conflict → preempt the prior registration (release_reason = 'preempted_by_force'); accept new one. Identical to v0.1 force semantics, just gated.
  • Credentials missing/invalid → HTTP 403 + {error: "force_denied", reason: "<missing|invalid>"}. New session is NOT registered.
  • No conflict to preempt → force is silently a no-op (registration proceeds normally).
• Bot identity is NOT subject to force at all (Bot sessions don’t conflict).

​

§2.5 — Audit

​

§3 — Operator Credentials Setup

​

§3.1 — Storage

• Columns on tenants: force_operator_id varchar(128) NULL, force_password_hash varchar(128) NULL.
• Both nullable; tenants without credentials reject every force=true call regardless of payload (force_denied: not_configured).

​

§3.2 — Setup verb

• First call (no credentials yet): current_password may be empty.
• Rotation call (credentials exist): current_password MUST match the stored hash; otherwise HTTP 403.
• The verb is bootstrap-skipped (callable before prism_start returns, so an operator can configure creds on a fresh install without first having to bootstrap a persona).
• The verb NEVER echoes the password in its return; it returns {ok: true, operator_id, configured: true} or an error.

​

§3.3 — Plaintext handling

​

§4 — Implementation Surface

​

§5 — Verification

1. Same-machine, same-pid re-register → idempotent return.
2. Same-machine, new-pid re-register → silent reconnect; old reg release_reason='reconnect'.
3. Cross-machine no-force → HTTP 409 with same_machine: false.
4. Cross-machine force=true, valid creds → HTTP 200, prior reg release_reason='preempted_by_force'.
5. Cross-machine force=true, missing/invalid creds → HTTP 403 force_denied.
6. prism_set_force_credentials first call sets hash; second call without current_password → HTTP 403.
7. Bot identity force=true → no-op (no conflict to preempt).
8. Migration up-down clean on a fresh DB.

​

§6 — Decisions

• D1 — One operator per tenant: Personal Install pattern. Multi- operator force is a future spec; not in scope.
• D2 — machine_id is UX, not auth: trivially spoofable; we don’t pretend otherwise. Real auth is API-key + bcrypt + tenant scoping. This spec narrowly addresses honest-mistake collisions and gives cross-machine preempt an explicit operator gate.
• D3 — bcrypt on receipt: matches existing API-key handling; no new crypto primitive introduced.

​

§7 — Open Questions

• Q1: Should prism_set_force_credentials require an existing bootstrap session to call? Currently bootstrap-skipped to allow pre-persona setup; alternative is to force a Bot-bootstrap first. Resolution: bootstrap-skipped (D — installer flow needs this before any persona exists).
• Q2: Should the operator credentials live on tenant or on a separate operator table? Current design folds them onto tenant because Personal Install = one operator. A tenant_operators table is the right shape if we ever multi-operator; deferred.
• Q3: Should force preempt also work same-machine (skip the silent reconnect)? Currently no — same-machine is always silent reconnect. Alternative: respect explicit force=true even same-machine for audit-log emission. Deferred — silent path is the common case.