charness 3.6.1 → 3.8.0

package/dist/scheduler/mcpSurface.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.answerReplyToCommentIdsMaxCount = exports.schedulerMcpPendingCancellationMax = exports.schedulerMcpPendingCancellationTtlMs = exports.schedulerMcpBindRetryDelayMs = exports.schedulerMcpBindRetryCount = exports.legacySchedulerMcpClientIdHeader = exports.schedulerMcpClientIdHeader = exports.schedulerMcpPath = exports.defaultSchedulerMcpPort = void 0;
+exports.answerReplyToCommentIdsMaxCount = exports.claudeCodeInstructionsMaxLength = exports.schedulerMcpPendingCancellationMax = exports.schedulerMcpPendingCancellationTtlMs = exports.schedulerMcpBindRetryDelayMs = exports.schedulerMcpBindRetryCount = exports.legacySchedulerMcpClientIdHeader = exports.schedulerMcpClientIdHeader = exports.schedulerMcpPath = exports.defaultSchedulerMcpPort = void 0;
 exports.buildMcpServerInstructions = buildMcpServerInstructions;
 exports.getSchedulerMcpPort = getSchedulerMcpPort;
 exports.resolveSchedulerMcpPort = resolveSchedulerMcpPort;
@@ -12,6 +12,7 @@ exports.verifySchedulerMcpToken = verifySchedulerMcpToken;
 exports.extractBearerToken = extractBearerToken;
 exports.buildBotMcpToolDigest = buildBotMcpToolDigest;
 exports.getBotMcpToolDigest = getBotMcpToolDigest;
+exports.getBotMcpToolDefinitions = getBotMcpToolDefinitions;
 exports.resolveTargetThreadKey = resolveTargetThreadKey;
 exports.buildSpecFromCreateArgs = buildSpecFromCreateArgs;
 exports.checkIsConversationInScope = checkIsConversationInScope;
@@ -23,17 +24,25 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const zod_1 = require("zod");
+const adapterNames_1 = require("../adapters/adapterNames");
 const sessionKey_1 = require("../sessionKey");
+const botSkills_1 = require("../utils/botSkills");
+const claudeProfiles_1 = require("../utils/claudeProfiles");
+const claudeUsage_1 = require("../utils/claudeUsage");
 const isoTimestamp_1 = require("../utils/isoTimestamp");
 const messageSendService_1 = require("../utils/messageSendService");
 const utils_1 = require("../utils");
 const checkRun_1 = require("./checkRun");
 const deliveryKind_1 = require("./deliveryKind");
+const workerWatch_1 = require("./workerWatch");
 const recurrence_1 = require("./recurrence");
+const strictToolInput_1 = require("./strictToolInput");
 const store_1 = require("./store");
 const legacyNames_1 = require("../legacyNames");
 const answerRequest_1 = require("../requests/answerRequest");
 const answerStyle_1 = require("../requests/answerStyle");
+const registry_1 = require("../todos/registry");
+const types_1 = require("../todos/types");
 /**
  * @description The bot-owned MCP server exposes the agent-facing tools —
  * `schedule_create`, `schedule_list`, `schedule_cancel`, `send_file_to_user`,
@@ -106,28 +115,82 @@ const schedulerMcpClientIdPattern = /^[A-Za-z0-9._:-]+$/;
 /** Server identity reported in the MCP `initialize` handshake. */
 const mcpServerName = 'telegram-bot-scheduler';
 const mcpServerVersion = '1.0.0';
+/** The skill an orchestrating agent loads in a bot session, as each CLI names it. */
+const managerSkillInstruction = 'load the `charness-manager` skill (Claude Code lists it as `charness:charness-manager`) and follow it instead of any other manager skill';
 /** The instruction bullets that hold on every platform (the two platform-neutral tools). */
-const compactConversationInstruction = '• The user EXPLICITLY asks to compact/shrink/summarize this conversation\'s context → compact_conversation. Only on an explicit request, never on your own judgement.';
-const answerRequestInstruction = '• A message carries a "[Request <id> · from: …]" header → answer it through answer_request with that id: kind "final" with the full result at the end of your turn, "question" when you need the requester before you can go on (their reply arrives as a new request), "progress" for an interim note. You may call it several times; only question/final close the request. ' +
+const compactConversationInstruction = '• The user EXPLICITLY asks to compact/shrink/summarize this conversation\'s context → compact_conversation. Never on your own judgement.';
+const answerRequestInstruction = '• A message carries a "[Request <id> · from: …]" header → answer it through answer_request with that id: kind "final" with the full result at the end of your turn, "question" when you need the requester before you can go on (their reply arrives as a new request), "progress" for an interim note. Only question/final close the request. ' +
     answerStyle_1.answerStyleInstruction;
-const claudeProfilesInstruction = '• Before you start a child `claude` process (a detached worker, reviewer, planner) → claude_profiles with the model you will launch: it lists the signed-in Claude accounts with their usage windows and names the one with the most headroom (`recommended`). Launch the child with `CLAUDE_CONFIG_DIR=<its configDir>` in its environment (nothing when configDir is null); without it the child inherits YOUR account and drains the same limits.';
-const telegramInstructions = `This MCP lets the agent act on its own Telegram topic.
+/** The shared todo registry's bullet (D7) — Telegram topics and Jira issues publish alike. */
+const todoInstruction = '• BEFORE you start any task (fixes you found yourself included: a failing test, a leak) → todo_update adds it as inWork, naming the area (files, tests). Check the returned board for overlap with other agents. Take the queue top-down; mark items done / dropped at once. A ticket you create in a tracker gets an item with its key in `ref`.';
+/** The `charness remote-run` bullet — present only while a runner is paired or listed in `runners.json`, for Telegram topics and tracker issues alike. The CLI's own `--help` has the job commands. */
+const remoteRunInstruction = '• Heavy work (test suite, build, e2e run) → send it to a runner, not this machine: `charness remote-run runners` lists them and what each can do; `charness remote-run [--needs android|ios|docker|playwright] <command>` runs it in a copy of this project and returns its output and exit code (edit files only here). Longer than your tool timeout: `charness remote-run --bg <command>`, then `charness remote-run wait <id>` in the background; `charness remote-run --help` lists the rest.';
+/**
+ * Claude Code cuts a server's connect-time `instructions` that are longer than this: whatever comes last is lost, silently. The Telegram
+ * text is within a few hundred characters of it before the remote-run bullet, so the runner lines are fitted to the room that is left.
+ */
+exports.claudeCodeInstructionsMaxLength = 4096;
+/**
+ * The remote-run bullet with one line per runner under it (`mac — macOS 15.1, android, playwright`: the name, the OS, what it could do when
+ * last probed): the first `shownCount` runners, and «… and N more» for the rest. The lines are a snapshot taken at connect; `charness
+ * remote-run runners` has the live state. `shownCount` 0 gives the bullet alone.
+ */
+function buildRemoteRunInstruction(runnerLines, shownCount) {
+    if (shownCount === 0)
+        return remoteRunInstruction;
+    const hiddenCount = runnerLines.length - shownCount;
+    return [
+        remoteRunInstruction,
+        '  Runners, as last seen:',
+        ...runnerLines.slice(0, shownCount).map((line) => `  – ${line}`),
+        ...(hiddenCount > 0 ? [`  – … and ${hiddenCount} more`] : []),
+    ].join('\n');
+}
+const orchestrationInstructionHead = '• You orchestrate detached workers (a `claude -p` / `opencode run` builder, reviewer, researcher) →';
+/** What the worker-watch recipe says once a tool is named: shared by both wordings of the Telegram bullet. */
+const workerWatchRecipeText = `its description has the recipe (checkCommand, cron, \`${workerWatch_1.workerWatchPinArgument}\`); never \`kill -0\` alone: it never fires on a hung worker.`;
+/**
+ * The orchestration bullet of a conversation on a tracker, which has no scheduling tools: only the manager-skill hint, so
+ * with the bot's skills off (`/bot_skills`) there is nothing left of it and `null` drops it.
+ */
+function buildTrackerOrchestrationInstruction(isBotSkillsEnabled) {
+    return isBotSkillsEnabled ? `${orchestrationInstructionHead} ${managerSkillInstruction}.` : null;
+}
+/** The orchestration bullet of a Telegram topic: the manager-skill hint (dropped with the skills off) and the worker-watch recipe, which is a tool fact and stays. */
+function buildTelegramOrchestrationInstruction(isBotSkillsEnabled) {
+    return isBotSkillsEnabled
+        ? `${orchestrationInstructionHead} ${managerSkillInstruction}. Watch EACH worker with schedule_create — ${workerWatchRecipeText}`
+        : `${orchestrationInstructionHead} schedule_create to watch EACH worker — ${workerWatchRecipeText}`;
+}
+const claudeProfilesInstruction = '• Before you start or resume a child `claude` process (worker, reviewer, planner) → claude_profiles with the model you will launch, and start the child under the account it names (`CLAUDE_CONFIG_DIR=<configDir>`): without it the child inherits YOUR account and drains the same limits. The tool description has the rest (resuming, `recommended: null`).';
+/** @description Which optional tools `deps` offers. */
+function getOptionalBotTools(deps) {
+    return {
+        isJiraAttachmentToolOffered: deps.fetchJiraAttachment !== undefined,
+        isTodoToolOffered: deps.todos !== undefined,
+        remoteRunRunnerLines: deps.getRemoteRunRunnerLines?.() ?? [],
+    };
+}
+function buildTelegramInstructions(isTodoToolOffered, remoteRunInstructionText, isBotSkillsEnabled) {
+    return `This MCP lets the agent act on its own Telegram topic.
 
 When to use it:
-• The user asks to run/finish a plan or task LATER ("in 2h", "tomorrow 9am", "every weekday") → schedule_create. Put the work in \`prompt\`; the future run is a fresh session with no memory of this chat. Not CronCreate / ScheduleWakeup for anything that must happen: they live only in your process, which the bot stops after a long idle stretch, and die with it.
-• You produced a file/chart/screenshot/video to deliver → send_file_to_user. Videos MUST be H.264 .mp4 sent as video (never as_file/document, never .webm/.mov — those render as GIFs or don't play); transcode first if needed (the tool description has the ffmpeg recipe).
-• You want to deliver SEVERAL discrete messages (each as its own Telegram message, e.g. a per-item news digest) → send_messages_to_user. Each item can optionally attach ONE file/photo/video (text becomes its caption).
+• The user asks to run/finish a plan or task LATER ("in 2h", "tomorrow 9am", "every weekday") → schedule_create. Put the work in \`prompt\`; the future run is a fresh session with no memory of this chat. Not CronCreate / ScheduleWakeup for anything that must happen: they die with your process, which the bot stops after a long idle stretch.
+• You produced a file/chart/screenshot/video to deliver → send_file_to_user. Videos MUST be H.264 .mp4 sent as video (never as_file/document or .webm/.mov — those render as GIFs or don't play); transcode first if needed (recipe in the tool description).
+• You want to deliver SEVERAL discrete messages (each its own message, e.g. a per-item news digest) → send_messages_to_user; an item may attach ONE file (the text becomes its caption).
 ${compactConversationInstruction}
-• You need to review or remove scheduled jobs → schedule_list / schedule_cancel.
-• You need a watchdog — keep an eye on a service, process, build, deploy, disk, URL… → schedule_create with \`checkCommand\` (cron). The bot runs the command in this folder on schedule, stays silent while it exits 0, and on the first failure pins an alert and wakes you with \`prompt\` + the exit code and output tail. Checks survive bot restarts and crashes. NEVER build your own watcher (a background loop, nohup, a sleep loop, a tmux pane, a shell crontab): it dies with your session or a restart and then fails silently.
-${answerRequestInstruction} The requester may not see your plain text, so anything they must read goes through answer_request. Your plain text is relayed into the topic too, so after answer_request end the turn WITHOUT a plain-text recap of what you answered — it would show up twice.
-${claudeProfilesInstruction}
+${isTodoToolOffered ? `${todoInstruction}\n` : ''}• You need to review or remove scheduled jobs → schedule_list / schedule_cancel.
+• You need a watchdog — keep an eye on a service, build, deploy, disk, URL… → schedule_create with \`checkCommand\` (cron): the bot runs it in this folder, stays silent while it exits 0, and on the first failure pins an alert and wakes you with \`prompt\` + the exit code and output tail. Checks survive restarts and crashes. NEVER build your own watcher (background loop, nohup, sleep loop, tmux pane, shell crontab): it dies with your session or a restart, silently.
+${buildTelegramOrchestrationInstruction(isBotSkillsEnabled)}
+${answerRequestInstruction} The requester may not see your plain text: anything they must read goes through answer_request — yet your plain text is relayed into the topic too, so end the turn WITHOUT a recap of what you answered (it would show twice).
+${claudeProfilesInstruction}${remoteRunInstructionText === null ? '' : `\n${remoteRunInstructionText}`}
 
-Each tool's own description has the exact argument recipe (one-shot vs cron vs N-times, checks).`;
+Tool descriptions hold the argument recipes.`;
+}
 /** What a Jira session's instructions add: the tool that reaches the issue's original files (C10). */
 const jiraAttachmentInstruction = '• The issue lists a file (an attachment id in the attachments list, or in a placeholder such as "[image: shot.png — attachment 10234]") you need to look at → jira_get_attachment with that id; it saves the original file and returns its path.';
 /** For a conversation on a tracker: the requester sees nothing but the answers; `extraInstructions` name the platform's own tools. */
-function buildTrackerInstructions(extraInstructions) {
+function buildTrackerInstructions(extraInstructions, isBotSkillsEnabled) {
     return `This MCP connects the agent to the conversation that asked for its work.
 
 When to use it:
@@ -136,12 +199,11 @@ ${[
         ...extraInstructions,
         compactConversationInstruction,
         claudeProfilesInstruction,
-    ].join('\n')}
+        buildTrackerOrchestrationInstruction(isBotSkillsEnabled),
+    ].filter((instruction) => instruction !== null).join('\n')}
 
 Each tool's own description has the exact argument recipe.`;
 }
-const neutralInstructions = buildTrackerInstructions([]);
-const jiraInstructions = buildTrackerInstructions([jiraAttachmentInstruction]);
 /**
  * Connect-time `instructions` returned in the MCP `initialize` handshake — a
  * short, high-level pointer the client surfaces to the agent BEFORE any call.
@@ -151,12 +213,33 @@ const jiraInstructions = buildTrackerInstructions([jiraAttachmentInstruction]);
  *
  * @description The connect-time instructions for a session of `platform`: only
  * a Telegram session has the scheduling and send-to-topic tools, so only its
- * instructions name them (Jira connector plan J2, D18).
+ * instructions name them (Jira connector plan J2, D18); an optional tool is named
+ * only where it is offered. With the bot's skills off for the session
+ * (`isBotSkillsEnabled`, `/bot_skills`) the orchestration bullet no longer tells it to load `charness-manager`.
  */
-function buildMcpServerInstructions(platform, isJiraAttachmentToolOffered = false) {
-    if (platform === 'telegram')
-        return telegramInstructions;
-    return platform === 'jira' && isJiraAttachmentToolOffered ? jiraInstructions : neutralInstructions;
+function buildMcpServerInstructions(platform, offered, isBotSkillsEnabled) {
+    const render = (remoteRunInstructionText) => {
+        if (platform === 'telegram')
+            return buildTelegramInstructions(offered.isTodoToolOffered, remoteRunInstructionText, isBotSkillsEnabled);
+        const remoteRunInstructions = remoteRunInstructionText === null ? [] : [remoteRunInstructionText];
+        if (platform !== 'jira')
+            return buildTrackerInstructions(remoteRunInstructions, isBotSkillsEnabled);
+        return buildTrackerInstructions([
+            ...(offered.isJiraAttachmentToolOffered ? [jiraAttachmentInstruction] : []),
+            ...(offered.isTodoToolOffered ? [todoInstruction] : []),
+            ...remoteRunInstructions,
+        ], isBotSkillsEnabled);
+    };
+    const runnerCount = offered.remoteRunRunnerLines.length;
+    if (runnerCount === 0)
+        return render(null);
+    // As many runners as the room under Claude Code's cap leaves; the bullet itself always stays (its `runners` command is the full list).
+    for (let shownCount = runnerCount; shownCount > 0; shownCount -= 1) {
+        const text = render(buildRemoteRunInstruction(offered.remoteRunRunnerLines, shownCount));
+        if (text.length <= exports.claudeCodeInstructionsMaxLength)
+            return text;
+    }
+    return render(buildRemoteRunInstruction(offered.remoteRunRunnerLines, 0));
 }
 /** Max characters of a free-text job name / prompt accepted by a tool (defensive bound). */
 const maxNameLength = 200;
@@ -298,15 +381,22 @@ const digestScope = { kind: 'dir', directory: '' };
  * a tool added, renamed, re-described or re-shaped changes it and nothing else
  * has to be kept in step by hand.
  */
-function getBotMcpToolDigest(deps, platform) {
+function getBotMcpToolDigest(deps, platform, isBotSkillsEnabled) {
+    return buildBotMcpToolDigest(buildMcpServerInstructions(platform, getOptionalBotTools(deps), isBotSkillsEnabled), getBotMcpToolDefinitions(deps, platform));
+}
+/**
+ * @description The tool definitions a session of `platform` gets, recorded from the SAME registration the request
+ * path runs (never a handler): what the digest hashes, and what a test reads the tools' names and descriptions from.
+ */
+function getBotMcpToolDefinitions(deps, platform) {
     const definitions = [];
     const recorder = {
         registerTool: (name, config) => {
-            definitions.push({ name, title: config.title, description: config.description, inputKeys: Object.keys(config.inputSchema ?? {}).sort() });
+            definitions.push({ name, title: config.title, description: config.description, inputKeys: Object.keys(config.inputSchema.shape).sort() });
         },
     };
     registerBotTools(recorder, deps, digestScope, platform, undefined);
-    return buildBotMcpToolDigest(buildMcpServerInstructions(platform, deps.fetchJiraAttachment !== undefined), definitions);
+    return definitions;
 }
 /**
  * @description Resolve the single thread a tool call targets, from its scope and
@@ -356,6 +446,11 @@ function resolveTargetThreadKey(scope, suppliedThreadKey, getThreadsForDirectory
     return { ok: true, threadKey: suppliedThreadKey };
 }
 // ─── tool input schemas + spec building ──────────────────────────────
+/** The optional target thread every topic-scoped tool takes (a `dir:` scope with several bound threads needs it). */
+const threadKeyArgSchema = zod_1.z
+    .string()
+    .optional()
+    .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.');
 const scheduleCreateShape = {
     name: zod_1.z.string().min(1).max(maxNameLength).describe('Short human name for the job (shown in announcements/lists).'),
     cron: zod_1.z
@@ -396,7 +491,7 @@ const scheduleCreateShape = {
         'non-zero exit or timeout pins an alert in the topic and wakes you with `prompt` plus the exit ' +
         'code and output tail; later failures stay silent until a run passes again (the topic is told). ' +
         'Keep it a quick probe, e.g. `systemctl --user is-active myapp`, `curl -fsS -m 10 http://127.0.0.1:8080/health`, ' +
-        '`test $(df --output=pcent / | tail -1 | tr -dc 0-9) -lt 90`.'),
+        '`test $(df --output=pcent / | tail -1 | tr -dc 0-9) -lt 90`; a detached worker: the recipe in the tool description.'),
     checkTimeoutSeconds: zod_1.z
         .number()
         .int()
@@ -409,24 +504,18 @@ const scheduleCreateShape = {
         .boolean()
         .optional()
         .describe('Pin the fire announcement silently (no member notification). Default false = notify all.'),
-    threadKey: zod_1.z
-        .string()
-        .optional()
-        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+    threadKey: threadKeyArgSchema,
 };
+const scheduleCreateInput = (0, strictToolInput_1.createStrictToolInput)(scheduleCreateShape);
 const scheduleListShape = {
-    threadKey: zod_1.z
-        .string()
-        .optional()
-        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+    threadKey: threadKeyArgSchema,
 };
+const scheduleListInput = (0, strictToolInput_1.createStrictToolInput)(scheduleListShape);
 const scheduleCancelShape = {
     id: zod_1.z.string().min(1).describe('The schedule id to cancel (from schedule_list).'),
-    threadKey: zod_1.z
-        .string()
-        .optional()
-        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+    threadKey: threadKeyArgSchema,
 };
+const scheduleCancelInput = (0, strictToolInput_1.createStrictToolInput)(scheduleCancelShape);
 /**
  * Coerces an ARRAY tool argument into an actual array before validation. Some
  * MCP bridges (observed: Claude-agent harnesses AND OpenCode) serialize an array
@@ -466,19 +555,18 @@ const sendFileShape = {
         .boolean()
         .optional()
         .describe('Explicitly force sendDocument (original quality, no inline preview), including for MP4s that use sendVideo by default.'),
-    threadKey: zod_1.z
-        .string()
-        .optional()
-        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+    threadKey: threadKeyArgSchema,
 };
+const sendFileInput = (0, strictToolInput_1.createStrictToolInput)(sendFileShape);
 /**
  * One batch item: EITHER a plain non-empty string (text-only message,
  * backward-compatible with the original string-array tool) OR an object that may
- * carry a text body, an attachment `path`, or both. The `.refine` rejects an
- * all-empty object so a stray `{}` never posts nothing.
+ * carry a text body, an attachment `path`, or both. The object is CLOSED: an
+ * agent that writes `filePath` for `path` must be told, not silently sent as a
+ * text-only message. The `.refine` rejects an all-empty object so a stray `{}`
+ * never posts nothing.
  */
-const sendMessageItemObjectSchema = zod_1.z
-    .object({
+const sendMessageItemObjectSchema = (0, strictToolInput_1.createStrictToolInput)({
     text: zod_1.z
         .string()
         .optional()
@@ -494,12 +582,11 @@ const sendMessageItemObjectSchema = zod_1.z
         .boolean()
         .optional()
         .describe('Force sendDocument for THIS attachment (original quality, no inline preview), including for MP4s.'),
-})
-    .refine((item) => (item.text?.trim().length ?? 0) > 0 || (item.path?.trim().length ?? 0) > 0, { message: 'each message object must set a non-empty text or path' });
+}).refine((item) => (item.text?.trim().length ?? 0) > 0 || (item.path?.trim().length ?? 0) > 0, { message: 'each message object must set a non-empty text or path' });
 const sendMessageShape = {
     messages: zod_1.z
         .preprocess(coerceJsonArrayArg, zod_1.z
-        .array(zod_1.z.union([zod_1.z.string().min(1), sendMessageItemObjectSchema]))
+        .array(zod_1.z.union([zod_1.z.string().min(1), sendMessageItemObjectSchema], { error: strictToolInput_1.getUnknownKeysMessageOfUnion }))
         .min(1)
         .max(messageSendService_1.maxDiscreteMessages))
         .describe(`1..${messageSendService_1.maxDiscreteMessages} items; EACH item is posted as its OWN separate Telegram message, in order (never ` +
@@ -512,11 +599,9 @@ const sendMessageShape = {
         'Use this when you deliberately want several distinct messages (e.g. a per-item news digest: one message ' +
         'per headline). Do NOT also print the same content as your normal reply, or it posts twice. Text supports ' +
         'the usual markdown (links, bold); an over-long text item is split automatically.'),
-    threadKey: zod_1.z
-        .string()
-        .optional()
-        .describe('Target thread "<chatId>:<threadId>". Required when a directory scope has more than one bound thread.'),
+    threadKey: threadKeyArgSchema,
 };
+const sendMessageInput = (0, strictToolInput_1.createStrictToolInput)(sendMessageShape);
 /**
  * The three valid call shapes, appended to structural errors so a bad first call
  * teaches the corrected next call (the model spirals when an error says only what
@@ -629,8 +714,13 @@ function registerSchedulerTools(server, deps, scope) {
             'with a cron — the bot runs it in this folder and wakes you only when it starts failing. This is ' +
             'the ONLY reliable watcher: it survives bot restarts and crashes. Never build your own (a ' +
             'background loop, nohup, a sleep loop, a tmux pane, a shell crontab) — it dies with your session ' +
-            'or a restart and then fails silently.',
-        inputSchema: scheduleCreateShape,
+            'or a restart and then fails silently.\n\n' +
+            `A DETACHED WORKER you launched (a \`claude -p\` / \`opencode run\` process): cron \`${workerWatch_1.workerWatchCheckCron}\`, ` +
+            `\`${workerWatch_1.workerWatchPinArgument}\`, checkCommand \`${workerWatch_1.workerWatchCheckCommand}\` with its PID and run dir — it fails when ` +
+            'the worker exits OR nothing in its run dir changed for 45 min, so the first failure is also the "worker finished" ' +
+            'signal (hence the silent pin: a normal finish must not notify the user). Never `kill -0` alone: it stays green ' +
+            'while a worker hangs. One check per worker run; schedule_cancel it once its wake is handled.',
+        inputSchema: scheduleCreateInput,
     }, async (args) => {
         const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
         if (!resolved.ok)
@@ -678,7 +768,7 @@ function registerSchedulerTools(server, deps, scope) {
     server.registerTool('schedule_list', {
         title: 'List scheduled prompts',
         description: 'List the scheduled prompts for this topic (id, name, schedule, next run, paused flag).',
-        inputSchema: scheduleListShape,
+        inputSchema: scheduleListInput,
     }, async (args) => {
         const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
         if (!resolved.ok)
@@ -706,8 +796,10 @@ function registerSchedulerTools(server, deps, scope) {
     });
     server.registerTool('schedule_cancel', {
         title: 'Cancel a scheduled prompt',
-        description: 'Cancel (delete) a scheduled prompt by its id. Only schedules owned by this topic can be cancelled.',
-        inputSchema: scheduleCancelShape,
+        description: 'Cancel (delete) a scheduled prompt by its id. Only schedules owned by this topic can be cancelled. Cancelling a ' +
+            'watchdog check also unpins the alerts it pinned — cancel a worker watch once its wake is handled, so a finished ' +
+            'worker leaves no pinned alert behind.',
+        inputSchema: scheduleCancelInput,
     }, async (args) => {
         const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
         if (!resolved.ok)
@@ -723,7 +815,11 @@ function registerSchedulerTools(server, deps, scope) {
         }
         await deps.store.removeSchedule(args.id);
         deps.disarmJob(args.id);
-        return textResult(`Cancelled "${record.name}" (id: ${record.id}).`);
+        const alertPins = record.alertPinMessageIds ?? [];
+        if (alertPins.length === 0)
+            return textResult(`Cancelled "${record.name}" (id: ${record.id}).`);
+        await deps.unpinMessages(record.threadKey, alertPins);
+        return textResult(`Cancelled "${record.name}" (id: ${record.id}); its ${alertPins.length} pinned alert(s) unpinned.`);
     });
 }
 /**
@@ -750,7 +846,7 @@ function registerFileSendTool(server, deps, scope, requestSignal) {
             'the whole album documents — which turns its MP4s into GIFs, so send videos in their own call. ' +
             'If a send fails, say so and give the file\'s path in your reply, then go on with the work — never stop over it. ' +
             'Caption is optional (trimmed to 1024 chars; on the first album item).',
-        inputSchema: sendFileShape,
+        inputSchema: sendFileInput,
     }, async (args, extra) => {
         const signal = requestSignal
             ? AbortSignal.any([extra.signal, requestSignal])
@@ -797,7 +893,7 @@ function registerMessageSendTool(server, deps, scope, requestSignal) {
             'items; an over-long text item is split automatically. Note: this does NOT replace your normal single ' +
             'reply — only reach for it when multiple discrete messages are wanted, and do not also print the same ' +
             'content as your reply text (that would post it twice).',
-        inputSchema: sendMessageShape,
+        inputSchema: sendMessageInput,
     }, async (args, extra) => {
         const signal = requestSignal
             ? AbortSignal.any([extra.signal, requestSignal])
@@ -843,12 +939,12 @@ function registerCompactConversationTool(server, deps, scope) {
             'never to "clean up". It does NOT compact mid-turn: it arms compaction and returns immediately; the ' +
             'bot runs the real compaction the moment this turn finishes. There is nothing for you to do ' +
             'afterwards — do not call it again for the same request.',
-        inputSchema: {
+        inputSchema: (0, strictToolInput_1.createStrictToolInput)({
             reason: zod_1.z
                 .string()
                 .optional()
                 .describe('Optional short note on why the user asked to compact (for the bot log only).'),
-        },
+        }),
     }, async (args) => {
         // A surviving session may call this before boot re-attached it.
         await deps.whenSessionsRestored();
@@ -861,6 +957,95 @@ function registerCompactConversationTool(server, deps, scope) {
         return outcome.ok ? textResult(outcome.message) : errorResult(outcome.message);
     });
 }
+/** The most items one `todo_update` call may name, and the longest `order` — a stand-up list is a few items (D1). */
+const todoUpdateMaxItems = 30;
+const todoOrderMaxIds = 100;
+const todoItemPatchSchema = (0, strictToolInput_1.createStrictToolInput)({
+    id: zod_1.z
+        .string()
+        .trim()
+        .regex(/^t\d+$/)
+        .optional()
+        .describe('The item to change ("t3", from your list). Leave it out to ADD a new item.'),
+    title: zod_1.z
+        .string()
+        .max(types_1.todoTitleMaxLength)
+        .optional()
+        .describe('Task-sized and concrete: name the area (files, tests). Required for a new item.'),
+    status: zod_1.z
+        .enum(types_1.todoStatuses)
+        .optional()
+        .describe('queued (default for a new item) · inWork (you are on it) · done · dropped (will not be done — the way to remove an item).'),
+    note: zod_1.z.string().max(types_1.todoNoteMaxLength).optional().describe('A short note other agents should know (what is left, a blocker). An empty note removes it.'),
+    ref: zod_1.z
+        .string()
+        .max(types_1.todoRefMaxLength)
+        .optional()
+        .describe('A tracker key / id / link the item stands for, e.g. the bug ticket you just created. An empty ref removes it.'),
+    position: zod_1.z.enum(types_1.todoPositions).optional().describe('Put the item first or last among the open ones (a new item goes last by default).'),
+});
+const todoUpdateShape = {
+    items: zod_1.z
+        .preprocess(coerceJsonArrayArg, zod_1.z.array(todoItemPatchSchema).max(todoUpdateMaxItems))
+        .optional()
+        .describe('Items to add (no id) or change (id + only the fields that change). Nothing disappears by omission: set status dropped to remove one.'),
+    order: zod_1.z
+        .preprocess(coerceJsonArrayArg, zod_1.z.array(zod_1.z.string().trim().min(1)).max(todoOrderMaxIds))
+        .optional()
+        .describe('Open item ids in the wanted queue order; the ones left out keep their relative order after them.'),
+    threadKey: threadKeyArgSchema,
+};
+const todoUpdateInput = (0, strictToolInput_1.createStrictToolInput)(todoUpdateShape);
+const todoReadShape = {
+    scope: zod_1.z
+        .enum(registry_1.todoReadScopes)
+        .optional()
+        .describe('own (default): your list · project: the whole board of the project\'s other topics (what they work on now).'),
+    includeHistory: zod_1.z.boolean().optional().describe(`With scope own: also list older closed items (done / dropped), up to ${registry_1.todoHistoryMaxItems}.`),
+    threadKey: threadKeyArgSchema,
+};
+const todoReadInput = (0, strictToolInput_1.createStrictToolInput)(todoReadShape);
+/**
+ * @description Register `todo_update` / `todo_read` (shared todo registry D3–D5): the published list of the
+ * conversation the token names — never another one; the rules live in `todos/registry.ts`.
+ */
+function registerTodoTools(server, deps, todos, scope) {
+    server.registerTool('todo_update', {
+        title: 'Update your published todo list',
+        description: 'Publish what you are doing so the agents in the project\'s other topics see it and never fix the same thing ' +
+            'unknowingly (and you see theirs). Stand-up level: a few task-sized items, never micro-steps (those stay in ' +
+            'your own todo tool). Add an item as inWork BEFORE you start any task, self-found fixes included (a failing ' +
+            'test, a leak), naming the area concretely; mark it done / dropped as soon as it is. An UPSERT: an item ' +
+            'without id is new; with an id only the fields given change. A call with no items and no order confirms the ' +
+            'list is still accurate. The result is your list and what changed in the project\'s other topics since you last saw them.',
+        inputSchema: todoUpdateInput,
+    }, async (args) => {
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        const outcome = await todos.update(resolved.threadKey, {
+            ...(args.items === undefined ? {} : { items: args.items }),
+            ...(args.order === undefined ? {} : { order: args.order }),
+        });
+        return outcome.ok ? textResult(outcome.message) : errorResult(outcome.error);
+    });
+    server.registerTool('todo_read', {
+        title: 'Read your published todo list',
+        description: 'Your published todo list (in work, the queue in order, recently done) and what changed in the project\'s other ' +
+            'topics since you last saw them; with includeHistory also your older closed items; with scope project the whole board ' +
+            'of the other topics.',
+        inputSchema: todoReadInput,
+    }, async (args) => {
+        const resolved = resolveTargetThreadKey(scope, args.threadKey, deps.getThreadsForDirectory);
+        if (!resolved.ok)
+            return errorResult(resolved.error);
+        const outcome = await todos.read(resolved.threadKey, {
+            ...(args.scope === undefined ? {} : { scope: args.scope }),
+            ...(args.includeHistory === undefined ? {} : { includeHistory: args.includeHistory }),
+        });
+        return outcome.ok ? textResult(outcome.message) : errorResult(outcome.error);
+    });
+}
 /**
  * `jira_get_attachment`: the issue is the conversation this session's token names — never an argument —
  * so a file of any other issue cannot be asked for, however the id got into the agent's head.
@@ -873,9 +1058,9 @@ function registerJiraAttachmentTool(server, deps, fetchJiraAttachment, scope) {
             '"[image: shot.png — attachment 10234]". There is no size limit. What you do with the file is up to ' +
             'you: view an image with your file-reading tool, take frames or the audio of a video with ffmpeg ' +
             '(when it is on your PATH). Only this issue\'s own attachments can be fetched.',
-        inputSchema: {
+        inputSchema: (0, strictToolInput_1.createStrictToolInput)({
             attachmentId: zod_1.z.string().min(1).describe('The attachment id, e.g. "10234" from "[image: shot.png — attachment 10234]".'),
-        },
+        }),
     }, async (args) => {
         await deps.whenSessionsRestored();
         const resolved = resolveTargetThreadKey(scope, undefined, deps.getThreadsForDirectory);
@@ -917,6 +1102,7 @@ const answerRequestShape = {
         .max(answerRequest_1.answerBodyMaxLength)
         .describe(`The answer itself, in Markdown. The requester does not see your other output. ${answerStyle_1.answerStyleInstruction}`),
 };
+const answerRequestInput = (0, strictToolInput_1.createStrictToolInput)(answerRequestShape);
 /** `answer_request` in a Jira session: the same, and the comments the answer replies to. */
 const jiraAnswerRequestShape = {
     ...answerRequestShape,
@@ -927,6 +1113,7 @@ const jiraAnswerRequestShape = {
         .describe('Ids of the issue\'s comments this answer replies to, e.g. ["10240"]. The bot mentions each comment\'s ' +
         'author at the top of your answer so they are notified. Only comments you were shown in this conversation count.'),
 };
+const jiraAnswerRequestInput = (0, strictToolInput_1.createStrictToolInput)(jiraAnswerRequestShape);
 /**
  * @description Register `answer_request` (request/answer core S3): the agent's
  * answer to a request, delivered to the surface the request came from. The
@@ -956,9 +1143,9 @@ function registerAnswerRequestTool(server, deps, scope, platform) {
     };
     // The reply field names a tracker's comments: only a Jira session is offered it.
     if (platform === 'jira')
-        server.registerTool('answer_request', { ...definition, inputSchema: jiraAnswerRequestShape }, handle);
+        server.registerTool('answer_request', { ...definition, inputSchema: jiraAnswerRequestInput }, handle);
     else
-        server.registerTool('answer_request', { ...definition, inputSchema: answerRequestShape }, handle);
+        server.registerTool('answer_request', { ...definition, inputSchema: answerRequestInput }, handle);
 }
 /**
  * @description Correlate stateless MCP requests with cancellation notifications.
@@ -1058,6 +1245,20 @@ function createSchedulerMcpCancellationLifecycle(options = {}) {
     }
     return { registerRequest, cancelRequest };
 }
+/**
+ * @description Whether the bot's skills are on for the conversations a scope reaches (`utils/botSkills.ts`). A `thread:`
+ * scope is one conversation. A `dir:` scope is the OpenCode registration of a folder — ONE per folder and server run, read
+ * at connect — so it serves the folder's OpenCode topics alone (a Claude topic bound to the same folder has its own
+ * `thread:` scope) and keeps the manager hint while any of them has the skills on; a folder with no OpenCode topic gets the
+ * instance value.
+ */
+function checkIsBotSkillsEnabledForScope(deps, scope) {
+    const threadKeys = scope.kind === 'thread'
+        ? [scope.threadKey]
+        : deps.getThreadsForDirectory(scope.directory).filter((threadKey) => deps.getThreadAdapterName(threadKey) === adapterNames_1.openCodeAdapterName);
+    const keys = threadKeys.map(sessionKey_1.tryKeyFromString).filter((key) => key !== null);
+    return keys.length === 0 ? (0, botSkills_1.checkIsBotSkillsEnabled)(null) : keys.some((key) => (0, botSkills_1.checkIsBotSkillsEnabled)(key));
+}
 /**
  * @description Build a fresh {@link McpServer} for one request, registering the
  * scope-bound scheduler tools plus the `send_file_to_user` tool. The SDK binds one server
@@ -1066,7 +1267,7 @@ function createSchedulerMcpCancellationLifecycle(options = {}) {
  */
 function buildRequestServer(deps, scope, requestSignal) {
     const platform = getSchedulerScopePlatform(scope);
-    const server = new mcp_js_1.McpServer({ name: mcpServerName, version: mcpServerVersion }, { instructions: buildMcpServerInstructions(platform, deps.fetchJiraAttachment !== undefined) });
+    const server = new mcp_js_1.McpServer({ name: mcpServerName, version: mcpServerVersion }, { instructions: buildMcpServerInstructions(platform, getOptionalBotTools(deps), checkIsBotSkillsEnabledForScope(deps, scope)) });
     registerBotTools(server, deps, scope, platform, requestSignal);
     return server;
 }
@@ -1082,10 +1283,22 @@ function registerBotTools(server, deps, scope, platform, requestSignal) {
     if (platform === 'jira' && deps.fetchJiraAttachment)
         registerJiraAttachmentTool(server, deps, deps.fetchJiraAttachment, scope);
     registerCompactConversationTool(server, deps, scope);
+    // A published list belongs to a conversation of a platform that has one (D54): a topic or a Jira issue.
+    if (deps.todos && (platform === 'telegram' || platform === 'jira'))
+        registerTodoTools(server, deps, deps.todos, scope);
     registerAnswerRequestTool(server, deps, scope, platform);
     if (deps.listClaudeProfiles)
         registerClaudeProfilesTool(server, deps.listClaudeProfiles);
 }
+/** The first line of the `claude_profiles` answer: the pick with how to launch it and why, or that nothing is usable and when something is. */
+function buildClaudeProfilesVerdict(report, currentProfile) {
+    const outcome = (0, claudeUsage_1.describeClaudeLaunchOutcome)(report, currentProfile);
+    if (report.recommended === null)
+        return outcome;
+    const dir = report.profiles.find((profile) => profile.name === report.recommended)?.configDir ?? null;
+    const launch = dir === null ? 'default profile, set no CLAUDE_CONFIG_DIR' : `CLAUDE_CONFIG_DIR=${dir}`;
+    return `recommended: ${report.recommended} → ${launch} (${outcome})`;
+}
 /**
  * `claude_profiles`: which Claude account a child process should run on. Reads the bot's per-profile usage
  * cache (refreshed on demand by the port); touches no conversation, so it needs no scope resolution. The
@@ -1095,31 +1308,43 @@ function registerClaudeProfilesTool(server, listClaudeProfiles) {
     server.registerTool('claude_profiles', {
         title: 'Claude accounts and their usage',
         description: 'The Claude account profiles signed in on this host, each with its usage windows — session (5 h), weekly ' +
-            '(all models) and weekly Fable — as percent used + reset instant, and `recommended`: the profile with the most ' +
-            'headroom for the model you pass (the session window and the shared weekly window bound every model, Fable ' +
-            'included; Fable also drains its own weekly window; signed-out and limited profiles are skipped). An account with ' +
-            '`billing: "api"` pays per request from a Claude Console balance: it has no windows and is NEVER recommended — do ' +
-            'not launch a child on it unless the operator asked you to. Call it BEFORE ' +
-            'launching a child `claude` and start the child with CLAUDE_CONFIG_DIR=<configDir> in its environment — ' +
-            'configDir null means the default profile: set nothing. Without the variable the child inherits the account ' +
-            'of this very session.',
-        inputSchema: {
+            '(all models) and weekly Fable — as percent used + reset instant, and `recommended`: the account a process of ' +
+            'the model you pass should run on. A NEW agent (omit `currentProfile`) goes to the usable account whose weekly ' +
+            'limit resets SOONEST — what burns soonest is spent first; an account whose five-hour window is at 90 % or more ' +
+            'is skipped until it resets. A session you RESUME (pass `currentProfile`, the profile it last ran on) stays on ' +
+            'it unless that account is signed out, limited or at 100 % on a window the model drains; when it broke off on a ' +
+            'usage limit pass `isStoppedByLimit: true` and resume the SAME session at once on the answer. The session ' +
+            'window and the shared weekly window bound every model, Fable included; Fable also drains its own weekly ' +
+            'window; signed-out, limited and operator-switched-off accounts are skipped. An account with `billing: "api"` ' +
+            'pays per request from a Claude Console balance: it has no windows and is NEVER picked for a new agent — do ' +
+            'not launch a child on it unless the operator asked you to. `recommended: null` means nothing is usable now: ' +
+            '`nextAvailable` names the account and instant that frees up first — schedule ONE resume at that time instead ' +
+            'of retrying; when `nextAvailable` is null too, tell the user and retry once in about 30 minutes. Call it BEFORE launching or resuming a child `claude` and start the child with ' +
+            'CLAUDE_CONFIG_DIR=<configDir> in its environment — configDir null means the default profile: set nothing. ' +
+            'Without the variable the child inherits the account of this very session.',
+        inputSchema: (0, strictToolInput_1.createStrictToolInput)({
             model: zod_1.z
                 .string()
                 .max(64)
                 .optional()
                 .describe('The model the child will run (e.g. "fable", "opus", "sonnet"); decides whether the Fable weekly window counts besides the shared ones. Omit for the shared windows.'),
-        },
+            currentProfile: zod_1.z
+                .string()
+                .max(claudeProfiles_1.claudeProfileNameMaxLength)
+                .optional()
+                .describe('The profile the session you RESUME last ran on (the `name` you recorded at its launch); omit for a new agent.'),
+            isStoppedByLimit: zod_1.z
+                .boolean()
+                .optional()
+                .describe('The resumed session broke off on a usage limit of `currentProfile`: that account is left out of this answer. Needs `currentProfile`.'),
+        }),
     }, async (args) => {
-        const report = await listClaudeProfiles(args.model?.trim() || null);
-        const verdict = report.recommended === null
-            ? 'No eligible subscription profile: every signed-in one is limited or at 100 % on a relevant window (an account billed to API credits is never recommended).'
-            : (() => {
-                const entry = report.profiles.find((profile) => profile.name === report.recommended);
-                const dir = entry?.configDir ?? null;
-                return `recommended: ${report.recommended} → ${dir === null ? 'default profile, set no CLAUDE_CONFIG_DIR' : `CLAUDE_CONFIG_DIR=${dir}`}`;
-            })();
-        return textResult(`${verdict}\n${JSON.stringify(report, null, 1)}`);
+        const currentProfile = args.currentProfile?.trim() || null;
+        if (args.isStoppedByLimit === true && currentProfile === null) {
+            return errorResult('isStoppedByLimit needs currentProfile — the profile the session that hit the limit last ran on.');
+        }
+        const report = await listClaudeProfiles({ model: args.model?.trim() || null, currentProfile, isStoppedByLimit: args.isStoppedByLimit === true });
+        return textResult(`${buildClaudeProfilesVerdict(report, currentProfile)}\n${JSON.stringify(report, null, 1)}`);
     });
 }
 /** Read the whole request body into a string (the SDK wants the parsed JSON body). */
@@ -1229,7 +1454,12 @@ function createSchedulerMcpServer(deps) {
             void server.close();
         });
         await server.connect(transport);
-        await transport.handleRequest(req, res, parsedBody);
+        // The SDK refuses a call's input before any tool code runs, so the refusal is reported from inside the handling.
+        const toolCall = types_js_1.CallToolRequestSchema.safeParse(parsedBody);
+        const handleRequest = () => transport.handleRequest(req, res, parsedBody);
+        await (toolCall.success && deps.logDiagnostic
+            ? (0, strictToolInput_1.runWithRefusalLogging)({ toolName: toolCall.data.params.name, log: deps.logDiagnostic }, handleRequest)
+            : handleRequest());
     }
     function start() {
         return new Promise((resolve, reject) => {
@@ -1323,7 +1553,7 @@ function createSchedulerMcpServer(deps) {
     return {
         start,
         stop,
-        getToolDigest: (platform) => getBotMcpToolDigest(deps, platform),
+        getToolDigest: (platform, isBotSkillsEnabled) => getBotMcpToolDigest(deps, platform, isBotSkillsEnabled),
         get port() {
             return boundPort;
         },