elanous 0.2.9 → 0.2.10

package/src/onboarding/web-first.ts

@@ -1,62 +1,150 @@
 import { spawnSync } from 'node:child_process';
+import { hostname, networkInterfaces, userInfo } from 'node:os';
+import { findNexusLifecycleState } from '../nexus/supervisor/lock.js';
+import { isLanReachableBind, isPrivateIpv4, pickLanAddress } from './lan-address.js';
 import { isHeadlessEnv } from '../acp/codex-auth.js';
-import { runNexusShow, type NexusShowResult } from '../cli/nexus-show.js';
+import { runBgLaunch, type BgLaunchResult } from '../cli/bg-launch.js';
+import { joinRestHealthUrl, runNexusShow, type NexusShowResult } from '../cli/nexus-show.js';
+import { issueSetupLinkToken } from '../auth/setup-link-tokens.js';
 import { debug } from '../debug/log.js';
 import { browserUnavailableReason } from '../oauth/browser-availability.js';
 import type { UserConfig } from '../user-config.js';
 
 export interface WebFirstSetupDeps {
   config: Pick<UserConfig, 'onboarding'>;
+  /** Whether a person is at a terminal (stdin TTY). Without one the web path only uses a daemon that is already up. */
   isTty?: boolean;
   terminal?: boolean;
+  startedAt?: number;
   showNexus?: () => Promise<NexusShowResult>;
+  startDaemon?: () => Promise<BgLaunchResult>;
+  probeHealth?: (url: string, timeoutMs: number) => Promise<boolean>;
   issueSetupLinkToken?: () => Promise<string | { token: string }>;
   renderQr?: (link: string) => string | undefined;
   openBrowser?: (link: string) => boolean;
   isHeadless?: () => boolean;
   browserEnv?: NodeJS.ProcessEnv;
   browserPlatform?: NodeJS.Platform;
+  httpHost?: () => string | undefined;
+  interfaces?: typeof networkInterfaces;
+  defaultRouteInterface?: () => string | undefined;
+  hostname?: typeof hostname;
+  username?: () => string;
   print?: (line: string) => void;
 }
 
+const STARTUP_TIMEOUT_MS = 12_000;
+
+async function probeHealth(url: string, timeoutMs: number): Promise<boolean> {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
 function setupUrl(pwa: string, token: string): string {
   return `${pwa.replace(/\/app\/?$/, '').replace(/\/$/, '')}/setup#t=${encodeURIComponent(token)}`;
 }
 
 export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-shown' | 'fallback'> {
-  const observe = (event: 'link-shown' | 'fallback', reason?: string, qr = false, browserOpened = false, remote: 'loopback' | 'tailnet' = 'loopback') => {
-    try { debug.log('onboarding.web-first', event, { ...(reason ? { reason } : {}), qr, browserOpened, remote }); }
+  const startedAt = deps.startedAt ?? Date.now();
+  const print = deps.print ?? console.log;
+  const observe = (event: 'link-shown' | 'fallback', reason?: string, qr = false, browserOpened = false, remote: 'loopback' | 'tailnet' = 'loopback', ms?: number, lan?: 'shown' | 'loopback-bind' | 'no-address', ssh?: boolean) => {
+    try { debug.log('onboarding.web-first', event, { ...(reason ? { reason } : {}), qr, browserOpened, remote, ...(ms !== undefined ? { ms } : {}), ...(lan ? { lan, ssh } : {}) }); }
     catch { /* Observability must not block onboarding. */ }
   };
-  if (deps.config.onboarding.webFirst !== true) { observe('fallback', 'disabled'); return 'fallback'; }
-  if ((deps.isTty ?? (process.stdin.isTTY === true)) !== true) { observe('fallback', 'non-tty'); return 'fallback'; }
+  const fallback = (reason: string): 'fallback' => {
+    print(`웹 셋업을 사용할 수 없습니다 (${reason}). 터미널 설정으로 전환합니다.`);
+    observe('fallback', reason);
+    return 'fallback';
+  };
+  if (deps.config.onboarding.webFirst === false) { observe('fallback', 'disabled'); return 'fallback'; }
   if (deps.terminal) { observe('fallback', 'terminal'); return 'fallback'; }
 
-  let shown: NexusShowResult;
-  try {
-    shown = await (deps.showNexus ?? (() => runNexusShow({ format: 'json', out: { log: () => {}, error: () => {} } })))();
-  } catch { observe('fallback', 'daemon-unavailable'); return 'fallback'; }
-  const running = shown.status === 'unregistered' || (shown.status === 'registered' && shown.instance?.alive === true);
-  if (!running || !shown.urls?.pwa.loopback) { observe('fallback', 'daemon-unavailable'); return 'fallback'; }
+  const show = deps.showNexus ?? (() => runNexusShow({ format: 'json', out: { log: () => {}, error: () => {} } }));
+  let shown: NexusShowResult | undefined;
+  try { shown = await show(); } catch { /* A missing daemon may make inspection fail. */ }
+  const running = shown?.status === 'unregistered' || (shown?.status === 'registered' && shown.instance?.alive === true);
+  // A script, pipe or CI run never starts a daemon on its own: without a terminal the web path
+  // only uses a daemon that already answers health once. (install.sh runs first setup with
+  // stdin on /dev/tty, so the install → web path still starts one.)
+  if ((deps.isTty ?? (process.stdin.isTTY === true)) !== true) {
+    const rest = running ? shown?.urls?.rest.loopback : undefined;
+    const up = rest && shown?.urls?.pwa.loopback
+      ? await (deps.probeHealth ?? probeHealth)(joinRestHealthUrl(rest), 500) : false;
+    if (!up) { observe('fallback', 'non-tty'); return 'fallback'; }
+  }
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  if (!running || !shown?.urls?.pwa.loopback) {
+    let launch: BgLaunchResult;
+    try {
+      launch = await (deps.startDaemon ?? (() => runBgLaunch({ out: { log: () => {}, error: () => {} } })))();
+    } catch { return fallback('daemon-start-failed'); }
+    if (launch.exitCode !== 0) return fallback('daemon-start-failed');
+  }
+
+  let healthy = false;
+  while (Date.now() < deadline) {
+    try {
+      shown = await show();
+      const live = shown.status === 'unregistered' || (shown.status === 'registered' && shown.instance?.alive === true);
+      if (live && shown.urls?.pwa.loopback && shown.urls.rest.loopback) {
+        const remaining = deadline - Date.now();
+        if (remaining > 0 && await (deps.probeHealth ?? probeHealth)(joinRestHealthUrl(shown.urls.rest.loopback), Math.min(remaining, 500))) {
+          healthy = true;
+          break;
+        }
+      }
+    } catch { /* A daemon may not have published its URLs yet. */ }
+    const remaining = deadline - Date.now();
+    if (remaining > 0) await Bun.sleep(Math.min(200, remaining));
+  }
+  if (!healthy) return fallback(running ? 'daemon-health-unavailable' : 'daemon-health-timeout');
+
+  if (!shown?.urls?.pwa.loopback) return fallback('daemon-unavailable');
 
   let token: string;
   try {
-    const issue = deps.issueSetupLinkToken ?? (async () => {
-      const modulePath = '../auth/setup-link-token.js';
-      const mod = await import(modulePath) as { issueSetupLinkToken?: (options: Record<string, never>) => Promise<string | { token: string }> };
-      if (typeof mod.issueSetupLinkToken !== 'function') throw new Error('issuer-missing');
-      return mod.issueSetupLinkToken({});
-    });
-    const issued = await issue();
+    const issued = await (deps.issueSetupLinkToken ?? (() => Promise.resolve(issueSetupLinkToken({}))))();
     token = typeof issued === 'string' ? issued : issued?.token;
     if (!token) throw new Error('issuer-missing');
-  } catch { observe('fallback', 'issuer-missing'); return 'fallback'; }
+  } catch { return fallback('issuer-missing'); }
 
-  const print = deps.print ?? console.log;
   const link = setupUrl(shown.urls.pwa.loopback, token);
-  const phoneLink = shown.urls.pwa.tailnet ? setupUrl(shown.urls.pwa.tailnet, token) : undefined;
+  const localUrl = new URL(shown.urls.pwa.loopback);
+  const port = localUrl.port || (localUrl.protocol === 'https:' ? '443' : '80');
+  let httpHost: string | undefined;
+  try { httpHost = (deps.httpHost ?? (() => findNexusLifecycleState()?.runtime?.httpHost))(); }
+  catch { /* Unknown bind must not produce a LAN link. */ }
+  const confirmedBind = typeof httpHost === 'string';
+  const reachable = confirmedBind && isLanReachableBind(httpHost);
+  let lanAddress: string | null = null;
+  if (reachable && httpHost !== undefined) {
+    if (isPrivateIpv4(httpHost.trim())) {
+      lanAddress = httpHost.trim();
+    } else {
+      try {
+        lanAddress = pickLanAddress({
+          interfaces: (deps.interfaces ?? networkInterfaces)(),
+          defaultRouteInterface: deps.defaultRouteInterface,
+        });
+      } catch { /* Optional LAN discovery must not block the local setup link. */ }
+    }
+  }
+  const lan: 'shown' | 'loopback-bind' | 'no-address' = !confirmedBind ? 'no-address' : !reachable ? 'loopback-bind' : lanAddress ? 'shown' : 'no-address';
+  const lanLink = lanAddress ? setupUrl(`http://${lanAddress}:${port}/app/`, token) : undefined;
+  const phoneLink = shown.urls.pwa.tailnet ? setupUrl(shown.urls.pwa.tailnet, token) : lanLink;
   print('브라우저에서 셋업을 이어가세요');
   print(link);
+  if (lanLink) {
+    print(`같은 와이파이의 폰이면: ${lanLink}`);
+    print('이 링크는 10분 안에 한 번만 열 수 있습니다');
+  } else if (lan === 'loopback-bind') {
+    print('같은 와이파이에서 열려면 `elanous nexus run` 을 루프백 없이 다시 띄우세요');
+  }
+  const linkShownMs = Date.now() - startedAt;
   let qr = false;
   if (phoneLink) {
     try {
@@ -66,14 +154,16 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
       }))(phoneLink);
       if (rendered) {
         print(rendered);
-        print('같은 와이파이·tailnet 의 폰 카메라로 스캔하세요');
+        print(shown.urls.pwa.tailnet ? '같은 와이파이·tailnet 의 폰 카메라로 스캔하세요' : '같은 와이파이의 폰 카메라로 스캔하세요');
         qr = true;
       }
     } catch { /* QR is optional. */ }
   }
   print('터미널에서 하려면: `elanous setup --terminal`');
   let browserOpened = false;
-  const why = browserUnavailableReason(deps.browserEnv ?? process.env, deps.browserPlatform ?? process.platform);
+  const env = deps.browserEnv ?? process.env;
+  const ssh = !!(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+  const why = browserUnavailableReason(env, deps.browserPlatform ?? process.platform);
   if (why) {
     print(why);
     debug.log('browser.open', 'skipped', { reason: why.includes('ssh') ? 'ssh' : 'no-display' });
@@ -85,6 +175,11 @@ export async function runWebFirstSetup(deps: WebFirstSetupDeps): Promise<'link-s
       }))(link);
     } catch { /* The displayed link remains usable. */ }
   }
-  observe('link-shown', undefined, qr, browserOpened, phoneLink ? 'tailnet' : 'loopback');
+  if (ssh) {
+    try {
+      print(`ssh -L ${port}:localhost:${port} ${(deps.username ?? (() => userInfo().username))()}@${(deps.hostname ?? hostname)()}`);
+    } catch { /* Optional SSH guidance must not block the setup link. */ }
+  }
+  observe('link-shown', undefined, qr, browserOpened, shown.urls.pwa.tailnet ? 'tailnet' : 'loopback', linkShownMs, lan, ssh);
   return 'link-shown';
 }

package/src/onboarding.ts

@@ -1656,6 +1656,10 @@ export function needsOnboarding(cfg: UserConfig): boolean {
   return !cfg.onboarding.completed;
 }
 
+export function needsFirstRun(cfg: UserConfig): boolean {
+  return !cfg.onboarding.completed && cfg.onboarding.ready !== true;
+}
+
 /** γ (2026-04-28) · per-step wizard. Runs ONE of the 5 steps,
  *  preserving every other field. Used by:
  *

package/src/ops-now/ops-now-refresh.ts

@@ -0,0 +1,100 @@
+import { debug } from '../debug/log.js';
+import { listMemories, makeMemoryJudge, memoryRoot, saveMemory } from '../memory.js';
+
+export interface OpsNowComment { body: string; createdAt: string; url: string }
+export interface OpsNowDeps {
+  listComments?: (sinceIso: string) => Promise<OpsNowComment[] | null>;
+  summarize?: (prompt: string) => Promise<string>;
+  now?: () => Date;
+  root?: string;
+  dryRun?: boolean;
+}
+export interface OpsNowResult {
+  outcome: 'updated' | 'unchanged' | 'no-notices' | 'summarize-failed' | 'channel-unreadable';
+  notices: number;
+  memoryId?: string;
+  /** Only populated for dry-run, so callers can inspect the proposed write. */
+  body?: string;
+}
+
+const HEADER = /^갱신: [^\n]* · 출처 글 \d+개\n/;
+const CITED_ITEM = /^- .+ \(출처: (https?:\/\/[^\s)]+)\)$/;
+
+function citedItems(body: string): string[] | null {
+  const lines = body.trim().split('\n').filter((line) => line.trim());
+  if (!lines.length) return null;
+  const sources: string[] = [];
+  for (const line of lines) {
+    const match = CITED_ITEM.exec(line);
+    if (!match || line.match(/\(출처:/g)?.length !== 1) return null;
+    sources.push(match[1]!);
+  }
+  return sources;
+}
+
+function channelIssue(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === 'github.com' && /^\/[^/]+\/[^/]+\/(?:issues|pull)\/\d+$/.test(parsed.pathname) &&
+      /^#issuecomment-\d+$/.test(parsed.hash) ? `${parsed.origin}${parsed.pathname}` : null;
+  } catch { return null; }
+}
+
+export async function refreshOpsNow(deps: OpsNowDeps = {}): Promise<OpsNowResult> {
+  const now = (deps.now ?? (() => new Date()))();
+  const root = deps.root ?? memoryRoot();
+  const finish = (outcome: OpsNowResult['outcome'], notices: number, chars: number, memoryId?: string, body?: string): OpsNowResult => {
+    debug.log('ops-now.refresh', outcome, { notices, chars });
+    return { outcome, notices, ...(memoryId ? { memoryId } : {}), ...(body !== undefined ? { body } : {}) };
+  };
+  let comments: OpsNowComment[] | null;
+  try {
+    const listComments = deps.listComments ?? (await import('../nexus/api/ops-seats-sources.js')).channelCommentsSince;
+    comments = await listComments(new Date(now.getTime() - 86_400_000).toISOString());
+  } catch {
+    comments = null;
+  }
+  if (!comments) return finish('channel-unreadable', 0, 0);
+  const notices = comments.filter((c) => c.body.includes('📌안내') &&
+    Number.isFinite(Date.parse(c.createdAt)) && Date.parse(c.createdAt) >= now.getTime() - 86_400_000 && Date.parse(c.createdAt) <= now.getTime())
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  if (!notices.length) return finish('no-notices', 0, 0);
+
+  const existing = listMemories({}, root).find((m) => m.name === 'ops-now');
+  const oldBody = existing?.body.trim() ?? '';
+  const issue = channelIssue(notices[0]!.url);
+  const oldSources = (issue ? oldBody.replace(HEADER, '').split('\n').map((line) => CITED_ITEM.exec(line)?.[1]) : [])
+    .filter((url): url is string => !!url && channelIssue(url) === issue);
+  const allowedSources = new Set([...notices.map((c) => c.url), ...oldSources]);
+  const prompt = [
+    '너는 봇의 ops-now 고정 기억을 diff 갱신한다. 기존 본문과 채널 📌안내 글을 대조해 지금 유효한 안내만 한국어로 반환한다.',
+    '새 글의 정정이 앞 글과 충돌하면 새 글이 이긴다. 이미 유효한 기존 안내는 유지하되 낡거나 정정된 안내는 제거한다.',
+    '각 항목은 한 줄의 "- 안내 (출처: <코멘트 URL>)" 꼴로 쓰고 다른 문장은 출력하지 않는다. 출처는 아래 새 글 URL 또는 기존 본문의 검증 가능한 채널 URL만 사용한다. 출처가 확인되지 않는 항목은 쓰지 않는다.',
+    '비밀 값·토큰·개인 메모·계정 이름은 옮기지 않는다.',
+    '본문만 출력한다. 갱신 시각 헤더는 출력하지 않는다. 2,000자 이하.',
+    '## 기존 ops-now 본문', oldBody || '(없음)', '## 📌안내 (오래된 글 → 새로운 글)',
+    ...notices.map((c) => {
+      const seat = /^\s*\*\*\[(OP|MK|TC|UX)\]\*/.exec(c.body)?.[1] ?? '미상';
+      return `시각: ${c.createdAt} · 자리: ${seat} · URL: ${c.url}\n${c.body.slice(0, 1500)}`;
+    }),
+  ].join('\n\n');
+  let summary: string;
+  try {
+    summary = (await (deps.summarize ?? makeMemoryJudge())(prompt)).trim().replace(HEADER, '').trim();
+    const sources = citedItems(summary);
+    if (!sources || sources.some((url) => !allowedSources.has(url)) ||
+      `갱신: ${now.toISOString()} · 출처 글 ${notices.length}개\n${summary}`.length > 2000) throw new Error('invalid summary');
+  } catch {
+    return finish('summarize-failed', notices.length, 0, existing?.id);
+  }
+  if (summary === oldBody.replace(HEADER, '').trim() && existing?.pinned && existing.staleAfterMinutes === 120) {
+    return finish('unchanged', notices.length, summary.length, existing.id, deps.dryRun ? existing.body.trimStart() : undefined);
+  }
+  const body = `갱신: ${now.toISOString()} · 출처 글 ${notices.length}개\n${summary}`;
+  if (deps.dryRun) return finish('updated', notices.length, body.length, existing?.id, body);
+  const saved = saveMemory({
+    type: 'project', name: 'ops-now', description: existing?.description ?? '지금 운영 상태 — 채널 📌안내 갱신',
+    body, id: existing?.id, priority: existing?.priority, pinned: true, staleAfterMinutes: 120,
+  }, root);
+  return finish('updated', notices.length, body.length, saved.id);
+}

package/src/project/project-store.ts

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { parse, stringify } from 'yaml';
+import { debug } from '../debug/log.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
+export interface Project {
+  id: string;
+  name: string;
+  primaryFolder?: string;
+  createdAt: string;
+}
+
+const PROJECT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function validId(id: unknown): id is string {
+  return typeof id === 'string' && PROJECT_ID.test(id);
+}
+
+function validateProject(value: unknown): Project {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid project record');
+  const item = value as Record<string, unknown>;
+  if (!validId(item.id) || typeof item.name !== 'string' || !item.name.trim() || item.name.length > 80
+    || typeof item.createdAt !== 'string' || !Number.isFinite(Date.parse(item.createdAt))
+    || (item.primaryFolder !== undefined && (typeof item.primaryFolder !== 'string' || !isAbsolute(item.primaryFolder)))) {
+    throw new Error('invalid project record');
+  }
+  return value as Project;
+}
+
+export class ProjectStore {
+  readonly dir: string;
+
+  constructor(configRoot = getElanousConfigDir()) {
+    this.dir = join(configRoot, 'projects');
+  }
+
+  create(input: { name: string; primaryFolder?: string }): Project {
+    const item = validateProject({ id: randomUUID(), name: input.name, createdAt: new Date().toISOString(),
+      ...(input.primaryFolder !== undefined ? { primaryFolder: input.primaryFolder } : {}) });
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    const target = join(this.dir, `${item.id}.yaml`);
+    const temp = join(this.dir, `.${item.id}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temp, stringify(item), { flag: 'wx', mode: 0o600 });
+      // Link publishes a complete file without replacing an existing project.
+      linkSync(temp, target);
+    } finally {
+      try { unlinkSync(temp); } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+    return item;
+  }
+
+  get(id: string): Project | null {
+    if (!validId(id)) return null;
+    let text: string;
+    try { text = readFileSync(join(this.dir, `${id}.yaml`), 'utf8'); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw error;
+    }
+    const item = validateProject(parse(text) as unknown);
+    if (item.id !== id) throw new Error('project id does not match filename');
+    return item;
+  }
+
+  list(): Project[] {
+    let files: string[];
+    try { files = readdirSync(this.dir); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+    return files.filter(file => PROJECT_ID.test(file.slice(0, -5)) && file.endsWith('.yaml'))
+      .flatMap(file => { const item = this.get(file.slice(0, -5)); return item ? [item] : []; })
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || a.id.localeCompare(b.id));
+  }
+
+  suggestForFolder(folder: string): Project | null {
+    if (!isAbsolute(folder)) throw new Error('folder must be absolute');
+    // Compare real paths: macOS reports cwd as /private/var/… for a folder stored as /var/… (symlinked roots).
+    const real = (path: string): string => { try { return realpathSync(path); } catch { return resolve(path); } };
+    const cwd = real(folder);
+    let best: Project | null = null;
+    let bestLength = -1;
+    for (const item of this.list()) {
+      if (!item.primaryFolder) continue;
+      const base = real(item.primaryFolder);
+      const rel = relative(base, cwd);
+      if (rel !== '' && (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))) continue;
+      if (base.length > bestLength) { best = item; bestLength = base.length; }
+    }
+    debug.log('project.suggestion', 'checked', { matched: best !== null });
+    return best;
+  }
+}
+
+export function createProject(input: { name: string; primaryFolder?: string }): Project {
+  return new ProjectStore().create(input);
+}
+
+export function listProjects(): Project[] {
+  return new ProjectStore().list();
+}
+
+export function getProject(id: string): Project | null {
+  return new ProjectStore().get(id);
+}
+
+export function suggestProjectForFolder(folder: string): Project | null {
+  return new ProjectStore().suggestForFolder(folder);
+}

package/src/release-loop/checklist.ts

@@ -28,6 +28,7 @@ export interface ChecklistHistory {
   to: unknown;
   released: string;
   dev: string;
+  force?: true;
 }
 export interface Checklist {
   version: string;
@@ -41,12 +42,44 @@ export function devVersion(): string {
   return (JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version: string }).version;
 }
 
+export function parseOwner(value: string): { seat: string; sub?: string } {
+  const match = /^([A-Z]{2,8})(?:\/([a-z][a-z0-9-]{0,31}))?$/.exec(value);
+  if (!match || match[0] !== value) throw new CliUserError(`잘못된 담당: ${value}`, 'TC 또는 TC/rel');
+  return match[2] ? { seat: match[1]!, sub: match[2] } : { seat: match[1]! };
+}
+
+export function ownerMatches(owner: string | undefined, filter: string): boolean {
+  if (owner === undefined) return false;
+  try {
+    const parsed = parseOwner(owner);
+    const requested = parseOwner(filter);
+    return parsed.seat === requested.seat && (requested.sub === undefined || parsed.sub === requested.sub);
+  } catch { return false; }
+}
+
+// The ledger event schema has no force column; decode its claim target for every checklist snapshot.
+export function decodeClaimHistoryEntry<T extends ChecklistHistory>(entry: T): T {
+  if (entry.field !== 'claim' || !entry.to || typeof entry.to !== 'object') return entry;
+  const target = entry.to as { owner?: unknown; force?: unknown };
+  return typeof target.owner === 'string' && target.force === true ? { ...entry, to: target.owner, force: true } as T : entry;
+}
+
+function decodeClaimHistory(data: Checklist): Checklist {
+  return { ...data, history: data.history.map(decodeClaimHistoryEntry) };
+}
+
 export function listChecklist(v: string): Checklist {
-  return store.list(v);
+  return decodeClaimHistory(store.list(v));
+}
+
+/** Status events in the requested window; other ledger fields never become status changes. */
+export function statusChangesSince(history: readonly ChecklistHistory[], sinceIso: string): ChecklistHistory[] {
+  const since = Date.parse(sinceIso);
+  return history.filter((entry) => entry.field === 'status' && Date.parse(entry.at) >= since);
 }
 
 function mutate(v: string, apply: (data: Checklist) => boolean): Checklist {
-  return store.mutate(v, store.releasedVersion(), devVersion(), apply);
+  return decodeClaimHistory(store.mutate(v, store.releasedVersion(), devVersion(), apply));
 }
 
 function change(data: Checklist, id: string, field: string, from: unknown, to: unknown, by: string, at: string): void {
@@ -58,6 +91,7 @@ export function addItem(v: string, input: { id: string; title: string; owner?: s
   if (!input.id.trim()) throw new CliUserError('칸 id 가 비었다');
   if (!input.title.trim()) throw new CliUserError('칸 제목이 비었다');
   if (input.kind !== undefined && input.kind !== 'screen') throw new CliUserError(`잘못된 종류: ${input.kind}`, 'screen');
+  if (input.owner !== undefined) parseOwner(input.owner);
   return mutate(v, (data) => {
     if (data.items.some((item) => item.id === input.id)) throw new CliUserError(`이미 있는 칸: ${input.id}`, 'set <id> 로 고친다');
     const by = process.env.ELANOUS_TRACK || 'cli';
@@ -76,6 +110,12 @@ export function setItem(v: string, id: string, patch: { status?: ChecklistStatus
     if (patch.status !== undefined && !['green', 'yellow', 'red', 'done'].includes(patch.status)) throw new CliUserError(`잘못된 상태: ${patch.status}`);
     if (patch.disposition !== undefined && !['move', 'known-issue', 'block'].includes(patch.disposition)) throw new CliUserError(`잘못된 처분: ${patch.disposition}`);
     if (patch.kind !== undefined && patch.kind !== 'screen') throw new CliUserError(`잘못된 종류: ${patch.kind}`, 'screen');
+    if (patch.owner !== undefined) {
+      parseOwner(patch.owner);
+      if (item.owner && patch.owner !== item.owner) {
+        throw new CliUserError(`지금 주인: ${item.owner} — --force 로만 바꾼다`, 'release checklist claim <id> --by <자리> --force');
+      }
+    }
     const fields = (['evidence', 'owner', 'status', 'disposition', 'kind'] as const).filter((field) => patch[field] !== undefined && patch[field] !== item[field]);
     if (fields.length === 0) return false;
     const at = new Date().toISOString();
@@ -91,6 +131,34 @@ export function setItem(v: string, id: string, patch: { status?: ChecklistStatus
   });
 }
 
+export function claimItem(v: string, id: string, by: string, options: { force?: boolean } = {}): Checklist {
+  const requested = parseOwner(by);
+  let outcome: 'claimed' | 'same' | 'refused' = 'refused';
+  let from: string | null = null;
+  try {
+    const result = mutate(v, (data) => {
+      const item = data.items.find((i) => i.id === id);
+      if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
+      from = item.owner ?? null;
+      if (from === by) { outcome = 'same'; return false; }
+      if (from && !options.force && !(from === requested.seat && requested.sub)) {
+        throw new CliUserError(`지금 주인: ${from} — --force 로만 바꾼다`);
+      }
+      const at = new Date().toISOString();
+      item.owner = by;
+      item.updatedAt = at;
+      item.updatedBy = by;
+      data.history.push({ at, by, id, field: 'claim', from, to: options.force ? { owner: by, force: true } : by,
+        released: data.released, dev: data.dev });
+      outcome = 'claimed';
+      return true;
+    });
+    return result;
+  } finally {
+    debug.log('release-loop.checklist', 'claim', { version: v, id, from, to: by, force: options.force === true, outcome });
+  }
+}
+
 export function removeItem(v: string, id: string, by: string): Checklist {
   return mutate(v, (data) => {
     const index = data.items.findIndex((i) => i.id === id);
@@ -106,15 +174,21 @@ export function summarize(v: string): ChecklistSummary {
   return summarizeChecklist(listChecklist(v));
 }
 
-export interface ChecklistSummary { green: number; yellow: number; red: number; done: number; blocked: string[]; byOwner: Record<string, number> }
+export interface ChecklistSummary { green: number; yellow: number; red: number; done: number; blocked: string[]; byOwner: Record<string, number>; bySeat: Record<string, number> }
 
 export function summarizeChecklist(data: Checklist): ChecklistSummary {
-  const summary = { green: 0, yellow: 0, red: 0, done: 0, blocked: [] as string[], byOwner: Object.create(null) as Record<string, number> };
+  const summary = { green: 0, yellow: 0, red: 0, done: 0, blocked: [] as string[], byOwner: Object.create(null) as Record<string, number>, bySeat: Object.create(null) as Record<string, number> };
   for (const item of data.items) {
     summary[item.status]++;
     if (item.status === 'red') summary.blocked.push(item.id);
     const owner = item.owner ?? 'unassigned';
     summary.byOwner[owner] = (summary.byOwner[owner] ?? 0) + 1;
+    if (item.owner !== undefined) {
+      try {
+        const { seat } = parseOwner(item.owner);
+        summary.bySeat[seat] = (summary.bySeat[seat] ?? 0) + 1;
+      } catch { /* Preserve legacy owner in byOwner without assigning it to a seat. */ }
+    }
   }
   return summary;
 }