@vzn/vx-dte 0.0.651 → 0.0.653

package/README.md

@@ -5,7 +5,8 @@ Website: <https://vznjs.github.io/vx/> · source: <https://github.com/vznjs/vx>
 Distributed task execution for vx: one `vx run` spread over workers your
 own CI starts, replayed here as one run. The run you start is the
 orchestrator. It runs no task itself, only restores cache hits: it starts
-workers and hands the ready tasks to the workers with room, critical path first. A worker runs it in its own checkout and saves the task's
+workers and hands the ready tasks to the workers with room, critical path first,
+ranked by history and ranked again when fetched timings land. A worker runs it in its own checkout and saves the task's
 output and the files its declared outputs left to the workspace's cache,
 under the task's key. They land here before the task ends, so the run
 reports the task as its own. No file travels through the relay: it
@@ -64,12 +65,12 @@ the initiator.
   anyone who reads the repository's Actions sees. A dispatch GitHub
   answers without a run id (204) is refused, so its workers exit.
 
-| Who           | `info` / `body`                                         |
-| ------------- | ------------------------------------------------------- |
-| worker `join` | `info: { "noise": <message 1>, "token"? }`              |
-| orchestrator  | `{ "type": "hello", "noise": <message 2>, "token"? }`   |
-| orchestrator  | `{ "type": "refused", "reason" }`, plain, then `remove` |
-| either, then  | `{ "seal": ["<n>.<ciphertext>", …] }`                   |
+| Who           | `info` / `body`                                            |
+| ------------- | ---------------------------------------------------------- |
+| worker `join` | `info: { "noise": <message 1>, "token"? }`                 |
+| orchestrator  | `{ "type": "hello", "noise": <message 2>, "token"? }`      |
+| orchestrator  | `{ "type": "refused", "reason" }`, plain, then `remove`    |
+| either, then  | `["<n>.<ciphertext>", …]`, or `["+", …]` with more to come |
 
 The orchestrator checks each worker the moment the relay says it joined,
 and `remove`s one whose handshake fails. Message 1's payload is the
@@ -78,17 +79,28 @@ body is Noise transport messages, base64, each at most 65535 bytes and
 naming its nonce `n` (Noise §11.4, since a relay may reorder); each is
 sealed with associated data `<first n>.<parts>` of its body, so no part
 opens in another body, and a body's parts take consecutive nonces, so
-none is repeated or reordered in it. A body whose first nonce was seen before is a
+none is repeated or reordered in it. A body of more than 5 parts goes
+over several sends of 5, each but the last led by `"+"`, so no frame
+passes the relay's 1 MiB; the receiver holds them until the last and
+opens the body whole. A body whose first nonce was seen before is a
 replay and is dropped; one older than a body already opened (the relay
 held it back: the wire's numbers are outside the seal) or that does not
-open loses its sender. The
-plaintext is JSON, or over 256 bytes and smaller so, a `0` byte, the
-zstd frame's length (4 bytes, big-endian) and the frame: compressed
-before sealing, since no relay or socket compresses what is sealed. It
+open loses its sender. The plaintext is a lead byte, the length of
+every body its sender sealed before (4 bytes, big-endian, mod 2³²), and
+then, `1`, its JSON, an array of the messages sent together (up to 64
+KiB), or `0`, when smaller so, its zstd frame's length (4 bytes) and
+the frame: compressed before sealing, since no
+relay or socket compresses what is sealed. The orchestrator's are
+compressed against the last 16 KiB of its bodies' JSON to that worker
+as their dictionary, so a batch's env and paths said before cost a few
+bytes; a worker's go without one, which would cost the orchestrator
+some 100 µs to open each. A body whose length is not
+the receiver's own count was sealed after one it never opened, which the
+relay kept back, and loses its sender. It
 is padded with trailing spaces to its size class, a power of two from
-256 bytes, then whole transport messages, so the relay learns no size
+64 bytes, then whole transport messages, so the relay learns no size
 within a class. Inside, each send is numbered and acknowledged
-end to end, and a quiet worker reports (Switchboard § Delivery, § Liveness).
+end to end (`{ "n", "b", "a"? }`: its number, body and ack), and a quiet worker reports (Switchboard § Delivery, § Liveness).
 
 ## Try it
 
@@ -104,7 +116,7 @@ import { dte, local } from '@vzn/vx-dte'
 export default defineWorkspace({
   plugins: [
     dte({
-      workers: { small: { max: 4, cpu: 2, memory: '8GB' } },
+      workers: { linux: { machines: { small: { max: 4, cpu: 2, memory: '8GB' } } } },
       adapter: local({ prepare: 'bun install' }),
     }),
   ],
@@ -120,8 +132,9 @@ runs here as always (on GitHub Actions, `github()` with a relay names one
 itself). It is a random UUID, so no one can guess a run to
 open it first or join it; vx and the relay refuse any other. `local()` starts each worker as a process in its own
 git worktree of the tracked files as they are, uncommitted changes
-included (untracked files are not: a task that keys one fails; a run with
-an unmerged index, mid-merge, is refused), at the
+included, and a file mid-merge or flagged `assume-unchanged` or
+`skip-worktree` as it is on disk (untracked files are not: a task that keys
+one fails), at the
 workspace's place in it (a workspace in a subdirectory of its repository too),
 saving to the run's store (a relative `cache.dir` or `--cache-dir` too).
 A run from a git hook works too: the worktree and its worker drop the
@@ -130,7 +143,10 @@ index being committed is left as it is. When a worker fails, its row names
 the error line and the log that holds its whole stderr and all `prepare`
 printed. At the run's end,
 or on Ctrl-C, vx exits without waiting for the worktrees to be removed:
-a detached shell removes them and prunes git's records.
+a detached shell waits up to 5 s for the workers to leave, kills any
+still running, removes the worktrees and prunes git's records. A run whose vx
+was killed (`kill -9`) removes none; the next `local()` run in the
+repository removes them, once their run's process is gone.
 
 `docker()` starts each worker as a container held to its size: `--cpus`
 and `--memory` come from `cpu` and `memory`. The container clones this
@@ -148,7 +164,7 @@ names its error line and the log of its whole stderr and all `prepare` printed:
 
 ```ts
 dte({
-  workers: { small: { max: 4, cpu: 2, memory: '4GB' } },
+  workers: { linux: { machines: { small: { max: 4, cpu: 2, memory: '4GB' } } } },
   adapter: docker({ image: 'my/bun-git', prepare: 'bun install' }),
 })
 ```
@@ -222,7 +238,7 @@ export default defineWorkspace({
   plugins: [
     dte({
       relay: 'https://relay.example.com',
-      workers: { small: { max: 8, cpu: 4, memory: '16GB' } },
+      workers: { linux: { machines: { small: { max: 8, cpu: 4, memory: '16GB' } } } },
       adapter: github(),
     }),
   ],
@@ -285,7 +301,7 @@ workspace in a subdirectory of its repository gets them at the repository's
 root, its jobs running in that directory. Each size runs on
 its platform's GitHub-hosted runner (`ubuntu-latest` for none named,
 `ubuntu-24.04-arm`, `macos-latest`, `macos-15-intel`), or on the label
-`github({ runsOn: { small: 'ubuntu-latest-16-cores' } })` names, as
+a machine's `runsOn: 'ubuntu-latest-16-cores'` names, as
 `gitlab({ tags })` does. It installs with the package manager your lockfile
 names and runs vx as `bun vx`, which runs the repo's own and never
 downloads one, as `pnpm exec` does (Yarn too: Bun reads no Plug'n'Play,
@@ -326,7 +342,7 @@ jobs:
       id-token: write
       # A worker of a run that is over cancels its own run.
       actions: write
-    runs-on: ${{ fromJSON('{"small":"ubuntu-latest"}')[inputs.size] }}
+    runs-on: ${{ fromJSON('{"linux.small":"ubuntu-latest"}')[inputs.size] }}
     timeout-minutes: 30
     strategy:
       fail-fast: false
@@ -381,7 +397,7 @@ export default defineWorkspace({
   plugins: [
     dte({
       relay: 'https://relay.example.com',
-      workers: { small: { max: 4, cpu: 2, memory: '8GB' } },
+      workers: { linux: { machines: { small: { max: 4, cpu: 2, memory: '8GB' } } } },
       adapter: gitlab(),
     }),
   ],
@@ -437,12 +453,12 @@ vx:
     - bun install --frozen-lockfile
   script: [bun vx dte worker]
 
-'vx-worker small':
+'vx-worker linux.small':
   extends: .vx-worker
   parallel:
     matrix:
       - VX_DTE_SLOT: ['1', '2', '3', '4']
-  rules: [{ if: $VX_DTE_SIZE == "small" && $VX_DTE_SLOT =~ $VX_DTE_PICK }]
+  rules: [{ if: $VX_DTE_SIZE == "linux.small" && $VX_DTE_SLOT =~ $VX_DTE_PICK }]
 ```
 
 `gitlab({ tags })` names each size's runner tags. Each job's ID token
@@ -485,6 +501,13 @@ use your own instead.
   done. The run starts a worker of each
   platform its work needs. A task none of whose platforms any size has
   refuses the run before a worker starts.
+- A task naming `exec.worker` runs only on machines of that worker type;
+  any other on the first type, in declared order, with a machine of one
+  of its platforms. So a type listed last (a costly Mac) gets only the
+  tasks no other type can take. Core refuses the run before a worker
+  starts when no type has the name, or none of its machines runs one of
+  the task's platforms. A worker that joins on its own is of the first
+  type with its platform.
 - Tasks waiting for room go out longest tail first: a task's recorded
   duration and its longest chain of dependants, so a long chain that got
   ready late does not queue behind many short tasks ready at once.
@@ -501,9 +524,16 @@ use your own instead.
   A sandbox the worker cannot host (no `bwrap` in its image) fails the
   task there, as it fails here; the worker stays in the run.
 - A persistent task a task depends on starts on the worker that runs the
-  task, once per worker, ready before it, and stops when the worker leaves;
+  task, once per worker, ready before it, and stops there once no task left
+  in the run uses it (the run's `unneeded`), or when the worker leaves;
   the orchestrator never starts it, and a worker no dependant reaches
-  never does (2026-10-22).
+  never does (2026-10-22). Its CPU is learned on the worker each second
+  as `cores = base + each running dependant's cost`: the base from looks
+  with no dependant running, each cost from looks with it (a look on a
+  full machine only raises them). Each dependant's cost is added to its
+  CPU, so its history books it; the base is booked once on each worker
+  that starts the server, in placement and in the plan, and kept for the
+  next run under the commit, as warm-ups are.
 - A task whose key hashes a runtime probe (`inputs.runtime`, such as
   `bun --version`) runs on a worker, which answers the probe first and
   fails the task when it answers otherwise than this machine did. A path
@@ -525,9 +555,13 @@ use your own instead.
   or of files a formatter changed) is sent in parts, none of it dropped.
   An order too long for one frame (a task with thousands of deps) sends
   its deps ahead of it the same way.
+- A worker gets each dependency in full once. Later orders name it, so a
+  deep graph's orders stay small.
 - A task runs with the orchestrator's environment under the worker's
   root. `HOME`, `TMPDIR`, `USER` and the like are the worker's own, unless
-  the task's `env.define` sets them; `npm_execpath` is the workspace's
+  the task's `env.define` sets them or its `inputs.env` keys them: a keyed
+  one is the orchestrator's value, or unset where it is unset there, so
+  the worker runs on what the key saw; `npm_execpath` is the workspace's
   package manager on the worker, as core sets it on a local task.
 - A worker restores, by key, the declared outputs of every task the one
   it runs depends on, each after its own dependencies (an additive task's
@@ -538,7 +572,9 @@ use your own instead.
   leaves no file. One waits there up to 10 s; past that, with that worker
   gone or of another platform, or with its uncached upstreams on two
   workers, the upstream runs again where the dependant can go, and the
-  dependant follows it. A task whose upload no remote took after three
+  dependant follows it. One whose `exec.worker` or `exec.platforms` rules
+  out where its dependant runs refuses the run before a worker starts,
+  naming both: cache it, or run both alike. A task whose upload no remote took after three
   tries (too big, a 429, a reset connection) is its worker's fault: that
   worker takes no more tasks and the task runs on another; a second fault
   fails the run. Before a task runs, its
@@ -560,20 +596,37 @@ use your own instead.
   `--no-cache` or read-only run, a dependant of a failure under
   `--continue=always`, one that left a process running that may still
   write its outputs, one a stopped run cancelled), and one that left a tracked file under its project
-  changed on its worker (a formatter's input), which this machine never
-  sees: core withholds its own save when the key read that file, and says so.
+  changed on its worker (a formatter's input), or that found an untracked,
+  unignored file under its project there (its outputs and its dependencies'
+  aside), which this machine never sees: core withholds its own save when
+  the key read that file or its inputs declare it, and says so.
 - Under `--force`, a success is saved under its key (which keeps an entry
   it already holds, as core does) and under the run's key, which this
   machine and the dependants' workers restore: the bytes this run built,
   never the entry it bypassed.
 - A worker whose tracked files differ from the orchestrator's (another
   tree, or the same commit with a tracked file changed, such as by a
-  prepare step) is refused. Both sides read their tracked files as they
-  are, so the same change on both is the same tree.
+  prepare step) is refused, and the orchestrator says so as it happens:
+  `[vx] dte: refused worker <id>: <reason>`. Both sides read their tracked files as they
+  are on disk, a file flagged `assume-unchanged` or `skip-worktree` too
+  (one a sparse checkout left off disk is its index's), so the same change
+  on both is the same tree.
+- A worker runs the commit's bytes and modes, which are the ones the key
+  read: the run's snapshot stages each file's executable bit as on disk
+  (under `core.fileMode=false` too, as core keys it), and a worker writes
+  back as the commit holds it each file a git filter of its own checked
+  out otherwise (`text`, `eol`, `ident`, `filter` such as LFS,
+  `working-tree-encoding`, `core.autocrlf`). A task whose key hashes a
+  tracked file that is on disk other than the commit holds it (CRLF such
+  a filter wrote, an expanded ident, an LFS file's content) fails, naming
+  the file: no worker builds on those bytes.
 - A task whose key hashes a file the run's commit lacks (untracked, or
   gitignored and named outright, or inside a submodule, whose files the
   commit holds only as a gitlink) fails, naming the file: no worker has it.
   A dependency's declared output is not one: its worker restores it first.
+  A task whose project the commit lacks (its config untracked) fails,
+  naming the project, and a run whose `.vx/workspace.*` is untracked is
+  refused before a worker starts.
 - A task's `exec.timeout` counts from its start on its worker: the wait
   for a worker still booting is not its run (the executor declares
   `timeouts`).
@@ -582,11 +635,22 @@ use your own instead.
   another. A task two such workers were sent fails, naming both; one whose
   send failed does not count. With no worker of the run left
   to take it and none starting, it fails at once.
+- A task that failed and retries (its `retries`, or the one retry a
+  known-flaky task gets) runs on another worker than the attempt that
+  failed, as core asks (`ExecuteRequest.attempt`): the worker, or what
+  ran beside it, may be the flake. With no other worker of its platform
+  in the run, it runs there again rather than wait.
 - A relay that answers nothing for 10 s, every try counted, fails every task not done
   (`the relay is unreachable`); none runs here, which may be far smaller
   than the workers. What finished is saved, so a rerun resumes from it.
-  A shorter fault (a `5xx` while the host restarts the relay, a dropped
-  connection) is asked through, by the orchestrator and workers alike.
+  The footer counts each worker that had joined `lost`, with what it ran.
+  A fault (a `5xx`, a dropped or refused connection) is tried again 3
+  times, by the orchestrator and workers alike, and the third failed
+  retry ends them (`no socket in 3 dials`). The waits are random, from
+  up to 250 ms doubling to up to half a heartbeat, about 3 s at most in
+  all on the default, so a relay down or restarting is asked through
+  only when it is back within them: one down under a second usually is,
+  one down 2 s usually fails the run.
 - The relay stores nothing, so a restart forgets the run. The orchestrator
   joins again as its host and each worker joins again as itself, for two
   heartbeats (4 s on the default); tasks keep running meanwhile, and what
@@ -594,9 +658,12 @@ use your own instead.
   keeps what it runs, and one sent a task it runs already
   does not run it again, so no work repeats. One not back by then
   ends: a worker's tasks run elsewhere, an orchestrator's run fails.
-  Joining has the same 10 s in all, its socket and request together: a
+  Joining has the same 10 s in all and the same 3 retries, its waits
+  spread over the 10 s (1.25 s doubling, jittered to half: 4.4 to 8.75 s
+  in all), so a relay or network down a few seconds is still joined. A
   relay silent that long fails the run with `cannot connect to the relay
-<origin>: no answer in 10 s`.
+<origin>: no answer in 10 s`; four failed tries say why and how long,
+  as `cannot connect to the relay <origin>: ENOTFOUND, 4 dials in 9.1 s`.
 - A worker that never joins says why on its row (`failed  exited 1:
 …`); its job ending, a success too, is what says so. Once the first
   worker of a size joins, each other of that size not joined within twice
@@ -613,8 +680,8 @@ use your own instead.
 - Only `leave` ends a participant at once (2026-10-25): the
   orchestrator's at its run's end is the final call that closes the run,
   and a worker's when it is done. Either whose socket drops without it
-  dials again, 3 times within 10 s, and the relay keeps it, and its run,
-  for those 10 s; past them the run is over. Either side hearing nothing
+  dials again, 3 times as above and within 10 s, and the relay keeps it,
+  and its run, for 10 s; past either the run is over. Either side hearing nothing
   from the other for 3 heartbeats (6 s on the default) loses it, and the
   rest follows from that: a worker that said nothing for half of it (3 s)
   sends its report; the orchestrator never speaks on a timer, only orders
@@ -657,14 +724,16 @@ on its frame, in that worker's own color, by size and the order the run
 started it:
 
 ```
- ⏺︎   308ms success miss     c#build · small#1
+ ⏺︎   308ms success miss     c#build · linux.small#1
 ```
 
 An idle worker the rest of the run cannot keep busy leaves (`left`): one
 beyond the peak of the cores the remaining tasks keep busy, so a lull
 between two wide parts keeps it. One a remaining task needs for its size
 stays, and so does one a later task needs when its size's `max` is
-spent, since none could start in its place. A lost worker's tasks run again on
+spent, since none could start in its place. With that `max` spent, the
+last worker of its platform also stays while any task of that platform
+has not ended: a hit whose restore fails runs after all. A lost worker's tasks run again on
 another, and the run starts one in its place. A worker is lost when its
 socket closes, when it says nothing for 3 heartbeats (6 s), or at
 once when its adapter sees its process or job end. Workers start at the first
@@ -677,7 +746,7 @@ workspace's cache under its commit, and the next commit's run plans by it
 before any worker of that size joins.
 
 The `workers` rows, live while the run goes and again in the footer,
-give each worker its status (`starting`, `online`, `left`, `gone`, or `failed`
+give each worker its status (`starting`, `online`, `left`, `lost`, or `failed`
 with why, such as `exited 1: Cannot find package '@vzn/vx-dte'`; once the
 run is over, one still starting is `not joined`), the tasks it
 has done, failed or had aborted by a stop, and the ones it runs now; while the run goes, those that left
@@ -695,28 +764,32 @@ declares and its machine reports, green when they agree and red when
 not:
 
 ```
-  workers    small#1  online    3 done · 2 running
-            small#2  starting
+  workers    linux.small#1  online    3 done · 2 running
+            linux.small#2  starting
             local    online    1 done
 ```
 
 ```
-  workers    small#1  stopped  5 done · warm-up 0.1s
+  workers    linux.small#1  stopped  5 done · warm-up 0.1s
                      declared 2c/8G · actual 4c/16G
-            small#2  lost     1 done · warm-up 0.2s
+            linux.small#2  lost     1 done · warm-up 0.2s
                      declared 2c/8G · actual 4c/16G
             local    online   1 done
                      actual 10c/32G
 ```
 
 A run over that started none (every task a hit) says
-`workers   none started: no task needed one`.
+`workers   none started: no task needed one`; one where a task waited
+on a worker and none joined says
+`workers   none joined: a task waited on one`, or, when the run refused
+workers, `workers   none joined: 2 refused (<first reason>)`.
 
 Under each worker, and `local`, the footer then spells out what it did:
 its time online, busy and idle; its CPU peak and average in cores and
 the cores the run booked for the tasks it was running, on average (a
-booked from a task's start to its command's end); its cpu utilization (the core-time its
-tasks used over the core-time it had); its memory peak and average, when its tasks reported any; and, for a worker, the messages and
+booked from a task's start to its command's end); its cpu utilization from its first task's send to its last
+one's end, the warm-up and the wait for a first task left out: its machine's (any process's busy core-time over
+the core-time it had, so what is left is idle cores), its tasks' and its worker process's; its memory peak and average, when its tasks reported any; and, for a worker, the messages and
 bytes the run sent it and received from it. The `probe` line says when
 core's cache probe answered, how many tasks it left to run (held in no
 cache, or not answered for) and how many of them it found in none. The `asked` line says each
@@ -733,20 +806,24 @@ the worker started, any process's, as its last frame said. Where the
 rest went, the worker says in its own log as it leaves: `cpu over 61.2s:
 machine 2.80 cores · tasks 2.00 cores · this worker 0.15 cores · its other
 children 0.05 cores · most besides: Runner.Worker 0.30 cores`, the last
-from one `ps` as it starts and one as it leaves. The `total` line is the cpu utilization of every
+from one `ps` as it starts and one as it leaves. The `total` line is the same cpu utilization of every
 machine together, and the share of their history the run's tasks used:
 
 ```
-            small#1  stopped  5 done · warm-up 0.2s
+            linux.small#1  stopped  5 done · warm-up 0.2s
                      declared 4c/14G · actual 4c/14G
                      online 12.1s · busy 9.8s · idle 2.3s
-                     cpu peak 3.6 · used avg 2.4 cores · machine avg 2.9 · booked avg 3.8 · cpu utilization 61%
+                     cpu peak 3.6 · used avg 2.4 cores · machine avg 2.9 · booked avg 3.8
+                     cpu utilization machine 78% · tasks 64% · worker 2%
                      memory peak 1.2 GB · avg 640.0 MB
                      sent 6 messages · 3.1 MB, received 15 messages · 8.4 MB
             probe    at 0.4s: 5 tasks left to run, 5 known misses
             asked    1 at 0.5s for 5 tasks (5 measured), plan 12.0s
             ideal    10.8s: each task as long as it took, placed perfectly
-            total    cpu utilization 58%
+            best     2 × linux.small (4c/14G): 11.4s, the fewest of its sizes
+            more     3 × linux.small (4c/14G): 10.8s, past its sizes' max
+            any      1 × (8c/28G): 10.9s, of any cores, the least core time
+            total    cpu utilization machine 74% · tasks 60% · worker 2%
 ```
 
 `vx run --profile[=<path>]` adds the run in time to the profile it
@@ -776,6 +853,17 @@ real warm-up. That ideal end (`TaskExecutor.idealMs`) sits beside the
 real time in the run summary and the footer's `ideal` line, and
 `@vzn/vx-ci` prints it.
 
+The same replay says which workers to declare next time
+(`TaskExecutor.advice`), each from an empty run with the plan's own
+rules (the fewest that end it within its margin of the soonest): `best`
+is how many of each size; `more`, shown only when more than a size's
+`max` would end the run sooner past that margin, is how many it would
+take; `any` is one shape for each platform, of 2 to 64 cores (memory a
+core as the platform's sizes have most), the one ending as soon for the
+least core time. Raise a size's `max`, or change its `cpu` and
+`memory`, by them. They are in the footer and the run summary, and
+`@vzn/vx-ci` prints them under "Workers to declare".
+
 ## Environment
 
 What `@vzn/vx-dte` reads from the CI job it runs in:
@@ -809,7 +897,12 @@ What `@vzn/vx-dte` reads from the CI job it runs in:
 process.env.CF_ACCESS_CLIENT_ID, … }`); an unset value is left out, and
   a name the dial sets itself (`authorization`, `content-type`,
   `relay-proof`) is refused. The rest:
-  - `workers` names each `WorkerSize`, `{ cpu, memory, max?, platform? }`: its cores
+  - `workers` names each worker type, a `WorkerType` `{ machines }`, in order of
+    preference (`exec.worker` picks one). Each machine is a size the
+    adapter may start, named `<type>.<machine>` (`linux.small`) in the
+    run's output and an adapter's options, and is a `WorkerSize`,
+    `{ cpu, memory, max?, platform?, runsOn? }` (`runsOn`: the runner
+    label `vx dte init` writes for it): its cores
     and memory (bytes, or `'8GB'`, `'512MiB'`), which the run counts on
     when it starts one, until the worker reports what its machine has,
     how many of it one run may start (absent, no cap), and its machines'
@@ -817,16 +910,28 @@ process.env.CF_ACCESS_CLIENT_ID, … }`); an unset value is left out, and
     absent, planned as this machine's and not checked on join). With no adapter, the sizes' platforms are
     the ones joining workers may have. Only work counts:
     a task that missed the cache, or waits on a cached one that did, and
-    every uncached task, which runs every time; groups and hits need no worker. At each miss, finish and join the run plays
+    every uncached task, which runs every time; groups and hits need no worker. The run plays
     that work out on its workers and on N more (`src/planner.ts`), each new
     one joining after its size's warm-up: this run's first of that size,
     else an earlier run's, else any size's this run, else 20 s,
     and takes the fewest N that end within 5% (5 s at least) of the best.
+    It plays only two warm-ups and the longest task ahead; past that, the
+    rest ends no sooner than its longest chain, nor than its work spread
+    on the cores it has, and the next plan, a warm-up on, sees further.
     Sizes of different platforms come in turns, so of those N it drops
     each the plan ends as soon without, its platform's work no more than
     5 s later.
     That margin is spent once: later plans keep its deadline until new
     work is known. A task waiting on one that runs waits until it ends.
+    Then the run follows that plan: a start it wants later is asked when
+    due, and a worker idle with its planned work done goes, once every
+    task planned on it has started. It plays again
+    only when reality leaves the plan: new work, work that leaves without
+    running, a worker idle at its planned end with a task planned on it not
+    started, a worker that joins, leaves or warms up off plan, a task past
+    its time or ending sooner, one of no known time ending, a task starting
+    with its time, CPU or memory more than 5% off (1 s, 0.05 cores, 64 MiB
+    at least), or its window moving on.
     What is left, running tasks too, takes as many times its history as
     the run's finished tasks took theirs (once they had 20 s of it; never
     less): a task past its forecast would otherwise be planned to end now,
@@ -876,7 +981,7 @@ HEAD^`), and every task after one (`src/forecast.ts`): a lockfile or
   - `adapter` is the `DteAdapter` that starts workers, of the sizes in
     `workers`: at least one with `max` above 0, or `dte()` is refused.
     Absent, the run starts none and uses the workers that join `relay`.
-  - `relay` is the relay's URL, http(s); absent, the adapter's own.
+  - `relay` is the relay's base URL, http(s), without `/v1`, `?query` or `#fragment`; absent, the adapter's own.
   - `token` answers the relay's bearer token (default `VX_DTE_TOKEN`). It
     is asked again a minute before the token's `exp`, when it has one.
   - `unmeasured`, `{ cpu, memory }` (default 2 cores, `'4GB'`), is what a
@@ -907,7 +1012,7 @@ HEAD^`), and every task after one (`src/forecast.ts`): a lockfile or
 - `DteAdapter` is `{ spawn(worker: WorkerSpawn), relay?(), close?(), cancel?(ids), init?(setup: DteSetup), runId?(), adopt?(worker), report?(warn), keyless?, workerRuns?() }`; `init` gets a `DteSetup` (workspace root, its directory in the repository, relay, sizes, the `PackageManager` read from the lockfile, the tasks asked for) and returns a `DteInit`: the CI files `vx dte init` writes and the steps it prints; `report` hands it the run's warning channel as the run starts, where `github()` says a status poll or a cancel the CI API refused, by status and body; `adopt` hands each worker the CI started before the run to `worker(id, size)`, which counts it and returns its spawn; `cancel` stops workers the run no longer needs that have not joined, and may answer with those it left running, which the run takes (with `late`, workers given up on joining, stopped whatever their job holds); `runId` names the run, in the adapter's own CI, when `VX_DTE_RUN` is unset; `workerId` names a worker in a job its CI started for several, when `VX_DTE_WORKER` is unset; `keyless` workers prove themselves by GitHub OIDC, and `workerRuns` names the workflow runs whose jobs alone may join as them (`undefined`: any job of the repository).
   `WorkerSpawn` is `{ run, relay, size, max, cpu, memory, index, id, workspaceRoot, commit, cacheDir?, env }`,
   with `memory` in bytes and `max` its size's (`Infinity` uncapped),
-  where `id` is the worker's name (`small#2`, numbered within its size), `commit` the
+  where `id` is the worker's name (`linux.small#2`, numbered within its size), `commit` the
   tracked files as the run saw them at its start (uncommitted changes included), whose
   tree a worker must check out, `cacheDir` the run's cache dir (absolute) when the
   workspace names one, for workers on this machine to save where the run reads, and
@@ -916,10 +1021,9 @@ HEAD^`), and every task after one (`src/forecast.ts`): a lockfile or
   of its own on loopback. `DockerOptions` is `{ image, prepare? }`.
 - `github(options?: GithubOptions)` dispatches workers as matrix jobs of
   one workflow, one dispatch per size and demand (at most 256 workers,
-  a matrix's limit). `GithubOptions` is `{ workflow?, runsOn?, env? }`:
+  a matrix's limit). `GithubOptions` is `{ workflow?, env? }`:
   `workflow` defaults to `vx-worker.yml`, a file name in
-  `.github/workflows` other than `ci.yml`, the run's own; `runsOn` is the runner label
-  of each size, which `vx dte init` writes; `env` is variables every
+  `.github/workflows` other than `ci.yml`, the run's own; `env` is variables every
   worker gets (one-line strings, no secret-named one: the worker job's
   log shows them), sent as the
   dispatch's `env` input only when set, which `vx dte init`'s workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-dte",
-  "version": "0.0.651",
+  "version": "0.0.653",
   "license": "MIT",
   "description": "Distributed task execution for vx: one run spread over workers your own CI spawns, joined through a relay.",
   "keywords": [
@@ -29,10 +29,10 @@
     "bun": ">=1.4.4"
   },
   "dependencies": {
-    "@vzn/vx-dte-server": "0.0.651"
+    "@vzn/vx-dte-server": "0.0.653"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.651"
+    "@vzn/vx": "^0.0.653"
   },
   "repository": {
     "type": "git",