minimal-agent 0.10.0 → 0.12.0

package/src/tools/tasks/backgroundTaskService.js

@@ -0,0 +1,275 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { closeSync, createWriteStream, existsSync, openSync, readSync, statSync, } from 'node:fs';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { killTree } from '../shared/killTree.js';
+import { pruneRuntimeOutputs, registerRuntimeOutput, sessionRuntimeDir, unregisterRuntimeOutput, } from '../../session/runtimeStore.js';
+export function createBackgroundTaskState() {
+    return { tasks: new Map() };
+}
+const fallbackState = createBackgroundTaskState();
+/** Contains only states that currently own at least one running child. */
+const liveStates = new Set();
+const TASK_ROOT = join(homedir(), '.minimal-agent', 'tasks');
+const MAX_LOG_BYTES = 512 * 1024 * 1024;
+const MAX_COMPLETED_PER_STATE = 50;
+const MAX_GLOBAL_LOGS = 500;
+const LOG_RETENTION_MS = 7 * 24 * 60 * 60_000;
+function safeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 80) || 'local';
+}
+export async function startBackgroundTask(spec, state = fallbackState) {
+    const sessionDir = join(sessionRuntimeDir(spec), 'outputs');
+    await mkdir(sessionDir, { recursive: true });
+    const id = `proc_${randomUUID()}`;
+    const logPath = join(sessionDir, `${id}.log`);
+    registerRuntimeOutput(logPath);
+    const log = createWriteStream(logPath, { flags: 'wx', encoding: 'utf8' });
+    const child = spec.executable
+        ? spawn(spec.executable, spec.args ?? [], {
+            cwd: spec.cwd,
+            env: spec.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        })
+        : spawn(spec.command, {
+            cwd: spec.cwd,
+            env: spec.env,
+            shell: spec.shell ?? true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        });
+    let settle;
+    const completion = new Promise((resolvePromise) => {
+        settle = resolvePromise;
+    });
+    const task = {
+        id,
+        command: spec.command,
+        cwd: spec.cwd,
+        logPath,
+        startedAt: Date.now(),
+        status: 'running',
+        child,
+        completion,
+        events: new EventEmitter(),
+        shell: spec.shellKind ?? 'bash',
+    };
+    state.tasks.set(id, task);
+    liveStates.add(state);
+    let written = 0;
+    let truncated = false;
+    const outputHash = createHash('sha256');
+    const writeChunk = (source, value) => {
+        if (written >= MAX_LOG_BYTES) {
+            if (!truncated) {
+                truncated = true;
+                log.write('\n[log truncated at 512 MiB; complete=false]\n');
+            }
+            return true;
+        }
+        const raw = Buffer.from(value);
+        const chunk = source === 'stderr'
+            ? Buffer.concat([Buffer.from('[stderr] '), raw])
+            : raw;
+        const remaining = MAX_LOG_BYTES - written;
+        const selected = chunk.subarray(0, remaining);
+        written += selected.length;
+        outputHash.update(selected);
+        const accepted = log.write(selected, () => task.events.emit('change'));
+        if (selected.length < chunk.length) {
+            truncated = true;
+            log.write('\n[log truncated at 512 MiB; complete=false]\n');
+        }
+        return accepted;
+    };
+    child.stdout?.on('data', (chunk) => {
+        if (!writeChunk('stdout', chunk)) {
+            child.stdout?.pause();
+            log.once('drain', () => child.stdout?.resume());
+        }
+    });
+    child.stderr?.on('data', (chunk) => {
+        if (!writeChunk('stderr', chunk)) {
+            child.stderr?.pause();
+            log.once('drain', () => child.stderr?.resume());
+        }
+    });
+    let finalized = false;
+    const finalize = (status, code, error) => {
+        if (finalized)
+            return;
+        finalized = true;
+        task.status = status;
+        task.finishedAt = Date.now();
+        task.exitCode = code;
+        task.child = undefined;
+        task.outputBytes = written;
+        task.outputSha256 = outputHash.digest('hex');
+        task.complete = !truncated;
+        log.end(error ? `[stderr] Failed to start: ${error}\n` : undefined, () => {
+            unregisterRuntimeOutput(logPath);
+            void pruneRuntimeOutputs();
+            task.events.emit('change');
+            settle();
+            pruneCompletedTasks(state);
+            if (![...state.tasks.values()].some((item) => item.status === 'running'))
+                liveStates.delete(state);
+        });
+    };
+    child.once('error', (error) => {
+        finalize('failed', null, error.message);
+    });
+    child.once('close', (code) => {
+        finalize(task.status === 'stopped'
+            ? 'stopped'
+            : code === 0
+                ? 'completed'
+                : 'failed', code);
+    });
+    void pruneTaskLogs();
+    return task;
+}
+export function getBackgroundTask(id, state = fallbackState) {
+    return (state.tasks.get(id) ??
+        state.tasks.get(id.startsWith('proc_') ? id.slice(5) : `proc_${id}`));
+}
+export function stopBackgroundTask(id, state = fallbackState) {
+    const task = getBackgroundTask(id, state);
+    if (!task)
+        return undefined;
+    if (task.status === 'running' && task.child) {
+        task.status = 'stopped';
+        task.finishedAt = Date.now();
+        killTree(task.child);
+    }
+    return task;
+}
+export function readTaskLog(task, offset = 0, limit = 30_000) {
+    if (!existsSync(task.logPath))
+        return { text: '', nextOffset: offset, totalBytes: 0 };
+    const totalBytes = statSync(task.logPath).size;
+    const start = Math.max(0, Math.min(offset, totalBytes));
+    const requestedLength = Math.max(0, Math.min(limit, totalBytes - start));
+    if (requestedLength === 0)
+        return { text: '', nextOffset: start, totalBytes };
+    // Up to three look-ahead bytes let a byte-based page finish the final UTF-8
+    // scalar instead of returning replacement characters or making no progress.
+    const readLength = Math.min(requestedLength + 3, totalBytes - start);
+    const bytes = Buffer.allocUnsafe(readLength);
+    const descriptor = openSync(task.logPath, 'r');
+    let bytesRead = 0;
+    try {
+        bytesRead = readSync(descriptor, bytes, 0, readLength, start);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    let pageLength = Math.min(requestedLength, bytesRead);
+    while (pageLength < bytesRead && (bytes[pageLength] & 0xc0) === 0x80)
+        pageLength += 1;
+    const validLength = completeUtf8PrefixLength(bytes.subarray(0, pageLength));
+    return {
+        text: bytes.subarray(0, validLength).toString('utf8'),
+        nextOffset: start + validLength,
+        totalBytes,
+    };
+}
+function completeUtf8PrefixLength(bytes) {
+    if (bytes.length === 0)
+        return 0;
+    let continuationBytes = 0;
+    let index = bytes.length - 1;
+    while (index >= 0 && (bytes[index] & 0xc0) === 0x80) {
+        continuationBytes += 1;
+        index -= 1;
+    }
+    if (index < 0)
+        return bytes.length;
+    const lead = bytes[index];
+    const expectedLength = lead >= 0xf0 && lead <= 0xf7
+        ? 4
+        : lead >= 0xe0 && lead <= 0xef
+            ? 3
+            : lead >= 0xc0 && lead <= 0xdf
+                ? 2
+                : 1;
+    return expectedLength > continuationBytes + 1 ? index : bytes.length;
+}
+export async function stopAllBackgroundTasks(state) {
+    const states = state ? [state] : [...liveStates];
+    const completions = [];
+    for (const item of states) {
+        for (const task of item.tasks.values()) {
+            if (task.status === 'running') {
+                stopBackgroundTask(task.id, item);
+                completions.push(task.completion);
+            }
+        }
+    }
+    if (completions.length > 0) {
+        await Promise.race([
+            Promise.allSettled(completions).then(() => undefined),
+            new Promise((resolvePromise) => setTimeout(resolvePromise, 5_000)),
+        ]);
+    }
+    for (const item of states)
+        liveStates.delete(item);
+}
+/** Release all process/task resources owned by a disposed host session. */
+export async function disposeBackgroundTaskState(state) {
+    await stopAllBackgroundTasks(state);
+    state.tasks.clear();
+    liveStates.delete(state);
+}
+function pruneCompletedTasks(state) {
+    const completed = [...state.tasks.values()]
+        .filter((task) => task.status !== 'running')
+        .sort((a, b) => (b.finishedAt ?? b.startedAt) - (a.finishedAt ?? a.startedAt));
+    for (const task of completed.slice(MAX_COMPLETED_PER_STATE)) {
+        state.tasks.delete(task.id);
+        task.events.removeAllListeners();
+    }
+}
+let prunePromise;
+async function pruneTaskLogsInner() {
+    try {
+        const sessions = await readdir(TASK_ROOT);
+        const files = [];
+        for (const session of sessions) {
+            const dir = join(TASK_ROOT, basename(session));
+            for (const name of await readdir(dir).catch(() => [])) {
+                const path = join(dir, basename(name));
+                const info = await stat(path).catch(() => undefined);
+                if (info?.isFile())
+                    files.push({ path, mtime: info.mtimeMs });
+            }
+        }
+        files.sort((a, b) => b.mtime - a.mtime);
+        const activeLogs = new Set([...liveStates].flatMap((state) => [...state.tasks.values()]
+            .filter((task) => task.status === 'running')
+            .map((task) => task.logPath)));
+        const completedFiles = files.filter((item) => !activeLogs.has(item.path));
+        const cutoff = Date.now() - LOG_RETENTION_MS;
+        await Promise.all(completedFiles
+            .filter((item, index) => index >= MAX_GLOBAL_LOGS || item.mtime < cutoff)
+            .map((item) => rm(item.path, { force: true })));
+    }
+    catch { }
+}
+function pruneTaskLogs() {
+    prunePromise ??= pruneTaskLogsInner().finally(() => {
+        prunePromise = undefined;
+    });
+    return prunePromise;
+}
+process.once('exit', () => {
+    for (const state of liveStates)
+        for (const task of state.tasks.values())
+            stopBackgroundTask(task.id, state);
+});

package/src/tools/tasks/backgroundTaskService.ts

@@ -0,0 +1,369 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import {
+  closeSync,
+  createWriteStream,
+  existsSync,
+  openSync,
+  readSync,
+  statSync,
+} from 'node:fs';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+import { killTree } from '../shared/killTree.js';
+import {
+  pruneRuntimeOutputs,
+  registerRuntimeOutput,
+  sessionRuntimeDir,
+  unregisterRuntimeOutput,
+} from '../../session/runtimeStore.js';
+
+export type BackgroundTaskStatus =
+  'running' | 'completed' | 'failed' | 'stopped';
+export interface BackgroundTask {
+  id: string;
+  command: string;
+  cwd: string;
+  logPath: string;
+  startedAt: number;
+  finishedAt?: number;
+  status: BackgroundTaskStatus;
+  exitCode?: number | null;
+  outputBytes?: number;
+  outputSha256?: string;
+  complete?: boolean;
+  child?: ChildProcess;
+  completion: Promise<void>;
+  events: EventEmitter;
+  shell: 'bash' | 'powershell';
+}
+export interface BackgroundTaskState {
+  tasks: Map<string, BackgroundTask>;
+}
+export function createBackgroundTaskState(): BackgroundTaskState {
+  return { tasks: new Map() };
+}
+
+const fallbackState = createBackgroundTaskState();
+/** Contains only states that currently own at least one running child. */
+const liveStates = new Set<BackgroundTaskState>();
+const TASK_ROOT = join(homedir(), '.minimal-agent', 'tasks');
+const MAX_LOG_BYTES = 512 * 1024 * 1024;
+const MAX_COMPLETED_PER_STATE = 50;
+const MAX_GLOBAL_LOGS = 500;
+const LOG_RETENTION_MS = 7 * 24 * 60 * 60_000;
+
+function safeSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 80) || 'local';
+}
+
+export interface BackgroundSpawnSpec {
+  command: string;
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  executable?: string;
+  args?: string[];
+  shell?: boolean;
+  sessionId?: string;
+  workspaceId?: string;
+  shellKind?: 'bash' | 'powershell';
+}
+
+export async function startBackgroundTask(
+  spec: BackgroundSpawnSpec,
+  state: BackgroundTaskState = fallbackState,
+): Promise<BackgroundTask> {
+  const sessionDir = join(sessionRuntimeDir(spec), 'outputs');
+  await mkdir(sessionDir, { recursive: true });
+  const id = `proc_${randomUUID()}`;
+  const logPath = join(sessionDir, `${id}.log`);
+  registerRuntimeOutput(logPath);
+  const log = createWriteStream(logPath, { flags: 'wx', encoding: 'utf8' });
+  const child = spec.executable
+    ? spawn(spec.executable, spec.args ?? [], {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+      })
+    : spawn(spec.command, {
+        cwd: spec.cwd,
+        env: spec.env,
+        shell: spec.shell ?? true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+      });
+
+  let settle!: () => void;
+  const completion = new Promise<void>((resolvePromise) => {
+    settle = resolvePromise;
+  });
+  const task: BackgroundTask = {
+    id,
+    command: spec.command,
+    cwd: spec.cwd,
+    logPath,
+    startedAt: Date.now(),
+    status: 'running',
+    child,
+    completion,
+    events: new EventEmitter(),
+    shell: spec.shellKind ?? 'bash',
+  };
+  state.tasks.set(id, task);
+  liveStates.add(state);
+
+  let written = 0;
+  let truncated = false;
+  const outputHash = createHash('sha256');
+  const writeChunk = (
+    source: 'stdout' | 'stderr',
+    value: Buffer | string,
+  ): boolean => {
+    if (written >= MAX_LOG_BYTES) {
+      if (!truncated) {
+        truncated = true;
+        log.write('\n[log truncated at 512 MiB; complete=false]\n');
+      }
+      return true;
+    }
+    const raw = Buffer.from(value);
+    const chunk =
+      source === 'stderr'
+        ? Buffer.concat([Buffer.from('[stderr] '), raw])
+        : raw;
+    const remaining = MAX_LOG_BYTES - written;
+    const selected = chunk.subarray(0, remaining);
+    written += selected.length;
+    outputHash.update(selected);
+    const accepted = log.write(selected, () => task.events.emit('change'));
+    if (selected.length < chunk.length) {
+      truncated = true;
+      log.write('\n[log truncated at 512 MiB; complete=false]\n');
+    }
+    return accepted;
+  };
+  child.stdout?.on('data', (chunk) => {
+    if (!writeChunk('stdout', chunk)) {
+      child.stdout?.pause();
+      log.once('drain', () => child.stdout?.resume());
+    }
+  });
+  child.stderr?.on('data', (chunk) => {
+    if (!writeChunk('stderr', chunk)) {
+      child.stderr?.pause();
+      log.once('drain', () => child.stderr?.resume());
+    }
+  });
+  let finalized = false;
+  const finalize = (
+    status: BackgroundTaskStatus,
+    code: number | null,
+    error?: string,
+  ) => {
+    if (finalized) return;
+    finalized = true;
+    task.status = status;
+    task.finishedAt = Date.now();
+    task.exitCode = code;
+    task.child = undefined;
+    task.outputBytes = written;
+    task.outputSha256 = outputHash.digest('hex');
+    task.complete = !truncated;
+    log.end(error ? `[stderr] Failed to start: ${error}\n` : undefined, () => {
+      unregisterRuntimeOutput(logPath);
+      void pruneRuntimeOutputs();
+      task.events.emit('change');
+      settle();
+      pruneCompletedTasks(state);
+      if (![...state.tasks.values()].some((item) => item.status === 'running'))
+        liveStates.delete(state);
+    });
+  };
+  child.once('error', (error) => {
+    finalize('failed', null, error.message);
+  });
+  child.once('close', (code) => {
+    finalize(
+      task.status === 'stopped'
+        ? 'stopped'
+        : code === 0
+          ? 'completed'
+          : 'failed',
+      code,
+    );
+  });
+  void pruneTaskLogs();
+  return task;
+}
+
+export function getBackgroundTask(
+  id: string,
+  state: BackgroundTaskState = fallbackState,
+): BackgroundTask | undefined {
+  return (
+    state.tasks.get(id) ??
+    state.tasks.get(id.startsWith('proc_') ? id.slice(5) : `proc_${id}`)
+  );
+}
+
+export function stopBackgroundTask(
+  id: string,
+  state: BackgroundTaskState = fallbackState,
+): BackgroundTask | undefined {
+  const task = getBackgroundTask(id, state);
+  if (!task) return undefined;
+  if (task.status === 'running' && task.child) {
+    task.status = 'stopped';
+    task.finishedAt = Date.now();
+    killTree(task.child);
+  }
+  return task;
+}
+
+export function readTaskLog(
+  task: BackgroundTask,
+  offset = 0,
+  limit = 30_000,
+): { text: string; nextOffset: number; totalBytes: number } {
+  if (!existsSync(task.logPath))
+    return { text: '', nextOffset: offset, totalBytes: 0 };
+  const totalBytes = statSync(task.logPath).size;
+  const start = Math.max(0, Math.min(offset, totalBytes));
+  const requestedLength = Math.max(0, Math.min(limit, totalBytes - start));
+  if (requestedLength === 0) return { text: '', nextOffset: start, totalBytes };
+  // Up to three look-ahead bytes let a byte-based page finish the final UTF-8
+  // scalar instead of returning replacement characters or making no progress.
+  const readLength = Math.min(requestedLength + 3, totalBytes - start);
+  const bytes = Buffer.allocUnsafe(readLength);
+  const descriptor = openSync(task.logPath, 'r');
+  let bytesRead = 0;
+  try {
+    bytesRead = readSync(descriptor, bytes, 0, readLength, start);
+  } finally {
+    closeSync(descriptor);
+  }
+  let pageLength = Math.min(requestedLength, bytesRead);
+  while (pageLength < bytesRead && (bytes[pageLength]! & 0xc0) === 0x80)
+    pageLength += 1;
+  const validLength = completeUtf8PrefixLength(bytes.subarray(0, pageLength));
+  return {
+    text: bytes.subarray(0, validLength).toString('utf8'),
+    nextOffset: start + validLength,
+    totalBytes,
+  };
+}
+
+function completeUtf8PrefixLength(bytes: Uint8Array): number {
+  if (bytes.length === 0) return 0;
+  let continuationBytes = 0;
+  let index = bytes.length - 1;
+  while (index >= 0 && (bytes[index]! & 0xc0) === 0x80) {
+    continuationBytes += 1;
+    index -= 1;
+  }
+  if (index < 0) return bytes.length;
+  const lead = bytes[index]!;
+  const expectedLength =
+    lead >= 0xf0 && lead <= 0xf7
+      ? 4
+      : lead >= 0xe0 && lead <= 0xef
+        ? 3
+        : lead >= 0xc0 && lead <= 0xdf
+          ? 2
+          : 1;
+  return expectedLength > continuationBytes + 1 ? index : bytes.length;
+}
+
+export async function stopAllBackgroundTasks(
+  state?: BackgroundTaskState,
+): Promise<void> {
+  const states = state ? [state] : [...liveStates];
+  const completions: Promise<void>[] = [];
+  for (const item of states) {
+    for (const task of item.tasks.values()) {
+      if (task.status === 'running') {
+        stopBackgroundTask(task.id, item);
+        completions.push(task.completion);
+      }
+    }
+  }
+  if (completions.length > 0) {
+    await Promise.race([
+      Promise.allSettled(completions).then(() => undefined),
+      new Promise<void>((resolvePromise) => setTimeout(resolvePromise, 5_000)),
+    ]);
+  }
+  for (const item of states) liveStates.delete(item);
+}
+
+/** Release all process/task resources owned by a disposed host session. */
+export async function disposeBackgroundTaskState(
+  state: BackgroundTaskState,
+): Promise<void> {
+  await stopAllBackgroundTasks(state);
+  state.tasks.clear();
+  liveStates.delete(state);
+}
+
+function pruneCompletedTasks(state: BackgroundTaskState): void {
+  const completed = [...state.tasks.values()]
+    .filter((task) => task.status !== 'running')
+    .sort(
+      (a, b) => (b.finishedAt ?? b.startedAt) - (a.finishedAt ?? a.startedAt),
+    );
+  for (const task of completed.slice(MAX_COMPLETED_PER_STATE)) {
+    state.tasks.delete(task.id);
+    task.events.removeAllListeners();
+  }
+}
+
+let prunePromise: Promise<void> | undefined;
+async function pruneTaskLogsInner(): Promise<void> {
+  try {
+    const sessions = await readdir(TASK_ROOT);
+    const files: Array<{ path: string; mtime: number }> = [];
+    for (const session of sessions) {
+      const dir = join(TASK_ROOT, basename(session));
+      for (const name of await readdir(dir).catch(() => [])) {
+        const path = join(dir, basename(name));
+        const info = await stat(path).catch(() => undefined);
+        if (info?.isFile()) files.push({ path, mtime: info.mtimeMs });
+      }
+    }
+    files.sort((a, b) => b.mtime - a.mtime);
+    const activeLogs = new Set(
+      [...liveStates].flatMap((state) =>
+        [...state.tasks.values()]
+          .filter((task) => task.status === 'running')
+          .map((task) => task.logPath),
+      ),
+    );
+    const completedFiles = files.filter((item) => !activeLogs.has(item.path));
+    const cutoff = Date.now() - LOG_RETENTION_MS;
+    await Promise.all(
+      completedFiles
+        .filter(
+          (item, index) => index >= MAX_GLOBAL_LOGS || item.mtime < cutoff,
+        )
+        .map((item) => rm(item.path, { force: true })),
+    );
+  } catch {}
+}
+
+function pruneTaskLogs(): Promise<void> {
+  prunePromise ??= pruneTaskLogsInner().finally(() => {
+    prunePromise = undefined;
+  });
+  return prunePromise;
+}
+
+process.once('exit', () => {
+  for (const state of liveStates)
+    for (const task of state.tasks.values()) stopBackgroundTask(task.id, state);
+});

package/src/tools/tasks/processEvidence.js

@@ -0,0 +1,24 @@
+/** Conservative command classification: false negatives are safer than claiming an unrun verification. */
+export function classifyProcessCommand(command) {
+    const normalized = command.trim();
+    if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?test(?:\s|$)|(?:^|[;&|]\s*)cargo\s+test(?:\s|$)/i.test(normalized))
+        return 'test';
+    if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?typecheck(?:\s|$)|(?:^|[;&|]\s*)(?:npx\s+)?tsc(?:\s|$)/i.test(normalized))
+        return 'typecheck';
+    if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?build(?:\s|$)|(?:^|[;&|]\s*)cargo\s+build(?:\s|$)/i.test(normalized))
+        return 'build';
+    if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?check(?:\s|$)|(?:^|[;&|]\s*)cargo\s+check(?:\s|$)/i.test(normalized))
+        return 'check';
+    return 'other';
+}
+export function processExecutionMetadata(input) {
+    return {
+        kind: 'process_execution',
+        shell: input.shell,
+        mode: input.mode,
+        commandKind: classifyProcessCommand(input.command),
+        status: input.status,
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        ...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+    };
+}

package/src/tools/tasks/processEvidence.ts

@@ -0,0 +1,34 @@
+import type {
+  ProcessCommandKind,
+  ProcessExecutionMetadata,
+  ProcessExecutionStatus,
+} from '../../types.js';
+
+/** Conservative command classification: false negatives are safer than claiming an unrun verification. */
+export function classifyProcessCommand(command: string): ProcessCommandKind {
+  const normalized = command.trim();
+  if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?test(?:\s|$)|(?:^|[;&|]\s*)cargo\s+test(?:\s|$)/i.test(normalized)) return 'test';
+  if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?typecheck(?:\s|$)|(?:^|[;&|]\s*)(?:npx\s+)?tsc(?:\s|$)/i.test(normalized)) return 'typecheck';
+  if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?build(?:\s|$)|(?:^|[;&|]\s*)cargo\s+build(?:\s|$)/i.test(normalized)) return 'build';
+  if (/(?:^|[;&|]\s*)(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?check(?:\s|$)|(?:^|[;&|]\s*)cargo\s+check(?:\s|$)/i.test(normalized)) return 'check';
+  return 'other';
+}
+
+export function processExecutionMetadata(input: {
+  shell: 'bash' | 'powershell';
+  mode: 'foreground' | 'background';
+  command: string;
+  status: ProcessExecutionStatus;
+  taskId?: string;
+  exitCode?: number | null;
+}): ProcessExecutionMetadata {
+  return {
+    kind: 'process_execution',
+    shell: input.shell,
+    mode: input.mode,
+    commandKind: classifyProcessCommand(input.command),
+    status: input.status,
+    ...(input.taskId ? { taskId: input.taskId } : {}),
+    ...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+  };
+}