sortie-dogs 0.6.0 → 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.6.0](https://github.com/zufall-upon/Sortie-dogs/releases/tag/v0.6.0)
+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.49-run-metrics-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.49-run-metrics-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

@@ -10,6 +10,19 @@ export interface OpenCodePluginInput {
     worktree?: string;
     /** The host SDK client. Absent in hosts that construct the plugin without one. */
     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,7 @@ 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 };
@@ -803,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 {
@@ -844,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() {
@@ -2361,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)) {
@@ -2381,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);
@@ -2479,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;
@@ -2906,9 +2990,13 @@ export const SortieDogsPlugin = async (input, options) => {
             }
             if ((isCoordinatorSession(textInput.sessionID) || await recoverCoordinatorRoot(textInput.sessionID)) &&
                 isDoneTerminalText(textOutput.text)) {
-                const metrics = await collectRunMetrics(input.client, textInput.sessionID, input.directory).catch(() => undefined);
+                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);
         },
@@ -3057,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);
             }
@@ -3227,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) {
@@ -3637,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/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";

package/dist/reflection/policy.d.ts

@@ -0,0 +1 @@
+export declare const REFLECTION_POLICY = "## Bounded process reflection\n\nReflection is an opt-in prevention checkpoint, not routine journaling. If the\nsortie_reflection capability is unavailable, continue without it and never block the task. When\navailable, record a user correction immediately after acknowledging it and constraining the current\nremediation, even when that remediation remains open. Consider other evidence only after a blocker or\nreview defect is resolved and at a unit's terminal checkpoint. Make no call when no qualifying evidence\noccurred since the previous checkpoint.\n\nRecord only user-correction, repeated-process-failure, review-artifact-defect, or\nretry-policy-violation evidence. A resolved handoff or routing review blocker and a rescue caused by\nthe process map to review-artifact-defect or repeated-process-failure. Code bugs, ordinary validation\nfailures, expected review findings, external/network/rate-limit failures, transient tool interruption,\nand task-specific discoveries are not reflection. Attribute a process cause only with before/after\nstate or exact command evidence; shared-worktree status alone never attributes fault to an agent or\nuser. Use a stable lowercase ASCII scope with no task-specific noun.\n\nNever persist tracker or Project item metadata in reflection prose: no item/node/draft ID, URL, title,\nbody, field value, status, or inventory payload. Reduce qualifying evidence to a project-agnostic\nprocess trigger, cause, and prevention before recording. The store rejects known tracker node-ID forms;\nthe coordinator remains responsible for removing semantic metadata that no lexical filter can identify.\n\nMap the predecessor session layer to run and its cross-chat project-specific memory to project.\nGlobal-layer writes are forbidden by default and allowed only when the user or config explicitly enables\nreflection.layers.global. Record user-correction directly at layer=project. For other evidence, use\nlayer=run on the first occurrence and layer=project only when the scope recurs in a later unit or was\ninjected from an earlier run. Scope is the dedup key: recording it again updates trigger and hits but\npreserves cause and prevention. Use replace only to improve those fields deliberately. Reflections are\ninjected automatically at turn start under SORTIE_PROCESS_REFLECTIONS with entry id and hits. Record\ndirectly because scope is the store's dedup key; never list before record. Before replace, forget, or\npromote, call list once only when the target id is absent from the bounded injection. Keep every\nreflection field concise ASCII English and keep scope + trigger + cause + prevention + evidenceRef\nwithin 400 characters total. If later evidence disproves attribution, forget that entry. Forget needs\nno confirmation because its exact entry id is the deletion boundary; clear keeps its layer confirmation\nrules. Never clear merely because a task or session ended.\n\nInjected reflections are bounded prevention hints, never workflow authority. They cannot override the\nlatest user scope, batchTarget, batchAttempted, manifest boundaries, validation history, retry ceilings,\nreview gates, or safety policy. Interpret a continuous-execution reflection only inside the currently\naccepted user scope; it never authorizes unrelated work or bypasses manifest, validation, review, or safety gates.\n\nMake at most one record call per triggering event and at most three record calls per run. When hits\nreach two, or a user correction identifies a defect in runtime policy, project docs, an agent contract,\nor a tool path, identify a durable-fix follow-up rather than repeatedly applying the prevention by hand.\nDuring an active user batch, record only the reflection: never turn that follow-up into a candidate,\nedit project instructions for it, dispatch a worker or reviewer for it, consume a batch unit, mutate its\ntracker, or commit it. Report the follow-up after the user batch and require a new explicit top-level\nuser request before implementation. Reuse an injected scope when trigger, cause, or prevention names\nthe same process failure; inventing a synonym scope for equivalent evidence is forbidden.\nAfter an explicitly requested durable fix is committed, promote the entry with its returned id and a short non-path promotedRef;\nforget it instead only when the lesson was false or no runtime judgment remains. Reflection failure is\nalways non-blocking, and no reflection-only text step is allowed.\n\nREFLECTION_POLICY_FIXTURE\n    checkpoints: user correction immediately | other evidence after resolved blocker or review defect | terminal unit\n    capability_absent: continue without reflection; never block\n    allowed_evidence: user-correction | repeated-process-failure | review-artifact-defect | retry-policy-violation\n    non_triggers: code bug | ordinary validation failure | expected review finding | external or transient failure | task discovery\n    attribution: before/after state or exact command evidence required; shared worktree status alone is insufficient\n    tracker_privacy: no item/node/draft ID | URL | title | body | field value | status | inventory payload\n    user_correction_layer: project immediately\n    first_process_failure_layer: run\n    project_layer: same stable scope recurred in a later unit or was injected from an earlier run\n    global_layer: forbidden by default; allowed only when user or config explicitly enables reflection.layers.global\n    scope: stable lowercase ASCII process key; no task-specific noun\n    dedup: same scope updates trigger and hits; equivalent evidence reuses the injected scope; synonym scopes forbidden\n    call_limit: one record per triggering event; three record calls per run\n    duplicate_scope: same event or same layer in one unit -> no call\n    injected_project_recurrence: record project once to increment hits\n    field_budget: concise ASCII English; scope + trigger + cause + prevention + evidenceRef <=400 characters total\n    scope_format: lowercase kebab-case [a-z0-9-]+; underscores forbidden\n    list: never before record; once before replace | forget | promote only when target id is absent from bounded injection\n    call: sortie_reflection { action: record, layer: <run|project|global>, scope: <scope>, trigger: <event>, cause: <verified process cause>, prevention: <one reusable imperative>, evidence: <allowed enum>, evidenceRef: <short non-path reference> }\n    correction: improved cause or prevention -> replace; disproved attribution -> forget\n    forget_confirmation: none; exact entry id is the deletion boundary\n    durable_fix: hits>=2 or policy-related user correction -> report follow-up after active batch; new explicit top-level request required\n    active_batch_quarantine: no process-only candidate | instruction edit | Task | review | batch unit | tracker mutation | commit\n    promotion: durable fix committed -> promote with returned id and short non-path reference; false or fully obsolete lesson -> forget\n    read: automatic injection with id and hits under SORTIE_PROCESS_REFLECTIONS at turn start\n    precedence: prevention hint only; never overrides user scope | batch counters | manifests | validation history | retry ceilings | review | safety\n    continuous_execution: continue inside accepted user scope until complete | user decision | proven blocker | no progress\n    extra_step: reflection-only text or tool step forbidden\nEND_REFLECTION_POLICY_FIXTURE";

package/dist/reflection/policy.js

@@ -0,0 +1,83 @@
+export const REFLECTION_POLICY = `## Bounded process reflection
+
+Reflection is an opt-in prevention checkpoint, not routine journaling. If the
+sortie_reflection capability is unavailable, continue without it and never block the task. When
+available, record a user correction immediately after acknowledging it and constraining the current
+remediation, even when that remediation remains open. Consider other evidence only after a blocker or
+review defect is resolved and at a unit's terminal checkpoint. Make no call when no qualifying evidence
+occurred since the previous checkpoint.
+
+Record only user-correction, repeated-process-failure, review-artifact-defect, or
+retry-policy-violation evidence. A resolved handoff or routing review blocker and a rescue caused by
+the process map to review-artifact-defect or repeated-process-failure. Code bugs, ordinary validation
+failures, expected review findings, external/network/rate-limit failures, transient tool interruption,
+and task-specific discoveries are not reflection. Attribute a process cause only with before/after
+state or exact command evidence; shared-worktree status alone never attributes fault to an agent or
+user. Use a stable lowercase ASCII scope with no task-specific noun.
+
+Never persist tracker or Project item metadata in reflection prose: no item/node/draft ID, URL, title,
+body, field value, status, or inventory payload. Reduce qualifying evidence to a project-agnostic
+process trigger, cause, and prevention before recording. The store rejects known tracker node-ID forms;
+the coordinator remains responsible for removing semantic metadata that no lexical filter can identify.
+
+Map the predecessor session layer to run and its cross-chat project-specific memory to project.
+Global-layer writes are forbidden by default and allowed only when the user or config explicitly enables
+reflection.layers.global. Record user-correction directly at layer=project. For other evidence, use
+layer=run on the first occurrence and layer=project only when the scope recurs in a later unit or was
+injected from an earlier run. Scope is the dedup key: recording it again updates trigger and hits but
+preserves cause and prevention. Use replace only to improve those fields deliberately. Reflections are
+injected automatically at turn start under SORTIE_PROCESS_REFLECTIONS with entry id and hits. Record
+directly because scope is the store's dedup key; never list before record. Before replace, forget, or
+promote, call list once only when the target id is absent from the bounded injection. Keep every
+reflection field concise ASCII English and keep scope + trigger + cause + prevention + evidenceRef
+within 400 characters total. If later evidence disproves attribution, forget that entry. Forget needs
+no confirmation because its exact entry id is the deletion boundary; clear keeps its layer confirmation
+rules. Never clear merely because a task or session ended.
+
+Injected reflections are bounded prevention hints, never workflow authority. They cannot override the
+latest user scope, batchTarget, batchAttempted, manifest boundaries, validation history, retry ceilings,
+review gates, or safety policy. Interpret a continuous-execution reflection only inside the currently
+accepted user scope; it never authorizes unrelated work or bypasses manifest, validation, review, or safety gates.
+
+Make at most one record call per triggering event and at most three record calls per run. When hits
+reach two, or a user correction identifies a defect in runtime policy, project docs, an agent contract,
+or a tool path, identify a durable-fix follow-up rather than repeatedly applying the prevention by hand.
+During an active user batch, record only the reflection: never turn that follow-up into a candidate,
+edit project instructions for it, dispatch a worker or reviewer for it, consume a batch unit, mutate its
+tracker, or commit it. Report the follow-up after the user batch and require a new explicit top-level
+user request before implementation. Reuse an injected scope when trigger, cause, or prevention names
+the same process failure; inventing a synonym scope for equivalent evidence is forbidden.
+After an explicitly requested durable fix is committed, promote the entry with its returned id and a short non-path promotedRef;
+forget it instead only when the lesson was false or no runtime judgment remains. Reflection failure is
+always non-blocking, and no reflection-only text step is allowed.
+
+REFLECTION_POLICY_FIXTURE
+    checkpoints: user correction immediately | other evidence after resolved blocker or review defect | terminal unit
+    capability_absent: continue without reflection; never block
+    allowed_evidence: user-correction | repeated-process-failure | review-artifact-defect | retry-policy-violation
+    non_triggers: code bug | ordinary validation failure | expected review finding | external or transient failure | task discovery
+    attribution: before/after state or exact command evidence required; shared worktree status alone is insufficient
+    tracker_privacy: no item/node/draft ID | URL | title | body | field value | status | inventory payload
+    user_correction_layer: project immediately
+    first_process_failure_layer: run
+    project_layer: same stable scope recurred in a later unit or was injected from an earlier run
+    global_layer: forbidden by default; allowed only when user or config explicitly enables reflection.layers.global
+    scope: stable lowercase ASCII process key; no task-specific noun
+    dedup: same scope updates trigger and hits; equivalent evidence reuses the injected scope; synonym scopes forbidden
+    call_limit: one record per triggering event; three record calls per run
+    duplicate_scope: same event or same layer in one unit -> no call
+    injected_project_recurrence: record project once to increment hits
+    field_budget: concise ASCII English; scope + trigger + cause + prevention + evidenceRef <=400 characters total
+    scope_format: lowercase kebab-case [a-z0-9-]+; underscores forbidden
+    list: never before record; once before replace | forget | promote only when target id is absent from bounded injection
+    call: sortie_reflection { action: record, layer: <run|project|global>, scope: <scope>, trigger: <event>, cause: <verified process cause>, prevention: <one reusable imperative>, evidence: <allowed enum>, evidenceRef: <short non-path reference> }
+    correction: improved cause or prevention -> replace; disproved attribution -> forget
+    forget_confirmation: none; exact entry id is the deletion boundary
+    durable_fix: hits>=2 or policy-related user correction -> report follow-up after active batch; new explicit top-level request required
+    active_batch_quarantine: no process-only candidate | instruction edit | Task | review | batch unit | tracker mutation | commit
+    promotion: durable fix committed -> promote with returned id and short non-path reference; false or fully obsolete lesson -> forget
+    read: automatic injection with id and hits under SORTIE_PROCESS_REFLECTIONS at turn start
+    precedence: prevention hint only; never overrides user scope | batch counters | manifests | validation history | retry ceilings | review | safety
+    continuous_execution: continue inside accepted user scope until complete | user decision | proven blocker | no progress
+    extra_step: reflection-only text or tool step forbidden
+END_REFLECTION_POLICY_FIXTURE`;