From 6a2c09b1859542b25e3679de21f9c7f3957ef4c1 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:15:09 +0000 Subject: [PATCH 1/3] fork fleet: desk pool docs, a neutral example, the fork's `pc` pool on the desk link (D12) The fork's own `pc` pool now launches through the desk link (fork-fleet-desk.py launch pc) instead of the never-made launch-pc wrapper. The runbook gets a made-up desk pool entry any project can copy, and the desk kit's README a five-step path from nothing to a working pool. Co-Authored-By: Claude Opus 5.5 --- .github/fork-fleet.json | 4 +-- .github/fork-fleet.md | 29 +++++++++++++++++--- .github/scripts/fork-fleet-desk-key.test.py | 3 ++- FORK_CHANGES.md | 30 ++++++++++----------- fork-kit/desk/README.md | 10 +++++++ 5 files changed, 54 insertions(+), 22 deletions(-) diff --git a/.github/fork-fleet.json b/.github/fork-fleet.json index af0b2cb0a1265..8507cefb03588 100644 --- a/.github/fork-fleet.json +++ b/.github/fork-fleet.json @@ -26,12 +26,12 @@ }, "pools": [ { - "_doc": "The owner's PC: its dispatcher runs on the always-on host and starts runners on the PC over ssh.", + "_doc": "The owner's PC, a desk pool: its desk agent dials out to the always-on host, whose dispatcher for this pool starts runners on the PC through that link (fork-fleet.md, The desk link).", "name": "pc", "label": "fleet-pc-t3code", "slots": 1, "beacon": "FLEET_BEACON_PC", - "launch": ["/opt/fork-fleet/launch-pc"], + "launch": ["python3", "-I", "/opt/fork-fleet/fork-fleet-desk.py", "launch", "pc"], "waits": false }, { diff --git a/.github/fork-fleet.md b/.github/fork-fleet.md index ae52011a38f6b..b0fa77339aaef 100644 --- a/.github/fork-fleet.md +++ b/.github/fork-fleet.md @@ -572,10 +572,13 @@ Do not name the dispatcher's unit `fork-fleet-*`: that prefix is for runner units. Runner units are separate transient units, so restarting the dispatcher leaves running jobs alone. -**The `pc` pool** stays off until `/opt/fork-fleet/launch-pc` exists: a wrapper -that runs `fork-fleet-launch.sh` on the PC over ssh. Run the dispatcher with -`--pool vm` until then. Without its dispatcher, `pc` has no heartbeat, and -`route` never counts it. Whether and how the PC joins is an owner decision. +**The `pc` pool** is a desk pool: the owner's PC, through the desk link below. +It stays off until its own dispatcher unit runs (`t3code-fleet-dispatcher-pc`, +"One dispatcher per desk pool") and the PC's desk key is added: without its +dispatcher, `pc` has no heartbeat and `route` never counts it. While the PC +sleeps or is off, `launch` exits 3 at once and its jobs go elsewhere. A host +that still has the older `/opt/fork-fleet/launch-pc` wrapper may delete it: +nothing reads it. ### The desk link (a desktop pool) @@ -600,6 +603,24 @@ systemd-tmpfiles --create /etc/tmpfiles.d/fork-fleet-desk.conf sudo -u fleet-desk -H /usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk-key.py --config /opt/fork-fleet/fork-fleet.json add POOL < desk-POOL.pub ``` +A desk pool's entry in a project's fleet config (made-up names; `seeds` is +optional, see "Seeds" below): + +```json +{ + "name": "desktop", + "label": "fleet-desktop-example", + "slots": 2, + "beacon": "FLEET_BEACON_DESKTOP", + "launch": ["python3", "-I", "/opt/fork-fleet/fork-fleet-desk.py", "launch", "desktop"], + "waits": false +} +``` + +`waits: false`: a desktop may sleep, so a job never waits for it. `slots` at +most the desktop's own `slots` (its machine file). The pool's name is the one in +the desktop's machine file and in the key line. + The line it writes (and the only kind of line that user's key file holds) is `restrict,command="/usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk.py serve POOL" ssh-ed25519 AAAA... fork-fleet-desk:POOL` in `~fleet-desk/.ssh/authorized_keys`. The pool's launch command in the diff --git a/.github/scripts/fork-fleet-desk-key.test.py b/.github/scripts/fork-fleet-desk-key.test.py index 9ee61a0527b2a..d446fea6254c2 100644 --- a/.github/scripts/fork-fleet-desk-key.test.py +++ b/.github/scripts/fork-fleet-desk-key.test.py @@ -54,7 +54,8 @@ def setUp(self): self.home = os.path.join(self.tmp, 'home') os.mkdir(self.home) cfg = dk.ff.load() - cfg['pools'] = cfg['pools'] + [desk('desk'), desk('desk2')] + # only this test's desk pools: the project's own (its fleet config may have some) are left out + cfg['pools'] = [p for p in cfg['pools'] if p['name'] not in dk.desk_pools(cfg)] + [desk('desk'), desk('desk2')] self.config = os.path.join(self.tmp, 'fleet.json') with open(self.config, 'w') as f: json.dump(cfg, f) diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index 83ae5032ac685..8c89854bb8065 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -35,21 +35,21 @@ is missing here or a setting named here does not exist. These change only how this repository is built, tested and released, not the app. -| Change | Why | Setting | Default | PR | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Fork release workflow: builds `v.fork.` with the Linux and Windows CLI archives and unsigned desktop apps. | The fork needs its own releases to install and update from. | none | run by hand or by fork-follow | [#2](https://github.com/scuttletoby/t3code/pull/2) | -| fork-follow: once a day, rebase the fork onto upstream's newest tag, test, and release only when green; on trouble, open one issue. | Stay close to upstream without manual work. | repository variable `FORK_FOLLOW_CHANNEL` | `nightly` | [#4](https://github.com/scuttletoby/t3code/pull/4), [#22](https://github.com/scuttletoby/t3code/pull/22), [#66](https://github.com/scuttletoby/t3code/pull/66) | -| Fork tests: upstream's test jobs, run on GitHub-hosted runners or on the repository's own machines chosen per run. | Fast CI that does not need upstream's runner labels. | repository variable `CI_RUNNERS` | `auto` | [#6](https://github.com/scuttletoby/t3code/pull/6), [#8](https://github.com/scuttletoby/t3code/pull/8), [#13](https://github.com/scuttletoby/t3code/pull/13) | -| Fleet runners: one-job runners started on demand on the repository's own machines, each behind walls, plus a link from a desktop machine. | Use spare machines for CI without letting a job reach the host. | repository variable `CI_RUNNERS` | `auto` | [#53](https://github.com/scuttletoby/t3code/pull/53), [#74](https://github.com/scuttletoby/t3code/pull/74), [#191](https://github.com/scuttletoby/t3code/pull/191), [#192](https://github.com/scuttletoby/t3code/pull/192), [#194](https://github.com/scuttletoby/t3code/pull/194), [#195](https://github.com/scuttletoby/t3code/pull/195), [#196](https://github.com/scuttletoby/t3code/pull/196), [#197](https://github.com/scuttletoby/t3code/pull/197), [#198](https://github.com/scuttletoby/t3code/pull/198), [#205](https://github.com/scuttletoby/t3code/pull/205), [#208](https://github.com/scuttletoby/t3code/pull/208) | -| Checks that refuse database schema and migration changes, fork changes to some upstream files, and fork lines outside the pinned seams. | Keep the fork thin, so upstream syncs stay easy and a database never needs a fork step. | none | always | [#3](https://github.com/scuttletoby/t3code/pull/3), [#97](https://github.com/scuttletoby/t3code/pull/97), [#185](https://github.com/scuttletoby/t3code/pull/185) | -| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | -| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | -| Secret scan on every push and pull request. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212) | -| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141) | -| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | -| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | -| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183) | -| Design notes: host tools (agents on a person's own computer). | Design for review; no code yet. | none | - | [#26](https://github.com/scuttletoby/t3code/pull/26) | +| Change | Why | Setting | Default | PR | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fork release workflow: builds `v.fork.` with the Linux and Windows CLI archives and unsigned desktop apps. | The fork needs its own releases to install and update from. | none | run by hand or by fork-follow | [#2](https://github.com/scuttletoby/t3code/pull/2) | +| fork-follow: once a day, rebase the fork onto upstream's newest tag, test, and release only when green; on trouble, open one issue. | Stay close to upstream without manual work. | repository variable `FORK_FOLLOW_CHANNEL` | `nightly` | [#4](https://github.com/scuttletoby/t3code/pull/4), [#22](https://github.com/scuttletoby/t3code/pull/22), [#66](https://github.com/scuttletoby/t3code/pull/66) | +| Fork tests: upstream's test jobs, run on GitHub-hosted runners or on the repository's own machines chosen per run. | Fast CI that does not need upstream's runner labels. | repository variable `CI_RUNNERS` | `auto` | [#6](https://github.com/scuttletoby/t3code/pull/6), [#8](https://github.com/scuttletoby/t3code/pull/8), [#13](https://github.com/scuttletoby/t3code/pull/13) | +| Fleet runners: one-job runners started on demand on the repository's own machines, each behind walls, plus a link from a desktop machine. | Use spare machines for CI without letting a job reach the host. | repository variable `CI_RUNNERS` | `auto` | [#53](https://github.com/scuttletoby/t3code/pull/53), [#74](https://github.com/scuttletoby/t3code/pull/74), [#191](https://github.com/scuttletoby/t3code/pull/191), [#192](https://github.com/scuttletoby/t3code/pull/192), [#194](https://github.com/scuttletoby/t3code/pull/194), [#195](https://github.com/scuttletoby/t3code/pull/195), [#196](https://github.com/scuttletoby/t3code/pull/196), [#197](https://github.com/scuttletoby/t3code/pull/197), [#198](https://github.com/scuttletoby/t3code/pull/198), [#205](https://github.com/scuttletoby/t3code/pull/205), [#208](https://github.com/scuttletoby/t3code/pull/208), [#229](https://github.com/scuttletoby/t3code/pull/229), [#230](https://github.com/scuttletoby/t3code/pull/230), [#236](https://github.com/scuttletoby/t3code/pull/236), [#237](https://github.com/scuttletoby/t3code/pull/237), [#238](https://github.com/scuttletoby/t3code/pull/238) | +| Checks that refuse database schema and migration changes, fork changes to some upstream files, and fork lines outside the pinned seams. | Keep the fork thin, so upstream syncs stay easy and a database never needs a fork step. | none | always | [#3](https://github.com/scuttletoby/t3code/pull/3), [#97](https://github.com/scuttletoby/t3code/pull/97), [#185](https://github.com/scuttletoby/t3code/pull/185) | +| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | +| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | +| Secret scan on every push and pull request. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212) | +| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141) | +| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | +| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | +| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far), `desk` (a desktop's side of a fleet desk pool). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183), [#225](https://github.com/scuttletoby/t3code/pull/225) | +| Design notes: host tools (agents on a person's own computer). | Design for review; no code yet. | none | - | [#26](https://github.com/scuttletoby/t3code/pull/26) | ## Adding a line diff --git a/fork-kit/desk/README.md b/fork-kit/desk/README.md index 57f2268d951e0..18b4ee7de166f 100644 --- a/fork-kit/desk/README.md +++ b/fork-kit/desk/README.md @@ -5,6 +5,16 @@ always-on host over ssh, and the dispatcher there starts one-job runners on this the fleet runbook ([.github/fork-fleet.md](../../.github/fork-fleet.md), "The desktop's side") lists by hand, done by one installer, with a PASS/FAIL check and an uninstall. +## From nothing to a working pool + +1. The project: a desk pool entry in its fleet config ([fork-fleet.md](../../.github/fork-fleet.md), "The desk + link", has a made-up one), released to its protected release branch. +2. The always-on host, once: the desk-link user and its socket folder, and one dispatcher unit for the pool (the + same section). +3. The desktop: the machine file below, then the install (on Windows: [the starter](#windows-wsl2)). +4. The always-on host: add the key install printed, with `fork-fleet-desk-key.py add POOL`. +5. The desktop: `desk-install check` says ALL PASS; the dispatcher's log says the pool's link is up. + ## The machine file The facts of this machine go in the `desk` section of `/etc/fork-kit/machine.json` (root-owned; see From 6678d64742fa6bc380d2425ae04aa8b178383aab Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 15 Nov 2026 20:52:44 +0000 Subject: [PATCH 2/3] fork fleet: desk docs fix round 1 (D12) Host step 3 installs the key tool and the README's step 2 names it; the example entry sits after the key line's paragraph; a host with an old pc dispatcher stops it and lets its runners finish first; the desk-key test drops the release's pc pool by name; the refresh test lists the desk link's files, not launch-pc. Co-Authored-By: Claude Opus 5.5 --- .github/fork-fleet.md | 31 +++++++++++---------- .github/scripts/fork-fleet-desk-key.test.py | 8 ++++-- .github/scripts/fork-fleet-refresh.test.py | 6 ++-- fork-kit/desk/README.md | 5 ++-- 4 files changed, 29 insertions(+), 21 deletions(-) diff --git a/.github/fork-fleet.md b/.github/fork-fleet.md index b5b1f0925c8f5..c6497b9b12dbd 100644 --- a/.github/fork-fleet.md +++ b/.github/fork-fleet.md @@ -449,6 +449,7 @@ done scripts/fork-fleet-hook.sh:hook.sh:755 scripts/fork-fleet-launch.sh:fork-fleet-launch.sh:755 scripts/fork-fleet-desk.py:fork-fleet-desk.py:644 scripts/fork-fleet-desk-wire.py:fork-fleet-desk-wire.py:644 scripts/fork-fleet-desk-seed.py:fork-fleet-desk-seed.py:644 + scripts/fork-fleet-desk-key.py:fork-fleet-desk-key.py:644 scripts/fork-fleet-refresh.service:fork-fleet-refresh.service:644 scripts/fork-fleet-refresh.timer:fork-fleet-refresh.timer:644 scripts/fork-fleet-job-paths.txt:fork-fleet-job-paths.txt:644" @@ -577,8 +578,10 @@ It stays off until its own dispatcher unit runs (`t3code-fleet-dispatcher-pc`, "One dispatcher per desk pool") and the PC's desk key is added: without its dispatcher, `pc` has no heartbeat and `route` never counts it. While the PC sleeps or is off, `launch` exits 3 at once and its jobs go elsewhere. A host -that still has the older `/opt/fork-fleet/launch-pc` wrapper may delete it: -nothing reads it. +that ran an older `pc` dispatcher on `/opt/fork-fleet/launch-pc` first stops +that dispatcher and lets its runners finish (this config's cleanup skips a pool +that is down, so it never stops or prunes them); then it may delete the +wrapper: nothing reads it. ### The desk link (a desktop pool) @@ -588,7 +591,7 @@ out to the always-on host over ssh, as a dedicated unprivileged user (default pool. The pool's dispatcher on the always-on host sends the launcher's verbs through that one session (`fork-fleet-desk.py`, its wire format `fork-fleet-desk-wire.py`). Once per always-on host, as root (step 3 installs -both files): +these files and the key tool `fork-fleet-desk-key.py`): ```sh # The desk-link user: a real shell (sshd runs the forced command through it, so nologin would close the link) and no @@ -599,10 +602,20 @@ usermod -p '*' fleet-desk echo 'd /run/fork-fleet-desk 0710 fleet-desk fleet-desk -' > /etc/tmpfiles.d/fork-fleet-desk.conf systemd-tmpfiles --create /etc/tmpfiles.d/fork-fleet-desk.conf # Per desk pool: the desktop's public key, as the desk-link user, with the key tool fork-fleet-desk-key.py -# (row D4 of the desktop-pool design; install it beside the others). +# (step 3 installs it). sudo -u fleet-desk -H /usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk-key.py --config /opt/fork-fleet/fork-fleet.json add POOL < desk-POOL.pub ``` +The line it writes (and the only kind of line that user's key file holds) is +`restrict,command="/usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk.py serve POOL" ssh-ed25519 AAAA... fork-fleet-desk:POOL` +in `~fleet-desk/.ssh/authorized_keys`. The pool's launch command in the +project's fleet config is +`"launch": ["python3", "-I", "/opt/fork-fleet/fork-fleet-desk.py", "launch", "POOL"]`. +Another user name: use it in all three places above, and give the dispatcher +`Environment=FORK_FLEET_DESK_USER=NAME`. Another socket group: the group in the +tmpfiles line; the desk-link user must be in it, and so must the dispatcher's +user when that is not root. + A desk pool's entry in a project's fleet config (made-up names; `seeds` is optional, see "Seeds" below): @@ -621,16 +634,6 @@ optional, see "Seeds" below): most the desktop's own `slots` (its machine file). The pool's name is the one in the desktop's machine file and in the key line. -The line it writes (and the only kind of line that user's key file holds) is -`restrict,command="/usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk.py serve POOL" ssh-ed25519 AAAA... fork-fleet-desk:POOL` -in `~fleet-desk/.ssh/authorized_keys`. The pool's launch command in the -project's fleet config is -`"launch": ["python3", "-I", "/opt/fork-fleet/fork-fleet-desk.py", "launch", "POOL"]`. -Another user name: use it in all three places above, and give the dispatcher -`Environment=FORK_FLEET_DESK_USER=NAME`. Another socket group: the group in the -tmpfiles line; the desk-link user must be in it, and so must the dispatcher's -user when that is not root. - `serve` keeps one session per pool (a lock), listens on a 0660 socket in `/run/fork-fleet-desk` (it lets in only root, its own user and the socket group), and pings the agent; `launch` fails at once (exit 3) when no session is diff --git a/.github/scripts/fork-fleet-desk-key.test.py b/.github/scripts/fork-fleet-desk-key.test.py index d446fea6254c2..2ef0720d26950 100644 --- a/.github/scripts/fork-fleet-desk-key.test.py +++ b/.github/scripts/fork-fleet-desk-key.test.py @@ -54,8 +54,10 @@ def setUp(self): self.home = os.path.join(self.tmp, 'home') os.mkdir(self.home) cfg = dk.ff.load() - # only this test's desk pools: the project's own (its fleet config may have some) are left out - cfg['pools'] = [p for p in cfg['pools'] if p['name'] not in dk.desk_pools(cfg)] + [desk('desk'), desk('desk2')] + # only this test's desk pools: the release's own desk pool (pc) is left out by name, never by the function + # under test; vm stays, so a non-desk pool is always there to be refused + cfg['pools'] = [p for p in cfg['pools'] if p['name'] != 'pc'] + [desk('desk'), desk('desk2')] + assert 'vm' in [p['name'] for p in cfg['pools']] self.config = os.path.join(self.tmp, 'fleet.json') with open(self.config, 'w') as f: json.dump(cfg, f) @@ -152,7 +154,7 @@ def test_refuses_anything_but_one_valid_ed25519_public_key(self): self.assertIn('private key', self.run_tool('add', 'desk', stdin=PRIVATE)[1]) def test_refuses_a_pool_it_does_not_know(self): - for pool in ('nope', 'vm', 'pc', '../desk', 'desk "x"'): + for pool in ('nope', 'vm', '../desk', 'desk "x"'): with self.subTest(pool): code, out = self.run_tool('add', pool, stdin=PUB1) self.assertEqual(code, REFUSED, out) diff --git a/.github/scripts/fork-fleet-refresh.test.py b/.github/scripts/fork-fleet-refresh.test.py index ea6fe0b0ac855..caa1fcc7912be 100755 --- a/.github/scripts/fork-fleet-refresh.test.py +++ b/.github/scripts/fork-fleet-refresh.test.py @@ -967,12 +967,14 @@ def test_the_service_cannot_write_run_dir(self): def test_the_service_writes_the_templates_own_folder_only(self): """The writable folder is the default template's own folder, and none of the files root runs (the launcher, - the dispatcher, its trust config, the job hook, the pc wrapper) is in it or under it.""" + the dispatcher, its trust config, the job hook, the desk link and its wire format, seed and key tools) is in it + or under it.""" service = unit('fork-fleet-refresh.service')['Service'] rw = [p.lstrip('-') for p in service['ReadWritePaths'].split()] self.assertEqual(rw, [os.path.dirname(default_template())]) root_dir = os.path.dirname(service['ExecStart'].split()[0]) - for f in ('fork-fleet-launch.sh', 'fork-fleet.py', 'fork-fleet.json', 'hook.sh', 'launch-pc', 'SOURCE'): + for f in ('fork-fleet-launch.sh', 'fork-fleet.py', 'fork-fleet.json', 'hook.sh', 'fork-fleet-desk.py', + 'fork-fleet-desk-wire.py', 'fork-fleet-desk-seed.py', 'fork-fleet-desk-key.py', 'SOURCE'): path = f'{root_dir}/{f}' self.assertFalse(any(path == w or path.startswith(w.rstrip('/') + '/') for w in rw), path) self.assertNotIn('AF_UNIX', service['RestrictAddressFamilies'].split()) diff --git a/fork-kit/desk/README.md b/fork-kit/desk/README.md index ae882da11f79e..e2d83beaf5f2f 100644 --- a/fork-kit/desk/README.md +++ b/fork-kit/desk/README.md @@ -9,8 +9,9 @@ done by one installer, with a PASS/FAIL check and an uninstall. 1. The project: a desk pool entry in its fleet config ([fork-fleet.md](../../.github/fork-fleet.md), "The desk link", has a made-up one), released to its protected release branch. -2. The always-on host, once: the desk-link user and its socket folder, and one dispatcher unit for the pool (the - same section). +2. The always-on host, once: host step 3 of the runbook ("The fleet files") again, from a main commit that has the + pool entry (it installs the desk link, the seed tool and the key tool); then the desk-link user and its socket + folder, and one dispatcher unit for the pool ("The desk link"). 3. The desktop: the machine file below, then the install (on Windows: [the starter](#windows-wsl2)). 4. The always-on host: add the key install printed, with `fork-fleet-desk-key.py add POOL`. 5. The desktop: `desk-install check` says ALL PASS; the dispatcher's log says the pool's link is up. From dcd20e226c65dde414d07149465640b324a4d623 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:06:57 +0000 Subject: [PATCH 3/3] fork fleet docs round 2: the pc pool is a desk pool (test), real log lines, another project's base (D12) - desk-key test: the release's pc pool is a desk pool (a launch typo shows in CI, not on the host) - desk README step 5: no "link is up" line; quote the real lines (runner started, pool answers again) - host step 3 and README step 2: another project points base at its own repository - README step 4: "the key the install printed" Co-Authored-By: Claude Opus 5.5 --- .github/fork-fleet.md | 3 ++- .github/scripts/fork-fleet-desk-key.test.py | 3 +++ fork-kit/desk/README.md | 11 +++++++---- 3 files changed, 12 insertions(+), 5 deletions(-) diff --git a/.github/fork-fleet.md b/.github/fork-fleet.md index cf340bae87d75..80ee86a6ff5e1 100644 --- a/.github/fork-fleet.md +++ b/.github/fork-fleet.md @@ -438,7 +438,8 @@ done # that folder. /opt and /var/lib must be on one filesystem: each copy hard-links the template (the launcher checks it). # 3. The fleet files, from one pinned main commit. All of them are fetched first and installed only when each came; -# SOURCE is written last, so it never names a commit whose files are not all in place. +# SOURCE is written last, so it never names a commit whose files are not all in place. Another project that +# carries these files: point `base` below at that project's repository and use a commit of its main. ( set -euo pipefail sha=FULL_MAIN_SHA diff --git a/.github/scripts/fork-fleet-desk-key.test.py b/.github/scripts/fork-fleet-desk-key.test.py index 2ef0720d26950..df41a5f73bb0a 100644 --- a/.github/scripts/fork-fleet-desk-key.test.py +++ b/.github/scripts/fork-fleet-desk-key.test.py @@ -91,6 +91,9 @@ def snap(self): st = os.lstat(self.keys) return self.content(), st.st_ino, st.st_mtime_ns, st.st_mode + def test_the_releases_pc_pool_is_a_desk_pool(self): + self.assertEqual(dk.desk_pools(dk.ff.load()), ['pc']) # a typo in its launch would only show on the host + def test_add_to_empty_home_then_again_then_remove(self): self.assertEqual(self.run_tool('add', 'desk', stdin=PUB1)[0], 0) line = 'restrict,command="/usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk.py serve desk" ' \ diff --git a/fork-kit/desk/README.md b/fork-kit/desk/README.md index 09f7db0f8def5..475441f5fc1ba 100644 --- a/fork-kit/desk/README.md +++ b/fork-kit/desk/README.md @@ -9,12 +9,15 @@ done by one installer, with a PASS/FAIL check and an uninstall. 1. The project: a desk pool entry in its fleet config ([fork-fleet.md](../../.github/fork-fleet.md), "The desk link", has a made-up one), released to its protected release branch. -2. The always-on host, once: host step 3 of the runbook ("The fleet files") again, from a main commit that has the - pool entry (it installs the desk link, the seed tool and the key tool); then the desk-link user and its socket +2. The always-on host, once: host step 3 of the runbook ("The fleet files") again, from a main commit of the + project's repository that has the pool entry (another project points that step's `base` at its own repository; + it installs the desk link, the seed tool and the key tool); then the desk-link user and its socket folder, and one dispatcher unit for the pool ("The desk link"). 3. The desktop: the machine file below, then the install (on Windows: [the starter](#windows-wsl2)). -4. The always-on host: add the key install printed, with `fork-fleet-desk-key.py add POOL`. -5. The desktop: `desk-install check` says ALL PASS; the dispatcher's log says the pool's link is up. +4. The always-on host: add the key the install printed, with `fork-fleet-desk-key.py add POOL`. +5. The desktop: `desk-install check` says ALL PASS. The dispatcher has no "link is up" line: the pool works + when its first job starts a runner on this machine (the dispatcher logs `RUNNER: started for JOB, attempt N`). + A pool that was down logs `fork-fleet: pool POOL answers again, after N passes left alone` when it comes back. ## The machine file