elanous 0.2.12 → 0.2.13

package/src/loops/loop-cli.ts

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

package/src/loops/observe.ts

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

package/src/loops/orchestrator/overlap.ts

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

package/src/loops/orchestrator/traffic.ts

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

package/src/loops/package/verify.ts

@@ -0,0 +1,125 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { debug } from '../../debug/log.js';
+import { loopAgentContractErrors } from '../contract/validate.js';
+
+const contractSchema = JSON.parse(readFileSync(resolve(import.meta.dir, '../contract/loop-agent.schema.json'), 'utf8')) as { $id: string };
+const allowedOverlayFields = new Set(['neighbors', 'cadence', 'grounding', 'budget']);
+type RecordValue = Record<string, unknown>;
+
+function record(value: unknown): value is RecordValue {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function schemaMajor(value: string): number | null {
+  const match = /^(?:https:\/\/elanous\.ai\/schemas\/loop-agent\/)?(\d+)\.\d+\.\d+$/.exec(value);
+  return match ? Number(match[1]) : null;
+}
+
+/** The package version is independent of the declared contract schema version. */
+export function contractMajor(manifest: RecordValue): { ok: boolean; error?: string } {
+  const declared = manifest.schema ?? manifest.$schema ?? contractSchema.$id;
+  const expected = schemaMajor(contractSchema.$id);
+  const actual = typeof declared === 'string' ? schemaMajor(declared) : null;
+  const other = manifest.schema !== undefined && manifest.$schema !== undefined ? manifest.$schema : undefined;
+  if (actual !== null && expected !== null && actual === expected &&
+      (other === undefined || typeof other === 'string' && schemaMajor(other) === expected)) return { ok: true };
+  return { ok: false, error: `contract major mismatch: declared ${String(declared)}${other === undefined ? '' : ` / ${String(other)}`}, expected ${contractSchema.$id}` };
+}
+
+/** Replace only allowlisted top-level fields; refused fields never enter the merged manifest. */
+export function mergeOverlay(manifest: RecordValue, overlay: unknown): { merged: RecordValue; refused: string[] } {
+  const merged = { ...manifest };
+  const refused: string[] = [];
+  if (!record(overlay)) return { merged, refused: ['overlay'] };
+  for (const [field, value] of Object.entries(overlay)) {
+    if (!allowedOverlayFields.has(field)) refused.push(field);
+    else merged[field] = value;
+  }
+  return { merged, refused };
+}
+
+function inside(root: string, path: string): boolean {
+  const part = relative(root, path);
+  return part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part);
+}
+
+function readReference(root: string, name: string, path: unknown, errors: string[]): void {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /^[a-zA-Z]:[\\/]/.test(path) || path.split(/[\\/]/).includes('..')) {
+    errors.push(`${name} path escape: ${String(path)}`);
+    return;
+  }
+  const candidate = resolve(root, path);
+  if (!inside(root, candidate)) {
+    errors.push(`${name} path escape: ${path}`);
+    return;
+  }
+  try {
+    const actual = realpathSync(candidate);
+    if (!inside(root, actual)) errors.push(`${name} path escape: ${path}`);
+    else if (!statSync(actual).isFile()) errors.push(`${name} file missing: ${path}`);
+  } catch {
+    errors.push(`${name} file missing: ${path}`);
+  }
+}
+
+export function readLoopPackage(dir: string): { manifest: RecordValue | null; overlay?: unknown; errors: string[] } {
+  const errors: string[] = [];
+  let manifest: RecordValue | null = null;
+  let overlay: unknown;
+  const root = realpathSync(dir);
+  if (!statSync(root).isDirectory()) throw new Error(`${dir} is not a directory`);
+  const readYaml = (name: string): unknown => {
+    const path = resolve(root, name);
+    const actual = realpathSync(path);
+    if (!inside(root, actual) || !statSync(actual).isFile()) throw new Error(`${name} path escape or not a file`);
+    return parseYaml(readFileSync(actual, 'utf8'));
+  };
+  try {
+    const parsed = readYaml('loop.yaml');
+    if (!record(parsed)) errors.push('loop.yaml must contain a manifest object');
+    else manifest = parsed;
+  } catch (error) { errors.push(`loop.yaml: ${error instanceof Error ? error.message : String(error)}`); }
+  try { overlay = readYaml('overlay.yaml'); }
+  catch (error) {
+    if (!(record(error) && error.code === 'ENOENT')) errors.push(`overlay.yaml: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (manifest) {
+    readReference(root, 'graph', manifest.graph, errors);
+    readReference(root, 'role', manifest.role, errors);
+  }
+  return { manifest, overlay, errors };
+}
+
+export function verifyLoopPackage(dir: string): {
+  ok: boolean; errors: string[]; refusedOverlayFields: string[]; merged: RecordValue | null;
+} {
+  let manifest: RecordValue | null = null;
+  let overlay: unknown;
+  const errors: string[] = [];
+  try {
+    const read = readLoopPackage(dir);
+    manifest = read.manifest;
+    overlay = read.overlay;
+    errors.push(...read.errors);
+  } catch (error) { errors.push(`package directory: ${error instanceof Error ? error.message : String(error)}`); }
+  let merged: RecordValue | null = null;
+  let refusedOverlayFields: string[] = [];
+  if (manifest) {
+    const major = contractMajor(manifest);
+    if (major.error) errors.push(major.error);
+    const result = overlay === undefined ? { merged: { ...manifest }, refused: [] } : mergeOverlay(manifest, overlay);
+    refusedOverlayFields = result.refused;
+    merged = result.merged;
+    if (refusedOverlayFields.length) errors.push(`overlay refused: ${refusedOverlayFields.join(', ')}`);
+    // Schema declaration is package metadata, not a field in the loop-agent contract.
+    const { schema: _schema, $schema: _dollarSchema, ...contractInput } = merged;
+    errors.push(...loopAgentContractErrors(contractInput));
+  }
+  const ok = errors.length === 0;
+  debug.log('loop.package', ok ? 'verified' : 'refused', {
+    id: manifest?.id, version: manifest?.version, errors: errors.length, refusedOverlayFields,
+  });
+  return { ok, errors, refusedOverlayFields, merged };
+}

package/src/loops/verdict.ts

@@ -0,0 +1,22 @@
+export type LoopCronVerdict = 'alive' | 'late' | 'failed' | 'off';
+
+/** Shared display inputs for a graph loop or a cron job. The caller supplies
+ * the cadence in milliseconds (or null when it is not known). */
+export interface LoopCronVerdictInput {
+  enabled: boolean;
+  lastRunAt: string | null;
+  lastStatus: string | null;
+  intervalMs: number | null;
+}
+
+/** Pure health classification; a failed last execution takes precedence over age.
+ * With no valid timestamp or positive cadence, lateness cannot be established. */
+export function loopCronVerdict(entry: LoopCronVerdictInput, nowMs: number): LoopCronVerdict {
+  if (!entry.enabled) return 'off';
+  if (entry.lastStatus === 'failed' || entry.lastStatus === 'error' || entry.lastStatus === 'failure') return 'failed';
+  const lastRunMs = entry.lastRunAt === null ? NaN : Date.parse(entry.lastRunAt);
+  if (Number.isFinite(nowMs) && Number.isFinite(lastRunMs) &&
+      entry.intervalMs !== null && Number.isFinite(entry.intervalMs) && entry.intervalMs > 0 &&
+      nowMs - lastRunMs > 2 * entry.intervalMs) return 'late';
+  return 'alive';
+}

package/src/maturity/feature-maturity.ts

@@ -57,11 +57,11 @@ export const FEATURE_MATURITY = {
     pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta',
     where: 'stable', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', seat: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
     control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
     grounding: 'beta', graph: 'beta', loop: 'stable', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',
-    persona: 'beta', 'team-set': 'beta', market: 'beta', directive: 'stable', connector: 'beta', storyboard: 'beta',
+    persona: 'beta', team: 'beta', 'team-set': 'beta', market: 'beta', directive: 'stable', connector: 'beta', storyboard: 'beta',
     python: 'beta', 'self-update': 'stable', 'measure-fabric-arc-ab': 'beta', mcp: 'beta',
     relay: 'beta', 'telegram-test': 'beta', telegram: 'beta', 'discord-test': 'beta',
     sync: 'beta', status: 'beta', git: 'beta', gh: 'beta', repro: 'system',
@@ -71,7 +71,7 @@ export const FEATURE_MATURITY = {
     provider: 'stable', 'provider:set': 'beta', 'provider:restore': 'beta',
     'provider:rotate': 'beta', 'provider:use': 'beta', 'status-bar': 'beta',
     schedule: 'beta', intake: 'beta', logs: 'stable', ad: 'beta', docs: 'beta',
-    decisions: 'beta', directives: 'beta', fleet: 'beta', ops: 'stable', publish: 'beta',
+    decisions: 'beta', directives: 'beta', fleet: 'beta', ops: 'stable', outputs: 'beta', publish: 'beta',
     env: 'beta', 'agent-mission': 'beta', dev: 'beta', keys: 'beta', finance: 'beta',
     config: 'stable', tasks: 'stable', labels: 'beta', msg: 'beta', ask: 'stable',
     onboarding: 'beta', login: 'stable', session: 'beta', chat: 'stable', repl: 'stable',