elanous 0.2.8 → 0.2.10

package/src/nexus/api/ops-seats.ts

@@ -0,0 +1,124 @@
+// GET /v1/ops/seats?date=YYYY-MM-DD — one row per seat: latest channel line, PRs landed that day, red items, open decisions.
+// A source that could not be read is null, never 0 («못 읽음» ≠ «없음»). Contract: 내부 문서 `DESIGN-ops3-seat-board-and-public-demo-2026-10-02` §1.
+import { debug, redactSecretText } from '../../debug/log.js';
+import { parseOwner, type ChecklistItem } from '../../release-loop/checklist.js';
+import { canonicalSeatId } from '../../msg/msg-store.js';
+
+export const SEATS = [
+  { seat: 'OP', role: 'COO' }, { seat: 'TC', role: 'CTO' }, { seat: 'MK', role: 'CMO' }, { seat: 'UX', role: 'CXO' },
+] as const;
+export const SEATS_CACHE_MS = 60_000;
+
+export interface ChannelComment { body: string; createdAt: string; url?: string }
+export type ChannelSource = 'ledger' | 'github' | 'unreadable' | 'unknown';
+export type ChannelResult = ChannelComment[] | {
+  comments: ChannelComment[];
+  source: 'ledger' | 'github';
+  seatSources?: Partial<Record<(typeof SEATS)[number]['seat'], ChannelSource>>;
+} | null;
+export interface MergedPr { number: number; title: string; body: string; mergedAt: string }
+export interface SeatsSources {
+  /** Coordination-channel comments created on `date` (KST) or later; null when unreadable. */
+  channel(date: string): Promise<ChannelResult>;
+  /** PRs merged on `date` (KST); null when unreadable. */
+  merged(date: string): Promise<MergedPr[] | null>;
+  /** Checklist items of the version being worked on (counts, red) and of every version known (id → owner). */
+  checklist(): { current: ChecklistItem[]; all: ChecklistItem[] } | null;
+  /** `raisedBy.agent` of every open decision. */
+  openDecisionRaisers(): string[] | null;
+}
+
+export interface SeatRow {
+  seat: string; role: string;
+  channelSource: ChannelSource;
+  now: { text: string; at: string } | null;
+  landed: Array<{ pr: number; title: string; at: string; checklistId: string | null }> | null;
+  blocked: Array<{ id: string; title: string; status: 'red' }> | null;
+  pendingDecisions: number | null;
+  checklist: { green: number; yellow: number; red: number; done: number } | null;
+}
+
+function seatOf(value: string | undefined): string | null {
+  if (!value) return null;
+  try { return canonicalSeatId(value.includes('/') ? parseOwner(value).seat : value); } catch { return null; }
+}
+
+const clip = (text: string, max: number) => redactSecretText(text).slice(0, max);
+
+/** First checklist id that appears as a whole word in the title, else in the body. */
+function checklistIdOf(pr: MergedPr, ids: string[]): string | null {
+  for (const text of [pr.title, pr.body]) {
+    const found = ids.map((id) => ({ id, at: text.search(new RegExp(`(?<![A-Za-z0-9])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9])`)) }))
+      .filter((hit) => hit.at >= 0).sort((a, b) => a.at - b.at || b.id.length - a.id.length);
+    if (found.length) return found[0]!.id;
+  }
+  return null;
+}
+
+export async function buildSeatsBoard(date: string, sources: SeatsSources): Promise<{ date: string; seats: SeatRow[] }> {
+  const [channelResult, merged] = await Promise.all([
+    sources.channel(date).catch(() => null), sources.merged(date).catch(() => null),
+  ]);
+  const channel = Array.isArray(channelResult) ? channelResult : channelResult?.comments ?? null;
+  const channelSource: ChannelSource = channelResult === null ? 'unreadable' : 'unknown';
+  let checklist: ReturnType<SeatsSources['checklist']> = null;
+  try { checklist = sources.checklist(); } catch { checklist = null; }
+  let raisers: string[] | null = null;
+  try { raisers = sources.openDecisionRaisers(); } catch { raisers = null; }
+
+  const owners = new Map<string, string>();
+  for (const item of checklist?.all ?? []) { const seat = seatOf(item.owner); if (seat) owners.set(item.id, seat); }
+  const ids = [...owners.keys()];
+  const landedBySeat = new Map<string, NonNullable<SeatRow['landed']>>();
+  for (const pr of merged ?? []) {
+    const id = checklistIdOf(pr, ids);
+    const seat = id ? owners.get(id) : undefined;
+    if (!seat) continue; // ⛔ not by commit author — every seat lands through the same account.
+    landedBySeat.set(seat, [...(landedBySeat.get(seat) ?? []), { pr: pr.number, title: clip(pr.title, 80), at: pr.mergedAt, checklistId: id }]);
+  }
+
+  const seats = SEATS.map(({ seat, role }): SeatRow => {
+    const latest = channel?.filter((c) => c.body.trimStart().startsWith(`**[${seat}]**`)).sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+    const mine = checklist?.current.filter((item) => seatOf(item.owner) === seat);
+    return {
+      seat, role, channelSource: channelResult && !Array.isArray(channelResult)
+        ? channelResult.seatSources?.[seat] ?? channelSource : channelSource,
+      now: latest ? { text: clip(latest.body.trimStart().split('\n')[0]!, 120), at: latest.createdAt } : null,
+      landed: merged === null || checklist === null ? null : (landedBySeat.get(seat) ?? []).sort((a, b) => a.at.localeCompare(b.at)),
+      blocked: mine ? mine.filter((item) => item.status === 'red').map((item) => ({ id: item.id, title: clip(item.title, 80), status: 'red' as const })) : null,
+      pendingDecisions: raisers === null ? null : raisers.filter((agent) => seatOf(agent) === seat).length,
+      checklist: mine ? {
+        green: mine.filter((i) => i.status === 'green').length, yellow: mine.filter((i) => i.status === 'yellow').length,
+        red: mine.filter((i) => i.status === 'red').length, done: mine.filter((i) => i.status === 'done').length,
+      } : null,
+    };
+  });
+  debug.log('ops.seats', 'built', {
+    date, channel: channel === null ? 'unreadable' : channel.length, merged: merged === null ? 'unreadable' : merged.length,
+    checklist: checklist !== null, decisions: raisers !== null,
+  });
+  return { date, seats };
+}
+
+/** KST calendar day → [start, end) in UTC ISO. */
+export function kstDayRange(date: string): { start: string; end: string } {
+  const start = new Date(`${date}T00:00:00+09:00`);
+  return { start: start.toISOString(), end: new Date(start.getTime() + 86_400_000).toISOString() };
+}
+
+export function todayKst(now = new Date()): string {
+  return new Intl.DateTimeFormat('sv-SE', { timeZone: 'Asia/Seoul' }).format(now);
+}
+
+/** One snapshot per date for 60 s; concurrent requests share one build. */
+export function createSeatsCache(sources: SeatsSources, now: () => number = Date.now, ttlMs = SEATS_CACHE_MS) {
+  const slots = new Map<string, { at: number; value: Promise<{ date: string; seats: SeatRow[] }> }>();
+  return (date: string) => {
+    const slot = slots.get(date);
+    if (slot && now() - slot.at < ttlMs) return slot.value;
+    const value = buildSeatsBoard(date, sources);
+    slots.set(date, { at: now(), value });
+    value.catch(() => slots.delete(date));
+    return value;
+  };
+}

package/src/nexus/api/public-routes.ts

@@ -36,6 +36,12 @@ export const PUBLIC_ROUTES: Array<PublicRoute> = [
     path: '/v1/push/vapid-public-key',
     why: 'PWA fetches the VAPID public key before a bearer is pasted',
   },
+  {
+    method: 'GET',
+    match: 'exact',
+    path: '/v1/me',
+    why: 'operator signal only (draw the ops area or not); false unless operator.enabled, no other data',
+  },
   {
     method: 'GET',
     match: 'exact',
@@ -56,6 +62,13 @@ export const PUBLIC_ROUTES: Array<PublicRoute> = [
     selfVerified: true,
     why: 'Pod GitHub App credential relay verifies its own run-scoped gh-credential token before minting a repository-scoped installation token',
   },
+  {
+    method: 'POST',
+    match: 'exact',
+    path: '/v1/setup/claim',
+    selfVerified: true,
+    why: 'one-use setup link is verified by the claim handler without an owner bearer',
+  },
   {
     method: 'GET',
     match: 'prefix',
@@ -76,7 +89,7 @@ export function isPublicRoute(
 ): boolean {
   for (const route of PUBLIC_ROUTES) {
     if (route.method !== method) continue;
-    if (route.path.startsWith('/v1/setup/') && !ctx.setupMode) continue;
+    if (route.path.startsWith('/v1/setup/') && route.path !== '/v1/setup/claim' && !ctx.setupMode) continue;
     if (route.match === 'exact') {
       if (pathname === route.path) return true;
     } else if (pathname === route.path || pathname.startsWith(route.path)) {

package/src/nexus/api/seat-requests.ts

@@ -1,7 +1,12 @@
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { debug } from '../../debug/log.js';
+import { resolveAttachmentPath } from '../../boot/attachment-store.js';
+import { runGh } from '../../decisions/decision-cards.js';
+import { openMsgStore, canonicalSeatId } from '../../msg/msg-store.js';
+import { dispatchCeoTask, type CeoCommandDeps } from '../../seat-dispatch/ceo-commands.js';
+import { getUserConfig } from '../../user-config.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
 import { submitIntakeWork } from '../../intake-plane/submit-intake-work.js';
 import { parseSeatAddress, resolveSeat } from '../../seat-address/seat-address.js';
@@ -16,6 +21,9 @@ interface SeatRequestItem {
   text: string;
   queuedAt: string;
   status: 'queued';
+  attachments?: string[];
+  channel?: 'posted' | 'failed' | 'unknown';
+  channelError?: string;
 }
 
 interface PendingRequest {
@@ -25,6 +33,7 @@ interface PendingRequest {
   text: string;
   queuedAt: string;
   ref: string;
+  attachments?: string[];
 }
 
 interface RejectedRequest extends Omit<PendingRequest, 'status'> {
@@ -38,10 +47,17 @@ export interface SeatRequestsDeps {
   submit?: typeof submitIntakeWork;
   now?: () => string;
   append?: (path: string, entry: RecordEntry) => void;
+  resolveAttachment?: typeof resolveAttachmentPath;
+  dispatch?: typeof dispatchCeoTask;
+  ceoDeps?: () => CeoCommandDeps;
 }
 
 const seats = trackData.tracks.filter((entry): entry is typeof entry & { title: string } => 'title' in entry)
   .map(({ id, title }) => ({ id, title }));
+
+function requestSeat(address: string) {
+  return resolveSeat(address) ?? trackData.tracks.find((entry) => entry.id.toLowerCase() === address.replace(/^@/, '').toLowerCase());
+}
 const inFlight = new Map<string, { payload: string; task: Promise<Response> }>();
 
 function unknownSeat(): Response {
@@ -140,7 +156,28 @@ function persistOutcome(path: string, entry: RecordEntry, write: typeof append):
 }
 
 function receipt(item: SeatRequestItem): Response {
-  return jsonResponse({ receiptId: item.receiptId, seat: item.seat, queuedAt: item.queuedAt }, 202);
+  return jsonResponse({ receiptId: item.receiptId, seat: item.seat, queuedAt: item.queuedAt,
+    // Only a CEO-seat dispatch knows whether the channel line went out; anything else is reported as unknown.
+    attachments: item.attachments?.length ?? 0, channel: item.channel ?? 'unknown',
+    ...(item.channelError ? { channelError: item.channelError } : {}) }, 202);
+}
+
+function defaultCeoDeps(): CeoCommandDeps {
+  const cfg = getUserConfig();
+  const replyTarget = (cfg.raw?.decisions as { replyGhPr?: unknown } | undefined)?.replyGhPr;
+  return { ownerId: null, replyTarget: typeof replyTarget === 'string' ? replyTarget : null, runGh,
+    append: (message) => { const store = openMsgStore(); try { return store.append(message); } finally { store.close(); } },
+    hasMessage: (seat, ref) => {
+      const store = openMsgStore();
+      try {
+        return store.db.query("SELECT 1 FROM msg_messages WHERE recipient = ? AND kind = 'ceo-task' AND body LIKE ? LIMIT 1")
+          .get(seat, `%\n요청: ${ref}`) !== null;
+      } finally { store.close(); }
+    } };
+}
+
+function canonicalSeatIdSafe(id: string): string {
+  try { return canonicalSeatId(id); } catch { return id; }
 }
 
 function unavailable(): Response {
@@ -153,7 +190,7 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
   if (req.method === 'GET') {
     const params = new URL(req.url).searchParams;
     const requestedSeat = params.get('seat');
-    const seat = requestedSeat ? resolveSeat(requestedSeat) : undefined;
+    const seat = requestedSeat ? requestSeat(requestedSeat) : undefined;
     if (requestedSeat && !seat) return unknownSeat();
     const rawLimit = params.get('limit');
     const limit = rawLimit === null ? 20 : Number(rawLimit);
@@ -183,18 +220,30 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
   const firstAddress = parsed && input.text.startsWith(prefix)
     && (input.text.length === prefix.length || /[ \t\r\n]/.test(input.text[prefix.length]!)) ? parsed : null;
   const address = input.seat ?? (firstAddress?.seats.length === 1 ? firstAddress.seats[0] : undefined);
-  const seat = address ? resolveSeat(address) : undefined;
+  const seat = address ? requestSeat(address) : undefined;
   if (!seat) return unknownSeat();
   const text = input.seat === undefined ? firstAddress!.body.trim() : input.text.trim();
   if (!text) {
     debug.log('seat-address.pwa', 'rejected', { reason: 'empty-text', seat: seat.id });
     return jsonResponse({ error: 'bad_request' }, 400);
   }
+  if (input.attachments !== undefined && (!Array.isArray(input.attachments) || input.attachments.length > 4
+    || input.attachments.some((attachment: unknown) => !attachment || typeof attachment !== 'object' || Array.isArray(attachment)
+      || typeof (attachment as { id?: unknown }).id !== 'string' || !(attachment as { id: string }).id.trim()))) {
+    debug.log('seat.dispatch', 'refused', { seat: seat.id, reason: 'invalid-attachments' });
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  const attachmentIds = (input.attachments as Array<{ id: string }> | undefined)?.map(({ id }) => id) ?? [];
+  // Intake (non-CEO seats) carries text only — refuse attachments there instead of accepting and dropping them.
+  if (attachmentIds.length && !['OP', 'TC', 'MK', 'UX'].includes(canonicalSeatIdSafe(seat.id))) {
+    debug.log('seat.dispatch', 'refused', { seat: seat.id, reason: 'attachments-unsupported' });
+    return jsonResponse({ error: 'attachments-unsupported', seat: seat.id }, 400);
+  }
   debug.log('seat-address.pwa', 'parsed', { seat: seat.id, textLength: text.length });
   const now = (deps.now ?? (() => new Date().toISOString()))();
   const header = req.headers.get('idempotency-key');
   if (header !== null && (!header.trim() || header.length > 200)) return jsonResponse({ error: 'bad_request' }, 400);
-  const payload = `${seat.id}\0${text}`;
+  const payload = JSON.stringify([seat.id, text, attachmentIds]);
   const key = header === null ? createHash('sha256').update(randomUUID()).digest('hex')
     : createHash('sha256').update(`client\0${header}`).digest('hex');
   const lock = `${path}\0${key}`;
@@ -213,11 +262,23 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
     try { existing = records(path).get(key); }
     catch { return unavailable(); }
     if (existing) {
-      if (existing.seat !== seat.id || existing.text !== text) return jsonResponse({ error: 'idempotency-conflict' }, 409);
+      if (existing.seat !== seat.id || existing.text !== text
+        || JSON.stringify(existing.attachments ?? []) !== JSON.stringify(attachmentIds)) return jsonResponse({ error: 'idempotency-conflict' }, 409);
       if (existing.status === 'queued') return receipt(existing);
     }
+    const attachments: Array<{ name: string; path: string }> = [];
+    for (const id of attachmentIds) {
+      const resolved = (deps.resolveAttachment ?? resolveAttachmentPath)(id);
+      if (!resolved) {
+        debug.log('seat.dispatch', 'refused', { seat: seat.id, reason: 'unknown-attachment' });
+        return jsonResponse({ error: 'unknown-attachment', id }, 400);
+      }
+      const metadata = (input.attachments as Array<{ name?: unknown }>)[attachments.length];
+      attachments.push({ name: typeof metadata?.name === 'string' && metadata.name.trim() ? metadata.name : basename(resolved), path: resolved });
+    }
     const intent: PendingRequest = existing?.status === 'pending'
-      ? existing : { key, seat: seat.id, text, queuedAt: now, status: 'pending', ref: `pwa:${randomUUID()}` };
+      ? existing : { key, seat: seat.id, text, queuedAt: now, status: 'pending', ref: `pwa:${randomUUID()}`,
+        ...(attachmentIds.length ? { attachments: attachmentIds } : {}) };
     if (existing?.status !== 'pending') {
       try {
         (deps.append ?? append)(path, intent);
@@ -227,6 +288,24 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
         }
       } catch { return unavailable(); }
     }
+    const ceoSeat = canonicalSeatId(seat.id);
+    if (['OP', 'TC', 'MK', 'UX'].includes(ceoSeat)) {
+      let result: Awaited<ReturnType<typeof dispatchCeoTask>>;
+      try {
+        result = await (deps.dispatch ?? dispatchCeoTask)(ceoSeat, text, (deps.ceoDeps ?? defaultCeoDeps)(), { attachments, via: 'pwa', ref: intent.ref });
+      } catch {
+        debug.log('seat.dispatch', 'refused', { seat: seat.id, reason: 'dispatch-failed' });
+        return unavailable();
+      }
+      const item: RecordEntry & SeatRequestItem = {
+        key, receiptId: intent.ref, seat: seat.id, text, queuedAt: intent.queuedAt, status: 'queued',
+        ...(attachmentIds.length ? { attachments: attachmentIds } : {}), channel: result.channel,
+        ...(result.channelError ? { channelError: result.channelError } : {}),
+      };
+      try { persistOutcome(path, item, deps.append ?? append); }
+      catch { return unavailable(); }
+      return receipt(item);
+    }
     let result: Awaited<ReturnType<typeof submitIntakeWork>>;
     try {
       result = await (deps.submit ?? submitIntakeWork)({
@@ -241,7 +320,8 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
       catch { return unavailable(); }
       return unavailable();
     }
-    const item: RecordEntry & SeatRequestItem = { key, receiptId: result.acceptanceId, seat: seat.id, text, queuedAt: intent.queuedAt, status: 'queued' };
+    const item: RecordEntry & SeatRequestItem = { key, receiptId: result.acceptanceId, seat: seat.id, text, queuedAt: intent.queuedAt,
+      status: 'queued', ...(attachmentIds.length ? { attachments: attachmentIds } : {}) };
     try { persistOutcome(path, item, deps.append ?? append); }
     catch { return unavailable(); }
     debug.log('seat-address.pwa', 'enqueued', { seat: seat.id, receiptId: item.receiptId });

package/src/nexus/api/sessions-store.ts

@@ -18,6 +18,11 @@ import {
   isHarnessSessionOrigin,
   type SessionMeta,
 } from '../../session/index.js';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getProject } from '../../project/project-store.js';
+import { sessionRoot } from '../../session/index.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './http-server.js';
 
@@ -32,6 +37,7 @@ export interface SessionStoreCard {
    *  `harness` = 하니스 자식이 만든 세션. 기본 목록에서 숨기고 includeHarness=1 로 포함. */
   origin?: string;
   sourceKind?: string;
+  projectId?: string;
   createdAt: string;
   updatedAt: string;
   messageCount: number;
@@ -50,6 +56,7 @@ function toCard(m: SessionMeta, preview: string, nowMs: number): SessionStoreCar
     source: m.source,
     ...(m.origin ? { origin: m.origin } : {}),
     ...(m.sourceKind ? { sourceKind: m.sourceKind } : {}),
+    ...(m.projectId !== undefined ? { projectId: m.projectId } : {}),
     createdAt: m.createdAt,
     updatedAt: m.updatedAt,
     messageCount: m.messageCount,
@@ -82,11 +89,13 @@ export function handleSessionsStoreList(req: Request, opts: MetaApiOpts): Respon
   // 하니스 자식 세션(origin:'harness')은 기본 숨김 — includeHarness=1 로 포함.
   // 신분이 없는 옛 세션은 사람 대화로 본다(숨기지 않음). 제목 문면으로 판정하지 않는다.
   const includeHarness = url.searchParams.get('includeHarness') === '1';
+  const projectId = url.searchParams.get('projectId');
   const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 300);
   const nowMs = Date.now();
 
   let metas = listSessions({
     limit: 600,
+    ...(projectId !== null ? { projectId } : {}),
     ...(includeOperational ? {} : { excludeSourceKinds: ['scheduled'] }),
     ...(includeHarness ? {} : { excludeOrigins: [HARNESS_SESSION_ORIGIN] }),
   }); // 이미 updatedAt DESC
@@ -157,6 +166,60 @@ export async function handleSessionsStoreFork(
   );
 }
 
+/** PATCH /v1/sessions/store/:id — only project membership; leave transcript and other meta untouched. */
+export async function handleSessionsStorePatch(req: Request, id: string, opts: MetaApiOpts): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!id || id.includes('/') || id.includes('\\') || id.includes('..')) {
+    return jsonResponse({ ok: false, error: 'invalid_session_id' }, 400);
+  }
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ ok: false, error: 'invalid_json' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)
+    || !Object.hasOwn(body, 'projectId')
+    || Object.keys(body).some((key) => key !== 'projectId')) {
+    return jsonResponse({ ok: false, error: 'invalid_project_id' }, 400);
+  }
+  const projectId = (body as { projectId: unknown }).projectId;
+  if (projectId !== null && (typeof projectId !== 'string' || !getProject(projectId))) {
+    return jsonResponse({ ok: false, error: 'invalid_project_id' }, 400);
+  }
+
+  const root = sessionRoot();
+  const lock = join(root, '.index.lock');
+  const deadline = Date.now() + 10_000;
+  for (;;) {
+    try { mkdirSync(lock); break; }
+    catch {
+      if (!existsSync(lock)) continue;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > 30_000) { rmdirSync(lock); continue; }
+      } catch { continue; }
+      if (Date.now() >= deadline) throw new Error(`timed out acquiring lock ${lock}`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  try {
+    const path = join(root, 'index.json');
+    const entries = JSON.parse(readFileSync(path, 'utf8')) as SessionMeta[];
+    const pos = entries.findIndex((meta) => meta.id === id);
+    if (pos < 0) return jsonResponse({ ok: false, error: 'not_found' }, 404);
+    const meta = { ...entries[pos] };
+    if (projectId === null) delete meta.projectId;
+    else meta.projectId = projectId;
+    entries[pos] = meta;
+    const temp = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    writeFileSync(temp, JSON.stringify(entries, null, 2) + '\n', 'utf8');
+    renameSync(temp, path);
+    return jsonResponse({ ok: true, meta }, 200);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return jsonResponse({ ok: false, error: 'not_found' }, 404);
+    throw error;
+  } finally {
+    rmdirSync(lock);
+  }
+}
+
 /** DELETE /v1/sessions/store/:id — on-disk 세션 삭제(index.json + <id>.jsonl 제거).
  *  파괴적·복구불가. in-flight turn abort + in-memory history forget 도 fail-soft 로 동반. */
 export function handleSessionsStoreDelete(req: Request, id: string, opts: MetaApiOpts): Response {

package/src/nexus/api/setup-claim.ts

@@ -0,0 +1,21 @@
+import { claimSetupLinkToken } from '../../auth/setup-link-tokens.js';
+import { jsonResponse } from './json-response.js';
+
+/** A setup link is its own credential; this handler never reads the owner bearer. */
+export async function handleSetupClaim(req: Request): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body)
+    || typeof (body as Record<string, unknown>).t !== 'string'
+    || !(body as { t: string }).t.trim()) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+
+  const result = claimSetupLinkToken((body as { t: string }).t);
+  if (!result.ok) return jsonResponse({ error: result.reason }, 401);
+  return jsonResponse({ scope: 'setup', bearer: result.bearer, expiresAt: result.expiresAt });
+}

package/src/nexus/api/setup-codex-login.ts

@@ -0,0 +1,160 @@
+import { debug } from '../../debug/log.js';
+import { loginWithCodexBrowser } from '../../oauth/codex-browser-login.js';
+import {
+  CODEX_DEVICE_LOGIN_URL,
+  exchangeDeviceAuthCode,
+  pollDeviceCode,
+  requestDeviceCode,
+} from '../../oauth/codex.js';
+import { expiresAtFromSeconds, saveTokens } from '../../oauth/store.js';
+import { getUserConfig, reloadUserConfig, saveUserConfig } from '../../user-config.js';
+
+type Mode = 'browser' | 'device';
+type CodexLoginStatus =
+  | { state: 'idle' }
+  | { state: 'pending'; mode: Mode; authorizeUrl?: string; userCode?: string; verificationUrl?: string }
+  | { state: 'ok'; mode: Mode }
+  | { state: 'error'; mode: Mode; error: string };
+
+const TIMEOUT_MS = 5 * 60_000;
+const SAFE_ERRORS = [
+  'timeout', 'authorization-denied', 'browser-unavailable', 'port-unavailable',
+  'token-exchange', 'device-code-failed', 'device-poll-failed', 'config-save-failed',
+] as const;
+
+type Failure = typeof SAFE_ERRORS[number];
+function reason(error: unknown, mode: Mode): Failure {
+  const message = error instanceof Error ? error.message : '';
+  for (const value of SAFE_ERRORS) if (message === value || message === `codex browser login failed: ${value}`) return value;
+  return mode === 'browser' ? 'browser-unavailable' : 'device-poll-failed';
+}
+
+interface LoginDeps {
+  browser: (openBrowser: (url: string) => boolean) => Promise<unknown>;
+  device: (ready: (userCode: string, verificationUrl: string) => void) => Promise<unknown>;
+  saveProvider: () => void;
+  observe: (event: 'started' | 'ok' | 'error', mode: Mode) => void;
+}
+
+async function deviceLogin(ready: (userCode: string, verificationUrl: string) => void): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  const fetchImpl = ((input, init) => fetch(input, { ...init, signal: controller.signal })) as typeof fetch;
+  try {
+    let code: Awaited<ReturnType<typeof requestDeviceCode>>;
+    try { code = await requestDeviceCode({ fetchImpl }); }
+    catch { throw new Error('device-code-failed'); }
+    if (controller.signal.aborted) throw new Error('timeout');
+    ready(code.user_code, code.verification_uri || CODEX_DEVICE_LOGIN_URL);
+    const interval = Math.max(3000, (code.interval ?? 0) * 1000);
+    const deadline = Date.now() + TIMEOUT_MS;
+    while (!controller.signal.aborted && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+      if (controller.signal.aborted || Date.now() >= deadline) break;
+      let result: Awaited<ReturnType<typeof pollDeviceCode>>;
+      try { result = await pollDeviceCode(code.device_auth_id, code.user_code, { fetchImpl }); }
+      catch { throw new Error('device-poll-failed'); }
+      if (!result) continue;
+      let token: Awaited<ReturnType<typeof exchangeDeviceAuthCode>>;
+      try { token = await exchangeDeviceAuthCode(result.authorization_code, result.code_verifier, { fetchImpl }); }
+      catch { throw new Error('token-exchange'); }
+      if (controller.signal.aborted) break;
+      saveTokens('openai-codex', {
+        accessToken: token.access_token,
+        refreshToken: token.refresh_token,
+        ...(token.id_token ? { idToken: token.id_token } : {}),
+        expiresAt: expiresAtFromSeconds(token.expires_in),
+        scope: token.scope,
+        tokenType: token.token_type ?? 'Bearer',
+      }, { authMode: 'chatgpt' });
+      return;
+    }
+    throw new Error('timeout');
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error('timeout');
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function saveCodexProvider(): void {
+  const cur = getUserConfig();
+  saveUserConfig({ ...cur, llm: { ...cur.llm, provider: 'openai-codex', apiKey: undefined, baseUrl: undefined, model: undefined } });
+  reloadUserConfig();
+}
+
+const defaultDeps: LoginDeps = {
+  browser: (openBrowser) => loginWithCodexBrowser({ openBrowser, timeoutMs: TIMEOUT_MS }),
+  device: deviceLogin,
+  saveProvider: saveCodexProvider,
+  observe: (event, mode) => { debug.log('setup.codex-login', event, { mode }); },
+};
+
+function json(body: CodexLoginStatus | { error: string }, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status, headers: { 'content-type': 'application/json; charset=utf-8', 'access-control-allow-origin': '*' },
+  });
+}
+
+/** One in-process login survives leaving or reloading the setup page. */
+export function createCodexLoginHandlers(deps: LoginDeps = defaultDeps) {
+  let status: CodexLoginStatus = { state: 'idle' };
+  let preparing: Promise<void> | undefined;
+  let generation = 0;
+
+  const get = (): Response => json(status);
+
+  const post = async (req: Request): Promise<Response> => {
+    let body: unknown;
+    try { body = await req.json(); } catch { return json({ error: 'invalid-json' }, 400); }
+    const mode = body && typeof body === 'object' && 'mode' in body ? body.mode : undefined;
+    if (mode !== 'browser' && mode !== 'device') return json({ error: 'invalid-mode' }, 400);
+    // Same method again → the login already in flight. A different method → start over; the older
+    // attempt's result is ignored (generation). Browser → device is the recovery path when a popup
+    // was blocked; device needs no local port, so it never collides with the browser's callback server.
+    if (status.state === 'pending' && status.mode === mode) {
+      if (preparing) await preparing;
+      return json(status);
+    }
+
+    status = { state: 'pending', mode };
+    const attempt = ++generation;
+    deps.observe('started', mode);
+    let resolveReady!: () => void;
+    preparing = new Promise<void>((resolve) => { resolveReady = resolve; });
+    const ready = (fields: Pick<Extract<CodexLoginStatus, { state: 'pending' }>, 'authorizeUrl' | 'userCode' | 'verificationUrl'>) => {
+      if (generation === attempt && status.state === 'pending' && status.mode === mode) {
+        status = { ...status, ...fields };
+        resolveReady();
+      }
+    };
+    void (async () => {
+      try {
+        if (mode === 'browser') {
+          await deps.browser((url) => { ready({ authorizeUrl: url }); return true; });
+        } else {
+          await deps.device((userCode, verificationUrl) => ready({ userCode, verificationUrl }));
+        }
+        if (generation !== attempt) return;
+        try { deps.saveProvider(); } catch { throw new Error('config-save-failed'); }
+        status = { state: 'ok', mode };
+        deps.observe('ok', mode);
+      } catch (error) {
+        if (generation !== attempt) return;
+        status = { state: 'error', mode, error: reason(error, mode) };
+        deps.observe('error', mode);
+      } finally {
+        resolveReady();
+        if (generation === attempt) preparing = undefined;
+      }
+    })();
+    await preparing;
+    return json(status);
+  };
+  return { get, post };
+}
+
+const login = createCodexLoginHandlers();
+export const handleSetupCodexLoginGet = login.get;
+export const handleSetupCodexLoginPost = login.post;