opencode-plugin-flow 6.0.0 → 6.2.0

package/dist/index.js

@@ -7,8 +7,10 @@ description: Manage a Flow goal from planning through implementation, validation
 # Flow
 
 Flow is a small state ledger around ordinary coding work. The root manager owns
-the session and every state-changing \`flow_*\` call. The reserved
-\`flow-reviewer\` independently reviews; it never edits or mutates Flow state.
+the session, every state-changing \`flow_*\` call, integration, validation,
+review dispatch, reset, and closure. Bounded \`flow-worker\` instances may
+contribute disjoint work inside the active feature. The reserved \`flow-reviewer\`
+independently reviews; it never edits or mutates Flow state.
 
 ## Route from status
 
@@ -32,7 +34,8 @@ report that the plugin is not fully loaded instead of simulating state changes.
 
 - Approved plans do not change. Reset affected work or close the session before
   changing direction.
-- Only one feature runs at a time.
+- Only one durable feature run is active at a time. Conversation-local worker
+  waves do not create additional runs or Flow state.
 - Work stays inside the active feature and preserves unrelated user changes.
 - A passing feature needs successful current-source validation and one
   independent reviewer assignment. The final feature uses broad validation and
@@ -199,9 +202,10 @@ description: Implement, validate, independently review, and record one approved
 
 # Flow Run
 
-Work on exactly one approved feature. The root manager owns edits and every
-state-changing \`flow_*\` call; the reserved \`flow-reviewer\` owns the independent
-review.
+Work on exactly one approved feature. The root manager owns the session, every
+state-changing \`flow_*\` call, integration, validation, review dispatch, reset,
+and closure. Bounded \`flow-worker\` instances may contribute disjoint work; the
+reserved \`flow-reviewer\` owns the independent review.
 
 ## Start and scope
 
@@ -227,9 +231,38 @@ normally be one stable Markdown artifact; JSON requires an explicit request.
 Do not stage, commit, push, publish, or mutate releases unless the user asks for
 that separate action.
 
+## Bounded worker waves
+
+Work serially by default. After manager orientation, fan out only when at least
+two genuinely independent slices can be named. Run one cohort of two or three
+\`flow-worker\` instances at a time. Issue every cohort Task call in the same
+assistant tool-use turn before consuming any result. If the host or model
+serializes those calls, treat and report that execution as serial instead of
+claiming parallelism. Each prompt must name a stable slice id, the exact outcome
+and read or write scope, expected coverage, recommended manager checks,
+dependencies, and a stop condition. Edit scopes must be exact and
+non-overlapping. Shared contracts, lockfiles, and generated outputs remain
+manager-owned unless one worker receives the whole relevant scope.
+
+Workers cannot call Flow tools or spawn children. Each returns one concise
+handoff containing status, scope and coverage, evidence or changed paths,
+recommended manager checks, gaps and risks, and integration notes. Workers do
+not run Bash; all executable checks remain manager-owned. Missing, partial, or
+blocked output remains an explicit coverage gap.
+
+After all workers stop, compare actual changed paths with every assigned scope,
+then inspect the combined diff and evidence and reconcile unexpected paths or
+conflicts before validation. At most one targeted follow-up wave may address a
+failed slice, newly unlocked dependency, or material claim verification. Do
+not start an automatic third wave. Coordination stays in the conversation:
+create no manifest, sidecar, Session field, durable handoff, or recovery ledger.
+After an interruption, inspect Flow status and the worktree and treat partial
+worker edits as untrusted.
+
 ## Validate
 
-Choose checks from the changed behavior and risk:
+Only validate after every worker has stopped and integration is settled. Choose
+checks from the changed behavior and risk:
 
 - Prefer focused behavioral tests that would fail without the change.
 - Cover persistence, integration, API, browser, accessibility, package, or
@@ -307,6 +340,44 @@ if (FLOW_GUIDANCE_BY_ID.size !== FLOW_GUIDANCE_IDS.length) {
 }
 
 // src/prompt-surfaces.ts
+var FLOW_WORKER_PROMPT = `# Flow bounded worker
+
+You are one hidden Flow worker supporting the root manager inside one active feature. Own only the single slice explicitly assigned by that manager. Preserve all unrelated work and do not broaden the assignment.
+
+You may run concurrently with sibling workers. Do not enter their scopes, assume their results, or revert changes you did not make.
+
+## Scope and authority
+
+- Use the manager assignment as your only source of Flow lifecycle context. Do not call any \`flow_*\` tool, including \`flow_status\`.
+- Do not delegate, spawn subtasks, or load skills.
+- Do not stage, commit, push, publish, or create a release.
+- Do not run Bash commands. The manager owns every executable check.
+- Never edit .flow or .git metadata paths; the host denies those paths.
+- A read-only evidence slice must not edit files.
+- An implementation slice may edit only the exact, non-overlapping write paths explicitly assigned by the manager. If required work would escape those paths, stop and return a partial or blocked handoff instead of expanding scope.
+- Use only non-shell inspection relevant to the assigned slice. The manager owns integration, focused checks, and authoritative combined validation after all workers have stopped.
+
+## Handoff
+
+Return exactly one concise handoff using this structure:
+
+## Status
+success | partial | blocked
+
+## Scope & coverage
+- Assigned slice and what was covered
+
+## Findings / changed paths
+- Evidence found or exact paths changed
+
+## Recommended manager checks
+- Exact checks the manager should run, or none
+
+## Gaps & risks
+- Missing coverage, blockers, conflicts, or none
+
+## Integration notes
+- What the manager must verify or integrate, or none`;
 function skillBody(id) {
   return getFlowGuidance(id).content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
 }
@@ -351,6 +422,8 @@ function compileFlowPromptSurface(surface) {
 `);
     case "flow-reviewer":
       return skillBody("flow-review");
+    case "flow-worker":
+      return FLOW_WORKER_PROMPT;
     default: {
       const unsupported = surface;
       throw new Error(`Unsupported Flow prompt surface '${unsupported}'.`);
@@ -374,6 +447,26 @@ var FLOW_CORE_AGENTS = {
       "flow_*": "deny",
       flow_status: "allow"
     }
+  },
+  "flow-worker": {
+    mode: "subagent",
+    hidden: true,
+    description: "Bounded worker for one read-only evidence or exact-scope implementation slice.",
+    prompt: compileFlowPromptSurface("flow-worker"),
+    permission: {
+      edit: {
+        "*": "allow",
+        ".flow": "deny",
+        ".flow/**": "deny",
+        ".git": "deny",
+        ".git/**": "deny"
+      },
+      bash: "deny",
+      external_directory: "deny",
+      skill: "deny",
+      task: { "*": "deny" },
+      "flow_*": "deny"
+    }
   }
 };
 var FLOW_CORE_COMMANDS = {
@@ -432,6 +525,13 @@ function createFlowCoreConfigEntries(options) {
           ...FLOW_CORE_AGENTS["flow-reviewer"].permission,
           task: { "*": "deny" }
         }
+      },
+      "flow-worker": {
+        ...FLOW_CORE_AGENTS["flow-worker"],
+        permission: {
+          ...FLOW_CORE_AGENTS["flow-worker"].permission,
+          task: { "*": "deny" }
+        }
       }
     },
     command: Object.fromEntries(Object.entries(FLOW_CORE_COMMANDS).map(([name, value]) => [
@@ -606,6 +706,39 @@ function planIssue(plan) {
   return visited === plan.features.length ? null : "The plan dependency graph is cyclic.";
 }
 
+// src/domain/session.ts
+function reviewResultSemanticIssues(result) {
+  const issues = [];
+  const blocking = result.findings.some((finding) => finding.severity === "blocking");
+  for (const [index, finding] of result.findings.entries()) {
+    if (finding.severity === "blocking" && !finding.evidence?.trim()) {
+      issues.push({
+        path: ["findings", index, "evidence"],
+        message: "A blocking finding requires concrete evidence."
+      });
+    }
+  }
+  if (result.verdict === "failed" && !blocking) {
+    issues.push({
+      path: ["findings"],
+      message: "A failed review requires a blocking finding."
+    });
+  }
+  if (result.verdict === "passed" && blocking) {
+    issues.push({
+      path: ["findings"],
+      message: "A passed review cannot contain blocking findings."
+    });
+  }
+  if (result.terminalDisposition === "observed_unsubmitted" && result.verdict !== "failed") {
+    issues.push({
+      path: ["terminalDisposition"],
+      message: "Observed-but-unsubmitted review work must fail closed."
+    });
+  }
+  return issues;
+}
+
 // src/domain/transitions.ts
 class FlowTransitionError extends Error {
   code = "FLOW_TRANSITION_REJECTED";
@@ -941,19 +1074,9 @@ function assertReviewResult(result) {
   if (result.findings.length > MAX_REVIEW_FINDINGS) {
     fail(`A review may contain at most ${MAX_REVIEW_FINDINGS} findings.`);
   }
-  const blocking = result.findings.some((finding) => finding.severity === "blocking");
-  const unsupported = result.findings.some((finding) => finding.severity === "blocking" && !finding.evidence?.trim());
-  if (unsupported)
-    fail("A blocking finding requires concrete evidence.");
-  if (result.verdict === "failed" && !blocking) {
-    fail("A failed review requires a blocking finding.");
-  }
-  if (result.verdict === "passed" && blocking) {
-    fail("A passed review cannot contain a blocking finding.");
-  }
-  if (result.terminalDisposition === "observed_unsubmitted" && result.verdict !== "failed") {
-    fail("Observed-but-unsubmitted review work must fail closed.");
-  }
+  const issue = reviewResultSemanticIssues(result)[0];
+  if (issue)
+    fail(issue.message);
 }
 function completeFeature(session, input) {
   assertReviewResult(input.result);
@@ -1364,36 +1487,8 @@ var PublicReviewResultSchema = z.object({
   findings: z.array(ReviewFindingSchema).max(MAX_REVIEW_FINDINGS).default([]),
   terminalDisposition: z.enum(["submitted", "observed_unsubmitted"])
 }).strict().superRefine((result, context) => {
-  const blocking = result.findings.some((finding) => finding.severity === "blocking");
-  for (const [index, finding] of result.findings.entries()) {
-    if (finding.severity === "blocking" && !finding.evidence) {
-      context.addIssue({
-        code: "custom",
-        path: ["findings", index, "evidence"],
-        message: "A blocking finding requires concrete evidence."
-      });
-    }
-  }
-  if (result.verdict === "failed" && !blocking) {
-    context.addIssue({
-      code: "custom",
-      path: ["findings"],
-      message: "A failed review requires a blocking finding."
-    });
-  }
-  if (result.verdict === "passed" && blocking) {
-    context.addIssue({
-      code: "custom",
-      path: ["findings"],
-      message: "A passed review cannot contain blocking findings."
-    });
-  }
-  if (result.terminalDisposition === "observed_unsubmitted" && result.verdict !== "failed") {
-    context.addIssue({
-      code: "custom",
-      path: ["terminalDisposition"],
-      message: "Observed-but-unsubmitted review work must fail closed."
-    });
+  for (const issue of reviewResultSemanticIssues(result)) {
+    context.addIssue({ code: "custom", ...issue });
   }
 });
 var ValidationObservationSchema = z.object({
@@ -2212,7 +2307,7 @@ function validIdentity(value) {
 }
 function canonicalProjectId(scopeId) {
   if (!boundedText2(scopeId))
-    throw new TypeError("Flow leadership scope ID must be a non-empty path.");
+    throw new TypeError("Flow runtime scope must be a non-empty path.");
   const projectId = resolve2(scopeId);
   try {
     return realpathSync2(projectId);
@@ -2260,17 +2355,11 @@ function acquireRegistry() {
 function snapshot(identity) {
   return Object.freeze({ ...identity });
 }
-function makeStatus(identity, reason, registrations = [], registered = false) {
+function makeStatus(reason) {
   const operational = reason === "sole-instance";
   return Object.freeze({
-    instanceId: identity.instanceId,
-    registered,
     operational,
-    role: operational ? "leader" : registered || reason === "incompatible-registry" ? "indeterminate" : "unregistered",
     reason,
-    registeredCount: reason === "incompatible-registry" && !registered ? null : registrations.length,
-    diagnosticLeader: operational ? identity : null,
-    registrations: Object.freeze([...registrations]),
     message: operational ? "Flow is active for this project." : `Flow is not operational (${reason}).`
   });
 }
@@ -2281,7 +2370,7 @@ var createFlowPluginInstanceId = () => globalThis.crypto.randomUUID();
 function registerFlowPluginInstance(scopeId, input) {
   const projectId = canonicalProjectId(scopeId);
   if (!validIdentity(input)) {
-    throw new TypeError("Flow leadership identity is invalid.");
+    throw new TypeError("Flow runtime identity is invalid.");
   }
   const identity = snapshot(input);
   const registry = acquireRegistry();
@@ -2294,7 +2383,7 @@ function registerFlowPluginInstance(scopeId, input) {
     }
     const existing = project.get(identity.instanceId);
     if (existing && !sameIdentity(existing, identity)) {
-      throw new Error(`Flow leadership instance ID '${identity.instanceId}' is already registered with different identity data.`);
+      throw new Error(`Flow runtime instance ID '${identity.instanceId}' is already registered with different identity data.`);
     }
     record = existing ?? identity;
     project.set(identity.instanceId, record);
@@ -2302,32 +2391,28 @@ function registerFlowPluginInstance(scopeId, input) {
   let released = false;
   const query = () => {
     if (released)
-      return makeStatus(identity, "released");
+      return makeStatus("released");
     const currentRegistry = readRegistry();
     if (!record)
-      return makeStatus(identity, "incompatible-registry");
+      return makeStatus("incompatible-registry");
     if (currentRegistry === undefined)
-      return makeStatus(identity, "not-registered");
+      return makeStatus("not-registered");
     if (!compatibleRegistry(currentRegistry))
-      return makeStatus(identity, "incompatible-registry");
+      return makeStatus("incompatible-registry");
     const project = currentRegistry.projects.get(projectId);
-    const registrations = project ? [...project.values()].map(snapshot) : [];
-    if (project?.get(identity.instanceId) !== record) {
-      return makeStatus(identity, "not-registered", registrations);
+    if (!project || project.get(identity.instanceId) !== record) {
+      return makeStatus("not-registered");
     }
     if (identity.protocolVersion !== FLOW_LEADERSHIP_PROTOCOL_VERSION) {
-      return makeStatus(identity, "incompatible-registry", registrations, true);
+      return makeStatus("incompatible-registry");
     }
-    if (registrations.length !== 1) {
-      return makeStatus(identity, "duplicate-instances", registrations, true);
+    if (project.size !== 1) {
+      return makeStatus("duplicate-instances");
     }
-    return makeStatus(identity, "sole-instance", registrations, true);
+    return makeStatus("sole-instance");
   };
   return Object.freeze({
-    identity,
-    scopeId: projectId,
     query,
-    isOperational: () => query().operational,
     assertOperational(action) {
       const current = query();
       if (!current.operational) {
@@ -2815,36 +2900,8 @@ var reviewResult = host.object({
   findings: host.array(reviewFinding).max(MAX_REVIEW_FINDINGS).default([]),
   terminalDisposition: host.enum(["submitted", "observed_unsubmitted"])
 }).strict().superRefine((result, context) => {
-  const blocking = result.findings.some((finding) => finding.severity === "blocking");
-  for (const [index, finding] of result.findings.entries()) {
-    if (finding.severity === "blocking" && !finding.evidence) {
-      context.addIssue({
-        code: "custom",
-        path: ["findings", index, "evidence"],
-        message: "A blocking finding requires concrete evidence."
-      });
-    }
-  }
-  if (result.verdict === "failed" && !blocking) {
-    context.addIssue({
-      code: "custom",
-      path: ["findings"],
-      message: "A failed review requires a blocking finding."
-    });
-  }
-  if (result.verdict === "passed" && blocking) {
-    context.addIssue({
-      code: "custom",
-      path: ["findings"],
-      message: "A passed review cannot contain blocking findings."
-    });
-  }
-  if (result.terminalDisposition === "observed_unsubmitted" && result.verdict !== "failed") {
-    context.addIssue({
-      code: "custom",
-      path: ["terminalDisposition"],
-      message: "Observed-but-unsubmitted review work must fail closed."
-    });
+  for (const issue of reviewResultSemanticIssues(result)) {
+    context.addIssue({ code: "custom", ...issue });
   }
 });
 var StatusArgs = {
@@ -3045,7 +3102,7 @@ class ValidationCaptureCoordinator {
   #prune() {
     const cutoff = this.#now() - CAPTURE_TTL_MS;
     for (const [sessionID, capture] of this.#pending) {
-      if (capture.armedAt < cutoff) {
+      if (capture.callID === null && capture.armedAt < cutoff) {
         this.#pending.delete(sessionID);
       }
     }
@@ -3174,17 +3231,18 @@ function createCommandHook(assertOperational) {
     }
   };
 }
-function guardTools(tools, leadership) {
+function guardTools(tools, runtimeGuard) {
   return Object.fromEntries(Object.entries(tools).map(([name, definition]) => [
     name,
     {
       ...definition,
       execute: async (...args) => {
-        if (!leadership.isOperational()) {
+        const status = runtimeGuard.query();
+        if (!status.operational) {
           return JSON.stringify({
             status: "error",
-            summary: "Flow is disabled because more than one runtime is registered for this project.",
-            workflowData: { runtimeGuard: leadership.query() }
+            summary: status.message,
+            workflowData: { runtimeGuard: status }
           });
         }
         return definition.execute(...args);
@@ -3195,13 +3253,13 @@ function guardTools(tools, leadership) {
 var FlowPlugin = async (ctx) => {
   const log = createFlowLog(ctx);
   const version = resolveFlowPluginVersion();
-  const leadership = registerFlowPluginInstance(ctx.worktree ?? ctx.directory, {
+  const runtimeGuard = registerFlowPluginInstance(ctx.worktree ?? ctx.directory, {
     packageName: "opencode-plugin-flow",
     version,
     protocolVersion: FLOW_LEADERSHIP_PROTOCOL_VERSION,
     instanceId: createFlowPluginInstanceId()
   });
-  const initial = leadership.query();
+  const initial = runtimeGuard.query();
   log(initial.operational ? "info" : "error", `Flow ${version}: ${initial.message}`);
   const validation = new ValidationCaptureCoordinator({
     persistObservation: persistWorkspaceValidation
@@ -3212,10 +3270,10 @@ var FlowPlugin = async (ctx) => {
   });
   return {
     config: createConfigHook(ctx, {
-      assertOperational: (action) => leadership.assertOperational(action)
+      assertOperational: (action) => runtimeGuard.assertOperational(action)
     }),
-    tool: guardTools(tools, leadership),
-    "command.execute.before": createCommandHook((action) => leadership.assertOperational(action)),
+    tool: guardTools(tools, runtimeGuard),
+    "command.execute.before": createCommandHook((action) => runtimeGuard.assertOperational(action)),
     event: async (input) => {
       const event = input.event;
       if (event.type !== "session.idle" && event.type !== "session.compacted") {
@@ -3240,7 +3298,7 @@ var FlowPlugin = async (ctx) => {
       }
     },
     dispose: async () => {
-      leadership.release();
+      runtimeGuard.release();
     }
   };
 };
@@ -3249,4 +3307,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=11C725AFDFE8E73E64756E2164756E21
+//# debugId=48BDB7D8B1F2A60764756E2164756E21