@hasna/workflows 0.1.2 → 0.1.4

package/dist/service.js

@@ -17,12 +17,12 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
 // src/lanes/types.ts
-import { statSync } from "fs";
+import { statSync as statSync2 } from "fs";
 function binaryOnPath(binary) {
   const pathEntries = (process.env.PATH ?? "").split(":").filter(Boolean);
   for (const entry of pathEntries) {
     try {
-      const stat = statSync(`${entry}/${binary}`);
+      const stat = statSync2(`${entry}/${binary}`);
       if (stat.isFile())
         return true;
     } catch {}
@@ -297,10 +297,12 @@ function createCursorAdapter(deps = {}) {
       try {
         const run = await withTimeout(runLocalAgent(sdk, job), timeoutMs, `cursor lane (${job.prompt.slice(0, 60)})`);
         const durationMs = Date.now() - started;
-        const status = run?.status ?? "finished";
+        const status = run.status;
         const ok = status === "finished";
-        return { ok, exitCode: ok ? 0 : 1, output: run?.result ?? "", durationMs };
+        return { ok, exitCode: ok ? 0 : 1, output: run.result, durationMs };
       } catch (err) {
+        if (err instanceof LaneAdapterShapeError)
+          throw err;
         const durationMs = Date.now() - started;
         return { ok: false, exitCode: 1, output: "", durationMs, error: String(err instanceof Error ? err.message : err) };
       }
@@ -321,7 +323,14 @@ async function runLocalAgent(sdk, job) {
   if (!run || typeof run !== "object") {
     throw new LaneAdapterShapeError("@cursor/sdk Agent.send() returned no Run");
   }
-  return run;
+  const candidate = run;
+  if (typeof candidate.status !== "string" || !["finished", "error", "cancelled"].includes(candidate.status)) {
+    throw new LaneAdapterShapeError(`@cursor/sdk Agent.send() returned a Run without a terminal status (got ${JSON.stringify(candidate.status)}; expected finished|error|cancelled)`);
+  }
+  if (typeof candidate.result !== "string") {
+    throw new LaneAdapterShapeError("@cursor/sdk Agent.send() returned a Run without a string result");
+  }
+  return { status: candidate.status, result: candidate.result };
 }
 function runCursorCli(job, cliPath, started, timeoutMs) {
   try {
@@ -439,13 +448,10 @@ var init_lanes = __esm(() => {
     ["grok", createGrokAdapter()]
   ]);
 });
-
-// src/service.ts
-import { join as join3 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/workflows",
-  version: "0.1.2",
+  version: "0.1.4",
   description: "Universal graph workflow app \u2014 graph language (start/step/decision/while/end), three-table store, session WAL, daemon with claims/leases, four lane adapters (claude/codex/cursor/grok), and a full CLI on four surfaces",
   type: "module",
   main: "./dist/index.js",
@@ -515,23 +521,21 @@ var package_default = {
   author: "Hasna",
   license: "Apache-2.0",
   dependencies: {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.234",
+    "@anthropic-ai/claude-agent-sdk": "0.3.234",
     "@cursor/sdk": "^1.0.28",
-    "@openai/codex-sdk": "^0.147.0",
+    "@hasna/paths": "0.1.0",
+    "@openai/codex-sdk": "0.147.0",
     commander: "^13.1.0"
   },
   devDependencies: {
-    "@hasna/contracts": "0.14.1",
-    "@types/bun": "latest",
+    "@hasna/contracts": "0.14.2",
+    "@types/bun": "1.3.14",
     "@types/pg": "^8.15.6",
     pg: "^8.16.3",
     typescript: "^5.7.3"
   }
 };
 
-// src/daemon.ts
-import { createHash as createHash2 } from "crypto";
-
 // src/expr.ts
 class ExprSyntaxError extends Error {
   constructor(message) {
@@ -905,6 +909,18 @@ function validateGraph(graph) {
   if (typeof graph.version !== "string" || graph.version.trim() === "") {
     issue(issues, "version", "graph requires a version string");
   }
+  if (graph.memoWatch !== undefined) {
+    if (!Array.isArray(graph.memoWatch) || graph.memoWatch.length === 0) {
+      issue(issues, "memoWatch", "memoWatch must be a non-empty array of file paths or globs");
+    } else {
+      for (const entry of graph.memoWatch) {
+        if (typeof entry !== "string" || entry.trim() === "") {
+          issue(issues, "memoWatch", "each memoWatch entry must be a non-empty path or glob string");
+          break;
+        }
+      }
+    }
+  }
   if (!Array.isArray(graph.nodes) || graph.nodes.length === 0) {
     issue(issues, "nodes", "graph requires at least one node");
     return { ok: false, issues };
@@ -1139,6 +1155,8 @@ function assertNoSecrets(value, what) {
 
 // src/session.ts
 import { createHash } from "crypto";
+import { readFileSync, statSync } from "fs";
+import { isAbsolute, join } from "path";
 var DEFAULT_MAX_ATTEMPTS = 3;
 function repairTornRuns(store, wal, opts = {}) {
   const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
@@ -1194,6 +1212,46 @@ function recordMemo(store, graphName, nodeId, input, output) {
   const key = memoKey(graphName, nodeId, input);
   store.memoPut(key, graphName, nodeId, inputHash(input), JSON.stringify(output));
 }
+function memoWatchFingerprint(graph, dataDir) {
+  if (!graph.memoWatch || graph.memoWatch.length === 0)
+    return;
+  const entries = [];
+  for (const pattern of graph.memoWatch) {
+    if (hasGlobMagic(pattern)) {
+      const matches = [...new Bun.Glob(pattern).scanSync({ cwd: dataDir, onlyFiles: true })].sort();
+      for (const match of matches) {
+        const path2 = isAbsolute(match) ? match : join(dataDir, match);
+        entries.push(fingerprintFile(pattern, path2));
+      }
+      continue;
+    }
+    const path = isAbsolute(pattern) ? pattern : join(dataDir, pattern);
+    entries.push(fingerprintFile(pattern, path));
+  }
+  return entries;
+}
+function hasGlobMagic(pattern) {
+  return /[*?[\]{}]/.test(pattern);
+}
+function fingerprintFile(pattern, path) {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile()) {
+      return { pattern, path, missing: true, mtimeMs: null, size: null, sha256: null };
+    }
+    const content = readFileSync(path);
+    return {
+      pattern,
+      path,
+      missing: false,
+      mtimeMs: stat.mtimeMs,
+      size: content.byteLength,
+      sha256: createHash("sha256").update(content).digest("hex")
+    };
+  } catch {
+    return { pattern, path, missing: true, mtimeMs: null, size: null, sha256: null };
+  }
+}
 function findRunByIdempotencyKey(store, key) {
   const runs = store.listRuns({ limit: 1000 });
   for (const run of runs) {
@@ -1468,10 +1526,13 @@ class WorkflowsDaemon {
   }
   async executeStep(run, graph, context, wf, node) {
     const nodeId = node.id;
-    const existing = this.store.listRunNodes(run.id).find((n) => n.nodeId === nodeId);
-    const nodeRow = existing ?? this.store.createRunNode({ runId: run.id, nodeId, lane: node.lane ?? "claude" });
-    if (node.memo) {
-      const memoInput = { command: node.command, prompt: node.prompt, context: stripRunState(context) };
+    const latest = this.store.getLatestRunNode(run.id, nodeId);
+    const isLoopBody = graph.nodes.some((candidate) => candidate.type === "while" && candidate.body.includes(nodeId));
+    const nodeRow = latest === undefined || isLoopBody && latest.status === "completed" ? this.store.createRunNode({ runId: run.id, nodeId, lane: node.lane ?? "claude" }) : latest;
+    const memoWatch = node.memo ? memoWatchFingerprint(graph, this.store.dataDir) : undefined;
+    const memoSource = { command: node.command, prompt: node.prompt, context: stripRunState(context) };
+    const memoInput = node.memo ? memoWatch !== undefined ? { ...memoSource, memoWatch } : memoSource : undefined;
+    if (memoInput !== undefined) {
       const hit = tryMemoHit(this.store, run.graphName, nodeId, memoInput);
       if (hit) {
         const cached = JSON.parse(hit.outputJson);
@@ -1500,9 +1561,9 @@ class WorkflowsDaemon {
     }
     const output = { ok: result.ok, exitCode: result.exitCode, output: result.output, durationMs: result.durationMs };
     if (!result.ok) {
-      const retriesLeft = (node.maxRetries ?? 0) + 1 - nodeRow.attempts;
-      if (retriesLeft > 0) {
-        this.store.bumpAttemptsNode(nodeRow.id);
+      const shouldRetry = nodeRow.attempts < (node.maxRetries ?? 0);
+      this.store.bumpAttemptsNode(nodeRow.id);
+      if (shouldRetry) {
         this.store.setRunNodeStatus(nodeRow.id, "pending", { error: result.error ?? `exit ${result.exitCode}` });
         return { kind: "advanced", nodeId };
       }
@@ -1523,9 +1584,13 @@ class WorkflowsDaemon {
     }
     this.store.setRunNodeStatus(nodeRow.id, "completed", { exitCode: result.exitCode, output });
     this.wal.append({ op: "node_finished", runId: run.id, nodeId, status: "completed", at: nowIso() });
-    if (node.memo) {
-      recordMemo(this.store, run.graphName, nodeId, { command: node.command, prompt: node.prompt, context: stripRunState(context) }, output);
-      this.wal.append({ op: "memo_set", key: `${run.graphName}:${nodeId}:${createHash2("sha256").update(JSON.stringify({ command: node.command, prompt: node.prompt, context: stripRunState(context) })).digest("hex")}`, at: nowIso() });
+    if (memoInput !== undefined) {
+      const memoInputAfter = node.memo ? memoWatchFingerprint(graph, this.store.dataDir) : undefined;
+      const stable = memoWatch === undefined && memoInputAfter === undefined || memoWatch !== undefined && memoInputAfter !== undefined && JSON.stringify(memoWatch) === JSON.stringify(memoInputAfter);
+      if (stable) {
+        recordMemo(this.store, run.graphName, nodeId, memoInput, output);
+        this.wal.append({ op: "memo_set", key: memoKey(run.graphName, nodeId, memoInput), at: nowIso() });
+      }
     }
     this.recordStepResult(context, nodeId, output);
     return this.afterNode(run, context, wf, node.next);
@@ -1620,6 +1685,7 @@ async function runGraphToCompletion(store, wal, graph, context, options = {}) {
     isolatedRunId: options.isolatedRunId
   });
   const run = daemon.startRun(graph, context);
+  options.onRunCreated?.(run);
   daemon.isolateRun(run.id);
   const maxCycles = options.maxCycles ?? 500;
   for (let cycle = 0;cycle < maxCycles; cycle++) {
@@ -1634,20 +1700,71 @@ async function runGraphToCompletion(store, wal, graph, context, options = {}) {
   return store.getRun(run.id);
 }
 
+// src/paths.ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { dataDir } from "@hasna/paths";
+var APP = "workflows";
+var STORE_DB_FILE = "workflows.db";
+function getHomeDir(env = process.env) {
+  return env["HOME"] || env["USERPROFILE"] || homedir();
+}
+function getLegacyDataDir(env = process.env) {
+  return join2(getHomeDir(env), ".hasna", APP);
+}
+function getResolverDataDir(env = process.env) {
+  return dataDir({ app: APP, home: getHomeDir(env), env });
+}
+function adoptResolverDataDir(resolved, env = process.env) {
+  const dataOverride = env.HASNA_DATA_HOME;
+  if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
+    return true;
+  return existsSync(join2(resolved, STORE_DB_FILE));
+}
+function getEffectiveDataDir(env = process.env) {
+  const resolved = getResolverDataDir(env);
+  return adoptResolverDataDir(resolved, env) ? resolved : getLegacyDataDir(env);
+}
+
 // src/store.ts
 import { Database } from "bun:sqlite";
 import { mkdirSync } from "fs";
-import { join } from "path";
+import { join as join3 } from "path";
 import { randomUUID } from "crypto";
 function nowIso2() {
   return new Date().toISOString();
 }
-function openStore(dataDir) {
-  mkdirSync(dataDir, { recursive: true });
-  const db = new Database(join(dataDir, "workflows.db"));
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA foreign_keys = ON");
-  db.exec(`
+var BUSY_TIMEOUT_MS = 3000;
+var BUSY_RETRIES = 2;
+var BUSY_RETRY_SLEEP_MS = 50;
+function isBusyError(err) {
+  if (!(err instanceof Error))
+    return false;
+  const code = String(err.code ?? "");
+  return code.includes("BUSY") || /\bdatabase is locked\b/i.test(err.message);
+}
+function retryBusy(fn) {
+  let last;
+  for (let attempt = 0;attempt <= BUSY_RETRIES; attempt++) {
+    try {
+      return fn();
+    } catch (err) {
+      if (!isBusyError(err))
+        throw err;
+      last = err;
+      Bun.sleepSync(BUSY_RETRY_SLEEP_MS);
+    }
+  }
+  throw last;
+}
+function openStore(dataDir2) {
+  mkdirSync(dataDir2, { recursive: true });
+  const db = new Database(join3(dataDir2, "workflows.db"));
+  retryBusy(() => db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`));
+  retryBusy(() => db.exec("PRAGMA journal_mode = WAL"));
+  retryBusy(() => db.exec("PRAGMA foreign_keys = ON"));
+  retryBusy(() => db.exec(`
     CREATE TABLE IF NOT EXISTS runs (
       id            TEXT PRIMARY KEY,
       graph_name    TEXT NOT NULL,
@@ -1687,7 +1804,7 @@ function openStore(dataDir) {
     CREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);
     CREATE INDEX IF NOT EXISTS idx_runs_created ON runs(created_at);
     CREATE INDEX IF NOT EXISTS idx_run_nodes_run ON run_nodes(run_id);
-  `);
+  `));
   const rowToRun = (r) => ({
     id: String(r.id),
     graphName: String(r.graph_name),
@@ -1725,31 +1842,33 @@ function openStore(dataDir) {
     createdAt: String(r.created_at)
   });
   return {
+    dataDir: dataDir2,
     close() {
       db.close();
     },
     listTables() {
-      const rows = db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
+      const rows = retryBusy(() => db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all());
       return rows.map((r) => r.name);
     },
     createRun(input) {
       const id = randomUUID();
       const now = nowIso2();
-      db.query(`INSERT INTO runs (id, graph_name, graph_version, status, attempts, context_json, created_at, updated_at)
-         VALUES (?, ?, ?, 'pending', 0, ?, ?, ?)`).run(id, input.graphName, input.graphVersion, JSON.stringify(input.context ?? {}), now, now);
+      retryBusy(() => db.query(`INSERT INTO runs (id, graph_name, graph_version, status, attempts, context_json, created_at, updated_at)
+             VALUES (?, ?, ?, 'pending', 0, ?, ?, ?)`).run(id, input.graphName, input.graphVersion, JSON.stringify(input.context ?? {}), now, now));
       return this.getRun(id);
     },
     getRun(id) {
-      const row = db.query(`SELECT * FROM runs WHERE id = ?`).get(id);
+      const row = retryBusy(() => db.query(`SELECT * FROM runs WHERE id = ?`).get(id));
       return row ? rowToRun(row) : undefined;
     },
     listRuns(opts = {}) {
       const limit = Math.min(opts.limit ?? 100, 1000);
       if (opts.status) {
-        const rows2 = db.query(`SELECT * FROM runs WHERE status = ? ORDER BY created_at DESC, id DESC LIMIT ?`).all(opts.status, limit);
+        const status = opts.status;
+        const rows2 = retryBusy(() => db.query(`SELECT * FROM runs WHERE status = ? ORDER BY created_at DESC, id DESC LIMIT ?`).all(status, limit));
         return rows2.map((r) => rowToRun(r));
       }
-      const rows = db.query(`SELECT * FROM runs ORDER BY created_at DESC, id DESC LIMIT ?`).all(limit);
+      const rows = retryBusy(() => db.query(`SELECT * FROM runs ORDER BY created_at DESC, id DESC LIMIT ?`).all(limit));
       return rows.map((r) => rowToRun(r));
     },
     setRunStatus(id, status, patch = {}) {
@@ -1760,28 +1879,32 @@ function openStore(dataDir) {
       const startedAt = patch.startedAt !== undefined ? patch.startedAt : status === "running" && existing?.startedAt === null ? now : existing?.startedAt ?? null;
       const terminal = status === "completed" || status === "failed" || status === "cancelled" || status === "interrupted";
       const finishedAt = patch.finishedAt !== undefined ? patch.finishedAt : terminal && existing?.finishedAt === null ? now : existing?.finishedAt ?? null;
-      db.query(`UPDATE runs SET status = ?, result_json = ?, error = ?, started_at = ?, finished_at = ?, updated_at = ? WHERE id = ?`).run(status, resultJson, error, startedAt, finishedAt, now, id);
+      retryBusy(() => db.query(`UPDATE runs SET status = ?, result_json = ?, error = ?, started_at = ?, finished_at = ?, updated_at = ? WHERE id = ?`).run(status, resultJson, error, startedAt, finishedAt, now, id));
     },
     bumpAttempts(id) {
-      db.query(`UPDATE runs SET attempts = attempts + 1, updated_at = ? WHERE id = ?`).run(nowIso2(), id);
+      retryBusy(() => db.query(`UPDATE runs SET attempts = attempts + 1, updated_at = ? WHERE id = ?`).run(nowIso2(), id));
     },
     setRunContext(id, context) {
-      db.query(`UPDATE runs SET context_json = ?, updated_at = ? WHERE id = ?`).run(JSON.stringify(context), nowIso2(), id);
+      retryBusy(() => db.query(`UPDATE runs SET context_json = ?, updated_at = ? WHERE id = ?`).run(JSON.stringify(context), nowIso2(), id));
     },
     createRunNode(input) {
       const id = randomUUID();
-      db.query(`INSERT INTO run_nodes (id, run_id, node_id, status, attempts, lane)
-         VALUES (?, ?, ?, 'pending', 0, ?)`).run(id, input.runId, input.nodeId, input.lane ?? null);
+      retryBusy(() => db.query(`INSERT INTO run_nodes (id, run_id, node_id, status, attempts, lane)
+             VALUES (?, ?, ?, 'pending', 0, ?)`).run(id, input.runId, input.nodeId, input.lane ?? null));
       return this.getRunNode(id);
     },
     getRunNode(id) {
-      const row = db.query(`SELECT * FROM run_nodes WHERE id = ?`).get(id);
+      const row = retryBusy(() => db.query(`SELECT * FROM run_nodes WHERE id = ?`).get(id));
       return row ? rowToNode(row) : undefined;
     },
     listRunNodes(runId) {
-      const rows = db.query(`SELECT * FROM run_nodes WHERE run_id = ? ORDER BY rowid ASC`).all(runId);
+      const rows = retryBusy(() => db.query(`SELECT * FROM run_nodes WHERE run_id = ? ORDER BY rowid ASC`).all(runId));
       return rows.map((r) => rowToNode(r));
     },
+    getLatestRunNode(runId, nodeId) {
+      const row = retryBusy(() => db.query(`SELECT * FROM run_nodes WHERE run_id = ? AND node_id = ? ORDER BY rowid DESC LIMIT 1`).get(runId, nodeId));
+      return row ? rowToNode(row) : undefined;
+    },
     setRunNodeStatus(id, status, patch = {}) {
       const now = nowIso2();
       const existing = this.getRunNode(id);
@@ -1793,44 +1916,44 @@ function openStore(dataDir) {
       const startedAt = patch.startedAt !== undefined ? patch.startedAt : status === "running" && existing.startedAt === null ? now : existing.startedAt;
       const terminal = status === "completed" || status === "failed" || status === "skipped";
       const finishedAt = patch.finishedAt !== undefined ? patch.finishedAt : terminal && existing.finishedAt === null ? now : existing.finishedAt;
-      db.query(`UPDATE run_nodes SET status = ?, exit_code = ?, output_json = ?, error = ?, started_at = ?, finished_at = ? WHERE id = ?`).run(status, exitCode, outputJson, error, startedAt, finishedAt, id);
+      retryBusy(() => db.query(`UPDATE run_nodes SET status = ?, exit_code = ?, output_json = ?, error = ?, started_at = ?, finished_at = ? WHERE id = ?`).run(status, exitCode, outputJson, error, startedAt, finishedAt, id));
     },
     bumpAttemptsNode(id) {
-      db.query(`UPDATE run_nodes SET attempts = attempts + 1 WHERE id = ?`).run(id);
+      retryBusy(() => db.query(`UPDATE run_nodes SET attempts = attempts + 1 WHERE id = ?`).run(id));
     },
     memoPut(key, graphName, nodeId, inputHash2, outputJson) {
-      db.query(`INSERT INTO memos (key, graph_name, node_id, input_hash, output_json, hit_count, created_at)
-         VALUES (?, ?, ?, ?, ?, 0, ?)
-         ON CONFLICT(key) DO UPDATE SET output_json = excluded.output_json`).run(key, graphName, nodeId, inputHash2, outputJson, nowIso2());
+      retryBusy(() => db.query(`INSERT INTO memos (key, graph_name, node_id, input_hash, output_json, hit_count, created_at)
+             VALUES (?, ?, ?, ?, ?, 0, ?)
+             ON CONFLICT(key) DO UPDATE SET output_json = excluded.output_json`).run(key, graphName, nodeId, inputHash2, outputJson, nowIso2()));
     },
     memoGet(key) {
-      const row = db.query(`SELECT * FROM memos WHERE key = ?`).get(key);
+      const row = retryBusy(() => db.query(`SELECT * FROM memos WHERE key = ?`).get(key));
       return row ? rowToMemo(row) : undefined;
     },
     memoHit(key) {
-      db.query(`UPDATE memos SET hit_count = hit_count + 1 WHERE key = ?`).run(key);
+      retryBusy(() => db.query(`UPDATE memos SET hit_count = hit_count + 1 WHERE key = ?`).run(key));
     },
     memoList() {
-      const rows = db.query(`SELECT * FROM memos ORDER BY created_at DESC LIMIT 1000`).all();
+      const rows = retryBusy(() => db.query(`SELECT * FROM memos ORDER BY created_at DESC LIMIT 1000`).all());
       return rows.map((r) => rowToMemo(r));
     },
     memoClear() {
-      db.exec(`DELETE FROM memos`);
+      retryBusy(() => db.exec(`DELETE FROM memos`));
     }
   };
 }
 
 // src/wal.ts
-import { createHash as createHash3 } from "crypto";
-import { appendFileSync, existsSync, mkdirSync as mkdirSync2, readFileSync, renameSync, truncateSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
+import { createHash as createHash2 } from "crypto";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, truncateSync, writeFileSync } from "fs";
+import { join as join4 } from "path";
 var WAL_FILE_NAME = "session.wal";
 var SESSIONS_DIR_NAME = "sessions";
 var MAX_WAL_BYTES = 256 * 1024 * 1024;
 function checksumOf(op) {
   if (op === undefined || op === null)
     return "";
-  return createHash3("sha256").update(JSON.stringify(op)).digest("hex");
+  return createHash2("sha256").update(JSON.stringify(op)).digest("hex");
 }
 
 class SessionWAL {
@@ -1838,11 +1961,11 @@ class SessionWAL {
   constructor(filePath) {
     this.filePath = filePath;
   }
-  static open(dataDir) {
-    mkdirSync2(join2(dataDir, SESSIONS_DIR_NAME), { recursive: true });
-    const canonical = join2(dataDir, SESSIONS_DIR_NAME, WAL_FILE_NAME);
-    const legacy = join2(dataDir, WAL_FILE_NAME);
-    if (existsSync(legacy) && !existsSync(canonical)) {
+  static open(dataDir2) {
+    mkdirSync2(join4(dataDir2, SESSIONS_DIR_NAME), { recursive: true });
+    const canonical = join4(dataDir2, SESSIONS_DIR_NAME, WAL_FILE_NAME);
+    const legacy = join4(dataDir2, WAL_FILE_NAME);
+    if (existsSync2(legacy) && !existsSync2(canonical)) {
       try {
         renameSync(legacy, canonical);
       } catch {
@@ -1873,7 +1996,7 @@ class SessionWAL {
     let repaired = false;
     let content;
     try {
-      content = readFileSync(this.filePath, "utf8");
+      content = readFileSync2(this.filePath, "utf8");
     } catch {
       return { entries, torn, repaired, liveClaims: () => new Map };
     }
@@ -1973,11 +2096,10 @@ function envInt(names, fallback) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 function resolveWorkflowsConfig(overrides = {}) {
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? ".";
   return {
     port: overrides.port ?? envInt(["HASNA_WORKFLOWS_PORT", "WORKFLOWS_PORT"], DEFAULT_PORT),
     host: overrides.host ?? envString(["HASNA_WORKFLOWS_HOST", "WORKFLOWS_HOST"]) ?? DEFAULT_HOST,
-    dataDir: overrides.dataDir ?? envString(["HASNA_WORKFLOWS_DATA_DIR", "WORKFLOWS_DATA_DIR"]) ?? join3(home, ".hasna", "workflows"),
+    dataDir: overrides.dataDir ?? envString(["HASNA_WORKFLOWS_DATA_DIR", "WORKFLOWS_DATA_DIR"]) ?? getEffectiveDataDir(),
     apiUrl: overrides.apiUrl ?? envString(["WORKFLOWS_API_URL"]),
     apiKey: overrides.apiKey ?? envString(["WORKFLOWS_API_KEY"])
   };

package/hasna.contract.json

@@ -3,8 +3,8 @@
   "name": "workflows",
   "class": "service",
   "contractVersion": "v1",
-  "kitVersion": "0.14.1",
-  "description": "Universal graph workflow app: graph language (start/step/decision/while/end), three-table run store, session WAL, claims/leases daemon, four lane adapters (claude, codex, cursor, grok), and a full CLI on four surfaces (CLI, MCP, serve, SDK).",
+  "kitVersion": "0.14.2",
+  "description": "Universal graph workflow app: graph language (start/step/decision/while/end), three-table run store, session WAL, claims/leases daemon, four lane adapters (claude, codex, cursor, grok), and a full CLI on four surfaces (CLI, MCP, serve, SDK). Local state lives at the effective workflows data home (~/.hasna/workflows by default, resolved via @hasna/paths; the XDG data home is adopted once the store is migrated there or HASNA_DATA_HOME is set).",
   "bins": [
     "workflows",
     "workflows-mcp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/workflows",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Universal graph workflow app — graph language (start/step/decision/while/end), three-table store, session WAL, daemon with claims/leases, four lane adapters (claude/codex/cursor/grok), and a full CLI on four surfaces",
   "type": "module",
   "main": "./dist/index.js",
@@ -70,14 +70,15 @@
   "author": "Hasna",
   "license": "Apache-2.0",
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.234",
+    "@anthropic-ai/claude-agent-sdk": "0.3.234",
     "@cursor/sdk": "^1.0.28",
-    "@openai/codex-sdk": "^0.147.0",
+    "@hasna/paths": "0.1.0",
+    "@openai/codex-sdk": "0.147.0",
     "commander": "^13.1.0"
   },
   "devDependencies": {
-    "@hasna/contracts": "0.14.1",
-    "@types/bun": "latest",
+    "@hasna/contracts": "0.14.2",
+    "@types/bun": "1.3.14",
     "@types/pg": "^8.15.6",
     "pg": "^8.16.3",
     "typescript": "^5.7.3"

package/types/daemon.d.ts

@@ -114,6 +114,9 @@ export interface RunToCompletionOptions {
     /** Pre-set the daemon's isolation; the foreground driver always isolates
      * to its own run anyway (see isolateRun in runGraphToCompletion). */
     isolatedRunId?: string;
+    /** Observe the durable run identity immediately after creation (the CLI -j
+     * failure surface needs the runId even when the run later throws). */
+    onRunCreated?: (run: RunRow) => void;
 }
 /** Drive a run to a terminal state with bounded cycles. Returns the final row. */
 export declare function runGraphToCompletion(store: WorkflowsStore, wal: SessionWAL, graph: WorkflowGraph, context: unknown, options?: RunToCompletionOptions): Promise<RunRow>;

package/types/graph.d.ts

@@ -53,6 +53,13 @@ export interface WorkflowGraph {
     name: string;
     version: string;
     nodes: GraphNode[];
+    /**
+     * Optional files/globs (relative to the data dir, or absolute) whose
+     * fingerprint (mtime + sha256) joins every memoized node's input.
+     * A memoized command that reads external state MUST declare it here, or
+     * it can serve a stale cached value that contradicts a live run.
+     */
+    memoWatch?: string[];
 }
 export interface GraphIssue {
     /** Dotted path to the offending member, e.g. "nodes.build" or "nodes.w.body". */

package/types/paths.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Workflows data-home resolution — the effective local data home for the
+ * @hasna/workflows package, resolved through @hasna/paths.
+ *
+ * Resolution order:
+ *   1. exact-app override — `HASNA_WORKFLOWS_DATA_DIR` / `WORKFLOWS_DATA_DIR`
+ *      (the shipped overrides, applied in `resolveWorkflowsConfig`) — wins
+ *      unconditionally;
+ *   2. the @hasna/paths data home (XDG / macOS home layout) once adopted;
+ *   3. otherwise the legacy `~/.hasna/workflows` default.
+ *
+ * Gated legacy adoption: the legacy `~/.hasna/workflows` home stays effective
+ * until the store has actually been migrated to the XDG data home
+ * (`workflows.db` exists at the resolver home) or the operator sets the
+ * data-kind override `HASNA_DATA_HOME`. An existing local store never becomes
+ * invisible on upgrade.
+ */
+/** The workflows app slug used by the @hasna/paths resolver. */
+export declare const APP: "workflows";
+/** The store database file name, the marker that a store lives at a data home. */
+export declare const STORE_DB_FILE = "workflows.db";
+/**
+ * The effective user home, mirroring the pre-existing resolution
+ * (`HOME` || `USERPROFILE` || os.homedir()).
+ */
+export declare function getHomeDir(env?: NodeJS.ProcessEnv): string;
+/** Pre-XDG legacy workflows data home: ~/.hasna/workflows. */
+export declare function getLegacyDataDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * The @hasna/paths-resolved workflows data home (XDG / macOS home layout):
+ * `~/.local/share/hasna/workflows` on Linux, `~/Library/Application
+ * Support/Hasna/workflows` on macOS. The home override mirrors the
+ * pre-existing `$HOME`-first resolution so the resolver follows the same home
+ * the legacy path does.
+ */
+export declare function getResolverDataDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Whether the resolver (XDG) data home should be adopted as the effective
+ * workflows data home. The resolver home is adopted only when the operator
+ * has set `HASNA_DATA_HOME` (the data-kind override — a deliberate opt-in to
+ * the XDG layout) or the store has already been physically migrated there
+ * (`workflows.db` exists). A machine that only redirects another kind (e.g.
+ * cache to tmpfs) must NOT have its data home moved, and a live store at the
+ * legacy home must never become invisible on upgrade.
+ */
+export declare function adoptResolverDataDir(resolved: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The effective workflows data home: the resolver home once adopted,
+ * otherwise the legacy `~/.hasna/workflows` default.
+ */
+export declare function getEffectiveDataDir(env?: NodeJS.ProcessEnv): string;

package/types/session.d.ts

@@ -1,5 +1,6 @@
 import { SessionWAL } from "./wal.js";
 import type { RunRow, WorkflowsStore } from "./store.js";
+import type { WorkflowGraph } from "./graph.js";
 export interface RepairResult {
     /** runs found running with no live claim */
     interrupted: number;
@@ -21,6 +22,29 @@ export declare function memoKey(graphName: string, nodeId: string, input: unknow
 export declare function tryMemoHit(store: WorkflowsStore, graphName: string, nodeId: string, input: unknown): import("./store.js").MemoRow | undefined;
 /** Persist a node output for future runs with the same input. */
 export declare function recordMemo(store: WorkflowsStore, graphName: string, nodeId: string, input: unknown, output: unknown): void;
+/** One watched file's fingerprint entry (mtime + sha256). */
+export interface MemoWatchEntry {
+    /** The pattern as declared on the graph. */
+    pattern: string;
+    /** The resolved absolute path (or the glob-relative file path). */
+    path: string;
+    missing: boolean;
+    mtimeMs: number | null;
+    size: number | null;
+    sha256: string | null;
+}
+/**
+ * Fingerprint of the graph's memoWatch files: mtimes + content hashes.
+ * Stress V3/V4 F2 (measured 2026-08-30): a memoized node reading
+ * $WORKFLOWS_DATA_DIR/scratch/wf2.cnt served a stale cached "0" while the
+ * file said "2" — the memo key covered only {command, prompt, context}. The
+ * fingerprint joins the memo input, so a changed watched file invalidates the
+ * cache exactly when the command's live result can differ. Exact paths and
+ * glob patterns are supported (relative to `dataDir` or absolute); a missing
+ * exact path keeps a stable `missing` entry so its later appearance (or a
+ * re-creation with different content) still changes the fingerprint.
+ */
+export declare function memoWatchFingerprint(graph: WorkflowGraph, dataDir: string): MemoWatchEntry[] | undefined;
 /** Requeue a cancelled run's in-flight nodes (used by cancel + resume). */
 export declare function resetRunNodes(store: WorkflowsStore, run: RunRow): void;
 export interface RestoreResult {

package/types/store.d.ts

@@ -49,6 +49,8 @@ export interface CreateRunNodeInput {
     lane?: string;
 }
 export interface WorkflowsStore {
+    /** The data dir this store was opened on (resolves relative memoWatch paths). */
+    readonly dataDir: string;
     close(): void;
     listTables(): string[];
     createRun(input: CreateRunInput): RunRow;
@@ -69,6 +71,9 @@ export interface WorkflowsStore {
     createRunNode(input: CreateRunNodeInput): RunNodeRow;
     getRunNode(id: string): RunNodeRow | undefined;
     listRunNodes(runId: string): RunNodeRow[];
+    /** The newest run_nodes row for a (run, node) pair — a node may own one row
+     * per while iteration, and `nodes show` + engine row-reuse need the latest. */
+    getLatestRunNode(runId: string, nodeId: string): RunNodeRow | undefined;
     setRunNodeStatus(id: string, status: NodeStatus, patch?: {
         exitCode?: number | null;
         output?: unknown;