@quolu/lattice 0.77.0 → 0.78.1

package/README.ja.md

@@ -386,8 +386,11 @@ pidへは送りません（pid再利用で無関係のprocessを止めうるた
 [ADR 0157](https://github.com/kitepon/Lattice/blob/main/docs/adr/0157-dashboard-daemons-are-discoverable-by-record.md)が正です。
 状態を書き込む`start / block / unblock / done / evidence promote / reopen / note / independence mode /
 revise / revise-phase / revise-set / phase review|accept|reject|reopen|close-unaudited|baseline /
-dashboard adopt`では、監査actorとして次の3環境変数を渡せます。未設定ならhost／`session`／USERから
-defaultします。渡した値がidentifierとして不正なら`ACTOR_UNRESOLVED`です。
+dashboard adopt`では、監査actorとして次の3環境変数を渡せます。未設定なら、hostは端末ごとのlabel
+（`terminal-`と16進12桁）、sessionは`session`、agentはUSERになります。hostのlabelは端末の乱数の識別子
+（`~/.lattice/bridge-hub-terminal.json`）から導き、OSのhost名はjournalへ書きません
+（[ADR 0197](https://github.com/kitepon/Lattice/blob/main/docs/adr/0197-terminal-label-instead-of-os-hostname.md)）。
+渡した値がidentifierとして不正なら`ACTOR_UNRESOLVED`です。
 
 ```bash
 export LATTICE_TODO_ACTOR_HOST=<host-id>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.77.0",
+  "version": "0.78.1",
   "description": "Schedulability compiler for multi-agent development: observe real code boundaries, refactor the conflicting seam, recompile the plan for parallel execution",
   "author": {
     "name": "Quo / クオ at kitepon.dev",

package/src/bridge-hub-heartbeat.mjs

@@ -16,22 +16,21 @@
  */
 
 import { randomBytes } from 'node:crypto';
-import { hostname } from 'node:os';
 import { link, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { bridgeConfigPaths } from './bridge-config.mjs';
 import { BRIDGE_HUB_HEARTBEAT_INTERVAL_MS, validateBridgeHubRegistrationRequest } from './bridge-hub-protocol.mjs';
+import { TERMINAL_IDENTIFIER, TERMINAL_IDENTITY_SCHEMA, terminalIdentityPath, terminalPublicLabel } from './terminal-identity.mjs';
 import { readServedTodoDashboardProjectIds } from './todo-dashboard-registry.mjs';
 
 export { BRIDGE_HUB_HEARTBEAT_INTERVAL_MS };
 
-const TERMINAL_IDENTITY_SCHEMA = 'lattice.bridge_hub_terminal_identity.v1';
 const HEARTBEAT_RESULT_SCHEMA = 'lattice.bridge_hub_heartbeat_result.v1';
 const REGISTRATION_REQUEST_SCHEMA = 'lattice.bridge_hub_registration_request.v1';
 const REGISTER_PATH = '__lattice/hub/register';
 const DEFAULT_TIMEOUT_MS = 5_000;
-const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const IDENTIFIER = TERMINAL_IDENTIFIER;
 
 export class BridgeHubHeartbeatError extends Error {
   constructor(code, message, detail = undefined, cause = undefined) {
@@ -42,10 +41,6 @@ export class BridgeHubHeartbeatError extends Error {
   }
 }
 
-function terminalIdentityPath(env) {
-  return path.join(bridgeConfigPaths(env).root, 'bridge-hub-terminal.json');
-}
-
 /**
  * This terminal's stable bridge-hub identity, created once and reused across
  * restarts. It must survive restarts: registration is a full-state
@@ -85,13 +80,15 @@ export async function readOrCreateBridgeHubTerminalId({ env = process.env } = {}
 }
 
 /**
- * The terminal's own display name, shown for every project it registers
- * (registry entries are per-project but `display_name` is terminal-wide —
- * ADR 0162 Decision 2). Hostname, not a project name: the active project set
- * changes heartbeat to heartbeat but the terminal's identity does not.
+ * The name this terminal registers under (ADR 0197). It is the public label
+ * derived from the terminal id, never the OS hostname: the hub landing is
+ * served to anyone, and a hostname routinely holds its owner's name. Still
+ * terminal-wide (ADR 0162 Decision 2) — the active project set changes
+ * heartbeat to heartbeat but the terminal's identity does not.
  */
-function terminalDisplayName() {
-  return hostname().slice(0, 128) || 'terminal';
+function terminalDisplayName(terminalId) {
+  // 不正なidはここで名付けず、下のrequest検証に型付きで落とさせる。
+  return typeof terminalId === 'string' && IDENTIFIER.test(terminalId) ? terminalPublicLabel(terminalId) : 'terminal';
 }
 
 /** Build and validate one registration/heartbeat request. Throws rather than
@@ -100,7 +97,7 @@ export function buildBridgeHubRegistrationRequest({ terminalId, port, projectIds
   const request = {
     schema: REGISTRATION_REQUEST_SCHEMA,
     terminal_id: terminalId,
-    display_name: terminalDisplayName(),
+    display_name: terminalDisplayName(terminalId),
     port,
     project_ids: [...new Set(projectIds)].sort((left, right) => left.localeCompare(right, 'en')),
     adopt: [...adopt],

package/src/bridge-hub-server.mjs

@@ -36,6 +36,7 @@ import {
   projectBridgeHubRegistry, validateBridgeHubRegistryEntry,
 } from './bridge-hub-protocol.mjs';
 import { escapeHtml, renderBridgeHubLanding } from './bridge-hub-landing.mjs';
+import { terminalPublicLabel } from './terminal-identity.mjs';
 
 const LOOPBACK = '127.0.0.1';
 const HUB_HTTP_ERROR_SCHEMA = 'lattice.bridge_hub_http_error.v1';
@@ -310,27 +311,43 @@ function validRegistryDocument(value) {
     && value.entries.every(validateBridgeHubRegistryEntry);
 }
 
+/** What a terminal is called on the public listing (ADR 0197). Never its self-reported name. */
+function publicTerminalName(terminalId, terminalDisplayNames) {
+  const label = terminalPublicLabel(terminalId);
+  return Object.hasOwn(terminalDisplayNames, label) ? terminalDisplayNames[label] : label;
+}
+
 const EMPTY_VISIBILITY = Object.freeze({
   hidden_project_ids: Object.freeze([]), hidden_terminal_ids: Object.freeze([]), display_names: Object.freeze({}),
+  terminal_display_names: Object.freeze({}),
 });
 
 function validVisibilityDocument(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
     && value.schema === HUB_PUBLIC_VISIBILITY_SCHEMA
     && Object.keys(value).every((key) =>
-      ['schema', 'hidden_project_ids', 'hidden_terminal_ids', 'display_names'].includes(key))
+      ['schema', 'hidden_project_ids', 'hidden_terminal_ids', 'display_names', 'terminal_display_names']
+        .includes(key))
     && Array.isArray(value.hidden_project_ids)
     && value.hidden_project_ids.every((entry) => typeof entry === 'string')
     && Array.isArray(value.hidden_terminal_ids)
     && value.hidden_terminal_ids.every((entry) => typeof entry === 'string')
     && value.display_names !== null && typeof value.display_names === 'object'
     && !Array.isArray(value.display_names)
-    && Object.values(value.display_names).every((entry) => typeof entry === 'string');
+    && Object.values(value.display_names).every((entry) => typeof entry === 'string')
+    // 任意（ADR 0197）。無い旧fileはそのまま読め、端末は導出labelで出る。
+    && (value.terminal_display_names === undefined
+      || (value.terminal_display_names !== null && typeof value.terminal_display_names === 'object'
+        && !Array.isArray(value.terminal_display_names)
+        && Object.values(value.terminal_display_names)
+          .every((entry) => typeof entry === 'string' && entry.length > 0 && entry === entry.trim())));
 }
 
 /**
  * Read the operator's public-visibility file (ADR 0164 Decision 3): which
- * projects/terminals stay off the public listing, and how project ids render.
+ * projects/terminals stay off the public listing, how project ids render, and
+ * what each terminal is called in public (`terminal_display_names`, keyed by
+ * the terminal's public label — ADR 0197).
  * Hot-read per request so edits apply without a hub restart. A missing file
  * hides nothing; a malformed file is a typed error, never a silent republish
  * of an internal terminal.
@@ -352,6 +369,7 @@ export async function readBridgeHubPublicVisibility({ env = process.env } = {})
     hidden_project_ids: document.hidden_project_ids,
     hidden_terminal_ids: document.hidden_terminal_ids,
     display_names: document.display_names,
+    terminal_display_names: document.terminal_display_names ?? EMPTY_VISIBILITY.terminal_display_names,
   };
 }
 
@@ -478,10 +496,18 @@ export async function startBridgeHubServer({
     // the codebase's existing posture of not leaking topology to public
     // responses (bridge-server.mjs's public bridge-health strips pid/address
     // the same way).
+    //
+    // `display_name` is the exception that proved the rule: it used to be the
+    // terminal's self-reported name, which was its OS hostname, published to
+    // anyone (ADR 0197). The public name is now the hub's to give — the
+    // operator's entry in `terminal_display_names`, else the label derived
+    // from the terminal id. What a terminal reports about itself stays in the
+    // registry, so a terminal still running an older Lattice cannot put its
+    // hostname back on the page, and neither can a stale offline entry.
     const view = projected.map((entry) => ({
       schema: HUB_PUBLIC_PROJECT_SCHEMA,
       project_id: entry.project_id,
-      display_name: entry.display_name,
+      display_name: publicTerminalName(entry.terminal_id, visibility.terminal_display_names),
       status: entry.status,
       last_seen_at: entry.last_seen_at,
     }));

package/src/terminal-identity.mjs

@@ -0,0 +1,98 @@
+/**
+ * This terminal's identity and the label it shows to others (ADR 0197).
+ *
+ * The identity is a random id kept in the Lattice config root. It was born as
+ * the bridge-hub's routing key (`bridge-hub-heartbeat.mjs`, ADR 0162) and stays
+ * that: the id itself never leaves the terminal↔hub wire.
+ *
+ * The label is what leaves. Todo journals are committed into public
+ * repositories and the hub landing is served to anyone, so neither may carry
+ * the OS hostname — a hostname is free text the operating system chose, and
+ * it routinely holds its owner's name. The label is derived one-way from the
+ * id: stable per terminal, so records and the landing still tell terminals
+ * apart, and it says nothing about the machine or the person.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { bridgeConfigPaths } from './bridge-config.mjs';
+
+export const TERMINAL_IDENTITY_SCHEMA = 'lattice.bridge_hub_terminal_identity.v1';
+export const TERMINAL_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+const LABEL_DOMAIN = 'lattice.terminal_public_label.v1';
+const LABEL_HEX_LENGTH = 12;
+
+export function terminalIdentityPath(env = process.env) {
+  return path.join(bridgeConfigPaths(env).root, 'bridge-hub-terminal.json');
+}
+
+/**
+ * The label a terminal is shown under in journals and on the hub landing.
+ * One-way: the routing id cannot be recovered from it, so publishing the label
+ * does not hand out the key the hub reconciles registrations by.
+ */
+export function terminalPublicLabel(terminalId) {
+  if (typeof terminalId !== 'string' || !TERMINAL_IDENTIFIER.test(terminalId)) {
+    throw new TypeError('terminal id is invalid');
+  }
+  const digest = createHash('sha256').update(`${LABEL_DOMAIN}\0${terminalId}`).digest('hex');
+  return `terminal-${digest.slice(0, LABEL_HEX_LENGTH)}`;
+}
+
+/** Whether a recorded host name is a public label — the only shape a published page may show as-is (ADR 0198). */
+export function isTerminalPublicLabel(value) {
+  return typeof value === 'string' && /^terminal-[0-9a-f]{12}$/u.test(value);
+}
+
+/**
+ * Synchronous twin of `readOrCreateBridgeHubTerminalId`: same file, same
+ * schema, same no-overwrite publish. The todo CLI resolves its actor
+ * synchronously on every mutation, and both paths must agree on one id per
+ * terminal — a second file would give the journal and the landing two
+ * different labels for the same machine.
+ *
+ * Returns `null` when the id can be neither read nor created (read-only or
+ * missing home, invalid file). The caller decides what an unidentified
+ * terminal is called; this function never invents an id it could not persist,
+ * because an unpersisted id would change on every call.
+ */
+export function readOrCreateTerminalIdSync({ env = process.env } = {}) {
+  let ref;
+  try {
+    ref = terminalIdentityPath(env);
+    mkdirSync(path.dirname(ref), { recursive: true, mode: 0o700 });
+  } catch {
+    return null;
+  }
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const value = JSON.parse(readFileSync(ref, 'utf8'));
+      return value?.schema === TERMINAL_IDENTITY_SCHEMA && TERMINAL_IDENTIFIER.test(value.terminal_id)
+        ? value.terminal_id : null;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return null;
+    }
+    const terminalId = randomBytes(16).toString('hex');
+    const temporary = `${ref}.${terminalId}.tmp`;
+    try {
+      writeFileSync(temporary, `${JSON.stringify({ schema: TERMINAL_IDENTITY_SCHEMA, terminal_id: terminalId })}\n`,
+        { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    } catch {
+      return null;
+    }
+    try {
+      // 完成済みのbytesだけを、既存のIDを上書きせず公開する。
+      linkSync(temporary, ref);
+      return terminalId;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') return null;
+      // 同時生成の勝者が公開した完成済みIDを読む。
+    } finally {
+      try { unlinkSync(temporary); } catch { /* 一時fileは残っても識別子を壊さない */ }
+    }
+  }
+  return null;
+}

package/src/todo-cli.mjs

@@ -2,9 +2,6 @@ import { cliCommandKind } from './cli-command-kind.mjs';
 import { cliFailureClass } from './cli-failure-class.mjs';
 import { gitSync } from './git-process.mjs';
 import { createHash } from 'node:crypto';
-import {
-  hostname,
-} from 'node:os';
 import {
   lstat, mkdir, readFile, realpath, writeFile,
 } from 'node:fs/promises';
@@ -39,6 +36,7 @@ import {
   ensureTodoDashboardActivity,
   removeTodoDashboardProject,
 } from './todo-dashboard-registry.mjs';
+import { readOrCreateTerminalIdSync, terminalPublicLabel } from './terminal-identity.mjs';
 import { readProjectExternalPane, resolveProjectIdentity } from './project-identity.mjs';
 import { layoutTodoGantt } from './todo-gantt-layout.mjs';
 import { TODO_GANTT_SCOPES } from './todo-gantt-scope.mjs';
@@ -563,6 +561,16 @@ function sanitizeActorIdentifier(raw, fallback) {
   return isTodoIdentifier(compact) ? compact : fallback;
 }
 
+/**
+ * 名乗りの無い操作のhost（ADR 0197）。journalは公開repositoryへcommitされるので、OSのhost名は
+ * 書かない——host名はOSが決めた自由文で、持ち主の名前を含むことがある。端末ごとの識別子から
+ * 一方向に導いたlabelを使い、端末の区別は保つ。識別子を読めず作れない端末は`host`になる。
+ */
+function defaultActorHost(env) {
+  const terminalId = readOrCreateTerminalIdSync({ env });
+  return terminalId === null ? 'host' : terminalPublicLabel(terminalId);
+}
+
 function mutationActor(env) {
   const provided = ACTOR_ENV_KEYS.map((key) => ({ key, value: env[key] }));
   const invalidEnvironment = provided
@@ -579,7 +587,7 @@ function mutationActor(env) {
   return {
     host: isTodoIdentifier(env.LATTICE_TODO_ACTOR_HOST)
       ? env.LATTICE_TODO_ACTOR_HOST
-      : sanitizeActorIdentifier(hostname(), 'host'),
+      : defaultActorHost(env),
     session: isTodoIdentifier(env.LATTICE_TODO_ACTOR_SESSION)
       ? env.LATTICE_TODO_ACTOR_SESSION
       : 'session',

package/src/todo-gantt-html-independence.mjs

@@ -5,8 +5,39 @@ import {
   renderTodoStructurePanel,
 } from './todo-gantt-structure.mjs';
 import { renderTodoMarkdown } from './todo-markdown-renderer.mjs';
+import { isTerminalPublicLabel } from './terminal-identity.mjs';
 
-function renderNoteContext(context) {
+/**
+ * 記録に残る端末名を、ページへ出す名前へ写す（ADR 0198）。
+ *
+ * journalと作業記録の`actor.host`は、書いた時の自由文である——OSのhost名のことも、席が自分で付けた名前の
+ * こともあり、持ち主の名前を含みうる。ページは公開面へ配信されるので、そのまま出さない。出してよいのは
+ * 端末の公開label（`terminal-`と16進12桁）だけで、それ以外は同じ名前に同じ番号を振った「端末N」にする。
+ * 番号はその名前が最初に記録された時刻の順で、同時刻は名前の順。記録は追記だけなので、後から現れた名前は
+ * 後ろの番号になり、既に振った番号は動かない。記録の本体は変えない——変えるのは表示だけである。
+ */
+export function recordedHostDisplayNames(sections) {
+  const firstSeen = new Map();
+  for (const section of sections) {
+    for (const note of section.noteContext?.notes ?? []) {
+      const host = note.actor.host;
+      if (isTerminalPublicLabel(host)) continue;
+      const known = firstSeen.get(host);
+      if (known === undefined || note.recorded_at < known) firstSeen.set(host, note.recorded_at);
+    }
+  }
+  const ordered = [...firstSeen].sort(([leftHost, leftAt], [rightHost, rightAt]) => (
+    leftAt < rightAt ? -1 : leftAt > rightAt ? 1 : leftHost < rightHost ? -1 : leftHost > rightHost ? 1 : 0));
+  return new Map(ordered.map(([host], index) => [host, `端末${index + 1}`]));
+}
+
+function recordedHostDisplayName(host, displayNames) {
+  if (isTerminalPublicLabel(host)) return host;
+  // 対応表に無い名前を素通しにしない。表を作る側の漏れは、名前でなく固定の語として現れる。
+  return displayNames.get(host) ?? '端末';
+}
+
+function renderNoteContext(context, hostDisplayNames) {
   if (context === null) {
     return '<section class="work-log"><h2>作業記録</h2><p class="note-warning">作業記録を読み取れません。概要の読取警告を確認してください。</p></section>';
   }
@@ -21,7 +52,7 @@ function renderNoteContext(context) {
       ? `訂正済み（後継 ${note.superseded_by.slice(0, 12)}…）` : '現行';
     // UTCのまま埋め、閲覧者の現地時刻への変換はブラウザ側へ委ねる（title属性に原文を残す）。
     const stamp = `<time datetime="${escapeHtmlAttribute(note.recorded_at)}" title="${escapeHtmlAttribute(note.recorded_at)}" data-utc-stamp>${escapeHtmlText(note.recorded_at)}</time>`;
-    return `<article class="work-log-entry"><header>${stamp}<span>${escapeHtmlText(correction)}</span></header><div class="work-log-body">${rendered.html}</div>${filtering}<p class="work-log-origin">来歴: ${escapeHtmlText(note.origin_plan_version)}/${escapeHtmlText(note.origin_task_id)}・記録者 ${escapeHtmlText(`${note.actor.host}/${note.actor.agent}`)}</p></article>`;
+    return `<article class="work-log-entry"><header>${stamp}<span>${escapeHtmlText(correction)}</span></header><div class="work-log-body">${rendered.html}</div>${filtering}<p class="work-log-origin">来歴: ${escapeHtmlText(note.origin_plan_version)}/${escapeHtmlText(note.origin_task_id)}・記録者 ${escapeHtmlText(`${recordedHostDisplayName(note.actor.host, hostDisplayNames)}/${note.actor.agent}`)}</p></article>`;
   }).join('');
   const overflow = context.overflow_count === 0 ? ''
     : `<p class="note-warning">ほか ${context.overflow_count}件は上限のため省略。全履歴: <code>${escapeHtmlText(context.full_history_command)}</code></p>`;
@@ -144,6 +175,8 @@ export function renderRightPane(
   structurePresentation = null,
 ) {
   const lookup = presentationLookup(presentation);
+  // 番号はproject全体で1つの対応表から振る。工程ごとに振ると、同じ端末が工程によって別の番号になる。
+  const hostDisplayNames = recordedHostDisplayNames(sections);
   const sectionByKey = new Map(sections.map((section) => [refKey(section.ref), section]));
   const semanticNodes = [...layout.nodes, ...(layout.hierarchy_nodes ?? [])];
   const nodeByKey = new Map(semanticNodes.map((node) => [refKey(node.ref), node]));
@@ -212,7 +245,7 @@ export function renderRightPane(
       : expandable
         ? '<p class="fold-note">完走済みのため既定の図には描いていません。左上の「完走済み」バッジを押すと、このページ内で表示できます。</p>'
         : '<p class="fold-note">完走済みのため図には描いていません。図に出すには動的dashboardを <code>lattice todo gantt serve --port &lt;port&gt; --scope all</code> で起動してください。</p>';
-    const workLog = notesEnabled ? renderNoteContext(section.noteContext) : '';
+    const workLog = notesEnabled ? renderNoteContext(section.noteContext, hostDisplayNames) : '';
     const designMemo = renderDesignMemo(section.task);
     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}${independenceNote}${foldedNote}${designMemo}<section><h2>前提工程</h2>${renderRelationList(incoming.get(key), sectionByKey, lookup, '登録済みの前提工程はありません。', folds)}</section><section><h2>後続工程</h2>${renderRelationList(outgoing.get(key), sectionByKey, lookup, '登録済みの後続工程はありません。', folds)}</section>${workLog}<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('');