aegis-bridge 0.1.0

package/dist/validation.js

@@ -0,0 +1,415 @@
+/**
+ * validation.ts — Zod schemas for API request body validation.
+ *
+ * Issue #359: Centralized validation for all POST route bodies.
+ * Issue #435: Path traversal defense in validateWorkDir.
+ */
+import { z } from 'zod';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+/** Regex for UUID v4 format: 8-4-4-4-12 hex digits */
+export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** POST /v1/auth/keys */
+export const authKeySchema = z.object({
+    name: z.string().min(1),
+    rateLimit: z.number().int().positive().optional(),
+}).strict();
+/** Maximum length for user-supplied prompts/commands (Issue #411). */
+export const MAX_INPUT_LENGTH = 10_000;
+/** POST /v1/sessions/:id/send */
+export const sendMessageSchema = z.object({
+    text: z.string().min(1).max(MAX_INPUT_LENGTH),
+}).strict();
+/** POST /v1/sessions/:id/command */
+export const commandSchema = z.object({
+    command: z.string().min(1).max(MAX_INPUT_LENGTH),
+}).strict();
+/** POST /v1/sessions/:id/bash */
+export const bashSchema = z.object({
+    command: z.string().min(1).max(MAX_INPUT_LENGTH),
+}).strict();
+/** POST /v1/sessions/:id/screenshot */
+export const screenshotSchema = z.object({
+    url: z.string().min(1),
+    fullPage: z.boolean().optional(),
+    width: z.number().int().positive().max(7680).optional(),
+    height: z.number().int().positive().max(4320).optional(),
+}).strict();
+/** Webhook endpoint — validates structure of each webhook entry */
+export const webhookEndpointSchema = z.object({
+    url: z.string().min(1),
+    events: z.array(z.string()).optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    timeoutMs: z.number().int().positive().optional(),
+}).strict();
+/** POST /v1/hooks/:eventName — CC hook event payload (Issue #665). */
+export const hookBodySchema = z.object({
+    session_id: z.string().optional(),
+    agent_name: z.string().optional(),
+    agent_type: z.string().optional(),
+    tool_name: z.string().optional(),
+    tool_input: z.object({ command: z.string().optional() }).passthrough().optional(),
+    tool_use_id: z.string().optional(),
+    permission_prompt: z.string().optional(),
+    permission_mode: z.string().optional(),
+    hook_event_name: z.string().optional(),
+    model: z.string().optional(),
+    timestamp: z.string().optional(),
+    stop_reason: z.string().optional(),
+    cwd: z.string().optional(),
+    command: z.string().optional(),
+}).passthrough();
+/** POST /v1/sessions/:id/hooks/permission */
+export const permissionHookSchema = z.object({
+    session_id: z.string().optional(),
+    tool_name: z.string().optional(),
+    tool_input: z.unknown().optional(),
+    permission_mode: z.string().optional(),
+    hook_event_name: z.string().optional(),
+}).strict();
+/** POST /v1/sessions/:id/hooks/stop */
+export const stopHookSchema = z.object({
+    session_id: z.string().optional(),
+    stop_reason: z.string().optional(),
+    hook_event_name: z.string().optional(),
+}).strict();
+const batchSessionSpecSchema = z.object({
+    name: z.string().max(200).optional(),
+    workDir: z.string().min(1),
+    prompt: z.string().max(100_000).optional(),
+    permissionMode: z.enum(['default', 'bypassPermissions', 'plan', 'acceptEdits', 'dontAsk', 'auto']).optional(),
+    autoApprove: z.boolean().optional(),
+    stallThresholdMs: z.number().int().positive().max(3_600_000).optional(),
+});
+/** POST /v1/sessions/batch — max 50 sessions per batch */
+export const batchSessionSchema = z.object({
+    sessions: z.array(batchSessionSpecSchema).min(1).max(50),
+}).strict();
+const pipelineStageSchema = z.object({
+    name: z.string().min(1),
+    workDir: z.string().min(1).optional(),
+    prompt: z.string().min(1).max(MAX_INPUT_LENGTH),
+    dependsOn: z.array(z.string()).optional(),
+    permissionMode: z.enum(['default', 'bypassPermissions', 'plan', 'acceptEdits', 'dontAsk', 'auto']).optional(),
+    autoApprove: z.boolean().optional(),
+});
+/** POST /v1/pipelines */
+export const pipelineSchema = z.object({
+    name: z.string().min(1),
+    workDir: z.string().min(1),
+    stages: z.array(pipelineStageSchema).min(1),
+}).strict();
+/** POST /v1/handshake */
+export const handshakeRequestSchema = z.object({
+    protocolVersion: z.string().min(1),
+    clientCapabilities: z.array(z.string().min(1)).optional(),
+    clientVersion: z.string().min(1).optional(),
+}).strict();
+/** Clamp a numeric value to [min, max]. Returns default if input is NaN. */
+export function clamp(value, min, max, fallback) {
+    if (Number.isNaN(value))
+        return fallback;
+    return Math.max(min, Math.min(max, value));
+}
+/** Parse an env string to integer with NaN/isFinite guard. Returns fallback on failure. */
+export function parseIntSafe(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = parseInt(value, 10);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return parsed;
+}
+/** Validate that a string looks like a UUID. */
+export function isValidUUID(id) {
+    return UUID_REGEX.test(id);
+}
+// ── JSON.parse boundary validation (Issue #410) ──────────────────
+const UIStateEnum = z.enum([
+    'idle', 'working', 'compacting', 'context_warning', 'waiting_for_input',
+    'permission_prompt', 'bash_approval', 'plan_mode', 'ask_question',
+    'settings', 'error', 'unknown',
+]);
+/** Issue #700: Permission Policy Schema */
+export const permissionRuleSchema = z.object({
+    source: z.enum(['userSettings', 'projectSettings', 'localSettings', 'flagSettings', 'aegisApi']),
+    ruleBehavior: z.enum(['allow', 'deny', 'ask']),
+    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(),
+    windowId: z.string(),
+    windowName: z.string(),
+    workDir: z.string(),
+    claudeSessionId: z.string().optional(),
+    jsonlPath: z.string().optional(),
+    byteOffset: z.number(),
+    monitorOffset: z.number(),
+    status: UIStateEnum,
+    createdAt: z.number(),
+    lastActivity: z.number(),
+    stallThresholdMs: z.number(),
+    permissionStallMs: z.number().default(300_000),
+    permissionMode: z.enum(['default', 'bypassPermissions', 'plan', 'acceptEdits', 'dontAsk', 'auto']),
+    settingsPatched: z.boolean().optional(),
+    hookSettingsFile: z.string().optional(),
+    lastHookAt: z.number().optional(),
+    activeSubagents: z.array(z.string()).optional(),
+    permissionPromptAt: z.number().optional(),
+    permissionRespondedAt: z.number().optional(),
+    lastHookReceivedAt: z.number().optional(),
+    lastHookEventAt: z.number().optional(),
+    model: z.string().optional(),
+    lastDeadAt: z.number().optional(),
+    ccPid: z.number().optional(),
+    parentId: z.string().uuid().optional(),
+    children: z.array(z.string().uuid()).optional(),
+    permissionPolicy: z.array(z.object({
+        source: z.enum(['userSettings', 'projectSettings', 'localSettings', 'flagSettings', 'aegisApi']),
+        ruleBehavior: z.enum(['allow', 'deny', 'ask']),
+        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({
+    session_id: z.string(),
+    cwd: z.string(),
+    window_name: z.string(),
+    transcript_path: z.string().nullable().optional(),
+    permission_mode: z.string().nullable().optional(),
+    agent_id: z.string().nullable().optional(),
+    source: z.string().nullable().optional(),
+    agent_type: z.string().nullable().optional(),
+    model: z.string().nullable().optional(),
+    written_at: z.number(),
+    schema_version: z.number().int().positive().optional(),
+    expires_at: z.number().optional(),
+});
+/** Schema for session_map.json entries. */
+export const sessionMapSchema = z.record(z.string(), sessionMapEntrySchema);
+/** Incoming Stop/StopFailure hook payload (Issue #515). */
+export const stopPayloadSchema = z.object({
+    error: z.string().optional(),
+    message: z.string().optional(),
+    error_details: z.unknown().optional(),
+    last_assistant_message: z.unknown().optional(),
+    agent_id: z.string().optional(),
+    stop_reason: z.string().optional(),
+}).passthrough();
+/** Schema for stop_signals.json entries. */
+export const stopSignalsSchema = z.record(z.string(), z.object({
+    event: z.string().optional(),
+    timestamp: z.number().optional(),
+    error: z.unknown().optional(),
+    error_details: z.unknown().optional(),
+    last_assistant_message: z.unknown().optional(),
+    agent_id: z.unknown().optional(),
+    stop_reason: z.string().optional(),
+}));
+/** Schema for persisted auth keys store (Issue #506). */
+export const authStoreSchema = z.object({
+    keys: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        hash: z.string(),
+        createdAt: z.number(),
+        lastUsedAt: z.number(),
+        rateLimit: z.number(),
+    })),
+});
+/** Schema for sessions-index.json entries (Issue #506). */
+export const sessionsIndexSchema = z.object({
+    entries: z.array(z.object({
+        sessionId: z.string(),
+        fullPath: z.string(),
+    })).optional(),
+});
+/** Schema for persisted metrics file (Issue #506). */
+export const metricsFileSchema = z.object({
+    global: z.object({
+        sessionsCreated: z.number().optional(),
+        sessionsCompleted: z.number().optional(),
+        sessionsFailed: z.number().optional(),
+        totalMessages: z.number().optional(),
+        totalToolCalls: z.number().optional(),
+        autoApprovals: z.number().optional(),
+        webhooksSent: z.number().optional(),
+        webhooksFailed: z.number().optional(),
+        screenshotsTaken: z.number().optional(),
+        pipelinesCreated: z.number().optional(),
+        batchesCreated: z.number().optional(),
+        promptsSent: z.number().optional(),
+        promptsDelivered: z.number().optional(),
+        promptsFailed: z.number().optional(),
+    }).passthrough().optional(),
+    savedAt: z.number().optional(),
+}).passthrough();
+/** Schema for WebSocket inbound messages (Issue #506). */
+export const wsInboundMessageSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('input'), text: z.string() }).strict(),
+    z.object({ type: z.literal('resize'), cols: z.number().optional(), rows: z.number().optional() }).strict(),
+    z.object({ type: z.literal('auth'), token: z.string().optional() }).strict(),
+]);
+/** Schema for CC settings.json shape (Issue #506).
+ *  Permissive — only validates the fields Aegis cares about. */
+export const ccSettingsSchema = z.object({
+    permissions: z.object({
+        defaultMode: z.string().optional(),
+    }).passthrough().optional(),
+}).passthrough();
+/** Helper: extract error message from unknown catch value. */
+export function getErrorMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    return String(e);
+}
+// ── CC version validation (Issue #564) ─────────────────────────────────
+/** Minimum supported Claude Code version. */
+export const MIN_CC_VERSION = '2.1.80';
+/** Parse a semver string into [major, minor, patch], or null if invalid. */
+export function parseSemver(v) {
+    const match = v.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/**
+ * Compare two semver strings.
+ * Returns -1 if a < b, 0 if equal or either is unparseable (fails open), 1 if a > b.
+ */
+export function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] < pb[i])
+            return -1;
+        if (pa[i] > pb[i])
+            return 1;
+    }
+    return 0;
+}
+/** Extract version number from `claude --version` output. */
+export function extractCCVersion(output) {
+    const match = output.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+}
+/** Default safe base directories used when allowedWorkDirs is not configured.
+ *  Prevents sessions from running in system-critical directories. */
+function getDefaultSafeDirs() {
+    return [
+        os.homedir(),
+        '/tmp',
+        '/var/tmp',
+        process.cwd(),
+    ];
+}
+/** Returns true when any path segment resolves to "..".
+ *  Checks raw, separator-normalized, and percent-decoded forms to catch
+ *  encoded traversal like %2e%2e and mixed slash/backslash payloads. */
+export function containsTraversalSegment(inputPath) {
+    const hasTraversalInSegments = (candidate) => {
+        const normalizedSeparators = candidate.replace(/[\\/]+/g, '/');
+        const segments = normalizedSeparators.split('/');
+        return segments.some((segment) => segment === '..');
+    };
+    let candidate = inputPath;
+    for (let i = 0; i < 4; i++) {
+        if (hasTraversalInSegments(candidate))
+            return true;
+        let decoded;
+        try {
+            decoded = decodeURIComponent(candidate);
+        }
+        catch {
+            decoded = candidate;
+        }
+        if (decoded === candidate)
+            break;
+        candidate = decoded;
+    }
+    return false;
+}
+/** Normalize path for consistent boundary comparisons. */
+function normalizeForBoundaryCheck(inputPath) {
+    const resolved = path.normalize(path.resolve(inputPath));
+    const root = path.parse(resolved).root;
+    const trimmed = resolved.length > root.length
+        ? resolved.replace(/[\\/]+$/g, '')
+        : resolved;
+    return process.platform === 'win32' ? trimmed.toLowerCase() : trimmed;
+}
+/** Check whether `childPath` is equal to or under `parentPath`. */
+function isUnderOrEqual(childPath, parentPath) {
+    const normalizedChild = normalizeForBoundaryCheck(childPath);
+    const normalizedParent = normalizeForBoundaryCheck(parentPath);
+    if (normalizedChild === normalizedParent)
+        return true;
+    const relative = path.relative(normalizedParent, normalizedChild);
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+/** Validate workDir to prevent path traversal attacks (Issue #435).
+ *  1. Reject raw strings containing ".." before any normalization.
+ *  2. Resolve to absolute path and resolve symlinks via fs.realpath().
+ *  3. Verify the resolved path is under an allowed directory:
+ *     - If allowedWorkDirs is configured, use that list.
+ *     - Otherwise, use default safe dirs (home, /tmp, cwd).
+ *  Returns the resolved real path on success, or an error object on failure. */
+export async function validateWorkDir(workDir, allowedWorkDirs = []) {
+    if (typeof workDir !== 'string')
+        return { error: 'workDir must be a string', code: 'INVALID_WORKDIR' };
+    // Step 1: Reject path traversal in raw/mixed/decoded forms before resolution.
+    if (containsTraversalSegment(workDir)) {
+        return { error: 'workDir must not contain path traversal components (..)', code: 'INVALID_WORKDIR' };
+    }
+    // Step 2: Resolve to absolute path and follow symlinks.
+    const resolved = path.resolve(workDir);
+    let realPath;
+    try {
+        realPath = await fs.realpath(resolved);
+    }
+    catch { /* path does not exist on disk */
+        return { error: `workDir does not exist: ${resolved}`, code: 'INVALID_WORKDIR' };
+    }
+    // Step 3: Directory allowlist check.
+    const safeDirCandidates = allowedWorkDirs.length > 0
+        ? allowedWorkDirs.map((dir) => path.resolve(dir))
+        : getDefaultSafeDirs().map((dir) => path.resolve(dir));
+    const safeDirs = await Promise.all(safeDirCandidates.map(async (dir) => {
+        try {
+            return await fs.realpath(dir);
+        }
+        catch {
+            return dir;
+        }
+    }));
+    const allowed = safeDirs.some((dir) => isUnderOrEqual(realPath, dir));
+    if (!allowed) {
+        return { error: 'workDir is not in the allowed directories list', code: 'INVALID_WORKDIR' };
+    }
+    return realPath;
+}

package/dist/verification.d.ts

@@ -0,0 +1,2 @@
+import type { VerificationResult } from './events.js';
+export declare function runVerification(workDir: string, criticalOnly?: boolean): Promise<VerificationResult>;

package/dist/verification.js

@@ -0,0 +1,72 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { join } from 'path';
+import { statSync } from 'fs';
+const execAsync = promisify(exec);
+async function runCmd(cmd, { cwd, timeoutMs }) {
+    try {
+        const { stdout, stderr } = await execAsync(cmd, { cwd, timeout: Math.floor(timeoutMs / 1000), killSignal: 'SIGKILL' });
+        return { stdout, stderr, exitCode: 0 };
+    }
+    catch (e) {
+        const err = e;
+        return { stdout: err.stdout ?? '', stderr: err.stderr ?? '', exitCode: err.code ?? 1 };
+    }
+}
+export async function runVerification(workDir, criticalOnly = false) {
+    const start = Date.now();
+    const hasPackageJson = statSync(join(workDir, 'package.json')).isFile();
+    if (!hasPackageJson) {
+        return {
+            ok: false,
+            steps: [],
+            totalDurationMs: Date.now() - start,
+            summary: 'No package.json found — cannot verify',
+        };
+    }
+    const steps = [];
+    const timeoutMs = 120_000;
+    // Step 1: tsc
+    const tscStart = Date.now();
+    const tscResult = await runCmd('npx tsc --noEmit', { cwd: workDir, timeoutMs });
+    const tscDuration = Date.now() - tscStart;
+    const tscOk = tscResult.exitCode === 0;
+    steps.push({
+        name: 'tsc',
+        ok: tscOk,
+        durationMs: tscDuration,
+        output: tscResult.stdout.slice(0, 2000),
+        error: tscOk ? undefined : (tscResult.stderr || tscResult.stdout).slice(0, 2000),
+    });
+    // Step 2: build
+    const buildStart = Date.now();
+    const buildResult = await runCmd('npm run build', { cwd: workDir, timeoutMs });
+    const buildDuration = Date.now() - buildStart;
+    const buildOk = buildResult.exitCode === 0;
+    steps.push({
+        name: 'build',
+        ok: buildOk,
+        durationMs: buildDuration,
+        output: buildResult.stdout.slice(0, 2000),
+        error: buildOk ? undefined : (buildResult.stderr || buildResult.stdout).slice(0, 2000),
+    });
+    // Step 3: test (unless criticalOnly)
+    let testOk = true;
+    if (!criticalOnly) {
+        const testStart = Date.now();
+        const testResult = await runCmd('npm test', { cwd: workDir, timeoutMs: 180_000 });
+        const testDuration = Date.now() - testStart;
+        testOk = testResult.exitCode === 0;
+        steps.push({ name: 'test', ok: testOk, durationMs: testDuration, output: testResult.stdout.slice(0, 2000), error: testOk ? undefined : (testResult.stderr || testResult.stdout).slice(0, 2000) });
+    }
+    const ok = tscOk && buildOk && (!criticalOnly || testOk);
+    const totalDurationMs = Date.now() - start;
+    const summary = ok
+        ? `Verification passed: tsc ✅, build ✅${criticalOnly ? '' : ', test ✅'} (${totalDurationMs}ms)`
+        : `Verification failed: ${[
+            !tscOk ? 'tsc ❌' : '',
+            !buildOk ? 'build ❌' : '',
+            !criticalOnly && !testOk ? 'test ❌' : '',
+        ].filter(Boolean).join(', ')} (${totalDurationMs}ms)`;
+    return { ok, steps, totalDurationMs, summary };
+}

package/dist/worktree-lookup.d.ts

@@ -0,0 +1,24 @@
+/**
+ * worktree-lookup.ts — Worktree-aware session file discovery.
+ *
+ * Issue #884: Extends the single-directory findSessionFile with bounded fanout
+ * across sibling worktree project directories. Returns the freshest (most
+ * recently modified) matching JSONL file across all candidate dirs.
+ */
+/**
+ * Find the freshest JSONL file for a given sessionId across multiple
+ * Claude projects directories.
+ *
+ * Search order:
+ * 1. Primary directory (existing `claudeProjectsDir` — normal path)
+ * 2. Sibling directories (fanout, bounded by maxCandidates)
+ *
+ * Returns the path with the highest mtime, or null if not found.
+ * Silently ignores unreadable/missing directories.
+ *
+ * @param sessionId     Claude session UUID
+ * @param primaryDir    Primary `~/.claude/projects` directory (searched first)
+ * @param siblingDirs   Additional directories to search (fanout)
+ * @param maxCandidates Upper bound on sibling candidates to evaluate (default: 5)
+ */
+export declare function findSessionFileWithFanout(sessionId: string, primaryDir: string, siblingDirs: string[], maxCandidates?: number): Promise<string | null>;

package/dist/worktree-lookup.js

@@ -0,0 +1,71 @@
+/**
+ * worktree-lookup.ts — Worktree-aware session file discovery.
+ *
+ * Issue #884: Extends the single-directory findSessionFile with bounded fanout
+ * across sibling worktree project directories. Returns the freshest (most
+ * recently modified) matching JSONL file across all candidate dirs.
+ */
+import { stat, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/** Expand leading ~ to home directory. */
+function expandTilde(p) {
+    return p.startsWith('~') ? join(homedir(), p.slice(1)) : p;
+}
+/**
+ * Find the freshest JSONL file for a given sessionId across multiple
+ * Claude projects directories.
+ *
+ * Search order:
+ * 1. Primary directory (existing `claudeProjectsDir` — normal path)
+ * 2. Sibling directories (fanout, bounded by maxCandidates)
+ *
+ * Returns the path with the highest mtime, or null if not found.
+ * Silently ignores unreadable/missing directories.
+ *
+ * @param sessionId     Claude session UUID
+ * @param primaryDir    Primary `~/.claude/projects` directory (searched first)
+ * @param siblingDirs   Additional directories to search (fanout)
+ * @param maxCandidates Upper bound on sibling candidates to evaluate (default: 5)
+ */
+export async function findSessionFileWithFanout(sessionId, primaryDir, siblingDirs, maxCandidates = 5) {
+    const candidates = [];
+    // Helper: scan one projects dir for sessionId.jsonl files
+    async function scanDir(dir) {
+        const expanded = expandTilde(dir);
+        if (!existsSync(expanded))
+            return;
+        let entries;
+        try {
+            entries = await readdir(expanded, { withFileTypes: true, encoding: 'utf8' });
+        }
+        catch {
+            return; // unreadable directory — skip
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const jsonlPath = join(expanded, entry.name, `${sessionId}.jsonl`);
+            if (existsSync(jsonlPath)) {
+                try {
+                    const { mtimeMs } = await stat(jsonlPath);
+                    candidates.push({ path: jsonlPath, mtimeMs });
+                }
+                catch {
+                    // stat failed — entry may have been deleted between existsSync and stat
+                }
+            }
+        }
+    }
+    // Always scan primary first
+    await scanDir(primaryDir);
+    // Fanout to siblings (bounded)
+    const bounded = siblingDirs.slice(0, maxCandidates);
+    await Promise.all(bounded.map(d => scanDir(d)));
+    if (candidates.length === 0)
+        return null;
+    // Return path with the highest mtime (freshest)
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates[0].path;
+}

package/dist/ws-terminal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ws-terminal.ts — WebSocket endpoint for live terminal streaming.
+ *
+ * WS /v1/sessions/:id/terminal
+ *
+ * Protocol:
+ *   Server → Client: { type: "pane", content: "..." }
+ *   Server → Client: { type: "status", status: "idle" }
+ *   Server → Client: { type: "error", message: "..." }
+ *   Client → Server: { type: "input", text: "..." }
+ *   Client → Server: { type: "resize", cols: 80, rows: 24 }
+ *
+ * Security (Issue #303, #503):
+ *   - Auth validation via first-message handshake: client sends
+ *     { type: "auth", token: "..." } as first message (#503)
+ *   - Bearer header auth still works for non-browser clients
+ *   - 5s auth timeout — connection dropped if not authenticated
+ *   - Per-connection message rate limiting (10 msg/sec)
+ *   - Shared tmux capture polls (one per session, not per connection)
+ *   - Ping/pong keep-alive with dead connection detection
+ */
+import type { FastifyInstance } from 'fastify';
+import type { SessionManager } from './session.js';
+import type { TmuxManager } from './tmux.js';
+import type { AuthManager } from './auth.js';
+/** Reset all internal state (for testing). */
+export declare function _resetForTesting(): void;
+/** Get the number of active shared polls (for testing). */
+export declare function _activePollCount(): number;
+/** Get subscriber count for a session (for testing). */
+export declare function _subscriberCount(sessionId: string): number;
+export declare function registerWsTerminalRoute(app: FastifyInstance, sessions: SessionManager, tmux: TmuxManager, auth: AuthManager): void;