@orchestraworks/worker 0.0.141 → 0.0.143

package/README.md

@@ -41,18 +41,19 @@ Run it once, as root on Linux or as an administrator on Windows, on a host that
 Each step reads what is there, changes only what is different, and prints `ok: <step>` or
 `changed: <step>`. The first failure stops the run and names the step. You can run it again.
 
-`<root>` is the machine-wide root: `/var/lib/sfdk/worker` on Linux, `%ProgramData%\sfdk\worker` on Windows.
+`<root>` is the machine-wide root: `/var/lib/orchestra/worker` on Linux, `%ProgramData%\orchestra\worker` on Windows.
+A host where an earlier release installed the worker keeps its root at `/var/lib/sfdk/worker` or `%ProgramData%\sfdk\worker`.
 
 | Step | When | What it does |
 |---|---|---|
-| preconditions | always | Refuses a host it is not written for. Refuses a host that has booted as a machine: a boot file or `<root>/state` is there. Refuses a running worker service. |
+| preconditions | always | Refuses a host it is not written for. Refuses a host that has booted as a machine: a boot file or `<root>/state` is there. Refuses a running worker service, under its name or the name an earlier release used. |
 | directories | Windows | Creates `<root>`, `C:\software-factory` and its `etc` folder for SYSTEM and Administrators only. Users can also read and run `C:\software-factory`, which holds the programs on the machine path. A folder that is already there is kept as it is. |
 | package | always | Copies this release package to `<root>/package`. The service runs from there, because a self-update replaces the package directory. |
 | agent account | Linux | Creates the `agent` account, uid and gid 1000, home `/home`, and gives `/home` to it. Another account at uid 1000 is kept. |
 | harnesses | `--harness` | Installs the named harness families and their Node under the root. `none` or no flag installs none: a family installs itself on its first turn, in about a minute. |
-| service | always | Defines the service, `SfdkWorker` on Windows and `sfdk-worker.service` on Linux. It restarts after a failure. The step does not start it. |
+| service | always | Removes the service an earlier release registered, then defines the service, `OrchestraWorker` on Windows and `orchestra-worker.service` on Linux. It restarts after a failure. The step does not start it. |
 | cloud | always | `azure`: at each boot, the start-up task runs `worker boot-files --cloud azure`, which writes the boot files from the VM's userData, and then the worker starts. `aws`: the worker starts at each boot, after the platform's user data, and an Azure start-up task or unit from an earlier run is removed. |
-| egress redirect | `--egress-redirect` | WinDivert and its inbound firewall rule on Windows, `iptables` on Linux. A Launcher machine does not need it. |
+| egress redirect | `--egress-redirect` | WinDivert and its inbound firewall rule on Windows. On Linux it installs nothing: it checks that the kernel carries the nftables parts the worker's redirect needs, and loads `nf_conntrack`. A Launcher machine does not need it. |
 | Docker | `--docker` | Windows containers, or rootless Docker for the `agent` account. |
 | Node | `--node` | The agent's own Node, on the machine path. On Windows a new Node keeps the packages that `npm install -g` put in its folder. |
 | check | always | Runs `worker check --profile launcher` for `azure`, and `--profile enrolled` for `aws`. |
@@ -104,7 +105,7 @@ The machine must reach these hosts. The command does not test them:
    This command shows `"restartPending":false` when none is:
 
    ```powershell
-   & "$env:ProgramData\sfdk\worker\package\worker.exe" check --profile launcher --output json
+   & "$env:ProgramData\orchestra\worker\package\worker.exe" check --profile launcher --output json
    ```
 
 6. Generalize with Sysprep:
@@ -177,6 +178,14 @@ The machine must reach these hosts. The command does not test them:
 If the image serves an app, end your own boot step with one request to the app. The first request after
 a boot is slow, so this request takes that delay instead of the first user.
 
+### The worker's service name
+
+The worker's service is `OrchestraWorker` on Windows, `orchestra-worker.service` on Linux and
+`ai.livingcomputers.orchestra.worker` on macOS. An install replaces the service an earlier release registered
+as `SfdkWorker`, `sfdk-worker.service` or `ai.livingcomputers.sfdk.worker`. Change your own scripts that name
+it. An image an earlier release built keeps its service after a self-update, and
+its start-up task still starts it.
+
 ### The model key and other tokens
 
 Give the agent its model key in one of three ways. Each works on every machine, with or without our
@@ -187,9 +196,9 @@ egress edge. The edge and its Secrets are an addition, never needed for your own
    an environment read returns them, and the VM's startup data carries them. If that is not acceptable,
    use route 2 or 3, or a Secret at our egress edge where one stands in front.
 2. **Baked into the image**, at machine scope, before Sysprep or generalizing. On Windows, that is the
-   `Environment` value (a multi-string) of `HKLM\SYSTEM\CurrentControlSet\Services\SfdkWorker`. Keep
+   `Environment` value (a multi-string) of `HKLM\SYSTEM\CurrentControlSet\Services\OrchestraWorker`. Keep
    the entries that are there, and add or replace only yours. On Linux, it is a drop-in on
-   `sfdk-worker.service`.
+   `orchestra-worker.service`.
 3. **The `onStartAgent` hook** writes the harness's own key file in the agent's home:
    `.claude/.credentials.json` for a Claude sign-in, `.codex/auth.json` for `codex`, or
    `.pi/agent/auth.json` for `pi`. The worker keeps a real value it finds there. A raw Claude API key has
@@ -205,7 +214,7 @@ The names:
 - `pi`: `ORCHESTRA_WORKER_OPENAI_API_KEY` or `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`.
   `ORCHESTRA_WORKER_PI_PROVIDER` chooses the provider.
 
-Never restart `SfdkWorker` or `sfdk-worker.service` to load a key. A restart after the worker registered
+Never restart `OrchestraWorker` or `orchestra-worker.service` to load a key. A restart after the worker registered
 stops the machine's work, and the platform parks the VM. The next message starts it again, 1 to 2
 minutes later.
 

package/docs/REFERENCE.md

@@ -12,7 +12,7 @@ The worker exposes no API of its own. Every route it calls is the platform's.
 
 | path | what it holds |
 |---|---|
-| `cmd/worker/` | the one binary: `run`, `install`, `install-machine`, `boot-files`, `enroll`, `check`, `trust-nested`, `screen`, `version` |
+| `cmd/worker/` | the one binary: `run`, `install`, `install-machine`, `boot-files`, `enroll`, `check`, `trust-nested`, `screen`, `redirect`, `version` |
 | `identity/` | the four identity exchanges — claim, refresh, reattach-challenge, reattach — the holder key, and the loop that keeps the machine token alive |
 | `broker/` | the protocol on the message broker: the connection, the register on every connect, the heartbeat and the status cadence, the pull of this machine's own work consumer, and the publisher every other package sends through |
 | `env/` | the machine-side environment the platform composes onto a launch, read from the names the contract declares |
@@ -21,7 +21,7 @@ The worker exposes no API of its own. Every route it calls is the platform's.
 | `process/` | the agent's setup and the harness process behind each session placement: the start, the stop and the last save a remove asks for, the startup fence over what a previous run left, and the stop of everything when the worker is told to stop |
 | `stream/` | the queue: every placement message and every prompt, steer and cancel pulled off this machine's work consumer, the ACP client that opens a session's harness conversation and runs its turns, each turn's events batched to the platform and published live, and the answer every placement message is owed |
 | `mount/` | the volumes the launch declares, placed on the lanes that mount them: the home volume first, because anything written under a mount point before the mount is hidden by it |
-| `network/` | the transparent redirect on the virtual-machine lanes, as the iptables rules the launch describes: what the worker's own uid reaches directly, and what every uid on the machine reaches through the egress edge |
+| `network/` | the transparent redirect the launch describes, as the worker's own nftables table written over netlink with no program from the image: what the worker's own uid reaches directly, and what every uid on the machine reaches through the egress edge |
 | `shim/` | the in-guest transparent proxy: the listener the redirect lands on, the recovery of the destination each connection was actually for, the hop to the egress edge under the machine-identity proof, the WinDivert half that is the Windows redirect, and the loopback feed a separate shim reads this machine's token from |
 | `egress/` | what puts that proxy in place on the virtual-machine lanes: the edge's certificate authority in this machine's trust store, the inbound firewall rule Windows needs, the redirect itself, and the state line an operator reads off the machine's console |
 | `ingress/` | the machine's half of the preview tunnel: the connection this worker holds open to the preview gateway, the challenge and the signed upgrade that authenticate it, and the loopback pipe that carries each viewer request to a port this machine declared and refuses every other |
@@ -39,6 +39,8 @@ shapes the schema ships, and nothing here re-declares one.
 
 ## The commands
 
+Each `ORCHESTRA_` machine variable this page names also has a former `SFDK_` spelling. Until the rename's compatibility period ends ([D50](../../docs/specs/2026-10-03_2446_orchestra_rename_spec.md)), the platform and the worker still write the former spelling beside the new one, and every reader takes the new name first and the former one when the new one is absent.
+
 - **`worker run`** claims this machine's identity — or reattaches, where its row is already bound to
   the key this machine holds — and then serves the machine. `run` hands the held identity, with the
   broker credential the claim co-issued, to the registrar seam in `cmd/worker/run.go`, which the
@@ -48,7 +50,7 @@ shapes the schema ships, and nothing here re-declares one.
   Before any of that, `run` starts what the launch describes: it places the declared volumes, puts
   the in-guest egress in place where the launch names an intercept set, opens the egress shim's token
   feed, and — on a machine the cloud can reclaim — watches for the notice that it is going away. Each
-  is started only where it is described: a Kubernetes pod places its own volumes and its egress
+  is started only where it is described: an OpenSandbox pod places its own volumes and its egress
   sidecar installs its own redirect, so a launch there names neither. If one of those duties is
   installed and then dies, `run` ends rather than serving a machine the platform counts as healthy
   with no route off it; the service manager starts the worker again.
@@ -91,6 +93,13 @@ shapes the schema ships, and nothing here re-declares one.
   same answer. Nothing on a machine somebody owns needs privilege: network enforcement is outside the
   machine, at the egress edge and the directional security group.
 
+  **An install replaces the service an earlier release registered.** It first stops and deletes that
+  service in the scope this install registers in. On Windows, the earlier service is the `SfdkWorker`
+  service in system scope, or the `SfdkWorker` logon task in user scope. On Linux, the earlier service
+  is the `sfdk-worker.service` unit, and on macOS the `ai.livingcomputers.sfdk.worker` job. Then the install
+  defines `OrchestraWorker`, `orchestra-worker.service` or `ai.livingcomputers.orchestra.worker`. When the
+  removal fails, the install stops and defines nothing new. Change your own scripts that name the old ones.
+
   **The machine-wide service is the image role's, and the role is the whole of what asks for it.** An
   `image` gets it — a property list under `/Library/LaunchDaemons`, a unit under `/etc/systemd/system`,
   a Windows service — because the platform builds the image with nobody logged in to it and nobody
@@ -98,8 +107,10 @@ shapes the schema ships, and nothing here re-declares one.
   virtual-machine image is made by `worker install-machine` below, which our bakes run; the `image` role
   stays for a container image, whose own command is the worker.
 
-  `--root` follows the scope the same way: `~/.sfdk/worker` (`%LOCALAPPDATA%\sfdk\worker` on Windows) for
-  a `user` install, `/var/lib/sfdk/worker` (`%ProgramData%\sfdk\worker`) for the other two. A `user`
+  `--root` follows the scope the same way: `~/.orchestra/worker` (`%LOCALAPPDATA%\orchestra\worker` on
+  Windows) for a `user` install, `/var/lib/orchestra/worker` (`%ProgramData%\orchestra\worker`) for the other
+  two. Where the earlier release's root already holds the worker's identity or its install, the
+  install keeps that root instead. A `user`
   install writes its log under that root, at `log/worker.log`, because no service manager in that scope
   keeps one a person can read.
 
@@ -145,12 +156,14 @@ shapes the schema ships, and nothing here re-declares one.
   `--root` and installs under the machine-wide root. Each step reads the current state, changes only what
   differs, reads the result back and prints `ok: <step>` or `changed: <step>`; the first failure stops the
   run. So a second run on a converged host changes nothing, and a run that stopped part way is repaired by
-  running it again. It refuses a host that has already booted as a machine — a boot file or `<root>/state`
-  is there — because removing one is not a repair, and it refuses a running worker service. On Windows it
-  creates `<root>`, the install root `C:\software-factory` and its `etc` folder for SYSTEM and
-  Administrators alone, with Users also reading and running the install root, whose `bin` and `node` are
-  on the machine path; a folder already there is kept, so a host that made one first keeps its
-  permissions.
+  running it again. It refuses a host that has already booted as a machine, where a boot file or
+  `<root>/state` is there. Removing one is not a repair. It also refuses a running worker service,
+  under its name or the name an earlier release used. On Windows, the command creates three separate
+  directories: `<root>`, the install root `C:\software-factory`, and the `etc` directory in the install
+  root. Only SYSTEM and Administrators may use these three directories. Users may also read and run the
+  install root, whose `bin` and `node` directories are on the machine path. The command keeps a
+  directory that is already there, with that directory's permissions. The service step
+  removes a service with the earlier release's name, then defines the new one.
 
   The service runs from a copy of the release package at `<root>/package`, because the self-update
   replaces the directory the running binary sits in; the step compares that copy's `worker version`
@@ -178,7 +191,7 @@ shapes the schema ships, and nothing here re-declares one.
   this boot does not carry is removed, so a resumed VM never reads its previous launch's file. Each file
   is written under a staged name of its own, created new with its permissions before any byte, and
   renamed into place: on Linux at modes `0600`, `0600` and `0644`, the egress authority being the one the
-  agent's programs read, and on Windows readable by SYSTEM and Administrators alone. On Windows it starts `SfdkWorker` last; on Linux systemd starts the worker's unit after this one ends.
+  agent's programs read, and on Windows readable by SYSTEM and Administrators alone. On Windows it starts `OrchestraWorker` last, or `SfdkWorker` on an image an earlier release built; on Linux systemd starts the worker's unit after this one ends.
 - **`worker enroll`** redeems the enrollment token this machine was given, prints the row it was
   issued, and then serves that machine. It does not stop at the redemption, because the holder key
   the redemption bound lives in this process.
@@ -213,11 +226,15 @@ shapes the schema ships, and nothing here re-declares one.
   A pending restart is reported and never refused: Sysprep refuses to generalize while one is pending.
 - **`worker trust-nested [--registry <host>]... [--root <dir>]`** lets the containers this machine
   runs trust the egress edge, which nothing does by default. It reads the authority from
-  `SFDK_EGRESS_CA_FILE`, which the worker sets on every harness process and on the setup script;
+  `ORCHESTRA_EGRESS_CA_FILE`, which the worker sets on every harness process and on the setup script;
   writes it into dockerd's `certs.d` for the well-known registries and each one named; writes
   `k3d-registries.yaml` under the root, whose `ca_file` is the authority's path inside each k3d node;
   and prints the flags `docker run`, compose and `k3d cluster create` need. On a machine that names no
   authority, such as one with no edge in front of it, it says so, writes nothing and succeeds.
+- **`worker redirect`** prints the redirect table this worker wrote, or says that none is installed;
+  **`worker redirect remove`** deletes it. Each runs with its caller's own rights, so without
+  `CAP_NET_ADMIN` the kernel refuses both, and each exits 0 on an answer and 1 on a failure. Off Linux
+  both refuse, naming the operating system. What the table holds is under the in-guest egress below.
 - **`worker version`** prints this binary's version, the release package it belongs to, and the
   protocol versions it speaks.
 
@@ -228,43 +245,46 @@ version it is not.
 ## The bootstrap a machine is started with
 
 Everything above assumes the worker already knows where its platform is. That is the one family of
-names it reads before it can speak to anything, so they are the worker's own rather than the
-contract's: the environment document owns the other `SFDK_` names the platform or the worker sets for a
-running machine and says these are outside its scope. They carry the same reserved prefix, so an environment
-cannot declare one; the only `SFDK_` names an environment may declare are the release settings
-`fwp/schema/environment-v1.json` lists under `customerDeclarable`, which the worker reads from its own
-environment in preference to the register answer. The platform composes what is listed here; a value it does not
-set is a concern this machine does not have.
+names it reads before it can speak to anything. `fwp/schema/environment-v1.json` lists them in its
+`bootstrap` list, apart from the other names the platform or the worker sets for a running machine. The
+table below gives each in its former spelling. Each also has a name under `ORCHESTRA_WORKER_`, the
+document's `name`, which the worker reads first; it reads the former spelling when the new one is absent
+or blank. The two enrollment carriers are read under their former spelling alone for now. An
+environment cannot declare a name under `SFDK_` or `ORCHESTRA_`, apart from the release settings the
+document lists under `customerDeclarable`, which the worker reads from its own environment in preference to
+the register answer. The platform composes what is listed here; a value it does not set is a concern this
+machine does not have.
 
 | name | what it carries |
 |---|---|
-| `SFDK_CLAIM_ENDPOINT_URL` | the platform's origin, not a route: the paths belong to the protocol |
-| `SFDK_TRANSPORT_TRUST_ROOTS` | the certificate bundle this machine trusts, inline |
-| `SFDK_TRANSPORT_TRUST_ROOTS_FILE` | the same bundle as an absolute path, for a delivery that cannot carry the newlines; setting both is refused |
-| `SFDK_CLAIM_LOCATOR` | the machine row this worker claims as |
-| `SFDK_ENROLLMENT_TOKEN` | the show-once token an enrolling machine redeems; mutually exclusive with the locator |
-| `SFDK_ENROLLMENT_TOKEN_FILE` | the same token as an absolute path; setting both is refused |
-| `SFDK_HOLDER_KEY_ALGORITHM` | which of the protocol's two holder-key algorithms this registration declares |
-| `SFDK_SUBSTRATE` | which evidence this worker gathers, so an unknown value is refused rather than defaulted |
-| `SFDK_CLAIM_AUDIENCE` | who the presented caller-identity request was meant for; required on the virtual-machine lanes |
-| `SFDK_STS_ENDPOINT_URL` | the security-token endpoint the platform will send that request to |
-| `SFDK_SERVICE_ACCOUNT_TOKEN_FILE` | where the audience-bound projected token is mounted, on the Kubernetes lane |
-| `SFDK_TPM_DEVICE_PATH` | the chip's device path where it is not this operating system's default |
-| `SFDK_SUBSTRATE_TOKEN` | the `local` substrate's stand-in factor, inline |
-| `SFDK_SUBSTRATE_TOKEN_FILE` | the same factor as an absolute path; setting both is refused |
-| `SFDK_INTERCEPT_PORTS` | the destination ports whose traffic goes to the egress edge, comma separated; naming none installs no redirect |
-| `SFDK_INTERCEPT_BYPASS` | the shared services the worker's own uid reaches directly, as `[{"host": …, "port": …}]` — our broker and our gateway, and nothing broader |
-| `SFDK_INTERCEPT_SKIP_RANGES` | the private ranges the redirect never takes, for any uid on any port, as comma-separated CIDR ranges; a range that is not wholly private is refused |
-| `SFDK_EDGE_ENDPOINT_URL` | where the redirect sends this machine's traffic; its scheme is the whole TLS statement for that hop |
-| `SFDK_EGRESS_LISTEN_PORT` | where the redirect lands, which is the shim's own listen port |
-| `SFDK_EGRESS_IPV6` | `true` mirrors the redirect through `ip6tables` |
-| `SFDK_EGRESS_PROXY` | `on`, the default, or `off`; `off` tells each harness that no edge of ours stands in front of this machine, as on an enrolled one. The platform writes `off` into every Launcher machine's boot file, because no proxy entrance of ours stands in front of one yet |
-| `SFDK_RUNTIME_ENVIRONMENT` | a whole environment folded into one JSON object of string values, for a boot file whose lines cannot carry a line break; each pair is placed unless already set, except that a non-blank pair replaces a name that holds exactly the image's placeholder |
-| `SFDK_VOLUME_MOUNTS` | the volumes this launch declares, as one JSON document |
-| `SFDK_MACHINE_SLUG` | the machine's platform-minted slug: the leading label of its preview hostnames, and what the tunnel's upgrade signs |
-| `SFDK_TUNNEL_ENDPOINT_URL` | where the preview gateway serves its tunnel listener; its scheme is the whole TLS statement for that hop |
-| `SFDK_INGRESS_PORTS` | the loopback ports this machine projects through that tunnel, comma separated; with no reserved ports below, naming none holds no tunnel |
-| `SFDK_INGRESS_ANY_PORT_EXCEPT` | the reserved loopback ports, comma separated; set, the tunnel is held from start, forwards every other port whatever `SFDK_INGRESS_PORTS` says, and the worker registers `ingress-any-port` |
+| `ORCHESTRA_WORKER_CLAIM_ENDPOINT_URL` | the platform's origin, not a route: the paths belong to the protocol |
+| `ORCHESTRA_WORKER_TRANSPORT_TRUST_ROOTS` | the certificate bundle this machine trusts, inline |
+| `ORCHESTRA_WORKER_TRANSPORT_TRUST_ROOTS_FILE` | the same bundle as an absolute path, for a delivery that cannot carry the newlines; setting both is refused |
+| `ORCHESTRA_WORKER_CLAIM_LOCATOR` | the machine row this worker claims as |
+| `ORCHESTRA_WORKER_ENROLLMENT_TOKEN` | the show-once token an enrolling machine redeems; mutually exclusive with the locator |
+| `ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE` | the same token as an absolute path; setting both is refused |
+| `ORCHESTRA_WORKER_HOLDER_KEY_ALGORITHM` | which of the protocol's two holder-key algorithms this registration declares |
+| `ORCHESTRA_WORKER_SUBSTRATE` | which evidence this worker gathers, so an unknown value is refused rather than defaulted |
+| `ORCHESTRA_WORKER_CLAIM_AUDIENCE` | who the presented caller-identity request was meant for; required on the virtual-machine lanes |
+| `ORCHESTRA_WORKER_STS_ENDPOINT_URL` | the security-token endpoint the platform will send that request to |
+| `ORCHESTRA_WORKER_SERVICE_ACCOUNT_TOKEN_FILE` | where the audience-bound projected token is mounted, on the Kubernetes lane |
+| `ORCHESTRA_WORKER_TPM_DEVICE_PATH` | the chip's device path where it is not this operating system's default |
+| `ORCHESTRA_WORKER_SUBSTRATE_TOKEN` | the `local` substrate's stand-in factor, inline |
+| `ORCHESTRA_WORKER_SUBSTRATE_TOKEN_FILE` | the same factor as an absolute path; setting both is refused |
+| `ORCHESTRA_WORKER_INTERCEPT_PORTS` | the destination ports whose traffic goes to the egress edge, comma separated; naming none installs no redirect |
+| `ORCHESTRA_WORKER_INTERCEPT_BYPASS` | the shared services the worker's own uid reaches directly, as `[{"host": …, "port": …}]` — our broker and our gateway, and nothing broader |
+| `ORCHESTRA_WORKER_INTERCEPT_SKIP_RANGES` | the private ranges the redirect never takes, for any uid on any port, as comma-separated CIDR ranges; a range that is not wholly private is refused |
+| `ORCHESTRA_WORKER_EDGE_ENDPOINT_URL` | where the redirect sends this machine's traffic; its scheme is the whole TLS statement for that hop |
+| `ORCHESTRA_WORKER_EGRESS_LISTEN_PORT` | where the redirect lands, which is the shim's own listen port |
+| `ORCHESTRA_WORKER_EGRESS_IPV6` | `true` also writes the worker's redirect table for IPv6 |
+| `ORCHESTRA_WORKER_EGRESS_PROXY` | `on`, the default, or `off`; `off` tells each harness that no edge of ours stands in front of this machine, as on an enrolled one. The platform writes `off` into a Launcher machine's boot file only where the deployment names no public egress entrance |
+| `ORCHESTRA_WORKER_LAUNCHER` | `true` on a machine a customer's Launcher created, written by that boot file alone; absent or `false` elsewhere. Such a machine with no `egress-redirect` file under the worker root runs the local egress port on loopback with no redirect |
+| `ORCHESTRA_WORKER_RUNTIME_ENVIRONMENT` | a whole environment folded into one JSON object of string values, for a boot file whose lines cannot carry a line break; each pair is placed unless already set, except that a non-blank pair replaces a name that holds exactly the image's placeholder |
+| `ORCHESTRA_WORKER_VOLUME_MOUNTS` | the volumes this launch declares, as one JSON document |
+| `ORCHESTRA_WORKER_MACHINE_SLUG` | the machine's platform-minted slug: the leading label of its preview hostnames, and what the tunnel's upgrade signs |
+| `ORCHESTRA_WORKER_TUNNEL_ENDPOINT_URL` | where the preview gateway serves its tunnel listener; its scheme is the whole TLS statement for that hop |
+| `ORCHESTRA_WORKER_INGRESS_PORTS` | the loopback ports this machine projects through that tunnel, comma separated; with no reserved ports below, naming none holds no tunnel |
+| `ORCHESTRA_WORKER_INGRESS_ANY_PORT_EXCEPT` | the reserved loopback ports, comma separated; set, the tunnel is held from start, forwards every other port whatever `ORCHESTRA_WORKER_INGRESS_PORTS` says, and the worker registers `ingress-any-port` |
 
 **The worker reads that file itself, on every operating system, and no service manager is handed it.**
 Every `worker run` places each pair into its own environment before it serves, leaving alone any name
@@ -274,16 +294,17 @@ a placeholder the family facts list, whether or not an egress edge stands in fro
 customer's own token in `provisionSpec.env` reaches the harness; it rides the machine's startup data in
 plain text. systemd's
 `EnvironmentFile=` is deliberately not used: it processes backslash escapes in an unquoted value, so
-the two characters `\n` that carry a line break inside `SFDK_RUNTIME_ENVIRONMENT` would arrive as a bare
+the two characters `\n` that carry a line break inside `ORCHESTRA_WORKER_RUNTIME_ENVIRONMENT` would arrive as a bare
 `n` and the certificate folded in there would hold no certificate at all. A machine with no file
 starts anyway — that is an enrolled machine's ordinary start — and a line that is not `NAME=VALUE`
 stops the start and is named.
 
 Where the file sits is the one thing that differs, and only because of who may write it. On a Linux
-machine the platform launched, cloud-init writes `/etc/sfdk/machine.env` from the user data and the run
+machine the platform launched, cloud-init writes `/etc/orchestra/machine.env`, and `/etc/sfdk/machine.env` for a worker
+of an earlier release, from the user data and the run
 reads it; on an Azure machine `worker boot-files` writes the same file from the VM's userData, and
 `<root>\machine.env` on Windows. No install by a person writes there. A `worker` install that registers a service writes
-`<root>/machine.env` under the worker's own root — `C:\ProgramData\sfdk\worker\machine.env` on a default
+`<root>/machine.env` under the worker's own root — `C:\ProgramData\orchestra\worker\machine.env` on a default
 machine-wide Windows install — because an install that registers the worker in one person's own session
 cannot write under `/etc`. A Linux run reads both, the machine-wide one first. The platform's user data writes that file on a machine
 it launched, and a person enrolling one writes it or exports the same names in the shell that runs
@@ -303,8 +324,8 @@ rather than woken, and its row is fresh with it.
 
 ## The in-guest egress
 
-On the virtual-machine lanes this worker's own process is the transparent proxy, and it puts three
-things in place in one order that is not interchangeable:
+Wherever the launch names an intercept set, this worker's own process is the transparent proxy, and
+it puts three things in place in one order that is not interchangeable:
 
 1. **The edge's certificate authority into this machine's trust store**, from the file the launch
    wrote (or, where that file is not there, from the URL it names). Windows reads the machine
@@ -315,9 +336,23 @@ things in place in one order that is not interchangeable:
 2. **The listener**, bound before any rule exists, so no connection is ever sent to a port with
    nothing behind it. On Windows an inbound firewall rule is written first as well: the rewritten
    packet arrives as an inbound connection, which Windows Server blocks by default.
-3. **The redirect** — `iptables` on Ubuntu, WinDivert on Windows. The two WinDivert files are loaded
-   by absolute path from `<root>\bin`, where `install-machine --egress-redirect` places them, and never through the
-   operating system's own search order: opening the driver installs and starts a kernel service.
+3. **The redirect** — the worker's own nftables table on Linux, WinDivert on Windows. The two
+   WinDivert files are loaded by absolute path from `<root>\bin`, where `install-machine --egress-redirect`
+   places them, and never through the operating system's own search order: opening the driver installs and starts
+   a kernel service.
+
+On Linux the worker runs no program from the image to install its redirect, so an image needs neither
+`iptables` nor `nft`. It writes one table, `orchestra_worker`, in the `ip` family and, where the launch
+declares IPv6, in `ip6` too, over netlink through `github.com/google/nftables`, in one transaction the
+kernel takes whole or not at all. Each bypassed host is resolved once, when the table is written, and
+the rules hold the addresses it resolved to then. The kernel needs nftables for each family in play
+(`CONFIG_NF_TABLES` with `CONFIG_NF_TABLES_IPV4` or `_IPV6`), `CONFIG_NFT_NAT` and `CONFIG_NFT_REDIR`,
+built in or as modules; a kernel missing one fails the install, and the error names the part.
+
+The table is written once, at the start, and the running worker never writes it again, so a table
+`worker redirect remove` deleted stays deleted until the next start; `worker redirect` prints it as
+`nft list table` would. A worker updated in place from a release that installed `iptables` rules keeps
+those rules, which `worker redirect remove` does not touch.
 
 Each accepted connection's original destination is recovered (`SO_ORIGINAL_DST` on Linux, the
 redirect's own proxy-port map on Windows; a recovery that misses is refused rather than sent to the
@@ -332,13 +367,24 @@ this worker calls it before it holds the token the edge would identify it by; an
 service, which answers the evidence that call presents. Nothing is uid-wide, so the object store
 stays intercepted and this worker's own content pulls meet the platform's rule at the edge.
 
-The redirect takes its Windows form on Windows and its `iptables` form everywhere else, whatever the
+The redirect takes its Windows form on Windows and its nftables form everywhere else, whatever the
 substrate. A pod with an egress sidecar runs only the certificate step: the sidecar installs that
-lane's redirect and runs its own shim, which reads the token from the loopback feed below. A pod with
-no sidecar, as a customer's Launcher creates, names an intercept set and this worker installs the
-redirect itself.
-
-The private ranges `SFDK_INTERCEPT_SKIP_RANGES` names are never redirected, for any uid on any port:
+lane's redirect and runs its own shim, which reads the token from the loopback feed below. A Launcher
+machine, a Launcher pod included, names an intercept set: where `install-machine --egress-redirect`
+wrote the file `egress-redirect` under the worker root this worker installs the redirect itself, and
+where it did not, as on an image built before that file existed, the worker binds the local egress port
+on loopback alone and each harness reaches it through the proxy names. The machine's token stays in
+this worker either way.
+
+The local egress port resolves a destination's name once. Where every address it answers is in a range
+`SFDK_INTERCEPT_SKIP_RANGES` names or is a compiled-in exemption, the port dials that address itself;
+otherwise it forwards the request to the edge by name. `NO_PROXY` lists the same ranges and exemptions
+for a tool that reads ranges, and then names the host of `ORCHESTRA_EGRESS_CA_URL`, so a harness fetches
+the edge's certificate directly rather than through an edge that may refuse it. On an Azure machine the
+compiled-in exemptions are the metadata service and the platform's host address `168.63.129.16`, which
+skip the redirect on Windows and on Linux.
+
+The private ranges `ORCHESTRA_WORKER_INTERCEPT_SKIP_RANGES` names are never redirected, for any uid on any port:
 the rules return them ahead of the redirect, a nested container reaches them through its bridge, and
 the Windows filter excludes each range beside the single destinations.
 
@@ -483,21 +529,22 @@ artifacts:
 
 The worker does not *merge* an environment into a harness process: the family's `passEnv` enumeration in
 `facts/families.json` **is** that process's complete environment. An environment cannot declare an
-`SFDK_` name for it, because `SFDK_` is reserved apart from the four `SFDK_WORKER_*` release settings, which
+`ORCHESTRA_` or `SFDK_` name for it, because both are reserved apart from `ORCHESTRA_FDK_` names and the seven
+`ORCHESTRA_WORKER_*` settings, which
 reach the worker and never a harness process. A derived image that bakes a name the list does not carry, such as `ENV JOB_TARGET=…`, gets **silence**,
 not an override: the variable never reaches the command, and a job running under `set -u` aborts on the
 first reference to it. Per-job configuration travels the prompt, the agent's instructions, or a file in the
 image.
 
 The worker consumes every `ORCHESTRA_WORKER_<FIELD>` variable itself and drops it from every list,
-`SFDK_EXTRA_PASSENV` included: those are the sign-in and settings the worker places for the harness, from the
+`ORCHESTRA_EXTRA_PASSENV` included: those are the sign-in and settings the worker places for the harness, from the
 `settings` table of `facts/families.json` (`docs/architecture/agent-runtime-images.md` § *The worker places
 each harness's sign-in and settings*).
 
-Every family's harness process also gets `SFDK_SESSION_ID`, which the worker sets from the `sessionId` on
+Every family's harness process also gets `ORCHESTRA_SESSION_ID`, which the worker sets from the `sessionId` on
 `session_placement.apply`: the worker adds it itself, so it needs no `passEnv` entry, whatever the worker's
 own environment holds. The `script` family adds only the organization to the command it runs, as
-`ORCHESTRA_ORGANIZATION_ID` and `SFDK_ORGANIZATION_ID`, from its stored conversation metadata; its command inherits
+`ORCHESTRA_ORGANIZATION_ID`, from its stored conversation metadata; its command inherits
 the session variable from the harness process. Neither grants egress authority.
 
 **On Windows the operating system's own variables are added to that list.** The list is not a filter over

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/worker",
-  "version": "0.0.141",
+  "version": "0.0.143",
   "type": "module",
   "description": "The Orchestra worker.",
   "license": "Apache-2.0",
@@ -22,10 +22,10 @@
     "docs/REFERENCE.md"
   ],
   "optionalDependencies": {
-    "@orchestraworks/worker-linux-x64": "0.0.141",
-    "@orchestraworks/worker-linux-arm64": "0.0.141",
-    "@orchestraworks/worker-darwin-x64": "0.0.141",
-    "@orchestraworks/worker-darwin-arm64": "0.0.141",
-    "@orchestraworks/worker-win32-x64": "0.0.141"
+    "@orchestraworks/worker-linux-x64": "0.0.143",
+    "@orchestraworks/worker-linux-arm64": "0.0.143",
+    "@orchestraworks/worker-darwin-x64": "0.0.143",
+    "@orchestraworks/worker-darwin-arm64": "0.0.143",
+    "@orchestraworks/worker-win32-x64": "0.0.143"
   }
 }