Skip to content

hold-work: --hold-work needs --base-dir; one marker read per boot (#439) - #497

Merged
scuttletoby merged 2 commits into
mainfrom
w439-hold-work-followups
Nov 18, 2026
Merged

scuttletoby merged 2 commits into
mainfrom
w439-hold-work-followups

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

Fixes #439

Follow-ups from the round-2 lenses on #398. Item 1 is needed before go-live.

What changes

  1. t3 serve --hold-work needs --base-dir, and never the default home. It is refused without --base-dir, with a blank one, and when the path resolves to the default home (~/.t3, also through a symlink, ~/.t3, a trailing / or x/..). The check runs before config resolution, so nothing is started or written, and the message explains why. T3CODE_HOME on its own is not enough: it is set in a shell, not written on the command. The go-live kit's rehearsal already passes --base-dir <clone>/home, so it is not affected.
    • The two --hold-work refusals moved to a new fork file, apps/server/src/cli/forkHoldWork.ts. cli/server.ts (a pending file) now holds 20 fewer fork lines, and upstream's one-line serviceLauncherClient import is back. The pending ceiling goes from 37 to 17 and the lost counts from 4 to 3, because --from-upstream asks for that.
  2. Docs: a copy made from only the userdata/ of a marked copy (as the kit's copy step does) is not protected. It is now listed next to the copies from older builds (docs/fork/updates.md).
  3. The marker is read once per boot. One ConnectHoldDecision layer value is provided by both the CloudLink wrapper and the agent-activity wrapper. A server builds a given layer value once, so both parts use the same answer and cannot disagree. The docs now say so.
  4. Comment: the marker check fails closed on purpose (holdWorkConnect.ts, at orElseSucceed(() => true)).

Tests

Test New code Old code
server.holdWork.test.ts: serve --hold-work with no --base-dir (fake user home) refused, ~/.t3 not created red: it starts a server on the default home (times out)
server.holdWork.test.ts: no or blank flag; default home in 5 spellings, symlink included; named copies allowed green (new function)
holdWorkConnect.test.ts: both layers built together count marker checks (marked home, marker deleted by hand while CloudLink builds, unmarked home) 1 read, and both parts agree red: 2 reads (3 rows)
holdWork.boot.test.ts: one HoldWorkConnect.heldCopyMarker span on the marked boot and on the unmarked boot (real t3 serve) green red: expected 2 to be 1

Run locally, with heavy and the user home pointed at a scratch folder:

  • holdWorkConnect, server.holdWork, connect.holdWork, config, connect, up.connect and holdWork.boot: 70/70.
  • typecheck for apps/server: green.
  • fork-seam-check.test.cjs: green. Golive contract.test.py: green.
  • node .github/scripts/fork-seam-check.cjs origin/main HEAD: pass. --from-upstream <upstream merge-base> HEAD: pass, after lowering the ceiling.

State question

Case Result
Runs again (marker already there) A second held boot keeps the marker as it is (wx). Every boot reads it once and holds Connect and agent activity together. The --base-dir refusal has no state of its own, so it gives the same answer each time.
Stopped half-way (marker written, boot cut off) An empty or partly written marker still counts. The decision is made once, before CloudLink is built. A boot cut off after that has started no tunnel. The refusal runs before anything is written, so cutting it off leaves nothing behind.
Old or empty home (no marker, missing home) No marker: one read, nothing held, as upstream. A missing --base-dir home is allowed and created later, as before. A missing default home is still refused by path. Copies with no marker (never held, held only on older builds, or userdata/-only) are not protected, as the docs say.
Marker deleted or added by hand during boot Both parts follow the single read, so they cannot split.
Marker check fails (EIO/EACCES) Counted as marked (fail closed). This is unchanged and now has a comment.

Fix round 1 (lens SAFE: 2 minors + 1 nit)

All three are fixed in apps/server/src/cli/forkHoldWork.ts. The check still runs before anything starts or writes. Each one has a test in server.holdWork.test.ts that was red on the old code.

  1. $HOME pointed elsewhere. .t3 under the account's passwd home (os.userInfo().homedir, which ignores $HOME) is refused as well. Tests: refuses the account's own T3 home when $HOME points somewhere else (the real passwd home with a scratch HOME) and refuses the account home's .t3, made or not, and nothing beside it (hermetic).
  2. Same folder, different spelling or mount. When both folders exist, their stat dev+ino are compared too. The path checks are kept. Test: refuses the same folder under another spelling the path check cannot see. It uses a file system that folds .T3 to .t3 and whose realPath keeps the spelling, as the JS realpath does on APFS.
  3. A home not made yet, behind a symlinked parent. The deepest folder that exists is realpath'd and the rest of the path is appended. Test: refuses a default home not made yet, reached through a symlinked parent.

Rebased onto the new fork main (2284c4cf). fork-seam-check.cjs origin/main HEAD passes. The three PR test files give 36/36 and the apps/server typecheck is green.

General vs project

General. Everything is in the fork's own t3 serve --hold-work and the T3 Connect hold, with nothing tied to one machine or project. The default home comes from HostProcess.HomeDirectory (~/.t3), as upstream resolves it, and from the account's passwd home.

🤖 Generated with Claude Code

@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: state+safety verdict: SAFE (head ae13523)

Read-only review, Opus 5.5. The items in #439 are done, and the bypasses I found are minor. Nothing blocks the merge or go-live.

Run myself (clone, heavy, scratch HOME): holdWorkConnect, server.holdWork and holdWork.boot give 32/32. apps/server typecheck is green. fork-seam-check.cjs origin/main HEAD passes, and so does --from-upstream <merge-base> HEAD. PR CI: 25 pass, 2 pending.

Findings

  1. minor: $HOME pointed elsewhere lets the live home through. See apps/server/src/cli/forkHoldWork.ts:57. resolveBaseDir(undefined) builds the default home from HostProcess.HomeDirectory, which is os.homedir(), and that follows $HOME. So HOME=/scratch t3 serve --hold-work --base-dir /home/<user>/.t3 is allowed, and it marks the live home. The same goes for sudo/root with --base-dir /home/<user>/.t3. Fleet agents are told to run servers with a scratch HOME, so this is the setting where a typo is most likely. Probe (green, so allowed): give HomeDirectory = <tmp>/scratch and flag = <tmp>/real/.t3 with that folder present, and refuseHoldWorkOnDefaultHome succeeds. Fix: also refuse NodeOS.userInfo().homedir/.t3 (the passwd home, which ignores $HOME).
  2. minor: the comparison is by path, so on macOS --base-dir ~/.T3 gets through. See forkHoldWork.ts:58-60. fs.realPath is NFS.realpath (JS) everywhere except win32 (platform-node-shared NodeFileSystem.js:390). The JS version keeps the spelling it is given for parts that are not symlinks. On a case-insensitive APFS volume, then, ~/.T3 is the live home but is not equal to ~/.t3. I found this by reading the code and could not run it, because this box is Linux. A bind mount or a second mount of the same folder slips through the same way. Fix: compare stat dev+ino when both paths exist, and keep the path comparison as the fallback.
  3. nit: a missing default home reached through a symlinked parent gets through. See forkHoldWork.ts:58. realPath fails on a path that does not exist, and orElseSucceed(() => path) then compares the raw strings. Probe: <root>/alias -> <root>, no <root>/.t3, flag <root>/alias/.t3 is allowed. The server then creates <root>/.t3 and marks it, so on a machine with no T3 home yet, the first real install starts with Connect held. Fix: realpath the parent folder and join the basename.

Each probe is in apps/server/src/cli/l497.probe.test.ts in my clone. The test body for each is given above. They were run with vp test run.

State

  • Runs again: wx keeps the existing marker. The refusal keeps no state of its own.
  • Stops half-way: in the CloudLink chain, the decision layer is built before markHeldCopy and CloudLink.layer (the order of provide). So it is fixed before any tunnel can start. An empty or partial marker counts.
  • Old, empty or odd homes: with no marker there is one read and nothing is held. resolveBaseDir makes relative paths, trailing / and x/.. the same on the held boot and on normal boots, so the marker path matches. A home behind a symlink resolves to the same file.
  • One read per boot: connectHoldDecision is a module-level value, so the server's single build of its layers shares it. server.ts:692 (agent activity) and :1361 (CloudLink) get the same WorkAdmission (:1366) and ServerConfig. holdWork.boot.test.ts checks exactly 1 span on a real t3 serve, so a later Layer.fresh or split runtime would show up in that test. A restart exits the process (layerServerRestart, SIGTERM) and the next boot reads again, so nothing goes stale.
  • Connect vs agent activity: they can no longer disagree within one server. The t3 connect CLI still reads the marker on its own while a server runs, which is documented ("counts from its next start").
  • Boot paths: holdWork is set only by the serve flag (cli/server.ts:29 → cli/config.ts:535). No env var or bootstrap envelope can set it. Under --hold-work a blank flag is refused, so T3CODE_HOME and the desktop bootstrap.t3Home cannot pick the home.

Safety

  • Fail-closed is unchanged (holdWorkConnect.ts:211-214), and the decision layer cannot fail. The refusals run before config resolution, and a launcher error refuses (forkHoldWork.ts:17). The only fail-open spot is the realPath fallback (finding 3).
  • Seam list: server.ts against the upstream merge-base is +18 −3. That is the flag, the option, one call and the import. Flag is added to the effect/cli import, which explains 3 lost lines. Upstream's serviceLauncherClient import is back as it was. No fork logic is left out of the count.

scuttletoby and others added 2 commits November 18, 2026 16:05
- `t3 serve --hold-work` is refused without --base-dir, with a blank one,
  and on the default home (~/.t3, any spelling or a symlink to it), before
  anything starts or is written: a held boot marks its home, and on the
  live home that holds T3 Connect at every later boot. The refusals move
  to the fork file cli/forkHoldWork.ts, so cli/server.ts keeps 20 fewer
  fork lines (pending ceiling 37 -> 17, lost 4 -> 3).
- The held-copy marker is read once per boot: one ConnectHoldDecision
  layer value, shared by the CloudLink and agent activity wrappers, so the
  two can never disagree. Unit test counts the reads (2 on the old code)
  and covers a marker deleted during boot; the boot test asserts one
  heldCopyMarker span per boot.
- A comment says the marker check fails closed on purpose.
- Docs: --base-dir rule, one shared read, and a userdata-only copy of a
  marked copy is not protected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… parents (#439)

Fix round 1 for the default-home refusal of `serve --hold-work`:
- also refuse `.t3` under the passwd home (os.userInfo), so a scratch $HOME
  does not let `--base-dir <real home>/.t3` through;
- when both folders exist, compare dev+ino as well as paths, for
  case-insensitive disks and second mounts;
- a target not made yet resolves its deepest existing parent, so a symlinked
  parent cannot reach the default home.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby
scuttletoby force-pushed the w439-hold-work-followups branch from ae13523 to efee083 Compare November 18, 2026 16:06
@scuttletoby
scuttletoby merged commit 6951a31 into main Nov 18, 2026
39 checks passed
scuttletoby added a commit that referenced this pull request Nov 18, 2026
…) (#497)

* hold-work: --hold-work needs --base-dir; one marker read per boot (#439)

- `t3 serve --hold-work` is refused without --base-dir, with a blank one,
  and on the default home (~/.t3, any spelling or a symlink to it), before
  anything starts or is written: a held boot marks its home, and on the
  live home that holds T3 Connect at every later boot. The refusals move
  to the fork file cli/forkHoldWork.ts, so cli/server.ts keeps 20 fewer
  fork lines (pending ceiling 37 -> 17, lost 4 -> 3).
- The held-copy marker is read once per boot: one ConnectHoldDecision
  layer value, shared by the CloudLink and agent activity wrappers, so the
  two can never disagree. Unit test counts the reads (2 on the old code)
  and covers a marker deleted during boot; the boot test asserts one
  heldCopyMarker span per boot.
- A comment says the marker check fails closed on purpose.
- Docs: --base-dir rule, one shared read, and a userdata-only copy of a
  marked copy is not protected.

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

* hold-work: refuse the account's home, same-folder identity, symlinked parents (#439)

Fix round 1 for the default-home refusal of `serve --hold-work`:
- also refuse `.t3` under the passwd home (os.userInfo), so a scratch $HOME
  does not let `--base-dir <real home>/.t3` through;
- when both folders exist, compare dev+ino as well as paths, for
  case-insensitive disks and second mounts;
- a target not made yet resolves its deepest existing parent, so a symlinked
  parent cannot reach the default home.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
scuttletoby added a commit that referenced this pull request Nov 18, 2026
…) (#497)

* hold-work: --hold-work needs --base-dir; one marker read per boot (#439)

- `t3 serve --hold-work` is refused without --base-dir, with a blank one,
  and on the default home (~/.t3, any spelling or a symlink to it), before
  anything starts or is written: a held boot marks its home, and on the
  live home that holds T3 Connect at every later boot. The refusals move
  to the fork file cli/forkHoldWork.ts, so cli/server.ts keeps 20 fewer
  fork lines (pending ceiling 37 -> 17, lost 4 -> 3).
- The held-copy marker is read once per boot: one ConnectHoldDecision
  layer value, shared by the CloudLink and agent activity wrappers, so the
  two can never disagree. Unit test counts the reads (2 on the old code)
  and covers a marker deleted during boot; the boot test asserts one
  heldCopyMarker span per boot.
- A comment says the marker check fails closed on purpose.
- Docs: --base-dir rule, one shared read, and a userdata-only copy of a
  marked copy is not protected.

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

* hold-work: refuse the account's home, same-folder identity, symlinked parents (#439)

Fix round 1 for the default-home refusal of `serve --hold-work`:
- also refuse `.t3` under the passwd home (os.userInfo), so a scratch $HOME
  does not let `--base-dir <real home>/.t3` through;
- when both folders exist, compare dev+ino as well as paths, for
  case-insensitive disks and second mounts;
- a target not made yet resolves its deepest existing parent, so a symlinked
  parent cannot reach the default home.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.

Held-copy marker (#398) follow-ups: --hold-work on the default home, docs

1 participant