@emiliosp/pi-maestro 0.1.1 → 0.2.0

package/src/config/loadConfiguration.ts

@@ -3,15 +3,13 @@
  * Used: When Maestro initializes for a repository.
  */
 
-import { lstat, readFile, realpath } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
 import { assertConfiguration } from '#config/assertConfiguration.ts';
 import { CONFIG_FILE_PATH, DEFAULT_CONFIG } from '#config/defaults.ts';
 import type { MaestroConfig, PartialMaestroConfig } from '#config/schema.ts';
-import { isErrnoException } from '#utils/is-errno-exception.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
-import { isPathWithinOrEqual } from '#utils/path-within-or-equal.ts';
 
 const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => {
   const resolved: MaestroConfig = {
@@ -35,43 +33,6 @@ const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => {
   return resolved;
 };
 
-type ExistingAncestor = {
-  path: string;
-  realPath: string;
-};
-
-const findExistingAncestor = async (
-  path: string,
-): Promise<ExistingAncestor> => {
-  let anchestor = path;
-
-  while (true) {
-    try {
-      // lstat instead of access, because access follows symlinks
-      await lstat(anchestor);
-    } catch (error) {
-      if (!isErrnoException(error) || error.code !== 'ENOENT') {
-        throw error;
-      }
-
-      const parent = dirname(anchestor);
-
-      if (parent === anchestor) {
-        throw new Error(`Cannot resolve an existing ancestor for "${path}".`);
-      }
-
-      anchestor = parent;
-      continue;
-    }
-
-    try {
-      return { path: anchestor, realPath: await realpath(anchestor) };
-    } catch {
-      throw new Error(`Cannot resolve symlink "${anchestor}".`);
-    }
-  }
-};
-
 type AssertSafeDirectoryInput = {
   value: string;
   name: string;
@@ -96,11 +57,11 @@ type ResolveSafeDirectoryInput = {
   name: string;
 };
 
-const resolveSafeDirectory = async ({
+const resolveSafeDirectory = ({
   repositoryRoot,
   directory,
   name,
-}: ResolveSafeDirectoryInput): Promise<string> => {
+}: ResolveSafeDirectoryInput): string => {
   assertSafeDirectoryInput({ value: directory, name });
 
   const requestedDirectory = resolve(repositoryRoot, directory);
@@ -118,31 +79,7 @@ const resolveSafeDirectory = async ({
     throw new Error(`${name} must stay inside the Git root.`);
   }
 
-  // The directory could not exist at the check time. We find the existing anchestor and do the check on that.
-  const ancestor = await findExistingAncestor(requestedDirectory);
-
-  if (
-    !isPathWithinOrEqual({
-      parent: repositoryRoot,
-      candidate: ancestor.realPath,
-    })
-  ) {
-    throw new Error(`${name} resolves outside the Git root through a symlink.`);
-  }
-
-  const unresolvedSuffix = relative(ancestor.path, requestedDirectory);
-  const resolvedDirectory = resolve(ancestor.realPath, unresolvedSuffix);
-
-  if (
-    !isPathStrictlyWithin({
-      parent: repositoryRoot,
-      candidate: resolvedDirectory,
-    })
-  ) {
-    throw new Error(`${name} resolves outside the Git root through a symlink.`);
-  }
-
-  return resolvedDirectory;
+  return requestedDirectory;
 };
 
 type ResolveDirectoriesInput = {
@@ -150,13 +87,11 @@ type ResolveDirectoriesInput = {
   config: MaestroConfig;
 };
 
-const resolveDirectories = async ({
-  repositoryRoot: configuredRepositoryRoot,
+const resolveDirectories = ({
+  repositoryRoot,
   config,
-}: ResolveDirectoriesInput): Promise<MaestroConfig> => {
-  const repositoryRoot = await realpath(configuredRepositoryRoot);
-
-  const specDirectory = await resolveSafeDirectory({
+}: ResolveDirectoriesInput): MaestroConfig => {
+  const specDirectory = resolveSafeDirectory({
     repositoryRoot,
     directory: config.specDirectory,
     name: 'specDirectory',
@@ -186,7 +121,7 @@ export const loadConfiguration = async (
   const targetPath = join(repositoryRoot, CONFIG_FILE_PATH);
 
   if (!(await pathExists(targetPath))) {
-    return await resolveDirectories({ repositoryRoot, config: DEFAULT_CONFIG });
+    return resolveDirectories({ repositoryRoot, config: DEFAULT_CONFIG });
   }
 
   const parsed = await readConfigurationFile(targetPath);
@@ -194,5 +129,5 @@ export const loadConfiguration = async (
   assertConfiguration(parsed);
   const config = resolveConfiguration(parsed);
 
-  return await resolveDirectories({ repositoryRoot, config });
+  return resolveDirectories({ repositoryRoot, config });
 };

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -15,11 +15,11 @@ A builder escalation is an owner decision checkpoint, not only a technical failu
 
 If the approved contract must change from escalation-decision or findings-decision, the owner revises and approves the same specId, then calls maestro_mark_spec_ready. If a builder reports failed for a technical reason, Maestro reports the error and stops the workflow. The owner is responsible for the follow-up; there is no retry or spec revision from builder-failed.
 
-Use the deterministic maestro_* tools for workflow mutations, Git operations, artifact changes, and agent launches. Do not perform these mutations through generic tools.
+Use the deterministic maestro_* tools for workflow mutations, Git operations, artifact changes, and agent runs. Do not perform these mutations through generic tools.
 
 While Maestro mode is active, use generic tools to inspect and discuss the repository, but do not edit normal product files. Builder and verifier work through their dedicated handoff tools and do not communicate with the owner directly. Do not treat their conclusions as owner decisions.
 
-The verifier uses the parent of the verifier-running checkpoint as its candidate and must restore product changes before its handoff. The verifier handoff tool owns the protocol commit. The verifier handoff and finding resolution operations own the checks required to reach candidate-ready.
+The verifier uses the verifier-running checkpoint itself as its fixed candidate and must restore product changes before its handoff. The verifier handoff tool owns the protocol commit. The verifier handoff and finding resolution operations own the checks required to reach candidate-ready.
 
 The workflow ends at candidate-ready. No final tool call, checkpoint, or owner commit is required. You own the final summary. Use inspection tools to read the existing artifacts and Git information. Summarize the changes, verification results, rejected findings with their reasons, and applicable builder notes. Include the current branch and final HEAD after the protocol commit as the Pull Request facts. Do not present owner rejections as passed verification.
 

package/src/maestro/session/MaestroSessionState.ts

@@ -9,6 +9,7 @@ class MaestroSessionState {
   private active = false;
   private activeSpecId: string | null = null;
   private specSha256: string | null = null;
+  private verifierCheckpointCommit: string | null = null;
 
   public isActive = (): boolean => this.active;
 
@@ -34,6 +35,17 @@ class MaestroSessionState {
     this.specSha256 = await getFileSha256(specPath);
   };
 
+  public getVerifierCheckpointCommit = (): string | null =>
+    this.verifierCheckpointCommit;
+
+  public setVerifierCheckpointCommit = (commit: string): void => {
+    this.verifierCheckpointCommit = commit;
+  };
+
+  public clearVerifierCheckpointCommit = (): void => {
+    this.verifierCheckpointCommit = null;
+  };
+
   public activate = (): void => {
     this.active = true;
   };
@@ -41,6 +53,7 @@ class MaestroSessionState {
   public clearActiveSpecId = (): void => {
     this.activeSpecId = null;
     this.specSha256 = null;
+    this.clearVerifierCheckpointCommit();
   };
 
   public deactivate = (): void => {

package/src/maestro/status/refreshMaestroStatus.ts

@@ -6,7 +6,7 @@
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { formatMaestroStatus } from '#maestro/status/formatMaestroStatus.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 
 export const MAESTRO_STATUS_KEY = 'maestro';
@@ -32,7 +32,7 @@ export const refreshMaestroStatus = async (
   }
 
   try {
-    const { paths } = await resolveToolLaunchContext(context.cwd);
+    const { paths } = await resolveToolRunContext(context.cwd);
 
     const state = await readWorkflowState(paths.getWorkflowPath(specId));
 

package/src/tools/child/record-verifier-handoff.ts

@@ -11,10 +11,9 @@ import {
   VerifierFindingSchema,
 } from '#artifacts/verifier-handoff/schema.ts';
 import { createWorkflowCheckpointCommit } from '#git/commits/createWorkflowCheckpointCommit.ts';
-import { getParentCommit } from '#git/history/getParentCommit.ts';
-import { getHeadCommit } from '#git/repository/getHeadCommit.ts';
 import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import {
@@ -55,6 +54,14 @@ const isVerifierPassRejection = (
   result: VerifierPassResult,
 ): result is VerifierPassRejection => 'error' in result;
 
+function assertVerifierCheckpointCommit(
+  commit: string | null,
+): asserts commit is string {
+  if (commit === null) {
+    throw new Error('Verifier handoff requires a live verifier checkpoint.');
+  }
+}
+
 export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
   pi.registerTool({
     name: VERIFIER_HANDOFF_TOOL.NAME,
@@ -73,12 +80,9 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
         paths.getWorkflowPath(specId),
       );
 
-      const headCommit = await getHeadCommit(repositoryRoot);
+      const candidateCommit = maestroSessionState.getVerifierCheckpointCommit();
 
-      const candidateCommit = await getParentCommit({
-        repositoryRoot,
-        commit: headCommit,
-      });
+      assertVerifierCheckpointCommit(candidateCommit);
 
       const handoff = {
         version: VERIFIER_HANDOFF_VERSION,

package/src/tools/child/utils/resolveWorkflowContext.ts

@@ -4,7 +4,7 @@
  */
 
 import { isValidSpecId } from '#ids/isValidSpecId.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 
 export type ResolveWorkflowContextInput = {
   cwd: string;
@@ -19,7 +19,7 @@ export const resolveWorkflowContext = async ({
     throw new Error(`Invalid spec ID: "${specId}".`);
   }
 
-  const { paths, repositoryRoot } = await resolveToolLaunchContext(cwd);
+  const { paths, repositoryRoot } = await resolveToolRunContext(cwd);
 
   return { paths, specId, repositoryRoot };
 };

package/src/tools/main/create-spec.ts

@@ -7,7 +7,7 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { createSpec } from '#specs/create.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 
 export const CREATE_SPEC_TOOL = {
   NAME: 'maestro_create_spec',
@@ -30,7 +30,7 @@ export const registerCreateSpecTool = (pi: ExtensionAPI): void => {
     description: CREATE_SPEC_TOOL.DESCRIPTION,
     parameters: CreateSpecToolParameters,
     async execute(_toolCallId, { title }, _signal, _onUpdate, context) {
-      const { paths } = await resolveToolLaunchContext(context.cwd);
+      const { paths } = await resolveToolRunContext(context.cwd);
 
       const created = await createSpec({
         paths,

package/src/tools/main/mark-spec-ready.ts

@@ -7,14 +7,14 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { markSpecReady } from '#workflow/spec/markSpecReady.ts';
 
 export const MARK_SPEC_READY_TOOL = {
   NAME: 'maestro_mark_spec_ready',
   LABEL: 'Mark Spec Ready',
   DESCRIPTION:
-    'Approve the current spec.md after explicit owner approval and move the workflow to ready-for-builder. The owner must commit spec.md and workflow.json before launching the builder.',
+    'Approve the current spec.md after explicit owner approval and move the workflow to ready-for-builder. The owner must commit spec.md and workflow.json before running the builder.',
 } as const;
 
 const MarkSpecReadyToolParameters = Type.Object(
@@ -31,7 +31,7 @@ export const registerMarkSpecReadyTool = (pi: ExtensionAPI): void => {
     description: MARK_SPEC_READY_TOOL.DESCRIPTION,
     parameters: MarkSpecReadyToolParameters,
     async execute(_toolCallId, { specId }, _signal, _onUpdate, context) {
-      const { paths } = await resolveToolLaunchContext(context.cwd);
+      const { paths } = await resolveToolRunContext(context.cwd);
 
       const state = await markSpecReady({
         paths,
@@ -43,7 +43,7 @@ export const registerMarkSpecReadyTool = (pi: ExtensionAPI): void => {
         content: [
           {
             type: 'text',
-            text: `Spec ${state.specId} is approved at workflow revision ${state.revision} and ready-for-builder. Commit spec.md and workflow.json before launching the builder.`,
+            text: `Spec ${state.specId} is approved at workflow revision ${state.revision} and ready-for-builder. Commit spec.md and workflow.json before running the builder.`,
           },
         ],
         details: state,

package/src/tools/main/resolve-escalation.ts

@@ -10,14 +10,14 @@ import {
   EscalationResolutionSchema,
 } from '#artifacts/escalation/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { resolveBuilderEscalation } from '#workflow/escalation/resolveBuilderEscalation.ts';
 
 export const RESOLVE_ESCALATION_TOOL = {
   NAME: 'maestro_resolve_escalation',
   LABEL: 'Resolve Escalation',
   DESCRIPTION:
-    'Record the explicit owner decision for the current builder escalation when the approved contract remains valid. Commit the resolution and workflow transition on the current branch, then return ready-for-builder without launching the builder. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
+    'Record the explicit owner decision for the current builder escalation when the approved contract remains valid. Commit the resolution and workflow transition on the current branch, then return ready-for-builder without running the builder. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
 } as const;
 
 const ResolveEscalationToolParameters = Type.Object(
@@ -37,7 +37,7 @@ export const registerResolveEscalationTool = (pi: ExtensionAPI): void => {
     parameters: ResolveEscalationToolParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
       const { specId, escalationId, ...resolution } = params;
-      const { paths } = await resolveToolLaunchContext(context.cwd);
+      const { paths } = await resolveToolRunContext(context.cwd);
 
       const resolved = await resolveBuilderEscalation({
         paths,
@@ -50,7 +50,7 @@ export const registerResolveEscalationTool = (pi: ExtensionAPI): void => {
         content: [
           {
             type: 'text',
-            text: `Escalation ${resolved.escalation.id} resolved. Spec ${resolved.state.specId} is ready-for-builder. Launch the builder separately.`,
+            text: `Escalation ${resolved.escalation.id} resolved. Spec ${resolved.state.specId} is ready-for-builder. Run the builder separately.`,
           },
         ],
         details: {

package/src/tools/main/resolve-findings.ts

@@ -7,7 +7,7 @@ import { StringEnum } from '@earendil-works/pi-ai';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import {
   FINDING_DECISIONS,
   resolveFindings,
@@ -73,7 +73,7 @@ const formatResolution = (details: FindingResolutionDetails): string => {
   const requiringFix = formatFindingIds(details.findingsRequiringFixIds);
 
   if (details.phase === WORKFLOW_PHASES.READY_FOR_BUILDER) {
-    return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is ready-for-builder. Launch the builder separately.`;
+    return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is ready-for-builder. Run the builder separately.`;
   }
 
   return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is candidate-ready.`;
@@ -92,7 +92,7 @@ export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
       _onUpdate,
       context,
     ) {
-      const { paths } = await resolveToolLaunchContext(context.cwd);
+      const { paths } = await resolveToolRunContext(context.cwd);
 
       const resolved = await resolveFindings({
         paths,

package/src/tools/main/{launch-builder.ts → run-builder.ts}

@@ -1,6 +1,6 @@
 /**
- * Objective: Launch and validate one foreground builder pass for the owner session.
- * Used: When the owner invokes the launch-builder tool.
+ * Objective: Run and validate one foreground builder pass for the owner session.
+ * Used: When the owner invokes the run-builder tool.
  */
 
 import { randomUUID } from 'node:crypto';
@@ -22,20 +22,20 @@ import {
   assertDelegationResponse,
   waitForDelegationResponse,
 } from '#tools/utils/pi-subagent-delegation.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
-import { prepareBuilderLaunch } from '#workflow/builder/prepareBuilderLauncher.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
+import { prepareBuilderRun } from '#workflow/builder/prepareBuilderRun.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 
-export const LAUNCH_BUILDER_TOOL = {
-  NAME: 'maestro_launch_builder',
-  LABEL: 'Launch Builder',
+export const RUN_BUILDER_TOOL = {
+  NAME: 'maestro_run_builder',
+  LABEL: 'Run Builder',
   DESCRIPTION:
-    'Launch the builder in the current checkout for an owner-approved spec. The builder runs in the foreground and cannot be retried after a committed failure.',
+    'Run the builder in the current checkout for an owner-approved spec. The builder runs in the foreground and cannot be retried after a committed failure.',
 } as const;
 
-const LaunchBuilderToolParameters = Type.Object(
+const RunBuilderToolParameters = Type.Object(
   {
     specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
   },
@@ -44,7 +44,7 @@ const LaunchBuilderToolParameters = Type.Object(
 
 const MILLISECONDS_PER_MINUTE = 60_000;
 
-type BuilderLaunchResult =
+type BuilderRunResult =
   | {
       outcome: typeof BUILDER_HANDOFF_STATUSES.DONE;
       specId: string;
@@ -75,7 +75,7 @@ type ReadCommittedBuilderResultInput = {
 const readCommittedBuilderResult = async ({
   paths,
   specId,
-}: ReadCommittedBuilderResultInput): Promise<BuilderLaunchResult> => {
+}: ReadCommittedBuilderResultInput): Promise<BuilderRunResult> => {
   try {
     const repositoryStatus = await getRepositoryStatus(
       paths.getRepositoryRoot(),
@@ -95,7 +95,7 @@ const readCommittedBuilderResult = async ({
       );
     }
 
-    return await buildLaunchResult({ paths, specId, state });
+    return await buildRunResult({ paths, specId, state });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
 
@@ -117,7 +117,7 @@ const readTerminalBuilderResult = async ({
   specId,
   revision,
   phase,
-}: ReadTerminalBuilderResultInput): Promise<BuilderLaunchResult> => {
+}: ReadTerminalBuilderResultInput): Promise<BuilderRunResult> => {
   const handoff = await readBuilderHandoff({
     path: paths.getBuilderHandoffPath(specId),
     specId,
@@ -154,17 +154,17 @@ const readTerminalBuilderResult = async ({
   };
 };
 
-type BuildLaunchResultInput = {
+type BuildRunResultInput = {
   paths: MaestroPaths;
   specId: string;
   state: WorkflowState;
 };
 
-const buildLaunchResult = async ({
+const buildRunResult = async ({
   paths,
   specId,
   state,
-}: BuildLaunchResultInput): Promise<BuilderLaunchResult> => {
+}: BuildRunResultInput): Promise<BuilderRunResult> => {
   if (
     state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER ||
     state.phase === WORKFLOW_PHASES.BUILDER_FAILED
@@ -210,7 +210,7 @@ const buildLaunchResult = async ({
   );
 };
 
-const formatBuilderResult = (result: BuilderLaunchResult): string => {
+const formatBuilderResult = (result: BuilderRunResult): string => {
   if (result.outcome === BUILDER_HANDOFF_STATUSES.DONE) {
     return `Builder completed spec ${result.specId}. The workflow is ready-for-verifier.`;
   }
@@ -222,16 +222,16 @@ const formatBuilderResult = (result: BuilderLaunchResult): string => {
   return `Builder opened escalation ${result.escalation.id} for spec ${result.specId}. The workflow is waiting for an owner decision.`;
 };
 
-export const registerLaunchBuilderTool = (pi: ExtensionAPI): void => {
+export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
   pi.registerTool({
-    name: LAUNCH_BUILDER_TOOL.NAME,
-    label: LAUNCH_BUILDER_TOOL.LABEL,
-    description: LAUNCH_BUILDER_TOOL.DESCRIPTION,
-    parameters: LaunchBuilderToolParameters,
+    name: RUN_BUILDER_TOOL.NAME,
+    label: RUN_BUILDER_TOOL.LABEL,
+    description: RUN_BUILDER_TOOL.DESCRIPTION,
+    parameters: RunBuilderToolParameters,
     async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
-      const { paths, config } = await resolveToolLaunchContext(context.cwd);
+      const { paths, config } = await resolveToolRunContext(context.cwd);
 
-      const launch = await prepareBuilderLaunch({ paths, specId });
+      const run = await prepareBuilderRun({ paths, specId });
 
       const request: SubagentDelegationRequest = {
         requestId: randomUUID(),
@@ -240,9 +240,9 @@ export const registerLaunchBuilderTool = (pi: ExtensionAPI): void => {
         // pi-subagents loads this name from agents/builder.md through package.json.
         // See docs/subagent-integration.md.
         agent: AGENTS.BUILDER,
-        task: `Implement specId "${specId}" in the current checkout "${launch.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
+        task: `Implement specId "${specId}" in the current checkout "${run.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
         context: 'fresh',
-        cwd: launch.repositoryRoot,
+        cwd: run.repositoryRoot,
         model: config.builder.model,
         thinking: config.builder.thinking,
         timeoutMs: config.builder.timeoutMinutes * MILLISECONDS_PER_MINUTE,