loopctl-mcp-server 2.72.0 → 2.73.0

package/README.md

@@ -251,21 +251,21 @@ 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.** `q` 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`). Optional: `project_id`, `story_id` for attribution. |
+| `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: `topic`. Optional: `category`, `limit`. |
+| `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_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`, `idempotency_key`, 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). 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`. |
 | `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_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). Required: `article_id`. Optional: `threshold` (cosine floor 0–1, default 0.5), `limit` (default 5). |
+| `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`. |
 | `knowledge_novelty` | Score ideas by novelty: embeds each idea's text, returns `novelty_score` = cosine distance to the nearest **visible** prior proposal (0 = identical, higher = more novel, up to 2.0; `null` when the idea text is blank, no visible priors exist, or embedding fails — see `meta.prior_count`). Agent callers see only their own and `shared` articles as priors. Priors default to articles tagged `proposal`. Provide ideas as `texts` (strings) OR `ideas` (strings or objects), ≤50. Optional: `prior_tag`. |
 | `knowledge_random_walk` | Random walk through the link graph from `start_id` (no cycles, up to `length` nodes), traversing only **agent's visible published articles**, surfacing unexpected connections. Agent callers see only their own and `shared` articles. Returns `{id, title, category}` in walk order. Required: `start_id`. Optional: `length` (default 4, max 25). |
 | `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`. |
-| `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Last-write-wins per pair. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence`, `confidence`. |
+| `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Last-write-wins per pair. **`supersede` is the one disposition that retires an article unattended**, so its `confidence` is capped server-side: an agent-role `"high"` is recorded as `"medium"` (`data.requested_confidence` + `note` say so) and the pair stays in `knowledge_conflicts` until an orchestrator+ key records it at high; a `high` supersede also REQUIRES `evidence` (422 without it). `merge` is never capped. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence` (required for a high supersede), `confidence`. |
 | `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). RESERVED TAG NAMESPACE: a tag starting with `idem-` must be `idem-<family>-<digest>` (digest = 12 or 40 lowercase hex chars, e.g. `idem-url-7ebe1ca33431`) or the write is rejected 422 — never silently rewritten; put topics outside that prefix and use `idempotency_key` for idempotent capture. Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
 | `knowledge_update` | Edit an EXISTING article IN PLACE, **preserving its ID** (IDs are load-bearing — cited in project CLAUDE.mds and cross-links). Fold in a new fact, tidy a hub, retag, or reclassify without churning a new row. Send only the fields to change; `tags` REPLACES the whole array. A changed body/tags re-triggers embedding + auto-linking. Agent role — KB-content curation (non-destructive + audited; the in-place edit overwrites the prior body, so it is not reversible either); visibility-scoped, so another agent's private/owner memory 404s. The reserved `idem-` tag namespace applies here too (see `knowledge_create`). Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |
@@ -284,11 +284,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. 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`. |
 | `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). 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`. |
 | `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)
@@ -379,14 +379,14 @@ Key distribution for the dispatch pattern (Epic 26): per-dispatch ephemeral keys
 | Tool | Description |
 |---|---|
 | `signup` | **US-26.7.1.** Create a NEW **agent-rooted (KB-tier)** tenant and mint its one-time root API key — entirely through this call, no human operator, no hardware authenticator, no existing API key required. The tenant gets the FULL knowledge-wiki surface but **cannot** perform work-breakdown / chain-of-custody operations (those require a separate human-anchored tenant via the WebAuthn ceremony at `https://loopctl.com/signup`). Rate-limited per client IP (<= 5/hour). The `raw_key` is shown ONCE — save it immediately (e.g. as `LOOPCTL_USER_KEY`). Required: `name`, `slug`, `email`. |
-| `dispatch` | Mint an ephemeral, scoped api_key for a sub-agent dispatch, carrying its lineage path. The `raw_key` is returned ONCE — pass it to the sub-agent's launch args, never store it in env vars; it expires after `expires_in_seconds` (default 3600, max 14400). Required: `role` (`agent`/`orchestrator`), `agent_id`. Optional: `parent_dispatch_id`, `story_id`. **LCP-1 §9.2 signed profile:** optionally enroll an agent key via `agent_pubkey` (hex) + `alg` + an `attestation` (from `custody_sign_attestation`) + `attestation_conditions`. |
+| `dispatch` | Mint an ephemeral, scoped api_key for a sub-agent dispatch, carrying its lineage path. The `raw_key` is returned ONCE — pass it to the sub-agent's launch args, never store it in env vars; it expires after `expires_in_seconds` (default 3600, max 14400). Required: `role` (`agent`/`orchestrator`), `agent_id`, and `parent_dispatch_id` for every caller a dispatch minted — a dispatch may only be minted INSIDE the caller's own lineage. Omitting `parent_dispatch_id` requests a ROOT dispatch (a new independent lineage tree), which only the tenant's `user`-role operator key may create; anyone else gets `403 root_dispatch_forbidden` with their own dispatch id in `remediation.your_dispatch_id`. A parent outside the caller's lineage is `403 parent_outside_caller_lineage`. Optional: `story_id`. **LCP-1 §9.2 signed profile:** optionally enroll an agent key via `agent_pubkey` (hex) + `alg` + an `attestation` (from `custody_sign_attestation`) + `attestation_conditions`. |
 | `register_custody_owner_key` | **LCP-1 §9.2.** Register/rotate the tenant custody OWNER key — the root of trust the attestation chain hangs from. Private half stays with you; requires `LOOPCTL_USER_KEY` and a human-anchored tenant. Required: `owner_pubkey` (hex). ROTATION additionally requires `rotation_proof` (from `custody_sign_owner_rotation`); first registration needs none. |
 | `list_enrolled_agent_keys` | **LCP-1 §9.1.1 transparency.** List the agent public keys enrolled under your tenant, reconstructed from the tamper-evident audit chain (not a mutable listing). Compare against the keys you generated; any excess is operator-minted. Keyset-paged (`limit`, `cursor`). |
 | `custody_generate_keypair` | **LCP-1 §9.** Generate an Ed25519 keypair LOCALLY (private key never leaves the process). Returns `public_key_hex` + `private_key_hex`. |
 | `custody_sign_attestation` | **LCP-1 §9.2.** Sign an attestation over an agent key to enroll it — with the OWNER private key (root, `lineage_path: []`) or the PARENT agent private key (child, `lineage_path` = parent's). Returns the hex `attestation` for `dispatch`. |
 | `custody_sign_claim` | **LCP-1 §9.3.** Sign a custody claim with your enrolled agent private key. Returns a `claim` object to pass as the `claim` param to `report_story`/`review_complete`/`verify_story` when the deployment runs the signed profile. |
 | `custody_sign_owner_rotation` | **LCP-1 §9.2.** Sign an owner-key ROTATION proof with the OUTGOING owner private key, proving possession before it re-roots the attestation chain. Binds the old key + its set-at (Unix microseconds) so a captured proof is not replayable after a rotate-back. Returns `rotation_proof` for `register_custody_owner_key`. |
-| `recover_cap` | Re-mint a capability token for a story you're assigned to, after a session crash lost your cap. Required: `story_id`. Optional: `cap_type` (`start_cap`/`report_cap`, default `start_cap`), `lineage`. |
+| `recover_cap` | Re-mint the `start_cap` for a story you're assigned to, after a session crash lost your cap. Required: `story_id`. No other parameters: recovery only ever mints a `start_cap` (any other `cap_type` is a 422 AND is recorded as a forgery attempt), and the lineage is always derived server-side. |
 | `get_sth` | Get the latest Signed Tree Head for a tenant's tamper-evident audit chain. Public — no auth required. Required: `tenant_id`. |
 | `request_authenticator_challenge` | **US-26.7.2.** Step 1 of the opt-in WebAuthn trust-tier upgrade ceremony: issues a registration challenge for enrolling a hardware authenticator against an EXISTING agent-rooted (KB-tier) tenant, promoting it to `human_anchored` on success. Requires an interactive WebAuthn client. |
 | `enroll_authenticator` | Step 2 of the WebAuthn trust-tier upgrade ceremony: completes enrollment with the attestation produced by `navigator.credentials.create()` against the challenge from `request_authenticator_challenge`. On a tenant's first enrollment the tenant is promoted to `human_anchored`. |

package/index.js

@@ -15,6 +15,9 @@ import os from "node:os";
 import crypto from "node:crypto";
 import { fileURLToPath } from "node:url";
 import path, { dirname, join } from "node:path";
+import { applyArgAliases } from "./lib/arg-aliases.js";
+import { clientContextHeader } from "./lib/client-context.js";
+import { degradedSearchNotice } from "./lib/search-notices.js";
 import {
   projectsPath,
   ingestionJobsPath,
@@ -115,6 +118,19 @@ function resolveKey(keyOverride) {
   );
 }
 
+let clientContextHeaderCache;
+function cachedClientContextHeader() {
+  if (clientContextHeaderCache === undefined) {
+    try {
+      clientContextHeaderCache = clientContextHeader({ version: SERVER_VERSION }) || null;
+    } catch {
+      // Analytics must never break a tool call.
+      clientContextHeaderCache = null;
+    }
+  }
+  return clientContextHeaderCache;
+}
+
 async function apiCall(method, path, body, keyOverride, { exactKey = false, timeoutMs } = {}) {
   const url = `${getBaseUrl()}${path}`;
   // Secret-managing tools pass exactKey:true so the request uses the EXACT
@@ -139,6 +155,14 @@ async function apiCall(method, path, body, keyOverride, { exactKey = false, time
     Accept: "application/json",
   };
 
+  // #658: client-asserted context (session id, main-vs-child, repo, effort). None of it is
+  // derivable server-side — an api key names a KEY, and under the v2 dispatch pattern a key
+  // is minted per dispatch. UNTRUSTED and analytics-only; the server stores it under a
+  // `client_` prefix and never authorizes on it. Computed once: the environment does not
+  // change mid-process, and a per-call `os.hostname()` + git shell-out is not hot-path work.
+  const clientCtx = cachedClientContextHeader();
+  if (clientCtx) headers["x-loopctl-client-context"] = clientCtx;
+
   const serializedBody =
     body !== undefined && body !== null ? JSON.stringify(body) : undefined;
 
@@ -355,7 +379,10 @@ function llmRemediationNotice(result) {
  */
 function withRemediationNotice(result) {
   const base = toContent(result);
-  const notice = llmRemediationNotice(result);
+  // Two notice sources, in priority order: the BYO-key remediation (more specific), then
+  // the degraded-search notice (#658). At most one is prepended — stacking two leading
+  // blocks buries both. `degradedSearchNotice` already declines the no_embedding_key case.
+  const notice = llmRemediationNotice(result) || degradedSearchNotice(result);
   if (!notice) return base;
   return { ...base, content: [{ type: "text", text: notice }, ...base.content] };
 }
@@ -952,6 +979,103 @@ async function contractStory({ story_id, story_title, ac_count }) {
   return toContent(result);
 }
 
+// --- L1 capability plumbing (issue #621) ---
+//
+// A tenant with an audit signing key MUST present a capability token on the
+// custody transitions that consume one, or the call fails 403 missing_capability.
+// `start` is the only such transition (#621): claim returns the start_cap it mints.
+// Callers should not have to carry it by hand — so we cache what the server issues
+// and attach it automatically, while still honouring an explicit `capability`.
+//
+// The cache is per-process and therefore does NOT survive a session crash. That is
+// what the recovery paths below are for; never treat a cache miss as fatal.
+// Bounded so a long-lived server process cannot grow these without limit: this
+// module lives for the life of the MCP connection and sees every story the agent
+// touches. Insertion order is Map/Set iteration order in JS, so evicting the
+// first key drops the oldest entry.
+const CAP_CACHE_MAX = 256;
+const SPENT_CAPS_MAX = 1024;
+
+function boundedSet(store, max) {
+  while (store.size > max) {
+    const oldest = store.keys().next();
+    if (oldest.done) break;
+    store.delete(oldest.value);
+  }
+}
+
+const capCache = new Map();
+
+const capKey = (storyId, typ) => `${storyId}:${typ}`;
+
+function rememberCap(storyId, cap) {
+  if (cap && cap.cap_id && cap.typ) {
+    // Store the expiry alongside the id. A capability has a bounded TTL, and an
+    // agent can sit between claim and start for longer than that (a review pause,
+    // a crash-and-resume) — handing back a dead token afterwards costs a
+    // round-trip and surfaces a confusing refusal instead of the recovery path.
+    capCache.set(capKey(storyId, cap.typ), {
+      capId: cap.cap_id,
+      expiresAt: cap.expires_at ? Date.parse(cap.expires_at) : null,
+    });
+    boundedSet(capCache, CAP_CACHE_MAX);
+  }
+}
+
+function takeCap(storyId, typ) {
+  const key = capKey(storyId, typ);
+  const entry = capCache.get(key);
+  // Capabilities are single-use: once handed to a call, drop it so a retry does
+  // not present the same live token twice.
+  capCache.delete(key);
+  if (!entry) return undefined;
+  // Treat an unparseable expiry as usable — the server is the authority on
+  // expiry, and refusing here on a date we failed to parse would strand a token
+  // that is actually fine.
+  if (entry.expiresAt && Date.now() >= entry.expiresAt) return undefined;
+  return entry.capId;
+}
+
+// Cap ids this process has already handed to a call. Delivery is stateless
+// server-side and does NOT consume, so without this a retry (or a second tool
+// call) would present the same live token twice — and a double consume is
+// `:replay`, which IS byzantine and halts the whole tenant. takeCap gets the
+// same property for free by deleting on read.
+const spentCaps = new Set();
+
+// Fetches a live capability of `typ` already issued to this caller's lineage.
+// Returns undefined when there is none — callers must degrade gracefully.
+async function fetchCap(storyId, typ, key) {
+  try {
+    const result = await apiCall("GET", `/api/v1/stories/${storyId}/capabilities`, null, key);
+    const caps = (result && result.data) || [];
+    const match = caps.find((c) => c.typ === typ && !spentCaps.has(c.cap_id));
+    if (!match) return undefined;
+    spentCaps.add(match.cap_id);
+    boundedSet(spentCaps, SPENT_CAPS_MAX);
+    return match.cap_id;
+  } catch {
+    return undefined;
+  }
+}
+
+// Re-mints a start_cap for a story this agent owns (session-crash recovery).
+// Only start_cap is recoverable by design — an agent must never be able to mint a
+// capability to verify or report its own work.
+async function recoverStartCap(storyId) {
+  try {
+    const result = await apiCall(
+      "POST",
+      `/api/v1/stories/${storyId}/recover-cap`,
+      null,
+      process.env.LOOPCTL_AGENT_KEY
+    );
+    return result && result.data && result.data.cap_id;
+  } catch {
+    return undefined;
+  }
+}
+
 async function claimStory({ story_id }) {
   const result = await apiCall(
     "POST",
@@ -959,14 +1083,25 @@ async function claimStory({ story_id }) {
     null,
     process.env.LOOPCTL_AGENT_KEY
   );
+  // The claim response carries the start_cap that POST /start will require.
+  rememberCap(story_id, result && result.capability);
   return toContent(result);
 }
 
-async function startStory({ story_id }) {
+async function startStory({ story_id, capability }) {
+  // Cache first, then DELIVERY of the token claim already minted, then recovery
+  // (which mints a fresh one). Delivery also covers a legacy env-var key, whose
+  // lineage is [] and which recover-cap cannot serve at all.
+  const cap =
+    capability ||
+    takeCap(story_id, "start_cap") ||
+    (await fetchCap(story_id, "start_cap", process.env.LOOPCTL_AGENT_KEY)) ||
+    (await recoverStartCap(story_id));
+
   const result = await apiCall(
     "POST",
     `/api/v1/stories/${story_id}/start`,
-    null,
+    cap ? { capability: cap } : null,
     process.env.LOOPCTL_AGENT_KEY
   );
   return toContent(result);
@@ -1024,6 +1159,9 @@ async function reviewComplete({ story_id, review_type, findings_count, fixes_cou
 
 // --- Verification Tools (orch key) ---
 
+// Verify consumes NO capability (#621): no token can be bound to the principal
+// this endpoint permits to spend it. The gate is structural — loopctl selects the
+// verifier lineage and compares it against the implementer's server-side.
 async function verifyStory({ story_id, summary, review_type, claim }) {
   const body = {};
   if (summary) body.summary = summary;
@@ -1399,9 +1537,13 @@ async function knowledgeHybridSearch({ query, project_id, category, tags, match,
   return withRemediationNotice(result);
 }
 
-async function knowledgeProgressiveIndex({ topic, category, limit }) {
+async function knowledgeProgressiveIndex({ topic, query, category, limit }) {
   const params = new URLSearchParams();
-  if (topic != null) params.set("topic", topic);
+  // The endpoint's parameter is `topic`; `query` is the canonical spelling this surface
+  // converged on (#652 item 6). An explicit `topic` still wins, so a caller passing both
+  // gets what it asked for.
+  const resolved = topic != null && topic !== "" ? topic : query;
+  if (resolved != null) params.set("topic", resolved);
   if (category) params.set("category", category);
   if (limit != null) params.set("limit", String(limit));
 
@@ -1429,10 +1571,19 @@ async function knowledgeHeatIndex({ category, limit, since }) {
   return toContent(result);
 }
 
-async function knowledgeProgressiveDrill({ article_id }) {
+async function knowledgeProgressiveDrill({ article_id, body_max_bytes, body_offset }) {
+  const params = new URLSearchParams();
+  // 0 is meaningful on both (whole body / start at the beginning), so test for
+  // null/undefined rather than truthiness.
+  if (body_max_bytes !== undefined && body_max_bytes !== null)
+    params.set("body_max_bytes", String(body_max_bytes));
+  if (body_offset !== undefined && body_offset !== null)
+    params.set("body_offset", String(body_offset));
+  const qs = params.toString();
+  const base = `/api/v1/knowledge/progressive/${article_id}`;
   const result = await apiCall(
     "GET",
-    `/api/v1/knowledge/progressive/${article_id}`,
+    qs ? `${base}?${qs}` : base,
     null,
     process.env.LOOPCTL_AGENT_KEY,
   );
@@ -1476,11 +1627,24 @@ async function knowledgeList({
   return toContent(result);
 }
 
-async function knowledgeGet({ article_id, project_id, story_id, links }) {
+async function knowledgeGet({
+  article_id,
+  project_id,
+  story_id,
+  links,
+  body_max_bytes,
+  body_offset,
+}) {
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
   if (links) params.set("links", links);
+  // 0 is meaningful on both (whole body / start at the beginning), so test for
+  // null/undefined rather than truthiness.
+  if (body_max_bytes !== undefined && body_max_bytes !== null)
+    params.set("body_max_bytes", String(body_max_bytes));
+  if (body_offset !== undefined && body_offset !== null)
+    params.set("body_offset", String(body_offset));
   const qs = params.toString();
   const path = qs ? `/api/v1/articles/${article_id}?${qs}` : `/api/v1/articles/${article_id}`;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
@@ -2772,9 +2936,12 @@ async function getSystemArticles({ slug, category } = {}) {
   return toContent(result);
 }
 
-// US-26: Cap recovery after session crash
-async function recoverCap({ story_id, cap_type, lineage }) {
-  const body = { cap_type: cap_type || "start_cap", lineage: lineage || [] };
+// US-26: Cap recovery after session crash. start_cap is the ONLY recoverable type
+// (#621) — the server answers any other cap_type with 422 AND records a
+// cap_recovery_forgery_attempt against the caller, so never forward one. `lineage`
+// is resolved server-side from the authenticating key and was always ignored.
+async function recoverCap({ story_id }) {
+  const body = { cap_type: "start_cap" };
   const result = await apiCall("POST", `/api/v1/stories/${story_id}/recover-cap`, body);
   return toContent(result);
 }
@@ -3563,7 +3730,10 @@ const TOOLS = [
   {
     name: "start_story",
     description:
-      "Agent starts work on a claimed story. Transitions assigned -> implementing. Uses the AGENT key.",
+      "Agent starts work on a claimed story. Transitions assigned -> implementing. Uses the AGENT key. " +
+      "The L1 capability (start_cap) is handled for you: it is taken from the claim_story response, " +
+      "and re-minted via recover-cap if this process lost it (e.g. after a session crash). " +
+      "Pass `capability` only to override that.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3571,6 +3741,13 @@ const TOOLS = [
           type: "string",
           description: "The UUID of the story.",
         },
+        capability: {
+          type: "string",
+          description:
+            "Optional start_cap cap_id. Normally omitted — supplied automatically from the " +
+            "claim response or recovered. A tenant with an audit signing key cannot start " +
+            "without one (403 missing_capability).",
+        },
       },
       required: ["story_id"],
     },
@@ -4023,7 +4200,7 @@ const TOOLS = [
     name: "knowledge_list",
     description:
       "List articles (id, title, category, status, tags, source_type, source_id, " +
-      "idempotency_key, timestamps), filtered and paginated. **Body-less summary by default** " +
+      "timestamps), filtered and paginated. **Body-less summary by default** " +
       "— the right tool to enumerate, dedup, or repair at scale (safe to page up to limit=1000). " +
       "Pass `include_body: true` to also return the full `body`, in which case the server bounds " +
       "the page by a ~5 MB serialized-body budget and returns meta.next_offset/has_more/" +
@@ -4034,7 +4211,9 @@ const TOOLS = [
       "of record (draft, published, archived, superseded visible). Use for idempotency/existence " +
       "checks: filter by `tags`, `source_type`+`source_id`, or `idempotency_key` and read " +
       "`meta.total_count` (exact) to answer \"does an article for X already exist?\" reliably " +
-      "right after a write. Paginate via offset/limit.",
+      "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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4072,7 +4251,8 @@ const TOOLS = [
           type: "string",
           description:
             "Optional: filter by exact idempotency_key — the lag-free existence check for a " +
-            "prior capture.",
+            "prior capture. Filter only: it is not returned in the rows, so read " +
+            "`meta.total_count`.",
         },
         offset: {
           type: "integer",
@@ -4258,7 +4438,11 @@ const TOOLS = [
       "Suggest ranked typed-link CANDIDATES for an article by embedding similarity — " +
       "READ-ONLY, creates nothing. Excludes the article itself and any already-linked " +
       "article (either direction, any relationship type); only embedded published articles. " +
-      "Returns { data: [{id, title, category, similarity_score}] } highest-similarity first. " +
+      "Returns { data: [{id, title, category, similarity_score}], meta } highest-similarity " +
+      "first. Read `meta.ann_iterative_scan` before concluding an article has no neighbours: " +
+      "`unavailable` (with `meta.ann_iterative_scan_reason`) means the vector read ran without " +
+      "pgvector's iterative scan and the list may be INCOMPLETE — `meta.recall_truncated: false` " +
+      "does NOT cover that case. " +
       "Review them and create the one you want as a TYPED link (relates_to/derived_from/" +
       "contradicts/supersedes) — unlike the auto-linker which only makes ambient relates_to. " +
       "Optional: threshold (cosine floor 0–1, default 0.5), limit (default 5).",
@@ -4385,14 +4569,24 @@ const TOOLS = [
       "— a stable tag naming WHY (e.g. no_embedding_key, embedding_circuit_open, " +
       "embedding_provider_error_<status>, embedding_timeout). When the reason is a MISSING " +
       "embedding key (no_embedding_key), the result leads with an ACTION REQUIRED notice + " +
-      "meta.remediation telling you to provision it with set_llm_config (BYO — do it once).",
+      "meta.remediation telling you to provision it with set_llm_config (BYO — do it once). " +
+      "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 and the total_count fields cannot tell you.",
     inputSchema: {
       type: "object",
       properties: {
-        q: {
+        query: {
           type: "string",
           description:
-            "Search query string. Optional when tags/category are supplied (enumeration mode).",
+            "Search query string. Optional when tags/category are supplied (enumeration mode). " +
+            "`query` is the canonical spelling across every search-shaped tool here; `q` is " +
+            "the historical name and is still accepted.",
+        },
+        q: {
+          type: "string",
+          description: "Deprecated alias for `query`. Accepted; prefer `query`.",
         },
         project_id: {
           type: "string",
@@ -4500,9 +4694,15 @@ const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
+        query: {
+          type: "string",
+          description:
+            "The topic to index (max 500 characters). Required unless `topic` is given. " +
+            "`query` is the canonical spelling across every search-shaped tool here.",
+        },
         topic: {
           type: "string",
-          description: "The topic to index (max 500 characters). Required.",
+          description: "Historical name for `query`. Accepted; prefer `query`.",
         },
         category: {
           type: "string",
@@ -4513,7 +4713,7 @@ const TOOLS = [
           description: "Optional: top-K override (clamped to the configured cap).",
         },
       },
-      required: ["topic"],
+      required: [],
     },
   },
   {
@@ -4572,7 +4772,11 @@ const TOOLS = [
       "reach — both resolve the same ids now. A drill records an UNCOUNTED read, so " +
       "following an index never raises the heat of what that index just showed you; " +
       "knowledge_get records a counted one, which is a vote that the article was worth " +
-      "opening on its own. Following a list is not a vote.",
+      "opening on its own. Following a list is not a vote.\n\n" +
+      "BODY: served in a byte WINDOW (default 32000 bytes) exactly like knowledge_get, so " +
+      "an oversized article comes back in parts instead of being rejected whole by a client " +
+      "token cap. Read body_truncated / next_body_offset to continue, or pass " +
+      "body_max_bytes: 0 for the whole body.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4581,6 +4785,19 @@ const TOOLS = [
           format: "uuid",
           description: "The UUID of the article to open (from a progressive index stub).",
         },
+        body_max_bytes: {
+          type: "integer",
+          minimum: 0,
+          description:
+            "Optional: serialized-body byte budget (default 32000). 0 returns the whole body.",
+        },
+        body_offset: {
+          type: "integer",
+          minimum: 0,
+          description:
+            "Optional: byte offset to start the body window at (default 0). Pass the " +
+            "previous response's next_body_offset to read the next part.",
+        },
       },
       required: ["article_id"],
     },
@@ -4610,7 +4827,13 @@ const TOOLS = [
       "`potential_conflicts` is returned in all three modes, so opting out of the link " +
       "list never hides a conflict from you; it is capped at 25 (strongest first) with " +
       "`conflicts_total` / `conflicts_truncated`. To actually traverse the graph, use " +
-      "knowledge_graph rather than raising this cap.",
+      "knowledge_graph rather than raising this cap.\n\n" +
+      "BODY: the body is served in a byte WINDOW (default 32000 bytes) so an oversized " +
+      "article is returned in parts instead of being rejected whole by a client token " +
+      "cap - four measured reads of 61-82KB were discarded that way after the search had " +
+      "already found them. Every response carries body_bytes (the full size), body_offset, " +
+      "body_returned_bytes, body_truncated and next_body_offset; pass next_body_offset back " +
+      "as body_offset to continue, or body_max_bytes: 0 for the whole body in one read.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4628,6 +4851,20 @@ const TOOLS = [
             "link fields. potential_conflicts (capped, with conflicts_total) is always " +
             "returned.",
         },
+        body_max_bytes: {
+          type: "integer",
+          minimum: 0,
+          description:
+            "Optional: serialized-body byte budget (default 32000). 0 returns the whole " +
+            "body. Read body_truncated / next_body_offset to continue.",
+        },
+        body_offset: {
+          type: "integer",
+          minimum: 0,
+          description:
+            "Optional: byte offset to start the body window at (default 0). Pass the " +
+            "previous response's next_body_offset to read the next part.",
+        },
         project_id: {
           type: "string",
           format: "uuid",
@@ -4944,7 +5181,12 @@ const TOOLS = [
       "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` and `meta.underfilled` are also returned so you can " +
-      "distinguish a short page from a hard cap.",
+      "distinguish a short page from a hard cap. Check `meta.ann_iterative_scan` too: " +
+      "`unavailable` (with `meta.ann_iterative_scan_reason`) means the vector read ran " +
+      "without pgvector's iterative scan and may be INCOMPLETE — a short page then is not " +
+      "evidence of a sparse scope, and meta.fallback/underfilled cannot tell you that. 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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4979,7 +5221,10 @@ const TOOLS = [
       "untouched per-source `memory` and `knowledge` envelopes so you can re-rank. " +
       "Cross-source scores are heuristic, not calibrated. If the knowledge search " +
       "degrades (embedding unavailable) or errors, the memory side is still returned and " +
-      "meta.degraded is true — never a hard failure.",
+      "meta.degraded is true — never a hard failure. Each envelope's " +
+      "`meta.ann_iterative_scan` discloses whether THAT half's vector read ran with " +
+      "pgvector's iterative scan (`unavailable` ⇒ possibly incomplete); the two halves " +
+      "are resolved independently and may differ.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5400,10 +5645,16 @@ const TOOLS = [
       "synthesize the two into ONE new DRAFT — both sources preserved, never auto-published, " +
       "for you/a human to review and publish). Non-destructive " +
       "at agent role — you record intent; the privileged nightly job executes it. " +
+      "NOTE for an agent-role key: 'supersede' is the one disposition that RETIRES an " +
+      "article unattended, so its confidence is capped server-side — your \"high\" is " +
+      "recorded as \"medium\" (see data.requested_confidence and note in the response) and " +
+      "the pair STAYS in knowledge_conflicts until an orchestrator+ key records it at high. " +
+      "'merge' is never capped and executes normally at agent role. " +
       "Last-write-wins per pair, so re-recording with fresher ground truth overrides. " +
       "Resolve only conflicts material to your current task; adjudicate against the actual " +
-      "system, and if you can't tell which is right, leave it (or record low confidence) " +
-      "rather than guessing.",
+      "system, and if you can't tell which is right, LEAVE IT UNRECORDED rather than " +
+      "guessing — recording low confidence is not a way to park it, it closes the verdict " +
+      "as dismissed on the next nightly run.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5440,14 +5691,21 @@ const TOOLS = [
           type: "string",
           description:
             "Why you're sure — ideally a ground-truth reference (commit, file:line, URL, or the " +
-            "observed behavior). Recorded for audit and for a human reviewing low-confidence calls.",
+            "observed behavior). Recorded for audit and for a human reviewing low-confidence " +
+            "calls. REQUIRED for a supersede OR merge recorded at confidence 'high' (422 " +
+            "without it) — every verdict the executor applies unattended must say why.",
         },
         confidence: {
           type: "string",
           enum: ["high", "medium", "low"],
           description:
-            "high, medium, or low. supersede auto-executes only at 'high'; lower confidence is " +
-            "recorded but left for review. Default medium.",
+            "high, medium, or low. Default medium. supersede/merge auto-execute only at 'high'; " +
+            "recorded LOWER, the next nightly run closes the verdict as dismissed (both " +
+            "articles retained) and the pair leaves the conflict queue — it is NOT left for " +
+            "review, so re-record at 'high' if you mean it to apply. On a supersede the value " +
+            "is a REQUEST: it is capped to 'medium' unless the calling key is orchestrator+, " +
+            "and a CAPPED verdict is the exception — it stays in the queue for an " +
+            "orchestrator+ key. merge is not capped.",
         },
       },
       required: ["source_article_id", "target_article_id", "disposition"],
@@ -6362,13 +6620,22 @@ const TOOLS = [
     description:
       "Mint an ephemeral api_key for a sub-agent dispatch. " +
       "The raw_key is returned ONCE — pass it to the sub-agent via its launch arguments, " +
-      "never store it in env vars. The key expires after expires_in_seconds.",
+      "never store it in env vars. The key expires after expires_in_seconds. " +
+      "Pass parent_dispatch_id: a dispatch may only be minted INSIDE the caller's own " +
+      "lineage. Omitting it starts a new independent lineage tree, which only the " +
+      "tenant's user-role operator key may do — every other caller gets 403 " +
+      "root_dispatch_forbidden, and the 403 body returns the caller's own dispatch id " +
+      "as remediation.your_dispatch_id.",
     inputSchema: {
       type: "object",
       properties: {
         parent_dispatch_id: {
           type: "string",
-          description: "UUID of the parent dispatch (omit for root dispatch).",
+          description:
+            "UUID of the parent dispatch — your own dispatch id, or one of its " +
+            "descendants. Required in practice: omitting it requests a ROOT dispatch, " +
+            "which is 403 root_dispatch_forbidden for any caller a dispatch minted. " +
+            "A parent outside your lineage is 403 parent_outside_caller_lineage.",
         },
         role: {
           type: "string",
@@ -6694,13 +6961,11 @@ const TOOLS = [
   },
   {
     name: "recover_cap",
-    description: "Re-mint a capability token for a story you're assigned to. Use after a session crash when you've lost your cap.",
+    description: "Re-mint the start_cap for a story you're assigned to. Use after a session crash when you've lost it. start_cap is the only recoverable capability: asking for any other type is refused and logged as a forgery attempt.",
     inputSchema: {
       type: "object",
       properties: {
         story_id: { type: "string", description: "Story UUID." },
-        cap_type: { type: "string", enum: ["start_cap", "report_cap"], description: "Which cap to recover (default: start_cap)." },
-        lineage: { type: "array", items: { type: "string" }, description: "Your dispatch lineage path." },
       },
       required: ["story_id"],
     },
@@ -6767,6 +7032,17 @@ const server = new Server(
   }
 );
 
+// The parameter names each STATIC tool declares, so the alias layer can tell a rescue from
+// an inert convenience fill. Dynamic per-tenant `cr_*` tools are absent here and fall back
+// to reporting every fill (the conservative default).
+const DECLARED_TOOL_ARGS = new Map(
+  TOOLS.map((t) => [t.name, Object.keys(t.inputSchema?.properties ?? {})]),
+);
+
+function declaredToolArgs(name) {
+  return DECLARED_TOOL_ARGS.get(name);
+}
+
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   // Static hand-maintained tools PLUS the calling tenant's per-tenant generated
   // Context Retriever tools (US-30.5). fetchGeneratedTools degrades to the static
@@ -6776,7 +7052,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
+  const { name } = request.params;
+  // The callback keeps the schema inconsistency MEASURABLE rather than merely survivable:
+  // every rescue is a call that would have been a hard 400 before, and a count of them is
+  // the evidence for eventually converging the spellings instead of aliasing forever.
+  //
+  // The tool's OWN declared parameters are passed so only a genuine rescue is reported. The
+  // fill is bidirectional, so without this a correct `knowledge_search` call carrying `q`
+  // also filled `query` and logged a "rescue" — counting normal traffic, and drowning the
+  // signal the count exists to carry.
+  const args = applyArgAliases(
+    request.params.arguments,
+    ({ canonical, alias }) => {
+      process.stderr.write(
+        `[loopctl-mcp] arg alias applied: '${alias}' -> '${canonical}' on tool '${name}'\n`,
+      );
+    },
+    declaredToolArgs(name),
+  );
 
   switch (name) {
     // Project Tools

package/lib/arg-aliases.js

@@ -0,0 +1,121 @@
+/**
+ * Argument-name aliases for MCP tool calls (#657).
+ *
+ * WHY THIS EXISTS. A catalogue of 1,932 real agent searches, mined from Claude session
+ * transcripts across two machines, found that 86 `knowledge_search` calls — 8% of every
+ * search call made — failed with `400 Query parameter 'q' is required`. 85 of those had
+ * passed `query` instead of `q`, and most also passed `max_results` instead of `limit`.
+ *
+ * The queries were not the problem. They were the best queries in the corpus:
+ *
+ *     {"query": "custody halt tenant threshold byzantine detection", "max_results": "1"}
+ *     {"query": "LCP-1 signed custody profile attestation enrollment owner key"}
+ *     {"query": "dropping a legacy pgvector HNSW index shared_buffers eviction retirement"}
+ *
+ * Every one was discarded over a synonym. Agents reach for `query`/`max_results` because
+ * that is what the surrounding ecosystem uses (WebSearch takes `query`; several MCP servers
+ * take `max_results`), and no amount of tool-description wording reliably overrides that
+ * habit — these calls were made by agents that had the schema in context.
+ *
+ * A search costs an embedding call and a turn of human attention. Refusing one over a
+ * spelling is the worst trade available. Accept both.
+ *
+ * CANONICAL WINS. An explicit canonical value is never overwritten, so a caller passing both
+ * `q` and `query` gets exactly what it asked for. Only a missing/blank canonical is filled.
+ */
+
+// BIDIRECTIONAL BY DESIGN. The 86 failures were not agents guessing wrong — this MCP
+// server's own surface is inconsistent, and `knowledge_search` is the odd one out:
+//
+//     query  ->  knowledge_hybrid_search, knowledge_context, memory_recall, recall_context
+//     q      ->  knowledge_search        (alone)
+//
+// Four sibling tools take `query`; the single most-used tool takes `q`. An agent that
+// learns `query` from any neighbour and applies it to knowledge_search gets a 400. So the
+// mapping runs BOTH ways: whichever spelling arrives, the other is filled in, and each tool
+// reads the key it declares. Handlers select named arguments when building their request,
+// so the extra key is inert rather than forwarded.
+//
+// Renaming knowledge_search's parameter instead would be a breaking change for every
+// existing caller that already passes `q` correctly. Accepting both costs nothing.
+//
+// A BIDIRECTIONAL FILL IS NOT A BIDIRECTIONAL RESCUE. Because a blank canonical is filled
+// from whichever spelling arrived, a perfectly correct `knowledge_search` call carrying `q`
+// ALSO gets `query` populated. Counting that as a rescue made the metric count normal
+// traffic — far more often than real rescues — so it could not support the decision it was
+// built to inform. `declared` (below) is the tool's own parameter list: a rescue is counted
+// only when the key the HANDLER READS was blank and the alias supplied it.
+//
+// ONLY OBSERVED ALIASES. This table lists what agents were MEASURED to send, nothing more.
+// The first draft also mapped `search`, `text`, `top_k`, `topK`, `n` and the camelCase id
+// spellings — all invented, none seen in the data — and the drift guard below immediately
+// caught two of them colliding with real parameters that mean something else entirely:
+// four tools declare `query` as their own canonical, and `memory_remember` declares `text`
+// for the CONTENT of a memory. Aliasing that into `q` would have copied a memory's body
+// into a search-query slot.
+//
+// A speculative alias is not free: it is a silent rename of somebody else's parameter.
+// Add one only when a real failing call is observed to need it.
+//
+// `max_results` has NO reverse entry on purpose: no tool declares it, so filling it from
+// `limit` rescued nothing and merely put a stderr write on the hot path of every call that
+// paginated correctly.
+const ARG_ALIASES = {
+  q: ["query"],
+  query: ["q"],
+  limit: ["max_results"],
+};
+
+function isBlank(v) {
+  return v === undefined || v === null || v === "";
+}
+
+/**
+ * Returns a NEW args object with canonical keys filled in from any alias present.
+ * Non-object input (null/undefined/array) is returned unchanged.
+ *
+ * `declared` is the set/array of parameter names the CALLED TOOL actually declares. When
+ * supplied, only a fill of a declared key is reported as a rescue — the rest are inert
+ * conveniences. Omit it and every fill is reported (the conservative default for a tool
+ * whose schema is not known, e.g. the per-tenant `cr_*` tools).
+ */
+function applyArgAliases(args, onAliasUsed, declared) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+
+  const out = { ...args };
+  const declaredSet = declared ? new Set(declared) : null;
+
+  for (const [canonical, aliases] of Object.entries(ARG_ALIASES)) {
+    if (!isBlank(out[canonical])) continue;
+    for (const alias of aliases) {
+      if (!isBlank(out[alias])) {
+        out[canonical] = out[alias];
+        // Report every real rescue. Aliasing treats the SYMPTOM — the real defect is that
+        // the tool surface spells the same parameter three ways (`q`, `query`, `topic`). If
+        // the rescue is invisible, the inconsistency costs nothing measurable and never gets
+        // fixed, and the alias table quietly becomes load-bearing forever. Counting it
+        // keeps the residual cost on the books — which only works if the count is of calls
+        // that WOULD HAVE FAILED, hence the `declared` gate.
+        const rescued = declaredSet === null || declaredSet.has(canonical);
+        if (rescued && typeof onAliasUsed === "function") {
+          try {
+            onAliasUsed({ canonical, alias });
+          } catch {
+            // Telemetry must never break a tool call.
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  // Some callers send a numeric arg as a string ("6"). Coerce so downstream validation and
+  // the outbound query string both see a number rather than rejecting or double-encoding.
+  if (typeof out.limit === "string" && /^\d+$/.test(out.limit.trim())) {
+    out.limit = parseInt(out.limit.trim(), 10);
+  }
+
+  return out;
+}
+
+export { ARG_ALIASES, applyArgAliases };

package/lib/client-context.js

@@ -0,0 +1,128 @@
+/**
+ * Client context reported alongside every search (#658).
+ *
+ * WHY THE CLIENT HAS TO SUPPLY THIS. None of it is derivable server-side. An api_key
+ * identifies a KEY, and under the v2 dispatch pattern a key is minted per dispatch, so the
+ * server cannot tell which agent searched, at what effort, from which repo, or whether the
+ * caller was a main session or a dispatched subagent. The MCP server runs inside the
+ * agent's own process, so it can simply read its environment.
+ *
+ * UNTRUSTED BY CONSTRUCTION. Every field here is client-asserted and trivially spoofable.
+ * It is ANALYTICS ONLY and must never gate access or authorize anything — the api_key
+ * remains the sole authority. The server stores these under a `client_` prefix so no later
+ * reader mistakes them for server-derived facts.
+ *
+ * WHAT IS ACTUALLY AVAILABLE (verified on a live session, 2026-08-12):
+ *
+ *   CLAUDE_EFFORT=high              -> effort, available
+ *   CLAUDE_SESSION_ID=<uuid>        -> session id, available
+ *   CLAUDE_CODE_CHILD_SESSION=1     -> subagent vs main session, available
+ *   CLAUDE_CODE_ENTRYPOINT=cli      -> entrypoint, available
+ *   (no model variable)             -> MODEL IS NOT AVAILABLE
+ *
+ * The model is deliberately still sent when a variable for it appears, because the session
+ * TRANSCRIPT does record it (`message.model`, e.g. `claude-opus-5`) keyed by session id —
+ * so `client_session_id` is the join key that enriches model offline today, and the field
+ * fills itself in the day the runtime exposes one.
+ */
+
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+
+function env(name) {
+  const v = process.env[name];
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
+/**
+ * The repo the AGENT was working in — which is NOT the project a KB search was scoped to.
+ * "Which repos lean on the knowledge base, and which never touch it" cannot be answered
+ * without it, and the scoped project_id does not answer it.
+ *
+ * Derived from the git remote so it is stable across machines and checkout paths; falls
+ * back to the directory basename when there is no remote. Cached: this runs per search and
+ * shelling out per call would put a process spawn on the hot path.
+ */
+let repoCache;
+function detectRepo() {
+  if (repoCache !== undefined) return repoCache;
+  repoCache = null;
+  try {
+    const remote = execFileSync("git", ["remote", "get-url", "origin"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    }).trim();
+    // Normalise git@host:owner/repo.git and https://host/owner/repo(.git) to owner/repo.
+    const m = remote.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+    if (m) repoCache = m[1];
+  } catch {
+    try {
+      repoCache = process.cwd().split("/").filter(Boolean).pop() || null;
+    } catch {
+      repoCache = null;
+    }
+  }
+  return repoCache;
+}
+
+/** Test seam: forget the cached repo. */
+function resetRepoCache() {
+  repoCache = undefined;
+}
+
+/**
+ * Builds the client-context payload. Every field is optional — a missing value is omitted
+ * rather than sent as null, so "we could not observe this" and "this was empty" stay
+ * distinguishable in the data.
+ */
+function clientContext({ version } = {}) {
+  const ctx = {
+    session_id: env("CLAUDE_SESSION_ID") || env("CLAUDE_CODE_SESSION_ID"),
+    effort: env("CLAUDE_EFFORT"),
+    model: env("CLAUDE_MODEL") || env("ANTHROPIC_MODEL"),
+    host: os.hostname(),
+    repo: detectRepo() || undefined,
+    entrypoint: env("CLAUDE_CODE_ENTRYPOINT"),
+    version,
+  };
+
+  // main vs child. A dispatched agent sets CLAUDE_CODE_CHILD_SESSION=1.
+  //
+  // Only TWO values, on purpose. A workflow agent cannot be distinguished from an ordinary
+  // subagent here: CLAUDE_CODE_WORKFLOWS is a feature flag that is present in main sessions
+  // too, and nothing else marks one. Since an audit measured materially different failure
+  // rates across main/workflow/subagent, the third value matters — but it is recoverable
+  // only OFFLINE, by joining session_id to the transcript path (wf_* vs subagents/). Report
+  // what is observable and let the join supply the rest; do not guess a value that would
+  // then be analysed as fact.
+  const child = env("CLAUDE_CODE_CHILD_SESSION");
+  if (child !== undefined) {
+    ctx.kind = child === "1" || child.toLowerCase() === "true" ? "child" : "main";
+  } else if (ctx.session_id) {
+    // A MAIN session sets no child marker at all, so keying on the marker alone filed
+    // every main session under NULL — beside every request from an older client that sends
+    // no context, which is the one population NULL has to keep meaning. An absent marker on
+    // a recognisable session IS main; with nothing identifying the caller, kind stays
+    // absent rather than guessed.
+    ctx.kind = "main";
+  }
+
+  for (const k of Object.keys(ctx)) {
+    if (ctx[k] === undefined || ctx[k] === null || ctx[k] === "") delete ctx[k];
+  }
+  return ctx;
+}
+
+/**
+ * Encodes the context for transport as a single header. Base64 keeps arbitrary repo names
+ * and hostnames from breaking header parsing, and one header keeps the surface small.
+ * Returns undefined when there is nothing to report, so no empty header is sent.
+ */
+function clientContextHeader(opts) {
+  const ctx = clientContext(opts);
+  if (Object.keys(ctx).length === 0) return undefined;
+  return Buffer.from(JSON.stringify(ctx), "utf8").toString("base64");
+}
+
+export { clientContext, clientContextHeader, detectRepo, resetRepoCache };

package/lib/search-notices.js

@@ -0,0 +1,70 @@
+/**
+ * Leading notices for search results whose META carries something the agent must act on
+ * (#658).
+ *
+ * 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`,
+ * `meta.fallback_reason`, plus telemetry and a server-side warning log. The degradation is
+ * not silent at the server. It is silent at the CLIENT: agents do not read `meta`.
+ *
+ * Measured across real session transcripts on two machines: every degraded response that
+ * came back empty was treated by the receiving agent as "the knowledge base has nothing".
+ * It is a low-volume failure (roughly a dozen in ~1,900 searches) and a totally deceptive
+ * one — and it lands hardest on the BEST queries, because the keyword fallback lane uses
+ * AND semantics, so a long specific query is the most likely to match nothing at all.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+/** True when a result degraded to a fallback lane, whatever the cause. */
+function isDegraded(meta) {
+  return Boolean(meta && (meta.fallback === true || meta.degraded === true));
+}
+
+function resultCount(result) {
+  if (!result || typeof result !== "object") return null;
+  if (Array.isArray(result.data)) return result.data.length;
+  if (Array.isArray(result.results)) return result.results.length;
+  return null;
+}
+
+/**
+ * Returns a notice string when a search DEGRADED, or null otherwise.
+ *
+ * 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.
+ */
+function degradedSearchNotice(result) {
+  const meta = result && result.meta;
+  if (!isDegraded(meta)) 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);
+
+  if (count === 0) {
+    return (
+      `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 (
+    `PARTIAL SEARCH — semantic ranking was unavailable (${reason}), so these are ` +
+    `keyword-only matches and may be incomplete. Retry the same query for full ranking.`
+  );
+}
+
+export { degradedSearchNotice, isDegraded };

package/package.json

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