# COMPATIBILITY — JUJU 0.8.2

## 0.8.2 current platform matrix

| Platform | Current 0.8.2 claim |
|---|---|
| macOS | Supported on the tested Node range; built-in Seatbelt command sandbox, `say`/eSpeak speech and existing Screen Recording/Accessibility desktop backend. Owner OS permissions remain required. |
| Windows x64 | Supported for the 0.8.2 native acceptance set: authenticated named-pipe IPC, managed dependencies, SAPI/eSpeak speech, interactive desktop capture/control and `windows-srt` command sandbox. Tested on Windows Server / Node v24.21.0. |
| Linux | Supported for coding/media/setup and bubblewrap command sandbox. Desktop support is X11/XWayland-style only when `DISPLAY`, X-Resource/XTEST and AT-SPI are available; pure Wayland portal-only sessions are not claimed. Debian bookworm arm64 / Node 22 was exercised. |

`juju setup` is the normal dependency-preparation entry point on all three OS families. A component is not reported ready merely because an executable exists: setup/check performs bounded capability probes for Git/ripgrep, media/Whisper, Chromium, LSP, speech, desktop and sandbox where applicable. Web fetch remains an explicit owner configuration choice rather than an installation capability.

Windows sandbox acceptance uses local-drive workspaces. UNC and Windows ARM64 are not native-tested release claims. The 0.8.x IPC upgrade boundary remains: stop 0.7.x with its matching old CLI before replacement; OAuth grants/workspace ACL/trust are retained.

The 0.8.0 candidate section below is historical and describes the limitations before 0.8.2 closed the native backend work.

## 0.8.0 — Windows native: EXPERIMENTAL, not yet validated

Source now contains Windows named-pipe IPC, authenticated owner control,
trusted executable/PATHEXT and shell adapters, Windows process cancellation,
private state DACL handling, NTFS path guards and portable runtime tests.
This is an implementation candidate, **not a Windows support certification**.

The current development host is macOS arm64 / Node 22.23.2. Native Windows
Node 22/24 CI is defined in `.github/workflows/windows.yml` as an allow-failure
phase-0 evidence job; it has not been run as part of this local change. The
full native gate and Windows 11 manual acceptance are still required before
changing the status to supported. See [Windows status](WINDOWS_0.8.0.md) and
[TEST_REPORT](TEST_REPORT.md) for exact evidence and skipped tests.

Windows v1 intentionally has no JUJU command OS sandbox, native desktop tools
or macOS speech synthesis. Cancellation is hard-kill-only for owned live
children. Local-drive workspaces only; UNC and Windows ARM64 are not claimed.
A requested sandbox fails closed; schedules require explicit unsandboxed
consent rather than silently downgrading a saved sandbox requirement.

**Upgrade boundary:** stop old 0.7.x servers using their matching old CLI or
terminal before replacing the installation. The new IPC protocol has no
unauthenticated legacy fallback. Existing OAuth grants, workspace ACLs and
trust state are not erased. Tool surfaces remain 19 / 49 / 74.

The versioned sections below are historical release evidence, not new
Windows test results or a publication claim for 0.8.0.

## 0.7.2 addition — hybrid surface

- Opt-in `toolSurface: "hybrid"` (config) or `--tools hybrid`: exactly 49
  tools = the compact coverage core (first) + 30 direct coding tools;
  tools/list ≈ 113 KB. Defaults unchanged. `schemas/tools.hybrid.json` added.

## 0.7.1 tool surfaces

- HTTP default: **compact** — 19 tools (project_overview, juju_discover, 17
  gateways); serialized tools/list ≈ 47 KB vs ≈ 236 KB full. STDIO default:
  **full** — the unchanged 74-tool catalog, same names/order/schemas.
- Override: global config `toolSurface`, or `--tools compact|full` on
  `juju start`/`juju stdio`. Exposure only; scopes/ACL/trust/approvals and
  all guards are enforced per TARGET operation through one shared pipeline.
- `schemas/tools.json` (full) is unchanged; `schemas/tools.compact.json`
  is new. Startup logs `[juju] mcp tool surface | …` on both transports.
- No client-side tool-count limit is asserted anywhere; compact reduces
  catalog/schema ingest. Live ChatGPT rescan is a manual gate.

## Historical 0.7.0 contract

74 tools: 49 retained tools + 5 assistance + 20 multimodal. MCP SDK 2.0.0,
modern HTTP/STDIO and legacy stateless dispatch retain their existing contract.
Image and audio content require host/model support; a successful SDK fixture is
not a claim that every external AI client ingests both modalities.

New runtime dependencies: `sharp@0.35.4`, `playwright@1.63.0`. Chromium installation
and FFmpeg/ffprobe/whisper-cli/model installation are separate optional steps;
`juju-media-setup` is included in the package. Native desktop and local speech
synthesis remain macOS-specific. Windows remains unsupported. New Linux/macOS
Intel/Node24 and external ChatGPT/Claude/Codex/tunnel acceptance: MANUAL_NOT_RUN.

Release gate on macOS 26.3.1 arm64, Node 22.23.2 and npm 10.9.8:
374/374 tests in 44 files, typecheck/lint/build passed, no skipped tests.
Media decoding, ASR/TTS and Chromium tests use real local fixtures. New desktop
wrappers use a fake OS adapter with actual image bytes, not new native input evidence.

Existing OAuth grants, workspace ACLs, trust modes, desktop consent, command
sandbox settings and schedules are retained. Restart/reload is required to load
the new code/catalog; package publication alone does not update running instances.
See [RELEASE_0.7.0](RELEASE_0.7.0.md) and [MULTIMODAL](MULTIMODAL.md).

The sections below preserve older release evidence; historical tool counts and
unchanged-dependency statements apply to the named releases, not to 0.7.0.


> **0.2.0 update (supersedes older workspace-only grant wording below):** New
> OAuth grants authenticate the JUJU installation; every request still checks
> a separate current-workspace/client scope ACL. Legacy tokens remain bound to
> their original root until a fresh login. Bare `juju` now starts HTTP and a
> private token-protected config listener on 127.0.0.1:21731; subprocess clients
> must explicitly use `juju stdio`. `--allow --all` and `--bypass` are run-only
> execution overrides, never authentication or workspace-ACL bypasses.
> See [ADR-017](adr/017-installation-identity-local-config.md) and the
> [setup guide](../README.md#quickstart) for the current contract. Since 0.3,
> the owner can switch the active HTTP workspace from Local Config; 0.3.1
> rejects stale config tabs and drains actual handlers before teardown.

Records the OS/arch/Node/dependency/protocol versions actually exercised while
building and testing JUJU. Anything not listed here is **not claimed** as
supported.

Previous 0.3.1 release gate on 2026-09-09: `npm run test:all` exit 0, **216/216 tests across
26 files**, with typecheck/lint passing. WS-07..09 cover stale config saves,
disconnected handlers and same-port restart. Browser checks used isolated
local fixtures. Live ChatGPT/tunnel acceptance remains `MANUAL_NOT_RUN`.

## Toolchain tested

| Component | Version | Notes |
|---|---|---|
| OS | macOS 26.3.1 (Darwin 25.x) | release gate |
| Arch | arm64 (Apple Silicon) | macOS x64 not separately tested here |
| Node.js | v22.23.2 | `engines: >=22.12.0`. Spec proposes Node 24 LTS; the code targets ES2023/NodeNext and runs on the installed 22.x LTS. Re-run the suite on your Node before release. |
| npm | 10.9.8 | |
| git | 2.50.1 | required only for `git_status` / `git_diff`; absent → `isRepo:false` |
| ripgrep | optional, not on the recorded test process PATH | the suite exercised the bounded JS/worker fallback |

## Pinned dependencies (exact lockfile included)

| Package | Version |
|---|---|
| `@modelcontextprotocol/server` | 2.0.0 |
| `@modelcontextprotocol/express` | 2.0.0 |
| `@modelcontextprotocol/node` | 2.0.0 |
| `@modelcontextprotocol/client` (dev) | 2.0.0 |
| `oidc-provider` | 9.12.2 |
| `better-sqlite3` | 13.0.3 |
| `express` | 5.2.1 |
| `cron-parser` | 5.10.0 |
| `commander` | 15.0.0 |
| `jose` | 6.2.12 |
| `zod` | 4.5.4 |
| `typescript` | 5.9.3 |
| `ignore` | 7.0.9 |
| `diff` | 9.0.0 |
| `picomatch` | 4.0.7 |
| `pyright` (dev only, LSP tests) | 1.1.413 |

## MCP protocol

- **SDK generation:** v2 split packages (`@modelcontextprotocol/{server,express,node}`),
  confirmed installed and used — no v1 imports mixed in (ADR-003).
- **Modern path:** served by `createMcpHandler` (per-request instances). A real
  `@modelcontextprotocol/client` `Client` over `StreamableHTTPClientTransport`
  connects, lists the registered tool catalog, and dispatches (`MCP-01`).
- **Legacy 2025-era path:** `createMcpHandler(..., { legacy: 'stateless' })`. A
  raw `initialize` (protocolVersion `2025-03-26`) + `tools/list` + `tools/call`
  works with no `Mcp-Session-Id` (`MCP-02`). `GET`/`DELETE` → `405` (`MCP-03`).
- The exact protocol revision a given ChatGPT build negotiates was **not
  captured** (no traffic interception); both generations are tested locally.

## SQLite native binding

`better-sqlite3@13.0.3` loaded its **prebuilt** binary on macOS arm64 with no
compiler required. `juju doctor` reports `sqlite-native`. On a target with no
prebuilt binary the install fails loudly (documented; no silent in-memory
fallback).

## Platforms

- **macOS arm64** — release gate: full suite passes here.
- **Linux x64** — CI gate: the same `npm run test:all` is expected to pass;
  **run it in your CI** and record the result (not inferred from macOS).
- **Windows** — **not supported**. Audited 2026-09-09: both entry points die at
  the Unix-socket IPC bind, and four more independent hard stops sit behind it
  (shell, executable resolution, LSP resolution, process-tree kill), plus two
  Windows-only security regressions (NTFS ADS/8.3 aliases, cwd-first `git`/`rg`
  lookup). Evidence, blockers and a ~40 engineer-day plan: [WINDOWS_PLAN.md](WINDOWS_PLAN.md).
  Do not claim support.

## OS sandbox

- macOS: `/usr/bin/sandbox-exec` present and enforcing on macOS 26.3.1 (tests spawn it and prove an outside-workspace write fails with "Operation not permitted"). Deprecated by Apple, still functional.
- Linux: `bwrap` argv is unit-tested; enforcement on a Linux host is **not** verified here (CI gate).

## stdio transport

- `juju stdio` verified with the real `@modelcontextprotocol/client` `StdioClientTransport` (tests/integration/stdio.test.ts).

## Known limitations

- Directory `fsync` durability depends on the platform/filesystem.
- Grandchild processes that leave their process group can survive `job_cancel`.
- Pure-Node path checks have TOCTOU races against a hostile same-user process
  (see SECURITY.md). The optional command sandbox does not eliminate this limitation.

## Desktop backend (0.4.0)

macOS 14+ required for SCScreenshotManager; Swift helper compiled locally via
Xcode Command Line Tools. Actual run: macOS 26.3.1 arm64/Node 22.23.2,
Screen Recording true and Accessibility false. Native fixture capture/OCR
passed; positive input and AX reading are MANUAL_NOT_RUN. Linux/Windows have no
desktop backend. macOS Intel is not claimed tested. No install hooks or
prebuilt native executable are added to the npm package. See DESKTOP.md.

0.4.0 full gate: `npm run test:all` exit 0, **236/236 tests in 28 files**,
including typecheck/lint. Desktop policy tests use a fake OS adapter; the
separate native fixture receipt above is the evidence for actual macOS calls.

0.4.1 persistent consent gate on the same macOS/Node environment:
`npm run test:all` exit 0, **246/246 tests in 28 files**, typecheck/lint passed.
Fresh packed CLI saves/revokes persistent consent without a running server.
No new dependency/protocol/native-helper versions; native input was not rerun.
Both HTTP and STDIO use the same workspace policy reader. This is a local
release; npm publication and new external-client acceptance are not claimed.

0.4.2 on macOS 26.3.1 arm64 / Node 22.23.2 / npm 10.9.8:
`npm run test:all` exit 0, **254/254 tests in 30 files**, typecheck/lint passed.
Owner kill tested with HTTP, duplicate-root STDIO, owned jobs, and real OAuth
access/refresh credentials across restart. A previously installed 0.4.1 HTTP
process also stopped through its legacy IPC socket with exit 0. No dependency
or protocol versions changed. Linux/Intel/Windows kill behavior was not run;
Windows is explicitly unsupported. External GPT reconnect remains manual.

0.4.3 on the same macOS arm64/Node/npm toolchain:
`npm run test:all` exit 0, **272/272 tests in 33 files**, typecheck/lint passed.
Modern and legacy HTTP dispatch, 11 MiB STDIO file, exact 8 MiB STDIO command,
3 MiB safe editing/rollback, macOS sandbox, native argv bounds and owner CLI
profiles were exercised locally. SDK 2.0.0 and all dependency versions unchanged.
New Linux/Intel large-command runs and real AI-client/tunnel limits are
MANUAL_NOT_RUN; Windows support is not added. See LARGE_INPUTS for limits.

## 0.6.0 contract change

49 tools: the three usage controls introduced in 0.5 were removed; schedule_propose
remains. All common chat/usageId inputs, private chat/usage routes, owner CLI
chat/usage/reset and the web chat controls are removed. Clients must reload their
tool catalog and stop sending those fields. project_overview takes no chat
context; every other tool still requires workspaceId and workspaceEpoch.

HTTP continues to require OAuth plus workspace ACL. STDIO retains local trust
and action approval. Existing OAuth signing state and client registrations are
preserved, as are independently approved schedules. Legacy usage/chat tables
remain inert; no new database migration is necessary.

Dependencies/protocol versions are unchanged: SDK 2.0.0 modern + legacy stateless,
oidc-provider 9.12.2, better-sqlite3 13.0.3, TypeScript 5.9.3, cron-parser 5.10.0.
Local test environment is macOS 26.3.1 arm64 / Node22.23.2 / npm10.9.8.
See TEST_REPORT for this release's actual commands/results. New Linux, macOS Intel,
Node24 and real ChatGPT/Claude/Codex UI runs are MANUAL_NOT_RUN. Windows remains
unsupported; no new native Desktop backend was added.

0.5.0–0.5.3 behavior/results are historical and retained in RELEASE_NOTES and
TEST_REPORT. Their per-chat instructions no longer apply to 0.6.0.

## 0.6.1 private UI/API change

/api/state.clients now contains only clients with nonempty ACLs for the current
root. Registered but unassigned clients are available in a separate, on-demand
owner picker. No MCP schema, OAuth, dependency or SQLite migration change; tool
count remains 49. Restart JUJU after upgrading to serve the new UI assets and
API. Existing login and other-project scopes remain intact.

## 0.6.2 owner deletion

Adds private owner manage/delete routes and UI controls. No MCP wire/dependency
or SQLite migration changes; 49 tools remain. Deleting a selected registration
intentionally invalidates that client's connection across workspaces; unlike
ordinary package upgrade, using that deleted connection again requires a new
registration/authorization. Other registrations/login state are preserved.

## 0.6.3 OAuth approval command fix

Terminal and browser instructions now include `--` before OAuth request IDs.
The installed CLI accepts IDs beginning with hyphens through the standard
argument separator. No dependency, MCP schema, OAuth or database migration
change. macOS 26.3.1 arm64 / Node22.23.2 / npm10.9.8: `npm run test:all`,
exit 0, 293/293 tests across 37 files. New platform and live external-client
acceptance remain MANUAL_NOT_RUN. Restart JUJU to load the new instructions.