principles-disciple 1.7.8 → 1.8.1

package/dist/core/config.d.ts

@@ -78,6 +78,8 @@ export interface PainSettings {
     deep_reflection?: DeepReflectionSettings;
     empathy_engine?: {
         enabled?: boolean;
+        /** Shadow mode: also run EmpathyObserverWorkflowManager alongside legacy path */
+        helper_empathy_enabled?: boolean;
         dedupe_window_ms?: number;
         penalties?: {
             mild?: number;

package/dist/core/session-tracker.d.ts

@@ -8,6 +8,8 @@ export interface TokenUsage {
 }
 export interface SessionState {
     sessionId: string;
+    sessionKey?: string;
+    trigger?: string;
     workspaceDir?: string;
     toolReadsByFile: Record<string, number>;
     llmTurns: number;
@@ -40,7 +42,7 @@ export declare function initPersistence(stateDir: string): void;
  */
 export declare function flushAllSessions(): void;
 export declare function trackToolRead(sessionId: string, filePath: string, workspaceDir?: string): SessionState;
-export declare function trackLlmOutput(sessionId: string, usage: TokenUsage | undefined, config?: PainConfig, workspaceDir?: string): SessionState;
+export declare function trackLlmOutput(sessionId: string, usage: TokenUsage | undefined, config?: PainConfig, workspaceDir?: string, sessionKey?: string, trigger?: string): SessionState;
 /**
  * Tracks physical friction based on tool execution failures.
  */

package/dist/core/session-tracker.js

@@ -111,11 +111,13 @@ export function flushAllSessions() {
         persistSession(state);
     }
 }
-function getOrCreateSession(sessionId, workspaceDir) {
+function getOrCreateSession(sessionId, workspaceDir, sessionKey, trigger) {
     let state = sessions.get(sessionId);
     if (!state) {
         state = {
             sessionId,
+            sessionKey,
+            trigger,
             workspaceDir,
             toolReadsByFile: {},
             llmTurns: 0,
@@ -143,6 +145,13 @@ function getOrCreateSession(sessionId, workspaceDir) {
     if (workspaceDir && !state.workspaceDir) {
         state.workspaceDir = workspaceDir;
     }
+    // Update sessionKey and trigger if provided (they may be more recent)
+    if (sessionKey && !state.sessionKey) {
+        state.sessionKey = sessionKey;
+    }
+    if (trigger && !state.trigger) {
+        state.trigger = trigger;
+    }
     return state;
 }
 function ensureGfiLedger(state) {
@@ -158,8 +167,8 @@ export function trackToolRead(sessionId, filePath, workspaceDir) {
     touchActivity(state);
     return state;
 }
-export function trackLlmOutput(sessionId, usage, config, workspaceDir) {
-    const state = getOrCreateSession(sessionId, workspaceDir);
+export function trackLlmOutput(sessionId, usage, config, workspaceDir, sessionKey, trigger) {
+    const state = getOrCreateSession(sessionId, workspaceDir, sessionKey, trigger);
     state.llmTurns += 1;
     touchActivity(state);
     if (usage) {

package/dist/hooks/llm.d.ts

@@ -7,6 +7,7 @@ export interface EmpathySignal {
     mode?: 'structured' | 'legacy_tag';
 }
 export declare function extractEmpathySignal(text: string): EmpathySignal;
+export declare function isEmpathyAuditPayload(text: string): boolean;
 export declare function handleLlmOutput(event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext & {
     workspaceDir?: string;
 }): void;

package/dist/hooks/llm.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { trackFriction, trackLlmOutput, recordThinkingCheckpoint, resetFriction } from '../core/session-tracker.js';
+import { trackLlmOutput, recordThinkingCheckpoint, resetFriction } from '../core/session-tracker.js';
 import { writePainFlag } from '../core/pain.js';
 import { ControlUiDatabase } from '../core/control-ui-db.js';
 import { DetectionService } from '../core/detection-service.js';
@@ -175,6 +175,18 @@ function applyRateLimit(sessionId, runId, score, config) {
     empathyRateState.set(sessionId, prev);
     return allowed;
 }
+export function isEmpathyAuditPayload(text) {
+    if (!text || typeof text !== 'string')
+        return false;
+    const trimmed = text.trim();
+    if (/^\{[\s\S]*"damageDetected"[\s\S]*\}$/.test(trimmed))
+        return true;
+    if (/^<empathy\s+([^>]*)\/?>/i.test(trimmed))
+        return true;
+    if (/^\s*\[EMOTIONAL_DAMAGE_DETECTED(?::(mild|moderate|severe))?\]\s*$/i.test(trimmed))
+        return true;
+    return false;
+}
 export function handleLlmOutput(event, ctx) {
     if (!ctx.workspaceDir || !ctx.sessionId)
         return;
@@ -182,7 +194,7 @@ export function handleLlmOutput(event, ctx) {
     const config = wctx.config;
     const eventLog = wctx.eventLog;
     // Track this turn in the core session memory
-    const state = trackLlmOutput(ctx.sessionId, event.usage, config, ctx.workspaceDir);
+    const state = trackLlmOutput(ctx.sessionId, event.usage, config, ctx.workspaceDir, ctx.sessionKey, ctx.trigger);
     // We need actual assistant text to analyze
     if (!event.assistantTexts || event.assistantTexts.length === 0)
         return;
@@ -207,14 +219,15 @@ export function handleLlmOutput(event, ctx) {
         ctx.logger?.warn?.(`[PD:LLM] Failed to persist assistant turn to trajectory: ${String(error)}`);
     }
     // ── Track B: Semantic Pain Detection (V1.3.0 Funnel) ──
+    const detectionText = isEmpathyAuditPayload(text) ? '' : text;
     const detectionService = DetectionService.get(wctx.stateDir);
-    const detection = detectionService.detect(text);
+    const detection = detectionService.detect(detectionText);
     if (detection.detected) {
         eventLog.recordRuleMatch(ctx.sessionId, {
             ruleId: detection.ruleId || detection.source,
             layer: detection.source === 'l1_exact' ? 'L1' : (detection.source === 'l2_cache' ? 'L2' : 'L3'),
             severity: detection.severity || 0,
-            textPreview: text.substring(0, 100)
+            textPreview: detectionText.substring(0, 100)
         });
     }
     let painScore = detection.detected ? (detection.severity || 0) : 0;
@@ -224,73 +237,7 @@ export function handleLlmOutput(event, ctx) {
     let matchedReason = detection.detected
         ? `Agent triggered pain detection (Source: ${detection.source}${detection.ruleId ? `, Rule: ${detection.ruleId}` : ''})`
         : '';
-    // empathy sub-pipeline (enabled by default)
-    const empathyEnabled = config.get('empathy_engine.enabled');
-    if (empathyEnabled !== false) {
-        if (signal.detected) {
-            const dedupeWindow = Number(config.get('empathy_engine.dedupe_window_ms') ?? 60000);
-            const deduped = shouldDedupe(ctx.sessionId, event.runId, signal, dedupeWindow);
-            if (!deduped) {
-                const baseScore = mapSeverityToPenalty(signal.severity, config);
-                const weightedScore = Math.round(baseScore * signal.confidence);
-                const calibrationFactor = resolveCalibrationFactor(event, config);
-                const calibratedScore = Math.round(weightedScore * calibrationFactor);
-                const boundedScore = applyRateLimit(ctx.sessionId, event.runId, calibratedScore, config);
-                if (boundedScore > 0) {
-                    trackFriction(ctx.sessionId, boundedScore, `user_empathy_${signal.severity}`, ctx.workspaceDir, { source: 'user_empathy' });
-                    try {
-                        wctx.trajectory?.recordPainEvent?.({
-                            sessionId: ctx.sessionId,
-                            source: 'user_empathy',
-                            score: boundedScore,
-                            reason: signal.reason || 'Assistant self-reported user emotional distress.',
-                            severity: signal.severity,
-                            origin: 'assistant_self_report',
-                            confidence: signal.confidence,
-                        });
-                    }
-                    catch (error) {
-                        ctx.logger?.warn?.(`[PD:LLM] Failed to persist empathy pain event to trajectory: ${String(error)}`);
-                    }
-                    // Generate unique event ID for rollback support
-                    const eventId = `emp_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
-                    eventLog.recordPainSignal(ctx.sessionId, {
-                        score: boundedScore,
-                        source: 'user_empathy',
-                        reason: signal.reason || 'Assistant self-reported user emotional distress.',
-                        isRisky: false,
-                        origin: 'assistant_self_report',
-                        severity: signal.severity,
-                        confidence: signal.confidence,
-                        detection_mode: signal.mode,
-                        deduped: false,
-                        trigger_text_excerpt: text.substring(0, 120),
-                        raw_score: weightedScore,
-                        calibrated_score: calibratedScore,
-                        eventId,
-                    });
-                }
-            }
-            else {
-                eventLog.recordPainSignal(ctx.sessionId, {
-                    score: 0,
-                    source: 'user_empathy',
-                    reason: signal.reason || 'Deduped empathy signal.',
-                    isRisky: false,
-                    origin: 'assistant_self_report',
-                    severity: signal.severity,
-                    confidence: signal.confidence,
-                    detection_mode: signal.mode,
-                    deduped: true,
-                    trigger_text_excerpt: text.substring(0, 120),
-                    raw_score: Math.round(mapSeverityToPenalty(signal.severity, config) * signal.confidence),
-                    calibrated_score: Math.round(mapSeverityToPenalty(signal.severity, config) * signal.confidence * resolveCalibrationFactor(event, config))
-                });
-            }
-        }
-    }
     // ═══ Natural Language Rollback Detection ═══
-    // Detect [EMPATHY_ROLLBACK_REQUEST] tag and trigger rollback
     const rollbackMatch = text.match(/^\s*\[EMPATHY_ROLLBACK_REQUEST\]\s*$/m);
     if (rollbackMatch) {
         const eventId = eventLog.getLastEmpathyEventId(ctx.sessionId);

package/dist/hooks/progressive-trust-gate.d.ts

@@ -48,4 +48,5 @@ export declare function checkProgressiveTrustGate(event: PluginHookBeforeToolCal
     sessionId?: string;
 }, profile?: {
     risk_paths: string[];
+    core_governance_files?: string[];
 }): PluginHookBeforeToolCallResult | void;

package/dist/hooks/progressive-trust-gate.js

@@ -22,6 +22,46 @@
  */
 import { checkEvolutionGate } from '../core/evolution-engine.js';
 import { recordGateBlockAndReturn } from './gate-block-helper.js';
+// ═══ P-16: Core Governance Files — Exempt from all Blocking ═══
+// 这些文件是团队协作的基础，必须始终放行，不受 GFI 和 Risk Path 限制
+// 可通过 PROFILE.core_governance_files 扩展（merge 而非覆盖）
+const DEFAULT_CORE_GOVERNANCE_PATTERNS = [
+    'PLAN.md',
+    'AGENTS.md',
+    'VERSION.md',
+    '.team/',
+    'MEMORY.md',
+    'SOUL.md',
+    'IDENTITY.md',
+    'USER.md',
+    'HEARTBEAT.md',
+    'BOOTSTRAP.md',
+    'PRINCIPLES.md',
+    'TEAM_ROLE.md',
+    'REPAIR_OPERATING_PROMPT.md',
+];
+/**
+ * Get effective core governance patterns from PROFILE config, merged with defaults.
+ * PROFILE.core_governance_files extends (not replaces) the default list.
+ */
+function getCoreGovernancePatterns(profile) {
+    const base = DEFAULT_CORE_GOVERNANCE_PATTERNS;
+    const extra = profile?.core_governance_files ?? [];
+    return Array.from(new Set([...base, ...extra]));
+}
+/**
+ * Check if a file path matches a core governance pattern.
+ * Core governance files are exempt from all gate blocking (P-16).
+ */
+function isCoreGovernanceFile(filePath, corePatterns) {
+    if (!filePath)
+        return false;
+    const patterns = corePatterns ?? DEFAULT_CORE_GOVERNANCE_PATTERNS;
+    const normalized = filePath.replace(/\\/g, '/');
+    return patterns.some(pattern => pattern.endsWith('/')
+        ? normalized.includes(pattern)
+        : normalized.endsWith(pattern) || normalized.includes(`/${pattern}`));
+}
 /**
  * Build EP gate rejection reason
  */
@@ -54,6 +94,11 @@ function block(filePath, reason, wctx, toolName, logger, sessionId) {
  * @returns PluginHookBeforeToolCallResult to block, or undefined to allow
  */
 export function checkProgressiveTrustGate(event, wctx, relPath, risky, lineChanges, logger, ctx, profile) {
+    // P-16: Core governance files are exempt from all gate blocking
+    if (isCoreGovernanceFile(relPath, getCoreGovernancePatterns(profile))) {
+        logger.info?.(`[PD_GATE:P-16] Core governance file exempt — bypass all gates: ${relPath}`);
+        return;
+    }
     // EP is the only gate now - use actual gate decision
     if (!ctx.workspaceDir) {
         logger.warn?.('[PD_GATE] No workspaceDir, skipping EP gate check');

package/dist/hooks/prompt.d.ts

@@ -17,6 +17,8 @@ interface PromptHookApi {
         };
         empathy_engine?: {
             enabled?: boolean;
+            /** Shadow mode: also run EmpathyObserverWorkflowManager alongside legacy path */
+            helper_empathy_enabled?: boolean;
         };
     };
     runtime: EmpathyObserverApi['runtime'];

package/dist/hooks/prompt.js

@@ -6,6 +6,7 @@ import { defaultContextConfig } from '../types.js';
 import { classifyTask } from '../core/local-worker-routing.js';
 import { extractSummary, getHistoryVersions, parseWorkingMemorySection, workingMemoryToInjection, autoCompressFocus, safeReadCurrentFocus } from '../core/focus-history.js';
 import { empathyObserverManager } from '../service/empathy-observer-manager.js';
+import { EmpathyObserverWorkflowManager, empathyObserverWorkflowSpec } from '../service/subagent-workflow/index.js';
 import { PathResolver } from '../core/path-resolver.js';
 /**
  * OpenClaw API Prompt Hook
@@ -414,11 +415,13 @@ You are a **self-evolving AI agent** powered by Principles Disciple.
 - If you need self-inspection, prioritize the worker entry pointed by PathResolver key: EVOLUTION_WORKER
 `;
     // ──── 2. Evolution Directive (always on, highest priority) - stays in prependContext ────
-    // NOTE: active evolution task prompt is injected from EVOLUTION_QUEUE for active tasks
-    // NOT used for Phase 3 eligibility decisions
-    // EVOLUTION_DIRECTIVE.json is a compatibility-only display artifact
-    // Phase 3 eligibility uses only queue and evolution (see phase3-input-filter.ts)
     let activeEvolutionTaskPrompt = '';
+    const empathySilenceConstraint = `
+### 【EMPATHY OUTPUT RESTRICTION】
+Do NOT output empathy diagnostic text in JSON, XML, or tag format.
+Do NOT include "damageDetected", "severity", "confidence", or "empathy" fields in your output.
+The empathy observer subagent handles pain detection independently.
+`.trim();
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     if (fs.existsSync(queuePath)) {
         try {
@@ -498,7 +501,9 @@ REQUIRED ACTION:
         }
     }
     // Inject queue-derived evolution task at the front of prependContext
-    if (activeEvolutionTaskPrompt) {
+    // Skip for minimal mode (heartbeat / subagent / observer sessions) to avoid
+    // polluting empathy observer prompts and other internal subagent sessions.
+    if (activeEvolutionTaskPrompt && !isMinimalMode) {
         prependContext = activeEvolutionTaskPrompt + prependContext;
     }
     // ─────────────────────────────────────────────────4. Empathy Observer Spawn (async sidecar)
@@ -506,7 +511,23 @@ REQUIRED ACTION:
     const latestUserMessage = extractLatestUserMessage(event.messages);
     const isAgentToAgent = latestUserMessage.includes('sourceSession=agent:') || sessionId?.includes(':subagent:') === true;
     if (trigger === 'user' && sessionId && api && !isAgentToAgent) {
-        empathyObserverManager.spawn(api, sessionId, latestUserMessage).catch((err) => api.logger.warn(String(err)));
+        prependContext = '### BEHAVIORAL_CONSTRAINTS\n' + empathySilenceConstraint + '\n\n' + prependContext;
+        empathyObserverManager.spawn(api, sessionId, latestUserMessage, workspaceDir).catch((err) => api.logger.warn(String(err)));
+        if (api.config?.empathy_engine?.helper_empathy_enabled === true && workspaceDir) {
+            // Cast required because SDK SubagentRunParams lacks expectsCompletionMessage
+            // which is supported by the actual OpenClaw runtime
+            const shadowManager = new EmpathyObserverWorkflowManager({
+                workspaceDir,
+                logger: api.logger,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                subagent: api.runtime.subagent,
+            });
+            shadowManager.startWorkflow(empathyObserverWorkflowSpec, {
+                parentSessionId: sessionId,
+                workspaceDir,
+                taskInput: latestUserMessage,
+            }).catch((err) => api.logger.warn(`[PD:ShadowEmpathy] workflow failed: ${String(err)}`));
+        }
     }
     // ──── 5. Heartbeat-specific checklist ────
     if (trigger === 'heartbeat') {

package/dist/hooks/subagent.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import { writePainFlag } from '../core/pain.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
-import { empathyObserverManager } from '../service/empathy-observer-manager.js';
+import { empathyObserverManager, isEmpathyObserverSession } from '../service/empathy-observer-manager.js';
 import { acquireQueueLock } from '../service/evolution-worker.js';
 import { recordEvolutionSuccess } from '../core/evolution-engine.js';
 const COMPLETION_RETRY_DELAY_MS = 250;
@@ -125,7 +125,7 @@ export async function handleSubagentEnded(event, ctx) {
         return;
     const wctx = WorkspaceContext.fromHookContext(ctx);
     const logger = ctx.api?.logger ?? console;
-    if (targetSessionKey?.startsWith('empathy_obs:')) {
+    if (isEmpathyObserverSession(targetSessionKey || '')) {
         await empathyObserverManager.reap(ctx.api, targetSessionKey, workspaceDir);
         return;
     }

package/dist/http/principles-console-route.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { ControlUiQueryService } from '../service/control-ui-query-service.js';
 import { getEvolutionQueryService } from '../service/evolution-query-service.js';
+import { HealthQueryService } from '../service/health-query-service.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
 import { getCentralDatabase } from '../service/central-database.js';
 const ROUTE_PREFIX = '/plugins/principles';
@@ -406,6 +407,119 @@ function handleApiRoute(api, pathname, req, res) {
             evoService.dispose();
         }
     }
+    // === Health Query API (v1.1 new endpoints) ===
+    const healthService = () => {
+        const workspaceDir = api.resolvePath('.');
+        return new HealthQueryService(workspaceDir);
+    };
+    if (pathname === `${API_PREFIX}/overview/health` && method === 'GET') {
+        const hs = healthService();
+        try {
+            json(res, 200, hs.getOverviewHealth());
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Health overview failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
+    if (pathname === `${API_PREFIX}/evolution/principles` && method === 'GET') {
+        const hs = healthService();
+        try {
+            json(res, 200, hs.getEvolutionPrinciples());
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Evolution principles failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
+    if (pathname === `${API_PREFIX}/feedback/gfi` && method === 'GET') {
+        const hs = healthService();
+        try {
+            json(res, 200, hs.getFeedbackGfi());
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Feedback GFI failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
+    if (pathname === `${API_PREFIX}/feedback/empathy-events` && method === 'GET') {
+        const hs = healthService();
+        try {
+            const limit = url.searchParams.has('limit') ? Number(url.searchParams.get('limit')) : undefined;
+            json(res, 200, hs.getFeedbackEmpathyEvents(limit));
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Feedback empathy events failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
+    if (pathname === `${API_PREFIX}/feedback/gate-blocks` && method === 'GET') {
+        const hs = healthService();
+        try {
+            const limit = url.searchParams.has('limit') ? Number(url.searchParams.get('limit')) : undefined;
+            json(res, 200, hs.getFeedbackGateBlocks(limit));
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Feedback gate blocks failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
+    if (pathname === `${API_PREFIX}/gate/stats` && method === 'GET') {
+        const hs = healthService();
+        try {
+            json(res, 200, hs.getGateStats());
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Gate stats failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
+    if (pathname === `${API_PREFIX}/gate/blocks` && method === 'GET') {
+        const hs = healthService();
+        try {
+            const limit = url.searchParams.has('limit') ? Number(url.searchParams.get('limit')) : undefined;
+            json(res, 200, hs.getGateBlocks(limit));
+            return true;
+        }
+        catch (error) {
+            api.logger.warn(`[PD:ControlUI] Gate blocks failed: ${String(error)}`);
+            json(res, 500, { error: 'internal_error', message: String(error) });
+            return true;
+        }
+        finally {
+            hs.dispose();
+        }
+    }
     if (pathname === `${API_PREFIX}/export/corrections` && method === 'GET') {
         try {
             const mode = url.searchParams.get('mode') === 'redacted' ? 'redacted' : 'raw';

package/dist/service/empathy-observer-manager.d.ts

@@ -13,7 +13,15 @@ export interface EmpathyObserverApi {
                 lane?: string;
                 deliver?: boolean;
                 idempotencyKey?: string;
+                expectsCompletionMessage?: boolean;
             }) => Promise<unknown>;
+            waitForRun: (params: {
+                runId: string;
+                timeoutMs?: number;
+            }) => Promise<{
+                status: 'ok' | 'error' | 'timeout';
+                error?: string;
+            }>;
             getSessionMessages: (params: {
                 sessionKey: string;
                 limit?: number;
@@ -21,6 +29,10 @@ export interface EmpathyObserverApi {
                 messages: unknown[];
                 assistantTexts?: string[];
             }>;
+            deleteSession: (params: {
+                sessionKey: string;
+                deleteTranscript?: boolean;
+            }) => Promise<void>;
         };
     };
     logger: PluginLogger;
@@ -28,21 +40,44 @@ export interface EmpathyObserverApi {
 export declare class EmpathyObserverManager {
     private static instance;
     private sessionLocks;
+    private activeRuns;
+    private completedSessions;
     private constructor();
     static getInstance(): EmpathyObserverManager;
     /**
-     * Probe whether the subagent runtime is actually functional.
-     * api.runtime.subagent always exists (it's a Proxy), but in embedded mode
-     * every method throws "only available during a gateway request".
-     * We cache the result to avoid repeated probing.
+     * Build a safe session key for empathy observer
+     * Format: agent:main:subagent:empathy-obs-{safeParentSessionId}-{timestamp}
      */
-    private subagentAvailableCache;
-    private isSubagentAvailable;
+    buildEmpathyObserverSessionKey(parentSessionId: string): string;
+    /**
+     * Check if a session key is an empathy observer session
+     */
+    isObserverSession(sessionKey: string): boolean;
+    private markCompleted;
+    private isCompleted;
+    private isActive;
+    private getActiveMetadata;
     shouldTrigger(api: EmpathyObserverApi | null | undefined, sessionId: string): boolean;
-    spawn(api: EmpathyObserverApi | null | undefined, sessionId: string, userMessage: string): Promise<string | null>;
-    reap(api: EmpathyObserverApi | null | undefined, targetSessionKey: string, workspaceDir: string): Promise<void>;
-    private isObserverSession;
-    private extractParentSessionId;
+    spawn(api: EmpathyObserverApi | null | undefined, sessionId: string, userMessage: string, workspaceDir?: string): Promise<string | null>;
+    /**
+     * Main回收链路: 使用 waitForRun 驱动回收
+     * 仅在 ok 时回收; timeout/exception 保留 session 由 fallback 处理
+     */
+    private finalizeRun;
+    /**
+     * 统一回收入口: reap + deleteSession + 清理状态
+     */
+    private reapBySession;
+    /**
+     * Fallback回收: 由 subagent_ended 触发
+     * 仅在主链路未处理时执行补救回收
+     */
+    reap(api: EmpathyObserverApi | null | undefined, targetSessionKey: string, workspaceDir?: string): Promise<void>;
+    private cleanupState;
+    /**
+     * Extract parent session ID from observer session key
+     */
+    extractParentSessionId(sessionKey: string): string | null;
     private parseJsonPayload;
     private extractAssistantText;
     private scoreFromSeverity;
@@ -50,3 +85,4 @@ export declare class EmpathyObserverManager {
     private normalizeConfidence;
 }
 export declare const empathyObserverManager: EmpathyObserverManager;
+export declare function isEmpathyObserverSession(sessionKey: string): boolean;