agenr 3.2.0 → 2026.6.2

package/dist/adapters/skeln/index.d.ts

@@ -1,7 +1,7 @@
 import { TSchema } from 'typebox';
 import { AgentToolResult, AgentMessage } from '@earendil-works/pi-agent-core';
 import { C as ClaimSlotPolicyConfig, a as ClaimSlotPolicy } from '../../claim-slot-policy-CdrW_1l4.js';
-import { E as EntryType, b as RecallPorts, r as ProcedureDatabasePort, t as Entry, u as DatabasePort, v as EpisodeDatabasePort, w as EmbeddingPort, L as LlmPort } from '../../ports-CpzWESmZ.js';
+import { D as DurableKind, b as RecallPorts, v as ProcedureDatabasePort, a as Durable, w as DurableUpdateInput, x as DatabasePort, y as EpisodeDatabasePort, z as EmbeddingPort, L as LlmPort } from '../../ports-C4QkwDBS.js';
 
 /** Minimal branch-entry shape needed for before-turn visibility filtering. */
 interface SkelnBranchEntryLike {
@@ -76,9 +76,9 @@ type AgenrFeatureFlagKey = (typeof AGENR_FEATURE_FLAG_KEYS)[number];
 /**
  * Sparse persisted feature-flag overrides.
  *
- * Only `true` values are written to disk. Explicit `false` is accepted during
- * parse and reflected in resolved runtime flags, but canonicalization strips
- * false entries because every flag defaults to off.
+ * Most flags default to off and are persisted only when explicitly enabled.
+ * `sessionTreeCompaction` defaults to on and is persisted only when explicitly
+ * disabled.
  */
 type AgenrFeatureFlagConfig = Partial<Record<AgenrFeatureFlagKey, boolean>>;
 /**
@@ -92,7 +92,7 @@ type AgenrFeatureFlags = Record<AgenrFeatureFlagKey, boolean>;
 interface ClaimExtractionConfig {
     enabled: boolean;
     confidenceThreshold: number;
-    eligibleTypes: EntryType[];
+    eligibleTypes: DurableKind[];
     /** Maximum preview workers used by cleanup flows that parallelize claim extraction. Defaults to `10`. */
     concurrency?: number;
 }
@@ -109,6 +109,451 @@ interface BeforeTurnDeps {
     embedQuery?: (text: string) => Promise<number[]>;
     /** Optional runtime claim-slot-policy overrides used during claim-aware shaping. */
     slotPolicyConfig?: ClaimSlotPolicyConfig;
+    /** Optional semantic clock used for recall validity and recency decisions. */
+    now?: Date;
+    /**
+     * Optional lookup for active user memory directives.
+     *
+     * When wired, the service drops directive rows from injection and suppresses
+     * any surfaced durable that mentions a directive's blocked topic. Callers that
+     * omit it skip directive abstention entirely.
+     */
+    listActiveAbstainDirectives?: () => Promise<Durable[]>;
+    /**
+     * Optional lookup for active proactive directives with `topic:` triggers.
+     *
+     * When wired, the service may inject matching directives during before-turn
+     * selection before the abstain filter runs.
+     */
+    listActiveTopicProactiveDirectives?: () => Promise<Durable[]>;
+}
+
+/**
+ * Supported dreaming action identifiers.
+ */
+type DreamActionType = "stale" | "merge" | "log_conflict" | "resolve_conflict" | "update_durable" | "insert_durable" | "supersede_durable" | "flag_review" | "skip";
+/**
+ * Audit log record for one action emitted during a dreaming run.
+ */
+interface DreamRunAction {
+    id: string;
+    runId: string;
+    actionType: DreamActionType;
+    durableIds: string[];
+    reasoning: string;
+    details?: Record<string, unknown> | null;
+    createdAt: string;
+}
+
+/**
+ * Core dreaming domain types.
+ */
+
+/** Ordered list of supported dreaming run tiers. */
+declare const DREAM_TIERS: readonly ["light", "standard", "deep"];
+
+/** Union of supported dreaming run tiers. */
+type DreamTier = (typeof DREAM_TIERS)[number];
+/** Ordered list of supported dreaming pipeline stages. */
+declare const DREAM_STAGES: readonly ["scan", "extract", "reconcile", "temporalize", "project", "prune", "apply"];
+
+/** Union of supported dreaming pipeline stages. */
+type DreamStage = (typeof DREAM_STAGES)[number];
+/**
+ * Structured claim-key health snapshot captured before or after one pass.
+ */
+interface ClaimKeyHealthSnapshot {
+    totalDurables: number;
+    activeDurables: number;
+    coverageCount: number;
+    coveragePct: number;
+    missingCount: number;
+    eligibleMissingCount: number;
+    malformedOrNoncanonicalCount: number;
+    suspectCanonicalCount: number;
+    entityFamilyGroupCount: number;
+    suspiciousSingletonAliasCount: number;
+    mixedGroupCount: number;
+    exactKeyMultiActiveClusterCount: number;
+}
+/**
+ * Aggregate repair counts captured during one reconcile run.
+ */
+interface ReconcileRepairCounts {
+    identifiedNormalizations: number;
+    appliedNormalizations: number;
+    identifiedBackfills: number;
+    appliedBackfills: number;
+    identifiedMetadataRewrites: number;
+    appliedMetadataRewrites: number;
+    identifiedEntityFamilyConvergences: number;
+    appliedEntityFamilyConvergences: number;
+    proposalsEmitted: number;
+    skippedNoClaim: number;
+    skippedLowConfidence: number;
+    skippedCollision: number;
+    flaggedAmbiguousProposals: number;
+}
+/** Threshold-only cohort bucket used by shadow sibling-slot-resonance reporting. */
+type ReconcileShadowBucket = "high_density_grounded_family" | "large_grounding_diluted_grounded_family" | "thin_grounded_family_tail" | "relaxed_one_sibling_stable_slot" | "other_grounded_family_alignment";
+/** Stable machine-readable circuit-breaker categories for reconcile runs. */
+type ReconcileCircuitBreakerKind = "claim_key_concentration" | "entity_prefix_concentration" | "collision_spike";
+/** Summary counts for one threshold-only shadow-evaluation bucket. */
+interface ReconcileShadowBucketSummary {
+    bucket: ReconcileShadowBucket;
+    candidateCount: number;
+    resonanceApplicableCount: number;
+    resonanceFiredCount: number;
+    shadowQualifiedCount: number;
+}
+/** Shadow-only sibling-slot-resonance summary captured for threshold-only supported cases. */
+interface ReconcileSiblingSlotResonanceShadowSummary {
+    rule: {
+        supportClass: "trusted_family_grounded_alignment";
+        minFamilyReuseCount: number;
+        minGroundedRatio: number;
+        minConfidence: number;
+        requiresSiblingSlotResonance: true;
+    };
+    thresholdOnlyCandidateCount: number;
+    resonanceApplicableCount: number;
+    resonanceFiredCount: number;
+    shadowQualifiedCount: number;
+    resonanceFiredClaimKeys: string[];
+    shadowQualifiedClaimKeys: string[];
+    buckets: ReconcileShadowBucketSummary[];
+}
+/** Structured reconcile pass summary persisted on the dreaming run. */
+interface ReconcilePassSummary {
+    executionStyle: "autonomous" | "targeted";
+    workingSet: {
+        includeInactive: boolean;
+        project: string | null;
+        type: string | null;
+        claimKeyPrefix: string | null;
+        durableIds: string[];
+    };
+    before: ClaimKeyHealthSnapshot;
+    after: ClaimKeyHealthSnapshot;
+    projectedAfter?: ClaimKeyHealthSnapshot;
+    counts: ReconcileRepairCounts;
+    shadowSiblingSlotResonance?: ReconcileSiblingSlotResonanceShadowSummary | null;
+    circuitBreaker?: {
+        kind: ReconcileCircuitBreakerKind;
+        message: string;
+    } | null;
+}
+/** Machine-readable reason one dreaming pipeline stage was skipped. */
+type DreamStageSkipReason = "light_tier";
+/** Structured record for a pipeline stage skipped by tier policy. */
+interface DreamStageSkipSummary {
+    /** Pipeline stage skipped during the run. */
+    stage: DreamStage;
+    /** Stable reason the stage did not run. */
+    reason: DreamStageSkipReason;
+}
+/** Structured unresolved claim-key proposal persisted for later adjudication. */
+type DreamProposalReviewStatus = "open" | "applied" | "rejected";
+/** Structured unresolved claim-key proposal persisted for later adjudication. */
+interface DreamRunProposal {
+    id: string;
+    runId: string;
+    groupId: string;
+    issueKind: string;
+    scope: "single_durable" | "cluster";
+    durableIds: string[];
+    currentClaimKeys: string[];
+    proposedClaimKeys: string[];
+    rationale: string;
+    confidence: number;
+    source: string;
+    eligibleForApply: boolean;
+    createdAt: string;
+    reviewStatus: DreamProposalReviewStatus;
+    reviewedAt: string | null;
+    reviewReason: string | null;
+    appliedActionCount: number;
+}
+/** Lifecycle states for one dreaming run. */
+type DreamRunStatus = "running" | "completed" | "failed" | "aborted" | "budget_exhausted" | "cost_capped" | "no_work" | "stalled";
+/** Evidence locator referenced by dreaming mutations. */
+interface DreamEvidenceRef {
+    kind: "episode" | "ingest_log" | "durable" | "transcript";
+    locator: string;
+    observedAt?: string;
+}
+/** Structured summary of one extract stage execution. */
+interface DreamExtractSummary {
+    episodesScanned: number;
+    candidatesEmitted: number;
+    newCandidates: number;
+    refineCandidates: number;
+    knownCandidates: number;
+    durablesInserted: number;
+}
+/** Structured summary of one temporalize stage execution. */
+interface DreamTemporalizeSummary {
+    revisionsIdentified: number;
+    revisionsApplied: number;
+    revisionsSkipped: number;
+}
+/** Structured summary of one profile projection stage execution. */
+interface DreamProjectSummary {
+    profileDurableCount: number;
+    directiveCount: number;
+    snapshotId: string | null;
+    applied: boolean;
+}
+/** Structured summary of one deterministic prune stage execution. */
+interface DreamPruneSummary {
+    durablesScanned: number;
+    candidatesIdentified: number;
+    candidatesProtected: number;
+    /**
+     * Count of unprotected candidates eligible to be staled this run. The field
+     * keeps the `candidatesRetirable` name for backward compatibility with the
+     * dreaming-efficiency eval wire contract consumed by `agenr-evals`; it counts
+     * stale-eligible candidates and does not imply a separate retirement concept.
+     */
+    candidatesRetirable: number;
+    durablesStaled: number;
+    dryRun: boolean;
+}
+/** Compute-efficiency counters emitted for eval scoreboard reporting. */
+interface DreamEfficiencySummary {
+    evidenceItemsRead: number;
+    synthesizedDurableMutations: number;
+    costPerSynthesizedDurableUsd: number | null;
+    profileInjectionTokenEstimate: number;
+    recomputeRatio: number;
+}
+/** Scan delta describing unsynthesized evidence since the last successful run. */
+interface DreamScanSummary {
+    episodesSinceLastRun: number;
+    ingestFilesSinceLastRun: number;
+    durablesCreatedSinceLastRun: number;
+    evidenceRefs: DreamEvidenceRef[];
+    unsynthesizedImportanceSum: number;
+}
+/** Minimal persisted completion summary for a dreaming run. */
+interface DreamCompletionSummary {
+    actions_taken: number;
+    /** True when an apply run intentionally skipped the pre-apply database backup. */
+    backupSkipped?: boolean;
+    /** Pipeline stages intentionally skipped by tier policy. */
+    stages_skipped?: DreamStageSkipSummary[];
+    durables_skipped: Array<{
+        durable_id?: string;
+        reason: string;
+    }>;
+    observations: string[];
+    recommendations: string[];
+    scan?: DreamScanSummary;
+    extract?: DreamExtractSummary;
+    reconcile?: ReconcilePassSummary;
+    temporalize?: DreamTemporalizeSummary;
+    project?: DreamProjectSummary;
+    prune?: DreamPruneSummary;
+    efficiency?: DreamEfficiencySummary;
+}
+
+/**
+ * Narrative evidence row surfaced to the extract stage from one episode.
+ */
+interface DreamEpisodeEvidence {
+    id: string;
+    summary: string;
+    startedAt: string;
+    endedAt: string | null;
+    sessionId: string | null;
+    project: string | null;
+}
+/**
+ * Persisted dreaming run metadata returned by history and status queries.
+ */
+interface DreamRunRecord {
+    id: string;
+    tier: DreamTier;
+    project: string | null;
+    startedAt: string;
+    completedAt: string | null;
+    status: DreamRunStatus;
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCostUsd: number;
+    model: string | null;
+    actionsTaken: number;
+    actionsSkipped: number;
+    durablesStaled: number;
+    summaryJson: DreamCompletionSummary | null;
+    error: string | null;
+    dryRun: boolean;
+    config: Record<string, unknown> | null;
+}
+/**
+ * Persisted profile snapshot generated by the dreaming project stage.
+ */
+interface DreamProfileSnapshot {
+    id: string;
+    durableIds: string[];
+    directiveIds: string[];
+    asOf: string;
+    contentHash: string;
+    runId: string | null;
+    createdAt: string;
+}
+/**
+ * Aggregate corpus health summary used by dreaming status tools.
+ */
+interface DreamHealthStats {
+    total: number;
+    byType: Record<string, number>;
+    claimKeyLifecycle: {
+        trusted: number;
+        tentative: number;
+        unresolved: number;
+        noKey: number;
+    };
+    /** Count of durable unresolved dreaming proposals awaiting review. */
+    proposalBacklogCount: number;
+    /** Open proposals that are already safe to apply. */
+    eligibleProposalBacklogCount: number;
+    /** Oldest still-open proposal creation timestamp, when one exists. */
+    oldestOpenProposalCreatedAt: string | null;
+    recency: {
+        last7: number;
+        last30: number;
+        d30To90: number;
+        d90Plus: number;
+    };
+    recall: {
+        never: number;
+        oneToFive: number;
+        fivePlus: number;
+    };
+    quality: {
+        high: number;
+        medium: number;
+        low: number;
+        average: number;
+    };
+}
+/**
+ * Query options for the global proposal backlog view.
+ */
+interface DreamProposalBacklogQuery {
+    state?: DreamProposalReviewStatus | "all";
+    issueKind?: string;
+    eligibleOnly?: boolean;
+    durableId?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Global backlog row that joins one proposal to its originating run metadata.
+ */
+interface DreamProposalBacklogItem {
+    proposal: DreamRunProposal;
+    runPassType: DreamTier;
+    runStartedAt: string;
+    runStatus: DreamRunStatus;
+    runDryRun: boolean;
+}
+/**
+ * Milestone 1 dreaming persistence boundary.
+ */
+interface DreamPort {
+    getDailyCost(now?: Date): Promise<number>;
+    createRun(run: {
+        tier: DreamTier;
+        project?: string;
+        model?: string | null;
+        dryRun: boolean;
+        config?: Record<string, unknown> | null;
+        startedAt?: string;
+    }): Promise<string>;
+    completeRun(runId: string, result: {
+        status: DreamRunStatus;
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCostUsd: number;
+        actionsTaken: number;
+        actionsSkipped: number;
+        durablesStaled: number;
+        summaryJson?: DreamCompletionSummary | null;
+        error?: string | null;
+        completedAt?: string;
+    }): Promise<void>;
+    logRunAction(action: DreamRunAction): Promise<void>;
+    getLastRun(): Promise<DreamRunRecord | null>;
+    getRunHistory(limit?: number): Promise<DreamRunRecord[]>;
+    /** Returns the most recent applied (non-dry-run) `light` runs, newest first. */
+    getRecentAppliedLightRuns(limit: number): Promise<DreamRunRecord[]>;
+    getRunActions(runId: string): Promise<DreamRunAction[]>;
+    getRunProposals(runId: string): Promise<DreamRunProposal[]>;
+    getProposal(proposalId: string): Promise<DreamRunProposal | null>;
+    reviewProposal(input: {
+        proposalId: string;
+        status: Exclude<DreamProposalReviewStatus, "open">;
+        reason: string;
+        reviewedAt?: string;
+        appliedActionCount?: number;
+    }): Promise<boolean>;
+    listProposalBacklog(query?: DreamProposalBacklogQuery): Promise<DreamProposalBacklogItem[]>;
+    getHealthStats(now?: Date): Promise<DreamHealthStats>;
+    getDurable(durableId: string): Promise<Durable | null>;
+    getDurables(durableIds: string[]): Promise<Durable[]>;
+    closeDurableValidity(durableId: string, reason?: string): Promise<boolean>;
+    updateDurable(durableId: string, fields: DurableUpdateInput, options?: {
+        includeInactive?: boolean;
+    }): Promise<boolean>;
+    listReconcileDurables(query: {
+        project?: string;
+        type?: string;
+        claimKeyPrefix?: string;
+        durableIds?: string[];
+        includeInactive?: boolean;
+    }): Promise<Durable[]>;
+    /** Reads recent episode narrative evidence newer than one timestamp. */
+    listEpisodeEvidenceSince(since: string, options?: {
+        project?: string;
+        limit?: number;
+    }): Promise<DreamEpisodeEvidence[]>;
+    /** Lists live host-store durables written during one episode session window. */
+    listSessionHostStoreDurables(sessionId: string, startedAt: string, endedAt: string): Promise<Durable[]>;
+    /** Loads active durables that share one canonical claim key (context-lookup). */
+    findActiveDurablesByClaimKey(claimKey: string): Promise<Durable[]>;
+    /** Returns the subset of normalized content hashes that already exist among active durables. */
+    findExistingNormContentHashes(hashes: string[]): Promise<Set<string>>;
+    /** Inserts one new durable row written by the extract or temporalize stages. */
+    insertDurable(durable: Durable, embedding: number[], contentHash: string): Promise<string>;
+    /** Links one active durable to the newer durable that supersedes it. */
+    supersedeDurable(oldDurableId: string, newDurableId: string, kind?: string, reason?: string): Promise<boolean>;
+    logRunProposal(proposal: DreamRunProposal): Promise<void>;
+    countEpisodesSince(since: string, project?: string): Promise<number>;
+    countIngestFilesSince(since: string): Promise<number>;
+    countDurablesCreatedSince(since: string, project?: string): Promise<number>;
+    sumDurableImportanceCreatedSince(since: string, project?: string): Promise<number>;
+    createProfileSnapshot(snapshot: DreamProfileSnapshot): Promise<void>;
+    getActiveProfileSnapshot(): Promise<DreamProfileSnapshot | null>;
+    updateDreamState(input: {
+        lastSuccessfulRunAt?: string;
+        unsynthesizedImportanceSum?: number;
+        activeProfileSnapshotId?: string;
+        updatedAt: string;
+    }): Promise<void>;
+    /** Attempts to acquire the singleton dreaming run lock row. */
+    tryAcquireRunLock(holderToken: string): Promise<boolean>;
+    /** Refreshes the dreaming run lock heartbeat when the holder token still matches. */
+    heartbeatRunLock(holderToken: string): Promise<boolean>;
+    /** Releases the dreaming run lock when the holder token still matches. */
+    releaseRunLock(holderToken: string): Promise<void>;
+    /**
+     * Runs a callback inside a single write transaction so a group of related
+     * dreaming writes either all commit or all roll back. The callback receives a
+     * port bound to the transaction; nested executors fall back to running inline.
+     */
+    withTransaction<T>(fn: (tx: DreamPort) => Promise<T>): Promise<T>;
 }
 
 /**
@@ -119,6 +564,59 @@ interface EntryRecallEvent {
     sessionKey?: string;
     recalledAt: string;
 }
+/**
+ * Recall summary returned by the trace read model.
+ */
+interface EntryTraceRecallSummary {
+    /** Total persisted recall events for the durable. */
+    totalCount: number;
+    /** Most recent recall events, ordered newest first. */
+    recentEvents: EntryRecallEvent[];
+}
+/**
+ * Dreaming audit action linked to one traced durable.
+ */
+interface EntryTraceDreamAction {
+    id: string;
+    runId: string;
+    actionType: string;
+    reasoning: string;
+    details?: Record<string, unknown> | null;
+    createdAt: string;
+}
+/**
+ * Profile snapshot that included one traced durable.
+ */
+interface EntryTraceProfileSnapshot {
+    id: string;
+    asOf: string;
+    runId: string | null;
+    createdAt: string;
+    role: "profile" | "directive";
+}
+/**
+ * Provenance facts surfaced by the trace read model.
+ */
+interface EntryTraceProvenance {
+    sourceFile?: string;
+    sourceContext?: string;
+    claimKeySource?: string;
+    claimSupportLocator?: string;
+    claimSupportObservedAt?: string;
+    project?: string;
+    userId?: string;
+}
+/**
+ * One chronological audit event in a durable trace timeline.
+ */
+interface EntryTraceTimelineEvent {
+    at: string;
+    kind: "created" | "updated" | "dream" | "recall" | "profile";
+    label: string;
+    detail?: string;
+    runId?: string;
+    actionType?: string;
+}
 /**
  * Narrow claim-family lineage view returned by trace surfaces.
  */
@@ -130,17 +628,21 @@ interface ClaimFamily {
     /** Human-readable explanation of how the slot policy was chosen. */
     slotPolicyReason?: string;
     /** Family rows ordered oldest-first for lineage inspection. */
-    entries: Entry[];
+    entries: Durable[];
 }
 /**
- * Minimal provenance view available from the current v1 schema.
+ * Unified provenance and audit view for one durable.
  */
 interface EntryTrace {
-    entry: Entry;
-    supersededBy?: Entry;
-    supersedes: Entry[];
+    entry: Durable;
+    supersededBy?: Durable;
+    supersedes: Durable[];
     claimFamily?: ClaimFamily;
-    recallEvents: EntryRecallEvent[];
+    recall: EntryTraceRecallSummary;
+    provenance: EntryTraceProvenance;
+    dreamActions: EntryTraceDreamAction[];
+    profileSnapshots: EntryTraceProfileSnapshot[];
+    timeline: EntryTraceTimelineEvent[];
 }
 /**
  * Aggregate memory status facts used by host memory runtimes.
@@ -160,13 +662,13 @@ interface MemoryRepository {
      * @param subject - Free-form subject text to resolve.
      * @returns Matching entry, or `null` when no match exists.
      */
-    findEntryBySubject(subject: string): Promise<Entry | null>;
+    findEntryBySubject(subject: string): Promise<Durable | null>;
     /**
      * Finds the most recently created entry from any state.
      *
      * @returns Newest entry, or `null` when none exist.
      */
-    findMostRecentEntry(): Promise<Entry | null>;
+    findMostRecentEntry(): Promise<Durable | null>;
     /**
      * Loads the current trace view for one entry.
      *
@@ -632,7 +1134,7 @@ interface ResolvedWorkingScope extends WorkingScope {
 /**
  * Artifact kinds accepted by schema v12.
  */
-declare const SESSION_ARTIFACT_KINDS: readonly ["continuity_summary", "recent_session", "compaction_checkpoint", "branch_abandonment", "session_episode"];
+declare const SESSION_ARTIFACT_KINDS: readonly ["compaction_checkpoint", "branch_abandonment", "session_episode"];
 /**
  * Host transition reasons that create session-lineage edges.
  */
@@ -1365,6 +1867,15 @@ interface WorkingMemoryService {
     renderProjection(input: string | WorkingProjectionRequest): Promise<WorkingContextProjection>;
 }
 
+/** Active profile snapshot metadata used by session-start selection. */
+interface SessionStartProfileSnapshot {
+    id: string;
+    durableIds: string[];
+    directiveIds: string[];
+    asOf: string;
+    runId: string | null;
+    createdAt: string;
+}
 /**
  * Feature-scoped durable-memory lookup contract used by session-start selection.
  */
@@ -1375,7 +1886,21 @@ interface SessionStartRepository {
      * @param limit - Maximum number of core entries to return.
      * @returns Ordered active core entries.
      */
-    listCoreEntries(limit: number): Promise<Entry[]>;
+    listCoreEntries(limit: number, now?: Date): Promise<Durable[]>;
+    /**
+     * Loads the active profile snapshot when it is fresh enough.
+     *
+     * @param maxAgeMs - Maximum snapshot age in milliseconds.
+     * @returns Fresh active snapshot, or null.
+     */
+    getActiveProfileSnapshot(maxAgeMs: number, now?: Date): Promise<SessionStartProfileSnapshot | null>;
+    /**
+     * Hydrates active durables by id while preserving the caller's id order.
+     *
+     * @param ids - Ordered durable ids to hydrate.
+     * @returns Hydrated active durables in requested order.
+     */
+    listEntriesByIds(ids: string[]): Promise<Durable[]>;
 }
 /**
  * Dependencies needed by the app-layer session-start service.
@@ -1387,6 +1912,20 @@ interface SessionStartDeps {
     recall: RecallPorts;
     /** Optional runtime claim-slot-policy overrides used during claim-aware shaping. */
     slotPolicyConfig?: ClaimSlotPolicyConfig;
+    /** Optional semantic clock used for validity, freshness, and recall decisions. */
+    now?: Date;
+    /**
+     * Optional lookup for active user memory directives.
+     *
+     * When wired, the service drops directive rows from injection and suppresses
+     * any surfaced durable that mentions a directive's blocked topic. Callers that
+     * omit it skip directive abstention entirely.
+     */
+    listActiveAbstainDirectives?: () => Promise<Durable[]>;
+    /** Optional lookup for proactive session-start directives. */
+    listActiveProactiveDirectives?: () => Promise<Durable[]>;
+    /** Optional session-memory repository used for predecessor artifact recall. */
+    sessionMemoryRepository?: SessionMemoryRepository;
 }
 
 /**
@@ -1438,6 +1977,13 @@ interface PluginWorkingContextMemoryPolicyConfig {
     /** Enables or disables automatic working-context injection. Defaults to true when working memory is enabled. */
     enabled?: boolean;
 }
+/**
+ * Episode-write overrides for automatic OpenClaw episode capture.
+ */
+interface PluginEpisodeMemoryPolicyConfig {
+    /** Enables or disables automatic episode writes. Defaults to true. */
+    enabled?: boolean;
+}
 /**
  * Memory-policy settings shared by host plugin adapters, including injection knobs.
  */
@@ -1448,6 +1994,8 @@ interface PluginInjectionMemoryPolicyConfig extends PluginMemoryPolicyConfig {
     beforeTurn?: PluginBeforeTurnMemoryPolicyConfig;
     /** Working-context overrides for transient per-turn WIP injection. */
     workingContext?: PluginWorkingContextMemoryPolicyConfig;
+    /** Episode-write overrides for automatic OpenClaw/Skeln episode capture. */
+    episodes?: PluginEpisodeMemoryPolicyConfig;
 }
 /**
  * Infrastructure path overrides shared by host plugin adapters.
@@ -1490,6 +2038,7 @@ interface PluginMemoryRuntimeServices {
     episodes: EpisodeDatabasePort;
     procedures: ProcedureDatabasePort;
     memory: MemoryRepository;
+    dreaming: DreamPort;
     workingMemoryRepository?: WorkingMemoryRepository;
     sessionMemoryRepository?: SessionMemoryRepository;
     sessionStart: SessionStartDeps;
@@ -1588,33 +2137,51 @@ interface ModelConfig {
     model?: string;
 }
 /**
- * Per-pass surgeon configuration.
+ * Prune-stage protection configuration for dreaming runs.
  */
-interface SurgeonPassConfig {
-    /** Protect entries recalled within this many days. */
+interface DreamingPruneConfig {
+    /** Protect durables recalled within this many days. */
     protectRecalledDays?: number;
-    /** Protect entries at or above this importance. */
+    /** Protect durables at or above this importance. */
     protectMinImportance?: number;
-    /** Skip entries evaluated by surgeon in the last N days. */
-    skipRecentlyEvaluatedDays?: number;
 }
 /**
- * Surgeon module configuration persisted in `config.json`.
+ * Dreaming module configuration persisted in `config.json`.
  */
-interface SurgeonConfig {
-    /** Model override for surgeon runs. */
+interface DreamingConfig {
+    /** Model override for dreaming runs. */
     model?: ModelConfig;
-    /** Maximum cost per run in USD. */
-    costCap?: number;
-    /** Maximum total surgeon cost in the last 24 hours. */
+    /** Maximum total dreaming cost in the last 24 hours. */
     dailyCostCap?: number;
-    /** Context token limit override. */
-    contextLimit?: number;
-    /** Custom instructions appended to the surgeon system prompt. */
-    customInstructions?: string;
-    /** Per-pass configuration. */
-    passes?: {
-        retirement?: SurgeonPassConfig;
+    tiers?: {
+        light?: {
+            enabled?: boolean;
+        };
+        standard?: {
+            enabled?: boolean;
+        };
+        deep?: {
+            enabled?: boolean;
+            intervalHours?: number;
+        };
+    };
+    stages?: {
+        extract?: {
+            maxSessionsPerRun?: number;
+            lightMaxSessionsPerRun?: number;
+            contextLookup?: {
+                enabled?: boolean;
+            };
+        };
+        project?: {
+            maxProfileDurables?: number;
+        };
+        prune?: DreamingPruneConfig;
+    };
+    triggers?: {
+        postSessionLightDream?: boolean;
+        importanceThreshold?: number;
+        minIntervalMinutes?: number;
     };
 }
 /**
@@ -1657,8 +2224,8 @@ interface AgenrConfigInput {
     crossEncoderModel?: ModelConfig;
     /** Best-effort claim-key extraction settings. */
     claimExtraction?: AgenrClaimExtractionConfig;
-    /** Surgeon module configuration. */
-    surgeon?: SurgeonConfig;
+    /** Dreaming module configuration. */
+    dreaming?: DreamingConfig;
     /** Staged rollout feature flags. All default to false. */
     features?: AgenrFeatureFlagConfig;
     /** Database file path. */
@@ -1907,6 +2474,18 @@ interface AgenrSkelnMemoryController {
     executeWorkCommand(context: ExtensionContext, params: AgenrSkelnWorkCommandParams): Promise<AgenrSkelnWorkCommandOutcome>;
 }
 
+/**
+ * Tracks lifecycle intake writes that prompt injection depends on.
+ */
+interface SessionLifecycleIntakeTracker {
+    /** Records one pending lifecycle intake promise for the session identity. */
+    track(sessionId: string | undefined, sessionKey: string | undefined, work: Promise<void>): Promise<void>;
+    /** Waits for any pending lifecycle intake for the session identity. */
+    wait(sessionId: string | undefined, sessionKey: string | undefined): Promise<void>;
+    /** Waits for pending intake, then clears tracked state for the session identity. */
+    clear(sessionId: string | undefined, sessionKey: string | undefined): Promise<void>;
+}
+
 /**
  * Structured tracking facts returned by the session-start tracker.
  */
@@ -1932,21 +2511,18 @@ interface SessionStartTracker {
      * @returns Tracking facts for the attempted session-start event.
      */
     consume(sessionId?: string, sessionKey?: string): SessionStartConsumeResult;
-    /**
-     * Remembers a session-start transition emitted by the host.
-     *
-     * @param sessionId - New ephemeral host session identifier.
-     * @param sessionKey - Stable host session key for the active lane.
-     * @param resumedFrom - Previous session identifier when the host provides it.
-     */
-    rememberSessionStart(sessionId?: string, sessionKey?: string, resumedFrom?: string): void;
-    /**
-     * Returns the predecessor session identifier remembered for a new session.
-     *
-     * @param sessionId - New ephemeral host session identifier lookup.
-     * @returns Previous session identifier, or `undefined` when unavailable.
-     */
-    getResumedFrom(sessionId?: string): string | undefined;
+}
+
+/**
+ * Tracks which compaction artifacts were already injected into prompts.
+ */
+interface CompactionPromptTracker {
+    /** Returns whether one artifact should be injected for the active session. */
+    shouldInject(sessionId: string | undefined, sessionKey: string | undefined, artifactSourceId: string): boolean;
+    /** Records one injected compaction artifact for the active session. */
+    markInjected(sessionId: string | undefined, sessionKey: string | undefined, artifactSourceId: string): void;
+    /** Clears tracked compaction prompt state for one session identity. */
+    clear(sessionId: string | undefined, sessionKey: string | undefined): void;
 }
 
 /** Describes one agenr memory surface observed during a prompt turn. */
@@ -1985,6 +2561,8 @@ interface AgenrSkelnBeforeAgentStartResult {
 interface AgenrSkelnBeforeAgentStartDeps {
     servicesPromise: Promise<AgenrSkelnServices>;
     sessionStartTracker: SessionStartTracker;
+    compactionPromptTracker: CompactionPromptTracker;
+    lifecycleIntakeTracker: SessionLifecycleIntakeTracker;
     resolveScope: (context: ExtensionContext) => Promise<AgenrSkelnSessionScope>;
 }
 /**