@saifymatteo/pi-extensions 0.1.4 → 0.1.5

package/packages/pi-bg-bash/test/job-controls.test.mjs

@@ -0,0 +1,347 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+const deferred = () => { let resolve, reject; const promise = new Promise((yes, no) => { resolve = yes; reject = no; }); return { promise, resolve, reject }; };
+
+function setup({ stop = async () => 'stopped', capture = async pid => ({ pid, started: 'fixture' }), windows = false,
+  launchText = '__PI_BG_PID:501 __PI_BG_WINPID:601', hasChildren = () => false } = {}) {
+  const tools = new Map(), commands = new Map(), hooks = new Map(), events = new Map();
+  const files = new Map(), intervals = new Set(), messages = [], statuses = [], calls = [], stopped = [];
+  let controls, panelSignal;
+  const processStub = { ...process, platform: windows ? 'win32' : 'linux', kill() {} };
+  const builtin = () => ({ description: '', execute: async (_id, args) => {
+    calls.push(args);
+    return { content: [{ type: 'text', text: launchText }] };
+  } });
+  const { default: extension } = loadExtension(fileURLToPath(new URL('../src/index.ts', import.meta.url)), {
+    'node:fs': { ...fs, readdirSync: () => [], existsSync: path => files.has(path), readFileSync: path => {
+      if (files.has(path)) return files.get(path);
+      throw Object.assign(new Error('missing'), { code: 'ENOENT' });
+    }, writeFileSync: (path, content) => files.set(path, content) },
+    './lib/process-control': { captureProcess: capture, hasTrackedDescendants: hasChildren,
+      stopProcessTree: async (identity, mode) => { stopped.push({ identity, mode }); return stop(identity, mode); } },
+    './lib/output': { readTail: path => files.get(path) ?? '', oneLine: text => text.replace(/\s+/g, ' ') },
+    './lib/panel': { showJobPanel: async (_ctx, api, signal) => { controls = api; panelSignal = signal; } },
+    '@earendil-works/pi-coding-agent': { createBashTool: builtin, createPowerShellTool: builtin },
+    '@earendil-works/pi-tui': {},
+  }, { process: processStub, crypto: globalThis.crypto,
+    setInterval: callback => { const timer = { callback }; intervals.add(timer); return timer; },
+    clearInterval: timer => intervals.delete(timer),
+  });
+  const pi = { registerTool: tool => tools.set(tool.name, tool), registerToolRenderer() {}, registerMessageRenderer() {},
+    registerCommand: (name, options) => commands.set(name, options.handler),
+    events: { on: (name, fn) => events.set(name, fn) }, on: (name, fn) => hooks.set(name, fn),
+    getAllTools: () => [{ name: 'bash' }, ...(windows ? [{ name: 'powershell' }] : [])],
+    sendMessage: (message, options) => messages.push({ message, options }),
+  };
+  const ctx = { hasUI: true, mode: 'tui', isIdle: () => true, hasPendingMessages: () => false,
+    sessionManager: { getSessionFile: () => 'fixture-session', getBranch: () => [] },
+    ui: { setStatus: (...args) => statuses.push(args), notify() {} },
+  };
+  extension(pi);
+  return {
+    tools, commands, hooks, files, intervals, messages, statuses, stopped, calls, ctx,
+    get controls() { return controls; }, get panelSignal() { return panelSignal; },
+    start: () => hooks.get('session_start')({}, ctx),
+    launch: async (tool = 'bash') => {
+      const result = await tools.get(tool).execute('fixture', { command: 'npm run dev', background: true }, undefined, undefined, ctx);
+      const id = result.details.bgJob;
+      return { id, outPath: result.details.bgOutputPath, statusPath: result.details.bgOutputPath.replace(/\.out$/, '.status') };
+    },
+    panel: () => commands.get('bg')('', ctx),
+    claim: ids => {
+      let provider;
+      events.get('async-work:providers:v1')({ sessionFile: 'fixture-session', add: value => { provider = value; } });
+      return provider.claim(ids, 'fixture-wait');
+    },
+    shutdown: () => hooks.get('session_shutdown')({ reason: 'quit' }, ctx),
+  };
+}
+
+test('launch records the real platform PID and updates the running footer', async () => {
+  for (const windows of [false, true]) {
+    const captured = [];
+    const s = setup({ windows, capture: async pid => { captured.push(pid); return { pid, started: 'fixture' }; } });
+    await s.start();
+    await s.launch();
+    if (windows) await s.launch('powershell');
+    assert.deepEqual(captured, windows ? [601, 501] : [501]);
+    assert.match(s.statuses.at(-1)[1], /running.*\/bg/);
+    await s.shutdown();
+    assert.equal(s.statuses.at(-1)[1], undefined);
+  }
+});
+
+test('Windows launch isolates both shells and clears Ctrl+C suppression before children start', async () => {
+  const s = setup({ windows: true });
+  await s.start();
+  await s.launch();
+  const launcher = Buffer.from(s.calls[0].command.match(/-EncodedCommand (\S+)/)[1], 'base64').toString('utf16le');
+  assert.match(launcher, /-WindowStyle Hidden/);
+  assert.match(launcher, /-WorkingDirectory \(Get-Location\)\.ProviderPath/);
+  assert.doesNotMatch(launcher, /-NoNewWindow/);
+  const bashBootstrap = [...s.files].find(([path]) => path.endsWith('.ps1'))[1];
+  assert.match(bashBootstrap, /SetConsoleCtrlHandler\(\[IntPtr\]::Zero, \$false\)/);
+  assert.ok(bashBootstrap.indexOf('SetConsoleCtrlHandler') < bashBootstrap.indexOf('$child = [System.Diagnostics.Process]::Start'));
+  assert.ok(bashBootstrap.indexOf('SetHandleInformation($inputHandle, 1, 1)') < bashBootstrap.indexOf('$child = [System.Diagnostics.Process]::Start'));
+  await s.launch('powershell');
+  const psBootstrap = [...s.files].filter(([path]) => path.endsWith('.ps1')).at(-1)[1];
+  assert.ok(psBootstrap.indexOf('SetConsoleCtrlHandler') < psBootstrap.indexOf('npm run dev'));
+  await s.shutdown();
+});
+
+test('Unix background jobs enable job control instead of inheriting ignored SIGINT', async () => {
+  const s = setup();
+  await s.start();
+  await s.launch();
+  assert.match(s.calls[0].command, /^set -m;/);
+  await s.shutdown();
+});
+
+test('failed launch without a PID does not register an unmanageable forever-running job', async () => {
+  const s = setup({ launchText: 'launch failed' });
+  await s.start();
+  await assert.rejects(s.launch(), /did not return a native PID/);
+  await s.panel();
+  assert.equal(s.controls.list().length, 0);
+  assert.equal(s.intervals.size, 0);
+  await s.shutdown();
+});
+
+test('identity discovery does not block launch; stopping waits for verification', { timeout: 1000 }, async () => {
+  const identity = deferred();
+  const s = setup({ capture: () => identity.promise });
+  await s.start();
+  const job = await s.launch();
+  await s.panel();
+  assert.match(s.controls.list()[0].state, /verifying PID/);
+  const stopping = s.controls.stop(job.id);
+  await Promise.resolve();
+  assert.equal(s.stopped.length, 0);
+  identity.resolve({ pid: 501, started: 'fixture' });
+  await stopping;
+  assert.equal(s.stopped.length, 1);
+  await s.shutdown();
+});
+
+test('viewing jobs/output does not consume or claim completion; footer clears on exit', async () => {
+  const s = setup();
+  await s.start();
+  const job = await s.launch();
+  s.files.set(job.outPath, 'preview ready');
+  await s.panel();
+  assert.equal(s.controls.output(job.id), 'preview ready');
+  assert.equal(s.controls.list()[0].state, 'running');
+  const lease = s.claim([job.id]);
+  s.files.set(job.statusPath, '0');
+  for (const timer of s.intervals) timer.callback();
+  const [result] = await lease.result;
+  assert.equal(result.details.exit, '0');
+  assert.equal(s.messages.length, 0);
+  assert.equal(s.statuses.at(-1)[1], undefined);
+  lease.commit();
+  await s.shutdown();
+});
+
+test('a direct user stop is recorded without waking an idle model and remains queryable', async () => {
+  const s = setup();
+  await s.start();
+  const job = await s.launch();
+  await s.panel();
+  assert.match(await s.controls.stop(job.id), /tracked process tree is gone/);
+  assert.equal(s.stopped.length, 1);
+  assert.equal(s.controls.list()[0].state, 'done, stopped gracefully by user');
+  assert.equal(s.messages.length, 1);
+  assert.equal(s.messages[0].options.triggerTurn, false);
+  const result = await s.tools.get('bash').execute('query', { job: String(job.id) }, undefined, undefined, s.ctx);
+  assert.match(result.content[0].text, /stopped gracefully by user/);
+  await s.shutdown();
+});
+
+test('user stopping a wait-owned job resolves the lease once without duplicate delivery', async () => {
+  const s = setup();
+  await s.start();
+  const job = await s.launch();
+  const lease = s.claim([job.id]);
+  await s.panel();
+  await s.controls.stop(job.id);
+  const results = await lease.result;
+  assert.equal(results.length, 1);
+  assert.equal(results[0].details.exit, 'stopped gracefully by user');
+  assert.equal(s.messages.length, 0);
+  lease.commit();
+  lease.release();
+  assert.equal(s.messages.length, 0);
+  await s.shutdown();
+});
+
+test('releasing a stopped job restores exactly one automatic delivery', async () => {
+  const s = setup();
+  await s.start();
+  const job = await s.launch();
+  const lease = s.claim([job.id]);
+  await s.panel();
+  await s.controls.stop(job.id);
+  await lease.result;
+  lease.release();
+  lease.release();
+  assert.equal(s.messages.length, 1);
+  await s.shutdown();
+});
+
+test('concurrent user and agent stop share one operation and preserve the wait result', { timeout: 1000 }, async () => {
+  const operation = deferred(), entered = deferred();
+  const s = setup({ stop: () => { entered.resolve(); return operation.promise; } });
+  await s.start();
+  const job = await s.launch();
+  const lease = s.claim([job.id]);
+  await s.panel();
+  const first = s.controls.stop(job.id);
+  const second = s.tools.get('bash').execute('stop', { job: `${job.id}:stop` }, undefined, undefined, s.ctx);
+  await entered.promise;
+  assert.equal(s.stopped.length, 1);
+  assert.equal(s.controls.list()[0].state, 'stopping gracefully');
+  operation.resolve('stopped');
+  await Promise.all([first, second]);
+  assert.equal((await lease.result)[0].details.exit, 'stopped gracefully by user');
+  lease.commit();
+  await s.shutdown();
+});
+
+test('force requested during graceful stopping queues a real force operation without duplicating completion', { timeout: 1000 }, async () => {
+  const graceful = deferred(), entered = deferred();
+  const s = setup({ stop: (_identity, mode) => {
+    if (mode === 'graceful') { entered.resolve(); return graceful.promise; }
+    return 'stopped';
+  } });
+  await s.start();
+  const job = await s.launch();
+  const lease = s.claim([job.id]);
+  await s.panel();
+  const first = s.controls.stop(job.id, 'graceful');
+  const failed = assert.rejects(first, /Force kill/);
+  await entered.promise;
+  const force = s.tools.get('bash').execute('kill', { job: `${job.id}:kill` }, undefined, undefined, s.ctx);
+  assert.equal(s.stopped.length, 1);
+  graceful.resolve('stuck');
+  await failed;
+  await force;
+  assert.deepEqual(s.stopped.map(call => call.mode), ['graceful', 'force']);
+  assert.equal((await lease.result)[0].details.exit, 'force killed by agent');
+  assert.equal(s.messages.length, 0);
+  lease.commit();
+  await s.shutdown();
+});
+
+test('force stop is explicit, recorded without idle wakeup and never masquerades as graceful', async () => {
+  const s = setup();
+  await s.start();
+  const job = await s.launch();
+  await s.panel();
+  await s.controls.stop(job.id, 'force');
+  assert.equal(s.stopped[0].mode, 'force');
+  assert.equal(s.controls.list()[0].state, 'done, force killed by user');
+  assert.equal(s.messages[0].options.triggerTurn, false);
+  await s.shutdown();
+});
+
+test('failed or unverifiable stops retain jobs and allow safe retry', async () => {
+  let attempt = 0;
+  const s = setup({ stop: async () => ++attempt === 1 ? 'stuck' : 'stopped' });
+  await s.start();
+  const job = await s.launch();
+  await s.panel();
+  await assert.rejects(s.controls.stop(job.id), /still running/);
+  s.files.set(job.statusPath, '143'); // The launcher exited, but a child survived cleanup.
+  for (const timer of s.intervals) timer.callback();
+  assert.equal(s.controls.list()[0].running, true);
+  assert.equal(s.controls.list()[0].state, 'cleanup incomplete');
+  assert.equal(s.messages.length, 0);
+  await s.controls.stop(job.id, 'force');
+  assert.equal(s.stopped.length, 2);
+  assert.deepEqual(s.stopped.map(call => call.mode), ['graceful', 'force']);
+  await s.shutdown();
+
+  const unavailable = setup({ capture: async () => { throw new Error('access denied'); } });
+  await unavailable.start();
+  const unknown = await unavailable.launch();
+  await unavailable.panel();
+  await assert.rejects(unavailable.controls.stop(unknown.id), /access denied/);
+  assert.equal(unavailable.stopped.length, 0);
+  assert.match(unavailable.controls.list()[0].state, /stop unavailable/);
+  await unavailable.shutdown();
+});
+
+test('completed commands can clean known children without changing or duplicating their wait result', async () => {
+  let children = true;
+  const s = setup({ hasChildren: () => children, stop: async () => { children = false; return 'stopped'; } });
+  await s.start();
+  const job = await s.launch();
+  const lease = s.claim([job.id]);
+  s.files.set(job.statusPath, '0');
+  for (const timer of s.intervals) timer.callback();
+  assert.equal((await lease.result)[0].details.exit, '0');
+  await s.panel();
+  assert.equal(s.controls.list()[0].running, false);
+  assert.equal(s.controls.list()[0].stoppable, true);
+  assert.match(s.controls.list()[0].state, /child cleanup available/);
+  const cleanup = await s.tools.get('bash').execute('cleanup', { job: `${job.id}:kill` }, undefined, undefined, s.ctx);
+  assert.match(cleanup.content[0].text, /command result is unchanged/);
+  assert.equal(s.controls.list()[0].stoppable, false);
+  assert.equal((await lease.result)[0].details.exit, '0');
+  assert.equal(s.messages.length, 0);
+  lease.commit();
+  await s.shutdown();
+});
+
+test('history trimming retains completed commands with unverified child cleanup', async () => {
+  const s = setup({ hasChildren: () => true });
+  await s.start();
+  for (let i = 0; i < 23; i++) {
+    const job = await s.launch();
+    const lease = s.claim([job.id]);
+    s.files.set(job.statusPath, '0');
+    for (const timer of s.intervals) timer.callback();
+    await lease.result;
+    lease.commit();
+  }
+  await s.panel();
+  assert.equal(s.controls.list().length, 23);
+  assert.ok(s.controls.list().every(job => job.stoppable && !job.running));
+  await s.shutdown();
+});
+
+test('already-finished jobs receive no stop signal', async () => {
+  const s = setup();
+  await s.start();
+  const job = await s.launch();
+  s.files.set(job.statusPath, '0');
+  await s.panel();
+  assert.match(await s.controls.stop(job.id), /already finished/);
+  assert.equal(s.stopped.length, 0);
+  await s.shutdown();
+});
+
+test('shutdown closes panel scope and drains only previously requested stops', async () => {
+  const operation = deferred();
+  const s = setup({ stop: () => operation.promise });
+  await s.start();
+  const job = await s.launch();
+  await s.launch();
+  await s.panel();
+  const stopping = s.controls.stop(job.id);
+  let drained = false;
+  const shutdown = s.shutdown().then(() => { drained = true; });
+  await Promise.resolve();
+  assert.equal(s.panelSignal.aborted, true);
+  assert.equal(drained, false);
+  operation.resolve('stopped');
+  await Promise.all([stopping, shutdown]);
+  assert.equal(s.stopped.length, 1);
+  assert.equal(s.messages.length, 0);
+  assert.equal(s.intervals.size, 0);
+  await assert.rejects(s.controls.stop(job.id), /no longer available/);
+});

package/packages/pi-bg-bash/test/native-process-control.test.mjs

@@ -0,0 +1,126 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import * as fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+// Opt in: this launches and terminates only this test's disposable Node tree.
+// PI_BG_NATIVE_TEST=1 node --test packages/pi-bg-bash/test/native-process-control.test.mjs
+test('native stop retires a disposable parent and child process', {
+  skip: process.env.PI_BG_NATIVE_TEST !== '1', timeout: 90_000,
+}, async () => {
+  const { captureProcess, stopProcessTree } = loadExtension(fileURLToPath(new URL('../src/lib/process-control.ts', import.meta.url)));
+  const childCode = "process.on('SIGTERM', () => {}); setTimeout(() => {}, 60000)";
+  const root = spawn(process.execPath, ['-e', `
+    const { spawn } = require('node:child_process');
+    const child = spawn(process.execPath, ['-e', ${JSON.stringify(childCode)}], { stdio: 'ignore', windowsHide: true });
+    child.once('spawn', () => console.log(JSON.stringify({ child: child.pid })));
+    process.on('SIGTERM', () => {});
+    setTimeout(() => {}, 60000);
+  `], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  const exited = once(root, 'exit');
+  let identity, childIdentity, childPid;
+  try {
+    const [chunk] = await once(root.stdout, 'data');
+    childPid = JSON.parse(chunk.toString().trim()).child;
+    identity = await captureProcess(root.pid);
+    childIdentity = await captureProcess(childPid);
+    const started = performance.now();
+    assert.equal(await stopProcessTree(identity, 'force'), 'stopped');
+    console.log(`native force: ${Math.round(performance.now() - started)}ms including discovery and verification`);
+    await exited;
+    await assert.rejects(captureProcess(childPid), /gone/);
+  } catch (error) {
+    console.error('native fixture failed before cleanup:', error);
+    throw error;
+  } finally {
+    for (const captured of [childIdentity, identity].filter(Boolean)) {
+      try { process.kill(captured.pid, 0); await stopProcessTree(captured, 'force'); } catch { /* Already exited or cleanup failed; fixtures self-expire. */ }
+    }
+    // ChildProcess retains the directly spawned fixture handle if identity capture failed.
+    if (root.exitCode === null && root.signalCode === null) root.kill('SIGKILL');
+  }
+});
+
+for (const name of process.platform === 'win32' ? ['bash', 'powershell'] : ['bash']) {
+test(`native ${name} console supports graceful Ctrl+C and separate force kill through job controls`, {
+  skip: process.env.PI_BG_NATIVE_TEST !== '1', timeout: 240_000,
+}, async () => {
+  const host = await import('@earendil-works/pi-coding-agent');
+  const tools = new Map(), hooks = new Map(), commands = new Map();
+  const folder = fs.mkdtempSync(join(tmpdir(), 'pi bg native-'));
+  const script = join(folder, 'preview.cjs');
+  fs.writeFileSync(script, `
+    const fs = require('node:fs');
+    const { spawn } = require('node:child_process');
+    const marker = process.argv[2];
+    const safety = setTimeout(() => process.exit(91), 90000);
+    process.on('SIGINT', () => setTimeout(() => {
+      fs.writeFileSync(marker, 'SIGINT cleanup completed');
+      clearTimeout(safety);
+    }, 200));
+    const code = "const fs=require('node:fs'); const t=setTimeout(()=>process.exit(91),90000); process.on('SIGINT',()=>setTimeout(()=>{fs.writeFileSync(process.argv[1], 'SIGINT child cleanup completed');clearTimeout(t);},100)); console.log('child-ready');";
+    const child = spawn(process.execPath, ['-e', code, marker + '.child'], { stdio: ['ignore', 'pipe', 'inherit'] });
+    child.stdout.once('data', () => {
+      fs.writeFileSync(marker + '.ready', String(child.pid));
+      console.log('native-preview-ready child=' + child.pid);
+    });
+  `);
+  let mode = 'force';
+  const { default: extension } = loadExtension(fileURLToPath(new URL('../src/index.ts', import.meta.url)), {
+    '@earendil-works/pi-coding-agent': host,
+    '@earendil-works/pi-tui': {},
+    'node:os': { tmpdir: () => folder, homedir: () => folder },
+    'node:fs': { ...fs, readdirSync: () => [] },
+    './lib/panel': { showJobPanel: async (_ctx, api) => {
+      const job = api.list().find(job => job.running);
+      assert.ok(job, 'launched job appears in /bg');
+      assert.match(await api.stop(job.id, mode), /tracked process tree is gone/);
+    } },
+  }, { crypto: globalThis.crypto });
+  const ctx = { cwd: folder, hasUI: false, isIdle: () => true, hasPendingMessages: () => false,
+    sessionManager: { getSessionFile: () => undefined, getBranch: () => [], getSessionId: () => 'native-test' },
+    ui: { notify() {} },
+  };
+  extension({ registerTool: tool => tools.set(tool.name, tool), registerToolRenderer() {}, registerMessageRenderer() {},
+    registerCommand: (name, options) => commands.set(name, options.handler),
+    on: (name, fn) => hooks.set(name, fn), events: { on() {} }, getAllTools: () => [{ name: 'powershell' }],
+    sendMessage: (_message, options) => assert.equal(options.triggerTurn, false),
+  });
+  try {
+    await hooks.get('session_start')({}, ctx);
+    for (mode of ['graceful', 'force']) {
+        const marker = join(folder, `${name}-${mode}.marker`);
+        let watcher, timer;
+        const ready = new Promise((resolve, reject) => {
+          watcher = fs.watch(folder, () => { if (fs.existsSync(marker + '.ready')) resolve(); });
+          timer = setTimeout(() => reject(new Error(`${name} fixture did not become ready`)), 15000);
+        });
+        void ready.catch(() => {});
+        try {
+          const command = `node "${script.replace(/\\/g, '/')}" "${marker.replace(/\\/g, '/')}"`;
+          const launch = await tools.get(name).execute('native-launch', { command, background: true }, undefined, undefined, ctx);
+          if (!fs.existsSync(marker + '.ready')) await ready;
+          const childPid = Number(fs.readFileSync(marker + '.ready', 'utf8'));
+          const started = performance.now();
+          await commands.get('bg')('', ctx);
+          console.log(`native ${name} ${mode}: ${Math.round(performance.now() - started)}ms`);
+          const result = await tools.get(name).execute('native-query', { job: String(launch.details.bgJob) }, undefined, undefined, ctx);
+          assert.match(result.content[0].text, mode === 'graceful' ? /stopped gracefully by user/ : /force killed by user/);
+          assert.equal(fs.existsSync(marker), mode === 'graceful', 'only graceful stop runs parent cleanup');
+          assert.equal(fs.existsSync(marker + '.child'), mode === 'graceful', 'only graceful stop runs child cleanup');
+          const { captureProcess } = loadExtension(fileURLToPath(new URL('../src/lib/process-control.ts', import.meta.url)));
+          await assert.rejects(captureProcess(childPid), /gone/, 'no live orphaned child remains');
+        } finally { watcher?.close(); clearTimeout(timer); }
+    }
+  } finally {
+    await hooks.get('session_shutdown')({ reason: 'quit' }, ctx);
+    try { fs.rmSync(folder, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); }
+    catch (error) { console.error('Native fixture directory still locked:', folder, error.code); }
+  }
+});
+}

package/packages/pi-bg-bash/test/output.test.mjs

@@ -0,0 +1,28 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+const { cleanOutput, oneLine, readTail } = loadExtension(fileURLToPath(new URL('../src/lib/output.ts', import.meta.url)));
+
+test('output removes terminal controls, preserves text, and command labels stay on one line', () => {
+  assert.equal(cleanOutput('\x1b[31mred\x1b[0m\x1b]0;bad title\x07\x00\r\nnext\tcell'), 'red\nnext    cell');
+  assert.equal(oneLine('npm\nrun\tdev\x1b[2J'), 'npm run dev');
+});
+
+test('tail reads cap both bytes and lines, even for a giant single line', () => {
+  const root = mkdtempSync(join(tmpdir(), 'pi-bg-output-test-'));
+  try {
+    const file = join(root, 'out');
+    writeFileSync(file, 'one\ntwo\nthree\n');
+    assert.equal(readTail(file, 3), '(earlier output omitted)\ntwo\nthree');
+    writeFileSync(file, 'x'.repeat(1024 * 1024));
+    const tail = readTail(file, 2000, 1024);
+    assert.match(tail, /^\(earlier output omitted\)/);
+    assert.ok(tail.length < 1100);
+    assert.equal(readTail(join(root, 'absent')), '(no output yet)');
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/packages/pi-bg-bash/test/panel.test.mjs

@@ -0,0 +1,146 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as tui from '@earendil-works/pi-tui';
+import { fileURLToPath } from 'node:url';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+const flush = async () => { for (let i = 0; i < 12; i++) await Promise.resolve(); };
+
+function setup({ mode = 'tui', hasUI = true, confirm = true, answers = [] } = {}) {
+  const timers = new Set(), notifications = [], stopped = [], confirmations = [], selections = [...answers];
+  const { showJobPanel } = loadExtension(fileURLToPath(new URL('../src/lib/panel.ts', import.meta.url)), {
+    '@earendil-works/pi-tui': tui,
+  }, {
+    setInterval: callback => { const timer = { callback }; timers.add(timer); return timer; },
+    clearInterval: timer => timers.delete(timer),
+  });
+  const jobs = [{ id: 2, tool: 'bash', command: 'npm run dev', state: 'running', secs: 10, running: true, stoppable: true },
+    { id: 1, tool: 'powershell', command: 'npm test', state: 'done', secs: 4, running: false, stoppable: false }];
+  let component, output = 'line 1\nline 2\nline 3\nline 4';
+  const controller = new AbortController();
+  const ctx = { mode, hasUI, ui: {
+    notify: (...args) => notifications.push(args),
+    confirm: async (...args) => { confirmations.push(args); return confirm; },
+    select: async (_title, options) => { const answer = selections.shift(); return typeof answer === 'number' ? options[answer] : answer; },
+    custom: factory => new Promise(resolve => {
+      component = factory({ terminal: { rows: 8 }, requestRender() {} },
+        { fg: (_color, text) => text }, {}, value => { component?.dispose?.(); resolve(value); });
+    }),
+  } };
+  const controls = { list: () => jobs, output: () => output, stop: async (id, mode) => { stopped.push([id, mode]); jobs[0].running = false; return 'stopped'; } };
+  const result = showJobPanel(ctx, controls, controller.signal);
+  return { result, jobs, timers, stopped, confirmations, notifications, selections, controller,
+    get component() { return component; }, get output() { return output; }, set output(value) { output = value; },
+    refresh: () => { for (const timer of timers) timer.callback(); },
+  };
+}
+
+test('x confirms before stopping; refusing or closing never stops a job', async () => {
+  for (const confirm of [true, false]) {
+    const s = setup({ confirm });
+    s.component.handleInput('x');
+    await flush();
+    assert.equal(s.confirmations.length, 1);
+    assert.deepEqual(s.stopped, confirm ? [[2, 'force']] : []);
+    assert.match(s.confirmations[0][0], /Force kill/);
+    assert.match(s.confirmations[0][1], /Cleanup hooks will not run/);
+    s.component.handleInput('\x1b');
+    await s.result;
+    assert.equal(s.timers.size, 0);
+  }
+  const s = setup();
+  s.component.handleInput('q');
+  await s.result;
+  assert.equal(s.stopped.length, 0);
+});
+
+test('s requests graceful stopping, independently confirmed and without escalation', async () => {
+  for (const confirm of [true, false]) {
+    const s = setup({ confirm });
+    s.component.handleInput('s');
+    await flush();
+    assert.match(s.confirmations[0][0], /Gracefully stop/);
+    assert.match(s.confirmations[0][1], /no automatic escalation/);
+    assert.deepEqual(s.stopped, confirm ? [[2, 'graceful']] : []);
+    s.component.handleInput('q');
+    await s.result;
+    assert.equal(s.timers.size, 0);
+  }
+});
+
+test('list refresh preserves the selected job as rows change', async () => {
+  const s = setup();
+  s.component.handleInput('\x1b[B');
+  s.jobs.unshift({ id: 3, tool: 'bash', command: 'new', state: 'running', secs: 1, running: true, stoppable: true });
+  s.refresh();
+  s.component.handleInput('x');
+  await flush();
+  assert.equal(s.confirmations.length, 0, 'selected completed job is still selected');
+  assert.match(s.notifications.at(-1)[0], /#1 already finished/);
+  s.component.handleInput('q');
+  await s.result;
+});
+
+test('output follows the bottom, preserves scroll-up, and all rendered lines fit narrow widths', async () => {
+  const s = setup();
+  s.component.handleInput('\r');
+  await flush();
+  let lines = s.component.render(40).map(line => line.trimEnd());
+  assert.ok(lines.includes('line 4'));
+  s.component.handleInput('\x1b[H');
+  lines = s.component.render(40).map(line => line.trimEnd());
+  assert.ok(lines.includes('line 1'));
+  s.output = 'line 1\nline 2\nline 3\nline 4\nline 5';
+  s.refresh();
+  lines = s.component.render(40).map(line => line.trimEnd());
+  assert.ok(lines.includes('line 1'));
+  assert.ok(!lines.includes('line 5'));
+  s.component.handleInput('\x1b[F');
+  s.component.render(40);
+  s.output += '\nline 6';
+  s.refresh();
+  assert.ok(s.component.render(40).some(line => line.trimEnd() === 'line 6'));
+  s.output = '界'.repeat(100);
+  s.refresh();
+  assert.ok(s.component.render(9).every(line => tui.visibleWidth(line) <= 9));
+  s.component.handleInput('\x1b');
+  await flush();
+  assert.equal(s.timers.size, 1, 'only the reopened list refreshes');
+  s.controller.abort();
+  await s.result;
+  assert.equal(s.timers.size, 0);
+});
+
+test('session invalidation closes an open output view and clears its timer', async () => {
+  const s = setup();
+  s.component.handleInput('\r');
+  await flush();
+  s.controller.abort();
+  await s.result;
+  assert.equal(s.timers.size, 0);
+  assert.equal(s.stopped.length, 0);
+});
+
+test('non-UI mode is list-only, and RPC uses explicit view/stop choices', async () => {
+  const noUI = setup({ mode: 'print', hasUI: false });
+  await noUI.result;
+  assert.match(noUI.notifications[0][0], /npm run dev/);
+  assert.equal(noUI.stopped.length, 0);
+  assert.equal(noUI.timers.size, 0);
+
+  const rpc = setup({ mode: 'rpc', answers: [0, 'View output', 0, 'Stop gracefully'] });
+  await rpc.result;
+  assert.match(rpc.notifications[0][0], /line 1/);
+  assert.deepEqual(rpc.stopped, [[2, 'graceful']]);
+  assert.equal(rpc.confirmations.length, 1);
+  assert.equal(rpc.timers.size, 0);
+
+  const force = setup({ mode: 'rpc', answers: [0, 'Force kill'] });
+  await force.result;
+  assert.deepEqual(force.stopped, [[2, 'force']]);
+  assert.match(force.confirmations[0][0], /Force kill/);
+
+  const cancelled = setup({ mode: 'rpc' });
+  await cancelled.result;
+  assert.equal(cancelled.stopped.length, 0);
+});