elanous 0.2.13 → 0.2.15

package/src/loops/orchestrator/author-input-check.ts

@@ -0,0 +1,82 @@
+import { debug } from '../../debug/log.js';
+
+export interface AuthorInput {
+  title: string;
+  text: string;
+  cellId: string;
+  version: string;
+}
+
+export interface AuthorInputSignal {
+  kind: 'path' | 'symbol' | 'command' | 'marker' | 'missing';
+  match: string;
+  field: 'title' | 'text';
+  reason: string;
+}
+
+export interface AuthorInputCheck {
+  verdict: 'approved' | 'resubmit' | 'confirm' | 'uncheckable';
+  signals: AuthorInputSignal[];
+  units: { checked: number; candidates: number };
+  implementationRatio: number | null;
+}
+
+const TOKEN_SHAPES: ReadonlyArray<{ kind: AuthorInputSignal['kind']; pattern: RegExp; reason: string }> = [
+  { kind: 'path', pattern: /[\w.@~-]+\/[\w./@~-]+|[\w-]+\.[A-Za-z][A-Za-z0-9]{0,7}/g,
+    reason: '경로 또는 파일 이름 꼴' },
+  { kind: 'symbol', pattern: /[A-Za-z_][\w.]*\(\)|`[A-Za-z_][\w.]*`/g,
+    reason: '함수 또는 심볼 이름 꼴' },
+  { kind: 'command', pattern: /\b(?:bun|npm|pnpm|yarn|npx|bunx|node|deno|python3?|pip|uv|make|git|gh|cargo|go|docker|kubectl|elanous|eln|bash|sh|zsh|curl)\s+[a-z][\w-]*\b|--[\w-]+/g,
+    reason: '실행 명령 또는 플래그 꼴' },
+  { kind: 'marker', pattern: /대상 경로:|경계:|불변식:|판정 신호:|관측\s*=|기대\s*=/g,
+    reason: '골 구조 마커 꼴' },
+];
+
+const KOREAN_DIRECTIVE = /하라|해라|하세요|하십시오|해\s?주세요|해\s?줘|해야|바꿔|고쳐|넣어|빼|돌려|추가|수정|삭제|판정|실행|쓰라/;
+const ENGLISH_DIRECTIVE = /\b(?:please|must|should)\b|^\s*(?:run|edit|change|fix|add|remove|delete|update|modify|execute|test|build|use|write|implement|create|set|check|verify)\b/i;
+
+function sentences(value: string): string[] {
+  return value.split(/(?<=[.?])(?=\s|$)|\n+/).map(part => part.trim()).filter(Boolean);
+}
+
+export function checkAuthorInput({ title, text, cellId, version }: AuthorInput): AuthorInputCheck {
+  const validIdentity = [title, cellId, version].every(value => typeof value === 'string' && !!value.trim())
+    && /^\d+\.\d+\.\d+$/.test(version);
+  const missingText = typeof text !== 'string' || !text.trim();
+  const valid = validIdentity && !missingText;
+  const signals: AuthorInputSignal[] = [];
+  if (validIdentity && missingText) signals.push({ kind: 'missing', match: '', field: 'text', reason: 'missing cell text' });
+  let checked = 0;
+  let candidates = 0;
+  let directed = false;
+
+  if (validIdentity) {
+    for (const field of ['title', 'text'] as const) {
+      if (field === 'text' && missingText) continue;
+      for (const sentence of sentences(field === 'title' ? title : text)) {
+        checked++;
+        let found = false;
+        for (const { kind, pattern, reason } of TOKEN_SHAPES) {
+          for (const match of sentence.matchAll(pattern)) {
+            signals.push({ kind, match: match[0], field, reason });
+            found = true;
+            if (kind === 'marker' || kind === 'command') directed = true;
+          }
+        }
+        if (found) {
+          candidates++;
+          if (KOREAN_DIRECTIVE.test(sentence) || ENGLISH_DIRECTIVE.test(sentence)) directed = true;
+        }
+      }
+    }
+  }
+
+  const verdict: AuthorInputCheck['verdict'] = !valid ? 'uncheckable'
+    : signals.length === 0 ? 'approved' : directed ? 'resubmit' : 'confirm';
+  const implementationRatio = valid ? candidates / checked : null;
+  if (!valid) { checked = 0; candidates = 0; }
+  debug.log('author.par', 'input-checked', {
+    cellId, version, verdict, signals: signals.length, ratio: implementationRatio,
+  });
+  return { verdict, signals, units: { checked, candidates }, implementationRatio };
+}

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

@@ -0,0 +1,232 @@
+import { Database } from 'bun:sqlite';
+import { createHash } from 'node:crypto';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+
+export type AuthorVerdict = 'approved' | 'resubmit' | 'confirm' | 'uncheckable';
+export type AuthorStatus = 'held' | 'queued-for-author' | 'authoring' | 'authored' | 'enqueued'
+  | 'failed' | 'cancelled' | 'superseded-by-cell-change';
+export interface AuthorCheck { verdict: AuthorVerdict; signals: unknown[]; ratio: number | null }
+export interface AuthorRequest { seat: string; cellId: string; version: string; title: string; text: string; check: AuthorCheck }
+export interface AuthorDetail {
+  queueId?: string;
+  goalRef?: string;
+  supersededBy?: string;
+  textHash?: string;
+  reason?: string;
+}
+export interface AuthorHistory {
+  fromStatus: AuthorStatus | null;
+  toStatus: AuthorStatus;
+  at: string;
+  by: string;
+  detail: AuthorDetail | AuthorCheck | string;
+}
+export interface AuthorRow extends AuthorRequest {
+  id: string;
+  status: AuthorStatus;
+  queueId: string | null;
+  goalRef: string | null;
+  supersededBy: string | null;
+  textHash: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+export interface AuthorRecord extends AuthorRow { history: AuthorHistory[] }
+export interface AuthorMetric { value: number | null; reason?: '못 쟀다(원장 결손)' }
+export interface AuthorMetrics {
+  tps: AuthorMetric;
+  latencyMs: AuthorMetric;
+  depthBySeat: { value: Record<string, number> | null; reason?: '못 쟀다(원장 결손)' };
+}
+export interface AuthorLedgerOptions { path?: string; now?: () => Date }
+
+type StoredRow = Omit<AuthorRow, 'check'> & { checkJson: string };
+type StoredHistory = Omit<AuthorHistory, 'detail'> & { detailJson: string };
+const unmeasured = { value: null, reason: '못 쟀다(원장 결손)' } as const;
+// Terminal states never change again: a cancel/fail after a supersede would erase the recorded replacement (supersededBy · textHash).
+const TERMINAL: ReadonlySet<AuthorStatus> = new Set(['failed', 'cancelled', 'superseded-by-cell-change']);
+const successors: Partial<Record<AuthorStatus, AuthorStatus>> = {
+  'queued-for-author': 'authoring', authoring: 'authored', authored: 'enqueued',
+};
+
+function hash(parts: string[]): string {
+  const digest = createHash('sha256');
+  for (const part of parts) {
+    const bytes = Buffer.from(part, 'utf8');
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(bytes.length);
+    digest.update(length).update(bytes);
+  }
+  return digest.digest('hex');
+}
+
+export class AuthorLedger {
+  readonly path: string;
+  private readonly now: () => Date;
+
+  constructor(options: AuthorLedgerOptions = {}) {
+    this.path = options.path ?? join(effectiveInstanceRoot(), 'orchestrator', 'author-ledger.sqlite');
+    this.now = options.now ?? (() => new Date());
+  }
+
+  private open(create: boolean): Database {
+    if (create) mkdirSync(dirname(this.path), { recursive: true });
+    const db = new Database(this.path, { create, strict: true });
+    try {
+      if (create) chmodSync(this.path, 0o600);
+      db.exec('PRAGMA busy_timeout = 10000');
+      db.exec('PRAGMA foreign_keys = ON');
+      if (create) db.exec(`CREATE TABLE IF NOT EXISTS requests (
+        id TEXT PRIMARY KEY, seat TEXT NOT NULL, cellId TEXT NOT NULL, version TEXT NOT NULL,
+        title TEXT NOT NULL, text TEXT NOT NULL, checkJson TEXT NOT NULL,
+        status TEXT NOT NULL, queueId TEXT, goalRef TEXT, supersededBy TEXT, textHash TEXT,
+        createdAt TEXT NOT NULL, updatedAt TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS history (
+          requestId TEXT NOT NULL REFERENCES requests(id), fromStatus TEXT, toStatus TEXT NOT NULL,
+          at TEXT NOT NULL, by TEXT NOT NULL, detailJson TEXT NOT NULL);`);
+      return db;
+    } catch (error) { db.close(); throw error; }
+  }
+
+  private using<T>(work: (db: Database) => T): T {
+    const db = this.open(true);
+    try { return work(db); } finally { db.close(); }
+  }
+
+  private transaction<T>(db: Database, work: () => T): T {
+    db.exec('BEGIN IMMEDIATE');
+    try { const result = work(); db.exec('COMMIT'); return result; }
+    catch (error) { db.exec('ROLLBACK'); throw error; }
+  }
+
+  private row(db: Database, id: string): AuthorRow {
+    const row = db.query('SELECT * FROM requests WHERE id = ?').get(id) as StoredRow | null;
+    if (!row) throw new Error(`author request not found: ${id}`);
+    const { checkJson, ...rest } = row;
+    return { ...rest, check: JSON.parse(checkJson) as AuthorCheck };
+  }
+
+  private record(db: Database, id: string, from: AuthorStatus | null, to: AuthorStatus,
+    at: string, by: string, detail: AuthorDetail | AuthorCheck | string): void {
+    db.query('INSERT INTO history (requestId, fromStatus, toStatus, at, by, detailJson) VALUES (?, ?, ?, ?, ?, ?)')
+      .run(id, from, to, at, by, JSON.stringify(detail));
+  }
+
+  private log(event: string, row: AuthorRow): void {
+    debug.log('author.par', 'ledger', { event, seat: row.seat, cellId: row.cellId, version: row.version, status: row.status });
+  }
+
+  request(input: AuthorRequest): AuthorRow & { duplicate: boolean } {
+    for (const key of ['seat', 'cellId', 'version', 'title'] as const) {
+      if (typeof input[key] !== 'string' || !input[key].trim()) throw new Error(`${key} is required`);
+    }
+    if (typeof input.text !== 'string' || (!input.text.trim() && input.check?.verdict !== 'uncheckable'))
+      throw new Error('text is required unless uncheckable');
+    if (!['approved', 'resubmit', 'confirm', 'uncheckable'].includes(input.check?.verdict)
+      || !Array.isArray(input.check.signals)
+      || (input.check.ratio !== null && (typeof input.check.ratio !== 'number' || !Number.isFinite(input.check.ratio))))
+      throw new Error('invalid author input check');
+    const id = hash([input.seat, input.cellId, input.version, input.title, input.text]);
+    return this.using(db => this.transaction(db, () => {
+      if (db.query('SELECT 1 FROM requests WHERE id = ?').get(id)) {
+        const row = this.row(db, id);
+        this.log('duplicate', row);
+        return { ...row, duplicate: true };
+      }
+      const at = this.now().toISOString();
+      const status = input.check.verdict === 'approved' ? 'queued-for-author' : 'held';
+      db.query(`INSERT INTO requests (id, seat, cellId, version, title, text, checkJson, status, createdAt, updatedAt)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.seat, input.cellId, input.version,
+        input.title, input.text, JSON.stringify(input.check), status, at, at);
+      this.record(db, id, null, status, at, 'system', input.check);
+      const row = this.row(db, id);
+      this.log('request', row);
+      return { ...row, duplicate: false };
+    }));
+  }
+
+  transition(id: string, to: AuthorStatus, input: { by: string; detail: AuthorDetail | string }): AuthorRow {
+    return this.using(db => this.transaction(db, () => {
+      const previous = this.row(db, id);
+      const allowed = !TERMINAL.has(previous.status) && (successors[previous.status] === to
+        || (to === 'superseded-by-cell-change' && (previous.status === 'authored' || previous.status === 'enqueued'))
+        || to === 'failed' || to === 'cancelled');
+      if (!allowed) throw new Error(`invalid author transition: ${previous.status} → ${to}`);
+      const detail = input.detail;
+      const fields = typeof detail === 'string' ? {} : detail;
+      if (!input.by?.trim()) throw new Error('by is required');
+      if (to === 'authored' && !fields.goalRef?.trim()) throw new Error('goalRef is required');
+      if (to === 'enqueued' && !fields.queueId?.trim()) throw new Error('queueId is required');
+      if (to === 'superseded-by-cell-change') {
+        if (!previous.goalRef) throw new Error('old goalRef is required');
+        if (!fields.supersededBy?.trim() || !/^[a-f0-9]{64}$/.test(fields.textHash ?? ''))
+          throw new Error('supersededBy and textHash are required');
+        const candidates = db.query(`SELECT id, text FROM requests
+          WHERE seat = ? AND cellId = ? AND version = ? AND goalRef = ? AND status IN ('authored', 'enqueued')`)
+          .all(previous.seat, previous.cellId, previous.version, fields.supersededBy) as Array<{ id: string; text: string }>;
+        if (candidates.length !== 1 || candidates[0]!.id === id || candidates[0]!.text === previous.text
+          || createHash('sha256').update(candidates[0]!.text, 'utf8').digest('hex') !== fields.textHash)
+          throw new Error('supersededBy and textHash must match a changed authored snapshot');
+      }
+      const at = this.now().toISOString();
+      const recordedDetail: AuthorDetail | string = typeof detail === 'string' ? detail :
+        to === 'authored' ? { goalRef: fields.goalRef } :
+        to === 'enqueued' ? { queueId: fields.queueId } :
+        to === 'superseded-by-cell-change' ? { supersededBy: fields.supersededBy, textHash: fields.textHash } :
+        to === 'failed' || to === 'cancelled' ? { reason: fields.reason } : {};
+      db.query(`UPDATE requests SET status = ?, queueId = COALESCE(?, queueId), goalRef = COALESCE(?, goalRef),
+        supersededBy = ?, textHash = ?, updatedAt = ? WHERE id = ?`).run(to,
+        to === 'enqueued' ? fields.queueId ?? null : null, to === 'authored' ? fields.goalRef ?? null : null,
+        to === 'superseded-by-cell-change' ? fields.supersededBy ?? null : null,
+        to === 'superseded-by-cell-change' ? fields.textHash ?? null : null, at, id);
+      this.record(db, id, previous.status, to, at, input.by, recordedDetail);
+      const row = this.row(db, id);
+      this.log('transition', row);
+      return row;
+    }));
+  }
+
+  get(id: string): AuthorRecord {
+    return this.using(db => ({ ...this.row(db, id), history: (db.query(
+      'SELECT fromStatus, toStatus, at, by, detailJson FROM history WHERE requestId = ? ORDER BY rowid',
+    ).all(id) as StoredHistory[]).map(({ detailJson, ...item }) => ({ ...item, detail: JSON.parse(detailJson) as AuthorDetail | AuthorCheck | string })) }));
+  }
+
+  metrics({ since, until }: { since: Date; until: Date }): AuthorMetrics {
+    const duration = (until.getTime() - since.getTime()) / 1000;
+    if (!Number.isFinite(duration) || duration <= 0) throw new Error('metrics window must have positive duration');
+    let db: Database;
+    try { db = this.open(false); }
+    catch { return { tps: unmeasured, latencyMs: unmeasured, depthBySeat: unmeasured }; }
+    try {
+      const start = since.toISOString();
+      const end = until.toISOString();
+      const events = (db.query('SELECT count(*) AS n FROM history WHERE at >= ? AND at < ?').get(start, end) as { n: number }).n;
+      if (!events) return { tps: unmeasured, latencyMs: unmeasured, depthBySeat: unmeasured };
+      const completed = db.query(`SELECT r.seat, r.version, r.cellId, r.createdAt, h.at
+        FROM history h JOIN requests r ON r.id = h.requestId
+        WHERE h.toStatus = 'authored' AND h.at >= ? AND h.at < ?`).all(start, end) as
+        Array<{ seat: string; version: string; cellId: string; createdAt: string; at: string }>;
+      const distinctCells = new Set(completed.map(row => JSON.stringify([row.seat, row.version, row.cellId])));
+      const delays = completed.map(row => Date.parse(row.at) - Date.parse(row.createdAt));
+      const latencyMs = delays.length && delays.every(delay => Number.isFinite(delay) && delay >= 0)
+        ? { value: delays.reduce((sum, delay) => sum + delay, 0) / delays.length } : unmeasured;
+      const depthRows = db.query(`WITH last_status AS (
+        SELECT requestId, toStatus, ROW_NUMBER() OVER (
+          PARTITION BY requestId ORDER BY at DESC, rowid DESC
+        ) AS rank FROM history WHERE at < ?
+      )
+        SELECT seat, count(*) AS n FROM (
+          SELECT DISTINCT r.seat, r.version, r.cellId FROM last_status h
+            JOIN requests r ON r.id = h.requestId
+            WHERE h.rank = 1 AND h.toStatus IN ('queued-for-author', 'authoring')
+        ) GROUP BY seat`).all(end) as Array<{ seat: string; n: number }>;
+      return { tps: { value: distinctCells.size / duration }, latencyMs,
+        depthBySeat: { value: Object.fromEntries(depthRows.map(row => [row.seat, row.n])) } };
+    } catch { return { tps: unmeasured, latencyMs: unmeasured, depthBySeat: unmeasured }; }
+    finally { db.close(); }
+  }
+}

package/src/loops/orchestrator/finish-rate.ts

@@ -0,0 +1,175 @@
+import { execFileSync } from 'node:child_process';
+import { readdirSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { loadRunLedger, resolveFederatedRunLedgerTargets } from '../../self-implement/run-ledger.js';
+import type { LogTarget } from '../../cli/logs-cli.js';
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const GH_LIMIT = 1000;
+
+export type FinishMetric = 'launched' | 'landed' | 'landingRate' | 'staleDrafts' | 'conflictRatio' | 'unknownMergeable';
+export type FinishMetrics = {
+  launched: number | null;
+  launchedUnreadable?: number;
+  landed: number | null;
+  landingRate: number | null;
+  staleDrafts: number | null;
+  conflictRatio: number | null;
+  unknownMergeable: number | null;
+  reasons: Partial<Record<FinishMetric, string>>;
+};
+export type FinishAdvice = { finishSlots: number; launchSlots: number; state: 'healthy' | 'backlogged' | 'unknown'; reasons: string[] };
+export type FinishThresholds = { landingRate?: number; staleDrafts?: number; conflictRatio?: number };
+
+type Start = { runId: string; startedAt: string };
+type StartObservation = { starts: readonly Start[]; unreadable: readonly { runId: string; reason: string }[]; unreadableDirectories?: number };
+type Pr = { number: number; headRefName: string; mergedAt?: string; createdAt?: string; mergeable?: string; labels?: { name: string }[] };
+export interface MeasureFinishDeps {
+  listStarts?: (cutoff: number) => StartObservation;
+  ledgerTargets?: readonly LogTarget[];
+  runGh?: (args: string[]) => string;
+}
+
+function defaultListStarts(cutoff: number, targets?: readonly LogTarget[]): StartObservation {
+  const directories = new Set<string>();
+  const starts = new Map<string, Start>();
+  const unreadable = new Map<string, { runId: string; reason: string }>();
+  const childLedgers = new Set<string>();
+  let unreadableDirectories = 0;
+  let unresolvedDirectories = 0;
+  for (const { ledgerDirectory } of resolveFederatedRunLedgerTargets({ includeTest: true, ...(targets ? { targets } : {}) })) {
+    let dir: string;
+    try {
+      dir = realpathSync(ledgerDirectory);
+    } catch {
+      unreadableDirectories += 1;
+      unresolvedDirectories += 1;
+      continue;
+    }
+    if (directories.has(dir)) continue;
+    directories.add(dir);
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      unreadableDirectories += 1;
+      continue;
+    }
+    for (const name of names) {
+      if (!/^run-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/.test(name)) continue;
+      const path = join(dir, name);
+      if (statSync(path).mtimeMs < cutoff) continue;
+      const runId = name.slice(0, -'.jsonl'.length);
+      const entries = loadRunLedger(runId, dir);
+      if (!entries) throw new Error(`run ledger disappeared: ${runId}`);
+      if (entries[0]?.event === 'pod-child-run') {
+        childLedgers.add(runId);
+        continue;
+      }
+      const start = entries.find(entry => entry.event === 'start');
+      if (!start?.timestamp) {
+        if (!starts.has(runId)) unreadable.set(runId, { runId, reason: entries[0]?.event ?? 'start missing' });
+        continue;
+      }
+      starts.set(runId, { runId, startedAt: start.timestamp });
+      unreadable.delete(runId);
+    }
+  }
+  debug.log('loop.orchestrator', 'finish-launch-population', {
+    directories: directories.size + unresolvedDirectories, launched: starts.size, childLedgers: childLedgers.size, unreadable: unreadable.size,
+  });
+  return { starts: [...starts.values()], unreadable: [...unreadable.values()], unreadableDirectories };
+}
+
+function defaultRunGh(args: string[]): string {
+  return execFileSync('gh', args, { cwd: resolve(import.meta.dir, '../../..'), encoding: 'utf8', timeout: 60_000, maxBuffer: 20 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function readPrs(runGh: (args: string[]) => string, args: string[]): Pr[] {
+  const parsed: unknown = JSON.parse(runGh(['pr', 'list', ...args, '--limit', String(GH_LIMIT)]));
+  if (!Array.isArray(parsed) || parsed.length >= GH_LIMIT || parsed.some(pr => !pr || typeof pr !== 'object'
+    || typeof pr.number !== 'number' || typeof pr.headRefName !== 'string')) throw new Error('incomplete or invalid PR observation');
+  return parsed as Pr[];
+}
+
+function reason(error: unknown): string { return error instanceof Error ? error.message : String(error); }
+
+/** Read each source independently; an unreadable source never becomes a measured zero. */
+export function measureFinish(deps: MeasureFinishDeps = {}, now: Date = new Date()): FinishMetrics {
+  const reasons: FinishMetrics['reasons'] = {};
+  const cutoff = now.getTime() - DAY_MS;
+  let launched: number | null = null;
+  let launchedUnreadable = 0;
+  let landed: number | null = null;
+  let staleDrafts: number | null = null;
+  let conflictRatio: number | null = null;
+  let unknownMergeable: number | null = null;
+  const gh = deps.runGh ?? defaultRunGh;
+  try {
+    const observation = deps.listStarts ? deps.listStarts(cutoff) : defaultListStarts(cutoff, deps.ledgerTargets);
+    if (!observation || !Array.isArray(observation.starts) || !Array.isArray(observation.unreadable)
+      || observation.starts.some(start => !start || typeof start.runId !== 'string' || !Number.isFinite(Date.parse(start.startedAt)))
+      || observation.unreadable.some(entry => !entry || typeof entry.runId !== 'string' || typeof entry.reason !== 'string')) throw new Error('invalid run start observation');
+    launched = new Set(observation.starts.filter(start => Date.parse(start.startedAt) >= cutoff && Date.parse(start.startedAt) <= now.getTime()).map(start => start.runId)).size;
+    launchedUnreadable = observation.unreadable.length;
+    if (launchedUnreadable > 0) {
+      reasons.launched = `${launchedUnreadable}개 원장 시작 줄 없음(하한값)`;
+      debug.log('loop.orchestrator', 'finish-ledger-unreadable', { count: launchedUnreadable, sample: observation.unreadable.slice(0, 5) });
+    }
+    if (observation.unreadableDirectories) {
+      reasons.launched = [reasons.launched, `원장 폴더 ${observation.unreadableDirectories}개 못 읽음(하한값)`].filter(Boolean).join(' · ');
+    }
+  } catch (error) { reasons.launched = reason(error); }
+  try {
+    const prs = readPrs(gh, ['--state', 'merged', '--search', `merged:>=${new Date(cutoff).toISOString().replace(/\.\d{3}Z$/, 'Z')}`, '--json', 'number,headRefName,mergedAt']);
+    if (prs.some(pr => typeof pr.mergedAt !== 'string' || !Number.isFinite(Date.parse(pr.mergedAt)))) throw new Error('invalid merged PR timestamp');
+    landed = new Set(prs.filter(pr => pr.headRefName.startsWith('self-impl/') && Date.parse(pr.mergedAt!) >= cutoff
+      && Date.parse(pr.mergedAt!) <= now.getTime()).map(pr => pr.number)).size;
+  } catch (error) { reasons.landed = reason(error); }
+  try {
+    const drafts = readPrs(gh, ['--state', 'open', '--draft', '--json', 'number,headRefName,createdAt,mergeable,labels']);
+    if (drafts.some(pr => typeof pr.createdAt !== 'string' || !Number.isFinite(Date.parse(pr.createdAt)) || !Array.isArray(pr.labels)
+      || pr.labels.some(label => !label || typeof label.name !== 'string'))) throw new Error('invalid draft observation');
+    staleDrafts = drafts.filter(pr => pr.headRefName.startsWith('self-impl/') && Date.parse(pr.createdAt!) < cutoff
+      && !pr.labels!.some(label => label.name === 'elanous:superseded')).length;
+  } catch (error) { reasons.staleDrafts = reason(error); }
+  try {
+    const prs = readPrs(gh, ['--state', 'open', '--json', 'number,headRefName,mergeable']);
+    const harness = prs.filter(pr => pr.headRefName.startsWith('self-impl/'));
+    if (harness.some(pr => !['CONFLICTING', 'MERGEABLE', 'UNKNOWN'].includes(pr.mergeable ?? ''))) throw new Error('invalid mergeability observation');
+    unknownMergeable = harness.filter(pr => pr.mergeable === 'UNKNOWN').length;
+    const known = harness.length - unknownMergeable;
+    if (known === 0) reasons.conflictRatio = 'no open harness PRs with known mergeability';
+    else conflictRatio = harness.filter(pr => pr.mergeable === 'CONFLICTING').length / known;
+  } catch (error) { reasons.conflictRatio = reason(error); reasons.unknownMergeable = reason(error); unknownMergeable = null; }
+  let landingRate: number | null = null;
+  if (launched === null) reasons.landingRate = `launched unavailable: ${reasons.launched}`;
+  else if (landed === null) reasons.landingRate = `landed unavailable: ${reasons.landed}`;
+  else if (launched === 0) reasons.landingRate = reasons.launched
+    ? `launched lower bound is zero — launch population unknown: ${reasons.launched}`
+    : 'no harness runs launched in the last 24 hours';
+  else if (landed > launched) reasons.landingRate = `landed exceeds launched — population mismatch (launched=${launched}, landed=${landed})`;
+  else landingRate = landed / launched;
+  return { launched, ...(launchedUnreadable > 0 ? { launchedUnreadable } : {}), landed, landingRate, staleDrafts, conflictRatio, unknownMergeable, reasons };
+}
+
+/** Advice only: no launch cap, PR, or config is changed. */
+export function finishAdvice(metrics: FinishMetrics, totalSlots: number, thresholds: FinishThresholds = {}): FinishAdvice {
+  const reasons: string[] = [];
+  const missing = (['launched', 'landed', 'landingRate', 'staleDrafts', 'conflictRatio', 'unknownMergeable'] as const)
+    .filter(key => metrics[key] === null).map(key => `${key}: ${metrics.reasons[key] ?? 'unavailable'}`);
+  let state: FinishAdvice['state'];
+  let desired: number;
+  if (missing.length) { state = 'unknown'; desired = 6; reasons.push(...missing); }
+  else {
+    if (metrics.landingRate! < (thresholds.landingRate ?? 0.5)) reasons.push('landingRate below threshold');
+    if (metrics.staleDrafts! > (thresholds.staleDrafts ?? 20)) reasons.push('staleDrafts above threshold');
+    if (metrics.conflictRatio! > (thresholds.conflictRatio ?? 0.3)) reasons.push('conflictRatio above threshold');
+    state = reasons.length ? 'backlogged' : 'healthy';
+    desired = state === 'backlogged' ? Math.max(6, Math.ceil(totalSlots * 0.3)) : 2;
+  }
+  if (metrics.launched !== null && metrics.reasons.launched) reasons.push(metrics.reasons.launched);
+  const finishSlots = Math.min(totalSlots, desired);
+  return { finishSlots, launchSlots: totalSlots - finishSlots, state, reasons };
+}

package/src/loops/orchestrator/overlap.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { basename, isAbsolute, resolve } from 'node:path';
+import { readFileSync, readdirSync } from 'node:fs';
+import { basename, isAbsolute, join, 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';
@@ -10,7 +10,8 @@ export type WorkItem = { kind: 'pr' | 'goal'; ref: string; seat: OrchestratorSea
 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 };
+type OpenPr = { number: number; title: string; body?: string | null; headRefName: string; files: Array<{ path: string }>; isDraft: boolean; labels: Array<{ name: string }> };
+export type CollectWorkResult = { work: WorkItem[]; excluded: { stalled: number; superseded: number; draft: number }; unreadableTrees: number; unreadableGoals: number };
 export interface CollectWorkDeps {
   runGh?: (args: string[]) => string;
   listProcesses?: () => HarnessProcessListObservation;
@@ -59,14 +60,51 @@ function goalFiles(text: string): string[] {
   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[];
+export function collectWork(deps: CollectWorkDeps = {}): CollectWorkResult {
+  const prs = JSON.parse((deps.runGh ?? defaultRunGh)(['pr', 'list', '--state', 'open', '--limit', '1000', '--json', 'number,title,body,headRefName,files,isDraft,labels'])) 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 ?? ''}`) }));
+  const excluded = { stalled: 0, superseded: 0, draft: 0 };
+  const ready = prs.filter(pr => {
+    const labels = pr.labels ?? [];
+    if (labels.some(label => label.name === 'elanous:stalled')) { excluded.stalled++; return false; }
+    if (labels.some(label => label.name === 'elanous:superseded')) { excluded.superseded++; return false; }
+    if (pr.isDraft) { excluded.draft++; return false; }
+    return true;
+  });
+  const seatsByPr = new Map<number, Set<OrchestratorSeat>>();
+  let unreadableTrees = 0;
+  let unreadableGoals = 0;
+  for (const seat of TRAFFIC_SEATS) {
+    for (const tree of cfg.seatTrees[seat] ?? []) {
+      try {
+        const goals = join(tree, 'docs', 'goals');
+        const numbers = new Set<number>();
+        for (const entry of readdirSync(goals, { withFileTypes: true })) {
+          if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+          // One unreadable goal file must not drop the whole tree's PR→seat mapping; count it instead.
+          let text: string;
+          try { text = (deps.readGoal ?? ((file: string) => readFileSync(file, 'utf8')))(join(goals, entry.name)); }
+          catch { unreadableGoals++; continue; }
+          for (const match of text.matchAll(/^[ \t]*prNumber:[ \t]*(\d+)[ \t]*\r?$/gm)) numbers.add(Number(match[1]));
+        }
+        for (const number of numbers) {
+          const seats = seatsByPr.get(number) ?? new Set<OrchestratorSeat>();
+          seats.add(seat);
+          seatsByPr.set(number, seats);
+        }
+      } catch {
+        unreadableTrees++;
+      }
+    }
+  }
+  const work: WorkItem[] = ready.map(pr => {
+    const matched = seatsByPr.get(pr.number);
+    return { kind: 'pr', ref: `#${pr.number}`, seat: seatOfPr(pr.title) ?? (matched?.size === 1 ? [...matched][0]! : null),
+      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;
@@ -86,7 +124,7 @@ export function collectWork(deps: CollectWorkDeps = {}): WorkItem[] {
     }
     work.push({ kind: 'goal', ref, seat, files: goalFiles(text), cells: cellsOf(text) });
   }
-  return work;
+  return { work, excluded, unreadableTrees, unreadableGoals };
 }
 
 export function findOverlaps(work: readonly WorkItem[], excludedFiles: readonly string[] = ['release/next.md']): Overlap[] {
@@ -119,16 +157,17 @@ export function renderOverlaps(overlaps: readonly Overlap[]): string[] {
 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 { work, excluded, unreadableTrees, unreadableGoals } = 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}`;
+    const seatNull = work.filter(item => item.kind === 'pr' && item.seat === null).length;
+    debug.log('loop.orchestrator', 'exchange', { node: 'overlap', files, cells, crossSeat, excluded, seatNull, unreadableTrees, unreadableGoals });
+    const summary = `overlap work=${work.length} files=${files} cells=${cells} crossSeat=${crossSeat} unreadable=${unreadable} excluded=stalled:${excluded.stalled},superseded:${excluded.superseded},draft:${excluded.draft} seatNull=${seatNull} unreadableTrees=${unreadableTrees} unreadableGoals=${unreadableGoals}`;
     if (process.argv.includes('--json')) {
-      console.log(JSON.stringify({ work, overlaps }));
+      console.log(JSON.stringify({ work, overlaps, excluded, seatNull, unreadableTrees, unreadableGoals }));
       console.error(summary);
     } else {
       for (const line of renderOverlaps(overlaps)) console.log(line);