@opencode-cockpit/daemon 0.1.5 → 0.2.1

package/dist/main.js

@@ -11,7 +11,8 @@ const daemon = new Daemon({
   paths,
   modules: createModules({
     shell: {
-      registryFile: join(paths.home, "shells.json")
+      registryFile: join(paths.home, "shells.json"),
+      logDir: join(paths.home, "logs")
     }
   }),
   idleTimeoutMs: Number(env.COCKPIT_IDLE_TIMEOUT_MS ?? 10 * 60_000),

package/dist/modules/shell/methods.js

@@ -0,0 +1,204 @@
+import { invalidParams, invalidState } from "../../core/errors.js";
+import { compilePattern } from "./module.js";
+import { waitFor } from "./wait.js";
+import { PRESETS, presetByName, presetForCommand } from "./watch/presets.js";
+import { compileRule, Watcher } from "./watch/watcher.js";
+
+/** Preset name for a watcher with no patterns: it only reports the process dying. */
+const EXIT_ONLY = "exit";
+
+/**
+ * The `shell.*` methods, kept apart from the module's lifecycle and bookkeeping so each file has
+ * one job: this one maps protocol calls onto the module, `module.ts` owns the shells.
+ */
+export function shellMethods(module) {
+  return {
+    start: params => module.startShell(params),
+    list: params => {
+      const owner = params.owner;
+      return [...module.shells.values()].filter(s => params.includeExited || s.running).filter(s => !owner?.project || s.spec.owner.project === owner.project).filter(s => !owner?.session || s.spec.owner.session === owner.session).map(s => s.info());
+    },
+    get: ({
+      id
+    }) => module.require(id).info(),
+    read: ({
+      id,
+      after,
+      tail,
+      limit,
+      grep,
+      ignoreCase
+    }) => {
+      const shell = module.require(id);
+      const page = shell.log.read({
+        after,
+        tail,
+        limit,
+        grep: grep === undefined ? undefined : compilePattern(grep, ignoreCase)
+      });
+      return {
+        ...page,
+        status: shell.status
+      };
+    },
+    screen: ({
+      id
+    }) => module.require(id).snapshot(),
+    write: ({
+      id,
+      data
+    }) => {
+      const shell = module.require(id);
+      if (!shell.running) throw invalidState(`shell ${id} is ${shell.status}`);
+      return {
+        bytes: shell.write(data)
+      };
+    },
+    resize: ({
+      id,
+      cols,
+      rows
+    }) => {
+      module.require(id).resize(cols, rows);
+      return {};
+    },
+    wait: async params => {
+      const shell = module.require(params.id);
+      const outcome = await waitFor(shell, params, compilePattern);
+      return {
+        ...outcome,
+        info: shell.info()
+      };
+    },
+    stop: async ({
+      id,
+      signal,
+      graceMs
+    }, {
+      peer
+    }) => {
+      const shell = module.require(id);
+      await shell.stop(signal, graceMs, {
+        reason: "request",
+        by: peer.name
+      });
+      await shell.exited;
+      return shell.info();
+    },
+    restart: async ({
+      id
+    }, {
+      peer
+    }) => {
+      const shell = module.require(id);
+      if (shell.running) {
+        await shell.stop("SIGTERM", 3000, {
+          reason: "request",
+          by: peer.name
+        });
+        await shell.exited;
+      }
+      module.spawn(shell);
+      return shell.info();
+    },
+    remove: async ({
+      id
+    }, {
+      peer
+    }) => {
+      const shell = module.require(id);
+      if (shell.running) {
+        await shell.stop("SIGTERM", 3000, {
+          reason: "request",
+          by: peer.name
+        });
+        await shell.exited;
+      }
+      module.forget(shell);
+      return {};
+    },
+    attach: ({
+      id,
+      fromOffset
+    }, {
+      peer
+    }) => {
+      const shell = module.require(id);
+      module.detach(peer, id);
+      const replay = shell.raw.since(fromOffset ?? 0);
+      module.attachStream(peer, shell);
+      return {
+        offset: replay.offset,
+        replay: Buffer.from(replay.bytes).toString("base64")
+      };
+    },
+    clear: ({
+      owner,
+      finishedBeforeMs
+    }) => {
+      const cutoff = Date.now() - (finishedBeforeMs ?? 0);
+      const removed = [];
+      for (const shell of [...module.shells.values()]) {
+        if (shell.running) continue;
+        const info = shell.info();
+        if (owner?.project && info.owner.project !== owner.project) continue;
+        if (owner?.session && info.owner.session !== owner.session) continue;
+        if ((info.endedAt ?? 0) > cutoff) continue;
+        module.forget(shell);
+        removed.push(info.id);
+      }
+      return {
+        removed
+      };
+    },
+    watch: ({
+      id,
+      preset,
+      rule
+    }) => {
+      const shell = module.require(id);
+      const command = [shell.spec.command, ...shell.spec.args].join(" ");
+      const named = preset && preset !== "auto" && preset !== EXIT_ONLY;
+      const chosen = rule ? undefined : named ? presetByName(preset) ?? invalidParams(`no watch preset named "${preset}". Call shell.presets for the list, or pass your own rule (done/fail/ok patterns).`) : preset === EXIT_ONLY ? undefined : presetForCommand(command);
+      if (chosen instanceof Error) throw chosen;
+      // No pattern fits a command like `sleep 300`, and that is still worth watching: an empty rule
+      // reports nothing until the process dies, which is exactly crash detection.
+      const watchRule = rule ?? chosen?.rule ?? {};
+      try {
+        shell.watcher = new Watcher(compileRule(watchRule), chosen?.name ?? (rule ? undefined : EXIT_ONLY));
+      } catch (err) {
+        throw invalidParams(`invalid watch pattern: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      shell.onWatchChange = change => {
+        module.emit("shell.watch", {
+          info: shell.info(),
+          ...change
+        });
+      };
+      module.armIdle(shell);
+      return shell.info();
+    },
+    unwatch: ({
+      id
+    }) => {
+      const shell = module.require(id);
+      shell.watcher = undefined;
+      shell.onWatchChange = undefined;
+      module.clearIdle(id);
+      return shell.info();
+    },
+    presets: () => PRESETS.map(preset => ({
+      name: preset.name,
+      match: preset.match,
+      rule: preset.rule
+    })),
+    detach: ({
+      id
+    }, {
+      peer
+    }) => {
+      module.detach(peer, id);
+      return {};
+    }
+  };
+}

package/dist/modules/shell/module.js

@@ -1,10 +1,11 @@
-import { invalidParams, invalidState, notFound } from "../../core/errors.js";
+import { join } from "node:path";
+import { invalidParams, notFound } from "../../core/errors.js";
 import { silentLogger } from "../../core/logger.js";
 import { newShellId } from "./ids.js";
+import { shellMethods } from "./methods.js";
 import { bunPtyBackend } from "./pty.js";
 import { ProcessRegistry } from "./registry.js";
 import { Shell } from "./shell.js";
-import { waitFor } from "./wait.js";
 const DEFAULT_LIMITS = {
   logChars: 4_000_000,
   rawBytes: 1_000_000,
@@ -12,10 +13,14 @@ const DEFAULT_LIMITS = {
 };
 export class ShellModule {
   name = "shell";
+  /** @internal */
   shells = new Map();
+  /** @internal */
   attachments = new Map(); // `${peer.id}:${shellId}` → detach
 
   log = silentLogger;
+  idleTimers = new Map();
+  /** @internal */
   emit = () => {};
   constructor(options = {}) {
     this.options = options;
@@ -37,7 +42,10 @@ export class ShellModule {
     }
   }
   async stop() {
-    await Promise.all([...this.shells.values()].map(s => s.stop("SIGTERM", 2000).catch(() => {})));
+    for (const id of [...this.idleTimers.keys()]) this.clearIdle(id);
+    await Promise.all([...this.shells.values()].map(s => s.stop("SIGTERM", 2000, {
+      reason: "shutdown"
+    }).catch(() => {})));
     for (const detach of this.attachments.values()) detach();
     for (const shell of this.shells.values()) shell.dispose();
     this.attachments.clear();
@@ -47,139 +55,9 @@ export class ShellModule {
     for (const shell of this.shells.values()) if (shell.running) return true;
     return false;
   }
-  methods = {
-    start: params => this.startShell(params),
-    list: params => {
-      const owner = params.owner;
-      return [...this.shells.values()].filter(s => params.includeExited || s.running).filter(s => !owner?.project || s.spec.owner.project === owner.project).filter(s => !owner?.session || s.spec.owner.session === owner.session).map(s => s.info());
-    },
-    get: ({
-      id
-    }) => this.require(id).info(),
-    read: ({
-      id,
-      after,
-      tail,
-      limit,
-      grep,
-      ignoreCase
-    }) => {
-      const shell = this.require(id);
-      const page = shell.log.read({
-        after,
-        tail,
-        limit,
-        grep: grep === undefined ? undefined : compilePattern(grep, ignoreCase)
-      });
-      return {
-        ...page,
-        status: shell.status
-      };
-    },
-    screen: ({
-      id
-    }) => this.require(id).snapshot(),
-    write: ({
-      id,
-      data
-    }) => {
-      const shell = this.require(id);
-      if (!shell.running) throw invalidState(`shell ${id} is ${shell.status}`);
-      return {
-        bytes: shell.write(data)
-      };
-    },
-    resize: ({
-      id,
-      cols,
-      rows
-    }) => {
-      this.require(id).resize(cols, rows);
-      return {};
-    },
-    wait: async params => {
-      const shell = this.require(params.id);
-      const outcome = await waitFor(shell, params, compilePattern);
-      return {
-        ...outcome,
-        info: shell.info()
-      };
-    },
-    stop: async ({
-      id,
-      signal,
-      graceMs
-    }) => {
-      const shell = this.require(id);
-      await shell.stop(signal, graceMs);
-      await shell.exited;
-      return shell.info();
-    },
-    restart: async ({
-      id
-    }) => {
-      const shell = this.require(id);
-      if (shell.running) {
-        await shell.stop("SIGTERM", 3000);
-        await shell.exited;
-      }
-      this.spawn(shell);
-      return shell.info();
-    },
-    remove: async ({
-      id
-    }) => {
-      const shell = this.require(id);
-      if (shell.running) {
-        await shell.stop("SIGTERM", 3000);
-        await shell.exited;
-      }
-      this.forget(shell);
-      return {};
-    },
-    attach: ({
-      id,
-      fromOffset
-    }, {
-      peer
-    }) => {
-      const shell = this.require(id);
-      this.detach(peer, id);
-      const replay = shell.raw.since(fromOffset ?? 0);
-      this.attachStream(peer, shell);
-      return {
-        offset: replay.offset,
-        replay: Buffer.from(replay.bytes).toString("base64")
-      };
-    },
-    clear: ({
-      owner,
-      finishedBeforeMs
-    }) => {
-      const cutoff = Date.now() - (finishedBeforeMs ?? 0);
-      const removed = [];
-      for (const shell of [...this.shells.values()]) {
-        if (shell.running) continue;
-        const info = shell.info();
-        if (owner?.project && info.owner.project !== owner.project) continue;
-        if (owner?.session && info.owner.session !== owner.session) continue;
-        if ((info.endedAt ?? 0) > cutoff) continue;
-        this.forget(shell);
-        removed.push(info.id);
-      }
-      return {
-        removed
-      };
-    },
-    detach: ({
-      id
-    }, {
-      peer
-    }) => {
-      this.detach(peer, id);
-      return {};
-    }
-  };
+  methods = shellMethods(this);
+
+  /** @internal used by methods.ts */
   startShell(params) {
     if (params.reuse) {
       const previous = this.findReusable(params);
@@ -194,8 +72,9 @@ export class ShellModule {
         return previous.info();
       }
     }
+    const id = this.uniqueId();
     const shell = new Shell({
-      id: this.uniqueId(),
+      id,
       command: params.command,
       args: params.args,
       cwd: params.cwd,
@@ -204,7 +83,9 @@ export class ShellModule {
       cols: params.cols,
       rows: params.rows,
       owner: params.owner,
-      timeoutMs: params.timeoutMs
+      timeoutMs: params.timeoutMs,
+      idleTimeoutMs: params.idleTimeoutMs,
+      logFile: params.logFile ? join(this.options.logDir ?? "/tmp", `${id}.log`) : undefined
     }, this.backend, this.limits);
     this.shells.set(shell.id, shell);
     shell.subscribe({
@@ -214,6 +95,8 @@ export class ShellModule {
     this.pruneFinished();
     return shell.info();
   }
+
+  /** @internal used by methods.ts */
   findReusable(params) {
     const args = JSON.stringify(params.args);
     let match;
@@ -225,6 +108,8 @@ export class ShellModule {
     }
     return match;
   }
+
+  /** @internal used by methods.ts */
   spawn(shell) {
     try {
       shell.start();
@@ -257,6 +142,8 @@ export class ShellModule {
     });
     this.emit("shell.exited", info);
   }
+
+  /** @internal used by methods.ts */
   attachStream(peer, shell) {
     const key = `${peer.id}:${shell.id}`;
     const flushMs = this.options.outputFlushMs ?? 16;
@@ -290,10 +177,42 @@ export class ShellModule {
     this.attachments.set(key, detach);
     peer.onClose(detach);
   }
+
+  /** @internal used by methods.ts */
   detach(peer, id) {
     this.attachments.get(`${peer.id}:${id}`)?.();
   }
+
+  /**
+   * Rules without a `done` pattern end a run on silence, so poll those watchers; the check is a
+   * timestamp comparison, and only shells that need it are polled.
+   */
+  /** @internal used by methods.ts */
+  armIdle(shell) {
+    this.clearIdle(shell.id);
+    const idleMs = shell.watcher?.idleMs;
+    if (!idleMs) return;
+    const timer = setInterval(() => {
+      if (!shell.watcher || Date.now() - shell.lastOutputAt < idleMs) return;
+      const change = shell.watcher.idle();
+      if (change) this.emit("shell.watch", {
+        info: shell.info(),
+        ...change
+      });
+    }, Math.max(500, Math.floor(idleMs / 2)));
+    this.idleTimers.set(shell.id, timer);
+  }
+
+  /** @internal used by methods.ts */
+  clearIdle(id) {
+    const timer = this.idleTimers.get(id);
+    if (timer) clearInterval(timer);
+    this.idleTimers.delete(id);
+  }
+
+  /** @internal used by methods.ts */
   forget(shell) {
+    this.clearIdle(shell.id);
     for (const [key, detach] of this.attachments) if (key.endsWith(`:${shell.id}`)) detach();
     shell.dispose();
     this.shells.delete(shell.id);
@@ -301,21 +220,29 @@ export class ShellModule {
       id: shell.id
     });
   }
+
+  /** @internal used by methods.ts */
   pruneFinished() {
     const max = this.options.maxFinished ?? 50;
     const finished = [...this.shells.values()].filter(s => !s.running);
     for (const shell of finished.slice(0, Math.max(0, finished.length - max))) this.forget(shell);
   }
+
+  /** @internal used by methods.ts */
   require(id) {
     const shell = this.shells.get(id);
     if (!shell) throw notFound(`shell ${id}`);
     return shell;
   }
+
+  /** @internal used by methods.ts */
   uniqueId() {
     let id = newShellId();
     while (this.shells.has(id)) id = newShellId();
     return id;
   }
+
+  /** @internal used by methods.ts */
   environment(extra) {
     const env = {};
     for (const [k, v] of Object.entries(this.options.baseEnv ?? process.env)) if (v !== undefined) env[k] = v;

package/dist/modules/shell/output/palette.js

@@ -0,0 +1,19 @@
+/** Standard xterm palette, so the daemon can hand UIs resolved colours instead of escape codes. */
+const BASE = ["#000000", "#cd0000", "#00cd00", "#cdcd00", "#0000ee", "#cd00cd", "#00cdcd", "#e5e5e5", "#7f7f7f", "#ff0000", "#00ff00", "#ffff00", "#5c5cff", "#ff00ff", "#00ffff", "#ffffff"];
+const STEPS = [0, 95, 135, 175, 215, 255];
+const hex = n => n.toString(16).padStart(2, "0");
+export function paletteColor(index) {
+  if (index < 16) return BASE[index] ?? "#ffffff";
+  if (index < 232) {
+    const value = index - 16;
+    const r = STEPS[Math.floor(value / 36) % 6] ?? 0;
+    const g = STEPS[Math.floor(value / 6) % 6] ?? 0;
+    const b = STEPS[value % 6] ?? 0;
+    return `#${hex(r)}${hex(g)}${hex(b)}`;
+  }
+  const grey = 8 + (index - 232) * 10;
+  return `#${hex(grey)}${hex(grey)}${hex(grey)}`;
+}
+export function rgbColor(value) {
+  return `#${hex(value >> 16 & 0xff)}${hex(value >> 8 & 0xff)}${hex(value & 0xff)}`;
+}

package/dist/modules/shell/output/screen.js

@@ -1,4 +1,5 @@
 import { Terminal } from "@xterm/headless";
+import { paletteColor, rgbColor } from "./palette.js";
 
 /** Full VT emulation of a shell's output: what a human would see right now (ADR 0003). */
 export class Screen {
@@ -25,10 +26,16 @@ export class Screen {
     await new Promise(resolve => this.term.write("", resolve));
     const buffer = this.term.buffer.active;
     const rows = [];
+    const styled = [];
     for (let y = 0; y < this.term.rows; y++) {
-      rows.push(buffer.getLine(buffer.baseY + y)?.translateToString(true) ?? "");
+      const line = buffer.getLine(buffer.baseY + y);
+      rows.push(line?.translateToString(true) ?? "");
+      styled.push(line ? styleRuns(line, this.term.cols) : []);
+    }
+    while (rows.length > 0 && rows[rows.length - 1] === "") {
+      rows.pop();
+      styled.pop();
     }
-    while (rows.length > 0 && rows[rows.length - 1] === "") rows.pop();
     return {
       text: rows.join("\n"),
       cols: this.term.cols,
@@ -36,10 +43,60 @@ export class Screen {
       cursor: {
         x: buffer.cursorX,
         y: buffer.cursorY
-      }
+      },
+      styled
     };
   }
   dispose() {
     this.term.dispose();
   }
+}
+/** Groups a row's cells into runs of identical style, trimming the trailing blank. */
+function styleRuns(line, cols) {
+  const runs = [];
+  let current;
+  for (let x = 0; x < cols; x++) {
+    const cell = line.getCell(x);
+    if (!cell || cell.getWidth() === 0) continue;
+    const chars = cell.getChars() || " ";
+    const style = cellStyle(cell);
+    if (current && sameStyle(current, style)) current.text += chars;else {
+      current = {
+        ...style,
+        text: chars
+      };
+      runs.push(current);
+    }
+  }
+  // Drop trailing spaces so a mostly empty row costs nothing to send or paint.
+  while (runs.length > 0) {
+    const last = runs[runs.length - 1];
+    last.text = last.text.replace(/\s+$/, "");
+    if (last.text.length > 0) break;
+    runs.pop();
+  }
+  return runs;
+}
+function cellStyle(cell) {
+  const inverse = cell.isInverse() !== 0;
+  const fg = colorOf(cell, inverse ? "bg" : "fg");
+  const bg = colorOf(cell, inverse ? "fg" : "bg");
+  const style = {};
+  if (fg) style.fg = fg;
+  if (bg) style.bg = bg;
+  if (cell.isBold()) style.bold = true;
+  if (cell.isDim()) style.dim = true;
+  if (cell.isItalic()) style.italic = true;
+  if (cell.isUnderline()) style.underline = true;
+  return style;
+}
+function colorOf(cell, which) {
+  const isDefault = which === "fg" ? cell.isFgDefault() : cell.isBgDefault();
+  if (isDefault) return undefined;
+  const rgb = which === "fg" ? cell.isFgRGB() : cell.isBgRGB();
+  const value = which === "fg" ? cell.getFgColor() : cell.getBgColor();
+  return rgb ? rgbColor(value) : paletteColor(value);
+}
+function sameStyle(a, b) {
+  return a.fg === b.fg && a.bg === b.bg && a.bold === b.bold && a.dim === b.dim && a.italic === b.italic && a.underline === b.underline;
 }

package/dist/modules/shell/shell.js

@@ -1,3 +1,5 @@
+import { createWriteStream, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { LineLog } from "./output/line-log.js";
 import { OutputNormalizer } from "./output/normalizer.js";
 import { RawRing } from "./output/raw-ring.js";
@@ -13,8 +15,15 @@ export class Shell {
   /** First log line number belonging to the current run. */
   runStartLine = 1;
   lastOutputAt = Date.now();
+  /** Health rule attached to this shell, if any (see watch/watcher.ts). */
+
+  /** Called when the watcher's reported status changes; never per line. */
+
   listeners = new Set();
   startedAt = 0;
+
+  /** Why the daemon stopped it, when it was not a user or agent request. */
+
   stopRequested = false;
   exitPromise = Promise.resolve();
   constructor(spec, backend, limits) {
@@ -54,6 +63,25 @@ export class Shell {
       this.screen.reset();
     }
     this.runStartLine = this.log.lastLine + 1;
+    this.stoppedBecause = undefined;
+    this.stopReason = undefined;
+    this.stoppedBy = undefined;
+    if (this.spec.logFile && !this.logWriter) {
+      mkdirSync(dirname(this.spec.logFile), {
+        recursive: true
+      });
+      const file = createWriteStream(this.spec.logFile, {
+        flags: "a",
+        mode: 0o600
+      });
+      file.on("error", () => {
+        this.logWriter = undefined;
+      });
+      this.logWriter = {
+        write: text => file.write(text),
+        end: () => file.end()
+      };
+    }
     this.status = "running";
     this.startedAt = Date.now();
     this.lastOutputAt = this.startedAt;
@@ -83,7 +111,20 @@ export class Shell {
     const pty = this.pty;
     this.exitPromise = pty.exited.then(exit => this.onExit(pty, exit));
     if (this.spec.timeoutMs) {
-      this.timeout = setTimeout(() => void this.stop("SIGTERM", 3000), this.spec.timeoutMs);
+      this.timeout = setTimeout(() => {
+        this.stoppedBecause = `reached its ${Math.round((this.spec.timeoutMs ?? 0) / 1000)}s time limit`;
+        this.stopReason = "timeout";
+        void this.stop("SIGTERM", 3000);
+      }, this.spec.timeoutMs);
+    }
+    if (this.spec.idleTimeoutMs) {
+      const idleMs = this.spec.idleTimeoutMs;
+      this.idleTimer = setInterval(() => {
+        if (!this.running || Date.now() - this.lastOutputAt < idleMs) return;
+        this.stoppedBecause = `produced no output for ${Math.round(idleMs / 1000)}s`;
+        this.stopReason = "idle";
+        void this.stop("SIGTERM", 3000);
+      }, Math.max(500, Math.floor(idleMs / 4)));
     }
   }
   write(data) {
@@ -97,11 +138,18 @@ export class Shell {
     if (this.running) this.pty?.resize(cols, rows);
   }
 
-  /** Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. */
-  async stop(signal = "SIGTERM", graceMs = 3000) {
+  /**
+   * Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. `cause` says who
+   * asked, so an exit can be reported as a stop rather than as an unexplained kill.
+   */
+  async stop(signal = "SIGTERM", graceMs = 3000, cause = {
+    reason: "request"
+  }) {
     const pty = this.pty;
     if (!pty || !this.running) return;
     this.stopRequested = true;
+    this.stopReason ??= cause.reason;
+    this.stoppedBy ??= cause.by;
     pty.signal(signal);
     const exited = await Promise.race([this.exitPromise.then(() => true), Bun.sleep(graceMs).then(() => false)]);
     if (!exited) {
@@ -137,11 +185,17 @@ export class Shell {
     if (this.exit?.signal) info.signal = this.exit.signal;
     if (this.error) info.error = this.error;
     if (this.summary) info.summary = this.summary;
+    if (this.stopReason) info.stopReason = this.stopReason;
+    if (this.stoppedBy) info.stoppedBy = this.stoppedBy;
+    if (this.spec.logFile) info.logFile = this.spec.logFile;
+    if (this.watcher) info.watch = this.watcher.state();
     if (this.endedAt) info.endedAt = this.endedAt;
     return info;
   }
   dispose() {
     clearTimeout(this.timeout);
+    clearInterval(this.idleTimer);
+    this.logWriter?.end();
     this.listeners.clear();
     this.pty?.close();
     this.screen.dispose();
@@ -162,6 +216,9 @@ export class Shell {
   createNormalizer() {
     return new OutputNormalizer(text => {
       const line = this.log.append(text);
+      this.logWriter?.write(`${text}\n`);
+      const change = this.watcher?.line(text);
+      if (change) this.onWatchChange?.(change);
       for (const l of this.listeners) l.line?.(line);
     });
   }
@@ -179,11 +236,16 @@ export class Shell {
   onExit(pty, exit) {
     if (this.pty !== pty) return; // a newer run replaced this one
     clearTimeout(this.timeout);
+    clearInterval(this.idleTimer);
+    this.logWriter?.end();
+    this.logWriter = undefined;
     this.normalizer.flush();
     this.exit = exit;
     this.endedAt = Date.now();
     this.status = this.stopRequested || exit.signal ? "killed" : "exited";
-    this.summary = this.summarize();
+    this.summary = this.stoppedBecause ? `stopped: ${this.stoppedBecause}` : this.summarize();
+    const ended = this.watcher?.exited(exit.exitCode ?? undefined, exit.signal ?? undefined);
+    if (ended) this.onWatchChange?.(ended);
     // Session leader is gone; make sure nothing it left behind keeps running.
     if (pty.groupAlive()) pty.signal("SIGHUP");
     pty.close();

package/dist/modules/shell/watch/presets.js

@@ -0,0 +1,299 @@
+/**
+ * Watch rules for common tools, as data rather than parsers: `done` marks the end of a run, `fail`
+ * and `ok` say how it went. They are deliberately conservative — matching a tool's summary line,
+ * not its full output — and a caller can always pass its own rule instead. Adding a tool is a row
+ * here, and a wrong guess costs a status, never a crash.
+ */
+export const PRESETS = [
+// TypeScript and linting
+{
+  name: "tsc",
+  match: "\\btsc\\b",
+  rule: {
+    done: "Found \\d+ errors?|Watching for file changes",
+    fail: "error TS\\d+",
+    ok: "Found 0 errors"
+  }
+}, {
+  name: "eslint",
+  match: "\\beslint\\b",
+  rule: {
+    done: "\\d+ problems?|Done in |^\\s*$",
+    fail: "\\d+ problems? \\(\\d*[1-9]\\d* error",
+    ok: "0 problems"
+  }
+}, {
+  name: "biome",
+  match: "\\bbiome\\b",
+  rule: {
+    done: "Checked \\d+ file|Found \\d+ (?:error|warning)",
+    fail: "Found \\d+ errors?",
+    ok: "No fixes applied|Checked \\d+ files?"
+  }
+}, {
+  name: "prettier",
+  match: "\\bprettier\\b",
+  rule: {
+    done: "\\d+ms$",
+    fail: "\\[error\\]",
+    ok: "\\(unchanged\\)"
+  }
+}, {
+  name: "mypy",
+  match: "\\bmypy\\b",
+  rule: {
+    done: "Success: no issues|Found \\d+ errors?",
+    fail: "Found \\d+ errors?",
+    ok: "Success: no issues"
+  }
+}, {
+  name: "ruff",
+  match: "\\bruff\\b",
+  rule: {
+    done: "Found \\d+ error|All checks passed",
+    fail: "Found \\d+ errors?",
+    ok: "All checks passed"
+  }
+},
+// Test runners
+{
+  name: "vitest",
+  match: "\\bvitest\\b",
+  rule: {
+    done: "Test Files\\s+\\d|Test Files\\s+\\w",
+    fail: "Test Files.*failed",
+    ok: "Test Files.*passed"
+  }
+}, {
+  name: "jest",
+  match: "\\bjest\\b",
+  rule: {
+    done: "^Tests:\\s",
+    fail: "Tests:.*\\d+ failed",
+    ok: "Tests:.*passed"
+  }
+}, {
+  name: "mocha",
+  match: "\\bmocha\\b",
+  rule: {
+    done: "\\d+ (?:passing|failing)",
+    fail: "[1-9]\\d* failing",
+    ok: "\\d+ passing"
+  }
+}, {
+  name: "bun-test",
+  match: "bun\\s+(?:--\\S+\\s+)*test\\b",
+  rule: {
+    done: "Ran \\d+ tests?",
+    fail: "[1-9]\\d* fail",
+    ok: "\\b0 fail"
+  }
+}, {
+  name: "deno-test",
+  match: "deno\\s+test\\b",
+  rule: {
+    done: "test result:",
+    fail: "FAILED",
+    ok: "test result: ok"
+  }
+}, {
+  name: "pytest",
+  match: "\\bpytest\\b",
+  rule: {
+    done: "=+ .*(?:passed|failed|error|no tests ran).* =+",
+    fail: "\\d+ (?:failed|error)",
+    ok: "\\d+ passed"
+  }
+}, {
+  name: "rspec",
+  match: "\\brspec\\b",
+  rule: {
+    done: "\\d+ examples?, \\d+ failures?",
+    fail: "[1-9]\\d* failures?",
+    ok: " 0 failures"
+  }
+}, {
+  name: "phpunit",
+  match: "phpunit",
+  rule: {
+    done: "^OK \\(|FAILURES!|ERRORS!",
+    fail: "FAILURES!|ERRORS!",
+    ok: "^OK \\("
+  }
+}, {
+  name: "playwright",
+  match: "playwright\\s+test",
+  rule: {
+    done: "\\d+ (?:passed|failed)",
+    fail: "[1-9]\\d* failed",
+    ok: "\\d+ passed"
+  }
+}, {
+  name: "cypress",
+  match: "\\bcypress\\b",
+  rule: {
+    done: "All specs passed|\\d+ of \\d+ failed",
+    fail: "\\d+ of \\d+ failed",
+    ok: "All specs passed"
+  }
+},
+// Dev servers and bundlers
+{
+  name: "vite",
+  match: "\\bvite\\b",
+  rule: {
+    done: "ready in|page reload|hmr update|built in",
+    fail: "Internal server error|Rollup failed|error during build",
+    ok: "ready in|built in"
+  }
+}, {
+  name: "next",
+  match: "\\bnext\\s+(?:dev|build|start)",
+  rule: {
+    done: "Compiled|Ready in|Creating an optimized",
+    fail: "Failed to compile|⨯",
+    ok: "Compiled successfully|✓ Compiled|Ready in"
+  }
+}, {
+  name: "nuxt",
+  match: "\\bnuxt\\b",
+  rule: {
+    done: "Nuxt .*ready|built in|✔ (?:Client|Server)",
+    fail: "ERROR|✖",
+    ok: "ready in|built in"
+  }
+}, {
+  name: "astro",
+  match: "\\bastro\\b",
+  rule: {
+    done: "watching for file changes|Complete!|ready in",
+    fail: "error",
+    ok: "Complete!|ready in",
+    ignoreCase: true
+  }
+}, {
+  name: "angular",
+  match: "\\bng\\s+(?:serve|build|test)",
+  rule: {
+    done: "Application bundle generation complete|Compiled successfully|Build at",
+    fail: "Error:|ERROR",
+    ok: "Compiled successfully|generation complete"
+  }
+}, {
+  name: "webpack",
+  match: "\\b(?:webpack|rspack)\\b",
+  rule: {
+    done: "compiled|webpack \\d",
+    fail: "ERROR in|compiled with \\d+ error",
+    ok: "compiled successfully"
+  }
+}, {
+  name: "esbuild",
+  match: "\\besbuild\\b",
+  rule: {
+    done: "build finished|Done in",
+    fail: "✘ \\[ERROR\\]",
+    ok: "build finished"
+  }
+}, {
+  name: "tsup",
+  match: "\\btsup\\b",
+  rule: {
+    done: "Build success|⚡️ Build",
+    fail: "error",
+    ok: "Build success",
+    ignoreCase: true
+  }
+}, {
+  name: "turbo",
+  match: "\\bturbo\\b",
+  rule: {
+    done: "Tasks:\\s+\\d+ successful",
+    fail: "ERROR  run failed|Tasks:.*\\d+ failed",
+    ok: "Tasks:\\s+\\d+ successful"
+  }
+}, {
+  name: "metro",
+  match: "expo\\s+start|react-native\\s+start|\\bmetro\\b",
+  rule: {
+    done: "Bundled|BUNDLE",
+    fail: "error:|Failed building",
+    ok: "Bundled",
+    ignoreCase: true
+  }
+}, {
+  name: "storybook",
+  match: "storybook",
+  rule: {
+    done: "started|built",
+    fail: "ERR!|Error:",
+    ok: "started|built"
+  }
+},
+// Compiled languages and infrastructure
+{
+  name: "cargo",
+  match: "\\bcargo\\b",
+  rule: {
+    done: "Finished|error\\[|error:|test result:",
+    fail: "^error(?:\\[|:)|test result: FAILED",
+    ok: "Finished|test result: ok"
+  }
+}, {
+  name: "go",
+  match: "\\bgo\\s+(?:build|test|run|vet)",
+  rule: {
+    done: "^(?:ok|FAIL|PASS|\\?)\\s",
+    fail: "^FAIL|\\.go:\\d+:",
+    ok: "^ok\\s"
+  }
+}, {
+  name: "dotnet",
+  match: "\\bdotnet\\s+(?:build|watch|test|run)",
+  rule: {
+    done: "Build succeeded|Build FAILED|Passed!|Failed!",
+    fail: "Build FAILED|Failed!|error [A-Z]+\\d+",
+    ok: "Build succeeded|Passed!"
+  }
+}, {
+  name: "gradle",
+  match: "\\bgradlew?\\b",
+  rule: {
+    done: "BUILD SUCCESSFUL|BUILD FAILED",
+    fail: "BUILD FAILED",
+    ok: "BUILD SUCCESSFUL"
+  }
+}, {
+  name: "maven",
+  match: "\\bmvn\\b",
+  rule: {
+    done: "BUILD SUCCESS|BUILD FAILURE",
+    fail: "BUILD FAILURE",
+    ok: "BUILD SUCCESS"
+  }
+}, {
+  name: "docker-compose",
+  match: "docker[\\s-]compose",
+  rule: {
+    fail: "ERROR|exited with code [1-9]",
+    ok: "Started|healthy",
+    idleSeconds: 5
+  }
+}, {
+  name: "terraform",
+  match: "\\bterraform\\b",
+  rule: {
+    done: "Apply complete|Plan:|Error:",
+    fail: "Error:",
+    ok: "Apply complete|No changes"
+  }
+}];
+const byName = new Map(PRESETS.map(preset => [preset.name, preset]));
+export function presetByName(name) {
+  return byName.get(name);
+}
+
+/** First preset whose `match` fits the command, e.g. `npm run dev` → nothing, `tsc --watch` → tsc. */
+export function presetForCommand(command) {
+  return PRESETS.find(preset => preset.match && new RegExp(preset.match, "i").test(command));
+}

package/dist/modules/shell/watch/watcher.js

@@ -0,0 +1,82 @@
+export function compileRule(rule) {
+  const flags = rule.ignoreCase ? "i" : "";
+  const compiled = {};
+  if (rule.done) compiled.done = new RegExp(rule.done, flags);
+  if (rule.fail) compiled.fail = new RegExp(rule.fail, flags);
+  if (rule.ok) compiled.ok = new RegExp(rule.ok, flags);
+  if (rule.idleSeconds) compiled.idleMs = Math.round(rule.idleSeconds * 1000);
+  return compiled;
+}
+/**
+ * Tracks the health of one shell from its log.
+ *
+ * A run ends when `done` matches (or, without it, after `idleSeconds` of silence); the run's status
+ * is then `fail` if anything matched `fail`, `ok` if anything matched `ok`, and otherwise whatever
+ * it was. Only status changes are reported — a watcher that recompiles a thousand times says
+ * nothing until something actually breaks or gets fixed. A new failing line during an already
+ * failing run is reported too, since it is different news.
+ */
+export class Watcher {
+  status = "pending";
+  runs = 0;
+  since = Date.now();
+  constructor(rule, preset) {
+    this.rule = rule;
+    this.preset = preset;
+  }
+  get idleMs() {
+    return this.rule.done ? undefined : this.rule.idleMs;
+  }
+  state() {
+    const state = {
+      status: this.status,
+      runs: this.runs,
+      since: this.since
+    };
+    if (this.preset) state.preset = this.preset;
+    if (this.summaryText) state.summary = this.summaryText;
+    return state;
+  }
+
+  /** Feeds one committed log line. Returns a change when the reported status or failure changed. */
+  line(text, now = Date.now()) {
+    if (this.rule.fail?.test(text)) this.sawFail = text.trim();else if (this.rule.ok?.test(text)) this.sawOk = text.trim();
+    if (!this.rule.done?.test(text)) return undefined;
+    return this.settle(now);
+  }
+
+  /** Ends the current run because output went quiet (rules without a `done` pattern). */
+  idle(now = Date.now()) {
+    if (this.rule.done) return undefined;
+    return this.settle(now);
+  }
+
+  /** The process ended: a watched program that stops is a failure unless it exited cleanly. */
+  exited(exitCode, signal, now = Date.now()) {
+    const clean = exitCode === 0 && !signal;
+    const summary = clean ? this.summaryText : `process ended ${signal ? `on ${signal}` : `with exit code ${exitCode ?? "?"}`}`;
+    return this.apply(clean ? this.sawFail ? "fail" : this.status === "pending" ? "ok" : this.status : "fail", summary, now);
+  }
+  settle(now) {
+    if (!this.sawFail && !this.sawOk && this.status === "pending") return undefined;
+    this.runs++;
+    const status = this.sawFail ? "fail" : this.sawOk ? "ok" : this.status;
+    const summary = this.sawFail ?? this.sawOk ?? this.summaryText;
+    this.sawFail = undefined;
+    this.sawOk = undefined;
+    return this.apply(status === "pending" ? "unknown" : status, summary, now);
+  }
+  apply(status, summary, now) {
+    const changed = status !== this.status || status === "fail" && summary !== this.summaryText;
+    const previous = this.status;
+    this.status = status;
+    this.summaryText = summary;
+    if (!changed) return undefined;
+    this.since = now;
+    return {
+      previous,
+      current: status,
+      summary
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/daemon",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "cockpitd: the process host behind opencode-cockpit (PTY shells, clean logs, wait conditions)",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/protocol": "0.1.5",
+    "@opencode-cockpit/protocol": "0.2.1",
     "@xterm/headless": "6.0.0"
   },
   "engines": {

package/types/modules/shell/methods.d.ts

@@ -0,0 +1,7 @@
+import type { MethodTable } from "../../core/module.ts";
+import type { ShellModule } from "./module.ts";
+/**
+ * The `shell.*` methods, kept apart from the module's lifecycle and bookkeeping so each file has
+ * one job: this one maps protocol calls onto the module, `module.ts` owns the shells.
+ */
+export declare function shellMethods(module: ShellModule): MethodTable<"shell">;

package/types/modules/shell/module.d.ts

@@ -1,6 +1,7 @@
-import type { MethodTable, Module, ModuleContext } from "../../core/module.ts";
+import type { ShellInfo, StartParams } from "@opencode-cockpit/protocol/shell";
+import type { MethodTable, Module, ModuleContext, Peer } from "../../core/module.ts";
 import { type PtyBackend } from "./pty.ts";
-import { type ShellLimits } from "./shell.ts";
+import { Shell, type ShellLimits } from "./shell.ts";
 export interface ShellModuleOptions {
     backend?: PtyBackend;
     limits?: Partial<ShellLimits>;
@@ -12,32 +13,56 @@ export interface ShellModuleOptions {
     outputFlushMs?: number;
     /** Where to record owned process groups so a restarted daemon can reap orphans. */
     registryFile?: string;
+    /** Directory for per-shell log files, when a caller asks for one. */
+    logDir?: string;
 }
 export declare class ShellModule implements Module<"shell"> {
     private readonly options;
     readonly name: "shell";
-    private readonly shells;
-    private readonly attachments;
+    /** @internal */
+    readonly shells: Map<string, Shell>;
+    /** @internal */
+    readonly attachments: Map<string, () => void>;
     private readonly backend;
     private readonly limits;
     private log;
     private registry;
-    private emit;
+    private readonly idleTimers;
+    /** @internal */
+    emit: ModuleContext["emit"];
     constructor(options?: ShellModuleOptions);
     start(ctx: ModuleContext): Promise<void>;
     stop(): Promise<void>;
     busy(): boolean;
     readonly methods: MethodTable<"shell">;
-    private startShell;
-    private findReusable;
-    private spawn;
+    /** @internal used by methods.ts */
+    startShell(params: StartParams): ShellInfo;
+    /** @internal used by methods.ts */
+    findReusable(params: StartParams): Shell | undefined;
+    /** @internal used by methods.ts */
+    spawn(shell: Shell): void;
     private onExit;
-    private attachStream;
-    private detach;
-    private forget;
-    private pruneFinished;
-    private require;
-    private uniqueId;
-    private environment;
+    /** @internal used by methods.ts */
+    attachStream(peer: Peer, shell: Shell): void;
+    /** @internal used by methods.ts */
+    detach(peer: Peer, id: string): void;
+    /**
+     * Rules without a `done` pattern end a run on silence, so poll those watchers; the check is a
+     * timestamp comparison, and only shells that need it are polled.
+     */
+    /** @internal used by methods.ts */
+    armIdle(shell: Shell): void;
+    /** @internal used by methods.ts */
+    clearIdle(id: string): void;
+    /** @internal used by methods.ts */
+    forget(shell: Shell): void;
+    /** @internal used by methods.ts */
+    pruneFinished(): void;
+    /** @internal used by methods.ts */
+    require(id: string): Shell;
+    /** @internal used by methods.ts */
+    uniqueId(): string;
+    /** @internal used by methods.ts */
+    environment(extra: Record<string, string> | undefined): Record<string, string>;
 }
 export declare function compilePattern(pattern: string, ignoreCase: boolean): RegExp;

package/types/modules/shell/output/palette.d.ts

@@ -0,0 +1,2 @@
+export declare function paletteColor(index: number): string;
+export declare function rgbColor(value: number): string;

package/types/modules/shell/shell.d.ts

@@ -1,8 +1,9 @@
-import type { LogLine, Owner, ScreenResult, ShellInfo, ShellStatus } from "@opencode-cockpit/protocol/shell";
+import type { LogLine, Owner, ScreenResult, ShellInfo, ShellStatus, StopReason } from "@opencode-cockpit/protocol/shell";
 import { LineLog } from "./output/line-log.ts";
 import { RawRing } from "./output/raw-ring.ts";
 import { Screen } from "./output/screen.ts";
 import type { PtyBackend } from "./pty.ts";
+import type { WatchChange, Watcher } from "./watch/watcher.ts";
 export interface ShellSpec {
     id: string;
     command: string;
@@ -14,6 +15,9 @@ export interface ShellSpec {
     rows: number;
     owner: Owner;
     timeoutMs?: number;
+    idleTimeoutMs?: number;
+    /** Absolute path the clean log is appended to, when logging was requested. */
+    logFile?: string;
 }
 export interface ShellLimits {
     logChars: number;
@@ -42,6 +46,10 @@ export declare class Shell {
     /** First log line number belonging to the current run. */
     runStartLine: number;
     lastOutputAt: number;
+    /** Health rule attached to this shell, if any (see watch/watcher.ts). */
+    watcher: Watcher | undefined;
+    /** Called when the watcher's reported status changes; never per line. */
+    onWatchChange: ((change: WatchChange) => void) | undefined;
     private pty;
     private normalizer;
     private listeners;
@@ -49,9 +57,15 @@ export declare class Shell {
     private endedAt;
     private exit;
     private error;
+    /** Why the daemon stopped it, when it was not a user or agent request. */
+    private stoppedBecause;
+    private stopReason;
+    private stoppedBy;
     private summary;
     private stopRequested;
     private timeout;
+    private idleTimer;
+    private logWriter;
     private exitPromise;
     constructor(spec: ShellSpec, backend: PtyBackend, limits: ShellLimits);
     get id(): string;
@@ -64,8 +78,14 @@ export declare class Shell {
     start(): void;
     write(data: string): number;
     resize(cols: number, rows: number): void;
-    /** Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. */
-    stop(signal?: NodeJS.Signals, graceMs?: number): Promise<void>;
+    /**
+     * Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. `cause` says who
+     * asked, so an exit can be reported as a stop rather than as an unexplained kill.
+     */
+    stop(signal?: NodeJS.Signals, graceMs?: number, cause?: {
+        reason: StopReason;
+        by?: string;
+    }): Promise<void>;
     snapshot(): Promise<ScreenResult>;
     info(): ShellInfo;
     dispose(): void;

package/types/modules/shell/watch/presets.d.ts

@@ -0,0 +1,17 @@
+import type { WatchRule } from "@opencode-cockpit/protocol/shell";
+export interface Preset {
+    name: string;
+    /** Matched against the command line to pick a preset automatically. */
+    match?: string;
+    rule: WatchRule;
+}
+/**
+ * Watch rules for common tools, as data rather than parsers: `done` marks the end of a run, `fail`
+ * and `ok` say how it went. They are deliberately conservative — matching a tool's summary line,
+ * not its full output — and a caller can always pass its own rule instead. Adding a tool is a row
+ * here, and a wrong guess costs a status, never a crash.
+ */
+export declare const PRESETS: Preset[];
+export declare function presetByName(name: string): Preset | undefined;
+/** First preset whose `match` fits the command, e.g. `npm run dev` → nothing, `tsc --watch` → tsc. */
+export declare function presetForCommand(command: string): Preset | undefined;

package/types/modules/shell/watch/watcher.d.ts

@@ -0,0 +1,43 @@
+import type { WatchRule, WatchState, WatchStatus } from "@opencode-cockpit/protocol/shell";
+export interface CompiledRule {
+    done?: RegExp;
+    fail?: RegExp;
+    ok?: RegExp;
+    idleMs?: number;
+}
+export declare function compileRule(rule: WatchRule): CompiledRule;
+export interface WatchChange {
+    previous: WatchStatus;
+    current: WatchStatus;
+    summary?: string;
+}
+/**
+ * Tracks the health of one shell from its log.
+ *
+ * A run ends when `done` matches (or, without it, after `idleSeconds` of silence); the run's status
+ * is then `fail` if anything matched `fail`, `ok` if anything matched `ok`, and otherwise whatever
+ * it was. Only status changes are reported — a watcher that recompiles a thousand times says
+ * nothing until something actually breaks or gets fixed. A new failing line during an already
+ * failing run is reported too, since it is different news.
+ */
+export declare class Watcher {
+    private readonly rule;
+    private readonly preset?;
+    private status;
+    private summaryText;
+    private runs;
+    private since;
+    private sawFail;
+    private sawOk;
+    constructor(rule: CompiledRule, preset?: string | undefined);
+    get idleMs(): number | undefined;
+    state(): WatchState;
+    /** Feeds one committed log line. Returns a change when the reported status or failure changed. */
+    line(text: string, now?: number): WatchChange | undefined;
+    /** Ends the current run because output went quiet (rules without a `done` pattern). */
+    idle(now?: number): WatchChange | undefined;
+    /** The process ended: a watched program that stops is a failure unless it exited cleanly. */
+    exited(exitCode: number | undefined, signal: string | undefined, now?: number): WatchChange | undefined;
+    private settle;
+    private apply;
+}