@wichayutdew/pi-workflows 1.0.0 → 2.0.0

package/schemas/workflow.schema.json

@@ -48,6 +48,7 @@
               "tree",
               "trust",
               "workflow-abort",
+              "workflow-doctor",
               "workflow-list",
               "workflow-pause",
               "workflow-reload",
@@ -94,6 +95,34 @@
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]{0,63}$"
     },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "pattern": "^\\S(?:.*\\S)?$",
+      "allOf": [
+        {
+          "not": {
+            "pattern": "^/"
+          }
+        },
+        {
+          "not": {
+            "pattern": "^[A-Za-z]:"
+          }
+        },
+        {
+          "not": {
+            "pattern": "^\\\\"
+          }
+        },
+        {
+          "not": {
+            "pattern": "\\u0000"
+          }
+        }
+      ]
+    },
     "resourceName": {
       "type": "string",
       "pattern": "^[A-Za-z0-9_@./:+-]+$"
@@ -114,8 +143,7 @@
           "required": ["file"],
           "properties": {
             "file": {
-              "type": "string",
-              "minLength": 1
+              "$ref": "#/$defs/relativePath"
             }
           }
         }
@@ -175,32 +203,17 @@
             "required": ["mode"]
           },
           "then": {
-            "anyOf": [
-              {
-                "required": ["allow"],
-                "properties": {
-                  "allow": {
-                    "minItems": 1
-                  }
-                }
-              },
-              {
-                "required": ["approvedSources"],
-                "properties": {
-                  "approvedSources": {
-                    "minItems": 1
-                  }
-                }
+            "required": ["allow"],
+            "properties": {
+              "allow": {
+                "minItems": 1
               }
-            ]
+            }
           },
           "else": {
             "properties": {
               "allow": {
                 "maxItems": 0
-              },
-              "approvedSources": {
-                "maxItems": 0
               }
             }
           }
@@ -208,24 +221,13 @@
       ],
       "properties": {
         "mode": {
-          "enum": ["deny", "read-only", "allow-list", "unrestricted"]
+          "enum": ["deny", "allow-list", "unrestricted"]
         },
         "allow": {
           "type": "array",
           "items": {
             "$ref": "#/$defs/bashRule"
           }
-        },
-        "approvedSources": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": {
-            "enum": [
-              "verification-worker",
-              "verification-reviewer",
-              "remote-actions"
-            ]
-          }
         }
       }
     },
@@ -546,16 +548,54 @@
               "type": "integer",
               "minimum": 1000,
               "maximum": 30000,
-              "default": 5000
+              "default": 30000
             }
           }
         }
       ]
     },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bindOn"],
+      "properties": {
+        "bindOn": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/identifier"
+          }
+        },
+        "allowedRoots": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "default": ["."],
+          "items": {
+            "$ref": "#/$defs/relativePath"
+          }
+        }
+      }
+    },
     "step": {
       "type": "object",
       "additionalProperties": false,
       "required": ["prompt", "transitions"],
+      "allOf": [
+        {
+          "if": {
+            "required": ["workspace"]
+          },
+          "then": {
+            "required": ["subagent"],
+            "not": {
+              "required": ["gate"]
+            }
+          }
+        }
+      ],
       "properties": {
         "title": {
           "type": "string",
@@ -586,6 +626,9 @@
         },
         "gate": {
           "$ref": "#/$defs/gate"
+        },
+        "workspace": {
+          "$ref": "#/$defs/workspace"
         }
       }
     }

package/src/command-names.ts

@@ -3,6 +3,7 @@
  */
 export const HARNESS_COMMAND_NAMES = [
   'workflow-abort',
+  'workflow-doctor',
   'workflow-list',
   'workflow-pause',
   'workflow-reload',

package/src/commands.ts

@@ -12,6 +12,11 @@ export type WorkflowCommandController = {
   readonly workflowIds: () => ReadonlyArray<string>;
   /** Lists loaded workflows. */
   readonly list: (context: ExtensionCommandContext) => Promise<void>;
+  /** Diagnoses workflow graph liveness. */
+  readonly doctor: (
+    workflowId: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
   /** Starts a workflow. */
   readonly start: (
     workflowId: string,
@@ -23,8 +28,11 @@ export type WorkflowCommandController = {
     reason: string,
     context: ExtensionCommandContext,
   ) => Promise<void>;
-  /** Resumes the paused workflow. */
-  readonly resume: (context: ExtensionCommandContext) => Promise<void>;
+  /** Resumes the paused workflow with optional user guidance. */
+  readonly resume: (
+    input: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
   /** Aborts the active workflow. */
   readonly abort: (
     reason: string,
@@ -98,6 +106,25 @@ export function createHarnessCommands(
         handler: async (_args, context) => controller.list(context),
       },
     },
+    {
+      name: 'workflow-doctor',
+      options: {
+        description:
+          'Check workflow completion paths, unreachable steps, and cycles',
+        getArgumentCompletions: (prefix) => {
+          const completions = controller
+            .workflowIds()
+            .filter((workflowId) => workflowId.startsWith(prefix))
+            .map((workflowId) => ({
+              value: workflowId,
+              label: workflowId,
+            }));
+          return completions.length > 0 ? completions : null;
+        },
+        handler: async (args, context) =>
+          controller.doctor(args.trim(), context),
+      },
+    },
     createStartCommand(controller),
     {
       name: 'workflow-pause',
@@ -110,8 +137,10 @@ export function createHarnessCommands(
     {
       name: 'workflow-resume',
       options: {
-        description: 'Reload configuration and resume the paused workflow',
-        handler: async (_args, context) => controller.resume(context),
+        description:
+          'Reload configuration and resume: /workflow-resume [guidance]',
+        handler: async (input, context) =>
+          controller.resume(input.trim(), context),
       },
     },
     {

package/src/config/ceiling.ts

@@ -28,17 +28,10 @@ function bashWithinCeiling(
   if (ceiling.mode === 'unrestricted') return true;
   if (requested.mode === 'deny') return true;
   if (ceiling.mode === 'deny') return false;
-  if (ceiling.mode === 'read-only') return requested.mode === 'read-only';
   if (requested.mode !== 'allow-list') return false;
 
   const allowedRules = new Set(ceiling.allow.map(ruleKey));
-  const allowedSources = new Set(ceiling.approvedSources ?? []);
-  return (
-    requested.allow.every((rule) => allowedRules.has(ruleKey(rule))) &&
-    (requested.approvedSources ?? []).every((source) =>
-      allowedSources.has(source),
-    )
-  );
+  return requested.allow.every((rule) => allowedRules.has(ruleKey(rule)));
 }
 
 function turnBudgetErrors(
@@ -124,6 +117,11 @@ export function checkWorkflowAgainstCeiling(
   return Object.entries(workflow.steps).flatMap(([stepId, step]) => {
     const path = `workflow.steps.${stepId}.permissions`;
     return [
+      ...(Object.hasOwn(step, 'workspace')
+        ? [
+            `workflow.steps.${stepId}.workspace: workspace binding is unavailable to project workflows`,
+          ]
+        : []),
       ...step.permissions.tools
         .filter((tool) => !ceiling.tools.includes(tool))
         .map(

package/src/config/load-workflows.ts

@@ -2,6 +2,10 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { digest } from '../digest.ts';
 import { createDiagnostic, errorCode, errorMessage } from './diagnostics.ts';
 import type { ConfigFileSystem, LoadedDirectory } from './load-types.ts';
+import {
+  digestWorkflowStep,
+  digestWorkflowStepStructure,
+} from './step-digests.ts';
 import type {
   LoadedWorkflow,
   WorkflowDefinition,
@@ -81,7 +85,13 @@ async function loadWorkflowFile(
   const stepDigests = Object.fromEntries(
     Object.entries(definition.steps).map(([stepId, step]) => [
       stepId,
-      digest({ step, prompt: prompts[stepId] }),
+      digestWorkflowStep(step, prompts[stepId] ?? ''),
+    ]),
+  );
+  const stepStructuralDigests = Object.fromEntries(
+    Object.entries(definition.steps).map(([stepId, step]) => [
+      stepId,
+      digestWorkflowStepStructure(step),
     ]),
   );
   return {
@@ -89,6 +99,7 @@ async function loadWorkflowFile(
     prompts,
     digest: digest({ definition, prompts }),
     stepDigests,
+    stepStructuralDigests,
     sourcePath,
     sourceKind,
   };

package/src/config/step-digests.ts

@@ -0,0 +1,19 @@
+import { digest } from '../digest.ts';
+import type { WorkflowStep } from './types.ts';
+
+/**
+ * Digests a normalized workflow step together with its resolved prompt text.
+ */
+export function digestWorkflowStep(step: WorkflowStep, prompt: string): string {
+  return digest({ step, prompt });
+}
+
+/**
+ * Digests every normalized workflow-step field except the prompt specification.
+ */
+export function digestWorkflowStepStructure(step: WorkflowStep): string {
+  const structure = Object.fromEntries(
+    Object.entries(step).filter(([key]) => key !== 'prompt'),
+  );
+  return digest(structure);
+}

package/src/config/types.ts

@@ -4,14 +4,14 @@ export const WORKFLOW_SCHEMA_VERSION = 1 as const;
 export const DEFAULT_STATUS_SHORTCUT = 'ctrl+alt+w' as const satisfies KeyId;
 export const SUBAGENT_RUNTIME_NAME_PATTERN =
   /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+export const MAX_WORKSPACE_PATH_CHARS = 4_096;
+export const MAX_WORKSPACE_ALLOWED_ROOTS = 32;
 
 export const TERMINAL_TARGETS = ['$done', '$pause'] as const;
 export type TerminalTarget = (typeof TERMINAL_TARGETS)[number];
 export type StepTarget = string;
 
-export type BashMode = 'deny' | 'read-only' | 'allow-list' | 'unrestricted';
-export type BashApprovalSource =
-  'verification-worker' | 'verification-reviewer' | 'remote-actions';
+export type BashMode = 'deny' | 'allow-list' | 'unrestricted';
 
 export type BashRule = {
   readonly executable: string;
@@ -21,11 +21,6 @@ export type BashRule = {
 export type BashPermission = {
   readonly mode: BashMode;
   readonly allow: ReadonlyArray<BashRule>;
-  /**
-   * Exact commands extracted from the most recent human-approved artifact.
-   * They supplement `allow` only inside the correlated step execution.
-   */
-  readonly approvedSources?: ReadonlyArray<BashApprovalSource>;
 };
 
 export type StepPermissions = {
@@ -70,9 +65,9 @@ export type StepSubagent = {
   readonly toolBudget?: SubagentToolBudget;
   readonly artifacts: boolean;
   /**
-   * Authorizes the bounded automatic recovery sequence in Bash modes broader
-   * than read-only. Every failed attempt must still have a complete,
-   * mutation-safe replay audit.
+   * Authorizes bounded automatic recovery when Bash can execute commands.
+   * Every failed attempt must still have a complete, mutation-safe replay
+   * audit.
    */
   readonly retryToolFailures: boolean;
 };
@@ -97,6 +92,13 @@ export type PlannotatorGate = GateDefinition & {
 
 export type WorkflowGate = PromptGate | PlannotatorGate;
 
+export type StepWorkspaceBinding = {
+  /** Outcomes whose result establishes the workspace for later steps. */
+  readonly bindOn: ReadonlyArray<string>;
+  /** Paths relative to the run-start directory that may contain the workspace. */
+  readonly allowedRoots: ReadonlyArray<string>;
+};
+
 export type WorkflowStep = {
   readonly title: string;
   readonly prompt: PromptSpec;
@@ -106,6 +108,8 @@ export type WorkflowStep = {
   readonly requires: StepRequirements;
   readonly transitions: Readonly<Record<string, StepTarget>>;
   readonly gate?: WorkflowGate;
+  /** Optional one-time workspace binding produced by this delegated step. */
+  readonly workspace?: StepWorkspaceBinding;
 };
 
 export type WorkflowDefinition = {
@@ -126,6 +130,8 @@ export type LoadedWorkflow = {
   readonly prompts: Readonly<Record<string, string>>;
   readonly digest: string;
   readonly stepDigests: Readonly<Record<string, string>>;
+  /** Per-step digest excluding only the prompt specification and resolved text. */
+  readonly stepStructuralDigests: Readonly<Record<string, string>>;
   readonly sourcePath: string;
   readonly sourceKind: WorkflowSourceKind;
 };

package/src/config/validation/permissions.ts

@@ -1,6 +1,5 @@
 import {
   EMPTY_PERMISSIONS,
-  type BashApprovalSource,
   type BashMode,
   type BashPermission,
   type BashRule,
@@ -8,7 +7,6 @@ import {
   type StepRequirements,
 } from '../types.ts';
 import {
-  BASH_APPROVAL_SOURCE_PATTERN,
   EXECUTABLE_PATTERN,
   isJsonObject,
   MCP_SELECTOR_PATTERN,
@@ -20,16 +18,6 @@ import {
   type ValidationErrors,
 } from './shared.ts';
 
-const BASH_APPROVAL_SOURCES = [
-  'verification-worker',
-  'verification-reviewer',
-  'remote-actions',
-] as const satisfies ReadonlyArray<BashApprovalSource>;
-
-function isBashApprovalSource(value: string): value is BashApprovalSource {
-  return BASH_APPROVAL_SOURCES.some((source) => source === value);
-}
-
 function emptyPermissions(): StepPermissions {
   return {
     tools: [],
@@ -129,18 +117,13 @@ function parseBashPermission(
     errors.push(`${path}: expected an object`);
     return { ...EMPTY_PERMISSIONS.bash, allow: [] };
   }
-  rejectUnknownKeys(value, ['mode', 'allow', 'approvedSources'], path, errors);
+  rejectUnknownKeys(value, ['mode', 'allow'], path, errors);
 
   const mode = readString(value.mode, `${path}.mode`, errors);
   const isValidMode =
-    mode === 'deny' ||
-    mode === 'read-only' ||
-    mode === 'allow-list' ||
-    mode === 'unrestricted';
+    mode === 'deny' || mode === 'allow-list' || mode === 'unrestricted';
   if (!isValidMode) {
-    errors.push(
-      `${path}.mode: expected deny, read-only, allow-list, or unrestricted`,
-    );
+    errors.push(`${path}.mode: expected deny, allow-list, or unrestricted`);
   }
 
   const allow = Array.isArray(value.allow)
@@ -152,40 +135,17 @@ function parseBashPermission(
     errors.push(`${path}.allow: expected an array`);
   }
 
-  const approvedSources = (
-    value.approvedSources === undefined
-      ? []
-      : readStringList(
-          value.approvedSources,
-          `${path}.approvedSources`,
-          errors,
-          BASH_APPROVAL_SOURCE_PATTERN,
-        )
-  ).filter(isBashApprovalSource);
-
   const normalizedMode: BashMode = isValidMode ? mode : 'deny';
   if (normalizedMode !== 'allow-list' && allow.length > 0) {
     errors.push(`${path}.allow: only valid when mode is "allow-list"`);
   }
-  if (
-    normalizedMode === 'allow-list' &&
-    allow.length === 0 &&
-    approvedSources.length === 0
-  ) {
-    errors.push(
-      `${path}: allow-list mode requires an allow rule or an approved command source`,
-    );
-  }
-  if (normalizedMode !== 'allow-list' && approvedSources.length > 0) {
-    errors.push(
-      `${path}.approvedSources: only valid when mode is "allow-list"`,
-    );
+  if (normalizedMode === 'allow-list' && allow.length === 0) {
+    errors.push(`${path}: allow-list mode requires an allow rule`);
   }
 
   return {
     mode: normalizedMode,
     allow,
-    ...(approvedSources.length > 0 ? { approvedSources } : {}),
   };
 }
 

package/src/config/validation/prompt.ts

@@ -5,7 +5,10 @@ const PROMPT_VARIABLES = new Set([
   'step.id',
   'step.title',
   'last.summary',
+  'reviewed.artifact',
+  'reviewed.feedback',
   'gate.feedback',
+  'resume.input',
 ]);
 
 /** Validate template variables embedded in resolved prompt text. */

package/src/config/validation/shared.ts

@@ -12,8 +12,6 @@ export const TOOL_PATTERN = /^[A-Za-z0-9_.:-]+$/;
 export const RESOURCE_SELECTOR_PATTERN = /^[A-Za-z0-9_@./:+-]+$/;
 export const MCP_SELECTOR_PATTERN = /^[A-Za-z0-9_.:-]+(?:\/[A-Za-z0-9_.:-]+)?$/;
 export const EXECUTABLE_PATTERN = /^[A-Za-z0-9_./+-]+$/;
-export const BASH_APPROVAL_SOURCE_PATTERN =
-  /^(verification-worker|verification-reviewer|remote-actions)$/;
 
 type StringOptions = {
   readonly pattern?: RegExp;

package/src/config/validation/step.ts

@@ -1,10 +1,19 @@
-import type { PromptSpec, WorkflowGate, WorkflowStep } from '../types.ts';
+import { isAbsolute, win32 } from 'node:path';
+import {
+  MAX_WORKSPACE_ALLOWED_ROOTS,
+  MAX_WORKSPACE_PATH_CHARS,
+  type PromptSpec,
+  type StepWorkspaceBinding,
+  type WorkflowGate,
+  type WorkflowStep,
+} from '../types.ts';
 import { parsePermissions, parseRequirements } from './permissions.ts';
 import {
   isJsonObject,
   OUTCOME_PATTERN,
   readInteger,
   readString,
+  readStringList,
   rejectUnknownKeys,
   type ValidationErrors,
 } from './shared.ts';
@@ -135,7 +144,7 @@ function parseGate(
         rejectedOutcome,
         timeoutMs: readInteger(
           value.timeoutMs,
-          5_000,
+          30_000,
           `${path}.timeoutMs`,
           errors,
           { min: 1_000, max: 30_000 },
@@ -143,6 +152,85 @@ function parseGate(
       };
 }
 
+function parseWorkspaceRoots(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): Array<string> {
+  if (value === undefined) return ['.'];
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: expected an array of relative paths`);
+    return [];
+  }
+  if (value.length > MAX_WORKSPACE_ALLOWED_ROOTS) {
+    errors.push(
+      `${path}: at most ${MAX_WORKSPACE_ALLOWED_ROOTS} relative paths are allowed`,
+    );
+  }
+
+  const roots = value
+    .slice(0, MAX_WORKSPACE_ALLOWED_ROOTS)
+    .reduce<Array<string>>((result, item, index) => {
+      const itemPath = `${path}[${index}]`;
+      if (typeof item !== 'string' || !item || item.trim() !== item) {
+        errors.push(`${itemPath}: expected a non-empty relative path`);
+        return result;
+      }
+      const root = item;
+      if (root.length > MAX_WORKSPACE_PATH_CHARS) {
+        errors.push(
+          `${itemPath}: path exceeds ${MAX_WORKSPACE_PATH_CHARS} characters`,
+        );
+        return result;
+      }
+      if (
+        root.includes('\0') ||
+        isAbsolute(root) ||
+        win32.parse(root).root !== ''
+      ) {
+        errors.push(`${itemPath}: expected a relative path`);
+        return result;
+      }
+      if (result.includes(root)) {
+        errors.push(`${itemPath}: duplicate value "${root}"`);
+        return result;
+      }
+      return [...result, root];
+    }, []);
+  if (roots.length === 0) {
+    errors.push(`${path}: at least one relative path is required`);
+  }
+  return roots;
+}
+
+function parseWorkspace(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): StepWorkspaceBinding | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(value, ['bindOn', 'allowedRoots'], path, errors);
+  const bindOn = readStringList(
+    value.bindOn,
+    `${path}.bindOn`,
+    errors,
+    OUTCOME_PATTERN,
+  );
+  if (bindOn.length === 0) {
+    errors.push(`${path}.bindOn: at least one outcome is required`);
+  }
+  const allowedRoots = parseWorkspaceRoots(
+    value.allowedRoots,
+    `${path}.allowedRoots`,
+    errors,
+  );
+  return { bindOn, allowedRoots };
+}
+
 /** Parse one workflow step and validate relationships within that step. */
 export function parseWorkflowStep(
   value: unknown,
@@ -164,6 +252,7 @@ export function parseWorkflowStep(
       'requires',
       'transitions',
       'gate',
+      'workspace',
     ],
     path,
     errors,
@@ -196,6 +285,11 @@ export function parseWorkflowStep(
     errors,
   );
   const gate = parseGate(value.gate, `${path}.gate`, errors);
+  const workspace = parseWorkspace(
+    value.workspace,
+    `${path}.workspace`,
+    errors,
+  );
 
   if (gate) {
     if (!Object.hasOwn(transitions, gate.approvedOutcome)) {
@@ -214,6 +308,15 @@ export function parseWorkflowStep(
       );
     }
   }
+  if (workspace) {
+    workspace.bindOn.forEach((outcome) => {
+      if (!Object.hasOwn(transitions, outcome)) {
+        errors.push(
+          `${path}.workspace.bindOn: unknown transition outcome "${outcome}"`,
+        );
+      }
+    });
+  }
 
   if (!title || !prompt) return undefined;
   return {
@@ -224,5 +327,6 @@ export function parseWorkflowStep(
     requires,
     transitions,
     ...(gate ? { gate } : {}),
+    ...(workspace ? { workspace } : {}),
   };
 }