@astrosheep/pi-context 0.25.1 → 0.26.0

package/dist/src/context/reset-lifecycle.js

@@ -1,5 +1,5 @@
 import { isContextOverflow, isRecoverableLength } from "@earendil-works/pi-ai";
-import { currentReset } from "./context-window.js";
+import { currentReset, currentWindowId } from "./context-window.js";
 function isAbort(message, outcome, ctx) {
     return outcome === "aborted" || (message.role === "assistant" && message.stopReason === "aborted") || ctx.signal?.aborted === true;
 }
@@ -9,139 +9,166 @@ function isOverflowLike(message, ctx) {
     return isContextOverflow(message, ctx.model?.contextWindow) ||
         (ctx.model !== undefined && isRecoverableLength(message, ctx.model.maxTokens));
 }
+const NO_REQUEST = { phase: "none" };
 export function initialResetControl() {
-    return { request: "none", overflow: "idle" };
+    return { request: NO_REQUEST, overflow: "idle" };
 }
-/**
- * Pure reset-control transition. It performs no writes, no policy resolution of its own, and
- * no UI work; every fact it reads is supplied by the caller. Callers can therefore drive the
- * full transition table without a live Pi session.
- */
+function requestForWindow(request, windowId) {
+    return request.phase !== "none" && request.windowId === windowId ? request : NO_REQUEST;
+}
+/** Pure reset-control transitions: request phases own close-out, tool commit, and fallback. */
 export function reduceResetControl(state, event) {
     switch (event.type) {
-        case "request": {
-            if (state.request === "explicit")
-                return { state, effect: "already-requested" };
-            return { state: { ...state, request: "explicit" }, effect: "requested" };
+        case "close_out": {
+            const request = state.request;
+            if (request.phase === "tool-requested" && request.windowId === event.windowId) {
+                return { state, effect: "already-pending" };
+            }
+            if (request.phase === "close-out" && request.windowId === event.windowId) {
+                if (request.source === "manual" || event.source === "automatic")
+                    return { state, effect: "already-pending" };
+                return { state: { ...state, request: { ...request, source: "manual" } }, effect: "close-out-armed" };
+            }
+            return { state: { ...state, request: { phase: "close-out", windowId: event.windowId, source: event.source } }, effect: "close-out-armed" };
+        }
+        case "tool_request": {
+            const request = state.request;
+            if (request.phase === "tool-requested" && request.windowId === event.windowId)
+                return { state, effect: "already-pending" };
+            return { state: { ...state, request: { phase: "tool-requested", windowId: event.windowId } }, effect: "close-out-armed" };
         }
         case "turn_end": {
             const facts = event.facts;
-            const requested = state.request === "explicit";
-            // The explicit request is consumed by the turn boundary whether or not it commits.
-            const request = "none";
-            if (facts.aborted) {
-                // An aborted turn drops the whole boundary: no explicit request, no overflow chain.
-                return { state: { request, overflow: "idle" }, effect: "none" };
-            }
+            const request = requestForWindow(state.request, facts.windowId);
+            if (facts.aborted)
+                return { state: initialResetControl(), effect: "none" };
             if (facts.overflow) {
-                // A failure that Pi may recover natively: arm (or re-arm) the bounded settle path.
-                // A queued message, disabled mode, or disabled automatic reset leaves it disarmed.
                 const pending = !facts.queued && facts.enabled && facts.automaticResetEnabled;
                 const spent = state.overflow === "pending-spent" || state.overflow === "spent";
                 const overflow = pending
                     ? (spent ? "pending-spent" : "pending")
                     : (spent ? "spent" : "idle");
-                return { state: { request, overflow }, effect: "none" };
+                return { state: { request: NO_REQUEST, overflow }, effect: "none" };
+            }
+            if (facts.failed)
+                return { state: { request: NO_REQUEST, overflow: state.overflow }, effect: "none" };
+            if (!facts.enabled) {
+                return { state: { request: NO_REQUEST, overflow: "idle" }, effect: "none" };
             }
-            // Any non-overflow completed turn supersedes an older overflow failure. A non-overflow
-            // error leaves the armed overflow chain untouched for the settle boundary.
-            const overflow = facts.failed ? state.overflow : "idle";
-            if (!facts.enabled || facts.failed)
-                return { state: { request, overflow }, effect: "none" };
-            // Explicit and threshold resets both commit at turn_end, after incoming and budget drafts.
-            const commit = requested || facts.thresholdDue;
-            return { state: { request, overflow }, effect: commit ? "commit-boundary" : "none" };
+            // A direct tool request commits after the whole tool batch. The budget cutoff is
+            // a separate hard-reserve safety path; ordinary close-out waits for settlement.
+            if (request.phase === "tool-requested" || facts.hardReserveDue) {
+                return { state: { request: NO_REQUEST, overflow: "idle" }, effect: "commit-boundary" };
+            }
+            return { state: { request, overflow: "idle" }, effect: "none" };
         }
         case "before_settle": {
             const facts = event.facts;
-            if (state.overflow !== "pending" && state.overflow !== "pending-spent")
-                return { state, effect: "none" };
-            // Let a queued turn run first; its own turn_end settles or clears this chain.
+            if (facts.aborted)
+                return { state: initialResetControl(), effect: "none" };
+            const request = requestForWindow(state.request, facts.windowId);
+            if (state.overflow === "pending" || state.overflow === "pending-spent") {
+                if (facts.queued) {
+                    return { state: { ...state, request: facts.failed ? NO_REQUEST : request }, effect: "none" };
+                }
+                const spent = state.overflow === "pending-spent";
+                if (!facts.enabled || !facts.automaticResetEnabled) {
+                    return { state: { request: facts.failed ? NO_REQUEST : request, overflow: spent ? "spent" : "idle" }, effect: "none" };
+                }
+                return { state: { request: NO_REQUEST, overflow: "spent" }, effect: spent ? "none" : "recover-overflow" };
+            }
+            if (facts.failed || !facts.enabled || request.phase !== "close-out") {
+                return { state: { ...state, request: NO_REQUEST }, effect: "none" };
+            }
             if (facts.queued)
-                return { state, effect: "none" };
-            const spent = state.overflow === "pending-spent";
-            if (!facts.enabled || !facts.automaticResetEnabled || facts.aborted) {
-                return { state: { ...state, overflow: spent ? "spent" : "idle" }, effect: "none" };
+                return { state: { ...state, request }, effect: "none" };
+            if (request.source === "automatic" && !facts.automaticResetEnabled) {
+                return { state: { ...state, request: NO_REQUEST }, effect: "none" };
             }
-            // The recovery is one-use per failure chain. Committing it spends the attempt.
-            return { state: { ...state, overflow: "spent" }, effect: spent ? "none" : "recover-overflow" };
+            return { state: { request: NO_REQUEST, overflow: "idle" }, effect: "commit-boundary" };
         }
         case "settled":
-            // Settlement ends the failure chain but leaves a pending explicit request armed.
-            return { state: { ...state, overflow: "idle" }, effect: "none" };
+            return { state: initialResetControl(), effect: "none" };
         case "abort":
         case "clear":
             return { state: initialResetControl(), effect: "none" };
     }
 }
 /**
- * Own reset requests at Pi 0.87 boundaries. Persisted windows are custom entries, not
- * compaction summaries: turn_end commits explicit/threshold resets after a complete tool
- * batch, while agent_before_settle commits the one bounded overflow recovery after Pi's
- * native recovery attempt has been cancelled.
- *
- * This function is the effect adapter: it captures Pi events, translates them into pure
- * reset-control transitions, and performs the resulting marker/boot/continuation writes and
- * notifications. The decision of what to do lives entirely in `reduceResetControl`.
+ * Own close-out requests at Pi's public turn and pre-settlement boundaries. Tool-requested
+ * resets commit at turn_end; manual and budget close-outs remain armed across note/tool turns
+ * and fall back at a successful agent_before_settle. Overflow recovery remains bounded.
  */
 export function registerResetLifecycle(pi, options) {
     let sessionActive = true;
+    let lifecycleGeneration = 0;
     let control = initialResetControl();
     const clear = () => { control = reduceResetControl(control, { type: "clear" }).state; };
-    const resetBoundaryResult = (entries, ctx) => {
+    const resetBoundaryResult = async (entries, ctx) => {
+        const generation = lifecycleGeneration;
+        const outerGeneration = options.getLifecycleGeneration?.();
+        const sessionId = ctx.sessionManager.getSessionId();
+        const windowId = currentWindowId(ctx);
+        const isCurrent = () => sessionActive && lifecycleGeneration === generation &&
+            (outerGeneration === undefined || options.getLifecycleGeneration?.() === outerGeneration) && options.isEnabled() &&
+            ctx.signal?.aborted !== true && ctx.sessionManager.getSessionId() === sessionId && currentWindowId(ctx) === windowId;
+        let resetDrafts;
         try {
-            return { entries: [...entries, ...options.buildReset(ctx)], continue: true };
+            resetDrafts = await options.buildReset(ctx, isCurrent);
         }
         catch (error) {
-            ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
-            // The incoming drafts and budget drafts are already valid work from this
-            // boundary. Preserve them, but do not claim a continuation when reset
-            // construction failed.
+            if (isCurrent())
+                ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
             return entries.length > 0 ? { entries } : undefined;
         }
+        if (!isCurrent())
+            return entries.length > 0 ? { entries } : undefined;
+        options.onResetReady?.(ctx, resetDrafts);
+        return { entries: [...entries, ...resetDrafts], continue: true };
     };
-    pi.on("turn_end", (event, ctx) => {
+    pi.on("turn_end", async (event, ctx) => {
         if (!sessionActive)
             return undefined;
         const aborted = isAbort(event.message, event.outcome, ctx);
         const stagedBudgetEntries = options.budget.consumeTurnEnd(ctx);
-        // Lifecycle owns whether drafts are acceptable for this turn. Budget only
-        // drains its instance-local staging, so aborts and disabled mode cannot commit it.
-        const budgetEntries = options.isEnabled() && !aborted ? stagedBudgetEntries : [];
+        const budgetEntries = options.isEnabled() && !aborted && event.outcome !== "error" ? stagedBudgetEntries : [];
         const entries = [...(event.entries ?? []), ...budgetEntries];
         const decision = reduceResetControl(control, {
             type: "turn_end",
             facts: {
+                windowId: currentWindowId(ctx),
                 aborted,
                 overflow: aborted ? false : isOverflowLike(event.message, ctx),
                 failed: event.outcome === "error",
                 enabled: options.isEnabled(),
                 get queued() { return event.context.pendingMessages.length > 0 || ctx.hasPendingMessages(); },
                 get automaticResetEnabled() { return options.budget.automaticResetEnabled(ctx); },
-                get thresholdDue() { return options.budget.resetDue(ctx); },
+                get hardReserveDue() { return options.budget.hardReserveDue(ctx); },
             },
         });
         control = decision.state;
         if (decision.effect === "commit-boundary")
-            return resetBoundaryResult(entries, ctx);
+            return await resetBoundaryResult(entries, ctx);
         return entries.length > 0 ? { entries } : undefined;
     });
-    pi.on("agent_before_settle", (event, ctx) => {
+    pi.on("agent_before_settle", async (event, ctx) => {
         if (!sessionActive)
             return undefined;
         const decision = reduceResetControl(control, {
             type: "before_settle",
             facts: {
+                windowId: currentWindowId(ctx),
                 get queued() { return event.context.pendingMessages.length > 0 || ctx.hasPendingMessages(); },
                 get enabled() { return options.isEnabled(); },
                 get automaticResetEnabled() { return options.budget.automaticResetEnabled(ctx); },
-                get aborted() { return event.outcome === "aborted" || ctx.signal?.aborted === true; },
+                aborted: event.outcome === "aborted" || ctx.signal?.aborted === true,
+                failed: event.outcome === "error",
             },
         });
         control = decision.state;
-        if (decision.effect !== "recover-overflow")
+        if (decision.effect !== "commit-boundary" && decision.effect !== "recover-overflow")
             return undefined;
-        return resetBoundaryResult(event.entries, ctx);
+        return await resetBoundaryResult(event.entries, ctx);
     });
     pi.on("session_before_compact", (event, ctx) => {
         if (!sessionActive)
@@ -153,29 +180,30 @@ export function registerResetLifecycle(pi, options) {
             if (event.reason === "manual") {
                 ctx.ui.notify("pi-context: /compact is disabled while context windows are active; use /wipe-memory to start a fresh window.", "warning");
             }
-            // Native compaction is cancelled here. Threshold resets are decided solely from
-            // completed-turn usage at turn_end, never from canonical pre-request history.
             return { cancel: true };
         }
         return undefined;
     });
     pi.on("agent_end", (_event, ctx) => {
         if (ctx.signal?.aborted)
-            clear();
+            control = reduceResetControl(control, { type: "abort" }).state;
     });
     pi.on("agent_settled", () => {
-        // A failed recovery chain is bounded to one reset/retry. Once Pi settles, a later
-        // user prompt starts a new chain; successful continuations clear this earlier.
         control = reduceResetControl(control, { type: "settled" }).state;
     });
-    pi.on("session_start", () => { clear(); sessionActive = true; });
-    pi.on("session_tree", clear);
-    pi.on("session_shutdown", () => { clear(); options.budget.clear(); sessionActive = false; });
+    pi.on("session_start", () => { lifecycleGeneration++; clear(); sessionActive = true; });
+    pi.on("session_tree", () => { lifecycleGeneration++; clear(); });
+    pi.on("session_shutdown", () => { lifecycleGeneration++; clear(); options.budget.clear(); sessionActive = false; });
     return {
-        request() {
-            const decision = reduceResetControl(control, { type: "request" });
+        closeOut(windowId, source) {
+            const decision = reduceResetControl(control, { type: "close_out", windowId, source });
+            control = decision.state;
+            return decision.effect;
+        },
+        request(windowId) {
+            const decision = reduceResetControl(control, { type: "tool_request", windowId });
             control = decision.state;
-            return decision.effect === "already-requested" ? "rollover_already_pending" : "rollover_requested";
+            return decision.effect === "already-pending" ? "rollover_already_pending" : "rollover_requested";
         },
         clear,
     };

package/dist/src/context/runtime.d.ts

@@ -0,0 +1,3 @@
+import { type ExtensionAPI, type SettingsManager } from "@earendil-works/pi-coding-agent";
+/** Register the context-window runtime and its context-owned commands/tools. */
+export declare function registerContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void;

package/dist/src/context/runtime.js

@@ -2,10 +2,11 @@ import { getCurrentSystemMessage, Type } from "@earendil-works/pi-ai";
 import { VERSION, defineTool } from "@earendil-works/pi-coding-agent";
 import { registerBudget } from "./budget.js";
 import { output } from "../tool-output.js";
-import { migrateLegacyHomes } from "../notes/paths.js";
-import { currentReset, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.js";
+import { migrateLegacyHomes } from "../pi/notes/adapter.js";
+import { currentReset, currentWindowId, isCheckpointBackedReset, isWindowBoot, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
-import { buildResetDrafts, persistManualReset, resetTailCommitted } from "./reset-artifacts.js";
+import { buildResetDrafts, resetTailCommitted } from "./reset-artifacts.js";
+import { BOOT_TYPE, WARNING_CONTENT, WARNING_TYPE } from "../protocol.js";
 import { ensureBoot } from "./boot.js";
 // The bundle captures its identity; direct source loads must not claim a built hash.
 const buildLabel = typeof __PI_CONTEXT_BUILD__ === "undefined"
@@ -17,6 +18,7 @@ function branchHasWindowMarker(ctx, fromId) {
 /** Register the context-window runtime and its context-owned commands/tools. */
 export function registerContext(pi, settingsManager) {
     let enabled = true;
+    let lifecycleGeneration = 0;
     let missingBootNotice;
     const incompleteNotesNotified = new Set();
     const pendingResetNotices = new Set();
@@ -30,7 +32,7 @@ export function registerContext(pi, settingsManager) {
         const branch = ctx.sessionManager.getBranch();
         for (const windowId of pendingResetNotices) {
             const marker = branch.find((entry) => isWindowMarker(entry) && entry.data.windowId === windowId);
-            if (!marker || !resetTailCommitted(ctx, marker.id, windowId))
+            if (!marker || !isCheckpointBackedReset(ctx, marker) || !resetTailCommitted(ctx, marker.id, windowId))
                 continue;
             pendingResetNotices.delete(windowId);
             ctx.ui.notify(`pi-context: memory cleared · ${windowId}`, "info");
@@ -51,19 +53,25 @@ export function registerContext(pi, settingsManager) {
     const migrationWarning = migrateLegacyHomes();
     if (migrationWarning)
         console.warn(`pi-context: ${migrationWarning}`);
-    const budget = registerBudget(pi, () => enabled, settingsManager);
-    pi.on("session_start", (_event, ctx) => {
+    const budget = registerBudget(pi, () => enabled, settingsManager, (windowId) => resets.closeOut(windowId, "automatic"));
+    pi.on("session_start", async (_event, ctx) => {
+        const generation = ++lifecycleGeneration;
         if (!enabled)
             return;
         missingBootNotice = undefined;
         pendingResetNotices.clear();
-        ensureBoot(pi, ctx, notifyIncompleteNotes);
+        await ensureBoot(pi, ctx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
     });
-    pi.on("session_tree", (_event, ctx) => {
+    pi.on("session_tree", async (_event, ctx) => {
+        const generation = ++lifecycleGeneration;
         missingBootNotice = undefined;
         pendingResetNotices.clear();
         if (enabled)
-            ensureBoot(pi, ctx, notifyIncompleteNotes);
+            await ensureBoot(pi, ctx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
+    });
+    pi.on("session_shutdown", () => {
+        lifecycleGeneration++;
+        pendingResetNotices.clear();
     });
     // Pi's branch summarizer receives raw entries and bypasses context_with_system. Do not
     // let a summary of a reset branch smuggle erased history back into the destination.
@@ -81,7 +89,12 @@ export function registerContext(pi, settingsManager) {
         const reset = currentReset(ctx);
         const windowId = reset?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
         try {
-            return { messages: reset ? projectWindow(event.messages, windowId) : projectRootWindow(event.messages, windowId) };
+            if (reset) {
+                if (!event.messages.some((message) => isWindowBoot(message, windowId)))
+                    throw new Error(`Missing boot for context window ${windowId}`);
+                return { messages: isCheckpointBackedReset(ctx, reset) ? event.messages : projectWindow(event.messages, windowId) };
+            }
+            return { messages: projectRootWindow(event.messages, windowId) };
         }
         catch (error) {
             if (missingBootNotice !== windowId) {
@@ -100,10 +113,13 @@ export function registerContext(pi, settingsManager) {
             const arg = args.trim().toLowerCase();
             if (arg === "on") {
                 enabled = true;
-                ensureBoot(pi, cmdCtx, notifyIncompleteNotes);
+                const generation = ++lifecycleGeneration;
+                await ensureBoot(pi, cmdCtx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
             }
             else if (arg === "off") {
                 enabled = false;
+                lifecycleGeneration++;
+                pendingResetNotices.clear();
                 budget.clear();
                 resets.clear();
             }
@@ -115,17 +131,28 @@ export function registerContext(pi, settingsManager) {
         },
     });
     pi.registerCommand("wipe-memory", {
-        description: "Persist a fresh context window without calling the model",
+        description: "Ask the agent to close out its notes, then start a fresh context window",
         handler: async (_args, cmdCtx) => {
             if (!enabled) {
                 cmdCtx.ui.notify("pi-context: /wipe-memory requires /pi-context on.", "error");
                 return;
             }
+            const requestedWindowId = currentWindowId(cmdCtx);
             await cmdCtx.waitForIdle();
-            if (!enabled)
+            if (!enabled || currentWindowId(cmdCtx) !== requestedWindowId)
+                return;
+            const armed = resets.closeOut(requestedWindowId, "manual");
+            if (armed === "already-pending")
                 return;
-            resets.clear();
-            notifyCommittedResets(cmdCtx, persistManualReset(pi, cmdCtx, notifyIncompleteNotes));
+            try {
+                pi.sendMessage({ customType: WARNING_TYPE, content: WARNING_CONTENT, display: false }, { triggerTurn: true });
+            }
+            catch (error) {
+                resets.clear();
+                cmdCtx.ui.notify(`pi-context: could not start manual close-out (${String(error)}).`, "error");
+                return;
+            }
+            await cmdCtx.waitForIdle();
         },
     });
     pi.registerTool(defineTool({
@@ -133,18 +160,23 @@ export function registerContext(pi, settingsManager) {
         label: "Wipe memory",
         description: "Wipe your in-context memory and start a fresh context window. Your session, notes, and history survive.",
         parameters: Type.Object({}, { additionalProperties: false }),
-        async execute() {
+        async execute(_id, _params, _signal, _update, ctx) {
             if (!enabled)
                 return output({ error: "pi-context is off (/pi-context on to enable)" });
-            return output({ status: resets.request() }, undefined, true);
+            return output({ status: resets.request(currentWindowId(ctx)) }, undefined, true);
         },
     }));
     const resets = registerResetLifecycle(pi, {
         isEnabled: () => enabled,
-        buildReset: (ctx) => {
-            const drafts = buildResetDrafts(ctx, notifyIncompleteNotes);
-            pendingResetNotices.add(drafts[1].details.windowId);
-            return drafts;
+        buildReset: (ctx, isCurrent) => buildResetDrafts(ctx, notifyIncompleteNotes, isCurrent),
+        getLifecycleGeneration: () => lifecycleGeneration,
+        onResetReady: (_ctx, drafts) => {
+            const boot = drafts.find((draft) => draft.type === "custom_message" && draft.customType === BOOT_TYPE);
+            if (boot?.type === "custom_message" && boot.details && typeof boot.details === "object") {
+                const windowId = boot.details.windowId;
+                if (typeof windowId === "string")
+                    pendingResetNotices.add(windowId);
+            }
         },
         budget,
     });

package/dist/src/context/thresholds.d.ts

@@ -0,0 +1,33 @@
+import { SettingsManager, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type PiContextSettings } from "../settings.js";
+export type ResolvedThresholds = {
+    reminder: number;
+    reserve: number;
+    warning: number;
+};
+/**
+ * Pure derivation of the thresholds from Pi's reserve: the reminder fires at reserve
+ * plus the pi-context margin, the warning steer at reserve plus WARNING_RUNWAY_TOKENS.
+ * An invalid margin degrades to the default and reports one warning. Automatic
+ * threshold/overflow handling is represented by reset lifecycle boundary drafts;
+ * no compaction summary is generated.
+ */
+export declare function deriveThresholds(reserveTokens: number, margins: PiContextSettings): {
+    thresholds: ResolvedThresholds;
+    warnings: string[];
+};
+/**
+ * Read the active compaction reserve, enablement, and pi-context margin settings. This
+ * function deliberately has no cache: the budget owner supplies the invocation-scoped
+ * cache so two live piContext instances cannot share mutable policy state.
+ */
+export type ThresholdSettingsResolution = {
+    thresholds: ResolvedThresholds;
+    automatic: boolean;
+    warnings: string[];
+};
+/**
+ * Resolve policy from either the explicitly supplied SDK authority or Pi's default
+ * file-backed settings. The caller owns diagnostics and any lifecycle caching.
+ */
+export declare function readThresholdSettings(ctx: ExtensionContext, settingsManager?: SettingsManager): ThresholdSettingsResolution;

package/dist/src/context/thresholds.js

@@ -23,7 +23,7 @@ export function deriveThresholds(reserveTokens, margins) {
     else {
         const parsed = validMargin(margins.reminderMarginTokens);
         if (parsed === undefined) {
-            warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+            warnings.push(`pi-context: ${reminderKey} must be a positive integer; using the default reminder margin.`);
             reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
         }
         else

package/dist/src/dream/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runDreamer, type DreamerSessionFactory } from "./runner.js";
+import { type DreamerSetting } from "./settings.js";
+/** Injection seams used by tests; production uses the defaults. */
+export type DreamDependencies = {
+    sessionFactory?: DreamerSessionFactory;
+    dreamerSettings?: (cwd?: string) => DreamerSetting;
+    runDreamer?: typeof runDreamer;
+};
+export declare function main(argv?: string[], deps?: DreamDependencies): Promise<number>;

package/dist/src/dream/cli.js

@@ -8,7 +8,7 @@ import { loadPlaybook, runDreamer } from "./runner.js";
 import { gitCommit } from "./git.js";
 import { readDreamerSettings } from "./settings.js";
 import { doctor } from "./doctor.js";
-import { notesRoot } from "../notes/paths.js";
+import { notesRoot } from "../pi/notes/adapter.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force" || a === "--help")

package/dist/src/dream/doctor.d.ts

@@ -0,0 +1,2 @@
+/** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
+export declare function doctor(home: string): string[];

package/dist/src/dream/doctor.js

@@ -37,11 +37,15 @@ export function doctor(home) {
                 report(path, `duplicate metadata key ${field[1]}; keep one value`);
             fields.set(field[1], field[2].replace(/^(["'])(.*)\1$/, "$2"));
         }
-        for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, access_count: /^\d+$/ })) {
+        for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, accessCount: /^\d+$/ })) {
             if (!valid.test(fields.get(key) ?? ""))
                 report(path, `missing/invalid ${key}; repair frontmatter`);
         }
-        for (const key of ["created_at", "updated_at", "last_accessed"]) {
+        for (const [legacy, current] of [["created_at", "createdAt"], ["updated_at", "updatedAt"], ["last_accessed", "lastAccessed"], ["access_count", "accessCount"], ["source_window", "sourceWindow"], ["recurrence_count", "recurrenceCount"], ["recurrence_windows", "recurrenceWindows"]]) {
+            if (fields.has(legacy))
+                report(path, `legacy metadata key ${legacy}; manually migrate to ${current}`);
+        }
+        for (const key of ["createdAt", "updatedAt", "lastAccessed"]) {
             const value = fields.get(key);
             if (!value || !Number.isFinite(Date.parse(value)))
                 report(path, `missing/invalid ${key}; use an ISO timestamp`);

package/dist/src/dream/gates.d.ts

@@ -0,0 +1,10 @@
+export type GateResult = {
+    ok: boolean;
+    reason: string;
+};
+/**
+ * The scheduler reads the last-run sidecar, not the lock: the lock's lifetime says
+ * nothing about when the last dream ran, while the sidecar records exactly that.
+ */
+export declare function timeGate(stampPath: string, minHours: number, now?: number): GateResult;
+export declare function materialGate(home: string, sinceMtime: number, minSessions: number): GateResult;

package/dist/src/dream/git.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Outcome of one audit commit. `ok: true` always carries a real `commit` snapshot;
+ * `empty: true` only means no files changed (an empty baseline commit or no commit was
+ * needed). `ok: false` means the audit layer could not guarantee a snapshot.
+ */
+export type AuditResult = {
+    ok: true;
+    commit: string;
+    empty: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Git audit layer for a dream run: one commit before (baseline) and one after (dream),
+ * so the human gate reviews `git show` instead of trusting a report, and rollback is
+ * `git revert`. The caller decides how loud a failure is; this function only reports it.
+ * A clean tree on an established repository commits nothing; a repository with no HEAD
+ * gets an empty baseline commit, because an audit run with no snapshot is not a success.
+ */
+export declare function gitCommit(home: string, message: string): AuditResult;

package/dist/src/dream/lock.d.ts

@@ -0,0 +1,31 @@
+export type LockState = {
+    path: string;
+    held: boolean;
+    reason?: string;
+    startedAt: number;
+    /** mtime of the last-run sidecar before this run took the lock; failLock restores it. */
+    priorStampMtime?: number;
+    /** Random identity written into the lock file; cleanup only removes the lock it wrote. */
+    token?: string;
+};
+/**
+ * The scheduler's last-run timestamp lives in a sidecar beside the lock, never in the
+ * lock file itself: acquiring, releasing or cleaning up the lock touches only the PID
+ * marker, so lock lifecycle does not destroy the timestamp the time gate reads.
+ */
+export declare function lastRunPath(lockPath: string): string;
+/**
+ * Acquire the dream lock with Git-style exclusive existence locking: one O_CREAT|O_EXCL
+ * creation. An existing path refuses acquisition regardless of its contents, PID, or age,
+ * and is never read for permission, replaced, or removed. There is no automatic stale
+ * recovery; a crash-left lock is human cleanup after confirming no dream is running.
+ */
+export declare function acquireLock(path: string): LockState;
+/** Release only the lock this run acquired. Idempotent: repeated cleanup does nothing. */
+export declare function releaseLock(lock: LockState): void;
+/**
+ * A failed run must not advance the scheduler: restore the previous timestamp, or remove
+ * the one this run wrote when there was none. Only this run's own marker is removed, and
+ * the state is marked released so a later cleanup attempt is harmless.
+ */
+export declare function failLock(lock: LockState): void;

package/dist/src/dream/runner.d.ts

@@ -0,0 +1,30 @@
+import { type AgentSession, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+export type DreamWrite = {
+    tool: "write" | "edit";
+    path: string;
+};
+export type DreamResult = {
+    report: string;
+    writes: DreamWrite[];
+    error?: string;
+};
+export type DreamerSession = Pick<AgentSession, "prompt" | "subscribe" | "dispose">;
+export type DreamerSessionFactory = (options: {
+    cwd: string;
+    modelPattern?: string;
+    tools: string[];
+}) => Promise<DreamerSession>;
+export declare const DREAMER_TOOLS: string[];
+/** The only custom definitions in the dream session replace the two built-ins with jailed versions. */
+export declare function dreamerWriteToolDefinitions(notesHome: string): ToolDefinition<any, any, any>[];
+export declare const defaultDreamerSessionFactory: DreamerSessionFactory;
+/**
+ * Run one dream turn. A dreamer failure is returned as `error` together with the partial
+ * writes observed so far, so the caller can record partial state instead of losing it;
+ * only a failure to even start the session throws.
+ */
+export declare function runDreamer(playbook: string, cwd: string, options?: {
+    modelPattern?: string;
+    sessionFactory?: DreamerSessionFactory;
+}): Promise<DreamResult>;
+export declare function loadPlaybook(path: string): string;