@duetso/agent 0.1.133 → 0.1.136

package/dist/src/memory/observational.d.ts

@@ -3,6 +3,7 @@ import type { Model, Usage } from "@earendil-works/pi-ai";
 import { type WireGuardHorizon } from "../turn-runner/wire-shaping.js";
 import type { MemoryContextCache } from "./store.js";
 import type { MemorySession } from "./session.js";
+import { type SessionObservationsSnapshot } from "./storage.js";
 import type { Observation, ObservationalMemoryActivityEvent, ObservationalMemorySettings, ObservationalMemorySettingsInput } from "../types/memory.js";
 import { type RawMemoryMessage } from "./observational-prompts.js";
 /**
@@ -224,6 +225,192 @@ export declare function optimizeObservationsForContext(observations: string): st
  * message list whether or not the transform has run.
  */
 export declare function stripObservationalContextMessages(messages: AgentMessage[]): AgentMessage[];
+/**
+ * Sentinel session id used by `reflectAllObservations` to stamp the
+ * reflection rows produced from the cross-session pool. Lets the
+ * loader/UI distinguish a global prune-reflection from a per-session one
+ * without needing a new column.
+ */
+export declare const GLOBAL_REFLECTION_SESSION_ID = "__global_reflection__";
+/**
+ * Default minimum age, in days, that a raw observation must reach before
+ * the global reflect prune (`duet memory reflect`) is allowed to fold it
+ * into a reflection row and delete the original.
+ *
+ * --- Why a min-age gate exists (read before changing) -----------------
+ *
+ * The global prune *deletes* the eligible source rows after condensing
+ * them. If a long-lived session is later resumed and finds its own local
+ * observation rows wiped, the runner's `getUnobservedMessageTail` loses
+ * its observation-group range markers — so the next observer call treats
+ * the entire session tail as unobserved and re-observes only the newest
+ * `FIXED_OBSERVER_BUDGETS.maxTranscriptTokens` (~35k tokens) of raw
+ * messages. Everything older than that newest slice is silently dropped
+ * by `trimMessagesToTranscriptBudget`, which walks newest→oldest. For
+ * sessions that had accumulated rich local condensation, that older
+ * content is genuinely lost: the actor's wire eviction horizon already
+ * shaped those messages off-wire, so they cannot be re-observed from the
+ * raw tail. The global reflection row preserves cross-session themes,
+ * but not the session-specific specifics.
+ *
+ * 3 days is the line where the cost-of-loss flips. After ~3 days a human
+ * no longer remembers session specifics anyway, only the higher-level
+ * shape — which is what the reflection row captures. Up to 3 days, the
+ * specifics still matter for resume continuity, so we hold those rows
+ * untouched.
+ *
+ * --- Alternatives considered and rejected (May 2026) ------------------
+ *
+ *   1. *Append-only with high-water-mark watermark.* Never delete; just
+ *      keep appending reflection rows tagged `global-prune`. Recall
+ *      ranks them above raw rows via `reflectionBias`. Pro: zero risk of
+ *      resume info loss. Con: the pool grows unbounded over time and we
+ *      still pay retrieval cost over every stale raw row that the
+ *      reflection already supersedes. Rejected because the user
+ *      explicitly wanted the pool to stay small.
+ *
+ *   2. *Per-session reflect+replace, batched by `session_id`.* Preserves
+ *      attribution. Rejected because the whole point of the global
+ *      prune is *cross-session* dedup; grouping by session forfeits
+ *      that. Used only by the in-session reflector
+ *      (`reflectObservations`).
+ *
+ *   3. *Reflect on existing reflections too.* Pro: keeps total row count
+ *      bounded across many reflect runs. Rejected because reflections
+ *      of reflections collapse already-condensed text into vaguer text,
+ *      losing specificity each pass. The current shape preserves rows
+ *      where `kind === "reflection"` (skipped as input and skipped from
+ *      the deletion set), so older reflections accumulate but never
+ *      degrade. A separate `duet memory compact` can later GC stale
+ *      reflections by `lastUsedAt`.
+ *
+ *   4. *Smaller min-age (e.g. 1 day) for faster pruning.* Rejected
+ *      because typical bursty work patterns (a 2-day investigation, a
+ *      multi-day refactor) would lose mid-thread specifics exactly when
+ *      a resume is most likely to need them.
+ */
+export declare const DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS = 3;
+export declare const DEFAULT_GLOBAL_REFLECT_MIN_AGE_MS: number;
+export interface ReflectAllOptions {
+    session: MemorySession;
+    /**
+     * The snapshot to reflect. Callers (the CLI) read the pool once so they
+     * can also print stats before the model call; passing the snapshot in
+     * avoids a redundant second `SELECT` inside this function.
+     */
+    snapshot: SessionObservationsSnapshot;
+    settings: ObservationalMemorySettings;
+    model: string;
+    /**
+     * Override the target token budget for the reflected log produced by
+     * each batch's reflector call. Defaults to
+     * `settings.reflection.bufferActivation` so each batch behaves the
+     * same way an in-session reflection does: condense to roughly the
+     * half-trigger budget, leaving headroom before the next reflection.
+     */
+    targetTokens?: number;
+    /**
+     * Maximum input tokens packed into a single reflector batch. Defaults
+     * to `settings.reflection.observationTokens` — the same trigger the
+     * in-session reflector uses, so each global-prune batch is the size
+     * of one natural reflection round. Multiple batches fire sequentially
+     * when the eligible pool is larger; cross-session dedup still works
+     * because batches are packed in chronological order, not grouped by
+     * `sessionId`.
+     */
+    batchTokens?: number;
+    /**
+     * Minimum age, in milliseconds, before a non-reflection row is
+     * eligible for prune. Defaults to {@link DEFAULT_GLOBAL_REFLECT_MIN_AGE_MS}.
+     * See the {@link DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS} doc for the
+     * tradeoffs behind this default.
+     */
+    minAgeMs?: number;
+    /**
+     * Override of "now" for eligibility comparison. Defaults to
+     * `Date.now()`. Tests pin this so the cutoff is deterministic.
+     */
+    now?: number;
+    /**
+     * When true, do not write the reflected rows back. The function still
+     * runs the reflector model(s) and returns the result so callers can
+     * preview the prune (`duet memory reflect --dry-run`).
+     */
+    dryRun?: boolean;
+    onUsage?: (usage: Usage) => void;
+}
+export interface ReflectAllResult {
+    /** Observations as they existed before the reflect call. */
+    before: Observation[];
+    /**
+     * Rows preserved verbatim — either too fresh (younger than
+     * `minAgeMs`) or already reflection rows. These are written back
+     * untouched.
+     */
+    preserved: Observation[];
+    /**
+     * Raw observation rows that were eligible for condensation and were
+     * folded into one of `reflections`. When `written` is true, these
+     * rows have been deleted from the durable store.
+     */
+    eligible: Observation[];
+    /** One reflection row per batch processed. Empty if nothing was eligible. */
+    reflections: Observation[];
+    /** Whether the pool was rewritten (false on dryRun or when reflections is empty). */
+    written: boolean;
+}
+/** Pure-plan output of {@link planReflectionBatches}. */
+export interface ReflectionBatch {
+    observations: Observation[];
+    estimatedTokens: number;
+}
+export interface PlanReflectionBatchesOptions {
+    /** Observations older than this (`createdAt <= cutoff`) are eligible. */
+    cutoff: number;
+    /** Maximum content tokens packed into a single batch. */
+    batchTokens: number;
+}
+/**
+ * Partition a snapshot into rows preserved verbatim vs eligible batches
+ * fed to the reflector. Pure function — no I/O, no model calls — so the
+ * batching/eligibility rules can be unit-tested without docker/LLM.
+ *
+ * Rules:
+ *   - `kind === "reflection"` rows are always preserved (we never
+ *     reflect on reflections; see option 3 in the
+ *     {@link DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS} comment).
+ *   - Non-reflection rows with `createdAt > cutoff` are preserved (too
+ *     fresh; resume-info-loss risk too high).
+ *   - Everything else is eligible. Eligible rows are sorted by
+ *     `createdAt` ascending and greedily packed into batches whose
+ *     total `estimateTokens(content)` stays ≤ `batchTokens`. A single
+ *     oversize row is allowed to occupy its own batch so we never drop
+ *     rows just because they exceed the cap on their own.
+ */
+export declare function planReflectionBatches(observations: readonly Observation[], options: PlanReflectionBatchesOptions): {
+    preserved: Observation[];
+    batches: ReflectionBatch[];
+};
+/**
+ * Cross-session reflect: condense each eligible batch of raw
+ * observations through the reflector and replace the eligible rows
+ * with one reflection row per batch. Preserved rows (fresh
+ * observations and existing reflections) survive verbatim. Used by
+ * `duet memory reflect` to prune the global memory store.
+ *
+ * Unlike `reflectObservations`, this can touch rows across all
+ * sessions — the caller is asking for a global prune, not a
+ * per-session compaction. See {@link DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS}
+ * for the resume-info-loss tradeoffs that motivated the min-age gate
+ * and the "never reflect on reflections" rule.
+ *
+ * Returns `undefined` only when there is nothing eligible *and* nothing
+ * preserved (empty store). When the store has only fresh/reflection
+ * rows, returns a result with empty `eligible`/`reflections` and
+ * `written: false` so callers can report "nothing to prune" without
+ * conflating it with an empty store.
+ */
+export declare function reflectAllObservations(options: ReflectAllOptions): Promise<ReflectAllResult | undefined>;
 export declare function enforceObservationTokenBudget(options: {
     text: string;
     targetTokens: number;

package/dist/src/memory/observational.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observational.d.ts","sourceRoot":"","sources":["../../../src/memory/observational.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAgB,KAAK,EAAe,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAIrF,OAAO,EAQL,KAAK,gBAAgB,EACtB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAOlD,OAAO,KAAK,EACV,WAAW,EAEX,gCAAgC,EAChC,2BAA2B,EAC3B,gCAAgC,EACjC,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EAYL,KAAK,gBAAgB,EACtB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;IAC/B,iDAAiD;;IAEjD,2DAA2D;;IAE3D,yCAAyC;;CAEjC,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IACjC;;;;;;;;;;;;;;OAcG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;OAIG;;CAEK,CAAC;AAeX,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,uBAAuB,EAAE,MAAM,CAAC;QAChC,gBAAgB,EAAE,MAAM,CAAC;QACzB,sBAAsB,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,UAAU,EAAE;QACV,iBAAiB,EAAE,MAAM,CAAC;QAC1B,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,GAAG,oBAAoB,CAqBlF;AAMD,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAoDD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;CAClC;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8C;gBAE7D,MAAM,EAAE,wBAAwB;IAkB5C,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC;IAYxC,aAAa,IAAI,MAAM,EAAE;CAG1B;AAED,MAAM,WAAW,oCAAoC;IACnD,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,gCAAgC,CAAC;IAC5C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;;;;;;OASG;IACH,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC;IACvB,2GAA2G;IAC3G,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,gCAAgC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,KAAK,IAAI,CAAC;CAChE;AAED,MAAM,WAAW,+BAA+B;IAC9C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,WAAW,EAAE,WAAW,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAChD,gBAAgB,EAAE,MAAM,EACxB,KAAK,CAAC,EAAE,gCAAgC,GACvC,2BAA2B,CAwB7B;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI,CAwB/F;AAED,wBAAgB,mCAAmC,CAAC,OAAO,EAAE,oCAAoC,IAIjF,UAAU,YAAY,EAAE,KAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmEjE;AAoCD,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,+BAA+B,CAAC,CA+E1C;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS3E;AAoCD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAgRD,wBAAsB,6BAA6B,CAAC,OAAO,EAAE;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC,MAAM,CAAC,CAclB;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAY3F;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,gBAAgB,EAAE,MAAM,GACvB,gBAAgB,EAAE,CAmBpB;AAqBD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,YAAY,EAAE,WAAW,EAAE,GAC1B,gBAAgB,EAAE,CAMpB;AA0BD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAI/E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,GAAG,SAAS,CAgBrF;AAuOD,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAWrE;AAcD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"observational.d.ts","sourceRoot":"","sources":["../../../src/memory/observational.ts"],"names":[],"mappings":"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"}

package/dist/src/memory/observational.js

@@ -2,7 +2,7 @@ import { nanoid } from "nanoid";
 import { Type } from "typebox";
 import { generateStructuredOutput } from "../core/structured-output.js";
 import { applyEvictionHorizon, calculateWireBytes, calculateWireTokens, IMAGE_WIRE_TOKEN_ESTIMATE, findEvictionHorizon, WIRE_BYTE_TARGET, WIRE_BYTE_TRIGGER, } from "../turn-runner/wire-shaping.js";
-import { appendObservation, bumpLastUsed, readSessionObservations, replaceSessionObservations, } from "./storage.js";
+import { appendObservation, bumpLastUsed, readSessionObservations, replaceAllObservations, replaceSessionObservations, } from "./storage.js";
 import { parseObservationGroups, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, stripObservationGroups, wrapInObservationGroup, } from "./observation-groups.js";
 import { GLOBAL_OBSERVATIONS_HEADING, GLOBAL_OBSERVATIONS_HINT, LOCAL_OBSERVATIONS_HEADING, LOCAL_OBSERVATIONS_HINT, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTINUATION_HINT, buildObserverPrompt, buildObserverSystemPrompt, buildReflectorPrompt, buildReflectorSystemPrompt, } from "./observational-prompts.js";
 /**
@@ -135,9 +135,15 @@ const observerResultSchema = Type.Object({
     usedObservationIds: Type.Optional(Type.Array(Type.String(), {
         description: "Ids of prior memories from the [memory id: mem_...] markers in the existing observations block whose content actually informed the assistant's response in this exchange. Drives the lastUsedAt freshness signal so reused memories keep surfacing. When multiple existing memories describe the same fact, cite only the single best one (most specific, highest priority, most recent) — never every duplicate, otherwise stale duplicates get uniformly refreshed and decay-ranking breaks. Omit or return [] when no prior memory was leaned on.",
     })),
-    currentTask: Type.Optional(Type.String({ description: "Current task state distilled for continuity." })),
-    suggestedContinuation: Type.Optional(Type.String({ description: "Hint for the actor's next response after context compression." })),
-    threadTitle: Type.Optional(Type.String({ description: "Short 2-5 word title when thread title generation is requested." })),
+    currentTask: Type.Optional(Type.String({
+        description: "Current task state distilled for continuity.",
+    })),
+    suggestedContinuation: Type.Optional(Type.String({
+        description: "Hint for the actor's next response after context compression.",
+    })),
+    threadTitle: Type.Optional(Type.String({
+        description: "Short 2-5 word title when thread title generation is requested.",
+    })),
 });
 const observerResultTool = {
     name: "recordObservations",
@@ -342,7 +348,10 @@ export async function updateObservationalMemory(options) {
         : { observations: [], estimatedObservationTokens: 0 };
     const globalPack = options.memory.getContextPack().global;
     const unobservedMessages = getUnobservedMessageTail(rawMessages, localSnapshot.observations);
-    const result = { observations: [], reflections: [] };
+    const result = {
+        observations: [],
+        reflections: [],
+    };
     if (unobservedMessages.length > 0) {
         emitMemoryActivity(options.onActivity, {
             phase: "observation",
@@ -555,6 +564,240 @@ async function reflectObservations(args) {
     await replaceSessionObservations(session, sessionId, [reflected]);
     return [reflected];
 }
+/**
+ * Sentinel session id used by `reflectAllObservations` to stamp the
+ * reflection rows produced from the cross-session pool. Lets the
+ * loader/UI distinguish a global prune-reflection from a per-session one
+ * without needing a new column.
+ */
+export const GLOBAL_REFLECTION_SESSION_ID = "__global_reflection__";
+/**
+ * Default minimum age, in days, that a raw observation must reach before
+ * the global reflect prune (`duet memory reflect`) is allowed to fold it
+ * into a reflection row and delete the original.
+ *
+ * --- Why a min-age gate exists (read before changing) -----------------
+ *
+ * The global prune *deletes* the eligible source rows after condensing
+ * them. If a long-lived session is later resumed and finds its own local
+ * observation rows wiped, the runner's `getUnobservedMessageTail` loses
+ * its observation-group range markers — so the next observer call treats
+ * the entire session tail as unobserved and re-observes only the newest
+ * `FIXED_OBSERVER_BUDGETS.maxTranscriptTokens` (~35k tokens) of raw
+ * messages. Everything older than that newest slice is silently dropped
+ * by `trimMessagesToTranscriptBudget`, which walks newest→oldest. For
+ * sessions that had accumulated rich local condensation, that older
+ * content is genuinely lost: the actor's wire eviction horizon already
+ * shaped those messages off-wire, so they cannot be re-observed from the
+ * raw tail. The global reflection row preserves cross-session themes,
+ * but not the session-specific specifics.
+ *
+ * 3 days is the line where the cost-of-loss flips. After ~3 days a human
+ * no longer remembers session specifics anyway, only the higher-level
+ * shape — which is what the reflection row captures. Up to 3 days, the
+ * specifics still matter for resume continuity, so we hold those rows
+ * untouched.
+ *
+ * --- Alternatives considered and rejected (May 2026) ------------------
+ *
+ *   1. *Append-only with high-water-mark watermark.* Never delete; just
+ *      keep appending reflection rows tagged `global-prune`. Recall
+ *      ranks them above raw rows via `reflectionBias`. Pro: zero risk of
+ *      resume info loss. Con: the pool grows unbounded over time and we
+ *      still pay retrieval cost over every stale raw row that the
+ *      reflection already supersedes. Rejected because the user
+ *      explicitly wanted the pool to stay small.
+ *
+ *   2. *Per-session reflect+replace, batched by `session_id`.* Preserves
+ *      attribution. Rejected because the whole point of the global
+ *      prune is *cross-session* dedup; grouping by session forfeits
+ *      that. Used only by the in-session reflector
+ *      (`reflectObservations`).
+ *
+ *   3. *Reflect on existing reflections too.* Pro: keeps total row count
+ *      bounded across many reflect runs. Rejected because reflections
+ *      of reflections collapse already-condensed text into vaguer text,
+ *      losing specificity each pass. The current shape preserves rows
+ *      where `kind === "reflection"` (skipped as input and skipped from
+ *      the deletion set), so older reflections accumulate but never
+ *      degrade. A separate `duet memory compact` can later GC stale
+ *      reflections by `lastUsedAt`.
+ *
+ *   4. *Smaller min-age (e.g. 1 day) for faster pruning.* Rejected
+ *      because typical bursty work patterns (a 2-day investigation, a
+ *      multi-day refactor) would lose mid-thread specifics exactly when
+ *      a resume is most likely to need them.
+ */
+export const DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS = 3;
+export const DEFAULT_GLOBAL_REFLECT_MIN_AGE_MS = DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS * 24 * 60 * 60 * 1000;
+/**
+ * Partition a snapshot into rows preserved verbatim vs eligible batches
+ * fed to the reflector. Pure function — no I/O, no model calls — so the
+ * batching/eligibility rules can be unit-tested without docker/LLM.
+ *
+ * Rules:
+ *   - `kind === "reflection"` rows are always preserved (we never
+ *     reflect on reflections; see option 3 in the
+ *     {@link DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS} comment).
+ *   - Non-reflection rows with `createdAt > cutoff` are preserved (too
+ *     fresh; resume-info-loss risk too high).
+ *   - Everything else is eligible. Eligible rows are sorted by
+ *     `createdAt` ascending and greedily packed into batches whose
+ *     total `estimateTokens(content)` stays ≤ `batchTokens`. A single
+ *     oversize row is allowed to occupy its own batch so we never drop
+ *     rows just because they exceed the cap on their own.
+ */
+export function planReflectionBatches(observations, options) {
+    const preserved = [];
+    const eligible = [];
+    for (const observation of observations) {
+        if (observation.kind === "reflection") {
+            preserved.push(observation);
+            continue;
+        }
+        if (observation.createdAt > options.cutoff) {
+            preserved.push(observation);
+            continue;
+        }
+        eligible.push(observation);
+    }
+    eligible.sort((a, b) => a.createdAt - b.createdAt);
+    const batches = [];
+    let current = [];
+    let currentTokens = 0;
+    for (const observation of eligible) {
+        const tokens = estimateTokens(observation.content);
+        // Roll over to a new batch when adding this row would exceed the
+        // cap — unless the current batch is empty, in which case we keep
+        // the (oversize) row so it isn't silently dropped.
+        if (current.length > 0 && currentTokens + tokens > options.batchTokens) {
+            batches.push({ observations: current, estimatedTokens: currentTokens });
+            current = [];
+            currentTokens = 0;
+        }
+        current.push(observation);
+        currentTokens += tokens;
+    }
+    if (current.length > 0) {
+        batches.push({ observations: current, estimatedTokens: currentTokens });
+    }
+    return { preserved, batches };
+}
+/**
+ * Cross-session reflect: condense each eligible batch of raw
+ * observations through the reflector and replace the eligible rows
+ * with one reflection row per batch. Preserved rows (fresh
+ * observations and existing reflections) survive verbatim. Used by
+ * `duet memory reflect` to prune the global memory store.
+ *
+ * Unlike `reflectObservations`, this can touch rows across all
+ * sessions — the caller is asking for a global prune, not a
+ * per-session compaction. See {@link DEFAULT_GLOBAL_REFLECT_MIN_AGE_DAYS}
+ * for the resume-info-loss tradeoffs that motivated the min-age gate
+ * and the "never reflect on reflections" rule.
+ *
+ * Returns `undefined` only when there is nothing eligible *and* nothing
+ * preserved (empty store). When the store has only fresh/reflection
+ * rows, returns a result with empty `eligible`/`reflections` and
+ * `written: false` so callers can report "nothing to prune" without
+ * conflating it with an empty store.
+ */
+export async function reflectAllObservations(options) {
+    const { session, snapshot, settings, model, dryRun, onUsage } = options;
+    if (snapshot.observations.length === 0) {
+        return undefined;
+    }
+    const minAgeMs = options.minAgeMs ?? DEFAULT_GLOBAL_REFLECT_MIN_AGE_MS;
+    const now = options.now ?? Date.now();
+    const cutoff = now - minAgeMs;
+    const batchTokens = options.batchTokens ?? settings.reflection.observationTokens;
+    const targetTokens = options.targetTokens ?? settings.reflection.bufferActivation;
+    const { preserved, batches } = planReflectionBatches(snapshot.observations, {
+        cutoff,
+        batchTokens,
+    });
+    if (batches.length === 0) {
+        return {
+            before: snapshot.observations,
+            preserved,
+            eligible: [],
+            reflections: [],
+            written: false,
+        };
+    }
+    const eligible = batches.flatMap((batch) => batch.observations);
+    const reflections = [];
+    for (const batch of batches) {
+        const reflection = await reflectBatch({
+            batch,
+            settings,
+            model,
+            targetTokens,
+            onUsage,
+        });
+        if (reflection) {
+            reflections.push(reflection);
+        }
+    }
+    const written = !dryRun && reflections.length > 0;
+    if (written) {
+        // Single-write replacement keeps the storage transaction atomic:
+        // eligible rows disappear and new reflection rows appear together,
+        // never leaving a peer CLI looking at a half-pruned pool.
+        await replaceAllObservations(session, [...preserved, ...reflections]);
+    }
+    return {
+        before: snapshot.observations,
+        preserved,
+        eligible,
+        reflections,
+        written,
+    };
+}
+async function reflectBatch(args) {
+    const { batch, settings, model, targetTokens, onUsage } = args;
+    const source = batch.observations.map((observation) => observation.content).join("\n\n");
+    const rendered = renderObservationGroupsForReflection(source) ?? source;
+    const result = await generateStructuredOutput({
+        model,
+        tool: reflectorResultTool,
+        systemPrompt: buildReflectorSystemPrompt(settings.reflection.instruction),
+        prompt: buildReflectorPrompt(rendered, targetTokens),
+        onUsage,
+    });
+    const text = await enforceObservationTokenBudget({
+        text: result.observations,
+        targetTokens,
+        retry: async (actualTokens) => {
+            const retryResult = await generateStructuredOutput({
+                model,
+                tool: reflectorResultTool,
+                systemPrompt: buildReflectorSystemPrompt(settings.reflection.instruction),
+                prompt: buildReflectorPrompt(rendered, targetTokens, { actualTokens }),
+                onUsage,
+            });
+            return retryResult.observations;
+        },
+    });
+    if (!text || text.trim().length === 0) {
+        return undefined;
+    }
+    const reconciled = reconcileObservationGroupsFromReflection(text, source) ?? text;
+    const now = Date.now();
+    return {
+        id: createMemoryId(),
+        createdAt: now,
+        lastUsedAt: now,
+        kind: "reflection",
+        sessionId: GLOBAL_REFLECTION_SESSION_ID,
+        observedDate: new Date().toISOString().slice(0, 10),
+        timeOfDay: new Date().toISOString().slice(11, 16),
+        priority: "high",
+        source: { kind: "system" },
+        content: reconciled,
+        tags: ["observational-memory", "reflection", "global-prune"],
+    };
+}
 async function observe(messages, previousLocalObservations, attributableMemories, settings, model, onUsage) {
     const transcriptBudget = settings.observation.maxTranscriptTokens;
     const observationLogBudget = settings.observation.maxObservationLogTokens;