loopctl-mcp-server 2.80.0 → 2.86.0

package/README.md

@@ -268,23 +268,50 @@ 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`. |
+| `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`/`suppressed_at`/`suppressed_by`/`suppression_reason` explicitly; `id` and `category` are always included) to keep the payload small. Pair `suppressed: "only"` with `fields: suppressed_by,suppression_reason` to see who suppressed what and why without a read per row. Optional: `project_id`, `story_id`, `category`, `tags`, `offset`, `limit`, `fields`, `suppressed`. |
 | `embedding_status` | This tenant's embedding-dimension state: active dimension, whether semantic recall is available (and the exact reason when it is not), the instance's supported dimension set, whether the shared system-scoped corpus has been materialized for this tenant, and per-dimension row counts. Call it when semantic search under-returns or reports `fallback_reason: semantic_recall_unavailable`. |
 | `embedding_materialize_system_corpus` | Embed the shared SYSTEM-scoped corpus for THIS tenant at its active dimension with this tenant's own credential (system articles are keyword-only until then). Idempotent, batched. |
 | `embedding_reembed` | Move the tenant's whole corpus (articles, per-tenant system-article materializations and agent memories) onto `target_dimension`. Recall keeps serving at the current dimension throughout; the pin flips and stale rows drop only when everything is present at the target. One-time and cost-bearing; requires `LOOPCTL_ORCH_KEY`. |
 | `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 (suppressed articles are excluded, matching `knowledge_index` — except on an `idempotency_key` filter, which is an identity check and still sees them) — 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. Pass `suppressed: "include"` when a repair pass must see the whole table, or `"only"` to list what there is to undo. 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`, `suppressed`. 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`. |
@@ -311,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)
@@ -327,6 +354,8 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_unpublish` | **Requires `LOOPCTL_USER_KEY`.** Revert a published article back to draft (hidden from search/context, not deleted). Required: `article_id`. |
 | `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_suppress` | Take an article OUT OF RETRIEVAL without changing its status, **reversibly** — the tombstone. Status stays `published`; body, embedding and links are untouched; the article is STILL readable by id with `knowledge_get`, which renders `suppressed_at`/`suppressed_by`/`suppression_reason`. It disappears from `knowledge_search`, `knowledge_hybrid_search`, `knowledge_context`, `/recall`, `knowledge_progressive_index`, `knowledge_heat_index`, suggested links, `knowledge_graph`, `knowledge_walk`, the novelty priors and the nightly consolidation scans. Pick between the three retraction verbs by what you need afterwards: **suppress** = undoable and says nothing about status, **`knowledge_unpublish`** = undoable but claims the article is a draft, **`knowledge_archive`/`knowledge_delete`** = not undoable by any call you can make. Re-suppressing is an idempotent no-op that keeps the ORIGINAL actor and reason. Agent role, visibility-scoped. Required: `article_id`, `reason` (non-blank, <=500 chars). |
+| `knowledge_unsuppress` | Lift a retrieval suppression — the inverse of `knowledge_suppress`. Restores the article to every read path immediately; nothing is re-embedded or re-linked because suppression never touched them. A no-op on an article that is not suppressed. Does NOT undo `knowledge_archive`. Agent role, visibility-scoped. 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` (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`. |
@@ -399,7 +428,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

@@ -1337,7 +1337,7 @@ async function setTokenBudget({ scope_type, scope_id, budget_millicents, alert_t
 
 // --- Knowledge Wiki Tools (agent key) ---
 
-async function knowledgeIndex({ project_id, story_id, category, tags, match, offset, limit, fields }) {
+async function knowledgeIndex({ project_id, story_id, category, tags, match, offset, limit, fields, suppressed }) {
   if (project_id && !UUID_RE.test(project_id)) {
     return {
       content: [{ type: "text", text: "Error: project_id must be a canonical UUID (8-4-4-4-12 hex)." }],
@@ -1355,6 +1355,7 @@ async function knowledgeIndex({ project_id, story_id, category, tags, match, off
   if (offset != null) params.set("offset", String(offset));
   if (limit != null) params.set("limit", String(limit));
   if (fields) params.set("fields", Array.isArray(fields) ? fields.join(",") : fields);
+  if (suppressed) params.set("suppressed", suppressed);
   const qs = params.toString();
   const path = qs ? `${basePath}?${qs}` : basePath;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
@@ -1590,7 +1591,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 +1609,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 }) {
@@ -1639,6 +1645,7 @@ async function knowledgeList({
   limit,
   offset,
   include_body,
+  suppressed,
 }) {
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
@@ -1654,6 +1661,11 @@ async function knowledgeList({
   // Body-less summary by default (safe to enumerate large pages); opt into full
   // bodies (byte-budget bounded server-side) with include_body: true.
   if (include_body === true) params.set("include_body", "true");
+  // Sent only when the caller asked. The server's default is per-filter — exclude
+  // everywhere except an idempotency_key lookup, which includes suppressed rows so an
+  // identity check cannot mint a duplicate — and sending a computed "exclude" on every
+  // call would overwrite that.
+  if (suppressed) params.set("suppressed", suppressed);
 
   const result = await apiCall(
     "GET",
@@ -1661,7 +1673,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 +1851,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 +1874,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 }) {
@@ -2000,6 +2019,29 @@ async function knowledgeArchive({ article_id }) {
   return toContent(result);
 }
 
+// The REVERSIBLE retrieval tombstone. Agent-role KB curation like archive, but it is the
+// one member of that family that undoes: nothing is destroyed and nothing is rebuilt, so
+// knowledge_unsuppress restores the article to every read path immediately.
+async function knowledgeSuppress({ article_id, reason }) {
+  const result = await apiCall(
+    "POST",
+    `/api/v1/articles/${article_id}/suppress`,
+    { reason },
+    process.env.LOOPCTL_AGENT_KEY
+  );
+  return toContent(result);
+}
+
+async function knowledgeUnsuppress({ article_id }) {
+  const result = await apiCall(
+    "POST",
+    `/api/v1/articles/${article_id}/unsuppress`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY
+  );
+  return toContent(result);
+}
+
 // #331: soft-delete (archive) is agent-role KB curation, same as knowledge_archive.
 async function knowledgeDelete({ article_id }) {
   const result = await apiCall(
@@ -3076,8 +3118,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 }) {
@@ -4356,10 +4400,29 @@ const TOOLS = [
           type: "array",
           items: {
             type: "string",
-            enum: ["id", "title", "category", "tags", "status", "updated_at"],
+            enum: [
+              "id",
+              "title",
+              "category",
+              "tags",
+              "status",
+              "updated_at",
+              "suppressed_at",
+              "suppressed_by",
+              "suppression_reason",
+            ],
           },
           description:
-            "Optional: projection of article fields to return. Default: id, title, category. `id` is always included.",
+            "Optional: projection of article fields to return. Default: id, title, category. `id` is always included. " +
+            "Pair suppressed='only' with fields=suppressed_by,suppression_reason to see who suppressed what and why without a per-row read.",
+        },
+        suppressed: {
+          type: "string",
+          enum: ["exclude", "include", "only"],
+          description:
+            "Optional: how to treat RETRIEVAL-SUPPRESSED articles — 'exclude' (default), 'include', or " +
+            "'only'. 'only' is the discovery path: it lists exactly what there is to undo with " +
+            "knowledge_unsuppress, across every status. An unrecognised value resolves to 'exclude'.",
         },
       },
       required: [],
@@ -4382,7 +4445,11 @@ const TOOLS = [
       "`meta.total_count` (exact) to answer \"does an article for X already exist?\" reliably " +
       "right after a write — `idempotency_key` is a FILTER only and is never returned in a " +
       "row, so you check a key you already hold rather than reading back the keys other " +
-      "callers chose. Paginate via offset/limit.",
+      "callers chose. Suppressed articles are EXCLUDED here (matching knowledge_index) except " +
+      "on an `idempotency_key` filter, which is an identity check on a key you already hold " +
+      "and still sees them — so the existence check stays true about the row a create would " +
+      "dedup against. Pass `suppressed: 'include'` when a repair pass must see the whole " +
+      "table, or `'only'` to list what there is to undo. Paginate via offset/limit.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4442,6 +4509,17 @@ const TOOLS = [
             "rows); continue via meta.next_offset while meta.has_more is true. Leave false to " +
             "enumerate metadata cheaply at scale.",
         },
+        suppressed: {
+          type: "string",
+          enum: ["exclude", "include", "only"],
+          description:
+            "Optional: how to treat RETRIEVAL-SUPPRESSED articles — 'exclude' (the default on " +
+            "every filter but idempotency_key), 'include', or 'only'. Pass 'include' when a " +
+            "repair or audit pass must see the whole table, and 'only' to list exactly what " +
+            "there is to undo with knowledge_unsuppress. Omit it to keep the per-filter " +
+            "default. The body-less rows do NOT carry the three suppressed_* fields — pair " +
+            "with include_body: true, or read knowledge_get, to see who suppressed what and why.",
+        },
       },
       required: [],
     },
@@ -5664,6 +5742,69 @@ const TOOLS = [
       required: ["article_id"],
     },
   },
+  {
+    name: "knowledge_suppress",
+    description:
+      "Take an article OUT OF RETRIEVAL without changing its status — reversibly. This is " +
+      "the tool to reach for when an article is wrong, superseded, noisy or no longer " +
+      "wanted in results, but you might want it back. The article stays `published`, keeps " +
+      "its body, embedding and links, and is STILL readable by id with knowledge_get " +
+      "(which renders suppressed_at / suppressed_by / suppression_reason) — that is what " +
+      "makes the act inspectable and undoable. It disappears from knowledge_search, " +
+      "knowledge_hybrid_search, knowledge_context, /recall, knowledge_progressive_index, " +
+      "knowledge_heat_index, suggested links, knowledge_graph, knowledge_walk, the novelty " +
+      "priors and the nightly consolidation scans. " +
+      "Undo with knowledge_unsuppress; nothing was destroyed, so nothing is rebuilt. " +
+      "Choose between the three retraction verbs by what you need afterwards: " +
+      "knowledge_suppress (undoable, status untouched, the article is simply not retrieved), " +
+      "knowledge_unpublish (undoable, but it says the article is a DRAFT — an editorial " +
+      "claim), knowledge_archive/knowledge_delete (NOT undoable by any call you can make: " +
+      "`:archived` is terminal). " +
+      "A reason is REQUIRED — a tombstone that does not record why is not inspectable. " +
+      "Re-suppressing an already-suppressed article is an idempotent no-op that KEEPS the " +
+      "original actor and reason; to change a recorded reason, unsuppress and suppress " +
+      "again, which records both acts. " +
+      "Agent role. Visibility-scoped: you can only suppress an article you can see, so " +
+      "another agent's private/owner memory returns 404.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          description: "The UUID of the article to take out of retrieval.",
+        },
+        reason: {
+          type: "string",
+          description:
+            "Why this article should stop being retrieved. Required and non-blank; " +
+            "bounded at 500 characters. Recorded on the row and in the audit log, and " +
+            "returned by knowledge_get, so write it for whoever decides later whether to " +
+            "undo this.",
+        },
+      },
+      required: ["article_id", "reason"],
+    },
+  },
+  {
+    name: "knowledge_unsuppress",
+    description:
+      "Lift a retrieval suppression: the inverse of knowledge_suppress. Clears the " +
+      "tombstone and restores the article to search, context, /recall, the indexes, the " +
+      "graph and the link surfaces immediately — nothing has to be re-embedded or " +
+      "re-linked, because suppression never touched any of it. Unsuppressing an article " +
+      "that is not suppressed is a harmless no-op. Agent role, visibility-scoped. " +
+      "This does NOT undo knowledge_archive or knowledge_delete, which are terminal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          description: "The UUID of the article to restore to retrieval.",
+        },
+      },
+      required: ["article_id"],
+    },
+  },
   {
     name: "knowledge_delete",
     description:
@@ -7908,6 +8049,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_archive":
       return await knowledgeArchive(args);
 
+    case "knowledge_suppress":
+      return await knowledgeSuppress(args);
+
+    case "knowledge_unsuppress":
+      return await knowledgeUnsuppress(args);
+
     case "knowledge_delete":
       return await knowledgeDelete(args);
 

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.80.0",
+  "version": "2.86.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",