elanous 0.2.35 → 0.2.37

package/src/task-orchestrator/surfaces/self-implement.ts

@@ -30,6 +30,7 @@ import { isAbandonedClassification, type AbandonedClassificationResult } from '.
 import { createExecution, type Task, type TaskExecution } from '../types.js';
 import type { DispatchContext, DispatchResult } from '../surface-registry.js';
 import { nestedPodResult } from './pod-failure-reason.js';
+import { SCOPE_EXPANSION_CAP, SCOPE_STOP_REASONS, isProtectedScopePath, type ScopeStopReason } from '../../self-implement/scope-adjacency.js';
 
 /** Result of one self-implement subprocess. */
 export interface SelfImplementJobDone {
@@ -103,10 +104,19 @@ export interface PodChildEvidence {
   error?: string;
   detail?: string;
   stderr?: string;
+  /** Bounded, redacted complete Pod log tail. Separate from child stderr to avoid replacing stronger child facts. */
+  podLogTail?: string[];
+  podLogTailLines?: number;
+  podLogUnavailable?: string;
   exitCode?: number;
   classification?: string;
   scopeEscape?: true;
   outOfScopeEdits?: unknown;
+  /** SCOPE-ESCAPE-AS-REFINE — why held out-of-scope edits stop the run (deletion · protected path · cap). Present only with scopeEscape. */
+  scopeStopReasons?: ScopeStopReason[];
+  /** SCOPE-ESCAPE-AS-REFINE — «구현이 알려준 새 범위», not a failure: held names with no stop reason, or (no held names)
+   *  the accepted `scopeExpansion` paths of a child that failed later (e.g. gate). Evidence is built only for failed results. */
+  newScope?: string[];
   abandonedClassification?: Record<string, unknown>;
   supervisorVerdict?: unknown;
   goalCauseObserved?: true;
@@ -122,6 +132,34 @@ export interface PodChildEvidence {
   };
 }
 
+const SCOPE_STOP_REASON_ORDER: readonly ScopeStopReason[] = SCOPE_STOP_REASONS;
+
+/** Stop reasons for held out-of-scope edits: the child's own `scopeStopReasons` (orchestrator decideScopeExpansion) plus
+ *  what the names alone prove (protected path · count over SCOPE_EXPANSION_CAP · incomplete name list). A deletion is
+ *  only known from the child. Deterministic, fixed order. */
+export function scopeStopReasonsFromResult(o: Record<string, unknown>, outOfScopeEdits: unknown = o.outOfScopeEdits): ScopeStopReason[] {
+  const reasons = new Set<ScopeStopReason>();
+  if (Array.isArray(o.scopeStopReasons)) {
+    for (const reason of o.scopeStopReasons) if ((SCOPE_STOP_REASON_ORDER as readonly unknown[]).includes(reason)) reasons.add(reason as ScopeStopReason);
+  }
+  const names = Array.isArray(outOfScopeEdits) ? outOfScopeEdits.filter((name): name is string => typeof name === 'string') : [];
+  if (names.some(isProtectedScopePath)) reasons.add('protected-path');
+  const count = typeof o.outsideCount === 'number' ? Math.max(o.outsideCount, names.length) : names.length;
+  if (count > SCOPE_EXPANSION_CAP) reasons.add('over-cap');
+  if (o.nameCapReached === true) reasons.add('name-cap');
+  return SCOPE_STOP_REASON_ORDER.filter((reason) => reasons.has(reason));
+}
+
+/** «구현이 알려준 새 범위» — held names with no stop reason, else the accepted expansion's paths. */
+function newScopeFromResult(outOfScopeEdits: unknown, scopeExpansion: unknown): string[] | undefined {
+  const names = Array.isArray(outOfScopeEdits) ? outOfScopeEdits.filter((name): name is string => typeof name === 'string' && name.length > 0) : [];
+  if (names.length) return names.slice(0, 40);
+  const files = scopeExpansion && typeof scopeExpansion === 'object' ? (scopeExpansion as { files?: unknown }).files : undefined;
+  const paths = Array.isArray(files) ? files.map((file) => (file && typeof file === 'object' ? (file as { path?: unknown }).path : undefined))
+    .filter((path): path is string => typeof path === 'string' && path.length > 0) : [];
+  return paths.length ? paths.slice(0, 40).map((path) => redactSecretText(path)) : undefined;
+}
+
 /** Preserve only named terminal facts; the full child detail may contain logs or credentials. */
 export function podChildEvidenceFromResult(o: Record<string, unknown>): PodChildEvidence | undefined {
   const object = (value: unknown): Record<string, unknown> | undefined =>
@@ -146,8 +184,13 @@ export function podChildEvidenceFromResult(o: Record<string, unknown>): PodChild
   const failureExitCode = o.ok === false && typeof o.exitCode === 'number'
     && Number.isInteger(o.exitCode) && o.exitCode >= 0 && o.exitCode <= 255 ? o.exitCode : undefined;
   const outOfScopeEdits = scrubValue(o.outOfScopeEdits);
-  const scopeEscape = (Array.isArray(outOfScopeEdits) && outOfScopeEdits.length > 0)
+  const held = (Array.isArray(outOfScopeEdits) && outOfScopeEdits.length > 0)
     || (typeof o.detail === 'string' && /^Out-of-scope edits held in the worktree(?:[.;]|$)/i.test(o.detail.trim()));
+  // SCOPE-ESCAPE-AS-REFINE (대표 10-22 «범위 밖 허용도 로직으로») — held edits stop the run only for a deletion, a protected
+  //   path, or a cap; otherwise they are the new scope the implementation found and the exit is classified as if unheld.
+  const scopeStopReasons = held ? scopeStopReasonsFromResult(o, outOfScopeEdits) : [];
+  const scopeEscape = held && scopeStopReasons.length > 0;
+  const newScope = scopeEscape ? undefined : newScopeFromResult(outOfScopeEdits, o.scopeExpansion);
   const classification = scopeEscape ? 'scope-escape'
     : typeof abandoned?.classification === 'string' ? redactSecretText(abandoned.classification)
       : typeof o.failureClassification === 'string' ? redactSecretText(o.failureClassification) : undefined;
@@ -157,8 +200,9 @@ export function podChildEvidenceFromResult(o: Record<string, unknown>): PodChild
     ...(failedText(o.stderr) ? { stderr: failedText(o.stderr) } : {}),
     ...(failureExitCode !== undefined ? { exitCode: failureExitCode } : {}),
     ...(classification ? { classification } : {}),
-    ...(scopeEscape ? { scopeEscape: true } : {}),
+    ...(scopeEscape ? { scopeEscape: true, scopeStopReasons } : {}),
     ...(outOfScopeEdits !== undefined ? { outOfScopeEdits } : {}),
+    ...(newScope ? { newScope } : {}),
     ...(abandoned ? { abandonedClassification: abandoned } : {}),
     ...(o.supervisorVerdict !== undefined ? { supervisorVerdict: scrubValue(o.supervisorVerdict) } : {}),
     ...(o.goalCauseObserved === true ? { goalCauseObserved: true } : {}),

package/src/testing/linux-env.ts

@@ -0,0 +1,177 @@
+/**
+ * 🐧 LINUX-STAGE — 개발 머신 환경에 기대지 않는 «격리 무대».
+ *
+ * Situation: 같은 시험이 macOS(개발 머신)에서는 통과하고 Linux 에서는 실패하는 잔여 실패가 있다.
+ *   원인은 코드가 아니라 «환경»이다 — 개발 머신 HOME 의 글로벌 git user.* · PATH 에 있는 grok CLI ·
+ *   LANG/LC_ALL 이 정하는 콜레이션 · 로케일마다 달라지는 이모지 비교.
+ * Answer: 그 네 축을 «무대»로 고정한다 — 임시 HOME(글로벌 설정 없음), grok 이 없는 PATH,
+ *   저장소 로컬 identity 만 가진 git 작업 트리, C.UTF-8, 코드포인트 비교.
+ * ⛔ 이 무대는 «생산 진입점을 그대로 지나게» 하는 시험을 위한 것이다 — 소스 문자열 검사용이 아니다.
+ * ⛔ `withLinuxEnv` 는 끝나면 env 와 임시 디렉터리를 원상복구한다(같은 파일의 뒤 시험을 오염시키지 않는다).
+ */
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+/** 무대 로케일 — Linux CI 의 기본값(LANG 미설정 · POSIX)을 넘긴다. */
+export const STAGE_LOCALE = 'C.UTF-8';
+
+/** 무대 git 신원 — 글로벌 설정이 아니라 저장소 로컬에만 박는다. */
+export const STAGE_GIT_IDENTITY = { name: 'Elanous Stage', email: 'stage@elanous.test', branch: 'main' } as const;
+
+export interface LinuxEnvStage {
+  /** 무대 루트(시험 끝에 통째로 지운다). */
+  readonly root: string;
+  /** 임시 HOME — `.gitconfig` 가 없다(글로벌 git 신원 없음). */
+  readonly home: string;
+  /** ELANOUS_STATE_DIR — config-dir 이 이 경로를 따라가므로 둘 다 격리된다. */
+  readonly state: string;
+  /** 무대 git 작업 트리(저장소 로컬 identity 만). */
+  readonly repo: string;
+  /** PATH 앞머리 — grok 이 없는 빈 디렉터리. */
+  readonly bin: string;
+  readonly env: Record<string, string>;
+}
+
+const ENV_KEYS = [
+  'HOME',
+  'ELANOUS_STATE_DIR',
+  'ELANOUS_STATE_DIR_SOURCE',
+  'ELANOUS_CONFIG_DIR',
+  'LANG',
+  'LC_ALL',
+  'TZ',
+  'PATH',
+  'GIT_CONFIG_GLOBAL',
+  'GIT_CONFIG_SYSTEM',
+  'GIT_AUTHOR_NAME',
+  'GIT_AUTHOR_EMAIL',
+  'GIT_COMMITTER_NAME',
+  'GIT_COMMITTER_EMAIL',
+] as const;
+
+/** 무대 PATH 의 시스템 꼬리 — grok 이 깔린 디렉터리는 «걸러낸다»(머신마다 설치 위치가 다르다). */
+const SYSTEM_PATH = ['/usr/local/bin', '/usr/bin', '/bin'];
+
+/** 무대를 만들기만 한다(env 적용은 `withLinuxEnv`). */
+export function createLinuxEnvStage(): LinuxEnvStage {
+  const root = mkdtempSync(join(tmpdir(), 'elanous-linux-env-'));
+  const home = join(root, 'home');
+  const repo = join(root, 'repo');
+  const bin = join(root, 'bin');
+  const state = join(repo, '.elanous');
+  for (const dir of [home, repo, bin, state]) mkdirSync(dir, { recursive: true });
+  const env: Record<string, string> = {
+    HOME: home,
+    // ELANOUS_CONFIG_DIR 는 state 를 따라가는 것이 정본이므로 따로 두지 않는다(무시 경고 방지).
+    ELANOUS_STATE_DIR: state,
+    ELANOUS_STATE_DIR_SOURCE: 'explicit',
+    LANG: STAGE_LOCALE,
+    LC_ALL: STAGE_LOCALE,
+    TZ: 'UTC',
+    PATH: [bin, ...SYSTEM_PATH.filter((dir) => !existsSync(join(dir, 'grok')))].join(delimiter),
+    // 글로벌·시스템 git 설정을 read 자체에서 끊는다 — 개발 머신 설정이 새어 들어올 길을 없앤다.
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_CONFIG_SYSTEM: '/dev/null',
+  };
+  return { root, home, state, repo, bin, env };
+}
+
+/**
+ * 무대 env 로 `fn` 을 돌리고 원상복구한다.
+ * `ELANOUS_STATE_DIR` 가 정해지면 config-dir 도 그 아래로 오므로(config 정본 = state) 저장소·HOME 오염이 없다.
+ */
+export async function withLinuxEnv<T>(fn: (stage: LinuxEnvStage) => T | Promise<T>): Promise<T> {
+  const stage = createLinuxEnvStage();
+  const saved = ENV_KEYS.map((key) => [key, process.env[key]] as const);
+  delete process.env.ELANOUS_CONFIG_DIR;
+  for (const [key, value] of Object.entries(stage.env)) process.env[key] = value;
+  // 개발 머신이 물려준 author/committer env 가 저장소 로컬 identity 증명을 가리지 않게 걷어낸다.
+  for (const key of ['GIT_AUTHOR_NAME', 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_NAME', 'GIT_COMMITTER_EMAIL']) delete process.env[key];
+  try {
+    return await fn(stage);
+  } finally {
+    for (const [key, value] of saved) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+    rmSync(stage.root, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 무대 env 를 «명시» 해서 자식 프로세스를 띄운다.
+ * ⛔ bun 1.4.2 는 `process.env.PATH` 를 바꾸는 순간 이후 spawn 한 자식의 environ 을 기동 시 스냅샷으로
+ * 재구성한다 — HOME 등 다른 키의 JS 측 변이가 자식에 새지 않는다(실측: PATH assign 뒤 `env` 자식의
+ * HOME 이 원래 값으로 되돌아감). ambient 상속에 기대지 말고 무대 안의 자식은 반드시 이 함수로 띄운다.
+ * in-process(process.env 를 직접 읽는 코드)는 `withLinuxEnv` 의 변이가 그대로 보인다.
+ */
+export function stageSpawnSync(
+  stage: LinuxEnvStage,
+  file: string,
+  args: string[],
+  opts: { cwd?: string } = {},
+): SpawnSyncReturns<string> {
+  return spawnSync(file, args, {
+    cwd: opts.cwd ?? stage.repo,
+    env: { ...process.env, ...stage.env },
+    encoding: 'utf8',
+  });
+}
+
+/** 무대 PATH 에서 그 명령이 실행 가능한가 — Linux CI 에 grok 이 없다는 사실을 «재는» 데 쓴다. */
+export function stageHasCommand(stage: LinuxEnvStage, name: string): boolean {
+  return (stage.env.PATH ?? '').split(delimiter).some((dir) => {
+    if (!dir) return false;
+    try {
+      accessSync(join(dir, name), constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** 무대 HOME 에 글로벌 git 신원이 있는가 — 무대에서는 false 여야 한다. */
+export function hasGlobalGitIdentity(stage: LinuxEnvStage): boolean {
+  return existsSync(join(stage.home, '.gitconfig')) || existsSync(join(stage.home, '.config', 'git', 'config'));
+}
+
+function gitInStage(stage: LinuxEnvStage, args: string[]): string {
+  const result = stageSpawnSync(stage, 'git', args);
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`git ${args.join(' ')} 실패(rc=${result.status}): ${result.stderr.trim()}`);
+  return result.stdout.trim();
+}
+
+/**
+ * 무대 작업 트리를 «저장소 로컬 identity 만» 으로 초기화하고 첫 커밋까지 만든다.
+ * 커밋이 성공했다는 것 자체가 user.name/user.email 이 로컬 설정으로 먹었다는 실물 증거다.
+ */
+export function initGitWithExplicitIdentity(stage: LinuxEnvStage): void {
+  gitInStage(stage, ['-c', `init.defaultBranch=${STAGE_GIT_IDENTITY.branch}`, 'init', '--quiet']);
+  gitInStage(stage, ['config', 'user.name', STAGE_GIT_IDENTITY.name]);
+  gitInStage(stage, ['config', 'user.email', STAGE_GIT_IDENTITY.email]);
+  gitInStage(stage, ['config', 'init.defaultBranch', STAGE_GIT_IDENTITY.branch]);
+  writeFileSync(join(stage.repo, 'README.md'), '# linux stage\n');
+  gitInStage(stage, ['add', 'README.md']);
+  gitInStage(stage, ['commit', '--quiet', '-m', 'stage: 초기 커밋']);
+}
+
+/** 무대 작업 트리의 실제 git 정체 — 로컬 설정과 현재 브랜치를 읽어 온다. */
+export function gitStageIdentity(stage: LinuxEnvStage): { name: string; email: string; branch: string } {
+  return {
+    name: gitInStage(stage, ['config', '--get', 'user.name']),
+    email: gitInStage(stage, ['config', '--get', 'user.email']),
+    branch: gitInStage(stage, ['symbolic-ref', '--short', 'HEAD']),
+  };
+}
+
+/**
+ * 문자열을 «코드포인트» 단위로 쪼갠다 — `'🎉party'.length` 는 7(UTF-16)이지만 코드포인트는 6이다.
+ * 로케일·인코딩에 따라 이모지 비교가 흔들리는 자리를 코드포인트로 고정한다.
+ */
+export function codePoints(value: string): string[] {
+  return [...value];
+}

package/src/tool-runtime/index.ts

@@ -73,11 +73,18 @@ import { bootstrapMcpProxyRuntimes } from './mcp-proxy-bootstrap.js';
 import { SELF_COGNITION_RUNTIMES } from './self-cognition-runtimes.js';
 import { ELANOUS_CONTROL_RUNTIMES } from './elanous-control-runtimes.js';
 
+export interface RegisterAllDefaultToolRuntimesOpts {
+  /** CLASSIC-IDLE-MCP-LAZY — classic TUI 만 켠다. 외부 MCP 프록시를 «첫 도구
+   *  호출» 때 띄우고, 그 전엔 지난 부팅의 툴 인덱스로 목록만 알린다.
+   *  데몬·`mcp serve` 는 기본값(즉시 기동) 그대로다. */
+  mcpLazyBoot?: boolean;
+}
+
 /** Register every built-in runtime. Idempotent — safe to call more
  *  than once (registry dedupe). Call from the dashboard boot path;
  *  skills pick up registrations via side-effect when this module
  *  gets imported. */
-export function registerAllDefaultToolRuntimes(): void {
+export function registerAllDefaultToolRuntimes(opts: RegisterAllDefaultToolRuntimesOpts = {}): void {
   for (const rt of PTY_RUNTIMES) registerToolRuntime(rt);
   registerToolRuntime(terminalInjectRuntime);
   registerToolRuntime(bashRuntime);
@@ -170,7 +177,13 @@ export function registerAllDefaultToolRuntimes(): void {
   // External MCP proxies already declare surfaces `['mcp','tui']`, but the
   // TUI process never registered them. Fire-and-forget: handshake must not
   // block TUI startup; failures stay queryable via diagnostics.
-  bootstrapMcpProxyRuntimes();
+  // CLASSIC-IDLE-MCP-LAZY: classic TUI 는 지연 기동 — 자식 둘(약 267MB)을
+  // 기동 때 상주시키지 않고, 첫 도구 호출 때 한 번 띄운다.
+  if (opts.mcpLazyBoot === true) {
+    bootstrapMcpProxyRuntimes({ lazy: true });
+  } else {
+    bootstrapMcpProxyRuntimes();
+  }
 }
 
 export { setTerminalInjectApprover } from './terminal-inject-runtime.js';

package/src/tool-runtime/mcp-proxy-bootstrap.ts

@@ -51,6 +51,10 @@ export interface BootstrapMcpProxyRuntimesOpts {
   registerRuntime?: typeof registerToolRuntime;
   logger?: McpBootLogger;
   handshakeTimeoutMs?: number;
+  /** CLASSIC-IDLE-MCP-LAZY — classic TUI 만 켠다. MCP 자식을 «첫 도구 호출»
+   *  때 띄우고, 그 전엔 지난 부팅의 툴 인덱스로 목록만 알린다. */
+  lazy?: boolean;
+  toolIndexStore?: RegisterMcpClientsOpts['toolIndexStore'];
 }
 
 const IDLE: McpProxyBootstrapSnapshot = {
@@ -62,6 +66,8 @@ const IDLE: McpProxyBootstrapSnapshot = {
 
 let testOpts: BootstrapMcpProxyRuntimesOpts | null = null;
 let activeHandle: McpProxyBootstrapHandle | undefined;
+let activeClients: McpClientsHandle | undefined;
+let exitHookInstalled = false;
 let lastSnapshot: McpProxyBootstrapSnapshot = IDLE;
 let bootGeneration = 0;
 
@@ -75,6 +81,7 @@ export function setMcpProxyBootstrapOptsForTest(opts: BootstrapMcpProxyRuntimesO
 export function _resetMcpProxyBootstrapForTest(): void {
   bootGeneration += 1;
   activeHandle = undefined;
+  activeClients = undefined;
   lastSnapshot = IDLE;
 }
 
@@ -86,6 +93,24 @@ export function getMcpProxyBootstrapHandle(): McpProxyBootstrapHandle | undefine
   return activeHandle;
 }
 
+/** 프로세스가 «그냥» 죽는 경로(exit 훅)에서도 MCP 자식이 고아로 남지 않게 마지막
+ *  SIGTERM 을 건다. `process.on('exit')` 은 await 할 수 없으므로 동기 kill 만 쓴다. */
+function installMcpExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.once('exit', () => {
+    const clients = activeClients;
+    activeClients = undefined;
+    if (!clients) return;
+    try {
+      const terminated = clients.terminateChildrenSync?.() ?? 0;
+      if (terminated > 0) log('exit-terminate', { terminated });
+    } catch {
+      /* dying process — never throw from an exit hook */
+    }
+  });
+}
+
 function observabilityBootLogger(): McpBootLogger {
   return {
     info: (line) => {
@@ -183,11 +208,15 @@ export function bootstrapMcpProxyRuntimes(
         ...(resolved.handshakeTimeoutMs !== undefined
           ? { handshakeTimeoutMs: resolved.handshakeTimeoutMs }
           : {}),
+        ...(resolved.lazy === true ? { lazy: true } : {}),
+        ...(resolved.toolIndexStore ? { toolIndexStore: resolved.toolIndexStore } : {}),
       });
       if (generation !== bootGeneration) {
         try { await result.shutdown(); } catch { /* abandoned boot */ }
         return current;
       }
+      activeClients = result;
+      installMcpExitHook();
       const snap = freezeSnapshot({
         status: 'ready',
         registered: result.registered,

package/src/tty-foreground.ts

@@ -0,0 +1,155 @@
+// TUI-SIGTTIN-SUSPEND (0.2.36 · 10-23 n8n) — the TUI must not be stopped because a child stole its terminal.
+//
+// Observed: the TUI's process group was no longer the foreground group of its own tty, its next stdin
+// read raised SIGTTIN and zsh printed «suspended (tty input)» (state T). The trigger was an interactive
+// login shell (`$SHELL -l -i -c printenv`, shell-env-bootstrap.ts) that opened /dev/tty for job control,
+// moved the terminal to its own group and never gave it back. The root fix runs that capture with no
+// controlling tty (`detached`). This module is the defence for any other child that does the same:
+//
+//   ① every tick, compare tcgetpgrp(stdin) with our own group;
+//   ② if the foreground group is gone, or it is led by one of our own descendants (or its leader is
+//      dead), it was taken by a child of ours → take it back (SIGTTOU ignored for that one call);
+//   ③ if a live process that is NOT ours holds it (the user's shell after a real job-control action),
+//      do not fight it — log `tui.lifecycle background-tty` once.
+//
+// Shared by both TUIs: `initTui()` (src/tui.ts) starts it for the classic dashboard and `--tui next`.
+
+import { spawnSync } from 'node:child_process';
+import { debug } from './debug/log.js';
+
+export interface ForegroundFacts {
+  /** Our process group id (getpgrp()). */
+  ownPgid: number;
+  /** tcgetpgrp(stdin) — -1 when it could not be read (stdin is not our controlling tty). */
+  ttyPgid: number;
+  /** Some process still exists in ttyPgid (kill(-ttyPgid, 0)). */
+  groupAlive: boolean;
+  /** The group leader (pid === ttyPgid) still exists. */
+  leaderAlive: boolean;
+  /** The group leader is one of our descendants. */
+  leaderIsDescendant: boolean;
+}
+
+export type ForegroundVerdict =
+  | { action: 'ok' }
+  | { action: 'unknown' }
+  | { action: 'reclaim'; reason: 'fg-group-gone' | 'fg-leader-gone' | 'fg-held-by-our-child'; ttyPgid: number }
+  | { action: 'yield'; ttyPgid: number };
+
+/** Pure decision — see the header for the rule. */
+export function decideForeground(f: ForegroundFacts): ForegroundVerdict {
+  if (f.ttyPgid < 0 || f.ownPgid < 0) return { action: 'unknown' };
+  if (f.ttyPgid === f.ownPgid) return { action: 'ok' };
+  if (!f.groupAlive) return { action: 'reclaim', reason: 'fg-group-gone', ttyPgid: f.ttyPgid };
+  if (!f.leaderAlive) return { action: 'reclaim', reason: 'fg-leader-gone', ttyPgid: f.ttyPgid };
+  if (f.leaderIsDescendant) return { action: 'reclaim', reason: 'fg-held-by-our-child', ttyPgid: f.ttyPgid };
+  return { action: 'yield', ttyPgid: f.ttyPgid };
+}
+
+export interface ForegroundDeps {
+  tcgetpgrp(): number;
+  getpgrp(): number;
+  /** tcsetpgrp(stdin, pgid) with SIGTTOU ignored for the call. Returns true on success. */
+  reclaim(pgid: number): boolean;
+  alive(pid: number): boolean;
+  isDescendant(pid: number): boolean;
+  log(event: string, data: Record<string, unknown>): void;
+}
+
+function exists(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (e) { return (e as { code?: string }).code === 'EPERM'; }
+}
+
+/** Walks ppid from `pid` up to 1 and reports whether it passes through us. Only runs on an anomaly. */
+function isOurDescendant(pid: number): boolean {
+  let cur = pid;
+  for (let i = 0; i < 64 && cur > 1; i++) {
+    const r = spawnSync('ps', ['-o', 'ppid=', '-p', String(cur)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1000 });
+    const ppid = Number.parseInt(String(r.stdout ?? '').trim(), 10);
+    if (!Number.isFinite(ppid) || ppid <= 0) return false;
+    if (ppid === process.pid) return true;
+    cur = ppid;
+  }
+  return false;
+}
+
+type Libc = { tcgetpgrp(fd: number): number; tcsetpgrp(fd: number, pgid: number): number; getpgrp(): number; signal(sig: number, handler: number | bigint): number | bigint };
+
+let libcCache: Libc | null | undefined;
+function libc(): Libc | null {
+  if (libcCache !== undefined) return libcCache;
+  libcCache = null;
+  const path = process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : process.platform === 'linux' ? 'libc.so.6' : null;
+  if (!path || typeof (globalThis as { Bun?: unknown }).Bun === 'undefined') return null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { dlopen, FFIType } = require('bun:ffi') as typeof import('bun:ffi');
+    const lib = dlopen(path, {
+      tcgetpgrp: { args: [FFIType.i32], returns: FFIType.i32 },
+      tcsetpgrp: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      getpgrp: { args: [], returns: FFIType.i32 },
+      // sig_t signal(int, sig_t) — the handler is a pointer; i64 carries it in the same register.
+      signal: { args: [FFIType.i32, FFIType.i64], returns: FFIType.i64 },
+    });
+    libcCache = lib.symbols as unknown as Libc;
+  } catch {
+    libcCache = null;
+  }
+  return libcCache;
+}
+
+const SIGTTOU = 22; // darwin and linux
+const SIG_IGN = 1;
+
+export function defaultForegroundDeps(): ForegroundDeps | null {
+  const c = libc();
+  if (!c) return null;
+  return {
+    tcgetpgrp: () => c.tcgetpgrp(0),
+    getpgrp: () => c.getpgrp(),
+    reclaim: (pgid) => {
+      // A background tcsetpgrp raises SIGTTOU unless it is ignored — ignore it for this one call only.
+      const prev = c.signal(SIGTTOU, SIG_IGN);
+      try { return c.tcsetpgrp(0, pgid) === 0; } finally { c.signal(SIGTTOU, prev); }
+    },
+    alive: exists,
+    isDescendant: isOurDescendant,
+    log: (event, data) => debug.log('tui.lifecycle', event, data),
+  };
+}
+
+/** One check. Exported for tests; the guard calls it on a timer. `state.yieldedTo` keeps the yield log to once per holder. */
+export function checkForeground(deps: ForegroundDeps, state: { yieldedTo: number | null } = { yieldedTo: null }): ForegroundVerdict {
+  const ownPgid = deps.getpgrp();
+  const ttyPgid = deps.tcgetpgrp();
+  if (ttyPgid < 0 || ttyPgid === ownPgid) {
+    state.yieldedTo = null;
+    return decideForeground({ ownPgid, ttyPgid, groupAlive: true, leaderAlive: true, leaderIsDescendant: false });
+  }
+  if (state.yieldedTo === ttyPgid) return { action: 'yield', ttyPgid };
+  const groupAlive = deps.alive(-ttyPgid);
+  const leaderAlive = groupAlive && deps.alive(ttyPgid);
+  const leaderIsDescendant = leaderAlive && deps.isDescendant(ttyPgid);
+  const verdict = decideForeground({ ownPgid, ttyPgid, groupAlive, leaderAlive, leaderIsDescendant });
+  if (verdict.action === 'reclaim') {
+    const ok = deps.reclaim(ownPgid);
+    deps.log(ok ? 'foreground-reclaimed' : 'foreground-reclaim-failed', { reason: verdict.reason, ttyPgid, ownPgid });
+  } else if (verdict.action === 'yield') {
+    state.yieldedTo = ttyPgid;
+    deps.log('background-tty', { ttyPgid, ownPgid, groupAlive, leaderAlive });
+  }
+  return verdict;
+}
+
+/** Starts the guard; returns stop(). No-op (returns a no-op) when libc/FFI is unavailable. */
+export function startForegroundGuard(opts: { intervalMs?: number; deps?: ForegroundDeps | null } = {}): () => void {
+  if (process.env.ELANOUS_TTY_FOREGROUND_GUARD === '0') return () => {};
+  const deps = opts.deps === undefined ? defaultForegroundDeps() : opts.deps;
+  if (!deps) return () => {};
+  const state = { yieldedTo: null as number | null };
+  const tick = (): void => { try { checkForeground(deps, state); } catch { /* fail-soft */ } };
+  tick();
+  const timer = setInterval(tick, opts.intervalMs ?? 250);
+  (timer as { unref?: () => void }).unref?.();
+  return () => clearInterval(timer);
+}