@jsonstudio/rcc 0.89.2202 → 0.90.1

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

@@ -4,9 +4,97 @@ 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 { encodeClockClientApiKey, extractClockClientDaemonIdFromApiKey, extractClockClientTmuxSessionIdFromApiKey } from '../../utils/clock-client-token.js';
+import { isClockScopeTraceEnabled, isClockScopeTraceVerbose } from '../../utils/clock-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';
+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) {
@@ -69,43 +157,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 +281,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 +296,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 +406,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 +468,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) {
@@ -506,24 +660,38 @@ function findReusableManagedTmuxSession(spawnSyncImpl, cwd, commandName) {
         return null;
     }
 }
+function requestManagedTmuxSessionExit(spawnSyncImpl, sessionName) {
+    const target = String(sessionName || '').trim();
+    if (!target) {
+        return;
+    }
+    try {
+        spawnSyncImpl('tmux', ['send-keys', '-t', target, '-X', 'cancel'], { 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, 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
-                }
-            }
-        };
-    }
     const sessionName = (() => {
         const token = normalizeSessionToken(commandName);
         return `rcc_${token}_${Date.now()}_${Math.random().toString(16).slice(2, 8)}`;
@@ -543,34 +711,32 @@ function createManagedTmuxSession(args) {
         tmuxTarget,
         reused: false,
         stop: () => {
-            try {
-                spawnSyncImpl('tmux', ['kill-session', '-t', sessionName], { encoding: 'utf8' });
-            }
-            catch {
-                // ignore
-            }
+            requestManagedTmuxSessionExit(spawnSyncImpl, sessionName);
         }
     };
 }
 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 +749,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,6 +813,15 @@ function sendJson(res, status, payload) {
     res.setHeader('content-type', 'application/json');
     res.end(body);
 }
+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 startClockClientService(args) {
     const { ctx, resolved, workdir, tmuxTarget, spawnSyncImpl, clientType, managedTmuxSession, getManagedProcessState } = args;
     const daemonId = (() => {
@@ -650,10 +833,12 @@ async function startClockClientService(args) {
         }
     })();
     const normalizedTmuxTarget = String(tmuxTarget || '').trim();
+    if (!normalizedTmuxTarget) {
+        // No tmux target means no reliable stdin injection path.
+        // Do not register a clock-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 +852,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, {
@@ -719,6 +906,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_CLOCK_CLIENT_CONTROL_TIMEOUT_MS ?? ctx.env.RCC_CLOCK_CLIENT_CONTROL_TIMEOUT_MS, 1500, 200, 30_000);
     const normalizeManagedProcessPayload = () => {
         const state = typeof getManagedProcessState === 'function' ? getManagedProcessState() : undefined;
         const managedClientProcess = state?.managedClientProcess === true;
@@ -735,17 +923,37 @@ 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);
     let registerInFlight = null;
@@ -913,7 +1121,11 @@ export function createLauncherCommand(program, ctx, spec) {
         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);
+            await ctx.ensureGuardianDaemon?.();
+            const ensureResult = await ensureServerReady(ctx, fsImpl, pathImpl, spinner, options, resolved, 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);
@@ -1023,16 +1235,64 @@ export function createLauncherCommand(program, ctx, spec) {
                     managedClientCommandHint
                 })
             });
-            if (managedClientProcessEnabled && reclaimRequired && !clockClientService) {
+            if (managedClientProcessEnabled && reclaimRequired && tmuxTarget && !clockClientService) {
                 throw new Error('clock client registration failed for managed child process; aborting launch to avoid orphan process');
             }
             if (tmuxTarget && !clockClientService) {
                 ctx.logger.warning('[clock-advanced] failed to start clock client daemon service; launcher continues without advanced mode.');
             }
             const clockAdvancedEnabled = Boolean(clockClientService && tmuxTarget);
-            const clockClientApiKey = clockAdvancedEnabled && clockClientService
-                ? encodeClockClientApiKey(resolved.configuredApiKey || 'rcc-proxy-key', clockClientService.daemonId)
+            const inferredTmuxSessionId = clockClientService?.tmuxSessionId ||
+                inferTmuxSessionIdFromTarget(tmuxTarget) ||
+                undefined;
+            const inferredDaemonId = clockClientService?.daemonId ||
+                (inferredTmuxSessionId ? `clockd_unbound_${process.pid}` : undefined);
+            const clockClientApiKey = inferredTmuxSessionId && inferredDaemonId
+                ? encodeClockClientApiKey(resolved.configuredApiKey || 'rcc-proxy-key', inferredDaemonId, inferredTmuxSessionId)
                 : (resolved.configuredApiKey || 'rcc-proxy-key');
+            if (isClockScopeTraceEnabled()) {
+                try {
+                    const parsedDaemonId = extractClockClientDaemonIdFromApiKey(clockClientApiKey) || 'none';
+                    const parsedTmuxSessionId = extractClockClientTmuxSessionIdFromApiKey(clockClientApiKey) || 'none';
+                    const verbose = isClockScopeTraceVerbose();
+                    ctx.logger.info(`[clock-scope][launch] command=${spec.commandName} advanced=${clockAdvancedEnabled ? '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: resolved.port,
+                tmuxSessionId: clockClientService?.tmuxSessionId || inferTmuxSessionIdFromTarget(tmuxTarget) || undefined,
+                tmuxTarget: tmuxTarget || undefined,
+                metadata: {
+                    workingDirectory: currentCwd,
+                    binary: resolvedBinary,
+                    managedTmuxSession: Boolean(managedTmuxSession),
+                    autoStartedServer: ensureResult.started === true
+                }
+            });
+            const applyLifecycleOrThrow = async (args) => {
+                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: resolved.port,
+                        serverUrl: resolved.serverUrl
+                    }
+                });
+                if (ctx.reportGuardianLifecycle && accepted !== true) {
+                    throw new Error(`guardian lifecycle apply rejected (${args.action})`);
+                }
+            };
             const toolEnv = spec.buildEnv({
                 env: {
                     ...ctx.env,
@@ -1044,12 +1304,14 @@ export function createLauncherCommand(program, ctx, spec) {
                     OPENAI_API_BASE_URL: normalizeOpenAiBaseUrl(baseUrl),
                     OPENAI_API_KEY: clockClientApiKey,
                     RCC_CLOCK_ADVANCED_ENABLED: clockAdvancedEnabled ? '1' : '0',
-                    ...(clockAdvancedEnabled && clockClientService
+                    ...(inferredTmuxSessionId
                         ? {
-                            RCC_CLOCK_CLIENT_SESSION_ID: clockClientService.tmuxSessionId,
-                            RCC_CLOCK_CLIENT_TMUX_SESSION_ID: clockClientService.tmuxSessionId,
-                            RCC_CLOCK_CLIENT_DAEMON_ID: clockClientService.daemonId
+                            RCC_CLOCK_CLIENT_SESSION_ID: inferredTmuxSessionId,
+                            RCC_CLOCK_CLIENT_TMUX_SESSION_ID: inferredTmuxSessionId
                         }
+                        : {}),
+                    ...(inferredDaemonId
+                        ? { RCC_CLOCK_CLIENT_DAEMON_ID: inferredDaemonId }
                         : {})
                 },
                 baseUrl,
@@ -1107,26 +1369,121 @@ export function createLauncherCommand(program, ctx, spec) {
                 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 clockClientService?.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 +1501,30 @@ export function createLauncherCommand(program, ctx, spec) {
                         // ignore
                     }
                     try {
-                        await clockClientService?.stop();
-                    }
-                    catch {
-                        // ignore
-                    }
-                    try {
-                        managedTmuxSession?.stop();
+                        await applyLifecycleOrThrow({
+                            action: 'launcher_tool_error_exit',
+                            targetPid: toolProcess.pid ?? null
+                        });
                     }
                     catch {
-                        // ignore
+                        // ignore lifecycle logging errors for terminal error path
                     }
-                    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();
         }