@orchestraworks/worker 0.0.152 → 0.0.153

package/docs/REFERENCE.md

@@ -22,8 +22,9 @@ The worker exposes no API of its own. Every route it calls is the platform's.
 | `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 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 |
+| `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, and the WinDivert half that is the Windows redirect |
 | `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 |
+| `oneworker/` | the one-worker lock: the fixed loopback port whose bind stops a second worker on the machine |
 | `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 |
 | `termination/` | the cloud's notice that this machine is being reclaimed, delivered to the broker so the next status report carries it |
 | `paths/` | which native place a logical path denotes, and when two logical paths denote one place — pinned against the platform's own answer by committed vectors |
@@ -48,12 +49,12 @@ Each `ORCHESTRA_` machine variable this page names also has a former `SFDK_` spe
   work consumer and reports on the cadence.
 
   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: 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.
+  the in-guest egress in place where the launch names an intercept set, takes the one-worker lock, 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 launch that names no volumes places none, and one that names no
+  intercept set installs no redirect. 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.
 
   `--service` is how the process is hosted rather than what it does: on Windows it hands the body to
   the service control manager, which kills a service that does not answer its handshake, and on the
@@ -82,17 +83,31 @@ Each `ORCHESTRA_` machine variable this page names also has a former `SFDK_` spe
   forms fill the installer seam in `cmd/worker/install.go`; a build with none refuses rather than
   reporting an install it did not perform.
 
-  **An install that names a family stops the running worker first.** When `--harness` names a family
-  and `--service` is not `none`, the install stops the worker service in its scope, and the service an
-  earlier release registered, before it changes anything under the root. A running service installs and
-  runs harnesses from that same root, and nothing else keeps the two apart. The stop keeps each
-  service's definition, and the install prints `the worker service is stopped while this install changes
-  <root>`. The service starts again only after the whole install succeeds, and then at the time its role
-  sets, below. When the stop fails, the install changes nothing. When a later step fails, or a signal
-  interrupts the install after the stop, the service stays stopped and the error says so; for a `worker`,
-  run `worker install` again to start it. A signal during the stop itself gives an error that says the
-  service may still be stopping. A signal before the stop ends the install quietly, with nothing stopped
-  and nothing changed.
+  **An install stops the running worker when it changes what the service reads.** When `--service` is not
+  `none`, the install may stop the worker service in its scope, and the service an earlier release
+  registered. It stops them in three cases. A named family, or the pinned Node the families run on, needs
+  installing. An enrollment token, or its file, is in its environment. The service definition it writes
+  differs from the one on disk, or, for a `worker`, the bootstrap file does. A file it cannot read counts
+  as different. On Windows the definition never counts as different: a changed one takes effect at the
+  next start. Otherwise it leaves the service as it is. A running service installs and runs harnesses
+  from the same root, and nothing else keeps the two apart. Only a fresh start redeems an enrollment
+  token, and the install waits for the registration that start makes. On macOS, launchd also loads a
+  changed property list only after a stop. A definition that counts as different, or a changed bootstrap
+  file, stops the service, so it does not keep running on the old ones. A `worker` then starts again at
+  once.
+
+  The stop keeps each service's definition, and the install prints `the worker service is stopped while
+  this install runs`. The service starts again only after the whole install succeeds, and then at the
+  time its role sets, below. When the stop fails, the install changes nothing. When a later step fails,
+  or a signal interrupts the install after the stop, the service stays stopped and the error says so. For
+  a `worker`, run `worker install` again to start it. A signal during the stop itself gives an error that
+  says the service may still be stopping. A signal before the stop ends the install quietly, with nothing
+  stopped and nothing changed.
+
+  **An install that would change nothing does not stop the worker service.** A running service keeps
+  its open turns. The install prints `this install changes nothing under <root> and does not stop the
+  worker service; an upgraded worker runs after the service restarts`. A worker upgraded at the same path
+  leaves the definition as it is, so the running service keeps the program it started with.
 
   **`--service` says which session the worker is registered in, and neither of its two values needs any
   privilege.** `user` registers it in the invoking account's own session: a launch agent under
@@ -381,8 +396,7 @@ service, which answers the evidence that call presents. Nothing is uid-wide, so
 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 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 Launcher
+substrate. A launch that names no intercept set runs only the certificate step. 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
@@ -407,24 +421,15 @@ because the metadata service is never reached through a proxy. Where a redirect
 names are left out of the environment each harness and the setup script are handed, so the agent's
 calls reach the redirect, which carries them to the edge.
 
-## The egress shim's token feed
+## The one-worker lock
 
-The shim that intercepts this machine's traffic stamps the machine token on it, and the worker is
-what holds that token. On Kubernetes the two are in different containers of one pod, so the only
-channel between them is the network: the worker listens on `127.0.0.1:7788` — a constant both halves
-carry, not a placed value — and the shim connects with retry.
+On every machine the worker listens on `127.0.0.1:7788`, so that a second worker started on the same
+machine finds the port held and stops. The port is a constant, not a placed value, and
+`orchestra outpost up` checks the same port to refuse a second outpost on one machine.
 
-Each frame is one JSON line, newline-terminated:
-
-```
-{"generation": 7, "token": "<the machine token>", "expiresAt": "2026-09-12T10:15:00.123456Z"}
-```
-
-On connect the worker writes the generation this machine holds now, and one line per rotation after
-that. It writes nothing else on that socket and never reads from it, and it listens on loopback and
-nowhere else. A worker restart drops the connection; the shim reconnects and is fed the current
-generation again. The broker credential co-issued beside the token never crosses this channel, and
-neither does the holder key.
+The worker writes nothing on that port: it closes each connection as soon as it accepts it, and a
+completed connection is the whole answer. It listens on loopback and nowhere else. No credential
+crosses this port: not the machine token, the broker credential or the holder key.
 
 ## Building and testing
 

package/package.json

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