pi-better-background-tasks 0.2.20 → 0.4.0

package/src/tools.ts

@@ -1,17 +1,28 @@
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { failurePath, failureSummary } from "./failures.js";
-import { readFailureState } from "./shared-failure-observations.js";
-import { readLog } from "./logs.js";
 import { refreshBackgroundTasksNavigator } from "./navigator-provider.js";
+import {
+  classifyOwnership,
+  formatLaunch,
+  formatList,
+  formatLog,
+  formatMissingTask,
+  formatMutationRefusal,
+  formatStatus,
+  formatStopResult,
+  type OutputOptions,
+} from "./output.js";
+import { readOutputControls } from "./shared-log-utils.js";
 import { cancelCallbackBatch } from "./shared-callback-batcher.js";
-import { listMetas, listMetasForOrigin, readMeta, writeMeta } from "./registry.js";
+import { inspectMeta, listMetasForOrigin, writeMeta } from "./registry.js";
 import { resumeRunningTask, spawnTask, startWatchTask, stopTask } from "./runtime.js";
 import { runTaskMaintenance } from "./maintenance.js";
 import { ForegroundSandboxBlockedError } from "./sandbox.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta } from "./types.js";
 import { isTerminalStatus } from "./types.js";
 
+export { formatLaunch } from "./output.js";
+
 const JsonPathSchema = Type.String({
   pattern: "^\\$",
   description: "Root-prefixed JSON path, e.g. $.status, $.terminalFailure, or $.steps[0].status. Bare keys and wildcards are unsupported.",
@@ -25,13 +36,22 @@ const ConditionSchema = Type.Union([
   Type.Object({ type: Type.Literal("json_path_exists"), path: JsonPathSchema }),
 ]);
 
+/**
+ * String-to-string map declared with additionalProperties. Equivalent to
+ * Type.Record(Type.String(), Type.String()) for accepted values; kept as the
+ * plainer JSON Schema form.
+ */
+function StringMap(description: string) {
+  return Type.Unsafe<Record<string, string>>({ type: "object", additionalProperties: { type: "string" }, description });
+}
+
 const SshSchema = Type.Object({
   host: Type.String({ description: "SSH host. Required when ssh is set." }),
   user: Type.Optional(Type.String({ description: "SSH user." })),
   port: Type.Optional(Type.Integer({ minimum: 1, maximum: 65_535, description: "SSH port." })),
   identity_file: Type.Optional(Type.String({ description: "SSH identity file path." })),
   jump: Type.Optional(Type.String({ description: "SSH jump host passed with -J." })),
-  options: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Additional SSH -o key/value options. Agent-safe defaults remain enforced." })),
+  options: Type.Optional(StringMap("Additional SSH -o key/value options. Agent-safe defaults remain enforced.")),
 }, {
   description: "Structured SSH connection for remote background tasks. Set ssh instead of wrapping command in a hand-written ssh command; command is the remote command, and Pi keeps durable local logs, status, callbacks, and remote stop semantics.",
 });
@@ -44,18 +64,29 @@ const RemoteSchema = Type.Object({
   description: "Remote execution controls used with ssh. Omit session for SSH spawn to get the durable tmux default; SSH watch runs direct one-shot polls regardless of session and does not install tmux.",
 });
 
+// Structured intent (#325). Validated in code before launch (no uniqueItems/pattern: some providers reject them).
+// Each field also admits null, which means "not declared": models send optional fields as explicit
+// null, and readTaskIntent treats null exactly like an omitted field on every Pi version. Plain
+// JSON Schema `anyOf` (Type.Unsafe), not Type.Union: Pi 0.82 converts a null to "" or [] through a
+// TypeBox union, and a Null-first union reports a malformed array as "must be null".
+const IntentFields = {
+  operation_id: Type.Optional(Type.Unsafe<string | null>({ anyOf: [{ type: "null" }, { type: "string" }], description: "Optional stable id (letters, digits, . _ : / -; up to 64) for one logical operation. Reuse it when you retry with a changed command, scope, or timeout: when a later task with the same operation_id succeeds, earlier failures of that operation in this session are recovered." })),
+  expected_exit_codes: Type.Optional(Type.Unsafe<number[] | null>({ anyOf: [{ type: "array", items: { type: "integer", minimum: 1, maximum: 255 }, minItems: 1, maxItems: 16 }, { type: "null" }], description: "Optional distinct non-zero exit codes that are intentional for this command (e.g. [1] for a no-match probe). Declared before launch; recorded as expected failures, not incidents needing action. Signals and timeouts are never expected." })),
+};
+
 const CommandFields = {
   name: Type.Optional(Type.String({ description: "Human-readable task label." })),
   command: Type.Optional(Type.String({ description: "Shell command to run, or the remote command when ssh is set. Required unless shell:false with argv is used." })),
   argv: Type.Optional(Type.Array(Type.String(), { description: "Argument vector. Use with shell:false to avoid shell parsing." })),
   shell: Type.Optional(Type.Boolean({ description: "Run command through the package's bash-compatible shell. Default true." })),
   cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the current pi cwd." })),
-  env: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Extra environment variables." })),
+  env: Type.Optional(StringMap("Extra environment variables.")),
   max_log_bytes: Type.Optional(Type.Number({ description: "Maximum retained raw-log bytes. Default 4194304 (4 MiB). Older output is compacted while the task runs." })),
   callback: Type.Optional(Type.Boolean({ description: "Queue a follow-up when the task reaches a terminal state. Default true." })),
   timeout_seconds: Type.Optional(Type.Number({ description: "Optional timeout in seconds. Command watchers default to 900 seconds when omitted; pass 0 to disable. Spawned processes have no default timeout." })),
   ssh: Type.Optional(SshSchema),
   remote: Type.Optional(RemoteSchema),
+  ...IntentFields,
 };
 
 const SpawnParams = Type.Object(CommandFields);
@@ -67,17 +98,38 @@ const WatchParams = Type.Object({
   failure_when: Type.Optional(ConditionSchema),
 });
 
+const CursorFields = {
+  cursor: Type.Optional(Type.String({ description: "Caller-owned continuation cursor from a previous page. Replay returns the same page or a no-change/failure-only notice; nextCursor continues. Independent callers do not consume each other. Cursors are bound to the selected session scope." })),
+  max_bytes: Type.Optional(Type.Number({ description: "Optional UTF-8 byte budget. Defaults: status/log/list 1 KiB, raw evidence 16 KiB. Larger explicit pages are allowed up to the shared hard cap (status 2 KiB, log/list 4 KiB, raw 64 KiB). Hard caps are OUTPUT_BUDGET_MAX_BYTES." })),
+  maxBytes: Type.Optional(Type.Number({ description: "Deprecated alias for max_bytes. max_bytes wins when both are given." })),
+  all: Type.Optional(Type.Boolean({ description: "Inspect, list, stop, or clear-by-id tasks across every session. Default false is current-session only. Unknown ownership is reported as a gap, never as missing or healthy; stop and clear refuse tasks outside the current session." })),
+};
+
 const IdParams = Type.Object({
   id: Type.String({ description: "Background task id." }),
-  verbose: Type.Optional(Type.Boolean({ description: "Return full raw metadata JSON. Default false returns the compact model-facing summary. Use true only for debugging or explicit recovery." })),
+  verbose: Type.Optional(Type.Boolean({ description: "Return raw metadata JSON with environment values omitted, bounded like raw evidence (16 KiB default, max_bytes up to 64 KiB, paged with cursor when larger). Default false returns the compact model-facing summary. Use true only for debugging or explicit recovery." })),
+  ...CursorFields,
+});
+const HistoryField = {
+  history: Type.Optional(Type.Boolean({ description: "If true, return an incident page that also lists failure history: expected failures and recovered or superseded incidents. Default output lists only failures that need action and counts the rest." })),
+};
+const StatusParams = Type.Object({
+  id: Type.String({ description: "Background task id." }),
+  verbose: Type.Optional(Type.Boolean({ description: "Return raw metadata JSON with environment values omitted, bounded like raw evidence (16 KiB default, max_bytes up to 64 KiB, paged with cursor when larger). Default false returns the compact model-facing summary. Use true only for debugging or explicit recovery." })),
+  ...HistoryField,
+  ...CursorFields,
 });
 const ListParams = Type.Object({
   status: Type.Optional(Type.Array(Type.String({ description: "Statuses to include." }))),
-  limit: Type.Optional(Type.Number({ description: "Maximum tasks to show. Default 20." })),
+  limit: Type.Optional(Type.Number({ description: "Maximum tasks to show. Default 10, max 100." })),
+  ...CursorFields,
 });
 const LogParams = Type.Object({
   id: Type.String({ description: "Background task id." }),
-  tail_lines: Type.Optional(Type.Number({ description: "Number of trailing lines. Default 5 for compact model ingestion. Set <=0 only when the full log is explicitly required." })),
+  lines: Type.Optional(Type.Number({ description: "Number of trailing display rows. Default 10 for compact model ingestion. Set 0 to page retained raw bytes from the oldest retained offset." })),
+  tail_lines: Type.Optional(Type.Number({ description: "Deprecated alias for lines. lines wins when both are given." })),
+  raw: Type.Optional(Type.Boolean({ description: "Page retained raw log bytes (16 KiB default, 64 KiB hard cap) instead of the compact excerpt. Capture and retention loss are disclosed; this is not a full-history archive." })),
+  ...CursorFields,
 });
 
 const ActionParams = Type.Object({
@@ -93,12 +145,16 @@ const ActionParams = Type.Object({
   id: Type.Optional(Type.String()),
   status: Type.Optional(Type.Array(Type.String())),
   limit: Type.Optional(Type.Number()),
-  tail_lines: Type.Optional(Type.Number()),
+  lines: Type.Optional(Type.Number({ description: "action:log trailing display rows (default 10; 0 pages raw bytes)." })),
+  tail_lines: Type.Optional(Type.Number({ description: "Deprecated alias for lines." })),
   verbose: Type.Optional(Type.Boolean()),
   ...CommandFields,
   interval_seconds: Type.Optional(Type.Number()),
   success_when: Type.Optional(ConditionSchema),
   failure_when: Type.Optional(ConditionSchema),
+  raw: Type.Optional(Type.Boolean()),
+  ...HistoryField,
+  ...CursorFields,
 });
 
 const StatusActionParams = Type.Object({
@@ -106,8 +162,12 @@ const StatusActionParams = Type.Object({
   id: Type.Optional(Type.String()),
   status: Type.Optional(Type.Array(Type.String())),
   limit: Type.Optional(Type.Number()),
-  tail_lines: Type.Optional(Type.Number()),
+  lines: Type.Optional(Type.Number({ description: "action:log trailing display rows (default 10; 0 pages raw bytes)." })),
+  tail_lines: Type.Optional(Type.Number({ description: "Deprecated alias for lines." })),
   verbose: Type.Optional(Type.Boolean()),
+  raw: Type.Optional(Type.Boolean()),
+  ...HistoryField,
+  ...CursorFields,
 });
 
 const BACKGROUND_ORCHESTRATION_GUIDELINES = [
@@ -169,45 +229,47 @@ export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "bg_task_list",
     label: "BG List",
-    description: "List durable background tasks. Nonblocking.",
+    description: "List durable background tasks as compact rows under a 1 KiB UTF-8 budget (10 entries default), newest first. Current-session only unless all:true. Nonblocking. Pass the returned nextCursor as cursor to page further (every task is reachable), or statusCursor to get a small no-change response or failure-only updates; a higher limit/max_bytes gives a larger explicit page.",
     parameters: ListParams,
-    async execute(_toolCallId, params) {
-      return text(formatList(resolveList(params.status, params.limit)));
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      activeSession = getCallbackOrigin(ctx);
+      return text(formatList(listOptions(params, activeSession)));
     },
   });
 
   pi.registerTool({
     name: "bg_task_status",
     label: "BG Status",
-    description: "Inspect one background task. Default output is a compact model-facing summary; pass verbose:true only when full raw metadata is explicitly needed. After a terminal callback, call this first and call bg_task_log only if the summary is insufficient.",
-    parameters: IdParams,
-    async execute(_toolCallId, params) {
-      const meta = readMeta(params.id);
-      return text(formatStatus(meta, params.id, { verbose: params.verbose === true }));
+    description: "Inspect one background task. Default output is a compact model-facing summary (1 KiB UTF-8) with matched condition, exit/signal, stop error, and failure counts before progress. Current-session only unless all:true; unknown ownership is a gap, not missing or healthy. Pass verbose:true only when full raw metadata is explicitly needed. Environment values are omitted. A raw log nextCursor passed as cursor continues the raw log page; an incidentCursor pages incidents that need action; history:true lists failure history too. After a terminal callback, call this first and call bg_task_log only if the summary is insufficient.",
+    parameters: StatusParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      activeSession = getCallbackOrigin(ctx);
+      return text(formatStatus(inspectMeta(params.id), statusOptions(params, activeSession)));
     },
   });
 
   pi.registerTool({
     name: "bg_task_log",
     label: "BG Log",
-    description: "Read a background task log. Default output is a compact 5-line terminal-aware tail for model ingestion. Pass tail_lines for a bounded tail; tail_lines:0 returns the retained raw log, capped at 512 KiB for safe recovery. Nonblocking.",
+    description: "Read a background task log. Default output is a compact 10-line terminal-aware tail for model ingestion (1 KiB UTF-8). Current-session only unless all:true. Pass lines for a bounded tail (tail_lines is a deprecated alias); lines:0 pages the retained raw log from the oldest retained offset (16 KiB pages, 64 KiB hard cap) with a caller-owned cursor. Capture and retention loss are disclosed; this is not a full-history archive. Nonblocking.",
     parameters: LogParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
       return renderBackgroundTaskLogDisplay(result, options, theme);
     },
-    async execute(_toolCallId, params) {
-      return logText(params.id, params.tail_lines);
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      activeSession = ctx ? getCallbackOrigin(ctx) : activeSession;
+      return logText(params.id, logOptions(params, activeSession));
     },
   });
 
   pi.registerTool({
     name: "bg_task_stop",
     label: "BG Stop",
-    description: "Cancel a watcher or terminate a background task. For a tmux-backed SSH task, stop kills its remote tmux session before marking it cancelled. Direct SSH stop only tears down the local client and may leave the remote process running.",
+    description: "Cancel a watcher or terminate a background task. Only a task owned by the current session stops; a foreign-session or unverifiable task is refused unless all:true. For a tmux-backed SSH task, stop kills its remote tmux session before marking it cancelled. Direct SSH stop only tears down the local client and may leave the remote process running.",
     parameters: IdParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
-      const result = await formatStop(pi, params.id, ctx, getActiveSession);
+      const result = await formatStop(pi, params.id, ctx, getActiveSession, statusOptions(params, activeSession));
       refreshBackgroundTasksNavigator(ctx);
       return text(result);
     },
@@ -216,7 +278,7 @@ export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "bg_task",
     label: "BG Task",
-    description: "Action wrapper for background tasks: spawn, watch, list, status, log, stop, or clear. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. SSH spawn defaults to durable tmux; SSH watches use direct one-shot polls without tmux installation; remote.session=direct is a weaker-stop spawn escape hatch. Spawn/watch return immediately; do not poll in foreground. For action:status, default compact output and use verbose:true only for full metadata. For action:log, default compact tail and use tail_lines:0 only for explicit full logs.",
+    description: "Action wrapper for background tasks: spawn, watch, list, status, log, stop, or clear. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. SSH spawn defaults to durable tmux; SSH watches use direct one-shot polls without tmux installation; remote.session=direct is a weaker-stop spawn escape hatch. Spawn/watch return immediately; do not poll in foreground. For action:status, default compact output and use verbose:true only for full metadata. For action:log, default compact tail and use lines:0 to page retained raw bytes. Standalone tools and these wrappers share the same output assembler. List/status/log default to the current session; pass all:true to override. Stop and clear change only current-session tasks: clear dismisses every owned terminal task, or one task with id (all:true allows another session's task by id).",
     promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: ActionParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
@@ -231,7 +293,7 @@ export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "bg_status",
     label: "BG Status",
-    description: "Action wrapper for inspecting background tasks: list, status, log, stop, or clear. Nonblocking. Status is compact by default; log returns a compact tail by default. Use verbose:true or tail_lines:0 only for explicit full-data recovery.",
+    description: "Action wrapper for inspecting background tasks: list, status, log, stop, or clear. Nonblocking. Status is compact by default; log returns a compact tail by default. Use verbose:true or lines:0 only for explicit full-data recovery. Shares the same output assembler as the standalone tools. Current-session default; pass all:true to override. Stop and clear change only current-session tasks (clear with id and all:true for another session's task).",
     parameters: StatusActionParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
       return renderBackgroundTaskLogDisplay(result, options, theme);
@@ -247,6 +309,47 @@ export function text(textValue: string, details?: unknown) {
   return { content: [{ type: "text" as const, text: textValue }], details };
 }
 
+/** Requested byte budget: canonical `max_bytes`, else the deprecated `maxBytes` alias (#321). */
+function requestedMaxBytes(params: Record<string, unknown>): number | undefined {
+  const value = readOutputControls(params).maxBytes;
+  return typeof value === "number" ? value : undefined;
+}
+
+function statusOptions(params: Record<string, unknown>, origin?: BackgroundTaskCallbackOrigin): OutputOptions {
+  return {
+    verbose: params.verbose === true,
+    history: params.history === true,
+    cursor: typeof params.cursor === "string" ? params.cursor : undefined,
+    maxBytes: requestedMaxBytes(params),
+    all: params.all === true,
+    ...scopeOptions(origin),
+  };
+}
+
+function logOptions(params: Record<string, unknown>, origin?: BackgroundTaskCallbackOrigin): OutputOptions {
+  // Canonical `lines`, else the deprecated `tail_lines` alias (#321).
+  const lines = readOutputControls(params).lines;
+  return {
+    tailLines: typeof lines === "number" ? lines : undefined,
+    raw: params.raw === true,
+    cursor: typeof params.cursor === "string" ? params.cursor : undefined,
+    maxBytes: requestedMaxBytes(params),
+    all: params.all === true,
+    ...scopeOptions(origin),
+  };
+}
+
+function listOptions(params: Record<string, unknown>, origin?: BackgroundTaskCallbackOrigin): OutputOptions {
+  return {
+    statuses: params.status as string[] | undefined,
+    limit: typeof params.limit === "number" ? params.limit : undefined,
+    cursor: typeof params.cursor === "string" ? params.cursor : undefined,
+    maxBytes: requestedMaxBytes(params),
+    all: params.all === true,
+    ...scopeOptions(origin),
+  };
+}
+
 async function actionText(
   pi: ExtensionAPI,
   params: Record<string, unknown>,
@@ -255,7 +358,7 @@ async function actionText(
   getActiveSession: () => BackgroundTaskCallbackOrigin | undefined,
 ) {
   if (params.action === "log" && params.id) {
-    return logText(String(params.id), params.tail_lines as number | undefined);
+    return logText(String(params.id), logOptions(params, callbackOrigin));
   }
   return text(await runAction(pi, params, ctx, callbackOrigin, getActiveSession));
 }
@@ -274,18 +377,18 @@ async function runAction(
       if (!params.success_when) return "Invalid parameters: watch requires success_when.";
       return withNavigatorRefresh(ctx, reportLaunch(() => startWatchTask(pi, params as never, ctx.cwd, callbackOrigin, getActiveSession)));
     case "list":
-      return formatList(resolveList(params.status as string[] | undefined, params.limit as number | undefined));
+      return formatList(listOptions(params, callbackOrigin));
     case "status":
       if (!params.id) return "Invalid parameters: status requires id.";
-      return formatStatus(readMeta(String(params.id)) ?? undefined, String(params.id), { verbose: params.verbose === true });
+      return formatStatus(inspectMeta(String(params.id)), statusOptions(params, callbackOrigin));
     case "log":
       if (!params.id) return "Invalid parameters: log requires id.";
-      return formatLog(String(params.id), params.tail_lines as number | undefined);
+      return formatLog(String(params.id), logOptions(params, callbackOrigin));
     case "stop":
       if (!params.id) return "Invalid parameters: stop requires id.";
-      return withNavigatorRefresh(ctx, await formatStop(pi, String(params.id), ctx, getActiveSession));
+      return withNavigatorRefresh(ctx, await formatStop(pi, String(params.id), ctx, getActiveSession, statusOptions(params, callbackOrigin)));
     case "clear":
-      return withNavigatorRefresh(ctx, formatClear(params.status as string[] | undefined, callbackOrigin));
+      return withNavigatorRefresh(ctx, formatClear(params, statusOptions(params, callbackOrigin)));
     default:
       return `Unknown action: ${String(params.action)}`;
   }
@@ -311,111 +414,33 @@ function withNavigatorRefresh(ctx: ExtensionContext, result: string): string {
   return result;
 }
 
-function getCallbackOrigin(ctx: ExtensionContext): BackgroundTaskCallbackOrigin {
+/** Origins whose session identity could not be read (the host threw). */
+const unavailableSessionOrigins = new WeakSet<BackgroundTaskCallbackOrigin>();
+
+function getCallbackOrigin(ctx: ExtensionContext | undefined): BackgroundTaskCallbackOrigin {
   let sessionId: string | undefined;
+  let unavailable = false;
   try {
-    sessionId = ctx.sessionManager?.getSessionId();
+    sessionId = ctx?.sessionManager?.getSessionId();
   } catch {
     sessionId = undefined;
+    unavailable = true;
   }
-  return { cwd: ctx.cwd, sessionId };
-}
-
-function resolveList(statuses?: string[], limit?: number): BackgroundTaskMeta[] {
-  let metas = listMetas();
-  if (statuses && statuses.length > 0) {
-    const wanted = new Set(statuses);
-    metas = metas.filter((meta) => wanted.has(meta.status));
-  }
-  return metas.slice(0, Math.max(1, Math.min(limit ?? 20, 100)));
-}
-
-export function formatLaunch(meta: BackgroundTaskMeta): string {
-  const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
-  const remote = meta.ssh
-    ? ` Remote: ${meta.ssh.target}${meta.remote?.session ? ` mode=${meta.remote.session}` : ""}${meta.remote?.sessionName ? ` session=${meta.remote.sessionName}` : ""}.`
-    : "";
-  const setup = meta.remote?.bootstrapMessage ? ` Remote setup: ${meta.remote.bootstrapMessage}` : "";
-  const warning = meta.remote?.warning ? ` Warning: ${meta.remote.warning}` : "";
-  const failure = failureSummary(meta.id);
-  return `${failure ? `${failure}\n` : ""}Started background ${meta.kind} ${label}. Status: ${meta.status}.${remote}${setup}${warning} Log: ${meta.logPath}`;
-}
-
-function formatList(metas: BackgroundTaskMeta[]): string {
-  if (metas.length === 0) return "No background tasks found.";
-  return metas.map((meta) => {
-    const failure = failureSummary(meta.id);
-    const age = formatDuration((meta.endedAt ?? Date.now()) - meta.startedAt);
-    const label = meta.name ? `${meta.name} ` : "";
-    const remote = meta.ssh ? ` ${meta.ssh.target}${meta.remote?.session ? ` ${meta.remote.session}` : ""}` : "";
-    return `${failure ? `${failure}\n` : ""}${meta.id} ${label}${meta.kind} ${meta.status} ${age}${remote}`;
-  }).join("\n");
-}
-
-function formatStatus(meta: BackgroundTaskMeta | undefined, id?: string, options: { verbose?: boolean } = {}): string {
-  if (!meta) return `No background task found${id ? ` for id ${id}` : ""}.`;
-  const failure = failureSummary(meta.id);
-  if (!options.verbose) return [failure, formatCompactStatus(meta)].filter(Boolean).join("\n");
-  const state = readFailureState(failurePath(meta.id));
-  const observations = Object.values(state.observations);
-  return JSON.stringify(observations.length ? {
-    failureSummary: failure, failureJournal: failurePath(meta.id),
-    failureObservations: observations.map((observation) => ({ ...observation, attentionDeliveredAt: state.delivered[observation.id] })),
-    ...meta,
-  } : meta, null, 2);
-}
-
-function formatCompactStatus(meta: BackgroundTaskMeta): string {
-  const lines = [
-    `Background task ${meta.id}${meta.name ? ` (${meta.name})` : ""} is ${meta.status}.`,
-    `kind: ${meta.kind}`,
-    `elapsed: ${formatDuration((meta.endedAt ?? Date.now()) - meta.startedAt)}`,
-  ];
-  if (meta.ssh) lines.push(`remote: ${meta.ssh.target}`);
-  if (meta.remote?.session) lines.push(`remote mode: ${meta.remote.session}`);
-  if (meta.remote?.sessionName) lines.push(`remote session: ${meta.remote.sessionName}`);
-  if (meta.remote?.bootstrapMessage) lines.push(`remote setup: ${oneLine(meta.remote.bootstrapMessage, 500)}`);
-  if (meta.remote?.warning) lines.push(`warning: ${oneLine(meta.remote.warning, 500)}`);
-  if (meta.remote?.stopMessage) lines.push(`remote stop: ${oneLine(meta.remote.stopMessage, 500)}`);
-  if (meta.deadlineAt && meta.status === "running") lines.push(`deadline: ${formatDuration(meta.deadlineAt - Date.now())} left`);
-  if (meta.lastExitCode !== undefined || meta.lastSignal !== undefined) lines.push(`last exit: ${meta.lastExitCode ?? "null"}${meta.lastSignal ? ` signal=${meta.lastSignal}` : ""}`);
-  const reason = resultReason(meta.result);
-  if (reason) lines.push(`result: ${reason}`);
-  if (meta.error) lines.push(`error: ${oneLine(meta.error, 500)}`);
-  if (meta.lastState !== undefined) lines.push(`last state: ${oneLine(meta.lastState, 800)}`);
-  if (meta.logDiscardedBytes) lines.push(`log retention: ${meta.logDiscardedBytes} bytes discarded in ${meta.logRetentionEvents ?? 1} compaction(s).`);
-  lines.push(`log: ${meta.logPath}`);
-  lines.push(`For full metadata use bg_task_status id=${meta.id} verbose=true. For logs use bg_task_log id=${meta.id} tail_lines=5, or tail_lines=0 for the retained raw log.`);
-  return lines.join("\n");
-}
-
-function resultReason(result: unknown): string | undefined {
-  if (!result) return undefined;
-  if (typeof result === "object" && result !== null && "reason" in result) {
-    const reason = (result as { reason?: unknown }).reason;
-    return reason === undefined ? undefined : oneLine(reason, 500);
-  }
-  return oneLine(result, 500);
-}
-
-function oneLine(value: unknown, maxLength: number): string {
-  const raw = typeof value === "string" ? value : JSON.stringify(value);
-  const single = String(raw ?? "").replace(/\s+/g, " ").trim();
-  return single.length <= maxLength ? single : `${single.slice(0, Math.max(0, maxLength - 1))}…`;
+  const origin = { cwd: ctx?.cwd ?? "", sessionId };
+  if (unavailable) unavailableSessionOrigins.add(origin);
+  return origin;
 }
 
-function formatLog(id: string, tailLines?: number): string {
-  const meta = readMeta(id);
-  if (!meta) return `No background task found for id ${id}.`;
-  const log = readLog(meta.logPath, tailLines ?? 5);
-  const prefix = log.truncated ? `[showing tail of ${meta.logPath}]\n` : `[${meta.logPath}]\n`;
-  const failure = failureSummary(id);
-  return `${failure ? `${failure}\n` : ""}${prefix}${log.text || "(log is empty)"}`;
+function scopeOptions(origin?: BackgroundTaskCallbackOrigin): Pick<OutputOptions, "origin" | "sessionUnavailable"> {
+  return {
+    origin,
+    ...(origin && unavailableSessionOrigins.has(origin) ? { sessionUnavailable: true } : {}),
+  };
 }
 
-function logText(id: string, tailLines?: number) {
-  const body = formatLog(id, tailLines);
-  if (!readMeta(id)) return text(body);
+function logText(id: string, options: OutputOptions) {
+  const body = formatLog(id, options);
+  if (!inspectMeta(id).meta) return text(body);
   return text(body, buildBackgroundTaskLogDisplayDetails(body));
 }
 
@@ -464,8 +489,8 @@ export function renderBackgroundTaskLogDisplay(result: unknown, options: unknown
 
 function resultTextContent(result: unknown): string {
   const content = (result as { content?: Array<{ text?: string }> })?.content;
-  if (!Array.isArray(content)) return String(result ?? "");
-  return content.map((part) => part.text ?? "").join("\n");
+  if (Array.isArray(content)) return content.map((part) => part.text ?? "").join("\n");
+  return String(result ?? "");
 }
 
 function nonEmptyPreviewLines(lines: string[]): string[] {
@@ -519,46 +544,66 @@ async function formatStop(
   id: string,
   _ctx: ExtensionContext,
   getActiveSession?: () => BackgroundTaskCallbackOrigin | undefined,
+  options: OutputOptions = {},
 ): Promise<string> {
+  const existing = inspectMeta(id);
+  if (!existing.meta && !existing.found) return formatStopResult(existing, options);
+  if (!existing.meta) return formatMissingTask(existing, options);
+  // Same ownership rule as reads (#322): only a task owned by the current
+  // session stops unless the caller passes all:true.
+  const ownership = classifyOwnership(existing.meta, options);
+  if (ownership !== "allow") return formatMutationRefusal(id, ownership, "stop", options);
   const meta = await stopTask(pi, id, getActiveSession);
-  if (!meta) return `No background task found for id ${id}.`;
-  const remoteStop = meta.remote?.stopMessage ? ` ${meta.remote.stopMessage}` : "";
-  const weakStop = meta.remote?.session === "direct" ? ` Warning: ${meta.remote.warning}` : "";
-  return `Background task ${id} is ${meta.status}.${remoteStop}${weakStop}`;
+  if (!meta) return formatStopResult({ id, found: existing.found, readable: false, error: existing.error }, options);
+  return formatStopResult({ id: meta.id, meta, found: true, readable: true }, options);
 }
 
-function formatClear(statuses: string[] | undefined, active: BackgroundTaskCallbackOrigin): string {
+/**
+ * Dismiss terminal tasks with the same ownership rule as reads (#322). Bulk
+ * clear never crosses the current session scope (stricter than reads, which
+ * accept all:true for a list); clear with an id honours all:true like a read
+ * by id. Tasks whose ownership cannot be verified are counted, not dismissed.
+ */
+function formatClear(params: Record<string, unknown>, options: OutputOptions): string {
+  if (typeof params.id === "string" && params.id) return formatClearById(params.id, options);
+  const statuses = params.status as string[] | undefined;
   const wanted = statuses && statuses.length > 0 ? new Set(statuses) : undefined;
+  const statusLabel = wanted ? ` matching ${Array.from(wanted).join(",")}` : "";
+  const origin = options.origin;
+  if (!origin || options.sessionUnavailable) {
+    return "Dismissed 0 terminal background tasks: the current session identity is unavailable, so no task's ownership can be verified. Clear one task with id and all:true.";
+  }
+  const scoped: OutputOptions = { ...options, all: false };
   const now = Date.now();
   let cleared = 0;
-  for (const meta of listMetasForOrigin(active)) {
+  let unverified = 0;
+  for (const meta of listMetasForOrigin(origin)) {
     if (meta.dismissedAt !== undefined) continue;
     if (!isTerminalStatus(meta.status)) continue;
     if (wanted && !wanted.has(meta.status)) continue;
-    if (!belongsToActiveToolSession(meta, active)) continue;
+    if (classifyOwnership(meta, scoped) !== "allow") {
+      unverified += 1;
+      continue;
+    }
     meta.dismissedAt = now;
     writeMeta(meta);
     cleared += 1;
   }
-  const statusLabel = wanted ? ` matching ${Array.from(wanted).join(",")}` : "";
-  return `Dismissed ${cleared} terminal background task${cleared === 1 ? "" : "s"}${statusLabel}.`;
+  const skipped = unverified
+    ? ` ${unverified} terminal task${unverified === 1 ? "" : "s"} with unverifiable ownership ${unverified === 1 ? "was" : "were"} not dismissed; clear one with id and all:true.`
+    : "";
+  return `Dismissed ${cleared} terminal background task${cleared === 1 ? "" : "s"}${statusLabel}.${skipped}`;
 }
 
-function belongsToActiveToolSession(meta: BackgroundTaskMeta, active: BackgroundTaskCallbackOrigin): boolean {
-  const origin = meta.callbackOrigin;
-  if (origin) {
-    if (origin.cwd !== active.cwd) return false;
-    if (origin.sessionId || active.sessionId) return origin.sessionId === active.sessionId;
-    return true;
-  }
-  if (active.sessionId) return false;
-  return meta.cwd === active.cwd;
+function formatClearById(id: string, options: OutputOptions): string {
+  const inspection = inspectMeta(id);
+  if (!inspection.meta) return formatMissingTask(inspection, options);
+  const meta = inspection.meta;
+  const ownership = classifyOwnership(meta, options);
+  if (ownership !== "allow") return formatMutationRefusal(id, ownership, "clear", options);
+  if (!isTerminalStatus(meta.status)) return `Background task ${id} is ${meta.status}; only terminal tasks can be dismissed. Stop it first.`;
+  if (meta.dismissedAt !== undefined) return `Background task ${id} was already dismissed.`;
+  meta.dismissedAt = Date.now();
+  writeMeta(meta);
+  return `Dismissed terminal background task ${id} (${meta.status}).`;
 }
-
-function formatDuration(ms: number): string {
-  const seconds = Math.max(0, Math.round(ms / 1000));
-  if (seconds < 60) return `${seconds}s`;
-  const minutes = Math.floor(seconds / 60);
-  const rest = seconds % 60;
-  return `${minutes}m${rest.toString().padStart(2, "0")}s`;
-}

package/src/types.ts

@@ -34,6 +34,12 @@ export interface CommandResult {
   startedAt: number;
   endedAt: number;
   timedOut?: boolean;
+  /** Bytes of stdout never stored because the capture cap was reached. */
+  stdoutDiscardedBytes?: number;
+  /** Bytes of stderr never stored because the capture cap was reached. */
+  stderrDiscardedBytes?: number;
+  /** True when stdout or stderr capture overflowed. Distinct from log retention. */
+  captureTruncated?: boolean;
 }
 
 export interface RemoteTaskParams {
@@ -102,6 +108,13 @@ export interface BackgroundTaskMeta {
   maxLogBytes?: number;
   logDiscardedBytes?: number;
   logRetentionEvents?: number;
+  /** Incremented on every same-inode compaction so log-page cursors can detect it. */
+  logGeneration?: number;
+  /** Bytes never captured into watch/command buffers. Distinct from logDiscardedBytes. */
+  captureDiscardedBytes?: number;
+  captureOverflowEvents?: number;
+  stdoutDiscardedBytes?: number;
+  stderrDiscardedBytes?: number;
   pid?: number;
   /** Opaque process-start token used to reject recycled child PIDs. */
   pidStartTime?: string;
@@ -111,9 +124,18 @@ export interface BackgroundTaskMeta {
   spawnPidStartTime?: string;
   successWhen?: Condition;
   failureWhen?: Condition;
+  /**
+   * Caller-declared structured intent (#325), validated before launch. A later task of the same
+   * kind, cwd, SSH target, and session with the same operationId that succeeds recovers this
+   * task's earlier failures; exit codes in expectedExitCodes are recorded as expected failures.
+   */
+  operationId?: string;
+  expectedExitCodes?: number[];
   notifyOn?: "terminal";
   stopRequestedAt?: number;
   error?: string;
+  /** Set when stop failed while the task is still running. Distinct from poll errors. */
+  stopError?: string;
   ssh?: ResolvedSshIdentity;
   remote?: ResolvedRemoteTaskMetadata;
 }
@@ -122,6 +144,7 @@ export interface TerminalResult {
   status: Exclude<BackgroundTaskStatus, "running">;
   reason: string;
   matchedCondition?: Condition;
+  matchedValue?: unknown;
   commandResult?: CommandResult;
 }