@dmsdc-ai/aigentry-telepty 0.1.95 → 0.1.97

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/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.
    */

package/src/mailbox/storage.js

@@ -7,6 +7,7 @@ const path = require('path');
 
 const LOCK_POLL_MS = 10;
 const LOCK_TIMEOUT_MS = 500;
+const DEFAULT_STALE_LOCK_AGE_MS = 60000; // 60s — lock hold time is ~5ms, so 60s is definitionally stale
 
 function isProcessAlive(pid) {
   try {
@@ -20,10 +21,15 @@ function isProcessAlive(pid) {
 /**
  * Acquire an advisory lock for a session directory.
  * Returns a release function. Throws on timeout.
+ *
+ * @param {string} sessionDir
+ * @param {Object} [options]
+ * @param {number} [options.staleLockAgeMs] — break locks older than this (default 60s)
  */
-function acquireLock(sessionDir) {
+function acquireLock(sessionDir, options = {}) {
   const lockPath = path.join(sessionDir, '.lock');
   const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  const staleLockAgeMs = options.staleLockAgeMs || DEFAULT_STALE_LOCK_AGE_MS;
 
   while (Date.now() < deadline) {
     try {
@@ -36,12 +42,28 @@ function acquireLock(sessionDir) {
     } catch (err) {
       if (err.code !== 'EEXIST') throw err;
 
-      // Lock file exists — check for stale PID
+      // Lock file exists — check age first, then PID
+
+      // Fix 2: Lock age threshold — if lock is older than staleLockAgeMs,
+      // break regardless of PID (handles PID recycling)
+      try {
+        const stat = fs.statSync(lockPath);
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs > staleLockAgeMs) {
+          try { fs.unlinkSync(lockPath); } catch {}
+          continue;
+        }
+      } catch {
+        // stat failed — file may have been removed between EEXIST and stat
+        continue;
+      }
+
+      // Fix 1: Invalid PID handling — treat NaN, 0, negative, empty as stale
       try {
         const content = fs.readFileSync(lockPath, 'utf8').trim();
         const pid = Number(content);
-        if (pid > 0 && !isProcessAlive(pid)) {
-          // Stale lock — remove and retry
+        if (!Number.isFinite(pid) || pid <= 0 || !isProcessAlive(pid)) {
+          // Invalid PID (empty, NaN, 0, negative) OR dead PID → stale lock
           try { fs.unlinkSync(lockPath); } catch {}
           continue;
         }
@@ -51,7 +73,7 @@ function acquireLock(sessionDir) {
         continue;
       }
 
-      // Lock is held by a live process — wait
+      // Lock is held by a live process with a recent lock — wait
       const buffer = new SharedArrayBuffer(4);
       const view = new Int32Array(buffer);
       Atomics.wait(view, 0, 0, LOCK_POLL_MS);
@@ -61,6 +83,61 @@ function acquireLock(sessionDir) {
   throw new Error(`Mailbox lock timeout for ${sessionDir}`);
 }
 
+/**
+ * Break stale lock files across all session directories (startup sweep).
+ * Returns count of broken locks.
+ *
+ * @param {string} root — mailbox root directory
+ * @param {Object} [options]
+ * @param {number} [options.staleLockAgeMs] — age threshold (default 60s)
+ */
+function breakStaleLocks(root, options = {}) {
+  const staleLockAgeMs = options.staleLockAgeMs || DEFAULT_STALE_LOCK_AGE_MS;
+  const dirs = listSessionDirs(root);
+  let broken = 0;
+
+  for (const { sessionId, dir } of dirs) {
+    const lockPath = path.join(dir, '.lock');
+    if (!fs.existsSync(lockPath)) continue;
+
+    let shouldBreak = false;
+    let reason = '';
+
+    try {
+      const stat = fs.statSync(lockPath);
+      const ageMs = Date.now() - stat.mtimeMs;
+
+      if (ageMs > staleLockAgeMs) {
+        shouldBreak = true;
+        reason = `age ${Math.round(ageMs / 1000)}s > ${Math.round(staleLockAgeMs / 1000)}s threshold`;
+      } else {
+        // Check PID validity
+        const content = fs.readFileSync(lockPath, 'utf8').trim();
+        const pid = Number(content);
+        if (!Number.isFinite(pid) || pid <= 0) {
+          shouldBreak = true;
+          reason = `invalid PID: ${JSON.stringify(content)}`;
+        } else if (!isProcessAlive(pid)) {
+          shouldBreak = true;
+          reason = `dead PID ${pid}`;
+        }
+      }
+    } catch {
+      // Can't read/stat lock — treat as stale
+      shouldBreak = true;
+      reason = 'unreadable lock file';
+    }
+
+    if (shouldBreak) {
+      try { fs.unlinkSync(lockPath); } catch {}
+      console.log(`[MAILBOX] Broke stale lock for ${sessionId}: ${reason}`);
+      broken++;
+    }
+  }
+
+  return broken;
+}
+
 // --- JSONL read/write ---
 
 function readJsonl(filePath) {
@@ -172,6 +249,7 @@ function compact(sessionDir, threshold) {
 
 module.exports = {
   acquireLock,
+  breakStaleLocks,
   readJsonl,
   appendJsonl,
   writeJsonl,
@@ -182,4 +260,5 @@ module.exports = {
   loadMessages,
   countPending,
   compact,
+  isProcessAlive,
 };