@tranhoangnguyen0310/pi-flow-external 3.1.0-external.0 → 3.1.1-external.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [3.1.1-external.0] - 2026-10-02
+
+### Fixed
+- `external_runs list` no longer reports live work as `interrupted_or_uncertain` on later pages, or lists a live run twice. Live state now replaces a run's persisted row on whichever page that row falls. Live runs with no persisted row yet (for example, while evidence writes fail) are paged first and count against `limit`, so every page stays within `limit`. The cursor bookmarks the last such run in registry order, so persisting one between pages never skips another; it can only appear twice (once live, once persisted). If the bookmarked run has left the registry, the next page fails with "Run list changed while paging" instead of guessing. A run started after the listing reached its persisted rows appears in the next fresh listing.
+- One unreadable workflow journal (an incompatible version, a corrupt start line, or a read error) no longer fails the whole `list`. It is listed as one `interrupted_or_uncertain` row with the read error; `inspect` of that ID still reports the error.
+- A workflow launched after its session closed no longer throws with its journal left open. The journal is settled as failed, and the call returns an error result naming the closed session.
+- Workflow resume no longer reveals that another project's run exists: it reports the same "run journal not found" message as an unknown run ID.
+
 ## [3.1.0-external.0] - 2026-10-02
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "3.1.0-external.0",
+  "version": "3.1.1-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/external-runs.ts

@@ -12,7 +12,7 @@ import { renderOutputText } from "./core/subagent-render.ts";
 import { SPINNER_INTERVAL_MS } from "./core/spinner.ts";
 import { EXTERNAL_RUNS_PROMPT_SNIPPET } from "./prompts.ts";
 import type { WorkflowToolDetails } from "./types.ts";
-import { getSessionWorkflowDir, listWorkflowJournals, loadWorkflowJournal, type LoadedWorkflowJournal } from "./workflow/journal.ts";
+import { getSessionWorkflowDir, listWorkflowJournals, loadWorkflowJournal, WorkflowJournalReadError, type LoadedWorkflowJournal, type UnreadableWorkflowJournal } from "./workflow/journal.ts";
 
 const RUN_ID = /^(?:run|wf)_[A-Za-z0-9_-]{1,128}$/;
 const WORKFLOW_ID = /^wf_[A-Za-z0-9_-]{1,128}$/;
@@ -219,6 +219,97 @@ function journalSummary(journal: LoadedWorkflowJournal, allChildren = false) {
   };
 }
 
+/** A listed journal that could not be loaded: one uncertain row instead of a failed listing. */
+function unreadableJournalSummary(journal: UnreadableWorkflowJournal) {
+  return {
+    ...projectWorkflowRun({
+      runId: journal.runId,
+      live: false,
+      status: "interrupted_or_uncertain",
+      error: clip(journal.unreadable),
+      resultAvailable: false,
+      finalAvailable: false,
+    }),
+    children: [],
+  };
+}
+
+/** Mirrors the listing's own inclusion rule, so a journal is counted persisted exactly when some page lists it. */
+async function hasWorkflowJournal(dir: string, runId: string, project: string): Promise<boolean> {
+  try {
+    return (await loadWorkflowJournal(dir, runId))?.project === project;
+  } catch (error) {
+    const owner = error instanceof WorkflowJournalReadError ? error.project : undefined;
+    return owner === undefined || owner === project;
+  }
+}
+
+function listScope(stream: "runs" | "workflows", sessionId: string, project: string, workflowRunId?: string): string {
+  return JSON.stringify({ stream, sessionId, project, workflowRunId });
+}
+
+type UnpersistedBookmark = { after: string } | { persisted: true };
+
+function encodeUnpersistedCursor(scope: string, bookmark: UnpersistedBookmark): string {
+  return Buffer.from(JSON.stringify({ v: 1, kind: "unpersisted-list", scope, ...bookmark })).toString("base64url");
+}
+
+/** The bookmark of an unpersisted-stage cursor, or undefined for any other cursor (passed on to the persisted listing). */
+function decodeUnpersistedCursor(value: string, scope: string): UnpersistedBookmark | undefined {
+  let parsed: Record<string, unknown> | undefined;
+  try {
+    parsed = record(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+  } catch {
+    return undefined;
+  }
+  if (parsed?.kind !== "unpersisted-list") return undefined;
+  const keys = Object.keys(parsed).sort().join(",");
+  const valid = parsed.v === 1 && ((keys === "after,kind,scope,v" && typeof parsed.after === "string" && RUN_ID.test(parsed.after)) || (keys === "kind,persisted,scope,v" && parsed.persisted === true));
+  if (!valid) throw new Error("Invalid list cursor");
+  if (parsed.scope !== scope) throw new Error("Cursor belongs to a different list scope");
+  return typeof parsed.after === "string" ? { after: parsed.after } : { persisted: true };
+}
+
+/**
+ * One bounded list page: live runs with no persisted row first, then
+ * persisted rows, all within `pageSize`. The unpersisted stage bookmarks the
+ * last run it served, in registry order. Persisting a run never removes it
+ * from the registry, so a later page always resumes after the same run and
+ * none is skipped. If the bookmarked run has left the registry, continuation
+ * fails as stale rather than guessing. A run persisted between pages may
+ * appear in both stages; a run registered after the listing reached its
+ * persisted stage appears in the next fresh listing.
+ */
+async function pageUnpersistedFirst<L extends { runId: string }, D>(
+  scope: string,
+  cursor: string | undefined,
+  pageSize: number,
+  candidates: L[],
+  isUnpersisted: (candidate: L) => Promise<boolean>,
+  persisted: (limit: number, cursor: string | undefined) => Promise<{ items: D[]; nextCursor?: string }>,
+): Promise<{ live: L[]; items: D[]; nextCursor?: string }> {
+  const bookmark = cursor === undefined ? undefined : decodeUnpersistedCursor(cursor, scope);
+  if (cursor !== undefined && bookmark === undefined) return { live: [], ...await persisted(pageSize, cursor) };
+  if (bookmark && "persisted" in bookmark) return { live: [], ...await persisted(pageSize, undefined) };
+  let start = 0;
+  if (bookmark) {
+    const index = candidates.findIndex((candidate) => candidate.runId === bookmark.after);
+    if (index < 0) throw new Error("Run list changed while paging; restart the listing without a cursor");
+    start = index + 1;
+  }
+  // Find one more than fits, to know whether the unpersisted stage continues.
+  const live: L[] = [];
+  for (let index = start; index < candidates.length && live.length <= pageSize; index++) {
+    if (await isUnpersisted(candidates[index]!)) live.push(candidates[index]!);
+  }
+  if (live.length > pageSize) {
+    const served = live.slice(0, pageSize);
+    return { live: served, items: [], nextCursor: encodeUnpersistedCursor(scope, { after: served.at(-1)!.runId }) };
+  }
+  if (live.length === pageSize) return { live, items: [], nextCursor: encodeUnpersistedCursor(scope, { persisted: true }) };
+  return { live, ...await persisted(pageSize - live.length, undefined) };
+}
+
 function projectionRevision(text: string): string {
   return createHash("sha256").update(text).digest("hex");
 }
@@ -685,30 +776,44 @@ export function createExternalRunsTool(
 
       if (params.action === "list") {
         if (params.workflowRunId !== undefined && !WORKFLOW_ID.test(params.workflowRunId)) throw new Error("Invalid workflow run ID");
-        const page = params.workflowCursor && !params.cursor
-          ? { items: [] }
-          : await listRunRecords({
-              runsDirectory,
-              sessionId,
-              project,
-              workflowRunId: params.workflowRunId,
-              limit: params.limit,
-              cursor: params.cursor,
-            });
         const workflowDir = getSessionWorkflowDir(ctx);
-        const historical = !params.workflowRunId && workflowDir
-          ? await listWorkflowJournals(workflowDir, project, params.limit, params.workflowCursor)
-          : { items: [] };
-        const current = params.cursor || params.workflowCursor || params.workflowRunId
-          ? []
-          : options.registry.list(sessionId, project).filter((entry) => entry.kind === "workflow").map((entry) => liveSummary(entry));
-        const currentIds = new Set(current.map((entry) => entry.runId));
-        const workflows = [...current, ...historical.items.filter((journal) => !currentIds.has(journal.runId)).map((journal) => journalSummary(journal))];
-        const liveAgents = params.cursor || params.workflowCursor ? [] : options.registry.list(sessionId, project)
-          .filter((entry) => entry.kind === "agent" && (params.workflowRunId === undefined || entry.workflowRunId === params.workflowRunId))
-          .map(listedAgent);
-        const liveIds = new Set(liveAgents.map((entry) => entry.runId));
-        const runs = [...liveAgents, ...page.items.filter((entry) => !liveIds.has(entry.runId)).map(historicalAgent)];
+        // Live state overlays its persisted row on whichever page that row
+        // falls, so a live run is never shown as interrupted or listed twice.
+        // Live runs with no persisted row yet are paged first, inside the same
+        // limit, before the persisted rows begin.
+        const registered = new Map(options.registry.list(sessionId, project).map((entry) => [entry.runId, entry]));
+        const runScope = listScope("runs", sessionId, project, params.workflowRunId);
+        const page = params.workflowCursor && !params.cursor
+          ? { live: [], items: [] }
+          : await pageUnpersistedFirst(runScope, params.cursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 50))),
+            [...registered.values()].filter((entry) => entry.kind === "agent" && (params.workflowRunId === undefined || entry.workflowRunId === params.workflowRunId)),
+            async (entry) => {
+              const persisted = await getRunRecord(runsDirectory, entry.runId);
+              return !persisted || persisted.parentSessionId !== sessionId || persisted.project !== project
+                || (params.workflowRunId !== undefined && persisted.workflowRunId !== params.workflowRunId);
+            },
+            (limit, cursor) => listRunRecords({ runsDirectory, sessionId, project, workflowRunId: params.workflowRunId, limit, cursor }));
+        const historical = params.workflowRunId
+          ? { live: [], items: [] }
+          : await pageUnpersistedFirst(listScope("workflows", sessionId, project), params.workflowCursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 100))),
+            [...registered.values()].filter((entry) => entry.kind === "workflow"),
+            async (entry) => !workflowDir || !await hasWorkflowJournal(workflowDir, entry.runId, project),
+            async (limit, cursor) => workflowDir ? listWorkflowJournals(workflowDir, project, limit, cursor) : { items: [] });
+        const workflows = [
+          ...historical.live.map((entry) => liveSummary(entry)),
+          ...historical.items.map((journal) => {
+            const live = registered.get(journal.runId);
+            if (live?.kind === "workflow") return liveSummary(live);
+            return "unreadable" in journal ? unreadableJournalSummary(journal) : journalSummary(journal);
+          }),
+        ];
+        const runs = [
+          ...page.live.map(listedAgent),
+          ...page.items.map((item) => {
+            const live = registered.get(item.runId);
+            return live?.kind === "agent" ? listedAgent(live) : historicalAgent(item);
+          }),
+        ];
         const list = { workflows, runs, nextCursor: page.nextCursor, nextWorkflowCursor: historical.nextCursor };
         return result(JSON.stringify(list), list);
       }

package/src/workflow/journal.ts

@@ -41,6 +41,14 @@ export interface LoadedWorkflowJournal {
   children: Array<{ index: number; runId?: string; label?: string; status: "queued" | "done" | "error" | "aborted"; outcome?: ChildRunOutcome; error?: unknown }>;
 }
 
+/** A journal that exists but cannot be loaded; `project` is set when its own run_start line names one. */
+export class WorkflowJournalReadError extends Error {
+  constructor(message: string, readonly project?: string) {
+    super(message);
+    this.name = "WorkflowJournalReadError";
+  }
+}
+
 export interface WorkflowJournalWriter {
   runId: string;
   path: string;
@@ -128,8 +136,9 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
     }
     if (entry.type === "run_start") {
       if (entry.version !== JOURNAL_VERSION || entry.apiVersion !== WORKFLOW_API_VERSION) {
-        throw new Error(
+        throw new WorkflowJournalReadError(
           `Workflow journal ${path} uses an incompatible API contract; recompose with meta.apiVersion: ${WORKFLOW_API_VERSION}. No children were launched`,
+          typeof entry.project === "string" ? entry.project : undefined,
         );
       }
       seenRunStart = entry.runId === runId;
@@ -190,13 +199,19 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
   }
 
   if (!seenRunStart) {
-    throw new Error(`Workflow journal ${path} does not match run id ${runId}`);
+    throw new WorkflowJournalReadError(`Workflow journal ${path} does not match run id ${runId}`, project);
   }
   return { launch, runId, path, agentResults, name, source, project, status, outcome, result, error: terminalError, children: children.filter(Boolean) };
 }
 
+/** A listed journal that failed to load: shown as its own row instead of failing the whole listing. */
+export interface UnreadableWorkflowJournal {
+  runId: string;
+  unreadable: string;
+}
+
 export interface WorkflowJournalPage {
-  items: LoadedWorkflowJournal[];
+  items: Array<LoadedWorkflowJournal | UnreadableWorkflowJournal>;
   nextCursor?: string;
 }
 
@@ -228,12 +243,19 @@ export async function listWorkflowJournals(dir: string, project: string, limit =
   }
   const start = workflowListStart(names, cursor);
   const pageLimit = Math.max(1, Math.min(100, limit));
-  const journals: LoadedWorkflowJournal[] = [];
+  const journals: WorkflowJournalPage["items"] = [];
   let index = start;
   for (; index < names.length && index < start + 200; index++) {
     const name = names[index]!;
-    const journal = await loadWorkflowJournal(dir, name.slice(4, -6));
-    if (journal?.project === project) journals.push(journal);
+    const runId = name.slice(4, -6);
+    try {
+      const journal = await loadWorkflowJournal(dir, runId);
+      if (journal?.project === project) journals.push(journal);
+    } catch (error) {
+      // The directory is this session's own; a journal whose project cannot be read is still listed so it is never silently dropped.
+      const owner = error instanceof WorkflowJournalReadError ? error.project : undefined;
+      if (owner === undefined || owner === project) journals.push({ runId, unreadable: error instanceof Error ? error.message : String(error) });
+    }
     if (journals.length >= pageLimit) {
       index++;
       break;

package/src/workflow/source.ts

@@ -6,6 +6,7 @@ import {
   createWorkflowJournalWriter,
   createWorkflowRunIdentity,
   getSessionWorkflowDir,
+  WorkflowJournalReadError,
   loadWorkflowJournal,
   persistWorkflowScript,
   type WorkflowJournalWriter,
@@ -270,19 +271,23 @@ export async function prepareWorkflowToolSource(
     try {
       journal = await loadWorkflowJournal(sessionWorkflowDir, resumeFromRunId);
     } catch (error) {
-      const message = `Cannot resume workflow: ${error instanceof Error ? error.message : String(error)}`;
-      return sourceError(message, {
-        name: metaName,
-        error: message,
-        logs: source.warnings,
-        source: source.source,
-        sourcePath: source.sourcePath,
-        scriptPath,
-        runId: identity.runId,
-        resumeFromRunId,
-      });
+      // Another project's unreadable journal is reported exactly like a missing one.
+      if (!(error instanceof WorkflowJournalReadError) || error.project === undefined || error.project === project) {
+        const message = `Cannot resume workflow: ${error instanceof Error ? error.message : String(error)}`;
+        return sourceError(message, {
+          name: metaName,
+          error: message,
+          logs: source.warnings,
+          source: source.source,
+          sourcePath: source.sourcePath,
+          scriptPath,
+          runId: identity.runId,
+          resumeFromRunId,
+        });
+      }
     }
-    if (!journal) {
+    // Another project's run is indistinguishable from an unknown one.
+    if (!journal || journal.project !== project) {
       const message = `Cannot resume workflow: run journal not found for ${resumeFromRunId}.`;
       return sourceError(message, {
         name: metaName,
@@ -295,19 +300,6 @@ export async function prepareWorkflowToolSource(
         resumeFromRunId,
       });
     }
-    if (journal.project !== project) {
-      const message = `Cannot resume workflow: ${resumeFromRunId} belongs to a different project. No children were launched.`;
-      return sourceError(message, {
-        name: metaName,
-        error: message,
-        logs: source.warnings,
-        source: source.source,
-        sourcePath: source.sourcePath,
-        scriptPath,
-        runId: identity.runId,
-        resumeFromRunId,
-      });
-    }
     resumeAgentResults = journal.agentResults;
   }
 

package/src/workflow/tool.ts

@@ -18,7 +18,8 @@ import { CHILD_EXCLUDED_TOOLS, spawnSubagent } from "../core/spawn.ts";
 import { createRunRecord } from "../core/run-record.ts";
 import { runRecordsDirectory } from "../core/retention.ts";
 import { captureParentContext } from "../core/parent-context.ts";
-import { RunRegistry } from "../core/run-registry.ts";
+import { RunRegistry, type RegisteredRunHandle } from "../core/run-registry.ts";
+import { ExpectedFlowError } from "../core/errors.ts";
 import { OUTPUT_PREVIEW_CHARS } from "../core/progress.ts";
 import { loadExternalCatalog, resolveExternalProfile, selectorHarness, unknownExternalProfileMessage } from "../profiles.ts";
 import { resolveExecutionProfile } from '../execution-config.ts';
@@ -585,23 +586,33 @@ export function createWorkflowTool(
       }
       };
 
-      const registered = options.registry.start({
-        runId: identity.runId,
-        kind: "workflow",
-        sessionId,
-        sessionVersion,
-        project,
-        ...(background ? {} : { signal }),
-        run: executeWorkflow,
-        outcome: (result, workflowSignal) => ({
-          status: result.details.status === "completed" ? "done" : result.details.status === "aborted" ? "aborted" : "error",
-          outcome: result.details.outcome ?? (result.details.status === "completed" ? "succeeded" : result.details.status === "aborted" ? "cancelled" : "failed"),
-          ...(result.details.result !== undefined ? { result: result.details.result } : {}),
-          ...(workflowSignal.aborted && workflowSignal.reason !== undefined
-            ? { error: workflowSignal.reason instanceof Error ? workflowSignal.reason.message : String(workflowSignal.reason) }
-            : result.details.error ? { error: result.details.error } : {}),
-        }),
-      });
+      let registered: RegisteredRunHandle<ReturnType<typeof workflowResult>>;
+      try {
+        registered = options.registry.start({
+          runId: identity.runId,
+          kind: "workflow",
+          sessionId,
+          sessionVersion,
+          project,
+          ...(background ? {} : { signal }),
+          run: executeWorkflow,
+          outcome: (result, workflowSignal) => ({
+            status: result.details.status === "completed" ? "done" : result.details.status === "aborted" ? "aborted" : "error",
+            outcome: result.details.outcome ?? (result.details.status === "completed" ? "succeeded" : result.details.status === "aborted" ? "cancelled" : "failed"),
+            ...(result.details.result !== undefined ? { result: result.details.result } : {}),
+            ...(workflowSignal.aborted && workflowSignal.reason !== undefined
+              ? { error: workflowSignal.reason instanceof Error ? workflowSignal.reason.message : String(workflowSignal.reason) }
+              : result.details.error ? { error: result.details.error } : {}),
+          }),
+        });
+      } catch (error) {
+        // The run_start journal line is already written; settle it so the
+        // never-started run does not read as interrupted forever.
+        const message = error instanceof Error ? error.message : String(error);
+        await journalWriter?.fail(message).catch(() => undefined);
+        if (!(error instanceof ExpectedFlowError)) throw error;
+        return workflowError(`Workflow "${metaName}" was not started: ${message}`, { name: metaName, error: message, status: "error", outcome: "failed", runId: identity.runId, journalPath: journalWriter?.path });
+      }
       emit();
       if (!background) return await registered.result;
       return workflowResult(