@wichayutdew/pi-workflows 1.0.0 → 2.0.0

package/src/config/validation/workflow.ts

@@ -67,6 +67,82 @@ function validateGraph(
       }
     });
   });
+  validateWorkspaceGraph(steps, errors);
+}
+
+function validateWorkspaceGraph(
+  steps: Readonly<Record<string, WorkflowStep>>,
+  errors: ValidationErrors,
+): void {
+  const binders = Object.entries(steps).filter(
+    (
+      entry,
+    ): entry is [
+      string,
+      WorkflowStep & { workspace: NonNullable<WorkflowStep['workspace']> },
+    ] => entry[1].workspace !== undefined,
+  );
+  const firstBinderId = binders[0]?.[0];
+
+  binders.forEach(([stepId, step], index) => {
+    const workspacePath = `workflow.steps.${stepId}.workspace`;
+    if (index > 0) {
+      errors.push(
+        `${workspacePath}: only one workspace-binding step is allowed; "${firstBinderId}" also configures workspace binding`,
+      );
+    }
+    if (!step.subagent) {
+      errors.push(`${workspacePath}: workspace binding requires a subagent`);
+    }
+    if (step.gate) {
+      errors.push(
+        `${workspacePath}: workspace binding is not allowed on a gated step`,
+      );
+    }
+
+    const downstream = step.workspace.bindOn.flatMap((outcome) => {
+      const target = step.transitions[outcome];
+      if (target === '$done' || target === '$pause') {
+        errors.push(
+          `workflow.steps.${stepId}.transitions.${outcome}: workspace-binding outcome must target an ordinary step`,
+        );
+        return [];
+      }
+      return target && Object.hasOwn(steps, target) ? [target] : [];
+    });
+    validateWorkspaceDescendants(steps, downstream, errors);
+  });
+}
+
+function validateWorkspaceDescendants(
+  steps: Readonly<Record<string, WorkflowStep>>,
+  initialStepIds: ReadonlyArray<string>,
+  errors: ValidationErrors,
+): void {
+  const pending = [...initialStepIds];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const stepId = pending.pop();
+    if (!stepId || visited.has(stepId)) continue;
+    visited.add(stepId);
+    const step = steps[stepId];
+    if (!step) continue;
+    if (!step.subagent) {
+      errors.push(
+        `workflow.steps.${stepId}.subagent: every nonterminal step reachable after workspace binding must use a subagent`,
+      );
+    }
+    Object.values(step.transitions).forEach((target) => {
+      if (
+        target !== '$done' &&
+        target !== '$pause' &&
+        Object.hasOwn(steps, target) &&
+        !visited.has(target)
+      ) {
+        pending.push(target);
+      }
+    });
+  }
 }
 
 /** Validate and normalize an untrusted workflow definition. */

package/src/engine/create-run.ts

@@ -10,6 +10,7 @@ import type { WorkflowRun } from './state-types.ts';
  * @param baselineTools - Tool names available before workflow restrictions.
  * @param runId - Stable run identifier.
  * @param now - Creation timestamp.
+ * @param cwd - Canonical working directory captured at workflow start.
  * @returns A new running workflow state.
  */
 export const createRun = (
@@ -18,6 +19,7 @@ export const createRun = (
   baselineTools: ReadonlyArray<string>,
   runId: string,
   now: number,
+  cwd?: string,
 ): WorkflowRun => {
   const startStepId = workflow.definition.start;
   return {
@@ -35,6 +37,8 @@ export const createRun = (
     startedAt: now,
     updatedAt: now,
     reviewedArtifact: '',
+    reviewedFeedback: '',
+    ...(cwd ? { startCwd: cwd, cwd } : {}),
     stepHandoff: '',
     lastSummary: '',
     gateFeedback: '',

package/src/engine/gate-transitions.ts

@@ -1,5 +1,6 @@
 import type { LoadedWorkflow } from '../config/types.ts';
 import { advanceRun } from './run-advance.ts';
+import { recordCurrentGateDecision } from './step-trace.ts';
 import type { GateResolution, WorkflowRun } from './state-types.ts';
 import { currentStep, withRunUpdate } from './transition-helpers.ts';
 
@@ -12,6 +13,7 @@ import { currentStep, withRunUpdate } from './transition-helpers.ts';
  * @param artifact - Artifact to display for review.
  * @param requestId - Stable gate request identifier.
  * @param now - Update timestamp.
+ * @param summary - Compact step handoff, separate from the review artifact.
  * @returns A new awaiting-gate workflow state.
  * @throws When the run or gate submission is invalid.
  */
@@ -22,6 +24,7 @@ export const beginGate = (
   artifact: string,
   requestId: string,
   now: number,
+  summary: string,
 ): WorkflowRun => {
   if (run.status !== 'running') {
     throw new Error(
@@ -38,6 +41,9 @@ export const beginGate = (
   if (!artifact.trim()) {
     throw new Error('gate submission requires a non-empty artifact');
   }
+  if (!summary.trim()) {
+    throw new Error('gate submission requires a non-empty summary');
+  }
   if (!requestId) throw new Error('gate submission requires a request id');
 
   return withRunUpdate(
@@ -49,6 +55,7 @@ export const beginGate = (
         requestId,
         stepId: run.currentStepId,
         artifact,
+        summary,
         submittedOutcome: outcome,
         requestedAt: now,
       },
@@ -102,6 +109,9 @@ export const failGate = (
           status: 'running',
           pendingGate: undefined,
           gateFeedback: reason,
+          pausedFrom: undefined,
+          pauseReason: undefined,
+          failedStepId: undefined,
         },
         now,
       )
@@ -158,27 +168,69 @@ export const resolveGate = (
   const outcome = resolution.approved
     ? step.gate.approvedOutcome
     : step.gate.rejectedOutcome;
+  const stepStructuralDigest =
+    workflow.stepStructuralDigests[pendingGate.stepId] ?? '';
+  if (resolution.approved && !stepStructuralDigest) {
+    throw new Error(
+      `gated step "${pendingGate.stepId}" has no structural digest`,
+    );
+  }
   const summary = resolution.approved
-    ? pendingGate.artifact
+    ? (pendingGate.summary ?? '')
     : resolution.feedback
       ? `Gate rejected: ${resolution.feedback}`
       : 'Gate rejected';
-  const runnableRun = withRunUpdate(
+  const decidedRun = recordCurrentGateDecision(
     run,
+    {
+      provider: pendingGate.provider,
+      requestId: pendingGate.requestId,
+      approved: resolution.approved,
+      feedback: resolution.feedback,
+      resolvedAt: resolution.resolvedAt,
+      ...(pendingGate.reviewId ? { reviewId: pendingGate.reviewId } : {}),
+    },
+    now,
+  );
+  const runnableRun = withRunUpdate(
+    decidedRun,
     {
       status: 'running',
       pendingGate: undefined,
-      ...(resolution.approved
-        ? { reviewedArtifact: pendingGate.artifact }
-        : {}),
       pausedFrom: undefined,
       pauseReason: undefined,
       gateFeedback: resolution.feedback,
     },
     now,
   );
+  const advanced = advanceRun(workflow, runnableRun, outcome, summary, now);
+  const completedApprovedGate =
+    resolution.approved && advanced.history.length > runnableRun.history.length;
+  const history = completedApprovedGate
+    ? advanced.history.map((entry, index) =>
+        index === advanced.history.length - 1
+          ? {
+              ...entry,
+              artifact: pendingGate.artifact,
+              approval: {
+                requestId: pendingGate.requestId,
+                artifact: pendingGate.artifact,
+                feedback: resolution.feedback,
+                stepStructuralDigest,
+              },
+            }
+          : entry,
+      )
+    : advanced.history;
   return {
-    ...advanceRun(workflow, runnableRun, outcome, summary, now),
+    ...advanced,
+    history,
+    ...(completedApprovedGate
+      ? {
+          reviewedArtifact: pendingGate.artifact,
+          reviewedFeedback: resolution.feedback,
+        }
+      : {}),
     gateFeedback: resolution.feedback,
   };
 };

package/src/engine/reconciliation-history.ts

@@ -1,6 +1,30 @@
 import type { LoadedWorkflow } from '../config/types.ts';
 import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
 
+type ReviewedApproval = {
+  readonly artifact: string;
+  readonly feedback: string;
+};
+
+const isApprovedGateEntry = (
+  workflow: LoadedWorkflow,
+  entry: StepHistoryEntry,
+): boolean => {
+  const gate = workflow.definition.steps[entry.stepId]?.gate;
+  return gate !== undefined && entry.outcome === gate.approvedOutcome;
+};
+
+const latestApprovedGateEntry = (
+  workflow: LoadedWorkflow,
+  history: ReadonlyArray<StepHistoryEntry>,
+): { readonly entry: StepHistoryEntry; readonly index: number } | undefined => {
+  for (let index = history.length - 1; index >= 0; index -= 1) {
+    const entry = history[index];
+    if (entry && isApprovedGateEntry(workflow, entry)) return { entry, index };
+  }
+  return undefined;
+};
+
 /**
  * Rebuilds step visit counts from retained history and the current step.
  *
@@ -26,37 +50,49 @@ export const rebuildVisits = (
 };
 
 /**
- * Retains reviewed authority only when its approving history remains.
+ * Restores the execution directory represented by retained history.
  *
- * @param workflow - Updated workflow.
- * @param run - Existing workflow state.
+ * @param run - Existing workflow state with immutable start directory.
  * @param history - History retained after reconciliation.
- * @returns The retained artifact, or an empty string when provenance was lost.
+ * @returns The latest retained binding, or the workflow start directory.
  */
-export const retainedReviewedArtifact = (
-  workflow: LoadedWorkflow,
+export const retainedWorkspaceCwd = (
   run: WorkflowRun,
   history: ReadonlyArray<StepHistoryEntry>,
-): string => {
-  const reviewedArtifact = run.reviewedArtifact ?? '';
-  if (!reviewedArtifact) return '';
+): string | undefined => {
+  for (let index = history.length - 1; index >= 0; index -= 1) {
+    const cwd = history[index]?.workspaceCwd;
+    if (cwd) return cwd;
+  }
+  return run.startCwd ?? run.cwd;
+};
 
-  const isApprovalRetained = history.some((entry) => {
-    const gate = workflow.definition.steps[entry.stepId]?.gate;
-    return (
-      gate !== undefined &&
-      entry.outcome === gate.approvedOutcome &&
-      entry.summary === reviewedArtifact
-    );
-  });
-  return isApprovalRetained ? reviewedArtifact : '';
+/**
+ * Restores one reviewed approval from the latest retained approving history.
+ *
+ * Approved history records carry their own artifact, feedback, gate request
+ * identity, and prompt-excluded structural digest.
+ *
+ * @param workflow - Updated workflow.
+ * @param history - History retained after reconciliation.
+ * @returns The retained pair, or `undefined` when provenance was lost.
+ */
+export const retainedReviewedApproval = (
+  workflow: LoadedWorkflow,
+  history: ReadonlyArray<StepHistoryEntry>,
+): ReviewedApproval | undefined => {
+  const retainedApproval = latestApprovedGateEntry(workflow, history);
+  const approval = retainedApproval?.entry.approval;
+  return approval
+    ? { artifact: approval.artifact, feedback: approval.feedback }
+    : undefined;
 };
 
 /**
  * Refreshes the digest of retained approved-gate history.
  *
- * The reviewed artifact itself proves the gate output is unchanged, allowing a
- * prompt-only configuration refresh without discarding approved authority.
+ * The approved history's prompt-excluded structural digest must still match,
+ * allowing only a prompt-only refresh without discarding the reviewed value.
  *
  * @param run - Existing workflow state.
  * @param workflow - Updated workflow.
@@ -66,18 +102,19 @@ export const refreshApprovedGateHistory = (
   run: WorkflowRun,
   workflow: LoadedWorkflow,
 ): WorkflowRun => {
-  const reviewedArtifact = run.reviewedArtifact ?? '';
-  if (!reviewedArtifact) return run;
-
   const history = run.history.map((entry) => {
     const gate = workflow.definition.steps[entry.stepId]?.gate;
     const currentDigest = workflow.stepDigests[entry.stepId];
+    const currentStructuralDigest =
+      workflow.stepStructuralDigests[entry.stepId];
     const shouldRefresh =
       gate !== undefined &&
       typeof currentDigest === 'string' &&
       currentDigest.length > 0 &&
+      typeof currentStructuralDigest === 'string' &&
+      currentStructuralDigest.length > 0 &&
       entry.outcome === gate.approvedOutcome &&
-      entry.summary === reviewedArtifact &&
+      entry.approval?.stepStructuralDigest === currentStructuralDigest &&
       entry.stepDigest !== currentDigest;
     return shouldRefresh ? { ...entry, stepDigest: currentDigest } : entry;
   });

package/src/engine/run-advance.ts

@@ -2,16 +2,29 @@ import type { LoadedWorkflow } from '../config/types.ts';
 import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
 import { currentStep, withRunUpdate } from './transition-helpers.ts';
 
+export type RunStepEffects = {
+  /** Canonical directory selected through the step's YAML-authorized result. */
+  readonly workspaceCwd?: string | undefined;
+};
+
 const completedStep = (
   run: WorkflowRun,
   outcome: string,
   summary: string,
   now: number,
+  effects: RunStepEffects,
 ): StepHistoryEntry => ({
   stepId: run.currentStepId,
   stepDigest: run.currentStepDigest,
   outcome,
   summary,
+  ...(effects.workspaceCwd ? { workspaceCwd: effects.workspaceCwd } : {}),
+  ...(run.currentStepAttempts?.length
+    ? { attempts: run.currentStepAttempts }
+    : {}),
+  ...(run.currentStepOmittedAttempts
+    ? { omittedAttempts: run.currentStepOmittedAttempts }
+    : {}),
   completedAt: now,
 });
 
@@ -23,6 +36,7 @@ const completedStep = (
  * @param outcome - Submitted step outcome.
  * @param summary - Step handoff summary.
  * @param now - Update timestamp.
+ * @param effects - Validated declarative effects accepted with this result.
  * @returns A new paused, running, or completed workflow state.
  * @throws When the run, outcome, current step, or transition target is invalid.
  */
@@ -32,6 +46,7 @@ export const advanceRun = (
   outcome: string,
   summary: string,
   now: number,
+  effects: RunStepEffects = {},
 ): WorkflowRun => {
   if (run.status !== 'running') {
     throw new Error(
@@ -55,6 +70,14 @@ export const advanceRun = (
       `outcome "${outcome}" is not valid for step "${run.currentStepId}"`,
     );
   }
+  const shouldBindWorkspace = step.workspace?.bindOn.includes(outcome) ?? false;
+  if (shouldBindWorkspace !== Boolean(effects.workspaceCwd)) {
+    throw new Error(
+      shouldBindWorkspace
+        ? `outcome "${outcome}" requires a validated workspace binding`
+        : `outcome "${outcome}" cannot bind a workspace`,
+    );
+  }
   if (target === '$pause') {
     return withRunUpdate(
       run,
@@ -63,30 +86,35 @@ export const advanceRun = (
         pausedFrom: 'running',
         pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
         lastSummary: summary,
+        resumeInput: undefined,
       },
       now,
     );
   }
 
-  const completed = completedStep(run, outcome, summary, now);
+  const completed = completedStep(run, outcome, summary, now, effects);
+  const cwd = effects.workspaceCwd ?? run.cwd;
   if (target === '$done') {
     return withRunUpdate(
       run,
       {
         status: 'completed',
         history: [...run.history, completed],
+        currentStepAttempts: undefined,
+        currentStepOmittedAttempts: undefined,
+        ...(cwd ? { cwd } : {}),
         stepHandoff: summary,
         lastSummary: summary,
         gateFeedback: '',
         pausedFrom: undefined,
         pendingGate: undefined,
+        resumeInput: undefined,
       },
       now,
     );
   }
 
-  const nextStep = workflow.definition.steps[target];
-  if (!nextStep) {
+  if (!workflow.definition.steps[target]) {
     throw new Error(`transition target "${target}" does not exist`);
   }
 
@@ -97,11 +125,13 @@ export const advanceRun = (
         status: 'paused',
         pausedFrom: 'running',
         pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`,
+        failedStepId: target,
       }
     : {
         status: 'running',
         pausedFrom: undefined,
         pauseReason: undefined,
+        failedStepId: undefined,
       };
 
   return withRunUpdate(
@@ -112,10 +142,13 @@ export const advanceRun = (
       currentStepDigest: workflow.stepDigests[target] ?? '',
       visits: { ...run.visits, [target]: nextVisitCount },
       history: [...run.history, completed],
+      currentStepAttempts: undefined,
+      currentStepOmittedAttempts: undefined,
+      ...(cwd ? { cwd } : {}),
       stepHandoff: summary,
       lastSummary: summary,
       gateFeedback: '',
-      ...(nextStep.gate ? { reviewedArtifact: '' } : {}),
+      resumeInput: undefined,
     },
     now,
   );

package/src/engine/run-lifecycle.ts

@@ -98,6 +98,16 @@ export const resumeRun = (run: WorkflowRun, now: number): WorkflowRun => {
   );
 };
 
+/**
+ * Replaces the user-authored guidance for one explicit resume attempt.
+ */
+export const setResumeInput = (
+  run: WorkflowRun,
+  input: string,
+  now: number,
+): WorkflowRun =>
+  withRunUpdate(run, { resumeInput: input.trim() || undefined }, now);
+
 /**
  * Aborts a run and clears resumable gate state.
  *
@@ -119,6 +129,7 @@ export const abortRun = (
       pausedFrom: undefined,
       failedStepId: undefined,
       pendingGate: undefined,
+      resumeInput: undefined,
     },
     now,
   );

package/src/engine/run-reconciliation.ts

@@ -2,11 +2,13 @@ import type { LoadedWorkflow } from '../config/types.ts';
 import {
   rebuildVisits,
   refreshApprovedGateHistory,
-  retainedReviewedArtifact,
+  retainedReviewedApproval,
+  retainedWorkspaceCwd,
 } from './reconciliation-history.ts';
 import type { WorkflowRun } from './state-types.ts';
 import { withRunUpdate } from './transition-helpers.ts';
 import type { ReconcileResult } from './transition-types.ts';
+import { validateRunWorkflowSemantics } from './run-workflow-validation.ts';
 
 /**
  * Reconciles persisted run state with a reloaded workflow configuration.
@@ -30,33 +32,61 @@ export const reconcileRun = (
       error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`,
     };
   }
-  if (run.workflowDigest === workflow.digest) {
-    return { run, changed: false };
+  const reconciledRun =
+    run.workflowDigest === workflow.digest
+      ? run
+      : refreshApprovedGateHistory(run, workflow);
+  const changedHistoryIndex =
+    run.workflowDigest === workflow.digest
+      ? -1
+      : reconciledRun.history.findIndex(
+          (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
+        );
+  const changedHistoryEntry =
+    changedHistoryIndex >= 0
+      ? reconciledRun.history[changedHistoryIndex]
+      : undefined;
+  if (
+    changedHistoryEntry &&
+    !workflow.definition.steps[changedHistoryEntry.stepId]
+  ) {
+    return {
+      changed: true,
+      error: 'a completed step was removed; abort or restore the configuration',
+    };
   }
-  if (!workflow.definition.steps[run.currentStepId]) {
+  if (
+    changedHistoryIndex < 0 &&
+    !workflow.definition.steps[run.currentStepId]
+  ) {
     return {
       changed: true,
       error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`,
     };
   }
-
-  const reconciledRun = refreshApprovedGateHistory(run, workflow);
-  const changedHistoryIndex = reconciledRun.history.findIndex(
-    (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
-  );
+  const semanticError = validateRunWorkflowSemantics(reconciledRun, workflow);
+  if (semanticError) {
+    return {
+      changed: run.workflowDigest !== workflow.digest,
+      error: `workflow checkpoint is inconsistent: ${semanticError}`,
+    };
+  }
+  if (run.workflowDigest === workflow.digest) {
+    return { run, changed: false };
+  }
   if (changedHistoryIndex >= 0) {
-    const changedEntry = reconciledRun.history[changedHistoryIndex];
-    if (!changedEntry || !workflow.definition.steps[changedEntry.stepId]) {
-      return {
-        changed: true,
-        error:
-          'a completed step was removed; abort or restore the configuration',
-      };
+    const changedEntry = changedHistoryEntry;
+    if (!changedEntry) {
+      return { changed: true, error: 'changed history entry is unavailable' };
     }
 
     const retainedHistory = reconciledRun.history.slice(0, changedHistoryIndex);
     const restartedStep = changedEntry.stepId;
     const stepHandoff = retainedHistory.at(-1)?.summary ?? '';
+    const reviewedApproval = retainedReviewedApproval(
+      workflow,
+      retainedHistory,
+    );
     return {
       changed: true,
       restartedStep,
@@ -68,12 +98,12 @@ export const reconcileRun = (
           currentStepId: restartedStep,
           currentStepDigest: workflow.stepDigests[restartedStep] ?? '',
           history: retainedHistory,
+          currentStepAttempts: changedEntry.attempts,
+          currentStepOmittedAttempts: changedEntry.omittedAttempts,
           visits: rebuildVisits(retainedHistory, restartedStep),
-          reviewedArtifact: retainedReviewedArtifact(
-            workflow,
-            reconciledRun,
-            retainedHistory,
-          ),
+          cwd: retainedWorkspaceCwd(reconciledRun, retainedHistory),
+          reviewedArtifact: reviewedApproval?.artifact ?? '',
+          reviewedFeedback: reviewedApproval?.feedback ?? '',
           stepHandoff,
           lastSummary: stepHandoff,
           pendingGate: undefined,