@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/be/memory/providers/sqlite-store.ts

@@ -2,6 +2,7 @@ import { getDb, getDbClient, isSqliteVecAvailable } from "@/be/db";
 import { cosineSimilarity, deserializeEmbedding, serializeEmbedding } from "@/be/embedding";
 import { contentSha256 } from "@/commands/profile-sync";
 import type { AgentMemory, AgentMemoryScope, AgentMemorySource } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
 import {
   EMBEDDING_DIMENSIONS,
   isHybridSearchEnabled,
@@ -19,6 +20,7 @@ import type {
   MemoryInput,
   MemoryListOptions,
   MemoryRetrievalSource,
+  MemoryScrubFields,
   MemorySearchOptions,
   MemoryStats,
   MemoryStore,
@@ -437,7 +439,12 @@ export class SqliteMemoryStore implements MemoryStore {
     const now = new Date().toISOString();
     const key = input.key ?? `${input.scope}/${input.source}/${id}`;
     const expiresAt = computeExpiresAt(input.source, key);
-    const contentHash = contentSha256(input.content);
+    // Scrub before the hash, the FTS sync and the caller's embedding (callers
+    // embed the returned row's content), so all of them see the same text.
+    const name = scrubSecrets(input.name);
+    const content = scrubSecrets(input.content);
+    const summary = input.summary == null ? null : scrubSecrets(input.summary);
+    const contentHash = contentSha256(content);
     const version = 1;
 
     const row = await getDbClient().transaction(async (tx) => {
@@ -449,15 +456,15 @@ export class SqliteMemoryStore implements MemoryStore {
           input.agentId ?? null,
           input.scope,
           key,
-          input.name,
-          input.content,
-          input.summary ?? null,
+          name,
+          content,
+          summary,
           input.source,
           input.sourceTaskId ?? null,
           input.sourcePath ?? null,
           input.chunkIndex ?? 0,
           input.totalChunks ?? 1,
-          JSON.stringify(input.tags ?? []),
+          JSON.stringify((input.tags ?? []).map((tag) => scrubSecrets(tag))),
           now,
           now,
           now,
@@ -478,7 +485,7 @@ export class SqliteMemoryStore implements MemoryStore {
           crypto.randomUUID(),
           inserted.id,
           version,
-          input.content,
+          content,
           contentHash,
           input.intent ?? "create memory",
           input.agentId ?? null,
@@ -1009,13 +1016,17 @@ export class SqliteMemoryStore implements MemoryStore {
 
       const previousVersion = row.version ?? 1;
       const moving = input.newKey !== undefined && input.newKey !== row.key;
+      // Scrub the edited text before the hash and FTS sync; callers embed the
+      // returned content, so the vector matches the stored row.
       const nextContent = moveOnly
         ? row.content
-        : applyEditMode(input.mode, row.content, {
-            content: input.content,
-            oldString: input.oldString,
-            newString: input.newString,
-          });
+        : scrubSecrets(
+            applyEditMode(input.mode, row.content, {
+              content: input.content,
+              oldString: input.oldString,
+              newString: input.newString,
+            }),
+          );
 
       const nextHash = contentSha256(nextContent);
       const contentChanged = !moveOnly && nextHash !== row.contentHash;
@@ -1268,6 +1279,47 @@ export class SqliteMemoryStore implements MemoryStore {
     }
   }
 
+  async rewriteForScrub(
+    id: string,
+    before: MemoryScrubFields,
+    after: MemoryScrubFields,
+  ): Promise<boolean> {
+    const contentChanged = after.content !== before.content;
+    return getDbClient().transaction(async (tx) => {
+      // Compare-and-set: the sweep scrubbed `before` outside the write lock, so
+      // skip the row if a concurrent write moved it since.
+      const result = await tx.run(
+        `UPDATE agent_memory
+         SET name = ?, content = ?, summary = ?, contentHash = ?,
+             embedding = CASE WHEN ? = 1 THEN NULL ELSE embedding END,
+             embeddingModel = CASE WHEN ? = 1 THEN NULL ELSE embeddingModel END
+         WHERE id = ? AND name IS ? AND content IS ? AND summary IS ?`,
+        [
+          after.name,
+          after.content,
+          after.summary,
+          contentSha256(after.content),
+          contentChanged ? 1 : 0,
+          contentChanged ? 1 : 0,
+          id,
+          before.name,
+          before.content,
+          before.summary,
+        ],
+      );
+      if (result.changes === 0) return false;
+      // The vector embeds the old (secret-bearing) content. Drop it; the
+      // re-embed backfill picks the row up via `embedding IS NULL`.
+      if (contentChanged && this.vecInitialized && this.getVecTableSchema()) {
+        await tx.run("DELETE FROM memory_vec WHERE memory_id = ?", [id]);
+      }
+      if (after.name !== before.name || contentChanged) {
+        await this.syncFtsRow(id, after.name, after.content);
+      }
+      return true;
+    });
+  }
+
   async getStats(agentId: string): Promise<MemoryStats> {
     const db = getDbClient();
 

package/src/be/memory/types.ts

@@ -40,6 +40,17 @@ export interface MemoryStore {
   deleteBySourcePath(sourcePath: string, agentId: string): Promise<number>;
   purgeExpired(): Promise<number>;
   updateEmbedding(id: string, embedding: Float32Array, model: string): Promise<void>;
+  /**
+   * Redact a row in place (boot retro-sweep). Writes only if the row still
+   * holds `before`; keeps FTS in sync and drops the embedding when the
+   * content changed so the re-embed backfill regenerates it. Returns whether
+   * the row was written.
+   */
+  rewriteForScrub(
+    id: string,
+    before: MemoryScrubFields,
+    after: MemoryScrubFields,
+  ): Promise<boolean>;
   getStats(agentId: string): Promise<MemoryStats>;
   getHealth(): MemoryHealth;
 }
@@ -48,6 +59,9 @@ export interface MemoryStore {
 // Supporting types
 // ============================================================================
 
+/** The free-text `agent_memory` columns the boot retro-sweep redacts. */
+export type MemoryScrubFields = { name: string; content: string; summary: string | null };
+
 export interface MemoryInput {
   agentId: string | null;
   scope: AgentMemoryScope;

package/src/be/migrations/197_connector_codes.sql

@@ -0,0 +1,23 @@
+-- Single-use connect codes for the agent-swarm.dev ChatGPT connector.
+--
+-- `POST /api/users/:id/connector-codes` stores a code here. The connector
+-- trades it once at `POST /api/connector/exchange` for a freshly minted
+-- `aswt_` token (src/be/connector-codes.ts). The plaintext code is never
+-- stored. The heartbeat cleanup sweep deletes rows 1h after they expire.
+
+CREATE TABLE IF NOT EXISTS connector_codes (
+  -- sha256 hex of the plaintext code.
+  code_hash TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  label TEXT NOT NULL,
+  -- IdentityActor that created the code. The token minted at exchange time
+  -- is attributed to this actor in user_identity_events.
+  actor_kind TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  used_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_connector_codes_expires_at
+  ON connector_codes(expires_at);

package/src/be/migrations/198_permission_audit_guest.sql

@@ -0,0 +1,33 @@
+-- Page guest sessions are an RBAC principal, so their decisions are audited.
+-- SQLite cannot change a CHECK in place, so rebuild the table with the 108
+-- shape plus the new principal type. Every row is copied unchanged.
+
+CREATE TABLE permission_audit_new (
+  id               TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  ts               TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  principalType    TEXT NOT NULL CHECK (principalType IN ('agent','user','operator','guest')),
+  principalId      TEXT,
+  originatorUserId TEXT,
+  verb             TEXT NOT NULL,
+  resourceType     TEXT,
+  resourceId       TEXT,
+  decision         TEXT NOT NULL CHECK (decision IN ('allow','deny')),
+  reason           TEXT,
+  source           TEXT NOT NULL CHECK (source IN ('mcp','http'))
+);
+
+INSERT INTO permission_audit_new (
+  id, ts, principalType, principalId, originatorUserId,
+  verb, resourceType, resourceId, decision, reason, source
+)
+SELECT
+  id, ts, principalType, principalId, originatorUserId,
+  verb, resourceType, resourceId, decision, reason, source
+FROM permission_audit;
+
+DROP TABLE permission_audit;
+ALTER TABLE permission_audit_new RENAME TO permission_audit;
+
+CREATE INDEX idx_permission_audit_ts ON permission_audit(ts);
+CREATE INDEX idx_permission_audit_decision_ts ON permission_audit(decision, ts);
+CREATE INDEX idx_permission_audit_principal_ts ON permission_audit(principalId, ts);

package/src/be/migrations/200_backfill_auto_memory_expiry.sql

@@ -0,0 +1,20 @@
+-- Backfill a TTL on legacy auto-generated memories.
+--
+-- task_completion and session_summary rows written before TTL_DEFAULTS existed
+-- (or by paths that skipped computeExpiresAt) carry expiresAt = NULL, so
+-- purgeExpired() never removes them and they keep competing for pre-task
+-- recall slots indefinitely. Give each one a 7-day grace window from the
+-- moment this migration runs; the regular purge then removes them.
+--
+-- Excluded:
+--   * swarm-scope rows: promoted to shared knowledge, not per-agent residue.
+--   * /longterm keys: tierSource() treats them as manual (no TTL).
+--
+-- Data-only. ISO-8601 with milliseconds, matching Date#toISOString() used by
+-- computeExpiresAt() for new rows.
+UPDATE agent_memory
+SET expiresAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '+7 days')
+WHERE source IN ('task_completion', 'session_summary')
+  AND expiresAt IS NULL
+  AND scope <> 'swarm'
+  AND (key IS NULL OR (key <> '/longterm' AND key NOT LIKE '/longterm/%'));

package/src/be/migrations/201_workflow_replay_columns.sql

@@ -0,0 +1,10 @@
+-- Byte-exact replay state for workflow runs, sealed at rest.
+--
+-- `workflow_run_steps.output` and `workflow_runs.context` are scrubbed at write
+-- for display and SQL filters (`json_extract(context, '$.swarm.requestedByUserId')`).
+-- Resume, retry, dedup and recovery rebuild the live ctx from these values, so
+-- they need the exact value: these columns hold it, encrypted with `sealJson`
+-- (src/be/sealed-json.ts). NULL for rows written before this migration; their
+-- readers fall back to the plain column.
+ALTER TABLE workflow_run_steps ADD COLUMN output_replay TEXT;
+ALTER TABLE workflow_runs ADD COLUMN context_replay TEXT;

package/src/be/migrations/202_codex_oauth_device_flows.sql

@@ -0,0 +1,24 @@
+-- Codex device-login flow state, moved out of `kv_entries`.
+--
+-- `state` is the encrypted flow (device auth id, user code, poll lease). It
+-- lived in `kv_entries` namespace 'codex-oauth-device', which db-query must
+-- keep readable for general KV debugging. A dedicated table lets db-query deny
+-- this store by table name, with no SQL-text parsing.
+--
+-- expires_at: unix-ms. Expired rows are deleted on read and on every write.
+
+CREATE TABLE IF NOT EXISTS codex_oauth_device_flows (
+  flow_id     TEXT PRIMARY KEY,
+  state       TEXT NOT NULL,
+  expires_at  INTEGER NOT NULL,
+  created_at  INTEGER NOT NULL DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER)),
+  updated_at  INTEGER NOT NULL DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER))
+);
+
+INSERT OR IGNORE INTO codex_oauth_device_flows (flow_id, state, expires_at, created_at, updated_at)
+  SELECT key, value, expires_at, created_at, updated_at
+    FROM kv_entries
+   WHERE namespace = 'codex-oauth-device'
+     AND expires_at IS NOT NULL;
+
+DELETE FROM kv_entries WHERE namespace = 'codex-oauth-device';

package/src/be/model-tier-resolution.ts

@@ -30,6 +30,7 @@ import {
   harnessCatalogSection,
   harnessModelMismatch,
   isAlias,
+  isHarnessModelJudged,
   type ModelsDevCatalog,
   type ModelsDevModel,
   parseAlias,
@@ -340,7 +341,7 @@ export async function resolveTaskModel(
   input: ResolveTaskModelInput,
 ): Promise<TaskModelResolution | TaskModelHarnessMismatch | null> {
   const harness = input.harnessProvider ?? null;
-  const judged = harness !== null && harnessCatalogSection(harness) !== null;
+  const judged = harness !== null && isHarnessModelJudged(harness);
   const sections = judged
     ? ((await loadResolutionCatalog()).catalog as HarnessCatalogSections)
     : {};

package/src/be/model-validation.ts

@@ -81,7 +81,7 @@ export interface ExplicitModelCheck {
   agentName?: string | null;
 }
 
-/** Null when `model` runs on `harness`, else the reason. Pure; only judges claude, claude-managed, codex. */
+/** Null when `model` runs on `harness`, else the reason. Pure; only judges claude, claude-managed, codex and grok. */
 export const harnessModelError = harnessModelMismatch;
 
 /** `harnessModelError` against the current catalog, for callers with no agent row (claim path). */

package/src/be/pricing-normalize.ts

@@ -66,6 +66,9 @@ const ROUTING_PREFIXES_BY_PROVIDER: Record<PricingProvider, readonly string[]> =
   amp: ["anthropic/", "openai/", "google-vertex/", "google/"],
   // cursor reports a bare Cursor model id, already the vendor's own id.
   cursor: [],
+  // The Grok CLI reports a bare xAI id (`grok-4.6`) or `openrouter/<vendor>/<id>`
+  // for an OpenRouter model; stripping the prefix lands it on the openrouter rows.
+  grok: ["openrouter/", "xai/"],
 };
 
 /** `gpt-5-nano-2025-08-07` -> `gpt-5-nano`. Anthropic's 8-digit dates (`-20251001`) are real catalog ids and are left alone. */

package/src/be/rbac-audit.ts

@@ -21,7 +21,7 @@ import { isEnvFlagEnabled } from "../utils/env-flag";
 import { getDbClient } from "./db";
 
 type AuditRow = {
-  principalType: "agent" | "user" | "operator";
+  principalType: "agent" | "user" | "operator" | "guest";
   principalId: string | null;
   originatorUserId: string | null;
   verb: string;
@@ -61,6 +61,7 @@ function principalIdOf(principal: RbacCheck["principal"]): string | null {
     case "user":
       return principal.userId;
     case "operator":
+    case "guest":
       return null;
   }
 }

package/src/be/scripts/db.ts

@@ -8,10 +8,10 @@ import type {
   ScriptScope,
   ScriptVersionRecord,
 } from "../../types";
-import { registerVolatileSecret } from "../../utils/secret-scrubber";
 import { generateBearerToken, generateShortId } from "../../utils/short-id";
 import { decryptSecret, encryptSecret, getEncryptionKey } from "../crypto";
 import { computeContentHash, getDbClient } from "../db";
+import { registerStoredSecret, scriptApiSecretName } from "../secret-registry";
 import { embedScript } from "./embeddings";
 
 type ScriptRow = Omit<ScriptRecord, "isScratch" | "typeChecked"> & {
@@ -517,7 +517,7 @@ export async function createScriptApi(args: {
         ],
       );
       if (!row) throw new Error("Failed to create script API endpoint");
-      if (token) registerVolatileSecret(token, `script-api:${id}`);
+      registerStoredSecret(token, scriptApiSecretName(id));
       return { ...rowToScriptApi(row), token };
     } catch (err) {
       if (isUniqueConstraintError(err) && attempt < 4) continue;
@@ -527,6 +527,30 @@ export async function createScriptApi(args: {
   throw new Error("Failed to allocate a unique script API endpoint id");
 }
 
+/**
+ * Every stored script API bearer token, decrypted, for the secret registry
+ * (src/be/secret-registry.ts). A row that fails to decrypt is counted, not thrown.
+ */
+export async function listStoredScriptApiSecrets(): Promise<{
+  secrets: { id: string; token: string }[];
+  failed: number;
+}> {
+  const rows = await getDbClient().query<{ id: string; bearerTokenEncrypted: string }>(
+    "SELECT id, bearerTokenEncrypted FROM script_apis WHERE bearerTokenEncrypted IS NOT NULL",
+  );
+  const secrets: { id: string; token: string }[] = [];
+  let failed = 0;
+  for (const row of rows) {
+    try {
+      const token = decryptSecret(row.bearerTokenEncrypted, getEncryptionKey());
+      if (token) secrets.push({ id: row.id, token });
+    } catch {
+      failed++;
+    }
+  }
+  return { secrets, failed };
+}
+
 export async function listScriptApisForScript(scriptId: string): Promise<ScriptApiRecord[]> {
   const rows = await getDbClient().query<ScriptApiRow>(
     "SELECT * FROM script_apis WHERE scriptId = ? ORDER BY createdAt DESC",
@@ -554,7 +578,7 @@ export async function getScriptApiSecret(id: string): Promise<string | null> {
   );
   if (!row?.bearerTokenEncrypted) return null;
   const token = decryptSecret(row.bearerTokenEncrypted, getEncryptionKey());
-  registerVolatileSecret(token, `script-api:${id}`);
+  registerStoredSecret(token, scriptApiSecretName(id));
   return token;
 }
 
@@ -604,7 +628,7 @@ export async function rotateScriptApiSecret(
     [encrypted, updatedBy ?? null, id],
   );
   if (!row) return null;
-  registerVolatileSecret(token, `script-api:${id}`);
+  registerStoredSecret(token, scriptApiSecretName(id));
   return { ...rowToScriptApi(row), token };
 }
 

package/src/be/scripts/source-secrets.ts

@@ -0,0 +1,37 @@
+import { findSecretsIn } from "../../utils/secret-scrubber";
+
+/**
+ * Executable source is stored and served verbatim (`scripts.source`,
+ * `script_versions.source`, `script_runs.source`): redacting it would change
+ * what runs, and sealing it would hide reviewed code. So a source that embeds
+ * a secret is refused at write instead, before anything runs or persists.
+ *
+ * Checked: every registered secret value, in each encoded form the known-value
+ * matcher holds, and the gitleaks vendor-token rules. The refusal names the
+ * secret's key or the rule id, never the value. Rows written before this check
+ * are left as they are.
+ */
+export interface SourceSecretRefusal {
+  error: "source_contains_secret";
+  message: string;
+  findings: { kind: "registered-secret" | "gitleaks-rule"; id: string }[];
+}
+
+export function refuseSourceWithSecrets(source: string): SourceSecretRefusal | null {
+  const { knownValues, gitleaksRules } = findSecretsIn(source);
+  if (knownValues.length === 0 && gitleaksRules.length === 0) return null;
+  const findings = [
+    ...knownValues.map((id) => ({ kind: "registered-secret" as const, id })),
+    ...gitleaksRules.map((id) => ({ kind: "gitleaks-rule" as const, id })),
+  ];
+  const named = findings
+    .map((f) =>
+      f.kind === "registered-secret" ? `registered secret ${f.id}` : `gitleaks rule ${f.id}`,
+    )
+    .join(", ");
+  return {
+    error: "source_contains_secret",
+    message: `Script source contains a secret (${named}); nothing was saved or run. Source is stored and shown verbatim, so read secrets at run time instead: a credential binding (ctx.api.<slug> / ctx.mcp.<slug>) or ctx.swarm.config.get("<KEY>").`,
+    findings,
+  };
+}

package/src/be/scripts/typecheck.ts

@@ -106,6 +106,26 @@ export interface KvEntry<T = unknown> {
   expiresAt: number | null;
   createdAt: number;
   updatedAt: number;
+  /** Present only on a path/offset/limit read. */
+  view?: KvView;
+}
+
+export interface KvViewArgs {
+  /** Dot path into the JSON value, e.g. "outcome.data.rows" or "rows.3". */
+  path?: string;
+  /** First array item / object key / string char. Default 0. */
+  offset?: number;
+  /** Max items / keys / chars. Unbounded in scripts. */
+  limit?: number;
+}
+
+export interface KvView {
+  path: string;
+  type: "object" | "array" | "string" | "number" | "boolean" | "null";
+  total?: number;
+  offset?: number;
+  returned?: number;
+  nextOffset?: number | null;
 }
 
 export interface KvSdkSuccess<T, TStatus extends number = 200> {
@@ -175,8 +195,9 @@ export interface SwarmSdk {
   task_defer(args: { taskId: string; delayMs?: number; runAt?: string; wakeOn?: { event: "task.completed" | "task.failed" | "settled"; taskId: string }; summary: string; note: string; checks?: string[] }): Promise<unknown>;
   task_poll(args?: Record<string, unknown>): Promise<unknown>;
   // --- kv ---
-  kv_get<T = unknown>(args: { key: string; namespace?: string }): Promise<KvSdkResponse<KvEntry<T>>>;
-  kv_getOrNull<T = unknown>(args: { key: string; namespace?: string }): Promise<KvEntry<T> | null>;
+  /** path/offset/limit return a view: \`value\` is the slice at a dot path (JSON strings count as JSON), paged over items/keys/chars; \`view\` describes it. */
+  kv_get<T = unknown>(args: { key: string; namespace?: string } & KvViewArgs): Promise<KvSdkResponse<KvEntry<T>>>;
+  kv_getOrNull<T = unknown>(args: { key: string; namespace?: string } & KvViewArgs): Promise<KvEntry<T> | null>;
   kv_set<T>(args: KvSetArgsBase & { value: T; valueType?: "json" }): Promise<KvSdkResponse<KvEntry<T>>>;
   kv_set(args: KvSetArgsBase & { value: string; valueType: "string" }): Promise<KvSdkResponse<KvEntry<string>>>;
   kv_set(args: KvSetArgsBase & { value: number | string; valueType: "integer" }): Promise<KvSdkResponse<KvEntry<number>>>;

package/src/be/scrub-json.ts

@@ -0,0 +1,32 @@
+import { type ScrubbedText, scrubObject, scrubSecrets } from "../utils/secret-scrubber";
+
+/** True when `before` parsed as JSON and `after` no longer does. */
+export function breaksJsonValidity(before: string, after: string): boolean {
+  try {
+    JSON.parse(before);
+  } catch {
+    return false;
+  }
+  try {
+    JSON.parse(after);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Serialize `value` for a JSON TEXT column with secrets redacted.
+ *
+ * Scrubs the serialized text first, so context-keyed passes (`"password":
+ * "..."`, auth headers) see the key next to its value. When a redaction breaks
+ * JSON validity (a marker swallowed a quote or brace), falls back to scrubbing
+ * each string leaf, which always serializes cleanly. Readers keep `JSON.parse`.
+ */
+export function scrubJsonValue(value: unknown): ScrubbedText {
+  const raw = JSON.stringify(value);
+  const scrubbed = scrubSecrets(raw);
+  if (!breaksJsonValidity(raw, scrubbed)) return scrubbed;
+  // Every string leaf went through scrubSecrets; the brand holds.
+  return JSON.stringify(scrubObject(value)) as ScrubbedText;
+}

package/src/be/sealed-json.ts

@@ -0,0 +1,59 @@
+import { decryptSecret, encryptSecret, getEncryptionKey } from "./crypto";
+import { scrubJsonValue } from "./scrub-json";
+
+/**
+ * Sealed JSON: byte-exact replay state, encrypted at rest.
+ *
+ * Some JSON columns are execution inputs, not records. The supervisor relaunches
+ * a durable script run from `script_runs.args`, and the harness replays
+ * `script_run_journal.result` as a step's return value. Redacting them would
+ * change what the script sees after a restart, and storing them raw leaves a
+ * secret at rest. Sealing keeps the exact bytes for the replay readers and
+ * nothing readable for anything that scans the database.
+ *
+ * Readers pick a view: `openSealedJson` (replay, exact value) or
+ * `sealedJsonForDisplay` (API/UI, redacted). Rows written before sealing are
+ * plain JSON and both readers still accept them.
+ */
+
+const SEALED_PREFIX = "sealed:v1:";
+
+/**
+ * Every column a writer fills with `sealJson`. Boot counts a sealed value here
+ * as encrypted data, like an encrypted config or OAuth row: with the key
+ * missing, startup refuses instead of generating a replacement key that could
+ * never open them. Add a column here when a writer starts sealing it.
+ */
+export const SEALED_REPLAY_COLUMNS: readonly { table: string; column: string }[] = [
+  { table: "script_runs", column: "args" },
+  { table: "script_run_journal", column: "result" },
+  { table: "workflow_run_steps", column: "output_replay" },
+  { table: "workflow_runs", column: "context_replay" },
+  { table: "approval_requests", column: "responses" },
+];
+
+/** SQL `EXISTS` arms matching a sealed value in each `SEALED_REPLAY_COLUMNS` entry. */
+export function sealedReplayExistsSql(): string[] {
+  return SEALED_REPLAY_COLUMNS.map(
+    ({ table, column }) => `SELECT 1 FROM ${table} WHERE ${column} GLOB '${SEALED_PREFIX}*'`,
+  );
+}
+
+export function sealJson(value: unknown): string {
+  return SEALED_PREFIX + encryptSecret(JSON.stringify(value), getEncryptionKey());
+}
+
+export function isSealedJson(text: string): boolean {
+  return text.startsWith(SEALED_PREFIX);
+}
+
+/** The exact stored value. Only execution and replay paths may call this. */
+export function openSealedJson(text: string): unknown {
+  if (!isSealedJson(text)) return JSON.parse(text);
+  return JSON.parse(decryptSecret(text.slice(SEALED_PREFIX.length), getEncryptionKey()));
+}
+
+/** The stored value with secrets redacted, for API responses and the UI. */
+export function sealedJsonForDisplay(text: string): unknown {
+  return JSON.parse(scrubJsonValue(openSealedJson(text)));
+}