@quolu/lattice 0.12.10 → 0.12.12

package/package.json

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

@@ -45,9 +45,9 @@ Read commands:
   status [--json]
   verify [--plan <key>] [--json]
   snapshot --rebuild --plan <key>
-  gantt [--out <file>]
+  gantt [--out <file>] [--scope live|all]  # 既定live: 完走した枝を畳む
   gantt status [--out <file>]
-  gantt serve --port <port>  # /projects/<project_id>/ をforeground配信
+  gantt serve --port <port> [--scope live|all]  # /projects/<project_id>/ をforeground配信
   phase status --plan <key>
 
 Write commands:
@@ -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送信元から決める。
 `,
 });
 
@@ -106,7 +110,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'todo status': 'todo status [--json]',
   'todo verify': 'todo verify [--plan <key>] [--json]',
   'todo snapshot': 'todo snapshot --rebuild --plan <key>',
-  'todo gantt': 'todo gantt [--out <file>] | status [--out <file>] | serve --port <port>',
+  'todo gantt': 'todo gantt [--out <file>] [--scope live|all] | status [--out <file>] | serve --port <port> [--scope live|all]',
   'todo phase': 'todo phase <status|review|accept|reject|reopen> --plan <key> [options]',
   'todo phase status': 'todo phase status --plan <key>',
   'todo phase review': 'todo phase review --plan <key> --phase <id> --reason <text>',
@@ -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) {