@quolu/lattice 0.53.0 → 0.54.0

package/bin/lattice-bridge-supervisor.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Windows bridge supervisor (bh6 prep). Startup-folder items only run once at
+ * logon — nothing like launchd's KeepAlive exists to restart a crashed
+ * process. This script is that supervision, written in JS instead of a batch
+ * GOTO loop because a loop's own process (and therefore its killability) is
+ * awkward to track reliably on Windows; a Node process's pid is not.
+ *
+ * Usage: node lattice-bridge-supervisor.mjs <descriptor.json>
+ * The descriptor supplies the environment `lattice-bridge.mjs` needs (it is
+ * never inherited from the Startup-folder launch context) and the path to
+ * write this supervisor's own pid to, so `bridge-startup-folder.mjs` can find
+ * and stop the whole tree later via `taskkill /T /F`.
+ */
+
+import { spawn } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const RESTART_DELAY_MS = 3_000;
+
+const descriptorPath = process.argv[2];
+if (typeof descriptorPath !== 'string' || descriptorPath.length === 0) {
+  process.stderr.write('usage: lattice-bridge-supervisor.mjs <descriptor.json>\n');
+  process.exit(2);
+}
+const descriptor = JSON.parse(readFileSync(descriptorPath, 'utf8'));
+if (descriptor?.schema !== 'lattice.bridge_supervisor_descriptor.v1'
+  || typeof descriptor.bridgePath !== 'string' || typeof descriptor.pidPath !== 'string'
+  || typeof descriptor.env !== 'object' || descriptor.env === null) {
+  process.stderr.write('bridge supervisor descriptor is invalid\n');
+  process.exit(2);
+}
+
+await writeFile(descriptor.pidPath, String(process.pid), { encoding: 'utf8', flag: 'w' });
+
+let stopping = false;
+let child = null;
+const stop = () => {
+  stopping = true;
+  child?.kill();
+};
+process.once('SIGINT', stop);
+process.once('SIGTERM', stop);
+
+const bridgePath = path.resolve(descriptor.bridgePath);
+while (!stopping) {
+  child = spawn(process.execPath, [bridgePath], {
+    env: { ...process.env, ...descriptor.env },
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  await new Promise((resolve) => child.once('exit', resolve));
+  child = null;
+  if (stopping) break;
+  await new Promise((resolve) => setTimeout(resolve, RESTART_DELAY_MS));
+}

package/bin/lattice-bridge.mjs

@@ -2,14 +2,26 @@
 
 import { readBridgeConfig } from '../src/bridge-config.mjs';
 import {
-  readBridgeStopRequest, removeBridgeDaemonActiveMarker, removeBridgeDaemonDescriptor,
-  writeBridgeDaemonDescriptor, writeBridgeStopReceipt,
+  bridgeDaemonVersionDrifted, readBridgeStopRequest, removeBridgeDaemonActiveMarker,
+  removeBridgeDaemonDescriptor, writeBridgeDaemonDescriptor, writeBridgeStopReceipt,
 } from '../src/bridge-daemon.mjs';
 import { createBridgeHubHeartbeatController } from '../src/bridge-hub-heartbeat.mjs';
+import { migrateBridgeToHub, retireBridgeTunnelLaunchAgent } from '../src/bridge-hub-migration.mjs';
+import { bridgeRegistrarSettings } from '../src/bridge-registrar.mjs';
 import { bridgeRuntimeController } from '../src/bridge-server.mjs';
 
+// Throttles bridgeDaemonVersionDrifted's disk read and the migration/tunnel-
+// retirement checks' subprocess calls (ssh, launchctl) — the 250ms reconcile
+// tick exists for local responsiveness, not for polling external processes
+// 4x/sec. Migration and tunnel-retirement share this interval: once migrated,
+// the migration check itself becomes a single cheap config-field read
+// (`current.hub !== null`), so there is no cost to leaving both armed forever.
+const BACKGROUND_CHECK_INTERVAL_MS = 60_000;
+
 const env = process.env;
 const hubHeartbeat = createBridgeHubHeartbeatController({ env });
+let lastVersionCheckAt = 0;
+let lastMigrationCheckAt = 0;
 const instanceToken = env.LATTICE_BRIDGE_INSTANCE_TOKEN;
 if (typeof instanceToken !== 'string' || !/^[0-9a-f]{64}$/u.test(instanceToken)) {
   process.stderr.write(`${JSON.stringify({ schema: 'lattice.bridge_daemon_error.v1',
@@ -61,6 +73,51 @@ timer = setInterval(async () => {
       await removeBridgeDaemonActiveMarker({ env });
       process.exit(0);
     }
+    // A stale-version exit is a clean stop, not a failure: whatever supervises
+    // this process (launchd KeepAlive, the Windows supervisor loop) relaunches
+    // it immediately, and the fresh process imports whatever is on disk now —
+    // this is the mechanism that makes "npm update, done" actually true rather
+    // than leaving an already-running daemon serving replaced code forever.
+    if (Date.now() - lastVersionCheckAt >= BACKGROUND_CHECK_INTERVAL_MS) {
+      lastVersionCheckAt = Date.now();
+      if (await bridgeDaemonVersionDrifted({})) {
+        await close();
+        await removeBridgeDaemonDescriptor({ env });
+        await removeBridgeDaemonActiveMarker({ env });
+        process.exit(0);
+      }
+    }
+    // bh5 auto-migration: a terminal still carrying the pre-hub registrar env
+    // (LaunchAgent-baked, so it outlives any single process) upgrades itself
+    // to hub registration with no operator action — see bridge-hub-migration.mjs's
+    // module doc for why this is the whole point of the owner's "update it,
+    // done" acceptance test. Runs on the same throttle as the version check;
+    // once migrated it is a single cheap config-field read, so leaving it
+    // armed forever costs nothing. Tunnel retirement is attempted alongside
+    // it (not gated to the migration transition alone) so a retirement that
+    // failed once keeps getting retried rather than being a one-shot.
+    if (Date.now() - lastMigrationCheckAt >= BACKGROUND_CHECK_INTERVAL_MS) {
+      lastMigrationCheckAt = Date.now();
+      if (bridgeRegistrarSettings(env) !== null) {
+        await migrateBridgeToHub({ env }).catch((error) => {
+          process.stderr.write(`${JSON.stringify({ schema: 'lattice.bridge_daemon_error.v1',
+            code: error?.code ?? 'BRIDGE_HUB_MIGRATION_FAILED',
+            message: error?.message ?? 'bridge hub migration failed' })}\n`);
+        });
+        const migratedConfig = await readBridgeConfig({ env });
+        if (migratedConfig?.hub !== null && migratedConfig?.hub !== undefined) {
+          // retireBridgeTunnelLaunchAgent's own contract never throws for any
+          // expected outcome (not loaded, bootout failure, launchctl absent —
+          // all typed returns); this catch is only for a genuinely unexpected
+          // bug in that function, and it is still logged, not swallowed.
+          await retireBridgeTunnelLaunchAgent({ env }).catch((error) => {
+            process.stderr.write(`${JSON.stringify({ schema: 'lattice.bridge_daemon_error.v1',
+              code: error?.code ?? 'BRIDGE_TUNNEL_RETIREMENT_FAILED',
+              message: error?.message ?? 'bridge tunnel retirement failed' })}\n`);
+          });
+        }
+      }
+    }
     const config = await readBridgeConfig({ env });
     if (config === null || !config.enabled) {
       await close();

package/bin/lattice-dashboard.mjs

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-import { stat } from 'node:fs/promises';
-import path from 'node:path';
-
-import { readTodoStoreStable } from '../src/todo-store.mjs';
 import { TODO_STATUS_DISPATCH_ONLY, projectTodoStatus } from '../src/todo-status.mjs';
+import { createTodoStoreCache } from '../src/todo-store-cache.mjs';
 import { ganttLiveHeadDigest, renderTodoGanttForProject } from '../src/todo-cli.mjs';
 import { readProjectExternalPane } from '../src/project-identity.mjs';
 import {
@@ -35,27 +32,12 @@ const port = typeof configured === 'string' && /^(?:0|[1-9][0-9]{0,4})$/u.test(c
 const registry = createTodoGanttProjectRegistry();
 const roots = new Map();
 const reportedStoreReadFailures = new Set();
-const storeCache = new Map();
-
-function manifestFingerprint(value) {
-  return `${value.dev}:${value.ino}:${value.size}:${value.mtimeMs}:${value.ctimeMs}`;
-}
-
-async function readCachedStore(repoRoot) {
-  const manifestRef = path.join(repoRoot, '.lattice', 'todo', 'manifest.json');
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    const beforeFingerprint = manifestFingerprint(await stat(manifestRef));
-    const cached = storeCache.get(repoRoot);
-    if (cached?.fingerprint === beforeFingerprint) return cached.store;
-    const store = await readTodoStoreStable({ repoRoot });
-    const afterFingerprint = manifestFingerprint(await stat(manifestRef));
-    if (beforeFingerprint === afterFingerprint) {
-      storeCache.set(repoRoot, { fingerprint: afterFingerprint, store });
-      return store;
-    }
-  }
-  return readTodoStoreStable({ repoRoot });
-}
+// room 2488's "gantt serve固着" symptom (a dashboard stuck on stale/broken state that
+// only a process restart cleared, with the store and git both already fixed) traced to
+// this cache — see src/todo-store-cache.mjs for why it is content-digest keyed rather
+// than stat()-fingerprint keyed.
+const storeCache = createTodoStoreCache();
+const readCachedStore = (repoRoot) => storeCache.read(repoRoot);
 
 async function synchronize() {
   const active = await readVisibleTodoDashboardProjects({ env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Schedulability compiler for multi-agent development: observe real code boundaries, refactor the conflicting seam, recompile the plan for parallel execution",
   "author": {
     "name": "Quo / クオ at kitepon.dev",

package/src/bridge-address.mjs

@@ -105,3 +105,22 @@ export function resolveBridgeListenAddress({ configured, interfaces = {} } = {})
   return { state: 'rebindable', effective: candidates[0], configured: wanted, candidates,
     reason: 'configured_address_absent_rebound_within_subnet' };
 }
+
+/**
+ * Pick a LAN-facing address for a terminal that has none yet — bh5's Mac
+ * auto-migration (loopback + ssh tunnel → direct hub registration) and any
+ * first-time setup with no address preference. Deliberately simpler than
+ * `resolveBridgeListenAddress`: that function preserves "same intent" across
+ * a DHCP move by requiring a same-subnet match against an already-configured
+ * address, but there is no prior intent to preserve when the terminal had no
+ * LAN presence before. The first non-internal address, sorted for
+ * determinism, is a reasonable default; ambiguous hosts (more than one
+ * candidate) are still reported so a caller can choose to surface that rather
+ * than silently pick.
+ */
+export function pickBridgeLanAddress({ interfaces = {}, family = null } = {}) {
+  const candidates = bridgeHostAddresses(interfaces)
+    .filter((entry) => !entry.internal && (family === null || entry.family === family))
+    .map((entry) => entry.address);
+  return { address: candidates[0] ?? null, candidates };
+}

package/src/bridge-cli.mjs

@@ -17,6 +17,10 @@ import {
   disableBridgeLaunchAgent, installBridgeLaunchAgent, restoreBridgeLaunchAgent,
   snapshotBridgeLaunchAgent,
 } from './bridge-launch-agent.mjs';
+import {
+  disableBridgeStartupFolder, installBridgeStartupFolder, restoreBridgeStartupFolder,
+  snapshotBridgeStartupFolder,
+} from './bridge-startup-folder.mjs';
 
 // v2 adds the liveness fields. `enabled` only says the configuration is on;
 // it never said the bridge could actually be reached, which let a DHCP lease
@@ -66,6 +70,22 @@ async function bridgeLiveness(config, { interfaces = networkInterfaces(), probe
   };
 }
 
+// The bridge's own persistence mechanism is OS-specific; everything above
+// this line (config, daemon lifecycle, registrar) is not. Selecting by
+// `process.platform` here — rather than requiring every caller to pick — is
+// what lets `lattice bridge setup` on Windows persist via the Startup folder
+// exactly the way it persists via a LaunchAgent on macOS, with no separate
+// command or manual step (see bridge-startup-folder.mjs's module doc for why
+// Task Scheduler's ONLOGON trigger could not be used instead).
+function platformLaunchAgent() {
+  if (process.platform === 'win32') {
+    return { snapshot: snapshotBridgeStartupFolder, install: installBridgeStartupFolder,
+      disable: disableBridgeStartupFolder, restore: restoreBridgeStartupFolder };
+  }
+  return { snapshot: snapshotBridgeLaunchAgent, install: installBridgeLaunchAgent,
+    disable: disableBridgeLaunchAgent, restore: restoreBridgeLaunchAgent };
+}
+
 function fail(stderr, code, message) {
   stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code, message })}\n`);
   return 2;
@@ -160,8 +180,7 @@ export async function collectBridgeSetupWizard({ input, output, prompts = clack
 export async function runBridgeCli({ argv, stdout, stderr, env = process.env,
   stdin = process.stdin, daemon = { ensure: ensureBridgeDaemon, requestStop: requestBridgeDaemonStop,
     stop: stopBridgeDaemon, clearStop: clearBridgeStopControl },
-  launchAgent = { snapshot: snapshotBridgeLaunchAgent, install: installBridgeLaunchAgent,
-    disable: disableBridgeLaunchAgent, restore: restoreBridgeLaunchAgent },
+  launchAgent = platformLaunchAgent(),
   prompts = clack, probe = probeBridgeListener, interfaces = networkInterfaces() } = {}) {
   if (!Array.isArray(argv)) {
     return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable|register> [options] --json');

package/src/bridge-config.mjs

@@ -175,7 +175,14 @@ async function readDocument(ref) {
     if (error?.code === 'ENOENT') return null;
     throw new BridgeConfigError('BRIDGE_CONFIG_UNREADABLE', 'bridge config cannot be read', undefined, error);
   }
-  if (!stats.isFile() || stats.isSymbolicLink() || (stats.mode & 0o777) !== 0o600) {
+  // Windows has no POSIX permission-bit model: `fs.stat().mode` never reports
+  // 0600 there regardless of what `mode`/`chmod` requested at write time, so
+  // this check is a hard, unconditional block on every platform but darwin/
+  // linux — verified against a real Windows host (`BRIDGE_CONFIG_MODE_INVALID`
+  // on a config `configureBridge` itself had just written moments earlier).
+  // The other checks (regular file, not a symlink) still apply everywhere.
+  if (!stats.isFile() || stats.isSymbolicLink()
+    || (process.platform !== 'win32' && (stats.mode & 0o777) !== 0o600)) {
     throw new BridgeConfigError('BRIDGE_CONFIG_MODE_INVALID', 'bridge config must be a regular 0600 file');
   }
   let value;

package/src/bridge-daemon.mjs

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
-import { chmod, lstat, open, rename, rm, writeFile } from 'node:fs/promises';
+import { chmod, lstat, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { isIP } from 'node:net';
 import path from 'node:path';
 import { parseTree } from 'jsonc-parser';
@@ -9,6 +9,7 @@ import { parseTree } from 'jsonc-parser';
 import {
   BRIDGE_PORT_MAX, BRIDGE_PORT_MIN, BridgeConfigError, bridgeConfigPaths, readBridgeConfig,
 } from './bridge-config.mjs';
+import packageJson from '../package.json' with { type: 'json' };
 
 const DESCRIPTOR_SCHEMA = 'lattice.bridge_daemon.v1';
 const START_TIMEOUT_MS = 5_000;
@@ -83,7 +84,10 @@ async function readStrictJsonOnce(ref, label) {
   let handle;
   try {
     before = await lstat(ref);
-    if (!before.isFile() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o600
+    // Windows has no POSIX permission-bit model — see bridge-config.mjs's
+    // readDocument for the same guard and the real-host verification.
+    if (!before.isFile() || before.isSymbolicLink()
+      || (process.platform !== 'win32' && (before.mode & 0o777) !== 0o600)
       || before.size > CONTROL_MAX_BYTES) throw new Error(`${label} unsafe`);
     handle = await open(ref, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
     const opened = await handle.stat();
@@ -376,3 +380,25 @@ export async function stopBridgeDaemon({ env = process.env } = {}) {
   }
   throw new BridgeConfigError('BRIDGE_DAEMON_STOP_FAILED', 'bridge daemon did not stop');
 }
+
+const PACKAGE_JSON_PATH = path.resolve(import.meta.dirname, '../package.json');
+
+/**
+ * Whether the on-disk package.json now reports a different version than the
+ * one this running process loaded at start — i.e. `npm install`/`update`
+ * replaced the files under a still-running daemon (the "daemon の版持ち"
+ * trap, AGENTS.md: a daemon keeps serving whatever module it imported at
+ * startup no matter what gets installed afterward). A long-running process
+ * cannot hot-swap its own already-imported modules; the only fix is to exit
+ * and let whatever supervises it (launchd's KeepAlive, the Windows
+ * supervisor's restart loop) relaunch a fresh process that imports the new
+ * code. Read failures return `false` — an unrelated fs hiccup must not force
+ * a restart loop.
+ */
+export async function bridgeDaemonVersionDrifted({ packageJsonPath = PACKAGE_JSON_PATH } = {}) {
+  let onDisk;
+  try {
+    onDisk = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+  } catch { return false; }
+  return typeof onDisk?.version === 'string' && onDisk.version !== packageJson.version;
+}

package/src/bridge-hub-migration.mjs

@@ -0,0 +1,118 @@
+/**
+ * Mac auto-migration (bh5): a terminal running the old single-slot topology
+ * (loopback bridge + `LATTICE_BRIDGE_REGISTRAR_*` ssh registrar) upgrades to
+ * hub registration with zero manual commands. The owner's stated acceptance
+ * test is literal: an agent who knows nothing about hub/port/flags/migration
+ * runs a normal package update, and the bridge finds its own way onto the
+ * public page (room 2446, 2461) — no `--hub` flag, no LaunchAgent surgery.
+ *
+ * The trigger is the registrar call the daemon already makes on every new
+ * binding (`bridge-registrar.mjs`'s `registerBridgeUpstream`, used by
+ * `bridge-launch-agent.mjs`'s plist today only to keep the reverse-proxy
+ * literal current). The v2 registrar script (room 2452) additionally returns
+ * `hub_url` in that same response — this module is what turns "a hub_url
+ * showed up in a registration reply" into "reconfigure this bridge to use
+ * it and retire the ssh tunnel", entirely from information the terminal
+ * already had a reason to ask for.
+ */
+
+import { execFile } from 'node:child_process';
+import { rm } from 'node:fs/promises';
+import { networkInterfaces } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { pickBridgeLanAddress } from './bridge-address.mjs';
+import { configureBridge, readBridgeConfig } from './bridge-config.mjs';
+import {
+  bridgeRegistrarSettings, deriveBridgeHubUrlFromRegistration, registerBridgeUpstream,
+} from './bridge-registrar.mjs';
+
+const execFileAsync = promisify(execFile);
+
+/** The ssh reverse-tunnel LaunchAgent from the pre-hub topology
+  * (docs/operations/lattice-kitepon-deployment.md) — distinct from
+  * `dev.kitepon.lattice.bridge`, which `bridge-launch-agent.mjs` owns and
+  * this migration never touches. */
+export const BRIDGE_TUNNEL_LAUNCH_AGENT_LABEL = 'dev.kitepon.lattice.bridge-tunnel';
+
+/**
+ * Attempt one migration step. Called from the daemon's reconcile loop, so it
+ * must be cheap to call when there is nothing to do and must never throw for
+ * a condition the caller should just keep running through (no registrar
+ * configured, already migrated, hub unreachable this cycle) — only a
+ * genuinely invalid registrar env (`bridgeRegistrarSettings`'s own
+ * half-configured-pair failure) propagates, matching every other registrar
+ * caller's behavior.
+ */
+export async function migrateBridgeToHub({
+  env = process.env, interfaces = networkInterfaces(), readConfig = readBridgeConfig,
+  configure = configureBridge, register = registerBridgeUpstream,
+} = {}) {
+  const registrar = bridgeRegistrarSettings(env);
+  if (registrar === null) return { migrated: false, reason: 'registrar_not_configured' };
+  const current = await readConfig({ env });
+  if (current === null || !current.enabled) return { migrated: false, reason: 'bridge_not_enabled' };
+  if (current.hub !== null) return { migrated: false, reason: 'already_migrated' };
+
+  const registration = await register({ port: current.listen.port, env });
+  const hubUrl = deriveBridgeHubUrlFromRegistration(registration);
+  if (hubUrl === null) return { migrated: false, reason: 'no_hub_url_available', registration };
+
+  const picked = pickBridgeLanAddress({ interfaces });
+  if (picked.address === null) return { migrated: false, reason: 'no_lan_address_available' };
+
+  const updated = await configure({
+    address: picked.address, port: null, reuseCurrentPort: false,
+    upstream: current.upstream, hub: { url: hubUrl },
+    allowedHosts: current.allowed_hosts.filter((host) => host !== current.listen.address),
+    env,
+  });
+  return { migrated: true, config: updated, hubUrl };
+}
+
+function launchAgentPlistPath(label, env) {
+  const home = env.HOME;
+  if (typeof home !== 'string' || !path.isAbsolute(home)) return null;
+  return path.join(home, 'Library', 'LaunchAgents', `${label}.plist`);
+}
+
+/**
+ * Retire the pre-hub ssh reverse-tunnel LaunchAgent, once migration has
+ * actually landed a hub URL — never speculatively, so a bridge that never
+ * reaches `migrateBridgeToHub`'s success path never touches this agent.
+ * Idempotent and non-fatal: a tunnel that is not loaded (already retired, or
+ * this deployment never had one) is success, not an error, and any
+ * `launchctl` failure here must not crash a daemon whose primary job — hub
+ * registration — has already succeeded by the time this runs.
+ */
+export async function retireBridgeTunnelLaunchAgent({
+  env = process.env, uid = process.getuid?.(), runner = defaultTunnelLaunchctlRunner,
+  label = BRIDGE_TUNNEL_LAUNCH_AGENT_LABEL,
+} = {}) {
+  if (!Number.isSafeInteger(uid) || uid < 0) return { retired: false, reason: 'uid_unavailable' };
+  const service = `gui/${uid}/${label}`;
+  let probe;
+  try { probe = await runner(['print', service]); } catch { return { retired: false, reason: 'launchctl_unavailable' }; }
+  if (probe.code !== 0) return { retired: false, reason: 'not_loaded' };
+  try {
+    const bootout = await runner(['bootout', service]);
+    if (bootout.code !== 0) return { retired: false, reason: 'bootout_failed' };
+  } catch { return { retired: false, reason: 'bootout_failed' }; }
+  const plistPath = launchAgentPlistPath(label, env);
+  if (plistPath !== null) await rm(plistPath, { force: true }).catch(() => {});
+  return { retired: true };
+}
+
+export async function defaultTunnelLaunchctlRunner(args) {
+  try {
+    const result = await execFileAsync('/bin/launchctl', args, { encoding: 'utf8' });
+    return { code: 0, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+  } catch (error) {
+    if (Number.isInteger(error?.code)) {
+      return { code: error.code, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };
+    }
+    throw error;
+  }
+}
+

package/src/bridge-hub-server.mjs

@@ -176,19 +176,30 @@ function respondError(response, status, code, detail = null) {
   response.end(`${JSON.stringify(body)}\n`);
 }
 
+// This must stay visually identical to todo-gantt-live.mjs's dashboardHtml
+// (same shell/brand/card markup, same design tokens) — the public entrance
+// changing its own look when the routing behind it changed from single- to
+// multi-terminal is exactly the regression the owner flagged (room 2474;
+// plan_bridge-hub.md's non-goal "dashboard renderer/gantt UIの変更はしない"
+// covers keeping this landing's appearance, not just the diagrams behind it).
+// Reimplemented locally rather than imported: this codebase's bridge modules
+// each keep their own copy of such patterns rather than cross-importing
+// (see bh2-hub-server.md's rationale for validatedHubHost et al.), and the
+// only genuinely new thing here — an online/offline badge per project — has
+// no home in the single-terminal original to import from anyway.
 function hubIndexHtml(view) {
   const rows = view.map((project) => {
     const href = `/projects/${encodeURIComponent(project.project_id)}/`;
-    const statusLabel = project.status === 'online' ? 'オンライン' : 'オフライン';
+    const online = project.status === 'online';
+    const statusLabel = online ? 'オンライン' : 'オフライン';
+    const statusClass = online ? 'status-online' : 'status-offline';
     const identity = project.display_name === project.project_id ? '' : `<code>${escapeHtml(project.project_id)}</code>`;
     return `<li><a href="${escapeHtml(href)}"><strong>${escapeHtml(project.display_name)}</strong>`
-      + `${identity}<span>${escapeHtml(statusLabel)}</span></a></li>`;
+      + `${identity}<span class="${statusClass}">${escapeHtml(statusLabel)}</span>`
+      + `<span aria-hidden="true">→</span></a></li>`;
   }).join('');
-  const content = rows.length === 0 ? '<p>登録されているプロジェクトはありません。</p>' : `<ul>${rows}</ul>`;
-  return `<!doctype html><html lang="ja"><head><meta charset="utf-8">`
-    + `<meta name="viewport" content="width=device-width,initial-scale=1">`
-    + `<title>登録済みプロジェクト — Lattice hub</title></head>`
-    + `<body><h1>登録済みプロジェクト</h1>${content}</body></html>`;
+  const content = rows.length === 0 ? '<p>登録されている端末はありません。</p>' : `<ul>${rows}</ul>`;
+  return `<!doctype html><html lang="ja"><head><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="description" content="Latticeが管理している公開中の工程と現在地を確認できます。"><meta name="robots" content="noindex, nofollow"><meta property="og:title" content="公開中の工程表 — Lattice"><meta property="og:description" content="Latticeが管理している公開中の工程と現在地を確認できます。"><meta name="theme-color" content="#f7f3ea"><title>公開中の工程表 — Lattice</title><style>:root{color-scheme:light;--paper:#f7f3ea;--panel:#fffdf8;--ink:#201d19;--soft:#6c655d;--line:#d8d0c5;--cobalt:#315cbe;--orange:#e85f2a;--good:#0ca30c;--critical:#d03b3b}*{box-sizing:border-box}body{min-height:100vh;margin:0;color:var(--ink);background:var(--paper);font:16px/1.7 system-ui,-apple-system,sans-serif}.shell{max-width:880px;margin:0 auto;padding:28px 22px 40px}.brand{display:flex;align-items:center;gap:9px;padding-bottom:24px;border-bottom:1px solid var(--line);font-size:.88rem}.brand a,.footer a{color:var(--ink);font-weight:800;text-decoration:none}.brand a:hover,.footer a:hover{color:var(--cobalt)}.brand span{color:var(--soft)}main{padding:64px 0 72px}.eyebrow{margin:0 0 8px;color:var(--orange);font-size:.76rem;font-weight:800;letter-spacing:.14em}.lead{max-width:620px;margin:0 0 34px;color:var(--soft)}h1{margin:0 0 14px;font-size:clamp(2rem,6vw,3.4rem);line-height:1.12;letter-spacing:-.04em}ul{display:grid;gap:12px;margin:0;padding:0;list-style:none}li a{display:grid;grid-template-columns:minmax(0,1fr) auto auto;align-items:center;gap:20px;padding:18px 20px;border:1px solid var(--line);border-radius:12px;color:inherit;background:var(--panel);text-decoration:none;box-shadow:0 8px 28px rgba(48,39,27,.04)}li a:hover{border-color:var(--cobalt);transform:translateY(-1px)}li strong{font-size:1.04rem}li code{color:var(--soft);font-size:.78rem}li .status-online{color:var(--good);font-weight:800}li .status-offline{color:var(--critical);font-weight:800}li>a>span[aria-hidden]{color:var(--cobalt);font-weight:800}.note{margin:28px 0 0;padding:16px 18px;border-left:3px solid var(--orange);color:var(--soft);background:rgba(255,253,248,.72);font-size:.88rem}.footer{display:flex;flex-wrap:wrap;justify-content:space-between;gap:16px;padding-top:20px;border-top:1px solid var(--line);color:var(--soft);font-size:.82rem}.footer nav{display:flex;gap:18px}@media(max-width:560px){.shell{padding:20px 16px 32px}main{padding:44px 0 56px}li a{grid-template-columns:minmax(0,1fr) auto;padding:16px}li code{grid-column:1/-1;grid-row:2}.footer{display:block}.footer nav{margin-top:10px}}</style></head><body><div class="shell"><header class="brand"><a href="https://kitepon.dev/">kitepon.dev</a><span aria-hidden="true">/</span><strong>Lattice</strong></header><main><p class="eyebrow">LIVE DEVELOPMENT</p><h1>公開中の工程表</h1><p class="lead">Latticeが管理しているプロジェクトの工程と、いまどこまで進んでいるかを公開データから確認できます。</p>${content}<p class="note">表示内容はLatticeの記録から自動生成されます。製品の紹介や使い方はGitHubをご覧ください。</p></main><footer class="footer"><span>kitepon.dev の開発工程を、Latticeで可視化しています。</span><nav aria-label="関連リンク"><a href="https://kitepon.dev/">kitepon.dev</a><a href="https://github.com/kitepon-rgb/Lattice">GitHub</a></nav></footer></div></body></html>`;
 }
 
 function hubProjectStatusHtml(code, projectId, requestPath, message) {
@@ -512,6 +523,15 @@ export async function startBridgeHubServer({
       return;
     }
     const rawPath = requestUrl.split('?', 1)[0];
+    if (rawPath === '/') {
+      // The old single-terminal bridge served the project index at root; hub only ever
+      // routed `/projects/*`, so the public entrance 404'd (room 2488 — a functional
+      // regression, not a design one: the front door itself was gone, independent of how
+      // it looks). Redirect rather than duplicate handleProjectsIndex's logic at a second path.
+      response.writeHead(301, { location: '/projects/', 'cache-control': 'no-store' });
+      response.end();
+      return;
+    }
     if (rawPath === '/__lattice/hub/register') { await handleRegister(incoming, response); return; }
     if (rawPath === '/projects/') { await handleProjectsIndex(incoming, response); return; }
     const match = PROJECT_ROUTE.exec(rawPath);

package/src/bridge-registrar.mjs

@@ -21,6 +21,8 @@
 
 import { execFile } from 'node:child_process';
 
+import { normalizeBridgeHubUrl } from './bridge-config.mjs';
+
 export const REGISTRAR_RESULT_SCHEMA = 'lattice.bridge_registrar_result.v1';
 
 const SSH_HOST = /^[A-Za-z0-9][A-Za-z0-9._-]{0,253}$/u;
@@ -100,3 +102,19 @@ export async function registerBridgeUpstream({
     state: remote.changed === true ? 'updated' : 'unchanged',
     port, host: settings.host, remote, detail: null };
 }
+
+/**
+ * Extract a validated hub URL from a `registerBridgeUpstream` result, or
+ * `null` if this response carries none (old `lattice.bridge_registration.v1`
+ * script, a failed/not_configured registration, or a malformed value).
+ *
+ * Never throws: the caller is bh5's auto-migration path, which must fail
+ * safe into the legacy (no-hub) configuration rather than crash the daemon
+ * over a malformed hint from a remote script it does not control the
+ * deployment of.
+ */
+export function deriveBridgeHubUrlFromRegistration(result) {
+  const hubUrl = result?.remote?.hub_url;
+  if (typeof hubUrl !== 'string' || hubUrl.length === 0) return null;
+  try { return normalizeBridgeHubUrl({ url: hubUrl }).url; } catch { return null; }
+}

package/src/bridge-server.mjs

@@ -45,7 +45,10 @@ async function readDashboardDescriptor(ref) {
   let handle;
   try {
     before = await lstat(ref);
-    if (!before.isFile() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o600 || before.size > 65_536) {
+    // Windows has no POSIX permission-bit model — see bridge-config.mjs's
+    // readDocument for the same guard and the real-host verification.
+    if (!before.isFile() || before.isSymbolicLink()
+      || (process.platform !== 'win32' && (before.mode & 0o777) !== 0o600) || before.size > 65_536) {
       throw new BridgeConfigError('BRIDGE_UPSTREAM_INVALID', 'dashboard descriptor is unsafe');
     }
     handle = await open(ref, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));

package/src/bridge-startup-folder.mjs

@@ -0,0 +1,348 @@
+/**
+ * Windows bridge persistence via the per-user Startup folder — the Windows
+ * counterpart to `bridge-launch-agent.mjs`'s macOS LaunchAgent, with the same
+ * public contract (`snapshot`/`install`/`disable`/`restore`) so `bridge-cli.mjs`
+ * can select between them by `process.platform` without changing its own flow.
+ *
+ * Windows has no per-user analogue of launchd's KeepAlive supervision, and
+ * Task Scheduler's `ONLOGON` trigger requires elevation this product's "no
+ * ritual beyond one-time setup" bar cannot spend (verified empirically: both
+ * `schtasks /Create /SC ONLOGON` and `Register-ScheduledTask -Trigger
+ * (New-ScheduledTaskTrigger -AtLogOn)` return access-denied under a normal,
+ * non-elevated user token). The Startup folder needs no elevation — writing
+ * into `%APPDATA%\...\Startup` is an ordinary per-user file operation — but it
+ * only *starts* something at logon; nothing supervises it afterward.
+ *
+ * `lattice-bridge-supervisor.mjs` supplies that supervision (spawn, wait for
+ * exit, restart) in plain JS rather than a batch GOTO loop: a loop's own
+ * process is awkward to track and kill reliably on Windows, while a Node
+ * process's pid is not. The Startup-folder `.vbs` launcher runs the
+ * supervisor hidden (`WindowStyle 0`) so no console window appears at logon
+ * or at any crash-restart — the same class of bug the Windows-console-
+ * avalanche P0 hotfix (`windowsHide`, 0.52.4) exists to avoid, here via a
+ * different mechanism since this process tree is spawned by Windows logon
+ * rather than by this codebase's own `child_process.spawn`. Stopping the
+ * whole tree (supervisor + whatever bridge child it currently owns) uses
+ * `taskkill /T /F /PID <supervisor pid>` — Windows's own recursive-kill,
+ * since a forcibly-terminated supervisor gets no chance to clean up its own
+ * child.
+ */
+
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import {
+  lstat, mkdir, open, readFile, realpath, rename, rm, writeFile,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { BridgeConfigError, readBridgeConfig } from './bridge-config.mjs';
+import { readBridgeDaemonDescriptor } from './bridge-daemon.mjs';
+import { bridgeRegistrarSettings } from './bridge-registrar.mjs';
+
+export const BRIDGE_STARTUP_LABEL = 'LatticeBridge';
+const DESCRIPTOR_SCHEMA = 'lattice.bridge_supervisor_descriptor.v1';
+const START_TIMEOUT_MS = 5_000;
+const STOP_TIMEOUT_MS = 3_000;
+const execFileAsync = promisify(execFile);
+
+function fail(code, message, cause = undefined) {
+  return new BridgeConfigError(code, message, undefined, cause);
+}
+
+export function bridgeStartupFolderPaths(env = process.env) {
+  const appData = env.APPDATA;
+  const localAppData = env.LOCALAPPDATA;
+  if (typeof appData !== 'string' || !path.isAbsolute(appData)) {
+    throw fail('BRIDGE_STARTUP_FOLDER_APPDATA_INVALID', 'APPDATA must be an absolute path');
+  }
+  if (typeof localAppData !== 'string' || !path.isAbsolute(localAppData)) {
+    throw fail('BRIDGE_STARTUP_FOLDER_APPDATA_INVALID', 'LOCALAPPDATA must be an absolute path');
+  }
+  // The launcher must live in the Startup folder — Windows only runs what it
+  // finds there. Everything it launches lives in our own runtime directory
+  // instead: Startup-folder contents are conventionally opaque shortcuts, and
+  // keeping the real state (descriptor, pidfile) in a folder this module
+  // fully owns keeps the safety checks below meaningful.
+  const startupDirectory = path.join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+  const runtimeDirectory = path.join(localAppData, 'Lattice', 'bridge-startup');
+  return Object.freeze({
+    startupDirectory, runtimeDirectory,
+    launcher: path.join(startupDirectory, `${BRIDGE_STARTUP_LABEL}.vbs`),
+    descriptor: path.join(runtimeDirectory, 'descriptor.json'),
+    pidfile: path.join(runtimeDirectory, 'supervisor.pid'),
+  });
+}
+
+async function prepareDirectory(directory) {
+  await mkdir(directory, { recursive: true });
+  const stats = await lstat(directory);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw fail('BRIDGE_STARTUP_FOLDER_DIR_UNSAFE', 'startup folder path is unsafe');
+  }
+}
+
+async function strictFile(ref, maxBytes = 65_536) {
+  let before;
+  let handle;
+  try {
+    before = await lstat(ref);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) {
+      throw new Error('unsafe startup file');
+    }
+    handle = await open(ref, fsConstants.O_RDONLY);
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino
+      || opened.size !== before.size) {
+      throw new Error('startup file changed during validation');
+    }
+    const content = await handle.readFile('utf8');
+    const after = await lstat(ref);
+    if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) {
+      throw new Error('startup file changed during read');
+    }
+    return content;
+  } catch (error) {
+    if (error?.code === 'ENOENT' && before === undefined) return null;
+    throw fail('BRIDGE_STARTUP_FOLDER_FILE_UNSAFE', 'bridge startup file is unsafe', error);
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function atomicFile(ref, content) {
+  const temporary = `${ref}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });
+    await rename(temporary, ref);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+async function executablePath(ref, label) {
+  if (typeof ref !== 'string' || !path.isAbsolute(ref)) {
+    throw fail('BRIDGE_STARTUP_FOLDER_EXECUTABLE_INVALID', `${label} path must be absolute`);
+  }
+  let resolved;
+  let stats;
+  try {
+    resolved = await realpath(ref);
+    stats = await lstat(resolved);
+  } catch (error) {
+    throw fail('BRIDGE_STARTUP_FOLDER_EXECUTABLE_INVALID', `${label} is unavailable`, error);
+  }
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw fail('BRIDGE_STARTUP_FOLDER_EXECUTABLE_INVALID', `${label} is unsafe`);
+  }
+  return resolved;
+}
+
+/** VBS escapes an embedded `"` by doubling it. Paths we generate never
+  * contain one (`executablePath`/our own runtime dir), so this only guards
+  * against that invariant silently breaking rather than mis-escaping. */
+function vbsQuoted(label, value) {
+  if (typeof value !== 'string' || value.length === 0 || value.includes('"')) {
+    throw fail('BRIDGE_STARTUP_FOLDER_VALUE_UNSAFE', `${label} is unsafe to embed in the startup launcher`);
+  }
+  return `"""${value}"""`;
+}
+
+function launcherScript({ nodePath, supervisorPath, descriptorPath }) {
+  // WScript.Shell.Run(command, windowStyle, waitOnReturn). windowStyle 0 =
+  // hidden, waitOnReturn False = fire-and-forget (the supervisor outlives
+  // wscript.exe, which exits right after this call).
+  const command = [vbsQuoted('node executable', nodePath), vbsQuoted('supervisor script', supervisorPath),
+    vbsQuoted('descriptor path', descriptorPath)].join(' & " " & ');
+  return `Set shell = CreateObject("WScript.Shell")\r\nshell.Run ${command}, 0, False\r\n`;
+}
+
+function supervisorDescriptor({ bridgePath, pidfile, instanceToken, env }) {
+  const forwarded = { LATTICE_BRIDGE_INSTANCE_TOKEN: instanceToken };
+  if (env.LATTICE_CONFIG_DIR !== undefined) {
+    if (typeof env.LATTICE_CONFIG_DIR !== 'string' || !path.isAbsolute(env.LATTICE_CONFIG_DIR)) {
+      throw fail('BRIDGE_CONFIG_DIR_INVALID', 'LATTICE_CONFIG_DIR must be absolute');
+    }
+    forwarded.LATTICE_CONFIG_DIR = env.LATTICE_CONFIG_DIR;
+  }
+  // Same rationale as the LaunchAgent plist: nothing here inherits the
+  // installer's shell environment at restart time, so registrar settings must
+  // be baked in or self-registration silently never fires after a crash restart.
+  const registrar = bridgeRegistrarSettings(env);
+  if (registrar !== null) {
+    forwarded.LATTICE_BRIDGE_REGISTRAR_SSH_HOST = registrar.host;
+    forwarded.LATTICE_BRIDGE_REGISTRAR_SCRIPT = registrar.script;
+  }
+  return JSON.stringify({ schema: DESCRIPTOR_SCHEMA, bridgePath, pidPath: pidfile, env: forwarded });
+}
+
+export async function defaultStartupRunner(args) {
+  try {
+    const result = await execFileAsync(args[0], args.slice(1), { encoding: 'utf8', windowsHide: true });
+    return { code: 0, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+  } catch (error) {
+    if (Number.isInteger(error?.code)) {
+      return { code: error.code, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };
+    }
+    throw fail('BRIDGE_STARTUP_LAUNCHER_UNAVAILABLE', 'the startup launcher could not be executed', error);
+  }
+}
+
+function healthHost(address) {
+  if (address === '0.0.0.0') return '127.0.0.1';
+  if (address === '::') return '[::1]';
+  return address.includes(':') ? `[${address}]` : address;
+}
+
+async function defaultWaitReady({ config, instanceToken, env, timeoutMs = START_TIMEOUT_MS }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const descriptor = await readBridgeDaemonDescriptor({ env });
+    if (descriptor?.address === config.listen.address && descriptor?.port === config.listen.port
+      && descriptor?.config_updated_at === config.updated_at) {
+      try {
+        const response = await fetch(
+          `http://${healthHost(descriptor.address)}:${descriptor.port}/__lattice/bridge-health`, {
+            headers: { 'x-lattice-bridge-instance-token': instanceToken },
+            signal: AbortSignal.timeout(400),
+          });
+        const body = response.status === 200 ? await response.json() : null;
+        if (body?.schema === 'lattice.bridge_health.v1' && body.pid === descriptor.pid
+          && body.updated_at === config.updated_at) return descriptor;
+      } catch {}
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw fail('BRIDGE_STARTUP_FOLDER_START_FAILED', 'bridge startup process did not become healthy');
+}
+
+async function defaultWaitStopped({ listen, timeoutMs = STOP_TIMEOUT_MS }) {
+  if (listen === null) return;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await fetch(`http://${healthHost(listen.address)}:${listen.port}/__lattice/bridge-health`,
+        { signal: AbortSignal.timeout(300) });
+    } catch { return; }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw fail('BRIDGE_STARTUP_FOLDER_STOP_FAILED', 'bridge startup process socket did not stop');
+}
+
+export async function snapshotBridgeStartupFolder({ env = process.env } = {}) {
+  const refs = bridgeStartupFolderPaths(env);
+  await prepareDirectory(refs.startupDirectory);
+  await prepareDirectory(refs.runtimeDirectory);
+  const launcherContent = await strictFile(refs.launcher);
+  const descriptorContent = await strictFile(refs.descriptor);
+  if ((launcherContent === null) !== (descriptorContent === null)) {
+    throw fail('BRIDGE_STARTUP_FOLDER_STATE_INVALID', 'startup launcher and descriptor disagree on installed state');
+  }
+  return Object.freeze({ installed: launcherContent !== null, launcherContent, descriptorContent });
+}
+
+/** Read the supervisor's own recorded pid and kill its whole process tree
+  * (`taskkill /T /F`) — a forcibly-terminated supervisor cannot clean up its
+  * child itself, so the tree kill is what actually stops the bridge, not the
+  * SIGTERM handler `lattice-bridge.mjs` relies on when Node manages it directly. */
+async function stopRunning({ env, listen, runner, waitStopped }) {
+  const refs = bridgeStartupFolderPaths(env);
+  let pidText;
+  try { pidText = await readFile(refs.pidfile, 'utf8'); } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw fail('BRIDGE_STARTUP_FOLDER_STOP_FAILED', 'could not read supervisor pidfile', error);
+  }
+  const pid = Number(pidText.trim());
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+  const result = await runner(['taskkill.exe', '/T', '/F', '/PID', String(pid)]);
+  // taskkill exits non-zero (128) when the target is already gone — not a failure to report.
+  if (result.code !== 0 && !/not found|not running/iu.test(result.stderr ?? '')) {
+    throw fail('BRIDGE_STARTUP_FOLDER_STOP_FAILED', 'could not stop bridge supervisor process tree');
+  }
+  await waitStopped({ listen, env });
+  await rm(refs.pidfile, { force: true });
+}
+
+export async function installBridgeStartupFolder({ config, env = process.env,
+  runner = defaultStartupRunner, nodePath = process.execPath,
+  bridgePath = path.resolve(import.meta.dirname, '../bin/lattice-bridge.mjs'),
+  supervisorPath = path.resolve(import.meta.dirname, '../bin/lattice-bridge-supervisor.mjs'),
+  waitReady = defaultWaitReady, waitStopped = defaultWaitStopped,
+  previousListen = null } = {}) {
+  if (config?.enabled !== true) throw fail('BRIDGE_DISABLED', 'bridge is disabled');
+  const refs = bridgeStartupFolderPaths(env);
+  await prepareDirectory(refs.startupDirectory);
+  await prepareDirectory(refs.runtimeDirectory);
+  await strictFile(refs.launcher);
+  await strictFile(refs.descriptor);
+  const resolvedNode = await executablePath(nodePath, 'node executable');
+  const resolvedBridge = await executablePath(bridgePath, 'bridge executable');
+  const resolvedSupervisor = await executablePath(supervisorPath, 'supervisor executable');
+  const instanceToken = randomBytes(32).toString('hex');
+  const descriptorContent = supervisorDescriptor({
+    bridgePath: resolvedBridge, pidfile: refs.pidfile, instanceToken, env,
+  });
+  await stopRunning({ env, listen: previousListen, runner, waitStopped });
+  await atomicFile(refs.descriptor, descriptorContent);
+  await atomicFile(refs.launcher,
+    launcherScript({ nodePath: resolvedNode, supervisorPath: resolvedSupervisor, descriptorPath: refs.descriptor }));
+  await launch(runner, ['wscript.exe', refs.launcher], 'BRIDGE_STARTUP_LAUNCHER_FAILED',
+    'could not start the bridge startup process');
+  return waitReady({ config, instanceToken, env });
+}
+
+async function launch(runner, args, code, message) {
+  let result;
+  try { result = await runner(args); } catch (error) {
+    if (error instanceof BridgeConfigError) throw error;
+    throw fail(code, message, error);
+  }
+  if (!result || result.code !== 0) throw fail(code, message);
+  return result;
+}
+
+export async function disableBridgeStartupFolder({ snapshot, listen, env = process.env,
+  runner = defaultStartupRunner, waitStopped = defaultWaitStopped } = {}) {
+  if (!snapshot || typeof snapshot.installed !== 'boolean') {
+    throw new TypeError('bridge startup folder snapshot required');
+  }
+  const refs = bridgeStartupFolderPaths(env);
+  const stopped = snapshot.installed;
+  if (stopped) await stopRunning({ env, listen, runner, waitStopped });
+  await rm(refs.launcher, { force: true });
+  await rm(refs.descriptor, { force: true });
+  return { removed: snapshot.installed, stopped };
+}
+
+export async function restoreBridgeStartupFolder({ snapshot, listen = null, env = process.env,
+  runner = defaultStartupRunner, waitStopped = defaultWaitStopped,
+  config = undefined, waitReady = defaultWaitReady } = {}) {
+  if (!snapshot || typeof snapshot.installed !== 'boolean'
+    || (snapshot.installed
+      && (typeof snapshot.launcherContent !== 'string' || typeof snapshot.descriptorContent !== 'string'))) {
+    throw new TypeError('bridge startup folder snapshot required');
+  }
+  const refs = bridgeStartupFolderPaths(env);
+  await prepareDirectory(refs.startupDirectory);
+  await prepareDirectory(refs.runtimeDirectory);
+  await stopRunning({ env, listen, runner, waitStopped });
+  if (snapshot.installed) {
+    await atomicFile(refs.descriptor, snapshot.descriptorContent);
+    await atomicFile(refs.launcher, snapshot.launcherContent);
+    await launch(runner, ['wscript.exe', refs.launcher], 'BRIDGE_STARTUP_ROLLBACK_FAILED',
+      'could not restore the bridge startup process');
+    const restoredConfig = config ?? await readBridgeConfig({ env });
+    let tokenMatch = null;
+    try { tokenMatch = JSON.parse(snapshot.descriptorContent).env?.LATTICE_BRIDGE_INSTANCE_TOKEN ?? null; }
+    catch { tokenMatch = null; }
+    if (restoredConfig?.enabled !== true || typeof tokenMatch !== 'string' || !/^[0-9a-f]{64}$/u.test(tokenMatch)) {
+      throw fail('BRIDGE_STARTUP_ROLLBACK_FAILED', 'restored bridge startup process is not attestable');
+    }
+    await waitReady({ config: restoredConfig, instanceToken: tokenMatch, env });
+  } else {
+    await rm(refs.launcher, { force: true });
+    await rm(refs.descriptor, { force: true });
+  }
+  return snapshot;
+}

package/src/todo-store-cache.mjs

@@ -0,0 +1,45 @@
+/**
+ * A content-addressed cache in front of `readTodoStoreStable`, for long-running
+ * processes (the dashboard daemon) that re-render on every request/poll and would
+ * otherwise re-validate the whole merged store every time.
+ *
+ * An earlier version keyed the cache on a stat()-derived fingerprint (dev/ino/size/
+ * mtimeMs/ctimeMs). On filesystems with coarse mtime granularity (observed on
+ * WSL/DrvFs), two different manifest contents written close together can land on the
+ * same fingerprint, so the cache would serve a stale store as current — and since the
+ * mismatch never surfaces as an error, nothing invalidates it until the process
+ * restarts. Hashing the manifest's actual bytes costs one small file read and removes
+ * that failure mode entirely.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { readTodoStoreStable } from './todo-store.mjs';
+
+async function manifestContentDigest(manifestRef) {
+  return createHash('sha256').update(await readFile(manifestRef)).digest('hex');
+}
+
+/**
+ * @param {object} [options]
+ * @param {(options: object) => Promise<object>} [options.readStable] injection point for tests
+ */
+export function createTodoStoreCache({ readStable = readTodoStoreStable } = {}) {
+  const cache = new Map();
+  return {
+    async read(repoRoot) {
+      const manifestRef = path.join(repoRoot, '.lattice', 'todo', 'manifest.json');
+      const digest = await manifestContentDigest(manifestRef);
+      const cached = cache.get(repoRoot);
+      if (cached?.digest === digest) return cached.store;
+      // Read before caching: a failure here (including the store's own inconsistency
+      // detection) must not populate the cache, so the very next call re-reads instead
+      // of serving a poisoned entry.
+      const store = await readStable({ repoRoot });
+      cache.set(repoRoot, { digest, store });
+      return store;
+    },
+  };
+}

package/src/todo-store.mjs

@@ -1392,6 +1392,18 @@ export async function readTodoStoreStable(options = {}) {
   if (!Number.isSafeInteger(maximumAttempts) || maximumAttempts < 1 || maximumAttempts > 16) {
     throw new TypeError('maximumAttempts must be 1..16');
   }
+  // `manifest_journal_head_mismatch`/`manifest_plan_binding_mismatch` are treated as a
+  // transient in-flight write and retried. That is correct while a concurrent writer is
+  // mid-commit, but a crashed writer can leave the SAME mismatch permanently — retrying
+  // forever against a manifest that never changes just burns attempts and then reports
+  // a content-free STORE_BUSY, hiding the real STORE_INCONSISTENT reason the caller needs
+  // to actually recover (2026-08-10 P0: a crashed `todo start` left exactly this behind).
+  // Track the manifest digest seen at the START of the previous attempt: if it is
+  // unchanged going into this attempt too, no writer completed anything in between, so
+  // the "transient" classification no longer has evidence behind it — surface the real
+  // error instead of exhausting the budget on a window that was never closing.
+  let previousAttemptManifestDigest = null;
+  let lastError = null;
   for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
     const before = await readArtifact(repoRoot, MANIFEST_REF, {
       code: 'STORE_INCONSISTENT', maxBytes: TODO_LIMITS.snapshotBytes, validate: validateTodoManifest,
@@ -1411,12 +1423,21 @@ export async function readTodoStoreStable(options = {}) {
       const transientWriteWindow = error.code === 'STORE_INCONSISTENT'
         && ['manifest_journal_head_mismatch', 'manifest_plan_binding_mismatch']
           .includes(error.detail.reason);
-      if (before.manifest_digest === after.manifest_digest && !transientWriteWindow) throw error;
+      const stableAcrossAttempts = previousAttemptManifestDigest === before.manifest_digest;
+      if (before.manifest_digest === after.manifest_digest
+        && (!transientWriteWindow || stableAcrossAttempts)) throw error;
+      lastError = error;
     }
+    previousAttemptManifestDigest = before.manifest_digest;
     if (attempt < maximumAttempts) {
       await new Promise((resolve) => setTimeout(resolve, Math.min(16, 2 ** attempt)));
     }
   }
+  // Exhausted without ever observing a genuinely closing write. Surface the last typed
+  // STORE_INCONSISTENT reason rather than a bare STORE_BUSY — the caller (and a human
+  // reading the error) needs to know which store artifact actually disagrees, not just
+  // that reads kept failing.
+  if (lastError !== null) throw lastError;
   fail('STORE_BUSY', 'stable_read_exhausted', { attempts: maximumAttempts });
 }