sortie-dogs 0.2.12 → 0.2.13

package/dist/plugin/config.d.ts

@@ -1,4 +1,17 @@
 import { type ModelCatalog, type ModelRoutingConfig, type ModelTarget } from "./model-routing.js";
+export interface ReflectionConfiguration {
+    readonly enabled: boolean;
+    readonly layers: {
+        readonly run: boolean;
+        readonly project: boolean;
+        readonly global: boolean;
+    };
+    readonly maxInjectedEntries: number;
+    readonly maxInjectedTokens: number;
+}
+export type ReflectionPolicyInput = Partial<Omit<ReflectionConfiguration, "layers">> & {
+    layers?: Partial<ReflectionConfiguration["layers"]>;
+};
 export interface SortieDogsPluginOptions {
     operationManifestPath?: string;
     handoffPaths?: readonly string[];
@@ -22,6 +35,7 @@ export interface SortieDogsPluginOptions {
      * only states this to raise the ceiling, choose a compaction model, or switch continuation off.
      */
     continuation?: ContinuationPolicyInput;
+    reflection?: ReflectionPolicyInput;
 }
 export type ContinuationPolicyInput = Partial<ContinuationConfiguration>;
 export interface ContinuationConfiguration {
@@ -65,6 +79,7 @@ export interface ConfiguredPlugin {
     freeTierFallbackModels: readonly string[];
     consultation: ConsultationPolicy;
     continuation: ContinuationConfiguration;
+    reflection: ReflectionConfiguration;
 }
 export type PluginConfiguration = ConfiguredPlugin | {
     kind: "invalid";

package/dist/plugin/config.js

@@ -32,6 +32,7 @@ export const DEFAULT_PLUGIN_OPTIONS = {
         capability: CONTINUATION_CAPABILITY,
         maxAutoContinues: DEFAULT_MAX_AUTO_CONTINUES,
     }),
+    reflection: Object.freeze({ enabled: false, layers: Object.freeze({ run: true, project: true, global: false }), maxInjectedEntries: 3, maxInjectedTokens: 500 }),
 };
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -204,7 +205,7 @@ function parseLayer(value) {
         return undefined;
     if (Object.keys(value).some((key) => ![
         "operationManifestPath", "handoffPaths", "readOnlyTools", "dedicatedWorkerModel",
-        "modelRouting", "modelCatalog", "freeTierFallbackModels", "consultation", "continuation",
+        "modelRouting", "modelCatalog", "freeTierFallbackModels", "consultation", "continuation", "reflection",
     ].includes(key))) {
         return undefined;
     }
@@ -229,6 +230,22 @@ function parseLayer(value) {
     const continuation = value.continuation === undefined
         ? undefined
         : parseContinuationPolicy(value.continuation);
+    const reflectionValue = value.reflection;
+    let reflection;
+    if (reflectionValue !== undefined) {
+        if (!isRecord(reflectionValue) || Object.keys(reflectionValue).some((key) => !["enabled", "layers", "maxInjectedEntries", "maxInjectedTokens"].includes(key)))
+            return undefined;
+        const layers = reflectionValue.layers;
+        if (layers !== undefined && (!isRecord(layers) || Object.keys(layers).some((key) => !["run", "project", "global"].includes(key)) || Object.values(layers).some((item) => typeof item !== "boolean")))
+            return undefined;
+        if (reflectionValue.enabled !== undefined && typeof reflectionValue.enabled !== "boolean")
+            return undefined;
+        if (reflectionValue.maxInjectedEntries !== undefined && (!positiveInteger(reflectionValue.maxInjectedEntries) || reflectionValue.maxInjectedEntries > 3))
+            return undefined;
+        if (reflectionValue.maxInjectedTokens !== undefined && (!positiveInteger(reflectionValue.maxInjectedTokens) || reflectionValue.maxInjectedTokens > 500))
+            return undefined;
+        reflection = { ...(reflectionValue.enabled === undefined ? {} : { enabled: reflectionValue.enabled }), ...(layers === undefined ? {} : { layers: layers }), ...(reflectionValue.maxInjectedEntries === undefined ? {} : { maxInjectedEntries: reflectionValue.maxInjectedEntries }), ...(reflectionValue.maxInjectedTokens === undefined ? {} : { maxInjectedTokens: reflectionValue.maxInjectedTokens }) };
+    }
     if (manifestPath !== undefined && (typeof manifestPath !== "string" || manifestPath.length === 0)) {
         return undefined;
     }
@@ -262,6 +279,7 @@ function parseLayer(value) {
         freeTierFallbackModels: freeTierFallbackModels,
         consultation,
         continuation,
+        reflection,
     };
 }
 /** Merge defaults, optional project/env configuration, then the host override. */
@@ -275,6 +293,7 @@ export function resolvePluginConfiguration(...values) {
     let freeTierFallbackModels = DEFAULT_PLUGIN_OPTIONS.freeTierFallbackModels;
     let consultation = DEFAULT_PLUGIN_OPTIONS.consultation;
     let continuation = DEFAULT_PLUGIN_OPTIONS.continuation;
+    let reflection = DEFAULT_PLUGIN_OPTIONS.reflection;
     const configuredRoles = new Set();
     for (const value of values) {
         const layer = parseLayer(value);
@@ -314,6 +333,8 @@ export function resolvePluginConfiguration(...values) {
         if (layer.continuation !== undefined) {
             continuation = Object.freeze({ ...continuation, ...layer.continuation });
         }
+        if (layer.reflection !== undefined)
+            reflection = Object.freeze({ ...reflection, ...layer.reflection, layers: Object.freeze({ ...reflection.layers, ...(layer.reflection.layers ?? {}) }) });
     }
     modelRouting = {
         ...Object.fromEntries(Object.entries(modelRouting).filter(([role]) => !isFixedModelRole(role))),
@@ -346,6 +367,7 @@ export function resolvePluginConfiguration(...values) {
         freeTierFallbackModels,
         consultation,
         continuation,
+        reflection,
     };
 }
 /** Resolve the plugin's fixed source boundaries: project-local first, environment and host global. */

package/dist/plugin/index.d.ts

@@ -28,6 +28,12 @@ export interface OpenCodeHooks {
     "tool.execute.before"?: (input: ToolExecuteBeforeInput, output: ToolExecuteBeforeOutput) => Promise<void>;
     "tool.execute.after"?: (input: TaskToolExecuteAfterInput, output: TaskResultRepairOutput) => Promise<void>;
     "chat.message"?: OpenCodeChatMessageHook;
+    "experimental.chat.system.transform"?: (input: {
+        sessionID: string;
+    }, output: {
+        system?: string[];
+        model?: unknown;
+    }) => Promise<void>;
     /** Continuation observes the coordinator's completed final text to honour its fallback markers. */
     "experimental.text.complete"?: (input: {
         sessionID: string;

package/dist/plugin/index.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
-import { isAbsolute, resolve, sep } from "node:path";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import { RUNTIME_ASSET_VERSION } from "../asset-version.js";
 import { normalizeRelativePath, RelativePathError } from "../core/path.js";
 import { validateManifest } from "../core/validate-manifest.js";
@@ -10,6 +10,7 @@ import { CONTINUATION_CAPABILITY, createContinuationHooks, } from "./continuatio
 import { WriteDeniedError, createProjectPaths, createWriteGate, describeUnclassifiedCommand, isKnownReadOnlyTool, normalizeCommand, resolveProjectRoot, safePath, } from "./gate.js";
 import { createModelRoutingHook, } from "./model-routing-hook.js";
 import { createTaskResultRepairHook, } from "./task-result-repair.js";
+import { configRoot, nearestPackageVersion, reflectionEnabled, ReflectionError, ReflectionStore } from "../reflection/index.js";
 const INPUT_LIMITS = { config: 64 * 1024, manifest: 512 * 1024, handoff: 2 * 1024 * 1024 };
 const INSPECTION_CACHE = { maximum: 256, ttlMilliseconds: 30 * 60 * 1000 };
 const ACTIVE_SESSION_CACHE = { maximum: 256, ttlMilliseconds: 30 * 60 * 1000 };
@@ -228,6 +229,7 @@ function loadConfigured(config, handoffBase, client) {
         readOnlyTools: new Set(config.readOnlyTools.map((tool) => tool.toLowerCase())),
         modelRoutingHook,
         continuation: config.continuation,
+        reflection: config.reflection,
     };
 }
 function samePath(left, right) {
@@ -392,12 +394,51 @@ export const SortieDogsPlugin = async (input, options) => {
     const defineTool = validToolCandidate
         ? toolCandidate
         : Object.assign((definition) => definition, { schema: { string: () => ({ type: "string" }) } });
+    const optionalString = () => {
+        const stringSchema = defineTool.schema.string();
+        if (isRecord(stringSchema) && typeof stringSchema.optional === "function") {
+            return stringSchema.optional();
+        }
+        return typeof defineTool.schema.optional === "function" ? defineTool.schema.optional(stringSchema) : stringSchema;
+    };
     let project;
+    let reflectionStartup = false;
+    let reflectionConfiguration;
+    let reflectionVersion;
+    let reflectionStore;
     let loaded;
     let loadFailure;
     let loading;
     let manifestAbsent = false;
     let assetVersionReported = false;
+    // 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 {
+        project = await createProjectPaths(resolveProjectRoot(input));
+        const probed = resolvePluginConfigurationSources(await readOptionalProjectConfig(project), readEnvironmentConfig(), options);
+        if (probed.kind === "configured" && reflectionEnabled(probed.reflection)) {
+            reflectionVersion = await nearestPackageVersion();
+            reflectionConfiguration = probed.reflection;
+            reflectionStore = new ReflectionStore(join(configRoot(), "sortie-dogs", "reflection"), project.root, {
+                warn: (code) => {
+                    const log = input.client?.app;
+                    if (!isRecord(log) || typeof log.log !== "function")
+                        return;
+                    try {
+                        log.log({ level: "warn", service: "sortie-dogs", message: code });
+                    }
+                    catch { /* host logging is best effort */ }
+                },
+            });
+            reflectionStartup = true;
+        }
+    }
+    catch {
+        reflectionStartup = false;
+        reflectionConfiguration = undefined;
+        reflectionVersion = undefined;
+        reflectionStore = undefined;
+    }
     /*
      * Continuation must be callable before the first lazy configuration load completes, so it reads
      * the effective policy at call time and falls back to the shipped default until then.
@@ -484,6 +525,10 @@ export const SortieDogsPlugin = async (input, options) => {
     const bindingPins = new Map();
     const activeSessions = new Map();
     const coordinatorRoots = new Map();
+    const reflectionOwnedRoots = new Set();
+    const reflectionClosingRoots = new Set();
+    const reflectionInFlight = new Map();
+    const reflectionWaiters = new Map();
     const bindingDenials = new Map();
     const expiredSessions = new Set();
     const sessionParents = new Map();
@@ -1117,6 +1162,7 @@ export const SortieDogsPlugin = async (input, options) => {
             return {
                 ...(typeof payload.agent === "string" ? { agent: payload.agent } : {}),
                 ...(typeof payload.parentID === "string" ? { parentID: payload.parentID } : {}),
+                parentPresent: "parentID" in payload,
             };
         }
         catch {
@@ -1135,7 +1181,7 @@ export const SortieDogsPlugin = async (input, options) => {
         if (child?.parentID === undefined)
             return undefined;
         const parent = await hostSessionIdentity(child.parentID);
-        if (parent?.agent !== COORDINATOR_AGENT || parent.parentID !== undefined)
+        if (parent?.agent !== COORDINATOR_AGENT || parent.parentPresent)
             return undefined;
         await rememberCoordinatorRoot(child.parentID);
         rememberParent(sessionID, child.parentID);
@@ -1151,7 +1197,51 @@ export const SortieDogsPlugin = async (input, options) => {
             }
         }
     }
-    return {
+    async function reflectionPermitted(sessionID, agent) {
+        if (!reflectionStartup || reflectionStore === undefined || reflectionVersion === undefined || process.env.SORTIE_REFLECTION === "0")
+            return false;
+        if (agent !== undefined && agent !== COORDINATOR_AGENT)
+            return false;
+        if (!isCoordinatorSession(sessionID) || coordinatorRootForSession(sessionID) !== sessionID || sessionParents.has(sessionID))
+            return false;
+        const identity = await hostSessionIdentity(sessionID);
+        if (identity?.agent !== COORDINATOR_AGENT || identity.parentPresent)
+            return false;
+        return true;
+    }
+    async function beginReflection(sessionID, agent) {
+        if (!(await reflectionPermitted(sessionID, agent)) || reflectionClosingRoots.has(sessionID))
+            return false;
+        reflectionOwnedRoots.add(sessionID);
+        reflectionInFlight.set(sessionID, (reflectionInFlight.get(sessionID) ?? 0) + 1);
+        return true;
+    }
+    function endReflection(sessionID) {
+        const remaining = (reflectionInFlight.get(sessionID) ?? 1) - 1;
+        if (remaining > 0) {
+            reflectionInFlight.set(sessionID, remaining);
+            return;
+        }
+        reflectionInFlight.delete(sessionID);
+        for (const resolve of reflectionWaiters.get(sessionID) ?? [])
+            resolve();
+        reflectionWaiters.delete(sessionID);
+    }
+    async function waitForReflections(sessionID) {
+        if ((reflectionInFlight.get(sessionID) ?? 0) === 0)
+            return;
+        await new Promise((resolve) => (reflectionWaiters.get(sessionID) ?? reflectionWaiters.set(sessionID, []).get(sessionID)).push(resolve));
+    }
+    function reflectionWarning(code) {
+        const log = input.client?.app;
+        if (!isRecord(log) || typeof log.log !== "function")
+            return;
+        try {
+            log.log({ level: "warn", service: "sortie-dogs", message: code });
+        }
+        catch { /* host logging is best effort */ }
+    }
+    const hooks = {
         tool: {
             sortie_bind_write_gate: defineTool({
                 description: "Bind this active session to one project-relative operation manifest without changing files.",
@@ -1194,6 +1284,36 @@ export const SortieDogsPlugin = async (input, options) => {
                     return await continuation.tool.execute({}, context);
                 },
             }),
+            ...(reflectionStartup ? {
+                sortie_reflection: defineTool({
+                    description: "Record, promote, or clear a bounded process reflection.",
+                    args: { action: defineTool.schema.string(), layer: defineTool.schema.string(), scope: optionalString(), trigger: optionalString(), cause: optionalString(), prevention: optionalString(), evidence: optionalString(), evidenceRef: optionalString(), id: optionalString(), promotedRef: optionalString(), confirmation: optionalString() },
+                    async execute(args, context) {
+                        if (!(await beginReflection(context.sessionID, context.agent)))
+                            return "reflection_not_permitted";
+                        const layer = args.layer;
+                        try {
+                            if (!["run", "project", "global"].includes(layer))
+                                return "reflection_invalid_layer";
+                            if (!(reflectionConfiguration?.layers[layer] ?? false))
+                                return "reflection_not_permitted";
+                            if (args.action === "record")
+                                return JSON.stringify(await reflectionStore.record(layer, context.sessionID, args, reflectionVersion));
+                            if (args.action === "promote")
+                                return await reflectionStore.promote(layer, context.sessionID, args.id, args.promotedRef, reflectionVersion);
+                            if (args.action === "clear")
+                                return await reflectionStore.clear(layer, context.sessionID, args.confirmation, reflectionVersion);
+                            return "reflection_invalid_action";
+                        }
+                        catch (error) {
+                            return error instanceof ReflectionError ? error.code : "reflection_storage_error";
+                        }
+                        finally {
+                            endReflection(context.sessionID);
+                        }
+                    },
+                }),
+            } : {}),
         },
         "experimental.text.complete": async (textInput, textOutput) => {
             await continuation.textComplete(textInput, textOutput);
@@ -1238,6 +1358,25 @@ export const SortieDogsPlugin = async (input, options) => {
             await ensureLoaded();
             await loaded?.modelRoutingHook?.(chatInput, output);
         },
+        ...(reflectionStartup ? { "experimental.chat.system.transform": async (transformInput, transformOutput) => {
+                if (!(await beginReflection(transformInput.sessionID)))
+                    return;
+                const config = reflectionConfiguration;
+                try {
+                    if (!config)
+                        return;
+                    const buckets = ["run", "project", "global"]
+                        .filter((layer) => config.layers[layer])
+                        .map((layer) => ({ layer, ...(layer === "global" ? {} : { run: transformInput.sessionID }) }));
+                    const text = await reflectionStore.injectBuckets(buckets, config.maxInjectedEntries, config.maxInjectedTokens, reflectionVersion);
+                    if (text)
+                        transformOutput.system = [...(transformOutput.system ?? []), text];
+                }
+                catch { /* reflection is strictly non-invasive */ }
+                finally {
+                    endReflection(transformInput.sessionID);
+                }
+            } } : {}),
         "permission.ask": async (permission) => {
             if (permission.permission !== "edit")
                 return;
@@ -1348,6 +1487,28 @@ export const SortieDogsPlugin = async (input, options) => {
                 return;
             }
             if (event.type === "session.deleted") {
+                if (reflectionStore !== undefined && reflectionConfiguration?.layers.run && reflectionOwnedRoots.has(eventSessionID)) {
+                    reflectionClosingRoots.add(eventSessionID);
+                    await waitForReflections(eventSessionID);
+                    let deleted = false;
+                    for (const delay of [0, 50, 250, 1_000, 5_000]) {
+                        if (delay > 0)
+                            await new Promise((resolve) => setTimeout(resolve, delay));
+                        try {
+                            await reflectionStore.deleteRun(eventSessionID);
+                            deleted = true;
+                        }
+                        catch { /* bounded retry below */ }
+                        if (deleted)
+                            break;
+                    }
+                    if (deleted) {
+                        reflectionOwnedRoots.delete(eventSessionID);
+                        reflectionClosingRoots.delete(eventSessionID);
+                    }
+                    else
+                        reflectionWarning("reflection_cleanup_failed");
+                }
                 evictSession(eventSessionID);
                 continuation.forgetSession(eventSessionID);
                 return;
@@ -1377,5 +1538,6 @@ export const SortieDogsPlugin = async (input, options) => {
             }
         },
     };
+    return hooks;
 };
 export { InvalidModelTargetError, ModelRoutingDeniedError } from "./model-routing-hook.js";

package/dist/reflection/config.d.ts

@@ -0,0 +1,7 @@
+import type { ReflectionConfiguration } from "../plugin/config.js";
+export type ReflectionLayer = "run" | "project" | "global";
+export declare const DEFAULT_REFLECTION: ReflectionConfiguration;
+export declare function reflectionEnabled(config: ReflectionConfiguration, env?: string | undefined): boolean;
+export declare function projectKey(root: string): string;
+export declare function configRoot(explicit?: string): string;
+export declare function nearestPackageVersion(): Promise<string>;

package/dist/reflection/config.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+export const DEFAULT_REFLECTION = Object.freeze({ enabled: false, layers: Object.freeze({ run: true, project: true, global: false }), maxInjectedEntries: 3, maxInjectedTokens: 500 });
+export function reflectionEnabled(config, env = process.env.SORTIE_REFLECTION) {
+    return env === "0" ? false : config.enabled;
+}
+export function projectKey(root) {
+    const normalized = resolve(root).replaceAll("\\", "/").replace(/\/+$/u, "");
+    return createHash("sha256").update(process.platform === "win32" ? normalized.toLowerCase() : normalized).digest("hex").slice(0, 16);
+}
+export function configRoot(explicit) {
+    if (explicit)
+        return resolve(explicit);
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, "opencode");
+    return join(homedir(), ".config", "opencode");
+}
+export async function nearestPackageVersion() {
+    try {
+        const file = join(resolve(fileURLToPath(import.meta.url), "..", "..", ".."), "package.json");
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (typeof parsed.version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(parsed.version))
+            throw new Error("invalid");
+        return parsed.version;
+    }
+    catch {
+        throw new Error("reflection_version_unavailable");
+    }
+}

package/dist/reflection/index.d.ts

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

package/dist/reflection/index.js

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

package/dist/reflection/store.d.ts

@@ -0,0 +1,76 @@
+import { type ReflectionLayer } from "./config.js";
+export type Evidence = "user-correction" | "repeated-process-failure" | "review-artifact-defect" | "retry-policy-violation";
+export type EntryStatus = "active" | "promotable" | "promoted";
+export interface ReflectionEntry {
+    id: string;
+    scope: string;
+    trigger: string;
+    cause: string;
+    prevention: string;
+    evidence: Evidence;
+    evidenceRef: string;
+    hits: number;
+    firstSeen: string;
+    lastSeen: string;
+    status: EntryStatus;
+    promotedRef?: string;
+    promotedAtVersion?: string;
+}
+export interface ReflectionBucket {
+    v: 1;
+    updatedAt: string;
+    entries: ReflectionEntry[];
+}
+export interface ReflectionStoreOptions {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    warn?: (code: string) => void;
+    processAlive?: (pid: number) => boolean;
+}
+export declare class ReflectionError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function normalizeField(value: unknown, max: number, scope?: boolean): string;
+export declare function estimateInjectionTokens(text: string): number;
+export declare class ReflectionStore {
+    private readonly root;
+    private readonly projectRoot;
+    private readonly warned;
+    private readonly now;
+    private readonly sleep;
+    private readonly warn;
+    private readonly processAlive;
+    constructor(root: string, projectRoot: string, options?: ReflectionStoreOptions);
+    private file;
+    private warning;
+    private artifacts;
+    private temps;
+    private load;
+    private validEntry;
+    private owner;
+    private live;
+    private heartbeat;
+    private acquire;
+    private stale;
+    private recoveryClaims;
+    private recoverGuard;
+    private recoverStale;
+    private lock;
+    private pathGuard;
+    private releaseGuard;
+    private withOwnership;
+    private release;
+    private save;
+    read(layer: ReflectionLayer, run?: string, currentVersion?: string): Promise<ReflectionBucket>;
+    private transaction;
+    record(layer: ReflectionLayer, run: string | undefined, input: Record<string, unknown>, currentVersion: string): Promise<ReflectionEntry>;
+    promote(layer: ReflectionLayer, run: string | undefined, id: string, ref: string, currentVersion: string): Promise<string>;
+    clear(layer: ReflectionLayer, run: string | undefined, confirmation: string, currentVersion: string): Promise<string>;
+    deleteRun(run: string): Promise<void>;
+    inject(layer: ReflectionLayer, run: string | undefined, max: number, tokenBudget: number, currentVersion: string): Promise<string>;
+    injectBuckets(buckets: readonly {
+        layer: ReflectionLayer;
+        run?: string;
+    }[], max: number, tokenBudget: number, currentVersion?: string): Promise<string>;
+}

package/dist/reflection/store.js

@@ -0,0 +1,321 @@
+import { randomBytes } from "node:crypto";
+import { chmod, copyFile, mkdir, open, readFile, readdir, rename, rm, stat, unlink } from "node:fs/promises";
+import { dirname, join, basename } from "node:path";
+import { projectKey } from "./config.js";
+export class ReflectionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const EMPTY = () => ({ v: 1, updatedAt: new Date(0).toISOString(), entries: [] });
+const evidence = new Set(["user-correction", "repeated-process-failure", "review-artifact-defect", "retry-policy-violation"]);
+const caps = { run: 12, project: 24, global: 16 };
+const ages = { run: 6 * 3600000, project: 30 * 86400000, global: 90 * 86400000 };
+const MAX_LEASE_AGE = 60_000;
+const activeTokens = new Set();
+const prohibited = /[\n\r\t\u0000-\u001f\u007f]|```|(?:api[_ -]?key|password|secret|token)|private\s+key|https?:\/\/|(?:^|\s)[+\-]{3}(?:\s|$)|\b[0-9a-f]{32,}\b|\b[A-Za-z0-9+/]{40,}={0,2}\b/iu;
+const jsonBytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+function version(value) { const match = /^(?:v)?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value); if (!match)
+    return { core: [0, 0, 0] }; return { core: [Number(match[1]), Number(match[2]), Number(match[3])], ...(match[4] === undefined ? {} : { pre: match[4].split(".") }) }; }
+function comparePre(left, right) { for (let index = 0; index < Math.max(left.length, right.length); index++) {
+    const a = left[index], b = right[index];
+    if (a === undefined)
+        return -1;
+    if (b === undefined)
+        return 1;
+    if (a === b)
+        continue;
+    const aNumber = /^\d+$/u.test(a), bNumber = /^\d+$/u.test(b);
+    if (aNumber && bNumber) {
+        const normalizedA = a.replace(/^0+(?=\d)/u, ""), normalizedB = b.replace(/^0+(?=\d)/u, "");
+        return normalizedA.length === normalizedB.length ? (normalizedA > normalizedB ? 1 : -1) : (normalizedA.length > normalizedB.length ? 1 : -1);
+    }
+    if (aNumber !== bNumber)
+        return aNumber ? -1 : 1;
+    return a > b ? 1 : -1;
+} return 0; }
+function greaterVersion(left, right) { const a = version(left), b = version(right); for (let index = 0; index < 3; index++) {
+    if (a.core[index] !== b.core[index])
+        return a.core[index] > b.core[index];
+} if (a.pre === undefined || b.pre === undefined)
+    return a.pre === undefined && b.pre !== undefined; return comparePre(a.pre, b.pre) > 0; }
+function redact(value) { if (!/[\\/]/u.test(value) || /:\/\//u.test(value))
+    return value; let result = value.replace(/[A-Za-z]:[\\/](?:[^\s\\/]+[\\/])*([^\s\\/]+)/gu, "$1"); return result.replace(/(^|\s)\/(?:[^\s/]+\/)*([^\s/]+)/gu, (_match, lead, leaf) => `${lead}${leaf}`).replace(/(^|\s)(?:[^\s\\/]+[\\/])+([^\s\\/]+)/gu, (_match, lead, leaf) => `${lead}${leaf}`); }
+export function normalizeField(value, max, scope = false) { if (typeof value !== "string" || value.length === 0)
+    throw new ReflectionError("reflection_invalid_input"); const clean = scope ? value.toLowerCase() : redact(value); if (clean.length > max || prohibited.test(clean) || (scope && !/^[a-z0-9-]+$/u.test(clean)))
+    throw new ReflectionError("reflection_invalid_input"); return clean; }
+function shortRef(value) { if (typeof value !== "string" || value.length === 0 || value.length > 64 || /[\\/]|\.log\b|(?:log|line|stack\s+trace|diff)\s*[:#]?/iu.test(value) || prohibited.test(value))
+    throw new ReflectionError("reflection_invalid_input"); return value; }
+export function estimateInjectionTokens(text) { return Buffer.byteLength(text, "utf8"); }
+function ulid() { const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; let timestamp = Date.now(), time = ""; for (let i = 0; i < 10; i++) {
+    time = alphabet[timestamp % 32] + time;
+    timestamp = Math.floor(timestamp / 32);
+} let random = ""; for (const byte of randomBytes(16))
+    random += alphabet[byte & 31]; return time + random; }
+function pathFor(root, layer, projectRoot, run) { if (layer === "run" && (typeof run !== "string" || !/^[A-Za-z0-9_-]{1,128}$/u.test(run)))
+    throw new ReflectionError("reflection_invalid_run"); return layer === "global" ? join(root, "global.json") : layer === "project" ? join(root, "projects", `${projectKey(projectRoot)}.json`) : join(root, "runs", `${run}.json`); }
+export class ReflectionStore {
+    root;
+    projectRoot;
+    warned = new Set();
+    now;
+    sleep;
+    warn;
+    processAlive;
+    constructor(root, projectRoot, options = {}) {
+        this.root = root;
+        this.projectRoot = projectRoot;
+        this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.warn = options.warn ?? (() => undefined);
+        this.processAlive = options.processAlive ?? ((pid) => { try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        } });
+    }
+    file(layer, run) { return pathFor(this.root, layer, this.projectRoot, run); }
+    warning(file, code) { const key = `${file}:${code}`; if (!this.warned.has(key)) {
+        this.warned.add(key);
+        this.warn(code);
+    } }
+    async artifacts(file, olderThan) { const dir = dirname(file), prefix = `${basename(file)}.`; const names = await readdir(dir).catch(() => []); for (const name of names) {
+        if (!name.startsWith(prefix) || name.startsWith(`${basename(file)}.lock`))
+            continue;
+        const path = join(dir, name), info = await stat(path).catch(() => undefined);
+        if (olderThan !== undefined && (info === undefined || info.mtimeMs >= olderThan))
+            continue;
+        await rm(path, { force: true }).catch(() => undefined);
+    } }
+    async temps(file) { const dir = dirname(file); for (const name of await readdir(dir).catch(() => []))
+        if (name.startsWith(`${basename(file)}.`) && name.endsWith(".tmp"))
+            await rm(join(dir, name), { force: true }).catch(() => undefined); }
+    async load(file, layer, currentVersion, lock) {
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (parsed.v !== 0 && parsed.v !== 1 && (parsed.v ?? 0) > 1) {
+                this.warning(file, "reflection_future_schema");
+                return { bucket: EMPTY(), future: true, legacy: false, changed: false };
+            }
+            if (parsed.v !== 0 && parsed.v !== 1 || typeof parsed.updatedAt !== "string" || Number.isNaN(Date.parse(parsed.updatedAt)) || !Array.isArray(parsed.entries))
+                throw new Error("invalid");
+            const bucket = { v: 1, updatedAt: parsed.updatedAt, entries: parsed.entries };
+            if (!bucket.entries.every((entry) => this.validEntry(entry)))
+                throw new Error("invalid");
+            const cutoff = this.now() - ages[layer];
+            const before = bucket.entries.length;
+            bucket.entries = bucket.entries.filter((entry) => Date.parse(entry.lastSeen) >= cutoff && !(currentVersion && entry.status === "promoted" && entry.promotedAtVersion && greaterVersion(currentVersion, entry.promotedAtVersion)));
+            return { bucket, future: false, legacy: parsed.v === 0, changed: parsed.v === 0 || before !== bucket.entries.length };
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return { bucket: EMPTY(), future: false, legacy: false, changed: false };
+            await this.withOwnership(lock, async () => { await rename(file, `${file}.corrupt.${this.now()}`); });
+            this.warning(file, "reflection_corrupt_json");
+            return { bucket: EMPTY(), future: false, legacy: false, changed: false };
+        }
+    }
+    validEntry(entry) { if (!entry || typeof entry !== "object" || jsonBytes(entry) > 512)
+        return false; const item = entry; try {
+        normalizeField(item.scope, 80, true);
+        normalizeField(item.trigger, 160);
+        normalizeField(item.cause, 360);
+        normalizeField(item.prevention, 500);
+        shortRef(item.evidenceRef);
+        if (item.status === "promoted") {
+            shortRef(item.promotedRef);
+            if (typeof item.promotedAtVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(item.promotedAtVersion))
+                return false;
+        }
+        return /^[0-9A-HJKMNP-TV-Z]{26}$/u.test(item.id) && evidence.has(item.evidence) && ["active", "promotable", "promoted"].includes(item.status) && Number.isInteger(item.hits) && item.hits > 0 && !Number.isNaN(Date.parse(item.lastSeen)) && !Number.isNaN(Date.parse(item.firstSeen));
+    }
+    catch {
+        return false;
+    } }
+    owner(token) { return JSON.stringify({ pid: process.pid, token }); }
+    live(raw) { try {
+        const owner = JSON.parse(raw ?? "");
+        if (typeof owner.token !== "string" || typeof owner.pid !== "number" || !Number.isInteger(owner.pid))
+            return false;
+        return owner.pid === process.pid ? activeTokens.has(owner.token) : this.processAlive(owner.pid);
+    }
+    catch {
+        return false;
+    } }
+    async heartbeat(handle, owner) { await handle.truncate(0); await handle.write(owner, 0, "utf8"); await handle.sync(); }
+    async acquire(path) { const token = randomBytes(24).toString("hex"), owner = this.owner(token); const handle = await open(path, "wx", 0o600); activeTokens.add(token); try {
+        await this.heartbeat(handle, owner);
+        const timer = setInterval(() => { void this.heartbeat(handle, owner).catch(() => undefined); }, 1000);
+        timer.unref();
+        return { handle, path, token, timer };
+    }
+    catch (error) {
+        const opened = await handle.stat().catch(() => undefined), removedOpen = await unlink(path).then(() => true).catch(() => false);
+        await handle.close().catch(() => undefined);
+        if (!removedOpen && opened !== undefined) {
+            const current = await stat(path).catch(() => undefined);
+            if (current !== undefined && current.dev === opened.dev && current.ino === opened.ino && Date.now() - current.mtimeMs <= 5000)
+                await unlink(path).catch(() => undefined);
+        }
+        activeTokens.delete(token);
+        throw error;
+    } }
+    async stale(path, finiteLease) { const info = await stat(path).catch(() => undefined); if (!info)
+        return false; const age = this.now() - info.mtimeMs; return age > 5000 && ((finiteLease && age > MAX_LEASE_AGE) || !this.live(await readFile(path, "utf8").catch(() => undefined))); }
+    async recoveryClaims(path) { const prefix = `${basename(path)}.recover.`; const claims = (await readdir(dirname(path)).catch(() => [])).filter((name) => name.startsWith(prefix)).map((name) => join(dirname(path), name)); for (const claim of claims)
+        if (await this.stale(claim, false))
+            await unlink(claim).catch(() => undefined); return (await readdir(dirname(path)).catch(() => [])).filter((name) => name.startsWith(prefix)).map((name) => join(dirname(path), name)).sort(); }
+    async recoverGuard(path) { if (!await this.stale(path, false))
+        return false; const claim = await this.acquire(`${path}.recover.${randomBytes(12).toString("hex")}`); try {
+        const claims = await this.recoveryClaims(path);
+        if (claims[0] !== claim.path || !await this.stale(path, false))
+            return false;
+        await unlink(path).catch(() => undefined);
+        return true;
+    }
+    finally {
+        await this.releaseGuard(claim);
+    } }
+    async recoverStale(path) { if (!await this.stale(path, true))
+        return false; const guard = await this.pathGuard(path); if (!guard)
+        return false; try {
+        if (!await this.stale(path, true))
+            return false;
+        await unlink(path).catch(() => undefined);
+        return true;
+    }
+    finally {
+        await this.releaseGuard(guard);
+    } }
+    async lock(file) { const path = `${file}.lock`; for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            return await this.acquire(path);
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST")
+                throw new ReflectionError("reflection_lock_timeout");
+            await this.recoverStale(path);
+            await this.sleep(10 * 2 ** attempt);
+        }
+    } throw new ReflectionError("reflection_lock_timeout"); }
+    async pathGuard(path) { const guard = `${path}.guard`; for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            if ((await this.recoveryClaims(guard)).length > 0) {
+                await this.sleep(2 ** attempt);
+                continue;
+            }
+            const candidate = await this.acquire(guard);
+            if ((await this.recoveryClaims(guard)).length === 0)
+                return candidate;
+            await this.releaseGuard(candidate);
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST")
+                return undefined;
+            await this.recoverGuard(guard);
+        }
+        await this.sleep(2 ** attempt);
+    } return undefined; }
+    async releaseGuard(guard) { clearInterval(guard.timer); await guard.handle.close().catch(() => undefined); try {
+        if (await readFile(guard.path, "utf8").catch(() => undefined) === this.owner(guard.token))
+            await unlink(guard.path).catch(() => undefined);
+    }
+    finally {
+        activeTokens.delete(guard.token);
+    } }
+    async withOwnership(lock, action) { const guard = await this.pathGuard(lock.path); if (!guard)
+        throw new ReflectionError("reflection_lock_lost"); try {
+        if (await readFile(lock.path, "utf8").catch(() => undefined) !== this.owner(lock.token))
+            throw new ReflectionError("reflection_lock_lost");
+        return await action();
+    }
+    finally {
+        await this.releaseGuard(guard);
+    } }
+    async release(lock) { clearInterval(lock.timer); await lock.handle.close().catch(() => undefined); try {
+        await this.withOwnership(lock, async () => { await unlink(lock.path); });
+    }
+    catch { /* a newer owner or stale recovery owns the path */ }
+    finally {
+        activeTokens.delete(lock.token);
+    } }
+    async save(file, bucket, lock) { if (bucket.entries.some((entry) => jsonBytes(entry) > 512) || jsonBytes(bucket) > 32768)
+        throw new ReflectionError("reflection_size_limit"); const temp = `${file}.${ulid()}.tmp`; const handle = await open(temp, "w", 0o600); try {
+        await handle.writeFile(JSON.stringify(bucket));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    } await chmod(temp, 0o600).catch(() => undefined); try {
+        await this.withOwnership(lock, async () => { await rename(temp, file); });
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    } const dir = await open(dirname(file), "r").catch(() => undefined); await dir?.sync().catch(() => undefined); await dir?.close().catch(() => undefined); }
+    async read(layer, run, currentVersion) { const file = this.file(layer, run); if (!await stat(dirname(file)).catch(() => undefined))
+        return EMPTY(); const lock = await this.lock(file); try {
+        await this.withOwnership(lock, async () => { await this.temps(file); await this.artifacts(file, this.now() - ages[layer]); });
+        const loaded = await this.load(file, layer, currentVersion, lock);
+        if (loaded.future)
+            return loaded.bucket;
+        if (loaded.changed) {
+            if (loaded.legacy)
+                await this.withOwnership(lock, async () => { await copyFile(file, `${file}.v0.bak`); });
+            await this.save(file, loaded.bucket, lock);
+        }
+        return loaded.bucket;
+    }
+    finally {
+        await this.release(lock);
+    } }
+    async transaction(layer, run, currentVersion, fn) { const file = this.file(layer, run); await mkdir(dirname(file), { recursive: true, mode: 0o700 }); await chmod(dirname(file), 0o700).catch(() => undefined); const lock = await this.lock(file); try {
+        const loaded = await this.load(file, layer, currentVersion, lock);
+        if (loaded.future)
+            throw new ReflectionError("reflection_future_schema");
+        if (loaded.legacy)
+            await this.withOwnership(lock, async () => { await copyFile(file, `${file}.v0.bak`); });
+        const result = await fn(loaded.bucket, file, lock);
+        await this.save(file, loaded.bucket, lock);
+        return result;
+    }
+    finally {
+        await this.release(lock);
+    } }
+    async record(layer, run, input, currentVersion) { if (!evidence.has(input.evidence))
+        throw new ReflectionError("reflection_invalid_evidence"); const now = new Date(this.now()).toISOString(); const entry = { id: ulid(), scope: normalizeField(input.scope, 80, true), trigger: normalizeField(input.trigger, 160), cause: normalizeField(input.cause, 360), prevention: normalizeField(input.prevention, 500), evidence: input.evidence, evidenceRef: shortRef(input.evidenceRef), hits: 1, firstSeen: now, lastSeen: now, status: input.evidence === "user-correction" ? "promotable" : "active" }; if (jsonBytes(entry) > 512)
+        throw new ReflectionError("reflection_size_limit"); return this.transaction(layer, run, currentVersion, async (bucket) => { const same = bucket.entries.find((item) => item.scope === entry.scope); if (same) {
+        same.hits++;
+        same.lastSeen = now;
+        same.status = same.hits >= 2 || same.evidence === "user-correction" ? "promotable" : same.status;
+        bucket.updatedAt = now;
+        return same;
+    } bucket.entries.push(entry); while (bucket.entries.length > caps[layer])
+        bucket.entries.sort((a, b) => a.hits - b.hits || a.lastSeen.localeCompare(b.lastSeen) || a.id.localeCompare(b.id)).shift(); bucket.updatedAt = now; return entry; }); }
+    async promote(layer, run, id, ref, currentVersion) { return this.transaction(layer, run, currentVersion, async (bucket) => { const entry = bucket.entries.find((item) => item.id === id); if (!entry)
+        throw new ReflectionError("reflection_not_found"); if (entry.status !== "promotable")
+        throw new ReflectionError("reflection_not_promotable"); entry.status = "promoted"; entry.promotedRef = shortRef(ref); entry.promotedAtVersion = currentVersion; bucket.updatedAt = new Date(this.now()).toISOString(); return "promoted"; }); }
+    async clear(layer, run, confirmation, currentVersion) { if ((layer !== "run") && confirmation !== "CLEAR_REFLECTIONS")
+        throw new ReflectionError("reflection_confirmation_required"); return this.transaction(layer, run, currentVersion, async (bucket, file, lock) => { bucket.entries = []; bucket.updatedAt = new Date(this.now()).toISOString(); await this.withOwnership(lock, async () => { await this.artifacts(file); }); return "cleared"; }); }
+    async deleteRun(run) { const file = this.file("run", run); if (!await stat(dirname(file)).catch(() => undefined))
+        return; const lock = await this.lock(file); try {
+        await this.withOwnership(lock, async () => { await this.artifacts(file); await rm(file, { force: true }); });
+    }
+    finally {
+        await this.release(lock);
+    } }
+    async inject(layer, run, max, tokenBudget, currentVersion) { return this.injectBuckets([{ layer, run }], max, tokenBudget, currentVersion); }
+    async injectBuckets(buckets, max, tokenBudget, currentVersion) { const byScope = new Map(); for (const { layer, run } of buckets)
+        for (const entry of (await this.read(layer, run, currentVersion)).entries)
+            if (!byScope.has(entry.scope))
+                byScope.set(entry.scope, entry); const entries = [...byScope.values()].sort((a, b) => b.hits - a.hits || a.lastSeen.localeCompare(b.lastSeen) || a.id.localeCompare(b.id)); const lines = []; for (const entry of entries) {
+        const line = `- ${entry.scope}: ${entry.prevention}`;
+        if (lines.length >= max || estimateInjectionTokens([...lines, line].join("\n")) > tokenBudget)
+            break;
+        lines.push(line);
+    } return lines.join("\n"); }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sortie-dogs",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Bounded, validated orchestration loop plugin for OpenCode",
   "keywords": [
     "opencode",