# ADR 0007: Cross-platform programming-AI terminal link

- Status: implemented in source; installed acceptance remains per platform
- Date: 2026-08-17

## Context

An external programming AI must remain attached to a HoloLake-owned work environment without making MCP stability, one chat window, or model protocol recall the continuity root. The product is not macOS-only: Windows and Linux must enforce the same session and write semantics even though their local IPC primitives differ.

## Decision

Embed `HOLOLAKE_TERMINAL_LINK/2` in the native HoloLake executable. macOS and Linux use a mode-0600 Unix socket inside a mode-0700 runtime directory. Windows uses a local Named Pipe with a protected DACL granting full access only to Local System and the creating object owner. All platforms additionally require HoloLake session authentication.

The installed executable exposes `--connector` as sequential newline-delimited JSON. It reloads the broker descriptor after transport loss. If an operation may have reached HoloLake but its response was lost, the connector reports an uncertain response and does not blindly replay it.

Opening or resuming a session establishes continuity in HoloLake. The authenticated client then acquires the account's single development writer and obtains a short-lived work-environment frame. Heartbeats refresh both durable session observation and that frame. The frame contains the HoloLake runtime owner, session and event cursor, writer match, compiled GLS runtime identity, expiry and digest. It explicitly says that model-side protocol restoration is not required.

## Boundary

This decision completes the first-stage control plane, not the second-stage Agent executor. It does not grant a supervised shell, arbitrary file mutation, build, publication, deployment, persona binding or reality-execution authority. Those require separate typed operations, approvals and receipts.

Cross-compilation of the isolated Linux Unix-socket adapter is evidence for source portability only. It is not installed-runtime acceptance. The Windows implementation additionally passes a full Tauri build and 110 native tests on the registered Windows Server 2022 x64 build node. That node has no authenticated HoloLake private account, so application-level installed broker readback remains separate and unobserved. Linux installed readback must likewise occur on a real registered desktop target rather than being inferred from a server or macOS cross-compile.

## Rejected alternatives

- TCP loopback as the common denominator: it broadens the local attack surface and weakens the operating-system account boundary.
- A macOS implementation with Windows and Linux documentation only: transport portability without compiled adapters is not an implementation.
- Replaying a request automatically after a broken response: a mutation could execute twice.
- Asking every newly started model to reread all GLS prose: protocols are HoloLake runtime code, not model memory.
- Calling the control plane an Agent shell: the supervised execution organ is the next phase.

## Evidence

- `src-tauri/src/direct_local_broker.rs`
- `src-tauri/src/direct_local_session.rs`
- `src-tauri/src/local_development_bridge.rs`
- `src/main.tsx`
- `contracts/programming-ai-terminal-link.json`
- `scripts/programming-ai-terminal-link.test.mjs`