@intentic/sandbox-contract 1.288.0 → 1.291.0

package/src/contracts/usage.contract.ts

@@ -8,6 +8,23 @@ export const RefreshPlanLimitsSchema = z.object({
     force: z.boolean().default(false).describe("Measure again even if a reading was taken a moment ago."),
 });
 
+// What a re-measure could not read. A provider rate-limits these reads per account, and while it is holding one off
+// the number on screen cannot move: without this the caller can only report a press that changed nothing.
+export const PlanLimitsRefreshedSchema = z.object({
+    ok: z.literal(true),
+    held: z
+        .array(
+            z.object({
+                provider: z.string().describe("Which provider is holding the read off."),
+                account: z.string().describe("The account as its provider's list names it: an account id, or a routed auth file's name."),
+                resumesAt: z.number().describe("Unix seconds: when this account may be read again, the provider's own retry-after."),
+            }),
+        )
+        .describe("Accounts whose plan limits could not be read now because the provider is rate-limiting them."),
+});
+export type PlanLimitsRefreshed = z.infer<typeof PlanLimitsRefreshedSchema>;
+export type PlanLimitsHeld = PlanLimitsRefreshed["held"][number];
+
 // Durable spend ledger, read-only over the wire; rows are appended daemon-side at turn end.
 // `rollup` groups by day, provider, account and model, so every cost panel re-projects from this one answer.
 export const usageContract = {
@@ -28,10 +45,10 @@ export const usageContract = {
             path: "/usage/plan-limits/refresh",
             summary: "Measure every account's plan limits again",
             description:
-                "Reads how full each connected account's plan limits are, for every provider, and records it. Forced, it measures even accounts read a moment ago, which is the right thing when a plan was just changed and the question is whether the number on screen is still true.",
+                "Reads how full each connected account's plan limits are, for every provider, and records it. Forced, it measures even accounts read a moment ago, which is the right thing when a plan was just changed and the question is whether the number on screen is still true. Answers with the accounts it could not read because the provider is rate-limiting them, and when each may be asked again: those keep the reading they already had, so a number that does not move is explained rather than silent.",
         })
         .input(RefreshPlanLimitsSchema)
-        .output(z.object({ ok: z.literal(true) })),
+        .output(PlanLimitsRefreshedSchema),
     // Asked, not polled: the provider only evaluates this when told the account is at the wall, and the answer isn't
     // cached.
     // Answers `available: false` rather than failing when the account has no such mechanism.

package/src/events/transcript.ts

@@ -120,6 +120,23 @@ export interface TranscriptTool {
     subagent?: TranscriptSubagent | undefined;
 }
 
+// Three endings that wake a conversation off a condition watch: the first two are promised when it is armed, the third
+// is the daemon's own (a deadline that passed while it was down). Composing and parsing the wake is watch-wake.ts.
+export const WatchOutcomeSchema = z.enum(["met", "timeout", "restart-expired"]);
+export type WatchOutcome = z.infer<typeof WatchOutcomeSchema>;
+
+// A condition watch waking the conversation, as the row carries it. The wake arrives as an ordinary turn prompt that
+// nobody typed, so the row keeps that prompt verbatim rather than a summary of it.
+export const TranscriptWatchWakeSchema = z.object({
+    outcome: WatchOutcomeSchema.describe("How the watch ended: the condition held, the deadline passed, or a restart cut it short."),
+    note: z.string().describe("The agent's own line on what it was waiting for."),
+    elapsed: z
+        .string()
+        .describe("How long the watch stood, already worded ('43m'): carried rather than recomputed, since the arming instant is not on the row."),
+    sent: z.string().describe("The whole prompt the model was woken with, disclosed under the row."),
+});
+export type TranscriptWatchWake = z.infer<typeof TranscriptWatchWakeSchema>;
+
 // One note the daemon put before a user's message: the model reads `text`, the chat draws `title` on a row that opens
 // to it. Shared by the live frame and the restored transcript, so it reads the same either way.
 export const TurnNoteSchema = z.object({
@@ -191,14 +208,19 @@ export const TranscriptRowSchema = z.object({
         ),
     // The one-press follow-up this notice offers, by name; the chat decides what it does, and whether it stands.
     noticeAction: z
-        .enum(["landHold", "outageOptOut", "depsInstall", "tierHold"])
+        .enum(["landHold", "outageOptOut", "depsInstall", "tierHold", "watchStop"])
         .optional()
         .describe("A one-press follow-up this notice offers, by name. The chat decides what it does and whether it still applies."),
     // An unfinished wait this notice describes, by name; whether it's still running is live state, not stored here.
     noticeWait: z
-        .enum(["credentialRenewal", "personaRoute"])
+        .enum(["credentialRenewal", "personaRoute", "watch"])
         .optional()
         .describe("The wait this notice describes, by name, so a reader can say whether it is still on."),
+    // Which one, for a wait whose kind can have several in flight at once; without it two armed watches settle together.
+    noticeWaitId: z
+        .string()
+        .optional()
+        .describe("Which instance of the wait this notice names, for a kind that can have several running at once."),
     // At most one card per row; a card closes its bubble. One field per kind, so a reader reaches it by name.
     plan: TranscriptPlanSchema.optional().describe("The plan this row asked approval for, and the answer."),
     question: TranscriptQuestionSchema.optional().describe("The questions this row asked, and the picks that answered them."),
@@ -207,6 +229,7 @@ export const TranscriptRowSchema = z.object({
     terminalHelp: TranscriptTerminalHelpSchema.optional().describe("The terminal hand-over this row asked for, and how it ended."),
     capabilityOffer: TranscriptCapabilityOfferSchema.optional().describe("The capability setup this row asked for, the decision, and the outcome."),
     paymentOffer: TranscriptPaymentOfferSchema.optional().describe("The payment this row asked for, the decision, and the receipt."),
+    watchWake: TranscriptWatchWakeSchema.optional().describe("The condition watch that woke this conversation, and the prompt it was woken with."),
     credentialOffer: TranscriptCredentialOfferSchema.optional().describe(
         "The gated credential this row asked to use, who may release it, and who did.",
     ),

package/src/events/verify-nudge.ts

@@ -0,0 +1,14 @@
+// The follow-up the daemon sends when a turn ended with work it could not confirm: the runtimes with no Stop hook get
+// their turn.ending asks this way (verify-nudge.ts), as an ordinary prompt. Its opening lives on the wire because the
+// chat has to recognise it coming back: a prompt nobody typed must not reach a reader as their own words.
+
+// Anchored on by the reader, so it must stay unique and stable across releases — a reworded opening un-recognises every
+// nudge already in a record, and they read as the user's own typing again.
+export const VERIFY_NUDGE_OPENING =
+    "The turn you just finished left work this sandbox could not confirm, so it is asking before the work is called done. Each item below is either a check that did not pass, which you repair, or something the turn changed without showing it works, which you prove. Deal with every one of them, then say plainly what you ran and what it covered.";
+
+// The prompt a nudge actually sends: its opening, then the findings and asks, each already worded for the model.
+export const verifyNudgePrompt = (parts: readonly string[]): string => [VERIFY_NUDGE_OPENING, ...parts].join("\n\n");
+
+// Whether a stored prompt is one, so any reader can ask without checking first.
+export const isVerifyNudge = (prompt: string): boolean => prompt.startsWith(VERIFY_NUDGE_OPENING);

package/src/events/watch-wake.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import type { WatchOutcome } from "./transcript.js";
+import { watchWakeOf, watchWakePrompt, watchWakeRow, type WatchWakeFields } from "./watch-wake.js";
+
+const fields = (over: Partial<WatchWakeFields> = {}): WatchWakeFields => ({
+    outcome: "met",
+    id: "watch-2",
+    note: "CI run 316 on intentic/intentic",
+    elapsed: "43m",
+    command: "gh run view 316 --json status",
+    exitCode: 0,
+    output: "completed success",
+    ...over,
+});
+
+const OUTCOMES: readonly WatchOutcome[] = ["met", "timeout", "restart-expired"];
+
+describe("watch wake", () => {
+    // The composer and the parser are the same piece of knowledge; this is what holds them together when either is
+    // reworded.
+    it.each(OUTCOMES)("round-trips a %s wake back to its fields", (outcome) => {
+        const wake = watchWakeOf(watchWakePrompt(fields({ outcome })));
+        expect(wake).toEqual({ outcome, note: "CI run 316 on intentic/intentic", elapsed: "43m", sent: expect.any(String) });
+    });
+
+    it("keeps the prompt verbatim on the row, since nobody typed it", () => {
+        const prompt = watchWakePrompt(fields());
+        expect(watchWakeOf(prompt)?.sent).toBe(prompt);
+    });
+
+    it("carries the watch id in the body, not the opening", () => {
+        const prompt = watchWakePrompt(fields());
+        expect(prompt.split("\n")[0]).not.toContain("watch-2");
+        expect(prompt).toContain("Watch id: watch-2");
+    });
+
+    it("says an absent exit code in words, since the check never reported one", () => {
+        expect(watchWakePrompt(fields({ exitCode: undefined }))).toContain("Last exit code: none (check was killed or failed to start)");
+    });
+
+    it("omits the output block when the check said nothing", () => {
+        expect(watchWakePrompt(fields({ output: "" }))).not.toContain("Last output (tail):");
+    });
+
+    it("draws a notice row, never a user row: a watch firing is neither side speaking", () => {
+        const row = watchWakeRow(watchWakePrompt(fields()));
+        expect(row?.role).toBe("notice");
+        expect(row?.text).toBe("CI run 316 on intentic/intentic — the watch fired after 43m.");
+    });
+
+    it("words each ending differently, since each calls for a different next step", () => {
+        const textOf = (outcome: WatchOutcome): string => watchWakeRow(watchWakePrompt(fields({ outcome })))?.text ?? "";
+        expect(textOf("timeout")).toBe("CI run 316 on intentic/intentic — the watch gave up after 43m.");
+        expect(textOf("restart-expired")).toBe("CI run 316 on intentic/intentic — the watch stopped when the sandbox restarted, after 43m.");
+    });
+
+    it("ignores a prompt that is not a wake, so any reader can ask without checking first", () => {
+        expect(watchWakeOf("fix the bug")).toBeUndefined();
+        expect(watchWakeRow("Watch fired: something I typed myself")).toBeUndefined();
+    });
+
+    it("refuses a wake whose labelled lines are gone, rather than putting a blank note on the row", () => {
+        const prompt = watchWakePrompt(fields());
+        expect(watchWakeOf(prompt.replace("Watching: CI run 316 on intentic/intentic\n", ""))).toBeUndefined();
+        expect(watchWakeOf(prompt.replace("Elapsed: 43m\n", ""))).toBeUndefined();
+    });
+});

package/src/events/watch-wake.ts

@@ -0,0 +1,78 @@
+import type { TranscriptRow, TranscriptWatchWake, WatchOutcome } from "./transcript.js";
+
+// What a condition watch says when it wakes a conversation, and how that reads to a person. The wake is delivered as an
+// ordinary turn prompt, so composing it and recognising it must stay one piece of knowledge: three separate readers
+// (the daemon's record, a steered live turn, a provider's session store) turn that prompt back into a row.
+
+// Per-outcome opening sentence, which is also what the parser anchors on: keep each unique and stable across releases,
+// or a reworded opening un-recognises wakes already in a record and they read as the user's own words again.
+const OPENINGS: Record<WatchOutcome, string> = {
+    met: "Watch fired: the condition you were watching is now met.",
+    timeout: "Watch timed out: the deadline passed and the check never exited 0. Decide whether to re-arm it, investigate the check, or report back.",
+    "restart-expired":
+        "Watch stopped: its deadline passed while the daemon was restarting, so it went unchecked for part of that window. It has just been re-checked once and the condition still does not hold. Decide whether to re-arm it, investigate the check, or report back.",
+};
+
+// Labels the prompt writes and the parser reads back. `Watching` and `Elapsed` are load-bearing on both sides; the rest
+// are for the model and the reader only.
+const WATCHING = "Watching: ";
+const ELAPSED = "Elapsed: ";
+
+export interface WatchWakeFields {
+    readonly outcome: WatchOutcome;
+    readonly id: string;
+    readonly note: string;
+    readonly elapsed: string;
+    readonly command: string;
+    // Undefined when the check never exited on its own (killed at its timeout, or failed to spawn).
+    readonly exitCode: number | undefined;
+    readonly output: string;
+}
+
+// The prompt a wake actually sends. The watch id sits in the body rather than the opening: it is the handle for
+// `watch stop`, so it has to be here, but it is the least useful thing on the page to read first.
+export const watchWakePrompt = (fields: WatchWakeFields): string =>
+    [
+        OPENINGS[fields.outcome],
+        `${WATCHING}${fields.note}`,
+        `${ELAPSED}${fields.elapsed}`,
+        `Watch id: ${fields.id}`,
+        `Check command: ${fields.command}`,
+        `Last exit code: ${fields.exitCode === undefined ? "none (check was killed or failed to start)" : fields.exitCode}`,
+        ...(fields.output === "" ? [] : ["Last output (tail):", "```", fields.output, "```"]),
+        "Continue the task this watch was armed for.",
+    ].join("\n");
+
+// The one line a person reads. Present tense for the ending itself, since the row appears the moment it happens.
+const headline = (outcome: WatchOutcome, note: string, elapsed: string): string => {
+    if (outcome === "met") {
+        return `${note} — the watch fired after ${elapsed}.`;
+    }
+    if (outcome === "timeout") {
+        return `${note} — the watch gave up after ${elapsed}.`;
+    }
+    return `${note} — the watch stopped when the sandbox restarted, after ${elapsed}.`;
+};
+
+const valueOn = (lines: readonly string[], label: string): string | undefined => lines.find((line) => line.startsWith(label))?.slice(label.length);
+
+// Which wake a stored prompt is, if any; undefined for every prompt that isn't one, so any reader can ask without
+// checking first. A prompt that opens as a wake but lost its labelled lines is not one: half-parsing it would put a
+// blank note on the row and lose the words with it.
+export const watchWakeOf = (prompt: string): TranscriptWatchWake | undefined => {
+    const outcome = (Object.keys(OPENINGS) as WatchOutcome[]).find((key) => prompt.startsWith(OPENINGS[key]));
+    if (outcome === undefined) {
+        return undefined;
+    }
+    const lines = prompt.split("\n");
+    const note = valueOn(lines, WATCHING);
+    const elapsed = valueOn(lines, ELAPSED);
+    return note === undefined || elapsed === undefined ? undefined : { outcome, note, elapsed, sent: prompt };
+};
+
+// The row a wake becomes, wherever a prompt is turned into rows: a notice, because a watch firing is something that
+// happened to the turn rather than anything either side said. Undefined when the prompt is not a wake at all.
+export const watchWakeRow = (prompt: string): TranscriptRow | undefined => {
+    const wake = watchWakeOf(prompt);
+    return wake === undefined ? undefined : { role: "notice", text: headline(wake.outcome, wake.note, wake.elapsed), watchWake: wake };
+};

package/src/index.ts

@@ -9,6 +9,7 @@ import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
+import { diffContract } from "./contracts/diff.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { exitContract } from "./contracts/exit.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
@@ -52,6 +53,7 @@ export { endpointsContract, type TrialHealth, TrialStatusSchema, type TrialStatu
 export { exitContract } from "./contracts/exit.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
 export { personasContract } from "./contracts/personas.contract.js";
+export { diffContract } from "./contracts/diff.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
 export { historyContract } from "./contracts/history.contract.js";
 // Not part of `sandboxContract` below: spoken over a device's WebSocket, with the machine implementing it.
@@ -81,7 +83,7 @@ export { shareContract } from "./contracts/share.contract.js";
 export { skillsContract } from "./contracts/skills.contract.js";
 export { systemContract } from "./contracts/system.contract.js";
 export { translatorContract } from "./contracts/translator.contract.js";
-export { usageContract } from "./contracts/usage.contract.js";
+export { type PlanLimitsHeld, type PlanLimitsRefreshed, PlanLimitsRefreshedSchema, usageContract } from "./contracts/usage.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
@@ -90,6 +92,8 @@ export * from "./events/cards.js";
 export * from "./events/resume.js";
 export * from "./events/system-events.js";
 export * from "./events/transcript.js";
+export * from "./events/verify-nudge.js";
+export * from "./events/watch-wake.js";
 export * from "./policy/card-status.js";
 export * from "./text/mentions.js";
 export * from "./protocol/sse.js";
@@ -151,6 +155,7 @@ export * from "./schemas/environment.js";
 export * from "./schemas/exit.js";
 export * from "./schemas/extension-updates.js";
 export * from "./schemas/providers/fast-mode.js";
+export * from "./schemas/diff.js";
 export * from "./schemas/git/git.js";
 export * from "./schemas/git/git-history.js";
 export * from "./schemas/history.js";
@@ -209,6 +214,7 @@ export const sandboxContract = {
     capabilities: capabilitiesContract,
     chores: choresContract,
     ci: ciContract,
+    diff: diffContract,
     endpoints: endpointsContract,
     extensions: extensionsContract,
     personas: personasContract,

package/src/models/agent-catalog.test.ts

@@ -204,10 +204,14 @@ test("the instruction axis discloses its two weaker answers, differently", () =>
     expect(limitationsOf(acpCaps).length).toBeGreaterThan(limitationsOf(codexCaps).length);
 });
 
-test("only the Claude Code loop hosts the js execution backend", () => {
+// The backend is one of the daemon's own functions, so it takes a runtime that can call one directly AND a gate the
+// daemon controls: Claude Code has the SDK server plus its PreToolUse matcher, Cursor has customTools plus a consult
+// inside the handler. Every other runtime is a child process with neither, where a script would run unread.
+test("the js execution backend rides the two runtimes that can host the daemon's own tools", () => {
+    const hosts: ReadonlySet<string> = new Set(["claude-code", "cursor"]);
     for (const { provider, harness } of pairs) {
         const capabilities = capabilitiesOf(provider, harness);
-        expect(capabilities.execution.includes("js")).toBe(capabilities.runtime === "claude-code");
+        expect(capabilities.execution.includes("js")).toBe(hosts.has(capabilities.runtime));
     }
 });
 

package/src/models/agent-catalog.ts

@@ -153,6 +153,11 @@ export const modelsFor = (provider: AgentProvider): CatalogOption[] => {
     return [];
 };
 
+// Every reasoning tier a catalog row's `efforts` may name, weakest first. One vocabulary for every provider, so the
+// picker can label and order a ladder it has never seen; a provider spelling a rung its own way translates on the way
+// in, at the adapter that read it.
+export const EFFORT_TIERS: readonly string[] = ["minimal", "low", "medium", "high", "xhigh", "max"];
+
 // Filters exactly one pair: Claude's `max` with thinking explicitly false, the one combination Anthropic's API refuses
 // (400). Absent thinking is not off; the model's own default answers, every other tier or provider passes through.
 export const effortAllowed = (effort: string, provider: AgentProvider, thinking: boolean | undefined): boolean =>

package/src/models/agent-runtimes.ts

@@ -171,15 +171,17 @@ export const PI: AgentCapabilities = {
 // other runtimes lack are function arguments here. The harness axis doesn't apply: the SDK is the only door.
 export const CURSOR: AgentCapabilities = {
     runtime: "cursor",
-    // The SDK's Run can be cancelled but not written to mid-flight; a second send errors rather than injecting.
-    steering: false,
+    // Run.steer injects into the live run; only a `complete_delivered` ack transfers ownership of the message.
+    steering: true,
     // Cursor's own plan mode, not this repo's emulation; not "modes" since the hook can't gate the whole surface.
     permissions: "plan",
     // True since the daemon supplies its own ask tool; Cursor's own can fabricate an answer, so it's disallowed.
     questions: true,
     // stdio + http/sse MCP servers plus host callbacks; everything but a Claude Code plugin checkout.
     mcp: "tools",
-    execution: ["shell"],
+    // The JS backend rides Cursor's custom-tool seam rather than an MCP server, and consults the rulebook in its
+    // handler, since the hook file only covers the shell.
+    execution: ["shell", "js"],
     // Cursor publishes effort as model parameters, not one scale; true here just means it's forwardable at all.
     effort: true,
     fastMode: false,
@@ -191,7 +193,8 @@ export const CURSOR: AgentCapabilities = {
     terminals: false,
     // The SDK throws typed errors instead of dissolving a refusal into prose, so the adapter files coded frames.
     recovery: true,
-    // append, reached differently: `beforeSubmitPrompt`'s reply folds the prompt onto Cursor's base, unreplaceable.
+    // append, reached differently: `beforeSubmitPrompt`'s reply folds the daemon's text onto Cursor's base. The SDK can
+    // replace that base outright, but only for an entitled account, so the seam every turn can reach is this one.
     instructions: "append",
     skillDiscovery: "prompt",
     // The full hook tier, the only foreign runtime to reach it: a hold parks since the vendor waits on the hook.

package/src/models/plan-pools.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { bindingWindow, gatesModel, gatingWindows, scopedWindow } from "./plan-pools.js";
+import { bindingWindow, gatesModel, gatingWindows, scopedWindow, windowLive, windowPeriod } from "./plan-pools.js";
 import type { AccountUsage, UsageWindow } from "../schemas/providers/plan-limits.js";
 
 // One rule for which pool blocks a given model, shared by the daemon and the browser: a plan can meter models
@@ -64,3 +64,42 @@ test("names the pool a plan meters this model by on its own, preferring the more
     const tied = usage(window({ kind: "model:Opus", gates: { models: ["Opus"] } }), window({ kind: "model:Claude", gates: { models: ["Claude"] } }));
     expect(scopedWindow(tied, { id: "claude-opus-4-6" })).toBeUndefined();
 });
+
+// How long a pool's window runs, read off the provider's own key and name. Two things turn on it, which is why it is
+// one function: a narrow column names the window by `short`, and a reading with no published reset may only be trusted
+// for that long.
+
+test("a window's length is read off the provider's own key, and off its name where the key says nothing", () => {
+    const period = (kind: string, label?: string) => windowPeriod(label === undefined ? { kind } : { kind, label });
+    expect(period("five_hour")).toEqual({ seconds: 5 * 3_600, short: "5h" });
+    expect(period("seven_day")).toEqual({ seconds: 7 * 86_400, short: "wk" });
+    expect(period("seven_day_opus")).toEqual({ seconds: 7 * 86_400, short: "wk" });
+    // Anthropic's own key says nothing; the label the reader built from it does.
+    expect(period("model:Fable", "Weekly · Fable")).toEqual({ seconds: 7 * 86_400, short: "wk" });
+    expect(period("google:gemini-weekly", "Gemini Models · Weekly Limit Remaining")).toEqual({ seconds: 7 * 86_400, short: "wk" });
+    expect(period("monthly", "Monthly · all models")).toEqual({ seconds: 30 * 86_400, short: "mo" });
+    expect(period("claude:12_hour")).toEqual({ seconds: 12 * 3_600, short: "12h" });
+    expect(period("daily")).toEqual({ seconds: 86_400, short: "24h" });
+    expect(period("30_minutes")).toEqual({ seconds: 1_800, short: "30m" });
+    // A pool nothing names the length of answers nothing, rather than guessing one.
+    expect(period("claude:tangelo")).toBeUndefined();
+    expect(period("model:Fable", "Fable")).toBeUndefined();
+});
+
+test("a reading is live until its reset, or, with none published, for one window's length after it was taken", () => {
+    const NOW = 1_700_000_000_000;
+    const HOUR = 3_600_000;
+    // A published reset is the authority whatever the window's length says, in both directions.
+    expect(windowLive(window({ kind: "five_hour", resetsAt: NOW / 1_000 + 60 }), NOW - 50 * HOUR, NOW)).toBe(true);
+    expect(windowLive(window({ kind: "seven_day", resetsAt: NOW / 1_000 - 1 }), NOW, NOW)).toBe(false);
+
+    // With none — what an idle five-hour pool is published with — the window's own length retires it.
+    const idle = window({ kind: "five_hour", utilization: 0 });
+    expect(windowLive(idle, NOW - 4 * HOUR, NOW)).toBe(true);
+    expect(windowLive(idle, NOW - 6 * HOUR, NOW)).toBe(false);
+    // A weekly pool read on the same morning is still describing the week it was read in.
+    expect(windowLive(window({ kind: "seven_day", utilization: 78 }), NOW - 12 * HOUR, NOW)).toBe(true);
+
+    // And a pool whose length nothing names has only its reset instant; without one it stands.
+    expect(windowLive(window({ kind: "claude:tangelo" }), NOW - 400 * HOUR, NOW)).toBe(true);
+});

package/src/models/plan-pools.ts

@@ -63,3 +63,72 @@ export const scopedWindow = (usage: AccountUsage | undefined, model: ModelRef):
     }
     return best.window;
 };
+
+// How long a pool's window runs, read off the provider's own key and whatever name it published. One implementation,
+// because two things need it and must agree: a narrow column names the window by `short`, and a reading with no
+// published reset instant may only be trusted for `seconds` past the moment it was taken.
+
+export interface WindowPeriod {
+    readonly seconds: number;
+    // The token a narrow column names this window by, e.g. "5h", "wk".
+    readonly short: string;
+}
+
+const HOUR_SECONDS = 3_600;
+const DAY_SECONDS = 86_400;
+
+/** Kind and label as space-padded lowercase words, underscores split, so `\b` matches across both spellings. */
+export const periodWords = (pool: { readonly kind: string; readonly label?: string | undefined }): string =>
+    ` ${`${pool.kind} ${pool.label ?? ""}`
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/gu, " ")
+        .trim()} `;
+
+// A count the words spell out, e.g. the 3 in "3 days".
+const counted = (words: string, pattern: RegExp): number | undefined => {
+    const found = pattern.exec(words)?.[1];
+    return found === undefined ? undefined : Number(found);
+};
+
+// Day-scale and longer, where the named periods outrank a bare count: "7 days" is the week every plan sells, not a
+// seven-day span of its own.
+const dayPeriod = (words: string, days: number | undefined): WindowPeriod | undefined => {
+    if (days === 7 || /\bseven days?\b|\bweek(ly|s)?\b/u.test(words)) {
+        return { seconds: 7 * DAY_SECONDS, short: "wk" };
+    }
+    if (/\bmonth(ly|s)?\b/u.test(words)) {
+        return { seconds: 30 * DAY_SECONDS, short: "mo" };
+    }
+    if (days === 1 || /\bdaily\b/u.test(words)) {
+        return { seconds: DAY_SECONDS, short: "24h" };
+    }
+    return days === undefined ? undefined : { seconds: days * DAY_SECONDS, short: `${days}d` };
+};
+
+/** Window length behind a pool; undefined when neither the key nor the name says how long it runs. */
+export const windowPeriod = (pool: { readonly kind: string; readonly label?: string | undefined }): WindowPeriod | undefined => {
+    const words = periodWords(pool);
+    const hours = counted(words, /\b(\d+) hours?\b/u);
+    // Hours first: a pool named both ("5 hours, weekly cap") runs on the shorter clock.
+    if (hours !== undefined || /\bfive hours?\b/u.test(words)) {
+        const span = hours ?? 5;
+        return { seconds: span * HOUR_SECONDS, short: `${span}h` };
+    }
+    const day = dayPeriod(words, counted(words, /\b(\d+) days?\b/u));
+    if (day !== undefined) {
+        return day;
+    }
+    const minutes = counted(words, /\b(\d+) minutes?\b/u);
+    return minutes === undefined ? undefined : { seconds: minutes * 60, short: `${minutes}m` };
+};
+
+// Whether a reading of this window can still be true. A published reset instant is the authority; with none, the
+// window's own length is, since a pool read as empty says nothing about the window that opened after it. A window whose
+// length nothing names keeps the old rule: only its reset instant can retire it.
+export const windowLive = (window: UsageWindow, measuredAt: number, now: number): boolean => {
+    if (window.resetsAt !== undefined) {
+        return window.resetsAt * 1000 > now;
+    }
+    const period = windowPeriod(window);
+    return period === undefined || measuredAt + period.seconds * 1000 > now;
+};

package/src/schemas/agents.ts

@@ -418,6 +418,12 @@ export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
 // needs that type declared first.
 export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });
 
+// Naming no watch disarms every one, which is what a press made about the whole card means; a press made about one
+// watch's own transcript row names it, and leaves the conversation's other watches armed.
+export const AgentStopWatchingSchema = AgentIdSchema.extend({
+    watchId: z.string().optional().describe("Which watch to disarm. Absent disarms every watch this conversation is parked on."),
+});
+
 // Pages a transcript: a read returns its most recent turns and where they start (`from`); handing that back as `before`
 // asks for the page above. A stale cursor (a rewind, a fork) is clamped, never refused.
 export const AgentTranscriptQuerySchema = AgentIdSchema.extend({

package/src/schemas/devices.ts

@@ -123,9 +123,14 @@ export type DeviceAgentFlowInput = z.infer<typeof DeviceAgentFlowInputSchema>;
 // `sync-clean` removes the build output left in directories the sandbox has deleted, which is what stops those
 // deletions from ever landing. It deletes only content the session already ignores, so it is the one command here whose
 // worst outcome is a rebuild — which is why it is a button and not a turn.
+// `mirror-ignore`/`mirror-unignore` are `mirror-off`'s per-port form, and the reason they exist: a port number that is
+// permanently taken on one machine's localhost has no answer in an all-or-nothing switch, so the choice lives where the
+// conflict does — one port, one device, durable — instead of muting every port the pairing serves.
 export const DeviceCommandSchema = z.enum([
     "mirror-off",
     "mirror-on",
+    "mirror-ignore",
+    "mirror-unignore",
     "sync-pause",
     "sync-resume",
     "sync-unpair",
@@ -210,6 +215,8 @@ export const DeviceLocalDirSchema = z
     .min(1)
     .max(4096)
     .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r]*$/);
+// A TCP port number, the one value a caller supplies that reaches a command line as a number rather than a string.
+export const PortNumberSchema = z.number().int().min(1).max(65535);
 export const DeviceCommandInputSchema = z.object({
     id: z.string().min(1),
     command: DeviceCommandSchema,
@@ -218,6 +225,9 @@ export const DeviceCommandInputSchema = z.object({
     // for file sync, the folder on that device. The pairing token is minted by the daemon; no caller ever carries one.
     mode: z.enum(["sync", "mirror"]).optional(),
     localDir: DeviceLocalDirSchema.optional(),
+    // The two per-port mirror switches only. A number rather than a string, so nothing a caller sends can widen the
+    // command line it lands in.
+    port: PortNumberSchema.optional(),
 });
 export type DeviceCommandInput = z.infer<typeof DeviceCommandInputSchema>;
 // `ok` is the command's own exit status, not this route's: a refusal or non-zero exit is a real answer, not a thrown
@@ -294,9 +304,18 @@ export const DevicePortStateSchema = z.enum([
     "held-by-sandbox",
     // Something outside this product already binds the port; not ours to name or take.
     "busy",
+    // The owner told this device to leave this number alone (`sync mirror ignore`); nothing was attempted.
+    "ignored",
 ]);
+export type DevicePortState = z.infer<typeof DevicePortStateSchema>;
+
+// Why a port the sandbox serves is not on this machine's localhost: the state minus its one success. Named here
+// because the machine decides it and the browser renders it, so a new reason has to reach both at once.
+export const PortSkipReasonSchema = DevicePortStateSchema.exclude(["mirrored"]);
+export type PortSkipReason = z.infer<typeof PortSkipReasonSchema>;
+
 export const DevicePortSchema = z.object({
-    port: z.number().int().min(1).max(65535),
+    port: PortNumberSchema,
     host: z.enum(["127.0.0.1", "::1"]),
     // The sandbox serving the port, whose /ports listed it, not whoever ended up holding the local bind.
     sandboxId: z.string(),

package/src/schemas/diff.ts

@@ -0,0 +1,72 @@
+// diff: one side of a file diff named by its source, for the routes that answer with something other than the text
+// diff itself (bytes on /diff/raw, derived text on /diff/derived).
+import { z } from "zod";
+import { GitDiffSideSchema } from "./git/git.js";
+
+const path = z.string().min(1).describe("The file, relative to the repo or scope the diff belongs to.");
+const repo = z.string().min(1).describe('Which repository: "root" for the workspace itself, otherwise a repo id.');
+
+// The four pairings a review surface lists a row under; every field is a string, so the same shape rides a query string
+// and the JSON body of a typed call alike.
+export const DiffSourceQuerySchema = z.discriminatedUnion("source", [
+    z
+        .object({
+            source: z.literal("working"),
+            repo,
+            side: GitDiffSideSchema.describe("Which git side the row came from; a half-staged file is two different diffs."),
+            path,
+        })
+        .describe("Uncommitted work in a workspace repo, what the Changes panel lists."),
+    z
+        .object({
+            source: z.literal("agent"),
+            agent: z.string().min(1).describe("The conversation whose work is under review."),
+            repo,
+            path,
+        })
+        .describe("One agent's work against the base its review is listed against."),
+    z
+        .object({
+            source: z.literal("commit"),
+            repo,
+            sha: z
+                .string()
+                .regex(/^[0-9a-f]{4,64}$/)
+                .describe("The commit, compared against its first parent."),
+            path,
+        })
+        .describe("A commit against its first parent."),
+    z
+        .object({
+            source: z.literal("checkpoint"),
+            snapshot: z.string().min(1).describe("Which saved point."),
+            scope: z.string().min(1).describe("Which part of the workspace the path belongs to."),
+            path,
+        })
+        .describe("A saved point in the timeline, against the visible one before it."),
+]);
+export type DiffSourceQuery = z.infer<typeof DiffSourceQuerySchema>;
+
+// One side of a document rendered to text, or why it could not be. The text is fileq's rendering, the same one an
+// agent reads instead of the bytes, so what a reviewer compares here is what the agent worked from.
+export const DerivedSideSchema = z.discriminatedUnion("present", [
+    z.object({
+        present: z.literal(true),
+        content: z.string().describe("The side as markdown."),
+        deriver: z.string().describe("Which reader made this text, with its version."),
+        notes: z.array(z.string()).describe("Every cap and degradation the conversion hit, one line each."),
+        truncated: z.boolean().describe("The rendering was longer than this response carries; only its start is here."),
+    }),
+    z.object({
+        present: z.literal(false),
+        reason: z.string().describe("Why this side has no text: a format nothing reads, a broken file, a sandbox with no reader."),
+    }),
+]);
+export type DerivedSide = z.infer<typeof DerivedSideSchema>;
+
+// Both sides as text; an absent side is a side the diff does not have (an added file has no before).
+export const DerivedDiffSchema = z.object({
+    before: DerivedSideSchema.optional().describe("The file as it was, rendered to text. Absent when it did not exist yet."),
+    after: DerivedSideSchema.optional().describe("The file as it is now, rendered to text. Absent when it was deleted."),
+});
+export type DerivedDiff = z.infer<typeof DerivedDiffSchema>;