@naswerks/engineering-loop 0.7.0 → 0.8.0

package/bin/witness-extract-cmd.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// One tool call's command, written to a file byte for byte, with its line count and every non-ASCII
+// character named: a refused command is often explained by one character a terminal never shows.
+// Writes only <outFile>.
+//
+//   node witness-extract-cmd.mjs <file.jsonl> <toolUseId> <outFile>
+//   node witness-extract-cmd.mjs --self-test
+
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { contentOf, entries, isMain, positionals, report, scratch, toolUse, writeTranscript } from './witness-lib.mjs';
+
+export async function extractCmd(file, id, outFile) {
+  for await (const { entry } of entries(file)) {
+    for (const c of contentOf(entry)) {
+      if (c.type !== 'tool_use' || c.id !== id) continue;
+      const command = String(c.input?.command ?? '');
+      writeFileSync(outFile, command);
+      const lines = command.split('\n');
+      const out = [`${lines.length} line(s), ${Buffer.byteLength(command)} bytes -> ${outFile}`];
+      lines.forEach((line, i) => {
+        const odd = [...line].filter((ch) => ch.charCodeAt(0) > 127);
+        if (odd.length) out.push(`non-ascii on line ${i + 1}: ${odd.map((ch) => `U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}`).join(' ')}`);
+      });
+      return out;
+    }
+  }
+  return [`no tool call ${id} in ${file}`];
+}
+
+async function selfTest() {
+  const dir = scratch('witness-extract-cmd');
+  try {
+    const command = 'cat >> tldr.md <<\'EOF\'\nC:\\work\\path and a dash — here\nEOF';
+    const file = writeTranscript(dir, 'seat.jsonl', [
+      toolUse(1, 'toolu_one', 'Bash', { command: 'git status' }),
+      toolUse(2, 'toolu_two', 'Bash', { command }),
+    ]);
+    const out = join(dir, 'command.txt');
+    const lines = await extractCmd(file, 'toolu_two', out);
+    return report('witness-extract-cmd', [
+      { name: 'the command is written byte for byte, backslashes included', ok: readFileSync(out, 'utf8') === command, detail: JSON.stringify(readFileSync(out, 'utf8')) },
+      { name: 'its non-ASCII character is named with its line', ok: lines.some((l) => l === 'non-ascii on line 2: U+2014'), detail: lines.join(' | ') },
+      { name: 'CONTROL: an id not in the transcript says so', ok: (await extractCmd(file, 'toolu_none', out))[0].startsWith('no tool call'), detail: '' },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [file, id, outFile] = positionals(argv);
+  if (!file || !id || !outFile) { console.log('usage: witness-extract-cmd.mjs <file.jsonl> <toolUseId> <outFile>'); process.exit(2); }
+  for (const line of await extractCmd(file, id, outFile)) console.log(line);
+}

package/bin/witness-extract-seed.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// A session's seed (its first user message) and its prompt snapshots, saved verbatim. The seed is what the
+// session was told; the policy text a control plane appends to the system prompt lives in the
+// `prompt_snapshot` attachments, not in the seed. Writes <outPrefix>-seed-as-kicked.txt and
+// <outPrefix>-prompt-snapshots.txt.
+//
+//   node witness-extract-seed.mjs <file.jsonl> <outPrefix>
+//   node witness-extract-seed.mjs --self-test
+
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { at, entries, isMain, positionals, report, scratch, userText, writeTranscript } from './witness-lib.mjs';
+
+// A user message shorter than this is a command or a meta line, never a seed.
+const SEED_FLOOR = 200;
+
+export async function extractSeed(file, outPrefix) {
+  let seed = null;
+  const snapshots = [];
+  for await (const { entry } of entries(file)) {
+    if (seed === null && entry.message?.role === 'user' && !entry.isMeta) {
+      const c = entry.message.content;
+      const text = typeof c === 'string' ? c : Array.isArray(c) ? c.filter((x) => x.type === 'text').map((x) => x.text).join('\n') : '';
+      if (text.length > SEED_FLOOR) seed = `${entry.timestamp}\n${text}`;
+    }
+    if (entry.type === 'attachment' && /prompt_snapshot/.test(JSON.stringify(entry.attachment?.type ?? ''))) {
+      snapshots.push(`${entry.timestamp}\n${JSON.stringify(entry.attachment, null, 1)}`);
+    }
+  }
+  writeFileSync(`${outPrefix}-seed-as-kicked.txt`, seed ?? '(no seed found)');
+  writeFileSync(`${outPrefix}-prompt-snapshots.txt`, snapshots.join('\n\n=====\n\n') || '(no prompt_snapshot attachments)');
+  return [`seed ${seed === null ? 0 : seed.length} chars; prompt snapshots ${snapshots.length}`];
+}
+
+async function selfTest() {
+  const dir = scratch('witness-extract-seed');
+  try {
+    const seed = `You are the COORDINATOR. ${'Read the brief and follow it. '.repeat(10)}`;
+    const file = writeTranscript(dir, 'seat.jsonl', [
+      userText(0, '<command-name>/clear</command-name>'),
+      userText(1, seed),
+      { type: 'attachment', timestamp: at(1), attachment: { type: 'prompt_snapshot', text: 'the policy suffix' } },
+      userText(9, `a later human message ${'x'.repeat(SEED_FLOOR)}`),
+    ]);
+    const prefix = join(dir, 'coordinator');
+    await extractSeed(file, prefix);
+    const saved = readFileSync(`${prefix}-seed-as-kicked.txt`, 'utf8');
+    const snapshots = readFileSync(`${prefix}-prompt-snapshots.txt`, 'utf8');
+    return report('witness-extract-seed', [
+      { name: 'the seed is the first user message long enough to be one, saved verbatim', ok: saved.endsWith(`\n${seed}`), detail: saved.slice(0, 80) },
+      { name: 'the prompt snapshot is saved', ok: snapshots.includes('the policy suffix'), detail: snapshots.slice(0, 80) },
+      { name: 'CONTROL: a short command line before it and a later message are not the seed', ok: !saved.includes('/clear') && !saved.includes('a later human message'), detail: saved.slice(0, 80) },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [file, outPrefix] = positionals(argv);
+  if (!file || !outPrefix) { console.log('usage: witness-extract-seed.mjs <file.jsonl> <outPrefix>'); process.exit(2); }
+  for (const line of await extractSeed(file, outPrefix)) console.log(line);
+}

package/bin/witness-file-ledger.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Files the witness ledger into the run's sessions folder, on the human's word: the ledger's body
+// unedited, under the header the repository's § Doc metadata (repository-owned) prescribes. The header is
+// the config's `ledgerHeader` (a string, or a list of lines) with `{date}`, `{pipeline}` and `{topic}`
+// filled in; the ledger is `ledger.md` in the witness folder, or --ledger <path>. It refuses to overwrite.
+//
+//   node witness-file-ledger.mjs <destPath> [--config <path>] [--ledger <path>]
+//   -> e.g. docs/research/{topic}/sessions/witness-ledger-{date}.md
+//   node witness-file-ledger.mjs --self-test
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { flag, isMain, loadConfig, positionals, report, scratch } from './witness-lib.mjs';
+
+export function fileLedger(dest, config, ledgerPath, today = new Date().toISOString().slice(0, 10)) {
+  if (existsSync(dest)) return { ok: false, out: [`EXISTS, refusing to overwrite: ${dest}`] };
+  if (config.ledgerHeader === undefined) {
+    return { ok: false, out: ['no ledgerHeader in the config - the filed ledger needs the header the repository\'s § Doc metadata (repository-owned) prescribes'] };
+  }
+  const template = Array.isArray(config.ledgerHeader) ? config.ledgerHeader.join('\n') : String(config.ledgerHeader);
+  const header = template.replaceAll('{date}', today).replaceAll('{pipeline}', String(config.pipeline ?? '')).replaceAll('{topic}', String(config.topic ?? ''));
+  const body = readFileSync(ledgerPath, 'utf8').replace(/\r/g, '');
+  writeFileSync(dest, `${header}\n${body}`);
+  return { ok: true, out: [`wrote ${header.length + 1 + body.length} chars to ${dest}; body ${body.length} chars = the ledger, unedited`] };
+}
+
+function selfTest() {
+  const dir = scratch('witness-file-ledger');
+  try {
+    const ledger = join(dir, 'ledger.md');
+    writeFileSync(ledger, '# Witness ledger\n\nW1 the kick, by its act.\n');
+    const config = { pipeline: '42', topic: 'demo', ledgerHeader: ['---', 'title: "Witness ledger, pipeline {pipeline} ({date})"', 'status: deprecated', '---', ''] };
+    const dest = join(dir, 'witness-ledger.md');
+    const first = fileLedger(dest, config, ledger, 'the-date');
+    const filed = readFileSync(dest, 'utf8');
+    const second = fileLedger(dest, config, ledger, 'the-date');
+    const headless = fileLedger(join(dir, 'other.md'), { ...config, ledgerHeader: undefined }, ledger);
+    return report('witness-file-ledger', [
+      { name: 'the ledger is filed under the configured header, its body unedited', ok: first.ok && filed === '---\ntitle: "Witness ledger, pipeline 42 (the-date)"\nstatus: deprecated\n---\n\n# Witness ledger\n\nW1 the kick, by its act.\n', detail: JSON.stringify(filed) },
+      { name: 'CONTROL: a second filing refuses to overwrite', ok: !second.ok && second.out[0].startsWith('EXISTS'), detail: second.out[0] },
+      { name: 'CONTROL: a config with no header refuses rather than inventing one', ok: !headless.ok && !existsSync(join(dir, 'other.md')), detail: headless.out[0] },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(selfTest());
+  const [dest] = positionals(argv, ['--config', '--ledger']);
+  if (!dest) { console.log('usage: witness-file-ledger.mjs <destPath> [--config <path>] [--ledger <path>]'); process.exit(2); }
+  const config = loadConfig(argv, { required: true });
+  const { ok, out } = fileLedger(dest, config, flag(argv, '--ledger') ?? join(config.dir, 'ledger.md'));
+  for (const line of out) console.log(line);
+  process.exit(ok ? 0 : 1);
+}

package/bin/witness-gaps.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Idle gaps between a transcript's consecutive entries, its first and last timestamps, and the entries a
+// pattern matches. A transcript with no entry since T has not acted since T. Read-only.
+//
+//   node witness-gaps.mjs <file.jsonl> <minGapMinutes> [pattern]
+//   node witness-gaps.mjs --self-test
+
+import { rmSync } from 'node:fs';
+import { assistantText, entries, isMain, positionals, report, scratch, userText, writeTranscript } from './witness-lib.mjs';
+
+export async function gaps(file, min = 10, pattern = null) {
+  const re = pattern ? new RegExp(pattern) : null;
+  const out = [];
+  let prev = null;
+  let first = null;
+  for await (const { entry } of entries(file)) {
+    const ts = entry.timestamp;
+    if (!ts) continue;
+    first ??= ts;
+    const minutes = prev ? (Date.parse(ts) - Date.parse(prev)) / 60000 : 0;
+    if (prev && minutes >= min) out.push(`GAP ${minutes.toFixed(0)} min: ${prev} -> ${ts}`);
+    if (re) {
+      const hit = JSON.stringify(entry.message?.content ?? entry.content ?? '').match(re);
+      if (hit) out.push(`MATCH ${ts} ${hit[0].slice(0, 160)}`);
+    }
+    prev = ts;
+  }
+  out.push(`first ${first} last ${prev}`);
+  return out;
+}
+
+async function selfTest() {
+  const dir = scratch('witness-gaps');
+  try {
+    const file = writeTranscript(dir, 'seat.jsonl', [
+      userText(0, 'the seed'),
+      assistantText(5, 'working'),
+      assistantText(45, 'back after the limit reset'),
+    ]);
+    const lines = await gaps(file, 10, 'limit reset');
+    return report('witness-gaps', [
+      { name: 'a forty-minute gap is a line', ok: lines.some((l) => l.startsWith('GAP 40 min')), detail: lines.join(' | ') },
+      { name: 'CONTROL: a five-minute gap under the floor is not', ok: !lines.some((l) => l.startsWith('GAP 5 ')), detail: lines.join(' | ') },
+      { name: 'the pattern and the first and last timestamps are reported', ok: lines.some((l) => l.startsWith('MATCH')) && lines.at(-1).startsWith('first '), detail: lines.join(' | ') },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [file, min, pattern] = positionals(argv);
+  if (!file) { console.log('usage: witness-gaps.mjs <file.jsonl> <minGapMinutes> [pattern]'); process.exit(2); }
+  for (const line of await gaps(file, Number(min ?? 10), pattern ?? null)) console.log(line);
+}

package/bin/witness-latency.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Every tool call with its wait, from the call to its result: a long wait on a gated call is a park or an
+// approval, and a long wait on a plane call is the plane. Read-only.
+//
+//   node witness-latency.mjs <file.jsonl> <sinceIso> [minSeconds]
+//   node witness-latency.mjs --self-test
+
+import { rmSync } from 'node:fs';
+import { at, clip, contentOf, entries, isMain, positionals, report, resultText, scratch, toolResult, toolUse, writeTranscript } from './witness-lib.mjs';
+
+export async function latency(file, since, min = 0) {
+  const uses = new Map();
+  const out = [];
+  for await (const { entry } of entries(file)) {
+    if ((entry.timestamp ?? '') < since) continue;
+    for (const c of contentOf(entry)) {
+      if (c.type === 'tool_use') uses.set(c.id, { ts: entry.timestamp, name: c.name, input: JSON.stringify(c.input) });
+      else if (c.type === 'tool_result' && uses.has(c.tool_use_id)) {
+        const use = uses.get(c.tool_use_id);
+        uses.delete(c.tool_use_id);
+        const lag = (Date.parse(entry.timestamp) - Date.parse(use.ts)) / 1000;
+        if (lag < min) continue;
+        out.push(`${lag.toFixed(0).padStart(5)}s ${use.ts.slice(11, 19)}Z ${use.name} ${clip(use.input, 150)} => ${c.is_error ? 'ERROR ' : ''}${clip(resultText(c), 140)}`);
+      }
+    }
+  }
+  return out;
+}
+
+async function selfTest() {
+  const dir = scratch('witness-latency');
+  try {
+    const file = writeTranscript(dir, 'seat.jsonl', [
+      toolUse(1, 'a', 'Bash', { command: 'git status' }),
+      toolResult(1.05, 'a', 'clean'),
+      toolUse(2, 'b', 'Bash', { command: 'a command a human had to approve' }),
+      toolResult(4, 'b', 'approved'),
+    ]);
+    const lines = await latency(file, at(0), 60);
+    return report('witness-latency', [
+      { name: 'a two-minute wait is a line', ok: lines.length === 1 && lines[0].trim().startsWith('120s') && lines[0].includes('approved'), detail: lines.join(' | ') },
+      { name: 'CONTROL: a three-second call under the floor is not', ok: !lines.some((l) => l.includes('git status')), detail: lines.join(' | ') },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [file, since, min] = positionals(argv);
+  if (!file || !since) { console.log('usage: witness-latency.mjs <file.jsonl> <sinceIso> [minSeconds]'); process.exit(2); }
+  for (const line of await latency(file, since, Number(min ?? 0))) console.log(line);
+}

package/bin/witness-lib.mjs

@@ -0,0 +1,124 @@
+// Shared by the witness tools in this folder: the config, a transcript read one line at a time, the
+// plane's tool prefix, and the self-test helpers. Nothing here writes outside the paths a tool is given.
+//
+// The config is `witness.config.json` in the witness folder (or `--config <path>`). The folder is the
+// witness's durable folder: the watcher keeps its state, its event log and its captures there, and the
+// filed ledger is read from it. Every run-specific fact lives in the config, never in a tool.
+
+import { createReadStream, existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const DEFAULTS = {
+  sourceDirs: ['src', 'tests'],
+  generatedPaths: [],
+  noisePaths: [],
+  watchedCommands: [],
+  branches: [],
+  logScan: [],
+  extraLogDirs: [],
+  ownerContainers: [],
+  reaperContainerPrefix: 'testcontainers-ryuk',
+  pollSeconds: 20,
+  probes: { processes: true, docker: true },
+};
+
+// The value after `name` in argv, or `fallback`.
+export function flag(argv, name, fallback = undefined) {
+  const at = argv.indexOf(name);
+  return at >= 0 && at + 1 < argv.length ? argv[at + 1] : fallback;
+}
+
+// argv without the flags in `valued` (each with its value) and without bare `--` switches.
+export function positionals(argv, valued = []) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (valued.includes(argv[i])) { i++; continue; }
+    if (argv[i].startsWith('--')) continue;
+    out.push(argv[i]);
+  }
+  return out;
+}
+
+export function loadConfig(argv, { required = false } = {}) {
+  const path = resolve(flag(argv, '--config', 'witness.config.json'));
+  if (!existsSync(path)) {
+    if (required) throw new Error(`no witness config at ${path} - pass --config <path>`);
+    return { ...DEFAULTS, dir: process.cwd(), path: null };
+  }
+  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  return { ...DEFAULTS, ...raw, probes: { ...DEFAULTS.probes, ...(raw.probes ?? {}) }, dir: dirname(path), path };
+}
+
+// The tool-name prefix of the plane's MCP server: `--plane <server>`, else the config's `planeServer`.
+export function planePrefix(argv, config) {
+  const server = flag(argv, '--plane') ?? config?.planeServer;
+  if (!server) throw new Error('name the control plane\'s MCP server: --plane <server>, or planeServer in the config');
+  return `mcp__${server}__`;
+}
+
+// The plane's read verbs. A read that succeeded is not an act; a read that failed is worth a line.
+export const PLANE_READS = /^(read_blackboard|seat_read|seat_acts|seat_siblings|seat_usage|seat_parks|seat_content|seat_findings|seat_promises|seat_timeline|needs_you)$/;
+
+export const clip = (value, n) => {
+  const t = String(value ?? '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n)}...` : t;
+};
+
+// A transcript entry's content blocks, whether the message holds a string or a list.
+export function contentOf(entry) {
+  const message = entry?.message;
+  if (!message) return [];
+  return Array.isArray(message.content) ? message.content : [{ type: 'text', text: message.content }];
+}
+
+export function resultText(block) {
+  return Array.isArray(block.content) ? block.content.map((x) => x.text ?? '').join(' ') : String(block.content ?? '');
+}
+
+// Every entry of a transcript, one line at a time from `fromByte`, so a transcript of tens of megabytes is
+// never held whole. Lines that do not parse are skipped.
+export async function* entries(file, fromByte = 0) {
+  const lines = createInterface({ input: createReadStream(file, { start: fromByte, encoding: 'utf8' }), crlfDelay: Infinity });
+  let line = 0;
+  for await (const raw of lines) {
+    line++;
+    if (!raw.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(raw); } catch { continue; }
+    yield { line, entry };
+  }
+}
+
+export const isMain = (url) => Boolean(process.argv[1]) && pathToFileURL(resolve(process.argv[1])).href === url;
+
+// --- self-test helpers ------------------------------------------------------------------------------
+
+export const scratch = (prefix) => mkdtempSync(join(tmpdir(), `${prefix}-`));
+
+// A timestamp `minutes` after a fixed base, so a fixture names no date of its own.
+export const at = (minutes) => new Date(Date.UTC(2030, 0, 1) + minutes * 60000).toISOString();
+
+export const userText = (minutes, text, extra = {}) => ({ type: 'user', timestamp: at(minutes), message: { role: 'user', content: text }, ...extra });
+export const assistantText = (minutes, text) => ({ type: 'assistant', timestamp: at(minutes), message: { role: 'assistant', content: [{ type: 'text', text }] } });
+export const toolUse = (minutes, id, name, input) => ({ type: 'assistant', timestamp: at(minutes), message: { role: 'assistant', content: [{ type: 'tool_use', id, name, input }] } });
+export const toolResult = (minutes, id, text, isError = false) => ({ type: 'user', timestamp: at(minutes), message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, content: [{ type: 'text', text }], is_error: isError }] } });
+
+export function writeTranscript(dir, name, events) {
+  const path = join(dir, name);
+  writeFileSync(path, events.map((e) => JSON.stringify(e)).join('\n') + '\n');
+  return path;
+}
+
+// Prints one line per case and the verdict; returns the exit code. A case is { name, ok, detail }.
+export function report(tool, cases) {
+  let failed = 0;
+  for (const c of cases) {
+    if (!c.ok) failed++;
+    console.log(`  [${c.ok ? 'PASS' : 'FAIL'}] ${c.name}${c.ok ? '' : ` - ${c.detail ?? ''}`}`);
+  }
+  console.log(failed === 0 ? `SELF-TEST PASSED: ${tool}` : `SELF-TEST FAILED: ${tool}: ${failed} case(s)`);
+  return failed === 0 ? 0 : 1;
+}

package/bin/witness-plane-window.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Every plane call in a time window, reads included, with its full result: what a session asked the plane
+// and what the plane answered, for the minutes a claim is about. Read-only.
+//
+//   node witness-plane-window.mjs <file.jsonl> <fromIso> <toIso> [maxChars] [--plane <server>] [--config <path>]
+//   node witness-plane-window.mjs --self-test
+
+import { rmSync } from 'node:fs';
+import { contentOf, entries, isMain, loadConfig, planePrefix, positionals, report, resultText, scratch, toolResult, toolUse, writeTranscript, at } from './witness-lib.mjs';
+
+export async function window(file, prefix, from, to, max = 700) {
+  const uses = new Map();
+  const out = [];
+  for await (const { entry } of entries(file)) {
+    for (const c of contentOf(entry)) {
+      if (c.type === 'tool_use' && typeof c.name === 'string' && c.name.startsWith(prefix)) {
+        uses.set(c.id, { ts: entry.timestamp ?? '', verb: c.name.slice(prefix.length), input: c.input ?? {} });
+      } else if (c.type === 'tool_result' && uses.has(c.tool_use_id)) {
+        const use = uses.get(c.tool_use_id);
+        uses.delete(c.tool_use_id);
+        if (use.ts < from || use.ts > to) continue;
+        const body = resultText(c).replace(/\s+/g, ' ');
+        out.push(`${use.ts} -> ${entry.timestamp} ${use.verb} ${JSON.stringify(use.input).slice(0, 80)} => ${c.is_error ? 'ERROR ' : ''}${body.slice(0, max)}`);
+      }
+    }
+  }
+  return out;
+}
+
+async function selfTest() {
+  const dir = scratch('witness-plane-window');
+  try {
+    const file = writeTranscript(dir, 'coordinator.jsonl', [
+      toolUse(1, 'a', 'mcp__plane__seat_read', { seatId: 3 }),
+      toolResult(1, 'a', 'seat 3: building'),
+      toolUse(10, 'b', 'mcp__plane__callout', { seatId: 3, ruling: 'go' }),
+      toolResult(11, 'b', 'RULING RECORDED, NOT DELIVERED'),
+      toolUse(30, 'c', 'mcp__plane__seat_read', { seatId: 3 }),
+      toolResult(30, 'c', 'seat 3: waiting'),
+    ]);
+    const lines = await window(file, 'mcp__plane__', at(5), at(20));
+    return report('witness-plane-window', [
+      { name: 'a call inside the window is a line, with its result', ok: lines.length === 1 && lines[0].includes('callout') && lines[0].includes('RECORDED, NOT DELIVERED'), detail: lines.join(' | ') },
+      { name: 'CONTROL: calls before and after the window are not', ok: !lines.some((l) => l.includes('seat_read')), detail: lines.join(' | ') },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [file, from, to, max] = positionals(argv, ['--plane', '--config']);
+  if (!file || !from || !to) { console.log('usage: witness-plane-window.mjs <file.jsonl> <fromIso> <toIso> [maxChars] [--plane <server>]'); process.exit(2); }
+  for (const line of await window(file, planePrefix(argv, loadConfig(argv)), from, to, Number(max ?? 700))) console.log(`${line}\n`);
+}

package/bin/witness-procs.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// The processes doing a run's work, by the worktree they run in, and the runner's own processes. A quiet
+// compile is a busy process, and no runner where there was one is a restart, which ends every live
+// session. Windows reads the process table through PowerShell's CIM query, anything else through `ps`.
+// Read-only.
+//
+//   node witness-procs.mjs [--key <worktree-folder-name>] [--pattern <regex>] [--config <path>]
+//   -> one line per process: `RUNNER|<pid>` for the runner, `<pid>|<name>` for a match
+//   node witness-procs.mjs --self-test
+
+import { execFileSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { flag, isMain, loadConfig, report } from './witness-lib.mjs';
+
+// Every process with its id, its name, its command line and its executable path.
+export function listProcesses() {
+  if (process.platform === 'win32') {
+    const json = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command',
+      'Get-CimInstance Win32_Process | Select-Object ProcessId,Name,CommandLine,ExecutablePath | ConvertTo-Json -Compress'],
+    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    const rows = JSON.parse(json);
+    return (Array.isArray(rows) ? rows : [rows]).map((r) => ({ pid: r.ProcessId, name: String(r.Name ?? ''), cmd: String(r.CommandLine ?? ''), exe: String(r.ExecutablePath ?? '') }));
+  }
+  const out = execFileSync('ps', ['-eo', 'pid=,comm=,args='], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return out.split('\n').filter((l) => l.trim()).map((l) => {
+    const m = l.trim().match(/^(\d+)\s+(\S+)\s+(.*)$/);
+    return m ? { pid: Number(m[1]), name: m[2], cmd: m[3], exe: '' } : null;
+  }).filter(Boolean);
+}
+
+// The runner is a node process whose command line names periscope; a match is a process of the
+// configured pattern running in the worktree named by `key`. This tool never reports itself.
+export function classify(processes, { key = '', pattern = null } = {}) {
+  const re = pattern ? new RegExp(pattern, 'i') : null;
+  const out = [];
+  for (const p of processes) {
+    const text = `${p.cmd} ${p.exe}`;
+    if (/witness-procs/.test(text)) continue;
+    if (/^node(\.exe)?$/i.test(p.name) && /periscope/i.test(p.cmd)) { out.push(`RUNNER|${p.pid}`); continue; }
+    if (key && re && text.includes(key) && re.test(text)) out.push(`${p.pid}|${p.name}`);
+  }
+  return out.sort();
+}
+
+function selfTest() {
+  const synthetic = [
+    { pid: 10, name: 'node.exe', cmd: 'node C:/npm/node_modules/@scope/periscope/dist/bin/periscope.js serve', exe: '' },
+    { pid: 11, name: 'dotnet', cmd: 'dotnet test --project tests/App.Tests', exe: 'C:/work/pipeline-7/x' },
+    { pid: 12, name: 'dotnet', cmd: 'dotnet test --project tests/App.Tests', exe: 'C:/work/pipeline-9/x' },
+    { pid: 13, name: 'node.exe', cmd: 'node vitest run C:/work/pipeline-7', exe: '' },
+    { pid: 14, name: 'node.exe', cmd: 'node witness-procs.mjs --key pipeline-7', exe: '' },
+  ];
+  const lines = classify(synthetic, { key: 'pipeline-7', pattern: 'dotnet.*test|vitest' });
+  let live = [];
+  let liveError = '';
+  try { live = listProcesses(); } catch (e) { liveError = String(e.message ?? e).slice(0, 120); }
+  return report('witness-procs', [
+    { name: 'the runner and the work in this worktree are reported', ok: JSON.stringify(lines) === JSON.stringify(['11|dotnet', '13|node.exe', 'RUNNER|10']), detail: JSON.stringify(lines) },
+    { name: 'CONTROL: the same work in another worktree, and this tool itself, are not', ok: !lines.some((l) => l.startsWith('12|') || l.startsWith('14|')), detail: JSON.stringify(lines) },
+    { name: 'the process table is read on this machine, this process in it', ok: live.some((p) => p.pid === process.pid), detail: liveError || `${live.length} processes, ${process.pid} absent` },
+  ]);
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(selfTest());
+  const config = loadConfig(argv);
+  const key = flag(argv, '--key') ?? (config.worktree ? basename(config.worktree) : '');
+  const pattern = flag(argv, '--pattern') ?? config.testProcessPattern ?? null;
+  for (const line of classify(listProcesses(), { key, pattern })) console.log(line);
+}

package/bin/witness-spawn-task.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Each `seat_spawn` call's task exactly as the coordinator sent it, one file per spawn, and the plane's
+// answer: what a seat was told, in the words that reached it. Writes only into <outDir>.
+//
+//   node witness-spawn-task.mjs <file.jsonl> <outDir> [--plane <server>] [--config <path>]
+//   node witness-spawn-task.mjs --self-test
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { contentOf, entries, isMain, loadConfig, planePrefix, positionals, report, resultText, scratch, toolResult, toolUse, writeTranscript } from './witness-lib.mjs';
+
+export async function spawnTasks(file, prefix, outDir) {
+  mkdirSync(outDir, { recursive: true });
+  const pending = new Set();
+  const out = [];
+  for await (const { entry } of entries(file)) {
+    for (const c of contentOf(entry)) {
+      if (c.type === 'tool_use' && c.name === `${prefix}seat_spawn`) {
+        pending.add(c.id);
+        const input = c.input ?? {};
+        const path = join(outDir, `spawn-${input.seatId}-task-as-sent.txt`);
+        writeFileSync(path, `${entry.timestamp}\n${JSON.stringify({ ...input, task: undefined })}\n\n${input.task ?? ''}`);
+        out.push(`seat ${input.seatId} task ${String(input.task ?? '').length} chars -> ${path}`);
+      } else if (c.type === 'tool_result' && pending.has(c.tool_use_id)) {
+        pending.delete(c.tool_use_id);
+        out.push(`  result: ${resultText(c)}`);
+      }
+    }
+  }
+  return out;
+}
+
+async function selfTest() {
+  const dir = scratch('witness-spawn-task');
+  try {
+    const task = 'You are a BUILD SEAT.\nYour spec: 01-a-slice.md\n\tindented line, kept as sent';
+    const file = writeTranscript(dir, 'coordinator.jsonl', [
+      toolUse(1, 'a', 'mcp__plane__seat_spawn', { seatId: 12, task }),
+      toolResult(2, 'a', 'spawned; act 4321'),
+      toolUse(3, 'b', 'mcp__plane__seat_read', { seatId: 12 }),
+      toolResult(3, 'b', 'seat 12: planning'),
+    ]);
+    const lines = await spawnTasks(file, 'mcp__plane__', join(dir, 'out'));
+    const saved = readFileSync(join(dir, 'out', 'spawn-12-task-as-sent.txt'), 'utf8');
+    return report('witness-spawn-task', [
+      { name: 'the task is saved exactly as sent', ok: saved.endsWith(`\n\n${task}`), detail: JSON.stringify(saved.slice(-80)) },
+      { name: 'the plane\'s answer is reported', ok: lines.some((l) => l.includes('result: spawned; act 4321')), detail: lines.join(' | ') },
+      { name: 'CONTROL: another plane call is not a spawn', ok: lines.length === 2, detail: `${lines.length} lines` },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [file, outDir] = positionals(argv, ['--plane', '--config']);
+  if (!file || !outDir) { console.log('usage: witness-spawn-task.mjs <file.jsonl> <outDir> [--plane <server>]'); process.exit(2); }
+  for (const line of await spawnTasks(file, planePrefix(argv, loadConfig(argv)), outDir)) console.log(line);
+}