galaxy/specs/warp-control-cli/TECH.md

Context

PRODUCT.md defines a local Warp control CLI (warpctrl) with an allowlisted catalog of exactly 84 actions, deterministic addressing across multiple running Warp app processes, and a simple enabled/disabled Scripting setting. SECURITY.md is the normative security architecture. If this technical plan and SECURITY.md disagree, update the plan before implementing. The design is external-only: all callers are same-user processes. There is no inside-Warp/outside-Warp distinction, no verified-terminal invocation context, and no authenticated-user identity layer. Security relies on owner-only filesystem discovery, same-user Unix credential broker with kernel peer credentials, short-lived instance-bound exact-action credentials, loopback HTTP transport, and app-side enforcement.

Existing building blocks

• crates/http_server/src/lib.rs runs a native-only loopback Axum server on fixed port 9277.
• app/src/lib.rs registers that HTTP server and currently merges only installation-detection and profiling routers.
• app/src/workspace/action.rs defines tab creation and workspace actions.
• app/src/pane_group/mod.rs shows pane creation/splitting semantics.
• app/src/settings/theme.rs and app/src/themes/theme_chooser.rs define theme settings behavior.
• crates/warp_cli/src/lib.rs defines existing CLI/parser conventions and channel-specific command naming.
• app/src/lib.rs routes CLI invocations into CLI execution before GUI launch.
• script/macos/bundle and script/linux/bundle show wrapper-script packaging patterns.

Proposed changes

0. Security architecture dependency

Before implementing any local-control listener, CLI command, credential path, or action handler, the implementation must be checked against SECURITY.md. Required security gates:

• Scripting has a single setting: enabled (default) or disabled.
• The authoritative value lives in protected local storage, not ordinary preferences.
• When disabled, no credentials are issued, no control requests are accepted, and discovery records contain no actionable endpoint.
• When enabled, same-user processes may request exact-action credentials from the broker.
• The broker authenticates the OS user through kernel peer credentials, not the calling application.
• Every credential grants one exact action, is bound to the issuing instance, and has a short expiry.
• The app bridge verifies the exact granted action before selector resolution or handler dispatch.
• Close actions (window.close, tab.close, pane.close) flow through normal Warp close behavior so existing app warnings remain authoritative.
• Input-staging commands never submit the buffer. There is no input.run action.
• The Block, Auth, Drive, and History families are entirely absent from the 84-action catalog. Input is limited to input.insert and input.replace.

1. Protocol crate and stable envelope

Create a shared protocol crate used by both the app server and the warpctrl client. It defines:

• A request protocol version for defensive schema guarding.
• Discovery/health response types.
• The 84-action ActionKind enum with implementation status metadata. The Block, Auth, Drive, and History families are entirely absent; Input is limited to input.insert and input.replace.
• Selector types:
  • InstanceSelector: Active, Id(InstanceId), Pid(u32).
  • WindowSelector: Active, Id(WindowId), Index(u32), Title(String).
  • TabSelector: Active, Id(TabId), Index(u32), Title(String).
  • PaneSelector: Active, Id(PaneId), Index(u32).
  • SessionSelector: Active, Id(SessionId).
• Opaque protocol-facing ID newtypes for instance/window/tab/pane/session identifiers.
• Typed parameter payloads per action.
• Success/error envelopes with stable machine-readable error codes from SECURITY.md. The protocol treats target IDs as opaque. Internal runtime IDs are implementation details. Request shape for tab.create:

{
  "protocol_version": 1,
  "request_id": "client-generated-id",
  "target": { "window": "active" },
  "action": { "kind": "tab.create", "params": {} }
}

Success response:

{
  "protocol_version": 1,
  "request_id": "client-generated-id",
  "response": { "status": "ok", "data": {} }
}

Error response:

{
  "protocol_version": 1,
  "request_id": "client-generated-id",
  "response": {
    "status": "error",
    "error": { "code": "missing_target", "message": "No active window is available", "details": null }
  }
}

Error codes include: local_control_disabled, unauthorized_local_client, insufficient_permissions, ambiguous_instance, ambiguous_target, stale_target, missing_target, invalid_request, invalid_selector, invalid_params, unsupported_action, not_allowlisted, target_state_conflict, no_instance, protocol_version_unsupported, transport_unavailable, bridge_unavailable, internal.

2. Per-process discovery

Keep the existing fixed-port 9277 HTTP behavior intact. Add a separate local-control listener per process. Design:

• Each Warp process creates a random opaque instance_id at startup.
• Each process binds a loopback control listener on an ephemeral port.
• Each process writes a discovery record into a secure per-user directory when Scripting is enabled.
• The record contains: instance_id, PID, channel/build metadata, control-listener endpoint, protocol version, start timestamp, and the filename of its instance-bound broker socket.
• The record does not contain bearer tokens, raw credentials, or control authority.
• The CLI passes its compiled channel into the shared discovery scan. The scan excludes records from other channels before returning candidates, rejects records whose endpoint is not exactly 127.0.0.1 or whose broker socket is not the expected filename, prunes stale same-channel records after health checks, and selects an instance using product selector rules. This same-channel boundary applies to listing, implicit selection, and explicit instance or PID selection.
• When Scripting is disabled, no discovery record is published. Default discovery directory: ~/.warp/local-control/. $XDG_RUNTIME_DIR/warp/local-control is preferred when available. On Unix, the directory is restricted to 0700 and records/sockets to 0600.

3. Credential broker

The broker is a Unix-domain socket inside the owner-only discovery directory, one per instance. It is the protected path from discovery metadata to a short-lived exact-action credential. Flow:

1. Client reads the discovery record to learn the broker socket filename.
2. Client connects to the socket.
3. Broker calls the platform peer-credential API and verifies the connecting process's UID equals Warp's effective UID. The broker authenticates the OS user, not the calling application.
4. Client sends a credential request naming one exact action.
5. Broker checks that Scripting is enabled and evaluates the requested action against the catalog.
6. Broker mints a short-lived credential in memory: instance-bound, one exact action, short expiry, unique credential ID.
7. Broker returns the credential to the client. Properties:

• Credentials are never written to discovery records or disk.
• There is no stored bootstrap secret or reusable token.
• The broker evaluates current Scripting state at issuance time.
• Every credential is bound to exactly one action and one instance.
• Issued credentials exist only in the app's process-local credential map and the client's memory.

4. Transport: loopback HTTP

The control listener is an instance-local Axum server bound to 127.0.0.1 on an ephemeral port. Before dispatch, the listener:

• Rejects requests carrying an Origin header.
• Requires the Host header to exactly match 127.0.0.1:<port>.
• Requires a bearer credential present in the instance's process-local credential map.
• Rejects missing, malformed, expired, or wrong-instance credentials.
• Decodes the typed request only after transport authentication.
• Passes the request and credential to the app bridge for exact-action enforcement.

5. App-side request bridge

The HTTP handler runs on a Tokio runtime thread. It cannot directly access WarpUI state because all UI state is single-threaded on the main app event loop. The bridge transfers work to the main thread.

Thread model

• Tokio thread (HTTP handler): Owns the Axum router, validates transport credentials, deserializes the RequestEnvelope, hands the request to the bridge.
• Main app thread: Owns all WarpUI entities (App, AppContext, views, models). All UI state reads and mutations happen here.
• Bridge: Uses ModelSpawner<LocalControlBridge> to transfer a typed closure from the Tokio thread to the main thread, execute it with &mut ModelContext, and return the result.

Flow for tab.create

HTTP handler (Tokio thread)
  ├─ verify Scripting is enabled
  ├─ verify credential existence, expiry, instance binding
  ├─ deserialize RequestEnvelope
  ├─ call bridge_spawner.spawn(move |bridge, ctx| { ... }).await
  └─ serialize ResponseEnvelope as JSON

LocalControlBridge::handle_request (main thread)
  ├─ verify the credential grants the exact requested action
  ├─ match request.action.kind
  │   └─ ActionKind::TabCreate
  │       ├─ resolve window: active window, or sole window, or missing_target/ambiguous_target
  │       ├─ ctx.views_of_type::<Workspace>(window_id)
  │       └─ workspace.update(ctx, |workspace, ctx| {
  │             workspace.handle_action(&WorkspaceAction::AddTerminalTab { ... }, ctx)
  │           })
  └─ return ResponseEnvelope::ok(request_id, ...)

Adding new action handlers

1. Add an entry to the ActionKind catalog.
2. Add a match arm in LocalControlBridge::handle_request.
3. Verify the credential grants the exact action before selector resolution.
4. Resolve selectors and dispatch onto existing app types through ctx.
5. Return ResponseEnvelope::ok(...) or ResponseEnvelope::error(...).

6. Target resolution

Implement target resolution as a reusable component. Resolution order: instance → window → tab → pane → session. Selector behavior:

• active resolves from current app focus state. For window-scoped mutations, a missing active window may fall back to the sole existing window.
• Explicit opaque IDs must resolve exactly or return stale_target.
• Index selectors resolve to a concrete opaque ID before execution.
• Title/name selectors are exact by default and return ambiguous_target on multiple matches.
• Session-scoped requests against non-terminal panes return target_state_conflict. Target resolution happens after credential authentication and exact-action verification.

7. Close behavior

The 3 close actions (window.close, tab.close, pane.close) flow through normal Warp close behavior after exact-action credential validation and deterministic target resolution. Existing warnings for unsaved files, running processes, shared sessions, and similar app state remain authoritative and may cancel the close.

8. CLI parsing and output

The CLI uses the same libraries as the Oz CLI:

• clap (derive) for argument parsing and subcommand trees.
• serde / serde_json for JSON serialization.
• clap_complete for shell completion generation.
• OutputFormat enum (Pretty, Json, Ndjson, Text) shared from warp_cli. New subcommand types live in warp_cli::local_control and follow existing #[derive(Parser)] patterns.

9. CLI packaging

The shipped product is a bundled warpctrl wrapper script that calls the channel-specific Warp binary with a hidden --warpctrl flag:

• macOS: Resources/bin/warpctrl wrapper in the app bundle, same pattern as the Oz wrapper.
• Linux: Small warpctrl wrapper or symlink in the app package.
• Windows: Fails closed until authenticated broker transport is implemented. Startup: app/src/lib.rs recognizes --warpctrl before app launch and routes into warp_cli::local_control. The control-mode path initializes only command parsing, discovery, credential material, HTTP transport, and output formatting. It does not initialize GUI state, rendering, or terminal session models.

10. Feature flag

Gate behind FeatureFlag::WarpControlCli with Cargo feature warp_control_cli. When disabled:

• No Scripting settings page.
• No LocalControlBridge, LocalControlServer, discovery records, broker sockets, or /v1/control endpoints.
• The warpctrl wrapper returns a structured no_instance or feature-disabled error. When enabled:
• Settings > Scripting page is rendered.
• All local-control infrastructure starts when Scripting is enabled (the default on internal dogfood channels; public channels require explicit opt-in through Settings > Scripting).
• resources/bundled/skills/warpctrl/SKILL.md teaches the built-in agent and users how to discover and invoke the allowlisted CLI surface.
• The skill manager maps warpctrl to FeatureFlag::WarpControlCli through BundledSkillActivation. Both skill listing and direct bundled-skill reads enforce the activation state.

11. First slice: discovery + tab.create

The first implementation slice proves the end-to-end architecture:

• Shared protocol types and error envelopes.
• FeatureFlag::WarpControlCli and Cargo feature.
• Settings > Scripting page with enabled/disabled toggle.
• Protected local-only mode storage (channel-based default: enabled on dogfood channels, disabled on public channels).
• Discovery registry and CLI instance selection.
• warpctrl wrapper entrypoint with --warpctrl control-mode dispatch.
• Per-process credential broker (Unix socket, peer credential check).
• Loopback control listener.
• App-side request bridge with ModelSpawner.
• Exact-action credential issuance and enforcement.
• app.ping, app.version, instance.list, and tab.create.
• Structured success/error output in pretty and JSON formats.

12. Follow-up slices

After the first slice validates the architecture, add remaining catalog actions in family groups:

• Window/tab mutations (including close through normal Warp close behavior).
• Pane mutations (including close through normal Warp close behavior).
• Session actions.
• Input staging (insert and replace only, never submitting).
• Appearance/theme actions.
• Settings reads and writes.
• Surface availability, idempotent direct opens, and toggles.
• File open intent. Each addition extends the ActionKind catalog, adds a handler, adds validation/tests, and adds CLI surface.

End-to-end flow

sequenceDiagram
    participant CLI as warpctrl
    participant REG as Discovery registry
    participant BROKER as Unix credential broker
    participant HTTP as Loopback control listener
    participant BRIDGE as App bridge
    participant UI as Warp app state

    CLI->>REG: Read same-channel instance discovery records
    CLI->>HTTP: Health/protocol check (app.ping)
    HTTP-->>CLI: Instance metadata
    CLI->>CLI: Resolve instance selector
    CLI->>BROKER: Connect to Unix socket
    BROKER->>BROKER: Verify peer UID == Warp UID
    BROKER->>BROKER: Check Scripting == enabled
    CLI->>BROKER: Request credential for exact action
    BROKER-->>CLI: Short-lived instance-bound credential
    CLI->>HTTP: POST /v1/control with credential + typed request
    HTTP->>HTTP: Validate credential, reject if expired/invalid
    HTTP->>BRIDGE: Typed request + credential on main thread
    BRIDGE->>BRIDGE: Verify exact action matches credential
    BRIDGE->>BRIDGE: Resolve target selectors
    BRIDGE->>UI: Execute allowlisted handler
    UI-->>BRIDGE: Typed result
    BRIDGE-->>HTTP: Response envelope
    HTTP-->>CLI: JSON success/error

Testing

• Catalog invariant: Every ActionKind with Implemented status has a parseable warpctrl CLI route, generated help/completion coverage, and an app-side bridge handler.
• Scripting gate: Disabled state rejects all credential requests and control requests. Enabled state allows them. Toggling invalidates outstanding credentials.
• Credential model: Raw credentials never appear in discovery records. Credentials are instance-bound, action-bound, and short-lived. A credential for one action fails with insufficient_permissions for any other action.
• Selector resolution: Tests for active, explicit ID, index, stale target, ambiguous target, missing target, and target-state-conflict cases.
• Channel isolation: Discovery tests prove that a CLI scan excludes records published by other Warp channels.
• Input staging: Only input.insert and input.replace exist. No input.run, input.get, input.clear, or input.mode.set. Tests prove no buffer submission occurs.
• Excluded families: The Block, Auth, Drive, and History families are entirely absent. The CLI rejects their command routes at parse time, the protocol rejects their action names at deserialization (invalid_request), and action.inspect/capability.inspect report non-catalog names as not_allowlisted.
• Unsupported platforms: Windows fails closed with no fallback.
• Action count: Tests verify the catalog contains exactly 84 uniformly authorized actions.
• Bundled skill gate: Tests verify the warpctrl bundled skill is discoverable and readable only while FeatureFlag::WarpControlCli is enabled, without affecting unrelated bundled skills.

Risks and mitigations

• Same-user residual risk: The broker authenticates the OS user, not the calling application. Any process running as the same user can request credentials. Mitigated by: protected enablement, short expiry, exact-action grants, app-side revalidation, normal Warp close warnings for close actions.
• Browser-to-localhost: Mitigated by: no permissive CORS, Origin header rejection, Host header validation, credential requirement.
• Fixed-port contention: Mitigated by: leaving 9277 undisturbed, using per-process ephemeral ports for control.
• Input execution risk: Mitigated by: no input.run in the catalog, input commands stage text only, tests prove no submission.
• Heavyweight CLI startup: Mitigated by: --warpctrl routes before GUI launch, control-mode path initializes only what's needed.