[scuttletoby]

Row D12 of the desktop pool plan, the last one: the docs that join D1 to D11 into one path from nothing to a working desk pool, a made-up example entry, and the fork's own pc pool moved onto the desk link. Stacked on #237 (D11b).

Why

The pieces are all there now (link, walls, agent, setup pack, Windows starter, free contract, seeds). What was missing:

• a page that says in what order to use them
• an example a project can copy
• the fork's own pc pool using them

Until now, the pc pool's launch pointed at a hand-made /opt/fork-fleet/launch-pc wrapper that runs commands over plain ssh. That wrapper was never part of the fork.

• .github/fork-fleet.json: the pc pool's launch is now python3 -I /opt/fork-fleet/fork-fleet-desk.py launch pc, the same as any desk pool. Its _doc says so.
• .github/fork-fleet.md:
  • The pc pool paragraph now says it is a desk pool, what turns it on (its dispatcher unit and the PC's desk key), and what happens while the PC sleeps (launch exits 3 at once, and its jobs go elsewhere).
  • A host that ran an old pc dispatcher on the wrapper first stops it and lets its runners finish (this config's
    cleanup skips a pool that is down, so it would never stop them); then it may delete the wrapper.
  • Host step 3 installs the key tool fork-fleet-desk-key.py with the other desk files.
  • A made-up desk pool entry, with what waits: false and slots mean for a desktop.
• fork-kit/desk/README.md: "From nothing to a working pool" in five steps (project config, host once: host step 3
  then the desk link, desktop install, add the key, check).

What happens when this runs again, stops half-way, or meets existing, old or empty state?

Case	What happens
Runs again	Config and docs only. A re-released config with the same entry changes nothing on any machine.
Stops half-way	Nothing here runs. A desk pool set up only partly (no dispatcher unit, or no key yet) has no heartbeat, so route never counts it and no job waits for it.
Existing / old state	Once a host's dispatcher for pc runs with the new config, it calls the desk link instead of the old launch-pc wrapper. The wrapper is then unused; the docs say to stop the old pc dispatcher and let its runners finish first, then delete it. Until the PC's desk agent is installed and its key added, launch exits 3 and jobs go to other pools, the same as when the PC is off.
Empty state	A fleet with no desk pool is unchanged. The pc pool with no dispatcher stays off, as before.

General vs project

• General: the five steps, the example entry (made-up names desktop and fleet-desktop-example) and the paragraph on waits/slots.
• Project: the one-line change to the fork's own pc pool entry in .github/fork-fleet.json, which is this repository's own fleet config. No personal names, addresses or machine ids are in it.

Upstream fit

Only fork-only files (.github/fork-fleet.*, fork-kit/desk/README.md) change. Nothing in upstream T3 changes.

It also lists the stack in FORK_CHANGES.md (new on main since #223): desk in the host kits row with #225, and
#229, #230, #236, #237 and #238 in the fleet runners row.

Tests

No new test file. The changed config is checked by the existing tests:

• .github/scripts/fork-fleet.test.py loads .github/fork-fleet.json, and check_config finds no problems.
• fork-fleet-desk-seed.test.py and fork-fleet-desk-key.test.py read the pool list from it.

Local run (the whole stack merged in):

• .github/scripts/fork-fleet-desk-key.test.py: 20 OK
• .github/scripts/fork-fleet-refresh.test.py: 43 OK (1 skipped)
• .github/scripts/fork-fleet-desk-seed.test.py: 30 OK
• .github/scripts/fork-fleet-desk.test.py: 42 OK
• .github/scripts/fork-fleet-desk-agent.test.py: 31 OK
• .github/scripts/fork-fleet-walls-wsl2.test.py: 15 OK
• fork-kit/desk/tests/install.test.py: 28 OK
• fork-kit/desk/tests/windows.test.py: 11 OK (1 skipped: no pwsh here)
• fork-kit/common/tests/free_contract.test.py: 13 OK
• fork-kit/common/tests/machine_file.test.py: 17 OK

Round 1: the desk-key test drops the release's own desk pool by name (pc), not with the function under test, and
asserts vm stays; fork-fleet-refresh.test.py's list of root-run files names the desk link's files instead of
launch-pc.

Red-checks

None: config and docs only, with no new rule to break.

🤖 Generated with Claude Code

[scuttletoby]

Review round 1 at 6a2c09b (lens238): SAFE WITH NITS. Merging the pc switch before the PC has the desk kit is safe: the host's only dispatcher unit serves vm (.github/fork-fleet.md:505), and an early pc dispatcher fails closed at every half-set-up stage (no socket folder or socket: exit 3; desk script missing: exit 2; Host._must raises, the pool is left alone with heartbeat 0, vm carries on). Fix round to follow with the rest of the stack.

1. Docs gap, nothing installs the key tool: fork-kit/desk/README.md:15 step 4 runs fork-fleet-desk-key.py add POOL, but host step 3's file list (.github/fork-fleet.md:449-452) installs fork-fleet-desk.py, -wire, -seed, not -key. Following steps 1-5 exactly fails at step 4. Add the key tool to step 3's list and name host step 3 in README step 2 (re-run it from a commit that has the pool entry).
2. Docs order: the new example and the waits/slots paragraph sit between the key tool's code block and "The line it writes…" (fork-fleet.md:606-625), so "it" now reads as the example; the launch command appears twice within ~10 lines. Move the example below "The pool's launch command … is …".
3. Old wrapper state (low): a host that ran a pc dispatcher on launch-pc with live runners, then installs this config: the pool is down every pass and leftover cleanup skips down pools, so those runners are never stopped or pruned. Add one clause before "may delete it" (:579): stop the old pc dispatcher and let its runners finish first.
4. Test nit: fork-fleet-desk-key.test.py:58 drops desk pools using dk.desk_pools(cfg), the function under test; filter by name 'pc' or assert vm stays. The pc subtest now duplicates nope.
5. Stale list outside this diff: fork-fleet-refresh.test.py:975 still names launch-pc as a root-run file and not fork-fleet-desk.py.

Checked fine: the example entry is neutral; FORK_CHANGES.md rows match the stack; the pc launch line matches desk_pools detection and the runbook. Tests: desk-key 20, desk-seed 20, desk 42 OK.

[scuttletoby]

Fix round 1 (commit 6678d64; D11b's round 1 merged in at 6bd6f2e and e7090ff; head e7090ff). Tests: desk-key 20 OK, refresh 43 OK (1 skipped), desk-seed 30 OK, desk 42 OK, desk-agent 31 OK, walls-wsl2 15 OK, install 28 OK, windows 11 OK (1 skipped, no pwsh), free_contract 13 OK, machine_file 17 OK.

1. Nothing installs the key tool: fixed (6678d64). Host step 3's file list installs fork-fleet-desk-key.py; the desk-link section and README step 2 name host step 3.
2. Docs order: fixed (6678d64). The example entry and its waits/slots paragraph now come after "The pool's launch command … is …".
3. Old pc wrapper state: fixed (6678d64). The clause now says to stop the old pc dispatcher and let its runners finish before deleting the wrapper.
4. desk-key test: fixed (6678d64). The test drops the release's pool by name (pc) and asserts vm stays; the duplicate pc subtest is gone.
5. Stale list: fixed (6678d64). fork-fleet-refresh.test.py lists the desk link, wire, seed and key files instead of launch-pc.

The docs follow the fixed stack: per-pool seed path, the desktop's own limits, uninstall and drop-ins (merged from the lower branches).

PR body updated. Still draft.

[scuttletoby]

Re-check lens 238 r1 at e7090ff: SAFE WITH NITS

Earlier findings 1-5 FIXED: key tool installed in host step 3 (.github/fork-fleet.md:452, pointed to from :594, :607 and fork-kit/desk/README.md:12; every /opt/fork-fleet/* file the runbook runs is installed there); docs order (:613-635); old wrapper state (:580-584; the dispatcher loads its config once at start, fork-fleet.py:1226); desk-key test (:59, :157); stale list (fork-fleet-refresh.test.py:976-977). Findings 4-5 are test cleanups that also pass on round-0.

The pc switch before the PC has the desk kit fails closed: no unit means no heartbeat; an early unit without socket/session/key makes launch exit 3 and the pool is marked down (fork-fleet.py:981-986, cleanup skips it :1072, :1097, :1112); a broken config makes load() raise (:82-88); re-running step 3 is safe (temp folder, SOURCE written last, fork-fleet.md:455-471). The example entry is neutral and passes check_config; FORK_CHANGES.md rows are right.

Nits:

1. No test that the release's pc pool is a desk pool (a launch typo would only show on the host):

def test_the_releases_pc_pool_is_a_desk_pool(self):
    self.assertEqual(dk.desk_pools(dk.ff.load()), ['pc'])

2. README.md:16 promises a "link is up" log line that does not exist; the real line is pool X answers again, after N passes left alone (fork-fleet.py:1138) and only after the pool was down. Quote the real line, or check desk-install check plus a started runner.
3. Another project's path is unclear: step 1 says release branch, step 2 a main commit, and host step 3's URL is fixed to this repository (fork-fleet.md:440); one line saying to point base at the project's repository.
4. Wording README.md:15: "the key the install printed".

Tests: desk-key 20, desk-seed 30, desk 42 OK; refresh Timer 8 OK. Other refresh/fork-fleet failures are fork-fleet-launch.sh tests needing a local https server, systemd or the network (not touched by this PR; not re-run on base).