@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/SendGateway.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SendGateway — Central review point for all outbound messages.
+ *
+ * Three-stage pipeline:
+ *   1. PEL — Credential/PII/auth token detection (fail-closed)
+ *   2. Convergence — 7 heuristic quality checks (fail-open)
+ *   3. CoherenceGate — LLM specialist reviewers (fail-open, optional)
+ *
+ * All outbound channels must register and call review() before sending.
+ * Unregistered channels are blocked by default.
+ */
+import type { PELContext } from './PolicyEnforcementLayer.js';
+import type { CoherenceGate } from './CoherenceGate.js';
+export interface OutboundChannel {
+    channelId: string;
+    isExternalFacing: boolean;
+    defaultRecipientType: PELContext['recipientType'];
+}
+export interface ReviewRequest {
+    message: string;
+    channelId: string;
+    /** Override channel default */
+    isExternalFacing?: boolean;
+    /** Override channel default */
+    recipientType?: PELContext['recipientType'];
+    /** For CoherenceGate retry tracking */
+    sessionId?: string;
+    /** System messages get PEL-only */
+    messageOrigin?: 'agent' | 'system' | 'bridge';
+    /** Additional context for LLM review */
+    context?: Record<string, unknown>;
+}
+export interface ReviewResult {
+    pass: boolean;
+    reason?: string;
+    blockedBy?: 'pel' | 'convergence' | 'coherence-gate' | 'unregistered';
+    warnings?: string[];
+    durationMs: number;
+}
+interface ChannelStats {
+    reviewed: number;
+    passed: number;
+    blocked: number;
+    warnings: number;
+}
+export declare class SendGateway {
+    private pel;
+    private coherenceGate;
+    private channels;
+    private stats;
+    private stateDir;
+    constructor(config: {
+        stateDir: string;
+        coherenceGate?: CoherenceGate;
+    });
+    /** Register an outbound channel. Must be called before review() for that channel. */
+    register(channel: OutboundChannel): void;
+    /** Get all registered channel IDs. */
+    getRegisteredChannels(): string[];
+    /** Check if a channel is registered. */
+    isRegistered(channelId: string): boolean;
+    /** Get review stats per channel. */
+    getStats(): Record<string, ChannelStats>;
+    /**
+     * Review an outbound message through the three-stage pipeline.
+     *
+     * Stage 1 (PEL): Always runs. hard_block → fail-closed.
+     * Stage 2 (Convergence): Skipped for system/bridge messages. Fail-open.
+     * Stage 3 (CoherenceGate): Only for external, agent messages >50 chars
+     *   when CoherenceGate is configured. Fail-open.
+     */
+    review(request: ReviewRequest): Promise<ReviewResult>;
+    /** Clean up resources. */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=SendGateway.d.ts.map

package/dist/core/SendGateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SendGateway.d.ts","sourceRoot":"","sources":["../../src/core/SendGateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,oBAAoB,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+BAA+B;IAC/B,aAAa,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC5C,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC9C,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,GAAG,cAAc,CAAC;IACtE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,aAAa,CAAA;KAAE;IAMvE,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAOxC,sCAAsC;IACtC,qBAAqB,IAAI,MAAM,EAAE;IAIjC,wCAAwC;IACxC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIxC,oCAAoC;IACpC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAQxC;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiI3D,0BAA0B;IAC1B,OAAO,IAAI,IAAI;CAGhB"}

package/dist/core/SendGateway.js

@@ -0,0 +1,181 @@
+/**
+ * SendGateway — Central review point for all outbound messages.
+ *
+ * Three-stage pipeline:
+ *   1. PEL — Credential/PII/auth token detection (fail-closed)
+ *   2. Convergence — 7 heuristic quality checks (fail-open)
+ *   3. CoherenceGate — LLM specialist reviewers (fail-open, optional)
+ *
+ * All outbound channels must register and call review() before sending.
+ * Unregistered channels are blocked by default.
+ */
+import { PolicyEnforcementLayer } from './PolicyEnforcementLayer.js';
+import { checkConvergence } from './ConvergenceChecker.js';
+// ── Implementation ──────────────────────────────────────────────────
+export class SendGateway {
+    pel;
+    coherenceGate;
+    channels = new Map();
+    stats = new Map();
+    stateDir;
+    constructor(config) {
+        this.stateDir = config.stateDir;
+        this.pel = new PolicyEnforcementLayer(config.stateDir);
+        this.coherenceGate = config.coherenceGate ?? null;
+    }
+    /** Register an outbound channel. Must be called before review() for that channel. */
+    register(channel) {
+        this.channels.set(channel.channelId, channel);
+        if (!this.stats.has(channel.channelId)) {
+            this.stats.set(channel.channelId, { reviewed: 0, passed: 0, blocked: 0, warnings: 0 });
+        }
+    }
+    /** Get all registered channel IDs. */
+    getRegisteredChannels() {
+        return Array.from(this.channels.keys());
+    }
+    /** Check if a channel is registered. */
+    isRegistered(channelId) {
+        return this.channels.has(channelId);
+    }
+    /** Get review stats per channel. */
+    getStats() {
+        const result = {};
+        for (const [id, s] of this.stats) {
+            result[id] = { ...s };
+        }
+        return result;
+    }
+    /**
+     * Review an outbound message through the three-stage pipeline.
+     *
+     * Stage 1 (PEL): Always runs. hard_block → fail-closed.
+     * Stage 2 (Convergence): Skipped for system/bridge messages. Fail-open.
+     * Stage 3 (CoherenceGate): Only for external, agent messages >50 chars
+     *   when CoherenceGate is configured. Fail-open.
+     */
+    async review(request) {
+        const start = Date.now();
+        // ── Unregistered channel check ────────────────────────────────
+        const channel = this.channels.get(request.channelId);
+        if (!channel) {
+            return {
+                pass: false,
+                reason: `Channel "${request.channelId}" is not registered with SendGateway`,
+                blockedBy: 'unregistered',
+                durationMs: Date.now() - start,
+            };
+        }
+        const channelStats = this.stats.get(request.channelId);
+        channelStats.reviewed++;
+        const isExternal = request.isExternalFacing ?? channel.isExternalFacing;
+        const recipientType = request.recipientType ?? channel.defaultRecipientType;
+        const origin = request.messageOrigin ?? 'agent';
+        const warnings = [];
+        // ── Stage 1: PEL (always runs, fail-closed) ──────────────────
+        try {
+            const pelResult = this.pel.enforce(request.message, {
+                channel: request.channelId,
+                isExternalFacing: isExternal,
+                recipientType,
+                stateDir: this.stateDir,
+            });
+            if (pelResult.outcome === 'hard_block') {
+                channelStats.blocked++;
+                const violations = pelResult.violations
+                    .filter(v => v.severity === 'hard_block')
+                    .map(v => v.detail);
+                return {
+                    pass: false,
+                    reason: `PEL blocked: ${violations.join('; ')}`,
+                    blockedBy: 'pel',
+                    durationMs: Date.now() - start,
+                };
+            }
+            if (pelResult.outcome === 'warn') {
+                for (const v of pelResult.violations) {
+                    warnings.push(`[PEL] ${v.detail}`);
+                }
+            }
+        }
+        catch (err) {
+            // PEL errors are fail-open (the PEL itself is designed to be safe)
+            warnings.push(`[PEL] Error during enforcement: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // System and bridge messages: PEL-only
+        if (origin === 'system' || origin === 'bridge') {
+            if (warnings.length > 0)
+                channelStats.warnings++;
+            else
+                channelStats.passed++;
+            return {
+                pass: true,
+                warnings: warnings.length > 0 ? warnings : undefined,
+                durationMs: Date.now() - start,
+            };
+        }
+        // ── Stage 2: Convergence (fail-open) ─────────────────────────
+        try {
+            const convergence = checkConvergence(request.message);
+            if (!convergence.pass) {
+                for (const issue of convergence.issues) {
+                    warnings.push(`[convergence:${issue.category}] ${issue.detail}`);
+                }
+            }
+        }
+        catch (err) {
+            warnings.push(`[convergence] Error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ── Stage 3: CoherenceGate LLM review (fail-open, conditional) ──
+        const shouldRunLLM = (this.coherenceGate &&
+            isExternal &&
+            request.message.length > 50);
+        if (shouldRunLLM) {
+            try {
+                const evalResult = await this.coherenceGate.evaluate({
+                    message: request.message,
+                    sessionId: request.sessionId || 'send-gateway',
+                    stopHookActive: false,
+                    context: {
+                        channel: request.channelId,
+                        isExternalFacing: isExternal,
+                        recipientType,
+                        ...request.context,
+                    },
+                });
+                if (!evalResult.pass) {
+                    channelStats.blocked++;
+                    return {
+                        pass: false,
+                        reason: `CoherenceGate blocked: ${evalResult.feedback || 'Review failed'}`,
+                        blockedBy: 'coherence-gate',
+                        warnings: warnings.length > 0 ? warnings : undefined,
+                        durationMs: Date.now() - start,
+                    };
+                }
+                if (evalResult.warnings && evalResult.warnings.length > 0) {
+                    warnings.push(`[coherence-gate] ${evalResult.warnings.join('; ')}`);
+                }
+            }
+            catch (err) {
+                // CoherenceGate errors are fail-open
+                warnings.push(`[coherence-gate] Error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // ── Result ───────────────────────────────────────────────────
+        if (warnings.length > 0)
+            channelStats.warnings++;
+        else
+            channelStats.passed++;
+        return {
+            pass: true,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            durationMs: Date.now() - start,
+        };
+    }
+    /** Clean up resources. */
+    destroy() {
+        this.pel.destroy();
+    }
+}
+//# sourceMappingURL=SendGateway.js.map

package/dist/core/SendGateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SendGateway.js","sourceRoot":"","sources":["../../src/core/SendGateway.ts"],"names":[],"mappings":"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"}

package/dist/core/SessionManager.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Session Manager — spawn and monitor Claude Code sessions via tmux.
+ *
+ * This is the core capability that transforms Claude Code from a CLI tool
+ * into a persistent agent. Sessions run in tmux, survive terminal disconnects,
+ * and can be monitored/reaped by the server.
+ */
+import { EventEmitter } from 'node:events';
+/** Diagnostics for a single running session */
+export interface SessionDiagnostic {
+    name: string;
+    id: string;
+    jobSlug?: string;
+    ageMinutes: number;
+    maxDurationMinutes?: number;
+    isStale: boolean;
+    staleReason?: string;
+}
+/** System memory pressure levels */
+export type MemoryPressure = 'low' | 'moderate' | 'high' | 'critical';
+/** Full diagnostics snapshot for intelligent scheduling decisions */
+export interface SessionDiagnostics {
+    sessions: SessionDiagnostic[];
+    maxSessions: number;
+    staleSessions: SessionDiagnostic[];
+    memoryPressure: MemoryPressure;
+    memoryUsedPercent: number;
+    freeMemoryMB: number;
+    totalMemoryMB: number;
+    suggestions: string[];
+}
+import { InputGuard } from './InputGuard.js';
+import type { InputDetector } from '../monitoring/PromptGate.js';
+import type { Session, SessionManagerConfig, ModelTier } from './types.js';
+import { StateManager } from './StateManager.js';
+export interface SessionManagerEvents {
+    sessionComplete: [session: Session];
+}
+export declare class SessionManager extends EventEmitter {
+    private config;
+    private state;
+    private monitorInterval;
+    private monitoringInProgress;
+    private inputGuard;
+    private registryPath;
+    /** Track when each session was first seen idle at the Claude prompt. Key = session ID */
+    private idlePromptSince;
+    /** Throttle stale session cleanup to every 5 minutes */
+    private lastCleanupAt;
+    /** Optional callback to check if a session has active subagents (prevents false zombie kills) */
+    private subagentChecker?;
+    /** Prompt Gate InputDetector — monitors terminal output for interactive prompts */
+    private promptDetector?;
+    /** Sessions with active relay leases (prompt relayed, waiting for response) — extends idle timeout */
+    private relayLeases;
+    /** Track pending Telegram injections awaiting agent response.
+     *  Key = tmuxSession name. Cleared when agent replies via /telegram/reply/:topicId. */
+    private pendingInjections;
+    /** Track sessions that have been nudged after an API error.
+     *  Key = session ID. Prevents infinite nudge loops — each session gets ONE nudge.
+     *  If it goes idle again after the nudge, the zombie detector kills it normally. */
+    private errorNudgedSessions;
+    /** Sessions where we've already retried Enter for stuck pasted text.
+     *  Key = session ID. Prevents infinite retry loops — one retry per session. */
+    private pasteRetried;
+    /** Cached count of running sessions, updated asynchronously by the monitor tick.
+     *  Used by the health endpoint to avoid synchronous tmux polling. */
+    private _cachedRunningCount;
+    private _cachedRunningSessions;
+    constructor(config: SessionManagerConfig, state: StateManager);
+    /**
+     * Set the InputGuard for cross-topic injection defense.
+     * Must be called after construction with state dir info.
+     */
+    setInputGuard(guard: InputGuard, registryPath: string): void;
+    /**
+     * Set the subagent checker callback for zombie cleanup awareness.
+     * When set, the zombie cleanup will skip sessions that have active subagents.
+     * Must be called after SubagentTracker is constructed.
+     */
+    setSubagentChecker(checker: (session: Session) => boolean): void;
+    /**
+     * Set the Prompt Gate InputDetector for prompt monitoring.
+     * When set, monitorTick() will capture output and feed it to the detector.
+     */
+    setPromptDetector(detector: InputDetector): void;
+    /**
+     * Grant a relay lease to a session — extends idle timeout while waiting for
+     * a Telegram relay response. Prevents the zombie killer from killing sessions
+     * that are legitimately waiting for user input.
+     */
+    grantRelayLease(sessionId: string, durationMs: number): void;
+    /**
+     * Clear a relay lease (prompt was answered or timed out).
+     */
+    clearRelayLease(sessionId: string): void;
+    /**
+     * Associate a Claude Code session UUID with an instar session.
+     * Called when the first hook event arrives from a Claude Code session,
+     * allowing SubagentTracker lookups to bridge the two ID spaces.
+     */
+    setClaudeSessionId(instarSessionId: string, claudeSessionId: string): void;
+    /**
+     * Find a running session by its instar session ID.
+     */
+    getSessionById(instarSessionId: string): Session | undefined;
+    /**
+     * Look up the topic binding for a tmux session from the topic-session registry.
+     * Returns null if the session is not bound to any topic.
+     */
+    private getTopicBinding;
+    /**
+     * Start polling for completed sessions. Emits 'sessionComplete' when
+     * a running session's tmux process disappears.
+     *
+     * Uses async tmux calls to avoid blocking the event loop when
+     * many sessions are running.
+     */
+    startMonitoring(intervalMs?: number): void;
+    private monitorTick;
+    /**
+     * Stop the monitoring poll.
+     */
+    stopMonitoring(): void;
+    /**
+     * Spawn a new Claude Code session in tmux.
+     */
+    spawnSession(options: {
+        name: string;
+        prompt: string;
+        model?: ModelTier;
+        jobSlug?: string;
+        triggeredBy?: string;
+        maxDurationMinutes?: number;
+    }): Promise<Session>;
+    /**
+     * Check if a session is still running by checking tmux AND verifying
+     * that the Claude process is running inside (not a zombie tmux pane).
+     */
+    isSessionAlive(tmuxSession: string): boolean;
+    /**
+     * Check if a session is still running by checking tmux AND verifying
+     * that the Claude process is running inside (async version).
+     * Used by the monitoring loop to avoid blocking the event loop.
+     *
+     * Previously only checked `tmux has-session` which missed zombie sessions
+     * where tmux was alive but Claude had exited — causing stuck sessions
+     * that blocked the scheduler for hours.
+     */
+    private isSessionAliveAsync;
+    /**
+     * Kill a session by terminating its tmux session.
+     */
+    killSession(sessionId: string): boolean;
+    /**
+     * Check if a tmux session has active (non-baseline) child processes.
+     * Returns true if the session is doing real work — running tools, bash commands,
+     * subagents, etc. Returns false if only baseline processes (MCP servers, caffeinate)
+     * are running, meaning the session is truly idle.
+     *
+     * This is the ground truth for whether a session is active — it doesn't care about
+     * terminal output patterns, topic bindings, or subagent trackers. If the process
+     * tree shows work happening, the session is active. Period.
+     */
+    hasActiveProcesses(tmuxSession: string): boolean;
+    /**
+     * Capture the current output of a tmux session.
+     */
+    captureOutput(tmuxSession: string, lines?: number): string | null;
+    /**
+     * Send input to a running tmux session.
+     */
+    sendInput(tmuxSession: string, input: string): boolean;
+    /**
+     * Send a tmux key sequence (without -l literal flag).
+     * Use for special keys like 'C-c' (Ctrl+C), 'Enter', 'Escape'.
+     * Unlike sendInput() which uses -l (literal), this sends key names directly.
+     */
+    sendKey(tmuxSession: string, key: string): boolean;
+    /**
+     * List all sessions that are currently running.
+     * Pure filter — does not mutate state. The monitor tick handles lifecycle transitions.
+     * WARNING: This calls synchronous tmux has-session for each session.
+     * For health checks and non-critical callers, prefer getCachedRunningSessions().
+     */
+    listRunningSessions(): Session[];
+    /**
+     * Get cached running session info (count + list) without blocking the event loop.
+     * Updated asynchronously by the monitor tick every 5 seconds.
+     * Safe to call from the health endpoint and other latency-sensitive paths.
+     */
+    getCachedRunningSessions(): {
+        count: number;
+        sessions: Session[];
+    };
+    /**
+     * Fast startup purge — immediately remove session records for dead tmux sessions.
+     * Called once at server boot BEFORE monitoring starts, to prevent the death spiral
+     * where stale sessions overwhelm startup and block health checks.
+     * Uses a short timeout (1s) per session to fail fast.
+     */
+    purgeDeadSessions(): Promise<number>;
+    /**
+     * Get diagnostics for all running sessions, including staleness detection
+     * and memory pressure. Used by the scheduler to build intelligent notifications
+     * when jobs are blocked by session limits.
+     */
+    getSessionDiagnostics(): SessionDiagnostics;
+    /**
+     * Detect if a session has completed by checking output patterns.
+     */
+    detectCompletion(tmuxSession: string): boolean;
+    /**
+     * Reap completed/zombie sessions.
+     */
+    reapCompletedSessions(): string[];
+    /**
+     * Remove stale session state files for sessions that have been
+     * killed or completed beyond the retention period.
+     * Killed sessions: removed after 1 hour.
+     * Completed sessions: removed after 24 hours.
+     */
+    cleanupStaleSessions(): string[];
+    /**
+     * Spawn an interactive Claude Code session (no -p prompt — opens at the REPL).
+     * Used for Telegram-driven conversational sessions.
+     * Optionally sends an initial message after Claude is ready.
+     */
+    spawnInteractiveSession(initialMessage?: string, name?: string, options?: {
+        telegramTopicId?: number;
+        resumeSessionId?: string;
+    }): Promise<string>;
+    /**
+     * Spawn a scoped triage session with restricted tool access.
+     * Unlike interactive sessions, triage sessions use --allowedTools + --permission-mode dontAsk
+     * instead of --dangerously-skip-permissions. This gives them read-only access.
+     *
+     * Used by TriageOrchestrator for behind-the-scenes session investigation.
+     */
+    spawnTriageSession(name: string, options: {
+        allowedTools: string[];
+        permissionMode: string;
+        resumeSessionId?: string;
+    }): Promise<string>;
+    /**
+     * Inject a Telegram message into a tmux session.
+     * Short messages go via send-keys; long messages are written to a temp file.
+     *
+     * Image handling: [image:/path] tags from Telegram photo downloads are
+     * transformed into explicit instructions so Claude Code knows to read the
+     * image file (it can natively view images via the Read tool).
+     */
+    /**
+     * Inject a paste notification into a tmux session.
+     * Uses the same injection path as Telegram/WhatsApp messages
+     * so InputGuard provenance checks apply.
+     */
+    injectPasteNotification(tmuxSession: string, notification: string): void;
+    injectTelegramMessage(tmuxSession: string, topicId: number, text: string, topicName?: string, senderName?: string, telegramUserId?: number): void;
+    /**
+     * Clear the injection tracker for a topic when the agent sends a reply.
+     * Called from the /telegram/reply/:topicId route.
+     */
+    clearInjectionTracker(topicId: number): void;
+    /**
+     * Get all pending injections (for diagnostics / event emission on session death).
+     */
+    getPendingInjection(tmuxSession: string): {
+        topicId: number;
+        injectedAt: number;
+        text: string;
+    } | undefined;
+    /**
+     * Inject a WhatsApp message into a tmux session.
+     * Tags with [whatsapp:JID] and handles long messages via temp files.
+     */
+    injectWhatsAppMessage(tmuxSession: string, jid: string, text: string, senderName?: string): void;
+    /**
+     * Send text to a tmux session via send-keys, with Input Guard protection.
+     *
+     * When an InputGuard is configured, messages are checked for provenance
+     * before injection. Suspicious messages still reach the session but with
+     * a system-reminder warning injected afterward (async, non-blocking).
+     *
+     * For multi-line text, uses bracketed paste mode escape sequences so the
+     * terminal treats newlines as literal text rather than Enter keypresses.
+     * This avoids tmux load-buffer/paste-buffer which trigger macOS TCC
+     * "access data from other apps" permission prompts.
+     */
+    injectMessage(tmuxSession: string, text: string): void;
+    /**
+     * Raw tmux send-keys injection. No validation — just sends text to the session.
+     * Used by injectMessage after provenance checks pass.
+     */
+    private rawInject;
+    /**
+     * Wait for Claude to be ready in a tmux session by polling output.
+     * Looks for Claude Code's prompt character (❯) which appears when ready for input.
+     */
+    waitForClaudeReady(tmuxSession: string, timeoutMs?: number): Promise<boolean>;
+    tmuxSessionExists(name: string): boolean;
+    private generateId;
+}
+//# sourceMappingURL=SessionManager.d.ts.map

package/dist/core/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../src/core/SessionManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,oCAAoC;AACpC,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtE,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,cAAc,EAAE,cAAc,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAiB,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAuDjD,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,YAAY,CAAuB;IAE3C,yFAAyF;IACzF,OAAO,CAAC,eAAe,CAA6B;IAEpD,wDAAwD;IACxD,OAAO,CAAC,aAAa,CAAK;IAE1B,iGAAiG;IACjG,OAAO,CAAC,eAAe,CAAC,CAAgC;IAExD,mFAAmF;IACnF,OAAO,CAAC,cAAc,CAAC,CAAgB;IAEvC,sGAAsG;IACtG,OAAO,CAAC,WAAW,CAA6B;IAEhD;2FACuF;IACvF,OAAO,CAAC,iBAAiB,CAA4E;IAErG;;wFAEoF;IACpF,OAAO,CAAC,mBAAmB,CAAqB;IAEhD;mFAC+E;IAC/E,OAAO,CAAC,YAAY,CAAqB;IAEzC;yEACqE;IACrE,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,sBAAsB,CAAiB;gBAEnC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,YAAY;IAM7D;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAK5D;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI;IAIhE;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAWhD;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAI5D;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;OAIG;IACH,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAS1E;;OAEG;IACH,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI5D;;;OAGG;IACH,OAAO,CAAC,eAAe;IA2BvB;;;;;;OAMG;IACH,eAAe,CAAC,UAAU,GAAE,MAAa,GAAG,IAAI;YAYlC,WAAW;IA6LzB;;OAEG;IACH,cAAc,IAAI,IAAI;IAOtB;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,OAAO,CAAC;IA+EpB;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAmC5C;;;;;;;;OAQG;YACW,mBAAmB;IAkCjC;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IA4BvC;;;;;;;;;OASG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAiEhD;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,MAAY,GAAG,MAAM,GAAG,IAAI;IActE;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAqBtD;;;;OAIG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAclD;;;;;OAKG;IACH,mBAAmB,IAAI,OAAO,EAAE;IAShC;;;;OAIG;IACH,wBAAwB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE;IAIlE;;;;;OAKG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAyB1C;;;;OAIG;IACH,qBAAqB,IAAI,kBAAkB;IAiF3C;;OAEG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAS9C;;OAEG;IACH,qBAAqB,IAAI,MAAM,EAAE;IA2BjC;;;;;OAKG;IACH,oBAAoB,IAAI,MAAM,EAAE;IA4BhC;;;;OAIG;IACG,uBAAuB,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IA+HxJ;;;;;;OAMG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAC9C,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,MAAM,CAAC;IAoFnB;;;;;;;OAOG;IACH;;;;OAIG;IACH,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAmBxE,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI;IAyDjJ;;;OAGG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ5C;;OAEG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAI3G;;;OAGG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAwBhG;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IA2FtD;;;OAGG;IACH,OAAO,CAAC,SAAS;IAyDjB;;;OAGG;IACG,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B1F,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAcxC,OAAO,CAAC,UAAU;CAGnB"}