@north-light/crouter 0.3.173 → 0.3.175

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

@@ -16,36 +16,54 @@
 //                      Let it sleep; the resulting inbox delivery wakes it.
 //   • finished/asked → it pushed --final (done) or called `crtr ask` this turn.
 //                      Also fine.
+//   • structured     → a TERMINAL node has a pending structured-output request.
+//                      Valid requests reprompt with the schema; invalid requests
+//                      reprompt with an error and require manual cleanup.
 //   • 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, 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';
+import { readOutputRequest } from './structured-output.js';
 export { STALL_REPROMPT } from '../../shared/generated-context.js';
-function structuredOutputReprompt(nodeId) {
-    let schema = '{}';
-    try {
-        const request = readOutputRequest(nodeId);
-        if (request !== null)
-            schema = JSON.stringify(request.schema, null, 2);
-    }
-    catch {
-        /* keep a deterministic reprompt even if the schema file was corrupted */
-    }
-    return formatStructuredOutputReprompt(schema);
+/** Format the stop guard's reprompt for a valid structured-output request. */
+function formatValidStructuredOutputReprompt(schema) {
+    return formatStructuredOutputReprompt(JSON.stringify(schema, null, 2));
 }
-/** 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 function evaluateStop(nodeId, signals) {
+/** Format the stop guard's reprompt for an invalid structured-output request file. */
+function formatInvalidStructuredOutputReprompt(error) {
+    return (`Structured-output request file is invalid and cannot be used: ${error}\n\n` +
+        `You have two options:\n` +
+        `1. Remove the invalid file (the output-schema.json in your node directory has been corrupted)\n` +
+        `2. Fix the corruption if you know the original request schema\n\n` +
+        `After resolving the file, retry the submission. ` +
+        `If this is unexpected, escalate to the human using \`crtr human ask\`.`);
+}
+/** Decide what to do when a node stops. crtrd supplies every current-canvas
+ * fact; the broker contributes only whether its Pi-owned background job registry
+ * is still running work. */
+export function evaluateStop(nodeId, signals, backgroundJobsRunning = activeBackgroundBashJobs(contextDir(nodeId)).length > 0) {
     if (signals.pushedFinal)
         return { action: 'allow', reason: 'finished' };
     if (signals.askedHuman)
         return { action: 'allow', reason: 'escalated' };
     // A pending structured-output request overrides every stored-state dormancy
     // path: a post-final one-off follow-up still owes `submit` before it may stop.
-    if (hasPendingStructuredOutput(nodeId)) {
-        return { action: 'reprompt', reason: 'stalled', message: structuredOutputReprompt(nodeId) };
+    // Invalid requests surface an explicit error and require manual cleanup.
+    const outputState = readOutputRequest(nodeId);
+    if (outputState.state === 'valid') {
+        return {
+            action: 'reprompt',
+            reason: 'stalled',
+            message: formatValidStructuredOutputReprompt(outputState.request.schema),
+        };
+    }
+    if (outputState.state === 'invalid') {
+        return {
+            action: 'reprompt',
+            reason: 'stalled',
+            message: formatInvalidStructuredOutputReprompt(outputState.error),
+        };
     }
     // Canonically finalized follow-up cycles and already-terminal stored states
     // are not waiting to be re-prompted for a second final.
@@ -75,7 +93,7 @@ export function evaluateStop(nodeId, signals) {
     // sends an inbox message can suppress the stall guard.
     if (hasActiveLiveSubscription(nodeId)
         || hasLiveMessageWait(nodeId)
-        || activeBackgroundBashJobs(contextDir(nodeId)).length > 0)
+        || backgroundJobsRunning)
         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/stop-signals.d.ts

@@ -1,4 +1,7 @@
-import type { StopSignals } from './stop-guard.js';
+export interface StopSignals {
+    pushedFinal: boolean;
+    askedHuman: boolean;
+}
 export type StopSignal = keyof StopSignals;
 /** Record a successful command outcome for this broker process. The stophook
  * consumes the marker at settlement, so no broker-side canvas read is needed to

package/dist/core/runtime/stream-watchdog.js

@@ -9,11 +9,10 @@
 // queued-messages-never-delivered-diagnosis.md RC1/RC2). This watchdog aborts
 // the stalled stream itself, well before that backstop: if no engine event has
 // been relayed for STREAM_WATCHDOG_MS while a turn is active, the stream is
-// presumed dead — abort it. The turn ends with stopReason 'aborted' (or the
-// stophook's own error classification if the abort races a real error), the
-// existing connection-fault retry machinery (which arms on agent_end) owns
-// re-driving the turn, and the broker process — and its in-memory queues —
-// survive instead of being killed.
+// presumed dead — abort it. The watchdog stamps its abort on the live session
+// generation so settlement records an automatic pi→provider connection fault;
+// the existing fault-retry machinery owns re-driving the turn. The broker
+// process — and its in-memory queues — survives instead of being killed.
 const DEFAULT_STREAM_WATCHDOG_MS = 5 * 60_000; // 5 minutes.
 // Comfortably under the daemon's 20-minute WEDGE_QUIET_MS hard kick (crtrd.ts),
 // so this is the common-case recovery path and the daemon kick becomes the rare

package/dist/core/runtime/structured-output.d.ts

@@ -3,10 +3,23 @@ export interface StructuredOutputRequest {
     mode: StructuredOutputMode;
     schema: Record<string, unknown>;
 }
+/** Tri-state result of reading a structured-output request file. */
+export type StructuredOutputState = {
+    state: 'absent';
+} | {
+    state: 'valid';
+    request: StructuredOutputRequest;
+} | {
+    state: 'invalid';
+    error: string;
+};
 export declare function outputSchemaPath(nodeId: string): string;
 export declare function outputResultPath(nodeId: string): string;
 export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;
+/** Write a structured-output request atomically using temp-file-plus-rename. */
 export declare function writeOutputSchema(nodeId: string, mode: StructuredOutputMode, schema: Record<string, unknown>): string;
-export declare function readOutputRequest(nodeId: string): StructuredOutputRequest | null;
+/** Read a structured-output request with full validation and error reporting.
+ *  Returns a tri-state: absent (file doesn't exist), valid (parsed successfully),
+ *  or invalid (file exists but is malformed). */
+export declare function readOutputRequest(nodeId: string): StructuredOutputState;
 export declare function removeOutputSchema(nodeId: string): void;
-export declare function hasPendingStructuredOutput(nodeId: string): boolean;

package/dist/core/runtime/structured-output.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, renameSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { nodeDir, contextDir } from '../canvas/paths.js';
 import { InputError } from '../io.js';
 export function outputSchemaPath(nodeId) {
@@ -58,25 +59,50 @@ export function parseOutputSchemaValue(value) {
     }
     return parsed;
 }
+/** Write a structured-output request atomically using temp-file-plus-rename. */
 export function writeOutputSchema(nodeId, mode, schema) {
     const path = outputSchemaPath(nodeId);
     mkdirSync(dirname(path), { recursive: true });
     const request = { mode, schema };
-    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`, 'utf8');
+    const json = `${JSON.stringify(request, null, 2)}\n`;
+    const tmpPath = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(tmpPath, json, 'utf8');
+    renameSync(tmpPath, path);
     return path;
 }
+/** Read a structured-output request with full validation and error reporting.
+ *  Returns a tri-state: absent (file doesn't exist), valid (parsed successfully),
+ *  or invalid (file exists but is malformed). */
 export function readOutputRequest(nodeId) {
     const path = outputSchemaPath(nodeId);
     if (!existsSync(path))
-        return null;
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    if (!isObject(parsed))
-        return null;
+        return { state: 'absent' };
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        return { state: 'invalid', error: `could not read request file: ${err.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return { state: 'invalid', error: `request file is not valid JSON: ${err.message}` };
+    }
+    if (!isObject(parsed)) {
+        return { state: 'invalid', error: 'request file top-level value must be an object' };
+    }
     const mode = parsed['mode'];
     const schema = parsed['schema'];
-    if ((mode !== 'terminal' && mode !== 'oneoff') || !isObject(schema))
-        return null;
-    return { mode, schema };
+    if (mode !== 'terminal' && mode !== 'oneoff') {
+        return { state: 'invalid', error: `mode must be 'terminal' or 'oneoff', got ${JSON.stringify(mode)}` };
+    }
+    if (!isObject(schema)) {
+        return { state: 'invalid', error: `schema must be an object, got ${typeof schema}` };
+    }
+    return { state: 'valid', request: { mode, schema } };
 }
 export function removeOutputSchema(nodeId) {
     const path = outputSchemaPath(nodeId);
@@ -85,6 +111,3 @@ export function removeOutputSchema(nodeId) {
     }
     catch { /* already gone */ }
 }
-export function hasPendingStructuredOutput(nodeId) {
-    return existsSync(outputSchemaPath(nodeId));
-}

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

@@ -0,0 +1,25 @@
+import { type BindingId, type BindingResolution } from '../keybindings/index.js';
+export interface TmuxInstalledPair {
+    readonly table: string;
+    readonly key: string;
+}
+export interface TmuxInstallDiagnostic {
+    readonly code: 'occupied' | 'tmux-error';
+    readonly bindingId?: BindingId;
+    readonly gesture?: string;
+    readonly message: string;
+}
+export interface TmuxInstallResult {
+    readonly ok: boolean;
+    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 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;