aegis-bridge 2.15.3 → 2.15.5

package/dist/auth.js

@@ -10,6 +10,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { authStoreSchema } from './validation.js';
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { secureFilePermissions } from './file-utils.js';
 /** Default SSE token lifetime: 60 seconds. */
 const SSE_TOKEN_TTL_MS = 60_000;
 /** Max SSE tokens per bearer token to prevent abuse. */
@@ -61,6 +62,7 @@ export class AuthManager {
             await mkdir(dir, { recursive: true });
         }
         await writeFile(this.keysFile, JSON.stringify(this.store, null, 2), { mode: 0o600 });
+        await secureFilePermissions(this.keysFile);
     }
     /** Create a new API key. Returns the plaintext key (only shown once). */
     async createKey(name, rateLimit = 100) {

package/dist/channels/telegram.js

@@ -6,6 +6,7 @@
  *
  * Formatting: HTML parse_mode with structured, clean messages.
  */
+import { homedir } from 'node:os';
 import { esc, bold, code, italic, quickUpdate, taskComplete, alert as styleAlert, } from './telegram-style.js';
 /** Call Telegram Bot API with retry on 429. */
 // ── HTML Helpers ────────────────────────────────────────────────────────────
@@ -25,12 +26,22 @@ function elapsed(ms) {
     return `${h}h ${m % 60}m`;
 }
 function shortPath(path) {
+    const normalized = path.replace(/\\/g, '/');
     // Keep only filename or last 2 segments
-    const parts = path.replace(/^\//, '').split('/');
+    const parts = normalized.replace(/^\//, '').split('/');
     if (parts.length <= 2)
         return parts.join('/');
     return '…/' + parts.slice(-2).join('/');
 }
+function shortenHomePath(workDir) {
+    const normalized = workDir.replace(/\\/g, '/');
+    const home = homedir().replace(/\\/g, '/').replace(/\/+$/, '');
+    if (normalized === home)
+        return '~';
+    if (normalized.startsWith(`${home}/`))
+        return `~${normalized.slice(home.length)}`;
+    return normalized;
+}
 /**
  * Strip Claude Code internal XML tags from assistant messages.
  * These tags (local-command-*, antml:*, etc.) are CC's internal markup
@@ -244,7 +255,7 @@ function md2html(md) {
 // ── Message Formatting ──────────────────────────────────────────────────────
 function formatSessionCreated(name, workDir, id, meta) {
     const shortId = id.slice(0, 8);
-    const shortDir = workDir.replace(/^\/home\/[^/]+\/projects\//, '~/');
+    const shortDir = shortenHomePath(workDir);
     const parts = [`${bold(name)}  ${code(shortDir)}  ${code(shortId)}`];
     const flags = [];
     if (meta?.permissionMode && meta.permissionMode !== 'default')

package/dist/cli.js

@@ -5,23 +5,26 @@
  * `npx aegis-bridge` or `aegis-bridge` starts the server with sensible defaults.
  * Auto-detects tmux and claude CLI, prints helpful startup message.
  */
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseIntSafe, getErrorMessage } from './validation.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+/** Current aegis-bridge version read from package.json at startup. */
 const VERSION = pkg.version;
-function checkDependency(name, command) {
+/** Check whether a required external dependency can be executed. */
+function checkDependency(command, args) {
     try {
-        execSync(`${command} 2>/dev/null`, { stdio: 'ignore' });
+        execFileSync(command, args, { stdio: 'ignore', timeout: 5000 });
         return true;
     }
     catch { /* command not found or exited non-zero */
         return false;
     }
 }
+/** Render the startup banner shown when launching the HTTP server. */
 function printBanner(port) {
     console.log(`
   ┌─────────────────────────────────────────┐
@@ -107,6 +110,7 @@ async function handleCreate(args) {
     console.log(`    Read:     curl ${baseUrl}/v1/sessions/${sessionId}/read`);
     console.log(`    Kill:     curl -X DELETE ${baseUrl}/v1/sessions/${sessionId}`);
 }
+/** Main CLI entry point that dispatches subcommands and bootstraps the server. */
 async function main() {
     const args = process.argv.slice(2);
     // Help
@@ -184,8 +188,8 @@ async function main() {
         process.env.AEGIS_PORT = args[portIdx + 1];
     }
     // Check dependencies
-    const hasTmux = checkDependency('tmux', 'tmux -V');
-    const hasClaude = checkDependency('claude', 'claude --version');
+    const hasTmux = checkDependency('tmux', ['-V']);
+    const hasClaude = checkDependency('claude', ['--version']);
     if (!hasTmux) {
         console.error(`
   ❌ tmux not found.

package/dist/file-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function buildWindowsIcaclsArgs(filePath: string, account: string): string[];
+export declare function secureFilePermissions(filePath: string, platform?: NodeJS.Platform): Promise<void>;

package/dist/file-utils.js

@@ -0,0 +1,37 @@
+import { execFile } from 'node:child_process';
+import { chmod } from 'node:fs/promises';
+const PERMISSIONS_TIMEOUT_MS = 5_000;
+export function buildWindowsIcaclsArgs(filePath, account) {
+    return [filePath, '/inheritance:r', '/grant:r', `${account}:(R,W)`];
+}
+function runIcacls(filePath, account) {
+    const args = buildWindowsIcaclsArgs(filePath, account);
+    return new Promise((resolve, reject) => {
+        execFile('icacls', args, { timeout: PERMISSIONS_TIMEOUT_MS }, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+export async function secureFilePermissions(filePath, platform = process.platform) {
+    if (platform !== 'win32') {
+        await chmod(filePath, 0o600);
+        return;
+    }
+    const username = process.env.USERNAME;
+    if (!username) {
+        console.warn(`Windows permission hardening skipped for ${filePath}: USERNAME is not set`);
+        return;
+    }
+    const account = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${username}` : username;
+    try {
+        await runIcacls(filePath, account);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        console.warn(`Windows permission hardening failed for ${filePath}: ${detail}`);
+    }
+}

package/dist/hook-settings.d.ts

@@ -13,6 +13,8 @@
  *
  * Issue #169: Phase 2 — Inject CC settings.json with HTTP hooks.
  */
+/** Build a normalized path to .claude/settings.local.json for Unix and Windows workDirs. */
+export declare function buildProjectSettingsPath(workDir: string, platform?: NodeJS.Platform): string;
 /** CC hook events that support `type: "http"`.
  *
  * All CC hook events support HTTP hooks. We register the most useful ones

package/dist/hook-settings.js

@@ -19,6 +19,7 @@ import { join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { ccSettingsSchema, containsTraversalSegment } from './validation.js';
+import { secureFilePermissions } from './file-utils.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -45,6 +46,23 @@ function normalizeHookBaseUrl(baseUrl) {
         return baseUrl.replace('0.0.0.0', '127.0.0.1');
     }
 }
+/** Build a normalized path to .claude/settings.local.json for Unix and Windows workDirs. */
+export function buildProjectSettingsPath(workDir, platform = process.platform) {
+    let normalizedWorkDir = platform === 'win32'
+        ? workDir.replace(/\//g, '\\')
+        : workDir.replace(/\\/g, '/');
+    // On Linux, resolve() prepends CWD to Windows paths like "D:\Users\dev"
+    // because Linux doesn't understand Windows drive letters. Only resolve
+    // paths that are NOT already absolute on the target platform.
+    const isWinAbs = /^[A-Za-z]:\\/.test(normalizedWorkDir);
+    const isUnixAbs = /^\//.test(normalizedWorkDir);
+    const alreadyAbs = (platform === 'win32' && isWinAbs) || isUnixAbs;
+    if (!alreadyAbs)
+        normalizedWorkDir = resolve(normalizedWorkDir);
+    // Normalize separators to match the target platform.
+    const result = join(normalizedWorkDir, '.claude', 'settings.local.json');
+    return platform === 'win32' ? result.replace(/\//g, '\\') : result;
+}
 /**
  * Validate a workDir path for use in hook settings resolution.
  * Defense-in-depth against path traversal: rejects paths containing ".." segments
@@ -145,7 +163,7 @@ export async function writeHookSettingsFile(baseUrl, sessionId, hookSecret, work
     let merged = {};
     const safeWorkDir = workDir ? validateWorkDirPath(workDir) : undefined;
     if (safeWorkDir) {
-        const projectSettingsPath = join(safeWorkDir, '.claude', 'settings.local.json');
+        const projectSettingsPath = buildProjectSettingsPath(safeWorkDir);
         if (existsSync(projectSettingsPath)) {
             try {
                 const raw = await readFile(projectSettingsPath, 'utf-8');
@@ -175,6 +193,7 @@ export async function writeHookSettingsFile(baseUrl, sessionId, hookSecret, work
     await mkdir(settingsDir, { recursive: true, mode: 0o700 });
     const filePath = join(settingsDir, `hooks-${sessionId}.json`);
     await writeFile(filePath, JSON.stringify(combined, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await secureFilePermissions(filePath);
     return filePath;
 }
 /**
@@ -210,7 +229,7 @@ export async function cleanupStaleSessionHooks(workDir, activeSessionIds) {
     const safeWorkDir = workDir ? validateWorkDirPath(workDir) : undefined;
     if (!safeWorkDir)
         return;
-    const projectSettingsPath = join(safeWorkDir, '.claude', 'settings.local.json');
+    const projectSettingsPath = buildProjectSettingsPath(safeWorkDir);
     if (!existsSync(projectSettingsPath))
         return;
     try {
@@ -243,6 +262,7 @@ export async function cleanupStaleSessionHooks(workDir, activeSessionIds) {
         }
         if (changed) {
             await writeFile(projectSettingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+            await secureFilePermissions(projectSettingsPath);
         }
     }
     catch {

package/dist/hook.d.ts

@@ -15,4 +15,5 @@
  *   }
  * }
  */
-export {};
+/** Build a shell-safe command string that invokes hook.js with an explicit Node executable. */
+export declare function buildHookCommand(scriptPath: string, nodeExecutable?: string, platform?: NodeJS.Platform): string;

package/dist/hook.js

@@ -16,7 +16,7 @@
  * }
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +32,17 @@ const MAP_FILE = join(BRIDGE_DIR, 'session_map.json');
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const TMUX_PANE_RE = /^%\d+$/;
 const DEFAULT_POINTER_TTL_MS = 24 * 60 * 60 * 1000;
+function normalizeCommandPath(pathValue, platform = process.platform) {
+    return platform === 'win32' ? pathValue.replace(/\//g, '\\') : pathValue.replace(/\\/g, '/');
+}
+function quoteCommandPath(pathValue, platform = process.platform) {
+    const normalized = normalizeCommandPath(pathValue, platform);
+    return `"${normalized.replace(/"/g, '\\"')}"`;
+}
+/** Build a shell-safe command string that invokes hook.js with an explicit Node executable. */
+export function buildHookCommand(scriptPath, nodeExecutable = process.execPath, platform = process.platform) {
+    return `${quoteCommandPath(nodeExecutable, platform)} ${quoteCommandPath(scriptPath, platform)}`;
+}
 function getPointerTtlMs() {
     const raw = process.env.AEGIS_CONTINUATION_POINTER_TTL_MS ?? process.env.MANUS_CONTINUATION_POINTER_TTL_MS;
     const parsed = raw ? Number(raw) : NaN;
@@ -176,7 +187,7 @@ function install() {
         }
         settings = parsed.data;
     }
-    const hookCommand = `node ${join(__dirname, 'hook.js')}`;
+    const hookCommand = buildHookCommand(join(__dirname, 'hook.js'));
     const hooks = (settings.hooks || {});
     const sessionStart = (hooks.SessionStart || []);
     // Check if already installed
@@ -204,4 +215,17 @@ function install() {
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     console.log(`Aegis hook installed in ${settingsPath}`);
 }
-main();
+const isDirectExecution = (() => {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return resolve(argv1) === resolve(__filename);
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectExecution) {
+    main();
+}

package/dist/mcp-server.js

@@ -15,13 +15,27 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isValidUUID } from './validation.js';
 // Read version from package.json at startup (matches cli.ts pattern)
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
 const VERSION = pkg.version;
+function normalizeWorkDirForCompare(workDir) {
+    const isWindowsLikePath = /^[a-zA-Z]:[\\/]/.test(workDir) || workDir.startsWith('\\\\');
+    const normalizedPath = (isWindowsLikePath ? workDir : resolve(workDir))
+        .replace(/\\/g, '/')
+        .replace(/\/+$/, '');
+    return process.platform === 'win32' || isWindowsLikePath
+        ? normalizedPath.toLowerCase()
+        : normalizedPath;
+}
+function isSameOrChildWorkDir(candidate, parent) {
+    const normalizedCandidate = normalizeWorkDirForCompare(candidate);
+    const normalizedParent = normalizeWorkDirForCompare(parent);
+    return normalizedCandidate === normalizedParent || normalizedCandidate.startsWith(`${normalizedParent}/`);
+}
 // ── Aegis REST client ───────────────────────────────────────────────
 export class AegisClient {
     baseUrl;
@@ -65,7 +79,7 @@ export class AegisClient {
             sessions = sessions.filter((s) => s.status === filter.status);
         }
         if (filter?.workDir) {
-            sessions = sessions.filter((s) => s.workDir === filter.workDir || s.workDir?.startsWith(filter.workDir + '/'));
+            sessions = sessions.filter((s) => isSameOrChildWorkDir(s.workDir, filter.workDir));
         }
         return sessions;
     }

package/dist/process-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function buildWindowsFindPidOnPortScript(port: number): string;
+export declare function buildWindowsReadParentPidScript(pid: number): string;
+export declare function findPidOnPort(port: number): Promise<number[]>;
+export declare function readParentPid(pid: number): Promise<number | null>;

package/dist/process-utils.js

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const SUBPROCESS_TIMEOUT_MS = 5_000;
+function runCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { encoding: 'utf-8', timeout: SUBPROCESS_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+function parsePidLines(output) {
+    return [...new Set(output
+            .trim()
+            .split(/\r?\n/)
+            .map(line => parseInt(line.trim(), 10))
+            .filter(pid => Number.isInteger(pid) && pid > 0))];
+}
+export function buildWindowsFindPidOnPortScript(port) {
+    return [
+        `Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue`,
+        'Select-Object -ExpandProperty OwningProcess -Unique',
+    ].join(' | ');
+}
+export function buildWindowsReadParentPidScript(pid) {
+    return [
+        `Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" -ErrorAction SilentlyContinue`,
+        'Select-Object -ExpandProperty ParentProcessId',
+    ].join(' | ');
+}
+export async function findPidOnPort(port) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return [];
+    try {
+        if (process.platform === 'win32') {
+            const script = buildWindowsFindPidOnPortScript(port);
+            const stdout = await runCommand('powershell', ['-NoProfile', '-Command', script]);
+            return parsePidLines(stdout);
+        }
+        const stdout = await runCommand('lsof', ['-ti', `tcp:${port}`]);
+        return parsePidLines(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+export async function readParentPid(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (process.platform === 'win32') {
+            const script = buildWindowsReadParentPidScript(pid);
+            const stdout = await runCommand('powershell', ['-NoProfile', '-Command', script]);
+            const parent = parseInt(stdout.trim(), 10);
+            return Number.isInteger(parent) && parent > 0 ? parent : null;
+        }
+        if (process.platform !== 'linux') {
+            return null;
+        }
+        const status = await readFile(`/proc/${pid}/status`, 'utf-8');
+        const match = status.match(/^PPid:\s+(\d+)/m);
+        if (!match)
+            return null;
+        const parent = parseInt(match[1], 10);
+        return Number.isInteger(parent) && parent > 0 ? parent : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server.d.ts

@@ -7,4 +7,4 @@
  * Notification channels (Telegram, webhooks, etc.) are pluggable —
  * the server doesn't know which channels are active.
  */
-export { readPpid } from './startup.js';
+export { readParentPid as readPpid } from './process-utils.js';

package/dist/server.js

@@ -49,6 +49,7 @@ import { MemoryBridge } from './memory-bridge.js';
 import { cleanupTerminatedSessionState } from './session-cleanup.js';
 import { normalizeApiErrorPayload } from './api-error-envelope.js';
 import { listenWithRetry, removePidFile, writePidFile } from './startup.js';
+import { isWindowsShutdownMessage, parseShutdownTimeoutMs } from './shutdown-utils.js';
 import { authKeySchema, sendMessageSchema, commandSchema, bashSchema, screenshotSchema, permissionHookSchema, stopHookSchema, batchSessionSchema, pipelineSchema, handshakeRequestSchema, parseIntSafe, isValidUUID, compareSemver, extractCCVersion, MIN_CC_VERSION, permissionProfileSchema, } from './validation.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -1676,7 +1677,7 @@ function registerChannels(cfg) {
     }
 }
 // Preserve public export used by tests and external imports.
-export { readPpid } from './startup.js';
+export { readParentPid as readPpid } from './process-utils.js';
 async function main() {
     // Load configuration
     config = await loadConfig();
@@ -1765,56 +1766,67 @@ async function main() {
     // Issue #361: Graceful shutdown handler
     // Issue #415: Reentrance guard at handler level prevents double execution on rapid SIGINT
     let shuttingDown = false;
+    const shutdownTimeoutMs = parseShutdownTimeoutMs(process.env.AEGIS_SHUTDOWN_TIMEOUT_MS);
     async function gracefulShutdown(signal) {
         console.log(`${signal} received, shutting down gracefully...`);
-        // 1. Stop accepting new requests
+        const forceExitTimer = setTimeout(() => {
+            console.error(`Graceful shutdown timed out after ${shutdownTimeoutMs}ms — forcing process exit`);
+            process.exit(1);
+        }, shutdownTimeoutMs);
+        forceExitTimer.unref?.();
         try {
-            await app.close();
-        }
-        catch (e) {
-            console.error('Error closing server:', e);
-        }
-        // 2. Stop background monitors and intervals
-        monitor.stop();
-        swarmMonitor.stop();
-        clearInterval(reaperInterval);
-        clearInterval(zombieReaperInterval);
-        clearInterval(metricsSaveInterval);
-        clearInterval(ipPruneInterval);
-        clearInterval(authFailPruneInterval);
-        clearInterval(authSweepInterval);
-        // Issue #569: Kill all CC sessions and tmux windows before exit
-        try {
-            await killAllSessions(sessions, tmux);
-        }
-        catch (e) {
-            console.error('Error killing sessions:', e);
-        }
-        // 3. Destroy channels (awaits Telegram poll loop)
-        try {
-            await channels.destroy();
-        }
-        catch (e) {
-            console.error('Error destroying channels:', e);
-        }
-        // 4. Save session state
-        try {
-            await sessions.save();
-        }
-        catch (e) {
-            console.error('Error saving sessions:', e);
-        }
-        // 5. Save metrics
-        try {
-            await metrics.save();
+            // 1. Stop accepting new requests
+            try {
+                await app.close();
+            }
+            catch (e) {
+                console.error('Error closing server:', e);
+            }
+            // 2. Stop background monitors and intervals
+            monitor.stop();
+            swarmMonitor.stop();
+            clearInterval(reaperInterval);
+            clearInterval(zombieReaperInterval);
+            clearInterval(metricsSaveInterval);
+            clearInterval(ipPruneInterval);
+            clearInterval(authFailPruneInterval);
+            clearInterval(authSweepInterval);
+            // Issue #569: Kill all CC sessions and tmux windows before exit
+            try {
+                await killAllSessions(sessions, tmux);
+            }
+            catch (e) {
+                console.error('Error killing sessions:', e);
+            }
+            // 3. Destroy channels (awaits Telegram poll loop)
+            try {
+                await channels.destroy();
+            }
+            catch (e) {
+                console.error('Error destroying channels:', e);
+            }
+            // 4. Save session state
+            try {
+                await sessions.save();
+            }
+            catch (e) {
+                console.error('Error saving sessions:', e);
+            }
+            // 5. Save metrics
+            try {
+                await metrics.save();
+            }
+            catch (e) {
+                console.error('Error saving metrics:', e);
+            }
+            // 6. Cleanup PID file
+            removePidFile(pidFilePath);
+            console.log('Graceful shutdown complete');
+            process.exit(0);
         }
-        catch (e) {
-            console.error('Error saving metrics:', e);
+        finally {
+            clearTimeout(forceExitTimer);
         }
-        // 6. Cleanup PID file
-        removePidFile(pidFilePath);
-        console.log('Graceful shutdown complete');
-        process.exit(0);
     }
     process.on('SIGTERM', () => { if (!shuttingDown) {
         shuttingDown = true;
@@ -1824,6 +1836,14 @@ async function main() {
         shuttingDown = true;
         void gracefulShutdown('SIGINT');
     } });
+    if (process.platform === 'win32') {
+        process.on('message', (message) => {
+            if (!shuttingDown && isWindowsShutdownMessage(message)) {
+                shuttingDown = true;
+                void gracefulShutdown('WINMSG');
+            }
+        });
+    }
     process.on('unhandledRejection', (reason) => {
         console.error('unhandledRejection:', reason);
     });

package/dist/session.d.ts

@@ -10,6 +10,12 @@ import { type UIState } from './terminal-parser.js';
 import type { Config } from './config.js';
 import { type PermissionPolicy, type PermissionProfile } from './validation.js';
 import { type PermissionDecision } from './permission-request-manager.js';
+/**
+ * Canonical runtime metadata for an Aegis-managed Claude Code session.
+ *
+ * This structure is persisted to disk and reused by the REST API, SSE layer,
+ * monitoring loop, and session recovery logic.
+ */
 export interface SessionInfo {
     id: string;
     windowId: string;
@@ -43,6 +49,7 @@ export interface SessionInfo {
     permissionProfile?: PermissionProfile;
     prd?: string;
 }
+/** Persisted session store keyed by Aegis session ID. */
 export interface SessionState {
     sessions: Record<string, SessionInfo>;
 }
@@ -57,6 +64,10 @@ export interface SessionState {
 export declare function detectApprovalMethod(paneText: string): 'numbered' | 'yes';
 /** Resolves a pending PermissionRequest hook with a decision. */
 export type { PermissionDecision };
+/**
+ * Coordinates session lifecycle, persistence, transcript discovery, and
+ * interactive approval/question flows for all managed Claude Code sessions.
+ */
 export declare class SessionManager {
     private tmux;
     private config;

package/dist/session.js

@@ -52,6 +52,10 @@ export function detectApprovalMethod(paneText) {
     }
     return 'yes';
 }
+/**
+ * Coordinates session lifecycle, persistence, transcript discovery, and
+ * interactive approval/question flows for all managed Claude Code sessions.
+ */
 export class SessionManager {
     tmux;
     config;

package/dist/shutdown-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * shutdown-utils.ts — reusable shutdown helpers for server signal handling.
+ */
+export declare function parseShutdownTimeoutMs(rawValue: string | undefined, fallbackMs?: number): number;
+export declare function isWindowsShutdownMessage(message: unknown): boolean;

package/dist/shutdown-utils.js

@@ -0,0 +1,24 @@
+/**
+ * shutdown-utils.ts — reusable shutdown helpers for server signal handling.
+ */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 15_000;
+export function parseShutdownTimeoutMs(rawValue, fallbackMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed < 1_000)
+        return fallbackMs;
+    return Math.floor(parsed);
+}
+export function isWindowsShutdownMessage(message) {
+    if (typeof message === 'string') {
+        const normalized = message.trim().toLowerCase();
+        return normalized === 'shutdown' || normalized === 'graceful-shutdown';
+    }
+    if (typeof message === 'object' && message !== null && 'type' in message) {
+        const typeValue = message.type;
+        if (typeof typeValue === 'string') {
+            const normalized = typeValue.trim().toLowerCase();
+            return normalized === 'shutdown' || normalized === 'graceful-shutdown';
+        }
+    }
+    return false;
+}

package/dist/startup.d.ts

@@ -1,5 +1,6 @@
 import Fastify from 'fastify';
 export declare function writePidFile(stateDir: string): string;
 export declare function removePidFile(pidFilePath: string): void;
-export declare function readPpid(pid: number): number;
+/** Read parent PID with cross-platform fallback. */
+export declare function readPpid(pid: number): Promise<number>;
 export declare function listenWithRetry(app: ReturnType<typeof Fastify>, port: number, host: string, stateDir: string, maxRetries?: number): Promise<void>;

package/dist/startup.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
-import { readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { writeFileSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
+import { findPidOnPort, readParentPid } from './process-utils.js';
 export function writePidFile(stateDir) {
     try {
         const pidFilePath = path.join(stateDir, 'aegis.pid');
@@ -41,21 +41,22 @@ function pidExists(pid) {
         return false;
     }
 }
-export function readPpid(pid) {
-    const status = readFileSync(`/proc/${pid}/status`, 'utf-8');
-    const match = status.match(/^PPid:\s+(\d+)/m);
-    if (!match)
-        throw new Error(`no PPid line in /proc/${pid}/status`);
-    return parseInt(match[1], 10);
+/** Read parent PID with cross-platform fallback. */
+export async function readPpid(pid) {
+    const parent = await readParentPid(pid);
+    if (parent === null) {
+        throw new Error(`no parent PID available for process ${pid}`);
+    }
+    return parent;
 }
-function isAncestorPid(pid) {
+async function isAncestorPid(pid) {
     try {
         let current = process.ppid;
         for (let depth = 0; depth < 10 && current > 1; depth++) {
             if (current === pid)
                 return true;
             try {
-                current = readPpid(current);
+                current = await readPpid(current);
             }
             catch {
                 break;
@@ -93,17 +94,14 @@ async function waitForPortRelease(port, maxWaitMs = 5000) {
 async function killStalePortHolder(port, stateDir) {
     await new Promise(resolve => setTimeout(resolve, 100 + Math.random() * 400));
     try {
-        const output = execFileSync('lsof', ['-ti', `tcp:${port}`], { encoding: 'utf-8', timeout: 5000 }).trim();
-        if (!output)
-            return false;
-        const pids = output.split('\n').map(s => parseInt(s.trim(), 10)).filter(n => !Number.isNaN(n));
+        const pids = await findPidOnPort(port);
         if (pids.length === 0)
             return false;
         let killed = false;
         for (const pid of pids) {
             if (pid === process.pid)
                 continue;
-            if (isAncestorPid(pid)) {
+            if (await isAncestorPid(pid)) {
                 console.warn(`EADDRINUSE recovery: skipping ancestor PID ${pid} on port ${port}`);
                 continue;
             }

package/dist/swarm-monitor.d.ts

@@ -75,10 +75,13 @@ export declare class SwarmMonitor {
     private lastResult;
     private timer;
     private eventHandlers;
+    private windowsDisabledLogged;
     constructor(sessions: SessionManager, config?: SwarmMonitorConfig);
     /** Register an event handler for teammate lifecycle events. */
     onEvent(handler: SwarmEventHandler): void;
     private emitEvent;
+    private isWindowsPlatform;
+    private logWindowsDisabled;
     /** Start the periodic scan loop. */
     start(): void;
     /** Stop the periodic scan loop. */

package/dist/swarm-monitor.js

@@ -28,6 +28,7 @@ export class SwarmMonitor {
     lastResult = null;
     timer = null;
     eventHandlers = [];
+    windowsDisabledLogged = false;
     constructor(sessions, config = DEFAULT_SWARM_CONFIG) {
         this.sessions = sessions;
         this.config = config;
@@ -46,8 +47,21 @@ export class SwarmMonitor {
             }
         }
     }
+    isWindowsPlatform() {
+        return process.platform === 'win32';
+    }
+    logWindowsDisabled() {
+        if (this.windowsDisabledLogged)
+            return;
+        console.info('SwarmMonitor disabled on Windows: tmux swarm sockets are not supported on this platform.');
+        this.windowsDisabledLogged = true;
+    }
     /** Start the periodic scan loop. */
     start() {
+        if (this.isWindowsPlatform()) {
+            this.logWindowsDisabled();
+            return;
+        }
         if (this.running)
             return;
         this.running = true;
@@ -70,6 +84,16 @@ export class SwarmMonitor {
     }
     /** Run a single scan and return the result. */
     async scan() {
+        if (this.isWindowsPlatform()) {
+            this.logWindowsDisabled();
+            this.lastResult = {
+                swarms: [],
+                totalSockets: 0,
+                totalTeammates: 0,
+                scannedAt: Date.now(),
+            };
+            return this.lastResult;
+        }
         try {
             const sockets = await this.discoverSwarmSockets();
             // Issue #353: Inspect sockets in parallel to avoid N×timeout accumulation.
@@ -176,6 +200,17 @@ export class SwarmMonitor {
     }
     /** Inspect a single swarm socket and return swarm info. */
     async inspectSwarmSocket(socketName) {
+        if (this.isWindowsPlatform()) {
+            const pid = this.extractPid(socketName);
+            return {
+                socketName,
+                pid,
+                parentSession: null,
+                teammates: [],
+                aggregatedStatus: 'no_teammates',
+                lastScannedAt: Date.now(),
+            };
+        }
         const pid = this.extractPid(socketName);
         const teammates = await this.listSwarmWindows(socketName);
         const parentSession = this.findParentSession(pid, teammates);

package/dist/tmux.d.ts

@@ -4,6 +4,8 @@
  * Wraps tmux CLI commands to manage windows inside a named session.
  * Port of CCBot's tmux_manager.py to TypeScript.
  */
+/** Build the platform-specific launch wrapper that clears inherited tmux vars. */
+export declare function buildClaudeLaunchCommand(baseCommand: string, platform?: NodeJS.Platform): string;
 /** Thrown when a tmux command exceeds its timeout. */
 export declare class TmuxTimeoutError extends Error {
     constructor(args: string[], timeoutMs: number);
@@ -89,10 +91,14 @@ export declare class TmuxManager {
      *  Values never appear in terminal scrollback or capture-pane output.
      */
     private setEnvSecure;
+    /** #909: Windows variant — set tmux env and dot-source a temp .ps1 in the active pane. */
+    private setEnvSecureWin32;
     /** #837: Direct variant of setEnvSecure that uses sendKeysDirectInternal instead of
      *  sendKeys, safe to call from inside a serialize() callback without deadlocking.
      *  Identical logic otherwise. */
     private setEnvSecureDirect;
+    /** #909: Direct Windows variant that avoids serialize() re-entry. */
+    private setEnvSecureDirectWin32;
     /** P1 fix: Check if a window exists. Returns true if window is in the session.
      *  #357: Uses a short-lived cache to avoid repeated tmux CLI calls. */
     windowExists(windowId: string): Promise<boolean>;

package/dist/tmux.js

@@ -12,10 +12,21 @@ import { join } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { computeProjectHash } from './path-utils.js';
+import { secureFilePermissions } from './file-utils.js';
 /** Shell-escape a string by wrapping in single quotes and escaping embedded single quotes. */
 function shellEscape(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
+function powerShellSingleQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Build the platform-specific launch wrapper that clears inherited tmux vars. */
+export function buildClaudeLaunchCommand(baseCommand, platform = process.platform) {
+    if (platform === 'win32') {
+        return `Remove-Item Env:TMUX -ErrorAction SilentlyContinue; Remove-Item Env:TMUX_PANE -ErrorAction SilentlyContinue; ${baseCommand}`;
+    }
+    return `unset TMUX TMUX_PANE && exec ${baseCommand}`;
+}
 /** Validate that an env var key contains only safe characters (Issue #630: uppercase only, aligned with session.ts). */
 const ENV_KEY_RE = /^[A-Z_][A-Z0-9_]*$/;
 const execFileAsync = promisify(execFile);
@@ -309,13 +320,9 @@ export class TmuxManager {
         if (existsSync(settingsPath)) {
             cmd += ` --settings ${shellEscape(settingsPath)}`;
         }
-        // Issue #68: Unset $TMUX and $TMUX_PANE before launching Claude Code.
-        // If Aegis itself runs inside tmux, CC inherits these vars and:
-        //   - Teammate spawns attempt split-pane in Aegis session (not isolated)
-        //   - Color capabilities reduced to 256
-        //   - Clipboard passthrough via tmux load-buffer instead of OSC 52
-        // Prefixing with 'unset' ensures CC gets a clean environment.
-        cmd = `unset TMUX TMUX_PANE && exec ${cmd}`;
+        // Issue #68 / #909: Clear inherited tmux vars before launching CC.
+        // Linux/macOS uses `unset`; Windows uses PowerShell env removal.
+        cmd = buildClaudeLaunchCommand(cmd);
         // Send the command to start Claude
         await this.sendKeys(windowId, cmd, true);
         // Issue #7: Verify Claude process started by checking pane command.
@@ -393,6 +400,10 @@ export class TmuxManager {
      *  Values never appear in terminal scrollback or capture-pane output.
      */
     async setEnvSecure(windowId, env) {
+        if (process.platform === 'win32') {
+            await this.setEnvSecureWin32(windowId, env);
+            return;
+        }
         const fs = await import('node:fs/promises');
         const path = await import('node:path');
         // Validate env var keys before interpolation
@@ -410,6 +421,7 @@ export class TmuxManager {
             return `export ${key}='${escaped}'`;
         });
         await fs.writeFile(tmpFile, lines.join('\n') + '\n', { mode: 0o600 });
+        await secureFilePermissions(tmpFile);
         // Source the file and delete it — all in one command so the values
         // appear in the process environment but not in the terminal history.
         // The 'source' line is visible but only shows the temp file path, not the values.
@@ -428,10 +440,44 @@ export class TmuxManager {
         }
         catch { /* already deleted by shell */ }
     }
+    /** #909: Windows variant — set tmux env and dot-source a temp .ps1 in the active pane. */
+    async setEnvSecureWin32(windowId, env) {
+        const fs = await import('node:fs/promises');
+        const path = await import('node:path');
+        for (const key of Object.keys(env)) {
+            if (!ENV_KEY_RE.test(key)) {
+                throw new Error(`Invalid env var key: '${key}' — must match ${ENV_KEY_RE.source}`);
+            }
+        }
+        const tmpFile = path.join(tmpdir(), `.aegis-env-${randomBytes(16).toString('hex')}.ps1`);
+        const lines = Object.entries(env).map(([key, val]) => `$env:${key} = ${powerShellSingleQuote(val)}`);
+        await fs.writeFile(tmpFile, lines.join('\n') + '\n', { mode: 0o600 });
+        for (const [key, val] of Object.entries(env)) {
+            await this.tmux('set-environment', '-t', this.sessionName, key, val);
+        }
+        const psPath = powerShellSingleQuote(tmpFile);
+        const cmd = `. ${psPath}; Remove-Item -LiteralPath ${psPath} -Force -ErrorAction SilentlyContinue`;
+        await this.sendKeys(windowId, cmd, true);
+        await this.pollUntil(async () => { try {
+            await stat(tmpFile);
+            return false;
+        }
+        catch {
+            return true;
+        } }, 50, 750);
+        try {
+            await fs.unlink(tmpFile);
+        }
+        catch { /* already deleted by shell */ }
+    }
     /** #837: Direct variant of setEnvSecure that uses sendKeysDirectInternal instead of
      *  sendKeys, safe to call from inside a serialize() callback without deadlocking.
      *  Identical logic otherwise. */
     async setEnvSecureDirect(windowId, env) {
+        if (process.platform === 'win32') {
+            await this.setEnvSecureDirectWin32(windowId, env);
+            return;
+        }
         const fs = await import('node:fs/promises');
         const path = await import('node:path');
         for (const key of Object.keys(env)) {
@@ -445,6 +491,7 @@ export class TmuxManager {
             return `export ${key}='${escaped}'`;
         });
         await fs.writeFile(tmpFile, lines.join('\n') + '\n', { mode: 0o600 });
+        await secureFilePermissions(tmpFile);
         // Use sendKeysDirectInternal to avoid re-entering serialize()
         const cmd = `source ${shellEscape(tmpFile)} && rm -f ${shellEscape(tmpFile)}`;
         await this.sendKeysDirectInternal(windowId, cmd, true);
@@ -460,6 +507,36 @@ export class TmuxManager {
         }
         catch { /* already deleted by shell */ }
     }
+    /** #909: Direct Windows variant that avoids serialize() re-entry. */
+    async setEnvSecureDirectWin32(windowId, env) {
+        const fs = await import('node:fs/promises');
+        const path = await import('node:path');
+        for (const key of Object.keys(env)) {
+            if (!ENV_KEY_RE.test(key)) {
+                throw new Error(`Invalid env var key: '${key}' — must match ${ENV_KEY_RE.source}`);
+            }
+        }
+        const tmpFile = path.join(tmpdir(), `.aegis-env-${randomBytes(16).toString('hex')}.ps1`);
+        const lines = Object.entries(env).map(([key, val]) => `$env:${key} = ${powerShellSingleQuote(val)}`);
+        await fs.writeFile(tmpFile, lines.join('\n') + '\n', { mode: 0o600 });
+        for (const [key, val] of Object.entries(env)) {
+            await this.tmuxInternal('set-environment', '-t', this.sessionName, key, val);
+        }
+        const psPath = powerShellSingleQuote(tmpFile);
+        const cmd = `. ${psPath}; Remove-Item -LiteralPath ${psPath} -Force -ErrorAction SilentlyContinue`;
+        await this.sendKeysDirectInternal(windowId, cmd, true);
+        await this.pollUntil(async () => { try {
+            await stat(tmpFile);
+            return false;
+        }
+        catch {
+            return true;
+        } }, 50, 750);
+        try {
+            await fs.unlink(tmpFile);
+        }
+        catch { /* already deleted by shell */ }
+    }
     /** P1 fix: Check if a window exists. Returns true if window is in the session.
      *  #357: Uses a short-lived cache to avoid repeated tmux CLI calls. */
     async windowExists(windowId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-bridge",
-  "version": "2.15.3",
+  "version": "2.15.5",
   "type": "module",
   "description": "Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship.",
   "main": "dist/server.js",
@@ -27,10 +27,12 @@
     "build": "tsc && npm run build:copy-dashboard",
     "build:copy-dashboard": "node scripts/copy-dashboard.mjs",
     "build:dashboard": "cd dashboard && npm ci && npm run build",
+    "docs": "typedoc",
     "start": "node dist/cli.js",
     "dev": "tsc && node dist/cli.js",
     "prepublishOnly": "npm run build:dashboard && npm run build",
     "test": "vitest run",
+    "test:smoke": "node scripts/uat-smoke.mjs",
     "test:fault-harness": "vitest run src/__tests__/fault-injection-harness-901.test.ts"
   },
   "keywords": [
@@ -72,6 +74,7 @@
     "@types/ws": "^8.18.1",
     "lockfile-lint": "5.0.0",
     "ts-morph": "^27.0.2",
+    "typedoc": "^0.28.18",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   }