@intentic/sandbox-contract 1.167.0 → 1.168.0

package/src/schemas.ts

@@ -262,6 +262,14 @@ export const AgentSummarySchema = z.object({
     // Completed turns and lifetime tool calls — the card's msgs/tools counters.
     turns: z.number().optional(),
     toolUses: z.number().optional(),
+    /* The agents THIS agent started (SubagentSessionSchema), live and lifetime. Absent ⇒ it has never delegated,
+     * which is most agents — so the card's chip appears on content rather than reading "0" down the board.
+     *
+     * It earns a place on a card because a fleet card is the answer to "what is this agent up to", and an agent
+     * running five children looked exactly like an agent running none: the work was real, the spend was real, and
+     * the board said nothing. The tokens are NOT folded into the parent's cost — a child's spend is its own, and
+     * the Subagents area is where it is attributed. */
+    subagents: z.object({ running: z.number(), total: z.number() }).optional(),
     // The agent's cumulative output (base → branch tip across every repo), refreshed on each land —
     // the card's "12 files · +412 −96" readout. Independent of what has landed.
     diff: z.object({ files: z.number(), insertions: z.number(), deletions: z.number() }).optional(),
@@ -383,9 +391,52 @@ export const AgentLandSchema = z.object({ id: z.string().min(1), mode: LandModeS
 export const KeyedProviderSchema = z.enum(["codex", "grok", "kimi", "gemini"]);
 export type KeyedProvider = z.infer<typeof KeyedProviderSchema>;
 
+// ---- plan-limit usage ----
+// Declared ABOVE both account shapes because both carry it: headroom is one idea in this product, not a Claude
+// idea that other providers imitate. A native account (OauthAccount) and a routed subscription
+// (TranslatorAccount) differ in who holds the credential and how the reading is taken — never in what a
+// reading IS — so every surface that draws a percentage reads this one type and no other.
+
+// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
+// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
+// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
+// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
+// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
+// `resetsAt` is epoch SECONDS (matching the SDK's frame).
+export const UsageWindowSchema = z.object({
+    kind: z.string(),
+    label: z.string().optional(),
+    utilization: z.number(), // 0-100
+    resetsAt: z.number().optional(),
+});
+export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+
+// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
+// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
+// comparing accounts needs the same pools on every row. How the reading is TAKEN is per provider and stops at
+// the daemon's readers: Claude's rides the turn's own stream, ChatGPT's and Google's are pulled through
+// CLIProxyAPI's credential-scoped management call. All of them are control requests, so none costs tokens.
+//
+// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
+// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
+// (matching connectedAt) — deliberately a different unit from the windows' seconds.
+export const AccountUsageSchema = z.object({
+    windows: z.array(UsageWindowSchema),
+    measuredAt: z.number(),
+});
+export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+
 // One connected subscription in the translator. `name` is CLIProxyAPI's auth-file name — the stable store key a
 // disconnect addresses — and `label` the sign-in identity it reported (the account email, else the file name).
-export const TranslatorAccountSchema = z.object({ name: z.string(), label: z.string() });
+export const TranslatorAccountSchema = z.object({
+    name: z.string(),
+    label: z.string(),
+    // The same headroom an OauthAccount carries, on the same field, for the same reason: the account rows are
+    // one list to the reader. Optional because a provider whose quota this sandbox cannot read (Grok, Kimi) —
+    // or one that did not answer — must still render as the connected account it is, with a dot instead of a
+    // ring.
+    usage: AccountUsageSchema.optional(),
+});
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 // Which routed-provider subscriptions are connected in the translator, per provider — a LIST per provider, not
 // a flag: CLIProxyAPI holds any number of auth files per provider side by side and balances requests across
@@ -453,14 +504,8 @@ export const SteerSchema = z
 // True cancel for the conversation's in-flight turn — aborts the agent daemon-side, unlike closing the
 // /agent fetch (which sends no cancel frame).
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
-// Fire the conversation's remembered usage-limit resume NOW instead of waiting out the reset. `account`
-// points the re-run at a different connected account of the same provider — the "resume on another account"
-// action a spent allowance offers when the sandbox holds more than one; omitted, the turn re-runs on
-// whatever served it (a plain "try again now"). NOT_FOUND when nothing is pending (the failure was already
-// superseded by a fresh turn, or the daemon restarted).
-export const ResumeLimitSchema = z.object({ conversationId: z.string().min(1), account: z.string().min(1).optional() });
-
-// ---- claude subscription usage ----
+
+// ---- claude rate-limit gate ----
 // The GATE signal: whether the provider is letting turns through right now, and — when it is refusing — which
 // window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
 // ever about the CURRENT moment. It is deliberately NOT the thing the headroom displays read: the event names a
@@ -474,34 +519,6 @@ export const RateLimitInfoSchema = z.object({
 });
 export type RateLimitInfo = z.infer<typeof RateLimitInfoSchema>;
 
-// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
-// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
-// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
-// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
-// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
-// `resetsAt` is epoch SECONDS (matching the SDK's frame).
-export const UsageWindowSchema = z.object({
-    kind: z.string(),
-    label: z.string().optional(),
-    utilization: z.number(), // 0-100
-    resetsAt: z.number().optional(),
-});
-export type UsageWindow = z.infer<typeof UsageWindowSchema>;
-
-// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
-// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
-// comparing accounts needs the same pools on every row. Sourced from the CLI's own usage endpoint at turn end
-// (see claudeUsageWindows) — a control request, so it costs no tokens.
-//
-// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
-// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
-// (matching connectedAt) — deliberately a different unit from the windows' seconds.
-export const AccountUsageSchema = z.object({
-    windows: z.array(UsageWindowSchema),
-    measuredAt: z.number(),
-});
-export type AccountUsage = z.infer<typeof AccountUsageSchema>;
-
 // ---- provider oauth ----
 // Claude uses the PKCE authorize-URL + paste-back handshake (start → exchange). Codex uses OpenAI's device-code
 // flow (start → poll): the browser signs in at verificationUri and enters userCode; the daemon polls until done.
@@ -528,8 +545,9 @@ export const OauthAccountSchema = z.object({
     needsReauth: z.boolean().optional(),
     detail: z.string().optional(),
     // The account's last known subscription-usage snapshot, so the picker can show what's left on each account
-    // before the user commits a turn to one. Claude-only (it is the sole provider whose stream reports a usage
-    // window) and absent until that account has run a turn — an unmeasured account reads as unknown, never 0%.
+    // before the user commits a turn to one. Absent until a reading exists for it — an unmeasured account reads
+    // as unknown, never 0%. Claude is the provider that fills it here, because its stream reports the windows;
+    // the routed subscriptions carry the identical field on TranslatorAccount, filled by a pulled reading.
     usage: AccountUsageSchema.optional(),
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
@@ -669,11 +687,6 @@ export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"
 // surface fail to parse the moment a toggle is added — which reaches the user as a page of switches that are
 // silently dead, not as an error. It also means an older on-disk manifest keeps the owner's other picks rather
 // than being discarded whole.
-// Build-wide kill switch for usage-limit auto-resume. Keep the setting and implementation in place while the
-// feature is disabled, but clamp every daemon response and settings write to OFF so a persisted `true` from an
-// older build cannot keep spending a newly reset allowance. The web also reads this constant to render the
-// control unavailable and to distrust a stale daemon that still reports a scheduled resume.
-export const USAGE_LIMIT_AUTO_RESUME_ENABLED: boolean = false;
 
 export const SandboxSettingsSchema = z.object({
     stableSystemPrompt: z.boolean().default(false),
@@ -746,18 +759,12 @@ export const SandboxSettingsSchema = z.object({
      * automation-opened agents (Discord, webhooks, email) finish turns with no browser in the room — a
      * browser-held preference could not govern them. Per-agent override: AgentSummarySchema.autoLand. */
     autoLand: z.boolean().default(true),
-    // Latent opt-in for re-running a turn after the Claude subscription's usage window resets. It defaults off
-    // because an unattended retry spends the fresh allowance without the user in the room, and the build-wide
-    // gate above currently clamps even an older saved opt-in off while the feature is unavailable.
-    autoResumeOnLimit: z
-        .boolean()
-        .default(false)
-        .overwrite((enabled) => USAGE_LIMIT_AUTO_RESUME_ENABLED && enabled),
     /* When a turn dies because the MODEL PROVIDER was failing (500/502/503, a 529 at capacity, a dropped
      * socket), re-run it on an escalating backoff until it goes through or the attempts are spent.
      *
-     * Defaults ON, unlike autoResumeOnLimit, and the difference is not an inconsistency: a spent allowance is
-     * the user's own budget, and resuming into a fresh window spends something they may have been saving. An
+     * Defaults ON, and a spent Claude allowance is the counter-example that explains why: that one is the
+     * user's own budget, and resuming into a freshly reset window spends something they may have been saving —
+     * so a usage limit stops the turn and says when it resets, and nothing re-runs it. An
      * outage resume spends nothing the dead turn had not already committed, resolves in minutes rather than
      * hours, and — the deciding argument — the turns hurt worst by it are the ones with nobody in the room
      * (automation wakes, Discord, webhooks), which no browser-held preference could ever rescue. It is the same
@@ -765,8 +772,8 @@ export const SandboxSettingsSchema = z.object({
     resumeAfterOutage: z.boolean().default(true),
     /* When the daemon dies under a running turn, re-run that turn once it is back (agent/turn-journal.ts records
      * every in-flight turn; the boot pass in agent/turn-resume.ts re-runs what survived). ON by default, where
-     * autoResumeOnLimit is off, and the difference is who broke the turn: a spent allowance is the user's own
-     * budget, while a restart is usually intentic's OWN doing — the container is recreated on every update,
+     * a spent usage limit re-runs nothing, and the difference is who broke the turn: a spent allowance is the
+     * user's own budget, while a restart is usually intentic's OWN doing — the container is recreated on every update,
      * every environment approval and every dev-sandbox.sh swap. Approving the Dockerfile change an agent asked
      * for must not cost the run that asked for it, and a user who just clicked Approve is in the room expecting
      * the work to continue, not a second button.
@@ -797,7 +804,7 @@ export const SandboxSettingsSchema = z.object({
     // gate exists to prevent is a green light nobody earned.
     gateTimeoutMs: z.number().min(60_000).max(3_600_000).default(900_000),
     /* Wake a fixer automatically when the gate goes red, instead of only lighting the badge. ON with a
-     * configured command, unlike the other unattended-spend toggles (autoResumeOnLimit), and the difference is
+     * configured command, and the difference from the unattended spend a usage limit refuses is
      * that the spend here is the POINT: a red gate whose fix waits for the user to notice has moved the CI
      * round-trip into the workspace without removing it from the user's day. One attempt per verdict, so a
      * command that fails for a reason no agent can fix costs one turn, not a loop (gate/gate.ts). */
@@ -2507,7 +2514,7 @@ export const BrowserPageSchema = z.object({
     // The page's own title. Absent mid-navigation, which is exactly when a tab still needs to render.
     title: z.string().optional(),
     url: z.string(),
-    // The page the agent last drove. Exactly one page per running session has it.
+    // The page the agent last drove — on a finished session, the one it ended on. Exactly one page has it.
     active: z.boolean(),
 });
 export const BrowserSessionSchema = z.object({
@@ -2521,6 +2528,9 @@ export const BrowserSessionSchema = z.object({
     // still lists for a while, with the pages it had — the record of where the agent went.
     running: z.boolean(),
     activityAt: z.number(),
+    // When that Chromium went away, for the "closed 20m ago" line a finished session leads with. Absent while
+    // running, which is the same fact as `running` — but the view needs the timestamp, not just the flag.
+    finishedAt: z.number().optional(),
     pages: z.array(BrowserPageSchema),
 });
 export type BrowserPage = z.infer<typeof BrowserPageSchema>;
@@ -2529,6 +2539,75 @@ export const BrowsersListSchema = z.object({ sessions: z.array(BrowserSessionSch
 export type BrowsersList = z.infer<typeof BrowsersListSchema>;
 export const BrowserNameParamSchema = z.object({ name: z.string() });
 
+/* ---- subagents: the agents an agent starts ----
+ *
+ * The third thing a turn spawns that the operator can be shown, after its shell and its browser — and the only
+ * one that is itself an agent. Two kinds land in this one list, because from outside they are the same fact
+ * (another agent, working, that you did not start):
+ *   • `subagent` — the SDK's Agent/Task tool. The daemon learns of it from the SubagentStart/SubagentStop hooks
+ *     and the task_* stream messages, joined on `toolUseId`.
+ *   • `codex` / `grok` — a CLI the agent drove from its own Bash (agent/delegation.ts). Detected in the Bash
+ *     PreToolUse hook, bound to its thread/session id from the command's output.
+ *
+ * `id` IS THE SPAWNING TOOL CALL'S id — the Agent card's, or the Bash card's for a delegation. It is the one key
+ * every source already carries (the SDK's subagent meta, its task_* messages, and the `parentToolUseId` the
+ * client nests inner frames under), so nothing has to be correlated: a card links to its subagent with the id it
+ * already has, and the subagent points back at the card the same way. The ids the transcripts are actually READ
+ * with — the SDK's agent id, a Codex thread, an OpenCode session — stay daemon-side, because no surface asks a
+ * question they answer.
+ *
+ * WHAT A KIND CHANGES, and it is only ever the live view: a subagent has no process of its own to look at, so
+ * watching it means reading its transcript. A delegation runs in a tmux window, so it has both — `terminal`
+ * names it, and the card keeps its existing "Watch in terminal" beside the transcript door. */
+export const SubagentKindSchema = z.enum(["subagent", "codex", "grok"]);
+export type SubagentKind = z.infer<typeof SubagentKindSchema>;
+
+// running/pending are live; the rest are terminal. Deliberately the SDK's own task vocabulary
+// (SDKTaskUpdatedMessage.patch.status) rather than AgentStatus: this is not a fleet card's lifecycle (no
+// draft/landed/conflict), and mapping the two would invent states neither side reports.
+export const SubagentStatusSchema = z.enum(["pending", "running", "completed", "failed", "killed", "paused"]);
+export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
+
+export const SubagentSessionSchema = z.object({
+    id: z.string(),
+    kind: SubagentKindSchema,
+    // The conversation whose turn spawned this — what the area groups its rows by, and the way back to the chat
+    // the card lives in.
+    conversationId: z.string(),
+    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or the delegated
+    // provider's model, and the caller's one-line description. The area's row and the card's title read as
+    // `Explore · Locate claimIndexer definition`.
+    agentType: z.string().optional(),
+    description: z.string().optional(),
+    model: z.string().optional(),
+    // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
+    // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
+    spawnDepth: z.number().optional(),
+    // Backgrounded: the parent went on working instead of waiting for it. This is the whole reason the list
+    // exists — a backgrounded child used to be invisible until its result landed, sometimes minutes later.
+    background: z.boolean().optional(),
+    status: SubagentStatusSchema,
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    activityAt: z.number(),
+    // What it has spent and done so far (task_progress). Tokens are the child's own, so a parent's cost line and
+    // the sum of its children's are two different true numbers.
+    tokens: z.number().optional(),
+    toolUses: z.number().optional(),
+    lastTool: z.string().optional(),
+    // Its report — the last assistant message (SubagentStop) or the task summary. The answer to "what did it
+    // conclude?" without opening the transcript, which is the question a finished child is read for.
+    summary: z.string().optional(),
+    error: z.string().optional(),
+    // A delegation's live view: the tmux session its command runs in. Absent for an SDK subagent, which has no
+    // process of its own to attach to.
+    terminal: z.string().optional(),
+});
+export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
+export const SubagentsListSchema = z.object({ sessions: z.array(SubagentSessionSchema) });
+export type SubagentsList = z.infer<typeof SubagentsListSchema>;
+export const SubagentIdParamSchema = z.object({ id: z.string() });
+
 // ---- environment: the overlay Dockerfile extending the sandbox image ----
 // The approved file is DAEMON-COMPOSED: pinned FROM + capability fragments + the owner-approved custom section.
 // The agent writes the proposal file (.intentic/environment.Dockerfile — custom-section content only, no FROM)

package/src/title.ts

@@ -15,8 +15,12 @@
  * names a turn that arrived without one — an automation, a Discord message, a webchat visitor (agents-
  * registry.ts). One rule, because two would let the same prompt open under two different names depending on
  * where it entered. Nothing here calls a model: the title has to exist before the first frame comes back.
- * (A model DOES get its say later — the daemon's title-summary pass renames a still-derived title once the
- * first turn has an answer to read — but that is a promotion over this title, never a replacement for it.) */
+ *
+ * Which is exactly the ceiling on it. Cutting is not naming — what comes out is the user's own sentence,
+ * shortened, and a column of those is scannable only where the users' sentences happened to differ early. The
+ * name a conversation ends up WEARING is written a second or two later by a model that reads the same prompt
+ * and answers in the fleet board's own shape (the daemon's title-namer.ts). This is the title that holds the
+ * tab until that arrives, and the one it keeps if nothing is connected to write a better one. */
 
 // The registry's title budget (agents-registry MAX_TITLE_LENGTH, the rename input's maxlength) — the widest
 // any surface stores. Every surface truncates in CSS to its own width, so the clamp here is a storage cap,

package/src/workspace-state.test.ts

@@ -0,0 +1,129 @@
+import type { FileContribution } from "@intentic/extension-api";
+import { describe, expect, it } from "vitest";
+import { staleQueryKeys, WORKSPACE_STATE_FILES } from "./workspace-state.js";
+
+// What the automations extension declares in its manifest, and what the memory extension WOULD declare if the
+// watcher reported its files. Literals rather than the real manifests: an extension package importing this one is
+// the dependency direction, so reaching back for them here would invert it. The real manifests are checked
+// against this rule where they are loaded — web's fileBindings.test.ts and the daemon's file-bindings.test.ts.
+const AUTOMATIONS: readonly FileContribution[] = [
+    { path: `.intentic/automations.json`, invalidates: [`automations`] },
+    { path: `.intentic/approvals/`, invalidates: [`automation-approvals`] },
+];
+
+describe(`staleQueryKeys`, () => {
+    it(`maps a manifest write to the queries it makes stale`, () => {
+        expect(staleQueryKeys([`.intentic/capabilities.json`], [])).toEqual([`capabilities`, `environment`, `panels`]);
+    });
+
+    it(`matches a name family and a one-file-per-entry directory through one prefix each`, () => {
+        // environment.Dockerfile, environment.custom.Dockerfile, environment.approved.Dockerfile — one entry.
+        expect(staleQueryKeys([`.intentic/environment.custom.Dockerfile`], [])).toEqual([`environment`]);
+        expect(staleQueryKeys([`.intentic/drafts/post-1.json`], [])).toEqual([`drafts`]);
+    });
+
+    it(`refreshes the Drafts view when the AGENT writes a draft`, () => {
+        // The regression this table was reorganized around: the drafts skill writes these files directly, so
+        // there is no browser mutation to hang an invalidate on — the watcher push is the only signal, and it
+        // used to be dropped on the floor.
+        expect(staleQueryKeys([`.intentic/drafts/post-1.json`], [])).toEqual([`drafts`]);
+    });
+
+    it(`ignores unrelated churn under .intentic/`, () => {
+        // The amplification that turned an iq index rebuild into an endless request storm: a prefix test on
+        // `.intentic/` alone would invalidate every one of these queries for each index write.
+        expect(staleQueryKeys([`.intentic/iq/index.db`, `.intentic/claude/projects/p/session.jsonl`], [])).toEqual([]);
+    });
+
+    it(`ignores a store's own temp file while it is mid-swap`, () => {
+        // jsonFile writes `.<name>.<pid>.tmp` beside the target precisely so the atomic rename can't be read as
+        // a write to the target itself. A trailing-tag temp would prefix-match and bill an extra refetch.
+        expect(staleQueryKeys([`.intentic/.settings.json.42.tmp`], [])).toEqual([]);
+        expect(staleQueryKeys([`.intentic/settings.json`], [])).toEqual([`settings`]);
+    });
+
+    it(`ignores ordinary workspace edits`, () => {
+        expect(staleQueryKeys([`src/main.ts`, `README.md`], [])).toEqual([]);
+    });
+
+    it(`dedupes keys across a batch that touches several manifests`, () => {
+        // A capability add recomposes the overlay, so both entries claim `environment` — one refetch, not two.
+        expect(staleQueryKeys([`.intentic/capabilities.json`, `.intentic/environment.Dockerfile`], [])).toEqual([
+            `capabilities`,
+            `environment`,
+            `panels`,
+        ]);
+    });
+
+    it(`invalidates an extension's queries from its own declaration`, () => {
+        expect(staleQueryKeys([`.intentic/automations.json`], AUTOMATIONS)).toEqual([`automations`]);
+        expect(staleQueryKeys([`.intentic/approvals/a1.json`], AUTOMATIONS)).toEqual([`automation-approvals`]);
+    });
+
+    it(`makes nothing stale for an extension that is not running`, () => {
+        // The reason the live set is passed in rather than read off the installed list: `automations` is the
+        // extension's query key, so with the extension gone there is no cache entry for it to be about. The core
+        // table used to carry these two keys itself, and would have kept invalidating them either way.
+        expect(staleQueryKeys([`.intentic/automations.json`, `.intentic/approvals/a1.json`], [])).toEqual([]);
+    });
+
+    it(`lets an extension claim a path the core table deliberately ignores`, () => {
+        // The two lists are unioned flat, not layered: a narrow extension entry under a broad core entry that
+        // invalidates nothing must still fire. Without this, every path beneath one of the daemon's
+        // machine-state prefixes would be unreachable to extensions.
+        const nested: readonly FileContribution[] = [{ path: `.intentic/claude/projects/p/memory/`, invalidates: [`memory`] }];
+        expect(staleQueryKeys([`.intentic/claude/projects/p/memory/note.md`], nested)).toEqual([`memory`]);
+        // …and a sibling under the same core prefix stays ignored.
+        expect(staleQueryKeys([`.intentic/claude/projects/p/session.jsonl`], nested)).toEqual([]);
+    });
+
+    it(`dedupes a key two extensions both claim`, () => {
+        const twice: readonly FileContribution[] = [
+            { path: `.intentic/automations.json`, invalidates: [`automations`] },
+            { path: `.intentic/automations.json`, invalidates: [`automations`] },
+        ];
+        expect(staleQueryKeys([`.intentic/automations.json`], twice)).toEqual([`automations`]);
+    });
+});
+
+describe(`WORKSPACE_STATE_FILES`, () => {
+    it(`declares every entry under .intentic/, root-relative and forward-slash`, () => {
+        for (const file of WORKSPACE_STATE_FILES) {
+            expect(file.path.startsWith(`.intentic/`), file.path).toBe(true);
+            expect(file.path.includes(`\\`), file.path).toBe(false);
+        }
+    });
+
+    it(`states a reason for every entry that invalidates nothing`, () => {
+        // An empty `invalidates` is a real answer (daemon machine state, a deliberately-polled surface, a path
+        // whose query keys belong to an extension), but a SILENT one is indistinguishable from the omission this
+        // table exists to prevent — which is exactly how drafts went missing. Requiring the reason is what makes
+        // the difference visible at review time.
+        for (const file of WORKSPACE_STATE_FILES) {
+            if (file.invalidates.length === 0) {
+                expect(file.why, `${file.path} invalidates nothing and must say why`).toBeTruthy();
+            } else {
+                expect(file.why, `${file.path} invalidates queries, so \`why\` is dead weight`).toBeUndefined();
+            }
+        }
+    });
+
+    it(`keeps directory entries slash-terminated so they cannot swallow a sibling`, () => {
+        // `.intentic/drafts` without the slash would also prefix-match a future `.intentic/drafts-archive.json`.
+        for (const file of WORKSPACE_STATE_FILES.filter((entry) => entry.invalidates.length > 0)) {
+            const isFamilyPrefix = file.path.endsWith(`.`);
+            const isFile = file.path.endsWith(`.json`) || file.path.endsWith(`.Dockerfile`);
+            expect(isFile || isFamilyPrefix || file.path.endsWith(`/`), file.path).toBe(true);
+        }
+    });
+
+    it(`has no entry that prefix-matches another, so one write can't be billed twice`, () => {
+        for (const file of WORKSPACE_STATE_FILES) {
+            const overlapping = WORKSPACE_STATE_FILES.filter((other) => other !== file && other.path.startsWith(file.path));
+            expect(
+                overlapping.map((other) => other.path),
+                `${file.path} is a prefix of another entry`,
+            ).toEqual([]);
+        }
+    });
+});

package/src/workspace-state.ts

@@ -0,0 +1,160 @@
+import type { FileContribution } from "@intentic/extension-api";
+
+/* WHICH WORKSPACE FILE BACKS WHICH CORE VIEW — one declaration, read by both sides of the wire.
+ *
+ * The daemon's own state lives under `<workspace>/.intentic/`, the agent edits it out-of-band with its file
+ * tools, and the file watcher pushes every change as a `workspaceChanged` batch. Turning those paths back into
+ * "and therefore this view is stale" used to be a hand-written table in the BROWSER (web's systemEventRouting),
+ * maintained separately from the paths the daemon actually writes (composition.ts) — two lists of the same
+ * fact, in two packages, with nothing tying them together.
+ *
+ * They drifted, exactly as that shape always does. `.intentic/drafts/` is written by the AGENT (the drafts
+ * skill puts a file there) and rendered by the Drafts view, but it was never added to the browser's table — so
+ * a draft appearing on disk while the owner watched the page changed nothing until they refocused the tab.
+ * Extension settings and the members list were missing for the same reason; writing them out is what showed
+ * that neither is a drafts-shaped hole — see their entries.
+ *
+ * So the binding is declared HERE, once, in the package both the daemon and the browser already import, and
+ * each side derives what it needs: the daemon builds its store paths from `path`, the browser builds its
+ * invalidation table from `invalidates`. Adding a manifest without saying what it makes stale is now a change
+ * to one visible list rather than an omission in a file nobody edits — and `workspace-state.test.ts` fails when
+ * a daemon store names a `.intentic` path this list doesn't carry.
+ *
+ * This mirrors what routes.ts does for the route surface ("nothing is generated and nothing is hand-maintained")
+ * one layer over: the same refusal to keep the same knowledge in two places.
+ *
+ * EXTENSIONS declare their own half in their manifest (`contributes.files`, @intentic/extension-api), in the same
+ * two fields, and the browser unions the two lists — see staleQueryKeys. That split is what this table is FOR:
+ * before it existed the core enumeration had to carry `automations` and `automation-approvals`, query keys owned
+ * by the automations extension, because the extension had no way to say so itself. A key belongs to whoever
+ * queries it. */
+
+// A core entry is an extension's `contributes.files` entry plus the one thing only the core list needs: the
+// right to declare NO invalidations, which for a daemon-owned file is the answer more often than not.
+export interface WorkspaceStateFile {
+    /* Workspace-root-relative, forward-slash — the space `workspaceChanged` paths arrive in. Matching is by
+     * PREFIX, which lets one entry cover three shapes without a second matching rule:
+     *   - an exact file      `.intentic/settings.json`
+     *   - a directory        `.intentic/drafts/`     (one file per draft)
+     *   - a name family      `.intentic/environment.` (…Dockerfile, .custom.Dockerfile, .approved.Dockerfile)
+     * A directory entry keeps its trailing slash so it can never prefix-match a sibling file. */
+    readonly path: string;
+    /* The browser query keys this file's contents feed. EMPTY is a real answer, not a gap — a file the browser
+     * renders nothing from, or one deliberately kept off the push path — and `why` says which. Never a prefix
+     * test over `.intentic/` as a whole: one stray write must not cost every view a refetch, which is the
+     * amplification that once turned an iq index rebuild into an endless request storm. */
+    readonly invalidates: readonly string[];
+    // Why this file has no invalidations, for the entries that declare none. Absent when it has some.
+    readonly why?: string;
+}
+
+export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
+    // A capability add/remove recomposes the environment overlay and can add or drop a repo's panel.
+    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels"] },
+    { path: ".intentic/environment.", invalidates: ["environment"] },
+    { path: ".intentic/settings.json", invalidates: ["settings"] },
+    // Written by the AGENT's file tools (the drafts skill), read by the owner's approval inbox — the one entry
+    // here whose whole point is that a change arrives from outside the browser that renders it.
+    { path: ".intentic/drafts/", invalidates: ["drafts"] },
+    // ---- declared by the extension that renders them (contributes.files), not here ----
+    // The path is the DAEMON's (automations-store writes both), the query keys are the intentic.automations
+    // extension's. It declares them in its own manifest and the browser unions the two lists, so uninstalling
+    // the extension takes its invalidations with it instead of leaving a rule for a view that no longer exists.
+    {
+        path: ".intentic/automations.json",
+        invalidates: [],
+        why: "Declared by the intentic.automations extension's contributes.files — `automations` is its query key, not core's.",
+    },
+    {
+        path: ".intentic/approvals/",
+        invalidates: [],
+        why: "Declared by the intentic.automations extension's contributes.files — `automation-approvals` is its query key, not core's.",
+    },
+
+    /* ---- reached by no query, for reasons that are not oversights ----
+     *
+     * This channel's currency is a QUERY KEY, and invalidation only reaches a query something is observing.
+     * Both entries below are outside that by design, so an empty set is the honest record — naming a key no
+     * query uses would put the drift this table exists to remove straight back into it. Each says which
+     * constraint would have to move first, so the next reader doesn't re-derive it. */
+    {
+        path: ".intentic/extension-settings.json",
+        invalidates: [],
+        why: "Held in a module-level shallowRef store per extension (web's extensionSettingsStore) with no query observer, and deliberately so: api.settings.get must answer SYNCHRONOUSLY from an extension's first activate() line, and the store outlives every component scope. A module-level QueryObserver is the one shape that would make invalidation refetch, and this app already ruled it out — it detaches on the queryClient.clear() at logout (see useSandbox's sandbox-list mirror). So a remote member's setting edit reaches this browser on its next load, not live.",
+    },
+    {
+        path: ".intentic/members.json",
+        invalidates: [],
+        why: "Not this view's source at all: SandboxAccess renders the PLATFORM's invite records (apiClient.invite.list), and this file is the daemon's ENFORCED copy — written first so a grant the enforcer never got is never recorded, then never read back. A change here means the two disagreed, which the write order makes fail-closed rather than stale.",
+    },
+
+    // ---- daemon-owned, nothing derives from watching them ----
+    {
+        path: ".intentic/gate.json",
+        invalidates: [],
+        why: "The landing gate's verdict is POLLED on purpose (web's useGate). Its fingerprint pass rewrites this file every couple of seconds while a check runs, and pushing that back would refetch the review set — the daemon's most expensive read — on every poll.",
+    },
+    {
+        path: ".intentic/gate-index/",
+        invalidates: [],
+        why: "The gate's per-repo git index. Machine state, rewritten continuously by the fingerprint pass.",
+    },
+    /* Agent session transcripts, rewritten on every streamed token.
+     *
+     * The memory notes under it (`projects/<slug>/memory/**`) ARE user-facing and the /memory view polls them
+     * every 30s, which is the one place in this table where a poll survives a real change feed being available.
+     * It stays a poll deliberately: the watcher's exclusion is a DESCENT filter, so reaching those notes means
+     * letting it walk `.intentic/claude` → `projects` → every project slug. Measured on the live workspace that
+     * is +119 watched directories against ~593 today (a fifth more), with 314 continuously-rewritten transcripts
+     * inside the newly-watched set, to make ONE memory directory live. Notes change at agent-turn cadence, so the
+     * poll costs a request a minute and the alternative costs a permanent 20% on the watcher. */
+    {
+        path: ".intentic/claude/",
+        invalidates: [],
+        why: "Agent session transcripts — see the note above on why the memory notes under it stay polled.",
+    },
+    {
+        path: ".intentic/ci.json",
+        invalidates: [],
+        why: "Webhook secret + conclusion memory; the Pipelines view reads it through /ci/runs, not off disk.",
+    },
+    { path: ".intentic/bridge-tokens.json", invalidates: [], why: "Hashed ACP bridge tokens, listed on demand by the owner." },
+    {
+        path: ".intentic/owner.json",
+        invalidates: [],
+        why: "Bound once on first use; a change here means the sandbox was re-owned, which re-authenticates anyway.",
+    },
+    { path: ".intentic/workspace.json", invalidates: [], why: "The workspace identity, read from the /events hello frame rather than as a file." },
+    { path: ".intentic/templates.json", invalidates: [], why: "Scaffold templates, read when the scaffold dialog opens." },
+    {
+        path: ".intentic/browser/",
+        invalidates: [],
+        why: "Browser-login profiles: Chromium rewrites these constantly. Descent-ignored by the watcher outright.",
+    },
+    {
+        path: ".intentic/extensions/",
+        invalidates: [],
+        why: "Extension checkouts — whole git clones. The `extensions` query is driven by the capability manifest above, not by their contents.",
+    },
+    { path: ".intentic/plugins/", invalidates: [], why: "Agent plugin dirs, read by the SDK's loader each turn." },
+];
+
+/* The query keys a batch of changed paths makes stale, deduped and stable. The browser's `/events` handler calls
+ * this; keeping it here rather than in the web means the rule is unit-testable without a query client, and the
+ * daemon can assert against the same table.
+ *
+ * `contributed` is what the ACTIVATED extensions declared in `contributes.files` — passed in rather than
+ * imported, because which extensions are live is a browser fact this package has no way to know. It is a
+ * required argument for the same reason: an added second source that callers may forget is a source that
+ * silently does nothing, which is the failure this whole file exists to remove. Extension entries are unioned
+ * flat with the core ones, not layered over them: both lists describe the same fact about the same file, and a
+ * path can legitimately match one entry in each — a core prefix that invalidates nothing must not veto a
+ * narrower extension entry beneath it, or everything under one of the daemon's machine-state prefixes would be
+ * unreachable to extensions by construction. */
+export const staleQueryKeys = (paths: readonly string[], contributed: readonly FileContribution[]): readonly string[] => [
+    ...new Set(
+        [...WORKSPACE_STATE_FILES, ...contributed]
+            .filter((file) => file.invalidates.length > 0 && paths.some((path) => path.startsWith(file.path)))
+            .flatMap((file) => file.invalidates),
+    ),
+];