@orboto/mcp 0.192.0 → 0.194.0

package/dist/server.js

@@ -1,17 +1,5 @@
 /**
  * ORB-244 Phase A/B - MCP server factory.
- *
- * Builds an `McpServer` with the registered tool set + a handle to
- * the orboto REST client. Transport is picked by the process entry
- * point (`index.ts`) based on `ORBOTO_MCP_TRANSPORT=stdio|http`.
- *
- * Keeping the server factory transport-agnostic means `server.ts` is
- * the same object whether we ship stdio for Local-Proxy (Phase G
- * `@orboto/mcp-cli`) or HTTP-SSE for Self-Hosted-inline.
- *
- * Tool registrations stay in this file so adding a new tool in
- * Phase C is one diff here + one new file in `tools/`. Phase D will
- * add `registerResource` / `registerPrompt` calls here too.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { VERSION } from './version.js';
@@ -68,12 +56,11 @@ import { listGitAppInstallationsToolConfig, makeListGitAppInstallationsHandler }
 import { createTicketToolConfig, makeCreateTicketHandler, updateTicketToolConfig, makeUpdateTicketHandler, moveTicketToolConfig, makeMoveTicketHandler, closeTicketToolConfig, makeCloseTicketHandler, deleteTicketToolConfig, makeDeleteTicketHandler, commentToolConfig, makeCommentHandler, updateCommentToolConfig, makeUpdateCommentHandler, deleteCommentToolConfig, makeDeleteCommentHandler, assignToolConfig, makeAssignHandler, unassignToolConfig, makeUnassignHandler, labelTicketToolConfig, makeLabelTicketHandler, unlabelTicketToolConfig, makeUnlabelTicketHandler, setMilestoneToolConfig, makeSetMilestoneHandler, addTicketDependencyToolConfig, makeAddTicketDependencyHandler, removeTicketDependencyToolConfig, makeRemoveTicketDependencyHandler, listTicketDependenciesToolConfig, makeListTicketDependenciesHandler, } from './tools/ticket-writes.js';
 import { timerStartToolConfig, makeTimerStartHandler, timerStopToolConfig, makeTimerStopHandler, logTimeToolConfig, makeLogTimeHandler, listTimeEntriesToolConfig, makeListTimeEntriesHandler, editTimeEntryToolConfig, makeEditTimeEntryHandler, deleteTimeEntryToolConfig, makeDeleteTimeEntryHandler, } from './tools/time-writes.js';
 import { listTicketSchedulesToolConfig, makeListTicketSchedulesHandler, scheduleTicketSessionToolConfig, makeScheduleTicketSessionHandler, cancelTicketSessionToolConfig, makeCancelTicketSessionHandler, } from './tools/ticket-schedules.js';
-import { checkToolConfig, makeCheckHandler, uncheckToolConfig, makeUncheckHandler, addCheckToolConfig, makeAddCheckHandler, removeCheckToolConfig, makeRemoveCheckHandler, newChecklistToolConfig, makeNewChecklistHandler, } from './tools/checklist-writes.js';
+import { checkToolConfig, makeCheckHandler, uncheckToolConfig, makeUncheckHandler, addCheckToolConfig, makeAddCheckHandler, removeCheckToolConfig, makeRemoveCheckHandler, updateCheckToolConfig, makeUpdateCheckHandler, newChecklistToolConfig, makeNewChecklistHandler, } from './tools/checklist-writes.js';
 import { listUsersToolConfig, makeListUsersHandler, getAuditLogToolConfig, makeGetAuditLogHandler, triggerBackupToolConfig, makeTriggerBackupHandler, } from './tools/admin-writes.js';
 import { freeBusyToolConfig, makeFreeBusyHandler } from './tools/free-busy.js';
 import { createFullBackupToolConfig, makeCreateFullBackupHandler, listBackupsToolConfig, makeListBackupsHandler, downloadBackupToolConfig, makeDownloadBackupHandler, } from './tools/backup.js';
 import { primerFactListToolConfig, makePrimerFactListHandler, primerFactAddToolConfig, makePrimerFactAddHandler, primerFactUpdateToolConfig, makePrimerFactUpdateHandler, primerFactSupersedeToolConfig, makePrimerFactSupersedeHandler, primerFactVerifyToolConfig, makePrimerFactVerifyHandler, primerFactDeleteToolConfig, makePrimerFactDeleteHandler, } from './tools/primer-facts.js';
-// ORB-799 - wrapper-feature-parity gap-close.
 import { whoamiToolConfig, makeWhoamiHandler } from './tools/identity.js';
 import { claimToolConfig, makeClaimHandler, unclaimToolConfig, makeUnclaimHandler, } from './tools/claim.js';
 import { reportFeedbackToolConfig, makeReportFeedbackHandler } from './tools/feedback.js';
@@ -103,18 +90,7 @@ const FALLBACK_WORKING_RULES = [
     'When you write a git commit that touches a ticket, put the ticket key (e.g. `ORB-42`) in parentheses at the END of the subject line - `feat(auth): add token rotation (ORB-42)`. The orboto git-activity parser links the commit by that key.',
     'Use sub-tickets for steps large enough to need their own commit / time tracking / review, and checklists for one-liners inside a single ticket\'s scope. Big features (Epic + 3+ phase tickets): create a milestone FIRST, then the Epic, then phase tickets as children on that milestone.',
 ].join(' ');
-// Static MCP operational hints - tool/resource/prompt usage that does
-// not change per workspace. The configurable working-rules are appended
-// live below. ORB-1520 - assembled per toolset: the curated manifest
-// gets the escape-hatch pointer, the full manifest keeps the
-// get_checklists hint (that tool only exists there).
 function staticMcpHints(toolset) {
-    // ORB-1805 - the minimal tier serves 8k/16k local models, where the
-    // instructions block competes with the user's own turn for the same
-    // few thousand tokens. Everything that is merely NICE to know
-    // (resources, prompts, checklist semantics, primer) is dropped here:
-    // `orboto_session_start` delivers the authoritative rules on the first
-    // call anyway, and `orboto_api_search` reaches the rest.
     if (toolset === 'minimal') {
         return [
             'orboto is a ticket + project management system. Ticket keys look like `PROJ-123`; the first segment is the project key.',
@@ -139,14 +115,6 @@ function staticMcpHints(toolset) {
         'All writes respect the caller\'s project-level permissions - a 403 means the API rejected the write, not the MCP server.',
     ].filter((s) => s.length > 0).join(' ');
 }
-// ORB-1177 - MCP clients cap how much of the `instructions` block they
-// inject and silently truncate the overflow (ORB-1168 saw a 5k+ string
-// cut mid-rule). Enforce our own budget so the high-priority head (hints
-// + non-negotiables + the orboto_session_start / orboto://rules pointers)
-// always survives, and the workspace rules are cut at a WHOLE-LINE
-// boundary with an explicit pointer to the cap-independent full set,
-// rather than the client slicing mid-sentence. The complete rules are
-// always available via orboto_session_start + the orboto://rules resource.
 const INSTRUCTIONS_BUDGET = 4000;
 const RULES_HEADING = 'Working rules for this workspace:\n';
 const TRUNCATION_MARKER = '\n\n[... rules truncated to fit the client cap - read the COMPLETE rules via the orboto_session_start tool or the orboto://rules resource ...]';
@@ -154,7 +122,7 @@ export function assembleInstructions(head, workingRules, budget = INSTRUCTIONS_B
     const full = `${head}\n\n${RULES_HEADING}${workingRules}`;
     if (full.length <= budget)
         return full;
-    const room = budget - head.length - RULES_HEADING.length - TRUNCATION_MARKER.length - 2; // 2 = the '\n\n' join
+    const room = budget - head.length - RULES_HEADING.length - TRUNCATION_MARKER.length - 2;
     let kept = '';
     if (room > 0) {
         for (const line of workingRules.split('\n')) {
@@ -167,23 +135,10 @@ export function assembleInstructions(head, workingRules, budget = INSTRUCTIONS_B
 }
 export async function buildOrbotoMcpServer(opts) {
     const client = new OrbotoClient(opts);
-    // ORB-1520 - the manifest mode. Explicit option (per-connection) wins,
-    // then the process-wide env default, then `curated`.
     const toolset = resolveToolset(opts.toolset, process.env.ORBOTO_MCP_TOOLSET);
-    // ORB-1090 - fetch the workspace's configurable working-rules at
-    // connect so admin edits propagate to every new MCP session. The
-    // instructions block is the one place every MCP client reliably sees
-    // the rules (clients don't read the repo's CLAUDE.md). If unavailable,
-    // keep the connection usable for recovery but gate all other tools.
     let workingRules = FALLBACK_WORKING_RULES;
-    // ORB-1471 - the same connect-time fetch also reports whether this
-    // workspace requires `orboto_session_start` before any other tool call
-    // (the hard gate). Unknown policy must never silently disable the gate.
     let requireSessionStart = true;
     try {
-        // ORB-1753 - stdio deployments can declare their profile via
-        // ORBOTO_AGENT_KIND / ORBOTO_MODEL_TIER; api-key standing profiles
-        // resolve server-side either way.
         const connectParams = new URLSearchParams();
         applyAgentProfile(connectParams);
         const connectQs = connectParams.toString();
@@ -196,33 +151,9 @@ export async function buildOrbotoMcpServer(opts) {
         workingRules = 'Workspace rules are unavailable. Built-in hints are not a substitute. Call orboto_session_start with forceRules and retry after connectivity or authentication recovers.';
     }
     const server = new McpServer({ name: 'orboto', version: VERSION }, {
-        // ORB-940 - advertise resources/subscribe so MCP-aware clients
-        // (Claude Desktop, Cursor) wire up live updates instead of
-        // polling. Even when no bridge is hooked up (stdio sessions)
-        // the capability stays on; subscriptions just stay quiet.
         capabilities: {
             resources: { subscribe: true, listChanged: true },
         },
-        // `instructions` appears in the system-prompt-style block some
-        // MCP clients inject before the user's first message. Static
-        // operational hints + the live, workspace-configurable working
-        // rules (ORB-1086).
-        //
-        // ORB-1168 - MCP clients cap how much of this block they inject; a
-        // 5k+ string was being silently truncated mid-rule, so an MCP-only
-        // agent (no skill / no repo CLAUDE.md) got incomplete rules. Put
-        // the orientation, a pointer to the full rule set (the
-        // orboto_session_start tool), and the core non-negotiables
-        // FIRST so they survive any truncation; the full workspace rules
-        // follow and only their tail is at risk.
-        // ORB-1805 - the minimal tier ships the HEAD ONLY: no workspace
-        // rules block at all. On an 8k window every rule line here is a
-        // line the user's own turn does not get, and the rules are not
-        // lost - `orboto_session_start` (which the head demands as the
-        // first action) returns the complete, authoritative set, and its
-        // length is then the caller's budget to spend, not a fixed tax on
-        // every connect. It also makes this block a CONSTANT: a workspace
-        // that grows its rules cannot grow the minimal manifest.
         instructions: toolset === 'minimal'
             ? [
                 staticMcpHints(toolset),
@@ -233,71 +164,34 @@ export async function buildOrbotoMcpServer(opts) {
                 'FIRST ACTION this session: call the `orboto_session_start` tool - it returns the complete, authoritative binding rules you must follow (plus your in-progress work). Re-run it after any context compaction. If the rules below look cut off, `orboto_session_start` and the `orboto://rules` resource always have the full set. (Do NOT use `orboto_list_agent_instructions` to read the rules - that manages rule blocks for admins.) Core non-negotiables: ticket-first (claim or create a ticket before touching code), one commit per ticket with the ticket key in the subject line, push after each commit, and never mark work done that is not actually done.',
             ].join('\n\n'), workingRules),
     });
-    // ORB-1331 - one-time session-start nudge. The state object lives for
-    // the lifetime of THIS server instance: the HTTP transport builds one
-    // server per session and the stdio transport one per process, so a
-    // single flag object is per-session (HTTP) / process-local (stdio)
-    // without any session-lifecycle plumbing. Shared by reference into
-    // every tool's dispatch wrapper below.
     const nudgeState = createNudgeState(requireSessionStart);
-    // ORB-311 - every tool dispatch posts one row to /admin/mcp/instrument
-    // via the withMetrics wrapper. `reg` is a one-line shim around
-    // `server.registerTool` that adds the metrics layer at registration
-    // time; per-tool files stay metrics-unaware.
-    // ORB-1520 - the toolset gate. Wraps the metrics-registering shim so a
-    // tail tool in curated mode simply never registers; the reg() CALL
-    // SITES below stay untouched (the chat-tools drift guard parses them
-    // from this file's source and must keep seeing the full set).
     const regAll = registerWithMetrics(server, client, opts.userAgentSuffix, nudgeState);
     const reg = (toolName, config, handler) => {
         if (!toolInToolset(toolName, toolset))
             return;
-        // ORB-1805 - the minimal tier drops the human-readable `title`
-        // (measured 580 characters across its 12 tools). `name` is already
-        // self-describing (orboto_create_ticket) and a client without a
-        // title falls back to it, so the display loss is small where the
-        // token pressure is largest. Curated/full keep their titles.
         const cfg = toolset === 'minimal' && config && 'title' in config
             ? (() => { const { title: _title, ...rest } = config; return rest; })()
             : config;
         regAll(toolName, cfg, handler);
     };
-    // Tools - alphabetical-ish by concept. Each tool file owns its
-    // input/output schema; the server just glues names to handlers.
     reg('orboto_ai_status', aiStatusToolConfig, makeAiStatusHandler(client));
-    reg('orboto_draft_customer_reply', draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler(client)); // ORB-2000
+    reg('orboto_draft_customer_reply', draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler(client));
     reg('orboto_embedding_status', embeddingStatusToolConfig, makeEmbeddingStatusHandler(client));
     reg('orboto_ai_usage', aiUsageToolConfig, makeAiUsageHandler(client));
-    // ORB-1093 - session-start / post-compact re-orientation digest.
     reg('orboto_session_start', sessionStartToolConfig, makeSessionStartHandler(client));
-    // ORB-1697 - the way back from a budget-truncated response. Serves the
-    // omitted remainder from the in-process store, so capping a response
-    // never loses content.
     reg('orboto_response_expand', responseExpandToolConfig, makeResponseExpandHandler());
-    // ORB-1741 - lazy full guidance: manifest descriptions are one-line
-    // summaries (tool-docs.ts); this serves the complete text on demand.
     reg('orboto_help', helpToolConfig, makeHelpHandler());
-    // ORB-1518 - Code-Mode escape hatch, discovery half: search the live
-    // OpenAPI spec / fetch one endpoint's schema on demand. Keeps the whole
-    // REST surface reachable without a named tool per endpoint.
     reg('orboto_api_search', apiSearchToolConfig, makeApiSearchHandler(client));
-    // ORB-1519 - the execute half: structured REST proxy through the
-    // API's full auth + permission chain (POST /system/api-proxy).
     reg('orboto_api_call', apiCallToolConfig, makeApiCallHandler(client));
-    // ORB-1089 - manage the configurable coding-agent rule blocks (admin:ai:write).
     reg('orboto_list_agent_instructions', listAgentInstructionsToolConfig, makeListAgentInstructionsHandler(client));
     reg('orboto_create_agent_instruction', createAgentInstructionToolConfig, makeCreateAgentInstructionHandler(client));
     reg('orboto_update_agent_instruction', updateAgentInstructionToolConfig, makeUpdateAgentInstructionHandler(client));
     reg('orboto_reset_agent_instruction', resetAgentInstructionToolConfig, makeResetAgentInstructionHandler(client));
     reg('orboto_delete_agent_instruction', deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler(client));
-    // ORB-705 - Multi-Agent Coordination tools (heartbeat, presence,
-    // directed notify). Layered on the ORB-704 REST surface.
     reg('orboto_agent_heartbeat', agentHeartbeatToolConfig, makeAgentHeartbeatHandler(client));
     reg('orboto_agent_presence', agentPresenceToolConfig, makeAgentPresenceHandler(client));
     reg('orboto_agent_notify', agentNotifyToolConfig, makeAgentNotifyHandler(client));
-    // ORB-1727 - the receive half of the store-and-forward inbox.
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
-    // ORB-964 - scoped fan-out for multi-agent coordination.
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
     reg('orboto_get_project', getProjectToolConfig, makeGetProjectHandler(client));
@@ -317,42 +211,27 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_requirements_spec', requirementsSpecToolConfig, makeRequirementsSpecHandler(client));
     reg('orboto_list_doc_spaces', listDocSpacesToolConfig, makeListDocSpacesHandler(client));
     reg('orboto_get_doc', getDocToolConfig, makeGetDocHandler(client));
-    // ORB-1342 (epic ORB-1339) - context-efficient doc snippet search +
-    // targeted edits. Wrap GET /docs/search (ORB-1340) and POST
-    // /docs/:id/edits (ORB-1341). Prefer these over get_doc + update_doc for
-    // small changes to a large doc: find a passage by snippet, change it by
-    // diff, never transfer the full body in either direction.
     reg('orboto_search_docs', searchDocsToolConfig, makeSearchDocsHandler(client));
     reg('orboto_edit_doc', editDocToolConfig, makeEditDocHandler(client));
     reg('orboto_edit_doc_section', editDocSectionToolConfig, makeEditDocSectionHandler(client));
-    // ORB-912 - doc-spaces CRUD + list docs in a space. Closes the
-    // first slice of the MCP doc-surface parity gap (epic ORB-911).
     reg('orboto_create_doc_space', createDocSpaceToolConfig, makeCreateDocSpaceHandler(client));
     reg('orboto_update_doc_space', updateDocSpaceToolConfig, makeUpdateDocSpaceHandler(client));
     reg('orboto_delete_doc_space', deleteDocSpaceToolConfig, makeDeleteDocSpaceHandler(client));
     reg('orboto_list_docs_in_space', listDocsInSpaceToolConfig, makeListDocsInSpaceHandler(client));
-    // ORB-913 - doc-page CRUD (plain create + update + delete + move).
     reg('orboto_create_doc', createDocToolConfig, makeCreateDocHandler(client));
     reg('orboto_update_doc', updateDocToolConfig, makeUpdateDocHandler(client));
     reg('orboto_delete_doc', deleteDocToolConfig, makeDeleteDocHandler(client));
     reg('orboto_move_doc', moveDocToolConfig, makeMoveDocHandler(client));
-    // ORB-914 - doc-attachments (upload + list + delete).
     reg('orboto_upload_doc_attachment', uploadDocAttachmentToolConfig, makeUploadDocAttachmentHandler(client));
     reg('orboto_list_doc_attachments', listDocAttachmentsToolConfig, makeListDocAttachmentsHandler(client));
     reg('orboto_delete_doc_attachment', deleteDocAttachmentToolConfig, makeDeleteDocAttachmentHandler(client));
-    // ORB-1455 - ticket-attachment read + view (list metadata, fetch bytes /
-    // image content block). Complements orboto_attach_to_ticket (write-only).
     reg('orboto_list_ticket_attachments', listTicketAttachmentsToolConfig, makeListTicketAttachmentsHandler(client));
     reg('orboto_get_attachment', getAttachmentToolConfig, makeGetAttachmentHandler(client));
-    // ORB-915 - doc export (Markdown + PDF).
     reg('orboto_export_doc_md', exportDocMdToolConfig, makeExportDocMdHandler(client));
     reg('orboto_export_doc_pdf', exportDocPdfToolConfig, makeExportDocPdfHandler(client));
-    // ORB-916 - doc revision history (list + get + restore). Closes
-    // the last slice of the doc-surface parity gap (epic ORB-911).
     reg('orboto_list_doc_revisions', listDocRevisionsToolConfig, makeListDocRevisionsHandler(client));
     reg('orboto_get_doc_revision', getDocRevisionToolConfig, makeGetDocRevisionHandler(client));
     reg('orboto_restore_doc_revision', restoreDocRevisionToolConfig, makeRestoreDocRevisionHandler(client));
-    // ORB-917 - doc comments (list + post + resolve + delete).
     reg('orboto_list_doc_comments', listDocCommentsToolConfig, makeListDocCommentsHandler(client));
     reg('orboto_post_doc_comment', postDocCommentToolConfig, makePostDocCommentHandler(client));
     reg('orboto_resolve_doc_comment', resolveDocCommentToolConfig, makeResolveDocCommentHandler(client));
@@ -365,13 +244,8 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_add_cross_project_link', addCrossProjectLinkToolConfig, makeAddCrossProjectLinkHandler(client));
     reg('orboto_update_cross_project_link', updateCrossProjectLinkToolConfig, makeUpdateCrossProjectLinkHandler(client));
     reg('orboto_remove_cross_project_link', removeCrossProjectLinkToolConfig, makeRemoveCrossProjectLinkHandler(client));
-    // ORB-918 - duplicate-space + resolve-links. Closes the doc-surface
-    // parity epic (ORB-911) - every doc-API endpoint now has an MCP
-    // pendant.
     reg('orboto_duplicate_doc_space', duplicateDocSpaceToolConfig, makeDuplicateDocSpaceHandler(client));
     reg('orboto_resolve_doc_smart_links', resolveDocSmartLinksToolConfig, makeResolveDocSmartLinksHandler(client));
-    // ORB-855 - LLM-Wiki tools (ingest / ask / lint / plan-apply / record /
-    // append-section / flag-stale). Thin wrappers over the Phase B/C/D routes.
     reg('orboto_wiki_ingest_url', wikiIngestUrlToolConfig, makeWikiIngestUrlHandler(client));
     reg('orboto_wiki_ask', wikiAskToolConfig, makeWikiAskHandler(client));
     reg('orboto_wiki_lint', wikiLintToolConfig, makeWikiLintHandler(client));
@@ -381,16 +255,12 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_wiki_append_section', wikiAppendSectionToolConfig, makeWikiAppendSectionHandler(client));
     reg('orboto_wiki_flag_stale', wikiFlagStaleToolConfig, makeWikiFlagStaleHandler(client));
     reg('orboto_wiki_save_answer', wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler(client));
-    // ORB-862 - personal AI-preference facts (owner-scoped).
     reg('orboto_personal_fact_list', personalFactListToolConfig, makePersonalFactListHandler(client));
     reg('orboto_personal_fact_add', personalFactAddToolConfig, makePersonalFactAddHandler(client));
     reg('orboto_personal_fact_update', personalFactUpdateToolConfig, makePersonalFactUpdateHandler(client));
     reg('orboto_personal_fact_delete', personalFactDeleteToolConfig, makePersonalFactDeleteHandler(client));
     reg('orboto_get_timer', getTimerToolConfig, makeGetTimerHandler(client));
     reg('orboto_list_git_app_installations', listGitAppInstallationsToolConfig, makeListGitAppInstallationsHandler(client));
-    // ORB-309 Phase C - write tools (Group 1: ticket mutations).
-    // Each respects the API's PBAC cascade - a 403 surfaces as
-    // OrbotoApiError → MCP throws → client sees an isError response.
     reg('orboto_create_ticket', createTicketToolConfig, makeCreateTicketHandler(client));
     reg('orboto_update_ticket', updateTicketToolConfig, makeUpdateTicketHandler(client));
     reg('orboto_move_ticket', moveTicketToolConfig, makeMoveTicketHandler(client));
@@ -404,73 +274,45 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_label_ticket', labelTicketToolConfig, makeLabelTicketHandler(client));
     reg('orboto_unlabel_ticket', unlabelTicketToolConfig, makeUnlabelTicketHandler(client));
     reg('orboto_set_milestone', setMilestoneToolConfig, makeSetMilestoneHandler(client));
-    // ORB-1037 - RACI agent surfaces: read the matrix + set a person's role.
     reg('orboto_raci', raciToolConfig, makeRaciHandler(client));
     reg('orboto_set_raci', setRaciToolConfig, makeSetRaciHandler(client));
-    // ORB-453 - ticket-dependency tools (3-way-sync gap filed after the
-    // skill wrapper landed in ORB-452). Same idempotent-on-409/404
-    // semantics as orboto_assign / orboto_unassign.
     reg('orboto_add_ticket_dependency', addTicketDependencyToolConfig, makeAddTicketDependencyHandler(client));
     reg('orboto_remove_ticket_dependency', removeTicketDependencyToolConfig, makeRemoveTicketDependencyHandler(client));
     reg('orboto_list_ticket_dependencies', listTicketDependenciesToolConfig, makeListTicketDependenciesHandler(client));
-    // ORB-309 Phase C - Group 2: time tools.
     reg('orboto_timer_start', timerStartToolConfig, makeTimerStartHandler(client));
     reg('orboto_timer_stop', timerStopToolConfig, makeTimerStopHandler(client));
     reg('orboto_log_time', logTimeToolConfig, makeLogTimeHandler(client));
     reg('orboto_list_time_entries', listTimeEntriesToolConfig, makeListTimeEntriesHandler(client));
     reg('orboto_edit_time_entry', editTimeEntryToolConfig, makeEditTimeEntryHandler(client));
     reg('orboto_delete_time_entry', deleteTimeEntryToolConfig, makeDeleteTimeEntryHandler(client));
-    // ORB-626 - ticket meeting schedules (working sessions + iCal invites).
     reg('orboto_list_ticket_schedules', listTicketSchedulesToolConfig, makeListTicketSchedulesHandler(client));
     reg('orboto_schedule_ticket_session', scheduleTicketSessionToolConfig, makeScheduleTicketSessionHandler(client));
     reg('orboto_cancel_ticket_session', cancelTicketSessionToolConfig, makeCancelTicketSessionHandler(client));
-    // ORB-309 Phase C - Group 3: checklist writes (ORB-234 surface).
     reg('orboto_check', checkToolConfig, makeCheckHandler(client));
     reg('orboto_uncheck', uncheckToolConfig, makeUncheckHandler(client));
     reg('orboto_add_check', addCheckToolConfig, makeAddCheckHandler(client));
     reg('orboto_remove_check', removeCheckToolConfig, makeRemoveCheckHandler(client));
+    reg('orboto_update_check', updateCheckToolConfig, makeUpdateCheckHandler(client));
     reg('orboto_new_checklist', newChecklistToolConfig, makeNewChecklistHandler(client));
-    // ORB-309 Phase C - Group 4: admin-only tools. Each call hits a
-    // route gated on super-admin / admin:* permissions; a non-admin
-    // caller's 403 surfaces as a readable error from rewrite403().
     reg('orboto_list_users', listUsersToolConfig, makeListUsersHandler(client));
-    // ORB-625 - free/busy availability lookup for assignee selection (read).
     reg('orboto_free_busy', freeBusyToolConfig, makeFreeBusyHandler(client));
     reg('orboto_get_audit_log', getAuditLogToolConfig, makeGetAuditLogHandler(client));
     reg('orboto_trigger_backup', triggerBackupToolConfig, makeTriggerBackupHandler(client));
     reg('orboto_create_full_backup', createFullBackupToolConfig, makeCreateFullBackupHandler(client));
     reg('orboto_list_backups', listBackupsToolConfig, makeListBackupsHandler(client));
     reg('orboto_download_backup', downloadBackupToolConfig, makeDownloadBackupHandler(client));
-    // ORB-510 / ORB-513 - primer-fact tools. Wraps the ORB-511 REST
-    // surface so agents can record structured project facts that the
-    // primer renderer (ORB-512) surfaces at session start. The skill
-    // rule (ORB-514) tells agents *when* to record; these are the *how*.
     reg('orboto_primer_fact_list', primerFactListToolConfig, makePrimerFactListHandler(client));
     reg('orboto_primer_fact_add', primerFactAddToolConfig, makePrimerFactAddHandler(client));
     reg('orboto_primer_fact_update', primerFactUpdateToolConfig, makePrimerFactUpdateHandler(client));
     reg('orboto_primer_fact_supersede', primerFactSupersedeToolConfig, makePrimerFactSupersedeHandler(client));
     reg('orboto_primer_fact_verify', primerFactVerifyToolConfig, makePrimerFactVerifyHandler(client));
     reg('orboto_primer_fact_delete', primerFactDeleteToolConfig, makePrimerFactDeleteHandler(client));
-    // ORB-799 - wrapper-feature-parity gap-close. Eight clusters:
-    //   1. Identity   (whoami)
-    //   2. Composite  (claim, unclaim)
-    //   3. Milestone CRUD (create, close, update)
-    //   4. Project listings (statuses, labels)
-    //   5. Bulk writes (patch, move, close, comment, assign, unassign)
-    //   6. Docs-AI (ask, ingest-url, ingest-file)
-    //   7. Attachments (attach-to-ticket)
-    //   8. Re-parenting (set-parent - symmetric to set_milestone)
     reg('orboto_whoami', whoamiToolConfig, makeWhoamiHandler(client));
     reg('orboto_claim', claimToolConfig, makeClaimHandler(client));
     reg('orboto_unclaim', unclaimToolConfig, makeUnclaimHandler(client));
-    // ORB-1910 - feedback / bug report to the operator through the tenant relay.
     reg('orboto_report_feedback', reportFeedbackToolConfig, makeReportFeedbackHandler(client));
-    // ORB-1223 - approval / sign-off gates.
     reg('orboto_list_approvals', listApprovalsToolConfig, makeListApprovalsHandler(client));
     reg('orboto_approval_decide', approvalDecideToolConfig, makeApprovalDecideHandler(client));
-    // ORB-1615 - structural review policy: fingerprint, consult-before-invoking
-    // policy check, and recording a review decision. Rule CONFIGURATION stays
-    // out of MCP (project-settings admin, same as approval-policy CRUD above).
     reg('orboto_review_fingerprint', reviewFingerprintToolConfig, makeReviewFingerprintHandler(client));
     reg('orboto_review_policy_check', reviewPolicyCheckToolConfig, makeReviewPolicyCheckHandler(client));
     reg('orboto_review_approval_record', reviewApprovalRecordToolConfig, makeReviewApprovalRecordHandler(client));
@@ -483,8 +325,6 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_bulk_patch_tickets', bulkPatchTicketsToolConfig, makeBulkPatchTicketsHandler(client));
     reg('orboto_bulk_move_tickets', bulkMoveTicketsToolConfig, makeBulkMoveTicketsHandler(client));
     reg('orboto_bulk_close_tickets', bulkCloseTicketsToolConfig, makeBulkCloseTicketsHandler(client));
-    // ORB-1694 - the two longest measured consecutive-call runs (create 49x,
-    // add_dependency 27x) collapse into one call each.
     reg('orboto_bulk_create_tickets', bulkCreateTicketsToolConfig, makeBulkCreateTicketsHandler(client));
     reg('orboto_bulk_add_ticket_dependencies', bulkAddTicketDependenciesToolConfig, makeBulkAddTicketDependenciesHandler(client));
     reg('orboto_bulk_comment_tickets', bulkCommentTicketsToolConfig, makeBulkCommentTicketsHandler(client));
@@ -499,17 +339,12 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_create_project', createProjectToolConfig, makeCreateProjectHandler(client));
     reg('orboto_archive_project', archiveProjectToolConfig, makeArchiveProjectHandler(client));
     reg('orboto_check_similar', checkSimilarToolConfig, makeCheckSimilarHandler(client));
-    // ORB-1609 - work sessions: the lease/timer/presence/evidence record.
     reg('orboto_work_session_start', workSessionStartToolConfig, makeWorkSessionStartHandler(client));
-    // ORB-1611 - the one-call bundled pickup: acquire + full context bundle.
     reg('orboto_work_start', workStartToolConfig, makeWorkStartHandler(client));
     reg('orboto_work_session_finish', workSessionFinishToolConfig, makeWorkSessionFinishHandler(client));
-    // ORB-1612 - the one-call bundled exit: finish + ticket transition + note.
     reg('orboto_work_finish', workFinishToolConfig, makeWorkFinishHandler(client));
-    // ORB-1613 - collision-aware dispatch pull for worker pools.
     reg('orboto_work_next', workNextToolConfig, makeWorkNextHandler(client));
     reg('orboto_work_sessions', workSessionsToolConfig, makeWorkSessionsHandler(client));
-    // ORB-1610 - resource claims: path globs + named exclusive resources.
     reg('orboto_work_session_claims_add', workSessionClaimsAddToolConfig, makeWorkSessionClaimsAddHandler(client));
     reg('orboto_work_session_claims_release', workSessionClaimsReleaseToolConfig, makeWorkSessionClaimsReleaseHandler(client));
     reg('orboto_admin_translation_list', listAdminTranslationsToolConfig, makeListAdminTranslationsHandler(client));
@@ -517,23 +352,12 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_admin_translation_revert', revertTranslationToolConfig, makeAdminRevertTranslationHandler(client));
     reg('orboto_admin_agent_drift_list', listAgentDriftToolConfig, makeListAgentDriftHandler(client));
     reg('orboto_admin_agent_drift_resolve', resolveAgentDriftToolConfig, makeResolveAgentDriftHandler(client));
-    // ORB-310 Phase D - read-only `orboto://…` URI resources +
-    // task-shaped Prompt templates the MCP client offers in its UI.
     registerOrbotoResources(server, client);
     registerOrbotoPrompts(server);
-    // ORB-940 - resources/subscribe + resources/unsubscribe. The Set
-    // is shared by reference with the transport's event-bridge, which
-    // is the actual sender of `notifications/resources/updated`. We
-    // resolve immediately with an empty result either way - the spec
-    // allows that, and the bridge does the real work.
     if (opts.subscriptions) {
         const subs = opts.subscriptions;
         server.server.setRequestHandler(SubscribeRequestSchema, async (req) => {
             subs.add(req.params.uri);
-            // ORB-940 follow-up - stderr-log every subscribe/unsubscribe so
-            // operators can see in the MCP container log whether the AI
-            // client actually opts into live updates (vs. just reading the
-            // resource once). Diagnostic only - never throw from here.
             try {
                 process.stderr.write(`[orboto-mcp] subscribe → ${req.params.uri} (total subs: ${subs.size})\n`);
             }

package/dist/session-nudge.js

@@ -52,15 +52,6 @@ export const SESSION_START_GATE_MESSAGE = 'This workspace requires you to load i
  * Advance the gate state for one dispatch and report whether this
  * dispatch must be REFUSED (returned an instructive error without running the
  * handler).
- *
- * Semantics when the gate is enabled: every tool call other than
- * `orboto_session_start` is refused until `orboto_session_start` has run once
- * this session. A rule refresh locks the session until its result succeeds
- * (and is itself never gated). When the gate is disabled, nothing is ever
- * refused (returns false) - default behaviour is unchanged.
- *
- * The metrics wrapper records successful completion separately; dispatch
- * alone is not evidence of rule delivery.
  */
 export function shouldGate(state, toolName) {
     if (toolName === SESSION_START_TOOL) {

package/dist/session-nudge.test.js

@@ -11,7 +11,6 @@ describe('shouldNudge (ORB-1331)', () => {
     it('nudges on the first tool call when it is not session_start, then never again', () => {
         const state = createNudgeState();
         expect(shouldNudge(state, 'orboto_list_projects')).toBe(true);
-        // Every subsequent call is clean regardless of tool.
         expect(shouldNudge(state, 'orboto_get_ticket')).toBe(false);
         expect(shouldNudge(state, 'orboto_list_projects')).toBe(false);
         expect(shouldNudge(state, SESSION_START_TOOL)).toBe(false);
@@ -19,14 +18,12 @@ describe('shouldNudge (ORB-1331)', () => {
     it('never nudges when the first call IS session_start', () => {
         const state = createNudgeState();
         expect(shouldNudge(state, SESSION_START_TOOL)).toBe(false);
-        // and does not resurface on later calls either.
         expect(shouldNudge(state, 'orboto_list_projects')).toBe(false);
     });
     it('isolates state between sessions/processes (each fresh state nudges once)', () => {
         const a = createNudgeState();
         const b = createNudgeState();
         expect(shouldNudge(a, 'orboto_list_projects')).toBe(true);
-        // b is untouched by a - its own first call still nudges.
         expect(shouldNudge(b, 'orboto_list_projects')).toBe(true);
         expect(shouldNudge(a, 'orboto_list_projects')).toBe(false);
         expect(shouldNudge(b, 'orboto_list_projects')).toBe(false);
@@ -34,21 +31,18 @@ describe('shouldNudge (ORB-1331)', () => {
 });
 describe('shouldGate (ORB-1471)', () => {
     it('never gates when the gate is disabled (default), whatever the tool', () => {
-        const state = createNudgeState(); // gateEnabled defaults false
+        const state = createNudgeState();
         expect(shouldGate(state, 'orboto_list_projects')).toBe(false);
         expect(shouldGate(state, 'orboto_create_ticket')).toBe(false);
         expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
     });
     it('when enabled, refuses every non-session-start tool until session_start runs', () => {
         const state = createNudgeState(true);
-        // Pre session_start: every other tool is gated.
         expect(shouldGate(state, 'orboto_list_projects')).toBe(true);
         expect(shouldGate(state, 'orboto_create_ticket')).toBe(true);
-        // Dispatch is not proof of delivery; only successful completion unlocks.
         expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
         expect(shouldGate(state, 'orboto_list_projects')).toBe(true);
         recordSessionStartResult(state, SESSION_START_TOOL, true);
-        // Post session_start: everything passes.
         expect(shouldGate(state, 'orboto_list_projects')).toBe(false);
         expect(shouldGate(state, 'orboto_create_ticket')).toBe(false);
     });
@@ -76,7 +70,7 @@ describe('SESSION_START_NUDGE text (ORB-1331)', () => {
     it('is English, ASCII-only, and free of em/en-dashes', () => {
         // eslint-disable-next-line no-control-regex
         expect(/^[\x00-\x7F]*$/.test(SESSION_START_NUDGE)).toBe(true);
-        expect(SESSION_START_NUDGE).not.toMatch(/[\u2013\u2014]/); // en/em dash
+        expect(SESSION_START_NUDGE).not.toMatch(/[\u2013\u2014]/);
         expect(SESSION_START_NUDGE).toContain('orboto_session_start');
     });
 });
@@ -90,9 +84,7 @@ describe('prependNudge (ORB-1331)', () => {
         expect(out.content).toHaveLength(2);
         expect(out.content[0]).toEqual({ type: 'text', text: SESSION_START_NUDGE });
         expect(out.content[1]).toEqual({ type: 'text', text: 'tool output' });
-        // structuredContent consumers are unaffected - same reference-equal payload.
         expect(out.structuredContent).toBe(original.structuredContent);
-        // input is not mutated.
         expect(original.content).toHaveLength(1);
     });
     it('preserves isError on an error result', () => {

package/dist/session-nudge.transport.test.js

@@ -1,30 +1,11 @@
 /**
  * ORB-1331 - end-to-end transport proof of the session-start nudge.
- *
- * Drives the REAL server (buildOrbotoMcpServer → registerWithMetrics →
- * withMetrics → prependNudge) over an in-memory MCP transport with a
- * genuine MCP Client, so the whole JSON-RPC dispatch path is exercised,
- * not just the helper in isolation.
- *
- * Transport semantics both reduce to the lifetime of the per-build nudge
- * state:
- *   - HTTP: the transport calls buildOrbotoMcpServer once PER SESSION, so
- *     each session is an independent server instance with its own state.
- *   - stdio: buildOrbotoMcpServer is called once PER PROCESS, so a single
- *     server instance's state is process-local.
- * We model a "session"/"process" as one built server + one connected
- * client, and assert the nudge fires exactly once on the first non-
- * session_start call and never when the first call is session_start.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { buildOrbotoMcpServer } from './server.js';
 import { SESSION_START_NUDGE } from './session-nudge.js';
-// Every API call the tools make resolves to a benign empty payload so
-// the handlers succeed without a live backend. list_projects → [] →
-// "no projects" text + valid structuredContent; session_start's sub-
-// rules read is required and carries an explicit valid empty ruleset.
 function mockApi() {
     vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => ({
         ok: true,
@@ -76,7 +57,6 @@ describe('ORB-1331 - HTTP transport (per-session nudge)', () => {
         const client = await connectSession();
         const first = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
         expect(firstText(first)).toContain(SESSION_START_NUDGE);
-        // structuredContent must be untouched by the text-block prepend.
         expect(first.structuredContent).toMatchObject({ projects: [], total: 0 });
         const second = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
         expect(firstText(second)).not.toContain(SESSION_START_NUDGE);
@@ -93,15 +73,12 @@ describe('ORB-1331 - HTTP transport (per-session nudge)', () => {
         const b = await connectSession();
         const aFirst = await a.callTool({ name: 'orboto_list_projects', arguments: {} });
         expect(firstText(aFirst)).toContain(SESSION_START_NUDGE);
-        // b is a distinct built server → distinct state → still nudges.
         const bFirst = await b.callTool({ name: 'orboto_list_projects', arguments: {} });
         expect(firstText(bFirst)).toContain(SESSION_START_NUDGE);
     });
 });
 describe('ORB-1331 - stdio transport (process-local nudge)', () => {
     it('fires once for the process: first non-session_start call nudged, all later calls clean', async () => {
-        // stdio builds one server per process → one nudge state reused for
-        // every call on this single connected client.
         const client = await connectSession();
         const first = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
         expect(firstText(first)).toContain(SESSION_START_NUDGE);

package/dist/tool-annotations.test.js

@@ -1,37 +1,5 @@
 /**
  * ORB-1669 - safety-annotation ratchet for the MCP tool surface.
- *
- * MCP clients use `annotations` to decide whether a tool call needs a
- * confirmation step. The hints DEFAULT badly for us: per the MCP spec a
- * tool with no annotations is read-only=false / destructive=true /
- * idempotent=false - so an unannotated read looks dangerous, and (worse,
- * because it is the silent direction) a write annotated only with
- * `{ readOnlyHint: false }` still reports destructive=true. Before this
- * ticket 90 of 168 tools carried nothing at all and `orboto_bulk_close`
- * was indistinguishable from `orboto_get_ticket`.
- *
- * This test enumerates the tools exactly as a client sees them  -
- * `tools/list` over an in-memory transport, not a source scan - and
- * fails the build on a new tool that skips its annotations. There is no
- * allowlist on purpose: unlike the dark-mode / i18n ratchets there is no
- * legitimate "sanctioned exception", every tool can answer these
- * questions.
- *
- * THE CONVENTION (apply it when you add a tool):
- *
- *   readOnlyHint: true    - performs no writes at all.
- *   destructiveHint: true - the call can DELETE or REMOVE a row, DISCARD
- *                           content, take over state owned by someone
- *                           else, or mutate many tickets at once. If ANY
- *                           argument combination can do that, the tool is
- *                           destructive - the hint is per-tool and cannot
- *                           be conditioned on a flag (this is why
- *                           `orboto_claim` is destructive: `sole=true`
- *                           strips every other assignee).
- *   destructiveHint: false- purely additive, or a reversible single-entity
- *                           field/state update.
- *   idempotentHint: true  - repeating the call with identical arguments
- *                           has no further effect.
  */
 import { describe, it, expect, beforeAll } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -48,11 +16,6 @@ function unsafeTakeoverTools(list) {
         .map((tool) => tool.name);
 }
 beforeAll(async () => {
-    // Port 1 is never listened on -> the connect-time /agent-instructions
-    // fetch fails immediately and the server falls back to its built-in
-    // rules. No network, no fixture server, no timeout.
-    // ORB-1520 made the CURATED manifest the default; the annotation contract
-    // covers every registered tool, so this ratchet lists the FULL toolset.
     const server = await buildOrbotoMcpServer({ baseUrl: 'http://127.0.0.1:1', apiKey: 'orb_test', toolset: 'full' });
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const client = new Client({ name: 'annotation-ratchet', version: '0' });
@@ -62,8 +25,6 @@ beforeAll(async () => {
 });
 describe('MCP tool safety annotations (ORB-1669)', () => {
     it('enumerates the full tool surface', () => {
-        // Guards the guard: if the in-memory handshake ever silently returns
-        // nothing, every expectation below would vacuously pass.
         expect(tools.length).toBeGreaterThan(150);
     });
     it('every tool declares annotations with an explicit readOnlyHint', () => {
@@ -74,9 +35,6 @@ describe('MCP tool safety annotations (ORB-1669)', () => {
             'Add an `annotations` block to the tool config in apps/mcp/src/tools/ - see the convention at the top of this file.').toEqual([]);
     });
     it('every write tool declares an explicit destructiveHint', () => {
-        // The load-bearing one. `{ readOnlyHint: false }` alone leaves
-        // destructiveHint defaulting to TRUE, so a harmless write advertises
-        // itself as destructive and the signal stops meaning anything.
         const offenders = tools
             .filter((t) => t.annotations?.readOnlyHint === false)
             .filter((t) => typeof t.annotations?.destructiveHint !== 'boolean')
@@ -92,10 +50,8 @@ describe('MCP tool safety annotations (ORB-1669)', () => {
     });
     it('every takeover-capable tool is a destructive write for all argument combinations', () => {
         const capable = tools.filter((tool) => Object.prototype.hasOwnProperty.call(tool.inputSchema?.properties ?? {}, 'takeover'));
-        // Pin the actual siblings so losing schema discovery cannot pass vacuously.
         expect(capable.map((tool) => tool.name)).toEqual(expect.arrayContaining(['orboto_work_start', 'orboto_work_session_start']));
         expect(unsafeTakeoverTools(tools)).toEqual([]);
-        // Reservation without a takeover path is not an account-state takeover.
         expect(tools.find((tool) => tool.name === 'orboto_work_next')?.annotations).toMatchObject({ readOnlyHint: false, destructiveHint: false });
     });
     it('the takeover ratchet catches missing, false and contradictory hints on future tools', () => {