@dmsdc-ai/aigentry-telepty 0.1.88 → 0.1.89

package/cli.js

@@ -18,6 +18,7 @@ const { formatHostLabel, groupSessionsByHost, pickSessionTarget } = require('./s
 const { buildSharedContextPrompt, createSharedContextDescriptor, ensureSharedContextFile } = require('./shared-context');
 const { runInteractiveSkillInstaller } = require('./skill-installer');
 const crossMachine = require('./cross-machine');
+const { FileMailbox } = require('./src/mailbox/index');
 const args = process.argv.slice(2);
 let pendingTerminalInputError = null;
 let simulatedPromptErrorInjected = false;
@@ -1000,10 +1001,41 @@ async function main() {
     const cmdBase = path.basename(command).replace(/\..*$/, '');
     const promptPattern = PROMPT_PATTERNS[cmdBase] || /[❯>$#%]\s*$/;
     let promptReady = false;  // wait for CLI prompt before accepting inject
-    const injectQueue = [];
     let lastUserInputTime = 0;  // timestamp of last user keystroke
     const IDLE_THRESHOLD = 2000; // ms after last user input to consider idle
 
+    // Mailbox-backed inject queue (replaces in-memory array for crash resilience)
+    const bridgeMailbox = new FileMailbox({
+      root: path.join(os.homedir(), '.aigentry', 'mailbox', 'bridge'),
+    });
+    const bridgeTarget = sessionId;
+    let bridgeMsgSeq = 0;
+    let bridgePendingCount = 0;
+
+    // Recover undelivered messages from a previous crash
+    try {
+      const leftover = bridgeMailbox.peek(bridgeTarget).filter(m => m.state === 'pending' || m.state === 'in_flight');
+      bridgePendingCount = leftover.length;
+      if (bridgePendingCount > 0) {
+        console.log(`\x1b[33m[BRIDGE] Recovered ${bridgePendingCount} undelivered message(s) from previous session\x1b[0m`);
+      }
+    } catch {}
+
+    function enqueueBridgeMessage(text) {
+      const msgId = `${sessionId}:${Date.now()}:${++bridgeMsgSeq}`;
+      try {
+        bridgeMailbox.enqueue({
+          msg_id: msgId, from: 'daemon', to: bridgeTarget,
+          payload: text, created_at: Math.floor(Date.now() / 1000), attempt: 0,
+        });
+        bridgePendingCount++;
+      } catch (err) {
+        // Fallback: write directly if mailbox fails
+        console.error(`[BRIDGE] Mailbox enqueue failed, writing directly: ${err.message}`);
+        child.write(text);
+      }
+    }
+
     function isIdle() {
       return promptReady && (Date.now() - lastUserInputTime > IDLE_THRESHOLD);
     }
@@ -1011,34 +1043,47 @@ async function main() {
     let queueFlushTimer = null;
     let idleCheckTimer = null;
 
-    function flushInjectQueue() {
+    function flushBridgeMailbox() {
       if (queueFlushTimer) { clearTimeout(queueFlushTimer); queueFlushTimer = null; }
       if (idleCheckTimer) { clearInterval(idleCheckTimer); idleCheckTimer = null; }
-      if (injectQueue.length === 0) return;
-      const batch = injectQueue.splice(0);
+      if (bridgePendingCount === 0) return;
       let delay = 0;
-      for (const item of batch) {
-        setTimeout(() => child.write(item), delay);
-        delay += item === '\r' ? 0 : 100;
-      }
+      const batch = [];
+      // Dequeue all pending messages
+      while (true) {
+        const msg = bridgeMailbox.dequeue(bridgeTarget);
+        if (!msg) break;
+        batch.push(msg);
+      }
+      if (batch.length === 0) { bridgePendingCount = 0; return; }
+      for (const msg of batch) {
+        const text = msg.payload;
+        const msgId = msg.msg_id;
+        setTimeout(() => {
+          child.write(text);
+          try { bridgeMailbox.ack(bridgeTarget, msgId); } catch {}
+        }, delay);
+        delay += text === '\r' ? 0 : 100;
+      }
+      bridgePendingCount = Math.max(0, bridgePendingCount - batch.length);
       promptReady = false;
     }
     function scheduleIdleFlush() {
       if (idleCheckTimer) return;
       // Poll every 500ms for idle state
       idleCheckTimer = setInterval(() => {
-        if (isIdle() && injectQueue.length > 0) {
-          flushInjectQueue();
+        if (isIdle() && bridgePendingCount > 0) {
+          flushBridgeMailbox();
         }
       }, 500);
-      // Safety: flush after 15s regardless (prevent stuck queue)
+      // Safety: flush after 5s regardless (prevent stuck queue when prompt not detected)
       if (!queueFlushTimer) {
         queueFlushTimer = setTimeout(() => {
           queueFlushTimer = null;
-          if (injectQueue.length > 0) {
-            flushInjectQueue();
+          if (bridgePendingCount > 0) {
+            flushBridgeMailbox();
           }
-        }, 15000);
+        }, 5000);
       }
     }
 
@@ -1104,11 +1149,11 @@ async function main() {
               }
 
               const isCr = chunk === '\r';
-              if (isCr && injectQueue.length > 0) {
+              if (isCr && bridgePendingCount > 0) {
                 // CR with pending queued text — queue CR too and flush immediately.
-                injectQueue.push(chunk);
+                enqueueBridgeMessage(chunk);
                 if (queueFlushTimer) { clearTimeout(queueFlushTimer); queueFlushTimer = null; }
-                flushInjectQueue();
+                flushBridgeMailbox();
               } else if (isCr) {
                 // CR always written immediately — never idle-gated.
                 child.write(chunk);
@@ -1119,7 +1164,7 @@ async function main() {
                 lastInjectTextTime = Date.now();
               } else {
                 // Text when not idle — queue for safe delivery.
-                injectQueue.push(chunk);
+                enqueueBridgeMessage(chunk);
                 scheduleIdleFlush();
               }
             }
@@ -1184,6 +1229,8 @@ async function main() {
 
       allowSessionClosed = true;
       cleanupTerminal();
+      // Purge bridge mailbox on clean exit (undelivered messages are stale)
+      try { bridgeMailbox.purge(bridgeTarget); } catch {}
       process.stdout.write(`\x1b]0;\x07`);
       fetchWithAuth(`${DAEMON_URL}/api/sessions/${encodeURIComponent(sessionId)}`, { method: 'DELETE' }).catch(() => {});
       if (reconnectTimer) clearTimeout(reconnectTimer);
@@ -1220,7 +1267,7 @@ async function main() {
       // Detect prompt in output to enable inject delivery
       if (promptPattern.test(data)) {
         promptReady = true;
-        flushInjectQueue();
+        flushBridgeMailbox();
         // Notify daemon that CLI is ready for inject
         if (!readyNotified && wsReady && daemonWs.readyState === 1) {
           readyNotified = true;
@@ -1257,7 +1304,7 @@ async function main() {
                 }
                 if (promptPattern.test(data)) {
                   promptReady = true;
-                  flushInjectQueue();
+                  flushBridgeMailbox();
                   if (wsReady && daemonWs.readyState === 1) {
                     daemonWs.send(JSON.stringify({ type: 'ready' }));
                   }
@@ -1656,6 +1703,76 @@ async function main() {
     return;
   }
 
+  if (cmd === 'status') {
+    const statusSessionId = args[1] || process.env.TELEPTY_SESSION_ID;
+    if (!statusSessionId) {
+      console.error('❌ Usage: telepty status <session_id>');
+      process.exit(1);
+    }
+
+    try {
+      const target = await resolveSessionTarget(statusSessionId);
+      if (!target) {
+        console.error(`❌ Session '${statusSessionId}' was not found on any discovered host.`);
+        process.exit(1);
+      }
+
+      const res = await fetchWithAuth(`http://${target.host}:${PORT}/api/sessions/${encodeURIComponent(target.id)}/state`);
+      const data = await res.json();
+      if (!res.ok) {
+        console.error(`❌ ${formatApiError(data)}`);
+        process.exit(1);
+      }
+
+      const auto = data.auto || {};
+      const selfReport = data.self_report || {};
+
+      // Color-coded state display
+      const stateColors = {
+        running: '\x1b[32m',       // green
+        idle: '\x1b[33m',          // yellow
+        thinking: '\x1b[36m',      // cyan
+        stuck: '\x1b[31m',         // red
+        waiting_input: '\x1b[35m', // magenta
+      };
+      const stateColor = stateColors[auto.state] || '\x1b[37m';
+      const reset = '\x1b[0m';
+
+      console.log(`\n  Session: \x1b[36m${data.session_id}${reset}`);
+      console.log(`  Auto State: ${stateColor}${auto.state || 'unknown'}${reset} (confidence: ${auto.confidence != null ? (auto.confidence * 100).toFixed(0) + '%' : '?'})`);
+      if (auto.since) {
+        const durationMs = auto.duration_ms || 0;
+        const durationStr = durationMs < 60000
+          ? `${(durationMs / 1000).toFixed(0)}s`
+          : `${(durationMs / 60000).toFixed(1)}m`;
+        console.log(`  Since: ${auto.since} (${durationStr} ago)`);
+      }
+      if (auto.detail) {
+        console.log(`  Trigger: ${auto.detail.trigger || '-'}`);
+        if (auto.detail.matched_line) console.log(`  Matched: "${auto.detail.matched_line}"`);
+        if (auto.detail.silence_ms) console.log(`  Silence: ${(auto.detail.silence_ms / 1000).toFixed(1)}s`);
+        if (auto.detail.repeat_count) console.log(`  Error repeats: ${auto.detail.repeat_count}`);
+      }
+      if (auto.last_output_preview) {
+        const preview = auto.last_output_preview.replace(/\n/g, '\\n').slice(-80);
+        console.log(`  Last output: "${preview}"`);
+      }
+
+      if (selfReport.phase) {
+        console.log(`\n  Self-report:`);
+        console.log(`    Phase: ${selfReport.phase}`);
+        if (selfReport.current_task) console.log(`    Task: ${selfReport.current_task}`);
+        if (selfReport.blocker) console.log(`    Blocker: \x1b[31m${selfReport.blocker}${reset}`);
+        if (selfReport.needs_input) console.log(`    Needs input: \x1b[35myes${reset}`);
+      }
+      console.log('');
+    } catch (e) {
+      console.error(`❌ ${e.message || 'Failed to get session state.'}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   if (cmd === 'status-report') {
     const reportArgs = args.slice(1);
     let sessionId = process.env.TELEPTY_SESSION_ID || undefined;

package/daemon.js

@@ -9,6 +9,10 @@ const pkg = require('./package.json');
 const { claimDaemonState, clearDaemonState } = require('./daemon-control');
 const { checkEntitlement } = require('./entitlement');
 const terminalBackend = require('./terminal-backend');
+const { FileMailbox } = require('./src/mailbox/index');
+const { DeliveryEngine } = require('./src/mailbox/delivery');
+const { UnixSocketNotifier } = require('./src/mailbox/notifier');
+const { SessionStateManager } = require('./session-state');
 
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
@@ -21,6 +25,23 @@ const SESSION_CLEANUP_SECONDS = Math.max(SESSION_STALE_SECONDS, Number(process.e
 const DELIVERY_TIMEOUT_MS = Math.max(100, Number(process.env.TELEPTY_DELIVERY_TIMEOUT_MS || 5000));
 const HEALTH_POLL_MS = Math.max(100, Number(process.env.TELEPTY_HEALTH_POLL_MS || 10000));
 
+// Session state machine manager — auto-detects session state from PTY output
+const sessionStateManager = new SessionStateManager({
+  idle_timeout_ms:    Number(process.env.TELEPTY_STATE_IDLE_TIMEOUT_MS || 5000),
+  stuck_repeat_count: Number(process.env.TELEPTY_STATE_STUCK_REPEAT_COUNT || 3),
+  stuck_window_ms:    Number(process.env.TELEPTY_STATE_STUCK_WINDOW_MS || 180000),
+  thinking_timeout_ms:Number(process.env.TELEPTY_STATE_THINKING_TIMEOUT_MS || 300000),
+});
+
+// Broadcast state transitions to the bus
+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 }
+  });
+});
+
 function persistSessions() {
   try {
     const data = {};
@@ -227,12 +248,9 @@ function getSessionHealthStatus(session, options = {}) {
       const isSocketPath = endpoint.startsWith('/');
       if (isSocketPath) {
         try {
-          fs.accessSync(endpoint, fs.constants.F_OK);
-          return 'CONNECTED';
+          const stat = fs.statSync(endpoint);
+          return stat.isSocket() ? 'CONNECTED' : 'DISCONNECTED';
         } catch {
-          session.deliveryEndpoint = null;
-          if (session.delivery) session.delivery.address = null;
-          session.lastDisconnectedAt = session.lastDisconnectedAt || new Date().toISOString();
           return 'DISCONNECTED';
         }
       }
@@ -461,6 +479,7 @@ async function writeDataToSession(id, session, data) {
             try {
               const resp = JSON.parse(responseBuf.trim());
               if (resp.status === 'Error' || resp.success === false) {
+                console.log(`[UDS] Delivery rejected by ${id}: ${resp.error || resp.message || 'unknown'}`);
                 resolve(buildErrorBody('DELIVERY_REJECTED', resp.error || resp.message || 'Target rejected the payload.', {
                   httpStatus: 502,
                   detail: resp
@@ -470,11 +489,15 @@ async function writeDataToSession(id, session, data) {
             } catch {
               // Non-JSON response — treat as success (legacy endpoints)
             }
+          } else {
+            console.log(`[UDS] Empty response from ${id} — delivery unconfirmed (aterm may not have processed)`);
           }
           resolve({ success: true });
         });
         sock.on('error', (err) => {
           clearTimeout(timeout);
+          console.log(`[UDS] Connection error for ${id} at ${session.delivery.address}: ${err.message}`);
+          markSessionDisconnected(session);
           resolve(buildErrorBody('DISCONNECTED', 'UDS endpoint is unreachable.', {
             httpStatus: 503,
             detail: err.message
@@ -538,34 +561,67 @@ async function deliverInjectionToSession(id, session, prompt, options = {}) {
     return { success: false, ...injectFailure };
   }
 
-  const textResult = await writeDataToSession(id, session, prompt);
-  if (!textResult.success) {
-    return textResult;
-  }
+  // Build the payload: text + CR for non-aterm sessions (aterm handles Enter internally)
+  const payload = (!options.noEnter && session.type !== 'aterm')
+    ? prompt + '\r'
+    : prompt;
 
-  if (!options.noEnter && session.type !== 'aterm') {
-    const submitDelay = session.type === 'wrapped' ? 500 : 300;
-    setTimeout(async () => {
-      const submitResult = await writeDataToSession(id, session, '\r');
-      if (!submitResult.success) {
-        emitInjectFailureEvent(id, submitResult.code, submitResult.error, {
-          phase: 'submit',
-          source: options.source || 'inject'
-        }, session);
-      }
-    }, submitDelay);
-  }
+  const from = options.from || 'daemon';
+  const msgId = `${from}:${Date.now()}:${crypto.randomUUID().slice(0, 8)}`;
 
-  session.lastActivityAt = new Date(now).toISOString();
-  return {
-    success: true,
-    strategy: session.type === 'wrapped'
-      ? 'ws_split_cr'
-      : session.type === 'aterm'
-        ? (session.delivery && session.delivery.transport === 'unix_socket' ? 'aterm_uds' : 'aterm_endpoint')
-        : 'pty_split_cr',
-    submit: options.noEnter ? 'skipped' : 'deferred'
-  };
+  try {
+    const ack = mailbox.enqueue({
+      msg_id: msgId,
+      from,
+      to: id,
+      payload,
+      created_at: Math.floor(now / 1000),
+      attempt: 0,
+    });
+
+    // Notify aterm sessions immediately via UDS wake
+    if (session.type === 'aterm') {
+      mailboxNotifier.notify(id);
+    }
+
+    // Trigger immediate delivery tick for low-latency
+    mailboxDelivery.tick().catch(() => {});
+
+    session.lastActivityAt = new Date(now).toISOString();
+    return {
+      success: true,
+      msg_id: msgId,
+      queued: ack.queued,
+      pending: ack.pending,
+      strategy: 'mailbox',
+      submit: options.noEnter ? 'skipped' : 'included'
+    };
+  } catch (err) {
+    console.error(`[MAILBOX] Enqueue failed for ${id}: ${err.message}`);
+    // Fallback: direct delivery (backward compat during migration)
+    const textResult = await writeDataToSession(id, session, prompt);
+    if (!textResult.success) return textResult;
+
+    if (!options.noEnter && session.type !== 'aterm') {
+      const submitDelay = session.type === 'wrapped' ? 500 : 300;
+      setTimeout(async () => {
+        const submitResult = await writeDataToSession(id, session, '\r');
+        if (!submitResult.success) {
+          emitInjectFailureEvent(id, submitResult.code, submitResult.error, {
+            phase: 'submit',
+            source: options.source || 'inject'
+          }, session);
+        }
+      }, submitDelay);
+    }
+
+    session.lastActivityAt = new Date(now).toISOString();
+    return {
+      success: true,
+      strategy: 'direct_fallback',
+      submit: options.noEnter ? 'skipped' : 'deferred'
+    };
+  }
 }
 
 function appendToOutputRing(session, data) {
@@ -606,6 +662,7 @@ function serializeSession(id, session, options = {}) {
   const disconnectedMs = getSessionDisconnectedMs(session, nowMs);
   const transport = buildSessionTransportBlock(session, { nowMs });
   const semantic = buildSessionSemanticBlock(session);
+  const autoState = sessionStateManager.getState(id);
 
   return {
     id,
@@ -633,7 +690,15 @@ function serializeSession(id, session, options = {}) {
     disconnectedSeconds: disconnectedMs === null ? null : Math.floor(disconnectedMs / 1000),
     lastStateReportAt: session.lastStateReportAt || null,
     transport,
-    semantic
+    semantic,
+    autoState: autoState ? { state: autoState.state, since: autoState.since, confidence: autoState.confidence } : null,
+    mailbox: (() => {
+      try {
+        const pending = mailbox.peek(id).filter(m => m.state === 'pending' || m.state === 'in_flight');
+        const deadLetter = mailbox.peekDeadLetter(id);
+        return { pending: pending.length, dead_letter: deadLetter.length };
+      } catch { return { pending: 0, dead_letter: 0 }; }
+    })()
   };
 }
 
@@ -797,6 +862,7 @@ app.post('/api/sessions/spawn', (req, res) => {
       }
 
       appendToOutputRing(currentSession, data);
+      sessionStateManager.feed(sessionRecord.id, data);
 
       // Send to direct WS clients
       currentSession.clients.forEach(ws => {
@@ -804,6 +870,9 @@ app.post('/api/sessions/spawn', (req, res) => {
       });
     });
 
+    // Register session with state machine
+    sessionStateManager.register(session_id);
+
     ptyProcess.onExit(({ exitCode, signal }) => {
       const currentId = sessionRecord.id;
       console.log(`[EXIT] Session ${currentId} exited with code ${exitCode}`);
@@ -811,6 +880,7 @@ app.post('/api/sessions/spawn', (req, res) => {
       sessionRecord.clients.forEach(ws => ws.close(1000, 'Session exited'));
       if (sessions[currentId] === sessionRecord) {
         delete sessions[currentId];
+        sessionStateManager.unregister(currentId);
       }
     });
 
@@ -908,6 +978,7 @@ app.post('/api/sessions/register', (req, res) => {
   }
 
   sessions[session_id] = sessionRecord;
+  sessionStateManager.register(session_id);
 
   const busMsg = JSON.stringify({
     type: 'session_register',
@@ -949,6 +1020,26 @@ app.get('/api/sessions/:id', (req, res) => {
   });
 });
 
+// Auto-detected session state (from PTY output pattern analysis)
+app.get('/api/sessions/:id/state', (req, res) => {
+  const requestedId = req.params.id;
+  const resolvedId = resolveSessionAlias(requestedId);
+  if (!resolvedId) return respondWithError(res, 404, 'SESSION_NOT_FOUND', 'Session not found', { requested: requestedId });
+  if (!sessions[resolvedId]) return respondWithError(res, 404, 'SESSION_NOT_FOUND', 'Session not found', { requested: requestedId });
+
+  const autoState = sessionStateManager.getState(resolvedId);
+  const session = sessions[resolvedId];
+  const semantic = buildSessionSemanticBlock(session);
+
+  res.json({
+    session_id: resolvedId,
+    auto: autoState || { state: 'unknown', detail: 'no state machine registered' },
+    self_report: semantic,
+    last_state_report_at: session.lastStateReportAt || null,
+  });
+});
+
+// Self-reported session state (explicit POST from session)
 app.post('/api/sessions/:id/state', (req, res) => {
   const requestedId = req.params.id;
   const resolvedId = resolveSessionAlias(requestedId);
@@ -977,10 +1068,59 @@ app.get('/api/meta', (req, res) => {
     port: Number(PORT),
     machine_id: MACHINE_ID,
     terminal: DETECTED_TERMINAL,
-    capabilities: ['sessions', 'wrapped-sessions', 'skill-installer', 'singleton-daemon', 'handoff-inbox', 'deliberation-threads', 'cross-machine']
+    capabilities: ['sessions', 'wrapped-sessions', 'skill-installer', 'singleton-daemon', 'handoff-inbox', 'deliberation-threads', 'cross-machine', 'mailbox']
   });
 });
 
+// --- Mailbox API endpoints ---
+
+app.get('/api/sessions/:id/mailbox', (req, res) => {
+  const id = resolveSessionAlias(req.params.id);
+  if (!id || !sessions[id]) return res.status(404).json({ error: 'Session not found' });
+  try {
+    const pending = mailbox.peek(id);
+    const deadLetter = mailbox.peekDeadLetter(id);
+    res.json({ session_id: id, pending, dead_letter: deadLetter });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.post('/api/sessions/:id/mailbox/ack', (req, res) => {
+  const id = resolveSessionAlias(req.params.id);
+  if (!id || !sessions[id]) return res.status(404).json({ error: 'Session not found' });
+  const { msg_id } = req.body;
+  if (!msg_id) return res.status(400).json({ error: 'msg_id is required' });
+  try {
+    mailbox.ack(id, msg_id);
+    res.json({ success: true, msg_id });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.delete('/api/sessions/:id/mailbox', (req, res) => {
+  const id = resolveSessionAlias(req.params.id);
+  if (!id || !sessions[id]) return res.status(404).json({ error: 'Session not found' });
+  try {
+    mailbox.purge(id);
+    res.json({ success: true, session_id: id });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+app.delete('/api/sessions/:id/mailbox/dead-letter', (req, res) => {
+  const id = resolveSessionAlias(req.params.id);
+  if (!id || !sessions[id]) return res.status(404).json({ error: 'Session not found' });
+  try {
+    mailbox.purgeDeadLetter(id);
+    res.json({ success: true, session_id: id });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // Peer management endpoint (for cross-machine module)
 app.get('/api/peers', (req, res) => {
   try {
@@ -1336,7 +1476,8 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
   try {
     const delivery = await deliverInjectionToSession(id, session, finalPrompt, {
       noEnter: !!no_enter,
-      source: 'inject'
+      source: 'inject',
+      from: from || 'inject'
     });
     if (!delivery.success) {
       emitInjectFailureEvent(id, delivery.code, delivery.error, {
@@ -1475,9 +1616,11 @@ app.patch('/api/sessions/:id', (req, res) => {
   if (!new_id) return res.status(400).json({ error: 'new_id is required' });
   if (sessions[new_id]) return res.status(409).json({ error: `Session ID '${new_id}' is already in use.` });
 
-  // Move session to new key
+  // Move session to new key (including state machine)
   sessions[new_id] = session;
   delete sessions[id];
+  sessionStateManager.unregister(id);
+  sessionStateManager.register(new_id);
   session.id = new_id;
 
   // Broadcast rename to bus
@@ -1511,12 +1654,16 @@ app.delete('/api/sessions/:id', (req, res) => {
       session.ptyProcess.kill();
     }
     delete sessions[id];
+    sessionStateManager.unregister(id);
+    try { mailbox.purge(id); } catch {}
     console.log(`[KILL] Session ${id} removed`);
     persistSessions();
     res.json({ success: true, status: 'closing' });
   } catch (err) {
     // Even if kill fails, remove from registry
     delete sessions[id];
+    sessionStateManager.unregister(id);
+    try { mailbox.purge(id); } catch {}
     persistSessions();
     console.log(`[KILL] Session ${id} force-removed (process cleanup error: ${err.message})`);
     res.json({ success: true, status: 'force-removed' });
@@ -1851,6 +1998,46 @@ const server = app.listen(PORT, HOST, () => {
   console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${PORT}`);
 });
 
+// --- Mailbox system initialization ---
+const mailbox = new FileMailbox();
+const mailboxNotifier = new UnixSocketNotifier({ coalesceMs: 25 });
+
+// Resolve aterm UDS socket path for a session
+mailboxNotifier.setSocketResolver((sessionId) => {
+  const session = sessions[sessionId];
+  if (!session || session.type !== 'aterm') return null;
+  return (session.delivery && session.delivery.transport === 'unix_socket' && session.delivery.address) || null;
+});
+
+// Delivery engine: dequeue → writeDataToSession → ack/nack
+const mailboxDelivery = new DeliveryEngine(mailbox, {
+  pollMs: 200,
+  sessionResolver: () => Object.keys(sessions),
+  deliverFn: async (sessionId, msg) => {
+    const session = sessions[sessionId];
+    if (!session) return { success: false, error: 'Session not found' };
+    const result = await writeDataToSession(sessionId, session, msg.payload);
+    if (result.success) {
+      session.lastActivityAt = new Date().toISOString();
+    }
+    return result;
+  },
+  onDelivery: (sessionId, msgId, result) => {
+    const session = sessions[sessionId];
+    if (!session) return;
+    if (result.success) {
+      broadcastSessionEvent('mailbox_delivered', sessionId, session, {
+        extra: { msg_id: msgId }
+      });
+    } else {
+      broadcastSessionEvent('mailbox_delivery_failed', sessionId, session, {
+        extra: { msg_id: msgId, error: result.error }
+      });
+    }
+  },
+});
+mailboxDelivery.start();
+
 const IDLE_THRESHOLD_SECONDS = 60;
 setInterval(() => {
   const now = Date.now();
@@ -1912,18 +2099,24 @@ setInterval(() => {
     }
 
     // Periodically verify aterm socket existence — triggers health transition
+    // NOTE: Do NOT nullify delivery address here. The address is preserved so that
+    // if aterm restarts and the socket reappears, health check recovers automatically.
     if (session.type === 'aterm') {
       const atermEndpoint = session.deliveryEndpoint || (session.delivery && session.delivery.address);
       if (atermEndpoint && atermEndpoint.startsWith('/')) {
+        let socketAlive = false;
         try {
-          fs.accessSync(atermEndpoint, fs.constants.F_OK);
+          const stat = fs.statSync(atermEndpoint);
+          socketAlive = stat.isSocket();
         } catch {
-          session.deliveryEndpoint = null;
-          if (session.delivery) session.delivery.address = null;
-          if (!session.lastDisconnectedAt) {
-            session.lastDisconnectedAt = new Date().toISOString();
-          }
+          socketAlive = false;
+        }
+        if (!socketAlive && !session.lastDisconnectedAt) {
+          markSessionDisconnected(session);
           console.log(`[SWEEP] aterm socket gone for ${id}: ${atermEndpoint}`);
+        } else if (socketAlive && session.lastDisconnectedAt) {
+          markSessionConnected(session);
+          console.log(`[SWEEP] aterm socket recovered for ${id}: ${atermEndpoint}`);
         }
       }
     }
@@ -1947,6 +2140,7 @@ setInterval(() => {
         disconnectedSeconds
       });
       delete sessions[id];
+      sessionStateManager.unregister(id);
       console.log(`[CLEANUP] Removed stale session ${id} after ${disconnectedSeconds}s disconnected`);
       persistSessions();
     }
@@ -2066,6 +2260,7 @@ wss.on('connection', (ws, req) => {
           if (type === 'output') {
             activeSession.lastActivityAt = new Date().toISOString();
             appendToOutputRing(activeSession, data);
+            sessionStateManager.feed(sessionId, data);
             activeSession.clients.forEach(client => {
               if (client !== ws && client.readyState === 1) {
                 client.send(JSON.stringify({ type: 'output', data }));
@@ -2210,6 +2405,8 @@ server.on('upgrade', (req, socket, head) => {
 });
 
 function shutdown(code) {
+  mailboxDelivery.stop();
+  mailboxNotifier.cancelAll();
   clearDaemonState(process.pid);
   process.exit(code);
 }