opencode-plugin-flow 5.2.0 → 5.2.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [5.2.1] - 2026-07-19
+
+Desktop helper runtime lore restores durable session closure under OpenCode
+Desktop while preserving Flow's pinned-filesystem safety boundary:
+
+- Electron-hosted Flow now starts its short-lived filesystem helper through the
+  host executable's Node mode. Bun-hosted OpenCode retains its dedicated CLI
+  mode, and ordinary Node hosts remain unchanged.
+- Helper launch and protocol failures are classified separately from malformed
+  or ambiguous canonical history. Recovery guidance preserves the active
+  session and its exact durable close operation instead of blaming healthy
+  archive state.
+- Persistence coverage exercises the Electron launch contract end to end and
+  proves that runtime failures remain atomic and receive the correct guidance.
+
 ## [5.2.0] - 2026-07-19
 
 Runtime-owned review assignment lore removes the recovery loops seen in long

package/README.md

@@ -17,7 +17,7 @@ Full project documentation is available in the
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@5.2.0 --global --force
+opencode plugin opencode-plugin-flow@5.2.1 --global --force
 ```
 
 Start or restart OpenCode, then give Flow a goal:
@@ -235,7 +235,7 @@ or sync command is required. To preview recoverable migration of pristine v4
 global skill folders:
 
 ```bash
-npx -y opencode-plugin-flow@5.2.0 legacy-cleanup --dry-run
+npx -y opencode-plugin-flow@5.2.1 legacy-cleanup --dry-run
 ```
 
 ## Development

package/dist/application/ports/session-repository.d.ts

@@ -3,7 +3,10 @@ import type { EvidenceArtifactStore } from "./evidence-artifact-store.js";
 import type { SourceIdentityProvider } from "./source-identity.js";
 export declare class ArchivedSessionLookupError extends Error {
     readonly code = "FLOW_ARCHIVE_LOOKUP_FAILED";
-    constructor(message: string, options?: ErrorOptions);
+    readonly failureKind: "history-integrity" | "helper-runtime";
+    constructor(message: string, options?: ErrorOptions & {
+        failureKind?: "history-integrity" | "helper-runtime";
+    });
 }
 export type SessionTransaction = EvidenceArtifactStore & SourceIdentityProvider & {
     load(): Promise<Session | null>;

package/dist/index.js

@@ -3313,9 +3313,11 @@ class UnsupportedFlowSessionVersionError extends Error {
 // src/application/ports/session-repository.ts
 class ArchivedSessionLookupError extends Error {
   code = "FLOW_ARCHIVE_LOOKUP_FAILED";
+  failureKind;
   constructor(message, options) {
     super(message, options);
     this.name = "ArchivedSessionLookupError";
+    this.failureKind = options?.failureKind ?? "history-integrity";
   }
 }
 
@@ -7292,6 +7294,17 @@ async function assertManagedDirectoryIdentity(path, description, expected) {
     throw new UnsafeFlowWorkspaceLayoutError(`Flow detected that ${description} changed during a managed operation: ${path}.`);
   }
 }
+
+class PinnedFilesystemHelperError extends Error {
+  code = "FLOW_PINNED_HELPER_FAILED";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PinnedFilesystemHelperError";
+  }
+}
+function pinnedHelperFailure(message, cause) {
+  return new PinnedFilesystemHelperError(message, { cause });
+}
 function helperFailure(stderr, cause) {
   let detail = null;
   try {
@@ -7300,16 +7313,23 @@ function helperFailure(stderr, cause) {
   if (detail?.code === "FLOW_PINNED_DIRECTORY_MISMATCH" || detail?.code === "FLOW_ARCHIVE_CASE_COLLISION" || detail?.code === "FLOW_ARCHIVE_UNKNOWN_JSON") {
     return new UnsafeFlowWorkspaceLayoutError(detail.message ?? "Flow detected an unsafe pinned directory change.", { cause });
   }
-  const error = new Error(detail?.message ?? "Flow pinned filesystem helper failed.", { cause });
-  if (detail?.code)
-    error.code = detail.code;
-  return error;
+  return new PinnedFilesystemHelperError(detail?.message ?? "Flow pinned filesystem helper failed.", { cause });
+}
+function pinnedHelperEnvironment(runtime) {
+  if (runtime === "electron") {
+    return { ...process.env, ELECTRON_RUN_AS_NODE: "1" };
+  }
+  if (runtime === "bun") {
+    return { ...process.env, BUN_BE_BUN: "1" };
+  }
+  return process.env;
 }
 async function runPinnedDirectoryHelper(cwd, request, input = "", afterPinned, options = {}) {
   const encodedRequest = Buffer.from(JSON.stringify(request), "utf8").toString("base64");
+  const runtime = options.pinnedHelperTestRuntime ?? (process.versions.electron ? "electron" : process.versions.bun ? "bun" : "node");
   const child = spawn(options.pinnedHelperTestExecutable ?? process.execPath, ["--eval", PINNED_DIRECTORY_HELPER_SOURCE, encodedRequest], {
     cwd,
-    env: process.versions.bun ? { ...process.env, BUN_BE_BUN: "1" } : process.env,
+    env: pinnedHelperEnvironment(runtime),
     stdio: ["pipe", "pipe", "pipe"],
     windowsHide: true
   });
@@ -7337,7 +7357,7 @@ async function runPinnedDirectoryHelper(cwd, request, input = "", afterPinned, o
     child.kill("SIGKILL");
   };
   const readyTimeout = setTimeout(() => {
-    terminateHelper(new Error("Flow pinned filesystem helper timed out before readiness."));
+    terminateHelper(pinnedHelperFailure("Flow pinned filesystem helper timed out before readiness."));
   }, positiveTimeout(options.pinnedHelperReadyTimeoutMs, PINNED_HELPER_READY_TIMEOUT_MS));
   readyTimeout.unref();
   let completionTimeout;
@@ -7351,18 +7371,18 @@ async function runPinnedDirectoryHelper(cwd, request, input = "", afterPinned, o
         try {
           event = JSON.parse(stdout.slice(0, newline));
         } catch (error) {
-          terminateHelper(new Error("Flow pinned filesystem helper returned an invalid ready event.", { cause: error }));
+          terminateHelper(pinnedHelperFailure("Flow pinned filesystem helper returned an invalid ready event.", error));
           return;
         }
         if (event.event !== "pinned") {
-          terminateHelper(new Error("Flow pinned filesystem helper omitted its ready event."));
+          terminateHelper(pinnedHelperFailure("Flow pinned filesystem helper omitted its ready event."));
           return;
         }
         stdout = stdout.slice(newline + 1);
         readyState = "resolved";
         clearTimeout(readyTimeout);
         completionTimeout = setTimeout(() => {
-          terminateHelper(new Error("Flow pinned filesystem helper timed out before completion."));
+          terminateHelper(pinnedHelperFailure("Flow pinned filesystem helper timed out before completion."));
         }, positiveTimeout(options.pinnedHelperCompletionTimeoutMs, PINNED_HELPER_COMPLETION_TIMEOUT_MS));
         completionTimeout.unref();
         resolvePinned?.();
@@ -7394,7 +7414,7 @@ async function runPinnedDirectoryHelper(cwd, request, input = "", afterPinned, o
         return;
       }
       if (readyState !== "resolved") {
-        const failure = new Error("Flow pinned filesystem helper exited before readiness.");
+        const failure = pinnedHelperFailure("Flow could not start its pinned filesystem helper under the current host runtime.");
         if (readyState === "pending") {
           readyState = "rejected";
           rejectPinned?.(failure);
@@ -7409,9 +7429,7 @@ async function runPinnedDirectoryHelper(cwd, request, input = "", afterPinned, o
       try {
         resolve2(JSON.parse(stdout));
       } catch (error) {
-        reject(new Error("Flow pinned filesystem helper returned invalid output.", {
-          cause: error
-        }));
+        reject(pinnedHelperFailure("Flow pinned filesystem helper returned invalid output.", error));
       }
     });
   });
@@ -7645,6 +7663,12 @@ async function findCanonicalArchivedSession(worktree, predicate) {
   } catch (error) {
     if (error instanceof ArchivedSessionLookupError)
       throw error;
+    if (error instanceof PinnedFilesystemHelperError) {
+      throw new ArchivedSessionLookupError(error.message, {
+        cause: error,
+        failureKind: "helper-runtime"
+      });
+    }
     throw new ArchivedSessionLookupError("Flow could not verify archived operation history safely.", { cause: error });
   }
 }
@@ -8171,43 +8195,46 @@ function archivedCloseResponse(session, operationId) {
   }, [], operationId);
 }
 function archivedLookupFailureResponse(error, operationId) {
+  const helperRuntimeFailure = error.failureKind === "helper-runtime";
   return rejectedMutationResponse({
     status: "error",
-    summary: "Flow could not verify archived retry history.",
-    nextAction: "Inspect canonical Flow history integrity before retrying this close operation.",
+    summary: helperRuntimeFailure ? "Flow could not start its filesystem helper to read archived retry history." : "Flow could not verify archived retry history.",
+    nextAction: helperRuntimeFailure ? "Restart OpenCode with the current Flow build, then retry this close operation." : "Inspect canonical Flow history integrity before retrying this close operation.",
     dataNote: WORKFLOW_DATA_NOTE,
     workflowData: {
       failure: {
         summary: error.message,
-        recovery: "Preserve archive files and resolve corrupt or ambiguous canonical history; quarantine records are not replay sources."
+        recovery: helperRuntimeFailure ? "Preserve Flow state, restart OpenCode after updating Flow, and retry with the same close operation id." : "Preserve archive files and resolve corrupt or ambiguous canonical history; quarantine records are not replay sources."
       }
     }
   }, null, operationId);
 }
 function archivedCloseStartLookupFailureResponse(error, session, operationId) {
+  const helperRuntimeFailure = error.failureKind === "helper-runtime";
   return rejectedMutationResponse({
     status: "error",
-    summary: "Flow could not prove that this close operation id is unique in canonical history.",
-    nextAction: "Inspect canonical Flow history integrity before starting this close operation.",
+    summary: helperRuntimeFailure ? "Flow could not start its filesystem helper to verify this close operation id." : "Flow could not prove that this close operation id is unique in canonical history.",
+    nextAction: helperRuntimeFailure ? "Restart OpenCode with the current Flow build, then start this close operation again." : "Inspect canonical Flow history integrity before starting this close operation.",
     dataNote: WORKFLOW_DATA_NOTE,
     workflowData: {
       failure: {
         summary: error.message,
-        recovery: "Preserve the active session and resolve corrupt or ambiguous canonical history before retrying with a verified operation id."
+        recovery: helperRuntimeFailure ? "Preserve the active session, restart OpenCode after updating Flow, and retry with the same unconsumed operation id." : "Preserve the active session and resolve corrupt or ambiguous canonical history before retrying with a verified operation id."
       }
     }
   }, session, operationId);
 }
 function archivedCloseRetryLookupFailureResponse(error, session, operationId) {
+  const helperRuntimeFailure = error.failureKind === "helper-runtime";
   return rejectedMutationResponse({
     status: "error",
-    summary: "Flow could not verify canonical history before publishing the pending close.",
-    nextAction: "Inspect canonical Flow history integrity before retrying archive publication.",
+    summary: helperRuntimeFailure ? "Flow could not start its filesystem helper before publishing the pending close." : "Flow could not verify canonical history before publishing the pending close.",
+    nextAction: helperRuntimeFailure ? "Restart OpenCode with the current Flow build, then retry archive publication." : "Inspect canonical Flow history integrity before retrying archive publication.",
     dataNote: WORKFLOW_DATA_NOTE,
     workflowData: {
       failure: {
         summary: error.message,
-        recovery: "Preserve the active closed session and resolve corrupt, ambiguous, or conflicting canonical history before retrying its durable close operation."
+        recovery: helperRuntimeFailure ? "Preserve the active closed session, restart OpenCode after updating Flow, and retry its exact durable close operation." : "Preserve the active closed session and resolve corrupt, ambiguous, or conflicting canonical history before retrying its durable close operation."
       }
     }
   }, session, operationId);
@@ -9862,4 +9889,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=A0752D8309CC46B964756E2164756E21
+//# debugId=E001CAB8DE3EBE1964756E2164756E21