elanous 0.2.0 → 0.2.5

package/src/graph-kinds/installed-plugin-nodes.ts

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { listInstalledPlugins, type InstalledPlugin } from '../plugins/install/plugin-install.js';
+import { loadPluginManifestFromDir, type PluginManifest } from '../plugins/core/manifest.js';
+import { loadPluginNodes } from './plugin-nodes.js';
+import { getNodeKindRegistration, listNodeKinds, unregisterPluginNodeKind, type GraphKind, type NodeKindEntry } from './registry.js';
+
+export interface InstalledPluginNodeSyncResult {
+  registered: number;
+  removed: number;
+  errors: Array<{ plugin: string; reason: string }>;
+}
+
+type OwnedNode = { graph: GraphKind; kind: string; plugin: string; registered: NodeKindEntry };
+type InstalledNodeState = { stamp: string; owned: Map<string, { fingerprint: string; nodes: OwnedNode[] }> };
+const states = new Map<string, InstalledNodeState>();
+
+function fingerprint(item: InstalledPlugin, manifest: PluginManifest): string {
+  const root = realpathSync(item.path);
+  const hash = createHash('sha256');
+  hash.update(JSON.stringify([item.name, item.version, item.market, item.sha256, item.installedAt, manifest]));
+  for (const path of manifest.contributes.nodes ?? []) {
+    const file = realpathSync(resolve(root, path));
+    const rel = relative(root, file);
+    if (!path.startsWith('./') || !rel || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) {
+      throw new Error(`node path must remain inside the plugin dir: ${path}`);
+    }
+    hash.update(path);
+    hash.update(readFileSync(file));
+  }
+  return hash.digest('hex');
+}
+
+/** Reconcile only registrations made by this sync; the registry's identity check protects other owners. */
+export function syncInstalledPluginNodes(root: string): InstalledPluginNodeSyncResult {
+  const result: InstalledPluginNodeSyncResult = { registered: 0, removed: 0, errors: [] };
+  const stateRoot = resolve(root);
+  const ledger = statSync(join(stateRoot, 'plugins', 'installed.json'), { throwIfNoEntry: false, bigint: true });
+  // The installer atomically replaces the ledger, so mtime and size alone can
+  // coincide across installs. File identity and ctime detect that replacement.
+  const stamp = ledger ? `${ledger.dev}:${ledger.ino}:${ledger.ctimeNs}:${ledger.mtimeNs}:${ledger.size}` : 'missing';
+  const previous = states.get(stateRoot);
+  if (previous?.stamp === stamp) return result;
+
+  // The installer commits a new ledger via rename after the package directory is in place.
+  // If discovery itself fails, the stamp is not advanced and the next request retries.
+  const installed = listInstalledPlugins(stateRoot);
+  const current = new Set(installed.map(item => item.path));
+  const owned = previous?.owned ?? new Map<string, { fingerprint: string; nodes: OwnedNode[] }>();
+  const removeOwned = (path: string): void => {
+    for (const node of owned.get(path)?.nodes ?? []) {
+      if (unregisterPluginNodeKind(node.graph, node.kind, node.plugin, node.registered)) result.removed++;
+    }
+    owned.delete(path);
+  };
+  for (const path of owned.keys()) {
+    if (!current.has(path)) removeOwned(path);
+  }
+
+  for (const item of installed) {
+    try {
+      const manifest = loadPluginManifestFromDir(item.path, { id: item.name }).manifest;
+      if (!manifest.contributes.nodes?.length) {
+        removeOwned(item.path);
+        continue;
+      }
+      const version = fingerprint(item, manifest);
+      if (owned.get(item.path)?.fingerprint === version) continue;
+      removeOwned(item.path);
+      const before = new Set(listNodeKinds().filter(entry => entry.plugin === manifest.id).map(entry => `${entry.graph}:${entry.kind}`));
+      const loaded = loadPluginNodes(item.path, manifest);
+      const nodes: OwnedNode[] = [];
+      for (const entry of listNodeKinds().filter(entry => entry.plugin === manifest.id && !before.has(`${entry.graph}:${entry.kind}`))) {
+        const registered = getNodeKindRegistration(entry.graph, entry.kind);
+        if (registered) nodes.push({ graph: entry.graph, kind: entry.kind, plugin: manifest.id, registered });
+      }
+      if (loaded.errors.length) {
+        for (const node of nodes) unregisterPluginNodeKind(node.graph, node.kind, node.plugin, node.registered);
+        result.errors.push({ plugin: item.name, reason: loaded.errors.join('; ') });
+        owned.set(item.path, { fingerprint: version, nodes: [] });
+        continue;
+      }
+      result.registered += nodes.length;
+      owned.set(item.path, { fingerprint: version, nodes });
+    } catch (error) {
+      removeOwned(item.path);
+      result.errors.push({ plugin: item.name, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  states.set(stateRoot, { stamp, owned });
+  debug.log('graph.kinds', 'installed-sync', { root: stateRoot, ...result });
+  return result;
+}

package/src/graph-kinds/plugin-nodes.ts

@@ -0,0 +1,68 @@
+import { readFileSync, realpathSync } from 'fs';
+import { isAbsolute, relative, resolve } from 'path';
+import { parse } from 'yaml';
+import type { PluginManifest } from '../plugins/core/manifest.js';
+import { registerNodeKind, type GraphKind, type NodeKindRun } from './registry.js';
+
+export interface PluginNodeLoadResult {
+  errors: string[];
+}
+
+/** Load declarative node kinds independently: a broken YAML cannot hide a sibling definition. */
+export function loadPluginNodes(pluginDir: string, manifest: PluginManifest): PluginNodeLoadResult {
+  const result: PluginNodeLoadResult = { errors: [] };
+  for (const path of manifest.contributes.nodes ?? []) {
+    try {
+      const root = realpathSync(pluginDir);
+      const file = realpathSync(resolve(root, path));
+      const rel = relative(root, file);
+      if (!path.startsWith('./') || !rel || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) {
+        throw new Error('node path must remain inside the plugin dir');
+      }
+      const raw: unknown = parse(readFileSync(file, 'utf8'));
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('node must be an object');
+      const node = raw as Record<string, unknown>;
+      if (typeof node.kind !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(node.kind)) {
+        throw new Error('kind must be a kebab-case name');
+      }
+      if (node.graph !== 'workflow' && node.graph !== 'harness') throw new Error('graph must be workflow or harness');
+      if (!node.inputs || typeof node.inputs !== 'object' || Array.isArray(node.inputs)
+        || (node.inputs as Record<string, unknown>).type !== 'object') {
+        throw new Error('inputs must be an object schema');
+      }
+      let run: NodeKindRun | undefined;
+      if (node.graph === 'workflow') {
+        if (!node.run || typeof node.run !== 'object' || Array.isArray(node.run)) throw new Error('run must be an object');
+        const spec = node.run as Record<string, unknown>;
+        if (Object.keys(spec).length !== 1 || !['bash', 'http', 'skill', 'mcp'].some((key) => key in spec)) {
+          throw new Error('run must contain exactly one bash, http, skill or mcp executor');
+        }
+        if ('mcp' in spec) {
+          const mcp = spec.mcp;
+          if (!mcp || typeof mcp !== 'object' || Array.isArray(mcp)
+            || typeof (mcp as Record<string, unknown>).server !== 'string'
+            || typeof (mcp as Record<string, unknown>).tool !== 'string') {
+            throw new Error('mcp run requires server and tool');
+          }
+        }
+        run = spec as NodeKindRun;
+      } else if (node.run !== undefined) {
+        throw new Error('harness nodes cannot define run');
+      }
+      const kind = `${manifest.id}:${node.kind}`;
+      const registration = registerNodeKind({
+        graph: node.graph as GraphKind,
+        kind,
+        plugin: manifest.id,
+        description: typeof node.description === 'string' ? node.description : '',
+        schema: node.inputs as Record<string, unknown>,
+        core: false,
+        ...(run ? { run } : {}),
+      });
+      if (!registration.ok) throw new Error(`node ${kind} rejected: ${registration.reason}`);
+    } catch (err) {
+      result.errors.push(`${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return result;
+}

package/src/graph-kinds/registry.ts

@@ -0,0 +1,118 @@
+import { debug } from '../debug/log.js';
+
+export type GraphKind = 'harness' | 'workflow';
+
+/** Declarative body a workflow plugin kind reuses. */
+export type NodeKindRun =
+  | { bash: string }
+  | { http: { method: string; url: string; body?: string } }
+  | { skill: { name: string; prompt?: string } }
+  | { mcp: { server: string; tool: string; args?: Record<string, unknown> } };
+
+export interface NodeKindEntry {
+  graph: GraphKind;
+  kind: string;
+  plugin?: string;
+  description: string;
+  schema?: Record<string, unknown>;
+  core: boolean;
+  /** Workflow kinds only. Absent on core kinds and on harness kinds. */
+  run?: NodeKindRun;
+}
+
+export const HARNESS_CORE_KINDS = ['agent', 'gate', 'git', 'judge', 'observe', 'hitl', 'subgraph'] as const;
+
+// Workflow validation and the palette read the same keys; runtime dispatch remains unchanged.
+export const WORKFLOW_CORE_KINDS = ['prompt', 'bash', 'skill', 'cft', 'approval', 'if', 'switch', 'iteration', 'classify', 'extract', 'set', 'filter', 'template', 'http', 'showroom', 'task', 'scheduleTrigger', 'webhookTrigger', 'discordTrigger', 'telegramTrigger', 'manualTrigger', 'chatTrigger'] as const;
+
+const descriptions: Record<GraphKind, readonly string[]> = {
+  harness: ['Run an agent', 'Check an execution gate', 'Perform git operations', 'Judge an outcome', 'Observe a result', 'Request human input', 'Run a child graph'],
+  workflow: ['Run an LLM prompt', 'Run a shell command', 'Invoke a skill', 'Invoke a CFT method', 'Request approval', 'Branch on a condition', 'Select a case', 'Iterate items', 'Classify input', 'Extract structured data', 'Assign variables', 'Filter items', 'Render a template', 'Make an HTTP request', 'Run a showroom', 'Create a task', 'Start on a schedule', 'Start on a webhook', 'Start on Discord', 'Start on Telegram', 'Start manually', 'Start on chat'],
+};
+
+const kinds = new Map<GraphKind, Map<string, NodeKindEntry>>();
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function registerNodeKind(entry: NodeKindEntry): { ok: true } | { ok: false; reason: 'core-kind' | 'bad-name' | 'duplicate' } {
+  if (entry.graph !== 'harness' && entry.graph !== 'workflow') return { ok: false, reason: 'bad-name' };
+  const graphKinds = kinds.get(entry.graph) ?? new Map<string, NodeKindEntry>();
+  const existing = graphKinds.get(entry.kind);
+  if (existing?.core || (!entry.core && (entry.graph === 'harness' ? HARNESS_CORE_KINDS : WORKFLOW_CORE_KINDS).some((kind) => kind === entry.kind))) return { ok: false, reason: 'core-kind' };
+  if (!entry.core && (!entry.plugin || !NAME.test(entry.plugin) || !NAME.test(entry.kind.split(':')[1] ?? '') || entry.kind !== `${entry.plugin}:${entry.kind.split(':')[1]}`)) {
+    return { ok: false, reason: 'bad-name' };
+  }
+  if (entry.core && (entry.plugin !== undefined || entry.run !== undefined || !(entry.graph === 'harness' ? HARNESS_CORE_KINDS : WORKFLOW_CORE_KINDS).some((kind) => kind === entry.kind))) return { ok: false, reason: 'bad-name' };
+  if (entry.run !== undefined && (entry.graph !== 'workflow' || !isNodeKindRun(entry.run))) return { ok: false, reason: 'bad-name' };
+  if (existing) return { ok: false, reason: 'duplicate' };
+  graphKinds.set(entry.kind, { ...entry });
+  kinds.set(entry.graph, graphKinds);
+  debug.log('graph.kinds', 'register', { graph: entry.graph, kind: entry.kind, plugin: entry.plugin });
+  return { ok: true };
+}
+
+/** Internal ownership handle; unlike the public snapshot, this is the registered object itself. */
+export function getNodeKindRegistration(graph: GraphKind, kind: string): NodeKindEntry | undefined {
+  return kinds.get(graph)?.get(kind);
+}
+
+/** Remove a plugin registration only when it is still the same registered object; core kinds are immutable. */
+export function unregisterPluginNodeKind(graph: GraphKind, kind: string, plugin: string, registered: NodeKindEntry): boolean {
+  const graphKinds = kinds.get(graph);
+  const entry = graphKinds?.get(kind);
+  if (!entry || entry.core || entry.plugin !== plugin || entry !== registered) return false;
+  graphKinds!.delete(kind);
+  debug.log('graph.kinds', 'unregister', { graph, kind, plugin });
+  return true;
+}
+
+export function registerCoreKinds(): void {
+  for (const graph of ['harness', 'workflow'] as const) {
+    const names = graph === 'harness' ? HARNESS_CORE_KINDS : WORKFLOW_CORE_KINDS;
+    names.forEach((kind, index) => {
+      if (!kinds.get(graph)?.has(kind)) registerNodeKind({ graph, kind, description: descriptions[graph][index]!, core: true });
+    });
+  }
+}
+
+export function listNodeKinds(graph?: GraphKind): NodeKindEntry[] {
+  registerCoreKinds();
+  return (graph ? [graph] : ['harness', 'workflow'] as const).flatMap((g) => [...(kinds.get(g)?.values() ?? [])].map((entry) => ({ ...entry })));
+}
+
+export function hasNodeKind(graph: GraphKind, kind: string): boolean {
+  registerCoreKinds();
+  return kinds.get(graph)?.has(kind) ?? false;
+}
+
+/** The registered entry, or undefined. Core kinds are ensured first. */
+export function getNodeKind(graph: GraphKind, kind: string): NodeKindEntry | undefined {
+  registerCoreKinds();
+  const entry = kinds.get(graph)?.get(kind);
+  return entry ? { ...entry } : undefined;
+}
+
+function isNodeKindRun(run: NodeKindRun): boolean {
+  if (!run || typeof run !== 'object' || Array.isArray(run)) return false;
+  if ('bash' in run) return typeof run.bash === 'string' && run.bash.trim().length > 0 && !('http' in run) && !('skill' in run) && !('mcp' in run);
+  if ('http' in run) {
+    return !('skill' in run) && !('mcp' in run)
+      && typeof run.http === 'object' && run.http !== null
+      && typeof run.http.method === 'string' && run.http.method.trim().length > 0
+      && typeof run.http.url === 'string' && run.http.url.trim().length > 0
+      && (run.http.body === undefined || typeof run.http.body === 'string');
+  }
+  if ('skill' in run) return !('mcp' in run)
+    && typeof run.skill === 'object' && run.skill !== null
+    && typeof run.skill.name === 'string' && run.skill.name.trim().length > 0
+    && (run.skill.prompt === undefined || typeof run.skill.prompt === 'string');
+  if ('mcp' in run) {
+    const spec = run.mcp;
+    return typeof spec === 'object' && spec !== null && !Array.isArray(spec)
+      && typeof spec.server === 'string' && /^[a-z0-9_-]+$/.test(spec.server)
+      && typeof spec.tool === 'string' && /^[a-z0-9_-]+$/.test(spec.tool)
+      && (spec.args === undefined || (typeof spec.args === 'object' && spec.args !== null && !Array.isArray(spec.args)));
+  }
+  return false;
+}
+
+registerCoreKinds();

package/src/graph-runner/graph-cli.ts

@@ -0,0 +1,103 @@
+import type { Command } from 'commander';
+import { writeStdoutJson } from '../cli/stdout-json.js';
+import { decideGraphApproval, latestGraphRun, runGraph } from './runner.js';
+
+export function registerGraphCommands(program: Command): void {
+  const graph = program.command('graph').description('Run a declared command graph or inspect its latest run');
+  graph.command('run <file>')
+    .option('--dry-run', 'Walk the success path without executing commands')
+    .option('--json', 'Print run state as JSON')
+    .option('--resume <run_id>', 'Resume a persisted run awaiting approval or restart a failed path with --from')
+    .option('--from <node_id>', 'Restart a failed run at a node on its saved path (requires --resume)')
+    .option('--input <json>', 'JSON object passed to the graph run')
+    .action(async (file: string, opts: { dryRun?: boolean; json?: boolean; resume?: string; from?: string; input?: string }) => {
+      try {
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        if (opts.resume && opts.dryRun) throw new Error('--resume cannot be combined with --dry-run');
+        if (opts.from && !opts.resume) throw new Error('--from requires --resume');
+        let input: Record<string, unknown> | undefined;
+        if (opts.input !== undefined) {
+          let parsed: unknown;
+          try { parsed = JSON.parse(opts.input); }
+          catch { throw new Error('--input must be a JSON object'); }
+          if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('--input must be a JSON object');
+          input = parsed as Record<string, unknown>;
+        }
+        const state = await runGraph(file, { ...(opts.resume ? { resumeRunId: opts.resume } : { dryRun: opts.dryRun }), ...(opts.from ? { fromNodeId: opts.from } : {}), ...(input === undefined ? {} : { input }) });
+        if (opts.json) await writeStdoutJson(JSON.stringify(state) + '\n');
+        else console.log(`${state.graphId} ${state.runId}: ${state.status} (${state.path.join(' → ')}, executed: ${state.executed})${state.pending ? ` — ${state.pending.message}` : ''}`);
+        if (state.status !== 'done' && state.status !== 'awaiting-approval') process.exitCode = 1;
+      } catch (error) {
+        console.error(`graph run: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  graph.command('tick <file>')
+    .description('Advance one graph run, resuming a pending decision or starting only when requested')
+    .option('--start', 'Start a new run when the graph is idle')
+    .option('--input <json>', 'JSON object passed to a newly started run')
+    .option('--json', 'Print the tick result as JSON')
+    .action(async (file: string, opts: { start?: boolean; input?: string; json?: boolean }) => {
+      try {
+        if (opts.input !== undefined && !opts.start) throw new Error('--input requires --start');
+        let input: Record<string, unknown> | undefined;
+        if (opts.input !== undefined) {
+          let parsed: unknown;
+          try { parsed = JSON.parse(opts.input); }
+          catch { throw new Error('--input must be a JSON object'); }
+          if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('--input must be a JSON object');
+          input = parsed as Record<string, unknown>;
+        }
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        const { graphTick } = await import('./graph-tick.js');
+        const result = await graphTick(file, { startIfIdle: opts.start, ...(input === undefined ? {} : { input }),
+          deps: { notify: async () => { const { notifyGraphEvents } = await import('./graph-notify.js'); await notifyGraphEvents(); } } });
+        if (opts.json) await writeStdoutJson(JSON.stringify(result) + '\n');
+        else console.log(`graph tick: ${result.action}${result.runId ? ` ${result.runId}: ${result.status}` : ''}`);
+        if (result.status === 'failed') process.exitCode = 1;
+      } catch (error) {
+        console.error(`graph tick: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  graph.command('notify')
+    .description('Deliver graph run events not yet recorded in the notification ledger')
+    .option('--dry-run', 'Preview notifications without sending or recording them')
+    .action(async (opts: { dryRun?: boolean }) => {
+      try {
+        if (!opts.dryRun) await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        const { notifyGraphEvents } = await import('./graph-notify.js');
+        const events = await notifyGraphEvents({ dryRun: opts.dryRun });
+        if (opts.dryRun) for (const event of events) console.log(`${event.id} ${event.message}`);
+        console.log(`${opts.dryRun ? 'pending' : 'sent'} graph notifications: ${events.length}`);
+      } catch (error) {
+        console.error(`graph notify: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  graph.command('approve <graph_id> <run_id>')
+    .option('--reject', 'Reject instead of approving')
+    .option('--by <name>', 'Record the approver name')
+    .action((graphId: string, runId: string, opts: { reject?: boolean; by?: string }) => {
+      try {
+        const state = decideGraphApproval(graphId, runId, opts.reject ? 'rejected' : 'approved', opts.by);
+        console.log(`${state.graphId} ${state.runId}: ${state.pending?.decision}`);
+      } catch (error) {
+        console.error(`graph approve: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  graph.command('status <graph_id>')
+    .option('--json', 'Print latest run state as JSON')
+    .action(async (graphId: string, opts: { json?: boolean }) => {
+      try {
+        const state = latestGraphRun(graphId);
+        if (opts.json) await writeStdoutJson(JSON.stringify(state) + '\n');
+        else console.log(state ? `${state.graphId} ${state.runId}: ${state.status} (${state.path.join(' → ')})${state.pending ? ` — ${state.pending.message}` : ''}` : `no runs: ${graphId}`);
+        if (!state) process.exitCode = 1;
+      } catch (error) {
+        console.error(`graph status: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/graph-runner/graph-notify.ts

@@ -0,0 +1,220 @@
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { GraphRunState } from './runner.js';
+
+export interface GraphNotificationEvent {
+  id: string;
+  graphId: string;
+  runId: string;
+  nodeId: string;
+  kind: 'approval' | 'node';
+  visit: number;
+  message: string;
+  status?: 'ok' | 'fail';
+}
+
+export interface GraphNotifyOptions {
+  root?: string;
+  graphsDir?: string;
+  dryRun?: boolean;
+  send?: (message: string, event: GraphNotificationEvent) => Promise<void> | void;
+}
+
+type NotificationSetting = boolean | string | { on?: string | string[]; enabled?: boolean };
+type NodeDeclaration = { node_id?: string; notify?: NotificationSetting };
+
+function filesUnder(dir: string, extension: string): string[] {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  return entries.flatMap((entry) => entry.isDirectory()
+    ? filesUnder(join(dir, entry.name), extension)
+    : entry.isFile() && entry.name.endsWith(extension) ? [join(dir, entry.name)] : []).sort();
+}
+
+function declarations(graphsDir: string): Map<string, Map<string, NodeDeclaration>> {
+  const graphs = new Map<string, Map<string, NodeDeclaration>>();
+  for (const file of [...filesUnder(graphsDir, '.yaml'), ...filesUnder(graphsDir, '.yml')].sort()) {
+    const doc: unknown = parseYaml(readFileSync(file, 'utf8'));
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) continue;
+    const graph = doc as { graph_id?: unknown; nodes?: unknown };
+    if (typeof graph.graph_id !== 'string' || !Array.isArray(graph.nodes)) continue;
+    const nodes = new Map<string, NodeDeclaration>();
+    for (const raw of graph.nodes) {
+      if (raw && typeof raw === 'object' && typeof (raw as NodeDeclaration).node_id === 'string') {
+        const node = raw as NodeDeclaration;
+        nodes.set(node.node_id!, node);
+      }
+    }
+    graphs.set(graph.graph_id, nodes);
+  }
+  return graphs;
+}
+
+function wantsNotification(setting: NotificationSetting | undefined, kind: 'approval' | 'node', status?: 'ok' | 'fail'): boolean {
+  // Approval gates notify by default; ordinary nodes are opt-in.
+  if (setting === undefined) return kind === 'approval';
+  if (typeof setting === 'boolean') return setting;
+  if (typeof setting === 'object' && setting !== null) {
+    if (setting.enabled === false) return false;
+    if (setting.on === undefined) return setting.enabled === true || kind === 'approval';
+    return (Array.isArray(setting.on) ? setting.on : [setting.on]).some((value) => matches(value, kind, status));
+  }
+  return matches(setting, kind, status);
+}
+
+function matches(value: string, kind: 'approval' | 'node', status?: 'ok' | 'fail'): boolean {
+  return value === 'always' || value === 'all' || value === (kind === 'approval' ? 'approval' : 'node') ||
+    (kind === 'node' && (value === status || value === (status === 'ok' ? 'success' : 'failure')));
+}
+
+export function formatApprovalMessage(event: Pick<GraphNotificationEvent, 'graphId' | 'runId' | 'nodeId' | 'message'>): string {
+  return `Graph ${event.graphId} / run ${event.runId} — approval required at ${event.nodeId}\n${event.message}\nApprove: elanous graph approve ${event.graphId} ${event.runId}\nReject: elanous graph approve ${event.graphId} ${event.runId} --reject`;
+}
+
+/** Observe persisted runs only. Notification progress lives exclusively in the JSONL ledger. */
+export function collectGraphEvents(options: Pick<GraphNotifyOptions, 'root' | 'graphsDir'> = {}): GraphNotificationEvent[] {
+  const root = options.root ?? effectiveInstanceRoot();
+  const graphsDir = options.graphsDir ?? join(process.cwd(), 'graphs');
+  const graphs = declarations(graphsDir);
+  const events: GraphNotificationEvent[] = [];
+  const runRoot = join(root, 'graph-runs');
+  let graphDirectories;
+  try { graphDirectories = readdirSync(runRoot, { withFileTypes: true }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  for (const directory of graphDirectories) {
+    if (!directory.isDirectory()) continue;
+    const graphId = directory.name;
+    const nodes = graphs.get(graphId);
+    if (!nodes) continue;
+    const runDir = join(runRoot, graphId);
+    for (const entry of readdirSync(runDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name.endsWith('.decision.json')) continue;
+      const file = join(runDir, entry.name);
+      const state = JSON.parse(readFileSync(file, 'utf8')) as GraphRunState;
+      if (state.graphId !== graphId || file !== join(runRoot, graphId, `${state.runId}.json`)) throw new Error(`run identity mismatch: ${file}`);
+      if (!Array.isArray(state.nodes) || !Array.isArray(state.path) || state.dryRun) continue;
+      const visits = new Map<string, number>();
+      for (const record of state.nodes) {
+        const visit = (visits.get(record.nodeId) ?? 0) + 1;
+        visits.set(record.nodeId, visit);
+        const status = record.ok ? 'ok' : 'fail';
+        if (!nodes.has(record.nodeId) || !wantsNotification(nodes.get(record.nodeId)?.notify, 'node', status)) continue;
+        events.push({ id: JSON.stringify([state.graphId, state.runId, 'node', record.nodeId, visit]),
+          graphId: state.graphId, runId: state.runId, kind: 'node', nodeId: record.nodeId, visit, status,
+          message: `Graph ${state.graphId} / run ${state.runId} — ${record.nodeId} #${visit}: ${status}` });
+      }
+      const decisionPath = `${file}.${state.path.length}.decision.json`;
+      let claimed = false;
+      try { readFileSync(decisionPath, 'utf8'); claimed = true; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      if (state.status === 'awaiting-approval' && state.pending && !state.pending.decision && !claimed && nodes.has(state.pending.nodeId) &&
+          wantsNotification(nodes.get(state.pending.nodeId)?.notify, 'approval')) {
+        const pending = state.pending;
+        const visit = state.path.filter((nodeId) => nodeId === pending.nodeId).length;
+        const event = { id: JSON.stringify([state.graphId, state.runId, 'approval', pending.nodeId, visit]),
+          graphId: state.graphId, runId: state.runId, kind: 'approval' as const, nodeId: pending.nodeId, visit, message: pending.message };
+        events.push({ ...event, message: formatApprovalMessage(event) });
+      }
+    }
+  }
+  return events;
+}
+
+// Keep the lock inode permanently: unlinking it permits a second flock on a new inode.
+// flock is released by the kernel on process exit, including an unclean exit.
+// ⛔ Loaded lazily: this module is imported by every CLI start (index → graph-cli), and a top-level
+//    dlopen of glibc/libSystem throws on Windows and musl — that would take the whole CLI down.
+const LOCK_EX_NB = 2 | 4;
+const LOCK_UN = 8;
+type FlockFn = (fd: number, operation: number) => number;
+let flockFn: FlockFn | null | undefined;
+let flockLoading: Promise<FlockFn | null> | undefined;
+/** Test seam: `null` forces the exclusive-file path, `undefined` restores detection. */
+export function setGraphNotifyFlockForTest(fn: FlockFn | null | undefined): void {
+  flockFn = fn;
+  flockLoading = undefined;
+}
+async function loadFlock(): Promise<FlockFn | null> {
+  if (flockFn !== undefined) return flockFn;
+  flockLoading ??= (async () => {
+    const library = process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : process.platform === 'linux' ? 'libc.so.6' : null;
+    if (library) {
+      try {
+        const { dlopen, FFIType } = await import('bun:ffi');
+        const lib = dlopen(library, { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } });
+        return (fd: number, operation: number) => lib.symbols.flock(fd, operation) as number;
+      } catch { /* fall back to the exclusive owner file */ }
+    }
+    return null;
+  })();
+  const loaded = await flockLoading;
+  flockFn = loaded;
+  return loaded;
+}
+
+export async function notifyGraphEvents(options: GraphNotifyOptions = {}): Promise<GraphNotificationEvent[]> {
+  const root = options.root ?? effectiveInstanceRoot();
+  const ledgerPath = join(root, 'graph-runs', 'notifications.jsonl');
+  const collectFresh = (): GraphNotificationEvent[] => {
+    let ledger = '';
+    try { ledger = readFileSync(ledgerPath, 'utf8'); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    const sent = new Set<string>();
+    for (const line of ledger.split('\n').filter(Boolean)) {
+      const entry: unknown = JSON.parse(line);
+      if (!entry || typeof entry !== 'object' || typeof (entry as { id?: unknown }).id !== 'string') throw new Error(`invalid graph notification ledger: ${ledgerPath}`);
+      sent.add((entry as { id: string }).id);
+    }
+    return collectGraphEvents({ root, graphsDir: options.graphsDir }).filter((event) => !sent.has(event.id));
+  };
+  if (options.dryRun) return collectFresh();
+  // The former .lock path was a directory; use a separate, stable inode instead of trying to reclaim it.
+  const lock = `${ledgerPath}.flock`;
+  mkdirSync(join(root, 'graph-runs'), { recursive: true });
+  const flock = await loadFlock();
+  if (!flock) return notifyWithExclusiveFile(`${ledgerPath}.owner`, collectFresh, options.send, ledgerPath);
+  const fd = openSync(lock, 'a');
+  let acquired = false;
+  try {
+    if (flock(fd, LOCK_EX_NB) !== 0) throw new Error('graph notification is already running');
+    acquired = true;
+    return await sendFresh(collectFresh(), options.send, ledgerPath);
+  } finally {
+    try {
+      if (acquired && flock(fd, LOCK_UN) !== 0) throw new Error('graph notification lock release failed');
+    } finally { closeSync(fd); }
+  }
+}
+
+async function sendFresh(fresh: GraphNotificationEvent[], sendOption: GraphNotifyOptions['send'], ledgerPath: string): Promise<GraphNotificationEvent[]> {
+  const send = sendOption ?? (async (message: string) => {
+    const { deliver } = await import('../domains/outbound-alert.js');
+    if (!deliver(message, 'graph')) throw new Error('graph notification delivery failed');
+  });
+  for (const event of fresh) {
+    await send(event.message, event);
+    appendFileSync(ledgerPath, JSON.stringify({ id: event.id, graphId: event.graphId, runId: event.runId, nodeId: event.nodeId,
+      kind: event.kind, visit: event.visit, sentAt: new Date().toISOString() }) + '\n');
+  }
+  return fresh;
+}
+
+/** Platforms without flock (Windows, musl): an exclusive owner file. A crash leaves it behind, and the next run names it instead of double-sending. */
+async function notifyWithExclusiveFile(ownerPath: string, collectFresh: () => GraphNotificationEvent[], send: GraphNotifyOptions['send'], ledgerPath: string): Promise<GraphNotificationEvent[]> {
+  try { writeFileSync(ownerPath, String(process.pid), { flag: 'wx' }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') throw new Error(`graph notification is already running (or a crashed run left ${ownerPath} — remove it if no notifier is running)`);
+    throw error;
+  }
+  try { return await sendFresh(collectFresh(), send, ledgerPath); }
+  finally { rmSync(ownerPath, { force: true }); }
+}