elanous 0.2.11 → 0.2.13

package/src/loops/checker.ts

@@ -0,0 +1,178 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Database } from 'bun:sqlite';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import * as registry from './registry.js';
+import { cronMatches } from '../domains/cron-match.js';
+import { resolveTimeZone } from '../time/format.js';
+import type { LoopEntry, LoopRun } from './registry.js';
+
+type LoopState = 'off' | 'unregistered' | 'failing' | 'late' | 'unknown' | 'alive';
+export type LoopScope = 'graph-only' | 'registry';
+export interface CheckEntry {
+  id: string;
+  owner?: string;
+  mode?: string;
+  expectEveryMinutes?: number;
+  /** The scheduled fire before the latest one (cron loops). A run older than this missed two scheduled fires. */
+  dueAt?: string;
+  lastRunAt?: string;
+  lastStatus?: string;
+  recentStatuses?: string[];
+  enabled: boolean;
+  registered: boolean;
+}
+export interface CheckResult extends CheckEntry {
+  state: LoopState;
+  reason: string;
+}
+export const LOOP_STATES = ['alive', 'late', 'failing', 'off', 'unregistered', 'unknown'] as const;
+export type LoopCounts = Record<LoopState, number>;
+
+export function checkLoops(entries: CheckEntry[], now: Date, opts: { failureStatuses?: readonly string[] } = {}): CheckResult[] {
+  const failures = opts.failureStatuses ?? ['failed'];
+  return entries.map(entry => {
+    let state: LoopState;
+    let reason: string;
+    const age = entry.lastRunAt ? now.getTime() - Date.parse(entry.lastRunAt) : NaN;
+    if (!entry.enabled) { state = 'off'; reason = 'disabled'; }
+    else if (!entry.registered) { state = 'unregistered'; reason = 'not registered'; }
+    else if (entry.recentStatuses?.length && entry.recentStatuses.length >= 3
+      && entry.recentStatuses.slice(0, 3).every(status => failures.includes(status))) {
+      state = 'failing'; reason = 'last 3 runs failed';
+    } else if (Number.isFinite(age) && entry.dueAt && Number.isFinite(Date.parse(entry.dueAt))) {
+      // Judge against the real schedule, not a fixed interval: overnight or weekend gaps are not lateness.
+      if (Date.parse(entry.lastRunAt!) < Date.parse(entry.dueAt)) { state = 'late'; reason = `missed the scheduled runs since ${entry.dueAt}`; }
+      else { state = 'alive'; reason = 'ran at or after the previous scheduled fire'; }
+    } else if (Number.isFinite(age) && entry.expectEveryMinutes !== undefined
+      && entry.expectEveryMinutes > 0 && age > entry.expectEveryMinutes * 2 * 60_000) {
+      state = 'late'; reason = `last run exceeds twice the expected ${entry.expectEveryMinutes}m interval`;
+    } else if (!entry.lastRunAt || !Number.isFinite(age)) { state = 'unknown'; reason = 'no valid run recorded'; }
+    else if (entry.expectEveryMinutes === undefined || !Number.isFinite(entry.expectEveryMinutes) || entry.expectEveryMinutes <= 0) {
+      state = 'unknown'; reason = 'expected interval unknown';
+    } else { state = 'alive'; reason = 'within expected interval'; }
+    return { ...entry, state, reason };
+  });
+}
+
+export function countLoopStates(results: CheckResult[]): LoopCounts {
+  const counts: LoopCounts = { alive: 0, late: 0, failing: 0, off: 0, unregistered: 0, unknown: 0 };
+  for (const result of results) counts[result.state]++;
+  return counts;
+}
+
+/** Latest cron fire at or before `at` (minute resolution, scans back up to one year). */
+export function previousLoopFire(cron: string, at: Date, timeZone: string = resolveTimeZone().timeZone): string | null {
+  if (cron.trim().split(/\s+/).length !== 5) return null;
+  let minute = Math.floor(at.getTime() / 60000) * 60000;
+  for (let i = 0; i < 527040; i++, minute -= 60000) {
+    if (cronMatches(cron, new Date(minute), { timeZone })) return new Date(minute).toISOString();
+  }
+  return null;
+}
+
+/** The fire before the latest scheduled fire — a run older than this has missed two scheduled fires. */
+export function dueBefore(cron: string, now: Date, timeZone?: string): string | null {
+  const latest = previousLoopFire(cron, now, timeZone);
+  return latest ? previousLoopFire(cron, new Date(Date.parse(latest) - 60000), timeZone) : null;
+}
+
+export interface RegistryAdapterDeps {
+  listLoops?: () => LoopEntry[];
+  listAllLoops?: () => CheckEntry[];
+  statusForLoop?: (id: string) => { recentRuns: Pick<LoopRun, 'status'>[] };
+  now?: Date;
+  timeZone?: string;
+}
+
+export function entriesFromRegistry(deps: RegistryAdapterDeps = {}): { entries: CheckEntry[]; scope: LoopScope } {
+  // The registry integration is optional until LOOP-REG1 lands. Do not import a missing named export.
+  const all = deps.listAllLoops ?? (registry as typeof registry & { listAllLoops?: () => CheckEntry[] }).listAllLoops;
+  if (typeof all === 'function') return { entries: all(), scope: 'registry' };
+  const now = deps.now ?? new Date();
+  return { scope: 'graph-only', entries: (deps.listLoops ?? registry.listLoops)().map(loop => {
+    const first = loop.trigger.cron ? registry.nextLoopFire(loop.trigger.cron, now) : null;
+    const second = first && loop.trigger.cron ? registry.nextLoopFire(loop.trigger.cron, new Date(first)) : null;
+    const interval = first && second ? (Date.parse(second) - Date.parse(first)) / 60_000 : undefined;
+    const statuses = loop.lastRun
+      ? deps.statusForLoop ? deps.statusForLoop(loop.id).recentRuns.map(run => run.status)
+        : deps.listLoops ? [loop.lastRun.status]
+          : registry.loopStatus(loop.id).recentRuns.map(run => run.status)
+      : [];
+    const dueAt = loop.trigger.cron ? dueBefore(loop.trigger.cron, now, deps.timeZone) : null;
+    return { id: loop.id, enabled: loop.enabled, registered: true,
+      ...(interval !== undefined ? { expectEveryMinutes: interval } : {}),
+      ...(dueAt ? { dueAt } : {}),
+      ...(loop.lastRun ? { lastRunAt: loop.lastRun.at, lastStatus: loop.lastRun.status } : {}),
+      recentStatuses: statuses };
+  }) };
+}
+
+export interface CheckerDeps {
+  root?: string;
+  now?: Date;
+}
+
+/** Appends only new daily keys to the seat request journal; never rewrites existing lines. */
+export function notifyOwners(results: CheckResult[], deps: CheckerDeps = {}): number {
+  const eligible = results.filter(result => result.owner && (result.state === 'late' || result.state === 'failing'));
+  if (!eligible.length) return 0;
+  const now = deps.now ?? new Date();
+  const path = join(deps.root ?? effectiveInstanceRoot(), 'seat-requests', 'requests.jsonl');
+  mkdirSync(dirname(path), { recursive: true });
+  // SQLite's OS locks are released when a process dies, including after SIGKILL.
+  // The journal itself remains append-only; this database only serializes check + append.
+  const lock = new Database(`${path}.loop-checker.lock.sqlite`);
+  try {
+    lock.exec('PRAGMA busy_timeout = 10000');
+    lock.exec('BEGIN EXCLUSIVE');
+    try {
+      const existing = new Set<string>();
+      if (existsSync(path)) {
+        for (const line of readFileSync(path, 'utf8').split('\n')) {
+          if (line.trim()) {
+            const row = JSON.parse(line) as { key?: string };
+            if (row.key) existing.add(row.key);
+          }
+        }
+      }
+      let added = 0;
+      for (const result of eligible) {
+        const key = `loopcheck:${result.id}:${now.toISOString().slice(0, 10)}:${result.state}`;
+        if (existing.has(key)) continue;
+        const row = { key, receiptId: key, seat: result.owner, text: `${result.id} ${result.state} — 마지막 ${result.lastRunAt ?? '없음'} · ${result.reason}`,
+          status: 'queued', queuedAt: now.toISOString(), source: 'loop-checker' };
+        appendFileSync(path, JSON.stringify(row) + '\n');
+        existing.add(key);
+        added++;
+      }
+      lock.exec('COMMIT');
+      return added;
+    } catch (error) {
+      lock.exec('ROLLBACK');
+      throw error;
+    }
+  } finally { lock.close(); }
+}
+
+/** Persist the previous comparison only for explicit all-status checks. Notification is separate. */
+export function observeLoopCheck(results: CheckResult[], scope: LoopScope, deps: CheckerDeps = {}): LoopCounts {
+  const path = join(deps.root ?? effectiveInstanceRoot(), 'loop', 'checker', 'last.json');
+  let previous: Record<string, LoopState> = {};
+  try { previous = JSON.parse(readFileSync(path, 'utf8')) as Record<string, LoopState>; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  const current: Record<string, LoopState> = {};
+  for (const { id, state } of results) {
+    current[id] = state;
+    if (previous[id] && previous[id] !== state) debug.log('loop.checker', 'state-change', { id, from: previous[id], to: state });
+  }
+  const counts = countLoopStates(results);
+  debug.log('loop.checker', 'checked', { counts, scope });
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try { writeFileSync(tmp, JSON.stringify(current)); renameSync(tmp, path); }
+  catch (error) { if (existsSync(tmp)) unlinkSync(tmp); throw error; }
+  return counts;
+}

package/src/loops/loop-cli.ts

@@ -1,6 +1,9 @@
 import type { Command } from 'commander';
 import { writeStdoutJson } from '../cli/stdout-json.js';
 import { listLoops, loopStatus, runLoop, setLoopEnabled } from './registry.js';
+import { checkLoops, countLoopStates, entriesFromRegistry, LOOP_STATES, notifyOwners, observeLoopCheck, type RegistryAdapterDeps } from './checker.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { verifyLoopPackage } from './package/verify.js';
 
 async function output(value: unknown, json: boolean): Promise<void> {
   if (json) await writeStdoutJson(JSON.stringify(value) + '\n');
@@ -14,12 +17,31 @@ function handle(action: () => Promise<void> | void): Promise<void> {
   });
 }
 
-export function registerLoopCommands(program: Command): void {
+export function registerLoopCommands(program: Command, checkerDeps: RegistryAdapterDeps & { root?: string } = {}): void {
   const loop = program.command('loop').description('Inspect and control graph-backed loop agents');
   loop.command('list').option('--json', 'Print JSON')
     .action((opts: { json?: boolean }) => handle(() => output(listLoops(), !!opts.json)));
-  loop.command('status <id>').option('--json', 'Print JSON')
-    .action((id: string, opts: { json?: boolean }) => handle(() => output(loopStatus(id), !!opts.json)));
+  loop.command('status [id]').option('--all', 'Check all registered loops')
+    .option('--json', 'Print JSON').option('--notify', 'Queue late/failing loops for their owners')
+    .action((id: string | undefined, opts: { all?: boolean; json?: boolean; notify?: boolean }) => handle(async () => {
+      if (!opts.all) {
+        if (!id) throw new Error('loop status requires an id or --all');
+        await output(loopStatus(id), !!opts.json);
+        return;
+      }
+      if (id) throw new Error('loop status --all does not take an id');
+      const now = checkerDeps.now ?? new Date();
+      const root = checkerDeps.root ?? effectiveInstanceRoot();
+      const { entries, scope } = entriesFromRegistry({ ...checkerDeps, now });
+      const results = checkLoops(entries, now);
+      const counts = countLoopStates(results);
+      observeLoopCheck(results, scope, { root, now });
+      if (opts.notify) notifyOwners(results, { root, now });
+      if (opts.json) { await output({ results, counts, scope }, true); return; }
+      console.log('id\tstate\tlast run\texpected interval\towner\treason');
+      for (const result of results) console.log(`${result.id}\t${result.state}\t${result.lastRunAt ?? '—'}\t${result.expectEveryMinutes === undefined ? '—' : `${result.expectEveryMinutes}m`}\t${result.owner ?? '—'}\t${result.reason}`);
+      console.log(`${LOOP_STATES.map(state => `${state} ${counts[state]}`).join(' · ')} · scope ${scope}`);
+    }));
   for (const [name, enabled] of [['start', true], ['stop', false]] as const) {
     loop.command(`${name} <id>`).option('--yes', 'Apply the crontab change (otherwise preview only)')
       .option('--json', 'Print JSON')
@@ -34,4 +56,16 @@ export function registerLoopCommands(program: Command): void {
       await output(state, !!opts.json);
       if (state.status !== 'done' && state.status !== 'awaiting-approval') process.exitCode = 1;
     }));
+  loop.command('package').description('Inspect a loop package without installing it')
+    .command('verify <dir>').option('--json', 'Print JSON')
+    .action((dir: string, opts: { json?: boolean }) => handle(async () => {
+      const result = verifyLoopPackage(dir);
+      if (opts.json) await output(result, true);
+      else {
+        if (result.ok) console.log('OK');
+        else for (const error of result.errors) console.log(error);
+        console.log(`loop-package ${String(result.merged?.id ?? '?')} ${String(result.merged?.version ?? '?')} ${result.ok ? 'ok' : 'refused'} errors=${result.errors.length}`);
+      }
+      if (!result.ok) process.exitCode = 1;
+    }));
 }

package/src/loops/observe.ts

@@ -0,0 +1,49 @@
+import { debug } from '../debug/log.js';
+
+/** Event vocabulary of the loop-agent manifest observability contract. */
+export const LOOP_EVENTS = [
+  'tick', 'posture-change', 'resolution-change', 'grounding', 'heartbeat',
+  'absent', 'exchange', 'spawn', 'reap', 'promote', 'hitl',
+] as const;
+
+const LOOP_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const REQUIRED_CONTEXT = ['runId', 'profile', 'reason', 'sourceRef'] as const;
+
+function validId(id: unknown): id is string {
+  return typeof id === 'string' && LOOP_ID.test(id);
+}
+
+function reject(reason: 'invalid-loop-id' | 'invalid-event' | 'invalid-data'): void {
+  // Never include untrusted identifiers, event names or payloads in a log category.
+  debug.log('loop.observe', 'rejected', { reason });
+}
+
+/** Category matches observability.category in the loop-agent manifest. */
+export function loopCategory(id: string): string {
+  if (!validId(id)) {
+    reject('invalid-loop-id');
+    throw new Error('invalid loop id');
+  }
+  return `loop.${id}`;
+}
+
+/** Emit an RFC loop event, retaining absent context as a measurable list. */
+export function loopEvent(loopId: string, event: string, data: Record<string, unknown>): void {
+  if (!validId(loopId)) {
+    reject('invalid-loop-id');
+    return;
+  }
+  if (typeof event !== 'string' || !LOOP_EVENTS.some(name => name === event)) {
+    reject('invalid-event');
+    return;
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)
+    || Object.getPrototypeOf(data) !== Object.prototype && Object.getPrototypeOf(data) !== null
+    || (Object.hasOwn(data, 'loopId') && data.loopId !== loopId)) {
+    reject('invalid-data');
+    return;
+  }
+  const missingRequired = REQUIRED_CONTEXT.filter(field =>
+    typeof data[field] !== 'string' || !(data[field] as string).trim());
+  debug.log(`loop.${loopId}`, event, { ...data, loopId, missingRequired });
+}

package/src/loops/orchestrator/overlap.ts

@@ -0,0 +1,141 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { defaultListHarnessProcesses, type HarnessProcessListObservation } from '../../harness/harness-cli-command.js';
+import { getUserConfig, ORCHESTRATOR_DEFAULTS, type OrchestratorLoopConfig, type OrchestratorSeat } from '../../user-config.js';
+import { seatOfTree, TRAFFIC_SEATS } from './traffic.js';
+
+export type WorkItem = { kind: 'pr' | 'goal'; ref: string; seat: OrchestratorSeat | null; files: string[]; cells: string[]; unreadable?: true };
+export type WorkRef = Pick<WorkItem, 'kind' | 'ref' | 'seat'>;
+export type Overlap = ({ type: 'file'; path: string } | { type: 'cell'; cell: string }) & { refs: WorkRef[]; crossSeat: boolean };
+
+type OpenPr = { number: number; title: string; body?: string | null; headRefName: string; files: Array<{ path: string }>; isDraft: boolean };
+export interface CollectWorkDeps {
+  runGh?: (args: string[]) => string;
+  listProcesses?: () => HarnessProcessListObservation;
+  readGoal?: (path: string) => string;
+  config?: Pick<OrchestratorLoopConfig, 'seatTrees'>;
+}
+
+const repoRoot = resolve(import.meta.dir, '../../..');
+const defaultRunGh = (args: string[]): string => execFileSync('bun', ['bin/elanous.mjs', '--test', 'gh', ...args], {
+  cwd: repoRoot, encoding: 'utf8', timeout: 60_000, maxBuffer: 20 * 1024 * 1024,
+  stdio: ['ignore', 'pipe', 'pipe'], env: process.env,
+});
+const cellsOf = (text: string): string[] => [...new Set([...text.matchAll(/\b0\.2\.\d+\s+칸\s+([A-Za-z][A-Za-z0-9-]*)/g)].map(match => match[1]!))];
+const seatOfPr = (title: string): OrchestratorSeat | null => {
+  const seat = /^\s*\[(OP|TC|MK|UX)\]/.exec(title)?.[1];
+  return TRAFFIC_SEATS.find(id => id === seat) ?? null;
+};
+
+function goalPath(command: string): string | null {
+  // ps supplies an argv-shaped command, not a shell to execute. Only inspect explicit goal-file arguments.
+  const argv = [...command.matchAll(/"([^"]*)"|'([^']*)'|([^\s]+)/g)].map(match => match[1] ?? match[2] ?? match[3]!);
+  const entry = argv.findIndex(arg => /(?:^|\/)elanous\.mjs$/.test(arg));
+  if (entry < 0) return null;
+  let commandAt = entry + 1;
+  while (argv[commandAt] === '--test' || argv[commandAt] === '--config-dir') {
+    commandAt += argv[commandAt] === '--config-dir' ? 2 : 1;
+  }
+  const launch = argv[commandAt] === 'harness' && ['ask', 'say'].includes(argv[commandAt + 1] ?? '') ? commandAt : -1;
+  const dev = argv[commandAt] === 'dev' ? commandAt : -1;
+  if (launch < 0 && dev < 0) return null;
+  const fileFlag = argv.indexOf('--file', (launch >= 0 ? launch : dev) + 1);
+  if (fileFlag >= 0) return argv[fileFlag + 1] ?? null;
+  if (launch >= 0) {
+    const candidate = argv[launch + 2];
+    return candidate && !candidate.startsWith('-') && /\.(?:txt|md)$/.test(candidate) ? candidate : null;
+  }
+  const implement = argv.indexOf('--implement', dev + 1);
+  const candidate = implement >= 0 ? argv[implement + 1] : undefined;
+  return candidate && !candidate.startsWith('-') && /\.(?:txt|md)$/.test(candidate) ? candidate : null;
+}
+
+function goalFiles(text: string): string[] {
+  const line = text.split(/\r?\n/, 1)[0] ?? '';
+  const match = /^대상 경로:\s*(.*)$/.exec(line);
+  if (!match) return [];
+  return [...new Set(match[1]!.split(/\s*[·,]\s*/).map(file => file.trim().replace(/^`|`$/g, '')).filter(Boolean))];
+}
+
+export function collectWork(deps: CollectWorkDeps = {}): WorkItem[] {
+  const prs = JSON.parse((deps.runGh ?? defaultRunGh)(['pr', 'list', '--state', 'open', '--limit', '1000', '--json', 'number,title,body,headRefName,files,isDraft'])) as OpenPr[];
+  if (!Array.isArray(prs)) throw new Error('PR observation is not a list');
+  const observation = (deps.listProcesses ?? defaultListHarnessProcesses)();
+  if (observation.status !== 'ok') throw new Error(`process observation ${observation.status}`);
+  const cfg = deps.config ?? getUserConfig().loops?.orchestrator ?? ORCHESTRATOR_DEFAULTS;
+  const work: WorkItem[] = prs.map(pr => ({ kind: 'pr', ref: `#${pr.number}`, seat: seatOfPr(pr.title),
+    files: pr.files.map(file => file.path), cells: cellsOf(`${pr.title}\n${pr.body ?? ''}`) }));
+  for (const process of observation.records) {
+    const path = goalPath(process.command);
+    if (path === null) continue;
+    const ref = basename(path);
+    const cwd = process.cwdStatus === 'observed' && process.cwd && isAbsolute(process.cwd) ? process.cwd : undefined;
+    const seat = seatOfTree(cwd, cfg);
+    if (!isAbsolute(path) && !cwd) {
+      work.push({ kind: 'goal', ref, seat, files: [], cells: [], unreadable: true });
+      continue;
+    }
+    let text: string;
+    try {
+      text = (deps.readGoal ?? ((file: string) => readFileSync(file, 'utf8')))(isAbsolute(path) ? path : resolve(cwd!, path));
+    } catch {
+      work.push({ kind: 'goal', ref, seat, files: [], cells: [], unreadable: true });
+      continue;
+    }
+    work.push({ kind: 'goal', ref, seat, files: goalFiles(text), cells: cellsOf(text) });
+  }
+  return work;
+}
+
+export function findOverlaps(work: readonly WorkItem[], excludedFiles: readonly string[] = ['release/next.md']): Overlap[] {
+  const excluded = new Set(excludedFiles);
+  const files = new Map<string, WorkRef[]>();
+  const cells = new Map<string, WorkRef[]>();
+  for (const item of work) {
+    const ref = { kind: item.kind, ref: item.ref, seat: item.seat };
+    for (const path of new Set(item.files)) {
+      if (!excluded.has(path)) files.set(path, [...(files.get(path) ?? []), ref]);
+    }
+    for (const cell of new Set(item.cells)) cells.set(cell, [...(cells.get(cell) ?? []), ref]);
+  }
+  const details = (refs: WorkRef[]) => ({ refs, crossSeat: new Set(refs.map(ref => ref.seat).filter(Boolean)).size > 1 });
+  return [
+    ...[...files.entries()].filter(([, refs]) => refs.length > 1).map(([path, refs]): Overlap => ({ type: 'file', path, ...details(refs) })),
+    ...[...cells.entries()].filter(([, refs]) => refs.length > 1).map(([cell, refs]): Overlap => ({ type: 'cell', cell, ...details(refs) })),
+  ];
+}
+
+export function renderOverlaps(overlaps: readonly Overlap[]): string[] {
+  return overlaps.map(overlap => {
+    const refs = overlap.refs.map(ref => `${ref.kind === 'pr' ? 'PR ' : 'goal '}${ref.ref}(${ref.seat ?? '?'})`).join(' · ');
+    return overlap.type === 'file'
+      ? `⚠ 겹침 file ${overlap.path} — ${refs} · 먼저 착지하는 쪽 뒤에 다른 쪽 rebase`
+      : `⚠ 같은 칸 ${overlap.cell} — ${refs}`;
+  });
+}
+
+if (import.meta.main) {
+  try {
+    if (process.argv.slice(2).some(arg => arg !== '--json')) throw new Error('usage: overlap.ts [--json]');
+    const work = collectWork();
+    const overlaps = findOverlaps(work);
+    const files = overlaps.filter(overlap => overlap.type === 'file').length;
+    const cells = overlaps.filter(overlap => overlap.type === 'cell').length;
+    const crossSeat = overlaps.filter(overlap => overlap.crossSeat).length;
+    const unreadable = work.filter(item => item.unreadable).length;
+    debug.log('loop.orchestrator', 'exchange', { node: 'overlap', files, cells, crossSeat });
+    const summary = `overlap work=${work.length} files=${files} cells=${cells} crossSeat=${crossSeat} unreadable=${unreadable}`;
+    if (process.argv.includes('--json')) {
+      console.log(JSON.stringify({ work, overlaps }));
+      console.error(summary);
+    } else {
+      for (const line of renderOverlaps(overlaps)) console.log(line);
+      console.log(summary);
+    }
+  } catch (error) {
+    console.error(`overlap: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}

package/src/loops/orchestrator/traffic.ts

@@ -0,0 +1,150 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { defaultListHarnessProcesses, type HarnessProcessRecord } from '../../harness/harness-cli-command.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { devVersion, listChecklist, type ChecklistItem } from '../../release-loop/checklist.js';
+import { withFileLockSync } from '../../storage/file-lock.js';
+import { getUserConfig, ORCHESTRATOR_DEFAULTS, type OrchestratorLoopConfig, type OrchestratorSeat } from '../../user-config.js';
+
+export const TRAFFIC_SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+export type TrafficCell = Pick<ChecklistItem, 'id' | 'title' | 'owner' | 'status'>;
+export type TrafficProcess = Pick<HarnessProcessRecord, 'command' | 'elapsedSeconds' | 'cwd'> & { seat: OrchestratorSeat | null };
+export type TrafficSeatRow = { seat: OrchestratorSeat; running: number; cap: number; idleFor: number | null; idle: boolean; nextCell: TrafficCell | null };
+export type TrafficResult = { seats: TrafficSeatRow[]; unassigned: number; now: Date; idleMinutes: number };
+
+/** Same bounded walk as the CTX1 hook: a marker at the git root is checked before stopping. */
+export function seatOfTree(cwd: string | undefined, cfg: Pick<OrchestratorLoopConfig, 'seatTrees'>): OrchestratorSeat | null {
+  if (!cwd || !isAbsolute(cwd)) return null;
+  let dir = resolve(cwd);
+  for (let level = 0; level <= 6; level++) {
+    const marker = join(dir, '.claude', 'seat');
+    if (existsSync(marker)) {
+      const seat = readFileSync(marker, 'utf8').trim();
+      return TRAFFIC_SEATS.some(id => id === seat) ? seat as OrchestratorSeat : null;
+    }
+    if (existsSync(join(dir, '.git'))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Compare real paths: on macOS a process cwd under /var reports as /private/var (10-04 MK: UX trees under $TMPDIR
+  // never matched their configured /var/folders/... paths).
+  const path = realOrResolved(cwd);
+  for (const seat of TRAFFIC_SEATS) {
+    if (cfg.seatTrees[seat]?.some(tree => {
+      if (!isAbsolute(tree)) return false;
+      const root = realOrResolved(tree);
+      return path === root || path.startsWith(root + sep);
+    })) return seat;
+  }
+  return null;
+}
+
+function realOrResolved(path: string): string {
+  try { return realpathSync(path); } catch { return resolve(path); }
+}
+
+const IS_LAUNCH = /(?:^|\s)(?:\S*\/)?elanous\.mjs\s+(?:(?:--test|--config-dir\s+\S+)\s+)?harness\s+(?:ask|say)(?=\s|$)/;
+
+/** Process-to-seat resolution occurs at the boundary; this decision does no IO. */
+export function trafficTick({ processes, now, caps, lastLaunchAt, openCells, idleMinutes = 30 }: {
+  processes: readonly TrafficProcess[];
+  now: Date;
+  caps: Readonly<Record<OrchestratorSeat, number>>;
+  lastLaunchAt?: Partial<Record<OrchestratorSeat, Date | null>>;
+  openCells: readonly TrafficCell[];
+  idleMinutes?: number;
+}): TrafficResult {
+  const launches = processes.filter(process => IS_LAUNCH.test(process.command));
+  const seats = TRAFFIC_SEATS.map((seat): TrafficSeatRow => {
+    const owned = launches.filter(process => process.seat === seat);
+    const latest = owned.reduce<number | null>((current, process) => {
+      if (!Number.isFinite(process.elapsedSeconds) || process.elapsedSeconds < 0) return current;
+      const start = now.getTime() - process.elapsedSeconds * 1000;
+      return current === null ? start : Math.max(current, start);
+    }, null);
+    const fallback = owned.length ? lastLaunchAt?.[seat]?.getTime() : undefined;
+    const last = latest ?? (fallback !== undefined && Number.isFinite(fallback) ? fallback : null);
+    const idleFor = last === null ? null : Math.max(0, Math.floor((now.getTime() - last) / 60_000));
+    const idle = owned.length < caps[seat] && last !== null && now.getTime() - last > idleMinutes * 60_000;
+    return { seat, running: owned.length, cap: caps[seat], idleFor, idle,
+      nextCell: idle ? openCells.find(cell => cell.status !== 'done' && cell.owner?.split('/')[0] === seat) ?? null : null };
+  });
+  return { seats, unassigned: launches.filter(process => process.seat === null).length, now, idleMinutes };
+}
+
+export type TrafficRequest = { key: string; receiptId: string; seat: OrchestratorSeat; text: string; status: 'queued'; queuedAt: string; source: 'orchestrator-traffic' };
+export interface TrafficApplyDeps {
+  mode?: 'shadow' | 'live';
+  root?: string;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+/** Only the live branch opens the journal. The lock serializes hourly-key checks across CLI processes. */
+export function applyTraffic(result: TrafficResult, deps: TrafficApplyDeps = {}): number {
+  const log = deps.log ?? ((category: string, event: string, data: Record<string, unknown>) => debug.log(category, event, data));
+  const mode = deps.mode ?? 'shadow';
+  log('loop.orchestrator', 'tick', { mode, seats: result.seats.map(({ seat, running, cap, idleFor, idle }) => ({ seat, running, cap, idleFor, idle })), unassigned: result.unassigned });
+  let queued = 0;
+  for (const row of result.seats) {
+    if (!row.idle) continue;
+    const data = { seat: row.seat, running: row.running, cap: row.cap, idleMinutes: row.idleFor, nextCell: row.nextCell };
+    if (mode !== 'live') {
+      log('loop.orchestrator', 'would-nudge', data);
+      continue;
+    }
+    if (!row.nextCell) {
+      log('loop.orchestrator', 'exchange', { ...data, outcome: 'no-cell' });
+      continue;
+    }
+    const path = join(deps.root ?? effectiveInstanceRoot(), 'seat-requests', 'requests.jsonl');
+    const key = `orch-traffic:${row.seat}:${result.now.toISOString().slice(0, 13)}`;
+    mkdirSync(dirname(path), { recursive: true });
+    const appended = withFileLockSync(`${path}.lock`, () => {
+      const previous = existsSync(path) ? readFileSync(path, 'utf8') : '';
+      if (previous.split('\n').some(line => {
+        if (!line) return false;
+        try { return (JSON.parse(line) as { key?: string }).key === key; } catch { throw new Error('invalid seat request journal'); }
+      })) return false;
+      const request: TrafficRequest = { key, receiptId: key, seat: row.seat,
+        text: `다음 칸 쏘라: ${row.nextCell!.id} ${row.nextCell!.title.slice(0, 60)} (지금 ${row.running}/${row.cap} · ${row.idleFor}분 놂)`,
+        status: 'queued', queuedAt: result.now.toISOString(), source: 'orchestrator-traffic' };
+      appendFileSync(path, JSON.stringify(request) + '\n');
+      return true;
+    });
+    if (appended) queued++;
+    log('loop.orchestrator', 'exchange', { ...data, key, outcome: appended ? 'queued' : 'duplicate' });
+  }
+  return queued;
+}
+
+export function trafficLine(result: TrafficResult, mode: 'shadow' | 'live'): string {
+  const parts = result.seats.map(row => `${row.seat} ${row.running}/${row.cap}`);
+  const idle = result.seats.filter(row => row.idle).map(row => row.seat);
+  return `traffic ${parts.join(' · ')} · idle=${idle.length ? idle.join(',') : '없음'} · mode=${mode}`;
+}
+
+if (import.meta.main) {
+  try {
+    const args = process.argv.slice(2);
+    const versionFlag = args.indexOf('--version');
+    const version = versionFlag < 0 ? devVersion().replace(/-dev\.\d+$/, '') : args[versionFlag + 1];
+    if (!version || version.startsWith('--')
+      || args.some((arg, i) => arg !== '--json' && i !== versionFlag && (versionFlag < 0 || i !== versionFlag + 1))) {
+      throw new Error('usage: traffic.ts [--version <판>] [--json]');
+    }
+    const cfg = getUserConfig().loops?.orchestrator ?? ORCHESTRATOR_DEFAULTS;
+    const observation = defaultListHarnessProcesses();
+    if (observation.status !== 'ok') throw new Error(`process observation ${observation.status}`);
+    const now = new Date();
+    const processes = observation.records.map(process => ({ ...process, seat: seatOfTree(process.cwdStatus === 'unknown' ? undefined : process.cwd, cfg) }));
+    const result = trafficTick({ processes, now, caps: cfg.seatCaps, openCells: listChecklist(version).items });
+    const queued = applyTraffic(result, { mode: cfg.trafficMode });
+    if (args.includes('--json')) console.log(JSON.stringify({ ...result, mode: cfg.trafficMode, queued, version }));
+    else console.log(trafficLine(result, cfg.trafficMode));
+  } catch (error) {
+    console.error(`traffic: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}