pi-simple-background-tasks 0.0.0-stage → 0.1.0

package/src/core/registry.ts

@@ -0,0 +1,2426 @@
+import { spawn as nodeSpawn, type SpawnOptions } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createWriteStream, existsSync } from 'node:fs';
+// biome-ignore lint/correctness/noUnusedImports: rm is used in task-file cleanup (Promise.allSettled), which biome's import heuristic misses
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { formatSize } from '@earendil-works/pi-coding-agent';
+import {
+  type BgLogsDetails,
+  type BgTask,
+  type BgTaskSnapshot,
+  boundedRead,
+  deriveTaskNameFromCommand,
+  escapeXml,
+  formatDuration,
+  type KillKind,
+  normalizeTaskName,
+  type ReloadableShellExecutionV1,
+  type ReloadShellActivationClaimV1,
+  type ReloadShellActivationLeaseV1,
+  type ReloadShellHostAdapterV1,
+  type ReloadShellIdentityV1,
+  type ReloadShellOwnerHubV1,
+  ReloadSurvivalError,
+  type ResolvedShellPolicy,
+  resolveShellPolicy,
+  type StartTaskOptions,
+  sanitizePathSegment,
+  shellInvocationForPolicy,
+  shellPolicySnapshot,
+  snapshot,
+  type TaskStatus,
+  type TerminalPublicationAbandonReason,
+  taskDisplayName,
+} from './common.js';
+import { defaultTasksDir } from './config.js';
+import { BackgroundTaskExtensionServiceClosedError } from './extension-api.js';
+import {
+  createReloadableShellExecutionV1,
+  RELOAD_SHELL_OWNER_PROTOCOL,
+} from './reload-shell-owner.js';
+import {
+  type CleanupScope,
+  type CleanupSummary,
+  cleanupFinishedTasks as cleanupTasksOnDisk,
+} from './task-cleanup.js';
+import { closeAndFsyncOutputStream, writeJsonAtomic } from './task-durable.js';
+import {
+  runWindowsTaskkill,
+  type TaskkillOutcome,
+  type WindowsKillPhase,
+  type WindowsTaskkillOptions,
+} from './windows-taskkill.js';
+
+export const MAX_OUTPUT_BYTES = Number(process.env.PI_BG_MAX_OUTPUT_BYTES ?? 20 * 1024 * 1024);
+export const KILL_GRACE_MS = 3000;
+export const STOP_WAIT_MS = KILL_GRACE_MS + 1500;
+export const MAX_RECENT_TASKS = 100;
+export const TERMINAL_PUBLICATION_MAX_ATTEMPTS = 3;
+export const TERMINAL_PUBLICATION_RETRY_MS = 100;
+export const TASK_ADMISSION_TIMEOUT_MS = 30_000;
+const TERMINAL_PUBLICATION_DIAGNOSTIC_CHARS = 500;
+
+export type TerminalPublicationClosureReason = Extract<
+  TerminalPublicationAbandonReason,
+  'registry_shutdown' | 'publisher_closed'
+>;
+
+type TerminalPublicationGateOutcome =
+  | { readonly kind: 'released' }
+  | { readonly kind: 'rejected'; readonly error: unknown }
+  | { readonly kind: 'closed'; readonly reason: TerminalPublicationAbandonReason };
+
+interface TerminalPublicationAbandonSignal {
+  readonly promise: Promise<TerminalPublicationAbandonReason>;
+  readonly resolve: (reason: TerminalPublicationAbandonReason) => void;
+}
+
+export class BackgroundTaskAdmissionClosedError extends Error {
+  readonly code = 'pi_background_tasks_admission_closed';
+
+  constructor(kind: string) {
+    super(`Cannot start ${kind} after background task admissions have closed`);
+    this.name = 'BackgroundTaskAdmissionClosedError';
+  }
+}
+
+export class BackgroundTaskAdmissionTimeoutError extends Error {
+  readonly code = 'pi_background_tasks_admission_timeout';
+
+  constructor(kind: string, timeoutMs: number) {
+    super(`Timed out while preparing ${kind} after ${String(timeoutMs)}ms`);
+    this.name = 'BackgroundTaskAdmissionTimeoutError';
+  }
+}
+
+interface TaskAdmission {
+  readonly kind: string;
+  readonly controller: AbortController;
+  readonly deadlineAt: number;
+  readonly timeoutMs: number;
+  timeoutHandle: NodeJS.Timeout | undefined;
+  released: boolean;
+}
+
+export interface BackgroundTaskContext {
+  cwd: string;
+  sessionId?: string;
+}
+
+interface OutputEventSource {
+  on(event: 'data', listener: (data: Buffer | string) => void): unknown;
+}
+
+interface ChildStdin {
+  write(data: Buffer, callback: (error?: Error | null) => void): boolean;
+  end(callback?: () => void): unknown;
+  once(event: 'error', listener: (error: Error) => void): unknown;
+}
+
+export interface BackgroundTaskChildProcess {
+  pid?: number | undefined;
+  stdin?: ChildStdin | null | undefined;
+  stdout?: OutputEventSource | null | undefined;
+  stderr?: OutputEventSource | null | undefined;
+  kill(signal?: NodeJS.Signals): boolean;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  on(
+    event: 'close',
+    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+  ): unknown;
+}
+
+export type BackgroundTaskSpawn = (
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+) => BackgroundTaskChildProcess;
+
+type KillProcessFn = (pid: number, signal?: NodeJS.Signals | number) => boolean;
+type KillTreeFn = (
+  pid: number,
+  phase: WindowsKillPhase,
+  signal?: AbortSignal,
+) => Promise<TaskkillOutcome>;
+
+interface PosixProcessGroupKillState {
+  readonly groupId: number;
+  readonly completion: Promise<void>;
+  readonly resolveCompletion: () => void;
+  readonly deadlineAt: number;
+  forceAttempted: boolean;
+  settled: boolean;
+  failure?: Error | undefined;
+  lastProbeError?: Error | undefined;
+  verificationTimer?: NodeJS.Timeout | undefined;
+  failureListeners?: Array<(error: Error) => void> | undefined;
+}
+
+interface WindowsKillState {
+  softController?: AbortController | undefined;
+  softPromise?: Promise<void> | undefined;
+  forcePromise?: Promise<void> | undefined;
+  forceFailure?: Error | undefined;
+  forceFailureListeners?: Array<(error: Error) => void> | undefined;
+}
+
+export interface CompletionNotificationMessage {
+  customType: 'background-task-notification';
+  content: string;
+  display: true;
+  details: BgTaskSnapshot;
+}
+
+export interface CompletionNotificationOptions {
+  deliverAs: 'followUp';
+  triggerTurn: boolean;
+}
+
+export type CompletionNotificationSender = (
+  message: CompletionNotificationMessage,
+  options: CompletionNotificationOptions,
+) => void;
+
+export interface BackgroundTaskRegistryOptions {
+  sendCompletionNotification: CompletionNotificationSender;
+  publishTerminal?: (task: BgTaskSnapshot) => void;
+  spawn?: BackgroundTaskSpawn;
+  killProcess?: KillProcessFn;
+  killTree?: KillTreeFn;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  shellPolicy?: ResolvedShellPolicy;
+  tasksDir?: string | undefined;
+  makeTaskId?: () => string;
+  now?: () => number;
+  maxOutputBytes?: number;
+  maxRecentTasks?: number;
+  killGraceMs?: number;
+  stopWaitMs?: number;
+  taskAdmissionTimeoutMs?: number;
+  logger?: Pick<Console, 'error'>;
+  reloadShellOwner?: ReloadShellOwnerHubV1;
+}
+
+interface RuntimeDir {
+  abs: string;
+  display: string;
+}
+
+function defaultTaskId(): string {
+  return `b${randomBytes(4).toString('hex')}`;
+}
+
+function noopOnChange(): void {}
+
+export class BackgroundTaskRegistry {
+  private readonly tasks = new Map<string, BgTask>();
+  private runtimeDir: RuntimeDir | undefined;
+  private readonly tasksDir: string;
+  private shuttingDown = false;
+  private taskAdmissionsClosed = false;
+  private readonly activeTaskAdmissions = new Set<TaskAdmission>();
+  private readonly taskAdmissionDrainWaiters = new Set<() => void>();
+  private terminalPublicationClosed = false;
+  private terminalPublicationCloseReason: TerminalPublicationClosureReason | undefined;
+  private readonly terminalPublicationClosedSignal: Promise<TerminalPublicationClosureReason>;
+  private resolveTerminalPublicationClosedSignal: (
+    reason: TerminalPublicationClosureReason,
+  ) => void = () => {};
+  private readonly spawn: BackgroundTaskSpawn;
+  private readonly killProcess: KillProcessFn;
+  private readonly killTree: KillTreeFn;
+  private readonly platform: NodeJS.Platform;
+  private readonly env: NodeJS.ProcessEnv;
+  private shellPolicy: ResolvedShellPolicy | undefined;
+  private readonly shellPolicyEnv: NodeJS.ProcessEnv | undefined;
+  private readonly makeTaskIdFn: () => string;
+  private readonly now: () => number;
+  private readonly maxOutputBytes: number;
+  private readonly maxRecentTasks: number;
+  private readonly killGraceMs: number;
+  private readonly stopWaitMs: number;
+  private readonly taskAdmissionTimeoutMs: number;
+  private readonly logger: Pick<Console, 'error'>;
+  private readonly sendCompletionNotification: CompletionNotificationSender;
+  private readonly publishTerminalSnapshot: (task: BgTaskSnapshot) => void;
+  private readonly posixProcessGroupKillStates = new WeakMap<BgTask, PosixProcessGroupKillState>();
+  private readonly windowsKillStates = new WeakMap<BgTask, WindowsKillState>();
+  private readonly terminalPublicationAbandonSignals = new WeakMap<
+    BgTask,
+    TerminalPublicationAbandonSignal
+  >();
+  private readonly reloadShellOwner: ReloadShellOwnerHubV1 | undefined;
+  private reloadShellLease: ReloadShellActivationLeaseV1 | undefined;
+  private reloadShellIdentity: ReloadShellIdentityV1 | undefined;
+
+  constructor(options: BackgroundTaskRegistryOptions) {
+    this.terminalPublicationClosedSignal = new Promise((resolve) => {
+      this.resolveTerminalPublicationClosedSignal = resolve;
+    });
+    this.spawn =
+      options.spawn ?? ((command, args, spawnOptions) => nodeSpawn(command, args, spawnOptions));
+    this.killProcess = options.killProcess ?? process.kill.bind(process);
+    this.platform = options.platform ?? process.platform;
+    this.env = options.env ?? process.env;
+    this.shellPolicy = options.shellPolicy;
+    this.tasksDir = options.tasksDir ?? defaultTasksDir();
+    this.shellPolicyEnv = options.shellPolicy === undefined ? { ...this.env } : undefined;
+    const taskkillEnv = this.env;
+    this.killTree =
+      options.killTree ??
+      ((pid, phase, signal) => {
+        const taskkillOptions: WindowsTaskkillOptions =
+          signal === undefined ? { env: taskkillEnv } : { env: taskkillEnv, signal };
+        return runWindowsTaskkill(pid, phase, taskkillOptions);
+      });
+    this.makeTaskIdFn = options.makeTaskId ?? defaultTaskId;
+    this.now = options.now ?? Date.now;
+    this.maxOutputBytes = options.maxOutputBytes ?? MAX_OUTPUT_BYTES;
+    this.maxRecentTasks = options.maxRecentTasks ?? MAX_RECENT_TASKS;
+    this.killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
+    this.stopWaitMs = options.stopWaitMs ?? STOP_WAIT_MS;
+    this.taskAdmissionTimeoutMs = BackgroundTaskRegistry.positiveTimeout(
+      options.taskAdmissionTimeoutMs,
+      TASK_ADMISSION_TIMEOUT_MS,
+      'taskAdmissionTimeoutMs',
+    );
+    this.logger = options.logger ?? console;
+    this.sendCompletionNotification = options.sendCompletionNotification;
+    this.publishTerminalSnapshot = options.publishTerminal ?? noopOnChange;
+    this.reloadShellOwner = options.reloadShellOwner;
+  }
+
+  isShuttingDown(): boolean {
+    return this.shuttingDown;
+  }
+
+  private resolvedShellPolicy(): ResolvedShellPolicy {
+    const existing = this.shellPolicy;
+    if (existing !== undefined) return existing;
+    const resolved = resolveShellPolicy(
+      this.platform,
+      this.shellPolicyEnv ?? this.env,
+      process.cwd(),
+    );
+    this.shellPolicy = resolved;
+    return resolved;
+  }
+
+  private static positiveTimeout(
+    value: number | undefined,
+    fallback: number,
+    label: string,
+  ): number {
+    const candidate = value ?? fallback;
+    if (!Number.isFinite(candidate) || candidate <= 0) {
+      throw new Error(`${label} must be a positive finite number`);
+    }
+    return Math.max(1, Math.floor(candidate));
+  }
+
+  private beginTaskAdmission(kind: string): TaskAdmission {
+    this.assertTaskAdmissionOpen(kind);
+    const controller = new AbortController();
+    const admission: TaskAdmission = {
+      kind,
+      controller,
+      deadlineAt: Date.now() + this.taskAdmissionTimeoutMs,
+      timeoutMs: this.taskAdmissionTimeoutMs,
+      timeoutHandle: undefined,
+      released: false,
+    };
+    admission.timeoutHandle = setTimeout(() => {
+      if (admission.released || admission.controller.signal.aborted) return;
+      admission.controller.abort(
+        new BackgroundTaskAdmissionTimeoutError(admission.kind, admission.timeoutMs),
+      );
+    }, admission.timeoutMs);
+    this.activeTaskAdmissions.add(admission);
+    return admission;
+  }
+
+  private releaseTaskAdmission(admission: TaskAdmission): void {
+    if (admission.released) return;
+    admission.released = true;
+    if (admission.timeoutHandle !== undefined) {
+      clearTimeout(admission.timeoutHandle);
+      admission.timeoutHandle = undefined;
+    }
+    this.activeTaskAdmissions.delete(admission);
+    if (this.activeTaskAdmissions.size !== 0) return;
+    for (const resolve of this.taskAdmissionDrainWaiters) resolve();
+    this.taskAdmissionDrainWaiters.clear();
+  }
+
+  private taskAdmissionError(admission: TaskAdmission): Error {
+    const reason = admission.controller.signal.reason;
+    if (reason instanceof Error) return reason;
+    if (this.shuttingDown || this.taskAdmissionsClosed) {
+      return new BackgroundTaskAdmissionClosedError(admission.kind);
+    }
+    return new BackgroundTaskAdmissionTimeoutError(admission.kind, admission.timeoutMs);
+  }
+
+  private surfacedTaskAdmissionError(admission: TaskAdmission, ...details: unknown[]): Error {
+    const primary = this.taskAdmissionError(admission);
+    const meaningful = details.filter((detail) => {
+      if (detail === undefined || detail === primary) return false;
+      if (typeof detail !== 'object' || detail === null) return true;
+      return (
+        Reflect.get(detail, 'name') !== 'AbortError' &&
+        Reflect.get(detail, 'code') !== Reflect.get(primary, 'code')
+      );
+    });
+    if (meaningful.length === 0) return primary;
+    return new AggregateError(
+      [primary, ...meaningful],
+      `${primary.message}; admission cancellation or cleanup reported additional failures: ${meaningful.map(BackgroundTaskRegistry.errorMessage).join('; ')}`,
+    );
+  }
+
+  private assertTaskAdmissionOpen(kind: string, admission?: TaskAdmission): void {
+    if (admission?.controller.signal.aborted === true) throw this.taskAdmissionError(admission);
+    if (this.shuttingDown || this.taskAdmissionsClosed) {
+      throw new BackgroundTaskAdmissionClosedError(kind);
+    }
+  }
+
+  private async awaitTaskAdmissionBoundary<T>(
+    promise: Promise<T>,
+    admission: TaskAdmission,
+  ): Promise<T> {
+    try {
+      const value = await promise;
+      this.assertTaskAdmissionOpen(admission.kind, admission);
+      return value;
+    } catch (error) {
+      if (admission.controller.signal.aborted && typeof error === 'object' && error !== null) {
+        const isPlainAbort = Reflect.get(error, 'name') === 'AbortError';
+        const isCleanDurableCancellation =
+          Reflect.get(error, 'code') === 'durable_file_cancelled' &&
+          Reflect.get(error, 'renameCompleted') !== true &&
+          Array.isArray(Reflect.get(error, 'cleanupFailures')) &&
+          (Reflect.get(error, 'cleanupFailures') as unknown[]).length === 0;
+        if (isPlainAbort || isCleanDurableCancellation) {
+          throw this.taskAdmissionError(admission);
+        }
+      }
+      throw error;
+    }
+  }
+
+  closeTaskAdmissions(): void {
+    if (this.taskAdmissionsClosed) return;
+    this.taskAdmissionsClosed = true;
+    for (const admission of this.activeTaskAdmissions) {
+      if (!admission.controller.signal.aborted) {
+        admission.controller.abort(new BackgroundTaskAdmissionClosedError(admission.kind));
+      }
+    }
+  }
+
+  waitForTaskAdmissions(): Promise<void> {
+    if (this.activeTaskAdmissions.size === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.taskAdmissionDrainWaiters.add(resolve);
+    });
+  }
+
+  setShuttingDown(value: boolean): void {
+    if (value) {
+      this.shuttingDown = true;
+      this.closeTaskAdmissions();
+      this.closeTerminalPublication('registry_shutdown');
+      return;
+    }
+    // Publication and admission closure belong to one extension activation and
+    // are one-way. Pi session replacement creates a fresh registry; an old
+    // registry must not be reopened by a late lifecycle continuation.
+    if (!this.terminalPublicationClosed && !this.taskAdmissionsClosed) this.shuttingDown = false;
+  }
+
+  closeTerminalPublication(reason: TerminalPublicationClosureReason): void {
+    if (!this.terminalPublicationClosed) {
+      this.terminalPublicationClosed = true;
+      this.terminalPublicationCloseReason = reason;
+      this.resolveTerminalPublicationClosedSignal(reason);
+    }
+    const effectiveReason = this.terminalPublicationCloseReason ?? reason;
+    for (const task of this.tasks.values()) {
+      if (task.terminalPublicationState === 'pending' && task.terminalEmitInFlight === true) {
+        // A synchronous listener can close the service while emit() is still on
+        // the stack. Dispose queued work now, but let the emitter's return/throw
+        // settle the in-flight attempt exactly once.
+        if (task.terminalPublishRetryHandle !== undefined) {
+          clearTimeout(task.terminalPublishRetryHandle);
+          task.terminalPublishRetryHandle = undefined;
+        }
+        task.terminalPublicationGate = undefined;
+        continue;
+      }
+      const shouldLog =
+        task.terminalPublicationState === 'pending' &&
+        task.status !== 'running' &&
+        (task.terminalPublishAttempts > 0 ||
+          task.terminalPublishRetryHandle !== undefined ||
+          task.terminalPublicationGate !== undefined);
+      this.abandonTerminalPublication(task, effectiveReason, undefined, shouldLog);
+    }
+    this.pruneOldTasks();
+  }
+
+  allTasks(): BgTask[] {
+    return [...this.tasks.values()];
+  }
+
+  snapshot(task: BgTask): BgTaskSnapshot {
+    return snapshot(task);
+  }
+
+  // Delete the on-disk files of finished tasks in the given scope. Running
+  // tasks are left untouched and reported. Current-run tasks are also dropped
+  // from the in-memory registry so /jobs stays consistent.
+  async cleanupFinishedTasks(scope: CleanupScope, taskId?: string): Promise<CleanupSummary> {
+    const summary = await cleanupTasksOnDisk({
+      tasksDir: this.tasksDir,
+      sessionRunDir: this.runtimeDir?.abs,
+      scope,
+      taskId,
+    });
+    for (const deleted of summary.deleted) {
+      this.tasks.delete(deleted.id);
+    }
+    return summary;
+  }
+
+  hasCurrentReloadLease(): boolean {
+    const lease = this.reloadShellLease;
+    return lease !== undefined && this.reloadShellOwner?.isCurrentLease(lease) === true;
+  }
+
+  async stageReloadActivation(
+    claim: ReloadShellActivationClaimV1,
+  ): Promise<ReloadShellHostAdapterV1> {
+    if (claim.protocol !== RELOAD_SHELL_OWNER_PROTOCOL) {
+      throw new ReloadSurvivalError(
+        'pi_bg_reload_owner_protocol_incompatible',
+        'activation claim does not use the supported reload shell owner protocol',
+      );
+    }
+    const staged: ReloadableShellExecutionV1[] = [];
+    const ids = new Set<string>();
+    for (const execution of claim.executions) {
+      if (
+        execution.protocol !== RELOAD_SHELL_OWNER_PROTOCOL ||
+        execution.task.reloadExecution !== execution ||
+        execution.task.surviveReload !== true
+      ) {
+        throw new ReloadSurvivalError(
+          'pi_bg_reload_owner_protocol_incompatible',
+          'activation claim contains an incompatible reload shell execution',
+        );
+      }
+      if (ids.has(execution.task.id) || this.tasks.has(execution.task.id)) {
+        throw new ReloadSurvivalError(
+          'pi_bg_reload_owner_activation_conflict',
+          `claimed task id ${execution.task.id} conflicts with the fresh registry`,
+        );
+      }
+      ids.add(execution.task.id);
+    }
+
+    try {
+      for (const execution of claim.executions) {
+        const task = execution.task;
+        task.reloadHostDeliveryInFlight = false;
+        task.reloadHostDeliverySettled = false;
+        task.reloadHostNotificationSettled = false;
+        execution.updateLeaseAudit(claim.generation, (task.reloadSurvival?.handoffCount ?? 0) + 1);
+        this.tasks.set(task.id, task);
+        staged.push(execution);
+      }
+      await Promise.all(staged.map(async (execution) => this.writeMetadata(execution.task)));
+    } catch (error) {
+      for (const execution of staged) this.tasks.delete(execution.task.id);
+      throw error;
+    }
+
+    let boundLease: ReloadShellActivationLeaseV1 | undefined;
+    return {
+      activationNonce: claim.activationNonce,
+      onBound: (lease) => {
+        if (
+          lease.activationNonce !== claim.activationNonce ||
+          lease.generation !== claim.generation ||
+          lease.identityKey !== claim.identityKey
+        ) {
+          throw new ReloadSurvivalError(
+            'pi_bg_reload_owner_stale_claim',
+            'committed lease does not match its staged activation claim',
+          );
+        }
+        boundLease = lease;
+        this.reloadShellLease = lease;
+        this.reloadShellIdentity = claim.identity;
+      },
+      onChanged: (execution) => {
+        const lease = boundLease;
+        if (!this.ownsReloadExecution(execution, lease)) return;
+      },
+      onTerminal: (execution) => {
+        const lease = boundLease;
+        if (!this.ownsReloadExecution(execution, lease)) return;
+        void this.deliverReloadTerminal(execution, lease);
+      },
+    };
+  }
+
+  abortReloadActivation(claim: ReloadShellActivationClaimV1): void {
+    for (const execution of claim.executions) {
+      const task = execution.task;
+      if (this.tasks.get(task.id) !== task) continue;
+      if (task.terminalPublishRetryHandle !== undefined) {
+        clearTimeout(task.terminalPublishRetryHandle);
+        task.terminalPublishRetryHandle = undefined;
+      }
+      task.terminalPublicationGate = undefined;
+      task.terminalPublishInFlight = false;
+      this.tasks.delete(task.id);
+    }
+    if (this.reloadShellLease?.activationNonce === claim.activationNonce) {
+      this.reloadShellLease = undefined;
+      this.reloadShellIdentity = undefined;
+    }
+  }
+
+  prepareReloadHandoff(lease: ReloadShellActivationLeaseV1): readonly BgTask[] {
+    if (this.reloadShellOwner === undefined || this.reloadShellLease !== lease) {
+      throw new ReloadSurvivalError(
+        'pi_bg_reload_owner_stale_claim',
+        'registry does not own the requested reload activation lease',
+      );
+    }
+    const executions = this.reloadShellOwner.beginReloadHandoff(lease);
+    const tasks: BgTask[] = [];
+    for (const execution of executions) {
+      const task = execution.task;
+      if (this.tasks.get(task.id) !== task) {
+        throw new ReloadSurvivalError(
+          'pi_bg_reload_owner_stale_claim',
+          `registry no longer owns survivor ${task.id}`,
+        );
+      }
+      if (task.terminalPublishRetryHandle !== undefined) {
+        clearTimeout(task.terminalPublishRetryHandle);
+        task.terminalPublishRetryHandle = undefined;
+      }
+      task.terminalPublicationGate = undefined;
+      task.terminalPublishInFlight = false;
+      task.reloadHostDeliveryInFlight = false;
+      task.reloadHostDeliverySettled = false;
+      task.reloadHostNotificationSettled = false;
+      this.tasks.delete(task.id);
+      tasks.push(task);
+    }
+    this.reloadShellLease = undefined;
+    this.reloadShellIdentity = undefined;
+    return Object.freeze(tasks);
+  }
+
+  async waitForReloadHostSettlement(timeoutMs = this.stopWaitMs): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const unsettled = [...this.tasks.values()].filter(
+        (task) =>
+          task.reloadExecution?.phase === 'terminal' &&
+          (task.reloadHostNotificationSettled !== true ||
+            task.terminalPublicationState === 'pending'),
+      );
+      if (unsettled.length === 0) return;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        throw new Error(
+          `Timed out waiting for reload shell host settlement: ${unsettled.map((task) => task.id).join(', ')}`,
+        );
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(10, remaining)));
+    }
+  }
+
+  releaseReloadActivation(lease: ReloadShellActivationLeaseV1): void {
+    if (this.reloadShellOwner === undefined) return;
+    if (this.reloadShellLease !== lease || !this.reloadShellOwner.isCurrentLease(lease)) return;
+    this.reloadShellOwner.releaseActivation(lease);
+    this.reloadShellLease = undefined;
+    this.reloadShellIdentity = undefined;
+  }
+
+  currentReloadLease(): ReloadShellActivationLeaseV1 | undefined {
+    return this.hasCurrentReloadLease() ? this.reloadShellLease : undefined;
+  }
+
+  private ownsReloadExecution(
+    execution: ReloadableShellExecutionV1,
+    lease: ReloadShellActivationLeaseV1 | undefined,
+  ): lease is ReloadShellActivationLeaseV1 {
+    return (
+      lease !== undefined &&
+      this.reloadShellLease === lease &&
+      this.reloadShellOwner?.isCurrentLease(lease) === true &&
+      this.tasks.get(execution.task.id) === execution.task &&
+      execution.task.reloadExecution === execution
+    );
+  }
+
+  async ensureRuntimeDir(ctx: BackgroundTaskContext): Promise<RuntimeDir> {
+    if (this.runtimeDir) return this.runtimeDir;
+    const sessionId = sanitizePathSegment(ctx.sessionId ?? `session-${String(process.pid)}`);
+    const runId = `${sessionId}-${String(process.pid)}`;
+    const runtimeDirAbs = join(this.tasksDir, runId);
+    await mkdir(runtimeDirAbs, { recursive: true });
+    this.runtimeDir = { abs: runtimeDirAbs, display: runtimeDirAbs };
+    return this.runtimeDir;
+  }
+
+  private async destroyTaskStream(task: BgTask): Promise<void> {
+    const stream = task.stream;
+    if (stream === undefined || stream.closed) return;
+    await new Promise<void>((resolve) => {
+      const closed = () => {
+        stream.off('close', closed);
+        resolve();
+      };
+      stream.once('close', closed);
+      if (!stream.destroyed) stream.destroy();
+      if (stream.closed) closed();
+    });
+  }
+
+  private async discardUnspawnedTask(task: BgTask, paths: readonly string[]): Promise<void> {
+    this.tasks.delete(task.id);
+    task.finalized = true;
+    task.status = 'failed';
+    if (task.timeoutHandle !== undefined) clearTimeout(task.timeoutHandle);
+    if (task.killEscalationTimer !== undefined) clearTimeout(task.killEscalationTimer);
+    await this.destroyTaskStream(task);
+    const removals = await Promise.allSettled(paths.map((path) => rm(path, { force: true })));
+    const failures: Error[] = [];
+    for (let index = 0; index < removals.length; index++) {
+      const result = removals[index];
+      if (result?.status !== 'rejected') continue;
+      const path = paths[index] ?? '<unknown admission artifact>';
+      failures.push(
+        new Error(
+          `Failed to remove interrupted admission artifact ${path}: ${BackgroundTaskRegistry.errorMessage(result.reason)}`,
+        ),
+      );
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'Interrupted task admission artifact cleanup failed');
+    }
+  }
+
+  private captureSpawnedChild(task: BgTask, child: BackgroundTaskChildProcess): void {
+    task.child = child;
+    task.pid = child.pid;
+    if (
+      this.platform !== 'win32' &&
+      child.pid !== undefined &&
+      Number.isSafeInteger(child.pid) &&
+      child.pid > 0
+    ) {
+      // Capture detached-group ownership once, directly from this spawn. Never
+      // reconstruct signal authority from mutable task metadata or a later PID.
+      task.ownedPosixProcessGroupId = child.pid;
+    }
+  }
+
+  private bindOwnedTaskToAdmission(task: BgTask, admission: TaskAdmission): () => void {
+    const cancelOwnedTask = (): void => {
+      this.stopOwnedTaskAfterAdmissionCancellation(task, this.taskAdmissionError(admission));
+    };
+    admission.controller.signal.addEventListener('abort', cancelOwnedTask, { once: true });
+    if (admission.controller.signal.aborted) cancelOwnedTask();
+    return () => {
+      admission.controller.signal.removeEventListener('abort', cancelOwnedTask);
+    };
+  }
+
+  private stopOwnedTaskAfterAdmissionCancellation(task: BgTask, error: Error): void {
+    if (task.status !== 'running') return;
+    task.killKind = error instanceof BackgroundTaskAdmissionTimeoutError ? 'timeout' : 'shutdown';
+    task.error = error.message;
+    try {
+      this.requestKill(task, 'SIGTERM');
+    } catch (killError) {
+      this.logger.error(
+        `[background-tasks] failed to stop ${task.id} after admission cancellation:`,
+        killError,
+      );
+    }
+  }
+
+  async startTask(
+    ctx: BackgroundTaskContext,
+    command: string,
+    options: StartTaskOptions = {},
+  ): Promise<BgTask> {
+    const hasSurvival = Object.hasOwn(options, 'surviveReload');
+    if (hasSurvival && typeof options.surviveReload !== 'boolean') {
+      throw new ReloadSurvivalError(
+        'pi_bg_survive_reload_invalid',
+        'surviveReload must be a boolean when present',
+      );
+    }
+    const surviveReload = options.surviveReload === true;
+    const reloadLease = surviveReload ? this.currentReloadLease() : undefined;
+    if (surviveReload && reloadLease === undefined) {
+      throw new ReloadSurvivalError(
+        'pi_bg_reload_owner_unavailable',
+        'no successfully bound same-process reload owner activation is available',
+      );
+    }
+
+    const admission = this.beginTaskAdmission('a background task');
+    try {
+      if (surviveReload && reloadLease !== undefined) {
+        return await this.startReloadableTaskAdmitted(
+          ctx,
+          command,
+          options,
+          admission,
+          reloadLease,
+        );
+      }
+      return await this.startTaskAdmitted(ctx, command, options, admission);
+    } finally {
+      this.releaseTaskAdmission(admission);
+    }
+  }
+
+  private async startReloadableTaskAdmitted(
+    ctx: BackgroundTaskContext,
+    command: string,
+    options: StartTaskOptions,
+    admission: TaskAdmission,
+    lease: ReloadShellActivationLeaseV1,
+  ): Promise<BgTask> {
+    const normalizedCommand = command.trim();
+    if (!normalizedCommand) throw new Error('Background command is empty');
+    if (
+      this.reloadShellOwner === undefined ||
+      this.reloadShellIdentity === undefined ||
+      this.reloadShellLease !== lease ||
+      !this.reloadShellOwner.isCurrentLease(lease)
+    ) {
+      throw new ReloadSurvivalError(
+        'pi_bg_reload_owner_unavailable',
+        'reload owner activation became unavailable before launch',
+      );
+    }
+    if (ctx.sessionId !== this.reloadShellIdentity.sessionId) {
+      throw new ReloadSurvivalError(
+        'pi_bg_reload_owner_stale_claim',
+        'launch context session id does not match the bound reload owner identity',
+      );
+    }
+    this.assertTaskAdmissionOpen('a background task', admission);
+
+    const shellPolicy = this.resolvedShellPolicy();
+    const invocation = shellInvocationForPolicy(normalizedCommand, shellPolicy);
+    const dir = await this.awaitTaskAdmissionBoundary(this.ensureRuntimeDir(ctx), admission);
+    this.assertTaskAdmissionOpen('a background task', admission);
+    if (this.reloadShellLease !== lease || !this.reloadShellOwner.isCurrentLease(lease)) {
+      throw new ReloadSurvivalError(
+        'pi_bg_reload_owner_stale_claim',
+        'reload owner activation changed during task preflight',
+      );
+    }
+
+    const id = this.makeTaskIdFn();
+    const outputAbsPath = join(dir.abs, `${id}.output`);
+    const metadataAbsPath = join(dir.abs, `${id}.json`);
+    const outputPath = join(dir.display, `${id}.output`);
+    const timeoutSeconds =
+      typeof options.timeoutSeconds === 'number' &&
+      Number.isFinite(options.timeoutSeconds) &&
+      options.timeoutSeconds > 0
+        ? Math.floor(options.timeoutSeconds)
+        : undefined;
+    const taskName =
+      normalizeTaskName(options.name) ??
+      normalizeTaskName(options.description) ??
+      deriveTaskNameFromCommand(normalizedCommand);
+    const trimmedDescription = options.description?.trim();
+    const description =
+      trimmedDescription && trimmedDescription.length > 0 ? trimmedDescription : undefined;
+    const task: BgTask = {
+      id,
+      name: taskName,
+      command: normalizedCommand,
+      description,
+      status: 'running',
+      outputPath,
+      outputAbsPath,
+      metadataAbsPath,
+      cwd: ctx.cwd,
+      startTime: this.now(),
+      exitCode: undefined,
+      pid: undefined,
+      bytesWritten: 0,
+      surviveReload: true,
+      notified: false,
+      notifyOnCompletion: options.notifyOnCompletion ?? true,
+      triggerOnCompletion: options.triggerOnCompletion ?? false,
+      timeoutSeconds,
+      terminalPublished: false,
+      terminalPublicationState: 'pending',
+      terminalPublishAttempts: 0,
+      terminalPublicationGate: options.terminalPublicationGate,
+      shellPolicy: shellPolicySnapshot(shellPolicy),
+      waiters: [],
+    };
+    const launchNonce = randomBytes(16).toString('hex');
+    this.assertTaskAdmissionOpen('a background task', admission);
+    this.tasks.set(id, task);
+
+    let execution: ReloadableShellExecutionV1 | undefined;
+    let registered = false;
+    let committed = false;
+    let abortListener: (() => void) | undefined;
+    try {
+      execution = createReloadableShellExecutionV1({
+        task,
+        identity: this.reloadShellIdentity,
+        lease,
+        launchNonce,
+        invocation,
+        spawn: this.spawn,
+        killProcess: this.killProcess,
+        killTree: this.killTree,
+        platform: this.platform,
+        env: this.env,
+        maxOutputBytes: this.maxOutputBytes,
+        killGraceMs: this.killGraceMs,
+        stopWaitMs: this.stopWaitMs,
+        now: this.now,
+        logger: this.logger,
+      });
+      this.reloadShellOwner.registerExecution(lease, execution);
+      registered = true;
+      abortListener = () => {
+        if (execution === undefined) return;
+        const error = this.taskAdmissionError(admission);
+        execution.failAdmission(error);
+        const kind: KillKind =
+          error instanceof BackgroundTaskAdmissionTimeoutError ? 'timeout' : 'shutdown';
+        void execution.requestStop(kind, error.message).catch((stopError: unknown) => {
+          this.logger.error(
+            `[background-tasks] failed to stop reloadable task ${task.id} after admission cancellation:`,
+            stopError,
+          );
+        });
+      };
+      admission.controller.signal.addEventListener('abort', abortListener, { once: true });
+      if (admission.controller.signal.aborted) abortListener();
+
+      await this.awaitTaskAdmissionBoundary(
+        execution.commitInitialMetadata(admission.controller.signal),
+        admission,
+      );
+      this.assertTaskAdmissionOpen('a background task', admission);
+      if (this.reloadShellLease !== lease || !this.reloadShellOwner.isCurrentLease(lease)) {
+        throw new ReloadSurvivalError(
+          'pi_bg_reload_owner_stale_claim',
+          'reload owner activation changed before admission commit',
+        );
+      }
+      this.reloadShellOwner.markAdmissionCommitted(lease, execution);
+      committed = true;
+      return task;
+    } catch (error) {
+      const primary = admission.controller.signal.aborted
+        ? this.taskAdmissionError(admission)
+        : error instanceof Error
+          ? error
+          : new Error(String(error));
+      execution?.failAdmission(primary);
+      let cleanupError: unknown;
+      if (execution !== undefined) {
+        try {
+          if (task.status === 'running') {
+            await execution.requestStop(
+              admission.controller.signal.aborted &&
+                primary instanceof BackgroundTaskAdmissionTimeoutError
+                ? 'timeout'
+                : 'shutdown',
+              primary.message,
+            );
+          }
+        } catch (stopError) {
+          cleanupError = stopError;
+        }
+      }
+      if (registered && !committed && execution !== undefined) {
+        if (this.reloadShellOwner.isCurrentLease(lease)) {
+          this.reloadShellOwner.releaseExecution(lease, execution);
+        }
+      }
+      this.tasks.delete(task.id);
+      if (execution === undefined) {
+        const removals = await Promise.allSettled([
+          rm(outputAbsPath, { force: true }),
+          rm(metadataAbsPath, { force: true }),
+        ]);
+        const removalFailure = removals.find((result) => result.status === 'rejected');
+        if (removalFailure?.status === 'rejected') cleanupError = removalFailure.reason;
+      }
+      if (admission.controller.signal.aborted) {
+        throw this.surfacedTaskAdmissionError(admission, error, cleanupError);
+      }
+      if (cleanupError !== undefined) {
+        throw new AggregateError(
+          [primary, cleanupError],
+          `Failed to start reloadable background task and cleanup also failed: ${BackgroundTaskRegistry.errorMessage(cleanupError)}`,
+        );
+      }
+      throw new Error(`Failed to start background task: ${primary.message}`);
+    } finally {
+      if (abortListener !== undefined) {
+        admission.controller.signal.removeEventListener('abort', abortListener);
+      }
+    }
+  }
+
+  private async startTaskAdmitted(
+    ctx: BackgroundTaskContext,
+    command: string,
+    options: StartTaskOptions,
+    admission: TaskAdmission,
+  ): Promise<BgTask> {
+    const normalizedCommand = command.trim();
+    if (!normalizedCommand) throw new Error('Background command is empty');
+    this.assertTaskAdmissionOpen('a background task', admission);
+
+    const dir = await this.awaitTaskAdmissionBoundary(this.ensureRuntimeDir(ctx), admission);
+    this.assertTaskAdmissionOpen('a background task', admission);
+    const id = this.makeTaskIdFn();
+    const outputAbsPath = join(dir.abs, `${id}.output`);
+    const metadataAbsPath = join(dir.abs, `${id}.json`);
+    const outputPath = join(dir.display, `${id}.output`);
+    const shellPolicy = this.resolvedShellPolicy();
+    const invocation = shellInvocationForPolicy(normalizedCommand, shellPolicy);
+    const timeoutSeconds =
+      typeof options.timeoutSeconds === 'number' &&
+      Number.isFinite(options.timeoutSeconds) &&
+      options.timeoutSeconds > 0
+        ? Math.floor(options.timeoutSeconds)
+        : undefined;
+    const taskName =
+      normalizeTaskName(options.name) ??
+      normalizeTaskName(options.description) ??
+      deriveTaskNameFromCommand(normalizedCommand);
+    const trimmedDescription = options.description?.trim();
+    const description =
+      trimmedDescription && trimmedDescription.length > 0 ? trimmedDescription : undefined;
+
+    const task: BgTask = {
+      id,
+      name: taskName,
+      command: normalizedCommand,
+      description,
+      status: 'running',
+      outputPath,
+      outputAbsPath,
+      metadataAbsPath,
+      cwd: ctx.cwd,
+      startTime: this.now(),
+      exitCode: undefined,
+      pid: undefined,
+      bytesWritten: 0,
+      surviveReload: false,
+      notified: false,
+      notifyOnCompletion: options.notifyOnCompletion ?? true,
+      triggerOnCompletion: options.triggerOnCompletion ?? false,
+      timeoutSeconds,
+      terminalPublished: false,
+      terminalPublicationState: 'pending',
+      terminalPublishAttempts: 0,
+      terminalPublicationGate: options.terminalPublicationGate,
+      shellPolicy: shellPolicySnapshot(shellPolicy),
+      waiters: [],
+    };
+    this.assertTaskAdmissionOpen('a background task', admission);
+    this.tasks.set(id, task);
+
+    const stream = createWriteStream(outputAbsPath, { flags: 'a', encoding: 'utf8' });
+    task.stream = stream;
+    stream.on('error', (error) => {
+      task.error = `Output file write failed: ${error.message}`;
+      if (task.status === 'running') {
+        task.killKind = 'output_cap';
+        try {
+          this.requestKill(task, 'SIGTERM');
+        } catch (killError) {
+          void this.finalizeTask(
+            task,
+            'failed',
+            null,
+            undefined,
+            `${task.error}; kill failed: ${killError instanceof Error ? killError.message : String(killError)}`,
+          );
+        }
+      }
+    });
+
+    let unbindAdmissionCancellation = (): void => undefined;
+    try {
+      this.assertTaskAdmissionOpen('a background task', admission);
+      const child = this.spawn(invocation.shell, invocation.args, {
+        cwd: ctx.cwd,
+        detached: this.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: this.env,
+        windowsHide: true,
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+      });
+
+      this.captureSpawnedChild(task, child);
+
+      child.stdout?.on('data', (data) => {
+        this.appendChildOutput(task, data);
+      });
+      child.stderr?.on('data', (data) => {
+        this.appendChildOutput(task, data);
+      });
+
+      child.on('error', (error) => {
+        this.writeNotice(task, `\n[background task spawn error: ${error.message}]\n`);
+        void this.finalizeTask(task, 'failed', null, undefined, error.message);
+      });
+
+      child.on('close', (code, signalName) => {
+        let status: TaskStatus;
+        let error: string | undefined;
+        if (task.killKind === 'user' || task.killKind === 'shutdown') {
+          status = 'killed';
+        } else if (task.killKind === 'timeout') {
+          status = 'failed';
+          error = task.error ?? `Timed out after ${String(timeoutSeconds)}s`;
+        } else if (task.killKind === 'output_cap') {
+          status = 'failed';
+          error = task.error ?? `Output exceeded cap of ${formatSize(this.maxOutputBytes)}`;
+        } else if ((code ?? 0) === 0) {
+          status = 'completed';
+        } else {
+          status = 'failed';
+          const exitCode = code === null ? 'null' : String(code);
+          error = `Exited with code ${exitCode}${signalName ? ` (${signalName})` : ''}`;
+        }
+        void this.finalizeTask(task, status, code, signalName, error);
+      });
+
+      if (timeoutSeconds !== undefined) {
+        task.timeoutHandle = setTimeout(() => {
+          if (task.status !== 'running') return;
+          task.killKind = 'timeout';
+          task.error = `Timed out after ${String(timeoutSeconds)}s`;
+          this.writeNotice(task, `\n[background task timeout: ${task.error}]\n`);
+          try {
+            this.requestKill(task, 'SIGTERM');
+          } catch (error) {
+            void this.finalizeTask(
+              task,
+              'failed',
+              null,
+              undefined,
+              `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`,
+            );
+          }
+        }, timeoutSeconds * 1000);
+      }
+
+      unbindAdmissionCancellation = this.bindOwnedTaskToAdmission(task, admission);
+      await this.awaitTaskAdmissionBoundary(
+        this.writeMetadata(task, admission.controller.signal),
+        admission,
+      );
+      this.assertTaskAdmissionOpen('a background task', admission);
+      return task;
+    } catch (error) {
+      if (admission.controller.signal.aborted) {
+        const admissionError = this.taskAdmissionError(admission);
+        let cleanupError: unknown;
+        if (task.child === undefined) {
+          try {
+            await this.discardUnspawnedTask(task, [outputAbsPath, metadataAbsPath]);
+          } catch (cleanupFailure) {
+            cleanupError = cleanupFailure;
+          }
+        } else {
+          this.stopOwnedTaskAfterAdmissionCancellation(task, admissionError);
+        }
+        throw this.surfacedTaskAdmissionError(admission, error, cleanupError);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      this.writeNotice(task, `\n[background task spawn exception: ${message}]\n`);
+      await this.finalizeTask(task, 'failed', null, undefined, message);
+      throw new Error(`Failed to start background task: ${message}`);
+    } finally {
+      unbindAdmissionCancellation();
+    }
+  }
+
+  resolveTask(idOrPrefix: string): BgTask {
+    const id = idOrPrefix.trim();
+    if (!id) throw new Error('Task ID is required');
+    const exact = this.tasks.get(id);
+    if (exact) return exact;
+    const matches = [...this.tasks.values()].filter((task) => task.id.startsWith(id));
+    const onlyMatch = matches[0];
+    if (matches.length === 1 && onlyMatch) return onlyMatch;
+    if (matches.length > 1)
+      throw new Error(
+        `Ambiguous task ID prefix "${id}": ${matches.map((task) => task.id).join(', ')}`,
+      );
+    throw new Error(`Unknown background task ID: ${id}`);
+  }
+
+  async stopTask(task: BgTask, kind: KillKind, reason?: string): Promise<BgTask> {
+    if (task.status !== 'running') {
+      throw new Error(`Task ${task.id} is ${task.status}, not running`);
+    }
+    if (task.reloadExecution !== undefined) {
+      return task.reloadExecution.requestStop(kind, reason);
+    }
+    const stopWaitMs = this.stopWaitMs;
+    if (
+      this.platform !== 'win32' &&
+      task.posixProcessGroupSignalAuthorityReleased === true &&
+      this.posixProcessGroupKillStates.get(task) === undefined
+    ) {
+      const finalized = await this.waitForEnd(task, stopWaitMs);
+      if (!finalized) {
+        throw new Error(
+          `Task ${task.id} did not finish terminalization within ${formatDuration(stopWaitMs)} after its process group signal authority was released`,
+        );
+      }
+      return task;
+    }
+    task.killKind = kind;
+    if (reason) task.error = reason;
+    this.requestKill(task, 'SIGTERM');
+    const stopped =
+      this.platform === 'win32'
+        ? await this.waitForEndOrWindowsForceFailure(task, stopWaitMs)
+        : await this.waitForEndOrPosixForceFailure(task, stopWaitMs);
+    const posixForceFailure = this.posixProcessGroupKillStates.get(task)?.failure;
+    if (posixForceFailure !== undefined) throw posixForceFailure;
+    const windowsForceFailure = this.windowsKillStates.get(task)?.forceFailure;
+    if (windowsForceFailure !== undefined) throw windowsForceFailure;
+    if (!stopped) {
+      throw new Error(
+        `Task ${task.id} did not exit within ${formatDuration(stopWaitMs)} after cancellation`,
+      );
+    }
+    return task;
+  }
+
+  async stopAllRunning(
+    kind: KillKind,
+    reason?: string,
+  ): Promise<{ stopped: number; failures: string[] }> {
+    const running = this.allTasks().filter((task) => task.status === 'running');
+    const failures: string[] = [];
+    let stopped = 0;
+    await Promise.all(
+      running.map(async (task) => {
+        try {
+          await this.stopTask(task, kind, reason);
+          stopped++;
+        } catch (error) {
+          failures.push(
+            `${taskDisplayName(task)} (${task.id}): ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }),
+    );
+    return { stopped, failures };
+  }
+
+  async getTaskLogs(
+    task: BgTask,
+    maxBytes: number,
+    tail: boolean,
+  ): Promise<{ text: string; details: BgLogsDetails }> {
+    if (!existsSync(task.outputAbsPath)) {
+      throw new Error(`Output file does not exist for ${task.id}: ${task.outputPath}`);
+    }
+    const read = await boundedRead(task.outputAbsPath, maxBytes, tail);
+    const direction = tail ? 'tail' : 'head';
+    let text = read.content.length > 0 ? read.content : '(no output yet)';
+    if (read.truncated) {
+      const omitted = read.totalBytes - read.bytesRead;
+      const notice = `\n\n[Showing ${direction} ${formatSize(read.bytesRead)} of ${formatSize(read.totalBytes)}; ${formatSize(omitted)} omitted. Full output: ${task.outputPath}]`;
+      text = tail ? `${notice}\n\n${text}` : `${text}${notice}`;
+    } else {
+      text += `\n\n[Full output: ${task.outputPath}]`;
+    }
+    return {
+      text,
+      details: {
+        task: snapshot(task),
+        path: task.outputPath,
+        bytesRead: read.bytesRead,
+        truncated: read.truncated,
+        tail,
+      },
+    };
+  }
+
+  private async writeMetadata(task: BgTask, signal?: AbortSignal): Promise<void> {
+    await this.writeMetadataSnapshot(task, snapshot(task), signal);
+  }
+
+  private async writeMetadataSnapshot(
+    task: BgTask,
+    value: BgTaskSnapshot,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    const write = async () => {
+      await writeJsonAtomic(task.metadataAbsPath, value, signal);
+    };
+    const previous = task.metadataWriteChain ?? Promise.resolve();
+    const next = previous.then(write, write);
+    task.metadataWriteChain = next.catch(() => undefined);
+    await next;
+  }
+
+  /** Cap-enforcing sink for all persisted task output; terminates the task once the byte cap is exceeded. */
+  private writeToStream(task: BgTask, buffer: Buffer): void {
+    if (!task.stream || task.stream.destroyed) return;
+    if (buffer.length === 0) return;
+
+    const nextBytes = task.bytesWritten + buffer.length;
+    if (nextBytes <= this.maxOutputBytes) {
+      task.stream.write(buffer);
+      task.bytesWritten = nextBytes;
+      return;
+    }
+
+    const remaining = Math.max(0, this.maxOutputBytes - task.bytesWritten);
+    if (remaining > 0) {
+      task.stream.write(buffer.subarray(0, remaining));
+      task.bytesWritten += remaining;
+    }
+
+    if (!task.capExceeded) {
+      task.capExceeded = true;
+      task.error = `Output exceeded cap of ${formatSize(this.maxOutputBytes)}; terminating task`;
+      const notice = `\n\n[background task error: ${task.error}]\n`;
+      task.stream.write(notice);
+      task.bytesWritten += Buffer.byteLength(notice, 'utf8');
+      task.killKind = 'output_cap';
+      try {
+        this.requestKill(task, 'SIGTERM');
+      } catch (error) {
+        task.error = `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`;
+        void this.finalizeTask(task, 'failed', null, undefined, task.error);
+      }
+    }
+  }
+
+  /** Persist an internally generated notice (spawn/timeout/cap diagnostics) verbatim. */
+  private writeNotice(task: BgTask, text: string): void {
+    if (!text) return;
+    this.writeToStream(task, Buffer.from(text, 'utf8'));
+  }
+
+  private appendChildOutput(task: BgTask, data: Buffer | string): void {
+    if (!task.stream || task.stream.destroyed) return;
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+    if (buffer.length === 0) return;
+    this.writeToStream(task, buffer);
+  }
+
+  private beginPosixProcessGroupKill(task: BgTask, armGrace: boolean): PosixProcessGroupKillState {
+    const existing = this.posixProcessGroupKillStates.get(task);
+    if (existing !== undefined) return existing;
+    if (task.posixProcessGroupSignalAuthorityReleased === true) {
+      throw new Error(`Task ${task.id} has released its POSIX process-group signal authority`);
+    }
+    const groupId = task.ownedPosixProcessGroupId;
+    if (groupId === undefined) {
+      throw new Error(`Task ${task.id} has no owned POSIX process group`);
+    }
+
+    let resolveCompletion = (): void => undefined;
+    const completion = new Promise<void>((resolve) => {
+      resolveCompletion = resolve;
+    });
+    // Finish ownership slightly before stopTask's waiter so a force/proof
+    // failure is observed as that specific loud error instead of a generic
+    // cancellation timeout.
+    const reserveMs = Math.min(25, Math.max(1, Math.floor(this.stopWaitMs / 4)));
+    const ownershipMs = Math.max(1, this.stopWaitMs - reserveMs);
+    const state: PosixProcessGroupKillState = {
+      groupId,
+      completion,
+      resolveCompletion,
+      deadlineAt: Date.now() + ownershipMs,
+      forceAttempted: false,
+      settled: false,
+    };
+    this.posixProcessGroupKillStates.set(task, state);
+
+    if (armGrace) {
+      // Publish the sole force owner before TERM. An injected signal can emit
+      // close reentrantly; that close must see and await this exact state.
+      task.killEscalationTimer = setTimeout(
+        () => {
+          task.killEscalationTimer = undefined;
+          this.forceOwnedPosixProcessGroup(task, state);
+        },
+        Math.min(this.killGraceMs, ownershipMs),
+      );
+      // Unlike ordinary housekeeping timers, this owner stays referenced: a
+      // departed leader must not let the host exit and strand its owned group.
+    }
+    return state;
+  }
+
+  private finishPosixProcessGroupKill(
+    task: BgTask,
+    state: PosixProcessGroupKillState,
+    releaseOwnership: boolean,
+  ): void {
+    if (state.settled) return;
+    state.settled = true;
+    this.clearKillEscalationTimer(task);
+    if (state.verificationTimer !== undefined) {
+      clearTimeout(state.verificationTimer);
+      state.verificationTimer = undefined;
+    }
+    task.posixProcessGroupSignalAuthorityReleased = true;
+    if (releaseOwnership && task.ownedPosixProcessGroupId === state.groupId) {
+      delete task.ownedPosixProcessGroupId;
+    }
+    state.resolveCompletion();
+    const failure = state.failure;
+    const listeners = state.failureListeners;
+    if (listeners !== undefined) {
+      delete state.failureListeners;
+      if (failure !== undefined) {
+        for (const listener of listeners) listener(failure);
+      }
+    }
+  }
+
+  private observeOwnedPosixProcessGroupGone(
+    task: BgTask,
+    state: PosixProcessGroupKillState,
+  ): boolean {
+    if (state.settled) return state.failure === undefined;
+    try {
+      const exists = this.killProcess(-state.groupId, 0);
+      state.lastProbeError = exists
+        ? undefined
+        : new Error(`process-group probe for ${String(state.groupId)} returned false`);
+      return false;
+    } catch (error) {
+      if (typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'ESRCH') {
+        this.finishPosixProcessGroupKill(task, state, true);
+        return true;
+      }
+      state.lastProbeError =
+        error instanceof Error ? error : new Error(BackgroundTaskRegistry.errorMessage(error));
+      return false;
+    }
+  }
+
+  private recordPosixProcessGroupForceFailure(
+    task: BgTask,
+    state: PosixProcessGroupKillState,
+    error: Error,
+  ): void {
+    if (state.settled) return;
+    state.failure = error;
+    this.finishPosixProcessGroupKill(task, state, false);
+    task.error = BackgroundTaskRegistry.appendTaskError(task.error, error.message);
+    this.writeNotice(task, `\n[background task POSIX termination: ${error.message}]\n`);
+    void this.writeMetadata(task).catch((metadataError: unknown) => {
+      this.logger.error(
+        `[background-tasks] failed to write POSIX process-group failure metadata for ${task.id}:`,
+        metadataError,
+      );
+    });
+  }
+
+  private schedulePosixProcessGroupVerification(
+    task: BgTask,
+    state: PosixProcessGroupKillState,
+  ): void {
+    if (state.settled) return;
+    const remainingMs = state.deadlineAt - Date.now();
+    if (remainingMs <= 0) {
+      const probeDetail =
+        state.lastProbeError === undefined
+          ? ''
+          : `; last group probe failed: ${state.lastProbeError.message}`;
+      this.recordPosixProcessGroupForceFailure(
+        task,
+        state,
+        new Error(
+          `POSIX process group ${String(state.groupId)} remained present after SIGKILL${probeDetail}. Descendant processes may have leaked.`,
+        ),
+      );
+      return;
+    }
+    state.verificationTimer = setTimeout(
+      () => {
+        state.verificationTimer = undefined;
+        if (this.observeOwnedPosixProcessGroupGone(task, state)) return;
+        this.schedulePosixProcessGroupVerification(task, state);
+      },
+      Math.min(10, remainingMs),
+    );
+  }
+
+  private forceOwnedPosixProcessGroup(task: BgTask, state: PosixProcessGroupKillState): void {
+    if (state.settled || state.forceAttempted) return;
+    // Latch before either probe or signal: both are injected boundaries that can
+    // reentrantly emit root close, and no continuation may launch a second KILL.
+    state.forceAttempted = true;
+    this.clearKillEscalationTimer(task);
+    if (this.observeOwnedPosixProcessGroupGone(task, state)) return;
+
+    try {
+      const forced = this.killProcess(-state.groupId, 'SIGKILL');
+      if (!forced) {
+        this.recordPosixProcessGroupForceFailure(
+          task,
+          state,
+          new Error(
+            `POSIX process-group SIGKILL returned false for task ${task.id} group ${String(state.groupId)}. Descendant processes may have leaked.`,
+          ),
+        );
+        return;
+      }
+    } catch (error) {
+      if (typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'ESRCH') {
+        this.finishPosixProcessGroupKill(task, state, true);
+        return;
+      }
+      this.recordPosixProcessGroupForceFailure(
+        task,
+        state,
+        new Error(
+          `POSIX process-group SIGKILL failed for task ${task.id} group ${String(state.groupId)}: ${BackgroundTaskRegistry.errorMessage(error)}. Descendant processes may have leaked.`,
+        ),
+      );
+      return;
+    }
+
+    if (this.observeOwnedPosixProcessGroupGone(task, state)) return;
+    this.schedulePosixProcessGroupVerification(task, state);
+  }
+
+  private requestPosixKill(task: BgTask, signal: NodeJS.Signals): void {
+    const state = this.beginPosixProcessGroupKill(task, signal !== 'SIGKILL');
+    if (signal === 'SIGKILL') {
+      task.killSignalSent = true;
+      this.forceOwnedPosixProcessGroup(task, state);
+      return;
+    }
+    if (task.killSignalSent) return;
+    // Publish de-duplication before the signal boundary for the same reason the
+    // state/timer is published above: close may be emitted synchronously.
+    task.killSignalSent = true;
+
+    const errors: string[] = [];
+    let killed = false;
+    try {
+      killed = this.killProcess(-state.groupId, signal);
+      if (!killed) errors.push(`process group ${signal} returned false`);
+    } catch (error) {
+      if (typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'ESRCH') {
+        this.finishPosixProcessGroupKill(task, state, true);
+      } else {
+        errors.push(`process group kill failed: ${BackgroundTaskRegistry.errorMessage(error)}`);
+      }
+    }
+
+    if (!killed) {
+      try {
+        killed = task.child?.kill(signal) === true;
+        if (!killed) errors.push(`child ${signal} returned false`);
+      } catch (error) {
+        errors.push(`child kill failed: ${BackgroundTaskRegistry.errorMessage(error)}`);
+      }
+    }
+
+    if (!killed) {
+      // If TERM reached neither target, waiting out grace has no benefit. Keep
+      // the same owner but attempt its one force phase immediately.
+      if (!state.settled) this.forceOwnedPosixProcessGroup(task, state);
+      throw new Error(`Could not kill task ${task.id}: ${errors.join('; ')}`);
+    }
+  }
+
+  private async awaitPosixProcessGroupBeforeTerminal(task: BgTask): Promise<Error | undefined> {
+    if (this.platform === 'win32') return undefined;
+    const state = this.posixProcessGroupKillStates.get(task);
+    if (state === undefined) {
+      // No tree stop won the race before direct-child finalization. Release
+      // signal authority synchronously so a concurrent late stop waits for this
+      // terminalization instead of targeting a potentially reused group id.
+      task.posixProcessGroupSignalAuthorityReleased = true;
+      delete task.ownedPosixProcessGroupId;
+      return undefined;
+    }
+    this.observeOwnedPosixProcessGroupGone(task, state);
+    await state.completion;
+    return state.failure;
+  }
+
+  private waitForEndOrPosixForceFailure(task: BgTask, timeoutMs: number): Promise<boolean> {
+    const state = this.posixProcessGroupKillStates.get(task);
+    if (state === undefined) return this.waitForEnd(task, timeoutMs);
+    if (state.failure !== undefined) return Promise.reject(state.failure);
+    if (task.status !== 'running') return Promise.resolve(true);
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timeout);
+        const waiterIndex = task.waiters.indexOf(done);
+        if (waiterIndex >= 0) task.waiters.splice(waiterIndex, 1);
+        const listeners = state.failureListeners;
+        if (listeners !== undefined) {
+          const listenerIndex = listeners.indexOf(failed);
+          if (listenerIndex >= 0) listeners.splice(listenerIndex, 1);
+          if (listeners.length === 0) delete state.failureListeners;
+        }
+      };
+      const timeout = setTimeout(() => {
+        cleanup();
+        resolve(false);
+      }, timeoutMs);
+      const done = () => {
+        cleanup();
+        resolve(true);
+      };
+      const failed = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      task.waiters.push(done);
+      if (state.failureListeners === undefined) state.failureListeners = [];
+      state.failureListeners.push(failed);
+    });
+  }
+
+  private getWindowsKillState(task: BgTask): WindowsKillState {
+    let state = this.windowsKillStates.get(task);
+    if (state === undefined) {
+      state = {};
+      this.windowsKillStates.set(task, state);
+    }
+    return state;
+  }
+
+  private static errorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+  }
+
+  private static appendTaskError(existing: string | undefined, next: string): string {
+    if (existing === undefined || existing.length === 0) return next;
+    if (existing.includes(next)) return existing;
+    return `${existing}; ${next}`;
+  }
+
+  private static describeTaskkillOutcome(outcome: TaskkillOutcome): string {
+    const exitCode = outcome.exitCode === null ? 'null' : String(outcome.exitCode);
+    const signal = outcome.signal === null ? 'null' : outcome.signal;
+    const stdout = outcome.stdout.length > 0 ? ` stdout=${JSON.stringify(outcome.stdout)}` : '';
+    const stderr = outcome.stderr.length > 0 ? ` stderr=${JSON.stringify(outcome.stderr)}` : '';
+    const stdoutTruncated = outcome.stdoutTruncated ? ' stdout_truncated=true' : '';
+    const stderrTruncated = outcome.stderrTruncated ? ' stderr_truncated=true' : '';
+    return `exit=${exitCode} signal=${signal}${stdout}${stderr}${stdoutTruncated}${stderrTruncated}`;
+  }
+
+  private isWindowsTaskkillTerminalRace(task: BgTask): boolean {
+    return task.status !== 'running' || task.finalized === true;
+  }
+
+  private clearKillEscalationTimer(task: BgTask): void {
+    if (task.killEscalationTimer !== undefined) {
+      clearTimeout(task.killEscalationTimer);
+      task.killEscalationTimer = undefined;
+    }
+  }
+
+  private recordWindowsTaskkillNotice(task: BgTask, message: string): void {
+    this.writeNotice(task, `\n[background task Windows termination: ${message}]\n`);
+  }
+
+  private recordWindowsSoftFailure(task: BgTask, pid: number, detail: string): void {
+    const message =
+      `Windows taskkill /T logical termination request failed for task ${task.id} pid ${String(pid)}: ` +
+      `${detail}; force escalation remains scheduled`;
+    task.error = BackgroundTaskRegistry.appendTaskError(task.error, message);
+    this.recordWindowsTaskkillNotice(task, message);
+    void this.writeMetadata(task).catch((metadataError: unknown) => {
+      this.logger.error(
+        `[background-tasks] failed to write Windows taskkill soft-failure metadata for ${task.id}:`,
+        metadataError,
+      );
+    });
+  }
+
+  private makeWindowsForceFailure(task: BgTask, pid: number, detail: string): Error {
+    return new Error(
+      `Windows taskkill /T /F force termination failed for task ${task.id} pid ${String(pid)}: ${detail}. Descendant processes may have leaked.`,
+    );
+  }
+
+  private recordWindowsForceFailure(task: BgTask, error: Error): void {
+    const state = this.getWindowsKillState(task);
+    state.forceFailure = error;
+    task.error = BackgroundTaskRegistry.appendTaskError(task.error, error.message);
+    this.recordWindowsTaskkillNotice(task, error.message);
+    void this.writeMetadata(task).catch((metadataError: unknown) => {
+      this.logger.error(
+        `[background-tasks] failed to write Windows taskkill force-failure metadata for ${task.id}:`,
+        metadataError,
+      );
+    });
+    const listeners = state.forceFailureListeners;
+    if (listeners !== undefined) {
+      delete state.forceFailureListeners;
+      for (const listener of listeners) listener(error);
+    }
+  }
+
+  private evaluateWindowsTaskkillOutcome(
+    task: BgTask,
+    pid: number,
+    phase: WindowsKillPhase,
+    outcome: TaskkillOutcome,
+  ): Error | undefined {
+    if (outcome.exitCode === 0) return undefined;
+    const detail = BackgroundTaskRegistry.describeTaskkillOutcome(outcome);
+    if (outcome.exitCode === 128) {
+      this.recordWindowsTaskkillNotice(
+        task,
+        `taskkill ${phase} reported process not found for pid ${String(pid)} (${detail}); treating as an already-exited race`,
+      );
+      return undefined;
+    }
+    if (this.isWindowsTaskkillTerminalRace(task)) {
+      this.recordWindowsTaskkillNotice(
+        task,
+        `taskkill ${phase} finished after the task became terminal for pid ${String(pid)} (${detail}); treating as a terminal race`,
+      );
+      return undefined;
+    }
+    if (phase === 'terminate') {
+      this.recordWindowsSoftFailure(task, pid, detail);
+      return undefined;
+    }
+    return this.makeWindowsForceFailure(task, pid, detail);
+  }
+
+  private handleWindowsSoftException(
+    task: BgTask,
+    pid: number,
+    error: unknown,
+    state: WindowsKillState,
+  ): void {
+    const message = BackgroundTaskRegistry.errorMessage(error);
+    if (state.forcePromise !== undefined || this.isWindowsTaskkillTerminalRace(task)) return;
+    this.recordWindowsSoftFailure(task, pid, message);
+  }
+
+  private startWindowsSoftKill(task: BgTask, pid: number): Promise<void> {
+    const state = this.getWindowsKillState(task);
+    if (state.softPromise !== undefined) return state.softPromise;
+    const controller = new AbortController();
+    state.softController = controller;
+
+    let launched: Promise<TaskkillOutcome>;
+    try {
+      launched = this.killTree(pid, 'terminate', controller.signal);
+    } catch (error) {
+      delete state.softController;
+      throw new Error(
+        `Could not kill task ${task.id}: Windows taskkill /T failed to start: ${BackgroundTaskRegistry.errorMessage(error)}`,
+      );
+    }
+
+    const promise = launched
+      .then((outcome) => {
+        if (state.forcePromise !== undefined || this.isWindowsTaskkillTerminalRace(task)) return;
+        const failure = this.evaluateWindowsTaskkillOutcome(task, pid, 'terminate', outcome);
+        if (failure !== undefined) throw failure;
+      })
+      .catch((error: unknown) => {
+        this.handleWindowsSoftException(task, pid, error, state);
+      })
+      .finally(() => {
+        if (state.softController === controller) delete state.softController;
+      });
+    state.softPromise = promise;
+    return promise;
+  }
+
+  private startWindowsForceKill(task: BgTask, pid: number): Promise<void> {
+    const state = this.getWindowsKillState(task);
+    if (state.forcePromise !== undefined) return state.forcePromise;
+
+    let resolveForce: (() => void) | undefined;
+    let rejectForce: ((error: unknown) => void) | undefined;
+    const forcePromise = new Promise<void>((resolve, reject) => {
+      resolveForce = resolve;
+      rejectForce = reject;
+    });
+    if (resolveForce === undefined || rejectForce === undefined) {
+      throw new Error('Windows force termination promise could not be initialized');
+    }
+    const resolveForceReady = resolveForce;
+    const rejectForceReady = rejectForce;
+    state.forcePromise = forcePromise;
+    void forcePromise.catch((error: unknown) => {
+      this.logger.error(
+        `[background-tasks] Windows force tree termination failed for ${task.id}:`,
+        error,
+      );
+    });
+
+    this.clearKillEscalationTimer(task);
+    if (state.softController !== undefined && !state.softController.signal.aborted) {
+      state.softController.abort();
+    }
+
+    let launched: Promise<TaskkillOutcome>;
+    try {
+      launched = this.killTree(pid, 'force');
+    } catch (error) {
+      const failure = this.makeWindowsForceFailure(
+        task,
+        pid,
+        `helper failed to start: ${BackgroundTaskRegistry.errorMessage(error)}`,
+      );
+      delete state.forcePromise;
+      this.recordWindowsForceFailure(task, failure);
+      rejectForceReady(failure);
+      throw failure;
+    }
+
+    launched.then(
+      (outcome) => {
+        const failure = this.evaluateWindowsTaskkillOutcome(task, pid, 'force', outcome);
+        if (failure !== undefined) {
+          this.recordWindowsForceFailure(task, failure);
+          rejectForceReady(failure);
+          return;
+        }
+        resolveForceReady();
+      },
+      (error: unknown) => {
+        if (this.isWindowsTaskkillTerminalRace(task)) {
+          this.recordWindowsTaskkillNotice(
+            task,
+            `taskkill force rejected after the task became terminal for pid ${String(pid)} (${BackgroundTaskRegistry.errorMessage(error)}); treating as a terminal race`,
+          );
+          resolveForceReady();
+          return;
+        }
+        const failure = this.makeWindowsForceFailure(
+          task,
+          pid,
+          BackgroundTaskRegistry.errorMessage(error),
+        );
+        this.recordWindowsForceFailure(task, failure);
+        rejectForceReady(failure);
+      },
+    );
+
+    return forcePromise;
+  }
+
+  private requestWindowsKill(task: BgTask, pid: number, signal: NodeJS.Signals): void {
+    if (signal === 'SIGKILL') {
+      this.startWindowsForceKill(task, pid);
+      task.killSignalSent = true;
+      return;
+    }
+
+    this.startWindowsSoftKill(task, pid);
+    task.killSignalSent = true;
+    if (task.killEscalationTimer !== undefined) return;
+    task.killEscalationTimer = setTimeout(() => {
+      task.killEscalationTimer = undefined;
+      if (task.status !== 'running') return;
+      try {
+        this.requestKill(task, 'SIGKILL');
+      } catch (error) {
+        task.error = BackgroundTaskRegistry.appendTaskError(
+          task.error,
+          `SIGKILL failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        void this.writeMetadata(task).catch((metadataError: unknown) => {
+          this.logger.error(
+            `[background-tasks] failed to write metadata for ${task.id}:`,
+            metadataError,
+          );
+        });
+      }
+    }, this.killGraceMs).unref();
+  }
+
+  private requestKill(task: BgTask, signal: NodeJS.Signals = 'SIGTERM'): void {
+    if (task.status !== 'running') {
+      throw new Error(`Task ${task.id} is ${task.status}, not running`);
+    }
+    if (!task.child) {
+      throw new Error(`Task ${task.id} has no child process handle`);
+    }
+    if (task.killSignalSent && signal === 'SIGTERM') return;
+
+    if (this.platform === 'win32') {
+      if (!task.pid) throw new Error(`Task ${task.id} has no process id`);
+      this.requestWindowsKill(task, task.pid, signal);
+      return;
+    }
+
+    this.requestPosixKill(task, signal);
+  }
+
+  private waitForEnd(task: BgTask, timeoutMs: number): Promise<boolean> {
+    if (task.status !== 'running') return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        const idx = task.waiters.indexOf(done);
+        if (idx >= 0) task.waiters.splice(idx, 1);
+        resolve(false);
+      }, timeoutMs);
+      const done = () => {
+        clearTimeout(timeout);
+        resolve(true);
+      };
+      task.waiters.push(done);
+    });
+  }
+
+  private waitForEndOrWindowsForceFailure(task: BgTask, timeoutMs: number): Promise<boolean> {
+    const state = this.getWindowsKillState(task);
+    if (state.forceFailure !== undefined) return Promise.reject(state.forceFailure);
+    if (task.status !== 'running') return Promise.resolve(true);
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timeout);
+        const waiterIndex = task.waiters.indexOf(done);
+        if (waiterIndex >= 0) task.waiters.splice(waiterIndex, 1);
+        const listeners = state.forceFailureListeners;
+        if (listeners !== undefined) {
+          const listenerIndex = listeners.indexOf(failed);
+          if (listenerIndex >= 0) listeners.splice(listenerIndex, 1);
+          if (listeners.length === 0) delete state.forceFailureListeners;
+        }
+      };
+      const timeout = setTimeout(() => {
+        cleanup();
+        resolve(false);
+      }, timeoutMs);
+      const done = () => {
+        cleanup();
+        resolve(true);
+      };
+      const failed = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      task.waiters.push(done);
+      if (state.forceFailureListeners === undefined) state.forceFailureListeners = [];
+      state.forceFailureListeners.push(failed);
+    });
+  }
+
+  private async awaitWindowsForceBeforeTerminal(task: BgTask): Promise<Error | undefined> {
+    const state = this.windowsKillStates.get(task);
+    if (state === undefined) return undefined;
+    const forcePromise = state.forcePromise;
+    if (forcePromise === undefined) return state.forceFailure;
+    try {
+      await forcePromise;
+    } catch (error) {
+      return error instanceof Error ? error : new Error(String(error));
+    }
+    return state.forceFailure;
+  }
+
+  private async deliverReloadTerminal(
+    execution: ReloadableShellExecutionV1,
+    lease: ReloadShellActivationLeaseV1,
+  ): Promise<void> {
+    const task = execution.task;
+    if (task.reloadHostDeliveryInFlight || task.reloadHostDeliverySettled) {
+      this.maybeReleaseReloadExecution(task);
+      return;
+    }
+    task.reloadHostDeliveryInFlight = true;
+    try {
+      if (!this.ownsReloadExecution(execution, lease)) return;
+      this.publishTerminal(task);
+      const deliveryGate = await this.waitForTerminalPublicationGate(task);
+      if (!this.ownsReloadExecution(execution, lease)) return;
+      if (deliveryGate.kind === 'rejected') {
+        this.logger.error(
+          `[background-tasks] completion delivery gate failed for ${task.id}: ${this.terminalPublicationError(deliveryGate.error)}`,
+        );
+      } else if (
+        task.notifyOnCompletion &&
+        !task.notified &&
+        !this.shuttingDown &&
+        execution.notificationState === 'pending'
+      ) {
+        const token = execution.beginNotification(lease);
+        if (token !== undefined) {
+          try {
+            this.notifyCompletion(task);
+            execution.finishNotification(token, task.notified);
+          } catch (error) {
+            execution.finishNotification(token, false);
+            this.logger.error(`[background-tasks] notification failed for ${task.id}:`, error);
+          }
+        }
+      }
+      if (!this.ownsReloadExecution(execution, lease)) return;
+      task.reloadHostNotificationSettled = true;
+      task.reloadHostDeliverySettled = true;
+      try {
+        await this.writeMetadata(task);
+      } catch (error) {
+        this.logger.error(
+          `[background-tasks] failed to update survivor notification metadata for ${task.id}:`,
+          error,
+        );
+      }
+    } finally {
+      task.reloadHostDeliveryInFlight = false;
+      this.maybeReleaseReloadExecution(task);
+    }
+  }
+
+  private maybeReleaseReloadExecution(task: BgTask): void {
+    const execution = task.reloadExecution;
+    const lease = this.reloadShellLease;
+    if (
+      execution === undefined ||
+      execution.phase !== 'terminal' ||
+      task.reloadHostNotificationSettled !== true ||
+      task.terminalPublicationState === 'pending' ||
+      !this.ownsReloadExecution(execution, lease) ||
+      this.reloadShellOwner === undefined ||
+      lease === undefined
+    ) {
+      return;
+    }
+    try {
+      this.reloadShellOwner.releaseExecution(lease, execution);
+    } catch (error) {
+      if (
+        typeof error !== 'object' ||
+        error === null ||
+        Reflect.get(error, 'code') !== 'pi_bg_reload_owner_stale_claim'
+      ) {
+        this.logger.error(
+          `[background-tasks] failed to release reload shell execution ${task.id}:`,
+          error,
+        );
+      }
+    }
+  }
+
+  private terminalPublicationAbandonSignal(task: BgTask): TerminalPublicationAbandonSignal {
+    const existing = this.terminalPublicationAbandonSignals.get(task);
+    if (existing !== undefined) return existing;
+    let resolveSignal: (reason: TerminalPublicationAbandonReason) => void = () => {};
+    const promise = new Promise<TerminalPublicationAbandonReason>((resolve) => {
+      resolveSignal = resolve;
+    });
+    const signal = { promise, resolve: resolveSignal };
+    this.terminalPublicationAbandonSignals.set(task, signal);
+    return signal;
+  }
+
+  private publishTerminal(task: BgTask): void {
+    if (task.reloadExecution !== undefined && this.tasks.get(task.id) !== task) return;
+    if (task.terminalPublicationState !== 'pending' || task.terminalPublishInFlight) return;
+    if (this.terminalPublicationClosed) {
+      this.abandonTerminalPublication(
+        task,
+        this.terminalPublicationCloseReason ?? 'registry_shutdown',
+      );
+      return;
+    }
+    task.terminalPublishInFlight = true;
+    if (task.terminalPublicationGate === undefined) {
+      this.tryPublishTerminalNow(task);
+      return;
+    }
+    void this.publishTerminalWhenReady(task);
+  }
+
+  private async publishTerminalWhenReady(task: BgTask): Promise<void> {
+    const outcome = await this.waitForTerminalPublicationGate(task);
+    if (task.reloadExecution !== undefined && this.tasks.get(task.id) !== task) {
+      task.terminalPublishInFlight = false;
+      return;
+    }
+    if (outcome.kind === 'closed') {
+      this.abandonTerminalPublication(task, outcome.reason);
+      return;
+    }
+    if (outcome.kind === 'rejected') {
+      this.abandonTerminalPublication(task, 'gate_rejected', outcome.error);
+      return;
+    }
+    // The gate and registry closure can settle in the same microtask turn.
+    // Re-check after the await so a late gate cannot publish into a disposed
+    // activation or revive a task already abandoned by shutdown.
+    if (this.terminalPublicationClosed || task.terminalPublicationState !== 'pending') {
+      this.abandonTerminalPublication(
+        task,
+        this.terminalPublicationCloseReason ?? 'registry_shutdown',
+      );
+      return;
+    }
+    this.tryPublishTerminalNow(task);
+  }
+
+  private async waitForTerminalPublicationGate(
+    task: BgTask,
+  ): Promise<TerminalPublicationGateOutcome> {
+    if (this.terminalPublicationClosed) {
+      return {
+        kind: 'closed',
+        reason: this.terminalPublicationCloseReason ?? 'registry_shutdown',
+      };
+    }
+    if (task.terminalPublicationState === 'abandoned') {
+      if (task.terminalPublicationAbandonReason === 'gate_rejected') {
+        return { kind: 'rejected', error: new Error('terminal publication gate rejected') };
+      }
+      return {
+        kind: 'closed',
+        reason: task.terminalPublicationAbandonReason ?? 'registry_shutdown',
+      };
+    }
+    const gate = task.terminalPublicationGate;
+    if (gate === undefined) return { kind: 'released' };
+
+    const gateOutcome: Promise<TerminalPublicationGateOutcome> = gate.then(
+      () => ({ kind: 'released' }),
+      (error: unknown) => ({ kind: 'rejected', error }),
+    );
+    const closureOutcome: Promise<TerminalPublicationGateOutcome> =
+      this.terminalPublicationClosedSignal.then((reason) => ({ kind: 'closed', reason }));
+    const abandonmentOutcome: Promise<TerminalPublicationGateOutcome> =
+      this.terminalPublicationAbandonSignal(task).promise.then((reason) => ({
+        kind: 'closed',
+        reason,
+      }));
+    const outcome = await Promise.race([gateOutcome, closureOutcome, abandonmentOutcome]);
+
+    // Closure wins if it happened before this continuation resumed, regardless
+    // of which promise queued its reaction first.
+    if (this.terminalPublicationClosed) {
+      return {
+        kind: 'closed',
+        reason: this.terminalPublicationCloseReason ?? 'registry_shutdown',
+      };
+    }
+    return outcome;
+  }
+
+  private tryPublishTerminalNow(task: BgTask): void {
+    if (task.reloadExecution !== undefined && this.tasks.get(task.id) !== task) {
+      task.terminalPublishInFlight = false;
+      return;
+    }
+    if (task.terminalPublicationState !== 'pending') {
+      task.terminalPublishInFlight = false;
+      return;
+    }
+    if (this.terminalPublicationClosed) {
+      task.terminalPublishInFlight = false;
+      this.abandonTerminalPublication(
+        task,
+        this.terminalPublicationCloseReason ?? 'registry_shutdown',
+      );
+      this.pruneOldTasks();
+      return;
+    }
+
+    task.terminalPublishAttempts += 1;
+    task.terminalEmitInFlight = true;
+    let emitFailed = false;
+    let emitError: unknown;
+    try {
+      this.publishTerminalSnapshot(snapshot(task));
+    } catch (error) {
+      emitFailed = true;
+      emitError = error;
+    }
+    task.terminalEmitInFlight = false;
+    task.terminalPublishInFlight = false;
+
+    if (emitFailed) {
+      const execution = task.reloadExecution;
+      if (execution !== undefined && !this.ownsReloadExecution(execution, this.reloadShellLease)) {
+        // The emitter synchronously detached this task into a reload handoff
+        // before throwing. Attempt 1 is consumed, but only the fresh owner may
+        // retry or decide abandonment on the shared publication ledger.
+        return;
+      }
+      this.handleTerminalPublishFailure(task, emitError);
+    } else {
+      this.markTerminalPublicationDelivered(task);
+    }
+    this.pruneOldTasks();
+  }
+
+  private markTerminalPublicationDelivered(task: BgTask): void {
+    if (task.terminalPublishRetryHandle !== undefined) {
+      clearTimeout(task.terminalPublishRetryHandle);
+      task.terminalPublishRetryHandle = undefined;
+    }
+    task.terminalPublicationGate = undefined;
+    task.terminalEmitInFlight = false;
+    task.terminalPublishInFlight = false;
+    task.terminalPublicationState = 'delivered';
+    delete task.terminalPublicationAbandonReason;
+    task.terminalPublished = true;
+    this.maybeReleaseReloadExecution(task);
+  }
+
+  private abandonTerminalPublication(
+    task: BgTask,
+    reason: TerminalPublicationAbandonReason,
+    error?: unknown,
+    log = true,
+  ): void {
+    if (task.terminalPublishRetryHandle !== undefined) {
+      clearTimeout(task.terminalPublishRetryHandle);
+      task.terminalPublishRetryHandle = undefined;
+    }
+    task.terminalPublicationGate = undefined;
+    if (task.terminalEmitInFlight !== true) task.terminalPublishInFlight = false;
+    if (task.terminalPublicationState === 'delivered') return;
+    if (task.terminalPublicationState === 'abandoned') return;
+
+    task.terminalPublicationState = 'abandoned';
+    task.terminalPublicationAbandonReason = reason;
+    task.terminalPublished = false;
+    this.terminalPublicationAbandonSignal(task).resolve(reason);
+    if (log) {
+      const detail = error === undefined ? '' : `: ${this.terminalPublicationError(error)}`;
+      this.logger.error(
+        `[background-tasks] terminal publication abandoned for ${task.id} (${reason}) after ${String(task.terminalPublishAttempts)}/${String(TERMINAL_PUBLICATION_MAX_ATTEMPTS)} emit attempts${detail}`,
+      );
+    }
+    this.maybeReleaseReloadExecution(task);
+  }
+
+  private terminalPublicationError(error: unknown): string {
+    const compact = BackgroundTaskRegistry.errorMessage(error).replace(/\s+/gu, ' ').trim();
+    if (compact.length <= TERMINAL_PUBLICATION_DIAGNOSTIC_CHARS) return compact;
+    return `${compact.slice(0, TERMINAL_PUBLICATION_DIAGNOSTIC_CHARS - 1)}…`;
+  }
+
+  private handleTerminalPublishFailure(task: BgTask, error: unknown): void {
+    task.terminalPublishInFlight = false;
+    if (task.terminalPublicationState !== 'pending') return;
+    if (error instanceof BackgroundTaskExtensionServiceClosedError) {
+      this.closeTerminalPublication('publisher_closed');
+      return;
+    }
+    if (this.terminalPublicationClosed) {
+      this.abandonTerminalPublication(
+        task,
+        this.terminalPublicationCloseReason ?? 'registry_shutdown',
+        error,
+      );
+      this.pruneOldTasks();
+      return;
+    }
+    if (task.terminalPublishAttempts >= TERMINAL_PUBLICATION_MAX_ATTEMPTS) {
+      this.abandonTerminalPublication(task, 'retry_exhausted', error);
+      this.pruneOldTasks();
+      return;
+    }
+
+    this.logger.error(
+      `[background-tasks] terminal publication failed for ${task.id} (attempt ${String(task.terminalPublishAttempts)}/${String(TERMINAL_PUBLICATION_MAX_ATTEMPTS)}; retrying): ${this.terminalPublicationError(error)}`,
+    );
+    if (task.terminalPublishRetryHandle !== undefined) return;
+    task.terminalPublishRetryHandle = setTimeout(() => {
+      task.terminalPublishRetryHandle = undefined;
+      if (
+        this.terminalPublicationClosed ||
+        task.terminalPublicationState !== 'pending' ||
+        (task.reloadExecution !== undefined && this.tasks.get(task.id) !== task)
+      )
+        return;
+      this.publishTerminal(task);
+    }, TERMINAL_PUBLICATION_RETRY_MS);
+    task.terminalPublishRetryHandle.unref();
+  }
+
+  private notifyCompletion(task: BgTask): void {
+    if (!task.notifyOnCompletion || task.notified || this.shuttingDown) return;
+    task.notified = true;
+    const exit =
+      task.exitCode === undefined ? '' : `\n  <exit-code>${String(task.exitCode)}</exit-code>`;
+    const error = task.error ? `\n  <error>${escapeXml(task.error)}</error>` : '';
+    const taskName = taskDisplayName(task);
+    const guidance =
+      'Terminal state and output metadata are durable. Do not call bg_status to reconfirm; use bg_logs only if output is needed.';
+    const content = [
+      '<background-task-notification>',
+      `  <task-id>${task.id}</task-id>`,
+      `  <task-name>${escapeXml(taskName)}</task-name>`,
+      `  <status>${task.status}</status>`,
+      exit,
+      error,
+      `  <output-file>${escapeXml(task.outputPath)}</output-file>`,
+      `  <summary>${escapeXml(`Background task ${JSON.stringify(taskName)} ${task.status}`)}</summary>`,
+      `  <guidance>${escapeXml(guidance)}</guidance>`,
+      '</background-task-notification>',
+    ]
+      .filter(Boolean)
+      .join('\n');
+
+    try {
+      this.sendCompletionNotification(
+        {
+          customType: 'background-task-notification',
+          content,
+          display: true,
+          details: snapshot(task),
+        },
+        { deliverAs: 'followUp', triggerTurn: task.triggerOnCompletion },
+      );
+    } catch (error) {
+      task.notified = false;
+      throw new Error(
+        `Failed to send background task notification for ${task.id}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  private async finalizeTask(
+    task: BgTask,
+    status: TaskStatus,
+    exitCode: number | null,
+    signal?: string | null,
+    error?: string,
+  ): Promise<void> {
+    if (task.finalized) return;
+    task.finalized = true;
+    if (task.timeoutHandle) clearTimeout(task.timeoutHandle);
+    if (this.platform === 'win32') this.clearKillEscalationTimer(task);
+    let finalStatus = status;
+    let finalError = error;
+    const posixForceFailure = await this.awaitPosixProcessGroupBeforeTerminal(task);
+    if (posixForceFailure !== undefined) {
+      finalStatus = 'failed';
+      finalError = BackgroundTaskRegistry.appendTaskError(finalError, posixForceFailure.message);
+    }
+    const windowsForceFailure = await this.awaitWindowsForceBeforeTerminal(task);
+    if (windowsForceFailure !== undefined) {
+      finalStatus = 'failed';
+      finalError = BackgroundTaskRegistry.appendTaskError(finalError, windowsForceFailure.message);
+    }
+    task.exitCode = exitCode;
+    task.signal = signal ?? null;
+
+    try {
+      if (task.stream && !task.stream.destroyed) await closeAndFsyncOutputStream(task.stream);
+    } catch (finalizeError) {
+      finalStatus = 'failed';
+      const message =
+        finalizeError instanceof Error ? finalizeError.message : String(finalizeError);
+      finalError = finalError
+        ? `${finalError}; final output durability failed: ${message}`
+        : `Final output durability failed: ${message}`;
+    }
+
+    task.endTime = this.now();
+    if (finalError) task.error = finalError;
+    try {
+      await this.writeMetadataSnapshot(task, { ...snapshot(task), status: finalStatus });
+      task.status = finalStatus;
+    } catch (metadataError) {
+      finalStatus = 'failed';
+      task.status = 'failed';
+      task.error = `Terminal metadata write failed: ${metadataError instanceof Error ? metadataError.message : String(metadataError)}`;
+      this.logger.error(
+        `[background-tasks] failed to write metadata for ${task.id}:`,
+        metadataError,
+      );
+      await this.writeMetadata(task).catch((retryError: unknown) => {
+        this.logger.error(
+          `[background-tasks] failed to write failed terminal metadata for ${task.id}:`,
+          retryError,
+        );
+      });
+    }
+
+    for (const waiter of task.waiters.splice(0)) waiter();
+    this.publishTerminal(task);
+    const deliveryGate = await this.waitForTerminalPublicationGate(task);
+    if (deliveryGate.kind === 'rejected') {
+      this.logger.error(
+        `[background-tasks] completion delivery gate failed for ${task.id}: ${this.terminalPublicationError(deliveryGate.error)}`,
+      );
+    } else {
+      // EventBus disposal abandons only EventBus publication. Notification truth
+      // remains independent; notifyCompletion itself suppresses session shutdown.
+      try {
+        this.notifyCompletion(task);
+      } catch (notificationError) {
+        this.logger.error(
+          `[background-tasks] notification failed for ${task.id}:`,
+          notificationError,
+        );
+      }
+    }
+    try {
+      await this.writeMetadata(task);
+    } catch (metadataError) {
+      this.logger.error(
+        `[background-tasks] failed to update notification metadata for ${task.id}:`,
+        metadataError,
+      );
+    }
+    this.pruneOldTasks();
+  }
+
+  private pruneOldTasks(): void {
+    if (this.tasks.size <= this.maxRecentTasks) return;
+    const removable = [...this.tasks.values()]
+      .filter((task) => task.status !== 'running' && task.terminalEmitInFlight !== true)
+      .sort((a, b) => (a.endTime ?? a.startTime) - (b.endTime ?? b.startTime));
+    while (this.tasks.size > this.maxRecentTasks && removable.length > 0) {
+      const task = removable.shift();
+      if (task === undefined) continue;
+      if (task.terminalPublicationState === 'pending') {
+        this.abandonTerminalPublication(task, 'retention_limit');
+      }
+      this.tasks.delete(task.id);
+    }
+  }
+}