@relayflows/sdk 2.0.42 → 2.0.43

package/src/authored-human.ts

@@ -145,3 +145,8 @@ export function resumeCommand(runId: string, dataDir?: string, localAgent = fals
   const dir = dataDir === undefined ? '' : ` --data-dir ${shellWord(dataDir)}`;
   return `flows resume${dir}${localAgent ? ' --local-agent' : ''} ${runId}`;
 }
+
+/** Cloud discovers the open wait, then records the answer and resumes. */
+export function cloudAnswerCommand(runId: string): string {
+  return `flows answer --cloud ${shellWord(runId)} yes|no`;
+}

package/src/authored-memory.ts

@@ -1,9 +1,10 @@
-import type { MemoryHelper } from '@relayflows/surface';
-import { createHash } from 'node:crypto';
-import { access, stat } from 'node:fs/promises';
+import type { HistoryEntry, MemoryFinding, MemoryHelper, MemoryRecallOptions, TrajectoryEntry } from '@relayflows/surface';
+import { createHash, randomUUID } from 'node:crypto';
+import { access, chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
 import { preflightMemory } from './preflight.js';
 
 /** Stable across runs; disjoint from other flow files and other named flows. */
@@ -27,29 +28,458 @@ export async function assertMemoryReachable(): Promise<void> {
   if (refusal) throw new AuthoredFlowExecutionError('memory_unreachable', refusal.message);
 }
 
+/**
+ * The promise `learn` returns. Its constructor is not `Promise`, so `await`,
+ * `Promise.all` and friends reach it through `then`, which records that the
+ * body consumed the result.
+ */
+class LearnCall extends Promise<void> {
+  static override get [Symbol.species](): PromiseConstructor { return Promise; }
+  observed = false;
+  settled = false;
+  override then<A = void, B = never>(
+    onFulfilled?: ((value: void) => A | PromiseLike<A>) | null,
+    onRejected?: ((reason: unknown) => B | PromiseLike<B>) | null,
+  ): Promise<A | B> {
+    this.observed = true;
+    return super.then(onFulfilled, onRejected);
+  }
+}
+
+/** Lets the executor find `learn` calls whose outcome the body never consumed. */
+export class MemoryWriteTracker {
+  private readonly calls: LearnCall[] = [];
+  track(write: Promise<void>): Promise<void> {
+    const call = new LearnCall((resolve, reject) => { void write.then(resolve, reject); });
+    // Bypass the override: marking the rejection handled must not count as the body consuming it.
+    void Promise.prototype.then.call(call, () => { call.settled = true; }, () => { call.settled = true; });
+    this.calls.push(call);
+    return call;
+  }
+  /** Wait for every call to settle, so no write outlives the execution that started it. */
+  async settle(): Promise<void> {
+    await Promise.allSettled(this.calls.map(call => Promise.prototype.then.call(call, () => {}, () => {})));
+  }
+  /** Every call the body did not await, after letting each one settle. */
+  async unawaited(): Promise<number> {
+    const unobserved = this.calls.filter(call => !call.observed || !call.settled);
+    await Promise.allSettled(unobserved.map(call => Promise.prototype.then.call(call, () => {}, () => {})));
+    return unobserved.length;
+  }
+}
+
+/** Root-run stream holding every finding `learn` committed: the source of truth the trajectory files are projected from. */
+export const MEMORY_LEARN_STREAM = 'memory-learn';
+
+export interface LearnRecord {
+  readonly memory: 'learn';
+  readonly id: string;
+  readonly scope: string;
+  readonly decision: Required<MemoryFinding>;
+  readonly learnedAt: string;
+}
+
+export interface CommittedLearn {
+  readonly record: LearnRecord;
+  readonly runId: string;
+}
+
+/** Where `learn` journals a finding before it may become recallable. */
+export interface LearnLedger {
+  /** The durable root run this ledger journals on. */
+  readonly runId: string;
+  /** The commit already recorded for `id`, if any. */
+  recorded(id: string): Promise<CommittedLearn | undefined>;
+  /**
+   * Journal `record`, then return the commit that wins for its id: the first
+   * one in the stream. Usually that is `record`; if another attempt on this
+   * root committed the same finding first, it is theirs, so every attempt
+   * projects the same bytes.
+   */
+  append(record: LearnRecord): Promise<CommittedLearn>;
+}
+
+function canonicalLearnRecord(raw: unknown): LearnRecord | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const value = raw as Record<string, unknown>;
+  const decision = value.decision as Record<string, unknown> | undefined;
+  if (value.memory !== 'learn' || typeof value.id !== 'string' || typeof value.scope !== 'string'
+    || typeof value.learnedAt !== 'string' || typeof decision !== 'object' || decision === null) return undefined;
+  const { question, chosen, reasoning, alternatives } = decision;
+  if (typeof question !== 'string' || typeof chosen !== 'string' || typeof reasoning !== 'string'
+    || !Array.isArray(alternatives) || alternatives.some(item => typeof item !== 'string')) return undefined;
+  // Fixed field order, never the record as it came back: the journal stores
+  // stream messages with sorted keys, and the projected file must be
+  // byte-identical whether it is written now or republished on resume.
+  return {
+    memory: 'learn', id: value.id, scope: value.scope,
+    decision: { question, chosen, reasoning, alternatives: [...alternatives] as string[] },
+    learnedAt: value.learnedAt,
+  };
+}
+
+/**
+ * A ledger on the durable root run's `memory-learn` stream. The stream is read
+ * once per execution and re-read after each append, so a resumed or re-driven
+ * body finds what any earlier attempt committed. A failed read is not cached:
+ * the next call reads again. Journal errors propagate unchanged, so a read
+ * interruption or a lost lease keeps its resumable meaning for the root.
+ */
+export function journalLearnLedger(journal: Pick<JournalClient, 'streamAppend' | 'streamRead'>, rootRunId: string): LearnLedger {
+  let loaded: Promise<Map<string, CommittedLearn>> | undefined;
+  async function read(): Promise<Map<string, CommittedLearn>> {
+    const commits = new Map<string, CommittedLearn>();
+    let offset = 0;
+    for (;;) {
+      const page = await journal.streamRead(rootRunId, MEMORY_LEARN_STREAM, offset, 1000);
+      for (const message of page.messages) {
+        const record = canonicalLearnRecord((message as { message?: unknown }).message ?? message);
+        // The first commit for an id wins; it is the one its file is built from.
+        if (record !== undefined && !commits.has(record.id)) commits.set(record.id, { record, runId: rootRunId });
+      }
+      if (page.messages.length === 0 || page.next_offset <= offset) break;
+      offset = page.next_offset;
+    }
+    return commits;
+  }
+  function load(): Promise<Map<string, CommittedLearn>> {
+    loaded ??= read().catch(error => { loaded = undefined; throw error; });
+    return loaded;
+  }
+  return {
+    runId: rootRunId,
+    async recorded(id) {
+      return (await load()).get(id);
+    },
+    async append(record) {
+      await journal.streamAppend(rootRunId, MEMORY_LEARN_STREAM, record);
+      loaded = undefined;
+      return (await load()).get(record.id) ?? { record, runId: rootRunId };
+    },
+  };
+}
+
 export function authoredMemory(
   scope: string,
   assertOpen: () => void,
   enabled: boolean,
+  tracker?: MemoryWriteTracker,
+  ledger?: LearnLedger,
 ): MemoryHelper {
-  async function read<T>(action: (reader: import('ai-hist').AiHist) => T): Promise<T> {
-    assertOpen();
+  function assertEnabled(): void {
     if (!enabled) throw new AuthoredFlowExecutionError('unsupported_header', 'f.memory requires script memory; memory.script is false');
+  }
+  async function read<T>(action: (reader: import('ai-hist').AiHist, learned: LearnedTrajectory[]) => T): Promise<T> {
+    assertOpen();
+    assertEnabled();
     await assertMemoryReachable();
     assertOpen();
-    const { openAiHist } = await import('ai-hist');
+    const { defaultDbPath, openAiHist } = await import('ai-hist');
+    const learned = await readLearned(defaultDbPath(), scope);
     const reader = await openAiHist({ projectScope: scope, fallback: 'error' });
-    try { return action(reader); } finally { reader.close(); }
+    try { return action(reader, learned); } finally { reader.close(); }
+  }
+  /**
+   * Journal first, then publish. The trajectory file is staged under a name
+   * no read lists, the finding is committed to the root run's `memory-learn`
+   * stream, and only then is the file renamed into place. Nothing is
+   * recallable that the journal does not record, and the failures a disk
+   * write can have (space, permissions) happen while staging, before anything
+   * is journaled. If the process dies between the commit and the rename, the
+   * resumed body re-runs `learn`, finds the commit, and publishes the same
+   * file from it without journaling again. With no durable root run there is
+   * nowhere to journal, so `learn` refuses rather than write unrecorded memory.
+   */
+  const learning = new Map<string, Promise<void>>();
+  async function learnOnce(decision: Required<MemoryFinding>, journaled: LearnLedger): Promise<void> {
+    const { dbPath, mode } = await learnTarget();
+    const id = learnedId(scope, decision);
+    const existing = await journaled.recorded(id);
+    if (existing !== undefined) {
+      await publishLearned(dbPath, existing, mode);
+      return;
+    }
+    const record: LearnRecord = { memory: 'learn', id, scope, decision, learnedAt: new Date().toISOString() };
+    let staged: StagedLearned;
+    try {
+      staged = await stageLearned(dbPath, { record, runId: journaled.runId }, mode);
+    } catch (error) {
+      throw new AuthoredFlowExecutionError('memory_unwritable', `f.memory.learn could not stage the finding: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      // The last point a body that already called done() can be refused: past
+      // here the finding is journaled and will be published.
+      assertOpen();
+      const winner = await journaled.append(record);
+      try {
+        await staged.publish(winner);
+      } catch (error) {
+        throw new AuthoredFlowExecutionError('memory_unwritable', `f.memory.learn journaled the finding (root run ${winner.runId}, stream ${MEMORY_LEARN_STREAM}, id ${id}) but could not publish it: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    } finally {
+      await staged.discard();
+    }
+  }
+  async function learn(finding: MemoryFinding): Promise<void> {
+    assertOpen();
+    assertEnabled();
+    const decision = normalizeFinding(finding);
+    if (ledger === undefined) {
+      throw new AuthoredFlowExecutionError('memory_unjournaled', 'f.memory.learn requires a durable root run to journal the finding; run the flow through flows run');
+    }
+    const id = learnedId(scope, decision);
+    // Concurrent learns of one finding in this execution share one commit.
+    let pending = learning.get(id);
+    if (pending === undefined) {
+      pending = learnOnce(decision, ledger);
+      learning.set(id, pending);
+      void pending.then(() => learning.delete(id), () => learning.delete(id));
+    }
+    await pending;
   }
   return {
-    recall: (query, options) => read(reader => reader.search(query, { ...options, project: scope })),
-    why: task => read(reader => {
-      const entry = reader.whyForTask(task);
-      return entry?.projectId === scope ? [entry] : [];
+    recall: (query, options) => read((reader, learned) => recallMerged(reader, learned, scope, query, options)),
+    why: task => read((reader, learned) => {
+      const synced = reader.whyForTask(task);
+      const candidates = [
+        ...(synced?.projectId === scope ? [synced] : []),
+        ...learned.map(entry => entry.trajectory).filter(entry => trajectoryMatches(entry, task)),
+      ];
+      const newest = candidates.sort((a, b) => b.timestampMs - a.timestampMs)[0];
+      return newest === undefined ? [] : [newest];
     }),
-    async learn() {
-      assertOpen();
-      throw new AuthoredFlowExecutionError('unsupported_verb', 'f.memory.learn requires the follow-up journal-backed trajectory writer');
+    learn(finding) {
+      const write = learn(finding);
+      return tracker === undefined ? write : tracker.track(write);
+    },
+  };
+}
+
+function normalizeFinding(finding: MemoryFinding): Required<MemoryFinding> {
+  const text = (value: unknown, field: string): string => {
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new AuthoredFlowExecutionError('memory_finding_invalid', `f.memory.learn requires a non-empty string ${field}`);
+    }
+    return value;
+  };
+  const alternatives = finding?.alternatives ?? [];
+  if (!Array.isArray(alternatives) || alternatives.some(item => typeof item !== 'string')) {
+    throw new AuthoredFlowExecutionError('memory_finding_invalid', 'f.memory.learn alternatives must be an array of strings');
+  }
+  return {
+    question: text(finding?.question, 'question'),
+    chosen: text(finding?.chosen, 'chosen'),
+    reasoning: text(finding?.reasoning, 'reasoning'),
+    alternatives: [...alternatives],
+  };
+}
+
+/**
+ * Learned findings live beside the ai-hist database, not beside the flow
+ * source: a flow deployed from a read-only checkout, package or image can
+ * still learn. The directory is keyed by the scope's hash, and each file
+ * still names the scope as its `projectId`. Reads here do not need
+ * `ai-hist sync`. For sync to index them too, add `<db-dir>/flows-memory` to
+ * `TRAJECTORY_ROOT` together with the roots it already scans: setting it
+ * replaces ai-hist's default `~/Projects` scan rather than adding to it.
+ */
+const learnedDir = (dbPath: string, scope: string): string =>
+  join(dirname(dbPath), 'flows-memory', basename(scope), '.trajectories', 'compacted');
+const LEARNED_PREFIX = 'flows-memory-';
+
+const learnedId = (scope: string, decision: Required<MemoryFinding>): string =>
+  `${LEARNED_PREFIX}${createHash('sha256').update(JSON.stringify([scope, decision])).digest('hex').slice(0, 32)}`;
+
+/**
+ * `learn` never reads the ai-hist database, so it does not load it: it needs
+ * only the directory it lives in and its mode. A missing database is the same
+ * refusal reads give.
+ */
+async function learnTarget(): Promise<{ dbPath: string; mode: number }> {
+  const { defaultDbPath } = await import('ai-hist');
+  const dbPath = defaultDbPath();
+  const info = await stat(dbPath).catch(() => undefined);
+  if (info === undefined || !info.isFile()) {
+    throw new AuthoredFlowExecutionError('memory_unreachable', `memory database ${dbPath} is missing or not a file`);
+  }
+  return { dbPath, mode: info.mode & 0o777 };
+}
+
+function learnedContent({ record, runId }: CommittedLearn): string {
+  return `${JSON.stringify({
+    id: record.id,
+    version: 1,
+    type: 'compacted',
+    projectId: record.scope,
+    task: { title: record.decision.question, description: null },
+    status: 'completed',
+    startedAt: record.learnedAt,
+    completedAt: record.learnedAt,
+    decisions: [record.decision],
+    retrospective: { summary: null, approach: null, learnings: [], confidence: null },
+    journal: { runId, stream: MEMORY_LEARN_STREAM, id: record.id },
+  }, null, 2)}\n`;
+}
+
+interface StagedLearned {
+  /** Rename into place, rewriting first if the winning commit is not the one staged. */
+  publish(winner: CommittedLearn): Promise<void>;
+  discard(): Promise<void>;
+}
+
+/**
+ * Write a committed finding's compacted trajectory file under a temporary
+ * name. Its content is derived only from the commit (including when it was
+ * learned and which root run journaled it), so every publication of one
+ * commit writes the same bytes. The final name is a hash of scope and
+ * finding, so re-learning a finding atomically replaces one file. The file
+ * takes the database's mode, so a private history does not leak findings
+ * through a world-readable file. The ai-hist database is never modified.
+ */
+async function stageLearned(dbPath: string, staging: CommittedLearn, mode: number): Promise<StagedLearned> {
+  const file = join(learnedDir(dbPath, staging.record.scope), `${staging.record.id}.json`);
+  await mkdir(dirname(file), { recursive: true });
+  const staged = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  let content = learnedContent(staging);
+  const write = async () => {
+    await writeFile(staged, content, { mode });
+    await chmod(staged, mode);
+  };
+  try {
+    await write();
+  } catch (error) {
+    await rm(staged, { force: true });
+    throw error;
+  }
+  return {
+    async publish(winner) {
+      const winning = learnedContent(winner);
+      if (winning !== content) {
+        content = winning;
+        await write();
+      }
+      await rename(staged, file);
     },
+    discard: () => rm(staged, { force: true }),
   };
 }
+
+async function publishLearned(dbPath: string, committed: CommittedLearn, mode: number): Promise<void> {
+  let staged: StagedLearned;
+  try {
+    staged = await stageLearned(dbPath, committed, mode);
+  } catch (error) {
+    throw new AuthoredFlowExecutionError('memory_unwritable', `f.memory.learn could not publish journaled finding ${committed.record.id}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    await staged.publish(committed);
+  } catch (error) {
+    throw new AuthoredFlowExecutionError('memory_unwritable', `f.memory.learn could not publish journaled finding ${committed.record.id}: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    await staged.discard();
+  }
+}
+
+interface LearnedTrajectory {
+  trajectory: TrajectoryEntry;
+  history: HistoryEntry;
+}
+
+/** This scope's learned findings, read straight from disk so they need no `ai-hist sync`. */
+async function readLearned(dbPath: string, scope: string): Promise<LearnedTrajectory[]> {
+  const dir = learnedDir(dbPath, scope);
+  let names: string[];
+  try { names = await readdir(dir); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const learned = await Promise.all(names
+    .filter(name => name.startsWith(LEARNED_PREFIX) && name.endsWith('.json'))
+    .map(async name => {
+      const path = join(dir, name);
+      try {
+        return learnedEntry(scope, path, await readFile(path, 'utf8'), Math.trunc((await stat(path)).mtimeMs));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+        // Files here are only ever published whole, so an unreadable one is
+        // real damage; recalling around it would silently drop journaled memory.
+        throw new AuthoredFlowExecutionError('memory_unreachable', `learned finding ${path} is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }));
+  return learned.filter((entry): entry is LearnedTrajectory => entry !== undefined);
+}
+
+function learnedEntry(scope: string, path: string, text: string, updatedMs: number): LearnedTrajectory {
+  const raw: unknown = JSON.parse(text);
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error('not a trajectory object');
+  const value = raw as Record<string, unknown>;
+  const decisions = value.decisions;
+  if (typeof value.id !== 'string' || !Array.isArray(decisions)) throw new Error('missing id or decisions');
+  const parsed = decisions.map(decision => {
+    const d = decision as Record<string, unknown> | null;
+    if (typeof d !== 'object' || d === null || typeof d.question !== 'string' || typeof d.chosen !== 'string'
+      || typeof d.reasoning !== 'string' || !Array.isArray(d.alternatives) || d.alternatives.some(a => typeof a !== 'string')) {
+      throw new Error('malformed decision');
+    }
+    return { question: d.question, chosen: d.chosen, reasoning: d.reasoning, alternatives: d.alternatives as string[] };
+  });
+  const task = (typeof value.task === 'object' && value.task !== null ? value.task : {}) as Record<string, unknown>;
+  const title = typeof task.title === 'string' ? task.title : null;
+  const description = typeof task.description === 'string' ? task.description : null;
+  const id = value.id;
+  const completedAt = typeof value.completedAt === 'string' ? value.completedAt : null;
+  const timestampMs = completedAt !== null && Number.isFinite(Date.parse(completedAt)) ? Date.parse(completedAt) : updatedMs;
+  // Same field order ai-hist's buildSearchText uses, so matching agrees with a later sync.
+  const searchText = [id, scope, 'completed', title, description,
+    ...parsed.flatMap(d => [d.question, d.chosen, d.reasoning, ...d.alternatives])]
+    .filter((part): part is string => typeof part === 'string' && part.length > 0).join('\n');
+  return {
+    trajectory: {
+      id, version: 1, personaId: null, projectId: scope,
+      task: { title, description },
+      status: 'completed', startedAt: typeof value.startedAt === 'string' ? value.startedAt : null, completedAt,
+      decisions: parsed, retrospective: { summary: null, approach: null, learnings: [], confidence: null },
+      searchText, path, updatedMs, timestampMs,
+    },
+    // Not yet in the ai-hist database, so it has no row id; a negative id
+    // derived from the trajectory id marks it as read from disk.
+    history: {
+      id: -Number.parseInt(createHash('sha256').update(id).digest('hex').slice(0, 12), 16),
+      source: 'trajectory', sessionId: id, project: scope, prompt: searchText, timestampMs, gitBranch: null,
+    },
+  };
+}
+
+const includesFolded = (haystack: string | null | undefined, needle: string): boolean =>
+  (haystack ?? '').toLowerCase().includes(needle.toLowerCase());
+
+function trajectoryMatches(entry: TrajectoryEntry, query: string): boolean {
+  const needle = query.trim();
+  if (needle === '') return false;
+  return [entry.searchText, entry.task.title, entry.task.description, entry.personaId, entry.projectId]
+    .some(field => includesFolded(field, needle));
+}
+
+/** ai-hist's `search` semantics over the database plus this scope's not-yet-synced findings. */
+function recallMerged(
+  reader: import('ai-hist').AiHist,
+  learned: LearnedTrajectory[],
+  scope: string,
+  query: string,
+  options: MemoryRecallOptions | undefined,
+): HistoryEntry[] {
+  const limit = options?.limit ?? 50;
+  const needle = query.trim();
+  const fromDisk = learned.map(entry => entry.history).filter(entry =>
+    (needle === '' || includesFolded(entry.prompt, needle) || includesFolded(entry.project, needle))
+    && (options?.source === undefined || options.source === 'trajectory')
+    && options?.tag === undefined
+    && (options?.beforeMs === undefined || entry.timestampMs < options.beforeMs));
+  // Fetching `limit + fromDisk.length` rows guarantees a synced copy of any
+  // disk entry that makes the cut is among them, so it dedupes correctly.
+  const synced = reader.search(query, { ...options, project: scope, limit: limit + fromDisk.length });
+  const syncedIds = new Set(synced.filter(entry => entry.source === 'trajectory').map(entry => entry.sessionId));
+  return [...synced, ...fromDisk.filter(entry => !syncedIds.has(entry.sessionId))]
+    .sort((a, b) => b.timestampMs - a.timestampMs)
+    .slice(0, limit);
+}

package/src/authored-node-entry.ts

@@ -1,3 +1,4 @@
+import { FLOW_READ_BUDGET_MS, isReadInterruptionError } from './journal-read-policy.js';
 import { Worker } from 'node:worker_threads';
 import { createHash, createHmac } from 'node:crypto';
 import { readFileSync, writeSync } from 'node:fs';
@@ -74,7 +75,7 @@ try {
   const loaded = await loadPinnedAuthoredSource(request.metadata, true);
   if (request.localAgentStream !== request.metadata.localAgentStream) throw new Error('authored root local agent surface mismatch');
   if (request.workerCapacity !== undefined && !isAgentCapacity(request.workerCapacity)) throw new Error('invalid authored worker capacity');
-  client = new JournalClient(request.socketPath);
+  client = new JournalClient(request.socketPath, { readBudgetMs: FLOW_READ_BUDGET_MS, budgetHandshake: true });
   await client.connect(); await client.hello('flows-authored-node');
   const result = await executeAuthoredFlow(loaded.handle, client,
     request.metadata.inputPresent ? request.metadata.input : undefined, {
@@ -99,6 +100,10 @@ try {
     // `parkCause` travels for the same reason: it is the difference between
     // "attach a worker" and "a human has to recover this", and this process is
     // the only one that saw the child's classification.
+    // Preserve a read interruption across the Node/Bun error frame so the
+    // lease-owning parent can leave the root resumable.
+    ...(isReadInterruptionError(error)
+      ? { code: 'daemon_unresponsive' } : {}),
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
       completionReason: error.completionReason, runId: error.runId,
       details: error.details,

package/src/authored-node-runner.ts

@@ -1,4 +1,5 @@
 import { JournalClient } from './journal-client.js';
+import { FLOW_READ_BUDGET_MS } from './journal-read-policy.js';
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
@@ -171,7 +172,7 @@ export async function runAuthoredInNode(
         else resolve(result);
       });
     });
-    await verifyAuthoredNodeResult(result, metadata, rootRunId, socketPath);
+    await verifyAuthoredNodeResult(result, metadata, rootRunId, socketPath, options.signal);
     return result;
   } finally { await rm(directory, { recursive: true, force: true }); }
 }
@@ -323,7 +324,7 @@ function frameCount(frame: Record<string, unknown>, key: string): number | undef
 /** The IPC frame is a claim, not a durable terminal fact or a sandbox boundary. */
 export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,
-  rootRunId: string, socketPath: string,
+  rootRunId: string, socketPath: string, signal?: AbortSignal,
 ): Promise<void> {
   const invalid = (why = ''): never => { throw new Error(`authored runtime result has no matching durable completion${process.env['FLOWS_VERIFIER_DEBUG'] && why ? ` (${why})` : ''}`); };
   if (result.rootRunId !== rootRunId || result.name !== metadata.flowName
@@ -354,7 +355,9 @@ export async function verifyAuthoredNodeResult(
     if (!authoredIds.has(gate.id.slice(0, -'.gate'.length))) invalid(`orphan ${gate.id}`);
   }
   const runs = new Set<string>();
-  const journal = new JournalClient(socketPath);
+  // The verifier reads the same journal under the same CPU load as the body.
+  const journal = new JournalClient(socketPath, { readBudgetMs: FLOW_READ_BUDGET_MS, budgetHandshake: true,
+    ...(signal === undefined ? {} : { readSignal: signal }) });
   await journal.connect();
   try {
     await journal.hello('flows-authored-result-verifier');

package/src/authored-root-readback.ts

@@ -0,0 +1,100 @@
+import { isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
+import type { AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { isSurfaceCompletionReason } from './authored-step-output.js';
+import { JournalFrameError, JournalProtocolError, type JournalClient } from './journal-client.js';
+import type { RunOutcome } from './protocol.js';
+
+/*
+ * Reading an authored root back from its journal, and what a failed read
+ * means. Only a definite answer from the daemon may change how a run is
+ * treated; an unanswered, canceled or failed read decides nothing.
+ */
+
+const NO_ROOT_STEP = new Error('authored root journal has no root step');
+
+export async function rootKernelStep(journal: JournalClient, runId: string): Promise<Record<string, unknown>> {
+  const entries = (await journal.journalRead(runId, 1)).entries as Array<Record<string, unknown>>;
+  const spawned = entries.find(entry => entry.entry_type === 'run.spawned');
+  const payload = spawned?.payload as { spec?: { steps?: unknown[] } } | undefined;
+  const step = payload?.spec?.steps?.[0];
+  if (typeof step !== 'object' || step === null || Array.isArray(step)) throw NO_ROOT_STEP;
+  return step as Record<string, unknown>;
+}
+
+/** Codes relayflowd uses when it failed to read its own storage (server/protocol.rs). */
+const DAEMON_READ_FAILURES = new Set(['journal_write_failed', 'internal']);
+
+/**
+ * The root step of `runId`, or undefined when the daemon definitively answered
+ * that it has none: a refusal of the read (run_not_found, an unreadable early
+ * epoch, ...) or a journal without a root step. A daemon-side read failure, an
+ * interruption or a cancellation propagates instead, so a delayed, canceled or
+ * failing daemon never makes resume guess the declarative path.
+ */
+export async function rootStepIfPresent(journal: JournalClient, runId: string): Promise<Record<string, unknown> | undefined> {
+  return rootKernelStep(journal, runId).catch(error => {
+    if ((error instanceof JournalProtocolError && !DAEMON_READ_FAILURES.has(error.code)) || error === NO_ROOT_STEP) return undefined;
+    throw error;
+  });
+}
+
+/**
+ * The stored result of a root the daemon already reports completed. If reading
+ * it back is interrupted, the outcome is still known: say so, rather than
+ * recasting a finished run as resumable.
+ */
+export function completedResult(journal: JournalClient, outcome: RunOutcome, rootRunId: string): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  return completedRootResult(journal, rootRunId).catch(error => {
+    // A bad frame or a journal with no stored result is a definite fact; any
+    // other failure — interrupted, canceled, or a daemon-side read error such
+    // as journal_write_failed — left the verdict unread, not the run unfinished.
+    if (error instanceof JournalFrameError || error === NO_DURABLE_RESULT) throw error;
+    // The kernel completes the root step with success whatever the body
+    // declared; the authored verdict lives only in the unread output.
+    const unread = new AuthoredFlowExecutionError('result_unreadable',
+      `run ${rootRunId} completed, but its stored result (the flow's verdict) could not be read: ${error.message}`,
+      undefined, rootRunId);
+    unread.rootRunId = rootRunId;
+    throw unread;
+  });
+}
+
+const NO_DURABLE_RESULT = new Error('completed authored root has no durable result');
+
+async function completedRootResult(
+  journal: JournalClient,
+  rootRunId: string,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  const entries = (await journal.journalRead(rootRunId, 1)).entries as Array<Record<string, unknown>>;
+  const completed = entries.slice().reverse().find(entry => entry.entry_type === 'step.completed'
+    && entry.step_id === 'authored-root'
+    && (entry.payload as { completionReason?: unknown } | undefined)?.completionReason === 'success');
+  const output = (completed?.payload as { output?: unknown } | undefined)?.output;
+  if (!isCompletedRootOutput(output)) throw NO_DURABLE_RESULT;
+  // The stored detail, never a freshly computed one: redaction reads the
+  // CURRENT environment, so recomputing here would let a completed run report
+  // something its journal does not hold.
+  return Object.freeze({
+    name: output.name,
+    completionReason: output.completionReason,
+    ...(output.completionDetail === undefined ? {} : { completionDetail: output.completionDetail }),
+    journalSteps: Object.freeze(output.journalSteps.map(step => Object.freeze({ ...step }))),
+    rootRunId,
+  });
+}
+
+function isCompletedRootOutput(value: unknown): value is Omit<AuthoredFlowExecutionResult, 'rootRunId'> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const output = value as Partial<AuthoredFlowExecutionResult>;
+  return typeof output.name === 'string'
+    && isLoweredCompletion(output.completionReason)
+    // A malformed detail fails the whole readback rather than being dropped:
+    // silently discarding it would report the verdict without the evidence
+    // the journal says it was recorded with.
+    && (output.completionDetail === undefined || isDurableCompletionDetail(output.completionDetail))
+    && Array.isArray(output.journalSteps)
+    && output.journalSteps.every(step => typeof step === 'object' && step !== null
+      && typeof step.id === 'string' && typeof step.runId === 'string'
+      && isSurfaceCompletionReason(step.completionReason));
+}