execution flow

the host polls git for changes. when new diffs appear, it runs tree-sitter semantic analysis (Go, Dart) to classify chunks, then parses them into diff cards (file-level or chunk-level) with risk scores. cards are streamed over websocket to the mobile client in risk-first order. you review each card and accept or reject.

validation stage

• content hash checked against working tree to detect staleness.
• atomic writes with base version checking -- prevents overwrites when the file changed externally.
• conflict reconciliation when multiple changes target the same file.
• operations are idempotent -- reapplying the same card is a no-op.
• binary files are flagged but not diffed.

rollback behavior

1. accept stages the change into the working tree.
2. reject restores the file to its previous state.
3. undo reverses a previous accept or reject -- works at both file and chunk level.
4. stale-state refresh: if the working tree diverged, cards are re-validated before apply.
5. errors are explicit: "hash mismatch", "file deleted externally", "patch conflict".

connection issues

• run pseudocoder doctor to check host health and network reachability.
• confirm tailscale is connected on both devices (if using tailscale).
• run pseudocoder host status to verify the host is listening.
• re-pair with a fresh code if the device was revoked or the code expired.

terminal sync

• run pseudocoder session list to see active sessions.
• check tmux state if using a multiplexer.
• history buffer defaults to 5000 lines; configurable in config.toml.

common errors

• pairing code expired: codes are valid for 2 minutes. generate a new one with pseudocoder start --pair.
• trust mismatch: hard-block triggered when device trust state is inconsistent. re-pair from scratch.
• rate limited: pairing attempts are limited to 5 per minute per ip. wait for the cooldown to expire.
• chunk stale: the file changed since the diff card was created. refresh and retry.
• tls cert error: regenerate certs with pseudocoder doctor --fix-certs.

pairing flow

device pairing follows a staged flow:

1. scan: scan the QR code or enter the code manually.
2. verify trust: check device trust state. if mismatched, hard-block and require re-pair.
3. submit: send the pairing code to the host.
4. result: on success, the device is registered. on failure, you get a clear error and can retry (5-attempt cooldown).

codes are 6-digit, single-use, and expire after 2 minutes. bcrypt-hashed at rest.

session lifecycle

• multi-session support -- multiple concurrent sessions on the same host
• pseudocoder session attach-tmux <name> -- attach to a running tmux session
• pseudocoder session detach -- detach without stopping the session
• pseudocoder session rename <new-name> -- rename for organization
• clear history per session