@osolmaz/pi-workflows 0.4.0 → 0.5.0

package/docs/plans/2026-08-13-session-addressed-workflow-notifications-plan.md

@@ -0,0 +1,95 @@
+---
+title: Route workflow reports to their starting session
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-13
+---
+
+# Route workflow reports to their starting session
+
+Pi Workflows must not send one workflow's report into an unrelated conversation. A workflow started in one Pi session must report only to that session, even when another session or the standalone host executes part of the run.
+
+## Requirements
+
+- Record the starting Pi session as the origin of each interactive workflow run.
+- Keep execution events separate from user-facing notifications.
+- Store each notification durably and address it to one Pi session.
+- Deliver a notification only when its target session is open.
+- Keep undelivered notifications until the target session opens again.
+- Prevent unrelated sessions from claiming session-bound runs.
+- Permit a detached host to execute a run without changing its report target.
+- Give workflow authors a runtime-owned notification node instead of using an agent step to relay text.
+- Migrate active path-based runs and existing queue rows without guessing their origin.
+- Remove project-wide hidden-message broadcasts and the shared project watermark.
+
+## Data model
+
+Queue records gain an optional `origin_session_id`. Interactive runs set it from `ctx.sessionManager.getSessionId()`. Controller-created detached runs leave it empty. A session runner can claim a record only when the origin is empty or matches its current session. The standalone host can claim either form.
+
+A `workflow_notifications` table is the durable outbox:
+
+| Field                       | Meaning                                             |
+| --------------------------- | --------------------------------------------------- |
+| `notification_id`           | Stable unique delivery ID                           |
+| `run_id`                    | Workflow run that created the notification          |
+| `node_id`                   | Node that created it                                |
+| `attempt_id`                | Latest node attempt that requested it               |
+| `notification_index`        | Stable one-based occurrence of this node in the run |
+| `target_session_id`         | Exact Pi session that may receive it                |
+| `kind`                      | `progress` or `final`                               |
+| `content`                   | Bounded plain-text report                           |
+| `created_at`                | Creation time                                       |
+| `delivery_claim_token`      | Current delivery owner, or null                     |
+| `delivery_claim_expires_at` | Delivery lease deadline, or null                    |
+| `delivered_at`              | Delivery time, or null while pending                |
+
+`(run_id, node_id, notification_index)` is unique. A crash retry reuses the same logical index, even though it gets a new attempt ID. A later loop iteration gets the next index. Delivery polling claims pending rows with a short lease before it writes to a session. This prevents two Pi processes that open the same session from sending the same notification concurrently. If a process stops, another process can reclaim the row after the lease expires. A stable notification ID is included in the custom session entry so the same session can detect a delivery completed before a crash.
+
+The existing `run_events` table remains an execution audit feed. It does not inject conversation messages. The obsolete `session_watermarks` table is no longer used.
+
+## Workflow API
+
+Add a `notify(...)` node. Its message callback returns plain text. The engine calls a host-provided notification sink and persists the resulting receipt as the node output. The node does not ask the model to relay a message and does not depend on the runner's active conversation.
+
+The built-in monitor uses `notify` for progress and final reports. Its check agent still decides whether a report is needed, but delivery always targets the origin session.
+
+## Migration
+
+For each active run with a queue row and no origin:
+
+1. Read `session/binding.json` from its run bundle.
+2. If the binding exists, set `origin_session_id` to its `piSessionId`.
+3. If no binding exists, keep the run detached.
+4. Never infer an origin from the working directory.
+
+Existing lifecycle events are not converted into notifications. This prevents old completion events from appearing in unrelated sessions after the update.
+
+## Non-goals
+
+- Do not modify Pi core or Pi session files directly.
+- Do not broadcast workflow reports to all sessions in a project.
+- Do not keep compatibility aliases for the shared project watermark behavior.
+- Do not make closed Pi sessions execute workflow steps.
+
+## Acceptance criteria
+
+- Two open Pi sessions in the same directory cannot receive each other's workflow reports.
+- A report executed by the standalone host is delivered after the origin session opens.
+- A report remains pending while its origin session is closed.
+- A session-bound run is not claimed by a different interactive session.
+- Duplicate polling and process restart do not duplicate a delivered notification.
+- Monitor progress and final reports use the notification outbox.
+- Existing active runs gain their recorded binding as origin when available.
+- Pi starts with the released package in OnurPi.
+
+## Verification
+
+- `npm run check`
+- `npm run test:e2e`
+- `npm run slophammer`
+- `git diff --check`
+- `npx -y @simpledoc/simpledoc check`
+- `cargo fmt --check --manifest-path tui/Cargo.toml`
+- `cargo clippy --manifest-path tui/Cargo.toml --all-targets --all-features -- -D warnings`
+- `cargo test --manifest-path tui/Cargo.toml`
+- `pi-reviewer --base main`
+- Start two isolated RPC Pi sessions in one directory and prove that only the matching session receives a targeted notification.

package/docs/workflows.md

@@ -117,10 +117,9 @@ Conversation nodes execute in headless `pi --mode rpc` children that load a
 small bridge extension; the model sees the same `workflow` tool contract as an
 in-session run. The host is a foreground process: start it in a terminal and
 stop it with Ctrl-C. A second host for the same project refuses to start, and
-a host that dies has its orphaned children reaped by the next one. While the
-host works, any open Pi session stays current: a per-session watermark over
-the shared run event feed produces catch-up summaries and quiet context
-updates.
+a host that dies has its orphaned children reaped by the next one. While the host works, reports enter a durable outbox addressed to the Pi
+session that started the run. They remain pending while that session is closed
+and never enter another conversation in the same project.
 
 ## Node types
 
@@ -165,6 +164,26 @@ Runs a TypeScript function inline. Use it for pure data shaping.
 compute({ run: ({ outputs }) => ({ merged: { ...outputs } }) });
 ```
 
+### notify
+
+Queues a durable plain-text message for the Pi session that started the run.
+The runner does not write the message into its own conversation. A standalone
+host can execute this node, and the message still waits for the origin session.
+
+```typescript
+notify({
+  kind: "progress", // or "final"
+  message: ({ outputs }) => String(outputs.check),
+});
+```
+
+The runtime gives each logical execution of a notification node a stable index.
+A retry after a crash reuses that index, so it cannot queue the same message
+twice. Re-entering the node later in a loop gets the next index. A workflow
+with a `notify` node must be an interactive queued run with an origin session.
+Controller child workflows are detached and must report through their
+controller resource instead.
+
 ### action
 
 Performs a side effect. Two forms exist. The function form runs arbitrary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/src/builtins/catalog.ts

@@ -4,12 +4,12 @@ import monitorWorkflow from "./monitor.workflow.js";
 export const builtinWorkflowCatalog = new BuiltinWorkflowCatalog([
   {
     id: "monitor",
-    revision: "1",
+    revision: "2",
     definition: monitorWorkflow,
     legacySources: [
       {
         workflowHash: "7a22158da94d18ec1c9fe42e70d72017a4e0620d5e5142ae839d0cd6eea55c06",
-        revision: "1",
+        revision: "2",
         pathSuffixes: [
           "/src/builtins/monitor.workflow.ts",
           "/dist/builtins/monitor.workflow.js",
@@ -17,6 +17,16 @@ export const builtinWorkflowCatalog = new BuiltinWorkflowCatalog([
           "/dist/workflows/monitor.workflow.js",
         ],
       },
+      {
+        workflowHash: "352fc09c88922c7375281b52f049c1039d05441ce37f2082f5ff07fea66d5318",
+        revision: "2",
+        pathSuffixes: ["/dist/builtins/monitor.workflow.js"],
+      },
+      {
+        workflowHash: "dc601e2323a8213f5d52fa555e804ae8ed0846f809b3a1e9e5073a3c9c3a114e",
+        revision: "2",
+        pathSuffixes: ["/dist/builtins/monitor.workflow.js"],
+      },
     ],
   },
 ]);

package/src/builtins/monitor.workflow.ts

@@ -1,4 +1,4 @@
-import { agent, compute, defineWorkflow, shell } from "../workflows/definition.js";
+import { agent, compute, defineWorkflow, notify, shell } from "../workflows/definition.js";
 import type { WorkflowNodeContext } from "../workflows/types.js";
 
 const MIN_INTERVAL_MINUTES = 1;
@@ -150,22 +150,9 @@ function validateCheck(output: unknown): MonitorCheck {
   };
 }
 
-function validateReportAck(output: unknown): { reported: true } {
-  const value = requireRecord(output, "report acknowledgement");
-  if (value.reported !== true) {
-    throw new Error("report acknowledgement must set reported to true");
-  }
-  return { reported: true };
-}
-
-function reportPrompt(outputs: Record<string, unknown>): string {
+function reportMessage(outputs: Record<string, unknown>): string {
   const check = outputs.check as MonitorCheck;
-  return [
-    "Write one concise normal assistant message to the user with this monitoring update:",
-    check.report ?? check.observation,
-    "Do not add unrelated detail.",
-    "After writing the update, submit the acknowledgement required by the workflow step contract.",
-  ].join("\n\n");
+  return check.report ?? check.observation;
 }
 
 export default defineWorkflow({
@@ -232,19 +219,15 @@ export default defineWorkflow({
         '{ "route": "continue_quiet" | "continue_report" | "stop_quiet" | "stop_report", "observation": "current factual state", "report": "required for report routes", "reason": "short reason" }',
       validate: (output) => validateCheck(output),
     }),
-    report_continue: agent({
-      statusDetail: "reporting monitor update",
-      timeoutMs: agentTimeoutMs,
-      prompt: ({ outputs }) => reportPrompt(outputs),
-      expectedOutput: '{ "reported": true }',
-      validate: (output) => validateReportAck(output),
+    report_continue: notify({
+      statusDetail: "queueing monitor update",
+      message: ({ outputs }) => reportMessage(outputs),
+      kind: "progress",
     }),
-    report_stop: agent({
-      statusDetail: "reporting final monitor update",
-      timeoutMs: agentTimeoutMs,
-      prompt: ({ outputs }) => reportPrompt(outputs),
-      expectedOutput: '{ "reported": true }',
-      validate: (output) => validateReportAck(output),
+    report_stop: notify({
+      statusDetail: "queueing final monitor update",
+      message: ({ outputs }) => reportMessage(outputs),
+      kind: "final",
     }),
     sleep: shell({
       statusDetail: "waiting for next monitor check",

package/src/controllers/index.ts

@@ -23,6 +23,7 @@ export { createResultHelpers, requeue, requeueAfter, settled } from "./results.j
 export {
   SqliteControllerStore,
   type RunEventRecord,
+  type WorkflowNotificationRecord,
   type WorkflowRunQueueRecord,
 } from "./sqlite.js";
 export {

package/src/controllers/sqlite.ts

@@ -93,6 +93,7 @@ type WorkflowRunQueueRow = {
   claim_token: string | null;
   claim_expires_at: number | null;
   affinity_runner_id: string | null;
+  origin_session_id: string | null;
   parent_run_id: string | null;
   created_at: string;
   updated_at: string;
@@ -111,11 +112,42 @@ export type WorkflowRunQueueRecord = {
   claimToken: string | null;
   claimExpiresAt: string | null;
   affinityRunnerId: string | null;
+  /** Pi session that owns delivery and interactive execution, or null for detached runs. */
+  originSessionId: string | null;
   parentRunId: string | null;
   createdAt: string;
   updatedAt: string;
 };
 
+type WorkflowNotificationRow = {
+  notification_id: string;
+  run_id: string;
+  node_id: string;
+  attempt_id: string;
+  notification_index: number;
+  target_session_id: string;
+  kind: "progress" | "final";
+  content: string;
+  created_at: string;
+  delivery_claim_token: string | null;
+  delivery_claim_expires_at: number | null;
+  delivered_at: string | null;
+};
+
+export type WorkflowNotificationRecord = {
+  notificationId: string;
+  runId: string;
+  nodeId: string;
+  attemptId: string;
+  notificationIndex: number;
+  targetSessionId: string;
+  kind: "progress" | "final";
+  content: string;
+  createdAt: string;
+  deliveryClaimExpiresAt: string | null;
+  deliveredAt: string | null;
+};
+
 type RunEventRow = {
   seq: number;
   recorded_at: string;
@@ -774,6 +806,13 @@ export class SqliteControllerStore implements ControllerStore {
         .prepare("INSERT OR IGNORE INTO schema_info (singleton, schema_id) VALUES (1, ?)")
         .run(CONTROLLER_STORE_SCHEMA);
       this.database.exec(SCHEMA_SQL);
+      const queueColumns = this.database.pragma("table_info(workflow_run_queue)") as {
+        name: string;
+      }[];
+      if (!queueColumns.some((column) => column.name === "origin_session_id")) {
+        this.database.exec("ALTER TABLE workflow_run_queue ADD COLUMN origin_session_id TEXT");
+      }
+      this.database.exec("DROP TABLE IF EXISTS session_watermarks");
     });
   }
 
@@ -875,6 +914,7 @@ export class SqliteControllerStore implements ControllerStore {
     claimToken: string;
     leaseMs: number;
     affinityRunnerId?: string;
+    originSessionId?: string;
     parentRunId?: string;
     now?: string;
   }): WorkflowRunQueueRecord {
@@ -884,6 +924,9 @@ export class SqliteControllerStore implements ControllerStore {
     validateKey(options.runnerId, "runner id");
     validateKey(options.claimToken, "claim token");
     validateDuration(options.leaseMs, "leaseMs");
+    if (options.originSessionId !== undefined) {
+      validateKey(options.originSessionId, "origin session id");
+    }
     const inputJson = canonicalJson(options.input ?? null, "workflow run input");
     validateJsonSize(inputJson, "Workflow run input", MAX_RESOURCE_VALUE_BYTES);
     const now = validTimestamp(options.now);
@@ -893,8 +936,8 @@ export class SqliteControllerStore implements ControllerStore {
         `INSERT INTO workflow_run_queue (
           run_id, workflow_ref, workflow_path, input_json, status,
           runner_id, claim_token, claim_expires_at, affinity_runner_id,
-          parent_run_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, 'claimed', ?, ?, ?, ?, ?, ?, ?)`,
+          origin_session_id, parent_run_id, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, 'claimed', ?, ?, ?, ?, ?, ?, ?, ?)`,
       )
       .run(
         options.runId,
@@ -905,6 +948,7 @@ export class SqliteControllerStore implements ControllerStore {
         options.claimToken,
         expiresAt,
         options.affinityRunnerId ?? options.runnerId,
+        options.originSessionId ?? null,
         options.parentRunId ?? null,
         now,
         now,
@@ -945,11 +989,14 @@ export class SqliteControllerStore implements ControllerStore {
     claimToken: string;
     leaseMs: number;
     excludeRunIds?: string[];
+    /** Interactive sessions provide their id; detached hosts omit it. */
+    sessionId?: string;
     now?: string;
   }): WorkflowRunQueueRecord | undefined {
     validateKey(options.runnerId, "runner id");
     validateKey(options.claimToken, "claim token");
     validateDuration(options.leaseMs, "leaseMs");
+    if (options.sessionId !== undefined) validateKey(options.sessionId, "session id");
     const now = validTimestamp(options.now);
     const nowMs = epoch(now);
     const expiresAt = nowMs + options.leaseMs;
@@ -959,6 +1006,10 @@ export class SqliteControllerStore implements ControllerStore {
     }
     const exclusion =
       excluded.length === 0 ? "" : `AND run_id NOT IN (${excluded.map(() => "?").join(", ")})`;
+    const sessionFilter =
+      options.sessionId === undefined
+        ? ""
+        : "AND (origin_session_id IS NULL OR origin_session_id = ?)";
     const claimable = `(
       status = 'parked'
       OR (status = 'claimed' AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
@@ -967,13 +1018,18 @@ export class SqliteControllerStore implements ControllerStore {
       const candidate = this.database
         .prepare(
           `SELECT run_id FROM workflow_run_queue
-           WHERE ${claimable} ${exclusion}
+           WHERE ${claimable} ${exclusion} ${sessionFilter}
            ORDER BY
              CASE WHEN affinity_runner_id = ? THEN 0 ELSE 1 END,
              created_at ASC
            LIMIT 1`,
         )
-        .get(nowMs, ...excluded, options.runnerId) as { run_id: string } | undefined;
+        .get(
+          nowMs,
+          ...excluded,
+          ...(options.sessionId === undefined ? [] : [options.sessionId]),
+          options.runnerId,
+        ) as { run_id: string } | undefined;
       if (candidate === undefined) {
         return undefined;
       }
@@ -1235,37 +1291,141 @@ export class SqliteControllerStore implements ControllerStore {
     }));
   }
 
-  /** The highest run event seq in the feed; 0 when empty. */
-  latestRunEventSeq(): number {
-    const row = this.database.prepare("SELECT MAX(seq) AS latest FROM run_events").get() as {
-      latest: number | null;
-    };
-    return row.latest ?? 0;
-  }
-
-  /** The last run event this session was told about; 0 before any sync. */
-  getSessionWatermark(sessionId: string): number {
-    validateKey(sessionId, "session id");
+  enqueueWorkflowNotification(options: {
+    runId: string;
+    nodeId: string;
+    attemptId: string;
+    notificationIndex: number;
+    targetSessionId: string;
+    kind: "progress" | "final";
+    content: string;
+    notificationId?: string;
+    now?: string;
+  }): WorkflowNotificationRecord {
+    validateRunId(options.runId);
+    validateKey(options.nodeId, "workflow node id");
+    validateKey(options.attemptId, "workflow attempt id");
+    if (!Number.isSafeInteger(options.notificationIndex) || options.notificationIndex <= 0) {
+      throw new Error("Workflow notification index must be a positive safe integer");
+    }
+    validateKey(options.targetSessionId, "target session id");
+    if (options.content.trim().length === 0 || options.content.length > MAX_EVENT_BYTES) {
+      throw new Error(`Workflow notification content must be 1-${MAX_EVENT_BYTES} characters`);
+    }
+    const notificationId = options.notificationId ?? randomUUID();
+    validateKey(notificationId, "notification id");
+    this.database
+      .prepare(
+        `INSERT INTO workflow_notifications (
+          notification_id, run_id, node_id, attempt_id, notification_index,
+          target_session_id, kind, content, created_at, delivered_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+        ON CONFLICT(run_id, node_id, notification_index) DO NOTHING`,
+      )
+      .run(
+        notificationId,
+        options.runId,
+        options.nodeId,
+        options.attemptId,
+        options.notificationIndex,
+        options.targetSessionId,
+        options.kind,
+        options.content.trim(),
+        validTimestamp(options.now),
+      );
     const row = this.database
-      .prepare("SELECT last_event_seq FROM session_watermarks WHERE session_id = ?")
-      .get(sessionId) as { last_event_seq: number } | undefined;
-    return row?.last_event_seq ?? 0;
+      .prepare(
+        "SELECT * FROM workflow_notifications WHERE run_id = ? AND node_id = ? AND notification_index = ?",
+      )
+      .get(options.runId, options.nodeId, options.notificationIndex) as WorkflowNotificationRow;
+    return workflowNotificationFromRow(row);
   }
 
-  setSessionWatermark(sessionId: string, seq: number, now?: string): void {
-    validateKey(sessionId, "session id");
-    if (!Number.isSafeInteger(seq) || seq < 0) {
-      throw new Error(`Invalid run event watermark: ${seq}`);
+  claimPendingWorkflowNotifications(options: {
+    targetSessionId: string;
+    claimToken: string;
+    leaseMs: number;
+    limit?: number;
+    now?: string;
+  }): WorkflowNotificationRecord[] {
+    validateKey(options.targetSessionId, "target session id");
+    validateKey(options.claimToken, "notification claim token");
+    validateDuration(options.leaseMs, "notification leaseMs");
+    const limit = options.limit ?? 20;
+    if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+      throw new Error("Workflow notification limit must be an integer from 1 through 100");
     }
-    this.database
+    const now = validTimestamp(options.now);
+    const nowMs = epoch(now);
+    return this.transaction(() => {
+      const ids = this.database
+        .prepare(
+          `SELECT notification_id FROM workflow_notifications
+           WHERE target_session_id = ? AND delivered_at IS NULL
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)
+           ORDER BY created_at, notification_id LIMIT ?`,
+        )
+        .all(options.targetSessionId, nowMs, limit) as { notification_id: string }[];
+      if (ids.length === 0) return [];
+      const placeholders = ids.map(() => "?").join(", ");
+      this.database
+        .prepare(
+          `UPDATE workflow_notifications
+           SET delivery_claim_token = ?, delivery_claim_expires_at = ?
+           WHERE notification_id IN (${placeholders}) AND delivered_at IS NULL
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)`,
+        )
+        .run(
+          options.claimToken,
+          nowMs + options.leaseMs,
+          ...ids.map((row) => row.notification_id),
+          nowMs,
+        );
+      const rows = this.database
+        .prepare(
+          `SELECT * FROM workflow_notifications WHERE delivery_claim_token = ?
+           ORDER BY created_at, notification_id`,
+        )
+        .all(options.claimToken) as WorkflowNotificationRow[];
+      return rows.map(workflowNotificationFromRow);
+    });
+  }
+
+  markWorkflowNotificationDelivered(options: {
+    notificationId: string;
+    targetSessionId: string;
+    claimToken: string;
+    now?: string;
+  }): boolean {
+    validateKey(options.notificationId, "notification id");
+    validateKey(options.targetSessionId, "target session id");
+    validateKey(options.claimToken, "notification claim token");
+    const result = this.database
+      .prepare(
+        `UPDATE workflow_notifications
+         SET delivered_at = ?, delivery_claim_token = NULL, delivery_claim_expires_at = NULL
+         WHERE notification_id = ? AND target_session_id = ?
+           AND delivery_claim_token = ? AND delivered_at IS NULL`,
+      )
+      .run(
+        validTimestamp(options.now),
+        options.notificationId,
+        options.targetSessionId,
+        options.claimToken,
+      );
+    return result.changes === 1;
+  }
+
+  setWorkflowRunOriginSession(runId: string, originSessionId: string): boolean {
+    validateRunId(runId);
+    validateKey(originSessionId, "origin session id");
+    const result = this.database
       .prepare(
-        `INSERT INTO session_watermarks (session_id, last_event_seq, updated_at)
-         VALUES (?, ?, ?)
-         ON CONFLICT(session_id) DO UPDATE SET
-           last_event_seq = MAX(session_watermarks.last_event_seq, excluded.last_event_seq),
-           updated_at = excluded.updated_at`,
+        `UPDATE workflow_run_queue SET origin_session_id = ?
+         WHERE run_id = ? AND origin_session_id IS NULL`,
       )
-      .run(sessionId, seq, validTimestamp(now));
+      .run(originSessionId, runId);
+    return result.changes === 1;
   }
 
   private requireWorkflowRun(runId: string): WorkflowRunQueueRecord {
@@ -1329,6 +1489,7 @@ const SCHEMA_SQL = `
     claim_token TEXT,
     claim_expires_at INTEGER,
     affinity_runner_id TEXT,
+    origin_session_id TEXT,
     parent_run_id TEXT,
     created_at TEXT NOT NULL,
     updated_at TEXT NOT NULL
@@ -1351,11 +1512,24 @@ const SCHEMA_SQL = `
   );
   CREATE INDEX IF NOT EXISTS run_events_run ON run_events(run_id);
 
-  CREATE TABLE IF NOT EXISTS session_watermarks (
-    session_id TEXT PRIMARY KEY,
-    last_event_seq INTEGER NOT NULL CHECK (last_event_seq >= 0),
-    updated_at TEXT NOT NULL
+  CREATE TABLE IF NOT EXISTS workflow_notifications (
+    notification_id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    node_id TEXT NOT NULL,
+    attempt_id TEXT NOT NULL,
+    notification_index INTEGER NOT NULL CHECK (notification_index > 0),
+    target_session_id TEXT NOT NULL,
+    kind TEXT NOT NULL CHECK (kind IN ('progress', 'final')),
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    delivery_claim_token TEXT,
+    delivery_claim_expires_at INTEGER,
+    delivered_at TEXT,
+    UNIQUE (run_id, node_id, notification_index)
   );
+  CREATE INDEX IF NOT EXISTS workflow_notifications_pending
+    ON workflow_notifications(target_session_id, delivery_claim_expires_at, created_at)
+    WHERE delivered_at IS NULL;
 
   CREATE TABLE IF NOT EXISTS effects (
     effect_key TEXT NOT NULL,
@@ -1447,6 +1621,23 @@ function workflowFromRow(row: WorkflowRow): ChildWorkflowRecord {
   };
 }
 
+function workflowNotificationFromRow(row: WorkflowNotificationRow): WorkflowNotificationRecord {
+  return {
+    notificationId: row.notification_id,
+    runId: row.run_id,
+    nodeId: row.node_id,
+    attemptId: row.attempt_id,
+    notificationIndex: row.notification_index,
+    targetSessionId: row.target_session_id,
+    kind: row.kind,
+    content: row.content,
+    createdAt: row.created_at,
+    deliveryClaimExpiresAt:
+      row.delivery_claim_expires_at === null ? null : iso(row.delivery_claim_expires_at),
+    deliveredAt: row.delivered_at,
+  };
+}
+
 function workflowRunFromRow(row: WorkflowRunQueueRow): WorkflowRunQueueRecord {
   return {
     runId: row.run_id,
@@ -1458,6 +1649,7 @@ function workflowRunFromRow(row: WorkflowRunQueueRow): WorkflowRunQueueRecord {
     claimToken: row.claim_token,
     claimExpiresAt: row.claim_expires_at === null ? null : iso(row.claim_expires_at),
     affinityRunnerId: row.affinity_runner_id,
+    originSessionId: row.origin_session_id,
     parentRunId: row.parent_run_id,
     createdAt: row.created_at,
     updatedAt: row.updated_at,