@humwick/server 0.0.0-stage → 0.130.1

package/src/db/user-invites.ts

@@ -0,0 +1,107 @@
+// Single-use user invites (#3567 D2). Persistence only: the route owns the flag and the admin gate,
+// the service owns password hashing. A code is shown once and stored as its SHA-256; accepting is
+// one write transaction that claims the invite (`used_at IS NULL` CAS), creates the user and links
+// the password identity, so a replayed or raced code can never create a second account.
+import { createHash, randomBytes } from "node:crypto";
+import { ValidationError, getDb, writeTransaction } from "./connection.ts";
+import { createUser } from "./users.ts";
+import { createAuthIdentity } from "./auth-identities.ts";
+import type { User, UserRole } from "../types";
+
+export const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface UserInvite {
+  id: string;
+  role: UserRole;
+  displayName: string | null;
+  createdBy: string;
+  expiresAt: number;
+  usedAt: number | null;
+  usedBy: string | null;
+  createdAt: number;
+}
+
+interface UserInviteRow {
+  id: string;
+  code_hash: string;
+  role: string;
+  display_name: string | null;
+  created_by: string;
+  expires_at: number;
+  used_at: number | null;
+  used_by: string | null;
+  created_at: number;
+}
+
+export function ensureUserInvitesSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS user_invites (
+      id TEXT PRIMARY KEY,
+      code_hash TEXT NOT NULL UNIQUE,
+      role TEXT NOT NULL,
+      display_name TEXT,
+      created_by TEXT NOT NULL REFERENCES users(id),
+      expires_at INTEGER NOT NULL,
+      used_at INTEGER,
+      used_by TEXT REFERENCES users(id),
+      created_at INTEGER NOT NULL
+    )
+  `);
+}
+
+export function hashInviteCode(code: string): string {
+  return createHash("sha256").update(code).digest("hex");
+}
+
+function rowToInvite(row: UserInviteRow): UserInvite {
+  return {
+    id: row.id,
+    role: row.role as UserRole,
+    displayName: row.display_name,
+    createdBy: row.created_by,
+    expiresAt: row.expires_at,
+    usedAt: row.used_at,
+    usedBy: row.used_by,
+    createdAt: row.created_at,
+  };
+}
+
+/** Create an invite and return it with its plaintext code (shown once, never stored). */
+export function createUserInvite(input: { role: UserRole; displayName?: string; createdBy: string; now?: number }): { invite: UserInvite; code: string } {
+  const now = input.now ?? Date.now();
+  const code = randomBytes(32).toString("base64url");
+  const id = `inv_${randomBytes(8).toString("hex")}`;
+  getDb()
+    .query(`INSERT INTO user_invites (id, code_hash, role, display_name, created_by, expires_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+    .run(id, hashInviteCode(code), input.role, input.displayName ?? null, input.createdBy, now + INVITE_TTL_MS, now);
+  return { invite: getUserInvite(id)!, code };
+}
+
+export function getUserInvite(id: string): UserInvite | undefined {
+  const row = getDb().query("SELECT * FROM user_invites WHERE id = ?").get(id) as UserInviteRow | null;
+  return row ? rowToInvite(row) : undefined;
+}
+
+/** Thrown when a code is unknown, expired or already used: the route answers 410 for all three. */
+export class InviteUnavailableError extends Error {}
+
+/**
+ * Accept an invite: claim it, create the user with the invite's role, and link the login identity
+ * (`secretHash` is hashed by the caller, outside the transaction). All or nothing.
+ */
+export function acceptUserInvite(input: { code: string; userId: string; handle: string; displayName?: string; provider: string; secretHash: string; now?: number }): User {
+  const now = input.now ?? Date.now();
+  return writeTransaction(() => {
+    const row = getDb().query("SELECT * FROM user_invites WHERE code_hash = ?").get(hashInviteCode(input.code)) as UserInviteRow | null;
+    if (!row || row.used_at !== null || row.expires_at <= now) throw new InviteUnavailableError("invite is invalid, expired or already used");
+    if (getDb().query("SELECT 1 FROM users WHERE id = ? OR handle = ?").get(input.userId, input.handle)) {
+      throw new ValidationError(`handle "${input.handle}" is taken`);
+    }
+    const claimed = getDb().query("UPDATE user_invites SET used_at = ? WHERE id = ? AND used_at IS NULL").run(now, row.id);
+    if (claimed.changes !== 1) throw new InviteUnavailableError("invite is invalid, expired or already used");
+    const user = createUser({ id: input.userId, handle: input.handle, displayName: input.displayName || row.display_name || input.handle, role: row.role as UserRole });
+    createAuthIdentity({ userId: user.id, provider: input.provider, providerSubject: input.handle, secretHash: input.secretHash });
+    getDb().query("UPDATE user_invites SET used_by = ? WHERE id = ?").run(user.id, row.id);
+    return user;
+  });
+}

package/src/db/user-settings-read-ops.ts

@@ -0,0 +1,19 @@
+// User-settings reader-op registry (#391, #1870/#1991 data-store leaf). Domain-owned map; the op
+// bodies live in `../user-settings-store.ts` (row shape + validation) and take `db` explicitly, so
+// this thin wrapper is the ONLY place that resolves the thread-local connection via `getDb()` for a
+// per-user settings read. The shared `read-ops.ts` edit stays one import + spread.
+
+import { getUserSetting, listUserSettings } from "../user-settings-store.ts";
+import { getDb } from "./connection.ts";
+
+export const USER_SETTINGS_READ_OPS = Object.freeze({
+  "userSettings.get": (args: { userId: string; namespace: string; key: string }) =>
+    getUserSetting(getDb(), args.userId, args.namespace, args.key),
+  "userSettings.list": (args: { userId: string; namespace: string }) =>
+    listUserSettings(getDb(), args.userId, args.namespace),
+});
+
+/** Sync read for the synchronous prompt composer (#3567): the principal's agent preferences. */
+export function readUserSettingValue(userId: string, namespace: string, key: string): unknown {
+  return getUserSetting(getDb(), userId, namespace, key)?.value;
+}

package/src/db/user-settings-write-ops.ts

@@ -0,0 +1,43 @@
+// User-settings writer-op registry (#391, ADR 0001 §3.1/§3.4/§3.7.1, #1870/#1991 data-store leaf).
+// Domain-owned map; the op body lives in `../user-settings-store.ts` and takes `db` explicitly, so
+// this wrapper is the only place that resolves the thread-local connection via `getDb()`.
+//
+// LANDMINE #2 (TOCTOU / lost-update, ADR §3.4, mirrored from config-store's `config.set`):
+// `setUserSetting` computes `version = existing.version + 1` from a read that runs in the SAME op
+// body as the write, under the executor's already-open transaction — so two concurrent setters for
+// the same (user, namespace, key) can't both read version N and both commit N+1.
+
+import { deleteUserSetting, setUserSetting } from "../user-settings-store.ts";
+import { getDb } from "./connection.ts";
+import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
+
+export interface SetUserSettingOpArgs {
+  readonly userId: string;
+  readonly namespace: string;
+  readonly key: string;
+  readonly value: unknown;
+  readonly updatedBy?: string;
+}
+
+export interface DeleteUserSettingOpArgs {
+  readonly userId: string;
+  readonly namespace: string;
+  readonly key: string;
+}
+
+export const USER_SETTINGS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  // Non-idempotent: `version` increments on every apply, so a blind retry would double-bump. The
+  // gateway requires an idempotencyKey (the facade supplies a per-submission one).
+  "userSettings.set": {
+    offLoop: true,
+    idempotent: false,
+    fn: (args: SetUserSettingOpArgs, ctx: WriterOpContext) =>
+      setUserSetting(getDb(), args.userId, args.namespace, args.key, args.value, args.updatedBy, ctx.now),
+  },
+  // Idempotent by construction: deleting again finds no row (`existing` null → early false).
+  "userSettings.delete": {
+    offLoop: true,
+    idempotent: true,
+    fn: (args: DeleteUserSettingOpArgs) => deleteUserSetting(getDb(), args.userId, args.namespace, args.key),
+  },
+});

package/src/db/users.ts

@@ -0,0 +1,173 @@
+import { assertMainThreadState } from "./main-thread-state";
+// First-class human users (#388 keystone #393). The relational identity store behind the
+// per-user `user:<id>` addressing namespace. Addressing/alias logic lives in the SDK
+// (@humwick/sdk `users.ts`, the single resolver home); this module owns persistence.
+import { DEFAULT_USER_ID } from "@humwick/sdk";
+import { ValidationError, getDb } from "./connection.ts";
+import type { CreateUserInput, User, UserRole, UserStatus } from "../types";
+
+interface UserRow {
+  id: string;
+  handle: string;
+  display_name: string;
+  role: string;
+  status: string;
+  tenant_id: string | null;
+  avatar_artifact_id: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Single DDL home for the `users` table (#388 keystone #393). Called from initDb (fresh DBs)
+ * and applyMigrations (existing DBs gain it on upgrade), mirroring the
+ * `dropLegacyContinuationArchiveIndex` pattern. `tenant_id` is the SaaS multi-tenant seam
+ * (nullable, defaulted — multi-tenant becomes an additive migration, not a refactor);
+ * `avatar_artifact_id` is the column-only avatar FK toward the artifact stack (#395/#630).
+ */
+export function ensureUsersSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      handle TEXT NOT NULL,
+      display_name TEXT NOT NULL,
+      role TEXT NOT NULL DEFAULT 'operator',
+      status TEXT NOT NULL DEFAULT 'active',
+      tenant_id TEXT DEFAULT 'default',
+      avatar_artifact_id TEXT REFERENCES artifacts(id) ON DELETE SET NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_users_handle ON users(coalesce(tenant_id, ''), handle)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_users_tenant ON users(tenant_id)");
+}
+
+function rowToUser(row: UserRow): User {
+  return {
+    id: row.id,
+    handle: row.handle,
+    displayName: row.display_name,
+    role: row.role as UserRole,
+    status: row.status as UserStatus,
+    tenantId: row.tenant_id,
+    avatarArtifactId: row.avatar_artifact_id,
+    avatarUrl: row.avatar_artifact_id ? `/users/${encodeURIComponent(row.id)}/avatar` : null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export function getUser(id: string): User | undefined {
+  const row = getDb().query("SELECT * FROM users WHERE id = ?").get(id) as UserRow | null;
+  return row ? rowToUser(row) : undefined;
+}
+
+export function getUserByHandle(handle: string, tenantId: string | null = "default"): User | undefined {
+  const row = getDb()
+    .query("SELECT * FROM users WHERE handle = ? AND coalesce(tenant_id, '') = coalesce(?, '')")
+    .get(handle, tenantId) as UserRow | null;
+  return row ? rowToUser(row) : undefined;
+}
+
+export function listUsers(): User[] {
+  const rows = getDb().query("SELECT * FROM users ORDER BY created_at").all() as UserRow[];
+  return rows.map(rowToUser);
+}
+
+// #3567 — the user count gates every multi-user check on hot paths (sends to `user`, authz), so it
+// is cached. A create in this process invalidates at once; the short TTL bounds staleness for writes
+// made by another connection (a reader worker, a maintenance subprocess).
+const USER_COUNT_TTL_MS = 5_000;
+let userCountCache: { db: ReturnType<typeof getDb>; count: number; at: number } | undefined;
+
+export function userCount(now: number = Date.now()): number {
+  assertMainThreadState("users.ts");
+  const db = getDb();
+  if (userCountCache?.db === db && now - userCountCache.at < USER_COUNT_TTL_MS) return userCountCache.count;
+  const count = (db.query("SELECT count(*) AS n FROM users").get() as { n: number } | null)?.n ?? 0;
+  userCountCache = { db, count, at: now };
+  return count;
+}
+
+export function createUser(input: CreateUserInput): User {
+  assertMainThreadState("users.ts");
+  if (!input.id) throw new ValidationError("user id is required");
+  if (!input.handle) throw new ValidationError("user handle is required");
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO users (id, handle, display_name, role, status, tenant_id, avatar_artifact_id, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      input.id,
+      input.handle,
+      input.displayName || input.handle,
+      input.role ?? "operator",
+      input.status ?? "active",
+      input.tenantId === undefined ? "default" : input.tenantId,
+      input.avatarArtifactId ?? null,
+      now,
+      now,
+    );
+  userCountCache = undefined;
+  const created = getUser(input.id);
+  if (!created) throw new ValidationError(`failed to create user ${input.id}`);
+  return created;
+}
+
+export function updateUserProfile(input: {
+  id: string;
+  displayName?: string;
+  avatarArtifactId?: string | null;
+}): User {
+  const current = getUser(input.id);
+  if (!current) throw new ValidationError("user not found");
+  const updates: string[] = [];
+  const params: Array<string | number | null> = [];
+  if (input.displayName !== undefined) {
+    if (!input.displayName.trim()) throw new ValidationError("displayName required");
+    updates.push("display_name = ?");
+    params.push(input.displayName.trim());
+  }
+  if (input.avatarArtifactId !== undefined) {
+    updates.push("avatar_artifact_id = ?");
+    params.push(input.avatarArtifactId);
+  }
+  if (!updates.length) return current;
+  updates.push("updated_at = ?");
+  params.push(Date.now(), input.id);
+  getDb().query(`UPDATE users SET ${updates.join(", ")} WHERE id = ?`).run(...params);
+  return getUser(input.id)!;
+}
+
+/** Change a user's role or account status (#3567 admin user list). */
+export function updateUserAccess(input: { id: string; role?: UserRole; status?: UserStatus }): User {
+  const current = getUser(input.id);
+  if (!current) throw new ValidationError("user not found");
+  getDb().query("UPDATE users SET role = ?, status = ?, updated_at = ? WHERE id = ?")
+    .run(input.role ?? current.role, input.status ?? current.status, Date.now(), input.id);
+  return getUser(input.id)!;
+}
+
+/**
+ * Seed the admin-level default user mapped to the existing single human (#393 P0).
+ * Idempotent (ON CONFLICT DO NOTHING) so it runs safely on every boot/migration — the
+ * existing human is NEVER locked out, and the relational identity all later #388 waves FK to
+ * (`users.id='default'`, role=admin, tenant_id='default') exists from day one. Bare `'user'`
+ * and `user:default` both resolve to this row (see the SDK resolver helpers).
+ */
+export function seedDefaultUser(): User {
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO users (id, handle, display_name, role, status, tenant_id, avatar_artifact_id, created_at, updated_at)
+       VALUES (?, 'admin', 'User', 'admin', 'active', 'default', NULL, ?, ?)
+       ON CONFLICT(id) DO NOTHING`,
+    )
+    .run(DEFAULT_USER_ID, now, now);
+  const seeded = getUser(DEFAULT_USER_ID);
+  if (!seeded) throw new ValidationError("failed to seed default user");
+  return seeded;
+}

package/src/db/vault-backup.ts

@@ -0,0 +1,59 @@
+import { OPERATOR_ACTION_DONE, OPERATOR_ACTION_NOT_DONE, OPERATOR_ACTION_OUTCOME_ID, type VaultBackupStatus } from "@humwick/sdk";
+import { getConfig, setConfigInternal } from "../config-store";
+import { inWriteTransaction } from "./connection";
+import { insertOperatorDecision, withdrawOpenOperatorDecision } from "./operator-decisions";
+
+// #3572 — operational state of the vault backup, kept apart from the operator's settings.
+const STATE = ["vault-backup-state", "default"] as const;
+export const VAULT_BACKUP_TEAM = "vault-backup:global";
+export type VaultBackupWarning = NonNullable<VaultBackupStatus["warning"]>;
+export interface VaultBackupState {
+  lastSuccess: VaultBackupStatus["lastSuccess"];
+  lastError: VaultBackupStatus["lastError"];
+  warning?: { kind: VaultBackupWarning; decisionId: number };
+}
+
+export function readVaultBackupState(): VaultBackupState {
+  return { lastSuccess: null, lastError: null, ...getConfig<VaultBackupState>(...STATE)?.value };
+}
+const save = (state: VaultBackupState, now: number) => setConfigInternal(...STATE, state, "vault-backup", now);
+
+/** One outcome per attempt: a success clears the last error, a failure keeps the last success. */
+export function recordVaultBackup(args: { now: number; success?: NonNullable<VaultBackupStatus["lastSuccess"]>; error?: string }): void {
+  inWriteTransaction(() => {
+    const state = readVaultBackupState();
+    save(args.success ? { ...state, lastSuccess: args.success, lastError: null } : { ...state, lastError: { at: args.now, message: args.error ?? "backup failed" } }, args.now);
+  });
+}
+
+const WARNING_TEXT: Record<VaultBackupWarning, { title: string; context: string }> = {
+  "no-recipient": { title: "Set the vault backup recipient", context: "The vault holds secrets but has no backup recipient, so no backup is written. Set your age public key (age1…) in Settings → Secrets → Vault backup. Keep the private identity offline, never on the hub." },
+  stale: { title: "Vault backup is older than 48 hours", context: "The last successful vault backup is more than 48 hours old. Open the Secrets page to see the last error, then use Back up now." },
+};
+
+/**
+ * Files one operator action per warning episode. The action stays until the condition clears, so
+ * closing it without fixing the cause does not re-file it every hour. Returns changed decision ids.
+ */
+export function syncVaultBackupWarning(args: { kind: VaultBackupWarning | null; now: number }): Array<{ id: number; status: "open" | "withdrawn" }> {
+  return inWriteTransaction(() => {
+    const state = readVaultBackupState();
+    if (state.warning?.kind === args.kind) return [];
+    const changed: Array<{ id: number; status: "open" | "withdrawn" }> = [];
+    if (state.warning && withdrawOpenOperatorDecision(state.warning.decisionId, args.now)) changed.push({ id: state.warning.decisionId, status: "withdrawn" });
+    let warning: VaultBackupState["warning"];
+    if (args.kind) {
+      const decision = insertOperatorDecision({ teamId: VAULT_BACKUP_TEAM, filedBy: "system", kind: "action", ...WARNING_TEXT[args.kind], links: [], timeCritical: false,
+        questions: [{ id: OPERATOR_ACTION_OUTCOME_ID, prompt: "Is the vault backup fixed?", kind: "single", options: [{ label: OPERATOR_ACTION_DONE }, { label: OPERATOR_ACTION_NOT_DONE }] }], now: args.now });
+      warning = { kind: args.kind, decisionId: decision.id };
+      changed.push({ id: decision.id, status: "open" });
+    }
+    save({ lastSuccess: state.lastSuccess, lastError: state.lastError, ...(warning ? { warning } : {}) }, args.now);
+    return changed;
+  });
+}
+
+export const VAULT_BACKUP_WRITE_OPS = {
+  "secretsVault.backup.record": { offLoop: true, idempotent: true, fn: recordVaultBackup },
+  "secretsVault.backup.warn": { offLoop: true, idempotent: true, fn: syncVaultBackupWarning },
+};

package/src/db/vault-expiry.ts

@@ -0,0 +1,71 @@
+import type { VaultMetadata } from "@humwick/sdk";
+import { OPERATOR_ACTION_DONE, OPERATOR_ACTION_NOT_DONE, OPERATOR_ACTION_OUTCOME_ID } from "@humwick/sdk";
+import { getDb, inWriteTransaction } from "./connection";
+import { insertOperatorDecision, withdrawOpenOperatorDecision } from "./operator-decisions";
+import { seatTeamIdForProject } from "./team-project";
+import { parseSecretName, scopedSecretName } from "../secrets-vault/identity";
+import { vaultExpiryDescription } from "../secrets-vault/expiry";
+import { getVaultExpiryLeadMs } from "../vault-expiry-config";
+
+export const VAULT_EXPIRY_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS vault_expiry_notices (
+  name TEXT NOT NULL, environment TEXT NOT NULL, version INTEGER NOT NULL, expires_at TEXT NOT NULL,
+  decision_id INTEGER NOT NULL, team_id TEXT, notified INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY(name, environment)
+)`;
+
+interface Notice { name: string; environment: string; version: number; expires_at: string; decision_id: number; team_id: string | null; notified: number }
+
+/** A project has a stable seat. Global secrets follow the team that last set or used them. */
+function owningTeam(name: string, projectId?: string): string | null {
+  if (projectId) return seatTeamIdForProject(projectId);
+  const row = getDb().query(`SELECT a.team_id FROM secret_broker_audit s JOIN agents a ON a.id = s.actor
+    JOIN teams t ON t.id = a.team_id WHERE s.secret_key = ? AND s.outcome = 'ok'
+    AND s.action IN ('set','rotated','resolved','requested') AND t.status = 'active' ORDER BY s.seq DESC LIMIT 1`).get(name) as { team_id: string } | null;
+  return row?.team_id ?? null;
+}
+
+/** Prepare actions and delivery records together, without reading or decrypting secret values. */
+export function prepareVaultExpiryNotices(args: { now: number }) {
+  return inWriteTransaction(() => {
+    const db = getDb();
+    const changed: Array<{ id: number; teamId: string; status: "open" | "withdrawn" }> = [];
+    const previous = db.query("SELECT * FROM vault_expiry_notices").all() as Notice[];
+    const current = db.query(`SELECT v.name, v.environment, MAX(v.version) AS version, m.metadata
+      FROM secret_vault_versions v JOIN secret_vault_metadata m ON m.name = v.name AND m.environment = v.environment
+      WHERE json_extract(m.metadata, '$.expiresAt') IS NOT NULL GROUP BY v.name, v.environment`).all() as Array<{ name: string; environment: string; version: number; metadata: string }>;
+    const byName = new Map(current.map(row => [JSON.stringify([row.name, row.environment]), row]));
+    for (const old of previous) {
+      const row = byName.get(JSON.stringify([old.name, old.environment]));
+      if (row && row.version === old.version && JSON.parse(row.metadata).expiresAt === old.expires_at) continue;
+      if (withdrawOpenOperatorDecision(old.decision_id, args.now)) changed.push({ id: old.decision_id, teamId: old.team_id ?? "vault-expiry:global", status: "withdrawn" });
+      db.query("DELETE FROM vault_expiry_notices WHERE name=? AND environment=?").run(old.name, old.environment);
+    }
+    const leadMs = getVaultExpiryLeadMs();
+    for (const row of current) {
+      const metadata = JSON.parse(row.metadata) as VaultMetadata;
+      if (!(Date.parse(metadata.expiresAt!) <= args.now + leadMs)) continue;
+      if (db.query("SELECT 1 FROM vault_expiry_notices WHERE name=? AND environment=?").get(row.name, row.environment)) continue;
+      const identity = parseSecretName(row.name);
+      const ref = scopedSecretName(identity.name, identity.projectId, row.environment);
+      const parsed = parseSecretName(ref);
+      const teamId = owningTeam(ref, parsed.projectId);
+      const scope = parsed.projectId ? `project:${parsed.projectId}` : "global";
+      const decision = insertOperatorDecision({ teamId: teamId ?? "vault-expiry:global", ...(parsed.projectId ? { projectId: parsed.projectId } : {}), filedBy: "system", kind: "action",
+        title: `Rotate secret ${parsed.name} (${scope}, ${row.environment})`.slice(0, 200),
+        context: `${vaultExpiryDescription(parsed.name, metadata, args.now)}\nScope: ${scope}. Environment: ${row.environment}. Version: ${row.version}.`,
+        links: metadata.sourceUrl ? [metadata.sourceUrl] : [], timeCritical: true,
+        questions: [{ id: OPERATOR_ACTION_OUTCOME_ID, prompt: "Did you rotate the secret?", kind: "single", options: [{ label: OPERATOR_ACTION_DONE }, { label: OPERATOR_ACTION_NOT_DONE }] }], now: args.now });
+      db.query("INSERT INTO vault_expiry_notices(name,environment,version,expires_at,decision_id,team_id,notified) VALUES(?,?,?,?,?,?,?)")
+        .run(row.name, row.environment, row.version, metadata.expiresAt!, decision.id, teamId, Number(!teamId));
+      changed.push({ id: decision.id, teamId: decision.teamId, status: "open" });
+    }
+    const pending = db.query(`SELECT n.decision_id AS id, n.team_id AS teamId, d.context AS body FROM vault_expiry_notices n
+      JOIN operator_decisions d ON d.id = n.decision_id WHERE n.notified = 0`).all() as Array<{ id: number; teamId: string; body: string }>;
+    return { changed, pending };
+  });
+}
+
+export const VAULT_EXPIRY_WRITE_OPS = {
+  "secretsVault.expiry.prepare": { offLoop: true, idempotent: true, fn: prepareVaultExpiryNotices },
+  "secretsVault.expiry.sent": { offLoop: true, idempotent: true, fn: (args: { id: number }) => { getDb().query("UPDATE vault_expiry_notices SET notified=1 WHERE decision_id=?").run(args.id); } },
+};

package/src/db/vault-health.ts

@@ -0,0 +1,99 @@
+import type { ServiceAccessHostHealth, ServiceAccessLogCollection, ServiceAccessLogPage, ServiceAccessRequestLog, ServiceAccessVaultHealth } from "@humwick/sdk";
+import { getDb } from "./connection";
+import type { WriterOpContext, WriterOpSpec } from "./write-ops";
+
+export const VAULT_LOG_RETENTION_MS = 30 * 86_400_000;
+export const VAULT_LOG_CAP_PER_SOURCE = 20_000;
+const PRUNE_BATCH = 5_000;
+
+/** `source` names one vault on one broker, so a replaced broker's restarted native ids never collide. */
+export interface VaultHealthState extends ServiceAccessVaultHealth { source: string }
+
+export interface VaultLogCollect {
+  source: string;
+  health: Omit<VaultHealthState, "logs">;
+  logs: ServiceAccessRequestLog[];
+  collection: Pick<ServiceAccessLogCollection, "cursor" | "backlog" | "error">;
+}
+
+export function ensureVaultHealthSchema(): void {
+  getDb().run(`CREATE TABLE IF NOT EXISTS vault_request_logs (
+    source TEXT NOT NULL, native_id INTEGER NOT NULL, profile TEXT NOT NULL, at INTEGER NOT NULL, data TEXT NOT NULL,
+    PRIMARY KEY (source, native_id)
+  ) WITHOUT ROWID;
+  CREATE INDEX IF NOT EXISTS idx_vault_request_logs_profile ON vault_request_logs(profile, at, native_id);
+  CREATE INDEX IF NOT EXISTS idx_vault_request_logs_age ON vault_request_logs(at);
+  CREATE TABLE IF NOT EXISTS vault_health (key TEXT PRIMARY KEY, updated_at INTEGER NOT NULL, data TEXT NOT NULL);`);
+}
+
+function readState<T>(key: string): T | undefined {
+  const row = getDb().query("SELECT data FROM vault_health WHERE key = ?").get(key) as { data: string } | null;
+  return row ? JSON.parse(row.data) as T : undefined;
+}
+
+function writeState(key: string, value: unknown, now: number): void {
+  getDb().query("INSERT INTO vault_health VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET updated_at = excluded.updated_at, data = excluded.data")
+    .run(key, now, JSON.stringify(value));
+}
+
+const storedCount = (source: string) => (getDb().query("SELECT count(*) AS n FROM vault_request_logs WHERE source = ?").get(source) as { n: number }).n;
+
+/** Rows and cursor commit together: a crash replays the same page and the primary key drops repeats. */
+export function collectVaultLogs(input: VaultLogCollect, now: number): { inserted: number; duplicates: number } {
+  const insert = getDb().query("INSERT OR IGNORE INTO vault_request_logs VALUES (?, ?, ?, ?, ?)");
+  let inserted = 0;
+  for (const log of input.logs) inserted += insert.run(input.source, log.id, log.profile, log.at, JSON.stringify(log)).changes;
+  const previous = readState<VaultHealthState>(`vault:${input.source}`)?.logs;
+  const newest = input.logs.reduce((max, log) => Math.max(max, log.at), previous?.newestAt ?? 0);
+  const logs: ServiceAccessLogCollection = {
+    cursor: Math.max(previous?.cursor ?? 0, input.collection.cursor),
+    stored: storedCount(input.source),
+    ...(input.collection.error ? { collectedAt: previous?.collectedAt, error: input.collection.error } : { collectedAt: now }),
+    ...(newest ? { newestAt: newest } : {}),
+    ...(input.collection.backlog ? { backlog: true } : {}),
+    ...(previous?.evicted ? { evicted: previous.evicted } : {}),
+  };
+  if (logs.collectedAt === undefined) delete logs.collectedAt;
+  writeState(`vault:${input.source}`, { ...input.health, source: input.source, logs }, now);
+  return { inserted, duplicates: input.logs.length - inserted };
+}
+
+export function pruneVaultLogs(now: number): { expired: number; evicted: number } {
+  const db = getDb();
+  const expired = db.query("DELETE FROM vault_request_logs WHERE (source, native_id) IN (SELECT source, native_id FROM vault_request_logs WHERE at < ? LIMIT ?)").run(now - VAULT_LOG_RETENTION_MS, PRUNE_BATCH).changes;
+  let evicted = 0;
+  const sources = db.query("SELECT source, count(*) AS n FROM vault_request_logs GROUP BY source HAVING n > ?").all(VAULT_LOG_CAP_PER_SOURCE) as Array<{ source: string; n: number }>;
+  for (const { source, n } of sources) {
+    const excess = Math.min(n - VAULT_LOG_CAP_PER_SOURCE, PRUNE_BATCH);
+    const removed = db.query("DELETE FROM vault_request_logs WHERE source = ? AND native_id IN (SELECT native_id FROM vault_request_logs WHERE source = ? ORDER BY native_id LIMIT ?)").run(source, source, excess).changes;
+    evicted += removed;
+    const state = readState<VaultHealthState>(`vault:${source}`);
+    if (state) writeState(`vault:${source}`, { ...state, logs: { ...state.logs, stored: n - removed, evicted: (state.logs.evicted ?? 0) + removed } }, now);
+  }
+  return { expired, evicted };
+}
+
+export function logPage(args: { profile?: string; before?: { at: number; id: number }; limit: number }): ServiceAccessLogPage {
+  const where: string[] = [], params: Array<string | number> = [];
+  if (args.profile) { where.push("profile = ?"); params.push(args.profile); }
+  if (args.before) { where.push("(at < ? OR (at = ? AND native_id < ?))"); params.push(args.before.at, args.before.at, args.before.id); }
+  const rows = getDb().query(`SELECT data FROM vault_request_logs ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY at DESC, native_id DESC LIMIT ?`)
+    .all(...params, args.limit + 1) as Array<{ data: string }>;
+  const logs = rows.slice(0, args.limit).map((row) => JSON.parse(row.data) as ServiceAccessRequestLog);
+  const last = logs.at(-1);
+  return { logs, ...(rows.length > args.limit && last ? { next: `${last.at}:${last.id}` } : {}) };
+}
+
+export const VAULT_HEALTH_WRITE_OPS: Record<string, WriterOpSpec> = {
+  "vaultHealth.host": { offLoop: true, idempotent: true, fn: (host: ServiceAccessHostHealth, ctx: WriterOpContext) => { writeState("host", host, ctx.now); return null; } },
+  "vaultHealth.collect": { offLoop: true, idempotent: true, fn: (input: VaultLogCollect, ctx: WriterOpContext) => collectVaultLogs(input, ctx.now) },
+  "vaultHealth.prune": { offLoop: true, idempotent: true, fn: (args: { now: number }) => pruneVaultLogs(args.now) },
+};
+
+export const VAULT_HEALTH_READ_OPS = {
+  "vaultHealth.snapshot": () => ({
+    host: readState<ServiceAccessHostHealth>("host") ?? null,
+    vaults: (getDb().query("SELECT data FROM vault_health WHERE key LIKE 'vault:%'").all() as Array<{ data: string }>).map((row) => JSON.parse(row.data) as VaultHealthState),
+  }),
+  "vaultHealth.logs": (args: { profile?: string; before?: { at: number; id: number }; limit: number }) => logPage(args),
+};

package/src/db/vault-token-launch.ts

@@ -0,0 +1,77 @@
+import { isRecord, type ServiceAccessCatalog, type ServiceAccessProfileState } from "@humwick/sdk";
+import { getConfig, getAgentProfile } from "../config-store";
+import { ValidationError } from "./connection";
+import { getAgent } from "./agents";
+import { desiredServiceAccess, retainsServiceAccess } from "../service-access/policy";
+import { vaultToken, vaultTokenRows, saveVaultToken, transitionVaultToken, revokeVaultTokens, terminalProviderLaunchId, type VaultTokenRow } from "./vault-tokens";
+
+function policy(row: Pick<VaultTokenRow, "profile">) {
+  const profile = getAgentProfile(row.profile)?.value;
+  const catalog = getConfig<ServiceAccessCatalog>("service-access", "catalog")?.value;
+  if (!profile || !catalog) return null;
+  const state = getConfig<ServiceAccessProfileState>("service-access-state", row.profile.toLowerCase())?.value;
+  const desired = desiredServiceAccess(catalog, profile.name, profile.serviceAccess?.services ?? [], undefined, profile.serviceAccess?.vault);
+  return { catalog, desired, state, access: profile.serviceAccess };
+}
+
+function current(row: VaultTokenRow): boolean {
+  const agent = getAgent(row.agentId);
+  return !!agent && agent.instanceId === row.instanceId && agent.meta?.spawnRequestId === row.spawnRequestId
+    && terminalProviderLaunchId(agent.meta?.terminalProviderExit) !== row.launchId && !isRecord(agent.meta?.lastExit);
+}
+
+export function beginVaultToken(row: VaultTokenRow): VaultTokenRow | null {
+  const existing = vaultTokenRows("SELECT data FROM vault_tokens WHERE agent_id = ? AND instance_id = ? AND launch_id = ?", row.agentId, row.instanceId, row.launchId)[0];
+  if (existing) throw new ValidationError("vault_handoff_consumed: launch exchange is one-use; restart the provider");
+  if (!current(row)) throw new ValidationError("vault_launch_superseded: runner instance does not own this launch");
+  const resolved = policy(row);
+  if (!resolved?.desired.services.length) return null;
+  const state = resolved.state;
+  if (resolved.desired.desiredRevision !== row.revision || state?.status !== "applied" || state.appliedRevision !== row.revision) throw new ValidationError("vault_unapplied: service policy must be fully applied before launch");
+  revokeVaultTokens(row.agentId, row.createdAt, "replacement_launch");
+  return saveVaultToken(row);
+}
+
+export function activateVaultToken(id: string, sessionId: string, expiresAt: number, now: number): boolean {
+  const row = vaultToken(id);
+  if (!row) return false;
+  if (row.state === "active" && row.sessionId === sessionId && row.expiresAt === expiresAt) return true;
+  row.sessionId = sessionId; row.expiresAt = expiresAt;
+  if (row.state !== "minting" || !current(row) || policy(row)?.desired.desiredRevision !== row.revision) {
+    row.retryAt = now; transitionVaultToken(row, "revoke_pending", "launch_changed_during_mint", now); return false;
+  }
+  row.retryAt = now + 60_000;
+  transitionVaultToken(row, "active", "handoff", now);
+  return true;
+}
+
+/** #3577: a live launch rotates its broker session on the same row and label; a dead or narrowed launch revokes instead. */
+export function renewVaultToken(id: string, sessionId: string, expiresAt: number, now: number): boolean {
+  const row = vaultToken(id);
+  if (!row || !["active", "expired"].includes(row.state)) return false;
+  if (row.state === "active" && row.sessionId === sessionId && row.expiresAt === expiresAt) return true;
+  const resolved = policy(row);
+  // An in-runner restart keeps the instance, so only the newest launch row of the agent may renew.
+  const superseded = vaultTokenRows("SELECT data FROM vault_tokens WHERE agent_id = ? AND id != ? AND json_extract(data, '$.createdAt') > ? LIMIT 1", row.agentId, row.id, row.createdAt).length > 0;
+  if (superseded || !current(row) || !resolved || !retainsServiceAccess(row, resolved.catalog.broker, resolved.access)) {
+    row.retryAt = now; transitionVaultToken(row, "revoke_pending", "launch_changed_during_renewal", now); return false;
+  }
+  if (row.state === "active") row.audit = [...row.audit, { at: now, state: "active" as const, reason: "renewed" }].slice(-32);
+  row.sessionId = sessionId; row.expiresAt = expiresAt; row.retryAt = now + 60_000;
+  transitionVaultToken(row, "active", "renewed", now);
+  return true;
+}
+
+export function checkVaultToken(id: string, now: number): VaultTokenRow | undefined {
+  const row = vaultToken(id);
+  if (!row || ["revoked", "expired"].includes(row.state)) return row;
+  if (row.state === "minting") transitionVaultToken(row, "revoke_pending", "interrupted_mint", now);
+  if (row.state === "active") {
+    const resolved = policy(row);
+    const removed = !resolved || !retainsServiceAccess(row, resolved.catalog.broker, resolved.access);
+    if (!current(row) || removed) transitionVaultToken(row, "revoke_pending", removed ? "profile_access_removed" : "launch_dead", now);
+    else if (row.expiresAt! <= now) transitionVaultToken(row, "expired", "vault_token_expired", now);
+  }
+  row.retryAt = now + 60_000;
+  return saveVaultToken(row);
+}