@nuucognition/flint-cli 0.6.0-dev.20 → 0.6.0-dev.21

package/README.md

@@ -154,6 +154,23 @@ flint open my-project         # Open by name from registry
 
 **Dev-only:** use the `flint-dev` binary or a source build with no baked `BUILD_MODE`.
 
+### Development builds and atomic live releases
+
+Flint has separate development and live runtime channels:
+
+- `ndv use flint dev` activates `bin/flint-dev.js`. It consumes the checkout's
+  `apps/flint-cli/dist`, so `ndv build flint dev` is visible on the next
+  invocation. Orbh children spawned from this channel remain on the caller's
+  checkout.
+- `bin/flint.js` is the canonical live launcher used by Orbh-managed release
+  flows. When `.flint-live-build/current` is complete, it consumes that
+  atomically selected release rather than an in-place checkout build.
+- `bin/flint-prod.js` consumes the `dist` shipped inside its installed package.
+
+The channels are intentionally distinct: NDV owns checkout development, while
+the declared `[live-build]` command stages and smoke-tests long-running Orbh
+releases before cutover.
+
 **Behavior:**
 - Opens the flint in all apps configured in the current profile config
 - Default (no config): opens in Obsidian only

package/bin/flint-dev.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+
+import { launchFlint } from './launch-flint.js';
+
+// A dev activation is an explicit choice to keep the spawned Orbh process tree
+// on the caller's checkout instead of silently switching detached auxiliaries
+// back to the machine-canonical live launcher.
+process.env.ORBH_AUX_CODE_SOURCE = 'caller';
+
+await launchFlint({
+  launcherPath: fileURLToPath(import.meta.url),
+  preferLiveBuild: false,
+});

package/bin/flint-prod.js

@@ -30,6 +30,13 @@ if (openTuiRequested && ffiSupported
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const entrypoint = join(__dirname, '..', 'dist', 'index.js');
+
+// Default to production React — see bin/flint.js. The bundled react-reconciler
+// is baked to production at build time, but `react` stays external; with
+// NODE_ENV unset it loads its development build, whose jsx runtime calls
+// dev-only dispatcher methods the production reconciler never installs
+// ("dispatcher.getOwner is not a function" on first TUI render).
+process.env.NODE_ENV ||= 'production';
 process.env.FLINT_CLI_LAUNCHER ??= fileURLToPath(import.meta.url);
 process.env.FLINT_CLI_ENTRYPOINT ??= entrypoint;
 await import(pathToFileURL(entrypoint).href);

package/bin/flint.js

@@ -1,90 +1,10 @@
 #!/usr/bin/env node
 
-import { existsSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { resolveLiveBuildPackageRoot } from './live-build-path.js';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const sourcePackageRoot = join(__dirname, '..');
-const runtimePackageRoot = resolveLiveBuildPackageRoot(sourcePackageRoot);
-const openTuiInvocationEntry = join(runtimePackageRoot, 'dist', 'open-tui-invocation.js');
-const { shouldEnableOpenTuiFfi } = await import(openTuiInvocationEntry);
+import { launchFlint } from './launch-flint.js';
 
-const openTuiRequested = shouldEnableOpenTuiFfi({
-  cli: 'flint',
-  args: process.argv.slice(2),
-  envRenderer: process.env.ORBH_TUI_RENDERER,
-  envNoChrome: process.env.ORBH_NO_CHROME,
-  stdinTty: Boolean(process.stdin.isTTY),
-  stdoutTty: Boolean(process.stdout.isTTY),
+await launchFlint({
+  launcherPath: fileURLToPath(import.meta.url),
+  preferLiveBuild: true,
 });
-const [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split('.').map(Number);
-const ffiSupported = nodeMajor > 26 || (nodeMajor === 26 && nodeMinor >= 1);
-const ffiFlag = '--experimental-ffi';
-if (openTuiRequested && ffiSupported
-  && !process.execArgv.includes(ffiFlag)
-  && !process.env.NODE_OPTIONS?.split(/\s+/).includes(ffiFlag)
-  && process.execve) {
-  const options = new Set(process.env.NODE_OPTIONS?.split(/\s+/).filter(Boolean) ?? []);
-  for (const option of [ffiFlag, '--disable-warning=ExperimentalWarning', '--disable-warning=DEP0205']) options.add(option);
-  process.execve(process.execPath, process.argv, {
-    ...process.env,
-    NODE_OPTIONS: [...options].join(' '),
-    ORBH_TUI_FFI_REEXEC: '1',
-  });
-}
-
-const srcEntry = join(__dirname, '..', 'src', 'index.ts');
-const distEntry = join(runtimePackageRoot, 'dist', 'index.js');
-
-// Default to production React/ink. Unset NODE_ENV loads react-reconciler's
-// development build, whose per-render performance.measure() calls accumulate
-// forever in Node's perf buffer — a ~1GB/hour leak in long-lived interactive
-// views like `orbh list`. Explicit NODE_ENV=development still wins.
-process.env.NODE_ENV ||= 'production';
-
-// Performance: prefer the built dist and run it IN-PROCESS (one node process,
-// no tsx, no recompile-on-every-invocation). `flint orbh i` previously spawned
-// `node bin/flint.js` -> `tsx` -> `tsx loader (compiling src/index.ts)` -> agent,
-// i.e. 3 node processes + a TypeScript compile per launch. Running the prebuilt
-// dist in-process collapses that to a single node process with zero compile cost.
-// Set FLINT_CLI_FORCE_SOURCE=1 to fall back to running the TypeScript source via
-// tsx (the dev workflow where you edit src/ without rebuilding).
-const forceSource =
-  process.env.FLINT_CLI_FORCE_SOURCE === '1' ||
-  process.env.FLINT_CLI_FORCE_SOURCE === 'true';
-
-if (!forceSource && existsSync(distEntry)) {
-  process.env.FLINT_CLI_LAUNCHER = fileURLToPath(import.meta.url);
-  process.env.FLINT_CLI_ENTRYPOINT = distEntry;
-  // The dist entry parses process.argv and runs the CLI on import. Awaiting keeps
-  // the launcher process alive for the CLI's async work (incl. interactive `orbh i`,
-  // which blocks on the child process's exit event — no polling, no extra wrapper).
-  await import(distEntry);
-} else {
-  // Dev fallback: run the TypeScript source via tsx in a subprocess.
-  const tsxPath = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
-
-  // tsx still calls the deprecated module.register(); Node 26 turned DEP0205 into a
-  // runtime warning. Disable it just for the spawned subprocess, preserving any
-  // NODE_OPTIONS the user already set. Remove once tsx migrates to module.registerHooks().
-  const SUPPRESS_FLAG = '--disable-warning=DEP0205';
-  const existingNodeOptions = process.env.NODE_OPTIONS ?? '';
-  const nodeOptions = existingNodeOptions.includes(SUPPRESS_FLAG)
-    ? existingNodeOptions
-    : (existingNodeOptions ? `${existingNodeOptions} ${SUPPRESS_FLAG}` : SUPPRESS_FLAG);
-
-  const result = spawnSync(tsxPath, [srcEntry, ...process.argv.slice(2)], {
-    stdio: 'inherit',
-    env: {
-      ...process.env,
-      NODE_OPTIONS: nodeOptions,
-      FLINT_CLI_LAUNCHER: fileURLToPath(import.meta.url),
-      FLINT_CLI_ENTRYPOINT: srcEntry,
-    },
-  });
-
-  process.exit(result.status ?? 0);
-}

package/bin/launch-flint.js

@@ -0,0 +1,93 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveLiveBuildPackageRoot } from './live-build-path.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourcePackageRoot = join(__dirname, '..');
+
+/**
+ * Run Flint through an explicit runtime channel.
+ *
+ * NDV dev launchers consume the checkout build. Canonical live launchers prefer
+ * the atomically selected release. Keeping this decision in the entrypoint
+ * avoids an inherited environment variable silently changing channels.
+ */
+export async function launchFlint({ launcherPath, preferLiveBuild }) {
+  const runtimePackageRoot = resolveLiveBuildPackageRoot(sourcePackageRoot, { preferLiveBuild });
+  const openTuiInvocationEntry = join(runtimePackageRoot, 'dist', 'open-tui-invocation.js');
+  const { shouldEnableOpenTuiFfi } = await import(openTuiInvocationEntry);
+
+  const openTuiRequested = shouldEnableOpenTuiFfi({
+    cli: 'flint',
+    args: process.argv.slice(2),
+    envRenderer: process.env.ORBH_TUI_RENDERER,
+    envNoChrome: process.env.ORBH_NO_CHROME,
+    stdinTty: Boolean(process.stdin.isTTY),
+    stdoutTty: Boolean(process.stdout.isTTY),
+  });
+  const [nodeMajor = 0, nodeMinor = 0] = process.versions.node.split('.').map(Number);
+  const ffiSupported = nodeMajor > 26 || (nodeMajor === 26 && nodeMinor >= 1);
+  const ffiFlag = '--experimental-ffi';
+  if (openTuiRequested && ffiSupported
+    && !process.execArgv.includes(ffiFlag)
+    && !process.env.NODE_OPTIONS?.split(/\s+/).includes(ffiFlag)
+    && process.execve) {
+    const options = new Set(process.env.NODE_OPTIONS?.split(/\s+/).filter(Boolean) ?? []);
+    for (const option of [ffiFlag, '--disable-warning=ExperimentalWarning', '--disable-warning=DEP0205']) options.add(option);
+    process.execve(process.execPath, process.argv, {
+      ...process.env,
+      NODE_OPTIONS: [...options].join(' '),
+      ORBH_TUI_FFI_REEXEC: '1',
+    });
+  }
+
+  const srcEntry = join(sourcePackageRoot, 'src', 'index.ts');
+  const distEntry = join(runtimePackageRoot, 'dist', 'index.js');
+
+  // Default to production React/ink. Unset NODE_ENV loads react-reconciler's
+  // development build, whose per-render performance.measure() calls accumulate
+  // forever in Node's perf buffer — a ~1GB/hour leak in long-lived interactive
+  // views like `orbh list`. Explicit NODE_ENV=development still wins.
+  process.env.NODE_ENV ||= 'production';
+
+  // Performance: prefer the built dist and run it IN-PROCESS (one node process,
+  // no tsx, no recompile-on-every-invocation). Set FLINT_CLI_FORCE_SOURCE=1 to
+  // fall back to the checkout TypeScript source via tsx.
+  const forceSource =
+    process.env.FLINT_CLI_FORCE_SOURCE === '1' ||
+    process.env.FLINT_CLI_FORCE_SOURCE === 'true';
+
+  if (!forceSource && existsSync(distEntry)) {
+    process.env.FLINT_CLI_LAUNCHER = launcherPath;
+    process.env.FLINT_CLI_ENTRYPOINT = distEntry;
+    // The dist entry parses process.argv and runs the CLI on import. Awaiting
+    // keeps the launcher process alive for async work such as `flint orbh i`.
+    await import(distEntry);
+    return;
+  }
+
+  const tsxPath = join(sourcePackageRoot, 'node_modules', '.bin', 'tsx');
+
+  // tsx still calls deprecated module.register(); Node 26 turned DEP0205 into a
+  // runtime warning. Disable it just for the source subprocess.
+  const suppressFlag = '--disable-warning=DEP0205';
+  const existingNodeOptions = process.env.NODE_OPTIONS ?? '';
+  const nodeOptions = existingNodeOptions.includes(suppressFlag)
+    ? existingNodeOptions
+    : (existingNodeOptions ? `${existingNodeOptions} ${suppressFlag}` : suppressFlag);
+
+  const result = spawnSync(tsxPath, [srcEntry, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      NODE_OPTIONS: nodeOptions,
+      FLINT_CLI_LAUNCHER: launcherPath,
+      FLINT_CLI_ENTRYPOINT: srcEntry,
+    },
+  });
+
+  process.exit(result.status ?? 0);
+}

package/bin/live-build-path.js

@@ -10,7 +10,8 @@ const hasCompleteDist = (packageRoot) =>
  * inside a deployed/npm package has no checkout-level pointer and uses its own
  * dist directory instead.
  */
-export function resolveLiveBuildPackageRoot(sourcePackageRoot) {
+export function resolveLiveBuildPackageRoot(sourcePackageRoot, { preferLiveBuild = true } = {}) {
+  if (!preferLiveBuild) return sourcePackageRoot;
   const checkoutRoot = resolve(sourcePackageRoot, '..', '..');
   const currentRelease = join(checkoutRoot, '.flint-live-build', 'current');
 

package/dist/_flint/prompts/flint-interactive.md

@@ -36,9 +36,9 @@ Orbh is a **meta-harness**: a session layer that launches, tracks, supervises, a
 
 **Lifecycle.** `workState` is `working | needs-input | awaiting | finished | abandoned`. Headless/subagent turns end with `return --finish` (done; default) or `return --await` (dormant, expecting further interaction). Await still delivers that turn's result immediately — collectors resolve on the correlated result, not process state. An exit without return is re-prompted at most twice, then `failed-unreturned` and the session becomes awaiting (recoverable); `abandoned` is for kill/discard/operator verdicts, not a clean silent exit. Interactive sessions never declare their own activity: the launcher's PTY wrapper watches the harness title spinner and derives observed activity (busy/idle), which overrides declared state — spinner running reads as `working`, sitting at the prompt reads as `needs-input`.
 
-**Delivery.** Unattended (headless/subagent/peer) sessions carry a detached **persistent waiter** for the session lifetime; `page arm` is a one-shot **attach** for mid-turn latency, and awaiting sessions wake on page-worthy events with a coalesced digest. Interactive sessions keep a run-scoped pager (`page arm` re-arm) — not a session-lifetime waiter. Plain `park` is the legacy spelling of await; `message --wake` is unnecessary for awaiting targets (`--revive` still resumes an ended one). **Liveness notices**: when a counterparty you wait on (a `message request` target or a dispatched subagent) exits, fails to return, blocks on human input, or is killed, a typed NOTICES entry reaches you (digest, pager render, or Page) with a reason, trust grade, and guidance — follow it; `killed` means deliberately cancelled: do NOT re-send or spawn a replacement.
+**Delivery.** The machine-wide Orbh orchestrator sweep owns wake delivery for unattended (headless/subagent/peer) sessions across turns; `page arm` is an optional one-shot surface for mid-turn latency, and awaiting sessions wake on page-worthy events with a coalesced digest. Interactive sessions keep a run-scoped pager (`page arm` re-arm). Plain `park` is the legacy spelling of await; `message --wake` is unnecessary for awaiting targets (`--revive` still resumes an ended one). **Liveness notices**: when a counterparty you wait on (a `message request` target or a dispatched subagent) exits, fails to return, blocks on human input, or is killed, a typed NOTICES entry reaches you (digest, pager render, or Page) with a reason, trust grade, and guidance — follow it; `killed` means deliberately cancelled: do NOT re-send or spawn a replacement.
 
-**The orchestrator.** A per-machine supervisor repairs persistent waiters, reaps un-returned turns, enforces job timeouts, and resumes awaiting sessions. You never manage it; it manages you.
+**The orchestrator.** A per-machine supervisor runs the generalized awaiting-wake sweep, reaps un-returned turns, enforces job timeouts, and resumes awaiting sessions. You never manage it; it manages you.
 
 **Surfaces.** Operators see sessions through `flint orbh list` / `inspect` / `watch`, terminal pane titles, and the NUU Orbit dashboard — all keyed on title and description. Your title is effectively a broadcast channel.
 
@@ -46,7 +46,7 @@ Orbh is a **meta-harness**: a session layer that launches, tracks, supervises, a
 
 ## Interactive self-compaction at 80% context
 
-The Page `CONTEXT` line is the source of truth for context occupancy. At or above 80%: pack what the successor context needs into interface keys and your final words, then run `flint orbh session compact`. It is a **turn-ending verb** — the pane manager ends this context immediately, shows "compacting…", distills the transcript, and relaunches a fresh run of the **same session** in the same pane. Do not plan work after it; there is no after. The relaunched context wakes from the distilled handoff and continues this session's identity.
+The Page `CONTEXT` line is the source of truth for context occupancy. At or above 80% you write your own handoff — there is no distiller. Compaction is **three verbs**. (1) `flint orbh compact start` prints the handoff contract, the exact path in this session's `scratch/` to write it to, and your live Page (write OPEN OBLIGATIONS from that durable state, not from memory). It records no compaction intent and kills nothing — it holds the pager and marks this session **`[Compacting...]`** on every title surface (this pane's title, `orbh list`, the cockpit, Orbit) so the human watching knows the session is not doing their work right now. Write the handoff to that path with your own tools. (2) `flint orbh compact handoff` is the **turn-ending verb**: it validates the handoff while you are still alive, the pane manager ends this context immediately, and a fresh run of the **same session** relaunches in the same pane pointed at what you wrote. Do not plan work after it; there is no after. (3) `flint orbh compact finish` is run **by that fresh context**, not by you — once it has read the handoff and every path in its FILES list, it runs `finish` to clear `[Compacting...]` and release the pager hold — the normal release, so the marker honestly covers the successor's bootstrap too. A refusal at any step (a missing or malformed handoff, a dispatch claim whose child has not materialized) leaves your context alive — fix it and retry; materialized in-flight dispatches never refuse, they are detached and inherited by the successor as durable obligations. `flint orbh compact abort` releases the hold and clears the marker if you decide not to compact after all, and so does any other turn-ending verb — ending the turn before handoff releases them too.
 
 ## Register: title + description
 
@@ -84,7 +84,10 @@ As part of bootstrap, arm your session pager: run `flint orbh page arm` with you
 
 Rooms are durable shared coordination channels with a message stream and a context library. If a manager tells you to join a room first, run `flint orbh room join <room>`, announce yourself with `flint orbh room post <room> "<text>"`, and read `flint orbh room read <room> --since-cursor`; check shared context with `flint orbh room context show <room>` before starting work. Use `room context append` or `room context edit --search "<old>" --replace "<new>"` only for deliberate shared-context updates.
 
+<!-- Improvement intake disabled 2026-07-27: the improve loop is not working well enough to
+     advertise to every session. Restore this paragraph when the intake path is reliable again.
 Any session may file harness bugs or Orbh improvement requests in the well-known `orbh-improvements` room (no join needed); start the envelope with `[improve] category=bug|improvement | reporter=<session-id> | title=<short title>`. Use `flint orbh improve "<description>" --title "<short title>"` as the convenience command.
+-->
 
 ## Dispatching subagents
 

package/dist/_orbh/prompts/harness/claude.md

@@ -6,19 +6,27 @@ variables: {}
 
 ## Claude Code Orbh Behavior
 
-Your Bash tool supports `run_in_background: true` — that is the native background execution the dispatch pattern asks for. Run blocking Orbh commands (`request -q`, `wait`, `job wait`) as background tasks: they survive foreground tool-call timeouts, keep running across turns, and you are notified when they exit. Do not poll a background dispatch in a loop; continue other work and collect the output when the completion notification arrives.
+Your Bash tool supports `run_in_background: true` — that is the native background execution the dispatch pattern asks for. Run blocking Orbh commands (`request -q`, `wait`, `job wait`) as background tasks: they survive foreground tool-call timeouts, and while this turn is still running you are notified when they exit. Do not poll a background dispatch in a loop; continue other work and collect the output when the completion notification arrives.
 
-### Attach to your waiter
+**A background task belongs to this run's process, not to your session.** Its completion notification can only re-invoke you inside the turn that started it. When the turn ends the task is killed with the process, and the next turn opens with an `__orphan_summary__ … stopped` notice where its output should have been. What it was waiting on — the child session, the job, the peer request — is durable and keeps going; only your local waiter dies. So a backgrounded wait is never a reason to end a turn. If you have nothing left to do in this turn, that is exactly the moment to `return --await`: the orchestrator then wakes you as a NEW turn when the thing lands, and it is the only mechanism that can.
 
-For lowest-latency delivery during a live turn, run `flint orbh page arm` with `run_in_background: true`. This is a thin attach to the session's persistent waiter. It exits with a full Page render when a message, job completion, request, room event, or other page-worthy event arrives, and Claude surfaces that output as a background-task notification. The attach is one-shot: attach again after delivery when low latency still matters. A missed re-attach only delays durable events until your next turn boundary. If it prints `session ended — pager exiting`, or you are about to return, do not attach again.
+### Your last action in every turn is `return`
+
+Every turn ends with a `flint orbh session return --finish` or `--await` Bash call — a fresh dispatch, a checkpoint continuation, and a ten-second wake turn that did nothing but read a digest, all alike. A closing assistant message is not a turn ending: Orbh never sees it, the run is recorded `exit-zero` with no result, and the bounded re-prompt that repairs it costs minutes of dead time. Before you write a status summary, check whether `return` has already run this turn; if it has not, that summary IS the return payload, so put it in the command instead of in the message.
+
+The failure has one recognisable shape, and it is always the same sentence: "dispatched — waiting for the results", "pager re-armed, idling until the verdicts land". Whenever you catch yourself about to say you are waiting, waiting is the disposition — `return --await` and say it there.
+
+### Arm the pager
+
+For lowest-latency delivery during a live turn, run `flint orbh page arm` with `run_in_background: true`. It is an optional one-shot delivery surface that exits with a full Page render when a message, job completion, request, room event, or other page-worthy event arrives, and Claude surfaces that output as a background-task notification. Re-arm after delivery when low latency still matters. A missed re-arm only delays durable events until your next turn boundary. If it prints `session ended — pager exiting`, or you are about to return, do not arm again.
 
 ### Self-pacing in headless runs
 
-In a headless/subagent run your process exits when the turn ends — harness self-pacing tools that schedule a future wake-up for THIS process (ScheduleWakeup, /loop-style timers) cannot fire after that exit and will strand the run as an un-returned turn. To pause until something happens, `return --await` (optionally `--until-group <g>`): your persistent waiter wakes the session with a digest as a NEW turn. Awaiting is the only headless self-pacing primitive.
+In a headless/subagent run your process exits when the turn ends — anything that would re-invoke THIS process later (ScheduleWakeup, /loop-style timers, an outstanding background-task completion) cannot fire after that exit and will strand the run as an un-returned turn. Being woken mid-turn by a background task earlier in the same turn is not evidence to the contrary: that notification only reached you because the turn was still alive. To pause until something happens, `return --await` (optionally `--until-group <g>`): the Orbh orchestrator sweep wakes the session with a digest as a NEW turn. Awaiting is the only headless self-pacing primitive.
 
 ### Talking to other sessions
 
-Discover who is running with `flint orbh active` (titles, descriptions, phase/progress — write your own `register` description knowing peers read it there). `message send <id> "<text>"` is fire-and-forget; any message wakes an awaiting target, so `--wake` is unnecessary there, while `--revive` explicitly resumes an ended target. When you need an answer before proceeding, use a blocking peer request: run `flint orbh message request <id> "<question>"` with `run_in_background: true` and continue working — the answer arrives as a background-task notification. When your own Page shows a `↳ REQUEST` line, answer it promptly with the exact `flint orbh message respond <requestId> "<answer>"` command it displays (or cancel yours with `message request --cancel <requestId>`).
+Discover who is running with `flint orbh active` (titles, descriptions, phase/progress — write your own `register` description knowing peers read it there). `message send <id> "<text>"` is fire-and-forget; any message wakes an awaiting target, so `--wake` is unnecessary there, while `--revive` explicitly resumes an ended target. When you need an answer before proceeding, use a blocking peer request: run `flint orbh message request <id> "<question>"` with `run_in_background: true` and continue working — the answer arrives as a background-task notification while this turn lasts, and if you run out of other work before it does, `return --await` rather than ending the turn on it. When your own Page shows a `↳ REQUEST` line, answer it promptly with the exact `flint orbh message respond <requestId> "<answer>"` command it displays (or cancel yours with `message request --cancel <requestId>`).
 
 ### Rooms
 

package/dist/_orbh/prompts/harness/codex.md

@@ -12,6 +12,6 @@ variables:
 
 Use shell commands for the entire Orbh lifecycle. For blocking dispatches (`request -q`, `wait`), use your background execution facility if this environment provides one; otherwise dispatch through a detached Orbh job (`flint orbh job run --agent <runtime/profile> "<prompt>"`) and collect with `flint orbh job result <id>` — never let a blocking dispatch ride on a foreground shell call that can time out.
 
-When low-latency mid-turn delivery matters, run `flint orbh page arm` with your background execution facility. It attaches to the persistent waiter for one delivery. Attach again after it fires if low latency still matters; otherwise events arrive at the next turn boundary.
+When low-latency mid-turn delivery matters, run `flint orbh page arm` with your background execution facility. It is an optional one-shot delivery surface. Re-arm after it fires if low latency still matters; otherwise events arrive at the next turn boundary.
 
 {{#if canContactHuman}}When you need human input while staying in the same turn, call `flint orbh session ask "<question>"` and use the command output as the answer. When your operator channel is asynchronous, call `flint orbh request "$ORBH_SESSION_ID" "<question>"`, then end the turn with `flint orbh session return --await "<status and pending question>"`. A later response wakes the awaiting session. Inspect it with `flint orbh requests "$ORBH_SESSION_ID"`, continue the work, and end that turn with an explicit return disposition.{{/if}}

package/dist/_orbh/prompts/harness/droid.md

@@ -6,4 +6,4 @@ variables: {}
 
 ## Droid Orbh Behavior
 
-Run blocking Orbh collectors with Droid's background execution facility so foreground tool-call timeouts do not cancel them. For lowest-latency mid-turn delivery, run `flint orbh page arm` in the background as a one-shot attach to the persistent waiter. Attach again after delivery when latency matters; otherwise events arrive at the next turn boundary.
+Run blocking Orbh collectors with Droid's background execution facility so foreground tool-call timeouts do not cancel them. For lowest-latency mid-turn delivery, run `flint orbh page arm` in the background as an optional one-shot delivery surface. Re-arm after delivery when latency matters; otherwise events arrive at the next turn boundary.

package/dist/_orbh/prompts/harness/opencode.md

@@ -6,4 +6,4 @@ variables: {}
 
 ## OpenCode Orbh Behavior
 
-Run blocking Orbh collectors with OpenCode's background execution facility so foreground tool-call timeouts do not cancel them. For lowest-latency mid-turn delivery, run `flint orbh page arm` in the background as a one-shot attach to the persistent waiter. Attach again after delivery when latency matters; otherwise events arrive at the next turn boundary.
+Run blocking Orbh collectors with OpenCode's background execution facility so foreground tool-call timeouts do not cancel them. For lowest-latency mid-turn delivery, run `flint orbh page arm` in the background as an optional one-shot delivery surface. Re-arm after delivery when latency matters; otherwise events arrive at the next turn boundary.

package/dist/_orbh/prompts/headless.md

@@ -39,19 +39,22 @@ Orbh is a meta-harness: a durable session layer that launches, tracks, supervise
 
 **Modes.** Sessions run interactive `(I)`, headless `(H)` (you), or subagent `(S)`. A subagent has a collector waiting on its result. A peer is a bare headless launch with no collector and a manager-flavored prompt.
 
-**Delivery.** A detached persistent waiter stands for your session's lifetime across turns. While this run is live, `{{commandPath}} page arm` is a thin **attach** to that waiter: keep it attached in your harness's background execution for the lowest-latency mid-run delivery. An attach is one-shot after delivery, so re-attach for the next event. If you do not re-attach, events remain durable and arrive at your next turn boundary. When awaiting, any page-worthy event wakes the session with a coalesced digest.
+**Delivery.** The machine-wide Orbh orchestrator sweep owns unattended wake delivery across turns. While this run is live, `{{commandPath}} page arm` is an optional one-shot surface for the lowest-latency mid-run delivery; re-arm after delivery when latency matters. If you do not re-arm, events remain durable and arrive at your next turn boundary. When awaiting, the orchestrator resumes the session for any page-worthy event with a coalesced digest.
 
 **Collection.** Waiting on a subagent means waiting on the result of the turn you dispatched. Its process state, awaits, resumes, and intermediate turns are not your concern. The collector unblocks when the correlated result exists or an explicit failure outcome occurs.
 
-**Liveness notices.** When a counterparty you are waiting on — a pending `message request` target or a dispatched subagent — exits, fails to return, blocks on human input, or is killed, Orbh delivers a typed NOTICES entry to you (digest, attach render, or `{{commandPath}} page`) carrying a reason, a trust grade (`accurate`/`advisory`), and guidance. Follow the guidance instead of guessing at silence: `awaiting-input` means no nudge will help until a human acts; `killed` means the pending item was deliberately cancelled — do NOT re-send or spawn a replacement.
+**Liveness notices.** When a counterparty you are waiting on — a pending `message request` target or a dispatched subagent — exits, fails to return, blocks on human input, or is killed, Orbh delivers a typed NOTICES entry to you (digest or `{{commandPath}} page`) carrying a reason, a trust grade (`accurate`/`advisory`), and guidance. Follow the guidance instead of guessing at silence: `awaiting-input` means no nudge will help until a human acts; `killed` means the pending item was deliberately cancelled — do NOT re-send or spawn a replacement.
 
-**The orchestrator.** A per-machine supervisor repairs persistent waiters, reaps un-returned turns, enforces job timeouts, and resumes awaiting sessions. You do not manage it.
+**The orchestrator.** A per-machine supervisor runs the generalized awaiting-wake sweep, reaps un-returned turns, enforces job timeouts, and resumes awaiting sessions. You do not manage it.
 
 **Surfaces.** Operators see sessions through `{{commandPath}} list`, `inspect`, `watch`, and dashboards. Keep title and description accurate. Your `return` payload is what your consumer reads.
 
 Available coordination surfaces include `request`/`wait`/`result`, `active`, messages, blocking peer requests, rooms, background jobs and group barriers, the Page (`{{commandPath}} page`), human-input requests, profiles, and session bundles. Plain `park` is the legacy spelling of await; `message --wake` is unnecessary for awaiting targets.
 
+<!-- Improvement intake disabled 2026-07-27: the improve loop is not working well enough to
+     advertise to every session. Restore this paragraph when the intake path is reliable again.
 Any session may file harness bugs or Orbh improvement requests in the well-known `orbh-improvements` room (no join needed); start the envelope with `[improve] category=bug|improvement | reporter=<session-id> | title=<short title>`. Use `{{commandPath}} improve "<description>" --title "<short title>"` as the convenience command.
+-->
 
 ## Register: title + description
 
@@ -73,6 +76,8 @@ Terminal output is not a deliverable. Return the full turn result as markdown:
 Use `--finish` even for partial failure when no further interaction is expected; state what was done, what is missing, and why. Use `--await` only when the await-promise is real.
 `return --await` still delivers this turn's result immediately, so any collector resolves now. Awaiting only keeps the session wakeable for a future turn, and every future turn ends with its own return.
 
+This holds for short turns too. A wake turn that reads a digest, finds the work not ready, and stops on a message saying so has not paused — it has stranded itself, because nothing outside a live turn can re-invoke you except `--await`. Waiting is a disposition: return it.
+
 ## Dispatch subagents and peers
 
 Dispatch collected work as a subagent:
@@ -91,12 +96,13 @@ Your session carries a free-form key/value interface: `{{commandPath}} session s
 
 ## Self-compaction at 80% context
 
-Your context window fills across turns. The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery — is the source of truth for occupancy; do not invent alternate token accounting. An armed pager autofires a hard advisory when occupancy reaches 80%.
+Your context window fills across turns. The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery — is the source of truth for occupancy; do not invent alternate token accounting. An armed pager autofires a hard advisory when occupancy reaches 80%. 80% is guidance, not a gate: nothing in the runtime fires these verbs for you, so treat it as the point by which you should have **started**.
 
-When occupancy is **at or above 80%** (or clearly approaching it on a long turn):
+At or above 80% (or clearly approaching it on a long turn, or whenever an operator asks) you write your own handoff — there is no distiller:
 
-1. Pack everything a successor needs into interface keys and your return payload: planted facts, open threads, dispatches and job groups in flight.
-2. Run `{{commandPath}} session compact --request`.
-3. IMMEDIATELY end the turn with `{{commandPath}} session return --await "<durable state>"`. Do not continue substantive work after requesting — this session identity is about to be succeeded.
+1. `{{commandPath}} compact start` — prints the handoff contract, the exact path in this session's `scratch/` to write it to, and your live Page, so OPEN OBLIGATIONS come from durable state rather than memory. It records nothing and kills nothing; it holds the pager and marks the session `[Compacting...]`.
+2. Write the handoff to that path with your own tools.
+3. `{{commandPath}} compact handoff` — a **turn-ending verb**, sibling of `return`. It validates the handoff while you are still alive, ends this context, and relaunches a fresh run on the **same session id**: inbox, jobs, rooms, stations, scratch, and collector anchors all carry over. Do not plan work after it; there is no after.
+4. `{{commandPath}} compact finish` — run by the **relaunched context**, once it has read the handoff and every path in its FILES list directly (the summary is orientation, not ground truth). It clears `[Compacting...]` and releases the pager hold.
 
-You cannot compact yourself mid-turn. The orchestrator (or an operator running `session compact <id>`) executes compaction, and only on an **awaiting** headless/subagent session with no live dispatches — finish in-flight work to the await boundary first if the gate would refuse. Compaction happens while you are dormant: the predecessor finishes and a **successor session** continues your duty from a distilled bootstrap. If you wake as a successor: the bootstrap is a summary plus a FILES list — read every listed file directly before acting; the summary is orientation, not ground truth.
+Every refusal — a missing or malformed handoff, a dispatch claim whose child has not materialized — leaves your context alive: fix it and retry. Materialized in-flight dispatches do not refuse; they are detached and inherited by the successor as durable obligations. `{{commandPath}} compact abort` backs out before handoff, and any other turn-ending verb releases the hold too.

package/dist/_orbh/prompts/peer.md

@@ -40,7 +40,7 @@ Your run is one **turn**. Every turn ends with an explicit return disposition:
 
 Await is a promise of further interaction. As a peer, default to `--await` while the standing duty, shared coordination, or expected follow-ups remain live. Finish when no further interaction is expected. Exiting without returning gets the turn re-prompted at most twice; after the second failure it becomes `failed-unreturned` and the session becomes awaiting.
 
-A detached persistent waiter stands across every turn. During a live run, `{{commandPath}} page arm` is a thin attach for lowest-latency mid-run delivery. Re-attach after delivery when latency matters; otherwise durable events arrive at your next turn boundary. While awaiting, any page-worthy event resumes you with a coalesced digest.
+The machine-wide Orbh orchestrator sweep owns unattended wake delivery across turns. During a live run, `{{commandPath}} page arm` is an optional one-shot surface for lowest-latency mid-run delivery. Re-arm after delivery when latency matters; otherwise durable events arrive at your next turn boundary. While awaiting, the orchestrator resumes you for any page-worthy event with a coalesced digest.
 
 If a counterparty you wait on (a `message request` target or a dispatched subagent) exits, fails to return, blocks on human input, or is killed, a typed NOTICES entry reaches you with a reason, trust grade, and guidance — follow it; `killed` means deliberately cancelled: do NOT re-send or spawn a replacement.
 
@@ -51,7 +51,10 @@ If a counterparty you wait on (a `message request` target or a dispatched subage
 
 There is no collector for you. Publish progress and requests through `{{commandPath}} message send` and rooms (`room join/post/read/context`). Read the Page at meaningful seams. Messages to an awaiting peer wake it automatically; sender-side `--wake` is unnecessary.
 
+<!-- Improvement intake disabled 2026-07-27: the improve loop is not working well enough to
+     advertise to every session. Restore this paragraph when the intake path is reliable again.
 Any session may file harness bugs or Orbh improvement requests in the well-known `orbh-improvements` room (no join needed); start the envelope with `[improve] category=bug|improvement | reporter=<session-id> | title=<short title>`. Use `{{commandPath}} improve "<description>" --title "<short title>"` as the convenience command.
+-->
 
 You may dispatch collected subagents with `{{commandPath}} request -q <runtime/profile> '<complete prompt>'`. Run the blocking collector with your harness's native background execution. Waiting means waiting on the subagent's correlated result, not its process state. Subagents may recurse; depth and fan-out are capped.
 
@@ -61,4 +64,4 @@ Your session also exposes `{{commandPath}} session set/get` for workspace-define
 
 ## Self-compaction at 80% context
 
-The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery — is the source of truth for context occupancy; an armed pager autofires a hard advisory at 80%. When occupancy is **at or above 80%** (or clearly approaching it on a long turn): pack the standing duty into interface keys and your awaiting return payload (planted facts, open threads, job groups in flight), run `{{commandPath}} session compact --request`, then IMMEDIATELY end the turn with `{{commandPath}} session return --await "<durable state>"`. Do not keep working after requesting — this session identity is about to be succeeded. You cannot compact mid-turn: the orchestrator (or an operator `session compact <id>`) executes compaction only on an awaiting headless/subagent session with no live dispatches, while you are dormant; a successor session continues the standing duty. If you wake as a successor, read every path in the bootstrap FILES list directly before acting — the summary is orientation, not ground truth.
+The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery — is the source of truth for context occupancy; an armed pager autofires a hard advisory at 80%. 80% is guidance, not a gate: nothing fires on your behalf, so treat it as the point by which you should have **started**. At or above 80% (or clearly approaching it on a long turn) you write your own handoff — there is no distiller. Run `{{commandPath}} compact start` (it prints the handoff contract, the exact path in your spool's `scratch/` to write it to, and your live Page, so the standing duty and OPEN OBLIGATIONS come from durable state rather than memory), write the handoff to that path with your own tools, then run `{{commandPath}} compact handoff` — a **turn-ending verb**, sibling of `return`. It validates the handoff while you are still alive, ends this context, and relaunches a fresh run on the **same session id**, so your inbox, jobs, rooms, and station bindings carry over. Do not plan work after it; there is no after. Every refusal leaves your context alive — fix it and retry; materialized in-flight dispatches are detached and inherited by the successor rather than refused, and `{{commandPath}} compact abort` backs out. If you wake as the relaunched context, read the handoff and every path in its FILES list directly before acting — the summary is orientation, not ground truth — then run `{{commandPath}} compact finish` and resume the standing duty.

package/dist/_orbh/prompts/subagent.md

@@ -41,7 +41,7 @@ Orbh is a meta-harness: a durable session layer that launches, tracks, supervise
 
 A session is an event-sourced Orb spool with a stable id, title and description, a free-form key/value interface (`session set/get`), and runs. Your run is one **turn**. Every turn ends with `return --finish` or `return --await`; `--finish` is the default. Await is a promise of further interaction. `return --await` still delivers this turn's result immediately, so your collector resolves now; awaiting only keeps you wakeable for a future turn, which ends with its own return. As a subagent, use `--await` only when your dispatcher granted or requested follow-up availability. Exiting without returning gets this turn re-prompted at most twice, then marks it `failed-unreturned` and leaves the session awaiting.
 
-A detached persistent waiter stands for the session's lifetime. During a live run, `{{commandPath}} page arm` attaches to it for lowest-latency mid-run delivery. Re-attach after delivery when latency matters; otherwise durable events arrive at your next turn boundary. Awaiting sessions wake on any page-worthy event with a coalesced digest.
+The machine-wide Orbh orchestrator sweep owns unattended wake delivery across turns. During a live run, `{{commandPath}} page arm` is an optional one-shot surface for lowest-latency mid-run delivery. Re-arm after delivery when latency matters; otherwise durable events arrive at your next turn boundary. While awaiting, the orchestrator resumes the session for any page-worthy event with a coalesced digest.
 
 If a counterparty you wait on (a `message request` target or a dispatched subagent) exits, fails to return, blocks on human input, or is killed, a typed NOTICES entry reaches you with a reason, trust grade, and guidance — follow it; `killed` means deliberately cancelled: do NOT re-send or spawn a replacement.
 
@@ -68,11 +68,14 @@ Run blocking collection with your harness's native background execution. Waiting
 
 For work that should outlive you or belongs to no one, use bare `launch` to create a **peer**. A peer is not your subagent and no collector waits for it. Coordinate by message or room.
 
+<!-- Improvement intake disabled 2026-07-27: the improve loop is not working well enough to
+     advertise to every session. Restore this paragraph when the intake path is reliable again.
 Any session may file harness bugs or Orbh improvement requests in the well-known `orbh-improvements` room (no join needed); start the envelope with `[improve] category=bug|improvement | reporter=<session-id> | title=<short title>`. Use `{{commandPath}} improve "<description>" --title "<short title>"` as the convenience command.
+-->
 
 ## Self-compaction at 80% context
 
-The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery — is the source of truth for context occupancy; an armed pager autofires a hard advisory at 80%. When occupancy is **at or above 80%** (or clearly approaching it on a long turn): pack successor state into interface keys and your return payload (done, missing, in-flight dispatches), run `{{commandPath}} session compact --request`, then IMMEDIATELY end the turn with `{{commandPath}} session return --await "<durable state>"`. Do not keep working after requesting — this session identity is about to be succeeded. You cannot compact mid-turn: the orchestrator (or an operator `session compact <id>`) executes compaction only on an awaiting headless/subagent session with no live dispatches, while you are dormant; a successor session continues the dispatch. If you wake as a successor, read every path in the bootstrap FILES list directly before acting — the summary is orientation, not ground truth.
+The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery — is the source of truth for context occupancy; an armed pager autofires a hard advisory at 80%. 80% is guidance, not a gate: nothing fires on your behalf, so treat it as the point by which you should have **started**. At or above 80% (or clearly approaching it on a long turn) you write your own handoff — there is no distiller. Run `{{commandPath}} compact start` (it prints the handoff contract, the exact path in your spool's `scratch/` to write it to, and your live Page, so OPEN OBLIGATIONS come from durable state rather than memory), write the handoff to that path with your own tools, then run `{{commandPath}} compact handoff` — a **turn-ending verb**, sibling of `return`. It validates the handoff while you are still alive, ends this context, and relaunches a fresh run on the **same session id**, so your dispatcher's collector anchor, inbox, and jobs carry over. Do not plan work after it; there is no after. Every refusal leaves your context alive — fix it and retry; materialized in-flight dispatches are detached and inherited by the successor rather than refused, and `{{commandPath}} compact abort` backs out. If you wake as the relaunched context, read the handoff and every path in its FILES list directly before acting — the summary is orientation, not ground truth — then run `{{commandPath}} compact finish`.
 
 ## End this turn
 
@@ -81,3 +84,5 @@ The Page `CONTEXT` line — via `{{commandPath}} page` or a `page arm` delivery
 ```
 
 Use `--await` instead only when the dispatcher granted or requested follow-up availability. Do not `close` or `end`; return owns the disposition.
+
+This is the last action of every turn, short ones included: a wake turn that reads a digest and stops on a message saying it is still waiting has stranded itself, because nothing outside a live turn can re-invoke you except an `--await` return.