@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/server/lib/updates/shell-release.ts

@@ -1,3 +1,8 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 /**
  * Which published native-shell artifact a browser or an installed shell should
  * download, and whether the installed one is behind.
@@ -19,11 +24,12 @@
  *
  * - `url` is what to download. For the mobile pair it is the artifact itself (an
  *   APK the shell installs, an IPA the release page explains). For the DESKTOP
- *   trio it is the RELEASE PAGE, deliberately: every desktop artifact is
- *   per-architecture (`Kabmo-0.2.0-mac-arm64.zip`), and this server cannot know
- *   which architecture the window asking is running on — it may be a remote
- *   console on another machine entirely. Naming one arch's file would hand half
- *   the readers a build that will not launch.
+ *   trio it is the artifact when the caller reported its ARCHITECTURE, and the
+ *   release page otherwise: every desktop artifact is per-architecture, and a
+ *   console served to another machine cannot guess. Naming the wrong arch's file
+ *   would hand half the readers a build that will not launch.
+ * - `direct` says which of the two `url` is, so the client knows whether the
+ *   offer can be installed from inside the shell.
  * - `latest` is the version that asset ships, read from the asset NAME (see
  *   `shell-assets`). The release TAG cannot be used: the artifact is attached to
  *   the app's release, whose tag names the SERVER version.
@@ -34,10 +40,25 @@
  */
 
 import { REPO } from '@/server/lib/updates/release-url';
-import { SHELL_ASSETS, versionFromAssetName } from '@/server/lib/updates/shell-assets';
+import {
+  cacheSlot,
+  CACHE_MS,
+  githubApiBase,
+  gitHubHeaders,
+  shellCacheKey,
+} from '@/server/lib/updates/shell-cache';
+import { SHELL_ASSETS, selfUpdateArtifact, versionFromAssetName } from '@/server/lib/updates/shell-assets';
 import { findAssetInPages } from '@/server/lib/updates/shell-pages';
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
 import type { ShellKind } from '@/shared/lib/updates/shell-ua';
 
+/**
+ * The test seam for the process-wide answer cache, re-exported here because this
+ * module is what owns the answers. The cache itself lives next door (`shell-cache`)
+ * so its key — shell AND architecture — is stated in one place.
+ */
+export { resetShellReleaseCache } from '@/server/lib/updates/shell-cache';
+
 /** One published shell artifact, as the console needs it. */
 export interface ShellRelease {
   /** Asset download URL, or the release page for a per-arch desktop build. */
@@ -46,8 +67,21 @@ export interface ShellRelease {
   latest: string | null;
   /** The release page, for a "what changed" link. */
   releaseUrl: string | null;
+  /**
+   * True when `url` names the artifact itself rather than the release page.
+   *
+   * This is what tells the console whether the offer can be INSTALLED from
+   * inside the shell. It is true for the mobile pair (one file for every
+   * device) and for a desktop shell that reported its architecture — and false
+   * for a desktop probe without one, which still gets the page that lists every
+   * architecture.
+   */
+  direct: boolean;
 }
 
+/** The answer a probe gives when it found nothing: a valid result, not an error. */
+const EMPTY_RELEASE: ShellRelease = { url: null, latest: null, releaseUrl: null, direct: false };
+
 /**
  * The newest release that actually carries this shell's artifact.
  *
@@ -57,25 +91,32 @@ export interface ShellRelease {
  * `release.yml`), so their `kabmo-sdk/v*` / `kabmo-ui/v*` releases are newer
  * than the app release that carries the shells. `@semantic-release/github` runs
  * in both pipelines, so those are real releases — measured against a stub that
- * answered a package release: `/releases/latest` produced
- * `{url: null, latest: null}` and the sidebar's button disappeared even though
- * the APK sat on the release directly below.
+ * answered a package release: `/releases/latest` produced `{url: null, …}` and
+ * the sidebar's button disappeared even though the APK sat on the release
+ * directly below.
+ *
+ * `arch` is what a DESKTOP shell reports about its own machine, and it is the
+ * difference between "here is the page, pick your build" and "here is your
+ * installer". It is the THIRD parameter so every existing caller — including
+ * every test, which passes `fetchImpl` — keeps its shape.
  *
- * Cached for five minutes on `globalThis` for the same reason the database
- * handle is anchored there: `bun --hot` re-evaluates this module while the cache
- * it would otherwise hold lives on.
+ * Cached for five minutes on `globalThis` (see `shell-cache`) for the same
+ * reason the database handle is anchored there: `bun --hot` re-evaluates this
+ * module while the cache it would otherwise hold lives on.
  */
 export async function fetchShellRelease(
   kind: ShellKind,
   fetchImpl: typeof fetch = fetch,
+  arch: ShellArch | null = null,
 ): Promise<ShellRelease | null> {
-  const cache = cacheSlot(kind);
+  const cache = cacheSlot<ShellRelease>(shellCacheKey(kind, arch));
   const now = Date.now();
   if (cache.entry && now - cache.at < CACHE_MS) return cache.entry;
 
   const headers = gitHubHeaders();
   const resolved =
-    (await readFromApi(kind, fetchImpl, headers)) ?? (await readFromPages(kind, fetchImpl, headers));
+    (await readFromApi(kind, arch, fetchImpl, headers)) ??
+    (await readFromPages(kind, arch, fetchImpl, headers));
   if (!resolved) return cache.entry ?? null;
 
   cache.entry = resolved;
@@ -94,6 +135,7 @@ const RELEASE_SCAN = 20;
  */
 async function readFromApi(
   kind: ShellKind,
+  arch: ShellArch | null,
   fetchImpl: typeof fetch,
   headers: Record<string, string>,
 ): Promise<ShellRelease | null> {
@@ -105,8 +147,8 @@ async function readFromApi(
 
     const body = (await response.json()) as unknown;
     // A body that is not the release list is a failed probe, not an empty
-    // repository: answering `{url: null, latest: null}` here would be
-    // indistinguishable from "no release carries an artifact".
+    // repository: answering `{url: null, …}` here would be indistinguishable
+    // from "no release carries an artifact".
     if (!Array.isArray(body)) return null;
 
     // Drafts are not published and prereleases are not what a console offers an
@@ -117,12 +159,12 @@ async function readFromApi(
     );
 
     const release = published
-      .map((entry) => ({ entry, asset: shellAsset(kind, entry.assets) }))
+      .map((entry) => ({ entry, asset: shellAsset(kind, arch, entry.assets) }))
       .find((candidate) => candidate.asset !== null);
 
-    if (!release?.asset) return { url: null, latest: null, releaseUrl: null };
+    if (!release?.asset) return EMPTY_RELEASE;
 
-    return resolvedRelease(kind, {
+    return resolvedRelease(kind, arch, {
       name: String(release.asset.name),
       downloadUrl:
         typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
@@ -136,14 +178,15 @@ async function readFromApi(
 /** The public-pages read, wrapped so a failure is the caller's `null`. */
 async function readFromPages(
   kind: ShellKind,
+  arch: ShellArch | null,
   fetchImpl: typeof fetch,
   headers: Record<string, string>,
 ): Promise<ShellRelease | null> {
   try {
-    const found = await findAssetInPages(kind, fetchImpl, headers);
+    const found = await findAssetInPages(kind, fetchImpl, headers, arch);
     if (found.kind === 'unreachable') return null;
-    if (found.kind === 'none') return { url: null, latest: null, releaseUrl: null };
-    return resolvedRelease(kind, { ...found.asset, releaseUrl: found.releaseUrl });
+    if (found.kind === 'none') return EMPTY_RELEASE;
+    return resolvedRelease(kind, arch, { ...found.asset, releaseUrl: found.releaseUrl });
   } catch {
     return null;
   }
@@ -152,16 +195,26 @@ async function readFromPages(
 /**
  * The asset of a release that names this shell's artifact, or null.
  *
- * The CURRENT scheme wins over the legacy one, and that is not cosmetic. A
- * release that carries both — which happens the moment a rename lands and
- * `--clobber` has not yet replaced the old asset, or a hand-upload adds one
- * beside the other — would otherwise resolve to whichever the asset list
- * happened to order first. Measured: a release holding both
- * `kabmo-android-v0.4.0.apk` and `Kabmo-0.6.0-android.apk` answered `0.4.0`,
- * i.e. the console offered an update to a version it already had and hid the
- * newer one.
+ * Two questions, in this order:
+ *
+ * 1. **Does an architecture match?** When the caller named one, the only
+ *    acceptable asset is the file that machine installs (`selfUpdateArtifact`).
+ *    Everything else in the release — the other architecture, the `.dmg`, a
+ *    `.deb` — is skipped, and the next release is tried.
+ * 2. **Which spelling?** The CURRENT scheme wins over the legacy one, and that
+ *    is not cosmetic. A release that carries both — which happens the moment a
+ *    rename lands and `--clobber` has not yet replaced the old asset, or a
+ *    hand-upload adds one beside the other — would otherwise resolve to
+ *    whichever the asset list happened to order first. Measured: a release
+ *    holding both `kabmo-android-v0.4.0.apk` and `Kabmo-0.6.0-android.apk`
+ *    answered `0.4.0`, i.e. the console offered an update to a version it
+ *    already had and hid the newer one.
  */
-function shellAsset(kind: ShellKind, assets: unknown): Record<string, unknown> | null {
+function shellAsset(
+  kind: ShellKind,
+  arch: ShellArch | null,
+  assets: unknown,
+): Record<string, unknown> | null {
   if (!Array.isArray(assets)) return null;
 
   const named = assets.filter(
@@ -172,95 +225,38 @@ function shellAsset(kind: ShellKind, assets: unknown): Record<string, unknown> |
       versionFromAssetName(kind, String((entry as Record<string, unknown>).name)) !== null,
   );
 
+  if (arch) {
+    const exact = named.find(
+      (asset) => selfUpdateArtifact(kind, arch, String(asset.name)) !== null,
+    );
+    if (exact) return exact;
+  }
+
   return named.find((asset) => SHELL_ASSETS[kind].current.test(String(asset.name))) ?? named[0] ?? null;
 }
 
-/** Turn one resolved asset into the payload, applying the per-kind link rule. */
+/**
+ * Turn one resolved asset into the payload.
+ *
+ * `direct` is derived from the SAME decision that chose the asset: an arch was
+ * named and the asset is that arch's self-update file. Deriving it separately —
+ * from `directDownload`, or from the platform — is how the client ends up
+ * offering an install for a release page.
+ */
 function resolvedRelease(
   kind: ShellKind,
+  arch: ShellArch | null,
   asset: { name: string; downloadUrl: string | null; releaseUrl: string | null },
 ): ShellRelease {
+  const installable = arch !== null && selfUpdateArtifact(kind, arch, asset.name) !== null;
+  const direct = SHELL_ASSETS[kind].directDownload || installable;
+
   return {
-    // A per-arch desktop build cannot be named from here — see the module
-    // comment — so the link is the page that lists every architecture.
-    url: SHELL_ASSETS[kind].directDownload ? asset.downloadUrl : asset.releaseUrl,
+    // A per-arch desktop build cannot be named without an architecture — see
+    // the module comment — so the link is the page that lists every one.
+    url: direct ? asset.downloadUrl : asset.releaseUrl,
     latest: versionFromAssetName(kind, asset.name),
     releaseUrl: asset.releaseUrl,
+    direct: direct && asset.downloadUrl !== null,
   };
 }
-
-const CACHE_MS = 5 * 60_000;
-
-/**
- * Where the release read goes.
- *
- * Overridable for the same reason the npm probe honours `NPM_CONFIG_REGISTRY`: a
- * test and a rehearsal need to exercise the real parsing against a stub instead
- * of a live GitHub call, and hardcoding the host makes that impossible without
- * intercepting `fetch` globally.
- */
-function githubApiBase(): string {
-  const configured = Bun.env.KABMO_GITHUB_API ?? '';
-  return configured.trim().replace(/\/+$/, '') || 'https://api.github.com';
-}
-
-/**
- * A token, when the operator has one, which lifts the API quota from 60 an hour
- * to 5000 — the difference between the precise read working on a shared address
- * and falling through to the pages every time.
- *
- * Read from the environment rather than a setting: it is a deployment fact, it
- * must never reach the browser, and `kabmo serve` already passes its own
- * environment through.
- */
-function gitHubHeaders(): Record<string, string> {
-  const token = (Bun.env.KABMO_GITHUB_TOKEN ?? Bun.env.GITHUB_TOKEN ?? '').trim();
-  const headers: Record<string, string> = {
-    // GitHub rejects a request with no User-Agent.
-    'user-agent': 'kabmo-console',
-  };
-  if (token) headers.authorization = `Bearer ${token}`;
-  return headers;
-}
-
-interface CacheSlot {
-  entry: ShellRelease | null;
-  at: number;
-}
-
-type ShellCacheHost = typeof globalThis & {
-  __kabmoShellRelease?: Partial<Record<ShellKind, CacheSlot>>;
-};
-
-/**
- * The cache slot for one shell.
- *
- * PER SHELL, not one shared slot: both probes read the same release list but
- * resolve different assets, so one slot would make the second shell answer with
- * the first one's artifact.
- */
-function cacheSlot(kind: ShellKind): CacheSlot {
-  const host = globalThis as ShellCacheHost;
-  host.__kabmoShellRelease ??= {};
-  host.__kabmoShellRelease[kind] ??= { entry: null, at: 0 };
-  return host.__kabmoShellRelease[kind] as CacheSlot;
-}
-
-/**
- * Drop the cached answer for one shell (or every shell, with no argument).
- *
- * The cache lives on `globalThis` so `bun --hot` cannot orphan it, which also
- * means it outlives a test file: without this seam the second case in a suite
- * reads the first case's answer and passes for the wrong reason (measured — the
- * "malformed body" case returned the previous test's release). Production has
- * no caller; it exists because the cache is process-wide by design.
- */
-export function resetShellReleaseCache(kind?: ShellKind): void {
-  const host = globalThis as ShellCacheHost;
-  if (!kind) {
-    host.__kabmoShellRelease = {};
-    return;
-  }
-  host.__kabmoShellRelease ??= {};
-  host.__kabmoShellRelease[kind] = { entry: null, at: 0 };
-}

package/src/server/routes/fs/git-merge.test.ts

@@ -19,7 +19,7 @@
  *    answers "no <op> in progress" and only `reset --merge HEAD` clears it.
  */
 
-import { afterAll, describe, expect, test } from 'bun:test';
+import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test';
 import fs from 'node:fs';
 import path from 'node:path';
 import { action } from '@/server/routes/fs/git';
@@ -36,6 +36,16 @@ import { removeDir } from '@/test-support/remove-dir';
  * action ran against THE Kabmo REPOSITORY.
  */
 const FIXTURE_ROOT = path.join(process.cwd(), 'tmp-test-git-merge');
+
+/**
+ * Every case here builds a real repository and drives several `git` processes
+ * through it, so Bun's 5s per-test default is a budget for the RUNNER rather
+ * than for the code. Measured on a loaded CI runner: the cherry-pick case alone
+ * spent 5.0s and timed out, while the same commit passed the `Checks` job and
+ * failed the `Release` one minutes later — the same suite, two machines, one
+ * answer each. `git-actions-sync.test.ts` sets the same 30s for the same reason.
+ */
+setDefaultTimeout(30_000);
 const repos: string[] = [];
 
 function git(cwd: string, ...args: string[]): string {

package/src/server/routes/fs/read.test.ts

@@ -21,6 +21,7 @@ import fs from 'fs';
 import path from 'path';
 import { readFile } from '@/server/routes/fs/read';
 import { EDITOR_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+import { formatBytes } from '@/shared/lib/format/number';
 
 const DIR = path.join(process.cwd(), 'tmp-read-gate');
 
@@ -88,16 +89,23 @@ describe('fs read gate', () => {
 
     expect(status).toBe(415);
     expect(body.kind).toBe('too-large');
-    expect(body.error).toContain('5.00 MB');
+    // Derived from the constant, not spelled out: the sentence and the gate must
+    // name the same number, and a literal here would pass while they drifted.
+    expect(body.error).toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
   });
 
   // A PDF is streamed to Chrome's own viewer through `/api/fs/raw`, so the text
-  // ceiling does not apply to it — the route must still point at the raw route
-  // for a PDF well past 5 MB rather than refusing it. Refusing it was the bug:
-  // the size test ran before the document branch, so a 6 MB PDF was answered
-  // "larger than the 5.00 MB the editor opens".
-  test('a PDF past the text ceiling is still served by the raw route', async () => {
-    write('report.pdf', new Uint8Array(EDITOR_MAX_FILE_BYTES + 1).fill(0x25));
+  // ceiling has no bearing on it — the route must point at the raw route rather
+  // than refuse it. Refusing it was the bug: the size test ran before the
+  // document branch, so a 6 MB PDF was answered "larger than the 5.00 MB the
+  // editor opens". 6 MB is the size that was over the old text ceiling and is
+  // still a perfectly ordinary PDF.
+  //
+  // It is written at 6 MB rather than at `EDITOR_MAX_FILE_BYTES + 1` because the
+  // two ceilings are independent: the text one is now ABOVE the PDF one, so
+  // "past text, under PDF" is no longer a size that exists.
+  test('a PDF past the old text ceiling is still served by the raw route', async () => {
+    write('report.pdf', new Uint8Array(6 * 1024 * 1024).fill(0x25));
     const { status, body } = await read('report.pdf');
 
     expect(status).toBe(400);
@@ -105,6 +113,15 @@ describe('fs read gate', () => {
     expect(body.kind).toBeUndefined();
   });
 
+  test('a PDF past its own ceiling is refused before the document branch', async () => {
+    write('enormous.pdf', new Uint8Array(PDF_MAX_FILE_BYTES + 1).fill(0x25));
+    const { status, body } = await read('enormous.pdf');
+
+    expect(status).toBe(415);
+    expect(body.kind).toBe('too-large');
+    expect(body.error).toContain(formatBytes(PDF_MAX_FILE_BYTES));
+  });
+
   test('a PDF past the PDF ceiling is refused for size, naming 30 MB', async () => {
     write('huge.pdf', new Uint8Array(PDF_MAX_FILE_BYTES + 1).fill(0x25));
     const { status, body } = await read('huge.pdf');

package/src/server/routes/fs/scope.test.ts

@@ -20,7 +20,8 @@ import fs from 'fs';
 import path from 'path';
 import { testPosix } from '@/test-support/platform';
 import { resolveFileScope } from '@/server/routes/fs/scope';
-import { DOCUMENT_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+import { DOCUMENT_MAX_FILE_BYTES, EDITOR_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+import { formatBytes } from '@/shared/lib/format/number';
 
 const APP = process.cwd();
 const DIR = path.join(APP, 'tmp-scope-probe');
@@ -158,14 +159,18 @@ describe('fs scope route', () => {
     expect(body.error).toContain('20.00 MB');
   });
 
-  // Plain text keeps the text ceiling: a textarea holds that buffer for the
-  // life of the tab, which is why its limit did not move with the documents'.
-  test('a text file past the text ceiling is still refused', async () => {
-    const target = write('big.log', new Uint8Array(6 * 1024 * 1024).fill(0x61));
-    const { status, body } = await scope(target);
-
-    expect(status).toBe(200);
-    expect(body.kind).toBe('too-large');
-    expect(body.error).toContain('5.00 MB');
+  // Plain text keeps the text ceiling, which is its own number: the buffer is
+  // held for the life of the tab and re-posted on every save, where a document
+  // is converted once. 6 MB used to be over it; it is a normal generated file
+  // and must open.
+  test('a text file over the text ceiling is refused, and one under it is not', async () => {
+    const ok = await scope(write('big.log', new Uint8Array(6 * 1024 * 1024).fill(0x61)));
+    expect(ok.status).toBe(200);
+    expect(ok.body.kind).toBe('text');
+
+    const over = await scope(write('huge.log', new Uint8Array(EDITOR_MAX_FILE_BYTES + 1).fill(0x61)));
+    expect(over.status).toBe(200);
+    expect(over.body.kind).toBe('too-large');
+    expect(over.body.error).toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
   });
 });

package/src/server/routes/fs/scope.ts

@@ -26,25 +26,14 @@
 import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
 import { resolveScopeForAbsolutePath } from '@/server/lib/fs/root';
 import { BINARY_SNIFF_BYTES, classifyEditorFile, unsupportedEditorMessage } from '@/shared/lib/fs/file-kind';
+import { pathFromFileUrl } from '@/shared/lib/fs/file-url';
 import fs from 'fs';
 import path from 'path';
 
-/**
- * A `file://` URL to the path it names.
- *
- * The pathname is percent-encoded (a space is `%20`, and a Finder drop of
- * `My Notes.md` is exactly that), so decoding is not optional. `decodeURIComponent`
- * can throw on a malformed escape, which is answered as "not a path" rather
- * than surfacing as a 500.
- */
+/** A `file://` URL to the path it names; see `pathFromFileUrl` for the rules. */
 function pathFromReference(reference: string): string | null {
   if (!/^file:\/\//i.test(reference)) return reference;
-  try {
-    const url = new URL(reference);
-    return decodeURIComponent(url.pathname);
-  } catch {
-    return null;
-  }
+  return pathFromFileUrl(reference);
 }
 
 export async function resolveFileScope({ request }: LoaderFunctionArgs) {

package/src/server/routes/updates/android.ts

@@ -12,11 +12,16 @@ import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell
  *
  * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
  * is to omit a button it cannot back with a link.
+ *
+ * PUBLIC, unlike its siblings: the Android shell asks this from native code
+ * (`AppUpdateCheck`), which has no session cookie, and its "Check for update"
+ * button is for a shell too stale to load the console. See `PUBLIC_EXACT` in
+ * `lib/auth/guard.ts`.
  */
 export async function loader() {
   const release: ShellRelease | null = await fetchShellRelease('android');
   return json(
-    release ?? { url: null, latest: null, releaseUrl: null },
+    release ?? { url: null, latest: null, releaseUrl: null, direct: false },
     { headers: NO_STORE_HEADERS },
   );
 }

package/src/server/routes/updates/desktop.ts

@@ -1,9 +1,10 @@
 import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
 import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell-release';
 import { isDesktopShellKind, type DesktopShellKind } from '@/shared/lib/updates/shell-ua';
+import { parseShellArch, type ShellArch } from '@/shared/lib/updates/shell-arch';
 
 /**
- * GET /api/updates/desktop?kind=macos|windows|linux — the newest desktop shell.
+ * GET /api/updates/desktop?kind=macos|windows|linux[&arch=arm64|x64]
  *
  * ONE route with an explicit `kind`, unlike the mobile pair's two routes, and
  * the difference is deliberate. `?kind` here is REQUIRED and refused when it is
@@ -11,17 +12,29 @@ import { isDesktopShellKind, type DesktopShellKind } from '@/shared/lib/updates/
  * the mobile pair's split exists precisely because a defaulted parameter would
  * have made "the newest shell" mean Android without anyone saying so.
  *
+ * ## `arch` is what makes the offer installable
+ *
  * Only an INSTALLED desktop shell asks for this — the page reports its own
  * version over the shell bridge (`__kabmoDesktop.shellVersion`), because a
- * desktop app carries no User-Agent token. The `url` it answers with is the
- * RELEASE PAGE rather than a file: every desktop artifact is per-architecture,
- * and the server cannot know which architecture the window is running on.
+ * desktop app carries no User-Agent token. Without `arch` the answer is the
+ * RELEASE PAGE: every desktop artifact is per-architecture, and a console served
+ * to another machine cannot guess which one this window runs on.
+ *
+ * WITH `arch` the answer is that machine's own installer, and `direct: true`
+ * says so — which is what lets the sidebar offer an in-app update instead of a
+ * link. The shell still verifies the bytes before installing them; this route
+ * only decides WHICH file, never whether it is trusted.
+ *
+ * An `arch` that names nothing this product publishes is a REFUSAL rather than a
+ * silent fallback: a caller that asked for a build we do not make should be told,
+ * not handed the other architecture's installer.
  *
  * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
  * is to omit a button it cannot back with a link.
  */
 export async function loader({ request }: { request: Request }) {
-  const kind = new URL(request.url).searchParams.get('kind');
+  const params = new URL(request.url).searchParams;
+  const kind = params.get('kind');
   if (!isDesktopShellKind(kind ?? '')) {
     return json(
       { error: 'kind must be one of macos, windows, linux' },
@@ -29,9 +42,18 @@ export async function loader({ request }: { request: Request }) {
     );
   }
 
-  const release: ShellRelease | null = await fetchShellRelease(kind as DesktopShellKind);
+  const requested = params.get('arch');
+  const arch: ShellArch | null = requested ? parseShellArch(requested) : null;
+  if (requested && !arch) {
+    return json(
+      { error: 'arch must be one of arm64, x64' },
+      { status: 400, headers: NO_STORE_HEADERS },
+    );
+  }
+
+  const release: ShellRelease | null = await fetchShellRelease(kind as DesktopShellKind, fetch, arch);
   return json(
-    release ?? { url: null, latest: null, releaseUrl: null },
+    release ?? { url: null, latest: null, releaseUrl: null, direct: false },
     { headers: NO_STORE_HEADERS },
   );
 }

package/src/server/routes/updates/ios.ts

@@ -16,11 +16,15 @@ import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell
  *
  * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
  * is to omit a button it cannot back with a link.
+ *
+ * PUBLIC, for the same reason as `/api/updates/android`: the installed shell
+ * asks it from native code with no session cookie, and the check has to work
+ * before the console can load.
  */
 export async function loader() {
   const release: ShellRelease | null = await fetchShellRelease('ios');
   return json(
-    release ?? { url: null, latest: null, releaseUrl: null },
+    release ?? { url: null, latest: null, releaseUrl: null, direct: false },
     { headers: NO_STORE_HEADERS },
   );
 }

package/src/server/routes/worktrees/list.ts

@@ -26,7 +26,7 @@ import { scanSessionInfoCached } from '@/server/lib/omp/session/files';
 import { canonicalPath } from '@/server/lib/fs/canonical';
 import { worktreeIdentityFor, listWorktreeRows } from '@/server/lib/db/worktree-registry.server';
 import { dirtyCount, commitsAheadOf } from '@/server/lib/fs/worktree/remove';
-import { listWorktrees } from '@/server/lib/fs/worktree/list';
+import { listWorktrees, isWorkTree } from '@/server/lib/fs/worktree/list';
 import {
   defaultWorktreeRoot,
   resolveConfiguredWorktreeRoot,
@@ -49,6 +49,16 @@ export async function loader({ request }: LoaderFunctionArgs) {
   try {
     const db = await getDb();
     const primaryRoot = await resolveProjectRoot(root);
+    // "This folder is not a Git repository" is an ANSWER, not a failure. The
+    // payload has carried `isRepo` for exactly this, and a plain directory (a
+    // notes folder bound as a workspace) must read as "no worktrees here" —
+    // a 500 would make the composer report a broken feature for a folder that
+    // simply has nothing to offer. The probe runs before the identity read,
+    // which is what throws for a directory with no root commit.
+    if (!(await isWorkTree(primaryRoot))) {
+      const empty: WorktreeListPayload = { worktrees: [], base: '', isRepo: false };
+      return json(empty);
+    }
     const settings = await readWorktreeSettings();
     const projectId = await resolveProjectId(primaryRoot, (candidate) => worktreeIdentityFor(db, candidate));
     const base = resolveConfiguredWorktreeRoot(settings.directory, primaryRoot)

package/src/server/routes/worktrees/routes.test.ts

@@ -163,6 +163,23 @@ describe('GET /api/worktrees', () => {
     expect(primary.dirty).toBe(0);
   });
 
+  test('a folder that is not a repository answers isRepo:false, not a failure', async () => {
+    // A notes folder bound as a workspace: it can never hold a worktree, and
+    // the composer must read that as "no control here" rather than as a broken
+    // feature. The route used to 500 here, because the identity read throws for
+    // a directory with no root commit.
+    const plain = join(workRoot, 'plain-notes');
+    mkdirSync(plain, { recursive: true });
+    writeFileSync(join(plain, 'todo.md'), '- buy milk\n');
+    const db = await getDb();
+    await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['plain', plain]);
+
+    const { status, body } = await call(listLoader, `http://localhost/api/worktrees?root=${encodeURIComponent(plain)}`);
+    expect(status).toBe(200);
+    expect(body.isRepo).toBe(false);
+    expect(worktreesOf(body)).toEqual([]);
+  });
+
   test('counts a session running in a worktree that lives OUTSIDE the repository', async () => {
     const created = await call(createAction, base(), {
       method: 'POST',