elanous 0.2.25 → 0.2.28

package/src/loops/orchestrator/resync-shadow.ts

@@ -5,6 +5,9 @@ import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { debug } from '../../debug/log.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { PR_LABEL_NAMES } from '../../github/pr-labels.js';
+import { listRunLedgers } from '../../self-implement/run-ledger.js';
+import { queryRunningRuns } from '../../self-implement/running-runs.js';
 import {
   defaultGitMergeSeam, defaultLlmResolve, mergeMainWithLlmResolve,
   type LlmMergeOutcome, type MergeGitSeam,
@@ -16,6 +19,8 @@ interface ResyncShadowEntry {
   at: string;
   pr: number;
   head: string;
+  beforeHead?: string;
+  afterHead?: string;
   mode: ResyncShadowMode;
   pushed: boolean;
   labelRemoved: boolean;
@@ -27,7 +32,7 @@ interface ResyncShadowEntry {
 }
 export interface ResyncShadowSummary { candidates: number; tried: number; saved: number; savedRatio: number | null }
 
-type OpenPr = { number: number; headRefName: string; mergeable: string; isDraft: boolean; labels: { name: string }[] };
+type OpenPr = { number: number; headRefName: string; headRefOid?: string; mergeable: string; isDraft: boolean; labels: { name: string }[] };
 export interface ResyncShadowDeps {
   repoRoot?: string;
   instanceRoot?: string;
@@ -37,6 +42,63 @@ export interface ResyncShadowDeps {
   gitSeam?: MergeGitSeam;
   runTests?: (cwd: string, files: string[]) => { ok: boolean; failedTests?: string[]; noTests?: boolean };
   now?: () => Date;
+  /** Run ownership is checked before touching a branch; null means the observation failed. */
+  activePrNumbers?: (candidatePrs: readonly number[]) => ReadonlySet<number> | null;
+}
+
+function activePrNumbers(candidatePrs: readonly OpenPr[], repoRoot: string, instanceRoot: string): ReadonlySet<number> | null {
+  const owners = new Map<number, { runId: string; branch: string; headCommit: string; terminal: boolean }[]>();
+  const branchRuns = new Map<string, Set<string>>();
+  const incompleteOwnerPrs = new Set<number>();
+  const candidateSet = new Set(candidatePrs.map(pr => pr.number));
+  try {
+    for (const match of listRunLedgers().matches) {
+      const latestStatus = match.entries.filter(entry => entry.event === 'run-status').at(-1)?.data.runStatus;
+      const terminal = latestStatus === 'completed' || latestStatus === 'failed' || latestStatus === 'cancelled';
+      for (const entry of match.entries) {
+        // A competing run can own the branch even when its PR number or worktree event is missing.
+        if ((entry.event === 'worktree' || entry.event === 'pr-opened') && typeof entry.data.branch === 'string') {
+          const ids = branchRuns.get(entry.data.branch) ?? new Set<string>();
+          ids.add(match.runId);
+          branchRuns.set(entry.data.branch, ids);
+        }
+        const number = entry.event === 'pr-opened' ? entry.data.number : undefined;
+        if (typeof number !== 'number' || !candidateSet.has(number)) continue;
+        const matches = owners.get(number) ?? [];
+        if (typeof entry.data.branch !== 'string' || typeof entry.data.headCommit !== 'string')
+          incompleteOwnerPrs.add(number);
+        else matches.push({ runId: match.runId, branch: entry.data.branch, headCommit: entry.data.headCommit, terminal });
+        owners.set(number, matches);
+      }
+    }
+    const runIds = [...new Set([...owners.values()].flatMap(rows => rows.map(row => row.runId)))];
+    if (runIds.length === 0) return new Set(candidatePrs.map(pr => pr.number));
+    const observed = queryRunningRuns({ runIds, caller: 'smart-merge.resync' });
+    if (observed.completeness !== 'complete') return null;
+    const active = new Set(observed.entries.filter(row => row.status === 'running' || row.status === 'probable-running'
+      || row.status === 'unknown' || row.status === 'ended-unclosed').map(row => row.runId));
+    const priorPath = join(instanceRoot, 'orchestrator', 'resync-shadow.jsonl');
+    const prior = existsSync(priorPath) ? readFileSync(priorPath, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line) as ResyncShadowEntry) : [];
+    const excluded = new Set<number>();
+    for (const pr of candidatePrs) {
+      const matches = owners.get(pr.number) ?? [];
+      if (incompleteOwnerPrs.has(pr.number) || matches.length !== 1 || !/^[a-f0-9]{40}$/i.test(pr.headRefOid ?? '')) { excluded.add(pr.number); continue; }
+      const owner = matches[0]!;
+      if (owner.branch !== pr.headRefName || !owner.terminal || !/^[a-f0-9]{40}$/i.test(owner.headCommit)
+        || active.has(owner.runId) || [...(branchRuns.get(pr.headRefName) ?? [])].some(id => id !== owner.runId)) {
+        excluded.add(pr.number); continue;
+      }
+      const remote = command('git', ['ls-remote', 'origin', `refs/heads/${pr.headRefName}`], repoRoot).trim().split(/\s/)[0];
+      if (remote !== pr.headRefOid) { excluded.add(pr.number); continue; }
+      let proven = owner.headCommit;
+      for (const row of prior.filter(row => row.pr === pr.number && row.head === pr.headRefName && row.pushed)) {
+        if (row.beforeHead !== proven || !/^[a-f0-9]{40}$/i.test(row.afterHead ?? '')) { proven = ''; break; }
+        proven = row.afterHead!;
+      }
+      if (proven !== remote) excluded.add(pr.number);
+    }
+    return excluded;
+  } catch { return null; }
 }
 
 function command(file: string, args: string[], cwd: string, timeout = 60_000): string {
@@ -51,6 +113,15 @@ function changedTests(gh: (args: string[]) => string, number: number): string[]
     path.endsWith('.test.ts') && !isAbsolute(path) && path !== '' && !path.split('/').some(part => part === '..' || part === '.' || part === '')))];
 }
 
+function listOpenPrs(gh: (args: string[]) => string): OpenPr[] {
+  const observed: unknown = JSON.parse(gh(['pr', 'list', '--state', 'open', '--json', 'number,headRefName,headRefOid,mergeable,isDraft,labels', '--limit', '1000']));
+  if (!Array.isArray(observed) || observed.length >= 1000 || observed.some(pr => !pr || !Number.isSafeInteger(pr.number)
+    || typeof pr.headRefName !== 'string' || typeof pr.mergeable !== 'string' || typeof pr.isDraft !== 'boolean'
+    || !Array.isArray(pr.labels) || pr.labels.some((label: unknown) => !label || typeof label !== 'object' || typeof (label as { name?: unknown }).name !== 'string')))
+    throw new Error('incomplete or invalid PR observation');
+  return observed as OpenPr[];
+}
+
 // A PR test must not inherit credentials, reach the network or write outside its own worktree.
 // If the kernel does not provide the required isolation, fail closed before starting bun.
 const TEST_SANDBOX = `import ctypes, os, sys
@@ -145,16 +216,16 @@ export async function runResyncShadow(max = 3, deps: ResyncShadowDeps = {}, mode
   if (mode !== 'shadow' && mode !== 'live') throw new Error('mode must be shadow or live');
   const repoRoot = deps.repoRoot ?? resolve(import.meta.dir, '../../..');
   const gh = deps.runGh ?? ((args: string[]) => command('gh', args, repoRoot));
-  const observed: unknown = JSON.parse(gh(['pr', 'list', '--state', 'open', '--json', 'number,headRefName,mergeable,isDraft,labels', '--limit', '1000']));
-  if (!Array.isArray(observed) || observed.length >= 1000 || observed.some(pr => !pr || !Number.isSafeInteger(pr.number)
-    || typeof pr.headRefName !== 'string' || typeof pr.mergeable !== 'string' || typeof pr.isDraft !== 'boolean'
-    || !Array.isArray(pr.labels) || pr.labels.some((label: unknown) => !label || typeof label !== 'object' || typeof (label as { name?: unknown }).name !== 'string')))
-    throw new Error('incomplete or invalid PR observation');
-  const candidates = (observed as OpenPr[]).filter(pr => pr.headRefName.startsWith('self-impl/')
-    && pr.mergeable === 'CONFLICTING'
-    && (mode === 'shadow' || pr.labels.some(label => label.name === 'elanous:needs-rebase'))
-    && !pr.labels.some(label => label.name === 'elanous:stalled' || label.name === 'elanous:superseded'))
-    .sort((a, b) => a.number - b.number).slice(0, max);
+  const eligible = listOpenPrs(gh).filter(pr => pr.headRefName.startsWith('self-impl/')
+    && (mode === 'shadow' ? pr.mergeable === 'CONFLICTING' : pr.mergeable === 'MERGEABLE')
+    && (mode === 'shadow' || pr.labels.some(label => label.name === PR_LABEL_NAMES.needsRebase))
+    && !pr.labels.some(label => label.name === PR_LABEL_NAMES.running)
+    && !pr.labels.some(label => label.name === PR_LABEL_NAMES.stalled || label.name === PR_LABEL_NAMES.superseded));
+  const observeActive = deps.activePrNumbers ?? ((numbers: readonly number[]) => activePrNumbers(
+    eligible.filter(pr => numbers.includes(pr.number)), repoRoot, deps.instanceRoot ?? effectiveInstanceRoot()));
+  const active = mode === 'live' && eligible.length ? observeActive(eligible.map(pr => pr.number)) : new Set<number>();
+  if (active === null) throw new Error('active run observation unavailable — resync stays read-only');
+  const candidates = eligible.filter(pr => !active.has(pr.number)).sort((a, b) => a.number - b.number).slice(0, max);
   const ledger = join(deps.instanceRoot ?? effectiveInstanceRoot(), 'orchestrator', 'resync-shadow.jsonl');
   let saved = 0;
   let tried = 0;
@@ -169,6 +240,9 @@ export async function runResyncShadow(max = 3, deps: ResyncShadowDeps = {}, mode
       // Explicit destination refspecs make origin/<head> and origin/main fresh even without remote.origin.fetch.
       command('git', ['fetch', 'origin', `+refs/heads/${pr.headRefName}:refs/remotes/origin/${pr.headRefName}`,
         '+refs/heads/main:refs/remotes/origin/main'], repoRoot);
+      entry.beforeHead = command('git', ['rev-parse', `origin/${pr.headRefName}`], repoRoot).trim();
+      if (mode === 'live' && !deps.activePrNumbers && entry.beforeHead !== pr.headRefOid)
+        throw new Error('PR head changed after owner proof — resync stays read-only');
       entry.testFiles = changedTests(gh, pr.number);
       tmp = realpathSync(mkdtempSync(join(tmpdir(), 'resync-shadow-')));
       command('git', ['worktree', 'add', '--detach', tmp, `origin/${pr.headRefName}`], repoRoot);
@@ -189,10 +263,24 @@ export async function runResyncShadow(max = 3, deps: ResyncShadowDeps = {}, mode
       } else entry.verdict = outcome.status === 'conflict-unresolved' || outcome.status === 'up-to-date' ? 'unresolved' : 'error';
       if (mode === 'live' && entry.verdict === 'saved') {
         try {
+          const lateActive = observeActive([pr.number]);
+          if (lateActive === null || lateActive.has(pr.number))
+            throw new Error('PR ownership changed before push — resync stays read-only');
+          const current = listOpenPrs(gh).filter(row => row.number === pr.number);
+          if (current.length !== 1 || current[0]!.headRefName !== pr.headRefName
+            || current[0]!.headRefOid !== pr.headRefOid || current[0]!.mergeable !== 'MERGEABLE'
+            || !current[0]!.labels.some(label => label.name === PR_LABEL_NAMES.needsRebase)
+            || current[0]!.labels.some(label => label.name === PR_LABEL_NAMES.running
+              || label.name === PR_LABEL_NAMES.stalled || label.name === PR_LABEL_NAMES.superseded))
+            throw new Error('PR state changed before push — resync stays read-only');
+          const immediateHead = command('git', ['ls-remote', 'origin', `refs/heads/${pr.headRefName}`], repoRoot).trim().split(/\s/)[0];
+          if (immediateHead !== entry.beforeHead)
+            throw new Error('remote head changed before push — resync stays read-only');
           (deps.runGit ?? (args => { command('git', args, tmp!); }))(
             ['push', 'origin', `HEAD:refs/heads/${pr.headRefName}`]);
           entry.pushed = true;
-          gh(['pr', 'edit', String(pr.number), '--remove-label', 'elanous:needs-rebase']);
+          entry.afterHead = command('git', ['rev-parse', 'HEAD'], tmp).trim();
+          gh(['pr', 'edit', String(pr.number), '--remove-label', PR_LABEL_NAMES.needsRebase]);
           entry.labelRemoved = true;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);

package/src/loops/orchestrator/tick.ts

@@ -1,5 +1,5 @@
 import { withFileLockSync } from '../../storage/file-lock.js';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { CardStore, taskCardsDir, type TaskCard } from '../../task-cards/card-store.js';
 import { Database } from 'bun:sqlite';
@@ -16,6 +16,7 @@ import { placeOnGrid, type GridHost } from './grid-place.js';
 import { checkPodPool, parsePodPool, resolvePodPoolSpec } from '../../task-orchestrator/surfaces/pod-pool.js';
 import { leaseKubectl } from '../../task-orchestrator/surfaces/pod-lease.js';
 import { readTaskAgentState, TASK_SEATS, type HandTaskOptions, type TaskCard as TaskAgentCard, type HandTaskResult, type TaskLauncher, type TaskSeat } from '../../task-agent/task-hand.js';
+import { runCoordinatorInbox } from './inbox.js';
 
 export type Window = '08' | '12' | '18';
 export type Node = 'intake' | 'split' | 'place' | 'delegate' | 'launch' | 'reconcile' | 'report';
@@ -31,6 +32,10 @@ export interface TickState {
   /** The highest degradation actually applied in this run — the report keeps it even if the signal recovers before report. */
   degradationPeak?: { level: 1 | 2; reason: string };
   deferredCells?: Cell[];
+  /** A placement adapter rejected at least one cell; this run cannot claim full completion. */
+  placementFailed?: boolean;
+  /** Last confirmed live placement write in this run, carried across node processes. */
+  boardWrittenAt?: string;
   /** place ran at L2 (skipped) in this run — its unplaced cells are carried even if the board is back by delegate. */
   placeDegraded?: boolean;
   delegatedKeys?: string[];
@@ -67,6 +72,8 @@ export interface TickDeps {
   handToTaskAgentCell?: string;
   handTask?: (opts: HandTaskOptions) => Promise<HandTaskResult>;
   taskLauncher?: TaskLauncher;
+  /** Coordinator inbox seam; the real intake reads and replies on the durable message bus. */
+  coordinatorInbox?: () => { replied: number; acknowledged: number };
 }
 
 /** ORCH-TA-HAND ledger — one row per handed `orch:<card>:<cell>` key so a cell is handed once across ticks and processes. */
@@ -329,6 +336,41 @@ function stateFile(root: string, runId: string): string {
   if (!/^[a-zA-Z0-9._-]+$/.test(runId) || runId === '.' || runId === '..') throw new Error('Invalid orchestrator runId');
   return join(root, 'loop', 'orchestrator', `${runId}.json`);
 }
+/** COORD-HA ③ 진행 하트비트 — the last tick that finished its work and the last confirmed placement write. The guardian watches this
+ * (RFC-loop-agent-map §A8b: «마지막 틱 완료 ⊕ 보드 마지막 쓰기 시각»), not process liveness — a held node keeps pulsing
+ * healthy while this record goes stale, which is exactly the stall it exists to expose. */
+export interface CompletionHeartbeat {
+  runId: string;
+  node: Node;
+  window: Window;
+  mode: Mode;
+  /** last confirmed live placement write; null before the first such write */
+  boardWrittenAt: string | null;
+  /** last fully completed run, or null while only board writes have succeeded */
+  tickCompletedAt: string | null;
+}
+/** Its own subdirectory, so the run-state scanners (`restorePrevious` · `previousDelegations` · `syncQueuedPoolHints`) never parse it as a TickState. */
+function completionHeartbeatPath(root: string): string { return join(root, 'loop', 'orchestrator', 'heartbeat', 'completion.json'); }
+/** COORD-HA ③ — last completed run and board write, independently. Undefined means neither has been recorded. */
+export function readCompletionHeartbeat(root: string): CompletionHeartbeat | undefined {
+  const path = completionHeartbeatPath(root);
+  if (!existsSync(path)) return undefined;
+  try {
+    const { runId, node, window, mode, boardWrittenAt, tickCompletedAt } = JSON.parse(readFileSync(path, 'utf8')) as Partial<CompletionHeartbeat>;
+    if (typeof runId !== 'string' || typeof node !== 'string' || typeof window !== 'string' || typeof mode !== 'string'
+      || (boardWrittenAt !== null && (typeof boardWrittenAt !== 'string' || !Number.isFinite(Date.parse(boardWrittenAt))))
+      || (tickCompletedAt !== null && (typeof tickCompletedAt !== 'string' || !Number.isFinite(Date.parse(tickCompletedAt))))) return undefined;
+    return { runId, node: node as Node, window: window as Window, mode: mode as Mode, boardWrittenAt, tickCompletedAt };
+  } catch { return undefined; }
+}
+/** Temp + rename, so a guardian in another process never reads a torn record. */
+function recordCompletionHeartbeat(root: string, completion: CompletionHeartbeat): void {
+  const path = completionHeartbeatPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(completion));
+  renameSync(temp, path);
+}
 function restorePrevious(root: string, day: string, mode: Mode): Pick<TickState, 'cards' | 'cells' | 'launched'> | null {
   const dir = join(root, 'loop', 'orchestrator');
   if (!existsSync(dir)) return null;
@@ -430,6 +472,15 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
     try { (deps.observe ?? ((name, payload) => debug.log('loop.orchestrator', name, payload)))(event, data); }
     catch { /* observation must not change the run */ }
   };
+  // A graph node may be replayed with the same runId, and 12/18 skip intake.
+  // Drain the bus on every tick command; the message transaction prevents duplicate answers.
+  if (mode !== 'off') {
+    const inbox = (deps.coordinatorInbox ?? (() => runCoordinatorInbox(undefined, 100, join(root, 'msg', 'messages.db'))))();
+    if (inbox.replied || inbox.acknowledged) {
+      observe('exchange', 'coordinator-inbox-replied', inbox.replied);
+      observe('exchange', 'coordinator-inbox-acknowledged', inbox.acknowledged);
+    }
+  }
   if (mode !== 'off' && activeNode(node, window) && state.nodes[node] !== 'ok') {
     if (node === 'intake') {
       if (mode === 'live' && deps.cards) { state.cards = wishCards(deps.cards()); state.skippedCards = []; }
@@ -495,11 +546,19 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
             if (validVersion(placed?.version)) {
               cell.version = placed.version;
               state.placed++;
+              // The live placer has returned from its board write. A shadow dry run or null result is not a write.
+              if (mode === 'live') state.boardWrittenAt = currentTime().toISOString();
               observe('exchange', mode === 'shadow' ? `would-place:${cell.id}:${cell.version}` : `placed:${cell.id}:${cell.version}`, 1);
-            } else { state.unplaced = (state.unplaced ?? 0) + 1; observe('exchange', 'unplaced-no-release', 1); }
+            } else {
+              state.unplaced = (state.unplaced ?? 0) + 1;
+              if (mode === 'live') state.placementFailed = true;
+              observe('exchange', 'unplaced-no-release', 1);
+            }
           } catch (error) {
             state.unplaced = (state.unplaced ?? 0) + 1;
+            state.placementFailed = true;
             observe('exchange', `unplaced:${cell.id}:${String(error).slice(0, 160)}`, 1);
+            // Preserve the cell-by-cell recovery contract; the run completion record is withheld at report.
           }
         }
       }
@@ -762,8 +821,20 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
     state.nodes[node] = 'skipped';
   }
   observe('tick', state.nodes[node], state.cells.length);
+  if (mode === 'live' && node === 'place' && state.boardWrittenAt) {
+    // A board write can succeed even when a later cell fails. Advance its clock without claiming run completion.
+    const previous = readCompletionHeartbeat(root);
+    recordCompletionHeartbeat(root, previous
+      ? { ...previous, boardWrittenAt: state.boardWrittenAt }
+      : { runId, node, window, mode, boardWrittenAt: state.boardWrittenAt, tickCompletedAt: null });
+  }
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, JSON.stringify(state));
+  if (mode !== 'off' && node === 'report' && !state.placementFailed && !state.placeDegraded) {
+    // Only the last node can attest that the whole run completed. Carry the most recent confirmed board write.
+    const boardWrittenAt = state.boardWrittenAt ?? readCompletionHeartbeat(root)?.boardWrittenAt ?? null;
+    recordCompletionHeartbeat(root, { runId, node, window, mode, boardWrittenAt, tickCompletedAt: currentTime().toISOString() });
+  }
   return state;
   } catch (error) {
     nodeError = error;

package/src/machines/machine-ledger.ts

@@ -10,6 +10,16 @@ export interface MachineRow {
   locationStatus: string;
   role: string;
   duties: string;
+  /** Fleet intent only. Live membership comes from Nexus machine resources. */
+  fleet?: MachineFleetIntent;
+}
+
+export interface MachineFleetIntent {
+  sshName: string;
+  role: 'worker' | 'hq';
+  platform: 'darwin' | 'linux' | 'wsl';
+  podPool: string;
+  cap: number;
 }
 
 export interface DeviceRow {
@@ -59,18 +69,36 @@ export function validateMachineLedger(value: unknown): MachineLedger {
   keys(data, ['title', 'policy', 'machines', 'devices', 'rules', 'changes'], 'ledger');
   if (!Array.isArray(data.machines) || !Array.isArray(data.devices)) throw new Error('invalid machines or devices');
   const ids = new Set<string>();
-  const rows = <T extends { id: string }>(entries: unknown[], fields: string[], label: string): T[] => entries.map((entry, index) => {
+  const rows = <T extends { id: string }>(entries: unknown[], fields: string[], label: string, extraFields: string[] = []): T[] => entries.map((entry, index) => {
     const row = record(entry, `${label}[${index}]`);
-    keys(row, fields, label);
+    keys(row, [...fields, ...extraFields], label);
     const result = Object.fromEntries(fields.map((field) => [field, text(row[field], `${label}.${field}`)])) as T;
     if (!idPattern.test(result.id) || ids.has(result.id)) throw new Error(`empty, duplicate or invalid id: ${result.id}`);
     ids.add(result.id);
     return result;
   });
+  const machines = rows<MachineRow>(data.machines, ['id', 'name', 'specs', 'locationStatus', 'role', 'duties'], 'machines', ['fleet']);
+  const sshNames = new Set<string>();
+  for (let index = 0; index < machines.length; index++) {
+    const raw = record(data.machines[index], `machines[${index}]`);
+    if (raw.fleet === undefined) continue;
+    const fleet = record(raw.fleet, `machines[${index}].fleet`);
+    keys(fleet, ['sshName', 'role', 'platform', 'podPool', 'cap'], 'fleet');
+    const sshName = text(fleet.sshName, 'fleet.sshName');
+    const role = text(fleet.role, 'fleet.role');
+    const platform = text(fleet.platform, 'fleet.platform');
+    const podPool = text(fleet.podPool, 'fleet.podPool');
+    if (!idPattern.test(sshName) || sshNames.has(sshName)) throw new Error(`duplicate or invalid fleet.sshName: ${sshName}`);
+    if (role !== 'worker' && role !== 'hq') throw new Error(`invalid fleet.role: ${role}`);
+    if (platform !== 'darwin' && platform !== 'linux' && platform !== 'wsl') throw new Error(`invalid fleet.platform: ${platform}`);
+    if (!Number.isSafeInteger(fleet.cap) || (fleet.cap as number) < 0) throw new Error('invalid fleet.cap');
+    sshNames.add(sshName);
+    machines[index]!.fleet = { sshName, role, platform, podPool, cap: fleet.cap as number };
+  }
   return {
     title: text(data.title, 'title'),
     policy: list(data.policy, 'policy'),
-    machines: rows<MachineRow>(data.machines, ['id', 'name', 'specs', 'locationStatus', 'role', 'duties'], 'machines'),
+    machines,
     devices: rows<DeviceRow>(data.devices, ['id', 'name', 'status', 'purpose'], 'devices'),
     rules: list(data.rules, 'rules'),
     changes: list(data.changes, 'changes'),

package/src/maturity/cli-maturity.ts

@@ -18,14 +18,24 @@ export function cliRootVisibleFor(name: string, role: Role, { showAll }: { showA
   return grade === 'stable' || (role === 'contributor' && (grade === 'beta' || grade === 'tool'));
 }
 
-/** Only help is filtered: Commander still dispatches explicitly typed commands. */
-export function filterCliRootHelp(commands: readonly Command[], role: Role, showAll: boolean): { shown: number; hidden: number } {
+/** Root --help first screen (SETUP-HELP-SLIM): the three stable onboarding commands. */
+export const FIRST_SCREEN_COMMANDS: readonly string[] = ['start', 'setup', 'ask'];
+
+/**
+ * Only help is filtered: Commander still dispatches explicitly typed commands.
+ * firstScreen narrows the visible set to FIRST_SCREEN_COMMANDS and showAll wins over it;
+ * the caller opts in per role — the wired default (deferred slice) enables it for the
+ * general role only, so owner/contributor keep today's list.
+ */
+export function filterCliRootHelp(commands: readonly Command[], role: Role, showAll: boolean, firstScreen: boolean = false): { shown: number; hidden: number } {
+  const firstScreenActive = firstScreen && !showAll;
   let shown = 0;
   let hidden = 0;
   for (const command of commands) {
     const grade = cliRootMaturity(command.name(), commands);
     if (!grade) throw new Error(`cliRoot 에 등급 없는 명령: ${command.name()}`);
-    const visible = cliRootVisibleFor(command.name(), role, { showAll }, commands);
+    const visible = cliRootVisibleFor(command.name(), role, { showAll }, commands)
+      && (!firstScreenActive || FIRST_SCREEN_COMMANDS.includes(command.name()));
     (command as Command & { _hidden: boolean })._hidden = !visible;
     if (visible) shown++;
     else hidden++;

package/src/maturity/feature-maturity.ts

@@ -62,7 +62,7 @@ export const FEATURE_MATURITY = {
     preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta',
     where: 'stable', bench: 'beta', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', know: 'beta', freeze: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', freeze: 'beta', flow: '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', resource: 'beta', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',

package/src/msg/msg-sse-server.ts

@@ -0,0 +1,141 @@
+import { timingSafeEqual } from 'node:crypto';
+import { canonicalSeatId, type Message, type MsgStore } from './msg-store.js';
+
+type Subscriber = { to: string; lastId: number; heartbeatAt: number; replaying: boolean; controller: ReadableStreamDefaultController<Uint8Array> };
+const encoder = new TextEncoder();
+
+function cursor(raw: string | null): number {
+  if (raw === null) return 0;
+  if (!/^(0|[1-9]\d*)$/.test(raw)) throw new Error('invalid message cursor');
+  const id = Number(raw);
+  if (!Number.isSafeInteger(id)) throw new Error('invalid message cursor');
+  return id;
+}
+
+function authorized(request: Request, token: string): boolean {
+  const value = request.headers.get('authorization');
+  if (!value?.startsWith('Bearer ')) return false;
+  const received = Buffer.from(value.slice(7));
+  const expected = Buffer.from(token);
+  return expected.length > 0 && received.length === expected.length && timingSafeEqual(received, expected);
+}
+
+function addressed(message: Message, to: string): boolean {
+  return message.to === to || (message.to === 'ALL' && message.from !== to);
+}
+
+/** The SQLite ledger remains authoritative; this independent process only accelerates delivery. */
+export function startMsgSseServer(input: {
+  store: MsgStore;
+  token: string;
+  port: number;
+  hostname?: string;
+  pollMs?: number;
+}): { port: number; stats: () => { subscribers: number; maxQueuedEvents: number }; stop: () => void } {
+  if (!input.token) throw new Error('message SSE token is required');
+  if (!Number.isSafeInteger(input.port) || input.port < 0 || input.port > 65535) throw new Error('invalid SSE port');
+  const hostname = input.hostname ?? '127.0.0.1';
+  if (!['127.0.0.1', 'localhost', '::1', '[::1]'].includes(hostname)) throw new Error('message SSE must bind to loopback');
+  const pollMs = input.pollMs ?? 250;
+  if (!Number.isSafeInteger(pollMs) || pollMs < 1 || pollMs > 500) throw new Error('SSE ledger poll must be 1–500ms');
+  const subscribers = new Set<Subscriber>();
+  let maxQueuedEvents = 0;
+  let scanned = input.store.latestId();
+  const send = (subscriber: Subscriber, message: Message) => {
+    if (message.id <= subscriber.lastId || !addressed(message, subscriber.to)) return;
+    if ((subscriber.controller.desiredSize ?? 0) < -256) throw new Error('slow SSE subscriber; reconnect for ledger replay');
+    subscriber.controller.enqueue(encoder.encode(`id: ${message.id}\ndata: ${JSON.stringify(message)}\n\n`));
+    maxQueuedEvents = Math.max(maxQueuedEvents, Math.max(0, 1 - (subscriber.controller.desiredSize ?? 0)));
+    subscriber.lastId = message.id;
+  };
+  const replay = (subscriber: Subscriber) => {
+    if (!subscriber.replaying) return;
+    try {
+      while ((subscriber.controller.desiredSize ?? 0) > 0) {
+        const batch = input.store.listByRecipient(subscriber.to, subscriber.lastId, 1000);
+        if (!batch.length) { subscriber.replaying = false; break; }
+        for (const message of batch) {
+          if ((subscriber.controller.desiredSize ?? 0) <= 0) break;
+          send(subscriber, message);
+        }
+      }
+    } catch (error) {
+      subscribers.delete(subscriber);
+      subscriber.controller.error(error);
+    }
+  };
+  const tick = () => {
+    try {
+      let batch: Message[];
+      let scans = 0;
+      do {
+        batch = input.store.listAfter(scanned);
+        for (const message of batch) {
+          scanned = message.id;
+          for (const subscriber of subscribers) {
+            if (subscriber.replaying) continue;
+            try { send(subscriber, message); } catch (error) {
+              subscribers.delete(subscriber);
+              try { subscriber.controller.error(error); } catch { /* already disconnected */ }
+            }
+          }
+        }
+        scans++;
+      } while (batch.length === 1000 && scans < 4);
+      const now = Date.now();
+      for (const subscriber of subscribers) {
+        if (subscriber.replaying || (subscriber.controller.desiredSize ?? 0) <= 0) continue;
+        if (now - subscriber.heartbeatAt < 1000) continue;
+        try {
+          subscriber.controller.enqueue(encoder.encode(': keepalive\n\n'));
+          subscriber.heartbeatAt = now;
+        } catch { subscribers.delete(subscriber); }
+      }
+    } catch (error) {
+      // The next tick retries from the last scanned ID; the durable ledger is unchanged.
+      console.error(`msg SSE scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  const server = Bun.serve({
+    port: input.port,
+    hostname,
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname !== '/stream' || request.method !== 'GET') return new Response('Not Found', { status: 404 });
+      if (!authorized(request, input.token)) return new Response('Unauthorized', { status: 401 });
+      let to: string;
+      let after: number;
+      try {
+        to = canonicalSeatId(url.searchParams.get('to') ?? '');
+        if (to === 'ALL') throw new Error('ALL is not a recipient');
+        after = Math.max(cursor(url.searchParams.get('since')), cursor(request.headers.get('last-event-id')));
+      } catch (error) { return new Response(error instanceof Error ? error.message : String(error), { status: 400 }); }
+      let subscriber: Subscriber;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          subscriber = { to, lastId: after, heartbeatAt: Date.now(), replaying: true, controller };
+          subscribers.add(subscriber);
+          controller.enqueue(encoder.encode(': connected\n\n'));
+        },
+        pull() { replay(subscriber); },
+        cancel() { subscribers.delete(subscriber); },
+      });
+      request.signal.addEventListener('abort', () => subscribers.delete(subscriber), { once: true });
+      return new Response(stream, { headers: {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+      } });
+    },
+  });
+  const timer = setInterval(tick, pollMs);
+  timer.unref();
+  return { port: server.port ?? input.port,
+    stats: () => ({ subscribers: subscribers.size, maxQueuedEvents }),
+    stop: () => {
+    clearInterval(timer);
+    for (const subscriber of subscribers) { try { subscriber.controller.close(); } catch { /* disconnected */ } }
+    subscribers.clear();
+    server.stop(true);
+  } };
+}