aegis-bridge 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,90 @@
+/**
+ * config.ts — Configuration loader for Aegis.
+ *
+ * Priority (highest to lowest):
+ * 1. CLI argument --config <path>
+ * 2. ./aegis.config.json (cwd) — fallback: ./manus.config.json
+ * 3. ~/.aegis/config.json — fallback: ~/.manus/config.json
+ * 4. Defaults
+ *
+ * Environment variables override config file values.
+ * AEGIS_* env vars take priority; MANUS_* still supported for backward compat.
+ */
+export interface Config {
+    /** HTTP server port */
+    port: number;
+    /** HTTP server host */
+    host: string;
+    /** Bearer auth token (empty = no auth) */
+    authToken: string;
+    /** tmux session name */
+    tmuxSession: string;
+    /** Directory for bridge state (state.json, session_map.json) */
+    stateDir: string;
+    /** Directory where Claude Code stores projects (~/.claude/projects) */
+    claudeProjectsDir: string;
+    /** Max session age in milliseconds */
+    maxSessionAgeMs: number;
+    /** Reaper check interval in milliseconds */
+    reaperIntervalMs: number;
+    /** Continuation pointer TTL in milliseconds (Issue #900). */
+    continuationPointerTtlMs: number;
+    /** Telegram bot token */
+    tgBotToken: string;
+    /** Telegram group chat ID */
+    tgGroupId: string;
+    /** Allowed Telegram user IDs for inbound commands (empty = allow all) */
+    tgAllowedUsers: number[];
+    /** TTL for Telegram forum topics after session end, in milliseconds. */
+    tgTopicTtlMs: number;
+    /** Webhook URLs (comma-separated or array) */
+    webhooks: string[];
+    /** Default env vars injected into every CC session (e.g. model overrides, API keys).
+     *  Per-session env vars from the API merge on top (per-session wins). */
+    defaultSessionEnv: Record<string, string>;
+    /** Default permission mode for new sessions (default: "bypassPermissions").
+     *  Aegis is headless — there is no human at the TTY to approve prompts.
+     *  Set explicitly to "default" if approval gating is needed.
+     *  Values: "default" | "plan" | "acceptEdits" | "bypassPermissions" | "dontAsk" | "auto" */
+    defaultPermissionMode: string;
+    /** Stall threshold for monitor (ms). */
+    stallThresholdMs: number;
+    /** Maximum total concurrent SSE connections (default: 100). Env: AEGIS_SSE_MAX_CONNECTIONS */
+    sseMaxConnections: number;
+    /** Maximum concurrent SSE connections per client IP (default: 10). Env: AEGIS_SSE_MAX_PER_IP */
+    sseMaxPerIp: number;
+    /** Allowed working directories for session creation (Issue #349).
+     *  Empty array = all directories allowed (backward compatible).
+     *  Paths are resolved and symlink-resolved before checking. */
+    allowedWorkDirs: string[];
+    /** Memory bridge: key/value store for cross-session context (default: disabled). */
+    memoryBridge: {
+        enabled: boolean;
+        persistPath?: string;
+        reaperIntervalMs?: number;
+    };
+    /** 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[];
+    /** Issue #740: Verification Protocol — auto run quality gate after session ends.
+     *  When enabled, Aegis runs tsc + build + test after a Stop hook and emits
+     *  results via SSE (event: 'verification'). */
+    verificationProtocol: {
+        /** Auto-run verification when Stop hook fires (default: false). */
+        autoVerifyOnStop: boolean;
+        /** Run only critical checks: tsc + build (skip slow tests). Default: false = full. */
+        criticalOnly: boolean;
+    };
+}
+/** 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).
+ *  Otherwise defaults to 2 minutes (120000ms). */
+export declare function computeStallThreshold(): number;
+/** Load and merge configuration from all sources */
+export declare function loadConfig(): Promise<Config>;
+/** Get config without async file loading (for tests or synchronous contexts) */
+export declare function getConfig(): Config;

package/dist/config.js

@@ -0,0 +1,214 @@
+/**
+ * config.ts — Configuration loader for Aegis.
+ *
+ * Priority (highest to lowest):
+ * 1. CLI argument --config <path>
+ * 2. ./aegis.config.json (cwd) — fallback: ./manus.config.json
+ * 3. ~/.aegis/config.json — fallback: ~/.manus/config.json
+ * 4. Defaults
+ *
+ * Environment variables override config file values.
+ * AEGIS_* env vars take priority; MANUS_* still supported for backward compat.
+ */
+import { readFile, realpath } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseIntSafe } from './validation.js';
+/** 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).
+ *  Otherwise defaults to 2 minutes (120000ms). */
+export function computeStallThreshold() {
+    const env = process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS;
+    if (env) {
+        return Math.max(120_000, Math.round(parseInt(env, 10) * 1.5));
+    }
+    return 2 * 60 * 1000;
+}
+/** Default configuration values */
+const defaults = {
+    port: 9100,
+    host: '127.0.0.1',
+    authToken: '',
+    tmuxSession: 'aegis',
+    stateDir: join(homedir(), '.aegis'),
+    claudeProjectsDir: join(homedir(), '.claude', 'projects'),
+    maxSessionAgeMs: 2 * 60 * 60 * 1000, // 2 hours
+    reaperIntervalMs: 5 * 60 * 1000, // 5 minutes
+    continuationPointerTtlMs: 24 * 60 * 60 * 1000, // 24 hours
+    tgBotToken: '',
+    tgGroupId: '',
+    tgAllowedUsers: [],
+    tgTopicTtlMs: 24 * 60 * 60 * 1000,
+    webhooks: [],
+    defaultSessionEnv: {},
+    defaultPermissionMode: 'default',
+    stallThresholdMs: computeStallThreshold(),
+    sseMaxConnections: 100,
+    sseMaxPerIp: 10,
+    allowedWorkDirs: [],
+    worktreeAwareContinuation: false,
+    memoryBridge: { enabled: false },
+    worktreeSiblingDirs: [],
+    verificationProtocol: { autoVerifyOnStop: false, criticalOnly: false },
+};
+/** Parse CLI args for --config flag */
+function getConfigPathFromArgv() {
+    const idx = process.argv.indexOf('--config');
+    if (idx !== -1 && idx + 1 < process.argv.length) {
+        return resolve(process.argv[idx + 1]);
+    }
+    return null;
+}
+/** Find and load config file from possible locations.
+ *  Checks aegis paths first, falls back to manus paths for backward compat.
+ */
+async function loadConfigFile() {
+    const locations = [
+        getConfigPathFromArgv(),
+        // New aegis paths (preferred)
+        resolve('aegis.config.json'),
+        join(homedir(), '.aegis', 'config.json'),
+        // Legacy manus paths (backward compat)
+        resolve('manus.config.json'),
+        join(homedir(), '.manus', 'config.json'),
+    ].filter(Boolean);
+    for (const path of locations) {
+        if (existsSync(path)) {
+            try {
+                const data = await readFile(path, 'utf-8');
+                const parsed = JSON.parse(data);
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                    console.warn(`Config file ${path} is not a JSON object, ignoring`);
+                    continue;
+                }
+                // Expand ~ in paths
+                if (typeof parsed.stateDir === 'string') {
+                    parsed.stateDir = expandTilde(parsed.stateDir);
+                }
+                if (typeof parsed.claudeProjectsDir === 'string') {
+                    parsed.claudeProjectsDir = expandTilde(parsed.claudeProjectsDir);
+                }
+                // Log if using legacy path
+                if (path.includes('manus')) {
+                    console.log(`Config: loaded from legacy path ${path} — consider migrating to aegis paths`);
+                }
+                return parsed;
+            }
+            catch (e) {
+                console.warn(`Failed to parse config file ${path}:`, e);
+            }
+        }
+    }
+    return {};
+}
+/** Expand ~ to homedir in path strings */
+function expandTilde(path) {
+    if (path.startsWith('~/')) {
+        return join(homedir(), path.slice(2));
+    }
+    return path;
+}
+/** Apply environment variable overrides.
+ *  AEGIS_* vars take priority over MANUS_* (backward compat).
+ */
+function applyEnvOverrides(config) {
+    // AEGIS_* (new, preferred) and MANUS_* (legacy, backward compat)
+    const envMappings = [
+        { aegis: 'AEGIS_PORT', manus: 'MANUS_PORT', key: 'port' },
+        { aegis: 'AEGIS_HOST', manus: 'MANUS_HOST', key: 'host' },
+        { aegis: 'AEGIS_AUTH_TOKEN', manus: 'MANUS_AUTH_TOKEN', key: 'authToken' },
+        { aegis: 'AEGIS_TMUX_SESSION', manus: 'MANUS_TMUX_SESSION', key: 'tmuxSession' },
+        { aegis: 'AEGIS_STATE_DIR', manus: 'MANUS_STATE_DIR', key: 'stateDir' },
+        { aegis: 'AEGIS_CLAUDE_PROJECTS_DIR', manus: 'MANUS_CLAUDE_PROJECTS_DIR', key: 'claudeProjectsDir' },
+        { aegis: 'AEGIS_MAX_SESSION_AGE_MS', manus: 'MANUS_MAX_SESSION_AGE_MS', key: 'maxSessionAgeMs' },
+        { aegis: 'AEGIS_REAPER_INTERVAL_MS', manus: 'MANUS_REAPER_INTERVAL_MS', key: 'reaperIntervalMs' },
+        { aegis: 'AEGIS_CONTINUATION_POINTER_TTL_MS', manus: 'MANUS_CONTINUATION_POINTER_TTL_MS', key: 'continuationPointerTtlMs' },
+        { aegis: 'AEGIS_TG_TOKEN', manus: 'MANUS_TG_TOKEN', key: 'tgBotToken' },
+        { aegis: 'AEGIS_TG_GROUP', manus: 'MANUS_TG_GROUP', key: 'tgGroupId' },
+        { aegis: 'AEGIS_TG_ALLOWED_USERS', manus: 'MANUS_TG_ALLOWED_USERS', key: 'tgAllowedUsers' },
+        { aegis: 'AEGIS_TG_TOPIC_TTL_MS', manus: 'MANUS_TG_TOPIC_TTL_MS', key: 'tgTopicTtlMs' },
+        { aegis: 'AEGIS_WEBHOOKS', manus: 'MANUS_WEBHOOKS', key: 'webhooks' },
+        { aegis: 'AEGIS_SSE_MAX_CONNECTIONS', manus: 'MANUS_SSE_MAX_CONNECTIONS', key: 'sseMaxConnections' },
+        { aegis: 'AEGIS_SSE_MAX_PER_IP', manus: 'MANUS_SSE_MAX_PER_IP', key: 'sseMaxPerIp' },
+    ];
+    for (const { aegis, manus, key } of envMappings) {
+        // AEGIS_* takes priority over MANUS_*
+        const value = process.env[aegis] ?? process.env[manus];
+        if (value === undefined)
+            continue;
+        switch (key) {
+            case 'port':
+            case 'maxSessionAgeMs':
+            case 'reaperIntervalMs':
+            case 'continuationPointerTtlMs':
+            case 'tgTopicTtlMs':
+            case 'sseMaxConnections':
+            case 'sseMaxPerIp':
+                config[key] = parseIntSafe(value, config[key]);
+                break;
+            case 'webhooks':
+                // Support comma-separated webhooks
+                config[key] = value.includes(',')
+                    ? value.split(',').map(s => s.trim())
+                    : [value];
+                break;
+            case 'tgAllowedUsers':
+                config[key] = value.split(',').map(s => Number(s.trim())).filter(n => !isNaN(n) && n > 0);
+                break;
+            // All remaining env-mapped keys are string-typed — assign directly.
+            case 'host':
+            case 'authToken':
+            case 'tmuxSession':
+            case 'stateDir':
+            case 'claudeProjectsDir':
+            case 'tgBotToken':
+            case 'tgGroupId':
+                config[key] = value;
+                break;
+            default:
+                // Skip complex types (Record<string,string>) that can't be set from a single env var
+                break;
+        }
+    }
+    return config;
+}
+/** Resolve the state directory.
+ *  If ~/.aegis doesn't exist but ~/.manus does, use ~/.manus for backward compat.
+ */
+function resolveStateDir(config) {
+    const aegisDir = join(homedir(), '.aegis');
+    const manusDir = join(homedir(), '.manus');
+    // If stateDir is the default aegis path but doesn't exist, check for legacy manus path
+    if (config.stateDir === aegisDir && !existsSync(aegisDir) && existsSync(manusDir)) {
+        console.log(`Config: using legacy state dir ${manusDir} — consider migrating to ${aegisDir}`);
+        config.stateDir = manusDir;
+    }
+    return config;
+}
+/** Load and merge configuration from all sources */
+export async function loadConfig() {
+    const fileConfig = await loadConfigFile();
+    let config = { ...defaults, ...fileConfig };
+    config = applyEnvOverrides(config);
+    config = resolveStateDir(config);
+    // Issue #349: Resolve allowedWorkDirs entries via realpath so symlink targets match
+    if (config.allowedWorkDirs.length > 0) {
+        config.allowedWorkDirs = await Promise.all(config.allowedWorkDirs.map(async (dir) => {
+            try {
+                return await realpath(resolve(dir));
+            }
+            catch { /* dir does not exist yet — use unresolved path */
+                return resolve(dir);
+            }
+        }));
+    }
+    return config;
+}
+/** Get config without async file loading (for tests or synchronous contexts) */
+export function getConfig() {
+    // This returns defaults + env overrides only (no file loading)
+    let config = { ...defaults };
+    config = applyEnvOverrides(config);
+    return config;
+}

package/dist/consensus.d.ts

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

package/dist/consensus.js

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

package/dist/continuation-pointer.d.ts

@@ -0,0 +1,11 @@
+import type { z } from 'zod';
+import { sessionMapEntrySchema } from './validation.js';
+export type ContinuationPointerEntry = z.infer<typeof sessionMapEntrySchema>;
+/**
+ * Read continuation pointers with schema validation + TTL cleanup.
+ *
+ * Backward compatible behavior:
+ * - Legacy entries without expires_at are accepted and normalized.
+ * - Corrupt files do not throw; they are reset to an empty map.
+ */
+export declare function loadContinuationPointers(sessionMapFile: string, ttlMs: number, nowMs?: number): Promise<Record<string, ContinuationPointerEntry>>;

package/dist/continuation-pointer.js

@@ -0,0 +1,65 @@
+import { existsSync } from 'node:fs';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { sessionMapEntrySchema } from './validation.js';
+import { safeJsonParse } from './safe-json.js';
+function computeExpiresAt(entry, ttlMs) {
+    if (typeof entry.expires_at === 'number') {
+        return entry.expires_at;
+    }
+    return entry.written_at + ttlMs;
+}
+async function persistPointerMap(sessionMapFile, mapData) {
+    const tmpFile = `${sessionMapFile}.tmp`;
+    await writeFile(tmpFile, JSON.stringify(mapData, null, 2));
+    await rename(tmpFile, sessionMapFile);
+}
+/**
+ * Read continuation pointers with schema validation + TTL cleanup.
+ *
+ * Backward compatible behavior:
+ * - Legacy entries without expires_at are accepted and normalized.
+ * - Corrupt files do not throw; they are reset to an empty map.
+ */
+export async function loadContinuationPointers(sessionMapFile, ttlMs, nowMs = Date.now()) {
+    if (!existsSync(sessionMapFile))
+        return {};
+    let parsed;
+    const raw = await readFile(sessionMapFile, 'utf-8');
+    const parsedResult = safeJsonParse(raw, 'Continuation pointer map');
+    if (!parsedResult.ok) {
+        await persistPointerMap(sessionMapFile, {});
+        return {};
+    }
+    parsed = parsedResult.data;
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        await persistPointerMap(sessionMapFile, {});
+        return {};
+    }
+    const cleaned = {};
+    let changed = false;
+    for (const [key, value] of Object.entries(parsed)) {
+        const entryResult = sessionMapEntrySchema.safeParse(value);
+        if (!entryResult.success) {
+            changed = true;
+            continue;
+        }
+        const entry = entryResult.data;
+        const expiresAt = computeExpiresAt(entry, ttlMs);
+        if (expiresAt <= nowMs) {
+            changed = true;
+            continue;
+        }
+        if (entry.expires_at !== expiresAt || entry.schema_version !== 1) {
+            changed = true;
+        }
+        cleaned[key] = {
+            ...entry,
+            schema_version: 1,
+            expires_at: expiresAt,
+        };
+    }
+    if (changed) {
+        await persistPointerMap(sessionMapFile, cleaned);
+    }
+    return cleaned;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,27 @@
+/**
+ * diagnostics.ts - no-PII diagnostics event stream with bounded in-memory buffer.
+ */
+export type DiagnosticsLevel = 'info' | 'warn' | 'error';
+export interface DiagnosticsEvent {
+    event: string;
+    level: DiagnosticsLevel;
+    component: string;
+    operation: string;
+    sessionId?: string;
+    errorCode?: string;
+    timestamp: string;
+    attributes: Record<string, unknown>;
+}
+export declare const DEFAULT_DIAGNOSTICS_BUFFER_SIZE = 100;
+export declare function sanitizeDiagnosticsAttributes(attributes: Record<string, unknown> | undefined): Record<string, unknown>;
+export declare class DiagnosticsBus {
+    private readonly maxEntries;
+    private readonly emitter;
+    private readonly buffer;
+    constructor(maxEntries?: number);
+    emit(event: DiagnosticsEvent): void;
+    subscribe(handler: (event: DiagnosticsEvent) => void): () => void;
+    getRecent(limit?: number): DiagnosticsEvent[];
+    clear(): void;
+}
+export declare const diagnosticsBus: DiagnosticsBus;

package/dist/diagnostics.js

@@ -0,0 +1,95 @@
+/**
+ * diagnostics.ts - no-PII diagnostics event stream with bounded in-memory buffer.
+ */
+import { EventEmitter } from 'node:events';
+export const DEFAULT_DIAGNOSTICS_BUFFER_SIZE = 100;
+const MAX_DIAGNOSTICS_STRING_LENGTH = 200;
+const MAX_SANITIZE_DEPTH = 4;
+const FORBIDDEN_KEY_FRAGMENTS = [
+    'token',
+    'password',
+    'secret',
+    'authorization',
+    'cookie',
+    'auth',
+    'api_key',
+    'apikey',
+    'prompt',
+    'transcript',
+    'payload',
+    'workdir',
+];
+function isForbiddenAttribute(key) {
+    const normalized = key.toLowerCase();
+    return FORBIDDEN_KEY_FRAGMENTS.some(fragment => normalized.includes(fragment));
+}
+function sanitizeValue(value, depth = 0) {
+    if (depth > MAX_SANITIZE_DEPTH)
+        return '[TRUNCATED]';
+    if (typeof value === 'string') {
+        return value.length > MAX_DIAGNOSTICS_STRING_LENGTH
+            ? `${value.slice(0, MAX_DIAGNOSTICS_STRING_LENGTH)}...`
+            : value;
+    }
+    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => sanitizeValue(item, depth + 1));
+    }
+    if (typeof value === 'object') {
+        const sanitizedObject = {};
+        for (const [key, nested] of Object.entries(value)) {
+            if (isForbiddenAttribute(key))
+                continue;
+            sanitizedObject[key] = sanitizeValue(nested, depth + 1);
+        }
+        return sanitizedObject;
+    }
+    if (value === undefined)
+        return undefined;
+    return String(value);
+}
+export function sanitizeDiagnosticsAttributes(attributes) {
+    if (!attributes)
+        return {};
+    const sanitized = sanitizeValue(attributes);
+    return (typeof sanitized === 'object' && sanitized !== null && !Array.isArray(sanitized))
+        ? sanitized
+        : {};
+}
+function sanitizeDiagnosticsEvent(event) {
+    return {
+        ...event,
+        attributes: sanitizeDiagnosticsAttributes(event.attributes),
+    };
+}
+export class DiagnosticsBus {
+    maxEntries;
+    emitter = new EventEmitter();
+    buffer = [];
+    constructor(maxEntries = DEFAULT_DIAGNOSTICS_BUFFER_SIZE) {
+        this.maxEntries = maxEntries;
+    }
+    emit(event) {
+        const sanitizedEvent = sanitizeDiagnosticsEvent(event);
+        this.buffer.push(sanitizedEvent);
+        if (this.buffer.length > this.maxEntries) {
+            this.buffer.splice(0, this.buffer.length - this.maxEntries);
+        }
+        this.emitter.emit('event', sanitizedEvent);
+    }
+    subscribe(handler) {
+        this.emitter.on('event', handler);
+        return () => this.emitter.off('event', handler);
+    }
+    getRecent(limit = this.maxEntries) {
+        if (limit <= 0)
+            return [];
+        return this.buffer.slice(-Math.min(limit, this.maxEntries));
+    }
+    clear() {
+        this.buffer.length = 0;
+    }
+}
+export const diagnosticsBus = new DiagnosticsBus();

package/dist/error-categories.d.ts

@@ -0,0 +1,39 @@
+/**
+ * error-categories.ts — Structured error categorization and retry guidance.
+ *
+ * Issue #701: Provides an ErrorCode enum, categorize() function to inspect
+ * unknown errors and return structured metadata, and shouldRetry() helper.
+ */
+/** String enum of Aegis error codes. */
+export declare enum ErrorCode {
+    /** Session not found, already deleted, or in wrong state. */
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND",
+    /** Session creation failed (tmux window, CC launch). */
+    SESSION_CREATE_FAILED = "SESSION_CREATE_FAILED",
+    /** Permission request was rejected by the user. */
+    PERMISSION_REJECTED = "PERMISSION_REJECTED",
+    /** Tmux command timed out. */
+    TMUX_TIMEOUT = "TMUX_TIMEOUT",
+    /** Tmux operation failed (non-timeout). */
+    TMUX_ERROR = "TMUX_ERROR",
+    /** Request body or parameter failed validation. */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Authentication failed (missing/invalid token). */
+    AUTH_ERROR = "AUTH_ERROR",
+    /** Rate limit exceeded. */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Network or I/O error (transient). */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Unexpected internal error. */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/** Structured result returned by categorize(). */
+export interface CategorizedError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+}
+/** Inspect an unknown error and return a structured categorization. */
+export declare function categorize(error: unknown): CategorizedError;
+/** Return true if the error is worth retrying. */
+export declare function shouldRetry(error: unknown): boolean;

package/dist/error-categories.js

@@ -0,0 +1,73 @@
+/**
+ * error-categories.ts — Structured error categorization and retry guidance.
+ *
+ * Issue #701: Provides an ErrorCode enum, categorize() function to inspect
+ * unknown errors and return structured metadata, and shouldRetry() helper.
+ */
+import { TmuxTimeoutError } from './tmux.js';
+/** String enum of Aegis error codes. */
+export var ErrorCode;
+(function (ErrorCode) {
+    /** Session not found, already deleted, or in wrong state. */
+    ErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
+    /** Session creation failed (tmux window, CC launch). */
+    ErrorCode["SESSION_CREATE_FAILED"] = "SESSION_CREATE_FAILED";
+    /** Permission request was rejected by the user. */
+    ErrorCode["PERMISSION_REJECTED"] = "PERMISSION_REJECTED";
+    /** Tmux command timed out. */
+    ErrorCode["TMUX_TIMEOUT"] = "TMUX_TIMEOUT";
+    /** Tmux operation failed (non-timeout). */
+    ErrorCode["TMUX_ERROR"] = "TMUX_ERROR";
+    /** Request body or parameter failed validation. */
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** Authentication failed (missing/invalid token). */
+    ErrorCode["AUTH_ERROR"] = "AUTH_ERROR";
+    /** Rate limit exceeded. */
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    /** Network or I/O error (transient). */
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    /** Unexpected internal error. */
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+/** Inspect an unknown error and return a structured categorization. */
+export function categorize(error) {
+    // 1. Known typed errors
+    if (error instanceof TmuxTimeoutError) {
+        return { code: ErrorCode.TMUX_TIMEOUT, message: error.message, retryable: true };
+    }
+    if (error instanceof Error) {
+        const msg = error.message;
+        const lower = msg.toLowerCase();
+        // 2. Message-based heuristics for common Aegis error patterns
+        if (lower.includes('session not found') || lower.includes('no session with id')) {
+            return { code: ErrorCode.SESSION_NOT_FOUND, message: msg, retryable: false };
+        }
+        if (lower.includes('permission denied') || lower.includes('permission rejected')) {
+            return { code: ErrorCode.PERMISSION_REJECTED, message: msg, retryable: false };
+        }
+        if (lower.includes('unauthorized') || lower.includes('invalid token') || lower.includes('authentication')) {
+            return { code: ErrorCode.AUTH_ERROR, message: msg, retryable: false };
+        }
+        if (lower.includes('rate limit') || lower.includes('too many requests')) {
+            return { code: ErrorCode.RATE_LIMITED, message: msg, retryable: true };
+        }
+        if (lower.includes('validation') || lower.includes('invalid ') || lower.includes('required')) {
+            return { code: ErrorCode.VALIDATION_ERROR, message: msg, retryable: false };
+        }
+        if (lower.includes('econnrefused') || lower.includes('econnreset') || lower.includes('etimedout') || lower.includes('fetch failed')) {
+            return { code: ErrorCode.NETWORK_ERROR, message: msg, retryable: true };
+        }
+        if (lower.includes('tmux')) {
+            return { code: ErrorCode.TMUX_ERROR, message: msg, retryable: true };
+        }
+        // 3. Generic Error fallback
+        return { code: ErrorCode.INTERNAL_ERROR, message: msg, retryable: false };
+    }
+    // 4. Non-Error values
+    const msg = typeof error === 'string' ? error : String(error);
+    return { code: ErrorCode.INTERNAL_ERROR, message: msg, retryable: false };
+}
+/** Return true if the error is worth retrying. */
+export function shouldRetry(error) {
+    return categorize(error).retryable;
+}