sideby 0.12.0 → 0.13.0

package/dist/src/core/leveldb-keys.js

@@ -0,0 +1,291 @@
+// Reads the key names of a Chrome Local Storage LevelDB directory, read-only (spec §3.24, ADR-0023). Only keys are
+// kept: a value's bytes are stepped over and never turned into text, compared or returned. A table block is Snappy
+// compressed as a whole, keys and values together, so it is decompressed into a buffer that is dropped after its keys
+// are taken. Nothing is written, locked or copied; a record cut short (Chrome writing while we read) is skipped.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Files larger than this are skipped and reported. */
+export const MAX_LEVELDB_FILE = 64 * 1024 * 1024;
+class Cut extends Error {
+}
+function varint(buf, pos) {
+    let result = 0;
+    let shift = 0;
+    for (let i = pos; i < buf.length && shift <= 35; i++) {
+        const b = buf[i];
+        result += (b & 0x7f) * 2 ** shift;
+        if (b < 0x80)
+            return [result, i + 1];
+        shift += 7;
+    }
+    throw new Cut();
+}
+/** Snappy raw-format decompression (https://github.com/google/snappy/blob/main/format_description.txt). */
+export function snappyDecompress(src) {
+    const [len, start] = varint(src, 0);
+    if (len > MAX_LEVELDB_FILE)
+        throw new Cut();
+    const out = new Uint8Array(len);
+    let o = 0;
+    let i = start;
+    while (i < src.length) {
+        const tag = src[i++];
+        const kind = tag & 3;
+        if (kind === 0) {
+            let n = tag >> 2;
+            if (n >= 60) {
+                const extra = n - 59;
+                n = 0;
+                for (let k = 0; k < extra; k++)
+                    n += (src[i + k] ?? 0) * 256 ** k;
+                i += extra;
+            }
+            n += 1;
+            if (i + n > src.length || o + n > len)
+                throw new Cut();
+            out.set(src.subarray(i, i + n), o);
+            i += n;
+            o += n;
+            continue;
+        }
+        let n;
+        let off;
+        if (kind === 1) {
+            n = ((tag >> 2) & 7) + 4;
+            off = ((tag >> 5) << 8) | (src[i++] ?? 0);
+        }
+        else if (kind === 2) {
+            n = (tag >> 2) + 1;
+            off = (src[i] ?? 0) | ((src[i + 1] ?? 0) << 8);
+            i += 2;
+        }
+        else {
+            n = (tag >> 2) + 1;
+            off =
+                ((src[i] ?? 0) | ((src[i + 1] ?? 0) << 8) | ((src[i + 2] ?? 0) << 16)) + (src[i + 3] ?? 0) * 2 ** 24;
+            i += 4;
+        }
+        if (off === 0 || off > o || o + n > len)
+            throw new Cut();
+        for (let k = 0; k < n; k++, o++)
+            out[o] = out[o - off];
+    }
+    if (o !== len)
+        throw new Cut();
+    return out;
+}
+/** A `.log` file: 32 KiB blocks of records that together form WriteBatches. */
+function readLog(buf, sink) {
+    const BLOCK = 32768;
+    const parts = [];
+    let pos = 0;
+    while (pos + 7 <= buf.length) {
+        const left = BLOCK - (pos % BLOCK);
+        if (left < 7) {
+            pos += left;
+            continue;
+        }
+        const len = buf[pos + 4] | (buf[pos + 5] << 8);
+        const type = buf[pos + 6];
+        const data = buf.subarray(pos + 7, pos + 7 + len);
+        pos += 7 + len;
+        if (type === 0 || data.length < len)
+            break;
+        if (type === 1)
+            batch(data, sink);
+        else if (type === 2)
+            parts.splice(0, parts.length, data);
+        else if (type === 3)
+            parts.push(data);
+        else if (type === 4 && parts.length) {
+            parts.push(data);
+            batch(concat(parts), sink);
+            parts.length = 0;
+        }
+    }
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function batch(b, sink) {
+    if (b.length < 12)
+        return;
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    let seq = view.getUint32(0, true) + view.getUint32(4, true) * 2 ** 32;
+    const count = view.getUint32(8, true);
+    let pos = 12;
+    try {
+        for (let n = 0; n < count && pos < b.length; n++, seq++) {
+            const tag = b[pos++];
+            const [kl, p1] = varint(b, pos);
+            const key = b.subarray(p1, p1 + kl);
+            pos = p1 + kl;
+            if (pos > b.length)
+                throw new Cut();
+            if (tag === 1) {
+                const [vl, p2] = varint(b, pos);
+                pos = p2 + vl; // the value is stepped over
+                sink(key, seq, true);
+            }
+            else if (tag === 0)
+                sink(key, seq, false);
+            else
+                break;
+        }
+    }
+    catch (e) {
+        if (!(e instanceof Cut))
+            throw e;
+    }
+}
+/** One block of a table: prefix-compressed entries, then the restart array. Calls `each` with key and value range. */
+function blockEntries(block, each) {
+    if (block.length < 4)
+        return;
+    const view = new DataView(block.buffer, block.byteOffset, block.byteLength);
+    const restarts = view.getUint32(block.length - 4, true);
+    const end = block.length - 4 - restarts * 4;
+    if (end < 0)
+        return;
+    let pos = 0;
+    let last = new Uint8Array(0);
+    while (pos < end) {
+        const [shared, p1] = varint(block, pos);
+        const [unshared, p2] = varint(block, p1);
+        const [vlen, p3] = varint(block, p2);
+        if (shared > last.length || p3 + unshared + vlen > end)
+            throw new Cut();
+        const key = new Uint8Array(shared + unshared);
+        key.set(last.subarray(0, shared), 0);
+        key.set(block.subarray(p3, p3 + unshared), shared);
+        each(key, p3 + unshared, p3 + unshared + vlen);
+        last = key;
+        pos = p3 + unshared + vlen;
+    }
+}
+function readBlock(file, offset, size) {
+    if (offset + size + 5 > file.length)
+        throw new Cut();
+    const raw = file.subarray(offset, offset + size);
+    const type = file[offset + size];
+    if (type === 0)
+        return raw;
+    if (type === 1)
+        return snappyDecompress(raw);
+    throw new Cut();
+}
+/** A `.ldb` (or `.sst`) table: footer → index block → data blocks. Only internal keys are taken from data blocks. */
+function readTable(buf, sink) {
+    if (buf.length < 48)
+        return;
+    const footer = buf.subarray(buf.length - 48);
+    const magic = new DataView(footer.buffer, footer.byteOffset + 40, 8);
+    if (magic.getUint32(0, true) !== 0x8b80fb57 || magic.getUint32(4, true) !== 0xdb477524)
+        return;
+    let [, p] = varint(footer, 0) // metaindex offset
+    ;
+    [, p] = varint(footer, p); // metaindex size
+    const [indexOff, p2] = varint(footer, p);
+    const [indexSize] = varint(footer, p2);
+    const index = readBlock(buf, indexOff, indexSize);
+    blockEntries(index, (_key, vs, ve) => {
+        const handle = index.subarray(vs, ve);
+        const [off, q] = varint(handle, 0);
+        const [size] = varint(handle, q);
+        let block;
+        try {
+            block = readBlock(buf, off, size);
+        }
+        catch (e) {
+            if (e instanceof Cut)
+                return;
+            throw e;
+        }
+        blockEntries(block, (ikey) => {
+            if (ikey.length < 8)
+                return;
+            const t = new DataView(ikey.buffer, ikey.byteOffset + ikey.length - 8, 8);
+            const tag = t.getUint32(0, true) + t.getUint32(4, true) * 2 ** 32;
+            sink(ikey.subarray(0, ikey.length - 8), Math.floor(tag / 256), tag % 256 === 1);
+        });
+    });
+}
+const latin1 = new TextDecoder('latin1');
+const utf16 = new TextDecoder('utf-16le');
+/**
+ * The Local Storage key names of `origins` (`https://claude.ai`), from a `Local Storage/leveldb` directory. A key
+ * deleted later is left out. `changedAt` is the newest modification time of the files read. Files that are too large
+ * or unreadable go to `problems` (their name only).
+ */
+export async function localStorageKeys(dir, origins) {
+    const problems = [];
+    const keys = new Map(origins.map((o) => [o, new Set()]));
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { keys, problems };
+    }
+    const prefixes = origins.map((o) => Buffer.from(`_${o}\u0000`, 'latin1'));
+    const states = new Map();
+    const sink = (key, seq, live) => {
+        const i = prefixes.findIndex((p) => key.length > p.length && Buffer.from(key.subarray(0, p.length)).equals(p));
+        if (i < 0)
+            return;
+        const prefix = prefixes[i];
+        const enc = key[prefix.length];
+        const body = key.subarray(prefix.length + 1);
+        const name = enc === 1 ? latin1.decode(body) : enc === 0 ? utf16.decode(body) : undefined;
+        if (name === undefined)
+            return;
+        const id = `${i}\u0000${name}`;
+        const prev = states.get(id);
+        if (!prev || seq >= prev.seq)
+            states.set(id, { origin: origins[i], name, seq, live });
+    };
+    let changedAt;
+    for (const name of names.sort()) {
+        const table = name.endsWith('.ldb') || name.endsWith('.sst');
+        if (!table && !name.endsWith('.log'))
+            continue;
+        const file = join(dir, name);
+        try {
+            const st = await stat(file);
+            if (!st.isFile())
+                continue;
+            if (st.size > MAX_LEVELDB_FILE) {
+                problems.push(`${name} is larger than 64 MB and was skipped`);
+                continue;
+            }
+            changedAt = Math.max(changedAt ?? 0, st.mtimeMs);
+            const buf = new Uint8Array(await readFile(file));
+            try {
+                if (table)
+                    readTable(buf, sink);
+                else
+                    readLog(buf, sink);
+            }
+            catch (e) {
+                if (!(e instanceof Cut))
+                    throw e;
+                problems.push(`${name} could not be read completely`);
+            }
+        }
+        catch (e) {
+            if (e instanceof Cut)
+                continue;
+            problems.push(`${name} could not be read`);
+        }
+    }
+    for (const s of states.values())
+        if (s.live)
+            keys.get(s.origin)?.add(s.name);
+    return { keys, ...(changedAt === undefined ? {} : { changedAt }), problems };
+}

package/dist/src/core/remote-control.d.ts

@@ -13,13 +13,15 @@ export interface RemoteControlGroup {
     state: RemoteControlState;
     /** For `blocked` and `missing`: why, and what to do. */
     reason?: string;
-    /** sideby turned it off here and can put the earlier value back. */
+    /** sideby set it here and can put the earlier value back. */
     undo: boolean;
 }
 export interface RemoteControlUndoRecord {
     file: string;
-    /** The value before sideby wrote `false`, or null when the key was not there. */
+    /** The value before sideby wrote, or null when the key was not there. */
     previous: boolean | null;
+    /** The value sideby wrote; records from before `on` existed lack it and mean `false`. */
+    wrote?: boolean;
     at: string;
 }
 export interface RemoteControlChange {
@@ -37,9 +39,18 @@ export interface RemoteControlChange {
 export declare function remoteControlGroups(accounts: readonly Account[], ctx: ReadContext): Promise<RemoteControlGroup[]>;
 /** The groups `off` would change: those that are on, or follow a default that may be on. */
 export declare function groupsToTurnOff(groups: readonly RemoteControlGroup[]): RemoteControlGroup[];
-/** Sets `remoteControlAtStartup` to false in every group that is on or follows the default, remembering each old value. */
-export declare function turnRemoteControlOff(accounts: readonly Account[], ctx: ReadContext): Promise<RemoteControlChange>;
-/** Groups sideby can put back: it wrote `false` there and the key still holds it. */
+/** The groups `on` would change: those that are off, or follow a default that may be off. */
+export declare function groupsToTurnOn(groups: readonly RemoteControlGroup[]): RemoteControlGroup[];
+/**
+ * Sets `remoteControlAtStartup` to `to` in every group that does not hold it yet (a default counts as either),
+ * remembering each old value for undo.
+ */
+export declare function setRemoteControl(accounts: readonly Account[], ctx: ReadContext, to: boolean): Promise<RemoteControlChange>;
+/** Sets `remoteControlAtStartup` to false in every group that is on or follows the default. */
+export declare const turnRemoteControlOff: (accounts: readonly Account[], ctx: ReadContext) => Promise<RemoteControlChange>;
+/** Sets `remoteControlAtStartup` to true in every group that is off or follows the default. */
+export declare const turnRemoteControlOn: (accounts: readonly Account[], ctx: ReadContext) => Promise<RemoteControlChange>;
+/** Groups sideby can put back: it wrote there and the key still holds what it wrote. */
 export declare function groupsToUndo(groups: readonly RemoteControlGroup[]): RemoteControlGroup[];
-/** Puts back what each file had before `off`, only while the key is still `false`. */
+/** Puts back what each file had before `on` or `off`, only while the key still holds what sideby wrote. */
 export declare function undoRemoteControlOff(accounts: readonly Account[], ctx: ReadContext): Promise<RemoteControlChange>;

package/dist/src/core/remote-control.js

@@ -1,4 +1,4 @@
-// Remote Control off by default (spec §3.22, ADR-0017): reads and writes one key, `remoteControlAtStartup`, of each
+// Remote Control at startup (spec §3.22, ADR-0017): reads and writes one key, `remoteControlAtStartup`, of each
 // Claude Account's `settings.json`. Accounts that share a file (a link to the Main Account's) form one group and one
 // write. Nothing but that key is ever read out of the file into an output, an error or the undo record; writes go
 // through `writeIfUnchanged`, keep every other key, and never create, replace or retarget a link.
@@ -60,7 +60,8 @@ export async function remoteControlGroups(accounts, ctx) {
             }
             else {
                 group.state = stateOf(read.obj[RC_KEY]);
-                group.undo = group.state === 'off' && (await readRecord(ctx, where.file)) !== null;
+                const record = await readRecord(ctx, where.file);
+                group.undo = record !== null && read.obj[RC_KEY] === (record.wrote ?? false);
             }
         }
     }
@@ -70,6 +71,10 @@ export async function remoteControlGroups(accounts, ctx) {
 export function groupsToTurnOff(groups) {
     return groups.filter((g) => g.state === 'on' || g.state === 'default');
 }
+/** The groups `on` would change: those that are off, or follow a default that may be off. */
+export function groupsToTurnOn(groups) {
+    return groups.filter((g) => g.state === 'off' || g.state === 'default');
+}
 async function writeKey(file, change, expect) {
     const read = await readObject(file);
     if ('error' in read)
@@ -81,18 +86,23 @@ async function writeKey(file, change, expect) {
     const wrote = await writeIfUnchanged(file, sha256(read.text), render(change({ ...read.obj }), read.text), mode);
     return wrote ? null : 'settings.json changed while sideby was writing, so nothing was changed. Try again.';
 }
-/** Sets `remoteControlAtStartup` to false in every group that is on or follows the default, remembering each old value. */
-export async function turnRemoteControlOff(accounts, ctx) {
+/**
+ * Sets `remoteControlAtStartup` to `to` in every group that does not hold it yet (a default counts as either),
+ * remembering each old value for undo.
+ */
+export async function setRemoteControl(accounts, ctx, to) {
     const groups = await remoteControlGroups(accounts, ctx);
-    const todo = groupsToTurnOff(groups);
+    const todo = to ? groupsToTurnOn(groups) : groupsToTurnOff(groups);
     if (todo.length === 0) {
-        const stuck = groups.find((g) => g.state === 'blocked');
+        const stuck = groups.find((g) => g.state === 'blocked' || (to && g.state === 'missing'));
         return stuck
             ? { ok: false, results: [], message: `Nothing was changed: ${stuck.reason}` }
             : {
                 ok: true,
                 results: [],
-                message: 'Remote Control already does not start by itself; nothing changed.',
+                message: to
+                    ? 'Remote Control already starts by itself; nothing changed.'
+                    : 'Remote Control already does not start by itself; nothing changed.',
             };
     }
     const results = [];
@@ -100,32 +110,43 @@ export async function turnRemoteControlOff(accounts, ctx) {
         let previous = null;
         const failed = await writeKey(g.file, (obj) => {
             previous = typeof obj[RC_KEY] === 'boolean' ? obj[RC_KEY] : null;
-            obj[RC_KEY] = false;
+            obj[RC_KEY] = to;
             return obj;
-        }, (obj) => (obj[RC_KEY] === false ? 'It was turned off meanwhile; nothing changed.' : null));
+        }, (obj) => (obj[RC_KEY] === to ? `It was turned ${to ? 'on' : 'off'} meanwhile; nothing changed.` : null));
         if (failed) {
             results.push({ file: g.file, accounts: g.accounts, ok: false, message: failed });
             continue;
         }
-        const record = { file: g.file, previous, at: new Date().toISOString() };
+        const record = {
+            file: g.file,
+            previous,
+            wrote: to,
+            at: new Date().toISOString(),
+        };
         await mkdir(join(ctx.stateDir, 'remote-control'), { recursive: true });
         await writeFileAtomic(recordPath(ctx, g.file), `${JSON.stringify(record, null, 2)}\n`, 0o600);
-        results.push({ file: g.file, accounts: g.accounts, ok: true, message: 'Turned off.' });
+        results.push({ file: g.file, accounts: g.accounts, ok: true, message: to ? 'Turned on.' : 'Turned off.' });
     }
     const ok = results.every((r) => r.ok);
     return {
         ok,
         results,
-        message: ok
-            ? 'Done. New sessions no longer connect to claude.ai by themselves; restart sessions that are already running. You can still start it in a session with /remote-control.'
-            : 'Some files could not be changed; see each line.',
+        message: !ok
+            ? 'Some files could not be changed; see each line.'
+            : to
+                ? 'Done. New sessions connect to claude.ai and the Claude app by themselves, where every device signed in to that account can read them; restart sessions that are already running.'
+                : 'Done. New sessions no longer connect to claude.ai by themselves; restart sessions that are already running. You can still start it in a session with /remote-control.',
     };
 }
-/** Groups sideby can put back: it wrote `false` there and the key still holds it. */
+/** Sets `remoteControlAtStartup` to false in every group that is on or follows the default. */
+export const turnRemoteControlOff = (accounts, ctx) => setRemoteControl(accounts, ctx, false);
+/** Sets `remoteControlAtStartup` to true in every group that is off or follows the default. */
+export const turnRemoteControlOn = (accounts, ctx) => setRemoteControl(accounts, ctx, true);
+/** Groups sideby can put back: it wrote there and the key still holds what it wrote. */
 export function groupsToUndo(groups) {
     return groups.filter((g) => g.undo);
 }
-/** Puts back what each file had before `off`, only while the key is still `false`. */
+/** Puts back what each file had before `on` or `off`, only while the key still holds what sideby wrote. */
 export async function undoRemoteControlOff(accounts, ctx) {
     const todo = groupsToUndo(await remoteControlGroups(accounts, ctx));
     if (todo.length === 0)
@@ -141,7 +162,9 @@ export async function undoRemoteControlOff(accounts, ctx) {
             else
                 obj[RC_KEY] = record.previous;
             return obj;
-        }, (obj) => obj[RC_KEY] === false ? null : 'The setting was changed after sideby set it, so it was left alone.');
+        }, (obj) => obj[RC_KEY] === (record.wrote ?? false)
+            ? null
+            : 'The setting was changed after sideby set it, so it was left alone.');
         if (!failed)
             await rm(recordPath(ctx, g.file), { force: true });
         results.push({ file: g.file, accounts: g.accounts, ok: !failed, message: failed ?? 'Put back.' });

package/dist/src/core/update.d.ts

@@ -33,7 +33,7 @@ export interface UpdateCache {
         shown?: boolean;
     };
 }
-export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source';
+export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source' | 'local';
 export interface InstallMethod {
     kind: InstallKind;
     /** The installed package folder (real path). */
@@ -63,6 +63,10 @@ export interface UpdateDeps {
     }>;
     /** Starts `sideby ui --background --no-open --port <port>` from the newly installed code, detached; false when it could not start. */
     restartPanel: (env: Env, port: number) => Promise<boolean>;
+    /** Whether `sideby app install` put a desktop app in this home (its files carry the app marker). */
+    appInstalled: (home: string, env: Env) => Promise<boolean>;
+    /** Runs `sideby app install --json` from the newly installed code and waits; false when it failed. */
+    refreshApp: (env: Env) => Promise<boolean>;
 }
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
 export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
@@ -84,7 +88,7 @@ type UpdateSettings = {
     };
 };
 /** Why Update Checks are off, or null when they are on (spec §3.23). */
-export declare function checksOff(env: Env, config: UpdateSettings): string | null;
+export declare function checksOff(env: Env, config: UpdateSettings, local?: boolean): string | null;
 export declare function readUpdateCache(paths: Paths): Promise<UpdateCache>;
 /**
  * Merges a change into the cache file. The file is read again first, and `change` may be a function of what is there
@@ -181,11 +185,14 @@ export interface UpdateResult {
     message: string;
     /** A background Panel was running and is starting again from the new code. */
     restartedPanel: boolean;
+    /** The desktop app was installed and `sideby app install` ran again from the new code. */
+    refreshedApp: boolean;
     /** Another Update held the lock; nothing ran. */
     busy?: boolean;
 }
 /**
- * Runs the Update the plan names, then starts a running background Panel again from the new code. The caller has
+ * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
+ * desktop app is installed, runs `sideby app install` again from the new code. The caller has
  * shown the plan and got a confirmation (or this is an Auto Update). One Update runs at a time on this machine (the
  * CLI, a Panel and an Auto Update share the lock). `panelPort` gives the port of the background Panel to restart, or
  * null when none runs. A successful Update is recorded as said, so no notice for it follows.

package/dist/src/core/update.js

@@ -6,7 +6,7 @@ import { access, constants, mkdir, open, readdir, readFile, realpath, rm, stat }
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileAtomic } from './fs-safe.js';
-import { packageVersion } from './version.js';
+import { localBuild, packageVersion, parseLocalBuild } from './version.js';
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -76,6 +76,20 @@ const realDeps = {
         });
         child.once('error', () => resolve(false));
     }),
+    appInstalled: async (home, env) => {
+        const { appInstalled } = await import('../desktop/app.js');
+        return appInstalled({ home, env, platform: process.platform });
+    },
+    refreshApp: (env) => new Promise((resolve) => {
+        // By name, like restartPanel: the new code records its own Node and entry and draws the current mark.
+        const child = spawn('sideby', ['app', 'install', '--json'], {
+            env: env,
+            stdio: 'ignore',
+            timeout: 120_000,
+        });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    }),
 };
 let override = {};
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
@@ -137,7 +151,10 @@ const set = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !
 /** True in CI, where a notice is noise and a check is a request nobody reads. */
 export const inCi = (env) => set(env.CI) || set(env.CONTINUOUS_INTEGRATION) || set(env.BUILD_NUMBER);
 /** Why Update Checks are off, or null when they are on (spec §3.23). */
-export function checksOff(env, config) {
+export function checksOff(env, config, local = localBuild() !== null) {
+    // A Local Build (ADR-0024) follows the checkout: a notice or an Auto Update would only replace it with npm's.
+    if (local)
+        return 'this is a local build (pnpm local)';
     if (set(env.SIDEBY_NO_UPDATE_NOTIFIER))
         return 'SIDEBY_NO_UPDATE_NOTIFIER is set';
     if (set(env.NO_UPDATE_NOTIFIER))
@@ -373,6 +390,15 @@ export async function installMethod(env) {
         canUpdate: false,
         ...extra,
     });
+    try {
+        if (parseLocalBuild(JSON.parse(await readFile(join(packageDir, 'dist', 'build.json'), 'utf8'))))
+            return at('local', {
+                reason: 'it is a local build; run `pnpm local --off` in the sideby checkout to go back to npm',
+            });
+    }
+    catch {
+        // no build file: not a Local Build
+    }
     if (p.includes('/_npx/'))
         return at('npx', { reason: 'it runs from the npx cache, which fetches a version per call' });
     // Volta keeps a global package under its own npm prefix; installing there behind its back breaks its records.
@@ -436,6 +462,8 @@ export function updateCommand(method, version, env = {}) {
             return { text: `npm install ${spec}` };
         case 'source':
             return { text: 'git pull && pnpm install' };
+        case 'local':
+            return { text: 'pnpm local --off' };
     }
 }
 // ---- running sessions
@@ -514,7 +542,8 @@ export async function planUpdate(paths, env) {
     return planFrom(await installMethod(env), packageVersion(), latest, env);
 }
 /**
- * Runs the Update the plan names, then starts a running background Panel again from the new code. The caller has
+ * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
+ * desktop app is installed, runs `sideby app install` again from the new code. The caller has
  * shown the plan and got a confirmation (or this is an Auto Update). One Update runs at a time on this machine (the
  * CLI, a Panel and an Auto Update share the lock). `panelPort` gives the port of the background Panel to restart, or
  * null when none runs. A successful Update is recorded as said, so no notice for it follows.
@@ -526,6 +555,7 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
         output: '',
         message,
         restartedPanel: false,
+        refreshedApp: false,
         ...extra,
     });
     if (!cmd.run)
@@ -548,12 +578,17 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
         }).catch(() => { });
         const port = opts.panelPort ? await opts.panelPort().catch(() => null) : null;
         const restarted = port !== null && (await d.restartPanel(env, port).catch(() => false));
+        // The desktop app records the Node and entry it starts and carries the icon of the version that wrote it, so
+        // the new code writes it again. Only where one is installed; a failure here never fails the Update.
+        const installed = await d.appInstalled(paths.home, env).catch(() => false);
+        const refreshed = installed && (await d.refreshApp(env).catch(() => false));
         return {
             ok: true,
             code: 0,
             output: r.output,
             message: `updated sideby from ${plan.current} to ${plan.latest}`,
             restartedPanel: restarted,
+            refreshedApp: refreshed,
         };
     }
     finally {

package/dist/src/core/version.d.ts

@@ -7,3 +7,14 @@ export declare function packageVersion(): string;
  * id for tests.
  */
 export declare function buildId(env?: NodeJS.ProcessEnv): string;
+/** What `pnpm local` records about a Local Build (ADR-0024). */
+export interface LocalBuild {
+    commit: string;
+    /** The working tree had changes that were not committed. */
+    dirty: boolean;
+    builtAt: string;
+}
+/** The Local Build fields of a `dist/build.json`, or null for a published build or anything unexpected. */
+export declare function parseLocalBuild(data: unknown): LocalBuild | null;
+/** The running code's Local Build, or null when it was published or runs from source. */
+export declare function localBuild(): LocalBuild | null;

package/dist/src/core/version.js

@@ -44,3 +44,29 @@ export function buildId(env = process.env) {
     cachedBuild = `${packageVersion()}+${id}`;
     return cachedBuild;
 }
+/** The Local Build fields of a `dist/build.json`, or null for a published build or anything unexpected. */
+export function parseLocalBuild(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const d = data;
+    if (d.local !== true)
+        return null;
+    return {
+        commit: typeof d.commit === 'string' ? d.commit : '',
+        dirty: d.dirty === true,
+        builtAt: typeof d.builtAt === 'string' ? d.builtAt : '',
+    };
+}
+let cachedLocal;
+/** The running code's Local Build, or null when it was published or runs from source. */
+export function localBuild() {
+    if (cachedLocal !== undefined)
+        return cachedLocal;
+    try {
+        cachedLocal = parseLocalBuild(JSON.parse(readFileSync(new URL('../../build.json', import.meta.url), 'utf8')));
+    }
+    catch {
+        cachedLocal = null;
+    }
+    return cachedLocal;
+}

package/dist/src/desktop/app.d.ts

@@ -56,5 +56,7 @@ export interface LauncherSpec {
 export declare function launcherScript(s: LauncherSpec): string;
 export declare function infoPlist(version: string): string;
 export declare function desktopEntry(launcher: string): string;
+/** Whether a sideby desktop app is installed for this home: its main file exists and carries APP_MARKER. */
+export declare function appInstalled(ctx: AppContext): Promise<boolean>;
 export declare function installApp(ctx: AppContext, opts: InstallOptions): Promise<InstallResult>;
 export declare function uninstallApp(ctx: AppContext): Promise<UninstallResult>;