@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/chores/verdict.ts

@@ -6,35 +6,43 @@ import { probeSpec } from "./probes.js";
  * 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.
  *
- * Five states, and the distinctions between them are the whole design:
+ * 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 as a footer, so "why is there no Docker chore here?" has an answer.
+ *                The reason survives in the scope strip, 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 whose evidence is UNCHANGED since a turn was already
- * spent on it 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.
+ * 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, recorded in the panel's footer with its reason. A maintenance
- * surface you can quietly bury findings in is a maintenance surface nobody trusts. */
+ * is not hiding — it is the absence of a subject, counted in the panel's scope strip and expandable to the reason.
+ * A maintenance surface you can quietly bury findings in is a maintenance surface nobody trusts. */
 
-export type ChoreState = "due" | "clear" | "snoozed" | "unavailable" | "not-applicable";
+export type ChoreState = "due" | "clear" | "snoozed" | "stale" | "unavailable" | "not-applicable";
 
 export interface ChoreVerdict {
     readonly chore: Chore;
@@ -46,15 +54,30 @@ export interface ChoreVerdict {
     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. */
+    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.
     readonly prompt: string | undefined;
     readonly lastRun: ChoreLedgerEntry | undefined;
-    // A turn has already been spent on exactly this evidence, and the chore's cadence has not lapsed since. Still
-    // due, still shown, never badged.
+    // 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.
     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. */
+const measurementAge = (needs: readonly ProbeId[], probes: ReadonlyMap<ProbeId, ProbeResult>): number | undefined => {
+    const taken = needs.flatMap((id) => {
+        const probe = probes.get(id);
+        return probe?.state === `ok` ? [probe.ranAt] : [];
+    });
+    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.
@@ -87,21 +110,32 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
 
     /* 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 reason is carried as the headline, because the panel's footer
-     * is the only place it will ever be read. */
+     * function would be answering it anyway. The cause is carried as the headline, because the scope strip — which
+     * groups these rows BY it — is the only place it will ever be read. */
     const inapplicable = chore.applies?.(context.signals);
     if (inapplicable !== undefined) {
-        return { ...base, state: `not-applicable`, severity: `info`, headline: inapplicable, detail: [], digest: `` };
+        return { ...base, state: `not-applicable`, severity: `info`, headline: inapplicable, detail: [], digest: ``, measuredAt: undefined };
     }
 
     const unmeasured = unmeasuredDetail(chore.needs, context.probes);
     if (unmeasured.length > 0) {
-        return { ...base, state: `unavailable`, severity: `info`, headline: `Not measured`, detail: unmeasured, digest: `` };
+        return { ...base, state: `unavailable`, severity: `info`, headline: `Not measured`, detail: unmeasured, digest: ``, measuredAt: undefined };
     }
 
+    // Every state below this line rests on a measurement that ran, so all of them carry when it was taken.
+    const measuredAt = measurementAge(chore.needs, context.probes);
+
     const finding = chore.assess(context);
     if (finding === undefined) {
-        return { ...base, state: `clear`, severity: `info`, headline: clearHeadline(chore, ledger, context.nowMs), detail: [], digest: `` };
+        return {
+            ...base,
+            state: `clear`,
+            severity: `info`,
+            headline: clearHeadline(chore, ledger, context.nowMs),
+            detail: [],
+            digest: ``,
+            measuredAt,
+        };
     }
 
     /* Has the last run's settlement lapsed? A cadence of 0 means "this is decided by evidence alone" — an advisory
@@ -116,13 +150,30 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
      * 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?". */
     if (chore.survey === true && ledger !== undefined && context.nowMs - ledger.ranAt < chore.cadenceMs) {
-        return { ...base, state: `clear`, severity: `info`, headline: clearHeadline(chore, ledger, context.nowMs), detail: finding.detail, digest: finding.digest };
+        return {
+            ...base,
+            state: `clear`,
+            severity: `info`,
+            headline: clearHeadline(chore, ledger, context.nowMs),
+            detail: finding.detail,
+            digest: finding.digest,
+            measuredAt,
+        };
     }
 
     const prompt = chorePrompt(chore, finding, context.repo);
 
     if (ledger?.snoozedUntil !== undefined && ledger.snoozedUntil > context.nowMs) {
-        return { ...base, state: `snoozed`, severity: `info`, headline: finding.headline, detail: finding.detail, digest: finding.digest, prompt };
+        return {
+            ...base,
+            state: `snoozed`,
+            severity: `info`,
+            headline: finding.headline,
+            detail: finding.detail,
+            digest: finding.digest,
+            measuredAt,
+            prompt,
+        };
     }
 
     /* The agent looked at exactly this evidence and reported that there was nothing in it — knip's findings were
@@ -137,10 +188,32 @@ export const assessChore = (chore: Chore, context: ChoreContext, ledger: ChoreLe
             headline: `Checked — the findings did not hold up`,
             detail: finding.detail,
             digest: finding.digest,
+            measuredAt,
         };
     }
 
-    return { ...base, state: `due`, severity: finding.severity, headline: finding.headline, detail: finding.detail, digest: finding.digest, prompt, settled: sameEvidence };
+    /* 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. */
+    if (ledger !== undefined && measuredAt !== undefined && ledger.ranAt > measuredAt) {
+        return { ...base, state: `stale`, severity: `info`, headline: finding.headline, detail: finding.detail, digest: finding.digest, measuredAt };
+    }
+
+    return {
+        ...base,
+        state: `due`,
+        severity: finding.severity,
+        headline: finding.headline,
+        detail: finding.detail,
+        digest: finding.digest,
+        measuredAt,
+        prompt,
+        settled: sameEvidence,
+    };
 };
 
 // The ledger is keyed by repo + chore, which is the grain a verdict is decided at: the same chore in two repos is
@@ -162,8 +235,9 @@ export const assessReport = (report: ChoresReport, nowMs: number): ChoreVerdict[
  * 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.
- *   !settled        a turn has already been spent on this exact evidence.
+ *   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.
  *

package/src/contract-lock.test.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { expect, test } from "vitest";
+import { currentLock } from "./contract-lock.js";
+
+/* The committed lock and the code must say the same thing — see contract-lock.ts for what the pair buys.
+ *
+ * This is the HALF that runs everywhere the tests run; the other half (a shrunk lock needs a declared break)
+ * lives in prepass.mjs, which has git and this suite does not. */
+test("contract.lock.json matches the schemas this package exports", () => {
+    const committed: unknown = JSON.parse(readFileSync(new URL("../contract.lock.json", import.meta.url), "utf8"));
+    expect(
+        currentLock(),
+        "the wire contract moved — run `pnpm --filter @intentic/sandbox-contract lock` and commit contract.lock.json with this change. " +
+            "If a schema or field was removed or changed (not added), land it as a `type!:` commit with a `Breaking-Note:` trailer " +
+            "saying, in the user's words, what stops working and what to do instead.",
+    ).toEqual(committed);
+});

package/src/contract-lock.ts

@@ -0,0 +1,66 @@
+/* THE WIRE SURFACE, AS ONE COMPARABLE DOCUMENT — every zod schema this package exports, serialized to JSON
+ * Schema and sorted into a canonical shape. `contract.lock.json` at the package root is this function's
+ * committed output, and the pair is what makes "did the contract change?" a question git can answer.
+ *
+ * Two readers depend on that answer. contract-lock.test.ts fails whenever the committed file is out of step
+ * with the code, so a contract change always lands WITH its lock diff — visible in review, attributable to a
+ * commit. And prepass.mjs (invariant 6) compares the committed lock against its merge-base to insist that a
+ * SHRUNK surface — a schema or field removed, a type changed — arrives as a `!` commit carrying a
+ * `Breaking-Note:` trailer, which is what feeds the release's "Breaking changes" section and the update card's
+ * warning. Additions pass freely; every persisted-manifest reader parses loosely, so growth breaks nobody.
+ *
+ * Serialized from the package's EXPORTS rather than a hand-kept list, on the repo's own rule (AGENTS.md:
+ * "guard invariants by discovery, not enumeration"): a schema added tomorrow is in the lock tomorrow, and a
+ * schema that stops being exported is a removal the lock shows. `unrepresentable: "any"` keeps the rare
+ * function-valued corner from throwing — it serializes as `{}`, which still diffs when it moves. */
+
+import { z } from "zod";
+import * as contract from "./index.js";
+
+// Canonical ordering, so two runs of the same code are byte-identical and a lock diff is a contract diff
+// rather than a key-order shuffle. Arrays keep their order — for `required` and `enum` lists the order zod
+// emits is stable, and sorting them would hide a reorder that is genuinely no change at all anyway.
+const sorted = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map(sorted);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(
+            Object.keys(value)
+                .sort()
+                .map((key) => [key, sorted((value as Record<string, unknown>)[key])]),
+        );
+    }
+    return value;
+};
+
+export const currentLock = (): Record<string, unknown> => {
+    const lock: Record<string, unknown> = {};
+    for (const name of Object.keys(contract).sort()) {
+        const value = (contract as Record<string, unknown>)[name];
+        if (!(value instanceof z.ZodType)) {
+            continue;
+        }
+        try {
+            const schema = sorted(z.toJSONSchema(value, { unrepresentable: "any" })) as Record<string, unknown>;
+            // The dialect banner is identical on all ~500 entries — pure weight, no surface.
+            delete schema["$schema"];
+            lock[name] = schema;
+        } catch {
+            // A schema JSON Schema cannot express at all still holds a place in the lock: its appearance,
+            // disappearance, or transition to serializable are each a surface change worth a diff.
+            lock[name] = "<unserializable>";
+        }
+    }
+    return lock;
+};
+
+/* ONE LINE PER SCHEMA, on purpose — not JSON.stringify(lock, null, 4). Pretty-printed, the lock is a 35k-line
+ * wall nobody scrolls; a line per export keeps it ~500 lines and makes `git diff` read as the list of WHICH
+ * surfaces moved, which is the level a reviewer reviews at. The path-level detail lives in the tooling: the
+ * lock test diffs parsed objects and prepass invariant 6 names the exact removed paths, so nothing is lost by
+ * not laying the structure out vertically. */
+export const serializeLock = (lock: Record<string, unknown>): string =>
+    `{\n${Object.entries(lock)
+        .map(([name, schema]) => `${JSON.stringify(name)}: ${JSON.stringify(schema)}`)
+        .join(",\n")}\n}\n`;

package/src/contracts/agent.contract.ts

@@ -6,6 +6,8 @@ import {
     AttachTurnSchema,
     OkSchema,
     ProviderRefusalsSchema,
+    RewindResultSchema,
+    RewindTurnSchema,
     StartedTurnSchema,
     SteerSchema,
     StopTurnSchema,
@@ -22,6 +24,10 @@ export const agentContract = {
     reply: oc.route({ method: "POST", path: "/agent/reply" }).input(AgentReplySchema).output(OkSchema),
     steer: oc.route({ method: "POST", path: "/agent/steer" }).input(SteerSchema).output(OkSchema),
     stop: oc.route({ method: "POST", path: "/agent/stop" }).input(StopTurnSchema).output(OkSchema),
+    // 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.
+    rewind: oc.route({ method: "POST", path: "/agent/rewind" }).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", path: "/agent/commands" }).input(AgentCommandsQuerySchema).output(AgentCommandsSchema),

package/src/contracts/agents.contract.ts

@@ -8,6 +8,7 @@ import {
     AgentIdSchema,
     AgentIdsSchema,
     AgentLandSchema,
+    AgentPlaceSchema,
     AgentRenameSchema,
     AgentSearchQuerySchema,
     AgentSearchResultSchema,
@@ -54,6 +55,13 @@ export const agentsContract = {
     search: oc.route({ method: "GET", path: "/agents/search" }).input(AgentSearchQuerySchema).output(AgentSearchResultSchema),
     get: oc.route({ method: "GET", path: "/agents/{id}" }).input(AgentIdSchema).output(AgentSummarySchema),
     transcript: oc.route({ method: "GET", path: "/agents/{id}/transcript" }).input(AgentIdSchema).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 (RestoredMessageSchema); 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. */
+    place: oc.route({ method: "POST", path: "/agents/{id}/place" }).input(AgentPlaceSchema).output(OkSchema),
     rename: oc.route({ method: "POST", path: "/agents/{id}/rename" }).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
@@ -64,6 +72,10 @@ export const agentsContract = {
     diff: oc.route({ method: "GET", path: "/agents/{id}/diff" }).input(AgentIdSchema).output(AgentChangesSchema),
     fileDiff: oc.route({ method: "GET", path: "/agents/{id}/{repo}/file-diff" }).input(AgentFileDiffQuerySchema).output(FileDiffSchema),
     land: oc.route({ method: "POST", path: "/agents/{id}/land" }).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.
+    requestLand: oc.route({ method: "POST", path: "/agents/{id}/request-land" }).input(AgentIdSchema).output(AgentSummarySchema),
     discard: oc.route({ method: "POST", path: "/agents/{id}/discard" }).input(AgentIdSchema).output(OkSchema),
     archive: oc.route({ method: "POST", path: "/agents/archive" }).input(AgentArchiveSchema).output(AgentsMovedSchema),
     unarchive: oc.route({ method: "POST", path: "/agents/unarchive" }).input(AgentIdsSchema).output(AgentsMovedSchema),

package/src/contracts/automations.contract.ts

@@ -2,6 +2,8 @@ import { oc } from "@orpc/contract";
 import {
     AutomationApprovalIdParamSchema,
     AutomationApprovalsListSchema,
+    AutomationCatalogSchema,
+    AutomationEnabledInputSchema,
     AutomationIdParamSchema,
     AutomationSchema,
     AutomationsListSchema,
@@ -10,12 +12,19 @@ import {
 
 // 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), so the enabled toggle is a plain re-post. `remove` deletes.
+// 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.
 export const automationsContract = {
     list: oc.route({ method: "GET", path: "/automations" }).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", path: "/automations/catalog" }).output(AutomationCatalogSchema),
     upsert: oc.route({ method: "POST", path: "/automations" }).input(AutomationSchema).output(OkSchema),
+    setEnabled: oc.route({ method: "POST", path: "/automations/{id}/enabled" }).input(AutomationEnabledInputSchema).output(OkSchema),
     remove: oc.route({ method: "DELETE", path: "/automations/{id}" }).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
@@ -27,6 +36,13 @@ export const automationsContract = {
      * 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. */
     run: oc.route({ method: "POST", path: "/automations/{id}/run" }).input(AutomationIdParamSchema).output(OkSchema),

package/src/contracts/capabilities.contract.ts

@@ -2,8 +2,12 @@ import { eventIterator, oc } from "@orpc/contract";
 import { IntenticLineSchema } from "../events.js";
 import {
     CapabilitiesListSchema,
+    CapabilityCardParamSchema,
+    CapabilityConnectionSchema,
     CapabilityIdParamSchema,
     CapabilityLoginSchema,
+    CapabilityOtpSchema,
+    CapabilityRenameSchema,
     CapabilitySchema,
     CapabilitySecretInputSchema,
     CapabilityStatusSchema,
@@ -21,11 +25,29 @@ export const capabilitiesContract = {
     list: oc.route({ method: "GET", path: "/capabilities" }).output(CapabilitiesListSchema),
     add: oc.route({ method: "POST", path: "/capabilities" }).input(CapabilitySchema).output(eventIterator(IntenticLineSchema)),
     remove: oc.route({ method: "DELETE", path: "/capabilities/{id}" }).input(CapabilityIdParamSchema).output(OkSchema),
+    /* Give a connection a different name, carrying what the old one keyed: a browser profile with its logins,
+     * a connected machine's enrollment, an extension's checkout. The name is the agent's handle for the thing,
+     * so this is a migration — add + remove would lose exactly the state that makes the connection worth
+     * keeping. A kind whose name is part of what it IS (the scaffolders, the one-per-sandbox cards) refuses. */
+    rename: oc.route({ method: "POST", path: "/capabilities/{id}/rename" }).input(CapabilityRenameSchema).output(OkSchema),
     // Replace just the secret in a capability's config (the /secrets page's edit) and re-run its apply.
     setSecret: oc.route({ method: "POST", path: "/capabilities/{id}/secret" }).input(CapabilitySecretInputSchema).output(OkSchema),
     status: oc.route({ method: "GET", path: "/capabilities/{id}/status" }).input(CapabilityIdParamSchema).output(CapabilityStatusSchema),
+    /* One capability's stored config, secrets included — how an extension BACKEND dials the service behind a
+     * connected capability (ext-deployments reads its Komodo's key pair through this). Never a browser's: the
+     * handler refuses any caller with a member identity, so only the daemon's header grants reach it, and an
+     * extension's grant reaches it only when its manifest declares the route in `permissions.daemon` — which
+     * is the install dialog saying, in one line, "this extension can read connected credentials". */
+    connection: oc.route({ method: "GET", path: "/capabilities/{id}/connection" }).input(CapabilityIdParamSchema).output(CapabilityConnectionSchema),
     marketplace: oc.route({ method: "POST", path: "/capabilities/marketplace" }).input(MarketplaceRequestSchema).output(MarketplaceSchema),
+    // "Not needed": stop offering this card until the workspace evidence behind it changes. Nothing is torn
+    // down and nothing is remembered about the card itself — only the evidence it was declined against.
+    dismiss: oc.route({ method: "DELETE", path: "/capabilities/recommendations/{card}" }).input(CapabilityCardParamSchema).output(OkSchema),
     // Start an agent-kind capability's interactive login (its declared loginCommand) in a visible terminal
     // session the user types into — device-code sign-in flows. Returns the session the panel attaches to.
     login: oc.route({ method: "POST", path: "/capabilities/{id}/login" }).input(CapabilityIdParamSchema).output(CapabilityLoginSchema),
+    // Mint one TOTP code from the capability's stored seed (a field its card marks `totp`). The one capability
+    // read the agent token is admitted to (see auth/grants): a code expires within its period and never reveals
+    // the seed, so the in-sandbox `otp` command can answer a 2FA prompt without the agent holding the factor.
+    otp: oc.route({ method: "GET", path: "/capabilities/{id}/otp" }).input(CapabilityIdParamSchema).output(CapabilityOtpSchema),
 };

package/src/contracts/ci.contract.ts

@@ -1,5 +1,13 @@
 import { oc } from "@orpc/contract";
-import { CiFixResponseSchema, CiJobsResponseSchema, CiRunParamSchema, CiRunsResponseSchema, CiSeenResponseSchema, OkSchema } from "../schemas.js";
+import {
+    CiFixParamSchema,
+    CiFixResponseSchema,
+    CiJobsResponseSchema,
+    CiRunParamSchema,
+    CiRunsResponseSchema,
+    CiSeenResponseSchema,
+    OkSchema,
+} from "../schemas.js";
 
 // Pipelines on the workspace repos' github/gitlab remotes. `runs` serves the Pipelines rail view (cache +
 // on-demand backfill; per-repo webhook warnings ride along); `rerun`/`cancel` proxy to the vendor; `fix`
@@ -11,7 +19,7 @@ export const ciContract = {
     rerun: oc.route({ method: "POST", path: "/ci/runs/rerun" }).input(CiRunParamSchema).output(OkSchema),
     cancel: oc.route({ method: "POST", path: "/ci/runs/cancel" }).input(CiRunParamSchema).output(OkSchema),
     jobs: oc.route({ method: "POST", path: "/ci/runs/jobs" }).input(CiRunParamSchema).output(CiJobsResponseSchema),
-    fix: oc.route({ method: "POST", path: "/ci/fix" }).input(CiRunParamSchema).output(CiFixResponseSchema),
+    fix: oc.route({ method: "POST", path: "/ci/fix" }).input(CiFixParamSchema).output(CiFixResponseSchema),
     // "I have looked at the pipelines" — what silences the rail badge for breakages already read. No input:
     // the surface is read as a whole, and the daemon stamps its own clock so a skewed browser can't mark
     // future failures as already seen.

package/src/contracts/claude.contract.ts

@@ -1,9 +1,9 @@
 import { oc } from "@orpc/contract";
 import {
     AccountIdSchema,
+    AccountListQuerySchema,
     AccountRenameSchema,
     AuthorizeChallengeSchema,
-    ModelsSchema,
     OauthAccountListSchema,
     OauthAccountSchema,
     OauthExchangeSchema,
@@ -14,12 +14,16 @@ import {
 // PKCE material; `exchange` stores the resulting tokens as a new account and returns it; `accounts` lists the
 // connected accounts; `rename` renames one; `disconnect` clears the one named by id. A sandbox can hold several
 // Claude accounts.
+//
+// The model catalog is NOT here: it is the one thing every provider answers identically, so it lives on the
+// shared /providers/{provider}/models route (providers.contract.ts). What is left is what is genuinely Claude's
+// — an account handshake no other provider has.
 export const claudeContract = {
     start: oc.route({ method: "POST", path: "/claude/oauth/start" }).output(AuthorizeChallengeSchema),
     exchange: oc.route({ method: "POST", path: "/claude/oauth/exchange" }).input(OauthExchangeSchema).output(OauthAccountSchema),
-    // Claude's available models for the picker, from the Agent SDK's supportedModels() (see claude-models.ts).
-    models: oc.route({ method: "GET", path: "/claude/models" }).output(ModelsSchema),
-    accounts: oc.route({ method: "GET", path: "/claude/accounts" }).output(OauthAccountListSchema),
+    // Each account carries its plan-limit reading. `force` re-measures before answering — see
+    // AccountListQuerySchema, and USAGE_WAIT_MS in claude.routes.ts for what an ordinary read waits.
+    accounts: oc.route({ method: "GET", path: "/claude/accounts" }).input(AccountListQuerySchema).output(OauthAccountListSchema),
     rename: oc.route({ method: "POST", path: "/claude/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
     disconnect: oc.route({ method: "POST", path: "/claude/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
 };

package/src/contracts/endpoints.contract.ts

@@ -1,10 +1,31 @@
 import { oc } from "@orpc/contract";
+import { z } from "zod";
 import { CapabilityIdParamSchema, ModelsSchema } from "../schemas.js";
 
 // An `endpoint` capability's picker catalog — the models the configured server itself publishes, read from its
 // own /v1/models. Every other provider's catalog is one fixed route because there is one of each; endpoints are
 // user-created and unbounded, so the id rides in the path. There is no seed floor and no static list: what a
 // model API serves is knowable only by asking it, and an empty answer is the honest report that we could not.
+
+/* The free trial's remaining allowance, on the endpoints contract because the trial IS an endpoint — the one
+ * the daemon provisions rather than the user (agent-catalog.ts TRIAL_ENDPOINT_ID). It is a separate read from
+ * the catalog above because it answers a different question and changes on a different clock: the model list is
+ * a property of the upstream, while this is a property of the ACCOUNT and moves with every message sent.
+ *
+ * `available` false is the ordinary answer, not an error: most sandboxes run against a platform that serves no
+ * trial, and the picker simply has no trial row to badge.
+ */
+export const TrialStatusSchema = z.object({
+    available: z.boolean(),
+    allowance: z.number().int().nonnegative(),
+    used: z.number().int().nonnegative(),
+    remaining: z.number().int().nonnegative(),
+    // ISO stamp of the next reset, absent until the platform has answered once.
+    resetsAt: z.string().optional(),
+});
+export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;
+
 export const endpointsContract = {
     models: oc.route({ method: "GET", path: "/endpoints/{id}/models" }).input(CapabilityIdParamSchema).output(ModelsSchema),
+    trial: oc.route({ method: "GET", path: "/endpoints/trial/status" }).output(TrialStatusSchema),
 };

package/src/contracts/extensions.contract.ts

@@ -6,8 +6,17 @@ import {
     ExtensionProcessStatusSchema,
     ExtensionSettingsInputSchema,
     ExtensionSettingsSchema,
+    ExtensionReadinessSchema,
+    ExtensionUpdateActionSchema,
+    ExtensionUpdateAppliedSchema,
+    ExtensionUpdatePolicyInputSchema,
+    ExtensionUpdatePreviewSchema,
+    ExtensionUpdatesCheckedSchema,
+    ExtensionUsageInputSchema,
     ExtensionsListSchema,
     OkSchema,
+    WorkspaceExtensionCreatedSchema,
+    WorkspaceExtensionCreateSchema,
 } from "../schemas.js";
 
 // Installed extensions resolved to their approved manifests — what the web extension host boots from. The
@@ -16,12 +25,45 @@ import {
 // declared are refused, the same honesty rule the host applies to runtime view/command registrations.
 export const extensionsContract = {
     list: oc.route({ method: "GET", path: "/extensions" }).output(ExtensionsListSchema),
+    // Author a new extension in place: writes a running one into .intentic/workspace-extensions/<name>/. The only
+    // creating route here, and it exists because that directory is otherwise reachable exclusively through an
+    // agent's file tools — which is a fine way to CHANGE an extension and a poor way to meet the idea of one.
+    create: oc.route({ method: "POST", path: "/extensions/workspace" }).input(WorkspaceExtensionCreateSchema).output(WorkspaceExtensionCreatedSchema),
     settings: oc.route({ method: "GET", path: "/extensions/{id}/settings" }).input(CapabilityIdParamSchema).output(ExtensionSettingsSchema),
     setSettings: oc.route({ method: "POST", path: "/extensions/{id}/settings" }).input(ExtensionSettingsInputSchema).output(OkSchema),
     // The owner's on/off switch. Disabling stops the extension's declared processes here and now; its agent
     // plugin dir and PATH entry are rebuilt per turn, and an `environment` fragment only at the next image
     // rebuild — the Extensions tab states which of those an extension actually has.
     setEnabled: oc.route({ method: "POST", path: "/extensions/{id}/enabled" }).input(ExtensionEnabledInputSchema).output(OkSchema),
+    // The host reporting which declared routes it just let through. Written by the browser because that is where
+    // the permission gate runs (apiImpl.ts) — the daemon sees an extension's traffic as ordinary authenticated
+    // requests and cannot tell which extension, or which declared entry, any of it belongs to.
+    recordUsage: oc.route({ method: "POST", path: "/extensions/{id}/usage" }).input(ExtensionUsageInputSchema).output(OkSchema),
+    /* Whether this extension is fit for somebody else to run — the checks answerable from its files alone. Read
+     * on demand rather than carried on the list: it reads the bundle off disk per extension, and it is looked at
+     * when an author is about to publish, not every time the tab renders. */
+    readiness: oc.route({ method: "GET", path: "/extensions/{id}/readiness" }).input(CapabilityIdParamSchema).output(ExtensionReadinessSchema),
+    /* The update lifecycle for a GIT-INSTALLED extension. The list carries what the periodic registry check
+     * found (update/advisory/health per row); these are the verbs around it. `checkUpdates` runs the comparison
+     * now (the tab's "check now"). `updatePreview` stages the offered sha and answers with the version story +
+     * the mechanical powers diff — the read BEFORE the click, costing one throwaway clone like a registry
+     * browse. `applyUpdate` is the transaction: re-clone, validate, quiesce, swap (keeping the outgoing
+     * checkout one back), restart, health-watch — on the EXISTING capability config, so a private-source token
+     * survives what a bare re-add would lose. `revert` swaps the kept-previous checkout back. Update and revert
+     * change the code that runs, so like install they are owner-only. */
+    checkUpdates: oc.route({ method: "POST", path: "/extensions/updates/check" }).output(ExtensionUpdatesCheckedSchema),
+    updatePreview: oc
+        .route({ method: "POST", path: "/extensions/{id}/update/preview" })
+        .input(ExtensionUpdateActionSchema)
+        .output(ExtensionUpdatePreviewSchema),
+    applyUpdate: oc
+        .route({ method: "POST", path: "/extensions/{id}/update" })
+        .input(ExtensionUpdateActionSchema)
+        .output(ExtensionUpdateAppliedSchema),
+    revert: oc.route({ method: "POST", path: "/extensions/{id}/revert" }).input(CapabilityIdParamSchema).output(ExtensionUpdateAppliedSchema),
+    // The owner's standing answer per extension (notify / agent / auto, and the advisory opt-out) — see
+    // ExtensionUpdatePolicySchema for what each rung means.
+    setUpdatePolicy: oc.route({ method: "POST", path: "/extensions/{id}/update-policy" }).input(ExtensionUpdatePolicyInputSchema).output(OkSchema),
     // Declared background processes (contributes.processes): tmux-managed through the panel machinery
     // (session `panel-ext-<id>-<name>`, PORT-assigned, optional tunneled preview route).
     processStatus: oc