@orboto/mcp 0.211.3 → 0.212.1

package/dist/http-transport.js

@@ -12,6 +12,7 @@ import { resolveToolset } from './toolset.js';
 import { OrbotoClient, preflightMcpSession } from './orboto-client.js';
 import { EventBridge } from './event-bridge.js';
 import { mcpInstanceToken } from './tools/shared.js';
+import { releaseCapacityAtSessionEnd } from './tools/capacity-session.js';
 /** Default store backed by the api's `/system/mcp/sessions` endpoints. Each
  *  call builds a short-lived OrbotoClient bound to the request's token so the
  *  api scopes every read/write to that identity. */
@@ -278,6 +279,8 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                 }
             }
             void store.remove(token, sessionId).catch(() => { });
+            if (sessionId)
+                await releaseCapacityAtSessionEnd(existing?.client ?? new OrbotoClient({ baseUrl, apiKey: token }), mcpInstanceToken(undefined, { sessionId }));
             if (existing) {
                 await existing.transport.handleRequest(req, res);
                 return;

package/dist/http-transport.test.js

@@ -130,6 +130,7 @@ function fakeApi(opts = {}) {
         mcpUseGranted: opts.mcpUseGranted ?? true,
         userMcpEnabled: opts.userMcpEnabled ?? true,
         seenAuth: [],
+        capacityReleased: [],
     };
     const api = createNodeServer((req, res) => {
         const url = req.url ?? '';
@@ -154,6 +155,23 @@ function fakeApi(opts = {}) {
             res.end(JSON.stringify({ instructions: '' }));
             return;
         }
+        if (url.startsWith('/agents/session/unfinished')) {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ sessionId: 'sess-uuid', verdict: 'continue', reason: 'runnable', text: 'continue' }));
+            return;
+        }
+        if (url.startsWith('/capacity/claims?')) {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ items: [{ id: 'c-granted', resourceName: 'build-host:runner-1', state: 'granted' }, { id: 'c-queued', resourceName: 'unity:mac-1', state: 'queued' }], nextCursor: null }));
+            return;
+        }
+        const release = /^\/capacity\/claims\/([^/]+)\/release$/.exec(url);
+        if (release && req.method === 'POST') {
+            state.capacityReleased.push({ id: release[1], session: String(req.headers['x-orboto-agent-session'] ?? '') });
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ id: release[1], state: 'released' }));
+            return;
+        }
         if (url.startsWith('/sse/mcp-events')) {
             res.writeHead(200, { 'content-type': 'text/event-stream' });
             res.end();
@@ -238,6 +256,21 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
         await res.text();
         expect(store.resolve).toHaveBeenCalledWith('orb_alice', sid);
     });
+    it('ORB-2272 - the client ending its session (DELETE) releases the granted and the queued capacity claim of that session', async () => {
+        const store = fakeStore();
+        const fake = fakeApi();
+        const { base } = await startWithFakeApi(store.store, fake);
+        const initRes = await post(base, INIT_BODY, { authorization: 'Bearer orb_alice' });
+        const sid = initRes.headers.get('mcp-session-id');
+        await initRes.text();
+        const del = await fetch(`${base}/mcp`, { method: 'DELETE', headers: { authorization: 'Bearer orb_alice', 'mcp-session-id': sid } });
+        await del.text();
+        expect(del.status).toBeLessThan(300);
+        expect(fake.state.capacityReleased).toEqual([
+            { id: 'c-granted', session: `mcp-${sid}` },
+            { id: 'c-queued', session: `mcp-${sid}` },
+        ]);
+    });
     it('auto-adopts an unknown session id under a FRESH id when auth is valid (layer 2)', async () => {
         const store = fakeStore();
         const { base } = await startWithFakeApi(store.store);

package/dist/index.js

@@ -58,6 +58,8 @@ async function main() {
         const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
         const stdio = new StdioServerTransport();
         await server.connect(stdio);
+        const { releaseCapacityOnStdinEnd } = await import('./tools/capacity-session.js');
+        const releaseCapacity = releaseCapacityOnStdinEnd(process.stdin, preflightClient, (await import('./tools/shared.js')).mcpProcessInstance());
         if (channel) {
             const { InboxChannel, digestMinutesFromEnv, cliOutdatedNotice, CLI_OUTDATED_NOTICE } = await import('./inbox-channel.js');
             const { mcpProcessInstance } = await import('./tools/shared.js');
@@ -81,7 +83,7 @@ async function main() {
             const cleanup = () => { clearInterval(beats); inbox.close(); };
             stdio.onclose = cleanup;
             const { endProbeSessionOnStdinEnd } = await import('./probe-session.js');
-            endProbeSessionOnStdinEnd({ env: process.env, stdin: process.stdin, client: preflightClient, instanceToken, cleanup, exit: (code) => process.exit(code) });
+            endProbeSessionOnStdinEnd({ env: process.env, stdin: process.stdin, client: preflightClient, instanceToken, cleanup, exit: (code) => process.exit(code), settle: releaseCapacity });
         }
         return;
     }

package/dist/manifest-size.test.js

@@ -45,6 +45,8 @@ afterEach(() => { vi.restoreAllMocks(); });
  * write instead of after it (measured curated = 39,679 chars / 11,022
  * tokens, from 39,461 / 10,961 - one boolean parameter, no new tool). The
  * verdicts themselves ride the response, not the manifest.
+ * ORB-2338 added no named tool; the transcript rides the escape hatch and
+ * the resource.
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/oauth-bootstrap.js

@@ -3,7 +3,7 @@
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { VERSION } from './version.js';
@@ -83,7 +83,7 @@ export function buildAuthorizeUrl(authorizationEndpoint, params) {
     u.searchParams.set('state', params.state);
     return u.toString();
 }
-function parseTokenResponse(json) {
+function parseTokenResponse(json, now = Date.now) {
     const t = json;
     if (!t.access_token)
         throw new Error('OAuth token response missing access_token');
@@ -91,7 +91,7 @@ function parseTokenResponse(json) {
     return {
         accessToken: t.access_token,
         refreshToken: t.refresh_token ?? null,
-        expiresAt: Date.now() + expiresInMs,
+        expiresAt: now() + expiresInMs,
         scope: t.scope ?? BOOTSTRAP_SCOPE,
     };
 }
@@ -113,7 +113,7 @@ export async function exchangeAuthCode(tokenEndpoint, params, fetchImpl = fetch)
     }
     return parseTokenResponse(await res.json());
 }
-export async function refreshTokens(tokenEndpoint, params, fetchImpl = fetch) {
+export async function refreshTokens(tokenEndpoint, params, fetchImpl = fetch, now = Date.now) {
     const res = await fetchImpl(tokenEndpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
@@ -127,7 +127,7 @@ export async function refreshTokens(tokenEndpoint, params, fetchImpl = fetch) {
         const body = await res.text().catch(() => '');
         throw new Error(`OAuth token refresh failed: ${res.status} ${body}`);
     }
-    return parseTokenResponse(await res.json());
+    return parseTokenResponse(await res.json(), now);
 }
 /** Cache file path. Honours ORBOTO_MCP_TOKEN_CACHE for tests / custom homes. */
 export function tokenCachePath() {
@@ -149,37 +149,91 @@ export function loadCachedGrant(origin, path = tokenCachePath()) {
     const file = readCacheFile(path);
     return file[origin] ?? null;
 }
-export function saveCachedGrant(origin, grant, path = tokenCachePath()) {
-    const file = readCacheFile(path);
-    file[origin] = grant;
+function writeCacheFile(path, file) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2), { mode: 0o600 });
     try {
-        chmodSync(path, 0o600);
+        chmodSync(tmp, 0o600);
     }
     catch { /* best-effort on platforms without chmod */ }
+    renameSync(tmp, path);
+}
+export function saveCachedGrant(origin, grant, path = tokenCachePath()) {
+    const file = readCacheFile(path);
+    file[origin] = grant;
+    writeCacheFile(path, file);
 }
 export function clearCachedGrant(origin, path = tokenCachePath()) {
     const file = readCacheFile(path);
     if (!(origin in file))
         return;
     delete file[origin];
+    writeCacheFile(path, file);
+}
+export const CACHE_LOCK_STALE_MS = 60_000;
+export const CACHE_LOCK_TIMEOUT_MS = 75_000;
+/** Runs `fn` while holding `<cache>.lock`, so processes sharing one cache never present the same refresh token twice. */
+export async function withCacheLock(path, fn, opts = {}) {
+    const lockPath = `${path}.lock`;
+    const staleMs = opts.staleMs ?? CACHE_LOCK_STALE_MS;
+    const deadline = Date.now() + (opts.timeoutMs ?? CACHE_LOCK_TIMEOUT_MS);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+    for (;;) {
+        try {
+            const fd = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeSync(fd, String(process.pid));
+            }
+            finally {
+                closeSync(fd);
+            }
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > staleMs) {
+                    unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error('Another orboto-mcp process holds the OAuth cache lock.');
+            await new Promise((r) => setTimeout(r, 25));
+        }
+    }
     try {
-        chmodSync(path, 0o600);
+        return await fn();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* already reclaimed as stale */ }
     }
-    catch { /* best-effort */ }
 }
 /**
  * Build a token provider around an initial token set + a refresh closure.
- * Kept pure (no I/O of its own beyond the injected refresh fn) so the
- * refresh-on-expiry logic unit tests deterministically with a fake clock.
+ * With a store, a refresh first adopts a newer token set another process
+ * persisted and rotates only when no live access token is on disk.
  */
-export function createTokenProvider(initial, refresh, onRefreshed, now = Date.now) {
+export function createTokenProvider(initial, refresh, onRefreshed, now = Date.now, store) {
     let current = initial;
     let inflight = null;
-    async function doRefresh() {
+    const live = (t) => now() < t.expiresAt - EXPIRY_SKEW_MS;
+    async function rotate(forced) {
+        const seen = current.accessToken;
+        const stored = store?.read();
+        if (stored && stored.refreshToken && stored.refreshToken !== current.refreshToken) {
+            current = stored;
+            if (live(stored) && (!forced || stored.accessToken !== seen))
+                return current.accessToken;
+        }
         if (!current.refreshToken) {
             throw new Error('OAuth session expired and no refresh token is available - reconnect the client.');
         }
@@ -188,17 +242,20 @@ export function createTokenProvider(initial, refresh, onRefreshed, now = Date.no
         onRefreshed?.(current);
         return current.accessToken;
     }
+    function doRefresh(forced) {
+        return store ? store.withLock(() => rotate(forced)) : rotate(forced);
+    }
     return {
         async getAccessToken() {
-            if (now() < current.expiresAt - EXPIRY_SKEW_MS)
+            if (live(current))
                 return current.accessToken;
             if (!inflight)
-                inflight = doRefresh().finally(() => { inflight = null; });
+                inflight = doRefresh(false).finally(() => { inflight = null; });
             return inflight;
         },
         async forceRefresh() {
             if (!inflight)
-                inflight = doRefresh().finally(() => { inflight = null; });
+                inflight = doRefresh(true).finally(() => { inflight = null; });
             return inflight;
         },
     };
@@ -324,43 +381,70 @@ export async function runLoopbackAuthorization(opts) {
 }
 /**
  * Resolve an OAuth token provider for the stdio proxy. Order:
- *   1. A cached grant whose refresh token still works -> silent refresh.
- *   2. Otherwise run the interactive browser-assisted loopback flow once.
- * Either way the resulting grant is persisted (0600) so the next boot is
- * silent. The returned provider auto-refreshes and re-persists on rotation.
+ *   1. A cached grant with a live access token -> used as is, nothing rotates.
+ *   2. A cached grant whose refresh token still works -> silent refresh under the cache lock.
+ *   3. Otherwise run the interactive browser-assisted loopback flow once.
+ * The returned provider re-reads the cache under the lock before every refresh.
  */
 export async function bootstrapOAuth(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const log = opts.log ?? ((m) => process.stderr.write(`${m}\n`));
     const origin = deriveOrigin(opts.apiBaseUrl);
     const cachePath = opts.cachePath ?? tokenCachePath();
-    const persist = (clientId, tokenEndpoint, tokens) => {
-        if (tokens.refreshToken) {
+    const now = opts.now ?? Date.now;
+    const providerFor = (clientId, tokenEndpoint, initial) => {
+        const store = {
+            withLock: (fn) => withCacheLock(cachePath, fn),
+            read: () => {
+                const g = loadCachedGrant(origin, cachePath);
+                if (!g || g.clientId !== clientId)
+                    return null;
+                return { accessToken: g.accessToken ?? '', refreshToken: g.refreshToken, expiresAt: g.expiresAt ?? 0, scope: g.scope };
+            },
+        };
+        const persist = (tokens) => {
+            if (!tokens.refreshToken)
+                return;
             saveCachedGrant(origin, {
                 clientId, tokenEndpoint, refreshToken: tokens.refreshToken, scope: tokens.scope,
+                accessToken: tokens.accessToken, expiresAt: tokens.expiresAt,
             }, cachePath);
-        }
+        };
+        return createTokenProvider(initial, (rt) => refreshTokens(tokenEndpoint, { clientId, refreshToken: rt }, fetchImpl, now), persist, now, store);
     };
     const cached = loadCachedGrant(origin, cachePath);
     if (cached) {
+        const provider = providerFor(cached.clientId, cached.tokenEndpoint, {
+            accessToken: cached.accessToken ?? '', refreshToken: cached.refreshToken,
+            expiresAt: cached.expiresAt ?? 0, scope: cached.scope,
+        });
         try {
-            const tokens = await refreshTokens(cached.tokenEndpoint, {
-                clientId: cached.clientId, refreshToken: cached.refreshToken,
-            }, fetchImpl);
-            persist(cached.clientId, cached.tokenEndpoint, tokens);
+            await provider.getAccessToken();
             log('[orboto-mcp] reconnected via cached OAuth session (no browser needed)');
-            return createTokenProvider(tokens, (rt) => refreshTokens(cached.tokenEndpoint, { clientId: cached.clientId, refreshToken: rt }, fetchImpl), (next) => persist(cached.clientId, cached.tokenEndpoint, next));
+            return provider;
         }
         catch (e) {
             log(`[orboto-mcp] cached OAuth session no longer valid (${e.message}); re-authorizing`);
-            clearCachedGrant(origin, cachePath);
+            await withCacheLock(cachePath, async () => {
+                const onDisk = loadCachedGrant(origin, cachePath);
+                const renewedElsewhere = onDisk?.accessToken && (onDisk.expiresAt ?? 0) - EXPIRY_SKEW_MS > now();
+                if (onDisk && !renewedElsewhere)
+                    clearCachedGrant(origin, cachePath);
+            });
         }
     }
     const meta = await discoverAuthServer(origin, fetchImpl);
     const { tokens, clientId } = await runLoopbackAuthorization({
         meta, log, openBrowser: opts.openBrowser, fetchImpl,
     });
-    persist(clientId, meta.token_endpoint, tokens);
+    if (tokens.refreshToken) {
+        await withCacheLock(cachePath, async () => {
+            saveCachedGrant(origin, {
+                clientId, tokenEndpoint: meta.token_endpoint, refreshToken: tokens.refreshToken, scope: tokens.scope,
+                accessToken: tokens.accessToken, expiresAt: tokens.expiresAt,
+            }, cachePath);
+        });
+    }
     log('[orboto-mcp] OAuth authorization complete');
-    return createTokenProvider(tokens, (rt) => refreshTokens(meta.token_endpoint, { clientId, refreshToken: rt }, fetchImpl), (next) => persist(clientId, meta.token_endpoint, next));
+    return providerFor(clientId, meta.token_endpoint, tokens);
 }

package/dist/oauth-bootstrap.test.js

@@ -5,11 +5,11 @@
  * its testable pieces (PKCE, authorize-url, request builders).
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
-import { generatePkce, buildAuthorizeUrl, deriveOrigin, discoverAuthServer, registerLoopbackClient, exchangeAuthCode, refreshTokens, loadCachedGrant, saveCachedGrant, clearCachedGrant, createTokenProvider, bootstrapOAuth, EXPIRY_SKEW_MS, } from './oauth-bootstrap.js';
+import { generatePkce, buildAuthorizeUrl, deriveOrigin, discoverAuthServer, registerLoopbackClient, exchangeAuthCode, refreshTokens, loadCachedGrant, saveCachedGrant, clearCachedGrant, createTokenProvider, bootstrapOAuth, withCacheLock, EXPIRY_SKEW_MS, } from './oauth-bootstrap.js';
 describe('PKCE', () => {
     it('produces an S256 challenge that verifies against the verifier', () => {
         const { verifier, challenge, method } = generatePkce();
@@ -198,3 +198,119 @@ describe('bootstrapOAuth cached-grant path', () => {
         expect(loadCachedGrant('https://x.test', path)).toBeNull();
     });
 });
+describe('createTokenProvider with a shared store', () => {
+    const expired = { accessToken: 'at0', refreshToken: 'rt0', expiresAt: 0, scope: 'mcp' };
+    const storeOf = (read) => ({ withLock: (fn) => fn(), read });
+    it('adopts a newer live token set persisted after construction instead of rotating', async () => {
+        const refresh = vi.fn();
+        const p = createTokenProvider(expired, refresh, undefined, () => 1_000, storeOf(() => ({
+            accessToken: 'at5', refreshToken: 'rt5', expiresAt: 10_000_000, scope: 'mcp',
+        })));
+        expect(await p.getAccessToken()).toBe('at5');
+        expect(refresh).not.toHaveBeenCalled();
+    });
+    it('continues from the newer refresh token when the stored access token is expired too', async () => {
+        const refresh = vi.fn().mockResolvedValue({ accessToken: 'at6', refreshToken: 'rt6', expiresAt: 10_000_000, scope: 'mcp' });
+        const p = createTokenProvider(expired, refresh, undefined, () => 1_000, storeOf(() => ({
+            accessToken: 'at5', refreshToken: 'rt5', expiresAt: 0, scope: 'mcp',
+        })));
+        expect(await p.getAccessToken()).toBe('at6');
+        expect(refresh).toHaveBeenCalledWith('rt5');
+    });
+    it('forceRefresh with the same stored token rotates it, with a different live one adopts it', async () => {
+        const live = { accessToken: 'at1', refreshToken: 'rt1', expiresAt: 10_000_000, scope: 'mcp' };
+        const refresh = vi.fn().mockResolvedValue({ accessToken: 'at2', refreshToken: 'rt2', expiresAt: 10_000_000, scope: 'mcp' });
+        let onDisk = live;
+        const p = createTokenProvider(live, refresh, (n) => { onDisk = n; }, () => 1_000, storeOf(() => onDisk));
+        expect(await p.forceRefresh()).toBe('at2');
+        expect(refresh).toHaveBeenCalledWith('rt1');
+        onDisk = { accessToken: 'at9', refreshToken: 'rt9', expiresAt: 10_000_000, scope: 'mcp' };
+        expect(await p.forceRefresh()).toBe('at9');
+        expect(refresh).toHaveBeenCalledOnce();
+    });
+});
+describe('bootstrapOAuth with two processes on one cache', () => {
+    let dir;
+    let path;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'orboto-oauth-'));
+        path = join(dir, 'cache.json');
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+    function rotatingServer() {
+        let live = 'rt0';
+        let n = 0;
+        const sent = [];
+        const fetchImpl = vi.fn(async (_url, init) => {
+            const body = JSON.parse(String(init?.body));
+            sent.push(body.refresh_token);
+            await new Promise((r) => setTimeout(r, 30));
+            if (body.refresh_token !== live)
+                return new Response('{"error":"invalid_grant"}', { status: 400 });
+            n += 1;
+            live = `rt${n}`;
+            return jsonResponse({ access_token: `at${n}`, refresh_token: live, expires_in: 3600, scope: 'mcp offline_access' });
+        });
+        return { fetchImpl, sent };
+    }
+    const seed = () => saveCachedGrant('https://x.test', {
+        clientId: 'cid', refreshToken: 'rt0', scope: 'mcp offline_access', tokenEndpoint: 'https://x.test/oauth/token',
+    }, path);
+    it('two concurrent boots on an expired cache rotate once and share the token', async () => {
+        seed();
+        const { fetchImpl, sent } = rotatingServer();
+        const boot = () => bootstrapOAuth({ apiBaseUrl: 'https://x.test/api', fetchImpl, openBrowser: vi.fn(), cachePath: path, log: () => { } });
+        const [a, b] = await Promise.all([boot(), boot()]);
+        expect(sent).toEqual(['rt0']);
+        expect(await a.getAccessToken()).toBe('at1');
+        expect(await b.getAccessToken()).toBe('at1');
+        expect(loadCachedGrant('https://x.test', path)).toMatchObject({ refreshToken: 'rt1', accessToken: 'at1' });
+    });
+    it('a boot with a live cached access token rotates nothing, and the later refresh sends the first process rotated token', async () => {
+        seed();
+        const { fetchImpl, sent } = rotatingServer();
+        let offset = 0;
+        const now = () => Date.now() + offset;
+        const boot = () => bootstrapOAuth({ apiBaseUrl: 'https://x.test/api', fetchImpl, openBrowser: vi.fn(), cachePath: path, log: () => { }, now });
+        const a = await boot();
+        const b = await boot();
+        expect(sent).toEqual(['rt0']);
+        offset = 2 * 3600_000;
+        expect(await a.getAccessToken()).toBe('at2');
+        expect(await b.getAccessToken()).toBe('at2');
+        expect(sent).toEqual(['rt0', 'rt1']);
+        offset = 4 * 3600_000;
+        expect(await b.forceRefresh()).toBe('at3');
+        expect(sent).toEqual(['rt0', 'rt1', 'rt2']);
+        expect(await a.getAccessToken()).toBe('at3');
+        expect(sent).toHaveLength(3);
+    });
+});
+describe('withCacheLock', () => {
+    let dir;
+    let path;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'orboto-oauth-'));
+        path = join(dir, 'cache.json');
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+    it('serialises holders and removes the lock file afterwards', async () => {
+        const order = [];
+        const hold = (tag) => withCacheLock(path, async () => {
+            order.push(`${tag}+`);
+            await new Promise((r) => setTimeout(r, 20));
+            order.push(`${tag}-`);
+        });
+        await Promise.all([hold('a'), hold('b')]);
+        expect(order.join(' ')).toMatch(/^(a\+ a- b\+ b-|b\+ b- a\+ a-)$/);
+        expect(existsSync(`${path}.lock`)).toBe(false);
+    });
+    it('reclaims a stale lock and times out on a held one', async () => {
+        writeFileSync(`${path}.lock`, '1');
+        const old = new Date(Date.now() - 120_000);
+        utimesSync(`${path}.lock`, old, old);
+        await expect(withCacheLock(path, async () => 'ok')).resolves.toBe('ok');
+        writeFileSync(`${path}.lock`, '1');
+        await expect(withCacheLock(path, async () => 'x', { timeoutMs: 60 })).rejects.toThrow(/holds the OAuth cache lock/);
+    });
+});

package/dist/probe-session.js

@@ -10,7 +10,9 @@ export function endProbeSessionOnStdinEnd(opts) {
             return;
         ended = true;
         opts.cleanup();
-        void opts.client.post('/v1/agent/end-session', {}, { instanceToken: opts.instanceToken })
+        void (opts.settle ?? (() => Promise.resolve()))()
+            .catch(() => undefined)
+            .then(() => opts.client.post('/v1/agent/end-session', {}, { instanceToken: opts.instanceToken }))
             .catch(() => undefined)
             .finally(() => opts.exit(0));
     };

package/dist/probe-session.test.js

@@ -3,13 +3,13 @@ import { EventEmitter } from 'node:events';
 import { readFileSync } from 'node:fs';
 import { describe, expect, it, vi } from 'vitest';
 import { endProbeSessionOnStdinEnd, PROBE_SESSION_ENV } from './probe-session.js';
-function harness(env) {
+function harness(env, settle) {
     const stdin = new EventEmitter();
     const calls = [];
     const client = { post: async (path, body, opts) => { calls.push({ path, body, instanceToken: opts?.instanceToken }); return undefined; } };
     const cleanup = vi.fn();
     const exit = vi.fn();
-    const armed = endProbeSessionOnStdinEnd({ env, stdin, client, instanceToken: 'agent-0123456789ab', cleanup, exit });
+    const armed = endProbeSessionOnStdinEnd({ env, stdin, client, instanceToken: 'agent-0123456789ab', cleanup, exit, ...(settle ? { settle } : {}) });
     return { stdin, calls, cleanup, exit, armed };
 }
 describe('ORB-2263 - probe session end', () => {
@@ -26,6 +26,15 @@ describe('ORB-2263 - probe session end', () => {
         expect(h.cleanup).toHaveBeenCalledTimes(1);
         expect(h.calls).toEqual([{ path: '/v1/agent/end-session', body: {}, instanceToken: 'agent-0123456789ab' }]);
     });
+    it('ORB-2272 - releases the session\'s capacity claims before the session row ends, even when that release fails', async () => {
+        const order = [];
+        const h = harness({ [PROBE_SESSION_ENV]: '1' }, async () => { order.push('capacity'); throw new Error('api down'); });
+        const post = h.calls;
+        h.stdin.emit('end');
+        await vi.waitFor(() => expect(h.exit).toHaveBeenCalledWith(0));
+        expect(order).toEqual(['capacity']);
+        expect(post.map((c) => c.path)).toEqual(['/v1/agent/end-session']);
+    });
     it('leaves a real session alone so a resume keeps its row', () => {
         const h = harness({});
         expect(h.armed).toBe(false);

package/dist/resources.js

@@ -5,6 +5,7 @@ import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { OrbotoApiError } from './orboto-client.js';
 import { loadRequiredRules } from './required-rules.js';
 import { resolveProjectByKey, resolveTicketByKey } from './tools/shared.js';
+import { readTranscriptResource } from './tools/live-transcript.js';
 export function registerOrbotoResources(server, client) {
     server.registerResource('rules', new ResourceTemplate('orboto://rules', { list: undefined }), {
         title: 'Workspace agent rules (complete)',
@@ -74,6 +75,13 @@ export function registerOrbotoResources(server, client) {
                 }],
         };
     });
+    server.registerResource('live-transcript', new ResourceTemplate('orboto://live/{sessionId}/transcript', { list: undefined }), {
+        title: 'Live session transcript',
+        description: 'ORB-2338 - the newest lines of a live agent session you may see: prompts, assistant markdown, tool groups, turn ends, usage and context, masked. Cut to 4,000 characters with an explicit note; the rest is paged with `orboto_api_call get /agents/live-sessions/<id>/transcript?afterSeq=N`.',
+        mimeType: 'text/markdown',
+    }, async (uri, vars) => ({
+        contents: [{ uri: uri.href, mimeType: 'text/markdown', text: await readTranscriptResource(client, String(vars.sessionId)) }],
+    }));
     server.registerResource('search', new ResourceTemplate('orboto://search/{query}', { list: undefined }), {
         title: 'orboto search',
         description: 'Full-text search across tickets, comments, docs - visibility-filtered.',

package/dist/server.js

@@ -28,6 +28,7 @@ import { agentBroadcastToolConfig, makeAgentBroadcastHandler, } from './tools/ag
 import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools/agent-message-work.js';
 import { agentMessagesToolConfig, makeAgentMessagesHandler } from './tools/agent-messages.js';
 import { agentWakesToolConfig, makeAgentWakesHandler } from './tools/agent-wakes.js';
+import { agentWhoToolConfig, makeAgentWhoHandler } from './tools/agent-who.js';
 import { sessionCheckToolConfig, makeSessionCheckHandler } from './tools/session-check.js';
 import { knowledgeAskToolConfig, makeKnowledgeAskHandler, knowledgeAddToolConfig, makeKnowledgeAddHandler } from './tools/knowledge.js';
 import { listProjectsToolConfig, makeListProjectsHandler } from './tools/list-projects.js';
@@ -210,6 +211,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_delete_agent_instruction', deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler(client));
     reg('orboto_agent_heartbeat', agentHeartbeatToolConfig, makeAgentHeartbeatHandler(client));
     reg('orboto_agent_presence', agentPresenceToolConfig, makeAgentPresenceHandler(client));
+    reg('orboto_who', agentWhoToolConfig, makeAgentWhoHandler(client));
     reg('orboto_agent_notify', agentNotifyToolConfig, makeAgentNotifyHandler(client));
     reg('orboto_message_work', agentMessageWorkToolConfig, makeAgentMessageWorkHandler(client));
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));

package/dist/tail-labels.js

@@ -0,0 +1,30 @@
+/** ORB-2272, ORB-2274 - an orboto_api_call on a tail route is logged under the tool name it stands in for; leaf module. */
+const SEG = '[^/]+';
+export const TAIL_LABELS = [
+    { method: 'GET', path: new RegExp(`^/capacity/resources(/${SEG}(/queue)?)?$`), label: 'orboto_capacity_list' },
+    { method: 'GET', path: new RegExp(`^/capacity/claims(/${SEG})?$`), label: 'orboto_capacity_list' },
+    { method: 'POST', path: /^\/capacity\/claims$/, label: 'orboto_capacity_claim' },
+    { method: 'POST', path: new RegExp(`^/capacity/claims/${SEG}/renew$`), label: 'orboto_capacity_renew' },
+    { method: 'POST', path: new RegExp(`^/capacity/claims/${SEG}/release$`), label: 'orboto_capacity_release' },
+    { method: 'GET', path: /^\/capacity\/windows$/, label: 'orboto_capacity_windows' },
+    { method: 'GET', path: /^\/capacity\/metrics$/, label: 'orboto_capacity_stats' },
+    { method: 'GET', path: new RegExp(`^/capacity/resources/${SEG}/plan$`), label: 'orboto_capacity_plan' },
+    { method: 'POST', path: new RegExp(`^/capacity/resources/${SEG}/plan$`), label: 'orboto_capacity_plan' },
+    { method: 'POST', path: /^\/capacity\/seeds\/nightly-unity$/, label: 'orboto_capacity_seed' },
+];
+/** The metrics label of one tool call: the stand-in tool name for a labelled api_call, else the tool name itself. */
+export function metricsToolName(toolName, args) {
+    if (toolName !== 'orboto_api_call' || !args || typeof args !== 'object')
+        return toolName;
+    const { method, path } = args;
+    if (typeof method !== 'string' || typeof path !== 'string')
+        return toolName;
+    const bare = path.split('?')[0].replace(/\/+$/, '');
+    const hit = TAIL_LABELS.find((l) => l.method === method.toUpperCase() && l.path.test(bare));
+    return hit ? hit.label : toolName;
+}
+/** The inner HTTP status of an api_call envelope, so a labelled call that the API refused counts as a failure. */
+export function envelopeStatus(structured) {
+    const status = structured?.status;
+    return typeof status === 'number' ? status : undefined;
+}

package/dist/tool-parameters.test.js

@@ -1,10 +1,11 @@
 /**
  * ORB-1805 - the schema diet must never cost a PARAMETER.
  *
- * ORB-2157 - one reviewed baseline edit: `orboto_help.tool` is no longer
- * required, because the tool now also answers `topic` ("connect" returns the
- * setup script). The parameter itself is untouched and still the only way to
- * ask for a tool's guidance; a call with neither says which topics exist.
+ * Reviewed baseline edits: ORB-2157 made `orboto_help.tool` optional (the
+ * tool also answers `topic`; a call with neither lists the topics); ORB-2264
+ * made `orboto_agent_notify.targetEmail` optional (`to` names the recipient
+ * too, a role address like integrator@KEY reaches several accounts; the
+ * parameter stays and narrows a role address to one account).
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { readFileSync } from 'node:fs';