@orchestraworks/worker 0.0.136 → 0.0.138

package/bin/worker.js

@@ -53,11 +53,13 @@ function statusFor(code, signal) {
 }
 
 function run(binary) {
-  const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
-
+  let child;
+  // Listening at all is what stops Node ending the launcher on its own and orphaning the worker
+  // mid-shutdown: the launcher outlives the signal and exits on the child's exit instead. The listeners go
+  // in before the spawn: the binary runs from the moment spawn returns, and a signal that reached the
+  // launcher before its listeners would kill it. Node runs a listener from the event loop, so by then
+  // `child` is set.
   for (const signal of FORWARDED_SIGNALS) {
-    // Listening at all is what stops Node ending the launcher on its own and orphaning the worker
-    // mid-shutdown: the launcher outlives the signal and exits on the child's exit instead.
     process.on(signal, () => {
       if (child.exitCode === null && child.signalCode === null) {
         child.kill(signal);
@@ -65,6 +67,8 @@ function run(binary) {
     });
   }
 
+  child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
   child.on("error", (failure) => {
     console.error(`worker: ${failure.message}`);
     process.exit(1);

package/docs/REFERENCE.md

@@ -204,7 +204,7 @@ set is a concern this machine does not have.
 | `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 |
+| `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 with `SFDK_EGRESS_PROXY=off` a pair replaces a name that holds exactly the image's egress 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 |
@@ -213,7 +213,11 @@ set is a concern this machine does not have.
 
 **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
-that is already set, so a person's own foreground run still wins over the file. systemd's
+that is already set, so a person's own foreground run still wins over the file. One name already set
+is replaced: where the switch `SFDK_EGRESS_PROXY` is `off`, no edge replaces the image's placeholder
+credential on the way out, so a value the launch declared replaces a name that holds exactly a
+placeholder the family facts list. That is how a customer's own token in `provisionSpec.env` reaches the
+harness on a Launcher machine; 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
 `n` and the certificate folded in there would hold no certificate at all. A machine with no file
@@ -429,36 +433,36 @@ not an override: the variable never reaches the command, and a job running under
 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
+`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
 `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
 the session variable from the harness process. Neither grants egress authority.
 
-**On Windows that list is shorter than the operating system's own habits assume.** It is
-OS-independent, so a Windows job sees `PATH`, `HOME` and `USERPROFILE` and *not* `TEMP`, `APPDATA` or
-`ComSpec` — names a PowerShell one-liner reaches for without thinking (`$env:TEMP`). The list is not a
-filter over the environment: the worker *builds* the child's environment from it, so a name the platform
-set on the service and the family does not declare is simply gone by the time the command runs.
-
-**Three names are backfilled for Windows and none of them is on any family's list.** A backfill is the
-treatment for operating-system *plumbing* — a variable the machine needs to work at all, as opposed to
-configuration a customer chose — and it is if-absent, so a declared spelling always wins. Two come from
-libraries: Go's `os/exec` adds `SYSTEMROOT` whenever a caller sets an explicit environment, and libuv copies
-its own required-variable set into a spawned child from *this* process's environment — which is why `PATH`
-reaching the command is what lets `powershell.exe` and `taskkill.exe` resolve at all. The third is ours:
-**`PATHEXT`**, the list of extensions PowerShell treats as *executable*. With it unset the effective list
-collapses to `.CPL`, so a `curl.exe` PowerShell resolved on `PATH` is a **document** rather than a program
-and invoking it throws `CantActivateDocumentInPipeline` — before a process starts, before a packet leaves.
-Every network probe on the Windows lane came back `000`, which reads exactly like a blocked connection.
-
-The neighbours a reader expects beside it were **measured and left out**, each changing nothing on a Windows
-Server 2025 runtime AMI: `cmd.exe` and `.bat` files run from CreateProcess's own default without `ComSpec`,
-`%SystemRoot%` expands from the `SYSTEMROOT` `os/exec` already backfills, `SystemDrive` and `windir` are
-unused by realistic work, and a service's temp directory falls back to `C:\Windows\SystemTemp` without
-`TEMP` or `TMP`. Add a fourth name only with that kind of evidence. Machine plumbing is not configuration
-and must never be pushed into the prompt: a job cannot set `PATHEXT` for a shell that has already refused to
-start its first program.
+**On Windows the operating system's own variables are added to that list.** The list is not a filter over
+the environment: the worker *builds* the child's environment from it, so a name the platform set on the
+service and the family does not declare is simply gone by the time the command runs. Windows programs
+assume their own variables are there, so the worker adds them from its own environment to every harness,
+and so to every hook and command the harness starts, and to the setup script: `WINDIR`, `SYSTEMROOT`,
+`SYSTEMDRIVE`, `COMSPEC`, `PATHEXT`, `TEMP`, `TMP`, `PROGRAMDATA`, `ALLUSERSPROFILE`, `ProgramFiles`,
+`ProgramFiles(x86)`, `ProgramW6432`, `CommonProgramFiles`, `CommonProgramFiles(x86)`, `CommonProgramW6432`,
+`APPDATA`, `LOCALAPPDATA`, `USERNAME`, `USERDOMAIN`, `COMPUTERNAME`, `OS`, `PROCESSOR_ARCHITECTURE`,
+`NUMBER_OF_PROCESSORS`, `PSModulePath` and `DriverData`. None of them carries a credential, and a name the
+family or the launch already declares, in any spelling, is not added twice.
+
+Two failures show why. With **`PATHEXT`** unset, PowerShell's list of executable extensions collapses to
+`.CPL`, so a `curl.exe` it resolved on `PATH` is a **document** rather than a program and invoking it throws
+`CantActivateDocumentInPipeline` — before a process starts, before a packet leaves. With **`WINDIR`** unset,
+`Import-Module Storage` looks for its library under `C:\system32` rather than `C:\Windows\system32`, so
+`Mount-DiskImage` and `Get-Volume` fail. On Windows the harness runs as the worker's own account, so the
+per-user names (`TEMP`, `APPDATA`, `USERNAME`) are that account's own. Machine plumbing is not
+configuration and must never be pushed into the prompt: a job cannot set `PATHEXT` for a shell that has
+already refused to start its first program.
 
 Three more bounds a job author should know:
 

package/package.json

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