elanous 0.2.32 → 0.2.35

package/src/prompt-library/gpt6-family-addendum.ts

@@ -152,6 +152,18 @@ Do not write tests for reversible, low-impact changes that mirror the implementa
 
 Run tests appropriate to the change and complete required checks. Once those pass, broaden or repeat testing only when new changes, failures, or unresolved concerns justify it; otherwise, continue toward completing the task.`;
 
+// ⭐ 2026-10-18 신설 — ***진행 설명.*** ⛔ 공식 문면이 아니다 — 이 저장소 `codex-family-addendum.ts`
+//   «Narrate Before Each Tool Batch» 절을 줄여 옮겼다(gpt-5 계열만 그 절을 받았다).
+//   🩸 계기(결함 #87 · 대표 10-18): OPT(`gpt-6-sol`) 30분 19라운드 전부 `llm.stream consume-end`
+//     `textChars=0` — 도구만 연달아 부르고 «무엇을 하는지» 한 줄도 안 냈다. TUI 가 숨긴 것이 아니다.
+//   ⛔ 효과는 `consume-end` 의 `textChars>0` 라운드 비율로 잰다(전: 0/19).
+const GPT6_PROGRESS_NARRATION = `## Progress narration (elanous TUI)
+
+Before each batch of tool calls, write one short plain-text sentence in the user's language
+saying what you are about to check and why. After the batch, if the next step changes, say
+so in one sentence. Do not narrate routine bookkeeping calls (mailbox checks, wake-up
+scheduling) one by one.`;
+
 /** 사람이 찾을 수 있게 «출처»를 산출에도 남긴다 — ⛔ 이 줄이 없으면 다음 사람이 창작으로 읽는다. */
 export const GPT6_ADDENDUM_SOURCE =
   'Source: OpenAI GPT-6 Astra prompting guidance '
@@ -160,7 +172,7 @@ export const GPT6_ADDENDUM_SOURCE =
   + 'codex-rs/models-manager/models.json. Quoted, not paraphrased.';
 
 /**
- * GPT-6(astra) 계열 행동 규율을 시스템 메시지 넷으로 낸다.
+ * GPT-6(astra) 계열 행동 규율을 시스템 메시지로 낸다(공식 넷 ⊕ 범위 ⊕ 진행 설명).
  * ⛔ 순서가 뜻을 갖는다 — ***자율 → 허락의 시점 → 우선순위 → 시험***.
  *    금지(우선순위)보다 «자율»을 먼저 둔다: 이 저장소의 앵커가 이미 금지로 가득하고,
  *    관측된 실패가 ***「멈춤」***이었기 때문이다.
@@ -172,5 +184,6 @@ export function buildGpt6FamilyAddendum(): LLMMessage[] {
     { role: 'system', content: GPT6_INSTRUCTION_PRECEDENCE },
     { role: 'system', content: GPT6_TESTING_CALIBRATION },
     { role: 'system', content: GPT6_SCOPE_DISCIPLINE },
+    { role: 'system', content: GPT6_PROGRESS_NARRATION },
   ];
 }

package/src/pty-shell/herdr-agent-report.ts

@@ -0,0 +1,442 @@
+// herdr pane 안의 elanous TUI 가 스스로 에이전트로 신고한다.
+// 전경 프로세스 이름(bun …/elanous.mjs)은 herdr 내장 감지 목록 밖이라
+// `herdr agent list` 에 안 잡힌다 — pane CLI 로 생애·세션을 직접 알린다.
+//
+// 활성은 HERDR_ENV=1 ⊕ HERDR_PANE_ID ⊕ 킬스위치가 아닐 때뿐.
+// 실패(rc≠0·timeout·spawn·ENOENT)는 던지지 않고 한 번 로그한 뒤 그 신고기를 끈다.
+//
+// herdr 는 같은 pane·source 에서 «직전보다 큰 seq» 만 받는다(작으면 rc0 인데 무시).
+// 같은 pane 에서 TUI 를 다시 띄워도 신고가 살도록 seq 는 max(직전+1 · 시각 · pane 기록+1) 이다.
+// pane 기록 = 그 pane 에서 마지막으로 낸 seq(기본 tmpdir 파일) — 같은 ms 재기동·시계 역행에도 뒤 프로세스가 앞 프로세스보다 크다.
+// ⛔ 턴 경로는 파일을 안 만진다: 기록은 start 때 한 번 읽고, release(원래 동기인 종료 경로)에서만 쓴다.
+// 기록을 못 읽고 못 쓰면(관측 `seq-store-failed` 한 번) 시각·직전+1 로만 간다.
+// 한계: release 없이 죽은 프로세스의 마지막 seq 는 기록되지 않는다 — 그때 뒤 프로세스는 시각에 기댄다.
+//
+// 실패로 꺼지는 것은 «이후 turn» 뿐이다. release(권한 반납)는 start 실패가 «확인»됐을 때만 건너뛴다.
+// start 의 비동기 신고가 아직 안 끝났으면(결과 모름) 반납을 미루지 않고 바로 동기로 시도한다(관측 `release-start-pending`) —
+// 종료 경로에서 미루면 exit 뒤 반납이 영영 안 나간다. 반납 실패(rc≠0 등)는 `release-failed` 로 늘 남긴다.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { debug } from '../debug/log.js';
+
+/** 턴 값 — tui-run-state 의 PtyTurnState 와 같은 낱말이지만 순환 import 를 피하려 여기 둔다. */
+export type HerdrTurn = 'busy' | 'idle';
+
+export interface HerdrRunResult {
+  readonly ok: boolean;
+  readonly stderr?: string;
+}
+
+export interface HerdrRunOpts {
+  readonly sync: boolean;
+  readonly timeoutMs: number;
+}
+
+export type HerdrRunner = (
+  argv: string[],
+  opts: HerdrRunOpts,
+) => HerdrRunResult | Promise<HerdrRunResult>;
+
+export interface HerdrAgentReporterDeps {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly run?: HerdrRunner;
+  readonly log?: (event: string, data: Record<string, unknown>) => void;
+  readonly sessionId?: string;
+  /** seq 시작값의 시계(ms). 기본 Date.now. */
+  readonly now?: () => number;
+  /** pane 별 마지막 seq 기록. 기본 = tmpdir 파일(`createFileSeqStore`). */
+  readonly seqStore?: HerdrSeqStore;
+}
+
+/** 같은 pane 에서 마지막으로 낸 seq — 프로세스 사이 단조를 잇는다. 실패는 던져도 된다(신고기가 삼킨다). */
+export interface HerdrSeqStore {
+  read(): number | undefined;
+  write(seq: number): void;
+}
+
+export function defaultHerdrSeqDir(): string {
+  return join(tmpdir(), 'elanous-herdr-seq');
+}
+
+/** pane 하나의 seq 기록 파일. 파일 이름은 pane id 의 안전 문자만. */
+export function createFileSeqStore(paneId: string, dir: string = defaultHerdrSeqDir()): HerdrSeqStore {
+  const path = join(dir, `${paneId.replace(/[^A-Za-z0-9._-]/g, '_')}.seq`);
+  return {
+    read() {
+      let text: string;
+      try { text = readFileSync(path, 'utf8'); } catch (error) {
+        if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return undefined;
+        throw error;
+      }
+      const n = Number(text.trim());
+      return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+    },
+    write(seq) {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(path, String(seq), 'utf8');
+    },
+  };
+}
+
+export interface HerdrAgentReporterLike {
+  start(): void;
+  turn(t: HerdrTurn): void;
+  release(): void;
+}
+
+const ASYNC_TIMEOUT_MS = 2000;
+const SYNC_TIMEOUT_MS = 300;
+const STDERR_HEAD = 240;
+const STDOUT_CAP = 4096;
+/** herdr «Integrate your own agent» — 내장 감지가 아닌 자기 신고는 custom: 접두. */
+const HERDR_SOURCE = 'custom:elanous';
+const HERDR_AGENT = 'elanous';
+
+const defaultLog = (event: string, data: Record<string, unknown>): void => {
+  debug.log('pty.herdr', event, data);
+};
+
+function stderrHead(stderr: string | undefined): string {
+  if (!stderr) return '';
+  return stderr.length <= STDERR_HEAD ? stderr : stderr.slice(0, STDERR_HEAD);
+}
+
+/**
+ * herdr pane CLI 는 실패를 stdout JSON `{"error":{"code","message"}}` 로 낸다(10-18 실측 · pane_not_found 는 rc1).
+ * rc 가 0 이어도 이 봉투가 있으면 실패다(r4 리뷰 mf) — 오류 문면을 돌려준다. 봉투가 없으면 undefined.
+ */
+export function herdrJsonError(stdout: string | undefined): string | undefined {
+  const text = stdout?.trim();
+  // herdr 0.9.1 실측: 성공은 rc0 + 빈 stdout, 오류는 stdout JSON 봉투(10-18 live README).
+  // 비어 있지 않은 응답은 전체가 JSON 이어야 한다 — 아니면 깨진 응답(#29077 리뷰 mf).
+  if (!text) return undefined;
+  try {
+    const parsed = JSON.parse(text) as { error?: unknown };
+    if (!parsed || typeof parsed !== 'object' || parsed.error === undefined || parsed.error === null) return undefined;
+    const e = parsed.error as { code?: unknown; message?: unknown };
+    const code = typeof e.code === 'string' ? e.code : '';
+    const message = typeof e.message === 'string' ? e.message : (typeof parsed.error === 'string' ? parsed.error : '');
+    return [code, message].filter((s) => s.length > 0).join(': ') || 'herdr error';
+  } catch {
+    // JSON 이 아니다 = 잘렸거나 깨진 응답 — 봉투인지 모르니 성공으로 읽지 않는다(r8·#29077 리뷰 mf).
+    return 'unparseable-json';
+  }
+}
+
+/** rc·stdout·stderr 로 결과를 정한다 — JSON error 봉투·깨진 JSON·상한 넘침은 rc 와 무관하게 실패, 오류 문면은 봉투 → stderr 순. */
+function judgeHerdr(code: number | null, stdout: string, stderr: string, stdoutOverflow = false): HerdrRunResult {
+  // 상한을 넘었다 = 응답을 끝까지 못 봤다 — 봉투 판정을 보장할 수 없으니 «측정 불가» 로 실패(r8 리뷰 mf).
+  if (stdoutOverflow) return { ok: false, stderr: 'stdout-overflow-unmeasured' };
+  const jsonError = herdrJsonError(stdout);
+  if (code === 0 && jsonError === undefined) return { ok: true };
+  return { ok: false, stderr: jsonError ?? (stderr || (code === null ? 'killed' : `rc=${code}`)) };
+}
+
+function binOf(env: NodeJS.ProcessEnv): string {
+  const fromEnv = env.HERDR_BIN_PATH?.trim();
+  return fromEnv && fromEnv.length > 0 ? fromEnv : 'herdr';
+}
+
+/** 기본 러너 — 비동기 ≤2000ms, 동기(release) ≤300ms. ENOENT·timeout·rc≠0·stdout JSON error 는 ok:false(오류 문면은 stderr 칸). */
+export function defaultHerdrRunner(env: NodeJS.ProcessEnv): HerdrRunner {
+  const bin = binOf(env);
+  return (argv, opts) => {
+    const cap = opts.sync ? Math.min(opts.timeoutMs, SYNC_TIMEOUT_MS) : Math.min(opts.timeoutMs, ASYNC_TIMEOUT_MS);
+    if (opts.sync) {
+      try {
+        const r = spawnSync(bin, argv, { timeout: cap, encoding: 'utf8', windowsHide: true });
+        if (r.error) return { ok: false, stderr: r.error.message };
+        const out = typeof r.stdout === 'string' ? r.stdout : '';
+        const overflow = Buffer.byteLength(out, 'utf8') > STDOUT_CAP;
+        return judgeHerdr(r.status, overflow ? '' : out, typeof r.stderr === 'string' ? r.stderr : '', overflow);
+      } catch (error) {
+        return { ok: false, stderr: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    return new Promise<HerdrRunResult>((resolve) => {
+      let child: ReturnType<typeof spawn>;
+      try {
+        child = spawn(bin, argv, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+      } catch (error) {
+        resolve({ ok: false, stderr: error instanceof Error ? error.message : String(error) });
+        return;
+      }
+      let stderr = '';
+      const stdoutChunks: Buffer[] = [];
+      let stdoutBytes = 0;
+      let stdoutOverflow = false;
+      let settled = false;
+      const finish = (result: HerdrRunResult): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+      };
+      const timer = setTimeout(() => {
+        try { child.kill(); } catch { /* already gone */ }
+        finish({ ok: false, stderr: stderr || 'timeout' });
+      }, cap);
+      child.stderr?.on('data', (chunk: Buffer | string) => {
+        if (stderr.length < STDERR_HEAD) stderr += String(chunk);
+      });
+      // 오류 봉투는 stdout 으로 온다 — 응답은 짧다(한 줄 JSON). 폭주 방어로 4KB 까지만.
+      // 상한은 «바이트» 로 잰다(UTF-8 · #29077 리뷰 mf) — 넘치면 더 모으지 않고 넘침만 적는다.
+      child.stdout?.on('data', (chunk: Buffer | string) => {
+        const buf = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        if (stdoutOverflow) return;
+        if (stdoutBytes + buf.length > STDOUT_CAP) { stdoutOverflow = true; return; }
+        stdoutBytes += buf.length;
+        stdoutChunks.push(buf);
+      });
+      child.on('error', (error) => finish({ ok: false, stderr: error.message }));
+      child.on('close', (code) => {
+        const stdout = stdoutOverflow ? '' : Buffer.concat(stdoutChunks, stdoutBytes).toString('utf8');
+        finish(judgeHerdr(code, stdout, stderr, stdoutOverflow));
+      });
+    });
+  };
+}
+
+/**
+ * herdr pane 안에서만 신고기. 비활성이면 null (skipped 로그 한 번).
+ * 반환 메서드는 실패해도 던지지 않는다.
+ */
+export function createHerdrAgentReporter(deps: HerdrAgentReporterDeps = {}): HerdrAgentReporterLike | null {
+  const env = deps.env ?? process.env;
+  const log = deps.log ?? defaultLog;
+  if (env.ELANOUS_HERDR_REPORT === '0') {
+    log('skipped', { reason: 'kill-switch' });
+    return null;
+  }
+  const paneId = env.HERDR_PANE_ID?.trim() ?? '';
+  if (env.HERDR_ENV !== '1' || paneId.length === 0) {
+    log('skipped', { reason: 'no-herdr-env' });
+    return null;
+  }
+  const run = deps.run ?? defaultHerdrRunner(env);
+  const sessionId = deps.sessionId ?? '';
+  return new Reporter(paneId, sessionId, run, log, deps.now ?? Date.now, deps.seqStore ?? createFileSeqStore(paneId));
+}
+
+type IssueResult = boolean | Promise<boolean>;
+
+class Reporter implements HerdrAgentReporterLike {
+  private seq = 0;
+  private disabled = false;
+  /**
+   * idle 신고(에이전트 등록)의 상태: none → (pending →) ok | failed.
+   * release 는 failed(등록 실패 확인)·none 이 아니면 보낸다 — session 신고 실패는 등록을 되돌리지 않으므로 반납한다.
+   */
+  private startState: 'none' | 'pending' | 'ok' | 'failed' = 'none';
+  private released = false;
+  /** start 때 한 번 읽은 pane 기록(턴 경로는 파일을 안 만진다). */
+  private storedSeq: number | undefined;
+  /** idle 신고(비동기 포함)가 실패했다 — 등록된 적이 없으니 반납할 것이 없다. */
+  private idleFailed = false;
+  private seqStoreFailed = false;
+  /**
+   * 아직 안 끝난 비동기 신고 — 있으면 다음 비동기 신고는 그 뒤에 줄을 선다(r5 리뷰 mf).
+   * herdr 는 «직전보다 큰 seq» 만 받으므로, 큰 seq(session·turn)가 작은 seq(idle 등록)보다 먼저 도착하면
+   * 늦은 등록이 무시돼 상태가 어긋났다. seq 는 넣는 순간 정해지고 줄이 그 순서대로 보낸다.
+   * 앞 신고가 없으면 예전처럼 바로 보낸다(동기 러너 결과는 동기로 판정).
+   * 동기 release(종료 경로)만 줄을 기다리지 않는다 — 가장 큰 seq 라 늦게 도착한 앞 신고는 herdr 가 버린다.
+   */
+  private pending: Promise<unknown> | null = null;
+  /** 등록 결과를 모르는 채 반납했다 — 등록이 뒤늦게 성공하면 한 번 더 반납한다. */
+  private releasedWhilePending = false;
+
+  constructor(
+    private readonly paneId: string,
+    private readonly sessionId: string,
+    private readonly run: HerdrRunner,
+    private readonly log: (event: string, data: Record<string, unknown>) => void,
+    private readonly now: () => number,
+    private readonly seqStore: HerdrSeqStore,
+  ) {}
+
+  start(): void {
+    if (this.startState !== 'none') return;
+    try { this.storedSeq = this.seqStore.read(); } catch (error) { this.seqStoreFail(error); }
+    const idleOk = this.issue([
+      'pane', 'report-agent',
+      '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
+      '--state', 'idle',
+      '--agent-session-id', this.sessionId,
+      '--seq', this.nextSeq(),
+      this.paneId,
+    ], false, 'start');
+    if (idleOk === false) { this.startState = 'failed'; return; }
+    if (idleOk === true) this.startState = 'ok';
+    else {
+      // 비동기 — 결과가 나기 전의 release 는 «모름»으로 보고 바로 시도한다.
+      this.startState = 'pending';
+      void idleOk.then((ok) => this.settleStart(ok), () => this.settleStart(false));
+    }
+    if (this.disabled) return;
+    // session 신고 실패는 이후 turn 만 끈다(신고기 off) — 등록은 idle 로 이미 됐으니 release 는 그대로 보낸다.
+    this.issue([
+      'pane', 'report-agent-session',
+      '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
+      '--agent-session-id', this.sessionId,
+      '--session-start-source', 'startup',
+      '--seq', this.nextSeq(),
+      this.paneId,
+    ], false, 'session');
+  }
+
+  private settleStart(ok: boolean): void {
+    if (this.startState !== 'pending') return;
+    this.startState = ok && !this.idleFailed ? 'ok' : 'failed';
+    // 결과를 모르는 채 반납했는데 등록이 뒤늦게 성공했다 — 반납이 등록보다 먼저 처리됐을 수 있으니
+    //   프로세스가 아직 살아 있으면 한 번 더 반납한다(r6 리뷰 완화 · 즉시 종료 경합은 ASK-HERDR-RELEASE-START-RACE).
+    if (this.startState === 'ok' && this.releasedWhilePending) this.resendRelease();
+  }
+
+  /** 늦은 등록 뒤 재반납 — 비동기·최선 노력 · 한 번만. */
+  private resendRelease(): void {
+    this.releasedWhilePending = false;
+    this.log('release-resend-after-late-start', {});
+    const seq = this.nextSeq();
+    // 재반납 seq 도 pane 기록에 남긴다 — 같은 ms 재기동의 첫 seq 가 이 값보다 커야 한다(r7 리뷰 mf).
+    try { this.seqStore.write(this.seq); } catch (error) { this.seqStoreFail(error); }
+    void this.runAndJudge([
+      'pane', 'release-agent',
+      this.paneId,
+      '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
+      '--seq', String(seq),
+    ], { sync: false, timeoutMs: ASYNC_TIMEOUT_MS }, 'release');
+  }
+
+  turn(t: HerdrTurn): void {
+    // 반납 뒤 신고는 반납한 에이전트를 더 큰 seq 로 다시 등록한다 — 막는다.
+    if (this.disabled || this.released) return;
+    const state = t === 'busy' ? 'working' : 'idle';
+    this.issue([
+      'pane', 'report-agent',
+      '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
+      '--state', state,
+      '--seq', this.nextSeq(),
+      this.paneId,
+    ], false, 'turn');
+  }
+
+  release(): void {
+    if (this.released) return;
+    // idle 등록 실패가 확인됐거나 start 전이면 건너뛴다. pending = 결과 모름 → 반납을 시도한다.
+    if (this.startState === 'none' || this.startState === 'failed' || this.idleFailed) return;
+    if (this.startState === 'pending') {
+      this.log('release-start-pending', {});
+      this.releasedWhilePending = true;
+    }
+    this.released = true;
+    const seq = this.nextSeq();
+    // pane 기록 쓰기는 여기(동기 종료 경로)뿐이다.
+    try { this.seqStore.write(this.seq); } catch (error) { this.seqStoreFail(error); }
+    // ⛔ herdr 0.9.1 `release-agent` 는 PANE_ID 를 옵션 «앞»에 둬야 받는다 — 뒤에 두면
+    //   «unknown option: custom:elanous» rc2 로 반납이 영영 안 됐다(10-18 라이브 실측 · report-agent 는 뒤도 받음).
+    this.issue([
+      'pane', 'release-agent',
+      this.paneId,
+      '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
+      '--seq', seq,
+    ], true, 'release');
+  }
+
+  private seqStoreFail(error: unknown): void {
+    if (this.seqStoreFailed) return;
+    this.seqStoreFailed = true;
+    this.log('seq-store-failed', { error: error instanceof Error ? error.message : String(error) });
+  }
+
+  /** max(직전+1 · 시각 ms · pane 기록+1) — 같은 ms 재기동에도 뒤 프로세스의 첫 seq 가 앞 프로세스의 마지막보다 크다. */
+  private nextSeq(): string {
+    const clock = Math.floor(this.now());
+    let next = Number.isFinite(clock) ? Math.max(this.seq + 1, clock) : this.seq + 1;
+    if (this.storedSeq !== undefined) next = Math.max(next, this.storedSeq + 1);
+    this.seq = next;
+    return String(this.seq);
+  }
+
+  /**
+   * release 는 꺼진 뒤에도 보낸다(권한 반납 · start 성공 조건은 release() 가 본다).
+   * @returns false = 동기 실패(신고기 꺼짐) · true = 동기 성공 · Promise = 비동기 결과(성공이면 true).
+   */
+  private issue(argv: string[], sync: boolean, phase: 'start' | 'session' | 'turn' | 'release'): IssueResult {
+    if (this.disabled && phase !== 'release') return false;
+    const opts: HerdrRunOpts = { sync, timeoutMs: sync ? SYNC_TIMEOUT_MS : ASYNC_TIMEOUT_MS };
+    if (!sync && this.pending) {
+      // 앞 신고 뒤에 줄 선다 — 반납 뒤에 차례가 온 신고는 보내지 않는다(반납한 에이전트를 되살리지 않게).
+      const queued = this.pending.then(() => {
+        if (this.released || this.disabled) return false;
+        return this.runAndJudge(argv, opts, phase);
+      });
+      this.track(queued);
+      return queued;
+    }
+    let result: HerdrRunResult | Promise<HerdrRunResult>;
+    try {
+      result = this.run(argv, opts);
+    } catch (error) {
+      this.fail(argv, phase, error instanceof Error ? error.message : String(error));
+      return false;
+    }
+    if (result && typeof (result as Promise<HerdrRunResult>).then === 'function') {
+      const judged = (result as Promise<HerdrRunResult>).then(
+        (r) => {
+          if (r.ok) return true;
+          this.fail(argv, phase, r.stderr);
+          return false;
+        },
+        (error: unknown) => {
+          this.fail(argv, phase, error instanceof Error ? error.message : String(error));
+          return false;
+        },
+      );
+      if (!sync) this.track(judged);
+      return judged;
+    }
+    const syncResult = result as HerdrRunResult;
+    if (!syncResult.ok) {
+      this.fail(argv, phase, syncResult.stderr);
+      return false;
+    }
+    return true;
+  }
+
+  /** 줄 끝을 이 신고로 옮긴다 — 끝나면(마지막이었다면) 줄을 비운다. */
+  private track(p: Promise<unknown>): void {
+    const tail = p.catch(() => undefined);
+    this.pending = tail;
+    void tail.then(() => { if (this.pending === tail) this.pending = null; });
+  }
+
+  /** 줄 선 비동기 한 건 — 러너 결과(동기·비동기 모두)를 성패로 접는다. */
+  private async runAndJudge(argv: string[], opts: HerdrRunOpts, phase: 'start' | 'session' | 'turn' | 'release'): Promise<boolean> {
+    try {
+      const r = await this.run(argv, opts);
+      if (r.ok) return true;
+      this.fail(argv, phase, r.stderr);
+      return false;
+    } catch (error) {
+      this.fail(argv, phase, error instanceof Error ? error.message : String(error));
+      return false;
+    }
+  }
+
+  private fail(argv: string[], phase: 'start' | 'session' | 'turn' | 'release', stderr: string | undefined): void {
+    if (phase === 'start') this.idleFailed = true;
+    // 반납 실패는 신고기가 이미 꺼졌어도 늘 남긴다(종료 경로의 유일한 흔적).
+    if (phase === 'release') {
+      this.log('release-failed', { stderrHead: stderrHead(stderr) });
+      return;
+    }
+    if (this.disabled) return;
+    this.disabled = true;
+    const cmd = argv[1] ?? '';
+    this.log('report-failed', { cmd, stderrHead: stderrHead(stderr) });
+  }
+}

package/src/pty-shell/pty-control-ipc.ts

@@ -4,7 +4,7 @@ import { dirname } from 'node:path';
 import { ptyManifestDbPath, getPtyManifest, markPtyControlled } from './pty-manifest.js';
 import { getHarnessRunId } from '../harness/harness-space.js';
 import { renamePty, type PtyControlTarget } from './registry.js';
-import { resizePtyWithOutcome, writePtyWithOutcome } from './pty-write-outcome.js';
+import { resizePtyWithOutcome, writePtyWithOutcome, writePtyWithOutcomeDetail } from './pty-write-outcome.js';
 import { resetExternalWriteProvenanceForTesting } from './pty-write-provenance.js';
 import { parsePtyWriteActor, resolveRemoteControlActor, type PtyWriteActor } from './pty-write-arbiter.js';
 import { isPtyAccessMode } from './pty-ref.js';
@@ -414,13 +414,13 @@ async function processPtyControlRequestsOnce(getHandle: (id: string) => PtyContr
           // ⛔⭐ 여기서 세지 «않는다» — 계기는 `registry.write`(진짜 초크포인트)에 있다.
           //   여기서도 세면 크로스-프로세스 쓰기가 **두 번** 세어진다(`[S]` 리뷰 후 이동).
           //   `input-key` 는 TUI 외부 입력 대기열(`input/external-input-queue`)을 타지 않는다 — 글이 아니라 키다.
-          const write = (): ReturnType<typeof writePtyWithOutcome> => writePtyWithOutcome(handle, payload.chars, authorized.actor);
+          const write = (): ReturnType<typeof writePtyWithOutcomeDetail> => writePtyWithOutcomeDetail(handle, payload.chars, authorized.actor);
           const outcome = row.action === 'input-key' ? withExternalKeyCommand(write) : write();
-          result = outcome === 'success'
+          result = outcome.status === 'success'
             ? { status: 'success' }
-            : outcome === 'denied'
+            : outcome.status === 'denied'
               ? { status: 'denied', reason: 'write-arbiter' }
-              : { status: 'write-failed', reason: 'adapter-write' };
+              : { status: 'write-failed', reason: outcome.reason ?? 'adapter-write' };
         } else result = { status: 'denied', reason: 'invalid-payload' };
       }
     } catch (error) {

package/src/pty-shell/pty-manifest.ts

@@ -251,6 +251,13 @@ function recordPtyLifecycle(event: PtyLifecycleEvent, row: PtyManifestRow, now:
       exitCode: row.exitCode,
       startedAt: row.startedAt,
       closedAt: row.closedAt,
+      // 시작·종료·오류·산출을 같은 seatId 한 흐름으로 대조할 수 있게
+      // 매니페스트 행의 자리 정체성과 산출 총량을 원장 이벤트에도 싣는다.
+      ...(row.seat ? { seat: row.seat } : {}),
+      ...(row.purpose ? { purpose: row.purpose } : {}),
+      outputBytesTotal: row.outputBytesTotal,
+      ...(row.lastControlAt === undefined ? {} : { lastControlAt: row.lastControlAt }),
+      ...(row.turnState ? { turnState: row.turnState, turnAt: row.turnAt } : {}),
     },
   });
   if (seq === 0) debug.log('pty.manifest', 'ledger-write-failed', { ptyId: row.id, event });

package/src/pty-shell/pty-write-outcome.ts

@@ -2,19 +2,37 @@ import type { PtyControlTarget } from './registry.js';
 import type { PtyWriteActor } from './pty-write-arbiter.js';
 
 type PtyWriteOutcome = 'success' | 'denied' | 'write-failed';
+export type PtyWriteOutcomeDetail =
+  | { readonly status: 'success' }
+  | { readonly status: 'denied' }
+  | { readonly status: 'write-failed'; readonly reason?: 'tui-busy-text-without-enter' | 'tui-external-input-queue-full' };
 type PtyResizeOutcome = 'success' | 'denied' | 'resize-failed';
 
-/** Preflights the public write contract while retaining its arbiter enforcement for other callers. */
-export function writePtyWithOutcome(handle: PtyControlTarget, chars: string, actor: PtyWriteActor = 'human'): PtyWriteOutcome {
-  if (!handle.canWrite(actor)) return 'denied';
+const EXTERNAL_INPUT_REJECTION_REASONS = new Set([
+  'tui-busy-text-without-enter',
+  'tui-external-input-queue-full',
+]);
+
+/** Detailed write result for command paths that must surface known TUI refusal reasons. */
+export function writePtyWithOutcomeDetail(handle: PtyControlTarget, chars: string, actor: PtyWriteActor = 'human'): PtyWriteOutcomeDetail {
+  if (!handle.canWrite(actor)) return { status: 'denied' };
   try {
     handle.write(chars, actor);
-    return 'success';
-  } catch {
-    return 'write-failed';
+    return { status: 'success' };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : '';
+    return EXTERNAL_INPUT_REJECTION_REASONS.has(message)
+      ? { status: 'write-failed', reason: message as 'tui-busy-text-without-enter' | 'tui-external-input-queue-full' }
+      : { status: 'write-failed' };
   }
 }
 
+/** Preflights the public write contract while retaining its arbiter enforcement for other callers. */
+export function writePtyWithOutcome(handle: PtyControlTarget, chars: string, actor: PtyWriteActor = 'human'): PtyWriteOutcome {
+  const result = writePtyWithOutcomeDetail(handle, chars, actor);
+  return result.status;
+}
+
 /** Gates control-channel resize requests with the same access matrix as input. */
 export function resizePtyWithOutcome(handle: PtyControlTarget, cols: number, rows: number, actor: PtyWriteActor = 'human'): PtyResizeOutcome {
   if (!handle.canWrite(actor)) return 'denied';