Fork and upstream differences¶
This document preserves detailed architecture and migration evidence from the upstream-porting audit. For the current user-facing product distinction, start with Comparison with upstream. The corresponding commit-by-commit decisions remain in Upstream commit review.
Historical comparison snapshot¶
The Phase 9 audit was performed against these immutable points:
| Role | Ref | Commit |
|---|---|---|
| Fork implementation audited here | feat/port-upstream-features-2026-07 |
10b645cbebf8e0f22e8004e62896549f31206326 |
| Fork branch baseline | main |
c40067a |
| Current upstream | upstream/main |
9f1484e880c01b64b320ce0105de6bee831821e7 |
| Shared historical fork point | merge base with upstream | e1f2dc0aa43ebcc72b5b47470daac446d7d02c8e |
This is the final Phase 9 architecture snapshot. Exact commit counts and diff statistics are intentionally omitted because later documentation-only closure commits do not change product parity. The fork and upstream are architecturally divergent: a filename diff alone is not a reliable feature comparison.
Executive summary¶
The fork is neither a strict subset nor a strict superset of upstream.
- Most shell, filesystem, job, remote-worker, transfer, terminal, Human UI, and OpenTUI outcomes from upstream exist in the fork, but are exposed through explicit agent/workspace sessions and a different module layout.
- The fork is materially ahead in session isolation, Agent Bridge integration, durable managed jobs, transactional cross-session copies, Windows support, worker-upgrade safety, browser-native operations UI, terminal streaming, and release/coverage enforcement.
- The migration has adapted the large-transfer transport, recoverable audit payloads, environment orientation, worker services, native OpenTUI packaging, and real browser E2E. Intentional remaining differences are structured public browser automation and multilingual documentation.
- Some upstream behavior should remain rejected: unredacted audit input retention, copying upstream release metadata, restoring obsolete one-tool-per- operation remote APIs, and removing the fork's active Agent Bridge.
Public MCP tool surface¶
The two projects often provide the same outcome through different public tools. The important mappings and actual gaps are:
| Upstream surface | Fork surface | Difference |
|---|---|---|
run_shell_tool |
bash |
Equivalent execution outcome; fork binds it to an explicit session and combines bounded command, async job, and PTY entry modes. |
run_python_tool |
run_python_code |
Equivalent outcome; fork keeps a separate structured helper but uses session ownership. |
shell_start, shell_send, shell_read, shell_kill, shell_list |
bash(pty=true) plus persistent-shell companions |
Equivalent outcome with a stable shell_id; fork additionally supports Windows ConPTY. |
job_start, job_list, job_tail, job_stop, job_retry |
bash(async_=true) plus unified job |
Fork also manages durable non-shell jobs such as background session_copy. |
read_file, grep_search, edit_file, todo tools |
read, search, hashline_edit/edit_lines, read_todos/write_todos |
Adapted to snapshot-grounded edits, selectors, pagination, and session ownership. |
Optional machine on many tools |
session_start(target="remote", machine=...) followed by ordinary tools |
Fork avoids duplicating local and remote schemas and gives every remote operation an explicit workspace session. |
transfer_path |
session_copy |
Functional transfer support exists; fork preserves synchronous compatibility, managed background copy jobs, and now an internal resumable HTTP transport for capable large copies without exposing upstream ticket tools. |
| Separate remote invite/list/revoke/rename tools | remote_admin |
Same control-plane outcomes through one compact tool. |
skills_list, skill_load, skill_read_file |
list_agent_skills, activate_agent_skill, read_agent_skill_file |
Similar static Skill outcome; fork additionally bridges configured MCP servers and dynamically installed capabilities. |
environment_info |
session_start and session_change_cwd return SessionStartOutput.environment |
The standalone tool is intentionally absent. Both local and remote sessions now return bounded typed runtime, workspace, tool, capability, and policy orientation; remote values are generated by the worker and preserved by the controller. |
audit_tail |
Session-bound audit_tail, Human UI, and native local/remote audit APIs |
The fork reuses its coalesced query engine, explicit sessions, worker RPCs, dedicated audit:read/audit:full scopes, and recoverable sanitized payload store instead of copying the upstream raw JSONL reader. |
browser_get_text, browser_capture, playwright_run_script |
No public structured equivalent; manual browser tooling can be invoked through session-bound bash |
Intentional remaining difference. This migration adds real browser E2E but does not add public browser automation tools. |
Capabilities present upstream but absent or incomplete in the fork¶
Decision table¶
| Capability | Upstream behavior | Fork behavior | Assessment | Recommendation |
|---|---|---|---|---|
| Structured browser automation | Local and remote browser_get_text, screenshot/capture, and arbitrary Playwright script execution with browser scopes and worker capabilities. |
No public browser automation tools are exposed; users can invoke browser tooling through session-bound bash, while dedicated Chromium E2E verifies the fork Human UI. |
Intentional remaining difference. Public browser automation was outside this migration and arbitrary scripts duplicate shell authority while adding profile, URL, process, scope, and remote-capability risk. | Keep absent unless a separate product/security review approves a bounded session-owned design. Do not infer public browser tools from the browser E2E dependency. |
| Real browser E2E for Human UI | CI installs Chromium and runs OAuth, PTY, navigation, responsive-layout, and related browser smoke tests. | A dedicated locked Playwright/Chromium job now starts the fork HTTP server and a real worker, then covers OAuth PKCE, Dashboard, Files, Todos, Audit, local/remote PTY, OpenTUI Console recovery, and responsive layout with retained failure artifacts. | Implemented (adapted). The fork tests its browser-native UI and machine/session model rather than restoring upstream public browser tools. | Keep the dedicated job isolated from the ordinary cross-platform pytest matrix and retain trace, screenshot, video, WebSocket, browser, server, and worker diagnostics on failure. |
| Worker OS service management | CLI installs, starts, stops, restarts, reports status, and reads logs for systemd --user and launchd agents. |
The fork now has an explicit local worker CLI, credential-free stable launcher, idempotent systemd-user/launchd lifecycle, typed status, bounded logs, verified update/restart integration, and Windows unsupported behavior. No MCP service-mutation tool was added. | Implemented (adapted). The fork preserves its private identity, source-only runtime, single-instance handoff, and local-only persistence boundary. | Keep Windows unsupported until a reviewed native service design exists; retain no-credential unit/plist and verified update invariants. |
| Embedded native OpenTUI in Python wheels | Platform-specific wheels contain a compressed native TUI runtime and are tagged non-pure. A normal platform wheel install can launch the TUI without Bun or a release sidecar. | Same-version native wheels now embed one bounded deterministic-gzip payload for Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x86_64. The universal py3-none-any wheel and sdist remain payload-free; Linux uses truthful linux_* tags rather than unaudited manylinux claims, and Windows arm64 awaits a native runner. |
Implemented (adapted). The fork preserves uv_build, explicit runner/tag verification, bounded private materialization, and sidecar/Bun fallbacks instead of copying upstream's inferred Hatchling hook. |
Keep the five-runner clean-install smoke, digest/magic/metadata checks, atomic publication, and no-payload universal fallback as release gates. |
| Public MCP audit query | audit_tail lets an agent inspect recent audit entries. |
A typed read-only audit_tail now selects local/remote targets through explicit sessions, returns bounded coalesced references/previews, excludes only its own current lifecycle, and resolves one retained sanitized payload by entry id. |
Adapted with stronger isolation and recovery semantics. | Implemented. Keep dedicated audit:read/audit:full, operation-sensitive Human UI checks, and entry-id-only full recovery. |
| Dedicated HTTP transfer transport | One-time URL-bearer upload/download tickets, streaming HTTP bodies, range validation, immutable download snapshots, and transactional commit. | session_copy selects local, same-worker, bounded RPC, or private HTTP streaming. The fork uses non-secret route ids plus separate hashed worker/direction/session-bound capabilities, durable cursor/spool state, exact replay, managed-job resume, quotas, and source-only stdlib clients. |
Implemented (adapted). Benchmarks showed material RPC/base64 overhead at 1 MiB and above, while the upstream credential-in-URL and in-memory ticket model did not meet fork security/recovery requirements. | Keep session_copy as the only public API; retain RPC/capability fallback, same-origin/no-redirect worker policy, immutable snapshots, digest/size/range checks, no credential-bearing URLs/logs/argv, and exact-route request-limit bypass. |
| Full oversized audit-payload recovery | Oversized values may be externalized into private gzip payload objects and referenced from bounded log entries. | Accepted sanitized values are stored as deterministic gzip canonical JSON under private quotas and represented by bounded content-addressed references; audit:full plus an entry id is required to recover one retained value. Values above the independent per-value limit remain explicit omissions. |
Implemented (adapted). The fork adds stronger redaction, canonical integrity, no-follow reads, expiry/retention accounting, local/remote session ownership, and access auditing. | Keep recovery bounded and opt-in through audit:full; never restore upstream no-redaction retention. |
| Multilingual documentation | Locale trees, translated navigation, and i18n regression checks. | One canonical English documentation site. | Documentation reach gap, with substantial synchronization cost. | Keep English-only unless maintainers commit to owning translation freshness. Generated or community translations should not silently become canonical. |
| Structured environment inventory | One read-only tool reports runtime, platform, dependencies, and machine information. | Both session orientation responses expose one bounded typed environment object with normalized probes and safe policy/capability fields. |
Adapted without expanding the public tool surface. | Implemented. Keep environment orientation session-bound so it matches the actual local or remote workdir and refreshes after cwd changes. |
Upstream behavior that should remain rejected¶
| Upstream behavior | Reason to keep it out of the fork |
|---|---|
| Preserve tool inputs without redaction | The fork intentionally redacts tokens, authorization headers, approval PINs, sensitive download URLs, and similar credentials. Debuggability does not justify raw credential retention. |
| Restore every legacy local/remote tool name | Explicit session_id ownership is clearer and prevents schema duplication. Unregistered names use the SDK-standard unknown-tool path rather than expanding the public surface. |
| Remove the dynamic Agent Bridge | It is an active fork feature, not dead plumbing. Removing it would eliminate installed Skill discovery, configured MCP-server bridging, and dynamic capability activation. |
| Copy upstream release/version commits | The fork has an independent 4.3.0 release line and release matrix. Functional commits should be reviewed independently of upstream version metadata. |
| Copy upstream WebUI/OpenTUI architecture verbatim | The fork deliberately keeps a browser-native Human UI as the default and treats OpenTUI as an optional client sharing the same APIs. |
Capabilities where the fork leads upstream¶
| Area | Fork advantage |
|---|---|
| Explicit workspace sessions | Every local or remote operation is owned by a stable session_id. Remote machine, worker session, workdir, lifecycle, and transfer routing are separated from persistent terminal shell_id and async job_id. |
| Agent Bridge, credentials, OAuth, and installed Skills | The fork discovers Skills, loads their instructions/files, lists configured MCP servers, invokes bridged MCP tools, resolves owner-private secret references, and acts as an OAuth client for HTTP/SSE upstreams with persisted refresh and local administration. It retains dynamic capabilities that upstream removed. |
| Unified durable jobs | One job surface manages shell and controller-managed jobs, persists output/payload/progress/result, detects lost processes, supports retry/cancel, and remains useful when a worker is offline. |
| Transactional cross-session copies | session_copy supports local/local, local/remote, remote/local, and remote/remote files and directories, same-worker fast paths, measured large-copy HTTP streaming, capability/RPC fallback, durable cursor/spool resume, transactional commit/abort, background managed jobs, and cancellation cleanup. |
| Worker upgrade security | Upgrade authority is the actual deterministic bundle digest. The worker enforces authenticated same-origin manifest/archive downloads and redirects, cache bypass, size/version/SHA validation, safe extraction, downgrade protection, atomic replacement/rollback, credential-free argv, and bounded retry. |
| Worker lifecycle robustness | Cross-platform single-instance locks cover enrollment, polling, jobs, and re-exec. POSIX inherits the lock descriptor; Windows adopts and reacquires the native handle. Poll deadlines are continuously negotiated. |
| Windows support | Native shell execution, ConPTY persistent terminals, Windows transfer identities and path behavior, process-detachment fixes, and full Windows pytest/VS Code/OpenTUI coverage are maintained as first-class behavior. |
| Browser-native Human UI | The default /ui is independent of terminal rendering and provides OAuth PKCE login, dashboard, remotes, local/remote files, copy/move/rename, todos, audit, and terminals with machine isolation and stale-response guards. |
| Multiple terminal clients | The fork supports tmux, Windows ConPTY, raw browser PTY streaming, resize, snapshots, optional native OpenTUI, and an authenticated browser OpenTUI console without changing the underlying shell identity. |
| Image handling | view_image is session-bound and remote-capable. Human UI/OpenTUI audit previews are bounded, and terminal image protocols can render inline images without unbounded decode or layout behavior. |
| OAuth and request hardening | S256 PKCE, bounded pending codes and request bodies, strong public-client credentials/reuse, bounded stateful MCP sessions, explicit scopes, and corrected safety annotations are integrated across the fork architecture. |
| File/download safety | Immutable private download snapshots, no-follow identity checks, bounded previews, symlink-aware serialized writes, snapshot-grounded hashline edits, and tokenized file links are composed with sessions. |
| Audit safety | Uniform redaction, bounded records, private payload objects, paired tool lifecycle events, scope-sensitive full recovery, and machine-aware views preserve forensic detail without unbounded raw retention. |
| Minimal MCP surface | Unregistered names use the SDK-standard unknown-tool path; the fork carries no aliases, hidden mappings, or custom removed-name behavior. |
| CI and release enforcement | The branch runs Linux/macOS/Windows tests, Windows ConPTY, OpenTUI on three OSes, verified platform-wheel build/install smoke on five native runners, VS Code packages on Linux/Windows, universal package/sdist smoke, Docker checks, release-matrix validation, branch-coverage ratchets, and bundled static tmux smoke on x86_64/aarch64. |
What this migration branch added¶
The baseline is main at c40067a; the final implementation snapshot is
10b645c. The migration commits fall into the following product decisions.
| Group | Representative commits | What was added or restored | Was it likely cut or absent before this branch? | Assessment |
|---|---|---|---|---|
| Agent Bridge and Skills | 82288d1 plus the current migration |
Hardened installed Skill discovery/loading, real Skill E2E, configured MCP-server discovery/invocation, owner-private static secrets, and MCP SDK OAuth client authorization/refresh/revocation. | Mostly fork-specific capability that upstream later removed as unused dynamic plumbing. | Keep. The capability is now an explicit product direction with private credential storage, fail-fast noninteractive runtime behavior, redacted status, and dedicated security tests; configured upstreams remain a trust boundary. |
| Durable jobs | 9d759e5, 02443a4 |
Persistent shell output, lifecycle recovery, lost-state detection, managed background copy jobs, retry/cancel/list/poll. | Fork-specific strengthening of upstream job and transfer work. | Keep. The stable session/job ownership model is coherent and materially improves long-running operations. |
| Remote worker persistence | d277517, 2a01281, 4bd1886, 733ec9a plus the current migration |
Identity/resume, inventory/admin, result heartbeats, safe auto-upgrade, process locks/handoff, explicit enroll/connect/run commands, and Linux/macOS user-service lifecycle. | Restores upstream worker persistence while preserving the fork source-only bundle and local-only service control. | Keep, with explicit trust acknowledgement. Auto-upgrade means an authenticated controller may replace worker code; digest/same-origin/rollback controls make this reasonable, but it is a major authority boundary. |
| Native image viewing | b5f4530, 029403e |
Session-bound local/remote image results, bounded previews, inline terminal image rendering. | Restores and extends upstream image/UI behavior. | Keep. Limits and first-frame decoding make the feature proportionate. |
| Audit hardening and UI | d8f176f, df21341, 9d875f7 plus Phase 5 |
Bounded/redacted retention, private recoverable payload objects, machine-aware audit UI, dashboard telemetry, and scope-sensitive full access. | Restores Human UI observability and useful recovery while rejecting upstream raw/no-redaction retention. | Keep. Preserve independent payload quotas, expiry, integrity checks, and audit:full authorization. |
| Immutable downloads and files | dc3a39a, 8cf017a, 6a94e71, 9d11cf2, af222ef |
Immutable download snapshots, browser file workspaces, copy/move/rename, remote workspaces, serialized symlink-safe writes. | Restores upstream Files UI and hardens it for fork sessions/remotes. | Keep. This is a coherent session-bound filesystem product rather than duplicated remote APIs. |
| Transactional transfers | 3ec0eae, eec5015, 962689c, 02443a4 plus Phase 8 |
Transaction begin/write/finish/abort, timestamp binding, same-worker fast paths, bounded RPC fallback, private resumable HTTP streaming, cross-worker spools, and resumable managed jobs. | Restores upstream outcomes through fork-native sessions and now adapts the useful HTTP transport without its URL-bearer/in-memory ticket design. | Keep. Preserve transport negotiation, durable security state, source-only workers, exact replay/digest guarantees, and the 1 MiB measured default threshold. |
| HTTP/OAuth/MCP safety | 824ae5, e103617, 067ae03, 0fc3fa1, dbe18d0, b977e5b, a37da3c |
Request-body limits, S256, pending-code bounds, client reuse/credentials, correct annotations, stateful-session caps, safer local interfaces. | Mostly security fixes and fork architecture hardening. | Keep. These are defense-in-depth changes with low product ambiguity. |
| Shell correctness | ab0b001, aa04036, 5cfa363, 8694314, 0dc21eb |
Shared stdout/stderr budget, timeout/watchdog cleanup, native Windows commands, missing-tmux compatibility. | Mix of upstream fixes and fork portability work. | Keep. These preserve compatibility and prevent resource leaks. |
| Persistent terminals | 60fa2f8, dd0c2e9, 6f14aec, a004089, 5bc8f22 |
Resize, browser console, remote terminals, raw PTY streaming, Windows ConPTY. | Restores upstream terminal UI and substantially extends it. | Keep if interactive terminals are intended. Raw terminal access is high privilege; loopback/OAuth/scope boundaries and session preservation must remain non-negotiable. |
| Browser-native Human UI | 4c6c0bc through 4813aa7, plus ceb6b30 and d9d3020 |
Human UI foundation, safe mounts, OAuth PKCE login, Files, Todos, Audit, Dashboard, Terminals, Remotes. | Reintroduces a UI capability that had been absent or cut, but uses a fork-native static implementation rather than upstream React architecture. | Keep if operator UI is a product goal. It is valuable, but maintaining native WebUI plus OpenTUI plus browser Console is a deliberate three-client maintenance commitment. |
| Optional OpenTUI | ae6a3e6, 29daeba, c6737d3 plus Phase 7 |
Adapted current upstream OpenTUI client and browser Console against fork Human UI APIs, then added same-version embedded platform wheels while retaining sidecar, Bun-source, and payload-free universal installation modes. | Restores upstream TUI presentation and ordinary platform-wheel installation without replacing the native browser UI or the fork packaging backend. | Keep only with explicit multi-client and bundled-binary commitment. Preserve the five native build runners, deterministic bounded payload checks, private materialization, and universal server fallback. |
| Windows compatibility | 5bc8f22, 8694314 through 5764e09 |
ConPTY, native job commands, stable file identities, path/error normalization, stdio/remote E2E, platform-aware tests. | Mostly new fork work needed by its expanded architecture. | Keep if Windows is supported. The CI investment indicates that it is already a first-class target. |
| CI, coverage, and release artifacts | 8481d1f, e4e52f8, e9dbc32, a350752, 6fbc0bb plus Phase 7 |
Unified full pytest matrix, branch coverage ratchet, merged platform baselines, bundled static tmux for Linux releases, payload-free universal packages, and five verified native OpenTUI wheels published atomically. | Fork-specific maintenance and distribution work. | Keep, but explicitly accept bundled-binary supply-chain ownership. Retain pinned source/tool versions, truthful platform tags, checksums, clean-install smoke, and no generated payload in the sdist/universal wheel. |
| Removed-name compatibility layer | a494f54 |
Custom handling for unregistered MCP names. | Fork-specific layer added during public-surface consolidation. | Removed in Phase 1. Standard SDK unknown-tool behavior is the only supported contract. |
Branch additions that need explicit owner confirmation¶
The following additions are reasonable, but they are not merely bug fixes. They change the product or trust model and should be explicitly accepted:
- Dynamic Agent Bridge and installed Skills. Keep only if loading external capability instructions and invoking configured MCP servers is intentional.
- Remote worker automatic code upgrade. Keep only if the controller is trusted as the worker's update authority. The current digest and same-origin design is substantially safer than upstream's original version-only design.
- Raw local/remote browser terminals. Keep only if interactive shell access through the Human UI is intended; do not weaken loopback, OAuth, scopes, or session ownership.
- Three UI clients. Native browser UI, native OpenTUI, and browser OpenTUI Console share APIs but still multiply visual and E2E maintenance.
- Bundled tmux binaries. This improves frozen Linux usability but creates binary provenance, architecture, CVE, license, and rebuild responsibilities.
Everything else in the branch is primarily correctness, compatibility, security, or a coherent implementation of those accepted product directions.
Intentional remaining differences and future review¶
- Structured public browser automation remains absent. A later proposal must justify a public API beyond session-bound shell execution and define browser profiles, URL/process policy, scopes, bounds, cleanup, audit handling, and remote capability negotiation before implementation.
- Documentation remains English-only. Add maintained locales only when ownership, navigation, generated-reference parity, and freshness checks are funded; machine-generated translations must not silently become canonical.
- Windows worker services remain unsupported. Keep the explicit failure until a reviewed native service manager preserves private identity, stable launcher, update handoff, and bounded log semantics.
- Windows arm64 OpenTUI wheels remain unavailable. Add them only with a native runner, truthful tag/magic validation, clean-install smoke, and release-matrix coverage.
Everything else selected by this migration is implemented or adapted. The security and architecture invariants above are permanent maintenance constraints, not a queue to re-port upstream code verbatim.
Migration history¶
The commit graph is the canonical implementation history. Product-level decisions are summarized in the tables above, while every upstream commit decision remains in the chronological upstream commit review. This avoids freezing a stale branch-tip commit list in permanent architecture docs.
Maintenance rule¶
For each future upstream update:
- Add every upstream commit to the single chronological review table.
- Use
Partial (adapted)whenever a user-visible or operational capability is still absent, even if the fork implements related behavior. - Use
Implemented (adapted)only when the upstream outcome is fully available through the fork architecture. - Keep tip-to-tip product differences in this document, because capabilities may predate the shared fork point or be removed only on one side and therefore never appear as a new upstream commit decision.