sortie-dogs 0.5.17 → 0.6.1

package/README.md

@@ -20,7 +20,7 @@ Requirements: Node.js 22.6 or newer, npm, and OpenCode.
 
 Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md) · [CLI testing](docs/cli-testing.md)
 
-Release: [v0.5.17](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.5.17)
+Release: [v0.6.1](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.6.1)
 
 ## Quick start
 
@@ -151,7 +151,8 @@ Optional settings in `.opencode/sortie-dogs.json`:
   "continuation": { "enabled": true, "maxAutoContinues": 10 },
   "reflection": {
     "enabled": false,
-    "layers": { "run": true, "project": true, "global": false }
+    "layers": { "run": true, "project": true, "global": false },
+    "maxInjectedTokens": 500
   }
 }
 ```
@@ -201,6 +202,10 @@ global file for durable global settings.
   to enabled after opt-in; the cross-project global storage layer remains
   disabled unless explicitly enabled. Child and non-coordinator sessions fail
   closed, and `SORTIE_REFLECTION=0` is an immediate kill switch. The coordinator
+  injects the governing `REFLECTION_POLICY` only while reflection is enabled.
+  `maxInjectedTokens` budgets the dynamic `SORTIE_PROCESS_REFLECTIONS` heading
+  and persisted entry lines; the policy is outside that entry budget.
+  The coordinator
   evaluates it only after a resolved blocker/review defect and at a terminal
   unit, with a maximum of three records per run; routine bugs and external
   failures are never journaled.

package/dist/asset-version.d.ts

@@ -2,5 +2,5 @@
  * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
  * installed project marker without importing every asset body.
  */
-export declare const RUNTIME_ASSET_VERSION = "0.3.48-recovery-compaction-v1";
+export declare const RUNTIME_ASSET_VERSION = "0.3.50-observability-reflection-v1";
 export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION;

package/dist/asset-version.js

@@ -2,4 +2,4 @@
  * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
  * installed project marker without importing every asset body.
  */
-export const RUNTIME_ASSET_VERSION = "0.3.48-recovery-compaction-v1";
+export const RUNTIME_ASSET_VERSION = "0.3.50-observability-reflection-v1";

package/dist/plugin/config.d.ts

@@ -7,6 +7,7 @@ export interface ReflectionConfiguration {
         readonly global: boolean;
     };
     readonly maxInjectedEntries: number;
+    /** Token budget for the dynamic SORTIE_PROCESS_REFLECTIONS heading and persisted entry lines; excludes the governing REFLECTION_POLICY. */
     readonly maxInjectedTokens: number;
 }
 export type ReflectionPolicyInput = Partial<Omit<ReflectionConfiguration, "layers">> & {

package/dist/plugin/continuation.d.ts

@@ -170,10 +170,21 @@ export interface ContinuationHooks {
     sessionIdle(sessionID: string): Promise<void>;
     forgetSession(sessionID: string): void;
 }
+export type ContinuationTransitionType = "continuation.queued" | "continuation.compacted" | "continuation.resumed" | "continuation.not_required";
+export type ContinuationTransitionReason = "continuation-requested" | "compaction-only" | "summarize-accepted" | "prompt-accepted" | "terminal-checkpoint";
+export interface ContinuationTransition {
+    readonly type: ContinuationTransitionType;
+    readonly sessionID: string;
+    readonly epoch: number;
+    readonly reason: ContinuationTransitionReason;
+    readonly attempts: number;
+    readonly resumeAttempts: number;
+}
+export type ContinuationTransitionObserver = (transition: ContinuationTransition) => void;
 /**
  * Build the continuation runtime. Every hook fails closed: an unreadable session, an absent client,
  * or a rejected identity leaves the coordinator exactly where it was, with manual continuation
  * still available to the user.
  */
-export declare function createContinuationHooks(client: ContinuationClient | undefined, directory: string, policySource: ContinuationPolicySource, timings?: ContinuationTimings, localIdentity?: LocalIdentitySource): ContinuationHooks;
+export declare function createContinuationHooks(client: ContinuationClient | undefined, directory: string, policySource: ContinuationPolicySource, timings?: ContinuationTimings, localIdentity?: LocalIdentitySource, transitionObserver?: ContinuationTransitionObserver): ContinuationHooks;
 export {};

package/dist/plugin/continuation.js

@@ -214,9 +214,38 @@ function sessionInfo(response) {
  * or a rejected identity leaves the coordinator exactly where it was, with manual continuation
  * still available to the user.
  */
-export function createContinuationHooks(client, directory, policySource, timings = DEFAULT_TIMINGS, localIdentity) {
+export function createContinuationHooks(client, directory, policySource, timings = DEFAULT_TIMINGS, localIdentity, transitionObserver) {
     const sessions = new Map();
     const warned = new Set();
+    function observeTransition(type, sessionID, state, reason) {
+        try {
+            transitionObserver?.({
+                type,
+                sessionID,
+                epoch: state.rolloverEpoch,
+                reason,
+                attempts: state.attempts,
+                resumeAttempts: state.resumeAttempts,
+            });
+        }
+        catch {
+            // Lifecycle telemetry is best effort and must never affect continuation.
+        }
+    }
+    function observeResumed(sessionID, state, epoch) {
+        if (state.compactedTransitionEpoch !== epoch || state.resumedTransitionEpoch === epoch)
+            return;
+        state.resumedTransitionEpoch = epoch;
+        observeTransition("continuation.resumed", sessionID, state, "prompt-accepted");
+    }
+    function observeCompacted(sessionID, state, epoch) {
+        if (state.compactedTransitionEpoch === epoch)
+            return;
+        state.compactedTransitionEpoch = epoch;
+        observeTransition("continuation.compacted", sessionID, state, "summarize-accepted");
+        if (state.resumeIssuedEpoch === epoch)
+            observeResumed(sessionID, state, epoch);
+    }
     /**
      * A rollover that cannot start is otherwise indistinguishable from a coordinator that never asked
      * for one, so every abort names its own reason exactly once per session.
@@ -532,6 +561,7 @@ export function createContinuationHooks(client, directory, policySource, timings
             state.recoverySummaryValidated = false;
             // The accepted prompt now belongs to the host loop, not this rollover request.
             state.active = false;
+            observeResumed(sessionID, state, epoch);
             return true;
         }
         catch (error) {
@@ -608,6 +638,7 @@ export function createContinuationHooks(client, directory, policySource, timings
                 state.promptPending = false;
                 state.compactedRollover = true;
                 state.lastRollover = Date.now();
+                observeCompacted(sessionID, state, operationEpoch);
             }
             if (state.resumeIssuingEpoch === operationEpoch ||
                 state.resumeIssuedEpoch === operationEpoch) {
@@ -694,6 +725,7 @@ export function createContinuationHooks(client, directory, policySource, timings
         if (resume && countAttempt)
             state.attempts += 1;
         const epoch = state.rolloverEpoch;
+        observeTransition("continuation.queued", sessionID, state, resume ? "continuation-requested" : "compaction-only");
         // session.idle can be lost when a one-shot CLI host exits. Keep this zero-delay timer referenced
         // so the rollover reaches the host after the current plugin hook returns but before process exit.
         setTimeout(async () => {
@@ -835,8 +867,11 @@ export function createContinuationHooks(client, directory, policySource, timings
                  * One-shot CLI hosts can exit as soon as the compaction assistant finishes, before the
                  * compacted event or summarize response. Its text-complete hook is the last awaited boundary
                  * where the summary message already exists and a resume prompt can still join the same loop.
-                 */
+                */
                 if (ownedCompactionSummary || trimmed.startsWith(ROLLOVER_TOKEN)) {
+                    if (ownedCompactionSummary) {
+                        observeCompacted(input.sessionID, state, state.rolloverEpoch);
+                    }
                     await arbitrateResume(input.sessionID, state);
                     if (state.resumeIssuedEpoch === state.rolloverEpoch)
                         return;
@@ -850,6 +885,12 @@ export function createContinuationHooks(client, directory, policySource, timings
                         clearTimer(state.stepRecoveryTimer);
                         state.stepRecoveryTimer = undefined;
                         resetRecoveryStall(state);
+                        if (state.notRequiredRevision !== state.turnRevision &&
+                            !output.text.includes(ROLLOVER_MARKER) &&
+                            !output.text.includes(CONTINUATION_MARKER)) {
+                            state.notRequiredRevision = state.turnRevision;
+                            observeTransition("continuation.not_required", input.sessionID, state, "terminal-checkpoint");
+                        }
                     }
                     if (batchCheckpointNeedsContinuation(state.latestCoordinatorReport)) {
                         if (input.allowCheckpointContinuation === false) {
@@ -951,8 +992,11 @@ export function createContinuationHooks(client, directory, policySource, timings
         },
         async sessionCompacted(sessionID) {
             const state = sessions.get(sessionID);
-            if (state !== undefined)
+            if (state?.pendingRollover === true &&
+                (state.active || state.promptPending || state.compactingEpoch === state.rolloverEpoch)) {
+                observeCompacted(sessionID, state, state.rolloverEpoch);
                 await arbitrateResume(sessionID, state);
+            }
         },
         async compactionAutoContinue(input, output) {
             const state = sessions.get(input.sessionID);

package/dist/plugin/index.d.ts

@@ -3,12 +3,26 @@ import { type ContinuationClient } from "./continuation.js";
 import { type ToolExecuteBeforeInput, type ToolExecuteBeforeOutput } from "./gate.js";
 import { type OpenCodeChatMessageHook, type OpenCodeModelAvailabilityClient } from "./model-routing-hook.js";
 import { type SessionMessageReader } from "./task-result-repair.js";
+import type { RunMetricsClient } from "./run-metrics.js";
 export declare const PARALLEL_COMMIT_ARTIFACT_CAPABILITY = "sortie_create_parallel_commit_artifact";
 export interface OpenCodePluginInput {
     directory: string;
     worktree?: string;
     /** The host SDK client. Absent in hosts that construct the plugin without one. */
-    client?: SessionMessageReader & ContinuationClient & OpenCodeModelAvailabilityClient & {
+    client?: SessionMessageReader & RunMetricsClient & ContinuationClient & OpenCodeModelAvailabilityClient & {
+        app?: {
+            log?: (request: {
+                body: {
+                    service: string;
+                    level: "debug" | "info" | "error" | "warn";
+                    message: string;
+                    extra?: Record<string, unknown>;
+                };
+                query?: {
+                    directory?: string;
+                };
+            }) => unknown;
+        };
         tui?: {
             showToast?: (request: {
                 body: {

package/dist/plugin/index.js

@@ -17,7 +17,8 @@ import { WriteDeniedError, canonicalManifestReadScopes, canonicalManifestWriteSc
 import { BACKLOG_DRAIN_CAPABILITY, FastLaneController } from "./fast-lane.js";
 import { createModelRoutingHook, } from "./model-routing-hook.js";
 import { createTaskResultRepairHook, lastAssistantText, markConsultationFallbackRetry, taskChildSessionID, } from "./task-result-repair.js";
-import { configRoot, nearestPackageVersion, reflectionEnabled, ReflectionError, ReflectionStore } from "../reflection/index.js";
+import { configRoot, nearestPackageVersion, REFLECTION_POLICY, reflectionEnabled, ReflectionError, ReflectionStore } from "../reflection/index.js";
+import { collectRunMetrics, insertRunMetrics, isDoneTerminalText } from "./run-metrics.js";
 const INPUT_LIMITS = { config: 64 * 1024, manifest: 512 * 1024, handoff: 2 * 1024 * 1024, parallel: 512 * 1024 };
 const INSPECTION_CACHE = { maximum: 256, ttlMilliseconds: 30 * 60 * 1000 };
 const ACTIVE_SESSION_CACHE = { maximum: 256, ttlMilliseconds: 30 * 60 * 1000 };
@@ -802,6 +803,83 @@ export const SortieDogsPlugin = async (input, options) => {
     let bootstrapCompleted = false;
     let assetVersionReported = false;
     const globalConfig = await readOptionalGlobalConfig();
+    const sessionOperationMetrics = new Map();
+    function appLogInfo(message, sessionID, extra) {
+        const app = input.client?.app;
+        const log = app?.log;
+        if (log === undefined)
+            return;
+        try {
+            const result = log.call(app, {
+                body: {
+                    service: "sortie-dogs",
+                    level: "info",
+                    message,
+                    extra: { sessionID: sessionID.slice(0, 128), ...extra },
+                },
+                query: { directory: input.directory },
+            });
+            void Promise.resolve(result).catch(() => undefined);
+        }
+        catch {
+            // Host lifecycle telemetry is best effort.
+        }
+    }
+    function pruneSessionOperationMetrics(now, reserveSlot = false) {
+        for (const [sessionID, metrics] of sessionOperationMetrics) {
+            if (metrics.touched + ACTIVE_SESSION_CACHE.ttlMilliseconds <= now) {
+                sessionOperationMetrics.delete(sessionID);
+            }
+        }
+        const limit = ACTIVE_SESSION_CACHE.maximum - (reserveSlot ? 1 : 0);
+        while (sessionOperationMetrics.size > limit) {
+            sessionOperationMetrics.delete(sessionOperationMetrics.keys().next().value);
+        }
+    }
+    function operationMetricsFor(sessionID) {
+        const now = Date.now();
+        pruneSessionOperationMetrics(now);
+        const existing = sessionOperationMetrics.get(sessionID);
+        if (existing !== undefined) {
+            existing.touched = now;
+            sessionOperationMetrics.delete(sessionID);
+            sessionOperationMetrics.set(sessionID, existing);
+            return existing;
+        }
+        pruneSessionOperationMetrics(now, true);
+        const created = {
+            touched: now,
+            operations: {
+                hostSessionIdentity: { count: 0, elapsedMilliseconds: 0 },
+                bootstrapControlState: { count: 0, elapsedMilliseconds: 0 },
+                collectRunMetrics: { count: 0, elapsedMilliseconds: 0 },
+            },
+        };
+        sessionOperationMetrics.set(sessionID, created);
+        return created;
+    }
+    async function measureSessionOperation(sessionID, operation, run) {
+        const started = performance.now();
+        try {
+            return await run();
+        }
+        finally {
+            const measurement = operationMetricsFor(sessionID).operations[operation];
+            measurement.count += 1;
+            measurement.elapsedMilliseconds += Math.max(0, performance.now() - started);
+        }
+    }
+    function operationMetricsSnapshot(sessionID) {
+        const operations = sessionOperationMetrics.get(sessionID)?.operations;
+        return {
+            hostSessionIdentityCount: operations?.hostSessionIdentity.count ?? 0,
+            hostSessionIdentityElapsedMilliseconds: Math.round(operations?.hostSessionIdentity.elapsedMilliseconds ?? 0),
+            bootstrapControlStateCount: operations?.bootstrapControlState.count ?? 0,
+            bootstrapControlStateElapsedMilliseconds: Math.round(operations?.bootstrapControlState.elapsedMilliseconds ?? 0),
+            collectRunMetricsCount: operations?.collectRunMetrics.count ?? 0,
+            collectRunMetricsElapsedMilliseconds: Math.round(operations?.collectRunMetrics.elapsedMilliseconds ?? 0),
+        };
+    }
     // Project config read is required discovery for its opt-in; no reflection storage/version read
     // occurs unless that resolved config enables reflection. It stays isolated from write-gate load.
     try {
@@ -843,7 +921,12 @@ export const SortieDogsPlugin = async (input, options) => {
      */
     (sessionID) => isCoordinatorSession(sessionID)
         ? { agent: COORDINATOR_AGENT, parentID: undefined }
-        : undefined);
+        : undefined, (transition) => appLogInfo(transition.type, transition.sessionID, {
+        epoch: transition.epoch,
+        reason: transition.reason,
+        attempts: transition.attempts,
+        resumeAttempts: transition.resumeAttempts,
+    }));
     const completedCoordinatorMessages = new Set();
     const completedCoordinatorParts = new Set();
     async function ensureLoaded() {
@@ -2360,6 +2443,7 @@ export const SortieDogsPlugin = async (input, options) => {
     }
     function expireSession(sessionID) {
         activeSessions.delete(sessionID);
+        sessionOperationMetrics.delete(sessionID);
         abandonSessionLease(sessionID);
         sessionAuthorizations.delete(sessionID);
         if (!childHasInFlightParentTask(sessionID)) {
@@ -2380,6 +2464,7 @@ export const SortieDogsPlugin = async (input, options) => {
     }
     function evictSession(sessionID) {
         activeSessions.delete(sessionID);
+        sessionOperationMetrics.delete(sessionID);
         abandonSessionLease(sessionID);
         sessionAuthorizations.delete(sessionID);
         bindingPins.delete(sessionID);
@@ -2478,10 +2563,10 @@ export const SortieDogsPlugin = async (input, options) => {
         if (get === undefined)
             return undefined;
         try {
-            const response = await get.call(input.client.session, {
+            const response = await measureSessionOperation(sessionID, "hostSessionIdentity", () => get.call(input.client.session, {
                 path: { id: sessionID },
                 query: { directory: input.directory },
-            });
+            }));
             const payload = isRecord(response) && "data" in response ? response.data : response;
             if (!isRecord(payload))
                 return undefined;
@@ -2903,6 +2988,16 @@ export const SortieDogsPlugin = async (input, options) => {
                     .replaceAll(CONTINUATION_MARKER, "")
                     .trimEnd();
             }
+            if ((isCoordinatorSession(textInput.sessionID) || await recoverCoordinatorRoot(textInput.sessionID)) &&
+                isDoneTerminalText(textOutput.text)) {
+                const metrics = await measureSessionOperation(textInput.sessionID, "collectRunMetrics", () => collectRunMetrics(input.client, textInput.sessionID, input.directory).catch(() => undefined));
+                if (metrics !== undefined)
+                    textOutput.text = insertRunMetrics(textOutput.text, metrics);
+                appLogInfo("run-metrics.snapshot", textInput.sessionID, {
+                    available: metrics !== undefined,
+                    ...operationMetricsSnapshot(textInput.sessionID),
+                });
+            }
             await completeContinuationText(textInput.sessionID, textOutput.text, false);
         },
         "experimental.session.compacting": async (compactInput, compactOutput) => {
@@ -3050,22 +3145,33 @@ export const SortieDogsPlugin = async (input, options) => {
                     }
                 }
             }
+            const heading = "SORTIE_PROCESS_REFLECTIONS";
+            const prefix = `${REFLECTION_POLICY}\n\n${heading}`;
+            if (transformOutput.system !== undefined) {
+                const retained = transformOutput.system.filter((item) => item !== REFLECTION_POLICY && !item.startsWith(`${prefix}\n`));
+                if (retained.length !== transformOutput.system.length)
+                    transformOutput.system = retained;
+            }
             if (!reflectionStartup || !(await beginReflection(transformInput.sessionID)))
                 return;
             const config = reflectionConfiguration;
             try {
                 if (!config)
                     return;
-                const heading = "SORTIE_PROCESS_REFLECTIONS";
-                const buckets = ["run", "project", "global"]
-                    .filter((layer) => config.layers[layer])
-                    .map((layer) => ({ layer, ...(layer === "global" ? {} : { run: transformInput.sessionID }) }));
-                const budget = Math.max(0, config.maxInjectedTokens - Buffer.byteLength(`${heading}\n`, "utf8"));
-                const text = await reflectionStore.injectBuckets(buckets, config.maxInjectedEntries, budget, reflectionVersion);
-                if (text)
-                    transformOutput.system = [...(transformOutput.system ?? []), `${heading}\n${text}`];
-            }
-            catch { /* reflection is strictly non-invasive */ }
+                let element = REFLECTION_POLICY;
+                try {
+                    const buckets = ["run", "project", "global"]
+                        .filter((layer) => config.layers[layer])
+                        .map((layer) => ({ layer, ...(layer === "global" ? {} : { run: transformInput.sessionID }) }));
+                    // Historical persisted configs budget the dynamic heading and entry payload, not policy.
+                    const entryBudget = Math.max(0, config.maxInjectedTokens - Buffer.byteLength(`${heading}\n`, "utf8"));
+                    const text = await reflectionStore.injectBuckets(buckets, config.maxInjectedEntries, entryBudget, reflectionVersion);
+                    if (text)
+                        element = `${prefix}\n${text}`;
+                }
+                catch { /* persisted entries are best effort; the active policy still applies */ }
+                transformOutput.system = [...(transformOutput.system ?? []), element];
+            }
             finally {
                 endReflection(transformInput.sessionID);
             }
@@ -3220,7 +3326,7 @@ export const SortieDogsPlugin = async (input, options) => {
             const bootstrap = bootstrapRequired && !exactCoordinatorDirectOperation &&
                 !coordinatorCapability && !sessionGateCapability &&
                 !sessionAuthorizations.has(toolInput.sessionID) && (coordinatorRoot || coordinatorRoots.size > 0)
-                ? await bootstrapControlState()
+                ? await measureSessionOperation(toolInput.sessionID, "bootstrapControlState", bootstrapControlState)
                 : undefined;
             if (coordinatorRoot && bootstrapRequired && !exactCoordinatorDirectOperation &&
                 !coordinatorCapability && !sessionGateCapability) {
@@ -3630,7 +3736,7 @@ export const SortieDogsPlugin = async (input, options) => {
             if (event.type === "session.compacted")
                 await continuation.sessionCompacted(eventSessionID);
             if (event.type === "session.idle" && isCoordinatorSession(eventSessionID)) {
-                const bootstrap = await bootstrapControlState();
+                const bootstrap = await measureSessionOperation(eventSessionID, "bootstrapControlState", bootstrapControlState);
                 if (bootstrapRequired && bootstrap?.usable === true && bootstrap.missing.length > 0) {
                     if (!bootstrapIdleWarnings.has(eventSessionID)) {
                         bootstrapIdleWarnings.add(eventSessionID);

package/dist/plugin/run-metrics.d.ts

@@ -0,0 +1,40 @@
+export interface RunMetricsClient {
+    readonly session?: {
+        readonly get?: (request: {
+            path: {
+                id: string;
+            };
+            query?: {
+                directory?: string;
+            };
+        }) => Promise<unknown>;
+        readonly children?: (request: {
+            path: {
+                id: string;
+            };
+            query?: {
+                directory?: string;
+            };
+        }) => Promise<unknown>;
+        readonly messages?: (request: {
+            path: {
+                id: string;
+            };
+            query?: {
+                directory?: string;
+            };
+        }) => Promise<unknown>;
+    };
+}
+export interface RunMetrics {
+    readonly durationMilliseconds: number | undefined;
+    readonly tokens: number | undefined;
+    readonly cost: number | undefined;
+    readonly steps: number | undefined;
+    readonly sessions: number | undefined;
+    readonly cacheRatio: number | undefined;
+}
+export declare function collectRunMetrics(client: RunMetricsClient | undefined, rootSessionID: string, directory?: string, now?: number): Promise<RunMetrics | undefined>;
+export declare function formatRunMetrics(metrics: RunMetrics): string;
+export declare function isDoneTerminalText(text: string): boolean;
+export declare function insertRunMetrics(text: string, metrics: RunMetrics): string;

package/dist/plugin/run-metrics.js

@@ -0,0 +1,169 @@
+const MAX_SESSIONS = 128;
+function record(value) {
+    return value !== null && typeof value === "object" ? value : undefined;
+}
+function unwrap(value) {
+    const object = record(value);
+    return object !== undefined && "data" in object ? object.data : value;
+}
+function number(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function messageTokens(message) {
+    const info = record(message.info) ?? message;
+    const tokens = record(info.tokens) ?? record(message.tokens);
+    if (tokens === undefined)
+        return undefined;
+    const input = number(tokens.input);
+    const output = number(tokens.output);
+    const reasoning = number(tokens.reasoning);
+    const cache = record(tokens.cache);
+    const cacheRead = number(cache?.read) ?? number(tokens.cacheRead) ?? number(tokens.cache_read);
+    const cacheWrite = number(cache?.write) ?? number(tokens.cacheWrite) ?? number(tokens.cache_write);
+    if (input === undefined || output === undefined || reasoning === undefined || cacheRead === undefined || cacheWrite === undefined)
+        return undefined;
+    return [input + output + reasoning + cacheRead + cacheWrite, cacheRead];
+}
+function assistantMessages(value) {
+    const payload = unwrap(value);
+    if (!Array.isArray(payload))
+        return undefined;
+    return payload.filter((entry) => {
+        const item = record(entry);
+        const info = item === undefined ? undefined : record(item.info);
+        return item !== undefined && (info?.role ?? item.role) === "assistant";
+    });
+}
+export async function collectRunMetrics(client, rootSessionID, directory, now = Date.now()) {
+    const session = client?.session;
+    if (session?.messages === undefined)
+        return undefined;
+    const ids = [rootSessionID];
+    const visited = new Set(ids);
+    let hierarchyComplete = session.children !== undefined;
+    for (let index = 0; index < ids.length && ids.length < MAX_SESSIONS; index += 1) {
+        if (session.children === undefined)
+            break;
+        try {
+            const children = unwrap(await session.children.call(session, { path: { id: ids[index] }, query: { directory } }));
+            if (!Array.isArray(children)) {
+                hierarchyComplete = false;
+                break;
+            }
+            for (const child of children) {
+                const item = record(child);
+                const id = typeof item?.id === "string" ? item.id : typeof item?.sessionID === "string" ? item.sessionID : undefined;
+                if (id === undefined) {
+                    hierarchyComplete = false;
+                    continue;
+                }
+                if (!visited.has(id) && ids.length < MAX_SESSIONS) {
+                    visited.add(id);
+                    ids.push(id);
+                }
+                else if (!visited.has(id))
+                    hierarchyComplete = false;
+            }
+        }
+        catch {
+            hierarchyComplete = false;
+            break;
+        }
+    }
+    if (ids.length >= MAX_SESSIONS)
+        hierarchyComplete = false;
+    const uniqueMessages = new Set();
+    let totalTokens = 0;
+    let cacheRead = 0;
+    let tokensAvailable = true;
+    let messagesComplete = true;
+    let steps = 0;
+    let cost = 0;
+    let costAvailable = true;
+    for (const id of ids) {
+        try {
+            const messages = assistantMessages(await session.messages.call(session, { path: { id }, query: { directory } }));
+            if (messages === undefined)
+                return undefined;
+            for (const message of messages) {
+                const info = record(message.info) ?? message;
+                const time = record(info.time) ?? record(message.time);
+                if (time !== undefined && number(time.completed) === undefined)
+                    continue;
+                const messageID = typeof info.id === "string" ? info.id : typeof message.id === "string" ? message.id : undefined;
+                if (messageID === undefined) {
+                    messagesComplete = false;
+                    continue;
+                }
+                if (uniqueMessages.has(messageID))
+                    continue;
+                uniqueMessages.add(messageID);
+                steps += 1;
+                const tokens = messageTokens(message);
+                if (tokens !== undefined) {
+                    totalTokens += tokens[0];
+                    cacheRead += tokens[1];
+                }
+                else
+                    tokensAvailable = false;
+                const reportedCost = number(info.cost) ?? number(message.cost);
+                if (reportedCost === undefined)
+                    costAvailable = false;
+                else
+                    cost += reportedCost;
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let created;
+    if (session.get !== undefined) {
+        try {
+            const root = record(unwrap(await session.get.call(session, { path: { id: rootSessionID }, query: { directory } })));
+            const time = record(root?.time);
+            created = number(time?.created);
+        }
+        catch { /* fallback below */ }
+    }
+    return {
+        durationMilliseconds: created === undefined ? undefined : Math.max(0, now - created),
+        tokens: hierarchyComplete && messagesComplete && tokensAvailable ? totalTokens : undefined,
+        cost: hierarchyComplete && messagesComplete && costAvailable ? cost : undefined,
+        steps: hierarchyComplete && messagesComplete ? steps : undefined,
+        sessions: hierarchyComplete ? ids.length : undefined,
+        cacheRatio: hierarchyComplete && messagesComplete && tokensAvailable && totalTokens > 0 ? cacheRead / totalTokens : undefined,
+    };
+}
+function duration(milliseconds) {
+    const seconds = Math.floor(milliseconds / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+export function formatRunMetrics(metrics) {
+    const elapsed = metrics.durationMilliseconds === undefined ? "duration unavailable" : `${duration(metrics.durationMilliseconds)} wall-clock`;
+    const cost = metrics.cost === undefined ? "cost unavailable" : `$${metrics.cost.toFixed(4)}`;
+    const tokens = metrics.tokens === undefined ? "tokens unavailable" : `${metrics.tokens.toLocaleString("en-US")} tokens`;
+    const steps = metrics.steps === undefined ? "steps unavailable" : `${metrics.steps} completed assistant model step${metrics.steps === 1 ? "" : "s"}`;
+    const sessions = metrics.sessions === undefined ? "sessions unavailable" : `${metrics.sessions} session${metrics.sessions === 1 ? "" : "s"}`;
+    const cache = metrics.cacheRatio === undefined ? "cache ratio unavailable" : `${(metrics.cacheRatio * 100).toFixed(1)}% cache ratio`;
+    return `**Run:** pre-terminal host snapshot · ${elapsed} · ${tokens} · ${cost} · ${steps} · ${sessions} · ${cache}`;
+}
+export function isDoneTerminalText(text) {
+    const first = text.split(/\r?\n/u).find((line) => line.trim().length > 0) ?? "";
+    return /^✅\s+\*\*DONE\*\*(?:\s|$)/u.test(first) || /^status:\s*DONE(?:\s|$)/u.test(first);
+}
+export function insertRunMetrics(text, metrics) {
+    if (/\*\*Run:\*\*/u.test(text) || !isDoneTerminalText(text))
+        return text;
+    const newline = text.includes("\r\n") ? "\r\n" : "\n";
+    const statusStart = text.search(/^(?:✅\s+\*\*DONE\*\*|status:\s*DONE).*$/mu);
+    if (statusStart < 0)
+        return text;
+    const statusEnd = text.indexOf(newline, statusStart);
+    if (statusEnd < 0)
+        return `${text}${newline}${newline}${formatRunMetrics(metrics)}`;
+    return `${text.slice(0, statusEnd + newline.length)}${newline}${formatRunMetrics(metrics)}${newline}${text.slice(statusEnd + newline.length)}`;
+}

package/dist/reflection/index.d.ts

@@ -1,3 +1,4 @@
 export { DEFAULT_REFLECTION, configRoot, nearestPackageVersion, projectKey, reflectionEnabled } from "./config.js";
+export { REFLECTION_POLICY } from "./policy.js";
 export { ReflectionStore, ReflectionError, estimateInjectionTokens, normalizeField } from "./store.js";
 export type { ReflectionLayer } from "./config.js";

package/dist/reflection/index.js

@@ -1,2 +1,3 @@
 export { DEFAULT_REFLECTION, configRoot, nearestPackageVersion, projectKey, reflectionEnabled } from "./config.js";
+export { REFLECTION_POLICY } from "./policy.js";
 export { ReflectionStore, ReflectionError, estimateInjectionTokens, normalizeField } from "./store.js";