src/controls-plan.ts

Functions

Imports

It imports src/agents-archive.ts, src/agents-schema.ts, src/agents.ts, src/canon.ts, src/controls-base.ts, src/env.ts, src/github.ts, src/job-breaker.ts, src/jobs-edit.ts, src/jobs-seat.ts, src/jobs-transition.ts, src/limits.ts, src/merge-safety.ts, src/merge-units.ts, src/ops-packages.ts, src/ops-sites.ts, src/ops-types/portal.ts, src/overnight.ts, src/policy-sign.ts, src/pr-approvals.ts, src/roster.ts, src/site-operator.ts, src/site-repair.ts. Imported by src/controls.ts.

Source

1import { adminAgentForEmail } from "./agents";
2import { archivedAgentByName } from "./agents-archive";
3import { agentActor } from "./agents-schema";
4import { type SweepItem, checkProposal, lineChanges, readSweep } from "./canon";
5import {
6  type Surface,
7  AUTOMERGE_RESUME_REASON,
8  CANON_REJECT_REASON,
9  UNIT_RESUME_REASON,
10  clickAuditAction,
11  revisionOf,
12  shippedEvidence,
13  sweepOrder,
14  switchReasonRefusal,
15} from "./controls-base";
16import type { Env } from "./env";
17import { resolveRepo } from "./github";
18import { breakerState } from "./job-breaker";
19import { openTitleHolder } from "./jobs-edit";
20import { resumeDestination, workRecorded } from "./jobs-seat";
21import { readJob } from "./jobs-transition";
22import { MAX_RESUME_NOTE } from "./limits";
23import { planResume } from "./merge-safety";
24import { planLift } from "./merge-units";
25import { validatePackage, readPackageRow, describePackage } from "./ops-packages";
26import { validateSite, readSiteRow, describeSite, type SiteInput } from "./ops-sites";
27import type { PortalAction } from "./ops-types/portal";
28import { overnightValueRefusal, overnightState, type OvernightMode, decisionFor, OVERNIGHT_MODE_KEY } from "./overnight";
29import { planPolicyChange, planPolicyFromRepo } from "./policy-sign";
30import { planApproval } from "./pr-approvals";
31import { APP_ROSTER } from "./roster";
32import { toolRefusal, tokenSet } from "./site-operator";
33import { limitRefusalFor } from "./site-repair";
34
35// A control's preview (src/controls.ts is the core): reads the current state, writes
36// nothing, and returns what will change and the audit rows it will write.
37
38// bind: params the plan itself adds to the token, beside the caller's, so the perform
39// carries out what this preview read (canon_approve_all binds its plan this way).
40export type Plan = { ok: true; changes: string[]; audit: string[]; bind?: Record<string, string> } | { ok: false; refusal: string };
41
42const SITE_FIELDS = ["name", "origin", "health_path", "platform", "script"] as const;
43
44function shown(value: string | null): string {
45  return value === null ? "(none)" : `"${value}"`;
46}
47
48const refused = (refusal: string): Plan => ({ ok: false, refusal });
49
50// How many added and removed lines a canon_approve preview lists before it says how many
51// more there are. The whole body is in the proposal row.
52const CANON_PREVIEW_LINES = 40;
53function sweepChanges(items: readonly SweepItem[], reason: string | undefined, click: string): string[] {
54  const approvals = items.filter((i) => i.outcome === "approve");
55  const superseded = items.filter((i) => i.outcome === "superseded").length;
56  const outdated = items.filter((i) => i.outcome === "outdated").length;
57  const flagged = approvals.filter((i) => i.proposal.directive_lines.length);
58  const line = (i: SweepItem) => {
59    const p = i.proposal;
60    const target = `${p.namespace}/${p.path}`;
61    if (i.reason !== null) return `reject proposal ${p.id} (${target}, from ${p.proposer}): pending -> rejected, with the reason "${i.reason}". ${target} is not touched.`;
62    return `approve proposal ${p.id} (${target}, from ${p.proposer}): ${p.creates ? `${target} is created` : `${target} is overwritten, the current version snapshotted first`}; ${p.added} line(s) added, ${p.removed} removed.`;
63  };
64  return [
65    `${items.length} pending canon proposal(s): ${approvals.length} approved, ${items.length - approvals.length} rejected (${superseded} superseded, ${outdated} outdated). Rejections run first, then approvals, each its own decision; one that fails does not stop the rest.`,
66    ...(flagged.length
67      ? [
68          `${flagged.length} approval(s) add lines that read as instructions addressed to agents. Read them before approving:`,
69          ...flagged.flatMap((i) => i.proposal.directive_lines.map((l) => `instruction (proposal ${i.proposal.id}, ${i.proposal.namespace}/${i.proposal.path}): ${l}`)),
70        ]
71      : ["No approval adds a line that reads as an instruction addressed to agents."]),
72    ...sweepOrder(items).map(line),
73    ...(reason ? [`Your reason "${reason}" is recorded in the ${click} audit row.`] : []),
74  ];
75}
76
77function rosterRefusal(action: "reset_breaker", namespace: string | undefined): string | null {
78  if (!namespace) return `${action} needs a namespace.`;
79  if (namespace === "all") {
80    return `the Portal acts on one namespace at a time, so "all" is refused here. Do each of ${APP_ROSTER.join(", ")} in turn.`;
81  }
82  if (!(APP_ROSTER as readonly string[]).includes(namespace)) return `'${namespace}' is not on the roster (${APP_ROSTER.join(", ")}).`;
83  return null;
84}
85
86/** What the action will change, read from the state now. Reads only: no D1 write and
87 *  no KV put, which test/portal-actions.test.ts asserts for every action. */
88export async function planAction(env: Env, email: string, action: PortalAction, p: Record<string, string>, surface: Surface = "portal"): Promise<Plan> {
89  const actor = adminAgentForEmail(email).actor;
90  const click = `${clickAuditAction(action, p, surface)} by ${actor}`;
91  if (p.undo !== undefined && p.undo !== "true") return refused(`${action}'s undo is "true" or absent; got '${p.undo}'.`);
92  switch (action) {
93    case "reset_breaker": {
94      const bad = rosterRefusal(action, p.namespace);
95      if (bad) return refused(bad);
96      const state = await breakerState(env, p.namespace, new Date());
97      return {
98        ok: true,
99        changes: [
100          state.open
101            ? `The breaker for ${p.namespace} is OPEN: ${state.failed} holder fails since ${state.since} UTC, at or over the threshold of ${state.threshold}. After the reset only failures from now count, and ${p.namespace} hands out work again.`
102            : `The breaker for ${p.namespace} is closed (${state.failed} of ${state.threshold} holder fails since ${state.since} UTC). The reset moves its window to now.`,
103        ],
104        audit: [`job-breaker-reset by ${actor}`, click],
105      };
106    }
107    case "overnight": {
108      const bad = overnightValueRefusal(p.value);
109      if (bad) return refused(bad);
110      if (!p.reason) return refused(switchReasonRefusal(action));
111      const state = await overnightState(env);
112      const value = p.value as OvernightMode;
113      const decision = decisionFor(value, actor, new Date(), p.reason);
114      return {
115        ok: true,
116        changes: [
117          state.mode === value ? `${OVERNIGHT_MODE_KEY} is already ${value}; it is written again unchanged.` : `${OVERNIGHT_MODE_KEY}: ${state.mode} -> ${value}.`,
118          ...(decision
119            ? [
120                `Recorded with the switch: the decision of ${decision.decided_by} on ${decision.decided_on}, "${decision.ruling}".`,
121                `Reasoning recorded: ${decision.reasoning}`,
122                "Hand-started VS Code tabs are unaffected and stay the default.",
123              ]
124            : value === "api"
125              ? ["The scheduler will refuse to start a run unless it authenticates with ANTHROPIC_API_KEY and no subscription token is in use."]
126              : ["No scheduled run starts. Hand-started VS Code tabs are unaffected."]),
127        ],
128        audit: [`overnight-set by ${actor}`, click],
129      };
130    }
131    case "resume_job":
132    case "release_job":
133    case "fail_job": {
134      if (!p.id) return refused(`${action} needs a job id.`);
135      if (!p.reason) return refused(`${action} needs a reason. It is recorded in the audit row, and a transition with no reason is one nobody can review.`);
136      const job = await readJob(env.DB, p.id);
137      if (!job) return refused(`no job ${p.id}.`);
138      const label = `${job.id} ('${job.title}' in ${job.namespace})`;
139      if (action === "resume_job") {
140        if (p.note && p.note.length > MAX_RESUME_NOTE) {
141          return refused(`resume_job's note is at most ${MAX_RESUME_NOTE} characters, as for the capsid_work_jobs tool; this one is ${p.note.length}.`);
142        }
143        if (job.status !== "blocked") {
144          return refused(`${job.id} is ${job.status}, not blocked. Resume is how a job comes back off a gate; a queued job is claimed and a done or failed one is finished.`);
145        }
146        const holder = job.claimed_by || actor;
147        const { toQueue } = await resumeDestination(env, holder, job, false);
148        return {
149          ok: true,
150          changes: [
151            toQueue
152              ? `${label}: blocked -> queued, claimed by nobody. The resume records why: ${toQueue}`
153              : `${label}: blocked -> claimed by ${holder}. ${holder} continues it; it does not move to you.`,
154            `resumed_count: ${job.resumed_count} -> ${job.resumed_count + 1}.`,
155            `Your approval "${p.reason}" is recorded in the resume note the next holder reads${p.note ? `, with your note of ${p.note.length} character${p.note.length === 1 ? "" : "s"} in full` : ""}.`,
156          ],
157          audit: [`job-resumed by ${actor}`, click],
158        };
159      }
160      if (action === "release_job") {
161        if (job.status !== "claimed") {
162          return refused(`${job.id} is ${job.status}, not claimed. Release returns a claimed job to the queue; a blocked job is resumed, a queued one is already free, and a finished one is not reopened.`);
163        }
164        if (job.claimed_by === actor) return refused(`${job.id} is held by ${actor} itself. A holder ends its own claim with fail or block.`);
165        return {
166          ok: true,
167          changes: [
168            `${label}: claimed by ${job.claimed_by} -> queued, claimed by nobody.`,
169            `${job.claimed_by}'s claim ends, and no outcome is recorded against ${job.claimed_by}.`,
170          ],
171          audit: [`job-released by ${actor}`, click],
172        };
173      }
174      if (job.status !== "queued" && job.status !== "claimed" && job.status !== "blocked") {
175        return refused(`${job.id} is already ${job.status}; there is nothing to fail.`);
176      }
177      return {
178        ok: true,
179        changes: [
180          `${label}: ${job.status}${job.claimed_by ? ` (held by ${job.claimed_by})` : ""} -> failed, with the reason "${p.reason}".`,
181          job.claimed_by
182            ? `An outcome row records the failure against ${job.claimed_by}.`
183            : `Nobody held it, so no outcome row is written.`,
184        ],
185        audit: [`job-admin-fail by ${actor}`, click],
186      };
187    }
188    case "close_shipped": {
189      if (!p.id) return refused("close_shipped needs a job id.");
190      if (!p.reason) return refused("close_shipped needs a reason: what shipped, and how you know. It is the job's result summary.");
191      const job = await readJob(env.DB, p.id);
192      if (!job) return refused(`no job ${p.id}.`);
193      if (job.status !== "blocked") {
194        return refused(`${job.id} is ${job.status}, not blocked. Close as shipped ends a blocked job whose work landed; a claimed job is completed by its holder, and a queued or finished one has nothing to close.`);
195      }
196      if (job.claimed_by === actor) {
197        return refused(`${job.id} is blocked and held by ${actor} itself. A holder resumes its own gate and completes the job; close as shipped is for a job another credential blocked.`);
198      }
199      const shipped = shippedEvidence(job);
200      return {
201        ok: true,
202        changes: [
203          `${job.id} ('${job.title}' in ${job.namespace}): blocked -> done, with the result "Closed as shipped by ${actor}: ${p.reason}".`,
204          `The outcome row credits ${job.claimed_by ?? "nobody"}, who did the work. No claim is recorded for you; one admin_complete touch records that you closed it.`,
205          shipped.prs.length
206            ? `The outcome verifies ${shipped.prs.length} pull request${shipped.prs.length === 1 ? "" : "s"} against GitHub: ${shipped.prs.join(", ")}${shipped.more ? ` (${shipped.more} more named, left out)` : ""}.`
207            : "The job names no pull request, so the outcome verifies nothing.",
208          ...(job.review_required ? ["The job needs a review: the close is refused, and nothing written, unless the newest review on its pull request approves the head."] : []),
209        ],
210        audit: [`job-admin-complete by ${actor}`, click],
211      };
212    }
213    case "supersede_job": {
214      if (!p.id) return refused("supersede_job needs a job id.");
215      if (!p.reason) return refused("supersede_job needs a reason: what replaced this job, or why it was withdrawn.");
216      const job = await readJob(env.DB, p.id);
217      if (!job) return refused(`no job ${p.id}.`);
218      const label = `${job.id} ('${job.title}' in ${job.namespace})`;
219      if (job.status !== "queued" && job.status !== "claimed") {
220        return refused(`${job.id} is ${job.status}. Supersede closes a queued job, or a claimed one with no work recorded; ${job.status === "blocked" ? "a blocked job has hit a gate, so it is failed instead" : "a finished job is not rewritten"}.`);
221      }
222      const work = job.status === "claimed" ? workRecorded(job) : null;
223      if (work) return refused(`${job.id} has work recorded on it: ${work}. Fail it instead; supersede is for a job replaced before any work was done.`);
224      if (p.replaced_by) {
225        if (p.replaced_by === job.id) return refused(`${job.id} cannot be replaced by itself.`);
226        const replacement = await readJob(env.DB, p.replaced_by);
227        if (!replacement) return refused(`no job ${p.replaced_by}. replaced_by names the job that replaces this one, and it must exist.`);
228        if (replacement.namespace !== job.namespace) return refused(`${p.replaced_by} is in ${replacement.namespace} and ${job.id} is in ${job.namespace}. A job is replaced by work in its own namespace.`);
229      }
230      return {
231        ok: true,
232        changes: [
233          `${label}: ${job.status}${job.claimed_by ? ` (held by ${job.claimed_by})` : ""} -> superseded, with the summary "${p.replaced_by ? `Superseded by ${p.replaced_by}` : "Superseded"}: ${p.reason}".`,
234          `No outcome row is written against anybody, and one supersede touch records that you did it.`,
235        ],
236        audit: [`job-superseded by ${actor}`, click],
237      };
238    }
239    case "park_job": {
240      if (!p.id) return refused("park_job needs a job id.");
241      if (!p.reason || p.reason.length > 300 || /[\r\n]/.test(p.reason)) {
242        return refused("park_job needs a reason in one line, at most 300 characters, saying when the job comes back (\"comes back when ...\").");
243      }
244      const job = await readJob(env.DB, p.id);
245      if (!job) return refused(`no job ${p.id}.`);
246      if (job.status !== "queued") {
247        return refused(`${job.id} is ${job.status}. Park changes a queued job; a claimed or blocked one has somebody on it, so resume or supersede that instead.`);
248      }
249      return {
250        ok: true,
251        changes: [
252          `${job.id} ('${job.title}' in ${job.namespace}): queued -> parked, with "${p.reason}". It is never claimed and never planned while parked.`,
253          "It keeps its row, its priority and its mirror document, and Unpark puts it back in the queue.",
254        ],
255        audit: [`job-parked by ${actor}`, click],
256      };
257    }
258    case "unpark_job": {
259      if (!p.id) return refused("unpark_job needs a job id.");
260      const job = await readJob(env.DB, p.id);
261      if (!job) return refused(`no job ${p.id}.`);
262      if (job.status !== "parked") return refused(`${job.id} is ${job.status}, not parked.`);
263      const holder = await openTitleHolder(env.DB, job.namespace, job.title, job.id);
264      if (holder) {
265        return refused(`${job.namespace} already has another open job titled '${job.title}': ${holder.id} is ${holder.status}. One open job per (namespace, title), so ${job.id} stays parked.`);
266      }
267      return {
268        ok: true,
269        changes: [`${job.id} ('${job.title}' in ${job.namespace}): parked ("${job.result_summary ?? ""}") -> queued, at priority ${job.priority}. The next free session may claim it.`],
270        audit: [`job-unparked by ${actor}`, click],
271      };
272    }
273    case "approve_pr": {
274      const plan = await planApproval(env, actor, p, surface, click);
275      return plan.ok ? { ok: true, changes: plan.changes, audit: plan.audit } : refused(plan.refusal);
276    }
277    case "sign_policy_change": {
278      const plan = await planPolicyChange(env, p.change, p.unit);
279      return plan.ok ? { ok: true, changes: plan.changes, audit: [`policy-changed by ${actor}`, click] } : refused(plan.error);
280    }
281    case "sign_policy_from_repo": {
282      const plan = await planPolicyFromRepo(env);
283      // A typed version, when one comes with the preview, is checked now and bound into the token.
284      if (plan.ok && p.confirm && p.confirm !== plan.to) return refused(`${p.confirm} is not the version in docs/policy/auto-merge.md, which says ${plan.to}. Type ${plan.to} to sign it. Nothing was signed.`);
285      return plan.ok ? { ok: true, changes: plan.changes, audit: [`policy-loaded-from-repo by ${actor}`, click], bind: { source_sha: plan.newSha } } : refused(plan.error);
286    }
287    case "unit_resume": {
288      if (!p.reason) return refused(UNIT_RESUME_REASON);
289      const plan = await planLift(env.APP_KV, p.unit);
290      if (!plan.ok) return refused(plan.refusal);
291      return {
292        ok: true,
293        changes: [`${plan.unit}: suspended since ${plan.suspension.since} ("${plan.suspension.reason}") -> lifted. The tick may merge its pull requests unattended again; a rollback after now suspends it again.`],
294        audit: [`merge-unit-resumed by ${actor}`, click],
295      };
296    }
297    case "automerge_resume": {
298      if (!p.reason) return refused(AUTOMERGE_RESUME_REASON);
299      const plan = await planResume(env.APP_KV, p.namespace);
300      if (!plan.ok) return refused(plan.refusal);
301      return {
302        ok: true,
303        changes: [`${plan.namespace}: auto-merge paused since ${plan.paused.since} ("${plan.paused.reason}") -> lifted. The tick may merge its pull requests unattended again; new bad merges pause it again.`],
304        audit: [`auto-merge-resumed by ${actor}`, click],
305      };
306    }
307    case "pr_close": {
308      if (!p.namespace) return refused("pr_close needs the namespace whose repo holds the pull request.");
309      if (!p.number || !/^[1-9][0-9]{0,9}$/.test(p.number)) return refused(`pr_close needs the pull request's number; got '${p.number ?? ""}'.`);
310      if (!p.reason) return refused("pr_close needs a reason: why the pull request is closed without merging. It is recorded in the audit row.");
311      let full: string;
312      try {
313        full = (await resolveRepo(env, p.namespace, p.repo)).full;
314      } catch (err) {
315        return refused(err instanceof Error ? err.message : String(err));
316      }
317      return {
318        ok: true,
319        changes: [
320          `${full}#${p.number}: open -> closed, not merged. GitHub refuses it at perform if it is already closed or merged, and nothing is written then.`,
321          "Its head branch is deleted as capsid_close_pr action close deletes it: never the default branch, a loop branch or a fork's.",
322        ],
323        audit: [`pr-closed by ${actor}`, click],
324      };
325    }
326    case "site_add": {
327      const checked = validateSite(p);
328      if (!checked.ok) return refused(checked.refusal);
329      const site = checked.site;
330      const registered = await env.DB.prepare("SELECT namespace FROM namespaces WHERE namespace = ?1").bind(site.namespace).first<{ namespace: string }>();
331      if (!registered) return refused(`'${site.namespace}' is not a registered namespace. Register it first; a site row for an unregistered namespace is drift the watcher reports.`);
332      const existing = await readSiteRow(env.DB, site.namespace);
333      if (existing) return refused(`${site.namespace} already has a row (${describeSite(existing)}). Edit it instead.`);
334      return {
335        ok: true,
336        changes: [
337          `ops_sites: add ${site.namespace}, ${describeSite(site)}.`,
338          site.origin
339            ? `The watcher probes it from its next pass, and the Sites view lists it.`
340            : `Nothing is probed for ${site.namespace}; the site-map check counts it as decided.`,
341        ],
342        audit: [`ops-site-added by ${actor}`, click],
343      };
344    }
345    case "site_edit": {
346      const revision = revisionOf(p.revision);
347      if (revision === null) return refused("site_edit needs the revision of the row it edits.");
348      const checked = validateSite(p);
349      if (!checked.ok) return refused(checked.refusal);
350      const site: SiteInput = checked.site;
351      const before = await readSiteRow(env.DB, site.namespace);
352      if (!before) return refused(`${site.namespace} has no row to edit. Add it instead.`);
353      if (before.revision !== revision) return refused(`${site.namespace} changed since you opened it (revision ${before.revision}, not ${revision}). Reload and edit again.`);
354      const diffs = SITE_FIELDS.filter((f) => before[f] !== site[f]).map((f) => `${f}: ${shown(before[f])} -> ${shown(site[f])}`);
355      // The operator API, only when the edit names it: a form that does not show it leaves it.
356      const beforeOperator = before.operator ? JSON.stringify(before.operator) : null;
357      if (site.operator !== undefined && site.operator !== beforeOperator) diffs.push(`operator: ${shown(beforeOperator)} -> ${shown(site.operator)}`);
358      if (diffs.length === 0) return refused(`the edit changes nothing in ${site.namespace}.`);
359      const changes = [`ops_sites ${site.namespace}, revision ${revision} -> ${revision + 1}:`, ...diffs.map((d) => `  ${d}`)];
360      if (before.self_probe && before.origin !== site.origin) changes.push("The origin changes, so the in-process self-probe is cleared and the site is probed over HTTP.");
361      return { ok: true, changes, audit: [`ops-site-edited by ${actor}`, click] };
362    }
363    case "site_remove": {
364      const revision = revisionOf(p.revision);
365      if (!p.namespace || revision === null) return refused("site_remove needs a namespace and the revision of the row it removes.");
366      const before = await readSiteRow(env.DB, p.namespace);
367      if (!before) return refused(`${p.namespace} has no row to remove.`);
368      if (before.revision !== revision) return refused(`${p.namespace} changed since you opened it (revision ${before.revision}, not ${revision}). Reload and try again.`);
369      const registered = await env.DB.prepare("SELECT namespace FROM namespaces WHERE namespace = ?1").bind(p.namespace).first<{ namespace: string }>();
370      return {
371        ok: true,
372        changes: [
373          `ops_sites: remove ${p.namespace} (${describeSite(before)}). The row is kept in the audit row.`,
374          before.origin ? `The watcher stops probing ${before.origin}, and its uptime ring leaves the next pass.` : `Nothing was probed for it.`,
375          ...(registered ? [`${p.namespace} is still registered, so the site-map check reports it as unmapped until it has a row again.`] : []),
376        ],
377        audit: [`ops-site-removed by ${actor}`, click],
378      };
379    }
380    case "package_add": {
381      const checked = validatePackage(p);
382      if (!checked.ok) return refused(checked.refusal);
383      const existing = await readPackageRow(env.DB, checked.pkg.name);
384      if (existing) return refused(`${checked.pkg.name} is already configured (${describePackage(existing)}). Edit it instead.`);
385      return {
386        ok: true,
387        changes: [
388          `ops_packages: add ${describePackage(checked.pkg)}.`,
389          "The watcher reads it from its next pass: about nine requests to npm, deps.dev and GitHub per pass. The Packages view appears once a package is configured.",
390        ],
391        audit: [`ops-package-added by ${actor}`, click],
392      };
393    }
394    case "package_edit": {
395      const revision = revisionOf(p.revision);
396      if (revision === null) return refused("package_edit needs the revision of the row it edits.");
397      const checked = validatePackage(p);
398      if (!checked.ok) return refused(checked.refusal);
399      const before = await readPackageRow(env.DB, checked.pkg.name);
400      if (!before) return refused(`${checked.pkg.name} is not configured. Add it instead.`);
401      if (before.revision !== revision) return refused(`${checked.pkg.name} changed since you opened it (revision ${before.revision}, not ${revision}). Reload and edit again.`);
402      const diffs = (["repo", "formerly"] as const).filter((k) => before[k] !== checked.pkg[k]).map((k) => `  ${k}: ${shown(before[k])} -> ${shown(checked.pkg[k])}`);
403      if (diffs.length === 0) return refused(`the edit changes nothing in ${checked.pkg.name}.`);
404      return {
405        ok: true,
406        changes: [`ops_packages ${checked.pkg.name}, revision ${revision} -> ${revision + 1}:`, ...diffs],
407        audit: [`ops-package-edited by ${actor}`, click],
408      };
409    }
410    case "package_remove": {
411      const revision = revisionOf(p.revision);
412      if (!p.name || revision === null) return refused("package_remove needs a name and the revision of the row it removes.");
413      const before = await readPackageRow(env.DB, p.name);
414      if (!before) return refused(`${p.name} is not configured.`);
415      if (before.revision !== revision) return refused(`${p.name} changed since you opened it (revision ${before.revision}, not ${revision}). Reload and try again.`);
416      return {
417        ok: true,
418        changes: [`ops_packages: remove ${describePackage(before)}. The row is kept in the audit row, and its weekly GitHub rows stay.`],
419        audit: [`ops-package-removed by ${actor}`, click],
420      };
421    }
422    case "site_repair": {
423      if (!p.namespace || !p.tool) return refused("site_repair needs a namespace and a tool.");
424      const row = await readSiteRow(env.DB, p.namespace);
425      if (!row?.origin) return refused(`${p.namespace} is not a configured site.`);
426      if (!row.operator) return refused(row.operator_problem ?? `${p.namespace} has no operator API configured, so Capsid may call nothing on it.`);
427      const bad = toolRefusal(row.operator, p.tool);
428      if (bad) return refused(bad);
429      if (!tokenSet(env, row.operator)) return refused(`the Capsid Worker secret ${row.operator.auth_var} is not set, so nothing can be called on ${p.namespace}.`);
430      const wait = await limitRefusalFor(env, p.namespace, p.tool, new Date());
431      if (wait) return refused(`${p.tool} on ${p.namespace} waits: ${wait}`);
432      return {
433        ok: true,
434        changes: [
435          `POST ${row.origin}${row.operator.path} with tool ${p.tool}, authorized by the Capsid Worker secret ${row.operator.auth_var} (the token is never shown or recorded).`,
436          `The site re-derives that store from its source and reports a read-back verdict; the result is shown when it returns, up to a minute. One task_runs row (site-repair) records it.`,
437        ],
438        audit: [`site-repair by ${actor}`, click],
439      };
440    }
441    case "canon_approve":
442    case "canon_reject": {
443      const id = revisionOf(p.id);
444      if (id === null) return refused(`${action} needs the proposal id, a positive integer.`);
445      if (action === "canon_reject" && !p.reason) return refused(CANON_REJECT_REASON);
446      const checked = await checkProposal(env.DB, id, action === "canon_approve");
447      if (!checked.ok) return refused(checked.refusal);
448      const { row, current, directive } = checked;
449      const target = `${row.namespace}/${row.path}`;
450      if (action === "canon_reject") {
451        return {
452          ok: true,
453          changes: [`canon proposal ${id} (${target}, from ${row.proposer} at ${row.created_at}): pending -> rejected, with the reason "${p.reason}". ${target} is not touched.`],
454          audit: [`canon-rejected by ${actor}`, click],
455        };
456      }
457      const { added, removed } = lineChanges(current, row.body);
458      const shownLines = (label: string, lines: string[]) => [
459        ...lines.slice(0, CANON_PREVIEW_LINES).map((l) => `${label}: ${l}`),
460        ...(lines.length > CANON_PREVIEW_LINES ? [`${label}: and ${lines.length - CANON_PREVIEW_LINES} more line(s), in the proposal row`] : []),
461      ];
462      return {
463        ok: true,
464        changes: [
465          current === null
466            ? `${target} does not exist; it is created as ${row.proposer} proposed at ${row.created_at} (${row.mode}).`
467            : `${target} is overwritten as ${row.proposer} proposed at ${row.created_at} (${row.mode}). The current version is snapshotted first, so it can be restored.`,
468          `${added.length} line(s) added, ${removed.length} removed.`,
469          ...(directive.length
470            ? [`${directive.length} added line(s) read as instructions addressed to agents. Read them before approving:`, ...directive.map((l) => `instruction: ${l}`)]
471            : ["No added line reads as an instruction addressed to agents."]),
472          ...shownLines("added", added),
473          ...shownLines("removed", removed),
474          ...(row.title !== null || row.type !== null || row.tags !== null || row.status !== null
475            ? [`metadata set by the proposal: ${[["title", row.title], ["type", row.type], ["tags", row.tags], ["status", row.status]].filter(([, v]) => v !== null).map(([k, v]) => `${k} "${v}"`).join(", ")}.`]
476            : []),
477        ],
478        audit: [`write by ${actor}`, click],
479      };
480    }
481    case "canon_approve_all": {
482      const sweep = await readSweep(env.DB);
483      if (!sweep.ok) return refused(sweep.refusal);
484      const approves = sweep.items.some((i) => i.outcome === "approve");
485      const rejects = sweep.items.some((i) => i.outcome !== "approve");
486      return {
487        ok: true,
488        changes: sweepChanges(sweep.items, p.reason, clickAuditAction(action, p, surface)),
489        audit: [...(rejects ? [`canon-rejected by ${actor}`] : []), ...(approves ? [`write by ${actor}`] : []), click],
490        bind: { plan: sweep.key },
491      };
492    }
493    case "revoke_agent": {
494      if (!p.name) return refused("revoke_agent needs an agent name.");
495      const agent = await env.DB.prepare("SELECT name, kind, revoked_at FROM agents WHERE name = ?1")
496        .bind(p.name)
497        .first<{ name: string; kind: string; revoked_at: string | null }>();
498      if (!agent) {
499        const archived = await archivedAgentByName(env.DB, p.name);
500        return refused(archived ? `'${p.name}' was revoked at ${archived.revoked_at} and archived at ${archived.archived_at}.` : `no agent named '${p.name}'.`);
501      }
502      if (agent.revoked_at) return refused(`'${p.name}' was already revoked at ${agent.revoked_at}.`);
503      // Bounded: the limit is a guard, not a page.
504      const { results } = await env.DB.prepare(
505        `SELECT id, title, namespace, status FROM jobs WHERE claimed_by = ?1 AND status IN ('claimed', 'blocked') ORDER BY id LIMIT 50`
506      )
507        .bind(agentActor(p.name))
508        .all<{ id: string; title: string; namespace: string; status: string }>();
509      const held = results ?? [];
510      return {
511        ok: true,
512        changes: [
513          `agent ${p.name} (${agent.kind}): live -> revoked. Its key stops resolving on the next request, and the name can never be minted again.`,
514          held.length === 0
515            ? `It holds no claimed or blocked job.`
516            : `It holds ${held.length} job${held.length === 1 ? "" : "s"}, which stay as they are until released or failed: ${held
517                .map((j) => `${j.id} (${j.status}, '${j.title}' in ${j.namespace})`)
518                .join("; ")}.`,
519        ],
520        audit: [`agent-revoked by ${actor}`, click],
521      };
522    }
523  }
524}