@hasna/loops 0.3.5 → 0.3.6

package/dist/lib/store.js

@@ -234,6 +234,82 @@ function parseDuration(input) {
   return Math.round(value * multiplier);
 }
 
+// src/lib/goal/types.ts
+var GOAL_TERMINAL = ["budgetLimited", "complete", "cancelled"];
+var GOAL_OBJECTIVE_MAX_CHARS = 4000;
+
+// src/lib/goal/status.ts
+function isTerminal(status) {
+  return GOAL_TERMINAL.includes(status);
+}
+function nodeBudgetExhausted(node) {
+  return node.tokenBudget !== undefined && node.tokensUsed >= node.tokenBudget;
+}
+function readyNodeKeys(plan) {
+  if (plan.status !== "active")
+    return [];
+  const byKey = new Map(plan.nodes.map((node) => [node.key, node]));
+  return plan.nodes.filter((node) => {
+    if (node.status !== "pending")
+      return false;
+    if (nodeBudgetExhausted(node))
+      return false;
+    return node.dependsOn.every((dependency) => byKey.get(dependency)?.status === "complete");
+  }).sort((a, b) => b.priority - a.priority || a.sequence - b.sequence || a.key.localeCompare(b.key)).map((node) => node.key);
+}
+function rollupSummary(nodes) {
+  const rollup = {
+    total: nodes.length,
+    pending: 0,
+    active: 0,
+    paused: 0,
+    blocked: 0,
+    usageLimited: 0,
+    budgetLimited: 0,
+    complete: 0,
+    cancelled: 0
+  };
+  for (const node of nodes) {
+    if (node.status in rollup) {
+      rollup[node.status] += 1;
+    }
+  }
+  return rollup;
+}
+function assertGoalTransition(from, to) {
+  if (isTerminal(from) && from !== to) {
+    throw new Error(`cannot transition terminal goal status ${from} to ${to}`);
+  }
+}
+function assertAcyclicNodes(nodes) {
+  const byKey = new Map(nodes.map((node) => [node.key, node]));
+  const visiting = new Set;
+  const visited = new Set;
+  function visit(key) {
+    if (visited.has(key))
+      return;
+    if (visiting.has(key))
+      throw new Error(`goal dependency cycle includes node ${key}`);
+    const node = byKey.get(key);
+    if (!node)
+      throw new Error(`goal plan references missing node ${key}`);
+    visiting.add(key);
+    for (const dependency of node.dependsOn) {
+      if (!byKey.has(dependency))
+        throw new Error(`goal node ${key} depends on missing node ${dependency}`);
+      visit(dependency);
+    }
+    visiting.delete(key);
+    visited.add(key);
+  }
+  for (const node of nodes)
+    visit(node.key);
+}
+function updateReadyFlags(nodes, planStatus) {
+  const ready = new Set(readyNodeKeys({ status: planStatus, nodes }));
+  return nodes.map((node) => ({ ...node, ready: ready.has(node.key) }));
+}
+
 // src/lib/workflow-spec.ts
 function assertObject(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -243,6 +319,35 @@ function assertString(value, label) {
   if (typeof value !== "string" || value.trim() === "")
     throw new Error(`${label} must be a non-empty string`);
 }
+function optionalPositiveInteger(value, label) {
+  if (value === undefined)
+    return;
+  if (!Number.isInteger(value) || value <= 0)
+    throw new Error(`${label} must be a positive integer`);
+  return value;
+}
+function normalizeGoalSpec(value, label = "goal") {
+  if (value === undefined)
+    return;
+  assertObject(value, label);
+  assertString(value.objective, `${label}.objective`);
+  const objective = value.objective.trim();
+  if (objective.length > GOAL_OBJECTIVE_MAX_CHARS) {
+    throw new Error(`${label}.objective must be ${GOAL_OBJECTIVE_MAX_CHARS} characters or fewer`);
+  }
+  const autoExecute = value.autoExecute === undefined ? undefined : String(value.autoExecute);
+  if (autoExecute !== undefined && !["off", "readyOnly", "aiDirected"].includes(autoExecute)) {
+    throw new Error(`${label}.autoExecute must be off, readyOnly, or aiDirected`);
+  }
+  return {
+    objective,
+    tokenBudget: optionalPositiveInteger(value.tokenBudget, `${label}.tokenBudget`),
+    maxTurns: optionalPositiveInteger(value.maxTurns, `${label}.maxTurns`),
+    maxTokens: optionalPositiveInteger(value.maxTokens, `${label}.maxTokens`),
+    model: typeof value.model === "string" && value.model.trim() ? value.model.trim() : undefined,
+    autoExecute
+  };
+}
 function validateTarget(value, label) {
   assertObject(value, label);
   if (value.type === "command") {
@@ -269,6 +374,7 @@ function validateTarget(value, label) {
 }
 function normalizeCreateWorkflowInput(input) {
   assertString(input.name, "workflow.name");
+  const goal = normalizeGoalSpec(input.goal, "goal");
   if (!Array.isArray(input.steps) || input.steps.length === 0)
     throw new Error("workflow.steps must contain at least one step");
   const seen = new Set;
@@ -281,6 +387,7 @@ function normalizeCreateWorkflowInput(input) {
     return {
       ...step,
       id: step.id,
+      goal: normalizeGoalSpec(step.goal, `workflow.steps[${index}].goal`),
       target: validateTarget(step.target, `workflow.steps[${index}].target`),
       dependsOn: step.dependsOn ?? [],
       continueOnFailure: step.continueOnFailure ?? false
@@ -295,7 +402,7 @@ function normalizeCreateWorkflowInput(input) {
     }
   }
   workflowExecutionOrder({ steps });
-  return { ...input, name: input.name.trim(), version: input.version ?? 1, steps };
+  return { ...input, name: input.name.trim(), goal, version: input.version ?? 1, steps };
 }
 function workflowExecutionOrder(workflow) {
   const byId = new Map(workflow.steps.map((step) => [step.id, step]));
@@ -331,6 +438,7 @@ function workflowBodyFromJson(value, fallbackName) {
   return normalizeCreateWorkflowInput({
     name: rawName,
     description: typeof value.description === "string" ? value.description : undefined,
+    goal: normalizeGoalSpec(value.goal, "goal"),
     version: typeof value.version === "number" ? value.version : undefined,
     steps: value.steps
   });
@@ -345,6 +453,7 @@ function rowToLoop(row) {
     status: row.status,
     schedule: JSON.parse(row.schedule_json),
     target: JSON.parse(row.target_json),
+    goal: row.goal_json ? JSON.parse(row.goal_json) : undefined,
     machine: row.machine_json ? JSON.parse(row.machine_json) : undefined,
     nextRunAt: row.next_run_at ?? undefined,
     retryScheduledFor: row.retry_scheduled_for ?? undefined,
@@ -377,6 +486,7 @@ function rowToRun(row) {
     stdout: row.stdout ?? undefined,
     stderr: row.stderr ?? undefined,
     error: row.error ?? undefined,
+    goalRunId: row.goal_run_id ?? undefined,
     createdAt: row.created_at,
     updatedAt: row.updated_at
   };
@@ -388,6 +498,7 @@ function rowToWorkflow(row) {
     description: row.description ?? undefined,
     version: row.version,
     status: row.status,
+    goal: row.goal_json ? JSON.parse(row.goal_json) : undefined,
     steps: JSON.parse(row.steps_json),
     createdAt: row.created_at,
     updatedAt: row.updated_at
@@ -407,6 +518,7 @@ function rowToWorkflowRun(row) {
     finishedAt: row.finished_at ?? undefined,
     durationMs: row.duration_ms ?? undefined,
     error: row.error ?? undefined,
+    goalRunId: row.goal_run_id ?? undefined,
     createdAt: row.created_at,
     updatedAt: row.updated_at
   };
@@ -428,6 +540,68 @@ function rowToWorkflowStepRun(row) {
     error: row.error ?? undefined,
     accountProfile: row.account_profile ?? undefined,
     accountTool: row.account_tool ?? undefined,
+    goalRunId: row.goal_run_id ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToGoal(row) {
+  return {
+    goalId: row.id,
+    planId: row.plan_id,
+    objective: row.objective,
+    status: row.status,
+    tokenBudget: row.token_budget ?? undefined,
+    tokensUsed: row.tokens_used,
+    timeUsedSeconds: row.time_used_seconds,
+    autoExecute: row.auto_execute,
+    maxTokens: row.max_tokens ?? undefined,
+    sourceType: row.source_type ?? undefined,
+    sourceId: row.source_id ?? undefined,
+    loopId: row.loop_id ?? undefined,
+    loopRunId: row.loop_run_id ?? undefined,
+    workflowId: row.workflow_id ?? undefined,
+    workflowRunId: row.workflow_run_id ?? undefined,
+    workflowStepId: row.workflow_step_id ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToGoalPlanNode(row) {
+  return {
+    nodeId: row.id,
+    planId: row.plan_id,
+    key: row.key,
+    sequence: row.sequence,
+    priority: row.priority,
+    objective: row.objective,
+    status: row.status,
+    ready: row.ready === 1,
+    tokenBudget: row.token_budget ?? undefined,
+    tokensUsed: row.tokens_used,
+    timeUsedSeconds: row.time_used_seconds,
+    dependsOn: JSON.parse(row.depends_on_json),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToGoalRun(row) {
+  return {
+    runId: row.id,
+    goalId: row.goal_id,
+    planId: row.plan_id,
+    loopId: row.loop_id ?? undefined,
+    loopRunId: row.loop_run_id ?? undefined,
+    workflowId: row.workflow_id ?? undefined,
+    workflowRunId: row.workflow_run_id ?? undefined,
+    workflowStepId: row.workflow_step_id ?? undefined,
+    turn: row.turn,
+    phase: row.phase,
+    status: row.status,
+    nodeKey: row.node_key ?? undefined,
+    tokensUsed: row.tokens_used,
+    evidence: row.evidence_json ? JSON.parse(row.evidence_json) : undefined,
+    rawResponse: row.raw_response_json ? JSON.parse(row.raw_response_json) : undefined,
     createdAt: row.created_at,
     updatedAt: row.updated_at
   };
@@ -488,6 +662,7 @@ class Store {
         status TEXT NOT NULL,
         schedule_json TEXT NOT NULL,
         target_json TEXT NOT NULL,
+        goal_json TEXT,
         machine_json TEXT,
         next_run_at TEXT,
         retry_scheduled_for TEXT,
@@ -521,6 +696,7 @@ class Store {
         stdout TEXT,
         stderr TEXT,
         error TEXT,
+        goal_run_id TEXT,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL,
         UNIQUE(loop_id, scheduled_for)
@@ -545,6 +721,7 @@ class Store {
         description TEXT,
         version INTEGER NOT NULL,
         status TEXT NOT NULL,
+        goal_json TEXT,
         steps_json TEXT NOT NULL,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
@@ -565,6 +742,7 @@ class Store {
         finished_at TEXT,
         duration_ms INTEGER,
         error TEXT,
+        goal_run_id TEXT,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
       );
@@ -591,6 +769,7 @@ class Store {
         error TEXT,
         account_profile TEXT,
         account_tool TEXT,
+        goal_run_id TEXT,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL,
         UNIQUE(workflow_run_id, step_id)
@@ -609,15 +788,100 @@ class Store {
         UNIQUE(workflow_run_id, sequence)
       );
       CREATE INDEX IF NOT EXISTS idx_workflow_events_run_sequence ON workflow_events(workflow_run_id, sequence);
+
+      CREATE TABLE IF NOT EXISTS goals (
+        id TEXT PRIMARY KEY,
+        plan_id TEXT NOT NULL,
+        objective TEXT NOT NULL,
+        status TEXT NOT NULL,
+        token_budget INTEGER,
+        tokens_used INTEGER NOT NULL,
+        time_used_seconds INTEGER NOT NULL,
+        auto_execute TEXT NOT NULL,
+        max_tokens INTEGER,
+        source_type TEXT,
+        source_id TEXT,
+        loop_id TEXT,
+        loop_run_id TEXT,
+        workflow_id TEXT,
+        workflow_run_id TEXT,
+        workflow_step_id TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_goals_status_updated ON goals(status, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_goals_loop_run ON goals(loop_run_id);
+      CREATE INDEX IF NOT EXISTS idx_goals_workflow_run ON goals(workflow_run_id);
+      CREATE INDEX IF NOT EXISTS idx_goals_source ON goals(source_type, source_id);
+
+      CREATE TABLE IF NOT EXISTS goal_plan_nodes (
+        id TEXT PRIMARY KEY,
+        goal_id TEXT NOT NULL REFERENCES goals(id) ON DELETE CASCADE,
+        plan_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        sequence INTEGER NOT NULL,
+        priority INTEGER NOT NULL,
+        objective TEXT NOT NULL,
+        status TEXT NOT NULL,
+        ready INTEGER NOT NULL,
+        token_budget INTEGER,
+        tokens_used INTEGER NOT NULL,
+        time_used_seconds INTEGER NOT NULL,
+        depends_on_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(plan_id, key)
+      );
+      CREATE INDEX IF NOT EXISTS idx_goal_plan_nodes_goal_sequence ON goal_plan_nodes(goal_id, sequence);
+      CREATE INDEX IF NOT EXISTS idx_goal_plan_nodes_status ON goal_plan_nodes(status);
+
+      CREATE TABLE IF NOT EXISTS goal_runs (
+        id TEXT PRIMARY KEY,
+        goal_id TEXT NOT NULL REFERENCES goals(id) ON DELETE CASCADE,
+        plan_id TEXT NOT NULL,
+        loop_id TEXT,
+        loop_run_id TEXT,
+        workflow_id TEXT,
+        workflow_run_id TEXT,
+        workflow_step_id TEXT,
+        turn INTEGER NOT NULL,
+        phase TEXT NOT NULL,
+        status TEXT NOT NULL,
+        node_key TEXT,
+        tokens_used INTEGER NOT NULL,
+        evidence_json TEXT,
+        raw_response_json TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_goal_runs_goal_created ON goal_runs(goal_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_goal_runs_loop_run ON goal_runs(loop_run_id);
+      CREATE INDEX IF NOT EXISTS idx_goal_runs_workflow_run ON goal_runs(workflow_run_id);
     `);
     try {
       this.db.query("ALTER TABLE loops ADD COLUMN machine_json TEXT").run();
     } catch {}
+    try {
+      this.db.query("ALTER TABLE loops ADD COLUMN goal_json TEXT").run();
+    } catch {}
+    try {
+      this.db.query("ALTER TABLE loop_runs ADD COLUMN goal_run_id TEXT").run();
+    } catch {}
+    try {
+      this.db.query("ALTER TABLE workflow_specs ADD COLUMN goal_json TEXT").run();
+    } catch {}
+    try {
+      this.db.query("ALTER TABLE workflow_runs ADD COLUMN goal_run_id TEXT").run();
+    } catch {}
     try {
       this.db.query("ALTER TABLE workflow_step_runs ADD COLUMN pid INTEGER").run();
     } catch {}
+    try {
+      this.db.query("ALTER TABLE workflow_step_runs ADD COLUMN goal_run_id TEXT").run();
+    } catch {}
     this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0001_initial_and_workflows", nowIso());
     this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0002_loop_machines", nowIso());
+    this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0003_goals", nowIso());
   }
   assertDaemonLeaseFence(opts = {}, now = nowIso()) {
     if (!opts.daemonLeaseId)
@@ -635,6 +899,7 @@ class Store {
       status: "active",
       schedule: input.schedule,
       target: input.target,
+      goal: input.goal,
       machine: input.machine,
       nextRunAt: initialNextRun(input.schedule, from),
       catchUp: input.catchUp ?? "latest",
@@ -648,8 +913,8 @@ class Store {
       updatedAt: now
     };
     this.db.query(`INSERT INTO loops (id, name, description, status, schedule_json, target_json, machine_json, next_run_at, retry_scheduled_for,
-          catch_up, catch_up_limit, overlap, max_attempts, retry_delay_ms, lease_ms, expires_at, created_at, updated_at)
-         VALUES ($id, $name, $description, $status, $schedule, $target, $machine, $nextRun, NULL, $catchUp, $catchUpLimit,
+          goal_json, catch_up, catch_up_limit, overlap, max_attempts, retry_delay_ms, lease_ms, expires_at, created_at, updated_at)
+         VALUES ($id, $name, $description, $status, $schedule, $target, $machine, $nextRun, NULL, $goal, $catchUp, $catchUpLimit,
           $overlap, $maxAttempts, $retryDelay, $leaseMs, $expiresAt, $created, $updated)`).run({
       $id: loop.id,
       $name: loop.name,
@@ -658,6 +923,7 @@ class Store {
       $schedule: JSON.stringify(loop.schedule),
       $target: JSON.stringify(loop.target),
       $machine: loop.machine ? JSON.stringify(loop.machine) : null,
+      $goal: loop.goal ? JSON.stringify(loop.goal) : null,
       $nextRun: loop.nextRunAt ?? null,
       $catchUp: loop.catchUp,
       $catchUpLimit: loop.catchUpLimit,
@@ -737,17 +1003,19 @@ class Store {
       description: normalized.description,
       version: normalized.version ?? 1,
       status: "active",
+      goal: normalized.goal,
       steps: normalized.steps,
       createdAt: now,
       updatedAt: now
     };
-    this.db.query(`INSERT INTO workflow_specs (id, name, description, version, status, steps_json, created_at, updated_at)
-         VALUES ($id, $name, $description, $version, $status, $steps, $created, $updated)`).run({
+    this.db.query(`INSERT INTO workflow_specs (id, name, description, version, status, goal_json, steps_json, created_at, updated_at)
+         VALUES ($id, $name, $description, $version, $status, $goal, $steps, $created, $updated)`).run({
       $id: workflow.id,
       $name: workflow.name,
       $description: workflow.description ?? null,
       $version: workflow.version,
       $status: workflow.status,
+      $goal: workflow.goal ? JSON.stringify(workflow.goal) : null,
       $steps: JSON.stringify(workflow.steps),
       $created: workflow.createdAt,
       $updated: workflow.updatedAt
@@ -781,6 +1049,277 @@ class Store {
       throw new Error(`workflow not found after archive: ${workflow.id}`);
     return archived;
   }
+  createGoal(input, opts = {}) {
+    const now = nowIso();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.assertDaemonLeaseFence(opts, now);
+      const id = genId();
+      this.db.query(`INSERT INTO goals (id, plan_id, objective, status, token_budget, tokens_used, time_used_seconds, auto_execute,
+            max_tokens, source_type, source_id, loop_id, loop_run_id, workflow_id, workflow_run_id, workflow_step_id,
+            created_at, updated_at)
+           VALUES ($id, $planId, $objective, 'active', $tokenBudget, 0, 0, $autoExecute, $maxTokens, $sourceType,
+            $sourceId, $loopId, $loopRunId, $workflowId, $workflowRunId, $workflowStepId, $created, $updated)`).run({
+        $id: id,
+        $planId: id,
+        $objective: input.objective,
+        $tokenBudget: input.tokenBudget ?? null,
+        $autoExecute: input.autoExecute ?? "readyOnly",
+        $maxTokens: input.maxTokens ?? input.tokenBudget ?? null,
+        $sourceType: input.sourceType ?? null,
+        $sourceId: input.sourceId ?? null,
+        $loopId: input.loopId ?? null,
+        $loopRunId: input.loopRunId ?? null,
+        $workflowId: input.workflowId ?? null,
+        $workflowRunId: input.workflowRunId ?? null,
+        $workflowStepId: input.workflowStepId ?? null,
+        $created: now,
+        $updated: now
+      });
+      this.db.exec("COMMIT");
+      return this.requireGoal(id);
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  getGoal(id) {
+    const row = this.db.query("SELECT * FROM goals WHERE id = ?").get(id);
+    return row ? rowToGoal(row) : undefined;
+  }
+  requireGoal(id) {
+    const goal = this.getGoal(id);
+    if (!goal)
+      throw new Error(`goal not found: ${id}`);
+    return goal;
+  }
+  findGoalByLoop(idOrName) {
+    const loop = this.getLoop(idOrName) ?? this.findLoopByName(idOrName);
+    if (!loop)
+      return;
+    const row = this.db.query("SELECT * FROM goals WHERE loop_id = ? ORDER BY created_at DESC LIMIT 1").get(loop.id);
+    return row ? rowToGoal(row) : undefined;
+  }
+  findGoalByRunId(id) {
+    const direct = this.getGoal(id);
+    if (direct)
+      return direct;
+    const event = this.db.query("SELECT * FROM goal_runs WHERE id = ?").get(id);
+    if (event)
+      return this.getGoal(event.goal_id);
+    const row = this.db.query(`SELECT * FROM goals
+         WHERE loop_run_id = ? OR workflow_run_id = ? OR workflow_step_id = ?
+         ORDER BY created_at DESC LIMIT 1`).get(id, id, id);
+    return row ? rowToGoal(row) : undefined;
+  }
+  findGoalByContext(context) {
+    if (context.loopRunId) {
+      const row = this.db.query(`SELECT * FROM goals
+           WHERE loop_run_id = ? AND (? IS NULL OR workflow_step_id = ?)
+           ORDER BY created_at DESC LIMIT 1`).get(context.loopRunId, context.workflowStepId ?? null, context.workflowStepId ?? null);
+      if (row)
+        return rowToGoal(row);
+    }
+    if (context.workflowRunId) {
+      const row = this.db.query(`SELECT * FROM goals
+           WHERE workflow_run_id = ? AND (? IS NULL OR workflow_step_id = ?)
+           ORDER BY created_at DESC LIMIT 1`).get(context.workflowRunId, context.workflowStepId ?? null, context.workflowStepId ?? null);
+      if (row)
+        return rowToGoal(row);
+    }
+    if (context.sourceType && context.sourceId) {
+      const row = this.db.query("SELECT * FROM goals WHERE source_type = ? AND source_id = ? ORDER BY created_at DESC LIMIT 1").get(context.sourceType, context.sourceId);
+      if (row)
+        return rowToGoal(row);
+    }
+    return;
+  }
+  listGoals(opts = {}) {
+    const limit = opts.limit ?? 100;
+    const rows = opts.status ? this.db.query("SELECT * FROM goals WHERE status = ? ORDER BY created_at DESC LIMIT ?").all(opts.status, limit) : this.db.query("SELECT * FROM goals ORDER BY created_at DESC LIMIT ?").all(limit);
+    return rows.map(rowToGoal);
+  }
+  createGoalPlanNodes(goalId, nodes, opts = {}) {
+    const goal = this.requireGoal(goalId);
+    const now = nowIso();
+    const materialized = nodes.map((node, sequence) => ({
+      nodeId: genId(),
+      planId: goal.planId,
+      key: node.key,
+      sequence,
+      priority: node.priority ?? 0,
+      objective: node.objective,
+      status: "pending",
+      ready: false,
+      tokenBudget: node.tokenBudget,
+      tokensUsed: 0,
+      timeUsedSeconds: 0,
+      dependsOn: node.dependsOn ?? [],
+      createdAt: now,
+      updatedAt: now
+    }));
+    const withReady = updateReadyFlags(materialized, "active");
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.assertDaemonLeaseFence(opts, now);
+      for (const node of withReady) {
+        this.db.query(`INSERT OR IGNORE INTO goal_plan_nodes (id, goal_id, plan_id, key, sequence, priority, objective, status, ready,
+              token_budget, tokens_used, time_used_seconds, depends_on_json, created_at, updated_at)
+             VALUES ($id, $goalId, $planId, $key, $sequence, $priority, $objective, $status, $ready, $tokenBudget,
+              $tokensUsed, $timeUsedSeconds, $dependsOn, $created, $updated)`).run({
+          $id: node.nodeId,
+          $goalId: goal.goalId,
+          $planId: goal.planId,
+          $key: node.key,
+          $sequence: node.sequence,
+          $priority: node.priority,
+          $objective: node.objective,
+          $status: node.status,
+          $ready: node.ready ? 1 : 0,
+          $tokenBudget: node.tokenBudget ?? null,
+          $tokensUsed: node.tokensUsed,
+          $timeUsedSeconds: node.timeUsedSeconds,
+          $dependsOn: JSON.stringify(node.dependsOn),
+          $created: node.createdAt,
+          $updated: node.updatedAt
+        });
+      }
+      this.db.exec("COMMIT");
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+    return this.listGoalPlanNodes(goalId);
+  }
+  listGoalPlanNodes(goalIdOrPlanId) {
+    const rows = this.db.query("SELECT * FROM goal_plan_nodes WHERE goal_id = ? OR plan_id = ? ORDER BY sequence ASC").all(goalIdOrPlanId, goalIdOrPlanId);
+    return rows.map(rowToGoalPlanNode);
+  }
+  updateGoalStatus(goalId, status, opts = {}) {
+    const current = this.requireGoal(goalId);
+    assertGoalTransition(current.status, status);
+    const now = (opts.now ?? new Date).toISOString();
+    this.db.query(`UPDATE goals SET status=$status, updated_at=$updated
+         WHERE id=$id
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $id: goalId,
+      $status: status,
+      $updated: now,
+      $daemonLeaseId: opts.daemonLeaseId ?? null,
+      $now: now
+    });
+    return this.requireGoal(goalId);
+  }
+  addGoalUsage(goalId, tokens, timeUsedSeconds = 0, opts = {}) {
+    const now = (opts.now ?? new Date).toISOString();
+    this.db.query(`UPDATE goals
+         SET tokens_used=tokens_used + $tokens, time_used_seconds=time_used_seconds + $seconds, updated_at=$updated
+         WHERE id=$id
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $id: goalId,
+      $tokens: tokens,
+      $seconds: timeUsedSeconds,
+      $updated: now,
+      $daemonLeaseId: opts.daemonLeaseId ?? null,
+      $now: now
+    });
+    return this.requireGoal(goalId);
+  }
+  updateGoalPlanNode(goalId, key, patch, opts = {}) {
+    const now = (opts.now ?? new Date).toISOString();
+    this.db.query(`UPDATE goal_plan_nodes
+         SET status=COALESCE($status, status),
+          tokens_used=COALESCE($tokensUsed, tokens_used),
+          time_used_seconds=COALESCE($timeUsedSeconds, time_used_seconds),
+          ready=COALESCE($ready, ready),
+          updated_at=$updated
+         WHERE goal_id=$goalId AND key=$key
+           AND ($daemonLeaseId IS NULL OR EXISTS (
+             SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
+           ))`).run({
+      $goalId: goalId,
+      $key: key,
+      $status: patch.status ?? null,
+      $tokensUsed: patch.tokensUsed ?? null,
+      $timeUsedSeconds: patch.timeUsedSeconds ?? null,
+      $ready: patch.ready === undefined ? null : patch.ready ? 1 : 0,
+      $updated: now,
+      $daemonLeaseId: opts.daemonLeaseId ?? null,
+      $now: now
+    });
+    const node = this.listGoalPlanNodes(goalId).find((entry) => entry.key === key);
+    if (!node)
+      throw new Error(`goal node not found: ${goalId}/${key}`);
+    return node;
+  }
+  recordGoalEvent(input, opts = {}) {
+    const goal = this.requireGoal(input.goalId);
+    const now = nowIso();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.assertDaemonLeaseFence(opts, now);
+      const previous = this.db.query("SELECT MAX(turn) AS turn FROM goal_runs WHERE goal_id = ?").get(goal.goalId);
+      const turn = input.turn ?? (previous?.turn ?? 0) + 1;
+      const id = genId();
+      this.db.query(`INSERT INTO goal_runs (id, goal_id, plan_id, loop_id, loop_run_id, workflow_id, workflow_run_id, workflow_step_id,
+            turn, phase, status, node_key, tokens_used, evidence_json, raw_response_json, created_at, updated_at)
+           VALUES ($id, $goalId, $planId, $loopId, $loopRunId, $workflowId, $workflowRunId, $workflowStepId,
+            $turn, $phase, $status, $nodeKey, $tokensUsed, $evidence, $rawResponse, $created, $updated)`).run({
+        $id: id,
+        $goalId: goal.goalId,
+        $planId: goal.planId,
+        $loopId: goal.loopId ?? null,
+        $loopRunId: goal.loopRunId ?? null,
+        $workflowId: goal.workflowId ?? null,
+        $workflowRunId: goal.workflowRunId ?? null,
+        $workflowStepId: goal.workflowStepId ?? null,
+        $turn: turn,
+        $phase: input.phase,
+        $status: input.status,
+        $nodeKey: input.nodeKey ?? null,
+        $tokensUsed: input.tokensUsed ?? 0,
+        $evidence: input.evidence ? JSON.stringify(input.evidence) : null,
+        $rawResponse: input.rawResponse === undefined ? null : JSON.stringify(input.rawResponse),
+        $created: now,
+        $updated: now
+      });
+      if (input.tokensUsed && input.tokensUsed > 0) {
+        this.db.query("UPDATE goals SET tokens_used=tokens_used + ?, updated_at=? WHERE id=?").run(input.tokensUsed, now, goal.goalId);
+      }
+      this.db.exec("COMMIT");
+      const event = this.db.query("SELECT * FROM goal_runs WHERE id = ?").get(id);
+      if (!event)
+        throw new Error(`goal run not found after record: ${id}`);
+      return rowToGoalRun(event);
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  listGoalRuns(opts = {}) {
+    const limit = opts.limit ?? 200;
+    let rows;
+    if (opts.goalId) {
+      rows = this.db.query("SELECT * FROM goal_runs WHERE goal_id = ? ORDER BY created_at ASC LIMIT ?").all(opts.goalId, limit);
+    } else if (opts.runId) {
+      rows = this.db.query(`SELECT * FROM goal_runs
+           WHERE id = ? OR loop_run_id = ? OR workflow_run_id = ?
+           ORDER BY created_at ASC LIMIT ?`).all(opts.runId, opts.runId, opts.runId, limit);
+    } else {
+      rows = this.db.query("SELECT * FROM goal_runs ORDER BY created_at DESC LIMIT ?").all(limit);
+    }
+    return rows.map(rowToGoalRun);
+  }
   createWorkflowRun(input) {
     const now = nowIso();
     if (input.idempotencyKey) {