vantage-peers-mcp 2.17.0 → 2.19.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [Unreleased] — grant-aware mission/mandate visibility + bind JWT audience
+
+### Fixed
+
+- **`check_messages` now renders `stuckInProgress` / `peersStuckOnYou` from the envelope (Day-156 reader-first; Eta REVISE PR #1218 dual-shape).** Missing / null / undefined keys default via `asCappedStuckList` so old Convex prod cannot throw `.length`. Accepts a raw `{taskId,title,age}[]` (already-deployed MCP) **or** `{entries,total,truncated}`. Empty unread + a stuck SIGNAL (`entries.length > 0` OR `truncated === true`) surfaces the block, never `"No new messages."` / Vide — a truncated empty list is a signal, not rest. `messages` / `staleInProgress` are unchanged; `pendingOnYou` is not revived.
+
+### Added
+
+- **`fail_task` tool — the third task terminal state (`failed`), distinct from `done`/`cancelled` (mission `k576mw0smxeqsg9wp7957njfsn8crey4`, commit `8c70e18`).** New tool, mandatory `failureNote`, output schema `{taskId, status: "failed"}`. `update_task`'s `updateTaskStatusSchema` now excludes both `"blocked"` and `"failed"` (client refused at the tool-input layer, mirroring the server-side `FAILED_VIA_UPDATE_REFUSED` gate). `taskStatusValues`/`taskStatusFilterSchema` gained `"failed"`. `createTaskOutputSchema.status` now reuses the canonical `taskStatusValues` array (was hand-typed and missing `"cancelled"`/`"failed"`). A blocker task reaching `failed` does NOT auto-release its waiters — see `convex`-side CHANGELOG for the reciprocal-unblock fix.
+- **`block_task` gained an optional `blockedCause` arg** (`"peer_task" | "human" | "authorisation" | "other"`) naming WHAT the task is waiting on. Backward-compatible: optional, defaults server-side to `"other"`. `block_task`'s output JSON now always carries `blockedCause`.
+
+### Security
+
+- **Consult per-row grants on missions, mandates, and tasks (task `k174y9ra7pp8zed3bcczk6xaed8cpynp`, `@vantageos/cloud-identity` 0.5.0).** The shared scope filter was structurally blind to every per-row grant: a scoped identity named on a mission (`pilot`/`agents`), a mandate (`requestedBy`/`fulfilledBy`), or a task (`assignedTo`) could not read the row it was named on — the multi-org separation failing at exactly what it is sold for. Upgraded the dependency `^0.3.0` → `^0.5.0` (the old caret stopped at the 0.3 minor and never admitted 0.4.0) and passed `grantFields` at the read sites: `get_mission` → `["pilot","agents"]`; `list_mandates`/`get_mandate` → `["requestedBy","fulfilledBy"]`; `get_task`/`list_tasks_by_mission`/`search_tasks_by_keyword` → `["assignedTo"]` (mirrors `convex/tasks.ts` L88-89's `createdBy===caller || assignedTo===caller` OR), replacing the two-sided `createdBy`-remap workaround (the local-variant pattern the shared filter now subsumes). Fail-closed unchanged: a table declaring no grant fields behaves byte-identically to before. Eta REVISE on the first pass of PR #1204 (the original test suite called the package predicate directly instead of the real handlers — litmus test false); rewritten to drive `registerTools()` end-to-end via the same duck-typed McpServer/Convex harness `test/scope-aware-filter-wave-c1.test.ts` uses, RED→GREEN reproduced against the real `get_task`/`search_tasks_by_keyword` call sites. `briefingNotes.participants` stays deferred (task `k175ga65p654z200ydj7s8qv5s8cnxfc`); `recurringTasks.assignedTo`, `missionTemplates.steps[].assignedTo`, `businessUnits.coreTeam.agents`, and `diaries.orchestrator` remain unwired (out of this PR's scope — see PR #1204 `CLASS:` block). TDD strict — GREEN 13/13 under scoped non-creator identity `alice`; full mcp-server suite 1087 passed / 12 skipped, build clean + boot-check 4/4.
+
+
+
+- **Bind the `audience` claim where the Clerk session JWT is verified (MCP server standard Critical Rule 14, element 5).** `tryVerifyClerkJwt` (`src/auth.ts`) verified the token with `issuer` bound but not `audience`, so a token minted for one audience/client was accepted on another — cross-tenant / cross-resource replay (the single exploitable finding of the mcp-doctor conformance audit, `projects/vantage-peers/audits/mcp-server-conformance-audit.md`). Fix binds `audience: CLERK_JWT_AUDIENCE` (env, default `"convex"`) at the single `jwtVerify` site — the value mirrors `convex/auth.config.ts` `applicationID: "convex"` and the `CLERK_JWT_TEMPLATE` default, and the verified token is forwarded verbatim to Convex which already requires `aud === "convex"`, so no correctly-minted production token is rejected. Minimal by design: only the one verification site; the auth-layer/DCR/PRM flow and the three other (non-exploitable) audit findings are untouched. TDD strict — RED both poles (wrong-audience refused / correct-audience accepted / no-`aud` refused) reproduced firsthand, GREEN 3/3; full suite 1074 passed / 0 failed, `tsc --noEmit` exit 0.
+
+### Fixed
+
+- **Regenerate `mcp-server/bun.lock` so the grant-aware read actually reaches the customer-facing server (task `k170n5az8xt95gg0b6thrzgej98crnw3`).** PR #1204 (`f51bd709`) bumped `mcp-server/package.json` `@vantageos/cloud-identity` `^0.3.0` → `^0.5.0` and the root `bun.lock`, but never regenerated `mcp-server/bun.lock` — which stayed pinned at `@vantageos/cloud-identity@0.3.0`. The Railway build runs `bun install --frozen-lockfile`, which refuses a lockfile that would have to change (`error: lockfile had changes, but lockfile is frozen`), so the deploy failed **silently**: the previous container kept serving and nothing disagreed. Result: the grant-aware filter was ACTIVE on Convex but INACTIVE on the MCP server — the path a customer actually uses. Repair regenerates the lockfile **in an isolated tree** (never in the workspace, which would resolve against the workspace and reproduce the locally-passing / Railway-failing file), touching `mcp-server/bun.lock` only; the manifest is untouched (dependency scope did not move). The drift named: `@vantageos/cloud-identity` `0.3.0` → `0.5.0`. Proven pair, both poles firsthand: RED = stale lockfile + `^0.5.0` manifest under `--frozen-lockfile` → exit 1 (the exact Railway message); GREEN = repaired lockfile under `--frozen-lockfile` → exit 0. Activation (separate from merge) is a successful Railway deploy read back from the platform, then a scoped-identity probe of the grant filter — never the master credential, which bypasses the very check.
+
+## [2.18.0] — 2026-08-11
+
+### Changed
+- **Expose only the CORE tool surface (mission `vp-mcp-alias-cleanup-v1`, S8).** A data-driven allowlist (`mcp-server/tool-exposure.json`, `{"core":[...]}`) masks every tool whose `T2_verdict` is not `CORE` in `analysis/vantagepeers/vp-restructuring/vp-by-tool-day158.csv`. Masking ≠ deletion: non-CORE tools stay registered + handler-wired and are `disable()`d so `tools/list` does not advertise them; reverting = removing a line from the data file. Exposed = CORE ∩ registered = **66** tools; masked = **43** (registered 109). The exposure list is derived from the CSV, never typed; a name in the file matching no registered tool makes the server refuse to start, naming it. Applied at the single shared `registerTools` surface, so both stdio and HTTP transports (online clients) inherit the reduced surface. 5 CORE names from the day158 CSV are #1169-removed aliases whose CORE survivors stay exposed (zero capability lost). Tests: `test/tool-exposure.test.ts` 2/2, full suite 1071 passed / 0 failed, tsc 0.
+
 ## [2.17.0] — 2026-08-11
 
 ### Removed

package/README.md

@@ -6,7 +6,7 @@
 [![MCP tools: 109+](https://img.shields.io/badge/MCP_tools-109+-green)]()
 
 > **Package:** `vantage-peers-mcp` (plain — NOT `@vantageos/vantage-peers-mcp`)
-> **Current version:** `2.17.0` (alias-cleanup release — 14 duplicate alias tools removed, fleet-used survivor of each pair kept)
+> **Current version:** `2.18.0` (S8 CORE tool-exposure filter release — server now advertises only 66 CORE tools of 109 registered; masking is data-driven (`tool-exposure.json`) and reversible, non-CORE tools stay registered/handler-wired but are not listed)
 > **License:** FSL-1.1-Apache-2.0
 > **Repo:** https://github.com/vantageos-agency/vantage-peers (full monorepo README at `/README.md`)
 > **Docs:** https://vantagepeers.com/docs
@@ -227,17 +227,20 @@ The full registered list ships in `mcp-server/src/tools.ts` and is enumerated be
 - `update_profile` — mutate an orchestrator profile (master-gated)
 - `list_peers` — page through registered peers
 
-### Tasks (14)
+### Tasks (17)
 - `create_task` — create a new task with VERIFICATION + TESTS blocks
 - `list_tasks` — page through tasks with filters + `excludeAutoGenerated`
 - `list_tasks_by_mission` — page through tasks for a single mission
 - `get_task` — fetch a single task by id
 - `update_task` — patch task fields (incl. cancel: `status="cancelled"` + `cancelReason`, creator-only)
-- `start_task` — transition to `in_progress`
+- `start_task` — transition to `in_progress`; resumes rather than restarts when the task already carries worked time, and refuses when a segment is already open, naming the verb to call instead
+- `pause_task` — close the open work segment and stop the clock without ending the task; paused is not blocked
+- `resume_task` — open a new work segment and put the task back in `in_progress`
 - `complete_task` — close with evidence-bound `completionNote`
 - `checkout_task` — claim a task without starting
 - `delete_task` — destructive delete (master-gated, blocked in prod; to retire an erroneous task use `update_task status="cancelled"` + `cancelReason`, not `complete_task`)
-- `block_task` — mark blocked with reason
+- `block_task` — mark blocked with reason and optional `blockedCause` (`peer_task`|`human`|`authorisation`|`other`) naming WHAT is being waited on
+- `fail_task` — close a task as **failed**, a terminal state distinct from `done`/`cancelled`, with a mandatory `failureNote`
 - `add_task_dependency` — add a predecessor
 - `bulk_complete_tasks` — dry-run-default bulk close (cron-spam cleanup)
 - `validate_task_payload` — client-side payload validation
@@ -278,6 +281,44 @@ Example — Pi queue cleaned of cron-spam:
 
 Returns `{ items: Task[], nextCursor: string | null }`. `nextCursor` is `null` on the last page.
 
+#### `block_task` — `blockedCause` discriminator (T1, PR #1208)
+
+```
+block_task(taskId, reason?, blockedOnTaskId?, blockedCause?, callerOrchestrator?)
+```
+
+`blockedCause` is optional (defaults server-side to `"other"`) and states WHAT the task is waiting on:
+
+| Value | Meaning |
+|-------|---------|
+| `human` | Waiting on a human answer/decision — an operator has to reply before work resumes. |
+| `authorisation` | Waiting on a merge/publish/approval gate (e.g. Eta review, Pi merge sign-off). |
+| `peer_task` | A plain upstream dependency on another live task — requires a cited `blockedOnTaskId` (refused otherwise: `BLOCKED_CAUSE_PEER_TASK_REQUIRES_LINK`). |
+| `other` | None of the above, or the default when omitted. |
+
+`blockedCause` is orthogonal input data, not a caller-written presentation state — the reader-facing "waiting-on" label is always DERIVED from `{status, blockedCause}`, never written directly. Pre-existing blocked rows (created before this field existed) read back as `"other"`.
+
+#### `fail_task` — the third terminal state (T1, PR #1208)
+
+```
+fail_task(taskId, failureNote, callerOrchestrator?)
+```
+
+Marks a task **failed** — a terminal status distinct from `done` (succeeded) and `cancelled` (retired before/without attempting the work). Use it when the work was genuinely attempted and did not succeed.
+
+- `failureNote` is **mandatory** and non-empty — describes how the work ended in failure.
+- This is the **only** door to the failed state: `update_task status="failed"` is refused server-side (`FAILED_VIA_UPDATE_REFUSED`), the same way `update_task status="blocked"` is refused. There is no field for a closer to default past — only a distinct named tool to call.
+- A task already `done`/`cancelled`/`failed` cannot be re-terminated as failed (`CANNOT_FAIL_CLOSED_TASK`).
+- **Waiters are NOT auto-released when a blocker fails.** Any task blocked on the failed one stays `blocked`, with `blockedOnTaskId` intact — the fleet does not silently treat a failed prerequisite as though it held. The waiter's owner instead receives a `BLOCKER_FAILED:` notification naming the failure; the block must be re-routed by a human/orchestrator decision, never auto-cleared. (Contrast: when a blocker reaches `done`, its waiters ARE swept to `todo` automatically — only success auto-releases.)
+
+Example:
+```json
+{
+  "tool": "fail_task",
+  "arguments": { "taskId": "k178d3ns...", "failureNote": "Migration errored on row 4102, rolled back cleanly", "callerOrchestrator": "beta" }
+}
+```
+
 #### `bulk_complete_tasks` — args schema + dry-run-default safety (PR-F)
 
 ```

package/dist/server-http.js

@@ -35,7 +35,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { timingSafeEqual } from "@vantageos/cloud-identity";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
-import { bearerAuthMiddleware, internalClient, masterOnlyMiddleware, sha256Base64Url, sha256Hex, } from "./src/auth.js";
+import { bearerAuthMiddleware, internalClient, isMasterScope, masterOnlyMiddleware, sha256Base64Url, sha256Hex, } from "./src/auth.js";
 import { selectConvexClientForRequest } from "./src/authenticatedConvexClient.js";
 import { registerTools } from "./src/tools.js";
 import { listUiResources, readUiResource } from "./src/ui-resources/index.js";
@@ -228,8 +228,8 @@ app.get("/.well-known/oauth-authorization-server", (c) => {
     });
 });
 const registerRateBuckets = new Map();
-const REGISTER_RATE_LIMIT = 5;
-const REGISTER_RATE_WINDOW_MS = 60_000;
+const REGISTER_RATE_LIMIT = 5; // maxPerWindow: 5
+const REGISTER_RATE_WINDOW_MS = 60_000; // windowMs: 60_000
 function checkRegisterRateLimit(ip) {
     const now = Date.now();
     const bucket = registerRateBuckets.get(ip);
@@ -555,6 +555,7 @@ app.post("/token", async (c) => {
             namespaceWritePrefixes: profile.namespaceWritePrefixes,
             expiresAt: now + ACCESS_TOKEN_TTL_SECONDS * 1000,
             refreshTokenHash,
+            clerkOrgSlug: profile.clerkOrgSlug,
         });
         await internalClient().mutation(
         // biome-ignore lint/suspicious/noExplicitAny: Convex string API
@@ -641,6 +642,7 @@ app.post("/token", async (c) => {
             namespaceWritePrefixes: profile.namespaceWritePrefixes,
             expiresAt: now + ACCESS_TOKEN_TTL_SECONDS * 1000,
             refreshTokenHash,
+            clerkOrgSlug: profile.clerkOrgSlug,
         });
         return c.json({
             access_token: accessToken,
@@ -743,6 +745,61 @@ admin.post("/oauth/clients", async (c) => {
         redirect_uris: redirectUris,
     }, 201);
 });
+// POST /admin/organizations — one-shot org + orchestrator seats
+admin.post("/organizations", async (c) => {
+    const masterToken = process.env.BEARER_SECRET_MASTER;
+    if (!masterToken) {
+        return c.json({ error: "server_misconfigured" }, 500);
+    }
+    let body = {};
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_request" }, 400);
+    }
+    const clerkOrgSlug = typeof body.clerkOrgSlug === "string" ? body.clerkOrgSlug : null;
+    const displayName = typeof body.displayName === "string" ? body.displayName : null;
+    const orchestratorsRaw = Array.isArray(body.orchestrators)
+        ? body.orchestrators
+        : null;
+    if (!clerkOrgSlug || !displayName || !orchestratorsRaw) {
+        return c.json({
+            error: "invalid_request",
+            error_description: "clerkOrgSlug, displayName, and orchestrators are required",
+        }, 400);
+    }
+    const orchestrators = orchestratorsRaw
+        .map((row) => {
+        if (row && typeof row === "object" && "name" in row) {
+            const name = row.name;
+            return typeof name === "string" ? { name } : null;
+        }
+        return null;
+    })
+        .filter((row) => row !== null);
+    const scopes = Array.isArray(body.scopes)
+        ? body.scopes.filter((s) => typeof s === "string")
+        : undefined;
+    try {
+        const result = await internalClient().mutation(
+        // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+        "oauth:provisionOrganization", {
+            callerToken: masterToken,
+            clerkOrgSlug,
+            displayName,
+            orchestrators,
+            scopes,
+        });
+        return c.json(result, result.replay ? 200 : 201);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("[admin] provisionOrganization failed:", message);
+        const status = message.includes("Unauthorized") ? 401 : 400;
+        return c.json({ error: "provision_failed", detail: message }, status);
+    }
+});
 // GET /admin/oauth/clients  — list (no secrets)
 admin.get("/oauth/clients", async (c) => {
     const masterToken = process.env.BEARER_SECRET_MASTER;
@@ -981,6 +1038,7 @@ admin.post("/oauth/access-tokens", async (c) => {
             namespaceReadPrefixes,
             namespaceWritePrefixes,
             expiresAt,
+            clerkOrgSlug: profile.clerkOrgSlug,
         });
     }
     catch (err) {
@@ -1172,7 +1230,17 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
             // biome-ignore lint/suspicious/noExplicitAny: Convex string API
             return convex.query(functionName, args);
         };
-        return await readUiResource(uri.toString(), fetchConvex);
+        // Day-165-parity — thread the caller identity into the ui-resource
+        // primitives the same way tools.ts does (mirrors the
+        // master/callerIdentities computation at tools.ts:5712/5808/5934), so
+        // briefingNotes:get/list resolve visibility inside Convex instead of
+        // falling into the `callerIdentities === undefined` legacy-open branch.
+        const master = oauthCtx === undefined || isMasterScope(oauthCtx);
+        const callerIdentities = master ? undefined : oauthCtx.fromAllowList;
+        return await readUiResource(uri.toString(), fetchConvex, {
+            master,
+            callerIdentities,
+        });
     });
     const transport = new WebStandardStreamableHTTPServerTransport();
     await server.connect(transport);

package/dist/server.d.ts

@@ -2,8 +2,9 @@
 /**
  * VantagePeers MCP Server — stdio transport (Self-host / local Claude Code path).
  *
- * Thin bootstrap: resolves CONVEX_URL, instantiates McpServer + ConvexHttpClient,
- * delegates ALL tool registration to the shared `registerTools(server, convex)`
+ * Thin bootstrap: resolves CONVEX_URL, instantiates McpServer + a
+ * service-account-identified Convex client, delegates ALL tool registration
+ * to the shared `registerTools(server, convex)`
  * surface in src/tools.ts. This guarantees stdio and HTTP transports expose the
  * same tool set (parity locked by src/__tests__/stdio-http-parity.test.ts).
  *

package/dist/server.js

@@ -2,8 +2,9 @@
 /**
  * VantagePeers MCP Server — stdio transport (Self-host / local Claude Code path).
  *
- * Thin bootstrap: resolves CONVEX_URL, instantiates McpServer + ConvexHttpClient,
- * delegates ALL tool registration to the shared `registerTools(server, convex)`
+ * Thin bootstrap: resolves CONVEX_URL, instantiates McpServer + a
+ * service-account-identified Convex client, delegates ALL tool registration
+ * to the shared `registerTools(server, convex)`
  * surface in src/tools.ts. This guarantees stdio and HTTP transports expose the
  * same tool set (parity locked by src/__tests__/stdio-http-parity.test.ts).
  *
@@ -19,10 +20,23 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ConvexHttpClient } from "convex/browser";
-import { readFileSync } from "fs";
-import { resolve } from "path";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createServiceAccountConvexClient } from "./src/authenticatedConvexClient.js";
+import { LOCAL_STDIO_TRUST_CTX } from "./src/auth.js";
 import { registerTools } from "./src/tools.js";
+// Advertised version is derived from the manifest, same pattern as
+// server-http.ts, so both transports report identical values in source and
+// dist mode.
+let pkg;
+try {
+    // Source mode: server.ts → ./package.json = mcp-server/package.json
+    pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf-8"));
+}
+catch {
+    // Dist mode: dist/server.js → ../package.json = mcp-server/package.json
+    pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Bootstrap: resolve CONVEX_URL from env or .env.local
 // ─────────────────────────────────────────────────────────────────────────────
@@ -54,15 +68,20 @@ function loadConvexUrl() {
 // Server setup
 // ─────────────────────────────────────────────────────────────────────────────
 const convexUrl = loadConvexUrl();
-const convex = new ConvexHttpClient(convexUrl);
+// Grants the stdio path master, via the service-account carve-out —
+// the local-trust posture claimed below, now backed by an actual identity.
+const convex = createServiceAccountConvexClient(convexUrl);
 const server = new McpServer({
     name: "vantage-peers",
-    version: "2.17.0",
+    version: pkg.version,
 });
-// stdio transport has no OAuth identity → pass oauthCtx=undefined to opt into
-// the legacy bearer / system-scope code path inside registerTools (same path
-// server-http.ts uses for unauthenticated requests).
-registerTools(server, convex);
+// stdio runs on the operator's own machine against their own CONVEX_URL, so it
+// is trusted with full LOCAL authority. That authority is now PRESENTED as an
+// explicit, named context (LOCAL_STDIO_TRUST_CTX) rather than inferred from an
+// absent oauthCtx — the scope guards in registerTools refuse on undefined, so
+// the missing-argument path is no longer a max-authority backdoor
+// (.claude/rules/one-identity-layer.md clause 3).
+registerTools(server, convex, LOCAL_STDIO_TRUST_CTX);
 // ─────────────────────────────────────────────────────────────────────────────
 // Start server on stdio transport
 // ─────────────────────────────────────────────────────────────────────────────

package/dist/src/auth.d.ts

@@ -50,6 +50,20 @@ export type OAuthContext = {
      * there for why that is fail-closed-safe.
      */
     clerkJwt?: string;
+    /**
+     * SHA-256 hex of the OAuth access token presented on this request —
+     * set ONLY on auth path (2) after oauth:getAccessTokenByHash hits.
+     * The roster query derives the organisation from the token ROW keyed
+     * by this hash. It is a credential locator, not an organisation id.
+     */
+    accessTokenHash?: string;
+    /**
+     * Organisation slug snapshotted onto the access-token row at mint.
+     * Presence selects the token-derived roster path; absence on a
+     * non-Clerk caller is the #1215 refuse. Never passed as a Convex
+     * query argument.
+     */
+    clerkOrgSlug?: string;
 };
 declare module "hono" {
     interface ContextVariableMap {
@@ -57,6 +71,22 @@ declare module "hono" {
         oauthContext: OAuthContext;
     }
 }
+/**
+ * Local-machine-trust context for the stdio transport (server.ts).
+ *
+ * The stdio server runs on the OPERATOR'S OWN machine (Self-host / local Claude
+ * Code via `npx vantage-peers-mcp`) against a CONVEX_URL the operator already
+ * holds. There is no network-facing bearer to scope on this transport, so the
+ * caller is trusted with full local authority.
+ *
+ * The point of naming it: this authority is now PRESENT and greppable, not
+ * inferred from an ABSENT oauthContext. server.ts passes it EXPLICITLY (see
+ * `.claude/rules/one-identity-layer.md` clause 3 — "a right is presented, never
+ * inferred from an absence"). Every guard below now REFUSES on undefined; the
+ * stdio full-access path keeps working only because this named context is
+ * handed in, never because a missing argument is read as master.
+ */
+export declare const LOCAL_STDIO_TRUST_CTX: OAuthContext;
 export declare function internalClient(): ConvexHttpClient;
 export declare function _setInternalClientForTest(client: ConvexHttpClient | null): void;
 export declare function sha256Hex(input: string): Promise<string>;
@@ -71,26 +101,66 @@ export declare function sha256Base64Url(input: string): Promise<string>;
  *
  * Delegates the actual master/wildcard decision to
  * `@vantageos/cloud-identity`'s `isMasterScope` (0.3.0+) via `toPackageOAuthCtx`
- * above — this repo no longer reimplements that check locally. `undefined` is
- * handled here (returns false) because several call sites in tools.ts pass an
- * optional `OAuthContext` (legacy bearer path has no oauthContext at all);
- * the package's own guard requires a non-null `OAuthCtx` and throws otherwise
- * (0.3.0's "never grant by absence" contract), so the undefined check must
- * happen before delegating, not be silently absorbed by the package call.
+ * above — this repo no longer reimplements that check locally. `undefined`
+ * returns FALSE here (absence is never master): callers pass an optional
+ * `OAuthContext`, and the package's own guard requires a non-null `OAuthCtx`
+ * and throws otherwise (0.3.0's "never grant by absence" contract), so the
+ * undefined check must happen before delegating, not be silently absorbed by
+ * the package call. Note the direction: undefined → NOT master (this fn) AND
+ * undefined → REFUSE (the check* predicates above); never undefined → grant.
  */
 export declare function isMasterScope(ctx: OAuthContext | undefined): boolean;
 /**
  * Checks that `from` is allowed by the current OAuth context.
  * Returns null when allowed, an error message string otherwise.
  *
- * `ctx` is only undefined in tests that call these predicates directly
- * without going through bearerAuthMiddleware — every real auth path
- * (master, OAuth, Clerk, DCR, legacy mcpTenants bearer) sets an oauthContext.
- * The legacy mcpTenants bearer path resolves to a deny-by-default
- * "legacy-tenant-generic" scope (empty allowlist/prefixes) — see auth.ts
- * path (4).
+ * A missing `ctx` REFUSES (returns the refusal string), it never passes.
+ * Every real auth path sets an oauthContext — the HTTP transport via
+ * bearerAuthMiddleware (master, OAuth, Clerk, DCR, and the legacy mcpTenants
+ * bearer path, which resolves to a deny-by-default "legacy-tenant-generic"
+ * scope), and the stdio transport via the explicit LOCAL_STDIO_TRUST_CTX
+ * server.ts hands to registerTools. So a `!ctx` here is a misconfiguration,
+ * and it fails closed rather than granting max authority (clause 3,
+ * `.claude/rules/one-identity-layer.md`).
  */
 export declare function checkFromAllowed(ctx: OAuthContext | undefined, from: string): string | null;
+/**
+ * Answers the DELEGATION question — is `assignedTo` a member of the CALLER'S
+ * own organisation? — as distinct from `checkFromAllowed`, which answers a
+ * different question (may this client SPEAK AS `from`). Conflating the two
+ * meant every non-master client could only delegate to the one identity in
+ * its own `fromAllowList`, making cross-station dispatch impossible for any
+ * non-master client (Day-... delegation-same-org-predicate incident).
+ *
+ * Rules:
+ *   - master scope (isMasterScope) → allowed (null), no roster read needed.
+ *   - non-master AND `ctx.clerkJwt` present (the Clerk-team org-scoped path,
+ *     auth.ts case 2.5, ~line 507) → `getOrgRoster` is called and resolves
+ *     via Convex `withOrgScope`/`client_org_mapping`, forwarding THIS
+ *     caller's own verified Clerk JWT (`selectConvexClientForRequest`,
+ *     authenticatedConvexClient.ts). This is a genuine per-caller org lookup.
+ *     Allowed iff `assignedTo` is in that roster, OR the roster itself is
+ *     `["*"]` — a CALLER org whose `client_org_mapping.allowedOrchestrators`
+ *     is itself the wildcard (a genuinely open org, same semantics as
+ *     `isMaster = allowedOrchestrators.includes("*")` elsewhere in Convex,
+ *     convex/lib/auth.ts).
+ *   - non-master AND `ctx.clerkJwt` ABSENT AND the access token carries
+ *     `accessTokenHash` + `clerkOrgSlug` → `getOrgRoster` MUST resolve via
+ *     `orgRoster:getForAccessToken({ tokenHash })` (org derived inside
+ *     Convex from that token row). Never `getMyOrgRoster` (service-account
+ *     `["*"]` is ETA-M15).
+ *   - non-master AND `ctx.clerkJwt` ABSENT AND no token org claim
+ *     (DCR client-generic, legacy mcpTenants, unattached OAuth profiles)
+ *     → REFUSE LOUDLY, `getOrgRoster` is NEVER called. ETA-M15: these paths
+ *     route Convex through the MCP service-account; treating its `["*"]`
+ *     as the caller org is the leak.
+ *
+ * Async because it performs a data read (clerkJwt path or token-hash path).
+ * `ctx` undefined REFUSES (returns the refusal string), matching the other
+ * check* predicates' fail-closed no-context convention — an absent identity
+ * is never allowed to delegate.
+ */
+export declare function checkDelegationAllowed(ctx: OAuthContext | undefined, assignedTo: string, getOrgRoster: () => Promise<string[]>): Promise<string | null>;
 /**
  * Checks namespace against prefix list. A prefix of "*" means any namespace.
  * Otherwise the target namespace must start with one of the prefixes.