@relayflows/sdk 2.0.8 → 2.0.10

package/src/cli/deploy.ts

@@ -0,0 +1,52 @@
+import { join } from 'node:path';
+import type { CliIo } from '../cli.js';
+import { BundleFailure, bucketDirectory, copyBundle, exists, parseDigestReference,
+  verifyDigest, writableBucket } from '../bundle-transport.js';
+import { checkRunnableBundle } from './bundle-preflight.js';
+
+export interface DeployArgs { command: 'deploy'; value: string; to: string }
+export function parseDeployArgs(args: readonly string[]): DeployArgs | undefined {
+  let value: string | undefined;
+  let to: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--to') {
+      if (to !== undefined || !args[i + 1] || args[i + 1]!.startsWith('-')) return undefined;
+      to = args[++i];
+    } else if (arg.startsWith('-') || value !== undefined) return undefined;
+    else value = arg;
+  }
+  return value && to && parseDigestReference(value) ? { command: 'deploy', value, to } : undefined;
+}
+export async function runDeploy(args: DeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  let started = false;
+  try {
+    const ref = parseDigestReference(args.value);
+    if (!ref) throw new BundleFailure('bundle_missing_locally', 'Expected <flow>@sha256:<64 lowercase hex characters>.');
+    const source = join(process.cwd(), 'dist', 'flows', args.value);
+    if (!await exists(source)) throw new BundleFailure('bundle_missing_locally', `Build ${args.value} locally first.`);
+    await verifyDigest(source, ref.digest);
+    const checked = await checkRunnableBundle(source, ref.name);
+    if (!checked.report.ok) {
+      for (const diagnostic of checked.report.diagnostics) io.stderr(`${diagnostic.severity.toUpperCase()} [${diagnostic.kind}] ${diagnostic.message}`);
+      return 2;
+    }
+    const target = bucketDirectory(args.to, ref);
+    if (await exists(target)) {
+      await verifyDigest(target, ref.digest);
+      io.stderr(`deploy_noop: ${args.value}`);
+      io.stdout(`SKIPPED (already-present) ${args.value} ${args.to}`);
+      return 0;
+    }
+    await writableBucket(target);
+    started = true;
+    const copied = await copyBundle(source, target, ref.digest);
+    if (!copied) io.stderr(`deploy_noop: ${args.value}`);
+    io.stdout(`${copied ? 'DEPLOYED' : 'SKIPPED (already-present)'} ${args.value} ${args.to}`);
+    return 0;
+  } catch (error) {
+    const kind = started ? 'deploy_partial' : error instanceof BundleFailure ? error.kind : 'bucket_unreachable';
+    io.stderr(`${started ? 'FAILED' : 'REFUSED'} [${kind}] ${error instanceof Error ? error.message : String(error)}`);
+    return started ? 1 : 2;
+  }
+}

package/src/cli/deterministic-failure.ts

@@ -0,0 +1,69 @@
+import type { StepFailedDetails } from '../failure-kinds.js';
+import type { JournalClient } from '../journal-client.js';
+
+const STDERR_TAIL_BYTES = 1_024;
+
+/** Read completion evidence through the existing protocol, including later pages. */
+export async function deterministicFailureDetails(
+  client: JournalClient,
+  runId: string,
+): Promise<StepFailedDetails | undefined> {
+  const snapshot = await client.runGet(runId);
+  if (!Object.values(snapshot.steps).some(step => step.type === 'deterministic')) return undefined;
+  let fromSeq = 1;
+  const failures = new Map<string, StepFailedDetails>();
+  while (true) {
+    const { entries } = await client.journalRead(runId, fromSeq, 100);
+    if (entries.length === 0) break;
+    for (const raw of entries) {
+      const entry = record(raw);
+      const seq = entry?.['seq'];
+      if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
+        throw new Error('invalid journal sequence in command failure inspection');
+      }
+      fromSeq = seq + 1;
+      const stepId = entry?.['step_id'];
+      if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string'
+        || snapshot.steps[stepId]?.type !== 'deterministic') continue;
+      // A later completion supersedes an earlier failed attempt.
+      failures.delete(stepId);
+      const payload = record(entry['payload']);
+      // Post-#292 the kernel preserves the captured `{exit_code, stdout_tail,
+      // stderr_tail}` in `output` on failed completions; prefer it. Fall back
+      // to `trajectory_tail` for journal records emitted before that fix.
+      const output = record(payload?.['output']) ?? record(payload?.['trajectory_tail']);
+      const exitCode = output?.['exit_code'];
+      if (payload?.['disposition'] !== 'step_done' || payload['completionReason'] === 'success'
+        || typeof exitCode !== 'number' || !Number.isSafeInteger(exitCode) || exitCode === 0) continue;
+      failures.set(stepId, {
+        stepId,
+        exitCode,
+        stderrTail: stderrTail(output?.['stderr_tail']),
+        hint: `flows replay ${shellQuote(runId)} --at ${shellQuote(stepId)}`,
+      });
+    }
+  }
+  return [...failures.values()].at(-1);
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function stderrTail(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  const bytes = Buffer.from(value, 'utf8');
+  let start = Math.max(0, bytes.length - STDERR_TAIL_BYTES);
+  // Drop a partial leading code point, avoiding replacement-byte expansion.
+  while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
+  // Preserve tabs/newlines; replace binary controls (including ESC and CR),
+  // C1 controls and Unicode formatting controls without growing the excerpt.
+  return bytes.subarray(start).toString('utf8')
+    .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
+}
+
+function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')
+    ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/cli/direct-run.ts

@@ -1,11 +1,16 @@
+import { McpStepError } from '../authored-mcp.js';
+import { McpPreflightError } from './check-typescript.js';
+import { attachLocalAgent } from '../local-agent.js';
+import { LlmWorker } from '../llm-worker.js';
 import {
   AuthoredFlowExecutionError,
   executeAuthoredFlow,
 } from '../authored-flow-executor.js';
-import { AuthoredFlowLoadError, loadAuthoredFlow } from '../authored-flow-loader.js';
+import { AuthoredFlowLoadError } from '../authored-flow-loader.js';
 import { DirectInputError, parseDirectInput } from '../direct-input.js';
 import { JournalClient } from '../journal-client.js';
 import { inputFailureReport } from './check.js';
+import { checkAuthoredTriggers } from './check-triggers.js';
 import {
   connect,
   emptyReport,
@@ -37,17 +42,44 @@ export async function runDirectFlow(
     };
   }
 
+  // Declared triggers are knowable before any daemon or step is started.
+  // Importing the authored module is unavoidable here — trigger sources
+  // are only observable after `flow(...).on(webhook(...))` has run — but
+  // the authored body is not called, so a side-effect-in-body flow still
+  // has its body deferred until after daemon-attach below.
+  const checked = await checkAuthoredTriggers(path);
+  if (!checked.report.ok || checked.loaded === undefined) {
+    return { exitCode: 2, report: fromCheckReport('run', checked.report) };
+  }
   const socketPath = socketFor(dataDir);
   const base: RunReport = { ...emptyReport('run'), path };
   const client = new JournalClient(socketPath);
   const connected = await connect(client, 'run', dataDir, base, options);
   if (connected !== undefined) return connected;
 
+  let localAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
+  let localLlm: LlmWorker | undefined;
+  let llmClient: JournalClient | undefined;
+  let llmFailure: unknown;
   try {
-    const { handle, getDefinition } = await loadAuthoredFlow(path);
+    const { handle, getDefinition } = checked.loaded;
+    if (options.localAgent) {
+      localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+      // A session owns one worker registration. Keep the workspace-free LLM
+      // worker on its own connection so it cannot replace the agent worker.
+      llmClient = new JournalClient(socketPath);
+      await llmClient.connect();
+      await llmClient.hello('flows-local-llm');
+      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`);
+      localLlm.on('error', error => { llmFailure = error; client.close(); });
+      await localLlm.attach();
+    }
     const result = await executeAuthoredFlow(handle, client, input, {
       getDefinition,
+      dataDir,
       flowPath: path,
+      onProgress: options.onProgress,
+      localAgentStream: localAgent?.stream,
       ...(options.signal !== undefined ? { signal: options.signal } : {}),
       ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
     });
@@ -57,6 +89,19 @@ export async function runDirectFlow(
         `authored flow "${result.name}" completed without a journal step`,
       ));
     }
+    if (result.completionReason === 'needs_human') {
+      return {
+        exitCode: 3,
+        report: {
+          ...base, ok: false, runId: terminal.runId, socketPath, status: 'parked',
+          completedSteps: result.journalSteps.length,
+          diagnostics: [...base.diagnostics, {
+            severity: 'parked', kind: 'run_parked',
+            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
+          }],
+        },
+      };
+    }
     return {
       exitCode: 0,
       report: {
@@ -69,7 +114,21 @@ export async function runDirectFlow(
         completedSteps: result.journalSteps.length,
       },
     };
-  } catch (error) {
+  } catch (caught) {
+    if (caught instanceof McpPreflightError) return {
+      exitCode: 2, report: fromCheckReport('run', caught.report),
+    };
+    if (caught instanceof McpStepError) return {
+      exitCode: 1,
+      report: { ...base, ok: false, runId: caught.runId, socketPath,
+        status: 'failed', completionReason: 'step_failed',
+        diagnostics: [...base.diagnostics, { severity: 'failure', kind: 'step_failed', message: caught.message }],
+      },
+    };
+    // Preserve authored classifications/run IDs; use the worker's cause only
+    // when its connection teardown left a generic transport error.
+    const error = caught instanceof AuthoredFlowExecutionError || caught instanceof AuthoredFlowLoadError
+      ? caught : llmFailure ?? localAgent?.failure ?? caught;
     // `agent_cli_unresolved` and `unsupported_workspace_permission` are
     // preflight-shaped refusals, not protocol failures — `flows check`
     // returns exit 2 for the equivalent declarative-spec failures, and this
@@ -82,21 +141,31 @@ export async function runDirectFlow(
     // the same limitation already documented elsewhere).
     if (error instanceof AuthoredFlowLoadError
       || (error instanceof AuthoredFlowExecutionError
-        && (error.code === 'unsupported_header'
+        && (error.code === 'helper_slack.credential_missing'
+          || error.code === 'helper_slack.mount_required'
+          || error.code === 'budget_syntax_invalid'
+          || error.code === 'budget_missing_price'
+          || error.code === 'unsupported_header'
           || error.code === 'agent_cli_unresolved'
+          || error.code === 'llm_cli_unresolved'
           || error.code === 'unsupported_workspace_permission'))) {
       return {
         exitCode: 2,
         report: {
           ...fromCheckReport('run', inputFailureReport({
-            kind: 'invalid_spec',
+            kind: error instanceof AuthoredFlowExecutionError && (
+              error.code === 'helper_slack.credential_missing'
+              || error.code === 'helper_slack.mount_required'
+              || error.code === 'budget_syntax_invalid'
+              || error.code === 'budget_missing_price'
+            ) ? error.code : 'invalid_spec',
             message: error.message,
           }, path)),
           socketPath,
         },
       };
     }
-    if (error instanceof AuthoredFlowExecutionError && error.code === 'agent_parked') {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'agent_parked' || error.code === 'llm_parked')) {
       return {
         exitCode: 3,
         report: {
@@ -116,6 +185,9 @@ export async function runDirectFlow(
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
     return protocolFailure('run', base, socketPath, error, runId);
   } finally {
-    client.close();
+    try {
+      await localLlm?.close();
+      await localAgent?.close();
+    } finally { llmClient?.close(); client.close(); }
   }
 }

package/src/cli/hn-monitor.ts

@@ -16,6 +16,7 @@ import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { pollHackerNewsOnce, HnTransientFetchError, type Fetcher } from '../hn-poller.js';
 import { AgentWorker } from '../worker.js';
+import { socketPathFor } from '../daemon-connection.js';
 import { JournalClient } from '../journal-client.js';
 import type { EventSubmitResult, HelloResult, Pins } from '../protocol.js';
 import type { CliIo } from '../cli.js';
@@ -181,7 +182,7 @@ async function defaultAttachWorker(
  */
 export async function runHnMonitor(args: HnMonitorArgs, io: CliIo): Promise<0 | 1> {
   const pollIntervalMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-  const socketPath = `${args.dataDir}/relayflowd.sock`;
+  const socketPath = socketPathFor(args.dataDir);
 
   let spec: unknown;
   try {

package/src/cli/replay.ts

@@ -0,0 +1,81 @@
+import type { CliIo } from '../cli.js';
+import { canonicalize } from '../canonical.js';
+import { JournalReadError, walkJournal } from '../journal-client.js';
+
+export interface ReplayArgs {
+  command: 'replay';
+  value: string;
+  json: boolean;
+  dataDir: string;
+  at?: string;
+  allowHumanInfluenced?: boolean;
+}
+
+export function parseReplayArgs(args: readonly string[]): ReplayArgs | undefined {
+  let json = false;
+  let allowHumanInfluenced = false;
+  let dataDir: string | undefined;
+  let at: string | undefined;
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]!;
+    if (argument === '--allow-human-influenced') {
+      if (allowHumanInfluenced) return undefined;
+      allowHumanInfluenced = true;
+    } else if (argument === '--json') {
+      if (json) return undefined;
+      json = true;
+    } else if (argument === '--data-dir' || argument === '--at') {
+      const value = args[++index];
+      if (value === undefined || value.length === 0 || value.startsWith('-')) return undefined;
+      if (argument === '--data-dir') {
+        if (dataDir !== undefined) return undefined;
+        dataDir = value;
+      } else {
+        if (at !== undefined) return undefined;
+        at = value;
+      }
+    } else if (argument.startsWith('-')) {
+      return undefined;
+    } else {
+      positionals.push(argument);
+    }
+  }
+  if (positionals.length !== 1) return undefined;
+  return { allowHumanInfluenced, command: 'replay', value: positionals[0]!, json, dataDir: dataDir ?? '.relayflowd', at };
+}
+
+export async function replayJournal(args: ReplayArgs, io: CliIo): Promise<0 | 1 | 2> {
+  let emitted = false;
+  try {
+    for await (const event of walkJournal(args.value, args.dataDir, { at: args.at })) {
+      const payload = event.payload !== null && typeof event.payload === 'object' && !Array.isArray(event.payload)
+        ? event.payload as Record<string, unknown> : {};
+      if (event.entry_type === 'step.completed' && payload['human_intervention'] === true && !args.allowHumanInfluenced) {
+        io.stderr(`REFUSED [human_influenced_run] step ${JSON.stringify(event.step_id)}; pass --allow-human-influenced to continue`);
+        return 2;
+      }
+      io.stdout(args.json ? canonicalize({
+        step_id: event.step_id,
+        kind: event.entry_type,
+        event,
+        verification: payload['verification'] ?? null,
+        spend: payload['budget'] ?? payload['budget_total'] ?? null,
+      })
+        : `${event.seq} ${event.at_ms} ${event.entry_type}`
+          + (event.step_id === null ? '' : ` step=${JSON.stringify(event.step_id)}`)
+          + (event.attempt === null ? '' : ` attempt=${event.attempt}`)
+          + ` ${canonicalize(event.payload)}`);
+      emitted = true;
+    }
+    return 0;
+  } catch (error) {
+    const diagnostic = {
+      severity: 'refusal',
+      kind: error instanceof JournalReadError ? error.code : 'journal_read_failed',
+      message: error instanceof Error ? error.message : String(error),
+    };
+    io.stderr(`${emitted ? 'FAILED' : 'REFUSED'} [${diagnostic.kind}] ${diagnostic.message}`);
+    return emitted ? 1 : 2;
+  }
+}

package/src/cli/reuse.ts

@@ -0,0 +1,23 @@
+import type { JournalClient } from '../journal-client.js';
+
+/** Count durable facts, including failed executions, across paginated reads. */
+export async function reuseSummary(client: JournalClient, runId: string, fromRunId: string): Promise<{
+  fromRunId: string; reusedSteps: number; executedSteps: number;
+}> {
+  const reused = new Set<string>();
+  const executed = new Set<string>();
+  let fromSeq = 1;
+  while (true) {
+    const { entries } = await client.journalRead(runId, fromSeq, 1000);
+    if (entries.length === 0) break;
+    for (const raw of entries) {
+      const entry = raw as { seq: number; entry_type: string; step_id?: string; payload: { reused_from?: unknown } };
+      if (!Number.isSafeInteger(entry.seq) || entry.seq < fromSeq) throw new Error('invalid journal sequence in reuse summary');
+      fromSeq = entry.seq + 1;
+      if (entry.step_id === undefined) continue;
+      if (entry.entry_type === 'step.attempt.started') executed.add(entry.step_id);
+      if (entry.entry_type === 'step.completed' && entry.payload.reused_from !== undefined) reused.add(entry.step_id);
+    }
+  }
+  return { fromRunId, reusedSteps: reused.size, executedSteps: executed.size };
+}

package/src/cli/run-digest.ts

@@ -0,0 +1,24 @@
+import { BundleFailure, fetchBundle, parseDigestReference } from '../bundle-transport.js';
+import { CheckFailure, inputFailureReport, readProjectConfig, type CheckExecution } from './check.js';
+import { checkRunnableBundle } from './bundle-preflight.js';
+import type { RunExecution } from './run.js';
+
+export async function prepareDigestRun(reference: string, bucket?: string): Promise<CheckExecution | RunExecution> {
+  try {
+    const ref = parseDigestReference(reference)!;
+    const selected = bucket ?? readProjectConfig(process.cwd()).deploy?.bucket;
+    if (!selected) throw new BundleFailure('bucket_unconfigured', 'Set --bucket <uri> or deploy.bucket in flows.json.');
+    const directory = await fetchBundle(ref, selected);
+    const checked = await checkRunnableBundle(directory, ref.name);
+    checked.report.path = reference;
+    return checked;
+  } catch (error) {
+    if (error instanceof CheckFailure) return { report: inputFailureReport(error, reference) };
+    const kind = error instanceof BundleFailure && (
+      error.kind === 'bucket_unconfigured' || error.kind === 'bucket_unreachable'
+      || error.kind === 'bundle_signature_invalid' || error.kind === 'bundle_unsupported'
+    ) ? error.kind : 'bundle_unsupported';
+    return { exitCode: 2, report: { ok: false, command: 'run', path: reference, resolutions: [],
+      diagnostics: [{ severity: 'refusal', kind, message: error instanceof Error ? error.message : String(error) }] } };
+  }
+}

package/src/cli/run.ts

@@ -1,10 +1,19 @@
+import { parseDigestReference } from '../bundle-transport.js';
+import { prepareDigestRun } from './run-digest.js';
+import { reuseSummary } from './reuse.js';
+import { resumeHelperEffect } from '../authored-helper-effect.js';
+import { AuthoredFlowExecutionError } from '../authored-flow-error.js';
 import { join, resolve } from 'node:path';
+import type { ProgressEvent } from '../progress.js';
 import { toKernelSpec } from '../compile.js';
+import { socketPathFor } from '../daemon-connection.js';
 import { ensureDaemon, type EnsureDaemonOptions } from '../daemon-lifecycle.js';
+import { isAuthoredFlowPath } from '../direct-input.js';
 import { daemonRefusal } from './daemon-refusal.js';
-import type { RunFailureKind, RunWarningKind } from '../failure-kinds.js';
+import type { RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
+import { deterministicFailureDetails } from './deterministic-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
-import type { PreflightDiagnostic } from '../preflight.js';
+import { attachLocalAgent } from '../local-agent.js';
 import type {
   RunCompletionReason,
   RunOutcome,
@@ -13,7 +22,6 @@ import type {
 import type { StepType } from '../spec.js';
 import {
   checkFlow,
-  type CheckInputDiagnostic,
   type CheckReport,
 } from './check.js';
 
@@ -25,7 +33,7 @@ export interface ParkedStep {
   type: Extract<StepType, 'llm' | 'agent'>;
 }
 
-export interface RunDiagnostic {
+export interface RunDiagnostic extends StepFailedDetails {
   severity: 'refusal' | 'failure' | 'parked' | 'warning';
   kind: RunFailureKind | RunWarningKind | RunCompletionReason;
   message: string;
@@ -40,10 +48,11 @@ export interface RunReport {
   status?: RunStatus;
   completionReason?: RunCompletionReason;
   completedSteps?: number;
+  reuse?: { fromRunId: string; reusedSteps: number; executedSteps: number };
   parkedStep?: ParkedStep;
   projectConfigPath?: string;
   resolutions: CheckReport['resolutions'];
-  diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic | RunDiagnostic>;
+  diagnostics: Array<CheckReport['diagnostics'][number] | RunDiagnostic>;
 }
 
 export interface RunExecution {
@@ -59,6 +68,12 @@ export interface RunProgress {
 }
 
 export interface RunLifecycleOptions {
+  bucket?: string;
+  allowHumanInfluenced?: boolean;
+  onPtyReady?: (path: string) => void;
+  reuseFromRunId?: string;
+  onProgress?: (event: ProgressEvent) => void;
+  localAgent?: boolean;
   signal?: AbortSignal;
   onWait?: (progress: RunProgress) => void;
   /**
@@ -74,7 +89,9 @@ export async function runFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
-  const checked = checkFlow(path);
+  const prepared = parseDigestReference(path) ? await prepareDigestRun(path, options.bucket) : undefined;
+  if (prepared && 'exitCode' in prepared) return prepared;
+  const checked = prepared ?? checkFlow(path);
   if (!checked.report.ok || checked.flow === undefined) {
     return { exitCode: 2, report: fromCheckReport('run', checked.report) };
   }
@@ -95,14 +112,31 @@ async function executeCheckedFlow(
   const connected = await connect(client, 'run', dataDir, base, options);
   if (connected !== undefined) return connected;
 
+  let localAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
   try {
     const spec = toKernelSpec(checked.flow!);
-    const outcome = await client.runStart(spec);
-    return await classifyOutcome(client, 'run', outcome, base, socketPath, options);
+    // Use the checked CLI/model and declared surfaces unchanged. The worker
+    // advertises its existing pins; the daemon still owns surface matching.
+    if (options.localAgent) localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+    const outcome = await client.runStart(spec, options.reuseFromRunId);
+    const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, options);
+    if (options.reuseFromRunId !== undefined) {
+      execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);
+    }
+    return execution;
   } catch (error) {
-    return protocolFailure('run', base, socketPath, error);
+    if (error instanceof JournalProtocolError && (
+      error.code === 'reuse_spec_mismatch' || error.code === 'reuse_run_not_found'
+      || error.code === 'reuse_journal_read_failed'
+    )) {
+      const failed = error.code === 'reuse_journal_read_failed';
+      return { exitCode: failed ? 1 : 2, report: { ...base, socketPath,
+        diagnostics: [...base.diagnostics, { severity: failed ? 'failure' : 'refusal',
+          kind: error.code, message: error.message }] } };
+    }
+    return protocolFailure('run', base, socketPath, localAgent?.failure ?? error);
   } finally {
-    client.close();
+    try { await localAgent?.close(); } finally { client.close(); }
   }
 }
 
@@ -118,9 +152,26 @@ export async function resumeFlow(
   if (connected !== undefined) return connected;
 
   try {
-    const outcome = await client.runResume(runId);
+    // resumeHelperEffect subsumes the old resumeSlackEffect: it handles the
+    // slack effect resume plus every other provider from N's codegen. The
+    // second call the earlier rebase left is a stale reference from before
+    // the helper fanout renamed the API.
+    let outcome = await client.runResume(runId, options.allowHumanInfluenced);
+    if (await resumeHelperEffect(client, runId, dataDir)) {
+      outcome = await client.runResume(runId, options.allowHumanInfluenced);
+    }
     return await classifyOutcome(client, 'resume', outcome, base, socketPath, options);
   } catch (error) {
+    if (error instanceof JournalProtocolError && error.code === 'human_influenced_run') {
+      return { exitCode: 2, report: { ...base, runId, socketPath,
+        diagnostics: [{ severity: 'refusal', kind: 'human_influenced_run', message: error.message.replace(/^human_influenced_run: /, '') }] } };
+    }
+    if (error instanceof AuthoredFlowExecutionError
+      && (error.code === 'helper_slack.credential_missing' || error.code === 'helper_slack.mount_required'
+        || error.code === 'helper_provider.mount_required' || error.code === 'helper_provider.unsupported')) {
+      return { exitCode: 2, report: { ...base, runId, socketPath,
+        diagnostics: [{ severity: 'refusal', kind: error.code, message: error.message }] } };
+    }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
       return protocolFailure('resume', base, socketPath, error, runId);
     }
@@ -243,11 +294,11 @@ export async function classifyOutcome(
     }
     if (inspection?.runningStep !== undefined) {
       await waitForRunningStep(client, current.run_id, inspection.runningStep, options);
-      current = await client.runResume(current.run_id);
+      current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
     }
     if (inspection?.status === 'completed' || inspection?.status === 'failed') {
-      current = await client.runResume(current.run_id);
+      current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
     }
     // The run is still RUNNING but no step is identifiable at this instant.
@@ -275,7 +326,7 @@ export async function classifyOutcome(
       // is already progressing -- it returns the current state rather than
       // re-dispatching. This loop leans on that up to MAX_UNCLASSIFIED_POLLS
       // times while the daemon is mid-transition.
-      current = await client.runResume(current.run_id);
+      current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
     }
     // Fail closed rather than loop forever: if it never resolves, the original
@@ -295,15 +346,30 @@ export async function classifyOutcome(
 
   if (report.ok) return { exitCode: 0, report };
   if (current.status === 'failed' && current.completion_reason !== null) {
+    const diagnostic: RunDiagnostic = {
+      severity: 'failure',
+      kind: current.completion_reason,
+      message: `Run "${current.run_id}" failed with completionReason: ${current.completion_reason}.`,
+    };
+    if (current.completion_reason === 'step_failed') {
+      try {
+        const details = await deterministicFailureDetails(client, current.run_id);
+        if (details !== undefined) {
+          Object.assign(diagnostic, details);
+          diagnostic.message += ` Step ${JSON.stringify(details.stepId)} exit=${details.exitCode}.`
+            + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '')
+            + `\nInspect: ${details.hint}`;
+        }
+      } catch (error) {
+        // Inspection must not erase the already known run failure.
+        diagnostic.message += ` Could not inspect command failure: ${errorMessage(error)}`;
+      }
+    }
     return {
       exitCode: 1,
       report: {
         ...report,
-        diagnostics: [...report.diagnostics, {
-          severity: 'failure',
-          kind: current.completion_reason,
-          message: `Run "${current.run_id}" failed with completionReason: ${current.completion_reason}.`,
-        }],
+        diagnostics: [...report.diagnostics, diagnostic],
       },
     };
   }
@@ -318,7 +384,20 @@ export async function classifyOutcome(
           kind: 'run_parked',
           message: needsHuman
             ? `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): waiting for human recovery after the worker attempt failed.`
-            : `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): no worker is attached for step type "${parkedStep.type}".`,
+            : `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): no worker is attached for step type "${parkedStep.type}".`
+              // Only suggest the `--local-agent` remedy for YAML flows.
+              // Authored TS flows require `--input`; the bare command below
+              // would be refused (Cursor Bugbot flagged as LOW on flows#293).
+              // For TS we omit the hint rather than fabricate a syntactically
+              // valid but semantically wrong command — the direct-run refusal
+              // for TS already names its own missing --input.
+              + (command === 'run'
+                  && parkedStep.type === 'agent'
+                  && !options.localAgent
+                  && base.path !== undefined
+                  && !isAuthoredFlowPath(base.path)
+                ? ` To start a new run with a local agent worker: flows run --local-agent '${base.path.replace(/'/g, "'\\''")}'. Declared workspace or stream surfaces require a worker that holds their pins.`
+                : ''),
         }],
       },
     };
@@ -461,8 +540,12 @@ function fromBase(command: RunCommand, base: CheckReport | RunReport): RunReport
   return 'command' in base ? base : fromCheckReport(command, base);
 }
 
+// Delegates to the daemon-connection derivation so run.ts, direct-run.ts, and
+// the daemon-lifecycle attach path all speak the same socket path. Kept as a
+// re-export here so existing callers do not have to reach into
+// daemon-connection.ts. See socketPathFor for the SUN_LEN reasoning (#262).
 export function socketFor(dataDir: string): string {
-  return join(resolve(dataDir), 'relayflowd.sock');
+  return socketPathFor(dataDir);
 }
 
 function errorMessage(error: unknown): string {