@emiliosp/pi-maestro 0.1.1 → 0.1.2

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,

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

@@ -1,6 +1,6 @@
 /**
- * Objective: Launch and validate one foreground verifier pass for the owner session.
- * Used: When the owner invokes the launch-verifier tool.
+ * Objective: Run and validate one foreground verifier pass for the owner session.
+ * Used: When the owner invokes the run-verifier tool.
  */
 
 import { randomUUID } from 'node:crypto';
@@ -13,11 +13,12 @@ import { AGENTS } from '#config/schema.ts';
 import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
+import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import {
   assertDelegationResponse,
   waitForDelegationResponse,
 } from '#tools/utils/pi-subagent-delegation.ts';
-import { resolveToolLaunchContext } from '#tools/utils/resolveToolLaunchContext.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.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';
@@ -27,18 +28,18 @@ import {
 } from '#workflow/verifier/completeVerifierPass.ts';
 import { hasProductChanges } from '#workflow/verifier/hasProductChanges.ts';
 import {
-  prepareVerifierLaunch,
-  type VerifierLaunch,
-} from '#workflow/verifier/prepareVerifierLaunch.ts';
+  prepareVerifierRun,
+  type VerifierRun,
+} from '#workflow/verifier/prepareVerifierRun.ts';
 
-export const LAUNCH_VERIFIER_TOOL = {
-  NAME: 'maestro_launch_verifier',
-  LABEL: 'Launch Verifier',
+export const RUN_VERIFIER_TOOL = {
+  NAME: 'maestro_run_verifier',
+  LABEL: 'Run Verifier',
   DESCRIPTION:
-    'Launch the verifier in the current checkout for a completed builder candidate. The verifier runs in the foreground.',
+    'Run the verifier in the current checkout for a completed builder candidate. The verifier runs in the foreground.',
 } as const;
 
-const LaunchVerifierToolParameters = Type.Object(
+const RunVerifierToolParameters = Type.Object(
   {
     specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
   },
@@ -78,7 +79,7 @@ type ProductChangesResult = {
   checkpointCommit: string;
 };
 
-type VerifierLaunchResult =
+type VerifierRunResult =
   | CandidateReadyResult
   | FindingsResult
   | ProductChangesResult;
@@ -86,7 +87,7 @@ type VerifierLaunchResult =
 type ReadTerminalVerifierResultInput = {
   paths: MaestroPaths;
   specId: string;
-  launch: VerifierLaunch;
+  run: VerifierRun;
   state: WorkflowState;
   productChanges: boolean;
 };
@@ -94,7 +95,7 @@ type ReadTerminalVerifierResultInput = {
 const readTerminalVerifierResult = async ({
   paths,
   specId,
-  launch,
+  run,
   state,
   productChanges,
 }: ReadTerminalVerifierResultInput): Promise<
@@ -115,7 +116,7 @@ const readTerminalVerifierResult = async ({
     );
   }
 
-  const repositoryStatus = await getRepositoryStatus(launch.repositoryRoot);
+  const repositoryStatus = await getRepositoryStatus(run.repositoryRoot);
 
   if (!repositoryStatus.clean) {
     throw new Error(
@@ -143,8 +144,8 @@ const readTerminalVerifierResult = async ({
   const details = {
     specId,
     revision: state.revision,
-    candidateCommit: launch.candidateCommit,
-    checkpointCommit: launch.checkpointCommit,
+    candidateCommit: run.candidateCommit,
+    checkpointCommit: run.checkpointCommit,
     handoff,
   };
 
@@ -158,14 +159,14 @@ const readTerminalVerifierResult = async ({
 type ReadVerifierResultInput = {
   paths: MaestroPaths;
   specId: string;
-  launch: VerifierLaunch;
+  run: VerifierRun;
 };
 
 const readVerifierResult = async ({
   paths,
   specId,
-  launch,
-}: ReadVerifierResultInput): Promise<VerifierLaunchResult> => {
+  run,
+}: ReadVerifierResultInput): Promise<VerifierRunResult> => {
   try {
     const state = await readWorkflowState(paths.getWorkflowPath(specId));
 
@@ -176,8 +177,8 @@ const readVerifierResult = async ({
     }
 
     const productChanges = await hasProductChanges({
-      repositoryRoot: launch.repositoryRoot,
-      candidateCommit: launch.candidateCommit,
+      repositoryRoot: run.repositoryRoot,
+      candidateCommit: run.candidateCommit,
       workflowPath: paths.getWorkflowPath(specId),
       handoffPath: paths.getVerifierHandoffPath(specId),
     });
@@ -191,8 +192,8 @@ const readVerifierResult = async ({
           specId,
           revision: state.revision,
           phase: state.phase,
-          candidateCommit: launch.candidateCommit,
-          checkpointCommit: launch.checkpointCommit,
+          candidateCommit: run.candidateCommit,
+          checkpointCommit: run.checkpointCommit,
         };
       }
 
@@ -204,7 +205,7 @@ const readVerifierResult = async ({
     return await readTerminalVerifierResult({
       paths,
       specId,
-      launch,
+      run,
       state,
       productChanges,
     });
@@ -215,7 +216,7 @@ const readVerifierResult = async ({
   }
 };
 
-const formatVerifierResult = (result: VerifierLaunchResult): string => {
+const formatVerifierResult = (result: VerifierRunResult): string => {
   if (result.outcome === WORKFLOW_PHASES.CANDIDATE_READY) {
     return `Verifier completed spec ${result.specId}. The workflow is candidate-ready.`;
   }
@@ -227,44 +228,48 @@ const formatVerifierResult = (result: VerifierLaunchResult): string => {
   return `${result.message} The workflow remains verifier-running.`;
 };
 
-export const registerLaunchVerifierTool = (pi: ExtensionAPI): void => {
+export const registerRunVerifierTool = (pi: ExtensionAPI): void => {
   pi.registerTool({
-    name: LAUNCH_VERIFIER_TOOL.NAME,
-    label: LAUNCH_VERIFIER_TOOL.LABEL,
-    description: LAUNCH_VERIFIER_TOOL.DESCRIPTION,
-    parameters: LaunchVerifierToolParameters,
+    name: RUN_VERIFIER_TOOL.NAME,
+    label: RUN_VERIFIER_TOOL.LABEL,
+    description: RUN_VERIFIER_TOOL.DESCRIPTION,
+    parameters: RunVerifierToolParameters,
     async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
-      const { paths, config } = await resolveToolLaunchContext(context.cwd);
-
-      const launch = await prepareVerifierLaunch({ paths, specId });
-
-      const request: SubagentDelegationRequest = {
-        requestId: randomUUID(),
-        ownerRunId: toolCallId,
-        nodeId: WORKFLOW_ROLES.VERIFIER,
-        // pi-subagents loads this name from agents/verifier.md through package.json.
-        agent: AGENTS.VERIFIER,
-        task: `Verify specId "${specId}" in the current checkout "${launch.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
-        context: 'fresh',
-        cwd: launch.repositoryRoot,
-        model: config.verifier.model,
-        thinking: config.verifier.thinking,
-        timeoutMs: config.verifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
-        result: { kind: 'text' },
-      };
-
-      const response = await waitForDelegationResponse({
-        piEventsBus: pi.events,
-        request,
-      });
-
-      assertDelegationResponse(response);
-      const result = await readVerifierResult({ paths, specId, launch });
-
-      return {
-        content: [{ type: 'text', text: formatVerifierResult(result) }],
-        details: result,
-      };
+      const { paths, config } = await resolveToolRunContext(context.cwd);
+
+      const run = await prepareVerifierRun({ paths, specId });
+
+      try {
+        const request: SubagentDelegationRequest = {
+          requestId: randomUUID(),
+          ownerRunId: toolCallId,
+          nodeId: WORKFLOW_ROLES.VERIFIER,
+          // pi-subagents loads this name from agents/verifier.md through package.json.
+          agent: AGENTS.VERIFIER,
+          task: `Verify specId "${specId}" at candidate checkpoint "${run.candidateCommit}" in the current checkout "${run.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
+          context: 'fresh',
+          cwd: run.repositoryRoot,
+          model: config.verifier.model,
+          thinking: config.verifier.thinking,
+          timeoutMs: config.verifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
+          result: { kind: 'text' },
+        };
+
+        const response = await waitForDelegationResponse({
+          piEventsBus: pi.events,
+          request,
+        });
+
+        assertDelegationResponse(response);
+        const result = await readVerifierResult({ paths, specId, run });
+
+        return {
+          content: [{ type: 'text', text: formatVerifierResult(result) }],
+          details: result,
+        };
+      } finally {
+        maestroSessionState.clearVerifierCheckpointCommit();
+      }
     },
   });
 };

package/src/tools/utils/pi-subagent-delegation.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Coordinate foreground pi-subagents delegation responses.
- * Used: By Pi tools that launch pi-subagents agents.
+ * Used: By Pi tools that run pi-subagents agents.
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';

package/src/tools/utils/{resolveToolLaunchContext.ts → resolveToolRunContext.ts}

@@ -8,15 +8,15 @@ import type { MaestroConfig } from '#config/schema.ts';
 import { findRepositoryRoot } from '#git/repository/findRepositoryRoot.ts';
 import { MaestroPaths } from '#MaestroPaths.ts';
 
-export type ToolLaunchContext = {
+export type ToolRunContext = {
   repositoryRoot: string;
   config: MaestroConfig;
   paths: MaestroPaths;
 };
 
-export const resolveToolLaunchContext = async (
+export const resolveToolRunContext = async (
   cwd: string,
-): Promise<ToolLaunchContext> => {
+): Promise<ToolRunContext> => {
   const repositoryRoot = await findRepositoryRoot(cwd);
   const config = await loadConfiguration(repositoryRoot);
 

package/src/workflow/builder/assertBuilderProtocolUnchanged.ts

@@ -26,6 +26,8 @@ export async function assertBuilderProtocolUnchanged({
   const actualSpecSha256 = await getFileSha256(specPath);
 
   if (actualSpecSha256 !== expectedSpecSha256) {
-    throw new Error(`Builder changed spec.md after launch: "${specPath}".`);
+    throw new Error(
+      `Builder changed spec.md after the run starts: "${specPath}".`,
+    );
   }
 }