loopctl-mcp-server 2.78.2 → 2.85.0

package/README.md

@@ -135,6 +135,31 @@ autonomous agent) can self-remediate without a human. Full agent-tenant lifecycl
 > dynamically at runtime — see [Dynamic per-tenant Context Retriever
 > tools](#dynamic-per-tenant-context-retriever-tools-epic-30) below.
 
+### Design invariant: no model-visible `confirm`/`approved` argument
+
+No loopctl MCP tool takes a `confirm`, `approved`, or `yes` argument. An argument
+like that is authorization the model writes for itself: the same call that asks for
+the mutation also carries its own approval, so nothing outside the caller ever sees
+the proposal, and a model that decided to delete will also decide to confirm.
+
+Set-based destructive actions therefore return a **proposal** instead. A dry-run
+resolves the selector once, freezes that id-set server-side, and hands back a
+single-use, TTL-bounded token; the caller replays the token to execute over exactly
+the frozen set. Every property that matters follows from the shape rather than from
+the caller's good behaviour: the executed set is the previewed set (rows that
+started matching afterwards are never swept), the token is spendable once, it
+expires, it is scoped to its tenant, and it is TYPED — by op AND by selector — so a
+proposal for a reversible op cannot be replayed as an irreversible one, nor spent on
+a selector it was not minted for. Selectors too large to freeze fall back to
+re-confirm-on-drift, which re-resolves and refuses on any change rather than relaxing
+the guarantee; its hash is keyed on the op, since with no token row it is the only
+thing keeping the two flows apart. `knowledge_bulk_delete` is the surface this governs today,
+on both its hard-delete path and its `tag` archive path.
+
+The pattern is borrowed from MemoRizz, whose destructive MCP tools return a durable
+single-use proposal the host approves out of band and never expose `approved` as a
+tool parameter.
+
 ### Project Tools
 
 | Tool | Description |
@@ -243,6 +268,33 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | A search came back empty/thin, or you don't yet know what to ask | `knowledge_heat_index` (no query at all) |
 | Enumerate / dedup / repair, or "does X exist?" (full fields, lag-free, all-status) | `knowledge_list` |
 
+**Read `meta.outcome` before you believe an empty result.** EVERY read on the knowledge,
+memory and corpus surfaces carries one of `success` | `empty` | `degraded` | `fallback` |
+`error`, so you never have to know which per-surface flag names a degradation — the
+retrieval tools (`knowledge_search`, `knowledge_context`, `knowledge_hybrid_search`,
+`knowledge_progressive_index`, `knowledge_heat_index`, `memory_recall`, `recall_context`,
+`corpus_search`), the enumerations (`knowledge_list`, `knowledge_index`, `memory_list`,
+`corpus_list`) and the review queues. On a catalog the value is only ever `empty` or
+`success` — it discloses no degradation of its own — but the KEY is there, so an ABSENT
+`outcome` means one thing and one thing only: a server older than this envelope.
+
+| `meta.outcome` | what happened | what to do |
+|---|---|---|
+| `success` | ran fully; this page carries rows, or an earlier one did | use them |
+| `empty` | ran fully and the whole matched set is empty | a real miss — re-route or accept it |
+| `degraded` | a half was shed, capacity-limited or scan-starved | this set may be SHORT — wait, then retry (a STANDING gap — `ann_iterative_scan_unavailable` or `embedding_dimension_mismatch` — only an operator clears) |
+| `fallback` | semantic ranking was unavailable, keyword-only was served | retry the SAME query, never reword |
+| `error` | the retrieval could not run; an empty envelope was served in its place | fix the request, then retry |
+
+Precedence is `error > fallback > degraded > empty > success`, so a degradation is never
+hidden behind a zero count. On `knowledge_search`, `knowledge_hybrid_search` and
+`knowledge_context` the MCP server also prints a leading banner for the three classes that
+need a remedy; `empty` and `success` are silent by design. Since 2.85.0 the banner also
+fires on `knowledge_list`, `knowledge_progressive_index`, `knowledge_heat_index`,
+`memory_recall`, `recall_context` and `corpus_search`, so every read that can report a
+degradation now announces one. Write tools carry no `outcome`. A page walked past the end of a non-empty set is `success`, not `empty`:
+exhausting a paginated walk is not the same as the row being absent.
+
 | Tool | Description |
 |---|---|
 | `knowledge_index` | Browse/paginate the knowledge wiki catalog grouped by category. **Agent callers see only articles they own or marked `shared`.** Honors `category`, `tags`, `offset`, `limit` with deterministic ordering over the filtered set (`meta.categories` reports per-category totals within visibility). Use `fields` (default `id,title,category`; request `tags`/`status`/`updated_at` explicitly; `id` and `category` are always included) to keep the payload small. Optional: `project_id`, `story_id`, `category`, `tags`, `offset`, `limit`, `fields`. |
@@ -252,14 +304,14 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `knowledge_stats` | Aggregate article counts (`total`, `by_category`, `by_status`) via cheap `COUNT(*) GROUP BY` within agent's visible set — no article metadata loaded. Agent callers see only their own and `shared` articles. Counts span all statuses. Optional: `project_id`. |
 | `knowledge_count` | Count articles matching filters **without returning rows** within agent's visible set. Agent callers see only their own and `shared` articles. Same filters as `knowledge_list` (`category`, `status`, `tags`, `match`, `source_type`, `source_id`, `idempotency_key`, `project_id`). With `tags`+`match: all` (+`status`) → "how many published articles tagged both X and Y (that I can see)". Returns `{ count }`. |
 | `knowledge_facets` | Count articles grouped by **distinct tag** within agent's visible set, no rows. Agent callers see only their own and `shared` articles. `tag_prefix` (e.g. `book-`) gives the distinct count of a tag family plus per-member totals. Returns `{ data: { tag: count }, meta: { distinct_count } }`. Optional: `category`, `status`, `tags`, `match`, `project_id`, `limit`. |
-| `knowledge_search` | Search the knowledge wiki by topic (keyword, semantic, or combined). Returns snippets. **Ranked, published-only, and LAGS writes by minutes while embeddings index — do NOT use for existence/idempotency/dedup checks (a fresh write false-negatives); use `knowledge_list` for that.** `query` (historically `q`, still accepted) is optional when `tags`/`category` are supplied — that **list mode** returns the complete filtered set paginated via `offset`/`limit` over `meta.total_count`. `meta.total_count` is mode-dependent — read `meta.total_count_scope` (`keyword_matches`/`ranked_corpus`/`merged_candidates`/`filtered_set`) and don't use a relevance-mode count to size the wiki (use `knowledge_list` or `knowledge_stats`). On the semantic/combined paths `meta.ann_iterative_scan` (`off`/`applied`/`unavailable`, with `meta.ann_iterative_scan_reason` alongside `unavailable`) discloses whether the vector read ran with pgvector's iterative scan — `unavailable` means results may be INCOMPLETE, which `meta.fallback` cannot tell you. Optional: `project_id`, `story_id` for attribution. |
-| `knowledge_hybrid_search` | Resolve a topic to a **single best answer with provenance** (US-31.4). Runs combined keyword+semantic over the full ranked pool, then decides whether a governed **curated** source actually answers. `meta.provenance` is `curated` (trust it — the canonical article is first in `data`, `meta.curated_article_id` points at it) or `retrieved` (best fuzzy match, `curated_article_id` null); `meta.confidence` is the winner's absolute score. Prefer over `knowledge_search` when you want one trustworthy answer, not a list to triage. Degrades to keyword-only like `knowledge_search` when embeddings are unavailable. Required: `query`. Optional: `project_id`, `category`, `tags`, `match`, `limit`, `offset`. |
-| `knowledge_progressive_index` | Progressive disclosure — a **cheap, capped index** of what's relevant to a topic (compact stubs: `id`/`title`/`category`/`summary`, **no bodies**), curated-preferred and hub-enriched, capped at top-K (`meta.truncated` when the pool exceeded it). Survey a topic without flooding context, then open only what you need via `knowledge_progressive_drill`. Required: `query` (historically `topic`, still accepted). Optional: `category`, `limit`. |
-| `knowledge_heat_index` | Browse the corpus with **no query at all** — capped compact stubs (`id`/`title`/`category`/`heat`/`summary`, **no bodies**) ranked by how many **distinct readers** (agents, not key rows — repeat reads by one reader count once, ties broken by the number of distinct days read, never by raw read count) opened each article inside a window. Every other retrieval tool starts from a query and so shares one failure mode: a paraphrase, or material topically central but lexically dissimilar to the question, comes back empty and reads as "the KB has nothing" rather than "I asked badly". Reach for it when a search came back empty or thin, or to survey what the fleet actually reads before you know what to ask. **Ordering is usage, not relevance**, and drilling a listed article (`knowledge_progressive_drill`) does not add heat to what it opened, at any scope — otherwise being shown would produce the rank that shows it. A `knowledge_get` of the same id does count. `meta` states `heat_window` (the default window is snapped to a UTC day boundary so the payload is stable between refreshes and safe in a cached prefix; an explicit `since` is served verbatim), `counted_access_types`, `char_budget`/`chars` (BYTES of the encoded stub array, framing included), `truncated` and `unresolved`. Both read tools open a stub, canonicals included — pick by what the read MEANS: a drill is uncounted, a `get` is a counted vote. Optional: `category`, `limit`, `since`. |
+| `knowledge_search` | Search the knowledge wiki by topic (keyword, semantic, or combined). Returns snippets. **Ranked, published-only, and LAGS writes by minutes while embeddings index — do NOT use for existence/idempotency/dedup checks (a fresh write false-negatives); use `knowledge_list` for that.** `query` (historically `q`, still accepted) is optional when `tags`/`category` are supplied — that **list mode** returns the complete filtered set paginated via `offset`/`limit` over `meta.total_count`. `meta.total_count` is mode-dependent — read `meta.total_count_scope` (`keyword_matches`/`ranked_corpus`/`merged_candidates`/`filtered_set`) and don't use a relevance-mode count to size the wiki (use `knowledge_list` or `knowledge_stats`). On the semantic/combined paths `meta.ann_iterative_scan` (`off`/`applied`/`unavailable`, with `meta.ann_iterative_scan_reason` alongside `unavailable`) discloses whether the vector read ran with pgvector's iterative scan — `unavailable` means results may be INCOMPLETE, which `meta.fallback` cannot tell you. Optional: `project_id`, `story_id` for attribution. Carries `meta.outcome` (see the table above) — a `fallback` or `degraded` value means an empty page is not a miss. |
+| `knowledge_hybrid_search` | Resolve a topic to a **single best answer with provenance** (US-31.4). Runs combined keyword+semantic over the full ranked pool, then decides whether a governed **curated** source actually answers. `meta.provenance` is `curated` (trust it — the canonical article is first in `data`, `meta.curated_article_id` points at it) or `retrieved` (best fuzzy match, `curated_article_id` null); `meta.confidence` is the winner's absolute score. Prefer over `knowledge_search` when you want one trustworthy answer, not a list to triage. Degrades to keyword-only like `knowledge_search` when embeddings are unavailable. Required: `query`. Optional: `project_id`, `category`, `tags`, `match`, `limit`, `offset`. Carries `meta.outcome` alongside `meta.provenance`: provenance says WHICH source answered, outcome says whether the retrieval that produced it ran healthily. |
+| `knowledge_progressive_index` | Progressive disclosure — a **cheap, capped index** of what's relevant to a topic (compact stubs: `id`/`title`/`category`/`summary`, **no bodies**), curated-preferred and hub-enriched, capped at top-K (`meta.truncated` when the pool exceeded it). Survey a topic without flooding context, then open only what you need via `knowledge_progressive_drill`. Required: `query` (historically `topic`, still accepted). Optional: `category`, `limit`. Carries `meta.outcome`; this path discloses no degradation of its own, so an `empty` index really is an empty topic. |
+| `knowledge_heat_index` | Browse the corpus with **no query at all** — capped compact stubs (`id`/`title`/`category`/`heat`/`summary`, **no bodies**) ranked by how many **distinct readers** (agents, not key rows — repeat reads by one reader count once, ties broken by the number of distinct days read, never by raw read count) opened each article inside a window. Every other retrieval tool starts from a query and so shares one failure mode: a paraphrase, or material topically central but lexically dissimilar to the question, comes back empty and reads as "the KB has nothing" rather than "I asked badly". Reach for it when a search came back empty or thin, or to survey what the fleet actually reads before you know what to ask. **Ordering is usage, not relevance**, and drilling a listed article (`knowledge_progressive_drill`) does not add heat to what it opened, at any scope — otherwise being shown would produce the rank that shows it. A `knowledge_get` of the same id does count. `meta` states `heat_window` (the default window is snapped to a UTC day boundary so the payload is stable between refreshes and safe in a cached prefix; an explicit `since` is served verbatim), `counted_access_types`, `char_budget`/`chars` (BYTES of the encoded stub array, framing included), `truncated` and `unresolved`. Both read tools open a stub, canonicals included — pick by what the read MEANS: a drill is uncounted, a `get` is a counted vote. Optional: `category`, `limit`, `since`. Carries `meta.outcome` like every other retrieval surface. |
 | `knowledge_progressive_drill` | Open one stub from `knowledge_progressive_index` or `knowledge_heat_index` — returns the **full article body** for the given id, scope-enforced. Resolves both tenant-owned articles and published system canonicals (the same set those indexes surface). Every article opened this way is recorded under an access type `knowledge_heat_index` does not count, whatever its scope, so that index can never rank on the reads it caused. `knowledge_get` reaches the same ids and DOES count — use it when the read is a deliberate vote rather than a step in following a list. Required: `article_id`. |
-| `knowledge_list` | List articles (`id`, `title`, `category`, `status`, `tags`, `source_type`, `source_id`, timestamps), filtered + paginated. **Body-less summary by default** (safe to page up to `limit=1000`); pass `include_body: true` to also return `body`, in which case the page is bounded by a ~5 MB byte budget — continue via `meta.next_offset` while `meta.has_more`. **Lag-free, all-status** read of the DB of record — unlike `knowledge_search` (ranked, published-only, lags writes) and `knowledge_index` (id/title/category only). The right tool to enumerate/dedup/repair and for idempotency/existence checks: filter by `tags`, `source_type`+`source_id`, or `idempotency_key` and read `meta.total_count` (exact) — `idempotency_key` is a FILTER only and is never returned in a row, so you check a key you already hold. Single full body → `knowledge_get`; relevant bodies → `knowledge_context`; bulk dump → `knowledge_export`. Optional: `project_id`, `category`, `status`, `tags`, `source_type`, `source_id`, `idempotency_key`, `offset`, `limit`, `include_body`. |
+| `knowledge_list` | List articles (`id`, `title`, `category`, `status`, `tags`, `source_type`, `source_id`, timestamps), filtered + paginated. **Body-less summary by default** (safe to page up to `limit=1000`); pass `include_body: true` to also return `body`, in which case the page is bounded by a ~5 MB byte budget — continue via `meta.next_offset` while `meta.has_more`. **Lag-free, all-status** read of the DB of record — unlike `knowledge_search` (ranked, published-only, lags writes) and `knowledge_index` (id/title/category only). The right tool to enumerate/dedup/repair and for idempotency/existence checks: filter by `tags`, `source_type`+`source_id`, or `idempotency_key` and read `meta.total_count` (exact) — `idempotency_key` is a FILTER only and is never returned in a row, so you check a key you already hold. Single full body → `knowledge_get`; relevant bodies → `knowledge_context`; bulk dump → `knowledge_export`. Optional: `project_id`, `category`, `status`, `tags`, `source_type`, `source_id`, `idempotency_key`, `offset`, `limit`, `include_body`. Carries `meta.outcome`; on this lag-free enumeration path `empty` is load-bearing — the filtered set is genuinely empty, not missed by a ranker (a page past the end reads `success`). |
 | `knowledge_get` | Get full article content by ID. Use after search to read an article in detail. Resolves tenant-owned articles **and published system canonicals**, and records a COUNTED read (it feeds `knowledge_heat_index`) — reach for `knowledge_progressive_drill` instead when you are merely following an index this system just produced. Each link carries only its FAR side (`article: {id, title}`, plus `similarity` when scored); both arrays are ranked (open conflicts first, then descending similarity, then oldest-first for the unscored) and capped at 25 per direction, with `links_total` / `links_truncated` reporting the truth (`count` returns both, so one cheap call tells you whether the full fetch is capped). Pass `links: "count"` or `"none"` when you only want the text — on a well-linked hub the link block is several times the body. `potential_conflicts` is returned in all three modes, itself capped at 25 with `conflicts_total` / `conflicts_truncated`. Optional: `links`, `project_id`, `story_id` for attribution. |
-| `knowledge_context` | Get relevance-and-recency-ranked full articles for a task query. Best knowledge for your current context. **Agent-memory scoping**: `memory_types` (comma-separated, OR — observation/finding/summary/decision/question/task), `agents` (comma-separated agent_ids, OR), `conversation_id` (exact) filter on article `metadata` (JSONB `@>`). Optional: `project_id`, `story_id` for attribution, `limit`, `recency_weight`. |
+| `knowledge_context` | Get relevance-and-recency-ranked full articles for a task query. Best knowledge for your current context. **Agent-memory scoping**: `memory_types` (comma-separated, OR — observation/finding/summary/decision/question/task), `agents` (comma-separated agent_ids, OR), `conversation_id` (exact) filter on article `metadata` (JSONB `@>`). Optional: `project_id`, `story_id` for attribution, `limit`, `recency_weight`. Carries `meta.outcome`, so an empty context pack is distinguishable from one whose underlying search fell back to keyword-only. |
 | `knowledge_graph` | Multi-hop traversal of the published article-link graph from `article_id` (depth 1–3, default 1), **bounded to agent's visible articles**. Agent callers see only their own and `shared` articles. Bidirectional, cycle-safe, bounded to 100 nodes / 500 edges (`truncated` flags a cap). Returns `nodes` (`id`/`title`/`category`/`depth`) + `edges` (`source_article_id`/`target_article_id`/`relationship_type`). Explore typed connections beyond `knowledge_context`'s 1-hop links. Required: `article_id`. Optional: `depth`, `project_id`. |
 | `knowledge_suggest_links` | Ranked typed-link **candidates** for an article by embedding similarity among **visible articles** — **read-only** (creates nothing). Excludes the article itself + any already-linked article (either direction, any type); only embedded published articles visible to the caller. Agent callers see only their own and `shared` articles. Returns `{id, title, category, similarity_score}` highest-first, to create as a **typed** link (relates_to/derived_from/contradicts/supersedes). `meta.ann_iterative_scan` (`off`/`applied`/`unavailable`, with `meta.ann_iterative_scan_reason` alongside `unavailable`) discloses whether the vector read ran with pgvector's iterative scan — `unavailable` means the list may be INCOMPLETE, which `meta.recall_truncated: false` does NOT cover, so do not read a short list as "no neighbours". Required: `article_id`. Optional: `threshold` (cosine floor 0–1, default 0.5), `limit` (default 5). |
 | `knowledge_distant_pairs` | Distant-but-bridgeable article pairs in the optimal-novelty embedding band (cosine distance, default 0.3–0.7) — the creative sweet spot. Sampled from **agent's visible published articles**; agent callers see only their own and `shared` articles. `bridge_path: true` requires a ≤2-hop link path. Returns `{a, b, distance}` pairs, paginated. Optional: `min_distance`, `max_distance`, `bridge_path`, `limit` (default 20, max 100), `offset`. |
@@ -286,11 +338,11 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | Tool | Description |
 |---|---|
 | `memory_remember` | Write to your own working memory. `tier` selects the substrate: `long_term` (default; requires `text`, embedded asynchronously and later recalled by semantic similarity via `memory_recall`) or `session` (short-term; requires `session_id`, `content`, `expires_at` — pruned after expiry, not semantically recalled). Returns 201 with the stored memory. Optional: `confidence`, `tags`, `source_session_id`, `metadata` (long-term); `role` (session). |
-| `memory_recall` | Semantically recall your own long-term memories most similar to `query`. When embedding generation is unavailable the response degrades to a recent-first text match with `meta.fallback: true` and a stable `meta.reason` (score is `null` on that path) — check `meta.fallback` before treating a short/empty result as a genuinely empty scope. `meta.total_count`/`meta.underfilled` are also returned. On the semantic path `meta.ann_iterative_scan` (`off`/`applied`/`unavailable`, with `meta.ann_iterative_scan_reason` alongside `unavailable`) discloses whether the vector read ran with pgvector's iterative scan — `unavailable` means results may be INCOMPLETE, which `meta.fallback`/`meta.underfilled` cannot tell you. It is absent on the ILIKE fallback AND on an `include_superseded: true` recall (a bounded exact top-k, no index scan), so absence never means the fallback ran. Optional: `limit`, `include_superseded`. |
+| `memory_recall` | Semantically recall your own long-term memories most similar to `query`. When embedding generation is unavailable the response degrades to a recent-first text match with `meta.fallback: true` and a stable `meta.reason` (score is `null` on that path) — check `meta.fallback` before treating a short/empty result as a genuinely empty scope. `meta.total_count`/`meta.underfilled` are also returned. On the semantic path `meta.ann_iterative_scan` (`off`/`applied`/`unavailable`, with `meta.ann_iterative_scan_reason` alongside `unavailable`) discloses whether the vector read ran with pgvector's iterative scan — `unavailable` means results may be INCOMPLETE, which `meta.fallback`/`meta.underfilled` cannot tell you. It is absent on the ILIKE fallback AND on an `include_superseded: true` recall (a bounded exact top-k, no index scan), so absence never means the fallback ran. Optional: `limit`, `include_superseded`. Carries `meta.outcome`, which is the one key to read here: a SHED read sets `meta.fallback: true` while serving no substitute lane, and is reported as `degraded` (wait, then retry), not `fallback`. |
 | `memory_list` | List your own long-term memories, newest first, paginated with `meta.total_count/limit/offset` (the true scoped count, never silently capped by `limit`). Optional: `limit`, `offset`, `include_superseded`, `all_subjects` (superadmin only; ignored for non-superadmin keys). |
 | `memory_forget` | Delete one of your own long-term memories by id. A foreign-subject, foreign-tenant, or unknown id returns 404 (no existence leak). Required: `id`. |
 | `memory_promote` | Call at session end to compile this session's short-term (`session`-tier) memory into durable `long_term` memory — unlike `memory_remember` (a single explicit write), this compiles the whole session in one shot; fire it once at session end, not per turn. Returns 202 with `{session_id, status: "enqueued"}` — promotion runs asynchronously, so the resulting memory is recallable via `memory_recall` only after the worker drains. You can only promote your own sessions (scope resolved server-side from your key). Required: `session_id`. |
-| `recall_context` | ONE round-trip returning the re-ranked `global ∪ active-project` union of long-term MEMORY **and** KNOWLEDGE for `query` — what you previously assembled by calling `memory_recall` and `knowledge_search` separately. Pass `project_id` (from `resolve_project`) to merge global with that project on both sides; absent → global-only. The knowledge half is combined-search *summaries* (not full bodies — use `knowledge_context` for those). Response carries merged `results` (each tagged `source: memory\|knowledge`) plus the untouched per-source `memory`/`knowledge` envelopes; `meta.degraded?` flags a one-sided degrade (the other side is still returned — never a 500). Each per-source envelope's `meta.ann_iterative_scan` describes only THAT half's vector read, and the two are resolved independently, so they may differ. A blank query, or one over 500 chars, is a `422` up front. Required: `query`. Optional: `project_id`, `limit`. |
+| `recall_context` | ONE round-trip returning the re-ranked `global ∪ active-project` union of long-term MEMORY **and** KNOWLEDGE for `query` — what you previously assembled by calling `memory_recall` and `knowledge_search` separately. Pass `project_id` (from `resolve_project`) to merge global with that project on both sides; absent → global-only. The knowledge half is combined-search *summaries* (not full bodies — use `knowledge_context` for those). Response carries merged `results` (each tagged `source: memory\|knowledge`) plus the untouched per-source `memory`/`knowledge` envelopes; `meta.degraded?` flags a one-sided degrade (the other side is still returned — never a 500). Each per-source envelope's `meta.ann_iterative_scan` describes only THAT half's vector read, and the two are resolved independently, so they may differ. A blank query, or one over 500 chars, is a `422` up front. Required: `query`. Optional: `project_id`, `limit`. The top-level `meta.outcome` classifies the whole endpoint and the `memory` envelope carries its own; `meta.degraded_reason` names the strongest-remedy half when both degrade, and `meta.search_mode` names the lane that half actually served (`keyword_only`) or is `null` when it served nothing. |
 | `memory_graduate` | Graduate ONE of your long-term memories into a durable Knowledge Wiki article — the explicit, on-demand version of the hourly graduation sweep. Use when a private memory has proven valuable enough to become durable knowledge. **Visibility**: the graduated article stays **owner-visible** (`metadata.visibility: "owner"`, keyed to your subject) — discoverable by YOU, NOT peer-readable (graduation does not share a memory to teammates; `re_scope: "global"` widens only the project scope, not visibility). Scope is key-derived (you can only graduate your OWN memory; a foreign/unknown `memory_id` → 404). DEDUPED by the novelty gate: `data.verdict` is `created` (novel → published) or `gated_to_draft` (near-dup → review draft) with a new article (**201**), or `duplicate`/`deduplicated` (already represented → canonical article, nothing created) (**200**). By default the article inherits the memory's project scope; pass `re_scope: "global"` to promote a PROJECT memory to a tenant-wide article — only valid on its FIRST graduation, and only if the hourly sweep hasn't graduated it project-scoped first (`409` `already_graduated` otherwise). An already-graduated global memory re-graduates idempotently (**200**). `503` `gate_unavailable` if the embedding backend is down — retry later. Required: `memory_id`. Optional: `re_scope` (`inherit`\|`global`). |
 
 ### Knowledge Management Tools (orchestrator key)
@@ -303,7 +355,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_bulk_unpublish` | **Requires `LOOPCTL_USER_KEY`.** Revert published articles to draft in bulk, partial-success style (mirror of `knowledge_bulk_publish`): per-id `unpublished`/`skipped` (already draft, or archived/superseded)/`not_found`/`errored`. No 100-id cap (auto-chunked, ≤5000); duplicates ignored; safe to retry. Not deleted (re-publish to restore; `knowledge_bulk_delete` to archive). `meta.count`/`meta.counts`/`meta.results` give the breakdown. Required: `article_ids` (array). |
 | `knowledge_archive` | Soft-delete an article (draft or published). Row retained for audit; hidden from all reads. **NOT reversible by you** — `:archived` is a TERMINAL status (no unarchive call, no outbound transition), so restoring one needs a user-role PATCH with an explicit status. Nothing is destroyed, but do not reach for this as an undoable action: for a retraction you can undo, use `knowledge_unpublish` and `knowledge_publish`. Agent role — KB-content curation, visibility-scoped (another agent's private/owner memory 404s). Required: `article_id`. |
 | `knowledge_delete` | Alias for `knowledge_archive` — DELETE verb on the REST API archives under the hood (soft delete: row retained and audited, but NOT reversible by any call you can make, since `:archived` is terminal — use `knowledge_unpublish` when you need an undoable retraction). Agent role. (Irreversible HARD delete is `knowledge_bulk_delete hard:true`, which stays `LOOPCTL_USER_KEY`.) Required: `article_id`. |
-| `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default — non-destructive, but NOT reversible by any call: `:archived` is terminal and restoring needs a user-role PATCH) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
+| `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default — non-destructive, but NOT reversible by any call: `:archived` is terminal and restoring needs a user-role PATCH) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag` (every active article with the tag — high blast radius). **There is no `confirm` parameter** — a request carrying one is `400 confirm_removed`, never ignored; see the [Design invariant](#design-invariant-no-model-visible-confirmapproved-argument) below. Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000); `article_ids` and `source` archive immediately. **Two-step** (the `tag` archive, and every hard delete): `dry_run:true` mutates nothing and returns `meta.would_affect` plus a single-use, TTL-bounded `meta.token` frozen over the previewed id-set; call again with the same selector plus that token to run the op over the FROZEN set — the selector is CHECKED, so a token minted for one tag is `400` on a call naming another. A call with neither is `400` (`dry_run_required` on the tag archive) unless the selector matches nothing, which stays a `200` no-op on either path. The archive and delete flows mint DIFFERENT token types, so an archive proposal is not spendable as a delete or the reverse. Oversized selectors get `meta.oversized`+`meta.confirm_hash` instead of a token — echo the hash back with the same selector and the server refuses on any drift; that hash is keyed on the op, so it does not cross flows either. Hard delete is FK-correct (links first, access events cascade). |
 | `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 1000 — over-max → 400, no silent clamp), `offset` (default 0), `project_id`. Returns `meta.total_count`. |
 | `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`, `max_per_category` (default 50, max 500). True totals returned in `summary.total_per_category`. |
 | `knowledge_consolidation` | Read the nightly consolidation ("dream") report: NUMBERED proposals for reconciling the corpus, each naming the articles involved and quoting an excerpt from each as evidence. **This tool** applies nothing and recomputes nothing — it returns persisted rows. **The pass** it reports on does write: since #608 the nightly run UNPUBLISHES the losers of each `duplicate_capture` group that two consecutive reports both propose (consecutive meaning the previous report is at most 2 days older, so one skipped nightly run is tolerated and a longer outage is not). That is its only write to `articles`, it is an unpublish and never an archive (archive is terminal for an article), and it still writes no links or conflict resolutions. Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, or idempotency keys that collide under the same normalization while differing verbatim — capture tag-format drift, which the novelty gate does not catch because novelty scoring and idempotency are separate paths), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation). Two classes are **RETIRED** (#605) and no longer produced, though the `class` filter still accepts them so historical reports stay readable: `contradiction_candidate` (the nightly lint judges those pairs itself now) and `stale_entry` (age is not a defect signal — for stale articles call `knowledge_lint`, which computes them with a caller-chosen `stale_days`). **Denominators:** `corpus_size` = PUBLISHED articles owned by the tenant at scan time, not its total article count; `proposal_count` = the TRUE pre-cap count of PROPOSALS, not of articles (one duplicate group of three articles is ONE proposal, and one article can appear in proposals of several classes); `persisted_count` = proposal ROWS the report carries, lower than `proposal_count` exactly when a class hit `max_per_class` (`truncated` flags which); `meta.total_count` counts persisted proposals matching the `class` filter, so it is bounded by `persisted_count`, never `proposal_count`. `review_status`/`reviewed_by`/`reviewed_at` are vestigial — nothing reads them to decide anything, there is no approve/reject surface and there will not be one (#605 supersedes #594); auto-apply is gated on reversibility and two-run agreement. They still reset to pending/null whenever the nightly pass re-derives a proposal, so refreshed machine output never inherits an earlier verdict. Requires orchestrator role. Optional: `day` (ISO8601, default most recent report), `class`, `limit` (default 50, max 500), `offset`. |
@@ -374,7 +426,7 @@ Two modes, pinned at creation:
 
 | Tool | Description |
 |---|---|
-| `corpus_search` | Search a corpus for POINTERS into files loopctl does not host. Returns `{source_ref, locator, snippet, score, chunk_id, corpus_id}` — a bounded excerpt, never the chunk body — so the next step is always to open the file. `server_embedded`: send `query`. `client_embedded`: send `query_vector` (length = the corpus `dim`); a query string there is `422 query_string_not_accepted` and asking for the keyword lane is `422 keyword_lane_unavailable`. Exactly one of `query`/`query_vector` (both is `422 ambiguous_query`). Scores are rank-derived (RRF) and comparable only WITHIN one result set. Agent key. |
+| `corpus_search` | Search a corpus for POINTERS into files loopctl does not host. Returns `{source_ref, locator, snippet, score, chunk_id, corpus_id}` — a bounded excerpt, never the chunk body — so the next step is always to open the file. `server_embedded`: send `query`. `client_embedded`: send `query_vector` (length = the corpus `dim`); a query string there is `422 query_string_not_accepted` and asking for the keyword lane is `422 keyword_lane_unavailable`. Exactly one of `query`/`query_vector` (both is `422 ambiguous_query`). Scores are rank-derived (RRF) and comparable only WITHIN one result set. Agent key. Carries `meta.outcome`, so a short lane is distinguishable from an empty corpus without knowing that `semantic_unavailable_reason` and `semantic_under_filled` are the keys that mean "ask again". |
 | `corpus_create` | Create a corpus, pinning `mode`, `embedding_model` and `dim`. Required: `slug`, `name`, `mode`, `embedding_model`, `dim`. Optional: `description`, `allow_snippets`, `project_id`. Agent key. |
 | `corpus_index` | Index a batch of chunks. `server_embedded` chunk: `{source_ref, locator, text, ordinal?, snippet?}`. `client_embedded` chunk: `{source_ref, locator, vector, content_hash, ordinal?, snippet?}` — there is **no** `text` parameter and sending one is `422 text_not_accepted`, not ignored. Idempotent on `(corpus, source_ref, locator)`. `source_complete` is how a RE-index removes what the document no longer contains: a bare `source_ref` string means this request carries that source's complete set, `{source_ref, locators}` declares the set explicitly for a document spanning several batches. Anything under a named source that is neither carried nor declared is deleted, and `meta.pruned_by_source` reports the cost. Agent key. |
 | `corpus_list` | List this tenant's corpora, newest first. Call it before searching to learn a corpus's `mode` (which decides string vs vector) and its `dim`. Optional: `project_id`, `limit`, `offset`. Agent key. |

package/index.js

@@ -1590,7 +1590,10 @@ async function knowledgeProgressiveIndex({ topic, query, category, limit }) {
     null,
     process.env.LOOPCTL_AGENT_KEY,
   );
-  return toContent(result);
+  // A topic browse is a RETRIEVAL: it runs the same ranked pool, so it can come back
+  // short or keyword-only. Without the banner a shed index reads as "the KB has no
+  // articles on this topic", which is the exact misread meta.outcome exists to end.
+  return withRemediationNotice(result);
 }
 
 async function knowledgeHeatIndex({ category, limit, since }) {
@@ -1605,7 +1608,9 @@ async function knowledgeHeatIndex({ category, limit, since }) {
     null,
     process.env.LOOPCTL_AGENT_KEY,
   );
-  return toContent(result);
+  // The query-free route, reached for precisely when the query-shaped ones came back
+  // empty — so an unannounced degradation here strands the agent with no route left.
+  return withRemediationNotice(result);
 }
 
 async function knowledgeProgressiveDrill({ article_id, body_max_bytes, body_offset }) {
@@ -1661,7 +1666,9 @@ async function knowledgeList({
     null,
     process.env.LOOPCTL_AGENT_KEY,
   );
-  return toContent(result);
+  // Enumeration, not ranking — but a short page still under-reports the set, and an
+  // agent enumerating to decide something absent is the caller least able to tell.
+  return withRemediationNotice(result);
 }
 
 async function knowledgeGet({
@@ -1837,9 +1844,11 @@ async function memoryRecall({ query, limit, include_superseded }) {
     process.env.LOOPCTL_AGENT_KEY,
   );
   // Surface meta (fallback/reason/total_count/underfilled) so the caller can tell
-  // a degraded recall from a genuinely empty scope (AC-28.4.4) — toContent already
-  // preserves the full result (data + meta), we just keep this call explicit.
-  return toContent(result);
+  // a degraded recall from a genuinely empty scope (AC-28.4.4). meta alone was not
+  // enough: agents do not read it, which is the whole finding behind the banner. On
+  // the MEMORY surface a shed read otherwise looks identical to an empty scope, and
+  // "I have never been told this" is the most consequential thing to get wrong here.
+  return withRemediationNotice(result);
 }
 
 async function recallContext({ query, project_id, limit }) {
@@ -1858,8 +1867,11 @@ async function recallContext({ query, project_id, limit }) {
     process.env.LOOPCTL_AGENT_KEY,
   );
   // Surface both per-source metas (memory fallback/underfilled + knowledge degraded)
-  // so the caller can tell a degraded recall from a genuinely empty scope.
-  return toContent(result);
+  // so the caller can tell a degraded recall from a genuinely empty scope. The merged
+  // meta can carry ONE half's failure beside the other half's rows, which the server
+  // classifies "degraded" — a banner is the only place a caller sees that the pack it
+  // is about to act on is a half.
+  return withRemediationNotice(result);
 }
 
 async function memoryList({ limit, offset, include_superseded, all_subjects }) {
@@ -2011,12 +2023,16 @@ async function knowledgeDelete({ article_id }) {
   return toContent(result);
 }
 
+// There is deliberately NO `confirm` parameter here (#779). A destructive action
+// returns a server-minted proposal the caller REPLAYS; it never takes its own
+// authorization as an argument the model can fill in. The server refuses a request
+// carrying a `confirm` key with 400 confirm_removed rather than ignoring it, so a
+// stale client learns the gate moved instead of believing it passed one.
 async function knowledgeBulkDelete({
   article_ids,
   source_type,
   source_id,
   tag,
-  confirm,
   dry_run,
   hard,
   token,
@@ -2027,11 +2043,12 @@ async function knowledgeBulkDelete({
   if (source_type) payload.source_type = source_type;
   if (source_id) payload.source_id = source_id;
   if (tag) payload.tag = tag;
-  if (confirm) payload.confirm = confirm;
-  // US-27.12: dry-run preview + irreversible hard delete via a single-use frozen
-  // token. dry_run=true mutates nothing (returns meta.would_affect; for the hard
-  // path a single-use meta.token); hard=true + token performs the FK-correct
-  // IRREVERSIBLE delete over the frozen id-set. Oversized selectors echo
+  // US-27.12 / #779: dry-run preview + a single-use frozen token, on BOTH the
+  // irreversible hard delete (any selector) and the soft ARCHIVE of a `tag`
+  // selector. dry_run=true mutates nothing (returns meta.would_affect plus
+  // meta.token); replaying that token performs the op over the FROZEN id-set.
+  // The two flows mint DIFFERENT token types, so an archive proposal is not
+  // spendable as a delete or the reverse. Oversized selectors echo
   // meta.confirm_hash for re-confirm-on-drift instead of a token.
   if (dry_run) payload.dry_run = true;
   if (hard) payload.hard = true;
@@ -3071,8 +3088,10 @@ async function corpusSearch({ corpus_id, query, query_vector, lanes, limit }) {
     process.env.LOOPCTL_AGENT_KEY,
   );
   // Pointers + snippets only — the caller's next step is to open the file at
-  // source_ref/locator. Nothing here is auto-injected into a recall pack.
-  return toContent(result);
+  // source_ref/locator. Nothing here is auto-injected into a recall pack, so a
+  // degradation nobody announces is never noticed downstream either: this banner is
+  // the only disclosure a corpus read gets.
+  return withRemediationNotice(result);
 }
 
 async function corpusStatus({ corpus_id, limit, offset }) {
@@ -5689,15 +5708,25 @@ const TOOLS = [
       "of articles by selector. " +
       "REQUIRES LOOPCTL_USER_KEY (user role — orchestrator is NOT sufficient). Provide EXACTLY ONE " +
       "selector: article_ids (explicit list), source_type + source_id (every active article from " +
-      "that source), or tag + confirm:true (every active article carrying the tag — high blast " +
-      "radius, so confirm:true is required). " +
+      "that source), or tag (every active article carrying the tag — high blast radius). " +
+      "THERE IS NO confirm PARAMETER. Sending one is 400 confirm_removed, never ignored. A " +
+      "high-blast-radius call is authorized by REPLAYING a server-minted proposal, never by a " +
+      "flag in the same request that asks for the mutation. " +
       "DEFAULT (soft archive): rows move to archived, never dropped; set-based + idempotent; " +
-      "meta.count = archived, meta.counts/meta.results give the breakdown. " +
-      "DRY-RUN: dry_run:true mutates NOTHING and returns meta.would_affect (and, for hard, a " +
-      "single-use meta.token / for oversized selectors a meta.confirm_hash). " +
-      "HARD DELETE (irreversible): first dry_run with hard:true to get a token, then call again " +
-      "with hard:true + that token to FK-correctly delete the FROZEN id-set (links removed first, " +
-      "access events cascade). The token is single-use and TTL-bounded. Bounded to 5000 per call.",
+      "meta.count = archived, meta.counts/meta.results give the breakdown. article_ids and " +
+      "source archive immediately; the tag selector is TWO-STEP. " +
+      "TWO-STEP (tag archive, and every hard delete): call with dry_run:true to get " +
+      "meta.would_affect and a single-use, TTL-bounded meta.token frozen over the previewed " +
+      "id-set, then call again with the SAME selector plus that token. The op runs over the " +
+      "FROZEN set, so rows that started matching after the preview are never touched. A call " +
+      "with neither dry_run nor token is 400 (dry_run_required on the tag archive) UNLESS the " +
+      "selector matches nothing, which stays a 200 no-op on either path. The token is TYPED by " +
+      "op AND by selector: an archive token is not spendable as a delete or the reverse, and a " +
+      "token minted for one tag is 400 on a call naming another — sweeping a list of tags " +
+      "needs its own dry-run per tag. Oversized selectors (over the frozen bound) get " +
+      "meta.oversized + " +
+      "meta.confirm_hash instead of a token; echo the hash back with the same selector and the " +
+      "server refuses on any drift. Bounded to 5000 per call.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5717,17 +5746,15 @@ const TOOLS = [
         tag: {
           type: "string",
           description:
-            "Every active article carrying this tag (selector 3). Requires confirm:true.",
-        },
-        confirm: {
-          type: "boolean",
-          description: "Required (true) when selecting by tag — guards the high blast radius.",
+            "Every active article carrying this tag (selector 3). Two-step even for the soft " +
+            "archive: dry_run:true for a meta.token, then replay it. There is no confirm flag.",
         },
         dry_run: {
           type: "boolean",
           description:
-            "Preview only — mutate nothing. Returns meta.would_affect; with hard:true also a " +
-            "single-use meta.token (or meta.confirm_hash for oversized selectors).",
+            "Preview only — mutate nothing. Returns meta.would_affect, plus the single-use " +
+            "meta.token for a hard delete or a tag archive (or meta.confirm_hash for oversized " +
+            "selectors).",
         },
         hard: {
           type: "boolean",
@@ -5739,14 +5766,17 @@ const TOOLS = [
         token: {
           type: "string",
           description:
-            "The single-use frozen-set token from a `dry_run:true, hard:true` preview. Required " +
-            "for the hard delete.",
+            "The single-use frozen-set token from a dry_run preview. Required for a hard delete " +
+            "and for a tag archive, and replayed with the SAME selector. Typed by op AND by " +
+            "selector: an archive token is not spendable as a delete, and a token minted for " +
+            "one tag is refused on a call naming another.",
         },
         confirm_hash: {
           type: "string",
           description:
-            "For an oversized hard-delete selector (no token): the meta.confirm_hash from the " +
-            "dry-run, echoed back to re-confirm the id-set hasn't drifted.",
+            "For an oversized selector (no token was minted): the meta.confirm_hash from the " +
+            "dry-run, echoed back to re-confirm the id-set hasn't drifted. Applies to an " +
+            "oversized hard delete and an oversized tag archive.",
         },
       },
       required: [],

package/lib/search-notices.js

@@ -1,6 +1,6 @@
 /**
  * Leading notices for search results whose META carries something the agent must act on
- * (#658).
+ * (#658), now driven by the uniform tool-outcome envelope.
  *
  * THE DEFECT THIS FIXES. When semantic ranking is unavailable the server degrades to
  * keyword-only and says so LOUDLY — `meta.fallback: true`, `meta.degraded: true`,
@@ -16,15 +16,50 @@
  * The remedy the agent needs is the opposite of the obvious one: do NOT rephrase. Different
  * words cannot fix a provider timeout. Retry the SAME query.
  *
+ * WHAT `meta.outcome` ADDS. The knowledge, memory and corpus RETRIEVAL responses (plus the
+ * `knowledge_list` enumeration path) now carry one of `success | empty | degraded |
+ * fallback | error`, so the notice no longer has to infer the class from a handful of
+ * per-surface flag names. Three classes get a notice, and they get DIFFERENT ones because
+ * the remedies differ:
+ *
+ *   - `fallback` — the semantic lane died, keyword-only was served. Retry the SAME query.
+ *   - `degraded` — a half was shed or capacity-limited. WAIT, then retry. Retrying at once
+ *     goes straight back into the same closed gate, which is why this is not worded as a
+ *     fallback. Some causes are STANDING rather than transient (`STANDING_REASONS`) and
+ *     get a remedy that does not prescribe a wait no wait can clear.
+ *   - `error`    — the retrieval never ran; the empty envelope is a placeholder and says
+ *     NOTHING about what the corpus holds.
+ *
+ * `empty` and `success` get NO notice on purpose. A notice on every ordinary zero-result
+ * search is noise, and noise teaches agents to ignore the channel — the exact fate of the
+ * `meta` fields this exists to replace. The distinction the agent needs is still on the
+ * wire: the rendered JSON carries `meta.outcome: "empty"` next to a `degraded` one that
+ * arrives with a shouting banner above it.
+ *
  * This mirrors the existing BYO-LLM `no_embedding_key` ACTION REQUIRED notice, which
  * already established that a meta-only disclosure is not enough to change behaviour.
  */
 
+/** The server's published vocabulary (LoopctlWeb.Outcome). */
+const OUTCOMES = ["success", "empty", "degraded", "fallback", "error"];
+
 /** True when a result degraded to a fallback lane, whatever the cause. */
 function isDegraded(meta) {
   return Boolean(meta && (meta.fallback === true || meta.degraded === true));
 }
 
+/**
+ * The server-declared outcome, or null when this response predates the envelope.
+ *
+ * Validated against the published list rather than passed through: an unrecognised value
+ * means a server newer than this client, and inventing a notice for a class we do not
+ * understand is worse than falling back to the flag heuristics below.
+ */
+function outcomeOf(result) {
+  const value = result && result.meta && result.meta.outcome;
+  return OUTCOMES.includes(value) ? value : null;
+}
+
 function resultCount(result) {
   if (!result || typeof result !== "object") return null;
   if (Array.isArray(result.data)) return result.data.length;
@@ -33,23 +68,143 @@ function resultCount(result) {
 }
 
 /**
- * Returns a notice string when a search DEGRADED, or null otherwise.
+ * The most specific bounded tag the response names, or a synthesised one.
  *
- * The empty case gets the strong wording because it is the one that misleads: an empty
- * degraded response is indistinguishable from a genuine miss. A degraded response that
- * still returned rows gets a softer note — the results are real but the ranking was not
- * the one requested, so they may be incomplete.
+ * Every surface publishes its cause under its own key; this picks whichever is present so
+ * the notice can NAME the cause. An unnamed degradation is much weaker advice — "something
+ * was short" does not tell an agent whether to wait or to reconfigure.
+ */
+function reasonOf(meta) {
+  const named =
+    meta.fallback_reason ||
+    meta.degraded_reason ||
+    meta.reason ||
+    meta.semantic_unavailable_reason ||
+    meta.keyword_unavailable_reason;
+
+  if (typeof named === "string" && named !== "") return named;
+  if (meta.semantic_under_filled === true) return "semantic_under_filled";
+  if (meta.ann_iterative_scan === "unavailable") return "ann_iterative_scan_unavailable";
+  return "unspecified";
+}
+
+function fallbackNotice(reason, count) {
+  if (count === 0) {
+    return (
+      `outcome: fallback — DEGRADED SEARCH, THIS IS NOT "NO RESULTS". Semantic ranking ` +
+      `was unavailable (${reason}), so this ran keyword-only, and the keyword lane ` +
+      `requires ALL terms to match — a long or specific query returns nothing even when ` +
+      `the answer exists. Do NOT conclude the knowledge base lacks this, and do NOT ` +
+      `rephrase: different words cannot fix a provider failure. RETRY THE SAME QUERY.`
+    );
+  }
+
+  return (
+    `outcome: fallback — PARTIAL SEARCH. Semantic ranking was unavailable (${reason}), so ` +
+    `these are keyword-only matches and may be incomplete. Retry the same query for full ` +
+    `ranking.`
+  );
+}
+
+/**
+ * Degradations that WAITING cannot clear, so the notice must not prescribe a wait.
+ *
+ * `ann_iterative_scan_unavailable` — the deployed pgvector ran the vector read without
+ * the iterative scan the operator enabled, and the tenant filter was applied after a
+ * single index batch, so the page may be short. The conclusive cause (pgvector < 0.8,
+ * or the extension absent) stands until the extension is upgraded.
+ *
+ * `embedding_dimension_mismatch` — the memory half's active embedding dimension does not
+ * match the stored one, so that half did not run at all. Beside rows from the other half
+ * the server classifies it `degraded` (a partial read, not a dead request), which is
+ * right — but only an operator can restore the half.
+ *
+ * Both re-run identically on retry and burn a heavy read for nothing.
+ */
+const STANDING_REASONS = new Set([
+  "ann_iterative_scan_unavailable",
+  "embedding_dimension_mismatch",
+]);
+
+function degradedNotice(reason, count) {
+  if (STANDING_REASONS.has(reason)) {
+    const scope = count === 0 ? `THIS IS NOT "NO RESULTS"` : `PARTIAL RESULTS`;
+
+    return (
+      `outcome: degraded — ${scope}. A half of this retrieval ran short or not at all ` +
+      `(${reason}), so it may have returned FEWER rows than match and its absences ` +
+      `prove nothing. Retrying re-runs the identical read and does NOT clear this — it ` +
+      `is a standing backend condition an operator has to fix. Use what you got, widen ` +
+      `the filters, or reach for a non-vector route (knowledge_list, knowledge_heat_index).`
+    );
+  }
+
+  if (count === 0) {
+    return (
+      `outcome: degraded — THIS IS NOT "NO RESULTS". A half of this retrieval was shed or ` +
+      `capacity-limited (${reason}), so the corpus was never fully read. Do NOT conclude ` +
+      `the knowledge base lacks this, and do NOT rephrase — the wording had no part in ` +
+      `it. WAIT a few seconds, then RETRY THE SAME QUERY; an immediate retry goes back ` +
+      `into the same closed gate.`
+    );
+  }
+
+  return (
+    `outcome: degraded — PARTIAL RESULTS. A half was shed or capacity-limited ` +
+    `(${reason}), so this set may be SHORT and its absences prove nothing. Wait a few ` +
+    `seconds, then retry the same query for the full set.`
+  );
+}
+
+function errorNotice(reason) {
+  return (
+    `outcome: error — THE RETRIEVAL DID NOT RUN (${reason}); this empty envelope was ` +
+    `served in its place. It says NOTHING about what the knowledge base holds. Fix the ` +
+    `request, then retry.`
+  );
+}
+
+/**
+ * Returns a notice string when a search needs one, or null otherwise.
+ *
+ * Prefers the server-declared `meta.outcome`; falls back to the pre-envelope flag
+ * heuristics so an older server still gets the #658 notice it used to.
+ *
+ * The zero-result cases get the strong wording because they are the ones that mislead: an
+ * empty degraded response is indistinguishable from a genuine miss. A degraded response
+ * that still returned rows gets a softer note — the results are real but the retrieval was
+ * not the one requested, so they may be incomplete.
  */
 function degradedSearchNotice(result) {
   const meta = result && result.meta;
-  if (!isDegraded(meta)) return null;
+  if (!meta || typeof meta !== "object") return null;
 
   // The BYO-key case already has its own, more specific ACTION REQUIRED notice; do not
   // stack two notices on one result.
   if (meta.fallback_reason === "no_embedding_key") return null;
 
-  const reason = meta.fallback_reason || "unknown";
   const count = resultCount(result);
+  const outcome = outcomeOf(result);
+
+  if (outcome) {
+    switch (outcome) {
+      case "fallback":
+        return fallbackNotice(reasonOf(meta), count);
+      case "degraded":
+        return degradedNotice(reasonOf(meta), count);
+      case "error":
+        return errorNotice(reasonOf(meta));
+      default:
+        // success / empty — silence is the signal, see the module header.
+        return null;
+    }
+  }
+
+  if (!isDegraded(meta)) return null;
+
+  // Pre-envelope server: one class, the historical wording, and no `outcome:` prefix to
+  // claim a classification the server never made.
+  const reason = meta.fallback_reason || "unknown";
 
   if (count === 0) {
     return (
@@ -67,4 +222,4 @@ function degradedSearchNotice(result) {
   );
 }
 
-export { degradedSearchNotice, isDegraded };
+export { degradedSearchNotice, isDegraded, outcomeOf, OUTCOMES };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.78.2",
+  "version": "2.85.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",