@quolu/lattice 0.53.1 → 0.55.0

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/docs/bridge-setup.md

@@ -33,6 +33,86 @@ fileを除去し、JSON結果の`recovery`へ処置を明示する。その後
 自動化・隔離testではabsoluteな`LATTICE_CONFIG_DIR`で設定rootを変更できる。無効な設定、低いport、
 使用中の明示port、危険なrequest target、到達不能upstreamはsilent fallbackせずtyped errorを返す。
 
+## 常駐が黙って死んでいないか確かめる
+
+`reachable`は「設定したaddressで誰かが応答しているか」しか答えない。常駐設定（macOSのLaunchAgent、
+WindowsのStartup launcher）が消えたbinaryを指していると、supervisorは起動できないprocessを回し続け、
+どこにもエラーが出ないまま公開面から端末だけが消える。`status`はそれを1回で名指しする。
+
+```bash
+lattice bridge status --json
+```
+
+bridgeが無効な間は以下すべてnullで、bridgeを有効にしている時だけ観測する。
+
+**`persistence`** — 常駐設定が実際に起動する対象。
+
+| field | 意味 |
+| --- | --- |
+| `state` | `installed`／`not_installed`／`unreadable` |
+| `loaded` | launchdへ読み込み済みか。Windowsには対応概念が無いのでnull |
+| `node_path`・`node_exists` | 起動するNode実行体と、それが今も存在するか |
+| `bridge_path`・`bridge_exists` | 起動するbridge scriptと、それが今も存在するか |
+| `error` | `unreadable`のときだけtyped code（例`BRIDGE_LAUNCH_AGENT_PLIST_UNSAFE`） |
+
+**`runtime`** — いま応答しているprocess自身の申告。`state`は`running`／`not_running`／`unattested`／
+`descriptor_invalid`で、`running`以外では各値がnullになる。`running`でも、identityを返さない
+0.55.0より前のdaemonが走っている間は`version`以下がnullになる（この場合`runtime_drift`は空になり、
+乖離の有無は判定できていない——「乖離なし」ではない）。
+
+| field | 意味 |
+| --- | --- |
+| `pid` | 応答しているprocessのpid |
+| `version` | そのprocessが読み込んでいるLatticeの版 |
+| `node_path`・`node_version` | そのprocessを実行しているNodeの実体pathと版 |
+| `bridge_path` | そのprocessが実行しているbridge script |
+
+**`runtime_drift`** — 両者の食い違い。空配列は「差が無い」または「`runtime`が名乗っていないので
+判定できない」のどちらかである。
+
+| 値 | 意味 |
+| --- | --- |
+| `bridge_path` | 常駐設定と違うtreeのcodeが走っている（開発treeの残骸など） |
+| `node_path` | 常駐設定が指すnodeと実走nodeが別実体。焼くのは意図的にaliasなので、比較はrealpathで行う |
+| `version` | npm更新後まだ旧moduleを保持している |
+
+**`remedy`** — 自己解消しない状態にだけ、打つべきコマンドが入る。出るのは次の4つ。
+
+- `persistence.node_exists`または`bridge_exists`がfalse（起動対象が消えた）
+- `persistence.state`が`not_installed`（bridgeは有効なのに常駐設定が無い。いま走っているdaemonが
+  最後の1つで、再起動しても戻らない）
+- `persistence.state`が`unreadable`（常駐設定を読めない）
+- `runtime_drift`に`node_path`または`bridge_path`がある
+
+`version`だけの差には`remedy`を出さない。daemonは60秒ごとにon-diskのpackage.jsonと自分の版を
+突き合わせ、差があれば自ら終了してsupervisorに新codeで起動し直させる。放っておいて最大1分ほどで
+解消するので、コマンドを出す状態ではない。自己解消する差にコマンドを出すと、本物の障害が埋もれる。
+
+`remedy`が出たら`reconfigure`で作り直す。plistやlauncherを手で書き換えない。
+
+```bash
+lattice bridge reconfigure --json
+```
+
+### 焼き込むnode pathの選び方（ADR 0163）
+
+常駐設定へ焼くnodeのpathは、版付きの実体（homebrewの`Cellar/node/<version>/bin/node`、nvm-windowsの
+版ディレクトリ）ではなく、**同じbinaryを指すとrealpathで検証できた安定alias**（`/opt/homebrew/bin/node`、
+`C:\Program Files\nodejs\node.exe`）を選ぶ。`brew upgrade node`が旧versionのディレクトリごと消しても
+起動対象が残るようにするためである。
+
+安定aliasを検証できない環境（shim方式のasdf／volta等。shimは自身のlauncherへ解決されるので実体と
+一致しない）では、版付きpathのまま焼く。検証していないpathを推測で焼けば別のnodeでdaemonが起動して
+しまうためで、そこでの防御は起動継続ではなく`node_exists`による消滅の可視化である。
+
+> **0.55.0より前に設定した常駐は自動では移行しない。** 焼き直しは`reconfigure`を実行した時にだけ
+> 起きるので、Latticeを更新しただけの端末は版付きpathを抱えたままになる。更新後に各端末で
+> `lattice bridge reconfigure --json`を1回打つ。現在どちらを焼いているかは`persistence.node_path`で読める。
+
+なお`setup`／`reconfigure`をnode_modules配下でない実体（開発tree）から実行すると、結果の`warnings`へ
+`BRIDGE_PERSISTED_FROM_DEVELOPMENT_TREE`が入る（該当しなければ空配列）。そのtreeを動かすと常駐が
+止まり、`npm`更新も反映されない。開発treeから常駐させること自体は正当な操作なので拒否はしない。
+
 ## listen IPがDHCPで動く場合
 
 設定したlisten IPがホストから消えると、古いsocketは死んだアドレスへ取り残され、LANから到達できなくなる。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.53.1",
+  "version": "0.55.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

@@ -1,7 +1,9 @@
+import { realpath } from 'node:fs/promises';
 import { createConnection, isIP } from 'node:net';
 import { networkInterfaces } from 'node:os';
 import * as clack from '@clack/prompts';
 
+import packageJson from '../package.json' with { type: 'json' };
 import { resolveBridgeListenAddress } from './bridge-address.mjs';
 import { registerBridgeUpstream } from './bridge-registrar.mjs';
 import {
@@ -10,24 +12,30 @@ import {
 } from './bridge-config.mjs';
 import {
   clearBridgeStopControl, ensureBridgeDaemon, readBridgeDaemonDescriptor,
-  removeBridgeDaemonActiveMarker, removeBridgeDaemonDescriptor, requestBridgeDaemonStop,
-  stopBridgeDaemon,
+  readBridgeRuntimeIdentity, removeBridgeDaemonActiveMarker, removeBridgeDaemonDescriptor,
+  requestBridgeDaemonStop, stopBridgeDaemon,
 } from './bridge-daemon.mjs';
+import { bridgeDevelopmentTreeWarning, DEFAULT_BRIDGE_PATH } from './bridge-executable.mjs';
 import {
-  disableBridgeLaunchAgent, installBridgeLaunchAgent, restoreBridgeLaunchAgent,
-  snapshotBridgeLaunchAgent,
+  describeBridgeLaunchAgent, disableBridgeLaunchAgent, installBridgeLaunchAgent,
+  restoreBridgeLaunchAgent, snapshotBridgeLaunchAgent,
 } from './bridge-launch-agent.mjs';
 import {
-  disableBridgeStartupFolder, installBridgeStartupFolder, restoreBridgeStartupFolder,
-  snapshotBridgeStartupFolder,
+  describeBridgeStartupFolder, 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
 // change take the published surface down while status kept reporting health.
 // v3 adds `hub` (bh3): the terminal's registered bridge-hub, if any.
-const RESULT_SCHEMA = 'lattice.bridge_cli_result.v3';
+// v4 adds `persistence`/`runtime`/`runtime_drift`/`remedy`/`warnings`: the
+// configuration being reachable still said nothing about whether the OS
+// persistence entry points at binaries that exist, or whether the process
+// actually serving is the code and node a restart would bring back.
+const RESULT_SCHEMA = 'lattice.bridge_cli_result.v4';
 const REACHABILITY_PROBE_TIMEOUT_MS = 750;
+const RECONFIGURE_COMMAND = 'lattice bridge reconfigure --json';
 
 /** TCP connect probe. Answers "is anything accepting there right now". */
 export function probeBridgeListener({ address, port, timeoutMs = REACHABILITY_PROBE_TIMEOUT_MS }) {
@@ -80,10 +88,86 @@ async function bridgeLiveness(config, { interfaces = networkInterfaces(), probe
 function platformLaunchAgent() {
   if (process.platform === 'win32') {
     return { snapshot: snapshotBridgeStartupFolder, install: installBridgeStartupFolder,
-      disable: disableBridgeStartupFolder, restore: restoreBridgeStartupFolder };
+      disable: disableBridgeStartupFolder, restore: restoreBridgeStartupFolder,
+      describe: describeBridgeStartupFolder };
   }
   return { snapshot: snapshotBridgeLaunchAgent, install: installBridgeLaunchAgent,
-    disable: disableBridgeLaunchAgent, restore: restoreBridgeLaunchAgent };
+    disable: disableBridgeLaunchAgent, restore: restoreBridgeLaunchAgent,
+    describe: describeBridgeLaunchAgent };
+}
+
+const UNREADABLE_PERSISTENCE = Object.freeze({ loaded: null, node_path: null, node_exists: false,
+  bridge_path: null, bridge_exists: false });
+
+/**
+ * What the OS persistence entry (LaunchAgent plist, Windows Startup launcher)
+ * actually points at, and whether those paths still exist. A read failure is
+ * reported as `unreadable` rather than thrown: this is a diagnostic, and it
+ * is worth least on exactly the broken hosts where it would otherwise abort.
+ */
+async function bridgePersistence({ launchAgent, env }) {
+  try {
+    const snapshot = await launchAgent.snapshot({ env });
+    const described = await launchAgent.describe({ snapshot, env });
+    // `loaded` is launchd-specific; the Windows Startup folder has no such
+    // concept and reports null rather than pretending to know.
+    const loaded = typeof snapshot?.loaded === 'boolean' ? snapshot.loaded : null;
+    if (described === null) return { state: 'not_installed', ...UNREADABLE_PERSISTENCE, loaded, error: null };
+    return { state: 'installed', loaded, ...described, error: null };
+  } catch (error) {
+    // Only environment failures degrade into a report: typed BridgeConfigErrors
+    // and raw fs errnos both carry a string `code`. Anything else is a defect in
+    // this codebase (a missing describe implementation, a bad argument) and must
+    // surface as itself rather than be laundered into "unreadable".
+    if (typeof error?.code !== 'string') throw error;
+    return { state: 'unreadable', ...UNREADABLE_PERSISTENCE, error: error.code };
+  }
+}
+
+/**
+ * Where the running process disagrees with what a restart would produce.
+ * `node_path` is compared through realpath because the persisted path is
+ * deliberately a stable alias (see bridge-executable.mjs) — the strings are
+ * expected to differ; the binaries behind them are not.
+ */
+async function bridgeRuntimeDrift(persistence, runtime) {
+  if (persistence?.state !== 'installed' || runtime?.state !== 'running') return [];
+  const drift = [];
+  if (runtime.bridge_path !== null && persistence.bridge_path !== null
+    && runtime.bridge_path !== persistence.bridge_path) drift.push('bridge_path');
+  if (runtime.node_path !== null && persistence.node_path !== null) {
+    const target = await realpath(persistence.node_path).catch(() => null);
+    if (target !== null && target !== runtime.node_path) drift.push('node_path');
+  }
+  if (runtime.version !== null && runtime.version !== packageJson.version) drift.push('version');
+  return drift;
+}
+
+/**
+ * `version` drift alone carries no remedy on purpose: the daemon polls its own
+ * on-disk package version and exits for the supervisor to relaunch on the new
+ * code (see bridgeDaemonVersionDrifted), so it resolves itself within a minute.
+ * Everything else here outlives the current process: a missing binary, a
+ * mismatched path, or an enabled bridge with no persistence entry at all all
+ * survive until someone reinstalls the entry.
+ */
+function bridgeRemedy(persistence, drift) {
+  if (persistence === null) return null;
+  if (persistence.state === 'unreadable') return RECONFIGURE_COMMAND;
+  // Only reached with the bridge enabled, so "nothing is installed" means the
+  // currently-serving daemon is the last one: nothing brings it back at reboot.
+  if (persistence.state === 'not_installed') return RECONFIGURE_COMMAND;
+  if (persistence.state === 'installed'
+    && (!persistence.node_exists || !persistence.bridge_exists)) return RECONFIGURE_COMMAND;
+  return drift.includes('node_path') || drift.includes('bridge_path') ? RECONFIGURE_COMMAND : null;
+}
+
+async function bridgeDiagnostics({ config, launchAgent, env, runtimeIdentity }) {
+  if (config?.enabled !== true) return null;
+  const persistence = await bridgePersistence({ launchAgent, env });
+  const runtime = await runtimeIdentity({ env });
+  const drift = await bridgeRuntimeDrift(persistence, runtime);
+  return { persistence, runtime, drift, remedy: bridgeRemedy(persistence, drift) };
 }
 
 function fail(stderr, code, message) {
@@ -121,7 +205,7 @@ function parseOptions(words) {
   return options;
 }
 
-function result(action, config, recovery = null, liveness = null) {
+function result(action, config, recovery = null, liveness = null, diagnostics = null, warnings = null) {
   return { schema: RESULT_SCHEMA, action, configured: config !== null, enabled: config?.enabled ?? false,
     listen: config?.listen ?? null, allowed_hosts: config?.allowed_hosts ?? null,
     upstream: config?.upstream ?? null, hub: config?.hub ?? null, updated_at: config?.updated_at ?? null, recovery,
@@ -129,7 +213,12 @@ function result(action, config, recovery = null, liveness = null) {
     effective_listen: liveness?.effective_listen ?? null,
     listen_candidates: liveness?.listen_candidates ?? null,
     reachable: liveness?.reachable ?? null,
-    liveness_reason: liveness?.liveness_reason ?? null };
+    liveness_reason: liveness?.liveness_reason ?? null,
+    persistence: diagnostics?.persistence ?? null,
+    runtime: diagnostics?.runtime ?? null,
+    runtime_drift: diagnostics?.drift ?? null,
+    remedy: diagnostics?.remedy ?? null,
+    warnings };
 }
 
 export async function collectBridgeSetupWizard({ input, output, prompts = clack } = {}) {
@@ -180,7 +269,8 @@ 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 = platformLaunchAgent(),
+  launchAgent = platformLaunchAgent(), runtimeIdentity = readBridgeRuntimeIdentity,
+  bridgePath = DEFAULT_BRIDGE_PATH,
   prompts = clack, probe = probeBridgeListener, interfaces = networkInterfaces() } = {}) {
   if (!Array.isArray(argv)) {
     return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable|register> [options] --json');
@@ -308,11 +398,21 @@ export async function runBridgeCli({ argv, stdout, stderr, env = process.env,
         return configured;
       });
     } else return fail(stderr, 'USAGE', 'unknown bridge command or options');
-    // Liveness is only meaningful for a read: the mutating commands have just
-    // reconfigured the daemon and the socket may not have settled yet.
+    // Liveness and the persistence/runtime diagnostics are only meaningful for
+    // a read: the mutating commands have just reconfigured the daemon and the
+    // socket may not have settled yet.
     const liveness = command === 'status' ? await bridgeLiveness(config, { probe, interfaces }) : null;
-    if (wizard) stdout.write(`Lattice bridgeを${config.listen.address}:${config.listen.port}で有効にしました。\n`);
-    else stdout.write(`${JSON.stringify(result(command, config, recovery, liveness))}\n`);
+    const diagnostics = command === 'status'
+      ? await bridgeDiagnostics({ config, launchAgent, env, runtimeIdentity }) : null;
+    // An install persisted straight out of a checkout is legitimate but must
+    // never be silent — it is half of what made the 2026-08-10 outage take
+    // manual launchctl archaeology to explain.
+    const warnings = command === 'setup' || command === 'reconfigure'
+      ? [bridgeDevelopmentTreeWarning(bridgePath)].filter((warning) => warning !== null) : null;
+    if (wizard) {
+      stdout.write(`Lattice bridgeを${config.listen.address}:${config.listen.port}で有効にしました。\n`);
+      for (const warning of warnings ?? []) stdout.write(`警告: ${warning.message}\n`);
+    } else stdout.write(`${JSON.stringify(result(command, config, recovery, liveness, diagnostics, warnings))}\n`);
     return 0;
   } catch (error) {
     stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2',

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;
@@ -305,6 +306,33 @@ async function attest(descriptor) {
   } catch { return null; }
 }
 
+const UNIDENTIFIED_RUNTIME = Object.freeze({ pid: null, version: null, node_path: null,
+  node_version: null, bridge_path: null });
+
+/**
+ * Who is actually serving right now — pid, product version, node binary — as
+ * reported by the running process itself over its attested health endpoint,
+ * not as recorded by any file. This is the only way to see that a daemon is
+ * executing code or a node binary that no longer matches what a restart would
+ * pick up. A malformed descriptor is reported as its own state rather than
+ * thrown: this feeds `lattice bridge status`, the command an operator reaches
+ * for precisely when something is already broken.
+ */
+export async function readBridgeRuntimeIdentity({ env = process.env } = {}) {
+  let descriptor;
+  try { descriptor = await readBridgeDaemonDescriptor({ env }); } catch (error) {
+    if (error?.code !== 'BRIDGE_DAEMON_DESCRIPTOR_INVALID') throw error;
+    return { ...UNIDENTIFIED_RUNTIME, state: 'descriptor_invalid' };
+  }
+  if (descriptor === null) return { ...UNIDENTIFIED_RUNTIME, state: 'not_running' };
+  const body = await attest(descriptor);
+  if (body === null) return { ...UNIDENTIFIED_RUNTIME, state: 'unattested', pid: descriptor.pid };
+  const text = (value) => (typeof value === 'string' ? value : null);
+  return { state: 'running', pid: descriptor.pid, version: text(body.version),
+    node_path: text(body.node_path), node_version: text(body.node_version),
+    bridge_path: text(body.bridge_path) };
+}
+
 async function healthy(descriptor, config) {
   if (descriptor === null || descriptor.address !== config.listen.address
     || descriptor.port !== config.listen.port) return false;
@@ -379,3 +407,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-executable.mjs

@@ -0,0 +1,100 @@
+/**
+ * What gets baked into the OS persistence surfaces (the macOS LaunchAgent
+ * plist, the Windows Startup launcher) as the Node executable — and how a
+ * bridge installed out of a development tree is called out at setup time.
+ *
+ * `process.execPath` is already realpath-resolved by libuv, so under Homebrew
+ * it reads `/opt/homebrew/Cellar/node/<version>/bin/node` even when node was
+ * invoked through `/opt/homebrew/bin/node`. Baking that version-pinned path
+ * into a LaunchAgent makes `brew upgrade node` delete the very binary launchd
+ * is told to exec: KeepAlive then respins a process that can never start, and
+ * nothing anywhere reports it — the terminal just disappears from the
+ * published view (hit on this Mac 2026-08-08 and again 2026-08-10).
+ *
+ * So we bake a stable alias whenever one demonstrably resolves to the same
+ * binary. The test is deliberately narrow — `realpath(candidate)` equals the
+ * already-validated `resolved` path, and nothing else. In particular we do
+ * NOT additionally require the candidate's parent directories to be free of
+ * group write: the standard Homebrew prefix (`/opt/homebrew/bin`, drwxrwxr-x)
+ * fails that check, so the rule would refuse to fire in exactly the
+ * environment it exists for. Nor would it buy anything — the Cellar path we
+ * bake today sits under an equally group-writable `/opt/homebrew/Cellar`, so
+ * the set of principals who can swap the binary is identical either way. The
+ * binary itself is still checked (owner, mode, exec bit) by the caller before
+ * any of this runs.
+ *
+ * Shim-based version managers (asdf, volta) resolve to their own launcher
+ * rather than to the node binary, so they never match and we keep the
+ * resolved path. That is the honest outcome: we never bake a path we could
+ * not verify, and `lattice bridge status` reports what the persistence
+ * surface actually points at, so a version-pinned path is visible before it
+ * dies rather than silent after.
+ */
+
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_BRIDGE_PATH = path.resolve(import.meta.dirname, '../bin/lattice-bridge.mjs');
+export const DEFAULT_SUPERVISOR_PATH =
+  path.resolve(import.meta.dirname, '../bin/lattice-bridge-supervisor.mjs');
+
+// Directories that hold a stable `node` on a default install of the platform's
+// usual package manager. They are appended to (not substituted for) whatever
+// PATH the installing shell had, because launchd and the Windows Startup
+// folder inherit no PATH at all — the candidate has to come from here.
+const WELL_KNOWN_DIRECTORIES = {
+  darwin: ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin'],
+  win32: ['C:\\Program Files\\nodejs'],
+  other: ['/usr/local/bin', '/usr/bin'],
+};
+
+function candidateDirectories(env, platform) {
+  const raw = typeof env.PATH === 'string' ? env.PATH
+    : typeof env.Path === 'string' ? env.Path : '';
+  const fromPath = raw.split(platform === 'win32' ? ';' : ':')
+    .filter((entry) => entry !== '' && path.isAbsolute(entry));
+  const wellKnown = WELL_KNOWN_DIRECTORIES[platform] ?? WELL_KNOWN_DIRECTORIES.other;
+  return [...new Set([...fromPath, ...wellKnown])];
+}
+
+function samePath(left, right, platform) {
+  return platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+/**
+ * The path to bake for a node executable whose real location is `resolved`:
+ * the first candidate alias that resolves to exactly that binary, or
+ * `resolved` itself when no alias can be verified.
+ */
+export async function stableNodePath({ resolved, env = process.env,
+  platform = process.platform } = {}) {
+  if (typeof resolved !== 'string' || !path.isAbsolute(resolved)) {
+    throw new TypeError('resolved node executable path required');
+  }
+  const name = platform === 'win32' ? 'node.exe' : 'node';
+  for (const directory of candidateDirectories(env, platform)) {
+    const candidate = path.join(directory, name);
+    if (samePath(candidate, resolved, platform)) continue;
+    let target;
+    try { target = await realpath(candidate); } catch { continue; }
+    if (samePath(target, resolved, platform)) return candidate;
+  }
+  return resolved;
+}
+
+/**
+ * A bridge script outside any `node_modules` is being persisted straight out
+ * of a checkout: the daemon then survives every `npm update` unchanged, and
+ * dies for good if the tree is moved or deleted. Not an error — installing
+ * from a development tree is a legitimate thing to do deliberately — but it
+ * must not happen without the operator being told.
+ */
+export function bridgeDevelopmentTreeWarning(bridgePath) {
+  if (typeof bridgePath !== 'string') return null;
+  if (bridgePath.split(/[\\/]/u).includes('node_modules')) return null;
+  return {
+    code: 'BRIDGE_PERSISTED_FROM_DEVELOPMENT_TREE',
+    message: `the bridge is persisted from a development tree (${bridgePath}); `
+      + 'it will not follow npm updates and stops for good if that tree moves',
+  };
+}

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

@@ -523,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-launch-agent.mjs

@@ -2,13 +2,14 @@ import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
 import {
-  chmod, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile,
+  chmod, lstat, mkdir, open, realpath, rename, rm, stat, 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 { DEFAULT_BRIDGE_PATH, stableNodePath } from './bridge-executable.mjs';
 import { bridgeRegistrarSettings } from './bridge-registrar.mjs';
 
 export const BRIDGE_LAUNCH_AGENT_LABEL = 'dev.kitepon.lattice.bridge';
@@ -252,6 +253,40 @@ export async function snapshotBridgeLaunchAgent({ env = process.env,
   return Object.freeze({ installed: content !== null, loaded, content });
 }
 
+const PROGRAM_ARGUMENTS_PATTERN =
+  /<key>ProgramArguments<\/key>\s*<array>\s*<string>([^<]*)<\/string>\s*<string>([^<]*)<\/string>\s*<\/array>/u;
+
+/** Inverse of `xml`, innermost-last so an escaped `&amp;lt;` survives intact. */
+function unxml(value) {
+  return value.replaceAll('&apos;', "'").replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>').replaceAll('&lt;', '<').replaceAll('&amp;', '&');
+}
+
+async function pathPresent(ref) {
+  if (typeof ref !== 'string') return false;
+  try { await stat(ref); return true; } catch { return false; }
+}
+
+/**
+ * What the installed plist actually tells launchd to run, and whether those
+ * paths still exist. A LaunchAgent whose ProgramArguments point at a deleted
+ * binary is the product's worst failure mode: KeepAlive keeps respinning it,
+ * nothing logs, and the only visible symptom is a terminal missing from the
+ * published view. Reporting it here is what turns that into an answer
+ * `lattice bridge status` can give in one call.
+ */
+export async function describeBridgeLaunchAgent({ snapshot } = {}) {
+  if (snapshot?.installed !== true) return null;
+  const match = typeof snapshot.content === 'string'
+    ? snapshot.content.match(PROGRAM_ARGUMENTS_PATTERN) : null;
+  const nodePath = match === null ? null : unxml(match[1]);
+  const bridgePath = match === null ? null : unxml(match[2]);
+  return {
+    node_path: nodePath, node_exists: await pathPresent(nodePath),
+    bridge_path: bridgePath, bridge_exists: await pathPresent(bridgePath),
+  };
+}
+
 async function bootoutIfLoaded({ runner, uid }) {
   if (!await loadedState(runner, uid)) return false;
   await launchctl(runner, ['bootout', service(uid)], 'BRIDGE_LAUNCHCTL_BOOTOUT_FAILED',
@@ -261,17 +296,22 @@ async function bootoutIfLoaded({ runner, uid }) {
 
 export async function installBridgeLaunchAgent({ config, env = process.env,
   runner = defaultLaunchctlRunner, uid = userId(), nodePath = process.execPath,
-  bridgePath = path.resolve(import.meta.dirname, '../bin/lattice-bridge.mjs'),
+  bridgePath = DEFAULT_BRIDGE_PATH,
   waitReady = defaultWaitReady, waitStopped = defaultWaitStopped,
-  previousListen = null } = {}) {
+  stableNode = stableNodePath, previousListen = null } = {}) {
   if (config?.enabled !== true) throw fail('BRIDGE_DISABLED', 'bridge is disabled');
   const refs = bridgeLaunchAgentPaths(env);
   await prepareDirectory(refs.directory, uid);
   await strictPlist(refs.plist, uid);
+  // The safety checks run against the real binary; what goes into the plist is
+  // a stable alias for it when one can be verified, so a version-manager
+  // upgrade cannot delete the path launchd was told to exec. See
+  // bridge-executable.mjs for why the alias is not additionally permission-checked.
   const resolvedNode = await executablePath(nodePath, 'node executable', { uid });
+  const bakedNode = await stableNode({ resolved: resolvedNode, env });
   const resolvedBridge = await executablePath(bridgePath, 'bridge executable', { executable: false, uid });
   const instanceToken = randomBytes(32).toString('hex');
-  const content = plistDocument({ nodePath: resolvedNode, bridgePath: resolvedBridge, instanceToken, env });
+  const content = plistDocument({ nodePath: bakedNode, bridgePath: resolvedBridge, instanceToken, env });
   const stopped = await bootoutIfLoaded({ runner, uid });
   if (stopped) await waitStopped({ listen: previousListen, env });
   await atomicPlist(refs.plist, content);

package/src/bridge-server.mjs

@@ -7,6 +7,7 @@ import { parseTree } from 'jsonc-parser';
 
 import { networkInterfaces } from 'node:os';
 
+import packageJson from '../package.json' with { type: 'json' };
 import { resolveBridgeListenAddress } from './bridge-address.mjs';
 import { registerBridgeUpstream } from './bridge-registrar.mjs';
 import {
@@ -228,10 +229,18 @@ export async function startBridgeServer({
       response.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
       const attested = typeof instanceToken === 'string'
         && incoming.headers['x-lattice-bridge-instance-token'] === instanceToken;
+      // The identity fields answer "what is actually running right now", which
+      // no descriptor can: the descriptor records what was configured, while a
+      // daemon can outlive an npm update or keep executing a node binary its
+      // own persistence entry no longer points at. Attested callers only —
+      // these are local filesystem paths and must not leak to the public
+      // availability probe.
       response.end(`${JSON.stringify(attested
         ? { schema: 'lattice.bridge_health.v1', pid: process.pid,
           address: currentConfig.listen.address, port: currentConfig.listen.port,
-          updated_at: currentConfig.updated_at ?? null }
+          updated_at: currentConfig.updated_at ?? null,
+          version: packageJson.version, node_path: process.execPath,
+          node_version: process.version, bridge_path: process.argv[1] ?? null }
         : { schema: 'lattice.bridge_health.v1', status: 'available' })}\n`);
       return;
     }

package/src/bridge-startup-folder.mjs

@@ -32,13 +32,16 @@ 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,
+  lstat, mkdir, open, readFile, realpath, rename, rm, stat, 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 {
+  DEFAULT_BRIDGE_PATH, DEFAULT_SUPERVISOR_PATH, stableNodePath,
+} from './bridge-executable.mjs';
 import { bridgeRegistrarSettings } from './bridge-registrar.mjs';
 
 export const BRIDGE_STARTUP_LABEL = 'LatticeBridge';
@@ -242,6 +245,33 @@ export async function snapshotBridgeStartupFolder({ env = process.env } = {}) {
   return Object.freeze({ installed: launcherContent !== null, launcherContent, descriptorContent });
 }
 
+async function pathPresent(ref) {
+  if (typeof ref !== 'string') return false;
+  try { await stat(ref); return true; } catch { return false; }
+}
+
+/**
+ * The Windows counterpart of `describeBridgeLaunchAgent`, reporting the same
+ * shape: what the persisted launcher runs and whether it is still there. The
+ * node path comes from the `.vbs` (first triple-quoted argument), the bridge
+ * script from the supervisor descriptor that owns it.
+ */
+export async function describeBridgeStartupFolder({ snapshot } = {}) {
+  if (snapshot?.installed !== true) return null;
+  const quoted = typeof snapshot.launcherContent === 'string'
+    ? [...snapshot.launcherContent.matchAll(/"""([^"]*)"""/gu)].map((match) => match[1]) : [];
+  const nodePath = quoted.length > 0 ? quoted[0] : null;
+  let bridgePath = null;
+  try {
+    const parsed = JSON.parse(snapshot.descriptorContent);
+    if (typeof parsed?.bridgePath === 'string') bridgePath = parsed.bridgePath;
+  } catch {}
+  return {
+    node_path: nodePath, node_exists: await pathPresent(nodePath),
+    bridge_path: bridgePath, bridge_exists: await pathPresent(bridgePath),
+  };
+}
+
 /** 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
@@ -266,17 +296,21 @@ async function stopRunning({ env, listen, runner, waitStopped }) {
 
 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'),
+  bridgePath = DEFAULT_BRIDGE_PATH, supervisorPath = DEFAULT_SUPERVISOR_PATH,
   waitReady = defaultWaitReady, waitStopped = defaultWaitStopped,
-  previousListen = null } = {}) {
+  stableNode = stableNodePath, 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);
+  // Same reasoning as the LaunchAgent: validate the real binary, bake a
+  // verified stable alias for it. nvm-windows swaps the version behind the
+  // `C:\Program Files\nodejs` junction exactly the way Homebrew swaps the
+  // Cellar directory behind `/opt/homebrew/bin/node`.
   const resolvedNode = await executablePath(nodePath, 'node executable');
+  const bakedNode = await stableNode({ resolved: resolvedNode, env });
   const resolvedBridge = await executablePath(bridgePath, 'bridge executable');
   const resolvedSupervisor = await executablePath(supervisorPath, 'supervisor executable');
   const instanceToken = randomBytes(32).toString('hex');
@@ -286,7 +320,7 @@ export async function installBridgeStartupFolder({ config, env = process.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 }));
+    launcherScript({ nodePath: bakedNode, 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 });

package/src/runtime-work-order-controller.mjs

@@ -348,8 +348,15 @@ async function observeWorkerProcessTree(pid, { requireDescendantsInRootGroup = t
       rawState: match[4],
       startedIdentity: match[5].trim(),
     };
-    if (![record.pid, record.processGroupId].every((value) => Number.isSafeInteger(value)
-      && value > 0) || !Number.isSafeInteger(record.parentPid) || record.parentPid < 0
+    // processGroupIdは0を許す: Linuxのkernel thread（pid 2 kthreaddとその子）は
+    // 実在するがユーザー空間のprocess groupに属さないためpgid=0を持つ——実機の`ps -axo`は
+    // これを常に含むので、pid>0の一律要求ではこの関数が動くたびに毎回fail closedしていた
+    // （2026-08-10、CIのubuntu-latestで再現・確認）。0は安全側にも効く: 実workerのroot
+    // process groupは常にpid>0のleaderが持つ実PIDなので、pgid=0のrecordは下の
+    // 「同じprocess groupを共有する無関係processが無いか」の照合に決して誤って一致しない。
+    if (!Number.isSafeInteger(record.pid) || record.pid <= 0
+      || !Number.isSafeInteger(record.processGroupId) || record.processGroupId < 0
+      || !Number.isSafeInteger(record.parentPid) || record.parentPid < 0
       || record.startedIdentity.length === 0 || records.has(record.pid)) {
       fail('WORK_ORDER_REPORT_INVALID', 'ps process recordが不正');
     }

package/src/todo-cli.mjs

@@ -183,6 +183,29 @@ function typedFailure(stderr, error) {
   return 1;
 }
 
+/**
+ * An error that reached here is, by definition, one none of the typed
+ * TodoStoreError/TypeError branches recognized — the one case where the
+ * caller most needs to know *what actually happened*. Collapsing it to just
+ * the constructor name (`{code:'INTERNAL_FAILURE',message:'Error'}`) was
+ * itself a diagnosability defect: a crashed `todo start` produced exactly
+ * that content-free payload, and the only way to find the real cause
+ * (`manifest_journal_head_mismatch`) was importing todo-store.mjs directly
+ * and calling readTodoStore() by hand (2026-08-10 P0). The actual message
+ * and a short stack excerpt cost nothing to include — this is a local CLI's
+ * own stderr, not a response surface with an untrusted audience.
+ */
+function internalFailure(stderr, error) {
+  const constructorName = error?.constructor?.name ?? 'Error';
+  const message = typeof error?.message === 'string' && error.message.length > 0
+    ? error.message : constructorName;
+  const detail = { error_name: constructorName };
+  if (typeof error?.stack === 'string' && error.stack.length > 0) {
+    detail.stack_excerpt = error.stack.split('\n').slice(0, 6).join('\n');
+  }
+  return typedFailure(stderr, { code: 'INTERNAL_FAILURE', message, detail });
+}
+
 const TODO_COMMAND_NAMES = Object.freeze([
   'status', 'show', 'note', 'bindings', 'independence', 'seam-profile', 'seam-proposal',
   'verify', 'snapshot', 'gantt', 'dashboard', 'phase', 'migrate', 'start', 'block',
@@ -2811,9 +2834,7 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
       await runTodoSchemaCommand(argv[0], stdout);
       return 0;
     } catch (error) {
-      return typedFailure(stderr, {
-        code: 'INTERNAL_FAILURE', message: error?.constructor?.name ?? 'Error',
-      });
+      return internalFailure(stderr, error);
     }
   }
 
@@ -2835,9 +2856,7 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     } catch (error) {
       if (typeof error?.code === 'string' && error.detail !== null
         && typeof error.detail === 'object') return typedFailure(stderr, error);
-      return typedFailure(stderr, {
-        code: 'INTERNAL_FAILURE', message: error?.constructor?.name ?? 'Error',
-      });
+      return internalFailure(stderr, error);
     }
   }
 
@@ -3118,7 +3137,18 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     const ganttCommand = argv[0] === 'gantt';
     const dashboardAdopt = argv[0] === 'dashboard' && argv[1] === 'adopt';
     const migrationDryRun = argv[0] === 'migrate' && argv.includes('--dry-run');
-    if (!ganttCommand && !dashboardAdopt && !migrationDryRun) {
+    // `verify` is the store's own read-only recovery diagnostic — the command
+    // an operator reaches for precisely when the store might be inconsistent.
+    // ensureActiveProjectDashboard calls readTodoStoreStable for an unrelated
+    // side effect (registering this session as an active dashboard project),
+    // and readTodoStoreStable retries a persistent STORE_INCONSISTENT as if it
+    // were a transient in-flight write before giving up and reporting a
+    // content-free STORE_BUSY. Running that pre-hook ahead of `verify` meant
+    // the one command meant to surface the real inconsistency never got to —
+    // it died in the same generic way every other command did (2026-08-10 P0:
+    // `todo verify` was unreachable for the exact case it exists to diagnose).
+    const verifyCommand = argv[0] === 'verify';
+    if (!ganttCommand && !dashboardAdopt && !migrationDryRun && !verifyCommand) {
       await ensureActiveProjectDashboard({ repoRoot, env });
     }
     const result = atomicCommit
@@ -3135,9 +3165,6 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
         message: error.message,
       });
     }
-    return typedFailure(stderr, {
-      code: 'INTERNAL_FAILURE',
-      message: error?.constructor?.name ?? 'Error',
-    });
+    return internalFailure(stderr, error);
   }
 }

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 });
 }