@1agh/maude 0.30.0 → 0.31.0

package/apps/studio/paths.ts

@@ -82,6 +82,18 @@ function isDevServerDir(dir: string): boolean {
 }
 
 function resolveDevServerRoot(): string {
+  // (0) Explicit override. Used when the runtime can't be found by walk-up — e.g.
+  // the Tauri desktop bundle (DDR-106) ships apps/studio/ as an app resource and
+  // sets MAUDE_DEV_SERVER_ROOT to it, because the sidecar binary sits alone in
+  // Maude.app/Contents/MacOS/ with no apps/studio/ up-tree (the bundle ships the
+  // full source, so `http.ts` is present at the resource root).
+  const override = process.env.MAUDE_DEV_SERVER_ROOT;
+  // Require the same `http.ts` anchor walk-up uses (not merely a `dist/` dir) so a
+  // planted dist-only directory can't hijack the runtime root (security review F4).
+  if (override && !isVirtualBunfsPath(override) && isDevServerDir(override)) {
+    return override;
+  }
+
   // (1) Dev mode: import.meta.url is a real file:// path AND lands in the
   // dev-server dir. Common case for `bun run server.ts`, tests, etc.
   const importDir = getImportMetaDir();

package/apps/studio/scaffold-design.ts

@@ -0,0 +1,57 @@
+// scaffold-design.ts — write a minimal, BOOTABLE `.design/` into a folder (Phase 28).
+//
+// Used by two native-app flows: "New project" (create a GitHub repo → init a local
+// project) and the "open a repo with no Maude design system" fallback ("set it up?").
+// It deliberately scaffolds only the MINIMUM the dev-server needs to boot (per
+// context.ts the only hard requirement is a `.design/` dir; config needs just
+// `name` + `designRoot`). A real design system is still created by /design:setup-ds
+// (agent-driven) — this just gets the project to open instead of crash-looping.
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const CONFIG_SCHEMA =
+  'https://raw.githubusercontent.com/1aGh/maude/main/apps/studio/config.schema.json';
+
+/** Whether `dir` is already a Maude project (has `.design/config.json`). */
+export function hasDesign(dir: string): boolean {
+  return existsSync(join(dir, '.design', 'config.json'));
+}
+
+export interface ScaffoldResult {
+  ok: boolean;
+  error?: string;
+}
+
+/** Scaffold a minimal bootable `.design/` (no design system yet). Refuses to
+ *  clobber an existing project. `name` is the human project label. */
+export function scaffoldDesign(dir: string, name?: string): ScaffoldResult {
+  const designDir = join(dir, '.design');
+  const configPath = join(designDir, 'config.json');
+  if (existsSync(configPath)) {
+    return { ok: false, error: 'This folder is already a Maude project.' };
+  }
+  const projectName = (name && name.trim()) || basename(dir) || 'Untitled';
+  try {
+    mkdirSync(join(designDir, 'ui'), { recursive: true });
+    mkdirSync(join(designDir, 'system'), { recursive: true });
+    const config = {
+      $schema: CONFIG_SCHEMA,
+      name: projectName,
+      designRoot: '.design',
+      canvasGroups: [
+        { label: 'Design system', path: 'system' },
+        { label: 'UI kit', path: 'ui' },
+      ],
+      designSystems: [],
+      completenessProfile: 'standard',
+    };
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    // Keep the empty group dirs in git so a fresh clone still has the structure.
+    writeFileSync(join(designDir, 'ui', '.gitkeep'), '', 'utf8');
+    writeFileSync(join(designDir, 'system', '.gitkeep'), '', 'utf8');
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : 'Could not set up the project.' };
+  }
+}

package/apps/studio/server.ts

@@ -16,14 +16,17 @@
 
 import { spawn } from 'node:child_process';
 
+import { createAcp } from './acp/index.ts';
 import { createActivity } from './activity.ts';
 import { createApi } from './api.ts';
 import { bootSelfHeal } from './boot-self-heal.ts';
-import { createAiActivity } from './collab/ai-activity.ts';
+import { createCanvasListWatch } from './canvas-list-watch.ts';
+import { type AiActivityEntry, createAiActivity } from './collab/ai-activity.ts';
 import { createGitLifecycle } from './collab/git-lifecycle.ts';
 import { createCollab } from './collab/index.ts';
 import { createContext } from './context.ts';
 import { createFsWatch } from './fs-watch.ts';
+import { createGitWatch } from './git/watch.ts';
 import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
@@ -77,11 +80,28 @@ await inspect.load();
 
 collab = createCollab(ctx, api);
 const aiActivity = createAiActivity(ctx);
+
+// Phase 30 — bridge agent `ai-activity` onto the per-canvas room awareness so a
+// remote peer sees "X is editing" cross-machine. The `ai-activity` bus event is
+// loopback-only (inspector WS); awareness is the one channel that crosses the
+// hub. Soft heads-up — projected onto the room's own awareness slot, cleared
+// when the activity ends/expires. No-op when no room is live for the slug.
+ctx.bus.on('ai-activity', (payload: { file: string; entry: AiActivityEntry | null }) => {
+  if (!collab) return;
+  const slug = api.fileSlug(payload.file);
+  collab.registry.setAgentEditing(
+    slug,
+    payload.entry ? { name: payload.entry.author, since: payload.entry.startedAt } : null
+  );
+});
 const gitLifecycle = createGitLifecycle(ctx, collab.registry);
 // Phase 13 / DDR-029 — fs-watch-driven canvas activity overlay. Subscribes to
 // `fs:any` and emits `activity:change`; ws.ts forwards it to canvas iframes.
 const activity = createActivity(ctx);
-const ws = createWs(ctx, api, inspect, collab, activity);
+// Phase 31 (DDR-123) — ACP chat bridge manager. Owns one claude-agent-acp
+// subprocess per /_ws/acp socket; main-origin + loopback only (wired below).
+const acp = createAcp(ctx);
+const ws = createWs(ctx, api, inspect, collab, activity, acp);
 const http = createHttp(ctx, api, inspect, aiActivity);
 const fsWatch = createFsWatch(ctx);
 
@@ -141,6 +161,26 @@ function startServer(port: number): BunServer {
         return new Response('Upgrade failed', { status: 400 });
       }
 
+      // Phase 31 (DDR-123) — ACP chat bridge WS. Main origin ONLY (this server,
+      // never startCanvasServer) and loopback-guarded like collab: the bridge
+      // spawns the user's `claude` and can drive file edits, so the untrusted
+      // canvas origin and remote hosts must never reach it. Checked BEFORE the
+      // generic `/_ws` inspector branch since `/_ws/acp`.startsWith('/_ws').
+      if (pathname === '/_ws/acp') {
+        if (!isLoopbackHost(req.headers.get('host'))) {
+          return new Response('ACP chat is loopback-only', { status: 403 });
+        }
+        const ok = srv.upgrade(req, {
+          data: {
+            id: crypto.randomUUID(),
+            remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+            kind: 'acp',
+          },
+        });
+        if (ok) return undefined as unknown as Response;
+        return new Response('Upgrade failed', { status: 400 });
+      }
+
       // Legacy inspector WS — JSON frames, designer-facing live tab state.
       if (pathname.startsWith('/_ws')) {
         const ok = srv.upgrade(req, {
@@ -339,6 +379,19 @@ await Bun.write(
 fsWatch.start();
 startHeapWatch();
 
+// Phase 27 Task 5 (E2) — live dirty-state. Subscribes to `fs:any` (after
+// fsWatch.start so it sees every event) and broadcasts `git-status` to the shell
+// on each versionable change. No-op for a non-git project (gitStatus → repo:false).
+const gitWatch = createGitWatch(ctx);
+
+// Phase 31 follow-up — external-canvas list watcher. Subscribes to `fs:any` and
+// emits `canvas-list-update` when a canvas file appears/disappears on disk from
+// OUTSIDE the dev-server (ACP agent `/design:new`, agent Write, git checkout),
+// so the browser file tree refreshes without a reload — the symmetric
+// counterpart to api.ts's create/delete emit. RCA:
+// `.ai/logs/rca/issue-acp-new-canvas-not-in-filetree.md`.
+const canvasListWatch = createCanvasListWatch(ctx);
+
 // Phase 9 Task 4 — bidirectional sync agent. No-op when the project isn't
 // linked to a hub (`.design/config.json` has no `linkedHub` field). Kicked
 // off after fsWatch so the agent's bus subscription receives every fs event.
@@ -371,6 +424,16 @@ if (!process.env.NO_OPEN) {
 async function shutdown() {
   console.log('\n  Stopping…');
   fsWatch.stop();
+  try {
+    gitWatch.stop();
+  } catch {
+    /* timer cleanup is best-effort */
+  }
+  try {
+    canvasListWatch.stop();
+  } catch {
+    /* timer cleanup is best-effort */
+  }
   try {
     activity.stop();
   } catch {

package/apps/studio/sync/agent.ts

@@ -50,17 +50,27 @@ import {
   commentsFromDoc,
   cssFromDoc,
   htmlFromDoc,
+  markSeeded,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  seededByFromDoc,
   stampBodyEdit,
   Y_SYNC_TYPES,
 } from './codec.ts';
-import { decideColdStart, unionCommentsById } from './cold-start.ts';
+import { decideColdStart, isExactRepeat, unionCommentsById } from './cold-start.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 
 export const DOC_FLUSH_MS = 800;
 
+/**
+ * Window after a `seed-local-up` during which this agent will repair a
+ * concurrent-seed duplication (F1). Bounded so the repair only ever fires for
+ * the cold-start race — a genuine peer edit that arrives minutes later is NEVER
+ * collapsed back to our original seed. Generous relative to the hub sync RTT.
+ */
+export const SEED_REPAIR_WINDOW_MS = 10_000;
+
 export interface CanvasSyncPaths {
   /** Absolute path to <designRoot>/<canvas>.html. */
   html: string;
@@ -164,10 +174,21 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
   let lastMeta: string | null = null;
   let lastCss: string | null = null;
 
+  // F1 — the body this agent pushed on `seed-local-up`, plus the deadline past
+  // which the de-dup repair stops firing. Set on seed; nulled only when the
+  // window lapses (after convergence the repair is a cheap no-op — the
+  // `body === seedInfo.body` guard short-circuits, so we don't bother clearing).
+  // Null = this agent never seeded (so it never repairs).
+  let seedInfo: { body: string; until: number } | null = null;
+
   function onDocUpdate(_update: Uint8Array, updateOrigin: unknown): void {
     if (stopped) return;
     // Self-applied (we just synced from disk) — disk is already current.
     if (updateOrigin === origin) return;
+    // F1 — a remote update during the seed window may have concatenated a
+    // concurrent peer's identical seed onto ours. Collapse it (single elected
+    // writer) BEFORE the flush below can mirror a doubled body to disk.
+    maybeRepairSeedDuplication();
     scheduleFlush();
   }
 
@@ -188,6 +209,45 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     }, flushMs);
   }
 
+  /**
+   * F1 — collapse a concurrent cold-seed duplication. When two peers
+   * `seed-local-up` the SAME body into an empty hub at the same instant, the
+   * merged Y.Text holds both insertions (`BODY` × N — un-buildable). This runs
+   * on every remote update inside the seed window and, on the single peer the
+   * `seededBy` Y.Map LWW elected, re-applies the canonical body so
+   * `applyHtmlToDoc`'s diff deletes the trailing duplicate(s). Only the elected
+   * owner repairs → the collapse op is emitted once and converges across peers
+   * (a non-owner just receives the delete). Restricted to an EXACT repeat of our
+   * seed: a divergent edit carries genuine bytes, so we DON'T touch it here —
+   * silently collapsing it would discard content. NOTE: that leaves the rare
+   * "two DIFFERENT bodies seeded into one empty hub at the same instant" case
+   * un-buildable until the NEXT boot, when `decideColdStart` routes it through
+   * the conflict path (dual snapshot + newest-wins). This live repair only
+   * covers the identical-seed race (the F1 RCA's scenario); the divergent
+   * variant is an accepted follow-up, not handled in-flight.
+   */
+  function maybeRepairSeedDuplication(): void {
+    if (!seedInfo) return;
+    if (Date.now() > seedInfo.until) {
+      seedInfo = null;
+      return;
+    }
+    const owner = seededByFromDoc(doc);
+    if (owner === null || owner !== doc.clientID) return; // not the elected writer
+    const body = htmlFromDoc(doc);
+    if (body === seedInfo.body) return; // already a single copy
+    if (!isExactRepeat(body, seedInfo.body)) return; // divergent edit → conflict path owns it
+    const canonical = seedInfo.body;
+    doc.transact(() => {
+      if (applyHtmlToDoc(doc, canonical, origin)) stampBodyEdit(doc, origin);
+    }, origin);
+    lastHtml = canonical;
+    opts.journal?.record(slug, { bodyHash: hashBytes(canonical) });
+    console.warn(
+      `[sync/${slug}] concurrent cold-seed duplication detected — collapsed to one copy (F1).`
+    );
+  }
+
   async function flush(): Promise<void> {
     if (!dirty || stopped) return;
     dirty = false;
@@ -348,7 +408,12 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       if (localHtml !== null) {
         doc.transact(() => {
           if (applyHtmlToDoc(doc, localHtml, origin)) stampBodyEdit(doc, origin);
+          // F1 — adopt is also a "seed local up" (first link / fresh hub); claim
+          // it + arm the repair window so two peers adopting the same draft into
+          // one hub at once self-heal the same way the decision-table seed does.
+          markSeeded(doc, origin);
         }, origin);
+        seedInfo = { body: localHtml, until: Date.now() + SEED_REPAIR_WINDOW_MS };
       }
       if (localComments !== null) {
         const parsed = tryParseJsonArray(localComments);
@@ -396,8 +461,15 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     const seedBodyUp = (body: string): void => {
       doc.transact(() => {
         if (applyHtmlToDoc(doc, body, origin)) stampBodyEdit(doc, origin);
+        // F1 — claim the seed (clientID marker) in the SAME update so a
+        // concurrent second seeder's merge resolves a single elected writer.
+        markSeeded(doc, origin);
       }, origin);
       lastHtml = body;
+      // Arm the de-dup repair window: if another peer seeded the same body at the
+      // same instant, the merged Y.Text will double — maybeRepairSeedDuplication
+      // (on the elected owner) collapses it back during this window.
+      seedInfo = { body, until: Date.now() + SEED_REPAIR_WINDOW_MS };
       opts.journal?.record(slug, { bodyHash: hashBytes(body) });
     };
 
@@ -421,6 +493,14 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         seedBodyUp(localHtml as string);
         bodyWinner = 'local';
         break;
+      case 'recover-seed-dup':
+        // F1 — booting against a hub whose body is our local body repeated (a
+        // concurrent cold-seed that already duplicated). Re-apply local so the
+        // diff deletes the extra copy/copies; the content equals local, so the
+        // visually-coupled lanes follow local too. Idempotent across peers.
+        seedBodyUp(localHtml as string);
+        bodyWinner = 'local';
+        break;
       case 'conflict': {
         // Divergence: snapshot BOTH versions to `_history/<slug>/` BEFORE any
         // write, then apply the newest-wins winner. Even a wrong pick costs

package/apps/studio/sync/codec.ts

@@ -338,6 +338,30 @@ export function bodyEditAtFromDoc(doc: Y.Doc): number | null {
   return typeof v === 'number' && Number.isFinite(v) ? v : null;
 }
 
+/**
+ * Record THIS doc's clientID as the seeder in `syncMeta.seededBy` (F1). Call it
+ * in the SAME transaction + origin as a `seed-local-up` body apply. The value is
+ * a Yjs clientID, so when two peers seed the same empty hub simultaneously and
+ * their maps merge, Y.Map's deterministic last-writer-wins resolution converges
+ * `seededBy` to ONE clientID on EVERY peer — that elected peer is the
+ * single-writer that performs the de-duplication repair, so the collapse op is
+ * never emitted twice. Informational/bookkeeping only; never materialized to
+ * disk (syncMeta is a sync-internal lane).
+ */
+export function markSeeded(doc: Y.Doc, origin?: unknown): void {
+  const map = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta);
+  doc.transact(() => {
+    map.set('seededBy', doc.clientID);
+  }, origin);
+}
+
+/** The elected seeder's clientID (`syncMeta.seededBy`), or null when no peer
+ *  ever seeded through the marker path (older peers / non-seed canvases). */
+export function seededByFromDoc(doc: Y.Doc): number | null {
+  const v = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).get('seededBy');
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
 /* ---------------------------------------------------------------- css */
 
 /** The synced canvas CSS string held in the doc, or null when unset/empty. */

package/apps/studio/sync/cold-start.ts

@@ -26,6 +26,7 @@ export type ColdStartAction =
   | 'materialize-hub'
   | 'seed-local-up'
   | 'fast-forward-hub'
+  | 'recover-seed-dup'
   | 'conflict';
 
 export interface ColdStartInput {
@@ -56,6 +57,24 @@ function isEmptyBody(body: string | null): boolean {
   return body === null || body.trim() === '';
 }
 
+/**
+ * True when `docBody` is exactly `localBody` repeated N≥2 times — the signature
+ * of a concurrent cold-seed collision (F1): two peers each `seed-local-up`-ed
+ * the SAME body into an empty hub before either's write propagated, so the CRDT
+ * preserved both insertions and the Y.Text became `BODY` × N. We detect the
+ * exact-repeat shape (not a fuzzy "contains") so a legitimate later edit — which
+ * is never a clean integer-multiple repeat of the prior body — can't be
+ * mis-read as a duplication and clobbered back. Exact equality (N==1) is the
+ * caller's `noop`, handled before this is consulted.
+ */
+export function isExactRepeat(docBody: string, localBody: string): boolean {
+  if (localBody.length === 0) return false;
+  if (docBody.length <= localBody.length) return false;
+  if (docBody.length % localBody.length !== 0) return false;
+  const n = docBody.length / localBody.length;
+  return docBody === localBody.repeat(n);
+}
+
 function commentId(c: unknown): string | null {
   if (c && typeof c === 'object' && typeof (c as { id?: unknown }).id === 'string') {
     return (c as { id: string }).id;
@@ -117,6 +136,27 @@ export function decideColdStart(input: ColdStartInput): ColdStartDecision {
     return { action: 'noop', reason: 'local and hub identical' };
   }
 
+  // Concurrent cold-seed collision (F1): the hub body is our local body repeated
+  // N≥2 times — two peers seeded the same canvas into an empty hub at the same
+  // moment and the CRDT concatenated both insertions (un-buildable: two `export
+  // default`). This is NOT divergence (it carries no new bytes — just a doubled
+  // copy of ours), so it must NOT take the conflict/fast-forward path. Collapse
+  // it back to one copy by re-applying local (the caller's `applyHtmlToDoc` diff
+  // deletes the trailing duplicate). Idempotent across peers — the delete targets
+  // the same CRDT items, so concurrent recoveries converge instead of fighting.
+  if (
+    input.localBody !== null &&
+    !localEmpty &&
+    !docEmpty &&
+    isExactRepeat(input.docBody, input.localBody)
+  ) {
+    return {
+      action: 'recover-seed-dup',
+      reason:
+        'hub body is local repeated — concurrent cold-seed duplication; collapsing to one copy',
+    };
+  }
+
   // Hash via hashBytes ONLY — the journal recorded its hashes through the same
   // fn (single source, echo-guard.ts), so this comparison is apples-to-apples.
   if (

package/apps/studio/sync/hub-link.ts

@@ -0,0 +1,137 @@
+// sync/hub-link.ts — Phase 29 (E4) Door C: connect to a team hub from the wizard.
+//
+// The CLI (`maude design link`) owns the FULL link flow (interactive trust gate +
+// per-project `.design/config.json` linkedHub write + `--adopt` push). This is the
+// lean in-app counterpart used by the onboarding wizard's advanced door: it saves the
+// hub CREDENTIAL to the global `~/.config/maude/hubs.json` (mode 0600) and records the
+// hub as trusted on THIS machine — the in-UI "Connect" IS the explicit trust grant the
+// CLI's interactive confirmation provides (DDR-054 F2). Hub tokens are GLOBAL /
+// per-machine (keyed by normalized URL), so a project later opened whose
+// `.design/config.json` names this hub syncs using the saved token. We deliberately do
+// NOT write a per-project `linkedHub` here (onboarding has no project yet) — that stays
+// a CLI / post-onboarding operation.
+//
+// SECURITY: the http layer gates this main-origin + loopback only (mirrors
+// /_api/github/*). The health probe is a best-effort, TOKENLESS GET to the user-entered
+// hub URL; only `{ ok, version }` is reflected back — no response-body passthrough, so it
+// can't become an SSRF data-exfil channel. The probe deliberately does NOT carry the hub
+// token: a user who pastes a lookalike URL must not have their credential delivered to the
+// attacker's host (phase-29 /flow:done attacker finding A2). The token is only persisted
+// locally (mode 0600) and presented later on the authenticated sync WS upgrade. The hub
+// address is whatever the user typed (a LAN / Tailscale / fly.dev URL is legitimate —
+// phase-9's hub model expects private hosts), so we do NOT block private IPs; the safety
+// is the loopback caller gate + no reflection + no token on the probe.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { hubsConfigPath, normalizeUrl } from './hubs-config.ts';
+
+export interface HubLinkResult {
+  status: number;
+  json: unknown;
+}
+
+const HUB_PROBE_TIMEOUT_MS = 4000;
+
+interface HubsFile {
+  hubs: Record<string, { token: string; linkedAt: number }>;
+  trusted?: string[];
+}
+
+/** Validate + probe + persist a hub credential. Returns an http-shaped result. */
+export async function linkHub(body: unknown): Promise<HubLinkResult> {
+  const b = (body ?? {}) as { url?: unknown; token?: unknown };
+  if (typeof b.url !== 'string' || !b.url.trim()) return bad('Enter the hub address.');
+  if (typeof b.token !== 'string' || !b.token.trim())
+    return bad('Paste the invite link or token your team gave you.');
+
+  let norm: string;
+  try {
+    norm = normalizeUrl(b.url.trim());
+  } catch {
+    return bad("That doesn't look like a valid hub address.");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(norm);
+  } catch {
+    return bad('Invalid hub address.');
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+    return bad('The hub address must start with http:// or https://.');
+
+  const token = b.token.trim();
+
+  // Best-effort reachability probe — TOKENLESS (never deliver the credential to a
+  // possibly-lookalike host) and does NOT gate the save (a firewalled hub the user
+  // trusts still links; the real auth happens on the sync WS upgrade).
+  const probe = await probeHealth(norm);
+
+  try {
+    saveHubCredential(norm, token);
+  } catch {
+    return { status: 500, json: { ok: false, error: "Couldn't save the hub connection." } };
+  }
+
+  return {
+    status: 200,
+    json: { ok: true, url: norm, healthy: probe.ok, version: probe.version ?? null },
+  };
+}
+
+function bad(error: string): HubLinkResult {
+  return { status: 400, json: { ok: false, error } };
+}
+
+async function probeHealth(url: string): Promise<{ ok: boolean; version?: string }> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), HUB_PROBE_TIMEOUT_MS);
+  try {
+    // Tokenless on purpose (attacker finding A2): /health is a liveness check; the
+    // credential is never sent to the user-typed host, only to the trusted hub on the
+    // authenticated sync WS upgrade later.
+    const res = await fetch(`${url}/health`, { signal: ctrl.signal });
+    if (!res.ok) return { ok: false };
+    let version: string | undefined;
+    try {
+      const j = (await res.json()) as { version?: unknown };
+      if (j && typeof j.version === 'string') version = j.version;
+    } catch {
+      /* health may not be JSON — reachability alone is enough */
+    }
+    return { ok: true, version };
+  } catch {
+    return { ok: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Upsert the token under `normUrl` + record per-machine trust; mode 0600. */
+export function saveHubCredential(normUrl: string, token: string): void {
+  const path = hubsConfigPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  let cfg: HubsFile = { hubs: {} };
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8'));
+      if (parsed && typeof parsed.hubs === 'object' && parsed.hubs !== null)
+        cfg = parsed as HubsFile;
+    } catch {
+      /* malformed → start fresh rather than throw */
+    }
+  }
+  cfg.hubs[normUrl] = { token, linkedAt: Date.now() };
+  if (!Array.isArray(cfg.trusted)) cfg.trusted = [];
+  if (!cfg.trusted.includes(normUrl)) cfg.trusted.push(normUrl);
+  writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* windows / read-only fs — best effort */
+  }
+}
+
+export const __testing = { probeHealth };