box/docs/MUSE-AUTH-CLI.md

MUSE-AUTH-CLI Decision Record

Status: Draft — taken over in this checkout 2026-10-07 per user choice. Only explicit user acceptance moves this document (or any decision) to Final.

Handoff note: a prior grill session settled D1–D11 and U1 and reportedly marked its own record Final, but that file lives in another checkout (absent here; this repo has no MUSE-AUTH-CLI.md, PI-AGENT-AUTH.md, OPERATORS.md, or agy-auth-switch). D1–D11 details below are CARRIED, not verified — their full text needs a paste or peer handoff before this record can go Final.

Goal

Define the muse-auth CLI: per-profile credential switcher (~/.config/muse/accounts/<name>/auth.json), tailnet push/pull of profiles between nodes, and a session spend logger — without stranding live sessions (the 2026-10-07 fleet-wide 400 outage was a mid-stream credential swap).

Non-goals (proposed)

• Implementation of muse-auth (needs a separate explicit request).
• agy-auth-switch validation (Track B, separate lane; PI-AGENT-AUTH.md is Final).
• OPERATORS.md amendment for agent-invokable keys (U2 follow-on, own delta).

Settled (from prior-session transcript, unverified here)

U1. Allowance reset period — SETTLED (calendar month)

Profile token allowances reset on the 1st of each month UTC, matching standard billing cycles (not a rolling 30-day window).

D10/D11. Agent-invokable key handling — SETTLED in principle, amendment pending

Decisions exist; codification as an OPERATORS.md amendment delta is the U2 follow-on and is UNRESOLVED.

D1–D11 (remaining detail) — CARRIED, text unavailable

Full decision text was settled in the prior session but is not present in this checkout. CARRIED as-is; paste or peer handoff required to verify. This record cannot go Final until they are quoted or re-settled here.

Scope contract (ACCEPTED 2026-10-07; user chose "accept the scope as written")

• Artifact boundary: IN — this decision record only. OUT — runtime code, tests, OPERATORS.md amendment, Track B validation.
• Done means: (1) push/pull file-set decision settled; (2) live-session guard decision settled; (3) D1–D11 text verified or re-settled; (4) user explicitly accepts this record as Final.
• Later stages (implementation, U2 amendment) each return for their own interview; accepting this record never approves them.
• "Go"/"do it all" authorize only the boundary above.

Settled Decisions (New)

P1. Push/pull transfer file set — SETTLED (Credentials + Metadata)

Transfer auth.json (cookies, tokens, session identity) and metadata.json (plan tier, spend watermarks, profile label). Ephemeral caches, runtime logs, and local locks are omitted from transfer. (profile.json in the earlier grill options was shorthand for this file and is superseded; confirmed 2026-10-07.)

P2. Live-session switch guard — SETTLED (Block with Force Override)

Refuse to switch credentials if active muse-bin or worker processes are detected holding the old profile identity. Operators must either terminate active processes first or explicitly pass --force to override, preventing mid-stream 400 outages caused by stale in-memory tokens. (Confirmed in this interview 2026-10-07.)

Pending

None. (All pending architectural decisions P1 and P2 are settled).

Session credential isolation (P3 — BUILT 2026-10-07, user-ordered)

Each muse session runs with an isolated config dir /tmp/muse-session-<pid>/muse: symlinks to ~/.config/muse/* except auth.json, which is replaced with the bound profile's credentials; refreshed tokens sync back to the profile on session exit/save.

Implications (unresolved): this largely obsoletes P2's block (switching stops disturbing live sessions; the guard becomes a backstop for legacy non-isolated sessions). Open risks: token sync-back races when two sessions share a profile (solved: newest-wins by mtime), sessions killed -9 never syncing (solved: reap-by-scan, no exit hook), symlink fragility (accepted: rebuilt per launch).

Implementation: bin/muse_session_bind.py (launch builds the dir and execs with XDG_CONFIG_HOME; save/reap sync back; status lists). Key integration choice: exec, not supervise, so panes keep their muse-bin identity and watcher coverage is untouched. Tests: tests/test_muse_session_bind.py (13). Follow-ups for the owning lanes: wire box runtime launch / resume-pool resume through the binder, and arm a reap timer once the profile store (P1) exists.