@wichayutdew/pi-workflows 2.1.0 → 2.2.0

package/examples/starter-kit/mr-review.workflow.yaml

@@ -105,7 +105,7 @@ steps:
       blocked: $pause
 
   verify:
-    title: Verify the review is observable remotely
+    title: Verify or return the review for publication repair
     prompt:
       file: steps/mr-review/verify.md
     subagent:
@@ -127,4 +127,6 @@ steps:
       tools: [bash]
     transitions:
       verified: $done
+      failed: publish
+      retry: verify
       blocked: $pause

package/examples/starter-kit/steps/mr-review/publish.md

@@ -10,6 +10,9 @@ Approved review:
 Approval feedback:
 {{reviewed.feedback}}
 
+Previous step handoff:
+{{last.summary}}
+
 Parse the approved Publication contract. Refresh the same review and head SHA
 through configured read-only MCP/CLI/cURL calls. For every action, first query
 the public review collections and skip it only when its exact marker, body,
@@ -26,5 +29,9 @@ After a mutation-capable call is attempted, ambiguity is `blocked`; do not
 blindly replay it. Call `structured_output` alone with outcome `published` only
 after every approved effect succeeded now or was proven already present.
 Summarize the URL/head, per-action pre-state, attempted/skipped result, exact
-correlation, and remaining work. Use `blocked` with the same ledger when
-freshness, execution, or correlation fails.
+correlation, and remaining work. When the previous handoff is an actionable
+verification finding, treat it as a corrective publication handoff: re-check
+the exact approved effect and retry only when its absence is conclusive. Never
+use it to alter the approved content, target, or action list. Use `blocked`
+with the same ledger when freshness, execution, or correlation is ambiguous or
+unsafe.

package/examples/starter-kit/steps/mr-review/verify.md

@@ -17,8 +17,19 @@ review collections and prove every exact marker, body, head, effect kind,
 optional path/line anchor, and remote identifier. The publication ledger alone
 is not proof.
 
-Call `structured_output` alone with outcome `verified` only when all approved
-effects are observable exactly once or in the explicitly idempotent form
-described by the contract. Summarize the canonical URL, current head, verified
-remote identifiers/URLs and anchors, action count, and final verdict. Use
-`blocked` when an effect is absent, stale, ambiguous, or different.
+Call `structured_output` alone with:
+
+- `verified` only when all approved effects are observable exactly once or in
+  the explicitly idempotent form described by the contract;
+- `failed` for an actionable, unambiguous missing or mismatched approved
+  effect. Its self-contained summary becomes the next publication worker's
+  corrective handoff, so include the expected and observed state, exact
+  evidence, and the smallest safe repair;
+- `retry` for a transient read-only verification failure after safe equivalent
+  checks were attempted;
+- `blocked` only when the review, head, target, or remote result is stale,
+  ambiguous, or unsafe to repair automatically.
+
+For `verified` and `failed`, summarize the canonical URL, current head,
+verified or missing remote identifiers/URLs and anchors, action count, and
+final verdict. Do not mutate state yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

package/schemas/workflow.schema.json

@@ -52,6 +52,7 @@
               "workflow-list",
               "workflow-pause",
               "workflow-reload",
+              "workflow-restart",
               "workflow-resume",
               "workflow-start",
               "workflow-status"

package/src/command-names.ts

@@ -7,6 +7,7 @@ export const HARNESS_COMMAND_NAMES = [
   'workflow-list',
   'workflow-pause',
   'workflow-reload',
+  'workflow-restart',
   'workflow-resume',
   'workflow-start',
 ] as const;

package/src/commands.ts

@@ -23,6 +23,11 @@ export type WorkflowCommandController = {
     input: string,
     context: ExtensionCommandContext,
   ) => Promise<void>;
+  /** Restarts a completed workflow in its existing worktree. */
+  readonly restart: (
+    input: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
   /** Pauses the active workflow. */
   readonly pause: (
     reason: string,
@@ -126,6 +131,15 @@ export function createHarnessCommands(
       },
     },
     createStartCommand(controller),
+    {
+      name: 'workflow-restart',
+      options: {
+        description:
+          'Restart the completed workflow in its worktree: /workflow-restart [input]',
+        handler: async (input, context) =>
+          controller.restart(input.trim(), context),
+      },
+    },
     {
       name: 'workflow-pause',
       options: {

package/src/config/validation/prompt.ts

@@ -1,6 +1,7 @@
 const PROMPT_VARIABLES = new Set([
   'workflow.input',
   'workflow.id',
+  'workflow.iteration',
   'run.id',
   'step.id',
   'step.title',
@@ -10,6 +11,7 @@ const PROMPT_VARIABLES = new Set([
   'gate.artifact',
   'gate.feedback',
   'resume.input',
+  'restart.workspace',
 ]);
 
 /** Validate template variables embedded in resolved prompt text. */

package/src/engine/create-run.ts

@@ -11,6 +11,7 @@ import type { WorkflowRun } from './state-types.ts';
  * @param runId - Stable run identifier.
  * @param now - Creation timestamp.
  * @param cwd - Canonical working directory captured at workflow start.
+ * @param iteration - One-based restart iteration within this worktree lineage.
  * @returns A new running workflow state.
  */
 export const createRun = (
@@ -20,10 +21,12 @@ export const createRun = (
   runId: string,
   now: number,
   cwd?: string,
+  iteration = 1,
 ): WorkflowRun => {
   const startStepId = workflow.definition.start;
   return {
     stateVersion: RUN_STATE_VERSION,
+    iteration,
     runId,
     workflowId: workflow.definition.id,
     workflowDigest: workflow.digest,

package/src/engine/run-advance.ts

@@ -88,6 +88,15 @@ export const advanceRun = (
         : `outcome "${outcome}" cannot bind a workspace`,
     );
   }
+  if (
+    shouldBindWorkspace &&
+    run.restartWorkspaceCwd !== undefined &&
+    effects.workspaceCwd !== run.restartWorkspaceCwd
+  ) {
+    throw new Error(
+      `restarted workflow must rebind workspace "${run.restartWorkspaceCwd}"`,
+    );
+  }
   if (target === '$pause') {
     return withRunUpdate(
       run,
@@ -105,6 +114,11 @@ export const advanceRun = (
   const completed = completedStep(run, outcome, summary, now, effects);
   const cwd = effects.workspaceCwd ?? run.cwd;
   if (target === '$done') {
+    if (run.restartWorkspaceCwd !== undefined) {
+      throw new Error(
+        `restarted workflow completed before rebinding workspace "${run.restartWorkspaceCwd}"`,
+      );
+    }
     return withRunUpdate(
       run,
       {
@@ -113,6 +127,7 @@ export const advanceRun = (
         currentStepAttempts: undefined,
         currentStepOmittedAttempts: undefined,
         ...(cwd ? { cwd } : {}),
+        ...(effects.workspaceCwd ? { restartWorkspaceCwd: undefined } : {}),
         stepHandoff: summary,
         lastSummary: summary,
         gateArtifact: '',
@@ -161,6 +176,7 @@ export const advanceRun = (
       currentStepAttempts: undefined,
       currentStepOmittedAttempts: undefined,
       ...(cwd ? { cwd } : {}),
+      ...(effects.workspaceCwd ? { restartWorkspaceCwd: undefined } : {}),
       stepHandoff: preservesGateRevisionContext ? run.stepHandoff : summary,
       lastSummary: summary,
       gateArtifact: preservesGateRevisionContext ? run.gateArtifact : '',

package/src/engine/run-lifecycle.ts

@@ -1,7 +1,16 @@
 import type { LoadedWorkflow } from '../config/types.ts';
+import { createRun } from './create-run.ts';
 import type { WorkflowRun } from './state-types.ts';
 import { currentStep, withRunUpdate } from './transition-helpers.ts';
 
+const completedWorkspaceCwd = (run: WorkflowRun): string | undefined => {
+  for (let index = run.history.length - 1; index >= 0; index -= 1) {
+    const workspaceCwd = run.history[index]?.workspaceCwd;
+    if (workspaceCwd) return workspaceCwd;
+  }
+  return undefined;
+};
+
 /**
  * Lists outcomes the active step may submit directly.
  *
@@ -133,3 +142,63 @@ export const abortRun = (
     },
     now,
   );
+
+/**
+ * Starts another iteration of a completed workflow while retaining its stable
+ * run/worktree identity. The next workspace-binding result must reaffirm the
+ * previously selected workspace before the iteration can complete.
+ *
+ * @param workflow - Current loaded workflow definition.
+ * @param run - Completed iteration to restart.
+ * @param input - New request, or the prior request when no replacement was supplied.
+ * @param baselineTools - Tools available before the new iteration is isolated.
+ * @param now - Restart timestamp.
+ * @returns A fresh running state for the next iteration.
+ */
+export const restartRun = (
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  input: string,
+  baselineTools: ReadonlyArray<string>,
+  now: number,
+): WorkflowRun => {
+  if (run.status !== 'completed') {
+    throw new Error('only a completed workflow can be restarted');
+  }
+  if (!run.startCwd) {
+    throw new Error(
+      'the completed workflow has no captured start directory; start a new workflow instead',
+    );
+  }
+
+  const previousIteration = run.iteration ?? 1;
+  if (!Number.isSafeInteger(previousIteration) || previousIteration < 1) {
+    throw new Error('the completed workflow has an invalid iteration number');
+  }
+  if (previousIteration >= Number.MAX_SAFE_INTEGER) {
+    throw new Error('the workflow iteration limit has been reached');
+  }
+
+  const workspaceCwd = completedWorkspaceCwd(run);
+  if (workspaceCwd && run.cwd !== workspaceCwd) {
+    throw new Error(
+      'the completed workflow workspace does not match its recorded binding',
+    );
+  }
+
+  const restarted = createRun(
+    workflow,
+    input,
+    baselineTools,
+    run.runId,
+    now,
+    run.startCwd,
+    previousIteration + 1,
+  );
+  return {
+    ...restarted,
+    stepHandoff: run.lastSummary,
+    lastSummary: run.lastSummary,
+    ...(workspaceCwd ? { restartWorkspaceCwd: workspaceCwd } : {}),
+  };
+};

package/src/engine/run-validation.ts

@@ -253,6 +253,10 @@ const isOptionalResumeInput = (value: unknown): value is string | undefined =>
   value === undefined ||
   (typeof value === 'string' && value.length <= MAX_RESUME_INPUT_CHARS);
 
+const isOptionalIteration = (value: unknown): value is number | undefined =>
+  value === undefined ||
+  (Number.isSafeInteger(value) && (value as number) >= 1);
+
 const isWorkflowRunStatus = (value: unknown): value is WorkflowRunStatus =>
   value === 'running' ||
   value === 'paused' ||
@@ -341,12 +345,15 @@ export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
   if (!hasValidRequiredFields) return false;
 
   const hasValidOptionalFields =
+    isOptionalIteration(value.iteration) &&
     isOptionalString(value.reviewedArtifact) &&
     isOptionalString(value.reviewedFeedback) &&
     (typeof value.reviewedFeedback !== 'string' ||
       value.reviewedFeedback.length <= MAX_GATE_FEEDBACK_CHARS) &&
     isOptionalString(value.stepHandoff) &&
     isOptionalString(value.gateArtifact) &&
+    (value.restartWorkspaceCwd === undefined ||
+      isAbsoluteCwd(value.restartWorkspaceCwd)) &&
     isOptionalResumeInput(value.resumeInput) &&
     isOptionalString(value.pauseReason) &&
     isOptionalString(value.failedStepId) &&
@@ -358,6 +365,15 @@ export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
   const pendingGate = value.pendingGate;
   if (pendingGate !== undefined && !isPendingGate(pendingGate)) return false;
 
+  if (
+    value.restartWorkspaceCwd !== undefined &&
+    (value.history as ReadonlyArray<StepHistoryEntry>).some(
+      (entry) => entry.workspaceCwd !== undefined,
+    )
+  ) {
+    return false;
+  }
+
   return (
     workflowTraceChars(value as WorkflowRun) <= MAX_WORKFLOW_TRACE_CHARS &&
     hasValidWorkspaceState(

package/src/engine/state-types.ts

@@ -125,6 +125,8 @@ export type PendingGate = {
 
 export type WorkflowRun = {
   readonly stateVersion: typeof RUN_STATE_VERSION;
+  /** One-based attempt number within a restartable workflow/worktree lineage. */
+  readonly iteration?: number | undefined;
   readonly runId: string;
   readonly workflowId: string;
   readonly workflowDigest: string;
@@ -153,6 +155,11 @@ export type WorkflowRun = {
   readonly startCwd?: string | undefined;
   /** Current canonical execution directory for delegated workflow steps. */
   readonly cwd?: string | undefined;
+  /**
+   * Exact workspace that a restarted iteration must bind before it can finish.
+   * This prevents a missing prior worktree from being silently replaced.
+   */
+  readonly restartWorkspaceCwd?: string | undefined;
   /**
    * Input inherited from the previous completed step. Unlike `lastSummary`,
    * this survives a paused attempt of the current step.

package/src/engine/transitions.ts

@@ -11,6 +11,7 @@ export {
   allowedOutcomes,
   failRun,
   pauseRun,
+  restartRun,
   resumeRun,
   setResumeInput,
 } from './run-lifecycle.ts';

package/src/harness/action-context.ts

@@ -77,6 +77,12 @@ export type HarnessActionContext = {
     startContext: WorkflowStartContext,
     sessionEpoch: number,
   ) => Promise<void>;
+  restart: (input: string, context: ExtensionCommandContext) => Promise<void>;
+  restartNow: (
+    input: string,
+    startContext: WorkflowStartContext,
+    sessionEpoch: number,
+  ) => Promise<void>;
   pause: (reason: string, context: ExtensionCommandContext) => Promise<void>;
   pauseNow: (reason: string, context: ExtensionCommandContext) => Promise<void>;
   resume: (input: string, context: ExtensionCommandContext) => Promise<void>;

package/src/harness/core-actions.ts

@@ -190,6 +190,8 @@ function enqueueMutation(
 function persist(this: HarnessActionContext): void {
   if (this.run) {
     this.pi.appendEntry(STATE_ENTRY_TYPE, structuredClone(this.run));
+    const session = this.latestContext?.sessionManager;
+    if (session) this.dependencies.flushUnwrittenSession(session);
   }
 }
 

package/src/harness/dependencies.ts

@@ -33,6 +33,7 @@ import {
   resolveWorkspaceDirectory,
   type ResolveWorkspaceDirectoryOptions,
 } from './workspace-directory.ts';
+import { flushUnwrittenSession } from './session-persistence.ts';
 
 const MAX_DELEGATED_RESULT_BYTES = 1024 * 1024;
 
@@ -71,6 +72,8 @@ export type WorkflowHarnessDependencies = {
     pi: ExtensionAPI,
   ) => MainStepRuntimeController;
   readonly createMutationQueue: () => SerialTaskQueueController;
+  /** Makes a new Pi session durable before its first assistant message. */
+  readonly flushUnwrittenSession: typeof flushUnwrittenSession;
   readonly scheduleInterval: (
     operation: () => void,
     intervalMs: number,
@@ -154,6 +157,7 @@ const DEFAULT_DEPENDENCIES: WorkflowHarnessDependencies = {
   createSubagentClient: (pi) => createSubagentDelegationClient(pi.events),
   createMainStepRuntime: (pi) => createMainStepRuntime({ pi }),
   createMutationQueue: createSerialTaskQueue,
+  flushUnwrittenSession,
   scheduleInterval: (operation, intervalMs) =>
     setInterval(operation, intervalMs),
   cancelInterval: (timer) => {

package/src/harness/lifecycle-actions.ts

@@ -107,9 +107,22 @@ function registerLifecycle(this: HarnessActionContext): void {
     this.isSessionActive = true;
   });
 
-  this.pi.on('session_shutdown', async () => {
+  this.pi.on('session_shutdown', async (_event, context) => {
     this.sessionEpoch += 1;
     this.isSessionActive = false;
+    if (this.run) {
+      this.latestContext = context;
+      try {
+        this.persist();
+      } catch (error) {
+        context.ui.notify(
+          `Workflow checkpoint could not be saved before shutdown: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          'error',
+        );
+      }
+    }
     this.cancelPromptReview();
     this.mainSteps.deactivate();
     await this.cancelActiveDelegation('Pi session shut down');

package/src/harness/session-persistence.ts

@@ -0,0 +1,66 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import type {
+  ExtensionContext,
+  SessionManager,
+} from '@earendil-works/pi-coding-agent';
+
+type SessionSnapshot = Pick<
+  ExtensionContext['sessionManager'],
+  'getEntries' | 'getHeader' | 'getSessionFile'
+>;
+
+type AdoptableSessionSnapshot = SessionSnapshot &
+  Pick<SessionManager, 'setSessionFile'>;
+
+const isAlreadyPersisted = (error: unknown): boolean =>
+  error instanceof Error && 'code' in error && error.code === 'EEXIST';
+
+function getAdoptableSession(
+  session: SessionSnapshot,
+): AdoptableSessionSnapshot {
+  const adoptable = session as Partial<AdoptableSessionSnapshot>;
+  if (typeof adoptable.setSessionFile !== 'function') {
+    throw new Error(
+      'This Pi runtime cannot adopt a materialized workflow session file',
+    );
+  }
+  return adoptable as AdoptableSessionSnapshot;
+}
+
+/**
+ * Materializes a Pi session before its first regular assistant message.
+ *
+ * Pi defers creating a new session file until it records a regular assistant
+ * message. A workflow made entirely of delegated steps can therefore have
+ * checkpoint entries in memory but no file to reopen. After creating a public
+ * session snapshot, this re-adopts the same file through Pi's public
+ * `SessionManager#setSessionFile` method. That marks the running manager as
+ * flushed, allowing Pi to append future custom and assistant entries normally.
+ *
+ * @param session - Public snapshot view supplied by Pi's extension context.
+ * @returns `true` when this call created the session file.
+ */
+export function flushUnwrittenSession(session: SessionSnapshot): boolean {
+  const sessionFile = session.getSessionFile();
+  const header = session.getHeader();
+  if (!sessionFile || !header) return false;
+  if (existsSync(sessionFile)) return false;
+  const adoptable = getAdoptableSession(session);
+
+  const serialized = [header, ...session.getEntries()]
+    .map((entry) => JSON.stringify(entry))
+    .join('\n');
+
+  try {
+    writeFileSync(sessionFile, `${serialized}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600,
+    });
+    adoptable.setSessionFile(sessionFile);
+    return true;
+  } catch (error) {
+    if (isAlreadyPersisted(error)) return false;
+    throw error;
+  }
+}