aegis-bridge 2.15.2 → 2.15.4

package/README.md

@@ -7,6 +7,7 @@
   <img src="https://img.shields.io/github/actions/workflow/status/OneStepAt4time/aegis/ci.yml?branch=main" alt="CI" />
   <img src="https://img.shields.io/npm/l/aegis-bridge.svg" alt="license" />
   <img src="https://img.shields.io/badge/node-%3E%3D20.0.0-blue.svg" alt="node" />
+  <img src="https://img.shields.io/badge/MCP-ready-green.svg" alt="MCP ready" />
 </p>
 
 <p align="center">
@@ -96,6 +97,14 @@ Or via `.mcp.json`:
 
 **3 prompts** — `implement_issue`, `review_pr`, `debug_session`
 
+## Ecosystem Integrations
+
+Aegis works beyond Claude Code anywhere an MCP host can launch a local stdio server.
+
+- [Cursor integration](docs/integrations/cursor.md)
+- [Windsurf integration](docs/integrations/windsurf.md)
+- [MCP Registry preparation](docs/integrations/mcp-registry.md)
+
 ---
 
 ## REST API

package/dist/cli.js

@@ -12,7 +12,9 @@ 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;
+/** Check whether a required external dependency can be executed. */
 function checkDependency(name, command) {
     try {
         execSync(`${command} 2>/dev/null`, { stdio: 'ignore' });
@@ -22,6 +24,7 @@ function checkDependency(name, command) {
         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

package/dist/consensus.d.ts

@@ -0,0 +1,16 @@
+export type ConsensusFocusArea = 'correctness' | 'security' | 'performance';
+export interface ConsensusRequest {
+    id: string;
+    targetSessionId: string;
+    reviewerIds: string[];
+    focusAreas: ConsensusFocusArea[];
+    status: 'running' | 'completed' | 'failed';
+    createdAt: number;
+}
+export interface ConsensusReview {
+    reviewerId: string;
+    focusArea: ConsensusFocusArea;
+    findings: string[];
+}
+export declare function buildConsensusPrompt(targetSessionId: string, focusArea: ConsensusFocusArea): string;
+export declare function mergeConsensusFindings(reviews: ConsensusReview[]): string[];

package/dist/consensus.js

@@ -0,0 +1,19 @@
+export function buildConsensusPrompt(targetSessionId, focusArea) {
+    return [
+        `Review Aegis session ${targetSessionId}.`,
+        `Focus area: ${focusArea}.`,
+        'Return concise findings ordered by severity.',
+        'Prefer concrete regressions, risks, and missing verification.',
+    ].join(' ');
+}
+export function mergeConsensusFindings(reviews) {
+    const merged = new Set();
+    for (const review of reviews) {
+        for (const finding of review.findings) {
+            const normalized = finding.trim();
+            if (normalized)
+                merged.add(normalized);
+        }
+    }
+    return Array.from(merged.values());
+}

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

@@ -45,6 +45,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 +162,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');
@@ -210,7 +227,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 {

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/hooks.js

@@ -15,6 +15,7 @@
  * Issue #169: Phase 3 — Hook-driven status detection.
  */
 import { isValidUUID, hookBodySchema, parseIntSafe } from './validation.js';
+import { evaluatePermissionProfile } from './permission-evaluator.js';
 /** CC hook events that require a decision response. */
 const DECISION_EVENTS = new Set(['PreToolUse', 'PermissionRequest']);
 /** Permission modes that should be auto-approved via hook response. */
@@ -289,6 +290,37 @@ export function registerHookRoutes(app, deps) {
                     // Timeout: allow without answer (CC shows question to user in terminal)
                     console.log(`Hooks: AskUserQuestion timeout for session ${sessionId} — allowing without answer`);
                 }
+                if (session.permissionProfile) {
+                    const evaluation = evaluatePermissionProfile(session.permissionProfile, {
+                        toolName,
+                        toolInput: hookBody.tool_input,
+                    });
+                    if (evaluation.behavior === 'deny') {
+                        deps.eventBus.emit(sessionId, {
+                            event: 'permission_denied',
+                            sessionId,
+                            timestamp: new Date().toISOString(),
+                            data: { toolName, reason: evaluation.reason },
+                        });
+                        return reply.status(200).send({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: 'deny',
+                                reason: evaluation.reason,
+                            },
+                        });
+                    }
+                    if (evaluation.behavior === 'ask') {
+                        deps.eventBus.emitApproval(sessionId, `Permission profile requires approval for ${toolName}`);
+                        const decision = await deps.sessions.waitForPermissionDecision(sessionId, PERMISSION_TIMEOUT_MS, toolName, evaluation.reason);
+                        return reply.status(200).send({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: decision,
+                            },
+                        });
+                    }
+                }
                 // Default: allow without modification
                 return reply.status(200).send({
                     hookSpecificOutput: {

package/dist/permission-evaluator.d.ts

@@ -0,0 +1,10 @@
+import type { PermissionProfile } from './validation.js';
+export interface PermissionEvaluationInput {
+    toolName: string;
+    toolInput?: Record<string, unknown>;
+}
+export interface PermissionEvaluationResult {
+    behavior: 'allow' | 'deny' | 'ask';
+    reason: string;
+}
+export declare function evaluatePermissionProfile(profile: PermissionProfile, input: PermissionEvaluationInput): PermissionEvaluationResult;

package/dist/permission-evaluator.js

@@ -0,0 +1,48 @@
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i');
+}
+function extractCandidatePaths(toolInput) {
+    if (!toolInput)
+        return [];
+    const values = [toolInput.path, toolInput.file_path, toolInput.target, ...(Array.isArray(toolInput.paths) ? toolInput.paths : [])];
+    return values.filter((v) => typeof v === 'string');
+}
+function extractContentSize(toolInput) {
+    const content = toolInput?.content;
+    return typeof content === 'string' ? content.length : null;
+}
+function isLikelyWriteTool(toolName) {
+    return /write|edit|delete|rename|move|create/i.test(toolName);
+}
+export function evaluatePermissionProfile(profile, input) {
+    for (const rule of profile.rules) {
+        if (rule.tool !== input.toolName)
+            continue;
+        if (rule.pattern) {
+            const candidate = typeof input.toolInput?.command === 'string'
+                ? input.toolInput.command
+                : JSON.stringify(input.toolInput ?? {});
+            if (!globToRegExp(rule.pattern).test(candidate))
+                continue;
+        }
+        if (rule.constraints?.readOnly && isLikelyWriteTool(input.toolName)) {
+            return { behavior: 'deny', reason: `Denied by readOnly constraint for ${input.toolName}` };
+        }
+        if (rule.constraints?.paths && rule.constraints.paths.length > 0) {
+            const paths = extractCandidatePaths(input.toolInput);
+            const allowed = paths.every((candidate) => rule.constraints.paths.some((prefix) => candidate.startsWith(prefix)));
+            if (!allowed) {
+                return { behavior: 'deny', reason: `Denied by path constraint for ${input.toolName}` };
+            }
+        }
+        if (rule.constraints?.maxFileSize) {
+            const size = extractContentSize(input.toolInput);
+            if (size !== null && size > rule.constraints.maxFileSize) {
+                return { behavior: 'deny', reason: `Denied by maxFileSize constraint for ${input.toolName}` };
+            }
+        }
+        return { behavior: rule.behavior, reason: `Matched rule for ${input.toolName}` };
+    }
+    return { behavior: profile.defaultBehavior, reason: 'No matching permission rule' };
+}

package/dist/server.js

@@ -37,6 +37,7 @@ import { registerHookRoutes } from './hooks.js';
 import { registerWsTerminalRoute } from './ws-terminal.js';
 import { registerMemoryRoutes } from './memory-routes.js';
 import { registerModelRouterRoutes } from './model-router.js';
+import { buildConsensusPrompt } from './consensus.js';
 import * as templateStore from './template-store.js';
 import { SwarmMonitor } from './swarm-monitor.js';
 import { killAllSessions } from './signal-cleanup-helper.js';
@@ -48,9 +49,11 @@ 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 { authKeySchema, sendMessageSchema, commandSchema, bashSchema, screenshotSchema, permissionHookSchema, stopHookSchema, batchSessionSchema, pipelineSchema, handshakeRequestSchema, parseIntSafe, isValidUUID, compareSemver, extractCCVersion, MIN_CC_VERSION, } from './validation.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);
+const consensusRequests = new Map();
 // ── Configuration ────────────────────────────────────────────────────
 // Issue #349: CSP policy for dashboard responses (shared between static and SPA fallback)
 const DASHBOARD_CSP = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ws: wss:";
@@ -904,6 +907,48 @@ async function forkSessionHandler(req, reply) {
 }
 app.post('/v1/sessions/:id/fork', forkSessionHandler);
 app.post('/sessions/:id/fork', forkSessionHandler);
+async function createConsensusHandler(req, reply) {
+    const targetSessionId = req.params.id;
+    const target = sessions.getSession(targetSessionId);
+    if (!target)
+        return reply.status(404).send({ error: 'Target session not found' });
+    const focusAreas = (req.body?.focusAreas && req.body.focusAreas.length > 0)
+        ? req.body.focusAreas
+        : ['correctness', 'security', 'performance'];
+    const reviewerCount = Math.min(5, Math.max(1, req.body?.reviewerCount ?? focusAreas.length));
+    const selectedFocus = focusAreas.slice(0, reviewerCount);
+    const reviewerIds = [];
+    for (let i = 0; i < selectedFocus.length; i += 1) {
+        const focus = selectedFocus[i];
+        const child = await sessions.createSession({
+            workDir: target.workDir,
+            name: `consensus-${focus}-${targetSessionId.slice(0, 6)}`,
+            parentId: targetSessionId,
+            permissionMode: target.permissionMode,
+        });
+        reviewerIds.push(child.id);
+        await sessions.sendInitialPrompt(child.id, buildConsensusPrompt(targetSessionId, focus));
+    }
+    const consensusId = crypto.randomUUID();
+    const record = {
+        id: consensusId,
+        targetSessionId,
+        reviewerIds,
+        focusAreas: selectedFocus,
+        status: 'running',
+        createdAt: Date.now(),
+    };
+    consensusRequests.set(consensusId, record);
+    return reply.status(202).send(record);
+}
+function getConsensusHandler(req, reply) {
+    const item = consensusRequests.get(req.params.id);
+    if (!item)
+        return reply.status(404).send({ error: 'Consensus request not found' });
+    return item;
+}
+app.post('/v1/sessions/:id/consensus', createConsensusHandler);
+app.get('/v1/consensus/:id', getConsensusHandler);
 async function getPermissionPolicyHandler(req, reply) {
     const sessionId = req.params.id;
     const session = sessions.getSession(sessionId);
@@ -928,6 +973,29 @@ app.get('/v1/sessions/:id/permissions', getPermissionPolicyHandler);
 app.put('/v1/sessions/:id/permissions', updatePermissionPolicyHandler);
 app.get('/sessions/:id/permissions', getPermissionPolicyHandler);
 app.put('/sessions/:id/permissions', updatePermissionPolicyHandler);
+async function getPermissionProfileHandler(req, reply) {
+    const sessionId = req.params.id;
+    const session = sessions.getSession(sessionId);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    return { permissionProfile: session.permissionProfile ?? null };
+}
+async function updatePermissionProfileHandler(req, reply) {
+    const sessionId = req.params.id;
+    const session = sessions.getSession(sessionId);
+    if (!session)
+        return reply.status(404).send({ error: 'Session not found' });
+    const parsed = permissionProfileSchema.safeParse(req.body ?? {});
+    if (!parsed.success)
+        return reply.status(400).send({ error: 'Invalid permission profile', details: parsed.error.issues });
+    session.permissionProfile = parsed.data;
+    await sessions.save();
+    return { permissionProfile: parsed.data };
+}
+app.get('/v1/sessions/:id/permission-profile', getPermissionProfileHandler);
+app.put('/v1/sessions/:id/permission-profile', updatePermissionProfileHandler);
+app.get('/sessions/:id/permission-profile', getPermissionProfileHandler);
+app.put('/sessions/:id/permission-profile', updatePermissionProfileHandler);
 // Read messages
 async function readMessagesHandler(req, reply) {
     try {
@@ -1698,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
-        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)
+        const forceExitTimer = setTimeout(() => {
+            console.error(`Graceful shutdown timed out after ${shutdownTimeoutMs}ms — forcing process exit`);
+            process.exit(1);
+        }, shutdownTimeoutMs);
+        forceExitTimer.unref?.();
         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;
@@ -1757,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

@@ -8,8 +8,14 @@ import { TmuxManager } from './tmux.js';
 import { type ParsedEntry } from './transcript.js';
 import { type UIState } from './terminal-parser.js';
 import type { Config } from './config.js';
-import { type PermissionPolicy } from './validation.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;
@@ -40,8 +46,10 @@ export interface SessionInfo {
     parentId?: string;
     children?: string[];
     permissionPolicy?: PermissionPolicy;
+    permissionProfile?: PermissionProfile;
     prd?: string;
 }
+/** Persisted session store keyed by Aegis session ID. */
 export interface SessionState {
     sessions: Record<string, SessionInfo>;
 }
@@ -56,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;
+/** Read the parent PID for a Linux process from /proc. */
 export declare function readPpid(pid: number): number;
 export declare function listenWithRetry(app: ReturnType<typeof Fastify>, port: number, host: string, stateDir: string, maxRetries?: number): Promise<void>;

package/dist/startup.js

@@ -41,6 +41,7 @@ function pidExists(pid) {
         return false;
     }
 }
+/** Read the parent PID for a Linux process from /proc. */
 export function readPpid(pid) {
     const status = readFileSync(`/proc/${pid}/status`, 'utf-8');
     const match = status.match(/^PPid:\s+(\d+)/m);

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

@@ -16,6 +16,16 @@ import { computeProjectHash } from './path-utils.js';
 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 +319,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 +399,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
@@ -428,10 +438,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)) {
@@ -460,6 +504,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/dist/validation.d.ts

@@ -141,6 +141,48 @@ export declare const permissionRuleSchema: z.ZodObject<{
     commandPattern: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PermissionPolicy = z.infer<typeof permissionRuleSchema>[];
+/** Issue #742: richer per-session permission profile. */
+export declare const permissionConstraintSchema: z.ZodObject<{
+    readOnly: z.ZodOptional<z.ZodBoolean>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxFileSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const permissionProfileRuleSchema: z.ZodObject<{
+    tool: z.ZodString;
+    behavior: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        ask: "ask";
+    }>;
+    pattern: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodObject<{
+        readOnly: z.ZodOptional<z.ZodBoolean>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxFileSize: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const permissionProfileSchema: z.ZodObject<{
+    defaultBehavior: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        ask: "ask";
+    }>;
+    rules: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        behavior: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodObject<{
+            readOnly: z.ZodOptional<z.ZodBoolean>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            maxFileSize: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PermissionProfile = z.infer<typeof permissionProfileSchema>;
 /** Schema for persisted SessionState (sessions: { [id]: SessionInfo }). */
 export declare const persistedStateSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     id: z.ZodString;
@@ -206,6 +248,27 @@ export declare const persistedStateSchema: z.ZodRecord<z.ZodString, z.ZodObject<
         toolName: z.ZodOptional<z.ZodString>;
         commandPattern: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    permissionProfile: z.ZodOptional<z.ZodObject<{
+        defaultBehavior: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        rules: z.ZodArray<z.ZodObject<{
+            tool: z.ZodString;
+            behavior: z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+                ask: "ask";
+            }>;
+            pattern: z.ZodOptional<z.ZodString>;
+            constraints: z.ZodOptional<z.ZodObject<{
+                readOnly: z.ZodOptional<z.ZodBoolean>;
+                paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                maxFileSize: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strip>>;
 /** Schema for a single continuation pointer entry in session_map.json (Issue #900). */
 export declare const sessionMapEntrySchema: z.ZodObject<{

package/dist/validation.js

@@ -138,6 +138,22 @@ export const permissionRuleSchema = z.object({
     toolName: z.string().optional(),
     commandPattern: z.string().optional(),
 });
+/** Issue #742: richer per-session permission profile. */
+export const permissionConstraintSchema = z.object({
+    readOnly: z.boolean().optional(),
+    paths: z.array(z.string().min(1)).max(50).optional(),
+    maxFileSize: z.number().int().positive().max(10_000_000).optional(),
+}).strict();
+export const permissionProfileRuleSchema = z.object({
+    tool: z.string().min(1),
+    behavior: z.enum(['allow', 'deny', 'ask']),
+    pattern: z.string().optional(),
+    constraints: permissionConstraintSchema.optional(),
+}).strict();
+export const permissionProfileSchema = z.object({
+    defaultBehavior: z.enum(['allow', 'deny', 'ask']),
+    rules: z.array(permissionProfileRuleSchema).max(100),
+}).strict();
 /** Schema for persisted SessionState (sessions: { [id]: SessionInfo }). */
 export const persistedStateSchema = z.record(z.string(), z.object({
     id: z.string(),
@@ -173,6 +189,7 @@ export const persistedStateSchema = z.record(z.string(), z.object({
         toolName: z.string().optional(),
         commandPattern: z.string().optional(),
     })).optional(),
+    permissionProfile: permissionProfileSchema.optional(),
 }));
 /** Schema for a single continuation pointer entry in session_map.json (Issue #900). */
 export const sessionMapEntrySchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-bridge",
-  "version": "2.15.2",
+  "version": "2.15.4",
   "type": "module",
   "description": "Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship.",
   "main": "dist/server.js",
@@ -27,6 +27,7 @@
     "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",
@@ -72,6 +73,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"
   }