elanous 0.2.4 → 0.2.6

package/src/nexus/api/field-uploads.ts

@@ -0,0 +1,143 @@
+// 현장 업로드 입구 — POST/GET /v1/field/uploads (owner 전용).
+// 저장 규칙은 src/field/field-media.ts 가 유일한 정본이고 텔레그램 `#현장` 도 같은 함수를 쓴다.
+
+import { debug } from '../../debug/log.js';
+import { getElanousConfigDir } from '../../elanous-config-dir.js';
+import {
+  FIELD_MAX_FILE_BYTES,
+  FIELD_MAX_REQUEST_BYTES,
+  FieldUploadError,
+  fieldEventDir,
+  isFieldSlug,
+  listFieldMedia,
+  saveFieldMedia,
+  type FieldMediaInput,
+} from '../../field/field-media.js';
+import { jsonResponse } from './json-response.js';
+
+export const FIELD_UPLOADS_PATH = '/v1/field/uploads';
+
+/** 멀티파트 경계·헤더 여유. */
+const MULTIPART_SLACK_BYTES = 4 * 1024 * 1024;
+/** JSON 본문은 base64(×4/3) 라 더 크다. */
+const JSON_MAX_BODY_BYTES = Math.ceil((FIELD_MAX_REQUEST_BYTES * 4) / 3) + MULTIPART_SLACK_BYTES;
+/** Bun.serve 의 `maxRequestBodySize`(기본 128 MB) — 이 입구의 JSON 상한까지 받도록 서버가 이 값을 쓴다. */
+export const FIELD_SERVER_MAX_BODY_BYTES = JSON_MAX_BODY_BYTES;
+
+interface FieldUploadsDeps {
+  authorize?: (request: Request) => boolean;
+  /** config 뿌리 — 기본 `getElanousConfigDir()`(데몬의 다른 저장소와 같은 해석). 시험은 temp 를 준다. */
+  rootDir?: () => string;
+  now?: () => Date;
+}
+
+function errorResponse(error: FieldUploadError): Response {
+  return jsonResponse({ ok: false, error: error.code, reason: error.message }, error.status);
+}
+
+function parseCapturedAtList(values: FormDataEntryValue[]): Array<string | undefined> {
+  const strings = values.filter((v): v is string => typeof v === 'string');
+  if (strings.length === 1 && strings[0]!.trim().startsWith('[')) {
+    try {
+      const arr = JSON.parse(strings[0]!) as unknown;
+      if (Array.isArray(arr)) return arr.map((v) => (typeof v === 'string' || typeof v === 'number' ? String(v) : undefined));
+    } catch { /* 배열이 아니면 단일 값으로 */ }
+  }
+  return strings;
+}
+
+async function readMultipart(req: Request): Promise<FieldMediaInput[]> {
+  let form: FormData;
+  try { form = await req.formData(); }
+  catch { throw new FieldUploadError('bad-request', 'invalid multipart body'); }
+  const files = form.getAll('file').filter((v): v is File => typeof v !== 'string');
+  const captured = parseCapturedAtList(form.getAll('capturedAt'));
+  let total = 0;
+  const inputs: FieldMediaInput[] = [];
+  for (const [i, file] of files.entries()) {
+    if (file.size > FIELD_MAX_FILE_BYTES) throw new FieldUploadError('too-large', 'a file exceeds 100 MB');
+    total += file.size;
+    if (total > FIELD_MAX_REQUEST_BYTES) throw new FieldUploadError('too-large', 'the request exceeds 250 MB');
+    inputs.push({
+      originalName: file.name || 'media',
+      mimeType: file.type,
+      bytes: new Uint8Array(await file.arrayBuffer()),
+      ...(captured[i] ? { capturedAt: captured[i] } : {}),
+    });
+  }
+  return inputs;
+}
+
+async function readJson(req: Request): Promise<FieldMediaInput[]> {
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { throw new FieldUploadError('bad-request', 'JSON body required'); }
+  const files = body && typeof body === 'object' && !Array.isArray(body) ? (body as { files?: unknown }).files : undefined;
+  if (!Array.isArray(files)) throw new FieldUploadError('bad-request', 'files[] required');
+  return files.map((raw) => {
+    const f = (raw ?? {}) as Record<string, unknown>;
+    if (typeof f.name !== 'string' || typeof f.dataBase64 !== 'string') {
+      throw new FieldUploadError('bad-request', 'each file needs name and dataBase64');
+    }
+    // base64 길이로 먼저 거른다 — 파일 상한(FIELD_MAX_FILE_BYTES)을 넘는 것을 디코드하지 않는다.
+    if (Math.floor((f.dataBase64.length * 3) / 4) > FIELD_MAX_FILE_BYTES + 3) {
+      throw new FieldUploadError('too-large', 'a file exceeds 100 MB');
+    }
+    const capturedAt = typeof f.capturedAt === 'string' || typeof f.capturedAt === 'number' ? f.capturedAt : undefined;
+    return {
+      originalName: f.name,
+      ...(typeof f.mimeType === 'string' ? { mimeType: f.mimeType } : {}),
+      bytes: new Uint8Array(Buffer.from(f.dataBase64, 'base64')),
+      ...(capturedAt !== undefined ? { capturedAt } : {}),
+    };
+  });
+}
+
+export async function handleFieldUploads(req: Request, deps: FieldUploadsDeps = {}): Promise<Response> {
+  const url = new URL(req.url);
+  if (url.pathname !== FIELD_UPLOADS_PATH) return jsonResponse({ error: 'not-found' }, 404);
+  if (!deps.authorize?.(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  const rootDir = (deps.rootDir ?? getElanousConfigDir)();
+  const event = url.searchParams.get('event') ?? '';
+  if (!isFieldSlug(event)) return errorResponse(new FieldUploadError('bad-slug', 'event slug must match ^[a-z0-9][a-z0-9._-]{0,63}$'));
+
+  if (req.method === 'GET') {
+    const files = listFieldMedia(fieldEventDir(rootDir, event));
+    debug.log('field.upload', 'listed', { count: files.length });
+    return jsonResponse({ event, count: files.length, files });
+  }
+  if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+
+  const device = url.searchParams.get('device') ?? '';
+  if (!isFieldSlug(device)) return errorResponse(new FieldUploadError('bad-slug', 'device slug must match ^[a-z0-9][a-z0-9._-]{0,63}$'));
+
+  const contentType = (req.headers.get('content-type') ?? '').toLowerCase();
+  const isMultipart = contentType.startsWith('multipart/form-data');
+  const isJson = contentType.startsWith('application/json');
+  if (!isMultipart && !isJson) {
+    return errorResponse(new FieldUploadError('unsupported-media-type', 'use multipart/form-data or application/json'));
+  }
+  const declared = Number(req.headers.get('content-length') ?? '');
+  const bodyCap = isJson ? JSON_MAX_BODY_BYTES : FIELD_MAX_REQUEST_BYTES + MULTIPART_SLACK_BYTES;
+  if (Number.isFinite(declared) && declared > bodyCap) {
+    debug.log('field.upload', 'refused', { reason: 'too-large', declaredBytes: declared });
+    return errorResponse(new FieldUploadError('too-large', 'the request exceeds 250 MB'));
+  }
+
+  try {
+    const inputs = isMultipart ? await readMultipart(req) : await readJson(req);
+    const caption = url.searchParams.get('caption') ?? undefined;
+    const result = saveFieldMedia(inputs, { rootDir, event, device, ...(caption ? { caption } : {}), ...(deps.now ? { now: deps.now } : {}) });
+    debug.log('field.upload', 'saved', {
+      surface: 'http', files: result.saved.length, bytes: result.saved.reduce((n, s) => n + s.bytes, 0), count: result.count,
+    });
+    return jsonResponse({ ok: true, event, saved: result.saved, count: result.count });
+  } catch (error) {
+    if (error instanceof FieldUploadError) {
+      debug.log('field.upload', 'refused', { surface: 'http', reason: error.code });
+      return errorResponse(error);
+    }
+    debug.log('field.upload', 'failed', { surface: 'http' });
+    throw error;
+  }
+}

package/src/nexus/api/graph-approvals.ts

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync, readdirSync, type Dirent } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { decideGraphApproval, lastJsonObject, type GraphRunState } from '../../graph-runner/runner.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { jsonResponse } from './json-response.js';
+
+export const GRAPH_APPROVALS_PATH = '/v1/graph-approvals';
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+interface GraphApprovalItem {
+  graphId: string;
+  runId: string;
+  nodeId: string;
+  message: string;
+  since: string;
+  path: string[];
+  recent: Array<{ nodeId: string; ok: boolean; outcome?: string; summary?: string }>;
+}
+
+/** One decision this daemon applied through `POST /v1/graph-approvals/:graphId/:runId`. */
+interface GraphApprovalDecided {
+  graphId: string;
+  runId: string;
+  nodeId: string;
+  decision: 'approved' | 'rejected';
+  decidedAt: string;
+}
+
+export const GRAPH_DECISION_RING_CAPACITY = 100;
+export const GRAPH_DECISION_RING_MAX_AGE_MS = 30 * 60 * 1000;
+
+/**
+ * Recent decisions, in memory. The undecided list drops a run the moment it is decided, so
+ * another device (Fold ↔ iPhone) could only see «gone» — this ring lets it say «승인됨/거절됨».
+ * ⚠️ In-memory: a daemon restart forgets it, and a decision made outside this process
+ * (`elanous graph approve` CLI) is not recorded — clients keep a «decided elsewhere» fallback.
+ */
+export function createGraphDecisionRing(opts: { capacity?: number; maxAgeMs?: number; now?: () => number } = {}) {
+  const capacity = opts.capacity ?? GRAPH_DECISION_RING_CAPACITY;
+  const maxAgeMs = opts.maxAgeMs ?? GRAPH_DECISION_RING_MAX_AGE_MS;
+  const now = opts.now ?? Date.now;
+  let entries: Array<{ atMs: number; record: GraphApprovalDecided }> = [];
+  const prune = () => {
+    const cutoff = now() - maxAgeMs;
+    entries = entries.filter((entry) => entry.atMs > cutoff).slice(-capacity);
+  };
+  return {
+    record(decision: Omit<GraphApprovalDecided, 'decidedAt'>): void {
+      const atMs = now();
+      entries.push({ atMs, record: { ...decision, decidedAt: new Date(atMs).toISOString() } });
+      prune();
+    },
+    /** Newest first, pruned by age and capacity. */
+    list(): GraphApprovalDecided[] {
+      prune();
+      return entries.map((entry) => entry.record).reverse();
+    },
+  };
+}
+
+export type GraphDecisionRing = ReturnType<typeof createGraphDecisionRing>;
+
+const defaultDecisionRing = createGraphDecisionRing();
+
+interface GraphApprovalsDeps {
+  /** Injected in tests; production shares one per-process ring. */
+  decisions?: GraphDecisionRing;
+  authorize?: (request: Request) => boolean;
+  /** Credential the request carries, checked independently of same-origin (`bearerCredential`).
+   * A decision needs a bearer token: same-origin alone is not trusted because behind
+   * `tailscale serve` every tailnet peer (Pod included) arrives from loopback. */
+  authReason?: (request: Request) => string | undefined;
+  root?: string;
+}
+
+const DECISION_AUTH_REASONS = new Set(['bearer-match', 'temp-token', 'noauth']);
+
+function validSegment(value: string): boolean {
+  return SEGMENT.test(value) && value !== '.' && value !== '..';
+}
+
+function readRun(root: string, graphId: string, runId: string): GraphRunState | null {
+  if (!validSegment(graphId) || !validSegment(runId)) return null;
+  try {
+    const state = JSON.parse(readFileSync(join(root, 'graph-runs', graphId, `${runId}.json`), 'utf8')) as GraphRunState;
+    return state.graphId === graphId && state.runId === runId ? state : null;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function undecided(state: GraphRunState, root: string): boolean {
+  return state.status === 'awaiting-approval' && !!state.pending && !state.pending.decision
+    && Array.isArray(state.path) && !existsSync(join(root, 'graph-runs', state.graphId, `${state.runId}.json.${state.path.length}.decision.json`));
+}
+
+function list(root: string): GraphApprovalItem[] {
+  const dir = join(root, 'graph-runs');
+  let graphs: Dirent[];
+  try { graphs = readdirSync(dir, { withFileTypes: true }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const items: GraphApprovalItem[] = [];
+  for (const graph of graphs) {
+    if (!graph.isDirectory() || !validSegment(graph.name)) continue;
+    for (const file of readdirSync(join(dir, graph.name), { withFileTypes: true })) {
+      if (!file.isFile() || !file.name.endsWith('.json') || file.name.endsWith('.decision.json')) continue;
+      const runId = file.name.slice(0, -5);
+      const state = readRun(root, graph.name, runId);
+      if (!state || !undecided(state, root) || !Array.isArray(state.nodes)) continue;
+      const pending = state.pending!;
+      items.push({
+        graphId: state.graphId, runId: state.runId, nodeId: pending.nodeId, message: pending.message,
+        since: pending.since, path: state.path,
+        recent: state.nodes.slice(-5).map((node) => {
+          const output = lastJsonObject(node.output);
+          return {
+            nodeId: node.nodeId, ok: node.ok,
+            ...(typeof output?.outcome === 'string' ? { outcome: output.outcome } : {}),
+            ...(typeof output?.summary === 'string' ? { summary: output.summary } : {}),
+          };
+        }),
+      });
+    }
+  }
+  return items.sort((a, b) => b.since.localeCompare(a.since));
+}
+
+export async function handleGraphApprovals(req: Request, deps: GraphApprovalsDeps = {}): Promise<Response> {
+  const pathname = new URL(req.url).pathname;
+  const match = /^\/v1\/graph-approvals\/([^/]+)\/([^/]+)$/.exec(pathname);
+  if (pathname !== GRAPH_APPROVALS_PATH && !match) return jsonResponse({ error: 'not-found' }, 404);
+  if (!deps.authorize?.(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (pathname === GRAPH_APPROVALS_PATH) {
+    if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+    // ⭐ `items` is unchanged; `decided` is additive (newest first) for other devices' cards.
+    return jsonResponse({ items: list(deps.root ?? effectiveInstanceRoot()), decided: (deps.decisions ?? defaultDecisionRing).list() });
+  }
+  if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  const authReason = deps.authReason?.(req);
+  if (!authReason || !DECISION_AUTH_REASONS.has(authReason)) {
+    debug.log('approvals.graph', 'refused', { reason: 'pairing-required', auth: authReason ?? null });
+    return jsonResponse({ error: 'pairing-required' }, 403);
+  }
+  let graphId: string;
+  let runId: string;
+  try { graphId = decodeURIComponent(match![1]!); runId = decodeURIComponent(match![2]!); }
+  catch { return jsonResponse({ error: 'not-found' }, 404); }
+  if (!validSegment(graphId) || !validSegment(runId)) return jsonResponse({ error: 'not-found' }, 404);
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const decision = body && typeof body === 'object' && !Array.isArray(body) && 'decision' in body ? body.decision : undefined;
+  if (decision !== 'approved' && decision !== 'rejected') return jsonResponse({ error: 'bad_request' }, 400);
+  const root = deps.root ?? effectiveInstanceRoot();
+  const state = readRun(root, graphId, runId);
+  if (!state) return jsonResponse({ error: 'not-found' }, 404);
+  if (!undecided(state, root)) return jsonResponse({ error: 'already-decided' }, 409);
+  const nodeId = state.pending!.nodeId;
+  try {
+    decideGraphApproval(graphId, runId, decision, `pwa:${authReason}`, root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return jsonResponse({ error: 'not-found' }, 404);
+    if (error instanceof Error && error.message.startsWith('run is not awaiting an undecided approval:')) return jsonResponse({ error: 'already-decided' }, 409);
+    throw error;
+  }
+  (deps.decisions ?? defaultDecisionRing).record({ graphId, runId, nodeId, decision });
+  debug.log('approvals.graph', 'decided', { graphId, runId, nodeId, decision, by: `pwa:${authReason}` });
+  return jsonResponse({ graphId, runId, decision });
+}

package/src/nexus/api/harness-api.ts

@@ -1,5 +1,7 @@
-import { readFileSync, writeFileSync } from 'node:fs';
-import { relative } from 'node:path';
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { hasTerminalRunStatus, loadRunLedger, runLedgerDir, runLedgerPath, type RunLedgerEntry } from '../../self-implement/run-ledger.js';
+import { summarizeTerminalLedger } from '../../self-implement/run-ledger-compact.js';
 import { debug } from '../../debug/log.js';
 import { enqueueSoftStop } from '../../harness/control-inbox.js';
 import { listHarnessScreens, readHarnessScreenTail } from '../../harness/harness-screen.js';
@@ -103,6 +105,10 @@ export interface HarnessApiDeps {
   readonly createAcceptanceId?: () => string;
   readonly log?: (event: string, data: Record<string, unknown>) => void;
   readonly createFeedbackEmitter?: (acceptanceId: string) => (env: FeedbackEnvelope) => void | Promise<void>;
+  /** 시험 심 — `?finishedSince=` 가 읽는 원장 디렉터리(기본 `runLedgerDir()`). */
+  readonly ledgerDir?: string;
+  /** 시험 심 — `?finishedSince=` 의 `landed`(gh 실행기·저장소·시간 초과). */
+  readonly landed?: LandedPrsDeps;
 }
 
 function json(body: unknown, status = 200): Response {
@@ -338,10 +344,218 @@ export function handleHarnessAskStatusGet(req: Request, _metaApi: HarnessMetaApi
   });
 }
 
-/** Return the structured shared running-runs observation without human rendering. */
-export function handleHarnessRunsGet(_req: Request, _metaApi: HarnessMetaApi, deps: HarnessApiDeps = {}): Response {
+/** One terminated run for `GET /v1/harness/runs?finishedSince=` (iPhone «오늘 끝난 일» · 2026-09-30). */
+export interface HarnessFinishedRun {
+  runId: string;
+  status: string;
+  endedAt: string;
+  /** 마지막 `run-status` 의 `stage`(예: `merged`·`pr-declined`) — 칩을 더 정확히 고를 때. */
+  stage?: string;
+  objective?: string;
+  prUrl?: string;
+  /** `merged` 이벤트의 값 — 이벤트가 없으면 칸이 없다(«병합 안 됨»으로 접지 않는다). */
+  merged?: boolean;
+  /** 마지막 `merge-decision` 의 `decision`(`auto`·`hitl`) — 병합 «결정»이지 병합 «사실»이 아니다. */
+  mergeDecision?: string;
+}
+
+export const FINISHED_RUNS_LIMIT = 20;
+export const FINISHED_RUNS_MAX_FILES = 300;
+export const FINISHED_RUNS_MAX_FILE_BYTES = 5 * 1024 * 1024;
+const FINISHED_OBJECTIVE_MAX_CHARS = 160;
+
+/**
+ * 원장 디렉터리에서 `sinceMs` 이후에 쓰인 «끝난» 런을 요약한다. 읽기는 묶여 있다 —
+ * mtime 최신 {@link FINISHED_RUNS_MAX_FILES} 개만 보고, {@link FINISHED_RUNS_MAX_FILE_BYTES} 를 넘는 파일은 건너뛴다.
+ */
+export function collectFinishedRuns(dir: string, sinceMs: number): { runs: HarnessFinishedRun[]; scannedFiles: number; skippedFiles: number } {
+  let names: string[];
+  try { names = readdirSync(dir); }
+  catch { return { runs: [], scannedFiles: 0, skippedFiles: 0 }; }
+  const candidates: Array<{ runId: string; mtimeMs: number; size: number }> = [];
+  for (const name of names) {
+    if (!name.endsWith('.jsonl')) continue;
+    try {
+      const st = statSync(join(dir, name));
+      if (st.isFile() && st.mtimeMs >= sinceMs) candidates.push({ runId: name.slice(0, -'.jsonl'.length), mtimeMs: st.mtimeMs, size: st.size });
+    } catch { /* 사이에 지워졌다 */ }
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const scanned = candidates.slice(0, FINISHED_RUNS_MAX_FILES);
+  let skippedFiles = candidates.length - scanned.length;
+  const runs: HarnessFinishedRun[] = [];
+  for (const file of scanned) {
+    if (file.size > FINISHED_RUNS_MAX_FILE_BYTES) { skippedFiles += 1; continue; }
+    let entries: RunLedgerEntry[] | null;
+    try { entries = loadRunLedger(file.runId, dir); }
+    catch { skippedFiles += 1; continue; }
+    if (!entries?.length || !hasTerminalRunStatus(entries)) continue;
+    let summary: ReturnType<typeof summarizeTerminalLedger>;
+    try { summary = summarizeTerminalLedger(file.runId, entries); }
+    catch { skippedFiles += 1; continue; }
+    if (!(Date.parse(summary.endedAt) >= sinceMs)) continue;
+    const feature = entries.find((entry) => entry.event === 'start' && typeof entry.data.feature === 'string')?.data.feature as string | undefined;
+    const objective = feature?.trim().slice(0, FINISHED_OBJECTIVE_MAX_CHARS);
+    const mergedEvent = [...entries].reverse().find((entry) => entry.event === 'merged' && typeof entry.data.merged === 'boolean');
+    const decision = [...entries].reverse().find((entry) => entry.event === 'merge-decision' && typeof entry.data.decision === 'string');
+    const statusEntry = [...entries].reverse().find((entry) => entry.event === 'run-status' && typeof entry.data.stage === 'string');
+    runs.push({
+      runId: summary.runId,
+      status: summary.status,
+      endedAt: summary.endedAt,
+      ...(statusEntry ? { stage: statusEntry.data.stage as string } : {}),
+      ...(objective ? { objective } : {}),
+      ...(summary.prUrl ? { prUrl: summary.prUrl } : {}),
+      ...(mergedEvent ? { merged: mergedEvent.data.merged as boolean } : {}),
+      ...(decision ? { mergeDecision: decision.data.decision as string } : {}),
+    });
+  }
+  runs.sort((a, b) => Date.parse(b.endedAt) - Date.parse(a.endedAt));
+  return { runs: runs.slice(0, FINISHED_RUNS_LIMIT), scannedFiles: scanned.length, skippedFiles };
+}
+
+/** 도는 런의 목표 — 그 런 원장의 첫 `start.data.feature`(≤160자). 원장 경로는 그 항목이 준 디렉터리들만 본다(런 수만큼만 읽는다). */
+export function runObjectiveFromLedgers(runId: string, directories: readonly string[]): string | undefined {
+  for (const dir of directories) {
+    try {
+      if (statSync(runLedgerPath(runId, dir)).size > FINISHED_RUNS_MAX_FILE_BYTES) continue;
+      const feature = loadRunLedger(runId, dir)?.find((entry) => entry.event === 'start' && typeof entry.data.feature === 'string')?.data.feature;
+      const objective = typeof feature === 'string' ? feature.trim().slice(0, FINISHED_OBJECTIVE_MAX_CHARS) : '';
+      if (objective) return objective;
+    } catch { /* 없거나 못 읽음 — 다음 디렉터리 */ }
+  }
+  return undefined;
+}
+
+// ── 오늘 착지(= main 에 병합된 PR) — 원장은 Pod·시험 우주의 런을 못 보므로 GitHub 이 정본이다 ──
+
+/** `landed` 한 줄 — `gh pr list --json number,title,url,mergedAt` 모양 그대로. */
+export interface HarnessLandedPr {
+  number: number;
+  title: string;
+  url: string;
+  mergedAt: string;
+}
+
+export const LANDED_PRS_LIMIT = 30;
+export const LANDED_PRS_TIMEOUT_MS = 4_000;
+const LANDED_CACHE_MS = 60_000;
+const landedCache = new Map<string, { at: number; prs: HarnessLandedPr[]; truncated: boolean }>();
+let cachedRepoSlug: string | null | undefined;
+
+export function _resetLandedPrsCacheForTest(): void {
+  landedCache.clear();
+  cachedRepoSlug = undefined;
+}
+
+export interface LandedPrsDeps {
+  /** gh 실행기(기본 = `git-fs/gh-cli` 의 재시도 게이트웨이 · 비동기). */
+  readonly runGh?: (args: string[]) => Promise<{ ok: boolean; exitCode: number; stdout: Buffer | string; stderr: Buffer | string }>;
+  /** 저장소 `owner/name` — 기본은 데몬이 아는 저장소 뿌리(`harness.defaultRepo` → cwd)의 origin. */
+  readonly repoSlug?: () => Promise<string | null>;
+  readonly timeoutMs?: number;
+  readonly now?: () => number;
+}
+
+async function defaultRepoSlug(): Promise<string | null> {
+  if (cachedRepoSlug !== undefined) return cachedRepoSlug;
+  const [{ resolveWorktreesRepoRoot }, { slugFromRemote }] = await Promise.all([import('./worktrees.js'), import('./live-shipped.js')]);
+  const root = resolveWorktreesRepoRoot();
+  if (!root) return (cachedRepoSlug = null);
+  const proc = Bun.spawn(['git', '-C', root, 'remote', 'get-url', 'origin'], { stdout: 'pipe', stderr: 'ignore' });
+  const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return (cachedRepoSlug = code === 0 ? slugFromRemote(out) : null);
+}
+
+async function defaultRunGh(args: string[]) {
+  const { runGhCliWithResultAsync } = await import('../../git-fs/gh-cli.js');
+  return runGhCliWithResultAsync(args);
+}
+
+function isLandedPr(value: unknown): value is HarnessLandedPr {
+  const v = value as Partial<HarnessLandedPr> | null;
+  return !!v && typeof v.number === 'number' && typeof v.title === 'string' && typeof v.url === 'string' && typeof v.mergedAt === 'string';
+}
+
+/** `sinceMs` 이후 main 에 병합된 PR(최신순 ≤30). 실패·시간 초과는 던지지 않고 `error` 로 돌려준다. 성공만 60초 캐시한다. */
+export async function listLandedPrs(sinceMs: number, deps: LandedPrsDeps = {}): Promise<{ prs: HarnessLandedPr[]; error?: string; cached?: boolean; truncated?: boolean }> {
+  const now = deps.now?.() ?? Date.now();
+  const sinceIso = new Date(Math.floor(sinceMs / 60_000) * 60_000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const hit = landedCache.get(sinceIso);
+  if (hit && now - hit.at < LANDED_CACHE_MS) return { prs: hit.prs, cached: true, ...(hit.truncated ? { truncated: true } : {}) };
+  const timeoutMs = deps.timeoutMs ?? LANDED_PRS_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<{ prs: HarnessLandedPr[]; error: string }>((resolve) => {
+    timer = setTimeout(() => resolve({ prs: [], error: `timeout ${timeoutMs}ms` }), timeoutMs);
+  });
+  const work = (async (): Promise<{ prs: HarnessLandedPr[]; error?: string; truncated?: boolean }> => {
+    try {
+      const slug = await (deps.repoSlug ?? defaultRepoSlug)();
+      if (!slug) return { prs: [], error: 'no-repository' };
+      const result = await (deps.runGh ?? defaultRunGh)([
+        'pr', 'list', '--repo', slug, '--state', 'merged', '--base', 'main',
+        '--search', `merged:>=${sinceIso}`,
+        '--json', 'number,title,url,mergedAt', '--limit', String(LANDED_PRS_LIMIT),
+      ]);
+      if (!result.ok) {
+        const stderr = String(result.stderr).trim().split('\n')[0] ?? '';
+        return { prs: [], error: `gh failed rc=${result.exitCode}${stderr ? `: ${redactSecretText(stderr).slice(0, 120)}` : ''}` };
+      }
+      const parsed: unknown = JSON.parse(String(result.stdout));
+      if (!Array.isArray(parsed)) return { prs: [], error: 'gh returned non-array' };
+      const prs = parsed.filter(isLandedPr)
+        .filter((pr) => Date.parse(pr.mergedAt) >= sinceMs)
+        .sort((a, b) => Date.parse(b.mergedAt) - Date.parse(a.mergedAt));
+      // gh 가 상한만큼 줬으면 더 있을 수 있다 — «전부»라고 말하지 않는다.
+      const truncated = parsed.length >= LANDED_PRS_LIMIT;
+      landedCache.set(sinceIso, { at: now, prs, truncated });
+      return { prs, ...(truncated ? { truncated: true } : {}) };
+    } catch (error) {
+      return { prs: [], error: message(error).slice(0, 120) };
+    }
+  })();
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Return the structured shared running-runs observation without human rendering.
+ *  `?finishedSince=<epoch ms>` 가 있으면(iPhone «오늘» · 2026-09-30) 셋을 더한다 —
+ *  `finished`(이 우주 원장의 끝난 런 · 최신순 ≤20) · `landed`(그 시각 뒤 main 에 병합된 PR · ≤30 · 실패면 `[]` ⊕ `landedError`) ·
+ *  도는 항목마다 `objective`(그 런 원장의 `start.feature`). 없으면 응답은 종전 그대로다(동기 응답). */
+export function handleHarnessRunsGet(req: Request, _metaApi: HarnessMetaApi, deps: HarnessApiDeps = {}): Response | Promise<Response> {
   const runs: RunningRunsResult = (deps.queryRunningRuns ?? queryRunningRuns)({ includeTest: false });
-  return json(runs);
+  const raw = new URL(req.url).searchParams.get('finishedSince');
+  if (raw === null) return json(runs);
+  const sinceMs = Number(raw);
+  if (!raw.trim() || !Number.isFinite(sinceMs) || sinceMs < 0) {
+    return json({ error: 'usage: GET /v1/harness/runs?finishedSince=<epoch ms>' }, 400);
+  }
+  return (async () => {
+    const landedWork = listLandedPrs(sinceMs, deps.landed ?? {});
+    const dir = deps.ledgerDir ?? runLedgerDir();
+    const finished = collectFinishedRuns(dir, sinceMs);
+    const entries = runs.entries.map((entry) => {
+      const objective = runObjectiveFromLedgers(entry.runId, entry.ledgerDirectories?.length ? entry.ledgerDirectories : [dir]);
+      return objective ? { ...entry, objective } : entry;
+    });
+    const landed = await landedWork;
+    debug.log('harness-http', 'runs-finished', {
+      sinceMs, count: finished.runs.length, scannedFiles: finished.scannedFiles, skippedFiles: finished.skippedFiles,
+      landed: landed.prs.length, landedCached: landed.cached === true, ...(landed.error ? { landedError: landed.error } : {}),
+    });
+    return json({
+      ...runs,
+      entries,
+      finished: finished.runs,
+      finishedObservation: { sinceMs, scannedFiles: finished.scannedFiles, skippedFiles: finished.skippedFiles, limit: FINISHED_RUNS_LIMIT },
+      landed: landed.prs,
+      ...(landed.truncated ? { landedTruncated: true } : {}),
+      ...(landed.error ? { landedError: landed.error } : {}),
+    });
+  })();
 }
 
 /** Return the human-readable skeleton events persisted for one harness run. */