Hold sink exports behind a bounded pick-pending marker on fresh enroll (LLP 0093)

[philcunliffe]

Stacked on #286 (fresh-enroll registry refresh) - the diff here is only the export hold. When #286 merges, GitHub retargets this to master.

Problem

The issue #281 reordering (PR #283) left a one-time forwarding window it explicitly deferred (the "Revisited-by #281" notes in LLP 0069/0080): on a fresh auto-daemon enroll, the daemon attaches, backfills, and can start exporting backfilled rows before the user finishes the local-only pick. Withholding is enforced at export-read time and the server has no retraction path, so rows from a directory the user was about to withhold forward once, permanently. That narrowed LLP 0069 R6's "recorded here, never forwarded - not even once" on exactly the path the picker exists for.

Decision (new LLP 0093)

The enrolling login writes a machine-local pick-pending marker before enrollCentralSink, and the kernel sink driver skips whole export ticks while that marker is fresh.

• Marker: usage-policy/pick-pending.json under HYP_HOME state, co-located with the local-only list it guards. Content is debug metadata; freshness is mtime, so a torn write can neither wedge nor extend the hold.
• Login-owned lifecycle: written on the fresh-enroll fork only (a re-login edits a list whose daemon already forwards), before enrollCentralSink so no daemon tick can beat it onto disk; cleared in one finally covering every exit (pick landed, cancelled, non-TTY skip, enroll error). Write and clear are best-effort - neither can fail the login (LLP 0072).
• Bounded, never a kill switch: 10-minute TTL (comfortably past the login's two 30s waits plus a human reading the picker); stale markers are treated as absent and unlinked; unreadable markers fail open - deliberately the opposite polarity of the local-only list (which fails loudly), because the marker is a timing hint, not the privacy signal, and failing closed would turn a crashed login into an unbounded export outage.
• Driver-wide enforcement: the driver cannot know which sinks leave the machine without a new registration concept, and briefly deferring a local sink is harmless where one missed forward hold is a permanent leak. Held rows stay in the cache; watermarks make the post-pick tick a plain catch-up.

Rejected alternatives (recorded in LLP 0093): backfill-before-forward reordering (does not close the window - the pick needs a human, and forwarding would resume the moment backfill finished if the user walked away), off-machine-only gating, unbounded hold.

Tests

• Marker module: fresh/clear/stale-unlink/injected-now/fail-open.
• Driver: a fresh marker holds the whole tick (held: 'pick_pending', no exportBatch call); a cleared or expired marker exports normally.
• Login lifecycle: marker lands before enroll, persists through the pick, and is cleared on return, on enroll error, and on non-TTY; never written on the re-login fork.

npm test: 2140 pass. build:types clean. Smokes: core_boot_noop, daemon_foreground_start_stop, local_only_export_withhold all ok.

🤖 Generated with Claude Code

[philcunliffe]

neutral review — adopted PR (full-heal, stacked on #286), head f628806

Verdict: clean. No blockers, majors, or minors. Reviewed the incremental delta on top of fix/picker-fresh-enroll-registry. Mergeable ∧ green (typecheck + test SUCCESS) ∧ reviewed.

Egress / withholding invariant (no leak found): driver.tick is the sole production forwarding chokepoint. Both callers — src/core/daemon/runtime.js:478 (daemon loop) and src/core/commands/sink.js:41 (hyp sink) — enter through it, and the marker check is the first thing after the tick counter (driver.js:58), returning { sinks: [], held: 'pick_pending' } before any listHandles/exportBatch. No sink (including the central forward sink) can export while the marker is fresh. The columns-projection/query read path is a separate seam already covered by LLP 0080 read-time withholding; this hold correctly targets the forwarding-tick race that seam can't cover on a fresh enroll. Marker path aligned: login writes ${HYP_HOME}/hypaware, daemon driver reads the same file.

Bounded (no kill switch needed): TTL 10 min via file mtime (pick_pending.js:96); stale marker reads absent + is opportunistically unlinked; stat failure fails open. An abandoned/crashed login can never wedge exports past the TTL — correctly the opposite polarity to the local-only list (which fails closed).

Ordering / lifecycle / idempotency: Marker written BEFORE enroll/enrollCentralSink (remote_commands.js:728), so no daemon tick beats it to disk. finally clears it on every exit from the fresh-enroll fork (pick landed, cancelled, non-TTY skip, enroll-throw, connectedElsewhere), gated by holdingExports so only a landed marker is cleared. Write and clear are best-effort (degrade to pre-hold behavior / TTL backstop; never fail login). Re-login/re-seed writes no marker.

Test quality (proves withhold-while-pending + release-after-pick): test/core/pick-pending.test.js:96 drives the real createSinkDriver: fresh marker → held==='pick_pending', 0 exports; clear marker → next tick held===undefined, 1 export — a true fail-before/pass-after in one test. Plus TTL-stale, injected-now freshness, and fail-open-on-unreadable coverage. remote-login-command.test.js proves marker present at enroll time, cleared on return/throw/non-TTY, never written on re-login. 72/72 tests pass.

@ref: driver.js:57, pick_pending.js:22/89 cite LLP 0093 / #bounded (anchor exists). LLP 0069/0080 edits are forward-ref notes only. No [inferred] claim survives in Accepted 0093.

[philcunliffe]

neutral verdict: approved ✅ — mergeable ∧ green ∧ reviewed at head f628806. Stacked on #286 — merge #286 first, then #287. Held for you to merge.

[philcunliffe]

neutral review (round 2) — adopted PR, head 2fc31aa

Verdict: clean. Re-review after conflict resolution. Mergeable ∧ green ∧ reviewed.

Why re-reviewed: #286 squash-merged to master and its branch was deleted; GitHub retargeted this PR's base to master, which left it CONFLICTING (master's #286 squash commit vs this branch's original #286 commits + #287's additions on the four shared files). neutral (full-heal, canPush) merged master in and resolved, keeping #287's superset on each shared file.

Re-verification of the resolution (nothing lost, nothing masked):

• Incremental delta vs the new base (master) now equals exactly Hold sink exports behind a bounded pick-pending marker on fresh enroll (LLP 0093) #287's own change set — llp/0093 + sinks/driver.js + sinks/types.d.ts + usage-policy/pick_pending.js + tests + the marker integration in remote_commands.js. Fix local-only picker still skipping on a genuinely fresh enroll (issue #281 follow-up) #286's changes no longer appear in the delta (they're on both sides now), confirming a correct union.
• Fix local-only picker still skipping on a genuinely fresh enroll (issue #281 follow-up) #286's freshenCaptureEnumeration and the full attach-wait → freshen → waitForCapturedDirectories → runLocalOnlyPicker sequence are present and intact in the merged head (not clobbered by the restructure).
• Hold sink exports behind a bounded pick-pending marker on fresh enroll (LLP 0093) #287's marker wrapping is correctly placed: markPickPendingBestEffort before enroll (remote_commands.js:731), clearPickPendingBestEffort in the finally gated by holdingExports (:840). The egress-hold invariant from round 1 still holds.
• No leftover conflict markers anywhere in src/, test/, llp/.

Green: full suite 2140 pass, 0 fail, 1 skipped; the two directly-touched files 72/72; npm run build:types (tsc) exit 0 — no type-import breakage.

Same clean bill as the round-1 review of f628806; the only change is the conflict resolution, which preserved all reviewed content.

[philcunliffe]

neutral verdict: approved ✅ (round 2, head 2fc31aa) — conflict with master resolved, mergeable ∧ green ∧ reviewed. Now that #286 has landed, #287 targets master directly and is held for you to merge.