@quolu/lattice 0.57.0 → 0.57.2

package/bin/lattice-bridge.mjs

@@ -140,12 +140,15 @@ timer = setInterval(async () => {
     // the terminal identity file) reaches this catch.
     try {
       const heartbeat = await hubHeartbeat.tick({ config });
-      hubHeartbeatError = null;
+      // 直前に書いた指紋は、健全な状態へ戻った時にだけ捨てる。判定より前に捨てると
+      // 比較相手が毎周期nullになり、同じ結果をpoll周期ごとに書き続ける。stderrの
+      // 消費者が居ない常駐（WindowsのStartup launcher、LaunchAgent）では、この
+      // 書込みが積み上がること自体が常駐を不安定にする。
       if (['unreachable', 'rejected', 'partial'].includes(heartbeat?.state)) {
         const fingerprint = JSON.stringify(heartbeat);
         if (fingerprint !== hubHeartbeatError) process.stderr.write(`${fingerprint}\n`);
         hubHeartbeatError = fingerprint;
-      }
+      } else hubHeartbeatError = null;
     } catch (error) {
       const failure = { schema: 'lattice.bridge_daemon_error.v1',
         code: error?.code ?? 'BRIDGE_HUB_HEARTBEAT_FAILED',

package/docs/bridge-setup.md

@@ -54,6 +54,11 @@ bridgeが無効な間は以下すべてnullで、bridgeを有効にしている
 | `node_path`・`node_exists` | 起動するNode実行体と、それが今も存在するか |
 | `bridge_path`・`bridge_exists` | 起動するbridge scriptと、それが今も存在するか |
 | `error` | `unreadable`のときだけtyped code（例`BRIDGE_LAUNCH_AGENT_PLIST_UNSAFE`） |
+| `error=BRIDGE_PERSISTENCE_STATE_SPLIT` | launcherまたはplistの片割れだけが残った状態。手でfileを消さず、`lattice bridge reconfigure --json`で常駐設定を揃える（0.57.2以降） |
+
+`BRIDGE_PERSISTENCE_STATE_SPLIT`は、常駐設定の一方（macOSのplist、またはWindowsのlauncher／descriptor）だけが
+存在することを示す。これは復旧対象そのものが壊れている状態なので、手作業でfileを削除せず、
+`lattice bridge reconfigure --json`を実行して正規のinstall経路で両方を再生成する。
 
 **`runtime`** — いま応答しているprocess自身の申告。`state`は`running`／`not_running`／`unattested`／
 `descriptor_invalid`で、`running`以外では各値がnullになる。`running`でも、identityを返さない
@@ -98,6 +103,24 @@ bridgeが無効な間は以下すべてnullで、bridgeを有効にしている
 lattice bridge reconfigure --json
 ```
 
+### 公開面から自分のprojectが消えた時（`last_heartbeat`）
+
+hubへ繋いでいる端末では、`runtime.last_heartbeat`が最後にhubへ名乗った結果を持つ。公開一覧で
+自分のprojectがofflineになっている時、原因が端末側か配線側かはここで分かれる。
+
+| `state` | 意味 | 打つ手 |
+| --- | --- | --- |
+| `accepted` | 全件受理された。公開面に出ていないならhub側の可視性設定を見る | — |
+| `partial` | 一部が他の生きた端末に所有されている。`rejected_projects`が名指しする | 意図した端末なら放置。奪うなら`adopt` |
+| `rejected` | hubがrequest全体を拒否した。`detail`にtyped code | detailのcodeで分岐 |
+| `unreachable` | hubへ届かない。配線かhubの停止 | hubのURLと生死を確認 |
+| `skipped_no_projects` | 配信しているprojectが0件。名乗るものが無い | 正常な静止。公開したいならそのrepoで作業する |
+| `skipped_no_dashboard` | dashboard daemonを観測できない。配信そのものが立っていない | daemonの生死を見る。`todo`系commandを1回打てば起動する |
+| `null` | hub未設定、またはまだ1回も送っていない | — |
+
+名乗る集合はdaemonが実際に配信している集合そのもの（ADR 0165）。登録簿の`last_seen_at`が古い
+ことは露出に影響しない——**人がCLIを叩かなくなっただけで公開面から消えることはない**。
+
 ### 焼き込むnode pathの選び方（ADR 0163）
 
 常駐設定へ焼くnodeのpathは、版付きの実体（homebrewの`Cellar/node/<version>/bin/node`、nvm-windowsの

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.57.0",
+  "version": "0.57.2",
   "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-cli.mjs

@@ -112,6 +112,10 @@ async function bridgePersistence({ launchAgent, 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 (snapshot?.split === true) {
+      return { state: 'unreadable', ...UNREADABLE_PERSISTENCE, loaded,
+        error: 'BRIDGE_PERSISTENCE_STATE_SPLIT' };
+    }
     if (described === null) return { state: 'not_installed', ...UNREADABLE_PERSISTENCE, loaded, error: null };
     return { state: 'installed', loaded, ...described, error: null };
   } catch (error) {

package/src/bridge-hub-heartbeat.mjs

@@ -2,8 +2,9 @@
  * Terminal-side bridge-hub heartbeat client (bh3).
  *
  * Wires the pure wire contract in `bridge-hub-protocol.mjs` (bh1) around this
- * terminal's own state: a persisted terminal identity, the locally active
- * project set (`todo-dashboard-registry.mjs`), and the configured hub origin
+ * terminal's own state: a persisted terminal identity, the project set this
+ * terminal is actually serving (asked of the dashboard daemon itself, ADR
+ * 0165), and the configured hub origin
  * (`bridge-config.mjs`'s `hub` field). It sends `POST /__lattice/hub/register`
  * on `bridge-hub-server.mjs`'s (bh2) contract — the request body is the raw
  * `lattice.bridge_hub_registration_request.v1` object, unmodified in transit.
@@ -21,7 +22,7 @@ import path from 'node:path';
 
 import { bridgeConfigPaths } from './bridge-config.mjs';
 import { BRIDGE_HUB_HEARTBEAT_INTERVAL_MS, validateBridgeHubRegistrationRequest } from './bridge-hub-protocol.mjs';
-import { readActiveTodoDashboardProjects } from './todo-dashboard-registry.mjs';
+import { readServedTodoDashboardProjectIds } from './todo-dashboard-registry.mjs';
 
 export { BRIDGE_HUB_HEARTBEAT_INTERVAL_MS };
 
@@ -180,7 +181,7 @@ export function bridgeHubHeartbeatSummary(result, at = null) {
 export function createBridgeHubHeartbeatController({
   env = process.env, fetchImpl = fetch, now = () => Date.now(),
   intervalMs = BRIDGE_HUB_HEARTBEAT_INTERVAL_MS,
-  readActiveProjects = readActiveTodoDashboardProjects,
+  readServedProjectIds = readServedTodoDashboardProjectIds,
 } = {}) {
   let lastSentAt = null;
   let lastResult = null;
@@ -198,13 +199,18 @@ export function createBridgeHubHeartbeatController({
       const nowMs = now();
       if (lastSentAt !== null && nowMs - lastSentAt < intervalMs) return lastResult;
       lastSentAt = nowMs;
-      const projects = await readActiveProjects({ env });
-      if (projects.length === 0) {
+      // 名乗る集合は、この端末が実際に配信している集合そのものを使う。登録簿から別途
+      // 数え直すと、配信している側と名乗る側が別々の基準を持ち、必ずずれる（ADR 0165）。
+      const projectIds = await readServedProjectIds({ env });
+      if (projectIds === null) {
+        return record({ schema: HEARTBEAT_RESULT_SCHEMA, state: 'skipped_no_dashboard' }, nowMs);
+      }
+      if (projectIds.length === 0) {
         return record({ schema: HEARTBEAT_RESULT_SCHEMA, state: 'skipped_no_projects' }, nowMs);
       }
       const terminalId = await readOrCreateBridgeHubTerminalId({ env });
       const request = buildBridgeHubRegistrationRequest({
-        terminalId, port: config.listen.port, projectIds: projects.map((project) => project.project_id),
+        terminalId, port: config.listen.port, projectIds,
       });
       return record(
         await sendBridgeHubHeartbeat({ hubUrl: config.hub.url, request, fetchImpl }), nowMs,

package/src/bridge-launch-agent.mjs

@@ -247,10 +247,8 @@ export async function snapshotBridgeLaunchAgent({ env = process.env,
   await prepareDirectory(refs.directory, uid);
   const content = await strictPlist(refs.plist, uid);
   const loaded = await loadedState(runner, uid);
-  if (loaded && content === null) {
-    throw fail('BRIDGE_LAUNCH_AGENT_STATE_INVALID', 'loaded bridge LaunchAgent has no owned plist');
-  }
-  return Object.freeze({ installed: content !== null, loaded, content });
+  const split = loaded && content === null;
+  return Object.freeze({ installed: content !== null, loaded, split, content });
 }
 
 const PROGRAM_ARGUMENTS_PATTERN =
@@ -346,6 +344,10 @@ export async function restoreBridgeLaunchAgent({ snapshot, listen = null, env =
   await prepareDirectory(refs.directory, uid);
   const stopped = await bootoutIfLoaded({ runner, uid });
   if (stopped) await waitStopped({ listen, env });
+  if (snapshot.split === true) {
+    await rm(refs.plist, { force: true });
+    return snapshot;
+  }
   if (snapshot.installed) await atomicPlist(refs.plist, snapshot.content);
   else await rm(refs.plist, { force: true });
   if (snapshot.loaded) {

package/src/bridge-startup-folder.mjs

@@ -239,10 +239,9 @@ export async function snapshotBridgeStartupFolder({ env = process.env } = {}) {
   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 });
+  const split = (launcherContent === null) !== (descriptorContent === null);
+  return Object.freeze({ installed: launcherContent !== null && descriptorContent !== null,
+    split, launcherContent, descriptorContent });
 }
 
 async function pathPresent(ref) {

package/src/todo-dashboard-registry.mjs

@@ -157,6 +157,34 @@ export async function readVisibleTodoDashboardProjects({
     || left.project_id.localeCompare(right.project_id, 'en'));
 }
 
+/**
+ * この端末がいま実際に配信しているproject id。登録簿を自分で数え直さず、配信している
+ * dashboard daemon自身へ問い、loopback healthをdescriptorと突き合わせてから答える。
+ * daemonが居ない・応答しない・descriptorと食い違う時はnull——「配信していない」であって
+ * 「0件を配信している」ではない。
+ *
+ * 公開面へ在ると名乗る集合は、実際に配信している集合と同じでなければならない。別々に
+ * 数えると必ずずれる（2026-08-11に実測）。daemonはactive runを持つprojectを配信し続ける
+ * のに、hub heartbeatは登録簿の2時間staleだけを見て0件と判断し、送信ごと省いた。中身は
+ * 配信できるのに、公開面からは端末ごとofflineになる——障害と見分けがつかない消え方をする。
+ */
+export async function readServedTodoDashboardProjectIds({
+  env = process.env, fetchImpl = fetch, timeoutMs = 2_000,
+} = {}) {
+  let descriptor;
+  try { descriptor = await readJson(paths(env).descriptor, null); } catch { return null; }
+  if (!validDaemonDescriptor(descriptor)) return null;
+  let body;
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${descriptor.port}/__lattice/health`,
+      { signal: AbortSignal.timeout(timeoutMs) });
+    body = response.status === 200 ? await response.json() : null;
+  } catch { return null; }
+  if (body?.schema !== 'lattice.todo_dashboard_health.v1' || body.pid !== descriptor.pid
+    || body.port !== descriptor.port || !Array.isArray(body.project_ids)) return null;
+  return body.project_ids.filter(identifier).sort((left, right) => left.localeCompare(right, 'en'));
+}
+
 /**
  * 見るのはrepo_root directoryの存在だけ。`.lattice`の有無で判定すると、storeを持たない
  * 生きたrepoまで登録簿から消える。ENOENT／ENOTDIR以外のerrorは「消えた証拠」ではないので