toolroll 0.9.54 → 0.9.56

package/dist/subagents-ui.js

@@ -0,0 +1,137 @@
+import { labelOf, nameOf, summaryOf, SUBAGENT_MODELS, zonesOf } from "./subagent-admin.js";
+import { SUBAGENT_TEMPLATES } from "./subagents.js";
+import { projectToolsOf } from "./project-tools.js";
+import { callWords, defaultRule, numberFields, receiptWords } from "./subagent-tools.js";
+import { MEMORY_CHARS, searchMemories } from "./subagent-memory.js";
+import { deskOf, localZone, routinesOf } from "./subagent-desk.js";
+import { weekOf, weekWords } from "./subagent-week.js";
+import { describeSchedule, parseSchedule } from "./flow-schedule.js";
+import { html, joinHtml, postForm } from "./html.js";
+/** v94: the Tools section's rule rows; a limit's fields show only while "Up to a limit" is chosen. */
+export const SUBAGENT_CSS = `.subagent-tools .tool-grant{border-top:1px solid var(--so-line);padding-top:12px;margin-top:12px}.subagent-tools .tool-grant:first-of-type{border-top:0;margin-top:0;padding-top:0}.subagent-tools h3{font-size:1rem;margin:0 0 4px}.subagent-tools .tool-rule{display:grid;gap:6px;padding:10px 0;border-bottom:1px solid var(--so-line)}.subagent-tools .tool-rule:last-of-type{border-bottom:0}.subagent-tools .tool-rule .meta{display:block}.subagent-tools select,.subagent-tools input{max-width:100%;box-sizing:border-box}.subagent-tools .tool-limit{display:none;flex-wrap:wrap;align-items:center;gap:6px}.subagent-tools .tool-rule:has(option[value="limit"]:checked) .tool-limit{display:flex}.subagent-tools .tool-rule>select{width:auto;min-width:16em}.subagent-tools .tool-limit select{width:auto}.subagent-tools .tool-limit input{width:7em}.subagent-tools .tool-buttons{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}.subagent-tools button{min-height:44px}.subagent-activity li{overflow-wrap:anywhere}.subagent-memory .memory-tell,.subagent-memory .memory-search{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin:0 0 12px}.subagent-memory .memory-tell textarea{flex:1 1 280px}.subagent-memory .memory-search input{flex:1 1 220px}.subagent-memory button{min-height:44px}.subagent-memories{list-style:none;padding:0;margin:0}.subagent-memories li{padding:10px 0;border-top:1px solid var(--so-line);overflow-wrap:anywhere}.subagent-memories li:first-child{border-top:0}.subagent-memories .meta{display:block;font-size:.85rem}.subagent-memories details.memory-edit{border:0;padding:0;margin:2px 0 0;background:transparent;box-shadow:none}.memory-edit summary{cursor:pointer;min-height:32px;display:inline-flex;align-items:center;font-size:.85rem;font-weight:400;color:var(--so-muted)}.tool-undo{border:0;padding:0;margin:8px 0;background:transparent;box-shadow:none}.tool-undo summary{cursor:pointer;min-height:36px;display:inline-flex;align-items:center;font-size:.9rem}.tool-undo-row{display:flex;flex-wrap:wrap;gap:6px;align-items:center;margin:6px 0}.tool-undo-row select{width:auto}.subagent-overrides,.subagent-undo{padding-left:18px}.subagent-undo li{margin:6px 0}.subagent-undo form{display:inline}.subagent-week h3{font-size:1rem;margin:14px 0 4px}.subagent-week button{min-height:44px}.subagent-routines{list-style:none;padding:0;margin:8px 0}.subagent-routines li{display:grid;gap:4px;padding:10px 0;border-top:1px solid var(--so-line)}.subagent-routines li:first-child{border-top:0}.routine-buttons{display:flex;flex-wrap:wrap;gap:8px}.routine-buttons button,.routine-add button{min-height:44px}.routine-add{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin:8px 0}.routine-add label{display:grid;gap:4px;flex:1 1 200px}.routine-add label:first-of-type{flex:0 1 180px}.subagent-actions,.question-options{display:flex;flex-wrap:wrap;gap:8px;margin:8px 0}.subagent-actions form,.question-options form{margin:0}.memory-edit form{display:grid;gap:8px;margin-top:6px}.memory-buttons{display:flex;flex-wrap:wrap;gap:8px}@media(max-width:600px){.subagent-tools select,.subagent-tools input{font-size:16px}}`;
+const USES = [["free", "Do it"], ["limit", "Do it, up to a limit"], ["ask", "Ask first"], ["never", "Never"]];
+/** v94: which project tools it may use, and its rule for each action. */
+function toolsSection(store, mate, canManage) {
+    const name = nameOf(mate);
+    const tools = projectToolsOf(store, mate.repo);
+    const grants = store.subagentGrants(mate.id);
+    const toolsPage = `/settings/tools?repo=${encodeURIComponent(mate.repo)}`;
+    const granted = grants.map(grant => {
+        const gone = !tools.some(one => one.name === grant.tool);
+        const rows = grant.actions.map(action => {
+            const rule = grant.rules[action.name] ?? defaultRule(action);
+            const use = rule.use === "free" && rule.limit !== undefined ? "limit" : rule.use;
+            const numbers = numberFields(action);
+            const words = rule.use === "never" ? "Never" : rule.use === "ask" ? "Ask first" : rule.limit === undefined ? "Do it" : `Do it up to ${rule.limit.field} ${rule.limit.over}, ask first above`;
+            const about = action.about !== "" && html `<span class="meta">${action.about}</span>`;
+            if (!canManage)
+                return html `<li class="tool-rule"><span><strong>${action.name}</strong> · ${words}</span>${about}</li>`;
+            const field = `${grant.tool}-${action.name}`.replace(/[^A-Za-z0-9_-]/g, "-");
+            const limit = numbers.length > 0 && html `<span class="tool-limit">Ask first when <select name="field.${action.name}" aria-label="The number the limit is on">${numbers.map(one => html `<option value="${one}"${rule.limit?.field === one && html ` selected`}>${one}</option>`)}</select> is over <input type="number" name="over.${action.name}" min="0" step="any" value="${rule.limit === undefined ? "" : rule.limit.over}" aria-label="The limit"></span>`;
+            return html `<div class="tool-rule" data-tool-action="${action.name}"><label for="use-${field}"><strong>${action.name}</strong>${about}</label><select id="use-${field}" name="use.${action.name}">${USES.filter(([value]) => value !== "limit" || numbers.length > 0).map(([value, label]) => html `<option value="${value}"${value === use && html ` selected`}>${label}</option>`)}</select>${limit}</div>`;
+        });
+        const head = html `<h3>${grant.tool}</h3>${gone && html `<p class="problem">This project doesn't have ${grant.tool} any more, so ${name} can't use it.</p>`}`;
+        // v97: which action undoes which, for the Undo button on its receipts. Optional, so it's folded away.
+        const undoing = grant.actions.filter(one => !one.readOnly).map(action => {
+            const chosen = grant.rules[action.name]?.undo ?? "";
+            return html `<label class="tool-undo-row">${action.name} is undone by<select name="undo.${action.name}"><option value="">nothing</option>${grant.actions.filter(other => other.name !== action.name).map(other => html `<option value="${other.name}"${other.name === chosen && html ` selected`}>${other.name}</option>`)}</select></label>`;
+        });
+        const undoBox = undoing.length > 0 && html `<details class="tool-undo"${grant.actions.some(one => grant.rules[one.name]?.undo !== undefined) && html ` open`}><summary>Undo</summary><p class="meta">When an action has an opposite, a person can press Undo on its receipts: the opposite is called with the same input.</p>${undoing}</details>`;
+        return canManage
+            ? html `<div class="tool-grant" data-tool-grant="${grant.tool}">${head}${postForm(`/settings/lead/subagents/${mate.id}/tools`, html `${rows}${undoBox}<div class="tool-buttons"><button name="op" value="rules">Save rules</button><button name="op" value="revoke" class="secondary">Stop using ${grant.tool}</button></div>`, { hidden: { tool: grant.tool } })}</div>`
+            : html `<div class="tool-grant" data-tool-grant="${grant.tool}">${head}<ul>${rows}</ul></div>`;
+    });
+    const open = tools.filter(one => !grants.some(grant => grant.tool === one.name));
+    const add = !canManage ? null : tools.length === 0 ? html `<p class="meta">This project has no tools yet. <a href="${toolsPage}">Add one</a>, then let ${name} use it here.</p>`
+        : open.length === 0 ? null : postForm(`/settings/lead/subagents/${mate.id}/tools`, html `<label>Let ${name} use<select name="tool">${open.map(one => html `<option value="${one.name}">${one.name}${one.spec.about === "" ? "" : ` — ${one.spec.about.slice(0, 80)}`}</option>`)}</select></label><button>Add tool</button>`, { attrs: { class: "tool-add" }, hidden: { op: "grant" } });
+    if (grants.length === 0 && add === null)
+        return "";
+    return html `<section class="card subagent-tools" id="tools"><h2>Tools</h2>${grants.length === 0 && html `<p class="meta">${name} doesn't use any tools yet. Reading starts as “Do it”; everything else asks you first.</p>`}${granted}${add}</section>`;
+}
+const when = (at) => new Date(at).toLocaleString("en", { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+const startOfDay = () => { const day = new Date(); day.setHours(0, 0, 0, 0); return day.toISOString(); };
+/** Text whose line breaks show as breaks. */
+const lines = (text) => joinHtml(text.split("\n"), html `<br>`);
+/** A blank soul file: the sections a subagent reads, to fill in. */
+export const BLANK_SOUL = `---\nname: \nrole: \n---\n\n## Who you are\n\n\n## How you write\n\n\n## What you know\n\n\n## Decide on your own\n- \n\n## Ask first\n- \n\n## Never\n- \n`;
+export function subagentsListHtml(store, mates, projects, projectName, canCreate, notice) {
+    const rows = mates.map(mate => {
+        const today = store.subagentTurnsSince(mate.id, startOfDay());
+        const open = store.openSubagentQuestions([mate.id]).length;
+        return html `<article class="card" data-subagent="${mate.handle}"><div class="flow-row"><h2><a href="/settings/lead/subagents/${mate.id}">${labelOf(mate)}</a></h2><span class="flow-counts">${projectName(mate.repo)} · ${mate.state === "active" ? "Working" : "Paused"} · ${today} today${open > 0 ? ` · ${open} question${open === 1 ? "" : "s"} for you` : ""}</span></div></article>`;
+    });
+    const create = canCreate && projects.length > 0
+        ? html `<details class="card" id="add"${(mates.length === 0 || notice.adding === true) && html ` open`}><summary>Add subagent</summary>${postForm("/settings/lead/subagents/new", html `<label>Start from<select name="template">${SUBAGENT_TEMPLATES.map(one => html `<option value="${one.id}">${one.label}: ${one.about}</option>`)}<option value="blank">Blank: write its soul file yourself</option></select></label><label>Name<input name="name" maxlength="40" placeholder="keep the template's name"></label>${projects.length === 1 ? html `<input type="hidden" name="repo" value="${projects[0]}">` : html `<label>Project<select name="repo">${projects.map(repo => html `<option value="${repo}">${projectName(repo)}</option>`)}</select></label>`}<button>Add subagent</button>`, { attrs: { "data-new-subagent": true } })}</details>`
+        : "";
+    const intro = html `<p class="meta">Your lead's helpers. Each works within rules you write and asks you when they say to. The quickest start is a <a href="/kits">starter kit</a>.</p>`;
+    return html `<section class="subagents">${notice.problem && html `<p class="problem" role="alert">${notice.problem}</p>`}${notice.said && html `<p class="said" role="status">${notice.said}</p>`}${intro}${rows.length > 0 ? rows : html `<p class="meta">No subagents yet.</p>`}${create}</section>`;
+}
+/** v97: its week: what it did and cost, what people overrode, and calls that can be undone. */
+function weekSection(store, mate, canManage) {
+    const week = weekOf(store, mate, new Date());
+    const overrides = week.overrides.length > 0 && html `<h3>What you overrode</h3><ul class="subagent-overrides">${week.overrides.map(one => html `<li>${one.said}${one.href !== null && html ` · <a href="${one.href}">open</a>`} <span class="meta">${when(one.at)}</span></li>`)}</ul>`;
+    const undo = week.undoable.length > 0 && html `<h3>Undo</h3><ul class="subagent-undo">${week.undoable.map(one => html `<li data-undo="${one.call}"><span>${one.words}</span> <span class="meta">${when(one.at)}${one.href !== null && html ` · <a href="${one.href}">open</a>`}</span>${canManage && postForm(`/settings/lead/subagents/${mate.id}/week`, html `<button name="op" value="undo" class="secondary">Undo with ${one.undo}</button>`, { hidden: { id: one.call } })}</li>`)}</ul>`;
+    const send = canManage && postForm(`/settings/lead/subagents/${mate.id}/week`, html `<button name="op" value="send" class="secondary">Send the week's report</button>`);
+    return html `<details class="card subagent-week" id="week" open><summary>This week</summary><p class="subagent-week-said">${lines(weekWords(mate, week))}</p>${overrides}${undo}${send}</details>`;
+}
+/** v96: its desk — where messages to it by name and its routines land — and its routines. */
+function deskSection(store, mate, canManage) {
+    const name = nameOf(mate);
+    const desk = deskOf(store, mate);
+    const routines = routinesOf(store, mate);
+    const intro = html `<p class="meta">Message ${name} by name in your chat app, like “@${mate.handle} where's order 1042?”. It lands on ${desk === null ? "its desk" : html `<a href="/flows/${desk.id}">${name}'s desk</a>`}, and the answer comes back to you.</p>`;
+    const list = routines.length > 0 && html `<ul class="subagent-routines">${routines.map(one => html `<li data-routine="${one.id}"><span><strong>${scheduleWords(one.schedule)}</strong> · ${one.text}</span><span class="meta">${one.state === "paused" ? "Paused" : one.nextAt === null ? "" : `Next ${when(one.nextAt)}`}${one.lastAt !== null && ` · last ${when(one.lastAt)}${one.lastOutcome === null ? "" : `: ${one.lastOutcome}`}`}</span>${canManage && postForm(`/settings/lead/subagents/${mate.id}/routines`, html `<button name="op" value="run" class="secondary">Run now</button><button name="op" value="remove" class="secondary">Remove</button>`, { attrs: { class: "routine-buttons" }, hidden: { id: one.id } })}</li>`)}</ul>`;
+    const add = canManage && postForm(`/settings/lead/subagents/${mate.id}/routines`, html `<label>When<input type="text" name="schedule" maxlength="80" placeholder="weekdays 09:00" required></label><label>What to do<input type="text" name="text" maxlength="200" placeholder="Look up yesterday's refunds and tell me the total." required></label><button>Add routine</button>`, { attrs: { class: "routine-add" }, hidden: { op: "add" } });
+    return html `<section class="card subagent-desk" id="desk"><h2>Desk and routines</h2>${intro}${list}${add}${canManage && html `<p class="meta">A routine puts a card on its desk on that schedule (“weekdays 09:00”, “daily 17:00”, “monday 09:00”, “every 2 hours”; times are this computer's, ${localZone()}, unless you name one); the answer goes to ${mate.manager}.</p>`}</section>`;
+}
+/** A schedule's stored form ("weekdays:09:00@Europe/London") in words. */
+const scheduleWords = (text) => { const parsed = parseSchedule(text); return parsed === null ? text : describeSchedule(parsed); };
+/** v95: what it remembers — what its people told it, and what it kept from cards — to search, edit and forget. */
+function memorySection(store, mate, canManage, query) {
+    const name = nameOf(mate);
+    const all = store.subagentMemories(mate.id, { limit: 500 });
+    const shown = query === null || query.trim() === "" ? all.slice(0, 30) : searchMemories(store, mate, query);
+    const tell = canManage && postForm(`/settings/lead/subagents/${mate.id}/note`, html `<label class="sr-only" for="subagent-note">Tell ${name} something</label><textarea id="subagent-note" name="note" rows="2" maxlength="${MEMORY_CHARS}" placeholder="For example: this week, offer free shipping instead of a refund when you can."></textarea><button>Tell ${name}</button>`, { attrs: { class: "memory-tell" } });
+    const search = (all.length > 8 || (query ?? "") !== "") && html `<form method="get" action="/settings/lead/subagents/${mate.id}#memory" class="memory-search" role="search"><label class="sr-only" for="memory-q">Search what ${name} remembers</label><input id="memory-q" type="search" name="q" value="${query ?? ""}" placeholder="Search what ${name} remembers"><button class="secondary">Search</button></form>`;
+    const items = shown.map(one => {
+        const card = one.card === null ? null : store.getFlowCard(one.card);
+        const whence = one.source === "person" ? `${one.createdBy} told it` : card === null ? "it kept this" : html `it kept this from <a href="/flows/${card.flow}?card=${card.id}">${card.title.slice(0, 60)}</a>`;
+        const edit = canManage && html `<details class="memory-edit"><summary>Edit</summary>${postForm(`/settings/lead/subagents/${mate.id}/memory`, html `<label class="sr-only" for="memory-${one.id}">Memory</label><textarea id="memory-${one.id}" name="text" rows="2" maxlength="${MEMORY_CHARS}">${one.text}</textarea><div class="memory-buttons"><button name="op" value="edit">Save</button><button name="op" value="forget" class="secondary">Forget</button></div>`, { hidden: { id: one.id } })}</details>`;
+        return html `<li data-memory="${one.id}" data-source="${one.source}"><span>${one.text}</span> <span class="meta">${whence} · ${when(one.updatedAt)}</span>${edit}</li>`;
+    });
+    const empty = (query ?? "") !== "" ? html `<p class="meta">Nothing ${name} remembers matches that.</p>` : html `<p class="meta">Nothing yet. What you tell ${name} is kept here, and it keeps short facts from the cards it works.</p>`;
+    return html `<section class="card subagent-memory" id="memory"><h2>Memory</h2>${tell}${search}${shown.length === 0 ? empty : html `<ul class="subagent-memories">${items}</ul>`}${query === null && all.length > shown.length && html `<p class="meta">${all.length - shown.length} older ${all.length - shown.length === 1 ? "memory" : "memories"}: search to find them.</p>`}</section>`;
+}
+export function subagentPageHtml(store, mate, viewer, projectName, canManage, approvers, notice) {
+    const name = nameOf(mate);
+    const questions = store.openSubagentQuestions([mate.id]);
+    const asked = questions.map(question => {
+        const card = store.getFlowCard(question.card);
+        const flow = card === null ? null : store.getFlow(card.flow);
+        const mine = question.askedOf === viewer;
+        const cardLink = card === null || flow === null ? "a card" : html `<a href="/flows/${flow.id}?card=${card.id}">${card.title}</a>`;
+        const answer = mine && html `<div class="question-options">${question.options.map(one => postForm(`/settings/lead/subagents/questions/${question.id}/answer`, html `<button>${one.label}</button>`, { hidden: { choice: one.id } }))}</div>${postForm(`/settings/lead/subagents/questions/${question.id}/answer`, html `<label>Or answer in your words<textarea name="text" rows="2" maxlength="2000"></textarea></label><button>Answer</button>`, { attrs: { class: "question-reply" } })}`;
+        return html `<article class="card subagent-question" data-question="${question.id}"${question.suggestion !== null && html ` data-suggestion`}><p class="meta">${question.suggestion === null ? html `About ${cardLink}` : "Suggests a rule change"} · ${when(question.createdAt)}${!mine && ` · for ${question.askedOf}`}</p><p><strong>${question.question}</strong></p>${answer}</article>`;
+    });
+    const zones = zonesOf(store, mate);
+    const where = zones.length === 0
+        ? html `<p class="meta">Not on any zone yet. In a flow, choose ${name} under “Who decides” on a “Person decides” zone, or add a “Subagent handles it” zone.</p>`
+        : html `<ul>${zones.map(one => html `<li><a href="/flows/${one.flow}">${one.flowName}</a> · ${one.kind === "decides" ? "decides" : "handles"} ${one.title}</li>`)}</ul>`;
+    // What it did and why, with every tool call it made or asked to make (v94), newest first.
+    const events = [
+        ...store.subagentEvents(mate.id, 40).filter(one => one.kind !== "note").map(one => ({ kind: one.kind, said: one.said, card: one.card, at: one.at })),
+        ...store.subagentCallsOf(mate.id, 40).map(one => ({ kind: "call", said: `Used ${callWords(one.tool, one.action, one.input, 200)} · ${receiptWords(store, one)}`, card: one.card, at: one.createdAt })),
+    ].sort((a, b) => b.at.localeCompare(a.at)).slice(0, 40);
+    const activity = events.length === 0 ? html `<p class="meta">Nothing yet.</p>` : html `<ul class="subagent-activity">${events.map(one => {
+        const card = one.card === null ? null : store.getFlowCard(one.card);
+        return html `<li data-event="${one.kind}">${one.said}${card !== null && html ` · <a href="/flows/${card.flow}?card=${card.id}">open</a>`} <span class="meta">${when(one.at)}</span></li>`;
+    })}</ul>`;
+    const versions = store.subagentVersions(mate.id);
+    const latest = versions[0];
+    const manage = canManage && html `<div class="subagent-actions">${postForm(`/settings/lead/subagents/${mate.id}/state`, html `<button${mate.state === "active" && html ` class="secondary"`}>${mate.state === "active" ? `Pause ${name}` : `Resume ${name}`}</button>`, { hidden: { state: mate.state === "active" ? "paused" : "active" } })}${postForm(`/settings/lead/subagents/${mate.id}/summary`, html `<button class="secondary">Send today's summary</button>`)}</div>`;
+    const soul = html `<details class="card"${canManage && html ` open`}><summary>Soul file</summary><p class="meta">Who ${name} is and its rules, read every turn. Version ${mate.version}${latest !== undefined && ` · saved by ${latest.savedBy}, ${when(latest.savedAt)}`} · <a href="/settings/lead/subagents/${mate.id}/soul.md" download>Download</a></p>${canManage
+        ? postForm(`/settings/lead/subagents/${mate.id}/soul`, html `<label class="sr-only" for="subagent-soul">Soul file</label><textarea id="subagent-soul" name="soul" rows="24" class="mono" maxlength="12000" spellcheck="false">${notice.soulDraft ?? mate.soul}</textarea><button>Save</button>`, { attrs: { "data-soul-form": true } })
+        : html `<pre class="mono">${mate.soul}</pre>`}</details>`;
+    const settings = canManage && html `<details class="card"><summary>Settings</summary>${postForm(`/settings/lead/subagents/${mate.id}/settings`, html `<label>Model<select name="model">${SUBAGENT_MODELS.map(one => html `<option value="${one}"${(mate.model ?? "default") === one && html ` selected`}>${one === "default" ? "The lead chat's model" : one[0].toUpperCase() + one.slice(1)}</option>`)}</select></label><label>Turns a day, at most<input type="number" name="dailyTurns" min="1" max="2000" value="${mate.dailyTurns}"></label><label>Reports to<select name="manager">${[...new Set([mate.manager, ...approvers])].map(one => html `<option value="${one}"${one === mate.manager && html ` selected`}>${one}</option>`)}</select></label><button>Save settings</button>`)}${postForm(`/settings/lead/subagents/${mate.id}/state`, html `<button class="danger">Remove ${name} from the team</button>`, { attrs: { class: "danger-zone" }, hidden: { state: "removed" } })}</details>`;
+    return html `${notice.problem && html `<p class="problem" role="alert">${notice.problem}</p>`}${notice.said && html `<p class="said" role="status">${notice.said}</p>`}<p class="meta">${projectName(mate.repo)} · ${mate.state === "active" ? "Working" : "Paused: its decisions go to people"} · reports to ${mate.manager}</p>${manage}${questions.length > 0 && html `<section><h2>Questions</h2>${asked}</section>`}<section class="card"><h2>Today</h2><p class="subagent-summary">${lines(summaryOf(store, mate, startOfDay()).said)}</p></section>${weekSection(store, mate, canManage)}<section class="card"><h2>Works on</h2>${where}</section>${toolsSection(store, mate, canManage)}${deskSection(store, mate, canManage)}${memorySection(store, mate, canManage, notice.query ?? null)}${soul}<details class="card"><summary>What ${name} did</summary>${activity}</details>${settings}`;
+}

package/dist/{teammates.d.ts → subagents.d.ts}

@@ -1,6 +1,6 @@
 import { run, type ExecResult } from "./exec.js";
 import type { ContractResult } from "./contracts/contract.js";
-import { type TurnAnswer } from "./contracts/teammate-turn.js";
+import { type TurnAnswer } from "./contracts/subagent-turn.js";
 import { type Overrun } from "./text-limits.js";
 export declare const SOUL_CHARS = 12000;
 export type Soul = {
@@ -24,17 +24,17 @@ export declare function parseSoul(text: string): {
 };
 /** A soul file with one section replaced (by title, any case), or added at the end when it has no such section. */
 export declare function withSection(soul: string, title: string, text: string): string;
-/** Starters to copy and make your own. Every rule is plain words the teammate reads each turn. */
-export declare const TEAMMATE_TEMPLATES: readonly {
+/** Starters to copy and make your own. Every rule is plain words the subagent reads each turn. */
+export declare const SUBAGENT_TEMPLATES: readonly {
     id: string;
     label: string;
     about: string;
     soul: string;
 }[];
-export type { TurnAction, TurnAnswer } from "./contracts/teammate-turn.js";
+export type { TurnAction, TurnAnswer } from "./contracts/subagent-turn.js";
 /** Each field's limit, in characters: stated in the prompt before it answers (turnPrompt), and an answer over one is
- * asked once to shorten (teammateTurn); one still over is kept whole, never cut. "text" is what the next zones read;
- * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/teammate-turn.ts): the CLI would
+ * asked once to shorten (subagentTurn); one still over is kept whole, never cut. "text" is what the next zones read;
+ * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/subagent-turn.ts): the CLI would
  * refuse an answer a few characters over one whole. */
 export declare const TURN_LIMITS: {
     readonly answer: 60;
@@ -53,7 +53,7 @@ export type TurnContext = {
     role: string;
     flow: string;
     zone: string;
-    /** decide: a "Person decides" zone; handle: a "Teammate handles it" zone. */
+    /** decide: a "Person decides" zone; handle: a "Subagent handles it" zone. */
     kind: "decide" | "handle";
     instructions: string | null;
     /** decide: the draft being decided on (null: none), whether it can be sent back, and to whom hard ones go. */
@@ -111,7 +111,7 @@ export type TurnContext = {
 };
 export declare function turnPrompt(context: TurnContext): string;
 /**
- * A turn's answer, read through its contract (src/contracts/teammate-turn.ts) and then checked against what this zone
+ * A turn's answer, read through its contract (src/contracts/subagent-turn.ts) and then checked against what this zone
  * allows, each refusal naming its path (`action: "route" isn't one this zone allows`). Text is trimmed and kept whole
  * (a field over its limit is asked to shorten, turnOverruns); blank options are dropped, and an ask offers at most 4,
  * each cut to an answer's length, and a tool name is cut to 140, as they always were.
@@ -142,7 +142,7 @@ export declare const TURN_TIMEOUT_MS = 180000;
 type CommandRunner = (file: string, args: readonly string[], options: Parameters<typeof run>[2]) => Promise<ExecResult>;
 /** The production runner: Claude through this computer's sign-in, answering in the turn schema (TURN_MODEL_SCHEMA), with no tools, no MCP servers and no repository. */
 export declare function claudeTurnRunner(runner?: CommandRunner): TurnRunner;
-/** How a teammate is named to people: "Maya · Support". */
-export declare const teammateLabel: (soul: Pick<Soul, "name" | "role">) => string;
+/** How a subagent is named to people: "Maya · Support". */
+export declare const subagentLabel: (soul: Pick<Soul, "name" | "role">) => string;
 /** How its acts read in a card's history: "Maya (AI)". */
-export declare const teammateActor: (soul: Pick<Soul, "name">) => string;
+export declare const subagentActor: (soul: Pick<Soul, "name">) => string;

package/dist/{teammates.js → subagents.js}

@@ -1,19 +1,19 @@
 /**
- * AI teammates (v92): agents that work a flow's cards the way an employee
+ * subagents (v92): agents that work a flow's cards the way an employee
  * would, within rules a person wrote for them.
  *
- * A teammate is a soul file: who it is, how it writes, what it knows, what it
+ * A subagent is a soul file: who it is, how it writes, what it knows, what it
  * decides on its own, what it asks about first, and what it never does. It is
  * staffed on zones: a "Person decides" zone it decides (approve, send back,
- * or hand it to a person), or a "Teammate handles it" zone where it picks
+ * or hand it to a person), or a "Subagent handles it" zone where it picks
  * where the card goes and writes what the next zones send. It never acts
  * itself: each turn answers with one decision as JSON, through Claude with no
  * tools, no repository and no MCP servers, and Toolroll carries it out
  * within the zone's choices. The card is data, never instructions. (v94: it
  * may ask for a project tool call on its turn; Toolroll makes it, or
- * asks a person first, by the rules in teammate-tools.ts.)
+ * asks a person first, by the rules in subagent-tools.ts.)
  *
- * Teammates do flow work only: they never approve a code task, a merge or
+ * Subagents do flow work only: they never approve a code task, a merge or
  * spending — those stay with people (or a signed hands-off mode).
  */
 import { Buffer } from "node:buffer";
@@ -24,13 +24,13 @@ import { strictJsonParse } from "./converse.js";
 import { scanForSecrets } from "./evidence.js";
 import { run } from "./exec.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
-import { readTurnAnswer, TURN_MODEL_SCHEMA } from "./contracts/teammate-turn.js";
+import { readTurnAnswer, TURN_MODEL_SCHEMA } from "./contracts/subagent-turn.js";
 import { LIMITS } from "./decision.js";
 import { overruns, TEXT_LIMITS } from "./text-limits.js";
 export const SOUL_CHARS = 12_000;
 const HANDLE = /^[a-z0-9][a-z0-9-]{0,31}$/;
 /** A handle from a name: "Maya" → "maya". */
-export const handleOf = (name) => name.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "teammate";
+export const handleOf = (name) => name.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "subagent";
 export const isHandle = (value) => typeof value === "string" && HANDLE.test(value);
 /** A soul file read: its name and role (front matter) and its sections. */
 export function parseSoul(text) {
@@ -47,9 +47,9 @@ export function parseSoul(text) {
     const field = (key) => new RegExp(`^${key}:\\s*(.+)$`, "im").exec(front[1])?.[1]?.trim() ?? "";
     const name = field("name"), role = field("role");
     if (!/^[\p{L}][\p{L}\p{N} .'-]{0,39}$/u.test(name))
-        return { ok: false, problem: "Give the teammate a name of up to 40 letters, like “name: Maya”." };
+        return { ok: false, problem: "Give the subagent a name of up to 40 letters, like “name: Maya”." };
     if (role === "" || role.length > 40)
-        return { ok: false, problem: "Say what the teammate does in up to 40 characters, like “role: Support”." };
+        return { ok: false, problem: "Say what the subagent does in up to 40 characters, like “role: Support”." };
     const body = normal.slice(front[0].length);
     const sections = [];
     for (const part of body.split(/^## /m).slice(1)) {
@@ -57,7 +57,7 @@ export function parseSoul(text) {
         sections.push({ title: title.trim(), body: rest.join("\n").trim() });
     }
     if (sections.length === 0 || sections.every(one => one.body === ""))
-        return { ok: false, problem: "Write at least one section, like “## Who you are”, saying who the teammate is." };
+        return { ok: false, problem: "Write at least one section, like “## Who you are”, saying who the subagent is." };
     return { ok: true, soul: { name, role, sections } };
 }
 /** A soul file with one section replaced (by title, any case), or added at the end when it has no such section. */
@@ -73,8 +73,8 @@ export function withSection(soul, title, text) {
     return `${parts.join("").trimEnd()}\n`;
 }
 const soul = (name, role, parts) => `---\nname: ${name}\nrole: ${role}\n---\n\n${Object.entries(parts).map(([title, lines]) => `## ${title}\n${lines.join("\n")}`).join("\n\n")}\n`;
-/** Starters to copy and make your own. Every rule is plain words the teammate reads each turn. */
-export const TEAMMATE_TEMPLATES = [
+/** Starters to copy and make your own. Every rule is plain words the subagent reads each turn. */
+export const SUBAGENT_TEMPLATES = [
     {
         id: "support", label: "Support rep", about: "Answers customers, handles refunds and replacements within limits, and hands angry or costly cases to you.",
         soul: soul("Maya", "Support", {
@@ -121,10 +121,10 @@ export const TEAMMATE_TEMPLATES = [
     },
 ];
 /** Each field's limit, in characters: stated in the prompt before it answers (turnPrompt), and an answer over one is
- * asked once to shorten (teammateTurn); one still over is kept whole, never cut. "text" is what the next zones read;
- * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/teammate-turn.ts): the CLI would
+ * asked once to shorten (subagentTurn); one still over is kept whole, never cut. "text" is what the next zones read;
+ * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/subagent-turn.ts): the CLI would
  * refuse an answer a few characters over one whole. */
-export const TURN_LIMITS = { answer: TEXT_LIMITS.teammateAnswer, text: TEXT_LIMITS.stageOutput, note: LIMITS.note, question: TEXT_LIMITS.teammateQuestion, reason: TEXT_LIMITS.teammateReason, remember: TEXT_LIMITS.teammateRemember };
+export const TURN_LIMITS = { answer: TEXT_LIMITS.subagentAnswer, text: TEXT_LIMITS.stageOutput, note: LIMITS.note, question: TEXT_LIMITS.subagentQuestion, reason: TEXT_LIMITS.subagentReason, remember: TEXT_LIMITS.subagentRemember };
 /** The fields of an answer over their limits. */
 export function turnOverruns(answer) {
     return overruns({ answer: answer.answer, text: answer.text, note: answer.note, question: answer.question, reason: answer.reason, remember: answer.remember }, TURN_LIMITS);
@@ -186,7 +186,7 @@ export function turnPrompt(context) {
 /** How many options an ask offers, and the longest tool name and input a tool call may give. */
 const ASK_OPTIONS = 4, TOOL_NAME_CHARS = 140, TOOL_INPUT_CHARS = 8000;
 /**
- * A turn's answer, read through its contract (src/contracts/teammate-turn.ts) and then checked against what this zone
+ * A turn's answer, read through its contract (src/contracts/subagent-turn.ts) and then checked against what this zone
  * allows, each refusal naming its path (`action: "route" isn't one this zone allows`). Text is trimmed and kept whole
  * (a field over its limit is asked to shorten, turnOverruns); blank options are dropped, and an ask offers at most 4,
  * each cut to an answer's length, and a tool name is cut to 140, as they always were.
@@ -204,7 +204,7 @@ export function readTurn(value, context) {
     const refuse = (path, what) => ({ ok: false, issues: [{ path, kind: "bad-value", line: `${path}: ${what}` }] });
     if (!allowed.includes(answer.action))
         return refuse("action", `"${answer.action}" isn't one this zone allows (${allowed.map(one => `"${one}"`).join(", ")})`);
-    // A tool call is checked against the teammate's rules where it's carried out; here only that it names one and fits.
+    // A tool call is checked against the subagent's rules where it's carried out; here only that it names one and fits.
     if (answer.action === "use_tool" && answer.tool === "")
         return refuse("tool", "required for use_tool");
     if (answer.action === "use_tool" && answer.input.length > TOOL_INPUT_CHARS)
@@ -221,7 +221,7 @@ export const TURN_TIMEOUT_MS = 180_000;
 /** The production runner: Claude through this computer's sign-in, answering in the turn schema (TURN_MODEL_SCHEMA), with no tools, no MCP servers and no repository. */
 export function claudeTurnRunner(runner = run) {
     return async (request) => {
-        const dir = mkdtempSync(join(tmpdir(), "standing-orders-teammate-"));
+        const dir = mkdtempSync(join(tmpdir(), "standing-orders-subagent-"));
         const started = Date.now();
         try {
             const result = await runner("claude", [
@@ -259,7 +259,7 @@ function costOf(body) {
     const tokensIn = count("input_tokens") + count("cache_creation_input_tokens") + count("cache_read_input_tokens"), tokensOut = count("output_tokens");
     return { ...(cost === undefined ? {} : { costUsd: cost }), ...(tokensIn > 0 ? { tokensIn } : {}), ...(tokensOut > 0 ? { tokensOut } : {}) };
 }
-/** How a teammate is named to people: "Maya · Support". */
-export const teammateLabel = (soul) => `${soul.name} · ${soul.role}`;
+/** How a subagent is named to people: "Maya · Support". */
+export const subagentLabel = (soul) => `${soul.name} · ${soul.role}`;
 /** How its acts read in a card's history: "Maya (AI)". */
-export const teammateActor = (soul) => `${soul.name} (AI)`;
+export const subagentActor = (soul) => `${soul.name} (AI)`;

package/dist/subscription-chat.d.ts

@@ -1,16 +1,16 @@
-import { type MateHistoryMessage, type MateProviderAnswer, type MateToolSchema } from "./converse.js";
+import { type LeadHistoryMessage, type LeadProviderAnswer, type LeadToolSchema } from "./converse.js";
 import { run, type ExecResult } from "./exec.js";
 import type { SubscriptionChatProviderId } from "./store.js";
-export type SubscriptionMateRequest = {
+export type SubscriptionLeadRequest = {
     provider: SubscriptionChatProviderId;
     /** `default` lets the authenticated harness choose its current default. */
     model: string;
     system: string;
     dataDocument: string;
-    history: readonly MateHistoryMessage[];
-    tools: readonly MateToolSchema[];
+    history: readonly LeadHistoryMessage[];
+    tools: readonly LeadToolSchema[];
     /** A structured answer of another shape (the memory pass's verdict): this JSON Schema is the harness's
-     * `--json-schema` (Codex's `--output-schema`) in place of the mate envelope, and its JSON text comes back as the
+     * `--json-schema` (Codex's `--output-schema`) in place of the lead envelope, and its JSON text comes back as the
      * answer's text, unread, for the caller's own schema to parse. */
     outputSchema?: Record<string, unknown>;
     timeoutMs: number;
@@ -20,31 +20,31 @@ export type SubscriptionMateRequest = {
      * (Claude). Display only: the finished answer is still parsed whole. */
     onText?: (text: string) => void;
 };
-export type SubscriptionMateRunner = (request: SubscriptionMateRequest) => Promise<{
+export type SubscriptionLeadRunner = (request: SubscriptionLeadRequest) => Promise<{
     ok: true;
-    answer: MateProviderAnswer;
+    answer: LeadProviderAnswer;
 } | {
     ok: false;
     problem: string;
 }>;
 type CommandRunner = (file: string, args: readonly string[], options: Parameters<typeof run>[2]) => Promise<ExecResult>;
-/** The model-visible request. Tool results are already redacted by mateView. */
-export declare function composeSubscriptionMatePrompt(request: Omit<SubscriptionMateRequest, "provider" | "model" | "timeoutMs" | "signal">): string;
+/** The model-visible request. Tool results are already redacted by leadView. */
+export declare function composeSubscriptionLeadPrompt(request: Omit<SubscriptionLeadRequest, "provider" | "model" | "timeoutMs" | "signal">): string;
 /** Strictly turn the harness's structured output into the provider-neutral answer. */
-export declare function parseSubscriptionMateAnswer(text: string, usage?: {
+export declare function parseSubscriptionLeadAnswer(text: string, usage?: {
     tokensIn?: unknown;
     tokensOut?: unknown;
 }): {
     ok: true;
-    answer: MateProviderAnswer;
+    answer: LeadProviderAnswer;
 } | {
     ok: false;
     problem: string;
 };
 /** Production runner; injectable so tests never consume a subscription turn. */
-export declare function performSubscriptionMateRequest(request: SubscriptionMateRequest, runner?: CommandRunner): Promise<{
+export declare function performSubscriptionLeadRequest(request: SubscriptionLeadRequest, runner?: CommandRunner): Promise<{
     ok: true;
-    answer: MateProviderAnswer;
+    answer: LeadProviderAnswer;
 } | {
     ok: false;
     problem: string;

package/dist/subscription-chat.js

@@ -1,5 +1,5 @@
 /**
- * Subscription-backed transport for the mate.
+ * Subscription-backed transport for the lead.
  *
  * The direct API transport owns dollar reservations and native function
  * calls. A cached Codex or Claude login has neither an API key nor a
@@ -7,16 +7,16 @@
  * temporary directory and asks for the same tool-call envelope as strict
  * structured JSON. The harness receives no repository path, no project
  * instructions, no MCP servers, and no executable tool surface. Tool calls
- * are still interpreted and executed by mate.ts, where every act remains a
+ * are still interpreted and executed by lead.ts, where every act remains a
  * proposal that needs a human confirmation card.
  */
 import { Buffer } from "node:buffer";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { MATE_MAX_CALLS_PER_STEP, MATE_STEP_TEXT_CAP_BYTES, MATE_TOOL_CALL_CAP_BYTES, MATE_TOOL_CALL_ID_CAP_BYTES, strictJsonParse, tokenCount, } from "./converse.js";
+import { LEAD_MAX_CALLS_PER_STEP, LEAD_STEP_TEXT_CAP_BYTES, LEAD_TOOL_CALL_CAP_BYTES, LEAD_TOOL_CALL_ID_CAP_BYTES, strictJsonParse, tokenCount, } from "./converse.js";
 import { run } from "./exec.js";
-import { claudeStreamReader } from "./mate-progress.js";
+import { claudeStreamReader } from "./lead-progress.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 import { claudeLimitsOf, noteLimits } from "./provider-limits.js";
 import { claudeBillingFrom } from "./spend.js";
@@ -25,18 +25,18 @@ function outputSchema(tools) {
     return {
         type: "object",
         properties: {
-            text: { type: "string", maxLength: MATE_STEP_TEXT_CAP_BYTES },
+            text: { type: "string", maxLength: LEAD_STEP_TEXT_CAP_BYTES },
             // With no tools offered there is nothing to name: an empty enum is not
             // a valid schema, so the calls array is simply required to be empty.
             calls: tools.length === 0 ? { type: "array", maxItems: 0 } : {
                 type: "array",
-                maxItems: MATE_MAX_CALLS_PER_STEP,
+                maxItems: LEAD_MAX_CALLS_PER_STEP,
                 items: {
                     type: "object",
                     properties: {
-                        id: { type: "string", minLength: 1, maxLength: MATE_TOOL_CALL_ID_CAP_BYTES },
+                        id: { type: "string", minLength: 1, maxLength: LEAD_TOOL_CALL_ID_CAP_BYTES },
                         name: { type: "string", enum: tools.map(tool => tool.name) },
-                        argumentsJson: { type: "string", maxLength: MATE_TOOL_CALL_CAP_BYTES },
+                        argumentsJson: { type: "string", maxLength: LEAD_TOOL_CALL_CAP_BYTES },
                     },
                     required: ["id", "name", "argumentsJson"],
                     additionalProperties: false,
@@ -47,8 +47,8 @@ function outputSchema(tools) {
         additionalProperties: false,
     };
 }
-/** The model-visible request. Tool results are already redacted by mateView. */
-export function composeSubscriptionMatePrompt(request) {
+/** The model-visible request. Tool results are already redacted by leadView. */
+export function composeSubscriptionLeadPrompt(request) {
     return [
         request.system,
         "SUBSCRIPTION HARNESS PROTOCOL:",
@@ -68,7 +68,7 @@ function exactKeys(value, keys) {
     return actual.length === keys.length && [...keys].sort().every((key, index) => actual[index] === key);
 }
 /** Strictly turn the harness's structured output into the provider-neutral answer. */
-export function parseSubscriptionMateAnswer(text, usage = {}) {
+export function parseSubscriptionLeadAnswer(text, usage = {}) {
     const parsed = strictJsonParse(Buffer.from(text, "utf8"), RESPONSE_CAP_BYTES, 8);
     if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) {
         return { ok: false, problem: parsed.ok ? "not-an-object" : parsed.problem };
@@ -77,7 +77,7 @@ export function parseSubscriptionMateAnswer(text, usage = {}) {
     if (!exactKeys(body, ["text", "calls"]) || typeof body["text"] !== "string" || !Array.isArray(body["calls"])) {
         return { ok: false, problem: "wrong-shape" };
     }
-    if (Buffer.byteLength(body["text"], "utf8") > MATE_STEP_TEXT_CAP_BYTES || body["calls"].length > MATE_MAX_CALLS_PER_STEP) {
+    if (Buffer.byteLength(body["text"], "utf8") > LEAD_STEP_TEXT_CAP_BYTES || body["calls"].length > LEAD_MAX_CALLS_PER_STEP) {
         return { ok: false, problem: "over-cap" };
     }
     const calls = [];
@@ -87,20 +87,20 @@ export function parseSubscriptionMateAnswer(text, usage = {}) {
         const call = raw;
         if (!exactKeys(call, ["id", "name", "argumentsJson"]))
             return { ok: false, problem: "bad-tool-call" };
-        if (typeof call["id"] !== "string" || call["id"] === "" || Buffer.byteLength(call["id"], "utf8") > MATE_TOOL_CALL_ID_CAP_BYTES) {
+        if (typeof call["id"] !== "string" || call["id"] === "" || Buffer.byteLength(call["id"], "utf8") > LEAD_TOOL_CALL_ID_CAP_BYTES) {
             return { ok: false, problem: "bad-tool-call" };
         }
         if (typeof call["name"] !== "string" || call["name"] === "" || call["name"].length > 64 || typeof call["argumentsJson"] !== "string") {
             return { ok: false, problem: "bad-tool-call" };
         }
         const argumentsBytes = Buffer.from(call["argumentsJson"], "utf8");
-        if (argumentsBytes.byteLength > MATE_TOOL_CALL_CAP_BYTES)
+        if (argumentsBytes.byteLength > LEAD_TOOL_CALL_CAP_BYTES)
             return { ok: false, problem: "bad-tool-call" };
-        const args = strictJsonParse(argumentsBytes, MATE_TOOL_CALL_CAP_BYTES, 6);
+        const args = strictJsonParse(argumentsBytes, LEAD_TOOL_CALL_CAP_BYTES, 6);
         if (!args.ok || typeof args.value !== "object" || args.value === null || Array.isArray(args.value))
             return { ok: false, problem: "bad-tool-call" };
         const normalized = { id: call["id"], name: call["name"], args: args.value };
-        if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > MATE_TOOL_CALL_CAP_BYTES)
+        if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > LEAD_TOOL_CALL_CAP_BYTES)
             return { ok: false, problem: "bad-tool-call" };
         calls.push(normalized);
     }
@@ -186,10 +186,10 @@ function lastResultLine(stdout) {
     return "";
 }
 /** Production runner; injectable so tests never consume a subscription turn. */
-export async function performSubscriptionMateRequest(request, runner = run) {
+export async function performSubscriptionLeadRequest(request, runner = run) {
     const dir = mkdtempSync(join(tmpdir(), "standing-orders-mate-"));
     try {
-        const prompt = composeSubscriptionMatePrompt(request);
+        const prompt = composeSubscriptionLeadPrompt(request);
         const streaming = request.provider !== "codex-subscription" && request.onText !== undefined;
         const schema = request.outputSchema ?? outputSchema(request.tools);
         let command;
@@ -274,7 +274,7 @@ export async function performSubscriptionMateRequest(request, runner = run) {
         if (request.outputSchema !== undefined) {
             return { ok: true, answer: { text: output.text, calls: [], tokensIn: output.tokensIn, tokensOut: output.tokensOut, reportedCostMicrousd: null } };
         }
-        return parseSubscriptionMateAnswer(output.text, output);
+        return parseSubscriptionLeadAnswer(output.text, output);
     }
     finally {
         rmSync(dir, { recursive: true, force: true });

package/dist/surface.d.ts

@@ -1,10 +1,27 @@
+/**
+ * The declared command guide (arc 5): the agent-facing surface as data,
+ * dumped by `contract --commands`. This is DOCUMENTATION with a stable
+ * shape, not authority — legacy verbs do not execute from it,
+ * and the runtime envelope remains the truth. Its honest limits ride the
+ * envelope itself as SURFACE_NOTES, because a source comment is invisible
+ * to consumers (arc-5 review, finding 1).
+ *
+ * What the tests DO hold to the code: every root here is a routed verb
+ * and every routed verb appears here; every declared flag lives in the
+ * parser's global vocabulary with the declared arity; the subcommand
+ * inventories for task/publish/config/approver match the
+ * exported action lists their dispatchers consult; keyed mutations
+ * declare --key; notableReasons come from DOCUMENTED_REASONS. What they
+ * CANNOT prove — that a given flag is read by a given handler — is why
+ * SURFACE_NOTES.flags says "intended".
+ */
 import { type CommandFlag, type CommandRow, type RemotePolicy } from './contracts/cli.js';
 /** A guide row and its flags are derived from their schemas in src/contracts/cli.ts. */
 export type { CommandFlag, CommandRow, RemotePolicy };
 /** The guide's limits, stated machine-readably in every dump. */
 export declare const SURFACE_NOTES: {
-    readonly authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory";
-    readonly flags: "session flags are exact per operation; legacy flags are intended per command and may use a global parser vocabulary";
+    readonly authority: "documentation is not permission; legacy entries remain advisory";
+    readonly flags: "flags are intended per command and may use a global parser vocabulary";
     readonly reasons: "curated, not exhaustive — the runtime `reason` field is the truth; ignore tokens you do not recognize";
     readonly database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file";
 };