@jsonstudio/rcc 0.89.2239 → 0.90.89

package/dist/cli/commands/launcher-kernel.js

@@ -4,13 +4,105 @@ import { spawnSync } from 'node:child_process';
 import { createServer } from 'node:http';
 import crypto from 'node:crypto';
 import { LOCAL_HOSTS } from '../../constants/index.js';
-import { encodeClockClientApiKey } from '../../utils/clock-client-token.js';
+import { encodeSessionClientApiKey, extractSessionClientDaemonIdFromApiKey, extractSessionClientScopeIdFromApiKey } from '../../utils/session-client-token.js';
+import { isSessionScopeTraceEnabled, isSessionScopeTraceVerbose } from '../../utils/session-scope-trace.js';
 import { logProcessLifecycle } from '../../utils/process-lifecycle-logger.js';
-import { resolveBinary, parseServerUrl, resolveTmuxSelfHealPolicy, readConfigApiKey, normalizeConnectHost, toIntegerPort, tryReadConfigHostPort, resolveIntFromEnv } from './launcher/utils.js';
+import { resolveBinary, parseServerUrl, resolveBoolFromEnv, resolveTmuxSelfHealPolicy, readConfigApiKey, normalizeConnectHost, toIntegerPort, tryReadConfigHostPort, resolveIntFromEnv } from './launcher/utils.js';
+import { resolveRouteCodexConfigPath } from '../../config/config-paths.js';
+function shouldStopManagedTmuxOnShutdown(signal, env) {
+    if (signal === 'SIGINT') {
+        return true;
+    }
+    if (signal !== 'SIGTERM') {
+        return true;
+    }
+    return resolveBoolFromEnv(env.ROUTECODEX_LAUNCHER_STOP_MANAGED_TMUX_ON_SIGTERM
+        ?? env.RCC_LAUNCHER_STOP_MANAGED_TMUX_ON_SIGTERM, true);
+}
+function shouldStopManagedTmuxOnToolExit(env) {
+    return resolveBoolFromEnv(env.ROUTECODEX_LAUNCHER_STOP_MANAGED_TMUX_ON_TOOL_EXIT
+        ?? env.RCC_LAUNCHER_STOP_MANAGED_TMUX_ON_TOOL_EXIT, true);
+}
+function shouldLogClientExitSummary(commandName) {
+    const normalized = String(commandName || '').trim().toLowerCase();
+    return normalized === 'codex' || normalized === 'claude' || normalized === 'routecodex';
+}
+function readProcessPpidAndCommand(pid) {
+    if (process.platform === 'win32') {
+        return { ppid: null, command: '' };
+    }
+    try {
+        const out = spawnSync('ps', ['-p', String(pid), '-o', 'ppid=,command='], { encoding: 'utf8' });
+        if (out.error || Number(out.status ?? 0) !== 0) {
+            return { ppid: null, command: '' };
+        }
+        const line = String(out.stdout || '')
+            .split(/\r?\n/)
+            .map((item) => item.trim())
+            .find(Boolean);
+        if (!line) {
+            return { ppid: null, command: '' };
+        }
+        const match = line.match(/^(\d+)\s+(.+)$/);
+        if (!match) {
+            return { ppid: null, command: line };
+        }
+        const ppid = Number.parseInt(match[1], 10);
+        return {
+            ppid: Number.isFinite(ppid) && ppid > 0 ? ppid : null,
+            command: match[2] || ''
+        };
+    }
+    catch {
+        return { ppid: null, command: '' };
+    }
+}
+function commandLikelyMatchesHint(command, commandHint) {
+    const normalizedCommand = String(command || '').toLowerCase();
+    const normalizedHint = String(commandHint || '').toLowerCase().trim();
+    if (!normalizedHint) {
+        return true;
+    }
+    const hintBase = path.basename(normalizedHint);
+    if (hintBase && normalizedCommand.includes(hintBase)) {
+        return true;
+    }
+    const tokens = normalizedHint
+        .split(/[\\/\s]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3);
+    return tokens.some((token) => normalizedCommand.includes(token));
+}
+function canSignalOwnedToolProcess(args) {
+    const strictGuard = resolveBoolFromEnv(args.env.ROUTECODEX_LAUNCHER_STRICT_SIGNAL_GUARD ?? args.env.RCC_LAUNCHER_STRICT_SIGNAL_GUARD, true);
+    if (!strictGuard) {
+        return { ok: true, reason: 'strict_guard_disabled' };
+    }
+    if (!args.pid || !Number.isFinite(args.pid) || args.pid <= 1) {
+        return { ok: false, reason: 'invalid_pid' };
+    }
+    if (process.platform === 'win32') {
+        return { ok: true, reason: 'unsupported_platform' };
+    }
+    const snapshot = readProcessPpidAndCommand(args.pid);
+    if (!snapshot.ppid) {
+        return { ok: false, reason: 'ppid_unavailable' };
+    }
+    if (snapshot.ppid !== args.expectedParentPid) {
+        return { ok: false, reason: 'ppid_mismatch' };
+    }
+    if (!commandLikelyMatchesHint(snapshot.command, args.commandHint)) {
+        return { ok: false, reason: 'command_mismatch' };
+    }
+    return { ok: true, reason: 'owned_child' };
+}
 function resolveServerConnection(ctx, fsImpl, pathImpl, options) {
     let configPath = typeof options.config === 'string' && options.config.trim() ? options.config.trim() : '';
     if (!configPath) {
-        configPath = pathImpl.join(ctx.homedir(), '.routecodex', 'config.json');
+        const resolved = resolveRouteCodexConfigPath();
+        configPath = resolved && resolved.trim()
+            ? resolved
+            : pathImpl.join(ctx.homedir(), '.routecodex', 'config.json');
     }
     let actualProtocol = 'http';
     let actualPort = toIntegerPort(options.port);
@@ -48,10 +140,9 @@ function resolveServerConnection(ctx, fsImpl, pathImpl, options) {
         throw new Error('Invalid or missing port configuration for RouteCodex server');
     }
     const configuredApiKey = (typeof options.apikey === 'string' && options.apikey.trim() ? options.apikey.trim() : null) ??
-        (typeof ctx.env.ROUTECODEX_APIKEY === 'string' && ctx.env.ROUTECODEX_APIKEY.trim()
-            ? ctx.env.ROUTECODEX_APIKEY.trim()
+        (typeof ctx.env.ROUTECODEX_HTTP_APIKEY === 'string' && ctx.env.ROUTECODEX_HTTP_APIKEY.trim()
+            ? ctx.env.ROUTECODEX_HTTP_APIKEY.trim()
             : null) ??
-        (typeof ctx.env.RCC_APIKEY === 'string' && ctx.env.RCC_APIKEY.trim() ? ctx.env.RCC_APIKEY.trim() : null) ??
         readConfigApiKey(fsImpl, configPath);
     const connectHost = normalizeConnectHost(actualHost);
     const portPart = actualPort ? `:${actualPort}` : '';
@@ -69,43 +160,82 @@ function resolveServerConnection(ctx, fsImpl, pathImpl, options) {
     };
 }
 async function checkServerReady(ctx, serverUrl, apiKey, timeoutMs = 2500) {
-    try {
-        const headers = apiKey ? { 'x-api-key': apiKey } : undefined;
-        const probe = async (pathSuffix) => {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const headers = apiKey ? { 'x-api-key': apiKey } : undefined;
+    const probeTargets = resolveServerProbeTargets(serverUrl);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        for (const target of probeTargets) {
             try {
-                const response = await ctx.fetch(`${serverUrl}${pathSuffix}`, {
-                    signal: controller.signal,
-                    method: 'GET',
-                    headers
-                }).catch(() => null);
-                if (!response || !response.ok) {
-                    return { ok: false, body: null };
+                const healthProbe = await probeServerState(ctx, `${target}/health`, headers, timeoutMs);
+                if (healthProbe.ok) {
+                    const status = typeof healthProbe.body?.status === 'string' ? healthProbe.body.status.toLowerCase() : '';
+                    if (status === 'ok' ||
+                        status === 'ready' ||
+                        healthProbe.body?.ready === true ||
+                        healthProbe.body?.pipelineReady === true ||
+                        healthProbe.body === null) {
+                        return true;
+                    }
+                }
+                const readyProbe = await probeServerState(ctx, `${target}/ready`, headers, timeoutMs);
+                if (readyProbe.ok) {
+                    const status = typeof readyProbe.body?.status === 'string' ? readyProbe.body.status.toLowerCase() : '';
+                    if (status === 'ready' || readyProbe.body?.ready === true || readyProbe.body === null) {
+                        return true;
+                    }
                 }
-                const body = await response.json().catch(() => null);
-                return { ok: true, body };
-            }
-            finally {
-                clearTimeout(timeoutId);
             }
-        };
-        const readyProbe = await probe('/ready');
-        if (readyProbe.ok) {
-            const status = typeof readyProbe.body?.status === 'string' ? readyProbe.body.status : '';
-            if (status.toLowerCase() === 'ready' || readyProbe.body?.ready === true) {
-                return true;
+            catch {
+                // try next target
             }
         }
-        const healthProbe = await probe('/health');
-        if (!healthProbe.ok) {
-            return false;
+        if (attempt < 1) {
+            await new Promise((resolve) => setTimeout(resolve, 150));
+        }
+    }
+    return false;
+}
+function resolveServerProbeTargets(serverUrl) {
+    const out = [];
+    const seen = new Set();
+    const pushTarget = (value) => {
+        const normalized = value.trim().replace(/\/+$/, '');
+        if (!normalized || seen.has(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        out.push(normalized);
+    };
+    pushTarget(serverUrl);
+    try {
+        const parsed = new URL(serverUrl);
+        if (parsed.hostname === '0.0.0.0' || parsed.hostname === '::' || parsed.hostname === '::1' || parsed.hostname === 'localhost') {
+            const loopback = new URL(serverUrl);
+            loopback.hostname = '127.0.0.1';
+            pushTarget(loopback.toString());
         }
-        const status = typeof healthProbe.body?.status === 'string' ? healthProbe.body.status.toLowerCase() : '';
-        return status === 'ok' || status === 'ready' || healthProbe.body?.ready === true || healthProbe.body?.pipelineReady === true;
     }
     catch {
-        return false;
+        // ignore invalid URL parse; keep original
+    }
+    return out;
+}
+async function probeServerState(ctx, url, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await ctx.fetch(url, {
+            signal: controller.signal,
+            method: 'GET',
+            headers
+        }).catch(() => null);
+        if (!response || !response.ok) {
+            return { ok: false, body: null };
+        }
+        const body = await response.json().catch(() => null);
+        return { ok: true, body };
+    }
+    finally {
+        clearTimeout(timeoutId);
     }
 }
 function rotateLogFile(fsImpl, filePath, maxBytes = 8 * 1024 * 1024, maxBackups = 3) {
@@ -154,10 +284,13 @@ function ensureServerLogPath(ctx, fsImpl, pathImpl, port) {
     rotateLogFile(fsImpl, logPath);
     return logPath;
 }
-async function ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, resolved) {
+async function ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, resolved, allowAutoStartServer) {
     const alreadyReady = await checkServerReady(ctx, resolved.serverUrl, resolved.configuredApiKey);
     if (alreadyReady) {
-        return { started: false };
+        return { started: false, ready: true };
+    }
+    if (!allowAutoStartServer) {
+        return { started: false, ready: false };
     }
     const hasExplicitUrl = typeof options.url === 'string' && options.url.trim().length > 0;
     if (hasExplicitUrl) {
@@ -166,12 +299,24 @@ async function ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, resolv
     spinner.info('RouteCodex server is not running, starting it in background...');
     const logPath = ensureServerLogPath(ctx, fsImpl, pathImpl, resolved.port);
     const logFd = fsImpl.openSync(logPath, 'a');
+    // Launcher auto-started server follows launcher lifecycle by default.
+    // This is intentionally different from `routecodex start`, which is persistent by default.
+    const bindServerToParent = resolveBoolFromEnv(ctx.env.ROUTECODEX_LAUNCHER_SERVER_PARENT_GUARD
+        ?? ctx.env.RCC_LAUNCHER_SERVER_PARENT_GUARD
+        ?? ctx.env.ROUTECODEX_SERVER_PARENT_GUARD
+        ?? ctx.env.RCC_SERVER_PARENT_GUARD, true);
     const env = {
         ...ctx.env,
         ROUTECODEX_CONFIG: resolved.configPath,
         ROUTECODEX_CONFIG_PATH: resolved.configPath,
         ROUTECODEX_PORT: String(resolved.port),
-        RCC_PORT: String(resolved.port)
+        RCC_PORT: String(resolved.port),
+        ...(bindServerToParent
+            ? {
+                ROUTECODEX_EXPECT_PARENT_PID: String(process.pid),
+                RCC_EXPECT_PARENT_PID: String(process.pid)
+            }
+            : {})
     };
     logProcessLifecycle({
         event: 'detached_spawn',
@@ -264,7 +409,7 @@ async function ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, resolv
         await ctx.sleep(1000);
         const ready = await checkServerReady(ctx, resolved.serverUrl, resolved.configuredApiKey, 1500);
         if (ready) {
-            return { started: true, logPath };
+            return { started: true, ready: true, logPath };
         }
     }
     logProcessLifecycle({
@@ -326,6 +471,18 @@ function resolveCurrentTmuxTarget(env, spawnSyncImpl = spawnSync) {
         return null;
     }
 }
+function inferTmuxSessionIdFromTarget(tmuxTarget) {
+    const normalized = String(tmuxTarget || '').trim();
+    if (!normalized) {
+        return null;
+    }
+    const index = normalized.indexOf(':');
+    if (index <= 0) {
+        return null;
+    }
+    const sessionName = normalized.slice(0, index).trim();
+    return sessionName || null;
+}
 function isReusableTmuxPaneTarget(spawnSyncImpl, tmuxTarget, cwd) {
     const normalizedTarget = String(tmuxTarget || '').trim();
     if (!normalizedTarget) {
@@ -448,129 +605,104 @@ function normalizePathForComparison(candidate) {
         return raw;
     }
 }
-function findReusableManagedTmuxSession(spawnSyncImpl, cwd, commandName) {
-    const expectedCwd = normalizePathForComparison(cwd);
-    const expectedSessionPrefix = `rcc_${normalizeSessionToken(commandName)}_`;
+function formatHmms(value) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(value.getHours())}${pad(value.getMinutes())}${pad(value.getSeconds())}`;
+}
+function tmuxSessionExists(spawnSyncImpl, sessionName) {
     try {
-        const listResult = spawnSyncImpl('tmux', ['list-sessions', '-F', '#S	#{session_attached}'], { encoding: 'utf8' });
-        if (listResult.status !== 0) {
-            return null;
-        }
-        const lines = String(listResult.stdout || '')
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter(Boolean);
-        for (const line of lines) {
-            const [sessionName, attachedFlag] = line.split('	');
-            const normalizedName = String(sessionName || '').trim();
-            if (!normalizedName.startsWith(expectedSessionPrefix)) {
-                continue;
-            }
-            if (String(attachedFlag || '').trim() === '1') {
-                continue;
-            }
-            const panesResult = spawnSyncImpl('tmux', [
-                'list-panes',
-                '-t',
-                normalizedName,
-                '-F',
-                '#{session_name}:#{window_index}.#{pane_index}	#{pane_current_command}	#{pane_current_path}'
-            ], { encoding: 'utf8' });
-            if (panesResult.status !== 0) {
-                continue;
-            }
-            const panes = String(panesResult.stdout || '')
-                .split(/\r?\n/)
-                .map((paneLine) => paneLine.trim())
-                .filter(Boolean);
-            for (const pane of panes) {
-                const [target, command, panePath] = pane.split('	');
-                const tmuxTarget = String(target || '').trim();
-                const currentCommand = String(command || '').trim().toLowerCase();
-                const normalizedPanePath = normalizePathForComparison(String(panePath || '').trim());
-                if (!tmuxTarget) {
-                    continue;
-                }
-                if (!isReusableIdlePaneCommand(currentCommand)) {
-                    continue;
-                }
-                if (!normalizedPanePath || normalizedPanePath !== expectedCwd) {
-                    continue;
-                }
-                return { sessionName: normalizedName, tmuxTarget };
-            }
-        }
-        return null;
+        const result = spawnSyncImpl('tmux', ['has-session', '-t', sessionName], { encoding: 'utf8' });
+        return result.status === 0;
     }
     catch {
-        return null;
+        return false;
     }
 }
-function createManagedTmuxSession(args) {
-    const { spawnSyncImpl, cwd, commandName } = args;
-    const reusable = findReusableManagedTmuxSession(spawnSyncImpl, cwd, commandName);
-    if (reusable) {
-        return {
-            sessionName: reusable.sessionName,
-            tmuxTarget: reusable.tmuxTarget,
-            reused: true,
-            stop: () => {
-                try {
-                    spawnSyncImpl('tmux', ['kill-session', '-t', reusable.sessionName], { encoding: 'utf8' });
-                }
-                catch {
-                    // ignore
-                }
-            }
-        };
+function buildManagedTmuxSessionName(nowMs, attempt) {
+    const stamp = formatHmms(new Date(nowMs + attempt * 1000));
+    return `rcc-tmux-${stamp}`;
+}
+function requestManagedTmuxSessionExit(spawnSyncImpl, sessionName) {
+    const target = String(sessionName || '').trim();
+    if (!target) {
+        return;
     }
-    const sessionName = (() => {
-        const token = normalizeSessionToken(commandName);
-        return `rcc_${token}_${Date.now()}_${Math.random().toString(16).slice(2, 8)}`;
-    })();
     try {
-        const result = spawnSyncImpl('tmux', ['new-session', '-d', '-s', sessionName, '-c', cwd], { encoding: 'utf8' });
-        if (result.status !== 0) {
-            return null;
-        }
+        spawnSyncImpl('tmux', ['send-keys', '-t', target, '-X', 'cancel'], { encoding: 'utf8' });
     }
     catch {
-        return null;
+        // ignore
     }
-    const tmuxTarget = `${sessionName}:0.0`;
-    return {
-        sessionName,
-        tmuxTarget,
-        reused: false,
-        stop: () => {
-            try {
-                spawnSyncImpl('tmux', ['kill-session', '-t', sessionName], { encoding: 'utf8' });
-            }
-            catch {
-                // ignore
+    try {
+        spawnSyncImpl('tmux', ['send-keys', '-t', target, 'C-c'], { encoding: 'utf8' });
+    }
+    catch {
+        // ignore
+    }
+    try {
+        spawnSyncImpl('tmux', ['send-keys', '-t', target, '-l', '--', 'exit'], { encoding: 'utf8' });
+    }
+    catch {
+        // ignore
+    }
+    try {
+        sendTmuxSubmitKey(spawnSyncImpl, target);
+    }
+    catch {
+        // ignore
+    }
+}
+function createManagedTmuxSession(args) {
+    const { spawnSyncImpl, cwd } = args;
+    const baseNow = Date.now();
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        const sessionName = buildManagedTmuxSessionName(baseNow, attempt);
+        if (tmuxSessionExists(spawnSyncImpl, sessionName)) {
+            continue;
+        }
+        try {
+            const result = spawnSyncImpl('tmux', ['new-session', '-d', '-s', sessionName, '-c', cwd], { encoding: 'utf8' });
+            if (result.status !== 0) {
+                continue;
             }
         }
-    };
+        catch {
+            continue;
+        }
+        const tmuxTarget = `${sessionName}:0.0`;
+        return {
+            sessionName,
+            tmuxTarget,
+            reused: false,
+            stop: () => {
+                requestManagedTmuxSessionExit(spawnSyncImpl, sessionName);
+            }
+        };
+    }
+    return null;
 }
 function launchCommandInTmuxPane(args) {
     const { spawnSyncImpl, tmuxTarget, cwd, command, commandName, commandArgs, envOverrides, selfHealPolicy } = args;
+    const tmuxSessionName = (() => {
+        const idx = String(tmuxTarget || '').indexOf(':');
+        const name = idx >= 0 ? String(tmuxTarget).slice(0, idx) : String(tmuxTarget || '');
+        return name.trim();
+    })();
     const envTokens = [
         ...envOverrides.unset.flatMap((key) => ['-u', key]),
         ...envOverrides.set.map(([key, value]) => `${key}=${value}`)
     ];
     const baseCommand = buildShellCommand(['env', ...envTokens, command, ...commandArgs]);
-    // Keep the managed tmux session alive when the client process exits.
-    // Session cleanup is handled by managed heartbeat/reaper logic, not by inline shell self-kill.
-    const shellCommand = (() => {
+    const commandBody = (() => {
         if (!selfHealPolicy.enabled || selfHealPolicy.maxRetries <= 0) {
-            return `cd -- ${shellQuote(cwd)} && ${baseCommand}`;
+            return `cd -- ${shellQuote(cwd)} || exit 1; ${baseCommand}; __rcc_exit=$?`;
         }
         const safeCommandName = shellQuote(commandName || command || 'client');
         const loopBody = [
             `${baseCommand}`,
             '__rcc_exit=$?',
-            'if [ "$__rcc_exit" -eq 0 ] || [ "$__rcc_exit" -eq 130 ] || [ "$__rcc_exit" -eq 143 ]; then exit "$__rcc_exit"; fi',
-            'if [ "$__rcc_try" -ge "$__rcc_max" ]; then exit "$__rcc_exit"; fi',
+            'if [ "$__rcc_exit" -eq 0 ] || [ "$__rcc_exit" -eq 130 ] || [ "$__rcc_exit" -eq 143 ]; then break; fi',
+            'if [ "$__rcc_try" -ge "$__rcc_max" ]; then break; fi',
             '__rcc_try=$((__rcc_try + 1))',
             `echo "[routecodex][self-heal] ${safeCommandName} exited with code $__rcc_exit; retry $__rcc_try/$__rcc_max in $__rcc_delay s" >&2`,
             'sleep "$__rcc_delay"'
@@ -583,6 +715,14 @@ function launchCommandInTmuxPane(args) {
             `while true; do ${loopBody}; done`
         ].join('; ');
     })();
+    // Client lifecycle owns managed tmux lifecycle: once command exits, destroy session.
+    const shellCommand = [
+        commandBody,
+        tmuxSessionName
+            ? `tmux kill-session -t ${shellQuote(tmuxSessionName)} >/dev/null 2>&1 || true`
+            : ':',
+        'exit "$__rcc_exit"'
+    ].join('; ');
     try {
         // Prefer respawn-pane for deterministic execution in managed sessions.
         // This avoids flaky "typed but not submitted" behavior from send-keys on some terminals.
@@ -639,21 +779,32 @@ function sendJson(res, status, payload) {
     res.setHeader('content-type', 'application/json');
     res.end(body);
 }
-async function startClockClientService(args) {
+function normalizeTmuxInjectedText(raw) {
+    return raw
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join(' ')
+        .trim();
+}
+async function startSessionClientService(args) {
     const { ctx, resolved, workdir, tmuxTarget, spawnSyncImpl, clientType, managedTmuxSession, getManagedProcessState } = args;
     const daemonId = (() => {
         try {
-            return `clockd_${crypto.randomUUID()}`;
+            return `sessiond_${crypto.randomUUID()}`;
         }
         catch {
-            return `clockd_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+            return `sessiond_${Date.now()}_${Math.random().toString(16).slice(2)}`;
         }
     })();
     const normalizedTmuxTarget = String(tmuxTarget || '').trim();
+    if (!normalizedTmuxTarget) {
+        // No tmux target means no reliable stdin injection path.
+        // Do not register a session-client daemon with a synthetic session id.
+        return null;
+    }
     const tmuxSessionId = (() => {
-        if (!normalizedTmuxTarget) {
-            return daemonId;
-        }
         const idx = normalizedTmuxTarget.indexOf(':');
         const candidate = (idx >= 0 ? normalizedTmuxTarget.slice(0, idx) : normalizedTmuxTarget).trim();
         return candidate || daemonId;
@@ -667,12 +818,14 @@ async function startClockClientService(args) {
                 return;
             }
             const body = await readJsonBody(req);
-            const text = typeof body.text === 'string' ? body.text.trim() : '';
+            const text = typeof body.text === 'string' ? normalizeTmuxInjectedText(body.text) : '';
             if (!text) {
                 sendJson(res, 400, { ok: false, message: 'text is required' });
                 return;
             }
             try {
+                // Ensure pane is not stuck in copy-mode before literal injection + submit.
+                spawnSyncImpl('tmux', ['send-keys', '-t', normalizedTmuxTarget, '-X', 'cancel'], { encoding: 'utf8' });
                 const literal = spawnSyncImpl('tmux', ['send-keys', '-t', normalizedTmuxTarget, '-l', '--', text], { encoding: 'utf8' });
                 if (literal.status !== 0) {
                     sendJson(res, 500, {
@@ -701,7 +854,7 @@ async function startClockClientService(args) {
             server?.listen(0, '127.0.0.1', () => {
                 const address = server?.address();
                 if (!address || typeof address === 'string') {
-                    reject(new Error('failed to resolve clock daemon callback address'));
+                    reject(new Error('failed to resolve session daemon callback address'));
                     return;
                 }
                 resolve(address.port);
@@ -719,6 +872,7 @@ async function startClockClientService(args) {
         callbackUrl = `http://127.0.0.1:${port}/inject`;
     }
     const controlUrl = `${resolved.protocol}://127.0.0.1:${resolved.port}${resolved.basePath}`;
+    const controlRequestTimeoutMs = resolveIntFromEnv(ctx.env.ROUTECODEX_SESSION_CLIENT_CONTROL_TIMEOUT_MS ?? ctx.env.RCC_SESSION_CLIENT_CONTROL_TIMEOUT_MS, 1500, 200, 30_000);
     const normalizeManagedProcessPayload = () => {
         const state = typeof getManagedProcessState === 'function' ? getManagedProcessState() : undefined;
         const managedClientProcess = state?.managedClientProcess === true;
@@ -735,19 +889,39 @@ async function startClockClientService(args) {
         };
     };
     const post = async (pathSuffix, payload) => {
+        const abortController = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        const timeoutHandle = abortController
+            ? setTimeout(() => {
+                try {
+                    abortController.abort();
+                }
+                catch {
+                    // ignore abort failures
+                }
+            }, controlRequestTimeoutMs)
+            : null;
+        if (timeoutHandle && typeof timeoutHandle.unref === 'function') {
+            timeoutHandle.unref();
+        }
         try {
             const response = await ctx.fetch(`${controlUrl}${pathSuffix}`, {
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
-                body: JSON.stringify(payload)
+                body: JSON.stringify(payload),
+                ...(abortController ? { signal: abortController.signal } : {})
             });
             return { ok: response.ok, status: response.status };
         }
         catch {
             return { ok: false, status: 0 };
         }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
     };
-    const reRegisterBackoffMs = resolveIntFromEnv(ctx.env.ROUTECODEX_CLOCK_CLIENT_REREGISTER_BACKOFF_MS ?? ctx.env.RCC_CLOCK_CLIENT_REREGISTER_BACKOFF_MS, 1500, 200, 60_000);
+    const reRegisterBackoffMs = resolveIntFromEnv(ctx.env.ROUTECODEX_SESSION_CLIENT_REREGISTER_BACKOFF_MS ?? ctx.env.RCC_SESSION_CLIENT_REREGISTER_BACKOFF_MS, 1500, 200, 60_000);
     let registerInFlight = null;
     let lastRegisterAttemptAtMs = 0;
     const registerDaemon = async () => {
@@ -756,7 +930,7 @@ async function startClockClientService(args) {
         }
         registerInFlight = (async () => {
             lastRegisterAttemptAtMs = Date.now();
-            const result = await post('/daemon/clock-client/register', {
+            const result = await post('/daemon/session-client/register', {
                 daemonId,
                 tmuxSessionId,
                 sessionId: tmuxSessionId,
@@ -777,7 +951,7 @@ async function startClockClientService(args) {
         }
     };
     const syncHeartbeat = async () => {
-        const heartbeat = await post('/daemon/clock-client/heartbeat', {
+        const heartbeat = await post('/daemon/session-client/heartbeat', {
             daemonId,
             tmuxSessionId,
             sessionId: tmuxSessionId,
@@ -824,7 +998,7 @@ async function startClockClientService(args) {
         syncHeartbeat,
         stop: async () => {
             clearInterval(heartbeat);
-            await post('/daemon/clock-client/unregister', { daemonId });
+            await post('/daemon/session-client/unregister', { daemonId });
             if (!server) {
                 return;
             }
@@ -912,10 +1086,24 @@ export function createLauncherCommand(program, ctx, spec) {
     command.action(async (extraArgs = [], options) => {
         const spinner = await ctx.createSpinner(`Preparing ${spec.displayName} with RouteCodex...`);
         try {
-            const resolved = resolveServerConnection(ctx, fsImpl, pathImpl, options);
-            const ensureResult = await ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, resolved);
+            const tmuxOnly = spec.commandName === 'codex';
+            const resolved = tmuxOnly ? undefined : resolveServerConnection(ctx, fsImpl, pathImpl, options);
+            const requireResolved = () => {
+                if (!resolved) {
+                    throw new Error('RouteCodex server connection is not available for this launcher');
+                }
+                return resolved;
+            };
+            let ensureResult = null;
+            if (!tmuxOnly) {
+                const server = requireResolved();
+                await ctx.ensureGuardianDaemon?.();
+                ensureResult = await ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, server, spec.allowAutoStartServer === true);
+                if (!ensureResult.ready) {
+                    spinner.info('RouteCodex server is not running; launcher will continue and wait for your next requests.');
+                }
+            }
             spinner.text = `Launching ${spec.displayName}...`;
-            const baseUrl = `${resolved.protocol}://${resolved.connectHost}${resolved.portPart}${resolved.basePath}`;
             const currentCwd = resolveWorkingDirectory(ctx, fsImpl, pathImpl, options.cwd);
             const spawnSyncImpl = ctx.spawnSyncImpl ?? spawnSync;
             const tmuxSelfHealPolicy = resolveTmuxSelfHealPolicy(ctx.env);
@@ -975,87 +1163,170 @@ export function createLauncherCommand(program, ctx, spec) {
             let managedTmuxSession = null;
             const tmuxEnabled = isTmuxAvailable(spawnSyncImpl);
             if (!tmuxEnabled) {
-                ctx.logger.warning('[clock-advanced] tmux not found; advanced clock client service disabled (launcher will continue).');
+                ctx.logger.warning('[session-advanced] tmux not found; advanced session client service disabled (launcher will continue).');
             }
-            let tmuxTarget = tmuxEnabled ? resolveCurrentTmuxTarget(ctx.env, spawnSyncImpl) : null;
-            if (tmuxTarget && !isReusableTmuxPaneTarget(spawnSyncImpl, tmuxTarget, currentCwd)) {
-                tmuxTarget = null;
+            let tmuxTarget = null;
+            if (tmuxEnabled && !tmuxOnly) {
+                tmuxTarget = resolveCurrentTmuxTarget(ctx.env, spawnSyncImpl);
             }
-            if (tmuxEnabled && !tmuxTarget) {
+            if (tmuxEnabled && (tmuxOnly || !tmuxTarget)) {
                 managedTmuxSession = createManagedTmuxSession({
                     spawnSyncImpl,
-                    cwd: currentCwd,
-                    commandName: spec.commandName
+                    cwd: currentCwd
                 });
                 if (managedTmuxSession) {
                     tmuxTarget = managedTmuxSession.tmuxTarget;
-                    if (managedTmuxSession.reused) {
-                        ctx.logger.info('[clock-advanced] reused existing managed tmux session and rebound launcher automatically.');
-                    }
-                    else {
-                        ctx.logger.info('[clock-advanced] started managed tmux session automatically; no manual tmux setup needed.');
-                    }
+                    ctx.logger.info('[session-advanced] started managed tmux session automatically; no manual tmux setup needed.');
                 }
                 else {
-                    ctx.logger.warning('[clock-advanced] failed to start managed tmux session; launcher continues without advanced mode.');
+                    ctx.logger.warning('[session-advanced] failed to start managed tmux session; launcher continues without advanced mode.');
                 }
             }
             const managedClientProcessEnabled = !managedTmuxSession;
             let managedClientPid = null;
             const managedClientCommandHint = managedClientProcessEnabled ? resolvedBinary : undefined;
-            const reclaimRequiredRaw = String(ctx.env.ROUTECODEX_CLOCK_RECLAIM_REQUIRED
-                ?? ctx.env.RCC_CLOCK_RECLAIM_REQUIRED
+            const reclaimRequiredRaw = String(ctx.env.ROUTECODEX_SESSION_RECLAIM_REQUIRED
+                ?? ctx.env.RCC_SESSION_RECLAIM_REQUIRED
                 ?? '1')
                 .trim()
                 .toLowerCase();
             const reclaimRequired = reclaimRequiredRaw !== '0' && reclaimRequiredRaw !== 'false' && reclaimRequiredRaw !== 'no';
-            const clockClientService = await startClockClientService({
-                ctx,
-                resolved,
-                workdir: currentCwd,
-                tmuxTarget,
-                spawnSyncImpl,
-                clientType: spec.commandName,
-                managedTmuxSession: Boolean(managedTmuxSession),
-                getManagedProcessState: () => ({
-                    managedClientProcess: managedClientProcessEnabled,
-                    managedClientPid,
-                    managedClientCommandHint
-                })
-            });
-            if (managedClientProcessEnabled && reclaimRequired && !clockClientService) {
-                throw new Error('clock client registration failed for managed child process; aborting launch to avoid orphan process');
+            let sessionClientService = null;
+            let sessionAdvancedEnabled = false;
+            let inferredTmuxSessionId;
+            let inferredDaemonId;
+            let sessionClientApiKey;
+            let tmuxOnlySessionId;
+            if (!tmuxOnly) {
+                const server = requireResolved();
+                sessionClientService = await startSessionClientService({
+                    ctx,
+                    resolved: server,
+                    workdir: currentCwd,
+                    tmuxTarget,
+                    spawnSyncImpl,
+                    clientType: spec.commandName,
+                    managedTmuxSession: Boolean(managedTmuxSession),
+                    getManagedProcessState: () => ({
+                        managedClientProcess: managedClientProcessEnabled,
+                        managedClientPid,
+                        managedClientCommandHint
+                    })
+                });
+                if (managedClientProcessEnabled && reclaimRequired && tmuxTarget && !sessionClientService) {
+                    throw new Error('session client registration failed for managed child process; aborting launch to avoid orphan process');
+                }
+                if (tmuxTarget && !sessionClientService) {
+                    ctx.logger.warning('[session-advanced] failed to start session client daemon service; launcher continues without advanced mode.');
+                }
+                sessionAdvancedEnabled = Boolean(sessionClientService && tmuxTarget);
+                inferredTmuxSessionId =
+                    sessionClientService?.tmuxSessionId ||
+                        inferTmuxSessionIdFromTarget(tmuxTarget) ||
+                        undefined;
+                inferredDaemonId =
+                    sessionClientService?.daemonId ||
+                        (inferredTmuxSessionId ? `sessiond_unbound_${process.pid}` : undefined);
+                sessionClientApiKey =
+                    inferredTmuxSessionId && inferredDaemonId
+                        ? encodeSessionClientApiKey(server.configuredApiKey || 'rcc-proxy-key', inferredDaemonId, inferredTmuxSessionId)
+                        : (server.configuredApiKey || 'rcc-proxy-key');
+                if (isSessionScopeTraceEnabled()) {
+                    try {
+                        const parsedDaemonId = extractSessionClientDaemonIdFromApiKey(sessionClientApiKey) || 'none';
+                        const parsedTmuxSessionId = extractSessionClientScopeIdFromApiKey(sessionClientApiKey) || 'none';
+                        const verbose = isSessionScopeTraceVerbose();
+                        ctx.logger.info(`[session-scope][launch] command=${spec.commandName} advanced=${sessionAdvancedEnabled ? 'on' : 'off'} ` +
+                            `daemon=${parsedDaemonId} tmux=${parsedTmuxSessionId} tmuxTarget=${tmuxTarget || 'none'}` +
+                            (verbose ? ` managedTmux=${managedTmuxSession ? 'yes' : 'no'} serverStarted=${ensureResult?.started ? 'yes' : 'no'}` : ''));
+                    }
+                    catch {
+                        // best-effort diagnostics only
+                    }
+                }
+                await ctx.registerGuardianProcess?.({
+                    source: spec.commandName,
+                    pid: process.pid,
+                    ppid: process.ppid,
+                    port: server.port,
+                    tmuxSessionId: sessionClientService?.tmuxSessionId || inferTmuxSessionIdFromTarget(tmuxTarget) || undefined,
+                    tmuxTarget: tmuxTarget || undefined,
+                    metadata: {
+                        workingDirectory: currentCwd,
+                        binary: resolvedBinary,
+                        managedTmuxSession: Boolean(managedTmuxSession),
+                        autoStartedServer: ensureResult?.started === true
+                    }
+                });
             }
-            if (tmuxTarget && !clockClientService) {
-                ctx.logger.warning('[clock-advanced] failed to start clock client daemon service; launcher continues without advanced mode.');
+            const applyLifecycleOrThrow = async (args) => {
+                if (tmuxOnly || !resolved) {
+                    return;
+                }
+                const server = requireResolved();
+                const accepted = await ctx.reportGuardianLifecycle?.({
+                    action: args.action,
+                    source: `cli.launcher.${spec.commandName}`,
+                    actorPid: process.pid,
+                    targetPid: args.targetPid && args.targetPid > 0 ? args.targetPid : undefined,
+                    signal: args.signal,
+                    metadata: {
+                        port: server.port,
+                        serverUrl: server.serverUrl
+                    }
+                });
+                if (ctx.reportGuardianLifecycle && accepted !== true) {
+                    throw new Error(`guardian lifecycle apply rejected (${args.action})`);
+                }
+            };
+            if (tmuxOnly) {
+                const tmuxSessionId = inferTmuxSessionIdFromTarget(tmuxTarget) || '';
+                tmuxOnlySessionId = tmuxSessionId || undefined;
             }
-            const clockAdvancedEnabled = Boolean(clockClientService && tmuxTarget);
-            const clockClientApiKey = clockAdvancedEnabled && clockClientService
-                ? encodeClockClientApiKey(resolved.configuredApiKey || 'rcc-proxy-key', clockClientService.daemonId)
-                : (resolved.configuredApiKey || 'rcc-proxy-key');
-            const toolEnv = spec.buildEnv({
-                env: {
-                    ...ctx.env,
-                    PWD: currentCwd,
-                    RCC_WORKDIR: currentCwd,
-                    ROUTECODEX_WORKDIR: currentCwd,
-                    OPENAI_BASE_URL: normalizeOpenAiBaseUrl(baseUrl),
-                    OPENAI_API_BASE: normalizeOpenAiBaseUrl(baseUrl),
-                    OPENAI_API_BASE_URL: normalizeOpenAiBaseUrl(baseUrl),
-                    OPENAI_API_KEY: clockClientApiKey,
-                    RCC_CLOCK_ADVANCED_ENABLED: clockAdvancedEnabled ? '1' : '0',
-                    ...(clockAdvancedEnabled && clockClientService
-                        ? {
-                            RCC_CLOCK_CLIENT_SESSION_ID: clockClientService.tmuxSessionId,
-                            RCC_CLOCK_CLIENT_TMUX_SESSION_ID: clockClientService.tmuxSessionId,
-                            RCC_CLOCK_CLIENT_DAEMON_ID: clockClientService.daemonId
+            const toolEnv = (() => {
+                if (tmuxOnly) {
+                    const env = { ...ctx.env };
+                    if (tmuxOnlySessionId) {
+                        const baseKey = (typeof env.ROUTECODEX_HTTP_APIKEY === 'string' && env.ROUTECODEX_HTTP_APIKEY.trim())
+                            || '';
+                        if (!baseKey) {
+                            ctx.logger.warning('[session-scope] ROUTECODEX_HTTP_APIKEY is empty; tmux scope not injected.');
+                            return env;
                         }
-                        : {})
-                },
-                baseUrl,
-                configuredApiKey: resolved.configuredApiKey,
-                cwd: currentCwd
-            });
+                        const scopedKey = encodeSessionClientApiKey(baseKey, '', tmuxOnlySessionId);
+                        env.ROUTECODEX_HTTP_APIKEY = scopedKey;
+                        env.OPENAI_API_KEY = scopedKey;
+                        env.ANTHROPIC_AUTH_TOKEN = scopedKey;
+                    }
+                    return env;
+                }
+                const server = requireResolved();
+                return spec.buildEnv({
+                    env: {
+                        ...ctx.env,
+                        PWD: currentCwd,
+                        RCC_WORKDIR: currentCwd,
+                        ROUTECODEX_WORKDIR: currentCwd,
+                        OPENAI_BASE_URL: normalizeOpenAiBaseUrl(`${server.protocol}://${server.connectHost}${server.portPart}${server.basePath}`),
+                        OPENAI_API_BASE: normalizeOpenAiBaseUrl(`${server.protocol}://${server.connectHost}${server.portPart}${server.basePath}`),
+                        OPENAI_API_BASE_URL: normalizeOpenAiBaseUrl(`${server.protocol}://${server.connectHost}${server.portPart}${server.basePath}`),
+                        OPENAI_API_KEY: sessionClientApiKey,
+                        RCC_SESSION_ADVANCED_ENABLED: sessionAdvancedEnabled ? '1' : '0',
+                        ...(inferredTmuxSessionId
+                            ? {
+                                RCC_SESSION_CLIENT_SESSION_ID: inferredTmuxSessionId,
+                                RCC_SESSION_CLIENT_TMUX_SESSION_ID: inferredTmuxSessionId
+                            }
+                            : {}),
+                        ...(inferredDaemonId
+                            ? { RCC_SESSION_CLIENT_DAEMON_ID: inferredDaemonId }
+                            : {})
+                    },
+                    baseUrl: `${server.protocol}://${server.connectHost}${server.portPart}${server.basePath}`,
+                    configuredApiKey: server.configuredApiKey,
+                    cwd: currentCwd
+                });
+            })();
             const shouldUseShell = ctx.isWindows &&
                 !pathImpl.extname(resolvedBinary) &&
                 !resolvedBinary.includes('/') &&
@@ -1094,39 +1365,137 @@ export function createLauncherCommand(program, ctx, spec) {
             managedClientPid = typeof toolProcess.pid === 'number' && Number.isFinite(toolProcess.pid)
                 ? Math.floor(toolProcess.pid)
                 : null;
-            if (clockClientService && managedClientProcessEnabled && managedClientPid) {
-                void clockClientService.syncHeartbeat();
+            if (sessionClientService && managedClientProcessEnabled && managedClientPid) {
+                void sessionClientService.syncHeartbeat();
             }
             spinner.succeed(`${spec.displayName} launched with RouteCodex proxy`);
             if (!managedTmuxSession) {
-                ctx.logger.info(`Using RouteCodex server at: ${baseUrl}`);
+                if (!tmuxOnly) {
+                    const server = requireResolved();
+                    ctx.logger.info(`Using RouteCodex server at: ${server.protocol}://${server.connectHost}${server.portPart}${server.basePath}`);
+                }
                 ctx.logger.info(`${spec.displayName} binary: ${resolvedBinary}`);
-                if (ensureResult.started && ensureResult.logPath) {
+                if (!tmuxOnly && ensureResult?.started && ensureResult.logPath) {
                     ctx.logger.info(`RouteCodex auto-start logs: ${ensureResult.logPath}`);
                 }
                 ctx.logger.info(`Working directory for ${spec.displayName}: ${currentCwd}`);
                 ctx.logger.info(`Press Ctrl+C to exit ${spec.displayName}`);
             }
-            const shutdown = async (signal) => {
+            let shutdownTriggered = false;
+            let toolProcessClosing = false;
+            let observedToolExitCode;
+            let observedToolExitSignal = null;
+            let requestedShutdownSignal = null;
+            let clientExitSummaryLogged = false;
+            const logClientExitSummary = () => {
+                if (clientExitSummaryLogged || !shouldLogClientExitSummary(spec.commandName)) {
+                    return;
+                }
+                clientExitSummaryLogged = true;
+                const codeLabel = typeof observedToolExitCode === 'number' && Number.isFinite(observedToolExitCode)
+                    ? String(observedToolExitCode)
+                    : 'n/a';
+                const signalLabel = observedToolExitSignal || 'none';
+                ctx.logger.info(`[client-exit] ${spec.displayName} exited (code=${codeLabel}, signal=${signalLabel})`);
+            };
+            const finalizeToolTermination = async (options) => {
+                if (toolProcessClosing) {
+                    return;
+                }
+                toolProcessClosing = true;
+                logClientExitSummary();
                 try {
-                    toolProcess.kill(signal);
+                    await sessionClientService?.stop();
                 }
                 catch {
                     // ignore
                 }
                 try {
-                    await clockClientService?.stop();
+                    if (managedTmuxSession && shouldStopManagedTmuxOnToolExit(ctx.env)) {
+                        managedTmuxSession.stop();
+                    }
                 }
                 catch {
                     // ignore
                 }
                 try {
-                    managedTmuxSession?.stop();
+                    await applyLifecycleOrThrow({
+                        action: 'launcher_tool_exit',
+                        signal: observedToolExitSignal ? String(observedToolExitSignal) : undefined,
+                        targetPid: toolProcess.pid ?? null
+                    });
+                }
+                catch {
+                    // ignore lifecycle logging errors in exit path
+                }
+                const forcedExitCode = options?.forceExitCode;
+                if (typeof forcedExitCode === 'number' && Number.isFinite(forcedExitCode)) {
+                    ctx.exit(Math.max(0, Math.floor(forcedExitCode)));
+                    return;
+                }
+                if (requestedShutdownSignal || observedToolExitSignal) {
+                    ctx.exit(0);
+                    return;
+                }
+                ctx.exit(observedToolExitCode ?? 0);
+            };
+            const shutdown = async (signal) => {
+                if (shutdownTriggered) {
+                    return;
+                }
+                shutdownTriggered = true;
+                requestedShutdownSignal = signal;
+                const targetGuard = canSignalOwnedToolProcess({
+                    env: ctx.env,
+                    pid: toolProcess.pid ?? null,
+                    expectedParentPid: process.pid,
+                    commandHint: resolvedBinary
+                });
+                logProcessLifecycle({
+                    event: 'launcher_signal_guard',
+                    source: 'cli.launcher.shutdown',
+                    details: {
+                        commandName: spec.commandName,
+                        signal,
+                        targetPid: toolProcess.pid ?? null,
+                        result: targetGuard.ok ? 'allowed' : 'blocked',
+                        reason: targetGuard.reason
+                    }
+                });
+                logProcessLifecycle({
+                    event: 'launcher_signal_forward',
+                    source: 'cli.launcher.shutdown',
+                    details: {
+                        commandName: spec.commandName,
+                        signal,
+                        forwarded: false,
+                        targetPid: toolProcess.pid ?? null,
+                        reason: 'disabled_no_forward'
+                    }
+                });
+                try {
+                    await applyLifecycleOrThrow({
+                        action: 'launcher_exit_signal',
+                        signal,
+                        targetPid: toolProcess.pid ?? null
+                    });
+                }
+                catch (error) {
+                    try {
+                        ctx.logger.error(error instanceof Error ? error.message : String(error));
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                try {
+                    if (managedTmuxSession && shouldStopManagedTmuxOnShutdown(signal, ctx.env)) {
+                        managedTmuxSession.stop();
+                    }
                 }
                 catch {
                     // ignore
                 }
-                ctx.exit(0);
             };
             const onSignal = ctx.onSignal ?? ((signal, cb) => process.on(signal, cb));
             onSignal('SIGINT', () => {
@@ -1144,40 +1513,30 @@ export function createLauncherCommand(program, ctx, spec) {
                         // ignore
                     }
                     try {
-                        await clockClientService?.stop();
+                        await applyLifecycleOrThrow({
+                            action: 'launcher_tool_error_exit',
+                            targetPid: toolProcess.pid ?? null
+                        });
                     }
                     catch {
-                        // ignore
-                    }
-                    try {
-                        managedTmuxSession?.stop();
+                        // ignore lifecycle logging errors for terminal error path
                     }
-                    catch {
-                        // ignore
-                    }
-                    ctx.exit(1);
+                    await finalizeToolTermination({ forceExitCode: 1 });
                 })();
             });
             toolProcess.on('exit', (code, signal) => {
-                void (async () => {
-                    try {
-                        await clockClientService?.stop();
-                    }
-                    catch {
-                        // ignore
-                    }
-                    try {
-                        managedTmuxSession?.stop();
-                    }
-                    catch {
-                        // ignore
-                    }
-                    if (signal) {
-                        ctx.exit(0);
-                        return;
-                    }
-                    ctx.exit(code ?? 0);
-                })();
+                observedToolExitCode = code;
+                observedToolExitSignal = signal ?? null;
+            });
+            toolProcess.on('close', (code, signal) => {
+                if (observedToolExitCode === undefined) {
+                    observedToolExitCode = code;
+                }
+                if (!observedToolExitSignal) {
+                    observedToolExitSignal = signal ?? null;
+                }
+                logClientExitSummary();
+                void finalizeToolTermination();
             });
             await ctx.waitForever();
         }