@quolu/lattice 0.45.1 → 0.46.1

package/README.ja.md

@@ -295,6 +295,12 @@ dashboard daemonは起動時に読み込んだ版数をhealthで名乗り、inst
 その間伸びます（実測: 8 project登録で約50秒台）。待ち時間は固定秒数ではなく、spawnした子が生きている
 間だけ待ち、子が死ねば即座に`DASHBOARD_DAEMON_UNAVAILABLE`を返します。既定120秒の上限は、応答を
 返さない子に対するbackstopであって正常な起動時間の見積りではありません。
+daemonの生死はdescriptor 1枚では持ちません。daemonは自分のpidの記録を書き、起動のたびに死んだ記録を
+掃除して、descriptorから外れた生存daemonを再認証のうえ停止します。入れ替えの途中でCLI側が落ちても、
+旧daemonが観測されないまま生き残ることはありません。descriptorだけを失った場合は2本目を建てず、
+配信を続けているdaemonを引き取ります。signalを送るのはその場で再認証を通った相手だけで、応答しない
+pidへは送りません（pid再利用で無関係のprocessを止めうるためです）。規約は
+[ADR 0157](docs/adr/0157-dashboard-daemons-are-discoverable-by-record.md)が正です。
 状態を書き込む`start / block / unblock / done / evidence promote / reopen / revise / revise-phase / revise-set`
 では、監査actorとして次の3環境変数をすべて設定してください。
 

package/bin/lattice-dashboard.mjs

@@ -7,6 +7,7 @@ import { readTodoStoreStable } from '../src/todo-store.mjs';
 import { projectTodoStatus } from '../src/todo-status.mjs';
 import { ganttLiveHeadDigest, renderTodoGanttForProject } from '../src/todo-cli.mjs';
 import {
+  forgetTodoDashboardDaemonRecord,
   readVisibleTodoDashboardProjects,
   todoDashboardMemberNeedsVisibility,
   writeTodoDashboardDaemonDescriptor,
@@ -106,15 +107,33 @@ async function synchronize() {
   return active.length;
 }
 
+let closing = null;
+
+/**
+ * 終了経路はsignalだけではない——配信するprojectが尽きた時と同期に失敗した時も
+ * ここを通る。どの経路でも自分の登録簿記録を落とす。消し損ねても次のdaemon起動が
+ * 掃除するので、後始末の失敗で終了を止めない。
+ */
+function close() {
+  if (closing === null) {
+    clearInterval(timer);
+    closing = (async () => {
+      try { await forgetTodoDashboardDaemonRecord({ env }); } catch {}
+      await dashboard.close();
+    })();
+  }
+  return closing;
+}
+
+function exit(code) {
+  close().catch(() => {}).finally(() => process.exit(code));
+}
+
 await synchronize();
 const dashboard = await startTodoGanttDashboardServer({ registry, port });
 await writeTodoDashboardDaemonDescriptor({ port: dashboard.port, env });
 const timer = setInterval(() => synchronize().then((count) => {
-  if (count === 0) process.exit(0);
-}).catch(() => process.exit(1)), 1_000);
-const close = async () => {
-  clearInterval(timer);
-  await dashboard.close();
-};
-process.once('SIGINT', () => close().finally(() => process.exit(0)));
-process.once('SIGTERM', () => close().finally(() => process.exit(0)));
+  if (count === 0) exit(0);
+}).catch(() => exit(1)), 1_000);
+process.once('SIGINT', () => exit(0));
+process.once('SIGTERM', () => exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.45.1",
+  "version": "0.46.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/todo-dashboard-registry.mjs

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import {
-  mkdir, open, readFile, realpath, rename, rm, writeFile,
+  mkdir, open, readdir, readFile, realpath, rename, rm, writeFile,
 } from 'node:fs/promises';
 import path from 'node:path';
 
@@ -41,6 +41,7 @@ function paths(env) {
     root,
     registry: path.join(root, 'projects.json'),
     descriptor: path.join(root, 'daemon.json'),
+    daemons: path.join(root, 'daemons'),
     lock: path.join(root, 'registry.lock'),
     startupLock: path.join(root, 'daemon-start.lock'),
   };
@@ -239,6 +240,71 @@ function processIsAlive(pid) {
   }
 }
 
+function daemonRecordRef(refs, pid) {
+  return path.join(refs.daemons, `${pid}.json`);
+}
+
+/**
+ * daemonごとの記録。descriptorは1枚しか無いので、そこから落ちたdaemonは二度と誰にも
+ * 観測されず、生きたまま不死になる（2026-08-03に2重起動を実測）。descriptorの所有者は
+ * 起動側のままにして、pidごとの記録だけをdaemon自身に書かせる——記録があれば、
+ * descriptorを失っても後続の起動が見つけられる。
+ */
+async function readDaemonRecords(refs) {
+  let names;
+  try { names = await readdir(refs.daemons); } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+  const records = [];
+  for (const name of names) {
+    if (!/^[1-9][0-9]{0,9}\.json$/u.test(name)) continue;
+    const ref = path.join(refs.daemons, name);
+    let record = null;
+    try { record = JSON.parse(await readFile(ref, 'utf8')); } catch { record = null; }
+    // 壊れた記録、file名のpidと中身が食い違う記録は、誰の生死も語れないので捨てる。
+    // 記録はatomicJsonで置かれるので、読み手が書きかけを見ることはない。
+    if (!validDaemonDescriptor(record) || `${record.pid}.json` !== name) {
+      await rm(ref, { force: true });
+      continue;
+    }
+    records.push(record);
+  }
+  return records;
+}
+
+/**
+ * 死んだpidの記録を落とす。全daemonが必ず通る起動時に呼ぶので、登録簿は
+ * 「生きているdaemon＋前回の起動以降に死んだ分」までしか育たない。
+ * keepはhealth応答で生存を確認済みのdaemon——process.kill(0)より強い証拠を
+ * 既に持っているので、その記録は生死判定に掛けない。
+ */
+async function sweepDaemonRecords(refs, { isProcessAlive, keep = null }) {
+  const live = [];
+  for (const record of await readDaemonRecords(refs)) {
+    if (record.pid === keep || await isProcessAlive(record.pid)) live.push(record);
+    else await rm(daemonRecordRef(refs, record.pid), { force: true });
+  }
+  return live;
+}
+
+async function awaitDaemonStopped(descriptor, { isProcessAlive, deadline }) {
+  for (;;) {
+    const alive = await isProcessAlive(descriptor.pid);
+    const stillServing = await daemonAttestation(descriptor) !== null;
+    if (!alive && !stillServing) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+/** 相手が既に死んでいるのは停止の成功であって失敗ではない。 */
+function signalIfPresent(signalProcess, pid, signal) {
+  try { signalProcess(pid, signal); } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+}
+
 async function stopAttestedLegacyDaemon(descriptor, {
   signalProcess = process.kill, isProcessAlive = processIsAlive, timeoutMs = 3_000,
 } = {}) {
@@ -250,18 +316,60 @@ async function stopAttestedLegacyDaemon(descriptor, {
     throw error;
   }
   signalProcess(descriptor.pid, 'SIGTERM');
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const alive = await isProcessAlive(descriptor.pid);
-    const stillServing = await daemonAttestation(descriptor) !== null;
-    if (!alive && !stillServing) return;
-    await new Promise((resolve) => setTimeout(resolve, 50));
-  }
+  if (await awaitDaemonStopped(descriptor, { isProcessAlive, deadline: Date.now() + timeoutMs })) return;
   const error = new Error('legacy dashboard daemon did not stop');
   error.code = 'DASHBOARD_LEGACY_STOP_FAILED';
   throw error;
 }
 
+/**
+ * descriptorの外に居るdaemonを止める。signalを送るのは、いま再認証を通った相手だけ——
+ * 応答しないpidへ送れば、pid再利用で無関係のprocessを殺しうる。認証できない生存pidは
+ * 記録を残したまま見送り、次の起動が判定し直す。
+ * 認証を通った相手はLattice自身のdaemonなので、SIGTERMで死ななければSIGKILLへ上げる。
+ * 置換前のlegacy停止と1つの関数へ畳まない——あちらは認証を失ったこと自体がerror
+ * （版を入れ替える確証が要る）で、こちらは見送ってよい。契約が違う。
+ */
+async function stopStrayDaemon(descriptor, {
+  signalProcess = process.kill, isProcessAlive = processIsAlive, timeoutMs = 3_000,
+} = {}) {
+  if (await daemonAttestation(descriptor) === null) return false;
+  signalIfPresent(signalProcess, descriptor.pid, 'SIGTERM');
+  const half = Math.ceil(timeoutMs / 2);
+  if (await awaitDaemonStopped(descriptor, { isProcessAlive, deadline: Date.now() + half })) return true;
+  signalIfPresent(signalProcess, descriptor.pid, 'SIGKILL');
+  if (await awaitDaemonStopped(descriptor, {
+    isProcessAlive, deadline: Date.now() + (timeoutMs - half),
+  })) return true;
+  const error = new Error('stray dashboard daemon did not stop');
+  error.code = 'DASHBOARD_ORPHAN_STOP_FAILED';
+  throw error;
+}
+
+/**
+ * descriptorが指すdaemon以外を掃除する。呼ぶのはdescriptorの整合が確立した後だけ——
+ * 失敗経路で呼べば、可用性を守るrollback契約より先に生きたdaemonを消してしまう。
+ */
+async function reapStrayDaemons(refs, keepPid, { signalProcess, isProcessAlive, timeoutMs }) {
+  for (const record of await sweepDaemonRecords(refs, { isProcessAlive, keep: keepPid })) {
+    if (record.pid === keepPid) continue;
+    if (await stopStrayDaemon(record, { signalProcess, isProcessAlive, timeoutMs })) {
+      await rm(daemonRecordRef(refs, record.pid), { force: true });
+    }
+  }
+}
+
+/** descriptorを失った時、登録簿の生存daemonから配信を続けている1つを選ぶ。 */
+async function adoptableDaemon(records, { attestationTimeoutMs }) {
+  let legacy = null;
+  for (const record of records) {
+    const attestation = await daemonAttestation(record, { timeoutMs: attestationTimeoutMs });
+    if (attestation === 'current') return { record, attestation };
+    if (attestation === 'legacy' && legacy === null) legacy = { record, attestation };
+  }
+  return legacy;
+}
+
 async function stopSpawnedReplacement(child, descriptor, {
   isProcessAlive = processIsAlive, timeoutMs = 3_000,
 } = {}) {
@@ -290,28 +398,61 @@ async function stopSpawnedReplacement(child, descriptor, {
 export async function writeTodoDashboardDaemonDescriptor({ port, env = process.env }) {
   if (!Number.isSafeInteger(port) || port <= 0 || port > 65_535) throw new TypeError('daemon port invalid');
   const refs = paths(env);
-  await mkdir(refs.root, { recursive: true, mode: 0o700 });
-  await atomicJson(refs.descriptor, { schema: DAEMON_SCHEMA, pid: process.pid, port,
-    started_at: new Date().toISOString() });
+  await mkdir(refs.daemons, { recursive: true, mode: 0o700 });
+  const record = { schema: DAEMON_SCHEMA, pid: process.pid, port,
+    started_at: new Date().toISOString() };
+  // 記録を先に置く。descriptorだけが在って記録が無い瞬間を作ると、その隙に起動側が
+  // 死んだ時に、まさに直そうとしている「誰からも観測されないdaemon」が生まれる。
+  await atomicJson(daemonRecordRef(refs, process.pid), record);
+  await atomicJson(refs.descriptor, record);
+}
+
+/** 自分の記録だけを消す。descriptorは起動側が所有するので、死ぬ側からは触らない。 */
+export async function forgetTodoDashboardDaemonRecord({ env = process.env } = {}) {
+  await rm(daemonRecordRef(paths(env), process.pid), { force: true });
 }
 
 export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon = spawn,
   signalProcess = process.kill, isProcessAlive = processIsAlive, startupTimeoutMs = 120_000,
   legacyStopTimeoutMs = 3_000, replacementIsProcessAlive = processIsAlive,
-  attestationTimeoutMs = 2_000 } = {}) {
+  attestationTimeoutMs = 2_000, strayStopTimeoutMs = 3_000 } = {}) {
   const refs = paths(env);
   await mkdir(refs.root, { recursive: true, mode: 0o700 });
+  // 掃除と孤児の始末の機会はここしかない。daemonの起動は全daemonが必ず通る一点であり、
+  // 誰かがコマンドを叩くのを待つ形にすると、記録は誰にも掃除されず積み上がる。
+  const reap = (keepPid) => reapStrayDaemons(refs, keepPid,
+    { signalProcess, isProcessAlive, timeoutMs: strayStopTimeoutMs });
   return withLock(refs.startupLock, async () => {
     const existing = await readJson(refs.descriptor, null);
     const existingAttestation = await daemonAttestation(existing, { timeoutMs: attestationTimeoutMs });
-    if (existingAttestation === 'current') return existing;
+    if (existingAttestation === 'current') {
+      await reap(existing.pid);
+      return existing;
+    }
     if (validDaemonDescriptor(existing) && existingAttestation === null
       && await isProcessAlive(existing.pid)) {
       const error = new Error('dashboard daemon is alive but temporarily unresponsive');
       error.code = 'DASHBOARD_DAEMON_UNRESPONSIVE';
       throw error;
     }
-    const legacy = existingAttestation === 'legacy' ? existing : null;
+    let legacy = existingAttestation === 'legacy' ? existing : null;
+    if (legacy === null) {
+      // descriptorの指す先が居ない。登録簿に配信中のdaemonが残っているなら、2本目を
+      // 建てずに引き取る——descriptorだけが失われた場合の直接の修理である。
+      const adopted = await adoptableDaemon(
+        (await sweepDaemonRecords(refs, { isProcessAlive })).filter(({ pid }) => pid !== existing?.pid),
+        { attestationTimeoutMs },
+      );
+      if (adopted !== null) {
+        // 引き取った相手は生きて応答しているので、descriptorの不変条件を満たす。
+        await atomicJson(refs.descriptor, adopted.record);
+        if (adopted.attestation === 'current') {
+          await reap(adopted.record.pid);
+          return adopted.record;
+        }
+        legacy = adopted.record;
+      }
+    }
     const portText = env.LATTICE_DASHBOARD_PORT;
     const configuredPort = typeof portText === 'string' && /^(?:0|[1-9][0-9]{0,4})$/u.test(portText)
       && Number(portText) <= 65_535 ? Number(portText) : DEFAULT_PORT;
@@ -348,6 +489,7 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
             throw error;
           }
         }
+        await reap(descriptor.pid);
         return descriptor;
       }
     }