loopctl-mcp-server 2.80.0 → 2.85.0

package/README.md

@@ -268,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`. |
@@ -277,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`. |
@@ -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)
@@ -399,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 }) {
@@ -3076,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 }) {

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