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

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>

Author: philcunliffe

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

@@ -133,6 +133,23 @@ is **no half-enrolled window** (see [dismiss semantics, LLP 0072 §default](./00
 > the follow-up tracked in [issue #281]; this record's decision is otherwise
 > unchanged.
 
+> **Revisited-by [issue #281] follow-up (fresh-enroll registry staleness).** The
+> #281 reordering above fixed *when* the picker runs but left *what it queries
+> with* stale: `hyp remote login` boots its kernel before enrollment, and on a
+> first-run box the local config names no plugins, so the login process's
+> query-registry snapshot 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. The
+> [enumeration](#enumerate) then failed as "unknown dataset" (best-effort null),
+> the capture wait read null as "cannot run, stop", and the picker still
+> silently skipped on every genuinely fresh enroll. The fix
+> (`freshenCaptureEnumeration`, `src/core/cli/remote_commands.js`) re-boots one
+> fresh kernel after a client attaches — attach markers land only after the
+> confirmed config apply, so the pulled central layer is on disk by then and the
+> re-boot's merged config registers the dataset — and hands its enumeration to
+> the capture wait. Best-effort: a failed re-boot falls back to the durable
+> hint, never an error. Requirements and R6 semantics are unchanged.
+
 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

@@ -325,6 +325,19 @@ enrollment it refines.
 > runs against the already-populated cache. Everything else in this design
 > (store, resolver, export seam, CLI, status) is unchanged.
 
+> **Revisited-by [issue #281] follow-up (fresh-enroll registry staleness).** The
+> reordered wiring above still enumerated through the login process's boot-time
+> query-registry snapshot, which on a genuinely fresh box predates the org
+> config pull that enables `@hypaware/ai-gateway` — so `ai_gateway_messages` was
+> unregistered, the enumeration failed to null, and the picker still silently
+> skipped. The fix adds `freshenCaptureEnumeration`
+> (`src/core/cli/remote_commands.js`): after a client attaches (which
+> guarantees the pulled central layer is on disk), the login re-boots one fresh
+> kernel and hands its registry's enumeration to the
+> `waitForCapturedDirectories` poll. Best-effort and one-shot; every other part
+> of this design is unchanged. See
+> [LLP 0069 §trigger, the follow-up note](./0069-local-only-dir-selection.spec.md#trigger).
+
 ## CLI: the durable authoring path {#cli}
 
 `hyp ignore` / `hyp unignore` / `hyp ignore --check`

src/core/cli/remote_commands.js

@@ -16,9 +16,11 @@ import {
   writeSession,
   writeToken,
 } from '../remote/credentials.js'
+import { Attr, getLogger } from '../observability/index.js'
 import { readCentralSinkOrigins, seedLoginGateway } from '../remote/gateway_seed.js'
+import { bootKernel } from '../runtime/boot.js'
 import { enrollCentralSink } from '../commands/central.js'
-import { listCapturedDirectories, runLocalOnlyPicker } from '../commands/local_only.js'
+import { CAPTURE_DATASET, listCapturedDirectories, runLocalOnlyPicker } from '../commands/local_only.js'
 import { originOf } from '../remote/gateway_seed.js'
 import { isTty, readAllStdin } from './stdio.js'
 import { isPlainObject } from '../util/json_util.js'
@@ -135,7 +137,11 @@ export const CAPTURE_WAIT_DEFAULT_MS = 30000
  * picker uses (`listCapturedDirectories`, R2 - local cache only, never the remote).
  *
  * A `null` result means enumeration cannot run at all (no query engine, or an
- * engine error): stop immediately and let the picker take its skip path. Only a
+ * engine error): stop immediately and let the picker take its skip path. On a
+ * genuinely fresh enroll the boot-snapshot registry is such an engine (the
+ * dataset registers only after the org config pull), so the caller first
+ * refreshes it via `freshenCaptureEnumeration` and passes the fresh
+ * `enumerate` in here rather than polling a query that can never run. Only a
  * valid-but-empty list means "backfill may still be landing", so keep polling
  * until the budget expires. Timing out returns the last (empty) result, and the
  * picker then shows the durable-command hint. Never throws and never blocks past
@@ -168,6 +174,94 @@ export async function waitForCapturedDirectories({ ctx, timeoutMs = CAPTURE_WAIT
   }
 }
 
+/**
+ * Rebuild a query context that can actually run the picker's candidate
+ * enumeration on a genuinely fresh enroll (issue #281 follow-up).
+ *
+ * `hyp remote login` boots its kernel at dispatch time, before enrollment. On
+ * a first-run box the local config names no plugins, so the boot snapshot in
+ * `ctx.query` never registers the dataset the enumeration reads - that
+ * registration arrives with `@hypaware/ai-gateway`, which the org
+ * config-control pull enables only after `enrollCentralSink` installs the
+ * daemon. Enumerating through the stale snapshot fails ("unknown dataset" -
+ * null), which `waitForCapturedDirectories` correctly reads as "enumeration
+ * cannot run, stop now": the picker silently skipped on exactly the fresh
+ * enroll it exists for, even after the #281 reordering.
+ *
+ * The attach that gates the capture wait is also what makes one re-boot
+ * sufficient: attach markers are written by the reconciler that runs only
+ * after a confirmed config apply, so a successful `waitForClientAttach` means
+ * the pulled central layer is on disk - and the attach handler requires the
+ * gateway capability, so that layer enables the plugin. Booting one fresh
+ * kernel here (config profile, the same layered resolution any subsequent
+ * `hyp` command runs) yields a registry with the dataset; re-resolving per
+ * poll tick would re-pay plugin discovery every second for nothing.
+ *
+ * Resolves to null whenever the caller should keep polling through its boot
+ * snapshot: the snapshot already has the dataset (the populated-box re-login
+ * case - no second boot is paid), the re-boot fails, or the merged config
+ * still lacks the plugin. Best-effort throughout: never throws, so a broken
+ * refresh can never break the login it refines (LLP 0072). Callers must
+ * `dispose()` a non-null handle - plugins may start sources during
+ * activation, and a live source handle would keep the login process alive
+ * after it prints its result.
+ *
+ * @param {{
+ *   ctx: Pick<CommandRunContext, 'query' | 'storage' | 'config' | 'env'>,
+ *   boot?: typeof bootKernel,
+ * }} args
+ * @returns {Promise<{ enumerate: () => Promise<any[] | null>, dispose: () => Promise<void> } | null>}
+ * @ref LLP 0069#enumerate [constrained-by]: the enumeration needs a registry that knows the dataset; on a fresh enroll only a post-attach re-boot has one
+ */
+export async function freshenCaptureEnumeration({ ctx, boot = bootKernel }) {
+  try {
+    if (ctx.query && ctx.query.getDataset(CAPTURE_DATASET)) return null
+    const fresh = await boot({
+      hypHome: readObservabilityEnv(ctx.env).hypHome,
+      mode: 'cli',
+      bootProfile: 'config',
+      env: ctx.env,
+    })
+    const runtime = fresh.runtime
+    const dispose = async () => {
+      try {
+        await runtime.sources.stopAll()
+      } catch {
+        // Best-effort, mirroring dispatch's own boot-source cleanup: a stop
+        // failure is not actionable from the login path.
+      }
+    }
+    const registered = !!runtime.query.getDataset(CAPTURE_DATASET)
+    getLogger('remote-login').info('local_only.capture_registry_refresh', {
+      [Attr.COMPONENT]: 'cmd-remote-login',
+      [Attr.OPERATION]: 'local_only.capture_registry_refresh',
+      status: registered ? 'ok' : 'failed',
+      ...(registered ? {} : { [Attr.ERROR_KIND]: 'dataset_still_unregistered' }),
+    })
+    if (!registered) {
+      await dispose()
+      return null
+    }
+    return {
+      enumerate: () => listCapturedDirectories({
+        query: runtime.query,
+        storage: runtime.storage,
+        config: fresh.config ?? ctx.config,
+      }),
+      dispose,
+    }
+  } catch (err) {
+    getLogger('remote-login').info('local_only.capture_registry_refresh', {
+      [Attr.COMPONENT]: 'cmd-remote-login',
+      [Attr.OPERATION]: 'local_only.capture_registry_refresh',
+      status: 'failed',
+      [Attr.ERROR_KIND]: 'boot_failed',
+      error_message: err instanceof Error ? err.message : String(err),
+    })
+    return null
+  }
+}
+
 /**
  * Run the local-only directory picker as a best-effort refinement of an
  * enrolling login. A non-cancellation failure (e.g. a corrupt existing list) is
@@ -248,7 +342,7 @@ export async function runRemoteAdd(argv, ctx) {
  *
  * @param {string[]} argv
  * @param {CommandRunContext} ctx
- * @param {{ login?: typeof loginWithBrowser, seed?: typeof seedLoginGateway, picker?: typeof runLocalOnlyPicker, enroll?: typeof enrollCentralSink, waitForAttach?: typeof waitForClientAttach, waitForCaptured?: typeof waitForCapturedDirectories }} [deps] test seam for the browser flow, gateway seeding, the local-only picker, central-sink enrollment, the post-enroll attach wait, and the post-backfill captured-directory wait
+ * @param {{ login?: typeof loginWithBrowser, seed?: typeof seedLoginGateway, picker?: typeof runLocalOnlyPicker, enroll?: typeof enrollCentralSink, waitForAttach?: typeof waitForClientAttach, waitForCaptured?: typeof waitForCapturedDirectories, freshen?: typeof freshenCaptureEnumeration }} [deps] test seam for the browser flow, gateway seeding, the local-only picker, central-sink enrollment, the post-enroll attach wait, the post-backfill captured-directory wait, and the fresh-enroll registry refresh
  * @ref LLP 0058#d1 [implements]: browser mode of `hyp remote login`; one command, one store, one more way to populate it
  */
 export async function runRemoteLogin(argv, ctx, deps = {}) {
@@ -313,6 +407,7 @@ export async function runRemoteLogin(argv, ctx, deps = {}) {
     enroll: deps.enroll ?? enrollCentralSink,
     waitForAttach: deps.waitForAttach ?? waitForClientAttach,
     waitForCaptured: deps.waitForCaptured ?? waitForCapturedDirectories,
+    freshen: deps.freshen ?? freshenCaptureEnumeration,
   })
 }
 
@@ -445,10 +540,10 @@ async function persistStaticToken(name, token, ctx) {
  * @param {string} name
  * @param {{ org?: string, host?: string, noBrowser: boolean, noForward: boolean, noDaemon: boolean }} opts
  * @param {CommandRunContext} ctx
- * @param {{ login: typeof loginWithBrowser, seed: typeof seedLoginGateway, picker: typeof runLocalOnlyPicker, enroll: typeof enrollCentralSink, waitForAttach: typeof waitForClientAttach, waitForCaptured: typeof waitForCapturedDirectories }} deps
+ * @param {{ login: typeof loginWithBrowser, seed: typeof seedLoginGateway, picker: typeof runLocalOnlyPicker, enroll: typeof enrollCentralSink, waitForAttach: typeof waitForClientAttach, waitForCaptured: typeof waitForCapturedDirectories, freshen: typeof freshenCaptureEnumeration }} deps
  * @returns {Promise<number>}
  */
-async function runBrowserLogin(name, { org, host, noBrowser, noForward, noDaemon }, ctx, { login, seed, picker, enroll, waitForAttach, waitForCaptured }) {
+async function runBrowserLogin(name, { org, host, noBrowser, noForward, noDaemon }, ctx, { login, seed, picker, enroll, waitForAttach, waitForCaptured, freshen }) {
   const remotes = await readConfiguredRemotes(ctx)
   const entry = remotes[name]
   if (!entry) {
@@ -661,8 +756,19 @@ async function runBrowserLogin(name, { org, host, noBrowser, noForward, noDaemon
     // runs and takes its own durable-hint path immediately.
     const canPromptPicker = isTty(ctx.stdin ?? process.stdin) && isTty(ctx.stderr)
     if (attached.length > 0 && canPromptPicker) {
-      const captured = await waitForCaptured({ ctx })
-      await refineLocalOnly({ ctx, stateDir, picker, listCandidates: () => Promise.resolve(captured) })
+      // On a first-run box the boot snapshot in ctx.query predates the org
+      // config pull that registers the dataset the enumeration reads, so the
+      // capture wait would stop on its first "unknown dataset" failure and
+      // the picker would silently skip (issue #281 follow-up). Refresh the
+      // registry once (best-effort; null keeps the snapshot) so the poll can
+      // actually see the backfill land, then poll and pick as before.
+      const freshened = await freshen({ ctx })
+      try {
+        const captured = await waitForCaptured(freshened ? { ctx, enumerate: freshened.enumerate } : { ctx })
+        await refineLocalOnly({ ctx, stateDir, picker, listCandidates: () => Promise.resolve(captured) })
+      } finally {
+        if (freshened) await freshened.dispose()
+      }
     } else {
       await refineLocalOnly({ ctx, stateDir, picker })
     }

src/core/commands/local_only.js

@@ -27,8 +27,13 @@ const MAX_SHOWN_CANDIDATES = 50
 // discoverable even when the interactive step is skipped (LLP 0072 #tty).
 const DURABLE_HINT = "tip: mark a directory local-only anytime with 'hyp ignore --local-only [path]'\n"
 
+// The dataset the candidate enumeration reads. Exported so the login flow
+// can ask "can this kernel snapshot run the enumeration at all?" against the
+// query registry (remote_commands.js) without the name drifting from the SQL.
+export const CAPTURE_DATASET = 'ai_gateway_messages'
+
 const ENUMERATE_SQL = `SELECT cwd, repo_root, COUNT(*) AS rows, MAX(date) AS last_seen ` +
-  `FROM ai_gateway_messages WHERE cwd IS NOT NULL GROUP BY cwd, repo_root ORDER BY last_seen DESC`
+  `FROM ${CAPTURE_DATASET} WHERE cwd IS NOT NULL GROUP BY cwd, repo_root ORDER BY last_seen DESC`
 
 /**
  * Enumerate the distinct working directories the user has captured