aegis-bridge 2.5.4 → 2.6.0

package/README.md

@@ -114,6 +114,7 @@ All endpoints under `/v1/`.
 | `POST` | `/v1/sessions/:id/interrupt` | Ctrl+C |
 | `DELETE` | `/v1/sessions/:id` | Kill session |
 | `POST` | `/v1/sessions/batch` | Batch create |
+| `POST` | `/v1/handshake` | Capability negotiation |
 | `POST` | `/v1/pipelines` | Create pipeline |
 
 <details>
@@ -124,6 +125,7 @@ All endpoints under `/v1/`.
 | `GET` | `/v1/sessions/:id/pane` | Raw terminal capture |
 | `GET` | `/v1/sessions/:id/health` | Health check with actionable hints |
 | `GET` | `/v1/sessions/:id/summary` | Condensed transcript summary |
+| `GET` | `/v1/sessions/:id/transcript/cursor` | Cursor-based transcript replay |
 | `POST` | `/v1/sessions/:id/screenshot` | Screenshot a URL (Playwright) |
 | `POST` | `/v1/sessions/:id/escape` | Send Escape |
 | `GET` | `/v1/pipelines` | List all pipelines |
@@ -175,6 +177,80 @@ Only **idle** sessions are reused. Working, stalled, or permission-prompt sessio
 
 </details>
 
+<details>
+<summary>Capability Handshake</summary>
+
+Before using advanced integration paths, clients can negotiate capabilities with Aegis via `POST /v1/handshake`. This prevents version-drift breakage.
+
+```bash
+curl -X POST http://localhost:9100/v1/handshake \
+  -H "Content-Type: application/json" \
+  -d '{"protocolVersion": "1", "clientCapabilities": ["session.create", "session.transcript.cursor"]}'
+```
+
+**Response** (200 OK when compatible):
+
+```json
+{
+  "protocolVersion": "1",
+  "serverCapabilities": ["session.create", "session.resume", "session.approve", "session.transcript", "session.transcript.cursor", "session.events.sse", "session.screenshot", "hooks.pre_tool_use", "hooks.post_tool_use", "hooks.notification", "hooks.stop", "swarm", "metrics"],
+  "negotiatedCapabilities": ["session.create", "session.transcript.cursor"],
+  "warnings": [],
+  "compatible": true
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `protocolVersion` | Server's protocol version (`"1"` currently) |
+| `serverCapabilities` | Full list of server-supported capabilities |
+| `negotiatedCapabilities` | Intersection of client + server capabilities |
+| `warnings` | Non-fatal issues (unknown caps, version skew) |
+| `compatible` | `true` (200) or `false` (409 Conflict) |
+
+Returns **409** if the client's `protocolVersion` is below the server minimum.
+
+</details>
+
+<details>
+<summary>Cursor-Based Transcript Replay</summary>
+
+Stable pagination for long transcripts that doesn't skip or duplicate messages under concurrent appends. Use instead of offset-based `/read` when you need reliable back-paging.
+
+```bash
+# Get the newest 50 messages
+curl http://localhost:9100/v1/sessions/abc123/transcript/cursor
+
+# Get the next page (pass oldest_id from previous response)
+curl "http://localhost:9100/v1/sessions/abc123/transcript/cursor?before_id=16&limit=50"
+
+# Filter by role
+curl "http://localhost:9100/v1/sessions/abc123/transcript/cursor?role=user"
+```
+
+**Query params:**
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `before_id` | (none) | Cursor ID to page before. Omit for newest entries. |
+| `limit` | `50` | Entries per page (1–200). |
+| `role` | (none) | Filter: `user`, `assistant`, or `system`. |
+
+**Response:**
+
+```json
+{
+  "messages": [...],
+  "has_more": true,
+  "oldest_id": 16,
+  "newest_id": 25
+}
+```
+
+Cursor IDs are stable — they won't shift when new messages are appended. Use `oldest_id` from one response as `before_id` in the next to page backwards without gaps or overlaps.
+
+</details>
+
 ---
 
 ### Telegram

package/dist/config.d.ts

@@ -53,6 +53,13 @@ export interface Config {
      *  Empty array = all directories allowed (backward compatible).
      *  Paths are resolved and symlink-resolved before checking. */
     allowedWorkDirs: string[];
+    /** Issue #884: Enable worktree-aware continuation metadata lookup (default: false).
+     *  When true, Aegis fans out to sibling worktree project dirs when the primary
+     *  directory lookup fails to find a session file. */
+    worktreeAwareContinuation: boolean;
+    /** Issue #884: Additional Claude projects directories to search during worktree fanout.
+     *  Paths are expanded (~) and checked for existence before searching. */
+    worktreeSiblingDirs: string[];
 }
 /** Compute stall threshold from env var or default (Issue #392).
  *  If CLAUDE_STREAM_IDLE_TIMEOUT_MS is set, uses Math.max(120000, parseInt(val) * 1.5).

package/dist/config.js

@@ -45,6 +45,8 @@ const defaults = {
     sseMaxConnections: 100,
     sseMaxPerIp: 10,
     allowedWorkDirs: [],
+    worktreeAwareContinuation: false,
+    worktreeSiblingDirs: [],
 };
 /** Parse CLI args for --config flag */
 function getConfigPathFromArgv() {

package/dist/handshake.d.ts

@@ -0,0 +1,40 @@
+/**
+ * handshake.ts — Capability handshake schema and negotiation for Aegis/Claude Code.
+ *
+ * Issue #885: Defines a formal protocolVersion + capabilities negotiation so
+ * that clients and Aegis can agree on supported feature set before using
+ * advanced integration paths. Prevents version-drift breakage.
+ */
+/** Current protocol version advertised by this Aegis build. */
+export declare const AEGIS_PROTOCOL_VERSION = "1";
+/** Minimum protocol version this Aegis build still accepts. */
+export declare const AEGIS_MIN_PROTOCOL_VERSION = "1";
+/**
+ * All capabilities Aegis supports in this build.
+ * Capabilities are additive; absence means the feature is unavailable/disabled.
+ */
+export declare const AEGIS_CAPABILITIES: readonly ["session.create", "session.resume", "session.approve", "session.transcript", "session.transcript.cursor", "session.events.sse", "session.screenshot", "hooks.pre_tool_use", "hooks.post_tool_use", "hooks.notification", "hooks.stop", "swarm", "metrics"];
+export type AegisCapability = (typeof AEGIS_CAPABILITIES)[number];
+/** Request body for POST /v1/handshake */
+export interface HandshakeRequest {
+    protocolVersion: string;
+    clientCapabilities?: string[];
+    clientVersion?: string;
+}
+/** Response shape for POST /v1/handshake */
+export interface HandshakeResponse {
+    protocolVersion: string;
+    serverCapabilities: AegisCapability[];
+    negotiatedCapabilities: AegisCapability[];
+    warnings: string[];
+    compatible: boolean;
+}
+/**
+ * Negotiate capabilities between a client request and this Aegis build.
+ *
+ * Rules:
+ * - If client protocolVersion < AEGIS_MIN_PROTOCOL_VERSION → not compatible, add warning, return empty negotiatedCapabilities
+ * - If client protocolVersion > AEGIS_PROTOCOL_VERSION → compatible but add forward-compat warning
+ * - negotiatedCapabilities = intersection of server caps and clientCapabilities (or all server caps if client sends none)
+ */
+export declare function negotiate(req: HandshakeRequest): HandshakeResponse;

package/dist/handshake.js

@@ -0,0 +1,90 @@
+/**
+ * handshake.ts — Capability handshake schema and negotiation for Aegis/Claude Code.
+ *
+ * Issue #885: Defines a formal protocolVersion + capabilities negotiation so
+ * that clients and Aegis can agree on supported feature set before using
+ * advanced integration paths. Prevents version-drift breakage.
+ */
+/** Current protocol version advertised by this Aegis build. */
+export const AEGIS_PROTOCOL_VERSION = '1';
+/** Minimum protocol version this Aegis build still accepts. */
+export const AEGIS_MIN_PROTOCOL_VERSION = '1';
+/**
+ * All capabilities Aegis supports in this build.
+ * Capabilities are additive; absence means the feature is unavailable/disabled.
+ */
+export const AEGIS_CAPABILITIES = [
+    'session.create',
+    'session.resume',
+    'session.approve',
+    'session.transcript',
+    'session.transcript.cursor', // Issue #883: cursor-based replay
+    'session.events.sse',
+    'session.screenshot',
+    'hooks.pre_tool_use',
+    'hooks.post_tool_use',
+    'hooks.notification',
+    'hooks.stop',
+    'swarm',
+    'metrics',
+];
+/**
+ * Negotiate capabilities between a client request and this Aegis build.
+ *
+ * Rules:
+ * - If client protocolVersion < AEGIS_MIN_PROTOCOL_VERSION → not compatible, add warning, return empty negotiatedCapabilities
+ * - If client protocolVersion > AEGIS_PROTOCOL_VERSION → compatible but add forward-compat warning
+ * - negotiatedCapabilities = intersection of server caps and clientCapabilities (or all server caps if client sends none)
+ */
+export function negotiate(req) {
+    const warnings = [];
+    const serverCapabilities = [...AEGIS_CAPABILITIES];
+    // Parse major version numbers for comparison
+    const clientMajor = parseInt(req.protocolVersion, 10);
+    const serverMajor = parseInt(AEGIS_PROTOCOL_VERSION, 10);
+    const minMajor = parseInt(AEGIS_MIN_PROTOCOL_VERSION, 10);
+    if (isNaN(clientMajor)) {
+        return {
+            protocolVersion: AEGIS_PROTOCOL_VERSION,
+            serverCapabilities,
+            negotiatedCapabilities: [],
+            warnings: [`Unrecognized protocolVersion format: "${req.protocolVersion}". Expected integer string.`],
+            compatible: false,
+        };
+    }
+    if (clientMajor < minMajor) {
+        return {
+            protocolVersion: AEGIS_PROTOCOL_VERSION,
+            serverCapabilities,
+            negotiatedCapabilities: [],
+            warnings: [
+                `Client protocolVersion ${req.protocolVersion} is below minimum supported version ${AEGIS_MIN_PROTOCOL_VERSION}. Upgrade required.`,
+            ],
+            compatible: false,
+        };
+    }
+    if (clientMajor > serverMajor) {
+        warnings.push(`Client protocolVersion ${req.protocolVersion} is newer than server version ${AEGIS_PROTOCOL_VERSION}. Some client features may be unavailable.`);
+    }
+    // Intersect: client declares what it supports; server only enables what it also supports
+    let negotiatedCapabilities;
+    if (!req.clientCapabilities || req.clientCapabilities.length === 0) {
+        // Client omitted capabilities → assume full server capability set
+        negotiatedCapabilities = serverCapabilities;
+    }
+    else {
+        const serverSet = new Set(serverCapabilities);
+        const unknown = req.clientCapabilities.filter(c => !serverSet.has(c));
+        if (unknown.length > 0) {
+            warnings.push(`Unknown client capabilities ignored: ${unknown.join(', ')}`);
+        }
+        negotiatedCapabilities = req.clientCapabilities.filter((c) => serverSet.has(c));
+    }
+    return {
+        protocolVersion: AEGIS_PROTOCOL_VERSION,
+        serverCapabilities,
+        negotiatedCapabilities,
+        warnings,
+        compatible: true,
+    };
+}

package/dist/monitor.js

@@ -11,6 +11,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { stopSignalsSchema } from './validation.js';
+import { suppressedCatch } from './suppress.js';
 /** Issue #89 L4: Debounce interval for status change broadcasts (ms). */
 const STATUS_CHANGE_DEBOUNCE_MS = 500;
 export const DEFAULT_MONITOR_CONFIG = {
@@ -124,8 +125,8 @@ export class SessionMonitor {
                 }
                 await this.checkSession(session);
             }
-            catch {
-                // Session may have been killed during poll
+            catch (e) {
+                suppressedCatch(e, 'monitor.checkSession');
             }
         }
         // Stall detection: run less frequently than message polling
@@ -372,7 +373,9 @@ export class SessionMonitor {
                 }
             }
         }
-        catch { /* ignore parse errors */ }
+        catch (e) {
+            suppressedCatch(e, 'monitor.checkStopSignals.parseEntry');
+        }
     }
     /** Issue #84: Handle new entries from the fs.watch-based JSONL watcher.
      *  Forwards messages to channels and updates stall tracking. */
@@ -555,8 +558,8 @@ export class SessionMonitor {
                 try {
                     await this.sessions.killSession(session.id);
                 }
-                catch {
-                    // Window already gone — that's fine, session is dead
+                catch (e) {
+                    suppressedCatch(e, 'monitor.checkDeadSessions.killSession');
                 }
             }
         }

package/dist/pipeline.d.ts

@@ -61,6 +61,7 @@ export interface PipelineState {
 export declare class PipelineManager {
     private sessions;
     private eventBus?;
+    private static readonly PIPELINE_RETRY_MAX_ATTEMPTS;
     private pipelines;
     private pipelineConfigs;
     private pollInterval;

package/dist/pipeline.js

@@ -5,9 +5,12 @@
  * sequential pipelines with stage dependencies.
  */
 import { getErrorMessage } from './validation.js';
+import { shouldRetry } from './error-categories.js';
+import { retryWithJitter } from './retry.js';
 export class PipelineManager {
     sessions;
     eventBus;
+    static PIPELINE_RETRY_MAX_ATTEMPTS = 3;
     pipelines = new Map();
     pipelineConfigs = new Map(); // #219: preserve original stage config
     pollInterval = null;
@@ -127,14 +130,20 @@ export class PipelineManager {
             if (!stageConfig)
                 continue;
             try {
-                const session = await this.sessions.createSession({
+                const session = await retryWithJitter(async () => this.sessions.createSession({
                     workDir: stageConfig.workDir || config.workDir,
                     name: `pipeline-${config.name}-${stage.name}`,
                     permissionMode: stageConfig.permissionMode,
                     autoApprove: stageConfig.autoApprove,
+                }), {
+                    maxAttempts: PipelineManager.PIPELINE_RETRY_MAX_ATTEMPTS,
+                    shouldRetry: (error) => shouldRetry(error),
                 });
                 if (stageConfig.prompt) {
-                    await this.sessions.sendInitialPrompt(session.id, stageConfig.prompt);
+                    await retryWithJitter(async () => this.sessions.sendInitialPrompt(session.id, stageConfig.prompt), {
+                        maxAttempts: PipelineManager.PIPELINE_RETRY_MAX_ATTEMPTS,
+                        shouldRetry: (error) => shouldRetry(error),
+                    });
                 }
                 stage.sessionId = session.id;
                 stage.status = 'running';

package/dist/retry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * retry.ts — shared retry helper with bounded exponential backoff + jitter.
+ */
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+export declare function retryWithJitter<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,34 @@
+/**
+ * retry.ts — shared retry helper with bounded exponential backoff + jitter.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeDelayMs(attempt, baseDelayMs, maxDelayMs) {
+    const exponential = Math.min(baseDelayMs * (2 ** (attempt - 1)), maxDelayMs);
+    const jitterMultiplier = 0.5 + (Math.random() * 0.5);
+    return Math.round(exponential * jitterMultiplier);
+}
+export async function retryWithJitter(fn, options = {}) {
+    const maxAttempts = options.maxAttempts ?? 3;
+    const baseDelayMs = options.baseDelayMs ?? 250;
+    const maxDelayMs = options.maxDelayMs ?? 3_000;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            const isLastAttempt = attempt >= maxAttempts;
+            const canRetry = options.shouldRetry ? options.shouldRetry(error, attempt) : true;
+            if (isLastAttempt || !canRetry) {
+                throw error;
+            }
+            const delayMs = computeDelayMs(attempt, baseDelayMs, maxDelayMs);
+            options.onRetry?.(error, attempt, delayMs);
+            await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}

package/dist/server.js

@@ -36,6 +36,7 @@ import { registerWsTerminalRoute } from './ws-terminal.js';
 import { SwarmMonitor } from './swarm-monitor.js';
 import { killAllSessions } from './signal-cleanup-helper.js';
 import { execFileSync } from 'node:child_process';
+import { negotiate } from './handshake.js';
 import { authKeySchema, sendMessageSchema, commandSchema, bashSchema, screenshotSchema, permissionHookSchema, stopHookSchema, batchSessionSchema, pipelineSchema, parseIntSafe, isValidUUID, } from './validation.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -70,8 +71,10 @@ async function handleInbound(cmd) {
                 await sessions.escape(cmd.sessionId);
                 break;
             case 'kill':
-                await channels.sessionEnded(makePayload('session.ended', cmd.sessionId, 'killed'));
+                // #842: killSession first, then notify — avoids race where channels
+                // reference a session that is still being destroyed.
                 await sessions.killSession(cmd.sessionId);
+                await channels.sessionEnded(makePayload('session.ended', cmd.sessionId, 'killed'));
                 monitor.removeSession(cmd.sessionId);
                 metrics.cleanupSession(cmd.sessionId);
                 break;
@@ -283,6 +286,18 @@ async function healthHandler() {
 }
 app.get('/v1/health', healthHandler);
 app.get('/health', healthHandler);
+app.post('/v1/handshake', async (req, reply) => {
+    const { protocolVersion, clientCapabilities, clientVersion } = req.body ?? {};
+    if (typeof protocolVersion !== 'string' || !protocolVersion.trim()) {
+        return reply.status(400).send({ error: 'protocolVersion is required' });
+    }
+    if (clientCapabilities !== undefined && !Array.isArray(clientCapabilities)) {
+        return reply.status(400).send({ error: 'clientCapabilities must be an array' });
+    }
+    const result = negotiate({ protocolVersion, clientCapabilities, clientVersion });
+    return reply.status(result.compatible ? 200 : 409).send(result);
+});
+// Issue #81: Swarm awareness
 // Issue #81: Swarm awareness — list all detected CC swarms and their teammates
 app.get('/v1/swarm', async () => {
     const result = await swarmMonitor.scan();
@@ -600,39 +615,29 @@ async function readMessagesHandler(req, reply) {
 }
 app.get('/v1/sessions/:id/read', readMessagesHandler);
 app.get('/sessions/:id/read', readMessagesHandler);
-// Approve
-async function approveHandler(req, reply) {
-    try {
-        await sessions.approve(req.params.id);
-        // Issue #87: Record permission response latency
-        const lat = sessions.getLatencyMetrics(req.params.id);
-        if (lat !== null && lat.permission_response_ms !== null) {
-            metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+function makePermissionHandler(action) {
+    return async (req, reply) => {
+        try {
+            const op = action === 'approve' ? sessions.approve.bind(sessions) : sessions.reject.bind(sessions);
+            await op(req.params.id);
+            // Issue #87: Record permission response latency
+            const lat = sessions.getLatencyMetrics(req.params.id);
+            if (lat !== null && lat.permission_response_ms !== null) {
+                metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+            }
+            return { ok: true };
         }
-        return { ok: true };
-    }
-    catch (e) {
-        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
-    }
-}
-app.post('/v1/sessions/:id/approve', approveHandler);
-app.post('/sessions/:id/approve', approveHandler);
-// Reject
-async function rejectHandler(req, reply) {
-    try {
-        await sessions.reject(req.params.id);
-        const lat = sessions.getLatencyMetrics(req.params.id);
-        if (lat !== null && lat.permission_response_ms !== null) {
-            metrics.recordPermissionResponse(req.params.id, lat.permission_response_ms);
+        catch (e) {
+            return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
         }
-        return { ok: true };
-    }
-    catch (e) {
-        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
-    }
+    };
 }
+const approveHandler = makePermissionHandler('approve');
+const rejectHandler = makePermissionHandler('reject');
 app.post('/v1/sessions/:id/reject', rejectHandler);
 app.post('/sessions/:id/reject', rejectHandler);
+app.post('/v1/sessions/:id/approve', approveHandler);
+app.post('/sessions/:id/approve', approveHandler);
 // Issue #336: Answer pending AskUserQuestion
 app.post('/v1/sessions/:id/answer', async (req, reply) => {
     const { questionId, answer } = req.body || {};
@@ -678,9 +683,11 @@ async function killSessionHandler(req, reply) {
         return reply.status(404).send({ error: 'Session not found' });
     }
     try {
+        // #842: killSession first, then notify — avoids race where channels
+        // reference a session that is still being destroyed.
+        await sessions.killSession(req.params.id);
         eventBus.emitEnded(req.params.id, 'killed');
         await channels.sessionEnded(makePayload('session.ended', req.params.id, 'killed'));
-        await sessions.killSession(req.params.id);
         monitor.removeSession(req.params.id);
         metrics.cleanupSession(req.params.id);
         return { ok: true };
@@ -762,6 +769,27 @@ app.get('/v1/sessions/:id/transcript', async (req, reply) => {
         return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
     }
 });
+// Cursor-based transcript replay (Issue #883): stable pagination under concurrent appends.
+// GET /v1/sessions/:id/transcript/cursor?before_id=N&limit=50&role=user|assistant|system
+app.get('/v1/sessions/:id/transcript/cursor', async (req, reply) => {
+    try {
+        const rawBeforeId = req.query.before_id;
+        const beforeId = rawBeforeId !== undefined ? parseInt(rawBeforeId, 10) : undefined;
+        if (beforeId !== undefined && (!Number.isInteger(beforeId) || beforeId < 1)) {
+            return reply.status(400).send({ error: 'before_id must be a positive integer' });
+        }
+        const limit = Math.min(200, Math.max(1, parseInt(req.query.limit || '50', 10) || 50));
+        const allowedRoles = new Set(['user', 'assistant', 'system']);
+        const roleFilter = req.query.role;
+        if (roleFilter && !allowedRoles.has(roleFilter)) {
+            return reply.status(400).send({ error: `Invalid role filter: ${roleFilter}. Allowed values: user, assistant, system` });
+        }
+        return await sessions.readTranscriptCursor(req.params.id, beforeId, limit, roleFilter);
+    }
+    catch (e) {
+        return reply.status(404).send({ error: e instanceof Error ? e.message : String(e) });
+    }
+});
 // Screenshot capture (Issue #22)
 async function screenshotHandler(req, reply) {
     const parsed = screenshotSchema.safeParse(req.body);
@@ -997,14 +1025,16 @@ async function reapStaleSessions(maxAgeMs) {
             const ageMin = Math.round(age / 60000);
             console.log(`Reaper: killing session ${session.windowName} (${session.id.slice(0, 8)}) — age ${ageMin}min`);
             try {
+                // #842: killSession first, then notify — avoids race where channels
+                // reference a session that is still being destroyed.
+                await sessions.killSession(session.id);
+                eventBus.cleanupSession(session.id);
                 await channels.sessionEnded({
                     event: 'session.ended',
                     timestamp: new Date().toISOString(),
                     session: { id: session.id, name: session.windowName, workDir: session.workDir },
                     detail: `Auto-killed: exceeded ${maxAgeMs / 3600000}h time limit`,
                 });
-                eventBus.cleanupSession(session.id);
-                await sessions.killSession(session.id);
                 monitor.removeSession(session.id);
                 metrics.cleanupSession(session.id);
             }

package/dist/session.d.ts

@@ -65,8 +65,14 @@ export declare class SessionManager {
     private pendingQuestions;
     private static readonly MAX_CACHE_ENTRIES_PER_SESSION;
     private parsedEntriesCache;
-    private sessionAcquireMutex;
+    private readonly sessionAcquireMutex;
     constructor(tmux: TmuxManager, config: Config);
+    /**
+     * Issue #884: Worktree-aware session file lookup.
+     * When `worktreeAwareContinuation` is enabled, fans out to sibling worktree
+     * project dirs; otherwise falls back to the existing single-directory search.
+     */
+    private findSessionFileMaybeWorktree;
     /** Validate that parsed data looks like a valid SessionState. */
     private isValidState;
     /** Clean up stale .tmp files left by crashed writes. */
@@ -164,7 +170,7 @@ export declare class SessionManager {
      *  Returns the most recently active idle session, or null if none found.
      *  Used to resume existing sessions instead of creating duplicates.
      *  Issue #636: Verifies tmux window is still alive before returning.
-     *  Issue #840: Atomically acquires the session under a mutex to prevent TOCTOU race. */
+     *  Issue #840/#880: Atomically acquires the session under a mutex to prevent TOCTOU race. */
     findIdleSessionByWorkDir(workDir: string): Promise<SessionInfo | null>;
     /** Release a session claim after the reuse path completes (success or failure). */
     releaseSessionClaim(id: string): void;
@@ -298,6 +304,23 @@ export declare class SessionManager {
         limit: number;
         hasMore: boolean;
     }>;
+    /**
+     * Cursor-based transcript read — stable under concurrent appends.
+     *
+     * Uses 1-based sequential entry indices as cursors.
+     * - `beforeId`: exclusive upper bound (fetch entries with index < beforeId).
+     *               If omitted, fetch the newest `limit` entries.
+     * - `limit`: max entries to return (capped at 200).
+     * - Returns entries in ascending order (oldest first) within the window.
+     */
+    readTranscriptCursor(id: string, beforeId?: number, limit?: number, roleFilter?: 'user' | 'assistant' | 'system'): Promise<{
+        messages: (ParsedEntry & {
+            _cursor_id: number;
+        })[];
+        has_more: boolean;
+        oldest_id: number | null;
+        newest_id: number | null;
+    }>;
     /** #405: Clean up all tracking maps for a session to prevent memory leaks. */
     private cleanupSession;
     /** Kill a session. */

package/dist/session.js

@@ -9,11 +9,13 @@ import { existsSync, unlinkSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { findSessionFile, readNewEntries } from './transcript.js';
+import { findSessionFileWithFanout } from './worktree-lookup.js';
 import { detectUIState, extractInteractiveContent, parseStatusLine } from './terminal-parser.js';
 import { computeStallThreshold } from './config.js';
 import { neutralizeBypassPermissions, restoreSettings, cleanOrphanedBackup } from './permission-guard.js';
 import { persistedStateSchema, sessionMapSchema } from './validation.js';
 import { writeHookSettingsFile, cleanupHookSettingsFile } from './hook-settings.js';
+import { Mutex } from 'async-mutex';
 /** Convert parsed JSON arrays to Sets for activeSubagents (#668). */
 function hydrateSessions(raw) {
     const sessions = {};
@@ -62,14 +64,25 @@ export class SessionManager {
     // #424: Evict oldest entries when cache exceeds max to prevent unbounded growth
     static MAX_CACHE_ENTRIES_PER_SESSION = 10_000;
     parsedEntriesCache = new Map();
-    // Issue #840: Mutex to prevent TOCTOU race in findIdleSessionByWorkDir
-    sessionAcquireMutex = Promise.resolve();
+    // Issue #840/#880: Explicit mutex to prevent TOCTOU races in session acquisition.
+    sessionAcquireMutex = new Mutex();
     constructor(tmux, config) {
         this.tmux = tmux;
         this.config = config;
         this.stateFile = join(config.stateDir, 'state.json');
         this.sessionMapFile = join(config.stateDir, 'session_map.json');
     }
+    /**
+     * Issue #884: Worktree-aware session file lookup.
+     * When `worktreeAwareContinuation` is enabled, fans out to sibling worktree
+     * project dirs; otherwise falls back to the existing single-directory search.
+     */
+    findSessionFileMaybeWorktree(sessionId) {
+        if (this.config.worktreeAwareContinuation && this.config.worktreeSiblingDirs.length > 0) {
+            return findSessionFileWithFanout(sessionId, this.config.claudeProjectsDir, this.config.worktreeSiblingDirs);
+        }
+        return findSessionFile(sessionId, this.config.claudeProjectsDir);
+    }
     /** Validate that parsed data looks like a valid SessionState. */
     isValidState(data) {
         if (typeof data !== 'object' || data === null)
@@ -705,15 +718,9 @@ export class SessionManager {
      *  Returns the most recently active idle session, or null if none found.
      *  Used to resume existing sessions instead of creating duplicates.
      *  Issue #636: Verifies tmux window is still alive before returning.
-     *  Issue #840: Atomically acquires the session under a mutex to prevent TOCTOU race. */
+     *  Issue #840/#880: Atomically acquires the session under a mutex to prevent TOCTOU race. */
     async findIdleSessionByWorkDir(workDir) {
-        // Issue #840: Acquire mutex — chain onto the previous operation
-        let release;
-        const lock = new Promise((resolve) => { release = resolve; });
-        const previous = this.sessionAcquireMutex;
-        this.sessionAcquireMutex = lock;
-        await previous.catch(() => { }); // tolerate prior rejection
-        try {
+        return this.sessionAcquireMutex.runExclusive(async () => {
             const candidates = Object.values(this.state.sessions).filter((s) => s.workDir === workDir && s.status === 'idle');
             if (candidates.length === 0)
                 return null;
@@ -729,10 +736,7 @@ export class SessionManager {
                 }
             }
             return null;
-        }
-        finally {
-            release();
-        }
+        });
     }
     /** Release a session claim after the reuse path completes (success or failure). */
     releaseSessionClaim(id) {
@@ -1040,9 +1044,9 @@ export class SessionManager {
         const interactive = extractInteractiveContent(paneText);
         session.status = status;
         session.lastActivity = Date.now();
-        // Try to find JSONL if we don't have it yet
+        // Try to find JSONL if we don't have it yet (Issue #884: worktree-aware)
         if (!session.jsonlPath && session.claudeSessionId) {
-            const path = await findSessionFile(session.claudeSessionId, this.config.claudeProjectsDir);
+            const path = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
             if (path) {
                 session.jsonlPath = path;
                 session.byteOffset = 0;
@@ -1081,9 +1085,9 @@ export class SessionManager {
         const statusText = parseStatusLine(paneText);
         const interactive = extractInteractiveContent(paneText);
         session.status = status;
-        // Try to find JSONL if we don't have it yet
+        // Try to find JSONL if we don't have it yet (Issue #884: worktree-aware)
         if (!session.jsonlPath && session.claudeSessionId) {
-            const path = await findSessionFile(session.claudeSessionId, this.config.claudeProjectsDir);
+            const path = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
             if (path) {
                 session.jsonlPath = path;
                 session.monitorOffset = 0;
@@ -1171,9 +1175,9 @@ export class SessionManager {
         const session = this.state.sessions[id];
         if (!session)
             throw new Error(`Session ${id} not found`);
-        // Discover JSONL path if not yet known
+        // Discover JSONL path if not yet known (Issue #884: worktree-aware)
         if (!session.jsonlPath && session.claudeSessionId) {
-            const path = await findSessionFile(session.claudeSessionId, this.config.claudeProjectsDir);
+            const path = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
             if (path) {
                 session.jsonlPath = path;
                 session.byteOffset = 0;
@@ -1197,6 +1201,50 @@ export class SessionManager {
             hasMore,
         };
     }
+    /**
+     * Cursor-based transcript read — stable under concurrent appends.
+     *
+     * Uses 1-based sequential entry indices as cursors.
+     * - `beforeId`: exclusive upper bound (fetch entries with index < beforeId).
+     *               If omitted, fetch the newest `limit` entries.
+     * - `limit`: max entries to return (capped at 200).
+     * - Returns entries in ascending order (oldest first) within the window.
+     */
+    async readTranscriptCursor(id, beforeId, limit = 50, roleFilter) {
+        const session = this.state.sessions[id];
+        if (!session)
+            throw new Error(`Session ${id} not found`);
+        // Discover JSONL path if not yet known
+        if (!session.jsonlPath && session.claudeSessionId) {
+            const path = await findSessionFile(session.claudeSessionId, this.config.claudeProjectsDir);
+            if (path) {
+                session.jsonlPath = path;
+                session.byteOffset = 0;
+            }
+        }
+        let allEntries = await this.getCachedEntries(session);
+        if (roleFilter) {
+            allEntries = allEntries.filter(e => e.role === roleFilter);
+        }
+        const total = allEntries.length;
+        const clampedLimit = Math.min(200, Math.max(1, limit));
+        // Determine exclusive upper index (0-based)
+        const upperExclusive = beforeId !== undefined
+            ? Math.min(beforeId - 1, total) // beforeId is 1-based
+            : total;
+        const lowerInclusive = Math.max(0, upperExclusive - clampedLimit);
+        const slice = allEntries.slice(lowerInclusive, upperExclusive);
+        const messages = slice.map((entry, i) => ({
+            ...entry,
+            _cursor_id: lowerInclusive + i + 1, // 1-based stable index
+        }));
+        return {
+            messages,
+            has_more: lowerInclusive > 0,
+            oldest_id: messages.length > 0 ? messages[0]._cursor_id : null,
+            newest_id: messages.length > 0 ? messages[messages.length - 1]._cursor_id : null,
+        };
+    }
     /** #405: Clean up all tracking maps for a session to prevent memory leaks. */
     cleanupSession(id) {
         // Clear polling timers (both regular and filesystem discovery variants)
@@ -1340,9 +1388,9 @@ export class SessionManager {
             }
             try {
                 await this.syncSessionMap();
-                // If we have claudeSessionId but no jsonlPath, try finding it
+                // If we have claudeSessionId but no jsonlPath, try finding it (Issue #884: worktree-aware)
                 if (session.claudeSessionId && !session.jsonlPath) {
-                    const jsonlPath = await findSessionFile(session.claudeSessionId, this.config.claudeProjectsDir);
+                    const jsonlPath = await this.findSessionFileMaybeWorktree(session.claudeSessionId);
                     if (jsonlPath) {
                         session.jsonlPath = jsonlPath;
                         session.byteOffset = 0;

package/dist/suppress.d.ts

@@ -0,0 +1,33 @@
+/**
+ * suppress.ts — Explicit suppression predicate for expected runtime races.
+ *
+ * Issue #882: Replaces silent empty catches with a documented, testable
+ * suppression contract. Suppressible errors (expected races, killed sessions,
+ * missing tmux panes) are forwarded as rate-limited diagnostics events.
+ * Non-suppressible errors are surfaced at warn level.
+ */
+/** Contexts where suppressible races may occur. */
+export type SuppressContext = 'monitor.checkSession' | 'monitor.checkDeadSessions.killSession' | 'monitor.checkStopSignals.parseEntry' | 'session.cleanup' | 'tmux.capturePane' | string;
+/** Exported for tests — clears all rate-limit counters. */
+export declare function _resetSuppressRateLimit(): void;
+/**
+ * Returns true if the error is an expected transient race that
+ * should be swallowed without surfacing a warning.
+ *
+ * Categories of suppressible errors:
+ * - Session killed while in-flight (SESSION_NOT_FOUND-class messages)
+ * - File not found (ENOENT) — session JSONL removed after kill
+ * - Tmux pane/window gone — dead-session race
+ * - SyntaxError from truncated JSONL reads during rotation
+ */
+export declare function isSuppressible(error: unknown, _context: SuppressContext): boolean;
+/**
+ * Handle a caught error using the explicit suppression policy.
+ *
+ * - Suppressible errors: console.debug with rate limiting (max 10/min per context).
+ * - Non-suppressible errors: console.warn — always visible.
+ *
+ * Does NOT rethrow. Call isSuppressible() directly if you need rethrow control.
+ */
+export declare function suppressedCatch(error: unknown, context: SuppressContext): void;
+export declare function _errorMessage(error: unknown): string;

package/dist/suppress.js

@@ -0,0 +1,79 @@
+/**
+ * suppress.ts — Explicit suppression predicate for expected runtime races.
+ *
+ * Issue #882: Replaces silent empty catches with a documented, testable
+ * suppression contract. Suppressible errors (expected races, killed sessions,
+ * missing tmux panes) are forwarded as rate-limited diagnostics events.
+ * Non-suppressible errors are surfaced at warn level.
+ */
+/** Rate-limit state: max N suppressed debug events per context per minute. */
+const suppressRateLimit = new Map();
+/** Exported for tests — clears all rate-limit counters. */
+export function _resetSuppressRateLimit() {
+    suppressRateLimit.clear();
+}
+const SUPPRESS_MAX_PER_MINUTE = 10;
+/**
+ * Returns true if the error is an expected transient race that
+ * should be swallowed without surfacing a warning.
+ *
+ * Categories of suppressible errors:
+ * - Session killed while in-flight (SESSION_NOT_FOUND-class messages)
+ * - File not found (ENOENT) — session JSONL removed after kill
+ * - Tmux pane/window gone — dead-session race
+ * - SyntaxError from truncated JSONL reads during rotation
+ */
+export function isSuppressible(error, _context) {
+    if (error instanceof SyntaxError)
+        return true;
+    if (error instanceof Error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return true;
+        const msg = error.message.toLowerCase();
+        if (msg.includes('session not found'))
+            return true;
+        if (msg.includes('no session with id'))
+            return true;
+        if (msg.includes('no such window'))
+            return true;
+        if (msg.includes('no such pane'))
+            return true;
+        if (msg.includes('no such session'))
+            return true;
+        if (msg.includes("can't find window"))
+            return true;
+        if (msg.includes('window already dead'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Handle a caught error using the explicit suppression policy.
+ *
+ * - Suppressible errors: console.debug with rate limiting (max 10/min per context).
+ * - Non-suppressible errors: console.warn — always visible.
+ *
+ * Does NOT rethrow. Call isSuppressible() directly if you need rethrow control.
+ */
+export function suppressedCatch(error, context) {
+    if (isSuppressible(error, context)) {
+        const now = Date.now();
+        const state = suppressRateLimit.get(context);
+        if (!state || now >= state.resetAt) {
+            suppressRateLimit.set(context, { count: 1, resetAt: now + 60_000 });
+            console.debug(`[suppress] ${context}: ${_errorMessage(error)}`);
+        }
+        else if (state.count < SUPPRESS_MAX_PER_MINUTE) {
+            state.count++;
+            console.debug(`[suppress] ${context}: ${_errorMessage(error)}`);
+        }
+        // rate limit exceeded for this window — drop silently
+    }
+    else {
+        console.warn(`[unexpected] ${context}: ${_errorMessage(error)}`, error);
+    }
+}
+export function _errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-bridge",
-  "version": "2.5.4",
+  "version": "2.6.0",
   "type": "module",
   "description": "Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship.",
   "main": "dist/server.js",
@@ -48,6 +48,7 @@
     "@fastify/static": "^9.0.0",
     "@fastify/websocket": "^11.2.0",
     "@modelcontextprotocol/sdk": "^1.28.0",
+    "async-mutex": "^0.5.0",
     "fastify": "^5.8.2",
     "zod": "^4.3.6"
   },