pi-background-tasks 1.0.7 → 2.0.0

package/src/core/fusion/result-package.ts

@@ -0,0 +1,385 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256Buffer } from '../attested-pi-run.js';
+import { parseJsonText, type JsonObject } from '../common.js';
+import {
+  FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
+  FUSION_MANIFEST_SCHEMA_VERSION,
+  FUSION_RESULT_SCHEMA_VERSION,
+  FusionError,
+  type FusionArtifactRef,
+  type FusionResultDetails,
+  type FusionRunResult,
+  type FusionUsage,
+  type FusionWorkflowId,
+} from './types.js';
+
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+
+function isRecord(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function fail(message: string, artifactDir: string): never {
+  throw new FusionError(`fusion committed result invalid: ${message}`, {
+    code: 'artifact_error',
+    childCreated: true,
+    artifactDir,
+  });
+}
+
+function assertOnlyKeys(
+  value: JsonObject,
+  allowed: readonly string[],
+  label: string,
+  artifactDir: string,
+): void {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0)
+    fail(`${label} contains unexpected keys: ${unexpected.join(', ')}`, artifactDir);
+}
+
+function artifactRef(value: unknown, label: string, artifactDir: string): FusionArtifactRef {
+  if (!isRecord(value)) fail(`${label} must be an object`, artifactDir);
+  assertOnlyKeys(value, ['path', 'byte_length', 'sha256'], label, artifactDir);
+  const path = value['path'];
+  const byteLength = value['byte_length'];
+  const sha256 = value['sha256'];
+  if (typeof path !== 'string' || path.length === 0 || path.includes('/') || path.includes('\\')) {
+    fail(`${label}.path is invalid`, artifactDir);
+  }
+  if (!Number.isSafeInteger(byteLength) || Number(byteLength) < 0) {
+    fail(`${label}.byte_length is invalid`, artifactDir);
+  }
+  if (typeof sha256 !== 'string' || !SHA256_PATTERN.test(sha256)) {
+    fail(`${label}.sha256 is invalid`, artifactDir);
+  }
+  return { path, byte_length: Number(byteLength), sha256 };
+}
+
+function usage(value: unknown, artifactDir: string): FusionUsage {
+  if (!isRecord(value)) fail('details.usage must be an object', artifactDir);
+  assertOnlyKeys(
+    value,
+    ['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens', 'cost'],
+    'details.usage',
+    artifactDir,
+  );
+  const cost = value['cost'];
+  if (!isRecord(cost)) fail('details.usage.cost must be an object', artifactDir);
+  assertOnlyKeys(
+    cost,
+    ['input', 'output', 'cacheRead', 'cacheWrite', 'total'],
+    'details.usage.cost',
+    artifactDir,
+  );
+  const finiteNonnegative = (entry: unknown, label: string): number => {
+    if (typeof entry !== 'number' || !Number.isFinite(entry) || entry < 0)
+      fail(`${label} is invalid`, artifactDir);
+    return entry;
+  };
+  return {
+    input: finiteNonnegative(value['input'], 'details.usage.input'),
+    output: finiteNonnegative(value['output'], 'details.usage.output'),
+    cacheRead: finiteNonnegative(value['cacheRead'], 'details.usage.cacheRead'),
+    cacheWrite: finiteNonnegative(value['cacheWrite'], 'details.usage.cacheWrite'),
+    totalTokens: finiteNonnegative(value['totalTokens'], 'details.usage.totalTokens'),
+    cost: {
+      input: finiteNonnegative(cost['input'], 'details.usage.cost.input'),
+      output: finiteNonnegative(cost['output'], 'details.usage.cost.output'),
+      cacheRead: finiteNonnegative(cost['cacheRead'], 'details.usage.cost.cacheRead'),
+      cacheWrite: finiteNonnegative(cost['cacheWrite'], 'details.usage.cost.cacheWrite'),
+      total: finiteNonnegative(cost['total'], 'details.usage.cost.total'),
+    },
+  };
+}
+
+function resultDetails(
+  value: unknown,
+  expected: { runId: string; workflow: FusionWorkflowId; artifactDir: string },
+): FusionResultDetails {
+  if (!isRecord(value)) fail('details must be an object', expected.artifactDir);
+  assertOnlyKeys(
+    value,
+    [
+      'schema_version',
+      'run_id',
+      'workflow',
+      'source',
+      'status',
+      'context',
+      'tool_policy',
+      'artifact_dir',
+      'models',
+      'evaluator_attempts',
+      'usage',
+      'budget',
+    ],
+    'details',
+    expected.artifactDir,
+  );
+  if (value['schema_version'] !== FUSION_RESULT_SCHEMA_VERSION)
+    fail('details schema version mismatch', expected.artifactDir);
+  if (value['run_id'] !== expected.runId) fail('details run id mismatch', expected.artifactDir);
+  if (value['workflow'] !== expected.workflow)
+    fail('details workflow mismatch', expected.artifactDir);
+  if (value['source'] !== 'command' && value['source'] !== 'tool')
+    fail('details source is invalid', expected.artifactDir);
+  if (value['status'] !== 'completed')
+    fail('details status is not completed', expected.artifactDir);
+  if (value['artifact_dir'] !== expected.artifactDir)
+    fail('details artifact directory mismatch', expected.artifactDir);
+  const context = value['context'];
+  const toolPolicy = value['tool_policy'];
+  const models = value['models'];
+  const budget = value['budget'];
+  if (!isRecord(context) || !isRecord(toolPolicy) || !isRecord(models) || !isRecord(budget)) {
+    fail('details nested contract is malformed', expected.artifactDir);
+  }
+  assertOnlyKeys(context, ['kind', 'policy_id'], 'details.context', expected.artifactDir);
+  if (
+    (context['kind'] !== 'session_projection' && context['kind'] !== 'clean_task') ||
+    typeof context['policy_id'] !== 'string'
+  ) {
+    fail('details.context is invalid', expected.artifactDir);
+  }
+  assertOnlyKeys(
+    toolPolicy,
+    ['candidate_tools', 'evaluation_tools', 'merge_tools'],
+    'details.tool_policy',
+    expected.artifactDir,
+  );
+  const stringArray = (entry: unknown): entry is string[] =>
+    Array.isArray(entry) && entry.every((item) => typeof item === 'string');
+  if (
+    !stringArray(toolPolicy['candidate_tools']) ||
+    !Array.isArray(toolPolicy['evaluation_tools']) ||
+    toolPolicy['evaluation_tools'].length !== 0 ||
+    !Array.isArray(toolPolicy['merge_tools']) ||
+    toolPolicy['merge_tools'].length !== 0
+  ) {
+    fail('details.tool_policy is invalid', expected.artifactDir);
+  }
+  assertOnlyKeys(
+    models,
+    ['candidates', 'evaluator', 'merger', 'thinking_level'],
+    'details.models',
+    expected.artifactDir,
+  );
+  if (
+    !stringArray(models['candidates']) ||
+    models['candidates'].length !== 3 ||
+    typeof models['evaluator'] !== 'string' ||
+    typeof models['merger'] !== 'string' ||
+    typeof models['thinking_level'] !== 'string'
+  ) {
+    fail('details.models is invalid', expected.artifactDir);
+  }
+  assertOnlyKeys(
+    budget,
+    [
+      'policy_id',
+      'calibration_version',
+      'route_table',
+      'rate_sources',
+      'unknown_provider_warnings',
+      'calibration_warnings',
+    ],
+    'details.budget',
+    expected.artifactDir,
+  );
+  if (
+    typeof budget['policy_id'] !== 'string' ||
+    typeof budget['calibration_version'] !== 'string' ||
+    !Array.isArray(budget['route_table']) ||
+    !Array.isArray(budget['rate_sources']) ||
+    !stringArray(budget['unknown_provider_warnings']) ||
+    !Array.isArray(budget['calibration_warnings'])
+  ) {
+    fail('details.budget is invalid', expected.artifactDir);
+  }
+  if (
+    !Number.isSafeInteger(value['evaluator_attempts']) ||
+    ![1, 2].includes(Number(value['evaluator_attempts']))
+  ) {
+    fail('details evaluator_attempts is invalid', expected.artifactDir);
+  }
+  const checkedUsage = usage(value['usage'], expected.artifactDir);
+  const candidates = models['candidates'];
+  if (!stringArray(candidates) || candidates.length !== 3)
+    fail('details.models candidates are invalid', expected.artifactDir);
+  const candidate1 = candidates[0];
+  const candidate2 = candidates[1];
+  const candidate3 = candidates[2];
+  if (candidate1 === undefined || candidate2 === undefined || candidate3 === undefined) {
+    fail('details.models candidates are incomplete', expected.artifactDir);
+  }
+  const source = value['source'];
+  const contextKind = context['kind'];
+  return {
+    schema_version: FUSION_RESULT_SCHEMA_VERSION,
+    run_id: expected.runId,
+    workflow: expected.workflow,
+    source,
+    status: 'completed',
+    context: { kind: contextKind, policy_id: context['policy_id'] },
+    tool_policy: {
+      candidate_tools: [...toolPolicy['candidate_tools']],
+      evaluation_tools: [],
+      merge_tools: [],
+    },
+    artifact_dir: expected.artifactDir,
+    models: {
+      candidates: [candidate1, candidate2, candidate3],
+      evaluator: models['evaluator'],
+      merger: models['merger'],
+      thinking_level: models['thinking_level'],
+    },
+    evaluator_attempts: Number(value['evaluator_attempts']),
+    usage: checkedUsage,
+    budget: {
+      policy_id: budget['policy_id'],
+      calibration_version: budget['calibration_version'],
+      route_table: budget['route_table'] as FusionResultDetails['budget']['route_table'],
+      rate_sources: budget['rate_sources'] as FusionResultDetails['budget']['rate_sources'],
+      unknown_provider_warnings: [...budget['unknown_provider_warnings']],
+      calibration_warnings: budget[
+        'calibration_warnings'
+      ] as FusionResultDetails['budget']['calibration_warnings'],
+    },
+  };
+}
+
+function sameRef(left: FusionArtifactRef, right: FusionArtifactRef): boolean {
+  return (
+    left.path === right.path &&
+    left.byte_length === right.byte_length &&
+    left.sha256 === right.sha256
+  );
+}
+
+async function readUtf8(
+  path: string,
+  label: string,
+  artifactDir: string,
+): Promise<{ bytes: Buffer; text: string }> {
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(path);
+  } catch (error) {
+    fail(
+      `${label} is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+      artifactDir,
+    );
+  }
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    fail(`${label} is not well-formed UTF-8`, artifactDir);
+  }
+  return { bytes, text };
+}
+
+export interface ReadFusionCommittedResultOptions {
+  artifactDirAbs: string;
+  artifactDir: string;
+  runId: string;
+  workflow: FusionWorkflowId;
+}
+
+/** Verify the manifest-bound Fusion commit before returning merged bytes. */
+export async function readFusionCommittedResult(
+  options: ReadFusionCommittedResultOptions,
+): Promise<FusionRunResult> {
+  const manifestFile = await readUtf8(
+    join(options.artifactDirAbs, 'manifest.json'),
+    'manifest.json',
+    options.artifactDir,
+  );
+  let manifestValue: unknown;
+  try {
+    manifestValue = parseJsonText(manifestFile.text);
+  } catch (error) {
+    fail(
+      `manifest.json is invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      options.artifactDir,
+    );
+  }
+  if (!isRecord(manifestValue)) fail('manifest.json must be an object', options.artifactDir);
+  if (manifestValue['schema_version'] !== FUSION_MANIFEST_SCHEMA_VERSION)
+    fail('manifest schema version mismatch', options.artifactDir);
+  if (manifestValue['run_id'] !== options.runId || manifestValue['workflow'] !== options.workflow)
+    fail('manifest identity mismatch', options.artifactDir);
+  if (manifestValue['state'] !== 'completed')
+    fail('manifest is not committed', options.artifactDir);
+  const artifacts = manifestValue['artifacts'];
+  if (!isRecord(artifacts)) fail('manifest artifacts map is invalid', options.artifactDir);
+  const manifestMerged = artifactRef(
+    artifacts['merged.md'],
+    'manifest artifacts merged.md',
+    options.artifactDir,
+  );
+  const manifestResult = artifactRef(
+    artifacts['result.json'],
+    'manifest artifacts result.json',
+    options.artifactDir,
+  );
+  if (manifestMerged.path !== 'merged.md' || manifestResult.path !== 'result.json')
+    fail('manifest fixed artifact paths are invalid', options.artifactDir);
+
+  const resultFile = await readUtf8(
+    join(options.artifactDirAbs, 'result.json'),
+    'result.json',
+    options.artifactDir,
+  );
+  if (
+    resultFile.bytes.length !== manifestResult.byte_length ||
+    sha256Buffer(resultFile.bytes) !== manifestResult.sha256
+  ) {
+    fail('result.json does not match its manifest hash and length', options.artifactDir);
+  }
+  let resultValue: unknown;
+  try {
+    resultValue = parseJsonText(resultFile.text);
+  } catch (error) {
+    fail(
+      `result.json is invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      options.artifactDir,
+    );
+  }
+  if (!isRecord(resultValue)) fail('result.json must be an object', options.artifactDir);
+  assertOnlyKeys(
+    resultValue,
+    ['schema_version', 'run_id', 'merged', 'details'],
+    'result.json',
+    options.artifactDir,
+  );
+  if (
+    resultValue['schema_version'] !== FUSION_COMMITTED_RESULT_SCHEMA_VERSION ||
+    resultValue['run_id'] !== options.runId
+  ) {
+    fail('result.json identity mismatch', options.artifactDir);
+  }
+  const committedMerged = artifactRef(
+    resultValue['merged'],
+    'result.json merged',
+    options.artifactDir,
+  );
+  if (!sameRef(committedMerged, manifestMerged))
+    fail('result.json merged reference does not match manifest', options.artifactDir);
+  const details = resultDetails(resultValue['details'], options);
+
+  const mergedFile = await readUtf8(
+    join(options.artifactDirAbs, 'merged.md'),
+    'merged.md',
+    options.artifactDir,
+  );
+  if (
+    mergedFile.bytes.length !== committedMerged.byte_length ||
+    sha256Buffer(mergedFile.bytes) !== committedMerged.sha256
+  ) {
+    fail('merged.md does not match its committed hash and length', options.artifactDir);
+  }
+  return { mergedText: mergedFile.text, details };
+}

package/src/core/fusion/types.ts

@@ -18,6 +18,8 @@ export const FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION =
   'pi-background-tasks.fusion-validation-candidate.v1';
 export const FUSION_LEGACY_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v4';
 export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v5';
+export const FUSION_COMMITTED_RESULT_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-committed-result.v1';
 export const FUSION_LEGACY_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v3';
 export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v4';
 export const FUSION_CONTEXT_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.fusion-context-ledger.v2';
@@ -553,6 +555,13 @@ export interface FusionResultBudgetDetails {
   calibration_warnings: readonly FusionCalibrationViolation[];
 }
 
+export interface FusionCommittedResultV1 {
+  schema_version: typeof FUSION_COMMITTED_RESULT_SCHEMA_VERSION;
+  run_id: string;
+  merged: FusionArtifactRef;
+  details: FusionResultDetails;
+}
+
 export interface FusionResultDetails {
   schema_version: typeof FUSION_RESULT_SCHEMA_VERSION;
   run_id: string;

package/src/core/registry.ts

@@ -28,6 +28,7 @@ import {
   type KillKind,
   type StartAttestedPiTaskOptions,
   type StartDelegateTaskOptions,
+  type StartManagedTaskOptions,
   type StartTaskOptions,
   type TaskContextUsage,
   type TaskStatus,
@@ -740,11 +741,13 @@ export class BackgroundTaskRegistry {
     this.killProcess = options.killProcess ?? process.kill.bind(process);
     this.platform = options.platform ?? process.platform;
     this.env = options.env ?? process.env;
-    this.killTree = options.killTree ?? ((pid, phase, signal) => {
-      const taskkillOptions: WindowsTaskkillOptions =
-        signal === undefined ? { env: this.env } : { env: this.env, signal };
-      return runWindowsTaskkill(pid, phase, taskkillOptions);
-    });
+    this.killTree =
+      options.killTree ??
+      ((pid, phase, signal) => {
+        const taskkillOptions: WindowsTaskkillOptions =
+          signal === undefined ? { env: this.env } : { env: this.env, signal };
+        return runWindowsTaskkill(pid, phase, taskkillOptions);
+      });
     this.makeTaskIdFn = options.makeTaskId ?? defaultTaskId;
     this.now = options.now ?? Date.now;
     this.maxOutputBytes = options.maxOutputBytes ?? MAX_OUTPUT_BYTES;
@@ -869,7 +872,8 @@ export class BackgroundTaskRegistry {
       let commandToSpawn = normalizedCommand;
       if (piTelemetryRequested) {
         if (baseInvocation.dialect === 'posix') {
-          if (piTelemetryLaunch === undefined) throw new Error('Pi telemetry launch spec was not resolved');
+          if (piTelemetryLaunch === undefined)
+            throw new Error('Pi telemetry launch spec was not resolved');
           const wrapperAbsPath = join(dir.abs, `${id}.pi-telemetry-wrapper.cjs`);
           await writeFile(
             wrapperAbsPath,
@@ -962,6 +966,128 @@ export class BackgroundTaskRegistry {
     }
   }
 
+  /**
+   * Track an in-process asynchronous workflow through the same durable task,
+   * notification, status, log, and cancellation surfaces as child processes.
+   * The supplied completion promise must own all workflow cleanup before it
+   * settles; terminal publication happens only after that settlement.
+   */
+  async startManagedTask(
+    ctx: BackgroundTaskContext,
+    request: StartManagedTaskOptions,
+  ): Promise<BgTask> {
+    if (this.shuttingDown)
+      throw new Error('Cannot start a managed background task while Pi is shutting down');
+    if (!/^[a-zA-Z0-9_.-]+$/u.test(request.id))
+      throw new Error(`Managed background task id is invalid: ${request.id}`);
+    if (this.tasks.has(request.id))
+      throw new Error(`Background task id already exists: ${request.id}`);
+
+    const dir = await this.ensureRuntimeDir(ctx);
+    const outputAbsPath = join(dir.abs, `${request.id}.output`);
+    const metadataAbsPath = join(dir.abs, `${request.id}.json`);
+    const outputPath = join(dir.display, `${request.id}.output`);
+    const task: BgTask = {
+      id: request.id,
+      name: normalizeTaskName(request.name) ?? 'Managed background task',
+      command: request.command,
+      description: request.description,
+      status: 'running',
+      outputPath,
+      outputAbsPath,
+      metadataAbsPath,
+      cwd: ctx.cwd,
+      startTime: this.now(),
+      exitCode: undefined,
+      pid: undefined,
+      bytesWritten: 0,
+      isAgent: request.isAgent,
+      notified: false,
+      notifyOnCompletion: request.notifyOnCompletion,
+      triggerOnCompletion: request.triggerOnCompletion,
+      fusion: request.fusion,
+      managedCancel: request.cancel,
+      managedStopWaitMs: request.stopWaitMs,
+      terminalPublicationGate: request.terminalPublicationGate,
+      waiters: [],
+    };
+    this.tasks.set(task.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.managedCancelRequested) {
+        task.managedCancelRequested = true;
+        try {
+          request.cancel();
+        } catch (cancelError) {
+          task.error = `${task.error}; cancellation failed: ${BackgroundTaskRegistry.errorMessage(cancelError)}`;
+        }
+      }
+    });
+
+    try {
+      await this.writeMetadata(task);
+      this.onChange();
+    } catch (error) {
+      this.tasks.delete(task.id);
+      if (!stream.destroyed) stream.destroy();
+      try {
+        request.cancel();
+      } catch (cancelError) {
+        this.logger.error(
+          `[background-tasks] managed task cancellation after metadata failure also failed for ${task.id}:`,
+          cancelError,
+        );
+      }
+      throw new Error(
+        `Failed to register managed background task: ${BackgroundTaskRegistry.errorMessage(error)}`,
+      );
+    }
+
+    void request.completion
+      .then(
+        () => this.finalizeTask(task, 'completed', 0),
+        (error: unknown) => {
+          const message = BackgroundTaskRegistry.errorMessage(error);
+          const killed = task.killKind === 'user' || task.killKind === 'shutdown';
+          return this.finalizeTask(task, killed ? 'killed' : 'failed', null, undefined, message);
+        },
+      )
+      .catch((error: unknown) => {
+        this.logger.error(
+          `[background-tasks] managed task finalization failed for ${task.id}:`,
+          error,
+        );
+      });
+    return task;
+  }
+
+  async updateManagedTask(task: BgTask, state: string, line?: string): Promise<void> {
+    if (task.status !== 'running' || task.fusion === undefined) return;
+    task.fusion.state = state;
+    if (line !== undefined && line.length > 0) this.writeNotice(task, `${line}\n`);
+    await this.writeMetadata(task);
+    this.onChange();
+  }
+
+  /** Claim deferred Fusion usage exactly once before returning it from bg_result. */
+  async claimFusionUsage(task: BgTask): Promise<boolean> {
+    if (task.fusion === undefined) throw new Error(`Task ${task.id} is not a Fusion task`);
+    let claimed = false;
+    const write = async () => {
+      if (!task.fusion || task.fusion.usageDelivered) return;
+      task.fusion.usageDelivered = true;
+      await writeJsonAtomic(task.metadataAbsPath, snapshot(task));
+      claimed = true;
+    };
+    const previous = task.metadataWriteChain ?? Promise.resolve();
+    const next = previous.then(write, write);
+    task.metadataWriteChain = next.catch(() => undefined);
+    await next;
+    return claimed;
+  }
+
   /**
    * Start a prepared delegate child.
    *
@@ -1420,15 +1546,16 @@ export class BackgroundTaskRegistry {
     task.killKind = kind;
     if (reason) task.error = reason;
     this.requestKill(task, 'SIGTERM');
+    const stopWaitMs = task.managedStopWaitMs ?? this.stopWaitMs;
     const stopped =
-      this.platform === 'win32'
-        ? await this.waitForEndOrWindowsForceFailure(task, this.stopWaitMs)
-        : await this.waitForEnd(task, this.stopWaitMs);
+      this.platform === 'win32' && task.managedCancel === undefined
+        ? await this.waitForEndOrWindowsForceFailure(task, stopWaitMs)
+        : await this.waitForEnd(task, stopWaitMs);
     const forceFailure = this.windowsKillStates.get(task)?.forceFailure;
     if (forceFailure !== undefined) throw forceFailure;
     if (!stopped) {
       throw new Error(
-        `Task ${task.id} did not exit within ${formatDuration(this.stopWaitMs)} after SIGTERM/SIGKILL`,
+        `Task ${task.id} did not exit within ${formatDuration(stopWaitMs)} after cancellation`,
       );
     }
     return task;
@@ -1880,7 +2007,10 @@ export class BackgroundTaskRegistry {
     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.logger.error(
+        `[background-tasks] Windows force tree termination failed for ${task.id}:`,
+        error,
+      );
     });
 
     this.clearKillEscalationTimer(task);
@@ -1922,7 +2052,11 @@ export class BackgroundTaskRegistry {
           resolveForceReady();
           return;
         }
-        const failure = this.makeWindowsForceFailure(task, pid, BackgroundTaskRegistry.errorMessage(error));
+        const failure = this.makeWindowsForceFailure(
+          task,
+          pid,
+          BackgroundTaskRegistry.errorMessage(error),
+        );
         this.recordWindowsForceFailure(task, failure);
         rejectForceReady(failure);
       },
@@ -1965,6 +2099,19 @@ export class BackgroundTaskRegistry {
     if (task.status !== 'running') {
       throw new Error(`Task ${task.id} is ${task.status}, not running`);
     }
+    if (task.managedCancel !== undefined) {
+      if (task.managedCancelRequested) return;
+      task.managedCancelRequested = true;
+      try {
+        task.managedCancel();
+      } catch (error) {
+        throw new Error(
+          `Could not cancel managed task ${task.id}: ${BackgroundTaskRegistry.errorMessage(error)}`,
+        );
+      }
+      task.killSignalSent = true;
+      return;
+    }
     if (!task.child) {
       throw new Error(`Task ${task.id} has no child process handle`);
     }
@@ -2145,6 +2292,12 @@ export class BackgroundTaskRegistry {
       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 =
+      task.fusion === undefined
+        ? 'Terminal state and output metadata are durable. Do not call bg_status to reconfirm; use bg_logs only if output is needed.'
+        : task.status === 'completed'
+          ? `Fusion result is durably committed at ${task.fusion.artifactDir}. Call bg_result({taskId:${JSON.stringify(task.id)}}) once to retrieve it; do not poll.`
+          : `Fusion ended ${task.status}. Inspect the preserved artifacts at ${task.fusion.artifactDir}; do not poll.`;
     const content = [
       '<background-task-notification>',
       `  <task-id>${task.id}</task-id>`,
@@ -2154,7 +2307,7 @@ export class BackgroundTaskRegistry {
       error,
       `  <output-file>${escapeXml(task.outputPath)}</output-file>`,
       `  <summary>${escapeXml(`Background task ${JSON.stringify(taskName)} ${task.status}`)}</summary>`,
-      '  <guidance>Terminal state and output metadata are durable. Do not call bg_status to reconfirm; use bg_logs only if output is needed.</guidance>',
+      `  <guidance>${escapeXml(guidance)}</guidance>`,
       '</background-task-notification>',
     ]
       .filter(Boolean)
@@ -2250,13 +2403,27 @@ export class BackgroundTaskRegistry {
     for (const waiter of task.waiters.splice(0)) waiter();
     this.onChange();
     this.publishTerminal(task);
-    try {
-      this.notifyCompletion(task);
-    } catch (notificationError) {
-      this.logger.error(
-        `[background-tasks] notification failed for ${task.id}:`,
-        notificationError,
-      );
+    let deliveryGateReady = true;
+    if (task.terminalPublicationGate !== undefined) {
+      try {
+        await task.terminalPublicationGate;
+      } catch (error) {
+        deliveryGateReady = false;
+        this.logger.error(
+          `[background-tasks] completion delivery gate failed for ${task.id}:`,
+          error,
+        );
+      }
+    }
+    if (deliveryGateReady) {
+      try {
+        this.notifyCompletion(task);
+      } catch (notificationError) {
+        this.logger.error(
+          `[background-tasks] notification failed for ${task.id}:`,
+          notificationError,
+        );
+      }
     }
     try {
       await this.writeMetadata(task);