@sanctuary-framework/mcp-server 1.2.3 → 1.2.5

package/dist/index.d.cts

@@ -252,6 +252,43 @@ interface ApprovalChannelConfig {
     webhook_url?: string;
     webhook_secret?: string;
 }
+/**
+ * WP-V1.3-10 Upsilon-2: cross-harness approval-redirect mode.
+ *
+ * `mode` selects how the underlying channel and the aggregator interact when
+ * a Tier 1/2 approval fires for a wrapped agent:
+ *
+ *  - `replace`: the underlying channel is bypassed; the gate's
+ *    `requestApproval()` blocks awaiting the operator's decision through
+ *    the aggregator HTTP `approve`/`deny` routes (or any other surface that
+ *    calls `aggregator.resolve()`). Default behavior when redirect is
+ *    enabled.
+ *  - `notify`: both the underlying channel AND the aggregator run; the
+ *    first decision wins. Right shape for harnesses (e.g. Mastra) where
+ *    full local-prompt suppression is not viable, so the operator still
+ *    sees the prompt locally but ALSO can resolve from the unified inbox.
+ *
+ * `per_agent` is a stub for v1.4 multi-agent fortresses: a map of
+ * `agent_id -> {enabled, mode}` overrides. v1.x ignores this field; the
+ * fortress-level `enabled` + `mode` apply to every wrapped agent in the
+ * fortress (which is currently single-agent in practice). v1.4 adds
+ * agent-id propagation through the gate signature and consults this map.
+ */
+interface ApprovalRedirectPerAgentOverride {
+    enabled?: boolean;
+    mode?: "replace" | "notify";
+}
+interface ApprovalRedirectConfig {
+    /** Master toggle. When false, redirect-mode is off across the fortress. */
+    enabled: boolean;
+    /** How the underlying channel and the aggregator coexist. */
+    mode: "replace" | "notify";
+    /**
+     * Per-agent overrides. v1.x stub — populated entries are validated and
+     * persisted but not enforced. Reserved for v1.4 multi-agent fortresses.
+     */
+    per_agent?: Record<string, ApprovalRedirectPerAgentOverride>;
+}
 /** Complete Principal Policy */
 interface PrincipalPolicy {
     version: number;
@@ -263,6 +300,20 @@ interface PrincipalPolicy {
     tier3_always_allow: string[];
     /** How approval requests reach the human */
     approval_channel: ApprovalChannelConfig;
+    /**
+     * WP-V1.3-9 Tau-1: operator-tunable retention window (days) for the
+     * concierge memory store. Per-turn `retention_until` is stamped at
+     * append time; cocoon-unlock pruning drops expired turns. Default 30
+     * days when absent; values <= 0 fall back to the default.
+     */
+    concierge_memory_retention_days?: number;
+    /**
+     * WP-V1.3-10 Upsilon-2: cross-harness approval-redirect mode. Optional;
+     * defaults to `{ enabled: false, mode: "replace" }` (preserves legacy
+     * behavior). Operator-toggled via `sanctuary agents config <tenant>
+     * --approval-redirect=<bool>` or by editing principal-policy.yaml.
+     */
+    approval_redirect?: ApprovalRedirectConfig;
 }
 /** Approval request sent to the human */
 interface ApprovalRequest {
@@ -276,7 +327,7 @@ interface ApprovalRequest {
 interface ApprovalResponse {
     decision: "approve" | "deny";
     decided_at: string;
-    decided_by: "human" | "timeout" | "auto" | "stderr:non-interactive";
+    decided_by: "human" | "timeout" | "auto" | "stderr:non-interactive" | "channel_failure";
 }
 /** Result of the approval gate evaluation */
 interface GateResult {
@@ -658,6 +709,31 @@ type InjectionAlertCallback = (alert: {
 }) => void;
 /** Resolver for proxy tool tiers — provided by the ProxyRouter */
 type ProxyTierResolver = (toolName: string) => (1 | 2 | 3) | null;
+/**
+ * Approval-lifecycle callback. Wired in v1.3 Upsilon-1 by the Cross-
+ * Harness Approval Inbox aggregator. The gate fires this callback before
+ * `channel.requestApproval()` (phase = "requested") and after the channel
+ * resolves or fails (phase = "resolved"). The callback is fire-and-forget;
+ * exceptions are swallowed so a broken aggregator never blocks the gate.
+ *
+ * The callback shape is import-free here so the principal-policy module
+ * keeps no dependency on the aggregator (the aggregator imports the gate,
+ * not vice versa).
+ */
+type ApprovalEventCallback = (event: {
+    phase: "requested" | "resolved";
+    operation: string;
+    tier: 1 | 2;
+    reason: string;
+    context: Record<string, unknown>;
+    request_timestamp: string;
+    resolution?: {
+        decision: "approve" | "deny";
+        decided_at: string;
+        decided_by: string;
+    };
+    correlation_id: string;
+}) => void;
 declare class ApprovalGate {
     private policy;
     private baseline;
@@ -665,8 +741,16 @@ declare class ApprovalGate {
     private auditLog;
     private injectionDetector;
     private onInjectionAlert?;
+    private onApprovalEvent?;
     private proxyTierResolver?;
-    constructor(policy: PrincipalPolicy, baseline: BaselineTracker, channel: ApprovalChannel, auditLog: AuditLog, injectionDetector?: InjectionDetector, onInjectionAlert?: InjectionAlertCallback);
+    constructor(policy: PrincipalPolicy, baseline: BaselineTracker, channel: ApprovalChannel, auditLog: AuditLog, injectionDetector?: InjectionDetector, onInjectionAlert?: InjectionAlertCallback, onApprovalEvent?: ApprovalEventCallback);
+    /**
+     * Set the approval-event callback after construction. Used by the
+     * Upsilon-1 wire-up when the aggregator is constructed alongside the
+     * gate. The aggregator subscribes through this setter rather than the
+     * constructor so existing call sites continue to work unchanged.
+     */
+    setApprovalEventCallback(cb: ApprovalEventCallback | undefined): void;
     /**
      * Set the proxy tier resolver. Called after the proxy router is initialized.
      */
@@ -685,6 +769,13 @@ declare class ApprovalGate {
     private detectAnomaly;
     /**
      * Request approval from the human principal.
+     *
+     * Fail-closed contract (full-sweep #49): if the channel throws (network
+     * down, callback unreachable, dashboard SSE peer dropped, webhook DNS
+     * failure, etc.), the gate denies the operation and audit-logs the cause.
+     * Channel-internal timeouts already resolve with decision: "deny" per
+     * SEC-002; this catch covers the remaining "channel raised" path so an
+     * unhandled rejection cannot turn into an indeterminate state at the gate.
      */
     private requestApproval;
     /**
@@ -3537,7 +3628,7 @@ interface ExitBundleVerifierResult {
      * Coarse failure-class enum, when `passed` is false. Distinct from a free-text
      * error message so import commands can branch.
      */
-    failure_class?: "manifest_signature_invalid" | "manifest_unknown_version" | "manifest_signature_scheme_invalid" | "artifact_hash_mismatch" | "artifact_missing" | "artifact_size_mismatch" | "aggregate_hash_mismatch" | "artifact_path_unsafe" | "artifact_path_duplicate" | "artifact_path_escapes_root" | "archive_contains_symlink" | "private_material_present" | "other";
+    failure_class?: "manifest_signature_invalid" | "manifest_unknown_version" | "manifest_signature_scheme_invalid" | "artifact_hash_mismatch" | "artifact_missing" | "artifact_size_mismatch" | "aggregate_hash_mismatch" | "artifact_path_unsafe" | "artifact_path_duplicate" | "artifact_path_escapes_root" | "archive_contains_symlink" | "private_material_present" | "identity_signature_invalid" | "reputation_bundle_signature_invalid" | "reputation_attestation_signature_invalid" | "reputation_unverifiable_attestations" | "other";
 }
 
 /**
@@ -4104,21 +4195,35 @@ interface ExitCommandArgs {
 declare function runExitCommand(args: ExitCommandArgs): Promise<number>;
 
 /**
- * Sanctuary MCP Server — Principal Policy Loader
+ * Sanctuary MCP Server -- Principal Policy Loader
  *
  * Loads the Principal Policy from a YAML file at server startup.
- * The policy is immutable at runtime — no MCP tool can modify it.
+ * The policy is immutable at runtime -- no MCP tool can modify it.
  *
  * Security invariant:
  * - The policy is loaded ONCE at startup and frozen.
  * - No code path exists to modify the policy during a session.
  * - If no policy file exists, a sensible default is generated and saved.
+ * - If the policy file exists but is malformed, the server refuses to start
+ *   rather than silently substituting a default (operator intent preservation).
  */
 
+/**
+ * Thrown when a principal-policy.yaml file exists on disk but cannot be
+ * parsed or validated. Sanctuary refuses to substitute a default policy
+ * when an existing file is present, to avoid silently overriding operator
+ * intent.
+ */
+declare class MalformedPrincipalPolicyError extends Error {
+    readonly policyPath: string;
+    readonly reason: string;
+    constructor(policyPath: string, reason: string);
+}
 /**
  * Load the Principal Policy from disk.
  * If no policy file exists, generate the default and save it.
- * The returned policy is frozen — immutable at runtime.
+ * If the file exists but is malformed, throw MalformedPrincipalPolicyError.
+ * The returned policy is frozen -- immutable at runtime.
  */
 declare function loadPrincipalPolicy(storagePath: string): Promise<PrincipalPolicy>;
 
@@ -5045,6 +5150,171 @@ declare class OperatorChatStore {
     deleteThread(surface: OperatorChatSurface, threadKey: string): Promise<void>;
 }
 
+/**
+ * Sanctuary MCP Server — Concierge Memory Store (WP-V1.3-9 Tau-1)
+ *
+ * Per-fortress, encrypted-at-rest, cocoon-bound persistence for
+ * concierge conversation turns. Distinct from the v1.2 OperatorChatStore
+ * (single fortress-scoped thread, capped FIFO, no retention) — this
+ * store is the foundation for v1.3 conversational sovereignty depth:
+ * multi-thread enumeration, per-turn retention, scrollable history.
+ *
+ * Storage layout:
+ *   namespace: `_chat`                       (existing reserved L1 namespace)
+ *   key:       `concierge_memory.{thread_id}` (one record per thread)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialised turns bundle.
+ *   key:       `concierge-memory-store-v1` HKDF subkey of fortress master.
+ *   AAD:       UTF-8 bytes of `thread_id` — swapping records across
+ *              threads breaks the auth tag. Castle-walking discipline:
+ *              the encryption boundary holds even against on-disk shuffle.
+ *
+ * Concurrency:
+ * Per-thread async lock serializes appendTurn calls within the same
+ * store instance. Cross-process locking is out of scope (single-process
+ * Sanctuary server).
+ *
+ * Retention:
+ * Each turn carries an ISO-8601 `retention_until`. `pruneExpired()`
+ * iterates threads and drops turns whose retention_until is in the
+ * past. Empty bundles are deleted entirely. Caller wires this into
+ * the cocoon-unlock initialization path (the wiring layer fires it
+ * once the store is constructed).
+ *
+ * Multi-fortress isolation:
+ * The HKDF subkey is derived from the fortress master key. Two
+ * fortresses never produce identical encryption keys for identical
+ * thread_ids. The `fortress_id` field on each turn is metadata for
+ * audit clarity; isolation is enforced cryptographically.
+ */
+
+/** One turn in a concierge thread. */
+interface ConciergeTurn {
+    /** UUID of the thread this turn belongs to. */
+    thread_id: string;
+    /** Stable fortress id (audit metadata; isolation is keyed). */
+    fortress_id: string;
+    /** Monotonic turn number within thread, starting at 1. */
+    turn_id: number;
+    /** Sender role. */
+    role: "user" | "assistant";
+    /** Cleartext at runtime; AES-256-GCM at rest. */
+    content: string;
+    /** ISO-8601 timestamp of turn creation. */
+    created_at: string;
+    /** ISO-8601 timestamp after which prune drops this turn. */
+    retention_until: string;
+}
+/** Operator-facing summary surfaced by `listThreads`. */
+interface ConciergeThreadSummary {
+    thread_id: string;
+    created_at: string;
+    last_turn_at: string;
+    turn_count: number;
+}
+interface ConciergeMemoryStoreOptions {
+    /** Storage backend that persists the encrypted bundles. */
+    storage: StorageBackend;
+    /** 32-byte fortress master key. */
+    masterKey: Uint8Array;
+    /** Stable fortress id stamped on every turn for audit clarity. */
+    fortressId: string;
+    /** Operator-tunable retention window. Default 30 days. */
+    retentionDays?: number;
+}
+interface ReadThreadOptions {
+    /** Return only turns with turn_id strictly greater than this. */
+    sinceTurnId?: number;
+    /** Cap the number of turns returned (oldest-first within the bundle). */
+    limit?: number;
+}
+/**
+ * Stable failure-reason enum for `readThreadStrict` (WP-V1.3-9 Tau-2).
+ * Mirrors the shape carried by `operator_concierge_memory_read_failed`
+ * audit payloads so the service emits the cause verbatim.
+ */
+type ConciergeMemoryReadFailure = "decrypt_failed" | "schema_mismatch" | "oversize_bundle" | "io_failed" | "unknown";
+/**
+ * Discriminated result for `readThreadStrict`. The fold-read path uses
+ * this so an empty thread (no bundle) does not look the same as a
+ * corrupted bundle (which must trigger graceful degradation).
+ */
+type ReadThreadStrictResult = {
+    ok: true;
+    turns: ConciergeTurn[];
+} | {
+    ok: false;
+    reason: ConciergeMemoryReadFailure;
+};
+interface ListThreadsOptions {
+    /** Cap the number of summaries returned. */
+    limit?: number;
+}
+/**
+ * Encrypted, AAD-bound, retention-aware concierge memory persistence.
+ */
+declare class ConciergeMemoryStore {
+    private storage;
+    private encryptionKey;
+    private fortressId;
+    private retentionDays;
+    private locks;
+    constructor(opts: ConciergeMemoryStoreOptions);
+    /**
+     * Append a turn to the named thread, creating the bundle if no record
+     * exists. Returns the persisted turn (with assigned turn_id +
+     * retention_until). Per-thread serialisation guarantees turn_id
+     * monotonicity even under concurrent callers.
+     */
+    appendTurn(threadId: string, role: "user" | "assistant", content: string): Promise<ConciergeTurn>;
+    /**
+     * Read turns from a thread, oldest-first. Returns an empty array if
+     * the thread does not exist or its bundle is corrupt. Does not emit
+     * audit events; the caller (HTTP route handler) owns audit semantics.
+     */
+    readThread(threadId: string, opts?: ReadThreadOptions): Promise<ConciergeTurn[]>;
+    /**
+     * Read turns with explicit failure surfacing (WP-V1.3-9 Tau-2). Where
+     * `readThread` collapses every failure mode to an empty array, this
+     * variant returns a discriminated result so the multi-turn fold path
+     * can degrade cleanly + emit `operator_concierge_memory_read_failed`
+     * with a concrete cause.
+     *
+     * - No bundle on disk → `{ ok: true, turns: [] }` (a fresh thread).
+     * - Bundle present, decode + decrypt + schema check pass → ok with turns.
+     * - Bundle present, oversize → `{ ok: false, reason: "oversize_bundle" }`.
+     * - Bundle present, decryption fails → `{ ok: false, reason: "decrypt_failed" }`.
+     * - Bundle present, schema mismatch (version / thread_id) → `schema_mismatch`.
+     * - Storage IO error → `io_failed`.
+     */
+    readThreadStrict(threadId: string, opts?: ReadThreadOptions): Promise<ReadThreadStrictResult>;
+    /**
+     * Enumerate concierge threads in this fortress with summary metadata.
+     * Sorted newest-first by last_turn_at.
+     */
+    listThreads(opts?: ListThreadsOptions): Promise<ConciergeThreadSummary[]>;
+    /**
+     * Delete a thread's bundle. Returns true if the bundle existed and
+     * was removed; false if no bundle was present. Audit emission is the
+     * caller's responsibility.
+     */
+    deleteThread(threadId: string): Promise<boolean>;
+    /**
+     * Drop expired turns across all threads. Threads emptied by pruning
+     * are removed entirely. Returns the count of turns pruned.
+     */
+    pruneExpired(now?: Date): Promise<{
+        pruned: number;
+    }>;
+    private loadBundle;
+    private saveBundle;
+    /**
+     * Run `task` while holding the per-thread async lock. Lock is released
+     * once the task settles (success or failure). Generic helper so
+     * appendTurn / deleteThread / pruneExpired share serialisation.
+     */
+    private withLock;
+}
+
 /**
  * Sanctuary MCP Server — Operator Chat Service
  *
@@ -5146,6 +5416,51 @@ interface OperatorChatServiceDeps {
      * summary). Operator-tunable via dashboard config.
      */
     conciergeMaxTokens?: number;
+    /**
+     * WP-V1.3-9 Tau-1: optional foundation memory store. When wired,
+     * `sendConcierge` dual-writes each operator+concierge turn pair into
+     * the memory store under a session-scoped thread_id. Tau-2 adds a
+     * read-fold path that surfaces the prior turns to the substrate so
+     * the concierge maintains coherence across a multi-turn session.
+     *
+     * Omit at construction time to disable memory-side persistence; the
+     * existing `OperatorChatStore` write keeps working unchanged.
+     */
+    conciergeMemory?: ConciergeMemoryStore;
+    /**
+     * WP-V1.3-9 Tau-2: maximum prior turns folded into the substrate
+     * context per round-trip. Defaults to
+     * `DEFAULT_CONCIERGE_HISTORY_WINDOW_TURNS` (10). The current operator
+     * turn is always present; this caps history only.
+     */
+    conciergeHistoryWindowTurns?: number;
+    /**
+     * WP-V1.3-9 Tau-2: prior turns older than this many milliseconds are
+     * excluded from the active fold even when they remain on disk.
+     * Defaults to `DEFAULT_CONCIERGE_HISTORY_FRESHNESS_MS` (24h).
+     */
+    conciergeHistoryFreshnessMs?: number;
+    /**
+     * WP-V1.3-9 Tau-2: rough token budget for the prior-conversation
+     * portion of the substrate context. Estimated as ~4 chars per token.
+     * Defaults to `DEFAULT_CONCIERGE_HISTORY_TOKEN_BUDGET` (500). The
+     * static reference block + fortress sections are NOT subject to this
+     * budget; only the prior-conversation fold is pruned oldest-first.
+     */
+    conciergeHistoryTokenBudget?: number;
+    /**
+     * WP-V1.3-9 Tau-2: how long an active session may stay quiet before
+     * the next `sendConcierge` allocates a fresh thread_id. Defaults to
+     * `DEFAULT_CONCIERGE_SESSION_TTL_MS` (24h). Does not delete the prior
+     * thread; it remains readable through the memory store.
+     */
+    conciergeSessionTtlMs?: number;
+    /**
+     * Optional clock for the session-TTL + freshness checks. Tests inject
+     * a deterministic clock; production lets the default `Date.now`-based
+     * implementation run.
+     */
+    conciergeClock?: () => number;
 }
 declare class OperatorChatService {
     private store;
@@ -5155,6 +5470,27 @@ declare class OperatorChatService {
     private contextProviders?;
     private piiFilter?;
     private conciergeMaxTokens;
+    private memory?;
+    private historyWindowTurns;
+    private historyFreshnessMs;
+    private historyTokenBudget;
+    private sessionTtlMs;
+    private clock;
+    /**
+     * In-memory thread_id assigned to the active concierge session.
+     * The first sendConcierge call after construction allocates a fresh
+     * UUID; subsequent calls reuse it so multi-turn coherence (Tau-2)
+     * folds the prior turns into context. Cleared by `resetConciergeMemoryThread`.
+     */
+    private activeMemoryThreadId?;
+    /**
+     * Wall-clock ms of the most recent sendConcierge that touched the
+     * active session thread. Drives the WP-V1.3-9 Tau-2 session-TTL
+     * check: a fresh sendConcierge after `sessionTtlMs` of quiet
+     * allocates a new thread_id even though the prior one is still
+     * readable from the memory store.
+     */
+    private lastInteractionAt?;
     constructor(deps: OperatorChatServiceDeps);
     /**
      * Operator submit on the concierge surface. Persists the operator's
@@ -5167,11 +5503,47 @@ declare class OperatorChatService {
      * operator sees on the page (no silent dropping).
      */
     sendConcierge(query: string): Promise<ConciergeResponse>;
+    /**
+     * Emit the WP-V1.3-9 Tau-2 graceful-degradation audit event. Pulled
+     * out of `sendConcierge` so the read-fold path stays readable. Emits
+     * with `result: "failure"` since the concierge fell back to
+     * single-turn mode for this round-trip.
+     */
+    private emitMemoryReadFailed;
     /**
      * Read the persisted concierge thread, oldest message first. Returns
      * an empty array when no thread exists yet.
      */
     getConciergeHistory(): Promise<OperatorChatMessage[]>;
+    /**
+     * Whether the foundation memory store is wired. Routes use this to
+     * 503 cleanly when called against an unwired service.
+     */
+    hasConciergeMemory(): boolean;
+    /**
+     * List concierge memory threads, newest-first. Emits the
+     * `operator_concierge_history_read` audit event with `thread_id="*"`.
+     */
+    listConciergeMemoryThreads(opts?: ListThreadsOptions): Promise<ConciergeThreadSummary[]>;
+    /**
+     * Read a concierge memory thread, oldest turn first. Emits the
+     * `operator_concierge_history_read` audit event with the named
+     * thread_id and the count of turns surfaced.
+     */
+    readConciergeMemoryThread(threadId: string, opts?: ReadThreadOptions): Promise<ConciergeTurn[]>;
+    /**
+     * Delete a concierge memory thread. Emits
+     * `operator_concierge_thread_deleted` only when a bundle was actually
+     * removed; absent threads return false without an audit event.
+     */
+    deleteConciergeMemoryThread(threadId: string): Promise<boolean>;
+    /**
+     * Reset the active session memory thread. Subsequent sendConcierge
+     * calls allocate a fresh thread_id. Surfaced for tests + future "new
+     * conversation" affordance; not currently called by the dashboard.
+     */
+    resetConciergeMemoryThread(): void;
+    private ensureActiveMemoryThread;
     /**
      * Stitch fortress state into a single context blob the substrate
      * folds into its summarization prompt.
@@ -5184,6 +5556,11 @@ declare class OperatorChatService {
      *   ## Sanctuary reference
      *   <static domain reference block>
      *
+     *   ## Prior conversation             ← WP-V1.3-9 Tau-2, when present
+     *   OPERATOR: ...
+     *   CONCIERGE: ...
+     *   ---
+     *
      *   ## Recent activity
      *   <recentActivity output>
      *
@@ -5193,8 +5570,22 @@ declare class OperatorChatService {
      *   ## Open inbox
      *   <openInbox output>
      *   ```
+     *
+     * The substrate selector ships a `context: string` shape (not a
+     * messages array), so multi-turn coherence is folded as a structured
+     * prior-conversation section with explicit OPERATOR / CONCIERGE
+     * boundaries. Coordinator-CTO guidance: prefer messages-array shape
+     * if available; the v1.2 selector does not expose one, so structured
+     * serialization is the canonical path for v1.3.
      */
     private assembleConciergeContext;
+    /**
+     * Render the prior-conversation section with token-budget enforcement
+     * (WP-V1.3-9 Tau-2). Drops oldest turns first when the rendered
+     * section exceeds `historyTokenBudget`. Returns an empty string when
+     * the input is empty or when the budget excludes every turn.
+     */
+    private formatPriorTurnsSection;
     private emit;
 }
 
@@ -5603,6 +5994,15 @@ declare class HubService {
      * Read the persisted concierge thread.
      */
     getConciergeHistory(): Promise<OperatorChatMessage[]>;
+    /**
+     * Whether the operator-chat service has the WP-V1.3-9 memory store
+     * wired. Routes use this to 503 cleanly when the foundation memory
+     * surface is unavailable on a given fortress.
+     */
+    hasConciergeMemory(): boolean;
+    listConciergeMemoryThreads(opts?: ListThreadsOptions): Promise<ConciergeThreadSummary[]>;
+    readConciergeMemoryThread(threadId: string, opts?: ReadThreadOptions): Promise<ConciergeTurn[]>;
+    deleteConciergeMemoryThread(threadId: string): Promise<boolean>;
     /**
      * Open the click-to-inspect/approve panel for a wrapped agent. The
      * panel surfaces recent activity routed through this agent, pending
@@ -5669,6 +6069,268 @@ interface V11Bindings {
     operatorChatService?: OperatorChatService;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-10 Cross-Harness Approval Inbox Upsilon-1
+ *
+ * The aggregator is a passive subscriber to the existing ApprovalGate
+ * lifecycle. On each `gate-request` event it normalizes the payload into a
+ * stable `AggregatedApproval` record, dedupes against prior emissions of
+ * the same `(source_harness, source_agent_id, audit_log_entry_id)` tuple,
+ * persists the record under the reserved `_approval_aggregator` namespace,
+ * and exposes a query + resolve API.
+ *
+ * Scope of Upsilon-1:
+ *  - Aggregator module + storage + resolve API.
+ *  - Wired into the gate via an additive callback. The gate's blocking
+ *    deny/accept logic is unchanged; the aggregator never fails the gate
+ *    (callback exceptions are swallowed and audit-logged).
+ *  - HTTP route surface and three audit event names are owned by the
+ *    sibling `approval-aggregator-routes.ts` module + the gate wire-up.
+ *
+ * Out of scope (carries to Upsilon-2..4):
+ *  - Per-harness wrapped-agent approval-redirect mode.
+ *  - Operator decisions through the aggregator's HTTP `approve`/`deny`
+ *    routes flowing back to a blocked `channel.requestApproval()` call;
+ *    Upsilon-1 records the decision on the aggregator entry only.
+ *  - Provenance + replay UX.
+ *  - Mobile companion preview hook.
+ */
+
+/**
+ * Lifecycle status of an aggregated approval entry.
+ *  - `pending`: ingest fired, gate is awaiting a channel decision.
+ *  - `approved` / `denied`: gate's channel returned a decision OR the
+ *    operator resolved through the HTTP surface.
+ *  - `timeout`: the channel reported a timeout (decided_by ===
+ *    'channel_failure' OR explicit timeout reason).
+ *  - `expired`: pending past TTL on a `list()` poll without a resolution.
+ */
+type AggregatedApprovalStatus = "pending" | "approved" | "denied" | "timeout" | "expired";
+/**
+ * Normalized record the aggregator stores per approval. Field set is
+ * additive-stable; new fields go behind `?` so existing dashboards keep
+ * rendering unchanged. Raw request payloads are not stored on the record;
+ * only a SHA-256 hash and the original payload pulled separately via
+ * `getFullPayload()`.
+ */
+interface AggregatedApproval {
+    /** Stable per-fortress aggregator id (UUID v4). */
+    aggregator_id: string;
+    /** Harness the source approval came from (claude-code, cline, cursor, etc). */
+    source_harness: string;
+    /** Wrapped-agent identifier. Ed25519 pubkey hex or label. */
+    source_agent_id: string;
+    /**
+     * Audit-log entry id this approval correlates to. Used as the
+     * deduplication key alongside source_harness and source_agent_id.
+     * Format: `<iso-timestamp>:<operation>` so two different requests on the
+     * same operation in the same millisecond are still distinguishable.
+     */
+    audit_log_entry_id: string;
+    /** Policy rule that fired (`tier1_<operation>`, `tier2_<anomaly>`, etc.). */
+    policy_rule_id: string;
+    /** Operator-friendly one-line summary, derived from gate context. */
+    action_summary: string;
+    /** SHA-256 hex of the canonicalized request payload. */
+    request_payload_hash: string;
+    /** Lifecycle status. */
+    status: AggregatedApprovalStatus;
+    /** ISO 8601 timestamp the aggregator first ingested the request. */
+    created_at: string;
+    /** ISO 8601 timestamp the status left `pending`. */
+    resolved_at?: string;
+    /** Operator identity that resolved the entry, if applicable. */
+    resolved_by?: string;
+    /** ISO 8601 deadline. Defaults to created_at + DEFAULT_PENDING_TTL_MS. */
+    expires_at: string;
+    /**
+     * Optional cross-link to a v1.1 hub inbox item id. When set, the
+     * dashboard renderer SHOULD suppress the duplicate hub card so the
+     * operator sees one card per approval. Hub inbox surface is unchanged
+     * (the cross-link signal lives on the aggregator side only).
+     */
+    hub_inbox_item_id?: string;
+}
+/**
+ * Source-context resolver. Called once per ingest to map gate context to
+ * the aggregator's harness + agent_id fields. Default impl reads the
+ * fortress identity (single-agent fortresses) and returns `unknown` when
+ * the gate context does not name an agent.
+ */
+interface ApprovalSourceContext {
+    source_harness: string;
+    source_agent_id: string;
+}
+/**
+ * Event the gate emits per approval lifecycle transition.
+ */
+interface ApprovalGateEvent {
+    /** `requested` on initial gate entry; `resolved` when channel returns. */
+    phase: "requested" | "resolved";
+    /** Operation name from the policy gate. */
+    operation: string;
+    /** Tier the gate decided on. */
+    tier: 1 | 2;
+    /** Human-readable reason from the gate (audit log only; not user-facing). */
+    reason: string;
+    /** Sanitized context map the gate captured. */
+    context: Record<string, unknown>;
+    /** ISO 8601 timestamp the gate entered `requestApproval()`. */
+    request_timestamp: string;
+    /**
+     * On `resolved` only. Channel decision plus decided_by metadata. When
+     * `decision === 'deny'` and `decided_by === 'channel_failure'`, the
+     * aggregator records `status: 'timeout'` (Castle-walking discipline:
+     * fail-closed at the gate flows through to the inbox).
+     */
+    resolution?: {
+        decision: "approve" | "deny";
+        decided_at: string;
+        decided_by: string;
+    };
+    /**
+     * Stable correlation id the gate emits BOTH on `requested` and on
+     * `resolved`. The aggregator uses this to update the same entry on the
+     * resolution event. Format: `<iso-ms-timestamp>:<operation>:<random4>`.
+     */
+    correlation_id: string;
+}
+/**
+ * Listener subscription returned by `onEvent`. Call to unsubscribe.
+ */
+type ApprovalAggregatorUnsubscribe = () => void;
+/**
+ * Event emitted to subscribers. Mirrors the lifecycle transitions the
+ * aggregator records. SSE listeners surface these to the dashboard.
+ */
+interface ApprovalAggregatorEmit {
+    /**
+     * `aggregated` on first ingest, `resolved` on a status leaving pending,
+     * `deduped` when an ingest dropped because the same dedup key was seen.
+     */
+    type: "aggregated" | "resolved" | "deduped";
+    entry: AggregatedApproval;
+}
+/**
+ * Constructor dependencies. `pendingTtlMs` and `maxListLimit` default to
+ * coordinator-CTO defaults; tests pass overrides for deterministic timing.
+ */
+interface ApprovalAggregatorDeps {
+    storage: StorageBackend;
+    masterKey: Uint8Array;
+    auditLog: AuditLog;
+    /** Operator identity id. Recorded on the audit entries. */
+    identityId: string;
+    /** Stable fortress id. Drives the source-context default values. */
+    fortressId: string;
+    /** Optional override for the pending TTL. */
+    pendingTtlMs?: number;
+    /** Optional override for the maximum list limit. */
+    maxListLimit?: number;
+    /** Optional clock override for deterministic tests. Defaults to `() => new Date()`. */
+    now?: () => Date;
+    /** Optional source-context resolver. Defaults to fortress identifiers. */
+    resolveSourceContext?: (event: ApprovalGateEvent) => ApprovalSourceContext;
+    /**
+     * Optional cross-link resolver. Returns the v1.1 hub inbox item id that
+     * shadows the same approval, when known. Default returns undefined and
+     * the dashboard renders both surfaces. Upsilon-2 wires this through the
+     * hub inbox store.
+     */
+    resolveHubInboxItemId?: (event: ApprovalGateEvent) => string | undefined;
+}
+/**
+ * Aggregator state. The map is hydrated lazily from the encrypted
+ * namespace on first read; subsequent reads are served from memory.
+ */
+declare class ApprovalAggregator {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly auditLog;
+    private readonly identityId;
+    private readonly fortressId;
+    private readonly pendingTtlMs;
+    private readonly maxListLimit;
+    private readonly now;
+    private readonly resolveSourceContext;
+    private readonly resolveHubInboxItemId;
+    /** Cached entries by `aggregator_id`. */
+    private readonly entries;
+    /** Dedup index: `${harness}|${agent}|${audit_id}` -> aggregator_id. */
+    private readonly dedupIndex;
+    /** Correlation index: gate `correlation_id` -> aggregator_id. */
+    private readonly correlationIndex;
+    /** Original request payloads kept in-memory for `getFullPayload()`. */
+    private readonly fullPayloads;
+    /** Has the aggregator hydrated persisted entries on this process? */
+    private hydrated;
+    /** Active SSE listeners. */
+    private readonly listeners;
+    constructor(deps: ApprovalAggregatorDeps);
+    /**
+     * Subscribe an event listener. Returns an unsubscribe fn. SSE handlers
+     * use this to forward aggregator emissions to the dashboard.
+     */
+    onEvent(listener: (event: ApprovalAggregatorEmit) => void): ApprovalAggregatorUnsubscribe;
+    /**
+     * Ingest a gate event. Returns the aggregator entry on first sight,
+     * `null` when deduped. Resolution events update the existing record;
+     * unmatched resolutions are dropped silently (caller's gate emitted a
+     * resolved-without-requested pair, which the aggregator does not invent
+     * a record for).
+     */
+    ingest(event: ApprovalGateEvent): Promise<AggregatedApproval | null>;
+    /**
+     * List pending or recently resolved entries. Pending entries past TTL
+     * are lazily transitioned to `expired` and persisted before the list
+     * snapshot is returned.
+     */
+    list(opts?: {
+        status?: AggregatedApprovalStatus;
+        sinceTs?: string;
+        limit?: number;
+    }): Promise<AggregatedApproval[]>;
+    /**
+     * Return the original (unhashed) request payload for the entry. Returns
+     * `null` when the entry is unknown or the payload was evicted (e.g. the
+     * process restarted; payloads are in-memory only at v1.3 Upsilon-1).
+     */
+    getFullPayload(aggregatorId: string): Promise<unknown>;
+    /**
+     * Resolve an entry. Used by both:
+     *   1. The gate wire-up on channel-decision return.
+     *   2. The HTTP `approve`/`deny` routes when an operator clicks.
+     *
+     * Idempotent: resolving an already-resolved entry is a no-op (the record
+     * keeps its first decision and the audit log is not double-fired).
+     * Unknown ids throw `Error("approval-aggregator: not_found")` so HTTP
+     * routes return 404.
+     */
+    resolve(aggregatorId: string, decision: "approved" | "denied", operatorId: string): Promise<AggregatedApproval>;
+    private ingestRequested;
+    private ingestResolved;
+    /**
+     * Audit-log entry id for the dedup tuple. The audit log itself does not
+     * surface a stable per-entry id (counter-prefixed keys are internal); the
+     * aggregator uses the request timestamp + operation, which together pin
+     * the audit entry the gate appended on the same call.
+     */
+    private auditEntryIdForEvent;
+    private derivePolicyRuleId;
+    private deriveActionSummary;
+    /**
+     * Canonical SHA-256 of the request context. Sorted-keys serialization so
+     * identical payloads always hash the same, even when key insertion order
+     * varies. Defends against payload-replay smuggling (the aggregator can
+     * tell the same payload was seen twice without storing it cleartext).
+     */
+    private hashPayload;
+    private emit;
+    private expireStale;
+    private persist;
+    private hydrate;
+}
+
 /**
  * Sanctuary MCP Server — Principal Dashboard
  *
@@ -5758,6 +6420,14 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * regardless. Default route flip is deferred to v1.2.
      */
     private v11Bindings;
+    /**
+     * v1.3 WP-V1.3-10 Cross-Harness Approval Inbox aggregator. Mounted
+     * additively at `/api/approval-inbox/*` when set. Legacy approval
+     * routes at `/api/approvals/:id/(allow|deny)` continue to serve. The
+     * aggregator is a passive subscriber to the gate; the routes here are
+     * the operator-facing query / decision surface.
+     */
+    private approvalAggregator;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -5788,6 +6458,18 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Pass `null` to detach the bindings (used by tests and during shutdown).
      */
     setV11Bindings(bindings: V11Bindings | null): void;
+    /**
+     * v1.3 WP-V1.3-10 Upsilon-1: bind the cross-harness approval inbox
+     * aggregator. Once set, requests to `/api/approval-inbox/*` route
+     * through `handleApprovalInboxRoute`. Pass `null` to detach (used by
+     * tests + during shutdown).
+     */
+    setApprovalAggregator(aggregator: ApprovalAggregator | null): void;
+    /**
+     * v1.3 WP-V1.3-10 dispatch entry point. Called from `handleRequest`
+     * before the legacy approval route table. Returns true when served.
+     */
+    private dispatchApprovalInbox;
     /**
      * v1.1 dispatch entry point. Called from `handleRequest` before the
      * legacy route table. Returns true when the request was served by v1.1
@@ -6772,4 +7454,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, 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 };
+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, MalformedPrincipalPolicyError, 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 };