elanous 0.2.29 → 0.2.32

package/src/release-loop/rehearsal-shard-plan.ts

@@ -0,0 +1,149 @@
+import { spawnSync } from 'node:child_process';
+import { availableParallelism, cpus as hostCpus, freemem, totalmem } from 'node:os';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { selectGateTestFiles } from '../self-implement/gate-cli.js';
+import { readFileMemory } from '../../scripts/release-loop/shard-plan.js';
+import { gateShardsPath, readGateShards } from './gate-shards.js';
+import { LIGHT_RC_ALWAYS_FILE, LIGHT_RC_DEFAULT_SHARDS, parseAlwaysIncludeList, previousCutBase } from './light-rc.js';
+
+const FILE_MEMORY_SOURCE = 'docs/measurements/td1-whole-gate-mechanical-2026-10-01.tsv';
+
+export interface RehearsalShardPlan {
+  shards: number;
+  testFiles: number | null;
+  /** Observed on the tick host, not necessarily the remote gate host. */
+  resources: { cpus: number; freeBytes: number; totalBytes: number };
+  gatePlanShards: number | null;
+  /** Local preflight budget, not a measured remote peak-RSS or a workload-specific guarantee. */
+  capacity?: { reserveBytes: number; bytesPerShard: number; memoryShards: number | null; requiredBytes: number; measuredFiles: number; peakFileBytes: number | null };
+  unmeasured: string | null;
+  /** The remote host's capacity is checked by the actual RC, after this preflight. */
+  remoteCapacityPending?: boolean;
+  rssRevisionPending?: boolean;
+  planningGaps?: string[];
+  remoteCapacityVerifiedBy?: string;
+}
+
+export interface RehearsalShardPlanDeps {
+  /** Rehearsal light RC dispatches remotely; local CPU/memory is evidence only, not a gate-host limit. */
+  remoteGate?: boolean;
+  select?: (checkout: string, options: { base: string; alwaysInclude: string[]; includeImporterTests: true }) => { testFiles: string[]; alwaysIncludeMissing?: readonly string[]; lookupFailed?: string | null; unrunImporterTotal?: number | null; skipTestStep?: boolean; routeLookupFailures?: readonly unknown[]; unverified?: readonly string[]; callerTestsOverflow?: readonly unknown[] };
+  resources?: () => RehearsalShardPlan['resources'];
+  board?: typeof readGateShards;
+  readAlways?: (path: string) => string;
+  resolveBase?: (version: string, checkout: string, root: string) => string;
+  fileMemory?: (path: string) => Map<string, number>;
+}
+
+/** Preflight only: the gate still performs its own selection at execution time. The local budget uses measured
+ * selected-file peak RSS with a 2 GiB floor per shard and reserves 1 GiB for the host. The RC result is the
+ * authority for whether execution on its actual gate host succeeded. */
+const GIB = 1024 ** 3;
+const RESERVE_BYTES = GIB;
+const BYTES_PER_SHARD = 2 * GIB;
+
+/** The dated TSV has no dependency graph/revision. Require the whole checkout to match its source commit;
+ * otherwise RSS is provisional until a completed RC measures this actual checkout on its gate host. */
+function measurementMatchesCheckout(checkout: string): boolean {
+  const source = spawnSync('git', ['log', '-1', '--format=%H', '--', FILE_MEMORY_SOURCE], { cwd: checkout, encoding: 'utf8' });
+  const commit = source.stdout?.trim();
+  if (source.status !== 0 || !/^[0-9a-f]{40}$/.test(commit ?? '')) return false;
+  const diff = spawnSync('git', ['diff', '--quiet', commit!, 'HEAD', '--', '.'], { cwd: checkout, encoding: 'utf8' });
+  if (diff.status !== 0) return false;
+  const working = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: checkout, encoding: 'utf8' });
+  return working.status === 0 && !working.stdout?.trim();
+}
+
+/** OS free memory can describe the entire host rather than the tick's container; bound it by cgroup headroom. */
+export function rehearsalHostResources(read: (path: string) => string = (path) => readFileSync(path, 'utf8')): RehearsalShardPlan['resources'] {
+  const cpus = Math.max(1, Number(availableParallelism?.() ?? hostCpus()?.length ?? 1) || 1);
+  let freeBytes = freemem(), totalBytes = totalmem();
+  for (const [limitPath, usagePath] of [
+    ['/sys/fs/cgroup/memory.max', '/sys/fs/cgroup/memory.current'],
+    ['/sys/fs/cgroup/memory/memory.limit_in_bytes', '/sys/fs/cgroup/memory/memory.usage_in_bytes'],
+  ]) {
+    try {
+      const limit = Number(read(limitPath).trim()), usage = Number(read(usagePath).trim());
+      if (Number.isSafeInteger(limit) && limit > 0 && limit < totalBytes && Number.isSafeInteger(usage) && usage >= 0) {
+        totalBytes = limit;
+        freeBytes = Math.min(freeBytes, Math.max(0, limit - usage));
+        break;
+      }
+    } catch { /* not running inside this cgroup version */ }
+  }
+  return { cpus, freeBytes, totalBytes };
+}
+
+export function planRehearsalShards(version: string, root: string, checkout: string, deps: RehearsalShardPlanDeps = {}): RehearsalShardPlan {
+  const reasons: string[] = [];
+  let rssRevisionPending = false;
+  let resources: RehearsalShardPlan['resources'];
+  try { resources = (deps.resources ?? rehearsalHostResources)(); }
+  catch (error) {
+    resources = { cpus: 0, freeBytes: 0, totalBytes: 0 };
+    reasons.push(`host resource probe failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let gatePlanShards: number | null = null;
+  try {
+    const board = (deps.board ?? readGateShards)(gateShardsPath(version, root));
+    gatePlanShards = board?.version === version && board.shards.length && new Set(board.shards.map(shard => shard.id)).size === board.shards.length ? board.shards.length : null;
+  } catch (error) { reasons.push(`persisted gate shard plan unreadable: ${error instanceof Error ? error.message : String(error)}`); }
+  let testFiles: number | null = null;
+  let measuredFiles = 0;
+  let peakFileBytes: number | null = null;
+  try {
+    const path = join(checkout, LIGHT_RC_ALWAYS_FILE);
+    const text = deps.readAlways ? deps.readAlways(path) : existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+    if (text === undefined) throw new Error(`${LIGHT_RC_ALWAYS_FILE} missing`);
+    const base = (deps.resolveBase ?? ((v, cwd, ledgerRoot) => previousCutBase(v, { cwd, ledgerRoot })))(version, checkout, root);
+    const selection = (deps.select ?? ((cwd, opts) => selectGateTestFiles(cwd, opts)))(checkout, { base, alwaysInclude: parseAlwaysIncludeList(text), includeImporterTests: true });
+    const files = [...new Set(selection.testFiles)];
+    testFiles = files.length;
+    try {
+      const memory = (deps.fileMemory ?? readFileMemory)(join(checkout, FILE_MEMORY_SOURCE));
+      const peaks = files.map(file => memory.get(file)).filter((value): value is number => value !== undefined && Number.isFinite(value) && value > 0);
+      measuredFiles = peaks.length;
+      if (peaks.length) peakFileBytes = Math.ceil(peaks.reduce((largest, value) => Math.max(largest, value), 0) * 1_000_000);
+      if (measuredFiles !== testFiles) reasons.push(`selected file memory not measured: ${testFiles - measuredFiles}/${testFiles}`);
+      if (!deps.fileMemory && files.length && !measurementMatchesCheckout(checkout)) {
+        if (deps.remoteGate) rssRevisionPending = true;
+        else reasons.push('selected file RSS measurement revision not verified against checkout');
+      }
+    } catch (error) { reasons.push(`selected file memory unavailable: ${error instanceof Error ? error.message : String(error)}`); }
+    if (selection.alwaysIncludeMissing?.length) reasons.push(`always-include missing: ${selection.alwaysIncludeMissing.join(', ')}`);
+    if (selection.lookupFailed) reasons.push(`importer lookup failed: ${selection.lookupFailed}`);
+    if (selection.unrunImporterTotal === undefined) reasons.push('importer coverage not reported');
+    if (selection.unrunImporterTotal === null || (selection.unrunImporterTotal ?? 0) > 0) reasons.push(`importer tests not run: ${selection.unrunImporterTotal ?? 'unknown'}`);
+    if (selection.routeLookupFailures?.length) reasons.push(`route lookup failed: ${selection.routeLookupFailures.length}`);
+    if (selection.unverified?.length) reasons.push(`unverified scope: ${selection.unverified.length}`);
+    if (selection.callerTestsOverflow?.length) reasons.push(`caller tests overflow: ${selection.callerTestsOverflow.length}`);
+    if (selection.skipTestStep) reasons.push('gate test step skipped');
+    if (!testFiles) reasons.push('selected test files empty');
+  } catch (error) { reasons.push(`test selection unavailable: ${error instanceof Error ? error.message : String(error)}`); }
+  if (gatePlanShards === null) reasons.push('persisted gate shard plan unavailable');
+  const cpuValid = Number.isSafeInteger(resources.cpus) && resources.cpus > 0;
+  const memoryValid = Number.isFinite(resources.freeBytes) && resources.freeBytes >= 0 && Number.isFinite(resources.totalBytes) && resources.totalBytes > 0 && resources.freeBytes <= resources.totalBytes;
+  if (!deps.remoteGate && (!cpuValid || !memoryValid)) reasons.push('host resources unavailable');
+  const bytesPerShard = Math.max(BYTES_PER_SHARD, peakFileBytes ?? 0);
+  const memoryShards = memoryValid ? Math.max(0, Math.floor((resources.freeBytes - RESERVE_BYTES) / bytesPerShard)) : null;
+  const candidate = Math.max(1, Math.min(gatePlanShards ?? LIGHT_RC_DEFAULT_SHARDS, testFiles ?? LIGHT_RC_DEFAULT_SHARDS, deps.remoteGate ? Number.MAX_SAFE_INTEGER : cpuValid ? resources.cpus : LIGHT_RC_DEFAULT_SHARDS));
+  if (!deps.remoteGate && peakFileBytes !== null && memoryValid && resources.freeBytes < RESERVE_BYTES + peakFileBytes) {
+    reasons.push(`selected file peak exceeds host memory: peak ${peakFileBytes}, free ${resources.freeBytes}, reserve ${RESERVE_BYTES} bytes`);
+  }
+  // Never treat a 0-slot host as sufficient for one shard. The caller must leave an unrun step retryable.
+  const shards = deps.remoteGate || memoryShards === null ? candidate : Math.max(1, Math.min(candidate, memoryShards));
+  const capacity = { reserveBytes: RESERVE_BYTES, bytesPerShard, memoryShards, requiredBytes: RESERVE_BYTES + shards * bytesPerShard, measuredFiles, peakFileBytes };
+  if (!deps.remoteGate && memoryShards === 0) reasons.push(`host memory insufficient: free ${resources.freeBytes} < required ${capacity.requiredBytes} bytes for 1 shard`);
+  // The exported local planner has no local RC caller to validate aggregate workload capacity. A prior board's
+  // shard count and individual file peaks cannot prove that hundreds of tests fit one shard.
+  if (!deps.remoteGate) reasons.push('local gate shard workload sufficiency not measured');
+  // A complete selected-file measurement plus the persisted shard count and a valid host budget is enough to
+  // select a candidate. Execution on another host is judged by the RC result, not by a permanent preflight warning.
+  const remoteCapacityReason = 'remote gate host resources unmeasured before RC';
+  const rssRevisionReason = 'selected file RSS measurement revision not verified before RC';
+  return { shards, testFiles, resources, gatePlanShards, capacity,
+    ...(deps.remoteGate ? { remoteCapacityPending: true, rssRevisionPending, planningGaps: reasons } : {}),
+    unmeasured: reasons.length || deps.remoteGate ? [...reasons, ...(rssRevisionPending ? [rssRevisionReason] : []), ...(deps.remoteGate ? [remoteCapacityReason] : [])].join('; ') : null,
+  };
+}

package/src/release-loop/rehearsal.ts

@@ -1,11 +1,14 @@
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { debug } from '../debug/log.js';
 import { sendOutbound } from '../domains/outbound-alert.js';
 import { releaseLedgerRoot } from '../instance/resolve.js';
-import { runLightRc, type LightRcResult } from './light-rc.js';
+import { isValidGateHost } from '../self-implement/gate-remote.js';
+import { LIGHT_RC_UNKNOWN_HOST, runLightRc, type LightRcResult } from './light-rc.js';
+import { planRehearsalShards, type RehearsalShardPlan, type RehearsalShardPlanDeps } from './rehearsal-shard-plan.js';
 import { listSchedules, type ReleaseSchedule } from './release-schedule.js';
 
 export type StepId = 'rc-7h' | 'rc-150m';
@@ -50,6 +53,9 @@ export interface RehearsalStamp {
   summary?: string;
   regressionFiles?: string[];
   result?: LightRcResult;
+  shardPlan?: RehearsalShardPlan;
+  leakCheck?: { outcome: 'ok' | 'fail'; sha: string; exitCode: number | null };
+  selection?: { shards?: number; remote?: string };
   notifiedAt?: string;
   ownerPid?: number;
 }
@@ -58,14 +64,19 @@ export interface RehearsalOptions {
   apply?: boolean;
   checkout?: string;
   ledgerRoot?: string;
+  shards?: number;
+  remote?: string;
 }
 
 export interface RehearsalDeps {
   now?: () => Date;
   schedules?: (root: string) => ReleaseSchedule[];
-  lightRc?: (version: string, checkout: string) => Promise<LightRcResult>;
+  lightRc?: (version: string, checkout: string, selection: { shards?: number; remote?: string }) => Promise<LightRcResult>;
+  shardPlan?: typeof planRehearsalShards;
+  shardPlanDeps?: RehearsalShardPlanDeps;
   notify?: (text: string) => void | boolean | Promise<void | boolean>;
   git?: (args: string[], cwd: string) => { rc: number | null; stdout: string; stderr?: string };
+  leakCheck?: (checkout: string) => { status: number | null };
 }
 
 export type RehearsalTickResult = RehearsalPlan & { applied?: boolean; stamps?: RehearsalStamp[]; notificationFailures?: number };
@@ -86,6 +97,17 @@ function gitResult(git: NonNullable<RehearsalDeps['git']>, args: string[], check
   return result.stdout.trim();
 }
 
+/** Public export checks the pinned rehearsal checkout before any remote RC work. Its output is private and ephemeral. */
+function runRehearsalLeakCheck(checkout: string): { status: number | null } {
+  const out = mkdtempSync(join(tmpdir(), 'elanous-rehearsal-export-'));
+  try {
+    const result = spawnSync('bun', ['scripts/public-export.ts', '--out', join(out, 'export')], {
+      cwd: checkout, encoding: 'utf8', timeout: 1_800_000, maxBuffer: 64 * 1024 * 1024,
+    });
+    return { status: result.status };
+  } finally { rmSync(out, { recursive: true, force: true }); }
+}
+
 function oneLine(text: string): string { return text.replace(/\s+/g, ' ').trim(); }
 
 function outcomeLine(stamp: RehearsalStamp): string {
@@ -95,7 +117,11 @@ function outcomeLine(stamp: RehearsalStamp): string {
   if (!stamp.result) return `${head}${stamp.summary ? ` · ${stamp.summary}` : ''}`;
   const result = stamp.result;
   const duration = Math.max(0, Math.round((Date.parse(stamp.endedAt!) - Date.parse(stamp.startedAt)) / minute));
-  return `${head} · 새 회귀 ${result.introduced ?? '못 쟀다'} · 기존 ${result.preexisting ?? '못 쟀다'} · 미분류 ${result.unclassified ?? '못 쟀다'} · ${result.remote ?? 'local'} · ${duration}분${stamp.outcome === 'error' ? ` · gate rc ${result.gateExitCode}${!result.ok ? ' · RC 실패' : ''}` : ''}${stamp.regressionFiles?.length ? ` · 파일 ${stamp.regressionFiles.slice(0, 3).join(', ')}` : ''}`;
+  const planningGap = stamp.shardPlan?.unmeasured
+    || (stamp.selection?.shards !== undefined && result.shards !== stamp.selection.shards)
+    || (stamp.selection?.remote !== undefined && result.remote !== stamp.selection.remote);
+  const detail = stamp.summary && (stamp.outcome === 'unmeasured' || stamp.outcome === 'error' && planningGap) ? ` · ${stamp.summary}` : '';
+  return `${head} · 새 회귀 ${result.introduced ?? '못 쟀다'} · 기존 ${result.preexisting ?? '못 쟀다'} · 미분류 ${result.unclassified ?? '못 쟀다'} · ${result.remote ?? 'local'} · ${duration}분${stamp.outcome === 'error' ? ` · gate rc ${result.gateExitCode}${!result.ok ? ' · RC 실패' : ''}` : ''}${stamp.regressionFiles?.length ? ` · 파일 ${stamp.regressionFiles.slice(0, 3).join(', ')}` : ''}${detail}`;
 }
 
 function persistStamp(path: string, stamp: RehearsalStamp): void {
@@ -207,6 +233,12 @@ function interruptStamp(path: string, saved: RehearsalStamp, now: Date): Rehears
 
 /** wx claim is permanent per version/step; a crashed run is reported as interrupted without running RC twice. */
 export async function runRehearsalTick(opts: RehearsalOptions = {}, deps: RehearsalDeps = {}): Promise<RehearsalTickResult> {
+  if (opts.shards !== undefined && (!Number.isSafeInteger(opts.shards) || opts.shards < 1)) {
+    throw new Error(`release rehearsal tick: invalid --shards count: ${opts.shards}`);
+  }
+  if (opts.remote !== undefined && !isValidGateHost(opts.remote)) {
+    throw new Error(`release rehearsal tick: invalid --remote host: ${opts.remote}`);
+  }
   const root = opts.ledgerRoot ?? releaseLedgerRoot();
   const now = (deps.now ?? (() => new Date()))();
   const schedules = (deps.schedules ?? listSchedules)(root);
@@ -289,26 +321,50 @@ export async function runRehearsalTick(opts: RehearsalOptions = {}, deps: Rehear
             gitResult(git, ['checkout', '-q', '--detach', 'origin/main'], checkout);
             stamp.sha = gitResult(git, ['rev-parse', 'HEAD'], checkout);
             if (!stamp.sha) throw new Error('git rev-parse HEAD returned no sha');
+            const leak = (deps.leakCheck ?? runRehearsalLeakCheck)(checkout);
+            stamp.leakCheck = { outcome: leak.status === 0 ? 'ok' : 'fail', sha: stamp.sha, exitCode: leak.status };
+            if (leak.status !== 0) throw new Error(`public export leak-check failed (rc=${leak.status ?? 'spawn'})`);
             const regressionFiles: string[] = [];
-            const result = await (deps.lightRc ?? ((version, cwd) => runLightRc(version, { ledgerRoot: root, head: stamp.sha, rehearsalTui: true, log: (line) => {
-              for (const entry of line.split(/\r?\n/)) {
-                const file = /^- introduced: (.+?)(?: > |$)/.exec(entry)?.[1];
-                if (file && regressionFiles.length < 3) regressionFiles.push(file);
-              }
-              console.error(line);
-            } }, { cwd })))(plan.version, checkout);
+            const shardPlan = opts.shards === undefined ? (deps.shardPlan ?? planRehearsalShards)(plan.version, root, checkout, { ...deps.shardPlanDeps, remoteGate: true }) : undefined;
+            if (shardPlan) stamp.shardPlan = shardPlan;
+            const selection = { shards: opts.shards ?? shardPlan?.shards, remote: opts.remote };
+            stamp.selection = selection;
+            const result = await (deps.lightRc ?? ((version, cwd) => runLightRc(version, { ledgerRoot: root, head: stamp.sha, ...selection, rehearsalTui: true, log: (line) => {
+                for (const entry of line.split(/\r?\n/)) {
+                  const file = /^- introduced: (.+?)(?: > |$)/.exec(entry)?.[1];
+                  if (file && regressionFiles.length < 3) regressionFiles.push(file);
+                }
+                console.error(line);
+              } }, { cwd })))(plan.version, checkout, selection);
             stamp.result = result;
             if (regressionFiles.length) stamp.regressionFiles = regressionFiles;
-            stamp.outcome = result.introduced === null || result.unclassified === null ? 'unmeasured'
-              : result.introduced > 0 ? 'regression'
-              : result.unclassified > 0 ? 'unmeasured'
-              : !result.ok || result.gateExitCode !== 0 ? 'error' : 'ok';
-            stamp.summary = oneLine(`introduced ${result.introduced} · preexisting ${result.preexisting ?? 'unmeasured'} · unclassified ${result.unclassified} · ${result.remote ?? 'local'} · gate rc ${result.gateExitCode}${!result.ok ? ' · RC 실패' : ''}`);
+            const shardMismatch = selection.shards !== undefined && result.shards !== selection.shards
+              ? `selected shards ${selection.shards} but RC reported ${result.shards}` : null;
+            const remoteMismatch = opts.remote && result.remote !== opts.remote
+              ? `requested remote ${opts.remote} but RC reported ${result.remote ?? 'local'}` : null;
+            if (shardPlan?.remoteCapacityPending && result.remote && result.remote !== LIGHT_RC_UNKNOWN_HOST
+              && !remoteMismatch && result.unmeasured === null
+              && result.introduced !== null && result.unclassified === 0 && result.ok
+              && result.gateExitCode === 0 && !shardMismatch) {
+              // Only the completed RC can validate capacity of the actual remote host. Keep independent
+              // selection/RSS gaps; clear just the provisional remote-capacity gap.
+              stamp.shardPlan = { ...shardPlan, remoteCapacityPending: false, rssRevisionPending: false,
+                remoteCapacityVerifiedBy: result.remote,
+                unmeasured: shardPlan.planningGaps?.length ? shardPlan.planningGaps.join('; ') : null };
+            }
+            const planningGap = stamp.shardPlan?.unmeasured || shardMismatch || remoteMismatch;
+            const missingEvidence = result.introduced === null || result.unclassified === null
+              || result.unmeasured !== null || result.unclassified > 0 || !!planningGap;
+            stamp.outcome = result.introduced !== null && result.introduced > 0 ? missingEvidence ? 'unmeasured' : 'regression'
+              : result.introduced === null || result.unclassified === null || result.unmeasured !== null || result.unclassified > 0 ? 'unmeasured'
+              : result.unmeasured === null && (!result.ok || result.gateExitCode !== 0) ? 'error'
+              : planningGap ? 'unmeasured' : 'ok';
+            stamp.summary = oneLine(`introduced ${result.introduced} · preexisting ${result.preexisting ?? 'unmeasured'} · unclassified ${result.unclassified} · ${result.remote ?? 'local'} · gate rc ${result.gateExitCode}${!result.ok ? ' · RC 실패' : ''}${result.unmeasured !== null ? ` · unmeasured: ${result.unmeasured || 'RC reason empty'}` : ''}${stamp.shardPlan?.unmeasured ? ` · unmeasured: ${stamp.shardPlan.unmeasured}` : ''}${shardMismatch ? ` · unmeasured: ${shardMismatch}` : ''}${remoteMismatch ? ` · unmeasured: ${remoteMismatch}` : ''}`);
           }
         }
       } catch (error) {
         stamp.outcome = 'error';
-        stamp.summary = oneLine(String(error instanceof Error ? error.message : error).split(/\r?\n/, 1)[0] ?? 'unknown error');
+        stamp.summary = oneLine(`${String(error instanceof Error ? error.message : error).split(/\r?\n/, 1)[0] ?? 'unknown error'}${stamp.shardPlan?.unmeasured ? ` · unmeasured: ${stamp.shardPlan.unmeasured}` : ''}`);
       }
       await finish(path, stamp);
     }

package/src/repl/index.ts

@@ -30,6 +30,7 @@ import {
 import {
   resolveSessionId,
   loadSession,
+  listSessions,
   setActiveSessionId,
   getActiveSessionId,
 } from '../session/index.js';
@@ -41,6 +42,7 @@ import {
 } from '../user-config.js';
 import { setAmbientSessionId, debug } from '../debug/log.js';
 import { decideSigintAction } from './sigint.js';
+import { decideSessionStart, observeSessionStart } from '../session/session-start.js';
 import { buildReplayTurnsFromSession } from './replay.js';
 import type { LLMToolSpec, ContentBlock } from '../llm.js';
 import { inspectActiveProvider } from '../provider-summary.js';
@@ -58,6 +60,8 @@ export interface ReplOpts {
   initialSessionId: string | undefined;
   /** Force a fresh session even if active marker exists. */
   forceNew: boolean;
+  /** `--continue`/`--resume` — 활성 세션 이어하기(명시). 대표 #73: 기본은 새 세션. */
+  continueActive?: boolean;
   /** Enable the tool loop (Read/Grep/Bash/...). Default true — REPL
    *  is the agent surface; users opt out with --no-tools. */
   enableTools: boolean;
@@ -445,11 +449,25 @@ export async function runRepl(opts: ReplOpts): Promise<number> {
       return 1;
     }
     initialId = id;
-  } else if (!opts.forceNew) {
-    initialId = getActiveSessionId() ?? undefined;
   }
+  const startDecision = decideSessionStart({
+    ...(initialId ? { explicitSessionId: initialId } : {}),
+    continueActive: opts.continueActive === true,
+    forceNew: opts.forceNew,
+    activeSessionId: () => getActiveSessionId(),
+    // TUI-H8-FOLLOW ① — 활성 표지가 사라진 세션이면 최신 세션으로.
+    sessionExists: (id) => loadSession(id) !== null,
+    latestSessionId: () => listSessions({ limit: 1 })[0]?.id ?? null,
+  });
+  initialId = startDecision.sessionIdHint;
   const session = ensureCliSession(cfg, initialId);
   setActiveSessionId(session.id);
+  observeSessionStart({
+    surface: 'repl',
+    origin: initialId && session.id === initialId ? startDecision.origin : 'new',
+    reason: initialId && session.id !== initialId ? 'resume-target-missing' : startDecision.reason,
+    sessionId: session.id,
+  });
   setAmbientSessionId(session.id);
   if (!opts.jsonOutput && (!initialId || session.id !== initialId)) {
     try {

package/src/seat-loop/seat-knowhow.ts

@@ -0,0 +1,282 @@
+// ── Seat knowhow packs — RFC-seat-knowhow-packs-adaptive-knowledge-2026-10-11.md §A ──
+//
+// Loader for `내부 문서 `KNOWHOW`` v2 items plus the role charter
+// `내부 문서 `<자리>``. Replaces the two duplicate role-file reads inside
+// seat-loop.ts (gatherSeatInputs + inquire) — one loader, no 4,000-char cut
+// on the charter, one overall budget cap instead.
+//
+// Injection rules (§A3 ⊕ review must-fix 1):
+//   «사실»          = status active ⊕ last verification «참» ⊕ within half-life
+//   «참고(검증 안 됨)» = unproven / unverifiable(못잼) / expired half-life
+//   dropped          = any status outside active/unproven/unverifiable,
+//                     last verification «거짓»/future/invalid date,
+//                     상태 미선언 · 검증 미선언 — a card is injected
+//                     only with an explicit 상태 AND an explicit 검증 line;
+//                     a missing 상태 is never assumed to be `active`.
+//
+// Half-life (§A1): fact 14 · warning 30 · heuristic 90 · playbook 60 days,
+// case unlimited; kind defaults to fact when a card does not declare one.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export type KnowhowKind = 'fact' | 'warning' | 'heuristic' | 'playbook' | 'case';
+
+export const KNOWHOW_HALF_LIFE_DAYS: Record<KnowhowKind, number> = {
+  fact: 14,
+  warning: 30,
+  heuristic: 90,
+  playbook: 60,
+  case: Number.POSITIVE_INFINITY,
+};
+
+/** One overall budget cap for the whole injected pack (RFC §A3 — value
+ * unspecified in the ask; 32,000 chars adopted as the documented value for
+ * this slice, replacing the old per-chunk 4,000-char cuts).
+ *
+ * Budget policy (review must-fix 3) — whole items only, `text.slice` is never
+ * used: the charter, each block header, and each card enter the pack whole or
+ * not at all.
+ *   1. The charter is always kept whole and outranks every card.
+ *   2. Cards are appended whole in top-k order while the running total stays
+ *      within this cap; a card that would exceed it is skipped (a later,
+ *      smaller card may still fit).
+ *   3. A charter that alone exceeds the cap is still injected whole and both
+ *      card blocks are dropped entirely — the seat keeps its charter; slicing
+ *      the charter mid-way is exactly what this policy abolishes. */
+export const SEAT_PACK_TOTAL_BUDGET_CHARS = 32_000;
+export const DEFAULT_TOP_K = 8;
+
+export interface KnowhowItem {
+  kind: KnowhowKind;
+  /** Declared 상태 — '' when the card states none (never assumed active). */
+  status: string;
+  verifiedAt: Date | null;
+  /** true = 참 · false = 거짓 · null = 못잼/unproven */
+  verified: boolean | null;
+  text: string;
+}
+
+export interface SeatPack {
+  charter: string;
+  /** Card texts actually injected into `text` — never a superset of it. */
+  facts: string[];
+  refs: string[];
+  /** Cards refused by classification (contradicted·stale·superseded·거짓·
+   *  상태/검증 미선언). Cards skipped only by the budget are not counted. */
+  dropped: number;
+  text: string;
+}
+
+export interface SeatPackDeps {
+  repo?: string;
+  read?: (path: string) => string;
+  now?: () => Date;
+  topK?: number;
+}
+
+// 참/거짓 뒤 경계는 \b 대신 명시적 뒷자리 제한 — \w 가 ASCII 한정이라
+// 참(한글) 뒤에서는 \b 가 경계로 안 센다(실측: verified 가 null 로 흘렀다).
+const VERIFIED_TRUE_RE = /^\s*(\d{4}-\d{2}-\d{2})\s*참(?![^\s(·])/;
+const VERIFIED_FALSE_RE = /^\s*(\d{4}-\d{2}-\d{2})\s*거짓(?![^\s(·])/;
+const VERIFIED_UNVERIFIABLE_RE = /^\s*(\d{4}-\d{2}-\d{2})\s*못잼/;
+const FIELD_RE = /^-([^:]+):\s*(.*)$/;
+
+function calendarDate(isoDay: string): Date | null {
+  const date = new Date(`${isoDay}T00:00:00Z`);
+  return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === isoDay ? date : null;
+}
+
+export function parseKnowhowItems(body: string, seat: string): KnowhowItem[] {
+  const headerRe = new RegExp(`^##\\s+K-${seat.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d+`, 'i');
+  const items: KnowhowItem[] = [];
+  // First section before any card header is the document preamble — drop it.
+  const sections = body.split(/^##\s+/m);
+  for (const section of sections) {
+    const lines = section.split('\n');
+    const header = lines[0] ?? '';
+    if (!headerRe.test(`## ${header}`)) continue;
+    const rest = lines.slice(1).join('\n');
+    const fields: Record<string, string> = {};
+    let kind: KnowhowKind | null = null;
+    let status = '';
+    let verifiedAt: Date | null = null;
+    let verified: boolean | null = null;
+    for (const line of rest.split('\n')) {
+      const m = line.match(FIELD_RE);
+      if (m) {
+        const label = m[1].trim();
+        const value = m[2].trim();
+        fields[label] = value;
+        if (label === '종류' && value in KNOWHOW_HALF_LIFE_DAYS) {
+          kind = value as KnowhowKind;
+        } else if (label === '상태') {
+          status = value;
+        } else if (label === '검증') {
+          // A later verification line supersedes the earlier one even when
+          // malformed; otherwise an old «참» survives a failed new check.
+          verified = null;
+          verifiedAt = null;
+          const t = value.match(VERIFIED_TRUE_RE);
+          const f = value.match(VERIFIED_FALSE_RE);
+          const u = value.match(VERIFIED_UNVERIFIABLE_RE);
+          if (t) {
+            verified = true;
+            verifiedAt = calendarDate(t[1]);
+          } else if (f) {
+            verified = false;
+            verifiedAt = calendarDate(f[1]);
+          } else if (u) {
+            verified = null;
+            verifiedAt = calendarDate(u[1]);
+          }
+        }
+      }
+    }
+    // Inline `상태:`/`종류:` inside other fields (e.g. the 출처 line) also count.
+    for (const value of Object.values(fields)) {
+      if (!status) {
+        const s = value.match(/(?:^|·\s*|[·，,;|\s])상태:\s*(\S+)/);
+        if (s) status = s[1];
+      }
+      if (!kind) {
+        const k = value.match(/(?:^|·\s*|[·，,;|\s])종류:\s*(\S+)/);
+        if (k && k[1] in KNOWHOW_HALF_LIFE_DAYS) kind = k[1] as KnowhowKind;
+      }
+    }
+    items.push({
+      kind: kind ?? 'fact',
+      // Missing 상태 stays '' — the classifier refuses to inject it; the
+      // parser must not default a status-less card to `active` (must-fix 1).
+      status,
+      verifiedAt,
+      verified,
+      text: `## ${header}\n${rest}`.trim(),
+    });
+  }
+  return items;
+}
+
+function withinHalfLife(item: KnowhowItem, now: Date): boolean {
+  if (!item.verifiedAt) return false;
+  const ageMs = now.getTime() - item.verifiedAt.getTime();
+  if (!Number.isFinite(ageMs) || ageMs < 0) return false;
+  const days = KNOWHOW_HALF_LIFE_DAYS[item.kind];
+  if (!Number.isFinite(days)) return true;
+  return ageMs <= days * 24 * 60 * 60 * 1000;
+}
+
+/** «사실» vs «참고(검증 안 됨)» vs dropped(contradicted·stale·superseded·최근
+ * 검증 거짓·상태/검증 미선언). Only active/unproven/unverifiable are admitted;
+ * a future or invalid verification date is rejected. A card is injected only when it declares an
+ * explicit 상태 AND an explicit 검증 line; a card whose most recent
+ * verification is «거짓» is contradicted — dropped, never filed as
+ * «검증 안 됨» (review must-fix 1). */
+export function splitKnowhow(
+  items: KnowhowItem[],
+  now: Date,
+): { facts: KnowhowItem[]; refs: KnowhowItem[]; dropped: number } {
+  const facts: KnowhowItem[] = [];
+  const refs: KnowhowItem[] = [];
+  let dropped = 0;
+  for (const item of items) {
+    const allowedStatus = item.status === 'active' || item.status === 'unproven' || item.status === 'unverifiable';
+    const verifiedAtMs = item.verifiedAt?.getTime();
+    const lacksExplicitConditions = !Number.isFinite(verifiedAtMs) || item.verified === false
+      || verifiedAtMs! > now.getTime();
+    if (!allowedStatus || lacksExplicitConditions) {
+      dropped += 1;
+      continue;
+    }
+    if (item.verified === true && item.status === 'active' && withinHalfLife(item, now)) {
+      facts.push(item);
+    } else {
+      refs.push(item);
+    }
+  }
+  return { facts, refs, dropped };
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}_]+/u)
+    .filter((t) => t.length > 0);
+}
+
+/** Top-k by word overlap with the query (default k = 8). Ties keep pack order. */
+export function selectTopK(items: KnowhowItem[], query: string, k: number = DEFAULT_TOP_K): KnowhowItem[] {
+  const tokens = new Set(tokenize(query));
+  const scored = items.map((item, index) => {
+    const itemTokens = new Set(tokenize(item.text));
+    let score = 0;
+    for (const token of itemTokens) if (tokens.has(token)) score += 1;
+    return { item, score, index };
+  });
+  scored.sort((a, b) => b.score - a.score || a.index - b.index);
+  return scored.slice(0, Math.max(0, k)).map((s) => s.item);
+}
+
+/** Assemble the pack under SEAT_PACK_TOTAL_BUDGET_CHARS at whole-item
+ * granularity — see the policy on the constant. The `facts`/`refs` arrays in
+ * the result carry exactly the cards that made it into `text`. */
+function assemblePack(
+  charter: string,
+  rankedItems: KnowhowItem[],
+  factSet: ReadonlySet<KnowhowItem>,
+): { text: string; facts: string[]; refs: string[] } {
+  const SEP = '\n\n';
+  let used = charter.length;
+  const facts: string[] = [];
+  const refs: string[] = [];
+  // Budget in query rank order; rendering can still group facts before refs.
+  for (const item of rankedItems) {
+    const isFact = factSet.has(item);
+    const out = isFact ? facts : refs;
+    const header = isFact ? '### 사실 (검증된 노하우)' : '### 참고 (검증 안 됨)';
+    const cost = out.length === 0
+      ? (used > 0 ? SEP.length : 0) + header.length + SEP.length + item.text.length
+      : SEP.length + item.text.length;
+    if (used + cost > SEAT_PACK_TOTAL_BUDGET_CHARS) continue;
+    out.push(item.text);
+    used += cost;
+  }
+  let text = charter;
+  if (facts.length > 0) text += `${text ? SEP : ''}### 사실 (검증된 노하우)${SEP}${facts.join(SEP)}`;
+  if (refs.length > 0) text += `${text ? SEP : ''}### 참고 (검증 안 됨)${SEP}${refs.join(SEP)}`;
+  return { text, facts, refs };
+}
+
+export function loadSeatPack(seat: string, query = '', deps: SeatPackDeps = {}): SeatPack {
+  const repo = deps.repo ?? process.cwd();
+  const read = deps.read ?? ((path: string) => readFileSync(path, 'utf8'));
+  const now = deps.now ?? (() => new Date());
+  const charter = read(join(repo, 'docs', 'roles', `${seat}.md`)).trim();
+  const knowhowPath = join(repo, 'docs', 'roles', seat, 'KNOWHOW.md');
+  // NOTE: presence is decided by reading through `deps.read`, not existsSync —
+  // tests mount a virtual reader; a disk probe would report the virtual path
+  // missing and silently drop the whole KNOWHOW pack (observed: facts=0).
+  let knowhowBody = '';
+  try {
+    knowhowBody = read(knowhowPath);
+  } catch {
+    knowhowBody = '';
+  }
+  const items = parseKnowhowItems(knowhowBody, seat);
+  const { facts, refs, dropped } = splitKnowhow(items, now());
+  const topK = deps.topK ?? DEFAULT_TOP_K;
+  // One top-k pass over the whole candidate pool (facts ⊕ refs), then the
+  // winners are split back into their blocks in score order — applying k per
+  // block would inject up to 2k cards (review must-fix 2).
+  const selected = selectTopK([...facts, ...refs], query, topK);
+  const factSet = new Set(facts);
+  const pack = assemblePack(charter, selected, factSet);
+  debug.log('seat.loop', 'pack-loaded', {
+    seat,
+    facts: pack.facts.length,
+    refs: pack.refs.length,
+    dropped,
+  });
+  return { charter, facts: pack.facts, refs: pack.refs, dropped, text: pack.text };
+}