@wichayutdew/pi-workflows 2.0.1 → 2.2.0

package/src/harness/start-actions.ts

@@ -1,5 +1,7 @@
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { createRun } from '../engine/state.ts';
+import { restartRun } from '../engine/transitions.ts';
+import type { LoadedWorkflow } from '../config/types.ts';
 import { analyzeWorkflow, formatWorkflowDoctor } from '../workflow-doctor.ts';
 import { formatWorkflowList } from '../workflow-list.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
@@ -36,6 +38,32 @@ function isCurrentSession(
   return session.isSessionActive && session.sessionEpoch === sessionEpoch;
 }
 
+type RestartWorkspaceBinding = {
+  readonly cwd: string;
+  readonly allowedRoots: ReadonlyArray<string>;
+};
+
+function completedWorkspaceBinding(
+  run: NonNullable<HarnessActionContext['run']>,
+  workflow: LoadedWorkflow,
+): RestartWorkspaceBinding | undefined {
+  for (let index = run.history.length - 1; index >= 0; index -= 1) {
+    const entry = run.history[index];
+    if (!entry?.workspaceCwd) continue;
+    const step = workflow.definition.steps[entry.stepId];
+    if (!step?.workspace || !step.workspace.bindOn.includes(entry.outcome)) {
+      throw new Error(
+        `workspace-binding step "${entry.stepId}" no longer matches the completed iteration`,
+      );
+    }
+    return {
+      cwd: entry.workspaceCwd,
+      allowedRoots: step.workspace.allowedRoots,
+    };
+  }
+  return undefined;
+}
+
 export type StartActions = {
   listWorkflows: (
     this: HarnessActionContext,
@@ -53,6 +81,12 @@ export type StartActions = {
     startContext: WorkflowStartContext,
     sessionEpoch: number,
   ) => Promise<void>;
+  restartNow: (
+    this: HarnessActionContext,
+    input: string,
+    startContext: WorkflowStartContext,
+    sessionEpoch: number,
+  ) => Promise<void>;
   reloadNow: (
     this: HarnessActionContext,
     context: ExtensionCommandContext,
@@ -231,6 +265,159 @@ async function startNow(
   this.launchCurrentStep(workflow);
 }
 
+async function restartNow(
+  this: HarnessActionContext,
+  input: string,
+  startContext: WorkflowStartContext,
+  sessionEpoch: number,
+): Promise<void> {
+  const { context } = startContext;
+  const completedRun = this.run;
+  if (!completedRun || completedRun.status !== 'completed') {
+    context.ui.notify('Only a completed workflow can be restarted', 'warning');
+    return;
+  }
+  if (this.activeDelegation) {
+    context.ui.notify(
+      `Cannot restart while subagent "${this.activeDelegation.agent}" is still cancelling`,
+      'warning',
+    );
+    return;
+  }
+  if (!completedRun.startCwd) {
+    context.ui.notify(
+      'Cannot restart this workflow on the same worktree because its original start directory was not captured; start a new workflow instead',
+      'error',
+    );
+    return;
+  }
+  if (!context.isIdle()) {
+    context.abort();
+    await startContext.waitForIdle();
+  }
+  if (!isCurrentSession(this, sessionEpoch) || this.run !== completedRun) {
+    context.ui.notify(
+      'Workflow restart was superseded by a session or workflow change',
+      'warning',
+    );
+    return;
+  }
+
+  this.captureSkills(startContext.skills());
+  if (!(await this.reloadCatalog(context, false))) {
+    context.ui.notify(
+      'Workflow restart was superseded by a newer configuration load',
+      'warning',
+    );
+    return;
+  }
+  if (!isCurrentSession(this, sessionEpoch) || this.run !== completedRun) {
+    context.ui.notify(
+      'Workflow restart was superseded by a session or workflow change',
+      'warning',
+    );
+    return;
+  }
+
+  const workflow = this.catalog.workflows.get(completedRun.workflowId);
+  if (!workflow) {
+    context.ui.notify(
+      `Workflow "${completedRun.workflowId}" is no longer loaded`,
+      'error',
+    );
+    return;
+  }
+  const livenessErrors = analyzeWorkflow(workflow.definition).issues.filter(
+    (issue) => issue.level === 'error',
+  );
+  if (livenessErrors.length > 0) {
+    context.ui.notify(
+      `Cannot restart workflow; run /workflow-doctor ${workflow.definition.id}:\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(
+      `Cannot restart workflow:\n${preflightErrors.join('\n')}`,
+      'error',
+    );
+    return;
+  }
+
+  let canonicalStartCwd: string;
+  let canonicalSessionCwd: string;
+  try {
+    canonicalStartCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: completedRun.startCwd,
+      startCwd: completedRun.startCwd,
+      allowedRoots: ['.'],
+    });
+    canonicalSessionCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: context.cwd,
+      startCwd: context.cwd,
+      allowedRoots: ['.'],
+    });
+  } catch (error) {
+    context.ui.notify(
+      `Cannot restart workflow on its captured worktree: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      'error',
+    );
+    return;
+  }
+  if (
+    canonicalStartCwd !== completedRun.startCwd ||
+    canonicalSessionCwd !== canonicalStartCwd
+  ) {
+    context.ui.notify(
+      'Current session cwd does not match the captured workflow start directory',
+      'error',
+    );
+    return;
+  }
+
+  try {
+    const binding = completedWorkspaceBinding(completedRun, workflow);
+    if (binding) {
+      const canonicalWorkspaceCwd = this.dependencies.resolveWorkspaceDirectory(
+        {
+          candidateCwd: binding.cwd,
+          startCwd: canonicalStartCwd,
+          allowedRoots: binding.allowedRoots,
+        },
+      );
+      if (canonicalWorkspaceCwd !== binding.cwd) {
+        throw new Error(
+          'previous workspace no longer resolves to its captured canonical directory',
+        );
+      }
+    }
+    this.run = restartRun(
+      workflow,
+      completedRun,
+      input.trim() || completedRun.input,
+      this.pi.getActiveTools(),
+      this.dependencies.now(),
+    );
+  } catch (error) {
+    context.ui.notify(
+      `Cannot restart workflow on the same worktree: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      'error',
+    );
+    return;
+  }
+
+  this.persist();
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.launchCurrentStep(workflow);
+}
+
 async function reloadNow(
   this: HarnessActionContext,
   context: ExtensionCommandContext,
@@ -253,5 +440,5 @@ async function reloadNow(
  * Returns workflow listing, start, and reload actions for harness composition.
  */
 export function createStartActions(): StartActions {
-  return { listWorkflows, doctorWorkflows, startNow, reloadNow };
+  return { listWorkflows, doctorWorkflows, startNow, restartNow, reloadNow };
 }

package/src/harness.ts

@@ -123,6 +123,11 @@ export class WorkflowHarness implements WorkflowCommandController {
     startContext: WorkflowStartContext,
     sessionEpoch: number,
   ) => Promise<void> = START_ACTIONS.startNow;
+  private readonly restartNow: (
+    input: string,
+    startContext: WorkflowStartContext,
+    sessionEpoch: number,
+  ) => Promise<void> = START_ACTIONS.restartNow;
   private readonly reloadNow: (
     context: ExtensionCommandContext,
   ) => Promise<void> = START_ACTIONS.reloadNow;
@@ -345,6 +350,21 @@ export class WorkflowHarness implements WorkflowCommandController {
     );
   }
 
+  /** Starts another completed iteration in its existing workflow worktree. */
+  restart(input: string, context: ExtensionCommandContext): Promise<void> {
+    return this.enqueueMutation(context, (sessionEpoch) =>
+      this.restartNow(
+        input,
+        {
+          context,
+          skills: () => context.getSystemPromptOptions().skills,
+          waitForIdle: () => context.waitForIdle(),
+        },
+        sessionEpoch,
+      ),
+    );
+  }
+
   /** Pauses the active workflow while retaining its checkpoint. */
   pause(reason: string, context: ExtensionCommandContext): Promise<void> {
     return this.enqueueMutation(context, () => this.pauseNow(reason, context));

package/src/prompt/step-sections.ts

@@ -58,6 +58,20 @@ export function buildDelegatedHandoffSection(
   ];
 }
 
+/** Builds the immutable same-worktree constraint for a restarted iteration. */
+export function buildRestartWorkspaceSection(
+  workspaceCwd: string | undefined,
+): ReadonlyArray<string> {
+  if (!workspaceCwd) return [];
+  return [
+    '## Restart workspace constraint',
+    '',
+    `This iteration must reuse and rebind exactly this existing workspace: ${workspaceCwd}`,
+    'Do not create or substitute another workspace. If it cannot be safely reused, complete with a configured non-binding outcome that pauses the workflow.',
+    '',
+  ];
+}
+
 /**
  * Builds non-interactive recovery guidance specific to delegated steps.
  *

package/src/prompt/step-task.ts

@@ -4,6 +4,7 @@ import { createStepContract } from './step-contract.ts';
 import {
   buildDelegatedCompletionInstructions,
   buildDelegatedHandoffSection,
+  buildRestartWorkspaceSection,
   buildResourceSection,
 } from './step-sections.ts';
 import {
@@ -119,6 +120,7 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     '',
     `Workflow: ${workflow.definition.id}`,
     `Run: ${run.runId}`,
+    `Iteration: ${run.iteration ?? 1}`,
     `Step: ${run.currentStepId} (${step.title})`,
     ...(isDelegated
       ? [
@@ -132,6 +134,7 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     prompt,
     '',
     ...(isDelegated ? buildDelegatedHandoffSection(handoff) : []),
+    ...buildRestartWorkspaceSection(run.restartWorkspaceCwd),
     ...buildResumeInputSection(
       run,
       RESUME_INPUT_PLACEHOLDER.test(promptTemplate),

package/src/prompt/template.ts

@@ -7,8 +7,8 @@ import type { WorkflowRun } from '../engine/state.ts';
 export type TemplateValues = Readonly<Record<string, string>>;
 
 /**
- * Combines the incoming handoff with the latest paused-attempt
- * summary without duplicating identical content.
+ * Combines the incoming handoff with the latest current-step summary without
+ * duplicating identical content.
  *
  * @param run - Current workflow run.
  * @returns The handoff text for the active step.
@@ -27,7 +27,7 @@ export function currentStepHandoff(run: WorkflowRun): string {
     'Incoming previous-step handoff:',
     incomingHandoff,
     '',
-    'Latest paused attempt:',
+    'Latest current-step summary:',
     run.lastSummary,
   ].join('\n');
 }
@@ -72,13 +72,16 @@ export function createTemplateValues({
   return {
     'workflow.input': run.input,
     'workflow.id': workflow.definition.id,
+    'workflow.iteration': String(run.iteration ?? 1),
     'run.id': run.runId,
     'step.id': run.currentStepId,
     'step.title': step.title,
     'last.summary': currentStepHandoff(run),
     'reviewed.artifact': run.reviewedArtifact ?? '',
     'reviewed.feedback': run.reviewedFeedback ?? '',
+    'gate.artifact': run.gateArtifact ?? '',
     'gate.feedback': run.gateFeedback,
     'resume.input': run.resumeInput ?? '',
+    'restart.workspace': run.restartWorkspaceCwd ?? '',
   };
 }

package/src/workflow-doctor.ts

@@ -235,7 +235,7 @@ export function formatWorkflowDoctor(
       '',
       `Result: ${errors.length > 0 ? 'ERROR' : warnings.length > 0 ? 'WARNING' : 'PASS'}`,
       '',
-      `Runtime loop guard: each step executes at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? '' : 's'} before the next attempted entry pauses an uninterrupted run. This bounds graph cycling; it does not guarantee $done or bound time spent inside a step or gate.`,
+      `Runtime loop guard: automatic graph advancement enters each step at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? '' : 's'} before the next attempted entry pauses the run. An explicit human rejection back to the same gated step bypasses that check for its transition because every revision awaits another decision; the visit is still recorded. This bounds unattended cycling; it does not guarantee $done or bound time spent inside a step or gate.`,
       '',
     );
     if (report.issues.length === 0) {

package/src/workflow-status/render-summary.ts

@@ -82,6 +82,9 @@ export function renderSummaryLines(
         ]
       : []),
     ...keyValueLines(theme, 'run', run.runId, width),
+    ...(run.iteration && run.iteration > 1
+      ? [...keyValueLines(theme, 'iteration', String(run.iteration), width)]
+      : []),
     ...keyValueLines(
       theme,
       'status',

package/src/workflow-status/view.ts

@@ -135,6 +135,7 @@ function nextScrollOffset(state: ViewportState, value: number): number {
 export class WorkflowStatusView implements Component {
   private timer: RefreshTimer | undefined;
   private state = initialViewportState();
+  private pendingDetailTopKey = false;
   private readonly statusShortcutLabel: string;
   private readonly dependencies: WorkflowStatusViewDependencies;
   private readonly transcriptCache = new Map<string, StepTranscriptViewState>();
@@ -180,11 +181,15 @@ export class WorkflowStatusView implements Component {
 
   /** Handle close and scrolling key input. */
   handleInput(data: string): void {
+    const isDetailHalfPageDown =
+      this.state.mode === 'detail' && matchesKey(data, Key.ctrl('d'));
+    const isDetailHalfPageUp =
+      this.state.mode === 'detail' && matchesKey(data, Key.ctrl('u'));
     if (
       data === 'q' ||
       data === 'Q' ||
       matchesKey(data, 'ctrl+c') ||
-      matchesKey(data, 'ctrl+d') ||
+      (this.state.mode !== 'detail' && matchesKey(data, 'ctrl+d')) ||
       matchesKey(data, this.statusShortcut)
     ) {
       this.close();
@@ -199,13 +204,31 @@ export class WorkflowStatusView implements Component {
       return;
     }
     const pageSize = Math.max(1, this.state.viewportRows - 2);
+    const contentHeight = Math.max(1, this.state.viewportRows - 1);
+    const halfPageSize = Math.max(1, Math.floor(contentHeight / 2));
     if (this.state.mode === 'detail') {
-      if (matchesKey(data, Key.left) || data === 'h') {
+      if (data === 'gg' || (data === 'g' && this.pendingDetailTopKey)) {
+        this.pendingDetailTopKey = false;
+        this.setScrollOffset(0);
+        return;
+      }
+      if (data === 'g') {
+        this.pendingDetailTopKey = true;
+        return;
+      }
+      this.pendingDetailTopKey = false;
+      if (data === 'G') {
+        this.setScrollOffset(Number.MAX_SAFE_INTEGER);
+      } else if (matchesKey(data, Key.left) || data === 'h') {
         this.showBoard();
       } else if (matchesKey(data, Key.down) || data === 'j') {
         this.setScrollOffset(this.state.scrollOffset + 1);
       } else if (matchesKey(data, Key.up) || data === 'k') {
         this.setScrollOffset(this.state.scrollOffset - 1);
+      } else if (isDetailHalfPageDown) {
+        this.setScrollOffset(this.state.scrollOffset + halfPageSize);
+      } else if (isDetailHalfPageUp) {
+        this.setScrollOffset(this.state.scrollOffset - halfPageSize);
       } else if (matchesKey(data, Key.pageDown)) {
         this.setScrollOffset(this.state.scrollOffset + pageSize);
       } else if (matchesKey(data, Key.pageUp)) {
@@ -217,6 +240,7 @@ export class WorkflowStatusView implements Component {
       }
       return;
     }
+    this.pendingDetailTopKey = false;
     if (matchesKey(data, Key.down) || data === 'j') {
       this.moveSelection(1);
     } else if (matchesKey(data, Key.up) || data === 'k') {
@@ -287,7 +311,7 @@ export class WorkflowStatusView implements Component {
       this.statusShortcutLabel,
       this.theme,
       this.state.mode === 'detail'
-        ? '↑/↓ or j/k scroll · PgUp/PgDn · ←/h/Esc back'
+        ? '↑↓/jk · Ctrl+D/U half-page · gg/G top/bottom · PgUp/PgDn · ←/h/Esc'
         : '↑/↓ or j/k select · Enter/→/l inspect · PgUp/PgDn',
     );
     this.state = page.state;
@@ -339,6 +363,7 @@ export class WorkflowStatusView implements Component {
     if (!snapshot) return;
     this.normalizeSelection(snapshot);
     if (!selectedStepDetail(snapshot, this.state.selectedIndex)) return;
+    this.pendingDetailTopKey = false;
     this.state = { ...this.state, mode: 'detail', scrollOffset: 0 };
     this.ensureSelectedTranscripts(snapshot);
     this.tui.requestRender(true);
@@ -346,6 +371,7 @@ export class WorkflowStatusView implements Component {
 
   private showBoard(): void {
     if (this.state.mode === 'board') return;
+    this.pendingDetailTopKey = false;
     this.state = { ...this.state, mode: 'board', scrollOffset: 0 };
     this.tui.requestRender(true);
   }