[mubeda]

Closes #217

Implements the approved design docs/plans/2026-11-01-mcp-ssh-agent-clone-design.md. The user chose option A1 on 2026-11-01, and Codex reviewed the design over 3 rounds.

Update 2026-11-02 (back in v0.15.0)

• The design's Status line now reads "Approved by Mauro 2026-11-02 (option A1; Codex review, 3 rounds)".
• Merged main (feat(web): resizable Git Changes panes and next/previous change across files #241), with no conflicts.
• Fixed the Windows x64 failure (backend::tests::an_unparsable_operation_id_reads_the_same_on_both_transports: "SQLite online backup WAL checkpoint remained busy (163/163 pages)"). Refs Tests: harden load-sensitive web, device, desktop and queue tests seen in the v0.15 batch #263.
  • Cause: update preparation calls Database::checkpoint_wal. That ran PRAGMA wal_checkpoint(TRUNCATE) once and refused any busy result. Here every committed page was already in the database file, and only the WAL reset waited on a reader.
  • Fix: a busy result now passes only with non-negative counts and every page moved. Two cases still fail: busy with -1 counts, which means another checkpointer held the lock and nothing moved (found by Codex), and pages left in the WAL.
  • Tests:
    • a_checkpoint_that_moved_every_page_succeeds_while_a_reader_holds_the_wal failed before the fix with exactly CI's error, remained busy (52/52 pages), and passes now.
    • a_checkpoint_that_leaves_committed_pages_behind_still_fails passes.
    • a_busy_checkpoint_is_complete_only_when_every_page_moved covers each result case.
  • Checks: persistence:: and maintenance:: lib tests (122) pass, as do --test production_maintenance (16), cargo fmt --all --check and Clippy with -D warnings.
  • Codex: the review found the -1 case (NEEDS-FIX), which is now fixed and covered by the case test.

Changes

• The gate (A1): outside agents may clone ssh://[user@]host[:port]/path only if they already pass the Terminals gate: MCP on, Terminals on, effective ceiling Full access, and terminal:operate.
  • The terminal tools and the clone path share one predicate, mcp::control::acts_as_server_user.
  • Live settings and live session access are read for every clone, so turning Terminals off or a Take over applies to the next clone, through both the tool and the direct RPCs.
• Refusals:
  • Every other agent gets clone_ssh_not_allowed, naming the https:// equivalent for GitHub, GitLab, Bitbucket and Codeberg on port 22.
  • scp-like user@host:path and git+ssh:// are refused with the ssh:// spelling.
  • An SSH URL whose rewrite differs is refused, so the clone uses the URL as written.
• The pinned ssh command:
  • It runs with -F none and HostName=<checked public address>. HostKeyAlias is the host on port 22, or [host]:port on other ports.
  • The person's known_hosts is read but never written: StrictHostKeyChecking=yes, BatchMode=yes, UpdateHostKeys=no.
  • Only keys loaded in the ssh-agent are offered: IdentityFile=none with IdentityAgent=SSH_AUTH_SOCK. There is no proxy, control master or forwarding.
  • Stalls end on their own: ConnectTimeout=30, ServerAliveInterval=15, ServerAliveCountMax=4.
  • Paths are escaped for OpenSSH's own parser, then for Git's sh -c.
  • An inherited GIT_SSH_COMMAND, GIT_SSH, GIT_SSH_VARIANT or core.sshCommand is never used.
• Agent selection:
  • Linux and macOS: SSH_AUTH_SOCK when it is a socket.
  • Windows: Git's ssh with SSH_AUTH_SOCK, or the System32 OpenSSH client with the openssh-ssh-agent pipe.
  • With no agent, the clone fails with clone_ssh_unavailable.
• Failure messages: they name the plan's alias, port and known_hosts file. For an unknown host they include a trust command that uses the plan's HostKeyAlias. The reason is kept in the direct sourceControl.cloneRepository RPC too.
• Process ownership: ssh runs as Git's child in the existing supervised process group, so cancel stops it. A test asserts the ssh child has exited.

Validation

• node scripts/run-msvc.mjs cargo test -p bibcode-server --lib -- clone_policy mcp_tools_tests::clone: 34 pass (17 policy, 17 clone integration), 3 runs in a row.
• Real-ssh tests ran on both Windows clients (Git's OpenSSH 10.6 and Windows OpenSSH 9.5). They cover ssh -G reading the generated command, a silent server ending the clone without a cancel, and the trust command.
• Reverting to the HTTPS-only refusal, or removing the %% escaping, failed 14 tests. The reason test failed before its fix.
• cargo fmt --all --check, clippy -D warnings, vp check, vp run typecheck: pass.
• Manual runbook steps added to docs/testing/cross-platform-validation.md (step 15) and docs/testing/ssh-environments.md: real sshd, ssh-add -c, a host certificate, and ports 22 and 2222.
• Not run on this host: the Linux and macOS paths. CI's Linux lib tests are their first run.

Review

• Codex on the implementation, 3 rounds. They found the cancel test not proving ssh stopped, the RPC dropping the reason, and a Windows pid race in the test. All are fixed.
• UI.md: one wording fix, so the refusal says how to get access.
• Not run: an advisor review, because no advisor tool was available in this session.

Profiler coverage: ssh is a child of the supervised clone process group (cancel, the 24 h bound and reaping cover it); vcs.clone is already long-running. No URL user, key or known_hosts content is logged.
Docs: docs/reference/mcp.md, docs/user/mcp.md, docs/architecture/rpc-and-orchestration.md, plus the runbooks above.

Known limitations (from the design)

• A server that trickles data holds a clone until Cancel or the 24 h bound.
• An ssh-add -c confirmation dialog belongs to the person's agent.
• Host certificates verify on port 22 only.
• Jump hosts fail closed.
• A known_hosts path set elsewhere in ssh_config is not read.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YWW672NbkSQaa8cTJBLP3P

[mubeda]

Merged into v015/batch, which will ship as the single "BiBCode v0.15.0" PR to main. Its issues are closed by that PR. The branch is kept.