@orboto/mcp 0.227.0 → 0.229.0

package/dist/tools/session-start.js

@@ -9,29 +9,31 @@
  * @see ORB-1605, ORB-1607, ORB-1818
  */
 import { z } from 'zod';
-import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken, localSessionHost } from './shared.js';
+import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken, localSessionHost, presenceRefusal, exitedPredecessor } from './shared.js';
+import { machineId, shortHost } from '../session-origin.js';
 import { AgentSessionScopeSchema } from './agent-session-scope.js';
 import { PROCESS_OWNER, PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
 import { channelStartLines } from '../inbox-channel.js';
 import { rememberDeclaredScope } from '../session-scope-memory.js';
-import { declareEnvProjectScope, envProjectScope } from '../project-scope.js';
+import { declareEnvProjectScope, envProjectScope, supervisorScopePending } from '../project-scope.js';
 import { agentHeadText } from '../agent-head.js';
 import { agentContextKey } from '../agent-context.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
     description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it FIRST in a session and AFTER every context compaction. Returns the rules in full (above the full-text bound: one title per rule plus every must-read rule in full, the rest via `rulesOnly: true`); a compact "unchanged" ack only on a repeat inside the same agent context. Also returns your in-progress tickets (LANDED, IDLE = a linked commit but no move for days: finished work never handed to review), your timer and unhealthy git connections. Not orboto_list_agent_instructions - that one edits rule blocks for admins. Registers this session (a heartbeat on its instance row), otherwise read-only. '
-        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text, never truncated. `projectId` adds that project\'s rules. `ticketKey` ("ACME-42") bundles that ticket\'s primer, detail, dependencies, checklists, git health and other agent sessions. `forceRules: true` returns the full text inline even above the bound or after an ack - use it whenever the rules are NOT in your context. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) target rule blocks and per-tier text. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; session.ref is what peers pass as toSessionRef (ORB-2136). '
+        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text, never truncated. `projectId` adds that project\'s rules. `ticketKey` ("ACME-42") bundles that ticket\'s primer, detail, dependencies, checklists, git health and other agent sessions. `forceRules: true` returns the full text inline even above the bound or after an ack - use it whenever the rules are NOT in your context. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) target rule blocks and per-tier text. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; session.ref is what peers pass as toSessionRef (ORB-2136). `previous` (adopt | end) answers a second-start refusal (ORB-2553). '
         + 'Also carries the Knowledge block (ORB-2225: the wiki index of your declared projects and the Operations wiki; ask with orboto_knowledge_ask before a person, file durable facts with orboto_knowledge_add) and the Responsibilities block (ORB-2542: who owns the topics of your projects, orboto_who before agent mail). Right after the rules come Where knowledge lives (ORB-2575: rules bind behaviour, project facts hold fixed decisions, the wiki the long tail; a decision goes to a fact proposal, orboto_primer_fact_add with observed: true) and the Project facts of your declared projects.',
     inputSchema: z.object({
-        projectId: z.string().uuid().optional().describe('Also load this project\'s rules.'),
-        ticketKey: z.string().min(3).optional().describe('Ticket key ("ACME-42") - bundles that ticket\'s full context.'),
-        forceRules: z.boolean().optional().describe('Always return the full rules; set it when you do not hold them.'),
-        rulesOnly: z.boolean().optional().describe('Return ONLY the complete rules text.'),
-        agentKind: z.string().min(1).max(32).optional().describe('coding | orchestrator | reviewer | runner.'),
-        modelTier: z.string().min(1).max(32).optional().describe('frontier | standard | small.'),
+        projectId: z.string().uuid().optional(),
+        ticketKey: z.string().min(3).optional(),
+        forceRules: z.boolean().optional(),
+        rulesOnly: z.boolean().optional(),
+        agentKind: z.string().min(1).max(32).optional(),
+        modelTier: z.string().min(1).max(32).optional(),
         scope: AgentSessionScopeSchema.optional(),
+        previous: z.enum(['adopt', 'end']).optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
@@ -175,6 +177,12 @@ function knowledgeSummary(index, handle) {
     };
 }
 /** ORB-2209 - a declared scope stays with the instance token; the agent declares it once per terminal. */
+/** ORB-2553 - what the start did to the session it ran into. */
+export function takeoverLine(t) {
+    if (t.action === 'ended')
+        return `Ended the previous session ${t.shortId} in this repository${t.releasedTickets.length ? `; its leases on ${t.releasedTickets.join(', ')} are released` : ''}.`;
+    return `Adopted session ${t.shortId}: ${t.movedMessages} unread message(s)${t.movedLeases.length ? ` and the leases on ${t.movedLeases.join(', ')}` : ''} moved here, it is ended.`;
+}
 export function identityLine(registration) {
     const count = registration.reconnects ?? 0;
     const kept = count > 0 ? ` It survived ${count} reconnect(s), the last at ${registration.lastReconnectAt ?? 'an unknown time'}.` : '';
@@ -223,15 +231,34 @@ export function makeSessionStartHandler(client, opts = {}) {
         const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? {
             sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt,
             wake: r.wake, scopeExpired: r.scopeExpired ?? null, scopeContinued: r.scopeContinued ?? null, notes: Array.isArray(r.notes) ? r.notes.filter((n) => typeof n === 'string') : [],
+            ...(r.takeover ? { takeover: r.takeover } : {}),
         } : null);
+        let refusal = null;
+        const refused = (err) => { refusal = presenceRefusal(err)?.message ?? refusal; return null; };
         const host = localSessionHost(extra);
-        let registration = await client.post('/v1/agent/heartbeat', { ...(input.scope !== undefined ? { scope: input.scope } : {}), ...(host ? { clientInfo: { host } } : {}) }, { instanceToken })
-            .then(toRegistration)
-            .catch(() => null);
-        if (input.scope !== undefined && registration)
+        const fallbackScope = input.scope === undefined && !supervisorScopePending() ? envProjectScope() : null;
+        const startBody = {
+            start: true, ...(input.previous ? { previous: input.previous } : {}), ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            ...(fallbackScope ? { fallbackScope } : {}), ...(host ? { clientInfo: { host } } : {}),
+        };
+        const beat = (body) => client.post('/v1/agent/heartbeat', body, { instanceToken }).then(toRegistration);
+        let exitedLine = null;
+        let registration = await beat(startBody).catch(async (err) => {
+            const dead = exitedPredecessor(presenceRefusal(err), { machine: machineId(), host: shortHost() });
+            if (!dead)
+                return refused(err);
+            const again = await beat({ ...startBody, previous: 'end' }).catch(refused);
+            if (again)
+                exitedLine = dead.line;
+            return again;
+        });
+        if ((input.scope !== undefined || fallbackScope) && registration?.scope)
             rememberDeclaredScope(instanceToken, registration.scope);
-        if (input.scope === undefined && registration && !registration.scope && envProjectScope()) {
-            registration = toRegistration(await declareEnvProjectScope(client, instanceToken)) ?? registration;
+        if (fallbackScope && registration && !registration.scope) {
+            const declared = await declareEnvProjectScope(client, instanceToken);
+            if (declared?.refusal)
+                refusal = declared.refusal;
+            registration = toRegistration(declared) ?? (declared?.refusal ? null : registration);
         }
         const [me, rules, assigned, timer, inboxRaw, knowledge, owners, projectFacts] = await Promise.all([
             client.get('/users/me').catch(() => null),
@@ -340,7 +367,14 @@ export function makeSessionStartHandler(client, opts = {}) {
             : registration
                 ? 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it'
                 : 'registration failed - only account mail is listed; retry orboto_session_start or check mcp:use';
-        lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
+        if (refusal)
+            lines.push(`ref ${instanceToken}. Not registered: ${refusal}`, 'With MCP: pass scope: { role, projectKeys } and, for another live session in this repository, previous: "adopt" or "end".');
+        else
+            lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
+        if (exitedLine)
+            lines.push(exitedLine);
+        else if (registration?.takeover)
+            lines.push(takeoverLine(registration.takeover));
         const roleAddresses = registration?.scope?.role ? (registration.scope.projectKeys ?? []).map((k) => `${registration.scope.role}@${k}`) : [];
         if (roleAddresses.length)
             lines.push(`Address form: peers reach this session and every other ${registration.scope.role} of the project with orboto_agent_notify { to: "${roleAddresses[0]}" } (${roleAddresses.join(', ')}); address a role, never a session id copied from a log.`);
@@ -384,6 +418,8 @@ export function makeSessionStartHandler(client, opts = {}) {
                     reconnects: registration?.reconnects ?? 0, reconnectedAt: registration?.lastReconnectAt ?? null,
                     ...(registration?.wake ? { wake: registration.wake } : {}), scopeExpired: registration?.scopeExpired ?? null,
                     scopeContinued: registration?.scopeContinued ?? null,
+                    ...(refusal ? { refused: refusal } : {}),
+                    ...(registration?.takeover ? { takeover: registration.takeover } : {}),
                 },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections

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

@@ -18,8 +18,9 @@ import { makeResponseExpandHandler } from './response-expand.js';
 import { applyResponseBudget, budgetFor, DEFAULT_BUDGET_CHARS } from '../response-budget.js';
 import { hostname, tmpdir } from 'node:os';
 import { localSessionHost } from './shared.js';
-beforeEach(() => { vi.restoreAllMocks(); });
-afterEach(() => { vi.restoreAllMocks(); });
+/** An `orboto claude` or `orboto connect` session exports its checkout project and role; the digest must not inherit them here. */
+beforeEach(() => { vi.restoreAllMocks(); vi.stubEnv('ORBOTO_PROJECT_KEY', ''); vi.stubEnv('ORBOTO_SESSION_ROLE', ''); });
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
 function stubByPath(map) {
     const calls = [];
     vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
@@ -646,7 +647,7 @@ describe('ORB-2136 - session scope and ref', () => {
         const res = await makeSessionStartHandler(client)({ scope: { role: 'integrator', projectKeys: ['orb'] } }, { sessionId: 'abc123' });
         const beat = seen.find((c) => c.path === '/v1/agent/heartbeat');
         expect(beat?.headers['x-orboto-agent-session']).toBe('mcp-abc123');
-        expect(beat?.body).toEqual({ scope: { role: 'integrator', projectKeys: ['orb'] } });
+        expect(beat?.body).toEqual({ start: true, scope: { role: 'integrator', projectKeys: ['orb'] } });
         expect(seen.find((c) => c.path.startsWith('/v1/agent/messages'))?.headers['x-orboto-agent-session']).toBe('mcp-abc123');
         const text = res.content[0].text;
         expect(text).toContain('ref mcp-abc123, instance cbb52195. role integrator; projects ORB');
@@ -682,11 +683,11 @@ describe('ORB-2136 - session scope and ref', () => {
             return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
         });
         await makeSessionStartHandler(client)({});
-        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({ clientInfo: { host: hostname().trim().toLowerCase() } });
+        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({ start: true, clientInfo: { host: hostname().trim().toLowerCase() } });
         expect(localSessionHost({ sessionId: 'http-1' }, 'server')).toBeUndefined();
         expect(localSessionHost(undefined, ' Mac-A ')).toBe('mac-a');
     });
-    it('without a scope the heartbeat body stays empty and the digest says no scope is declared', async () => {
+    it('without a scope the heartbeat body carries only the start and the digest says no scope is declared', async () => {
         const seen = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
             const u = new URL(url.toString());
@@ -697,7 +698,7 @@ describe('ORB-2136 - session scope and ref', () => {
             return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
         });
         const res = await makeSessionStartHandler(client)({}, { sessionId: 'abc123' });
-        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({});
+        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({ start: true });
         expect(res.content[0].text).toContain('no scope declared');
     });
     it('ORB-2148: a stdio proxy with the channel on hands over the exact start commands; other servers stay silent', async () => {

package/dist/tools/shared.js

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { OrbotoApiError } from '../orboto-client.js';
 /** ORB-2543 - the line every search-shaped tool prints when the API flags `semanticDegraded`. */
 export const SEMANTIC_DEGRADED_LINE = 'semantic search unavailable, showing full-text results';
@@ -178,6 +179,54 @@ export function applyAgentProfile(params, explicit) {
     if (tier)
         params.set('modelTier', tier);
 }
+export function presenceRefusal(err) {
+    if (!(err instanceof OrbotoApiError) || (err.status !== 409 && err.status !== 422))
+        return null;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(err.body);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.errorKey !== 'errors.agents.scope_required' && parsed.errorKey !== 'errors.agents.session_exists')
+        return null;
+    const notes = Array.isArray(parsed.errorParams?.notes) ? parsed.errorParams.notes.filter((n) => typeof n === 'string') : [];
+    return { key: parsed.errorKey, message: [parsed.error ?? parsed.errorKey, ...notes].join('\n'), params: parsed.errorParams ?? {} };
+}
+/** True while pid belongs to a running process: signal 0 answers ESRCH for none, and an exited zombie on Linux counts as gone. */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        if (err.code === 'ESRCH')
+            return false;
+    }
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return stat[stat.lastIndexOf(')') + 2] !== 'Z';
+    }
+    catch {
+        return true;
+    }
+}
+/** Every identifier both sides name must match, machine id and host alike, so containers of one image or cloned VMs never count as one machine. */
+export function sameMachine(theirMachine, ourMachine, theirHost, ourHost) {
+    const machines = Boolean(theirMachine && ourMachine);
+    const hosts = Boolean(theirHost && ourHost);
+    return (machines || hosts) && (!machines || theirMachine === ourMachine) && (!hosts || theirHost === ourHost);
+}
+/** ORB-2553 - the session a second-start refusal names when it runs on this machine under a pid that no longer runs; null otherwise. */
+export function exitedPredecessor(refusal, local, alive = processAlive) {
+    if (refusal?.key !== 'errors.agents.session_exists')
+        return null;
+    const p = refusal.params;
+    const same = sameMachine(typeof p.machineId === 'string' ? p.machineId : null, local.machine, typeof p.host === 'string' ? p.host : null, local.host);
+    if (typeof p.pid !== 'number' || !Number.isInteger(p.pid) || p.pid <= 1 || !same || typeof p.shortId !== 'string' || alive(p.pid))
+        return null;
+    return { shortId: p.shortId, pid: p.pid, line: `previous session ${p.shortId} (pid ${p.pid}) has exited, ended it` };
+}
 export function sizeBlockResult(err, verb) {
     if (!(err instanceof OrbotoApiError) || err.status !== 422)
         return null;

package/dist/tools/ticket-writes.js

@@ -620,7 +620,7 @@ export const setMilestoneToolConfig = {
     description: 'Move a ticket onto a different milestone (or off all milestones with milestone=null/undefined). Resolves the milestone by key (e.g. "ORB-M3"), name, OR UUID within the ticket\'s project (including closed/archived). If two milestones share a name, pass the key or UUID - an ambiguous name is rejected, not silently guessed.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
-        milestone: z.string().nullable().optional().describe('Milestone key (e.g. "ORB-M3"), name, or UUID. Pass the key/UUID when the name is ambiguous. Pass null to remove from any milestone.'),
+        milestone: z.string().nullable().optional().describe('Milestone key ("ORB-M3"), name or UUID (key when the name is ambiguous); null removes it.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
@@ -719,7 +719,7 @@ export function makeRemoveTicketDependencyHandler(client) {
 }
 export const listTicketDependenciesToolConfig = {
     title: 'List a ticket\'s dependencies',
-    description: 'Show both directions of a ticket\'s dependency graph: `blockedBy` (must finish first) and `blocks` (waiting on this one). ORB-1614: an edge to a ticket you cannot read comes back as an opaque stub (no title/key/status - just whether it is still open); `external` marks another project.',
+    description: 'Both directions of a ticket\'s dependencies: `blockedBy` (finish first) and `blocks` (waiting on it). ORB-1614: an edge to a ticket you cannot read comes back as an opaque stub (no title/key/status - just whether it is still open); `external` marks another project.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
     }).shape,

package/dist/tools/wiki.js

@@ -161,7 +161,7 @@ export const wikiSaveAnswerToolConfig = {
         answer: z.string().min(1).max(50_000),
         title: z.string().max(200).optional().describe('Defaults to the question.'),
         parentDocId: z.string().uuid().optional(),
-        citations: z.array(z.object({ docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'), title: z.string() })).max(50).optional().describe('From orboto_wiki_ask.'),
+        citations: z.array(z.object({ docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'), title: z.string() })).max(50).optional().describe('From orboto_wiki_ask.'),
         replace: z.boolean().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -177,7 +177,7 @@ export const wikiFlagStaleToolConfig = {
     title: 'Flag (or unflag) a wiki page as possibly outdated',
     description: 'Set or clear the "may be outdated" flag on a page. The flag surfaces passively as a pill in the UI; it does not change the content. Pass stale=false to clear. Wraps POST /docs/:id/flag-stale.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         stale: z.boolean().optional().describe('true to flag (default), false to clear.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -189,14 +189,22 @@ export function makeWikiFlagStaleHandler(client) {
         return text(res.staleFlagged ? 'Page flagged as possibly outdated.' : 'Stale flag cleared.', { staleFlagged: res.staleFlagged });
     };
 }
+/** ORB-2611 - the wait or run time of a queued run, and its stall. */
+function queuedNote(r) {
+    if (r.status !== 'queued')
+        return '';
+    const waited = r.startedAt ? (Date.parse(r.startedAt) - Date.parse(r.queuedAt ?? r.createdAt)) / 1000 : 0;
+    const minutes = Math.max(1, Math.round(Math.max(0, (r.ageSeconds ?? 0) - waited) / 60));
+    return ` (${r.startedAt ? 'running' : 'waiting'} ${minutes} min${r.stalled ? ', stalled' : ''})`;
+}
 export const wikiRunsToolConfig = {
     title: 'Wiki ingest runs',
-    description: 'List the ingest runs of a wiki space (status failed shows each error) or retry a failed run.',
+    description: 'List the ingest runs of a wiki space (queued shows the wait and a stall, failed each error) or retry a failed or stalled run.',
     inputSchema: z.object({
         spaceId: z.string().min(1),
         action: z.enum(['list', 'retry']).optional(),
         runId: z.string().uuid().optional(),
-        status: z.enum(['pending_review', 'applied', 'failed', 'skipped']).optional(),
+        status: z.enum(['pending_review', 'applied', 'failed', 'skipped', 'queued']).optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -204,13 +212,13 @@ export function makeWikiRunsHandler(client) {
     return async (input) => {
         if (input.action === 'retry') {
             if (!input.runId)
-                return { isError: true, content: [{ type: 'text', text: 'action retry needs the runId of a failed run (action list, status failed).' }] };
+                return { isError: true, content: [{ type: 'text', text: 'action retry needs the runId of a failed or stalled run (action list, status failed or queued).' }] };
             const res = await client.post(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs/${input.runId}/retry`, {});
             return text(res.queued ? `Run ${res.runId} is queued for the ingest worker again.` : `Run ${res.runId} ran again: ${res.status}${res.error ? ` - ${res.error}` : ''}.`, res);
         }
         const qs = input.status ? `?status=${input.status}` : '';
         const res = await client.get(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs${qs}`);
-        const lines = res.runs.map((r) => `- ${r.id} ${r.status} ${r.sourceKey ?? ''} "${r.sourceTitle}" ${r.createdAt}${r.droppedOps?.length ? ` (ops dropped: ${r.droppedOps.length})` : ''}${r.error ? ` - ${r.error}` : ''}`);
+        const lines = res.runs.map((r) => `- ${r.id} ${r.status}${queuedNote(r)} ${r.sourceKey ?? ''} "${r.sourceTitle}" ${r.createdAt}${r.droppedOps?.length ? ` (ops dropped: ${r.droppedOps.length})` : ''}${r.error ? ` - ${r.error}` : ''}`);
         return text(lines.length ? lines.join('\n') : 'No ingest runs.', res);
     };
 }

package/dist/tools/work-next.js

@@ -27,21 +27,21 @@ export const workNextToolConfig = {
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME") or UUID.'),
         agentTag: z.string().min(1).max(64).optional()
-            .describe('ORB-1772 - preferred routing tag: `agent:<tag>` tickets rank first, foreign `agent:*` last but eligible. Lowercased; often the model or fleet lane name.'),
+            .describe('Routing tag: `agent:<tag>` tickets first, foreign `agent:*` last but eligible.'),
         role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
             .describe('Default `implementation`; reserves only a ticket whose (ticket, role) lease is free.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
-            .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
+            .describe('Lease without renewal, default 900 (15 min).'),
         startTimer: z.boolean().optional()
-            .describe('Defaults to true for `implementation`, false for the attach-only roles.'),
+            .describe('Default true for implementation, false otherwise.'),
         agentSessionToken: z.string().optional()
-            .describe('Stable per-agent-instance token. Omit to use this MCP connection\'s own instance id.'),
+            .describe('Agent instance token; default this connection\'s.'),
         resourceClaims: z.array(z.object(ResourceClaimShape)).max(50).optional()
             .describe('ORB-1610 - claims to acquire with the reservation; a ticket under a conflicting granted write claim is skipped.'),
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set on the WINNING candidate. Default `reject`.'),
         peek: z.boolean().optional()
-            .describe('ORB-1930 - "is there work for me?" without reserving: the same candidate walk, no lease, timer or lane quota; returns `candidate` or the empty reason.'),
+            .describe('Look without reserving (no lease, timer or quota); returns `candidate` or the empty reason.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };

package/dist/tools/work-sessions.js

@@ -49,19 +49,19 @@ export const workStartToolConfig = {
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
         role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
-            .describe('Default implementation; other roles attach without reassignment. Spec prepares build orders; bots need the spec tag.'),
+            .describe('Default implementation; others attach without reassignment; spec needs the bot spec tag.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
-            .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
+            .describe('Lease without renewal, default 900 (15 min).'),
         override: z.boolean().optional().describe("Bypass the spec gate; reason required. Never epics."),
         reason: z.string().trim().min(1).max(2000).optional(),
         takeover: z.boolean().optional()
-            .describe('Displace the current holder of this (ticket, role) lease. Their session is cancelled and their tracked time booked.'),
+            .describe('Displace the lease holder; their session is cancelled, their time booked.'),
         startTimer: z.boolean().optional()
-            .describe('Defaults to true for `implementation`, false for the attach-only roles.'),
+            .describe('Default true for implementation, false otherwise.'),
         agentSessionToken: z.string().optional()
-            .describe('Stable per-agent-instance token. Omit to use this MCP connection\'s own instance id.'),
+            .describe('Agent instance token; default this connection\'s.'),
         resourceClaims: z.array(z.object(ResourceClaimShape)).max(50).optional()
-            .describe('ORB-1610 - resource claims to acquire alongside the lease. Same semantics as orboto_work_session_start\'s resourceClaims.'),
+            .describe('Resource claims with the lease, as in orboto_work_session_start.'),
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`.'),
     }).shape,
@@ -216,19 +216,19 @@ export const workSessionStartToolConfig = {
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
         role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
-            .describe('Default implementation; other roles attach without reassignment. Spec prepares build orders; bots need the spec tag.'),
+            .describe('Default implementation; others attach without reassignment; spec needs the bot spec tag.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
-            .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
+            .describe('Lease without renewal, default 900 (15 min).'),
         override: z.boolean().optional().describe("Bypass the spec gate; reason required. Never epics."),
         reason: z.string().trim().min(1).max(2000).optional(),
         takeover: z.boolean().optional()
-            .describe('Displace the current holder of this (ticket, role) lease. Their session is cancelled and their tracked time booked.'),
+            .describe('Displace the lease holder; their session is cancelled, their time booked.'),
         startTimer: z.boolean().optional()
-            .describe('Defaults to true for `implementation`, false for the attach-only roles.'),
+            .describe('Default true for implementation, false otherwise.'),
         agentSessionToken: z.string().optional()
-            .describe('Stable per-agent-instance token. Omit to use this MCP connection\'s own instance id.'),
+            .describe('Agent instance token; default this connection\'s.'),
         resourceClaims: z.array(z.object(ResourceClaimShape)).max(50).optional()
-            .describe('Atomic resource claims: path values are repo-relative globs, named values are exact ids. Overlapping writes conflict across the workspace; reads never conflict.'),
+            .describe('Atomic claims: path = repo-relative glob, named = exact id; overlapping writes conflict, reads never.'),
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('reject rolls back a new session on claim conflict; queue keeps it with waiting claims, promoted when conflicts clear.'),
     }).shape,
@@ -318,7 +318,7 @@ export const workSessionFinishToolConfig = {
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         outcome: z.enum(['finished', 'cancelled']).optional()
-            .describe('`finished` (default) = the work completed. `cancelled` = abandoned attempt; time is still booked, history stays honest.'),
+            .describe('`finished` (default) or `cancelled` (abandoned; time is still booked).'),
         commitSha: z.string().optional().describe('The commit this session produced, when it produced one.'),
         verification: z.object({
             reviewOfSessionId: z.string().uuid().optional().describe('Exact independent implementation work session this review examined.'),
@@ -460,7 +460,7 @@ export const workSessionClaimsAddToolConfig = {
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         claims: z.array(z.object(ResourceClaimShape)).min(1).max(50)
-            .describe('Claims to add. `kind: "path"` = glob relative to the repo root. `kind: "named"` = exact-match exclusive resource id.'),
+            .describe('Claims to add: path = repo-relative glob, named = exclusive exact id.'),
         onConflict: z.enum(['reject', 'queue']).optional().describe('Default `reject`.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -501,7 +501,7 @@ export function makeWorkSessionClaimsAddHandler(client) {
 }
 export const workSessionClaimsReleaseToolConfig = {
     title: 'Release resource claims from a live work session',
-    description: 'ORB-1610 - drop resource claims (or all) from a session you hold, WITHOUT finishing it or touching the ticket lease/timer. Releasing a granted write claim immediately runs a grant pass, so the earliest queued waiter for that resource is promoted as part of this call - useful once you know you are done touching a subtree but are not done with the ticket. Omit `claims` to release everything the session holds.',
+    description: 'Drop resource claims (or all) from your session without finishing it or touching lease and timer. Releasing a granted write claim immediately runs a grant pass, so the earliest queued waiter for that resource is promoted as part of this call - useful once you know you are done touching a subtree but are not done with the ticket. Omit `claims` to release everything the session holds.',
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         claims: z.array(z.object({ kind: z.enum(['path', 'named']), value: z.string().min(1).max(500) })).optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.227.0",
+  "version": "0.229.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",