@dmsdc-ai/aigentry-telepty 0.4.3 → 0.4.4

package/cli.js

@@ -23,6 +23,7 @@ const crossMachine = require('./cross-machine');
 const { parseHostSpec, buildDaemonUrl, buildDaemonWsUrl } = require('./host-spec');
 const { FileMailbox } = require('./src/mailbox/index');
 const readyRegistry = require('./src/prompt-symbol-registry');
+const lifecycle = require('./src/lifecycle');
 const args = process.argv.slice(2);
 let pendingTerminalInputError = null;
 let simulatedPromptErrorInjected = false;
@@ -156,6 +157,11 @@ const fetchWithAuth = (url, options = {}) => {
   return fetch(url, { ...options, headers });
 };
 
+function isSubmitForceDefaultEnabled(env = process.env) {
+  const value = (env.TELEPTY_SUBMIT_FORCE_DEFAULT || '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on';
+}
+
 async function getDaemonMeta(host = REMOTE_HOST) {
   try {
     const res = await fetchWithAuth(`${daemonUrl(host)}/api/meta`, {
@@ -206,6 +212,26 @@ function formatSessionHealth(session) {
   return status;
 }
 
+function enrichSessionIdle(session, nowMs = Date.now()) {
+  const idleSeconds = typeof session.idleSeconds === 'number'
+    ? session.idleSeconds
+    : lifecycle.computeIdleSeconds(session.lastActivityAt, nowMs);
+  return {
+    ...session,
+    idleSeconds,
+    idle_seconds: idleSeconds
+  };
+}
+
+function formatSessionStatusWithIdle(session) {
+  const base = formatSessionHealth(session);
+  const idleSeconds = typeof session.idleSeconds === 'number' ? session.idleSeconds : null;
+  if (idleSeconds !== null && idleSeconds > 60) {
+    return `${base} 💤 idle (${lifecycle.formatIdleDuration(idleSeconds)})`;
+  }
+  return base;
+}
+
 function formatApiError(data, fallback = 'Request failed.') {
   if (!data) {
     return fallback;
@@ -914,7 +940,25 @@ async function main() {
 
   if (cmd === 'list') {
     try {
-      const sessions = await discoverSessions({ silent: true });
+      let sessions = await discoverSessions({ silent: true });
+      // Bridge merge: surface supervisor-managed sessions discovered via
+      // filesystem manifest scan. De-dup with daemon entries by session id.
+      // Daemon path remains source-of-truth when both surfaces report the
+      // same session; bridge fills the gap when daemon is down (P2 #430).
+      try {
+        const bridgeSessions = require('./src/bridge/j3-shim').list();
+        const seenIds = new Set(sessions.map((s) => s.id));
+        for (const bs of bridgeSessions) {
+          if (!seenIds.has(bs.id)) {
+            sessions.push(bs);
+            seenIds.add(bs.id);
+          }
+        }
+      } catch {
+        // Best-effort: daemon list still surfaced above.
+      }
+      const nowMs = Date.now();
+      sessions = sessions.map((session) => enrichSessionIdle(session, nowMs));
       if (args.includes('--json')) {
         console.log(JSON.stringify(sessions, null, 2));
         return;
@@ -927,7 +971,7 @@ async function main() {
         console.log(`    Command: ${s.command}`);
         const autoEmoji = s.autoState ? s.autoState.emoji : '';
       const autoLabel = s.autoState ? s.autoState.state : '';
-      console.log(`    Status: ${formatSessionHealth(s)}${autoLabel ? ` ${autoEmoji} ${autoLabel}` : ''}`);
+      console.log(`    Status: ${formatSessionStatusWithIdle(s)}${autoLabel ? ` ${autoEmoji} ${autoLabel}` : ''}`);
         console.log(`    Terminal: ${formatSessionTerminal(s)}`);
         console.log(`    CWD: ${s.cwd}`);
         console.log(`    Clients: ${s.active_clients}`);
@@ -977,6 +1021,24 @@ async function main() {
       allowArgs.splice(idIndex, 2);
     }
 
+    // Extract per-session idle TTL override
+    let idleTtl = null;
+    const idleTtlIndex = allowArgs.indexOf('--idle-ttl');
+    if (idleTtlIndex !== -1) {
+      if (!allowArgs[idleTtlIndex + 1]) {
+        console.error('❌ Usage: telepty allow [--id <session_id>] [--idle-ttl <duration|off>] <command> [args...]');
+        process.exit(1);
+      }
+      idleTtl = allowArgs[idleTtlIndex + 1];
+      try {
+        lifecycle.parseDuration(idleTtl, { fieldName: 'idle_ttl' });
+      } catch (err) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+      }
+      allowArgs.splice(idleTtlIndex, 2);
+    }
+
     // Extract --auto-restart flag
     const autoRestartIndex = allowArgs.indexOf('--auto-restart');
     const autoRestart = autoRestartIndex !== -1;
@@ -1037,7 +1099,9 @@ async function main() {
           cmux_workspace_id: process.env.CMUX_WORKSPACE_ID || null,
           cmux_surface_id: process.env.CMUX_SURFACE_ID || null,
           term_program: terminalProgram,
-          term: terminalType
+          term: terminalType,
+          owner_pid: process.pid,
+          ...(idleTtl !== null ? { idle_ttl: idleTtl } : {})
         })
       });
       const data = await res.json();
@@ -1060,6 +1124,27 @@ async function main() {
     const MAX_CRASHES = 3;
     const DEATH_LOG_PATH = path.join(os.homedir(), '.telepty', 'logs', 'session-deaths.log');
 
+    function updateDaemonProcessMetadata() {
+      const body = {
+        session_id: sessionId,
+        command,
+        cwd: process.cwd(),
+        backend: detectedBackend,
+        cmux_workspace_id: process.env.CMUX_WORKSPACE_ID || null,
+        cmux_surface_id: process.env.CMUX_SURFACE_ID || null,
+        term_program: terminalProgram,
+        term: terminalType,
+        owner_pid: process.pid,
+        ...(child && child.pid ? { pty_pid: child.pid } : {}),
+        ...(idleTtl !== null ? { idle_ttl: idleTtl } : {})
+      };
+      fetchWithAuth(`${DAEMON_URL}/api/sessions/register`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body)
+      }).catch(() => {});
+    }
+
     function logSessionDeath(exitCode, signal, duration) {
       try {
         fs.mkdirSync(path.dirname(DEATH_LOG_PATH), { recursive: true });
@@ -1105,6 +1190,7 @@ async function main() {
         env: sessionEnv
       });
       sessionStartTime = Date.now();
+      updateDaemonProcessMetadata();
       return child;
     }
 
@@ -1239,7 +1325,10 @@ async function main() {
               cmux_workspace_id: process.env.CMUX_WORKSPACE_ID || null,
               cmux_surface_id: process.env.CMUX_SURFACE_ID || null,
               term_program: terminalProgram,
-              term: terminalType
+              term: terminalType,
+              owner_pid: process.pid,
+              ...(child && child.pid ? { pty_pid: child.pid } : {}),
+              ...(idleTtl !== null ? { idle_ttl: idleTtl } : {})
             })
           });
         } catch (e) {
@@ -1644,8 +1733,14 @@ async function main() {
     // caller is confident the target REPL is ready (e.g., orchestrator is
     // visibly idle). See specs/2026-05-02-submit-force-and-retry.md
     const submitForceIndex = args.indexOf('--submit-force');
-    const submitForce = submitForceIndex !== -1;
-    if (submitForce) args.splice(submitForceIndex, 1);
+    const noSubmitForceIndex = args.indexOf('--no-submit-force');
+    const explicitSubmitForce = submitForceIndex !== -1;
+    const explicitNoSubmitForce = noSubmitForceIndex !== -1;
+    for (const index of [submitForceIndex, noSubmitForceIndex].filter((i) => i !== -1).sort((a, b) => b - a)) {
+      args.splice(index, 1);
+    }
+    const submitForceFromEnv = !explicitSubmitForce && !explicitNoSubmitForce && isSubmitForceDefaultEnabled();
+    const submitForce = explicitSubmitForce || submitForceFromEnv;
 
     // Extract --submit-retry N flag (default 1, clamp [0, 3]). On a 504
     // gated-failure with a retry-safe reason (gate timed out and body is
@@ -1737,6 +1832,23 @@ async function main() {
         referencePath = reference.referencePath;
       }
 
+      // Bridge-first attempt for local supervisor-managed sessions (P2 #430).
+      // Gated submit semantics (render-gate, retry, submit-force) stay on
+      // daemon.js — P2 wire does not carry those yet — so we only bridge the
+      // basic inject path. Bridge failure (no manifest, supervisor crashed
+      // mid-call, etc.) falls through to the daemon HTTP path below.
+      if (!useSubmit) {
+        const bridgeShim = require('./src/bridge/j3-shim');
+        if (bridgeShim.findSupervisorManifest(target.id)) {
+          const bridgeRes = await bridgeShim.inject(target.id, `${injectPrompt}\r`, {});
+          if (bridgeRes.success) {
+            const refSuffix = referencePath ? ` (ref: ${referencePath})` : '';
+            console.log(`✅ Context injected successfully into '\x1b[36m${target.id}\x1b[0m' (bridge).${refSuffix}`);
+            return;
+          }
+        }
+      }
+
       const body = buildInjectRequestBody(injectPrompt, {
         fromId,
         replyTo,
@@ -1764,6 +1876,9 @@ async function main() {
       // an Enter that genuinely never landed cannot double-submit.
       // See docs/superpowers/specs/2026-04-26-inject-submit-enter-reliability.md
       if (useSubmit) {
+        if (submitForceFromEnv) {
+          console.error('[telepty inject] submit-force=env-default (TELEPTY_SUBMIT_FORCE_DEFAULT=1)');
+        }
         const submitBody = {
           injected_body: injectPrompt || '',
           retries: 1,
@@ -2208,10 +2323,111 @@ async function main() {
     return;
   }
 
+  if (cmd === 'kill') {
+    const killArgs = args.slice(1);
+    const force = killArgs.includes('--force');
+    const timeoutIndex = killArgs.indexOf('--timeout');
+    let timeout = 5;
+    if (timeoutIndex !== -1) {
+      if (!killArgs[timeoutIndex + 1]) {
+        console.error('❌ Usage: telepty kill <session-id> [--force] [--timeout <sec>]');
+        process.exit(1);
+      }
+      timeout = Number(killArgs[timeoutIndex + 1]);
+      if (!Number.isFinite(timeout) || timeout < 0) {
+        console.error('❌ --timeout must be a non-negative number of seconds.');
+        process.exit(1);
+      }
+      killArgs.splice(timeoutIndex, 2);
+    }
+    const filtered = killArgs.filter((item) => item !== '--force');
+    const sessionRef = filtered[0];
+    if (!sessionRef) { console.error('❌ Usage: telepty kill <session-id> [--force] [--timeout <sec>]'); process.exit(1); }
+
+    try {
+      const target = await resolveSessionTarget(sessionRef);
+      if (!target) { console.error(`❌ Session '${sessionRef}' not found.`); process.exit(1); }
+      const res = await fetchWithAuth(`${daemonUrl(target.host)}/api/sessions/${encodeURIComponent(target.id)}/kill`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ force, timeout, source: 'cli' })
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        console.error(`❌ Error: ${data.error || 'Failed to kill session.'}`);
+        process.exit(1);
+      }
+      console.log(`✅ Session '\x1b[36m${target.id}\x1b[0m' killed${data.kill && data.kill.escalated ? ' (escalated)' : ''}.`);
+    } catch (e) {
+      console.error(`❌ ${e.message || 'Failed to kill session.'}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   if (cmd === 'clean') {
     try {
+      const cleanArgs = args.slice(1);
+      const dryRun = cleanArgs.includes('--dry-run');
+      const idle = cleanArgs.includes('--idle');
+      const olderThanIndex = cleanArgs.indexOf('--older-than');
+      let olderThanMs = null;
+      if (olderThanIndex !== -1) {
+        if (!cleanArgs[olderThanIndex + 1]) {
+          console.error('❌ Usage: telepty clean [--older-than <duration>] [--idle] [--dry-run]');
+          process.exit(1);
+        }
+        try {
+          olderThanMs = lifecycle.parseDuration(cleanArgs[olderThanIndex + 1], { fieldName: '--older-than' });
+        } catch (err) {
+          console.error(`❌ ${err.message}`);
+          process.exit(1);
+        }
+        if (olderThanMs == null) {
+          console.error('❌ --older-than must be a duration like 30m, 1h, or 2d.');
+          process.exit(1);
+        }
+      }
+
       const sessions = await discoverSessions({ silent: true });
       if (sessions.length === 0) { console.log('No sessions found.'); return; }
+      if (olderThanMs !== null) {
+        const targets = lifecycle.selectCleanOlderThanTargets(sessions, {
+          olderThanMs,
+          idle,
+          nowMs: Date.now()
+        });
+        if (targets.length === 0) {
+          console.log(`✅ No ${idle ? 'idle ' : ''}sessions older than ${cleanArgs[olderThanIndex + 1]} found.`);
+          return;
+        }
+        if (dryRun) {
+          targets.forEach((target) => {
+            console.log(`  Would remove: \x1b[36m${target.id}\x1b[0m (${target.reference}, ${Math.floor(target.ageSeconds / 60)}m old)`);
+          });
+          console.log(`✅ Dry run: ${targets.length} session(s) would be removed.`);
+          return;
+        }
+
+        let cleaned = 0;
+        for (const target of targets) {
+          try {
+            const host = target.session.host || '127.0.0.1';
+            const res = await fetchWithAuth(`${daemonUrl(host)}/api/sessions/${encodeURIComponent(target.id)}/kill`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ force: false, timeout: 5, source: 'clean', reason: idle ? 'CLEAN_IDLE_OLDER_THAN' : 'CLEAN_OLDER_THAN' })
+            });
+            if (res.ok) {
+              console.log(`  🗑  Removed session: \x1b[36m${target.id}\x1b[0m (${target.reference})`);
+              cleaned++;
+            }
+          } catch (_) {}
+        }
+        console.log(cleaned > 0 ? `✅ Cleaned ${cleaned} session(s).` : '✅ No sessions cleaned.');
+        return;
+      }
+
       let cleaned = 0;
       for (const s of sessions) {
         if (s.healthStatus === 'STALE' || s.healthStatus === 'DISCONNECTED') {
@@ -3171,10 +3387,12 @@ Discuss the following topic from your project's perspective. Engage with other s
 \x1b[1mSession Management:\x1b[0m
   telepty daemon                                 Start the background daemon (port 3848)
   telepty spawn --id <id> <command> [args...]    Spawn a new background session
-  telepty allow [--id <id>] [--auto-restart] <command> [args...]  Wrap a CLI for remote control
+  telepty allow [--id <id>] [--idle-ttl 1h|off] [--auto-restart] <command> [args...]  Wrap a CLI for remote control
   telepty list [--json]                          List sessions (local + Tailnet)
   telepty attach [id[@host]]                     Attach interactively (picker if no ID)
   telepty rename <old_id[@host]> <new_id>        Rename a session
+  telepty kill <id[@host]> [--force] [--timeout N]  Gracefully terminate a session
+  telepty clean [--older-than 7d] [--idle] [--dry-run]  Clean ghost or old sessions
   telepty session info <id[@host]> [--json]      Show session metadata
 
 \x1b[1mInject & Communicate:\x1b[0m

package/daemon.js

@@ -16,6 +16,8 @@ const { SessionStateManager, STATE_DISPLAY, stripAnsi: stripAnsiState } = requir
 const { classifyReportPrompt, buildAutoSummary } = require('./src/report-enforcement');
 const submitGate = require('./src/submit-gate');
 const readyRegistry = require('./src/prompt-symbol-registry');
+const lifecycle = require('./src/lifecycle');
+const { loadTeleptyConfig } = require('./src/config-file');
 
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
@@ -27,6 +29,7 @@ const SESSION_STALE_SECONDS = Math.max(1, Number(process.env.TELEPTY_SESSION_STA
 const SESSION_CLEANUP_SECONDS = Math.max(SESSION_STALE_SECONDS, Number(process.env.TELEPTY_SESSION_CLEANUP_SECONDS || 300));
 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));
+const IDLE_REAPER_POLL_MS = Math.max(100, Number(process.env.TELEPTY_IDLE_REAPER_POLL_MS || 60000));
 const BOOTSTRAP_READY_TIMEOUT_MS = Math.max(500, Number(process.env.TELEPTY_BOOTSTRAP_READY_TIMEOUT_MS || 30000));
 const WRAPPED_SUBMIT_DELAY_MS = 500;
 
@@ -139,7 +142,11 @@ function persistSessions() {
         lastConnectedAt: s.lastConnectedAt || null,
         lastDisconnectedAt: s.lastDisconnectedAt || null,
         lastStateReportAt: s.lastStateReportAt || null,
-        stateReport: s.stateReport || null
+        stateReport: s.stateReport || null,
+        idleTtl: s.idleTtl || null,
+        idleTtlMs: s.idleTtlMs == null ? null : s.idleTtlMs,
+        ownerPid: s.ownerPid || null,
+        ptyPid: s.ptyPid || null
       };
     }
     fs.mkdirSync(require('path').dirname(SESSION_PERSIST_PATH), { recursive: true });
@@ -266,6 +273,13 @@ const AUTO_REPORT_IDLE_SECONDS = Number(process.env.TELEPTY_AUTO_REPORT_IDLE_SEC
 const sessions = {};
 const handoffs = {};
 const threads = {};
+let teleptyConfig;
+try {
+  teleptyConfig = loadTeleptyConfig();
+} catch (err) {
+  console.error(`[CONFIG] Failed to load telepty config: ${err.message}`);
+  process.exit(1);
+}
 
 function broadcastBusEvent(event) {
   const serialized = JSON.stringify(event);
@@ -357,6 +371,53 @@ function getSessionHealthReason(session, healthStatus) {
   return session.ptyProcess && !session.ptyProcess.killed ? 'PTY_RUNNING' : 'PTY_EXITED';
 }
 
+function parseOptionalIdleTtl(body) {
+  if (!body || !Object.prototype.hasOwnProperty.call(body, 'idle_ttl')) {
+    return { present: false };
+  }
+  try {
+    return {
+      present: true,
+      raw: body.idle_ttl == null ? 'off' : String(body.idle_ttl),
+      ms: lifecycle.parseDuration(body.idle_ttl == null ? 'off' : body.idle_ttl, { fieldName: 'idle_ttl' })
+    };
+  } catch (err) {
+    return { present: true, error: err.message };
+  }
+}
+
+function applyProcessMetadata(session, body) {
+  if (!session || !body) return;
+  const ownerPid = Number(body.owner_pid);
+  const ptyPid = Number(body.pty_pid);
+  if (Number.isInteger(ownerPid) && ownerPid > 0) {
+    session.ownerPid = ownerPid;
+  }
+  if (Number.isInteger(ptyPid) && ptyPid > 0) {
+    session.ptyPid = ptyPid;
+  }
+}
+
+function applyIdleTtlMetadata(session, parsedIdleTtl) {
+  if (!session || !parsedIdleTtl || !parsedIdleTtl.present || parsedIdleTtl.error) return;
+  session.idleTtl = parsedIdleTtl.raw;
+  session.idleTtlMs = parsedIdleTtl.ms;
+}
+
+function applyTimestampMetadata(session, body) {
+  if (!session || !body) return;
+  for (const [field, prop] of [
+    ['created_at', 'createdAt'],
+    ['last_activity_at', 'lastActivityAt']
+  ]) {
+    if (!Object.prototype.hasOwnProperty.call(body, field)) continue;
+    const value = body[field] == null ? null : String(body[field]);
+    if (value && Number.isFinite(new Date(value).getTime())) {
+      session[prop] = value;
+    }
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1104,6 +1165,11 @@ function serializeSession(id, session, options = {}) {
     healthReason,
     disconnectedSeconds: disconnectedMs === null ? null : Math.floor(disconnectedMs / 1000),
     lastStateReportAt: session.lastStateReportAt || null,
+    idleTtl: session.idleTtl || null,
+    idleTtlMs: session.idleTtlMs == null ? null : session.idleTtlMs,
+    effectiveIdleTtlMs: lifecycle.effectiveIdleTtlMs(session, teleptyConfig),
+    ownerPid: session.ownerPid || null,
+    ptyPid: session.ptyPid || (session.ptyProcess && session.ptyProcess.pid) || null,
     transport,
     semantic,
     autoState: autoState ? {
@@ -1123,6 +1189,53 @@ function serializeSession(id, session, options = {}) {
   };
 }
 
+async function teardownSessionById(id, options = {}) {
+  const session = sessions[id];
+  if (!session) {
+    return { success: false, httpStatus: 404, error: 'Session not found' };
+  }
+
+  const timeoutMs = Math.max(0, Number(options.timeoutMs ?? 5000));
+  const force = options.force === true;
+  const reason = options.reason || (force ? 'manual_force' : 'manual');
+  session.isClosing = true;
+
+  const kill = await lifecycle.killSessionProcess(session, { timeoutMs, force });
+  emitSessionLifecycleEvent('session_closed', id, session, {
+    reason,
+    force,
+    pid: kill.pid,
+    signal: kill.signal || null,
+    escalated: kill.escalated === true,
+    source: options.source || 'daemon'
+  });
+
+  if (session.clients) {
+    session.clients.forEach(ws => {
+      try { ws.close(1000, 'Session destroyed'); } catch {}
+    });
+  }
+  if (session.ownerWs) {
+    try { session.ownerWs.close(1000, 'Session destroyed'); } catch {}
+  }
+
+  delete sessions[id];
+  sessionStateManager.unregister(id);
+  try { mailbox.purge(id); } catch {}
+  lifecycle.cleanupSessionArtifacts(id);
+  persistSessions();
+
+  return {
+    success: true,
+    session_id: id,
+    status: 'closed',
+    reason,
+    force,
+    timeout_ms: timeoutMs,
+    kill
+  };
+}
+
 // Detect terminal environment at daemon startup
 const DETECTED_TERMINAL = terminalBackend.detectTerminal();
 console.log(`[DAEMON] Terminal backend: ${DETECTED_TERMINAL}`);
@@ -1145,6 +1258,10 @@ for (const [id, meta] of Object.entries(_persisted)) {
       lastDisconnectedAt: meta.lastDisconnectedAt || meta.lastActivityAt || new Date().toISOString(),
       lastStateReportAt: meta.lastStateReportAt || null,
       stateReport: meta.stateReport || null,
+      idleTtl: meta.idleTtl || null,
+      idleTtlMs: meta.idleTtlMs == null ? null : meta.idleTtlMs,
+      ownerPid: meta.ownerPid || null,
+      ptyPid: meta.ptyPid || null,
       clients: new Set(), isClosing: false, outputRing: [], ready: true,     };
     initializeBootstrapState(sessions[id]);
     console.log(`[PERSIST] Restored session ${id} (awaiting reconnect)`);
@@ -1242,6 +1359,7 @@ app.post('/api/sessions/spawn', (req, res) => {
       id: session_id,
       type: 'spawned',
       ptyProcess,
+      ptyPid: ptyProcess.pid || null,
       command,
       cwd,
       createdAt: new Date().toISOString(),
@@ -1311,6 +1429,10 @@ app.post('/api/sessions/spawn', (req, res) => {
 app.post('/api/sessions/register', (req, res) => {
   const { session_id, command, cwd = process.cwd(), backend, cmux_workspace_id, cmux_surface_id, term_program, term } = req.body;
   if (!session_id) return res.status(400).json({ error: 'session_id is required' });
+  const parsedIdleTtl = parseOptionalIdleTtl(req.body);
+  if (parsedIdleTtl.error) {
+    return res.status(400).json({ error: parsedIdleTtl.error, code: 'INVALID_IDLE_TTL' });
+  }
   // Idempotent: allow re-registration (update command/cwd, keep clients)
   if (sessions[session_id]) {
     const existing = sessions[session_id];
@@ -1333,6 +1455,9 @@ app.post('/api/sessions/register', (req, res) => {
       existing.ready = true;
       markSessionConnected(existing);
     }
+    applyProcessMetadata(existing, req.body);
+    applyIdleTtlMetadata(existing, parsedIdleTtl);
+    applyTimestampMetadata(existing, req.body);
     initializeBootstrapState(existing);
     console.log(`[REGISTER] Re-registered session ${session_id} (type: ${existing.type}, updated metadata)`);
     return res.status(200).json({ session_id, type: existing.type, command: existing.command, cwd: existing.cwd, reregistered: true });
@@ -1360,12 +1485,17 @@ app.post('/api/sessions/register', (req, res) => {
     lastDisconnectedAt: delivery_type === 'aterm' ? null : new Date().toISOString(),
     lastStateReportAt: null,
     stateReport: null,
+    idleTtl: parsedIdleTtl.present ? parsedIdleTtl.raw : null,
+    idleTtlMs: parsedIdleTtl.present ? parsedIdleTtl.ms : null,
+    ownerPid: Number.isInteger(Number(req.body.owner_pid)) && Number(req.body.owner_pid) > 0 ? Number(req.body.owner_pid) : null,
+    ptyPid: Number.isInteger(Number(req.body.pty_pid)) && Number(req.body.pty_pid) > 0 ? Number(req.body.pty_pid) : null,
     clients: new Set(),
     isClosing: false,
     outputRing: [],
     ready: true,  // unknown commands remain injectable once registered (#150)
   };
   initializeBootstrapState(sessionRecord);
+  applyTimestampMetadata(sessionRecord, req.body);
   // Check for existing session with same base alias and emit replaced event
   const baseAlias = session_id.replace(/-\d+$/, '');
   const replaced = Object.keys(sessions).find(id => {
@@ -2364,6 +2494,35 @@ app.patch('/api/sessions/:id', (req, res) => {
   res.json({ success: true, old_id: id, new_id });
 });
 
+app.post('/api/sessions/:id/kill', async (req, res) => {
+  const requestedId = req.params.id;
+  const resolvedId = resolveSessionAlias(requestedId);
+  if (!resolvedId) return res.status(404).json({ error: 'Session not found', requested: requestedId });
+
+  try {
+    const timeoutSeconds = req.body && req.body.timeout != null
+      ? Number(req.body.timeout)
+      : (req.body && req.body.timeout_sec != null ? Number(req.body.timeout_sec) : 5);
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) {
+      return res.status(400).json({ error: 'timeout must be a non-negative number of seconds', code: 'INVALID_TIMEOUT' });
+    }
+
+    const result = await teardownSessionById(resolvedId, {
+      force: req.body && req.body.force === true,
+      timeoutMs: Math.floor(timeoutSeconds * 1000),
+      reason: req.body && req.body.reason ? String(req.body.reason) : 'manual',
+      source: req.body && req.body.source ? String(req.body.source) : 'api'
+    });
+    if (!result.success) {
+      return res.status(result.httpStatus || 500).json({ error: result.error || 'Failed to kill session' });
+    }
+    console.log(`[KILL] Session ${resolvedId} closed (reason=${result.reason}, force=${result.force}, pid=${result.kill.pid || 'none'})`);
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message || 'Failed to kill session' });
+  }
+});
+
 app.delete('/api/sessions/:id', (req, res) => {
   const requestedId = req.params.id;
   const resolvedId = resolveSessionAlias(requestedId);
@@ -2381,6 +2540,7 @@ app.delete('/api/sessions/:id', (req, res) => {
     delete sessions[id];
     sessionStateManager.unregister(id);
     try { mailbox.purge(id); } catch {}
+    lifecycle.cleanupSessionArtifacts(id);
     console.log(`[KILL] Session ${id} removed`);
     persistSessions();
     res.json({ success: true, status: 'closing' });
@@ -2389,6 +2549,7 @@ app.delete('/api/sessions/:id', (req, res) => {
     delete sessions[id];
     sessionStateManager.unregister(id);
     try { mailbox.purge(id); } catch {}
+    lifecycle.cleanupSessionArtifacts(id);
     persistSessions();
     console.log(`[KILL] Session ${id} force-removed (process cleanup error: ${err.message})`);
     res.json({ success: true, status: 'force-removed' });
@@ -2769,6 +2930,43 @@ if (staleBroken > 0) {
 mailboxDelivery.start();
 
 const IDLE_THRESHOLD_SECONDS = 60;
+async function runIdleTtlSweep(nowMs = Date.now()) {
+  const victims = lifecycle.selectIdleTtlVictims(sessions, teleptyConfig, { nowMs });
+  for (const victim of victims) {
+    const session = sessions[victim.id];
+    if (!session || session._idleTtlKilling) continue;
+    session._idleTtlKilling = true;
+    broadcastSessionEvent('tracing', victim.id, session, {
+      nowMs,
+      extra: {
+        action: 'idle_ttl_auto_kill',
+        reason: 'IDLE_TTL',
+        idle_duration: victim.idleSeconds,
+        idle_duration_seconds: victim.idleSeconds,
+        idle_ttl_ms: victim.ttlMs
+      }
+    });
+    try {
+      await teardownSessionById(victim.id, {
+        force: false,
+        timeoutMs: 5000,
+        reason: 'IDLE_TTL',
+        source: 'idle_reaper'
+      });
+      console.log(`[REAPER] Auto-killed ${victim.id} after ${victim.idleSeconds}s idle (ttl=${victim.ttlMs}ms)`);
+    } catch (err) {
+      session._idleTtlKilling = false;
+      console.error(`[REAPER] Failed to auto-kill ${victim.id}: ${err.message}`);
+    }
+  }
+}
+
+setInterval(() => {
+  runIdleTtlSweep().catch((err) => {
+    console.error(`[REAPER] Idle TTL sweep failed: ${err.message}`);
+  });
+}, IDLE_REAPER_POLL_MS);
+
 setInterval(() => {
   const now = Date.now();
   for (const [id, session] of Object.entries(sessions)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -33,9 +33,9 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js && git diff --exit-code tests/snippet-protocol/v1/",
-    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js",
-    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js",
+    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js && git diff --exit-code tests/snippet-protocol/v1/",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },
   "keywords": [