aegis-bridge 0.1.0

package/dist/channels/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * channels/types.ts — Notification channel interface.
+ *
+ * Every notification channel (Telegram, Discord, webhook, Slack, etc.)
+ * implements this interface. The bridge doesn't know or care which
+ * channels are active — it fires events, channels decide what to do.
+ */
+/** Health status for a channel. */
+export interface ChannelHealthStatus {
+    channel: string;
+    healthy: boolean;
+    lastSuccess: number | null;
+    lastError: string | null;
+    pendingCount: number;
+}
+/** Events a channel can subscribe to. */
+export type SessionEvent = 'session.created' | 'session.ended' | 'message.user' | 'message.assistant' | 'message.thinking' | 'message.tool_use' | 'message.tool_result' | 'status.idle' | 'status.working' | 'status.permission' | 'status.question' | 'status.plan' | 'status.stall' | 'status.dead' | 'status.stopped' | 'status.error' | 'status.rate_limited' | 'status.permission_timeout' | 'status.recovered' | 'swarm.teammate_spawned' | 'swarm.teammate_finished';
+/** Payload for all session events. */
+export interface SessionEventPayload {
+    event: SessionEvent;
+    timestamp: string;
+    session: {
+        id: string;
+        name: string;
+        workDir: string;
+    };
+    detail: string;
+    /** Contextual data — depends on event type. */
+    meta?: Record<string, unknown>;
+}
+/** Inbound command from a channel (user replied in Telegram, webhook callback, etc.) */
+export interface InboundCommand {
+    sessionId: string;
+    action: 'approve' | 'reject' | 'escape' | 'kill' | 'message' | 'command';
+    text?: string;
+}
+/** Callback for inbound commands. */
+export type InboundHandler = (cmd: InboundCommand) => Promise<void>;
+/**
+ * A notification channel.
+ *
+ * Channels are initialized once and receive events for the lifetime
+ * of the bridge. They can optionally accept inbound commands
+ * (bidirectional channels like Telegram).
+ */
+export interface Channel {
+    /** Human-readable channel name (for logging). */
+    readonly name: string;
+    /** Initialize the channel. Called once at startup. */
+    init?(onInbound: InboundHandler): Promise<void>;
+    /** Tear down the channel. Called on shutdown. */
+    destroy?(): Promise<void>;
+    /** Called when a new session is created. */
+    onSessionCreated?(payload: SessionEventPayload): Promise<void>;
+    /** Called when a session ends. */
+    onSessionEnded?(payload: SessionEventPayload): Promise<void>;
+    /** Called when a message is sent to/from CC. */
+    onMessage?(payload: SessionEventPayload): Promise<void>;
+    /** Called when session status changes (idle, working, permission, question, plan). */
+    onStatusChange?(payload: SessionEventPayload): Promise<void>;
+    /**
+     * Optional: filter which events this channel cares about.
+     * Return true to receive the event, false to skip.
+     * If not implemented, receives all events.
+     */
+    filter?(event: SessionEvent): boolean;
+    /** Return entries from the dead letter queue (failed deliveries). */
+    getDeadLetterQueue?(): Array<{
+        timestamp: string;
+        endpoint: string;
+        event: SessionEvent;
+        error: string;
+        attempts: number;
+    }>;
+    /** Return channel health status. */
+    getHealth?(): ChannelHealthStatus;
+}

package/dist/channels/types.js

@@ -0,0 +1,8 @@
+/**
+ * channels/types.ts — Notification channel interface.
+ *
+ * Every notification channel (Telegram, Discord, webhook, Slack, etc.)
+ * implements this interface. The bridge doesn't know or care which
+ * channels are active — it fires events, channels decide what to do.
+ */
+export {};

package/dist/channels/webhook.d.ts

@@ -0,0 +1,60 @@
+/**
+ * channels/webhook.ts — Generic webhook notification channel.
+ *
+ * Fires HTTP POST to configured URLs on session events.
+ * Configure via AEGIS_WEBHOOKS (or legacy MANUS_WEBHOOKS) env var or config file.
+ */
+import type { Channel, SessionEvent, SessionEventPayload } from './types.js';
+export interface WebhookEndpoint {
+    /** URL to POST to. */
+    url: string;
+    /** Filter: only fire on these events. Omit = all events. */
+    events?: SessionEvent[];
+    /** Custom headers (e.g. Authorization). */
+    headers?: Record<string, string>;
+    /** Timeout in ms (default: 5000). */
+    timeoutMs?: number;
+}
+export interface WebhookChannelConfig {
+    endpoints: WebhookEndpoint[];
+}
+/** Dead letter queue entry for a failed webhook delivery. */
+export interface DeadLetterEntry {
+    timestamp: string;
+    endpoint: string;
+    event: SessionEvent;
+    error: string;
+    attempts: number;
+}
+export declare class WebhookChannel implements Channel {
+    readonly name = "webhook";
+    private endpoints;
+    /** Issue #89 L14: In-memory dead letter queue for failed deliveries. Max 100 items. */
+    private deadLetterQueue;
+    static readonly DLQ_MAX_SIZE = 100;
+    constructor(config: WebhookChannelConfig);
+    /** Create from AEGIS_WEBHOOKS (or legacy MANUS_WEBHOOKS) env var. Returns null if not set or invalid. */
+    static fromEnv(): WebhookChannel | null;
+    filter(event: SessionEvent): boolean;
+    onSessionCreated(payload: SessionEventPayload): Promise<void>;
+    onSessionEnded(payload: SessionEventPayload): Promise<void>;
+    onMessage(payload: SessionEventPayload): Promise<void>;
+    onStatusChange(payload: SessionEventPayload): Promise<void>;
+    /** Maximum retry attempts per webhook delivery. */
+    static readonly MAX_RETRIES = 5;
+    /** Base delay for exponential backoff (ms). */
+    static readonly BASE_DELAY_MS = 1000;
+    /** Exponential backoff with jitter: delay * (0.5 + Math.random() * 0.5). */
+    static backoff(attempt: number): number;
+    /** Redact sensitive session metadata from webhook payloads. */
+    private static redactPayload;
+    private fire;
+    /** Issue #25: Deliver webhook with retry + exponential backoff. */
+    private deliverWithRetry;
+    /** Issue #89 L14: Add a failed delivery to the dead letter queue. */
+    private addToDeadLetterQueue;
+    /** Issue #89 L14: Get all entries in the dead letter queue. */
+    getDeadLetterQueue(): DeadLetterEntry[];
+    /** Issue #89 L14: Clear the dead letter queue. Returns number of entries cleared. */
+    clearDeadLetterQueue(): number;
+}

package/dist/channels/webhook.js

@@ -0,0 +1,216 @@
+/**
+ * channels/webhook.ts — Generic webhook notification channel.
+ *
+ * Fires HTTP POST to configured URLs on session events.
+ * Configure via AEGIS_WEBHOOKS (or legacy MANUS_WEBHOOKS) env var or config file.
+ */
+import { webhookEndpointSchema, getErrorMessage } from '../validation.js';
+import { validateWebhookUrl, resolveAndCheckIp, buildConnectionUrl } from '../ssrf.js';
+import { redactSecretsFromText } from '../utils/redact-headers.js';
+import { RetriableError } from './manager.js';
+export class WebhookChannel {
+    name = 'webhook';
+    endpoints;
+    /** Issue #89 L14: In-memory dead letter queue for failed deliveries. Max 100 items. */
+    deadLetterQueue = [];
+    static DLQ_MAX_SIZE = 100;
+    constructor(config) {
+        this.endpoints = config.endpoints;
+    }
+    /** Create from AEGIS_WEBHOOKS (or legacy MANUS_WEBHOOKS) env var. Returns null if not set or invalid. */
+    static fromEnv() {
+        const raw = process.env.AEGIS_WEBHOOKS ?? process.env.MANUS_WEBHOOKS;
+        if (!raw)
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed) || parsed.length === 0)
+                return null;
+            // Validate each endpoint with Zod schema + SSRF URL check
+            const endpoints = [];
+            for (let i = 0; i < parsed.length; i++) {
+                const result = webhookEndpointSchema.safeParse(parsed[i]);
+                if (!result.success) {
+                    console.error(`Webhook URL validation failed for endpoint ${i}: schema error`, result.error.message);
+                    return null;
+                }
+                const urlError = validateWebhookUrl(result.data.url);
+                if (urlError) {
+                    console.error(`Webhook URL validation failed for endpoint ${i}: ${urlError}`, result.data.url);
+                    return null;
+                }
+                endpoints.push(result.data);
+            }
+            return new WebhookChannel({ endpoints });
+        }
+        catch (e) {
+            console.error('Failed to parse AEGIS_WEBHOOKS:', e);
+            return null;
+        }
+    }
+    filter(event) {
+        // Accept if ANY endpoint wants this event
+        return this.endpoints.some(ep => !ep.events || ep.events.length === 0 || ep.events.includes(event));
+    }
+    async onSessionCreated(payload) {
+        await this.fire(payload);
+    }
+    async onSessionEnded(payload) {
+        await this.fire(payload);
+    }
+    async onMessage(payload) {
+        await this.fire(payload);
+    }
+    async onStatusChange(payload) {
+        await this.fire(payload);
+    }
+    /** Maximum retry attempts per webhook delivery. */
+    static MAX_RETRIES = 5;
+    /** Base delay for exponential backoff (ms). */
+    static BASE_DELAY_MS = 1000;
+    /** Exponential backoff with jitter: delay * (0.5 + Math.random() * 0.5). */
+    static backoff(attempt) {
+        const base = WebhookChannel.BASE_DELAY_MS * Math.pow(2, attempt - 1);
+        return base * (0.5 + Math.random() * 0.5);
+    }
+    /** Redact sensitive session metadata from webhook payloads. */
+    static redactPayload(payload) {
+        const { session, ...rest } = payload;
+        return {
+            ...rest,
+            session: {
+                id: '[REDACTED]',
+                name: '[REDACTED]',
+                workDir: '[REDACTED]',
+            },
+            api: {
+                read: 'GET /sessions/[REDACTED]/read',
+                send: 'POST /sessions/[REDACTED]/send',
+                kill: 'DELETE /sessions/[REDACTED]',
+            },
+        };
+    }
+    async fire(payload) {
+        const body = JSON.stringify(WebhookChannel.redactPayload(payload));
+        const promises = this.endpoints.map(async (ep) => {
+            // Skip if endpoint filters and this event isn't in the list
+            if (ep.events && ep.events.length > 0 && !ep.events.includes(payload.event))
+                return;
+            await this.deliverWithRetry(ep, body, payload.event);
+        });
+        const results = await Promise.allSettled(promises);
+        const failed = results.filter((r) => r.status === 'rejected');
+        if (failed.length > 0) {
+            const reasons = failed.map(r => String(r.reason)).join('; ');
+            const allFailed = failed.length === results.length;
+            if (allFailed) {
+                console.error(`Webhook: ${failed.length}/${results.length} endpoint(s) failed (total): ${reasons}`);
+            }
+            else {
+                console.warn(`Webhook: ${failed.length}/${results.length} endpoint(s) failed: ${reasons}`);
+            }
+        }
+    }
+    /** Issue #25: Deliver webhook with retry + exponential backoff. */
+    async deliverWithRetry(ep, body, event, maxRetries = WebhookChannel.MAX_RETRIES) {
+        let lastError = '';
+        const hostname = new URL(ep.url).hostname;
+        const bareHost = hostname.replace(/^\[|\]$/g, '');
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                // DNS rebinding protection: resolve and validate IP before each fetch.
+                // Skip for literal IPs (already validated at config time).
+                let fetchUrl = ep.url;
+                let headers = {
+                    'Content-Type': 'application/json',
+                    ...(ep.headers || {}),
+                };
+                if (bareHost !== '127.0.0.1' && bareHost !== '::1' && bareHost !== 'localhost') {
+                    const dnsResult = await resolveAndCheckIp(bareHost);
+                    if (dnsResult.error) {
+                        lastError = dnsResult.error;
+                        if (attempt < maxRetries) {
+                            const delay = WebhookChannel.backoff(attempt);
+                            console.warn(`Webhook ${ep.url} DNS check failed for ${event} (attempt ${attempt}/${maxRetries}): ${lastError}, retrying in ${Math.round(delay)}ms`);
+                            await new Promise(r => setTimeout(r, delay));
+                            continue;
+                        }
+                        console.error(`Webhook ${ep.url} DNS check failed after ${maxRetries} attempts for ${event}: ${lastError}`);
+                        this.addToDeadLetterQueue(ep.url, event, lastError, maxRetries);
+                        throw new RetriableError(lastError);
+                    }
+                    if (dnsResult.resolvedIp) {
+                        const { connectionUrl, hostHeader } = buildConnectionUrl(ep.url, dnsResult.resolvedIp);
+                        fetchUrl = connectionUrl;
+                        headers['Host'] = hostHeader;
+                    }
+                }
+                const res = await fetch(fetchUrl, {
+                    method: 'POST',
+                    headers,
+                    body,
+                    signal: AbortSignal.timeout(ep.timeoutMs || 5000),
+                });
+                if (res.ok)
+                    return; // Success
+                lastError = `HTTP ${res.status}`;
+                // Server error (5xx) — retry; client error (4xx) — don't
+                if (res.status >= 500 && attempt < maxRetries) {
+                    const delay = WebhookChannel.backoff(attempt);
+                    console.warn(`Webhook ${ep.url} returned ${res.status} for ${event} (attempt ${attempt}/${maxRetries}), retrying in ${Math.round(delay)}ms`);
+                    await new Promise(r => setTimeout(r, delay));
+                    continue;
+                }
+                console.error(`Webhook ${ep.url} returned ${res.status} for ${event} (attempt ${attempt}/${maxRetries})`);
+                // Issue #89 L14: Only add to DLQ for 5xx (server) errors, not 4xx client errors
+                if (res.status >= 500) {
+                    this.addToDeadLetterQueue(ep.url, event, lastError, attempt);
+                }
+            }
+            catch (e) {
+                lastError = redactSecretsFromText(getErrorMessage(e), ep.headers);
+                if (attempt < maxRetries) {
+                    const delay = WebhookChannel.backoff(attempt);
+                    console.warn(`Webhook ${ep.url} error for ${event} (attempt ${attempt}/${maxRetries}): ${lastError}, retrying in ${Math.round(delay)}ms`);
+                    await new Promise(r => setTimeout(r, delay));
+                    continue;
+                }
+                console.error(`Webhook ${ep.url} failed after ${maxRetries} attempts for ${event}: ${lastError}`);
+                this.addToDeadLetterQueue(ep.url, event, lastError, maxRetries);
+            }
+            // Final failure — throw so fire() can aggregate.
+            // Use RetriableError for 5xx/network (circuit breaker counts these),
+            // plain Error for 4xx (circuit breaker ignores these).
+            if (lastError.startsWith('HTTP ') && parseInt(lastError.slice(5)) < 500) {
+                throw new Error(lastError);
+            }
+            throw new RetriableError(lastError);
+        }
+    }
+    /** Issue #89 L14: Add a failed delivery to the dead letter queue. */
+    addToDeadLetterQueue(endpoint, event, error, attempts) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            endpoint,
+            event,
+            error,
+            attempts,
+        };
+        this.deadLetterQueue.push(entry);
+        // Evict oldest entries if over max size
+        if (this.deadLetterQueue.length > WebhookChannel.DLQ_MAX_SIZE) {
+            this.deadLetterQueue = this.deadLetterQueue.slice(-WebhookChannel.DLQ_MAX_SIZE);
+        }
+        console.warn(`Webhook DLQ: added failed delivery for ${event} to ${endpoint} after ${attempts} attempts`);
+    }
+    /** Issue #89 L14: Get all entries in the dead letter queue. */
+    getDeadLetterQueue() {
+        return [...this.deadLetterQueue];
+    }
+    /** Issue #89 L14: Clear the dead letter queue. Returns number of entries cleared. */
+    clearDeadLetterQueue() {
+        const count = this.deadLetterQueue.length;
+        this.deadLetterQueue = [];
+        return count;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * cli.ts — CLI entry point for Aegis.
+ *
+ * `npx aegis-bridge` or `aegis-bridge` starts the server with sensible defaults.
+ * Auto-detects tmux and claude CLI, prints helpful startup message.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * cli.ts — CLI entry point for Aegis.
+ *
+ * `npx aegis-bridge` or `aegis-bridge` starts the server with sensible defaults.
+ * Auto-detects tmux and claude CLI, prints helpful startup message.
+ */
+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;
+/** Check whether a required external dependency can be executed. */
+function checkDependency(command, args) {
+    try {
+        execFileSync(command, args, { stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch { /* command not found or exited non-zero */
+        return false;
+    }
+}
+/** Parse tmux -V output and enforce minimum supported version. */
+function checkTmuxVersion(minMajor = 3, minMinor = 3) {
+    try {
+        const out = execFileSync('tmux', ['-V'], { encoding: 'utf-8', timeout: 5000 }).trim();
+        const m = out.match(/tmux\s+(\d+)\.(\d+)/i);
+        if (!m)
+            return { ok: false, version: null };
+        const major = parseInt(m[1], 10);
+        const minor = parseInt(m[2], 10);
+        const ok = major > minMajor || (major === minMajor && minor >= minMinor);
+        return { ok, version: `${major}.${minor}` };
+    }
+    catch {
+        return { ok: false, version: null };
+    }
+}
+/** Render the startup banner shown when launching the HTTP server. */
+function printBanner(port) {
+    console.log(`
+  ┌─────────────────────────────────────────┐
+  │          ⚡ Aegis v${VERSION}               │
+  │    Claude Code Session Bridge            │
+  └─────────────────────────────────────────┘
+  `);
+}
+/** Issue #5 stretch: create a session from CLI. */
+async function handleCreate(args) {
+    // Parse brief text (first non-flag argument)
+    let brief = '';
+    let cwd = process.cwd();
+    let port = parseIntSafe(process.env.AEGIS_PORT, 9100);
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--cwd' && args[i + 1]) {
+            cwd = args[++i];
+        }
+        else if (args[i] === '--port' && args[i + 1]) {
+            port = parseIntSafe(args[++i], 9100);
+        }
+        else if (!args[i].startsWith('-')) {
+            brief = args[i];
+        }
+    }
+    if (!brief) {
+        console.error('  ❌ Missing brief. Usage: aegis-bridge create "Build a login page"');
+        process.exit(1);
+    }
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const sessionName = `cc-${brief.slice(0, 20).replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase()}`;
+    // Create session
+    let sessionId;
+    try {
+        const res = await fetch(`${baseUrl}/v1/sessions`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ workDir: cwd, name: sessionName }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            console.error(`  ❌ Failed to create session: ${err.error || res.statusText}`);
+            process.exit(1);
+        }
+        const session = await res.json();
+        sessionId = session.id;
+        console.log(`  ✅ Session created: ${session.windowName}`);
+        console.log(`     ID: ${sessionId}`);
+    }
+    catch (e) {
+        const cause = e.cause;
+        if (cause?.code === 'ECONNREFUSED') {
+            console.error(`  ❌ Cannot connect to Aegis on port ${port}.`);
+            console.error(`     Start the server first: aegis-bridge`);
+        }
+        else {
+            console.error(`  ❌ ${getErrorMessage(e)}`);
+        }
+        process.exit(1);
+    }
+    // Send brief
+    try {
+        const res = await fetch(`${baseUrl}/v1/sessions/${sessionId}/send`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ text: brief }),
+        });
+        const result = await res.json();
+        if (result.delivered) {
+            console.log(`  ✅ Brief delivered (attempt ${result.attempts})`);
+        }
+        else {
+            console.log(`  ⚠️  Brief sent but delivery not confirmed after ${result.attempts} attempts`);
+        }
+    }
+    catch (e) {
+        console.error(`  ⚠️  Failed to send brief: ${getErrorMessage(e)}`);
+    }
+    // Print next steps
+    console.log('');
+    console.log('  Next steps:');
+    console.log(`    Status:   curl ${baseUrl}/v1/sessions/${sessionId}/health`);
+    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
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(`
+  aegis-bridge — Claude Code session bridge
+
+  Usage:
+    aegis-bridge                  Start the server (port 9100)
+    aegis-bridge --port 3000      Custom port
+    aegis-bridge create "brief"   Create a session and send brief
+    aegis-bridge mcp              Start MCP server (stdio transport)
+    aegis-bridge --help           Show this help
+
+  Create:
+    aegis-bridge create "Build a login page" --cwd /path/to/project
+    aegis-bridge create "Fix the tests"      (uses current directory)
+
+  MCP server:
+    aegis-bridge mcp              Start MCP stdio server
+    aegis-bridge mcp --port 3000  Custom Aegis API port
+    claude mcp add aegis -- npx aegis-bridge mcp
+
+  Environment variables:
+    AEGIS_PORT                    Server port (default: 9100)
+    AEGIS_HOST                    Server host (default: 127.0.0.1)
+    AEGIS_AUTH_TOKEN              Bearer token for API auth
+    AEGIS_TMUX_SESSION            tmux session name (default: aegis)
+    AEGIS_STATE_DIR               State directory (default: ~/.aegis)
+    AEGIS_TG_TOKEN                Telegram bot token
+    AEGIS_TG_GROUP                Telegram group chat ID
+    AEGIS_TG_ALLOWED_USERS        Allowed Telegram user IDs (comma-separated)
+    AEGIS_WEBHOOKS                Webhook URLs (comma-separated)
+
+  API:
+    POST /v1/sessions             Create a session
+    GET  /v1/sessions             List sessions
+    GET  /v1/sessions/:id         Get session
+    POST /v1/sessions/:id/send    Send message
+    GET  /v1/sessions/:id/read    Read messages
+    GET  /v1/sessions/:id/health  Health check
+    DEL  /v1/sessions/:id         Kill session
+    GET  /v1/health               Server health
+
+  Docs: https://github.com/OneStepAt4time/aegis
+    `);
+        process.exit(0);
+    }
+    // Version
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(`aegis-bridge v${VERSION}`);
+        process.exit(0);
+    }
+    // Subcommand: mcp
+    if (args[0] === 'mcp') {
+        const mcpArgs = args.slice(1);
+        let mcpPort = parseIntSafe(process.env.AEGIS_PORT, 9100);
+        const mcpPortIdx = mcpArgs.indexOf('--port');
+        if (mcpPortIdx !== -1 && mcpArgs[mcpPortIdx + 1]) {
+            mcpPort = parseIntSafe(mcpArgs[mcpPortIdx + 1], 9100);
+        }
+        const mcpAuth = process.env.AEGIS_AUTH_TOKEN || process.env.AEGIS_TOKEN;
+        const { startMcpServer } = await import('./mcp-server.js');
+        await startMcpServer(mcpPort, mcpAuth);
+        return; // stdio server runs until stdin closes
+    }
+    // Subcommand: create
+    if (args[0] === 'create') {
+        await handleCreate(args.slice(1));
+        process.exit(0);
+    }
+    // Port override from CLI
+    const portIdx = args.indexOf('--port');
+    if (portIdx !== -1 && args[portIdx + 1]) {
+        process.env.AEGIS_PORT = args[portIdx + 1];
+    }
+    // Check dependencies
+    const hasTmux = checkDependency('tmux', ['-V']);
+    const hasClaude = checkDependency('claude', ['--version']);
+    const tmuxVersion = hasTmux ? checkTmuxVersion(3, 3) : { ok: false, version: null };
+    if (!hasTmux) {
+        console.error(`
+  ❌ tmux not found.
+
+  Install tmux:
+    Ubuntu/Debian:  sudo apt install tmux
+    macOS:          brew install tmux
+    Windows:        winget install psmux
+    `);
+        process.exit(1);
+    }
+    if (!tmuxVersion.ok) {
+        console.error(`
+  ❌ Unsupported tmux version${tmuxVersion.version ? ` (${tmuxVersion.version})` : ''}.
+
+  Aegis requires tmux/psmux 3.3 or newer.
+  `);
+        process.exit(1);
+    }
+    if (!hasClaude) {
+        console.error(`
+  ⚠️  Claude Code CLI not found.
+
+  Install Claude Code:
+    curl -fsSL https://claude.ai/install.sh | bash
+
+  Sessions will fail to start without the 'claude' command.
+    `);
+        // Don't exit — server can still start, just sessions won't work
+    }
+    const port = parseIntSafe(process.env.AEGIS_PORT, 9100);
+    printBanner(port);
+    console.log(`  Dependencies:`);
+    console.log(`    tmux:   ${hasTmux ? '✅' : '❌'}`);
+    console.log(`    claude: ${hasClaude ? '✅' : '❌'}`);
+    console.log('');
+    // Start the server
+    await import('./server.js');
+}
+main().catch(err => {
+    console.error('Failed to start Aegis:', err);
+    process.exit(1);
+});