@quolu/lattice 0.71.1 → 0.72.1

package/bin/lattice-mcp.mjs

@@ -126,8 +126,8 @@ if (nodeVersionGuard.blocked) {
       await server.start();
     } catch (err) {
       // opt-in runtime error store（既定OFF・config有効時のみ）。観測失敗はstderr一行のbest-effort。
-      const { observeRuntimeError } = await import('../src/runtime-errors.mjs');
-      observeRuntimeError('LATTICE.MCP_SERVER_FAILED');
+      const { observeRuntimeError, runtimeErrorSafeContext } = await import('../src/runtime-errors.mjs');
+      observeRuntimeError('LATTICE.MCP_SERVER_FAILED', { safeContext: runtimeErrorSafeContext({ error: err }) });
       startupFailure('MCP_STARTUP_FAILED', err instanceof Error ? err.message : String(err));
     }
   }

package/bin/lattice.mjs

@@ -10,6 +10,8 @@ installPipeCloseGuard();
 const args = process.argv.slice(2);
 // 作業ディレクトリを読まないsurface。cwdが消えた席（閉じたworktree）からでも動かす。
 const CWD_FREE_COMMANDS = new Set(['runtime-errors', 'bridge', 'hooks', 'setup', 'factory-diagnostics']);
+// 内部故障の観測（下のobserveInternalFailure）が終わるのを、exit前に待つための置き場。
+let pendingObservation = Promise.resolve();
 installSqliteExperimentalWarningFilter();
 const help = renderCliHelp(args);
 
@@ -129,7 +131,9 @@ if (help !== null) {
     cwd: process.cwd(),
     stdout: process.stdout,
     stderr: process.stderr,
+    onInternalFailure: (error, commandKind) => observeInternalFailure(error, commandKind),
   });
+  await pendingObservation;
 } else if (args[0] === 'bridge') {
   const { runBridgeCli } = await import('../src/bridge-cli.mjs');
   process.exitCode = await runBridgeCli({
@@ -154,8 +158,9 @@ if (help !== null) {
     });
   } catch (error) {
     // typed契約（cli_error.v2＋exit 1/2）の外へ漏れた例外＝内部故障。opt-in時のみ観測を残す。
-    const { observeRuntimeError } = await import('../src/runtime-errors.mjs');
-    observeRuntimeError('LATTICE.CLI_INTERNAL_FAILED', { version: packageJson.version });
+    const { cliCommandKind } = await import('../src/cli-command-kind.mjs');
+    observeInternalFailure(error, cliCommandKind(args));
+    await pendingObservation;
     // **理由を捨てない。** 型名だけでは、何が起きたかを追う手段が無い——実際、seam解決の
     // `witness_set_invalid`はAPIを直接叩くまで見えなかった。typed契約の外へ漏れたこと自体は
     // 内部故障だが、漏れた中身は残す。
@@ -172,6 +177,16 @@ if (help !== null) {
   }
 }
 
+// typed契約の外へ漏れた例外を、opt-inのruntime error記録へ残す。どの面で・どの種類の例外で
+// 落ちたかを固定語彙の分類（safe_context）で添える——error_codeだけでは原因を追えなかった。
+function observeInternalFailure(error, commandKind) {
+  pendingObservation = import('../src/runtime-errors.mjs').then(({ observeRuntimeError, runtimeErrorSafeContext }) => {
+    observeRuntimeError('LATTICE.CLI_INTERNAL_FAILED', {
+      version: packageJson.version, safeContext: runtimeErrorSafeContext({ commandKind, error }),
+    });
+  }).catch(() => {});
+}
+
 function workingDirectory() {
   try {
     return process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.71.1",
+  "version": "0.72.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/cli-command-kind.mjs

@@ -0,0 +1,20 @@
+/**
+ * 落ちたCLIの面を、固定の語彙（`<surface>`か`<surface>.<subcommand>`）へ写す。
+ *
+ * runtime error記録の`safe_context.command_kind`に載る値で、工場reportを通ってBugHubまで運ばれる。
+ * 利用者が打った引数の値（run ref・path・plan key等）は載せない——この一覧に在る語だけを返し、
+ * 一覧に無い語は面の名前だけ、面も無ければ`other`へ落とす。
+ */
+const RUNTIME_SURFACES = Object.freeze({
+  plan: Object.freeze(['compile', 'verify']),
+  run: Object.freeze(['abandon', 'activate', 'adapter', 'close', 'conflict', 'finding', 'hold', 'intake',
+    'landing', 'list', 'observe', 'recompile', 'reprocess', 'request', 'resume', 'seam', 'start', 'status']),
+  event: Object.freeze(['verify']),
+});
+
+export function cliCommandKind(argv, surfaces = RUNTIME_SURFACES) {
+  if (!Array.isArray(argv)) return 'other';
+  const [surface, subcommand] = argv;
+  if (typeof surface !== 'string' || !Object.hasOwn(surfaces, surface)) return 'other';
+  return surfaces[surface].includes(subcommand) ? `${surface}.${subcommand}` : surface;
+}

package/src/runtime-errors.mjs

@@ -37,6 +37,18 @@ const definitions = Object.freeze({
   'LATTICE.MCP_SERVER_FAILED': { component: 'mcp', severity: 'high', template: 'Lattice MCP server failed' },
 });
 
+// safe_context（工場wireの任意欄）。固定語彙だけを載せ、message本文・path・引数の値・stackは載せない。
+// 3つのキーは必ずそろえる——fingerprintがこの3つを含むので、欠けると記録を一意に決められない。
+const SAFE_CONTEXT_KEYS = Object.freeze(['command_kind', 'error_kind', 'cause_code']);
+const ERROR_KINDS = new Set(['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'AggregateError', 'SystemError']);
+const COMMAND_KIND = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)?$/;
+const COMMAND_KIND_MAX = 48;
+// Nodeが付けるerror code（ENOENT・ERR_MODULE_NOT_FOUND等）だけを通す。Lattice自身のcodeや任意文字列は`none`。
+const CAUSE_CODE = /^(?:E[A-Z0-9]{2,15}|ERR_[A-Z0-9_]{1,60})$/;
+// 工場の`factory-reporter.json`が名乗る端末の種類。dotagentsの契約（lib/factory/contract.mjs）と同じ語を
+// 受ける——ここに無い語の端末は設定全体が無効とみなされ、故障を1件も記録しない。
+const HOST_PROFILES = Object.freeze(['server', 'mac', 'linux', 'wsl', 'windows-native']);
+
 const plain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const exact = (value, keys) => Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
 const validTime = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
@@ -74,7 +86,7 @@ function collectionEnabled(options = {}) {
     return plain(config) && exact(config, ['schema_version', 'host', 'collection', 'reporting'])
       && config.schema_version === '1.0' && plain(config.host) && exact(config.host, ['id', 'profile'])
       && typeof config.host.id === 'string' && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(config.host.id)
-      && ['server', 'mac', 'wsl', 'windows-native'].includes(config.host.profile)
+      && HOST_PROFILES.includes(config.host.profile)
       && plain(config.collection) && exact(config.collection, ['enabled']) && config.collection.enabled === true
       && canonicalReporting(config.reporting);
   } catch {
@@ -86,9 +98,35 @@ export function runtimeCollectionEnabled(env = process.env, configPath) {
   return collectionEnabled({ env, configPath });
 }
 
-function fingerprintOf(code) {
+const validCommandKind = (value) => typeof value === 'string' && value.length <= COMMAND_KIND_MAX && COMMAND_KIND.test(value);
+const validErrorKind = (value) => value === 'other' || ERROR_KINDS.has(value);
+const validCauseCode = (value) => value === 'none' || (typeof value === 'string' && CAUSE_CODE.test(value));
+const validSafeContext = (value) => plain(value) && exact(value, SAFE_CONTEXT_KEYS)
+  && validCommandKind(value.command_kind) && validErrorKind(value.error_kind) && validCauseCode(value.cause_code);
+
+/**
+ * 落ちた面と例外から、記録へ載せる固定語彙の分類を作る。語彙に無い値は`other`／`none`へ落とす
+ * ——呼び出し側が何を渡しても、利用者の入力やpathが記録へ入らない。
+ */
+export function runtimeErrorSafeContext({ commandKind, error } = {}) {
+  const errorKind = error?.constructor?.name;
+  return {
+    command_kind: validCommandKind(commandKind) ? commandKind : 'other',
+    error_kind: ERROR_KINDS.has(errorKind) ? errorKind : 'other',
+    cause_code: typeof error?.code === 'string' && CAUSE_CODE.test(error.code) ? error.code : 'none',
+  };
+}
+
+/**
+ * 旧記録（safe_context無し）はerror_codeだけで決まる式のまま。新しい記録は3つの分類も含める
+ * ——原因が違えば別の記録になる。式はdotagentsのadapterが再計算して照合する契約で、
+ * 連結順・NUL区切り・末尾区切り無しを変えない。
+ */
+function fingerprintOf(code, safeContext = null) {
   const definition = definitions[code];
-  return createHash('sha256').update(`${PRODUCT}\0${definition.component}\0${code}\0${definition.template}`).digest('hex');
+  const parts = [PRODUCT, definition.component, code, definition.template];
+  if (safeContext !== null) parts.push(...SAFE_CONTEXT_KEYS.map((key) => safeContext[key]));
+  return createHash('sha256').update(parts.join('\0')).digest('hex');
 }
 
 function assertPosix(info, mode) {
@@ -109,6 +147,8 @@ function ensureSafeFile(path) {
   assertPosix(statSync(path), 0o600);
 }
 
+const RECORD_KEYS = Object.freeze(['product', 'product_version', 'component', 'error_code', 'message_template', 'severity', 'fingerprint', 'count', 'first_seen', 'last_seen', 'state_schema_version', 'os', 'arch', 'status', 'resolved_at', 'reason_code', 'sequence']);
+
 const empty = () => ({ schema: RUNTIME_ERRORS_SCHEMA, next_sequence: 1, acknowledged_through: 0, records: [] });
 
 function validate(store) {
@@ -119,11 +159,13 @@ function validate(store) {
   const seen = new Set();
   let previous = 0;
   for (const record of store.records) {
-    if (!plain(record) || !exact(record, ['product', 'product_version', 'component', 'error_code', 'message_template', 'severity', 'fingerprint', 'count', 'first_seen', 'last_seen', 'state_schema_version', 'os', 'arch', 'status', 'resolved_at', 'reason_code', 'sequence'])) throw Error('state_invalid');
+    if (!plain(record) || (!exact(record, RECORD_KEYS) && !exact(record, [...RECORD_KEYS, 'safe_context']))) throw Error('state_invalid');
+    const safeContext = Object.hasOwn(record, 'safe_context') ? record.safe_context : null;
+    if (safeContext !== null && !validSafeContext(safeContext)) throw Error('state_invalid');
     const definition = definitions[record.error_code];
     if (!definition || record.product !== PRODUCT || !validVersion(record.product_version)
       || record.component !== definition.component || record.message_template !== definition.template
-      || record.severity !== definition.severity || record.fingerprint !== fingerprintOf(record.error_code)
+      || record.severity !== definition.severity || record.fingerprint !== fingerprintOf(record.error_code, safeContext)
       || seen.has(record.fingerprint) || !Number.isSafeInteger(record.count) || record.count < 1
       || !validTime(record.first_seen) || !validTime(record.last_seen)
       || Date.parse(record.first_seen) > Date.parse(record.last_seen)
@@ -219,7 +261,7 @@ function snapshot(options = {}) {
     version: options.version ?? 'unknown',
     state_schema_version: STATE_VERSION,
     cursor: { high_watermark: store.next_sequence - 1, acknowledged_through: store.acknowledged_through, next: rows.at(-1)?.sequence ?? afterCursor },
-    runtime_errors: rows.filter((record) => record.status === 'open').map(({ product_version, error_code, component, status, severity, fingerprint, message_template, count, first_seen, last_seen, state_schema_version }) => ({ product_version, error_code, component, status, severity, fingerprint, message_template, occurrence_count: count, first_seen, last_seen, state_schema_version })),
+    runtime_errors: rows.filter((record) => record.status === 'open').map(({ product_version, error_code, component, status, severity, fingerprint, message_template, count, first_seen, last_seen, state_schema_version, safe_context }) => ({ product_version, error_code, component, status, severity, fingerprint, message_template, occurrence_count: count, first_seen, last_seen, state_schema_version, ...(safe_context === undefined ? {} : { safe_context }) })),
     resolutions: rows.filter((record) => record.status === 'resolved').map(({ fingerprint, resolved_at, reason_code }) => ({ fingerprint, resolved_at, reason_code })),
     diagnostics: {
       collection: enabled ? 'enabled' : 'disabled',
@@ -264,7 +306,10 @@ export function recordRuntimeError(code, options = {}) {
   const { path } = optionsFor(options);
   return lock(path, () => {
     const store = readStore(path);
-    const key = fingerprintOf(code);
+    // 新しい発生は必ず分類つきの記録へ入る。分類を渡さない呼び出しは`other`／`none`で埋める。
+    const safeContext = options.safeContext === undefined ? runtimeErrorSafeContext() : options.safeContext;
+    if (!validSafeContext(safeContext)) throw Error('invalid_safe_context');
+    const key = fingerprintOf(code, safeContext);
     const sequence = store.next_sequence++;
     const time = now(options);
     const version = options.version ?? '0.0.0';
@@ -289,6 +334,7 @@ export function recordRuntimeError(code, options = {}) {
         message_template: definition.template, severity: definition.severity, fingerprint: key,
         count: 1, first_seen: time, last_seen: time, state_schema_version: STATE_VERSION,
         os, arch, status: 'open', resolved_at: null, reason_code: null, sequence,
+        safe_context: { ...safeContext },
       });
     }
     store.records.sort((a, b) => a.sequence - b.sequence);

package/src/todo-cli.mjs

@@ -1,3 +1,4 @@
+import { cliCommandKind } from './cli-command-kind.mjs';
 import { gitSync } from './git-process.mjs';
 import { createHash } from 'node:crypto';
 import {
@@ -3755,12 +3756,22 @@ async function repairStoreEol({ repoRoot }) {
  * `lattice todo` namespace. Exact position, order, and argument count are part of
  * the public contract; usage failures never use a JSON envelope.
  */
-export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env }) {
+export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env,
+  onInternalFailure = null }) {
   if (!Array.isArray(argv) || typeof cwd !== 'string'
     || typeof stdout?.write !== 'function' || typeof stderr?.write !== 'function'
-    || env === null || typeof env !== 'object' || Array.isArray(env)) {
+    || env === null || typeof env !== 'object' || Array.isArray(env)
+    || (onInternalFailure !== null && typeof onInternalFailure !== 'function')) {
     throw new TypeError('runTodoCli optionsが不正');
   }
+  // typed契約の外へ漏れた例外は、binが渡す観測口へも知らせる（opt-inのruntime error記録）。
+  // 観測口を持つのはprocess境界のbinだけ——このmoduleを直接呼ぶ試験や埋め込みは記録しない。
+  const failInternally = (error) => {
+    try {
+      onInternalFailure?.(error, cliCommandKind(['todo', ...argv], { todo: TODO_COMMAND_NAMES }));
+    } catch { /* 観測の失敗でCLIの応答を変えない */ }
+    return internalFailure(stderr, error);
+  };
 
   const atomicCommit = argv.at(-1) === '--commit-store';
   if (atomicCommit) argv = argv.slice(0, -1);
@@ -3777,7 +3788,7 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
       await runTodoSchemaCommand(argv[0], stdout);
       return 0;
     } catch (error) {
-      return internalFailure(stderr, error);
+      return failInternally(error);
     }
   }
 
@@ -3799,7 +3810,7 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     } catch (error) {
       if (typeof error?.code === 'string' && error.detail !== null
         && typeof error.detail === 'object') return typedFailure(stderr, error);
-      return internalFailure(stderr, error);
+      return failInternally(error);
     }
   }
 
@@ -4248,6 +4259,6 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
         message: error.message,
       });
     }
-    return internalFailure(stderr, error);
+    return failInternally(error);
   }
 }

package/src/todo-dashboard-registry.mjs

@@ -68,16 +68,12 @@ function validateRegistry(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)
     || value.schema !== REGISTRY_SCHEMA || !Array.isArray(value.projects)
     || !value.projects.every(validEntry)) {
-    const error = new Error('dashboard registry schema invalid');
-    error.code = 'DASHBOARD_REGISTRY_INVALID';
-    throw error;
+    throw dashboardError('DASHBOARD_REGISTRY_INVALID', 'dashboard registry schema invalid', { retry: false });
   }
   const ids = new Set();
   for (const entry of value.projects) {
     if (ids.has(entry.project_id)) {
-      const error = new Error(`dashboard project duplicate: ${entry.project_id}`);
-      error.code = 'DASHBOARD_REGISTRY_INVALID';
-      throw error;
+      throw dashboardError('DASHBOARD_REGISTRY_INVALID', `dashboard project duplicate: ${entry.project_id}`, { retry: false });
     }
     ids.add(entry.project_id);
   }
@@ -91,12 +87,25 @@ async function readJson(ref, missing) {
     throw error;
   }
   try { return JSON.parse(bytes); } catch {
-    const error = new Error(`invalid JSON: ${ref}`);
-    error.code = 'DASHBOARD_REGISTRY_INVALID';
-    throw error;
+    // local absolute pathをCLI errorへ運ばない。どのfileかは登録簿の置き場から決まる。
+    throw dashboardError('DASHBOARD_REGISTRY_INVALID', 'dashboard registry file is not valid JSON', { retry: false });
   }
 }
 
+/**
+ * 登録簿とdaemonの故障は、外部状態（別process・file・負荷）の不整合であって内部故障ではない。
+ * codeだけのErrorはCLIのtyped契約（code＋detail）に乗らず`INTERNAL_FAILURE`へ落ちていた
+ * ——launchdの`todo dashboard ensure`が、負荷時のlock待ち切れやdaemonの無応答をそう返していた。
+ * detailを必ず持たせ、再実行で解ける種類かどうかを`next_action`で伝える。
+ */
+function dashboardError(code, message, { retry = true } = {}) {
+  const error = new Error(message);
+  error.code = code;
+  error.detail = { reason: code.toLowerCase(),
+    next_action: retry ? 'lattice todo dashboard ensure --json' : null };
+  return error;
+}
+
 async function atomicJson(ref, value) {
   const temporary = `${ref}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
   await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx', flush: true });
@@ -131,9 +140,7 @@ async function withLock(lockRef, action) {
       await new Promise((resolve) => setTimeout(resolve, LOCK_WAIT_MS));
     }
   }
-  const error = new Error('dashboard registry lock timeout');
-  error.code = 'DASHBOARD_REGISTRY_BUSY';
-  throw error;
+  throw dashboardError('DASHBOARD_REGISTRY_BUSY', 'dashboard registry lock timeout');
 }
 
 export async function readActiveTodoDashboardProjects({ env = process.env, now = Date.now() } = {}) {
@@ -414,15 +421,11 @@ async function stopAttestedLegacyDaemon(descriptor, {
   const attestation = await daemonAttestation(descriptor);
   if (attestation !== 'legacy') {
     if (!await isProcessAlive(descriptor.pid) && attestation === null) return;
-    const error = new Error('legacy dashboard daemon attestation was lost before signal');
-    error.code = 'DASHBOARD_LEGACY_ATTESTATION_LOST';
-    throw error;
+    throw dashboardError('DASHBOARD_LEGACY_ATTESTATION_LOST', 'legacy dashboard daemon attestation was lost before signal');
   }
   if (!await requestDaemonShutdown(descriptor)) signalProcess(descriptor.pid, 'SIGTERM');
   if (await awaitDaemonStopped(descriptor, { isProcessAlive, deadline: Date.now() + timeoutMs })) return;
-  const error = new Error('legacy dashboard daemon did not stop');
-  error.code = 'DASHBOARD_LEGACY_STOP_FAILED';
-  throw error;
+  throw dashboardError('DASHBOARD_LEGACY_STOP_FAILED', 'legacy dashboard daemon did not stop');
 }
 
 /**
@@ -444,9 +447,7 @@ async function stopStrayDaemon(descriptor, {
   if (await awaitDaemonStopped(descriptor, {
     isProcessAlive, deadline: Date.now() + (timeoutMs - half),
   })) return true;
-  const error = new Error('stray dashboard daemon did not stop');
-  error.code = 'DASHBOARD_ORPHAN_STOP_FAILED';
-  throw error;
+  throw dashboardError('DASHBOARD_ORPHAN_STOP_FAILED', 'stray dashboard daemon did not stop');
 }
 
 /**
@@ -493,9 +494,7 @@ async function stopSpawnedReplacement(child, descriptor, {
     if (await stopped()) return;
     await new Promise((resolve) => setTimeout(resolve, 50));
   }
-  const error = new Error('replacement dashboard daemon rollback did not stop');
-  error.code = 'DASHBOARD_REPLACEMENT_ROLLBACK_FAILED';
-  throw error;
+  throw dashboardError('DASHBOARD_REPLACEMENT_ROLLBACK_FAILED', 'replacement dashboard daemon rollback did not stop');
 }
 
 function currentDaemonRecord(port) {
@@ -545,9 +544,7 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
     if (validDaemonDescriptor(existing) && existingAttestation === null
       && await isProcessAlive(existing.pid)
       && !await descriptorPidWasReused(existing, { observeProcessStartEpochMs })) {
-      const error = new Error('dashboard daemon is alive but temporarily unresponsive');
-      error.code = 'DASHBOARD_DAEMON_UNRESPONSIVE';
-      throw error;
+      throw dashboardError('DASHBOARD_DAEMON_UNRESPONSIVE', 'dashboard daemon is alive but temporarily unresponsive');
     }
     let legacy = existingAttestation === 'legacy' ? existing : null;
     if (legacy === null) {
@@ -610,9 +607,7 @@ export async function ensureTodoDashboardDaemon({ env = process.env, spawnDaemon
     }
     child.kill?.('SIGTERM');
     if (legacy === null) await rm(refs.descriptor, { force: true });
-    const error = new Error('dashboard daemon did not become ready');
-    error.code = 'DASHBOARD_DAEMON_UNAVAILABLE';
-    throw error;
+    throw dashboardError('DASHBOARD_DAEMON_UNAVAILABLE', 'dashboard daemon did not become ready');
   });
 }
 
@@ -634,9 +629,7 @@ export async function ensureTodoDashboardActivity(options) {
     if (!visible) await new Promise((resolve) => setTimeout(resolve, 50));
   }
   if (!visible) {
-    const error = new Error('registered project did not become visible');
-    error.code = 'DASHBOARD_PROJECT_UNAVAILABLE';
-    throw error;
+    throw dashboardError('DASHBOARD_PROJECT_UNAVAILABLE', 'registered project did not become visible');
   }
   return { ...registered, host: '127.0.0.1', port: daemon.port,
     url: `http://127.0.0.1:${daemon.port}/projects/${encodeURIComponent(registered.projectId)}/` };