@nonbot/mcp 0.2.4 → 0.3.0

package/dist/core/toolsets/build.js

@@ -1,8 +1,11 @@
 import { z } from 'zod';
 import { api, expectJson } from '../http.js';
 import { validateGraph } from '../validate.js';
-import { LEVELS, applyLayout, layoutTimeline, scheduleFields, todayColumn, columnOf, isItem, PX_PER_WEEK } from '../layout.js';
+import { LEVELS, applyLayout, layoutTimeline, layoutMapDetailed, applyMapLayout, scheduleFields, todayColumn, columnOf, isItem, PX_PER_WEEK } from '../layout.js';
 import { emptyIp, IP_KINDS, IP_NODE_SIZE } from '../ipShape.js';
+import { withMapHeaders } from '../mapHeaders.js';
+import { renderPreviewSvg } from '../preview.js';
+import { applyStyleRules, CARD_STYLES, TITLE_SIZES, ACCENTS, SHOW_KEYS, STATES as STYLE_STATES } from '../style.js';
 const STATES = ['funnel', 'reviewing', 'analyzing', 'ready', 'implementing', 'done'];
 const OKR_STATUSES = ['on-track', 'at-risk', 'behind'];
 const RESERVED = new Set(['hierarchyLevel', 'parentItemId', 'linkedEpicIds', 'id', '__proto__', 'constructor', 'prototype']);
@@ -13,7 +16,7 @@ const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true }
 const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 export const toHtml = (s) => /^\s*</.test(s) ? s : s.split(/\n{2,}/).map(p => `<p>${escHtml(p.trim()).replace(/\n/g, '<br>')}</p>`).join('');
 export function newItemId(now = Date.now()) { return `pf-${now}-${Math.random().toString(36).slice(2, 11)}`; }
-async function loadGraph(ctx, id) {
+export async function loadGraph(ctx, id) {
     const data = await expectJson(await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(id)}`), 'load portfolio');
     const g = (data.graph ?? data);
     return {
@@ -25,7 +28,7 @@ async function loadGraph(ctx, id) {
         version: typeof g.version === 'number' ? g.version : undefined,
     };
 }
-async function saveGraph(ctx, id, before, after, expectedVersion) {
+export async function saveGraph(ctx, id, before, after, expectedVersion) {
     const problems = validateGraph(after.nodes, after.edges);
     if (problems.length)
         return { ok: false, message: `Refusing to write — ${problems.length} problem(s):\n` + problems.map(p => `  - ${p}`).join('\n') };
@@ -63,7 +66,7 @@ const itemSpec = z.object({
     duration_weeks: z.number().min(0).max(156).optional().describe('Default: epic 8, feature 4, story 1, enabler 2, milestone 0, objective / key-result 12.'),
     tags: z.array(z.string().max(40)).max(20).optional(),
     wsjf: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional().describe('[business value, time criticality, risk reduction, job size].'),
-    owner: z.string().max(80).optional(),
+    owner: z.string().max(80).optional().describe(`Who does this item — the Program view's lanes group by it. Set it on every feature / story / enabler / milestone: the human's name (as they appear in the portfolio, e.g. "Conrad") for work only a person can do — review or approve a plan, decide, buy, sign up, sign in, hand over a key, test on a real device, talk to a customer; "AI" for work an agent delivers — code, tests, migrations, docs, research, drafts. Spell it exactly "AI" so all agent work shares one lane.`),
     kr_target: z.string().max(200).optional(),
     kr_current: z.string().max(200).optional(),
     okr_status: z.enum(OKR_STATUSES).optional(),
@@ -74,6 +77,20 @@ const DEFAULT_WEEKS = { epic: 8, feature: 4, story: 1, enabler: 2, milestone: 0,
 const LEGAL_PARENT = {
     epic: [], objective: [], 'key-result': ['objective'], feature: ['epic'], story: ['feature', 'epic'], enabler: ['epic', 'feature'], milestone: ['epic', 'feature'],
 };
+export const AI_OWNER = 'AI';
+const WORK_LEVELS = new Set(['feature', 'story', 'enabler', 'milestone']);
+export function ownerReport(specs) {
+    const owners = {};
+    const unassigned = [];
+    for (const s of specs) {
+        const who = s.owner?.trim();
+        if (who)
+            owners[who] = (owners[who] ?? 0) + 1;
+        else if (WORK_LEVELS.has(s.level))
+            unassigned.push(s.key ?? s.title);
+    }
+    return { owners, unassigned };
+}
 export function buildItems(g, specs, now = new Date()) {
     const errors = [];
     const ids = {};
@@ -112,8 +129,8 @@ export function buildItems(g, specs, now = new Date()) {
             d.hypothesisStatement = s.hypothesis;
         if (s.tags)
             d.tags = s.tags;
-        if (s.owner)
-            d.owner = s.owner;
+        if (s.owner?.trim())
+            d.owner = s.owner.trim();
         if (s.wsjf)
             Object.assign(d, { wsjfBusinessValue: s.wsjf[0], wsjfTimeCriticality: s.wsjf[1], wsjfRiskReduction: s.wsjf[2], wsjfJobSize: s.wsjf[3] });
         if (s.kr_target)
@@ -166,6 +183,21 @@ export function buildItems(g, specs, now = new Date()) {
     return { nodes, edges, ids, errors, patched };
 }
 export function registerBuildTools(server, ctx) {
+    server.registerTool('portfolio_preview', {
+        title: 'Picture a portfolio layout',
+        description: 'Draw the portfolio as an SVG schematic — every card at its stored Map (default) or Timeline position and size, with its level, state and title (done cards pale green), section-header notes as headings — so you can LOOK at a layout before calling it done. Returns the SVG text plus the card count and extent. `sizes` (px per id) overrides the stored / estimated card sizes; `width` sets the output width.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            view: z.enum(['map', 'timeline']).optional(),
+            sizes: z.record(z.string(), z.object({ width: z.number().min(1).max(8000), height: z.number().min(1).max(8000) })).optional(),
+            width: z.number().int().min(200).max(8000).optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const r = renderPreviewSvg(g.nodes, { view: a.view, sizes: a.sizes, width: a.width });
+        return { content: [{ type: 'text', text: JSON.stringify({ cards: r.cards, extent: r.extent }) }, { type: 'text', text: r.svg }] };
+    });
     if (ctx.readonly)
         return;
     server.registerTool('portfolio_create', {
@@ -216,12 +248,16 @@ export function registerBuildTools(server, ctx) {
         const r = await saveGraph(ctx, a.portfolio_id, g, after, a.expected_version);
         if (!r.ok)
             return fail(r.message);
-        const structured = { ok: true, added: built.nodes.length, edges: built.edges.length, ids: built.ids, ...(r.version !== undefined ? { version: r.version } : {}) };
-        return { content: [text(structured)], structuredContent: structured };
+        const who = ownerReport(a.items);
+        const structured = { ok: true, added: built.nodes.length, edges: built.edges.length, ids: built.ids, owners: who.owners, unassigned: who.unassigned, ...(r.version !== undefined ? { version: r.version } : {}) };
+        const content = [text(structured)];
+        if (who.unassigned.length)
+            content.push({ type: 'text', text: `${who.unassigned.length} work item(s) have no owner: ${who.unassigned.join(', ')}. Give each one with portfolio_patch_item (set: { owner }) — the human's name for work only a person can do (review, approve, decide, buy, sign in, test on a device), "${AI_OWNER}" for work an agent delivers — so the human can see at a glance what is theirs.` });
+        return { content, structuredContent: structured };
     });
     server.registerTool('portfolio_patch_item', {
         title: 'Patch one item',
-        description: 'Change fields of ONE portfolio item without rewriting the graph (PATCH /api/portfolio/graph/node): `set` writes allowlisted PortfolioItemData fields (title, description, bluf, acceptanceCriteria, hypothesisStatement, state, tags, wsjf*, krTarget, pastedImages, durationWeeks, startDate, …), `unset` deletes them. Rich text is stored as given (pass HTML, or plain text which is wrapped in <p>). A stale version answers 409 — nothing is written.',
+        description: 'Change fields of ONE portfolio item without rewriting the graph (PATCH /api/portfolio/graph/node): `set` writes allowlisted PortfolioItemData fields (title, description, bluf, acceptanceCriteria, hypothesisStatement, state, owner — the human\'s name or "AI", tags, wsjf*, krTarget, pastedImages, durationWeeks, startDate, …), `unset` deletes them. Rich text is stored as given (pass HTML, or plain text which is wrapped in <p>). A stale version answers 409 — nothing is written.',
         inputSchema: {
             portfolio_id: z.string(),
             item_id: z.string(),
@@ -248,22 +284,92 @@ export function registerBuildTools(server, ctx) {
     });
     server.registerTool('portfolio_layout', {
         title: 'Lay out a portfolio on the Timeline',
-        description: 'Re-position every item so the Timeline reads cleanly: x from each item\'s start date (the canvas reads dates off x), y top-down — objectives, key results, then one block per epic (epic, features, stories + enablers, milestones), each row lane-packed so overlapping items stack, IP nodes directly above their first source. Short items get a minimum painted width so titles fit. Content is untouched. `heights` overrides the estimated card height per id (px) when a card measures taller on screen.',
+        description: 'Re-position every item so the Timeline reads cleanly: x from each item\'s start date (the canvas reads dates off x), y top-down — objectives, key results, then one block per epic (epic, features, stories + enablers, milestones), each row lane-packed so overlapping items stack, IP nodes directly above their first source. Short items get a minimum painted width so titles fit. Content is untouched. `heights` overrides the estimated card height per id (px) when a card measures taller on screen. `group: "objective"` reads top-down by goal instead: each objective, its key results, then the blocks of the epics those key results link to, before the next objective (`objective_order` lists objective ids to put first); unlinked epics follow. Grouping changes rows only, never x or dates. `view: "map"` lays out the Map instead (the free layout, `freePosition` only — the Timeline positions and dates are untouched): one band per objective (`objective_order` first), the objective + key results leading it, then one column per linked epic with its features and a 3-wide grid of stories; unlinked epics, loose items and modules follow.',
         inputSchema: {
             portfolio_id: z.string(),
             heights: z.record(z.string(), z.number().min(20).max(2000)).optional(),
+            sizes: z.record(z.string(), z.object({ width: z.number().min(1).max(8000), height: z.number().min(1).max(8000) })).optional().describe('With view "map": measured card sizes (px) per id — Map cards are as wide as their content.'),
+            column_height: z.number().min(400).max(20000).optional().describe('With view "map": an epic column taller than this (px) wraps into another column beside it, at feature boundaries.'),
+            pack: z.enum(['stack', 'grid']).optional().describe('With view "map": "grid" packs the objective bands into rows shaped like a screen (default "stack": top to bottom).'),
+            headers: z.boolean().optional().describe('With view "map": a section-header note above each objective band (title + epics + % done). Re-running updates the same notes; notes you wrote are never touched.'),
+            view: z.enum(['timeline', 'map']).optional().describe('Default timeline. "map": write the Map (free) positions only, grouped by objective.'),
+            group: z.enum(['objective']).optional().describe('"objective": group epic blocks under the objective whose key results link to them.'),
+            objective_order: z.array(z.string()).max(100).optional().describe('With group "objective": objective ids to place first, in this order.'),
             expected_version: z.number().int().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (a) => {
         const g = await loadGraph(ctx, a.portfolio_id);
-        const res = layoutTimeline(g.nodes, { heights: a.heights });
+        if (a.view === 'map') {
+            const HEADER_H = 220;
+            const cards = g.nodes.filter(n => !(n.type === 'rad-module' && n.data?.moduleData?.__layoutHeader));
+            const d = layoutMapDetailed(cards, { edges: g.edges, objectiveOrder: a.objective_order, heights: a.heights, sizes: a.sizes, pack: a.pack, columnHeight: a.column_height, headerHeight: a.headers ? HEADER_H : 0 });
+            let nodes = applyMapLayout(g.nodes, d.positions);
+            let headers = { added: 0, updated: 0, removed: 0 };
+            if (a.headers !== undefined) {
+                const h = withMapHeaders(nodes, a.headers ? d.bands : [], HEADER_H);
+                nodes = h.nodes;
+                headers = { added: h.added, updated: h.updated, removed: h.removed };
+            }
+            const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes }, a.expected_version);
+            if (!r.ok)
+                return fail(r.message);
+            const structured = { ok: true, view: 'map', positioned: d.positions.size, bands: d.bands.length, headers, ...(r.version !== undefined ? { version: r.version } : {}) };
+            return { content: [text(structured)], structuredContent: structured };
+        }
+        const res = layoutTimeline(g.nodes, { heights: a.heights, ...(a.group ? { group: a.group, edges: g.edges, objectiveOrder: a.objective_order } : {}) });
         const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: applyLayout(g.nodes, res) }, a.expected_version);
         if (!r.ok)
             return fail(r.message);
         const structured = { ok: true, positioned: res.positions.size, ...(r.version !== undefined ? { version: r.version } : {}) };
         return { content: [text(structured)], structuredContent: structured };
     });
+    server.registerTool('portfolio_style', {
+        title: 'Restyle many cards at once',
+        description: 'Give a portfolio one consistent look in ONE versioned write: rules, applied in order, each matching cards by levels / states / ids / hasImage and setting how they are drawn — display (card_style plain|poster|split|image-top|cover|grid-2|grid-4, title_size sm|md|lg, accent tint|bar|plain, show {bluf, description, acceptanceCriteria, tags, dates, wsjf}), size (Map width × height, or "auto" to size to content) and satellites "close" (fold the card\'s inner-loop panels). Content is untouched. Artifact child cards (hypothesis, NFR…) are skipped unless a rule sets artifacts: true.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            rules: z.array(z.object({
+                levels: z.array(z.enum(LEVELS)).optional(),
+                states: z.array(z.enum(STYLE_STATES)).optional(),
+                ids: z.array(z.string()).max(1000).optional(),
+                has_image: z.boolean().optional(),
+                artifacts: z.boolean().optional(),
+                display: z.object({
+                    card_style: z.enum(CARD_STYLES).optional(),
+                    title_size: z.enum(TITLE_SIZES).optional(),
+                    accent: z.enum(ACCENTS).optional(),
+                    show: z.object(Object.fromEntries(SHOW_KEYS.map(k => [k, z.boolean().optional()]))).optional(),
+                }).optional(),
+                size: z.union([z.object({ width: z.number().min(60).max(4000), height: z.number().min(40).max(4000) }), z.literal('auto')]).optional(),
+                satellites: z.literal('close').optional(),
+            })).min(1).max(40),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const rules = a.rules.map(r => ({
+            ...(r.levels ? { levels: r.levels } : {}),
+            ...(r.states ? { states: r.states } : {}),
+            ...(r.ids ? { ids: r.ids } : {}),
+            ...(r.has_image !== undefined ? { hasImage: r.has_image } : {}),
+            ...(r.artifacts ? { artifacts: true } : {}),
+            ...(r.display ? { display: { cardStyle: r.display.card_style, titleSize: r.display.title_size, accent: r.display.accent, show: r.display.show } } : {}),
+            ...(r.size ? { size: r.size } : {}),
+            ...(r.satellites ? { satellites: r.satellites } : {}),
+        }));
+        const res = applyStyleRules(g.nodes, rules);
+        if (res.changed === 0) {
+            const structured = { ok: true, matched: res.matched, changed: 0, perRule: res.perRule };
+            return { content: [text(structured)], structuredContent: structured };
+        }
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: res.nodes }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, matched: res.matched, changed: res.changed, perRule: res.perRule, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
     server.registerTool('portfolio_set_meta', {
         title: 'Set portfolio settings',
         description: 'Graph-level settings that travel with the portfolio (the `__graph_meta__` record): `context_text` (the portfolio\'s context notes — what a newcomer reads first), `palette` ({ id, name, swatches: [{hex, label?}] ≤ 10, roles?: {epic, feature, story, …: hex | "p:N"} }), `canvas_style`, `sprint_settings`. Only the keys you pass change; everything else in the record is kept.',

package/dist/core/toolsets/radbugs.d.ts

@@ -1,3 +1,30 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ApiContext } from '../config.js';
+declare const LIST_STATUSES: readonly ["open", "done", "wontfix", "ai_flagged"];
+type ListStatus = (typeof LIST_STATUSES)[number];
+export interface RadbugNote {
+    id: string;
+    status: string;
+    priority: string | null;
+    area: string | null;
+    pageUrl: string | null;
+    description: string;
+    createdAt: number | null;
+    updatedAt: number | null;
+    hasScreenshot: boolean;
+    rawMessage?: string | null;
+}
+export declare function fetchRadbugs(ctx: ApiContext, opts?: {
+    status?: ListStatus;
+    area?: string;
+    priority?: 'low' | 'med' | 'high';
+    limit?: number;
+}): Promise<{
+    forbidden: true;
+    reason: string;
+} | {
+    forbidden: false;
+    notes: RadbugNote[];
+}>;
 export declare function registerRadbugsTools(server: McpServer, ctx: ApiContext): void;
+export {};

package/dist/core/toolsets/radbugs.js

@@ -16,7 +16,62 @@ async function forbiddenText(res) {
 function textResult(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
+const LIST_STATUSES = ['open', 'done', 'wontfix', 'ai_flagged'];
+const LIST_FORBIDDEN = 'radbug_list is owner-only: it needs the site owner\'s account and a token with the radbugs:read scope (or an unscoped token).';
+const ms = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : null; };
+export async function fetchRadbugs(ctx, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 200, 1), 500);
+    const q = [`limit=${encodeURIComponent(String(opts.status === 'done' ? 500 : limit))}`];
+    if (opts.status && opts.status !== 'done')
+        q.push(`status=${encodeURIComponent(opts.status)}`);
+    if (opts.area)
+        q.push(`area=${encodeURIComponent(opts.area)}`);
+    if (opts.priority)
+        q.push(`priority=${encodeURIComponent(opts.priority)}`);
+    const res = await api(ctx, `/api/admin/radbugs?${q.join('&')}`);
+    if (res.status === 403 || res.status === 401)
+        return { forbidden: true, reason: LIST_FORBIDDEN };
+    const body = await expectJson(res, 'GET /api/admin/radbugs');
+    const raw = Array.isArray(body.notes) ? body.notes : [];
+    const notes = [];
+    for (const r of raw) {
+        if (!r || typeof r.id !== 'string')
+            continue;
+        const status = String(r.status ?? '');
+        if (opts.status && status !== opts.status)
+            continue;
+        notes.push({
+            id: r.id, status,
+            priority: typeof r.priority === 'string' ? r.priority : null,
+            area: typeof r.area === 'string' ? r.area : null,
+            pageUrl: typeof r.pageUrl === 'string' ? r.pageUrl.slice(0, 2048) : null,
+            description: String(r.description ?? '').slice(0, 2000),
+            createdAt: ms(r.createdAt), updatedAt: ms(r.updatedAt),
+            hasScreenshot: !!(r.screenshot || (Array.isArray(r.screenshots) && r.screenshots.length)),
+            rawMessage: typeof r.rawMessage === 'string' ? r.rawMessage.slice(0, 500) : null,
+        });
+        if (notes.length >= limit)
+            break;
+    }
+    return { forbidden: false, notes };
+}
 export function registerRadbugsTools(server, ctx) {
+    server.registerTool('radbug_list', {
+        title: 'List radBUGS',
+        description: 'List radBUGS from the non.bot inbox, newest first (open ones lead): id (ti_…), status (open | ai_flagged | done | wontfix), priority, area, page URL, description (clipped to 2 000 chars), created / updated time (epoch ms). `done` includes bugs closed from the inbox. Screenshots are left out. Owner-only: the site owner\'s account with a radbugs:read (or unscoped) token.',
+        inputSchema: {
+            status: z.enum(LIST_STATUSES).optional().describe('Only this status; "done" = closed.'),
+            area: z.string().max(80).optional(),
+            priority: z.enum(['low', 'med', 'high']).optional(),
+            limit: z.number().int().min(1).max(500).optional().describe('Default 200.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const r = await fetchRadbugs(ctx, a);
+        if (r.forbidden)
+            return { content: [{ type: 'text', text: r.reason }], isError: true };
+        return textResult({ count: r.notes.length, notes: r.notes });
+    });
     if (ctx.readonly)
         return;
     server.registerTool('radbug_file', {

package/dist/core/toolsets/release.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ApiContext } from '../config.js';
+export declare function registerReleaseTools(server: McpServer, ctx: ApiContext): void;

package/dist/core/toolsets/release.js

@@ -0,0 +1,329 @@
+import { z } from 'zod';
+import { checkRepoPath } from '../config.js';
+import { api, expectJson } from '../http.js';
+import { loadGraph, saveGraph, toHtml } from './build.js';
+import { fetchRadbugs } from './radbugs.js';
+import { columnOf, PX_PER_WEEK } from '../layout.js';
+import { RELEASE_SUBTYPE, applyChainWrites, applyItemPatches, chainReleasesFromGraphNodes, chainWrites, fileSet, memberCounts, membersOf, newReleaseId, outTargetsOf, patchReleaseData, placeRelease, previousRelease, releaseIdOf, releaseNode, subtreeOf, unfileSet, unfinishedIn, } from '../releases.js';
+import { clocklessDone, completedWork, matchEvidence, proposeReleases, toMs, windowMs } from '../completedWork.js';
+const DATE = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'YYYY-MM-DD');
+const MAX_PROPOSALS = 120;
+const text = (obj) => ({ type: 'text', text: JSON.stringify(obj, null, 2) });
+const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+const ok = (structured) => ({ content: [text(structured)], structuredContent: structured });
+const items = (g) => g.nodes.filter(n => n.type === 'portfolio-item');
+const localDay = (s) => new Date(Number(s.slice(0, 4)), Number(s.slice(5, 7)) - 1, Number(s.slice(8, 10)));
+const xOfDate = (now) => (iso) => columnOf(localDay(iso), now) * PX_PER_WEEK;
+const findRelease = (g, id) => g.nodes.find(n => n.id === id && n.type === 'rad-module' && n.data?.subtype === RELEASE_SUBTYPE);
+const titleOf = (n) => String(n?.data?.title ?? '');
+function addRelease(nodes, md, now) {
+    const id = newReleaseId(now.getTime());
+    const prev = previousRelease(md.from, chainReleasesFromGraphNodes(nodes));
+    const node = releaseNode(id, md, placeRelease(nodes, md.from, prev?.id ?? null, xOfDate(now)));
+    const withNode = [...nodes, node];
+    return { nodes: applyChainWrites(withNode, chainWrites(id, chainReleasesFromGraphNodes(withNode))), id, prev: prev?.id ?? null };
+}
+function nextOf(nodes, id) {
+    const n = nodes.find(x => x.id === id);
+    return n ? (outTargetsOf(n.data ?? {})[0] ?? null) : null;
+}
+const versionOf = (r) => (r.version !== undefined ? { version: r.version } : {});
+export function registerReleaseTools(server, ctx) {
+    server.registerTool('portfolio_completed_work', {
+        title: 'What got done',
+        description: 'The done items of a portfolio in a date window, computed from the graph: each row names its done date and the clock it came from (doneAt — stamped when filed, stateChangedAt — the state clock, updatedAt — only the last edit, a proxy; none = unknown), rolled up objective → key result → epic → feature → story. Parents that are NOT done but hold done work are flagged partially_done and never counted. Cards already filed in a release are left out unless include_filed. Window ends are inclusive local days; with a window, done cards with no clock at all are listed as undated.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            from: DATE.optional(),
+            to: DATE.optional(),
+            include_filed: z.boolean().optional().describe('Default false: cards filed in a release are already accounted for.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        if (a.from && a.to && a.to < a.from)
+            return fail('to is before from.');
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const r = completedWork(g.nodes, g.edges, { from: a.from, to: a.to, includeFiled: a.include_filed });
+        return ok({ window: { from: a.from ?? null, to: a.to ?? null }, ...r });
+    });
+    server.registerTool('portfolio_rebuild_done_work', {
+        title: 'Find when forgotten work finished',
+        description: 'For every done card with no finish clock (no doneAt, no stateChangedAt), gather POINTERS — not verdicts — to when it finished: commits in the local git repo at repo_path (since `since`) that cite the card id or a radBUGS id tied to the card; closed radBUGS tied to it (owner-only — needs radbug_list access); the card\'s own comments. Each card gets a proposal: the latest commit / closed-radBUG date, else the latest comment, else unknown. Writes nothing; to keep a proposal, set the card\'s doneAt with portfolio_patch_item (set: { doneAt: <epoch ms> }), then portfolio_propose_releases.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            since: DATE.describe('Look at commits, radBUGS and comments from this day on.'),
+            repo_path: z.string().max(1024).optional().describe('Absolute path of a local git checkout (stdio only). portfolio_repo_path tells you the saved one.'),
+            radbugs: z.boolean().optional().describe('Default true: read closed radBUGS (owner-only; skipped with a note otherwise).'),
+            comments: z.boolean().optional().describe('Default true: read each card\'s comments (one request per card).'),
+            max_cards: z.number().int().min(1).max(300).optional().describe('Default 100: cards examined, most recently edited first.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        if (a.repo_path !== undefined) {
+            const bad = checkRepoPath(a.repo_path);
+            if (bad)
+                return fail(bad);
+        }
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const all = clocklessDone(g.nodes);
+        const upd = (n) => (typeof n.data?.updatedAt === 'number' ? n.data.updatedAt : 0);
+        const cards = [...all].sort((x, y) => upd(y) - upd(x) || x.id.localeCompare(y.id)).slice(0, a.max_cards ?? 100);
+        const { lo } = windowMs(a.since);
+        const sources = {};
+        let commits = [];
+        if (!a.repo_path)
+            sources.git = 'not requested — pass repo_path';
+        else if (!ctx.gitLog)
+            sources.git = 'unavailable — this server has no local disk (use the stdio server)';
+        else {
+            try {
+                commits = await ctx.gitLog(a.repo_path, a.since);
+                sources.git = `${commits.length} commit(s) since ${a.since}`;
+            }
+            catch (e) {
+                sources.git = `failed — ${e instanceof Error ? e.message.slice(0, 200) : 'git error'}`;
+            }
+        }
+        let radbugs = [];
+        if (a.radbugs === false)
+            sources.radbugs = 'not requested';
+        else {
+            const r = await fetchRadbugs(ctx, { status: 'done' });
+            if (r.forbidden)
+                sources.radbugs = `skipped — ${r.reason}`;
+            else {
+                radbugs = r.notes.filter(b => (b.updatedAt ?? b.createdAt ?? 0) >= lo);
+                sources.radbugs = `${radbugs.length} closed radBUG(s) since ${a.since}`;
+            }
+        }
+        const comments = new Map();
+        if (a.comments === false)
+            sources.comments = 'not requested';
+        else {
+            let failed = 0;
+            const queue = [...cards];
+            const worker = async () => {
+                for (let c = queue.shift(); c; c = queue.shift()) {
+                    try {
+                        const res = await api(ctx, `/api/portfolio/comments?portfolioId=${encodeURIComponent(a.portfolio_id)}&itemId=${encodeURIComponent(c.id)}`);
+                        const body = await expectJson(res, 'comments');
+                        comments.set(c.id, (Array.isArray(body.comments) ? body.comments : []).filter(x => (toMs(x.createdAt) ?? 0) >= lo));
+                    }
+                    catch {
+                        failed++;
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(4, cards.length) }, worker));
+            sources.comments = `read for ${cards.length - failed} card(s)${failed ? `, ${failed} failed` : ''}`;
+        }
+        const out = cards.map(c => {
+            const m = matchEvidence(c, { commits, radbugs, comments: comments.get(c.id) ?? [] });
+            return { id: c.id, title: titleOf(c), level: String(c.data?.hierarchyLevel ?? ''), proposal: m.proposal, evidence: m.evidence };
+        });
+        const known = out.filter(c => c.proposal.basis !== 'unknown').length;
+        return ok({ clockless_done: all.length, examined: cards.length, with_evidence: known, unknown: cards.length - known, sources, cards: out });
+    });
+    server.registerTool('portfolio_release_list', {
+        title: 'List releases',
+        description: 'The releases of a portfolio, oldest first: id, name, from–to window, draft / approvedAt / open, the chain (previous / next release by the OUT wire), member counts by level, and for a draft the cards it proposes. include_members lists each release\'s filed cards (id, title, level, doneAt).',
+        inputSchema: { portfolio_id: z.string(), include_members: z.boolean().optional() },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const cards = items(g);
+        const nodes = g.nodes;
+        const rels = g.nodes.filter(n => n.type === 'rad-module' && n.data?.subtype === RELEASE_SUBTYPE);
+        const prevOf = new Map();
+        for (const r of rels) {
+            const t = outTargetsOf(r.data ?? {})[0];
+            if (t)
+                prevOf.set(t, r.id);
+        }
+        const list = rels.map(r => {
+            const md = (r.data?.moduleData ?? {});
+            const proposed = Array.isArray(md.proposed) ? md.proposed.filter((x) => typeof x === 'string') : [];
+            return {
+                id: r.id, name: String(md.name ?? ''), from: String(md.from ?? ''), to: String(md.to ?? ''),
+                draft: md.draft === true, ...(typeof md.approvedAt === 'number' ? { approvedAt: md.approvedAt } : {}), open: md.open === true,
+                summary: String(md.summary ?? '').slice(0, 2000), ...(Array.isArray(md.highlights) ? { highlights: md.highlights } : {}),
+                previous: prevOf.get(r.id) ?? null, next: nextOf(nodes, r.id),
+                counts: memberCounts(r.id, cards),
+                ...(md.draft === true ? { proposed } : {}),
+                ...(a.include_members ? { members: membersOf(r.id, cards).map(n => ({ id: n.id, title: titleOf(n), level: String(n.data?.hierarchyLevel ?? ''), doneAt: n.data?.doneAt ?? null })) } : {}),
+            };
+        }).sort((x, y) => x.from.localeCompare(y.from) || x.to.localeCompare(y.to));
+        return ok({ releases: list, ...(g.version !== undefined ? { version: g.version } : {}) });
+    });
+    if (ctx.readonly)
+        return;
+    server.registerTool('portfolio_propose_releases', {
+        title: 'Propose releases',
+        description: 'Write DRAFT releases for done work that is not filed yet: one per calendar week (Mon–Sun, by each card\'s done date) and — unless objective_releases is false — one per finished objective, holding it and its done subtree. Each draft lists the cards it proposes (moduleData.proposed); NOTHING is filed and no card is touched until the draft is approved (portfolio_release_approve, or Accept in the app). Drafts are chained by date like any release. Cards already proposed by another draft and cards with no done clock are skipped and listed. One versioned write.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            from: DATE.optional().describe('Only work done on or after this day.'),
+            to: DATE.optional().describe('Only work done on or before this day.'),
+            objective_releases: z.boolean().optional().describe('Default true: a finished objective gets its own release.'),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        if (a.from && a.to && a.to < a.from)
+            return fail('to is before from.');
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const p = proposeReleases(g.nodes, g.edges, { from: a.from, to: a.to, objectiveReleases: a.objective_releases });
+        const report = { undated: p.undated, already_proposed: p.already_proposed, filed_skipped: p.filed_skipped };
+        if (!p.drafts.length)
+            return ok({ ok: true, created: [], ...report });
+        if (p.drafts.length > MAX_PROPOSALS)
+            return fail(`That would be ${p.drafts.length} drafts (limit ${MAX_PROPOSALS}) — narrow the window with from / to.`);
+        const now = new Date();
+        let nodes = g.nodes;
+        const created = [];
+        for (const d of p.drafts) {
+            const r = addRelease(nodes, { name: d.name, from: d.from, to: d.to, summary: '', draft: true, open: false, proposed: d.proposed }, now);
+            nodes = r.nodes;
+            created.push({ id: r.id, kind: d.kind, name: d.name, from: d.from, to: d.to, proposed: d.proposed.length, ...(d.objective_id ? { objective_id: d.objective_id } : {}) });
+        }
+        const s = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: nodes }, a.expected_version);
+        if (!s.ok)
+            return fail(s.message);
+        return ok({ ok: true, created, ...report, ...versionOf(s) });
+    });
+    server.registerTool('portfolio_release_create', {
+        title: 'Create a release',
+        description: 'Add one release (a Release node) covering from–to, chained after the release whose window ends latest before it starts (and before the one that starts next), placed above the cards on the Timeline at its date and beside the release it follows on the Map. Its summary is for a business reader (plain text or HTML; outcomes before features). File cards into it with portfolio_release_file. One versioned write.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            name: z.string().min(1).max(200),
+            from: DATE,
+            to: DATE,
+            summary: z.string().max(20000).optional(),
+            highlights: z.array(z.string().max(300)).max(20).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        outputSchema: { id: z.string(), previous: z.string().nullable(), next: z.string().nullable(), version: z.number().optional() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        if (a.to < a.from)
+            return fail('to is before from.');
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const md = { name: a.name, from: a.from, to: a.to, summary: a.summary ? toHtml(a.summary) : '', draft: false, open: false, ...(a.highlights?.length ? { highlights: a.highlights } : {}) };
+        const r = addRelease(g.nodes, md, new Date());
+        const s = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: r.nodes }, a.expected_version);
+        if (!s.ok)
+            return fail(s.message);
+        return ok({ id: r.id, previous: r.prev, next: nextOf(r.nodes, r.id), ...versionOf(s) });
+    });
+    server.registerTool('portfolio_release_file', {
+        title: 'File cards into a release',
+        description: 'File cards into a release, each WITH its subtree (children by parent; from an objective, its key results\' linked epics). Only done cards are filed unless only_done is false (open ones are listed as left_open). A card in another release moves; a card already in this one is skipped. Filing never moves a card or touches its parent, edges or position: it sets releaseId and stamps doneAt once (doneAt ?? stateChangedAt ?? updatedAt). Refuses a DRAFT release (approve it first). One versioned write.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            release_id: z.string(),
+            item_ids: z.array(z.string()).min(1).max(500),
+            only_done: z.boolean().optional().describe('Default true — "file the done parts only".'),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const rel = findRelease(g, a.release_id);
+        if (!rel)
+            return fail(`${a.release_id} is not a release in this portfolio.`);
+        if (rel.data?.moduleData?.draft === true)
+            return fail('That release is a draft — approve it first (portfolio_release_approve); a draft files nothing.');
+        const cards = items(g);
+        const known = new Set(cards.map(n => n.id));
+        const missing = a.item_ids.filter(id => !known.has(id));
+        if (missing.length)
+            return fail(`Not cards in this portfolio: ${missing.join(', ')}`);
+        const ids = [...subtreeOf(a.item_ids, cards, g.edges)];
+        const patches = fileSet(ids, a.release_id, cards, { onlyDone: a.only_done });
+        const leftOpen = a.only_done === false ? [] : unfinishedIn(ids, cards);
+        const moved = patches.filter(p => releaseIdOf(cards.find(n => n.id === p.id)) !== null).map(p => p.id);
+        const already = ids.filter(id => releaseIdOf(cards.find(n => n.id === id)) === a.release_id);
+        const report = { filed: patches.length, filed_ids: patches.map(p => p.id), moved_from_other_release: moved, already_in_release: already, left_open: leftOpen };
+        if (!patches.length)
+            return ok({ ok: true, ...report });
+        const s = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: applyItemPatches(g.nodes, patches) }, a.expected_version);
+        if (!s.ok)
+            return fail(s.message);
+        return ok({ ok: true, ...report, ...versionOf(s) });
+    });
+    server.registerTool('portfolio_release_unfile', {
+        title: 'Un-file cards',
+        description: 'Take cards out of their release: item_ids (exactly those cards — no subtree), or release_id for every member of one release. Clears releaseId and KEEPS doneAt (a fact about the card, not the release); nothing else changes. One versioned write.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            item_ids: z.array(z.string()).min(1).max(500).optional(),
+            release_id: z.string().optional().describe('Un-file every member of this release.'),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        if (!a.item_ids === !a.release_id)
+            return fail('Pass item_ids or release_id (one of them).');
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const cards = items(g);
+        let ids;
+        if (a.release_id) {
+            if (!findRelease(g, a.release_id))
+                return fail(`${a.release_id} is not a release in this portfolio.`);
+            ids = membersOf(a.release_id, cards).map(n => n.id);
+        }
+        else {
+            const known = new Set(cards.map(n => n.id));
+            const missing = a.item_ids.filter(id => !known.has(id));
+            if (missing.length)
+                return fail(`Not cards in this portfolio: ${missing.join(', ')}`);
+            ids = a.item_ids;
+        }
+        const patches = unfileSet(ids, cards);
+        if (!patches.length)
+            return ok({ ok: true, unfiled: 0, unfiled_ids: [] });
+        const s = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: applyItemPatches(g.nodes, patches) }, a.expected_version);
+        if (!s.ok)
+            return fail(s.message);
+        return ok({ ok: true, unfiled: patches.length, unfiled_ids: patches.map(p => p.id), ...versionOf(s) });
+    });
+    server.registerTool('portfolio_release_approve', {
+        title: 'Approve a draft release',
+        description: 'Turn a DRAFT release into a release: files exactly the cards it proposes (still-done ones; each keeps its parent, edges and position, gets releaseId and doneAt once) and sets draft false, approvedAt now and proposed empty — all in one versioned write. Optionally set its name, summary (for a business reader; plain text or HTML) and highlights in the same write. Proposed cards no longer done or no longer present are listed as not_filed.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            release_id: z.string(),
+            name: z.string().min(1).max(200).optional(),
+            summary: z.string().max(20000).optional(),
+            highlights: z.array(z.string().max(300)).max(20).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const rel = findRelease(g, a.release_id);
+        if (!rel)
+            return fail(`${a.release_id} is not a release in this portfolio.`);
+        const md = (rel.data?.moduleData ?? {});
+        if (md.draft !== true)
+            return fail('That release is not a draft — nothing to approve.');
+        const proposed = Array.isArray(md.proposed) ? md.proposed.filter((x) => typeof x === 'string') : [];
+        const cards = items(g);
+        const patches = fileSet(proposed, a.release_id, cards);
+        const filed = new Set(patches.map(p => p.id));
+        const notFiled = proposed.filter(id => !filed.has(id) && releaseIdOf(cards.find(n => n.id === id) ?? { id }) !== a.release_id);
+        const modPatch = { draft: false, approvedAt: Date.now(), proposed: [] };
+        if (a.name !== undefined)
+            modPatch.name = a.name;
+        if (a.summary !== undefined)
+            modPatch.summary = toHtml(a.summary);
+        if (a.highlights !== undefined)
+            modPatch.highlights = a.highlights;
+        const nodes = patchReleaseData(applyItemPatches(g.nodes, patches), a.release_id, modPatch);
+        const s = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes }, a.expected_version);
+        if (!s.ok)
+            return fail(s.message);
+        return ok({ ok: true, release_id: a.release_id, filed: patches.length, filed_ids: patches.map(p => p.id), not_filed: notFiled, ...versionOf(s) });
+    });
+}