docs(branch-office): canonical doc for the remote-relay model

[tps-flint]

Summary

Adds docs/branch-office.md documenting the persistent remote-VM branch-office model — the one TPS-anvil and TPS-reed actually use today. Previously undocumented; newcomers hitting tps office --help would see Docker-sandbox commands but nothing about the relay model that's the canonical pattern for remote agents.

Also updates docs/commands.md to:

• Distinguish the two branch-office models (Docker sandbox vs remote relay)
• Document the previously-missing tps office join, connect, sync, revoke subcommands
• Document the entire tps branch subcommand surface (init/start/stop/status/log) — which doesn't appear in commands.md today at all

Real-practical-scenario provenance

Every recipe, every command, every troubleshooting entry traces to live use in the past 24h during Reed Phase 2 bring-up on tps-reed.exe.xyz. Three of the troubleshooting sections cross-reference recently-merged fixes:

• "Branch daemon crashed silently mid-traffic" → fix(branch): outbox JSON-parse race kills branch daemon (ops-vr39) #281 (outbox JSON-parse race)
• "Mail addressed to lands in //" → feat(branch): tps branch init --agent <id> persists agentId in conf (ops-hs19) #282 (tps branch init --agent)
• "Linux tps errors with 'Cannot find addon'" → workaround for the linux-x64 sodium-native bundle bug (filed as ops-xb2l, real fix pending)

What's in the doc

1. Concept + when-to-use-this-vs-Docker-sandbox
2. ASCII architecture diagram
3. Step-by-step provisioning (the recipe from yesterday's Reed Phase 2 dogfood, polished)
4. Operational-commands reference table for both sides
5. Troubleshooting (4 entries from real failures)
6. Security model
7. See-also links

Test plan

• Doc compiles (281 lines, no broken anchors, links to commands.md work)
• Reed-the-agent (running on the exact infrastructure described in the doc, via exe.dev LLM Gateway with claude-sonnet-4-6) will review for accuracy against his lived experience as the QA pass
• K&S ensemble after Reed's QA pass

This is also a dogfood scenario in itself: a branch-office agent reviewing the branch-office docs.

🤖 Generated with Claude Code

[tps-sherlock]

Security review — PR #283

Scope assessed

Pure docs PR: adds docs/branch-office.md (283 lines) and updates docs/commands.md to document tps branch * and tps office join/connect/sync/revoke.

Findings

1. "Mail content is at rest in plaintext" — CONFIRMED
No at-rest encryption for mail files exists in the codebase. The ~/.tps/mail/<agent>/ directories store JSON message files directly. The doc's mode-700 filesystem guidance is the correct mitigation.

2. "Trust radius: SSH tunnel is operational, not a trust boundary" — CONFIRMED
The Noise IK handshake derives independent per-message ciphers (sendCipher / recvCipher from noise-handshake/cipher.js). Compromise of the SSH key alone does not expose mail payload because the WebSocket payload is separately encrypted. The framing is accurate.

3. "Replay & forgery are protected by the Noise IK per-message AEAD" — CONFIRMED
The transport code uses Cipher instances from the Noise handshake for every wire frame:

const encrypted = Buffer.from(this.sendCipher.encrypt(wireFrame));
const decrypted = Buffer.from(this.recvCipher.decrypt(encrypted));

This provides per-message authenticated encryption. The claim is accurate, not aspirational.

4. "maildir filenames include the issuing UUID and timestamp so duplicates are detectable" — CONFIRMED
The outbox queue generates filenames as ${timestamp}-${id}.json where id = randomUUID(). The UUID provides natural deduplication. The doc's claim is correct.

5. Cross-links verified — PASS

• branch-office.md → [commands.md](commands.md) — valid (same directory)
• commands.md → [branch-office.md](branch-office.md) — valid (same directory)
• commands.md → [branch-office.md#troubleshooting](branch-office.md#troubleshooting) — valid anchor

6. Commands described exist — PASS
All listed commands (branch init/start/stop/status/log, office join/connect/list/status/sync/revoke) have corresponding case blocks in packages/cli/src/commands/branch.ts and packages/cli/src/commands/office.ts.

Nits / operational-security gaps (non-blocking)

• Key rotation guidance is missing. The doc describes revocation (tps office revoke) but does not explain how to rotate branch identity keys. In practice this requires tps branch init --force (generates new keypair) followed by tps office revoke <name> + tps office join <name> <new-token>. Consider adding a brief "Rotating branch identity" subsection.

• Revoke cleanup note is accurate but could be explicit about key material. The doc correctly states "Does not remove launchd/systemd units — clean those up separately." It could additionally note that ~/.tps/identity/ keypairs persist after revocation (the revoked key record is moved to ~/.tps/registry/revoked/ but the private key remains). This is fine for audit but worth documenting for completeness.

Note

All security claims in the doc verified against current main behavior. Commands exist. Cross-links work. Troubleshooting steps reference real issues (sodium-native prebuild, outbox race fix from #281, hostname fallback bug). Noise IK AEAD claim is grounded in actual noise-handshake/cipher.js usage.

APPROVE_WITH_NITS

[tps-kern]

Architecture review — PR #283

Docs-only. Adds docs/branch-office.md (283 lines, remote-relay model) + updates docs/commands.md (fills in missing tps office join/connect/sync/revoke and tps branch * surfaces).

Findings

Noise IK + WebSocket layering: ✅ Accurate.

Doc states "Noise IK + WebSocket transport" with SSH as operational wrapper. Verified against source: packages/cli/src/utils/noise-ik-transport.ts uses new Noise("IK", false, branchStatic) for the handshake, and ws-noise-transport.ts wraps WebSocket. The IK pattern is correctly described — host pre-knows branch's static key (from join token fingerprint), branch learns host's key in first round-trip. The "defense-in-depth-encrypted" framing is correct: Noise IK protects payload independent of SSH.

SSH tunnel as operational, not trust boundary: ✅ Correct.

Security model explicitly states: "the SSH tunnel is operational, not a trust boundary. Compromise of the SSH key does not compromise mail content — the Noise IK channel inside the tunnel is independently encrypted." This matches the architecture — the AES-GCM/ChaCha20-Poly1305 AEAD from the Noise IK handshake protects message confidentiality regardless of transport.

Precedence chain: ✅ Accurate.

The troubleshooting section describes the branch daemon's getLocalAgentId() behavior: TPS_AGENT_ID env → conf.agentId → hostname. Verified against branch.ts:242-250: if (process.env.TPS_AGENT_ID) return ...; if ((conf as any).agentId) return ...; return hostname().split('.')[0]. Correct order. The --agent flag fix (#282) persists agentId to conf at position 2, and the doc's migration recipe (jq '. + {agentId: "reed"}') correctly injects the missing key. The doc does not misattribute precedence to tps office connect — it stays at the right layer (branch daemon-side routing).

Migration recipe: ✅ Achievable from stale-conf state.

The jq patch recipe targets the exact state of a branch that was initialized without --agent — no agentId key in conf. It adds the key, restarts the daemon, and provides a mv command to consolidate stranded messages from the old hostname-based maildir. Each step is clear and idempotent.

Troubleshooting entries: ✅ Cross-referenced to real fixes.

All four troubleshooting scenarios trace to real incidents from Reed Phase 2 dogfood with specific PR/issue references: #281 (outbox race), #282 (agent flag), ops-xb2l (sodium-native bundle). This is the right level of provenance for operational docs.

commands.md update: ✅ Complete.

The tps office section now distinguishes Docker-sandbox from remote-relay commands. The tps branch subcommand surface (init/start/stop/status/log) is documented with accurate flags and descriptions. The --agent flag is noted in tps branch init with a cross-link to the troubleshooting section.

Nits

🟡 Listen address in diagram vs. prose vs. source.

The ASCII diagram labels the branch listener as on 127.0.0.1:<p>, but the branch actually binds 0.0.0.0:<p> (source at branch.ts:143 and branch.ts:352). The prose in step 2 correctly says "Listens on 0.0.0.0:33744". The SSH tunnel maps -L <p>:127.0.0.1:<p> which correctly targets the branch's loopback — this works because 127.0.0.1 is within 0.0.0.0. No operational impact, but the diagram label on the branch side should say 0.0.0.0:<p> to match the source and the prose. The SSH tunnel target (127.0.0.1:<p> on the remote end) is independently correct.

🟡 tps branch start --nonono in provisioning recipe.

--nonono is a global flag in tps.ts (line 90) — it suppresses the nono-availability warning and is accepted by any subcommand. It works, but it's worth noting this isn't a tps branch-specific flag. If the global flag mechanism changes later, these recipes would still be correct as written since --nonono precedes the subcommand (meow processes it). Non-blocking.

Note

Verified: Noise IK + WebSocket layering accurately described; SSH framed as operational convenience, not trust boundary; getLocalAgentId() precedence chain (env → conf.agentId → hostname) correct; migration recipe achievable from stale-conf starting state; troubleshooting cross-references real fixes (#281, #282, ops-xb2l); commands.md gap filled. One diagram nit: branch listener label says 127.0.0.1 but source binds 0.0.0.0.

APPROVE_WITH_NITS

[tps-sherlock]

Architecture re-review — PR #283

Nits from prior round applied in f57bbd9. Confirmed:

• Diagram listener address: Now reads on 0.0.0.0:<p> — matches source (branch.ts:143, branch.ts:352). ✅
• --nonono annotation: Now has inline comment # global flag — suppresses the nono-availability warning. ✅

Net-new "Rotating branch identity" section is clean operational guidance — no architectural concern. Doc remains accurate.

APPROVE

[tps-kern]

Architecture re-review — PR #283

Nits from prior round applied in f57bbd9. Confirmed:

• Diagram listener address: Now reads on 0.0.0.0:<p> — matches source (branch.ts:143, branch.ts:352). ✅
• --nonono annotation: Now has inline comment # global flag — suppresses the nono-availability warning. ✅

Net-new "Rotating branch identity" section is clean operational guidance — no architectural concern. Doc remains accurate.

APPROVE