mcode-sl/docs/DECISIONS.md

DECISIONS

Stable IDs; newest at the bottom. Each records context, choice, alternatives, consequences.

D1 — Vault-first credentials, api.zai direct; credential.json fallback

• Context: the Aygea Claude statusline used ~/.secretvault/credential.json (url + clientKey → vault.itsaygea.com proxy). The user wants this repo public and machines to need nothing but their existing SecretVault (zai_api_key).
• Choice: read zai_api_key via secretvault run (name from env, default zai_api_key), hit https://api.z.ai/api/monitor/usage/quota/limit; fall back to credential.json → ${url}/proxy/zai/.... Key reaches curl via a 0600 header file (--header @file), never argv.
• Alternatives: bake the proxy URL + require credential.json everywhere (rejected: repo would document private infra as a requirement); store JSON {url,key} in the vault (rejected: existing secret is a plain key).
• Consequences: one secret per machine is the only setup; trial mcode-endpoint-key-pairing-2026-10-19 pins the pairing. Proxy users still work.

D2 — mcode statusline mechanics (verified facts, release-pinned)

Confirmed by reading the 0.6.12 bundle — re-verify after every mcode update. Files (SHA-256): chunks/launcher-AVQRYDKB.js 2c4337e3…edfbe3, chunks/chunk-X3PES5WL.js 600c23d…09ee5 under ~/.minimax-code/releases/0.6.12/lib/node_modules/@minimax-ai/code/.

• Config source: <dataDir>/config.yaml → tui.statusLine (array) + tui.customStatusLine (Pv() in launcher chunk).
• Valid statusLine items: current-dir, session-title, git-branch, review-link, plan-mode, approval-mode, model-with-reasoning, model, context-window, subagent, token-quota, cache-read-ratio, context-remaining, context-meter, custom-command.
• Custom command runner: only active when custom-command is in statusLine and build-mode is not; command required (non-empty). Schema: display: inline|block, position: above|below, colorMode: plain|ansi, intervalSeconds (default 0 = off, clamp ≥10), timeoutMs (default 5000, clamp 500–30000), block maxLines default 3 (clamp 1–5).
• Invocation: {command} parsed + spawned with cwd = workspace_dir, JSON on stdin ({protocol, event: startup|interval|session-change|workspace-change, session_id, workspace_dir, model, session_title, tui_version}), stdout capped ~8 KiB (exact cap expression Q1 not disambiguated: 8*1024 vs 8e3 — inferred). stdout becomes the custom-command item only on exit 0 without timeout; inline mode renders the first line; colorMode: ansi keeps escape codes when the terminal color level > 0, strips otherwise.
• Consequence: our script must be silent-fail (exit 0, empty output when unknown) and must not rely on stdin content.

D3 — mcode is the scheduler; refresh decoupled in-process

• Context: the Claude statusline needed a systemd timer because Claude Code has no interval hook. mcode's customStatusLine.intervalSeconds re-runs the command itself.
• Choice: no cron/systemd. On each call: fresh cache (≤150s) → print; stale → spawn detached (setsid, fallback & disown) flock-guarded refresh (--refresh-bg) and show the still-valid value (≤360s) or nothing.
• Consequences: zero extra services; segment self-heals; offline machines just hide the segment after 6 min. Timer coexistence is harmless (same cache file).

D4 — Shared cache with the Claude Aygea statusline

• Choice: keep schema {pct, reset_iso, ts} at ~/.cache/aygea-sl/quota.json exactly as the Claude refresher writes it (reset written as local ISO; epoch conversions have GNU/BSD branches).
• Consequence: both ecosystems interop; any writer refreshes both. Constrained the parser to ISO strings instead of the internally simpler reset_ms.

D5 — Config merge safety rails

• Context: user requirement: atomic, previous-entry aware, must never break a config holding API keys. Two early bugs (in-place write; backup taken after merge) proved the point.
• Choice: python3 stdlib line surgery limited to the tui: block; refuses multiple tui: blocks or duplicate keys; validates result (structural + PyYAML when available); writes temp + fsync + os.replace; preserves mode (0600 for new); timestamped backup copied before first modification; byte-exact elsewhere (incl. trailing newline).
• Alternatives: PyYAML full round-trip (rejected: reformats/comments lost); yq (rejected: extra dependency on every machine).
• Consequences: merge is monotonic and reviewable; docs/FEATURE-MATRIX.md gates remaining platform risk.

D6 — Public repo + Gitea over SSH port 2222

• Choice: repo git.itsaygea.com/admin/mcode-sl (main); remote via SSH; the curl one-liner points at …/raw/branch/main/install.sh. No secrets in the repo by design (D1).
• Consequences: see AGENTS.md → "SSH to Gitea" for the port-22 incident record, accepted host-key fingerprint, and the repeat guard.