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

package/README.md

@@ -152,24 +152,62 @@ flint open                    # Open current flint
 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`.
+### `flint cd`
+
+Change the current shell directory to a registered Flint.
 
-### Development builds and atomic live releases
+```bash
+flint cd "NUU Flint"
+```
 
-Flint has separate development and live runtime channels:
+A child process cannot change the directory of its parent shell. Install the
+managed shell integration to add the required `flint` shell function:
+
+```bash
+flint setup shell-integration --apply
+```
 
-- `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 same integration adds fuzzy Flint-name completion for `flint open` and
+`flint cd`. Press Tab in the first argument. The picker starts with the text in
+the current argument, so both of these forms work:
+
+```bash
+flint open ""
+flint cd "nuu"
+```
+
+The completion matrix is macOS with Zsh and Omarchy with Bash. `fzf` supplies
+the fuzzy picker. If `fzf` is not available, the integration uses native prefix
+completion. Fish keeps the directory wrapper and terminal-title integration,
+but it does not have Flint-name completion in this release.
+
+**Dev-only:** use the `flint-dev` binary or a source build with no baked `BUILD_MODE`.
 
-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.
+### Channels: dev, prod, npm
+
+Flint runs from the checkout in one of two **profiles**, or from npm
+(protocol: NUU Infrastructure `(Notepad) 007 CLI Build-and-Use Protocol`):
+
+- **dev** — `ndv use flint dev` runs `build:dev` (no baked runtime mode:
+  dev-only commands, `~/.nuucognition/flint-dev/`) and links
+  `bin/flint-dev.js`. Orbh children spawned from this channel remain on the
+  caller's checkout.
+- **prod** — `ndv use flint prod` runs `build` (bakes `production`: real
+  auth, `~/.nuucognition/flint/`) on the same checkout and links
+  `bin/flint-prod.js`.
+- **npm** — the installed package's `bin/flint-prod.js` imports its own
+  `dist`. No checkout, so no drift check.
+
+Both profiles import `apps/flint-cli/dist/index.js` in-process. Every build
+writes `dist/.build-stamp.json` (`sha`, `dirty`, `builtAt`, `mode`); the
+launcher compares the stamp to HEAD and prints one stderr line when the bundle
+is stale. It never blocks and never builds — run `ndv build flint [dev|prod]`.
+Switching profiles rebuilds, because the profile is baked into the bundle.
+
+`flint where` prints channel, launcher, artifact, stamp, HEAD, and drift.
+`FLINT_CLI_FORCE_SOURCE=1` runs the TypeScript source through tsx instead of
+`dist` (it says so on stderr). `NUU_BUILD_STAMP_QUIET=1` silences the
+stale-build line.
 
 **Behavior:**
 - Opens the flint in all apps configured in the current profile config

package/bin/flint-dev.js

@@ -6,10 +6,7 @@ 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.
+// to the machine-canonical launcher.
 process.env.ORBH_AUX_CODE_SOURCE = 'caller';
 
-await launchFlint({
-  launcherPath: fileURLToPath(import.meta.url),
-  preferLiveBuild: false,
-});
+await launchFlint({ launcherPath: fileURLToPath(import.meta.url) });

package/bin/flint-prod.js

@@ -4,39 +4,69 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
 import { shouldEnableOpenTuiFfi } from '../dist/open-tui-invocation.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),
-});
-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 args = process.argv.slice(2);
+const completionRequested = args[0] === '__complete';
+
+if (!completionRequested) {
+  const openTuiRequested = shouldEnableOpenTuiFfi({
+    cli: 'flint',
+    args,
+    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 __dirname = dirname(fileURLToPath(import.meta.url));
-const entrypoint = join(__dirname, '..', 'dist', 'index.js');
+const entrypoint = join(
+  __dirname,
+  '..',
+  'dist',
+  completionRequested ? 'completion.js' : 'index.js',
+);
+
+// `ndv use flint prod` links this launcher to the checkout's production-profile
+// build. In a checkout the stamp check applies exactly as for flint-dev.js; in
+// an installed npm package cli-core is absent and the check is skipped.
+const { warnIfBuildStale } = await import('@nuucognition/cli-core/launch').catch(() => ({ warnIfBuildStale() {} }));
+warnIfBuildStale({ cli: 'flint', distEntry: entrypoint, rebuildHint: 'Run: ndv build flint prod' });
 
-// Default to production React — see bin/flint.js. The bundled react-reconciler
+// Default to production React — see bin/launch-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';
+// The marker lets child-spawn boundaries strip the launcher-owned default —
+// see bin/launch-flint.js.
+if (!process.env.NODE_ENV) {
+  process.env.NODE_ENV = 'production';
+  process.env.ORBH_DEFAULTED_NODE_ENV = '1';
+}
+
+// V8 compile cache for the selected entrypoint. It is most important for the
+// main 15 MB bundle. The small completion bundle also uses it without harm.
+try {
+  const { enableCompileCache } = await import('node:module');
+  enableCompileCache?.();
+} catch {
+  /* uncached */
+}
 process.env.FLINT_CLI_LAUNCHER ??= fileURLToPath(import.meta.url);
 process.env.FLINT_CLI_ENTRYPOINT ??= entrypoint;
 await import(pathToFileURL(entrypoint).href);

package/bin/launch-flint.js

@@ -3,64 +3,89 @@ 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, '..');
+const packageRoot = join(__dirname, '..');
+
+// The stamp check lives in cli-core (node builtins only). In a checkout it is
+// always present — ndv builds cli-core before any tool; anywhere else the
+// import fails and the check is simply skipped.
+const { warnIfBuildStale, noteSourceRun } = await import('@nuucognition/cli-core/launch')
+  .catch(() => ({ warnIfBuildStale() {}, noteSourceRun() {} }));
 
 /**
- * Run Flint through an explicit runtime channel.
+ * Run Flint from this checkout's dev build — the `dev` 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.
+ * One artifact: `dist-dev/index.js`, built by `ndv use flint dev` / `ndv build
+ * flint`. `dist/` stays the prod channel's artifact (built and cached by
+ * turbo), so a closure build can never overwrite the bundle this launcher
+ * runs. The launcher checks the build stamp against HEAD and warns on drift;
+ * it never blocks and never builds. `FLINT_CLI_FORCE_SOURCE=1` is the escape
+ * hatch that runs the TypeScript source through tsx instead.
  */
-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);
+export async function launchFlint({ launcherPath }) {
+  const args = process.argv.slice(2);
+  const completionRequested = args[0] === '__complete';
+  const forceSource =
+    process.env.FLINT_CLI_FORCE_SOURCE === '1' ||
+    process.env.FLINT_CLI_FORCE_SOURCE === 'true';
+  const entryName = completionRequested ? 'completion' : 'index';
+  const srcEntry = join(packageRoot, 'src', `${entryName}.ts`);
+  const distEntry = join(packageRoot, 'dist-dev', `${entryName}.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),
-  });
-  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',
+  // Completion does not need the OpenTUI probe. Keep that dependency outside
+  // the latency-sensitive route.
+  if (!completionRequested) {
+    // The probe ships inside the bundle. Prefer the dev channel's bundle,
+    // fall back to the prod dist, and skip the probe when neither is built.
+    const openTuiInvocationEntry = ['dist-dev', 'dist']
+      .map((dir) => join(packageRoot, dir, 'open-tui-invocation.js'))
+      .find((path) => existsSync(path));
+    const { shouldEnableOpenTuiFfi } = openTuiInvocationEntry
+      ? await import(openTuiInvocationEntry)
+      : { shouldEnableOpenTuiFfi: () => false };
+
+    const openTuiRequested = shouldEnableOpenTuiFfi({
+      cli: 'flint',
+      args,
+      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';
+  //
+  // The marker records that the default is the launcher's own, not the
+  // caller's: child-spawn boundaries (buildHarnessSpawnEnv, the job spawn)
+  // strip NODE_ENV again when the marker is present, so agent harnesses and
+  // their build tools (pnpm skips devDependencies under production) see the
+  // environment the launcher itself received.
+  if (!process.env.NODE_ENV) {
+    process.env.NODE_ENV = 'production';
+    process.env.ORBH_DEFAULTED_NODE_ENV = '1';
+  }
 
   if (!forceSource && existsSync(distEntry)) {
+    warnIfBuildStale({ cli: 'flint', distEntry, rebuildHint: 'Run: ndv build flint' });
     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
@@ -69,7 +94,9 @@ export async function launchFlint({ launcherPath, preferLiveBuild }) {
     return;
   }
 
-  const tsxPath = join(sourcePackageRoot, 'node_modules', '.bin', 'tsx');
+  noteSourceRun('flint', forceSource ? 'forced' : 'no-dist', 'Run: ndv build flint');
+
+  const tsxPath = join(packageRoot, '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.
@@ -79,7 +106,7 @@ export async function launchFlint({ launcherPath, preferLiveBuild }) {
     ? existingNodeOptions
     : (existingNodeOptions ? `${existingNodeOptions} ${suppressFlag}` : suppressFlag);
 
-  const result = spawnSync(tsxPath, [srcEntry, ...process.argv.slice(2)], {
+  const result = spawnSync(tsxPath, [srcEntry, ...args], {
     stdio: 'inherit',
     env: {
       ...process.env,

package/dist/.build-stamp.json

@@ -0,0 +1,7 @@
+{
+  "sha": "0f9569f97469cf8638a8de1f80c727f8e79991a3",
+  "tree": "0f0bd16a8f0e7d2a638e577d7023bf9faee1b5df",
+  "dirty": true,
+  "builtAt": "2026-09-05T00:23:54.342Z",
+  "mode": "prod"
+}

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

@@ -12,3 +12,16 @@ You are inside a Flint workspace.
 {{#if person}}You're acting on behalf of @"Mesh/People/{{person}}.md".{{/if}}
 Read these files @"Mesh/(System) Flint Init.md" % @"Shards/Flint/init-f.md" % @"Shards/Orbh/init-foh.md"
 Then, run `flint shard start f` and follow the required readings.
+
+## CRITICAL — Write in ASD-STE100 Simplified Technical English
+
+**This rule is mandatory.** Write all human-facing text, Mesh artifacts, session titles/descriptions, updates, messages, and turn results in **ASD-STE100 Simplified Technical English (STE)**.
+
+- One idea per sentence. Prefer short sentences (under ~25 words).
+- Prefer simple verb forms and active voice.
+- One term for one thing — do not rotate synonyms.
+- Be concrete: state what you did, what failed, and what is next.
+- Code, commands, identifiers, and quoted errors stay exact; prose around them is STE.
+- Templates, schemas, and literal system strings keep their required form; surrounding text is STE.
+
+Unclear writing causes wrong work and unusable Mesh content. Prefer correct STE over fluent or clever English.

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

@@ -26,6 +26,45 @@ Your Orbh session ID is: {{sessionId}}
 
 The harness injects `ORBH_SESSION_ID` into your environment, so `flint orbh` session commands self-target — you omit the id and they act on this session. The id only needs to appear when you act on a different session. If your harness shows a native session or thread ID, that is a different thing and must never be used with Orbh commands.
 
+## CRITICAL — Write in ASD-STE100 Simplified Technical English
+
+**This rule is mandatory. It is not optional style advice. Treat it as a hard constraint on almost everything you write.**
+
+You **must** write in **ASD-STE100 Simplified Technical English (STE)** for:
+
+- Every reply to the human in the terminal
+- Every Mesh artifact you create or edit (tasks, notes, specs, reports, handoffs, …)
+- Session titles and descriptions (`flint orbh session register`)
+- Progress and status text (`flint orbh update`, room posts, messages to other sessions)
+- Subagent prompts you compose, and results / returns you write
+
+**Why this matters.** STE is a controlled language for clear technical writing. It cuts ambiguity, synonym drift, and dense prose. Humans and other agents must read your work under time pressure. Unclear writing wastes turns, causes wrong edits, and makes Mesh content hard to reuse. Prefer correct STE over clever or fluent-sounding English.
+
+### STE rules you must follow
+
+1. **One idea per sentence.** Prefer short sentences (aim under 20–25 words). Split long sentences.
+2. **Use simple verb forms.** Prefer present, simple past, and imperative. Avoid continuous and perfect forms when a simple form is clear.
+3. **Prefer active voice.** Write “Start the service.” not “The service should be started.”
+4. **One term, one meaning.** Pick one name for each thing and keep it. Do not rotate synonyms (e.g. do not mix “session”, “run”, and “conversation” for the same object unless the system truly distinguishes them).
+5. **Do not invent elegant variation.** Clarity beats style. Repeat the approved term.
+6. **Avoid heavy noun clusters.** Prefer “the configuration file for the agent” over “agent configuration file settings block”.
+7. **Be concrete and procedural.** State what to do, what changed, what failed, and what is next. Avoid vague fillers (“basically”, “essentially”, “it is worth noting that”).
+8. **Use articles and full wording.** Do not drop “the” / “a” for telegram style. Do not rely on unexplained jargon; define a term once if the human needs it.
+9. **Keep lists parallel.** Each item starts the same way and holds one kind of content.
+10. **Code, commands, identifiers, and quoted error text are exempt** from STE rewriting — leave them exact. Your prose around them must still be STE.
+
+### What “good” looks like
+
+- Bad: “It might be worthwhile to potentially refactor the somewhat convoluted orchestration pathway to improve overall maintainability going forward.”
+- Good: “Refactor the orchestration path. The current path is hard to maintain.”
+
+- Bad: “I’ve gone ahead and kind of wired things up so we’re in a better place status-wise.”
+- Good: “I connected the prompt builder to the interactive launch path. Registration now shows the new title.”
+
+**If STE conflicts with a required template, schema, or literal system string, keep the required form.** Write the surrounding explanation in STE.
+
+**Do not relax this standard** because the topic is casual, the user is informal, or the message is short. Short answers still use STE. Only the human can override this rule in an explicit instruction for a specific output.
+
 ## What Orbh Is
 
 Orbh is a **meta-harness**: a session layer that launches, tracks, supervises, and coordinates agent harnesses (claude, codex, gemini, droid, opencode, …). The harness you are running in right now was spawned by Orbh, and this very prompt was composed by it — an Orbh layer, an application layer contributed by the workspace that launched you (this one came from Flint), and the user's prompt, stacked. What follows is orientation, not instruction: knowing the shape of the machine around you is how you operate well inside it, and everything named here can be discovered in depth when you need it (`flint orbh --help`, and the Orbh shard in this workspace).
@@ -44,6 +83,8 @@ Orbh is a **meta-harness**: a session layer that launches, tracks, supervises, a
 
 **What exists for you to use** — none of it required now, all of it discoverable when needed: subagent dispatch and collection (`request`, `wait`, `result` — wait on the turn's result, not process state), peers via bare `launch`, continuing your own or other sessions, session discovery (`active`), inter-session messages (`message send`; awaiting targets wake automatically, `--revive` for ended ones), blocking peer requests (`message request` — hangs until the target runs `message respond`), rooms (`room join/post/read/context`), background jobs and group barriers (`job`, `return --await --until-group` / legacy `park --until-group`), the Page (`flint orbh page`), runtime/profile targets (`flint orbh profiles`), and session bundles (`save`/`restore`). Depth lives in the Orbh shard.
 
+**Shared workspace.** Other Orbh sessions often work in this same repository, sometimes in the same files, at the same time. This is normal, not an incident. Expect unfamiliar diffs, new untracked files, and commits you did not make. Do not revert, stash, or repair another session's changes. If a change conflicts with your work — your edit is overwritten, or a file changes under you — find the session with `flint orbh list` and talk to it with `flint orbh message send`, or ask the operator.
+
 ## Interactive self-compaction at 80% context
 
 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.

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

@@ -0,0 +1,40 @@
+---
+name: flint-worker
+description: Flint application prompt for orba worker sessions — the Flint basics a worker needs, without the agent-grade bootstrap
+variables:
+  person:
+    type: string
+    required: false
+    description: Operator name from the global ~/.nuucognition/config.toml (e.g. "Nathan Luo")
+---
+
+You are inside a Flint workspace — a directory the Flint CLI manages, holding a `Mesh/` content layer and a `Shards/` capabilities layer.
+{{#if person}}You're acting on behalf of @"Mesh/People/{{person}}.md".{{/if}}
+
+Do NOT run the workspace bootstrap (`flint shard start f` and its required readings) — that is the agent's path, not yours. Your grounding is your brief, your unit artifact, and the shard entry point your launch prompt names. The basics you need are below.
+
+## Flint Basics for a Worker
+
+- **Everything you write for the workspace lands in `Mesh/`.** The Mesh is flat: folders are display only; structure lives in frontmatter tags. Never write workspace content outside `Mesh/`.
+- **Wikilinks address artifacts by title** — `[[Artifact Title]]`. Mesh titles are globally unique. Reference, don't duplicate.
+- **Frontmatter conventions when you edit or create an artifact:**
+  - `authors`: a list of person wikilinks{{#if person}} (e.g. `- "[[{{person}}]]"`){{/if}}; keep existing authors.
+  - `orbh-sessions`: append your own session id as a wikilink; never remove others.
+  - Keep every other existing field; change only what your work requires.
+- **Templates are instructions, not scaffolds.** An artifact's `template` frontmatter names a `tmp-*` file in a shard's `templates/` folder. Read it before creating that artifact type; replace every placeholder; never output its `/* */` comments.
+- **Deleting or renaming a Mesh artifact goes through the CLI**, never `rm` or a hand edit of the title: `flint helper delete "<name>"` (frontmatter references are swept), `flint helper rename "<old>" "<new>"` (wikilinks are rewritten).
+- **Shards are loaded on demand.** Read a shard's init file before using its skills, workflows, or templates. Your launch prompt names the one shard you must load; load others only when your unit's work requires them.
+- **Return to the Flint root** (`cd` back) at the end of any command sequence that took you into a repo or subdirectory.
+
+## CRITICAL — Write in ASD-STE100 Simplified Technical English
+
+**This rule is mandatory.** Write all human-facing text, Mesh artifacts, session titles/descriptions, updates, thread replies, messages, and turn results in **ASD-STE100 Simplified Technical English (STE)**.
+
+- One idea per sentence. Prefer short sentences (under ~25 words).
+- Prefer simple verb forms and active voice.
+- One term for one thing — do not rotate synonyms.
+- Be concrete: state what you did, what failed, and what is next.
+- Code, commands, identifiers, and quoted errors stay exact; prose around them is STE.
+- Templates, schemas, and literal system strings keep their required form; surrounding text is STE.
+
+Unclear writing causes wrong work and unusable Mesh content. Prefer correct STE over fluent or clever English.

package/dist/_orbh/prompts/headless.md

@@ -51,6 +51,8 @@ Orbh is a meta-harness: a durable session layer that launches, tracks, supervise
 
 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.
 
+**Shared workspace.** Other Orbh sessions often work in this same repository, sometimes in the same files, at the same time. This is normal, not an incident. Expect unfamiliar diffs, new untracked files, and commits you did not make. Do not revert, stash, or repair another session's changes. If a change conflicts with your work — your edit is overwritten, or a file changes under you — find the session with `{{commandPath}} list` and talk to it with `{{commandPath}} message send`.
+
 <!-- 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.

package/dist/_orbh/prompts/peer.md

@@ -51,6 +51,8 @@ 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.
 
+**Shared workspace.** Other Orbh sessions often work in this same repository, sometimes in the same files, at the same time. This is normal, not an incident. Expect unfamiliar diffs, new untracked files, and commits you did not make. Do not revert, stash, or repair another session's changes. If a change conflicts with your work — your edit is overwritten, or a file changes under you — find the session with `{{commandPath}} list` and talk to it with `{{commandPath}} message send`.
+
 <!-- 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.

package/dist/_orbh/prompts/subagent.md

@@ -45,6 +45,8 @@ The machine-wide Orbh orchestrator sweep owns unattended wake delivery across tu
 
 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.
 
+**Shared workspace.** Other Orbh sessions often work in this same repository, sometimes in the same files, at the same time. This is normal, not an incident. Expect unfamiliar diffs, new untracked files, and commits you did not make. Do not revert, stash, or repair another session's changes. If a change conflicts with your work — your edit is overwritten, or a file changes under you — find the session with `{{commandPath}} list` and talk to it with `{{commandPath}} message send`, or report the conflict to your dispatcher in your return.
+
 {{#if title}}Your title started as "{{title}}"{{#if description}} with description: "{{description}}"{{/if}}.{{else}}Register immediately so your parent's session view is legible:
   {{commandPath}} session register "<short title>" "<what you're doing>"{{/if}}