@opentag/store 0.3.0 → 0.3.1

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/repository.ts
+import { createHash } from "crypto";
 import {
   ApprovalDecisionSchema,
   ApplyIntentOutcomeSchema,
@@ -13,6 +14,7 @@ import {
   PolicyRuleSchema,
   ProposalLineageSchema,
   preflightMutationIntent,
+  formatProjectTargetRef,
   projectTargetRefFromEvent,
   protocolRunFieldsFromEvent,
   RunAdmissionDecisionSchema,
@@ -20,7 +22,7 @@ import {
   RunEventVisibilitySchema,
   SuggestedChangesSnapshotSchema
 } from "@opentag/core";
-import { and, asc, eq, inArray } from "drizzle-orm";
+import { and, asc, desc, eq, inArray, lt } from "drizzle-orm";
 
 // src/schema.ts
 import { index, integer, primaryKey, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
@@ -93,6 +95,35 @@ var runEvents = sqliteTable(
     runIdx: index("run_events_run_idx").on(table.runId)
   })
 );
+var sourceDeliveries = sqliteTable(
+  "source_deliveries",
+  {
+    source: text("source").notNull(),
+    deliveryId: text("delivery_id").notNull(),
+    runId: text("run_id").notNull(),
+    eventId: text("event_id").notNull(),
+    createdAt: text("created_at").notNull()
+  },
+  (table) => ({
+    pk: primaryKey({ columns: [table.source, table.deliveryId] }),
+    runIdx: index("source_deliveries_run_idx").on(table.runId)
+  })
+);
+var controlPlaneEvents = sqliteTable(
+  "control_plane_events",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    type: text("type").notNull(),
+    severity: text("severity").notNull(),
+    subject: text("subject"),
+    payloadJson: text("payload_json").notNull(),
+    createdAt: text("created_at").notNull()
+  },
+  (table) => ({
+    typeIdx: index("control_plane_events_type_idx").on(table.type),
+    severityIdx: index("control_plane_events_severity_idx").on(table.severity)
+  })
+);
 var suggestedChanges = sqliteTable("suggested_changes", {
   proposalId: text("proposal_id").primaryKey(),
   runId: text("run_id").notNull(),
@@ -194,6 +225,7 @@ var callbackDeliveries = sqliteTable(
     uri: text("uri").notNull(),
     body: text("body").notNull(),
     threadKey: text("thread_key"),
+    idempotencyKey: text("idempotency_key"),
     metadataJson: text("metadata_json"),
     status: text("status").notNull(),
     attempts: integer("attempts").notNull().default(0),
@@ -204,7 +236,8 @@ var callbackDeliveries = sqliteTable(
   },
   (table) => ({
     callbackRunIdx: index("callback_deliveries_run_idx").on(table.runId),
-    callbackStatusIdx: index("callback_deliveries_status_idx").on(table.status)
+    callbackStatusIdx: index("callback_deliveries_status_idx").on(table.status),
+    callbackIdempotencyIdx: uniqueIndex("callback_deliveries_idempotency_key_idx").on(table.idempotencyKey)
   })
 );
 function migrateSchema(sqlite) {
@@ -247,6 +280,28 @@ function migrateSchema(sqlite) {
       created_at TEXT NOT NULL
     );
     CREATE INDEX IF NOT EXISTS run_events_run_idx ON run_events(run_id);
+    CREATE TABLE IF NOT EXISTS source_deliveries (
+      source TEXT NOT NULL,
+      delivery_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      event_id TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY (source, delivery_id)
+    );
+    CREATE INDEX IF NOT EXISTS source_deliveries_run_idx
+      ON source_deliveries(run_id);
+    CREATE TABLE IF NOT EXISTS control_plane_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      severity TEXT NOT NULL,
+      subject TEXT,
+      payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS control_plane_events_type_idx
+      ON control_plane_events(type);
+    CREATE INDEX IF NOT EXISTS control_plane_events_severity_idx
+      ON control_plane_events(severity);
     CREATE TABLE IF NOT EXISTS suggested_changes (
       proposal_id TEXT PRIMARY KEY,
       run_id TEXT NOT NULL,
@@ -328,6 +383,7 @@ function migrateSchema(sqlite) {
       uri TEXT NOT NULL,
       body TEXT NOT NULL,
       thread_key TEXT,
+      idempotency_key TEXT,
       metadata_json TEXT,
       status TEXT NOT NULL,
       attempts INTEGER NOT NULL DEFAULT 0,
@@ -340,6 +396,8 @@ function migrateSchema(sqlite) {
       ON callback_deliveries(run_id);
     CREATE INDEX IF NOT EXISTS callback_deliveries_status_idx
       ON callback_deliveries(status);
+    CREATE UNIQUE INDEX IF NOT EXISTS callback_deliveries_idempotency_key_idx
+      ON callback_deliveries(idempotency_key);
     CREATE TABLE IF NOT EXISTS follow_up_requests (
       id TEXT PRIMARY KEY,
       source_event_id TEXT NOT NULL,
@@ -446,6 +504,29 @@ function migrateSchema(sqlite) {
     sqlite.exec("ALTER TABLE run_events ADD COLUMN message TEXT");
   }
   sqlite.exec("CREATE INDEX IF NOT EXISTS run_events_run_idx ON run_events(run_id)");
+  sqlite.exec(`
+    CREATE TABLE IF NOT EXISTS source_deliveries (
+      source TEXT NOT NULL,
+      delivery_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      event_id TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY (source, delivery_id)
+    );
+  `);
+  sqlite.exec("CREATE INDEX IF NOT EXISTS source_deliveries_run_idx ON source_deliveries(run_id)");
+  sqlite.exec(`
+    CREATE TABLE IF NOT EXISTS control_plane_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      severity TEXT NOT NULL,
+      subject TEXT,
+      payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+  `);
+  sqlite.exec("CREATE INDEX IF NOT EXISTS control_plane_events_type_idx ON control_plane_events(type)");
+  sqlite.exec("CREATE INDEX IF NOT EXISTS control_plane_events_severity_idx ON control_plane_events(severity)");
   sqlite.exec("CREATE UNIQUE INDEX IF NOT EXISTS repo_policy_rules_repo_id_idx ON repo_policy_rules(provider, owner, repo, id)");
   sqlite.exec("CREATE UNIQUE INDEX IF NOT EXISTS repo_mutation_mappings_repo_id_idx ON repo_mutation_mappings(provider, owner, repo, id)");
   const callbackColumns = sqlite.prepare("PRAGMA table_info(callback_deliveries)").all();
@@ -456,6 +537,10 @@ function migrateSchema(sqlite) {
   if (!callbackColumnNames.has("metadata_json")) {
     sqlite.exec("ALTER TABLE callback_deliveries ADD COLUMN metadata_json TEXT");
   }
+  if (!callbackColumnNames.has("idempotency_key")) {
+    sqlite.exec("ALTER TABLE callback_deliveries ADD COLUMN idempotency_key TEXT");
+  }
+  sqlite.exec("CREATE UNIQUE INDEX IF NOT EXISTS callback_deliveries_idempotency_key_idx ON callback_deliveries(idempotency_key)");
   const legacySlackTable = sqlite.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'slack_channel_bindings'").get();
   if (legacySlackTable) {
     sqlite.exec(`
@@ -512,8 +597,18 @@ function runFromRow(row) {
     ...result ? { result } : {}
   };
 }
+function terminalRunStatus(status) {
+  return status === "succeeded" || status === "failed" || status === "cancelled" || status === "interrupted" || status === "timed_out";
+}
+function sourceContainerMetadataMatches(input) {
+  if (input.event.source !== input.source) return false;
+  return Object.entries(input.metadata).every(([key, value]) => input.event.metadata[key] === value);
+}
+function callbackDeliveryMetadataFromJson(metadataJson) {
+  return metadataJson && typeof metadataJson === "string" ? JSON.parse(metadataJson) : void 0;
+}
 function callbackDeliveryFromRow(row) {
-  const metadata = row.metadataJson && typeof row.metadataJson === "string" ? JSON.parse(row.metadataJson) : void 0;
+  const metadata = callbackDeliveryMetadataFromJson(row.metadataJson);
   return {
     id: row.id,
     runId: row.runId,
@@ -522,9 +617,12 @@ function callbackDeliveryFromRow(row) {
     uri: row.uri,
     body: row.body,
     ...row.threadKey ? { threadKey: row.threadKey } : {},
+    ...row.idempotencyKey ? { idempotencyKey: row.idempotencyKey } : {},
     ...metadata?.agentId ? { agentId: metadata.agentId } : {},
     ...metadata?.statusMessageKey ? { statusMessageKey: metadata.statusMessageKey } : {},
+    ...metadata?.externalMessageId ? { externalMessageId: metadata.externalMessageId } : {},
     ...metadata?.blocks ? { blocks: metadata.blocks } : {},
+    ...metadata && "rich" in metadata ? { rich: metadata.rich } : {},
     status: row.status,
     attempts: row.attempts,
     ...row.lastError ? { lastError: row.lastError } : {},
@@ -533,6 +631,19 @@ function callbackDeliveryFromRow(row) {
     updatedAt: row.updatedAt
   };
 }
+function callbackBodyHash(input) {
+  return createHash("sha256").update(JSON.stringify({ body: input.body, blocks: input.blocks ?? [], rich: input.rich ?? null })).digest("hex");
+}
+function callbackIdempotencyKey(input) {
+  return [
+    input.runId,
+    input.provider,
+    input.threadKey ?? input.uri,
+    input.kind,
+    input.statusMessageKey ?? "",
+    callbackBodyHash({ body: input.body, ...input.blocks ? { blocks: input.blocks } : {}, ...input.rich !== void 0 ? { rich: input.rich } : {} })
+  ].join("|");
+}
 function followUpRequestFromRow(row) {
   return {
     id: row.id,
@@ -564,6 +675,69 @@ function recordFromJson(value) {
     return void 0;
   }
 }
+function metadataString(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  return null;
+}
+function metadataBoolean(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "boolean") return value;
+  }
+  return null;
+}
+function signatureStateFromEvent(event) {
+  const explicitState = metadataString(event.metadata, ["signatureState", "webhookSignatureState"]);
+  if (explicitState === "verified" || explicitState === "unverified" || explicitState === "unknown") return explicitState;
+  const verified = metadataBoolean(event.metadata, [
+    "signatureVerified",
+    "verifiedSignature",
+    "webhookSignatureVerified",
+    "githubSignatureVerified"
+  ]);
+  if (verified === true) return "verified";
+  if (verified === false) return "unverified";
+  return "unknown";
+}
+function sourceDeliveryIdFromEvent(event) {
+  return metadataString(event.metadata, [
+    "sourceDeliveryId",
+    "webhookDeliveryId",
+    "deliveryId",
+    "githubDeliveryId",
+    "githubDeliveryGuid",
+    "slackEventId",
+    "larkEventId"
+  ]);
+}
+function projectTargetProvenance(ref) {
+  if (!ref) return null;
+  return {
+    ref: formatProjectTargetRef(ref),
+    ...ref
+  };
+}
+function runProvenance(input) {
+  return {
+    source: input.event.source,
+    sourceEventId: input.event.sourceEventId,
+    sourceDeliveryId: sourceDeliveryIdFromEvent(input.event),
+    signatureState: signatureStateFromEvent(input.event),
+    projectTarget: projectTargetProvenance(input.projectTarget),
+    admissionDecision: {
+      action: input.admissionDecision.action,
+      reasonCode: input.admissionDecision.reasonCode,
+      ...input.admissionDecision.eventId ? { eventId: input.admissionDecision.eventId } : {},
+      ...input.admissionDecision.activeRunId ? { activeRunId: input.admissionDecision.activeRunId } : {}
+    },
+    expectedRunnerId: input.expectedRunnerId
+  };
+}
 function channelBindingFromRow(row) {
   const metadata = recordFromJson(row.metadataJson);
   return {
@@ -664,6 +838,111 @@ function emptyApplyOutcomeCounts() {
 function recordFromUnknown(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
+function payloadString(payload, path) {
+  let current = payload;
+  for (const segment of path) {
+    const record = recordFromUnknown(current);
+    if (!record) return null;
+    current = record[segment];
+  }
+  return typeof current === "string" && current.trim().length > 0 ? current : null;
+}
+function controlPlaneAlertSubject(event) {
+  if (event.type === "run.claimed") {
+    return payloadString(event.payload, ["runnerId"]) ?? event.subject ?? "unknown-runner";
+  }
+  if (event.type === "security.auth_failed") {
+    return payloadString(event.payload, ["tokenFingerprint"]) ?? event.subject ?? "unknown-token";
+  }
+  if (event.type === "security.token_misuse") {
+    const provider = payloadString(event.payload, ["provider"]);
+    const tokenKind = payloadString(event.payload, ["tokenKind"]);
+    if (provider && tokenKind) return `${provider}:${tokenKind}`;
+    return event.subject ?? "unknown-token";
+  }
+  if (event.type === "security.signature_failed") {
+    const provider = payloadString(event.payload, ["provider"]);
+    const endpoint = payloadString(event.payload, ["endpoint"]);
+    if (provider && endpoint) return `${provider}:${endpoint}`;
+    return event.subject ?? "unknown-signature-source";
+  }
+  if (event.type === "security.request_body_rejected") {
+    return payloadString(event.payload, ["endpoint"]) ?? event.subject ?? "unknown-endpoint";
+  }
+  if (event.type === "admission.needs_human_decision") {
+    const reasonCode = payloadString(event.payload, ["decision", "reasonCode"]) ?? payloadString(event.payload, ["reasonCode"]);
+    if (reasonCode === "repo_not_bound" || reasonCode === "repo_context_missing") {
+      return payloadString(event.payload, ["projectTarget"]) ?? reasonCode;
+    }
+  }
+  return event.subject ?? event.type;
+}
+function controlPlaneAlertKind(event) {
+  if (event.type === "run.claimed") return "abnormal_runner_claim_rate";
+  if (event.type === "security.auth_failed") return "repeated_auth_failures";
+  if (event.type === "security.token_misuse") return "token_misuse";
+  if (event.type === "security.signature_failed") return "repeated_signature_failures";
+  if (event.type === "security.request_body_rejected") {
+    return payloadString(event.payload, ["reason"]) === "request_body_too_large" ? "repeated_large_payload_rejections" : "repeated_invalid_request_body";
+  }
+  if (event.type === "admission.needs_human_decision") {
+    const reasonCode = payloadString(event.payload, ["decision", "reasonCode"]) ?? payloadString(event.payload, ["reasonCode"]);
+    if (reasonCode === "repo_not_bound" || reasonCode === "repo_context_missing") return "repeated_unknown_project_targets";
+  }
+  return null;
+}
+function controlPlaneAlertMetadata(kind) {
+  if (kind === "repeated_auth_failures") {
+    return {
+      severity: "warn",
+      reason: "Repeated dispatcher authorization failures were observed.",
+      nextAction: "Check for token misuse, stale runner configuration, or a leaked/rotated pairing token."
+    };
+  }
+  if (kind === "token_misuse") {
+    return {
+      severity: "warn",
+      reason: "A platform or relay token failed with a terminal authentication or configuration error.",
+      nextAction: "Rotate or replace the affected token, then restart or re-pair the ingress or runner that owns it."
+    };
+  }
+  if (kind === "repeated_large_payload_rejections") {
+    return {
+      severity: "warn",
+      reason: "Repeated oversized dispatcher request bodies were rejected.",
+      nextAction: "Check source ingress payload size, request body limits, and whether a client is retrying an invalid payload."
+    };
+  }
+  if (kind === "repeated_invalid_request_body") {
+    return {
+      severity: "warn",
+      reason: "Repeated malformed or schema-invalid request bodies were rejected.",
+      nextAction: "Check source webhook payload shape, client versions, and whether unsigned or incompatible traffic is hitting the endpoint."
+    };
+  }
+  if (kind === "repeated_signature_failures") {
+    return {
+      severity: "warn",
+      reason: "Repeated source webhook signature verification failures were observed.",
+      nextAction: "Check the source webhook secret, signing configuration, endpoint URL, and whether unsigned traffic is hitting the ingress."
+    };
+  }
+  if (kind === "abnormal_runner_claim_rate") {
+    return {
+      severity: "warn",
+      reason: "Runner claim volume exceeded the local alert threshold.",
+      nextAction: "Check for runaway runner loops, token misuse, or an unexpected burst of queued runs for this runner."
+    };
+  }
+  return {
+    severity: "warn",
+    reason: "Repeated source events resolved to missing or unbound Project Targets.",
+    nextAction: "Verify source metadata, Project Target bindings, and runner allowlists before retrying."
+  };
+}
+function controlPlaneAlertThreshold(kind, thresholds) {
+  return thresholds?.[kind] ?? (kind === "token_misuse" ? 1 : kind === "repeated_auth_failures" || kind === "repeated_signature_failures" ? 3 : kind === "abnormal_runner_claim_rate" ? 10 : 2);
+}
 function metricsFromEvents(runId, events) {
   const latestApplyPlans = /* @__PURE__ */ new Map();
   for (const event of events) {
@@ -731,6 +1010,17 @@ function aggregateMetrics(input) {
   };
 }
 function createOpenTagRepository(db) {
+  async function repoBindingRunnerId(projectTarget) {
+    if (!projectTarget) return null;
+    const row = await db.select().from(repoBindings).where(
+      and(
+        eq(repoBindings.provider, projectTarget.provider),
+        eq(repoBindings.owner, projectTarget.owner),
+        eq(repoBindings.repo, projectTarget.repo)
+      )
+    ).limit(1).get();
+    return row?.runnerId ?? null;
+  }
   async function appendRunEvent(input) {
     await db.insert(runEvents).values({
       runId: input.runId,
@@ -742,6 +1032,51 @@ function createOpenTagRepository(db) {
       createdAt: input.createdAt ?? nowIso()
     });
   }
+  async function recordCreateRunReplay(input) {
+    const reason = input.replayKind === "source_delivery" ? "Source delivery already created a run." : "Source event already created a run.";
+    const reasonCode = input.replayKind === "source_delivery" ? "duplicate_source_delivery" : "duplicate_source_event";
+    const replayDecision = RunAdmissionDecisionSchema.parse({
+      action: "drop_duplicate",
+      reason,
+      reasonCode,
+      decidedAt: input.createdAt,
+      activeRunId: input.runRow.id,
+      eventId: input.event.id
+    });
+    await appendRunEvent({
+      runId: input.runRow.id,
+      type: "admission.decided",
+      payload: replayDecision,
+      visibility: "audit",
+      importance: "normal",
+      message: replayDecision.reason,
+      createdAt: input.createdAt
+    });
+    await appendRunEvent({
+      runId: input.runRow.id,
+      type: "run.create_idempotent_replay",
+      payload: {
+        requestedRunId: input.requestedRunId,
+        eventId: input.event.id,
+        replayKey: input.replayKind === "source_delivery" ? { kind: "source_delivery", source: input.event.source, deliveryId: input.sourceDeliveryId } : { kind: "source_event", eventId: input.event.id },
+        provenance: runProvenance({
+          event: input.event,
+          projectTarget: input.projectTarget,
+          admissionDecision: replayDecision,
+          expectedRunnerId: input.expectedRunnerId
+        })
+      },
+      visibility: "audit",
+      importance: "low",
+      createdAt: input.createdAt
+    });
+    return {
+      run: runFromRow(input.runRow),
+      created: false,
+      replayKind: input.replayKind,
+      replayDecision
+    };
+  }
   async function buildApplyPlan(input) {
     const storedProposalRow = await db.select().from(suggestedChanges).where(eq(suggestedChanges.proposalId, input.proposalId)).limit(1).get();
     const decisionRow = await db.select().from(approvalDecisions).where(eq(approvalDecisions.id, input.approvalDecisionId)).limit(1).get();
@@ -860,6 +1195,74 @@ function createOpenTagRepository(db) {
         event: OpenTagEventSchema.parse(JSON.parse(row.eventJson))
       };
     },
+    async findCancelableRunForSourceContainer(input) {
+      const rows = await db.select().from(runs).where(
+        and(
+          eq(runs.repoProvider, input.repoProvider),
+          eq(runs.repoOwner, input.owner),
+          eq(runs.repoName, input.repo),
+          inArray(runs.status, ["queued", "assigned", "running", "needs_approval"])
+        )
+      ).orderBy(asc(runs.createdAt));
+      for (const row of rows) {
+        const event = OpenTagEventSchema.parse(JSON.parse(row.eventJson));
+        if (sourceContainerMetadataMatches({ event, source: input.source, metadata: input.metadata })) {
+          return { run: runFromRow(row), event };
+        }
+      }
+      return null;
+    },
+    async cancelRun(input) {
+      const row = await db.select().from(runs).where(eq(runs.id, input.runId)).limit(1).get();
+      if (!row) return { outcome: "not_found" };
+      const event = OpenTagEventSchema.parse(JSON.parse(row.eventJson));
+      const existingRun = runFromRow(row);
+      if (terminalRunStatus(row.status)) {
+        return { outcome: "already_terminal", run: existingRun, event };
+      }
+      const updatedAt = nowIso();
+      const result = {
+        conclusion: "cancelled",
+        summary: input.reason ?? "Cancellation was requested by a human.",
+        nextAction: "OpenTag will not treat this stop request as a successful completion."
+      };
+      await db.update(runs).set({
+        status: "cancelled",
+        resultJson: JSON.stringify(result),
+        assignedRunnerId: null,
+        leasedAt: null,
+        leaseExpiresAt: null,
+        heartbeatAt: null,
+        updatedAt
+      }).where(eq(runs.id, input.runId));
+      await appendRunEvent({
+        runId: input.runId,
+        type: "run.cancel_requested",
+        payload: {
+          previousStatus: row.status,
+          previousRunnerId: row.assignedRunnerId,
+          terminalReason: "cancelled_by_user",
+          terminalSemantics: "A human stop request is not a successful completion and does not auto-promote queued follow-ups.",
+          ...input.requestedBy ? { requestedBy: input.requestedBy } : {},
+          reason: result.summary
+        },
+        visibility: "audit",
+        importance: "high",
+        message: result.summary,
+        createdAt: updatedAt
+      });
+      return {
+        outcome: "cancelled",
+        run: {
+          ...existingRun,
+          status: "cancelled",
+          assignedRunnerId: void 0,
+          updatedAt,
+          result
+        },
+        event
+      };
+    },
     async createFollowUpRequest(input) {
       const event = OpenTagEventSchema.parse(input.event);
       const decision = RunAdmissionDecisionSchema.parse(input.decision);
@@ -894,6 +1297,10 @@ function createOpenTagRepository(db) {
       const row = await db.select().from(followUpRequests).where(eq(followUpRequests.id, input.id)).limit(1).get();
       return row ? followUpRequestFromRow(row) : null;
     },
+    async listQueuedFollowUpsForActiveRun(input) {
+      const rows = await db.select().from(followUpRequests).where(and(eq(followUpRequests.activeRunId, input.activeRunId), eq(followUpRequests.status, "queued"))).orderBy(asc(followUpRequests.createdAt));
+      return rows.map(followUpRequestFromRow);
+    },
     async createRunFromFollowUpRequest(input) {
       const row = await db.select().from(followUpRequests).where(eq(followUpRequests.id, input.followUpRequestId)).limit(1).get();
       if (!row) {
@@ -950,7 +1357,13 @@ function createOpenTagRepository(db) {
     },
     async registerRunner(input) {
       const createdAt = nowIso();
-      await db.insert(runners).values({ runnerId: input.runnerId, name: input.name, createdAt }).onConflictDoNothing();
+      await db.insert(runners).values({ runnerId: input.runnerId, name: input.name, createdAt, heartbeatAt: createdAt }).onConflictDoUpdate({
+        target: runners.runnerId,
+        set: {
+          name: input.name,
+          heartbeatAt: createdAt
+        }
+      });
     },
     async getRunner(input) {
       const row = await db.select().from(runners).where(eq(runners.runnerId, input.runnerId)).limit(1).get();
@@ -1039,6 +1452,24 @@ function createOpenTagRepository(db) {
         }
       });
     },
+    async deleteChannelBinding(input) {
+      const existing = await db.select().from(channelBindings).where(
+        and(
+          eq(channelBindings.provider, input.provider),
+          eq(channelBindings.accountId, input.accountId),
+          eq(channelBindings.conversationId, input.conversationId)
+        )
+      ).limit(1).get();
+      if (!existing) return false;
+      await db.delete(channelBindings).where(
+        and(
+          eq(channelBindings.provider, input.provider),
+          eq(channelBindings.accountId, input.accountId),
+          eq(channelBindings.conversationId, input.conversationId)
+        )
+      );
+      return true;
+    },
     async createSlackChannelBinding(input) {
       const repoProvider = input.repoProvider ?? "github";
       await db.insert(channelBindings).values({
@@ -1065,6 +1496,26 @@ function createOpenTagRepository(db) {
       const createdAt = nowIso();
       const protocolFields = protocolRunFieldsFromEvent(event, createdAt);
       const repoKey = projectTargetRefFromEvent(event);
+      const expectedRunnerId = await repoBindingRunnerId(repoKey);
+      const sourceDeliveryId = sourceDeliveryIdFromEvent(event);
+      if (sourceDeliveryId) {
+        const existingDelivery = await db.select().from(sourceDeliveries).where(and(eq(sourceDeliveries.source, event.source), eq(sourceDeliveries.deliveryId, sourceDeliveryId))).limit(1).get();
+        if (existingDelivery) {
+          const existingByDelivery = await db.select().from(runs).where(eq(runs.id, existingDelivery.runId)).limit(1).get();
+          if (existingByDelivery) {
+            return recordCreateRunReplay({
+              runRow: existingByDelivery,
+              requestedRunId: input.id,
+              event,
+              projectTarget: repoKey,
+              expectedRunnerId,
+              replayKind: "source_delivery",
+              sourceDeliveryId,
+              createdAt
+            });
+          }
+        }
+      }
       const insertResult = await db.insert(runs).values({
         id: input.id,
         eventId: event.id,
@@ -1088,32 +1539,16 @@ function createOpenTagRepository(db) {
         if (!existingBySourceEvent) {
           throw new Error(`Run already exists for event ${event.id}, but it could not be loaded`);
         }
-        const replayDecision = RunAdmissionDecisionSchema.parse({
-          action: "drop_duplicate",
-          reason: "Source event already created a run.",
-          reasonCode: "duplicate_source_event",
-          decidedAt: createdAt,
-          activeRunId: existingBySourceEvent.id,
-          eventId: event.id
-        });
-        await appendRunEvent({
-          runId: existingBySourceEvent.id,
-          type: "admission.decided",
-          payload: replayDecision,
-          visibility: "audit",
-          importance: "normal",
-          message: replayDecision.reason,
-          createdAt
-        });
-        await appendRunEvent({
-          runId: existingBySourceEvent.id,
-          type: "run.create_idempotent_replay",
-          payload: { requestedRunId: input.id, eventId: event.id },
-          visibility: "audit",
-          importance: "low",
+        return recordCreateRunReplay({
+          runRow: existingBySourceEvent,
+          requestedRunId: input.id,
+          event,
+          projectTarget: repoKey,
+          expectedRunnerId,
+          replayKind: "source_event",
+          sourceDeliveryId,
           createdAt
         });
-        return { run: runFromRow(existingBySourceEvent), created: false };
       }
       const createDecision = RunAdmissionDecisionSchema.parse({
         action: "start",
@@ -1122,6 +1557,15 @@ function createOpenTagRepository(db) {
         decidedAt: createdAt,
         eventId: event.id
       });
+      if (sourceDeliveryId) {
+        await db.insert(sourceDeliveries).values({
+          source: event.source,
+          deliveryId: sourceDeliveryId,
+          runId: input.id,
+          eventId: event.id,
+          createdAt
+        }).onConflictDoNothing({ target: [sourceDeliveries.source, sourceDeliveries.deliveryId] });
+      }
       await appendRunEvent({
         runId: input.id,
         type: "admission.decided",
@@ -1134,7 +1578,15 @@ function createOpenTagRepository(db) {
       await appendRunEvent({
         runId: input.id,
         type: "run.created",
-        payload: { eventId: event.id },
+        payload: {
+          eventId: event.id,
+          provenance: runProvenance({
+            event,
+            projectTarget: repoKey,
+            admissionDecision: createDecision,
+            expectedRunnerId
+          })
+        },
         visibility: "audit",
         importance: "low",
         createdAt
@@ -1184,8 +1636,35 @@ function createOpenTagRepository(db) {
         created: true
       };
     },
+    async pruneSourceDeliveries(input) {
+      const cutoff = new Date(input.olderThan);
+      if (!Number.isFinite(cutoff.getTime())) {
+        throw new Error("olderThan must be a valid timestamp.");
+      }
+      const requestedLimit = input.limit ?? 1e3;
+      const limit = Number.isFinite(requestedLimit) ? Math.max(1, Math.floor(requestedLimit)) : 1e3;
+      const rows = await db.select().from(sourceDeliveries).where(lt(sourceDeliveries.createdAt, cutoff.toISOString())).orderBy(asc(sourceDeliveries.createdAt)).limit(limit);
+      let pruned = 0;
+      let retainedActive = 0;
+      for (const row of rows) {
+        const runRow = await db.select({ status: runs.status }).from(runs).where(eq(runs.id, row.runId)).limit(1).get();
+        if (runRow && !terminalRunStatus(runRow.status)) {
+          retainedActive += 1;
+          continue;
+        }
+        const result = await db.delete(sourceDeliveries).where(and(eq(sourceDeliveries.source, row.source), eq(sourceDeliveries.deliveryId, row.deliveryId)));
+        pruned += result.changes;
+      }
+      return {
+        scanned: rows.length,
+        pruned,
+        retainedActive
+      };
+    },
     async claimNextRun(input) {
       const now = /* @__PURE__ */ new Date();
+      const runnerHeartbeatAt = nowIso();
+      await db.update(runners).set({ heartbeatAt: runnerHeartbeatAt }).where(eq(runners.runnerId, input.runnerId));
       const activeRows = await db.select().from(runs).where(inArray(runs.status, ["assigned", "running"])).orderBy(asc(runs.createdAt));
       for (const activeRow of activeRows) {
         if (!isIsoExpired(activeRow.leaseExpiresAt, now)) continue;
@@ -1309,6 +1788,7 @@ function createOpenTagRepository(db) {
       if (!row) return false;
       const leaseSeconds = input.leaseSeconds ?? 60;
       const leaseExpiresAt = new Date(Date.now() + leaseSeconds * 1e3).toISOString();
+      await db.update(runners).set({ heartbeatAt: updatedAt }).where(eq(runners.runnerId, input.runnerId));
       await db.update(runs).set({ heartbeatAt: updatedAt, leaseExpiresAt, updatedAt }).where(eq(runs.id, input.runId));
       await appendRunEvent({
         runId: input.runId,
@@ -1326,31 +1806,55 @@ function createOpenTagRepository(db) {
       if (input.runnerId) {
         conditions.push(eq(runs.assignedRunnerId, input.runnerId));
       }
+      if (input.idempotencyKey) {
+        const existing = await db.select().from(runEvents).where(eq(runEvents.runId, input.runId)).orderBy(desc(runEvents.id)).limit(250);
+        for (const event of existing) {
+          if (event.type !== "run.running") continue;
+          const payload = recordFromJson(event.payloadJson);
+          if (payload?.["idempotencyKey"] === input.idempotencyKey) return "duplicate";
+        }
+      }
       const updateResult = await db.update(runs).set({ status: "running", executor: input.executor, updatedAt }).where(and(...conditions));
       if (updateResult.changes === 0) {
-        return false;
+        return "not_found";
       }
       await appendRunEvent({
         runId: input.runId,
         type: "run.running",
-        payload: input.runnerId ? { runnerId: input.runnerId, executor: input.executor } : { executor: input.executor },
+        payload: {
+          ...input.runnerId ? { runnerId: input.runnerId } : {},
+          ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
+          executor: input.executor,
+          ...input.runTimeoutMs ? { runTimeoutMs: input.runTimeoutMs } : {}
+        },
         visibility: "audit",
         importance: "normal",
         createdAt: updatedAt
       });
-      return true;
+      return "running";
     },
     async completeRun(input) {
       const result = OpenTagRunResultSchema.parse(input.result);
       const updatedAt = nowIso();
-      const status = result.conclusion === "success" ? "succeeded" : result.conclusion === "cancelled" ? "cancelled" : result.conclusion === "needs_human" ? "needs_approval" : "failed";
+      const status = result.conclusion === "success" ? "succeeded" : result.conclusion === "cancelled" ? "cancelled" : result.conclusion === "interrupted" ? "interrupted" : result.conclusion === "timed_out" ? "timed_out" : result.conclusion === "needs_human" ? "needs_approval" : "failed";
       const runRow = await db.select().from(runs).where(eq(runs.id, input.runId)).limit(1).get();
       if (!runRow) {
-        if (input.runnerId) return false;
+        if (input.runnerId) return "not_found";
         throw new Error(`Run not found: ${input.runId}`);
       }
+      if (input.idempotencyKey) {
+        const existing = await db.select().from(runEvents).where(eq(runEvents.runId, input.runId)).orderBy(desc(runEvents.id)).limit(250);
+        for (const event of existing) {
+          if (event.type !== "run.completed") continue;
+          const payload = recordFromJson(event.payloadJson);
+          if (payload?.["idempotencyKey"] === input.idempotencyKey) return "duplicate";
+        }
+      }
+      if (terminalRunStatus(runRow.status)) {
+        return "not_found";
+      }
       if (input.runnerId && runRow.assignedRunnerId !== input.runnerId) {
-        return false;
+        return "not_found";
       }
       const runThread = runRow ? protocolRunFieldsFromEvent(OpenTagEventSchema.parse(JSON.parse(runRow.eventJson)), runRow.createdAt).thread : void 0;
       await db.update(runs).set({
@@ -1394,7 +1898,10 @@ function createOpenTagRepository(db) {
       await appendRunEvent({
         runId: input.runId,
         type: "run.completed",
-        payload: result,
+        payload: {
+          ...result,
+          ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+        },
         visibility: "audit",
         importance: "high",
         message: result.summary,
@@ -1414,7 +1921,7 @@ function createOpenTagRepository(db) {
           createdAt: updatedAt
         });
       }
-      return true;
+      return "completed";
     },
     async getSuggestedChanges(input) {
       const row = await db.select().from(suggestedChanges).where(eq(suggestedChanges.proposalId, input.proposalId)).limit(1).get();
@@ -1602,13 +2109,22 @@ function createOpenTagRepository(db) {
     async recordProgress(input) {
       if (input.runnerId) {
         const row = await db.select().from(runs).where(and(eq(runs.id, input.runId), eq(runs.assignedRunnerId, input.runnerId))).limit(1).get();
-        if (!row) return false;
+        if (!row) return "not_found";
+      }
+      if (input.idempotencyKey) {
+        const existing = await db.select().from(runEvents).where(eq(runEvents.runId, input.runId)).orderBy(desc(runEvents.id)).limit(250);
+        for (const event of existing) {
+          if (event.type !== "run.progress") continue;
+          const payload = recordFromJson(event.payloadJson);
+          if (payload?.["idempotencyKey"] === input.idempotencyKey) return "duplicate";
+        }
       }
       await appendRunEvent({
         runId: input.runId,
         type: "run.progress",
         payload: {
           ...input.runnerId ? { runnerId: input.runnerId } : {},
+          ...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
           type: input.type ?? "progress",
           message: input.message,
           at: input.at ?? nowIso()
@@ -1618,7 +2134,7 @@ function createOpenTagRepository(db) {
         message: input.message,
         createdAt: input.at ?? nowIso()
       });
-      return true;
+      return "recorded";
     },
     async getRun(input) {
       const row = await db.select().from(runs).where(eq(runs.id, input.runId)).limit(1).get();
@@ -1641,8 +2157,91 @@ function createOpenTagRepository(db) {
         createdAt: row.createdAt
       }));
     },
+    async appendControlPlaneEvent(input) {
+      await db.insert(controlPlaneEvents).values({
+        type: input.type,
+        severity: input.severity ?? "info",
+        subject: input.subject ?? null,
+        payloadJson: JSON.stringify(input.payload ?? {}),
+        createdAt: input.createdAt ?? nowIso()
+      });
+    },
+    async listControlPlaneEvents(input = {}) {
+      const conditions = [
+        ...input.type ? [eq(controlPlaneEvents.type, input.type)] : [],
+        ...input.severity ? [eq(controlPlaneEvents.severity, input.severity)] : []
+      ];
+      const rows = await db.select().from(controlPlaneEvents).where(conditions.length > 0 ? and(...conditions) : void 0).orderBy(asc(controlPlaneEvents.id)).limit(input.limit ?? 100);
+      return rows.map((row) => ({
+        id: row.id,
+        type: row.type,
+        severity: row.severity,
+        ...row.subject ? { subject: row.subject } : {},
+        payload: JSON.parse(row.payloadJson),
+        createdAt: row.createdAt
+      }));
+    },
+    async summarizeControlPlaneAlerts(input = {}) {
+      const limit = input.limit ?? 5e3;
+      const rows = await db.select().from(controlPlaneEvents).orderBy(desc(controlPlaneEvents.id)).limit(limit);
+      const claimRows = await db.select().from(runEvents).where(eq(runEvents.type, "run.claimed")).orderBy(desc(runEvents.id)).limit(limit);
+      const groups = /* @__PURE__ */ new Map();
+      function addEvent(event) {
+        if (input.since && event.createdAt < input.since) return;
+        const kind = controlPlaneAlertKind(event);
+        if (!kind) return;
+        const subject = controlPlaneAlertSubject(event);
+        const key = `${kind}|${event.type}|${subject}`;
+        const group = groups.get(key) ?? { kind, eventType: event.type, subject, events: [] };
+        group.events.push(event);
+        groups.set(key, group);
+      }
+      for (const row of rows.reverse()) {
+        addEvent({
+          id: row.id,
+          type: row.type,
+          severity: row.severity,
+          ...row.subject ? { subject: row.subject } : {},
+          payload: JSON.parse(row.payloadJson),
+          createdAt: row.createdAt
+        });
+      }
+      for (const row of claimRows.reverse()) {
+        addEvent({
+          id: row.id,
+          type: row.type,
+          severity: "info",
+          subject: row.runId,
+          payload: JSON.parse(row.payloadJson),
+          createdAt: row.createdAt
+        });
+      }
+      return [...groups.values()].flatMap((group) => {
+        const threshold = controlPlaneAlertThreshold(group.kind, input.thresholds);
+        if (group.events.length < threshold) return [];
+        const metadata = controlPlaneAlertMetadata(group.kind);
+        const first = group.events[0];
+        const last = group.events.at(-1);
+        return [
+          {
+            id: `${group.kind}:${group.eventType}:${group.subject}`,
+            type: group.kind,
+            severity: metadata.severity,
+            eventType: group.eventType,
+            count: group.events.length,
+            threshold,
+            firstSeenAt: first.createdAt,
+            lastSeenAt: last.createdAt,
+            subject: group.subject,
+            reason: metadata.reason,
+            nextAction: metadata.nextAction
+          }
+        ];
+      }).sort((left, right) => right.count - left.count || left.id.localeCompare(right.id));
+    },
     async enqueueCallbackDelivery(input) {
       const createdAt = nowIso();
+      const idempotencyKey = callbackIdempotencyKey(input);
       const rows = await db.insert(callbackDeliveries).values({
         runId: input.runId,
         kind: input.kind,
@@ -1650,17 +2249,32 @@ function createOpenTagRepository(db) {
         uri: input.uri,
         body: input.body,
         threadKey: input.threadKey ?? null,
+        idempotencyKey,
         metadataJson: JSON.stringify({
           ...input.agentId ? { agentId: input.agentId } : {},
           ...input.statusMessageKey ? { statusMessageKey: input.statusMessageKey } : {},
-          ...input.blocks ? { blocks: input.blocks } : {}
+          ...input.blocks ? { blocks: input.blocks } : {},
+          ...input.rich !== void 0 ? { rich: input.rich } : {}
         }),
         status: "pending",
         createdAt,
         updatedAt: createdAt
-      }).returning();
+      }).onConflictDoNothing({ target: callbackDeliveries.idempotencyKey }).returning();
       const row = rows[0];
-      if (!row) throw new Error("callback delivery was not created");
+      if (!row) {
+        const existing = await db.select().from(callbackDeliveries).where(eq(callbackDeliveries.idempotencyKey, idempotencyKey)).limit(1).get();
+        if (!existing) throw new Error("callback delivery was not created");
+        await appendRunEvent({
+          runId: input.runId,
+          type: `callback.${input.kind}.duplicate`,
+          payload: callbackDeliveryFromRow(existing),
+          visibility: "audit",
+          importance: "normal",
+          message: "Duplicate callback delivery suppressed.",
+          createdAt
+        });
+        return callbackDeliveryFromRow(existing);
+      }
       await appendRunEvent({
         runId: input.runId,
         type: `callback.${input.kind}.queued`,
@@ -1675,29 +2289,46 @@ function createOpenTagRepository(db) {
       const updatedAt = nowIso();
       const row = await db.select().from(callbackDeliveries).where(eq(callbackDeliveries.id, input.deliveryId)).limit(1).get();
       if (!row) return;
-      await db.update(callbackDeliveries).set({ status: "delivered", attempts: row.attempts + 1, lastError: null, nextAttemptAt: null, updatedAt }).where(eq(callbackDeliveries.id, input.deliveryId));
+      const metadata = callbackDeliveryMetadataFromJson(row.metadataJson) ?? {};
+      const metadataJson = JSON.stringify({
+        ...metadata,
+        ...input.externalMessageId ? { externalMessageId: input.externalMessageId } : {}
+      });
+      await db.update(callbackDeliveries).set({ status: "delivered", attempts: row.attempts + 1, lastError: null, nextAttemptAt: null, metadataJson, updatedAt }).where(eq(callbackDeliveries.id, input.deliveryId));
+      const deliveredRow = { ...row, metadataJson };
       await appendRunEvent({
         runId: row.runId,
         type: `callback.${row.kind}.delivered`,
-        payload: { ...callbackDeliveryFromRow(row), status: "delivered", attempts: row.attempts + 1, updatedAt },
+        payload: { ...callbackDeliveryFromRow(deliveredRow), status: "delivered", attempts: row.attempts + 1, updatedAt },
         visibility: "human",
         importance: row.kind === "final" ? "high" : "normal",
         message: row.body,
         createdAt: updatedAt
       });
     },
+    async findCallbackExternalMessageId(input) {
+      const rows = await db.select().from(callbackDeliveries).where(and(eq(callbackDeliveries.runId, input.runId), eq(callbackDeliveries.provider, input.provider), eq(callbackDeliveries.status, "delivered"))).orderBy(desc(callbackDeliveries.updatedAt), desc(callbackDeliveries.id));
+      for (const row of rows) {
+        const delivery = callbackDeliveryFromRow(row);
+        if (delivery.statusMessageKey !== input.statusMessageKey) continue;
+        if ((delivery.threadKey ?? void 0) !== input.threadKey) continue;
+        if (delivery.externalMessageId) return delivery.externalMessageId;
+      }
+      return void 0;
+    },
     async markCallbackFailed(input) {
       const updatedAt = nowIso();
       const row = await db.select().from(callbackDeliveries).where(eq(callbackDeliveries.id, input.deliveryId)).limit(1).get();
       if (!row) return;
-      await db.update(callbackDeliveries).set({ status: "failed", attempts: row.attempts + 1, lastError: input.error, nextAttemptAt: input.nextAttemptAt ?? null, updatedAt }).where(eq(callbackDeliveries.id, input.deliveryId));
+      const attempts = row.attempts + 1;
+      await db.update(callbackDeliveries).set({ status: "failed", attempts, lastError: input.error, nextAttemptAt: input.nextAttemptAt ?? null, updatedAt }).where(eq(callbackDeliveries.id, input.deliveryId));
       await appendRunEvent({
         runId: row.runId,
         type: `callback.${row.kind}.failed`,
         payload: {
           ...callbackDeliveryFromRow(row),
           status: "failed",
-          attempts: row.attempts + 1,
+          attempts,
           lastError: input.error,
           ...input.nextAttemptAt ? { nextAttemptAt: input.nextAttemptAt } : {},
           updatedAt
@@ -1706,6 +2337,24 @@ function createOpenTagRepository(db) {
         importance: "normal",
         createdAt: updatedAt
       });
+      if (input.maxAttempts !== void 0 && attempts >= input.maxAttempts && !input.nextAttemptAt) {
+        await appendRunEvent({
+          runId: row.runId,
+          type: `callback.${row.kind}.suppressed`,
+          payload: {
+            ...callbackDeliveryFromRow(row),
+            status: "failed",
+            attempts,
+            maxAttempts: input.maxAttempts,
+            lastError: input.error,
+            updatedAt
+          },
+          visibility: "audit",
+          importance: "high",
+          message: "Callback delivery retry budget exhausted; further delivery attempts are suppressed to avoid duplicate storms.",
+          createdAt: updatedAt
+        });
+      }
     },
     async listPendingCallbackDeliveries(input) {
       const now = input.now ?? /* @__PURE__ */ new Date();
@@ -1815,6 +2464,7 @@ export {
   approvalDecisions,
   callbackDeliveries,
   channelBindings,
+  controlPlaneEvents,
   createOpenTagRepository,
   followUpRequests,
   migrateSchema,
@@ -1824,6 +2474,7 @@ export {
   runEvents,
   runners,
   runs,
+  sourceDeliveries,
   suggestedChanges
 };
 //# sourceMappingURL=index.js.map