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.