mixdog 0.9.93 → 0.9.95

package/src/tui/index.jsx

@@ -18,11 +18,19 @@ import { scheduleRenderFrameAck, TUI_RENDER_FPS } from './engine/render-timing.m
 import { installProcessSignalCleanup } from '../runtime/shared/process-shutdown.mjs';
 import { finishProcessLifecycle } from '../runtime/shared/process-lifecycle.mjs';
 import { rgbSgr } from '../ui/ansi.mjs';
-import { emitTerminalBackground, loadThemeSettingFromConfig, theme } from './theme.mjs';
+import {
+  emitTerminalBackground,
+  getThemeSetting,
+  listThemes,
+  loadThemeSettingFromConfig,
+  setThemeSetting,
+  theme,
+} from './theme.mjs';
 import { POP_KITTY, DISABLE_MODIFY_OTHER_KEYS } from './keyboard-protocol.mjs';
 import { displayWidth } from './display-width.mjs';
 import { rotateBoundedLog, PLUGIN_LOG_MAX_BYTES, PLUGIN_LOG_KEEP_BYTES } from '../lib/mixdog-debug.cjs';
 import { localPackageVersion } from '../runtime/shared/update-checker.mjs';
+import { touchProjectSelected } from '../standalone/projects.mjs';
 
 // Trailing `\x1b[>0s` restores XTSHIFTESCAPE (shift-to-select-extend) to its
 // terminal default; MOUSE_TRACKING_ON opts into `\x1b[>1s`, so every mouse/alt
@@ -505,6 +513,29 @@ export async function runTui({ provider, model, toolMode, remote, forceOnboardin
     const outcome = await storeOutcomePromise;
     if (outcome.error) throw outcome.error;
     store = outcome.store;
+    // Launching mixdog INSIDE a registered folder is an "open" too: without
+    // this, a project entered straight from the shell never moved in the
+    // picker's most-recent-first order. Unregistered folders are ignored.
+    try {
+      touchProjectSelected(store.getState?.()?.cwd || process.cwd());
+    } catch { /* best-effort recency */ }
+    // The palette lives in THIS process: on a daemon-backed store the engine's
+    // theme methods would run inside the daemon, so the picker saw a promise
+    // instead of the list and a switch repainted nothing here. Bind the three
+    // theme methods locally (same pattern as the ink selection helpers below)
+    // and mirror the switch to the engine with persist:false, purely so its
+    // themeEpoch bump re-renders this tree.
+    if (store.isRemoteEngine === true) {
+      const remoteSetTheme = store.setTheme;
+      store.listThemes = () => listThemes();
+      store.getTheme = () => getThemeSetting();
+      store.setTheme = (id, options = {}) => {
+        const applied = setThemeSetting(id, options);
+        void Promise.resolve(remoteSetTheme?.(id, { ...options, persist: false }))
+          .catch(() => { /* the local palette is already applied */ });
+        return applied;
+      };
+    }
     bootProfile('store:ready', { ms: (performance.now() - startedAt).toFixed(1) });
   } catch (error) {
     splash.stop();
@@ -517,6 +548,20 @@ export async function runTui({ provider, model, toolMode, remote, forceOnboardin
     process.stderr.write(`mixdog: ${error?.message || error}\n`);
     return 1;
   }
+  // The engine store is a daemon-backed Proxy: every method it does not
+  // implement locally comes back as an ASYNC remote call. A synchronous
+  // getOnboardingStatus() probe inside App therefore sees a Promise, never
+  // `.completed`, and re-opens the finished wizard on every launch. Resolve
+  // the status once here and hand the decided verdict to App. An unreadable
+  // status counts as completed so a transport hiccup cannot resurrect a
+  // wizard the user already dismissed (`mixdog --onboarding` still forces it).
+  let onboardingCompleted = true;
+  try {
+    const onboardingStatus = await store.getOnboardingStatus?.();
+    if (onboardingStatus && typeof onboardingStatus === 'object') {
+      onboardingCompleted = onboardingStatus.completed === true;
+    }
+  } catch { /* status probe failed → treat as completed */ }
   // Stop the spinner BEFORE ink mounts so no stray splash write can land
   // between (or after) ink's first frames.
   splash.stop();
@@ -598,7 +643,7 @@ export async function runTui({ provider, model, toolMode, remote, forceOnboardin
     // its clear-frame → write → relative re-render dance, which scrolls the
     // alt screen one line per stray console line (the streaming newline
     // bounce). See installTuiConsoleGuard.
-    const instance = render(<App store={store} forceOnboarding={forceOnboarding === true} />, { exitOnCtrlC: false, maxFps: TUI_RENDER_FPS, incrementalRendering: true, patchConsole: false, onRender: makeRenderProfiler() });
+    const instance = render(<App store={store} forceOnboarding={forceOnboarding === true} onboardingCompleted={onboardingCompleted} />, { exitOnCtrlC: false, maxFps: TUI_RENDER_FPS, incrementalRendering: true, patchConsole: false, onRender: makeRenderProfiler() });
     bootProfile('render:mounted', { ms: (performance.now() - startedAt).toFixed(1) });
     const { waitUntilExit } = instance;
     // [mixdog fork] Hand the ink renderer's drag-selection setter to the store so

package/src/tui/markdown/stream-fence.mjs

@@ -9,7 +9,7 @@
  * so the block height stays stable across deltas.
  *
  * Kept in its own dependency-free module so it can be unit-tested without the
- * ink/JSX render stack. Ref: earendil-works/pi packages/tui/src/components/markdown.ts.
+ * ink/JSX render stack.
  */
 export function trimPartialClosingFences(tokens) {
   const token = tokens?.[tokens.length - 1];

package/src/tui/spinner-meta.mjs

@@ -0,0 +1,80 @@
+/**
+ * src/tui/spinner-meta.mjs — the spinner BYLINE contract, shared by the TUI
+ * spinner row and the desktop live-activity band.
+ *
+ * The verb pool already lives in spinner-verbs.mjs so both surfaces say the
+ * same word at the same second. Everything AFTER the verb (elapsed gate, token
+ * label, thinking / "thought for Ns") used to be assembled twice, which is how
+ * the desktop ended up showing tokens from second one while the TUI hid them
+ * for 30s. One builder, one answer.
+ */
+
+/** Short turns stay quiet: elapsed/token meta only after this long. */
+export const SHOW_TOKENS_AFTER_MS = 30_000;
+
+const compactNumberFormatter = new Intl.NumberFormat('en-US', {
+  notation: 'compact',
+  maximumFractionDigits: 1,
+  minimumFractionDigits: 0,
+});
+
+export function formatSpinnerTokens(value) {
+  const tokens = Math.max(0, Number(value || 0));
+  if (tokens >= 1000) return compactNumberFormatter.format(tokens).toLowerCase();
+  return String(Math.round(tokens));
+}
+
+// `auto` is the absence of a choice, so it never becomes a visible suffix —
+// only an explicitly picked level earns "thinking (high)".
+function effortSuffix(effort) {
+  const level = String(effort || '').trim().toLowerCase();
+  if (!level || level === 'auto' || level === 'default' || level === 'off' || level === 'none') return '';
+  return ` (${level})`;
+}
+
+/**
+ * Live thinking reads as `thinking`; a finished thinking span reads as
+ * `thought for Ns` until the next one starts. Sub-second
+ * spans are noise and stay hidden.
+ */
+export function spinnerThinkingLabel({ thinking = false, thinkingSince = 0, thinkingMs = 0, effort = '' } = {}) {
+  if (thinking || Number(thinkingSince) > 0) return `thinking${effortSuffix(effort)}`;
+  const ms = Math.max(0, Number(thinkingMs) || 0);
+  if (ms >= 1000) return `thought for ${Math.max(1, Math.round(ms / 1000))}s`;
+  return '';
+}
+
+/**
+ * Byline pieces for one live turn. Width gating stays with each surface (the
+ * TUI measures terminal columns, the desktop wraps in CSS) — this only decides
+ * WHAT is worth showing and how it reads.
+ */
+export function buildSpinnerMeta({
+  elapsedMs = 0,
+  outputTokens = 0,
+  thinking = false,
+  thinkingSince = 0,
+  thinkingMs = 0,
+  effort = '',
+  verbose = false,
+} = {}) {
+  const tokens = Math.max(0, Number(outputTokens) || 0);
+  const thinkingText = spinnerThinkingLabel({ thinking, thinkingSince, thinkingMs, effort });
+  return {
+    tokensText: tokens > 0 ? `${formatSpinnerTokens(tokens)} tokens` : '',
+    showTokens: tokens > 0 && (Boolean(verbose) || Number(elapsedMs) > SHOW_TOKENS_AFTER_MS),
+    thinkingText,
+    thinkingActive: Boolean(thinking || Number(thinkingSince) > 0),
+  };
+}
+
+/**
+ * Reduced motion: one switch for the whole process — animation is a nicety,
+ * and low-power/SSH/recording sessions must be able to drop it without losing
+ * the timer or the token readout.
+ */
+export function isReducedMotion(env) {
+  const source = env || (typeof process !== 'undefined' && process?.env) || {};
+  const value = String(source.MIXDOG_REDUCED_MOTION ?? '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'on' || value === 'yes';
+}

package/src/tui/spinner-verbs.mjs

@@ -2,6 +2,11 @@
  * src/tui/spinner-verbs.mjs — playful "thinking" verbs for the spinner.
  *
  * Playful spinner verbs. Shown as `<Verb>… (Ns · ↑ N tokens)` while a turn runs.
+ *
+ * ONE common pool, never a per-mode pool: the stream flips
+ * thinking → tool-use → responding many times inside a single turn, so a
+ * mode-keyed phrase rewrites itself every few seconds and reads as flicker.
+ * The phrase is drawn from this list and held for a fixed window instead.
  */
 export const SPINNER_VERBS = [
   'Accomplishing', 'Actioning', 'Actualizing', 'Architecting', 'Baking', 'Beaming',
@@ -40,5 +45,35 @@ export const SPINNER_VERBS = [
   'Zesting', 'Zigzagging',
 ];
 
+/** How long one phrase holds before the pool advances. */
+export const SPINNER_VERB_ROTATE_MS = 30_000;
+
+/**
+ * Modes that describe a STATE rather than ongoing work: they replace the pool
+ * phrase for as long as the mode lasts, then the rotation resumes. Everything
+ * else (requesting/thinking/tool-use/tool-input/responding) shares the pool.
+ * `reconnecting` is absent on purpose — the engine authors that text itself
+ * (retry countdown), so the surfaces pass `spinner.verb` through unchanged.
+ */
+export const SPINNER_MODE_OVERRIDE_VERBS = {
+  compacting: 'Compacting conversation',
+  'auto-clear': 'Auto-clearing conversation',
+  resuming: 'Resuming conversation',
+};
+
+/**
+ * The phrase for a turn at a point in time. Derived from the turn's
+ * `startedAt` so the TUI and the desktop show the SAME word at the same
+ * second, and so mode flips cannot change it — only the 30s window can.
+ */
+export function spinnerVerbFor(startedAt = 0, now = 0, pool = SPINNER_VERBS) {
+  const list = Array.isArray(pool) && pool.length ? pool : SPINNER_VERBS;
+  const anchor = Math.max(0, Number(startedAt) || 0);
+  const elapsed = anchor > 0 ? Math.max(0, (Number(now) || 0) - anchor) : 0;
+  const slot = Math.floor(elapsed / SPINNER_VERB_ROTATE_MS);
+  const seed = Math.floor(anchor / 1000) + slot;
+  return list[((seed * 7) + 3) % list.length];
+}
+
 /** Spinner glyph frames. */
 export const SPINNER_FRAMES = ['◇', '◆', '◈', '◆', '◇'];

package/src/ui/statusline-segments.mjs

@@ -18,7 +18,13 @@ const DEFAULT_MIXDOG_HOME = process.env.MIXDOG_HOME || join(homedir(), '.mixdog'
 const DEFAULT_STANDALONE_DATA_DIR = join(DEFAULT_MIXDOG_HOME, 'data');
 const SHELL_JOBS_SEGMENT_CACHE_MS = 1000;
 
-let _shellJobsSegmentCache = { ownerPid: 0, at: 0, value: { count: 0, elapsedLabel: '' } };
+// Session buckets ride along with the owner-wide totals: one host process can
+// own many sessions (the desktop pools every pane's engine), so a pane must be
+// able to ask for ITS OWN jobs instead of the process aggregate.
+const EMPTY_SHELL_JOBS_SESSION = Object.freeze({ count: 0, elapsedLabel: '' });
+const EMPTY_SHELL_JOBS = Object.freeze({ count: 0, elapsedLabel: '', sessions: Object.freeze({}) });
+
+let _shellJobsSegmentCache = { ownerPid: 0, at: 0, value: EMPTY_SHELL_JOBS };
 let _shellJobsRefreshInFlight = false;
 
 function dataDir() {
@@ -26,10 +32,16 @@ function dataDir() {
 }
 
 // Render-path entry point: synchronous, cache-only. Never blocks on fs.
-export function shellJobsStatus({ clientHostPid } = {}) {
+// Without `sessionId` this reports the owner process aggregate (CLI statusline,
+// keep-awake); with one it reports only that session's own jobs.
+export function shellJobsStatus({ clientHostPid, sessionId } = {}) {
   const ownerPid = positiveInt(clientHostPid);
-  const empty = { count: 0, elapsedLabel: '' };
-  if (!ownerPid) return empty;
+  // Asking for a scope is what matters, not whether that scope is non-empty:
+  // an explicit blank id (a desktop pane with no session yet) owns nothing,
+  // while an OMITTED id means "the whole owner process".
+  const scoped = sessionId !== undefined && sessionId !== null;
+  const scope = String(sessionId ?? '').trim();
+  if (!ownerPid) return scoped ? EMPTY_SHELL_JOBS_SESSION : EMPTY_SHELL_JOBS;
   const now = Date.now();
   const sameOwner = _shellJobsSegmentCache.ownerPid === ownerPid;
   const fresh = sameOwner && now - _shellJobsSegmentCache.at < SHELL_JOBS_SEGMENT_CACHE_MS;
@@ -37,7 +49,9 @@ export function shellJobsStatus({ clientHostPid } = {}) {
     _shellJobsRefreshInFlight = true;
     refreshShellJobsStatus(ownerPid).finally(() => { _shellJobsRefreshInFlight = false; });
   }
-  return sameOwner ? (_shellJobsSegmentCache.value || empty) : empty;
+  const value = sameOwner ? (_shellJobsSegmentCache.value || EMPTY_SHELL_JOBS) : EMPTY_SHELL_JOBS;
+  if (!scoped) return value;
+  return (scope && value.sessions?.[scope]) || EMPTY_SHELL_JOBS_SESSION;
 }
 
 // Memory cycle L2 segment source. The memory daemon writes
@@ -95,8 +109,7 @@ function pidAlive(pid) {
 }
 
 async function refreshShellJobsStatus(ownerPid) {
-  const empty = { count: 0, elapsedLabel: '' };
-  let value = empty;
+  let value = EMPTY_SHELL_JOBS;
   try {
     const dir = join(dataDir(), 'shell-jobs');
     let names;
@@ -123,23 +136,43 @@ async function refreshShellJobsStatus(ownerPid) {
       .slice(0, 30);
     let count = 0;
     let oldestMs = Infinity;
+    // sessionId -> { count, oldestMs }. Jobs with no session stamp (legacy
+    // records, plain CLI runs) still count toward the owner total but belong to
+    // no pane, so they never light up a session's indicator.
+    const bySession = new Map();
     for (const id of ids) {
       const p = join(dir, `${id}.json`);
       let detail;
       try { detail = JSON.parse(await readFile(p, 'utf-8')); } catch { continue; }
       if (!(await isShellJobAlive(detail, p, dir, id))) continue;
       count++;
+      let jobMs = Infinity;
       try {
         const st = await stat(p);
+        jobMs = st.mtimeMs;
         if (st.mtimeMs < oldestMs) oldestMs = st.mtimeMs;
       } catch {}
+      const owner = String(detail?.ownerSessionId ?? '').trim();
+      if (!owner) continue;
+      const bucket = bySession.get(owner) || { count: 0, oldestMs: Infinity };
+      bucket.count += 1;
+      if (jobMs < bucket.oldestMs) bucket.oldestMs = jobMs;
+      bySession.set(owner, bucket);
     }
     if (count) {
-      const elapsedLabel = Number.isFinite(oldestMs) ? formatElapsed(Date.now() - oldestMs) : '';
-      value = { count, elapsedLabel };
+      const now = Date.now();
+      const elapsedLabel = Number.isFinite(oldestMs) ? formatElapsed(now - oldestMs) : '';
+      const sessions = {};
+      for (const [owner, bucket] of bySession) {
+        sessions[owner] = {
+          count: bucket.count,
+          elapsedLabel: Number.isFinite(bucket.oldestMs) ? formatElapsed(now - bucket.oldestMs) : '',
+        };
+      }
+      value = { count, elapsedLabel, sessions };
     }
   } catch {
-    value = empty;
+    value = EMPTY_SHELL_JOBS;
   }
   _shellJobsSegmentCache = { ownerPid, at: Date.now(), value };
 }

package/src/ui/statusline.mjs

@@ -350,7 +350,16 @@ function renderNativeStatusline({
     ...activeHiddenAgentWorkers({ sessionId, clientHostPid }),
   ], agentJobs);
   const { runningWorkers } = classifyAgentWorkers(agentPayload.workers);
-  const shellStatus = shellJobsStatus({ clientHostPid });
+  // Shell segment scope: one host process can own MANY sessions' jobs (the
+  // desktop pools every pane's engine; the daemon backend hosts every
+  // terminal's session), so the owner-wide aggregate would show one
+  // terminal's running shell on every other terminal. Render this session's
+  // own jobs whenever we know which session we are; only a session-less
+  // caller (plain statusline shim) keeps the process aggregate.
+  const shellScope = String(sessionId ?? '').trim();
+  const shellStatus = shellScope
+    ? shellJobsStatus({ clientHostPid, sessionId: shellScope })
+    : shellJobsStatus({ clientHostPid });
 
   const spinnerNow = Date.now();
   const sp = l2SpinnerFrame(spinnerNow);

package/scripts/tmp-cdp-errors.mjs

@@ -1,41 +0,0 @@
-import WebSocket from "ws";
-
-const list = await fetch("http://127.0.0.1:9342/json/list").then((r) => r.json());
-const page = list.find((t) => t.type === "page");
-const ws = new WebSocket(page.webSocketDebuggerUrl);
-let id = 0; const pending = new Map();
-function send(method, params) {
-  return new Promise((res) => { const mid = ++id; pending.set(mid, res); ws.send(JSON.stringify({ id: mid, method, params })); });
-}
-const seen = new Map();
-ws.on("message", (raw) => {
-  const msg = JSON.parse(raw);
-  if (msg.id && pending.has(msg.id)) { pending.get(msg.id)(msg.result); pending.delete(msg.id); return; }
-  if (msg.method === "Runtime.exceptionThrown") {
-    const d = msg.params.exceptionDetails;
-    const desc = d.exception?.description || d.text || "";
-    const key = desc.slice(0, 200);
-    seen.set(key, (seen.get(key) || 0) + 1);
-  } else if (msg.method === "Runtime.consoleAPICalled" && (msg.params.type === "error" || msg.params.type === "warning")) {
-    const text = msg.params.args.map((a) => a.value ?? a.description ?? "").join(" ");
-    const key = "[console." + msg.params.type + "] " + text.slice(0, 300);
-    seen.set(key, (seen.get(key) || 0) + 1);
-  } else if (msg.method === "Log.entryAdded") {
-    const e = msg.params.entry;
-    if (e.level === "error" || e.level === "warning") {
-      const key = "[log." + e.level + "] " + (e.text || "").slice(0, 300) + " @" + (e.url || "");
-      seen.set(key, (seen.get(key) || 0) + 1);
-    }
-  }
-});
-ws.on("open", async () => {
-  await send("Runtime.enable", {});
-  await send("Log.enable", {});
-  setTimeout(() => {
-    for (const [key, count] of [...seen.entries()].sort((a, b) => b[1] - a[1])) {
-      console.log(`x${count}  ${key.replace(/\n/g, " | ")}`);
-    }
-    if (!seen.size) console.log("(no errors captured in window)");
-    process.exit(0);
-  }, 12000);
-});

package/scripts/tmp-cdp-inspect.mjs

@@ -1,41 +0,0 @@
-import WebSocket from "ws";
-
-const list = await fetch("http://127.0.0.1:9342/json/list").then((r) => r.json());
-const page = list.find((t) => t.type === "page");
-if (!page) { console.error("no page target"); process.exit(1); }
-const ws = new WebSocket(page.webSocketDebuggerUrl);
-let id = 0; const pending = new Map();
-function send(method, params) {
-  return new Promise((res) => { const mid = ++id; pending.set(mid, res); ws.send(JSON.stringify({ id: mid, method, params })); });
-}
-ws.on("message", (raw) => {
-  const msg = JSON.parse(raw);
-  if (msg.id && pending.has(msg.id)) { pending.get(msg.id)(msg.result); pending.delete(msg.id); }
-});
-ws.on("open", async () => {
-  const expr = `(() => {
-    const gate = document.querySelector('.desktop-boot-gate');
-    const covers = [...document.querySelectorAll('.pane-surface-cover, .desktop-boot-cover')].map(c => ({
-      cls: c.className,
-      rect: Math.round(c.getBoundingClientRect().width) + 'x' + Math.round(c.getBoundingClientRect().height),
-      parent: (c.parentElement?.className || '').slice(0, 90),
-      hasSpinner: !!c.querySelector('.desktop-loading-spinner'),
-    }));
-    const gates = [...document.querySelectorAll('.pane-surface-gate[data-ready="false"], .stable-surface-switch[data-ready="false"], .stable-content-swap[data-ready="false"]')]
-      .map(g => g.className + ' | parent=' + (g.parentElement?.className || '').slice(0, 70));
-    return JSON.stringify({
-      bootGate: gate ? { ready: gate.dataset.ready, pending: gate.dataset.pending, timeout: gate.dataset.timeout } : null,
-      revealed: window.__mixdogDesktopRevealed,
-      shown: window.__mixdogWindowShown,
-      covers, gates,
-      metrics: (window.__mixdogBootMetrics || []).slice(-30),
-      recovery: !!document.querySelector('.desktop-recovery-screen'),
-      rootKids: document.getElementById('root')?.childElementCount,
-      url: location.href,
-    }, null, 1);
-  })()`;
-  const r = await send("Runtime.evaluate", { expression: expr, returnByValue: true });
-  console.log(r?.result?.value ?? JSON.stringify(r));
-  process.exit(0);
-});
-setTimeout(() => { console.error("timeout"); process.exit(1); }, 8000);

package/src/runtime/agent/orchestrator/session/loop/steering-ladder.mjs

@@ -1,176 +0,0 @@
-// Completion-first steering ladder (worker runaway prevention), extracted from
-// loop.mjs. Owns the mutable ladder counters and the post-batch steering-hint
-// emitters. State is threaded live via a context object of getters/setters so
-// no snapshot goes stale — the loop mutates `messages`/`iterations` in place and
-// this module reads them through the accessors on each call. No behavior change:
-// the counters, thresholds, and emitted messages are verbatim from agentLoop.
-import { appendAgentTrace } from '../../agent-trace.mjs';
-import { level2SteerMessage } from './completion-guards.mjs';
-import { isEagerDispatchable } from './tool-helpers.mjs';
-
-// A single chained segment is read-only only if it STARTS with a read-only verb.
-function _isReadOnlyShellSegment(seg) {
-    const s = seg.trim();
-    if (!s) return null;                                        // empty (trailing operator)
-    if (/^git\s+(status|log)\b/.test(s)) return true;
-    if (/^git\s+diff\b[^\n]*--stat\b/.test(s)) return true;
-    if (/^get-childitem\b/.test(s)) return true;
-    return /^(cat|ls|dir|type)\b/.test(s);
-}
-// Read-only only when EVERY chained segment is read-only — a single mutating
-// segment (e.g. `git status && npm test`) disqualifies the whole command.
-function _isReadOnlyShellCmd(cmd) {
-    const s = String(cmd || '').toLowerCase().trim();
-    if (!s) return false;
-    let sawCmd = false;
-    for (const seg of s.split(/&&|\|\||[;&|]/)) {
-        const verdict = _isReadOnlyShellSegment(seg);
-        if (verdict === null) continue;                         // blank segment
-        if (verdict === false) return false;                    // a mutating segment
-        sawCmd = true;
-    }
-    return sawCmd;
-}
-// Build the completion-first steering-ladder controller. `ctx` supplies live
-// accessors so every read reflects the loop's current mutable state:
-//   - messages, sessionId, sessionAgent, tools           (stable refs/values)
-//   - getIterations()                                    (current iteration)
-//   - getEditCount()                                     (mutated by the loop)
-//   - pushSystemReminder(text)  → push a meta:'hook' user message
-//   - pushUserMessage(msg)      → push a raw user message (level-2 latch text)
-export function createSteeringLadder(ctx) {
-    const {
-        sessionId,
-        sessionAgent,
-        tools,
-        getIterations,
-        getEditCount,
-    } = ctx;
-    const pushSystemReminder = ctx.pushSystemReminder;
-    const pushUserMessage = ctx.pushUserMessage;
-    // Permission-based role detection (agent names are user-definable):
-    // read-permission sessions legitimately never edit, so they get the
-    // report-oriented level-2 text.
-    const readOnlyRole = ctx.readOnlyRole === true;
-    // Edit-push steering is EXPLORER-ONLY: leads legitimately read broadly
-    // before delegating, and reviewer/debugger-style roles read continuously
-    // by design. Pushing "start editing / apply the edit" at those roles
-    // suppresses delegation (observed on TB2.1: forced-delegation workflow
-    // leads went solo right after these nudges). Non-explorer roles keep the
-    // batching guidance but never receive an edit directive, and level-2
-    // edit-push is skipped for them entirely.
-    const editPushEligible = sessionAgent === 'explorer';
-
-    // Step 1: escalation ladder. _level1FireCount is CUMULATIVE (never reset)
-    // so repeated batching reminders accumulate across the whole session.
-    // _level2LatchAtIteration latches level-2 steering to at most once / 5 turns.
-    let _level1FireCount = 0;
-    let _level2LatchAtIteration = -Infinity;
-    // Independent ladder counter: consecutive turns where EVERY call is
-    // read-only (any count) with zero edits. Catches multi-call read-only
-    // turns that the single-call level-1 streak misses. Reset on any edit.
-    let _allReadOnlyStreak = 0;
-    // Tracks consecutive assistant turns that ran exactly one read-only tool
-    // call (missed parallelism). Not reset per-iteration — only by the
-    // steering-hint fire below or by a turn that batches/edits.
-    let _serialReadOnlyStreak = 0;
-    let _level2FireCount = 0;
-
-    // Level-2 steering emitter shared by both ladder paths (single-call
-    // level-1 streak and the independent all-read-only streak). Sets the latch
-    // so it fires at most once per 5 turns regardless of which path triggered.
-    const _emitLevel2Steer = () => {
-        if (!editPushEligible && !readOnlyRole) return;
-        const iterations = getIterations();
-        _level2LatchAtIteration = iterations;
-        _level2FireCount += 1;
-        pushUserMessage({ role: 'user', content: level2SteerMessage(_level1FireCount, readOnlyRole, _level2FireCount), meta: 'hook' });
-        try {
-            appendAgentTrace({
-                sessionId,
-                iteration: iterations,
-                kind: 'steer',
-                payload: { tag: 'level2_steer', level1_fires: _level1FireCount, level2_fires: _level2FireCount, edit_count: getEditCount(), all_read_only_streak: _allReadOnlyStreak },
-                agent: sessionAgent || null,
-            });
-        } catch { /* best-effort */ }
-    };
-
-    return {
-        // Post-batch steering hint gate. `hintAlreadyFired` seeds the once-per-turn
-        // latch. Returns nothing;
-        // pushes at most one steering message via the ctx push callbacks.
-        emitPostBatchSteering(calls, hintAlreadyFired) {
-            const iterations = getIterations();
-            const editCount = getEditCount();
-            // Steering hint gate: at most ONE hint per turn.
-            let _hintFiredThisTurn = hintAlreadyFired;
-            // Missed-parallelism steering: 2+ consecutive turns of a single
-            // read-only tool call suggest the model isn't batching independent
-            // lookups. Nudge once, then reset (fires again after 2 more).
-            if (calls.length === 1 && isEagerDispatchable(calls[0].name, tools)) {
-                _serialReadOnlyStreak += 1;
-                // Escalation ladder (Step 1). Cumulative level-1 fires are tracked
-                // and NEVER reset. Once level-1 has fired >=3 times with ZERO edits,
-                // escalate to level-2 steering (latched once per 5 turns). The
-                // level-2 escalation always wins.
-                const _canEscalate = (_level1FireCount + 1) >= 3 && editCount === 0 && (iterations - _level2LatchAtIteration) >= 5;
-                if (_serialReadOnlyStreak >= 2 && !_hintFiredThisTurn) {
-                    _serialReadOnlyStreak = 0;
-                    _level1FireCount += 1;
-                    if (_canEscalate) {
-                        _emitLevel2Steer();
-                    } else {
-                        pushSystemReminder(editPushEligible
-                            ? 'Last 2 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.'
-                            : 'Last 2 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn.');
-                        try {
-                            appendAgentTrace({
-                                sessionId,
-                                iteration: iterations,
-                                kind: 'steer',
-                                payload: { tag: 'level1_batching', level1_fires: _level1FireCount, edit_count: editCount },
-                                agent: sessionAgent || null,
-                            });
-                        } catch { /* best-effort */ }
-                    }
-                    _hintFiredThisTurn = true;
-                }
-            } else {
-                _serialReadOnlyStreak = 0;
-            }
-            // Independent all-read-only escalation (audit finding): the level-1
-            // streak above only counts single-call turns, so a worker that runs
-            // 2+ read-only calls per turn escapes the ladder entirely. Track a
-            // cumulative count of consecutive turns where EVERY call is read-only
-            // (any count) and no edit has been made; at 12 such turns fire level-2
-            // directly (same once-per-5-turn latch), reset on any edit.
-            {
-                const _allReadOnly = calls.length > 0 && calls.every((c) => isEagerDispatchable(c.name, tools));
-                if (_allReadOnly && editCount === 0) {
-                    _allReadOnlyStreak += 1;
-                    if (_allReadOnlyStreak >= 12 && (iterations - _level2LatchAtIteration) >= 5 && !_hintFiredThisTurn) {
-                        _emitLevel2Steer();
-                        _hintFiredThisTurn = true;
-                    }
-                } else {
-                    _allReadOnlyStreak = 0;
-                }
-            }
-            // Detector: read-only shell (git status/log/diff --stat, ls/dir/cat/
-            // type/Get-ChildItem) inspects state the dedicated tools cover.
-            // Nudge toward them; never blocks execution.
-            {
-                if (!_hintFiredThisTurn && calls.some((c) => c?.name === 'shell' && _isReadOnlyShellCmd(c?.arguments?.command))) {
-                    pushSystemReminder('Read-only shell (git status/log/diff --stat, ls/dir/cat/type/Get-ChildItem) inspects state the dedicated tools cover — use grep/read/list/find/code_graph; shell is for changing state or running programs.');
-                    _hintFiredThisTurn = true;
-                }
-            }
-        },
-        // A zero-tool turn must not bridge any cross-turn ladder streak.
-        resetAllReadOnlyStreak() {
-            _allReadOnlyStreak = 0;
-            _serialReadOnlyStreak = 0;
-        },
-    };
-}