@north-light/crouter 0.3.158 → 0.3.159

package/dist/commands/node.js

@@ -27,7 +27,8 @@ import { profilesStateBlock } from '../core/profiles/state-block.js';
 import { stateBlock } from '../core/help.js';
 import { fuzzyMatch } from '../core/canvas/browse/model.js';
 import { loadPins, savePins } from '../core/canvas/browse/pins.js';
-import { backgroundRunningBashJobs, formatBashElapsed, jobStartedAtMs } from '../core/bash-jobs.js';
+import { existsSync, writeFileSync } from 'node:fs';
+import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobPaths, formatBashElapsed, jobStartedAtMs, readJobPgid, tailJobLog } from '../core/bash-jobs.js';
 // The API seam — every canvas mutation/read routes through the daemon (B-1).
 import { cliClient, cliCanvasSource, ApiCanvasSource, rethrowAsCliError, getNodeOrNull } from './api-client.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
@@ -842,16 +843,153 @@ const nodeBashBackground = defineLeaf({
         return `Handed ${result['backgrounded']} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
     },
 });
+const nodeBashList = defineLeaf({
+    name: 'list',
+    description: 'list a node’s live background bash jobs',
+    whenToUse: 'the Inspector’s jobs section reads this to show what a node handed off to the background',
+    tier: 'hidden',
+    help: {
+        name: 'node bash list',
+        summary: 'read every still-running background bash job owned by one node',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose background jobs to list. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+            { kind: 'flag', name: 'tail', type: 'int', required: false, default: 0, constraint: 'Include this many trailing log lines per job (0 = none).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, started_at, elapsed_ms, log_path, pgid, log_tail} for every live background job.' },
+        ],
+        outputKind: 'object',
+        effects: ['Reads the node context jobs directory. Changes nothing.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '')
+            id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found for the bash job list', next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+        }
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const now = Date.now();
+        const tail = Math.max(0, Math.trunc(Number(input['tail'] ?? 0)));
+        const dir = contextDir(node.node_id);
+        const jobs = activeBackgroundBashJobs(dir).map((job) => ({
+            job_id: job.jobId,
+            command: job.command,
+            started_at: new Date(job.startedAtMs).toISOString(),
+            elapsed_ms: now - job.startedAtMs,
+            log_path: job.logPath,
+            pgid: readJobPgid(dir, job.jobId) ?? null,
+            log_tail: tailJobLog(job.logPath, tail),
+        }));
+        return { node_id: node.node_id, jobs };
+    },
+    render: (result) => {
+        const jobs = result['jobs'];
+        if (jobs.length === 0)
+            return `No background bash jobs for ${result['node_id']}.`;
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${job.command.split('\n')[0]}\n  log: ${job.log_path}`).join('\n');
+    },
+});
+/** SIGTERM the job's process group, give it a moment, then SIGKILL. Returns
+ *  false only when the group was already gone at the first signal. */
+function stopJobGroup(pgid) {
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+const nodeBashKill = defineLeaf({
+    name: 'kill',
+    description: 'stop one of a node’s background bash jobs',
+    whenToUse: 'a human watching the Inspector wants a long-running background job to stop now, or an agent is abandoning work it backgrounded',
+    tier: 'hidden',
+    help: {
+        name: 'node bash kill',
+        summary: 'terminate a background bash job’s process group and tell the owning node it was canceled',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The job that was stopped.' },
+            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when the process group was still alive and received SIGTERM.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Sends SIGTERM (then SIGKILL) to the job’s whole process group, stopping the command and anything it forked.',
+            'Records the job’s exit so it stops showing as live, and sends the owning node an urgent inbox message saying the job was canceled — which steers that node mid-turn.',
+        ],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '')
+            id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found for the bash job', next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+        }
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        const dir = contextDir(node.node_id);
+        const paths = bashJobPaths(dir, jobId);
+        if (!existsSync(paths.dir)) {
+            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
+        }
+        const pgid = readJobPgid(dir, jobId);
+        if (pgid === undefined) {
+            throw new InputError({
+                error: 'not_stoppable',
+                message: `job ${jobId} recorded no process group`,
+                next: `It started before crtr persisted one. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
+            });
+        }
+        const signaled = stopJobGroup(pgid);
+        // The supervisor shares the group it leads, so it usually dies with the
+        // command and never writes job.exit. Record the cancellation ourselves —
+        // that sentinel is what retires the job from every live-jobs read.
+        await new Promise((r) => setTimeout(r, 400));
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        if (!existsSync(paths.jobExit))
+            writeFileSync(paths.jobExit, '143\n');
+        await cliClient().sendMessage(node.node_id, {
+            body: `Background bash job ${jobId} was canceled from the Inspector before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
+            tier: 'urgent',
+        });
+        return { node_id: node.node_id, job_id: jobId, signaled };
+    },
+    render: (result) => `Canceled background bash job ${result['job_id']} for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
+});
 const nodeBash = defineBranch({
     name: 'bash',
     description: 'control file-backed bash jobs owned by a node',
-    whenToUse: 'the tmux prefix menu needs to hand a running bash command off without waiting for the automatic timeout',
+    whenToUse: 'a running bash command must be handed off, listed, or stopped — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
     tier: 'hidden',
     help: {
         name: 'node bash',
         summary: 'control file-backed bash jobs owned by a node',
     },
-    children: [nodeBashBackground],
+    children: [nodeBashBackground, nodeBashList, nodeBashKill],
 });
 export const surfaceNodeIdLeaf = defineLeaf({
     name: 'id',

package/dist/commands/surface-inspect.js

@@ -8,17 +8,18 @@ import { runCoreView } from '../core/tui/host.js';
 export const surfaceInspectLeaf = defineLeaf({
     name: 'inspect',
     description: 'host the native Inspector for one node',
-    whenToUse: 'you want a live native screen for a node’s overview, raw record, and owner-scoped crons. Use node inspect show for the underlying one-shot data read instead.',
+    whenToUse: 'you want a live native screen for a node’s overview, raw record, owner-scoped crons, and live background bash jobs. Use node inspect show for the underlying one-shot data read instead.',
     help: {
         name: 'surface inspect',
         summary: 'host the native Inspector in this pane (the attach viewer opens it as a tmux popup)',
+        // sections: overview · schedule (armed crons) · jobs (live background bash) · raw
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id or resolvable reference to inspect.' },
-            { kind: 'flag', name: 'section', type: 'enum', choices: ['overview', 'schedule', 'raw'], required: false, default: 'overview', constraint: 'Section focused when the Inspector opens.' },
+            { kind: 'flag', name: 'section', type: 'enum', choices: ['overview', 'schedule', 'jobs', 'raw'], required: false, default: 'overview', constraint: 'Section focused when the Inspector opens.' },
         ],
         output: [],
         outputKind: 'object',
-        effects: ['Reads node and cron data through crtr subprocesses and crtrd. Takes over the hosting pane (or popup) until it quits.'],
+        effects: ['Reads node, cron, and background bash job data through crtr subprocesses and crtrd. Takes over the hosting pane (or popup) until it quits.'],
     },
     run: async (input) => {
         const node = input['node'];

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -75,7 +75,7 @@ async function waitFor(predicate, timeoutMs = 3000, stepMs = 10) {
         await wait(stepMs);
     }
 }
-test('coalesce inlines short reports with their absolute path and only hints for remaining canonical refs', () => {
+test('coalesce inlines short report bodies with a trailing artifact pointer and only hints for remaining canonical refs', () => {
     freshNode('child');
     const child = createNode({
         node_id: 'child',
@@ -93,8 +93,10 @@ test('coalesce inlines short reports with their absolute path and only hints for
     const digest = coalesce([
         finalizeInboxEntry({ from: 'child', tier: 'normal', kind: 'update', label: 'short report', ref: 'child:reports/short-update.md' }),
     ]);
-    assert.match(digest, new RegExp(`\\[update\\] short report at ${reportPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:`));
-    assert.match(digest, /short report body/);
+    // The label is NOT reprinted above the body it duplicates; the path trails it.
+    assert.doesNotMatch(digest, /\[update\] short report/);
+    assert.match(digest, /\[update\]\n {4}short report body\n/);
+    assert.match(digest, new RegExp(`\\(report: ${reportPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\)`));
     assert.doesNotMatch(digest, /Dereference a ref with/);
     const guidance = 'Dereference a ref with `crtr canvas history read <ref>`.';
     const canonical = coalesce([

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

@@ -5,9 +5,20 @@ export interface BashJobPaths {
     jobLog: string;
     jobExit: string;
     jobBg: 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
+     * notice knows the group to signal. */
+    jobPgid: string;
 }
 export declare function bashJobsDir(contextDir: string): string;
 export declare function bashJobPaths(contextDir: string, jobId: string): BashJobPaths;
+/** The job's supervisor process group, or undefined for a job started before
+ * pgid was persisted (or a partially-written dir). */
+export declare function readJobPgid(contextDir: string, jobId: string): number | undefined;
+/** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
+ * rather than the whole file, which for a long-running job can be enormous. */
+export declare function tailJobLog(logPath: string, count: number): string[];
 /** Mint a fresh job id — `${Date.now()}-${hex}`. The sole minting site; the
  * valve calls this instead of building the literal inline so the epoch-ms
  * prefix is a real contract shared with its parser (jobStartedAtMs), not an

package/dist/core/bash-jobs.js

@@ -3,7 +3,7 @@
 // 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.
 import { randomBytes } from 'node:crypto';
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 export function bashJobsDir(contextDir) {
     return join(contextDir, 'jobs');
@@ -17,8 +17,48 @@ export function bashJobPaths(contextDir, jobId) {
         jobLog: join(dir, 'job.log'),
         jobExit: join(dir, 'job.exit'),
         jobBg: join(dir, 'job.bg'),
+        jobPgid: join(dir, 'job.pgid'),
     };
 }
+/** The job's supervisor process group, or undefined for a job started before
+ * pgid was persisted (or a partially-written dir). */
+export function readJobPgid(contextDir, jobId) {
+    try {
+        const n = Number(readFileSync(bashJobPaths(contextDir, jobId).jobPgid, 'utf8').trim());
+        return Number.isInteger(n) && n > 1 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
+ * rather than the whole file, which for a long-running job can be enormous. */
+export function tailJobLog(logPath, count) {
+    if (count <= 0)
+        return [];
+    const WINDOW = 64 * 1024;
+    let fd;
+    try {
+        const size = statSync(logPath).size;
+        const start = Math.max(0, size - WINDOW);
+        const buf = Buffer.alloc(Math.min(size, WINDOW));
+        fd = openSync(logPath, 'r');
+        readSync(fd, buf, 0, buf.length, start);
+        const text = buf.toString('utf8');
+        // A partial first line (we cut mid-line) is dropped, not shown truncated.
+        const lines = (start > 0 ? text.slice(text.indexOf('\n') + 1) : text).split('\n');
+        if (lines[lines.length - 1] === '')
+            lines.pop();
+        return lines.slice(-count);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
 /** Mint a fresh job id — `${Date.now()}-${hex}`. The sole minting site; the
  * valve calls this instead of building the literal inline so the epoch-ms
  * prefix is a real contract shared with its parser (jobStartedAtMs), not an

package/dist/core/feed/inbox.d.ts

@@ -75,9 +75,9 @@ export declare function clipBody(body: string): {
  *
  * Format (per sender group):
  *   From <sender> — <N> update(s):
- *     [<kind>] <label> at <absolute report path>:
- *
- *   <short report body>
+ *     [<kind>]
+ *       <short report body>
+ *       (report: <absolute report path>)
  *
  * Large reports remain canonical pointers and add one shared dereference hint.
  */

package/dist/core/feed/inbox.js

@@ -330,15 +330,19 @@ function inlineReport(e) {
 /**
  * Render one entry's digest line(s).
  *
- * Short pushed reports are inlined with their absolute report path. Larger
- * reports stay canonical history pointers. Direct messages retain their bounded
+ * A short pushed report is inlined as its own body, followed by a pointer to
+ * the durable artifact. The label is NOT repeated above it: a report's label is
+ * just its first line (feed.ts `firstLine`), so printing both reads as a
+ * truncated preview stacked on the full text it previews. Larger reports stay
+ * canonical history pointers. Direct messages retain their bounded
  * inline-body/spill behavior.
  */
 function renderEntry(e) {
     const report = inlineReport(e);
     if (report !== null) {
+        const indented = report.body.trimEnd().split('\n').map((l) => `    ${l}`).join('\n');
         return {
-            text: `  [${e.kind}] ${e.label} at ${report.path}:\n\n${report.body}`,
+            text: `  [${e.kind}]\n${indented}\n    (report: ${report.path})`,
             hasCanonicalRef: false,
         };
     }
@@ -364,9 +368,9 @@ function renderEntry(e) {
  *
  * Format (per sender group):
  *   From <sender> — <N> update(s):
- *     [<kind>] <label> at <absolute report path>:
- *
- *   <short report body>
+ *     [<kind>]
+ *       <short report body>
+ *       (report: <absolute report path>)
  *
  * Large reports remain canonical pointers and add one shared dereference hint.
  */

package/dist/core/inspector/core.d.ts

@@ -1,6 +1,14 @@
 import type { CronDTO } from '../../api/dto/crons.js';
 import type { SourceError, ViewCore } from '../view/contract.js';
-import { scheduledItems, type InspectorSection } from './model.js';
+import { scheduledItems, type BashJobRow, type InspectorSection } from './model.js';
+/** What a `y` confirmation will act on. Both sections arm cancellation the same
+ *  way, so the pending action carries its own kind rather than the view guessing
+ *  from whichever section happens to be open when the key lands. */
+export type PendingAction = {
+    kind: 'cron' | 'job';
+    id: string;
+    label: string;
+};
 export interface InspectorState {
     target: string;
     section: InspectorSection;
@@ -14,10 +22,17 @@ export interface InspectorState {
         error: SourceError | null;
         fetchedAt: number;
     };
+    jobs: {
+        data: BashJobRow[] | null;
+        error: SourceError | null;
+        fetchedAt: number;
+    };
     selectedCronId: string | null;
+    selectedJobId: string | null;
     expanded: boolean;
-    pendingCancel: string | null;
+    pendingCancel: PendingAction | null;
     scroll: Record<InspectorSection, number>;
 }
 export declare const inspectorCore: ViewCore<InspectorState>;
+export declare function selectedJob(state: InspectorState): BashJobRow | undefined;
 export { scheduledItems };