@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/runtime/session-visibility.js

@@ -0,0 +1,83 @@
+// session-visibility.ts — transcript boundary projection for review companions.
+//
+// The companion node inherits the origin's full session context but the person
+// must see only the transcript from the moment the review started. A durable
+// marker (the boundary message) is appended to the session before the first
+// human-visible message, and this projection uses it to slice the visible
+// window.
+//
+// Applied at the two BrokerSnapshot.messages producers (live broker and
+// dormant node read) so every presenter — attach, web node viewer, inspect — is
+// boundary-safe by construction with no presenter-side changes.
+/** customType of the crtr-authored boundary marker that opens a review
+ *  companion's visible transcript. Data payload: `{ reviewId, originNodeId,
+ *  targetFile }` — per-review facts that complement the inheritance prefix.
+ *
+ *  The marker itself is a crtr-rendered divider shown to the person; everything
+ *  above it in the inherited session is context they cannot see.
+ */
+export const REVIEW_BOUNDARY_CUSTOM_TYPE = 'crtr-review-boundary';
+/** True when an entry is a durable review boundary, optionally for one review. */
+export function isReviewBoundary(entry, reviewId) {
+    if (entry === null || typeof entry !== 'object')
+        return false;
+    const candidate = entry;
+    return ((candidate.role === 'custom' || candidate.type === 'custom_message') &&
+        candidate.customType === REVIEW_BOUNDARY_CUSTOM_TYPE &&
+        (reviewId === undefined || candidate.details?.reviewId === reviewId));
+}
+function syntheticBoundary(timestamp) {
+    return {
+        role: 'custom',
+        customType: REVIEW_BOUNDARY_CUSTOM_TYPE,
+        content: 'Earlier conversation with the origin is not shown.',
+        display: true,
+        timestamp: timestamp ?? Date.now(),
+    };
+}
+/**
+ * Project snapshot messages to the visible window for a review companion.
+ *
+ * Contract (in evaluation order):
+ * 1. Marker present → slice from the **first** occurrence (marker included) to
+ *    the end. Everything before the marker is inherited context, hidden from
+ *    the person.
+ * 2. Not a review companion → return input unchanged (same reference). Ordinary
+ *    nodes are not filtered.
+ * 3. No marker and review companion → a leading compaction summary is replaced
+ *    with a synthetic boundary while its retained tail remains visible. Every
+ *    other markerless shape fails closed with the synthetic boundary alone.
+ */
+export function visibleMessages(messages, opts) {
+    const markerIndex = messages.findIndex((message) => isReviewBoundary(message));
+    if (markerIndex !== -1)
+        return messages.slice(markerIndex);
+    if (!opts.reviewCompanion)
+        return messages;
+    const [first, ...retainedTail] = messages;
+    if (first?.role === 'compactionSummary') {
+        return [syntheticBoundary(first.timestamp), ...retainedTail];
+    }
+    return [syntheticBoundary(first?.timestamp)];
+}
+/**
+ * Project a session tree to the review companion's visible transcript boundary.
+ *
+ * Pre-boundary ancestors are omitted rather than retained as empty structural
+ * shells, making each durable boundary a root in the returned forest. Once a
+ * boundary is crossed, its complete descendant subtree remains navigable. An
+ * absent boundary produces an empty tree, so picker previews never disclose an
+ * inherited entry before a mutation guard can reject its selection.
+ */
+export function boundaryRootedTree(tree) {
+    const retainSubtree = (node) => ({
+        ...node,
+        children: node.children.map(retainSubtree),
+    });
+    const project = (node) => {
+        if (isReviewBoundary(node.entry))
+            return [retainSubtree(node)];
+        return node.children.flatMap(project);
+    };
+    return tree.flatMap(project);
+}

package/dist/core/runtime/spawn.js

@@ -20,7 +20,7 @@ import { usage, brokerLaunchFailed } from '../errors.js';
 import { writeGoal } from './kickoff.js';
 import { appendSituationalContext } from './situational-context.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
-import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
+import { buildWakeBearings } from './bearings.js';
 import { contextDir, getNode, fullName, recordPid } from '../canvas/index.js';
 import { jobDir } from '../canvas/paths.js';
 import { openViewerWindow, focusOf, windowOfPane, currentTmux, focusWindow, } from './placement.js';
@@ -271,28 +271,13 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                 throw error;
             }
         }
-        // A fork inherits the SOURCE node's entire first-person conversation, so the
-        // identity re-assertion must ride the STRONGEST channel too, not only the
-        // session-start bearings (a trailing custom_message the model weighs only by
-        // recency). Prepend it to the kickoff PROMPT — the message that actually
-        // triggers the fork's first turn, so the model acts on "you are node X, a
-        // FORK of <source>, NOT them" as live instruction. When the daemon births this
-        // node from a scheduled `spawn` wake, the <crtr-wake> provenance block leads
-        // (so "a timer birthed you" precedes the task) — mirroring the fork-identity
-        // prepend. Only the pi argv prompt is reframed; the persisted goal (writeGoal
-        // above) keeps the raw task.
-        //
-        // A no-kickoff spawn (opts.prompt === '', see `node new --no-kickoff`) delivers
-        // NO positional prompt at all (buildPiArgv below omits it on an empty string),
-        // so no turn ever runs at spawn — neither block is meaningful without a turn to
-        // ride, so both are skipped even when forkFrom/wakeOrigin are set: the forked
-        // history still lands in the new session verbatim, it is simply not paired
-        // with an immediate re-assertion turn. Whatever real prompt arrives later is
-        // the fork's actual first turn.
+        // A scheduled birth prepends its clock provenance to the real task. Fork
+        // identity is owned exclusively by the session-start bearings message, which
+        // lands after copied history and before this prompt. An empty prompt starts
+        // the broker idle and carries neither a task nor wake provenance.
         const hasKickoff = opts.prompt !== '';
         const wakeBlock = hasKickoff && opts.wakeOrigin !== undefined ? `${buildWakeBearings(opts.wakeOrigin)}\n\n` : '';
-        const idBlock = hasKickoff && forkFrom !== undefined ? `${buildIdentityAssertion(meta.node_id)}\n\n` : '';
-        const kickoff = `${wakeBlock}${idBlock}${opts.prompt}`;
+        const kickoff = `${wakeBlock}${opts.prompt}`;
         // A child created DIRECTLY as an orchestrator (mode='orchestrator') boots
         // with the orchestrator persona but bypasses promote(), which is where a
         // roadmap scaffold would normally be seeded. Lay one down here (goal
@@ -387,12 +372,15 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                     // have bound view.sock yet. Hand the attach pane CRTR_ATTACH_WAIT_MS so
                     // it self-polls the socket until it accepts instead of connecting once,
                     // finding a cold socket, and closing the pane instantly — the exact
-                    // mechanism bootRoot uses. No pre-wait in this CLI subprocess.
+                    // mechanism bootRoot uses. Mark this as the initial auto-opened child
+                    // viewer too, so whip_mode can greet it without firing on ordinary
+                    // focus/attach paths. No pre-wait in this CLI subprocess.
                     const viewer = openViewerWindow(meta.node_id, parentViewer.session ?? '', {
                         name: fullName(meta),
                         cwd: opts.cwd,
                         besidePane: parentViewer.pane,
                         waitForBroker: true,
+                        initialWhip: true,
                     });
                     if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
                         session = viewer.session;

package/dist/core/runtime/stop-guard.d.ts

@@ -1,3 +1,4 @@
+export { STALL_REPROMPT } from '../../shared/generated-context.js';
 export interface StopSignals {
     /** Did the node call `push --final` (finish) this turn? */
     pushedFinal: boolean;
@@ -12,7 +13,6 @@ export type StopAction = {
     reason: 'stalled';
     message: string;
 };
-export declare const STALL_REPROMPT: string;
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
  *  signals — the stophook supplies the signals and enacts the action. */
 export declare function evaluateStop(nodeId: string, signals: StopSignals): StopAction;

package/dist/core/runtime/stop-guard.js

@@ -2,25 +2,27 @@
 //
 // Every time a node's pi process stops, we ask one question: is this node
 // *legitimately waiting*? A node is legitimately waiting iff it holds an ACTIVE
-// subscription to a live node, or explicitly awaits a live controller's message
-// — something that can actually wake it. (A passive sub won't wake you, so it
-// doesn't count.)
+// subscription to a live node, explicitly awaits a live controller's message,
+// or has a live file-backed background bash job whose completion sends an inbox
+// message — something that can actually wake it. (A passive sub won't wake you,
+// so it doesn't count.)
 //
 //   • resident       → an interactable / human-driven node is NEVER forced to
 //                      submit a final: stopping to go dormant is always
 //                      legitimate (woken by inbox/human). Keyed on the LIFECYCLE
 //                      value, not on parent/mode — what matters is residency.
-//   • waiting        → a TERMINAL node holding an active live subscription is a
-//                      dormant orchestrator awaiting its workers. Let it sleep;
-//                      a child's push wakes it (and idle-releases its window).
+//   • waiting        → a TERMINAL node has an active live subscription, an
+//                      explicit controller wait, or a live background bash job.
+//                      Let it sleep; the resulting inbox delivery wakes it.
 //   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
 //                      Also fine.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
-import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode } from '../canvas/index.js';
+import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode, contextDir } from '../canvas/index.js';
+import { activeBackgroundBashJobs } from '../bash-jobs.js';
+import { formatStructuredOutputReprompt, STALL_REPROMPT } from '../../shared/generated-context.js';
 import { hasPendingStructuredOutput, readOutputRequest } from './structured-output.js';
-export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
-    "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human ask` if you are blocked or need the user.";
+export { STALL_REPROMPT } from '../../shared/generated-context.js';
 function structuredOutputReprompt(nodeId) {
     let schema = '{}';
     try {
@@ -31,7 +33,7 @@ function structuredOutputReprompt(nodeId) {
     catch {
         /* keep a deterministic reprompt even if the schema file was corrupted */
     }
-    return `You must call the \`submit\` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n\`\`\`json\n${schema}\n\`\`\``;
+    return formatStructuredOutputReprompt(schema);
 }
 /** Decide what to do when a node stops. Pure given the canvas + this turn's
  *  signals — the stophook supplies the signals and enacts the action. */
@@ -68,9 +70,12 @@ export function evaluateStop(nodeId, signals) {
     if (hasPendingCancelOnWakeCron(nodeId))
         return { action: 'allow', reason: 'scheduled' };
     // A terminal node holding something live to wake it is legitimately awaiting.
-    // Parentage alone is deliberately absent: only a subscription or explicit
-    // controller wait can suppress the stall guard.
-    if (hasActiveLiveSubscription(nodeId) || hasLiveMessageWait(nodeId))
+    // Parentage alone is deliberately absent: only an active subscription, an
+    // explicit controller wait, or a live background bash job whose completion
+    // sends an inbox message can suppress the stall guard.
+    if (hasActiveLiveSubscription(nodeId)
+        || hasLiveMessageWait(nodeId)
+        || activeBackgroundBashJobs(contextDir(nodeId)).length > 0)
         return { action: 'allow', reason: 'awaiting' };
     // A terminal node with nothing live and no final pushed has stalled.
     return { action: 'reprompt', reason: 'stalled', message: STALL_REPROMPT };

package/dist/core/runtime/surface-bg.js

@@ -1,7 +1,7 @@
 // surface-bg.ts — the "distinct popup surface" background, theme-derived.
 //
 // crtr's overlays and popups must read as a SEPARATE surface from the normal one
-// (CTO ruling, taste/inline-ui-placement #11): a popup whose background matches
+// (CTO ruling, insights/terminal-ui/inline-ui-placement #11): a popup whose background matches
 // the surface has invisible edges, so you can't tell where the float begins. We
 // paint them with the active pi theme's `selectedBg` role — theme-derived, so it
 // adapts to light/dark and is ONE centralized knob, not a scattered hardcode.

package/dist/core/runtime/tmux-chrome.d.ts

@@ -1 +1 @@
-export { installTmuxBindings, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux.js';
+export { installTmuxBindings, occupiedTmuxRootGestures, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux.js';

package/dist/core/runtime/tmux-chrome.js

@@ -1,4 +1,4 @@
 // tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
 // The ONLY non-placement module allowed to import the tmux driver, per the
 // §5.1 lint. Re-exports the server chrome callers need.
-export { installTmuxBindings, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, } from './tmux.js';
+export { installTmuxBindings, occupiedTmuxRootGestures, legacyInboxKeyFile, sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, } from './tmux.js';

package/dist/core/runtime/tmux.d.ts

@@ -1,4 +1,4 @@
-import { type BindingId, type BindingResolution } from '../keybindings/index.js';
+import { type AttachBindingId, type BindingId, type BindingResolution } from '../keybindings/index.js';
 /** POSIX single-quote escaping for one shell word. */
 export declare function shellQuote(s: string): string;
 export declare function inTmux(): boolean;
@@ -142,8 +142,7 @@ export declare function paneRunning(pane: string): boolean;
  *  display-message each. */
 export declare function listLivePanes(): Set<string> | null;
 /** The working directory of a pane (`display-message -p -t <pane>
- *  '#{pane_current_path}'`). Used to preserve a view monitor's cwd across a
- *  view-cycle respawn so project-scoped views still resolve. Null if tmux fails. */
+ *  '#{pane_current_path}'`). Null if tmux fails. */
 export declare function paneCurrentPath(pane: string): string | null;
 /** Flash a transient status-line toast on the client showing `pane` (or the
  *  current client when `pane` is omitted). `ms` sets the display duration. Used
@@ -151,14 +150,36 @@ export declare function paneCurrentPath(pane: string): string | null;
  *  Best-effort; never throws. */
 export declare function displayMessage(message: string, pane?: string, ms?: number): boolean;
 /** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
- *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
- *  view-nav cycle can read it back and switch to the next/prev view in place.
  *  Best-effort; never throws. */
 export declare function setPaneOption(pane: string, name: string, value: string): boolean;
 /** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
  *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
  *  error so an unset option yields an empty string. undefined if tmux fails. */
 export declare function getPaneOption(pane: string, name: string): string | undefined;
+/** Pane option recording when an attach viewer was last started or focused.
+ *  `liveViewerPanes` uses it to select the most recently used viewer. */
+export declare const VIEWER_STAMP_OPTION = "@crtr_viewer_at";
+/** Stamp a viewer pane without blocking the input path that observed focus.
+ *  Stamps are monotonically increasing and their tmux writes are serialized, so
+ *  two rapid focus events cannot leave an older pane with the newer stamp. */
+export declare function stampViewerPaneAsync(pane: string): void;
+export interface LiveViewerPane {
+    readonly pane: string;
+    readonly session: string;
+    readonly nodeId: string;
+    readonly stampMs: number;
+}
+/** List viewer panes tagged by a running local attach viewer. Pane tags can
+ *  survive a killed process, so every tag must match a viewer for the same node.
+ *  Shell-hosted viewers are recognized through their live child process. Unstamped
+ *  valid viewers remain eligible at stamp zero while an older viewer rolls forward. */
+export declare function liveViewerPanes(socket?: string): LiveViewerPane[];
+/** Deliver one private attach-control sequence literally into a viewer pane.
+ *  `-l` bypasses tmux key-table lookup, so delivery cannot re-trigger a root
+ *  binding that initiated it. */
+export declare function sendAttachControl(socket: string | undefined, pane: string, actionId: AttachBindingId): boolean;
+/** Show a tmux status-line message on a specific client when one is known. */
+export declare function displayClientMessage(socket: string | undefined, client: string | undefined, text: string): boolean;
 export interface RespawnPaneOpts {
     /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
     pane: string;
@@ -242,6 +263,13 @@ export interface TmuxInstallResult {
     readonly installed: readonly TmuxInstalledPair[];
     readonly diagnostics: readonly TmuxInstallDiagnostic[];
 }
+/** Effective crouter gestures that tmux's root table currently consumes before
+ * pane input can see them. One list-keys snapshot serves the whole query. */
+export declare function occupiedTmuxRootGestures(gestures: readonly string[]): readonly string[];
 export declare function legacyInboxKeyFile(): string;
-/** Reconcile the tmux server with one immutable crouter binding snapshot. */
-export declare function installTmuxBindings(bindings?: BindingResolution<BindingId>): TmuxInstallResult;
+export declare function inboxToggleTmuxCommand(): string[];
+/** Reconcile the tmux server with one immutable crouter settings snapshot.
+ * Passing snapshots is hermetic; the no-argument front door reads both user
+ * settings from the same config read. The server lock covers the entire
+ * manifest read, restore, install, fingerprint, and write transition. */
+export declare function installTmuxBindings(bindingSnapshot?: BindingResolution<BindingId>, passthroughSnapshot?: readonly BindingId[]): TmuxInstallResult;