@sanctuary-framework/mcp-server 1.1.7 → 1.2.1

package/dist/index.d.ts

@@ -1248,6 +1248,18 @@ declare class PolicyStore {
     private persist;
 }
 
+/**
+ * Signature scheme identifier embedded in every AuditEntry and crypto-agility-bearing surface.
+ *
+ * v1.0: only "ed25519-v1" is valid.
+ * v1.x post-quantum migration: "ed25519+ml-dsa-v1" hybrid will be introduced.
+ * v1.0 verifiers MUST reject unknown schemes; the field exists so v1.x can add
+ * hybrid signing without breaking v1.0 readers. Do not optimize this field away.
+ *
+ * Spec: §5.3 (Crypto-agility per thesis §3 L1 PQ note).
+ */
+type SignatureScheme$1 = "ed25519-v1";
+
 /**
  * Sanctuary MCP Server — Sovereignty Health Report (SHR) Types
  *
@@ -1258,6 +1270,7 @@ declare class PolicyStore {
  *
  * SHR version: 1.0
  */
+
 type LayerStatus = "active" | "degraded" | "inactive";
 type DegradationSeverity = "info" | "warning" | "critical";
 type DegradationCode = "NO_TEE" | "PROCESS_ISOLATION_ONLY" | "COMMITMENT_ONLY" | "NO_ZK_PROOFS" | "SELF_REPORTED_ATTESTATION" | "NO_SELECTIVE_DISCLOSURE" | "BASIC_SYBIL_ONLY" | "NO_REPUTATION_HISTORY" | "LOW_TIER_DOMINANCE" | "STALE_REPUTATION" | "DISPUTE_ON_RECORD" | "NO_VERASCORE_LINK";
@@ -1337,6 +1350,7 @@ interface SHRBody {
 interface SignedSHR {
     body: SHRBody;
     signed_by: string;
+    signature_scheme: SignatureScheme$1;
     signature: string;
 }
 interface SHRVerificationResult {
@@ -2925,13 +2939,13 @@ interface PrivacyRehydratedPayload extends PrivacyAuditPayloadHeader {
 type PrivacyAuditPayload = PrivacyFilteredPayload | PrivacyAllowedPayload | PrivacyDeniedPayload | PrivacyErrorPayload | PrivacyRehydratedPayload;
 
 /**
- * Sanctuary v1.1 — Operator Hub Event Contracts
+ * Sanctuary v1.1 Operator Hub Event Contracts
  *
  * Shared shapes for the unified inbox, the activity feed, and the per-agent
  * status panels. The operator hub API workstream (Prompt 5) emits these; the
  * dashboard UI workstream (Prompt 8) consumes them. v1.2 mobile companion
  * planning will evaluate these shapes when it scopes a phone surface, but
- * v1.1 does not commit to mobile compatibility — these contracts are
+ * v1.1 does not commit to mobile compatibility. These contracts are
  * tuned for the local dashboard surface only.
  *
  * Local-only invariant:
@@ -2952,7 +2966,7 @@ type PrivacyAuditPayload = PrivacyFilteredPayload | PrivacyAllowedPayload | Priv
  * accepted; the dashboard rejects rendering on any value outside this union.
  *
  * The renderer treats every value as data to interpolate into a fixed
- * template registered under `template_id` — never as raw content. This
+ * template registered under `template_id`, never as raw content. This
  * defends against secrets, query text, file paths, and client names leaking
  * into inbox cards via stringly-typed display fields.
  */
@@ -2965,6 +2979,9 @@ type HubDisplayTemplateArg = {
 } | {
     kind: "policy_id";
     value: string;
+} | {
+    kind: "channel_template_id";
+    value: string;
 } | {
     kind: "destination_category";
     value: PrivacyDestinationCategory;
@@ -3012,7 +3029,7 @@ interface HubInboxItemHeader {
     display_template_id: string;
     /**
      * Typed args interpolated into the template. Every value MUST be a
-     * `HubDisplayTemplateArg` instance — no free-form strings. Renderers
+     * `HubDisplayTemplateArg` instance, no free-form strings. Renderers
      * reject any arg outside this union, which structurally blocks secret
      * leakage via inbox copy.
      */
@@ -3097,7 +3114,7 @@ interface HubBudgetWarningItem extends HubInboxItemHeader {
     used_fraction: number;
 }
 /**
- * Recovery prompt — operator should run a recovery flow (passphrase reset,
+ * Recovery prompt. Operator should run a recovery flow (passphrase reset,
  * keychain rebind, exit drill, etc.).
  */
 interface HubRecoveryPromptItem extends HubInboxItemHeader {
@@ -3143,12 +3160,32 @@ interface HubActivityFeedEntry {
     category: "policy_decision" | "approval" | "denial" | "egress" | "privacy" | "handoff" | "lifecycle" | "config" | "other";
     /**
      * Display template id. Resolved by the dashboard against the activity-feed
-     * template catalog. Backends MUST NOT emit raw summary text — the template
+     * template catalog. Backends MUST NOT emit raw summary text. The template
      * id plus typed args is the only legitimate channel.
      */
     display_template_id: string;
     /** Typed args. Same constraints as `HubInboxItemHeader.display_template_args`. */
     display_template_args: HubDisplayTemplateArg[];
+    /**
+     * Per-action attestation fragment for dashboard timeline rendering.
+     *
+     * Optional; absence means the row renders without a badge.
+     *
+     * `state` drives the `att-action` CSS class on the rendered badge.
+     * `fragment` is a deterministic short hex string derived from the
+     * audit-chain entry id; it gives operators a stable per-row visual hook
+     * the same shape the Sprint Piece 2 attestation gallery shows.
+     *
+     * Important: the fragment is NOT a real per-event Ed25519 signature.
+     * The audit chain itself is tamper-evident at the main-process boundary
+     * (scope-lock §8); the fragment is the visible projection of the entry's
+     * audit-chain identity. Real per-event signatures land post-v1.5+ in the
+     * Crypto Agility Sprint.
+     */
+    attestation?: {
+        state: "verified" | "degraded" | "unverified" | "neutral";
+        fragment: string;
+    };
 }
 /**
  * Per-agent status snapshot returned by the hub API. Mirrors the agent
@@ -3758,6 +3795,27 @@ declare class MemoryStorage implements StorageBackend {
  * - Secure deletion overwrites file content with random bytes before unlinking
  * - Directory creation uses restrictive permissions (0o700)
  * - File creation uses restrictive permissions (0o600)
+ *
+ * Path encoding (bijective, full-sweep #41):
+ *   Distinct (namespace, key) inputs MUST produce distinct on-disk paths;
+ *   otherwise an agent that can choose namespace/key strings within a tenant
+ *   could overwrite or read another namespace by colliding on the sanitized
+ *   form (multi-tenant isolation invariant). The encoder retains the safe
+ *   set [A-Za-z0-9_.-] (so internal namespaces such as `_audit`, `_bridge`,
+ *   etc. preserve their on-disk paths verbatim) and `!`-escapes every other
+ *   character as `!XX` where XX is the upper-hex byte. The escape character
+ *   `!` itself is NOT in the safe set, so a literal `!` in input encodes as
+ *   `!21` and decoding remains unambiguous.
+ *
+ * Legacy fallback (forward compatibility):
+ *   Pre-fix code used `replace(/[^a-zA-Z0-9_-]/g, "_")` for namespaces and
+ *   `replace(/[^a-zA-Z0-9_.-]/g, "_")` for keys; non-bijective. read(),
+ *   exists(), and delete() try the new path first; on ENOENT they fall back
+ *   to the legacy path so existing fortresses with operator-supplied
+ *   namespaces containing non-safe characters keep working. write() always
+ *   uses the new bijective path. list() and totalSize() walk on-disk
+ *   directory names directly and cannot disambiguate legacy collision-class
+ *   pairs; they are forward-only by design.
  */
 
 declare class FilesystemStorage implements StorageBackend {
@@ -3765,9 +3823,12 @@ declare class FilesystemStorage implements StorageBackend {
     constructor(basePath: string);
     private entryPath;
     private namespacePath;
+    private legacyEntryPath;
     write(namespace: string, key: string, data: Uint8Array): Promise<void>;
     read(namespace: string, key: string): Promise<Uint8Array | null>;
+    private readAtPath;
     delete(namespace: string, key: string, secureOverwrite?: boolean): Promise<boolean>;
+    private deleteAtPath;
     list(namespace: string, prefix?: string): Promise<StorageEntryMeta[]>;
     exists(namespace: string, key: string): Promise<boolean>;
     totalSize(): Promise<number>;
@@ -3921,6 +3982,31 @@ interface ImportExitBundleOptions {
     sourceRecoveryKey?: string;
     sourceMasterKey?: Uint8Array;
     destinationSignerIdentityId?: string;
+    /**
+     * v1.0.2 (i) / full-sweep #54. When the destination fortress already has a
+     * staged `public_identity` for the bundle's identity_id, activation is refused
+     * unless the operator passes this flag. The CLI surfaces the flag as
+     * `--force-rebind` and re-prompts Tier 1 confirmation. When `forceRebind` is
+     * true and the rebind triggers, an `exit_bundle_force_rebind` L1 audit entry
+     * records the explicit replacement.
+     */
+    forceRebind?: boolean;
+    /**
+     * v1.0.2 / full-sweep #55. Reputation attestations whose signer DID is not
+     * present in the bundle's published identity material are marked
+     * `unverifiable` by the verifier. By default the verdict is now strict and
+     * an unverifiable attestation fails the bundle. Setting this flag opts the
+     * operator in to an explicit relaxed verdict (Tier 1 confirmation in CLI).
+     */
+    acceptUnverifiableAttestations?: boolean;
+}
+/**
+ * Structured error raised by `importExitBundle` for codes the CLI / hub want
+ * to branch on without parsing free-text messages. v1.0.2 (i) / full-sweep #54.
+ */
+declare class ExitBundleImportError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
 }
 interface ExitBundleConflictReport {
     public_identity_exists: boolean;
@@ -3957,14 +4043,6 @@ declare function exportExitBundle(opts: ExportExitBundleOptions): Promise<Export
 declare function importExitBundle(opts: ImportExitBundleOptions): Promise<ImportExitBundleResult>;
 declare function exitBundleManifestShape(): Record<string, unknown>;
 
-/**
- * Sanctuary v1.1 exit-bundle verifier.
- *
- * Verifies the signed SANCTUARY_EXIT_BUNDLE_V1 manifest, every artifact hash,
- * and the exported identity / reputation signatures that are independently
- * verifiable from public material in the bundle.
- */
-
 interface ExitBundleDetailedVerifierResult extends ExitBundleVerifierResult {
     manifest_path: string;
     manifest_hash: string | null;
@@ -3995,7 +4073,19 @@ interface LoadedExitArtifact<T = unknown> {
 }
 declare function readManifest(bundleDir: string): Promise<ExitBundleManifest>;
 declare function loadExitArtifact<T = unknown>(bundleDir: string, manifest: ExitBundleManifest, kind: ExitBundleArtifactKind): Promise<LoadedExitArtifact<T> | null>;
-declare function verifyExitBundle(bundleDir: string): Promise<ExitBundleDetailedVerifierResult>;
+/**
+ * Caller-supplied verifier knobs. v1.0.2 / full-sweep #55.
+ *
+ * `acceptUnverifiableAttestations` flips the bundle verdict from strict-by-default
+ * (any unverifiable attestation fails the bundle) to a relaxed verdict that
+ * tolerates attestations whose signer DID is not in the bundle's published
+ * identity material. Operators opt in explicitly through the CLI
+ * `--accept-unverifiable-attestations` flag (Tier 1 confirmation).
+ */
+interface VerifyExitBundleOptions {
+    acceptUnverifiableAttestations?: boolean;
+}
+declare function verifyExitBundle(bundleDir: string, options?: VerifyExitBundleOptions): Promise<ExitBundleDetailedVerifierResult>;
 
 /**
  * `sanctuary exit` CLI.
@@ -4130,10 +4220,981 @@ type HubInboxAction = (typeof HUB_INBOX_ACTIONS)[number];
 declare const HUB_AGENT_CONTROL_ACTIONS: readonly ["pause", "resume", "restart", "unwrap", "lockdown"];
 type HubAgentControlAction = (typeof HUB_AGENT_CONTROL_ACTIONS)[number];
 
-/** Channel-template identifiers per Walkthrough Key 10 LOCKED starter set. */
-declare const CHANNEL_TEMPLATE_IDS: readonly ["read-outputs-only", "bidirectional-sync", "credential-share-scoped", "plan-inspect-read-only", "escrow-handoff"];
+/** Channel-template identifiers per the five-template canonical starter set. */
+declare const CHANNEL_TEMPLATE_IDS: readonly ["request-approve-act", "read-then-report", "scheduled-digest", "plan-draft-only", "fortress-relay"];
 type ChannelTemplateId = (typeof CHANNEL_TEMPLATE_IDS)[number];
 
+/**
+ * Sanctuary MCP Server — Intelligence Substrate Selector Types
+ *
+ * The substrate selector lets operators pick (and re-pick) the LLM substrate
+ * that powers Sanctuary's intelligence-layer surfaces: concierge, sentinel
+ * scoring, gate explanation, privacy filter Tier 2, template suggestion,
+ * direct-agent gate advisory.
+ *
+ * Per Erik directive 2026-04-29: the selector IS the architecture. Sanctuary's
+ * job is to make the tradeoffs visible and let the operator choose. Multi-option
+ * framing is preserved; no single substrate is surfaced as a winner.
+ *
+ * Per the position paper Intelligence_Layer_Drift_Audit_and_Substrate_Resolution_2026-04-29.md
+ * (sections 4 + 5), four substrates ship as operator-pickable:
+ *
+ *   - local:                  Ollama-hosted local model (Gemma 2 2B / Phi-4 Mini / Llama 3.1 8B)
+ *   - venice:                 Venice.ai privacy-respecting hosted relay
+ *   - frontier-with-filter:   operator's frontier API account, Privacy Filter Tier 2 pre-egress
+ *   - hybrid:                 per-surface routing across the above
+ *   - disabled:               surface refuses LLM calls; Tier 1 regex fallback for privacy filter
+ *
+ * Per-surface defaults (Erik ratification 2026-04-29):
+ *   - concierge:                       local (Gemma 2 2B)
+ *   - sentinel-scoring:                local (rules + Phi-4 Mini on escalation)
+ *   - gate-explanation:                templates v1.2; small LLM v1.3+ for custom policies
+ *   - privacy-filter-tier-2:           local (NER + small LLM PII classifier)
+ *   - direct-agent-gate-advisor:       same as concierge by default
+ *   - template-suggestion:             same as concierge by default
+ */
+/**
+ * The set of intelligence-layer surfaces the selector routes for.
+ *
+ * The enum is closed. Adding a surface requires updating the selector's
+ * default-config builder, the audit emission shape registry, and the
+ * transparency UI in the same PR.
+ */
+type Surface = "concierge" | "direct-agent-gate-advisor" | "sentinel-scoring" | "gate-explanation" | "privacy-filter-tier-2" | "template-suggestion";
+/**
+ * The substrate choice an operator may bind to a surface.
+ */
+type SubstrateChoice = "local" | "venice" | "frontier-with-filter" | "hybrid" | "disabled";
+/**
+ * Local-model picks for the Ollama-backed local substrate.
+ *
+ * Bundled tiers per position paper §5 hardware-tier table:
+ *   - gemma-2-2b   (Baseline / 8GB RAM)
+ *   - phi-4-mini   (Mid / 16GB RAM)
+ *   - llama-3.1-8b (Pro / 32GB+ RAM)
+ *
+ * Custom Ollama-installed models can be specified via `customModelTag` on the
+ * substrate config; the selector probes Ollama for availability at runtime.
+ */
+type LocalModelPick = "gemma-2-2b" | "phi-4-mini" | "llama-3.1-8b";
+/**
+ * Frontier providers operator may pick for the frontier-with-filter substrate.
+ * v1.2 ships three; v1.3+ may add Mistral / xAI / Cohere.
+ */
+type FrontierProvider = "anthropic" | "openai" | "google";
+/**
+ * What the selector does when its chosen substrate fails (e.g. Ollama not
+ * running, Venice API unreachable, frontier API key revoked).
+ *
+ * Per surface, operator-configurable. Defaults per position paper §5:
+ *   - concierge:               degrade-silent (next-tier substrate)
+ *   - sentinel-scoring:        conservative-deny (refuse rather than route elsewhere)
+ *   - privacy-filter-tier-2:   degrade-silent (Tier 1 regex always works)
+ *   - others:                  conservative-deny
+ */
+type FallbackBehavior = "conservative-deny" | "degrade-silent" | "disable-surface";
+/**
+ * Per-surface routing rules for the hybrid substrate.
+ *
+ * v1.2 ships per-surface routing only — operator pre-binds each surface to a
+ * concrete substrate. Per-query sensitivity classification routing is deferred
+ * to v1.3+.
+ */
+interface HybridRoutingRules {
+    perSurface: Record<Surface, Exclude<SubstrateChoice, "hybrid">>;
+}
+/**
+ * Operator-readable status badge for the transparency UI and chat headers.
+ *
+ * Backends emit a stable shape (no free-form prose); the dashboard's template
+ * registry renders it. This mirrors the v1.1 hub `HubDisplayTemplateArg`
+ * discipline so secret-leakage into operator-facing copy stays structurally
+ * impossible.
+ */
+interface SubstrateBadge {
+    surface: Surface;
+    substrate: SubstrateChoice;
+    /** Stable badge label key resolved by dashboard template registry. */
+    labelKey: string;
+    /** Stable tradeoff body key resolved by dashboard template registry. */
+    tradeoffKey: string;
+    /** Stable status; green = working; yellow = degraded; red = disabled / failing. */
+    status: "green" | "yellow" | "red";
+}
+/**
+ * Frontier provider configs. Operator's API key per provider is stored
+ * encrypted; never leaves the fortress except as outbound HTTPS to the
+ * provider after Privacy Filter Tier 2 redaction.
+ */
+interface FrontierProviderConfig {
+    /** Operator's per-provider API key (encrypted at rest). */
+    anthropic?: string;
+    openai?: string;
+    google?: string;
+}
+/**
+ * Operator-overridable substrate config. Persisted encrypted under the
+ * fortress master key in storage namespace `_intelligence`.
+ *
+ * v1.0 of this shape (`version: 1`) is the only shape this PR ships. Future
+ * v1.x extensions (per-query sensitivity classifier, MLX runtime pick,
+ * per-patron substrate scoping) MUST bump this version and provide a
+ * forward-compat migration in the selector.
+ */
+interface SubstrateConfig {
+    version: 1;
+    /** Operator's per-surface choice. Defaults from position paper §5. */
+    perSurface: Record<Surface, SubstrateChoice>;
+    /** Operator's local-model picks per surface, when 'local' is chosen. */
+    localModelPicks: Partial<Record<Surface, LocalModelPick>>;
+    /** Custom Ollama model tag override per surface (overrides localModelPicks if set). */
+    customLocalModelTags?: Partial<Record<Surface, string>>;
+    /** Ollama HTTP endpoint; defaults to http://localhost:11434. */
+    ollamaEndpoint?: string;
+    /** Venice API key, if 'venice' chosen for any surface. Encrypted at rest. */
+    veniceApiKey?: string;
+    /** Venice model selection; defaults to llama-3.1-70b. */
+    veniceModel?: string;
+    /** Frontier provider configs, if 'frontier-with-filter' chosen. */
+    frontierConfig: FrontierProviderConfig;
+    /** Hybrid routing rules, if 'hybrid' chosen for any surface. */
+    hybridRules?: HybridRoutingRules;
+    /** Fallback behavior per surface. */
+    fallback: Record<Surface, FallbackBehavior>;
+    /**
+     * Operator preference for the picker modal: when true, picking a
+     * substrate + key for any one surface fans out to every surface in one
+     * save (Finding SS, v1.2.0-rc.1). Defaults to true; operators wanting
+     * per-surface granularity flip the picker toggle off and the next
+     * single-surface choice persists this back to false.
+     */
+    applyToAllSurfaces?: boolean;
+    /** ISO8601 timestamp of last operator change. */
+    updatedAt: string;
+}
+interface SummarizeRequest {
+    kind: "summarize";
+    context: string;
+    query: string;
+    maxTokens?: number;
+}
+interface ClassifyRequest {
+    kind: "classify";
+    items: string[];
+    categories: string[];
+    maxTokens?: number;
+}
+interface RedactRequest {
+    kind: "redact";
+    text: string;
+}
+/**
+ * Per-substrate response envelope. Substrate clients return content + telemetry;
+ * audit-emission and badge-rendering happen at the selector layer.
+ */
+interface SubstrateResponse {
+    /** The substrate that actually served this invocation (may differ from chosen if fallback fired). */
+    servedBy: SubstrateChoice;
+    /** Stable failure-class enum on failure; null on success. */
+    failureClass: SubstrateFailureClass | null;
+    /** Body shape varies by request kind. */
+    body: {
+        kind: "summarize";
+        text: string;
+    } | {
+        kind: "classify";
+        results: {
+            category: string;
+            confidence: number;
+        }[];
+    } | {
+        kind: "redact";
+        redacted: string;
+        placeholders: Record<string, string>;
+    } | {
+        kind: "failure";
+        message: string;
+    };
+    /** ISO8601 of when invocation completed. */
+    completedAt: string;
+    /** Total wall-clock latency in ms. */
+    latencyMs: number;
+}
+/**
+ * Stable failure-class enum. Backends return one of these when a substrate
+ * invocation fails; the selector's audit emission carries this verbatim.
+ *
+ * Adding a new failure class requires updating the audit-event consumer and
+ * the dashboard status-mapping in the same PR.
+ */
+type SubstrateFailureClass = "substrate_unavailable" | "substrate_misconfigured" | "substrate_rate_limited" | "substrate_auth_failed" | "substrate_timeout" | "substrate_capability_unsupported" | "substrate_disabled" | "internal_error";
+/**
+ * Capability profile for each substrate. Surfaces consult this before
+ * invoking; if the substrate cannot serve the request kind, the selector
+ * applies the fallback policy.
+ */
+interface SubstrateCapability {
+    summarize: boolean;
+    classify: boolean;
+    redact: boolean;
+}
+/**
+ * The handle a surface holds after `selector.getSubstrate(surface)`. The
+ * surface invokes via the typed methods; the substrate client implements them.
+ *
+ * Surfaces MUST treat any thrown error as a `substrate_unavailable` failure;
+ * the selector's invoke wrapper catches and emits the audit event.
+ */
+interface SubstrateHandle {
+    surface: Surface;
+    substrate: SubstrateChoice;
+    badge: SubstrateBadge;
+    capability: SubstrateCapability;
+    /**
+     * Optional operator-readable display string for the chat / dashboard headers.
+     * Resolved from the badge labelKey; produced by the selector at handle issue,
+     * not by the substrate client.
+     */
+    displayLabel: string;
+    summarize?: (req: SummarizeRequest) => Promise<SubstrateResponse>;
+    classify?: (req: ClassifyRequest) => Promise<SubstrateResponse>;
+    redact?: (req: RedactRequest) => Promise<SubstrateResponse>;
+}
+/**
+ * Operator-visible per-surface status report rendered by the transparency UI.
+ *
+ * The dashboard SPA consumes this via the `/api/hub/intelligence/status`
+ * route; the picker modal consumes it before substrate selection to surface
+ * hardware-capability hints.
+ */
+interface SubstrateStatusReport {
+    version: "1.2";
+    generatedAt: string;
+    surfaces: SurfaceStatus[];
+    hardware: HardwareCapabilityReport;
+}
+interface SurfaceStatus {
+    surface: Surface;
+    chosen: SubstrateChoice;
+    badge: SubstrateBadge;
+    /** Substrate-side health probe result. */
+    health: "ok" | "degraded" | "unavailable";
+    /** Stable failure class when health != "ok"; null when "ok". */
+    failureClass: SubstrateFailureClass | null;
+    /**
+     * Recent runtime + validation failures for this surface, capped at 5
+     * entries and time-windowed to 24 hours. Sourced from real chat-call
+     * outcomes (and validateKey results for substrates that expose it),
+     * NOT from the static probe-time misconfig check.
+     *
+     * Per Finding VV (v1.2.0-rc.1): the operator-visible badge degrades to
+     * "yellow" / "degraded" whenever this array is non-empty even if the
+     * static probe still says ok. This closes the truth-telling gap where
+     * the dashboard reported all surfaces healthy after the runtime chat
+     * had already failed against the same substrate.
+     */
+    recentFailures: RecentFailureEntry[];
+}
+/**
+ * One observed substrate failure surfaced via `/api/hub/intelligence/status`.
+ * Carries enough metadata for the operator to triage (when, what failure
+ * class, brief operator-safe snippet) without leaking request bodies,
+ * response bodies, or operator credentials.
+ *
+ * Snippets are bounded human-readable strings (e.g. "venice configured
+ * model not found") drawn from the substrate failure-message field; the
+ * selector strips anything resembling an API key or PII before retention.
+ * Operators wanting full forensic detail consult the L2 audit log; this
+ * surface is the at-a-glance triage path.
+ */
+interface RecentFailureEntry {
+    /** ISO8601 timestamp of when the failure was observed. */
+    ts: string;
+    /** Stable failure-class enum carried verbatim from the substrate response. */
+    failureClass: SubstrateFailureClass;
+    /** Bounded operator-safe snippet describing the failure. */
+    snippet: string;
+}
+interface HardwareCapabilityReport {
+    /** Detected total RAM in GB. Self-reported via os.totalmem(). */
+    totalRamGb: number;
+    /** Apple Silicon family if detectable, or "other". */
+    cpuArch: "apple-silicon-m1" | "apple-silicon-m2" | "apple-silicon-m3" | "apple-silicon-m4" | "apple-silicon-other" | "x86_64" | "other";
+    /** Computed tier per position paper §5 (baseline / mid / pro / below-baseline). */
+    tier: "below-baseline" | "baseline" | "mid" | "pro";
+    /** Recommended local model tier per detected hardware. */
+    recommendedLocalModel: LocalModelPick | null;
+    /** Whether Ollama is reachable at the configured endpoint. */
+    ollamaReachable: boolean;
+    /** Models present in Ollama at the time of the report. Empty if not reachable. */
+    ollamaModels: string[];
+}
+
+/**
+ * Sanctuary MCP Server — Frontier-with-Filter Substrate
+ *
+ * Operator's frontier API account (Anthropic / OpenAI / Google) wrapped with
+ * mandatory pre-egress Privacy Filter Tier 2 redaction.
+ *
+ * Per position paper §5: every query routes through Privacy Filter Tier 2
+ * BEFORE the frontier API call. The Privacy Filter event log captures the
+ * pre-redaction match count so the operator can audit what was sent.
+ *
+ * Honesty discipline (CLAUDE.md):
+ *   - Tradeoff badge text explicitly names the leakage
+ *   - Required caveat about subtle PII (paraphrased addresses, contextual
+ *     identifiers) appears in tradeoff text
+ *   - Operator MUST acknowledge before configuration completes (enforced
+ *     by the picker modal in the dashboard SPA, deferred to the v1.2 UI
+ *     follow-up commit)
+ *
+ * Provider clients are kept minimal: one Chat Completions / Messages call
+ * per surface request, no streaming in v1.2 (streaming is a v1.3 chat
+ * surface enhancement).
+ */
+
+/**
+ * Pre-egress redaction hook. The substrate adapter calls this on every
+ * outbound text; returns the redacted text + placeholder map. The Privacy
+ * Filter Tier 2 implementation lives in `l2-operational/privacy-filter.ts`
+ * (extended in this PR to wire the substrate-aware Tier 2 path).
+ *
+ * For v1.2, the redactor passed in is responsible for emitting the audit
+ * event `intelligence_pii_redaction_event` via the selector's auditLog
+ * binding. The frontier substrate is provider-agnostic about how redaction
+ * happens; it just refuses to call the frontier API on `failureClass !== null`.
+ */
+type FrontierRedactor = (text: string) => Promise<{
+    redacted: string;
+    matchCount: number;
+}>;
+
+/**
+ * Sanctuary MCP Server — Intelligence Substrate Selector
+ *
+ * The selector IS the architecture (Erik directive 2026-04-29). Operators
+ * pick (and re-pick) the LLM substrate that powers each intelligence-layer
+ * surface; the selector binds choices to surfaces, provides a typed
+ * `SubstrateHandle` to consumers, applies operator-configured fallback
+ * behavior on substrate failure, and emits audit events for every change
+ * and every invocation.
+ *
+ * Architecture per position paper section 5:
+ *   ┌──────────┐  ┌──────────┐  ┌──────────┐ ┌──────────┐
+ *   │ concierge│  │ sentinel │  │ gate-expl│ │ priv-f-2 │  ... surfaces
+ *   └────┬─────┘  └────┬─────┘  └────┬─────┘ └────┬─────┘
+ *        ▼             ▼             ▼            ▼
+ *   ┌──────────────────────────────────────────────────┐
+ *   │    SubstrateSelector (per-surface routing)       │
+ *   └────┬──────────┬──────────┬──────────┬────────────┘
+ *        ▼          ▼          ▼          ▼
+ *   ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+ *   │ Local  │ │ Venice   │ │ Frontier │ │ Disabled │
+ *   │(Ollama)│ │ (relay)  │ │ + filter │ │ (refuse) │
+ *   └────────┘ └──────────┘ └──────────┘ └──────────┘
+ *
+ * The hybrid substrate is per-surface routing only at v1.2 — operator
+ * pre-binds each surface to a concrete substrate; per-query sensitivity
+ * classification routing is deferred to v1.3+.
+ *
+ * Audit emission discipline:
+ * Every public method that changes config or invokes a substrate appends
+ * an `IntelligenceAuditPayload` to the L2 audit log. The selector never
+ * stores raw request bodies, response bodies, or operator credentials in
+ * audit details; only safe metadata (surface, substrate, hashes, latency,
+ * failure-class enum). The event payload contracts live in
+ * `contracts/v1.2/intelligence-events.ts`.
+ *
+ * Sovereignty invariants preserved:
+ * - Operator API keys live in the encrypted SubstrateConfig persisted
+ *   under the fortress master key.
+ * - Frontier-with-filter substrate ALWAYS routes through a redactor
+ *   before any frontier API call; the redactor argument is required in
+ *   the constructor; passing a null redactor disables the substrate.
+ * - Sentinel-scoring surface defaults to `conservative-deny` fallback so
+ *   substrate failure cannot silently allow an unverified tool call.
+ */
+
+/**
+ * Configuration the selector needs at construction. The audit-log binding
+ * is required: a selector without an audit log violates the audit-emission
+ * invariant and is structurally rejected.
+ */
+interface SelectorConfig {
+    storage: StorageBackend;
+    masterKey: Uint8Array;
+    auditLog: AuditLog;
+    /** Identity that owns the substrate config. Stamped on every audit event. */
+    identityId: string;
+    /**
+     * Pre-egress redactor for the frontier-with-filter substrate. Defaults
+     * to `IDENTITY_REDACTOR` until Privacy Filter Tier 2 wires through.
+     * Passing a custom redactor at construction allows tests + the Tier 2
+     * commit to install a real implementation without modifying the
+     * selector.
+     */
+    redactor?: FrontierRedactor;
+    /**
+     * Optional fetch override for substrate clients. Forwarded to Ollama,
+     * Venice, and frontier client constructors so tests can stub out
+     * network calls.
+     */
+    fetchImpl?: typeof fetch;
+}
+declare class SubstrateSelector {
+    private store;
+    private auditLog;
+    private identityId;
+    private redactor;
+    private fetchImpl;
+    private config;
+    private loaded;
+    /**
+     * Per-surface ring buffer of recent runtime + validation failures. See
+     * `RECENT_FAILURES_CAP` and `RECENT_FAILURES_WINDOW_MS`. Populated by
+     * `recordRecentFailure()` from the `invoke()` failure path and from the
+     * post-config validation hook on substrates that expose validateKey.
+     * Drives the operator-visible degrade in `getOperatorVisibleStatus()`.
+     */
+    private recentFailures;
+    constructor(cfg: SelectorConfig);
+    /**
+     * Load (or initialize) the operator's substrate config. Emits the
+     * `intelligence_config_loaded` audit event regardless of branch so the
+     * audit chain shows config-load activity on boot.
+     */
+    load(): Promise<void>;
+    /**
+     * Operator picked (or re-picked) a substrate for a surface. Persists the
+     * change and emits `intelligence_substrate_chosen`. The picker modal
+     * surfaces the tradeoff text BEFORE invoking this method; the audit
+     * payload captures the hash of that text for auditor verification.
+     */
+    setPerSurfaceChoice(surface: Surface, substrate: SubstrateChoice): Promise<void>;
+    /**
+     * Apply a substrate choice to every surface in one save. Used by the
+     * picker modal's "Apply to all surfaces" affordance (Finding SS,
+     * v1.2.0-rc.1). Persists the per-surface map mutation in a single
+     * write and emits ONE `intelligence_bulk_substrate_chosen` audit
+     * event rather than six per-surface events.
+     *
+     * If `localModelPick` is provided AND substrate === "local", the same
+     * pick is applied to every surface; ignored for other substrates.
+     *
+     * Per-surface bindings the operator had previously customized are
+     * captured in the audit payload's `prior_substrates` map so the
+     * forensic record makes the configuration discontinuity visible.
+     */
+    applyChoiceToAllSurfaces(substrate: SubstrateChoice, opts?: {
+        localModelPick?: LocalModelPick | null;
+    }): Promise<void>;
+    /**
+     * Persist the operator's "Apply to all surfaces" preference. The
+     * picker modal calls this when the operator flips the toggle so the
+     * preference survives a dashboard reload. Does not emit a discrete
+     * audit event; the next bulk or per-surface choice carries the
+     * operator-visible signal.
+     */
+    setApplyToAllPreference(value: boolean): Promise<void>;
+    /**
+     * Operator picked a local model for a surface bound to the local
+     * substrate. Mirrors `setPerSurfaceChoice` for the model-picker case.
+     * Does not emit a separate audit event class; the next
+     * `intelligence_substrate_chosen` event captures the change and the
+     * dashboard transparency UI calls this method only as part of a binding
+     * flow that already audited the substrate choice.
+     */
+    setLocalModelPick(surface: Surface, pick: LocalModelPick | null): Promise<void>;
+    /**
+     * Set the Venice API key. Stored as part of the encrypted
+     * SubstrateConfig record. Does not emit a substrate_chosen event by
+     * itself; the dashboard flow always pairs key entry with a substrate
+     * choice and the choice carries the audit semantics.
+     *
+     * Post-set validation (Finding VV, v1.2.0-rc.1): if a non-null key is
+     * provided, the selector probes Venice with `validateKey()` and records
+     * a failure entry on every Venice-bound surface when the result is not
+     * `"ok"`. This lets the operator-visible status degrade from validation
+     * outcomes alone, not just from runtime chat-call failures, so a broken
+     * key or drifted model is visible before the operator's first chat
+     * attempt. Probe failures (timeout, transport) are not recorded; the
+     * runtime path will surface those when the operator actually invokes.
+     */
+    setVeniceApiKey(apiKey: string | null): Promise<void>;
+    /**
+     * Probe Venice with the given API key and record a failure entry on
+     * every surface bound to Venice when the probe returns anything other
+     * than `"ok"`. Failures map to stable substrate failure-class enum
+     * values: `invalid-key` -> `substrate_auth_failed`, `invalid-model` ->
+     * `substrate_misconfigured`, `unreachable` -> swallow (runtime path
+     * will surface).
+     */
+    private validateVeniceAndRecord;
+    /**
+     * Set a frontier provider's API key. See `setVeniceApiKey` for the
+     * audit-semantics rationale.
+     */
+    setFrontierApiKey(provider: FrontierProvider, apiKey: string | null): Promise<void>;
+    /**
+     * Set the hybrid routing rules. The picker modal calls this when the
+     * operator saves the hybrid configuration tab. Validates the rules
+     * (every surface bound, no `hybrid` recursion) before persist; throws
+     * on invalid input so the operator-facing form can surface the failure.
+     *
+     * Setting rules does NOT change any surface's per-surface choice; the
+     * operator must also pick `hybrid` for the surfaces they want routed
+     * through these rules. This separation keeps the flow obvious in the
+     * UI (set rules + then choose hybrid for each surface that should use
+     * them) and lets the operator test rule changes without mass-flipping
+     * surfaces to hybrid.
+     */
+    setHybridRules(rules: HybridRoutingRules): Promise<void>;
+    /**
+     * Override the per-surface fallback behavior. Defaults are set per
+     * position paper section 5; the picker modal surfaces the tradeoff and
+     * the operator can override.
+     */
+    setFallbackBehavior(surface: Surface, fallback: FallbackBehavior): Promise<void>;
+    /**
+     * Reset every binding to the per-surface defaults. Emits
+     * `intelligence_config_reset` so post-reset audit trails make the
+     * configuration discontinuity visible.
+     */
+    resetToDefaults(): Promise<void>;
+    /**
+     * Snapshot the current config (read-only). Tests + the dashboard
+     * transparency UI consume this; mutations always go through the
+     * setter methods so audit-emission stays consistent.
+     */
+    getConfig(): SubstrateConfig;
+    /**
+     * Install (or replace) the redactor used by the frontier-with-filter
+     * substrate. Bootstrap code calls this after constructing the selector
+     * with the default IDENTITY_REDACTOR; the Privacy Filter Tier 2
+     * commit's `buildPrivacyTier2Redactor` produces the redactor that
+     * closes over the selector for audit emission. Late-binding via this
+     * method avoids the circular construction dependency
+     * (selector needs redactor; redactor needs selector for emit).
+     *
+     * Subsequent calls to getSubstrate("...frontier-with-filter") will use
+     * the installed redactor; already-issued handles continue to use the
+     * redactor that was installed at handle-issue time. Consumers that
+     * cache handles SHOULD re-issue after installRedactor.
+     */
+    installRedactor(redactor: FrontierRedactor): void;
+    /**
+     * Build a typed SubstrateHandle for the given surface. Lazily
+     * instantiates the substrate client based on the operator's binding;
+     * the handle carries the substrate label, tradeoff badge, capability
+     * surface, and bound `summarize` / `classify` / `redact` methods that
+     * delegate to the substrate client.
+     *
+     * For the `disabled` substrate, the returned handle has the capability
+     * surface zeroed and no methods bound; consumers checking
+     * `handle.capability.summarize === false` short-circuit to the
+     * surface's static fallback (templates for gate-explanation, Tier 1
+     * regex for privacy-filter-tier-2, etc.).
+     *
+     * For the `hybrid` substrate, this method delegates to the per-surface
+     * routing rules (set via `setPerSurfaceChoice` on a substrate other
+     * than `hybrid`); v1.2 ships per-surface routing only.
+     */
+    getSubstrate(surface: Surface): Promise<SubstrateHandle>;
+    /**
+     * Operator-visible per-surface status report. Consumers: the dashboard
+     * transparency UI and the `/api/hub/intelligence/status` route.
+     *
+     * Probes hardware + Ollama at call time. The dashboard re-fetches every
+     * 5 minutes to refresh status badges (degraded -> ok flip when Ollama
+     * comes back up, and so on).
+     */
+    getOperatorVisibleStatus(): Promise<SubstrateStatusReport>;
+    /**
+     * Probe the host machine's hardware capability. v1.2 reports total RAM
+     * + CPU arch (Apple Silicon family if detectable) and computes the tier
+     * per position paper section 5. Used by the picker modal to surface
+     * "below-baseline -> recommend Venice" guidance.
+     */
+    probeHardware(): Promise<HardwareCapabilityReport>;
+    /**
+     * Invoke a substrate with audit emission. Wraps the underlying
+     * SubstrateHandle method, applies fallback behavior on failure per the
+     * operator's per-surface config, and emits `intelligence_substrate_invoked`
+     * + (on failure) `intelligence_substrate_failure`.
+     *
+     * Consumers SHOULD call this method rather than calling `handle.summarize`
+     * etc. directly; the handle is exposed for cases where audit emission
+     * needs to be explicitly skipped (probe paths, tests).
+     */
+    invokeSummarize(surface: Surface, req: SummarizeRequest): Promise<SubstrateResponse>;
+    invokeClassify(surface: Surface, req: ClassifyRequest): Promise<SubstrateResponse>;
+    invokeRedact(surface: Surface, req: RedactRequest): Promise<SubstrateResponse>;
+    private ensureLoaded;
+    private invoke;
+    /**
+     * Append a failure entry to the per-surface ring buffer. The selector
+     * uses this in the `invoke()` failure path and in the post-config
+     * `setVeniceApiKey` validation hook so the operator-visible badge
+     * degrades from runtime AND from validation outcomes.
+     *
+     * Operator-safe by construction: snippets are bounded by
+     * `FAILURE_SNIPPET_MAX_LEN` and pulled from substrate `failure.message`
+     * fields (which substrates produce for operator-readable output and
+     * never include API keys or PII). The cap + window prune happen on
+     * every read in `recentFailuresFor()` so the ring buffer never grows.
+     */
+    private recordRecentFailure;
+    /**
+     * Read recent failures for a surface, pruning entries older than the
+     * 24-hour window. Pruning happens lazily on read so a long-quiet surface
+     * does not retain stale entries from yesterday's debugging.
+     */
+    private recentFailuresFor;
+    /**
+     * Test-only seam: lets selector tests assert on recorded failures
+     * without poking the private ring buffer. Returns a defensive copy.
+     */
+    getRecentFailuresForTest(surface: Surface): RecentFailureEntry[];
+    /**
+     * Test-only seam: lets selector tests seed a recent-failure entry on a
+     * surface so the buffer-clear behavior added for Finding ZZ (v1.2.0-rc.2)
+     * can be exercised without spinning up a real failing substrate. Mirrors
+     * `getRecentFailuresForTest`; never call from production paths.
+     */
+    recordRecentFailureForTest(surface: Surface, failureClass: SubstrateFailureClass, snippet: string): void;
+    /**
+     * Build a substrate handle for a surface bound to a concrete choice.
+     * The substrate-client constructor is paid lazily so the selector
+     * doesn't pre-spawn HTTP clients for substrates the operator never
+     * touches.
+     */
+    private buildHandle;
+    private disabledHandle;
+    private localHandle;
+    private veniceHandle;
+    private frontierHandle;
+    private probeSurfaceHealth;
+    private makeBadge;
+    private fallbackAction;
+    /**
+     * Internal hook for the Privacy Filter Tier 2 commit. Lets a redactor
+     * audit-emit a `pii_redaction_event` payload through the selector
+     * without exposing the AuditLog binding directly to redactor
+     * implementations.
+     */
+    emitRedactionEvent(args: {
+        surface: Surface;
+        substrate: SubstrateChoice;
+        matchCount: number;
+        filterTier: 1 | 2;
+    }): void;
+    private emit;
+}
+
+/**
+ * Sanctuary MCP Server — Operator Chat Types
+ *
+ * Distinct from the existing agent-to-agent mesh chat (`chat-service.ts`).
+ * Operator chat is the operator-fortress concierge surface: an operator
+ * types into the v1.1 dashboard, Sanctuary persists the conversation,
+ * audits every message, and routes responses through the substrate
+ * selector.
+ *
+ * The direct-agent surface (operator-to-wrapped-agent conversation) was
+ * removed in the v1.2 reshape. The concierge surface (operator-to-
+ * Sanctuary) is the only operator chat surface that ships in v1.2.
+ *
+ * Sovereignty invariants:
+ * - Conversation history is encrypted at rest under the fortress master
+ *   key via an HKDF-derived purpose key.
+ * - Audit emission is non-optional: every operator submit and every
+ *   concierge reply lands in the L2 audit log.
+ * - No raw message bodies are stored in audit `details`; only message
+ *   hashes and safe metadata. Bodies live in the encrypted chat store
+ *   that the operator can export, delete, or rotate.
+ */
+
+/**
+ * The chat surface a message belongs to. Concierge is the only operator
+ * chat surface in v1.2; the type stays a single-member union for
+ * forward-compatibility if additional Sanctuary-side surfaces land later.
+ */
+type OperatorChatSurface = "concierge";
+/**
+ * Message-role enum. Concierge has two roles: `operator` (the human) and
+ * `concierge` (Sanctuary's response).
+ */
+type OperatorChatRole = "operator" | "concierge";
+/**
+ * One message in a concierge thread. The body is stored encrypted at
+ * rest; the in-memory shape carries the cleartext for service consumers,
+ * and the audit emission carries only `message_hash` + safe metadata.
+ */
+interface OperatorChatMessage {
+    /** Stable message id (uuid) assigned at create time. */
+    message_id: string;
+    /** Surface this message belongs to. */
+    surface: OperatorChatSurface;
+    /** Sender role. */
+    role: OperatorChatRole;
+    /** Cleartext body. NEVER appears in audit `details`. */
+    body: string;
+    /** ISO8601 timestamp the message was created. */
+    created_at: string;
+    /**
+     * For concierge response messages: which substrate served the response.
+     * Null on operator-sent messages. Surfaces in the chat header badge.
+     */
+    served_by?: SubstrateChoice;
+    /**
+     * For concierge response messages: latency of the substrate call in ms.
+     * Operator-side surfaces this in the message tooltip / activity feed.
+     */
+    substrate_latency_ms?: number;
+}
+/**
+ * The shape persisted to disk under `_chat/<surface>/<thread-key>`.
+ *
+ * Threads are append-only; the persisted record is read-rewritten on
+ * every message append. v1.2 caps thread length at
+ * `OPERATOR_CHAT_MAX_THREAD_LENGTH`; older messages drop off when the
+ * cap is exceeded.
+ */
+interface OperatorChatThread {
+    /** Forward-compat field. v1.2 uses 1; bump on schema change. */
+    version: 1;
+    /** Surface (concierge in v1.2). */
+    surface: OperatorChatSurface;
+    /** Thread key; concierge is fortress-scoped under `CONCIERGE_THREAD_KEY`. */
+    thread_key: string;
+    /** Append-only message log; oldest first. */
+    messages: OperatorChatMessage[];
+    /** ISO8601 timestamp the thread was last updated. */
+    updated_at: string;
+}
+/**
+ * Concierge response envelope. Carries the substrate response (or
+ * fallback message) plus the operator-visible substrate badge.
+ */
+interface ConciergeResponse {
+    /** The response message persisted into the concierge thread. */
+    message: OperatorChatMessage;
+    /** The substrate that served this query. */
+    served_by: SubstrateChoice;
+    /** Operator-visible label rendered next to the response. */
+    display_label: string;
+    /** Outcome class for activity-feed projection. */
+    outcome: "ok" | "substrate_failure" | "substrate_disabled";
+}
+
+/**
+ * Sanctuary MCP Server — Operator Chat Persistence
+ *
+ * Encrypted at-rest store for the operator-chat concierge thread.
+ * Mirrors the `IntelligenceConfigStore` shape but addresses records by
+ * `(surface, thread-key)` for forward-compatibility.
+ *
+ * Storage layout:
+ *   namespace: `_chat`              (underscore-prefixed = reserved L1 namespace)
+ *   key:       `concierge.{thread_key}`
+ *   payload:   AES-256-GCM-encrypted `OperatorChatThread` JSON, key
+ *              derived via HKDF from the fortress master key with info
+ *              string `operator-chat-store-v1`.
+ *
+ * The direct-agent surface (per-agent threads + session records) was
+ * removed in the v1.2 reshape. The concierge surface stores under a
+ * single record with sentinel thread-key `_fortress`
+ * (CONCIERGE_THREAD_KEY).
+ *
+ * Append-only semantics:
+ * Threads are append-only at the message level. Persist is full-record
+ * read-modify-write; the cap on thread length is enforced at append time
+ * (oldest messages fall off when `OPERATOR_CHAT_MAX_THREAD_LENGTH` is
+ * exceeded). The audit log retains every message regardless.
+ */
+
+/**
+ * Encrypted operator chat persistence.
+ */
+declare class OperatorChatStore {
+    private storage;
+    private encryptionKey;
+    constructor(storage: StorageBackend, masterKey: Uint8Array);
+    /**
+     * Load a thread. Returns null if no record exists or if the on-disk
+     * record is corrupt; callers treat both as "empty thread, start
+     * fresh" and emit no audit event for the absence.
+     */
+    loadThread(surface: OperatorChatSurface, threadKey: string): Promise<OperatorChatThread | null>;
+    /**
+     * Persist a thread. Caller is responsible for cap enforcement; the
+     * `appendMessage` helper below drops oldest messages before persist
+     * when the cap is exceeded.
+     */
+    saveThread(thread: OperatorChatThread): Promise<void>;
+    /**
+     * Append a message to a thread, creating the thread if it doesn't
+     * exist, and persist. Enforces the per-thread length cap by dropping
+     * oldest messages first. Returns the persisted thread.
+     */
+    appendMessage(surface: OperatorChatSurface, threadKey: string, message: OperatorChatMessage): Promise<OperatorChatThread>;
+    /**
+     * Delete a thread. Used by operator-driven thread reset. The audit
+     * log retains the per-message history regardless.
+     */
+    deleteThread(surface: OperatorChatSurface, threadKey: string): Promise<void>;
+}
+
+/**
+ * Sanctuary MCP Server — Operator Chat Service
+ *
+ * The operator-fortress concierge surface. Distinct from the
+ * agent-to-agent mesh chat (`chat-service.ts`) which handles libp2p +
+ * OpenMLS group sessions among wrapped agents.
+ *
+ * The direct-agent surface (operator-to-wrapped-agent conversation) was
+ * removed in the v1.2 reshape; the concierge surface is the only
+ * operator-chat surface in v1.2.
+ *
+ * Concierge surface (path: `sendConcierge`):
+ *   1. PII-filter the operator query (Tier 1 regex).
+ *   2. Build fortress context from audit log + activity feed +
+ *      agent registry (`assembleConciergeContext`).
+ *   3. Invoke the substrate selector at `surface: "concierge"`.
+ *   4. Persist operator query + concierge response in the concierge
+ *      thread under `_chat/concierge.<sentinel>`.
+ *   5. Emit `operator_concierge_chat` audit event with safe metadata.
+ *
+ * Sovereignty invariants:
+ * - Audit emission is non-optional on every public method that mutates
+ *   the chat state. Construction with no audit log is structurally
+ *   rejected.
+ * - The substrate selector is OPTIONAL: a service constructed without
+ *   one degrades to "Concierge unavailable; substrate not configured".
+ *   The wiring layer can instantiate the service before the substrate
+ *   selector when bootstrap order requires it.
+ * - The PII filter is the Tier 1 regex shipped in
+ *   `l2-operational/privacy-filter.ts`; Tier 2 NER+LLM redaction lives
+ *   in the substrate-selector layer (substrate-routed), not here.
+ */
+
+/**
+ * Snapshot of fortress state surfaces the concierge consults to
+ * answer operator queries. Caller (the hub-service wiring) supplies
+ * the providers; the service wires them into the substrate prompt.
+ *
+ * Each provider returns plain strings the substrate selector folds
+ * into a single context blob; the service does not attempt to
+ * structure the prompt beyond stitching with newlines. Keeping the
+ * prompt-shape decisions in the service-construction layer (rather
+ * than in the wiring) lets the dashboard team iterate concierge
+ * prompts without touching server code.
+ */
+interface ConciergeContextProviders {
+    /** Recent activity-feed entries as a free-form string, oldest first. */
+    recentActivity: () => Promise<string>;
+    /** Wrapped-agent inventory as a free-form string. */
+    agentInventory: () => Promise<string>;
+    /** Open inbox items as a free-form string. */
+    openInbox: () => Promise<string>;
+}
+/**
+ * PII filter the concierge applies to operator queries before passing
+ * them to the substrate. v1.2 wires the Tier 1 regex; the substrate
+ * selector handles Tier 2 NER+LLM redaction internally on egress paths.
+ *
+ * Returns the filtered query plus the count of redactions performed
+ * (surfaced in the audit event for operator visibility).
+ */
+interface ConciergePiiFilter {
+    filter(input: string): {
+        filtered: string;
+        redactions: number;
+    };
+}
+/**
+ * Construction inputs for the operator chat service.
+ */
+interface OperatorChatServiceDeps {
+    /** Encrypted at-rest store; built from fortress master key. */
+    store: OperatorChatStore;
+    /** Audit log for `operator_concierge_chat` events. */
+    auditLog: AuditLog;
+    /** Operator identity that owns the chat session. */
+    identityId: string;
+    /**
+     * Substrate selector for concierge LLM calls. Optional: when omitted
+     * the concierge surface degrades to a "substrate not configured"
+     * response.
+     */
+    substrateSelector?: SubstrateSelector;
+    /**
+     * Concierge context providers. Required when a substrate selector
+     * is wired; otherwise unused. Wiring layer assembles these from the
+     * activity feed, agent registry, and inbox aggregator.
+     */
+    conciergeContextProviders?: ConciergeContextProviders;
+    /**
+     * PII filter applied to concierge queries pre-substrate. Optional;
+     * when omitted the service still works (no redactions performed).
+     * v1.2 wiring passes the Tier 1 regex.
+     */
+    conciergePiiFilter?: ConciergePiiFilter;
+    /**
+     * Stable max tokens for concierge responses. Defaults to 512 (small
+     * enough for snappy local-model latency, large enough for a useful
+     * summary). Operator-tunable via dashboard config.
+     */
+    conciergeMaxTokens?: number;
+}
+declare class OperatorChatService {
+    private store;
+    private auditLog;
+    private identityId;
+    private substrateSelector?;
+    private contextProviders?;
+    private piiFilter?;
+    private conciergeMaxTokens;
+    constructor(deps: OperatorChatServiceDeps);
+    /**
+     * Operator submit on the concierge surface. Persists the operator's
+     * query, fans out to the substrate selector, persists the response,
+     * and emits the audit event.
+     *
+     * On substrate failure or absence: persists an honest "concierge
+     * unavailable" response and audit-emits with `outcome` = the
+     * appropriate failure class. The chat history reflects what the
+     * operator sees on the page (no silent dropping).
+     */
+    sendConcierge(query: string): Promise<ConciergeResponse>;
+    /**
+     * Read the persisted concierge thread, oldest message first. Returns
+     * an empty array when no thread exists yet.
+     */
+    getConciergeHistory(): Promise<OperatorChatMessage[]>;
+    /**
+     * Stitch fortress state into a single context blob the substrate
+     * folds into its summarization prompt.
+     *
+     * The blob is intentionally plain text (not structured JSON) because
+     * small local models (Gemma 2 2B) handle plain text more reliably
+     * than nested structures. Format:
+     *
+     *   ```
+     *   ## Recent activity
+     *   <recentActivity output>
+     *
+     *   ## Wrapped agents
+     *   <agentInventory output>
+     *
+     *   ## Open inbox
+     *   <openInbox output>
+     *   ```
+     */
+    private assembleConciergeContext;
+    private emit;
+}
+
 /**
  * Sanctuary v1.1. Operator Hub API Types
  *
@@ -4171,6 +5232,11 @@ interface HubTier1ApprovalEnqueuedResult {
      */
     operation_category: HubApprovalPendingItem["operation_category"];
 }
+interface HubTemplateBindingApprovalEnqueuedResult extends HubTier1ApprovalEnqueuedResult {
+    current_template_id?: ChannelTemplateId;
+    proposed_template_id: ChannelTemplateId;
+    compiled_policy_id: string;
+}
 /**
  * Result returned from a fortress-scope Tier-1 action that has been
  * deferred to operator approval. Distinguished from the per-agent shape by
@@ -4225,11 +5291,7 @@ interface HubAgentController {
      * approval lands.
      */
     bindPolicy(agentId: string, policyId: string): Promise<void>;
-    /**
-     * Apply a non-Tier-1 channel-template binding. Channel templates are
-     * compositions over the canonical four slots; binding does not require
-     * Tier 1 approval at v1.1.
-     */
+    /** Apply an operator-approved channel-template binding. */
     bindChannelTemplate(agentId: string, templateId: ChannelTemplateId): Promise<void>;
 }
 /**
@@ -4362,6 +5424,11 @@ interface HubServiceDeps {
      * returning the in-memory projection.
      */
     readPersistedLocalAgents?: () => LocalAgentRecord[];
+    /**
+     * Optional persisted agent writer. Used when approved hub actions mutate
+     * registry-local fields that should survive refresh and restart.
+     */
+    writePersistedLocalAgents?: (records: LocalAgentRecord[]) => void;
     /** Inbox aggregation sources. */
     inboxSources: HubInboxSources;
     /** Activity feed sources. */
@@ -4391,6 +5458,44 @@ interface HubServiceDeps {
      * Defaults to `() => new Date()` when omitted.
      */
     now?: () => Date;
+    /**
+     * Optional operator-chat service. When supplied, the hub exposes the
+     * concierge chat endpoints; when omitted, those routes return
+     * HubCapabilityError. Construction-time injection lets the dashboard
+     * wiring layer build the chat service against the same audit log +
+     * master key + storage backend as the rest of the v1.1 hub without
+     * forcing the chat-service constructor through a circular import.
+     * The direct-agent chat surface was removed in the v1.2 reshape
+     * (2026-04-30); the field name is retained for source compatibility.
+     */
+    operatorChat?: OperatorChatService;
+}
+/**
+ * Click-to-inspect panel returned by `openAgentInspectPanel`. The panel
+ * surfaces the agent's recent activity, pending approvals routed through
+ * this agent, and policy summary at a glance, repurposing the click-
+ * to-chat wire-up shipped in PR #98 + PR #100. The direct-agent chat
+ * surface was removed in the v1.2 reshape; this panel is the operational
+ * destination for the click.
+ */
+interface HubAgentInspectPanel {
+    /** The agent the panel was opened on. */
+    agent_id: string;
+    /** ISO8601 timestamp the panel was opened. */
+    opened_at: string;
+    /** Recent activity-feed entries for this agent, oldest first. */
+    recent_activity: HubActivityFeedEntry[];
+    /**
+     * Open Tier 1 inbox items routed through this agent. Empty when the
+     * agent has no pending approvals.
+     */
+    pending_approvals: HubInboxItem[];
+    /**
+     * Bound policy summary for this agent. Null when the agent has no
+     * channel-template binding (e.g. immediately after wrap, before the
+     * operator picks a template).
+     */
+    policy_summary: HubPolicySummary | null;
 }
 
 /**
@@ -4438,10 +5543,10 @@ declare class HubService {
      */
     bindAgentPolicy(agentId: string, policyId: string): HubTier1ApprovalEnqueuedResult;
     /**
-     * Bind a different channel template. Not Tier 1; channel templates are
-     * compositions over the four canonical slots and bind synchronously.
+     * Bind a different channel template. Tier 1: enqueues a policy_change
+     * approval item and only applies the binding after operator approval.
      */
-    bindAgentChannelTemplate(agentId: string, rawTemplateId: unknown): Promise<LocalAgentRecord>;
+    bindAgentChannelTemplate(agentId: string, rawTemplateId: unknown): HubTemplateBindingApprovalEnqueuedResult;
     /**
      * Enqueue a fortress-scope Tier 1 lockdown. One inbox item is created;
      * on operator approval the handler iterates `agentController.lockdown`
@@ -4484,6 +5589,33 @@ declare class HubService {
      * Test/inspection helper. Not part of the public service surface.
      */
     inboxStoreSize(): number;
+    private requireOperatorChat;
+    /**
+     * Operator submit on the concierge chat surface. Pass-through to the
+     * operator-chat-service which owns substrate-selector routing, PII
+     * filtering, persistence, and audit emission.
+     */
+    sendConcierge(query: string): Promise<ConciergeResponse>;
+    /**
+     * Read the persisted concierge thread.
+     */
+    getConciergeHistory(): Promise<OperatorChatMessage[]>;
+    /**
+     * Open the click-to-inspect/approve panel for a wrapped agent. The
+     * panel surfaces recent activity routed through this agent, pending
+     * Tier 1 approvals on this agent, and the bound policy summary,
+     * repurposing the click-to-chat wire-up from PR #98 + PR #100 to a
+     * substrate-aligned inspect destination after the v1.2 reshape removed
+     * direct-agent chat.
+     *
+     * Synchronous open shape preserved (caller's `await` semantics
+     * unchanged from the prior `openDirectAgentSession` surface). The
+     * panel is read-only; no side effects beyond the audit-event emission
+     * for the panel-open itself.
+     */
+    openAgentInspectPanel(agentId: string, options?: {
+        activityLimit?: number;
+    }): Promise<HubAgentInspectPanel>;
 }
 
 /**
@@ -4509,16 +5641,29 @@ declare class HubService {
  *     the v1.2 work to project those into operator cards.
  *   - Activity feed reads from the real audit log. This is the one source
  *     that's already complete in v1.1.0 and just needs to be plugged in.
- *   - Agent controller errors on every action. v1.1.1 cannot honestly
- *     pause / unwrap / lockdown anything because no agent registry yet
- *     exists; the wiring returns `HubCapabilityError` rather than lying
- *     about what shipped.
+ *   - Agent controller errors on runtime harness actions that v1.1 cannot
+ *     honestly execute. Channel-template binding is registry-local in v1.2,
+ *     so its controller hook is a no-op and HubService persists the binding
+ *     after Tier 1 approval.
  */
 
 interface V11Bindings {
     hubService: HubService;
     identityId: string;
     fortressId: string;
+    /**
+     * Optional Intelligence Substrate Selector. Dispatch layer routes
+     * `/api/hub/intelligence/*` here when set; absent means the routes
+     * 503 with a "selector not configured" body.
+     */
+    intelligenceSelector?: SubstrateSelector;
+    /**
+     * Optional Operator Chat Service. Constructed when storage + masterKey
+     * are passed to `buildV11Bindings`. The HubService accepts this
+     * directly via its `operatorChat` dep; callers that want the harness-
+     * side `recordAgentReply` integration also need the service handle.
+     */
+    operatorChatService?: OperatorChatService;
 }
 
 /**
@@ -5624,4 +6769,4 @@ declare function createSanctuaryServer(options?: {
     storage?: StorageBackend;
 }): Promise<SanctuaryServer>;
 
-export { ATTESTATION_VERSION, type ActivityEntry, type AggregatorSources, ApprovalGate, type ApprovalHandlers, type AttestationBody, type AttestationVerificationResult, AuditLog, AutoApproveChannel, BaselineTracker, type BridgeAttestationRequest, type BridgeAttestationResult, type BridgeCommitment, type BridgeVerificationResult, TEMPLATES as CONTEXT_GATE_TEMPLATES, CallbackApprovalChannel, ClientManager, CommitmentStore, type ConcordiaOutcome, type ConnectionState, type ContextAction, type ContextFilterResult, ContextGateEnforcer, type ContextGatePolicy, ContextGatePolicyStore, type ContextGateRule, type ContextGateTemplate, DashboardApprovalChannel, type DashboardConfig, type DashboardHandle, type DashboardServerOptions, type DetectionResult, type EnforcerConfig, type ExitAuditReceiptsArtifact, type ExitBundleDetailedVerifierResult, type ExitCommandArgs, type ExitCommitmentsArtifact, type ExitEncryptedStateBundle, type ExitPlaceholderVaultMetadataArtifact, type ExitPolicySetArtifact, type ExitPublicIdentityArtifact, type ExportExitBundleOptions, type ExportExitBundleResult, type FederationCapabilities, type FederationPeer, FederationRegistry, type FieldClassification, type FieldFilterResult, FilesystemStorage, type GateResult, HERO_COPY, type HandshakeChallenge, type HandshakeCompletion, type HandshakeResponse, type HandshakeResult, type ImportExitBundleOptions, type ImportExitBundleResult, InMemoryModelProvenanceStore, InjectionDetector, type InjectionDetectorConfig, type InjectionSignal, type L1Status, type L2Status, type L3Status, type L4Status, type LoadedExitArtifact, MODEL_PRESETS, MemoryStorage, type ModelProvenance, type ModelProvenanceStore, type PedersenCommitment, type PeerTrustEvaluation, type PendingApproval, type PolicyRecommendation, PolicyStore, type PrincipalPolicy, type ProtectionSnapshot, type ProviderCategory, ProxyRouter, type ProxyRouterOptions, type ReputationLookup, ReputationStore, type SHRBody, type SHRGeneratorOptions, type SHRVerificationResult, type SanctuaryConfig, type SanctuaryServer, type SignedAttestation, type SignedSHR, type SovereigntyProfile, SovereigntyProfileStore, type SovereigntyProfileUpdate, type SovereigntyTier, type StartDashboardOptions, StateStore, StderrApprovalChannel, type StreamEvent, TIER_WEIGHTS, type TierMetadata, type TieredAttestation, type UpstreamConnection, type UpstreamServer, type UpstreamTool, WebhookApprovalChannel, type WebhookCallbackPayload, type WebhookConfig, type WebhookPayload, type ZKProofOfKnowledge, type ZKRangeProof, canonicalize, classifyField, completeHandshake, computeWeightedScore, createBridgeCommitment, createDefaultProfile, createPedersenCommitment, createProofOfKnowledge, createRangeProof, createSanctuaryServer, evaluateField, exitBundleManifestShape, exportExitBundle, filterContext, generateAttestation, generateSHR, generateSystemPrompt, getProtectionSnapshot, getTemplate, importExitBundle, initiateHandshake, listTemplateIds, loadConfig, loadExitArtifact, loadPrincipalPolicy, readManifest, recommendPolicy, renderDashboardHTML, resolveTier, respondToHandshake, runExitCommand, signPayload, startDashboard, startDashboardServer, tierDistribution, verifyAttestation, verifyBridgeCommitment, verifyCompletion, verifyExitBundle, verifyPedersenCommitment, verifyProofOfKnowledge, verifyRangeProof, verifySHR, verifySignature };
+export { ATTESTATION_VERSION, type ActivityEntry, type AggregatorSources, ApprovalGate, type ApprovalHandlers, type AttestationBody, type AttestationVerificationResult, AuditLog, AutoApproveChannel, BaselineTracker, type BridgeAttestationRequest, type BridgeAttestationResult, type BridgeCommitment, type BridgeVerificationResult, TEMPLATES as CONTEXT_GATE_TEMPLATES, CallbackApprovalChannel, ClientManager, CommitmentStore, type ConcordiaOutcome, type ConnectionState, type ContextAction, type ContextFilterResult, ContextGateEnforcer, type ContextGatePolicy, ContextGatePolicyStore, type ContextGateRule, type ContextGateTemplate, DashboardApprovalChannel, type DashboardConfig, type DashboardHandle, type DashboardServerOptions, type DetectionResult, type EnforcerConfig, type ExitAuditReceiptsArtifact, type ExitBundleDetailedVerifierResult, ExitBundleImportError, type ExitCommandArgs, type ExitCommitmentsArtifact, type ExitEncryptedStateBundle, type ExitPlaceholderVaultMetadataArtifact, type ExitPolicySetArtifact, type ExitPublicIdentityArtifact, type ExportExitBundleOptions, type ExportExitBundleResult, type FederationCapabilities, type FederationPeer, FederationRegistry, type FieldClassification, type FieldFilterResult, FilesystemStorage, type GateResult, HERO_COPY, type HandshakeChallenge, type HandshakeCompletion, type HandshakeResponse, type HandshakeResult, type ImportExitBundleOptions, type ImportExitBundleResult, InMemoryModelProvenanceStore, InjectionDetector, type InjectionDetectorConfig, type InjectionSignal, type L1Status, type L2Status, type L3Status, type L4Status, type LoadedExitArtifact, MODEL_PRESETS, MemoryStorage, type ModelProvenance, type ModelProvenanceStore, type PedersenCommitment, type PeerTrustEvaluation, type PendingApproval, type PolicyRecommendation, PolicyStore, type PrincipalPolicy, type ProtectionSnapshot, type ProviderCategory, ProxyRouter, type ProxyRouterOptions, type ReputationLookup, ReputationStore, type SHRBody, type SHRGeneratorOptions, type SHRVerificationResult, type SanctuaryConfig, type SanctuaryServer, type SignedAttestation, type SignedSHR, type SovereigntyProfile, SovereigntyProfileStore, type SovereigntyProfileUpdate, type SovereigntyTier, type StartDashboardOptions, StateStore, StderrApprovalChannel, type StreamEvent, TIER_WEIGHTS, type TierMetadata, type TieredAttestation, type UpstreamConnection, type UpstreamServer, type UpstreamTool, type VerifyExitBundleOptions, WebhookApprovalChannel, type WebhookCallbackPayload, type WebhookConfig, type WebhookPayload, type ZKProofOfKnowledge, type ZKRangeProof, canonicalize, classifyField, completeHandshake, computeWeightedScore, createBridgeCommitment, createDefaultProfile, createPedersenCommitment, createProofOfKnowledge, createRangeProof, createSanctuaryServer, evaluateField, exitBundleManifestShape, exportExitBundle, filterContext, generateAttestation, generateSHR, generateSystemPrompt, getProtectionSnapshot, getTemplate, importExitBundle, initiateHandshake, listTemplateIds, loadConfig, loadExitArtifact, loadPrincipalPolicy, readManifest, recommendPolicy, renderDashboardHTML, resolveTier, respondToHandshake, runExitCommand, signPayload, startDashboard, startDashboardServer, tierDistribution, verifyAttestation, verifyBridgeCommitment, verifyCompletion, verifyExitBundle, verifyPedersenCommitment, verifyProofOfKnowledge, verifyRangeProof, verifySHR, verifySignature };