elanous 0.2.14 → 0.2.15

package/src/intake-plane/lens.ts

@@ -0,0 +1,177 @@
+// 흡수 렌즈 — outbox 항목마다 «우리에게 무엇인가»를 판정해 outbox/lens/<day>.jsonl 에만 남긴다.
+// 원 갈래(goals·manual·review·release)는 읽기만 한다. LLM 은 judge 한 번(id 당).
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { judge } from '../llm/judge-layer.js';
+import { intakeOutboxDir } from './route.js';
+
+export const LENS_VERDICTS = ['대체 후보', '보강', '경쟁 대조', '참고'] as const;
+export type LensVerdict = (typeof LENS_VERDICTS)[number];
+
+export const LENS_BRANCHES = ['goals', 'manual', 'review', 'release'] as const;
+export const LENS_DAILY_CAP = 20;
+export const LENS_FACT_CAP = 12;
+
+export interface LensRecord {
+  id: string;
+  at: string;
+  lensVerdict: LensVerdict;
+  why: string;
+  target: string;
+}
+
+export interface LensJudgeInput {
+  id: string;
+  facts: { fact: string; current: string }[];
+  url?: string;
+}
+
+export type LensJudge = (input: LensJudgeInput) => Promise<unknown>;
+
+export interface AnnotateIntakeLensDeps {
+  judge?: LensJudge;
+  now?: () => string;
+  log?: (event: string, data: Record<string, unknown>) => void;
+}
+
+export interface AnnotateIntakeLensResult {
+  judged: number;
+  skipped: number;
+  failed: number;
+  capped: boolean;
+}
+
+interface GroupedItem {
+  id: string;
+  facts: { fact: string; current: string }[];
+  url?: string;
+}
+
+function readJsonl(file: string): Record<string, unknown>[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, 'utf8').split('\n').filter(Boolean).flatMap((line) => {
+    try { const row = JSON.parse(line) as unknown; return row && typeof row === 'object' && !Array.isArray(row) ? [row as Record<string, unknown>] : []; }
+    catch { return []; }
+  });
+}
+
+function isTestProcess(): boolean {
+  return process.env.NODE_ENV === 'test' || Boolean(process.env.ELANOUS_TEST_HOME);
+}
+
+function isLensVerdict(value: unknown): value is LensVerdict {
+  return typeof value === 'string' && (LENS_VERDICTS as readonly string[]).includes(value);
+}
+
+/** 스키마 밖이면 null — 기록하지 않는다. why 는 한 문장이다. */
+export function coerceLensVerdict(raw: unknown): Omit<LensRecord, 'id' | 'at'> | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const row = raw as Record<string, unknown>;
+  const why = typeof row.why === 'string' ? row.why.trim() : '';
+  const target = typeof row.target === 'string' ? row.target.trim() : '';
+  if (!isLensVerdict(row.lensVerdict) || !why || !target) return null;
+  if (/[\r\n]/.test(why)) return null;
+  return { lensVerdict: row.lensVerdict, why, target };
+}
+
+function groupOutbox(root: string, day: string): GroupedItem[] {
+  const out = intakeOutboxDir(root);
+  const order: string[] = [];
+  const groups = new Map<string, GroupedItem>();
+  for (const branch of LENS_BRANCHES) {
+    for (const row of readJsonl(join(out, branch, `${day}.jsonl`))) {
+      const id = typeof row.id === 'string' ? row.id.trim() : '';
+      const fact = typeof row.fact === 'string' ? row.fact.trim() : '';
+      const current = typeof row.current === 'string' ? row.current.trim() : '';
+      if (!id || !fact) continue;
+      let group = groups.get(id);
+      if (!group) {
+        group = { id, facts: [] };
+        groups.set(id, group);
+        order.push(id);
+      }
+      if (!group.url && typeof row.url === 'string' && row.url.trim()) group.url = row.url.trim();
+      if (group.facts.length < LENS_FACT_CAP) group.facts.push({ fact, current });
+    }
+  }
+  return order.map((id) => groups.get(id)!);
+}
+
+function judgedIds(file: string): Set<string> {
+  return new Set(readJsonl(file).flatMap((row) => typeof row.id === 'string' && row.id ? [row.id] : []));
+}
+
+function lensPrompt(item: GroupedItem): string {
+  const lines = item.facts.map((row, i) => `${i + 1}. fact: ${row.fact}\n   current: ${row.current || '(없음)'}`);
+  return [
+    'SYSTEM:',
+    '흡수 항목이 우리에게 무엇인가를 한 번만 판정한다. 경로를 나열하지 말고, 왜 우리에게 그 판정인지를 한 문장으로 말한다.',
+    'lensVerdict 는 다음 넷 중 하나다: 대체 후보 · 보강 · 경쟁 대조 · 참고.',
+    'target 은 닿는 우리 쪽 이름 하나(기능·칸·파일)다.',
+    'JSON 만 답한다: {"lensVerdict":"...","why":"...","target":"..."}',
+    '',
+    `id: ${item.id}`,
+    ...(item.url ? [`url: ${item.url}`] : []),
+    ...lines,
+  ].join('\n');
+}
+
+async function defaultJudge(item: GroupedItem): Promise<unknown> {
+  const decision = await judge({
+    site: 'intake.lens',
+    prompt: lensPrompt(item),
+    schema: (value) => coerceLensVerdict(value),
+  });
+  if (!decision.ok) {
+    if (decision.reason === 'schema') return null;
+    throw decision.error instanceof Error ? decision.error : new Error(String(decision.error));
+  }
+  return decision.value;
+}
+
+/** 그날 outbox 를 id 로 묶어 아직 없는 판정만 남긴다. 원 갈래 파일은 쓰지 않는다. */
+export async function annotateIntakeLens(
+  root: string,
+  day: string,
+  deps: AnnotateIntakeLensDeps = {},
+): Promise<AnnotateIntakeLensResult> {
+  const log = deps.log ?? ((event, data) => { debug.log('intake.lens', event, data); });
+  const empty = { judged: 0, skipped: 0, failed: 0, capped: false };
+  if (!deps.judge && isTestProcess()) {
+    log('skipped-test', {});
+    return empty;
+  }
+  const items = groupOutbox(root, day);
+  const file = join(intakeOutboxDir(root), 'lens', `${day}.jsonl`);
+  const done = judgedIds(file);
+  const pending = items.filter((item) => !done.has(item.id));
+  const capped = pending.length > LENS_DAILY_CAP;
+  const batch = pending.slice(0, LENS_DAILY_CAP);
+  if (capped) log('capped', { day, total: pending.length, judged: batch.length });
+  const judgeOne = deps.judge ?? ((input: LensJudgeInput) => defaultJudge(input));
+  const now = deps.now ?? (() => new Date().toISOString());
+  let judged = 0;
+  let failed = 0;
+  for (const item of batch) {
+    let raw: unknown;
+    try {
+      raw = await judgeOne({ id: item.id, facts: item.facts, ...(item.url ? { url: item.url } : {}) });
+    } catch (error) {
+      failed++;
+      log('judge-failed', { id: item.id, reason: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    const verdict = coerceLensVerdict(raw);
+    if (!verdict) {
+      failed++;
+      log('judge-failed', { id: item.id, reason: 'schema' });
+      continue;
+    }
+    mkdirSync(join(intakeOutboxDir(root), 'lens'), { recursive: true });
+    const record: LensRecord = { id: item.id, at: now(), ...verdict };
+    appendFileSync(file, `${JSON.stringify(record)}\n`);
+    judged++;
+  }
+  return { judged, skipped: items.length - pending.length, failed, capped };
+}

package/src/intake-plane/route.ts

@@ -3,9 +3,13 @@
 // ⛔ 원장의 `text`(개인 메모일 수 있다)는 큐에 싣지 않는다 — 대조가 낸 사실·근거와 노트 경로만.
 import { execFileSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
 import { join } from 'node:path';
 import { debug } from '../debug/log.js';
-import { intakeLedgerDir, loadIntakeLedger, markIntakeItem, type IntakeItem } from './items.js';
+import { getToxRuntimeDeps } from '../task-orchestrator/runtime-deps.js';
+import type { TaskStore } from '../task-orchestrator/store.js';
+import type { TaskStatus } from '../task-orchestrator/types.js';
+import { canonicalUrl, ingestIntakeItems, intakeItemId, intakeLedgerDir, loadIntakeLedger, markIntakeItem, type IntakeItem } from './items.js';
 
 /** `elanous intake check --json` 산출 중 갈래가 읽는 칸. */
 export interface IntakeCheckJson {
@@ -29,6 +33,146 @@ export const gitLastCommitOf: LastCommitOf = (tree, path) => {
 
 export function intakeOutboxDir(root: string): string { return join(intakeLedgerDir(root), 'outbox'); }
 
+export const INTAKE_EVENT_DEFERRED_REPLY = '일일 즉시 흡수 상한을 넘어 다음 일일 판으로 미뤘습니다.';
+export type IntakeEventResult = { status: 'scheduled' | 'deferred' | 'duplicate'; reason: string; url: string; reply?: string };
+
+// A lost claim must become eligible at the next daily pass; live tasks remain excluded.
+const INTAKE_EVENT_LEASE_MS = 23 * 3600_000;
+
+// A non-terminal task that has not been touched for this long is treated as a dead worker.
+const INTAKE_EVENT_TASK_STALE_MS = 2 * 3600_000;
+
+/** A probe may return the bare status, or the status with the task's last update (epoch ms). */
+export type IntakeEventTaskProbe = (id: string) => TaskStatus | { status: TaskStatus; updatedAt?: number } | undefined;
+
+function eventTaskStatus(taskId: string): { status: TaskStatus; updatedAt?: number } | undefined {
+  const deps = getToxRuntimeDeps();
+  const graphTask = deps.getGraph()?.getTask(taskId) ?? (deps.getStore?.() as TaskStore | null | undefined)?.getTask(taskId);
+  return graphTask ? { status: graphTask.status, updatedAt: graphTask.updatedAt } : undefined;
+}
+
+function probeStatus(probe: IntakeEventTaskProbe, id: string): { status?: TaskStatus; updatedAt?: number } {
+  const value = probe(id);
+  return typeof value === 'string' ? { status: value } : value ?? {};
+}
+
+type EventClaim = { status: string; task_id: string | null; claimed_at: string | null; day: string };
+
+function activeEventClaim(row: EventClaim, now: string, taskStatus: IntakeEventTaskProbe): boolean {
+  if (row.status !== 'scheduled' && row.status !== 'pending') return false;
+  const { status, updatedAt } = row.task_id ? probeStatus(taskStatus, row.task_id) : {};
+  if (status === 'done') return true;
+  if (status === 'failed' || status === 'cancelled' || status === 'superseded') return false;
+  const claimedAt = Date.parse(row.claimed_at ?? `${row.day}T00:00:00.000+09:00`);
+  const withinLease = Number.isFinite(claimedAt) && Date.parse(now) - claimedAt < INTAKE_EVENT_LEASE_MS;
+  if (!status) return withinLease;
+  // A status alone is not liveness: a crashed worker leaves «running» behind, so require a recent update.
+  if (updatedAt !== undefined && Number.isFinite(updatedAt)) return Date.parse(now) - updatedAt < INTAKE_EVENT_TASK_STALE_MS;
+  return withinLease;
+}
+
+/** Claim an event slot before posting. The unique URL and KST-day quota share one SQLite transaction. */
+export async function scheduleIntakeEvent(
+  root: string,
+  url: string,
+  opts: {
+    eventMax?: number;
+    now?: string;
+    post: (input: { url: string }) => Promise<{ taskId: string }>;
+  },
+): Promise<IntakeEventResult> {
+  const normalized = canonicalUrl(url);
+  if (!normalized) throw new Error('intake event requires an HTTP(S) URL');
+  const now = opts.now ?? new Date().toISOString();
+  const day = kstDay(now);
+  const id = intakeItemId('telegram-bot', { url: normalized });
+  const max = opts.eventMax ?? 10;
+  if (!Number.isSafeInteger(max) || max < 0) throw new RangeError('intake.eventMax must be a non-negative integer');
+  const existing = loadIntakeLedger(root).items.get(id);
+  if (existing && ['queued', 'absorbed', 'checked', 'routed', 'discarded'].includes(existing.status)) {
+    return { status: 'duplicate', url: normalized, reason: 'already-in-ledger' };
+  }
+  mkdirSync(intakeLedgerDir(root), { recursive: true });
+  const db = new Database(join(intakeLedgerDir(root), 'events.sqlite'), { create: true });
+  db.exec('PRAGMA busy_timeout = 5000');
+  try {
+    db.exec(`CREATE TABLE IF NOT EXISTS intake_events (
+      url TEXT PRIMARY KEY, day TEXT NOT NULL, status TEXT NOT NULL, task_id TEXT, claimed_at TEXT
+    )`);
+    const columns = db.query('PRAGMA table_info(intake_events)').all() as { name: string }[];
+    if (!columns.some((column) => column.name === 'claimed_at')) db.exec('ALTER TABLE intake_events ADD COLUMN claimed_at TEXT');
+    // One row per claim that reached the task queue — the KST-day quota counts these, not current statuses.
+    db.exec('CREATE TABLE IF NOT EXISTS intake_event_claims (url TEXT NOT NULL, day TEXT NOT NULL, claimed_at TEXT NOT NULL, PRIMARY KEY (url, claimed_at))');
+    const claim = db.transaction((): 'scheduled' | 'deferred' | 'duplicate' => {
+      const previous = db.query('SELECT status, task_id, claimed_at, day FROM intake_events WHERE url = ?').get(normalized) as EventClaim | null;
+      if (previous && activeEventClaim(previous, now, eventTaskStatus)) {
+        if (previous.task_id && eventTaskStatus(previous.task_id)?.status === 'done') {
+          db.query("UPDATE intake_events SET status = 'completed' WHERE url = ?").run(normalized);
+        }
+        return 'duplicate';
+      }
+      if (previous && previous.status !== 'failed' && previous.status !== 'expired'
+        && previous.status !== 'pending' && previous.status !== 'scheduled') {
+        return previous.status === 'deferred' ? 'deferred' : 'duplicate';
+      }
+      const count = db.query('SELECT count(*) AS n FROM intake_event_claims WHERE day = ?').get(day) as { n: number };
+      const status = count.n >= max ? 'deferred' : 'pending';
+      db.query(`INSERT INTO intake_events (url, day, status, claimed_at) VALUES (?, ?, ?, ?)
+        ON CONFLICT(url) DO UPDATE SET day = excluded.day, status = excluded.status, claimed_at = excluded.claimed_at, task_id = NULL`)
+        .run(normalized, day, status, now);
+      if (status === 'pending') db.query('INSERT OR IGNORE INTO intake_event_claims (url, day, claimed_at) VALUES (?, ?, ?)').run(normalized, day, now);
+      return status === 'pending' ? 'scheduled' : 'deferred';
+    })();
+    if (claim === 'duplicate') return { status: 'duplicate', url: normalized, reason: 'already-claimed' };
+    if (claim === 'deferred') {
+      ingestIntakeItems(root, 'telegram-bot', [{ url: normalized }], now);
+      debug.log('intake.event', 'deferred', { url: normalized, reason: 'event-max' });
+      return { status: 'deferred', url: normalized, reason: 'event-max', reply: INTAKE_EVENT_DEFERRED_REPLY };
+    }
+    let posted: { taskId: string };
+    try {
+      ingestIntakeItems(root, 'telegram-bot', [{ url: normalized }], now);
+      posted = await opts.post({ url: normalized });
+      if (!posted.taskId) throw new Error('intake event post returned no taskId');
+    } catch (error) {
+      db.query('DELETE FROM intake_events WHERE url = ? AND status = ? AND claimed_at = ?').run(normalized, 'pending', now);
+      db.query('DELETE FROM intake_event_claims WHERE url = ? AND claimed_at = ?').run(normalized, now);
+      throw error;
+    }
+    db.query("UPDATE intake_events SET status = 'scheduled', task_id = ? WHERE url = ? AND status = 'pending' AND claimed_at = ?")
+      .run(posted.taskId, normalized, now);
+    debug.log('intake.event', 'scheduled', { url: normalized, reason: 'telegram-absorb' });
+    return { status: 'scheduled', url: normalized, reason: 'telegram-absorb' };
+  } finally {
+    db.close();
+  }
+}
+
+/** Only an active task or a fresh claim excludes a URL from the daily queue. */
+export function wasIntakeEventScheduled(root: string, url: string, now = new Date().toISOString(), taskStatus: IntakeEventTaskProbe = eventTaskStatus): boolean {
+  const file = join(intakeLedgerDir(root), 'events.sqlite');
+  if (!existsSync(file)) return false;
+  const normalized = canonicalUrl(url);
+  if (!normalized) return false;
+  const db = new Database(file);
+  try {
+    const row = db.query('SELECT status, task_id, claimed_at, day FROM intake_events WHERE url = ?').get(normalized) as EventClaim | null;
+    if (!row || (row.status !== 'scheduled' && row.status !== 'pending')) return row?.status === 'completed';
+    if (activeEventClaim(row, now, taskStatus)) {
+      if (row.task_id && probeStatus(taskStatus, row.task_id).status === 'done') {
+        db.query("UPDATE intake_events SET status = 'completed' WHERE url = ?").run(normalized);
+      }
+      return true;
+    }
+    const status = row.task_id ? probeStatus(taskStatus, row.task_id).status : undefined;
+    db.query("UPDATE intake_events SET status = ? WHERE url = ? AND status IN ('pending', 'scheduled')")
+      .run(status === 'failed' || status === 'cancelled' || status === 'superseded' ? 'failed' : 'expired', normalized);
+    return false;
+  } finally {
+    db.close();
+  }
+}
+
 function appendJsonl(file: string, rows: unknown[]): void {
   if (!rows.length) return;
   mkdirSync(join(file, '..'), { recursive: true });

package/src/launch-head/seat-goal-queue-lock.fixture.ts

@@ -0,0 +1,15 @@
+import { writeFileSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+
+const [dbPath, releasedMarker] = process.argv.slice(2);
+if (!dbPath || !releasedMarker) throw new Error('lock fixture requires database path and marker');
+const db = new Database(dbPath);
+try {
+  db.exec('BEGIN IMMEDIATE');
+  console.log('LOCKED');
+  await Bun.sleep(500);
+  writeFileSync(releasedMarker, 'released');
+  db.exec('COMMIT');
+} finally {
+  db.close();
+}

package/src/launch-head/seat-goal-queue.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { Database } from 'bun:sqlite';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { QueueSeat } from '../harness/harness-queue.js';
+
+export type SeatGoalStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'expired';
+export type SeatGoal = {
+  id: string;
+  seat: QueueSeat;
+  goal: string;
+  prerequisites: string[];
+  notBefore?: string;
+  endAt?: string;
+  queuedAt: string;
+  status: SeatGoalStatus;
+  startedAt?: string;
+  finishedAt?: string;
+};
+export type SeatGoalInput = {
+  id?: string;
+  seat: QueueSeat;
+  goal: string;
+  prerequisites?: string[];
+  notBefore?: string;
+  endAt?: string;
+};
+export type SeatGoalQueueOptions = { root?: string; now?: () => Date };
+export type SeatGoalScheduleOptions = SeatGoalQueueOptions & {
+  maxConcurrent: number;
+  seatCaps: Partial<Record<QueueSeat, number>>;
+  launch: (goal: SeatGoal) => Promise<void> | void;
+};
+export type SeatGoalScheduleResult = { outcome: 'started' | 'waiting' | 'empty'; goal?: SeatGoal; reason: string };
+
+const SEATS = new Set(['OP', 'TC', 'MK', 'UX']);
+const TERMINAL = new Set<SeatGoalStatus>(['succeeded', 'failed', 'expired']);
+
+export function seatGoalQueuePath(root = effectiveInstanceRoot()): string {
+  return join(root, 'launch-head', 'seat-goals.sqlite');
+}
+
+function openQueue(root: string): Database {
+  const path = seatGoalQueuePath(root);
+  mkdirSync(join(root, 'launch-head'), { recursive: true, mode: 0o700 });
+  const db = new Database(path, { create: true, strict: true });
+  db.exec('PRAGMA busy_timeout = 30000');
+  db.exec(`CREATE TABLE IF NOT EXISTS seat_goals (
+    id TEXT PRIMARY KEY, seat TEXT NOT NULL, goal TEXT NOT NULL, prerequisites TEXT NOT NULL,
+    not_before TEXT, end_at TEXT, queued_at TEXT NOT NULL, status TEXT NOT NULL,
+    started_at TEXT, finished_at TEXT
+  )`);
+  return db;
+}
+
+type GoalRow = {
+  id: string; seat: QueueSeat; goal: string; prerequisites: string;
+  not_before: string | null; end_at: string | null; queued_at: string;
+  status: SeatGoalStatus; started_at: string | null; finished_at: string | null;
+};
+
+function toGoal(row: GoalRow): SeatGoal {
+  return {
+    id: row.id, seat: row.seat, goal: row.goal, prerequisites: JSON.parse(row.prerequisites) as string[],
+    queuedAt: row.queued_at, status: row.status,
+    ...(row.not_before ? { notBefore: row.not_before } : {}),
+    ...(row.end_at ? { endAt: row.end_at } : {}),
+    ...(row.started_at ? { startedAt: row.started_at } : {}),
+    ...(row.finished_at ? { finishedAt: row.finished_at } : {}),
+  };
+}
+
+function rows(db: Database): SeatGoal[] {
+  return (db.query('SELECT * FROM seat_goals ORDER BY queued_at, rowid').all() as GoalRow[]).map(toGoal);
+}
+
+function instant(value: string, field: string): number {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) throw new Error(`seat goal queue: invalid ${field}`);
+  return time;
+}
+
+function clock(now?: () => Date): Date {
+  const date = now?.() ?? new Date();
+  if (!Number.isFinite(date.getTime())) throw new Error('seat goal queue: invalid clock');
+  return date;
+}
+
+function cap(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`seat goal queue: invalid ${field}`);
+  return value;
+}
+
+/** The launcher owns this store; producers enqueue only, never start a goal. */
+export function enqueueSeatGoal(input: SeatGoalInput, options: SeatGoalQueueOptions = {}): SeatGoal {
+  if (!SEATS.has(input.seat)) throw new Error('seat goal queue: invalid seat');
+  if (!input.goal?.trim()) throw new Error('seat goal queue: empty goal');
+  const id = input.id ?? `sg-${randomUUID()}`;
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(id)) throw new Error('seat goal queue: invalid id');
+  const prerequisites = input.prerequisites ?? [];
+  if (!Array.isArray(prerequisites) || prerequisites.some((key) => typeof key !== 'string' || !key.trim())
+    || new Set(prerequisites).size !== prerequisites.length || prerequisites.includes(id)) {
+    throw new Error('seat goal queue: invalid prerequisites');
+  }
+  const start = input.notBefore === undefined ? undefined : instant(input.notBefore, 'notBefore');
+  const end = input.endAt === undefined ? undefined : instant(input.endAt, 'endAt');
+  if (start !== undefined && end !== undefined && end <= start) throw new Error('seat goal queue: endAt must follow notBefore');
+  const queuedAt = clock(options.now).toISOString();
+  if (end !== undefined && end <= Date.parse(queuedAt)) throw new Error('seat goal queue: endAt has passed');
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  try {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const all = rows(db);
+      if (all.some((row) => row.id === id)) throw new Error(`seat goal queue: duplicate id ${id}`);
+      for (const key of prerequisites) {
+        if (!all.some((row) => row.id === key)) throw new Error(`seat goal queue: missing prerequisite ${key}`);
+      }
+      db.query(`INSERT INTO seat_goals (id, seat, goal, prerequisites, not_before, end_at, queued_at, status)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'queued')`).run(id, input.seat, input.goal, JSON.stringify(prerequisites),
+        input.notBefore ?? null, input.endAt ?? null, queuedAt);
+      db.exec('COMMIT');
+      return { id, seat: input.seat, goal: input.goal, prerequisites: [...prerequisites], queuedAt, status: 'queued',
+        ...(input.notBefore ? { notBefore: input.notBefore } : {}), ...(input.endAt ? { endAt: input.endAt } : {}) };
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  } finally { db.close(); }
+}
+
+export function listSeatGoals(options: SeatGoalQueueOptions = {}): SeatGoal[] {
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  try { return rows(db); } finally { db.close(); }
+}
+
+/** Completion is an explicit launcher receipt: an uncertain or crashed launch keeps its slot reserved. */
+export function finishSeatGoal(id: string, status: 'succeeded' | 'failed', options: SeatGoalQueueOptions = {}): SeatGoal {
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  try {
+    const finishedAt = clock(options.now).toISOString();
+    const result = db.query("UPDATE seat_goals SET status = ?, finished_at = ? WHERE id = ? AND status = 'running'")
+      .run(status, finishedAt, id);
+    if (result.changes !== 1) throw new Error(`seat goal queue: goal is not running: ${id}`);
+    return toGoal(db.query('SELECT * FROM seat_goals WHERE id = ?').get(id) as GoalRow);
+  } finally { db.close(); }
+}
+
+/** One tick claims at most one eligible goal atomically across launcher processes. */
+export async function scheduleSeatGoals(options: SeatGoalScheduleOptions): Promise<SeatGoalScheduleResult> {
+  const totalLimit = cap(options.maxConcurrent, 'maxConcurrent');
+  for (const [seat, value] of Object.entries(options.seatCaps)) {
+    if (!SEATS.has(seat) || value === undefined) throw new Error('seat goal queue: invalid seatCaps');
+    cap(value, `seatCaps.${seat}`);
+  }
+  const db = openQueue(options.root ?? effectiveInstanceRoot());
+  let selected: SeatGoal | undefined;
+  let reason = 'empty';
+  try {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const at = clock(options.now);
+      const all = rows(db);
+      const byId = new Map(all.map((goal) => [goal.id, goal]));
+      for (const goal of all) {
+        if (goal.status !== 'queued') continue;
+        const failed = goal.prerequisites.some((id) => {
+          const prerequisite = byId.get(id);
+          return !prerequisite || (TERMINAL.has(prerequisite.status) && prerequisite.status !== 'succeeded');
+        });
+        if (failed || (goal.endAt && Date.parse(goal.endAt) <= at.getTime())) {
+          db.query("UPDATE seat_goals SET status = 'expired', finished_at = ? WHERE id = ? AND status = 'queued'")
+            .run(at.toISOString(), goal.id);
+          goal.status = 'expired';
+          goal.finishedAt = at.toISOString();
+        }
+      }
+      const running = all.filter((goal) => goal.status === 'running');
+      for (const goal of all) {
+        if (goal.status !== 'queued') continue;
+        if (goal.notBefore && Date.parse(goal.notBefore) > at.getTime()) { reason = 'not-before'; continue; }
+        if (goal.prerequisites.some((id) => byId.get(id)?.status !== 'succeeded')) { reason = 'prerequisites'; continue; }
+        if (running.length >= totalLimit) { reason = 'global-cap'; continue; }
+        if (running.filter((row) => row.seat === goal.seat).length >= (options.seatCaps[goal.seat] ?? totalLimit)) {
+          reason = 'seat-cap'; continue;
+        }
+        const startedAt = at.toISOString();
+        selected = { ...goal, status: 'running', startedAt };
+        db.query("UPDATE seat_goals SET status = 'running', started_at = ? WHERE id = ? AND status = 'queued'")
+          .run(startedAt, goal.id);
+        break;
+      }
+      db.exec('COMMIT');
+      if (!selected) return { outcome: all.some((goal) => goal.status === 'queued') ? 'waiting' : 'empty', reason };
+    } catch (error) { db.exec('ROLLBACK'); throw error; }
+  } finally { db.close(); }
+  // Keep the claim on an uncertain launch. Only a positive completion receipt can release it.
+  await options.launch(selected);
+  return { outcome: 'started', goal: selected, reason: 'launched' };
+}

package/src/loops/budget.ts

@@ -8,6 +8,8 @@ export interface SpawnBudgetInput {
   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 {
@@ -16,13 +18,42 @@ export interface SpawnBudgetDecision {
   cap: number;
 }
 
-/** A release gate can lower, but never raise, the configured per-seat cap. */
-export function decideSpawn({ seat, running, caps, gate }: SpawnBudgetInput): SpawnBudgetDecision {
+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 cap = Number.isSafeInteger(configured) && configured >= 0 && Number.isSafeInteger(gated) && gated >= 0
-    ? Math.min(configured, gated)
-    : 0;
+  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 };
   }

package/src/loops/checker.ts

@@ -14,8 +14,8 @@ export type LoopScope = 'graph-only' | 'registry';
 export interface CheckEntry {
   id: string;
   owner?: string;
-  ownerSource?: 'header' | 'config' | 'seat' | 'default';
-  evidence?: 'log-mtime';
+  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. */