Shipped in Spark Control v0.21.0: status badge + Update/Restart/Stop-Start/Logs
tile. All three exit criteria confirmed. matrix-bridge needed no code change.
- AGENTS.md: Current state + ROADMAP Phase 3 -> DONE; Deploy switched scp -> git
pull (Update button); D10 stamped; new Infra fact for the Spark->Gitea path and
the load-bearing IdentitiesOnly ssh-config pin the Update button depends on.
- spark-control-integration.md: trimmed from dev spec to live contract (dropped
sudo -iu fallback and dev-side scaffolding; folded in direct-as-modelo, the
Gitea key gotcha, restart cadence, and the LAN-only HTTP API).
- README: dropped stale "pre-Phase 0" status; Setup reframed for a fresh install.
Deferred follow-up: badge reflects container liveness only, not Matrix
connectivity; HEALTHCHECK + {{.State.Health.Status}} is the matrix-bridge-side fix.
docs/spark-control-integration.md: the SSH command contract (status via
docker inspect; restart via docker restart; update via git fetch + reset
--hard origin/master + docker compose up -d --build) plus the one-time
conversion of the Spark's ~/matrix-bridge to a Gitea clone. No bot code
change. Update source = git-pull-from-Gitea; rides Spark Control's existing
SSH into spark-32d0 (no new key). Corrected the infra note: Spark is on the
LAN with the Start9/Gitea host, so Spark->Gitea resolves directly.
Lift the load-bearing connectivity/identity/env facts out of the Phase 0/1 narrative
into a stable "Infra facts" section, rewrite Current state as a ~15-line snapshot, and
correct the Core flow diagram (gui-launch.sh / ask-claude.sh, not launch-claude.sh
directly). No operational context dropped — verified by a fresh-eyes doc review.
A message starting with `?` in a mapped room runs `claude -p` one-shot in that
repo on the Mac and posts the full answer back into the room — Matrix as a
request/response interface, not just a trigger. Non-`?` messages keep launching
interactive sessions as before.
New scripts/ask-claude.sh is a login-shell wrapper (so ~/.zprofile puts claude on
PATH) that exports CLAUDE_CODE_OAUTH_TOKEN from the Mac's .env and runs
`claude -p "$prompt" < /dev/null`, printing the answer to stdout. The bot adds a
`?`-dispatch with run_ask/ask: SSH stdout captured, 300s timeout, fail-loud, output
chunked under Matrix's event cap (no truncation).
Headless claude -p needs the long-lived token because a non-GUI SSH session can't
reach the login Keychain (reports "Not logged in") — the deliberate Approach A that
the interactive GUI-Terminal path (D11) avoided. Token is kept Mac-side only; the
Spark never runs claude. Sovereignty unchanged: claude -p uses the subscription, no
frontier API touches message payloads.
Proven live on the Spark; fresh-eyes reviewed before commit.
Add Dockerfile, docker-compose.yml, docker-entrypoint.sh, and .dockerignore
so the bot runs detached and survives reboots, replacing the foreground venv run.
The image is generic (no secrets/deployment specifics baked in): host networking
reaches both Synapse and the Mac; .env, config.toml, and the SSH key are mounted
read-only. The entrypoint is the container's environment seam (D4 analog of
launch-claude.sh) — it generates ~/.ssh/config for the mac-bridge alias from
config.toml [mac] (new hostname/user fields) so the bot's `ssh mac-bridge` stays
unchanged. SSH key mounted not baked; first connect uses accept-new host trust.
Proven live on the Spark: container connects to Synapse and real messages launched
drivable sessions on the phone across 2 rooms via the full chain.
- AGENTS.md: Commands now has the bot run/deploy (venv + scp from Mac); Layout lists
src/bot.py, gui-launch.sh, requirements.txt, .env.example; Current state refreshed to
Phase 1 (sub-steps 1-3 proven on the Spark; next = containerize).
- ROADMAP.md: log headless "ask" mode (claude -p -> output back into the room).
- src/bot.py: log in as the bot user with the stored token, prime past history,
and on a new message in a mapped room run `ssh -> gui-launch.sh` (built with
shlex.quote). The all-projects room fans out to every repo, each session named
"<repo> - <date>". Launch failures are reported back into the room.
- scripts/gui-launch.sh: propagate MB_SESSION_NAME into the launched session.
- requirements.txt: matrix-nio.
Connectivity (sub-step 1) verified on the Mac; launch (sub-step 2/3) to be tested
on the Spark, where the SSH alias resolves.
Phase 0 proven by hand (N=3) across multiple rooms.
- scripts/gui-launch.sh: open a desktop Terminal via osascript so claude runs in
the GUI session (login Keychain + real TTY), avoiding a long-lived token (D11).
- scripts/launch-claude.sh: name the session `claude -n "<repo> - <topic>"` so
Remote Control's phone conversation index is readable.
- .env.example: bot credential schema (real .env stays gitignored).
- AGENTS.md / ROADMAP.md: D11, Phase 0 results, Phase 1 carry-overs.
Keysat