Creatidy/scarcity-router

Fork 0

M05: Native worker, pairing, and execution transport #90

New issue

Closed

opened 2026-09-19 13:07:36 +00:00 by kilo · 1 comment

kilo commented

2026-09-19 13:07:36 +00:00

Member

Goal

Provide one simple native worker for Windows/Linux/WSL that bridges local resources (localhost-only inference endpoints, local application entitlements) to the central server.

Module of the execution-gateway program; architecture and contracts come from A0 (#85).

User value

Local machines' Ollama instances and Codex/ZCode entitlements become usable from anywhere in the user's LAN/VPN without opening inbound ports, editing firewall rules or maintaining certificates. Install the worker only on machines where such access is actually needed.

Relationship to current code

New native component; the server side is the worker-protocol endpoint of the Execution Coordinator (M03). The protocol is defined by A0: a simple versioned protocol over TLS/WSS, worker-initiated outbound connection, no inbound worker port.
Worker-reported telemetry flows into M01's registry as safe normalized state (one normalization path; no duplicate collector implementations for the same provider/account).

Scope

Outbound TLS/WSS connection; explicit pairing; per-device identity; credential rotation/revocation; heartbeat; protocol-version negotiation; user-approved discovery; resource state reporting; execute; stream; cancel; bounded reconnect; backpressure; local diagnostics; server-worker compatibility handling.
The worker performs no global routing decisions.

Non-goals

No inbound listening port for normal operation; no generic /shell, /ssh or arbitrary-command endpoint; no remote host administration; no SSH orchestration protocol (SSH is how a user may reach another machine, not a required router protocol); no manual worker-IP configuration; no routine certificate maintenance for ordinary users.

Contracts / interfaces affected

Worker protocol contract (new, A0); resource-state report contract (M01); execution dispatch/stream/cancel contract (M03).

Dependencies

Depends on: A0 (#85), M03.
Feeds: M06/M07 (local adapter execution surface), M09 (pairing UI portion), M10 (E2E topologies).

Acceptance criteria

The worker requires no inbound listening port for normal operation.
Invalid identity is rejected; revoked credentials are rejected.
Incompatible protocol versions fail safely.
There is no generic /shell, /ssh or arbitrary-command endpoint.
A local adapter allowlist remains enforceable even if the server asks for something else.
Network loss must not cause automatic duplicate execution of an already-started request.
Application credentials stay local whenever possible.
Windows and WSL are not treated as one credential/configuration directory.
Full validation gate green; protocol tests deterministic.

Security considerations

Verified TLS/WSS (no verify=false); the pairing/trust bootstrap model from A0; per-device identity with revocation; no bearer secrets in URLs; local adapter allowlist enforcement; filesystem/session/tool isolation for any local adapter invocation; no root/Administrator execution by default; no uncontrolled client-supplied subprocess flags or environment variables; no Docker socket mounting; logs created by local runtimes are accounted for in diagnostics hygiene (no secrets, no prompts).

Risks

Cross-platform packaging drift (Windows/WSL credential separation is a known pitfall).
Reconnect/heartbeat edge cases duplicating work — mitigated by the idempotency rules in A0's execution contract.

Evidence still required

Minimum viable transport decision evidence (kept simple per A0: versioned protocol over TLS/WSS).
Windows autostart/service mechanism evidence (shared with M10 packaging).

## Goal Provide one simple native worker for Windows/Linux/WSL that bridges local resources (localhost-only inference endpoints, local application entitlements) to the central server. Module of the execution-gateway program; architecture and contracts come from A0 (#85). ## User value Local machines' Ollama instances and Codex/ZCode entitlements become usable from anywhere in the user's LAN/VPN without opening inbound ports, editing firewall rules or maintaining certificates. Install the worker only on machines where such access is actually needed. ## Relationship to current code - New native component; the server side is the worker-protocol endpoint of the Execution Coordinator (M03). The protocol is defined by A0: a simple versioned protocol over TLS/WSS, worker-initiated outbound connection, no inbound worker port. - Worker-reported telemetry flows into M01's registry as safe normalized state (one normalization path; no duplicate collector implementations for the same provider/account). ## Scope - Outbound TLS/WSS connection; explicit pairing; per-device identity; credential rotation/revocation; heartbeat; protocol-version negotiation; user-approved discovery; resource state reporting; execute; stream; cancel; bounded reconnect; backpressure; local diagnostics; server-worker compatibility handling. - The worker performs no global routing decisions. ## Non-goals - No inbound listening port for normal operation; no generic `/shell`, `/ssh` or arbitrary-command endpoint; no remote host administration; no SSH orchestration protocol (SSH is how a user may reach another machine, not a required router protocol); no manual worker-IP configuration; no routine certificate maintenance for ordinary users. ## Contracts / interfaces affected Worker protocol contract (new, A0); resource-state report contract (M01); execution dispatch/stream/cancel contract (M03). ## Dependencies - Depends on: A0 (#85), M03. - Feeds: M06/M07 (local adapter execution surface), M09 (pairing UI portion), M10 (E2E topologies). ## Acceptance criteria - [ ] The worker requires no inbound listening port for normal operation. - [ ] Invalid identity is rejected; revoked credentials are rejected. - [ ] Incompatible protocol versions fail safely. - [ ] There is no generic `/shell`, `/ssh` or arbitrary-command endpoint. - [ ] A local adapter allowlist remains enforceable even if the server asks for something else. - [ ] Network loss must not cause automatic duplicate execution of an already-started request. - [ ] Application credentials stay local whenever possible. - [ ] Windows and WSL are not treated as one credential/configuration directory. - [ ] Full validation gate green; protocol tests deterministic. ## Security considerations Verified TLS/WSS (no `verify=false`); the pairing/trust bootstrap model from A0; per-device identity with revocation; no bearer secrets in URLs; local adapter allowlist enforcement; filesystem/session/tool isolation for any local adapter invocation; no root/Administrator execution by default; no uncontrolled client-supplied subprocess flags or environment variables; no Docker socket mounting; logs created by local runtimes are accounted for in diagnostics hygiene (no secrets, no prompts). ## Risks - Cross-platform packaging drift (Windows/WSL credential separation is a known pitfall). - Reconnect/heartbeat edge cases duplicating work — mitigated by the idempotency rules in A0's execution contract. ## Evidence still required - Minimum viable transport decision evidence (kept simple per A0: versioned protocol over TLS/WSS). - Windows autostart/service mechanism evidence (shared with M10 packaging).

kilo referenced this issue

2026-09-19 13:11:01 +00:00

A0: Architecture, decisions, and contracts for the optional execution gateway #85

kilo added the

enhancement

label

2026-09-19 13:11:40 +00:00

kilo added a new dependency

2026-09-19 13:12:00 +00:00

#85 A0: Architecture, decisions, and contracts for the optional execution gateway

kilo added a new dependency

2026-09-19 13:12:00 +00:00

#88 M03: OpenAI-compatible gateway and execution coordinator

kilo added a new dependency

2026-09-19 13:12:16 +00:00

#91 M06: Codex adapter: CLI/App Server with Desktop and VS Code installations

kilo added a new dependency

2026-09-19 13:12:17 +00:00

#92 M07: ZCode adapter: feasibility proof and experimental integration

kilo added a new dependency

2026-09-19 13:12:18 +00:00

#95 M10: Distribution, installation, update, and end-to-end acceptance

kilo referenced this issue

2026-09-19 19:52:09 +00:00

M01: Resource registry, state, and collectors for executable resources (issue #86) #99

kilo removed a dependency

2026-09-20 00:02:37 +00:00

#92 M07: ZCode adapter: feasibility proof and experimental integration