@orboto/mcp 0.201.0 → 0.202.0

package/dist/claude-context.js

@@ -41,6 +41,7 @@ export function readClaudeContext(dir, now = Date.now(), root = claudeContextDir
             ...(typeof parsed.contextWindowSize === 'number' && Number.isFinite(parsed.contextWindowSize)
                 ? { contextWindowSize: Math.max(0, Math.round(parsed.contextWindowSize)) }
                 : {}),
+            ...(typeof parsed.sessionId === 'string' && parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
         });
     }
     return fresh.length === 1 ? fresh[0] : null;

package/dist/claude-context.test.js

@@ -6,7 +6,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { readClaudeContext } from './claude-context.js';
+import { claudeContextDir, readClaudeContext } from './claude-context.js';
 let root;
 beforeEach(() => {
     root = mkdtempSync(path.join(tmpdir(), 'orboto-ctx-'));
@@ -36,3 +36,8 @@ describe('ORB-2149 - claude statusline context reports', () => {
         expect(readClaudeContext('/work/repo', Date.now(), path.join(root, 'missing'))).toBeNull();
     });
 });
+describe('ORB-2149 - the report directory', () => {
+    it('lives under the orboto state directory of the user', () => {
+        expect(claudeContextDir().endsWith(path.join('.orboto', 'claude-context'))).toBe(true);
+    });
+});

package/dist/connect-script.js

@@ -8,7 +8,7 @@ export const CONNECT_SCRIPT_HEADING = 'If you are an AI agent helping a person s
 export const CONNECT_SCRIPT_STEPS = [
     'Work one step per message: say in one sentence what the step does and why, run it, show the result, and only then move on.',
     'Run every step you can run yourself - `orboto connect --yes` checks Node and Claude Code, writes the `orboto` server entry for this directory and prints the exact start command with the standing arguments.',
-    'Hand the person only the steps that need a human: the browser login, quitting and restarting the session with that command, confirming the servers from `.mcp.json` and the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels.',
+    'Hand the person only the steps that need a human: the browser login, the two `/plugin` commands that install the orboto plugin (a CLI cannot type into a running session), quitting and restarting the session with that command, confirming the servers from `.mcp.json` and, in the development form, the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels and lists the plugin.',
     'Give every command the person runs verbatim in its own code block, never paraphrased and never merged into prose.',
     'Verify before you continue: `orboto whoami` for the identity, `orboto mcp status` for the entry of this directory, `orboto connect --verify` for the channel.',
     'Never paste a reference page into the chat - link it and keep the message to the step you are on.',

package/dist/inbox-channel.js

@@ -1,3 +1,5 @@
+import { RESTART_REQUESTED_NOTICE, writeRestartRequest } from './session-restart.js';
+export { RESTART_REQUESTED_NOTICE };
 export const CHANNEL_METHOD = 'notifications/claude/channel';
 export const CHANNEL_CAPABILITY = 'claude/channel';
 export const DEFAULT_DIGEST_MINUTES = 15;
@@ -171,8 +173,24 @@ export class InboxChannel {
         if (!content)
             return;
         this.stats.notices += 1;
+        if (notice === RESTART_REQUESTED_NOTICE) {
+            await this.emit({ content: this.takeRestartRequest(content), meta: { kind: 'notice', notice } });
+            return;
+        }
         await this.emit({ content, meta: { kind: 'notice', notice } });
     }
+    /** ORB-2181 - an admin restart notice becomes the supervisor's request file. */
+    takeRestartRequest(reason) {
+        try {
+            const result = (this.opts.writeRestart ?? writeRestartRequest)(process.cwd(), { reason, source: 'channel' });
+            return result.written
+                ? `restart requested by the operator (${reason}) - the orboto claude supervisor restarts this session as soon as this turn ends and resumes the same conversation; Claude Code asks for the development-channel confirmation in that terminal.`
+                : `restart requested by the operator (${reason}), but nothing could be written: ${result.detail}. Run \`orboto claude --restart --reason "${reason}"\` in this session's terminal instead.`;
+        }
+        catch (err) {
+            return `restart requested by the operator (${reason}), but the request file could not be written: ${err.message}`;
+        }
+    }
     async flushDigest() {
         if (this.batch.length === 0)
             return;
@@ -279,6 +297,20 @@ export class InboxChannel {
         }
     }
 }
+/** ORB-2175 - the notice name the stale-CLI finding is delivered under. */
+export const CLI_OUTDATED_NOTICE = 'cli_outdated';
+/**
+ * ORB-2175 - `orboto mcp serve` hands its version-skew finding to the proxy in
+ * ORBOTO_MCP_CLI_OUTDATED; the channel says it once on connect, because a CLI
+ * older than the instance leaves this session under a second identity.
+ */
+export function cliOutdatedNotice(raw) {
+    const finding = (raw ?? '').trim();
+    if (!finding)
+        return '';
+    return `${finding}. Until then this checkout runs under two instance tokens, so this session is woken by its own edits. `
+        + 'Fix it yourself: run `orboto self-update`, then `orboto claude --restart --reason "CLI updated"` - the supervisor restarts this session on the same conversation as soon as your turn ends.';
+}
 /** ORB-2140 - the digest window from the environment; NaN or negative fall back to the default. */
 export function digestMinutesFromEnv(raw) {
     if (raw === undefined || raw.trim() === '')

package/dist/inbox-channel.test.js

@@ -5,7 +5,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, InboxChannel, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
 import { buildOrbotoMcpServer } from './server.js';
 function mockMcp() {
     const notification = vi.fn().mockResolvedValue(undefined);
@@ -115,6 +115,47 @@ describe('InboxChannel', () => {
         expect(String(fetchFn.mock.calls[1][0])).toContain('since=m1');
         channel.close();
     });
+    it('ORB-2181 - a restart_requested notice becomes the supervisor request file and says so', async () => {
+        const { mcp, notification } = mockMcp();
+        const writeRestart = vi.fn().mockReturnValue({ written: true, sessionId: 'sess-1', path: '/home/a/.orboto/claude/sess-1/restart.json', detail: 'ok' });
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0, writeRestart });
+        await channel.deliverNotice(RESTART_REQUESTED_NOTICE, 'the CLI was updated');
+        expect(writeRestart).toHaveBeenCalledWith(process.cwd(), { reason: 'the CLI was updated', source: 'channel' });
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.meta).toEqual({ kind: 'notice', notice: 'restart_requested' });
+        expect(sent.params.content).toContain('resumes the same conversation');
+        expect(channel.stats).toMatchObject({ notices: 1, delivered: 0 });
+        channel.close();
+    });
+    it('ORB-2181 - a restart_requested notice that cannot be written says why instead of pretending', async () => {
+        const { mcp, notification } = mockMcp();
+        const writeRestart = vi.fn().mockReturnValue({ written: false, sessionId: null, path: null, detail: 'no status line report' });
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0, writeRestart });
+        await channel.deliverNotice(RESTART_REQUESTED_NOTICE, 'rotated key');
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.content).toContain('no status line report');
+        channel.close();
+    });
+    it('ORB-2175 - the stale-CLI finding from `mcp serve` becomes one cli_outdated notice on connect', async () => {
+        expect(cliOutdatedNotice(undefined)).toBe('');
+        expect(cliOutdatedNotice('   ')).toBe('');
+        const finding = 'CLI 0.200.0 is older than the instance 0.201.0 - run `orboto self-update` and restart this session';
+        const content = cliOutdatedNotice(finding);
+        expect(content).toContain(finding);
+        expect(content).toContain('two instance tokens');
+        const { mcp, notification } = mockMcp();
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        await channel.deliverNotice(CLI_OUTDATED_NOTICE, content);
+        expect(notification).toHaveBeenCalledTimes(1);
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.meta).toEqual({ kind: 'notice', notice: 'cli_outdated' });
+        expect(sent.params.content).toBe(content);
+        expect(channel.stats).toMatchObject({ notices: 1, delivered: 0 });
+        channel.close();
+    });
 });
 describe('server capability', () => {
     async function connect(channel) {

package/dist/index.js

@@ -59,11 +59,14 @@ async function main() {
         const stdio = new StdioServerTransport();
         await server.connect(stdio);
         if (channel) {
-            const { InboxChannel, digestMinutesFromEnv } = await import('./inbox-channel.js');
+            const { InboxChannel, digestMinutesFromEnv, cliOutdatedNotice, CLI_OUTDATED_NOTICE } = await import('./inbox-channel.js');
             const { mcpProcessInstance } = await import('./tools/shared.js');
             const instanceToken = mcpProcessInstance();
             const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
             inbox.start();
+            const outdated = cliOutdatedNotice(process.env.ORBOTO_MCP_CLI_OUTDATED);
+            if (outdated)
+                void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
             const { readClaudeContext } = await import('./claude-context.js');
             const beat = () => {
                 const context = readClaudeContext(process.cwd());

package/dist/session-restart.js

@@ -0,0 +1,59 @@
+/**
+ * ORB-2181 - the proxy half of the session restart: whatever asked for it -
+ * the agent through `orboto_session_restart` or the operator through the
+ * `restart_requested` channel notice - ends as the same request file the
+ * `orboto claude` supervisor consumes. No socket, no signal, no network
+ * listener: one 0600 file in a 0700 directory of the caller's own home.
+ */
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { claudeContextDir, readClaudeContext } from './claude-context.js';
+export const RESTART_REQUESTED_NOTICE = 'restart_requested';
+export function claudeSessionsDir() {
+    return path.join(homedir(), '.orboto', 'claude');
+}
+/** Keeps a session id from escaping the session root. */
+export function safeSessionName(id) {
+    const cleaned = [...id].filter((c) => /[A-Za-z0-9_-]/.test(c)).join('').slice(0, 80);
+    return cleaned || 'session';
+}
+export function writeRestartRequest(dir, input, roots = {}) {
+    const now = roots.now ?? Date.now();
+    const root = roots.root ?? claudeSessionsDir();
+    const report = readClaudeContext(dir, now, roots.contextRoot ?? claudeContextDir());
+    const sessionId = report?.sessionId;
+    if (!sessionId) {
+        return {
+            written: false,
+            sessionId: null,
+            path: null,
+            detail: 'no status line report identifies a Claude Code session in this directory - wire the reporter up with `orboto mcp install --statusline`, then ask again',
+        };
+    }
+    const target = path.join(root, safeSessionName(sessionId));
+    const body = JSON.stringify({
+        reason: input.reason,
+        source: input.source,
+        requestedAt: new Date(now).toISOString(),
+        ...(input.requestedBy ? { requestedBy: input.requestedBy } : {}),
+        idleTimeoutSeconds: input.idleTimeoutSeconds ?? 0,
+    });
+    const staging = path.join(target, `.restart-${process.pid}.tmp`);
+    const file = path.join(target, 'restart.json');
+    mkdirSync(target, { recursive: true, mode: 0o700 });
+    writeFileSync(staging, body, { mode: 0o600 });
+    try {
+        renameSync(staging, file);
+    }
+    catch (err) {
+        rmSync(staging, { force: true });
+        throw err;
+    }
+    return {
+        written: true,
+        sessionId,
+        path: file,
+        detail: 'the supervisor restarts this session as soon as no turn is running; it never interrupts one',
+    };
+}

package/dist/session-restart.test.js

@@ -0,0 +1,56 @@
+/**
+ * ORB-2181 - the proxy writes one 0600 request file into a 0700 directory
+ * named after the Claude Code session, and refuses when no status line
+ * report names one.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { claudeSessionsDir, safeSessionName, writeRestartRequest } from './session-restart.js';
+let contexts;
+let sessions;
+const NOW = Date.parse('2026-09-19T10:00:00Z');
+beforeEach(() => {
+    contexts = mkdtempSync(path.join(tmpdir(), 'orboto-ctx-'));
+    sessions = mkdtempSync(path.join(tmpdir(), 'orboto-sessions-'));
+});
+afterEach(() => {
+    rmSync(contexts, { recursive: true, force: true });
+    rmSync(sessions, { recursive: true, force: true });
+});
+function report(body, root = contexts) {
+    mkdirSync(root, { recursive: true });
+    writeFileSync(path.join(root, 'report.json'), JSON.stringify(body));
+}
+describe('ORB-2181 - the restart request file', () => {
+    it('writes the request under the reported session id, owner only', () => {
+        report({ cwd: '/work/repo', sessionId: 'sess-7f3a2b1c', contextTokens: 10, updatedAt: new Date(NOW).toISOString() });
+        const result = writeRestartRequestHere('/work/repo', 'the CLI was updated');
+        expect(result.written).toBe(true);
+        expect(result.sessionId).toBe('sess-7f3a2b1c');
+        const file = path.join(sessions, 'sess-7f3a2b1c', 'restart.json');
+        expect(result.path).toBe(file);
+        expect(statSync(file).mode & 0o777).toBe(0o600);
+        expect(statSync(path.dirname(file)).mode & 0o777).toBe(0o700);
+        expect(JSON.parse(readFileSync(file, 'utf8'))).toMatchObject({ reason: 'the CLI was updated', source: 'mcp' });
+    });
+    it('refuses without a status line report and names the fix', () => {
+        const result = writeRestartRequestHere('/work/repo', 'rotated key');
+        expect(result.written).toBe(false);
+        expect(result.sessionId).toBeNull();
+        expect(result.detail).toContain('orboto mcp install --statusline');
+    });
+    it('keeps a session id from escaping the session root', () => {
+        expect(safeSessionName('../../etc/passwd')).toBe('etcpasswd');
+        expect(safeSessionName('!!!')).toBe('session');
+    });
+});
+function writeRestartRequestHere(dir, reason) {
+    return writeRestartRequest(dir, { reason, source: 'mcp' }, { now: NOW, root: sessions, contextRoot: contexts });
+}
+describe('ORB-2181 - the session root', () => {
+    it('lives under the orboto state directory of the user', () => {
+        expect(claudeSessionsDir().endsWith(path.join('.orboto', 'claude'))).toBe(true);
+    });
+});

package/dist/tools/agent-presence-schema.js

@@ -45,6 +45,10 @@ export const AgentInventoryEntrySchema = z.object({
         wrongWakeContextTokens: z.number().int(),
         backlogSeen: z.number().int(),
     }),
+    /** ORB-2181 - a restart was requested for this session and its supervisor has not reconnected yet. */
+    restartPending: z.boolean(),
+    /** ORB-2181 - the reason the requester gave; null when nothing is pending. */
+    restartReason: z.string().nullable(),
     lastSeenAt: z.string(),
     createdAt: z.string(),
 });

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

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+import { makeAgentWakesHandler } from './agent-wakes.js';
+function clientReturning(body) {
+    const get = vi.fn().mockResolvedValue(body);
+    return { client: { get }, get };
+}
+function textOf(result) {
+    return result.content[0].text;
+}
+describe('orboto_agent_wakes', () => {
+    it('renders the stats with precision, wrong-wake cost and backlog per session and sender', async () => {
+        const { client, get } = clientReturning({
+            hours: 12,
+            sessions: [
+                { label: 'lead (ab12cd34)', wakes: 4, precision: 0.75, medianLatencyMs: 20, topRule: 'addressed', wrongWakeContextTokens: 1200, backlogSeen: 3 },
+                { label: 'worker (ef56ab78)', wakes: 1, precision: null, medianLatencyMs: null, topRule: null, wrongWakeContextTokens: 0, backlogSeen: 0 },
+            ],
+            senders: [],
+        });
+        const result = await makeAgentWakesHandler(client)({ stats: true, hours: 12, sessionId: 'ab12cd34' });
+        expect(get).toHaveBeenCalledWith('/admin/agents/wake-stats?sessionId=ab12cd34&hours=12');
+        const text = textOf(result);
+        expect(text).toContain('Last 12 h - woken sessions:');
+        expect(text).toContain('- lead (ab12cd34): 4 wakes, precision 75%, median 20 ms, top rule addressed, wrong wakes cost 1200 tokens, 3 backlog seen');
+        expect(text).toContain('- worker (ef56ab78): 1 wakes, precision unjudged, median ? ms, top rule -');
+        expect(text).toContain('Senders:\n- (none)');
+    });
+    it('says so when nothing woke anyone', async () => {
+        const { client } = clientReturning({ hours: 24, sessions: [], senders: [] });
+        expect(textOf(await makeAgentWakesHandler(client)({ stats: true }))).toContain('- (no wakes)');
+    });
+    it('lists the ledger rows with latency, context cost and the next cursor', async () => {
+        const { client, get } = clientReturning({
+            rows: [
+                { wokenAt: '2026-01-02T03:04:05Z', subject: 'probe', senderLabel: 'lead (ab12cd34)', rule: 'addressed', transport: 'channel', outcome: 'handled', latencyMs: 18, contextTokens: 900 },
+                { wokenAt: '2026-01-02T03:05:05Z', subject: 'digest', senderLabel: 'worker (ef56ab78)', rule: 'scope_project', transport: 'poll', outcome: 'pending', latencyMs: null, contextTokens: null },
+            ],
+            nextCursor: 'abc',
+        });
+        const text = textOf(await makeAgentWakesHandler(client)({ project: 'ACME', outcome: 'handled', limit: 2, cursor: 'c0' }));
+        expect(get).toHaveBeenCalledWith('/v1/agent/wakes?project=ACME&outcome=handled&limit=2&cursor=c0');
+        expect(text).toContain('- 2026-01-02T03:04:05Z probe - from lead (ab12cd34) via addressed/channel -> handled (18 ms, 900 ctx tokens)');
+        expect(text).toContain('via scope_project/poll -> pending');
+        expect(text).toContain('(next cursor: abc)');
+    });
+    it('reports an empty ledger', async () => {
+        const { client } = clientReturning({ rows: [], nextCursor: null });
+        expect(textOf(await makeAgentWakesHandler(client)({}))).toBe('(no wakes recorded)');
+    });
+});

package/dist/tools/docs.js

@@ -276,7 +276,7 @@ export const createDocToolConfig = {
     inputSchema: z.object({
         spaceId: z.string().min(1).describe('Target doc space - key (e.g. ORB-S1), name, or UUID. Discover via orboto_list_doc_spaces.'),
         title: z.string().min(1).max(255),
-        content: z.string().optional().describe('Markdown body. Pass an empty string or omit for a blank page.'),
+        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Pass an empty string or omit for a blank page. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
         parentDocId: z.string().uuid().nullable().optional().describe('Nest under another doc.'),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional().describe('Defaults to "workspace".'),
         icon: z.string().nullish().describe('Single emoji shown in the tree.'),
@@ -315,7 +315,7 @@ export const updateDocToolConfig = {
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
         title: z.string().min(1).max(255).optional(),
-        content: z.string().optional().describe('Markdown body. Send the full new content; the API replaces, not appends.'),
+        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Send the full new content; the API replaces, not appends. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
         parentDocId: z.string().uuid().nullable().optional(),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional(),
         icon: z.string().nullish(),

package/dist/tools/shared.test.js

@@ -8,7 +8,7 @@
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
-import { resolveProjectByKey, resolveTicketByKey, ticketLine, normalizeName, resolveByName } from './shared.js';
+import { resolveProjectByKey, resolveTicketByKey, ticketLine, normalizeName, resolveByName, mcpProcessInstance, checkoutInstanceToken } from './shared.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
 function sequence(responses) {
@@ -171,3 +171,9 @@ describe('ORB-2171 - the stdio proxy shares the checkout token with the CLI and
         expect(checkoutInstanceToken({}, 'build-host', '/srv/other')).not.toBe('agent-e0b18afc9cec');
     });
 });
+describe('mcpProcessInstance', () => {
+    it('is the checkout token this process derived at start', () => {
+        expect(mcpProcessInstance()).toBe(checkoutInstanceToken());
+        expect(mcpProcessInstance().length).toBeGreaterThan(0);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.201.0",
+  "version": "0.202.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",