@north-light/crouter 0.3.168 → 0.3.169

package/dist/commands/sys/daemon.js

@@ -85,6 +85,7 @@ const daemonRestart = defineLeaf({
         outputKind: 'object',
         effects: [
             'The daemon acknowledges immediately, then after a short grace tears its whole broker fleet down, releases its claim, spawns a successor on the runtime generation currently selected, and exits.',
+            'Each torn-down broker hands its foreground bash commands to the file-backed background job system; they keep running and report completion by urgent inbox message.',
             'Every node it tore down — including the caller — is resumed by the successor through the ordinary startup recovery sweep.',
             'The calling process is killed as part of that teardown, AFTER this result is returned.',
         ],

package/dist/core/__tests__/revive.test.js

@@ -35,6 +35,7 @@ import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
 import { createNode, getNode, subscribe, updateNode, clearPid } from '../canvas/canvas.js';
 import { armFollowUpWork } from '../canvas/human-work-outbox.js';
+import { armCron, hasPendingCancelOnWakeCron } from '../canvas/crons.js';
 import { readInboxSince } from '../feed/inbox.js';
 import { closeDb } from '../canvas/db.js';
 import { buildPiArgv, CANVAS_EXTENSIONS } from '../runtime/launch.js';
@@ -346,6 +347,53 @@ test('reviveNode PROCEEDS when the node has NO fleet entry — cycle counter bum
         await h.dispose();
     }
 });
+// ---------------------------------------------------------------------------
+// BUG LOCKED — a recovery relaunch must not eat the node's armed deadline.
+// A node armed `crtr node wait deadline` and dormed; its broker then exited and
+// the daemon respawned it (fleet.#respawn → reviveNode). reviveNode used to
+// cancel every cancel-on-wake cron unconditionally, so the deadline vanished
+// with nothing having woken the node and the wait could never settle. A wake
+// (inbox delivery, attach, explicit revive) still consumes it.
+// ---------------------------------------------------------------------------
+function armDeadline(anchor, cronId) {
+    armCron({
+        cron_id: cronId,
+        name: `deadline:${anchor}`,
+        created_by: anchor,
+        command: 'true',
+        fire_at: new Date(Date.now() + 3_600_000).toISOString(),
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: anchor,
+        cancel_on_wake: true,
+        cwd: home,
+        env_json: null,
+        profile: null,
+        scope: 'profile',
+        run_timeout_s: 300,
+        overlap: 'skip',
+        on_output: 'on-failure',
+        sink: '',
+        tier: 'normal',
+    });
+}
+test('a recovery relaunch keeps the armed deadline; a wake revive consumes it', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-deadline' });
+    try {
+        const recovered = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-1' });
+        armDeadline(recovered, 'cron-recovery');
+        reviveNode(recovered, { resume: true, recovery: true });
+        assert.equal(hasPendingCancelOnWakeCron(recovered), true, 'the daemon replacing a dead broker is not a wake — the deadline survives so the wait can still settle');
+        const woken = h.fabricateBrokerNode({ status: 'active', intent: null, pi_pid: deadPid(), pi_session_id: 'uuid-2' });
+        armDeadline(woken, 'cron-wake');
+        reviveNode(woken, { resume: true });
+        assert.equal(hasPendingCancelOnWakeCron(woken), false, 'a wake revive won the race and cancels the deadline');
+    }
+    finally {
+        await h.dispose();
+    }
+});
 test('reviveNode fresh-fallback clears the stale session identity (Major-3: no phantom stranded-relaunch)', async () => {
     const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-freshfb' });
     try {

package/dist/core/bash-jobs.d.ts

@@ -4,7 +4,9 @@ export interface BashJobPaths {
     cmdSh: string;
     jobLog: string;
     jobExit: string;
+    jobRun: string;
     jobBg: string;
+    jobDone: string;
     /** Process-group id of the job's detached supervisor, written at spawn. It is
      * what makes a job stoppable from outside the agent that started it (the
      * Inspector's cancel) — without it on disk, only the agent's own handoff
@@ -42,25 +44,22 @@ export interface BashJobStatus {
     logPath: string;
 }
 /** Every live backgrounded bash job for this node — job.bg present, job.exit
- * absent — whether handed off by the menu or auto-backgrounded at the valve's
- * deadline. Read-only; never mutates. Distinct from (and shares no code path
- * with) the foreground-only `runningBashJobs` above: that scanner deliberately
- * EXCLUDES job.bg, this one REQUIRES it, so reusing one for the other would
- * corrupt foreground-admission semantics. Skips malformed/partially-written
+ * absent — whether handed off by the menu, the valve deadline, or broker
+ * termination. Read-only; never mutates. Skips malformed/partially-written
  * directories. Returns oldest-first by startedAtMs. */
 export declare function activeBackgroundBashJobs(contextDir: string): BashJobStatus[];
-/** The start time (ms epoch) of the OLDEST still-foreground bash command for
+export type BackgroundBashJobResult = 'backgrounded' | 'already-backgrounded' | 'finished' | 'missing';
+/** Atomically hand one foreground job to its detached supervisor. The rename
+ * is the ownership decision: exactly one caller can move job.run to job.bg,
+ * while the supervisor races to move the same source to job.done. */
+export declare function backgroundBashJob(paths: BashJobPaths): BackgroundBashJobResult;
+/** The start time (ms epoch) of the oldest still-foreground bash command for
  * this node, or undefined when none is running. This is the authoritative
- * source for the attach viewer's R4 "background it" footer hint: it reads the
- * exact same on-disk contract the valve writes (a job directory exists with
- * no job.bg and no job.exit while the command is running in the foreground,
- * and the valve deletes the directory the moment the command finishes or is
- * aborted — see canvas-bash-valve.ts), so a fresh or reconnected attach (which
- * has no memory of a broker-relayed tool-execution event) sees exactly what's
- * really running, and a viewer never needs its own call-id tracking that could
- * go stale across a broker/session replacement. */
+ * source for the attach viewer's background hint: a fresh or reconnected
+ * attach reads the same job.run state that backgrounding and completion race
+ * to claim, without viewer-local call tracking that can go stale. */
 export declare function oldestRunningBashJobStartedAtMs(contextDir: string): number | undefined;
-/** Request immediate handoff for every bash command still waiting on pi. The
- * valve observes job.bg within one poll, resolves the tool call, and leaves its
- * detached supervisor to notify the node when the real command exits. */
+/** Request immediate handoff for every bash command still waiting on pi. Only
+ * the caller that wins the job.run → job.bg rename reports the job as handed
+ * off; another backgrounder or the foreground-completion path may win the race. */
 export declare function backgroundRunningBashJobs(contextDir: string): BashJobPaths[];

package/dist/core/bash-jobs.js

@@ -1,9 +1,9 @@
-// File-backed control plane for bash commands that have been handed off by the
-// canvas bash valve. The valve starts every command in one of these directories;
-// the prefix menu requests backgrounding by creating job.bg. Keeping that signal
-// on disk means the command can outlive its pi process and still report its exit.
+// File-backed control plane for bash commands started by the canvas bash valve.
+// Every foreground command owns job.run; backgrounding atomically renames it to
+// job.bg, while foreground completion renames it to job.done. The detached
+// supervisor can therefore outlive pi and still decide whether to report exit.
 import { randomBytes } from 'node:crypto';
-import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export function bashJobsDir(contextDir) {
     return join(contextDir, 'jobs');
@@ -16,7 +16,9 @@ export function bashJobPaths(contextDir, jobId) {
         cmdSh: join(dir, 'cmd.sh'),
         jobLog: join(dir, 'job.log'),
         jobExit: join(dir, 'job.exit'),
+        jobRun: join(dir, 'job.run'),
         jobBg: join(dir, 'job.bg'),
+        jobDone: join(dir, 'job.done'),
         jobPgid: join(dir, 'job.pgid'),
     };
 }
@@ -94,11 +96,8 @@ export function formatBashElapsed(ms) {
     return `${hours}h ${String(minutes).padStart(2, '0')}m`;
 }
 /** Every live backgrounded bash job for this node — job.bg present, job.exit
- * absent — whether handed off by the menu or auto-backgrounded at the valve's
- * deadline. Read-only; never mutates. Distinct from (and shares no code path
- * with) the foreground-only `runningBashJobs` above: that scanner deliberately
- * EXCLUDES job.bg, this one REQUIRES it, so reusing one for the other would
- * corrupt foreground-admission semantics. Skips malformed/partially-written
+ * absent — whether handed off by the menu, the valve deadline, or broker
+ * termination. Read-only; never mutates. Skips malformed/partially-written
  * directories. Returns oldest-first by startedAtMs. */
 export function activeBackgroundBashJobs(contextDir) {
     let entries;
@@ -127,9 +126,27 @@ export function activeBackgroundBashJobs(contextDir) {
     }
     return jobs.sort((a, b) => a.startedAtMs - b.startedAtMs);
 }
-/** Every still-foreground bash command for this node. A completed command has
- * job.exit; an already-backgrounded one has job.bg and must not be selected a
- * second time. Invalid or concurrently-removed directories are ignored. */
+/** Atomically hand one foreground job to its detached supervisor. The rename
+ * is the ownership decision: exactly one caller can move job.run to job.bg,
+ * while the supervisor races to move the same source to job.done. */
+export function backgroundBashJob(paths) {
+    try {
+        renameSync(paths.jobRun, paths.jobBg);
+        return 'backgrounded';
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        if (existsSync(paths.jobBg))
+            return 'already-backgrounded';
+        if (existsSync(paths.jobDone))
+            return 'finished';
+        return 'missing';
+    }
+}
+/** Every still-foreground bash command for this node. job.run is the sole live
+ * foreground state; a handoff or foreground completion atomically removes it.
+ * Invalid or concurrently-removed directories are ignored. */
 function runningBashJobs(contextDir) {
     let entries;
     try {
@@ -140,21 +157,16 @@ function runningBashJobs(contextDir) {
     }
     return entries.flatMap((jobId) => {
         const paths = bashJobPaths(contextDir, jobId);
-        return existsSync(paths.cmdSh) && existsSync(paths.jobLog) && !existsSync(paths.jobExit) && !existsSync(paths.jobBg)
+        return existsSync(paths.cmdSh) && existsSync(paths.jobLog) && existsSync(paths.jobRun)
             ? [paths]
             : [];
     });
 }
-/** The start time (ms epoch) of the OLDEST still-foreground bash command for
+/** The start time (ms epoch) of the oldest still-foreground bash command for
  * this node, or undefined when none is running. This is the authoritative
- * source for the attach viewer's R4 "background it" footer hint: it reads the
- * exact same on-disk contract the valve writes (a job directory exists with
- * no job.bg and no job.exit while the command is running in the foreground,
- * and the valve deletes the directory the moment the command finishes or is
- * aborted — see canvas-bash-valve.ts), so a fresh or reconnected attach (which
- * has no memory of a broker-relayed tool-execution event) sees exactly what's
- * really running, and a viewer never needs its own call-id tracking that could
- * go stale across a broker/session replacement. */
+ * source for the attach viewer's background hint: a fresh or reconnected
+ * attach reads the same job.run state that backgrounding and completion race
+ * to claim, without viewer-local call tracking that can go stale. */
 export function oldestRunningBashJobStartedAtMs(contextDir) {
     let oldest;
     for (const paths of runningBashJobs(contextDir)) {
@@ -166,25 +178,14 @@ export function oldestRunningBashJobStartedAtMs(contextDir) {
     }
     return oldest;
 }
-/** Request immediate handoff for every bash command still waiting on pi. The
- * valve observes job.bg within one poll, resolves the tool call, and leaves its
- * detached supervisor to notify the node when the real command exits. */
+/** Request immediate handoff for every bash command still waiting on pi. Only
+ * the caller that wins the job.run → job.bg rename reports the job as handed
+ * off; another backgrounder or the foreground-completion path may win the race. */
 export function backgroundRunningBashJobs(contextDir) {
     const backgrounded = [];
     for (const paths of runningBashJobs(contextDir)) {
-        try {
-            // A job may exit or be claimed by another prefix press between the scan
-            // and this write. Recheck the two terminal/control files so that stale
-            // candidates never masquerade as a successful handoff.
-            if (existsSync(paths.jobExit) || existsSync(paths.jobBg))
-                continue;
-            writeFileSync(paths.jobBg, '');
+        if (backgroundBashJob(paths) === 'backgrounded')
             backgrounded.push(paths);
-        }
-        catch {
-            // The valve owns cleanup; a concurrently removed directory is simply no
-            // longer a running command to hand off.
-        }
     }
     return backgrounded;
 }

package/dist/core/canvas/__tests__/render-remote.test.js

@@ -102,6 +102,31 @@ test('dashboardRowsAllFromSource shows a node watched through its live broker',
     const rows = await dashboardRowsAllFromSource(source);
     assert.equal(rows[0]?.viewed, true);
 });
+test('enrichRowsFromSource serializes a full dashboard source read', async () => {
+    const nodeRows = ['a', 'b', 'c'].map(row);
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const source = {
+        getNode: async (id) => {
+            inFlight++;
+            maxInFlight = Math.max(maxInFlight, inFlight);
+            await new Promise((resolve) => setImmediate(resolve));
+            inFlight--;
+            return meta(id);
+        },
+        getRow: async () => null,
+        listNodes: async () => nodeRows,
+        subscriptionsOf: async () => [],
+        subscribersOf: async () => [],
+        view: async () => [],
+        ticketCountsForView: async () => ({}),
+        hasActiveLiveSubscription: async () => false,
+    };
+    const rows = await dashboardRowsAllFromSource(source);
+    await enrichRowsFromSource(source, rows);
+    assert.equal(maxInFlight, 1);
+    assert.deepEqual(rows.map((entry) => entry.name), ['a', 'b', 'c']);
+});
 let home;
 let localCwd;
 let sessionFile;

package/dist/core/canvas/crons.d.ts

@@ -160,8 +160,9 @@ export declare function setCronLastOutputHash(cron_id: string, hash: string): vo
  *  terminal node that stopped without finishing. */
 export declare function hasPendingCancelOnWakeCron(anchor_node: string): boolean;
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
- *  Two seams call it: reviveNode on every revive-for-any-reason (the wake won
- *  the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
+ *  Two seams call it: reviveNode on a WAKE — every revive except a recovery
+ *  relaunch, which only replaces a dead broker instance and leaves the wait
+ *  open (the wake won the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
  *  with the node, so its deadline must not fire against a finalized or closed
  *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
  *  Kills any in-flight

package/dist/core/canvas/crons.js

@@ -219,8 +219,9 @@ export function hasPendingCancelOnWakeCron(anchor_node) {
         .get(anchor_node) !== undefined);
 }
 /** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
- *  Two seams call it: reviveNode on every revive-for-any-reason (the wake won
- *  the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
+ *  Two seams call it: reviveNode on a WAKE — every revive except a recovery
+ *  relaunch, which only replaces a dead broker instance and leaves the wait
+ *  open (the wake won the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
  *  with the node, so its deadline must not fire against a finalized or closed
  *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
  *  Kills any in-flight

package/dist/core/canvas/render-source.js

@@ -430,14 +430,18 @@ export async function enrichRowsFromSource(source, rows, asks) {
         return;
     const remote = source instanceof RemoteCanvasSource;
     const askMap = asks ?? {};
-    await Promise.all(todo.map(async (row) => {
+    // A full dashboard may contain thousands of rows. Keep source reads serial:
+    // ApiCanvasSource turns each into a unix-socket request, and an unbounded
+    // Promise.all can overflow crtrd's accept backlog then spuriously trigger
+    // the client's cold-daemon path even though the daemon is still running.
+    for (const row of todo) {
         const meta = await source.getNode(row.node_id);
         if (meta !== null)
             row.name = fullName(meta);
         row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
         row.asks = askMap[row.node_id] ?? 0;
         row.enriched = true;
-    }));
+    }
 }
 /** goal (initial-prompt.md) and session parts are local disk reads — suppressed
  *  to undefined for a remote source. */

package/dist/core/runtime/revive-all.js

@@ -95,7 +95,9 @@ export function reviveAll() {
     const result = { revived: [], failed: [] };
     for (const meta of listDisconnected()) {
         try {
-            reviveNode(meta.node_id, { resume: true });
+            // Reconnecting a disconnected broker is recovery, not a wake — a node
+            // waiting on an armed deadline keeps it across the sweep.
+            reviveNode(meta.node_id, { resume: true, recovery: true });
             result.revived.push(meta.node_id);
         }
         catch (err) {

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

@@ -49,10 +49,17 @@ export interface ReviveResult {
 /** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
  *  meta. Opens no viewer (engine-only).
  *
+ *  `recovery: true` marks a launch that only replaces a broker instance which
+ *  died or was torn down — the daemon's respawn after a broker exit, and the
+ *  `reviveAll` sweep over disconnected nodes. Nothing external arrived for the
+ *  node, so such a launch is NOT a wake and does not consume the node's armed
+ *  deadline (see the cancelCronsOnWake call below).
+ *
  *  Throws if the node does not exist. All other failures propagate as-is —
  *  callers (daemon, command) decide how to handle.
  */
 export declare function reviveNode(nodeId: string, opts: {
     resume: boolean;
     wakeReason?: ReviveWakeReason;
+    recovery?: boolean;
 }): ReviveResult;

package/dist/core/runtime/revive.js

@@ -92,6 +92,12 @@ function isUnstartedBirth(nodeId) {
 /** Relaunch `nodeId`'s broker engine from its persisted recipe and update canvas
  *  meta. Opens no viewer (engine-only).
  *
+ *  `recovery: true` marks a launch that only replaces a broker instance which
+ *  died or was torn down — the daemon's respawn after a broker exit, and the
+ *  `reviveAll` sweep over disconnected nodes. Nothing external arrived for the
+ *  node, so such a launch is NOT a wake and does not consume the node's armed
+ *  deadline (see the cancelCronsOnWake call below).
+ *
  *  Throws if the node does not exist. All other failures propagate as-is —
  *  callers (daemon, command) decide how to handle.
  */
@@ -309,9 +315,15 @@ export function reviveNode(nodeId, opts) {
     // unchecked result, is what scopes a later diagnostic read to this attempt.
     clearFault(nodeId);
     const bootFault = beginBootFaultAttempt(nodeId);
-    // A cron armed --cancel-on-wake belongs to the dormancy being left, so any
-    // revive of its anchor deletes it.
-    cancelCronsOnWake(nodeId);
+    // A cron armed --cancel-on-wake belongs to the dormancy being left, so a WAKE
+    // of its anchor deletes it — an inbox delivery, an attach, an explicit
+    // revive. A recovery relaunch is not a wake: the broker instance died or was
+    // torn down and the daemon is putting the same waiting node back on its feet,
+    // with nothing external having arrived. The wait the deadline bounds is still
+    // open, so the deadline survives — the same rule lifecycle.ts applies to the
+    // `crash` transition (a deadline MUST survive instance death).
+    if (opts.recovery !== true)
+        cancelCronsOnWake(nodeId);
     let launched;
     try {
         launched = headlessBrokerHost.launch(nodeId, inv, {

package/dist/daemon/fleet.js

@@ -352,6 +352,10 @@ export class DaemonFleet {
             reviveNode(nodeId, {
                 resume: action === 'respawn-resume',
                 wakeReason: cleanAbort ? 'runtime-restart-abort' : undefined,
+                // Replacing a dead broker instance is recovery, not a wake: nothing
+                // external arrived for this node, so an armed deadline survives the
+                // relaunch instead of being consumed by it.
+                recovery: true,
             });
         }
         catch (err) {

package/dist/pi-extensions/canvas-bash-valve.js

@@ -27,7 +27,7 @@
 import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
-import { bashJobPaths, formatBashElapsed, newBashJobId } from '../core/bash-jobs.js';
+import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId } from '../core/bash-jobs.js';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
 // ---------------------------------------------------------------------------
 // Deadline — 5 minutes by default, overridable via CRTR_BASH_VALVE_MS
@@ -49,7 +49,8 @@ function resolveValveMs() {
 //
 // Positional argv (never interpolated into the script — the command text
 // lives only in cmd.sh):
-//   $1 cmd.sh   $2 job.log   $3 job.exit   $4 job.bg   $5 jobId   $6 nodeId
+//   $1 cmd.sh     $2 job.log   $3 job.exit   $4 job.run
+//   $5 job.done   $6 job.bg    $7 jobId      $8 nodeId
 //
 // `--` before the paths is a dummy $0 (a standard `bash -c script -- args`
 // idiom) so the real payload lands at $1 onward.
@@ -58,13 +59,38 @@ const SUPERVISOR_SCRIPT = [
     'bash "$1" > "$2" 2>&1',
     'ec=$?',
     'echo "$ec" > "$3"',
-    'if [ -f "$4" ]; then',
-    '  crtr node message send "Background bash job $5 finished (exit $ec). Log: $2  Command: $1" --to "$6" --tier urgent || true',
+    'if mv "$4" "$5" 2>/dev/null; then',
+    '  :',
+    'elif [ -f "$6" ]; then',
+    '  crtr node message send "Background bash job $7 finished (exit $ec). Log: $2  Command: $1" --to "$8" --tier urgent || true',
     'fi',
 ].join('\n');
 function makeJobPaths(contextDir) {
     return bashJobPaths(contextDir, newBashJobId());
 }
+const liveForegroundJobs = new Set();
+let terminationHandoffInstalled = false;
+/** The broker is about to exit. Persist every foreground handoff synchronously
+ * before pi's own termination listener aborts its active tool calls. */
+function backgroundLiveJobsForTermination() {
+    for (const paths of [...liveForegroundJobs]) {
+        try {
+            backgroundBashJob(paths);
+            liveForegroundJobs.delete(paths);
+        }
+        catch (err) {
+            process.stderr.write(`crtr: failed to background bash job ${paths.jobId} during broker termination: ${err.message}\n`);
+        }
+    }
+}
+function installTerminationHandoff() {
+    if (terminationHandoffInstalled)
+        return;
+    terminationHandoffInstalled = true;
+    process.prependListener('SIGTERM', backgroundLiveJobsForTermination);
+    if (process.platform !== 'win32')
+        process.prependListener('SIGHUP', backgroundLiveJobsForTermination);
+}
 function killGroup(pgid) {
     try {
         process.kill(-pgid, 'SIGTERM');
@@ -194,6 +220,7 @@ export function createValveOperations(nodeId, contextDir) {
                 mkdirSync(paths.dir, { recursive: true });
                 writeFileSync(paths.cmdSh, command);
                 writeFileSync(paths.jobLog, '');
+                writeFileSync(paths.jobRun, '');
                 let offset = 0;
                 let settled = false;
                 let pgid;
@@ -205,6 +232,7 @@ export function createValveOperations(nodeId, contextDir) {
                         clearInterval(interval);
                     if (signal)
                         signal.removeEventListener('abort', onAbort);
+                    liveForegroundJobs.delete(paths);
                 };
                 const finish = (act) => {
                     if (settled)
@@ -213,7 +241,7 @@ export function createValveOperations(nodeId, contextDir) {
                     teardown();
                     act();
                 };
-                function background(auto = false) {
+                function finishBackground(auto = false) {
                     const elapsed = formatBashElapsed(Date.now() - startedAt);
                     const notice = `\n[backgrounded as job ${paths.jobId} after ${elapsed} in the foreground${auto ? ' (auto)' : ''}. ` +
                         `It will interrupt you with a message when it exits. ` +
@@ -222,8 +250,35 @@ export function createValveOperations(nodeId, contextDir) {
                     finish(() => resolve({ exitCode: 0 }));
                     // Backgrounded — job dir persists (inspectable); no cleanup here.
                 }
+                function finishForeground() {
+                    offset = tailOnce(paths.jobLog, offset, onData);
+                    const exitCode = readExitCode(paths.jobExit);
+                    finish(() => resolve({ exitCode }));
+                    cleanupJobDir(paths.dir);
+                }
+                function requestBackground(auto = false) {
+                    const state = backgroundBashJob(paths);
+                    if (state === 'backgrounded' || state === 'already-backgrounded') {
+                        finishBackground(auto);
+                        return;
+                    }
+                    if (state === 'finished') {
+                        finishForeground();
+                        return;
+                    }
+                    finish(() => reject(new Error(`bash job ${paths.jobId} disappeared before it could be backgrounded`)));
+                    cleanupJobDir(paths.dir);
+                }
                 function onAbort() {
-                    tailOnce(paths.jobLog, offset, onData);
+                    offset = tailOnce(paths.jobLog, offset, onData);
+                    if (existsSync(paths.jobBg)) {
+                        finishBackground();
+                        return;
+                    }
+                    // Once the command has written its exit code, let the supervisor
+                    // finish the job.run → job.done transition before cleanup.
+                    if (existsSync(paths.jobExit))
+                        return;
                     if (pgid)
                         killGroup(pgid);
                     finish(() => reject(new Error('aborted')));
@@ -234,7 +289,7 @@ export function createValveOperations(nodeId, contextDir) {
                 const execution = resolveExecutionCwd(cwd);
                 if (execution.warning)
                     onData(Buffer.from(execution.warning));
-                const child = spawn('bash', ['-c', SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobBg, paths.jobId, nodeId], {
+                const child = spawn('bash', ['-c', SUPERVISOR_SCRIPT, '--', paths.cmdSh, paths.jobLog, paths.jobExit, paths.jobRun, paths.jobDone, paths.jobBg, paths.jobId, nodeId], {
                     cwd: execution.cwd,
                     detached: true,
                     stdio: 'ignore',
@@ -242,27 +297,31 @@ export function createValveOperations(nodeId, contextDir) {
                 });
                 child.on('error', (err) => {
                     finish(() => reject(err));
+                    cleanupJobDir(paths.dir);
                 });
                 pgid = child.pid;
                 // The detached supervisor IS the group leader, so its pid is the pgid.
                 // Persisting it is what lets a human stop the job from the Inspector
                 // later; the agent's own handoff notice quotes the same number.
-                if (pgid !== undefined)
+                if (pgid !== undefined) {
                     writeFileSync(paths.jobPgid, String(pgid));
+                    liveForegroundJobs.add(paths);
+                }
                 child.unref();
                 interval = setInterval(() => {
                     offset = tailOnce(paths.jobLog, offset, onData);
-                    if (existsSync(paths.jobExit)) {
-                        offset = tailOnce(paths.jobLog, offset, onData);
-                        const exitCode = readExitCode(paths.jobExit);
-                        finish(() => resolve({ exitCode }));
-                        cleanupJobDir(paths.dir);
+                    if (existsSync(paths.jobDone)) {
+                        finishForeground();
                         return;
                     }
                     if (existsSync(paths.jobBg)) {
-                        background();
+                        finishBackground();
                         return;
                     }
+                    // job.exit is written before the supervisor claims job.done. Do not
+                    // time out or delete the directory during that in-progress exit.
+                    if (existsSync(paths.jobExit))
+                        return;
                     const elapsedMs = Date.now() - startedAt;
                     if (timeout !== undefined && timeout > 0) {
                         if (elapsedMs >= timeout * 1000) {
@@ -273,10 +332,8 @@ export function createValveOperations(nodeId, contextDir) {
                         }
                         return;
                     }
-                    if (elapsedMs >= valveMs) {
-                        writeFileSync(paths.jobBg, '');
-                        background(true);
-                    }
+                    if (elapsedMs >= valveMs)
+                        requestBackground(true);
                 }, POLL_MS);
             });
         },
@@ -292,6 +349,7 @@ export default function (pi) {
     const contextDir = process.env['CRTR_CONTEXT_DIR'];
     if (contextDir === undefined || contextDir.trim() === '')
         return; // defensive; always set alongside CRTR_NODE_ID
+    installTerminationHandoff();
     // Registered on session_start (fires for startup, new, resume, fork, and
     // /reload) so we get ctx.cwd — the same session cwd the builtin bash tool
     // is built against. registerTool replaces the builtin by name; re-firing on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.168",
+  "version": "0.3.169",
   "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.168",
+  "version": "0.3.169",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.168",
+      "version": "0.3.169",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {