@wichayutdew/pi-workflows 1.0.1 → 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,33 +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",
-              "remote-push",
-              "remote-drafts"
-            ]
-          }
-        },
-        "handoffSources": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": {
-            "enum": ["verification-worker", "verification-reviewer"]
-          }
         }
       }
     },
@@ -555,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",
@@ -595,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,21 +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 ?? []);
-  const allowedHandoffSources = new Set(ceiling.handoffSources ?? []);
-  return (
-    requested.allow.every((rule) => allowedRules.has(ruleKey(rule))) &&
-    (requested.approvedSources ?? []).every((source) =>
-      allowedSources.has(source),
-    ) &&
-    (requested.handoffSources ?? []).every((source) =>
-      allowedHandoffSources.has(source),
-    )
-  );
+  return requested.allow.every((rule) => allowedRules.has(ruleKey(rule)));
 }
 
 function turnBudgetErrors(
@@ -128,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,18 +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'
-  | 'remote-push'
-  | 'remote-drafts';
+export type BashMode = 'deny' | 'allow-list' | 'unrestricted';
 
 export type BashRule = {
   readonly executable: string;
@@ -25,18 +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>;
-  /**
-   * Sources whose command-only retry handoffs may refine an already approved
-   * command. The original reviewed identity and safety envelope remain fixed.
-   */
-  readonly handoffSources?: ReadonlyArray<
-    'verification-worker' | 'verification-reviewer'
-  >;
 };
 
 export type StepPermissions = {
@@ -81,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;
 };
@@ -108,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;
@@ -117,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 = {
@@ -137,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,18 +18,6 @@ import {
   type ValidationErrors,
 } from './shared.ts';
 
-const BASH_APPROVAL_SOURCES = [
-  'verification-worker',
-  'verification-reviewer',
-  'remote-actions',
-  'remote-push',
-  'remote-drafts',
-] 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: [],
@@ -131,23 +117,13 @@ function parseBashPermission(
     errors.push(`${path}: expected an object`);
     return { ...EMPTY_PERMISSIONS.bash, allow: [] };
   }
-  rejectUnknownKeys(
-    value,
-    ['mode', 'allow', 'approvedSources', 'handoffSources'],
-    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)
@@ -159,54 +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 handoffSources = (
-    value.handoffSources === undefined
-      ? []
-      : readStringList(
-          value.handoffSources,
-          `${path}.handoffSources`,
-          errors,
-          /^(verification-worker|verification-reviewer)$/,
-        )
-  ) as Array<'verification-worker' | 'verification-reviewer'>;
-
   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' && handoffSources.length > 0) {
-    errors.push(`${path}.handoffSources: 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 } : {}),
-    ...(handoffSources.length > 0 ? { handoffSources } : {}),
   };
 }
 

package/src/config/validation/prompt.ts

@@ -8,6 +8,7 @@ const PROMPT_VARIABLES = new Set([
   '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|remote-push|remote-drafts)$/;
 
 type StringOptions = {
   readonly pattern?: RegExp;