Skip to content

fork fleet: free/v1 "is this machine free?" contract and examples (D10) - #230

Draft
scuttletoby wants to merge 7 commits into
fork/desk-d9-windows-starterfrom
fork/desk-d10-free-contract
Draft

scuttletoby wants to merge 7 commits into
fork/desk-d9-windows-starterfrom
fork/desk-d10-free-contract

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Row D10 of the desktop pool plan: the free/v1 contract, "is this machine free?". It defines one small script contract, one reader, shared cases and two example scripts. The desk pool's fits can now use it. Stacked on #229 (D9).

Why

Several tools need to ask whether a machine may take more work: a desk pool's fits, the placement factsCommand, and later heavy facts. If each one has its own idea of the answer, CI and agents disagree about the same machine. A desktop owner also needs one simple way to say "not now, a game is running".

  • fork-kit/common/FREE.md: the contract.
    • A script is called with no arguments, by its absolute path, with a plain environment, and must answer within 3 s.
    • The exit code is the verdict: 0 free, 75 busy. Anything else is not available.
    • stdout is one JSON object of at most 4096 bytes. It must have v, free and at, and reason when busy. A few optional fact groups may follow.
    • It is only run when no one else can change it (owner and mode bits; ACLs are not read, see FREE.md), and the
      file that was checked is the one run: a link is resolved once and its target is run, never the link.
    • The path is followed one part at a time: the folders of the path as written are judged too, and every link on
      the way must belong to root or the caller (another user's link in /tmp is refused, as fs.protected_symlinks
      would).
  • fork-kit/common/free_contract.py: the one reader.
    • judge judges one answer.
    • ask runs a script with a time limit, an output limit and its own process group, which is ended on a timeout,
      together with any process that left the group (setsid) and still holds its stdout. A process that left the
      group and also closed stdout is not found: that is the documented bound. A group it may not signal (a set-uid
      script) is never waited for without a limit: at most one more second.
    • NaN and Infinity are not JSON: an answer with one is not available.
    • The command line ask [--need-mb MB] /path is for shell callers.
  • fork-kit/common/free-fixtures.json: 30 cases every reader, in any language, must agree on.
  • Examples:
    • free/memory: busy under memory pressure or with swap nearly full (FREE.md says when pressure can stay low).
    • free/busy-while-running: busy while a named program runs (names longer than 15 characters too). Copy it and put
      your programs in it. Windows programs are not visible from WSL (FREE.md).
  • Desk pool:
    • The machine file's desk.freeCommand (optional) goes to launch.conf as FREE_COMMAND.
    • The launcher's fits MB then also needs a free answer from it, through FREE_CHECK, the reader installed beside the launcher.
    • desk-install check shows what the script answers now.
    • The kit installs the reader and the memory example (/opt/fork-fleet/free-memory).

With no freeCommand, nothing changes: fits uses its memory rule alone.

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

Case What happens
Runs again Asking is read-only: a script is run, its answer judged, nothing is written. A re-install with the same freeCommand rewrites nothing (D8's rule).
Stops half-way A script that hangs, or whose group may not be signalled (waited for at most 1 s more), or leaves a child holding stdout, is no answer after 3 s. Its whole process group is ended, and the verdict is not available, which counts as not free (tested). A stopped install follows D8: the next run finishes it.
Existing / old state A freeCommand reached through a folder others may change, or through another user's link, was run before and is now not available (not free) until the path is fixed; desk-install check shows why. Facts more than 60 s from now count as not available, so a stale cached answer cannot say free. A newer v counts as not available, never guessed. An old launch.conf without FREE_COMMAND keeps the memory-only rule. Unknown fields are ignored.
Empty state No script set: the memory rule alone. An empty stdout, a missing script, or a script that is a folder: not available, so not free. An unsafe script (others may change it or a folder above it, relative path, not executable) is never run (tested).

General vs project

General. The contract, reader and examples name no project, person or machine. The example program names in busy-while-running are made up. Which script a desktop uses is that desktop's own machine file setting.

Upstream fit

Only the fork-only folders fork-kit/ and .github/scripts/fork-fleet-* change. Nothing in upstream T3 changes.

Tests

  • fork-kit/common/tests/free_contract.test.py (new, in .github/fork-ci-tests.txt):
    • every case in the fixtures file
    • real scripts: the environment and folder a script gets, busy with a reason, a hang that ends its whole group, a child holding stdout, endless output cut at 4096 bytes, six kinds of unsafe script never run, a folder others may change, a sticky folder that is fine, and a link judged by where it leads, a link repointed after the check that does not change what runs, a child that
      left the group and holds stdout is ended, a name longer than 15 characters, another user's link in a sticky folder not followed, the folders of the path as
      written judged, relative links, chains and loops, a script it may not end not waited for without a limit
    • the command line
    • both examples answer by the contract on the test machine
  • .github/scripts/fork-fleet.test.py: fits asks the free script too: free, busy, a freeMb below the size asked, not available, the memory rule asked first (the script is not run when memory already says no), a reader others may write refused, and a relative FREE_COMMAND refused.
  • fork-kit/desk/tests/install.test.py: a free script reaches launch.conf and the check row.

Local run (round 2):

  • fork-kit/common/tests/free_contract.test.py: 17 OK
  • fork-kit/common/tests/machine_file.test.py: 17 OK
  • fork-kit/desk/tests/install.test.py: 34 OK
  • .github/scripts/fork-fleet.test.py -k fits: 2 OK
  • .github/scripts/fork-fleet-walls-wsl2.test.py: 15 OK
  • Round 1: the new free_contract tests run against the round-0 code fail 5 times (the repointed link, the setsid child, the 15-character name, NaN, Infinity).
  • Round 2: the four new tests run against the round-1 code fail 4 times (another user's link followed to true,
    a 0777 folder of the path as written not judged, no resolve, a 30 s wait after a refused killpg).

Since #213 the WSL2 walls pin the launcher's sha256 (LAUNCHER_SHA256), so this PR's launcher change updates the
pin. The change only adds two settings and a step in fits; how job units are made is unchanged, so the walls'
reading of the launcher still holds. fork-fleet-walls.test.py (41) and fork-fleet-walls-wsl2.test.py (15) pass
with it. FREE.md and free-fixtures.json are now in the repository's format (oxfmt; the data is unchanged).

Red-checks

Each rule was broken in a copy, one at a time, and the named test failed (all 6 red):

  • the whole process group ended on a timeout -> test_no_answer_in_time_ends_its_whole_group
  • free must match the exit code -> the shared fixtures
  • facts more than 60 s from now are not free -> the shared fixtures
  • a script others may change never runs -> test_unsafe_scripts_never_run
  • a free answer with freeMb below the size counts as busy -> the shared fixtures
  • fits asks the free script -> test_fits_asks_the_free_script_too

🤖 Generated with Claude Code

@scuttletoby
scuttletoby force-pushed the fork/desk-d9-windows-starter branch from f061484 to e554ddf Compare November 15, 2026 19:37
@scuttletoby
scuttletoby force-pushed the fork/desk-d10-free-contract branch 2 times, most recently from 91abd6e to f877ff9 Compare November 15, 2026 19:47
One small contract for every tool that asks whether a machine may take more
work: no arguments, 3 s, exit 0 free / 75 busy, one JSON object on stdout.
fork-kit/common/free_contract.py is the one reader (judge, ask, and a CLI for
shell callers); free-fixtures.json holds the cases every reader must agree on.
Two examples: memory (pressure, swap) and busy-while-running (named programs).

The launcher's fits also asks FREE_COMMAND when launch.conf names one (default
none: the memory rule alone). The desk kit installs the reader and the memory
example and writes FREE_COMMAND from the machine file's desk.freeCommand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review round 1 at f18fbda (lens230): SAFE WITH NITS. Fix round to follow.

Holds: no wall weakened (walls/wsl2:39 pin matches the launcher); fits checks memory first and any non-0 reader exit means "does not fit"; 3 s steady-clock deadline with the group killed on every path; 4096-byte output cap; plain env from /; at window ±60 s; old launch.conf keeps the memory rule alone; install stopped between file swap and settings is finished by the next run. Tests: free_contract 10, install 20, fork-fleet -k fits 2, walls-wsl2 15, all OK.

  1. free_contract.py:81,105: a link is checked by its target but run by its own path, and the folder holding the link is never checked. With freeCommand a link in a 0777 folder, another local user can repoint it between check and run (every dispatcher pass) and run code as root. Needs an owner misconfiguration; fix by running the resolved path. (proven)
  2. :46: json.loads accepts NaN/Infinity; "freeMb": NaN with --need-mb 100 gives free (NaN < 100 is False). Use parse_constant to reject, plus a fixture case. (proven)
  3. :123: a grandchild that calls setsid and holds stdout outlives ask(), leaking one process per fits call into the agent's cgroup. (proven)
  4. free/busy-while-running: ps -o comm= cuts names to 15 chars, and Windows programs are invisible in WSL (documented); the memory example's full avg10 > 10 can stay low while swapping hard.
    Nits: unsafe() ignores ACLs; select() fails on fds above 1024 in a long-lived consumer (none today).

scuttletoby and others added 4 commits November 15, 2026 20:45
- ask() runs the file unsafe() judged (the link's target), never the link
- NaN and Infinity are not JSON: not available (two fixture cases)
- a child that left the group with setsid and still holds stdout is ended;
  one that also closed stdout is the documented bound
- poll() instead of select() (descriptors above 1024)
- busy-while-running matches names longer than 15 characters
- FREE.md: the bound, links, ACLs, the memory example's pressure caveat

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ontract

# Conflicts:
#	fork-kit/desk/sbin/desk-install
The round-1 fix resolved the link again after the check, so a link
repointed between the two still changed what ran. The new test caught it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Fix round 1 (commits 8a312ae and f706ea4; D9's round 1 merged in; head f706ea4). Tests: free_contract 13 OK, machine_file 17 OK, install 28 OK, windows 11 OK (1 skipped, no pwsh), walls-wsl2 15 OK.

  1. Link checked by target but run by path: fixed (8a312ae, f706ea4). ask() resolves the link once, before the check, and both judges and runs that file (the first commit still resolved it again after the check; the test caught it). Test: test_a_link_repointed_after_the_check_does_not_change_what_runs.
  2. NaN/Infinity: fixed (8a312ae). parse_constant refuses them: not available. Two fixture cases (NaN is not JSON, Infinity is not JSON), now 30.
  3. setsid grandchild holding stdout: fixed (8a312ae). After the group is ended, any process still holding the stdout pipe is found through /proc/*/fd and killed. Test: test_a_child_that_left_the_group_and_holds_stdout_is_ended. A process that left the group and also closed stdout is not found: documented in FREE.md as the bound.
  4. busy-while-running 15 characters: fixed (8a312ae), test test_busy_while_running_knows_names_longer_than_15_characters. Windows programs invisible in WSL and the memory example's pressure caveat: documented in FREE.md.
    Nits: unsafe() and ACLs: documented (FREE.md: ACLs are not read; do not give a free script one). select() above 1024: fixed (poll()).

Fails before the fix: the new tests run against the round-0 code fail 5 times (repointed link, setsid child, 15-character name, NaN, Infinity).

PR body updated (30 cases, the bound, links). Still draft.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Re-check lens 230 r1 at f706ea4: SAFE WITH NITS

Earlier findings: 1 link checked vs run FIXED (free_contract.py:122-129); 2 NaN/Infinity FIXED (:49); 3 setsid grandchild FIXED within the documented one-scan bound (:102-114, :155-160); 4 15-char names FIXED (fails safe on shared prefixes); nits FIXED/documented. All 5 new tests fail on round-0. Tests: free_contract 13, install 28, walls-wsl2 15, fork-fleet -k fits 2, all OK.

New:

  1. (Low) Resolving the link in Python (:123 with :85/:93) bypasses fs.protected_symlinks: the link's owner and the folder holding it are not checked, only the target's folders. With freeCommand=/tmp/free (FREE.md says a sticky folder is fine) and the file missing, another local user can ln -s /usr/sbin/poweroff /tmp/free and the next fits runs it as root. Not reachable from CI jobs (private /tmp, fork-fleet-launch.sh:1083). Fix: refuse a link in a folder others may write unless owned by root or the caller; check the folders above the original path too.
def test_a_link_another_user_owns_in_a_sticky_folder_is_not_followed(self):
    with tempfile.TemporaryDirectory() as d:
        os.chmod(d, 0o1777); link = os.path.join(d, 'free')
        os.symlink('/usr/bin/true', link)
        real, os.geteuid = os.geteuid, (lambda: 4242)
        try: verdict, reason, _ = fc.ask(link)
        finally: os.geteuid = real
        self.assertNotEqual(reason, 'stdout is not JSON')
  1. Nit: a killpg PermissionError (:135, :151-154) makes leaving with p wait without a limit; both callers run as root today.

Checked and holding: monotonic 3 s limit with the whole group killed on every path, 4096-byte cap, plain env from /, absolute paths only, only exit 0 is free, at within ±60 s; no wall weakened (the walls/wsl2:39 pin equals the head launcher's sha256); old launch.conf without FREE_COMMAND falls back to the memory rule; a missing script is never free.

scuttletoby and others added 2 commits November 15, 2026 22:41
…und 2)

- free_contract.resolve() follows freeCommand one part at a time, as the
  kernel does: every folder on the path as written must belong to root or
  the caller and not be changeable by others (sticky is fine), and every
  link on the way must belong to root or the caller. Another user's link
  in a sticky folder is no longer followed to a root program (what
  fs.protected_symlinks refuses). Loops stop after 40 links.
- ask(): a process group it may not signal no longer makes it wait
  without a limit; it ends the script itself when it can and waits at
  most one more second.
- Tests: the lens test (another user's link in a sticky folder), folders
  of the path as written, relative links, chains and loops, and the
  bounded wait. FREE.md says the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Fix round 2 at 83849bc (D9 round 2 merged in first)

Findings of the lens 230 r1 re-check:

  1. (Low, MUST) A link resolved in Python bypasses fs.protected_symlinks: fixed in 83849bc. The new free_contract.resolve() follows freeCommand one part at a time, as the kernel does:

    • every folder on the path as written must belong to root or the caller, and no one else may change it (sticky is fine);
    • every link on the way must belong to root or the caller.

    So another user's /tmp/free -> /usr/sbin/poweroff is refused, and so is a link in a 0777 folder. Loops stop after 40 links. unsafe() and ask() both use it, and the file is still resolved once and that file is run.
    Tests (all fail on round 1):

    • test_a_link_another_user_owns_in_a_sticky_folder_is_not_followed: the lens test, with a faked geteuid. On round 1, true ran.
    • test_the_folders_of_the_path_as_written_are_judged_too
    • test_relative_links_chains_and_loops
  2. Nit: a killpg PermissionError gave a wait without a limit: fixed in 83849bc.

    • ask() no longer uses with p. On PermissionError it tries p.kill(), closes stdout, and waits at most 1 more second. A script it could not end is left to finish.
    • Test: test_a_script_it_may_not_end_is_not_waited_for_without_a_limit. On round 1 it waited the script's full 30 s.

State question:

  • Runs again: resolving reads only, so a second call gives the same answer.
  • Stops half-way: a script whose group cannot be signalled now costs at most about 1 s more.
  • Old state: a freeCommand that passes through a folder others may change, or through another user's link, used to run. It is now "not available", which counts as not free, until the path is fixed. desk-install check shows the reason.

Docs: FREE.md and the PR body say the same.

Local run (round 2):

Test Result
free_contract 17 OK
install 34 OK
walls-wsl2 15 OK
fork-fleet -k fits 2 OK

Red-check: the new tests run against round-1 code give 3 failures and 1 error.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant