@mcrescenzo/opencode-workflows 0.1.0

package/workflow-kernel/run-context.js

@@ -0,0 +1,139 @@
+// RunContext: the mutable per-run state object that threads through the workflow
+// orchestrator (workflow-plugin.js) and every extracted boundary it dispatches to
+// (sandbox-executor.js, child-agent-runner.js, run-store-status.js, lifecycle-control.js,
+// event-journal.js, budget-accounting.js, ...).
+//
+// This module is intentionally type-only: it carries NO runtime logic. Its single job is
+// to document the coupling surface — the ~70-property "run" object that the staged
+// god-object split (opencode-workflows-96b) decomposes around. Extracted modules import
+// the {@link RunContext} typedef so the property contract each boundary reads/writes is
+// explicit rather than implicit, and so the natural module split points (which subset of
+// these properties a concern actually touches) become visible.
+//
+// The canonical construction site is startWorkflow() in workflow-plugin.js. resume seeds a
+// subset from prior on-disk state via rehydrateRunFromPriorState (run-store-status.js).
+// Mutation here is deliberate: the run object IS the orchestrator's shared mutable state;
+// typing it does not freeze it.
+
+/**
+ * Per-lane abort wiring tracked for in-flight child agents, keyed by callId.
+ *
+ * @typedef {object} ActiveLaneAbort
+ * @property {AbortController} abortController Lane-scoped controller, chained to run.abortController.
+ * @property {string|undefined} childID Child session id once session.create returns.
+ * @property {string|undefined} directory Working directory (worktree path or tool directory).
+ */
+
+/**
+ * A pending concurrency-slot waiter (see acquireAgentSlot / releaseAgentSlot).
+ *
+ * @typedef {object} WaitingAgent
+ * @property {() => void} resolve Hand off the slot to this waiter.
+ * @property {(error: Error) => void} reject Reject the waiter (cancellation / fanout abort).
+ * @property {string} callId Lane call id, used by fanout cancellation to target waiters.
+ */
+
+/**
+ * Token accounting bucket (live or replayed).
+ *
+ * @typedef {object} TokenUsage
+ * @property {number} input
+ * @property {number} output
+ * @property {number} reasoning
+ */
+
+/**
+ * The mutable run context threaded through the orchestrator and its boundaries.
+ *
+ * Grouped by concern to make the split surface legible. The grouping is documentation
+ * only; at runtime this is one flat object.
+ *
+ * @typedef {object} RunContext
+ *
+ * --- identity / source / approval envelope ---
+ * @property {string} id Run id (resume id or a fresh uuid).
+ * @property {string} dir Durable run directory (state.json, journal.jsonl, lanes/, worktrees/).
+ * @property {string} sourcePath Resolved workflow source path ("<inline>" for inline sources).
+ * @property {string} sourceHash Content hash of the workflow source (approval-bound).
+ * @property {object} meta Parsed workflow meta (name, description, phases, ...).
+ * @property {object} authority Resolved authority profile (edit/worktreeEdit/integration, gates, isolation).
+ * @property {*} runtimeArgs Caller-supplied runtime args (approval-bound).
+ * @property {string} argsPreview Redacted preview of runtimeArgs for approval/status text.
+ * @property {Map<string, object>} nestedSnapshots Approved nested-workflow source snapshots, by path and hash.
+ * @property {boolean} [externalSource] True when the source was loaded via allowExternalScriptPath opt-in.
+ *
+ * --- lifecycle / status ---
+ * @property {string} status running | cancelling | pausing | paused | interrupted | completed | failed | ...
+ * @property {string} startedAt ISO start timestamp (preserved across resume).
+ * @property {string|undefined} resumedAt ISO timestamp set when a run resumes.
+ * @property {string|undefined} finishedAt ISO completion timestamp.
+ * @property {string|undefined} currentPhase Most recent phase() name.
+ * @property {Error|string|undefined} error Terminal error, if any.
+ * @property {{enabled: boolean, source?: string}|undefined} debugCapture Opt-in prompt/schema/transcript capture state.
+ * @property {string|undefined} firstResultAt First successful lane completion timestamp.
+ * @property {number|undefined} timeToFirstResultMs Duration from run start to first successful lane.
+ * @property {{startedAt?: string, completedAt?: string, durationMs?: number, diffPlanHash?: string}|undefined} approvalWait Diff-approval wait metric.
+ * @property {string[]} recentLogs Last narrator log() lines, bounded for toast/status display.
+ * @property {object|undefined} lifecycleRequests Last-read durable cancel/pause request envelope.
+ * @property {boolean} pauseRequested Set when a durable pause request is observed.
+ * @property {boolean} background True for fire-and-forget background runs.
+ * @property {boolean} ignoreToolAbort True when the run must ignore the tool-call abort signal (background).
+ * @property {Promise<*>} [done] Background run completion promise.
+ *
+ * --- budget / concurrency / model plan ---
+ * @property {number} agentsStarted Child agents launched (carried across resume).
+ * @property {number} maxAgents Hard cap on agents started.
+ * @property {number} concurrency Max concurrent active agents.
+ * @property {number} activeAgents Currently running agents (gated by concurrency).
+ * @property {WaitingAgent[]} waitingAgents FIFO queue of agents awaiting a concurrency slot.
+ * @property {number} laneTimeoutMs Default per-lane prompt timeout.
+ * @property {string} defaultChildModel Fallback child model.
+ * @property {{fast?: string, deep?: string}|undefined} modelTiers Lane model tier map.
+ * @property {TokenUsage} tokens Live token usage accumulated this session.
+ * @property {TokenUsage} replayedTokens Token usage carried forward from prior segments at resume.
+ * @property {number} cost Live cost accumulated this session.
+ * @property {number} replayedCost Cost carried forward from prior segments at resume.
+ * @property {{maxCost?: number, maxTokens?: number}|undefined} budgetCeilings Budget stop ceilings.
+ * @property {{hits: number, misses: number, invalidated: number}} cacheStats Resume cache-hit accounting.
+ * @property {Object<string, number>} laneOutcomes Per-outcome lane counters.
+ * @property {number} droppedLaneCount Fanout lanes dropped (non-failFast failures).
+ * @property {number} guestDeadlineMs Interrupt deadline budget for synchronous guest bursts.
+ * @property {number} hostCalls Host-op call counter (per-run scaled host-call guard).
+ *
+ * --- capability / adapter surface ---
+ * @property {object} capabilities Resolved client capabilities (childSession, structuredOutput, worktree, ...).
+ * @property {object} diagnostics Capability/probe diagnostics (incl. drainLiveGates).
+ * @property {object} adapter Capability adapter (getStructured, createWorktree, removeWorktree, ...).
+ * @property {object} [worktreeAdapter] Native integration worktree adapter (lazily created).
+ *
+ * --- edit / integration / worktrees ---
+ * @property {object[]} editWorktrees Throwaway edit-lane worktree records.
+ * @property {object|undefined} editPlan Accumulated diff plan (patches, baseCommit) for edit authority.
+ * @property {object|undefined} integrationPlan Integration plan (lanes, baseCommit, integrationResult).
+ * @property {object[]} integrationWorktrees Integration-lane worktree records.
+ * @property {object} [worktreeCleanup] Worktree cleanup summary ledger.
+ *
+ * --- lanes / journal / children ---
+ * @property {Map<string, object>} laneRecords In-memory lane outcome records, by callId.
+ * @property {Map<string, string>} children Active child session ids -> directory.
+ * @property {Map<string, ActiveLaneAbort>} activeLaneAbortControllers In-flight lane abort wiring.
+ * @property {Set<string>} cancelledFanoutScopes Fanout scopes cancelled by failFast.
+ * @property {Map<string, object>} resumeJournal Prior-segment journal entries consulted on resume.
+ * @property {Map<string, Map<string, object[]>>} resumeSignatureIndex Prior successful journal entries by lane signature and fallback scope.
+ * @property {Set<string>} resumeSignatureClaims Prior callIds already consumed by exact or signature resume replay.
+ * @property {number} eventCount Append-only events.jsonl line count (MAX guard).
+ * @property {number} journalRecords Append-only journal.jsonl line count (MAX guard).
+ * @property {(record: object, run: RunContext) => (Promise<void>|void)|undefined} eventSink Optional best-effort observer invoked after events append.
+ * @property {number} nestingDepth Current nested-workflow recursion depth (max 1).
+ *
+ * --- control / notification ---
+ * @property {AbortController} abortController Run-wide abort controller; lane controllers chain to it.
+ * @property {object|undefined} notificationTarget Background completion-notification target.
+ * @property {object} [notification] Completion-notification record/state.
+ * @property {() => Promise<void>|void} [releaseRunLock] Release the durable run lock.
+ */
+
+// No runtime exports: this module exists purely to host the shared typedef. A named export
+// keeps it a valid ES module and gives importers a stable specifier to attach the
+// `@typedef {import("./run-context.js").RunContext}` reference to.
+export const RUN_CONTEXT_TYPEDEF = "RunContext";

package/workflow-kernel/run-observability.js

@@ -0,0 +1,43 @@
+const RECENT_LOG_LIMIT = 3;
+
+function boundedString(value) {
+  return String(value ?? "");
+}
+
+function normalizeRecentLogs(logs, options = {}) {
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : RECENT_LOG_LIMIT;
+  if (!Array.isArray(logs)) return [];
+  return logs.map(boundedString).filter((line) => line.length > 0).slice(-limit);
+}
+
+function recordRecentLog(run, message, options = {}) {
+  if (!run || typeof run !== "object") return [];
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : RECENT_LOG_LIMIT;
+  const logs = normalizeRecentLogs(run.recentLogs, { limit });
+  const text = boundedString(message);
+  if (text) logs.push(text);
+  run.recentLogs = logs.slice(-limit);
+  return run.recentLogs;
+}
+
+function notifyRunEventSink(run, record) {
+  const sink = run?.eventSink;
+  if (typeof sink !== "function") return;
+  try {
+    const result = sink(record, run);
+    if (result && typeof result.then === "function") {
+      result.catch(() => {
+        // Event sinks are observers; rejected delivery must not affect journaling.
+      });
+    }
+  } catch {
+    // Event sinks are observers; thrown delivery must not affect journaling.
+  }
+}
+
+export {
+  RECENT_LOG_LIMIT,
+  normalizeRecentLogs,
+  recordRecentLog,
+  notifyRunEventSink,
+};

package/workflow-kernel/run-store-fs.js

@@ -0,0 +1,231 @@
+// Shared run-store primitives: FS/JSON atomic helpers, run-id/path containment guards,
+// run-root resolution, PID liveness, and the in-memory `runs` registry. These are the
+// concern-agnostic building blocks that every run-store module (durable state, locks,
+// projections, rehydration, status formatting) reads/writes; they were extracted from the
+// former 957-line run-store-status.js (opencode-workflows-nbp) so each concern module can
+// depend on this base rather than on each other.
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GLOBAL_WORKFLOW_DIR, RUN_ID_RE } from "./constants.js";
+import { hash } from "./text-json.js";
+import { projectWorkflowDir } from "./workflow-source.js";
+import { pathContains as isPathInside } from "./path-policy.js";
+
+const PRIVATE_DIR_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+const LOCK_LIVENESS_FALLBACK_TTL_MS = 24 * 60 * 60 * 1000;
+
+async function chmodBestEffort(filePath, mode) {
+  try {
+    await fs.chmod(filePath, mode);
+  } catch {
+    // chmod can be unsupported on some filesystems. Creation still requested the
+    // restrictive mode; keep workflow execution moving if the chmod backstop is unavailable.
+  }
+}
+
+async function ensurePrivateDir(dir) {
+  await fs.mkdir(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+  await chmodBestEffort(dir, PRIVATE_DIR_MODE);
+}
+
+function privateFileOptions(options = "utf8") {
+  if (typeof options === "string") return { encoding: options, mode: PRIVATE_FILE_MODE };
+  return { mode: PRIVATE_FILE_MODE, ...options };
+}
+
+async function writeFilePrivate(filePath, data, options = "utf8") {
+  await ensurePrivateDir(path.dirname(filePath));
+  await fs.writeFile(filePath, data, privateFileOptions(options));
+  await chmodBestEffort(filePath, PRIVATE_FILE_MODE);
+}
+
+async function appendFilePrivate(filePath, data, options = "utf8") {
+  await ensurePrivateDir(path.dirname(filePath));
+  await fs.appendFile(filePath, data, privateFileOptions(options));
+  await chmodBestEffort(filePath, PRIVATE_FILE_MODE);
+}
+
+// Generic FS-JSON helper (read with fallback) — colocated with writeJsonAtomic/pathExists.
+async function readJsonFile(filePath, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFilePrivate(tmp, JSON.stringify(value, null, 2), "utf8");
+    await fs.rename(tmp, filePath);
+    await chmodBestEffort(filePath, PRIVATE_FILE_MODE);
+  } catch (error) {
+    // A write/rename failure (EACCES/ENOSPC) can otherwise orphan a tmp file on disk.
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const runs = new Map();
+
+let selfStartTime;
+
+function assertSafeRunId(runId, label = "runId") {
+  if (typeof runId !== "string" || !RUN_ID_RE.test(runId) || runId === "." || runId === "..") {
+    throw new Error(`${label} must be a simple run id without path separators`);
+  }
+  return runId;
+}
+
+function runDirForRoot(root, runId) {
+  assertSafeRunId(runId);
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, runId);
+  if (!resolved.startsWith(`${resolvedRoot}${path.sep}`)) throw new Error(`runId escapes workflow run root: ${runId}`);
+  return resolved;
+}
+
+async function processStartTime(pid) {
+  // Linux-only best effort: field 22 of /proc/<pid>/stat is the process start time. The
+  // comm (field 2) can contain spaces/parens, so parse after the final ')'.
+  try {
+    const stat = await fs.readFile(`/proc/${pid}/stat`, "utf8");
+    const fields = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+    const starttime = Number(fields[19]);
+    return Number.isFinite(starttime) ? starttime : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function selfProcessStartTime() {
+  if (selfStartTime === undefined) selfStartTime = (await processStartTime(process.pid)) ?? null;
+  return selfStartTime === null ? undefined : selfStartTime;
+}
+
+async function processAppearsAlive(processInfo, {
+  readStartTime = processStartTime,
+  now = Date.now(),
+  lockTtlMs = LOCK_LIVENESS_FALLBACK_TTL_MS,
+} = {}) {
+  const owner = processInfo && typeof processInfo === "object" && processInfo.process ? processInfo.process : processInfo;
+  const pid = typeof owner === "number" ? owner : owner?.pid;
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  let alive;
+  try {
+    process.kill(pid, 0);
+    alive = true;
+  } catch (error) {
+    alive = error.code === "EPERM";
+  }
+  if (!alive) return false;
+  // Guard against PID reuse: if the owner's process start time was recorded, compare it to
+  // the live process's start time. When NO start time was recorded (non-Linux owner, legacy
+  // state) we have nothing to compare against, so fall back to the bare liveness check.
+  const recordedStart = typeof owner === "object" ? owner?.startTime : undefined;
+  if (Number.isFinite(recordedStart)) {
+    // A recorded start exists, so we expect to be able to confirm it. Distrust the PID unless
+    // the live start is readable AND matches: a non-finite liveStart (/proc unreadable,
+    // hidepid/EPERM, TOCTOU) is treated as a mismatch rather than blind trust, so a reused PID
+    // is not pinned as active and reconcile/cleanup is not blocked.
+    const liveStart = await readStartTime(pid);
+    if (!Number.isFinite(liveStart) || liveStart !== recordedStart) return false;
+  } else if (processInfo && typeof processInfo === "object" && typeof processInfo.acquiredAt === "string") {
+    const acquiredMs = Date.parse(processInfo.acquiredAt);
+    if (Number.isFinite(acquiredMs) && Number.isFinite(lockTtlMs) && lockTtlMs > 0 && now - acquiredMs >= lockTtlMs) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function currentProcessInfo() {
+  return { pid: process.pid, startTime: await selfProcessStartTime() };
+}
+
+function runRoot(context) {
+  return path.join(projectWorkflowDir(context), "runs");
+}
+
+function globalRunRoot(context) {
+  const key = hash(path.resolve(context.worktree || context.directory || ".")).slice(0, 16);
+  return path.join(GLOBAL_WORKFLOW_DIR, "runs", key);
+}
+
+function runRoots(context) {
+  return [...new Set([runRoot(context), globalRunRoot(context)])];
+}
+
+async function ensureRunRoot(context) {
+  for (const root of runRoots(context)) {
+    try {
+      await ensurePrivateDir(root);
+      await writeFilePrivate(path.join(root, ".gitignore"), "*\n!.gitignore\n", "utf8");
+      return root;
+    } catch (error) {
+      if (error.code !== "EACCES" && error.code !== "EROFS" && error.code !== "EPERM") throw error;
+    }
+  }
+  throw new Error("Could not create a writable workflow run directory");
+}
+
+async function assertContainedRealPath(root, candidate, label) {
+  const rootReal = await fs.realpath(root);
+  const candidateReal = await fs.realpath(candidate);
+  if (!isPathInside(rootReal, candidateReal)) throw new Error(`${label} escapes expected root: ${candidate}`);
+  return { rootReal, candidateReal };
+}
+
+async function assertContainedRunDir(root, dir) {
+  await assertContainedRealPath(root, dir, "Workflow run directory");
+  const stat = await fs.lstat(dir);
+  if (stat.isSymbolicLink()) throw new Error(`Workflow run directory is a symlink: ${dir}`);
+  if (!stat.isDirectory()) throw new Error(`Workflow run path is not a directory: ${dir}`);
+}
+
+function safeProjectionName(value) {
+  const safe = String(value ?? "").replace(/[^a-z0-9_.-]+/gi, "_").replace(/^_+|_+$/g, "").slice(0, 120);
+  return safe || hash(String(value ?? "lane")).slice(0, 16);
+}
+
+export {
+  PRIVATE_DIR_MODE,
+  PRIVATE_FILE_MODE,
+  LOCK_LIVENESS_FALLBACK_TTL_MS,
+  runs,
+  selfStartTime,
+  readJsonFile,
+  writeJsonAtomic,
+  ensurePrivateDir,
+  writeFilePrivate,
+  appendFilePrivate,
+  pathExists,
+  assertSafeRunId,
+  runDirForRoot,
+  processStartTime,
+  selfProcessStartTime,
+  processAppearsAlive,
+  currentProcessInfo,
+  runRoot,
+  globalRunRoot,
+  runRoots,
+  ensureRunRoot,
+  assertContainedRealPath,
+  assertContainedRunDir,
+  safeProjectionName,
+  isPathInside,
+};

package/workflow-kernel/run-store-locks.js

@@ -0,0 +1,180 @@
+// Concern (2): lock-file management. Atomic exclusive run/apply/cleanup lock acquisition,
+// lock reading with PID-liveness staleness, stale/corrupt lock clearing during reconcile,
+// and durable cancel/pause lifecycle request envelopes. Extracted from run-store-status.js
+// (opencode-workflows-nbp). Reads/writes the lock + lifecycle-request files under a run dir;
+// the RunContext properties it touches are limited to durable on-disk lock state (not the
+// in-memory run object). See {@link import("./run-context.js").RunContext}.
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DURABLE_STATE_VERSION } from "./constants.js";
+import { extractTextFromError } from "./text-json.js";
+import {
+  currentProcessInfo,
+  ensurePrivateDir,
+  processAppearsAlive,
+  readJsonFile,
+  writeFilePrivate,
+  writeJsonAtomic,
+} from "./run-store-fs.js";
+
+const RUN_LOCK_FILE = "run.lock";
+
+const APPLY_LOCK_FILE = "apply.lock";
+
+const CLEANUP_LOCK_FILE = ".cleanup.lock";
+
+const CANCEL_REQUEST_FILE = "cancel-request.json";
+
+const PAUSE_REQUEST_FILE = "pause-request.json";
+
+const KILL_REQUEST_FILE = "kill-request.json";
+
+function lockPathForRun(dir, operation) {
+  if (operation === "run") return path.join(dir, RUN_LOCK_FILE);
+  if (operation === "apply") return path.join(dir, APPLY_LOCK_FILE);
+  throw new Error(`Unknown workflow lock operation: ${operation}`);
+}
+
+function cleanupLockPath(root) {
+  return path.join(root, CLEANUP_LOCK_FILE);
+}
+
+async function readLock(lockPath) {
+  // Split reading from parsing. A failed READ (EACCES/EMFILE/ENFILE/EIO/EISDIR —
+  // plausible under this codebase's many concurrent lanes) tells us nothing about
+  // whether the lock's owner is alive, so it is classified `unreadable`, NOT
+  // `corrupt`. Only a genuine JSON.parse failure means the on-disk bytes are
+  // malformed (a partial write from a crash) — the one case reconcile may clear.
+  // If read errors were treated as corrupt, a transient FS hiccup at the wrong
+  // moment would let clearStaleRunLocks delete an actively-held lock.
+  let content;
+  try {
+    content = await fs.readFile(lockPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    return { path: lockPath, active: false, stale: false, unreadable: true, error: extractTextFromError(error) };
+  }
+  let metadata;
+  try {
+    metadata = JSON.parse(content);
+  } catch (error) {
+    return { path: lockPath, active: false, stale: false, corrupt: true, error: extractTextFromError(error) };
+  }
+  const active = await processAppearsAlive(metadata);
+  return { ...metadata, path: lockPath, active, stale: !active };
+}
+
+async function acquireWorkflowLock(lockPath, metadata) {
+  await ensurePrivateDir(path.dirname(lockPath));
+  const record = {
+    stateVersion: DURABLE_STATE_VERSION,
+    acquiredAt: new Date().toISOString(),
+    ...metadata,
+    process: await currentProcessInfo(),
+  };
+  // Lock creation must be atomic so a crash mid-write cannot leave a partial
+  // (corrupt) lock file that wedges the run. Write the full record to a temp
+  // file, then hard-link it into place: fs.link fails with EEXIST if the lock
+  // already exists, giving us atomic exclusive create with fully-written bytes.
+  const tmp = `${lockPath}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFilePrivate(tmp, JSON.stringify(record, null, 2), "utf8");
+    await fs.link(tmp, lockPath);
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      const existing = await readLock(lockPath);
+      const state = existing?.active ? "active" : existing?.stale ? "stale" : existing?.corrupt ? "corrupt" : "unreadable";
+      const recovery = (existing?.stale || existing?.corrupt)
+        ? "; run workflow_reconcile to clear stale/corrupt run locks"
+        : "";
+      throw new Error(`Workflow ${metadata.operation} lock is already held (${state}): ${lockPath}${recovery}`);
+    }
+    throw error;
+  } finally {
+    await fs.rm(tmp, { force: true });
+  }
+  return async () => {
+    const current = await readLock(lockPath);
+    if (current?.process?.pid === process.pid && current?.process?.startTime === record.process.startTime) {
+      await fs.rm(lockPath, { force: true });
+    }
+  };
+}
+
+async function runLocksForEntry(entry) {
+  const locks = {};
+  if (entry.kind !== "valid") return locks;
+  for (const [name, file] of Object.entries({ run: RUN_LOCK_FILE, apply: APPLY_LOCK_FILE })) {
+    const lock = await readLock(path.join(entry.dir, file));
+    if (lock) locks[name] = lock;
+  }
+  return locks;
+}
+
+async function clearStaleRunLocks(entry) {
+  if (entry.kind !== "valid") return [];
+  const cleared = [];
+  for (const [operation, file] of Object.entries({ run: RUN_LOCK_FILE, apply: APPLY_LOCK_FILE })) {
+    const lockPath = path.join(entry.dir, file);
+    const lock = await readLock(lockPath);
+    // A corrupt (partial-write) lock has no owning process we can ever match and
+    // is never released, so it would permanently wedge acquisition and block
+    // cleanup. Treat it like a stale lock and clear it during reconcile.
+    // An `unreadable` lock (transient read error — EACCES/EMFILE/EIO) is
+    // deliberately NOT cleared here: we could not read it, so it may still be
+    // actively held, and deleting it would let a second process resume the run.
+    if (lock?.stale || lock?.corrupt) {
+      await fs.rm(lockPath, { force: true });
+      cleared.push({ operation, path: lockPath, reason: lock?.corrupt ? "corrupt" : "stale" });
+    }
+  }
+  return cleared;
+}
+
+function lifecycleRequestPath(dir, type) {
+  if (type === "cancel") return path.join(dir, CANCEL_REQUEST_FILE);
+  if (type === "pause") return path.join(dir, PAUSE_REQUEST_FILE);
+  if (type === "kill") return path.join(dir, KILL_REQUEST_FILE);
+  throw new Error(`Unknown workflow lifecycle request type: ${type}`);
+}
+
+async function writeLifecycleRequest(dir, type, reason) {
+  const request = {
+    stateVersion: DURABLE_STATE_VERSION,
+    type,
+    requestedAt: new Date().toISOString(),
+    reason: reason || `${type} requested`,
+    process: await currentProcessInfo(),
+  };
+  await writeJsonAtomic(lifecycleRequestPath(dir, type), request);
+  return request;
+}
+
+async function readLifecycleRequests(dir) {
+  const requests = {};
+  for (const type of ["cancel", "pause", "kill"]) {
+    const request = await readJsonFile(lifecycleRequestPath(dir, type), undefined);
+    if (request) requests[type] = request;
+  }
+  return requests;
+}
+
+export {
+  RUN_LOCK_FILE,
+  APPLY_LOCK_FILE,
+  CLEANUP_LOCK_FILE,
+  CANCEL_REQUEST_FILE,
+  PAUSE_REQUEST_FILE,
+  KILL_REQUEST_FILE,
+  lockPathForRun,
+  cleanupLockPath,
+  readLock,
+  acquireWorkflowLock,
+  runLocksForEntry,
+  clearStaleRunLocks,
+  lifecycleRequestPath,
+  writeLifecycleRequest,
+  readLifecycleRequests,
+};