@orboto/mcp 0.192.0 → 0.194.0

package/dist/tools/session-start.js

@@ -6,46 +6,7 @@
  * briefing so the agent re-anchors on how to work and what it was
  * doing. Read-only.
  *
- * ORB-1605 - also surfaces git-connection health for the projects the
- * caller currently has open work in. A dead/unhealthy connection means
- * commit ingestion may be stalled, which the agent should know about
- * BEFORE it assumes a closing check that depends on git activity is
- * reliable.
- *
- * ORB-1607 - lean startup contract:
- *   (a) rules-hash ack. `/agent-instructions` now returns a stable
- *       `rulesHash`. This handler remembers the last hash it saw FOR
- *       THE LIFETIME OF THIS MCP CONNECTION (one handler closure per
- *       `buildOrbotoMcpServer` call - see server.ts) and passes it back
- *       as `knownRulesHash` on every subsequent call. An unchanged hash
- *       collapses the multi-thousand-token rules block into a one-line
- *       ack, which is most of the field-measured 12-18k token/session
- *       cost on a workspace with configured instruction blocks. Never
- *       exposed as a tool input - the caller (an LLM) just calls the
- *       tool the same way every time; the cache is transparent.
- *   (b) optional `ticketKey` input bundles a project primer, the full
- *       ticket (incl. dependencies + checklists), that project's git
- *       health, and any other agent sessions currently working the same
- *       ticket into the SAME response - replacing what would otherwise
- *       be >=4 separate tool calls (get_project_primer, get_ticket,
- *       get_checklists, list_ticket_dependencies) at the point an agent
- *       has the least context loaded.
- *
- * ORB-1818 - the rules INDEX. Measured on production 2026-09-03: the
- * last 15 `session_start` calls cost 21.8k-29.3k characters each, 89 %
- * of it the assembled rule text, and none was ever truncated (the tool
- * held a 48k per-tool budget). A result is re-sent on every later
- * request, so that block was the single largest carry cost an agent
- * paid, on every cold start, whether or not it needed a single rule.
- *
- * The default answer now carries the rules HASH plus one line per rule
- * block (title only, in delivery order) and a `response_expand` handle;
- * the full, byte-identical text is one call away via `rulesOnly: true`
- * (stateless, never truncated) or that handle (in-process, 15 min). The
- * ack semantics are unchanged: a caller that already acked this exact
- * hash gets neither the text NOR the index, and `forceRules: true`
- * still returns the full text inline for offline agents and operator
- * debugging.
+ * @see ORB-1605, ORB-1607, ORB-1818
  */
 import { z } from 'zod';
 import { resolveTicketByKey, applyAgentProfile } from './shared.js';
@@ -55,29 +16,17 @@ 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. '
-        // ORB-1805 - parameter prose moved out of the input schema (paid for
-        // at every connect) into the description orboto_help serves in full.
         + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them.',
     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.'),
-        // ORB-1697 - the caller is the only party that knows whether it still
-        // HOLDS the rules. See the ack-defect note on the handler below.
         forceRules: z.boolean().optional().describe('Always return the full rules; set it when you do not hold them.'),
-        // ORB-1818 - the stateless way back from the index to the full text.
         rulesOnly: z.boolean().optional().describe('Return ONLY the complete rules text.'),
-        // ORB-1753 - self-declared classification for rule targeting; defaults
-        // to ORBOTO_AGENT_KIND / ORBOTO_MODEL_TIER env, then the api-key's
-        // standing profile server-side.
         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.'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
-// 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
-// can't turn session-start into N parallel requests.
 const MAX_GIT_HEALTH_PROJECTS = 8;
 /** ORB-1607 - build the `--ticket` one-shot bundle. Never throws: an
  *  unresolvable/unauthorized ticket key comes back as a text error
@@ -96,9 +45,6 @@ async function buildTicketBundle(client, ticketKey) {
         };
     }
     const [enriched, checklists, deps, primer, gitHealthConnections, activeSessions] = await Promise.all([
-        // resolveTicketByKey hits the by-key endpoint, which returns a bare
-        // row (no statusCategory / assignees / description). Re-fetch the
-        // enriched by-id shape, mirroring orboto_get_ticket.
         client.get(`/projects/${resolved.projectId}/tickets/${resolved.id}`).catch(() => resolved),
         client.get(`/tickets/${resolved.id}/checklists`)
             .then((r) => (Array.isArray(r) ? r : []))
@@ -115,19 +61,9 @@ async function buildTicketBundle(client, ticketKey) {
             .get(`/projects/${resolved.projectId}/git-health`)
             .then((r) => (Array.isArray(r?.connections) ? r.connections : []))
             .catch(() => []),
-        // ORB-704 - non-admins only see their own sessions; that's an
-        // acceptable "cheaply available" degrade, not a bug to work around.
         client.get('/v1/agent/presence').catch(() => []),
     ]);
-    // ORB-1697 - `enriched ?? resolved` trusted truthiness: a 200 whose body
-    // is `{}` is truthy, so the fallback never fired and the bundle rendered
-    // "Ticket bundle: undefined" with empty fields. Fall back on the row we
-    // already resolved unless the enriched read actually carries a ticket.
     const full = enriched?.ticketKey ? enriched : resolved;
-    // ORB-1697 - the `.catch` above only covers a REJECTED request. A 200 with
-    // an unexpected body (a wrapped/paginated shape, or an older instance)
-    // would make `.filter` throw and take the whole digest down over an
-    // optional section. Coerce instead.
     const sessions = Array.isArray(activeSessions) ? activeSessions : [];
     const connections = Array.isArray(gitHealthConnections) ? gitHealthConnections : [];
     const sessionsOnTicket = sessions.filter((s) => s.workingOnTicket?.key === full.ticketKey);
@@ -153,9 +89,6 @@ async function buildTicketBundle(client, ticketKey) {
         }
     }
     lines.push('', '### Dependencies');
-    // ORB-1614 - a cross-project blocker/dependent the caller cannot read
-    // comes back with `title: null` - render a fixed, non-identifying
-    // placeholder instead of the literal "null".
     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('Blocked by:', fmtDeps(deps.blockedBy), 'Blocks:', fmtDeps(deps.blocks));
     if (unhealthy.length > 0) {
@@ -188,48 +121,23 @@ async function buildTicketBundle(client, ticketKey) {
                 blockedBy: deps.blockedBy.map((e) => ({ ticketKey: e.ticketKey, title: e.title, statusName: e.statusName, external: e.external, resolved: e.resolved })),
                 blocks: deps.blocks.map((e) => ({ ticketKey: e.ticketKey, title: e.title, statusName: e.statusName, external: e.external, resolved: e.resolved })),
             },
-            // ORB-1697 - only the connections that need attention. A healthy
-            // connection is 11 fields of "everything is fine" the agent never
-            // acts on; the count preserves the fact that connections exist.
             gitHealth: { unhealthy, healthyCount: connections.length - unhealthy.length },
             activeSessions: sessionsOnTicket.map((s) => ({ userFullName: s.userFullName, userEmail: s.userEmail, status: s.status, lastSeenAt: s.lastSeenAt })),
         },
     };
 }
 export function makeSessionStartHandler(client) {
-    // ORB-1607 - per-connection rules-hash cache. `buildOrbotoMcpServer`
-    // calls this factory once per MCP connection, so this closure variable
-    // lives for exactly that connection's lifetime and resets on reconnect.
-    //
-    // ORB-1697 - the defect that cache had: a stdio MCP server outlives
-    // `/clear` and every context compaction, so a repeat call answered
-    // "unchanged, keep following what you already loaded" at exactly the
-    // moment the agent no longer held the rules. The connection is the wrong
-    // thing to key the ack on; only the CALLER knows what is still in its
-    // context. Hence `forceRules`, and an ack text that says so.
     let lastKnownRulesHash;
     return async (input = {}) => {
         const rulesParams = new URLSearchParams();
         if (input.projectId)
             rulesParams.set('projectId', input.projectId);
-        // ORB-1753 - rule targeting: explicit input > env > (server-side) the
-        // api-key's standing profile. The rules hash is profile-specific
-        // server-side, so the cached ack stays valid per profile.
         applyAgentProfile(rulesParams, { agentKind: input.agentKind, modelTier: input.modelTier });
-        // ORB-1818 - both full-text answers bypass the ack: the caller is
-        // asking for the text precisely because it does not hold it.
         const wantsFullRules = input.forceRules === true || input.rulesOnly === true;
         if (lastKnownRulesHash && !wantsFullRules)
             rulesParams.set('knownRulesHash', lastKnownRulesHash);
         const rulesQs = rulesParams.toString();
         const rulesPath = rulesQs ? `/agent-instructions?${rulesQs}` : '/agent-instructions';
-        // ORB-1818 - `rulesOnly`: the STATELESS way back from the index to the
-        // full text. The `response_expand` handle the index also carries lives
-        // in this process' memory (15 min, 16 payloads), so a server restart,
-        // a reconnect or simply 16 later truncations can retire it - and a
-        // binding rule must never become unreachable. This path re-reads the
-        // 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 loadRequiredRules(client, rulesPath);
             if (rules.rulesHash)
@@ -258,24 +166,14 @@ export function makeSessionStartHandler(client) {
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
             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
-            // context and would otherwise re-claim / re-report finished work.
-            // Cap 20.
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
             client.get('/time/timer').catch(() => null),
-            // ORB-1727 - unread agent messages, delivered right where an agent
-            // re-orients. Coerced defensively (ORB-1697 lesson) and optional.
             client.get('/v1/agent/messages?limit=10')
                 .then((r) => (Array.isArray(r?.messages) ? r.messages : []))
                 .catch(() => []),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         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
-        // services/git-health.ts) - safe to fan out on every session start.
         const projectIds = [...new Set(tickets.map((t) => t.projectId).filter((id) => !!id))].slice(0, MAX_GIT_HEALTH_PROJECTS);
         const gitHealthByProject = await Promise.all(projectIds.map(async (projectId) => ({
             projectId,
@@ -292,13 +190,7 @@ export function makeSessionStartHandler(client) {
         const unhealthyWarnings = gitHealthWithConnections.flatMap((p) => p.connections
             .filter((c) => !c.healthy)
             .map((c) => `- Project ${p.projectId}: connection "${c.name}" (${c.provider}) is unhealthy - ${GIT_HEALTH_REASON_TEXT[c.reason ?? ''] ?? c.reason ?? 'unknown reason'}. If closing a ticket here depends on commit/PR ingestion, verify manually - ingestion may be stalled.`));
-        // ORB-1607 - the optional one-shot ticket bundle, built after the
-        // rest so it doesn't hold up the core digest on a slow primer render.
         const bundle = input.ticketKey ? await buildTicketBundle(client, input.ticketKey) : null;
-        // ORB-1697 - when the caller named the ticket it is working, the
-        // cross-project assigned list is noise: it measured 3.5k characters of
-        // other projects' tickets on a real call. List the ones in the same
-        // project, count the rest so nothing is hidden.
         const scopeProjectId = bundle?.projectId;
         const scopedTickets = scopeProjectId
             ? tickets.filter((t) => !t.projectId || t.projectId === scopeProjectId)
@@ -309,11 +201,6 @@ export function makeSessionStartHandler(client) {
             lines.push(`You are ${me.fullName ?? me.email}${me.email ? ` (${me.email})` : ''}.`);
         if (me?.workspaceLocale || me?.locale)
             lines.push(`Write tickets / comments / docs in: ${me.workspaceLocale ?? me.locale}.`);
-        // ORB-1818 - three delivery modes for the rules, cheapest first:
-        //   ack    - this connection already delivered this exact hash.
-        //   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 ?? '';
         const rulesIndex = Array.isArray(rules.rulesIndex)
             ? rules.rulesIndex.map((e) => e?.title).filter((t) => typeof t === 'string' && t.length > 0)
@@ -321,23 +208,14 @@ export function makeSessionStartHandler(client) {
         const deliverIndex = !rules.rulesUnchanged && input.forceRules !== true && rulesIndex.length > 0 && rulesText.length > 0;
         const deliverFull = !rules.rulesUnchanged && !deliverIndex && rulesText.length > 0;
         const rulesChars = rules.rulesChars ?? rulesText.length;
-        // The way back, spelled out for the structured half too: Claude Code
-        // keeps `structuredContent` and drops the text block, so a pointer
-        // that lives only in the Markdown reaches half the clients.
         const HOW_TO_READ_RULES = 'Call orboto_session_start { rulesOnly: true } for the complete rule text (one call, never truncated). '
             + 'Do that whenever you do not already hold this exact rulesHash - after a compaction, a /clear, or as a fresh agent.';
         let rulesHandle;
         lines.push('', '## Working rules - follow these');
         if (rules.rulesUnchanged) {
-            // ORB-1697 - never assert that the caller still HAS the rules. This
-            // connection delivered them once, which says nothing about whether
-            // they survived a compaction or a /clear on the client side.
             lines.push(`Unchanged since this connection last delivered them (hash ${rules.rulesHash}), so they were left out to save context.`, 'If the rules are NOT in your context right now - after a compaction, a /clear, or because you are a fresh agent on an existing connection - call this tool again with rulesOnly=true (rules alone) or forceRules=true (rules plus this digest) and read them in full. Do not proceed on a half-remembered rule set.');
         }
         else if (deliverIndex) {
-            // The full text stays one call away in BOTH directions: statelessly
-            // via rulesOnly, and via the standard ORB-1697 expand handle while
-            // this process still holds it.
             rulesHandle = storePayload('orboto_session_start', {
                 structuredContent: { rules: rules.instructions ?? '' },
                 text: rules.instructions ?? '',
@@ -353,9 +231,6 @@ export function makeSessionStartHandler(client) {
             lines.push('No tickets currently assigned to you - claim or create one before you start coding.');
         else {
             for (const t of scopedTickets) {
-                // ORB-1799 - the flag is the whole point of listing this ticket
-                // again, so it goes on the SAME line, not into a separate section
-                // a compaction-recovering agent might skim past.
                 const landed = t.landedIdle
                     ? ` - LANDED, IDLE ${t.landedIdleWorkingDays ?? '?'} working day(s): a commit is linked but the ticket never moved. Verify it is finished, then move it to review (orboto_work_finish / move_ticket) instead of re-implementing it.`
                     : '';
@@ -380,14 +255,9 @@ export function makeSessionStartHandler(client) {
             lines.push(...bundle.lines);
         lines.push('', 'Re-run this after any context compaction to re-sync.');
         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.
             ...(deliverFull ? { _meta: { [PROTECT_TEXT_META]: true } } : {}),
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
-                // ORB-1818 - empty in index/ack mode: the whole point is that the
-                // text is not carried. `rulesDelivery` says which answer this is.
                 rules: deliverFull ? (rules.instructions ?? '') : '',
                 rulesHash: rules.rulesHash ?? null,
                 rulesUnchanged: rules.rulesUnchanged === true,
@@ -400,15 +270,10 @@ export function makeSessionStartHandler(client) {
                     ticketKey: t.ticketKey,
                     title: t.title,
                     status: t.statusName ?? t.status ?? null,
-                    // ORB-1799 - only carried when true; a `false` on every row is
-                    // budget spent on "nothing to see here" (see the MCP response
-                    // budget contract in CLAUDE.md).
                     ...(t.landedIdle ? { landedIdle: true, landedIdleWorkingDays: t.landedIdleWorkingDays ?? null } : {}),
                 })),
                 ...(elsewhereCount > 0 ? { inProgressElsewhereCount: elsewhereCount } : {}),
                 timer: timer?.ticketId ? { ticketKey: timer.ticketKey ?? null, startedAt: timer.startedAt ?? null } : null,
-                // ORB-1697 - unhealthy connections only; a healthy one is 11 fields
-                // the agent never acts on. `healthyCount` keeps the fact visible.
                 gitHealth: {
                     unhealthy: gitHealthWithConnections
                         .map((p) => ({ projectId: p.projectId, connections: p.connections.filter((c) => !c.healthy) }))

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

@@ -54,9 +54,6 @@ describe('orboto_session_start (ORB-1093)', () => {
         expect(text).toContain('Running on ORB-42');
         expect(calls.some((c) => c.startsWith('/agent-instructions'))).toBe(true);
         expect(calls.some((c) => c.startsWith('/time/timer'))).toBe(true);
-        // ORB-1330 - the briefing must only ask for OPEN work; DONE tickets
-        // must never reach the "in-progress" section. Assert the status
-        // filter is on the wire so a future refactor can't silently widen it.
         const assignedCall = calls.find((c) => c.startsWith('/users/me/assigned-tickets'));
         expect(assignedCall).toBeDefined();
         expect(assignedCall).toContain('statuses=IN_PROGRESS,IN_REVIEW');
@@ -73,9 +70,6 @@ describe('orboto_session_start (ORB-1093)', () => {
         expect(text).toContain('No tickets currently assigned');
         expect(text).toContain('No timer running');
     });
-    // ORB-1605 - session-start fans out to GET /projects/:id/git-health for
-    // every distinct project the caller has open work in, and surfaces a
-    // warning when a connection is unhealthy.
     it('warns when a project git connection is unhealthy', async () => {
         stubByPath({
             '/users/me/assigned-tickets': {
@@ -96,8 +90,6 @@ describe('orboto_session_start (ORB-1093)', () => {
         expect(text).toContain('Git connection health - WARNING');
         expect(text).toContain('orboto/orboto');
         expect(text).toContain('connection is deactivated');
-        // ORB-1697 - unhealthy connections only; a healthy one is 11 fields
-        // the agent never acts on, so it is reduced to a count.
         const structured = res.structuredContent;
         expect(structured.gitHealth.unhealthy).toHaveLength(1);
         expect(structured.gitHealth.unhealthy[0].projectId).toBe('proj-1');
@@ -123,10 +115,6 @@ describe('orboto_session_start (ORB-1093)', () => {
         expect(text).not.toContain('Git connection health - WARNING');
     });
 });
-// ORB-1607 - rules-hash ack: the handler remembers the last rulesHash it
-// saw FOR THE LIFETIME OF ONE `makeSessionStartHandler(client)` CLOSURE
-// (mirrors one MCP connection) and passes it back as `knownRulesHash` on
-// every subsequent call.
 describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
     it('sends no knownRulesHash on the first call, then passes the received hash back on the second', async () => {
         const calls = [];
@@ -162,9 +150,6 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
         const secondCall = calls.find((c) => c.startsWith('/agent-instructions'));
         expect(secondCall).toBe('/agent-instructions?knownRulesHash=abc123def456');
         const secondText = second.content[0].text;
-        // ORB-1697 - the ack must not assert that the CALLER still holds the
-        // rules (a stdio server outlives /clear and every compaction), and it
-        // must name the way to get them back.
         expect(secondText).toContain('Unchanged since this connection last delivered them');
         expect(secondText).toContain('forceRules=true');
         expect(secondText).not.toContain('keep following what you already loaded');
@@ -185,9 +170,6 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
         expect(call).toBe('/agent-instructions');
     });
 });
-// ORB-1607 - the optional `ticketKey` one-shot bundle: project primer,
-// full ticket (incl. dependencies + checklists), git health, and active
-// sessions folded into the same response.
 describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
     const bundleStubs = {
         '/projects/by-key/ORB': { id: 'proj-1', key: 'ORB', name: 'orboto' },
@@ -212,7 +194,6 @@ describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
         '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
         '/agent-instructions': { instructions: 'rules here', rulesHash: 'h1' },
         '/time/timer': {},
-        // Re-fetch of the enriched by-id row (mirrors orboto_get_ticket).
         '/projects/proj-1/tickets/tick-1': {
             id: 'tick-1', projectId: 'proj-1', ticketKey: 'ORB-42', title: 'Bug',
             status: 'IN_PROGRESS', statusName: 'In Progress', priority: 'high', type: 'bug',
@@ -220,10 +201,6 @@ describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
         },
     };
     it('folds primer + ticket + dependencies + checklists + git health + active sessions into one response', async () => {
-        // bundleStubs first - the merged map is matched by `startsWith`, and
-        // baseStubs' bare `/projects/proj-1/tickets/tick-1` would otherwise
-        // shadow bundleStubs' longer `/projects/proj-1/tickets/tick-1/dependencies`
-        // if it came first in iteration order.
         const calls = stubByPath({ ...bundleStubs, ...baseStubs });
         const res = await makeSessionStartHandler(client)({ ticketKey: 'ORB-42' });
         const text = res.content[0].text;
@@ -239,7 +216,6 @@ describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
         expect(structured.ticketBundle.checklists).toHaveLength(1);
         expect(structured.ticketBundle.dependencies.blockedBy).toHaveLength(1);
         expect(structured.ticketBundle.activeSessions).toHaveLength(1);
-        // Replaces what would otherwise be several separate calls.
         expect(calls.some((c) => c.startsWith('/projects/proj-1/ai-primer'))).toBe(true);
         expect(calls.some((c) => c.startsWith('/tickets/tick-1/checklists'))).toBe(true);
         expect(calls.some((c) => c.startsWith('/projects/proj-1/tickets/tick-1/dependencies'))).toBe(true);
@@ -250,7 +226,6 @@ describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
         const text = res.content[0].text;
         expect(text).toContain('## Ticket bundle: ORB-999');
         expect(text).toContain('Could not load this ticket');
-        // The rest of the digest (rules, in-progress work, timer) still renders.
         expect(text).toContain('## Working rules');
         expect(text).toContain('## Timer');
         const structured = res.structuredContent;
@@ -275,10 +250,9 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
     it('forceRules re-sends the rules in full even when this connection already delivered them', async () => {
         const calls = stubByPath(rulesStub);
         const handler = makeSessionStartHandler(client);
-        await handler(); // primes the per-connection hash
+        await handler();
         calls.length = 0;
         const forced = await handler({ forceRules: true });
-        // No knownRulesHash means the API cannot answer with an ack.
         expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
         const text = forced.content[0].text;
         expect(text).toContain('THE FULL RULE TEXT');
@@ -312,7 +286,6 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
         const structured = res.structuredContent;
         expect(structured.gitHealth.unhealthy).toEqual([]);
         expect(structured.gitHealth.healthyCount).toBe(1);
-        // And the connection object itself is nowhere in the payload.
         expect(JSON.stringify(structured)).not.toContain('lastProbeAt');
     });
     it('with a ticketKey, open work in OTHER projects becomes a count instead of 20 rows', async () => {
@@ -323,7 +296,6 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 id: 'tick-1', projectId: 'proj-1', ticketKey: 'ORB-42', title: 'Bug',
                 status: 'IN_PROGRESS', statusName: 'In Progress', priority: 'high', type: 'bug',
             },
-            // Longest path first - the stub map is matched by startsWith.
             '/users/me/assigned-tickets': {
                 items: [
                     { ticketKey: 'ORB-42', title: 'Same project', statusName: 'In Progress', projectId: 'proj-1' },
@@ -341,7 +313,6 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
         expect(structured.inProgress.map((t) => t.ticketKey)).toEqual(['ORB-42']);
         expect(structured.inProgressElsewhereCount).toBe(2);
         const text = res.content[0].text;
-        // Nothing is hidden: the count is stated, with the way to list them.
         expect(text).toContain('2 open ticket(s) assigned to you in other projects');
         expect(text).toContain('orboto_my_tickets');
         expect(text).not.toContain('Another project entirely');
@@ -376,8 +347,6 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
 describe('orboto_session_start - a 200 with an unexpected body never kills the digest (ORB-1697)', () => {
     const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' });
     it('renders the digest when every optional endpoint answers 200 with {}', async () => {
-        // Only the paths the digest cannot work without return real data; every
-        // optional read answers `{}`, which is what the fallthrough produces.
         stubByPath({
             '/projects/by-key/ORB': { id: 'proj-1', key: 'ORB', name: 'orboto' },
             '/projects/proj-1/tickets/by-key/42': { id: 'tick-1', projectId: 'proj-1', ticketKey: 'ORB-42', title: 'Bug' },
@@ -417,14 +386,12 @@ describe('ORB-1753 - rule targeting passthrough', () => {
         calls = stubByPath({ '/agent-instructions': { instructions: 'RULES', rulesHash: 'h2' } });
         handler = makeSessionStartHandler(client);
         await handler({});
-        // env applies, lowercase-normalized client-side.
         expect(calls.find((c) => c.startsWith('/agent-instructions'))).toContain('agentKind=coding');
         expect(calls.find((c) => c.startsWith('/agent-instructions'))).toContain('modelTier=frontier');
         vi.restoreAllMocks();
         calls = stubByPath({ '/agent-instructions': { instructions: 'RULES', rulesHash: 'h3' } });
         handler = makeSessionStartHandler(client);
         await handler({ agentKind: 'reviewer' });
-        // explicit input beats the env default.
         expect(calls.find((c) => c.startsWith('/agent-instructions'))).toContain('agentKind=reviewer');
     });
 });
@@ -460,22 +427,16 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         stubDigest(rulesFull);
         const res = await makeSessionStartHandler(client)();
         const budgeted = applyResponseBudget('orboto_session_start', res, {});
-        // The whole point: no truncation, because there is nothing big left.
         expect(budgeted.truncatedChars).toBe(0);
         expect(budgeted.responseChars).toBeLessThan(DEFAULT_BUDGET_CHARS);
-        // ...and the tool no longer buys itself a special budget.
         expect(budgetFor('orboto_session_start', {})).toBe(DEFAULT_BUDGET_CHARS);
         const structured = res.structuredContent;
         expect(structured.rulesDelivery).toBe('index');
         expect(structured.rules).toBe('');
-        // One line per enabled block, in delivery order.
         expect(structured.rulesIndex).toEqual(BLOCK_TITLES);
         expect(structured.rulesChars).toBe(RULES_TEXT.length);
-        // The way back must live in the STRUCTURED half too - Claude Code
-        // keeps that one and drops the text block.
         expect(structured.rulesHowToRead).toContain('rulesOnly');
         expect(structured.rulesHandle).toBeTruthy();
-        // The rest of the digest is unchanged (ORB-1799 landed-idle included).
         expect(structured.inProgress).toHaveLength(2);
         expect(structured.inProgress[1].landedIdle).toBe(true);
         expect(structured.timer?.ticketKey).toBe('ORB-42');
@@ -527,13 +488,9 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(res.structuredContent.rulesDelivery).toBe('full');
         const budgeted = applyResponseBudget('orboto_session_start', res, {});
         expect(budgeted.truncatedChars).toBe(0);
-        // Both halves survive: the structured one via PROTECTED_PATHS, the
-        // text one via the per-call PROTECT_TEXT_META flag...
         expect(budgeted.result.structuredContent.rules).toBe(RULES_TEXT);
         expect(budgeted.result.content[0].text).toContain(RULES_TEXT);
-        // ...and no misleading "response truncated" notice is appended.
         expect(budgeted.result.content[0].text).not.toContain('Response truncated');
-        // The marker itself never reaches the wire.
         expect(budgeted.result._meta).toBeUndefined();
     });
     it('rulesOnly returns just the rules - no tickets, no timer, no other calls', async () => {

package/dist/tools/set-parent.js

@@ -1,23 +1,7 @@
 /**
  * ORB-799 (gap-cluster 8) - re-parent existing tickets.
  *
- * `orboto_update_ticket` accepts most ticket fields but NOT
- * `parentTicketId` / `parentTicketKey`, mirroring an API choice made
- * during ORB-309: parent assignment was treated as a creation-time
- * decision (set via `orboto_create_ticket`'s `parentTicketKey`) and the
- * patch surface was deliberately narrowed.
- *
- * In practice that left a gap: re-parenting an existing ticket under a
- * new epic (e.g. discovering during cluster-formation that ORB-600
- * belongs under ORB-800 as a sub-ticket) had no MCP-side path and
- * required falling back to the Bash wrapper's raw `patch /projects/...`
- * route - documented in `feedback_mcp_reparent_limitation.md`.
- *
- * Design choice: separate `orboto_set_parent` tool rather than
- * extending `orboto_update_ticket`'s patch shape. Symmetric to
- * `orboto_set_milestone` which exists for the same reason - a
- * dedicated tool with clearer semantics, easier permission gating
- * thinking, and a natural `parentTicketKey: null` path for detaching.
+ * @see ORB-309, ORB-600, ORB-800
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
@@ -52,8 +36,6 @@ export function makeSetParentHandler(client) {
             updated = await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { parentTicketId });
         }
         catch (err) {
-            // Surface the API's own cycle-detection error verbatim if it
-            // catches a deeper cycle we couldn't see from one hop above.
             if (err instanceof OrbotoApiError && err.status === 400) {
                 throw new Error(`Re-parent rejected by the API: ${err.body || 'cycle or constraint violation'}.`);
             }

package/dist/tools/shared.js

@@ -22,7 +22,6 @@ export async function resolveProjectByKey(client, key) {
 export function agentTicketListRow(t, verbose = false) {
     if (verbose) {
         return {
-            // ORB-1179 - uuid for write tools that want it without a lookup.
             id: t.id,
             key: t.ticketKey,
             title: t.title,
@@ -41,9 +40,6 @@ export function agentTicketListRow(t, verbose = false) {
             ...(t.waitingForGitIngestion ? { waitingForGitIngestion: true } : {}),
         };
     }
-    // Lean row: fields at their DEFAULT value are omitted entirely - a
-    // reader treats absence as "task / normal / no due date / unassigned".
-    // The list is a decision aid; the full picture is one get_ticket away.
     const assigneeNames = (t.assignees ?? []).map((a) => a.fullName || a.email);
     return {
         key: t.ticketKey,
@@ -53,7 +49,6 @@ export function agentTicketListRow(t, verbose = false) {
         ...(t.type && t.type !== 'task' ? { type: t.type } : {}),
         ...(t.dueDate ? { dueDate: t.dueDate } : {}),
         ...(assigneeNames.length > 0 ? { assigneeNames } : {}),
-        // ORB-1605 - only present when it fires; absent costs zero chars.
         ...(t.waitingForGitIngestion ? { waitingForGitIngestion: true } : {}),
     };
 }
@@ -92,25 +87,10 @@ export function ticketLine(t) {
     if (t.assignees && t.assignees.length > 0) {
         parts.push(`→ ${t.assignees.map((a) => a.fullName || a.email).join(', ')}`);
     }
-    // ORB-1605 - flag a ticket that's genuinely just waiting on stalled
-    // commit/PR ingestion, not a ticket someone forgot to close.
     if (t.waitingForGitIngestion)
         parts.push('[waiting on Git ingestion]');
     return parts.join(' ');
 }
-// ---------------------------------------------------------------------------
-// ORB-1252 / ORB-1283 / ORB-1609 - the agent-instance token.
-//
-// One MCP server process = one agent instance. Every surface that scopes work
-// to an instance (timers, and since ORB-1609 work-session leases) MUST derive
-// the token the same way, or the same agent ends up in two lanes: a claim
-// starting a timer in lane A while its work session holds the lease in lane B
-// is precisely the class of bug ORB-1603 had to paper over.
-//
-// A per-process random UUID rather than the PID: PIDs are recycled by the OS,
-// so a fresh process could inherit a recycled PID and adopt a previous
-// instance's stale timer or lease.
-// ---------------------------------------------------------------------------
 import { randomUUID } from 'node:crypto';
 const MCP_PROCESS_INSTANCE = `mcp-${randomUUID()}`;
 /** Precedence: explicit caller-supplied token > per-connection MCP session id
@@ -158,27 +138,6 @@ export function sizeBlockResult(err, verb) {
         isError: true,
     };
 }
-// ---------------------------------------------------------------------------
-// ORB-1826 - shared name-matching normaliser for free-text milestone /
-// label / status resolvers. An agent surface can hand back a name that
-// differs from the canonical DB row only in mechanically-recoverable ways:
-// leftover HTML entities from a rendering step upstream of the agent
-// (`QA & Testing`), a different case, or extra/collapsed whitespace.
-// The workspace rule is normalise, never reject - if the canonical form is
-// mechanically derivable, derive it instead of rejecting the call.
-//
-// Resolution order for every call site that uses `resolveByName`: raw exact
-// match first (zero-cost, preserves today's behaviour for clean names),
-// then a UNIQUE normalised match, then the existing ambiguity error listing
-// the candidates.
-//
-// Twin: `apps/api/src/lib/name-normalize.ts` (same two functions, same
-// semantics). This package ships standalone to npm with a deliberately
-// minimal dependency set (MCP SDK + zod only) and does not depend on the
-// API workspace package, so the ~20 lines below are duplicated rather than
-// imported. The Go CLI (`cli/internal/cmd/normalize.go`) carries a third
-// copy for the same reason. Keep all three in sync.
-// ---------------------------------------------------------------------------
 const NAMED_HTML_ENTITIES = {
     amp: '&',
     lt: '<',

package/dist/tools/shared.test.js

@@ -91,7 +91,6 @@ describe('ticketLine', () => {
         });
         expect(line).toBe('[ACME-2] Docs update (To Do)');
     });
-    // ORB-1605 - flags the stalled-ingestion signal in the one-line summary.
     it('appends the waiting-on-ingestion marker when waitingForGitIngestion is true', () => {
         const line = ticketLine({
             id: 't1', projectId: 'p1', milestoneId: null,
@@ -117,9 +116,6 @@ describe('ticketLine', () => {
         expect(line).toBe('[ACME-4] Docs change (In Review)');
     });
 });
-// ORB-1826 - production MCP error log showed `Milestone "QA & Testing"
-// not found` for a milestone literally named "QA & Testing": some upstream
-// surface handed the agent an HTML-escaped name. "Normalise, never reject."
 describe('normalizeName', () => {
     it('decodes the five XML-safe named entities', () => {
         expect(normalizeName('QA & Testing')).toBe('qa & testing');

package/dist/tools/similar-projection.js

@@ -1,23 +1,8 @@
 /**
  * ORB-1693 - the agent-facing projection of a duplicate-warning entry.
- *
- * Measured: `similarWarnings` was 76% of the entire create_ticket response
- * volume (~329k tokens over the corpus), and most of each entry was
- * decision-irrelevant: a CSS hex colour, a UUID next to the key, a
- * redundant statusName next to statusCategory, and similarity at 15
- * decimal places. The agent decision needs exactly:
- *
- *   { ticketKey, title, statusCategory, similarity (2dp), relation }
- *
- * The rich shape stays on the REST response for the web UI - this trims
- * only what agent surfaces emit. Same projection everywhere a warning
- * reaches an agent: create_ticket, the duplicate-block 409, check_similar
- * (mirrored in the chat registry + skill wrapper - keep them in sync).
  */
 export function trimSimilarEntry(w) {
     return {
-        // Keys over UUIDs (repo rule); the short-id fallback only exists for
-        // pre-backfill rows that never got a key.
         ticketKey: w.ticketKey ?? w.id.slice(0, 8),
         title: w.title,
         statusCategory: w.statusCategory ?? null,