elanous 0.2.13 → 0.2.15

package/src/loops/activity.ts

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { Database } from 'bun:sqlite';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { LogStore, type LogStoreRow } from '../mss/logging/log-store.js';
+import { checkLoops } from './checker.js';
+import { defaultLoopRoot, listAllLoops, type AllLoopEntry } from './registry.js';
+import type { ScheduleRow } from '../domains/schedule-registry.js';
+
+export interface ActivityNode {
+  id: string;
+  kind: AllLoopEntry['kind'] | 'seat' | 'card' | 'event';
+  title: string;
+  state: string | null;
+  reason: string | null;
+  lastAt: string | null;
+  events: number;
+}
+export interface ActivityEdge {
+  from: string;
+  to: string;
+  kind: 'delegation' | 'request' | 'reply' | 'card';
+  count: number;
+  lastAt: string;
+}
+export interface LoopActivityResult {
+  since: string;
+  until: string;
+  nodes: ActivityNode[];
+  edges: ActivityEdge[];
+}
+export interface LoopActivityDeps {
+  listAllLoops?: (opts: { root: string; stateRoot: string; now: Date; schedules: ScheduleRow[] }) => AllLoopEntry[];
+  queryEvents?: (root: string, sinceMs: number, untilMs: number) => LogStoreRow[];
+  readJournal?: (root: string, name: string) => readonly Record<string, unknown>[];
+  readCards?: (root: string) => readonly { id: string; createdAt: string; sections: readonly { owner: string; createdAt: string }[] }[];
+}
+
+function readSchedules(root: string): ScheduleRow[] {
+  const path = join(root, 'schedules.db');
+  if (!existsSync(path)) return [];
+  const db = new Database(path, { readonly: true });
+  try {
+    if (!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schedule_registry'").get()) return [];
+    const columns = (db.query('PRAGMA table_info(schedule_registry)').all() as Array<{ name: string }>).map(row => row.name);
+    if (!columns.includes('run_via')) return [];
+    return db.query('SELECT * FROM schedule_registry').all() as ScheduleRow[];
+  } finally { db.close(); }
+}
+
+function readEvents(root: string, sinceMs: number, untilMs: number): LogStoreRow[] {
+  const path = join(root, 'logs', 'logs.db');
+  if (!existsSync(path)) return [];
+  const store = LogStore.openReadOnly(path);
+  try { return store.queryAll({ categories: ['loop.', 'seat.loop'], sinceMs, untilMs }); }
+  finally { store.close(); }
+}
+
+function parseObject(value: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch { return {}; }
+}
+
+function readJournal(root: string, name: string): Record<string, unknown>[] {
+  const path = join(root, 'seat-requests', name);
+  return existsSync(path) ? readFileSync(path, 'utf8').split('\n').filter(Boolean).map(parseObject) : [];
+}
+
+function readCards(root: string): { id: string; createdAt: string; sections: { owner: string; createdAt: string }[] }[] {
+  const dir = join(root, 'task-cards');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(file => file.endsWith('.jsonl')).flatMap(file => {
+    const entries = readFileSync(join(dir, file), 'utf8').split('\n').filter(Boolean).map(parseObject);
+    const created = entries.find(row => row.type === 'created');
+    if (!created || typeof created.id !== 'string' || typeof created.createdAt !== 'string') return [];
+    return [{ id: created.id, createdAt: created.createdAt,
+      sections: entries.filter(row => row.type === 'section' && typeof row.owner === 'string' && typeof row.createdAt === 'string')
+        .map(row => ({ owner: row.owner as string, createdAt: row.createdAt as string })) }];
+  });
+}
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function loopId(value: unknown): string | null {
+  const id = text(value);
+  if (!id) return null;
+  const seat = id.toUpperCase();
+  if (seat === 'OP' || seat === 'TC' || seat === 'UX') return `${seat.toLowerCase()}-seat`;
+  if (seat === 'MK' || seat === 'MK-SEAT') return 'cmo-seat';
+  return id;
+}
+
+function cardNodeId(value: unknown): string | null {
+  const id = text(value);
+  return id ? (id.startsWith('card:') ? id : `card:${id}`) : null;
+}
+
+/** Read-only registry/checker snapshot plus observed edges in the inclusive time window. */
+export function loopActivity({ since, until, root = effectiveInstanceRoot(), deps = {} }: {
+  since: string | Date;
+  until?: string | Date;
+  root?: string;
+  deps?: LoopActivityDeps;
+}): LoopActivityResult {
+  const end = until === undefined ? new Date() : new Date(until);
+  const duration = typeof since === 'string' ? /^(\d+)([mhd])$/.exec(since) : null;
+  const durationMs = duration ? Number(duration[1]) * ({ m: 60_000, h: 3_600_000, d: 86_400_000 }[duration[2]!] ?? NaN) : NaN;
+  const start = duration ? new Date(end.getTime() - durationMs) : new Date(since);
+  if (!Number.isFinite(start.getTime()) || !Number.isFinite(end.getTime()) || start > end) throw new Error('invalid loop activity window');
+  const inventory = (deps.listAllLoops ?? listAllLoops)({ root: deps.listAllLoops ? root : defaultLoopRoot(), stateRoot: root, now: end, schedules: deps.listAllLoops ? [] : readSchedules(root) });
+  const checked = checkLoops(inventory, end);
+  const byId = new Map(inventory.map(entry => [entry.id, entry]));
+  const nodes = new Map<string, ActivityNode>(checked.map(entry => [entry.id, {
+    id: entry.id, kind: byId.get(entry.id)?.kind ?? 'graph',
+    title: byId.get(entry.id)?.title ?? entry.id,
+    state: entry.state, reason: entry.reason, lastAt: entry.lastRunAt ?? null, events: 0,
+  }]));
+  const edges = new Map<string, ActivityEdge>();
+  const ensure = (id: string, kind: ActivityNode['kind'] = 'event'): ActivityNode => {
+    let node = nodes.get(id);
+    if (!node) {
+      node = { id, kind, title: id, state: null, reason: null, lastAt: null, events: 0 };
+      nodes.set(id, node);
+    }
+    return node;
+  };
+  const inWindow = (value: unknown): string | null => {
+    const ms = typeof value === 'string' ? Date.parse(value) : NaN;
+    return Number.isFinite(ms) && ms >= start.getTime() && ms <= end.getTime() ? new Date(ms).toISOString() : null;
+  };
+  const touch = (id: string, at: string, kind: ActivityNode['kind'] = 'event'): void => {
+    const node = ensure(id, kind);
+    node.events++;
+    if (!node.lastAt || at > node.lastAt) node.lastAt = at;
+  };
+  const connect = (from: string, to: string, kind: ActivityEdge['kind'], at: string): void => {
+    if (from === to) return;
+    ensure(from, from.startsWith('card:') ? 'card' : 'event');
+    ensure(to, to.startsWith('card:') ? 'card' : 'event');
+    const key = JSON.stringify([from, to, kind]);
+    const edge = edges.get(key);
+    if (edge) { edge.count++; if (at > edge.lastAt) edge.lastAt = at; }
+    else edges.set(key, { from, to, kind, count: 1, lastAt: at });
+  };
+  for (const row of (deps.queryEvents ?? readEvents)(root, start.getTime(), end.getTime())) {
+    const timestamp = Number.isFinite(row.ts_ms) ? row.ts_ms : Date.parse(row.ts);
+    if (!Number.isFinite(timestamp) || timestamp < start.getTime() || timestamp > end.getTime()) continue;
+    const data = parseObject(row.data ?? '');
+    const actor = row.category.startsWith('loop.') && !['loop.checker', 'loop.observe', 'loop.registry', 'loop.neighbors', 'loop.package'].includes(row.category)
+      ? loopId(row.category.slice('loop.'.length)) : row.category === 'seat.loop' ? loopId(data.seat) : null;
+    if (!actor) continue;
+    const at = new Date(timestamp).toISOString();
+    touch(actor, at);
+    if (row.event === 'exchange' && text(data.reason) === 'delegation') {
+      const to = loopId(data.to ?? data.targetLoopId);
+      if (to) connect(loopId(data.from) ?? actor, to, 'delegation', at);
+    } else if (row.category === 'loop.orchestrator' && row.event === 'exchange' && data.reason === 'queued') {
+      const to = loopId(data.targetLoopId);
+      if (to) connect(actor, to, 'delegation', at);
+    } else if (row.event === 'exchange' && (data.reason === 'request' || data.reason === 'reply' || data.reason === 'card')) {
+      const to = data.reason === 'card' && data.cardId != null
+        ? cardNodeId(data.cardId) : loopId(data.to ?? data.targetLoopId);
+      if (to) connect(loopId(data.from) ?? actor, to, data.reason, at);
+    }
+  }
+  for (const item of (deps.readJournal ?? readJournal)(root, 'requests.jsonl')) {
+    const at = inWindow(item.queuedAt);
+    const to = loopId(item.loopId ?? item.seat);
+    if (!at || !to) continue;
+    touch(to, at, 'seat');
+    const from = loopId(item.from) ?? (item.source === 'orchestrator' || item.source === 'orchestrator-traffic' ? 'orchestrator'
+      : item.source === 'loop-checker' ? 'checker' : null);
+    if (from) connect(from, to, 'request', at);
+  }
+  for (const item of (deps.readJournal ?? readJournal)(root, 'replies.jsonl')) {
+    const at = inWindow(item.repliedAt ?? item.createdAt);
+    const from = loopId(item.from ?? item.seat);
+    if (!at || !from) continue;
+    touch(from, at, 'seat');
+    const to = loopId(item.to);
+    if (to) connect(from, to, 'reply', at);
+  }
+  for (const card of (deps.readCards ?? readCards)(root)) {
+    const id = cardNodeId(card.id);
+    if (!id) continue;
+    const created = inWindow(card.createdAt);
+    if (created) touch(id, created, 'card');
+    for (const section of card.sections) {
+      const at = inWindow(section.createdAt);
+      const owner = loopId(section.owner);
+      if (!at || !owner) continue;
+      touch(id, at, 'card');
+      connect(owner, id, 'card', at);
+    }
+  }
+  return { since: start.toISOString(), until: end.toISOString(),
+    nodes: [...nodes.values()].sort((a, b) => a.id.localeCompare(b.id)),
+    edges: [...edges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind)) };
+}

package/src/loops/budget.ts

@@ -0,0 +1,63 @@
+import { ORCHESTRATOR_DEFAULTS, type OrchestratorSeat } from '../user-config.js';
+
+export interface SpawnBudgetInput {
+  seat: OrchestratorSeat;
+  /** Current running count for this seat; null/undefined means the ledger could not be measured. */
+  running: number | null | undefined;
+  /** Configured loops.orchestrator.seatCaps. Missing seats use the orchestrator defaults. */
+  caps?: Partial<Record<OrchestratorSeat, number>>;
+  /** Release-gate seat limits. Missing seats use the gate default of four. */
+  gate?: Partial<Record<OrchestratorSeat, number>>;
+  /** Optional queue-injected cap; it may lower, never replace, the configured limit. */
+  injectedCap?: number;
+}
+
+export interface SpawnBudgetDecision {
+  allow: boolean;
+  reason: 'within-cap' | 'seat-cap' | 'unknown-running';
+  cap: number;
+}
+
+export type SeatCapDetails = {
+  cap: number;
+  seatCaps: number | '?';
+  releaseGate: number | '?';
+  injectedCap?: number | '?';
+  winners: ('releaseGate' | 'seatCaps' | 'injectedCap')[];
+};
+
+/** Keep the cap calculation and the names shown to operators on the same source of truth. */
+export function seatCapDetails({ seat, caps, gate, injectedCap }: Pick<SpawnBudgetInput, 'seat' | 'caps' | 'gate' | 'injectedCap'>): SeatCapDetails {
+  const configured = caps?.[seat] ?? ORCHESTRATOR_DEFAULTS.seatCaps[seat];
+  const gated = gate?.[seat] ?? 4;
+  const valid = (value: number): boolean => Number.isSafeInteger(value) && value >= 0;
+  const seatCaps = valid(configured) ? configured : '?';
+  const releaseGate = valid(gated) ? gated : '?';
+  const injected = injectedCap === undefined ? undefined : valid(injectedCap) ? injectedCap : '?';
+  const cap = [seatCaps, releaseGate, injected].some((value) => value === '?') ? 0
+    : Math.min(seatCaps as number, releaseGate as number, injected === undefined ? Infinity : injected as number);
+  const winners: SeatCapDetails['winners'] = [];
+  if (seatCaps !== '?' && releaseGate !== '?' && injected !== '?') {
+    if (releaseGate === cap) winners.push('releaseGate');
+    if (seatCaps === cap) winners.push('seatCaps');
+    if (injected === cap) winners.push('injectedCap');
+  }
+  return { cap, seatCaps, releaseGate, ...(injected === undefined ? {} : { injectedCap: injected }), winners };
+}
+
+export function seatCapReason(seat: OrchestratorSeat, active: number, details: SeatCapDetails): string {
+  const keys = (['releaseGate', 'seatCaps', 'injectedCap'] as const).filter((name) => name !== 'injectedCap' || details.injectedCap !== undefined);
+  const candidates = [...details.winners, ...keys.filter((name) => !details.winners.includes(name))];
+  return `seat ${seat}: ${active}/${details.cap} (${candidates.map((name) => `${name}.${seat}=${details[name]}`).join(' · ')})`;
+}
+
+/** A release gate or injected queue cap can lower, but never raise, the configured per-seat cap. */
+export function decideSpawn({ seat, running, caps, gate, injectedCap }: SpawnBudgetInput): SpawnBudgetDecision {
+  const { cap } = seatCapDetails({ seat, caps, gate, injectedCap });
+  if (!Number.isSafeInteger(running) || running === null || running === undefined || running < 0) {
+    return { allow: false, reason: 'unknown-running', cap };
+  }
+  return running < cap
+    ? { allow: true, reason: 'within-cap', cap }
+    : { allow: false, reason: 'seat-cap', cap };
+}

package/src/loops/checker.ts

@@ -14,6 +14,8 @@ export type LoopScope = 'graph-only' | 'registry';
 export interface CheckEntry {
   id: string;
   owner?: string;
+  ownerSource?: 'header' | 'config' | 'seat' | 'seat-arg' | 'default';
+  evidence?: 'log-mtime' | 'registry';
   mode?: string;
   expectEveryMinutes?: number;
   /** The scheduled fire before the latest one (cron loops). A run older than this missed two scheduled fires. */
@@ -88,8 +90,8 @@ export interface RegistryAdapterDeps {
 }
 
 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;
+  // An explicitly injected graph inventory remains the checker test/adapter fallback.
+  const all = deps.listAllLoops ?? (deps.listLoops ? undefined : registry.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 => {
@@ -102,7 +104,7 @@ export function entriesFromRegistry(deps: RegistryAdapterDeps = {}): { entries:
           : 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,
+    return { id: loop.id, owner: loop.owner ?? undefined, ownerSource: loop.ownerSource, enabled: loop.enabled, registered: true,
       ...(interval !== undefined ? { expectEveryMinutes: interval } : {}),
       ...(dueAt ? { dueAt } : {}),
       ...(loop.lastRun ? { lastRunAt: loop.lastRun.at, lastStatus: loop.lastRun.status } : {}),

package/src/loops/contract/examples/orchestrator.loop.yaml

@@ -2,7 +2,7 @@ id: orchestrator
 version: 1.0.0
 kind: orchestrator
 role: docs/roles/OP.md
-graph: graphs/operate-loop.yaml
+graph: graphs/orchestrator/orchestrator.yaml
 orchestration:
   windows:
     - {at: '08:00', delegateTo: [op-seat, cmo-seat, tc-seat, ux-seat], fromLedger: release/checklist-and-seat-requests}

package/src/loops/loop-cli.ts

@@ -1,9 +1,10 @@
 import type { Command } from 'commander';
 import { writeStdoutJson } from '../cli/stdout-json.js';
-import { listLoops, loopStatus, runLoop, setLoopEnabled } from './registry.js';
+import { listAllLoops, listLoops, loopStatus, runLoop, setLoopEnabled, unregisteredCronLoops, type AllLoopEntry, type LoopRegistryOptions } 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';
+import { loopActivity } from './activity.js';
 
 async function output(value: unknown, json: boolean): Promise<void> {
   if (json) await writeStdoutJson(JSON.stringify(value) + '\n');
@@ -17,10 +18,41 @@ function handle(action: () => Promise<void> | void): Promise<void> {
   });
 }
 
-export function registerLoopCommands(program: Command, checkerDeps: RegistryAdapterDeps & { root?: string } = {}): void {
+function allLoopTable(entries: AllLoopEntry[]): void {
+  console.log('id\t층\t주인 자리\t모드\t기대 주기\t호스트\t울타리 역할\t관측 카테고리\t마지막 실행');
+  for (const entry of entries) {
+    const interval = entry.expectEveryMinutes === undefined ? '모름'
+      : entry.cronIrregular ? `불규칙 · 최대 ${entry.expectEveryMinutes}분` : `${entry.expectEveryMinutes}분`;
+    console.log([entry.id, entry.kind, entry.owner ?? '모름', entry.mode ?? '모름', interval,
+      entry.host ?? '모름', entry.fenceRole ?? '모름', entry.observationCategory ?? '모름', entry.lastRunAt ?? '모름'].join('\t'));
+  }
+}
+
+export function registerLoopCommands(program: Command, checkerDeps: RegistryAdapterDeps & { root?: string; registryOptions?: LoopRegistryOptions } = {}): 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('list').option('--all', 'Show the full loop registry').option('--json', 'Print JSON')
+    .action((opts: { all?: boolean; json?: boolean }) => handle(async () => {
+      if (!opts.all) { await output(listLoops(checkerDeps.registryOptions), !!opts.json); return; }
+      const registryOpts = checkerDeps.registryOptions ?? {};
+      const entries = listAllLoops(registryOpts);
+      if (opts.json) { await output(entries, true); return; }
+      allLoopTable(entries);
+      const missing = unregisteredCronLoops(entries, registryOpts);
+      if (missing.length) console.log(`미등록 ${missing.length}: ${missing.map(row => `${row.id} (${row.command})`).join(', ')}`);
+    }));
+  loop.command('activity').description('Read loop and seat activity in a time window (default: last 24h)')
+    .option('--since <duration-or-date>', 'Start of window: duration (e.g. 24h) or ISO date', '24h')
+    .option('--json', 'Print JSON')
+    .action((opts: { since: string; json?: boolean }) => handle(async () => {
+      const activity = loopActivity({ since: opts.since, root: checkerDeps.root ?? effectiveInstanceRoot() });
+      if (opts.json) { await output(activity, true); return; }
+      console.log(`Loop activity ${activity.since} → ${activity.until}`);
+      console.log(`${activity.nodes.length} nodes · ${activity.edges.length} edges`);
+      console.log('Nodes (id · state · events · last activity)');
+      for (const node of activity.nodes) console.log(`${node.id} · ${node.state ?? '—'} · ${node.events} · ${node.lastAt ?? '—'}`);
+      console.log('Edges (from → to · kind · count · last activity)');
+      for (const edge of activity.edges) console.log(`${edge.from} → ${edge.to} · ${edge.kind} · ${edge.count} · ${edge.lastAt}`);
+    }));
   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 () => {

package/src/loops/neighbors.ts

@@ -0,0 +1,40 @@
+import { debug } from '../debug/log.js';
+
+/** The neighbor fields validated by src/loops/contract/validate.ts. */
+export interface Neighbor {
+  id: string;
+  exchange: ('status' | 'request' | 'decision' | 'blocked')[];
+  heartbeat: { everyMinutes: number; missedTicks: number };
+  onAbsent: { action: 'delegate' | 'defer' | 'escalate'; delegateTo: string };
+}
+
+export interface NeighborJudgment {
+  state: 'present' | 'absent' | 'unknown';
+  action?: Neighbor['onAbsent'];
+  reason: string;
+}
+
+/** lastSeenAt is the latest ACK of a heartbeat or envelope, not the last send attempt. */
+export function judgeNeighbor({ neighbor, lastSeenAt, lastSendError, now }: {
+  neighbor: Neighbor;
+  lastSeenAt?: string | null;
+  lastSendError?: unknown;
+  now: Date;
+}): NeighborJudgment {
+  const seen = lastSeenAt ? Date.parse(lastSeenAt) : NaN;
+  let result: NeighborJudgment;
+  if (lastSendError != null) {
+    result = { state: 'unknown', reason: 'send-failed' };
+  } else if (!Number.isFinite(seen) || !Number.isFinite(now.getTime()) || seen > now.getTime()) {
+    result = { state: 'unknown', reason: 'last-ack-unknown' };
+  } else if (now.getTime() - seen >= neighbor.heartbeat.everyMinutes * neighbor.heartbeat.missedTicks * 60_000) {
+    result = { state: 'absent', action: neighbor.onAbsent, reason: 'heartbeat-missed' };
+  } else {
+    result = { state: 'present', reason: 'within-heartbeat-window' };
+  }
+  // The validated neighbor entry does not carry its owning loop id; do not invent one.
+  debug.log('loop.neighbors', 'judged', {
+    loop: null, neighbor: neighbor.id, state: result.state, action: result.action, reason: result.reason,
+  });
+  return result;
+}

package/src/loops/observe.ts

@@ -1,4 +1,5 @@
 import { debug } from '../debug/log.js';
+import { recordFailureEvent } from '../self-implement/heal-intake.js';
 
 /** Event vocabulary of the loop-agent manifest observability contract. */
 export const LOOP_EVENTS = [
@@ -46,4 +47,13 @@ export function loopEvent(loopId: string, event: string, data: Record<string, un
   const missingRequired = REQUIRED_CONTEXT.filter(field =>
     typeof data[field] !== 'string' || !(data[field] as string).trim());
   debug.log(`loop.${loopId}`, event, { ...data, loopId, missingRequired });
+  if (event === 'tick' && (data.outcome === 'failed' || data.status === 'failed')) {
+    try {
+      recordFailureEvent({ source: 'loop-tick', kind: event, ref: loopId,
+        summary: `Loop ${loopId} tick failed`, at: new Date().toISOString() });
+    } catch (error) {
+      try { debug.log('heal.intake', 'record-failed', { source: 'loop-tick', kind: event, ref: loopId, error: String(error) }, { level: 'error' }); }
+      catch { /* Heal reporting must not change the tick outcome. */ }
+    }
+  }
 }

package/src/loops/orchestrator/author-depth.ts

@@ -0,0 +1,220 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { debug } from '../../debug/log.js';
+import { defaultListHarnessProcesses } from '../../harness/harness-cli-command.js';
+import { listHarnessQueue, type QueueItem } from '../../harness/harness-queue.js';
+import { releaseLedgerRoot } from '../../instance/resolve.js';
+import { listChecklist, type ChecklistItem } from '../../release-loop/checklist.js';
+import { listSchedules } from '../../release-loop/release-schedule.js';
+import { getUserConfig, ORCHESTRATOR_DEFAULTS, type OrchestratorSeat } from '../../user-config.js';
+import { checkAuthorInput } from './author-input-check.js';
+import { AuthorLedger } from './author-ledger.js';
+import { collectWork, findOverlaps, type WorkItem } from './overlap.js';
+import { seatOfTree, trafficTick, TRAFFIC_SEATS } from './traffic.js';
+
+export type AuthorCell = Pick<ChecklistItem, 'id' | 'title' | 'owner' | 'status' | 'evidence'> & { version: string };
+export type AuthorQueueRow = Pick<QueueItem, 'seat' | 'status'> & Partial<Pick<QueueItem, 'input' | 'kind'>>;
+export type AuthorDepthResult = {
+  seats: Array<{ seat: OrchestratorSeat; cap: number | null; running: number | null; queued: number | null;
+    target: number | null; short: number | null; wouldAuthor: Array<{ cellId: string; version: string; title: string }> }>;
+  unreadable: Array<{ source: string; reason: string }>;
+  receiptCounts?: { held: number; queuedForAuthor: number };
+  receiptFailures?: number;
+};
+export type AuthorDepthInput = {
+  seats: readonly OrchestratorSeat[];
+  caps: Partial<Record<OrchestratorSeat, number | null>>;
+  running: Partial<Record<OrchestratorSeat, number | null>> | null;
+  queued: readonly AuthorQueueRow[] | null;
+  cells: readonly AuthorCell[] | null;
+  overlaps: readonly WorkItem[] | null;
+  now: Date;
+  unreadable?: AuthorDepthResult['unreadable'];
+};
+
+const cellRefs = (text: string): string[] => [...new Set([...text.matchAll(/\b\d+\.\d+\.\d+\s+칸\s+([A-Za-z][A-Za-z0-9-]*)/g)]
+  .map(match => match[1]!))];
+
+/** A shadow decision: candidates are compared against existing work, never entered into the queue. */
+export function authorDepth({ seats, caps, running, queued, cells, overlaps, now, unreadable = [] }: AuthorDepthInput): AuthorDepthResult {
+  const errors = [...unreadable];
+  // Version selection happens in the collector at `now`; the pure calculation receives those cells already selected.
+  // Reject an invalid snapshot clock rather than presenting its candidates as a valid shadow decision.
+  const validClock = Number.isFinite(now.getTime());
+  if (!validClock) errors.push({ source: 'clock', reason: 'invalid observation time' });
+  const busy = queued === null ? null : queued.filter(row => row.status === 'queued' || row.status === 'launching');
+  const queueWork: WorkItem[] = busy?.map((row, index) => ({
+    kind: 'goal', ref: `queue:${index}`, seat: row.seat, files: [], cells: row.input ? cellRefs(row.input) : [],
+  })) ?? [];
+  const base = overlaps === null ? null : [...overlaps, ...queueWork];
+  const unknownWorkCells = overlaps?.some(item => item.unreadable) ?? false;
+  const availableCells = cells ?? [];
+  // The collector supplies current release before next; numeric version order need not match release order.
+  const versionOrder = new Map([...new Set(availableCells.map(cell => cell.version))]
+    .map((version, index) => [version, index]));
+  const missing = (source: string, seat: OrchestratorSeat): void => {
+    if (!errors.some(item => item.source === source)) errors.push({ source, reason: `missing ${seat} observation` });
+  };
+  const rows = seats.map(seat => {
+    const cap = caps[seat] ?? null;
+    const active = running?.[seat] ?? null;
+    if (cap === null) missing('caps', seat);
+    if (active === null) missing('running', seat);
+    if (queued === null) missing('queue', seat);
+    if (cells === null && !errors.some(item => item.source === 'checklist' || item.source === 'versions')) missing('checklist', seat);
+    if (overlaps === null || unknownWorkCells) missing('overlap', seat);
+    const unknownQueueCells = busy?.some(row => row.seat === seat && (!row.input || cellRefs(row.input).length === 0)) ?? false;
+    if (unknownQueueCells) missing('queue-cells', seat);
+    const have = busy === null ? null : busy.filter(row => row.seat === seat).length;
+    const depthKnown = cap !== null && active !== null && have !== null;
+    const candidateKnown = validClock && cells !== null && base !== null && !unknownQueueCells && !unknownWorkCells;
+    const target = cap === null || active === null ? null : Math.max(0, cap - active) + 2;
+    const short = !depthKnown || !candidateKnown || target === null ? null : Math.max(0, target - have);
+    return { seat, cap, running: active, queued: have, target, short,
+      wouldAuthor: [] as Array<{ cellId: string; version: string; title: string }> };
+  });
+  const chosen = new Set<string>();
+  for (const cell of [...availableCells].sort((a, b) => versionOrder.get(a.version)! - versionOrder.get(b.version)! || a.id.localeCompare(b.id))) {
+    if (cell.status === 'green' || cell.status === 'done' || !cell.title.trim() || chosen.has(cell.id)) continue;
+    const row = rows.find(entry => entry.seat === cell.owner?.split('/')[0]);
+    if (!row || row.short === null || row.wouldAuthor.length >= row.short) continue;
+    const candidate: WorkItem = { kind: 'goal', ref: `candidate:${cell.version}:${cell.id}`, seat: row.seat, files: [], cells: [cell.id] };
+    if (findOverlaps([...base!, candidate]).some(overlap => overlap.type === 'cell' && overlap.cell === cell.id
+      && overlap.refs.some(ref => ref.ref === candidate.ref))) continue;
+    chosen.add(cell.id);
+    row.wouldAuthor.push({ cellId: cell.id, version: cell.version, title: cell.title });
+  }
+  return { seats: rows, unreadable: errors };
+}
+
+export interface CollectAuthorDepthDeps {
+  root?: string;
+  seats?: readonly OrchestratorSeat[];
+  now?: Date;
+  caps?: () => Partial<Record<OrchestratorSeat, number>>;
+  running?: () => Partial<Record<OrchestratorSeat, number>>;
+  queued?: () => readonly AuthorQueueRow[];
+  cells?: (version: string) => readonly AuthorCell[];
+  overlaps?: () => readonly WorkItem[];
+  versions?: () => readonly [string, string];
+  ledger?: Pick<AuthorLedger, 'request'>;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+function defaultVersions(now: Date, root = releaseLedgerRoot()): readonly [string, string] {
+  if (!existsSync(join(root, 'release', 'features.sqlite'))) throw new Error('release schedule ledger unavailable');
+  const upcoming = listSchedules(root).filter(row => row.cutAt && Date.parse(row.cutAt) > now.getTime())
+    .sort((a, b) => Date.parse(a.cutAt) - Date.parse(b.cutAt));
+  if (upcoming.length < 2) throw new Error('current and next release schedules unavailable');
+  return [upcoming[0]!.version, upcoming[1]!.version];
+}
+
+/** Independent collection failures are surfaced, never substituted with an apparently empty source. */
+export function collectAuthorDepth(deps: CollectAuthorDepthDeps = {}): AuthorDepthResult {
+  const seats = deps.seats ?? TRAFFIC_SEATS;
+  const now = deps.now ?? new Date();
+  const unreadable: AuthorDepthResult['unreadable'] = [];
+  const observe = <T>(source: string, read: () => T): T | null => {
+    try { return read(); }
+    catch (error) { unreadable.push({ source, reason: error instanceof Error ? error.message : String(error) }); return null; }
+  };
+  const cfg = deps.caps && deps.running ? null : observe('config', () => getUserConfig().loops?.orchestrator ?? ORCHESTRATOR_DEFAULTS);
+  const caps = deps.caps ? observe('caps', deps.caps) : cfg === null ? null : observe('caps', () => cfg.seatCaps);
+  const running = deps.running ? observe('running', deps.running) : cfg === null ? null : observe('running', () => {
+    const observation = defaultListHarnessProcesses();
+    if (observation.status !== 'ok') throw new Error(`process observation ${observation.status}`);
+    const processes = observation.records.map(process => ({ ...process,
+      seat: seatOfTree(process.cwdStatus === 'unknown' ? undefined : process.cwd, cfg) }));
+    const measured = trafficTick({ processes, now, caps: cfg.seatCaps, openCells: [] });
+    if (measured.unassigned) throw new Error(`${measured.unassigned} unassigned harness launch process(es)`);
+    return Object.fromEntries(measured.seats.map(row => [row.seat, row.running]));
+  });
+  const queued = observe('queue', deps.queued ?? (() => listHarnessQueue({ root: deps.root })));
+  const releaseRoot = deps.root ?? releaseLedgerRoot();
+  const versions = observe('versions', deps.versions ?? (() => defaultVersions(now, releaseRoot)));
+  const cells = versions === null ? null : observe('checklist', () => versions.flatMap(version => {
+    if (!deps.cells && !existsSync(join(releaseRoot, 'release', 'features.sqlite')))
+      throw new Error('checklist ledger unavailable');
+    return deps.cells?.(version) ?? listChecklist(version, deps.root).items.map(item => ({ ...item, version }));
+  }));
+  const overlaps = observe('overlap', deps.overlaps ?? (() => {
+    const observed = collectWork();
+    if (observed.unreadableTrees || observed.unreadableGoals || observed.work.some(item => item.unreadable))
+      throw new Error(`incomplete work observation: trees=${observed.unreadableTrees} goals=${observed.unreadableGoals}`);
+    return observed.work;
+  }));
+  const result = authorDepth({ seats, now, caps: caps ?? {}, running, queued, cells, overlaps, unreadable });
+  const log = deps.log ?? ((category: string, event: string, data: Record<string, unknown>) => debug.log(category, event, data));
+  for (const row of result.seats) log('loop.orchestrator', 'would-author', {
+    seat: row.seat, target: row.target, have: row.queued, short: row.short, cells: row.wouldAuthor,
+  });
+  const ledger = deps.ledger ?? new AuthorLedger(deps.root === undefined ? {} : { path: join(deps.root, 'orchestrator', 'author-ledger.sqlite') });
+  const receiptCounts = { held: 0, queuedForAuthor: 0 };
+  let receiptFailures = 0;
+  for (const row of result.seats) for (const candidate of row.wouldAuthor) {
+    const cell = cells?.find(item => item.id === candidate.cellId && item.version === candidate.version);
+    try {
+      if (!cell) throw new Error('selected cell unavailable');
+      const text = cell.evidence ?? '';
+      const check = checkAuthorInput({ title: cell.title, text, cellId: cell.id, version: cell.version });
+      const receipt = ledger.request({ seat: row.seat, cellId: cell.id, version: cell.version, title: cell.title,
+        text, check: { verdict: check.verdict, signals: check.signals, ratio: check.implementationRatio } });
+      if (receipt.status === 'held') receiptCounts.held++;
+      if (receipt.status === 'queued-for-author') receiptCounts.queuedForAuthor++;
+    } catch (error) {
+      receiptFailures++;
+      result.unreadable.push({ source: 'author-ledger', reason: `${candidate.version} ${candidate.cellId}: ${error instanceof Error ? error.message : String(error)}` });
+    }
+  }
+  result.receiptCounts = receiptCounts;
+  result.receiptFailures = receiptFailures;
+  return result;
+}
+
+const SHADOW_INTERVAL_MS = 30 * 60_000;
+
+/** The queue tick serializes callers; stamp before collection so even a failing shadow cannot run every two minutes. */
+export function runAuthorDepthShadow(root = effectiveInstanceRoot(), now = new Date(), collect = collectAuthorDepth): void {
+  const path = join(root, 'orchestrator', 'author-depth-shadow-at');
+  const time = now.getTime();
+  if (!Number.isFinite(time)) throw new Error('invalid author-depth shadow clock');
+  if (existsSync(path)) {
+    const last = Date.parse(readFileSync(path, 'utf8').trim());
+    if (!Number.isFinite(last)) throw new Error('invalid author-depth shadow marker');
+    if (time - last < SHADOW_INTERVAL_MS) return;
+  }
+  mkdirSync(join(root, 'orchestrator'), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, now.toISOString(), { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, path);
+  } catch (error) {
+    try { unlinkSync(temporary); } catch { /* No temporary file to remove. */ }
+    throw error;
+  }
+  const result = collect({ root, now });
+  if (result.unreadable.length || result.receiptFailures || !result.receiptCounts) {
+    throw new Error(`author-depth shadow incomplete: ${JSON.stringify({ unreadable: result.unreadable, receiptFailures: result.receiptFailures })}`);
+  }
+}
+
+export function authorDepthLines(result: AuthorDepthResult): string[] {
+  return result.seats.map(row => `${row.seat} ${row.running ?? '?'}/${row.cap ?? '?'} · 대기 ${row.queued ?? '?'} · 목표 ${row.target ?? '?'} · 모자람 ${row.short ?? '?'} → ${row.wouldAuthor.map(cell => cell.cellId).join(', ') || '없음'}`);
+}
+
+if (import.meta.main) {
+  try {
+    if (process.argv.slice(2).some(arg => arg !== '--json')) throw new Error('usage: author-depth.ts [--json]');
+    const result = collectAuthorDepth();
+    if (process.argv.includes('--json')) console.log(JSON.stringify(result));
+    else {
+      for (const line of authorDepthLines(result)) console.log(line);
+      for (const source of result.unreadable) console.error(`author-depth ${source.source}: ${source.reason}`);
+    }
+  } catch (error) {
+    console.error(`author-depth: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
+}