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

* Fix local-only picker still skipping on a genuinely fresh enroll (issue #281 follow-up)

After the #283 reordering the picker ran at the right time but queried
through the wrong registry: hyp remote login boots its kernel at dispatch
time, before enrollment, and on a first-run box the local config names no
plugins. The login process's query-registry snapshot therefore never
registers ai_gateway_messages - that registration arrives with
@hypaware/ai-gateway, which the org config-control pull enables only after
enrollCentralSink installs the daemon. listCapturedDirectories then failed
with "unknown dataset" (best-effort null), waitForCapturedDirectories read
null as "enumeration cannot run, stop now" (no 30s poll), and the picker
took its enumeration_failed durable-hint path on exactly the fresh enroll
it exists for. The #283 tests stubbed waitForCaptured/listCandidates, so
the gap was never exercised; a re-login on a populated box worked, which is
why manual verification passed.

Fix: freshenCaptureEnumeration (src/core/cli/remote_commands.js). On the
fresh-enroll interactive fork, after waitForClientAttach returns a client,
re-boot one fresh kernel (config profile, the same layered resolution any
subsequent hyp command runs) and hand its registry's enumeration to the
capture wait. One re-boot is sufficient by construction: attach markers are
written by the reconciler that runs only after a confirmed config apply, so
attach means the pulled central layer is on disk - and the attach handler
requires the gateway capability, so that layer enables the plugin. The
snapshot-already-has-it case (re-login on a populated box) skips the boot
entirely; a failed re-boot or a still-missing dataset falls back to the
prior behavior. Best-effort throughout: the refinement never breaks the
login it refines (LLP 0072). The handle is disposed (sources.stopAll,
mirroring dispatch) after the picker so no boot-started source keeps the
login process alive.

local_only.js exports CAPTURE_DATASET so the registry check and the
enumeration SQL cannot drift. LLP 0069/0080 carry forward-ref notes per
the immutable-record convention.

Tests: seam-level coverage of the refresh wiring (fresh enumeration is
polled, disposed after the picker; null refresh falls back), unit coverage
of freshenCaptureEnumeration (snapshot no-op, success, still-missing,
boot-throw), and - the #283 lesson - one deliberately unstubbed test that
runs the REAL bootKernel against an on-disk central layer naming
@hypaware/ai-gateway and asserts enumeration RUNS (empty list, pollable)
instead of failing to null.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

Closes the one-time forwarding window the issue #281 reordering left open:
after PR #283 deferred the local-only picker past enrollCentralSink, the
daemon that enroll installs could attach, backfill, and start exporting
rows before the user finished the 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 forwarded once, permanently -
narrowing LLP 0069 R6's "not forwarded, even once" on exactly the
fresh-enroll path the picker exists for.

Decision (LLP 0093): the enrolling login writes a machine-local
pick-pending marker (usage-policy/pick-pending.json, co-located with the
local-only list) BEFORE enrollCentralSink, so no daemon tick can beat it
onto disk; the kernel sink driver skips whole export ticks while the
marker is fresh (held: 'pick_pending' in the tick report); the login
clears the marker in one finally covering every exit from the
fresh-enroll fork. Freshness is mtime with a 10-minute TTL and stale or
unreadable markers read as absent, so a crashed or abandoned login can
never stall exports indefinitely - the hold is a bounded refinement,
never a kill switch (LLP 0072). Held rows stay in the cache and export on
the first tick after the pick; watermarks make that a plain catch-up.

Enforcement is driver-wide rather than per-sink: 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. Rejected alternatives (backfill-before-forward
reordering, off-machine-only gating, unbounded hold) are recorded in the
decision doc. Re-logins and --no-forward/query-only logins never write
the marker.

Tests: marker module (fresh/clear/stale-unlink/injected-now/fail-open),
driver hold (fresh marker holds the whole tick, cleared or expired marker
exports), and login lifecycle (marker lands before enroll, persists
through the pick, cleared on return, on enroll error, and on non-TTY;
never written on re-login).

Stacked on the issue #281 follow-up fix (fresh-enroll registry refresh).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: philcunliffe

llp/0069-local-only-dir-selection.spec.md

@@ -150,6 +150,13 @@ is **no half-enrolled window** (see [dismiss semantics, LLP 0072 §default](./00
 > the capture wait. Best-effort: a failed re-boot falls back to the durable
 > hint, never an error. Requirements and R6 semantics are unchanged.
 
+> **Window closed by [LLP 0093](./0093-pick-pending-export-hold.decision.md).**
+> The one-time backfill forwarding window the first #281 note deferred is now
+> held shut: the enrolling login writes a bounded pick-pending marker before
+> `enrollCentralSink`, and the sink driver skips export ticks while it is
+> fresh, so R6's "not forwarded, even once" holds again on the auto-daemon
+> fresh-enroll path (bounded by the marker's TTL).
+
 The picker only makes sense on an **enrolling** login (one that provisions or
 already has a central sink). A `--no-forward` / query-only login
 ([LLP 0063 D3](./0063-login-auto-provision-forward-sink.decision.md)) forwards

llp/0080-local-only-dir-selection.design.md

@@ -338,6 +338,14 @@ enrollment it refines.
 > of this design is unchanged. See
 > [LLP 0069 §trigger, the follow-up note](./0069-local-only-dir-selection.spec.md#trigger).
 
+> **Extended-by [LLP 0093](./0093-pick-pending-export-hold.decision.md)
+> (export hold during the pick).** The one-time backfill forwarding window
+> both notes above describe is now closed: a bounded pick-pending marker
+> (`usage-policy/pick-pending.json`, written by the enrolling login before
+> `enrollCentralSink`, cleared on every exit from that fork) holds sink
+> driver ticks while fresh, restoring R6's "not forwarded, even once" on the
+> auto-daemon fresh-enroll path.
+
 ## CLI: the durable authoring path {#cli}
 
 `hyp ignore` / `hyp unignore` / `hyp ignore --check`

llp/0093-pick-pending-export-hold.decision.md

@@ -0,0 +1,98 @@
+# LLP 0093: fresh-enroll exports hold behind a bounded pick-pending marker
+
+**Type:** Decision
+**Status:** Accepted
+**Systems:** Sinks, CLI, Usage-Policy
+**Author:** Phil / Claude
+**Date:** 2026-07-08
+**Related:** LLP 0069, LLP 0071, LLP 0072, LLP 0080, LLP 0044, LLP 0063
+
+> Closes the one-time forwarding window the issue #281 reordering left open
+> (recorded as the "Revisited-by #281" notes in
+> [LLP 0069 §trigger](./0069-local-only-dir-selection.spec.md#trigger) and
+> [LLP 0080](./0080-local-only-dir-selection.design.md)), restoring R6's
+> "not forwarded, even once" on the auto-daemon fresh-enroll path.
+>
+> @ref LLP 0069 [implements] - restores the R6 ordering guarantee the #281 fix narrowed.
+> @ref LLP 0072 [constrained-by] - the hold must stay a bounded refinement; it can never block or fail the login, and an unanswered picker can never become a kill switch.
+
+## Context
+
+The #281 fix (PR #283) moved the local-only picker after `enrollCentralSink`
+so it enumerates a populated cache. That reintroduced a window: the daemon the
+enroll installs attaches clients and backfills history, and its central sink
+can start exporting those backfilled rows **before the user finishes the
+pick**. Withholding is enforced at export-read time (LLP 0080 export seam), so
+rows from a directory the user was *about to* mark local-only forward once -
+and the server has no retraction path, so that one-time leak is permanent.
+This narrowed LLP 0069 R6's "recorded here, never forwarded - not even once"
+to "withheld from every export tick after the pick" on exactly the
+fresh-enroll path the picker exists for.
+
+## Decision
+
+**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 (LLP 0071) whose first read it guards.
+  Content is debug metadata only; freshness is the file's mtime, so a torn
+  write can neither wedge nor extend the hold.
+- **Lifecycle is login-owned**: written on the fresh-enroll fork only (the
+  only fork where a first backfill can race the pick - a re-login edits a
+  list whose daemon is already forwarding, LLP 0080 editor semantics),
+  *before* `enrollCentralSink` so no daemon tick can beat it onto disk;
+  cleared in one `finally` covering every exit from that fork (pick landed,
+  cancelled, non-TTY skip, enroll error). Both write and clear are
+  best-effort: a failed write degrades to the pre-hold behavior, a failed
+  clear leaves the TTL as backstop; neither ever fails the login.
+- **Enforcement is driver-wide**: `createSinkDriver.tick` checks the marker
+  once per tick and, while fresh, exports nothing (`held: 'pick_pending'` in
+  the tick report, one info log). Held rows sit in the cache and export on
+  the first tick after the pick; watermarks (LLP 0040) make that a plain
+  catch-up, nothing is dropped.
+
+### The hold is always bounded {#bounded}
+
+The marker expires on its own: `isPickPending` treats a marker older than
+**10 minutes** (`PICK_PENDING_TTL_MS` - comfortably past the login's two 30s
+bounded waits plus a human actually reading the picker) as absent and
+opportunistically unlinks it. A stat failure also reads as absent. This is
+deliberately the opposite polarity of the local-only *list* (which fails
+loudly when unreadable, LLP 0080 #fail-safe): the list is the privacy signal,
+the marker is only a timing hint, and failing closed on it would turn a
+crashed login or a corrupt file into an unbounded export outage that only a
+hand-deleted file could end. A privacy hold that cannot expire is a kill
+switch, and LLP 0072 already decided the picker never gets one.
+
+## Alternatives rejected
+
+- **Backfill locally before the forwarding daemon starts** (the other option
+  the #281 note floated). Reordering does not actually close the window: the
+  pick needs a human, and the daemon would still forward the moment backfill
+  completed if the user had walked away. It also delays *all* forwarding
+  behind a possibly multi-minute backfill and rearranges the daemon
+  lifecycle (LLP 0044 attach-first ordering) for no guarantee.
+- **Gate only off-machine sinks**. The driver cannot know which sinks leave
+  the machine without a new registration concept (an `offMachine`
+  declaration every future forward sink must remember), and a plugin-side
+  convention is exactly the kind of seam a new sink forgets. Holding every
+  sink for a bounded window is harmless - a local sink's rows stay in the
+  cache and export minutes later - where one missed forward hold is a
+  permanent leak. One enforcement point in core, where local-only policy
+  already lives, wins.
+- **Unbounded hold until the pick lands**. See [#bounded](#bounded).
+
+## Consequences
+
+- R6's "not forwarded, even once" holds again on the auto-daemon
+  fresh-enroll path, provided the pick concludes within the TTL; a user who
+  ponders the picker past 10 minutes reverts to the narrowed guarantee
+  (withheld from every tick after the pick), never to an error.
+- Every sink, including local ones, pauses up to the pick duration (TTL-capped)
+  on a fresh enroll only. No steady-state cost: the marker exists for at most
+  one login's duration per machine lifetime, and a per-tick `stat` of a
+  usually-absent file otherwise.
+- `hyp remote login --no-forward` and query-only logins never write the
+  marker (they never reach the enrolling fork).