@orboto/mcp 0.211.2 → 0.212.0

package/dist/tools/agent-coordination.js

@@ -5,6 +5,7 @@
  */
 import { z } from 'zod';
 import { AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
+import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken } from './shared.js';
 import { AgentSessionScopeSchema } from './agent-session-scope.js';
 export const agentHeartbeatToolConfig = {
@@ -84,11 +85,32 @@ export function makeAgentPresenceHandler(client) {
 }
 /** ORB-2263 - mirror of AgentNotifyRoutedToSchema in @orboto/shared-schema (drift test in agent-coordination.test.ts). */
 export const NOTIFY_ROUTED_TO = ['session', 'scope', 'account'];
+/** ORB-2264 - the 409 `no_recipient` as a tool error naming who could receive it instead. */
+export function noRecipientText(err) {
+    if (err.status !== 409)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(err.body);
+    }
+    catch {
+        return null;
+    }
+    if (body.errorKey !== 'errors.agents.no_recipient')
+        return null;
+    const p = body.errorParams ?? {};
+    const live = (p.liveSessions ?? []).map((s) => `${s.addresses[0] ?? s.email} (${s.email}, ${s.shortId})`);
+    return `not sent: no live session can receive a request to ${p.address ?? '?'} (${p.reason ?? 'no_recipient'}). `
+        + (live.length ? `Live sessions: ${live.join('; ')}. ` : 'No live session declared the project. ')
+        + 'Address one of them, or send again with queue: true and project to keep it until a session declares the project.';
+}
 export const agentNotifyToolConfig = {
     title: 'Notify another agent / user',
-    description: 'Message a user (bot or human) by email; lands in their inbox (orboto_messages), for humans in-app. kind: request|error = work inside the scope the recipient holds (request needs project or toSessionRef + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136). The answer names routedTo (session, scope or account); routingNote "no session declared KEY" means nothing wakes - escalate instead of assuming delivery (ORB-2263).',
+    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account, each as addressed mail), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; orboto_who lists them before sending) unless queue: true keeps it in the inbox until a session declares the project (ORB-2264). The answer names routedTo (session, scope or account); routingNote "no session declared KEY" means nothing wakes - escalate instead of assuming delivery (ORB-2263).',
     inputSchema: z.object({
-        targetEmail: z.string().email(),
+        targetEmail: z.string().email().optional(),
+        to: z.string().min(3).max(200).optional(),
+        queue: z.boolean().optional(),
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
         subject: z.string().min(1).max(200),
         outcome: z.string().min(10).max(1000).optional(),
@@ -104,6 +126,8 @@ export const agentNotifyToolConfig = {
         toSessionId: z.string().uuid().nullable(),
         routedTo: z.enum(NOTIFY_ROUTED_TO),
         routingNote: z.string().optional(),
+        recipients: z.array(z.string()).optional(),
+        queued: z.boolean().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -134,11 +158,13 @@ export function makeAgentBroadcastHandler(client) {
 /** ORB-2223 - the message-kind definition this versioned sender enforces; the API only warns. */
 export function notifyDefinitionError(args) {
     const kind = args.kind ?? 'info';
+    if (!args.to && !args.targetEmail)
+        return 'Invalid arguments: name a recipient - `to` (integrator@KEY, an email or a session id) or `targetEmail`.';
     if ((kind === 'request' || kind === 'complete') && !args.outcome?.trim()) {
         return `Invalid arguments: \`outcome\` is required for a ${kind} - the outcome sentence (what must be true when it is done, or what was delivered).`;
     }
-    if (kind === 'request' && !args.project && !args.toSessionRef) {
-        return 'Invalid arguments: a request needs a target - `project` (key or UUID) or `toSessionRef`.';
+    if (kind === 'request' && !args.project && !args.toSessionRef && !(args.to && !args.to.includes('.'))) {
+        return 'Invalid arguments: a request needs a target - a role address in `to` (integrator@KEY), `project` (key or UUID) or `toSessionRef`.';
     }
     return null;
 }
@@ -148,13 +174,29 @@ export function makeAgentNotifyHandler(client) {
         if (invalid)
             return { isError: true, content: [{ type: 'text', text: invalid }] };
         const senderRef = mcpInstanceToken(args.senderRef, extra);
-        const res = await client.post('/v1/agent/notify', { ...args, senderRef }, { instanceToken: mcpInstanceToken(undefined, extra) });
-        const target = res.toSessionId ? `${args.targetEmail} session ${res.toSessionId.slice(0, 8)}` : args.targetEmail;
+        let res;
+        try {
+            res = await client.post('/v1/agent/notify', { ...args, senderRef }, { instanceToken: mcpInstanceToken(undefined, extra) });
+        }
+        catch (err) {
+            const refused = err instanceof OrbotoApiError ? noRecipientText(err) : null;
+            if (refused)
+                return { isError: true, content: [{ type: 'text', text: refused }] };
+            throw err;
+        }
+        const who = args.to ?? args.targetEmail ?? '?';
+        const recipients = (res.recipients ?? []).map((r) => r.label);
+        const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${who} session ${res.toSessionId.slice(0, 8)}` : who;
         const routedTo = res.routedTo ?? (res.toSessionId ? 'session' : 'account');
         const note = res.routingNote ? ` - ${res.routingNote}` : '';
         return {
-            content: [{ type: 'text', text: `notified ${target} (message ${res.messageId}, routed to ${routedTo}${note})` }],
-            structuredContent: { ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null, routedTo, ...(res.routingNote ? { routingNote: res.routingNote } : {}) },
+            content: [{ type: 'text', text: `${res.queued ? 'queued for' : 'notified'} ${target} (message ${res.messageId}, routed to ${routedTo}${note})` }],
+            structuredContent: {
+                ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null, routedTo,
+                ...(res.routingNote ? { routingNote: res.routingNote } : {}),
+                ...(recipients.length ? { recipients } : {}),
+                ...(res.queued ? { queued: true } : {}),
+            },
         };
     };
 }

package/dist/tools/agent-coordination.test.js

@@ -267,3 +267,45 @@ describe('ORB-2136 - session addressing', () => {
         expect(result.structuredContent).toMatchObject({ scope: { role: 'integrator', projectKeys: ['ORB'] } });
     });
 });
+describe('orboto_agent_notify role addresses (ORB-2264)', () => {
+    it('sends `to` as written, lists every recipient and needs no targetEmail', async () => {
+        const bodies = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            bodies.push(JSON.parse(String(init.body)));
+            return {
+                ok: true, status: 200, statusText: 'OK', text: async () => '',
+                json: async () => ({
+                    ok: true, messageId: '00000000-0000-4000-8000-000000000001', toSessionId: '00000000-0000-4000-8000-0000000000aa', routedTo: 'session',
+                    messageIds: ['00000000-0000-4000-8000-000000000001', '00000000-0000-4000-8000-000000000002'],
+                    recipients: [{ label: 'claude@orboto.io (integrator, aaaaaaaa)', sessionId: 'a' }, { label: 'claude+b@orboto.io (integrator, bbbbbbbb)', sessionId: 'b' }],
+                }),
+            };
+        });
+        const result = await makeAgentNotifyHandler(client)({ to: 'integrator@ORB', kind: 'request', subject: 'release 0.212.0', outcome: 'the release is tagged and deployed' });
+        expect(bodies[0]).toMatchObject({ to: 'integrator@ORB', kind: 'request' });
+        expect(bodies[0].targetEmail).toBeUndefined();
+        expect(result.structuredContent).toMatchObject({ routedTo: 'session', recipients: ['claude@orboto.io (integrator, aaaaaaaa)', 'claude+b@orboto.io (integrator, bbbbbbbb)'] });
+    });
+    it('turns 409 no_recipient into a tool error that names the live sessions and the queue option', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: false, status: 409, statusText: 'Conflict', json: async () => ({}),
+            text: async () => JSON.stringify({
+                error: 'x', errorKey: 'errors.agents.no_recipient',
+                errorParams: { address: 'review@ORB', reason: 'no_recipient', liveSessions: [{ shortId: 'f072e1c5', email: 'claude@orboto.io', addresses: ['integrator@ORB'] }] },
+            }),
+        }));
+        const result = await makeAgentNotifyHandler(client)({ to: 'review@ORB', kind: 'request', subject: 'review ORB-1', outcome: 'ORB-1 is reviewed with findings' });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain('review@ORB');
+        expect(text).toContain('integrator@ORB (claude@orboto.io, f072e1c5)');
+        expect(text).toContain('queue: true');
+    });
+    it('refuses a message without any recipient before calling the API', async () => {
+        const fetch = vi.spyOn(globalThis, 'fetch');
+        const result = await makeAgentNotifyHandler(client)({ subject: 'nobody' });
+        expect(result.isError).toBe(true);
+        expect(fetch).not.toHaveBeenCalled();
+        expect(agentNotifyToolConfig.description).toContain('integrator@KEY');
+    });
+});

package/dist/tools/agent-who.js

@@ -0,0 +1,34 @@
+/** ORB-2264 - the live directory: who a sender can address before sending. */
+import { z } from 'zod';
+import { AgentSessionRoleSchema } from './agent-session-scope.js';
+export const agentWhoToolConfig = {
+    title: 'Who can receive agent mail',
+    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. Each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log.',
+    inputSchema: z.object({
+        project: z.string().min(1).max(64).optional(),
+        role: AgentSessionRoleSchema.optional(),
+    }).shape,
+    outputSchema: z.object({ sessions: z.array(z.record(z.string(), z.unknown())) }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+/** One directory row as a line: address, account, session, projects, channel, ticket. */
+export function whoLine(s) {
+    const address = s.addresses.join(', ') || (s.role ? `${s.role} (no project)` : 'no scope');
+    const channel = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
+    const ticket = s.currentTicket ? `; on ${s.currentTicket.key ?? s.currentTicket.title}` : '';
+    return `- ${address} - ${s.email} session ${s.shortId}, ${s.status}, ${channel}, last seen ${s.lastSeenAt}${ticket}`;
+}
+export function makeAgentWhoHandler(client) {
+    return async (args = {}) => {
+        const qs = new URLSearchParams();
+        if (args.project)
+            qs.set('project', args.project);
+        if (args.role)
+            qs.set('role', args.role);
+        const res = await client.get(`/v1/agent/who${qs.size ? `?${qs.toString()}` : ''}`);
+        const lines = res.sessions.length
+            ? [`${res.sessions.length} live session(s):`, ...res.sessions.map(whoLine)]
+            : ['No live session matches - a request sent now answers no_recipient unless it is queued.'];
+        return { content: [{ type: 'text', text: lines.join('\n') }], structuredContent: { sessions: res.sessions } };
+    };
+}

package/dist/tools/agent-who.test.js

@@ -0,0 +1,31 @@
+/** ORB-2264 - orboto_who reads the live directory. */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { agentWhoToolConfig, makeAgentWhoHandler, whoLine } from './agent-who.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+const entry = {
+    sessionId: 'f072e1c5-0000-4000-8000-000000000000', shortId: 'f072e1c5', email: 'claude@orboto.io', role: 'integrator',
+    projectKeys: ['ORB'], addresses: ['integrator@ORB'], lastSeenAt: '2026-09-30T08:00:00Z',
+    channel: { announced: 'claude-code', online: true }, currentTicket: { key: 'ORB-2264', title: 'mail' }, status: 'working',
+};
+describe('orboto_who', () => {
+    it('GETs /v1/agent/who with the filters and prints one line per session', async () => {
+        const urls = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+            urls.push(String(url));
+            return { ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [entry] }) };
+        });
+        const result = await makeAgentWhoHandler(client)({ project: 'ORB', role: 'integrator' });
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?project=ORB&role=integrator');
+        expect(result.content[0].text).toContain('integrator@ORB - claude@orboto.io session f072e1c5, working, claude-code online');
+        expect(result.structuredContent).toMatchObject({ sessions: [expect.objectContaining({ shortId: 'f072e1c5' })] });
+    });
+    it('says a request would be refused when nobody matches, and is read-only', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [] }) }));
+        const result = await makeAgentWhoHandler(client)({});
+        expect(result.content[0].text).toContain('no_recipient');
+        expect(agentWhoToolConfig.annotations.readOnlyHint).toBe(true);
+        expect(whoLine({ ...entry, addresses: [], role: null, channel: { announced: null, online: false }, currentTicket: null })).toContain('no scope');
+    });
+});

package/dist/tools/bulk-writes.js

@@ -15,10 +15,10 @@ const CATEGORY_TO_LEGACY = {
     wont_fix: 'WONT_FIX',
 };
 const TICKET_KEY_ARRAY = z.array(z.string().min(3)).min(1).max(200).optional()
-    .describe('Ticket keys (e.g. ["ACME-1", "ACME-2"]). Capped at 200 per call to keep the per-tenant rate-limit budget reasonable. Give either ticketKeys or query.');
+    .describe('Ticket keys, e.g. ["ACME-1"]; at most 200. Give ticketKeys or query.');
 /** ORB-2054 - the target set can be an OQL query instead of a key list. */
 const QUERY_SOURCE = z.string().min(1).max(8000).optional()
-    .describe('OQL query selecting the tickets instead of ticketKeys (same grammar as orboto_query, caller ACL applies). At most 200 matches per call - narrow it or use POST /projects/{id}/tickets/bulk with `query` for a server-side run.');
+    .describe('OQL selecting the tickets instead of ticketKeys (orboto_query grammar, your ACL); at most 200 matches.');
 const QUERY_PROJECT = z.string().optional()
     .describe('Project key that scopes `query` (prepended as project = KEY).');
 /** Matches per call the MCP loop will process; above that the server-side bulk route is the right tool. */

package/dist/tools/capacity-guide.js

@@ -0,0 +1,46 @@
+/** ORB-2272, ORB-2274 - the build capacity recipes for an MCP agent, served by orboto_help topic "capacity". */
+export function capacityGuideText() {
+    return [
+        'Build capacity (shared build hosts, CI runners, game build hosts) runs through orboto_api_call; the metrics label each call as orboto_capacity_list, _claim, _renew, _release, _windows or _stats.',
+        'Build capacity (shared build hosts, CI runners, game build hosts) runs through orboto_api_call; the metrics label each call as orboto_capacity_list, _claim, _renew, _release, _windows, _plan or _seed.',
+        '',
+        'Who holds a resource, its queue and windows:',
+        '  orboto_api_call {"method":"GET","path":"/capacity/resources/build-host:runner-1"}',
+        'Every resource with used slots and queue length:',
+        '  orboto_api_call {"method":"GET","path":"/capacity/resources"}',
+        'Your own active claims:',
+        '  orboto_api_call {"method":"GET","path":"/capacity/claims","query":{"mine":true,"active":true}}',
+        '',
+        'Claim before a heavy run (granted when a slot is free, else queued by priority release > develop > pr > batch, then arrival):',
+        '  orboto_api_call {"method":"POST","path":"/capacity/claims","body":{"resource":"build-host:runner-1","reason":"0.212.0 release build","expectedMinutes":45,"priority":"release"}}',
+        '  The claim is held by this agent session. A queued answer names its position, what it waits for (waitingFor) and the holders.',
+        'Renew while the run lasts, and while queued, before the deadline in the claim:',
+        '  orboto_api_call {"method":"POST","path":"/capacity/claims/<claimId>/renew","body":{}}',
+        'Poll a queued claim until state is granted:',
+        '  orboto_api_call {"method":"GET","path":"/capacity/claims/<claimId>"}',
+        'Release when the run ends (idempotent):',
+        '  orboto_api_call {"method":"POST","path":"/capacity/claims/<claimId>/release","body":{"reason":"build done"}}',
+        'Reserved windows of every resource:',
+        '  orboto_api_call {"method":"GET","path":"/capacity/windows"}',
+        'Wait, hold, expirations, yields, overrun alerts and queue depth per resource over the last 24 hours and 7 days (needs admin:agents:read):',
+        '  orboto_api_call {"method":"GET","path":"/capacity/metrics","query":{"resource":"build-host:runner-1"}}',
+        '',
+        'Plan: the earliest slot for a duration, around windows, holders, the queue and booked reservations (409 when nothing fits within 14 days):',
+        '  orboto_api_call {"method":"GET","path":"/capacity/resources/build-host:runner-1/plan","query":{"minutes":45,"notBefore":"2026-10-01T18:00:00+02:00"}}',
+        'Book it: a reservation claim of this session that nothing else can take, granted at startsAt with a wake message; renew it within graceMinutes (default 15) of the grant or it expires:',
+        '  orboto_api_call {"method":"POST","path":"/capacity/resources/build-host:runner-1/plan","body":{"minutes":45,"book":true,"reason":"0.212.0 release window","priority":"release"}}',
+        'Use it: renew once right after the grant (that sets usedAt), then while the run lasts, and release it when the run ends; from a shell, orboto capacity wait <claimId> --hold -- <command...> does all three.',
+        'An integrator books the release window this way (CLI: orboto capacity plan <resource> --for 45m --book --priority release) before pushing the release commit;',
+        'a release reservation takes no slot: it keeps every lower priority off the resource during its run while the release runs use every slot, so plan a develop run with "priority":"develop".',
+        '',
+        'Seed the nightly Unity build window on the instance that runs the Unity host (admin:capacity:write, idempotent; optional resource, default unity:build, and timezone, default the workspace zone):',
+        '  orboto_api_call {"method":"POST","path":"/capacity/seeds/nightly-unity","body":{}}',
+        '',
+        'Automatic release: orboto_session_check (full toolset only: ?toolset=full or ORBOTO_MCP_TOOLSET=full) releases the granted claims of this session on may_stop,',
+        'except claims a live `orboto capacity claim --hold` or `orboto capacity wait --hold` process keeps (marker ~/.orboto/capacity-holds/<claimId>.json), and every claim with sessionEnd: true.',
+        'A curated agent has no orboto_session_check: it releases with orboto_api_call POST /capacity/claims/<claimId>/release, and the SessionEnd hook (`orboto session-check --session-end`) ends the rest.',
+        'The MCP server releases every claim when a probe or an HTTP client ends its session; a stdio stdin end (reconnect, harness restart) releases only the granted claims no live hold keeps.',
+        'A claim not renewed by its deadline expires and the next claim in line gets the slot. A yieldRequest on your claim asks you to release early; nothing is ever killed.',
+        'Resources and windows are administered with admin:capacity:write on the Capacity page or through the same REST routes.',
+    ].join('\n');
+}

package/dist/tools/capacity-session.js

@@ -0,0 +1,109 @@
+/** ORB-2272 - releases the capacity claims an agent session holds, on a may_stop completion check (granted only) and at session end (every active claim). */
+import { readFileSync, statSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { PROBE_SESSION_ENV } from '../probe-session.js';
+const PAGE = 100;
+const MAX_PAGES = 10;
+async function activeClaims(client, sessionId, instanceToken) {
+    const rows = [];
+    let cursor = null;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const q = new URLSearchParams({ holderKind: 'agent-session', holderId: sessionId, active: 'true', limit: String(PAGE) });
+        if (cursor)
+            q.set('cursor', cursor);
+        const res = await client.get(`/capacity/claims?${q}`, instanceToken ? { instanceToken } : {});
+        rows.push(...res.items);
+        cursor = res.nextCursor;
+        if (!cursor)
+            break;
+    }
+    return rows;
+}
+/** The marker a live `orboto capacity claim --hold` process (ORB-2270) writes per claim: `~/.orboto/capacity-holds/<claimId>.json`, `{"pid":N}`, 0600 in a 0700 directory. */
+export function capacityHoldPath(claimId) {
+    return join(process.env.HOME || process.env.USERPROFILE || homedir(), '.orboto', 'capacity-holds', `${claimId}.json`);
+}
+/** True while the marker names a live pid; a marker of a dead pid is removed, one another user owns is ignored. */
+export function capacityHoldAlive(claimId) {
+    const path = capacityHoldPath(claimId);
+    let pid = 0;
+    try {
+        const info = statSync(path);
+        if (typeof process.getuid === 'function' && info.uid !== process.getuid())
+            return false;
+        pid = Number(JSON.parse(readFileSync(path, 'utf8')).pid);
+    }
+    catch {
+        return false;
+    }
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EPERM')
+            return true;
+    }
+    try {
+        unlinkSync(path);
+    }
+    catch { /* already gone */ }
+    return false;
+}
+/** `scope: 'granted'` on may_stop, `'all'` at session end; one failed release never stops the others. */
+export async function releaseSessionCapacity(client, sessionId, scope, reason, instanceToken, opts = {}) {
+    const claims = (await activeClaims(client, sessionId, instanceToken))
+        .filter((c) => scope === 'all' || c.state === 'granted')
+        .filter((c) => scope === 'all' || !opts.respectHolds || !capacityHoldAlive(c.id));
+    const out = { released: [], failed: [] };
+    for (const claim of claims) {
+        try {
+            await client.post(`/capacity/claims/${claim.id}/release`, { reason }, instanceToken ? { instanceToken } : {});
+            out.released.push({ id: claim.id, resource: claim.resourceName, was: claim.state === 'queued' ? 'queued' : 'granted' });
+        }
+        catch (err) {
+            out.failed.push({ id: claim.id, resource: claim.resourceName, error: err instanceof Error ? err.message.slice(0, 200) : String(err) });
+        }
+    }
+    return out;
+}
+export const SESSION_END_RELEASE_DEADLINE_MS = 10_000;
+/** Resolves the session behind the instance token, then releases every active claim (`all`) or only the granted claims no live hold keeps (`turn`); never throws and never outlasts the deadline. */
+export async function releaseCapacityAtSessionEnd(client, instanceToken, deadlineMs = SESSION_END_RELEASE_DEADLINE_MS, mode = 'all') {
+    const release = (async () => {
+        const { sessionId } = await client.get('/agents/session/unfinished', { instanceToken });
+        return mode === 'all'
+            ? releaseSessionCapacity(client, sessionId, 'all', 'agent session ended', instanceToken)
+            : releaseSessionCapacity(client, sessionId, 'granted', 'MCP connection ended while no process held the claim', instanceToken, { respectHolds: true });
+    })().catch(() => null);
+    let timer;
+    const deadline = new Promise((resolve) => { timer = setTimeout(() => resolve(null), deadlineMs); timer.unref?.(); });
+    try {
+        return await Promise.race([release, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Stdio: a probe's stdin end ends its session and releases every claim; a real session outlives its stdin (reconnect, harness restart), so only granted claims no live hold keeps go, and the SessionEnd hook ends the rest. The runner is memoised so a probe exit awaits the same release. */
+export function releaseCapacityOnStdinEnd(stdin, client, instanceToken, env = process.env) {
+    let running = null;
+    const mode = env[PROBE_SESSION_ENV] === '1' ? 'all' : 'turn';
+    const run = () => (running ??= releaseCapacityAtSessionEnd(client, instanceToken, SESSION_END_RELEASE_DEADLINE_MS, mode));
+    stdin.once('end', () => { void run(); });
+    stdin.once('close', () => { void run(); });
+    return run;
+}
+export function describeCapacityRelease(res) {
+    if (!res.released.length && !res.failed.length)
+        return '';
+    const done = res.released.map((c) => `${c.resource} (${c.was}, ${c.id})`).join(', ');
+    const failed = res.failed.map((c) => `${c.resource} (${c.id}): ${c.error}`).join('; ');
+    return [
+        done ? `Released capacity claims of this session: ${done}.` : '',
+        failed ? `Release failed, release by hand with orboto_api_call POST /capacity/claims/<id>/release: ${failed}.` : '',
+    ].filter(Boolean).join(' ');
+}

package/dist/tools/capacity-session.test.js

@@ -0,0 +1,179 @@
+/** ORB-2272 - the MCP releases the capacity claims of its agent session: granted ones on may_stop, every one with sessionEnd and at session end. */
+import { EventEmitter } from 'node:events';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError } from '../orboto-client.js';
+import { makeSessionCheckHandler } from './session-check.js';
+import { mcpProcessInstance } from './shared.js';
+import { releaseCapacityAtSessionEnd, releaseCapacityOnStdinEnd, releaseSessionCapacity } from './capacity-session.js';
+const GRANTED = { id: 'c-granted', resourceName: 'build-host:runner-1', state: 'granted' };
+const QUEUED = { id: 'c-queued', resourceName: 'unity:mac-1', state: 'queued' };
+function fakeClient(verdict, opts = {}) {
+    const released = [];
+    const listed = [];
+    const get = vi.fn(async (path) => {
+        if (path === '/agents/session/unfinished')
+            return { sessionId: 'sess-uuid', verdict, reason: verdict, text: `verdict ${verdict}` };
+        if (path.startsWith('/capacity/claims?')) {
+            listed.push(path);
+            const cursor = new URLSearchParams(path.split('?')[1]).get('cursor');
+            return cursor ? { items: [QUEUED], nextCursor: null } : { items: [GRANTED], nextCursor: 'page-2' };
+        }
+        throw new Error(`unexpected GET ${path}`);
+    });
+    const post = vi.fn(async (path, body, o) => {
+        const id = path.split('/')[3];
+        if (id === opts.failRelease)
+            throw new OrbotoApiError(403, '{"error":"claim_not_yours"}', path);
+        released.push({ id, reason: body.reason, token: o?.instanceToken });
+        return { id, state: 'released' };
+    });
+    return { client: { get, post }, released, listed, get };
+}
+describe('ORB-2272 - orboto_session_check releases the session\'s capacity claims', () => {
+    it('may_stop releases the granted claim and keeps the queued one', async () => {
+        const api = fakeClient('may_stop');
+        const res = await makeSessionCheckHandler(api.client)({ action: 'check' }, { sessionId: 'http-1' });
+        expect(api.released.map((r) => r.id)).toEqual(['c-granted']);
+        expect(api.released[0]).toMatchObject({ reason: 'completion check: may_stop', token: 'mcp-http-1' });
+        expect(api.listed[0]).toContain('holderKind=agent-session');
+        expect(api.listed[0]).toContain('holderId=sess-uuid');
+        expect(api.listed[0]).toContain('active=true');
+        expect(res.content[0].text).toContain('build-host:runner-1 (granted, c-granted)');
+        expect(res.structuredContent).toMatchObject({ verdict: 'may_stop', capacityReleased: [{ id: 'c-granted', was: 'granted' }], capacityReleaseFailed: [] });
+    });
+    it('continue releases nothing and does not even list claims', async () => {
+        const api = fakeClient('continue');
+        const res = await makeSessionCheckHandler(api.client)({});
+        expect(api.released).toEqual([]);
+        expect(api.listed).toEqual([]);
+        expect(res.structuredContent).not.toHaveProperty('capacityReleased');
+    });
+    it('sessionEnd releases the granted and the queued claim, whatever the verdict', async () => {
+        const api = fakeClient('continue');
+        const res = await makeSessionCheckHandler(api.client)({ action: 'check', sessionEnd: true });
+        expect(api.released.map((r) => [r.id, r.reason])).toEqual([['c-granted', 'agent session ended'], ['c-queued', 'agent session ended']]);
+        expect(res.structuredContent).toMatchObject({ capacityReleased: [{ id: 'c-granted', was: 'granted' }, { id: 'c-queued', was: 'queued' }] });
+    });
+    it('a refused release is reported and never stops the others', async () => {
+        const api = fakeClient('may_stop', { failRelease: 'c-granted' });
+        const res = await releaseSessionCapacity(api.client, 'sess-uuid', 'all', 'agent session ended');
+        expect(res.released.map((r) => r.id)).toEqual(['c-queued']);
+        expect(res.failed).toEqual([expect.objectContaining({ id: 'c-granted', error: expect.stringContaining('403') })]);
+    });
+});
+describe('ORB-2272 - the MCP session end releases every claim of the session', () => {
+    it('resolves the session behind the instance token and releases granted and queued claims', async () => {
+        const api = fakeClient('continue');
+        const res = await releaseCapacityAtSessionEnd(api.client, 'mcp-proc');
+        expect(api.get).toHaveBeenCalledWith('/agents/session/unfinished', { instanceToken: 'mcp-proc' });
+        expect(res?.released.map((r) => r.id)).toEqual(['c-granted', 'c-queued']);
+        expect(api.released.every((r) => r.token === 'mcp-proc')).toBe(true);
+    });
+    it('gives up at the deadline instead of holding the session end open', async () => {
+        const get = vi.fn(() => new Promise(() => undefined));
+        const started = Date.now();
+        expect(await releaseCapacityAtSessionEnd({ get, post: vi.fn() }, 'mcp-proc', 20)).toBeNull();
+        expect(Date.now() - started).toBeLessThan(1_000);
+    });
+    it('never throws when the session is unknown', async () => {
+        const get = vi.fn().mockRejectedValue(new OrbotoApiError(404, 'instance_session_not_found', '/agents/session/unfinished'));
+        expect(await releaseCapacityAtSessionEnd({ get, post: vi.fn() }, 'mcp-proc')).toBeNull();
+    });
+    it('stdio: stdin end releases once, and the probe exit awaits the same run', async () => {
+        const api = fakeClient('continue');
+        const stdin = new EventEmitter();
+        const run = releaseCapacityOnStdinEnd(stdin, api.client, 'mcp-proc', { ORBOTO_PROBE_SESSION: '1' });
+        stdin.emit('end');
+        stdin.emit('close');
+        await run();
+        expect(api.released.map((r) => r.id)).toEqual(['c-granted', 'c-queued']);
+        expect(api.get.mock.calls.filter(([p]) => p === '/agents/session/unfinished')).toHaveLength(1);
+    });
+});
+describe('ORB-2272 - a live CLI --hold marker keeps its claim on the stdio process token', () => {
+    let home;
+    const realHome = process.env.HOME;
+    const marker = (id) => join(home, '.orboto', 'capacity-holds', `${id}.json`);
+    const writeMarker = (id, pid) => {
+        mkdirSync(join(home, '.orboto', 'capacity-holds'), { recursive: true, mode: 0o700 });
+        writeFileSync(marker(id), JSON.stringify({ pid }), { mode: 0o600 });
+    };
+    const deadPid = () => {
+        let pid = 2_000_000;
+        for (; pid < 2_100_000; pid += 1) {
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                return pid;
+            }
+        }
+        return pid;
+    };
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), 'orboto-holds-'));
+        process.env.HOME = home;
+    });
+    afterEach(() => {
+        process.env.HOME = realHome;
+        rmSync(home, { recursive: true, force: true });
+    });
+    it('may_stop on the process token keeps a claim whose marker names a live pid, and the marker', async () => {
+        writeMarker('c-granted', process.pid);
+        const api = fakeClient('may_stop');
+        await makeSessionCheckHandler(api.client)({ action: 'check' });
+        expect(api.released).toEqual([]);
+        expect(existsSync(marker('c-granted'))).toBe(true);
+    });
+    it('a marker with a dead pid is removed and the claim is released', async () => {
+        writeMarker('c-granted', deadPid());
+        const api = fakeClient('may_stop');
+        await makeSessionCheckHandler(api.client)({ action: 'check' });
+        expect(api.released.map((r) => r.id)).toEqual(['c-granted']);
+        expect(existsSync(marker('c-granted'))).toBe(false);
+    });
+    it('sessionEnd releases the held claim regardless and leaves the marker to its process', async () => {
+        writeMarker('c-granted', process.pid);
+        const api = fakeClient('continue');
+        await makeSessionCheckHandler(api.client)({ action: 'check', sessionEnd: true });
+        expect(api.released.map((r) => r.id)).toEqual(['c-granted', 'c-queued']);
+    });
+    it('an HTTP session token ignores the marker (it never shares a checkout)', async () => {
+        writeMarker('c-granted', process.pid);
+        const api = fakeClient('may_stop');
+        await makeSessionCheckHandler(api.client)({ action: 'check' }, { sessionId: 'http-1' });
+        expect(api.released.map((r) => r.id)).toEqual(['c-granted']);
+    });
+    it('a marker another process wrote without a pid does not keep the claim', async () => {
+        mkdirSync(join(home, '.orboto', 'capacity-holds'), { recursive: true });
+        writeFileSync(marker('c-granted'), '{"pid":"x"}');
+        const api = fakeClient('may_stop');
+        await makeSessionCheckHandler(api.client)({ action: 'check' });
+        expect(api.released.map((r) => r.id)).toEqual(['c-granted']);
+    });
+    it('a real stdio stdin end releases only the unheld granted claim, a probe end every claim', async () => {
+        const heldGranted = { ...GRANTED, id: 'c-held' };
+        writeMarker('c-held', process.pid);
+        const listing = (client) => {
+            client.get.mockImplementation(async (path) => {
+                if (path === '/agents/session/unfinished')
+                    return { sessionId: 'sess-uuid', verdict: 'continue', reason: 'continue', text: 'x' };
+                return { items: [heldGranted, GRANTED, QUEUED], nextCursor: null };
+            });
+        };
+        const real = fakeClient('continue');
+        listing(real);
+        const stdin = new EventEmitter();
+        await (() => { const run = releaseCapacityOnStdinEnd(stdin, real.client, mcpProcessInstance(), {}); stdin.emit('end'); return run(); })();
+        expect(real.released.map((r) => r.id)).toEqual(['c-granted']);
+        expect(existsSync(marker('c-held'))).toBe(true);
+        const probe = fakeClient('continue');
+        listing(probe);
+        const probeStdin = new EventEmitter();
+        await (() => { const run = releaseCapacityOnStdinEnd(probeStdin, probe.client, mcpProcessInstance(), { ORBOTO_PROBE_SESSION: '1' }); probeStdin.emit('end'); return run(); })();
+        expect(probe.released.map((r) => r.id)).toEqual(['c-held', 'c-granted', 'c-queued']);
+    });
+});