@north-light/crouter 0.3.311 → 0.3.313

package/dist/pi-extensions/canvas-stophook.js

@@ -24,15 +24,14 @@ import { envNodeId } from '../shared/env.js';
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { contextDir, jobDir } from '../core/canvas/paths.js';
-import { markBusy, clearBusy, touchBusy } from '../core/runtime/busy.js';
-import { clearFault } from '../core/runtime/fault.js';
+import { mutateBrokerFault, recordBrokerTurn } from '../core/runtime/broker/daemon-ops.js';
 import { clearStopSignals, consumeStopSignals } from '../core/runtime/stop-signals.js';
 import { bindBrokerSession, brokerExtensionState, relaunchBrokerRoot, settleBroker } from '../core/runtime/broker/daemon-ops.js';
 import { emitEvent } from '../core/events/emit.js';
 import { activeBackgroundBashJobs } from '../core/bash-jobs.js';
 import { CONTEXT_NUDGE_CUSTOM_TYPE, formatCard } from '../shared/generated-context.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
-import { runRefreshAbort } from '../core/runtime/broker/extension-abort.js';
+import { clearRefusedTurn, refuseTurn, runRefreshAbort } from '../core/runtime/broker/extension-abort.js';
 import { announceMessageOrigin } from '../core/runtime/stamp/channel.js';
 /** Condense a tool call into one short line for the activity cue. Picks the most
  *  identifying arg (command / path / pattern / description), collapses whitespace,
@@ -283,15 +282,7 @@ export function registerCanvasStophook(pi) {
             catch { /* Pi shutdown is local best-effort */ }
         }
     };
-    // Wedge-heartbeat throttle: message_update/tool_execution_update can fire many
-    // times per second while streaming, and touchBusy is a disk write — rate-limit
-    // it to at most once per HEARTBEAT_THROTTLE_MS. The daemon's wedge grace is
-    // measured in minutes, so this throttle costs it nothing. Also clears any
-    // stale `daemon→node` wedge fault at the same throttled cadence: a sign of
-    // life should both refresh the heartbeat marker AND clear a stale wedge
-    // notice as one coherent act, same as every coarser progress site below
-    // (tool execution, turn_end, agent_settled) already does. clearFault is
-    // a cheap no-op when no fault exists, so this stays safe to call every time.
+    // Streaming updates are rate-limited because daemon wedge grace is measured in minutes.
     const HEARTBEAT_THROTTLE_MS = 3_000;
     let lastHeartbeatAt = 0;
     const heartbeat = () => {
@@ -299,8 +290,10 @@ export function registerCanvasStophook(pi) {
         if (now - lastHeartbeatAt < HEARTBEAT_THROTTLE_MS)
             return;
         lastHeartbeatAt = now;
-        touchBusy(nodeId);
-        clearFault(nodeId, { link: 'daemon→node' });
+        void Promise.all([
+            recordBrokerTurn(nodeId, { event: 'progress' }),
+            mutateBrokerFault(nodeId, { op: 'clear', link: 'daemon→node' }),
+        ]).catch((error) => emitDaemonOperationFailure('turn_progress', error));
     };
     // session_start — capture pi's session id, and detect `/new`.
     //
@@ -385,13 +378,19 @@ export function registerCanvasStophook(pi) {
     // agent_start — pi entered a turn. Mark the node mid-turn (busy) so a
     // focus-away while it is genuinely working backstages it (Invariant F2)
     // rather than reaping it. Cleared only after the whole run settles.
-    pi.on('agent_start', () => {
-        // A fresh turn started. Keep any active fault marker in place so the daemon's
-        // retry accounting survives a failed retry cycle; just mark the turn busy.
+    pi.on('agent_start', async (_event, ctx) => {
+        // A turn may not enter Pi until crtrd has fenced and recorded it. Otherwise
+        // a broker that lost daemon ownership can run work with no durable turn.
         try {
-            markBusy(nodeId);
+            const result = await recordBrokerTurn(nodeId, { event: 'started' });
+            if (!result.applied)
+                throw new Error('daemon refused turn open');
+        }
+        catch (error) {
+            emitDaemonOperationFailure('turn_open', error);
+            ctx?.ui?.notify?.('Turn refused: the broker no longer owns this node.', 'error');
+            refuseTurn(() => ctx?.abort?.());
         }
-        catch { /* best-effort */ }
     });
     // input — a new user-directed run is beginning. This is the ONLY place stop
     // signals are cleared: `agent_start` re-fires for pi's automatic retries and
@@ -403,6 +402,7 @@ export function registerCanvasStophook(pi) {
     // of this same broker is discarded here, when the next prompt arrives (the pid
     // stamp only rules out a PRIOR broker's markers, not this broker's own).
     pi.on('input', () => {
+        clearRefusedTurn();
         try {
             clearStopSignals(nodeId);
         }
@@ -415,8 +415,7 @@ export function registerCanvasStophook(pi) {
         try {
             lastActivity = summarizeActivity(String(event?.toolName ?? ''), event?.args);
             flushTelemetry(jobDirPath, totalIn, totalOut, model, lastContext, lastActivity);
-            touchBusy(nodeId); // wedge heartbeat: a fresh tool starting is a sign of life
-            clearFault(nodeId, { link: 'daemon→node' }); // a tool actually starting clears any prior wedge notice
+            heartbeat(); // a fresh tool starting is a sign of life
         }
         catch { /* best-effort */ }
     });
@@ -458,8 +457,7 @@ export function registerCanvasStophook(pi) {
     // refreshes on its first tool — the desired outcome.)
     pi.on('tool_execution_end', async (_event, ctx) => {
         try {
-            touchBusy(nodeId); // wedge heartbeat: the tool returning is a sign of life
-            clearFault(nodeId, { link: 'daemon→node' }); // a tool that was "stuck" just returned — the wedge notice was resolved
+            heartbeat(); // a tool that returned is a sign of life
             if ((await brokerExtensionState(nodeId)).node.intent === 'refresh') {
                 // Stop this turn immediately so the large context does not keep running.
                 // The broker clears Pi's queued steering/follow-up messages inside this
@@ -479,7 +477,12 @@ export function registerCanvasStophook(pi) {
     // finish transition, focus teardown, presence clear, and fault clear. Other
     // session swaps keep the same node and need no durable settlement.
     pi.on('session_shutdown', async (event, ctx) => {
-        clearBusy(nodeId); // turn marker is meaningless once Pi is exiting
+        try {
+            await recordBrokerTurn(nodeId, { event: 'closed', end_reason: 'teardown-aborted' });
+        }
+        catch (error) {
+            emitDaemonOperationFailure('turn_close_teardown', error);
+        }
         if (event?.reason !== 'quit')
             return;
         try {
@@ -526,9 +529,16 @@ export function registerCanvasStophook(pi) {
             lastContext = contextTokens;
         // Fire-and-forget: flushTelemetry uses synchronous fs writes and never throws.
         flushTelemetry(jobDirPath, totalIn, totalOut, model, contextTokens, lastActivity);
-        touchBusy(nodeId); // wedge heartbeat: a turn ending is a sign of life
-        clearFault(nodeId, { link: 'daemon→node' }); // reaching turn_end proves this turn wasn't wedged
-        clearFault(nodeId, { link: 'pi→provider' }); // a completed provider round-trip proves this episode is over
+        heartbeat(); // reaching turn_end proves this turn was not wedged
+        try {
+            await Promise.all([
+                mutateBrokerFault(nodeId, { op: 'clear', link: 'daemon→node' }),
+                mutateBrokerFault(nodeId, { op: 'clear', link: 'pi→provider' }),
+            ]);
+        }
+        catch (error) {
+            emitDaemonOperationFailure('turn_end_fault_clear', error);
+        }
         // Will the agent run CONTINUE past this turn? Deterministic at turn_end:
         // the loop keeps going exactly when this assistant message carried tool
         // calls and the run wasn't aborted/errored (those end unconditionally,
@@ -598,10 +608,16 @@ export function registerCanvasStophook(pi) {
     pi.on('agent_settled', async (_event, ctx) => {
         const event = stagedAgentEnd;
         stagedAgentEnd = null;
-        // Busy is a broker-local job marker. The daemon operation below owns the
-        // fault marker, stop policy, lifecycle transition, focus, and inbox cursor
-        // decision even when Pi had no stageable final agent_end payload.
-        clearBusy(nodeId);
+        // crtrd owns the durable turn close, fault marker, stop policy, lifecycle
+        // transition, focus, and mail decision even when Pi had no stageable final
+        // agent_end payload.
+        try {
+            await recordBrokerTurn(nodeId, { event: 'closed', end_reason: 'settled' });
+        }
+        catch (error) {
+            emitDaemonOperationFailure('turn_close', error);
+            return;
+        }
         const messages = Array.isArray(event?.messages) ? event.messages : [];
         const last = lastAssistantMessage(messages);
         const stopReason = typeof last?.stopReason === 'string' ? last.stopReason : '';

package/dist/shared/env.d.ts

@@ -1,5 +1,6 @@
 /** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
 export declare function envNodeId(): string | undefined;
+export declare function envExecutionId(): string | undefined;
 /** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
 export declare function envProfileId(): string | undefined;
 /** The current node's working directory (`CRTR_NODE_CWD`), or undefined. */

package/dist/shared/env.js

@@ -26,6 +26,9 @@
 export function envNodeId() {
     return process.env['CRTR_NODE_ID'];
 }
+export function envExecutionId() {
+    return process.env['CRTR_EXECUTION_ID'];
+}
 /** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
 export function envProfileId() {
     return process.env['CRTR_PROFILE_ID'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.311",
+  "version": "0.3.313",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.311",
+  "version": "0.3.313",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.311",
+      "version": "0.3.313",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,17 +5206,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.311",
+      "version": "0.3.313",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.311",
+      "version": "0.3.313",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.311",
+      "version": "0.3.313",
       "license": "UNLICENSED",
       "dependencies": {
         "@north-light/crouter-api": "^0.3.295"

package/dist/clients/attach/__tests__/page-block.test.js

@@ -1,54 +0,0 @@
-import assert from 'node:assert/strict';
-import { mkdtempSync, utimesSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import test from 'node:test';
-import { atomicWriteJson, pageManifestPath, pagePath } from '../../../core/human/convention.js';
-import { derivePageManifestFromDocument } from '../../../core/human/page.js';
-import { sanitize } from '../../inbox/tui/ansi.js';
-import { PageBlockComponent } from '../render/page-block.js';
-function proposal(intro) {
-    return `const DOCS = ['Local stack', 'Guest home', 'Data and dependencies', 'Troubleshooting'];
-function Proposal({ docs }) {
-  return (
-    <Card>
-      <p>Move the <code>{docs.length}</code> operational areas behind focused pointers.</p>
-      <ul>{docs.map((doc) => <li key={doc}><strong>{doc}</strong> reference</li>)}</ul>
-    </Card>
-  );
-}
-export default function DevMemorySplit() {
-  return (
-    <Page title="Northlight dev memory" subtitle="Choose the documentation shape">
-      <p>${intro}</p>
-      <Proposal docs={DOCS} />
-      <UserQuestion id="decision" label="Approve the split?" body="The current file is 4,189 words." mode="single" options={[{ id: 'approve', label: 'Approve' }, { id: 'keep', label: 'Keep one file' }]} />
-    </Page>
-  );
-}
-`;
-}
-test('an inline page renders dynamic display JSX beside its manifest question and refreshes source-only revisions', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'crtr-page-block-'));
-    const source = proposal('The current guide mixes routing and operational detail.');
-    const manifest = derivePageManifestFromDocument(source);
-    writeFileSync(pagePath(dir), source);
-    atomicWriteJson(pageManifestPath(dir), manifest);
-    const block = new PageBlockComponent('dev-memory', dir, () => 'open it');
-    const rendered = sanitize(block.render(88).join('\n'));
-    assert.match(rendered, /The current guide mixes routing and operational detail\./);
-    assert.match(rendered, /Move the 4 operational areas behind focused pointers\./);
-    assert.match(rendered, /Local stack.*reference/);
-    assert.match(rendered, /Troubleshooting.*reference/);
-    assert.match(rendered, /Approve the split\?/);
-    assert.match(rendered, /The current file is 4,189 words\./);
-    assert.match(rendered, /Keep one file/);
-    const revised = proposal('The replacement keeps the intent router short.');
-    writeFileSync(pagePath(dir), revised);
-    const future = new Date(Date.now() + 2_000);
-    utimesSync(pagePath(dir), future, future);
-    assert.equal(block.refresh(), true);
-    const refreshed = sanitize(block.render(88).join('\n'));
-    assert.match(refreshed, /The replacement keeps the intent router short\./);
-    assert.doesNotMatch(refreshed, /mixes routing and operational detail/);
-});

package/dist/clients/inbox/review-visibility.d.ts

@@ -1,5 +0,0 @@
-import type { TicketSummary } from '../../core/human/types.js';
-/** Match the daemon's opaque inbox id: canonical tickets root, NUL, bridge id. */
-export declare function opaqueTicketId(canonicalTicketsRoot: string, bridgeNodeId: string): string;
-/** Retain local page rows and only daemon-visible review rows. */
-export declare function filterVisibleReviewTickets(tickets: readonly TicketSummary[], visibleIds: ReadonlySet<string>): TicketSummary[];

package/dist/clients/inbox/review-visibility.js

@@ -1,19 +0,0 @@
-import { createHash } from 'node:crypto';
-import { realpathSync } from 'node:fs';
-import { basename } from 'node:path';
-import { ticketsRoot } from '../../core/human/root.js';
-/** Match the daemon's opaque inbox id: canonical tickets root, NUL, bridge id. */
-export function opaqueTicketId(canonicalTicketsRoot, bridgeNodeId) {
-    return createHash('sha256').update(`${canonicalTicketsRoot}\0${bridgeNodeId}`, 'utf8').digest('hex');
-}
-/** Retain local page rows and only daemon-visible review rows. */
-export function filterVisibleReviewTickets(tickets, visibleIds) {
-    let canonicalTicketsRoot;
-    try {
-        canonicalTicketsRoot = realpathSync(ticketsRoot());
-    }
-    catch {
-        return tickets.filter((ticket) => ticket.kind !== 'review');
-    }
-    return tickets.filter((ticket) => ticket.kind !== 'review' || visibleIds.has(opaqueTicketId(canonicalTicketsRoot, basename(ticket.dir))));
-}

package/dist/commands/canvas-rebuild-index.d.ts

@@ -1,2 +0,0 @@
-import type { LeafDef } from '../core/command.js';
-export declare const canvasRebuildIndexLeaf: LeafDef;

package/dist/commands/canvas-rebuild-index.js

@@ -1,46 +0,0 @@
-// `crtr canvas rebuild-index` — re-derive the node-table index from on-disk metas.
-//
-// canvas.db's node rows are a derived index over `nodes/<id>/meta.json`. When the
-// db is absent or stale relative to the metas — most concretely a remote/guest
-// deployment's recreate-from-template, where node data lives on a durable Volume
-// but canvas.db lives on local disk that the recreate wipes — this verb rebuilds
-// the rows (identity columns) from the surviving metas via `rebuildIndex()`, so a
-// subsequent `node lifecycle revive` finds its node again.
-//
-// Fails loud if metas are present but the rebuild yields zero rows: a silent
-// empty db there means the revive would no-op against nothing.
-//
-// Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
-import { defineLeaf } from '../core/command.js';
-import { cliClient, rethrowAsCliError } from './api-client.js';
-export const canvasRebuildIndexLeaf = defineLeaf({
-    name: 'rebuild-index',
-    description: 're-derive node rows in canvas.db from on-disk nodes/<id>/meta.json',
-    whenToUse: 'canvas.db is missing or stale relative to the on-disk node metas and you need its node rows re-derived — most concretely after a remote/guest deployment\'s recreate-from-template, where node data survives on a durable Volume but canvas.db (local disk) was wiped, so a `node lifecycle revive` would otherwise find no row. Identity columns are rebuilt from each meta; runtime columns (status/intent/pi_pid/window/tmux) take their quiescent defaults, and subscribes_to edges are left intact',
-    help: {
-        name: 'canvas rebuild-index',
-        summary: 're-derive canvas.db node rows from on-disk metas; fails loud if metas exist but yield no rows',
-        params: [],
-        output: [
-            { name: 'metas', type: 'integer', required: true, constraint: 'How many `nodes/<id>/meta.json` files were found on disk.' },
-            { name: 'rows', type: 'integer', required: true, constraint: 'How many node rows exist in canvas.db after the rebuild.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Upserts a node row for every on-disk meta (identity columns only); runtime columns take schema defaults on freshly created rows.',
-            'Leaves subscribes_to edges intact; re-derives spawned_by provenance edges from each meta.',
-            'Throws (non-zero exit) if metas are present but the rebuild produced zero rows.',
-        ],
-    },
-    run: async () => {
-        // The rebuild + the fail-loud “metas exist but 0 rows” guard run server-side
-        // (crtrd owns canvas.db and the on-disk metas under the same CRTR_HOME).
-        try {
-            const res = await cliClient().rebuildIndex();
-            return { metas: res.metas, rows: res.rows };
-        }
-        catch (err) {
-            rethrowAsCliError(err);
-        }
-    },
-});

package/dist/core/__tests__/human-cancel-guard.test.js

@@ -1,110 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/human-cancel-guard.test.ts
-//
-// N2 — humanCancel on a ticket the store has already settled must short-circuit to
-// {canceled:false, reason:'already_resolved'} rather than throwing. A second cancel
-// is the ordinary race (the human submits while the agent retracts), so the client
-// guard in queue.ts turns the daemon's 409 into an idempotent no-op.
-import { test, before, after, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, existsSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { createNode } from '../canvas/canvas.js';
-import { closeDb } from '../canvas/db.js';
-import { nodeDir } from '../canvas/paths.js';
-import { atomicWriteJson, bindTicketReplyRoute, pageManifestPath } from '../human/convention.js';
-import { cancelTicket, readTicketResult } from '../human/tickets.js';
-import { humanCancel } from '../../commands/human/queue.js';
-import { createApiServer } from '../../daemon/api/server.js';
-import { apiSocketPath } from '../canvas/paths.js';
-// `humanCancel` is a thin CLI forwarder since the crtrd-API re-plumb: its
-// already-canceled short-circuit guard runs client-side after fetching the node
-// through `cliClient().getNode`. Stand up a real in-process `createApiServer()`
-// bound to the isolated CRTR_HOME's socket so that fetch resolves against the
-// genuine daemon seam (never an autostarted subprocess, never a mock client).
-let server;
-async function waitForSocket(path) {
-    for (let i = 0; i < 200; i++) {
-        if (existsSync(path))
-            return;
-        await new Promise((r) => setTimeout(r, 25));
-    }
-    throw new Error(`api socket never bound at ${path}`);
-}
-let home;
-function node(id) {
-    return {
-        node_id: id,
-        name: id,
-        created: new Date().toISOString(),
-        cwd: '/tmp/work',
-        kind: 'human',
-        mode: 'base',
-        lifecycle: 'terminal',
-        status: 'active',
-    };
-}
-/** Publish a reply-bearing page ticket in the bridge node's directory, exactly as
- *  `human send` does: reply route first, then the page manifest. */
-function publishTicket(id, slots = []) {
-    const dir = nodeDir(id);
-    mkdirSync(dir, { recursive: true });
-    bindTicketReplyRoute(dir, id);
-    atomicWriteJson(pageManifestPath(dir), {
-        schema: 'crtr.page/v2',
-        dialect: 'jsx',
-        title: id,
-        subtitle: 'Acknowledge this ticket so the request can proceed.',
-        delivery: { placement: 'inline', inbox: true, reply: true },
-        document: 'page.tsx',
-        steps: 1,
-        slots,
-    });
-}
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-humancancel-'));
-    process.env['CRTR_HOME'] = home;
-});
-beforeEach(async () => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    mkdirSync(home, { recursive: true });
-    server = createApiServer();
-    await waitForSocket(apiSocketPath());
-});
-afterEach(async () => {
-    await server?.close();
-});
-after(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-});
-test('cancel accepts newer page config and treats an already-canceled ticket as a no-op', async () => {
-    const newerId = 'newerPage';
-    createNode(node(newerId));
-    publishTicket(newerId, [{
-            id: 'decision',
-            kind: 'options',
-            step: 0,
-            config: {
-                label: 'Decision',
-                body: 'Choose one.',
-                options: [{ id: 'yes', label: 'Yes' }],
-                mode: 'single',
-                futureField: true,
-            },
-        }]);
-    const canceled = (await humanCancel.run({ ticket_id: newerId }));
-    assert.equal(canceled['canceled'], true);
-    assert.equal(canceled['ticket_id'], newerId);
-    assert.equal(readTicketResult(nodeDir(newerId))?.kind, 'canceled');
-    const settledId = 'canceledJob';
-    createNode(node(settledId));
-    publishTicket(settledId);
-    cancelTicket(nodeDir(settledId), { actor: 'human' });
-    const settled = (await humanCancel.run({ ticket_id: settledId }));
-    assert.equal(settled['canceled'], false);
-    assert.equal(settled['reason'], 'already_resolved');
-    assert.equal(settled['ticket_id'], settledId);
-});

package/dist/core/__tests__/human-deliver.test.d.ts

@@ -1 +0,0 @@
-export {};