@emiliosp/pi-maestro 0.1.1 → 0.2.0

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}".`,
+    );
   }
 }

package/src/workflow/builder/{prepareBuilderLauncher.ts → prepareBuilderRun.ts}

@@ -1,6 +1,6 @@
 /**
- * Objective: Prepare a committed builder launch checkpoint in the current checkout.
- * Used: Before Maestro launches a builder pass.
+ * Objective: Prepare a committed builder run checkpoint in the current checkout.
+ * Used: Before Maestro runs a builder pass.
  */
 
 import { rm } from 'node:fs/promises';
@@ -14,22 +14,22 @@ import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
-export type BuilderLaunch = {
+export type BuilderRun = {
   specId: string;
   revision: number;
   repositoryRoot: string;
   checkpointCommit: string;
 };
 
-type AssertBuilderLaunchBaseInput = {
+type AssertBuilderRunBaseInput = {
   paths: MaestroPaths;
   specId: string;
 };
 
-async function assertBuilderLaunchBase({
+async function assertBuilderRunBase({
   paths,
   specId,
-}: AssertBuilderLaunchBaseInput): Promise<void> {
+}: AssertBuilderRunBaseInput): Promise<void> {
   const state = await readWorkflowState(paths.getWorkflowPath(specId));
 
   if (state.specId !== specId) {
@@ -39,13 +39,13 @@ async function assertBuilderLaunchBase({
   }
 
   if (state.phase !== WORKFLOW_PHASES.READY_FOR_BUILDER) {
-    throw new Error(`Builder launch is not valid from phase "${state.phase}".`);
+    throw new Error(`Builder run is not valid from phase "${state.phase}".`);
   }
 
   const status = await getRepositoryStatus(paths.getRepositoryRoot());
 
   if (!status.clean) {
-    throw new Error('Builder launch requires a clean current checkout.');
+    throw new Error('Builder run requires a clean current checkout.');
   }
 
   if (!(await pathExists(paths.getSpecFilePath(specId)))) {
@@ -53,24 +53,24 @@ async function assertBuilderLaunchBase({
   }
 }
 
-type PrepareBuilderLaunchInput = {
+type PrepareBuilderRunInput = {
   paths: MaestroPaths;
   specId: string;
 };
 
-export const prepareBuilderLaunch = async ({
+export const prepareBuilderRun = async ({
   paths,
   specId,
-}: PrepareBuilderLaunchInput): Promise<BuilderLaunch> => {
+}: PrepareBuilderRunInput): Promise<BuilderRun> => {
   const activeSpecId = maestroSessionState.getActiveSpecId();
 
   if (activeSpecId !== specId) {
     throw new Error(
-      `Builder launch requires active Maestro spec "${specId}", found "${activeSpecId ?? 'none'}".`,
+      `Builder run requires active Maestro spec "${specId}", found "${activeSpecId ?? 'none'}".`,
     );
   }
 
-  await assertBuilderLaunchBase({ paths, specId });
+  await assertBuilderRunBase({ paths, specId });
 
   const workflowPath = paths.getWorkflowPath(specId);
   const handoffPath = paths.getBuilderHandoffPath(specId);
@@ -83,7 +83,7 @@ export const prepareBuilderLaunch = async ({
 
   const nextState = transitionWorkflow({
     state: currentState,
-    event: WORKFLOW_EVENTS.LAUNCH_BUILDER,
+    event: WORKFLOW_EVENTS.RUN_BUILDER,
   });
 
   await writeWorkflowState({

package/src/workflow/state/schema.ts

@@ -23,13 +23,12 @@ export const WORKFLOW_PHASES = {
 
 export const WORKFLOW_EVENTS = {
   MARK_SPEC_READY: 'mark-spec-ready',
-  LAUNCH_BUILDER: 'launch-builder',
+  RUN_BUILDER: 'run-builder',
   OPEN_ESCALATION: 'open-escalation',
   RESOLVE_ESCALATION: 'resolve-escalation',
   BUILDER_FAILED: 'builder-failed',
   BUILDER_DONE: 'builder-done',
-  LAUNCH_VERIFIER: 'launch-verifier',
-  RETRY_VERIFIER: 'retry-verifier',
+  RUN_VERIFIER: 'run-verifier',
   VERIFIER_FOUND_FINDINGS: 'verifier-found-findings',
   VERIFIER_APPROVED: 'verifier-approved',
   REJECT_FINDINGS: 'reject-findings',

package/src/workflow/transitions.ts

@@ -26,7 +26,7 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
     ],
     to: WORKFLOW_PHASES.READY_FOR_BUILDER,
   },
-  [WORKFLOW_EVENTS.LAUNCH_BUILDER]: {
+  [WORKFLOW_EVENTS.RUN_BUILDER]: {
     from: [WORKFLOW_PHASES.READY_FOR_BUILDER],
     to: WORKFLOW_PHASES.BUILDER_RUNNING,
   },
@@ -46,14 +46,10 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
     from: [WORKFLOW_PHASES.BUILDER_RUNNING],
     to: WORKFLOW_PHASES.READY_FOR_VERIFIER,
   },
-  [WORKFLOW_EVENTS.LAUNCH_VERIFIER]: {
+  [WORKFLOW_EVENTS.RUN_VERIFIER]: {
     from: [WORKFLOW_PHASES.READY_FOR_VERIFIER],
     to: WORKFLOW_PHASES.VERIFIER_RUNNING,
   },
-  [WORKFLOW_EVENTS.RETRY_VERIFIER]: {
-    from: [WORKFLOW_PHASES.VERIFIER_RUNNING],
-    to: WORKFLOW_PHASES.VERIFIER_RUNNING,
-  },
   [WORKFLOW_EVENTS.VERIFIER_FOUND_FINDINGS]: {
     from: [WORKFLOW_PHASES.VERIFIER_RUNNING],
     to: WORKFLOW_PHASES.FINDINGS_DECISION,

package/src/workflow/verifier/{prepareVerifierLaunch.ts → prepareVerifierRun.ts}

@@ -1,21 +1,20 @@
 /**
- * Objective: Prepare a committed verifier launch checkpoint in the current checkout.
+ * Objective: Prepare a committed verifier run checkpoint in the current checkout.
  * Used: When Maestro starts a verifier pass.
  */
 
 import { rm } from 'node:fs/promises';
 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 type { MaestroPaths } from '#MaestroPaths.ts';
+import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
-export type VerifierLaunch = {
+export type VerifierRun = {
   specId: string;
   repositoryRoot: string;
   candidateCommit: string;
@@ -23,15 +22,15 @@ export type VerifierLaunch = {
   revision: number;
 };
 
-type PrepareVerifierLaunchInput = {
+type PrepareVerifierRunInput = {
   paths: MaestroPaths;
   specId: string;
 };
 
-export const prepareVerifierLaunch = async ({
+export const prepareVerifierRun = async ({
   paths,
   specId,
-}: PrepareVerifierLaunchInput): Promise<VerifierLaunch> => {
+}: PrepareVerifierRunInput): Promise<VerifierRun> => {
   const repositoryRoot = paths.getRepositoryRoot();
   const workflowPath = paths.getWorkflowPath(specId);
   const handoffPath = paths.getVerifierHandoffPath(specId);
@@ -45,7 +44,7 @@ export const prepareVerifierLaunch = async ({
 
   if (currentState.phase !== WORKFLOW_PHASES.READY_FOR_VERIFIER) {
     throw new Error(
-      `Verifier launch requires ready-for-verifier state, found "${currentState.phase}".`,
+      `Verifier run requires ready-for-verifier state, found "${currentState.phase}".`,
     );
   }
 
@@ -53,13 +52,13 @@ export const prepareVerifierLaunch = async ({
 
   if (!status.clean) {
     throw new Error(
-      'Verifier launch requires a committed ready-for-verifier candidate.',
+      'Verifier run requires a committed ready-for-verifier candidate.',
     );
   }
 
   const nextState = transitionWorkflow({
     state: currentState,
-    event: WORKFLOW_EVENTS.LAUNCH_VERIFIER,
+    event: WORKFLOW_EVENTS.RUN_VERIFIER,
   });
 
   const handoffExists = await pathExists(handoffPath);
@@ -80,28 +79,17 @@ export const prepareVerifierLaunch = async ({
     expectedPaths.push(handoffPath);
   }
 
-  const previousHead = await getHeadCommit(repositoryRoot);
-
   const checkpointCommit = await createWorkflowCheckpointCommit({
     repositoryRoot,
     expectedPaths,
   });
 
-  const candidateCommit = await getParentCommit({
-    repositoryRoot,
-    commit: checkpointCommit,
-  });
-
-  if (candidateCommit !== previousHead) {
-    throw new Error(
-      'Verifier candidate changed while creating its checkpoint.',
-    );
-  }
+  maestroSessionState.setVerifierCheckpointCommit(checkpointCommit);
 
   return {
     specId,
     repositoryRoot,
-    candidateCommit,
+    candidateCommit: checkpointCommit,
     checkpointCommit,
     revision: nextState.revision,
   };