elanous 0.2.34 → 0.2.36

package/scripts/ci-typecheck-changed.ts

@@ -1316,6 +1316,129 @@ export function typecheckDispatchFlags(flags: GateRemoteFlags, env: NodeJS.Proce
     ? { ...flags, remote: 'node-b' } : flags;
 }
 
+// ── WSL-GATE-ENV (0.2.36) — base 환경 해석 · 원격 push 실패 «원인» 보고 ─────────────────────────
+//   🩸 wsl·node-c 가 «같은 head·base» 를 쟀는데 introduced·preexisting 이 갈렸고, 남는 출력은
+//      `push-failed rc=128: …` 한 줄이었다. 그 한 줄로는 «미러 쓰기 권한» 인지 «base 가 달랐다» 인지
+//      읽을 수 없었고, base env 가 원격에 무엇으로 전달됐는지도 어디에도 찍히지 않았다.
+//   ⇒ (1) 원격 디스패치마다 base env 를 `ref@sha` 로 «풀어서» 한 줄 찍는다 — 두 호스트가 같은 줄을
+//        찍는 것이 교차 측정의 전제다. (2) push 실패는 rc·문면으로 «권한/자격증명» 과 «그 밖»을 가르고
+//        처방을 같이 찍는다. (3) base ref 를 이 트리에서 풀 수 없으면 원격을 «띄우지 않고» 멈춘다 —
+//        다른 base 로 잰 판정을 두 호스트가 «같다»고 믿게 만든 것이 이 칸의 사고였다.
+//   ⛔ 로컬 경로(--local · Pod · CI)의 출력·원장 형식은 건드리지 않는다 — 아래 줄은 원격 디스패치 안에서만 나온다.
+const BASE_ENV_KEYS = ['NODE_OPTIONS', 'TSC_BASE_REF', 'TSC_HEAP_MB'] as const;
+
+export interface RemoteBaseEnv {
+  /** 원격으로 push 해 sha 로 받아야 하는 ref. TSC_BASE_REF 가 없으면 비어 있다(merge-base 는 HEAD 의 조상이라 HEAD 와 함께 간다). */
+  refs: string[];
+  /** 무엇을 base 로 골랐나 — TSC_BASE_REF 의 ref 이름, 없으면 `merge-base(origin/main)`. */
+  baseLabel: string;
+  /** base 를 이 트리에서 푼 sha — 두 호스트가 같은 값을 찍어야 교차 측정이 성립한다. */
+  baseSha?: string;
+  /** 원격 명령에 전달하는 env 키들. */
+  keys: string[];
+  /** 원격 명령 앞에 붙일 `KEY=VALUE`. TSC_BASE_REF 는 «항상» 이 트리에서 고정한 sha 로 넘긴다
+   *  (ref 는 dispatch 가 push 한 sha · 없으면 merge-base sha) — 원격이 제 origin/main 으로 다시 풀지 않는다. */
+  forward: (sha: (ref: string) => string) => string[];
+  /** 이 트리에서 base 를 sha 로 고정할 수 없을 때의 사유 — 있으면 원격 디스패치를 멈춘다. */
+  failure?: string;
+}
+
+const firstErrorLine = (thrown: unknown): string => (thrown instanceof Error ? thrown.message : String(thrown)).split('\n')[0].trim();
+
+export function remoteBaseEnv(
+  env: NodeJS.ProcessEnv,
+  resolve: (ref: string) => string = (ref) => execFileSync('git', ['rev-parse', '--verify', '--quiet', ref], { encoding: 'utf8' }).trim(),
+  mergeBase: () => string = () => execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], { encoding: 'utf8' }).trim(),
+): RemoteBaseEnv {
+  const baseRef = env.TSC_BASE_REF;
+  let baseSha: string | undefined;
+  let failure: string | undefined;
+  if (baseRef) {
+    try { baseSha = resolve(baseRef) || undefined; } catch (thrown) {
+      failure = `TSC_BASE_REF=${baseRef} 를 이 트리에서 sha 로 풀 수 없다 (${firstErrorLine(thrown) || 'git rev-parse 실패'})`;
+    }
+    if (!baseSha && !failure) failure = `TSC_BASE_REF=${baseRef} 를 이 트리에서 sha 로 풀 수 없다 (git rev-parse 빈 출력)`;
+  } else {
+    // TSC_BASE_REF 가 없으면 원격 쪽 기본(merge-base(origin/main))을 «여기서» 미리 풀어 sha 로 못 박는다 —
+    //   원격 미러의 origin/main 은 이 트리와 다를 수 있다(같은 head 인데 base 가 갈린 이 칸의 사고 · 리뷰 r1 must-fix).
+    try { baseSha = mergeBase() || undefined; } catch (thrown) {
+      failure = `merge-base(HEAD, origin/main) 을 이 트리에서 풀 수 없다 (${firstErrorLine(thrown) || 'git merge-base 실패'})`;
+    }
+    if (!baseSha && !failure) failure = 'merge-base(HEAD, origin/main) 을 이 트리에서 풀 수 없다 (git merge-base 빈 출력)';
+  }
+  const passKeys = BASE_ENV_KEYS.filter((key) => key !== 'TSC_BASE_REF' && env[key]);
+  return {
+    refs: baseRef ? [baseRef] : [],
+    baseLabel: baseRef || 'merge-base(origin/main)',
+    baseSha,
+    keys: ['TSC_BASE_REF', ...passKeys],
+    forward: (sha) => [`TSC_BASE_REF=${baseRef ? sha(baseRef) : baseSha}`, ...passKeys.map((key) => `${key}=${env[key]}`)],
+    failure,
+  };
+}
+
+/** 두 호스트가 같은 head·base 를 쟀는지 «눈으로» 비교할 수 있는 한 줄. 호스트 이름만 다르다. */
+export function describeRemoteBaseEnv(env: RemoteBaseEnv, host: string): string {
+  const base = `${env.baseLabel}@${env.baseSha ?? '미해석'}`;
+  return `[tsc-gate] base env [${host}] — base=${base} · refs=${env.refs.length} · forward=${env.keys.join(',') || '없음'}`;
+}
+
+export type RemoteInfraCause = 'base-env' | 'push-permission' | 'push-failed' | 'other';
+
+export interface RemoteDiagnosis { cause: RemoteInfraCause; message: string; hints: string[] }
+
+/** push 거부 문면에서 «미러 쓰기 권한·자격증명» 을 가리키는 신호. */
+export const PUSH_PERMISSION_SIGNAL = /permission denied|publickey|could not read (?:Username|Password)|authentication failed|host key verification failed|access denied|terminal prompts disabled/i;
+
+export const BASE_ENV_HINTS = [
+  'base 는 두 호스트가 «같은 커밋» 이어야 한다 — 위 base= 줄에서 @뒤 sha 가 같은지 먼저 본다.',
+  'TSC_BASE_REF 는 양쪽 트리에 존재하는 ref(또는 sha)로 준다 — 한쪽에만 있는 브랜치면 introduced 가 갈린다.',
+];
+
+export function baseEnvDiagnosis(env: RemoteBaseEnv, host: string): RemoteDiagnosis | undefined {
+  if (!env.failure) return undefined;
+  return { cause: 'base-env', message: `${env.failure} — ${host} 를 띄우지 않는다`, hints: BASE_ENV_HINTS };
+}
+
+export function formatRemoteDiagnosis(diagnosis: RemoteDiagnosis): string[] {
+  return [
+    `[tsc-gate] ⛔ 원격 판정 실패 원인 [${diagnosis.cause}] — ${diagnosis.message}`,
+    ...diagnosis.hints.map((hint) => `[tsc-gate]   ${hint}`),
+  ];
+}
+
+export function diagnoseRemoteOutcome(
+  outcome: { kind: 'ran' | 'busy' | 'infra'; reason?: string },
+  host: string,
+  env: RemoteBaseEnv,
+): RemoteDiagnosis | undefined {
+  const base = baseEnvDiagnosis(env, host);
+  if (base) return base;
+  if (outcome.kind !== 'infra') return undefined;
+  const reason = outcome.reason ?? '';
+  const push = /^push-failed rc=(\d+)/.exec(reason);
+  if (!push) return {
+    cause: 'other',
+    message: `원격 판정 인프라 실패 — ${reason}`,
+    hints: [`같은 head·base 인데 이 호스트에서만 실패하면 위 base env 줄을 호스트끼리 비교한다.`],
+  };
+  const rc = Number(push[1]);
+  if (rc === 128 && PUSH_PERMISSION_SIGNAL.test(reason)) return {
+    cause: 'push-permission',
+    message: `원격 push 거부 rc=128 — ${host} 미러에 쓰기 권한/자격증명이 없다`,
+    hints: [
+      `호스트 접근부터 확인: ssh -o BatchMode=yes ${host} true (rc=0 이어야 한다 — 아니면 키·호스트 항목 문제다)`,
+      `미러 쓰기 확인: ssh ${host} -- 'test -w <mirror>.git' — 권한이 없으면 ELANOUS_GATE_REMOTE_MIRROR 로 쓰기 가능한 미러를 준다`,
+      'push 는 자격증명이 없으면 «터미널 프롬프트 없이» 죽는다 — 대화형 ssh 로 한 번 손으로 push 해 rc 를 본다.',
+    ],
+  };
+  return {
+    cause: 'push-failed',
+    message: `원격 push 실패 rc=${rc} — ${host}`,
+    hints: [`push 출력: ${reason}`, '미러 경로·디스크 여유를 확인하고, 반복되면 같은 트리에서 손으로 push 해 원문을 남긴다.'],
+  };
+}
+
 if (import.meta.main) void (async () => {
   // GATE-REMOTE (10-06): the only accepted arguments are the dispatch flags `--remote [host]` / `--local` — they choose
   //   «where» the same commit is measured, never «what» (the base stays merge-base(origin/main) on both sides).
@@ -1333,15 +1456,26 @@ if (import.meta.main) void (async () => {
   const repo = sh('git rev-parse --show-toplevel').trim();
   const onMbp = forbidFullTypecheckOnLocal(process.env, hostname(), repo);
   const dispatchFlags = typecheckDispatchFlags(flags, process.env, hostname(), repo);
-  const baseRef = process.env.TSC_BASE_REF;
-  const passEnv = (sha: (ref: string) => string) => (['NODE_OPTIONS', 'TSC_BASE_REF', 'TSC_HEAP_MB'] as const).filter((key) => process.env[key])
-    .map((key) => `${key}=${key === 'TSC_BASE_REF' && baseRef !== 'origin/main' ? sha(baseRef!) : process.env[key]}`);
+  const baseEnv = remoteBaseEnv(process.env);
+  // 원격만 재는 자리에서 base ref 를 «이 트리에서» 못 풀면, 두 호스트가 «다른 base» 로 잰 판정을
+  //   «같은 답»처럼 찍게 된다 — 그래서 띄우지 않고 멈춘다(원인과 처방을 남긴다). --local 은 그대로 간다.
+  if (baseEnv.failure && dispatchFlags.remote !== undefined && !flags.local) {
+    for (const line of formatRemoteDiagnosis(baseEnvDiagnosis(baseEnv, dispatchFlags.remote === true ? '기본 원격' : dispatchFlags.remote)!)) console.error(line);
+    console.error('[tsc-gate]   ⇒ 원격을 띄우지 않는다. base 를 양쪽 호스트가 «같이» 푸는 ref/sha 로 고친 뒤 다시 돌려라.');
+    process.exit(2);
+  }
   // exitCode, not exit(): piped stdout/stderr drain before the process ends.
   process.exitCode = await dispatchHeavyCheck({
     tool: 'ci-typecheck-changed', repo, flags: dispatchFlags, explicitRemoteOnly: dispatchFlags.remote !== undefined,
     stableCheckout: true, installPwa: true,
-    remoteArgv: (sha) => { const vars = passEnv(sha); return [...(vars.length ? ['env', ...vars] : []), 'bun', 'run', 'scripts/ci-typecheck-changed.ts', '--local']; },
-    refs: baseRef ? [baseRef] : [],
+    remoteArgv: (sha) => { const vars = baseEnv.forward(sha); return [...(vars.length ? ['env', ...vars] : []), 'bun', 'run', 'scripts/ci-typecheck-changed.ts', '--local']; },
+    refs: baseEnv.refs,
+    // 원격 판정이 «무엇으로» 났는지 호스트마다 같은 문면으로 남긴다 — 교차 측정의 대조 줄.
+    onRemoteOutcome: (outcome, host) => {
+      console.error(describeRemoteBaseEnv(baseEnv, host));
+      const diagnosis = diagnoseRemoteOutcome(outcome, host, baseEnv);
+      if (diagnosis) for (const line of formatRemoteDiagnosis(diagnosis)) console.error(line);
+    },
     runLocal: () => { runGate({ forbidFullLocal: onMbp }); return 0; },
   });
 })();

package/scripts/coord-role-pack.ts

@@ -21,9 +21,17 @@ export interface RolePack {
 
 const KNOWHOW_PATH = 'docs/roles/OP/KNOWHOW.md';
 
+/**
+ * 카드 제목 문법은 src/seat-loop/knowhow-lint.ts 의 CARD_HEADING 과 같아야 한다.
+ * 다르면 린트가 카드로 못 본 제목이 자를 때 조용히 사라지거나, 번호만 잘려 엉뚱한 아이디로 제외 기록에 남는다.
+ */
+const CARD_HEADING = /^[ \t]{0,3}##\s+(K-[A-Za-z]+(?:-[A-Za-z]{1,4})?-\d+)(?=$|\s|:|—)(.*)$/u;
+const CARD_HEADING_LIKE = /^[ \t]{0,3}##\s*(K-[^\s:]*)/iu;
+const SECTION_HEADING = /^[ \t]{0,3}##\s/u;
+
 /**
  * KNOWHOW.md 를 `##` 제목 단위 카드로 자른다(코드 울타리 안은 본문으로 본다).
- * 유효한 `## K-<role>-<number>` 제목을 가진 카드만 반환한다.
+ * 린트 문법을 지킨 `## K-<role>-<number>` 제목만 카드로 반환하고, 카드처럼 보이지만 문법을 벗어난 제목은 파일 단위 린트처럼 실패한다.
  */
 export function splitKnowhowCards(body: string): Array<{ id: string; title: string; text: string }> {
   const segments: Array<{ heading: string | null; lines: string[] }> = [{ heading: null, lines: [] }];
@@ -40,7 +48,7 @@ export function splitKnowhowCards(body: string): Array<{ id: string; title: stri
       segments.at(-1)!.lines.push(line);
       continue;
     }
-    if (/^##\s/u.test(line)) {
+    if (SECTION_HEADING.test(line)) {
       segments.push({ heading: line, lines: [] });
       continue;
     }
@@ -49,9 +57,14 @@ export function splitKnowhowCards(body: string): Array<{ id: string; title: stri
   const cards: Array<{ id: string; title: string; text: string }> = [];
   for (const segment of segments) {
     if (!segment.heading) continue;
-    const heading = segment.heading.match(/^##\s+(K-[A-Za-z]+-\d+)\s*(.*)$/u);
-    if (!heading) continue;
-    cards.push({ id: heading[1]!, title: heading[2]!.trim(), text: [segment.heading, ...segment.lines].join('\n') });
+    const heading = segment.heading.match(CARD_HEADING);
+    if (!heading) {
+      // 카드처럼 보이는 제목이 문법을 벗어나면 통과도 제외 기록도 불가능하다 — 조용히 빼지 않고 그 자리에서 실패한다.
+      const like = segment.heading.match(CARD_HEADING_LIKE);
+      if (like) throw new KnowhowLintError(KNOWHOW_PATH, like[1]!, '카드 제목 형식이 K-<자리>-<번호>를 벗어남');
+      continue;
+    }
+    cards.push({ id: heading[1]!, title: heading[2]!.replace(/^[:\s—]+/u, '').trim(), text: [segment.heading, ...segment.lines].join('\n') });
   }
   return cards;
 }
@@ -141,7 +154,7 @@ export function buildCoordRolePackManifest(role: RolePackRole, root = resolve(im
   // The pack body is inline. Source docs only contribute hashes, so an installed package without them still builds.
   const present = SOURCE_PATHS.filter((path) => existsSync(resolve(repo, path)));
   const missingSources = SOURCE_PATHS.filter((path) => !present.includes(path));
-  const sources = present.map((path) => ({ path, sha256: sha256(readFileSync(resolve(repo, path), 'utf8')) }));
+  const sources: RolePack['sources'] = present.map((path) => ({ path, sha256: sha256(readFileSync(resolve(repo, path), 'utf8')) }));
   const knowhow = collectVerifiedKnowhow(repo);
   if (knowhow.fileBody !== null) sources.push({ path: KNOWHOW_PATH, sha256: sha256(knowhow.fileBody) });
   const packageJson = resolve(repo, 'package.json');

package/scripts/first10-gate.ts

@@ -0,0 +1,416 @@
+#!/usr/bin/env bun
+// FIRST10-GATE (0.2.36 first measurable slice) — a local, one-record stopwatch for a
+// fresh public install → first-run → first useful answer. UX runs this on an isolated
+// Mac account against the exact PR head; the recorder never claims the full macOS card
+// green by itself — a run without a real useful answer records `unmeasured`/`failed`,
+// never `pass`.
+//
+// Wraps scripts/install.sh UNEDITED (--prefix/--source, ELANOUS_INSTALL_LANG, and
+// ELANOUS_INSTALL_INTERACTIVE/--no-setup for non-interactive runs) and the installed
+// CLI's non-TTY first-run path (src/onboarding/first-chat-gate.ts → runFirstRun,
+// rc=2 on needs-llm). Phase boundaries are the runFirstRun outcomes
+// ('ready'|'needs-llm'|'cancelled') and the onboarding.first-run/first-chat ledger events.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export interface IsolationInput {
+  home: string;
+  prefix: string;
+  stateDir: string;
+  realHome?: string;
+  xdgDataHome?: string;
+}
+
+export type IsolationResult = { ok: true } | { ok: false; reason: string };
+
+const under = (path: string, root: string): boolean =>
+  path === root || path.startsWith(`${root}/`);
+
+/** Refuse operating default paths; only an isolated HOME/PREFIX/ELANOUS_STATE_DIR may run. */
+export function validateIsolation(input: IsolationInput): IsolationResult {
+  const realHome = resolve(input.realHome ?? process.env.FIRST10_GATE_REAL_HOME ?? process.env.HOME ?? '');
+  if (!realHome) return { ok: false, reason: '⛔ real HOME is unknown — pass --home for an isolated home' };
+  const home = resolve(input.home);
+  const prefix = resolve(input.prefix);
+  const stateDir = resolve(input.stateDir);
+  const xdgDataHome = input.xdgDataHome ?? process.env.XDG_DATA_HOME;
+  const operatingDefaultPrefixes = [
+    resolve(xdgDataHome ?? `${realHome}/.local/share`, 'elanous'),
+    resolve(`${realHome}/.local/share`, 'elanous'),
+  ];
+  // install.sh line 38: default PREFIX is ${XDG_DATA_HOME:-$HOME/.local/share}/elanous — refuse it.
+  if (operatingDefaultPrefixes.some((p) => prefix === p)) {
+    return { ok: false, reason: `⛔ refusing the operating default prefix ${prefix} — pass an isolated --prefix` };
+  }
+  if (home === realHome) return { ok: false, reason: `⛔ --home must be an isolated home, not the operating HOME ${realHome}` };
+  // install.sh lines 243-246: a PATH block pointing at a different installation prefix must
+  // never be silently reused — a prefix outside the isolated home is exactly that case.
+  if (!under(prefix, home)) {
+    return { ok: false, reason: `⛔ prefix ${prefix} is outside the isolated home ${home} (different installation prefix)` };
+  }
+  const operatingStateDirs = [resolve(`${realHome}/.elanous`), resolve(`${process.env.HOME ?? realHome}/.elanous`)];
+  // The operating prod state dir (~/.elanous) must never receive measurement writes.
+  if (operatingStateDirs.some((s) => stateDir === s)) {
+    return { ok: false, reason: `⛔ refusing the operating state dir ${stateDir} — pass an isolated --state-dir` };
+  }
+  if (!under(stateDir, home)) {
+    return { ok: false, reason: `⛔ state dir ${stateDir} is outside the isolated home ${home}` };
+  }
+  return { ok: true };
+}
+
+export type FirstRunOutcome = 'ready' | 'needs-llm' | 'cancelled' | 'unknown';
+
+export type UsefulResult = 'measured' | 'unmeasured' | 'failed';
+
+/** outcome ≠ ready → unmeasured/failed; ready alone is NOT a useful result without answer evidence. */
+export function mapOutcomeToUsefulResult(
+  { outcome, answerEvidence }: { outcome: FirstRunOutcome; answerEvidence?: string | null },
+): UsefulResult {
+  if (answerEvidence && outcome === 'ready') return 'measured';
+  if (outcome === 'needs-llm') return 'failed';
+  return 'unmeasured';
+}
+
+const SECRET_PATTERNS: readonly RegExp[] = [
+  /\bsk-[A-Za-z0-9_-]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{16,}\b/g,
+  /\bBearer\s+[A-Za-z0-9._-]+/gi,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g,
+  /((?:api[_-]?key|token|secret|password|credential)["'=:\s]+)[^\s'"",}]+/gi,
+];
+
+/** Secret hygiene (first-run.test.ts: tokens never appear in captured output). */
+export function scrubSecrets(text: string): string {
+  let out = text;
+  for (const pattern of SECRET_PATTERNS) {
+    out = out.replace(pattern, (match, ...rest) => {
+      const prefix = typeof rest[0] === 'string' ? rest[0] : '';
+      return prefix ? `${prefix}[REDACTED]` : '[REDACTED]';
+    });
+  }
+  return out;
+}
+
+export interface PhaseRecord {
+  rc: number | null;
+  stdout: string;
+  stderr: string;
+  elapsedMonotonicMs: number;
+}
+
+export interface RecordSource {
+  kind: 'url' | 'tarball' | 'checkout';
+  ref: string;
+  tarballSha256?: string;
+}
+
+export interface RecorderRecord {
+  schema: 'first10-gate/1';
+  mode: 'dry' | 'real';
+  createdAt: string;
+  locale: 'ko' | 'en';
+  source: RecordSource;
+  cliVersion?: string;
+  installMetadata?: { version?: string; versionDir?: string; source?: string; installedAt?: string; commit?: string };
+  phases: { install: PhaseRecord; firstRun?: PhaseRecord };
+  errorCount: number;
+  /** 600-second decision: null when the phase timings are incomplete or the run is a dry rehearsal. */
+  decision600s: 'within' | 'over' | null;
+  missingFields: string[];
+  /** Evidence reference for the first usable answer (a real reply line, never a fixture). */
+  answerEvidence: string | null;
+  usefulResult: UsefulResult;
+}
+
+export interface BuildRecordInput {
+  locale: 'ko' | 'en';
+  source: RecordSource;
+  cliVersion?: string;
+  installMetadata?: RecorderRecord['installMetadata'];
+  phases: { install: PhaseRecord; firstRun?: PhaseRecord };
+  answerEvidence?: string | null;
+  createdAt?: string;
+}
+
+const ERROR_LINE = /⛔|error|failed|fatal|panic/i;
+
+const countErrors = (phases: BuildRecordInput['phases']): number =>
+  Object.values(phases).reduce(
+    (n, phase) =>
+      n + (phase
+        ? phase.stderr.split('\n').filter((line) => ERROR_LINE.test(line)).length + (phase.rc !== 0 && phase.rc !== null ? 1 : 0)
+        : 0),
+    0,
+  );
+
+/** One JSON record: phase timings, rc/stdout/stderr, locale, source, CLI version, error count, 600s decision. */
+export function buildRecord(input: BuildRecordInput): RecorderRecord {
+  const missingFields: string[] = [];
+  if (!input.cliVersion) missingFields.push('cliVersion');
+  if (!input.phases.firstRun) missingFields.push('phases.firstRun');
+  if (!input.phases.install.stdout && !input.phases.install.stderr) missingFields.push('phases.install.output');
+  if (!input.answerEvidence) missingFields.push('answerEvidence');
+  if (input.source.kind === 'tarball' && !input.source.tarballSha256) missingFields.push('source.tarballSha256');
+  const firstRunRc = input.phases.firstRun?.rc;
+  const outcome: FirstRunOutcome = !input.phases.firstRun
+    ? 'unknown'
+    : firstRunRc === 0 ? 'ready' : firstRunRc === 2 ? 'needs-llm' : firstRunRc === null ? 'cancelled' : 'unknown';
+  const mode: RecorderRecord['mode'] =
+    input.phases.install.rc === 0 && input.phases.install.stdout === '[dry-run]' ? 'dry' : 'real';
+  // A dry rehearsal's 0 ms phase timings are placeholders, never measurements — a positive
+  // 600 s decision ("within") must not be published from them (review ta-20261022-e0a4f8 mustFix 2).
+  if (mode === 'dry') missingFields.push('decision600s');
+  const totalMs =
+    input.phases.install.elapsedMonotonicMs + (input.phases.firstRun?.elapsedMonotonicMs ?? 0);
+  const decision600s: RecorderRecord['decision600s'] =
+    mode === 'dry' ? null
+      : input.phases.firstRun
+        ? (totalMs <= 600_000 ? 'within' : 'over')
+        : null;
+  const record: RecorderRecord = {
+    schema: 'first10-gate/1',
+    mode,
+    createdAt: input.createdAt ?? new Date().toISOString(),
+    locale: input.locale,
+    source: input.source,
+    ...(input.cliVersion ? { cliVersion: input.cliVersion } : {}),
+    ...(input.installMetadata ? { installMetadata: input.installMetadata } : {}),
+    phases: input.phases as RecorderRecord['phases'],
+    errorCount: countErrors(input.phases),
+    decision600s,
+    missingFields,
+    answerEvidence: input.answerEvidence ? scrubSecrets(input.answerEvidence) : null,
+    // A dry rehearsal never measures a real useful result — 'unmeasured', never 'pass'.
+    usefulResult: mode === 'dry'
+      ? 'unmeasured'
+      : mapOutcomeToUsefulResult({ outcome, answerEvidence: input.answerEvidence }),
+  };
+  // Scrub each string field individually — never the serialized JSON, where an
+  // escaped quote (stderr `token=abc"`) would leave a bare quote and break JSON.parse.
+  const scrubPhase = (p: PhaseRecord): PhaseRecord =>
+    ({ ...p, stdout: scrubSecrets(p.stdout), stderr: scrubSecrets(p.stderr) });
+  return {
+    ...record,
+    source: { ...record.source, ref: scrubSecrets(record.source.ref) },
+    phases: {
+      install: scrubPhase(record.phases.install),
+      ...(record.phases.firstRun ? { firstRun: scrubPhase(record.phases.firstRun) } : {}),
+    },
+  };
+}
+
+export interface CliArgs {
+  record: string;
+  home?: string;
+  prefix: string;
+  stateDir?: string;
+  source?: string;
+  lang: 'ko' | 'en';
+  dry: boolean;
+  answerEvidence?: string;
+  help: boolean;
+}
+
+const HELP = `Usage: bun scripts/first10-gate.ts --record PATH --home PATH --prefix PATH --state-dir PATH [--source PATH.tgz|URL] [--lang ko|en] [--answer-evidence TEXT] [--dry] [--help]
+
+FIRST10-GATE — one JSON stopwatch record for install → first-run → first useful answer.
+  --record PATH        where to write the single JSON record (required)
+  --home PATH          isolated HOME for the measurement run (required, must not be the operating HOME)
+  --prefix PATH        isolated installation prefix (required; the operating default
+                       \${XDG_DATA_HOME:-\$HOME/.local/share}/elanous is refused)
+  --state-dir PATH     isolated ELANOUS_STATE_DIR (required; the operating ~/.elanous is refused)
+  --source PATH.tgz|URL  passed through to scripts/install.sh (--source), recorded as provenance
+  --lang ko|en         one locale per run (ELANOUS_INSTALL_LANG) — ko and en runs are recorded separately
+  --answer-evidence TEXT  evidence reference for the first usable answer; without it the run is unmeasured
+  --dry                dry rehearsal: no real install.sh spawn; the record is marked mode "dry" and
+                       usefulResult stays unmeasured — never pass
+  --help, -h           show this help
+
+Wraps scripts/install.sh unedited with --prefix/--source, ELANOUS_INSTALL_LANG and
+ELANOUS_INSTALL_INTERACTIVE=0/--no-setup for non-interactive measurement runs.
+The first-run phase invokes the installed CLI's non-TTY first-chat gate
+(src/onboarding/first-chat-gate.ts → runFirstRun): rc=0 outcome 'ready', rc=2 'needs-llm'.
+This recorder never claims the full macOS 600 s card green — UX runs the exact PR head on
+mbp in two fresh isolated homes (ko/en) and attaches the screen recording and answer evidence.
+`;
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = { record: '', prefix: '', lang: 'en', dry: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = (): string => { const v = argv[++i]; if (v === undefined) throw new Error(`⛔ ${a} needs a value`); return v; };
+    switch (a) {
+      case '--help': case '-h': args.help = true; return args;
+      case '--record': args.record = next(); break;
+      case '--home': args.home = next(); break;
+      case '--prefix': args.prefix = next(); break;
+      case '--state-dir': args.stateDir = next(); break;
+      case '--source': args.source = next(); break;
+      case '--lang': {
+        const lang = next(); if (lang !== 'ko' && lang !== 'en') throw new Error('⛔ --lang must be ko or en'); args.lang = lang; break;
+      }
+      case '--answer-evidence': args.answerEvidence = next(); break;
+      case '--dry': args.dry = true; break;
+      default: throw new Error(`⛔ unknown argument: ${a}`);
+    }
+  }
+  if (!args.record) throw new Error('⛔ --record is required');
+  if (!args.prefix) throw new Error('⛔ --prefix is required');
+  if (!args.home) throw new Error('⛔ --home is required');
+  if (!args.stateDir) throw new Error('⛔ --state-dir is required');
+  return args;
+}
+
+interface InstallJson {
+  version?: string;
+  versionDir?: string;
+  source?: string;
+  installedAt?: string;
+  commit?: string;
+}
+
+const readInstallJson = (prefix: string): InstallJson | undefined => {
+  const path = resolve(prefix, 'install.json');
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as InstallJson;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Repository root = parent of this script's own directory (<repo>/scripts → <repo>). */
+export const repoRootOf = (): string => resolve(import.meta.dir, '..');
+
+/** sha256 of a file, cross-platform: sha256sum, then macOS `shasum -a 256`; '' if neither exists. */
+export const sha256 = (path: string): string => {
+  // macOS has no sha256sum by default — fall back to `shasum -a 256` (and shasum
+  // to shasum-compatible coreutils `sha256` no-op is not attempted).
+  for (const cmd of ['sha256sum', 'shasum -a 256']) {
+    const [bin, ...rest] = cmd.split(' ');
+    const r = spawnSync(bin, [...rest, path], { encoding: 'utf8' });
+    if (r.status === 0) {
+      const sum = r.stdout.trim().split(/\s+/)[0] ?? '';
+      if (sum) return sum;
+    }
+  }
+  // Neither hasher exists: empty string — callers must record this as missing.
+  return '';
+};
+
+function sourceOf(source: string | undefined, installMetadata: InstallJson | undefined): RecordSource {
+  if (source) {
+    if (/^https?:\/\//.test(source)) return { kind: 'url', ref: source };
+    if (!existsSync(source)) return { kind: 'tarball', ref: resolve(source) };
+    const tarballSha256 = sha256(source);
+    return tarballSha256 ? { kind: 'tarball', ref: resolve(source), tarballSha256 } : { kind: 'tarball', ref: resolve(source) };
+  }
+  const metaSource = installMetadata?.source;
+  if (metaSource && /^https?:\/\//.test(metaSource)) return { kind: 'url', ref: metaSource };
+  return { kind: 'checkout', ref: metaSource ?? (process.cwd()) };
+}
+
+/** URL sources are passed through verbatim; only local file paths are resolve()d. */
+export const installSourceArg = (source: string): string =>
+  /^https?:\/\//.test(source) ? source : resolve(source);
+
+export function runInstallPhase(args: CliArgs, repoRoot: string): PhaseRecord {
+  if (args.dry) {
+    // Dry rehearsal: no real spawn — the record is marked mode "dry" so it can never be
+    // conflated with a real useful result.
+    return { rc: 0, stdout: '[dry-run]', stderr: '', elapsedMonotonicMs: 0 };
+  }
+  if (!existsSync(resolve(repoRoot, 'scripts/install.sh'))) {
+    return {
+      rc: 127,
+      stdout: '',
+      stderr: `⛔ scripts/install.sh not found under ${repoRoot} — not a real install run`,
+      elapsedMonotonicMs: 0,
+    };
+  }
+  const installer = resolve(repoRoot, 'scripts/install.sh');
+  const env = {
+    ...process.env,
+    HOME: resolve(args.home!),
+    ELANOUS_STATE_DIR: resolve(args.stateDir!),
+    ELANOUS_INSTALL_LANG: args.lang,
+    ELANOUS_INSTALL_INTERACTIVE: '0',
+  };
+  const started = performance.now();
+  const r = spawnSync('bash', [installer, '--prefix', resolve(args.prefix), '--no-setup', '--no-modify-path', ...(args.source ? ['--source', installSourceArg(args.source)] : [])], {
+    encoding: 'utf8', env, maxBuffer: 16 * 1024 * 1024,
+  });
+  return {
+    rc: r.status,
+    stdout: r.stdout ?? '',
+    stderr: r.stderr ?? '',
+    elapsedMonotonicMs: Math.round(performance.now() - started),
+  };
+}
+
+function runFirstRunPhase(args: CliArgs, install: PhaseRecord): PhaseRecord | undefined {
+  if (args.dry) return { rc: 2, stdout: '[dry-run]', stderr: '[dry-run] first-run not measured', elapsedMonotonicMs: 0 };
+  if (install.rc !== 0) return undefined;
+  const cli = resolve(args.prefix, 'bin/elanous');
+  if (!existsSync(cli)) return undefined;
+  const env = {
+    ...process.env,
+    HOME: resolve(args.home!),
+    ELANOUS_STATE_DIR: resolve(args.stateDir!),
+    ELANOUS_INSTALL_LANG: args.lang,
+  };
+  const started = performance.now();
+  // The installed CLI's non-TTY first-chat gate: rc=2 means runFirstRun outcome 'needs-llm'.
+  const r = spawnSync('bash', [cli], { encoding: 'utf8', env, maxBuffer: 16 * 1024 * 1024 });
+  return {
+    rc: r.status,
+    stdout: r.stdout ?? '',
+    stderr: r.stderr ?? '',
+    elapsedMonotonicMs: Math.round(performance.now() - started),
+  };
+}
+
+export function main(argv: string[]): number {
+  let args: CliArgs;
+  try {
+    args = parseArgs(argv);
+  } catch (e) {
+    process.stderr.write(`${(e as Error).message}\n\n${HELP}`);
+    return 2;
+  }
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  const isolation = validateIsolation({ home: args.home!, prefix: args.prefix, stateDir: args.stateDir! });
+  if (!isolation.ok) {
+    process.stderr.write(`${isolation.reason}\n`);
+    return 2;
+  }
+  // Repository root = parent of this script's own directory (<repo>/scripts → <repo>),
+  // so runInstallPhase spawns the real <repo>/scripts/install.sh, never <repo>/scripts/scripts/install.sh.
+  const repoRoot = repoRootOf();
+  const installPhase = runInstallPhase(args, repoRoot);
+  const installMetadata = readInstallJson(args.prefix);
+  const firstRunPhase = runFirstRunPhase(args, installPhase);
+  const record = buildRecord({
+    locale: args.lang,
+    source: sourceOf(args.source, installMetadata),
+    cliVersion: installMetadata?.version,
+    installMetadata,
+    phases: { install: installPhase, ...(firstRunPhase ? { firstRun: firstRunPhase } : {}) },
+    answerEvidence: args.answerEvidence ?? null,
+  });
+  const out = resolve(args.record);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${JSON.stringify(record, null, 2)}\n`);
+  process.stdout.write(`${out}: usefulResult=${record.usefulResult} decision600s=${record.decision600s ?? 'n/a'} missingFields=${record.missingFields.join(',') || '-'}\n`);
+  return 0;
+}
+
+if (import.meta.main) {
+  process.exit(main(process.argv.slice(2)));
+}
+