@steve31415/baselib 3.47.0 → 3.48.0

package/README.md

@@ -6,8 +6,9 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `~/migration/research/base-services-design.md`.
 
 Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `connector`, `s2s`, `db`, `http`, `sync`,
-`app-update`, `llm`, `email`, `twitter`, and `hub` (the connection hub's server core and app notifier). Browser exports: `log-browser`, `rum`,
-`slow-fetch`, `sync-browser`, and `app-update-browser`.
+`app-update`, `llm`, `email`, `twitter`, `hub` (the connection hub's server core and app notifier), `code-manifest` and
+`client-version`. Browser exports: `log-browser`, `rum`, `slow-fetch`, `sync-browser`, `app-update-browser`, and
+`extension-self-update`.
 
 `sync` provides the Postgres event-log and server protocol primitives;
 `sync-browser` provides the IndexedDB outbox and offline-first client.
@@ -36,6 +37,15 @@ app's hooks module (`DeployHooks` in `src/deploy/types.ts`) extends both,
 first step of any production investigation (same doc, "Investigating
 production state").
 
+Mac-run code (`~/plasticine-way/mac/sync/DESIGN.md`): `code-manifest` and the
+`pw-code-manifest` bin write and check a directory's `mac-code.json` (its
+tracked files' sha256 and one id); `extension-self-update` reloads an unpacked
+extension into code that verifies on disk and that its server says it
+deployed; `client-version` counts how long a Mac-run client has stayed behind
+while reporting continuously, for the "stayed behind" WARN. `pw-deploy` marks
+a running deploy in the git common dir (`pw-deploy.lock`) so the Mac's sync
+job does not fast-forward the checkout under the build.
+
 `twitter` provides Mirror-first tweet lookup, TwitterAPI.io batch/search/
 article calls, and thread assembly through direct reply edges. It includes
 one level of quotes, article bodies and URL expansions. Use one shared

package/dist/bin/pw-code-manifest.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/pw-code-manifest.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// `pw-code-manifest` — write or check a directory's mac-code.json (../code-manifest.ts;
+// plasticine-way mac/sync/DESIGN.md §3.3).
+//
+//   pw-code-manifest write <dir> [--exclude <pattern>]...   regenerate it
+//   pw-code-manifest check <dir> [--exclude <pattern>]...   exit 1 when it is stale (run by verify)
+//   pw-code-manifest id <dir>    [--exclude <pattern>]...   print the id of the files as they are now
+import { runCodeManifestCli } from '../code-manifest.js';
+process.exitCode = await runCodeManifestCli(process.argv.slice(2), process.cwd());

package/dist/client-version.d.ts

@@ -0,0 +1,52 @@
+/** Behind for this long, counted as above, before the first WARN. Expected is under 15 minutes. */
+export declare const BEHIND_WARN_MS: number;
+/** Further counted time before the WARN repeats. */
+export declare const BEHIND_REWARN_MS: number;
+export interface BehindState {
+    /** Counted time behind in this episode. */
+    behindMs: number;
+    /** Server time of the last report in this episode. */
+    lastAt: number;
+    /** behindMs at the last WARN in this episode, or null before the first. */
+    warnedAtMs: number | null;
+}
+export type BehindCause = 'switch_not_taken' | 'checkout_not_current';
+/**
+ * Why a client is behind, or null when it is not. `loaded`: the code the client
+ * runs (null or absent when it does not report one, e.g. a version from before
+ * code reports, which counts as behind). `disk`: the verified code on the Mac's
+ * disk (null when it does not verify). `shipped`: the code this server deployed.
+ */
+export declare function behindCause(report: {
+    loaded: string | null | undefined;
+    disk: string | null | undefined;
+    shipped: string;
+}): BehindCause | null;
+/** The gap cap for a client that reports every `intervalMs`. */
+export declare function gapCapFor(intervalMs: number): number;
+/** Fold one report into the episode. Returns null when the client is not behind (the episode ends). */
+export declare function accrueBehind(prev: BehindState | null, report: {
+    behind: boolean;
+    now: number;
+    gapCapMs: number;
+}): BehindState | null;
+/** Whether this state warrants a WARN now; when it does, the returned state records it. */
+export declare function shouldWarn(state: BehindState, limits?: {
+    thresholdMs?: number;
+    rewarnMs?: number;
+}): {
+    warn: boolean;
+    state: BehindState;
+};
+/** accrueBehind then shouldWarn: the one call an app makes per report. */
+export declare function recordBehind(prev: BehindState | null, report: {
+    behind: boolean;
+    now: number;
+    intervalMs: number;
+}, limits?: {
+    thresholdMs?: number;
+    rewarnMs?: number;
+}): {
+    state: BehindState | null;
+    warn: boolean;
+};

package/dist/client-version.js

@@ -0,0 +1,54 @@
+// "Stayed behind" accounting for code that runs on Steve's Mac (plasticine-way
+// mac/sync/DESIGN.md §3.6). Pure: each app persists the state per device and
+// calls this from the request that carries the device's report.
+//
+// A client is behind when the code it runs is not the code the server
+// deployed. The time that counts is time the client spent behind while
+// REPORTING CONTINUOUSLY: a report adds the gap since the previous one only
+// when that gap is at most `gapCapMs` (1.5 x the client's report interval).
+// A laptop asleep, offline or travelling contributes nothing, however long
+// (Steve, 2026-11-01: the laptop can easily be offline for 12 hours or more).
+// All times are the server's clock.
+/** Behind for this long, counted as above, before the first WARN. Expected is under 15 minutes. */
+export const BEHIND_WARN_MS = 4 * 60 * 60 * 1000;
+/** Further counted time before the WARN repeats. */
+export const BEHIND_REWARN_MS = 24 * 60 * 60 * 1000;
+/**
+ * Why a client is behind, or null when it is not. `loaded`: the code the client
+ * runs (null or absent when it does not report one, e.g. a version from before
+ * code reports, which counts as behind). `disk`: the verified code on the Mac's
+ * disk (null when it does not verify). `shipped`: the code this server deployed.
+ */
+export function behindCause(report) {
+    if (report.loaded === report.shipped)
+        return null;
+    return report.disk === report.shipped ? 'switch_not_taken' : 'checkout_not_current';
+}
+/** The gap cap for a client that reports every `intervalMs`. */
+export function gapCapFor(intervalMs) {
+    return Math.round(intervalMs * 1.5);
+}
+/** Fold one report into the episode. Returns null when the client is not behind (the episode ends). */
+export function accrueBehind(prev, report) {
+    if (!report.behind)
+        return null;
+    if (!prev)
+        return { behindMs: 0, lastAt: report.now, warnedAtMs: null };
+    const gap = report.now - prev.lastAt;
+    const counted = gap > 0 && gap <= report.gapCapMs ? gap : 0;
+    return { behindMs: prev.behindMs + counted, lastAt: Math.max(prev.lastAt, report.now), warnedAtMs: prev.warnedAtMs };
+}
+/** Whether this state warrants a WARN now; when it does, the returned state records it. */
+export function shouldWarn(state, limits = {}) {
+    const threshold = limits.thresholdMs ?? BEHIND_WARN_MS;
+    const rewarn = limits.rewarnMs ?? BEHIND_REWARN_MS;
+    const due = state.warnedAtMs === null ? state.behindMs >= threshold : state.behindMs - state.warnedAtMs >= rewarn;
+    return due ? { warn: true, state: { ...state, warnedAtMs: state.behindMs } } : { warn: false, state };
+}
+/** accrueBehind then shouldWarn: the one call an app makes per report. */
+export function recordBehind(prev, report, limits = {}) {
+    const state = accrueBehind(prev, { behind: report.behind, now: report.now, gapCapMs: gapCapFor(report.intervalMs) });
+    if (!state)
+        return { state: null, warn: false };
+    return shouldWarn(state, limits);
+}

package/dist/code-manifest.d.ts

@@ -0,0 +1,37 @@
+export declare const CODE_MANIFEST_FILE = "mac-code.json";
+export interface CodeManifest {
+    id: string;
+    files: Record<string, string>;
+}
+export interface CodeManifestOptions {
+    /** Paths to leave out, relative to the directory: `dir/` (a prefix), or a
+     *  glob where `*` matches within one path segment and `**` across segments. */
+    exclude?: string[];
+}
+/** The id over a file list (the browser twin is in extension-self-update). */
+export declare function codeIdOf(files: Record<string, string>): string;
+export declare function isExcluded(path: string, exclude?: string[]): boolean;
+/** Build the manifest for `dir` from git's tracked files as they are in the work tree. */
+export declare function buildCodeManifest(dir: string, options?: CodeManifestOptions): Promise<CodeManifest>;
+export declare function serializeCodeManifest(manifest: CodeManifest): string;
+export declare function writeCodeManifest(dir: string, options?: CodeManifestOptions): Promise<CodeManifest>;
+export interface CodeManifestCheck {
+    ok: boolean;
+    /** Paths added, removed or changed since the committed manifest was written. */
+    changed: string[];
+    committedId: string | null;
+    currentId: string;
+}
+/** Is the committed manifest current? (Run by each repo's verify.) */
+export declare function checkCodeManifest(dir: string, options?: CodeManifestOptions): Promise<CodeManifestCheck>;
+/** The committed manifest in `dir`, or null when absent or malformed. */
+export declare function readCodeManifest(dir: string): Promise<CodeManifest | null>;
+/**
+ * For a Node consumer reading its own directory (no git needed): the
+ * manifest's id when every listed file is present and matches and the id is
+ * the id of the list; null otherwise (a checkout in progress, a local edit, a
+ * missing or hand-edited manifest).
+ */
+export declare function verifyCodeManifestOnDisk(dir: string): Promise<string | null>;
+/** The `pw-code-manifest` command (src/bin/pw-code-manifest.ts). Returns the exit code. */
+export declare function runCodeManifestCli(argv: string[], cwd: string, out?: (line: string) => void, err?: (line: string) => void): Promise<number>;

package/dist/code-manifest.js

@@ -0,0 +1,176 @@
+// Code manifests: a committed list of a directory's files and their sha256, with
+// one id over the list (plasticine-way mac/sync/DESIGN.md §3.3).
+//
+// Steve's Mac runs extensions and daemons straight from git checkouts. Each of
+// those consumers switches to new code only when the code on disk verifies
+// against `mac-code.json` AND its id is the one the app's server says it
+// deployed. So the id must be computable three ways that agree: here (the
+// generator, the verify-time check, and server builds), in the browser
+// (`extension-self-update`), and in a Node consumer reading its own files
+// (`verifyCodeManifestOnDisk`).
+//
+// The id is sha256 over the sorted lines `<path>\0<sha256>\n`, first 16 hex
+// characters. Paths are relative to the directory, `/`-separated, and are
+// git's tracked files only, so untracked leftovers (.DS_Store, *.orig) never
+// change it. The manifest file itself is never listed.
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const CODE_MANIFEST_FILE = 'mac-code.json';
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** The id over a file list (the browser twin is in extension-self-update). */
+export function codeIdOf(files) {
+    const lines = Object.keys(files)
+        .sort()
+        .map((path) => `${path}\0${files[path]}\n`)
+        .join('');
+    return sha256Hex(lines).slice(0, 16);
+}
+function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*' && glob[i + 1] === '*') {
+            out += '.*';
+            i++;
+            if (glob[i + 1] === '/')
+                i++;
+        }
+        else if (c === '*') {
+            out += '[^/]*';
+        }
+        else {
+            out += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+export function isExcluded(path, exclude = []) {
+    return exclude.some((pattern) => pattern.endsWith('/') ? path.startsWith(pattern) : globToRegExp(pattern).test(path));
+}
+function gitLsFiles(dir) {
+    return new Promise((resolve, reject) => {
+        execFile('git', ['ls-files', '-z', '--', '.'], { cwd: dir, maxBuffer: 64 * 1024 * 1024 }, (error, stdout) => {
+            if (error)
+                reject(new Error(`git ls-files failed in ${dir}: ${error.message}`));
+            else
+                resolve(stdout.split('\0').filter((p) => p !== ''));
+        });
+    });
+}
+/** Build the manifest for `dir` from git's tracked files as they are in the work tree. */
+export async function buildCodeManifest(dir, options = {}) {
+    const paths = (await gitLsFiles(dir))
+        .filter((path) => path !== CODE_MANIFEST_FILE && !isExcluded(path, options.exclude))
+        .sort();
+    const files = {};
+    for (const path of paths)
+        files[path] = sha256Hex(await readFile(join(dir, path)));
+    return { id: codeIdOf(files), files };
+}
+export function serializeCodeManifest(manifest) {
+    return `${JSON.stringify({ id: manifest.id, files: manifest.files }, null, 2)}\n`;
+}
+export async function writeCodeManifest(dir, options = {}) {
+    const manifest = await buildCodeManifest(dir, options);
+    const target = join(dir, CODE_MANIFEST_FILE);
+    await writeFile(`${target}.tmp`, serializeCodeManifest(manifest));
+    await rename(`${target}.tmp`, target);
+    return manifest;
+}
+/** Is the committed manifest current? (Run by each repo's verify.) */
+export async function checkCodeManifest(dir, options = {}) {
+    const current = await buildCodeManifest(dir, options);
+    const committed = await readCodeManifest(dir);
+    const before = committed?.files ?? {};
+    const changed = [...new Set([...Object.keys(before), ...Object.keys(current.files)])]
+        .filter((path) => before[path] !== current.files[path])
+        .sort();
+    return { ok: committed !== null && changed.length === 0 && committed.id === current.id, changed, committedId: committed?.id ?? null, currentId: current.id };
+}
+/** The committed manifest in `dir`, or null when absent or malformed. */
+export async function readCodeManifest(dir) {
+    let raw;
+    try {
+        raw = await readFile(join(dir, CODE_MANIFEST_FILE), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const { id, files } = parsed;
+        if (typeof id !== 'string' || !files || typeof files !== 'object')
+            return null;
+        for (const value of Object.values(files))
+            if (typeof value !== 'string')
+                return null;
+        return { id, files: files };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * For a Node consumer reading its own directory (no git needed): the
+ * manifest's id when every listed file is present and matches and the id is
+ * the id of the list; null otherwise (a checkout in progress, a local edit, a
+ * missing or hand-edited manifest).
+ */
+export async function verifyCodeManifestOnDisk(dir) {
+    const manifest = await readCodeManifest(dir);
+    if (!manifest || codeIdOf(manifest.files) !== manifest.id)
+        return null;
+    for (const [path, expected] of Object.entries(manifest.files)) {
+        let bytes;
+        try {
+            bytes = await readFile(join(dir, path));
+        }
+        catch {
+            return null;
+        }
+        if (sha256Hex(bytes) !== expected)
+            return null;
+    }
+    return manifest.id;
+}
+/** The `pw-code-manifest` command (src/bin/pw-code-manifest.ts). Returns the exit code. */
+export async function runCodeManifestCli(argv, cwd, out = (line) => console.log(line), err = (line) => console.error(line)) {
+    const [command, dirArg, ...rest] = argv;
+    const exclude = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--exclude' && rest[i + 1] !== undefined)
+            exclude.push(rest[++i]);
+        else {
+            err(`pw-code-manifest: unexpected argument ${rest[i]}`);
+            return 2;
+        }
+    }
+    if (!dirArg || !['write', 'check', 'id'].includes(command ?? '')) {
+        err('usage: pw-code-manifest write|check|id <dir> [--exclude <pattern>]...');
+        return 2;
+    }
+    const dir = join(cwd, dirArg);
+    if (command === 'write') {
+        const manifest = await writeCodeManifest(dir, { exclude });
+        out(`${join(dirArg, CODE_MANIFEST_FILE)}: ${manifest.id} (${Object.keys(manifest.files).length} files)`);
+        return 0;
+    }
+    if (command === 'id') {
+        out((await buildCodeManifest(dir, { exclude })).id);
+        return 0;
+    }
+    const check = await checkCodeManifest(dir, { exclude });
+    if (check.ok) {
+        out(`${join(dirArg, CODE_MANIFEST_FILE)} is current (${check.currentId})`);
+        return 0;
+    }
+    err(`${join(dirArg, CODE_MANIFEST_FILE)} is stale${check.committedId ? '' : ' or missing'}: ${check.changed.slice(0, 20).join(', ') || '(id mismatch)'}`);
+    err(`Regenerate it: npx pw-code-manifest write ${dirArg}${exclude.map((p) => ` --exclude '${p}'`).join('')}`);
+    return 1;
+}

package/dist/deploy/deploy-marker.d.ts

@@ -0,0 +1,5 @@
+export declare const DEPLOY_MARKER_FILE = "pw-deploy.lock";
+/** The git common dir of `repoRoot`, without running git; null outside a checkout. */
+export declare function gitCommonDir(repoRoot: string): Promise<string | null>;
+/** Write the marker; returns a remover (a no-op outside a git checkout). Never throws. */
+export declare function writeDeployMarker(repoRoot: string, now?: Date): Promise<() => Promise<void>>;

package/dist/deploy/deploy-marker.js

@@ -0,0 +1,63 @@
+// The "a deploy is running from this checkout" marker (plasticine-way
+// mac/sync/DESIGN.md §3.2).
+//
+// pw-deploy checks the tree once at preflight and then builds from the live
+// work tree for minutes. On Steve's Mac a LaunchAgent fast-forwards the main
+// checkouts of Mac-run repos (the containers' ~ is that folder), which could
+// change files under a running build. So pw-deploy writes this marker into the
+// git common dir — shared by the Mac's git and the containers', never part of
+// the work tree — and removes it when the deploy ends; the job skips a repo
+// whose marker is younger than 2 hours.
+import { readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+export const DEPLOY_MARKER_FILE = 'pw-deploy.lock';
+/** The git common dir of `repoRoot`, without running git; null outside a checkout. */
+export async function gitCommonDir(repoRoot) {
+    const dotGit = join(repoRoot, '.git');
+    let info;
+    try {
+        info = await stat(dotGit);
+    }
+    catch {
+        return null;
+    }
+    if (info.isDirectory())
+        return dotGit;
+    // A worktree: `.git` is a file "gitdir: <path>", and that dir names the common dir in `commondir`.
+    const pointer = (await readFile(dotGit, 'utf8')).match(/^gitdir:\s*(.+)\s*$/m)?.[1];
+    if (!pointer)
+        return null;
+    const gitDir = isAbsolute(pointer) ? pointer : resolve(repoRoot, pointer);
+    try {
+        const common = (await readFile(join(gitDir, 'commondir'), 'utf8')).trim();
+        return isAbsolute(common) ? common : resolve(gitDir, common);
+    }
+    catch {
+        return dirname(dirname(gitDir));
+    }
+}
+/** Write the marker; returns a remover (a no-op outside a git checkout). Never throws. */
+export async function writeDeployMarker(repoRoot, now = new Date()) {
+    const dir = await gitCommonDir(repoRoot).catch(() => null);
+    if (!dir)
+        return async () => { };
+    const path = join(dir, DEPLOY_MARKER_FILE);
+    const body = `${JSON.stringify({ pid: process.pid, host: hostname(), repo: repoRoot, startedAt: now.toISOString() })}\n`;
+    try {
+        await writeFile(path, body);
+    }
+    catch {
+        return async () => { };
+    }
+    return async () => {
+        // Remove only our own marker: a second deploy may have replaced it.
+        try {
+            if ((await readFile(path, 'utf8')) === body)
+                await rm(path, { force: true });
+        }
+        catch {
+            // already gone
+        }
+    };
+}

package/dist/deploy/deploy.js

@@ -13,6 +13,7 @@ import { must, mustJson } from './exec.js';
 import { openEvidence, PhaseTimer } from './evidence.js';
 import { acquireLock, clearHold, publishRetainedAssets, readHold, readReleaseRecord, releaseLock, verifyLock, writeReleaseRecord, } from './gcs.js';
 import { consistentBaseSha, readServingState, SHA40 } from './plan.js';
+import { writeDeployMarker } from './deploy-marker.js';
 const RELEASE_DEADLINE_MS = 25 * 60_000;
 const IMAGE_DIGEST = /@sha256:[0-9a-f]{64}$/;
 const MAX_DIRTY_PATHS = 20;
@@ -40,6 +41,8 @@ export async function runDeploy(options) {
     let trafficMoved = false;
     let evidenceDir = '';
     let lock = null;
+    // Tells the Mac's checkout-sync job not to fast-forward this checkout under the build (deploy-marker.ts).
+    const removeDeployMarker = await writeDeployMarker(options.repoRoot);
     try {
         // ---- preflight ----
         const config = await loadConfig(options.repoRoot);
@@ -440,5 +443,6 @@ export async function runDeploy(options) {
     finally {
         if (lock)
             await releaseLock(runner, lock);
+        await removeDeployMarker();
     }
 }

package/dist/extension-self-update.d.ts

@@ -0,0 +1,68 @@
+export declare const STABLE_MS: number;
+export declare const RETRY_MS: number;
+export declare const BUSY_LEASE_MS: number;
+export declare const CODE_MANIFEST_FILE = "mac-code.json";
+/** chrome.storage.session: { code, since } — the shipped code first seen verified on disk. */
+export declare const SEEN_KEY = "selfUpdateSeen";
+/** chrome.storage.local: { code, at } — the last reload this extension asked for. */
+export declare const ATTEMPT_KEY = "selfUpdateAttempt";
+/** chrome.storage.local: { code, version } — the code Chrome loaded (written when it loads). */
+export declare const LOADED_KEY = "selfUpdateLoaded";
+/** chrome.storage.session: epoch ms until which the extension is busy (an open overlay renews it). */
+export declare const BUSY_LEASE_KEY = "selfUpdateBusyUntil";
+interface Seen {
+    code: string;
+    since: number;
+}
+interface Attempt {
+    code: string;
+    at: number;
+}
+export declare function sha256Hex(data: ArrayBuffer | string): Promise<string>;
+/** The id over a file list; the same algorithm as baselib code-manifest's codeIdOf. */
+export declare function codeIdOf(files: Record<string, string>): Promise<string>;
+/**
+ * The code on disk now: the manifest's id when every listed file is present and
+ * matches and the id is the id of the list; null otherwise (a merge in
+ * progress, a local edit, no manifest). An extension URL reads the folder as
+ * it is now (measured 2026-10-31).
+ */
+export declare function diskCode(): Promise<string | null>;
+/**
+ * Record the code Chrome just loaded. Call from runtime.onInstalled and
+ * runtime.onStartup — the moments Chrome reads the extension from disk — and
+ * nowhere else: a worker restarting after eviction runs the code loaded
+ * earlier, whatever the disk holds now.
+ */
+export declare function recordLoadedCode(): Promise<string>;
+/** The code this extension runs: the record from its last load (re-taken when the record predates this manifest). */
+export declare function loadedCode(): Promise<string>;
+/** Mark the extension busy for BUSY_LEASE_MS (an open overlay calls this through the worker every ~10 s). */
+export declare function extendBusyLease(now?: number): Promise<void>;
+export declare function busyLeaseActive(now?: number): Promise<boolean>;
+/** Is one of the extension's own pages open in a tab (an options or approval page a reload would close)? */
+export declare function extensionPageOpen(): Promise<boolean>;
+export type UpdateAction = 'none' | 'wait' | 'reload';
+/** The pure decision. `seen` and `attempt` are the stored records (or undefined). */
+export declare function decideUpdate(input: {
+    loaded: string;
+    disk: string | null;
+    shipped: string | null | undefined;
+    seen: Seen | undefined;
+    attempt: Attempt | undefined;
+    now: number;
+}): {
+    action: UpdateAction;
+    seen: Seen | null;
+};
+/**
+ * Check and reload when the rules allow. `shipped`: the code the server last
+ * said it deployed (null when unknown). `busy`: the extension's own work in
+ * flight; the busy lease and open extension pages are checked here too.
+ */
+export declare function maybeSelfUpdate(options: {
+    busy: boolean;
+    shipped: string | null | undefined;
+    log?: (message: string) => void;
+}): Promise<UpdateAction | 'busy'>;
+export {};

package/dist/extension-self-update.js

@@ -0,0 +1,171 @@
+// Self-update for an unpacked Chrome extension that Steve's Mac loads from a
+// git checkout (plasticine-way mac/sync/DESIGN.md §3.4). Generalised from
+// Reader's extension/self-update.js (1.3.7, 2026-10-31).
+//
+// The Mac job keeps the checkout at origin/main; Chrome reads an unpacked
+// extension's code only when it loads it, so the worker must reload itself.
+// It does so only into code that (1) verifies file by file against the
+// committed `mac-code.json` on disk, (2) is the code the app's server says it
+// deployed (`shipped`, from the server's answer to the extension's report),
+// and (3) differs from the code this worker loaded. Then: only once that code
+// has been on disk STABLE_MS, never while busy, and at most once per code per
+// RETRY_MS so a reload that does not take cannot loop. chrome.runtime.reload()
+// reloads from the folder and keeps chrome.storage; Chrome honours it only
+// with Developer mode on, which Load unpacked needs anyway.
+//
+// Plain browser ESM with no imports: Lurch bundles it; Reader and Snip (no
+// build step) commit a byte-identical copy of the compiled file, checked by a
+// test in each repo.
+export const STABLE_MS = 60 * 1000;
+export const RETRY_MS = 6 * 60 * 60 * 1000;
+export const BUSY_LEASE_MS = 30 * 1000;
+export const CODE_MANIFEST_FILE = 'mac-code.json';
+/** chrome.storage.session: { code, since } — the shipped code first seen verified on disk. */
+export const SEEN_KEY = 'selfUpdateSeen';
+/** chrome.storage.local: { code, at } — the last reload this extension asked for. */
+export const ATTEMPT_KEY = 'selfUpdateAttempt';
+/** chrome.storage.local: { code, version } — the code Chrome loaded (written when it loads). */
+export const LOADED_KEY = 'selfUpdateLoaded';
+/** chrome.storage.session: epoch ms until which the extension is busy (an open overlay renews it). */
+export const BUSY_LEASE_KEY = 'selfUpdateBusyUntil';
+function hex(bytes) {
+    return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export async function sha256Hex(data) {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    return hex(await crypto.subtle.digest('SHA-256', bytes));
+}
+/** The id over a file list; the same algorithm as baselib code-manifest's codeIdOf. */
+export async function codeIdOf(files) {
+    const lines = Object.keys(files)
+        .sort()
+        .map((path) => `${path}\0${files[path]}\n`)
+        .join('');
+    return (await sha256Hex(lines)).slice(0, 16);
+}
+async function readFile(path) {
+    try {
+        const res = await fetch(chrome.runtime.getURL(path), { cache: 'no-store' });
+        if (!res.ok)
+            return null;
+        return await res.arrayBuffer();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The code on disk now: the manifest's id when every listed file is present and
+ * matches and the id is the id of the list; null otherwise (a merge in
+ * progress, a local edit, no manifest). An extension URL reads the folder as
+ * it is now (measured 2026-10-31).
+ */
+export async function diskCode() {
+    const raw = await readFile(CODE_MANIFEST_FILE);
+    if (!raw)
+        return null;
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder().decode(raw));
+    }
+    catch {
+        return null;
+    }
+    const { id, files } = manifest;
+    if (typeof id !== 'string' || !files || typeof files !== 'object')
+        return null;
+    const list = files;
+    for (const value of Object.values(list))
+        if (typeof value !== 'string')
+            return null;
+    if ((await codeIdOf(list)) !== id)
+        return null;
+    for (const [path, expected] of Object.entries(list)) {
+        const bytes = await readFile(path);
+        if (!bytes || (await sha256Hex(bytes)) !== expected)
+            return null;
+    }
+    return id;
+}
+/**
+ * Record the code Chrome just loaded. Call from runtime.onInstalled and
+ * runtime.onStartup — the moments Chrome reads the extension from disk — and
+ * nowhere else: a worker restarting after eviction runs the code loaded
+ * earlier, whatever the disk holds now.
+ */
+export async function recordLoadedCode() {
+    const code = (await diskCode()) ?? 'unverified';
+    const record = { code, version: chrome.runtime.getManifest().version };
+    await chrome.storage.local.set({ [LOADED_KEY]: record });
+    return code;
+}
+/** The code this extension runs: the record from its last load (re-taken when the record predates this manifest). */
+export async function loadedCode() {
+    const { [LOADED_KEY]: stored } = await chrome.storage.local.get(LOADED_KEY);
+    const record = stored;
+    if (record && typeof record.code === 'string' && record.version === chrome.runtime.getManifest().version)
+        return record.code;
+    return recordLoadedCode();
+}
+/** Mark the extension busy for BUSY_LEASE_MS (an open overlay calls this through the worker every ~10 s). */
+export async function extendBusyLease(now = Date.now()) {
+    await chrome.storage.session.set({ [BUSY_LEASE_KEY]: now + BUSY_LEASE_MS });
+}
+export async function busyLeaseActive(now = Date.now()) {
+    const { [BUSY_LEASE_KEY]: until } = await chrome.storage.session.get(BUSY_LEASE_KEY);
+    return typeof until === 'number' && until > now;
+}
+/** Is one of the extension's own pages open in a tab (an options or approval page a reload would close)? */
+export async function extensionPageOpen() {
+    if (!chrome.runtime.getContexts)
+        return false;
+    try {
+        return (await chrome.runtime.getContexts({ contextTypes: ['TAB'] })).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** The pure decision. `seen` and `attempt` are the stored records (or undefined). */
+export function decideUpdate(input) {
+    const { loaded, disk, shipped, seen, attempt, now } = input;
+    if (!shipped || !disk || disk !== shipped || disk === loaded)
+        return { action: 'none', seen: null };
+    const since = seen && seen.code === disk ? seen.since : now;
+    const record = { code: disk, since };
+    if (now - since < STABLE_MS)
+        return { action: 'wait', seen: record };
+    if (attempt && attempt.code === disk && now - attempt.at < RETRY_MS)
+        return { action: 'none', seen: record };
+    return { action: 'reload', seen: record };
+}
+/**
+ * Check and reload when the rules allow. `shipped`: the code the server last
+ * said it deployed (null when unknown). `busy`: the extension's own work in
+ * flight; the busy lease and open extension pages are checked here too.
+ */
+export async function maybeSelfUpdate(options) {
+    const loaded = await loadedCode();
+    const disk = await diskCode();
+    const { [SEEN_KEY]: seen } = await chrome.storage.session.get(SEEN_KEY);
+    const { [ATTEMPT_KEY]: attempt } = await chrome.storage.local.get(ATTEMPT_KEY);
+    const now = Date.now();
+    const decision = decideUpdate({ loaded, disk, shipped: options.shipped, seen: seen, attempt: attempt, now });
+    const prior = seen;
+    if (decision.seen) {
+        if (!prior || prior.code !== decision.seen.code)
+            await chrome.storage.session.set({ [SEEN_KEY]: decision.seen });
+    }
+    else if (prior) {
+        await chrome.storage.session.remove(SEEN_KEY);
+    }
+    if (decision.action !== 'reload' || !decision.seen)
+        return decision.action;
+    const target = decision.seen.code;
+    if (options.busy || (await busyLeaseActive(now)) || (await extensionPageOpen()))
+        return 'busy';
+    options.log?.(`code ${target} is deployed and on disk (running ${loaded}): reloading.`);
+    await chrome.storage.local.set({ [ATTEMPT_KEY]: { code: target, at: now } });
+    chrome.runtime.reload();
+    return 'reload';
+}

package/dist/hub/notify.d.ts

@@ -45,6 +45,10 @@ export declare class HubNotifyBatch {
     private readonly notifier;
     private readonly hints;
     constructor(notifier: HubNotifier);
+    /** Coalesced per (user, kind), as design §5.3 says, except `notification`,
+     *  whose payloads differ in meaning: only exact duplicates of those fold.
+     *  A folded `work` keeps the first hint's ref (refs are optional pickup
+     *  shortcuts; the daemon re-reads its queue either way). */
     add(hint: AppHint): void;
     /** Send every distinct hint (concurrently, each within the notifier's
      *  bound) and empty the batch. Never throws. */

package/dist/hub/notify.js

@@ -81,6 +81,8 @@ export class HubNotifier {
                 body: JSON.stringify({ ...hint, app: this.app }),
                 signal: AbortSignal.timeout(this.timeoutMs),
             });
+            // An unread body holds the connection until garbage collection.
+            await res.body?.cancel().catch(() => { });
             if (res.status === 202)
                 return null;
             // 400/401/403/413: the hint or the grant is wrong, not the network.
@@ -97,8 +99,12 @@ export class HubNotifyBatch {
     constructor(notifier) {
         this.notifier = notifier;
     }
+    /** Coalesced per (user, kind), as design §5.3 says, except `notification`,
+     *  whose payloads differ in meaning: only exact duplicates of those fold.
+     *  A folded `work` keeps the first hint's ref (refs are optional pickup
+     *  shortcuts; the daemon re-reads its queue either way). */
     add(hint) {
-        const key = JSON.stringify([hint.user, hint.kind, hint.ref ?? null, hint.payload ?? null]);
+        const key = hint.kind === 'notification' ? JSON.stringify([hint.user, hint.kind, hint.ref ?? null, hint.payload ?? null]) : JSON.stringify([hint.user, hint.kind]);
         if (!this.hints.has(key))
             this.hints.set(key, hint);
     }

package/dist/hub/server.d.ts

@@ -21,6 +21,15 @@ export declare const DAEMON_LOOKBACK_MAX_MS = 60000;
 /** 401s per client address per minute on the token path before further
  *  tokens from it are refused without a database lookup. */
 export declare const TOKEN_FAILURES_PER_MIN = 20;
+/** Cross-copy publishes in flight at once; past it a publish is dropped (a
+ *  lost hint is tolerated) so a slow database cannot queue publishes ahead
+ *  of the token lookups that share the pool. */
+export declare const HUB_PUBLISHES_IN_FLIGHT_MAX = 16;
+/** The largest frame a browser may send (its frames are `connect` and `ping`). */
+export declare const HUB_SOCKET_MAX_PAYLOAD = 4096;
+/** A socket that has sent nothing (clients ping every 30 s) for this long is
+ *  closed: a half-dead socket would otherwise hold a slot for an hour. */
+export declare const HUB_SOCKET_IDLE_MS = 180000;
 export interface HubOptions {
     pool: pg.Pool;
     logger: Logger;
@@ -40,6 +49,13 @@ export interface HubOptions {
      *  origins (local development and Playwright). */
     allowLocalOrigins?: boolean;
     upgradeWebSocket: UpgradeWebSocket;
+    /** The upgrader's `ws` server (`createNodeWebSocket(...).wss`): the hub
+     *  caps its incoming frame size (ws's default is 100 MiB). */
+    webSocketServer?: {
+        options: {
+            maxPayload?: number;
+        };
+    };
     /** Passed through to requireIdentity (authUrl, whoamiFetch, verifyClient,
      *  rateLimitPerMin…). The hub admits invited users for sockets. */
     identity?: Partial<Omit<RequireIdentityOptions, 'audience' | 'grants' | 'logger' | 'userAccess'>>;
@@ -47,6 +63,11 @@ export interface HubOptions {
     bridge?: Partial<Pick<DbBroadcastBridgeOptions, 'heartbeatMs' | 'heartbeatTimeoutMs' | 'reconnectDelaysMs'>>;
     /** Monotonic milliseconds (tests). */
     now?: () => number;
+    /** Tests: the idle-socket limit and sweep interval. */
+    socketIdle?: {
+        idleMs: number;
+        sweepMs: number;
+    };
 }
 export interface Hub {
     /** Start the cross-copy bridge. Call before the server accepts

package/dist/hub/server.js

@@ -58,7 +58,18 @@ export const DAEMON_LOOKBACK_MAX_MS = 60_000;
 /** 401s per client address per minute on the token path before further
  *  tokens from it are refused without a database lookup. */
 export const TOKEN_FAILURES_PER_MIN = 20;
+/** Cross-copy publishes in flight at once; past it a publish is dropped (a
+ *  lost hint is tolerated) so a slow database cannot queue publishes ahead
+ *  of the token lookups that share the pool. */
+export const HUB_PUBLISHES_IN_FLIGHT_MAX = 16;
+/** The largest frame a browser may send (its frames are `connect` and `ping`). */
+export const HUB_SOCKET_MAX_PAYLOAD = 4096;
+/** A socket that has sent nothing (clients ping every 30 s) for this long is
+ *  closed: a half-dead socket would otherwise hold a slot for an hour. */
+export const HUB_SOCKET_IDLE_MS = 180_000;
+const HUB_SOCKET_SWEEP_MS = 30_000;
 const TOKEN_FORMAT = /^hubt_[A-Za-z0-9_-]{43}$/;
+const WEBSOCKET_KEY = /^[+/0-9A-Za-z]{22}==$/;
 const TOKEN_HASH_FORMAT = /^[0-9a-f]{64}$/;
 const DAEMON_ID_FORMAT = /^[A-Za-z0-9_-]{8,64}$/;
 export function createHub(app, opts) {
@@ -74,6 +85,8 @@ export function createHub(app, opts) {
         userAccess: 'invited',
     });
     const serviceAccount = new RegExp(`^([a-z][a-z0-9-]*)-svc@${escapeRegExp(opts.serviceAccountDomain)}$`);
+    if (opts.webSocketServer)
+        opts.webSocketServer.options.maxPayload = HUB_SOCKET_MAX_PAYLOAD;
     // app → user → sockets
     const sockets = new Map();
     const waits = new Map();
@@ -82,6 +95,8 @@ export function createHub(app, opts) {
     // when the bridge last recovered: hints sent while it was deaf are unknowable
     let lastBlanketAt = -Infinity;
     const publishes = new Set();
+    let droppedPublishes = 0;
+    let lastDropWarnAt = -Infinity;
     const tokenFailures = new FailureCounter(TOKEN_FAILURES_PER_MIN);
     let stopping = false;
     const bridge = new DbBroadcastBridge({
@@ -141,6 +156,15 @@ export function createHub(app, opts) {
                 waiter.finish(workResponse());
     }
     function publish(hint) {
+        if (publishes.size >= HUB_PUBLISHES_IN_FLIGHT_MAX) {
+            droppedPublishes++;
+            if (now() - lastDropWarnAt >= 10_000) {
+                lastDropWarnAt = now();
+                logger.warn('hub publishes dropped', { dropped: droppedPublishes, inFlight: publishes.size });
+                droppedPublishes = 0;
+            }
+            return;
+        }
         const p = withinMs(bridge.notify({ hint }), HUB_PUBLISH_TIMEOUT_MS, 'hub publish')
             .catch((error) => {
             logger.warn('hub publish failed', { app: hint.app, kind: hint.kind, error: serializeError(error) });
@@ -184,6 +208,8 @@ export function createHub(app, opts) {
         return c.body(null, 202);
     });
     app.post('/api/register-daemon', identity, async (c) => {
+        if (stopping)
+            return c.json({ error: 'hub restarting' }, 503);
         const caller = callerApp(c);
         if (!caller)
             return c.json({ error: 'app service accounts only' }, 403);
@@ -228,6 +254,9 @@ export function createHub(app, opts) {
     /** Resolves the waiting app: from a daemon hub token, or (no token) from
      *  `?app=` for a granted service caller. Cookies are refused (review B1). */
     const daemonAuth = createMiddleware(async (c, next) => {
+        // The lookback and the wait both count from arrival, before the token
+        // lookup or identity check, whose time would otherwise open a gap.
+        c.set('hubArrivedAt', now());
         const token = c.req.header('x-hub-token');
         if (token === undefined) {
             const { admitted, response } = await runIdentity(c);
@@ -280,13 +309,16 @@ export function createHub(app, opts) {
         if (stopping)
             return c.body(null, 204);
         // A work hint between the daemon's direct request and this wait being
-        // parked would otherwise be lost to the 30 s timer (review S2).
-        const t = now();
+        // parked would otherwise be lost to the 30 s timer (review S2). The
+        // daemon's lookbackMs covers from its direct request's start to its
+        // arrival here; this copy has seen every hint since arrival.
+        const since = c.var.hubArrivedAt - lookbackMs;
         const last = lastWork.get(appName);
-        if (lookbackMs > 0 && last && t - last.at <= lookbackMs)
+        if (last && last.at >= since)
             return workResponse(last.ref);
-        if (lookbackMs > 0 && t - lastBlanketAt <= lookbackMs)
+        if (lastBlanketAt >= since)
             return workResponse();
+        const remainingMs = Math.max(0, waitSeconds * 1000 - (now() - c.var.hubArrivedAt));
         return new Promise((resolve) => {
             let set = waits.get(appName);
             if (!set)
@@ -306,7 +338,7 @@ export function createHub(app, opts) {
                 },
             };
             const onAbort = () => waiter.finish(new Response(null, { status: 204 }));
-            const timer = setTimeout(() => waiter.finish(new Response(null, { status: 204 })), waitSeconds * 1000);
+            const timer = setTimeout(() => waiter.finish(new Response(null, { status: 204 })), remainingMs);
             waiters.add(waiter);
             if (signal.aborted)
                 onAbort();
@@ -322,6 +354,15 @@ export function createHub(app, opts) {
         const appName = c.req.query('app');
         if (!isAppName(appName))
             return c.json({ error: 'app required' }, 400);
+        // Only a well-formed handshake may reach the upgrader: @hono/node-ws
+        // keeps the request of an upgrade that ws aborts (a bad key or version)
+        // for the life of the process.
+        const version = c.req.header('sec-websocket-version');
+        if ((c.req.header('upgrade') ?? '').toLowerCase() !== 'websocket' ||
+            !WEBSOCKET_KEY.test(c.req.header('sec-websocket-key') ?? '') ||
+            (version !== '13' && version !== '8')) {
+            return c.json({ error: 'websocket handshake required' }, 400);
+        }
         if (!originAllowed(c.req.header('origin'), appName, opts)) {
             logger.warn('hub socket origin refused', { app: appName, origin: c.req.header('origin') ?? null });
             return c.json({ error: 'origin not allowed' }, 403);
@@ -332,6 +373,12 @@ export function createHub(app, opts) {
         const { admitted, response } = await runIdentity(c);
         if (!admitted)
             refusals.set(c, response?.status ?? 401);
+        // The client may have gone while its identity was checked; the upgrader
+        // would then keep its request forever (as above). Nothing awaits between
+        // this check and the upgrade.
+        const incoming = c.env?.incoming;
+        if (incoming?.socket && !(incoming.socket.readable && incoming.socket.writable))
+            return c.body(null, 400); // no one reads it
         await next();
     });
     app.get('/api/ws', originCheck, socketIdentity, opts.upgradeWebSocket((c) => {
@@ -367,7 +414,7 @@ export function createHub(app, opts) {
                         ws.close(4403, 'user identity required');
                     return;
                 }
-                socket = { ws, app: appName, user };
+                socket = { ws, app: appName, user, lastHeardAt: now() };
                 let users = sockets.get(appName);
                 if (!users)
                     sockets.set(appName, (users = new Map()));
@@ -379,6 +426,7 @@ export function createHub(app, opts) {
             onMessage: (evt, ws) => {
                 if (!socket)
                     return;
+                socket.lastHeardAt = now();
                 let message;
                 try {
                     message = JSON.parse(String(evt.data));
@@ -397,10 +445,34 @@ export function createHub(app, opts) {
             onError: remove,
         };
     }));
+    const idle = opts.socketIdle ?? { idleMs: HUB_SOCKET_IDLE_MS, sweepMs: HUB_SOCKET_SWEEP_MS };
+    let sweeper;
+    function sweepIdleSockets() {
+        const t = now();
+        for (const users of sockets.values()) {
+            for (const set of users.values()) {
+                for (const socket of set) {
+                    if (t - socket.lastHeardAt < idle.idleMs)
+                        continue;
+                    try {
+                        socket.ws.close(4408, 'idle');
+                    }
+                    catch {
+                        // already closing
+                    }
+                }
+            }
+        }
+    }
     return {
-        start: () => bridge.start(),
+        async start() {
+            sweeper = setInterval(sweepIdleSockets, idle.sweepMs);
+            sweeper.unref?.();
+            await bridge.start();
+        },
         async stop() {
             stopping = true;
+            clearInterval(sweeper);
             for (const users of sockets.values()) {
                 for (const set of users.values()) {
                     for (const socket of set) {
@@ -417,7 +489,9 @@ export function createHub(app, opts) {
             for (const set of waits.values())
                 for (const waiter of [...set])
                     waiter.finish(new Response(null, { status: 204 }));
-            await Promise.allSettled([...publishes]);
+            // A notify racing shutdown may add a publish while these settle.
+            while (publishes.size > 0)
+                await Promise.allSettled([...publishes]);
             await bridge.stop();
         },
         stats() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.47.0",
+  "version": "3.48.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -88,6 +88,18 @@
     "./connector": {
       "types": "./dist/connector.d.ts",
       "default": "./dist/connector.js"
+    },
+    "./code-manifest": {
+      "types": "./dist/code-manifest.d.ts",
+      "default": "./dist/code-manifest.js"
+    },
+    "./client-version": {
+      "types": "./dist/client-version.d.ts",
+      "default": "./dist/client-version.js"
+    },
+    "./extension-self-update": {
+      "types": "./dist/extension-self-update.d.ts",
+      "default": "./dist/extension-self-update.js"
     }
   },
   "bin": {
@@ -95,7 +107,8 @@
     "pw-deploy": "./dist/bin/pw-deploy.js",
     "pw-logs": "./dist/bin/pw-logs.js",
     "pw-rollback": "./dist/bin/pw-rollback.js",
-    "pw-sql": "./dist/bin/pw-sql.js"
+    "pw-sql": "./dist/bin/pw-sql.js",
+    "pw-code-manifest": "./dist/bin/pw-code-manifest.js"
   },
   "engines": {
     "node": "22.x"