@wichayutdew/pi-workflows 1.0.1 → 2.0.0

package/src/harness/delegation-retry-policy.ts

@@ -32,6 +32,9 @@ export function delegationFailureFingerprint(
           tool: normalizedFingerprintField(failure.diagnostic.tool),
           call: normalizedFingerprintField(failure.diagnostic.call),
           output: normalizedFingerprintField(failure.diagnostic.output),
+          postCompletionWarning: normalizedFingerprintField(
+            failure.diagnostic.postCompletionWarning,
+          ),
         }
       : undefined,
   });
@@ -62,6 +65,7 @@ export function isRetryableTerminalFailure(
   failure: DelegationFailureDetails,
 ): boolean {
   if (failure.recoveryBlocker !== undefined) return false;
+  if (failure.diagnostic?.postCompletionWarning !== undefined) return false;
   if (
     failure.status === 'timed_out' ||
     failure.status === 'turn_budget_exhausted' ||
@@ -96,9 +100,7 @@ export function isSafeToRetryDelegation(
 ): boolean {
   return (
     replayAudit?.replaySafe === true &&
-    (isReplayExplicitlyAuthorized ||
-      policy.permissions.bash.mode === 'deny' ||
-      policy.permissions.bash.mode === 'read-only')
+    (isReplayExplicitlyAuthorized || policy.permissions.bash.mode === 'deny')
   );
 }
 

package/src/harness/dependencies.ts

@@ -15,6 +15,7 @@ import {
   type SubagentDelegationClientController,
 } from '../integrations/subagents/client.ts';
 import {
+  auditCompletedDelegationTranscript,
   readDelegationReplayAudit,
   readToolFailureDiagnostic,
 } from '../integrations/subagents/diagnostics.ts';
@@ -28,6 +29,10 @@ import {
 } from '../runtime/serial-task-queue.ts';
 import { showWorkflowStatus } from '../workflow-status.ts';
 import type { ActiveDelegation } from './types.ts';
+import {
+  resolveWorkspaceDirectory,
+  type ResolveWorkspaceDirectoryOptions,
+} from './workspace-directory.ts';
 
 const MAX_DELEGATED_RESULT_BYTES = 1024 * 1024;
 
@@ -47,14 +52,17 @@ export type WorkflowHarnessDependencies = {
   readonly removeDelegationWorkspace: (
     resultDirectory: string,
   ) => Promise<void>;
-  readonly currentWorkingDirectory: () => string;
   readonly waitForDelay: (delayMs: number) => Promise<void>;
+  readonly resolveWorkspaceDirectory: (
+    options: ResolveWorkspaceDirectoryOptions,
+  ) => string;
   readonly loadCatalog: typeof loadCatalog;
   readonly requestPlannotatorReview: typeof requestPlannotatorReview;
   readonly requestPlannotatorReviewStatus: typeof requestPlannotatorReviewStatus;
   readonly requestPromptGateReview: typeof requestPromptGateReview;
   readonly readDelegationReplayAudit: typeof readDelegationReplayAudit;
   readonly readToolFailureDiagnostic: typeof readToolFailureDiagnostic;
+  readonly auditCompletedDelegationTranscript: typeof auditCompletedDelegationTranscript;
   readonly showWorkflowStatus: typeof showWorkflowStatus;
   readonly createSubagentClient: (
     pi: ExtensionAPI,
@@ -132,15 +140,16 @@ const DEFAULT_DEPENDENCIES: WorkflowHarnessDependencies = {
   readDelegatedResult,
   removeDelegationWorkspace: async (resultDirectory) =>
     rm(resultDirectory, { recursive: true, force: true }),
-  currentWorkingDirectory: () => process.cwd(),
   waitForDelay: async (delayMs) =>
     new Promise((resolve) => setTimeout(resolve, delayMs)),
+  resolveWorkspaceDirectory,
   loadCatalog,
   requestPlannotatorReview,
   requestPlannotatorReviewStatus,
   requestPromptGateReview,
   readDelegationReplayAudit,
   readToolFailureDiagnostic,
+  auditCompletedDelegationTranscript,
   showWorkflowStatus,
   createSubagentClient: (pi) => createSubagentDelegationClient(pi.events),
   createMainStepRuntime: (pi) => createMainStepRuntime({ pi }),

package/src/harness/gate-submission-action.ts

@@ -5,10 +5,9 @@ import {
   beginGate,
   failGate,
   failRun,
-  resolveGate,
 } from '../engine/transitions.ts';
-import { reviewedCommandShapeError } from '../policy/approved-commands.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { reportFailedStep } from './step-reporting.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
@@ -21,7 +20,6 @@ type HarnessActionContext = Pick<
   | 'restoreBaselineTools'
   | 'run'
   | 'sessionEpoch'
-  | 'settleAfterTransition'
   | 'updateStatus'
 >;
 
@@ -31,6 +29,7 @@ export type GateSubmissionAction = {
     workflow: LoadedWorkflow,
     originalRun: WorkflowRun,
     outcome: string,
+    summary: string,
     artifact: string,
   ) => Promise<void>;
 };
@@ -55,6 +54,7 @@ async function submitGate(
   workflow: LoadedWorkflow,
   originalRun: WorkflowRun,
   outcome: string,
+  summary: string,
   artifact: string,
 ): Promise<void> {
   const requestSessionEpoch = this.sessionEpoch;
@@ -64,34 +64,6 @@ async function submitGate(
   const step = workflow.definition.steps[originalRun.currentStepId];
   if (!step?.gate) throw new Error('Current step has no gate');
 
-  const commandShapeError = reviewedCommandShapeError(artifact);
-  if (commandShapeError) {
-    const awaitingReview = beginGate(
-      workflow,
-      originalRun,
-      outcome,
-      artifact,
-      requestId,
-      this.dependencies.now(),
-    );
-    this.run = resolveGate(
-      workflow,
-      awaitingReview,
-      {
-        approved: false,
-        feedback: commandShapeError,
-        resolvedAt: this.dependencies.now(),
-      },
-      this.dependencies.now(),
-    );
-    this.latestContext?.ui.notify(
-      `Plan contract needs repair before review: ${commandShapeError}`,
-      'warning',
-    );
-    this.settleAfterTransition(workflow);
-    return;
-  }
-
   this.run = beginGate(
     workflow,
     originalRun,
@@ -99,6 +71,7 @@ async function submitGate(
     artifact,
     requestId,
     this.dependencies.now(),
+    summary,
   );
   this.persist();
   this.restoreBaselineTools();
@@ -129,6 +102,7 @@ async function submitGate(
     const gateFailed = failGate(currentRun, reason, this.dependencies.now());
     this.run = failRun(gateFailed, reason, this.dependencies.now());
     this.persist();
+    reportFailedStep(this.pi, workflow, this.run, reason);
     this.restoreBaselineTools();
     this.updateStatus();
     throw new Error(reason);

package/src/harness/lifecycle-actions.ts

@@ -3,6 +3,7 @@ import { buildMainWorkflowNotice } from '../prompt.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
 import { parseAvailableSkills } from './catalog.ts';
 import { waitForEventContextIdle } from './context-idle.ts';
+import { reportFailedStep } from './step-reporting.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
@@ -126,12 +127,10 @@ function registerPolicy(this: HarnessActionContext): void {
     if (!this.run || this.run.status !== 'running') return;
     const workflow = this.catalog.workflows.get(this.run.workflowId);
     if (!workflow) {
-      this.run = failRun(
-        this.run,
-        'Workflow configuration disappeared; reload or restore it',
-        this.dependencies.now(),
-      );
+      const reason = 'Workflow configuration disappeared; reload or restore it';
+      this.run = failRun(this.run, reason, this.dependencies.now());
       this.persist();
+      reportFailedStep(this.pi, undefined, this.run, reason);
       this.restoreBaselineTools();
       this.updateStatus();
       return;

package/src/harness/pause-actions.ts

@@ -1,15 +1,18 @@
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { abortRun, pauseRun } from '../engine/transitions.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { conciseStepPauseSummary, reportPausedStep } from './step-reporting.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
   | 'cancelActiveDelegation'
   | 'cancelPromptReview'
+  | 'catalog'
   | 'dependencies'
   | 'isolateMainSessionTools'
   | 'mainSteps'
   | 'persist'
+  | 'pi'
   | 'restoreBaselineTools'
   | 'run'
   | 'updateStatus'
@@ -60,6 +63,12 @@ async function pauseNow(
 
   this.run = pauseRun(this.run, reason, this.dependencies.now());
   this.persist();
+  reportPausedStep(
+    this.pi,
+    this.catalog.workflows.get(this.run.workflowId),
+    this.run,
+    this.run.pauseReason ?? reason,
+  );
   if (isCancellationConfirmed) {
     this.restoreBaselineTools();
   } else {
@@ -68,7 +77,7 @@ async function pauseNow(
   this.updateStatus();
   context.ui.notify(
     isCancellationConfirmed
-      ? `Paused "${this.run.workflowId}" at step "${this.run.currentStepId}". Fix the issue, then run /workflow-resume.`
+      ? `Paused "${this.run.workflowId}" at step "${this.run.currentStepId}": ${conciseStepPauseSummary(this.run.pauseReason ?? reason)}`
       : `Pause recorded at "${this.run.currentStepId}", but child cancellation is not confirmed. Main tools remain isolated until it exits.`,
     isCancellationConfirmed ? 'info' : 'warning',
   );

package/src/harness/plannotator-result-actions.ts

@@ -9,6 +9,7 @@ import {
   PLANNOTATOR_RESULT_CHANNEL,
 } from '../integrations/plannotator.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { reportFailedStep } from './step-reporting.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
@@ -85,31 +86,39 @@ async function handlePlannotatorResult(
 
   const workflow = this.catalog.workflows.get(this.run.workflowId);
   if (!workflow) {
-    this.run = failRun(
-      this.run,
-      'Gate result arrived, but workflow configuration is unavailable',
-      this.dependencies.now(),
-    );
+    const reason =
+      'Gate result arrived, but workflow configuration is unavailable';
+    this.run = failRun(this.run, reason, this.dependencies.now());
     this.persist();
+    reportFailedStep(this.pi, undefined, this.run, reason);
     this.restoreBaselineTools();
     this.updateStatus();
     return;
   }
   try {
+    const stepId = this.run.currentStepId;
+    const gate = workflow.definition.steps[stepId]?.gate;
+    if (!gate) throw new Error(`gated step "${stepId}" no longer exists`);
     this.run = resolveGate(
       workflow,
       this.run,
       resolution,
       this.dependencies.now(),
     );
-    this.settleAfterTransition(workflow);
+    this.settleAfterTransition(workflow, {
+      stepId,
+      outcome: resolution.approved
+        ? gate.approvedOutcome
+        : gate.rejectedOutcome,
+      summary: this.run.lastSummary,
+    });
   } catch (error) {
-    this.run = failRun(
-      this.run,
-      `Cannot apply gate result: ${error instanceof Error ? error.message : String(error)}`,
-      this.dependencies.now(),
-    );
+    const reason = `Cannot apply gate result: ${
+      error instanceof Error ? error.message : String(error)
+    }`;
+    this.run = failRun(this.run, reason, this.dependencies.now());
     this.persist();
+    reportFailedStep(this.pi, workflow, this.run, reason);
     this.restoreBaselineTools();
     this.updateStatus();
   }

package/src/harness/prompt-gate-actions.ts

@@ -9,6 +9,12 @@ import {
 } from '../engine/transitions.ts';
 import type { PromptGateReviewResult } from '../integrations/prompt-gate.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import {
+  conciseStepFailureSummary,
+  conciseStepPauseSummary,
+  reportFailedStep,
+  reportPausedStep,
+} from './step-reporting.ts';
 import type { ActivePromptReview } from './types.ts';
 
 type HarnessActionContext = Pick<
@@ -23,6 +29,7 @@ type HarnessActionContext = Pick<
   | 'mutationQueue'
   | 'pausePromptGate'
   | 'persist'
+  | 'pi'
   | 'queuePromptReviewFailure'
   | 'queuePromptReviewResult'
   | 'restoreBaselineTools'
@@ -205,13 +212,22 @@ async function finishPromptReview(
     return;
   }
   try {
+    const stepId = this.run.currentStepId;
+    const gate = workflow.definition.steps[stepId]?.gate;
+    if (!gate) throw new Error(`gated step "${stepId}" no longer exists`);
     this.run = resolveGate(
       workflow,
       this.run,
       resolution,
       this.dependencies.now(),
     );
-    this.settleAfterTransition(workflow);
+    this.settleAfterTransition(workflow, {
+      stepId,
+      outcome: resolution.approved
+        ? gate.approvedOutcome
+        : gate.rejectedOutcome,
+      summary: this.run.lastSummary,
+    });
   } catch (error) {
     this.pausePromptGate(
       active.requestId,
@@ -234,16 +250,38 @@ function pausePromptGate(
   ) {
     return;
   }
+  const wasAwaitingGate = this.run.status === 'awaiting-gate';
+  const didFail = wasAwaitingGate && isFailed;
+  const didPause = wasAwaitingGate && !isFailed;
   if (this.run.status === 'awaiting-gate') {
     this.run = isFailed
       ? failRun(this.run, reason, this.dependencies.now())
       : pauseRun(this.run, reason, this.dependencies.now());
   }
   this.persist();
+  if (didFail) {
+    reportFailedStep(
+      this.pi,
+      this.catalog.workflows.get(this.run.workflowId),
+      this.run,
+      reason,
+    );
+  } else if (didPause) {
+    reportPausedStep(
+      this.pi,
+      this.catalog.workflows.get(this.run.workflowId),
+      this.run,
+      reason,
+    );
+  }
   this.restoreBaselineTools();
   this.updateStatus();
   this.latestContext?.ui.notify(
-    `Workflow paused at "${this.run.currentStepId}": ${reason}`,
+    `Workflow paused at "${this.run.currentStepId}": ${
+      isFailed
+        ? conciseStepFailureSummary(reason)
+        : conciseStepPauseSummary(reason)
+    }`,
     'warning',
   );
 }

package/src/harness/resume-action.ts

@@ -5,13 +5,20 @@ import {
   reconcileRun,
   resolveGate,
   resumeRun,
+  setResumeInput,
   storeGateResolution,
 } from '../engine/transitions.ts';
+import { MAX_RESUME_INPUT_CHARS } from '../engine/state.ts';
 import {
   captureResumeCheckpoint,
   matchesResumeCheckpoint,
 } from '../engine/resume.ts';
+import { analyzeWorkflow } from '../workflow-doctor.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import {
+  conciseStepFailureSummary,
+  reportFailedStep,
+} from './step-reporting.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
@@ -29,6 +36,7 @@ type HarnessActionContext = Pick<
   | 'restoreBaselineTools'
   | 'run'
   | 'sessionEpoch'
+  | 'settleAfterTransition'
   | 'updateStatus'
 >;
 
@@ -36,13 +44,23 @@ export type ResumeAction = {
   resumeNow: (
     this: HarnessActionContext,
     context: ExtensionCommandContext,
+    input?: string,
   ) => Promise<void>;
 };
 
 async function resumeNow(
   this: HarnessActionContext,
   context: ExtensionCommandContext,
+  input = '',
 ): Promise<void> {
+  const resumeInput = input.trim();
+  if (resumeInput.length > MAX_RESUME_INPUT_CHARS) {
+    context.ui.notify(
+      `Resume guidance exceeds ${MAX_RESUME_INPUT_CHARS} characters`,
+      'error',
+    );
+    return;
+  }
   if (!this.run || this.run.status !== 'paused') {
     context.ui.notify('No paused workflow to resume', 'warning');
     return;
@@ -92,6 +110,16 @@ async function resumeNow(
     );
     return;
   }
+  const livenessErrors = analyzeWorkflow(workflow.definition).issues.filter(
+    (issue) => issue.level === 'error',
+  );
+  if (livenessErrors.length > 0) {
+    context.ui.notify(
+      `Cannot resume workflow; run /workflow-doctor ${workflow.definition.id}:\n${livenessErrors.map((issue) => issue.message).join('\n')}`,
+      'error',
+    );
+    return;
+  }
 
   let resumed = reconciled.run;
   if (
@@ -144,6 +172,16 @@ async function resumeNow(
       );
       return;
     }
+    const latestLivenessErrors = analyzeWorkflow(
+      workflow.definition,
+    ).issues.filter((issue) => issue.level === 'error');
+    if (latestLivenessErrors.length > 0) {
+      context.ui.notify(
+        `Cannot resume workflow; run /workflow-doctor ${workflow.definition.id}:\n${latestLivenessErrors.map((issue) => issue.message).join('\n')}`,
+        'error',
+      );
+      return;
+    }
     resumed = latest.run;
 
     if (
@@ -187,14 +225,29 @@ async function resumeNow(
   }
 
   const storedResolution = resumed.pendingGate?.resolution;
+  let settledGate:
+    | {
+        readonly stepId: string;
+        readonly outcome: string;
+      }
+    | undefined;
   if (storedResolution) {
     try {
+      const stepId = resumed.pendingGate?.stepId ?? resumed.currentStepId;
+      const gate = workflow.definition.steps[stepId]?.gate;
+      if (!gate) throw new Error(`gated step "${stepId}" no longer exists`);
       resumed = resolveGate(
         workflow,
         resumed,
         storedResolution,
         this.dependencies.now(),
       );
+      settledGate = {
+        stepId,
+        outcome: storedResolution.approved
+          ? gate.approvedOutcome
+          : gate.rejectedOutcome,
+      };
     } catch (error) {
       context.ui.notify(
         `Cannot apply stored gate result: ${error instanceof Error ? error.message : String(error)}`,
@@ -205,8 +258,21 @@ async function resumeNow(
   } else {
     resumed = resumeRun(resumed, this.dependencies.now());
   }
+  resumed = setResumeInput(
+    resumed,
+    resumed.status === 'running' ? resumeInput : '',
+    this.dependencies.now(),
+  );
   this.run = resumed;
 
+  if (settledGate) {
+    this.settleAfterTransition(workflow, {
+      ...settledGate,
+      summary: this.run.lastSummary,
+    });
+    return;
+  }
+
   if (this.run.status === 'awaiting-gate') {
     this.persist();
     this.restoreBaselineTools();
@@ -238,10 +304,18 @@ async function resumeNow(
       this.dependencies.now(),
     );
     this.persist();
+    reportFailedStep(
+      this.pi,
+      workflow,
+      this.run,
+      this.run.pauseReason ?? 'Step preflight failed',
+    );
     this.restoreBaselineTools();
     this.updateStatus();
     context.ui.notify(
-      `Cannot resume workflow:\n${preflightErrors.join('\n')}`,
+      `Cannot resume workflow: ${conciseStepFailureSummary(
+        preflightErrors.join('; '),
+      )}`,
       'error',
     );
     return;

package/src/harness/start-actions.ts

@@ -1,7 +1,9 @@
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { createRun } from '../engine/state.ts';
+import { analyzeWorkflow, formatWorkflowDoctor } from '../workflow-doctor.ts';
 import { formatWorkflowList } from '../workflow-list.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { formatCatalogDiagnostics } from './catalog.ts';
 import type { WorkflowStartContext } from './types.ts';
 
 type HarnessActionContext = Pick<
@@ -13,7 +15,6 @@ type HarnessActionContext = Pick<
   | 'isSessionActive'
   | 'isolateMainSessionTools'
   | 'launchCurrentStep'
-  | 'openWorkflowStatus'
   | 'persist'
   | 'pi'
   | 'preflight'
@@ -40,6 +41,11 @@ export type StartActions = {
     this: HarnessActionContext,
     context: ExtensionCommandContext,
   ) => Promise<void>;
+  doctorWorkflows: (
+    this: HarnessActionContext,
+    workflowId: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
   startNow: (
     this: HarnessActionContext,
     workflowId: string,
@@ -76,6 +82,48 @@ async function listWorkflows(
   });
 }
 
+async function doctorWorkflows(
+  this: HarnessActionContext,
+  workflowId: string,
+  context: ExtensionCommandContext,
+): Promise<void> {
+  const catalog = await this.dependencies.loadCatalog({
+    cwd: context.cwd,
+    projectTrusted: context.isProjectTrusted(),
+  });
+  if (catalog.diagnostics.some((diagnostic) => diagnostic.level === 'error')) {
+    context.ui.notify(
+      `Workflow configuration errors:\n${formatCatalogDiagnostics(catalog)}`,
+      'warning',
+    );
+  }
+  const selected = workflowId
+    ? [catalog.workflows.get(workflowId)].filter(
+        (workflow) => workflow !== undefined,
+      )
+    : [...catalog.workflows.values()].sort((left, right) =>
+        left.definition.id.localeCompare(right.definition.id),
+      );
+  if (workflowId && selected.length === 0) {
+    context.ui.notify(`Workflow "${workflowId}" is not loaded`, 'error');
+    return;
+  }
+  if (selected.length === 0) {
+    context.ui.notify(
+      `No workflows loaded from ${catalog.userDirectory}`,
+      catalog.diagnostics.length > 0 ? 'warning' : 'info',
+    );
+    return;
+  }
+  this.pi.sendMessage({
+    customType: 'workflow-doctor',
+    content: formatWorkflowDoctor(
+      selected.map((workflow) => analyzeWorkflow(workflow.definition)),
+    ),
+    display: true,
+  });
+}
+
 async function startNow(
   this: HarnessActionContext,
   workflowId: string,
@@ -134,6 +182,16 @@ async function startNow(
     context.ui.notify(`Workflow "${workflowId}" is not loaded`, 'error');
     return;
   }
+  const livenessErrors = analyzeWorkflow(workflow.definition).issues.filter(
+    (issue) => issue.level === 'error',
+  );
+  if (livenessErrors.length > 0) {
+    context.ui.notify(
+      `Cannot start workflow; run /workflow-doctor ${workflowId}:\n${livenessErrors.map((issue) => issue.message).join('\n')}`,
+      'error',
+    );
+    return;
+  }
   const preflightErrors = this.preflight(workflow, workflow.definition.start);
   if (preflightErrors.length > 0) {
     context.ui.notify(
@@ -143,17 +201,33 @@ async function startNow(
     return;
   }
 
+  let canonicalStartCwd: string;
+  try {
+    canonicalStartCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: context.cwd,
+      startCwd: context.cwd,
+      allowedRoots: ['.'],
+    });
+  } catch (error) {
+    context.ui.notify(
+      `Cannot capture workflow working directory: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      'error',
+    );
+    return;
+  }
   this.run = createRun(
     workflow,
     input.trim(),
     this.pi.getActiveTools(),
     this.dependencies.createRequestId(),
     this.dependencies.now(),
+    canonicalStartCwd,
   );
   this.persist();
   this.isolateMainSessionTools();
   this.updateStatus();
-  this.openWorkflowStatus(context);
   this.launchCurrentStep(workflow);
 }
 
@@ -179,5 +253,5 @@ async function reloadNow(
  * Returns workflow listing, start, and reload actions for harness composition.
  */
 export function createStartActions(): StartActions {
-  return { listWorkflows, startNow, reloadNow };
+  return { listWorkflows, doctorWorkflows, startNow, reloadNow };
 }