pi-background-tasks 0.7.3 → 0.7.6

package/src/core/common.ts

@@ -1,5 +1,6 @@
 import { statSync, type WriteStream } from 'node:fs';
 import { open } from 'node:fs/promises';
+import { extname, isAbsolute, join, win32 } from 'node:path';
 import { DEFAULT_MAX_BYTES } from '@earendil-works/pi-coding-agent';
 import type { BackgroundTaskChildProcess } from './registry.js';
 
@@ -57,6 +58,7 @@ export interface BgTaskSnapshot {
   tokenUsage?: TaskTokenUsage | undefined;
   toolUsage?: TaskToolUsage | undefined;
   model?: string | undefined;
+  telemetryUnavailableReason?: string | undefined;
   attestationPath?: string | undefined;
 }
 
@@ -84,6 +86,7 @@ export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   timeoutHandle?: NodeJS.Timeout | undefined;
   killKind?: KillKind | undefined;
   killSignalSent?: boolean | undefined;
+  killEscalationTimer?: NodeJS.Timeout | undefined;
   capExceeded?: boolean | undefined;
   finalized?: boolean | undefined;
   terminalPublished?: boolean | undefined;
@@ -96,6 +99,7 @@ export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   telemetryWrapped?: boolean | undefined;
   /** Partial trailing stdout line held between chunks while reconstructing wrapped-agent control lines. */
   agentStdoutBuffer?: string | undefined;
+  telemetryUnavailableReason?: string | undefined;
   attestationPath?: string | undefined;
   attestedPi?: AttestedPiTaskFiles | undefined;
   metadataWriteChain?: Promise<void> | undefined;
@@ -524,20 +528,131 @@ export function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 
+export type ShellDialect = 'cmd' | 'posix';
+
+export interface ShellInvocation {
+  shell: string;
+  args: string[];
+  dialect: ShellDialect;
+  windowsVerbatimArguments: boolean;
+}
+
+export class ShellInvocationError extends Error {
+  readonly code = 'pi_bg_shell_invalid';
+
+  constructor(message: string) {
+    super(`pi_bg_shell_invalid: ${message}`);
+    this.name = 'ShellInvocationError';
+  }
+}
+
+type ShellCandidateResult =
+  | { readonly found: true }
+  | { readonly found: false; readonly diagnostic: string };
+
+function failShellInvocation(message: string): never {
+  throw new ShellInvocationError(message);
+}
+
+function shellErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isWindowsExecutablePath(path: string): boolean {
+  const extension = extname(path).toLowerCase();
+  return extension === '.exe' || extension === '.com';
+}
+
+function validateWindowsShellPath(path: string, label: string): string {
+  if (path.length === 0) failShellInvocation(`${label} is empty`);
+  if (!isAbsolute(path) && !win32.isAbsolute(path)) {
+    failShellInvocation(`${label} must be an absolute path`);
+  }
+  if (!isWindowsExecutablePath(path)) {
+    failShellInvocation(`${label} must point to a .exe or .com file`);
+  }
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(path);
+  } catch (error) {
+    failShellInvocation(`${label} stat failed: ${shellErrorMessage(error)}`);
+  }
+  if (!stats.isFile()) failShellInvocation(`${label} must point to a regular file`);
+  return path;
+}
+
+function inspectWindowsShellCandidate(path: string): ShellCandidateResult {
+  if (!isWindowsExecutablePath(path)) {
+    return { found: false, diagnostic: `${path} is not a .exe or .com path` };
+  }
+  try {
+    const stats = statSync(path);
+    if (stats.isFile()) return { found: true };
+    return { found: false, diagnostic: `${path} is not a regular file` };
+  } catch (error) {
+    return { found: false, diagnostic: `${path}: ${shellErrorMessage(error)}` };
+  }
+}
+
+function windowsPathValue(env: NodeJS.ProcessEnv): string {
+  return env['PATH'] ?? env['Path'] ?? env['path'] ?? '';
+}
+
+function resolveWindowsBash(env: NodeJS.ProcessEnv): string {
+  const pathValue = windowsPathValue(env);
+  const diagnostics: string[] = [];
+  for (const dir of pathValue.split(';').filter((entry) => entry.length > 0)) {
+    for (const name of ['bash.exe', 'bash.com']) {
+      const candidate = join(dir, name);
+      const result = inspectWindowsShellCandidate(candidate);
+      if (result.found) return candidate;
+      diagnostics.push(result.diagnostic);
+    }
+  }
+  const suffix = diagnostics.length > 0 ? `: ${diagnostics.join('; ')}` : '';
+  failShellInvocation(`PI_BG_SHELL=bash could not resolve bash.exe or bash.com on PATH${suffix}`);
+}
+
+function cmdShellInvocation(command: string, shell: string): ShellInvocation {
+  return {
+    shell,
+    args: ['/d', '/s', '/c', `"${command}"`],
+    dialect: 'cmd',
+    windowsVerbatimArguments: true,
+  };
+}
+
+function posixShellInvocation(command: string, shell: string): ShellInvocation {
+  return { shell, args: ['-c', command], dialect: 'posix', windowsVerbatimArguments: false };
+}
+
 export function shellInvocation(
   command: string,
   platform: NodeJS.Platform = process.platform,
   env: NodeJS.ProcessEnv = process.env,
-): { shell: string; args: string[] } {
-  if (platform === 'win32') {
+): ShellInvocation {
+  if (platform !== 'win32') {
+    const shell = env['SHELL'];
+    return posixShellInvocation(command, shell && shell.length > 0 ? shell : '/bin/sh');
+  }
+
+  const requestedShell = env['PI_BG_SHELL'];
+  const requestedPath = env['PI_BG_SHELL_PATH'];
+  if (requestedShell === undefined) {
+    if (requestedPath !== undefined) failShellInvocation('PI_BG_SHELL_PATH requires PI_BG_SHELL');
     const comSpec = env['ComSpec'];
-    return {
-      shell: comSpec && comSpec.length > 0 ? comSpec : 'cmd.exe',
-      args: ['/d', '/s', '/c', command],
-    };
+    return cmdShellInvocation(command, comSpec && comSpec.length > 0 ? comSpec : 'cmd.exe');
+  }
+  if (requestedShell !== 'cmd' && requestedShell !== 'bash') {
+    failShellInvocation('PI_BG_SHELL must be exactly cmd or bash');
+  }
+  const explicitPath =
+    requestedPath !== undefined ? validateWindowsShellPath(requestedPath, 'PI_BG_SHELL_PATH') : undefined;
+  if (requestedShell === 'cmd') {
+    const comSpec = env['ComSpec'];
+    return cmdShellInvocation(command, explicitPath ?? (comSpec && comSpec.length > 0 ? comSpec : 'cmd.exe'));
   }
-  const shell = env['SHELL'];
-  return { shell: shell && shell.length > 0 ? shell : '/bin/sh', args: ['-c', command] };
+  return posixShellInvocation(command, explicitPath ?? resolveWindowsBash(env));
 }
 
 export function normalizeMaxBytes(value: unknown, fallback = DEFAULT_LOG_BYTES): number {
@@ -570,6 +685,7 @@ export function snapshot(task: BgTask): BgTaskSnapshot {
     tokenUsage: task.tokenUsage,
     toolUsage: task.toolUsage,
     model: task.model,
+    telemetryUnavailableReason: task.telemetryUnavailableReason,
     attestationPath: task.attestationPath,
   };
 }

package/src/core/durable-fs.ts

@@ -0,0 +1,400 @@
+import { randomBytes } from 'node:crypto';
+import { open as nodeOpen, rename as nodeRename, rm as nodeRm } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+export type DurableData = Buffer | string;
+export type DurableWriteFlag = 'w' | 'wx';
+export type DurableOperation =
+  | 'open_file'
+  | 'write_file'
+  | 'sync_file'
+  | 'close_file'
+  | 'rename_file'
+  | 'remove_temp'
+  | 'open_directory'
+  | 'sync_directory'
+  | 'close_directory';
+
+export interface DurableFailure {
+  operation: DurableOperation;
+  path: string;
+  cause: unknown;
+}
+
+export interface DurableWritableHandle {
+  writeFile(data: DurableData): Promise<void>;
+  sync(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface DurableDirectoryHandle {
+  sync(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface DurableFileOperations {
+  platform: NodeJS.Platform;
+  openWritable(
+    path: string,
+    flag: DurableWriteFlag,
+    mode?: number,
+  ): Promise<DurableWritableHandle>;
+  openDirectory(path: string): Promise<DurableDirectoryHandle>;
+  rename(source: string, target: string): Promise<void>;
+  remove(path: string): Promise<void>;
+  temporaryPath(target: string): string;
+}
+
+export interface DurableFileWriter {
+  write(path: string, data: DurableData): Promise<void>;
+  replace(path: string, data: DurableData): Promise<void>;
+}
+
+interface DurableErrorInput {
+  operation: DurableOperation;
+  path: string;
+  cause: unknown;
+  cleanupFailures: readonly DurableFailure[];
+  targetPath: string | undefined;
+  temporaryPath: string | undefined;
+  renameCompleted: boolean;
+}
+
+interface WritableSequenceResult {
+  primaryFailure: DurableFailure | undefined;
+  cleanupFailures: DurableFailure[];
+}
+
+export class DurableFileError extends Error {
+  readonly operation: DurableOperation;
+  readonly path: string;
+  readonly nativeCode: string | undefined;
+  readonly primaryCause: unknown;
+  readonly cleanupFailures: readonly DurableFailure[];
+  readonly targetPath: string | undefined;
+  readonly temporaryPath: string | undefined;
+  readonly renameCompleted: boolean;
+
+  constructor(input: {
+    operation: DurableOperation;
+    path: string;
+    cause: unknown;
+    cleanupFailures: readonly DurableFailure[];
+    targetPath: string | undefined;
+    temporaryPath: string | undefined;
+    renameCompleted: boolean;
+  }) {
+    super(formatDurableMessage(input));
+    this.name = 'DurableFileError';
+    this.operation = input.operation;
+    this.path = input.path;
+    this.nativeCode = nativeCodeForCause(input.cause);
+    this.primaryCause = input.cause;
+    this.cleanupFailures = [...input.cleanupFailures];
+    this.targetPath = input.targetPath;
+    this.temporaryPath = input.temporaryPath;
+    this.renameCompleted = input.renameCompleted;
+  }
+}
+
+function failure(operation: DurableOperation, path: string, cause: unknown): DurableFailure {
+  return { operation, path, cause };
+}
+
+function durableError(input: DurableErrorInput): DurableFileError {
+  return new DurableFileError(input);
+}
+
+function nativeCodeForCause(cause: unknown): string | undefined {
+  if (typeof cause !== 'object' || cause === null) return undefined;
+  const code = Reflect.get(cause, 'code');
+  return typeof code === 'string' ? code : undefined;
+}
+
+function describeCause(cause: unknown): string {
+  if (cause instanceof Error) {
+    const message = cause.message.length > 0 ? cause.message : String(cause);
+    return `${cause.name}: ${message}`;
+  }
+  return String(cause);
+}
+
+function formatFailureForMessage(entry: DurableFailure): string {
+  const code = nativeCodeForCause(entry.cause);
+  const codeText = code === undefined ? '' : ` (code ${code})`;
+  return `${entry.operation} ${entry.path}${codeText}: ${describeCause(entry.cause)}`;
+}
+
+function formatDurableMessage(input: DurableErrorInput): string {
+  const primary = formatFailureForMessage({
+    operation: input.operation,
+    path: input.path,
+    cause: input.cause,
+  });
+  const segments = [`Durable file operation failed: ${primary}`];
+  if (input.targetPath !== undefined) segments.push(`target: ${input.targetPath}`);
+  if (input.temporaryPath !== undefined) segments.push(`temporary: ${input.temporaryPath}`);
+  if (input.renameCompleted) {
+    const target = input.targetPath ?? input.path;
+    segments.push(`Replacement may already be visible at ${target}.`);
+  }
+  if (input.cleanupFailures.length > 0) {
+    const cleanupText = input.cleanupFailures.map(formatFailureForMessage).join('; ');
+    segments.push(`Cleanup failures: ${cleanupText}`);
+  }
+  return segments.join(' ');
+}
+
+async function writeSyncClose(
+  handle: DurableWritableHandle,
+  path: string,
+  data: DurableData,
+): Promise<WritableSequenceResult> {
+  const cleanupFailures: DurableFailure[] = [];
+  let primaryFailure: DurableFailure | undefined;
+  try {
+    await handle.writeFile(data);
+  } catch (error) {
+    primaryFailure = failure('write_file', path, error);
+  }
+  if (primaryFailure === undefined) {
+    try {
+      await handle.sync();
+    } catch (error) {
+      primaryFailure = failure('sync_file', path, error);
+    }
+  }
+  try {
+    await handle.close();
+  } catch (error) {
+    const closeFailure = failure('close_file', path, error);
+    if (primaryFailure === undefined) primaryFailure = closeFailure;
+    else cleanupFailures.push(closeFailure);
+  }
+  return { primaryFailure, cleanupFailures };
+}
+
+async function syncCloseDirectory(
+  handle: DurableDirectoryHandle,
+  path: string,
+): Promise<WritableSequenceResult> {
+  const cleanupFailures: DurableFailure[] = [];
+  let primaryFailure: DurableFailure | undefined;
+  try {
+    await handle.sync();
+  } catch (error) {
+    primaryFailure = failure('sync_directory', path, error);
+  }
+  try {
+    await handle.close();
+  } catch (error) {
+    const closeFailure = failure('close_directory', path, error);
+    if (primaryFailure === undefined) primaryFailure = closeFailure;
+    else cleanupFailures.push(closeFailure);
+  }
+  return { primaryFailure, cleanupFailures };
+}
+
+function throwDurable(
+  primaryFailure: DurableFailure,
+  cleanupFailures: readonly DurableFailure[],
+  targetPath: string | undefined,
+  temporaryPath: string | undefined,
+  renameCompleted: boolean,
+): never {
+  throw durableError({
+    operation: primaryFailure.operation,
+    path: primaryFailure.path,
+    cause: primaryFailure.cause,
+    cleanupFailures,
+    targetPath,
+    temporaryPath,
+    renameCompleted,
+  });
+}
+
+async function removeTemporary(
+  operations: DurableFileOperations,
+  temporaryPath: string,
+  cleanupFailures: DurableFailure[],
+): Promise<void> {
+  try {
+    await operations.remove(temporaryPath);
+  } catch (error) {
+    cleanupFailures.push(failure('remove_temp', temporaryPath, error));
+  }
+}
+
+async function writeWithOperations(
+  operations: DurableFileOperations,
+  path: string,
+  data: DurableData,
+): Promise<void> {
+  let handle: DurableWritableHandle;
+  try {
+    handle = await operations.openWritable(path, 'w');
+  } catch (error) {
+    throwDurable(failure('open_file', path, error), [], path, undefined, false);
+  }
+  const result = await writeSyncClose(handle, path, data);
+  if (result.primaryFailure !== undefined) {
+    throwDurable(result.primaryFailure, result.cleanupFailures, path, undefined, false);
+  }
+}
+
+async function syncDirectoryAfterRename(
+  operations: DurableFileOperations,
+  targetPath: string,
+  temporaryPath: string,
+): Promise<void> {
+  if (operations.platform === 'win32') return;
+  const directoryPath = dirname(targetPath);
+  let handle: DurableDirectoryHandle;
+  try {
+    handle = await operations.openDirectory(directoryPath);
+  } catch (error) {
+    throwDurable(failure('open_directory', directoryPath, error), [], targetPath, temporaryPath, true);
+  }
+  const result = await syncCloseDirectory(handle, directoryPath);
+  if (result.primaryFailure !== undefined) {
+    throwDurable(result.primaryFailure, result.cleanupFailures, targetPath, temporaryPath, true);
+  }
+}
+
+async function replaceWithOperations(
+  operations: DurableFileOperations,
+  path: string,
+  data: DurableData,
+): Promise<void> {
+  const temporaryPath = operations.temporaryPath(path);
+  let handle: DurableWritableHandle;
+  try {
+    handle = await operations.openWritable(temporaryPath, 'wx', 0o600);
+  } catch (error) {
+    throwDurable(failure('open_file', temporaryPath, error), [], path, temporaryPath, false);
+  }
+  const writeResult = await writeSyncClose(handle, temporaryPath, data);
+  if (writeResult.primaryFailure !== undefined) {
+    await removeTemporary(operations, temporaryPath, writeResult.cleanupFailures);
+    throwDurable(writeResult.primaryFailure, writeResult.cleanupFailures, path, temporaryPath, false);
+  }
+  const renameError = await renameWithWindowsContention(operations, temporaryPath, path);
+  if (renameError !== undefined) {
+    const cleanupFailures: DurableFailure[] = [];
+    await removeTemporary(operations, temporaryPath, cleanupFailures);
+    throwDurable(
+      failure('rename_file', path, renameError),
+      cleanupFailures,
+      path,
+      temporaryPath,
+      false,
+    );
+  }
+  await syncDirectoryAfterRename(operations, path, temporaryPath);
+}
+
+/**
+ * Windows sharing-violation codes for a replace-rename.
+ *
+ * POSIX `rename(2)` atomically replaces the target. Windows `MoveFileEx` fails
+ * with a sharing violation when another process momentarily holds the target
+ * open, including transient scanners, indexers, and concurrent writers. The
+ * operation is legitimate and simply needs to be reattempted.
+ */
+const WINDOWS_RENAME_CONTENTION_CODES: ReadonlySet<string> = new Set([
+  'EPERM',
+  'EACCES',
+  'EBUSY',
+]);
+
+const WINDOWS_RENAME_ATTEMPTS = 10;
+const WINDOWS_RENAME_RETRY_DELAY_MS = 20;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Rename the temporary file over the target, retrying only Windows sharing
+ * violations.
+ *
+ * This is a bounded retry of a transient OS condition, not a fallback: the
+ * final failure is still returned and raised loudly, no alternative write path
+ * is taken, and no other platform or error code is retried.
+ *
+ * Returns the failure cause, or undefined on success.
+ */
+async function renameWithWindowsContention(
+  operations: DurableFileOperations,
+  temporaryPath: string,
+  targetPath: string,
+): Promise<unknown> {
+  const attempts = operations.platform === 'win32' ? WINDOWS_RENAME_ATTEMPTS : 1;
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      await operations.rename(temporaryPath, targetPath);
+      return undefined;
+    } catch (error) {
+      lastError = error;
+      const code = nativeCodeForCause(error);
+      const retryable =
+        operations.platform === 'win32' &&
+        code !== undefined &&
+        WINDOWS_RENAME_CONTENTION_CODES.has(code);
+      if (!retryable || attempt === attempts) return error;
+      await delay(WINDOWS_RENAME_RETRY_DELAY_MS * attempt);
+    }
+  }
+  return lastError;
+}
+
+function temporaryPathForTarget(target: string): string {
+  return join(
+    dirname(target),
+    `.${basename(target)}.${String(process.pid)}.${randomBytes(6).toString('hex')}.tmp`,
+  );
+}
+
+const nodeOperations: DurableFileOperations = {
+  platform: process.platform,
+  async openWritable(path: string, flag: DurableWriteFlag, mode?: number) {
+    if (mode === undefined) return nodeOpen(path, flag);
+    return nodeOpen(path, flag, mode);
+  },
+  async openDirectory(path: string) {
+    return nodeOpen(path, 'r');
+  },
+  async rename(source: string, target: string) {
+    await nodeRename(source, target);
+  },
+  async remove(path: string) {
+    // `force` ignores a missing path only. Permission and other failures still
+    // throw and are surfaced as `remove_temp` cleanup failures.
+    await nodeRm(path, { force: true });
+  },
+  temporaryPath: temporaryPathForTarget,
+};
+
+const defaultWriter = createDurableFileWriter(nodeOperations);
+
+export function createDurableFileWriter(operations: DurableFileOperations): DurableFileWriter {
+  return {
+    async write(path: string, data: DurableData): Promise<void> {
+      await writeWithOperations(operations, path, data);
+    },
+    async replace(path: string, data: DurableData): Promise<void> {
+      await replaceWithOperations(operations, path, data);
+    },
+  };
+}
+
+export async function writeFileDurable(path: string, data: DurableData): Promise<void> {
+  await defaultWriter.write(path, data);
+}
+
+export async function replaceFileDurable(path: string, data: DurableData): Promise<void> {
+  await defaultWriter.replace(path, data);
+}

package/src/core/fusion/artifacts.ts

@@ -1,9 +1,9 @@
 import { randomBytes } from 'node:crypto';
-import { closeSync, fsyncSync, openSync, renameSync } from 'node:fs';
-import { chmod, mkdir, open, rm } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { chmod, mkdir } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
 import { canonicalJson, sha256Buffer } from '../attested-pi-run.js';
 import { sanitizePathSegment } from '../common.js';
+import { replaceFileDurable } from '../durable-fs.js';
 import {
   EMPTY_FUSION_USAGE,
   FUSION_MANIFEST_SCHEMA_VERSION,
@@ -12,7 +12,9 @@ import {
   type FusionArtifactManifest,
   type FusionArtifactRef,
   type FusionAttemptArtifactRecord,
+  type FusionBudgetPlanV1,
   type FusionCandidateId,
+  type FusionContextOmissionLedgerV2,
   type FusionChildRunResult,
   type FusionModelConfigV1,
   type FusionSource,
@@ -118,16 +120,6 @@ function canTransition(from: FusionState, to: FusionState): boolean {
   return NEXT_STATES[from].includes(to);
 }
 
-function fsyncDirectory(path: string): void {
-  if (process.platform === 'win32') return;
-  const fd = openSync(path, 'r');
-  try {
-    fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
-}
-
 function pathInside(parent: string, child: string): boolean {
   const rel = relative(parent, child);
   return (
@@ -139,34 +131,12 @@ function errorForArtifact(message: string): FusionError {
   return new FusionError(message, { code: 'artifact_error', childCreated: false });
 }
 
-async function writeTempFile(absPath: string, data: Buffer | string): Promise<void> {
-  const handle = await open(absPath, 'wx', 0o600);
-  try {
-    await handle.writeFile(data);
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
-
 async function writePrivateFile(
   absPath: string,
   data: Buffer | string,
 ): Promise<FusionArtifactRef> {
-  const dir = dirname(absPath);
-  const tmp = join(
-    dir,
-    `.${basename(absPath)}.${String(process.pid)}.${randomBytes(6).toString('hex')}.tmp`,
-  );
   const bytes = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
-  try {
-    await writeTempFile(tmp, data);
-    renameSync(tmp, absPath);
-    fsyncDirectory(dir);
-  } catch (error) {
-    await rm(tmp, { force: true });
-    throw error;
-  }
+  await replaceFileDurable(absPath, data);
   return { path: basename(absPath), byte_length: bytes.length, sha256: sha256Buffer(bytes) };
 }
 
@@ -313,6 +283,20 @@ export class FusionArtifactStore {
     await this.writeArtifact('canonical-input.json', serialized);
   }
 
+  /**
+   * Complete, source-ordered ledger of every omitted conversation event. Kept in
+   * a separate artifact so canonical input carries only compact run receipts
+   * while the full omission accounting stays locally auditable.
+   */
+  async writeContextLedger(ledger: FusionContextOmissionLedgerV2): Promise<void> {
+    await this.writeArtifact('context-omission-ledger.json', canonicalJson(ledger));
+  }
+
+  /** Route capacities and the pre-candidate whole-workflow feasibility decision. */
+  async writeBudgetPlan(plan: FusionBudgetPlanV1): Promise<void> {
+    await this.writeArtifact('budget-plan.json', canonicalJson(plan));
+  }
+
   async writeBlindCandidates(serialized: string): Promise<void> {
     await this.writeArtifact('blind-candidates.json', serialized);
   }