@quolu/lattice 0.57.0 → 0.57.1

package/docs/bridge-setup.md

@@ -98,6 +98,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.1",
   "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-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/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は「消えた証拠」ではないので