@relayflows/sdk 2.0.1 → 2.0.2

package/src/cli/run.ts

@@ -1,6 +1,8 @@
 import { join, resolve } from 'node:path';
 import { toKernelSpec } from '../compile.js';
-import type { RunFailureKind } from '../failure-kinds.js';
+import { ensureDaemon, type EnsureDaemonOptions } from '../daemon-lifecycle.js';
+import { daemonRefusal } from './daemon-refusal.js';
+import type { RunFailureKind, RunWarningKind } from '../failure-kinds.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
 import type { PreflightDiagnostic } from '../preflight.js';
 import type {
@@ -24,8 +26,8 @@ export interface ParkedStep {
 }
 
 export interface RunDiagnostic {
-  severity: 'refusal' | 'failure' | 'parked';
-  kind: RunFailureKind | RunCompletionReason;
+  severity: 'refusal' | 'failure' | 'parked' | 'warning';
+  kind: RunFailureKind | RunWarningKind | RunCompletionReason;
   message: string;
 }
 
@@ -59,6 +61,12 @@ export interface RunProgress {
 export interface RunLifecycleOptions {
   signal?: AbortSignal;
   onWait?: (progress: RunProgress) => void;
+  /**
+   * Attach-or-spawn policy for the daemon this command needs
+   * (kernel/DAEMON-LIFECYCLE.md §3). `{ spawn: false }` is `--no-spawn`:
+   * refuse instead of starting one, which is today's exact behavior.
+   */
+  daemon?: EnsureDaemonOptions;
 }
 
 export async function runFlow(
@@ -80,16 +88,19 @@ async function executeCheckedFlow(
   options: RunLifecycleOptions,
 ): Promise<RunExecution> {
   const socketPath = socketFor(dataDir);
+  // Carry the preflight's diagnostics as a RunReport from here on, so the
+  // attach step has one accumulator to append to (see `connect`).
+  const base = fromCheckReport('run', checked.report);
   const client = new JournalClient(socketPath);
-  const connected = await connect(client, 'run', dataDir, checked.report);
+  const connected = await connect(client, 'run', dataDir, base, options);
   if (connected !== undefined) return connected;
 
   try {
     const spec = toKernelSpec(checked.flow!);
     const outcome = await client.runStart(spec);
-    return await classifyOutcome(client, 'run', outcome, checked.report, socketPath, options);
+    return await classifyOutcome(client, 'run', outcome, base, socketPath, options);
   } catch (error) {
-    return protocolFailure('run', checked.report, socketPath, error);
+    return protocolFailure('run', base, socketPath, error);
   } finally {
     client.close();
   }
@@ -103,7 +114,7 @@ export async function resumeFlow(
   const socketPath = socketFor(dataDir);
   const base = emptyReport('resume');
   const client = new JournalClient(socketPath);
-  const connected = await connect(client, 'resume', dataDir, base);
+  const connected = await connect(client, 'resume', dataDir, base, options);
   if (connected !== undefined) return connected;
 
   try {
@@ -131,13 +142,53 @@ export async function resumeFlow(
   }
 }
 
+/**
+ * Get a live daemon, then open the socket to it.
+ *
+ * This is the single seam every journal-opening verb shares (`runFlow`,
+ * `resumeFlow`, `runDirectFlow`), and it is where attach-or-spawn belongs —
+ * *after* the command has compiled, preflighted and validated its input, and
+ * immediately before `JournalClient` is used. Hoisting it into `runCli`
+ * instead would make a malformed invocation start a daemon as a side effect,
+ * breaking the surface's promise that missing, invalid, and oversized input is
+ * refused before the CLI contacts relayflowd (docs/SURFACE.md §5).
+ *
+ * Everything past `ensureDaemon` is unchanged and still fails closed: a
+ * connect or `hello` that fails against a daemon we just attached to is a
+ * refusal, with no retry and no second spawn.
+ */
 export async function connect(
   client: JournalClient,
   command: RunCommand,
   dataDir: string,
-  base: CheckReport | RunReport,
+  base: RunReport,
+  options: RunLifecycleOptions = {},
 ): Promise<RunExecution | undefined> {
   const socketPath = socketFor(dataDir);
+  const daemon = await ensureDaemon(dataDir, options.daemon ?? {});
+  if (daemon.kind !== 'attached') {
+    client.close();
+    return {
+      exitCode: 2,
+      report: {
+        ...fromBase(command, base),
+        socketPath,
+        diagnostics: [...base.diagnostics, daemonRefusal(daemon, dataDir, socketPath)],
+      },
+    };
+  }
+  if (daemon.warning !== undefined) {
+    // `base.diagnostics` is the accumulator that becomes the report's
+    // diagnostics, so a warning raised while attaching belongs in it — the
+    // attach succeeded, and silence about an anomaly is what AGENTS.md rule 4
+    // forbids.
+    base.diagnostics.push({
+      severity: 'warning',
+      kind: 'connection_file_stale',
+      message: daemon.warning,
+    });
+  }
+
   try {
     await client.connect();
   } catch {
@@ -396,7 +447,9 @@ export function fromCheckReport(command: RunCommand, report: CheckReport): RunRe
     ...(report.path !== undefined ? { path: report.path } : {}),
     ...(report.projectConfigPath !== undefined ? { projectConfigPath: report.projectConfigPath } : {}),
     resolutions: report.resolutions,
-    diagnostics: report.diagnostics,
+    // Copied, not aliased: the returned report is an accumulator the attach
+    // step appends to, and it must not write back into the check report.
+    diagnostics: [...report.diagnostics],
   };
 }
 

package/src/cli.ts

@@ -11,6 +11,7 @@ import {
   resumeFlow,
   runFlow,
   type RunExecution,
+  type RunProgress,
   type RunReport,
 } from './cli/run.js';
 import { runDirectFlow } from './cli/direct-run.js';
@@ -28,8 +29,8 @@ export interface CliIo {
 type CliExitCode = 0 | 1 | 2 | 3;
 type ParsedArgs =
   | { command: 'check'; json: boolean; value: string }
-  | { command: 'run'; dataDir: string; input: string | undefined; json: boolean; value: string }
-  | { command: 'resume'; dataDir: string; json: boolean; value: string }
+  | { command: 'run'; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; value: string }
+  | { command: 'resume'; dataDir: string; json: boolean; spawn: boolean; value: string }
   | { command: 'hn-monitor'; sub: 'start'; dataDir: string; specPath: string; pollIntervalMs: number | undefined }
   | { command: 'tick'; sub: 'start'; dataDir: string; specPath: string; scheduleId: string;
       intervalMs: number; epochMs: number | undefined; maxCatchUp: number | undefined;
@@ -39,13 +40,23 @@ const DEFAULT_DATA_DIR = '.relayflowd';
 const USAGE = [
   'Usage:',
   'flows check [--json] <flow.yaml|spec.json>',
-  'flows run [--json] [--data-dir <dir>] <flow.yaml|spec.json>',
-  'flows run [--json] [--data-dir <dir>] <flow.ts> --input <inline-json-or-file>',
+  'flows run [--json] [--no-spawn] [--data-dir <dir>] <flow.yaml|spec.json>',
+  'flows run [--json] [--no-spawn] [--data-dir <dir>] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
-  'flows resume [--json] [--data-dir <dir>] <run-id>',
+  'flows resume [--json] [--no-spawn] [--data-dir <dir>] <run-id>',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
 ].join(' ');
 
+/**
+ * `FLOWS_NO_SPAWN=1` is `--no-spawn` for a whole environment: the lever for CI
+ * that means to assert a daemon is already present rather than conjure one
+ * (kernel/DAEMON-LIFECYCLE.md §4). Only the exact string `1` counts — an
+ * unset or empty variable must not be read as an opinion.
+ */
+function spawnAllowedByEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env['FLOWS_NO_SPAWN'] !== '1';
+}
+
 const PROCESS_IO: CliIo = {
   stdout: (line) => process.stdout.write(`${line}\n`),
   stderr: (line) => process.stderr.write(`${line}\n`),
@@ -63,6 +74,11 @@ export async function runCli(
   }
 
   if (parsed.command === 'check') {
+    // Deliberately daemon-free (kernel/DAEMON-LIFECYCLE.md §4). `checkFlow` is
+    // a pure compile-and-preflight that opens no socket, and the parser
+    // refuses `--data-dir` on `check`, so there is no data dir to attach to.
+    // `flows check` keeps working with no daemon, no relayflowd binary and no
+    // data directory at all -- a property worth keeping, not an omission.
     const checked = checkFlow(parsed.value);
     emitCheckReport(checked.report, parsed.json, io);
     return checked.report.ok ? 0 : 2;
@@ -110,16 +126,19 @@ export async function runCli(
     }
   }
 
+  // Attach-or-spawn runs inside `runFlow`/`resumeFlow`/`runDirectFlow`, at the
+  // single `connect()` seam immediately before journal-client.ts is used --
+  // not here. Hoisting it above the dispatch would start a daemon as a side
+  // effect of an invocation that is about to be refused for bad input.
+  const lifecycle = {
+    onWait: (progress: RunProgress) => emitWait(progress, io),
+    daemon: { spawn: parsed.spawn && spawnAllowedByEnv() },
+  };
   const execution = parsed.command === 'run'
     ? isAuthoredFlowPath(parsed.value)
-      ? await runDirectFlow(
-          parsed.value,
-          parsed.input,
-          parsed.dataDir,
-          { onWait: (progress) => emitWait(progress, io) },
-        )
-      : await runFlow(parsed.value, parsed.dataDir, { onWait: (progress) => emitWait(progress, io) })
-    : await resumeFlow(parsed.value, parsed.dataDir, { onWait: (progress) => emitWait(progress, io) });
+      ? await runDirectFlow(parsed.value, parsed.input, parsed.dataDir, lifecycle)
+      : await runFlow(parsed.value, parsed.dataDir, lifecycle)
+    : await resumeFlow(parsed.value, parsed.dataDir, lifecycle);
   emitRunReport(execution, parsed.json, io);
   return execution.exitCode;
 }
@@ -143,6 +162,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   let json = false;
   let dataDir = DEFAULT_DATA_DIR;
   let sawDataDir = false;
+  let spawn = true;
   let input: string | undefined;
   let sawInput = false;
   const positionals: string[] = [];
@@ -153,6 +173,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       json = true;
       continue;
     }
+    if (argument === '--no-spawn') {
+      // Refused on `check` for the same reason `--data-dir` is: `check` never
+      // opens a socket, so a daemon flag there would describe nothing.
+      if (command === 'check' || !spawn) return undefined;
+      spawn = false;
+      continue;
+    }
     if (argument === '--data-dir') {
       const value = args[index + 1];
       if (command === 'check' || sawDataDir || value === undefined || value.startsWith('-')) return undefined;
@@ -178,8 +205,8 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   return command === 'check'
     ? { command, json, value: positionals[0]! }
     : command === 'run'
-      ? { command, dataDir, input, json, value: positionals[0]! }
-      : { command, dataDir, json, value: positionals[0]! };
+      ? { command, dataDir, input, json, spawn, value: positionals[0]! }
+      : { command, dataDir, json, spawn, value: positionals[0]! };
 }
 
 function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {

package/src/compile.ts

@@ -109,6 +109,8 @@ function compileStep(step: StepSpec): StepSpec {
     type: step.type,
     ...(step.dependsOn !== undefined ? { dependsOn: step.dependsOn } : {}),
     maxIterations,
+    ...(step.memory !== undefined ? { memory: step.memory } : {}),
+    ...(step.requirements !== undefined ? { requirements: step.requirements } : {}),
   };
 
   switch (step.type as StepType) {
@@ -352,13 +354,13 @@ function kernelTriggerToAuthoring(value: unknown, at: string): unknown {
 
 function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const unionKeys = [
-    'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification',
+    'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements',
     'command', 'timeout_ms', 'prompt', 'model', 'cli', 'instruction',
     'recovery_mode', 'surfaces', 'permissions',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   const type = step['type'];
-  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification'] as const;
+  const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements'] as const;
   const typeKeys = type === 'deterministic'
     ? ['command', 'timeout_ms'] as const
     : type === 'llm'
@@ -367,16 +369,18 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
         ? ['instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions'] as const
         : [];
   assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
-  if (step['retry'] !== undefined) validateKernelRetry(step['retry'], `${at}.retry`);
+  if (step['retry'] !== undefined) validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
   const dependsOn = step['depends_on'];
   const common = {
     id: step['id'],
     type,
+    ...(step['requirements'] !== undefined ? { requirements: kernelRequirementsToAuthoring(step['requirements'], `${at}.requirements`) } : {}),
     ...(dependsOn !== undefined && (!Array.isArray(dependsOn) || dependsOn.length > 0)
       ? { dependsOn }
       : {}),
     ...(step['max_iterations'] !== undefined ? { maxIterations: step['max_iterations'] } : {}),
     ...kernelVerificationToAuthoring(type, step['verification'], `${at}.verification`),
+    ...(step['memory'] !== undefined ? { memory: kernelMemoryToAuthoring(step['memory'], `${at}.memory`) } : {}),
   };
   if (type === 'deterministic') {
     return {
@@ -402,7 +406,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   return common;
 }
 
-function validateKernelRetry(value: unknown, at: string): void {
+function validateAuthoringRetryDefaults(value: unknown, at: string): void {
   const retry = requireKernelObject(value, [
     'initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent',
   ], at);
@@ -434,6 +438,14 @@ function kernelVerificationToAuthoring(
   return type === 'deterministic' ? { verification: { type: 'exit_code' } } : {};
 }
 
+function kernelMemoryToAuthoring(value: unknown, at: string): unknown {
+  const memory = requireKernelObject(value, ['scope', 'query', 'budget'], at);
+  return {
+    scope: memory['scope'], query: memory['query'],
+    budget: kernelBudgetToAuthoring(memory['budget'], `${at}.budget`),
+  };
+}
+
 function kernelBudgetToAuthoring(value: unknown, at: string): unknown {
   const budget = requireKernelObject(value, ['max_tokens_in', 'max_tokens_out', 'max_dollars'], at);
   return {
@@ -497,6 +509,19 @@ function toKernelStep(step: StepSpec): KernelStepSpec {
     max_iterations: step.maxIterations ?? 1,
     retry: { ...KERNEL_RETRY_DEFAULTS },
     verification: toKernelVerification(step),
+    ...(step.requirements !== undefined ? { requirements: {
+      ...Object.fromEntries(Object.entries(step.requirements).filter(([key]) => key !== 'expectedDurationMs')),
+      ...(step.requirements.expectedDurationMs !== undefined ? { expected_duration_ms: step.requirements.expectedDurationMs } : {}),
+    } } : {}),
+    ...(step.memory !== undefined ? { memory: {
+      scope: step.memory.scope,
+      query: step.memory.query,
+      budget: {
+        ...(step.memory.budget.maxTokensIn !== undefined ? { max_tokens_in: step.memory.budget.maxTokensIn } : {}),
+        ...(step.memory.budget.maxTokensOut !== undefined ? { max_tokens_out: step.memory.budget.maxTokensOut } : {}),
+        ...(step.memory.budget.maxDollars !== undefined ? { max_dollars: step.memory.budget.maxDollars } : {}),
+      },
+    } } : {}),
   };
   switch (step.type) {
     case 'deterministic':
@@ -571,3 +596,11 @@ export function compileAndHash(yaml: string): { spec: FlowSpec; kernelSpec: Kern
 }
 
 export { SPEC_SCHEMA_VERSION, canonicalize, specHash };
+
+function kernelRequirementsToAuthoring(value: unknown, at: string): unknown {
+  const requirements = requireKernelObject(value, ['execution', 'workspace', 'network', 'expected_duration_ms', 'preference'], at);
+  return {
+    ...copyDefined(requirements, ['execution', 'workspace', 'network', 'preference']),
+    ...(requirements['expected_duration_ms'] !== undefined ? { expectedDurationMs: requirements['expected_duration_ms'] } : {}),
+  };
+}

package/src/daemon-connection.ts

@@ -0,0 +1,336 @@
+// Reading and validating relayflowd's connection file, and deciding whether
+// anything is actually serving a data dir (kernel/DAEMON-LIFECYCLE.md §§1-2).
+//
+// Split from daemon-lifecycle.ts along the same seam ../relay uses between
+// broker-connection.ts and broker-lifecycle.ts: this file answers "what is
+// there?", that one answers "put something there". Neither approaches the
+// 500-line smell in AGENTS.md rule 1.
+//
+// The governing rule, from §1: **the socket is the authority;
+// `connection.json` is an index over it.** A file is never believed on its
+// own. Every "attach" in this module is backed by a `hello` that a live
+// daemon answered on the socket path recomputed from `--data-dir` — never by
+// what a file says about itself.
+
+import { spawn, type ChildProcess, type SpawnOptions } from 'node:child_process';
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { JournalClient, JournalProtocolError } from './journal-client.js';
+import { PROTOCOL_VERSION } from './protocol.js';
+import {
+  defaultRelayflowdPathDeps,
+  resolveRelayflowdBinary,
+} from './relayflowd-path.js';
+
+/**
+ * The `hello` probe runs before every command, so it must be short. §4 gives
+ * `connect()` the same bound for the same reason: a listener that accepts and
+ * never answers must not hold the CLI for the 30s request default.
+ */
+export const PROBE_TIMEOUT_MS = 2_000;
+
+export const CONNECTION_FILE = 'connection.json';
+export const SOCKET_FILE = 'relayflowd.sock';
+export const DAEMON_LOG_FILE = 'relayflowd.log';
+
+/** `<data-dir>/connection.json`, exactly the shape in §1. */
+export interface DaemonConnection {
+  socket_path: string;
+  pid: number;
+  version: string;
+  protocol: number;
+  started_at_ms: number;
+}
+
+/** Why an existing `connection.json` was not believed (§2's four cases). */
+export type StaleReason =
+  /** §2 step 3: the file names a socket that is not this data dir's. */
+  | 'socket_path_mismatch'
+  /** §2 row 1: nothing serving, and the pid is gone. A corpse. */
+  | 'dead_pid_dead_socket'
+  /** §2 row 3: pid alive but nothing answers — mid-boot, or a reused pid. */
+  | 'live_pid_dead_socket';
+
+/** Closed refusal taxonomy for the lifecycle itself. Mirrored in failure-kinds.ts. */
+export type DaemonFailureKind =
+  | 'daemon_unreachable'
+  | 'relayflowd_not_found'
+  | 'daemon_start_failed'
+  | 'daemon_start_timeout';
+
+export type DaemonState =
+  | { kind: 'attached'; socketPath: string; connection: DaemonConnection | null; warning?: string }
+  | { kind: 'absent' }
+  | { kind: 'stale'; reason: StaleReason; message: string }
+  | { kind: 'incompatible'; protocol: number }
+  /**
+   * `ensureDaemon` only. §4's sketch types `ensureDaemon` as returning a
+   * `DaemonState` while §3 branches D.b/D.d refuse with kinds that union has
+   * no member for; this is that refusal channel, kept as data rather than a
+   * thrown error so it reads like the rest of cli/run.ts.
+   */
+  | { kind: 'unavailable'; failure: DaemonFailureKind; message: string };
+
+/** A probe of the socket itself — the only check that proves something serves. */
+export interface SocketProbe {
+  reachable: boolean;
+  /**
+   * The protocol the daemon reported. Absent when something is demonstrably
+   * serving the socket but would not say — see `probeSocket`.
+   */
+  protocol?: number;
+}
+
+/**
+ * Injectable seams, following the `deps` pattern of the ../relay file this is
+ * modelled on. Unit tests reach no real filesystem and spawn no process.
+ */
+export interface DaemonLifecycleDeps {
+  readFile(path: string): string | null;
+  removeFile(path: string): void;
+  makeDirectory(path: string): void;
+  openAppend(path: string): number;
+  closeFd(fd: number): void;
+  readTail(path: string, bytes: number): string;
+  killProcess(pid: number, signal: number): void;
+  spawnProcess(command: string, args: readonly string[], options: SpawnOptions): ChildProcess;
+  resolveBinary(): string;
+  probe(socketPath: string, timeoutMs: number): Promise<SocketProbe>;
+  now(): number;
+  sleep(ms: number): Promise<void>;
+}
+
+export const defaultDaemonLifecycleDeps: DaemonLifecycleDeps = {
+  readFile(path) {
+    try {
+      return readFileSync(path, 'utf8');
+    } catch {
+      return null;
+    }
+  },
+  removeFile(path) {
+    rmSync(path, { force: true });
+  },
+  makeDirectory(path) {
+    mkdirSync(path, { recursive: true });
+  },
+  openAppend: (path) => openSync(path, 'a'),
+  closeFd: (fd) => closeSync(fd),
+  readTail(path, bytes) {
+    try {
+      const content = readFileSync(path, 'utf8');
+      return content.length <= bytes ? content : content.slice(-bytes);
+    } catch {
+      return '';
+    }
+  },
+  killProcess: (pid, signal) => {
+    process.kill(pid, signal);
+  },
+  spawnProcess: (command, args, options) => spawn(command, args as string[], options),
+  resolveBinary: () => resolveRelayflowdBinary(defaultRelayflowdPathDeps),
+  probe: (socketPath, timeoutMs) => probeSocket(socketPath, timeoutMs),
+  now: () => Date.now(),
+  // Deliberately NOT unref'd: an unref'd timer lets Node exit the event loop
+  // mid-poll, which would abandon the await and end the CLI with no report.
+  // The deadline in `pollForDaemon` is what bounds this wait.
+  sleep: (ms) => new Promise((done) => {
+    setTimeout(done, ms);
+  }),
+};
+
+export function socketPathFor(dataDir: string): string {
+  return join(resolve(dataDir), SOCKET_FILE);
+}
+
+export function connectionPathFor(dataDir: string): string {
+  return join(resolve(dataDir), CONNECTION_FILE);
+}
+
+/**
+ * §2 steps 1-2. Absent, unparseable, and wrongly-typed all read the same:
+ * `null`. Unknown fields are ignored, so adding one later is not breaking.
+ * The `socket_path` agreement check is §2 step 3 and lives in `checkDaemon`,
+ * which knows the data dir the path must agree with.
+ */
+export function readConnectionFile(
+  dataDir: string,
+  deps: DaemonLifecycleDeps = defaultDaemonLifecycleDeps,
+): DaemonConnection | null {
+  const raw = deps.readFile(connectionPathFor(dataDir));
+  if (raw === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return null;
+  const record = parsed as Record<string, unknown>;
+  const socketPath = record['socket_path'];
+  const pid = record['pid'];
+  const version = record['version'];
+  const protocol = record['protocol'];
+  const startedAtMs = record['started_at_ms'];
+  if (typeof socketPath !== 'string' || socketPath.length === 0) return null;
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) return null;
+  if (typeof version !== 'string') return null;
+  if (typeof protocol !== 'number' || !Number.isInteger(protocol)) return null;
+  if (typeof startedAtMs !== 'number' || !Number.isInteger(startedAtMs) || startedAtMs <= 0) {
+    return null;
+  }
+  return {
+    socket_path: socketPath,
+    pid,
+    version,
+    protocol,
+    started_at_ms: startedAtMs,
+  };
+}
+
+/**
+ * §2 step 4. **`EPERM` means alive** — the process exists and is owned by
+ * another user. ../relay's `isProcessRunning` treats every throw as dead,
+ * which would spawn a second daemon over a live one owned by someone else.
+ * That bug is not ported.
+ */
+export function isProcessAlive(
+  pid: number,
+  deps: DaemonLifecycleDeps = defaultDaemonLifecycleDeps,
+): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    deps.killProcess(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * §2 step 5. Connect, `hello`, close. A refused connection, a connect timeout,
+ * or a `hello` that does not answer inside the probe timeout is a failed
+ * probe. This is the only check that proves something is *serving*.
+ *
+ * A `hello` that answers with a structured REFUSAL is not a failed probe. §2
+ * step 5 was written against silence, and silence is what it must catch;
+ * something that returns `{ ok: false, error: ... }` is unmistakably a live
+ * server, and calling it absent would spawn a second daemon over it — the one
+ * outcome this whole design exists to prevent. It is reported as reachable
+ * with no protocol, which leaves the refusal to be reported by the command's
+ * own `hello`, where it becomes a `protocol_error` naming the server's code
+ * instead of a lifecycle guess.
+ */
+export async function probeSocket(
+  socketPath: string,
+  timeoutMs: number = PROBE_TIMEOUT_MS,
+): Promise<SocketProbe> {
+  const client = new JournalClient(socketPath, {
+    connectTimeoutMs: timeoutMs,
+    requestTimeoutMs: timeoutMs,
+  });
+  try {
+    await client.connect();
+    const hello = await client.hello('flows-probe');
+    return { reachable: true, protocol: hello.protocol };
+  } catch (error) {
+    return error instanceof JournalProtocolError ? { reachable: true } : { reachable: false };
+  } finally {
+    client.close();
+  }
+}
+
+/**
+ * §2, decided as one function. The socket is probed at the path recomputed
+ * from `--data-dir`, never at the path the file names, so a file that points
+ * elsewhere is stale rather than a redirect.
+ *
+ * One addition to §2's table, licensed by §1's governing rule: a socket that
+ * answers `hello` with **no** connection file at all is an attach, not an
+ * absence. §2 row 2 already attaches on the socket's authority over a file
+ * describing a dead pid; a missing file is strictly less evidence against the
+ * socket than a stale one. It also keeps the CLI honest about a daemon started
+ * from a build that predates the connection file.
+ */
+export async function checkDaemon(
+  dataDir: string,
+  deps: DaemonLifecycleDeps = defaultDaemonLifecycleDeps,
+): Promise<DaemonState> {
+  const socketPath = socketPathFor(dataDir);
+  const connection = readConnectionFile(dataDir, deps);
+  const agrees = connection !== null && connection.socket_path === socketPath;
+
+  // §2's reason for carrying `protocol` in the file: an incompatible daemon
+  // owning this data dir is decided without a round trip.
+  if (agrees && connection.protocol !== PROTOCOL_VERSION) {
+    return { kind: 'incompatible', protocol: connection.protocol };
+  }
+
+  const probe = await deps.probe(socketPath, PROBE_TIMEOUT_MS);
+  if (probe.reachable) {
+    // Only a KNOWN mismatch refuses. An undefined protocol means the daemon
+    // is serving but declined to say, which the command's own `hello` will
+    // report far better than this function could.
+    if (probe.protocol !== undefined && probe.protocol !== PROTOCOL_VERSION) {
+      return { kind: 'incompatible', protocol: probe.protocol };
+    }
+    if (!agrees) {
+      // No warning when the file is merely ABSENT: that is the ordinary state
+      // during a daemon's boot window, and the ordinary state of any daemon
+      // built before the connection file existed. A file that CONTRADICTS the
+      // socket is a different matter and is named.
+      const mismatch = connection === null
+        ? undefined
+        : `"${connectionPathFor(dataDir)}" names a different socket (${connection.socket_path}); attaching to "${socketPath}" instead.`;
+      return {
+        kind: 'attached',
+        socketPath,
+        connection: null,
+        ...(mismatch === undefined ? {} : { warning: mismatch }),
+      };
+    }
+    // §2 row 2: dead pid, live socket. Something is serving; do not spawn.
+    // Binding over a live daemon is the corruption this design prevents.
+    const warning = isProcessAlive(connection.pid, deps)
+      ? undefined
+      : `${CONNECTION_FILE} names pid ${connection.pid}, which is not running, but "${socketPath}" is serving. Attaching to the socket.`;
+    return {
+      kind: 'attached',
+      socketPath,
+      connection,
+      ...(warning === undefined ? {} : { warning }),
+    };
+  }
+
+  // Nothing is serving.
+  if (connection === null) return { kind: 'absent' };
+  if (!agrees) {
+    return {
+      kind: 'stale',
+      reason: 'socket_path_mismatch',
+      message: `${CONNECTION_FILE} names socket "${connection.socket_path}", not "${socketPath}".`,
+    };
+  }
+  // §2 row 3: a live pid proves nothing — a daemon mid-boot and an unrelated
+  // process that inherited the pid look identical from here, and neither is
+  // an attach. Spawning is safe in both cases because the daemon holds the
+  // mutex (§3): a redundant child loses the flock and exits 3.
+  return isProcessAlive(connection.pid, deps)
+    ? {
+      kind: 'stale',
+      reason: 'live_pid_dead_socket',
+      message: `pid ${connection.pid} is alive but "${socketPath}" is not accepting connections.`,
+    }
+    : {
+      kind: 'stale',
+      reason: 'dead_pid_dead_socket',
+      message: `pid ${connection.pid} is gone and "${socketPath}" is not accepting connections.`,
+    };
+}
+