@dmsdc-ai/aigentry-telepty 0.1.96 → 0.1.98

package/skills/telepty-listen/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: telepty-listen
+description: Monitor telepty events and read session screen output. Covers listen (event bus) and read-screen commands.
+---
+
+# telepty-listen — Event Monitoring and Screen Reading
+
+## listen — Subscribe to event bus
+
+```bash
+telepty listen
+telepty listen --json
+```
+
+Natural-language: "이벤트 보여줘", "listen to the bus", "monitor session events"
+
+Connects to the daemon's WebSocket event bus and streams all events in real-time.
+
+### Event types
+
+| Event | Description |
+|-------|-------------|
+| `session_health` | Periodic health status for all sessions |
+| `inject_written` | Message delivered to a session |
+| `inject_failed` | Delivery failure with error code |
+| `session_register` | New session registered |
+| `session_rename` | Session ID changed |
+| `session_stale` | Session disconnected beyond stale threshold |
+| `session_cleanup` | Stale session auto-removed |
+| `submit` | Enter keystroke sent |
+| `mailbox_delivered` | Mailbox message successfully delivered |
+| `mailbox_delivery_failed` | Mailbox delivery failed, will retry |
+
+### Examples
+
+```bash
+# Human-readable event stream
+telepty listen
+
+# JSON format for scripting
+telepty listen --json
+
+# Filter specific events with jq
+telepty listen --json | jq 'select(.type == "inject_written")'
+```
+
+## read-screen — Read session screen buffer
+
+```bash
+telepty read-screen <session_id> [--lines N] [--raw]
+```
+
+Natural-language: "세션 화면 읽어줘", "what's on the analyst's screen", "read screen output"
+
+Reads the last N lines of a session's PTY output buffer (default: 50 lines).
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--lines N` | Number of lines to read (default: 50) |
+| `--raw` | Return raw output with ANSI escape sequences |
+
+### Examples
+
+```bash
+# Read last 50 lines (cleaned)
+telepty read-screen my-claude
+
+# Read last 100 lines
+telepty read-screen my-claude --lines 100
+
+# Raw output with escape sequences
+telepty read-screen my-claude --raw
+
+# Use in scripts
+SCREEN=$(telepty read-screen my-claude --lines 10)
+echo "$SCREEN" | grep "error"
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Session not found` | Session doesn't exist | Check `telepty list` |
+| `(empty screen)` | No output captured yet | Wait for session to produce output |

package/skills/telepty-rename/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: telepty-rename
+description: Rename, delete, and clean up telepty sessions. Session lifecycle management.
+---
+
+# telepty-rename — Session Lifecycle Management
+
+## rename — Change a session's ID
+
+```bash
+telepty rename <old_id> <new_id>
+```
+
+Natural-language: "세션 이름 바꿔줘", "rename the session"
+
+Renames a session while preserving all state, connections, and attached clients. Publishes a `session_rename` event on the bus.
+
+### Examples
+
+```bash
+telepty rename temp-session analyst-claude
+```
+
+## delete — Remove a session
+
+```bash
+telepty delete <session_id>
+```
+
+Natural-language: "세션 삭제해줘", "kill that session", "remove the dead session"
+
+Forcefully closes the session's PTY process, disconnects all clients, and removes it from the daemon registry.
+
+### Examples
+
+```bash
+telepty delete stale-session
+```
+
+## clean — Remove ghost sessions
+
+```bash
+telepty clean
+```
+
+Natural-language: "고스트 세션 정리해줘", "clean up stale sessions"
+
+Scans all sessions and removes those with `STALE` or `DISCONNECTED` health status. Safe to run periodically.
+
+### Example output
+
+```
+  🗑  Removed ghost: old-brain-claude (STALE)
+  🗑  Removed ghost: temp-test (DISCONNECTED)
+✅ Cleaned 2 ghost session(s).
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Session not found` | Session doesn't exist or already removed | Check `telepty list` |
+| `Session ID already active` | New name conflicts with existing session | Choose a different name |

package/skills/telepty-session/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: telepty-session
+description: Multi-session orchestration — start multiple sessions at once and arrange terminal layouts. Covers session start and layout commands.
+---
+
+# telepty-session — Multi-Session Orchestration
+
+## session start — Launch multiple sessions
+
+```bash
+telepty session start [--launch]
+```
+
+Natural-language: "세션 여러 개 시작해줘", "start all sessions", "launch the ecosystem"
+
+Starts pre-configured sessions (from aigentry ecosystem or custom config). With `--launch`, opens each session in a new terminal tab/window.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--launch` | Open each session in a new kitty/ghostty tab |
+
+### Examples
+
+```bash
+# Start sessions interactively
+telepty session start
+
+# Start and launch in terminal tabs
+telepty session start --launch
+```
+
+## layout — Arrange terminal windows in a grid
+
+```bash
+telepty layout [columns]
+```
+
+Natural-language: "터미널 배치해줘", "arrange the windows", "layout the sessions"
+
+Arranges all terminal windows in a grid layout on the screen. Defaults to auto-calculated columns based on session count.
+
+### Examples
+
+```bash
+# Auto-layout
+telepty layout
+
+# Force 3-column grid
+telepty layout 3
+```
+
+## session info — Detailed session metadata
+
+```bash
+telepty session info <session_id>
+```
+
+Shows comprehensive session details including:
+- Session type, command, CWD
+- Terminal detection (ghostty, kitty, aterm)
+- Health status and reason
+- Transport block (delivery endpoint, backend)
+- Semantic state (phase, current task, blocker)
+- Mailbox stats (pending, dead-letter count)
+
+## deliberate — Start multi-session deliberation
+
+```bash
+telepty deliberate "<topic>"
+```
+
+Natural-language: "토론 시작해줘", "start a deliberation"
+
+Initiates a structured multi-session deliberation thread on the given topic.
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `No sessions configured` | No aigentry session config found | Configure sessions first |
+| `Terminal not supported` | Layout requires kitty or ghostty | Use a supported terminal |

package/specs/codex-inject-spec.md

@@ -0,0 +1,201 @@
+# SPEC: Codex inject reliability — 4 issues
+
+**Bug source:** orchestrator inject e9f41301...
+**Session:** aigentry-telepty
+**Status:** SPEC — awaiting orchestrator approval
+
+---
+
+## Goal
+
+Make `telepty inject` work reliably with codex sessions. Currently 4 failure
+modes: Enter not pressed, active work overwrite, REPORT not sent, multi-task
+partial processing.
+
+---
+
+## Root Cause Analysis
+
+### Issue 1: inject succeeds but Enter NOT pressed
+
+**Flow:** daemon `deliverInjectionToSession()` → mailbox → `tick()` →
+`writeDataToSession()` sends text via WS → allow-bridge → `child.write(text)`.
+Then 500ms later, `writeDataToSession(id, session, '\r')` → WS → allow-bridge →
+`child.write('\r')`.
+
+**Root cause:** codex CLI puts terminal in raw mode with custom input handling.
+PTY-level `\r` via `child.write('\r')` is NOT equivalent to pressing Enter in
+codex's input model. codex reads PTY input character by character in raw mode
+and interprets `\r` differently than a keyboard Enter event.
+
+**Evidence:** Project memory: "PTY `\r` 직접 의존 금지" — don't depend on PTY
+`\r` directly. "inject submit은 항상 osascript/kitty terminal-level submit 우선".
+
+The `--submit` flag exists in CLI but POST /submit also uses `submitViaPty()` →
+same `\r` via WS. It does NOT use terminal-level submit (kitty/cmux).
+
+### Issue 2: New inject overwrites active work
+
+**Flow:** `deliverInjectionToSession()` enqueues to mailbox and calls
+`mailboxDelivery.tick()` immediately. Text goes via WS → allow-bridge.
+
+Allow-bridge has queuing: if `isIdle()` is false, text goes to
+`enqueueBridgeMessage()`. The safety timer flushes after 5s regardless. But the
+daemon doesn't check session state — it pushes immediately.
+
+**Root cause:** Two layers of the problem:
+1. Daemon sends inject regardless of session state (working/thinking/idle)
+2. Allow-bridge 5s safety flush writes queued text to PTY even if session is
+   still working, which interrupts codex's current task
+
+### Issue 3: REPORT not sent after completion
+
+**Flow:** Auto-report mechanism (`pendingReports`) triggers when allow-bridge
+sends `{ type: 'ready' }` WS message. The `ready` signal fires when
+`promptPattern.test(data)` matches in the PTY output.
+
+**Root cause:** codex prompt pattern `codex: /[❯>]\s*$/` doesn't reliably match
+codex's actual prompt output. If prompt is never detected → `ready` never sent →
+`pendingReports` never cleared → auto-report never fires.
+
+The new session state machine (#185) detects `idle` via OSC 133 + silence
+timeout, but auto-report still uses the legacy `ready` WS signal (daemon.js
+line 2290-2315), not the `session_auto_state` transitions.
+
+### Issue 4: Multiple tasks in one inject — partial processing
+
+**Root cause:** AI behavior, not telepty bug. When a --ref file contains Task A
++ Task B, codex processes Task A and returns to prompt. This is standard LLM
+behavior — no telepty fix needed.
+
+**Mitigation:** Orchestrator should split multi-task injects into separate
+sequential calls with idle-gating between them (orchestrator-side logic).
+
+---
+
+## Scope
+
+**Phase 1 (this spec):** Fix Issues 1 and 3 (guaranteed Enter + guaranteed
+REPORT). These are telepty-side fixes.
+
+**Phase 2 (separate task):** Fix Issue 2 (inject queuing during active work).
+Requires daemon-side session state awareness.
+
+**Out of scope:** Issue 4 (orchestrator-level task splitting).
+
+---
+
+## Files to Modify
+
+| File | Change |
+|---|---|
+| `daemon.js` | Fix 1: `deliverInjectionToSession()` — use `sendViaKitty()` for CR instead of PTY `\r`. Fix 3: Wire auto-report to session state `idle` transition instead of legacy `ready` signal. |
+| `daemon.js` | Fix 1: POST `/submit` endpoint — use kitty send-text with cmux fallback instead of `submitViaPty()`. |
+
+---
+
+## Approach
+
+### Fix 1: Terminal-level submit for wrapped sessions
+
+Replace PTY `\r` with `sendViaKitty()` in `deliverInjectionToSession()`:
+
+```js
+// BEFORE (daemon.js ~line 590):
+if (!options.noEnter && session.type !== 'aterm') {
+  const submitDelay = session.type === 'wrapped' ? 500 : 300;
+  setTimeout(async () => {
+    const submitResult = await writeDataToSession(id, session, '\r');
+    // ...
+  }, submitDelay);
+}
+
+// AFTER:
+if (!options.noEnter && session.type !== 'aterm') {
+  const submitDelay = session.type === 'wrapped' ? 500 : 300;
+  setTimeout(async () => {
+    let submitted = false;
+    // Priority 1: kitty send-text (terminal-level, bypasses PTY quirks)
+    if (session.type === 'wrapped') {
+      submitted = sendViaKitty(id, '\r');
+    }
+    // Priority 2: cmux send-key (for cmux-managed sessions)
+    if (!submitted && session.backend === 'cmux' && session.cmuxWorkspaceId) {
+      submitted = submitViaCmux(id);
+    }
+    // Priority 3: PTY fallback (spawned sessions without kitty)
+    if (!submitted) {
+      const submitResult = await writeDataToSession(id, session, '\r');
+      if (!submitResult.success) {
+        emitInjectFailureEvent(id, submitResult.code, submitResult.error, {
+          phase: 'submit', source: options.source || 'inject'
+        }, session);
+      }
+    }
+  }, submitDelay);
+}
+```
+
+Also update POST `/submit` endpoint to use same priority chain instead of
+always calling `submitViaPty()`.
+
+### Fix 3: Auto-report via session state machine
+
+Wire auto-report to the `session_auto_state` transition event (already emitted
+by `sessionStateManager.onTransition()`). When a session transitions to `idle`
+and has a pending report, fire the auto-report.
+
+```js
+// In the existing sessionStateManager.onTransition callback (daemon.js ~line 37):
+sessionStateManager.onTransition((sessionId, from, to, detail) => {
+  const session = sessions[sessionId];
+  if (!session) return;
+  broadcastSessionEvent('session_auto_state', sessionId, session, {
+    extra: { auto_state: to, auto_state_from: from, auto_detail: detail }
+  });
+
+  // Auto-report: fire when session transitions to idle after inject
+  if (to === 'idle' && pendingReports[sessionId]) {
+    const pendingReport = pendingReports[sessionId];
+    delete pendingReports[sessionId];
+    const elapsed = ((Date.now() - new Date(pendingReport.injectedAt).getTime()) / 1000).toFixed(1);
+    const reportMsg = `TASK_COMPLETE: ${sessionId} is now idle after processing inject (${elapsed}s)`;
+    const srcId = resolveSessionAlias(pendingReport.source) || pendingReport.source;
+    const srcSession = sessions[srcId];
+    if (srcSession) {
+      deliverInjectionToSession(srcId, srcSession, reportMsg, { noEnter: false, source: 'auto_report' });
+      console.log(`[AUTO-REPORT] ${sessionId} → ${srcId}: idle after ${elapsed}s`);
+    }
+  }
+});
+```
+
+Keep the legacy `ready`-based auto-report as fallback (don't remove it).
+
+---
+
+## Verification
+
+1. **Test:** `telepty inject xtem-rtm "echo hello"` → codex processes it
+   (Enter pressed via kitty send-text)
+2. **Test:** `telepty inject --ref --from orchestrator xtem-rtm 'task'` → after
+   codex completes → auto-report fires via idle state transition
+3. **Test:** Sessions without kitty (spawned) → PTY `\r` fallback still works
+4. **Test:** Existing 131 tests still pass
+
+---
+
+## Risks
+
+1. **kitty not available.** Mitigated: 3-tier fallback (kitty → cmux → PTY).
+   PTY path preserved as last resort.
+2. **`sendViaKitty()` needs kitty socket + window ID match.** Already
+   implemented and working for other features. If kitty window not found,
+   falls through to PTY.
+3. **Auto-report via state machine may fire too early.** The idle detection
+   uses 5s silence timeout. If codex pauses >5s mid-task, it may fire
+   prematurely. Mitigated: auto-report has `AUTO_REPORT_IDLE_SECONDS` (10s)
+   threshold. Can add a minimum elapsed time guard.
+4. **Dual auto-report paths (state machine + legacy ready).** Could fire
+   twice. Mitigated: `delete pendingReports[sessionId]` in both paths —
+   whichever fires first consumes the pending report.

package/src/mailbox/config.js

@@ -27,6 +27,10 @@ const DEFAULTS = {
   deliveryPollMs: 200,
   /** Notification coalesce window in ms. */
   notifyCoalesceMs: 25,
+  /** Lock age threshold in seconds — break locks older than this (handles PID recycling). */
+  staleLockAgeSecs: 60,
+  /** Force-break lock after this many consecutive lock timeout failures per session. */
+  lockBreakAfterFailures: 3,
 };
 
 function createConfig(overrides = {}) {

package/src/mailbox/delivery.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
+
 /**
  * DeliveryEngine — polls mailbox for pending messages and delivers them.
  *
@@ -9,6 +12,7 @@
  * Also handles:
  * - In-flight timeout recovery (auto-nack stuck messages)
  * - TTL expiry (expire stale pending messages)
+ * - Stale lock detection: consecutive failure tracking + exponential backoff
  */
 class DeliveryEngine {
   /**
@@ -28,6 +32,10 @@ class DeliveryEngine {
     this._timer = null;
     this._running = false;
     this._tickInProgress = false;
+    // Fix 4: Per-session consecutive lock failure count
+    this._lockFailures = new Map();  // sessionId → count
+    // Fix 5: Per-session skip-until timestamp for backoff
+    this._skipUntil = new Map();     // sessionId → timestamp
   }
 
   /**
@@ -66,8 +74,15 @@ class DeliveryEngine {
 
     try {
       const sessionIds = this.sessionResolver();
+      const lockBreakThreshold = this.mailbox.config.lockBreakAfterFailures || 3;
 
       for (const sessionId of sessionIds) {
+        // Fix 5: Skip sessions in backoff
+        const skipUntil = this._skipUntil.get(sessionId) || 0;
+        if (Date.now() < skipUntil) continue;
+
+        let lockFailed = false;
+
         // 1. Recover in-flight timeouts
         try {
           const recovered = this.mailbox.recoverInflight(sessionId);
@@ -75,52 +90,98 @@ class DeliveryEngine {
             console.log(`[MAILBOX] Recovered ${recovered} in-flight message(s) for ${sessionId}`);
           }
         } catch (err) {
-          console.error(`[MAILBOX] recoverInflight error for ${sessionId}: ${err.message}`);
+          if (err.message.includes('lock timeout')) {
+            lockFailed = true;
+          } else {
+            console.error(`[MAILBOX] recoverInflight error for ${sessionId}: ${err.message}`);
+          }
         }
 
         // 2. Expire stale messages
-        try {
-          const expired = this.mailbox.expireStale(sessionId);
-          if (expired > 0) {
-            console.log(`[MAILBOX] Expired ${expired} stale message(s) for ${sessionId}`);
+        if (!lockFailed) {
+          try {
+            const expired = this.mailbox.expireStale(sessionId);
+            if (expired > 0) {
+              console.log(`[MAILBOX] Expired ${expired} stale message(s) for ${sessionId}`);
+            }
+          } catch (err) {
+            if (err.message.includes('lock timeout')) {
+              lockFailed = true;
+            } else {
+              console.error(`[MAILBOX] expireStale error for ${sessionId}: ${err.message}`);
+            }
           }
-        } catch (err) {
-          console.error(`[MAILBOX] expireStale error for ${sessionId}: ${err.message}`);
         }
 
         // 3. Dequeue and deliver
-        try {
-          const msg = this.mailbox.dequeue(sessionId);
-          if (!msg) continue;
+        if (!lockFailed) {
+          try {
+            const msg = this.mailbox.dequeue(sessionId);
+            if (!msg) {
+              // Success path (no message but lock acquired OK)
+              this._lockFailures.delete(sessionId);
+              this._skipUntil.delete(sessionId);
+              continue;
+            }
 
-          if (!this.deliverFn) {
-            // No delivery function — auto-ack (testing mode)
-            this.mailbox.ack(sessionId, msg.msg_id);
-            continue;
-          }
+            if (!this.deliverFn) {
+              // No delivery function — auto-ack (testing mode)
+              this.mailbox.ack(sessionId, msg.msg_id);
+              this._lockFailures.delete(sessionId);
+              this._skipUntil.delete(sessionId);
+              continue;
+            }
 
-          let result;
-          try {
-            result = await this.deliverFn(sessionId, msg);
+            let result;
+            try {
+              result = await this.deliverFn(sessionId, msg);
+            } catch (err) {
+              result = { success: false, error: err.message };
+            }
+
+            if (result && result.success) {
+              this.mailbox.ack(sessionId, msg.msg_id);
+              if (this.onDelivery) {
+                this.onDelivery(sessionId, msg.msg_id, { success: true });
+              }
+            } else {
+              const reason = (result && result.error) || 'delivery failed';
+              this.mailbox.nack(sessionId, msg.msg_id, reason);
+              console.log(`[MAILBOX] Delivery failed for ${sessionId}/${msg.msg_id}: ${reason} (attempt ${msg.attempt})`);
+              if (this.onDelivery) {
+                this.onDelivery(sessionId, msg.msg_id, { success: false, error: reason });
+              }
+            }
+
+            // Success path (lock was acquired)
+            this._lockFailures.delete(sessionId);
+            this._skipUntil.delete(sessionId);
           } catch (err) {
-            result = { success: false, error: err.message };
+            if (err.message.includes('lock timeout')) {
+              lockFailed = true;
+            } else {
+              console.error(`[MAILBOX] Delivery loop error for ${sessionId}: ${err.message}`);
+            }
           }
+        }
 
-          if (result && result.success) {
-            this.mailbox.ack(sessionId, msg.msg_id);
-            if (this.onDelivery) {
-              this.onDelivery(sessionId, msg.msg_id, { success: true });
-            }
+        // Fix 4 & 5: Handle lock failure — track, force-break, backoff
+        if (lockFailed) {
+          const failCount = (this._lockFailures.get(sessionId) || 0) + 1;
+          this._lockFailures.set(sessionId, failCount);
+
+          // Fix 4: Force-break after N consecutive failures
+          if (failCount >= lockBreakThreshold) {
+            const lockPath = path.join(this.mailbox._sessionDir(sessionId), '.lock');
+            try { fs.unlinkSync(lockPath); } catch {}
+            console.warn(`[MAILBOX] Force-broke stale lock for ${sessionId} after ${failCount} consecutive failures`);
+            this._lockFailures.delete(sessionId);
+            this._skipUntil.delete(sessionId);
           } else {
-            const reason = (result && result.error) || 'delivery failed';
-            this.mailbox.nack(sessionId, msg.msg_id, reason);
-            console.log(`[MAILBOX] Delivery failed for ${sessionId}/${msg.msg_id}: ${reason} (attempt ${msg.attempt})`);
-            if (this.onDelivery) {
-              this.onDelivery(sessionId, msg.msg_id, { success: false, error: reason });
-            }
+            // Fix 5: Exponential backoff — skip this session for increasing intervals
+            const backoffMs = Math.min(this.pollMs * (1 << failCount), 30000);
+            this._skipUntil.set(sessionId, Date.now() + backoffMs);
           }
-        } catch (err) {
-          console.error(`[MAILBOX] Delivery loop error for ${sessionId}: ${err.message}`);
         }
       }
     } finally {

package/src/mailbox/index.js

@@ -4,6 +4,7 @@ const path = require('path');
 const fs = require('fs');
 const {
   acquireLock,
+  breakStaleLocks,
   ensureSessionDir,
   loadStates,
   appendState,
@@ -278,6 +279,16 @@ class FileMailbox {
     try { fs.writeFileSync(p, ''); } catch {}
   }
 
+  /**
+   * Break stale lock files across all session directories.
+   * Call at daemon startup before DeliveryEngine.start().
+   * Returns count of broken locks.
+   */
+  breakStaleLocks() {
+    const staleLockAgeMs = (this.config.staleLockAgeSecs || 60) * 1000;
+    return breakStaleLocks(this.config.root, { staleLockAgeMs });
+  }
+
   /**
    * List all session IDs that have a mailbox directory.
    */