@intentic/extension-api 1.214.0 → 1.216.0

package/README.md

@@ -56,6 +56,12 @@ packages, which is exactly the case a per-repo `detect()` cannot express. An off
 directory rather than an affordance every directory of its kind has says so (`evidence: true`), and the tree
 keeps its icon on the row instead of revealing it on hover — the difference between a reader seeing which
 packages have a page and a reader having to go looking for one.
+- **[scope.ts](src/scope.ts)** — `sandboxRef` and `sandboxScopeGuard`: how an extension keeps state that
+  belongs to ONE sandbox. See "Where state lives" below; this is the rule most easily got wrong, because
+  getting it wrong looks fine until somebody switches sandbox.
+- **[background.ts](src/background.ts)** — `sandboxPoll` and `sandboxLedger`: the work an extension does while
+  none of it is on screen. A tile that badges has to be filled by something, and what has already been seen has
+  to be written down somewhere; both were hand-written in six extensions before they were here.
 - **[stream.ts](src/stream.ts)**, **[version.ts](src/version.ts)** — SSE/ndjson helpers and the host API
   version (`engines.intentic` is checked against it before activation).
 
@@ -73,6 +79,64 @@ are `sandbox-contract` schemas, parsed at the call site (`Schema.parse(await api
 in-repo, compiled-together design means a wire change is a compiler error fixed atomically, so there is no
 separate "stable data API" to promote. `facts.ts` stays the stable surface only for *detection*.
 
+## Where state lives
+
+Three tiers, and the tier decides what happens when the user points the browser at a **different sandbox**.
+Everything an extension holds is about one workspace, so a switch has to leave nothing of the last one behind.
+
+- **Cached reads** — `useQuery` in a view, or `api.sandbox.fetch(query)` from outside one. Key them with
+  `api.sandbox.key(...)` and the switch is handled by construction: the key carries the active sandbox id, so
+  the next box is a different cache entry. Use the *same* key for a view's query and for the badge poll that
+  warms it, and the poll's answer becomes the view's first paint.
+- **State inside a mounted component** — an ordinary `ref` in a `.vue` file. Nothing to do; it dies with the
+  component.
+- **Module state owned by `activate()`** — the badge counts, presence maps and poll results that must survive
+  the view being unmounted, because a badge you only see after opening the view is pointless. Declare it with
+  `sandboxRef(() => initial)` and the host empties it on every switch. There is no subscription to remember
+  and no teardown to write; `dispose` is there for state that owns an object URL or anything else the garbage
+  collector will not take back.
+
+For anything asynchronous in that third tier, take a `sandboxScopeGuard()` **before** the await and ask it
+**after** — a poll issued against the last sandbox otherwise resolves a moment later and writes its answer
+into the new one, which is the same wrong badge with a harder repro. It matters twice over for a call that
+WRITES: acknowledging what a badge has shown, in the wrong workspace's tree, is bookkeeping no later poll
+corrects.
+
+## Keeping a tile current while nothing is mounted
+
+Most of that third tier exists to feed a rail badge, so `sandboxPoll` covers the whole shape and you should not
+need `sandboxRef` directly for one:
+
+```ts
+const { state: unseen, start } = sandboxPoll<readonly Finding[]>({
+    host,                       // your hostSlot's accessor — nothing is bound until activate()
+    everyMs: 60_000,            // no default: the right interval is a claim about how fast the answer moves
+    initial: () => [],
+    read: async (api) => findings(await api.sandbox.fetch(query())),
+});
+```
+
+`start()` returns the `Disposable` to push onto `context.subscriptions`; `refresh()` reads off-cycle for the
+moments that should not wait out the interval. The five rules a hand-written version has to remember — never
+reject, skip an unreachable daemon, discard an answer that outlived its sandbox, keep the last good value on
+failure, stop the clock on disposal — are the poll's, not yours. Pass `immediate: false` if there is nothing
+worth asking until something else tells you what to ask about, and read `previous` in `read` if a round
+accumulates onto what you already hold rather than replacing it.
+
+What the tile SAYS stays yours: `badge()` is the judgement each surface exists to make, and no two of them
+agree about tone or wording.
+
+`sandboxLedger(host, path)` is the other half — the JSON file recording what the owner has already seen, as
+`key → mark`, where the mark is what makes an entry stale. Compare marks (a chore's evidence digest, a story's
+verdict) and the same key with new evidence is news again; ignore them and it is a plain presence ledger. It
+reads a missing or mangled file as "nothing acknowledged", writes nothing when nothing moved, and holds the
+scope guard across its own read-then-write so an acknowledgement cannot land in the wrong workspace's tree.
+
+This is not advice. `sandboxScope.guard.test.ts` in the app walks each extension's UI entry through its own
+imports and refuses module-level `ref`/`shallowRef`/`reactive`, any reassignable module binding, and any
+repeating clock in what it reaches — because the failure it prevents was found in six extensions at once: a
+rail tile reading `21` under a workspace that had two.
+
 ## Authoring an extension
 
 `activate(api, context)` registers contributions and returns; `deactivate` is optional. A UI extension also
@@ -86,6 +150,8 @@ The five UI extensions under [`_extensions/`](../../_extensions) are the working
 - [src/engines.ts](src/engines.ts) — how `engines.intentic` is matched against the version below, for the host
   and the daemon alike.
 - [src/route.ts](src/route.ts) — the query rules a view with internal navigation uses.
+- [src/scope.ts](src/scope.ts) — module state that belongs to one sandbox, and the guard for work in flight
+  across a switch.
 - [src/version.ts](src/version.ts) and [src/surface.json](src/surface.json) — the protocol version, and what
   each version of it promised.
 

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/background.d.ts

@@ -0,0 +1,23 @@
+import type { Ref } from "vue";
+import type { Disposable, IntenticApi } from "./api.js";
+export interface SandboxPoll<T> {
+    readonly state: Ref<T>;
+    start(): Disposable;
+    refresh(): void;
+}
+export interface SandboxPollOptions<T> {
+    readonly host: () => IntenticApi;
+    readonly everyMs: number;
+    readonly initial: () => T;
+    readonly read: (api: IntenticApi, previous: T) => Promise<T>;
+    readonly immediate?: boolean;
+    readonly dispose?: (previous: T) => void;
+}
+export declare const sandboxPoll: <T>(options: SandboxPollOptions<T>) => SandboxPoll<T>;
+export interface SandboxLedger {
+    read(): Promise<Readonly<Record<string, string>>>;
+    mark(entries: Readonly<Record<string, string>>): Promise<boolean>;
+    replace(entries: Readonly<Record<string, string>>): Promise<boolean>;
+}
+export declare const sandboxLedger: (host: () => IntenticApi, path: string) => SandboxLedger;
+//# sourceMappingURL=background.d.ts.map

package/dist/background.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAyBxD,MAAM,WAAW,WAAW,CAAC,CAAC;IAI1B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAEvB,KAAK,IAAI,UAAU,CAAC;IAGpB,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IAGjC,QAAQ,CAAC,IAAI,EAAE,MAAM,WAAW,CAAC;IAIjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAK1B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAI7D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5C;AAED,eAAO,MAAM,WAAW,GAAI,CAAC,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,WAAW,CAAC,CAAC,CAgC5E,CAAC;AA0BF,MAAM,WAAW,aAAa;IAE1B,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAIlD,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAKlE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAKD,eAAO,MAAM,aAAa,SAAU,MAAM,WAAW,QAAQ,MAAM,KAAG,aAgCrE,CAAC"}

package/dist/background.js

@@ -0,0 +1,57 @@
+import { sandboxRef, sandboxScopeGuard } from "./scope.js";
+export const sandboxPoll = (options) => {
+    const state = sandboxRef(options.initial, options.dispose);
+    const once = async () => {
+        try {
+            const api = options.host();
+            if (!api.sandbox.reachable()) {
+                return;
+            }
+            const current = sandboxScopeGuard();
+            const next = await options.read(api, state.value);
+            if (!current()) {
+                return;
+            }
+            state.value = next;
+        }
+        catch {
+        }
+    };
+    return {
+        state,
+        refresh: () => void once(),
+        start: () => {
+            if (options.immediate !== false) {
+                void once();
+            }
+            const timer = setInterval(() => void once(), options.everyMs);
+            return { dispose: () => clearInterval(timer) };
+        },
+    };
+};
+const sameEntries = (left, right) => Object.keys(left).length === Object.keys(right).length && Object.entries(left).every(([key, mark]) => right[key] === mark);
+export const sandboxLedger = (host, path) => {
+    const read = async () => {
+        const parsed = await host().workspace.readJson(path);
+        return Object.fromEntries(Object.entries(parsed ?? {}).filter((entry) => typeof entry[1] === `string`));
+    };
+    const settle = async (next) => {
+        const current = sandboxScopeGuard();
+        const seen = await read();
+        const wanted = next(seen);
+        if (sameEntries(seen, wanted)) {
+            return true;
+        }
+        if (!current()) {
+            return false;
+        }
+        await host().workspace.write(path, `${JSON.stringify(wanted, undefined, 2)}\n`);
+        return true;
+    };
+    return {
+        read,
+        mark: async (entries) => settle((seen) => ({ ...seen, ...entries })),
+        replace: async (entries) => settle(() => entries),
+    };
+};
+//# sourceMappingURL=background.js.map

package/dist/background.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.js","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export * from "./api.js";
+export * from "./background.js";
 export * from "./diff.js";
 export * from "./engines.js";
 export * from "./facts.js";
 export * from "./host.js";
 export * from "./route.js";
+export * from "./scope.js";
 export * from "./server.js";
 export * from "./stream.js";
 export * from "./version.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -1,9 +1,11 @@
 export * from "./api.js";
+export * from "./background.js";
 export * from "./diff.js";
 export * from "./engines.js";
 export * from "./facts.js";
 export * from "./host.js";
 export * from "./route.js";
+export * from "./scope.js";
 export * from "./server.js";
 export * from "./stream.js";
 export * from "./version.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,3 @@
+export { satisfiesEngines } from "./engines.js";
+export { extensionApiVersion } from "./version.js";
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,3 @@
+export { satisfiesEngines } from "./engines.js";
+export { extensionApiVersion } from "./version.js";
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/scope.d.ts

@@ -0,0 +1,9 @@
+import { type Ref } from "vue";
+export declare const sandboxRef: <T>(initial: () => T, dispose?: (previous: T) => void) => Ref<T>;
+export interface SandboxValue<T> {
+    value: T;
+}
+export declare const sandboxValue: <T>(initial: () => T, dispose?: (previous: T) => void) => SandboxValue<T>;
+export declare const sandboxScopeGuard: () => (() => boolean);
+export declare const resetSandboxScope: () => void;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AA+CpC,eAAO,MAAM,UAAU,GAAI,CAAC,WAAW,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,KAAG,GAAG,CAAC,CAAC,CAStF,CAAC;AAIF,MAAM,WAAW,YAAY,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC;CACZ;AAoBD,eAAO,MAAM,YAAY,GAAI,CAAC,WAAW,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,KAAG,YAAY,CAAC,CAAC,CASjG,CAAC;AAiBF,eAAO,MAAM,iBAAiB,QAAO,CAAC,MAAM,OAAO,CAGlD,CAAC;AAIF,eAAO,MAAM,iBAAiB,QAAO,IAKpC,CAAC"}

package/dist/scope.js

@@ -0,0 +1,34 @@
+import { ref } from "vue";
+const registered = [];
+let generation = 0;
+export const sandboxRef = (initial, dispose) => {
+    const state = ref(initial());
+    registered.push({
+        clear: () => {
+            dispose?.(state.value);
+            state.value = initial();
+        },
+    });
+    return state;
+};
+export const sandboxValue = (initial, dispose) => {
+    const box = { value: initial() };
+    registered.push({
+        clear: () => {
+            dispose?.(box.value);
+            box.value = initial();
+        },
+    });
+    return box;
+};
+export const sandboxScopeGuard = () => {
+    const taken = generation;
+    return () => taken === generation;
+};
+export const resetSandboxScope = () => {
+    generation += 1;
+    for (const entry of registered) {
+        entry.clear();
+    }
+};
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAY,MAAM,KAAK,CAAC;AA6BpC,MAAM,UAAU,GAAiB,EAAE,CAAC;AAKpC,IAAI,UAAU,GAAG,CAAC,CAAC;AAanB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAI,OAAgB,EAAE,OAA+B,EAAU,EAAE;IACvF,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,CAAW,CAAC;IACvC,UAAU,CAAC,IAAI,CAAC;QACZ,KAAK,EAAE,GAAG,EAAE;YACR,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACvB,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,CAAC;QAC5B,CAAC;KACJ,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACjB,CAAC,CAAC;AA0BF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAI,OAAgB,EAAE,OAA+B,EAAmB,EAAE;IAClG,MAAM,GAAG,GAAoB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;IAClD,UAAU,CAAC,IAAI,CAAC;QACZ,KAAK,EAAE,GAAG,EAAE;YACR,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACrB,GAAG,CAAC,KAAK,GAAG,OAAO,EAAE,CAAC;QAC1B,CAAC;KACJ,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACf,CAAC,CAAC;AAiBF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAoB,EAAE;IACnD,MAAM,KAAK,GAAG,UAAU,CAAC;IACzB,OAAO,GAAG,EAAE,CAAC,KAAK,KAAK,UAAU,CAAC;AACtC,CAAC,CAAC;AAIF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAS,EAAE;IACxC,UAAU,IAAI,CAAC,CAAC;IAChB,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC7B,KAAK,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;AACL,CAAC,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const extensionApiVersion = "2.5.0";
+export declare const extensionApiVersion = "2.8.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,mBAAmB,UAAU,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAuDA,eAAO,MAAM,mBAAmB,UAAU,CAAC"}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const extensionApiVersion = "2.5.0";
+export const extensionApiVersion = "2.8.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAmCA,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAuDA,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/extension-api",
-  "version": "1.214.0",
+  "version": "1.216.0",
   "description": "The versioned public API intentic extensions compile against — manifest schema, detection facts and the host API",
   "license": "MIT",
   "type": "module",
@@ -28,12 +28,23 @@
         "@intentic/src": "./src/index.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": {
+        "@intentic/src": "./src/protocol.ts",
+        "default": "./dist/protocol.js"
+      },
+      "require": {
+        "@intentic/src": "./src/protocol.ts",
+        "default": "./dist/protocol.js"
+      }
     }
   },
   "dependencies": {
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
-    "@intentic/sandbox-contract": "1.214.0"
+    "@intentic/sandbox-contract": "1.216.0"
   },
   "peerDependencies": {
     "vue": "3"

package/src/api.ts

@@ -93,13 +93,23 @@ export interface ViewRegistration {
     // logs, its status, its consumption) — inspected occasionally rather than worked in, so it costs a tab in
     // a scrolling word-labelled strip instead of an icon in the rail's fixed budget.
     readonly surface: "rail" | "directory" | "sandbox";
-    // Evidence-based detection over the public facts — one activation per sidebar element. Called on every
-    // facts poll; a throwing detect contributes nothing that round.
+    /* Evidence-based detection over the public facts — one activation per sidebar element. Called on every
+     * facts poll; a throwing detect contributes nothing that round.
+     *
+     * MUST NOT WRITE REACTIVE STATE. This runs inside the host's render computed, so a `sandboxRef` (or any
+     * other `Ref`) written here is a computed mutating its own dependency: Vue re-runs it, it writes again,
+     * and the rail recurses until the frame is abandoned — taking every unrelated update queued behind it, so
+     * the symptom is a window that stops responding rather than one misbehaving tile.
+     *
+     * It IS the right place to notice things, though — it is the only callback that sees the live facts — so
+     * for the bookkeeping that notice produces (which connections a poller should ask about next round) use
+     * `sandboxValue`, which has the same lifetime and no observers. Same rule for `badge` below. */
     readonly detect: (repos: readonly RepoFacts[], capabilities: readonly CapabilityFacts[]) => Activation[];
     // What this activation's tile should say without being opened. Read inside the host's own computed, so
     // reading a ref here re-renders the tile when it changes — no push channel needed. Called on every render
     // of every surface that draws tiles, so it must be cheap and pure: derive from state the extension already
-    // keeps, never fetch. A throwing badge simply yields none.
+    // keeps, never fetch, and never write a ref (see detect above — same computed, same recursion). A throwing
+    // badge simply yields none.
     //
     // Requires `badge: true` on the manifest's matching contributes.views entry — the host drops the function
     // otherwise, because a tile that can interrupt the user is a contribution the owner must have approved.

package/src/background.ts

@@ -0,0 +1,169 @@
+import type { Ref } from "vue";
+import type { Disposable, IntenticApi } from "./api.js";
+import { sandboxRef, sandboxScopeGuard } from "./scope.js";
+
+/* WHAT AN EXTENSION DOES WHILE NONE OF IT IS ON SCREEN — the two pieces every surface that badges a rail tile
+ * turned out to need, and had been writing out by hand.
+ *
+ * A tile has to be able to say something before it is opened. That rules out the view's own query, which stops
+ * when the component unmounts, and it rules out the file-change push, which only reaches a query something is
+ * observing. So the state lives at module scope (scope.ts) and something refreshes it on a timer.
+ *
+ * Seven modules across six extensions arrived at the identical shape for that timer, and it carries five rules
+ * that are each invisible until they are broken:
+ *
+ *   never reject      it runs detached, so a throw is an unhandled rejection with no caller to report to — and
+ *                     that includes reading the host handle, which throws before activate() has bound one
+ *   skip when down    an unreachable daemon is not news; asking it is a failed request per tick, forever
+ *   guard the await   a read issued before a sandbox switch must not write its answer into the box after it
+ *   keep the last     a transient failure is not evidence that nothing is waiting, so a failed read changes
+ *                     nothing rather than blanking the tile
+ *   stop the clock    the interval is disposed with the extension, or a switched-off extension keeps polling
+ *
+ * Six of the seven copies got the third one wrong, which is what this pair exists to make impossible. What is
+ * NOT here is what each tile SAYS: the count, the tone and the wording are the whole point of each surface and
+ * differ deliberately, so `badge()` stays with the extension that owns the judgement. */
+
+export interface SandboxPoll<T> {
+    /* The value, as sandbox-scoped module state (scope.ts). Read it from `badge()` or `detect()` and the host's
+     * own computed repaints when it moves; write to it directly for the local fold a "mark as seen" does, which
+     * is what clears a tile on the spot instead of at the next tick. */
+    readonly state: Ref<T>;
+    // Begin polling. Push the Disposable onto `context.subscriptions` and the clock stops with the extension.
+    start(): Disposable;
+    // Read now, off-cycle — for the moments that change the answer and should not wait out the interval: a
+    // connection appearing, a draft published, a run discarded.
+    refresh(): void;
+}
+
+export interface SandboxPollOptions<T> {
+    // The extension's own host handle (hostSlot). A function, not the api itself, because this is constructed
+    // at module load and nothing is bound until activate() runs.
+    readonly host: () => IntenticApi;
+    /* How often, in milliseconds. There is no default on purpose: the right interval is a claim about how fast
+     * the answer actually changes, and a surface that has not thought about it will inherit whatever number
+     * happened to be chosen here. A badge is glanced at, so the honest range is minutes, not seconds. */
+    readonly everyMs: number;
+    // The value before anything has been read, rebuilt on every sandbox switch (sandboxRef).
+    readonly initial: () => T;
+    /* The read. Gets the api and the value currently held — the second for a poll that ACCUMULATES rather than
+     * replaces, where one failed source must leave its own last answer standing beside the others. Throwing is
+     * fine and means "nothing changed": the value in hand is kept.
+     */
+    readonly read: (api: IntenticApi, previous: T) => Promise<T>;
+    /* Whether `start()` reads immediately as well as on the interval. Default true, because a tile that only
+     * badges a minute after login is a tile nobody trusts. Set false when the poll has nothing to ask until
+     * something else tells it what to ask about — deployments learns its connections from `detect()`. */
+    readonly immediate?: boolean;
+    // For a value that owns something the garbage collector will not take back; see sandboxRef.
+    readonly dispose?: (previous: T) => void;
+}
+
+export const sandboxPoll = <T>(options: SandboxPollOptions<T>): SandboxPoll<T> => {
+    const state = sandboxRef(options.initial, options.dispose);
+
+    const once = async (): Promise<void> => {
+        try {
+            const api = options.host();
+            if (!api.sandbox.reachable()) {
+                return;
+            }
+            const current = sandboxScopeGuard();
+            const next = await options.read(api, state.value);
+            if (!current()) {
+                return;
+            }
+            state.value = next;
+        } catch {
+            // Whatever went wrong — an unbound host, a refused route, a daemon mid-boot — the answer is the
+            // same: leave the last value standing. "We could not ask" is not "there is nothing there".
+        }
+    };
+
+    return {
+        state,
+        refresh: () => void once(),
+        start: () => {
+            if (options.immediate !== false) {
+                void once();
+            }
+            const timer = setInterval(() => void once(), options.everyMs);
+            return { dispose: () => clearInterval(timer) };
+        },
+    };
+};
+
+/* WHAT THE OWNER HAS ALREADY SEEN, as a file in the workspace.
+ *
+ * The rail's bar is that a badge means "something happened here that you do not already know about". Meeting it
+ * needs somewhere to record what they DO know, and three extensions independently chose the same home: a JSON
+ * object under `.intentic`, keyed by whatever identifies the thing. That is the right home — it survives a
+ * reload, it is shared across the owner's browsers, and it needs no setting nobody would ever type — but each
+ * of them then hand-wrote the same tolerant reader and the same careful write.
+ *
+ * KEY → MARK, where the mark is what makes the entry STALE. That is the whole vocabulary, and it covers both
+ * the ledgers that compare (a chore's evidence digest, a story's verdict — the same key with a different mark
+ * is news again) and the ones that only ask whether a key is present at all (a document set reviewed once).
+ * A presence-only ledger writes the acknowledgement time as its mark, which nothing reads and a human opening
+ * the file is glad of.
+ *
+ * The file is written by agents and editable by hand, so a missing, truncated or hand-mangled one reads as
+ * "nothing acknowledged". That direction is deliberate: bad bookkeeping may light a badge that should have been
+ * quiet, and must never hide one that should have been lit.
+ *
+ * BOTH WRITES ANSWER "did this take effect", which is the question the caller's NEXT line depends on. Marking
+ * something seen is almost always followed by folding it out of the badge locally, so the tile clears on the
+ * spot rather than at the next poll — and that fold is a write into sandbox-scoped state, so it must not happen
+ * when the acknowledgement itself was abandoned because the owner switched sandbox mid-operation. It would
+ * silence the NEW box's badge for a fact about the old one. `false` means only that: the scope moved. A ledger
+ * that already said what you asked it to say answers `true`, because it does. */
+export interface SandboxLedger {
+    // Everything acknowledged so far. Absent, unparseable or not-an-object all read as nothing.
+    read(): Promise<Readonly<Record<string, string>>>;
+    /* Record these, leaving every other entry alone — the ordinary acknowledgement. No write happens when
+     * nothing moved: the file push would otherwise cost every connected browser a refetch for a file whose
+     * content is identical. */
+    mark(entries: Readonly<Record<string, string>>): Promise<boolean>;
+    /* Make these the WHOLE ledger, dropping anything not named. For a ledger whose keys go out of scope — a
+     * run that has scrolled past the scan window can never be seen again, and merging forever would grow the
+     * file without bound. Same no-op-when-unchanged rule as `mark`.
+     */
+    replace(entries: Readonly<Record<string, string>>): Promise<boolean>;
+}
+
+const sameEntries = (left: Readonly<Record<string, string>>, right: Readonly<Record<string, string>>): boolean =>
+    Object.keys(left).length === Object.keys(right).length && Object.entries(left).every(([key, mark]) => right[key] === mark);
+
+export const sandboxLedger = (host: () => IntenticApi, path: string): SandboxLedger => {
+    const read = async (): Promise<Readonly<Record<string, string>>> => {
+        const parsed = await host().workspace.readJson<Record<string, unknown>>(path);
+        // Non-string values are dropped rather than coerced: a mark is a string, and anything else is somebody
+        // else's idea of what this file is for.
+        return Object.fromEntries(Object.entries(parsed ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === `string`));
+    };
+
+    /* One writer for both verbs, and the scope guard lives HERE rather than at the call site — this is the
+     * only thing in an extension's background work that damages state on DISK when a sandbox switch lands
+     * mid-operation. Reading one workspace's acknowledgements and writing them into the tree of the workspace
+     * the owner has just moved to is bookkeeping filed in the wrong place, which no later poll corrects. */
+    const settle = async (next: (seen: Readonly<Record<string, string>>) => Readonly<Record<string, string>>): Promise<boolean> => {
+        const current = sandboxScopeGuard();
+        const seen = await read();
+        const wanted = next(seen);
+        // Already saying it. Nothing to write, and the caller's local fold is still right.
+        if (sameEntries(seen, wanted)) {
+            return true;
+        }
+        if (!current()) {
+            return false;
+        }
+        await host().workspace.write(path, `${JSON.stringify(wanted, undefined, 2)}\n`);
+        return true;
+    };
+
+    return {
+        read,
+        mark: async (entries) => settle((seen) => ({ ...seen, ...entries })),
+        replace: async (entries) => settle(() => entries),
+    };
+};

package/src/index.ts

@@ -1,9 +1,11 @@
 export * from "./api.js";
+export * from "./background.js";
 export * from "./diff.js";
 export * from "./engines.js";
 export * from "./facts.js";
 export * from "./host.js";
 export * from "./route.js";
+export * from "./scope.js";
 export * from "./server.js";
 export * from "./stream.js";
 export * from "./version.js";

package/src/protocol.ts

@@ -0,0 +1,18 @@
+/* THE HALF OF THIS PACKAGE THAT RUNS WITHOUT A BROWSER — the protocol version and the matcher that compares a
+ * manifest's `engines.intentic` against it.
+ *
+ * The root barrel is the EXTENSION-facing surface, and an extension runs in the app, so the barrel is free to
+ * reach for vue: `scope.ts` imports `ref` as a value, not a type. The daemon is the other consumer, and it
+ * needs exactly these two names — to refuse an incompatible extension (backend-supervisor), to stamp the
+ * version it provides (backend-host-main), to write an engines range into a scaffold. It has no vue and no
+ * reason to grow one, but `export *` loads every re-exported module eagerly, so importing the barrel for
+ * `extensionApiVersion` alone dragged `vue` into a Node process that could not resolve it — the daemon crashed
+ * on boot and the sandbox never became healthy.
+ *
+ * Hence this entry point. `@intentic/extension-api/protocol` is what host-side Node code imports; the root
+ * barrel keeps exporting both names too, so nothing about the published extension surface changes. Type-only
+ * imports from the root (`ExtensionServerApi` and friends) stay where they are — those are erased at compile
+ * time and never reach the loader. */
+
+export { satisfiesEngines } from "./engines.js";
+export { extensionApiVersion } from "./version.js";

package/src/scope.ts

@@ -0,0 +1,121 @@
+import { ref, type Ref } from "vue";
+
+/* STATE THAT BELONGS TO ONE SANDBOX, and the reason an extension cannot be left to remember that itself.
+ *
+ * Three tiers of client state exist in this app, and each needs a different answer to "what happens on a
+ * switch". Cached server state is keyed by `api.sandbox.key(...)`, so it is answered by construction. State
+ * inside a mounted component dies with the component. THIS is the third tier: module state owned by
+ * `activate()` — the badge counts, the document-presence maps, the poll results that must survive the view
+ * being unmounted, because a badge you only see once you have already navigated to the view is pointless.
+ *
+ * Nothing owned it. A rail tile filled by a ten-minute timer therefore kept the PREVIOUS sandbox's number for
+ * up to ten minutes after a switch, under the new sandbox's name — a badge is a claim addressed to the reader,
+ * and one describing a workspace they are no longer looking at is worse than no badge at all. It was not one
+ * extension's mistake either: every extension that badges had the identical shape, which is the signature of a
+ * missing primitive rather than of carelessness.
+ *
+ * So the host owns it. Declare the state through `sandboxRef` and the host empties it on every switch; there
+ * is no subscription to remember and no teardown to write.
+ *
+ * A MODULE-LEVEL REGISTRY IS CORRECT HERE, and that is worth saying because `hostSlot` in this same package
+ * warns against exactly that. The shell publishes ONE instance of this module to every bundle
+ * (extension-host/hostModules.ts), so a slot held here is shared by all of them — which made it wrong for a
+ * per-extension host handle and makes it right for this: one switch empties every extension's scope, and no
+ * extension can be missed. */
+
+interface Registered {
+    readonly clear: () => void;
+}
+
+const registered: Registered[] = [];
+
+/* Which scope the extensions are in, counted rather than named — this module cannot see the sandbox id, and
+ * does not need to. All any caller asks is "is this still the scope I started in", and a counter answers that
+ * without this package having to know what a sandbox is. */
+let generation = 0;
+
+/* MODULE STATE FOR ONE SANDBOX. `initial` is a factory, not a value, so each scope starts from a fresh object
+ * rather than sharing (and slowly mutating) one literal written at import time.
+ *
+ *     const unseen = sandboxRef<readonly ChoreVerdict[]>(() => []);
+ *
+ * It is an ordinary `Ref` in every other respect: read it in a `badge()` or a `detect()` and the host's own
+ * computed re-renders the tile when it changes, exactly as before. READ, not write — see `sandboxValue`.
+ *
+ * `dispose` is for state that owns something the garbage collector will not take back — an object URL, a
+ * subscription. It is handed the value being dropped, once, at the moment the scope closes. Most callers need
+ * none: a list of verdicts is released by being replaced. */
+export const sandboxRef = <T>(initial: () => T, dispose?: (previous: T) => void): Ref<T> => {
+    const state = ref(initial()) as Ref<T>;
+    registered.push({
+        clear: () => {
+            dispose?.(state.value);
+            state.value = initial();
+        },
+    });
+    return state;
+};
+
+// A sandbox-scoped box that nothing observes. Same shape as a `Ref` on purpose — `.value`, read and written —
+// so moving state between the two is one word at the declaration and nothing at the call sites.
+export interface SandboxValue<T> {
+    value: T;
+}
+
+/* MODULE STATE FOR ONE SANDBOX THAT NOTHING RENDERS — `sandboxRef`'s lifetime without its reactivity, for the
+ * bookkeeping a background poll keeps for ITSELF: which connections to ask about next round, the cursor a
+ * fetch resumes from, the id a retry belongs to.
+ *
+ * It exists because of where `detect()` and `badge()` are called from. Both run INSIDE the host's render
+ * computed — that is the whole mechanism by which a tile repaints when a poll lands — and a `Ref` WRITTEN from
+ * inside a computed is that computed mutating its own dependency. Vue re-runs it, the write happens again, and
+ * the rail recurses until Vue abandons the flush mid-frame. What the reader sees then is not one broken tile:
+ * every update queued behind the rail is dropped with the flush, so the whole window stops answering, and the
+ * console fills with a recursion error naming a component that is merely where the loop was noticed.
+ *
+ * So the division is by AUDIENCE, not by lifetime: `sandboxRef` for what a tile SHOWS, `sandboxValue` for what
+ * a poll REMEMBERS. Both are emptied on a switch by the same door, and writing this one from a render callback
+ * is safe precisely because there is nothing to invalidate. When a poll's own bookkeeping later turns out to
+ * be worth showing, promoting it is a one-word change — and the promotion is the moment to check that nothing
+ * writes it from `detect()`.
+ *
+ * `dispose` behaves exactly as it does on `sandboxRef`. */
+export const sandboxValue = <T>(initial: () => T, dispose?: (previous: T) => void): SandboxValue<T> => {
+    const box: SandboxValue<T> = { value: initial() };
+    registered.push({
+        clear: () => {
+            dispose?.(box.value);
+            box.value = initial();
+        },
+    });
+    return box;
+};
+
+/* THE GUARD FOR WORK THAT WAS ALREADY IN FLIGHT WHEN THE SWITCH HAPPENED.
+ *
+ * Emptying the refs is not enough on its own. A poll that issued its request under the old sandbox resolves a
+ * moment after the switch, and writes the old box's answer into the fresh scope — the same wrong badge, just
+ * harder to reproduce. There is no way for this module to cancel that request, so it offers the one thing the
+ * caller needs instead: a way to ask, after the await, whether the answer is still wanted.
+ *
+ * Take it BEFORE the await, ask it AFTER:
+ *
+ *     const current = sandboxScopeGuard();
+ *     const report = await api.sandbox.fetch(query);
+ *     if (!current()) return;
+ *     unseen.value = assess(report);
+ *
+ * Two lines, and the failure it prevents is invisible without them. */
+export const sandboxScopeGuard = (): (() => boolean) => {
+    const taken = generation;
+    return () => taken === generation;
+};
+
+/* THE HOST'S DOOR, called by the shell when the active sandbox changes — not by extensions, which have nothing
+ * to reset and no business resetting each other's. */
+export const resetSandboxScope = (): void => {
+    generation += 1;
+    for (const entry of registered) {
+        entry.clear();
+    }
+};

package/src/surface.json

@@ -276,5 +276,196 @@
         ],
         "listener": ["automation", "events", "provider"],
         "sandboxApi": ["fetch", "json", "key", "origin", "reachable", "request", "role", "rpc"]
+    },
+    "2.6.0": {
+        "manifest": [
+            "$schema",
+            "art",
+            "category",
+            "contributes",
+            "engines",
+            "entry",
+            "icon",
+            "logo",
+            "name",
+            "permissions",
+            "publisher",
+            "server",
+            "version"
+        ],
+        "contributes": [
+            "agent",
+            "automationTemplates",
+            "bin",
+            "capabilities",
+            "commands",
+            "documents",
+            "environment",
+            "files",
+            "listener",
+            "processes",
+            "settings",
+            "viewers",
+            "views"
+        ],
+        "api": [
+            "apiVersion",
+            "chat",
+            "commands",
+            "documents",
+            "models",
+            "navigate",
+            "processes",
+            "route",
+            "sandbox",
+            "settings",
+            "terminal",
+            "theme",
+            "viewers",
+            "views",
+            "workspace"
+        ],
+        "listener": ["automation", "events", "provider"],
+        "sandboxApi": ["fetch", "json", "key", "origin", "reachable", "request", "role", "rpc"],
+        "moduleExports": [
+            "extensionApiVersion",
+            "flattenQuery",
+            "hostSlot",
+            "mergeQuery",
+            "readDaemonStream",
+            "resetSandboxScope",
+            "sandboxRef",
+            "sandboxScopeGuard",
+            "satisfiesEngines"
+        ]
+    },
+    "2.7.0": {
+        "manifest": [
+            "$schema",
+            "art",
+            "category",
+            "contributes",
+            "engines",
+            "entry",
+            "icon",
+            "logo",
+            "name",
+            "permissions",
+            "publisher",
+            "server",
+            "version"
+        ],
+        "contributes": [
+            "agent",
+            "automationTemplates",
+            "bin",
+            "capabilities",
+            "commands",
+            "documents",
+            "environment",
+            "files",
+            "listener",
+            "processes",
+            "settings",
+            "viewers",
+            "views"
+        ],
+        "api": [
+            "apiVersion",
+            "chat",
+            "commands",
+            "documents",
+            "models",
+            "navigate",
+            "processes",
+            "route",
+            "sandbox",
+            "settings",
+            "terminal",
+            "theme",
+            "viewers",
+            "views",
+            "workspace"
+        ],
+        "listener": ["automation", "events", "provider"],
+        "sandboxApi": ["fetch", "json", "key", "origin", "reachable", "request", "role", "rpc"],
+        "moduleExports": [
+            "extensionApiVersion",
+            "flattenQuery",
+            "hostSlot",
+            "mergeQuery",
+            "readDaemonStream",
+            "resetSandboxScope",
+            "sandboxLedger",
+            "sandboxPoll",
+            "sandboxRef",
+            "sandboxScopeGuard",
+            "satisfiesEngines"
+        ]
+    },
+    "2.8.0": {
+        "manifest": [
+            "$schema",
+            "art",
+            "category",
+            "contributes",
+            "engines",
+            "entry",
+            "icon",
+            "logo",
+            "name",
+            "permissions",
+            "publisher",
+            "server",
+            "version"
+        ],
+        "contributes": [
+            "agent",
+            "automationTemplates",
+            "bin",
+            "capabilities",
+            "commands",
+            "documents",
+            "environment",
+            "files",
+            "listener",
+            "processes",
+            "settings",
+            "viewers",
+            "views"
+        ],
+        "api": [
+            "apiVersion",
+            "chat",
+            "commands",
+            "documents",
+            "models",
+            "navigate",
+            "processes",
+            "route",
+            "sandbox",
+            "settings",
+            "terminal",
+            "theme",
+            "viewers",
+            "views",
+            "workspace"
+        ],
+        "listener": ["automation", "events", "provider"],
+        "sandboxApi": ["fetch", "json", "key", "origin", "reachable", "request", "role", "rpc"],
+        "moduleExports": [
+            "extensionApiVersion",
+            "flattenQuery",
+            "hostSlot",
+            "mergeQuery",
+            "readDaemonStream",
+            "resetSandboxScope",
+            "sandboxLedger",
+            "sandboxPoll",
+            "sandboxRef",
+            "sandboxScopeGuard",
+            "sandboxValue",
+            "satisfiesEngines"
+        ]
     }
 }

package/src/version.ts

@@ -33,4 +33,24 @@
 // rather than a URL because the row is drawn before any code is cloned: a link would put a stranger's server in
 // the render path, track who is browsing, and rot after approval. Additive — a manifest that ships no drawing
 // falls to exactly the mark it had before.
-export const extensionApiVersion = "2.5.0";
+// 2.6.0 gives module state an owner across a sandbox switch: `sandboxRef` declares state that belongs to ONE
+// sandbox and `sandboxScopeGuard` protects the write of a read that was already in flight when the switch
+// happened (scope.ts). The tier existed and nothing cleared it — every extension that badges a rail tile from a
+// timer kept the previous sandbox's count under the new sandbox's name, which is the one thing a badge must
+// never do. Additive: an extension that keeps no module state is unchanged, and the host resets the scope
+// whether or not anything registered.
+// 2.7.0 adds the two halves of work an extension does while none of it is on screen (background.ts):
+// `sandboxPoll`, the timer behind a rail badge, and `sandboxLedger`, the file recording what the owner has
+// already seen. Seven modules across six extensions had hand-written the same poller — five invisible rules
+// each, and six of the seven had the sandbox-switch one wrong — and three had hand-written the same tolerant
+// reader and careful write over the same shape of file. Additive: nothing is removed, and an extension that
+// keeps polling by hand still runs.
+// 2.8.0 splits sandbox-scoped module state by AUDIENCE: `sandboxValue` is `sandboxRef`'s lifetime without its
+// reactivity, for what a background poll remembers for itself (which connections to ask about next round, the
+// cursor a fetch resumes from) rather than what a tile shows. `detect()` and `badge()` both run inside the
+// host's render computed, so a `Ref` written from either is a computed mutating its own dependency — Vue
+// re-runs it, it writes again, and the rail recurses until the flush is abandoned mid-frame, dropping every
+// unrelated update queued behind it. The symptom is a window that stops answering, blamed on whichever
+// component the loop was noticed in, so the fix has to be a box nothing observes rather than a rule to
+// remember. Additive: `sandboxRef` is unchanged, and both are emptied on a switch by the same door.
+export const extensionApiVersion = "2.8.0";