elanous 0.2.34 → 0.2.36

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

@@ -3,7 +3,10 @@
 // `herdr agent list` 에 안 잡힌다 — pane CLI 로 생애·세션을 직접 알린다.
 //
 // 활성은 HERDR_ENV=1 ⊕ HERDR_PANE_ID ⊕ 킬스위치가 아닐 때뿐.
-// 실패(rc≠0·timeout·spawn·ENOENT)는 던지지 않고 한 번 로그한 뒤 그 신고기를 끈다.
+// 실패(rc≠0·spawn·ENOENT·오류 봉투)는 던지지 않고 한 번 로그한 뒤 그 신고기를 끈다.
+// 단 turn 신고의 timeout 은 끄지 않는다(TUI-HERDR-STATUS-STALE · 10-22 n8n): herdr 가 바쁜 한 번의 2s 초과로
+// 신고기가 꺼져 턴 끝 idle 이 영영 안 나가 herdr 가 1.9h 동안 working 을 보였다. timeout 은 «결과 모름»이라
+// 마지막 턴 상태를 잠시 뒤 다시 신고하고(새 seq · 더 새 턴이 오면 그만) 이후 턴 신고도 그대로 보낸다.
 //
 // herdr 는 같은 pane·source 에서 «직전보다 큰 seq» 만 받는다(작으면 rc0 인데 무시).
 // 같은 pane 에서 TUI 를 다시 띄워도 신고가 살도록 seq 는 max(직전+1 · 시각 · pane 기록+1) 이다.
@@ -15,6 +18,8 @@
 // 실패로 꺼지는 것은 «이후 turn» 뿐이다. release(권한 반납)는 start 실패가 «확인»됐을 때만 건너뛴다.
 // start 의 비동기 신고가 아직 안 끝났으면(결과 모름) 반납을 미루지 않고 바로 동기로 시도한다(관측 `release-start-pending`) —
 // 종료 경로에서 미루면 exit 뒤 반납이 영영 안 나간다. 반납 실패(rc≠0 등)는 `release-failed` 로 늘 남긴다.
+// 그때 반납 직전에 더 큰 seq 로 동기 재등록한다(TUI-HERDR-EXIT-RACE) — 미등록 반납은 seq 를 안 남겨
+// 늦게 닿은 비동기 등록이 유령이 되던 경합을 «동기 재등록 → 동기 반납» 순서로 닫는다.
 
 import { spawn, spawnSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -29,6 +34,8 @@ export type HerdrTurn = 'busy' | 'idle';
 export interface HerdrRunResult {
   readonly ok: boolean;
   readonly stderr?: string;
+  /** 시간 안에 답을 못 받았다 — herdr 가 이미 적용했을 수도 있는 «결과 모름»(TUI-HERDR-STATUS-STALE). */
+  readonly timedOut?: boolean;
 }
 
 export interface HerdrRunOpts {
@@ -50,8 +57,15 @@ export interface HerdrAgentReporterDeps {
   readonly now?: () => number;
   /** pane 별 마지막 seq 기록. 기본 = tmpdir 파일(`createFileSeqStore`). */
   readonly seqStore?: HerdrSeqStore;
+  /** 재신고 타이머 — 기본 setTimeout(unref). 시험이 가짜 시계를 준다. */
+  readonly schedule?: (fn: () => void, ms: number) => void;
 }
 
+const defaultSchedule = (fn: () => void, ms: number): void => {
+  const t = setTimeout(fn, ms);
+  (t as unknown as { unref?: () => void }).unref?.();
+};
+
 /** 같은 pane 에서 마지막으로 낸 seq — 프로세스 사이 단조를 잇는다. 실패는 던져도 된다(신고기가 삼킨다). */
 export interface HerdrSeqStore {
   read(): number | undefined;
@@ -89,6 +103,10 @@ export interface HerdrAgentReporterLike {
 }
 
 const ASYNC_TIMEOUT_MS = 2000;
+/** turn 신고가 timeout 이면 이만큼 뒤에 마지막 상태를 다시 신고한다. */
+export const HERDR_TURN_RETRY_DELAY_MS = 3000;
+/** 같은 턴 상태의 재신고 상한 — 넘으면 `report-gave-up` 을 남기고 다음 턴 신고를 기다린다(신고기는 켜 둔다). */
+export const HERDR_TURN_RETRY_MAX = 3;
 const SYNC_TIMEOUT_MS = 300;
 const STDERR_HEAD = 240;
 const STDOUT_CAP = 4096;
@@ -149,7 +167,10 @@ export function defaultHerdrRunner(env: NodeJS.ProcessEnv): HerdrRunner {
     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 };
+        if (r.error) {
+          const timedOut = (r.error as NodeJS.ErrnoException).code === 'ETIMEDOUT';
+          return { ok: false, stderr: r.error.message, ...(timedOut ? { timedOut: true } : {}) };
+        }
         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);
@@ -178,7 +199,7 @@ export function defaultHerdrRunner(env: NodeJS.ProcessEnv): HerdrRunner {
       };
       const timer = setTimeout(() => {
         try { child.kill(); } catch { /* already gone */ }
-        finish({ ok: false, stderr: stderr || 'timeout' });
+        finish({ ok: false, stderr: stderr || 'timeout', timedOut: true });
       }, cap);
       child.stderr?.on('data', (chunk: Buffer | string) => {
         if (stderr.length < STDERR_HEAD) stderr += String(chunk);
@@ -201,6 +222,43 @@ export function defaultHerdrRunner(env: NodeJS.ProcessEnv): HerdrRunner {
   };
 }
 
+/** 신호 지킴이가 쓰는 process 의 좁은 면 — 시험이 가짜를 준다. */
+export interface HerdrSignalTarget {
+  readonly pid: number;
+  on(sig: NodeJS.Signals, fn: (sig: NodeJS.Signals) => void): unknown;
+  removeListener(sig: NodeJS.Signals, fn: (sig: NodeJS.Signals) => void): unknown;
+  listenerCount(sig: NodeJS.Signals): number;
+  kill(pid: number, sig?: string | number): unknown;
+}
+
+const RELEASE_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM'];
+
+/**
+ * SIGINT·SIGTERM 기본 죽음에도 반납한다(TUI-HERDR-EXIT-RACE).
+ * 대시보드가 raw 모드에 들기 «전»의 ctrl+c 는 SIGINT 기본 동작으로 프로세스를 죽여(rc130) 'exit' 훅이 안 돈다 —
+ * 10-22 격리 세션 실측: 반납 0 · `agent list` 에 elanous idle 이 남았다.
+ * 신호가 오면 반납(동기) → 자기 리스너를 걷고, 이제 아무도 안 들으면 같은 신호를 다시 올려 기본 죽음을 지킨다.
+ * 다른 리스너가 있으면 그쪽이 같은 신호를 이미 받았다 — 다시 올리지 않는다.
+ * @returns 해제(정상 종료 경로에서 부른다).
+ */
+export function guardHerdrReleaseOnSignal(release: () => void, proc: HerdrSignalTarget = process): () => void {
+  let off = false;
+  const remove = (): void => {
+    if (off) return;
+    off = true;
+    for (const sig of RELEASE_SIGNALS) { try { proc.removeListener(sig, onSignal); } catch { /* 종료 경로를 깨지 않는다 */ } }
+  };
+  function onSignal(sig: NodeJS.Signals): void {
+    try { release(); } catch { /* 신호 경로를 깨지 않는다 */ }
+    remove();
+    let alone = true;
+    try { alone = proc.listenerCount(sig) === 0; } catch { alone = true; }
+    if (alone) { try { proc.kill(proc.pid, sig); } catch { /* 이미 끝나는 중 */ } }
+  }
+  for (const sig of RELEASE_SIGNALS) proc.on(sig, onSignal);
+  return remove;
+}
+
 /**
  * herdr pane 안에서만 신고기. 비활성이면 null (skipped 로그 한 번).
  * 반환 메서드는 실패해도 던지지 않는다.
@@ -219,7 +277,7 @@ export function createHerdrAgentReporter(deps: HerdrAgentReporterDeps = {}): Her
   }
   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));
+  return new Reporter(paneId, sessionId, run, log, deps.now ?? Date.now, deps.seqStore ?? createFileSeqStore(paneId), deps.schedule ?? defaultSchedule);
 }
 
 type IssueResult = boolean | Promise<boolean>;
@@ -256,8 +314,14 @@ class Reporter implements HerdrAgentReporterLike {
     private readonly log: (event: string, data: Record<string, unknown>) => void,
     private readonly now: () => number,
     private readonly seqStore: HerdrSeqStore,
+    private readonly schedule: (fn: () => void, ms: number) => void,
   ) {}
 
+  /** 마지막으로 요청된 턴 상태와 그 세대 — 재신고는 세대가 그대로일 때만(더 새 턴이 오면 그만). */
+  private lastTurn: HerdrTurn | null = null;
+  private turnGen = 0;
+  private turnRetries = 0;
+
   start(): void {
     if (this.startState !== 'none') return;
     try { this.storedSeq = this.seqStore.read(); } catch (error) { this.seqStoreFail(error); }
@@ -314,6 +378,13 @@ class Reporter implements HerdrAgentReporterLike {
   turn(t: HerdrTurn): void {
     // 반납 뒤 신고는 반납한 에이전트를 더 큰 seq 로 다시 등록한다 — 막는다.
     if (this.disabled || this.released) return;
+    this.lastTurn = t;
+    this.turnGen += 1;
+    this.turnRetries = 0;
+    this.issueTurn(t);
+  }
+
+  private issueTurn(t: HerdrTurn): void {
     const state = t === 'busy' ? 'working' : 'idle';
     this.issue([
       'pane', 'report-agent',
@@ -328,11 +399,24 @@ class Reporter implements HerdrAgentReporterLike {
     if (this.released) return;
     // idle 등록 실패가 확인됐거나 start 전이면 건너뛴다. pending = 결과 모름 → 반납을 시도한다.
     if (this.startState === 'none' || this.startState === 'failed' || this.idleFailed) return;
+    this.released = true;
     if (this.startState === 'pending') {
       this.log('release-start-pending', {});
       this.releasedWhilePending = true;
+      // 즉시 종료 경합(TUI-HERDR-EXIT-RACE): 비동기 idle 등록은 herdr 자식 프로세스라 부모가 죽어도 간다.
+      //   herdr 0.9.1 실측 — 미등록 에이전트 반납은 rc0 인데 seq 를 안 남긴다 ⇒ 반납 «뒤에» 닿은 작은 seq 등록이
+      //   유령으로 남는다(10-22 격리 세션 tf-exit-race). 기다릴 수 없으니(동기 ≤300ms) 순서를 동기로 고정한다:
+      //   더 큰 seq 로 동기 재등록 → 동기 반납. 반납이 «등록된» 에이전트를 지우며 seq 를 남기므로
+      //   늦게 닿는 앞 등록(작은 seq)은 herdr 가 버린다. 재등록 실패여도 반납은 그대로 시도한다(결과 모름).
+      this.issue([
+        'pane', 'report-agent',
+        '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
+        '--state', 'idle',
+        '--agent-session-id', this.sessionId,
+        '--seq', this.nextSeq(),
+        this.paneId,
+      ], true, 'release');
     }
-    this.released = true;
     const seq = this.nextSeq();
     // pane 기록 쓰기는 여기(동기 종료 경로)뿐이다.
     try { this.seqStore.write(this.seq); } catch (error) { this.seqStoreFail(error); }
@@ -346,6 +430,27 @@ class Reporter implements HerdrAgentReporterLike {
     ], true, 'release');
   }
 
+  /**
+   * turn 신고 timeout — 신고기를 끄지 않고 마지막 턴 상태를 잠시 뒤 다시 신고한다(TUI-HERDR-STATUS-STALE).
+   * herdr 가 그 신고를 이미 적용했어도(답만 늦었다) 다시 보내는 것은 무해하다 — 더 큰 seq 의 같은 상태다.
+   */
+  private retryTurnAfterTimeout(argv: string[], stderr: string | undefined): void {
+    const gen = this.turnGen;
+    const state = this.lastTurn;
+    const attempt = this.turnRetries + 1;
+    if (state === null) return;
+    if (attempt > HERDR_TURN_RETRY_MAX) {
+      this.log('report-gave-up', { cmd: argv[1] ?? '', state: state === 'busy' ? 'working' : 'idle', attempts: HERDR_TURN_RETRY_MAX, stderrHead: stderrHead(stderr) });
+      return;
+    }
+    this.turnRetries = attempt;
+    this.log('report-timeout-retry', { cmd: argv[1] ?? '', state: state === 'busy' ? 'working' : 'idle', attempt, delayMs: HERDR_TURN_RETRY_DELAY_MS, stderrHead: stderrHead(stderr) });
+    this.schedule(() => {
+      if (this.disabled || this.released || this.turnGen !== gen) return;
+      this.issueTurn(state);
+    }, HERDR_TURN_RETRY_DELAY_MS);
+  }
+
   private seqStoreFail(error: unknown): void {
     if (this.seqStoreFailed) return;
     this.seqStoreFailed = true;
@@ -388,7 +493,7 @@ class Reporter implements HerdrAgentReporterLike {
       const judged = (result as Promise<HerdrRunResult>).then(
         (r) => {
           if (r.ok) return true;
-          this.fail(argv, phase, r.stderr);
+          this.fail(argv, phase, r.stderr, r.timedOut === true);
           return false;
         },
         (error: unknown) => {
@@ -401,7 +506,7 @@ class Reporter implements HerdrAgentReporterLike {
     }
     const syncResult = result as HerdrRunResult;
     if (!syncResult.ok) {
-      this.fail(argv, phase, syncResult.stderr);
+      this.fail(argv, phase, syncResult.stderr, syncResult.timedOut === true);
       return false;
     }
     return true;
@@ -419,7 +524,7 @@ class Reporter implements HerdrAgentReporterLike {
     try {
       const r = await this.run(argv, opts);
       if (r.ok) return true;
-      this.fail(argv, phase, r.stderr);
+      this.fail(argv, phase, r.stderr, r.timedOut === true);
       return false;
     } catch (error) {
       this.fail(argv, phase, error instanceof Error ? error.message : String(error));
@@ -427,7 +532,11 @@ class Reporter implements HerdrAgentReporterLike {
     }
   }
 
-  private fail(argv: string[], phase: 'start' | 'session' | 'turn' | 'release', stderr: string | undefined): void {
+  private fail(argv: string[], phase: 'start' | 'session' | 'turn' | 'release', stderr: string | undefined, timedOut = false): void {
+    if (phase === 'turn' && timedOut && !this.disabled) {
+      this.retryTurnAfterTimeout(argv, stderr);
+      return;
+    }
     if (phase === 'start') this.idleFailed = true;
     // 반납 실패는 신고기가 이미 꺼졌어도 늘 남긴다(종료 경로의 유일한 흔적).
     if (phase === 'release') {

package/src/pty-shell/herdr-prompt.ts

@@ -0,0 +1,266 @@
+// `eln herdr prompt <대상> "<문장>" [--wait] [--timeout MS]` — herdr pane 의 elanous TUI 를 밖에서 깨운다.
+//
+// 왜 herdr `agent prompt` 가 아닌가(10-22 실측 · herdr 소스 v0.9.1·v0.9.5·main 5bd900d 동일):
+//   `src/app/api/agents.rs` 의 prompt·send-keys 는 `terminal.effective_known_agent()`(내장 kind 라벨)와
+//   `runtime_hosts_agent`(전경 프로세스가 그 kind)를 요구한다. «Add Herdr support to your agent» 계약대로
+//   자기 이름(`elanous`)으로 신고한 agent 는 list·get·wait·read·알림은 되지만 prompt 는
+//   `agent_not_ready: … is not an active named agent` 로 늘 거부된다.
+// 그래서 같은 의미를 여기서 낸다:
+//   ① `herdr agent get` — 신고 라벨이 elanous 이고 idle/done 인지(blocked/working/unknown 은 입력 0 으로 거부)
+//   ② `herdr pane run <pane> <문장>` — agent prompt 와 «같은 바이트»: herdr 의 `pane run` 은 pane 의 bracketed-paste
+//      모드를 따라 `ESC[200~문장ESC[201~` ⊕ Enter 를 한 번에 쓴다(격리 세션 실측 · `pane send-text` 는 날 바이트라 쓰지 않는다)
+//   ③ --wait — 제출 뒤 활동 창(5000ms) 안에 working/blocked 를 관측해야 하고(아니면 agent_prompt_stalled),
+//      그 뒤 idle/done/blocked 정착까지 기다린다. 호출자 timeout 이 먼저 끝나면 timeout. herdr agent prompt --wait 의미 그대로.
+// 관측: debug.log('pty.herdr', 'prompt', { target, paneId, accepted, reason, status, ms }) 한 줄.
+// 호출자 둘: CLI `eln herdr prompt`(라벨 elanous 만) ⊕ 우편 깨움 `src/loops/msg-wake.ts`(anyAgent · beforeSubmit 으로 재해석·opt-in·마감 관문).
+// 신고 계약(herdr-agent-report.ts)은 건드리지 않는다 — 이 명령은 그 신고(working/idle)를 «읽기만» 한다.
+
+import { spawn } from 'node:child_process';
+
+import { debug } from '../debug/log.js';
+
+export const HERDR_PROMPT_ACTIVITY_WINDOW_MS = 5000;
+const HERDR_PROMPT_AGENT = 'elanous';
+const CALL_TIMEOUT_MS = 5000;
+const KILL_GRACE_MS = 1500;
+const OUTPUT_CAP = 64 * 1024;
+
+export interface HerdrCliResult {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** herdr CLI 한 번. timeoutMs 가 Infinity 면 끝없이 기다린다. */
+export type HerdrCliRunner = (argv: readonly string[], timeoutMs: number) => Promise<HerdrCliResult>;
+
+export interface HerdrPromptOpts {
+  readonly target: string;
+  readonly text: string;
+  readonly wait?: boolean;
+  /** 호출자 timeout(제출 포함) — 없으면 정착 대기는 끝이 없다(herdr 와 같다). */
+  readonly timeoutMs?: number;
+  /**
+   * 라벨 확인을 끈다 — 호출자가 대상을 이미 정했을 때(우편 깨움: 자리 폴더 `herdr.pane`). 상태 확인(idle/done 만)과
+   * 제출(`pane run`)은 그대로다. CLI(`eln herdr prompt`)는 켜지 않는다 — herdr 내장 kind 는 herdr agent prompt 몫.
+   */
+  readonly anyAgent?: boolean;
+  /** `agent get` 이 agent_not_found 면 `pane get` 의 agent_status 로 떨어진다(우편 깨움 · #30261 전 경로와 같은 관문).
+   *  10-22 cct 아래 Claude 자리가 agent get 에서 간헐적으로 안 잡혀 깨움 18건이 failed 됐다. */
+  readonly paneFallback?: boolean;
+}
+
+/** 상태 확인을 통과한 대상 — `beforeSubmit` 이 본다. */
+export interface HerdrPromptView {
+  readonly agent: string;
+  readonly status: string;
+  readonly paneId: string;
+}
+
+export interface HerdrPromptDeps {
+  readonly run?: HerdrCliRunner;
+  readonly now?: () => number;
+  readonly log?: (event: string, data: Record<string, unknown>) => void;
+  /** 시험용 — 제출 뒤 활동 관측 창. 기본 5000ms(herdr 의미). */
+  readonly activityWindowMs?: number;
+  readonly env?: NodeJS.ProcessEnv;
+  /**
+   * 상태 확인 «뒤»·제출 «바로 앞» 호출자 관문 — 이유 문자열을 돌려주면 입력 0 으로 그 이유로 끝난다(accepted:false).
+   * 우편 깨움이 대상 재해석·opt-in 재확인·마감을 여기서 본다(조회 사이 바뀐 것에 넣지 않는다).
+   */
+  readonly beforeSubmit?: (view: HerdrPromptView) => string | undefined;
+}
+
+export type HerdrPromptReason =
+  | 'submitted' | 'settled'
+  | 'empty_agent_prompt' | 'not_elanous' | 'agent_blocked' | 'agent_working' | 'agent_unknown'
+  | 'agent_prompt_stalled' | 'timeout'
+  | string; // herdr 오류 코드 그대로(agent_not_found · pane_not_found …)
+
+export interface HerdrPromptResult {
+  readonly ok: boolean;
+  /** 문장이 pane 에 들어갔나(실패여도 true 일 수 있다 — 재제출 전에 화면을 읽어라). */
+  readonly accepted: boolean;
+  readonly reason: HerdrPromptReason;
+  readonly target: string;
+  readonly paneId?: string;
+  readonly agent?: string;
+  readonly status?: string;
+  readonly message?: string;
+  readonly ms: number;
+}
+
+interface AgentView {
+  readonly agent: string;
+  readonly status: string;
+  readonly paneId: string;
+  readonly seq: number;
+}
+
+/** herdr 오류 봉투(stderr 또는 stdout JSON `{"error":{code,message}}`). 없으면 undefined. */
+function herdrError(r: HerdrCliResult): { code: string; message: string } | undefined {
+  for (const text of [r.stderr, r.stdout]) {
+    const t = text.trim();
+    if (!t.startsWith('{')) continue;
+    try {
+      const e = (JSON.parse(t) as { error?: { code?: unknown; message?: unknown } }).error;
+      if (e && typeof e === 'object') {
+        return { code: typeof e.code === 'string' ? e.code : 'herdr_error', message: typeof e.message === 'string' ? e.message : '' };
+      }
+    } catch { /* not an envelope */ }
+  }
+  if (r.code === 0) return undefined;
+  return { code: r.code === null ? 'herdr_killed' : `herdr_rc_${r.code}`, message: r.stderr.trim().slice(0, 240) };
+}
+
+function agentOf(r: HerdrCliResult): AgentView | undefined {
+  try {
+    const a = (JSON.parse(r.stdout.trim()) as { result?: { agent?: Record<string, unknown> } }).result?.agent;
+    if (!a || typeof a.pane_id !== 'string') return undefined;
+    return {
+      agent: typeof a.agent === 'string' ? a.agent : '',
+      status: typeof a.agent_status === 'string' ? a.agent_status : 'unknown',
+      paneId: a.pane_id,
+      seq: typeof a.state_change_seq === 'number' ? a.state_change_seq : 0,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** `pane get` 봉투에서 agent·agent_status — paneFallback 전용(agent get 이 못 찾을 때). seq 는 없다(0). */
+function paneViewOf(r: HerdrCliResult): AgentView | undefined {
+  if (herdrError(r)) return undefined;
+  try {
+    const p = (JSON.parse(r.stdout.trim()) as { result?: { pane?: Record<string, unknown> } }).result?.pane;
+    if (!p || typeof p.pane_id !== 'string' || typeof p.agent_status !== 'string') return undefined;
+    return { agent: typeof p.agent === 'string' ? p.agent : '', status: p.agent_status, paneId: p.pane_id, seq: 0 };
+  } catch {
+    return undefined;
+  }
+}
+
+/** 기본 러너 — HERDR_BIN_PATH(없으면 PATH 의 herdr). HERDR_SOCKET_PATH 등 env 는 그대로 넘긴다. */
+export function defaultHerdrCliRunner(env: NodeJS.ProcessEnv = process.env): HerdrCliRunner {
+  const bin = env.HERDR_BIN_PATH?.trim() || 'herdr';
+  return (argv, timeoutMs) => new Promise<HerdrCliResult>((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(bin, [...argv], { env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (error) {
+      resolve({ code: null, stdout: '', stderr: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (r: HerdrCliResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(r);
+    };
+    const timer = Number.isFinite(timeoutMs)
+      ? setTimeout(() => {
+        try { child.kill(); } catch { /* gone */ }
+        finish({ code: null, stdout, stderr: stderr || 'herdr call timed out' });
+      }, Math.max(1, timeoutMs))
+      : undefined;
+    child.stdout?.on('data', (c: Buffer | string) => { if (stdout.length < OUTPUT_CAP) stdout += String(c); });
+    child.stderr?.on('data', (c: Buffer | string) => { if (stderr.length < OUTPUT_CAP) stderr += String(c); });
+    child.on('error', (error) => finish({ code: null, stdout, stderr: error.message }));
+    child.on('close', (code) => finish({ code, stdout, stderr }));
+  });
+}
+
+export async function herdrPrompt(opts: HerdrPromptOpts, deps: HerdrPromptDeps = {}): Promise<HerdrPromptResult> {
+  const now = deps.now ?? Date.now;
+  const run = deps.run ?? defaultHerdrCliRunner(deps.env);
+  const log = deps.log ?? ((event: string, data: Record<string, unknown>) => debug.log('pty.herdr', event, data));
+  const windowMs = deps.activityWindowMs ?? HERDR_PROMPT_ACTIVITY_WINDOW_MS;
+  const start = now();
+  const deadline = opts.timeoutMs !== undefined ? start + opts.timeoutMs : undefined;
+  const remaining = (): number => (deadline === undefined ? Number.POSITIVE_INFINITY : Math.max(0, deadline - now()));
+  const callCap = (): number => Math.min(CALL_TIMEOUT_MS, Math.max(1, remaining()));
+
+  let view: AgentView | undefined;
+  const done = (ok: boolean, accepted: boolean, reason: HerdrPromptReason, message?: string): HerdrPromptResult => {
+    const result: HerdrPromptResult = {
+      ok, accepted, reason, target: opts.target,
+      ...(view ? { paneId: view.paneId, agent: view.agent, status: view.status } : {}),
+      ...(message ? { message } : {}),
+      ms: Math.max(0, Math.round(now() - start)),
+    };
+    log('prompt', { target: opts.target, paneId: view?.paneId, accepted, reason, status: view?.status, ms: result.ms });
+    return result;
+  };
+
+  if (opts.text.length === 0) return done(false, false, 'empty_agent_prompt', 'prompt text must not be empty');
+
+  // ① 대상 확인
+  const got = await run(['agent', 'get', opts.target], callCap());
+  const getErr = herdrError(got);
+  if (getErr) {
+    if (!(opts.paneFallback && getErr.code === 'agent_not_found')) return done(false, false, getErr.code, getErr.message);
+    const pane = paneViewOf(await run(['pane', 'get', opts.target], callCap()));
+    if (!pane) return done(false, false, getErr.code, getErr.message);
+    log('prompt-pane-fallback', { target: opts.target, paneId: pane.paneId, agent: pane.agent, status: pane.status });
+    view = pane;
+  } else view = agentOf(got);
+  if (!view) return done(false, false, 'unparseable_agent_get');
+  if (!opts.anyAgent && view.agent !== HERDR_PROMPT_AGENT) {
+    return done(false, false, 'not_elanous', `agent label ${view.agent || '(none)'} — use herdr agent prompt for herdr-supported agents`);
+  }
+  if (view.status === 'blocked') return done(false, false, 'agent_blocked', 'agent is blocked and requires interactive input');
+  if (view.status === 'working') return done(false, false, 'agent_working', 'agent is working — wait for idle first');
+  if (view.status !== 'idle' && view.status !== 'done') return done(false, false, 'agent_unknown', `agent status ${view.status}`);
+  const seq0 = view.seq;
+  const paneId = view.paneId;
+  const veto = deps.beforeSubmit?.({ agent: view.agent, status: view.status, paneId });
+  if (veto !== undefined) return done(false, false, veto);
+
+  // ② 제출 — agent prompt 와 같은 bracketed text ⊕ Enter 한 번
+  const sent = await run(['pane', 'run', paneId, opts.text], callCap());
+  const sendErr = herdrError(sent);
+  if (sendErr) return done(false, false, sendErr.code, sendErr.message);
+  if (!opts.wait) return done(true, true, 'submitted');
+
+  const refresh = async (): Promise<AgentView | undefined> => {
+    const r = await run(['agent', 'get', paneId], CALL_TIMEOUT_MS);
+    const v = herdrError(r) ? undefined : agentOf(r);
+    if (v) view = v;
+    return v;
+  };
+  const settledStatus = (s: string): boolean => s === 'idle' || s === 'done' || s === 'blocked';
+
+  // ③ 활동 관측(working/blocked) — 창 안에 없으면 stalled, 호출자 timeout 이 먼저면 timeout
+  const win = Math.min(windowMs, remaining());
+  const activity = await run(['agent', 'wait', paneId, '--until', 'working', '--until', 'blocked', '--timeout', String(Math.max(1, Math.floor(win)))], win + KILL_GRACE_MS);
+  const actErr = herdrError(activity);
+  if (actErr) {
+    const v = await refresh();
+    // wait 를 걸기 전에 턴이 이미 돌고 끝났다 — seq 가 움직였고 정착 상태면 성공이다.
+    if (v && v.seq > seq0 && settledStatus(v.status)) return done(true, true, 'settled');
+    if (!(v && v.seq > seq0 && v.status === 'working')) {
+      if (actErr.code !== 'timeout') return done(false, true, actErr.code, actErr.message);
+      return done(false, true, remaining() <= 0 ? 'timeout' : 'agent_prompt_stalled', 'no working/blocked activity observed after submission');
+    }
+  } else {
+    const v = agentOf(activity);
+    if (v) view = v;
+    if (v?.status === 'blocked') return done(true, true, 'settled');
+  }
+
+  // ④ 정착(idle/done/blocked)까지
+  const rem = remaining();
+  const settleArgs = ['agent', 'wait', paneId, ...(Number.isFinite(rem) ? ['--timeout', String(Math.max(1, Math.floor(rem)))] : [])];
+  const settled = await run(settleArgs, Number.isFinite(rem) ? rem + KILL_GRACE_MS : Number.POSITIVE_INFINITY);
+  const setErr = herdrError(settled);
+  if (setErr) {
+    await refresh();
+    return done(false, true, setErr.code, setErr.message);
+  }
+  const v = agentOf(settled);
+  if (v) view = v;
+  return done(true, true, 'settled');
+}