codetrellis 0.0.0-stage → 0.2.0

package/src/backend/mcp/tools/plan-tools.js

@@ -0,0 +1,680 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_tools_exports = {};
+__export(plan_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(plan_tools_exports);
+var import_zod = require("zod");
+var import_item_git_state = require("../../services/item-git-state");
+var import_plan_status = require("../../services/plan-status");
+var import_plan_arrivals = require("../../services/plan-arrivals");
+var import_helpers = require("../helpers");
+var import_prompt_builders = require("../prompt-builders");
+var import_trusted_roots = require("../../services/trusted-roots");
+var import_stack_service = require("../../services/stack-service");
+var import_play_forward = require("../../services/play-forward");
+var import_recurring_service = require("../../services/recurring-service");
+function register(server, deps) {
+  server.registerTool(
+    "create_plan",
+    {
+      description: 'Create a new plan in CodeTrellis. Returns the plan UID. Use add_item or bulk_add_items to populate it with Objects (context pages) and Actions (work items). The new plan is auto-exported to .codetrellis/plans/<slug>/ on disk when the effective default visibility is "shared" (see get_project_config). When "local", it stays DB-only and you can later export it explicitly with export_plan_to_files.',
+      inputSchema: {
+        title: import_zod.z.string().describe("Brief title of the plan"),
+        description: import_zod.z.string().optional().describe("Detailed description of what this plan achieves"),
+        project_path: import_zod.z.string().describe("Absolute path to the project this plan is for")
+      }
+    },
+    async ({ title, description, project_path }) => {
+      const plan = deps.planService.createPlan(
+        { title, description: description || "", tasks: [] },
+        "agent",
+        "mcp",
+        project_path
+      );
+      let exported = false;
+      try {
+        const visibility = deps.projectConfigService.getEffectiveDefaultVisibility(project_path);
+        if (visibility === "shared") {
+          deps.planFileService.exportPlan(plan.uid, project_path);
+          exported = true;
+        }
+      } catch (err) {
+        console.warn(`[create_plan] Auto-export failed for ${plan.uid}:`, err);
+      }
+      const n = deps.broadcast("plan-created", { plan, exported });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)({
+        uid: plan.uid,
+        title: plan.title,
+        status: plan.status,
+        projectPath: plan.projectPath,
+        exported
+      }, n);
+    }
+  );
+  server.registerTool(
+    "get_plan",
+    {
+      description: `Read a plan by its UID. Returns plan metadata, a summary of its items (count by kind, status breakdown), state: every item's state with its source (git or the review host for an item on a branch, "plan" for everything else, with who recorded it) and the plan's progress, what waits on someone, what is under way and its lineage; and git_state: for each item worked on a branch, what git proves (building, pushed, or merged and how), with the commit and source. Where the person turned on a review host for the project, it also says in review (with checks and approvals) or closed, with source github. Use list_items to browse the item tree.`,
+      inputSchema: { plan_uid: import_zod.z.string().describe("Plan UID") }
+    },
+    async ({ plan_uid }) => {
+      const plan = deps.planService.getPlan(plan_uid);
+      if (!plan) return { content: [{ type: "text", text: "Plan not found" }] };
+      const items = deps.planItemService.listItemSummaries(plan_uid);
+      const objectCount = items.filter((i) => i.kind === "object").length;
+      const actionCount = items.filter((i) => i.kind === "action").length;
+      const statusCounts = {};
+      for (const i of items) {
+        if (i.status) statusCounts[i.status] = (statusCounts[i.status] || 0) + 1;
+      }
+      return { content: [{ type: "text", text: JSON.stringify({
+        uid: plan.uid,
+        title: plan.title,
+        description: plan.description,
+        status: plan.status,
+        projectPath: plan.projectPath,
+        createdAt: plan.createdAt,
+        updatedAt: plan.updatedAt,
+        items: { total: items.length, objects: objectCount, actions: actionCount, byStatus: statusCounts },
+        // Phase 32 C2.6a — how it reached this machine, when through its files.
+        ...arrivalFor(plan_uid) ? { arrived_from: arrivalFor(plan_uid) } : {},
+        // Phase 32 C2.4 — every item's state with its source, and the plan's status view.
+        state: await statusForAgent(plan_uid),
+        // Phase 32 C2.1 — what git proves about each item's branch.
+        git_state: await gitStateForAgent(plan_uid, items)
+      }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "update_plan",
+    {
+      description: `Update a plan (title, description, or status). Creates a new version snapshot. Approving a plan is the person's: set status "review" to ask for it, and they approve it in the window or on the phone. Status "approved" is refused here.`,
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        title: import_zod.z.string().optional(),
+        description: import_zod.z.string().optional(),
+        status: import_zod.z.enum(["draft", "review", "approved", "in_progress", "completed", "archived"]).optional()
+      }
+    },
+    async ({ plan_uid, title, description, status }, extra) => {
+      if (status === "approved") {
+        return { content: [{ type: "text", text: `Not changed: approving a plan is the person's. Set status "review" to ask for it; they approve it in the window (Approve on the plan header) or on the phone.` }], isError: true };
+      }
+      const by = (0, import_helpers.authorFromExtra)(deps, extra);
+      deps.planService.updatePlan(plan_uid, { title, description, status }, by.author, by.authorType);
+      const n = deps.broadcast("plan-updated", { planUid: plan_uid });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)({ ok: true, planUid: plan_uid }, n);
+    }
+  );
+  server.registerTool(
+    "list_plans",
+    {
+      description: "List plans, optionally filtered by project path or status. Returns lightweight summaries with item counts. Use limit/offset for pagination.",
+      inputSchema: {
+        project_path: import_zod.z.string().optional(),
+        status: import_zod.z.string().optional(),
+        limit: import_zod.z.number().int().min(1).max(100).optional().describe("Max plans to return (default 20)"),
+        offset: import_zod.z.number().int().min(0).optional().describe("Skip this many plans (default 0)")
+      }
+    },
+    async ({ project_path, status, limit, offset }) => {
+      const all = deps.planService.listPlans(project_path, status);
+      const start = offset ?? 0;
+      const end = start + (limit ?? 20);
+      const page = all.slice(start, end);
+      const summaries = page.map((p) => ({
+        uid: p.uid,
+        title: p.title,
+        status: p.status,
+        projectPath: p.projectPath,
+        itemCount: deps.planItemService.listItemSummaries(p.uid).length,
+        createdAt: p.createdAt,
+        updatedAt: p.updatedAt
+      }));
+      return { content: [{ type: "text", text: JSON.stringify({
+        total: all.length,
+        offset: start,
+        limit: limit ?? 20,
+        plans: summaries
+      }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_stack",
+    {
+      description: "The stack: every active plan in the project (not completed or archived) and its tasks, in one answer. Each plan is called by its ticket key when it has one, with its progress and how many breakpoint hits wait on a person. Each task says who is on it, the branch it is worked on, and its dependencies, including ones in other plans, with what it waits on in words. Use it to see how plans fit together before picking up work.",
+      inputSchema: {
+        project_path: import_zod.z.string().optional().describe("An opened project. Omit for the one open in the app.")
+      }
+    },
+    async ({ project_path }) => {
+      const root = project_path ?? (0, import_trusted_roots.getActiveProjectRoot)();
+      if (!root) return { isError: true, content: [{ type: "text", text: "No project is open." }] };
+      return { content: [{ type: "text", text: JSON.stringify((0, import_stack_service.buildStack)(root), null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_play_forward",
+    {
+      description: 'Play the plans forward: what every active plan in the project says it will change, from its unfinished tasks, and where two plans will meet if they go ahead ("\u25C7 planned overlap: JIRA-142 and JIRA-150 both plan to change src/billing/invoice.ts"), including materials both rely on. The same function, or one plan deleting what another changes, is serious; an overlap whose tasks already wait on one another is sequenced. Nothing here exists yet. Use it before claiming work that a planned overlap names.',
+      inputSchema: {
+        project_path: import_zod.z.string().optional().describe("An opened project. Omit for the one open in the app.")
+      }
+    },
+    async ({ project_path }) => {
+      const root = project_path ?? (0, import_trusted_roots.getActiveProjectRoot)();
+      if (!root) return { isError: true, content: [{ type: "text", text: "No project is open." }] };
+      return { content: [{ type: "text", text: JSON.stringify((0, import_play_forward.buildPlayForward)(root), null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_recurring",
+    {
+      description: `The project's recurring playbooks (Phase 32 C4): each rule ("Weekly security review, every Mon 09:00 \xB7 skill: security-review") with its runs by period, \u2713 done, \u25D0 in progress, \u2717 missed, the one due now if it is not started, and the next. Each run is an ordinary plan (planUid). A person makes a playbook recur and starts a run in the app; this only reads.`,
+      inputSchema: {
+        project_path: import_zod.z.string().optional().describe("An opened project. Omit for the one open in the app.")
+      }
+    },
+    async ({ project_path }) => {
+      const root = project_path ?? (0, import_trusted_roots.getActiveProjectRoot)();
+      if (!root) return { isError: true, content: [{ type: "text", text: "No project is open." }] };
+      return { content: [{ type: "text", text: JSON.stringify({ series: (0, import_recurring_service.seriesFor)(root) }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "request_plan_deletion",
+    {
+      description: 'Ask the person to delete one or more plans. Opens a confirmation in the CodeTrellis window listing the plans and your reason; they must type the plan name (or "delete N plans") to go ahead. This tool deletes nothing and returns immediately: check list_plans later to see whether they did. Plans outside the projects this app has opened are refused.',
+      inputSchema: {
+        plan_uids: import_zod.z.array(import_zod.z.string()).min(1).max(50).describe("UIDs of the plans to propose deleting"),
+        reason: import_zod.z.string().max(500).describe("One or two sentences the person will read: why these plans should go")
+      }
+    },
+    async ({ plan_uids, reason }) => {
+      const plans = [];
+      for (const uid of [...new Set(plan_uids)]) {
+        const plan = deps.planService.getPlan(uid);
+        if (!plan || plan.status === "archived") {
+          return { content: [{ type: "text", text: `No active plan ${uid}` }], isError: true };
+        }
+        if (!plan.projectPath || !(0, import_trusted_roots.isTrustedProjectRoot)(plan.projectPath)) {
+          return {
+            content: [{ type: "text", text: `Plan ${uid} belongs to a project that is not open; it can only be deleted from there.` }],
+            isError: true
+          };
+        }
+        plans.push({ uid: plan.uid, title: plan.title, projectPath: plan.projectPath });
+      }
+      const requestId = `pd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const n = deps.broadcast("ui-confirm-plan-deletion", { requestId, plans, reason });
+      return (0, import_helpers.resultWithMeta)({
+        requested: true,
+        requestId,
+        plans: plans.map((p) => ({ uid: p.uid, title: p.title })),
+        note: n > 0 ? "Asked the person to confirm in the CodeTrellis window. Nothing has been deleted." : "No CodeTrellis window is open to ask. Nothing has been deleted."
+      }, n);
+    }
+  );
+  server.registerTool(
+    "export_plan_to_files",
+    {
+      description: "Round-trip a plan to disk as YAML under `<projectRoot>/.codetrellis/plans/<slug>/`. Exports a nested `items/` tree layout. Idempotent \u2014 re-exporting overwrites the same files. Use this so plans can be committed to git and shared across devices / agents.",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        project_root: import_zod.z.string().describe("Absolute path to the project repo root. The .codetrellis/ directory will be created inside it.")
+      }
+    },
+    async ({ plan_uid, project_root }) => {
+      try {
+        const result = deps.planFileService.exportPlan(plan_uid, project_root);
+        deps.broadcast("plan-exported", { planUid: plan_uid, planDir: result.planDir, files: result.files.length });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ planDir: result.planDir, fileCount: result.files.length }, null, 2)
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : err}` }] };
+      }
+    }
+  );
+  server.registerTool(
+    "import_plan_from_files",
+    {
+      description: "Read a plan directory (`.codetrellis/plans/<slug>/`) from disk and upsert it into the DB. Detects format automatically. UID-based upsert is idempotent. Use after `git pull` to sync external changes.",
+      inputSchema: {
+        plan_dir: import_zod.z.string().describe("Absolute path to the plan directory (or directly to plan.yaml).")
+      }
+    },
+    async ({ plan_dir }) => {
+      try {
+        const result = deps.planFileService.importPlan(plan_dir);
+        deps.broadcast("plan-imported", { planUid: result.plan.uid, source: plan_dir });
+        if (result.items) {
+          for (const item of result.items) {
+            deps.broadcast("plan-item-created", { item });
+          }
+        }
+        deps.saveNow(() => deps.exportDatabase());
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              plan: { uid: result.plan.uid, title: result.plan.title },
+              itemCount: result.items?.length ?? 0,
+              warnings: result.warnings
+            }, null, 2)
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : err}` }] };
+      }
+    }
+  );
+  server.registerTool(
+    "discover_plan_files",
+    {
+      description: "List every plan directory under `<project_root>/.codetrellis/plans/`. Used to find plans that came in via `git pull` or that another tool authored. Returns absolute paths.",
+      inputSchema: { project_root: import_zod.z.string() }
+    },
+    async ({ project_root }) => {
+      const dirs = deps.planFileService.discoverPlanDirs(project_root);
+      return { content: [{ type: "text", text: JSON.stringify(dirs, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "unlink_plan_from_files",
+    {
+      description: "Remove a plan's on-disk directory under `.codetrellis/plans/<slug>/`. The DB rows survive \u2014 this is the \"Shared \u2192 Local\" toggle. Use this to stop write-through-syncing a plan to the project repo (e.g. for a private brainstorm you don't want committed).",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        project_root: import_zod.z.string()
+      }
+    },
+    async ({ plan_uid, project_root }) => {
+      try {
+        const result = deps.planFileService.unlinkPlan(plan_uid, project_root);
+        deps.broadcast("plan-unlinked", { planUid: plan_uid });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : err}` }] };
+      }
+    }
+  );
+  server.registerTool(
+    "publish_plan_as_template",
+    {
+      description: "Snapshot a plan as a reusable template under `<project_root>/.codetrellis/templates/<template_id>/`. Produces a template with a nested items tree. Strips runtime fields (statuses, assignees). The result can be shared via git.",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        project_root: import_zod.z.string(),
+        template_id: import_zod.z.string().describe('Lowercase slug, alphanumeric + hyphens (e.g. "company-mass-refactor").'),
+        label: import_zod.z.string().optional().describe("Human-readable name shown in the picker. Defaults to the plan title."),
+        short_description: import_zod.z.string().optional(),
+        long_description: import_zod.z.string().optional(),
+        default_title: import_zod.z.string().optional().describe("Default plan title when the template is applied. May contain `{{name}}` etc. for placeholder substitution."),
+        default_plan_description: import_zod.z.string().optional()
+      }
+    },
+    async ({ plan_uid, project_root, template_id, label, short_description, long_description, default_title, default_plan_description }) => {
+      try {
+        const result = deps.publishPlanAsTemplate({
+          planUid: plan_uid,
+          projectRoot: project_root,
+          templateId: template_id,
+          label,
+          shortDescription: short_description,
+          longDescription: long_description,
+          defaultTitle: default_title,
+          defaultPlanDescription: default_plan_description
+        });
+        deps.broadcast("plan-template-published", { templateId: template_id, templateDir: result.templateDir });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : err}` }] };
+      }
+    }
+  );
+  server.registerTool(
+    "list_plan_templates",
+    {
+      description: "List the available plan templates. Includes built-ins, user-global templates from `~/.codetrellis/templates/`, and project-local templates from `<project_root>/.codetrellis/templates/` when project_root is provided. Each template seeds a full plan tree in one go.",
+      inputSchema: {
+        project_root: import_zod.z.string().optional().describe("Project root for picking up team-published templates from `.codetrellis/templates/`. Optional \u2014 without it, only built-ins + user-global templates are returned.")
+      }
+    },
+    async ({ project_root }) => {
+      return { content: [{ type: "text", text: JSON.stringify(deps.listTemplates(project_root), null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "create_plan_from_template",
+    {
+      description: "Create a new plan from a template in one call. Use list_plan_templates to pick a template_id. Pass `placeholder_values` for templates with `{{key}}` placeholders.",
+      inputSchema: {
+        template_id: import_zod.z.string().describe('e.g. "mass-refactor"'),
+        project_path: import_zod.z.string(),
+        title: import_zod.z.string().optional().describe("Override the template default title"),
+        description: import_zod.z.string().optional().describe("Override the template default description"),
+        placeholder_values: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional().describe("Values for `{{key}}` placeholders declared by the template (Phase 13 \xA7C). Missing keys fall back to the placeholder default.")
+      }
+    },
+    async ({ template_id, project_path, title, description, placeholder_values }, extra) => {
+      try {
+        const result = deps.applyTemplate({
+          templateId: template_id,
+          projectPath: project_path,
+          title,
+          description,
+          ...(0, import_helpers.authorFromExtra)(deps, extra),
+          placeholderValues: placeholder_values
+        });
+        let exported = false;
+        try {
+          const visibility = deps.projectConfigService.getEffectiveDefaultVisibility(project_path);
+          if (visibility === "shared") {
+            deps.planFileService.exportPlan(result.plan.uid, project_path);
+            exported = true;
+          }
+        } catch (err) {
+          console.warn(`[create_plan_from_template] Auto-export failed for ${result.plan.uid}:`, err);
+        }
+        deps.broadcast("plan-created", { plan: result.plan, exported });
+        if (result.items) {
+          for (const item of result.items) deps.broadcast("plan-item-created", { item });
+        }
+        deps.saveNow(() => deps.exportDatabase());
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              plan: result.plan,
+              itemCount: result.items?.length ?? 0,
+              exported,
+              hint: "Use list_items(plan_uid) to browse the plan tree."
+            }, null, 2)
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Failed to apply template: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
+    }
+  );
+  server.registerTool(
+    "import_external",
+    {
+      description: "Import a plan from external text \u2014 a conversation transcript, markdown notes, GitHub issue body, or any structured text. Extracts action items, file references, and creates a plan with items automatically. Good for turning chat discussions or issue descriptions into actionable CodeTrellis plans.",
+      inputSchema: {
+        text: import_zod.z.string().describe("The text content to import (markdown, conversation, issue body, etc.)."),
+        title: import_zod.z.string().optional().describe("Optional title for the new plan. Auto-generated if omitted."),
+        project_path: import_zod.z.string().optional().describe(
+          "Absolute path to the project this plan belongs to. Defaults to the project currently open."
+        )
+      }
+    },
+    async ({ text, title, project_path }, extra) => {
+      const projectPath = project_path ?? (0, import_trusted_roots.getActiveProjectRoot)();
+      if (!projectPath) {
+        return { content: [{ type: "text", text: "No project is open: pass project_path, or open the project first." }], isError: true };
+      }
+      const id = (0, import_helpers.authorFromExtra)(deps, extra);
+      try {
+        const result = deps.planImportService.importFromConversation({ text, title });
+        const plan = deps.planService.createPlan(
+          { title: result.title, description: result.description, tasks: [] },
+          id.author,
+          id.authorType,
+          projectPath
+        );
+        let itemCount = 0;
+        for (const imported of result.items) {
+          deps.planItemService.createItem({
+            planUid: plan.uid,
+            kind: imported.kind,
+            title: imported.title,
+            body: imported.body,
+            fileSpecs: imported.fileSpecs,
+            scopePath: imported.scopePath,
+            author: id.author,
+            authorType: id.authorType
+          });
+          itemCount++;
+        }
+        deps.planFileService.exportIfSharedByDefault(plan.uid, projectPath);
+        deps.broadcast("plan-imported", { planUid: plan.uid, source: "mcp-import" });
+        return {
+          content: [{
+            type: "text",
+            text: `Imported plan "${plan.title}" (${plan.uid}) with ${itemCount} items`
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Import failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
+    }
+  );
+  server.registerTool(
+    "copy_plan_as_prompt",
+    {
+      description: 'Serialise a plan (or a single item) as a markdown prompt suitable for handing off to an AI agent. Returns the formatted prompt text that includes tasks, file targets, constraints, and git context. Equivalent to the "Copy as prompt" handoff button in the UI.',
+      inputSchema: {
+        plan_uid: import_zod.z.string().describe("UID of the plan to serialise."),
+        item_uid: import_zod.z.string().optional().describe("If provided, serialise only this item instead of the full plan.")
+      }
+    },
+    async ({ plan_uid, item_uid }) => {
+      const plan = deps.planService.getPlan(plan_uid);
+      if (!plan) {
+        return { content: [{ type: "text", text: `Plan ${plan_uid} not found` }], isError: true };
+      }
+      const items = deps.planItemService.listAllItems(plan_uid);
+      if (item_uid) {
+        const item = items.find((i) => i.uid === item_uid);
+        if (!item) {
+          return { content: [{ type: "text", text: `Item ${item_uid} not found in plan ${plan_uid}` }], isError: true };
+        }
+        const prompt2 = (0, import_prompt_builders.buildItemPrompt)(item, plan);
+        return { content: [{ type: "text", text: prompt2 }] };
+      }
+      const refs = deps.externalRefsService.getExternalRefsByPlan(plan_uid);
+      const prompt = (0, import_prompt_builders.buildPlanPrompt)(plan, items, refs);
+      return { content: [{ type: "text", text: prompt }] };
+    }
+  );
+  server.registerTool(
+    "set_plan_home_repo",
+    {
+      description: "Set the home repo of a plan to a normalised git origin URL. The home repo is captured automatically at create_plan from the project's git origin \u2014 call this only when you need to override it (e.g. moving a plan between repos, or attaching a previously-orphaned plan). Pass an empty string to clear.",
+      inputSchema: {
+        plan_uid: import_zod.z.string().describe("UID of the plan to update"),
+        home_repo_url: import_zod.z.string().describe("Git origin URL \u2014 will be normalised. Empty string clears.")
+      }
+    },
+    async ({ plan_uid, home_repo_url }) => {
+      const trimmed = home_repo_url.trim();
+      deps.planService.setPlanHomeRepo(plan_uid, trimmed === "" ? null : trimmed);
+      const plan = deps.planService.getPlan(plan_uid);
+      const n = deps.broadcast("plan-updated", { planUid: plan_uid });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)({ ok: true, planUid: plan_uid, homeRepo: plan?.homeRepo ?? null }, n);
+    }
+  );
+  server.registerTool(
+    "add_plan_scope",
+    {
+      description: "Add a repository (by git origin URL) to a plan's cross-repo scope. When `pointer_project_root` is supplied AND it's a clone of the scoped repo on this machine, a pointer file is written to <pointer_project_root>/.codetrellis/external/<plan-uid>.yaml so developers cloning that repo discover the plan. The pointer caches a snapshot of title/status/summary; it round-trips through git. Returns the updated scope list.",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        repo_url: import_zod.z.string().describe("Git origin URL of the participating repo \u2014 will be normalised"),
+        pointer_project_root: import_zod.z.string().optional().describe("Absolute path on this machine where the pointer file should be written. Skip when not locally available."),
+        contribution: import_zod.z.string().optional().describe(`Short note describing this repo's contribution to the plan (e.g. "ships the migration").`),
+        summary: import_zod.z.string().optional().describe("Short prose summary cached into the pointer; defaults to the plan's description.")
+      }
+    },
+    async ({ plan_uid, repo_url, pointer_project_root, contribution, summary }) => {
+      const plan = deps.planService.getPlan(plan_uid);
+      if (!plan) {
+        return { content: [{ type: "text", text: `Plan ${plan_uid} not found` }], isError: true };
+      }
+      const scope = deps.planService.addPlanScope(plan_uid, repo_url);
+      let pointerPath = null;
+      if (pointer_project_root) {
+        try {
+          pointerPath = deps.externalPointerService.writePointer({
+            planUid: plan_uid,
+            projectRoot: pointer_project_root,
+            homeRepo: plan.homeRepo ?? "",
+            title: plan.title,
+            status: plan.status,
+            summary: summary ?? plan.description ?? void 0,
+            contribution
+          });
+        } catch (err) {
+          console.warn("[add_plan_scope] pointer write failed:", err);
+        }
+      }
+      const n = deps.broadcast("plan-scope-changed", { planUid: plan_uid, scope, added: repo_url, pointerPath });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)({ ok: true, planUid: plan_uid, scope, pointerPath }, n);
+    }
+  );
+  server.registerTool(
+    "remove_plan_scope",
+    {
+      description: "Remove a repo from a plan's scope. When `pointer_project_root` is supplied, also delete the pointer file at <pointer_project_root>/.codetrellis/external/<plan-uid>.yaml so the scoped repo stops advertising the plan.",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        repo_url: import_zod.z.string(),
+        pointer_project_root: import_zod.z.string().optional().describe("Absolute path of the scoped repo on this machine \u2014 pointer is removed when supplied.")
+      }
+    },
+    async ({ plan_uid, repo_url, pointer_project_root }) => {
+      const scope = deps.planService.removePlanScope(plan_uid, repo_url);
+      let pointerRemoved = false;
+      if (pointer_project_root) {
+        pointerRemoved = deps.externalPointerService.removePointer(plan_uid, pointer_project_root);
+      }
+      const n = deps.broadcast("plan-scope-changed", { planUid: plan_uid, scope, removed: repo_url, pointerRemoved });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)({ ok: true, planUid: plan_uid, scope, pointerRemoved }, n);
+    }
+  );
+  server.registerTool(
+    "list_plan_pointers",
+    {
+      description: 'List every external plan pointer found under <project_path>/.codetrellis/external/. Each entry is a thin reference to a plan whose home is another repo \u2014 title/status/summary/contribution are cached at the last refresh. Use this to surface "plans from other repos that touch this one" in the UI.',
+      inputSchema: {
+        project_path: import_zod.z.string().describe("Absolute path to the project root")
+      }
+    },
+    async ({ project_path }) => {
+      const pointers = deps.externalPointerService.discoverPointers(project_path);
+      return { content: [{ type: "text", text: JSON.stringify({
+        projectPath: project_path,
+        count: pointers.length,
+        pointers: pointers.map((p) => ({ filePath: p.filePath, ...p.pointer }))
+      }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_plans_by_repo",
+    {
+      description: 'Return every active plan whose home_repo OR scope contains the given git origin URL. Cross-machine safe \u2014 URLs are normalised before matching. Useful for "show me every plan that touches this repo" in cross-repo views.',
+      inputSchema: {
+        repo_url: import_zod.z.string().describe("Git origin URL \u2014 will be normalised before matching")
+      }
+    },
+    async ({ repo_url }) => {
+      const plans = deps.planService.listPlansByRepoUrl(repo_url);
+      return { content: [{ type: "text", text: JSON.stringify({
+        repoUrl: repo_url,
+        count: plans.length,
+        plans: plans.map((p) => ({
+          uid: p.uid,
+          title: p.title,
+          status: p.status,
+          homeRepo: p.homeRepo,
+          scope: p.scope,
+          taskCount: p.taskCount,
+          completedTaskCount: p.completedTaskCount,
+          projectPath: p.projectPath
+        }))
+      }, null, 2) }] };
+    }
+  );
+}
+function arrivalFor(planUid) {
+  const a = (0, import_plan_arrivals.getPlanArrival)(planUid);
+  return a ? { added_by: a.addedBy, commit: a.commit, says: (0, import_plan_arrivals.arrivalWords)(a) } : null;
+}
+async function statusForAgent(planUid) {
+  const s = await (0, import_plan_status.planStatusFresh)(planUid);
+  if (!s) return null;
+  return {
+    progress: s.progress.words,
+    waiting: s.waiting.map((w) => ({ item_uid: w.itemUid, title: w.title, says: w.words, source: w.source })),
+    in_progress: s.inProgress.map((w) => ({ item_uid: w.itemUid, title: w.title, says: w.words, source: w.source })),
+    lineage: s.lineage,
+    items: s.items.map((i) => ({
+      item_uid: i.itemUid,
+      title: i.title,
+      kind: i.kind,
+      state: i.state,
+      says: i.words,
+      source: i.source,
+      ...i.recorded ? { recorded_by: i.recorded.by, recorded_at: i.recorded.at } : {},
+      // C3.1: taken from a teammate's record in the project's files, which anyone could have written.
+      ...i.recorded?.byType === "record" ? { recorded_in: i.recorded.check?.verified ? `the teammate's record, signed with ${i.recorded.check.how === "git" ? "their git key" : "their trusted device key"}` : "the teammate's record, unverified" } : {},
+      ...i.branch ? { branch: i.branch } : {},
+      ...i.gitNote ? { git_note: i.gitNote } : {},
+      // C3.2: set two ways at once by people who had not seen each other's change; nothing is picked.
+      ...i.atOnce ? { set_at_once: i.atOnce.words } : {}
+    })),
+    note: 'Read, never written: source says where each state came from \u2014 git or the review host for an item on a branch, the plan itself ("plan") for everything else.'
+  };
+}
+async function gitStateForAgent(planUid, items) {
+  const states = await (0, import_item_git_state.planGitStatesFresh)(planUid);
+  if (!states || states.items.length === 0) return { base: states?.base ?? null, items: [], note: "No item is worked on a branch yet (assign_workstream sets one)." };
+  const title = new Map(items.map((i) => [i.uid, i.title]));
+  return {
+    base: states.base,
+    items: states.items.map((s) => ({
+      item_uid: s.itemUid,
+      title: title.get(s.itemUid) ?? null,
+      branch: s.branch,
+      state: s.state,
+      says: s.words,
+      ...s.how ? { how: s.how } : {},
+      commit: s.commit,
+      source: s.source,
+      ...s.review ? { pull_request: s.review } : {},
+      ...s.hostNote ? { host_note: s.hostNote } : {}
+    })),
+    note: states.items.some((s) => s.source !== "git" || s.hostNote) ? "From git, and from the review host the person turned on where it says more: source names which." : "From git alone: building, pushed and merged. In review, checks and closed need a review host, which the person turns on in Settings \u2192 Review hosts; none is asked."
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});