A local-first multi-agent app development platform, built on PenguinHarness
/**
* Install scope (lib/install-scope.ts): browser state that names one data root's entities is
* swept when the server starts serving a different root, and nothing else ever is.
*
* - Every `penguin.*` key the source persists is classified — checked against the source, since
* a key added to the app and forgotten here is the one way this module silently stops working;
* each deliberate exclusion is still a key the source contains.
* - An exact preference is never captured by a family that shares its stem
* (`penguin.sidebarCollapsed` beside `penguin.sidebarCollapsedGroups.`, `penguin.terminal.theme`
* beside `penguin.terminal.page.id`); the rule table is well formed.
* - A changed install id sweeps the install-scoped keys, orphans of every earlier root included,
* and keeps the preferences and every key no rule covers.
* - An unchanged id (every ordinary restart) sweeps nothing; a first sight adopts without
* sweeping, and the next boot is an ordinary one.
* - A sweep whose marker cannot be written back is reported apart from one that stuck; a store
* that throws only on enumeration sweeps nothing rather than half of it.
* - Asking the server: an unreachable server, a null identity, a 401 and a server that never
* answers (three seconds) all sweep nothing; blocked site data still lets boot proceed.
* - A swept boot reloads, and the second pass cannot resurrect the dock; every other outcome
* mounts, a sweep that could not be recorded included.
* - A tab left open across the wipe sweeps what it re-persisted when another tab records a
* different root, and ignores a first recording, a clear, a rewrite and every other key.
*/
import { describe, expect, it, vi } from "vitest";
import { setUnauthorizedHandler } from "../src/api/client";
import {
bootInstallScope,
INSTALL_ID_KEY,
KEY_RULES,
reactToInstallIdChange,
reconcileInstallScope,
scopeOfKey,
syncInstallScope,
} from "../src/lib/install-scope";
import type { InstallScopeStorage } from "../src/lib/install-scope";
import { apiError, json, stubFetch } from "./helpers/fetch";
import { expectEveryRootScanned, scanSources } from "./helpers/roots";
import type { SourceScan } from "./helpers/roots";
import { blockedStorage, memoryStorage, stubLocalStorage } from "./helpers/storage";
import type { MemoryStorage } from "./helpers/storage";
/** State that names the data root's Projects, Sessions, Workspaces and terminals. */
const INSTALL_STATE: Record<string, string> = {
"penguin.chatDraft.admin.default_project": '{"workspace":"/srv/app","agentId":"default_agent"}',
"penguin.chatDraft.session.admin.session-1": '{"text":"half a sentence"}',
"penguin.chatDrafts.admin.default_project": '[{"id":"draft-abcd1234"}]',
"penguin.sidebarWorkspaces.default_project": '[{"path":"/srv/app"}]',
"penguin.pinnedSessions.default_project": '["session-1"]',
"penguin.sessionOrder.default_project.workspace": '["session-1"]',
"penguin.sessionSeen.default_project": '{"session-1":"2026-08-26T00:00:00Z"}',
"penguin.groupOrder.default_project.workspace": '["/srv/app"]',
"penguin.sidebarCollapsedGroups.default_project": '["/srv/app"]',
"penguin.sidebarPinnedGroups.default_project": '["/srv/app"]',
"penguin.lastProjectId": "default_project",
"penguin.lastAgentId.default_project": "default_agent",
"penguin.memoryCollapsed.admin.default_project.default_agent": '["project"]',
"penguin.modelsExpandedGroups.default_project": '["anthropic"]',
"penguin.modelsGroupOrder.default_project": '["anthropic"]',
"penguin.dock.layout": '{"scopes":{"session-1":{}},"bottomRatio":0.4}',
"penguin.terminal.page.id": "term-1",
"penguin.orgTempSessions.admin.default_project.acme":
'[{"sessionId":"session-2","agentId":"acme_dev","title":"Build the site"}]',
};
/** This browser's preferences, whatever root it talks to. */
const PREFERENCES: Record<string, string> = {
"penguin.theme": "dark",
"penguin.themeId": "geek",
"penguin.textSize": "l",
"penguin.fontScale": "lg",
"penguin.fontLatin": "mona-sans",
"penguin.fontCjk": "noto-sans-sc",
"penguin.accent": "violet",
"penguin.currency": "CNY",
"penguin.terminal.theme": "dark",
"penguin.lang": "en",
"penguin.sidebarCollapsed": "1",
"penguin.panelWidth": "420",
"penguin.sidebarGroupMode": "agent",
"penguin.sidebarSortMode": "manual",
"penguin.sidebarNavGroupCollapsed": "collapsed",
"penguin.sidebarNavPinned": '{"models":false}',
"penguin.steerMode": "followup",
"penguin.dock.launcherY": "0.25",
"penguin.dock.launcherHidden": "1",
"penguin.files.treeVisible": "0",
"penguin.files.treeWidth": "220",
"penguin.files.editorWrap": "1",
"penguin.notifications": "1",
"penguin.keybindings": '{"v":1,"linux":{"terminal.close":"Mod+Alt+KeyW"}}',
};
/** A store holding both halves, with `marker` recorded as the install id when given. */
function populated(marker?: string): MemoryStorage {
return memoryStorage({
...INSTALL_STATE,
...PREFERENCES,
...(marker === undefined ? {} : { [INSTALL_ID_KEY]: marker }),
});
}
/** Order-independent snapshot of a store, so assertions do not depend on Map insertion order. */
function snap(entries: Iterable<[string, string]>): [string, string][] {
return [...entries].sort(([a], [b]) => a.localeCompare(b));
}
/** `before` with the marker set to `installId`. */
function marked(before: [string, string][], installId: string): [string, string][] {
const entries = new Map(before);
entries.set(INSTALL_ID_KEY, installId);
return snap(entries);
}
/** What a populated store holds once swept onto `installId`: the preferences and the marker. */
function sweptOnto(installId: string): [string, string][] {
return marked(Object.entries(PREFERENCES), installId);
}
/**
* Keys the source contains that KEY_RULES deliberately does not classify, each with the
* reason. Anything else the scan finds has to be in the table: a key the sweep does not
* recognise is left alone, which is exactly how the bug this module fixes comes back.
*/
const UNCLASSIFIED_ON_PURPOSE: Record<string, string> = {
"penguin.installId": "the marker itself — it is what the comparison reads, never swept",
"penguin.chatRouteApplied.":
"sessionStorage: scoped to one tab's history, so it cannot outlive a data root",
};
/**
* Every `penguin.*` key literal in the scanned source, mapped to the file it was found in.
*
* Block comments are stripped first, and a match must follow a quote or backtick: prose
* names key PREFIXES (`penguin.terminal.`), a family without its dot, and the product's own
* domain in an example URL (`penguin.ooo`), and none of those is a storage key.
*/
function storageKeysIn(scan: SourceScan): Map<string, string> {
const found = new Map<string, string>();
for (const file of scan.files) {
const code = file.text.replace(/\/\*[\s\S]*?\*\//g, "");
for (const match of code.matchAll(/["'`](penguin\.[A-Za-z0-9_.]*)/g)) {
const key = match[1]!;
if (!found.has(key)) found.set(key, file.id);
}
}
return found;
}
describe("install-scope classification", () => {
it("classifies every penguin.* key the source persists, and each exclusion is still one of them", () => {
const scan = scanSources([".ts", ".tsx"]);
expectEveryRootScanned(scan);
const found = storageKeysIn(scan);
// A scan that finds nothing would pass every assertion below without checking anything.
expect(found.size).toBeGreaterThan(20);
for (const [key, file] of found) {
if (key in UNCLASSIFIED_ON_PURPOSE) continue;
expect(scopeOfKey(key), `${key} (${file}) is missing from KEY_RULES`).not.toBeNull();
}
for (const key of Object.keys(UNCLASSIFIED_ON_PURPOSE)) {
expect(found.has(key), `${key} is no longer in the source`).toBe(true);
}
});
it("an exact preference is not captured by a family that shares its stem", () => {
// The two traps plain prefix matching would fall into.
expect(scopeOfKey("penguin.sidebarCollapsed")).toBe("browser");
expect(scopeOfKey("penguin.sidebarCollapsedGroups.default_project")).toBe("install");
expect(scopeOfKey("penguin.terminal.theme")).toBe("browser");
expect(scopeOfKey("penguin.terminal.page.id")).toBe("install");
});
it("rules are well formed: penguin-namespaced, families dotted, no duplicates", () => {
const seen = new Set<string>();
for (const rule of KEY_RULES) {
expect(rule.key.startsWith("penguin."), rule.key).toBe(true);
expect(rule.why.length, rule.key).toBeGreaterThan(0);
if (rule.kind === "family") expect(rule.key.endsWith("."), rule.key).toBe(true);
expect(seen.has(rule.key), rule.key).toBe(false);
seen.add(rule.key);
}
});
});
describe("reconcileInstallScope", () => {
it("a changed install id sweeps the install-scoped keys and keeps the preferences", () => {
const storage = populated("root-a");
expect(reconcileInstallScope("root-b", storage)).toBe("swept");
expect(snap(storage.map)).toEqual(sweptOnto("root-b"));
});
it("the sweep collects orphans of every earlier root, and leaves keys no rule covers", () => {
// Keys are id-suffixed, so a Project or Session that no longer exists leaves an entry
// nothing would ever read again. Walking the store is what reaches them.
const storage = memoryStorage({
[INSTALL_ID_KEY]: "root-a",
"penguin.chatDraft.admin.default_project": "{}",
"penguin.pinnedSessions.long_gone_project": '["session-9"]',
"penguin.sessionSeen.another_dead_project": "{}",
"penguin.theme": "dark",
"penguin.somethingAddedLater": "1",
"unrelated-app-key": "1",
});
expect(reconcileInstallScope("root-b", storage)).toBe("swept");
expect([...storage.map.keys()].sort()).toEqual(
[INSTALL_ID_KEY, "penguin.somethingAddedLater", "penguin.theme", "unrelated-app-key"].sort(),
);
});
it("an unchanged install id sweeps nothing (the ordinary server restart)", () => {
const storage = populated("root-a");
const before = snap(storage.map);
expect(reconcileInstallScope("root-a", storage)).toBe("unchanged");
expect(snap(storage.map)).toEqual(before);
});
it("first sight — keys but no recorded id — adopts without sweeping, and the next boot is an ordinary one", () => {
const storage = populated();
const before = snap(storage.map);
expect(reconcileInstallScope("root-a", storage)).toBe("adopted");
expect(snap(storage.map)).toEqual(marked(before, "root-a"));
expect(reconcileInstallScope("root-a", storage)).toBe("unchanged");
expect(reconcileInstallScope("root-b", storage)).toBe("swept");
});
it("a sweep whose marker cannot be recorded is reported apart from one that stuck", () => {
const storage = populated("root-a");
const readOnlyMarker: InstallScopeStorage = {
...storage,
get length(): number {
return storage.length;
},
setItem: () => {
throw new Error("quota exceeded");
},
};
// The keys still go; only the marker fails to land, so the next load compares again.
expect(reconcileInstallScope("root-b", readOnlyMarker)).toBe("swept-unrecorded");
expect(snap(storage.map)).toEqual(sweptOnto("root-a"));
});
it("a store that throws only on enumeration sweeps nothing rather than half of it", () => {
const storage = populated("root-a");
const before = snap(storage.map);
const half: InstallScopeStorage = {
...storage,
get length(): number {
throw new Error("site data is blocked");
},
};
expect(reconcileInstallScope("root-b", half)).toBe("swept");
expect(snap(storage.map)).toEqual(marked(before, "root-b"));
});
});
describe("syncInstallScope", () => {
it("a server that cannot be reached sweeps nothing and never rejects", async () => {
stubFetch(() => {
throw new Error("connection refused");
});
const storage = populated("root-a");
const before = snap(storage.map);
await expect(syncInstallScope(storage)).resolves.toBe("unknown");
expect(snap(storage.map)).toEqual(before);
});
it("a server reporting a null identity sweeps nothing", async () => {
stubFetch(() => json({ installId: null }));
const storage = populated("root-a");
const before = snap(storage.map);
await expect(syncInstallScope(storage)).resolves.toBe("unknown");
expect(snap(storage.map)).toEqual(before);
});
it("a non-2xx answer sweeps nothing", async () => {
stubFetch(() => apiError(401, "unauthorized", "Not signed in."));
// apiFetch takes a different branch from the network failure above: it parses the error
// body and, for a 401 outside /api/auth/, calls the global sign-out hook. Nothing is
// registered at this point in the boot — AuthProvider installs one during the first
// render, which has not happened — so the probe stays invisible; the spy pins that the
// hook is reached at all, since registering one EARLIER would then sign the user out.
const signedOut = vi.fn();
setUnauthorizedHandler(signedOut);
const storage = populated("root-a");
const before = snap(storage.map);
try {
await expect(syncInstallScope(storage)).resolves.toBe("unknown");
expect(signedOut).toHaveBeenCalledTimes(1);
expect(snap(storage.map)).toEqual(before);
} finally {
setUnauthorizedHandler(null);
}
});
it("gives up on a server that never answers, after three seconds, having swept nothing", async () => {
vi.useFakeTimers();
try {
// A request that never settles: the page renders nothing until this resolves, so the
// bound is the whole reason the timeout exists.
stubFetch(() => new Promise<Response>(() => {}));
const storage = populated("root-a");
const before = snap(storage.map);
const pending = syncInstallScope(storage);
let settled = false;
void pending.then(() => {
settled = true;
});
await vi.advanceTimersByTimeAsync(2999);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(1);
await expect(pending).resolves.toBe("unknown");
expect(snap(storage.map)).toEqual(before);
} finally {
vi.useRealTimers();
}
});
it("blocked site data still lets boot proceed", async () => {
stubFetch(() => json({ installId: "root-b" }));
// Every read reads as empty, so this looks like a first sight and adopts — an adoption
// that stores nothing, because the write throws too. Nothing is destroyed and boot
// continues, which is the whole requirement.
await expect(syncInstallScope(blockedStorage())).resolves.toBe("adopted");
});
});
/**
* The two-pass boot. dock-state.ts parses `penguin.dock.layout` into module state AT MODULE
* EVALUATION, which ES semantics put before main.tsx's first statement — so these tests
* install the storage global first and import that module dynamically, in the order a
* browser does it.
*/
describe("bootInstallScope", () => {
/** A bottom dock holding one terminal tab, arranged against the root that is about to go. */
const DOCK_FROM_ROOT_A = JSON.stringify({
scopes: {
"session-1": {
right: { tabs: [], active: null, open: false },
bottom: { tabs: ["terminal:term-abc"], active: "terminal:term-abc", open: true },
focus: "bottom",
},
},
bottomRatio: 0.4,
});
const serverReports = (installId: string | null) => stubFetch(() => json({ installId }));
// Two dynamic imports of dock-state's whole module graph are what this test costs, and that
// graph alone takes 3+ seconds on an idle machine — 5s left too little headroom and the suite
// went red on a loaded box. The timeout only bounds the wait; the assertions are unchanged.
it("a swept boot reloads instead of rendering, and the second pass cannot resurrect the dock", async () => {
const storage = stubLocalStorage(
memoryStorage({
[INSTALL_ID_KEY]: "root-a",
"penguin.dock.layout": DOCK_FROM_ROOT_A,
"penguin.theme": "dark",
}),
);
serverReports("root-b");
// Pass one. Every module evaluates before main.tsx runs a statement, so dock-state is
// already holding the pre-wipe map — including a terminal tab whose shell died with the
// old root — and its first scope switch would write the whole thing back.
vi.resetModules();
await import("../src/features/dock/dock-state");
expect(await bootInstallScope()).toBe("reload");
expect(storage.map.has("penguin.dock.layout")).toBe(false);
// Pass two — the reload. Every module re-evaluates against the swept store.
vi.resetModules();
const dock = await import("../src/features/dock/dock-state");
expect(await bootInstallScope()).toBe("mount");
// The first route resolution's setDockScope is what persisted the old map; here it can
// only persist what the fresh evaluation read, which is nothing.
dock.setDockScope("new");
const persisted = storage.map.get("penguin.dock.layout") ?? "";
expect(persisted).not.toContain("term-abc");
expect(persisted).not.toContain("session-1");
expect(storage.map.get("penguin.theme")).toBe("dark");
}, 20_000);
it("mounts on every outcome that swept nothing, and on a sweep that could not be recorded", async () => {
stubLocalStorage(memoryStorage({ [INSTALL_ID_KEY]: "root-a" }));
serverReports("root-a");
expect(await bootInstallScope()).toBe("mount");
stubLocalStorage(memoryStorage({ "penguin.theme": "dark" }));
serverReports("root-a");
expect(await bootInstallScope()).toBe("mount");
stubLocalStorage(memoryStorage({ [INSTALL_ID_KEY]: "root-a" }));
serverReports(null);
expect(await bootInstallScope()).toBe("mount");
// The reload would otherwise repeat forever: sweep, fail to record, reload, sweep again.
const backing = memoryStorage({ [INSTALL_ID_KEY]: "root-a", "penguin.lastProjectId": "p1" });
stubLocalStorage({
...backing,
get length(): number {
return backing.length;
},
setItem: () => {
throw new Error("quota exceeded");
},
});
serverReports("root-b");
expect(await bootInstallScope()).toBe("mount");
expect(backing.map.has("penguin.lastProjectId")).toBe(false);
});
});
describe("a tab left open across the wipe", () => {
it("sweeps its own re-persisted state when another tab records a different root", () => {
const storage = populated("root-b"); // the other tab already recorded it
const stale = reactToInstallIdChange(
{ key: INSTALL_ID_KEY, oldValue: "root-a", newValue: "root-b" },
storage,
);
expect(stale).toBe(true);
expect(snap(storage.map)).toEqual(sweptOnto("root-b"));
});
it("ignores the other tab's FIRST recording, which swept nothing itself", () => {
const storage = populated();
const before = snap(storage.map);
expect(
reactToInstallIdChange({ key: INSTALL_ID_KEY, oldValue: null, newValue: "root-a" }, storage),
).toBe(false);
expect(snap(storage.map)).toEqual(before);
});
it("ignores site data being cleared, and a rewrite of the same id", () => {
const storage = populated();
const before = snap(storage.map);
expect(
reactToInstallIdChange({ key: INSTALL_ID_KEY, oldValue: "root-a", newValue: null }, storage),
).toBe(false);
expect(
reactToInstallIdChange(
{ key: INSTALL_ID_KEY, oldValue: "root-a", newValue: "root-a" },
storage,
),
).toBe(false);
expect(snap(storage.map)).toEqual(before);
});
it("ignores every other key, including the ones it would otherwise sweep", () => {
const storage = populated();
const before = snap(storage.map);
expect(
reactToInstallIdChange(
{ key: "penguin.pinnedSessions.default_project", oldValue: "[]", newValue: '["s1"]' },
storage,
),
).toBe(false);
expect(reactToInstallIdChange({ key: null, oldValue: null, newValue: null }, storage)).toBe(
false,
);
expect(snap(storage.map)).toEqual(before);
});
});