pi-better-background-tasks 0.2.20 → 0.3.0

package/src/process.ts

@@ -183,14 +183,15 @@ export function runCommandOnce(
   validateCommandSpec(spec);
   const startedAt = Date.now();
   const child = spawnArgs(spec, true, ["ignore", "pipe", "pipe"]);
-  let stdout = "";
-  let stderr = "";
+  const cap = Math.max(1, Math.floor(maxBufferBytes));
+  const stdoutCapture = createCaptureBuffer();
+  const stderrCapture = createCaptureBuffer();
   let timedOut = false;
-  child.stdout?.on("data", (chunk: Buffer) => {
-    if (Buffer.byteLength(stdout) < maxBufferBytes) stdout += chunk.toString("utf8");
+  child.stdout?.on("data", (chunk: Buffer | string) => {
+    captureChunk(stdoutCapture, chunk, cap);
   });
-  child.stderr?.on("data", (chunk: Buffer) => {
-    if (Buffer.byteLength(stderr) < maxBufferBytes) stderr += chunk.toString("utf8");
+  child.stderr?.on("data", (chunk: Buffer | string) => {
+    captureChunk(stderrCapture, chunk, cap);
   });
   return new Promise((resolve, reject) => {
     // The group outlives the leader as long as any member is alive, so the
@@ -239,19 +240,105 @@ export function runCommandOnce(
     });
     child.on("close", (exitCode, signal) => {
       settle();
+      const stdout = finishCapture(stdoutCapture);
+      const stderr = finishCapture(stderrCapture);
+      const captureTruncated = stdout.discardedBytes > 0 || stderr.discardedBytes > 0;
       resolve({
         exitCode,
         signal,
-        stdout,
-        stderr,
+        stdout: stdout.text,
+        stderr: stderr.text,
         startedAt,
         endedAt: Date.now(),
         ...(timedOut ? { timedOut: true } : {}),
+        ...(stdout.discardedBytes > 0 ? { stdoutDiscardedBytes: stdout.discardedBytes } : {}),
+        ...(stderr.discardedBytes > 0 ? { stderrDiscardedBytes: stderr.discardedBytes } : {}),
+        ...(captureTruncated ? { captureTruncated: true } : {}),
       });
     });
   });
 }
 
+interface CaptureBuffer {
+  chunks: Buffer[];
+  storedBytes: number;
+  discardedBytes: number;
+  truncated: boolean;
+}
+
+function createCaptureBuffer(): CaptureBuffer {
+  return { chunks: [], storedBytes: 0, discardedBytes: 0, truncated: false };
+}
+
+function asBuffer(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+}
+
+/** Largest UTF-8 prefix of `buffer` that fits in `maxBytes`. */
+export function utf8PrefixLength(buffer: Buffer, maxBytes: number): number {
+  if (maxBytes <= 0) return 0;
+  if (buffer.length <= maxBytes) return buffer.length;
+  let end = maxBytes;
+  while (end > 0 && (buffer[end]! & 0xc0) === 0x80) end -= 1;
+  if (end === 0 && (buffer[0]! & 0xc0) === 0x80) return 0;
+  const lead = buffer[end]!;
+  const need = lead <= 0x7f ? 1
+    : (lead & 0xe0) === 0xc0 ? 2
+    : (lead & 0xf0) === 0xe0 ? 3
+    : (lead & 0xf8) === 0xf0 ? 4
+    : 1;
+  return end + need <= maxBytes ? end + need : end;
+}
+
+function captureChunk(target: CaptureBuffer, chunk: Buffer | string, maxBytes: number): void {
+  const buffer = asBuffer(chunk);
+  if (target.truncated) {
+    target.discardedBytes += buffer.length;
+    return;
+  }
+  const room = maxBytes - target.storedBytes;
+  if (buffer.length <= room) {
+    target.chunks.push(buffer);
+    target.storedBytes += buffer.length;
+    return;
+  }
+  const take = utf8PrefixLength(buffer, room);
+  if (take > 0) {
+    target.chunks.push(buffer.subarray(0, take));
+    target.storedBytes += take;
+  }
+  target.discardedBytes += buffer.length - take;
+  target.truncated = true;
+}
+
+/**
+ * Length of `buffer` without a trailing UTF-8 sequence that the cap cut short.
+ * Chunk boundaries can split a code point; once capture overflows, the bytes
+ * that would have completed it were discarded, so the dangling lead bytes are
+ * discarded too instead of decoding to U+FFFD.
+ */
+export function completeUtf8Length(buffer: Buffer): number {
+  let start = buffer.length - 1;
+  while (start >= 0 && buffer.length - start < 4 && (buffer[start]! & 0xc0) === 0x80) start -= 1;
+  if (start < 0) return buffer.length;
+  const lead = buffer[start]!;
+  const need = lead <= 0x7f ? 1
+    : (lead & 0xe0) === 0xc0 ? 2
+    : (lead & 0xf0) === 0xe0 ? 3
+    : (lead & 0xf8) === 0xf0 ? 4
+    : 1;
+  return start + need > buffer.length ? start : buffer.length;
+}
+
+function finishCapture(target: CaptureBuffer): { text: string; discardedBytes: number } {
+  const stored = Buffer.concat(target.chunks, target.storedBytes);
+  const keep = target.truncated ? completeUtf8Length(stored) : stored.length;
+  return {
+    text: stored.subarray(0, keep).toString("utf8"),
+    discardedBytes: target.discardedBytes + (stored.length - keep),
+  };
+}
+
 /**
  * Stop a task's process tree.
  *

package/src/registry.ts

@@ -92,15 +92,92 @@ export function onMetaChanged(listener: () => void): () => void {
 }
 
 export function readMeta(id: string): BackgroundTaskMeta | undefined {
+  return inspectMeta(id).meta;
+}
+
+export interface MetaInspection {
+  id: string;
+  meta?: BackgroundTaskMeta;
+  found: boolean;
+  readable: boolean;
+  error?: string;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Parsed JSON that lacks the identifying fields is corrupt, not a task. */
+function metaShapeProblem(meta: unknown, id: string): string | undefined {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return "not an object";
+  const value = meta as Partial<BackgroundTaskMeta>;
+  if (value.id !== id) return `id ${JSON.stringify(value.id ?? null)} does not match ${JSON.stringify(id)}`;
+  if (typeof value.status !== "string" || !value.status) return "missing status";
+  if (typeof value.logPath !== "string" || !value.logPath) return "missing logPath";
+  if (typeof value.startedAt !== "number" || !Number.isFinite(value.startedAt)) return "missing startedAt";
+  return undefined;
+}
+
+/**
+ * Distinguish missing, unreadable, and healthy metadata. Callers must not treat
+ * an unreadable file as proof that a task does not exist.
+ */
+export function inspectMeta(id: string): MetaInspection {
+  const path = metaPathFor(id);
   try {
     registryIo.metadataFileReads += 1;
-    const meta = JSON.parse(readFileSync(metaPathFor(id), "utf8")) as BackgroundTaskMeta;
-    metaCache.set(id, meta);
-    return meta;
-  } catch {
+    const raw = readFileSync(path, "utf8");
+    try {
+      const meta = JSON.parse(raw) as BackgroundTaskMeta;
+      const invalid = metaShapeProblem(meta, id);
+      if (invalid) {
+        metaCache.delete(id);
+        return { id, found: true, readable: false, error: `invalid metadata: ${invalid}` };
+      }
+      metaCache.set(id, meta);
+      return { id, meta, found: true, readable: true };
+    } catch (error) {
+      metaCache.delete(id);
+      return { id, found: true, readable: false, error: `invalid JSON: ${errorText(error)}` };
+    }
+  } catch (error) {
     metaCache.delete(id);
-    return undefined;
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      try {
+        statSync(taskDir(id));
+        return { id, found: true, readable: false, error: "metadata file is missing" };
+      } catch {
+        return { id, found: false, readable: false };
+      }
+    }
+    return { id, found: true, readable: false, error: errorText(error) };
+  }
+}
+
+export interface TaskIndex {
+  records: MetaInspection[];
+  indexError?: string;
+}
+
+/** List every task directory, including unreadable metadata. */
+export function listTaskRecords(): TaskIndex {
+  let ids: string[];
+  try {
+    registryIo.fullDirectoryReads += 1;
+    ids = readdirSync(tasksDir());
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { records: [] };
+    return { records: [], indexError: errorText(error) };
   }
+  return {
+    records: ids.map((id) => inspectMeta(id)).sort((a, b) => {
+      const aTime = a.meta?.startedAt ?? 0;
+      const bTime = b.meta?.startedAt ?? 0;
+      return bTime - aTime;
+    }),
+  };
 }
 
 export function removeMeta(meta: BackgroundTaskMeta): boolean {
@@ -164,11 +241,11 @@ function readOwnedMeta(id: string): BackgroundTaskMeta | undefined {
   return metaCache.get(id) ?? readMeta(id);
 }
 
-function originOf(meta: BackgroundTaskMeta): BackgroundTaskCallbackOrigin {
+export function originOf(meta: BackgroundTaskMeta): BackgroundTaskCallbackOrigin {
   return meta.callbackOrigin ?? { cwd: meta.cwd };
 }
 
-function belongsToOrigin(meta: BackgroundTaskMeta, origin: BackgroundTaskCallbackOrigin): boolean {
+export function belongsToOrigin(meta: BackgroundTaskMeta, origin: BackgroundTaskCallbackOrigin): boolean {
   const candidate = originOf(meta);
   if (candidate.cwd !== origin.cwd) return false;
   if (candidate.sessionId || origin.sessionId) return candidate.sessionId === origin.sessionId;

package/src/runtime.ts

@@ -11,6 +11,7 @@ import { confineCommandSpec, resolveForegroundSandboxPlan } from "./sandbox.js";
 import { failurePath, recordFailure, recoverFailure, scheduleFailureAttention, stopFailureAttention, terminalFailureAttention } from "./failures.js";
 import { markFailureAttentionDelivered } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
+import { formatCallbackFacts } from "./output.js";
 import type {
   BackgroundTaskCallbackOrigin,
   BackgroundTaskMeta,
@@ -487,9 +488,7 @@ export async function stopTask(
   if (remoteSessionMayExist) {
     const remoteTask = activeRemoteTasks.get(id);
     if (!remoteTask) {
-      meta.stopRequestedAt = undefined;
-      meta.error = `Cannot stop remote tmux session ${remote.sessionName}: its active SSH controller is unavailable.`;
-      writeMeta(meta);
+      recordStopError(meta, `Cannot stop remote tmux session ${remote.sessionName}: its active SSH controller is unavailable.`);
       scheduleRemoteSessionPoll(pi, id, REMOTE_SESSION_POLL_MS, getActiveSession);
       return meta;
     }
@@ -497,18 +496,14 @@ export async function stopTask(
       const stopped = await remoteTask.killTmuxSession();
       if (stopped.exitCode !== 0) {
         const detail = stopped.stderr.trim() || stopped.stdout.trim() || "remote tmux returned no diagnostic";
-        meta.stopRequestedAt = undefined;
-        meta.error = `Could not kill remote tmux session ${remote.sessionName} on ${meta.ssh?.target} (exit ${stopped.exitCode ?? "unknown"}): ${detail}`;
-        writeMeta(meta);
+        recordStopError(meta, `Could not kill remote tmux session ${remote.sessionName} on ${meta.ssh?.target} (exit ${stopped.exitCode ?? "unknown"}): ${detail}`);
         scheduleRemoteSessionPoll(pi, id, REMOTE_SESSION_POLL_MS, getActiveSession);
         return meta;
       }
       remote.stopMessage = `Killed remote tmux session ${remote.sessionName} on ${meta.ssh?.target}.`;
       appendLine(meta.logPath, `--- ${remote.stopMessage} ---`);
     } catch (error) {
-      meta.stopRequestedAt = undefined;
-      meta.error = error instanceof Error ? error.message : String(error);
-      writeMeta(meta);
+      recordStopError(meta, error instanceof Error ? error.message : String(error));
       scheduleRemoteSessionPoll(pi, id, REMOTE_SESSION_POLL_MS, getActiveSession);
       return meta;
     }
@@ -516,9 +511,7 @@ export async function stopTask(
     try {
       stopProcessGroup(meta.pid, meta.pgid);
     } catch (error) {
-      meta.stopRequestedAt = undefined;
-      meta.error = error instanceof Error ? error.message : String(error);
-      writeMeta(meta);
+      recordStopError(meta, error instanceof Error ? error.message : String(error));
       if (meta.deadlineAt && meta.deadlineAt > Date.now()) {
         scheduleProcessTimeout(pi, id, meta.deadlineAt, getActiveSession);
       }
@@ -528,6 +521,7 @@ export async function stopTask(
 
   stopFailureAttention(id);
   meta.status = "cancelled";
+  meta.stopError = undefined;
   meta.endedAt = Date.now();
   meta.result = {
     reason: meta.remote?.session === "direct"
@@ -541,6 +535,13 @@ export async function stopTask(
   return meta;
 }
 
+function recordStopError(meta: BackgroundTaskMeta, message: string): void {
+  meta.stopRequestedAt = undefined;
+  meta.stopError = message;
+  meta.error = message;
+  writeMeta(meta);
+}
+
 function scheduleWatch(
   pi: ExtensionAPI,
   id: string,
@@ -583,6 +584,7 @@ async function pollWatch(
     appendWatchResult(meta.logPath, result);
     const latest = readMeta(id);
     if (!latest || latest.status !== "running") return;
+    applyCaptureOverflow(latest, result);
     enforceLogRetention(latest);
     latest.lastCheckedAt = Date.now();
     latest.lastProgressAt = latest.lastCheckedAt;
@@ -632,7 +634,13 @@ async function pollWatch(
     if (conditionErrors.length) latest.error = conditionErrors.join("; ");
     if (failure?.matched) {
       recordFailure(latest, "failure_when", "failure condition matched", pollKey, { category: "condition", at: result.endedAt });
-      finalize(latest, { status: "failed", reason: "failure condition matched", matchedCondition: latest.failureWhen, commandResult: result }, pi, getActiveSession);
+      finalize(latest, {
+        status: "failed",
+        reason: "failure condition matched",
+        matchedCondition: latest.failureWhen,
+        matchedValue: failure.value,
+        commandResult: result,
+      }, pi, getActiveSession);
       return;
     }
     if (transportFailure) {
@@ -647,7 +655,13 @@ async function pollWatch(
       return;
     }
     if (success?.matched) {
-      finalize(latest, { status: "succeeded", reason: "success condition matched", matchedCondition: latest.successWhen, commandResult: result }, pi, getActiveSession);
+      finalize(latest, {
+        status: "succeeded",
+        reason: "success condition matched",
+        matchedCondition: latest.successWhen,
+        matchedValue: success.value,
+        commandResult: result,
+      }, pi, getActiveSession);
       return;
     }
     writeMeta(latest);
@@ -683,10 +697,12 @@ function finalize(
   meta.result = {
     reason: terminal.reason,
     matchedCondition: terminal.matchedCondition,
+    matchedValue: terminal.matchedValue,
     exitCode: terminal.commandResult?.exitCode,
     signal: terminal.commandResult?.signal,
   };
   if (terminal.commandResult) {
+    applyCaptureOverflow(meta, terminal.commandResult);
     meta.lastExitCode = terminal.commandResult.exitCode;
     meta.lastSignal = terminal.commandResult.signal;
     meta.lastCheckedAt = terminal.commandResult.endedAt;
@@ -799,8 +815,8 @@ async function finalizeProcessTimeout(
         stopProcessGroup(meta.pid, meta.pgid);
       } catch (error) {
         reason = `timeout; could not terminate local process tree: ${readableError(error)}`;
-        meta.error = reason;
-        writeMeta(meta);
+        // The task is still running: this is a stop failure, reported as such.
+        recordStopError(meta, reason);
         return;
       }
     }
@@ -837,12 +853,17 @@ async function notifyTerminal(
   }
   const pending = terminalFailureAttention(latest.id);
   const label = latest.name ? `${latest.name} (${latest.id})` : latest.id;
+  const facts = formatCallbackFacts(latest);
   getCallbackBatcher(pi).enqueue({
     source: "background-task",
     id: latest.id,
     label,
     status: pending ? `${latest.status}: ${pending.summary}` : latest.status,
     detailTool: "bg_task_status",
+    outcome: facts.outcome,
+    failureRows: facts.failureRows,
+    decision: facts.decision,
+    incidentCount: facts.incidentCount,
     callback: true,
     isDelivered: () => {
       const current = readMeta(latest.id);
@@ -950,9 +971,27 @@ function enforceLogRetention(meta: BackgroundTaskMeta): void {
   if (!compacted) return;
   meta.logDiscardedBytes = (meta.logDiscardedBytes ?? 0) + compacted.discardedBytes;
   meta.logRetentionEvents = (meta.logRetentionEvents ?? 0) + 1;
+  meta.logGeneration = (meta.logGeneration ?? 0) + 1;
   writeMeta(meta);
 }
 
+/** Results whose capture loss is already counted; one poll result is counted once. */
+const countedCaptureResults = new WeakSet<CommandResult>();
+
+function applyCaptureOverflow(meta: BackgroundTaskMeta, result: CommandResult): void {
+  const stdout = result.stdoutDiscardedBytes ?? 0;
+  const stderr = result.stderrDiscardedBytes ?? 0;
+  if (!result.captureTruncated && stdout === 0 && stderr === 0) return;
+  // pollWatch counts a result before evaluating conditions, and finalize sees
+  // the same result again when that poll ends the watch.
+  if (countedCaptureResults.has(result)) return;
+  countedCaptureResults.add(result);
+  meta.stdoutDiscardedBytes = (meta.stdoutDiscardedBytes ?? 0) + stdout;
+  meta.stderrDiscardedBytes = (meta.stderrDiscardedBytes ?? 0) + stderr;
+  meta.captureDiscardedBytes = (meta.captureDiscardedBytes ?? 0) + stdout + stderr;
+  meta.captureOverflowEvents = (meta.captureOverflowEvents ?? 0) + 1;
+}
+
 function extractLastState(result: { stdout: string }): unknown {
   try {
     return JSON.parse(result.stdout);