@justjoshn/pi-pstack 0.15.36-pi.13 → 0.15.36-pi.15

package/src/index.ts

@@ -5,16 +5,17 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { aliasInputResult, aliasTable, packageSkillNames } from './aliases.ts';
 import { registerAskQuestion } from './ask.ts';
 import { aliasAutocomplete } from './autocomplete.ts';
+import { registerBackgroundShell } from './background-shell.ts';
 import { childIdentity } from './child-env.ts';
 import { registerGenerateImage } from './generate-image.ts';
 import { registerLoop } from './loop.ts';
 import { registerMode } from './mode.ts';
 import { canAsk, isOneShot } from './modes.ts';
-import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir } from './paths.ts';
+import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir, terminalsDir } from './paths.ts';
 import { registerPlanMode } from './plan.ts';
 import { registerReadonlyShell } from './readonly-shell.ts';
 import { migrateLegacyRule, modelsSection, readRule } from './rule.ts';
-import { alwaysAppliedRules, hostSection, subagentsSection } from './sections.ts';
+import { alwaysAppliedRules, hostSection, subagentsSection, todayText } from './sections.ts';
 import { registerSubscriptions } from './subscriptions/index.ts';
 import { type AgentDefinition, loadAgentDefinitions } from './task/agents.ts';
 import { registerAgentStatus } from './task/status.ts';
@@ -39,6 +40,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
   const activeTools = pi.getActiveTools();
   return {
     pstack_host: hostSection({
+      today: todayText(new Date()),
       packageRoot: PACKAGE_ROOT,
       skillsDir: SKILLS_DIR,
       skillNames: packageSkillNames(pi.getCommands()),
@@ -51,6 +53,7 @@ function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly
       rootStoreDir: rootStoreDir(ctx.cwd, ctx.sessionManager.getSessionId(), childIdentity.rootStore),
       projectsDir: projectsDir(ctx.cwd),
       artifactsDir: artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()),
+      terminalsDir: terminalsDir(ctx.cwd),
       loopAvailable: !isOneShot(ctx.mode),
       questionsAvailable: canAsk(ctx),
       activeTools,
@@ -122,7 +125,15 @@ export default function piPstack(pi: ExtensionAPI): void {
       return undefined;
     },
   });
-  const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
+  // A readonly agent's shell is the sandboxed one, and a background job would run outside that sandbox.
+  const shells = childIdentity.readonly
+    ? undefined
+    : registerBackgroundShell(pi, {
+        terminalsDir: (ctx) => terminalsDir(ctx.cwd),
+        waitsForJobs: (ctx) => childIdentity.depth === 0 && (ctx.mode === 'print' || ctx.mode === 'json'),
+        endsWithTurn: childIdentity.depth > 0,
+      });
+  const loop = registerLoop(pi, { hasPendingWork: () => task.hasBackgroundWork() || shells?.hasRunningJobs() === true });
   const todos = registerTodoWrite(pi, childIdentity.readonly ? {} : { onWrite: plan.syncTodos });
   registerAskQuestion(pi);
   if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);

package/src/linux-readonly-sandbox.ts

@@ -0,0 +1,121 @@
+// The Linux read-only sandbox: bubblewrap with every namespace unshared, the whole filesystem bound read-only, and a
+// seccomp filter that refuses Unix sockets. bubblewrap installs the filter itself, so this needs no nested user
+// namespace, which hosts with kernel.apparmor_restrict_unprivileged_userns=1 (Ubuntu 24.04 and later) refuse.
+import { spawnSync } from 'node:child_process';
+import { accessSync, closeSync, constants, existsSync, mkdtempSync, openSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+const LD_ABS_W = 0x20;
+const JEQ_K = 0x15;
+const JGE_K = 0x35;
+const RET_K = 0x06;
+const SECCOMP_RET_ALLOW = 0x7fff_0000;
+const SECCOMP_RET_ERRNO_EPERM = 0x0005_0001;
+const SECCOMP_RET_KILL_PROCESS = 0x8000_0000;
+const X32_SYSCALL_BIT = 0x4000_0000;
+const AF_UNIX = 1;
+
+const ARCHES: Record<string, { audit: number; socket: number; ioUringSetup: number }> = {
+  x64: { audit: 0xc000_003e, socket: 41, ioUringSetup: 425 },
+  arm64: { audit: 0xc000_00b7, socket: 198, ioUringSetup: 425 },
+};
+
+const instruction = (code: number, jt: number, jf: number, k: number): Buffer => {
+  const bytes = Buffer.alloc(8);
+  bytes.writeUInt16LE(code, 0);
+  bytes.writeUInt8(jt, 2);
+  bytes.writeUInt8(jf, 3);
+  bytes.writeUInt32LE(k >>> 0, 4);
+  return bytes;
+};
+
+/**
+ * A classic BPF seccomp program: socket(AF_UNIX, ...) and io_uring_setup fail with EPERM, any other architecture or
+ * the x32 ABI kills the process, and everything else is allowed. Jumps are relative to the next instruction.
+ */
+export function seccompFilter(arch: string): Buffer {
+  const target = ARCHES[arch];
+  if (target === undefined) throw new Error(`the read-only shell has no seccomp filter for ${arch}`);
+  return Buffer.concat([
+    instruction(LD_ABS_W, 0, 0, 4), // 0: architecture
+    instruction(JEQ_K, 0, 8, target.audit), // 1: native → 2, otherwise → 10
+    instruction(LD_ABS_W, 0, 0, 0), // 2: syscall number
+    instruction(JGE_K, 6, 0, X32_SYSCALL_BIT), // 3: x32 → 10
+    instruction(JEQ_K, 0, 2, target.socket), // 4: socket → 5, otherwise → 7
+    instruction(LD_ABS_W, 0, 0, 16), // 5: low word of the first argument, the domain
+    instruction(JEQ_K, 2, 1, AF_UNIX), // 6: AF_UNIX → 9, otherwise → 8
+    instruction(JEQ_K, 1, 0, target.ioUringSetup), // 7: io_uring_setup → 9, otherwise → 8
+    instruction(RET_K, 0, 0, SECCOMP_RET_ALLOW), // 8
+    instruction(RET_K, 0, 0, SECCOMP_RET_ERRNO_EPERM), // 9
+    instruction(RET_K, 0, 0, SECCOMP_RET_KILL_PROCESS), // 10
+  ]);
+}
+
+const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+
+/** bubblewrap's arguments before the command: nothing is writable and nothing outside is reachable. */
+export function bwrapArgs(cwd: string): string[] {
+  return ['--new-session', '--die-with-parent', '--unshare-all', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--cap-drop', 'ALL', '--chdir', cwd, '--seccomp', '3'];
+}
+
+interface Sandbox {
+  bwrap: string;
+  filterPath: string;
+  shell: string;
+}
+
+/** The first executable `name` on PATH, so every command runs the bubblewrap the check ran. */
+function onPath(name: string): string | undefined {
+  for (const dir of (process.env['PATH'] ?? '').split(delimiter).filter((entry) => entry !== '')) {
+    const candidate = join(dir, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Not here; keep looking.
+    }
+  }
+  return undefined;
+}
+
+let verified: { sandbox: Sandbox } | { error: Error } | undefined;
+
+/** The checked sandbox, or the error that stopped it; either is kept, so a failed host never retries into a weaker state. */
+function verifiedSandbox(): Sandbox {
+  verified ??= (() => {
+    try {
+      return { sandbox: checkSandbox() };
+    } catch (error) {
+      return { error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  })();
+  if ('error' in verified) throw verified.error;
+  return verified.sandbox;
+}
+
+/** Writes the filter into a private directory and checks that bubblewrap can load it here. */
+function checkSandbox(): Sandbox {
+  const filter = seccompFilter(process.arch);
+  const bwrap = onPath('bwrap');
+  if (bwrap === undefined) throw new Error('bubblewrap (bwrap) is not available: no bwrap on PATH');
+  const dir = mkdtempSync(join(tmpdir(), 'pi-pstack-ro-'));
+  const filterPath = join(dir, 'unix-block.bpf');
+  writeFileSync(filterPath, filter, { mode: 0o400 });
+  const shell = existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh';
+  const fd = openSync(filterPath, 'r');
+  try {
+    const probe = spawnSync(bwrap, [...bwrapArgs('/'), '--', shell, '-c', 'exit 0'], { stdio: ['ignore', 'ignore', 'pipe', fd], encoding: 'utf8', timeout: 15_000 });
+    if (probe.error !== undefined) throw new Error(`bubblewrap (bwrap) could not run: ${probe.error.message}`);
+    if (probe.status !== 0) throw new Error(`bubblewrap could not start the read-only sandbox: ${probe.stderr.trim() || `exit ${probe.status}`}`);
+  } finally {
+    closeSync(fd);
+  }
+  return { bwrap, filterPath, shell };
+}
+
+/** The shell command that runs `command` inside the read-only sandbox, or an error when no sandbox can start. */
+export function linuxReadonlyCommand(command: string, cwd: string): string {
+  const { bwrap, filterPath, shell } = verifiedSandbox();
+  return `exec ${quote(bwrap)} ${bwrapArgs(cwd).map(quote).join(' ')} -- ${quote(shell)} -c ${quote(command)} 3< ${quote(filterPath)}`;
+}

package/src/loop.ts

@@ -258,7 +258,7 @@ function registerLoopTool(pi: ExtensionAPI, registry: LoopRegistry): void {
     name: 'Loop',
     label: 'Loop',
     description:
-      '/loop for you: start an independent loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule its next wake, or stop it once its goal is met. Use it when a playbook says to arm /loop. Each result names the loop ID. With several loops running, pass loop_id to wake or stop the intended loop.',
+      '/loop for you: start an independent loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule its next wake, or stop it once its goal is met. Use it when a playbook says to arm /loop. Run the prompt once yourself in the turn that arms the loop; the first scheduled run comes after the interval or wake_in. Then confirm the interval, that the prompt already ran once, and when the first run comes. Each result names the loop ID. With several loops running, pass loop_id to wake or stop the intended loop.',
     promptSnippet: 'Start a /loop, schedule its next wake, or stop it',
     parameters: LoopParams,
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },

package/src/paths.ts

@@ -75,6 +75,11 @@ export function artifactsDir(cwd: string, sessionId: string): string {
   return join(workspaceStateDir(cwd), 'artifacts', sessionId);
 }
 
+/** Background shell jobs' output files, `<shell id>.txt`, as Cursor keeps them in a workspace's terminals folder. */
+export function terminalsDir(cwd: string): string {
+  return join(workspaceStateDir(cwd), 'terminals');
+}
+
 export function worktreesDir(cwd: string): string {
   return join(workspaceStateDir(cwd), 'worktrees');
 }

package/src/readonly-shell.ts

@@ -2,12 +2,14 @@ import { existsSync } from 'node:fs';
 
 import type { SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
 import { type BashSpawnContext, createBashTool, type ExtensionAPI, type ExtensionToolContext, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { linuxReadonlyCommand } from './linux-readonly-sandbox.ts';
 
 // Cursor's readonly subagent: "no file edits, no state-changing shell commands". The OS sandbox enforces it:
 // nothing may be written and no host may be reached, so a pipe, substitution, or pager cannot get around it.
+// Linux uses bubblewrap directly (linux-readonly-sandbox.ts); macOS uses sandbox-runtime's Seatbelt policy below.
 // denyWrite names the paths the sandbox makes writable for itself (/tmp/claude is a dependency default), and
 // denyRead drops the dependency's writable home defaults (~/.npm/_logs, ~/.claude/debug). Seatbelt is
-// last-match-wins with deny emitted after allow; on Linux bubblewrap binds deny last the same way.
+// last-match-wins with deny emitted after allow.
 // Unix sockets must stay blocked too: a host service can mutate files on a command's behalf.
 const READ_ONLY_POLICY: SandboxRuntimeConfig = {
   network: { allowedDomains: [], deniedDomains: [], allowAllUnixSockets: false },
@@ -29,7 +31,7 @@ type Sandbox = typeof import('@anthropic-ai/sandbox-runtime')['SandboxManager'];
 let ready: Promise<Sandbox> | undefined;
 
 /**
- * Starts the sandbox once per process, loading it only in a readonly subagent: a local package install gets no
+ * Starts sandbox-runtime once per process, loading it only in a readonly subagent: a local package install gets no
  * dependency install, and everything else in the package works without it. A failure is kept, so no command ever
  * runs outside the sandbox.
  */
@@ -73,11 +75,7 @@ export function createReadonlyBashTool(name = 'bash'): ToolDefinition<BashParame
     description: `${base.description}${NOTE}`,
     async execute(toolCallId, params, signal, onUpdate, ctx: ExtensionToolContext) {
       // Fail closed: when the sandbox cannot start, the call fails here and nothing spawns.
-      const sandbox = await sandboxReady();
-      // The per-command policy re-states READ_ONLY_POLICY, so the command never inherits a policy another
-      // consumer left on the shared manager. Wrapping honors abort, and Pi's own shell operations then enforce
-      // the pre-spawn abort check, timeouts, and process-tree cleanup.
-      const command = await sandbox.wrapWithSandbox(params.command, undefined, READ_ONLY_POLICY, signal);
+      const command = process.platform === 'linux' ? linuxCommand(params.command, ctx.cwd) : await wrapped(params.command, signal);
       const bash = createBashTool(ctx.cwd, {
         ...(existsSync('/bin/bash') ? { shellPath: '/bin/bash' } : {}),
         spawnHook: (spawn: BashSpawnContext) => ({ ...spawn, command, env: strippedEnv(spawn.env) }),
@@ -87,10 +85,25 @@ export function createReadonlyBashTool(name = 'bash'): ToolDefinition<BashParame
   };
 }
 
+function linuxCommand(command: string, cwd: string): string {
+  try {
+    return linuxReadonlyCommand(command, cwd);
+  } catch (error) {
+    throw new Error(`no verified OS sandbox is available: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 /**
- * Releases the sandbox if it started. On Linux the sandbox's socat bridges keep the event loop alive, so a process
- * that used the shell never exits unless the sandbox is released.
+ * The per-command policy re-states READ_ONLY_POLICY, so the command never inherits a policy another consumer left on
+ * the shared manager. Wrapping honors abort, and Pi's own shell operations then enforce the pre-spawn abort check,
+ * timeouts, and process-tree cleanup.
  */
+async function wrapped(command: string, signal: AbortSignal | undefined): Promise<string> {
+  const sandbox = await sandboxReady();
+  return sandbox.wrapWithSandbox(command, undefined, READ_ONLY_POLICY, signal);
+}
+
+/** Releases sandbox-runtime if it started, so a process that used the shell can exit. */
 export async function releaseReadonlySandbox(): Promise<void> {
   const started = ready;
   ready = undefined;

package/src/sections.ts

@@ -6,6 +6,8 @@ import type { AgentDefinition } from './task/agents.ts';
 import { type AvailableModel, type ModelSpec, modelLabel } from './task/models.ts';
 
 export interface HostFacts {
+  /** Today's date as Cursor states it in its user info, such as "Wednesday Nov 4, 2026". */
+  today: string;
   packageRoot: string;
   skillsDir: string;
   skillNames: readonly string[];
@@ -18,6 +20,8 @@ export interface HostFacts {
   rootStoreDir: string;
   projectsDir: string;
   artifactsDir: string;
+  /** Background shell jobs' output files. */
+  terminalsDir: string;
   /** False in print and JSON runs, including subagents, which exit when they settle. */
   loopAvailable: boolean;
   /** False when nobody can answer a dialog (print and JSON runs, including subagents). */
@@ -29,7 +33,9 @@ export interface HostFacts {
 }
 
 const LOOP_LINE =
-  '- /loop: the user starts `/loop [interval] <prompt>`. When a playbook says to arm /loop, call the Loop tool with prompt plus interval (fixed cadence) or wake_in (agent-paced). Inside a loop, Loop with wake_in schedules the next run and stop: true ends it.';
+  '- /loop: the user starts `/loop [interval] <prompt>`. When a playbook says to arm /loop, run the prompt once now, in this turn, then call the Loop tool with prompt plus interval (fixed cadence) or wake_in (agent-paced); its first scheduled run comes after that interval or wake. Inside a loop, Loop with wake_in schedules the next run and stop: true ends it.';
+const EVENT_LOOP_SENTENCE =
+  " When the next run waits on an event (CI finishing, a ref advancing, a log line), start a watcher with bash_background that exits, or prints a line its notify_on_output pattern matches, when the event fires, and keep a long wake_in as the fallback heartbeat: the watcher's notification wakes you.";
 const NO_LOOP_LINE =
   '- /loop: this run ends when it settles (a subagent, or a print or JSON run), so it has no Loop tool and cannot arm a loop. Keep working until the goal is met, and name in the final reply anything the parent chat should loop on.';
 
@@ -52,6 +58,14 @@ export function alwaysAppliedRules(skillsDir: string): string[] {
   return bodies;
 }
 
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** The local date in Cursor's user-info form: weekday, short month, day, year. */
+export function todayText(date: Date): string {
+  return `${WEEKDAYS[date.getDay()]} ${MONTHS[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
+}
+
 const TASK_PARAMS = 'description, prompt, subagent_type, model, readonly, run_in_background, resume, fork, fork_turns, environment, cloud_base_branch, file_attachments';
 
 function todoLine(facts: HostFacts): string {
@@ -79,7 +93,7 @@ function agentToolsLine(tools: readonly string[]): string[] {
 export function hostSection(facts: HostFacts): string {
   const transcript = facts.sessionFile === undefined ? 'This chat is not persisted (--no-session), so it has no transcript file.' : `This chat's transcript is ${facts.sessionFile}.`;
   return [
-    `pstack runs here through the pi-pstack package at ${facts.packageRoot}.`,
+    `pstack runs here through the pi-pstack package at ${facts.packageRoot}. Today's date: ${facts.today}.`,
     `- <SKILLS> = ${facts.skillsDir}. "the X skill", "/X", and "principle-X" mean <SKILLS>/X/SKILL.md, even for skills hidden from automatic invocation; a delegate that needs poteto-mode reads <SKILLS>/poteto-mode/SKILL.md. Installed skills (${facts.skillNames.length}): ${facts.skillNames.join(', ')}.`,
     '- A <skill> block in a user message means the user attached that skill to this request. Follow its workflow from its first step, including the steps it says to take before answering, instead of answering directly.',
     `- Skill folders: project \`.pi/skills/\`, personal \`${join(facts.agentDir, 'skills')}/\`.`,
@@ -95,7 +109,12 @@ export function hostSection(facts: HostFacts): string {
     `- Files a tool makes for the user, such as visualize charts, go in ${facts.artifactsDir}.`,
     facts.loopAvailable ? SUBSCRIPTIONS_LINE : NO_SUBSCRIPTIONS_LINE,
     ...agentToolsLine(facts.activeTools),
-    facts.loopAvailable ? LOOP_LINE : NO_LOOP_LINE,
+    facts.loopAvailable ? `${LOOP_LINE}${facts.activeTools.includes('bash_background') ? EVENT_LOOP_SENTENCE : ''}` : NO_LOOP_LINE,
+    ...(facts.activeTools.includes('bash_background')
+      ? [
+          `- Background shells: bash_background runs a command in the background, or moves it there after block_until_ms, and writes its output to ${facts.terminalsDir}/<shell id>.txt. The first lines of that file hold pid, cwd, command, title, status, and running_for_ms (\`head -n 10 *.txt\` there lists every job), and a footer with exit_code appears when the command ends. A notification wakes you after your turn when a job finishes and on each notify_on_output match; AwaitShell polls or waits. Stop a job with \`kill <pid>\`. bash waits for its command to finish and never moves it to the background, so start anything that can run for minutes (a watcher, a polling script such as watch-pr without --status-only, a dev server) with bash_background.`,
+        ]
+      : []),
     facts.activeTools.includes('GenerateImage')
       ? '- Image generation: the GenerateImage tool, which saves each image to the artifacts folder below and shows it in its result.'
       : '- Image generation: no image model is configured, so this session has no GenerateImage tool. Say so and use a mermaid diagram or a table instead.',

package/src/shell-output-watch.ts

@@ -0,0 +1,126 @@
+import { createRequire } from 'node:module';
+
+import type { RE2JS } from 're2js';
+
+const require = createRequire(import.meta.url);
+let regexEngine: typeof RE2JS | undefined;
+try {
+  regexEngine = (require('re2js') as { RE2JS: typeof RE2JS }).RE2JS;
+} catch {}
+
+export class OutputWatchDependencyError extends Error {}
+
+export interface OutputWatchRequest {
+  pattern: string;
+  reason: string;
+  debounceMs?: number;
+}
+
+export interface OutputMatchNotice {
+  sequence: number;
+  title: string;
+  detail: string;
+}
+
+interface MatchBatch {
+  start: number;
+  count: number;
+  matchedText: string;
+}
+
+const MATCH_LIMIT = 100;
+const MAX_CHUNK = 65_536;
+const MIN_DEBOUNCE_MS = 5_000;
+
+export class ShellOutputWatch {
+  private readonly request: OutputWatchRequest;
+  private readonly notify: (notice: OutputMatchNotice) => void;
+  private readonly regex: RE2JS;
+  private readonly title: string;
+  private readonly debounceMs: number;
+  private state: 'watching' | 'limited' | 'finished' = 'watching';
+  private carryover = '';
+  private occurrences = 0;
+  private notices = 0;
+  private batch: MatchBatch | undefined;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(request: OutputWatchRequest, notify: (notice: OutputMatchNotice) => void) {
+    this.request = request;
+    this.notify = notify;
+    if (request.pattern.length > 500) throw new Error('Output notification pattern exceeds 500 characters');
+    if (regexEngine === undefined) throw new OutputWatchDependencyError('Shell output monitoring needs the re2js dependency. Run bun install in the pi-pstack package directory, then reload Pi.');
+    this.regex = regexEngine.compile(request.pattern, regexEngine.MULTILINE);
+    const title = request.reason.trim() || `Shell output contains /${request.pattern}/`;
+    this.title = title.length <= 500 ? title : `${title.slice(0, 500)}...`;
+    this.debounceMs = Math.max(request.debounceMs ?? MIN_DEBOUNCE_MS, MIN_DEBOUNCE_MS);
+  }
+
+  observe(chunk: string): void {
+    if (this.state !== 'watching' || chunk.length === 0) return;
+    for (let offset = 0; offset < chunk.length && this.state === 'watching'; offset += MAX_CHUNK) {
+      const previous = this.carryover.length;
+      const text = this.carryover + chunk.slice(offset, offset + MAX_CHUNK);
+      const matcher = this.regex.matcher(text);
+      while (this.state === 'watching' && matcher.find()) {
+        if (matcher.end() > previous) this.match(matcher.group() ?? '');
+      }
+      this.carryover = text.slice(-1_024);
+    }
+  }
+
+  finish(announce = true): void {
+    if (this.state === 'finished') return;
+    this.state = 'finished';
+    if (announce) this.flush();
+    this.batch = undefined;
+    this.clearTimer();
+  }
+
+  private match(text: string): void {
+    this.occurrences += 1;
+    const label = this.occurrences === 1 ? 'Matched text' : 'Latest match';
+    const matchedText = text.length <= 5_000 ? `${label}: ${text}` : `${label} is ${text.length} characters; omitted from notification detail.`;
+    if (this.occurrences === 1) {
+      this.emit({ start: 1, count: 1, matchedText });
+    } else {
+      this.batch = this.batch === undefined ? { start: this.occurrences, count: 1, matchedText } : { start: this.batch.start, count: this.batch.count + 1, matchedText };
+      if (this.occurrences < MATCH_LIMIT && this.timer === undefined) {
+        this.timer = setTimeout(() => this.flush(), this.debounceMs);
+        this.timer.unref();
+      }
+    }
+    if (this.occurrences === MATCH_LIMIT) {
+      this.state = 'limited';
+      this.flush();
+      this.notices += 1;
+      this.notify({
+        sequence: this.notices,
+        title: `Notification limit reached (${MATCH_LIMIT})`,
+        detail: `Shell output matched /${this.request.pattern}/ ${MATCH_LIMIT} times and has reached the notification limit. No further notifications will be sent for this pattern. To continue monitoring, read the output file directly at the output path.`,
+      });
+    }
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+
+  private flush(): void {
+    const batch = this.batch;
+    this.batch = undefined;
+    this.clearTimer();
+    if (batch !== undefined) this.emit(batch);
+  }
+
+  private emit(batch: MatchBatch): void {
+    this.notices += 1;
+    const pattern = this.request.pattern;
+    const detail =
+      batch.count === 1
+        ? `Shell output has pattern /${pattern}/. This is occurrence number ${batch.start}. ${batch.matchedText}. The title message is being displayed to the user.`
+        : `Shell output matched /${pattern}/ ${batch.count} more times since the previous notification. The title message is being displayed to the user. ${batch.matchedText}.`;
+    this.notify({ sequence: this.notices, title: this.title, detail });
+  }
+}