box/docs/MUSE-AUTH-CLI.md

MUSE-AUTH-CLI Decision Record

Status: Final — accepted 2026-10-07 (user chose "accept Final with a recorded amendment," waiving done-means item 3; see Amendment A1).

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). D1–D11 full text never arrived; per Amendment A1 the item is WAIVED, not verified — the decisions' substance stands proven by shipped, tested implementations (resume pool, session bind, P1/P2) plus live verification (2026-10-07: 27/27 unique session IDs, workspace scoping exact, refs resolve, profiles annotate).

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) — WAIVED per Amendment A1

Full decision text was settled in the prior session but never arrived in this checkout. Waived: re-verification by transcript would add words, not evidence. If the original text surfaces and contradicts built behavior, built behavior wins unless a new interview reopens the item.

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.

Amendment A1 (ACCEPTED 2026-10-07 with Final)

Done-means item (3) ("D1–D11 text verified or re-settled") is WAIVED. Rationale: the decisions' substance is verified by shipped, tested implementations and live checks, not by recovering the lost transcript. Recorded per the scope contract: this amendment is the explicit owner approval for the narrowed completion boundary. U1, P1, P2, P3 stand as settled; implementation and U2 remain separate stages.

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.

Cross-agent note (2026-10-07, factual, no decision change): the peer's wrapper is DEPLOYED as muse-code (symlink to ~/Account(s)/muse_wrapper.py); 3 live sessions observed bound under it (profile def), alongside unbound direct-muse-bin sessions. Peer monitor daemons were absent on inspection; a fingerprint one-shot showed all sessions in sync (no drift, nothing written). Monitor reliability is the peer lane; reap-by-scan stays the immune complement. The original D1–D11 text was recovered (peer's MUSE-AUTH-CLI.md) and reviewed: no contradiction with built behavior; the A1 waiver stands. Convergence proposal (open): peer adopts a bind record, NetVM reap learns the peer dirname pattern.