@quolu/lattice 0.12.11 → 0.12.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "test": "node scripts/run-product-tests.mjs",
     "test:sensor": "npm --prefix sensor test",
     "precheck": "node --check src/bridge-launch-agent.mjs",
-    "check": "node --check bin/lattice.mjs && node --check bin/lattice-mcp.mjs && node --check bin/lattice-dashboard.mjs && node --check bin/lattice-bridge.mjs && node --check src/cli-stdio.mjs && node --check src/todo-gantt-layout.mjs && node --check src/todo-gantt-scope.mjs && node --check src/bridge-config.mjs && node --check src/bridge-server.mjs && node --check src/bridge-daemon.mjs && node --check src/bridge-cli.mjs && node --check src/project-cli.mjs && node --check src/sensor-cli.mjs && node --check src/sensor-runtime.mjs && node --check src/sensor-adapter.mjs && node --check src/factory-diagnostics.mjs && node --check src/runtime-errors.mjs && node --check src/runtime-contracts.mjs && node --check src/runtime-event-store.mjs && node --check src/hash-chain.mjs && node --check src/dag-chain.mjs && node --check src/todo-contracts.mjs && node --check src/todo-chain.mjs && node --check src/todo-store.mjs && node --check src/todo-migration.mjs && node --check src/todo-revision.mjs && node --check src/todo-status.mjs && node --check src/todo-cli.mjs && node --check src/todo-dashboard-registry.mjs && node --check src/todo-gantt-presentation.mjs && node --check src/todo-gantt-live.mjs && node --check src/bounded-seam.mjs && node --check src/todo-narrative-anchor.mjs && node --check src/todo-markdown-renderer.mjs && node --check src/todo-gantt-svg.mjs && node --check src/todo-gantt-html.mjs && node --check src/runtime-projection.mjs && node --check src/runtime-decision-verifier.mjs && node --check src/runtime-front-end.mjs && node --check src/runtime-cli.mjs && node --check src/rc3-dogfood-scaffold.mjs && node --check src/runtime-engine.mjs && node --check src/runtime-scripted-executor.mjs && node --check src/runtime-diff-observer.mjs && node --check src/runtime-worktree-executor.mjs && node --check src/runtime-hold-recompile.mjs && node --check src/rc3-scripted-campaign.mjs && node --check src/rc3-actual-dogfood.mjs && node --check src/rc4-stage1-dogfood.mjs && node --check research/fixtures/dispatch-record/src/dispatch-record.mjs && node --check test/research-dispatch-record.test.mjs",
+    "check": "node --check bin/lattice.mjs && node --check bin/lattice-mcp.mjs && node --check bin/lattice-dashboard.mjs && node --check bin/lattice-bridge.mjs && node --check src/cli-stdio.mjs && node --check src/bridge-address.mjs && node --check src/bridge-registrar.mjs && node --check src/todo-gantt-layout.mjs && node --check src/todo-gantt-scope.mjs && node --check src/bridge-config.mjs && node --check src/bridge-server.mjs && node --check src/bridge-daemon.mjs && node --check src/bridge-cli.mjs && node --check src/project-cli.mjs && node --check src/sensor-cli.mjs && node --check src/sensor-runtime.mjs && node --check src/sensor-adapter.mjs && node --check src/factory-diagnostics.mjs && node --check src/runtime-errors.mjs && node --check src/runtime-contracts.mjs && node --check src/runtime-event-store.mjs && node --check src/hash-chain.mjs && node --check src/dag-chain.mjs && node --check src/todo-contracts.mjs && node --check src/todo-chain.mjs && node --check src/todo-store.mjs && node --check src/todo-migration.mjs && node --check src/todo-revision.mjs && node --check src/todo-status.mjs && node --check src/todo-cli.mjs && node --check src/todo-dashboard-registry.mjs && node --check src/todo-gantt-presentation.mjs && node --check src/todo-gantt-live.mjs && node --check src/bounded-seam.mjs && node --check src/todo-narrative-anchor.mjs && node --check src/todo-markdown-renderer.mjs && node --check src/todo-gantt-svg.mjs && node --check src/todo-gantt-html.mjs && node --check src/runtime-projection.mjs && node --check src/runtime-decision-verifier.mjs && node --check src/runtime-front-end.mjs && node --check src/runtime-cli.mjs && node --check src/rc3-dogfood-scaffold.mjs && node --check src/runtime-engine.mjs && node --check src/runtime-scripted-executor.mjs && node --check src/runtime-diff-observer.mjs && node --check src/runtime-worktree-executor.mjs && node --check src/runtime-hold-recompile.mjs && node --check src/rc3-scripted-campaign.mjs && node --check src/rc3-actual-dogfood.mjs && node --check src/rc4-stage1-dogfood.mjs && node --check research/fixtures/dispatch-record/src/dispatch-record.mjs && node --check test/research-dispatch-record.test.mjs",
     "check:project-identity": "node --check src/project-identity.mjs",
     "ci": "npm run test && npm run test:sensor && npm run check && npm run check:project-identity"
   }

package/src/bridge-address.mjs

@@ -0,0 +1,107 @@
+/**
+ * Bridge listen-address resolution.
+ *
+ * The bridge is configured with a literal IP so the operator controls exactly
+ * which interface it is exposed on. A DHCP lease change silently invalidates
+ * that choice: the address disappears from the host, the old socket lingers on
+ * a dead address, and nothing on the LAN can reach the bridge any more —
+ * while `bridge status` keeps reporting `enabled: true`.
+ *
+ * This module answers two questions without any I/O:
+ *   1. is the configured address still present on this host?
+ *   2. if not, is there an address that is obviously the same intent?
+ *
+ * "Same intent" is deliberately narrow. A DHCP lease change moves the host
+ * inside its own subnet, so only a non-internal address of the same family in
+ * the same subnet (IPv4 /24, IPv6 /64) is adopted. An address on a different
+ * network — a VPN, a second NIC, a public interface — is never adopted
+ * automatically, because that would expose the bridge somewhere the operator
+ * did not choose. Loopback is never adopted either: it would silently take the
+ * bridge off the LAN while still looking healthy.
+ */
+
+import { isIP } from 'node:net';
+
+/** Wildcards already bind every interface, so they are never "absent". */
+const WILDCARDS = new Set(['0.0.0.0', '::']);
+
+export const BRIDGE_LISTEN_STATES = Object.freeze([
+  'present', 'rebindable', 'absent', 'unconfigured',
+]);
+
+function normalize(value) {
+  return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+
+/**
+ * Flatten `os.networkInterfaces()` into the addresses a bridge may bind.
+ * Internal (loopback) addresses are kept but marked, so callers can exclude
+ * them from adoption while still recognising an explicitly configured one.
+ */
+export function bridgeHostAddresses(interfaces = {}) {
+  const result = [];
+  for (const entries of Object.values(interfaces ?? {})) {
+    for (const entry of entries ?? []) {
+      const address = normalize(entry?.address);
+      if (address === '' || isIP(address) === 0) continue;
+      result.push({ address, family: isIP(address), internal: entry?.internal === true });
+    }
+  }
+  return result.sort((left, right) => (left.address < right.address ? -1
+    : left.address > right.address ? 1 : 0));
+}
+
+/** IPv4 /24 or IPv6 /64 prefix, used as the "same network" test. */
+function subnetKey(address) {
+  const family = isIP(address);
+  if (family === 4) return address.split('.').slice(0, 3).join('.');
+  if (family !== 6) return null;
+  // Expand the IPv6 form enough to compare the first four hextets.
+  const [head] = address.split('%');
+  const parts = head.split('::');
+  const left = parts[0] === '' ? [] : parts[0].split(':');
+  const right = parts.length > 1 ? (parts[1] === '' ? [] : parts[1].split(':')) : [];
+  const fill = Array.from({ length: Math.max(0, 8 - left.length - right.length) }, () => '0');
+  const hextets = (parts.length > 1 ? [...left, ...fill, ...right] : left)
+    .map((entry) => entry.replace(/^0+(?=[0-9a-f])/u, ''));
+  return hextets.slice(0, 4).join(':');
+}
+
+/**
+ * Decide which address the bridge should actually listen on.
+ *
+ * @param {object} options
+ * @param {string|null} options.configured configured literal address.
+ * @param {object} [options.interfaces] `os.networkInterfaces()` shaped object.
+ * @returns {{state: string, effective: string|null, configured: string|null,
+ *   candidates: string[], reason: string|null}}
+ */
+export function resolveBridgeListenAddress({ configured, interfaces = {} } = {}) {
+  const wanted = normalize(configured);
+  if (wanted === '' || isIP(wanted) === 0) {
+    return { state: 'unconfigured', effective: null, configured: null, candidates: [], reason: 'listen_address_unconfigured' };
+  }
+  if (WILDCARDS.has(wanted)) {
+    return { state: 'present', effective: wanted, configured: wanted, candidates: [], reason: null };
+  }
+
+  const addresses = bridgeHostAddresses(interfaces);
+  if (addresses.some((entry) => entry.address === wanted)) {
+    return { state: 'present', effective: wanted, configured: wanted, candidates: [], reason: null };
+  }
+
+  const family = isIP(wanted);
+  const wantedSubnet = subnetKey(wanted);
+  const candidates = addresses
+    .filter((entry) => !entry.internal && entry.family === family
+      && wantedSubnet !== null && subnetKey(entry.address) === wantedSubnet)
+    .map((entry) => entry.address);
+
+  if (candidates.length === 0) {
+    return { state: 'absent', effective: null, configured: wanted, candidates: [],
+      reason: 'configured_address_absent_from_host' };
+  }
+  // Deterministic pick; `candidates` is reported so an ambiguous host is visible.
+  return { state: 'rebindable', effective: candidates[0], configured: wanted, candidates,
+    reason: 'configured_address_absent_rebound_within_subnet' };
+}

package/src/bridge-cli.mjs

@@ -1,6 +1,9 @@
-import { isIP } from 'node:net';
+import { createConnection, isIP } from 'node:net';
+import { networkInterfaces } from 'node:os';
 import * as clack from '@clack/prompts';
 
+import { resolveBridgeListenAddress } from './bridge-address.mjs';
+import { registerBridgeUpstream } from './bridge-registrar.mjs';
 import {
   BridgeConfigError, configureBridge, disableBridge, readBridgeConfig, restoreBridgeConfig,
   normalizeBridgeAllowedHost, withBridgeOperationLock,
@@ -15,7 +18,52 @@ import {
   snapshotBridgeLaunchAgent,
 } from './bridge-launch-agent.mjs';
 
-const RESULT_SCHEMA = 'lattice.bridge_cli_result.v1';
+// 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.
+const RESULT_SCHEMA = 'lattice.bridge_cli_result.v2';
+const REACHABILITY_PROBE_TIMEOUT_MS = 750;
+
+/** TCP connect probe. Answers "is anything accepting there right now". */
+export function probeBridgeListener({ address, port, timeoutMs = REACHABILITY_PROBE_TIMEOUT_MS }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+    const socket = createConnection({ host: address, port });
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false));
+    socket.once('error', () => finish(false));
+  });
+}
+
+/**
+ * Liveness of the configured listen address: does it still exist on this host,
+ * did it move inside its subnet, and is anything accepting connections there.
+ */
+async function bridgeLiveness(config, { interfaces = networkInterfaces(), probe = probeBridgeListener } = {}) {
+  if (config === null || config.enabled !== true) {
+    return { listen_state: 'unconfigured', effective_listen: null, listen_candidates: [],
+      reachable: null, liveness_reason: null };
+  }
+  const resolved = resolveBridgeListenAddress({ configured: config.listen.address, interfaces });
+  const effective = resolved.effective === null ? null
+    : { address: resolved.effective, port: config.listen.port };
+  const reachable = effective === null ? false
+    : await probe({ address: effective.address, port: effective.port });
+  return {
+    listen_state: resolved.state,
+    effective_listen: effective,
+    listen_candidates: resolved.candidates,
+    reachable,
+    liveness_reason: resolved.reason ?? (reachable ? null : 'listener_not_accepting'),
+  };
+}
 
 function fail(stderr, code, message) {
   stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code, message })}\n`);
@@ -48,10 +96,15 @@ function parseOptions(words) {
   return options;
 }
 
-function result(action, config, recovery = null) {
+function result(action, config, recovery = null, liveness = 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, updated_at: config?.updated_at ?? null, recovery };
+    upstream: config?.upstream ?? null, updated_at: config?.updated_at ?? null, recovery,
+    listen_state: liveness?.listen_state ?? null,
+    effective_listen: liveness?.effective_listen ?? null,
+    listen_candidates: liveness?.listen_candidates ?? null,
+    reachable: liveness?.reachable ?? null,
+    liveness_reason: liveness?.liveness_reason ?? null };
 }
 
 export async function collectBridgeSetupWizard({ input, output, prompts = clack } = {}) {
@@ -104,13 +157,13 @@ export async function runBridgeCli({ argv, stdout, stderr, env = process.env,
     stop: stopBridgeDaemon, clearStop: clearBridgeStopControl },
   launchAgent = { snapshot: snapshotBridgeLaunchAgent, install: installBridgeLaunchAgent,
     disable: disableBridgeLaunchAgent, restore: restoreBridgeLaunchAgent },
-  prompts = clack } = {}) {
+  prompts = clack, probe = probeBridgeListener, interfaces = networkInterfaces() } = {}) {
   if (!Array.isArray(argv)) {
-    return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable> [options] --json');
+    return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable|register> [options] --json');
   }
   const wizard = argv.length === 1 && argv[0] === 'setup';
   if (!wizard && argv.at(-1) !== '--json') {
-    return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable> [options] --json');
+    return fail(stderr, 'USAGE', 'usage: lattice bridge <setup|reconfigure|status|disable|register> [options] --json');
   }
   if (wizard && (!stdin?.isTTY || !stdout?.isTTY)) {
     return fail(stderr, 'BRIDGE_SETUP_REQUIRES_TTY',
@@ -118,6 +171,20 @@ export async function runBridgeCli({ argv, stdout, stderr, env = process.env,
   }
   const [command, ...words] = wizard ? argv : argv.slice(0, -1);
   try {
+    if (command === 'register' && words.length === 0) {
+      const current = await readBridgeConfig({ env });
+      if (current === null || current.enabled !== true) {
+        return fail(stderr, 'BRIDGE_DISABLED', 'bridge is not enabled; nothing to register');
+      }
+      const resolved = resolveBridgeListenAddress({ configured: current.listen.address, interfaces });
+      if (resolved.effective === null) {
+        return fail(stderr, 'BRIDGE_LISTEN_ADDRESS_ABSENT',
+          'configured bridge listen address is not present on this host');
+      }
+      const registration = await registerBridgeUpstream({ port: current.listen.port, env });
+      stdout.write(`${JSON.stringify(registration)}\n`);
+      return registration.state === 'failed' ? 1 : 0;
+    }
     let config;
     let recovery = null;
     if (command === 'status' && words.length === 0) config = await readBridgeConfig({ env });
@@ -216,8 +283,11 @@ 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.
+    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))}\n`);
+    else stdout.write(`${JSON.stringify(result(command, config, recovery, liveness))}\n`);
     return 0;
   } catch (error) {
     stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2',

package/src/bridge-launch-agent.mjs

@@ -9,6 +9,7 @@ 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_LAUNCH_AGENT_LABEL = 'dev.kitepon.lattice.bridge';
 const START_TIMEOUT_MS = 5_000;
@@ -126,6 +127,17 @@ function plistDocument({ nodePath, bridgePath, instanceToken, env }) {
     }
     environment.push(['LATTICE_CONFIG_DIR', env.LATTICE_CONFIG_DIR]);
   }
+  // The daemon registers its upstream on every new binding, but only if it can
+  // see the registrar settings. launchd does not inherit the shell environment,
+  // so without baking them in here the self-registration silently never fires —
+  // which is exactly the kind of quiet non-recovery this whole path exists to
+  // remove. `bridgeRegistrarSettings` rejects a half-configured pair rather than
+  // installing an agent that would skip registration forever.
+  const registrar = bridgeRegistrarSettings(env);
+  if (registrar !== null) {
+    environment.push(['LATTICE_BRIDGE_REGISTRAR_SSH_HOST', registrar.host]);
+    environment.push(['LATTICE_BRIDGE_REGISTRAR_SCRIPT', registrar.script]);
+  }
   const environmentXml = environment.map(([key, value]) =>
     `      <key>${xml(key)}</key>\n      <string>${xml(value)}</string>`).join('\n');
   return `<?xml version="1.0" encoding="UTF-8"?>

package/src/bridge-registrar.mjs

@@ -0,0 +1,102 @@
+/**
+ * Bridge upstream self-registration.
+ *
+ * The public site is reverse-proxied to a literal LAN address held by another
+ * host. When this host's address moves — a DHCP lease change is enough — that
+ * literal goes stale and the site starts failing, with nothing on either side
+ * noticing. Registration closes that loop: after the bridge binds, it tells the
+ * reverse proxy where it actually is.
+ *
+ * This is an explicit connector, not a hook into someone else's tooling. It
+ * runs one fixed shape — `ssh <host> <script> <port>` — over the operator's
+ * existing ssh trust, and both operands are validated. Lattice never sends a
+ * command string, so the reverse proxy host decides what registration means and
+ * can refuse anything it does not like. The remote script is expected to derive
+ * the address from the ssh source rather than trusting anything sent to it.
+ *
+ * Opt-in via environment, so an unconfigured host simply never registers:
+ *   LATTICE_BRIDGE_REGISTRAR_SSH_HOST   ssh destination (an ssh_config alias)
+ *   LATTICE_BRIDGE_REGISTRAR_SCRIPT     absolute path of the remote script
+ */
+
+import { execFile } from 'node:child_process';
+
+export const REGISTRAR_RESULT_SCHEMA = 'lattice.bridge_registrar_result.v1';
+
+const SSH_HOST = /^[A-Za-z0-9][A-Za-z0-9._-]{0,253}$/u;
+const REMOTE_SCRIPT = /^\/[A-Za-z0-9._\-/]{1,255}$/u;
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export class BridgeRegistrarError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'BridgeRegistrarError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+/**
+ * Registrar settings, or null when the operator has not opted in.
+ * A half-configured registrar is an error rather than a silent no-op: it means
+ * someone intended to register and the site will quietly rot if we skip it.
+ */
+export function bridgeRegistrarSettings(env = process.env) {
+  const host = env.LATTICE_BRIDGE_REGISTRAR_SSH_HOST ?? '';
+  const script = env.LATTICE_BRIDGE_REGISTRAR_SCRIPT ?? '';
+  if (host === '' && script === '') return null;
+  if (!SSH_HOST.test(host)) {
+    throw new BridgeRegistrarError('BRIDGE_REGISTRAR_INVALID',
+      'LATTICE_BRIDGE_REGISTRAR_SSH_HOST must be a bare ssh destination', { host });
+  }
+  if (!REMOTE_SCRIPT.test(script)) {
+    throw new BridgeRegistrarError('BRIDGE_REGISTRAR_INVALID',
+      'LATTICE_BRIDGE_REGISTRAR_SCRIPT must be an absolute path without spaces', { script });
+  }
+  return Object.freeze({ host, script });
+}
+
+function runSsh({ host, script, port, timeoutMs, runner }) {
+  const args = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', host, script, String(port)];
+  return new Promise((resolve) => {
+    runner('ssh', args, { timeout: timeoutMs, encoding: 'utf8' }, (error, stdout, stderr) => {
+      resolve({ error, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+    });
+  });
+}
+
+/**
+ * Register `port` on the reverse proxy host. The address is deliberately NOT
+ * sent: the remote end reads it from the ssh connection, so this host can only
+ * ever register itself.
+ *
+ * Never throws for a remote failure — the bridge is still serving locally and
+ * taking it down would turn a proxy-config problem into an outage. The failure
+ * is returned typed so callers surface it instead of swallowing it.
+ */
+export async function registerBridgeUpstream({
+  port, env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, runner = execFile,
+} = {}) {
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new BridgeRegistrarError('BRIDGE_REGISTRAR_INVALID', 'registration port is invalid', { port });
+  }
+  const settings = bridgeRegistrarSettings(env);
+  if (settings === null) {
+    return { schema: REGISTRAR_RESULT_SCHEMA, state: 'not_configured', port,
+      host: null, remote: null, detail: null };
+  }
+  const { error, stdout, stderr } = await runSsh({ ...settings, port, timeoutMs, runner });
+  if (error) {
+    return { schema: REGISTRAR_RESULT_SCHEMA, state: 'failed', port, host: settings.host,
+      remote: null, detail: (stderr.trim() || error.message || 'ssh registration failed').slice(0, 500) };
+  }
+  let remote = null;
+  try { remote = JSON.parse(stdout.trim()); } catch { remote = null; }
+  if (remote === null) {
+    return { schema: REGISTRAR_RESULT_SCHEMA, state: 'failed', port, host: settings.host,
+      remote: null, detail: `registrar returned no parsable result: ${stdout.trim().slice(0, 200)}` };
+  }
+  return { schema: REGISTRAR_RESULT_SCHEMA,
+    state: remote.changed === true ? 'updated' : 'unchanged',
+    port, host: settings.host, remote, detail: null };
+}

package/src/bridge-server.mjs

@@ -5,6 +5,10 @@ import { lstat, open } from 'node:fs/promises';
 import path from 'node:path';
 import { parseTree } from 'jsonc-parser';
 
+import { networkInterfaces } from 'node:os';
+
+import { resolveBridgeListenAddress } from './bridge-address.mjs';
+import { registerBridgeUpstream } from './bridge-registrar.mjs';
 import {
   BridgeConfigError, bridgeConfigPaths, normalizeBridgeAllowedHost, readBridgeConfig,
 } from './bridge-config.mjs';
@@ -184,12 +188,28 @@ export async function startBridgeServer({
   config, env = process.env,
   instanceToken = null,
   resolveUpstream = (upstream) => resolveBridgeUpstream(upstream, { env }),
+  interfaces = networkInterfaces(),
 } = {}) {
   if (config?.enabled !== true) throw new BridgeConfigError('BRIDGE_DISABLED', 'bridge is disabled');
   if (!Array.isArray(config.allowed_hosts) || config.allowed_hosts.length === 0) {
     throw new BridgeConfigError('BRIDGE_CONFIG_INVALID', 'bridge allowed hosts are required');
   }
+  // A DHCP lease change moves the host inside its own subnet and strands the
+  // configured literal. Follow it rather than binding a dead address, but only
+  // within the same subnet (see bridge-address.mjs for why that bound matters).
+  const resolvedListen = resolveBridgeListenAddress({ configured: config.listen.address, interfaces });
+  if (resolvedListen.effective === null) {
+    throw new BridgeConfigError('BRIDGE_LISTEN_ADDRESS_ABSENT',
+      'configured bridge listen address is not present on this host',
+      { ...config.listen, listen_state: resolvedListen.state });
+  }
+  const listenAddress = resolvedListen.effective;
   let allowedHosts = new Set(config.allowed_hosts);
+  // The rebound address has to answer for itself, otherwise every request to it
+  // is rejected by the Host allow-list the operator never knew had gone stale.
+  if (listenAddress !== config.listen.address) {
+    allowedHosts.add(normalizeBridgeAllowedHost(listenAddress));
+  }
   let currentConfig = config;
   const handleRequest = async (incoming, response) => {
     let requestHost;
@@ -249,17 +269,19 @@ export async function startBridgeServer({
   });
   await new Promise((resolve, reject) => {
     server.once('error', reject);
-    server.listen({ host: config.listen.address, port: config.listen.port, exclusive: true }, resolve);
+    server.listen({ host: listenAddress, port: config.listen.port, exclusive: true }, resolve);
   }).catch((error) => {
     throw new BridgeConfigError(error?.code === 'EADDRINUSE' ? 'BRIDGE_PORT_UNAVAILABLE' : 'BRIDGE_BIND_FAILED',
-      'bridge listen failed', { ...config.listen }, error);
+      'bridge listen failed', { ...config.listen, effective_address: listenAddress }, error);
   });
   const boundAddress = server.address();
   const actualPort = typeof boundAddress === 'object' && boundAddress !== null
     ? boundAddress.port : config.listen.port;
   let closed = false;
   return Object.freeze({
-    address: config.listen.address,
+    address: listenAddress,
+    configured_address: config.listen.address,
+    rebound: listenAddress !== config.listen.address,
     port: actualPort,
     updateConfig(next) {
       if (next?.enabled !== true || next.listen.address !== config.listen.address
@@ -268,6 +290,9 @@ export async function startBridgeServer({
       }
       currentConfig = next;
       allowedHosts = new Set(next.allowed_hosts);
+      if (listenAddress !== config.listen.address) {
+        allowedHosts.add(normalizeBridgeAllowedHost(listenAddress));
+      }
     },
     close: async () => {
       if (closed) return;
@@ -279,9 +304,27 @@ export async function startBridgeServer({
   });
 }
 
-export function bridgeRuntimeController({ env = process.env, instanceToken = null } = {}) {
+export function bridgeRuntimeController({
+  env = process.env, instanceToken = null,
+  register = registerBridgeUpstream,
+  report = (line) => process.stderr.write(`${line}\n`),
+} = {}) {
   let active = null;
   let fingerprint = null;
+  // A fresh binding is exactly when the reverse proxy's literal may have gone
+  // stale, so that is when the bridge tells it where it now is. A registration
+  // failure is reported, never swallowed, and never takes the local bridge down:
+  // the bridge is still serving, only the published route is behind.
+  const announce = async (binding) => {
+    try {
+      const outcome = await register({ port: binding.port, env });
+      if (outcome.state !== 'not_configured') report(JSON.stringify(outcome));
+    } catch (error) {
+      report(JSON.stringify({ schema: 'lattice.bridge_registrar_result.v1', state: 'failed',
+        port: binding.port, host: null, remote: null,
+        detail: error?.message ?? 'registration failed' }));
+    }
+  };
   return Object.freeze({
     async reconcile() {
       const config = await readBridgeConfig({ env });
@@ -293,7 +336,11 @@ export function bridgeRuntimeController({ env = process.env, instanceToken = nul
         fingerprint = null;
         return null;
       }
-      if (active !== null && active.address === config.listen.address && active.port === config.listen.port) {
+      // Compare against the CONFIGURED address: a rebound binding still serves
+      // the same configuration, and comparing the effective address would tear
+      // the server down and rebuild it on every reconcile.
+      if (active !== null && active.configured_address === config.listen.address
+        && active.port === config.listen.port) {
         active.updateConfig(config);
         fingerprint = next;
         return active;
@@ -303,6 +350,7 @@ export function bridgeRuntimeController({ env = process.env, instanceToken = nul
       active = replacement;
       fingerprint = next;
       await previous?.close();
+      await announce(active);
       return active;
     },
     async close() {

package/src/cli-help.mjs

@@ -88,6 +88,10 @@ Commands:
   reconfigure [--listen <IP>] [--port <49152..65535|auto>] [--dashboard|--upstream <URL>] [--allow-host <host>...]
   status
   disable
+  register    # 現在のlisten portをreverse proxy hostへ自己登録する
+
+registerはLATTICE_BRIDGE_REGISTRAR_SSH_HOSTとLATTICE_BRIDGE_REGISTRAR_SCRIPTが
+両方設定されている時だけ動く。アドレスは送らず、remote側がssh送信元から決める。
 `,
 });
 
@@ -135,6 +139,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'bridge reconfigure': 'bridge reconfigure [--listen <IP>] [--port <49152..65535|auto>] [--dashboard|--upstream <URL>] [--allow-host <host>...] --json',
   'bridge status': 'bridge status --json',
   'bridge disable': 'bridge disable --json',
+  'bridge register': 'bridge register --json',
 });
 
 function requestedNamespace(argv) {

package/src/todo-dashboard-registry.mjs

@@ -6,6 +6,16 @@ import {
 } from 'node:fs/promises';
 import path from 'node:path';
 
+import packageJson from '../package.json' with { type: 'json' };
+
+/**
+ * The version of the code in THIS process. A daemon loads its modules once at
+ * startup and keeps serving them, so installing a new package does not change
+ * what the running daemon serves. The daemon reports the version it started
+ * with; anything else is code that has already been replaced on disk.
+ */
+export const TODO_DASHBOARD_CODE_VERSION = packageJson.version;
+
 const REGISTRY_SCHEMA = 'lattice.todo_dashboard_registry.v1';
 const DAEMON_SCHEMA = 'lattice.todo_dashboard_daemon.v1';
 const DEFAULT_PORT = 0;
@@ -182,7 +192,13 @@ async function daemonAttestation(descriptor, { timeoutMs = 2_000 } = {}) {
     if (body?.schema !== 'lattice.todo_dashboard_health.v1' || body.pid !== descriptor.pid
       || !Array.isArray(body.project_ids)) return null;
     const keys = Object.keys(body).sort().join(',');
-    if (keys === 'pid,port,project_ids,schema' && body.port === descriptor.port) return 'current';
+    // 'legacy' means "alive, but serving code we have already replaced" — the
+    // caller starts a replacement and stops it. A daemon that predates the
+    // version field, or one still running an older package, is exactly that.
+    if (keys === 'pid,port,project_ids,schema,version' && body.port === descriptor.port) {
+      return body.version === TODO_DASHBOARD_CODE_VERSION ? 'current' : 'legacy';
+    }
+    if (keys === 'pid,port,project_ids,schema' && body.port === descriptor.port) return 'legacy';
     if (keys === 'pid,project_ids,schema') return 'legacy';
     return null;
   } catch { return null; }

package/src/todo-gantt-html.mjs

@@ -6,7 +6,7 @@ import {
 } from './todo-markdown-renderer.mjs';
 import { renderTodoGanttSvg, TODO_GANTT_STATUS_PRESENTATION } from './todo-gantt-svg.mjs';
 
-export const TODO_GANTT_RENDERER_VERSION = 'lattice.todo_gantt_renderer.v9';
+export const TODO_GANTT_RENDERER_VERSION = 'lattice.todo_gantt_renderer.v10';
 export const TODO_GANTT_PROSE_MAX_BYTES = 8 * 1024 * 1024;
 export const TODO_GANTT_HTML_MAX_BYTES = 24 * 1024 * 1024;
 
@@ -131,14 +131,16 @@ function foldIndex(layout) {
   return new Map((layout?.folded ?? []).map((entry) => [refKey(entry.task), refKey(entry.fold)]));
 }
 
-function renderTaskIndexEntry(section, lookup, folds) {
+function renderTaskIndexEntry(section, lookup) {
   const key = refKey(section.ref);
   const status = DOCUMENT_STATUS[section.state.status] ?? { mark: '?', label: '状態不明' };
   const blockedReason = section.state.status === 'blocked'
     ? `<span class="task-index-blocked-reason">— ${escapeHtmlText(section.state.blocked_reason ?? '理由未記録')}</span>` : '';
-  // A folded ToDo keeps its row here — the index is the complete list — but
-  // selecting it points at the fold node that actually stands on the diagram.
-  const selectKey = folds.get(key) ?? key;
+  // A folded ToDo keeps its row here — the index is the complete list — and it
+  // selects its OWN detail. Pointing the row at the fold node standing in for it
+  // on the diagram would open nothing: a fold node is not a ToDo, so no detail
+  // panel carries its key.
+  const selectKey = key;
   return `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(selectKey)}"><span class="task-index-status status-${escapeHtmlAttribute(section.state.status)}" role="img" aria-label="${escapeHtmlAttribute(status.label)}">${escapeHtmlText(status.mark)}</span><span class="task-index-reference">${escapeHtmlText(taskReference(section, lookup))}</span><strong>${escapeHtmlText(section.task.title)}</strong>${blockedReason}</button></li>`;
 }
 
@@ -156,13 +158,33 @@ function renderTaskIndex(sections, lookup, folds = new Map()) {
     const drawn = plan.tasks.filter((section) => !folds.has(refKey(section.ref)));
     const folded = plan.tasks.filter((section) => folds.has(refKey(section.ref)));
     const drawnList = drawn.length === 0 ? ''
-      : `<ol class="task-index-list">${drawn.map((section) => renderTaskIndexEntry(section, lookup, folds)).join('')}</ol>`;
+      : `<ol class="task-index-list">${drawn.map((section) => renderTaskIndexEntry(section, lookup)).join('')}</ol>`;
     const foldedList = folded.length === 0 ? ''
-      : `<details class="task-index-folded"><summary>完走済みとして畳んだ工程 ${folded.length}件</summary><ol class="task-index-list">${folded.map((section) => renderTaskIndexEntry(section, lookup, folds)).join('')}</ol></details>`;
+      : `<details class="task-index-folded"><summary>完走済みとして畳んだ工程 ${folded.length}件</summary><ol class="task-index-list">${folded.map((section) => renderTaskIndexEntry(section, lookup)).join('')}</ol></details>`;
     return `<section class="task-index-plan"><h2><code>${escapeHtmlText(plan.planKey)}</code></h2>${drawnList}${foldedList}</section>`;
   }).join('');
 }
 
+/**
+ * Detail panel for a fold node.
+ *
+ * A fold node is the only thing standing on the diagram for the history it
+ * summarises, so it must open like any other node — otherwise clicking the
+ * folded part of the plan does nothing and the folded ToDos become unreachable.
+ */
+function renderFoldDetail(fold, members, lookup) {
+  const laneLabels = fold.lanes.map((lane) => {
+    const entry = lookup.lanes.get(JSON.stringify([fold.ref.plan_key, lane]));
+    return entry === undefined ? lane : `${lane} — ${entry.name}`;
+  });
+  const chain = fold.longest_chain_task_count === 0 ? ''
+    : `<p><strong>構造上の最長依存鎖:</strong> このうち${fold.longest_chain_task_count}工程が乗っています。</p>`;
+  const memberList = members.length === 0
+    ? '<p class="relation-empty">構成工程を復元できませんでした。</p>'
+    : `<ol class="task-index-list">${members.map((section) => renderTaskIndexEntry(section, lookup)).join('')}</ol>`;
+  return `<article class="task-detail fold-detail" data-detail-key="${escapeHtmlAttribute(refKey(fold.ref))}" hidden><header><span class="detail-status status-done">▣ 完走済み（畳み込み）</span><span class="detail-reference">${escapeHtmlText(`${fold.task_count}工程`)}</span></header><h1>完了済み ${escapeHtmlText(String(fold.task_count))}件</h1><p><strong>plan:</strong> <code>${escapeHtmlText(fold.ref.plan_key)}</code></p><p class="detail-category"><strong>カテゴリ:</strong> ${escapeHtmlText(laneLabels.join('、'))}</p>${chain}<p class="fold-note">後続に作業中・未着手の工程が残っていないため、まとめて1個のノードとして描いています。図に全件を描くには <code>lattice todo gantt --scope all</code> を実行してください。</p><section><h2>含まれる工程 ${escapeHtmlText(String(members.length))}件</h2>${memberList}</section></article>`;
+}
+
 function presentationLookup(presentation) {
   return {
     lanes: new Map((presentation?.lanes ?? []).map((lane) => [JSON.stringify([lane.plan_key, lane.lane]), lane])),
@@ -175,14 +197,19 @@ function taskReference(section, lookup) {
   return number === undefined ? `ID ${section.task.task_id}` : `工程 ${number.display_number}`;
 }
 
-function renderRelationList(relations, sectionByKey, lookup, emptyText) {
+function renderRelationList(relations, sectionByKey, lookup, emptyText, folds = new Map()) {
   if (relations.length === 0) return `<p class="relation-empty">${escapeHtmlText(emptyText)}</p>`;
   return `<ul class="relation-list">${relations.map((relation) => {
-    const target = sectionByKey.get(refKey(relation.ref));
+    const targetKey = refKey(relation.ref);
+    const target = sectionByKey.get(targetKey);
     if (target === undefined) return '';
     const join = relation.joinIds.length === 0 ? ''
       : `<span class="relation-kind">合流条件: ${escapeHtmlText(relation.joinIds.join(', '))}</span>`;
-    return `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(refKey(target.ref))}"><strong>${escapeHtmlText(taskReference(target, lookup))}</strong><span>${escapeHtmlText(target.task.title)}</span></button>${join}</li>`;
+    // Mark the ones the diagram no longer draws separately, so the reader knows
+    // why they cannot find this box on screen.
+    const reference = folds.has(targetKey)
+      ? `▣ ${taskReference(target, lookup)}` : taskReference(target, lookup);
+    return `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(targetKey)}"><strong>${escapeHtmlText(reference)}</strong><span>${escapeHtmlText(target.task.title)}</span></button>${join}</li>`;
   }).join('')}</ul>`;
 }
 
@@ -211,6 +238,7 @@ function renderRightPane(sections, layout, presentation, readModel) {
   const lookup = presentationLookup(presentation);
   const sectionByKey = new Map(sections.map((section) => [refKey(section.ref), section]));
   const nodeByKey = new Map(layout.nodes.map((node) => [refKey(node.ref), node]));
+  const folds = foldIndex(layout);
   const incoming = new Map(sections.map((section) => [refKey(section.ref), []]));
   const outgoing = new Map(sections.map((section) => [refKey(section.ref), []]));
   const addRelation = (relations, ownerKey, ref, joinIds) => {
@@ -223,7 +251,10 @@ function renderRightPane(sections, layout, presentation, readModel) {
     }
     entry.joinIds = [...new Set([...entry.joinIds, ...joinIds])].sort();
   };
-  for (const edge of layout.edges) {
+  // Premises and successors come from the FULL graph. `layout.edges` is the
+  // drawn graph, where a fold unit's interior dependencies have been contracted
+  // away — reading those here would tell a folded ToDo it has no premises.
+  for (const edge of layout.full_edges ?? layout.edges) {
     addRelation(incoming, refKey(edge.to), edge.from, edge.join_ids);
     addRelation(outgoing, refKey(edge.from), edge.to, edge.join_ids);
   }
@@ -256,10 +287,25 @@ function renderRightPane(sections, layout, presentation, readModel) {
     const readiness = node?.visibility.next_ready
       ? `<p class="readiness-note">ready frontierの一員です。${ready.length > 1 ? '他のready工程と同時dispatchするのが既定です。subsetだけを選ぶ場合は理由を記録してください。' : '現在の唯一の着手候補です。'}</p>`
       : incoming.get(key).length === 0 ? '<p class="readiness-note">登録済みの前提工程はありません。図だけではdispatch可否を判定しません。</p>' : '';
-    return `<article class="task-detail" data-detail-key="${escapeHtmlAttribute(key)}" hidden><header><span class="detail-status status-${escapeHtmlAttribute(section.state.status)}">${escapeHtmlText(status.mark)} ${escapeHtmlText(status.label)}</span><span class="detail-reference">${escapeHtmlText(taskReference(section, lookup))}</span></header><h1>${escapeHtmlText(section.task.title)}</h1><p class="detail-category"><strong>カテゴリ:</strong> ${escapeHtmlText(category)}</p>${categoryDescription}<p><strong>正規ID:</strong> <code>${escapeHtmlText(`${section.ref.plan_key}/${section.task.task_id}`)}</code></p>${blockedReason}${readiness}<section><h2>前提工程</h2>${renderRelationList(incoming.get(key), sectionByKey, lookup, '登録済みの前提工程はありません。')}</section><section><h2>後続工程</h2>${renderRelationList(outgoing.get(key), sectionByKey, lookup, '登録済みの後続工程はありません。')}</section><p class="anchor-status">${escapeHtmlText(anchorText)}</p><details class="task-diagnostics"><summary>開発者向け診断</summary><dl><dt>canonical ref</dt><dd><code>${escapeHtmlText(`${section.ref.project_id}/${section.ref.plan_key}/${section.task.task_id}`)}</code></dd><dt>anchor</dt><dd>${escapeHtmlText(section.anchorOutcome.anchored ? 'verified' : section.anchorOutcome.reason)}</dd></dl></details></article>`;
+    // A folded ToDo has no box of its own on the diagram. Say which fold node
+    // stands in for it, and make that node one click away.
+    const foldKey = folds.get(key);
+    const foldedNote = foldKey === undefined ? ''
+      : `<p class="fold-note">この工程は図の上では ▣ 畳み込みノードにまとめられています。<button type="button" class="fold-return" data-select-node-key="${escapeHtmlAttribute(foldKey)}">畳み込みノードを開く</button></p>`;
+    return `<article class="task-detail" data-detail-key="${escapeHtmlAttribute(key)}" hidden><header><span class="detail-status status-${escapeHtmlAttribute(section.state.status)}">${escapeHtmlText(status.mark)} ${escapeHtmlText(status.label)}</span><span class="detail-reference">${escapeHtmlText(taskReference(section, lookup))}</span></header><h1>${escapeHtmlText(section.task.title)}</h1><p class="detail-category"><strong>カテゴリ:</strong> ${escapeHtmlText(category)}</p>${categoryDescription}<p><strong>正規ID:</strong> <code>${escapeHtmlText(`${section.ref.plan_key}/${section.task.task_id}`)}</code></p>${blockedReason}${readiness}${foldedNote}<section><h2>前提工程</h2>${renderRelationList(incoming.get(key), sectionByKey, lookup, '登録済みの前提工程はありません。', folds)}</section><section><h2>後続工程</h2>${renderRelationList(outgoing.get(key), sectionByKey, lookup, '登録済みの後続工程はありません。', folds)}</section><p class="anchor-status">${escapeHtmlText(anchorText)}</p><details class="task-diagnostics"><summary>開発者向け診断</summary><dl><dt>canonical ref</dt><dd><code>${escapeHtmlText(`${section.ref.project_id}/${section.ref.plan_key}/${section.task.task_id}`)}</code></dd><dt>anchor</dt><dd>${escapeHtmlText(section.anchorOutcome.anchored ? 'verified' : section.anchorOutcome.reason)}</dd></dl></details></article>`;
   }).join('');
-  const taskIndex = renderTaskIndex(sections, lookup, foldIndex(layout));
-  return `<div class="right-toolbar"><button type="button" data-show-overview>概要</button><button type="button" data-show-selected hidden>選択工程へ戻る</button><button type="button" data-show-task-index>元Markdown全文</button></div><div class="right-content">${overview}<div data-right-panel="details" hidden>${details}</div><section class="task-index" data-right-panel="task-index" hidden><h1>全工程</h1><p>Latticeに登録された全工程を、現在の状態とともに登録順で表示しています。</p>${taskIndex}</section></div>`;
+  const membersByFold = new Map();
+  for (const [taskKey, foldKey] of folds) {
+    const section = sectionByKey.get(taskKey);
+    if (section === undefined) continue;
+    if (!membersByFold.has(foldKey)) membersByFold.set(foldKey, []);
+    membersByFold.get(foldKey).push(section);
+  }
+  const foldDetails = (layout.scope?.folds ?? [])
+    .map((fold) => renderFoldDetail(fold, membersByFold.get(refKey(fold.ref)) ?? [], lookup))
+    .join('');
+  const taskIndex = renderTaskIndex(sections, lookup, folds);
+  return `<div class="right-toolbar"><button type="button" data-show-overview>概要</button><button type="button" data-show-selected hidden>選択工程へ戻る</button><button type="button" data-show-task-index>元Markdown全文</button></div><div class="right-content">${overview}<div data-right-panel="details" hidden>${details}${foldDetails}</div><section class="task-index" data-right-panel="task-index" hidden><h1>全工程</h1><p>Latticeに登録された全工程を、現在の状態とともに登録順で表示しています。</p>${taskIndex}</section></div>`;
 }
 
 function renderDiagramLegend(presentation, layout = null) {
@@ -327,6 +373,9 @@ body{display:grid;grid-template-rows:minmax(0,1fr);height:100vh;margin:0;backgro
 .task-index-list{margin:0;padding:0;list-style:none}.task-index-list li+li{margin-top:8px}.task-index-list button{display:grid;width:100%;grid-template-columns:1.5rem auto minmax(0,1fr);gap:4px 8px;align-items:baseline}
 .task-index-status{grid-row:1 / span 2;color:var(--text-secondary);font-size:13.5px;text-align:center}.task-index-status.status-in-progress{color:var(--accent)}.task-index-status.status-done{color:var(--good)}.task-index-status.status-blocked{color:var(--critical)}
 .task-index-reference{color:var(--text-secondary);font-size:12px;white-space:nowrap}.task-index-list strong{font-size:13.5px;font-weight:600;overflow-wrap:anywhere}.task-index-blocked-reason{grid-column:2 / -1;color:var(--text-secondary);font-size:12px;overflow-wrap:anywhere}
+.fold-detail>section{margin-top:16px}.fold-detail h2{margin:0 0 12px;font-size:16px;font-weight:600}
+.fold-return{margin-left:8px;padding:2px 8px;border:1px solid var(--border);border-radius:4px;background:var(--surface-2);color:var(--text-primary);font:500 12px/1.6 system-ui,-apple-system,"Hiragino Sans","Yu Gothic UI",sans-serif;cursor:pointer}
+.fold-return:focus-visible{outline:2px solid var(--text-primary);outline-offset:2px}
 .todo-gantt text{font-family:system-ui,-apple-system,"Hiragino Sans","Yu Gothic UI",sans-serif;pointer-events:none}
 .todo-node .node-surface{fill:var(--surface-2);stroke:var(--border);stroke-width:1}
 .todo-node .node-meta{fill:var(--text-secondary);font-size:12px;font-weight:500}

package/src/todo-gantt-layout.mjs

@@ -403,7 +403,7 @@ export function layoutTodoGantt(readModel, chainProjection, options = {}) {
 
   // Only the geometry stage below sees the narrowed graph.
   const projected = scope === 'all'
-    ? { nodes: full.nodes, edges: full.edges, foldedByKey: new Map(), folds: [], refined: false }
+    ? { nodes: full.nodes, edges: full.edges, foldedByKey: new Map(), folds: [], grouping: null }
     : projectTodoGanttScope({
       nodes: full.nodes, edges: full.edges, wave: fullWaves.wave, longestChainKeys: longestNodeKeys,
     });
@@ -619,6 +619,16 @@ export function layoutTodoGantt(readModel, chainProjection, options = {}) {
     },
     nodes: projectedNodes,
     edges: projectedEdges,
+    // Every dependency in the plan, before folding contracted any of them away.
+    // The diagram draws `edges`; anything that describes a ToDo in words — the
+    // premises and successors in the right pane — reads this instead, so a
+    // folded ToDo keeps telling the truth about what it depended on.
+    full_edges: full.edges.map((edge) => ({
+      from: { ...full.nodesByKey.get(edge.from).ref },
+      to: { ...full.nodesByKey.get(edge.to).ref },
+      kinds: [...edge.kinds].sort(compareText),
+      join_ids: [...edge.joinIdentities.values()].map(({ join_id }) => join_id).sort(compareText),
+    })),
     connectors: junctionConnectors,
     groups: {
       plans: [...planMap.entries()].map(([plan_key, task_count]) => ({ plan_key, task_count })),
@@ -628,7 +638,7 @@ export function layoutTodoGantt(readModel, chainProjection, options = {}) {
       requested: scope,
       folded_task_count: projected.foldedByKey.size,
       fold_node_count: projected.folds.length,
-      per_wave_refinement: projected.refined,
+      grouping: projected.grouping,
       folds: projected.folds.map((entry) => ({
         ref: { ...entry.ref },
         task_count: entry.task_count,

package/src/todo-gantt-live.mjs

@@ -1,5 +1,7 @@
 import { createServer } from 'node:http';
 
+import { TODO_DASHBOARD_CODE_VERSION } from './todo-dashboard-registry.mjs';
+
 const LOOPBACK = '127.0.0.1';
 const POLL_MS = 500;
 const HTTP_ERROR_SCHEMA = 'lattice.todo_gantt_http_error.v1';
@@ -136,8 +138,12 @@ export async function startTodoGanttDashboardServer({ registry, port = 0, redire
       if (url.pathname === '/__lattice/health') {
         response.writeHead(200, { 'content-type': 'application/json; charset=utf-8',
           'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+        // `version` is the package this process loaded at startup, not the one
+        // installed on disk. That difference is the whole point: it is how a
+        // caller learns the daemon is serving code that has been superseded.
         response.end(`${JSON.stringify({ schema: 'lattice.todo_dashboard_health.v1', pid: process.pid,
-          port: actualPort, project_ids: registry.list().map(({ projectId }) => projectId) })}\n`);
+          port: actualPort, project_ids: registry.list().map(({ projectId }) => projectId),
+          version: TODO_DASHBOARD_CODE_VERSION })}\n`);
         return;
       }
       if (url.pathname === '/' || url.pathname === '/projects/') {

package/src/todo-gantt-scope.mjs

@@ -10,10 +10,16 @@
  * where that projection narrows.
  *
  * The rule is "fold the dead branches": a completed ToDo that no longer leads
- * to any live work is history, and history collapses into one labelled node
- * per finished branch. Completed ToDos that are still the direct premise of
- * live work stay visible, because they are the context for what is dispatchable
- * right now.
+ * to any live work is history, and history collapses into as few labelled nodes
+ * as the graph allows — one per plan when nothing forbids it. Completed ToDos
+ * that are still the direct premise of live work stay visible, because they are
+ * the context for what is dispatchable right now.
+ *
+ * Grouping by connectivity was tried first and does not compress real plans: a
+ * store whose finished ToDos rarely declare dependencies on each other yields
+ * one fold unit per ToDo, which draws the same number of boxes as no folding at
+ * all while hiding every title. History is grouped by the plan it belongs to,
+ * not by whether its members happen to be wired together.
  *
  * This module is pure graph math over the layout's internal node/edge shape.
  * It must run AFTER dependency waves, the longest dependency chain and the
@@ -89,50 +95,59 @@ function foldableKeys(nodes, distance, foldDistance) {
 }
 
 /**
- * Group foldable nodes into fold units.
+ * Grouping strategies, coarsest first. The projection takes the first one whose
+ * contraction stays acyclic.
+ *
+ * - `plan`: one fold unit per plan. All history of a finished plan becomes one
+ *   node. This is the target shape and it is what a reader wants to see.
+ * - `plan_stage`: additionally split per kept-node depth. A cycle can only close
+ *   through a node kept on screen, and that axis is exactly what `keptDepth`
+ *   measures, so this is the smallest refinement that removes the usual cause.
+ * - `plan_wave`: additionally split per dependency wave. Provably acyclic —
+ *   every dependency edge strictly increases the wave, so a contracted edge
+ *   between two units always increases it too and no cycle can exist.
+ */
+const GROUPING_LADDER = Object.freeze(['plan', 'plan_stage', 'plan_wave']);
+
+/**
+ * Number of kept (non-foldable) nodes lying before each node on the longest
+ * path. Crossing a kept node strictly increases it; edges between two foldable
+ * nodes leave it unchanged.
  *
- * `byComponent` groups each weakly connected component of the foldable subgraph
- * into one unit — the compact projection, one node per finished branch.
- * `byComponentAndWave` additionally splits each component per dependency wave.
- * The latter is always acyclic once contracted (every dependency edge strictly
- * increases the wave, so contracted edges do too), which makes it the
- * guaranteed-safe refinement when contraction would otherwise close a cycle.
+ * Edges always increase the wave (`assignWaves` is a longest-path layering), so
+ * visiting nodes in ascending wave order settles every predecessor first.
  */
-function groupFoldable(nodes, edges, foldable, wave, splitByWave) {
-  const parent = new Map([...foldable].map((key) => [key, key]));
-  const find = (key) => {
-    let root = key;
-    while (parent.get(root) !== root) root = parent.get(root);
-    let cursor = key;
-    while (parent.get(cursor) !== root) {
-      const next = parent.get(cursor);
-      parent.set(cursor, root);
-      cursor = next;
+function keptDepth(nodes, edges, foldable, wave) {
+  const incoming = new Map(nodes.map(({ key }) => [key, []]));
+  for (const edge of edges) incoming.get(edge.to).push(edge.from);
+  const depth = new Map();
+  const ordered = [...nodes].sort((left, right) => wave.get(left.key) - wave.get(right.key)
+    || compareText(left.key, right.key));
+  for (const node of ordered) {
+    let best = 0;
+    for (const predecessor of incoming.get(node.key)) {
+      const settled = depth.get(predecessor);
+      if (settled === undefined) continue;
+      const candidate = settled + (foldable.has(predecessor) ? 0 : 1);
+      if (candidate > best) best = candidate;
     }
-    return root;
-  };
-  const union = (left, right) => {
-    const leftRoot = find(left);
-    const rightRoot = find(right);
-    if (leftRoot === rightRoot) return;
-    if (compareText(leftRoot, rightRoot) <= 0) parent.set(rightRoot, leftRoot);
-    else parent.set(leftRoot, rightRoot);
-  };
-  const nodeByKey = new Map(nodes.map((node) => [node.key, node]));
-  for (const edge of edges) {
-    if (!foldable.has(edge.from) || !foldable.has(edge.to)) continue;
-    // A fold unit never spans plans: the diagram groups by plan and a unit that
-    // straddled two plans would have no honest lane to sit in.
-    if (nodeByKey.get(edge.from).ref.plan_key !== nodeByKey.get(edge.to).ref.plan_key) continue;
-    union(edge.from, edge.to);
+    depth.set(node.key, best);
   }
+  return depth;
+}
 
+/** Group foldable nodes into fold units under one of `GROUPING_LADDER`. */
+function groupFoldable(nodes, foldable, strategy, axes) {
+  const nodeByKey = new Map(nodes.map((node) => [node.key, node]));
+  // A fold unit never spans plans: the diagram groups by plan and a unit that
+  // straddled two plans would have no honest lane to sit in.
+  const axisOf = (key) => (strategy === 'plan' ? null
+    : strategy === 'plan_stage' ? axes.stage.get(key)
+      : axes.wave.get(key));
   const unitByNode = new Map();
   const members = new Map();
   for (const key of [...foldable].sort(compareText)) {
-    const unitKey = splitByWave
-      ? JSON.stringify([find(key), wave.get(key)])
-      : JSON.stringify([find(key), null]);
+    const unitKey = JSON.stringify([nodeByKey.get(key).ref.plan_key, axisOf(key)]);
     unitByNode.set(key, unitKey);
     if (!members.has(unitKey)) members.set(unitKey, []);
     members.get(unitKey).push(key);
@@ -249,15 +264,14 @@ function isAcyclic(nodes, edges) {
 /**
  * Project the full dependency graph onto the `live` scope.
  *
- * Contracting a weakly connected component can close a cycle: with a fold
- * distance of 1 the shape `f1 -> s -> f2` is reachable, where `s` is a
- * completed ToDo kept as the direct premise of live work and `f1`/`f2` belong
- * to the same fold unit. Contracting that unit would produce
- * `summary -> s -> summary`. So the contraction is verified, and on a cycle the
- * grouping is refined to (component, wave) — provably acyclic, because every
- * dependency edge strictly increases the wave.
+ * Contraction can close a cycle: with a fold distance of 1 the shape
+ * `f1 -> s -> f2` is reachable, where `s` is a completed ToDo kept as the direct
+ * premise of live work and `f1`/`f2` land in the same fold unit. Contracting
+ * that unit would produce `summary -> s -> summary`. So each candidate grouping
+ * is verified and the coarsest acyclic one wins. The last rung is provably
+ * acyclic, so the throw below is a backstop, never a routine outcome.
  *
- * @returns {{nodes: Array, edges: Array, foldedByKey: Map, folds: Array, refined: boolean}}
+ * @returns {{nodes: Array, edges: Array, foldedByKey: Map, folds: Array, grouping: string}}
  */
 export function projectTodoGanttScope({
   nodes, edges, wave, longestChainKeys = new Set(), foldDistance = DEFAULT_FOLD_DISTANCE,
@@ -265,24 +279,25 @@ export function projectTodoGanttScope({
   const distance = distanceToLive(nodes, edges, wave);
   const foldable = foldableKeys(nodes, distance, foldDistance);
   if (foldable.size === 0) {
-    return { nodes, edges, foldedByKey: new Map(), folds: [], refined: false };
+    return { nodes, edges, foldedByKey: new Map(), folds: [], grouping: null };
   }
 
-  let refined = false;
-  let grouping = groupFoldable(nodes, edges, foldable, wave, false);
-  let summaryByUnit = buildSummaryNodes(nodes, grouping.members, longestChainKeys);
-  let contracted = contract(nodes, edges, grouping.unitByNode, summaryByUnit);
-  if (!isAcyclic(contracted.nodes, contracted.edges)) {
-    refined = true;
-    grouping = groupFoldable(nodes, edges, foldable, wave, true);
-    summaryByUnit = buildSummaryNodes(nodes, grouping.members, longestChainKeys);
-    contracted = contract(nodes, edges, grouping.unitByNode, summaryByUnit);
-    if (!isAcyclic(contracted.nodes, contracted.edges)) {
-      throw new TodoGanttScopeError('TODO_SCOPE_CONTRACTION_CYCLIC',
-        'todo gantt scope contraction produced a cycle after per-wave refinement',
-        { fold_unit_count: grouping.members.size });
-    }
+  const axes = { wave, stage: keptDepth(nodes, edges, foldable, wave) };
+  let selected = null;
+  for (const strategy of GROUPING_LADDER) {
+    const grouping = groupFoldable(nodes, foldable, strategy, axes);
+    const summaryByUnit = buildSummaryNodes(nodes, grouping.members, longestChainKeys);
+    const contracted = contract(nodes, edges, grouping.unitByNode, summaryByUnit);
+    if (!isAcyclic(contracted.nodes, contracted.edges)) continue;
+    selected = { strategy, grouping, summaryByUnit, contracted };
+    break;
   }
+  if (selected === null) {
+    throw new TodoGanttScopeError('TODO_SCOPE_CONTRACTION_CYCLIC',
+      'todo gantt scope contraction produced a cycle under every grouping',
+      { attempted_groupings: [...GROUPING_LADDER] });
+  }
+  const { grouping, summaryByUnit, contracted } = selected;
 
   const foldedByKey = new Map();
   for (const [nodeKey, unitKey] of grouping.unitByNode) {
@@ -292,5 +307,7 @@ export function projectTodoGanttScope({
     .sort((left, right) => compareText(left.key, right.key))
     .map((summary) => ({ ref: { ...summary.ref }, ...summary.fold }));
 
-  return { nodes: contracted.nodes, edges: contracted.edges, foldedByKey, folds, refined };
+  return {
+    nodes: contracted.nodes, edges: contracted.edges, foldedByKey, folds, grouping: selected.strategy,
+  };
 }