principles-disciple 1.10.0 → 1.12.0

package/src/service/subagent-workflow/nocturnal-workflow-manager.ts

@@ -35,11 +35,12 @@ import {
     type NocturnalRunResult,
 } from '../nocturnal-service.js';
 import { type TrinityStageFailure, type TrinityResult } from '../../core/nocturnal-trinity.js';
-import type { TrinityRuntimeAdapter, TrinityConfig, DreamerOutput, PhilosopherOutput, TrinityTelemetry } from '../../core/nocturnal-trinity.js';
+import type { TrinityRuntimeAdapter } from '../../core/nocturnal-trinity.js';
 import type { NocturnalSessionSnapshot } from '../../core/nocturnal-trajectory-extractor.js';
-import { createHash } from 'crypto';
+import type { RecentPainContext } from '../evolution-worker.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { isSubagentRuntimeAvailable } from '../../utils/subagent-probe.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // NocturnalResult Type Alias
@@ -51,50 +52,6 @@ import * as path from 'path';
  */
 export type NocturnalResult = NocturnalRunResult;
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Idempotency Key Computation (D-18)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Compute idempotency key for the Dreamer stage (D-18).
- * Key = SHA-256(workflowId + stage + inputDigest)
- * inputDigest = SHA-256(snapshot.sessionId + principleId + maxCandidates)
- * Uses simple concatenation (no delimiters) per D-18 spec.
- */
-function computeDreamerIdempotencyKey(
-  workflowId: string,
-  snapshot: import('../../core/nocturnal-trajectory-extractor.js').NocturnalSessionSnapshot,
-  principleId: string,
-  maxCandidates: number
-): string {
-  // Use delimiters to prevent collision (e.g., "sess10"+"2"+"3" vs "sess1"+"02"+"3")
-  const inputDigest = createHash('sha256')
-    .update(`${snapshot.sessionId}::${principleId}::${maxCandidates}`)
-    .digest('hex');
-  return createHash('sha256')
-    .update(`${workflowId}::dreamer::${inputDigest}`)
-    .digest('hex');
-}
-
-/**
- * Compute idempotency key for the Philosopher stage (D-18).
- * Key = SHA-256(workflowId + stage + inputDigest)
- * inputDigest = SHA-256(workflowId + dreamerOutputJson)
- * Uses simple concatenation (no delimiters) per D-18 spec.
- */
-function computePhilosopherIdempotencyKey(
-  workflowId: string,
-  dreamerOutput: import('../../core/nocturnal-trinity.js').DreamerOutput
-): string {
-  const dreamerOutputJson = JSON.stringify(dreamerOutput);
-  const inputDigest = createHash('sha256')
-    .update(workflowId + dreamerOutputJson)
-    .digest('hex');
-  return createHash('sha256')
-    .update(workflowId + 'philosopher' + inputDigest)
-    .digest('hex');
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // NocturnalWorkflowOptions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -125,6 +82,7 @@ export interface NocturnalWorkflowOptions {
  * - timeoutMs: 15 minutes (900000ms)
  * - ttlMs: 30 minutes (1800000ms)
  */
+/* eslint-disable no-unused-vars, @typescript-eslint/no-unused-vars -- Reason: spec methods intentionally receive unused params per interface contract */
 export const nocturnalWorkflowSpec: SubagentWorkflowSpec<NocturnalResult> = {
     workflowType: 'nocturnal',
     transport: 'runtime_direct',
@@ -132,7 +90,10 @@ export const nocturnalWorkflowSpec: SubagentWorkflowSpec<NocturnalResult> = {
     ttlMs: 30 * 60 * 1000,            // D-04: 30 minutes
     shouldDeleteSessionAfterFinalize: false,  // D-09: no external session to delete
 
-    buildPrompt(_taskInput: unknown, _metadata: WorkflowMetadata): string {
+    buildPrompt(
+        _taskInput: unknown,
+        _metadata: WorkflowMetadata
+    ): string {
         // NocturnalWorkflowManager does not use prompt injection.
         // Execution is driven by executeNocturnalReflectionAsync.
         return '';
@@ -141,7 +102,7 @@ export const nocturnalWorkflowSpec: SubagentWorkflowSpec<NocturnalResult> = {
     async parseResult(ctx: WorkflowResultContext): Promise<NocturnalResult | null> {
         // NocturnalWorkflowManager handles execution directly in startWorkflow.
         // This is not called via the standard subagent message path.
-        return (ctx.metadata['nocturnalResult'] as NocturnalResult) ?? null;
+        return (ctx.metadata.nocturnalResult as NocturnalResult) ?? null;
     },
 
     async persistResult(_ctx: WorkflowPersistContext<NocturnalResult>): Promise<void> {
@@ -154,57 +115,7 @@ export const nocturnalWorkflowSpec: SubagentWorkflowSpec<NocturnalResult> = {
         return status === 'ok';
     },
 };
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Stub Fallback Runtime Adapter (NOC-15)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Stub fallback runtime adapter for Trinity.
- * Wraps a real adapter and provides stub implementations for fallback when stages fail.
- * Per NOC-15: Fallback degrades to stub, NOT to EmpathyObserver/DeepReflect.
- */
-class StubFallbackRuntimeAdapter implements TrinityRuntimeAdapter {
-    constructor(
-        private snapshot: NocturnalSessionSnapshot,
-        private principleId: string,
-        private maxCandidates: number
-    ) {}
-
-    async invokeDreamer(
-        snapshot: NocturnalSessionSnapshot,
-        principleId: string,
-        maxCandidates: number
-    ): Promise<DreamerOutput> {
-        const { invokeStubDreamer } = await import('../../core/nocturnal-trinity.js');
-        return invokeStubDreamer(snapshot, principleId, maxCandidates);
-    }
-
-    async invokePhilosopher(
-        dreamerOutput: DreamerOutput,
-        principleId: string
-    ): Promise<PhilosopherOutput> {
-        const { invokeStubPhilosopher } = await import('../../core/nocturnal-trinity.js');
-        return invokeStubPhilosopher(dreamerOutput, principleId);
-    }
-
-    async invokeScribe(
-        dreamerOutput: DreamerOutput,
-        philosopherOutput: PhilosopherOutput,
-        snapshot: NocturnalSessionSnapshot,
-        principleId: string,
-        telemetry: TrinityTelemetry,
-        config: TrinityConfig
-    ): Promise<import('../../core/nocturnal-trinity.js').TrinityDraftArtifact | null> {
-        // Use stub Scribe
-        const { invokeStubScribe } = await import('../../core/nocturnal-trinity.js');
-        return invokeStubScribe(dreamerOutput, philosopherOutput, snapshot, principleId, telemetry, config);
-    }
-
-    async close(): Promise<void> {
-        // No-op for stubs
-    }
-}
+/* eslint-enable no-unused-vars */
 
 // ─────────────────────────────────────────────────────────────────────────────
 // NocturnalWorkflowManager
@@ -230,15 +141,15 @@ export class NocturnalWorkflowManager implements WorkflowManager {
     private readonly store: WorkflowStore;
 
     /** Tracks completion timestamps for idempotency */
-    private completedWorkflows = new Map<string, number>();
+    private readonly completedWorkflows = new Map<string, number>();
     /** Maps workflowId → spec (needed for finalizeOnce) */
-    private workflowSpecs = new Map<string, SubagentWorkflowSpec<unknown>>();
+    private readonly workflowSpecs = new Map<string, SubagentWorkflowSpec<unknown>>();
     /** Maps workflowId → result (needed for finalizeOnce) */
-    private executionResults = new Map<string, NocturnalResult>();
+    private readonly executionResults = new Map<string, NocturnalResult>();
     /** Maps workflowId → TrinityStageFailure[] (stored before async launch, used in notifyWaitResult) */
-    private pendingTrinityFailures = new Map<string, TrinityStageFailure[]>();
+    private readonly pendingTrinityFailures = new Map<string, TrinityStageFailure[]>();
     /** Maps workflowId → TrinityResult (needed by notifyWaitResult for artifact persistence) */
-    private pendingTrinityResults = new Map<string, TrinityResult>();
+    private readonly pendingTrinityResults = new Map<string, TrinityResult>();
 
     constructor(opts: NocturnalWorkflowOptions) {
         this.workspaceDir = opts.workspaceDir;
@@ -261,7 +172,16 @@ export class NocturnalWorkflowManager implements WorkflowManager {
             metadata?: Record<string, unknown>;
         }
     ): Promise<WorkflowHandle> {
-        const workflowId = this.generateWorkflowId();
+        // #179: Check subagent runtime availability before starting
+        // Other workflow managers (empathy, deep-reflect) have this check
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: TrinityRuntimeAdapter interface doesn't expose api.runtime.subagent, but OpenClawTrinityRuntimeAdapter has it
+        const subagent = (this.runtimeAdapter as any).api?.runtime?.subagent;
+        if (!isSubagentRuntimeAvailable(subagent)) {
+            this.logger.warn(`[PD:NocturnalWorkflow] Subagent runtime unavailable, skipping workflow`);
+            throw new Error(`NocturnalWorkflowManager: subagent runtime unavailable`);
+        }
+
+        const workflowId = NocturnalWorkflowManager.generateWorkflowId();
         const now = Date.now();
 
         const metadata: WorkflowMetadata = {
@@ -286,13 +206,16 @@ export class NocturnalWorkflowManager implements WorkflowManager {
             state: 'active',
             created_at: now,
             updated_at: now,
+            duration_ms: null,
             metadata_json: JSON.stringify(metadata),
         });
         this.store.recordEvent(workflowId, 'nocturnal_started', null, 'active', 'TrinityRuntimeAdapter invoked', { workflowType: 'nocturnal' });
 
         // Extract snapshot and principleId from taskInput.metadata (NOC-07: Trinity async path)
-        const snapshot = options.metadata?.snapshot as import('../../core/nocturnal-trajectory-extractor.js').NocturnalSessionSnapshot | undefined;
+        const snapshot = options.metadata?.snapshot as NocturnalSessionSnapshot | undefined;
         const principleId = options.metadata?.principleId as string | undefined;
+        // Extract painContext for Selector ranking bias
+        const painContext = options.metadata?.painContext as RecentPainContext | undefined;
 
         // Validate required metadata (prevent runtime crashes from undefined snapshot)
         if (!snapshot?.sessionId) {
@@ -304,186 +227,68 @@ export class NocturnalWorkflowManager implements WorkflowManager {
                 state: 'terminal_error' as const,
             };
         }
-        if (!principleId) {
-            this.logger.warn(`[PD:NocturnalWorkflow] Missing principleId in metadata for workflow=${workflowId}, terminating`);
-            this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', 'Missing required metadata: principleId', { workflowId });
-            return {
-                workflowId,
-                childSessionKey: `nocturnal:internal:${workflowId}`,
-                state: 'terminal_error' as const,
-            };
-        }
-
-        // Configure Trinity for async execution (NOC-06, NOC-07)
-        const trinityConfig: TrinityConfig = {
-            useTrinity: true,  // NOC-07: Trinity chain, not single-reflector
-            maxCandidates: 3,
-            useStubs: false,
-            runtimeAdapter: this.runtimeAdapter,
-            stateDir: this.stateDir,
-        };
-
-        // Create mutable telemetry object (passed to invokeScribe and mutated)
-        const telemetry: TrinityTelemetry = {
-            chainMode: 'trinity',
-            usedStubs: false,
-            dreamerPassed: false,
-            philosopherPassed: false,
-            scribePassed: false,
-            candidateCount: 0,
-            selectedCandidateIndex: -1,
-            stageFailures: [],
-        };
-
-        // NOC-07: Launch Trinity async via Promise.resolve().then() WITHOUT awaiting
-        // This offloads the async chain so startWorkflow returns immediately with state='active'
+        // #205: Always use executeNocturnalReflectionAsync for unified pipeline
+        // This ensures the full post-processing flow is always executed:
+        // Selector → Trinity → Arbiter → Executability → Persist → Register
+        //
+        // When principleId is provided, we pass it as principleIdOverride to skip Selector.
+        // When principleId is missing, Selector will choose a principle from training store.
+        this.logger.info(`[PD:NocturnalWorkflow] Calling executeNocturnalReflectionAsync for full pipeline (principleId=${principleId ?? 'auto-select'})`);
+
+        // #213: Wrap fire-and-forget Promise with .catch() to prevent
+        // unhandled promise rejections if anything throws outside the try-catch
+        // (e.g., during parameter construction or environment errors).
         Promise.resolve().then(async () => {
             try {
-                // NOC-15: Track if stub fallback was used
-                let fallbackUsed = false;
-
-                // Step 1: Crash recovery — check for existing stage outputs (NOC-13)
-                // Query WorkflowStore for any existing outputs for this workflowId
-                const existingOutputs = this.store.getStageOutputs(workflowId);
-                const recoveredDreamerOutput = existingOutputs.find(o => o.stage === 'dreamer')?.output as DreamerOutput | undefined;
-                const recoveredPhilosopherOutput = existingOutputs.find(o => o.stage === 'philosopher')?.output as PhilosopherOutput | undefined;
-
-                let dreamerOutput: DreamerOutput;
-                let philosopherOutput: PhilosopherOutput;
-
-                // Step 2: Dreamer — skip if recovered (NOC-12 idempotency)
-                if (recoveredDreamerOutput) {
-                    this.logger.info(`[PD:NocturnalWorkflow] Recovered Dreamer output for workflow=${workflowId}, skipping Dreamer stage`);
-                    dreamerOutput = recoveredDreamerOutput;
-                } else {
-                    // Compute idempotency key BEFORE calling invokeDreamer
-                    const dreamerIdemKey = computeDreamerIdempotencyKey(workflowId, snapshot, principleId, trinityConfig.maxCandidates);
-
-                    // Check idempotency — another concurrent run may have completed this stage
-                    const existingDreamerByKey = this.store.getStageOutputByKey(dreamerIdemKey);
-                    if (existingDreamerByKey) {
-                        this.logger.info(`[PD:NocturnalWorkflow] Found existing Dreamer output by idempotency key for workflow=${workflowId}`);
-                        dreamerOutput = existingDreamerByKey.output as DreamerOutput;
-                    } else {
-                        dreamerOutput = await this.runtimeAdapter.invokeDreamer(snapshot, principleId, trinityConfig.maxCandidates);
-                        // NOC-15: Fallback to stub Dreamer if real Dreamer failed
-                        if (!dreamerOutput.valid || dreamerOutput.candidates.length === 0) {
-                            this.logger.info(`[PD:NocturnalWorkflow] Dreamer failed (${dreamerOutput.reason}), falling back to stub`);
-                            fallbackUsed = true;
-                            const stubAdapter = new StubFallbackRuntimeAdapter(
-                                snapshot,
-                                principleId,
-                                trinityConfig.maxCandidates
-                            );
-                            dreamerOutput = await stubAdapter.invokeDreamer(snapshot, principleId, trinityConfig.maxCandidates);
-                        }
-                        // Persist Dreamer output (NOC-11)
-                        if (dreamerOutput.valid) {
-                            this.store.recordStageOutput(workflowId, 'dreamer', dreamerOutput, dreamerIdemKey);
-                        }
-                    }
-                }
-
-                // Step 3: Philosopher — skip if recovered (NOC-12 idempotency)
-                if (recoveredPhilosopherOutput) {
-                    this.logger.info(`[PD:NocturnalWorkflow] Recovered Philosopher output for workflow=${workflowId}, skipping Philosopher stage`);
-                    philosopherOutput = recoveredPhilosopherOutput;
-                } else {
-                    // Compute idempotency key BEFORE calling invokePhilosopher
-                    const philosopherIdemKey = computePhilosopherIdempotencyKey(workflowId, dreamerOutput);
-
-                    // Check idempotency
-                    const existingPhilosopherByKey = this.store.getStageOutputByKey(philosopherIdemKey);
-                    if (existingPhilosopherByKey) {
-                        this.logger.info(`[PD:NocturnalWorkflow] Found existing Philosopher output by idempotency key for workflow=${workflowId}`);
-                        philosopherOutput = existingPhilosopherByKey.output as PhilosopherOutput;
-                    } else {
-                        philosopherOutput = await this.runtimeAdapter.invokePhilosopher(dreamerOutput, principleId);
-                        // NOC-15: Fallback to stub Philosopher if real Philosopher failed
-                        if (!philosopherOutput.valid || philosopherOutput.judgments.length === 0) {
-                            this.logger.info(`[PD:NocturnalWorkflow] Philosopher failed (${philosopherOutput.reason}), falling back to stub`);
-                            fallbackUsed = true;
-                            const stubAdapter = new StubFallbackRuntimeAdapter(
-                                snapshot,
-                                principleId,
-                                trinityConfig.maxCandidates
-                            );
-                            philosopherOutput = await stubAdapter.invokePhilosopher(dreamerOutput, principleId);
-                        }
-                        // Persist Philosopher output (NOC-11)
-                        if (philosopherOutput.valid) {
-                            this.store.recordStageOutput(workflowId, 'philosopher', philosopherOutput, philosopherIdemKey);
-                        }
+                const result = await executeNocturnalReflectionAsync(
+                    this.workspaceDir,
+                    this.stateDir,
+                    {
+                        runtimeAdapter: this.runtimeAdapter,
+                        trinityConfig: {
+                            useTrinity: true,
+                            maxCandidates: 3,
+                            useStubs: false,
+                            runtimeAdapter: this.runtimeAdapter,
+                            stateDir: this.stateDir,
+                        },
+                        // Pass painContext for Selector ranking bias
+                        painContext,
+                        // Skip Selector if principleId and snapshot are provided
+                        ...(principleId && snapshot ? {
+                            principleIdOverride: principleId,
+                            snapshotOverride: snapshot,
+                        } : {}),
                     }
-                }
-
-                // Step 4: Scribe — always runs (no intermediate Scribe output to persist)
-                const draftArtifact = await this.runtimeAdapter.invokeScribe(
-                    dreamerOutput,
-                    philosopherOutput,
-                    snapshot,
-                    principleId,
-                    telemetry,
-                    trinityConfig
                 );
 
-                // Step 5: Build TrinityResult from stage outcomes
-                const failures: TrinityStageFailure[] = [];
-                if (!dreamerOutput.valid || dreamerOutput.candidates.length === 0) {
-                    failures.push({ stage: 'dreamer', reason: dreamerOutput.reason ?? 'no valid candidates' });
-                }
-                if (!philosopherOutput.valid || philosopherOutput.judgments.length === 0) {
-                    failures.push({ stage: 'philosopher', reason: philosopherOutput.reason ?? 'no judgments produced' });
-                }
-                if (!draftArtifact) {
-                    failures.push({ stage: 'scribe', reason: 'Failed to synthesize artifact' });
-                }
-
-                const trinityResult: TrinityResult = {
-                    success: failures.length === 0 && !!draftArtifact,
-                    artifact: draftArtifact ?? undefined,
-                    telemetry: {
-                        chainMode: 'trinity',
-                        usedStubs: fallbackUsed,  // NOC-15: reflect actual stub usage
-                        dreamerPassed: dreamerOutput.valid && dreamerOutput.candidates.length > 0,
-                        philosopherPassed: philosopherOutput.valid && philosopherOutput.judgments.length > 0,
-                        scribePassed: !!draftArtifact,
-                        candidateCount: dreamerOutput.candidates.length,
-                        selectedCandidateIndex: draftArtifact?.selectedCandidateIndex ?? -1,
-                        stageFailures: failures.map(f => `${f.stage}: ${f.reason}`),
-                    },
-                    failures,
-                    fallbackOccurred: fallbackUsed,  // NOC-15: mark when fallback was triggered
-                };
-
-                // Store for notifyWaitResult and proceed with existing flow
-                this.pendingTrinityResults.set(workflowId, trinityResult);
-                this.pendingTrinityFailures.set(workflowId, failures);
-
-                // Record stage events (NOC-08, already implemented in Phase 07)
-                this.recordStageEvents(workflowId, trinityResult);
-
-                // Drive state transitions (NOC-10)
-                if (trinityResult.success) {
-                    await this.notifyWaitResult(workflowId, 'ok');
+                if (result.success) {
+                    this.store.recordEvent(workflowId, 'nocturnal_completed', null, 'completed', 'Full pipeline completed via executeNocturnalReflectionAsync', {
+                        artifactId: result.diagnostics?.persistedPath,
+                    });
+                    this.completedWorkflows.set(workflowId, Date.now());
                 } else {
-                    const errorMsg = failures.map(f => `${f.stage}: ${f.reason}`).join('; ');
-                    await this.notifyWaitResult(workflowId, 'error', errorMsg);
+                    const reason = result.noTargetSelected ? 'no_target_selected' : 'validation_failed';
+                    this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', reason, {
+                        failures: result.validationFailures,
+                        skipReason: result.skipReason,
+                    });
                 }
             } catch (err) {
-                // Unexpected error - treat as Trinity failure
-                const errorMsg = err instanceof Error ? err.message : String(err);
-                this.pendingTrinityFailures.set(workflowId, [{ stage: 'dreamer' as const, reason: errorMsg }]);
-                await this.notifyWaitResult(workflowId, 'error', errorMsg);
+                this.logger.error(`[PD:NocturnalWorkflow] executeNocturnalReflectionAsync threw: ${String(err)}`);
+                this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', String(err), { workflowId });
             }
+        }).catch((err) => {
+            // #213: Outer catch — catches errors from the fire-and-forget promise
+            // itself (e.g., if the async callback throws before entering try).
+            this.logger.error(`[PD:NocturnalWorkflow] Unhandled error in async pipeline for ${workflowId}: ${String(err)}`);
+            this.store.recordEvent(workflowId, 'nocturnal_failed', null, 'terminal_error', String(err), { workflowId });
         });
 
-        // Return immediately with state='active' (NOC-07)
         return {
             workflowId,
             childSessionKey: `nocturnal:internal:${workflowId}`,
-            runId: undefined,
-            state: 'active',
+            state: 'active' as const,
         };
     }
 
@@ -537,13 +342,13 @@ export class NocturnalWorkflowManager implements WorkflowManager {
         this.markCompleted(workflowId);
     }
 
-    // ─────────────────────────────────────────────────────────────────────────
-    // WorkflowManager Interface: notifyLifecycleEvent (NOC-01, D-10: no-op)
-    // ─────────────────────────────────────────────────────────────────────────
-
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- Reason: interface contract requires this method signature, implementation is a no-op per D-10
     async notifyLifecycleEvent(
+        // eslint-disable-next-line no-unused-vars -- Reason: interface contract requires these params but NocturnalWorkflowManager is a no-op per D-10
         _workflowId: string,
+        // eslint-disable-next-line no-unused-vars -- Reason: interface contract requires these params but NocturnalWorkflowManager is a no-op per D-10
         _event: 'subagent_spawned' | 'subagent_ended',
+        // eslint-disable-next-line no-unused-vars -- Reason: interface contract requires these params but NocturnalWorkflowManager is a no-op per D-10
         _data?: Record<string, unknown>
     ): Promise<void> {
         // D-10: No-op. NocturnalWorkflowManager does not use the wait-on-run pattern.
@@ -574,11 +379,38 @@ export class NocturnalWorkflowManager implements WorkflowManager {
         this.markCompleted(workflowId);
     }
 
+    /**
+     * Force-expire a specific workflow by ID.
+     * Used by evolution-worker when a sleep_reflection task times out (#214).
+     */
+    expireWorkflow(workflowId: string, reason: string): void {
+        this.store.updateWorkflowState(workflowId, 'expired');
+        this.store.recordEvent(
+            workflowId,
+            'nocturnal_expired',
+            'active',
+            'expired',
+            reason,
+            { reason }
+        );
+    }
+
     // ─────────────────────────────────────────────────────────────────────────
     // WorkflowManager Interface: sweepExpiredWorkflows (NOC-05)
     // ─────────────────────────────────────────────────────────────────────────
 
-    async sweepExpiredWorkflows(maxAgeMs = 30 * 60 * 1000): Promise<number> {
+    async sweepExpiredWorkflows(
+        maxAgeMs = 30 * 60 * 1000,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: subagentRuntime param is intentionally any for backward compatibility with callers
+        subagentRuntime?: any,
+        /* eslint-disable no-unused-vars -- Reason: type parameter names are documentation, not actual variables */
+        agentSession?: {
+            resolveStorePath: () => string;
+            loadSessionStore: (storePath: string, opts?: { skipCache?: boolean }) => Record<string, unknown>;
+            saveSessionStore: (storePath: string, store: Record<string, unknown>) => Promise<void>;
+        },
+        /* eslint-enable no-unused-vars */
+    ): Promise<number> {
         const expired = this.store.getExpiredWorkflows(maxAgeMs);
 
         this.logger.info(`[PD:NocturnalWorkflow] sweepExpiredWorkflows: found ${expired.length} expired`);
@@ -591,6 +423,44 @@ export class NocturnalWorkflowManager implements WorkflowManager {
                 this.store.updateWorkflowState(workflow.workflow_id, 'expired');
                 this.store.recordEvent(workflow.workflow_id, 'nocturnal_expired', workflow.state, 'expired', 'TTL expired', { workflowId: workflow.workflow_id });
 
+                // #180 + #188: Cleanup subagent session with gateway-safe fallback
+                if (workflow.child_session_key) {
+                    try {
+                        if (subagentRuntime) {
+                            await subagentRuntime.deleteSession({
+                                sessionKey: workflow.child_session_key,
+                                deleteTranscript: true,
+                            });
+                            this.logger.info(`[PD:NocturnalWorkflow] Cleaned up subagent session: ${workflow.child_session_key}`);
+                        } else if (agentSession) {
+                            // Heartbeat-safe fallback: directly manipulate session store
+                            const storePath = agentSession.resolveStorePath();
+                            const store = agentSession.loadSessionStore(storePath, { skipCache: true });
+                            const normalizedKey = workflow.child_session_key.toLowerCase();
+                            if (store[normalizedKey]) {
+                                delete store[normalizedKey];
+                                await agentSession.saveSessionStore(storePath, store);
+                                this.logger.info(`[PD:NocturnalWorkflow] Cleaned up subagent session via agentSession fallback: ${workflow.child_session_key}`);
+                            }
+                        }
+                    } catch (sessionErr) {
+                        const errMsg = String(sessionErr);
+                        // #188: If gateway-scoped method fails, try agentSession fallback
+                        if (errMsg.includes('gateway request') && agentSession) {
+                            const storePath = agentSession.resolveStorePath();
+                            const store = agentSession.loadSessionStore(storePath, { skipCache: true });
+                            const normalizedKey = workflow.child_session_key.toLowerCase();
+                            if (store[normalizedKey]) {
+                                delete store[normalizedKey];
+                                await agentSession.saveSessionStore(storePath, store);
+                                this.logger.info(`[PD:NocturnalWorkflow] Cleaned up subagent session via agentSession fallback after gateway error: ${workflow.child_session_key}`);
+                            }
+                        } else {
+                            this.logger.warn(`[PD:NocturnalWorkflow] Failed to cleanup session ${workflow.child_session_key}: ${errMsg}`);
+                        }
+                    }
+                }
+
                 // D-06: Clean partial artifact files by workflowId prefix
                 const samplesDir = resolveNocturnalDir(this.workspaceDir, 'SAMPLES');
                 if (fs.existsSync(samplesDir)) {
@@ -644,7 +514,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
             }));
 
         // NOC-16: Compute Trinity stage states from events
-        const trinityStageStates = this.computeTrinityStageStates(allEvents);
+        const trinityStageStates = NocturnalWorkflowManager.computeTrinityStageStates(allEvents);
 
         return {
             workflowId: workflow.workflow_id,
@@ -674,7 +544,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
     // Helper Methods
     // ─────────────────────────────────────────────────────────────────────────
 
-    private generateWorkflowId(): string {
+    private static generateWorkflowId(): string {
         return `wf_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
     }
 
@@ -700,19 +570,19 @@ export class NocturnalWorkflowManager implements WorkflowManager {
      * Compute Trinity stage states from workflow events (NOC-16).
      * Derives current/completed/failed state for each Trinity stage.
      */
-    private computeTrinityStageStates(events: WorkflowEventRow[]): Array<{
+    private static computeTrinityStageStates(events: WorkflowEventRow[]): {
         stage: 'dreamer' | 'philosopher' | 'scribe';
         status: 'pending' | 'running' | 'completed' | 'failed';
         reason?: string;
         completedAt?: number;
-    }> {
-        const stages: Array<'dreamer' | 'philosopher' | 'scribe'> = ['dreamer', 'philosopher', 'scribe'];
-        const result: Array<{
+    }[] {
+        const stages: ('dreamer' | 'philosopher' | 'scribe')[] = ['dreamer', 'philosopher', 'scribe'];
+        const result: {
             stage: 'dreamer' | 'philosopher' | 'scribe';
             status: 'pending' | 'running' | 'completed' | 'failed';
             reason?: string;
             completedAt?: number;
-        }> = [];
+        }[] = [];
 
         for (const stage of stages) {
             const startEvent = events.find(e => e.event_type === `trinity_${stage}_start`);
@@ -725,7 +595,7 @@ export class NocturnalWorkflowManager implements WorkflowManager {
             } else if (failedEvent) {
                 // Stage ran and failed
                 const payload = JSON.parse(failedEvent.payload_json || '{}') as Record<string, unknown>;
-                const failures = payload.failures as Array<{ reason?: string }> | undefined;
+                const failures = payload.failures as { reason?: string }[] | undefined;
                 result.push({
                     stage,
                     status: 'failed',