@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/runs/background/runner-monitor.ts

@@ -0,0 +1,399 @@
+import * as fs from "node:fs";
+import { RunnerChildObserver } from "./runner-child-observer.ts";
+import { refreshRunnerGraph } from "./runner-graph.ts";
+import {
+  expandDynamicStatus,
+  expandDynamicGraph,
+  reindexChildTargets,
+  type DynamicPlan,
+} from "./runner-dynamic.ts";
+import type { DynamicRunnerGroup, AcceptanceLedger, ActivityState } from "../../shared/types.ts";
+import * as path from "node:path";
+import type { ReadonlyDeep } from "type-fest";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { appendJsonl } from "../../shared/artifacts.ts";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../shared/pi-args.ts";
+import {
+  DEFAULT_CONTROL_CONFIG,
+  buildControlEvent,
+  deriveActivityState,
+  claimControlNotification,
+  formatControlIntercomMessage,
+  formatControlNoticeMessage,
+} from "../shared/subagent-control.ts";
+import { nestedSummaryFromAsyncStatus, writeNestedEvent } from "../shared/nested-events.ts";
+import { saveRunStatus, pendingSupervisorQuestion } from "../shared/supervisor-questions.ts";
+import type { MutationToolResult } from "../shared/mutating-tool-guard.ts";
+import type { ChildEvent } from "../shared/child-attempt.ts";
+import type { SubagentRunConfig } from "./runner-contract.ts";
+import type { RunnerStatusPayload } from "./runner-status.ts";
+
+/** Owns live status publication and attention notifications; execution owns cancellation. */
+export class RunnerMonitor {
+  private statusWriteTimer: NodeJS.Timeout | undefined;
+  private currentActivityState: ActivityState | undefined;
+  private readonly emittedControlEventKeys = new Set<string>();
+  private readonly childObserver: RunnerChildObserver;
+  private readonly controlConfig;
+  private readonly childSafeControls;
+  private readonly statusPath;
+  private readonly eventsPath;
+  private readonly asyncDir;
+  private readonly id;
+  private childIntercomTargets: Array<string | undefined> | undefined;
+  private readonly config: ReadonlyDeep<SubagentRunConfig>;
+  readonly statusPayload: RunnerStatusPayload;
+  private readonly overallStartTime: number;
+
+  constructor(
+    config: ReadonlyDeep<SubagentRunConfig>,
+    statusPayload: RunnerStatusPayload,
+    overallStartTime: number,
+  ) {
+    this.config = config;
+    this.statusPayload = statusPayload;
+    this.overallStartTime = overallStartTime;
+    this.id = this.config.id;
+    this.asyncDir = this.config.asyncDir;
+    this.statusPath = path.join(this.config.asyncDir, "status.json");
+    this.eventsPath = path.join(this.config.asyncDir, "events.jsonl");
+    this.controlConfig = this.config.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+    this.childSafeControls =
+      this.config.nestedSelf !== undefined ||
+      (process.env[SUBAGENT_CHILD_ENV] === "1" && process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1");
+    this.childObserver = new RunnerChildObserver(
+      statusPayload,
+      { id: this.id, controlConfig: this.controlConfig },
+      {
+        clearAttention: (index) => {
+          this.clearControlNotificationKeys(index);
+        },
+        notify: (event) => {
+          this.appendControlEvent(event);
+        },
+        scheduleWrite: () => {
+          this.scheduleStatusWrite();
+        },
+      },
+    );
+    this.childIntercomTargets = config.childIntercomTargets?.map((target) =>
+      typeof target === "string" ? target : undefined,
+    );
+  }
+
+  childTarget(index: number): string | undefined {
+    return this.childIntercomTargets?.[index];
+  }
+
+  failDynamicStep(stepIndex: number, flatIndex: number, error: string): void {
+    const now = Date.now();
+    this.statusPayload.state = "failed";
+    this.statusPayload.error = error;
+    this.statusPayload.currentStep = flatIndex;
+    const placeholder = this.statusPayload.steps.at(flatIndex);
+    if (placeholder) {
+      Object.assign(placeholder, {
+        status: "failed",
+        error,
+        startedAt: now,
+        endedAt: now,
+        durationMs: 0,
+        exitCode: 1,
+      });
+    }
+    this.statusPayload.lastUpdate = now;
+    this.markDynamicGraphGroup(stepIndex, "failed", error);
+    this.writeStatusPayload();
+  }
+
+  expandChildren(
+    plan: ReadonlyDeep<DynamicPlan>,
+    step: DynamicRunnerGroup,
+    position: Readonly<{ stepIndex: number; flatIndex: number }>,
+  ): void {
+    const address = { ...position, runId: this.id };
+    const count = expandDynamicStatus(this.statusPayload, plan, step, address);
+    this.childIntercomTargets = reindexChildTargets(
+      this.childIntercomTargets,
+      this.statusPayload.steps,
+      { ...address, count },
+    );
+    this.childObserver.expandChildren(position.flatIndex, count);
+    const graph = this.statusPayload.workflowGraph;
+    if (graph) {
+      this.statusPayload.workflowGraph = expandDynamicGraph(graph, plan, step, address);
+    }
+    this.writeStatusPayload();
+  }
+
+  private emitNestedSelfEvent(type: "subagent.nested.updated" | "subagent.nested.completed"): void {
+    if (!this.config.nestedRoute || !this.config.nestedSelf) {
+      return;
+    }
+    try {
+      writeNestedEvent(this.config.nestedRoute, {
+        type,
+        ts: Date.now(),
+        parentRunId: this.config.nestedSelf.parentRunId,
+        parentStepIndex: this.config.nestedSelf.parentStepIndex,
+        child: nestedSummaryFromAsyncStatus(this.statusPayload, this.asyncDir, {
+          id: this.id,
+          parentRunId: this.config.nestedSelf.parentRunId,
+          parentStepIndex: this.config.nestedSelf.parentStepIndex,
+          depth: this.config.nestedSelf.depth,
+          path: this.config.nestedSelf.path?.map((entry) => Object.assign({}, entry)),
+          mode: this.statusPayload.mode,
+          ts: Date.now(),
+        }),
+      });
+    } catch (error) {
+      console.error("Failed to emit nested async status event:", error);
+    }
+  }
+  private refreshWorkflowGraph(): void {
+    const graph = this.statusPayload.workflowGraph ?? this.config.workflowGraph;
+    if (graph !== undefined) {
+      this.statusPayload.workflowGraph = refreshRunnerGraph(
+        graph,
+        this.statusPayload.steps,
+        this.statusPayload.currentStep,
+      );
+    }
+  }
+
+  writeStatusPayload = (): void => {
+    if (this.statusWriteTimer) {
+      clearTimeout(this.statusWriteTimer);
+      this.statusWriteTimer = undefined;
+    }
+    this.refreshWorkflowGraph();
+    writeAtomicJson(this.statusPath, this.statusPayload);
+    if (this.config.runtimeVersion !== 2) {
+      saveRunStatus(this.id, this.statusPayload);
+    }
+    this.emitNestedSelfEvent(
+      this.statusPayload.state === "running" || this.statusPayload.state === "queued"
+        ? "subagent.nested.updated"
+        : "subagent.nested.completed",
+    );
+  };
+  private scheduleStatusWrite(): void {
+    if (this.statusWriteTimer) {
+      return;
+    }
+    this.statusWriteTimer = setTimeout(this.writeStatusPayload, 200);
+    this.statusWriteTimer.unref();
+  }
+  markDynamicGraphGroup(
+    stepIndex: number,
+    status: "completed" | "failed" | "blocked" | "running" | "paused",
+    error?: string,
+    acceptance?: AcceptanceLedger,
+  ): void {
+    const graph = this.statusPayload.workflowGraph;
+    if (graph === undefined) {
+      return;
+    }
+    this.statusPayload.workflowGraph = {
+      ...graph,
+      nodes: graph.nodes.map((node) =>
+        node.id === `step-${stepIndex}`
+          ? Object.assign({}, node, {
+              status,
+              error,
+              acceptanceStatus: acceptance?.status ?? node.acceptanceStatus,
+            })
+          : node,
+      ),
+    };
+  }
+
+  refreshUsageTotals(): void {
+    this.statusPayload.totalTokens = this.statusPayload.steps.reduce(
+      (total, step) => ({
+        input: total.input + (step.tokens?.input ?? 0),
+        output: total.output + (step.tokens?.output ?? 0),
+        total: total.total + (step.tokens?.total ?? 0),
+      }),
+      { input: 0, output: 0, total: 0 },
+    );
+  }
+  private stepOutputActivityAt(index: number): number {
+    const step = this.statusPayload.steps.at(index);
+    let lastActivityAt = step?.lastActivityAt ?? step?.startedAt ?? this.overallStartTime;
+    const outputPath = path.join(this.asyncDir, `output-${index}.log`);
+    try {
+      lastActivityAt = Math.max(lastActivityAt, fs.statSync(outputPath).mtimeMs);
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        console.error(`Failed to inspect async output file '${outputPath}':`, error);
+      }
+    }
+    return lastActivityAt;
+  }
+  appendControlEvent(event: ReadonlyDeep<ReturnType<typeof buildControlEvent>>): void {
+    if (!this.controlConfig.enabled) {
+      return;
+    }
+    const childIntercomTarget =
+      this.childIntercomTargets?.[event.index ?? this.statusPayload.currentStep];
+    const channels = this.controlConfig.notifyChannels;
+    if (
+      channels.length === 0 ||
+      !claimControlNotification(
+        this.controlConfig,
+        event,
+        this.emittedControlEventKeys,
+        childIntercomTarget,
+      )
+    ) {
+      return;
+    }
+    appendJsonl(
+      this.eventsPath,
+      JSON.stringify({
+        type: "subagent.control",
+        event,
+        channels,
+        childIntercomTarget,
+        noticeText: formatControlNoticeMessage(event, childIntercomTarget, this.childSafeControls),
+        ...(this.config.controlIntercomTarget !== undefined &&
+        this.config.controlIntercomTarget.length > 0 &&
+        channels.includes("intercom")
+          ? {
+              intercom: {
+                to: this.config.controlIntercomTarget,
+                message: formatControlIntercomMessage(
+                  event,
+                  childIntercomTarget,
+                  this.childSafeControls,
+                ),
+              },
+            }
+          : {}),
+      }),
+    );
+  }
+  updateStepModel(
+    flatIndex: number,
+    model: string | undefined,
+    thinking: string | undefined,
+    now = Date.now(),
+  ): void {
+    const step = this.statusPayload.steps.at(flatIndex);
+    if (!step) {
+      return;
+    }
+    step.model = model;
+    step.thinking = thinking;
+    step.modelStartedAt = now;
+    this.statusPayload.lastUpdate = now;
+    this.writeStatusPayload();
+  }
+  private clearControlNotificationKeys(flatIndex: number): void {
+    const childKey = this.childIntercomTargets?.[flatIndex] ?? `${this.config.id}:${flatIndex}`;
+    for (const key of this.emittedControlEventKeys) {
+      if (key.startsWith(`${childKey}:`)) {
+        this.emittedControlEventKeys.delete(key);
+      }
+    }
+  }
+  updateStepFromChildEvent(
+    flatIndex: number,
+    event: ReadonlyDeep<ChildEvent>,
+    toolSnapshot?: ReadonlyDeep<MutationToolResult>,
+  ): void {
+    this.childObserver.updateStepFromChildEvent(flatIndex, event, toolSnapshot);
+  }
+
+  private updateIdleAttention(index: number, lastActivityAt: number, now: number): boolean {
+    const step = this.statusPayload.steps[index];
+    const idleState = deriveActivityState({
+      config: this.controlConfig,
+      startedAt: step.startedAt ?? this.overallStartTime,
+      lastActivityAt,
+      now,
+    });
+    const previous = step.activityState;
+    if (idleState !== "needs_attention") {
+      if (previous !== "needs_attention") {
+        return false;
+      }
+      step.activityState = undefined;
+      this.clearControlNotificationKeys(index);
+      return true;
+    }
+    step.activityState = "needs_attention";
+    if (previous === "needs_attention") {
+      return false;
+    }
+    this.appendControlEvent(
+      buildControlEvent({
+        from: previous,
+        to: "needs_attention",
+        runId: this.id,
+        agent: step.agent,
+        index,
+        ts: now,
+        lastActivityAt,
+        currentTool: step.currentTool,
+        currentToolDurationMs:
+          step.currentToolStartedAt === undefined
+            ? undefined
+            : Math.max(0, now - step.currentToolStartedAt),
+        supervisorQuestion: pendingSupervisorQuestion({
+          runId: this.id,
+          agent: step.agent,
+          index,
+          sessionFile: step.sessionFile,
+        }),
+      }),
+    );
+    return true;
+  }
+
+  private syncRunAttention(): boolean {
+    const nextRunState = this.statusPayload.steps.some(
+      (step) => step.activityState === "needs_attention",
+    )
+      ? "needs_attention"
+      : undefined;
+    if (nextRunState === this.currentActivityState) {
+      return false;
+    }
+    this.currentActivityState = nextRunState;
+    this.statusPayload.activityState = nextRunState;
+    return true;
+  }
+
+  updateRunnerActivityState(now: number): boolean {
+    if (!this.controlConfig.enabled) {
+      return false;
+    }
+    let changed = false;
+    let runLastActivityAt = this.statusPayload.lastActivityAt ?? this.overallStartTime;
+    for (let index = 0; index < this.statusPayload.steps.length; index++) {
+      const step = this.statusPayload.steps[index];
+      if (step.status !== "running") {
+        continue;
+      }
+      const lastActivityAt = this.stepOutputActivityAt(index);
+      runLastActivityAt = Math.max(runLastActivityAt, lastActivityAt);
+      if (step.lastActivityAt !== lastActivityAt) {
+        step.lastActivityAt = lastActivityAt;
+        changed = true;
+      }
+      changed = this.updateIdleAttention(index, lastActivityAt, now) || changed;
+    }
+    if (this.statusPayload.lastActivityAt !== runLastActivityAt) {
+      this.statusPayload.lastActivityAt = runLastActivityAt;
+      changed = true;
+    }
+    changed = this.syncRunAttention() || changed;
+    this.statusPayload.lastUpdate = now;
+    if (changed) {
+      this.writeStatusPayload();
+    }
+    return changed;
+  }
+}

package/src/runs/background/runner-parallel.ts

@@ -0,0 +1,280 @@
+import * as path from "node:path";
+import { inspect } from "node:util";
+import type { ReadonlyDeep } from "type-fest";
+import { appendJsonl } from "../../shared/artifacts.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { writeInitialProgressFile } from "../../shared/settings.ts";
+import { completeWorkflowStep, runParallelTasks } from "../shared/workflow-policy.ts";
+import {
+  createWorktrees,
+  cleanupWorktrees,
+  findWorktreeTaskCwdConflict,
+  formatWorktreeTaskCwdConflict,
+  formatParallelWorktreeSummary,
+  WorktreeCleanupError,
+  type WorktreeSetup,
+} from "../shared/worktree.ts";
+import { MAX_PARALLEL_CONCURRENCY } from "../shared/parallel-utils.ts";
+import type { ParallelStepGroup, RunnerSubagentStep } from "../../shared/types.ts";
+import type { SubagentRunConfig, StepResult } from "./runner-contract.ts";
+import type { RunnerMonitor } from "./runner-monitor.ts";
+import type { RunnerLifecycle } from "./runner-lifecycle.ts";
+import type { RunnerChildExecutor, AsyncParallelStepResult } from "./runner-child-executor.ts";
+
+interface GroupPosition {
+  readonly flatIndex: number;
+  readonly stepIndex: number;
+  readonly flatStepCount: number;
+  readonly previousOutput: string;
+}
+
+export interface ParallelCompletion {
+  readonly results: AsyncParallelStepResult[];
+  readonly completion: ReturnType<typeof completeWorkflowStep>;
+  readonly summary: string;
+}
+
+type SetupOutcome =
+  | { readonly ready: true; readonly worktrees?: WorktreeSetup }
+  | { readonly ready: false; readonly results: StepResult[]; readonly warning?: string };
+
+/** Owns worktree setup/preservation/cleanup for a static parallel group. */
+export class RunnerParallelGroup {
+  private readonly config: ReadonlyDeep<SubagentRunConfig>;
+  private readonly monitor: RunnerMonitor;
+  private readonly lifecycle: RunnerLifecycle;
+  private readonly executor: RunnerChildExecutor;
+
+  constructor(
+    config: ReadonlyDeep<SubagentRunConfig>,
+    monitor: RunnerMonitor,
+    lifecycle: RunnerLifecycle,
+    executor: RunnerChildExecutor,
+  ) {
+    this.config = config;
+    this.monitor = monitor;
+    this.lifecycle = lifecycle;
+    this.executor = executor;
+  }
+
+  async run(
+    group: ParallelStepGroup,
+    position: GroupPosition,
+    hooks: Readonly<{
+      failed: (results: readonly ReadonlyDeep<StepResult>[], warning?: string) => void;
+      completed: (outcome: ReadonlyDeep<ParallelCompletion>) => void;
+    }>,
+  ): Promise<boolean> {
+    const setup = await this.setup(group, position);
+    if (!setup.ready) {
+      hooks.failed(setup.results, setup.warning);
+      return false;
+    }
+    const worktrees = setup.worktrees;
+    const cwd = group.cwd ?? this.config.cwd;
+    try {
+      if (group.worktree === true) {
+        this.ensureProgress(cwd, group);
+      }
+      this.startGroup(group, position);
+      const results = await this.executeTasks(group, position, worktrees);
+      this.monitor.refreshUsageTotals();
+      this.monitor.statusPayload.lastUpdate = Date.now();
+      this.monitor.writeStatusPayload();
+      const completion = completeWorkflowStep({
+        stepIndex: position.stepIndex,
+        stepCount: this.config.steps.length,
+        results,
+        previousOutput: position.previousOutput,
+        parallel: true,
+        outputNames: group.parallel.map((task) => task.outputName),
+      });
+      const summary = formatParallelWorktreeSummary(
+        worktrees,
+        path.join(this.config.asyncDir, "worktree-diffs", `step-${position.stepIndex}`),
+        group.parallel.map((task) => task.agent),
+      );
+      // Workflow outputs and terminal group event are published before ordered worktree cleanup.
+      hooks.completed({ results, completion, summary });
+      return completion.advance;
+    } catch (error) {
+      if (worktrees) {
+        worktrees.preserveOnCleanup = true;
+      }
+      throw error;
+    } finally {
+      if (worktrees) {
+        cleanupWorktrees(worktrees);
+      }
+    }
+  }
+
+  private async setup(group: ParallelStepGroup, position: GroupPosition): Promise<SetupOutcome> {
+    if (group.worktree !== true) {
+      return { ready: true };
+    }
+    const cwd = group.cwd ?? this.config.cwd;
+    const conflict = findWorktreeTaskCwdConflict(group.parallel, cwd);
+    if (conflict) {
+      return {
+        ready: false,
+        results: this.failSetup(group, position, formatWorktreeTaskCwdConflict(conflict, cwd)),
+      };
+    }
+    try {
+      const hook = this.config.worktreeSetupHook;
+      const worktrees = await createWorktrees(
+        cwd,
+        `${this.config.id}-s${position.stepIndex}`,
+        group.parallel.length,
+        {
+          agents: group.parallel.map((task) => task.agent),
+          signal: AbortSignal.any([
+            this.lifecycle.cancellation.signal,
+            this.lifecycle.interruption.signal,
+          ]),
+          setupHook:
+            hook === undefined || hook.length === 0
+              ? undefined
+              : { hookPath: hook, timeoutMs: this.config.worktreeSetupHookTimeoutMs },
+        },
+      );
+      return { ready: true, worktrees };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : inspect(error);
+      if (this.lifecycle.interrupted && !this.lifecycle.cancellation.signal.aborted) {
+        return this.interruptedSetup(group, position, error, message);
+      }
+      return { ready: false, results: this.failSetup(group, position, message) };
+    }
+  }
+
+  private interruptedSetup(
+    group: ParallelStepGroup,
+    position: GroupPosition,
+    error: unknown,
+    message: string,
+  ): SetupOutcome {
+    const warning = error instanceof WorktreeCleanupError ? message : undefined;
+    const results = group.parallel.map((task, index) => {
+      const stopped = this.executor.stop(task, position.flatIndex + index, "interrupted");
+      return {
+        ...stopped,
+        output: warning === undefined ? stopped.output : `${stopped.output}\n\n${warning}`,
+        success: false,
+      };
+    });
+    return { ready: false, results, warning };
+  }
+
+  private failSetup(
+    group: ParallelStepGroup,
+    position: GroupPosition,
+    error: string,
+  ): StepResult[] {
+    const failedAt = Date.now();
+    const status = this.monitor.statusPayload;
+    const results = group.parallel.map((task, taskIndex) => {
+      const step = status.steps[position.flatIndex + taskIndex];
+      Object.assign(step, {
+        status: "failed",
+        startedAt: failedAt,
+        endedAt: failedAt,
+        durationMs: 0,
+        exitCode: 1,
+      });
+      return {
+        agent: task.agent,
+        output: error,
+        success: false,
+        exitCode: 1,
+        sessionFile: task.sessionFile,
+      };
+    });
+    status.currentStep = position.flatIndex;
+    status.lastUpdate = failedAt;
+    status.outputFile = path.join(this.config.asyncDir, `output-${position.flatIndex}.log`);
+    writeAtomicJson(path.join(this.config.asyncDir, "status.json"), status);
+    this.append({
+      type: "subagent.parallel.completed",
+      ts: failedAt,
+      runId: this.config.id,
+      stepIndex: position.stepIndex,
+      success: false,
+    });
+    return results;
+  }
+
+  private startGroup(group: ParallelStepGroup, position: GroupPosition): void {
+    const startedAt = Date.now();
+    const status = this.monitor.statusPayload;
+    for (const [index] of group.parallel.entries()) {
+      Object.assign(status.steps[position.flatIndex + index], {
+        status: "pending",
+        startedAt: undefined,
+        endedAt: undefined,
+        durationMs: undefined,
+        lastActivityAt: undefined,
+        activityState: undefined,
+        error: undefined,
+      });
+    }
+    status.currentStep = position.flatIndex;
+    status.activityState = undefined;
+    status.lastActivityAt = startedAt;
+    status.lastUpdate = startedAt;
+    status.outputFile = path.join(this.config.asyncDir, `output-${position.flatIndex}.log`);
+    writeAtomicJson(path.join(this.config.asyncDir, "status.json"), status);
+    this.append({
+      type: "subagent.parallel.started",
+      ts: startedAt,
+      runId: this.config.id,
+      stepIndex: position.stepIndex,
+      agents: group.parallel.map((task) => task.agent),
+      count: group.parallel.length,
+    });
+  }
+
+  private executeTasks(
+    group: ParallelStepGroup,
+    position: GroupPosition,
+    worktrees: ReadonlyDeep<WorktreeSetup> | undefined,
+  ): Promise<AsyncParallelStepResult[]> {
+    return runParallelTasks<RunnerSubagentStep, AsyncParallelStepResult>({
+      tasks: group.parallel,
+      concurrency: group.concurrency ?? MAX_PARALLEL_CONCURRENCY,
+      failFast: group.failFast,
+      signal: this.lifecycle.cancellation.signal,
+      interruptSignal: this.lifecycle.interruption.signal,
+      stoppedTask: (task, index, reason) =>
+        this.executor.stop(task, position.flatIndex + index, reason),
+      runTask: (task, index, interruptSignal) =>
+        this.executor.run({
+          task: worktrees ? { ...task, cwd: undefined } : task,
+          taskCwd: worktrees ? worktrees.worktrees[index].agentCwd : (group.cwd ?? this.config.cwd),
+          worktreePath: worktrees?.worktrees[index]?.path,
+          flatIndex: position.flatIndex + index,
+          interruptSignal,
+          sessionDir:
+            this.config.sessionDir === undefined || this.config.sessionDir.length === 0
+              ? undefined
+              : path.join(this.config.sessionDir, `parallel-${index}`),
+          flatStepCount: position.flatStepCount,
+          resetTiming: true,
+          trackSession: true,
+          notifyCompletionGuard: true,
+        }),
+    });
+  }
+
+  private ensureProgress(cwd: string, group: ParallelStepGroup): void {
+    const progressPath = path.join(cwd, "progress.md");
+    if (group.parallel.some((task) => task.task.includes(`Update progress at: ${progressPath}`))) {
+      writeInitialProgressFile(cwd);
+    }
+  }
+
+  private append(event: ReadonlyDeep<Record<string, unknown>>): void {
+    appendJsonl(path.join(this.config.asyncDir, "events.jsonl"), JSON.stringify(event));
+  }
+}