@promptowl/contextnest-community 1.9.0 → 1.11.0

package/CONFIGURATION.md

@@ -56,16 +56,26 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `DB_SSL_CA` | `""` | Path to a CA certificate (PEM) for verify-ca/verify-full TLS when `DB_SSL=true`. |
 | `AUTH_MODE` | `key` | `key` or `open`. See above. |
 | `PROMPTOWL_API_URL` | `https://app.promptowl.ai` | PromptOwl's API origin — used for device auth, license validation, telemetry. Override for air-gapped or test setups. |
-| `PROMPTOWL_KEY` | `""` | Your PromptOwl Community License key (`pk_...`). Unlicensed instances still run and serve reads, but every write returns `503` until a valid key is installed. Can also be set via the browser License Setup Page, which persists it to `ENV_FILE_PATH`. |
+| `PROMPTOWL_KEY` | `""` | Your PromptOwl Community License key (`pk_...`). Unlicensed instances still run and serve reads, but every write returns `503` until a valid key is installed. Can also be set via the browser License Setup Page, which persists it to the database (`server_settings` table) so it survives a rebuild and reaches every instance — see [Runtime settings persistence](#runtime-settings-persistence). Setting it here in the deploy environment takes precedence on the next boot. |
 | `PROMPTOWL_SIGN_IN_GATE` | `open` | Restrict "Sign in with PromptOwl". `open` = anyone may; `admin-only` = only the license owner (admin) may, everyone else uses email/password (admin opens the login page with `?admin=1`); `disabled` = nobody may. Enforced server-side at `POST /auth/promptowl` and surfaced on the health endpoint. Unknown values fall back to `open`. |
+| `MANUAL_SIGN_IN` | `open` | Email + password sign-in mode. `open` = anyone may log in and self-register a new account; `invite-only` = existing/invited users may log in but brand-new self-registration returns `403` (the admin provisions accounts via invite/share/steward and shares the password — there is no self-service "set password", which would be account takeover without email verification); `disabled` = no email/password sign-in at all (`POST /auth/login` and `POST /auth/register` return `403`). Independent of `PROMPTOWL_SIGN_IN_GATE`, so the two methods are controlled separately (e.g. `invite-only` manual + `admin-only` PromptOwl). Also settable from Settings → General. The server refuses `disabled` while PromptOwl sign-in is also `disabled` (that would leave no way to log in). Unknown values fall back to `open`. |
 | `OFFICIAL_COMMUNITY_SSO_SECRET` | `""` | **Official deployment only — leave unset on self-hosted.** Shared HMAC secret enabling the one-click "Open Community" SSO auto-login from PromptOwl. Must exactly match the same-named var on PromptOwl. When unset, `GET /auth/sso` returns `404` and the feature is disabled; self-hosted users keep using the manual device-code flow. |
-| `PUBLIC_BASE_URL` | `""` | This server's canonical external URL (e.g. `https://community.promptowl.ai`). Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another. Only relevant when `OFFICIAL_COMMUNITY_SSO_SECRET` is set; when unset, the audience check is skipped. |
-| `ENV_FILE_PATH` | `$DATA_ROOT/.env` | Path to the `.env` file the license install flow writes `PROMPTOWL_KEY` into (alongside existing vars), and which the server also reads at boot. Defaults **under `DATA_ROOT`** so the browser License Setup Page persists durably in containers — `$cwd` is `/app` in the official image (root-owned, discarded on container recreate), which silently lost the key. Override only if your writable, persisted `.env` lives elsewhere. In containers, providing `PROMPTOWL_KEY` directly via the environment also works and is read at boot. |
+| `PUBLIC_BASE_URL` | `""` | This server's canonical external URL (e.g. `https://community.promptowl.ai`). Two uses. (1) Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another — only when `OFFICIAL_COMMUNITY_SSO_SECRET` is set; when unset, the audience check is skipped. (2) **Set this whenever `OIDC_ENABLED=true`.** It's the base for the OIDC `redirect_uri` sent to your IdP and replayed at token exchange. Unset, that URI is derived from the incoming request's `Host` header — fine when your proxy overwrites `Host` with a trusted value, but a proxy that passes an attacker-supplied `Host` through would feed it straight into the redirect URI. Setting this pins the value regardless of what the proxy forwards. (Your IdP's own redirect-URI allowlist is a second line of defence, not a substitute.) |
+| `OIDC_ENABLED` | `false` | Turn on generic OIDC single sign-on (`GET /auth/oidc/login` / `GET /auth/oidc/callback`). Requires `OIDC_ISSUER`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET` — the login-page button only appears once all three are set. Also editable from Settings → Single sign-on. See [Single sign-on (OIDC)](#single-sign-on-oidc). |
+| `OIDC_ISSUER` | `""` | OIDC issuer URL, e.g. `https://login.microsoftonline.com/<tenant>/v2.0` (Microsoft Entra ID) or `https://accounts.google.com` (Google). **`https://` only** — a non-https value is rejected with a warning and SSO stays off. Must serve `<issuer>/.well-known/openid-configuration`. |
+| `OIDC_CLIENT_ID` | `""` | Application (client) ID from your IdP app registration. |
+| `OIDC_CLIENT_SECRET` | `""` | Client secret from your IdP app registration. Write-only on the Settings API — `GET /admin/settings` reports only `oidc_client_secret_set: true/false`, never the value. |
+| `OIDC_ALLOWED_DOMAINS` | `""` (any) | Comma-separated email-domain allowlist, e.g. `acme.com, contractors.acme.com`. When set, only accounts whose asserted email is on a listed domain may sign in (others bounce with `domain_not_allowed`). Empty allows any domain the IdP asserts. |
+| `OIDC_AUTO_PROVISION` | `true` | Create a user automatically on first successful OIDC sign-in (display name from the `name` claim). Set `false` to allow only pre-existing (invited/registered) users — unknown emails bounce with `not_invited`. |
+| `OIDC_DEPARTMENT_TAGGING` | `false` | Auto-tag newly **created** documents with the creator's directory department: `dept:<slugified-department>` (lowercase, spaces → dashes, e.g. `dept:customer-success`) is appended to the document's tags, deduped against user-supplied tags. Applies on create only — never on update, never retroactively — and a user without a stored department is a silent no-op. The department is captured from the OIDC `department` ID-token claim on every SSO login (a login without the claim clears it, so directory moves propagate), so this is only meaningful when your IdP emits that claim — see [Department auto-tagging](#department-auto-tagging). Also editable from Settings → Single sign-on. |
+| `ENV_FILE_PATH` | `$DATA_ROOT/.env` | Path to an optional `.env` file the server reads at boot (in addition to `$cwd/.env`). **No longer used for persistence** — the License Setup Page and Settings page now write to the database, not this file (see [Runtime settings persistence](#runtime-settings-persistence)). Kept for operators who bootstrap config from a mounted `.env`. |
 | `TELEMETRY_ENABLED` | `"true"` (set to `"false"` to disable) | Batched, anonymized usage events sent to PromptOwl. Off disables the loop entirely. |
 | `TELEMETRY_INTERVAL_MS` | `3600000` (1 hour) | How often buffered telemetry is flushed to PromptOwl. |
+| `TRACE_RETENTION_DAYS` | `14` | Activity-trace retention window in days (the `api_events` rows behind `GET /admin/trace` and `GET /nests/:id/trace`). Rows older than this are pruned opportunistically (every ~500 inserts). `0` = keep forever (pruning is skipped entirely). Capped at `3650`; invalid/negative values fall back to `14`. Also editable from Settings → Advanced. |
 | `CORS_ORIGINS` | `*` in open mode; `http://localhost:5173,http://localhost:3838` in key mode | Comma-separated allowlist. Set to `*` to allow any origin (**only** safe in open mode — in key mode with Bearer tokens this enables CSRF). |
 | `MAX_BODY_BYTES` | `10485760` (10 MB) | Reject requests whose `Content-Length` exceeds this. Prevents giant-payload DoS. |
 | `LOGO_URL` | _(unset)_ | Custom logo shown in the UI header + login screen. Must start with `https://`, `http://`, or `data:image/` — other schemes (`file://`, relative, `javascript:`) are rejected with a warning and the bundled icon is used. |
+| `PROMPTOWL_TEAMS_ENABLED` | _(unset — off)_ | Lets users who signed in with PromptOwl import their PromptOwl teams as local teams. Off by default; set `true` to enable, or toggle from Settings → Advanced. When off, `GET/POST /teams/promptowl` return `404` and the PromptOwl Teams panel is hidden. Independent of `PROMPTOWL_SIGN_IN_GATE`. |
 | `FEATURE_WORKFLOW_PLANE` | _(unset — off)_ | Enables the workflow plane: typed edges, edge-type registry, governed runs. Optional feature; also toggleable from Settings. |
 | `FEATURE_SUBAGENT_RUNS` | _(unset — off)_ | Lets runs spawn nested sub-agent runs (recursion). Gated separately from the plane; requires `FEATURE_WORKFLOW_PLANE`. Also toggleable from Settings → Advanced (turning the plane off forces this off too). Opens a recursion surface — enable only after reviewing the depth/fan-out caps. |
 | `SUBAGENT_MAX_DEPTH` | `8` | Max sub-agent nesting depth (clamped 1..32) — bounds the call tree's HEIGHT so it stays finite/haltable. |
@@ -79,6 +89,119 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 
 ---
 
+## Single sign-on (OIDC)
+
+Generic OpenID Connect sign-in against any spec-compliant identity provider —
+Microsoft Entra ID and Google are the first-class presets in **Settings →
+Single sign-on**. The server runs a standard authorization-code flow with PKCE:
+`GET /auth/oidc/login` redirects to your IdP, `GET /auth/oidc/callback` verifies
+the returned ID token (issuer, audience, nonce, signature against the issuer's
+JWKS) and starts a normal browser session. Users are looked up by email;
+unknown emails are created automatically when `OIDC_AUTO_PROVISION` is on.
+
+All seven `OIDC_*` values are also editable at runtime from **Settings → Single
+sign-on** (superadmin only) — no restart needed. The Settings page shows the
+exact **redirect URI** to register with your IdP:
+
+```
+<PUBLIC_BASE_URL or server origin>/auth/oidc/callback
+```
+
+Set `PUBLIC_BASE_URL` when the server sits behind a reverse proxy so the
+redirect URI is derived from the canonical address rather than the incoming
+Host header.
+
+### Connect Microsoft Entra ID
+
+1. **Register an app.** Entra admin center → *Identity → Applications → App
+   registrations → New registration*. Name it (e.g. "ContextNest"), leave the
+   account type at *Accounts in this organizational directory only*.
+2. **Add the redirect URI.** In the registration: *Authentication → Add a
+   platform → Web*, and paste the redirect URI shown on the ContextNest
+   Settings page (`https://<your-server>/auth/oidc/callback`).
+3. **Create a client secret.** *Certificates & secrets → New client secret*.
+   Copy the secret **value** (not the ID) immediately — it's shown once.
+4. **Collect the IDs.** On the app's *Overview* page copy the **Application
+   (client) ID** and the **Directory (tenant) ID**.
+5. **Fill in ContextNest.** Settings → Single sign-on: click **Microsoft Entra
+   ID**, paste the tenant ID when prompted (issuer becomes
+   `https://login.microsoftonline.com/<tenant>/v2.0`), then paste the client
+   ID and the secret value. Optionally restrict **Allowed email domains** to
+   your org's domain. Save, then flip the toggle **On** and save again (or in
+   the same save).
+6. **Test.** Open the login page in a private window — a **Sign in with
+   Microsoft** button appears and round-trips through Entra. Entra accounts
+   without an `email` claim fall back to `preferred_username` (the UPN).
+
+For **Google**: create an OAuth client ID (type *Web application*) in the
+Google Cloud console, add the same redirect URI under *Authorized redirect
+URIs*, and use the **Google** preset (issuer `https://accounts.google.com`)
+with that client ID/secret.
+
+### Department auto-tagging
+
+With `OIDC_DEPARTMENT_TAGGING` on (Settings → Single sign-on → **Department
+auto-tagging**), every document a user **creates** is tagged
+`dept:<slugified-department>` from their directory department — e.g. a user in
+*Customer Success* creates docs tagged `dept:customer-success`. Create-only:
+edits never add or change the tag, and existing documents are never
+retro-tagged. Users without a department (password accounts, or an IdP that
+doesn't emit the claim) create untagged documents — never an error.
+
+The department is read from the **`department` claim** in the OIDC ID token
+and stored on the user at every SSO login: a new value updates it, an absent
+claim clears it, so directory moves propagate on the user's next sign-in.
+
+Microsoft Entra ID does **not** emit the claim by default — add it to the app
+registration: *Token configuration → Add optional claim → Token type: **ID**
+→ select **department** → Add* (grant the suggested Microsoft Graph
+permission if prompted), and make sure the users' *Department* field is
+populated in Entra. Other IdPs work too as long as they emit a string
+`department` claim in the ID token (e.g. a Keycloak user-attribute mapper).
+
+> **Privacy note:** the `dept:<slug>` tag becomes part of the document's
+> visible metadata — anyone who can read the document (collaborators, shared
+> nests, public nests) can see the creator's directory department. That's
+> PII-adjacent organizational data; consider this before enabling on servers
+> where documents are shared beyond the creator's own team or made public.
+
+### Revoking access (offboarding)
+
+Disabling a user **at the IdP** only blocks *new* sign-ins — an existing
+ContextNest session stays valid until it expires (30 days). To cut access
+immediately, **remove the user in ContextNest** (Settings → users): that wipes
+all of their active sessions at once. Real offboarding is therefore two steps —
+disable at the IdP *and* remove in ContextNest — with the ContextNest step being
+the one that ends live sessions.
+
+When a user signs themselves out, ContextNest performs an **RP-initiated
+logout**: if the IdP advertises an `end_session_endpoint` (Entra, Okta,
+Keycloak do; Google does not), the browser is bounced through it so the IdP
+session ends too and the next "Sign in with SSO" click doesn't silently
+re-authenticate. Where the IdP has no logout endpoint, the local session is
+cleared and the user lands back on the login page (the IdP session persists —
+that's the IdP's own timeout to manage).
+
+### Email-verification trust assumption
+
+An ID token whose `email_verified` claim is **explicitly `false`** is refused
+(`?sso_error=email_not_verified`). When the claim is **absent**, the server
+trusts the email claim — Microsoft Entra ID v2 tokens frequently omit it, and
+both Entra and Google guarantee address ownership, so refusing on absence
+would break the primary providers. This is a deliberate trust assumption:
+**when your IdP allows unverified self-registered emails (e.g. an open
+Keycloak realm), configure `oidc_allowed_domains` and disable self-registration
+at the IdP** — otherwise anyone able to assert an arbitrary email at your IdP
+could sign in as the matching local account.
+
+Sign-in failures bounce back to the app as `/?sso_error=<code>` and surface as
+a toast; codes: `disabled`, `not_configured`, `discovery_failed`,
+`provider_error`, `state_mismatch`, `exchange_failed`, `invalid_token`,
+`email_not_verified`, `domain_not_allowed`, `not_invited`, `rate_limited`,
+`service_error`.
+
+---
+
 ## Database backends
 
 The governance/auth metadata (users, sessions, nests registry, stewards, reviews,
@@ -103,6 +226,31 @@ Postgres backend starts empty.
 > shared storage — e.g. mount a GCS bucket via Cloud Storage FUSE, or use a
 > persistent volume — otherwise documents will disappear on redeploy/scale-in.
 
+### Runtime settings persistence
+
+Settings you change at runtime — everything on the **Settings page** (`/admin/settings`:
+sign-in gate, logo, base URL, upload limit, feature flags, OIDC SSO, Slack/SMTP connectors)
+plus the **installed license key** — are stored in the database (`server_settings`
+table), **not** in a `.env` file. This is deliberate: on Cloud Run the container
+filesystem is ephemeral, so a file-based value was wiped by every rebuild, and each
+horizontally-scaled instance had its own filesystem, so a change on one never
+reached the others. The database (Cloud SQL in production) is durable **and** shared,
+so a UI change persists across rebuilds and is seen by every instance. Rows are
+loaded into the process environment at boot.
+
+**Precedence between the deploy environment and a UI change.** Each stored row
+remembers the deploy-env value in effect when it was written. At boot:
+
+- If the deploy env value for that key is **unchanged**, the stored UI change wins
+  (your Settings-page edit survives an identical rebuild).
+- If the deploy env value **changed** (you redeployed with a new value for that
+  variable), the deploy env wins and the stored row is re-synced to it.
+
+So you can always override any setting from the deploy config, while UI edits made
+to keys you don't set in the environment stay put. Clearing a setting in the UI
+writes a tombstone, so a value you removed is not resurrected from the environment
+on the next boot.
+
 ### Cloud Run + Cloud SQL (PostgreSQL)
 
 Attach the Cloud SQL instance to the service (`--add-cloudsql-instances`) so the

package/README.md

@@ -105,7 +105,8 @@ For redistribution, hosted-service, OEM, or regulated-industry licensing, contac
 | Steward version revert | ✅ | ✅ |
 | MCP server for AI agents | ✅ | ✅ |
 | Centralized multi-tenant admin console | — | ✅ |
-| SSO / SAML / SCIM | — | ✅ |
+| Single sign-on (OIDC — Entra ID, Google, Okta, Keycloak) | ✅ | ✅ |
+| SAML / SCIM provisioning | — | ✅ |
 | Audit log streaming | — | ✅ |
 | Policy transforms (redaction, summarization) | — | ✅ |
 | Priority support and SLA | — | ✅ |

package/dist/{chunk-DPHV6Q26.js → chunk-3M7677XW.js}

@@ -28,8 +28,9 @@ var canonicalEnvLoaded = null;
 var slackUrlWarned = false;
 var emailFromWarned = false;
 var emailToWarned = false;
+var oidcIssuerWarned = false;
 function isEmailish(v) {
-  return /^[^\s@]+@[^\s@]+$/.test(v) && !/[\r\n]/.test(v);
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) && !/[\r\n]/.test(v);
 }
 function isEmailListish(v) {
   return v.split(",").every((e) => isEmailish(e.trim()));
@@ -124,6 +125,28 @@ var config = {
   get PROMPTOWL_KEY() {
     return process.env.PROMPTOWL_KEY || "";
   },
+  /**
+   * Whether importing/syncing teams FROM PromptOwl is offered. Default OFF
+   * (only an explicit "true" enables) — an operator opts the PO-team surface
+   * in from Settings or env. When off, the /teams/promptowl routes 404 and the
+   * UI hides the panel. Independent of PROMPTOWL_SIGN_IN_GATE: a user may sign
+   * in with PromptOwl yet not be allowed to pull their PO teams in.
+   */
+  get PROMPTOWL_TEAMS_ENABLED() {
+    return process.env.PROMPTOWL_TEAMS_ENABLED === "true";
+  },
+  /** Vercel automation-bypass secret for PO calls; unset = no bypass. */
+  get PROMPTOWL_BYPASS_SECRET() {
+    return process.env.PROMPTOWL_BYPASS_SECRET || "";
+  },
+  /** Outbound headers for PO fetches; bypass header only when secret set. */
+  get PROMPTOWL_FETCH_HEADERS() {
+    const h = { "Content-Type": "application/json" };
+    if (this.PROMPTOWL_BYPASS_SECRET) {
+      h["x-vercel-protection-bypass"] = this.PROMPTOWL_BYPASS_SECRET;
+    }
+    return h;
+  },
   /**
    * Shared secret for one-click SSO auto-login from PromptOwl (PO).
    *
@@ -164,6 +187,98 @@ var config = {
     const v = (process.env.PROMPTOWL_SIGN_IN_GATE || "open").trim().toLowerCase();
     return v === "admin-only" || v === "disabled" ? v : "open";
   },
+  /**
+   * Manual (email + password) sign-in. Three modes, independent of
+   * `PROMPTOWL_SIGN_IN_GATE` (the two methods are controlled separately):
+   *   "open"        — anyone may log in and self-register (default).
+   *   "invite-only" — existing + admin-invited users may log in and an invited
+   *                   placeholder may set its password ("claim"), but brand-new
+   *                   self-registration is refused. Use this when the admin
+   *                   provisions accounts (invite / share / steward) and users
+   *                   shouldn't be able to create their own.
+   *   "disabled"    — no email/password sign-in at all (PromptOwl only).
+   * Enforced at POST /auth/login and POST /auth/register. The /admin/settings
+   * validator refuses "disabled" while PromptOwl is also disabled, so a server
+   * can never be left with no way to sign in.
+   */
+  get MANUAL_SIGN_IN() {
+    const v = (process.env.MANUAL_SIGN_IN || "open").trim().toLowerCase();
+    return v === "invite-only" || v === "disabled" ? v : "open";
+  },
+  /**
+   * Generic OIDC single sign-on (Microsoft Entra ID, Google, any spec-
+   * compliant IdP). Off by default; superadmin-configurable at runtime via
+   * /admin/settings. When enabled AND fully configured (issuer + client id +
+   * client secret), GET /auth/oidc/login starts an authorization-code + PKCE
+   * flow and GET /auth/oidc/callback finishes it with a normal browser
+   * session — exactly like a password login.
+   */
+  get OIDC_ENABLED() {
+    return process.env.OIDC_ENABLED === "true";
+  },
+  /**
+   * OIDC issuer URL, e.g. "https://login.microsoftonline.com/<tenant>/v2.0"
+   * or "https://accounts.google.com". https only — tokens and the client
+   * secret ride this trust root, so a plaintext issuer is refused (warn once,
+   * treated as unset). Trailing slash stripped so discovery-doc comparison is
+   * canonical.
+   */
+  get OIDC_ISSUER() {
+    const raw = (process.env.OIDC_ISSUER || "").trim().replace(/\/$/, "");
+    if (!raw) return "";
+    let ok = false;
+    try {
+      ok = new URL(raw).protocol === "https:";
+    } catch {
+      ok = false;
+    }
+    if (!ok) {
+      if (!oidcIssuerWarned) {
+        oidcIssuerWarned = true;
+        console.warn(
+          "[config] OIDC_ISSUER rejected: must be a valid https:// URL. OIDC sign-in disabled."
+        );
+      }
+      return "";
+    }
+    return raw;
+  },
+  get OIDC_CLIENT_ID() {
+    return (process.env.OIDC_CLIENT_ID || "").trim();
+  },
+  get OIDC_CLIENT_SECRET() {
+    return (process.env.OIDC_CLIENT_SECRET || "").trim();
+  },
+  /**
+   * Comma-separated email-domain allowlist for OIDC sign-in (e.g.
+   * "acme.com, contractors.acme.com"). Empty = any domain the IdP asserts.
+   * Entries are normalized to lowercase; matching is on the part after the
+   * final "@" of the asserted email.
+   */
+  get OIDC_ALLOWED_DOMAINS() {
+    return (process.env.OIDC_ALLOWED_DOMAINS || "").split(",").map((d) => d.trim().toLowerCase()).filter(Boolean);
+  },
+  /**
+   * Auto-provision (JIT-create) an unknown user on first successful OIDC
+   * sign-in. Default true. When false, only emails that already have a user
+   * row (invited / registered) may sign in via OIDC — everyone else bounces
+   * with ?sso_error=not_invited.
+   */
+  get OIDC_AUTO_PROVISION() {
+    return process.env.OIDC_AUTO_PROVISION !== "false";
+  },
+  /**
+   * Auto-tag content created by SSO users with their directory department:
+   * when on, node CREATE appends `dept:<slugified-department>` to the new
+   * node's tags (never on update, never retroactively). The department is
+   * captured from the OIDC `department` claim at login (see oidc.ts), so
+   * this is only meaningful alongside an IdP that emits that claim — but
+   * there is no hard dependency on OIDC_ENABLED. Default off; superadmin-
+   * togglable at runtime via /admin/settings.
+   */
+  get OIDC_DEPARTMENT_TAGGING() {
+    return process.env.OIDC_DEPARTMENT_TAGGING === "true";
+  },
   /**
    * Path to the .env file the server reads its config from and the license
    * install flow persists PROMPTOWL_KEY into. Defaults UNDER DATA_ROOT (not
@@ -181,6 +296,18 @@ var config = {
   get TELEMETRY_INTERVAL_MS() {
     return parseInt(process.env.TELEMETRY_INTERVAL_MS || "3600000", 10);
   },
+  /**
+   * Activity-trace retention window in days (the api_events table behind
+   * GET /admin/trace and GET /nests/:id/trace). 0 = keep forever (pruning is
+   * skipped entirely). Invalid / negative → default 14; capped at 3650 (ten
+   * years) so a typo can't schedule a prune cutoff in the distant past.
+   * Editable at runtime from the admin Settings page (/admin/settings).
+   */
+  get TRACE_RETENTION_DAYS() {
+    const n = parseInt(process.env.TRACE_RETENTION_DAYS || "14", 10);
+    if (!Number.isFinite(n) || n < 0) return 14;
+    return Math.min(n, 3650);
+  },
   /**
    * Optional custom logo URL shown in UI header + login screen.
    * Must be an absolute https://, http://, or data:image/… URL. Other
@@ -206,9 +333,44 @@ var config = {
    * This flag is also the future license-tier hook: gating a paid tier here
    * is a one-line change because every plane route checks it per request.
    */
+  /**
+   * Optional Slack incoming-webhook URL for team notifications (review
+   * submitted/approved/rejected). Empty/unset = connector off. https only —
+   * a webhook carries an implicit secret in its path, so it never travels
+   * plaintext. (Ported from development PR #105.)
+   */
+  get SLACK_WEBHOOK_URL() {
+    const raw = process.env.SLACK_WEBHOOK_URL?.trim();
+    if (!raw) return null;
+    if (!/^https:\/\//i.test(raw)) {
+      if (!slackUrlWarned) {
+        slackUrlWarned = true;
+        console.warn(
+          "[config] SLACK_WEBHOOK_URL rejected: must be an https:// URL. Slack notifications disabled."
+        );
+      }
+      return null;
+    }
+    return raw;
+  },
   get FEATURE_WORKFLOW_PLANE() {
     return process.env.FEATURE_WORKFLOW_PLANE === "true";
   },
+  /**
+   * Content-type toggles — soft-disable a node type server-wide. DEFAULT ON:
+   * missing/unset/anything-but-"false" = enabled, so existing deployments see
+   * zero behavior change. Only CREATION of the type is refused when disabled;
+   * existing nodes of that type still read/render/version (never data loss).
+   * Runnable types (agent/skill/tool) are NOT governed here — they stay gated
+   * by FEATURE_WORKFLOW_PLANE. Superadmin-editable at runtime via
+   * /admin/settings (type_artifact_enabled / type_table_enabled).
+   */
+  get TYPE_ARTIFACT_ENABLED() {
+    return process.env.TYPE_ARTIFACT_ENABLED !== "false";
+  },
+  get TYPE_TABLE_ENABLED() {
+    return process.env.TYPE_TABLE_ENABLED !== "false";
+  },
   /**
    * Sub-agent runs: lets a run spawn nested runs (an external runner calling
    * back into POST /run for a child agent). Gated SEPARATELY from the base
@@ -238,6 +400,13 @@ var config = {
     const n = parseInt(process.env.RUN_MAX_STEPS || "10000", 10);
     return Number.isFinite(n) ? Math.min(1e5, Math.max(10, n)) : 1e4;
   },
+  /** Max concurrently-RUNNING root (depth-0) runs per nest. The subagent
+   *  depth/fan-out caps bound a single tree; this bounds how many trees a
+   *  caller can start at once, so root triggers can't flood the nest. */
+  get RUN_MAX_CONCURRENT_ROOTS() {
+    const n = parseInt(process.env.RUN_MAX_CONCURRENT_ROOTS || "50", 10);
+    return Number.isFinite(n) ? Math.min(1e3, Math.max(1, n)) : 50;
+  },
   get AUTH_MODE() {
     return process.env.AUTH_MODE || "key";
   },
@@ -295,26 +464,6 @@ var config = {
     }
     return raw;
   },
-  /**
-   * Optional Slack incoming-webhook URL for team notifications (review
-   * submitted/approved/rejected, nest shared). Empty/unset = connector off.
-   * https only — a webhook carries an implicit secret in its path, so it
-   * never travels plaintext.
-   */
-  get SLACK_WEBHOOK_URL() {
-    const raw = process.env.SLACK_WEBHOOK_URL?.trim();
-    if (!raw) return null;
-    if (!/^https:\/\//i.test(raw)) {
-      if (!slackUrlWarned) {
-        slackUrlWarned = true;
-        console.warn(
-          "[config] SLACK_WEBHOOK_URL rejected: must be an https:// URL. Slack notifications disabled."
-        );
-      }
-      return null;
-    }
-    return raw;
-  },
   /**
    * Per-nest notification digest window in milliseconds. A burst of governance
    * events on one nest inside this window collapses into a single digest
@@ -1078,6 +1227,198 @@ function runMigrations(db) {
     })();
     recordMigration("018_subagent_runs");
   }
+  if (!hasMigration("020_server_settings")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS server_settings (
+          key TEXT PRIMARY KEY,
+          value TEXT,
+          env_at_write TEXT,
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+      `);
+      recordMigration("020_server_settings");
+    })();
+  }
+  if (!hasMigration("020_schedules")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS schedules (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          agent_node TEXT NOT NULL,
+          every_minutes INTEGER NOT NULL CHECK(every_minutes >= 5),
+          enabled INTEGER NOT NULL DEFAULT 1,
+          last_run_at TEXT,
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_schedules_agent
+          ON schedules(nest_id, agent_node);
+      `);
+    })();
+    recordMigration("020_schedules");
+  }
+  if (!hasMigration("021_schedule_bounds")) {
+    db.transaction(() => {
+      db.exec(`
+        ALTER TABLE schedules ADD COLUMN max_runs INTEGER;
+        ALTER TABLE schedules ADD COLUMN runs_created INTEGER NOT NULL DEFAULT 0;
+      `);
+    })();
+    recordMigration("021_schedule_bounds");
+  }
+  if (!hasMigration("022_tools_and_watchers")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS nest_env (
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          updated_by TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          PRIMARY KEY (nest_id, key)
+        );
+        CREATE TABLE IF NOT EXISTS watchers (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          node_id TEXT NOT NULL,
+          user_email TEXT NOT NULL,
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_watchers_unique
+          ON watchers(nest_id, node_id, user_email);
+        CREATE TABLE IF NOT EXISTS notifications (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          user_email TEXT NOT NULL,
+          kind TEXT NOT NULL,
+          subject_id TEXT,
+          message TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          read_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_notifications_user
+          ON notifications(user_email, read_at, created_at);
+      `);
+    })();
+    recordMigration("022_tools_and_watchers");
+  }
+  if (!hasMigration("023_connectors")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS connectors (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          channel TEXT NOT NULL CHECK(channel IN ('slack', 'teams', 'webhook')),
+          url TEXT NOT NULL,               -- https://\u2026 or env:KEY
+          events TEXT NOT NULL,            -- JSON array of kinds, or ["*"]
+          enabled INTEGER NOT NULL DEFAULT 1,
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_connectors_nest ON connectors(nest_id);
+      `);
+    })();
+    recordMigration("023_connectors");
+  }
+  if (!hasMigration("024_trigger_hooks")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS trigger_hooks (
+          id TEXT PRIMARY KEY,               -- the token (hk_\u2026), capability auth
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          agent_node TEXT NOT NULL,
+          preset TEXT NOT NULL CHECK(preset IN ('slack', 'teams', 'webhook')),
+          enabled INTEGER NOT NULL DEFAULT 1,
+          fire_count INTEGER NOT NULL DEFAULT 0,
+          last_fired_at TEXT,
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_hooks_nest ON trigger_hooks(nest_id);
+      `);
+    })();
+    recordMigration("024_trigger_hooks");
+  }
+  if (!hasMigration("025_run_claims")) {
+    db.transaction(() => {
+      db.exec(`
+        ALTER TABLE runs ADD COLUMN claimed_by TEXT;
+        ALTER TABLE runs ADD COLUMN claimed_at TEXT;
+      `);
+    })();
+    recordMigration("025_run_claims");
+  }
+  if (!hasMigration("026_api_events_nest_index")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_api_events_nest_ts ON api_events(nest_id, id);
+      `);
+    })();
+    recordMigration("026_api_events_nest_index");
+  }
+  if (!hasMigration("027_teams")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS teams (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+          members TEXT NOT NULL DEFAULT '[]',   -- JSON [{userId, email, role}]
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_teams_owner ON teams(owner_id);
+      `);
+      const nestColsNow = db.prepare("PRAGMA table_info(nests)").all().map((c) => c.name);
+      if (!nestColsNow.includes("shared_teams")) {
+        db.exec("ALTER TABLE nests ADD COLUMN shared_teams TEXT NOT NULL DEFAULT '[]'");
+      }
+    })();
+    recordMigration("027_teams");
+  }
+  if (!hasMigration("028_user_department")) {
+    db.transaction(() => {
+      const userColsNow = db.prepare("PRAGMA table_info(users)").all().map((c) => c.name);
+      if (!userColsNow.includes("department")) {
+        db.exec("ALTER TABLE users ADD COLUMN department TEXT");
+      }
+    })();
+    recordMigration("028_user_department");
+  }
+  if (!hasMigration("029_super_admins")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS super_admins (
+          email TEXT PRIMARY KEY,          -- stored lowercased
+          granted_by TEXT NOT NULL,        -- email of the granting admin
+          granted_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+      `);
+    })();
+    recordMigration("029_super_admins");
+  }
+  if (!hasMigration("031_team_source")) {
+    db.transaction(() => {
+      const teamCols = db.prepare("PRAGMA table_info(teams)").all().map((c) => c.name);
+      if (!teamCols.includes("source")) {
+        db.exec("ALTER TABLE teams ADD COLUMN source TEXT");
+      }
+      if (!teamCols.includes("external_id")) {
+        db.exec("ALTER TABLE teams ADD COLUMN external_id TEXT");
+      }
+      db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_teams_external
+          ON teams(owner_id, source, external_id)
+          WHERE external_id IS NOT NULL;
+      `);
+    })();
+    recordMigration("031_team_source");
+  }
 }
 function mergeCaseCollidingUsers(db) {
   const groups = db.prepare(
@@ -1295,7 +1636,7 @@ async function initDb() {
   if (config.DB_DRIVER === "postgres") {
     const { Pool } = await import("pg");
     const { PostgresAdapter } = await import("./adapter.postgres-YOODX2BI.js");
-    const { runPostgresMigrations } = await import("./migrations.postgres-ORSV7UFJ.js");
+    const { runPostgresMigrations } = await import("./migrations.postgres-BRXZY2GE.js");
     const pool = new Pool(buildPgConfig());
     adapter = new PostgresAdapter(pool);
     await runPostgresMigrations(adapter);