@orboto/mcp 0.181.0 → 0.182.0

package/dist/tools/session-start.js

@@ -50,6 +50,8 @@
 import { z } from 'zod';
 import { resolveTicketByKey, applyAgentProfile } from './shared.js';
 import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
+import { loadRequiredRules } from '../required-rules.js';
+import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.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 as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Read-only; no side effects. '
@@ -72,18 +74,6 @@ export const sessionStartToolConfig = {
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
-const GIT_HEALTH_REASON_TEXT = {
-    connection_inactive: 'connection is deactivated',
-    app_installation_suspended: 'GitHub App installation is suspended',
-    oauth_token_expired: 'OAuth token expired with no refresh path',
-    history_backfill_error: 'last history backfill failed',
-    // ORB-1638
-    awaiting_first_event: 'webhook installed but has never delivered an event',
-    outbound_unreachable: 'orboto cannot reach the provider',
-    // ORB-1785 - two derivations now: the provider reporting a failed
-    // delivery, and the probe inferring one from commits that never arrived.
-    delivery_failing: 'webhook deliveries from the provider are not arriving',
-};
 // Cap how many distinct projects we probe for git health - a session's
 // in-progress work is capped at 20 tickets already, so this rarely
 // exceeds a handful, but bound it defensively so a pathological account
@@ -241,10 +231,10 @@ export function makeSessionStartHandler(client) {
         // rules from the API instead, costs one call, and skips the whole rest
         // of the digest. Protected in both halves: it IS the rule text.
         if (input.rulesOnly) {
-            const rules = await client.get(rulesPath).catch(() => ({}));
+            const rules = await loadRequiredRules(client, rulesPath);
             if (rules.rulesHash)
                 lastKnownRulesHash = rules.rulesHash;
-            const text = rules.instructions?.trim() ?? '';
+            const text = rules.instructions ?? '';
             return {
                 _meta: { [PROTECT_TEXT_META]: true },
                 content: [{
@@ -267,7 +257,7 @@ export function makeSessionStartHandler(client) {
         }
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
-            client.get(rulesPath).catch(() => ({})),
+            loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             // ORB-1330 - a re-orientation briefing must only list OPEN work.
             // Filter to in_progress + in_review so DONE tickets can't pose as
             // "what you're working on" at the moment the agent has the least
@@ -282,8 +272,6 @@ export function makeSessionStartHandler(client) {
                 .catch(() => []),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
-        if (rules.rulesHash)
-            lastKnownRulesHash = rules.rulesHash;
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
         // ORB-1605 - git-connection health for every project the caller has
         // open work in right now. Cheap, computed, read-only (see
@@ -326,7 +314,7 @@ export function makeSessionStartHandler(client) {
         //   index  - one line per rule + the hash + a handle; the default.
         //   full   - the text inline (forceRules, or an API too old to send
         //            an index - never leave a caller without its rules).
-        const rulesText = rules.instructions?.trim() ?? '';
+        const rulesText = rules.instructions ?? '';
         const rulesIndex = Array.isArray(rules.rulesIndex)
             ? rules.rulesIndex.map((e) => e?.title).filter((t) => typeof t === 'string' && t.length > 0)
             : [];
@@ -391,7 +379,7 @@ export function makeSessionStartHandler(client) {
         if (bundle)
             lines.push(...bundle.lines);
         lines.push('', 'Re-run this after any context compaction to re-sync.');
-        return {
+        const result = {
             // ORB-1818 - when the full rule text IS the payload, neither half
             // may be cut; see PROTECT_TEXT_META. The index answer carries no
             // rule text and is budgeted like any other response.
@@ -431,5 +419,7 @@ export function makeSessionStartHandler(client) {
                 ...(bundle ? { ticketBundle: bundle.structured } : {}),
             },
         };
+        lastKnownRulesHash = rules.rulesHash;
+        return result;
     };
 }

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

@@ -44,7 +44,7 @@ describe('orboto_session_start (ORB-1093)', () => {
         const calls = stubByPath({
             '/users/me/assigned-tickets': { items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Progress' }] },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev', workspaceLocale: 'en' },
-            '/agent-instructions': { instructions: 'claim -> commit -> close' },
+            '/agent-instructions': { instructions: 'claim -> commit -> close', rulesHash: 'fixture' },
             '/time/timer': { ticketId: 't1', ticketKey: 'ORB-42', startedAt: '2026-06-15T10:00:00Z' },
         });
         const res = await makeSessionStartHandler(client)();
@@ -65,7 +65,7 @@ describe('orboto_session_start (ORB-1093)', () => {
         stubByPath({
             '/users/me/assigned-tickets': { items: [] },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
         });
         const res = await makeSessionStartHandler(client)();
@@ -82,7 +82,7 @@ describe('orboto_session_start (ORB-1093)', () => {
                 items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Review', projectId: 'proj-1' }],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/projects/proj-1/git-health': {
                 connections: [{
@@ -109,7 +109,7 @@ describe('orboto_session_start (ORB-1093)', () => {
                 items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Review', projectId: 'proj-1' }],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/projects/proj-1/git-health': {
                 connections: [{
@@ -298,7 +298,7 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Review', projectId: 'proj-1' }],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/projects/proj-1/git-health': {
                 connections: [{
@@ -332,7 +332,7 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 ],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/v1/agent/presence': [],
         });
@@ -355,7 +355,7 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 ],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
         });
         const res = await makeSessionStartHandler(client)();
@@ -383,7 +383,7 @@ describe('orboto_session_start - a 200 with an unexpected body never kills the d
             '/projects/proj-1/tickets/by-key/42': { id: 'tick-1', projectId: 'proj-1', ticketKey: 'ORB-42', title: 'Bug' },
             '/users/me/assigned-tickets': { items: [] },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
         });
         const res = await makeSessionStartHandler(client)({ ticketKey: 'ORB-42' });
         const text = res.content[0].text;

package/dist/tools/ticket-writes.js

@@ -428,19 +428,20 @@ export function makeDeleteTicketHandler(client) {
     };
 }
 export const commentToolConfig = {
-    title: 'Post a comment on a ticket',
-    description: 'Append a comment. Supports Markdown. `isInternal=true` hides the comment from external/guest users (use for implementation chatter the customer shouldn\'t see).',
+    title: 'Post a comment',
+    description: 'Post Markdown. isInternal=true hides it from guests. Attachment drafts are claimed atomically with the comment; never use public ticket uploads for private comments.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         text: z.string().min(1),
-        isInternal: z.boolean().optional().describe('Default: false (visible to all members + guests).'),
+        isInternal: z.boolean().optional().describe('Default false: guests can read.'),
+        attachmentDraftIds: z.array(z.string().uuid()).max(20).optional().describe('Private /attachment-drafts/tickets/:ticketId uploads only.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCommentHandler(client) {
-    return async ({ ticketKey, text, isInternal }) => {
+    return async ({ ticketKey, text, isInternal, attachmentDraftIds }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
-        const created = await client.post(`/tickets/${ticket.id}/comments`, { content: text, isInternal: isInternal ?? false });
+        const created = await client.post(`/tickets/${ticket.id}/comments`, { content: text, isInternal: isInternal ?? false, ...(attachmentDraftIds ? { attachmentDraftIds } : {}) });
         return {
             content: [{
                     type: 'text',

package/dist/tools/ticket-writes.test.js

@@ -395,6 +395,12 @@ describe('orboto_delete_ticket', () => {
     });
 });
 describe('orboto_comment', () => {
+    it('forwards private upload claims without dropping the internal flag', async () => {
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: { id: 'c1', content: 'private image', isInternal: true, createdAt: 'now' } }]);
+        const ids = ['aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa'];
+        await makeCommentHandler(client)({ ticketKey: 'ACME-1', text: 'private image', isInternal: true, attachmentDraftIds: ids });
+        expect(calls[2].body).toEqual({ content: 'private image', isInternal: true, attachmentDraftIds: ids });
+    });
     it('posts a regular (non-internal) comment by default', async () => {
         const calls = stub([
             { json: PROJ },

package/dist/tools/work-next.js

@@ -0,0 +1,208 @@
+/**
+ * ORB-1613 - `orboto_work_next`, the pull side of low-management dispatch
+ * (Wave 3 of ORB-1602), in its own module since ORB-1930 added the peek.
+ * The shapes it shares with `orboto_work_start` live in
+ * work-sessions-shared.ts.
+ */
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+import { validateNextWorkEnvelope, validateRulesReceipt } from '../required-rules.js';
+import { GIT_HEALTH_REASON_TEXT, ResourceClaimShape } from './work-sessions-shared.js';
+/** ORB-1799 - rendered identically on every exit (reserved, empty, paused):
+ *  an agent that just pulled fresh work is exactly the one about to forget
+ *  the ticket it already finished. Empty array renders nothing. */
+function landedIdleLines(rows) {
+    if (!rows || rows.length === 0)
+        return [];
+    return [
+        '',
+        '## Landed, idle - finished-looking work of yours awaiting the status move',
+        ...rows.map((r) => `- ${r.ticketKey ?? r.ticketId} "${r.title}" - ${r.commitCount} commit(s) linked, no activity for ${r.idleWorkingDays} working day(s) (since ${r.lastActivityAt}).`),
+        'Verify each is actually finished, then move it into the review lane (orboto_work_finish with targetCategory "in_review", or orboto_move_ticket) - do NOT re-implement it.',
+    ];
+}
+export const workNextToolConfig = {
+    title: 'Pull and reserve the next ready ticket (worker-pool dispatch)',
+    description: 'ORB-1613 - the pull side of low-management dispatch, sibling of orboto_work_start on the "I already know which ticket" side. Picks the highest-priority ticket in a project that is READY FOR THE REQUESTED ROLE (default role implementation pulls TODO tickets; `role: "review"` pulls tickets in the in_review status category instead, and NEVER offers a ticket the caller itself implemented - the review lane primitive, ORB-1777), unblocked (every dependency closed), not already leased under the requested role, and not blocked by a conflicting resourceClaim - then reserves it with the EXACT same guarantees as orboto_work_start (atomic lease acquire + the full context bundle: rules ack, primer, ticket, checklists, dependencies, git health, siblings) in the same response. Priority then ticket number, deterministic - never a coin flip on ties. Two workers calling this concurrently never receive the SAME ticket: the underlying reservation is the identical partial-unique-index INSERT orboto_work_start uses, just walked across an ordered candidate list - a collision just advances to the next candidate. Epics are never returned (they are containers, not directly implementable). When nothing is ready, the response is a STRUCTURED result (`reserved: null`) with a `reason` (`none-matching` = no todo tickets at all; `all-blocked` = candidates exist but all have open dependencies; `all-leased` = ready candidates exist but are all currently leased or claim-conflicted; `autonomy_paused` = ORB-1774, this agent identity or the whole workspace has autonomous pulls paused by an operator - idle and wait for an operator/notify wakeup instead of retrying) and, ONLY when derivable from an actual active lease, a `retryAfterSeconds` backoff hint (`earliestFreeAt` null and `retryAfterSeconds` null means no signal exists - never a fabricated constant). This is never an error - a worker pool should back off on the hint rather than poll hot. Prefer this over orboto_work_start whenever the caller does not care WHICH ticket it gets, only that it gets the best available one right now. Every response - reserved, empty or paused - also carries `landedIdle`: YOUR OWN tickets in this project that are still in_progress with a linked commit and no activity for days (ORB-1799). Those are finished-looking work nobody handed to the review lane; move them on instead of re-implementing them.',
+    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-not-exclusive routing tag: tickets labeled `agent:<tag>` rank first for a matching caller, foreign `agent:*` tags rank last but stay eligible. Lowercased server-side. Set it to this worker\'s routing tag (often the model or fleet lane name).'),
+        role: z.enum(['implementation', 'review', 'preflight', 'integration']).optional()
+            .describe('Default `implementation`. The dispatcher only reserves a ticket whose (ticket, role) lease is free for THIS role.'),
+        leaseSeconds: z.number().int().min(60).max(86_400).optional()
+            .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
+        startTimer: z.boolean().optional()
+            .describe('Defaults to true for `implementation`, false for the attach-only roles.'),
+        agentSessionToken: z.string().optional()
+            .describe('Stable per-agent-instance token. Omit to use this MCP connection\'s own instance id.'),
+        resourceClaims: z.array(z.object(ResourceClaimShape)).max(50).optional()
+            .describe('ORB-1610 - resource claims to acquire alongside the reservation, AND to filter candidates: a ticket already held under a conflicting GRANTED write claim elsewhere is skipped even when its (ticket, role) lease is free.'),
+        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 - answer "is there work for me?" WITHOUT reserving anything: the same candidate walk (role pool, lane caps, labels, dependencies, leases), but no lease, no timer, no lane quota consumed. Returns `candidate` (the ticket a real pull would reserve right now) or the usual empty reason. Use it before spending a model turn on self-tasking.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeWorkNextHandler(client) {
+    // Per-connection rules-hash cache, same pattern as orboto_work_start.
+    let lastKnownRulesHash;
+    return async (args, extra) => {
+        const token = mcpInstanceToken(args.agentSessionToken, extra);
+        const res = await client.post('/work-sessions/next', {
+            projectKey: args.projectKey,
+            ...(args.peek ? { peek: true } : {}),
+            ...(args.agentTag ? { agentTag: args.agentTag } : {}),
+            ...(args.role ? { role: args.role } : {}),
+            ...(args.leaseSeconds ? { leaseSeconds: args.leaseSeconds } : {}),
+            ...(args.startTimer !== undefined ? { startTimer: args.startTimer } : {}),
+            ...(args.resourceClaims && args.resourceClaims.length > 0 ? { resourceClaims: args.resourceClaims } : {}),
+            ...(args.onConflict ? { onConflict: args.onConflict } : {}),
+            agentSessionToken: token,
+            ...(lastKnownRulesHash ? { knownRulesHash: lastKnownRulesHash } : {}),
+        });
+        validateNextWorkEnvelope(res, args.peek);
+        if (!res.reserved) {
+            // ORB-1930 - a peek that found work: name it, reserve nothing.
+            if (args.peek && res.candidate) {
+                const c = res.candidate;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                `Work is ready in "${args.projectKey}": ${c.ticketKey ?? c.ticketId} - ${c.title}${c.priority ? ` (${c.priority})` : ''}.`,
+                                'Nothing was reserved (peek). Call orboto_work_next without `peek` to take it.',
+                                ...landedIdleLines(res.landedIdle),
+                            ].join('\n'),
+                        }],
+                    structuredContent: {
+                        reserved: null,
+                        reason: null,
+                        candidate: c,
+                        candidatesConsidered: res.candidatesConsidered,
+                        ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
+                    },
+                };
+            }
+            // ORB-1774 - a pause is an operator decision, not a backoff situation:
+            // tell the agent to idle, not to poll for a free slot.
+            if (res.reason === 'autonomy_paused') {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: [
+                                'Autonomous work is PAUSED for this agent (by an operator, per-bot or workspace-wide). Do not poll for new tickets - idle and wait for an operator instruction or an agent-notify wakeup. Explicitly assigned work via orboto_work_start still runs.',
+                                ...landedIdleLines(res.landedIdle),
+                            ].join('\n'),
+                        }],
+                    structuredContent: {
+                        reserved: null,
+                        reason: res.reason,
+                        retryAfterSeconds: null,
+                        earliestFreeAt: null,
+                        candidatesConsidered: 0,
+                        ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
+                    },
+                };
+            }
+            const lines = [`No ready ticket in "${args.projectKey}" right now (${res.reason}).`];
+            lines.push(res.retryAfterSeconds != null
+                ? `Retry in ~${res.retryAfterSeconds}s (earliest known free: ${res.earliestFreeAt}).`
+                : 'No derivable ETA - poll again later or check the project board.');
+            lines.push(`Candidates considered: ${res.candidatesConsidered}.`);
+            lines.push(...landedIdleLines(res.landedIdle));
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+                structuredContent: {
+                    reserved: null,
+                    reason: res.reason,
+                    retryAfterSeconds: res.retryAfterSeconds,
+                    earliestFreeAt: res.earliestFreeAt,
+                    candidatesConsidered: res.candidatesConsidered,
+                    ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
+                },
+            };
+        }
+        const r = res.reserved;
+        validateRulesReceipt(r, lastKnownRulesHash, 'rules');
+        const lines = [
+            r.reused
+                ? `Renewed your existing ${r.session.role} session on ${r.ticket.ticketKey ?? r.session.ticketId}.`
+                : `Reserved ${r.ticket.ticketKey ?? r.session.ticketId} - started a ${r.session.role} work session.`,
+            `Session id: ${r.session.id} (pass this to orboto_work_session_finish / orboto_work_finish).`,
+            `Lease held until ${r.session.leaseUntil}; it renews automatically while you keep calling orboto.`,
+            r.session.activeTimerId ? 'Timer running.' : 'No timer started for this role.',
+        ];
+        if (r.queued && r.queued.length > 0) {
+            lines.push('Queued (waiting for a conflicting writer to release):', ...r.queued.map((q) => `  - ${q.claim.kind}:${q.claim.value} - position ${q.position}`));
+        }
+        lines.push('', '## Working rules');
+        if (r.rulesUnchanged) {
+            lines.push(`Unchanged since your last call on this connection (hash ${r.rulesHash}). If these rules are not currently in your context, call orboto_session_start with rulesOnly: true before proceeding.`);
+        }
+        else {
+            lines.push(r.rules?.trim() || '(no workspace rules configured)');
+        }
+        lines.push('', '## Project primer');
+        lines.push(r.primer.markdown.trim() || '(primer unavailable)');
+        lines.push('', `## Ticket: ${r.ticket.ticketKey ?? '?'}`);
+        lines.push(r.ticket.title);
+        lines.push(`Status: ${r.ticket.statusName ?? r.ticket.status}  Priority: ${r.ticket.priority}  Type: ${r.ticket.type}`);
+        if (r.ticket.description)
+            lines.push('', r.ticket.description);
+        lines.push('', '## Checklists');
+        if (r.checklists.length === 0) {
+            lines.push('(none)');
+        }
+        else {
+            for (const cl of r.checklists) {
+                lines.push(`${cl.title} (${cl.progress.done}/${cl.progress.total})${cl.triggersDone ? ' - triggers done' : ''}`);
+                for (const i of cl.items) {
+                    const link = i.linkedTicketKey ? ` -> [${i.linkedTicketKey}] (${i.linkedTicketStatusCategory ?? 'unknown'})` : '';
+                    lines.push(`- [${i.effectiveCompleted ? 'x' : ' '}] ${i.content}${link}`);
+                }
+            }
+        }
+        // ORB-1614 - see the comment on the other fmtDeps above.
+        const fmtDeps = (edges) => edges.length === 0 ? '(none)' : edges.map((e) => `- [${e.ticketKey ?? '?'}] ${e.title ?? `External dependency (access restricted)${e.resolved ? ' - resolved' : ' - still open'}`}${e.statusName ? ` - ${e.statusName}` : ''}`).join('\n');
+        lines.push('', '## Dependencies');
+        lines.push('Blocked by:', fmtDeps(r.dependencies.blockedBy), 'Blocks:', fmtDeps(r.dependencies.blocks));
+        const unhealthy = r.gitHealth.filter((c) => !c.healthy);
+        if (unhealthy.length > 0) {
+            lines.push('', '## Git connection health - WARNING');
+            for (const c of unhealthy) {
+                lines.push(`- "${c.name}" (${c.provider}) - ${GIT_HEALTH_REASON_TEXT[c.reason ?? ''] ?? c.reason ?? 'unknown reason'}`);
+            }
+        }
+        lines.push('', '## Other sessions on this ticket');
+        lines.push(r.siblingSessions.length === 0
+            ? '(none)'
+            : r.siblingSessions.map((s) => `  - [${s.role}] ${s.userFullName ?? s.userEmail ?? 'unknown'} - lease until ${s.leaseUntil}`).join('\n'));
+        lines.push(...landedIdleLines(res.landedIdle));
+        lastKnownRulesHash = r.rulesHash;
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                reserved: {
+                    session: r.session,
+                    reused: r.reused,
+                    queued: r.queued ?? [],
+                    rulesHash: r.rulesHash,
+                    rulesUnchanged: r.rulesUnchanged,
+                    primer: r.primer,
+                    ticket: r.ticket,
+                    checklists: r.checklists,
+                    dependencies: r.dependencies,
+                    gitHealth: r.gitHealth,
+                    siblingSessions: r.siblingSessions,
+                },
+                reason: null,
+                retryAfterSeconds: null,
+                earliestFreeAt: null,
+                candidatesConsidered: res.candidatesConsidered,
+                ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
+            },
+        };
+    };
+}

package/dist/tools/work-sessions-next.test.js

@@ -7,7 +7,7 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
-import { makeWorkNextHandler } from './work-sessions.js';
+import { makeWorkNextHandler } from './work-next.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
 function stub(responses) {
@@ -65,8 +65,31 @@ const RESERVED = {
     siblingSessions: [],
 };
 describe('orboto_work_next', () => {
+    const peekResponse = {
+        reserved: null, reason: null, retryAfterSeconds: null, earliestFreeAt: null,
+        candidatesConsidered: 1, landedIdle: [],
+        candidate: { ticketId: 't1', ticketKey: 'ACME-42', title: 'Ready', priority: null },
+    };
+    it('validates a peek candidate without claiming rules delivery or a reservation', async () => {
+        const calls = stub([{ json: peekResponse }, { json: peekResponse }]);
+        const handler = makeWorkNextHandler(client);
+        const result = await handler({ projectKey: 'ACME', peek: true });
+        expect(result.structuredContent).toMatchObject({ reserved: null, candidate: peekResponse.candidate });
+        expect(calls[0].body).toMatchObject({ peek: true });
+        expect(calls[0].body).not.toHaveProperty('knownRulesHash');
+        await expect(handler({ projectKey: 'ACME' })).rejects.toMatchObject({ reason: 'invalid_response' });
+    });
+    it.each([
+        { candidate: {} }, { candidate: { ticketId: '', ticketKey: null, title: '', priority: null } },
+        { candidate: { ticketId: 't1', title: 'Ready', priority: null } },
+        { candidate: { ticketId: 't1', ticketKey: null, title: 42, priority: null } },
+        { reason: 'none-matching' }, { reserved: RESERVED }, { candidatesConsidered: -1 },
+    ])('rejects malformed or contradictory peek responses %#', async (patch) => {
+        stub([{ json: { ...peekResponse, ...patch } }]);
+        await expect(makeWorkNextHandler(client)({ projectKey: 'ACME', peek: true })).rejects.toMatchObject({ reason: 'invalid_response' });
+    });
     it('reserves the winning candidate and renders the full bundle, sending projectKey straight through', async () => {
-        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 3 } }]);
+        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 3, landedIdle: [] } }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
         expect(calls).toHaveLength(1);
         expect(calls[0].method).toBe('POST');
@@ -87,25 +110,28 @@ describe('orboto_work_next', () => {
     });
     it('caches the rules hash across calls and renders "Renewed" on a reused session', async () => {
         const handler = makeWorkNextHandler(client);
-        stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1 } }]);
+        stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [] } }]);
         await handler({ projectKey: 'ACME' });
         const calls2 = stub([{
                 json: {
                     reserved: { ...RESERVED, reused: true, rulesUnchanged: true, rules: undefined },
-                    reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1,
+                    reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [],
                 },
             }]);
         const res2 = await handler({ projectKey: 'ACME' });
         expect(calls2[0].body?.knownRulesHash).toBe('abc123');
         const text2 = res2.content[0].text;
         expect(text2).toContain('Unchanged since your last call');
+        expect(text2).toContain('not currently in your context');
+        expect(text2).toContain('rulesOnly: true');
+        expect(text2).not.toContain('keep following what you already loaded');
         expect(text2).toContain('Renewed your existing');
     });
     it('renders a structured empty result with a retry hint (all-leased)', async () => {
         stub([{
                 json: {
                     reserved: null, reason: 'all-leased', retryAfterSeconds: 420,
-                    earliestFreeAt: '2026-07-24T10:15:00Z', candidatesConsidered: 4,
+                    earliestFreeAt: '2026-07-24T10:15:00Z', candidatesConsidered: 4, landedIdle: [],
                 },
             }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
@@ -124,7 +150,7 @@ describe('orboto_work_next', () => {
         stub([{
                 json: {
                     reserved: null, reason: 'none-matching', retryAfterSeconds: null,
-                    earliestFreeAt: null, candidatesConsidered: 0,
+                    earliestFreeAt: null, candidatesConsidered: 0, landedIdle: [],
                 },
             }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
@@ -134,7 +160,7 @@ describe('orboto_work_next', () => {
         expect(text).not.toContain('Retry in');
     });
     it('forwards role, leaseSeconds, and resourceClaims to the API', async () => {
-        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1 } }]);
+        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [] } }]);
         await makeWorkNextHandler(client)({
             projectKey: 'ACME',
             role: 'review',

package/dist/tools/work-sessions-shared.js

@@ -0,0 +1,17 @@
+/**
+ * ORB-1609 / ORB-1613 - the wire shapes the work-session tools share:
+ * resource claims, the start bundle `orboto_work_start` and
+ * `orboto_work_next` both return, and the git-health reason texts.
+ * Extracted so `orboto_work_next` can live in its own module (file-size
+ * ratchet, ORB-1863) without a cycle back into work-sessions.ts.
+ */
+import { z } from 'zod';
+export const ResourceClaimShape = {
+    kind: z.enum(['path', 'named']),
+    value: z.string().min(1).max(500),
+    mode: z.enum(['read', 'write']),
+};
+/** Shared 409-body reader: the endpoint's body carries EITHER `holder`
+ *  (a lease conflict) OR `claimConflicts` (a resource-claim conflict) -
+ *  never both, since the lease is checked before claims are applied. */
+export { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';

package/dist/tools/work-sessions-start.test.js

@@ -122,6 +122,9 @@ describe('orboto_work_start', () => {
         expect(post2.body?.knownRulesHash).toBe('abc123');
         const text2 = res2.content[0].text;
         expect(text2).toContain('Unchanged since your last work-start');
+        expect(text2).toContain('not currently in your context');
+        expect(text2).toContain('rulesOnly: true');
+        expect(text2).not.toContain('keep following what you already loaded');
         expect(text2).toContain('Renewed your existing');
     });
     it('surfaces the lease holder on a 409 instead of throwing', async () => {