@orboto/mcp 0.232.0 → 0.232.1

package/dist/checkout-repository.js

@@ -0,0 +1,66 @@
+/** ORB-2684 - the origin remote of the MCP server's checkout as a heartbeat's `repository`, parsed like the Go CLI and the wrapper (checkout-project.mjs). */
+import { spawnSync } from 'node:child_process';
+const SCP_REMOTE = /^(?:[^@/\s]+@)?[^:/\s]+:(.+)$/;
+/** Owner and name of an https, ssh or scp-like remote on any host; null when it names none. */
+export function parseRemote(raw) {
+    const remote = raw.trim();
+    let path;
+    if (remote.includes('://')) {
+        try {
+            path = new URL(remote).pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        const match = SCP_REMOTE.exec(remote);
+        if (!match)
+            return null;
+        path = match[1];
+    }
+    let parts = path.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+    if (parts[0] === 'v3' && parts.length === 4)
+        parts = [parts[1], parts[3]];
+    const git = parts.indexOf('_git');
+    if (git > 0 && git + 1 < parts.length)
+        parts = [parts[0], parts[git + 1]];
+    if (parts[0] === 'scm' && parts.length > 2)
+        parts = parts.slice(1);
+    if (parts.length < 2)
+        return null;
+    const name = parts[parts.length - 1].replace(/\.git$/, '');
+    const owner = parts.slice(0, -1).join('/').replace(/^~/, '');
+    return owner && name ? { owner, name } : null;
+}
+/** The host of a remote, empty when it names none. */
+export function remoteHost(raw) {
+    const remote = raw.trim();
+    if (remote.includes('://')) {
+        try {
+            return new URL(remote).hostname;
+        }
+        catch {
+            return '';
+        }
+    }
+    const match = SCP_REMOTE.exec(remote);
+    if (!match)
+        return '';
+    const head = remote.slice(0, remote.length - match[1].length - 1);
+    return head.slice(head.lastIndexOf('@') + 1);
+}
+/** The origin remote's URL of the checkout at `cwd`; empty outside a repository or without one. */
+function originUrl(cwd) {
+    const res = spawnSync('git', ['-C', cwd, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', timeout: 2000 });
+    return res.status === 0 ? String(res.stdout ?? '').trim() : '';
+}
+/** The checkout's repository for a heartbeat, or null when the working directory has no parsable origin remote. */
+export function checkoutRepository(cwd = process.cwd(), read = originUrl) {
+    const remote = read(cwd);
+    const parsed = remote ? parseRemote(remote) : null;
+    if (!parsed)
+        return null;
+    const host = remoteHost(remote).toLowerCase();
+    return { owner: parsed.owner.slice(0, 255), name: parsed.name.slice(0, 255), ...(host ? { host: host.slice(0, 255) } : {}) };
+}

package/dist/checkout-repository.test.js

@@ -0,0 +1,43 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** ORB-2684 - the checkout repository a heartbeat names parses remotes the way the CLI and the wrapper do. */
+import { describe, expect, it } from 'vitest';
+import { checkoutRepository, parseRemote, remoteHost } from './checkout-repository.js';
+import { inboxViewLine } from './tools/agent-messages.js';
+const REMOTES = [
+    'https://github.com/orboto/orboto.git',
+    'git@github.com:orboto/orboto.git',
+    'ssh://git@10.0.0.5:2222/acme/acme.shop.git',
+    'https://dev.azure.com/org/project/_git/repo',
+    'https://bitbucket.example.org/scm/team/repo.git',
+    'https://gitlab.example.org/group/sub/repo',
+    'not a remote',
+    '',
+];
+describe('ORB-2684 - checkout repository', () => {
+    it('parses every remote form exactly like the wrapper', async () => {
+        const wrapperPath = '../../../skills/orboto/scripts/checkout-project.mjs';
+        const wrapper = await import(__rewriteRelativeImportExtension(wrapperPath));
+        for (const remote of REMOTES) {
+            expect(parseRemote(remote), remote).toEqual(wrapper.parseRemote(remote));
+            expect(remoteHost(remote), remote).toBe(wrapper.remoteHost(remote));
+        }
+    });
+    it('names owner, name and the lower-cased host; nothing without a parsable origin', () => {
+        expect(checkoutRepository('/x', () => 'ssh://git@Forgejo.Example:2222/SilentFuture/game-repo.git')).toEqual({ owner: 'SilentFuture', name: 'game-repo', host: 'forgejo.example' });
+        expect(checkoutRepository('/x', () => '')).toBeNull();
+        expect(checkoutRepository('/x', () => 'just-a-name')).toBeNull();
+    });
+    it('the inbox view line names the checkout projects and the hint, and stays silent for a declared view', () => {
+        expect(inboxViewLine({ view: 'checkout', projectKeys: ['MSC'], hint: 'Declare one.' })).toBe('Inbox view: checkout - this session lists mail addressed to it, broadcasts and mail of MSC (its checkout). Declare one.');
+        expect(inboxViewLine({ view: 'addressed_only', projectKeys: [], hint: 'Declare one.' })).toBe('Inbox view: addressed_only - this session lists mail addressed to it and broadcasts. Declare one.');
+        expect(inboxViewLine({ view: 'declared', projectKeys: ['ORB'], hint: null })).toBeNull();
+        expect(inboxViewLine(undefined)).toBeNull();
+    });
+});

package/dist/index.js

@@ -80,9 +80,11 @@ async function main() {
                 void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
             const { readClaudeContext, channelClientInfo } = await import('./claude-context.js');
             const { presenceRefusal } = await import('./tools/shared.js');
+            const { checkoutRepository } = await import('./checkout-repository.js');
+            const repository = checkoutRepository();
             let refusalLogged = false;
             const beat = () => {
-                preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd()), undefined, channelStart ?? undefined) }, { instanceToken })
+                preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd()), undefined, channelStart ?? undefined), ...(repository ? { repository } : {}) }, { instanceToken })
                     .then((res) => {
                     refusalLogged = false;
                     const joined = adoptJoined(res);
@@ -110,7 +112,8 @@ async function main() {
         else {
             const { toolServerHeartbeat } = await import('./claude-context.js');
             const { beatAsToolServer } = await import('./tools/shared.js');
-            beatAsToolServer(preflightClient, toolServerHeartbeat())
+            const { checkoutRepository } = await import('./checkout-repository.js');
+            beatAsToolServer(preflightClient, toolServerHeartbeat(), checkoutRepository())
                 .catch((err) => { console.error(`[orboto-mcp] heartbeat failed: ${err.message}`); });
         }
         return;

package/dist/manifest-size.test.js

@@ -65,6 +65,10 @@ afterEach(() => { vi.restoreAllMocks(); });
  * ORB-2579 added the four rule proposal tools to the full tier after
  * tightening repeated parameter descriptions (doc ids, bulk selectors,
  * work-session leases, primer facts) by 3.0k (full = 169,607).
+ * ORB-2684 gave the scope input of `orboto_session_start` and
+ * `orboto_agent_heartbeat` the `account` boolean (+58) inside the ceiling:
+ * both titles and the session_start summary shrank to pay for it
+ * (full = 171,194).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/tools/agent-coordination.js

@@ -8,13 +8,13 @@ import { AGENT_WAKE_LABELS, AgentInventoryKindSchema, AgentSessionWakeSchema, }
 import { AgentPresenceRowSchema } from './agent-presence-row.js';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken, presenceRefusal } from './shared.js';
-import { AgentSessionRoleSchema, AgentSessionScopeSchema } from './agent-session-scope.js';
+import { AgentSessionRoleSchema, AgentSessionScopeInputSchema, AgentSessionScopeSchema } from './agent-session-scope.js';
 export const agentHeartbeatToolConfig = {
-    title: 'Agent heartbeat (Multi-Agent Coordination)',
-    description: 'Register or refresh this agent\'s presence with status detail. A live connection already counts as online (an open MCP event stream, `orboto messages --follow`, the agent WebSocket) - the heartbeat adds status: idle (default) | working (+workingOnTicketId) | blocked, capabilities (free-form strings for operator filters) and clientInfo.name (the runtime), and is the only presence path for turn-based clients without a standing connection. Rows older than 90 s count as offline; persist the returned sessionToken and send it on later heartbeats. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility (ORB-2136); an empty object clears it. `startedBy`: starter session id, same account.',
+    title: 'Agent heartbeat',
+    description: 'Register or refresh this agent\'s presence with status detail. A live connection already counts as online (an open MCP event stream, `orboto messages --follow`, the agent WebSocket) - the heartbeat adds status: idle (default) | working (+workingOnTicketId) | blocked, capabilities (free-form strings for operator filters) and clientInfo.name (the runtime), and is the only presence path for turn-based clients without a standing connection. Rows older than 90 s count as offline; persist the returned sessionToken and send it on later heartbeats. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility (ORB-2136); an empty object clears it; `account: true` = account view. `startedBy`: starter session id, same account.',
     inputSchema: z.object({
         sessionToken: z.string().nullable().optional(),
-        scope: AgentSessionScopeSchema.optional(),
+        scope: AgentSessionScopeInputSchema.optional(),
         status: z.enum(['idle', 'working', 'blocked']).optional(),
         workingOnTicketId: z.string().uuid().nullable().optional(),
         capabilities: z.array(z.string()).max(200).optional(),
@@ -123,7 +123,7 @@ function presenceLine(s) {
     const work = s.workingOnTicket ? ` · working on [${s.workingOnTicket.projectKey ?? '?'}] ${s.workingOnTicket.key ?? s.workingOnTicket.id} (${s.workingOnTicket.title})` : '';
     const owner = s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self');
     const declared = s.scope?.projectKeys ?? [];
-    const scope = s.scope?.role || declared.length ? `; scope: ${s.scope?.role ?? 'no role'}${declared.length ? ` on ${declared.join(', ')}` : ''}` : '';
+    const scope = s.scope?.role || declared.length ? `; scope: ${s.scope?.role ?? 'no role'}${declared.length ? ` on ${declared.join(', ')}` : ''}${s.scope?.account ? ' (account view)' : ''}` : '';
     const keys = s.projects.map((p) => p.key);
     const projects = keys.length === 0 ? '' : keys.length <= 8 ? `; projects: ${keys.join(', ')}` : `; member of ${keys.length} projects`;
     const connections = s.connections.length ? `; connections: ${[...new Set(s.connections.map((c) => c.type))].join(', ')}` : '';

package/dist/tools/agent-messages.js

@@ -22,6 +22,13 @@ export function repeatMarks(m) {
     ].filter(Boolean);
     return marks.length ? ` [${marks.join(', ')}]` : '';
 }
+/** ORB-2684 - the line a session without declared keys reads under its inbox; nothing for a declared or explicit view. */
+export function inboxViewLine(inbox) {
+    if (!inbox?.hint)
+        return null;
+    const holds = inbox.view === 'checkout' && inbox.projectKeys.length ? `mail addressed to it, broadcasts and mail of ${inbox.projectKeys.join(', ')} (its checkout)` : 'mail addressed to it and broadcasts';
+    return `Inbox view: ${inbox.view} - this session lists ${holds}. ${inbox.hint}`;
+}
 /** ORB-2548 - the compact page an MCP inbox read returns by default, sized so it fits the 4,000-character budget. */
 export const COMPACT_PAGE_LIMIT = 4;
 const UNREGISTERED_INBOX_HINT = 'Not registered: only account mail is listed. Register with orboto_session_start to see the mail addressed to your session.';
@@ -143,7 +150,7 @@ export function makeAgentMessagesHandler(client) {
             q.set('includeOwn', 'true');
         else if (args.direction !== 'sent')
             q.set('excludeRef', instanceToken);
-        const { messages, sessionId, counts, nextCursor } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
+        const { messages, sessionId, counts, nextCursor, inbox } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
         const header = (m) => `${m.own ? `[sent] ${sentState(m)} ` : ''}[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''}${repeatMarks(m)} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})`;
         const lines = messages.length === 0
             ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
@@ -166,6 +173,9 @@ export function makeAgentMessagesHandler(client) {
             lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
         else
             lines.push(UNREGISTERED_INBOX_HINT);
+        const view = inboxViewLine(inbox);
+        if (view)
+            lines.push(view);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
@@ -180,6 +190,7 @@ export function makeAgentMessagesHandler(client) {
                 dismissed: dismissedCount,
                 closed: closedCount,
                 nextCursor: nextCursor ?? null,
+                ...(inbox ? { inbox } : {}),
             },
         };
     };

package/dist/tools/agent-session-scope.js

@@ -6,3 +6,5 @@ export const AgentSessionScopeSchema = z.object({
     ticketKeys: z.array(z.string()).max(200).optional(),
     role: AgentSessionRoleSchema.optional(),
 });
+/** ORB-2684 - the declarable scope: `account` is the explicit account view of an integrator or a coordinator. */
+export const AgentSessionScopeInputSchema = AgentSessionScopeSchema.extend({ account: z.boolean().optional() });

package/dist/tools/agent-wakes.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
 import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
 export const agentWakesToolConfig = {
     title: 'Wake ledger',
-    description: 'The wake ledger: who woke this account\'s sessions and at what cost. It names the visibility rule that delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
+    description: 'The wake ledger: who woke this account\'s sessions and at what cost. It names the visibility rule that delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view | checkout_project | account_scope), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender.',
     inputSchema: z.object({
         stats: z.boolean().default(false).describe('Precision per session and per sender instead of rows.'),
         hours: z.number().int().min(1).max(720).optional().describe('Stats window, default 24.'),

package/dist/tools/session-start.js

@@ -11,18 +11,19 @@
 import { z } from 'zod';
 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 { AgentSessionScopeInputSchema } 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, supervisorScopePending } from '../project-scope.js';
+import { checkoutRepository } from '../checkout-repository.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. '
+    title: 'Load the rules + re-orient',
+    description: 'THE canonical way to LOAD the binding workspace rules you must follow. 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). `previous` (adopt | end) answers a second-start refusal (ORB-2553); it comes only when the scope overlaps another live session of the account in this checkout (the keys in errorParams.overlap) - a scope that shares no project or ticket with it runs beside it (ORB-2639). '
         + '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({
@@ -32,7 +33,7 @@ export const sessionStartToolConfig = {
         rulesOnly: z.boolean().optional(),
         agentKind: z.string().min(1).max(32).optional(),
         modelTier: z.string().min(1).max(32).optional(),
-        scope: AgentSessionScopeSchema.optional(),
+        scope: AgentSessionScopeInputSchema.optional(),
         previous: z.enum(['adopt', 'end']).optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -238,6 +239,8 @@ export function makeSessionStartHandler(client, opts = {}) {
             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 } : {}),
             ...(r.takeovers?.length ? { takeovers: r.takeovers } : {}),
+            checkoutProjectKeys: Array.isArray(r.checkoutProjectKeys) ? r.checkoutProjectKeys : [],
+            ...(r.inbox ? { inbox: r.inbox } : {}),
         } : null);
         let refusal = null;
         let alsoOverlapping = '';
@@ -249,10 +252,12 @@ export function makeSessionStartHandler(client, opts = {}) {
             return null;
         };
         const host = localSessionHost(extra);
-        const fallbackScope = input.scope === undefined && !supervisorScopePending() ? envProjectScope() : null;
+        const pending = supervisorScopePending();
+        const fallbackScope = input.scope === undefined && !pending ? envProjectScope() : null;
+        const repository = pending || !host ? null : checkoutRepository();
         const startBody = {
             start: true, ...(input.previous ? { previous: input.previous } : {}), ...(input.scope !== undefined ? { scope: input.scope } : {}),
-            ...(fallbackScope ? { fallbackScope } : {}), ...(host ? { clientInfo: { host } } : {}),
+            ...(fallbackScope ? { fallbackScope } : {}), ...(host ? { clientInfo: { host } } : {}), ...(repository ? { repository } : {}),
         };
         const beat = (body) => client.post('/v1/agent/heartbeat', body, { instanceToken }).then(toRegistration);
         let exitedLine = null;
@@ -273,6 +278,16 @@ export function makeSessionStartHandler(client, opts = {}) {
                 refusal = declared.refusal;
             registration = toRegistration(declared) ?? (declared?.refusal ? null : registration);
         }
+        let inferredFrom = null;
+        const inferred = input.scope === undefined && !fallbackScope && registration && !registration.scope && registration.checkoutProjectKeys.length === 1 ? registration.checkoutProjectKeys[0] : null;
+        if (inferred) {
+            const declared = await beat({ start: true, scope: { role: 'worker', projectKeys: [inferred] }, scopeDefault: true, ...(repository ? { repository } : {}) }).catch(refused);
+            if (declared?.scope) {
+                registration = declared;
+                rememberDeclaredScope(instanceToken, declared.scope);
+                inferredFrom = `inferred from the checkout's origin remote ${repository ? `${repository.owner}/${repository.name}` : ''}`.trim();
+            }
+        }
         const [me, rules, assigned, timer, inboxRaw, knowledge, owners, projectFacts] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
@@ -378,12 +393,14 @@ export function makeSessionStartHandler(client, opts = {}) {
         const scopeText = registration?.scope
             ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
             : registration
-                ? 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it'
+                ? `no scope declared - ${registration.inbox?.hint ?? 'this session gets only mail addressed to it, broadcasts and mail of its checkout\'s project'} With MCP: pass scope: { role, projectKeys }`
                 : 'registration failed - only account mail is listed; retry orboto_session_start or check mcp:use';
         if (refusal)
             lines.push(`ref ${instanceToken}. Not registered: ${refusal}`, `With MCP: pass scope: { role, projectKeys }; another live session in this repository whose scope overlaps runs beside this one once the scope shares none of its keys, or pass previous: "adopt" or "end" to replace ${overlappingTarget(alsoOverlapping)}.`);
         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 (inferredFrom)
+            lines.push(`Scope ${inferredFrom}; pass scope: { role, projectKeys } to declare another.`);
         if (exitedLine)
             lines.push(exitedLine);
         else if (registration?.takeovers?.length)

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

@@ -18,8 +18,10 @@ 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';
+const checkout = vi.hoisted(() => ({ repository: null }));
+vi.mock('../checkout-repository.js', () => ({ checkoutRepository: () => checkout.repository }));
 /** 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', ''); });
+beforeEach(() => { vi.restoreAllMocks(); vi.stubEnv('ORBOTO_PROJECT_KEY', ''); vi.stubEnv('ORBOTO_SESSION_ROLE', ''); checkout.repository = null; });
 afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
 function stubByPath(map) {
     const calls = [];
@@ -672,6 +674,35 @@ describe('ORB-2136 - session scope and ref', () => {
         await makeSessionStartHandler(client)({ scope: { role: 'worker', projectKeys: ['orb'] } }, { sessionId: 'keep1' });
         expect(rememberedScope('mcp-keep1')).toEqual({ role: 'worker', projectKeys: ['ORB'] });
     });
+    it('ORB-2684 - a stdio start sends the checkout repository; one project it maps to is declared as the worker scope and printed, none leaves the hint', async () => {
+        checkout.repository = { owner: 'SilentFuture', name: 'game-repo', host: 'git.example.org' };
+        const beats = [];
+        let mapped = ['MSC'];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            const sent = init?.body ? JSON.parse(init.body) : undefined;
+            if (u.pathname === '/v1/agent/heartbeat')
+                beats.push(sent);
+            const body = u.pathname === '/v1/agent/heartbeat'
+                ? { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: sent?.scope ?? null, checkoutProjectKeys: mapped,
+                    inbox: { view: mapped.length ? 'checkout' : 'addressed_only', projectKeys: mapped, hint: 'This session declared no scope, so it gets only mail addressed to it.' } }
+                : u.pathname === '/agent-instructions' ? { instructions: 'rules here', rulesHash: 'fixture' } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const declared = (await makeSessionStartHandler(client)({})).content[0].text;
+        expect(beats).toEqual([
+            { start: true, clientInfo: { host: hostname().trim().toLowerCase() }, repository: checkout.repository },
+            { start: true, scope: { role: 'worker', projectKeys: ['MSC'] }, scopeDefault: true, repository: checkout.repository },
+        ]);
+        expect(declared).toContain('role worker; projects MSC');
+        expect(declared).toContain("Scope inferred from the checkout's origin remote SilentFuture/game-repo");
+        beats.length = 0;
+        mapped = [];
+        const unmapped = (await makeSessionStartHandler(client)({ forceRules: true })).content[0].text;
+        expect(beats).toHaveLength(1);
+        expect(unmapped).toContain('no scope declared - This session declared no scope, so it gets only mail addressed to it.');
+        expect(unmapped).not.toContain('inferred from');
+    });
     it('ORB-2465 - a stdio session reports its host on the heartbeat; an HTTP connection reports none', async () => {
         const seen = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
@@ -744,7 +775,7 @@ describe('ORB-2347 - an unregistered caller is told it sees account mail only',
             '/agent-instructions': { instructions: 'rules', rulesHash: 'h2' },
         });
         const registered = (await makeSessionStartHandler(client)({ forceRules: true })).content[0];
-        expect(registered.text).toContain('lists every account-addressed message');
+        expect(registered.text).toContain('no scope declared - this session gets only mail addressed to it');
         expect(registered.text).not.toContain('not registered');
     });
 });

package/dist/tools/shared.js

@@ -137,8 +137,8 @@ export function adoptJoined(res) {
     return MCP_PROCESS_INSTANCE === token ? token : null;
 }
 /** ORB-2641 - the one heartbeat of a stdio server without a channel: it says so, and joins the session of its process when the answer names one. */
-export async function beatAsToolServer(client, clientInfo) {
-    const res = await client.post('/v1/agent/heartbeat', { clientInfo }, { instanceToken: MCP_PROCESS_INSTANCE });
+export async function beatAsToolServer(client, clientInfo, repository) {
+    const res = await client.post('/v1/agent/heartbeat', { clientInfo, ...(repository ? { repository } : {}) }, { instanceToken: MCP_PROCESS_INSTANCE });
     return adoptJoined(res);
 }
 /** ORB-2465 - the machine a stdio proxy runs on, lower-cased, as `agent-broadcast live --host` matches it; an HTTP connection (per-connection session id) runs on the server, so it reports none. */

package/package.json

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