@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/chores/verdict.ts

@@ -1,46 +1,10 @@
-import type { ChoreLedgerEntry, ChoresReport, ProbeId, ProbeResult } from "../schemas/maintenance.js";
+import type { ChoreLedgerEntry, ChoreOutcome, ChoresReport, ProbeId, ProbeResult } from "../schemas/maintenance.js";
 import { type Chore, type ChoreContext, type ChoreFinding, CHORES, chorePrompt } from "./chores.js";
 import { probeSpec } from "./probes.js";
 
-/* FROM EVIDENCE TO A VERDICT, the one place that decides whether a chore is due, and the only place that is
- * allowed to. Both the Maintenance panel and its rail badge run this function over the same report, so the number
- * on the tile and the reason in the panel are the same computation and cannot drift apart.
- *
- * Six states, and the distinctions between them are the whole design:
- *
- *   not-applicable  this chore is not a QUESTION worth asking of this repository, there is no Dockerfile to
- *                slim, no pipeline to tighten, no documentation to re-read. Dropped from the panel entirely
- *                rather than shown as clear, because "clear" claims we checked, and there was nothing to check.
- *                The reason survives in the panel's scope note, so "why is there no Docker chore here?" has an answer.
- *   unavailable  we have not measured this. knip is not a devDependency; there is no lockfile to audit. Rendered
- *                greyed, never badged, and never collapsed into `clear`, a maintenance surface reporting a green
- *                repository it has never actually measured is worse than one that says nothing.
- *   clear        we measured, and there is nothing to do. This is the common state, and it has to be visibly
- *                reachable or the panel is just a list of complaints.
- *   snoozed      the owner said "not now". Still listed, still showing its evidence, silent until it lapses.
- *   stale        we measured, then work landed, and we have not measured since. The evidence is still shown; the
- *                CLAIM comes off it, because it describes a tree that no longer exists.
- *   due          there is something to do.
- *
- * The first three are all ways of saying "no", and keeping them apart is what makes the surface trustworthy: they
- * mean we cannot ask, we did not measure, and we measured and found nothing, three different claims, and only
- * the last one is reassurance.
- *
- * And one flag that is not a state: `settled`. A due chore that has been RE-MEASURED since a turn was spent on
- * it, and whose evidence did not move, stays due, because it is, but must never light the rail again. This is
- * what stops the surface repeating itself while a fix sits in review, and it is why the ledger stores a digest
- * rather than a timestamp: "ran 3 days ago" cannot tell you whether it ran against THIS.
- *
- * `stale` is the other half of that sentence, and it exists because the digest alone cannot tell the two apart.
- * A probe that never re-ran produces an unchanged digest for free, so "the fix did not move the numbers" and "we
- * have not looked since the fix" arrived at this function looking identical, and the panel showed the second as
- * the first, quoting a week-old count an hour after the work that invalidated it. Comparing the run's time to the
- * MEASUREMENT's time is what separates them, and it is a comparison of two numbers the report already carries.
- *
- * Nothing here can hide a problem. Snoozing and settling change whether the rail SPEAKS; the panel still shows
- * the chore, its evidence and its state. The one thing that removes a row entirely is `not-applicable`, and that
- * is not hiding, it is the absence of a subject, counted in the panel's scope note and expandable to the reason.
- * A maintenance surface you can quietly bury findings in is a maintenance surface nobody trusts. */
+// The one function deciding whether a chore is due, run by both the panel and its badge over the same report so
+// neither can drift from the other. Six states (not-applicable, unavailable and clear are different ways of saying no);
+// `settled` is a due chore re-measured with no change, still due but never re-badged.
 
 export type ChoreState = "due" | "clear" | "snoozed" | "stale" | "unavailable" | "not-applicable";
 
@@ -49,27 +13,23 @@ export interface ChoreVerdict {
     readonly repo: string;
     readonly state: ChoreState;
     readonly severity: ChoreFinding["severity"];
-    // Always present, in every state, "nothing to do" and "not measured" are answers a reader deserves in words.
+    // Always present in every state; "nothing to do" and "not measured" are answers a reader deserves in words.
     readonly headline: string;
     readonly detail: readonly string[];
     // The evidence identity. Empty for `unavailable`, where there is no evidence to identify.
     readonly digest: string;
-    /* WHEN THE EVIDENCE WAS TAKEN, the fact every row shows beside its numbers, and the one whose absence let a
-     * measurement from last Tuesday read as this morning's. Undefined when the verdict rests on no measurement at
-     * all: a survey is decided by the calendar, and an unavailable chore has nothing to be out of date. */
+    // When the evidence was taken; undefined when the verdict rests on no measurement (a survey, or unavailable).
     readonly measuredAt: number | undefined;
-    // The turn. Present only when there is something to do, a "start an agent" button on a clear chore is an
-    // invitation to spend money proving that nothing is wrong.
+    // Present only when there is something to do; offering it on a clear chore would invite proving nothing's wrong.
     readonly prompt: string | undefined;
     readonly lastRun: ChoreLedgerEntry | undefined;
-    // A turn has been spent on this chore, the evidence has been re-measured since and did not move, and the
-    // chore's cadence has not lapsed. Still due, still shown, never badged.
+    // A turn was spent, the evidence was re-measured since and didn't move, and the cadence hasn't lapsed: still due,
+    // still shown, never badged.
     readonly settled: boolean;
 }
 
-/* HOW OLD THE EVIDENCE IS: the OLDEST of the measurements a verdict rests on, because a claim is only as current
- * as the least current thing it was computed from. Undefined when it rests on none, a survey has no measurement,
- * and an unavailable chore's probe did not produce one. */
+// How old the evidence is: the oldest of the measurements a verdict rests on, since a claim is only as current
+// as the least current input. Undefined when it rests on none (a survey, or an unavailable probe).
 const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId, ProbeResult>): number | undefined => {
     const taken = needs.flatMap((id) => {
         const probe = probes.get(id);
@@ -78,14 +38,13 @@ const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId,
     return taken.length === 0 ? undefined : Math.min(...taken);
 };
 
-// A survey that is clear is clear because it was READ recently, and saying so is the only way its row means
-// anything, "nothing to do" under a chore that has no measurement would be a claim about the code rather than
-// about the calendar.
+// A clear survey says when it was last read, since "nothing to do" under a chore with no measurement would be a
+// claim about the code rather than the calendar.
 const clearHeadline = (chore: Chore, lastRun: ChoreLedgerEntry | undefined, nowMs: number): string =>
     chore.survey === true && lastRun !== undefined ? `Surveyed ${Math.round((nowMs - lastRun.ranAt) / 86_400_000)} days ago` : `Nothing to do`;
 
-// Why a chore could not be assessed, in the words of the thing that could not do it. Never invented: an
-// `unavailable` probe carries the tool's own reason, and a probe that has simply not run yet says that.
+// Why a chore couldn't be assessed, in the words of the thing that couldn't: never invented, an `unavailable`
+// probe carries the tool's own reason, an unrun one says it hasn't run yet.
 const unmeasuredDetail = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId, ProbeResult>): string[] =>
     needs.flatMap((id) => {
         const probe = probes.get(id);
@@ -96,9 +55,7 @@ const unmeasuredDetail = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId
         if (probe.state === `ok`) {
             return [];
         }
-        // An unavailable probe's reason already says what is missing ("no lockfile"), so prefixing it with "not
-        // available in this repository" only says the same thing twice. A failure has to keep its label: its
-        // reason is the tool's own output, which on its own reads as a fact rather than as a breakage.
+        // An unavailable probe's reason already says what's missing; prefixing it would just say the same thing twice.
         if (probe.state === `unavailable`) {
             return [`${spec.title} · ${probe.reason ?? `not available in this repository`}`];
         }
@@ -108,10 +65,8 @@ const unmeasuredDetail = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId
 export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLedgerEntry | undefined): ChoreVerdict => {
     const base = { chore, repo: context.repo, lastRun: ledger, settled: false, prompt: undefined } as const;
 
-    /* APPLICABILITY FIRST, before anything is measured or any evidence is read. A chore that does not apply is
-     * not "clear" and not "unmeasured", the question does not arise here, and every subsequent branch of this
-     * function would be answering it anyway. The cause is carried as the headline, because the scope note, which
-     * groups these rows BY it, is the only place it will ever be read. */
+    // Decided before anything is measured; the cause is carried as the headline since the scope note is the only place
+    // it is read.
     const inapplicable = chore.applies?.(context.signals);
     if (inapplicable !== undefined) {
         return { ...base, state: `not-applicable`, severity: `info`, headline: inapplicable, detail: [], digest: ``, measuredAt: undefined };
@@ -138,17 +93,11 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* Has the last run's settlement lapsed? A cadence of 0 means "this is decided by evidence alone", an advisory
-     * does not become worth looking at again because ninety days passed, it becomes worth looking at again when
-     * the advisory set changes. Anything with a cadence expires its own settlement, so "we looked and chose not to
-     * act" cannot silence a chore for good. */
+    // A cadence of 0 is decided by evidence alone; any other cadence expires its own settlement over time.
     const lapsed = ledger !== undefined && chore.cadenceMs > 0 && context.nowMs - ledger.ranAt >= chore.cadenceMs;
     const sameEvidence = ledger?.digest === finding.digest && !lapsed;
 
-    /* A SURVEY has no measurement, so the calendar is the whole trigger: it is due because it has been that long,
-     * and a run inside the current period settles it until the next one begins. Checked against the run's TIME
-     * rather than its digest, because a survey run three days into a quarter and one three days before its end
-     * are the same period but very different answers to "when was this last read?". */
+    // A survey's only trigger is the calendar, checked against the run's time rather than its digest.
     if (chore.survey === true && ledger !== undefined && context.nowMs - ledger.ranAt < chore.cadenceMs) {
         return {
             ...base,
@@ -176,10 +125,8 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* The agent looked at exactly this evidence and reported that there was nothing in it, knip's findings were
-     * all public entry points, the clones were all generated files. That verdict has to stick, or the next poll
-     * starts the same turn again and the surface has taught the owner that its rows are wrong. It stops sticking
-     * when the evidence changes (a different digest) or the cadence lapses. */
+    // The agent looked at exactly this evidence and found nothing there; that verdict sticks until the evidence changes
+    // or the cadence lapses.
     if (sameEvidence && ledger?.outcome === `clean`) {
         return {
             ...base,
@@ -192,13 +139,8 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
         };
     }
 
-    /* THE MEASUREMENT IS OLDER THAN THE WORK. A turn landed after the last time we looked, so the evidence below
-     * describes a tree that no longer exists, an hour after a run deleted the dead code, the row was still
-     * quoting the count from six days before it. `sameEvidence` cannot catch this: an unchanged digest is exactly
-     * what a probe that never re-ran produces, so the flag says "settled" at its most confident when it knows
-     * least. The chore steps down instead, evidence stays on the row, the CLAIM comes off it, and carries no
-     * prompt, because the honest next move is to measure again rather than to spend a second turn on a finding
-     * nobody has re-checked. It cannot badge either, which is what stops the tile lighting for work already done. */
+    // The measurement predates the last run: an unchanged digest is what a stale probe produces too, so the claim and
+    // prompt come off, not the evidence.
     if (ledger !== undefined && measuredAt !== undefined && ledger.ranAt > measuredAt) {
         return { ...base, state: `stale`, severity: `info`, headline: finding.headline, detail: finding.detail, digest: finding.digest, measuredAt };
     }
@@ -216,13 +158,35 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
     };
 };
 
-// The ledger is keyed by repo + chore, which is the grain a verdict is decided at: the same chore in two repos is
-// two independent questions with two independent answers.
+// Has anyone already answered this, and does the answer still stand; the digest is what makes this an answer
+// rather than a timestamp, since a run against evidence that has since changed answered a different question.
+export interface ChoreAnswer {
+    readonly outcome: ChoreOutcome;
+    readonly ranAt: number;
+}
+
+// What was concluded about this evidence, whenever that was: history, not standing. A lapsed chore still shows
+// its old answer, since that is a fact worth having before spending a second turn.
+export const choreAnswer = (verdict: ChoreVerdict): ChoreAnswer | undefined => {
+    const { lastRun, digest } = verdict;
+    // An empty digest identifies no evidence, so nothing can have been concluded about it (unavailable, not-applicable,
+    // plain clear).
+    if (lastRun === undefined || digest === `` || lastRun.digest !== digest) {
+        return undefined;
+    }
+    return { outcome: lastRun.outcome, ranAt: lastRun.ranAt };
+};
+
+// Whether there is anything left to start: `settled` or `stale`, not gated on `choreAnswer`, since a stale row
+// has nothing to press either way. A lapsed chore returns to full weight; expiry asks again.
+export const choreAnswered = (verdict: ChoreVerdict): boolean => verdict.settled || verdict.state === `stale`;
+
+// The ledger is keyed by repo + chore, the grain a verdict is decided at: the same chore in two repos is two
+// independent answers.
 export const ledgerKey = (repo: string, chore: string): string => `${repo}|${chore}`;
 
-/* Every chore in every repo, from one report. This is what both surfaces call, the panel groups the result, the
- * badge filters it, so there is exactly one traversal of the book in the codebase and adding a chore to CHORES
- * reaches both surfaces without touching either. */
+// Every chore in every repo, from one report; the single traversal both the panel and the badge call, so adding
+// a chore to CHORES reaches both without touching either.
 export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[] => {
     const ledger = new Map(report.ledger.map((entry) => [ledgerKey(entry.repo, entry.chore), entry]));
     return report.repos.flatMap(({ repo, probes, signals }) => {
@@ -231,17 +195,8 @@ export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[
     });
 };
 
-/* WHAT THE RAIL IS ALLOWED TO SAY. A badge must mean "something happened here that you don't already know about",
- * never "here is a statistic", the extension API states that bar and this is the function that holds this
- * surface to it. Three filters, and every one of them removes a case that would otherwise light the tile forever:
- *
- *   state === due   the obvious one, and it is also what keeps `stale` silent, since a measurement taken before
- *                   the last turn is not a fact anyone should be interrupted about.
- *   !settled        a turn has been spent on this chore and the re-measured evidence did not move.
- *   unseen digest   the owner has already LOOKED at this evidence in the panel. Acknowledgement is per digest
- *                   rather than per chore, so acknowledging today's finding does not also swallow tomorrow's.
- *
- * `seen` maps ledgerKey → the digest last acknowledged. It lives in a file beside the ledger, because the badge is
- * derived from files and its acknowledgement belongs in the same tree. */
+// What the rail may say: something happened you don't already know about, never a statistic. Filters out:
+// - not due, or settled (a turn already re-measured this with no change)
+// - already acknowledged at this exact digest in the panel
 export const unseenVerdicts = (verdicts: readonly ChoreVerdict[], seen: Readonly<Record<string, string>>): ChoreVerdict[] =>
     verdicts.filter((verdict) => verdict.state === `due` && !verdict.settled && seen[ledgerKey(verdict.repo, verdict.chore.id)] !== verdict.digest);

package/src/contracts/accounts.contract.ts

@@ -14,23 +14,9 @@ import {
 } from "../schemas/provider-oauth.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* THE ACCOUNTS THIS SANDBOX HOLDS ITSELF, one route family with the provider as a PARAMETER.
- *
- * Four families used to serve this (Claude's, Cursor's, Grok's, and one for every provider whose sign-in mints
- * its own key), each "the previous one's shape" with a verb renamed: `oauth/start` here, `login/start` there,
- * an `exchange` for the flow whose proof travelled and a `complete` for the one whose proof did not. The
- * lesson providers.contract.ts learned about model catalogs holds for accounts too: the operations are the
- * same six for all of them, so the id is a parameter and a provider's own mechanism is its module's to declare
- * (the daemon's ProviderModule.accounts), not a vertical slice through the contract, the router and every test
- * double.
- *
- * WHY NOT THE TRANSLATOR ROUTES. Those address subscriptions CLIProxyAPI holds and re-serves behind an Anthropic
- * endpoint; these credentials live in this daemon's own auth tree (or, for Grok, in OpenCode's), and a
- * disconnect here removes a file rather than asking a proxy to forget one. A provider served both ways (Grok)
- * has a row in each.
- *
- * Nothing redeemable is on any answer here: `accounts` is an OauthAccount list, whose shape has no field a
- * credential could ride in, and a sign-in's proof never leaves the sandbox (provider-oauth.ts, LoginStart). */
+// One route family for the accounts this sandbox holds itself, with the provider as a parameter rather than a vertical
+// slice per provider. Distinct from the translator routes (subscriptions proxied through CLIProxyAPI): these
+// credentials live in this daemon's own auth tree, and no credential ever rides in an answer.
 export const accountsContract = {
     start: oc
         .route({
@@ -61,8 +47,7 @@ export const accountsContract = {
         })
         .input(NativeProviderParamSchema.extend(LoginCancelSchema.shape))
         .output(OkSchema),
-    // Each account carries its plan-limit reading where the provider publishes one. `force` re-measures before
-    // answering (AccountListQuerySchema); a provider with nothing to measure accepts it and answers at once.
+    // `force` re-measures before answering; a provider with nothing to measure accepts it and answers at once.
     accounts: oc
         .route({
             method: "GET",

package/src/contracts/agent.contract.ts

@@ -1,15 +1,14 @@
 import { eventIterator, oc } from "@orpc/contract";
-import { AgentCommandsQuerySchema, AgentCommandsSchema, AttachFrameSchema } from "../events.js";
+import { AgentCommandsQuerySchema, AgentCommandsSchema } from "../events/cards.js";
+import { AttachFrameSchema } from "../events/agent-events.js";
 import { AgentTurnSchema, AttachTurnSchema, StartedTurnSchema } from "../schemas/agent.js";
 import { RewindResultSchema, RewindTurnSchema } from "../schemas/history.js";
 import { AgentReplySchema, ProviderRefusalsSchema, ResumeTurnSchema, SteerSchema, StopTurnSchema } from "../schemas/plan-limits.js";
 import { OkSchema } from "../schemas/shared.js";
 
-// A turn EXECUTES as a detached daemon-side run: `run` starts it and acks with the run id; any number of
-// clients render it via `attach` (replay from a seq cursor, then live), the initiating window holds no
-// special stream, so a reload, a second window, or another device attaches identically. `reply` un-parks a
-// turn waiting on any interactive card (plan approval, clarifying questions, a per-tool permission prompt);
-// steer injects a user message into the running turn; stop hard-cancels it daemon-side.
+// A turn executes as a detached daemon-side run. `run` starts it, `attach` streams it to any number of clients
+// (replay then live, no special stream for the initiator), `reply` un-parks it, `steer` injects a message, `stop`
+// hard-cancels it.
 export const agentContract = {
     run: oc
         .route({
@@ -60,14 +59,7 @@ export const agentContract = {
         })
         .input(StopTurnSchema)
         .output(OkSchema),
-    /* Run the conversation's HELD turn again: the one a spent allowance refused, which the daemon kept whole.
-     * NOT_FOUND when it holds none (nothing was stranded, another turn has since superseded it, or the daemon
-     * restarted), which is what tells a client to fall back to saying something itself.
-     *
-     * Separate from `run` because it is a different act. `run` says something new; this repeats something already
-     * said, and the difference has to survive onto the wire or it cannot survive into the transcript: a repeat
-     * sent as a new turn is a new user message, and four presses against one spent allowance then read back, to
-     * the model as much as to the reader, as four things the user said and nobody answered. */
+    // NOT_FOUND when nothing is held (superseded, or the daemon restarted): the client should fall back to `run`.
     resume: oc
         .route({
             method: "POST",
@@ -78,9 +70,7 @@ export const agentContract = {
         })
         .input(ResumeTurnSchema)
         .output(StartedTurnSchema),
-    // Go back to a message: restore the workspace to that turn's checkpoint, drop the messages after it, and
-    // forget the provider session. CONFLICT while a turn is running, a restore cannot overwrite files an
-    // agent is editing. NOT_FOUND when that message has no checkpoint to go back to.
+    // CONFLICT while a turn is running; NOT_FOUND when the message has no checkpoint.
     rewind: oc
         .route({
             method: "POST",
@@ -91,8 +81,6 @@ export const agentContract = {
         })
         .input(RewindTurnSchema)
         .output(RewindResultSchema),
-    // The provider's slash commands as last published by one of its turns, so a conversation's `/` popover is
-    // populated before it has run one. The live `commands` frame stays authoritative for a running turn.
     commands: oc
         .route({
             method: "GET",
@@ -103,9 +91,6 @@ export const agentContract = {
         })
         .input(AgentCommandsQuerySchema)
         .output(AgentCommandsSchema),
-    // The last refusal per provider, as reported by whichever turn was refused (ProviderRefusalSchema). Read
-    // alongside the account listings by the surfaces that draw plan limits: the snapshot on an account row says
-    // how full its pools were when last polled, and this says whether one of them has since said no.
     refusals: oc
         .route({
             method: "GET",

package/src/contracts/agents.contract.ts

@@ -1,5 +1,5 @@
 import { oc } from "@orpc/contract";
-import { AgentTranscriptSchema } from "../events.js";
+import { AgentTranscriptSchema } from "../events/transcript.js";
 import {
     AgentArchiveSchema,
     AgentAutoLandSchema,
@@ -11,6 +11,7 @@ import {
     AgentPlaceSchema,
     AgentRenameSchema,
     AgentResumeAfterLimitSchema,
+    AgentMoveAfterLimitSchema,
     AgentResumeAfterOutageSchema,
     AgentsArchivedSchema,
     AgentSearchQuerySchema,
@@ -25,30 +26,9 @@ import { AgentChangesSchema, AgentHistorySchema } from "../schemas/git.js";
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema } from "../schemas/shared.js";
 
-// The fleet: every registered conversation-agent (see AgentSummarySchema). Registry-level actions (read,
-// rename, seen, archive) apply uniformly. For branch-backed conversations, `diff` is the worktree's CUMULATIVE
-// multi-repo delta vs its recorded per-repo bases, one flat change set per repo
-// (AgentChanges), each file flagged `landed` or not, deliberately not the working tree's staged/unstaged
-// shape: a worktree the user never checks out has no index they could stage into. `land` merges the worktree
-// branches into the main tree (per-repo, conflicts reported, nothing lost on failure); `discard` removes
-// worktrees + branches + registry entry. Those branch actions reject workspace conversations explicitly. An
-// unknown {id} is NOT_FOUND; land/discard while the turn runs is CONFLICT.
-// `rename` sets the user-chosen display title, legal mid-turn (it touches no worktree state).
-// `seen`/`seenAll` stamp the read marker behind the cards' unread badge (AgentSummarySchema.seenAt), also
-// legal mid-turn, and like `rename` they never bump `updatedAt` (reading is not activity).
-//
-// ARCHIVE is the non-destructive counterpart to discard, and the one the board leans on: for an isolated
-// conversation, `archive` commits whatever the worktree still holds onto agent/<id> and drops the CHECKOUT;
-// for a workspace conversation it has no git teardown. Both keep the entry and transcript. `list` stops carrying it and
-// `archived` does; `unarchive` puts it back, and either way the next turn re-attaches a worktree from the
-// surviving branch. Archiving a running agent is CONFLICT, same as land/discard.
-//
-// PURGE empties the archive, and it is `discard` applied to every agent already in there: worktree remnants,
-// branches and entries all go. Deliberately the whole archive and not a list of ids, the archive is the pile
-// of agents the user has already decided are over, so "clean it up" is one act with one confirmation, and a
-// per-id purge would be `discard`, which already exists. Never touches a running agent (a turn un-archives its
-// own agent, so there should be none) and answers with what it actually deleted: a teardown that fails on one
-// agent's repo leaves that one behind rather than taking the batch down with it.
+// Every registered conversation-agent (AgentSummarySchema); an unknown {id} is NOT_FOUND across this whole family.
+// `archive` is the non-destructive counterpart to `discard` (worktree committed, entry kept); `purge` is `discard`
+// applied to every already-archived agent.
 export const agentsContract = {
     list: oc
         .route({
@@ -68,10 +48,7 @@ export const agentsContract = {
                 "The same shape as the live fleet, for the conversations somebody has decided are finished. Their work is kept, and any one of them can be brought back.",
         })
         .output(AgentsListSchema),
-    // The board's filter. Answers over BOTH halves of the fleet, the live roster and the archive, because
-    // the board hides by design (the Finished lane windows to a handful, archived agents are off the roster
-    // entirely), and a filter that reports "no matches" while the agent sits one click away is a lie. The
-    // never-carded conversations that are neither are `sessions.list`'s query, which matches by the same rule.
+    // Never-carded conversations (neither live nor archived) are `sessions.list`'s query, matching by the same rule.
     search: oc
         .route({
             method: "GET",
@@ -101,12 +78,8 @@ export const agentsContract = {
         })
         .input(AgentTranscriptQuerySchema)
         .output(AgentTranscriptSchema),
-    /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
-     * turn behind them and no reply. The row is marked `placed` for human readers (TranscriptRowSchema); the
-     * provider session is FORGOTTEN in the same breath, rewind-style, so the next real turn opens a fresh
-     * runtime session seeded from the record, where the placed line reads as the agent's own words, because
-     * the handoff renders every assistant row identically. A running turn is CONFLICT: the illusion can only be
-     * established between turns, and a concurrent turn would resume the very session this exists to retire. */
+    // Also forgets the provider session, rewind-style, so the next fresh session reads the placed line as the agent's
+    // own.
     place: oc
         .route({
             method: "POST",
@@ -127,9 +100,6 @@ export const agentsContract = {
         })
         .input(AgentRenameSchema)
         .output(AgentSummarySchema),
-    // This agent's own land-at-completion posture, an override of the sandbox-wide `autoLand` setting; null
-    // clears it back to "inherit". Legal mid-turn on purpose: the setting is read at turn COMPLETION, so
-    // flipping it while the agent works is exactly "hold THIS turn's work for review", the press that matters.
     autoLand: oc
         .route({
             method: "POST",
@@ -140,13 +110,7 @@ export const agentsContract = {
         })
         .input(AgentAutoLandSchema)
         .output(AgentSummarySchema),
-    /* THIS conversation's answer to a provider outage, an override of the sandbox-wide `resumeAfterOutage`
-     * setting; null clears it back to "inherit". The chat's offer at the moment a turn dies writes this and
-     * never the global: the press happens inside one conversation and means "finish this piece of work", so
-     * its honest scope is that conversation. Sandbox > Agent owns the default for everything else.
-     *
-     * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too, an outage kills a
-     * main-tree chat exactly as readily as an isolated one, and there is no branch involved either way. */
+    // Legal for a workspace conversation too (unlike autoLand): an outage kills a main-tree chat just as readily.
     resumeAfterOutage: oc
         .route({
             method: "POST",
@@ -157,13 +121,7 @@ export const agentsContract = {
         })
         .input(AgentResumeAfterOutageSchema)
         .output(AgentSummarySchema),
-    /* THIS conversation's answer to a spent allowance, the same override in the same shape as the outage one
-     * above; null clears it back to "inherit". Offered on the CARD as well as in the chat, which is the one
-     * placement difference worth stating: an outage is over in minutes and is met by whoever is in the room,
-     * while a limit reopens hours later, so the person deciding is usually looking at a board rather than at a
-     * transcript.
-     *
-     * Legal mid-turn, and for a workspace conversation, for the same two reasons its neighbour is. */
+    // Also offered on the card, not just chat: a limit reopens hours later, so the decider is usually at a board.
     resumeAfterLimit: oc
         .route({
             method: "POST",
@@ -174,6 +132,17 @@ export const agentsContract = {
         })
         .input(AgentResumeAfterLimitSchema)
         .output(AgentSummarySchema),
+    // Moves the held turn the moment the refusal lands, not on the next attempt.
+    moveAfterLimit: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/move-after-limit",
+            summary: "Whether this conversation moves to another account when its allowance is spent",
+            description:
+                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. A move spends a second account of the same provider on this conversation's behalf, so it is off unless asked for.",
+        })
+        .input(AgentMoveAfterLimitSchema)
+        .output(AgentSummarySchema),
     seen: oc
         .route({
             method: "POST",
@@ -184,17 +153,7 @@ export const agentsContract = {
         })
         .input(AgentIdSchema)
         .output(AgentSummarySchema),
-    /* DISARM EVERY CONDITION WATCH THIS CONVERSATION IS PARKED ON (AgentSummary.watches), the way off the one
-     * standing arrangement an agent can enter into on the user's behalf without being asked again.
-     *
-     * ALL OF THEM, NOT ONE. The id of an individual watch is on the card, but the press a person makes about a
-     * card means "stop this conversation waking itself up", and picking watches off a submenu one at a time is a
-     * chore invented by the data shape rather than wanted by anybody. A conversation that should go on watching
-     * one thing and not another can be told so in the chat, which is where the watches were armed.
-     *
-     * No wake fires for what this disarms, which is the whole point: a watch left armed keeps a hosted machine
-     * awake and eventually starts a turn nobody is expecting. Nothing else about the conversation moves, so the
-     * card it hands back differs only by having lost its watches. */
+    // A finer-grained ask (watch this, not that) goes through the chat, not a per-watch id here.
     stopWatching: oc
         .route({
             method: "POST",
@@ -223,11 +182,8 @@ export const agentsContract = {
         })
         .input(AgentIdSchema)
         .output(AgentChangesSchema),
-    // The other side of `diff`: the work that is no longer a difference because it is in your own history, and
-    // the commits holding it. Asked for only once `diff` reports something absorbed, since it costs a `git log`
-    // per repo and answers nothing until then. Reading one of these files is the SAME call as reading a
-    // reviewable one (`fileDiff` below): the question "what did this conversation do to this file" has one
-    // answer whether or not you have since committed it.
+    // Costs a `git log` per repo: ask only once `diff` reports something absorbed. Reading a file here reuses
+    // `fileDiff`.
     history: oc
         .route({
             method: "GET",
@@ -257,9 +213,7 @@ export const agentsContract = {
         })
         .input(AgentLandSchema)
         .output(LandResultSchema),
-    // A collaborator's ask for the land they may not perform themselves (role floors put `land`/`discard` at
-    // maintainer). Stamps AgentSummarySchema.landRequested with the caller's identity and re-frames the fleet,
-    // so every maintainer's board carries the request; the land or discard that answers it clears the stamp.
+    // Stamps `AgentSummarySchema.landRequested` with the caller's identity.
     requestLand: oc
         .route({
             method: "POST",

package/src/contracts/automations.contract.ts

@@ -8,14 +8,10 @@ import {
     AutomationSchema,
     AutomationsListSchema,
 } from "../schemas/automations.js";
-import { OkSchema } from "../schemas/shared.js";
+import { DoorTokenSchema, OkSchema } from "../schemas/shared.js";
 
-// The sandbox's automations manifest (scheduled agent wake-ups). `list` returns each automation with its recent
-// runs + next fire time. `upsert` adds or edits by id (nothing to provision, the scheduler picks it up on its
-// next poll); `setEnabled` changes only the switch, so a list-row action never has to reconstruct the record.
-// `remove` deletes.
-// The `pending*` routes are the owner's approval queue: a `requireApproval` automation holds each fire here
-// instead of waking; `approve` runs the held wake, `reject` drops it.
+// Automations manifest (scheduled agent wake-ups); `pending*` is the owner's approval queue for wakes a
+// `requireApproval` automation holds instead of firing directly.
 export const automationsContract = {
     list: oc
         .route({
@@ -25,10 +21,6 @@ export const automationsContract = {
             description: "Every automation with its recent runs and when it fires next.",
         })
         .output(AutomationsListSchema),
-    /* WHAT CAN WAKE AN AGENT HERE, and what to start from, the daemon's own sources and templates merged with
-     * every installed extension's. The composer's entire vocabulary, so that adding a trigger to an area is a
-     * change to that area and to nothing else. `upsert` below validates against the same merge, which is what
-     * keeps the surface and the daemon from disagreeing about what is allowed. */
     catalog: oc
         .route({
             method: "GET",
@@ -65,25 +57,17 @@ export const automationsContract = {
         })
         .input(AutomationIdParamSchema)
         .output(OkSchema),
-    /* Fire one automation NOW, by hand, the answer to "I wrote a 3 a.m. cron and I have no way to try it".
-     * It runs the SAME path the real trigger runs: a schedule stays a headless main-tree wake, because a
-     * test-fire that proves an isolated worktree works proves nothing about the fire it is standing in for. The
-     * guard runs too ("skipped by guard" is the most useful thing this can report); only the approval gate is
-     * skipped, since pressing the button IS the owner's approval.
-     *
-     * Owner-explicit, so a DISABLED automation fires as well, trying a prompt before switching it on is the
-     * main reason to press this, and unlike the /automations/{id}/fire webhook there is no outside sender here to
-     * fail closed against.
-     *
-     * NOT FOR A LISTENER, which is the one trigger whose fire is nothing without the thing that fired it. A
-     * listener's prompt is a brief about handling the events riding with it, and by hand there are none, so the
-     * button could only ever produce an agent told to handle events, handed none, asking where they went. Worse,
-     * that pointless run took the automation's turn: a real mention arriving while it ran had to wait behind it.
-     * Refused here rather than hidden in the UI alone, because the honest answer to "how do I test this" is to
-     * send the bot a message, which costs nothing and tests the whole path.
-     *
-     * Acks immediately with the turn detached, like /fire and `approve`: the guard alone may take a minute, and
-     * the run history (with the session that makes it openable) is where the outcome lands. */
+    rotateToken: oc
+        .route({
+            method: "POST",
+            path: "/automations/{id}/rotate-token",
+            summary: "Rotate an automation's webhook token or intake key",
+            description:
+                "Mints a new credential for the door this automation opens and retires the old one at once. Every caller has to be handed the new URL; that is the point. Refused for an automation with no door.",
+        })
+        .input(AutomationIdParamSchema)
+        .output(DoorTokenSchema),
+    // Skips only the approval gate, since pressing this button is the owner's approval.
     run: oc
         .route({
             method: "POST",