@orboto/mcp 0.207.0 → 0.209.0

package/dist/server.js

@@ -14,6 +14,7 @@ import { aiStatusToolConfig, makeAiStatusHandler } from './tools/ai-status.js';
 import { draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler } from './tools/customer-draft.js';
 import { embeddingStatusToolConfig, makeEmbeddingStatusHandler } from './tools/embedding-status.js';
 import { aiUsageToolConfig, makeAiUsageHandler } from './tools/ai-usage.js';
+import { secretScanToolConfig, makeSecretScanHandler } from './tools/secret-scan.js';
 import { sessionStartToolConfig, makeSessionStartHandler } from './tools/session-start.js';
 import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS } from './inbox-channel.js';
 import { loadRequiredRules } from './required-rules.js';
@@ -28,6 +29,7 @@ import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools
 import { agentMessagesToolConfig, makeAgentMessagesHandler } from './tools/agent-messages.js';
 import { agentWakesToolConfig, makeAgentWakesHandler } from './tools/agent-wakes.js';
 import { sessionCheckToolConfig, makeSessionCheckHandler } from './tools/session-check.js';
+import { knowledgeAskToolConfig, makeKnowledgeAskHandler, knowledgeAddToolConfig, makeKnowledgeAddHandler } from './tools/knowledge.js';
 import { listProjectsToolConfig, makeListProjectsHandler } from './tools/list-projects.js';
 import { getProjectToolConfig, makeGetProjectHandler } from './tools/get-project.js';
 import { projectReadinessToolConfig, makeProjectReadinessHandler } from './tools/project-readiness.js';
@@ -45,7 +47,7 @@ import { queryToolConfig, makeQueryHandler } from './tools/query.js';
 import { customerReportToolConfig, makeCustomerReportHandler } from './tools/customer-report.js';
 import { requirementsSpecToolConfig, makeRequirementsSpecHandler } from './tools/requirements-spec.js';
 import { specCheckToolConfig, makeSpecCheckHandler } from './tools/spec-check.js';
-import { wikiIngestUrlToolConfig, makeWikiIngestUrlHandler, wikiAskToolConfig, makeWikiAskHandler, wikiLintToolConfig, makeWikiLintHandler, wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler, wikiApplyPlanToolConfig, makeWikiApplyPlanHandler, wikiRecordToolConfig, makeWikiRecordHandler, wikiAppendSectionToolConfig, makeWikiAppendSectionHandler, wikiFlagStaleToolConfig, makeWikiFlagStaleHandler, wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler, } from './tools/wiki.js';
+import { wikiIngestUrlToolConfig, makeWikiIngestUrlHandler, wikiAskToolConfig, makeWikiAskHandler, wikiLintToolConfig, makeWikiLintHandler, wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler, wikiApplyPlanToolConfig, makeWikiApplyPlanHandler, wikiRecordToolConfig, makeWikiRecordHandler, wikiAppendSectionToolConfig, makeWikiAppendSectionHandler, wikiFlagStaleToolConfig, makeWikiFlagStaleHandler, wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler, wikiRunsToolConfig, makeWikiRunsHandler } from './tools/wiki.js';
 import { personalFactListToolConfig, makePersonalFactListHandler, personalFactAddToolConfig, makePersonalFactAddHandler, personalFactUpdateToolConfig, makePersonalFactUpdateHandler, personalFactDeleteToolConfig, makePersonalFactDeleteHandler, } from './tools/personal-facts.js';
 import { listDocSpacesToolConfig, makeListDocSpacesHandler, getDocToolConfig, makeGetDocHandler, createDocSpaceToolConfig, makeCreateDocSpaceHandler, updateDocSpaceToolConfig, makeUpdateDocSpaceHandler, deleteDocSpaceToolConfig, makeDeleteDocSpaceHandler, listDocsInSpaceToolConfig, makeListDocsInSpaceHandler, createDocToolConfig, makeCreateDocHandler, updateDocToolConfig, makeUpdateDocHandler, deleteDocToolConfig, makeDeleteDocHandler, moveDocToolConfig, makeMoveDocHandler, duplicateDocSpaceToolConfig, makeDuplicateDocSpaceHandler, resolveDocSmartLinksToolConfig, makeResolveDocSmartLinksHandler, } from './tools/docs.js';
 import { searchDocsToolConfig, makeSearchDocsHandler, editDocToolConfig, makeEditDocHandler, editDocSectionToolConfig, makeEditDocSectionHandler, } from './tools/doc-edits.js';
@@ -194,6 +196,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_draft_customer_reply', draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler(client));
     reg('orboto_embedding_status', embeddingStatusToolConfig, makeEmbeddingStatusHandler(client));
     reg('orboto_ai_usage', aiUsageToolConfig, makeAiUsageHandler(client));
+    reg('orboto_secret_scan', secretScanToolConfig, makeSecretScanHandler(client));
     reg('orboto_session_start', sessionStartToolConfig, makeSessionStartHandler(client, { channel: opts.channel }));
     reg('orboto_response_expand', responseExpandToolConfig, makeResponseExpandHandler());
     reg('orboto_help', helpToolConfig, makeHelpHandler());
@@ -211,6 +214,8 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
     reg('orboto_agent_wakes', agentWakesToolConfig, makeAgentWakesHandler(client));
     reg('orboto_session_check', sessionCheckToolConfig, makeSessionCheckHandler(client));
+    reg('orboto_knowledge_ask', knowledgeAskToolConfig, makeKnowledgeAskHandler(client));
+    reg('orboto_knowledge_add', knowledgeAddToolConfig, makeKnowledgeAddHandler(client));
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
     reg('orboto_get_project', getProjectToolConfig, makeGetProjectHandler(client));
@@ -269,6 +274,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_wiki_ingest_url', wikiIngestUrlToolConfig, makeWikiIngestUrlHandler(client));
     reg('orboto_wiki_ask', wikiAskToolConfig, makeWikiAskHandler(client));
     reg('orboto_wiki_lint', wikiLintToolConfig, makeWikiLintHandler(client));
+    reg('orboto_wiki_runs', wikiRunsToolConfig, makeWikiRunsHandler(client));
     reg('orboto_wiki_plan_update', wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler(client));
     reg('orboto_wiki_apply_plan', wikiApplyPlanToolConfig, makeWikiApplyPlanHandler(client));
     reg('orboto_wiki_record', wikiRecordToolConfig, makeWikiRecordHandler(client));

package/dist/tools/admin-translations.js

@@ -55,7 +55,7 @@ export function makeApproveTranslationHandler(client) {
 }
 export const revertTranslationToolConfig = {
     title: 'Revert an auto-translated ticket back to the original',
-    description: 'Restore the pre-translation title + description from the auto-translated audit comment and clear the auto-translate marker + any prior approval. Use when the AI got the translation wrong and the operator wants to start over. 409 if the ticket was never auto-translated. Requires `admin:translation_review`.',
+    description: 'Restore the pre-translation title + description from the audit comment and clear the auto-translate marker + prior approval. Use when the AI got the translation wrong and the operator wants to start over. 409 if the ticket was never auto-translated. Requires `admin:translation_review`.',
     inputSchema: z.object({
         ticketId: z.string().uuid().describe('UUID of the ticket to revert.'),
     }).shape,

package/dist/tools/agent-coordination.js

@@ -42,7 +42,7 @@ export function makeAgentHeartbeatHandler(client) {
 }
 export const agentPresenceToolConfig = {
     title: 'Workspace agent presence',
-    description: 'Returns all active orboto agent instances, including lane workers/reviewers, inbox and MCP connections and registered runners. Session freshness is 90 seconds; lanes retain their 300-second heartbeat grace. Unexpired work leases keep their owning instance visible. Ticket metadata and claims retain ordinary ticket visibility. Rows include `kind` (agent or human, classified by the credential: agent API key, OAuth grant, lane, external token or bot account; `isBot` is its alias), `actsAs` (the human account an AI client acts under), `projects` (memberships plus lane projects), `connections` (type + label per credential or attachment, `live_events` for the MCP event bridge), owner, lane and stable sessionId; separate instances of one account remain separate. Callers with admin:system:read see every agent; other users see only their own sessions. Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, the ticket it works on, and `reconnects` survived under the same id and scope. Check it before dispatching a sub-task so you do not step on a parallel run. Filters `projectKey` (rows whose `projects` contain the key) and `kind` (agent | human) narrow the list client-side, the same way `orboto agents --project KEY --bots|--humans` does.',
+    description: 'Returns all active orboto agent instances: lane workers/reviewers, inbox and MCP connections, registered runners. Session freshness is 90 seconds; lanes retain their 300-second heartbeat grace. Unexpired work leases keep their owning instance visible. Ticket metadata and claims retain ordinary ticket visibility. Rows include `kind` (agent or human, classified by the credential: agent API key, OAuth grant, lane, external token or bot account; `isBot` is its alias), `actsAs` (the human account an AI client acts under), `projects` (memberships plus lane projects), `connections` (type + label per credential or attachment, `live_events` for the MCP event bridge), owner, lane and stable sessionId; separate instances of one account remain separate. Callers with admin:system:read see every agent; other users see only their own sessions. Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, the ticket it works on, and `reconnects` survived under the same id and scope. Check it before dispatching a sub-task so you do not step on a parallel run. Filters `projectKey` (rows whose `projects` contain the key) and `kind` (agent | human) narrow the list client-side, the same way `orboto agents --project KEY --bots|--humans` does.',
     inputSchema: z.object({
         projectKey: z.string().min(1).max(64).optional().describe('Keep only rows whose projects contain this project key (case-insensitive).'),
         kind: AgentInventoryKindSchema.optional().describe('Keep only rows classified as agent or human by their credential.'),

package/dist/tools/agent-drift.js

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 export const listAgentDriftToolConfig = {
     title: 'List agent drift events',
-    description: 'List agent drift events (commits with no ticket key + no timer, or ticket transitions without a summary comment), newest first, with aggregate metrics. Filter by `userId`, `driftType` (untracked_commit | transition_without_summary), `from`/`to` ISO dates, and `resolved`. The response `enabled` flag is false when the operator has not turned drift detection on. Requires `admin:agent_drift:read`.',
+    description: 'List agent drift events newest first, with aggregate metrics. A drift event is a commit with no ticket key and no timer, or a ticket transition without a summary comment. Filter by `userId`, `driftType` (untracked_commit | transition_without_summary), `from`/`to` ISO dates, and `resolved`. The response `enabled` flag is false when the operator has not turned drift detection on. Requires `admin:agent_drift:read`.',
     inputSchema: z.object({
         userId: z.string().uuid().optional().describe('Filter to one user.'),
         driftType: z.enum(['untracked_commit', 'transition_without_summary']).optional(),

package/dist/tools/agent-instructions.js

@@ -18,7 +18,7 @@ function renderBlock(b) {
 }
 export const listAgentInstructionsToolConfig = {
     title: 'MANAGE the workspace coding-agent rule blocks (admin)',
-    description: 'ADMIN/MANAGEMENT tool - lists the individual rule BLOCKS at a scope (workspace: needs admin:ai:read; project: needs project:edit; personal: your own) so they can be edited/toggled/reordered. This is NOT how you read the rules to follow. To LOAD the rules you must follow as an agent, call orboto_session_start instead - it returns the complete assembled rule set.',
+    description: 'ADMIN tool: lists the rule BLOCKS at a scope for editing, not the rules to follow. Scopes: workspace needs admin:ai:read, project needs project:edit, personal is your own; blocks can be edited, toggled and reordered. This is NOT how you read the rules to follow. To LOAD the rules you must follow as an agent, call orboto_session_start instead - it returns the complete assembled rule set.',
     inputSchema: z.object({
         scope: z.enum(['workspace', 'customer', 'project', 'personal']).default('workspace'),
         projectId: z.string().uuid().optional().describe('Required for scope=project.'),
@@ -72,7 +72,7 @@ export function makeListAgentInstructionsHandler(client) {
 }
 export const createAgentInstructionToolConfig = {
     title: 'Add a custom coding-agent rule block',
-    description: 'Create a custom rule block at a scope: workspace (every agent; admin:ai:write), customer (every project of one customer; customer:write), project (one project; project:edit), or personal (your own). For scope=customer pass customerId; for scope=project pass projectId.'
+    description: 'Create a custom rule block at a scope (workspace, customer, project or personal). Workspace reaches every agent (admin:ai:write), customer every project of one customer (customer:write), project one project (project:edit), personal only you. For scope=customer pass customerId; for scope=project pass projectId.'
         + RULE_WRITING_CONTRACT,
     inputSchema: z.object({
         title: z.string().min(1).max(120),

package/dist/tools/agent-messages.js

@@ -13,7 +13,7 @@ import { mcpInstanceToken } from './shared.js';
 const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it: mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
+    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),

package/dist/tools/agent-wakes.js

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

package/dist/tools/backup.js

@@ -69,7 +69,7 @@ export function makeListBackupsHandler(client) {
 }
 export const downloadBackupToolConfig = {
     title: 'Download a stored backup run',
-    description: 'Download a stored backup run by run id (from orboto_list_backups) as a base64 resource attachment; an encrypted run downloads sealed and needs its key to restore. Requires admin:backup:read.',
+    description: 'Download a stored backup run by run id as a base64 resource attachment. The id comes from orboto_list_backups; an encrypted run downloads sealed and needs its key to restore. Requires admin:backup:read.',
     inputSchema: z.object({
         runId: z.string().uuid().describe('Backup run id from orboto_list_backups.'),
     }).shape,

package/dist/tools/bulk-create.js

@@ -22,7 +22,7 @@ const TicketDraftSchema = z.object({
 });
 export const bulkCreateTicketsToolConfig = {
     title: 'Create many tickets in one call',
-    description: 'Create up to 50 tickets in one call - the right tool whenever you are about to create more than ~3 tickets (milestone planning, epic breakdown, import). Per-draft error isolation: a rejected draft (bad label, language block, hard duplicate-block) is reported in `failed` while the rest are still created. Duplicate detection runs per draft and is reported compactly - one line per flagged draft in `duplicateFlags`; review those before treating them as new work. A call-level `milestone` / `parentTicketKey` applies to every draft unless the draft overrides it. Drafts are created in array order, so a draft can NOT reference a sibling draft as parent - create parents first (or in a first call).',
+    description: 'Create up to 50 tickets in one call. It is the right tool whenever you are about to create more than ~3 tickets (milestone planning, epic breakdown, import). Per-draft error isolation: a rejected draft (bad label, language block, hard duplicate-block) is reported in `failed` while the rest are still created. Duplicate detection runs per draft and is reported compactly - one line per flagged draft in `duplicateFlags`; review those before treating them as new work. A call-level `milestone` / `parentTicketKey` applies to every draft unless the draft overrides it. Drafts are created in array order, so a draft can NOT reference a sibling draft as parent - create parents first (or in a first call).',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key - all drafts land here.'),
         tickets: z.array(TicketDraftSchema).min(1).max(50).describe('The ticket drafts, created in order.'),
@@ -137,7 +137,7 @@ export function makeBulkCreateTicketsHandler(client) {
 }
 export const bulkAddTicketDependenciesToolConfig = {
     title: 'Add many ticket dependencies in one call',
-    description: 'Create up to 200 blocked-by edges in one call - use instead of repeated orboto_add_ticket_dependency whenever wiring more than ~3 edges (dependency graphs after a bulk create). Each pair is (ticketKey, dependsOnKey) = "ticket is blocked by dependsOn". Per-pair error isolation; an already-existing edge counts as ok, a cycle rejection lands in `failed` with the API\'s reason.',
+    description: 'Create up to 200 blocked-by edges in one call. Use it instead of repeated orboto_add_ticket_dependency whenever wiring more than ~3 edges (dependency graphs after a bulk create). Each pair is (ticketKey, dependsOnKey) = "ticket is blocked by dependsOn". Per-pair error isolation; an already-existing edge counts as ok, a cycle rejection lands in `failed` with the API\'s reason.',
     inputSchema: z.object({
         pairs: z.array(z.object({
             ticketKey: z.string().min(3).describe('The blocked ticket.'),

package/dist/tools/bulk-writes.js

@@ -140,7 +140,7 @@ export function makeBulkPatchTicketsHandler(client) {
 }
 export const bulkMoveTicketsToolConfig = {
     title: 'Move many tickets to a status category',
-    description: 'Move every ticket in `ticketKeys` (or the tickets `query` selects) to the same status category (todo / in_progress / in_review / done / wont_fix). Each ticket lands on its own project\'s first status with that category. Returns the per-ticket outcome.',
+    description: 'Move every ticket in `ticketKeys` (or `query` selects) to the same status category (todo/in_progress/in_review/done/wont_fix). Each ticket lands on its own project\'s first status with that category. Returns the per-ticket outcome.',
     inputSchema: z.object({
         ticketKeys: TICKET_KEY_ARRAY,
         query: QUERY_SOURCE,
@@ -173,7 +173,7 @@ export function makeBulkMoveTicketsHandler(client) {
 }
 export const bulkCloseTicketsToolConfig = {
     title: 'Close many tickets (optionally with a shared comment)',
-    description: 'For every ticket in `ticketKeys` (or the tickets `query` selects): optionally post the same `comment` first, then move it to `done`. Mirrors `orboto.mjs bulk-close`. Comment-first ordering means the close note lands in the audit trail even if the status PATCH 403s.',
+    description: 'For every ticket in `ticketKeys` (or `query` selects): optionally post the same `comment` first, then move to `done`. Mirrors `orboto.mjs bulk-close`. Comment-first ordering means the close note lands in the audit trail even if the status PATCH 403s.',
     inputSchema: z.object({
         ticketKeys: TICKET_KEY_ARRAY,
         query: QUERY_SOURCE,
@@ -261,7 +261,7 @@ async function makeAssigneeResolver(client, email) {
 }
 export const bulkAssignTicketsToolConfig = {
     title: 'Assign the same user to many tickets',
-    description: 'POST `assigneeEmail` as an additional assignee on every ticket in `ticketKeys` (or the tickets `query` selects). Multi-assignee is supported - this adds, it does not replace. Idempotent: a 409 (already assigned) counts as success.',
+    description: 'POST `assigneeEmail` as an additional assignee on every ticket in `ticketKeys` (or `query` selects). Multi-assignee: this adds, never replaces. Idempotent: a 409 (already assigned) counts as success.',
     inputSchema: z.object({
         ticketKeys: TICKET_KEY_ARRAY,
         query: QUERY_SOURCE,
@@ -304,7 +304,7 @@ export function makeBulkAssignTicketsHandler(client) {
 }
 export const bulkUnassignTicketsToolConfig = {
     title: 'Unassign the same user from many tickets',
-    description: 'DELETE `assigneeEmail` from every ticket in `ticketKeys` (or the tickets `query` selects). Idempotent: a 404 (was not assigned) counts as success.',
+    description: 'DELETE `assigneeEmail` from every ticket in `ticketKeys` (or `query` selects). Idempotent: a 404 (was not assigned) counts as success.',
     inputSchema: z.object({
         ticketKeys: TICKET_KEY_ARRAY,
         query: QUERY_SOURCE,

package/dist/tools/check-similar.js

@@ -6,7 +6,7 @@ import { trimSimilarEntries } from './similar-projection.js';
 import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
 export const checkSimilarToolConfig = {
     title: 'Check for similar tickets before creating',
-    description: 'Run the duplicate-detection pipeline (tsvector + AI-embedding rerank when configured) against a proposed title + description, without creating anything. Returns up to `limit` candidates ranked by similarity. Use this BEFORE `orboto_create_ticket` when you want to confirm a feature is not already tracked - if a high-similarity candidate exists, prefer to comment on / claim / extend it instead of opening a new ticket. Empty result = safe to create. `orboto_create_ticket` runs the same check after the fact and surfaces `similarWarnings` in its response, so this tool is optional but cheaper than a create-then-close round trip. Only an AI-embedding candidate carries an absolute similarity; a full-text candidate prints as "text match" without a percentage (its rank is relative, so the best text match always scores 1.000) and can never trigger the hard duplicate-block, and neither can a match against a CLOSED ticket (ORB-2185). An empty result from a LONG, solution-framed title is weak evidence - detection ranks by term co-occurrence, so also probe with a single distinctive STABLE token (file/component/error-string fragment) and the SYMPTOM wording, not just your intended fix.',
+    description: 'Run the duplicate check against a proposed title + description without creating anything. The pipeline is tsvector plus an AI-embedding rerank when configured. Returns up to `limit` candidates ranked by similarity. Use this BEFORE `orboto_create_ticket` when you want to confirm a feature is not already tracked - if a high-similarity candidate exists, prefer to comment on / claim / extend it instead of opening a new ticket. Empty result = safe to create. `orboto_create_ticket` runs the same check after the fact and surfaces `similarWarnings` in its response, so this tool is optional but cheaper than a create-then-close round trip. Only an AI-embedding candidate carries an absolute similarity; a full-text candidate prints as "text match" without a percentage (its rank is relative, so the best text match always scores 1.000) and can never trigger the hard duplicate-block, and neither can a match against a CLOSED ticket (ORB-2185). An empty result from a LONG, solution-framed title is weak evidence - detection ranks by term co-occurrence, so also probe with a single distinctive STABLE token (file/component/error-string fragment) and the SYMPTOM wording, not just your intended fix.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
         title: z.string().min(1).describe('Proposed ticket title.'),

package/dist/tools/customer-draft.js

@@ -11,7 +11,7 @@ import { z } from 'zod';
 import { resolveTicketByKey } from './shared.js';
 export const draftCustomerReplyToolConfig = {
     title: 'Draft a customer-facing reply for a ticket',
-    description: 'Draft a reply or status update for a CUSTOMER / external reader about a ticket (by key), built server-side from customer-safe facts only (key, title, status, due date, customer summary, non-internal comments, your `ask`) - never from internal notes. Returns the draft, the facts used and what was excluded. Never posts: show it to the user, then `orboto_comment` only after approval. Use it for every customer-facing text.',
+    description: 'Draft a customer-facing reply about a ticket (by key). It is built server-side from customer-safe facts only (key, title, status, due date, customer summary, non-internal comments, your `ask`) - never from internal notes. Returns the draft, the facts used and what was excluded. Never posts: show it to the user, then `orboto_comment` only after approval. Use it for every customer-facing text.',
     inputSchema: z.object({
         ticketKey: z.string().describe('Ticket key like "ORB-42".'),
         ask: z.string().min(3).max(1000).describe('What the reply should do, in the user\'s words, e.g. "tell them the fix ships with the next release" or "ask for the browser version".'),

package/dist/tools/doc-attachments.js

@@ -37,7 +37,7 @@ function isImage(mimetype) {
 }
 export const uploadDocAttachmentToolConfig = {
     title: 'Upload an attachment to a doc page',
-    description: 'Upload a file as an attachment on a wiki doc and return its Markdown image (or link) line + the stable download URL. Bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the doc body to append the Markdown line - useful for dropping a screenshot into a page in one call. MIME / extension policy is enforced server-side: blocked types (HTML, SVG, executables) surface a 415.',
+    description: 'Upload a file as a doc attachment: returns its Markdown image (or link) line + a stable download URL. Bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the doc body to append the Markdown line - useful for dropping a screenshot into a page in one call. MIME / extension policy is enforced server-side: blocked types (HTML, SVG, executables) surface a 415.',
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
         filename: z.string().min(1).describe('Display filename, e.g. "architecture-diagram.png".'),

package/dist/tools/doc-edits.js

@@ -167,7 +167,7 @@ export function makeEditDocHandler(client) {
 }
 export const editDocSectionToolConfig = {
     title: 'Edit a doc section by heading path (context-efficient)',
-    description: 'Change a doc by markdown-heading-addressed section operations - ship only the new section content, not the whole doc. A section is addressed by its heading path (e.g. ["Setup","Credentials"] = a "Credentials" heading nested under "Setup"). Heading matching is EXACT + case-sensitive; the leading path elements must be an ordered ancestor chain (not necessarily immediate parents). op=replace swaps the section body, op=append adds to its end, op=insertAfter inserts directly below the heading line (the heading line itself is never removed). A path that matches zero or multiple headings returns a 409 you can act on (narrow the path to disambiguate). Prefer this over orboto_update_doc for section-scoped rewrites. baseRevisionId gives optimistic concurrency. Returns a short context window per op.',
+    description: 'Change a doc by heading-addressed section ops - ship only the new section content, not the whole doc. A section is addressed by its heading path (e.g. ["Setup","Credentials"] = a "Credentials" heading nested under "Setup"). Heading matching is EXACT + case-sensitive; the leading path elements must be an ordered ancestor chain (not necessarily immediate parents). op=replace swaps the section body, op=append adds to its end, op=insertAfter inserts directly below the heading line (the heading line itself is never removed). A path that matches zero or multiple headings returns a 409 you can act on (narrow the path to disambiguate). Prefer this over orboto_update_doc for section-scoped rewrites. baseRevisionId gives optimistic concurrency. Returns a short context window per op.',
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable key (ORB-D12 / DOC-5). Find via orboto_search_docs.'),
         sectionOps: z.array(z.object({

package/dist/tools/doc-export.js

@@ -27,7 +27,7 @@ export function makeExportDocMdHandler(client) {
 }
 export const exportDocPdfToolConfig = {
     title: 'Export a doc page as PDF',
-    description: 'Render the doc page to PDF via the workspace\'s PdfService (Puppeteer-backed) and return the bytes as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
+    description: 'Render the doc page to PDF (Puppeteer-backed PdfService) and return the bytes as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
     }).shape,

package/dist/tools/docs.js

@@ -216,7 +216,7 @@ export function makeDeleteDocSpaceHandler(client) {
 }
 export const listDocsInSpaceToolConfig = {
     title: 'List docs inside a space',
-    description: 'Return the flat list of doc pages in a space - each carries `parentDocId` so the caller can reconstruct the tree client-side. Use this when an agent needs to find a doc by title rather than asking for a UUID first. Pair with orboto_get_doc to read individual page bodies.',
+    description: 'Return the flat list of doc pages in a space - each carries `parentDocId` to reconstruct the tree client-side. Use this when an agent needs to find a doc by title rather than asking for a UUID first. Pair with orboto_get_doc to read individual page bodies.',
     inputSchema: z.object({
         spaceId: z.string().min(1).describe('Space key (e.g. ORB-S1), name, or UUID. Discover via orboto_list_doc_spaces.'),
     }).shape,
@@ -436,7 +436,7 @@ export function makeDuplicateDocSpaceHandler(client) {
 }
 export const resolveDocSmartLinksToolConfig = {
     title: 'Batch-resolve smart-link references to display metadata',
-    description: 'Resolve `[[doc:UUID]]` / `[[ticket:UUID]]` / `[[milestone:UUID]]` / `[[project:UUID]]` / commit-hash references to their current title + URL. Visibility-filtered - items the caller is not allowed to see come back as missing (the rendering frontend falls back to the literal label in that case). Useful when reading a doc body that contains many tokens and you want to display them with current titles in one round-trip rather than N+1 get-* calls. Max 200 items per call.',
+    description: 'Resolve `[[doc:UUID]]`/`[[ticket:UUID]]`/`[[milestone:UUID]]`/`[[project:UUID]]`/commit-hash references to their title + URL. Visibility-filtered - items the caller is not allowed to see come back as missing (the rendering frontend falls back to the literal label in that case). Useful when reading a doc body that contains many tokens and you want to display them with current titles in one round-trip rather than N+1 get-* calls. Max 200 items per call.',
     inputSchema: z.object({
         items: z.array(z.object({
             type: z.enum(['doc', 'ticket', 'milestone', 'project', 'commit']),

package/dist/tools/get-project-primer.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
 export const getProjectPrimerToolConfig = {
     title: 'Get project primer (AI Context Pack)',
-    description: 'Returns the project\'s auto-generated session primer in a single call: the project vocabulary a create has to get right (ticket type enum, the project\'s labels, its status names per category, its open milestone keys), active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
+    description: 'Returns the project\'s auto-generated session primer in one call. It carries the project vocabulary a create has to get right (ticket type enum, the project\'s labels, its status names per category, its open milestone keys), active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, the Knowledge block (the index of the project wiki and of the Operations wiki, their latest log entries and open lint issues), and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, case-insensitive.'),
         maxTokens: z.number().int().positive().max(200000).optional()

package/dist/tools/help.js

@@ -15,7 +15,7 @@ import { onboardingText } from '../agent-head.js';
 const TOPICS = { connect: connectScriptText, onboarding: onboardingText };
 export const helpToolConfig = {
     title: 'Full guidance for one orboto tool',
-    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up, topic: "onboarding" the first five minutes and the work loop.',
+    description: 'Return the complete guidance text for one orboto tool by name. Manifest descriptions are one-line summaries; this adds the workflows, warnings and edge cases. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up, topic: "onboarding" the first five minutes and the work loop.',
     inputSchema: z.object({
         tool: z.string().min(1).max(128).optional().describe('Tool name, e.g. orboto_create_ticket.'),
         topic: z.enum(['connect', 'onboarding']).optional().describe('Guidance topic instead of a tool.'),

package/dist/tools/identity.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const whoamiToolConfig = {
     title: 'Show the authenticated MCP principal',
-    description: 'Return the authenticated user record `{id, email, fullName, isBot, workspaceLocale}` corresponding to the API key this MCP server is running with. Useful for debugging which credential / bot identity is in use when multiple MCP configs are wired to different `orb_*` keys. **`workspaceLocale` (ORB-989)** is the language the workspace expects tickets / comments / docs in - check it before a mass-create so you write in the right language from the start instead of relying on the after-the-fact language-mismatch warning.',
+    description: 'Return the authenticated user record `{id, email, fullName, isBot, workspaceLocale}` for the API key this server runs with. Useful for debugging which credential / bot identity is in use when multiple MCP configs are wired to different `orb_*` keys. **`workspaceLocale` (ORB-989)** is the language the workspace expects tickets / comments / docs in - check it before a mass-create so you write in the right language from the start instead of relying on the after-the-fact language-mismatch warning.',
     inputSchema: z.object({}).shape,
     outputSchema: z.object({
         id: z.string(),

package/dist/tools/knowledge.js

@@ -0,0 +1,35 @@
+/** ORB-2225 - the wiki as the agents' knowledge base: ask it first, file durable facts in it. */
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+export const knowledgeAskToolConfig = {
+    title: 'Ask the wiki',
+    description: 'Ask your session\'s project wikis and the Operations wiki before asking a person; cite docs by key.',
+    inputSchema: z.object({ question: z.string().min(3).max(1000), projectKeys: z.array(z.string().min(1).max(32)).max(20).optional() }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeKnowledgeAskHandler(client) {
+    return async (input, extra) => {
+        const res = await client.post('/knowledge/ask', input, { instanceToken: mcpInstanceToken(undefined, extra) });
+        const where = res.spaces.map((s) => s.spaceKey ?? s.spaceName).join(', ');
+        const cites = res.citations.map((c) => `[${c.index}] ${c.title} - ${c.link}`).join('\n');
+        return {
+            content: [{ type: 'text', text: [res.answer, cites ? `Sources:\n${cites}` : '', `Asked: ${where}.`].filter(Boolean).join('\n\n') }],
+            structuredContent: res,
+        };
+    };
+}
+export const knowledgeAddToolConfig = {
+    title: 'File a fact in the wiki',
+    description: 'File a durable fact in a project wiki (projectKey) or the Operations wiki, never only in local memory.',
+    inputSchema: z.object({
+        title: z.string().min(1).max(200), content: z.string().min(1).max(50_000),
+        projectKey: z.string().min(1).max(32).optional(), operations: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeKnowledgeAddHandler(client) {
+    return async (input, extra) => {
+        const res = await client.post('/knowledge/add', input, { instanceToken: mcpInstanceToken(undefined, extra) });
+        return { content: [{ type: 'text', text: res.text }], structuredContent: res };
+    };
+}

package/dist/tools/knowledge.test.js

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient as RealClient } from '../orboto-client.js';
+import { knowledgeAddToolConfig, knowledgeAskToolConfig, makeKnowledgeAddHandler, makeKnowledgeAskHandler } from './knowledge.js';
+import { KNOWLEDGE_BLOCK_CHARS, knowledgeLines, makeSessionStartHandler } from './session-start.js';
+import { makeResponseExpandHandler } from './response-expand.js';
+import { makeWikiRunsHandler } from './wiki.js';
+function textOf(result) {
+    return result.content[0].text;
+}
+afterEach(() => { vi.restoreAllMocks(); });
+describe('ORB-2225 orboto_knowledge_ask and orboto_knowledge_add', () => {
+    it('asks the scope and lists the cited docs and the asked spaces', async () => {
+        const post = vi.fn().mockResolvedValue({
+            answer: 'Nightly with restic [1].', citations: [{ index: 1, title: 'Backup chain', link: '/spaces/s/docs/d' }], mode: 'keyword', abstained: false,
+            source: 'session', spaces: [{ spaceKey: 'ACME-S1', spaceName: 'ACME', projectKey: 'ACME' }, { spaceKey: 'SPACE-3', spaceName: 'Operations', projectKey: null }],
+        });
+        const result = await makeKnowledgeAskHandler({ post })({ question: 'where does the backup run?' }, { sessionId: 'abc' });
+        expect(post).toHaveBeenCalledWith('/knowledge/ask', { question: 'where does the backup run?' }, { instanceToken: 'mcp-abc' });
+        expect(textOf(result)).toContain('[1] Backup chain - /spaces/s/docs/d');
+        expect(textOf(result)).toContain('Asked: ACME-S1, SPACE-3.');
+    });
+    it('files a fact and returns the server sentence naming where it landed', async () => {
+        const post = vi.fn().mockResolvedValue({ action: 'recorded', text: 'Recorded in the ACME-S1 wiki: ACME-D7 "Build host". Cite it by key.', pages: [], source: null });
+        const result = await makeKnowledgeAddHandler({ post })({ title: 'Build host', content: 'build.example.org', projectKey: 'ACME' });
+        expect(post.mock.calls[0][0]).toBe('/knowledge/add');
+        expect(textOf(result)).toContain('ACME-D7');
+        expect(result.structuredContent).toMatchObject({ action: 'recorded' });
+    });
+    it('both tools carry a title and annotations; ask is read-only, add is not', () => {
+        expect(knowledgeAskToolConfig.title).toBeTruthy();
+        expect(knowledgeAskToolConfig.annotations.readOnlyHint).toBe(true);
+        expect(knowledgeAddToolConfig.title).toBeTruthy();
+        expect(knowledgeAddToolConfig.annotations.readOnlyHint).toBe(false);
+    });
+});
+describe('ORB-2225 the Knowledge block of orboto_session_start', () => {
+    it('prints the block from GET /knowledge with the session header', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            const headers = new Headers(init?.headers);
+            seen.push({ path: u.pathname, session: headers.get('x-orboto-agent-session') });
+            const body = u.pathname === '/agent-instructions' ? { instructions: 'claim -> commit -> close', rulesHash: 'fixture' } : u.pathname === '/knowledge'
+                ? { source: 'session', spaces: [{ spaceKey: 'ACME-S1', spaceName: 'ACME', projectKey: 'ACME', pages: 3, sources: 1, openLintIssues: 0, indexDoc: { key: 'ACME-D1' } }], missing: [], text: '## Knowledge\nIndex ACME-D1:\n- Build host' }
+                : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const client = new RealClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+        const result = await makeSessionStartHandler(client)({}, { sessionId: 'k1' });
+        expect(seen.find((c) => c.path === '/knowledge')?.session).toBe('mcp-k1');
+        expect(textOf(result)).toContain('## Knowledge\nIndex ACME-D1:\n- Build host');
+        expect(result.structuredContent).toMatchObject({ knowledge: { source: 'session', spaces: [{ spaceKey: 'ACME-S1', indexDocKey: 'ACME-D1', pages: 3 }] } });
+    });
+    it('cuts a long block at a line and serves the rest through a handle', async () => {
+        const text = ['## Knowledge', ...Array.from({ length: 200 }, (_, i) => `- ACME-D${i} Page ${i}`)].join('\n');
+        const block = knowledgeLines(text);
+        expect(block.lines.join('\n').length).toBeLessThan(KNOWLEDGE_BLOCK_CHARS + 200);
+        expect(block.lines.at(-1)).toContain(`handle: "${block.handle}"`);
+        const expanded = await makeResponseExpandHandler()({ handle: block.handle, path: 'knowledge' });
+        expect(textOf(expanded)).toContain('- ACME-D199 Page 199');
+    });
+});
+describe('ORB-2225 orboto_wiki_runs', () => {
+    it('lists the failed runs with their error and retries one by id', async () => {
+        const get = vi.fn().mockResolvedValue({ runs: [{ id: 'r1', sourceKey: 'ACME-D9', sourceTitle: 'Runner notes', status: 'failed', error: 'answer budget spent', createdAt: '2026-09-27T08:00:00Z' }] });
+        const post = vi.fn().mockResolvedValue({ runId: 'r1', status: 'applied', queued: false, error: null });
+        const handler = makeWikiRunsHandler({ get, post });
+        expect(textOf(await handler({ spaceId: 'ACME-S1', status: 'failed' }))).toContain('r1 failed ACME-D9 "Runner notes" 2026-09-27T08:00:00Z - answer budget spent');
+        expect(get).toHaveBeenCalledWith('/spaces/ACME-S1/llm-wiki/ingest-runs?status=failed');
+        expect((await handler({ spaceId: 'ACME-S1', action: 'retry' })).isError).toBe(true);
+        expect(textOf(await handler({ spaceId: 'ACME-S1', action: 'retry', runId: '11111111-0000-4000-8000-000000000000' }))).toContain('ran again: applied');
+        expect(post).toHaveBeenCalledWith('/spaces/ACME-S1/llm-wiki/ingest-runs/11111111-0000-4000-8000-000000000000/retry', {});
+    });
+});

package/dist/tools/list-git-app-installations.js

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 export const listGitAppInstallationsToolConfig = {
     title: 'List GitHub App installations',
-    description: 'Every GitHub App installation orboto knows about, across projects (super-admin): the org/user, install time and whether it is suspended.',
+    description: 'Every GitHub App installation orboto knows, across projects (super-admin): org/user, install time, suspended state.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };

package/dist/tools/primer-facts.js

@@ -53,7 +53,7 @@ function summariseFact(f) {
 }
 export const primerFactListToolConfig = {
     title: 'List structured project primer facts',
-    description: 'List structured project facts that feed the AI primer (tech stack, conventions, deployment, architecture, integrations, gotchas, commands). Use this to discover what the project has already documented before adding a new observation. Workspace-wide facts (applying to every project) are merged in by default; pass includeWorkspace=false to see only project-scoped rows.',
+    description: 'List structured project facts feeding the AI primer (stack, conventions, deployment, architecture, integrations, gotchas, commands). Use this to discover what the project has already documented before adding a new observation. Workspace-wide facts (applying to every project) are merged in by default; pass includeWorkspace=false to see only project-scoped rows.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, e.g. "ORB". Case-insensitive.'),
         category: PrimerFactCategoryEnum.optional().describe('Filter by category. Omit for all categories.'),

package/dist/tools/raci.js

@@ -60,7 +60,7 @@ export function makeRaciHandler(client) {
 }
 export const setRaciToolConfig = {
     title: 'Set a RACI role',
-    description: "Set a person's RACI role on a ticket: R (Responsible), A (Accountable, max one per ticket), C (Consulted), or I (Informed). RACI is OPT-IN per project: only use this when the project has RACI enabled (`raciEnabled` true) - do NOT suggest or set RACI on projects that haven't opted in. Resolves the user by email within the ticket's project. Requires ticket:manage_raci. A second Accountable is rejected with the current holder's name.",
+    description: "Set a person's RACI role: R (Responsible), A (Accountable, max one per ticket), C (Consulted), I (Informed). RACI is OPT-IN per project: only use this when the project has RACI enabled (`raciEnabled` true) - do NOT suggest or set RACI on projects that haven't opted in. Resolves the user by email within the ticket's project. Requires ticket:manage_raci. A second Accountable is rejected with the current holder's name.",
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key (e.g. "ORB-42").'),
         userEmail: z.string().email().describe('Email of a project member.'),

package/dist/tools/review-policy.js

@@ -52,7 +52,7 @@ export function makeReviewPolicyCheckHandler(client) {
 }
 export const reviewApprovalRecordToolConfig = {
     title: 'Record a review decision against a diff fingerprint',
-    description: 'Record your review verdict (approve/reject) against the complete version-prefixed fingerprint from orboto_review_fingerprint. A current-algorithm approval is reusable only for identical submitted diff text; even whitespace or file-order changes require a fresh review. Legacy/unversioned records remain history only. This advisory review ledger does not itself enforce ticket closure. Requires ticket:record_review_approval.',
+    description: 'Record your review verdict (approve/reject) against the version-prefixed fingerprint from orboto_review_fingerprint. A current-algorithm approval is reusable only for identical submitted diff text; even whitespace or file-order changes require a fresh review. Legacy/unversioned records remain history only. This advisory review ledger does not itself enforce ticket closure. Requires ticket:record_review_approval.',
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key, e.g. ORB-42.'),
         fingerprint: z.string().min(8).describe('From orboto_review_fingerprint.'),

package/dist/tools/secret-scan.js

@@ -0,0 +1,54 @@
+/**
+ * ORB-2229 - `orboto_secret_scan`, the admin secret scan.
+ */
+import { z } from 'zod';
+export const secretScanToolConfig = {
+    title: 'Secret scan',
+    description: 'Admin sweep for stored secret-shaped values (ORB-2229); see skill reference admin.md "Secret scan".',
+    inputSchema: z.object({
+        redact: z.boolean().optional().describe('Replace found values, purge history (default false).'),
+        limit: z.number().int().min(1).max(1000).optional().describe('Max hits (default 200).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeSecretScanHandler(client) {
+    return async (args) => {
+        const report = await client.post('/admin/content/secret-scan', {
+            redact: args.redact ?? false,
+            limit: args.limit ?? 200,
+        });
+        const lines = [];
+        const counts = Object.entries(report.scanned).map(([k, n]) => `${k} ${n}`).join(', ');
+        lines.push(`Secret scan at ${report.scannedAt} - scanned ${counts}`);
+        if (report.hits.length === 0) {
+            lines.push('No secret-shaped value found.');
+        }
+        else {
+            for (const hit of report.hits) {
+                const where = [hit.label, hit.projectKey ? `(${hit.projectKey})` : null, hit.spaceVisibility ? `[space: ${hit.spaceVisibility}]` : null].filter(Boolean).join(' ');
+                const state = hit.redacted ? ' - redacted' : '';
+                lines.push(`${hit.entity} ${where}${state}`);
+                for (const f of hit.findings) {
+                    lines.push(`    ${f.class} in ${hit.field} at line ${f.line}, column ${f.column} (${f.preview}, ${f.length} chars)`);
+                }
+            }
+            lines.push(report.redacted > 0
+                ? `Redacted ${report.redacted} rows; rotate every credential listed above.`
+                : `${report.hits.length} hits; rotate every credential listed above, then run with redact: true.`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                scannedAt: report.scannedAt,
+                scanned: report.scanned,
+                hitCount: report.hits.length,
+                redactedCount: report.redacted,
+                hits: report.hits.map((h) => ({
+                    entity: h.entity, id: h.id, label: h.label, field: h.field,
+                    projectKey: h.projectKey, spaceVisibility: h.spaceVisibility, webUrl: h.webUrl,
+                    classes: h.findings.map((f) => f.class), redacted: h.redacted,
+                })),
+            },
+        };
+    };
+}

package/dist/tools/sentry.js

@@ -9,7 +9,7 @@ import { mcpInstanceToken, resolveProjectByKey, resolveTicketByKey } from './sha
 const ACTIONS = ['list', 'health', 'connect', 'update', 'rotate_secret', 'disconnect', 'triage_lane', 'verdict'];
 export const sentryToolConfig = {
     title: 'Sentry connector',
-    description: 'Sentry connector (ORB-2123): list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md.',
+    description: 'Sentry connector (ORB-2123). Actions: list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md.',
     inputSchema: z.object({
         action: z.enum(ACTIONS),
         projectKey: z.string().min(1),

package/dist/tools/session-start.js

@@ -21,7 +21,8 @@ import { agentHeadText } from '../agent-head.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.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
-        + '**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. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136).',
+        + '**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. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136). '
+        + 'The digest also carries the Knowledge block (ORB-2225): the wiki index of your declared projects and of the Operations wiki, their latest log entries and open lint issues; ask the wiki with orboto_knowledge_ask before asking a person, file durable facts with orboto_knowledge_add.',
     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.'),
@@ -132,6 +133,30 @@ async function buildTicketBundle(client, ticketKey) {
         },
     };
 }
+/** ORB-2225 - the Knowledge block stays small; the rest is one expand away. */
+export const KNOWLEDGE_BLOCK_CHARS = 1500;
+export function knowledgeLines(text) {
+    if (text.length <= KNOWLEDGE_BLOCK_CHARS)
+        return { lines: text.split('\n') };
+    const cut = text.slice(0, KNOWLEDGE_BLOCK_CHARS);
+    const kept = cut.slice(0, Math.max(cut.lastIndexOf('\n'), 0));
+    const handle = storePayload('orboto_session_start', {
+        structuredContent: { knowledge: text }, text,
+        omitted: [{ path: 'knowledge', kind: 'string', omittedChars: text.length - kept.length }],
+    });
+    return {
+        handle,
+        lines: [...kept.split('\n'), `(Knowledge block cut at ${kept.length} of ${text.length} characters: orboto_response_expand { handle: "${handle}", path: "knowledge" }, or GET /knowledge.)`],
+    };
+}
+function knowledgeSummary(index, handle) {
+    return {
+        source: index.source,
+        spaces: index.spaces.map((s) => ({ spaceKey: s.spaceKey ?? s.spaceName, projectKey: s.projectKey, indexDocKey: s.indexDoc?.key ?? null, pages: s.pages, sources: s.sources, openLintIssues: s.openLintIssues })),
+        missing: index.missing,
+        ...(handle ? { handle } : {}),
+    };
+}
 /** ORB-2209 - a declared scope stays with the instance token; the agent declares it once per terminal. */
 export function identityLine(registration) {
     const count = registration.reconnects ?? 0;
@@ -185,7 +210,7 @@ export function makeSessionStartHandler(client, opts = {}) {
         if (input.scope === undefined && registration && !registration.scope && envProjectScope()) {
             registration = toRegistration(await declareEnvProjectScope(client, instanceToken)) ?? registration;
         }
-        const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
+        const [me, rules, assigned, timer, inboxRaw, knowledge] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
@@ -193,6 +218,9 @@ export function makeSessionStartHandler(client, opts = {}) {
             client.get('/v1/agent/messages?limit=10', { instanceToken })
                 .then((r) => (Array.isArray(r?.messages) ? r.messages : []))
                 .catch(() => []),
+            client.get('/knowledge', { instanceToken })
+                .then((r) => (typeof r?.text === 'string' && Array.isArray(r.spaces) && Array.isArray(r.missing) ? r : null))
+                .catch(() => null),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, from: m.from?.label ?? m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
@@ -267,6 +295,9 @@ export function makeSessionStartHandler(client, opts = {}) {
         }
         lines.push('', '## Timer');
         lines.push(timer?.ticketId ? `Running on ${timer.ticketKey ?? timer.ticketId} since ${timer.startedAt ?? 'earlier'}.` : 'No timer running.');
+        const knowledgeBlock = knowledge?.text ? knowledgeLines(knowledge.text) : null;
+        if (knowledgeBlock)
+            lines.push('', ...knowledgeBlock.lines);
         lines.push('', '## This session');
         const scopeText = registration?.scope
             ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
@@ -315,6 +346,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                         .filter((p) => p.connections.length > 0),
                     healthyCount: gitHealthWithConnections.reduce((n, p) => n + p.connections.filter((c) => c.healthy).length, 0),
                 },
+                ...(knowledge ? { knowledge: knowledgeSummary(knowledge, knowledgeBlock?.handle) } : {}),
                 ...(pendingMessages.length > 0 ? { pendingMessages } : {}),
                 ...(bundle ? { ticketBundle: bundle.structured } : {}),
             },

package/dist/tools/ticket-attachments.js

@@ -14,7 +14,7 @@ function isImage(mimetype) {
 }
 export const listTicketAttachmentsToolConfig = {
     title: 'List attachments on a ticket',
-    description: 'Return a ticket\'s attachments newest-first, with each attachment\'s id, filename, content type, size, and stable download URL. Use the returned id with orboto_get_attachment to actually view an image or fetch the bytes. Empty list = no attachments. Input is the ticket key like "ACME-42".',
+    description: 'Return a ticket\'s attachments newest-first: id, filename, content type, size, stable download URL. Use the returned id with orboto_get_attachment to actually view an image or fetch the bytes. Empty list = no attachments. Input is the ticket key like "ACME-42".',
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
     }).shape,
@@ -57,7 +57,7 @@ export function makeListTicketAttachmentsHandler(client) {
 }
 export const getAttachmentToolConfig = {
     title: 'View or fetch an attachment\'s bytes',
-    description: 'Fetch a single attachment by its id (from orboto_list_ticket_attachments, orboto_get_ticket, or orboto_list_doc_attachments) and return its content. For an image, the model receives an image content block so it actually SEES the screenshot, plus a text line with filename and size. For a non-image, the model gets a text block with metadata and, for small files, the base64 content; large binaries point at the skill\'s download-attachment shortcut. Works for ticket, doc, and comment attachments (the id is global). Enforces the same project/space access check as listing the attachment.',
+    description: 'Fetch an attachment by id (from orboto_list_ticket_attachments or orboto_get_ticket) and return its content. For an image, the model receives an image content block so it actually SEES the screenshot, plus a text line with filename and size. For a non-image, the model gets a text block with metadata and, for small files, the base64 content; large binaries point at the skill\'s download-attachment shortcut. Works for ticket, doc, and comment attachments (the id is global). Enforces the same project/space access check as listing the attachment.',
     inputSchema: z.object({
         attachmentId: z.string().uuid().describe('Attachment UUID from a list/get call.'),
     }).shape,

package/dist/tools/ticket-writes.js

@@ -403,7 +403,7 @@ export function makeCloseTicketHandler(client) {
 }
 export const deleteTicketToolConfig = {
     title: 'Permanently delete a ticket',
-    description: 'DESTRUCTIVE, IRREVERSIBLE hard-delete of a ticket (by key): the row and its history are gone, and a `ticket.deleted` event + webhook fire. Strongly prefer moving the ticket to `wont_fix` (orboto_move_ticket) or closing it instead - wont_fix keeps the history and analytics intact. Only hard-delete a ticket that should truly never have existed (accidental duplicate, spam). Caller must have `ticket:delete`.',
+    description: 'DESTRUCTIVE, IRREVERSIBLE hard-delete of a ticket (by key): row and history gone, a `ticket.deleted` event + webhook fire. Strongly prefer moving the ticket to `wont_fix` (orboto_move_ticket) or closing it instead - wont_fix keeps the history and analytics intact. Only hard-delete a ticket that should truly never have existed (accidental duplicate, spam). Caller must have `ticket:delete`.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
     }).shape,
@@ -719,7 +719,7 @@ export function makeRemoveTicketDependencyHandler(client) {
 }
 export const listTicketDependenciesToolConfig = {
     title: 'List a ticket\'s dependencies',
-    description: 'Show both directions of the dependency graph for a ticket: `blockedBy` (tickets that must finish first) and `blocks` (tickets waiting on this one). ORB-1614: an edge to a ticket in another project you cannot read comes back as an opaque "external dependency" entry (no title/key/status - just whether it is still open).',
+    description: 'Show both directions of a ticket\'s dependency graph: `blockedBy` (must finish first) and `blocks` (waiting on this one). ORB-1614: an edge to a ticket in another project you cannot read comes back as an opaque "external dependency" entry (no title/key/status - just whether it is still open).',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
     }).shape,

package/dist/tools/time-writes.js

@@ -165,7 +165,7 @@ export function makeListTimeEntriesHandler(client) {
 }
 export const editTimeEntryToolConfig = {
     title: 'Edit / correct a time entry',
-    description: 'Correct a time entry - fix an over-tracked duration, edit its note, change its date, or re-target it to another ticket. Use THIS (not orboto_log_time) to fix a wrong entry: log_time is additive and only makes the total worse. Get the entryId from orboto_list_time_entries (or an orboto_log_time response). Blocked if the entry is locked by an approved timesheet.',
+    description: 'Correct a time entry: fix a duration, edit its note, change its date, or re-target it to another ticket. Use THIS (not orboto_log_time) to fix a wrong entry: log_time is additive and only makes the total worse. Get the entryId from orboto_list_time_entries (or an orboto_log_time response). Blocked if the entry is locked by an approved timesheet.',
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('The ticket the entry currently belongs to.'),
         entryId: z.string().uuid(),

package/dist/tools/wiki.js

@@ -54,7 +54,7 @@ export function makeWikiAskHandler(client) {
 }
 export const wikiLintToolConfig = {
     title: 'Run the LLM-Wiki lint pass on a space',
-    description: 'Scan an LLM-Wiki space for inconsistencies (orphan pages, missing cross-references, stale pages, unprocessed sources, and - when AI is configured - contradictions and undocumented concepts). Returns the open issues, each with a suggested fix. Wraps POST /spaces/:id/llm-wiki/lint.',
+    description: 'Lint an LLM-Wiki space for inconsistencies. It finds orphan pages, missing cross-references, stale pages, unprocessed sources and, when AI is configured, contradictions and undocumented concepts. Returns the open issues, each with a suggested fix. Wraps POST /spaces/:id/llm-wiki/lint.',
     inputSchema: z.object({
         spaceId: z.string().uuid().describe('The LLM-Wiki space to lint.'),
     }).shape,
@@ -71,7 +71,7 @@ export function makeWikiLintHandler(client) {
 }
 export const wikiPlanUpdateToolConfig = {
     title: 'Plan a wiki edit (dry-run, no writes)',
-    description: 'Turn a natural-language instruction into a concrete set of page operations (create / patch / append) WITHOUT writing anything. Returns a planId valid for 15 minutes plus the proposed ops. Review the ops, then call orboto_wiki_apply_plan to commit. Wraps POST /spaces/:id/docs/plan-update.',
+    description: 'Turn a natural-language instruction into page operations (create/patch/append) WITHOUT writing anything. Returns a planId valid for 15 minutes plus the proposed ops. Review the ops, then call orboto_wiki_apply_plan to commit. Wraps POST /spaces/:id/docs/plan-update.',
     inputSchema: z.object({
         spaceId: z.string().uuid().describe('The wiki space to edit.'),
         instruction: z.string().min(1).max(4000).describe('What to change, in plain language.'),
@@ -91,7 +91,7 @@ export function makeWikiPlanUpdateHandler(client) {
 }
 export const wikiApplyPlanToolConfig = {
     title: 'Apply a previously-planned wiki edit',
-    description: 'Commit the page operations from a plan created by orboto_wiki_plan_update. Applies every op atomically (each page edit is snapshotted for rollback). Fails with 410 if the plan has expired (>15 min) or was already applied. Wraps POST /spaces/:id/docs/apply-plan.',
+    description: 'Commit the page operations from a plan created by orboto_wiki_plan_update. Applies every op atomically (each page edit is snapshotted for rollback), then rebuilds the index doc of the space and appends a line to its log doc. Fails with 410 if the plan has expired (>15 min) or was already applied. Wraps POST /spaces/:id/docs/apply-plan.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
         planId: z.string().uuid().describe('The planId returned by orboto_wiki_plan_update.'),
@@ -106,7 +106,7 @@ export function makeWikiApplyPlanHandler(client) {
 }
 export const wikiRecordToolConfig = {
     title: 'Record a wiki update in one step (plan + apply)',
-    description: 'Convenience wrapper that plans an edit from your instruction and immediately applies it - use mid-task to capture a fact or update a page without the two-step review loop. Internally calls plan-update then apply-plan. For a reviewable change, use orboto_wiki_plan_update instead.',
+    description: 'Plan and apply a wiki edit in one step. Use it mid-task to capture a fact or update a page without the two-step review loop. Internally calls plan-update then apply-plan. For a reviewable change, use orboto_wiki_plan_update instead.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
         instruction: z.string().min(1).max(4000).describe('What to record, in plain language.'),
@@ -175,3 +175,28 @@ export function makeWikiFlagStaleHandler(client) {
         return text(res.staleFlagged ? 'Page flagged as possibly outdated.' : 'Stale flag cleared.', { staleFlagged: res.staleFlagged });
     };
 }
+export const wikiRunsToolConfig = {
+    title: 'Wiki ingest runs',
+    description: 'List the ingest runs of a wiki space (status failed shows each error) or retry a failed run.',
+    inputSchema: z.object({
+        spaceId: z.string().min(1),
+        action: z.enum(['list', 'retry']).optional(),
+        runId: z.string().uuid().optional(),
+        status: z.enum(['pending_review', 'applied', 'failed', 'skipped']).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeWikiRunsHandler(client) {
+    return async (input) => {
+        if (input.action === 'retry') {
+            if (!input.runId)
+                return { isError: true, content: [{ type: 'text', text: 'action retry needs the runId of a failed run (action list, status failed).' }] };
+            const res = await client.post(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs/${input.runId}/retry`, {});
+            return text(res.queued ? `Run ${res.runId} is queued for the ingest worker again.` : `Run ${res.runId} ran again: ${res.status}${res.error ? ` - ${res.error}` : ''}.`, res);
+        }
+        const qs = input.status ? `?status=${input.status}` : '';
+        const res = await client.get(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs${qs}`);
+        const lines = res.runs.map((r) => `- ${r.id} ${r.status} ${r.sourceKey ?? ''} "${r.sourceTitle}" ${r.createdAt}${r.error ? ` - ${r.error}` : ''}`);
+        return text(lines.length ? lines.join('\n') : 'No ingest runs.', res);
+    };
+}

package/dist/tools/work-next.js

@@ -23,7 +23,7 @@ function landedIdleLines(rows) {
 }
 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.',
+    description: 'ORB-1613 - the pull side of low-management dispatch, sibling of orboto_work_start for "any ticket will do". 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()

package/dist/tools/work-sessions.js

@@ -314,7 +314,7 @@ export function makeWorkSessionStartHandler(client) {
 }
 export const workSessionFinishToolConfig = {
     title: 'Finish a work session (books time, frees the lease)',
-    description: 'End a work session: its timer is stopped and booked, the (ticket, role) lease is released for the next agent, and the evidence you pass (commit sha + which gates you ran) is recorded on the session. Idempotent - finishing an already-finished session succeeds and still absorbs late evidence, so a retrying harness never has to distinguish "already done" from "failed". This does NOT close the ticket; ticket status is a separate, deliberate decision (use orboto_close_ticket once the acceptance criteria are verified). Prefer orboto_work_finish (ORB-1612) for an `implementation` session that is actually done - it does this AND the ticket transition AND the completion note in one call.',
+    description: 'End a work session: timer booked, lease released, evidence recorded. The timer is stopped and booked, the (ticket, role) lease is released for the next agent, and the evidence you pass (commit sha + which gates you ran) is recorded on the session. Idempotent - finishing an already-finished session succeeds and still absorbs late evidence, so a retrying harness never has to distinguish "already done" from "failed". This does NOT close the ticket; ticket status is a separate, deliberate decision (use orboto_close_ticket once the acceptance criteria are verified). Prefer orboto_work_finish (ORB-1612) for an `implementation` session that is actually done - it does this AND the ticket transition AND the completion note in one call.',
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         outcome: z.enum(['finished', 'cancelled']).optional()
@@ -456,7 +456,7 @@ export function makeWorkSessionsHandler(client) {
 }
 export const workSessionClaimsAddToolConfig = {
     title: 'Add resource claims to a live work session',
-    description: 'ORB-1610 - declare more resource claims on a session you already hold (from orboto_work_session_start), without touching the ticket lease or timer. Use this when you did not know the files/resources you would touch at start time, or need to widen scope mid-task. Same conflict rule as start: `write` claims conflict with any OVERLAPPING active write claim workspace-wide; `read` claims never conflict. Default `onConflict: "reject"` fails the WHOLE call (nothing is added) and names every conflicting holder; `queue` accepts the conflicting ones as `state: "waiting"`.',
+    description: 'ORB-1610 - declare more resource claims on a session you hold, without touching the lease or timer. Use this when you did not know the files/resources you would touch at start time, or need to widen scope mid-task. Same conflict rule as start: `write` claims conflict with any OVERLAPPING active write claim workspace-wide; `read` claims never conflict. Default `onConflict: "reject"` fails the WHOLE call (nothing is added) and names every conflicting holder; `queue` accepts the conflicting ones as `state: "waiting"`.',
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         claims: z.array(z.object(ResourceClaimShape)).min(1).max(50)
@@ -501,7 +501,7 @@ export function makeWorkSessionClaimsAddHandler(client) {
 }
 export const workSessionClaimsReleaseToolConfig = {
     title: 'Release resource claims from a live work session',
-    description: 'ORB-1610 - drop specific resource claims (or all of them) from a session you hold, WITHOUT finishing the session or touching the ticket lease/timer. Releasing a granted write claim immediately runs a grant pass, so the earliest queued waiter for that resource is promoted as part of this call - useful once you know you are done touching a subtree but are not done with the ticket. Omit `claims` to release everything the session holds.',
+    description: 'ORB-1610 - drop resource claims (or all) from a session you hold, WITHOUT finishing it or touching the ticket lease/timer. Releasing a granted write claim immediately runs a grant pass, so the earliest queued waiter for that resource is promoted as part of this call - useful once you know you are done touching a subtree but are not done with the ticket. Omit `claims` to release everything the session holds.',
     inputSchema: z.object({
         sessionId: z.string().uuid().describe('The id returned by orboto_work_session_start.'),
         claims: z.array(z.object({ kind: z.enum(['path', 'named']), value: z.string().min(1).max(500) })).optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.207.0",
+  "version": "0.209.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",