@sanctuary-framework/mcp-server 1.2.6 → 1.2.8

package/dist/index.d.ts

@@ -5315,27 +5315,204 @@ declare class ConciergeMemoryStore {
     private withLock;
 }
 
+/**
+ * Sanctuary MCP Server, Operator Chat, Concierge Query Grammar
+ *
+ * WP-V1.3-9 Tau-4 (criterion (d) of the v1.3 scope-lock revision). Builds
+ * on Tau-3 (PR #171, dynamic context router). The grammar layer parses
+ * operator queries into structured parameters: time ranges, agent names,
+ * event types, and a free-form intent residual. Tau-3 fetchers receive
+ * the parsed hints alongside the query so the substrate sees the most
+ * relevant data slice.
+ *
+ * The module is pure: rule-based extraction, no I/O, no clock side
+ * effects beyond the optional `now` parameter for deterministic tests.
+ * The optional LLM-assist fallback is invoked by the caller when the
+ * rule-based parser produces low confidence.
+ *
+ * Castle-walking discipline:
+ * - No new outbound surface; the LLM-assist fallback routes through the
+ *   substrate selector at the same `concierge` surface Tau-3 already
+ *   uses.
+ * - Encryption boundaries hold: this module receives plain strings
+ *   already produced inside the fortress.
+ * - Failure-mode handling is fail-soft: low-confidence parses surface a
+ *   structured fallback menu so the operator sees what the concierge
+ *   can answer, never a silent drop.
+ *
+ * Privacy invariant:
+ * The runtime `ParsedQuery` carries `intent_phrase` (free-form residual
+ * pulled from the operator's query) for the router's own consumption.
+ * The audit emission MUST NOT include `intent_phrase`; consumers serialize
+ * via `auditSafeSummary()` which strips it. See `OperatorConciergeChatPayload`
+ * safe-metadata invariant in `contracts/v1.2/operator-chat-events.ts`.
+ *
+ * Out of scope here (Tau-5 + later):
+ * - Agent-context awareness (proactive parsing without an explicit
+ *   query). Tau-4 parses off explicit query content only.
+ * - Voice input or natural-language-as-API surface (defer to v1.5+).
+ * - Cross-fortress concierge query (defer to v1.4 cross-tenant scope).
+ * - Window markers like "around the time of <event>" that require an
+ *   audit-log lookup to resolve. Tau-4 ships static patterns only.
+ */
+
+/**
+ * A resolved time range. `relative_label` carries the original token
+ * ("yesterday", "past hour", etc.) when the range was derived from a
+ * relative pattern, so consumers can render operator-readable copy.
+ */
+interface ParsedTimeRange {
+    start: Date;
+    end: Date;
+    relative_label?: string;
+}
+/**
+ * Stable structured-failure flags surfaced when the parser cannot
+ * resolve a token confidently. The strings are enum-like (no free text)
+ * so the audit emission stays safe-metadata-only and the dashboard can
+ * group by cause.
+ */
+type AmbiguityFlag = "unknown_time_token" | "unknown_agent_token" | "unknown_event_token" | "ambiguous_time_range" | "no_signal_extracted";
+/**
+ * Runtime parsed-query shape. Used by the router to thread parameters
+ * into context fetchers, and by the structured-fallback menu builder.
+ *
+ * `intent_phrase` is the residual after time/agent/event tokens are
+ * stripped, useful for router-level intent routing. It carries operator
+ * query content and MUST NOT be serialized into the audit log.
+ */
+interface ParsedQuery {
+    time_range: ParsedTimeRange | null;
+    agent_names: string[];
+    event_types: string[];
+    intent_phrase: string;
+    ambiguity_flags: AmbiguityFlag[];
+    /** 0..1; 1.0 = every component resolved cleanly. */
+    parse_confidence: number;
+}
+/**
+ * Read-only registry view consumed by `parseQuery` for agent-name
+ * extraction. The grammar matches operator query tokens against the
+ * `agent_id` field of each record (case-insensitive, prefix-or-exact).
+ *
+ * Wired from `HubAgentRegistrySource.list()` at the service layer; tests
+ * can hand a literal array. Both shapes are accepted so callers do not
+ * have to wrap a hub registry in an adapter just to feed the parser.
+ */
+type AgentRegistryView = readonly {
+    agent_id: string;
+}[] | {
+    list: () => readonly {
+        agent_id: string;
+    }[];
+};
+/**
+ * Optional LLM-assist completion. Invoked by `parseQueryWithLlmAssist`
+ * when the rule-based parse confidence is below `LLM_ASSIST_THRESHOLD`.
+ * The classifier sees the query plus the partial parse and may return
+ * `null` (no completion) or a partial-shape patch the caller merges.
+ *
+ * The runtime caller (operator-chat-service) MUST route this through
+ * the substrate selector at the `concierge` surface so no new outbound
+ * channel opens. See Castle-walking discipline at the top of the file.
+ */
+type LlmAssistGrammarCompletion = (query: string, partial: ParsedQuery) => Promise<Partial<{
+    time_range: ParsedTimeRange;
+    agent_names: string[];
+    event_types: string[];
+}> | null>;
+
+/**
+ * Sanctuary MCP Server, Operator Chat, Concierge Dynamic Context Router
+ *
+ * WP-V1.3-9 Tau-3 (criterion (c) of the v1.3 scope-lock revision). Builds
+ * on Tau-1 (PR #164, concierge memory store) and Tau-2 (PR #166, multi-turn
+ * coherence read-fold path). At each operator turn the concierge fetches
+ * live data relevant to the operator's query and folds it into context
+ * between the static Sanctuary reference and the prior-turns fold.
+ *
+ * Tau-4 (PR #_, criterion (d)) layers an operator-query grammar on top:
+ * the caller (`operator-chat-service`) parses the query into a
+ * `ParsedQuery` via `concierge-query-grammar`, threads the result into
+ * `classifyQuery` + `foldContext`, and the matches carry the parsed
+ * grammar through to fetchers as `FetcherHints` (time range + agent
+ * names + event types). Existing fetcher implementations that do not
+ * read the second argument continue to work unchanged.
+ *
+ * The module is intentionally pure: keyword classification + a small
+ * amount of hint extraction + a fold orchestrator that calls caller-
+ * provided fetchers. The wiring layer assembles the concrete fetchers
+ * (templates registry, agent registry, audit log, sentinel store, etc.)
+ * so this module stays test-isolatable and composable.
+ *
+ * Castle-walking discipline:
+ * - No new outbound surface; the optional auxiliary classifier is invoked
+ *   through the substrate selector by the caller (the service threads the
+ *   classifier callback through, this module never owns the channel).
+ * - Encryption boundaries hold for the underlying data sources; this
+ *   module receives plain strings already produced inside the fortress.
+ * - Failure-mode handling is fail-soft: a fetcher failure omits its
+ *   category from the fold and surfaces an audit event through the
+ *   caller's onFetcherFailure hook. The user-facing concierge query is
+ *   never broken by a context-assembly failure.
+ *
+ * Out of scope here (Tau-5):
+ * - Agent-context awareness (proactive folding without an explicit
+ *   query). The router still routes off explicit query content only.
+ */
+
 /**
  * Closed enum of categories the router may classify a query into. Adding
  * a category requires updating: this enum, the keyword table, the
  * fetcher interface, every wiring fetcher, and the test surface.
  */
 type ContextCategory = "templates" | "agent_state" | "agent_activity" | "audit_log" | "sentinel_findings" | "anomaly_alerts" | "recent_receipts" | "verascore_deltas";
+/**
+ * Structured hints passed to fetchers as the optional second argument
+ * (Tau-4). Derived from `ParsedQuery` by the router; fetchers are free
+ * to read or ignore individual fields. Tau-3 fetchers that take no
+ * second argument continue to work because the slot is optional.
+ */
+interface FetcherHints {
+    /** Time range derived from the operator's query, when one resolved. */
+    time_range?: {
+        start: Date;
+        end: Date;
+        relative_label?: string;
+    };
+    /**
+     * All agent names the parser matched against the registry, in the
+     * order they surfaced. Distinct from the `agentNameHint` first arg
+     * (which carries only the first match for back-compat).
+     */
+    agent_names?: readonly string[];
+    /**
+     * Event-type names the parser matched against the canonical audit-
+     * event-class enumeration. Already filtered to the closed set.
+     */
+    event_types?: readonly string[];
+}
 /**
  * Caller-supplied data sources. Each fetcher returns plain text the
  * router stitches into the rendered section. Returning the empty string
  * (or whitespace only) is treated as "nothing to fold for this category"
  * and the category drops out of the final categoriesIncluded list.
+ *
+ * Tau-4 extends every fetcher with an optional `hints?: FetcherHints`
+ * argument carrying the parsed-query attachments (time range, agent
+ * names, event types). Fetchers that ignore the argument continue to
+ * compile; fetchers that consume it can scope queries against the
+ * audit log, activity feed, etc., to the operator's stated window.
  */
 interface ContextFetchers {
-    templates: () => Promise<string>;
-    agent_state: (agentNameHint: string | null) => Promise<string>;
-    agent_activity: (agentNameHint: string | null) => Promise<string>;
-    audit_log: () => Promise<string>;
-    sentinel_findings: () => Promise<string>;
-    anomaly_alerts: () => Promise<string>;
-    recent_receipts: () => Promise<string>;
-    verascore_deltas: () => Promise<string>;
+    templates: (hints?: FetcherHints) => Promise<string>;
+    agent_state: (agentNameHint: string | null, hints?: FetcherHints) => Promise<string>;
+    agent_activity: (agentNameHint: string | null, hints?: FetcherHints) => Promise<string>;
+    audit_log: (hints?: FetcherHints) => Promise<string>;
+    sentinel_findings: (hints?: FetcherHints) => Promise<string>;
+    anomaly_alerts: (hints?: FetcherHints) => Promise<string>;
+    recent_receipts: (hints?: FetcherHints) => Promise<string>;
+    verascore_deltas: (hints?: FetcherHints) => Promise<string>;
 }
 /**
  * Auxiliary classifier the caller may supply for the LLM-assist fallback
@@ -5344,6 +5521,213 @@ interface ContextFetchers {
  */
 type LlmAssistClassifier = (query: string, categories: readonly ContextCategory[]) => Promise<ContextCategory | "none">;
 
+/**
+ * Sanctuary MCP Server, Operator Chat, Agent-Context Cache
+ *
+ * WP-V1.3-9 Tau-5 (criterion (e) of the v1.3 scope-lock revision; closes
+ * WP-V1.3-9 Conversational Sovereignty Depth). Builds on Tau-1 (memory
+ * persistence), Tau-2 (multi-turn coherence), Tau-3 (8-category dynamic
+ * context routing), and Tau-4 (operator-query grammar). Tau-5 ships
+ * proactive context awareness: the concierge knows which wrapped agents
+ * the operator runs, their templates, current work, recent audit-log
+ * activity, recent commitment chains, and recent Verascore deltas, and
+ * folds that snapshot into every chat round-trip plus a starter
+ * suggestion when a fresh thread opens.
+ *
+ * Architecture:
+ *
+ * - The cache is per-fortress: one `AgentContextCache` instance per
+ *   `OperatorChatService` instance. The service-construction layer in
+ *   `dashboard/v1_1/wiring.ts` wires the cache to the same agent
+ *   registry + audit log it already passes to the Tau-3 fetchers, so
+ *   data sources align across both surfaces.
+ *
+ * - Refresh is lazy: `refresh()` returns the latest snapshot list and
+ *   updates the in-memory cache. `read()` is a synchronous accessor for
+ *   the latest cached snapshot (returns `[]` until the first refresh
+ *   resolves).
+ *
+ * - Cadence: callers schedule refreshes via `start()` (60-second timer)
+ *   and trigger an explicit refresh on cocoon-unlock by calling
+ *   `refresh()` once at construction. Tests can opt out of the timer
+ *   by leaving `start()` uncalled.
+ *
+ * Castle-walking discipline:
+ *
+ * - No new outbound surface. The cache reads server-local data only:
+ *   the agent registry (in-memory) and the audit log (encrypted under
+ *   L1 master key at rest). Optional Verascore receipt cache is read
+ *   through a caller-provided source; absent, the verascore field
+ *   degrades to null, never to an outbound HTTP call.
+ *
+ * - Encryption boundary held: the cache holds plain text already
+ *   produced inside the fortress. Audit-log decryption happens inside
+ *   the audit-log subsystem, not here.
+ *
+ * - Failure-mode handling is fail-soft: a refresh that throws (audit
+ *   log read error, registry contention, oversize bundle) leaves the
+ *   prior snapshot list intact and returns `[]` from the failed
+ *   refresh. The caller can emit an audit event; the concierge
+ *   degrades gracefully to no agent-state section. The user-facing
+ *   query is never broken by a cache-refresh failure.
+ *
+ * Privacy invariant:
+ *
+ * Snapshots carry agent_id, harness, template, and aggregate counts.
+ * They MUST NOT carry raw audit-log slices, raw operator queries, or
+ * raw secret material. Counts are integers; current_work_summary is a
+ * stable enum-derived string ("performed policy_change", "wrote to
+ * state"); state_flags is a closed enum. The "Current agent state"
+ * section the concierge renders into the substrate prompt aggregates
+ * those fields only.
+ *
+ * Out of scope here (v1.4+ and later):
+ *
+ * - Cross-fortress agent state aggregation (v1.4 cross-tenant scope).
+ * - Concierge-driven action execution (operator: "fix Cursor's
+ *   session"). Defer to v1.5+ pending approval-flow trust model.
+ * - Advanced ML-backed state inference (per-operator agent-state norms).
+ *   Defer to v1.5+; out of scope for v1.3.
+ */
+
+/**
+ * Stable enum of agent state flags surfaced into the substrate prompt
+ * and the proactive-suggestion trigger. The order in `STATE_FLAG_ORDER`
+ * encodes urgency: flags earlier in the list rank higher when the
+ * prompt-section pruner has to drop low-urgency agents to fit budget.
+ */
+type AgentStateFlag = "stuck" | "has_pending_approvals" | "has_open_findings" | "active" | "idle";
+/**
+ * One snapshot entry per wrapped agent. Stable shape so the prompt
+ * formatter and the proactive-suggestion generator can read off the
+ * same data without re-fetching from the registry.
+ *
+ * Counts (`recent_audit_count_24h`, `recent_egress_count_24h`,
+ * `recent_concordia_receipts_count_24h`) are integers derived from the
+ * last-24h slice of the audit log. `recent_verascore_delta_24h` is
+ * `null` when the optional Verascore source is not wired or returned
+ * no delta.
+ */
+interface AgentContextSnapshot {
+    agent_id: string;
+    agent_name: string;
+    template: string;
+    last_activity_at: string | null;
+    current_work_summary: string | null;
+    recent_audit_count_24h: number;
+    recent_egress_count_24h: number;
+    recent_concordia_receipts_count_24h: number;
+    recent_verascore_delta_24h: number | null;
+    state_flags: AgentStateFlag[];
+}
+/**
+ * Optional source for the Verascore reputation delta surface. v1.0
+ * Sanctuary does not currently expose a queryable Verascore receipt
+ * cache server-side; the source is wired in on Verascore-bridge-aware
+ * deployments and absent everywhere else. When absent, the snapshot's
+ * `recent_verascore_delta_24h` field is null. The concierge functions
+ * fully without it (non-dependency invariant).
+ */
+interface VerascoreDeltaSource {
+    /**
+     * Return the most-recent 24h reputation delta for this agent, or
+     * null when no delta is available. Implementations MUST be fast
+     * (server-local, no outbound) so the cache refresh stays bounded.
+     */
+    read(agentId: string): number | null;
+}
+/**
+ * One handler registration's removal callback.
+ */
+type AgentContextChangeUnsubscribe = () => void;
+interface AgentContextCacheDeps {
+    /** Operator identity that owns the agents this cache aggregates over. */
+    identityId: string;
+    /** Source of agent records, scoped to this operator's identity. */
+    agentRegistry: HubAgentRegistrySource;
+    /** Audit log used to derive recent-activity counts and state flags. */
+    auditLog: AuditLog;
+    /** Optional Verascore delta source. When absent, deltas degrade to null. */
+    verascoreSource?: VerascoreDeltaSource;
+    /** Hook invoked when a refresh throws. Defaults to a no-op. */
+    onRefreshError?: (error: unknown) => void;
+    /** Deterministic clock for tests. Defaults to `Date.now`. */
+    clock?: () => number;
+    /** Refresh cadence in ms. Defaults to 60_000. */
+    refreshCadenceMs?: number;
+    /**
+     * Window in ms used to derive 24h counts. Defaults to 24h. Tunable
+     * for tests so they can simulate older entries falling out of the
+     * window without manipulating the clock.
+     */
+    windowMs?: number;
+}
+/**
+ * Per-fortress in-memory cache of agent context snapshots. See
+ * file-level docstring for the invariants this class upholds.
+ */
+declare class AgentContextCache {
+    private readonly identityId;
+    private readonly agentRegistry;
+    private readonly auditLog;
+    private readonly verascoreSource;
+    private readonly onRefreshError;
+    private readonly clock;
+    private readonly cadenceMs;
+    private readonly windowMs;
+    private snapshots;
+    private observers;
+    private timer;
+    private inFlight;
+    constructor(deps: AgentContextCacheDeps);
+    /**
+     * Run the refresh cycle. Returns the new snapshot list (which is
+     * also stored as the cache state). On error, the prior snapshots
+     * are kept and the resolved promise carries `[]`. The error is
+     * dispatched to the `onRefreshError` hook so the caller can audit-
+     * emit a degradation event.
+     */
+    refresh(): Promise<AgentContextSnapshot[]>;
+    /**
+     * Synchronous read of the latest cached snapshot list. Returns `[]`
+     * until the first `refresh()` resolves, or after a failure that left
+     * the cache empty.
+     */
+    read(): AgentContextSnapshot[];
+    /**
+     * Subscribe to refresh notifications. The handler fires once per
+     * successful refresh with the new snapshot list. Returns an
+     * unsubscribe callback the caller invokes on teardown.
+     */
+    observeChanges(handler: (snapshots: AgentContextSnapshot[]) => void): AgentContextChangeUnsubscribe;
+    /**
+     * Start the periodic refresh timer. Idempotent. Tests typically do
+     * not call this and trigger refreshes manually.
+     */
+    start(): void;
+    /**
+     * Stop the periodic refresh timer. Idempotent.
+     */
+    stop(): void;
+    private notifyObservers;
+}
+/**
+ * Stable enum of the trigger classes the starter generator surfaces.
+ * Carried into the audit emission so dashboards can group by cause.
+ */
+type ProactiveStarterTrigger = "stuck_agent" | "pending_approvals" | "open_findings" | "all_idle";
+interface ConciergeProactiveStarter {
+    text: string;
+    trigger: ProactiveStarterTrigger;
+    /**
+     * How many agents contributed to this trigger. For `stuck_agent` and
+     * `open_findings` this is the count of agents in that state; for
+     * `pending_approvals` it is the count of agents with pending; for
+     * `all_idle` it is the total agent count.
+     */
+    triggered_agents_count: number;
+}
+
 /**
  * Sanctuary MCP Server — Operator Chat Service
  *
@@ -5514,6 +5898,41 @@ interface OperatorChatServiceDeps {
      * Defaults to `DEFAULT_CONCIERGE_DYNAMIC_CONTEXT_BUDGET` (2000).
      */
     conciergeDynamicContextBudget?: number;
+    /**
+     * WP-V1.3-9 Tau-4: read-only registry view consumed by the operator-
+     * query grammar to extract agent-name parameters. Wired from
+     * `HubAgentRegistrySource.list()` at the hub-service layer; absent
+     * services skip agent-name extraction (the grammar still resolves
+     * time ranges and event types). The registry is read at every
+     * `sendConcierge` call so newly-wrapped agents are visible without
+     * service reconstruction.
+     */
+    conciergeAgentRegistry?: AgentRegistryView;
+    /**
+     * WP-V1.3-9 Tau-4: optional LLM-assist completion for low-confidence
+     * grammar parses. When wired alongside the substrate selector, the
+     * service routes the call through the substrate selector at the
+     * `concierge` surface, so the grammar fallback shares the operator's
+     * substrate choice and never opens a new outbound surface. Distinct
+     * from `conciergeContextLlmAssist`, which classifies queries into
+     * fetcher categories; this hook completes structured grammar fields.
+     */
+    conciergeGrammarLlmAssist?: LlmAssistGrammarCompletion;
+    /**
+     * WP-V1.3-9 Tau-5: caller-supplied agent-context cache. When wired
+     * alongside the substrate selector, every `sendConcierge` round-trip
+     * folds a "Current agent state" section into the substrate prompt
+     * (between the dynamic-context fold and the prior-conversation
+     * fold), and `getProactiveStarter()` surfaces a fresh-thread starter
+     * based on the cache state. Omit to disable agent-context awareness;
+     * the rest of the concierge surface keeps working unchanged.
+     */
+    conciergeAgentContextCache?: AgentContextCache;
+    /**
+     * WP-V1.3-9 Tau-5: rough token budget for the "Current agent state"
+     * section. Defaults to `DEFAULT_CONCIERGE_AGENT_STATE_BUDGET` (400).
+     */
+    conciergeAgentStateBudget?: number;
 }
 declare class OperatorChatService {
     private store;
@@ -5532,6 +5951,17 @@ declare class OperatorChatService {
     private contextFetchers?;
     private contextLlmAssist?;
     private dynamicContextBudget;
+    private agentRegistry?;
+    private grammarLlmAssist?;
+    private agentContextCache?;
+    private agentStateBudget;
+    /**
+     * Per-thread guard so the proactive starter fires at most once per
+     * fresh thread. Tracks the thread_id the starter was last offered
+     * for; subsequent `getProactiveStarter()` calls within the same
+     * thread return null instead of re-emitting.
+     */
+    private starterOfferedForThreadId?;
     /**
      * In-memory thread_id assigned to the active concierge session.
      * The first sendConcierge call after construction allocates a fresh
@@ -5597,8 +6027,37 @@ declare class OperatorChatService {
      * 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.
+     *
+     * Tau-5: also clears the proactive-starter guard so the next
+     * `getProactiveStarter()` call against the freshly-allocated thread
+     * is eligible to fire.
      */
     resetConciergeMemoryThread(): void;
+    /**
+     * WP-V1.3-9 Tau-5: surface a proactive starter for the current
+     * concierge session. Intended to be called by the dashboard UI when
+     * the operator opens the chat surface, before any operator typing.
+     *
+     * Returns null when:
+     * - No agent-context cache is wired (Tau-5 disabled).
+     * - No concierge memory store is wired (no thread_id namespace).
+     * - The cache snapshot has no signal (empty fortress).
+     * - A starter has already been offered for the active thread (the
+     *   guard ensures one starter per fresh thread).
+     *
+     * Side effects:
+     * - Allocates a fresh thread_id if none is active.
+     * - Emits the `operator_concierge_proactive_suggestion_offered`
+     *   audit event with the trigger class + triggered_agents_count.
+     * - Records the offered thread_id so the next call within the same
+     *   thread is a no-op.
+     *
+     * The returned starter's `text` is operator-visible copy; the
+     * dashboard renders it as a system-message-style starter the
+     * operator can accept (clicks/types follow-up) or dismiss (types a
+     * new query).
+     */
+    getProactiveStarter(): ConciergeProactiveStarter | null;
     private ensureActiveMemoryThread;
     /**
      * Stitch fortress state into a single context blob the substrate
@@ -5646,8 +6105,20 @@ declare class OperatorChatService {
      * proceeds with no fold. Returns the rendered section + the list of
      * categories whose data made it into the section (used for the
      * round-trip audit emission).
+     *
+     * Tau-4: receives the pre-parsed `ParsedQuery` and forwards it as the
+     * `parsed` opt to `foldContext`, so fetchers see the structured
+     * `FetcherHints` derived from it.
      */
     private runDynamicContextFold;
+    /**
+     * WP-V1.3-9 Tau-4: parse the (PII-filtered) operator query into a
+     * `ParsedQuery`. Routes through the LLM-assist completion hook when
+     * configured and the rule-based parse is below
+     * `LLM_ASSIST_THRESHOLD`. Always returns a parse object (never
+     * throws) so the audit emission can carry the result unconditionally.
+     */
+    private runGrammarParse;
     /**
      * Emit the WP-V1.3-9 Tau-3 fetcher-failure audit event. Pulled out
      * of the fold path so the dynamic-context handler stays readable.
@@ -6329,6 +6800,22 @@ interface AggregatedApproval {
      * Upsilon-3.
      */
     enforcement_chain?: EnforcementLayerEvent[];
+    /**
+     * Aggregator revision number stamped at entry creation. Stable across
+     * status transitions. Used by the v1.4 mobile companion sync API to
+     * separate "added" from "changed" deltas (created_at_revision >
+     * sinceRevision means added; otherwise it is a status change).
+     * v1.3 Upsilon-4.
+     */
+    created_at_revision?: number;
+    /**
+     * Aggregator revision number stamped at the last mutation (creation,
+     * resolution, expiration). Sync-API consumers compare against the
+     * revision they last saw to compute the delta. Monotonically
+     * increasing per fortress; gaps are normal (one bump per mutation).
+     * v1.3 Upsilon-4.
+     */
+    last_modified_revision?: number;
 }
 /**
  * Source-context resolver. Called once per ingest to map gate context to
@@ -6385,11 +6872,35 @@ type ApprovalAggregatorUnsubscribe = () => void;
 interface ApprovalAggregatorEmit {
     /**
      * `aggregated` on first ingest, `resolved` on a status leaving pending,
-     * `deduped` when an ingest dropped because the same dedup key was seen.
+     * `deduped` when an ingest dropped because the same dedup key was seen,
+     * `removed` when an entry was pruned (v1.3 Upsilon-4).
      */
-    type: "aggregated" | "resolved" | "deduped";
+    type: "aggregated" | "resolved" | "deduped" | "removed";
     entry: AggregatedApproval;
 }
+/**
+ * Sync-API delta returned by `getSync()`. v1.3 Upsilon-4. Mobile
+ * companions poll this for cheap state-sync without re-fetching the
+ * full inbox. The `revision` field on the response is the aggregator's
+ * current revision; pass it back as `sinceRevision` on the next call.
+ *
+ * `added` carries entries created after `sinceRevision`. `changed`
+ * carries entries that existed at `sinceRevision` but have transitioned
+ * status (resolved, expired) since. `removed` carries the
+ * aggregator_ids of entries pruned after `sinceRevision`.
+ *
+ * Tombstone caveat: removal tombstones live in-process memory. Server
+ * restart clears them. Mobile clients reconnecting after the server
+ * restarted MUST re-bootstrap from `list()` rather than rely on the
+ * sync delta. The v1.4 mobile companion build wires the bootstrap-on-
+ * reconnect flow; v1.3 documents the constraint.
+ */
+interface ApprovalAggregatorSyncDelta {
+    revision: number;
+    added: AggregatedApproval[];
+    changed: AggregatedApproval[];
+    removed: string[];
+}
 /**
  * Constructor dependencies. `pendingTtlMs` and `maxListLimit` default to
  * coordinator-CTO defaults; tests pass overrides for deterministic timing.
@@ -6464,12 +6975,63 @@ declare class ApprovalAggregator {
     private hydrated;
     /** Active SSE listeners. */
     private readonly listeners;
+    /**
+     * Monotonic revision counter, bumped on every mutation (ingest of new
+     * entry, resolve, expire, delete). Hydrated from max(last_modified_revision)
+     * across persisted entries on first read; in-memory after that. v1.3
+     * Upsilon-4.
+     */
+    private currentRevision;
+    /**
+     * Removal tombstones: aggregator_id -> revision at removal. Used by the
+     * sync API to surface "removed" entries to mobile consumers between
+     * polls. In-memory only; server restart clears tombstones (mobile
+     * bootstraps via `list()` on reconnect). v1.3 Upsilon-4.
+     */
+    private readonly removedTombstones;
     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;
+    /**
+     * Current aggregator revision. v1.3 Upsilon-4. Mobile companions
+     * poll the lightweight `/revision` route to detect that something
+     * changed before fetching a full sync delta.
+     */
+    getRevision(): Promise<number>;
+    /**
+     * Compute a delta since `sinceRevision`. v1.3 Upsilon-4. Mobile
+     * clients poll this for cheap state-sync. Behavior:
+     *  - `added`: entries whose `created_at_revision > sinceRevision`.
+     *  - `changed`: entries that existed at `sinceRevision` but had a
+     *    status transition (resolve, expire) since.
+     *  - `removed`: aggregator_ids deleted after `sinceRevision`.
+     *  - `revision`: current aggregator revision; pass this back as
+     *    `sinceRevision` on the next call.
+     *
+     * `limit` caps the total count returned across all three lists,
+     * prioritized as added -> changed -> removed (newer-state first).
+     * When more changes exist than fit, the next call with the returned
+     * revision will pick up the rest because each entry's
+     * last_modified_revision is unchanged by truncation.
+     */
+    getSync(opts?: {
+        sinceRevision?: number;
+        limit?: number;
+    }): Promise<ApprovalAggregatorSyncDelta>;
+    /**
+     * Delete an entry. Drops the in-memory record, the persisted bundle,
+     * and the at-rest payload (if a payload store is wired). Records a
+     * tombstone with the new revision so sync-API consumers see a
+     * `removed` delta. Returns true when an entry was deleted, false on
+     * unknown id. v1.3 Upsilon-4. Reserved for v1.4+ retention housekeeping;
+     * Upsilon-4 ships the surface so mobile sync-API tests can exercise the
+     * removal path.
+     */
+    deleteEntry(aggregatorId: string): Promise<boolean>;
+    private nextRevision;
     /**
      * Ingest a gate event. Returns the aggregator entry on first sight,
      * `null` when deduped. Resolution events update the existing record;
@@ -6567,6 +7129,385 @@ declare class ApprovalAggregator {
     private hydrate;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Baseline Pack (Castle Layer 2 anchor)
+ *
+ * Shared types for the Sentinel observation surface.
+ *
+ * Castle-walking discipline:
+ *  - Castle Layer 1 (Castle Wall) blocks unauthorized egress at the kernel
+ *    boundary. That is the enforcement layer.
+ *  - Castle Layer 2 (Sentinels) observes server-local data only and surfaces
+ *    anomalies. NO outbound network. NO blocking. Findings flow into the
+ *    operator surface they already check.
+ *  - Castle Layer 3 (Cooperative MCP) is the agent contract. Sentinels do
+ *    not wrap agent tools and do not negotiate with agents.
+ *
+ * Phi-1 ships the framework + the egress-volume watcher. Phi-2 through
+ * Phi-5 add credential-usage, cross-agent-chatter, suspicious-tool-call,
+ * and anomaly-trigger sentinels against this same shape.
+ */
+
+/** Severity tier returned by `Sentinel.evaluate()`. */
+type SentinelSeverity = "info" | "warn" | "alert";
+/**
+ * Read-only context handed to every sentinel on subscribe + evaluate.
+ * Sentinels do NOT receive a writable storage handle and do NOT receive
+ * an outbound HTTP client. The substrate selector is the single
+ * outbound-capable surface; Phi-1 sentinels do not exercise it but
+ * Phi-2/3/4/5 may want to invoke a local LLM for reasoning.
+ */
+interface SentinelContext {
+    /** Stable per-fortress identifier; multi-fortress isolation pivot. */
+    fortressId: string;
+    /** Audit log read API. Sentinels MUST NOT call append() through this. */
+    auditLog: AuditLog;
+    /** Optional substrate selector for LLM-backed reasoning. v1.3 Phi-1 unused. */
+    substrateSelector?: SubstrateSelector;
+    /** Wall-clock provider. Tests inject a deterministic clock. */
+    now: () => Date;
+}
+/**
+ * One observation a sentinel produced. Persisted under the sentinel
+ * findings store + emitted as an audit event +
+ * surfaced to the operator dashboard.
+ */
+interface SentinelFinding {
+    /** Stable per-fortress finding id (UUID v4). */
+    finding_id: string;
+    /** Identifier of the sentinel that produced this finding. */
+    sentinel_id: string;
+    severity: SentinelSeverity;
+    /**
+     * Optional agent-id this finding pertains to. Absent when the finding
+     * is fortress-wide (e.g. cross-agent chatter spike).
+     */
+    agent_id?: string;
+    /** Operator-friendly one-liner. Truncated to 240 chars on persist. */
+    summary: string;
+    /**
+     * Structured payload. Schema varies per sentinel but every payload is
+     * a flat record of JSON-serializable values.
+     */
+    details: Record<string, unknown>;
+    /** ISO 8601 timestamp at evaluation time. */
+    observed_at: string;
+    /**
+     * Audit-log entries that triggered this finding. Sentinels populate
+     * with `${entry.timestamp}:${entry.operation}` tuples (mirrors the
+     * aggregator's audit_log_entry_id shape from Upsilon-1).
+     */
+    evidence_audit_ids: string[];
+    /** Stable fortress id stamped at emit. Multi-fortress isolation pivot. */
+    fortress_id: string;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel base class.
+ *
+ * Subclass to add a new sentinel. The dispatcher schedules `evaluate()`
+ * on a tick. `subscribe()` is called once when an operator opts in;
+ * `unsubscribe()` is called once when they opt out (or the fortress is
+ * disposed). Sentinels MUST treat the SentinelContext as read-only.
+ */
+
+/**
+ * Concrete sentinels implement these three methods and stamp a
+ * sentinel_id. Implementations must:
+ *  - Be pure with respect to the SentinelContext (no writable
+ *    storage, no external network).
+ *  - Return findings synchronously deterministically given the same
+ *    context state.
+ *  - Tolerate empty audit logs (return []).
+ */
+declare abstract class Sentinel {
+    /**
+     * Stable identifier. Used as the dictionary key in the registry, the
+     * URL path component, and the audit-log details payload's
+     * `sentinel_id` field. Convention: lowercase, dash-separated, prefix
+     * with the sentinel category (e.g. `egress-volume`,
+     * `credential-usage`).
+     */
+    abstract readonly sentinelId: string;
+    /**
+     * Human-readable description shown in the operator dashboard's
+     * "available sentinels" list. Should answer "what does this watch?"
+     * in one sentence.
+     */
+    abstract readonly description: string;
+    /**
+     * Bind the sentinel to a fortress context. Called once on
+     * subscribe. Default implementation stores the context on `this`;
+     * sentinels that need additional setup (e.g. priming a baseline
+     * cache) override.
+     */
+    subscribe(context: SentinelContext): Promise<void>;
+    /**
+     * Tear down. Default implementation clears the context; subclasses
+     * that hold timers or external handles override.
+     */
+    unsubscribe(): Promise<void>;
+    /**
+     * Compute findings against the current audit-log + agent-state
+     * snapshot. Returns an empty array when nothing notable is observed.
+     * Throwing is allowed; the dispatcher catches and emits a
+     * `sentinel_evaluation_failed` audit event.
+     */
+    abstract evaluate(): Promise<SentinelFinding[]>;
+    protected context: SentinelContext | undefined;
+    /** Internal helper: assert subscribed before evaluation. */
+    protected requireContext(): SentinelContext;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Registry.
+ *
+ * Tracks two things for one fortress:
+ *  1. The catalog of sentinel CLASSES the fortress can subscribe to
+ *     (registered at process boot).
+ *  2. Which sentinels the operator has actually opted IN.
+ *
+ * Default subscription set is empty: the operator must opt in. This
+ * keeps the no-outbound-by-default rule and the "operator pulls
+ * features" UX pattern from CLAUDE.md.
+ *
+ * Multi-fortress isolation: one registry instance per fortress. The
+ * dispatcher consults the registry and never crosses fortress
+ * boundaries.
+ */
+
+interface SentinelCatalogEntry {
+    sentinelId: string;
+    description: string;
+    factory: () => Sentinel;
+}
+/**
+ * Coordinator-CTO defaults: the registry ships with the Phi-1 catalog
+ * pre-loaded but with zero subscriptions. Tests inject custom catalogs
+ * via `register()`.
+ */
+declare class SentinelRegistry {
+    private readonly catalog;
+    private readonly subscribed;
+    register(entry: SentinelCatalogEntry): void;
+    /**
+     * Available sentinels (catalog view). Operator UI lists this so the
+     * operator can pick what to subscribe to.
+     */
+    listCatalog(): Array<{
+        sentinelId: string;
+        description: string;
+    }>;
+    /** Currently subscribed sentinel ids. */
+    listSubscribed(): string[];
+    /** Has the fortress opted into this sentinel? */
+    isSubscribed(sentinelId: string): boolean;
+    /**
+     * Subscribe a sentinel to a fortress context. Idempotent: a second
+     * subscribe call on an already-subscribed sentinel returns the
+     * existing instance without re-running `subscribe()`.
+     */
+    subscribe(sentinelId: string, context: SentinelContext): Promise<Sentinel>;
+    /**
+     * Unsubscribe. Idempotent: unsubscribing an unsubscribed sentinel
+     * returns false without throwing. Returns true when an active
+     * subscription was torn down.
+     */
+    unsubscribe(sentinelId: string): Promise<boolean>;
+    /**
+     * Snapshot of subscribed sentinels for the dispatcher's tick path.
+     * Returned as an array so the dispatcher can iterate without holding
+     * the map under modification.
+     */
+    snapshotSubscribed(): Array<{
+        sentinelId: string;
+        sentinel: Sentinel;
+    }>;
+    /**
+     * Tear down every subscription. Called by the dispatcher on
+     * fortress-shutdown. Best-effort: a failing unsubscribe does not
+     * abort the rest.
+     */
+    unsubscribeAll(): Promise<void>;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Finding Store.
+ *
+ * Encrypted at-rest persistence for sentinel findings. Sibling to the
+ * Upsilon-3 aggregator-store: same fortress-master-key-derived HKDF
+ * subkey shape, AAD-bound to the finding_id, retention-aware.
+ *
+ * Storage layout:
+ *   namespace: `_sentinel_findings`
+ *   key:       `finding.{finding_id}` (one record per finding)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialized record.
+ *   key:       `l2-sentinel-finding-v1` HKDF subkey of fortress master.
+ *   AAD:       UTF-8 bytes of `finding_id`.
+ *
+ * Multi-fortress isolation: HKDF subkey derives from the fortress
+ * master key. Two fortresses never produce identical encryption keys
+ * for identical finding_ids.
+ *
+ * Retention: 30 days default, mirroring the audit-log envelope and the
+ * aggregator payload store.
+ */
+
+interface SentinelFindingStoreOptions {
+    storage: StorageBackend;
+    masterKey: Uint8Array;
+    fortressId: string;
+    /** Operator-tunable retention window. Default 30 days. */
+    retentionDays?: number;
+    /** Wall-clock provider for deterministic tests. */
+    now?: () => Date;
+}
+declare class SentinelFindingStore {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly fortressId;
+    private readonly retentionDays;
+    private readonly now;
+    constructor(opts: SentinelFindingStoreOptions);
+    /**
+     * Persist a finding. Truncates the operator-visible summary to
+     * SENTINEL_SUMMARY_MAX_CHARS so the dashboard render stays bounded.
+     * Returns the retention deadline so callers can audit it.
+     */
+    saveFinding(finding: SentinelFinding): Promise<string>;
+    /** Load a single finding by id, or null when absent / corrupted. */
+    loadFinding(findingId: string): Promise<SentinelFinding | null>;
+    /**
+     * List findings, newest first. Optional filters: since (ISO 8601),
+     * severity, sentinel_id, agent_id, limit. Default limit 100.
+     */
+    listFindings(opts?: {
+        since?: string;
+        severity?: SentinelSeverity;
+        sentinelId?: string;
+        agentId?: string;
+        limit?: number;
+    }): Promise<SentinelFinding[]>;
+    /**
+     * Drop expired findings. Returns the count removed.
+     */
+    pruneExpired(now?: Date): Promise<{
+        pruned: number;
+    }>;
+    private decode;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Dispatcher.
+ *
+ * Drives the sentinel evaluation tick. On each tick:
+ *  1. For every subscribed sentinel, call `evaluate()`.
+ *  2. Each returned finding routes to:
+ *     - the sentinel finding store (encrypted persistence)
+ *     - the audit log (`sentinel_finding_emitted`)
+ *     - in-process subscribers (dashboard SSE wires through this)
+ *  3. Per-sentinel exceptions log `sentinel_evaluation_failed` and the
+ *     dispatcher continues with the next sentinel.
+ *
+ * The dispatcher is one-per-fortress. The fortress id is stamped on
+ * every finding before persistence + emission so multi-fortress
+ * isolation holds at the cryptographic + structural layers both.
+ *
+ * Castle-walking discipline: the dispatcher introduces no outbound
+ * surface. It reads from the audit log, writes to the encrypted
+ * findings store + audit log, and emits to in-process subscribers.
+ */
+
+type SentinelDispatcherUnsubscribe = () => void;
+/**
+ * Event emitted to in-process subscribers when a finding is produced.
+ * The dashboard SSE pipeline subscribes here.
+ */
+interface SentinelDispatcherEmit {
+    type: "finding";
+    finding: SentinelFinding;
+}
+/**
+ * Event emitted on per-sentinel evaluation failure. Distinct from
+ * `finding` so subscribers can render diagnostics separately.
+ */
+interface SentinelDispatcherFailureEmit {
+    type: "evaluation_failed";
+    sentinel_id: string;
+    error_message: string;
+    observed_at: string;
+}
+type SentinelDispatcherAnyEmit = SentinelDispatcherEmit | SentinelDispatcherFailureEmit;
+interface SentinelDispatcherDeps {
+    registry: SentinelRegistry;
+    findingStore: SentinelFindingStore;
+    auditLog: AuditLog;
+    /** Stable fortress id stamped on every finding. */
+    fortressId: string;
+    /** Operator identity id for audit attribution. */
+    identityId: string;
+    /** Wall-clock provider for deterministic tests. */
+    now?: () => Date;
+    /** Tick interval, ms. Default 60s. Set to 0 to disable auto-tick. */
+    tickIntervalMs?: number;
+}
+declare class SentinelDispatcher {
+    private readonly registry;
+    private readonly findingStore;
+    private readonly auditLog;
+    private readonly fortressId;
+    private readonly identityId;
+    private readonly now;
+    private readonly tickIntervalMs;
+    private readonly listeners;
+    private tickTimer;
+    private tickInFlight;
+    constructor(deps: SentinelDispatcherDeps);
+    /** Read-only view of the registry. Convenience for route handlers. */
+    getRegistry(): SentinelRegistry;
+    /** Read-only view of the finding store. Convenience for route handlers. */
+    getFindingStore(): SentinelFindingStore;
+    /**
+     * Subscribe an in-process listener. Returns an unsubscribe fn.
+     */
+    onEvent(listener: (event: SentinelDispatcherAnyEmit) => void): SentinelDispatcherUnsubscribe;
+    /**
+     * Subscribe a sentinel to this fortress + emit the
+     * `sentinel_subscribed` audit event. Wraps `registry.subscribe()` so
+     * the audit emission lives at the dispatcher boundary (the
+     * fortress-aware site).
+     */
+    subscribeSentinel(sentinelId: string, contextOverrides?: Partial<SentinelContext>): Promise<Sentinel>;
+    /**
+     * Unsubscribe + emit `sentinel_unsubscribed`. Returns true when an
+     * active subscription was torn down. Audit fires only on successful
+     * removal.
+     */
+    unsubscribeSentinel(sentinelId: string): Promise<boolean>;
+    /**
+     * Run one evaluation pass over every subscribed sentinel. Used by
+     * the auto-tick AND by tests that want a synchronous evaluation
+     * gate. Returns the findings produced this tick (already persisted
+     * + audit-logged + emitted).
+     */
+    tick(): Promise<SentinelFinding[]>;
+    /**
+     * Start the auto-tick loop. No-op when tickIntervalMs is 0 or when
+     * already started. Tests typically leave auto-tick off and call
+     * `tick()` directly.
+     */
+    start(): void;
+    /** Stop the auto-tick loop. Idempotent. */
+    stop(): void;
+    /**
+     * Tear down every subscription + stop the tick loop. Called on
+     * fortress shutdown.
+     */
+    dispose(): Promise<void>;
+    private routeFinding;
+    private emit;
+}
+
 /**
  * Sanctuary MCP Server — Principal Dashboard
  *
@@ -6664,6 +7605,13 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * the operator-facing query / decision surface.
      */
     private approvalAggregator;
+    /**
+     * v1.3 WP-V1.3-1 Phi-1 Sentinel dispatcher. Mounted additively at
+     * `/api/sentinels/*` when set. Sentinel surface is read-only against
+     * the audit log; subscribe/unsubscribe writes flow through the
+     * dispatcher's audited paths.
+     */
+    private sentinelDispatcher;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -6701,11 +7649,23 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * tests + during shutdown).
      */
     setApprovalAggregator(aggregator: ApprovalAggregator | null): void;
+    /**
+     * v1.3 WP-V1.3-1 Phi-1: bind the Sentinel dispatcher. Once set,
+     * requests to `/api/sentinels/*` route through `handleSentinelRoute`.
+     * Pass `null` to detach (used by tests + during shutdown).
+     */
+    setSentinelDispatcher(dispatcher: SentinelDispatcher | 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.3 WP-V1.3-1 Phi-1 dispatch entry point. Routes `/api/sentinels/*`
+     * requests through the sentinel router when a dispatcher has been
+     * bound. Returns true when served.
+     */
+    private dispatchSentinel;
     /**
      * v1.1 dispatch entry point. Called from `handleRequest` before the
      * legacy route table. Returns true when the request was served by v1.1