npm - @intentic/extension-api - Versions diffs - 1.214.0 → 1.215.0 - Mend

@intentic/extension-api 1.214.0 → 1.215.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM7D,MAAM,WAAW,UAAU;IACvB,OAAO,IAAI,IAAI,CAAC;CACnB;AAKD,MAAM,WAAW,UAAU;IAEvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAGnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACxD;AAQD,MAAM,WAAW,SAAS;IAGtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAKpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAYnC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAItE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAcD,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IAElC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAID,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAGpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAMvB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;~~IAGnD~~,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,eAAe,EAAE,KAAK,UAAU,EAAE,CAAC;~~IAUzG~~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"}
1	+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/background.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1 @@

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

package/dist/index.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +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"}
1	+ {"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 CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +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"}
1	+ {"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 ADDED Viewed

@@ -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 ADDED Viewed

	@@ -0,0 +1 @@
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 ADDED Viewed

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

package/dist/protocol.js.map ADDED Viewed

	@@ -0,0 +1 @@
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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/dist/version.js CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/extension-api",
-  "version": "1.214.0",
+  "version": "1.215.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.215.0"
   },
   "peerDependencies": {
     "vue": "3"

package/src/api.ts CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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";