@orboto/mcp 0.226.2 → 0.228.1

package/dist/tools/rule-proposals.test.js

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeRuleProposalAcceptHandler, makeRuleProposalRejectHandler, makeRuleProposeHandler, makeRuleProposalsHandler } from './rule-proposals.js';
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET', body: typeof init?.body === 'string' ? JSON.parse(init.body) : undefined });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        const status = r.status ?? 200;
+        return { ok: status < 400, status, statusText: 'x', json: async () => r.json, text: async () => JSON.stringify(r.json) };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const ROW = {
+    id: '11111111-1111-1111-1111-111111111111', scope: 'project', projectKey: 'ORB', title: 'Run the gates one by one', status: 'pending',
+    duplicates: [{ kind: 'rule', id: '22222222-2222-2222-2222-222222222222', title: 'Gates run separately', exact: false }],
+    proposedByName: 'Claude Agent', decisionReason: null, canDecide: false,
+};
+describe('rule proposal MCP tools (ORB-2579)', () => {
+    it('propose posts the proposal with the workspace default and names the text matches', async () => {
+        const calls = stub([{ status: 201, json: ROW }]);
+        const res = await makeRuleProposeHandler(client)({ title: ROW.title, body: 'Rule: one gate per call.', projectKey: 'ORB', scope: 'project', reason: 'a chained call ran one gate' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: 'https://orboto.example.com/agent-instructions/proposals' });
+        expect(calls[0].body).toEqual({ title: ROW.title, body: 'Rule: one gate per call.', projectKey: 'ORB', scope: 'project', reason: 'a chained call ran one gate' });
+        const text = res.content[0].text;
+        expect(text).toContain('pending review by a person with rule rights');
+        expect(text).toContain('text match: rule "Gates run separately"');
+        expect(text).not.toMatch(/%/);
+        const calls2 = stub([{ status: 201, json: { ...ROW, scope: 'workspace', projectKey: null, duplicates: [] } }]);
+        await makeRuleProposeHandler(client)({ title: 'x', body: 'y' });
+        expect(calls2[0].body).toEqual({ title: 'x', body: 'y', scope: 'workspace' });
+    });
+    it('propose turns the hard-cap refusal into a blocked result', async () => {
+        stub([{ status: 422, json: { error: 'too long', errorKey: 'errors.agent_content.oversize', sizeWarning: { chars: 900, limit: 800, hint: 'shorten it' } } }]);
+        const res = await makeRuleProposeHandler(client)({ title: 'x', body: 'y'.repeat(900) });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain('Rule proposal blocked');
+    });
+    it('list sends status, mine and cursor and marks what the caller can decide', async () => {
+        const calls = stub([{ json: { items: [{ ...ROW, canDecide: true }], nextCursor: 'abc' } }]);
+        const res = await makeRuleProposalsHandler(client)({ status: 'all', mine: true, cursor: 'c1' });
+        expect(calls[0].url).toBe('https://orboto.example.com/agent-instructions/proposals?status=all&mine=true&cursor=c1');
+        const text = res.content[0].text;
+        expect(text).toContain('[pending] Run the gates one by one (project ORB');
+        expect(text).toContain('[you can decide]');
+        expect(text).toContain('More: cursor abc');
+    });
+    it('list defaults to the pending queue and says when it is empty', async () => {
+        const calls = stub([{ json: { items: [], nextCursor: null } }]);
+        const res = await makeRuleProposalsHandler(client)();
+        expect(calls[0].url).toBe('https://orboto.example.com/agent-instructions/proposals?status=pending');
+        expect(res.content[0].text).toBe('No rule proposals.');
+    });
+    it('list forwards the scope, project, customer and limit filters', async () => {
+        const calls = stub([{ json: { items: [], nextCursor: null } }]);
+        await makeRuleProposalsHandler(client)({ scope: 'project', projectId: '44444444-4444-4444-8444-444444444444', customerId: '55555555-5555-4555-8555-555555555555', limit: 10 });
+        expect(calls[0].url).toBe('https://orboto.example.com/agent-instructions/proposals?status=pending&scope=project&projectId=44444444-4444-4444-8444-444444444444&customerId=55555555-5555-4555-8555-555555555555&limit=10');
+    });
+    it('accept posts the edits and names the new block', async () => {
+        const calls = stub([{ json: { proposal: { ...ROW, status: 'accepted', acceptedEdited: true }, block: { id: 'b1' }, proposerNotified: true } }]);
+        const res = await makeRuleProposalAcceptHandler(client)({ proposalId: ROW.id, title: 'Short', mustRead: true, note: 'tightened' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/agent-instructions/proposals/${ROW.id}/accept`, body: { title: 'Short', mustRead: true, note: 'tightened' } });
+        expect(res.content[0].text).toBe(`Accepted rule proposal "${ROW.title}" as rule block b1 (edited); the proposer got the decision as agent mail.`);
+    });
+    it('accept surfaces the person-only refusal and the hard-cap block', async () => {
+        stub([{ status: 403, json: { error: 'A person with rule rights decides on a rule proposal', errorKey: 'errors.agent_rules.review_needs_person' } }]);
+        await expect(makeRuleProposalAcceptHandler(client)({ proposalId: ROW.id })).rejects.toThrow(/403/);
+        stub([{ status: 422, json: { error: 'too long', sizeWarning: { chars: 900, limit: 800, hint: 'shorten it' } } }]);
+        const blocked = await makeRuleProposalAcceptHandler(client)({ proposalId: ROW.id, body: 'x'.repeat(900) });
+        expect(blocked.isError).toBe(true);
+    });
+    it('reject posts the reason', async () => {
+        const calls = stub([{ json: { proposal: { ...ROW, status: 'rejected', decisionReason: 'covered' }, block: null, proposerNotified: false } }]);
+        const res = await makeRuleProposalRejectHandler(client)({ proposalId: ROW.id, reason: 'covered' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/agent-instructions/proposals/${ROW.id}/reject`, body: { reason: 'covered' } });
+        expect(res.content[0].text).toBe(`Rejected rule proposal "${ROW.title}"; no agent mail was sent.`);
+    });
+});

package/dist/tools/semantic-degraded-wrapper.test.js

@@ -57,7 +57,7 @@ it('search, search-docs, ask-docs and check-similar print the degraded line on s
             child.on('close', (code) => code === 0 ? ok({ out, err }) : no(new Error(`Wrapper exit ${code}: ${err}`)));
             child.stdin.end('');
         });
-        for (const args of [['search', 'frobnicator'], ['search-docs', 'frobnicator'], ['ask-docs', 'how to restart'], ['check-similar', 'ORB', 'Frobnicator jams']]) {
+        for (const args of [['search', 'frobnicator'], ['search-docs', 'frobnicator'], ['ask-docs', 'how to restart'], ['check-similar', 'ORB', 'Frobnicator jams'], ['ticket', 'check-similar', 'ORB', 'Frobnicator jams']]) {
             const { out, err } = await run(args);
             expect(err, args.join(' ')).toContain(LINE);
             expect(out, args.join(' ')).not.toContain(LINE);

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) => {
@@ -189,7 +190,7 @@ describe('orboto_session_start - rules-hash ack (ORB-1607, ORB-2576)', () => {
     });
 });
 describe('orboto_session_start - knowledge layers and project facts (ORB-2575)', () => {
-    const FACTS_TEXT = '## Where knowledge lives\n- Rules: binding behaviour.\n\n## Project facts\n### ORB (project id proj-1): 1 of 3 facts\n- tech_stack/stack: Go and Postgres\n2 more: `orboto primer ORB`';
+    const FACTS_TEXT = '## Where knowledge lives\n- Rules: binding behaviour.\n\n## Project facts\n### ORB: 1 of 3 facts\n- tech_stack/stack: Go and Postgres\n2 more: `orboto primer ORB`';
     const facts = (text) => ({
         source: 'session', unknown: [], text,
         projects: [{ projectKey: 'ORB', projectId: 'proj-1', total: 3, facts: [{ category: 'tech_stack', key: 'stack', value: 'Go and Postgres', observed: false }] }],
@@ -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 },

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.226.2",
+  "version": "0.228.1",
   "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",