@ouro.bot/cli 0.1.0-alpha.109 → 0.1.0-alpha.110

package/changelog.json

@@ -1,6 +1,13 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.110",
+      "changes": [
+        "Pi-style capability salvage now lands fully inside the active-work-first architecture: coding lanes inherit a live world-state checkpoint, session recall stays evidence-based, and no parallel session-orientation self-model remains.",
+        "Repeated no-progress polling is now blocked across active-work, coding, and session status surfaces, while coding checkpoints/artifacts persist cleanly enough for the same agent to resume real work instead of narrating around it."
+      ]
+    },
     {
       "version": "0.1.0-alpha.109",
       "changes": [

package/dist/heart/active-work.js

@@ -39,6 +39,12 @@ function hasSharedObligationPressure(input) {
 function formatCodingLaneLabel(session) {
     return `${session.runner} ${session.id}`;
 }
+function compactCodingCheckpoint(session) {
+    const checkpoint = session.checkpoint?.replace(/\s+/g, " ").trim();
+    if (!checkpoint)
+        return "";
+    return checkpoint.length <= 80 ? checkpoint : `${checkpoint.slice(0, 77)}...`;
+}
 function describeCodingSessionScope(session, currentSession) {
     if (!session.originSession)
         return "";
@@ -159,6 +165,12 @@ function formatActiveLane(frame, obligation) {
     }
     return null;
 }
+function formatCodingArtifact(session) {
+    const artifactPath = session?.artifactPath?.trim();
+    if (artifactPath)
+        return artifactPath;
+    return session ? "no PR or merge artifact yet" : null;
+}
 function formatCurrentArtifact(frame, obligation) {
     if (obligation?.currentArtifact?.trim()) {
         return obligation.currentArtifact.trim();
@@ -166,8 +178,9 @@ function formatCurrentArtifact(frame, obligation) {
     if (obligation?.currentSurface?.kind === "merge" && obligation.currentSurface.label.trim()) {
         return obligation.currentSurface.label.trim();
     }
-    if ((frame.codingSessions ?? []).length > 0) {
-        return "no PR or merge artifact yet";
+    const liveCodingArtifact = formatCodingArtifact(frame.codingSessions?.[0]);
+    if (liveCodingArtifact) {
+        return liveCodingArtifact;
     }
     if (obligation) {
         return "no artifact yet";
@@ -232,8 +245,9 @@ function formatOtherSessionArtifact(obligation, codingSession) {
     if (obligation?.currentSurface?.kind === "merge" && obligation.currentSurface.label.trim()) {
         return obligation.currentSurface.label.trim();
     }
-    if (codingSession)
-        return "no PR or merge artifact yet";
+    const codingArtifact = formatCodingArtifact(codingSession);
+    if (codingArtifact)
+        return codingArtifact;
     return obligation ? "no artifact yet" : "no explicit artifact yet";
 }
 function formatOtherSessionNextAction(obligation, codingSession) {
@@ -278,7 +292,7 @@ function formatOtherActiveSessionSummaries(frame, nowMs = Date.now()) {
         .sort((left, right) => codingSessionTimestampMs(right) - codingSessionTimestampMs(left))
         .map((session) => ({
         timestampMs: codingSessionTimestampMs(session),
-        line: formatOtherSessionLine("another session", session.status, formatCodingLaneLabel(session), "no PR or merge artifact yet", formatOtherSessionNextAction(null, session)),
+        line: formatOtherSessionLine("another session", session.status, formatCodingLaneLabel(session), formatCodingArtifact(session), formatOtherSessionNextAction(null, session)),
     }));
     for (const session of frame.otherCodingSessions ?? []) {
         if (!session.originSession)
@@ -533,7 +547,8 @@ function formatActiveWorkFrame(frame) {
         lines.push("");
         lines.push("## live coding work");
         for (const session of frame.codingSessions) {
-            lines.push(`- [${session.status}] ${formatCodingLaneLabel(session)}${describeCodingSessionScope(session, frame.currentSession)}`);
+            const checkpoint = compactCodingCheckpoint(session);
+            lines.push(`- [${session.status}] ${formatCodingLaneLabel(session)}${describeCodingSessionScope(session, frame.currentSession)}${checkpoint ? `: ${checkpoint}` : ""}`);
         }
     }
     if (otherActiveSessions.length > 0) {

package/dist/heart/core.js

@@ -31,6 +31,7 @@ const pending_1 = require("../mind/pending");
 const identity_2 = require("./identity");
 const socket_client_1 = require("./daemon/socket-client");
 const obligations_1 = require("./obligations");
+const tool_loop_1 = require("./tool-loop");
 let _providerRuntime = null;
 function getProviderRuntimeFingerprint() {
     const provider = (0, identity_1.loadAgentConfig)().provider;
@@ -490,6 +491,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     let sawQuerySession = false;
     let sawBridgeManage = false;
     let sawExternalStateQuery = false;
+    const toolLoopState = (0, tool_loop_1.createToolLoopState)();
     // Prevent MaxListenersExceeded warning — each iteration adds a listener
     try {
         require("events").setMaxListeners(50, signal);
@@ -503,6 +505,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             ...options.toolContext,
             supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
             setReasoningEffort: (level) => { currentReasoningEffort = level; },
+            activeWorkFrame: options?.activeWorkFrame,
         }
         : undefined;
     // Rebase provider-owned turn state from canonical messages at user-turn start.
@@ -804,6 +807,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     if (isExternalStateQuery(tc.name, args))
                         sawExternalStateQuery = true;
                     const argSummary = (0, tools_1.summarizeArgs)(tc.name, args);
+                    const toolLoop = (0, tool_loop_1.detectToolLoop)(toolLoopState, tc.name, args);
+                    if (toolLoop.stuck) {
+                        const rejection = `loop guard: ${toolLoop.message}`;
+                        callbacks.onToolStart(tc.name, args);
+                        callbacks.onToolEnd(tc.name, argSummary, false);
+                        messages.push({ role: "tool", tool_call_id: tc.id, content: rejection });
+                        providerRuntime.appendToolOutput(tc.id, rejection);
+                        continue;
+                    }
                     // Confirmation check for mutate tools
                     if ((0, tools_1.isConfirmationRequired)(tc.name) && !options?.skipConfirmation) {
                         let decision = "denied";
@@ -831,6 +843,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         toolResult = `error: ${e}`;
                         success = false;
                     }
+                    (0, tool_loop_1.recordToolOutcome)(toolLoopState, tc.name, args, toolResult, success);
                     callbacks.onToolEnd(tc.name, argSummary, success);
                     messages.push({ role: "tool", tool_call_id: tc.id, content: toolResult });
                     providerRuntime.appendToolOutput(tc.id, toolResult);

package/dist/heart/session-recall.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recallSession = recallSession;
+exports.searchSessionTranscript = searchSessionTranscript;
 const fs = __importStar(require("fs"));
 const runtime_1 = require("../nerves/runtime");
 function normalizeContent(content) {
@@ -48,6 +49,19 @@ function normalizeContent(content) {
         .filter((text) => text.length > 0)
         .join("");
 }
+function normalizeSessionMessages(messages) {
+    if (!Array.isArray(messages))
+        return [];
+    return messages
+        .map((message) => {
+        const record = message && typeof message === "object" ? message : {};
+        return {
+            role: typeof record.role === "string" ? record.role : "",
+            content: normalizeContent(record.content),
+        };
+    })
+        .filter((message) => message.role !== "system" && message.content.length > 0);
+}
 function buildSummaryInstruction(friendId, channel, trustLevel) {
     if (friendId === "self" && channel === "inner") {
         return "summarize this session transcript fully and transparently. this is my own inner dialog — include all details, decisions, and reasoning.";
@@ -70,6 +84,57 @@ function buildSnapshot(summary, tailMessages) {
     }
     return lines.join("\n");
 }
+function buildSearchSnapshot(query, messages, includeLatestTurn = true) {
+    const lines = [`history query: "${clip(query, 120)}"`];
+    if (!includeLatestTurn) {
+        return lines.join("\n");
+    }
+    const latestUser = [...messages].reverse().find((message) => message.role === "user")?.content;
+    const latestAssistant = [...messages].reverse().find((message) => message.role === "assistant")?.content;
+    if (latestUser) {
+        lines.push(`latest user: ${clip(latestUser)}`);
+    }
+    if (latestAssistant) {
+        lines.push(`latest assistant: ${clip(latestAssistant)}`);
+    }
+    return lines.join("\n");
+}
+function buildSearchExcerpts(messages, query, maxMatches) {
+    const normalizedQuery = query.trim().toLowerCase();
+    if (!normalizedQuery)
+        return [];
+    const candidates = [];
+    let lastMatchIndex = -2;
+    for (let i = 0; i < messages.length; i++) {
+        if (!messages[i].content.toLowerCase().includes(normalizedQuery))
+            continue;
+        if (i <= lastMatchIndex + 1)
+            continue;
+        lastMatchIndex = i;
+        const start = Math.max(0, i - 1);
+        const end = Math.min(messages.length, i + 2);
+        const excerpt = messages
+            .slice(start, end)
+            .map((message) => `[${message.role}] ${clip(message.content, 200)}`)
+            .join("\n");
+        const score = messages
+            .slice(start, end)
+            .filter((message) => message.content.toLowerCase().includes(normalizedQuery))
+            .length;
+        candidates.push({ excerpt, score, index: i });
+    }
+    const seen = new Set();
+    return candidates
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .filter((candidate) => {
+        if (seen.has(candidate.excerpt))
+            return false;
+        seen.add(candidate.excerpt);
+        return true;
+    })
+        .slice(0, maxMatches)
+        .map((candidate) => candidate.excerpt);
+}
 async function recallSession(options) {
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
@@ -90,13 +155,7 @@ async function recallSession(options) {
         return { kind: "missing" };
     }
     const parsed = JSON.parse(raw);
-    const tailMessages = (parsed.messages ?? [])
-        .map((message) => ({
-        role: typeof message.role === "string" ? message.role : "",
-        content: normalizeContent(message.content),
-    }))
-        .filter((message) => message.role !== "system" && message.content.length > 0)
-        .slice(-options.messageCount);
+    const tailMessages = normalizeSessionMessages(parsed.messages).slice(-options.messageCount);
     if (tailMessages.length === 0) {
         return { kind: "empty" };
     }
@@ -114,3 +173,44 @@ async function recallSession(options) {
         tailMessages,
     };
 }
+async function searchSessionTranscript(options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.session_search",
+        message: "searching session transcript",
+        meta: {
+            friendId: options.friendId,
+            channel: options.channel,
+            key: options.key,
+            query: options.query,
+            maxMatches: options.maxMatches ?? 5,
+        },
+    });
+    let raw;
+    try {
+        raw = fs.readFileSync(options.sessionPath, "utf-8");
+    }
+    catch {
+        return { kind: "missing" };
+    }
+    const parsed = JSON.parse(raw);
+    const messages = normalizeSessionMessages(parsed.messages);
+    if (messages.length === 0) {
+        return { kind: "empty" };
+    }
+    const query = options.query.trim();
+    const matches = buildSearchExcerpts(messages, query, options.maxMatches ?? 5);
+    if (matches.length === 0) {
+        return {
+            kind: "no_match",
+            query,
+            snapshot: buildSearchSnapshot(query, messages),
+        };
+    }
+    return {
+        kind: "ok",
+        query,
+        snapshot: buildSearchSnapshot(query, messages, false),
+        matches,
+    };
+}

package/dist/heart/tool-loop.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLOBAL_CIRCUIT_BREAKER_LIMIT = exports.PING_PONG_WINDOW = exports.GENERIC_REPEAT_LIMIT = exports.POLL_NO_PROGRESS_LIMIT = exports.TOOL_LOOP_HISTORY_LIMIT = void 0;
+exports.createToolLoopState = createToolLoopState;
+exports.recordToolOutcome = recordToolOutcome;
+exports.detectToolLoop = detectToolLoop;
+const crypto = __importStar(require("crypto"));
+const runtime_1 = require("../nerves/runtime");
+exports.TOOL_LOOP_HISTORY_LIMIT = 30;
+exports.POLL_NO_PROGRESS_LIMIT = 3;
+exports.GENERIC_REPEAT_LIMIT = 4;
+exports.PING_PONG_WINDOW = 6;
+exports.GLOBAL_CIRCUIT_BREAKER_LIMIT = 24;
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    /* v8 ignore next -- stableStringify currently receives only objects/strings from normalized loop inputs @preserve */
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
+function digest(value) {
+    return crypto.createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+function normalizeArgs(toolName, args) {
+    if (toolName === "query_active_work") {
+        return { toolName };
+    }
+    if (toolName === "coding_status" || toolName === "coding_tail") {
+        return {
+            toolName,
+            sessionId: args.sessionId ?? "",
+        };
+    }
+    if (toolName === "query_session") {
+        return {
+            toolName,
+            mode: args.mode ?? "",
+            friendId: args.friendId ?? "",
+            channel: args.channel ?? "",
+            key: args.key ?? "",
+            query: args.query ?? "",
+        };
+    }
+    return {
+        toolName,
+        args,
+    };
+}
+function normalizeOutcome(result, success) {
+    return {
+        success,
+        result: result.replace(/\s+/g, " ").trim(),
+    };
+}
+function isKnownPollTool(toolName, args) {
+    return toolName === "query_active_work"
+        || toolName === "coding_status"
+        || toolName === "coding_tail"
+        || (toolName === "query_session" && (args.mode ?? "").trim() === "status");
+}
+function emitDetection(detector, toolName, count, message, pairedToolName) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "engine",
+        event: "engine.tool_loop_detected",
+        message: "tool loop guard detected repeated non-progress work",
+        meta: {
+            detector,
+            toolName,
+            count,
+            pairedToolName: pairedToolName ?? null,
+        },
+    });
+    return {
+        stuck: true,
+        detector,
+        count,
+        message,
+        pairedToolName,
+    };
+}
+function countTrailingRepeats(history, toolName, callHash) {
+    let count = 0;
+    let outcomeHash;
+    for (let index = history.length - 1; index >= 0; index--) {
+        const record = history[index];
+        if (record.toolName !== toolName || record.callHash !== callHash) {
+            break;
+        }
+        if (!outcomeHash) {
+            outcomeHash = record.outcomeHash;
+        }
+        if (record.outcomeHash !== outcomeHash) {
+            break;
+        }
+        count += 1;
+    }
+    return { count, outcomeHash };
+}
+function detectPingPong(history, toolName, callHash) {
+    if (history.length < exports.PING_PONG_WINDOW) {
+        return { stuck: false };
+    }
+    const recent = history.slice(-exports.PING_PONG_WINDOW);
+    const first = recent[0];
+    const second = recent[1];
+    if (!first.isKnownPoll || !second.isKnownPoll) {
+        return { stuck: false };
+    }
+    if (first.toolName === second.toolName && first.callHash === second.callHash) {
+        return { stuck: false };
+    }
+    for (let index = 0; index < recent.length; index++) {
+        const expected = index % 2 === 0 ? first : second;
+        const actual = recent[index];
+        if (actual.toolName !== expected.toolName
+            || actual.callHash !== expected.callHash
+            || actual.outcomeHash !== expected.outcomeHash) {
+            return { stuck: false };
+        }
+    }
+    const matchesPair = (toolName === first.toolName && callHash === first.callHash)
+        || (toolName === second.toolName && callHash === second.callHash);
+    if (!matchesPair) {
+        return { stuck: false };
+    }
+    const pairedToolName = toolName === first.toolName ? second.toolName : first.toolName;
+    return emitDetection("ping_pong", toolName, exports.PING_PONG_WINDOW, `repeated ${first.toolName}/${second.toolName} polling is not changing. stop cycling between status checks and either act on the current state, change approach, or answer truthfully with what is known.`, pairedToolName);
+}
+function createToolLoopState() {
+    return { history: [] };
+}
+function recordToolOutcome(state, toolName, args, result, success) {
+    state.history.push({
+        toolName,
+        callHash: digest(normalizeArgs(toolName, args)),
+        outcomeHash: digest(normalizeOutcome(result, success)),
+        isKnownPoll: isKnownPollTool(toolName, args),
+    });
+    if (state.history.length > exports.TOOL_LOOP_HISTORY_LIMIT) {
+        state.history.splice(0, state.history.length - exports.TOOL_LOOP_HISTORY_LIMIT);
+    }
+}
+function detectToolLoop(state, toolName, args) {
+    if (state.history.length >= exports.GLOBAL_CIRCUIT_BREAKER_LIMIT) {
+        return emitDetection("global_circuit_breaker", toolName, state.history.length, `this turn has already made ${state.history.length} tool calls. stop thrashing, use the current evidence, and either change approach or answer truthfully with the best grounded status.`);
+    }
+    const callHash = digest(normalizeArgs(toolName, args));
+    const trailing = countTrailingRepeats(state.history, toolName, callHash);
+    if (isKnownPollTool(toolName, args) && trailing.count >= exports.POLL_NO_PROGRESS_LIMIT) {
+        return emitDetection("known_poll_no_progress", toolName, trailing.count, `repeated ${toolName} calls have returned the same state ${trailing.count} times. stop polling and either act on the current state, wait for a meaningful change, or answer truthfully with what is known.`);
+    }
+    if (trailing.count >= exports.GENERIC_REPEAT_LIMIT) {
+        return emitDetection("generic_repeat", toolName, trailing.count, `repeating ${toolName} with the same inputs is not producing new information. change approach, use the evidence already gathered, or answer truthfully with what is known.`);
+    }
+    return detectPingPong(state.history, toolName, callHash);
+}

package/dist/mind/prompt.js

@@ -437,6 +437,7 @@ function memoryFriendToolContractSection() {
 2. \`memory_save\` — When I learn something general - about a project, codebase, system, decision, or anything I might need later that isn't about a specific person - I call \`memory_save\`. When in doubt, I save it.
 3. \`get_friend_note\` — When I need to check what I know about someone who isn't in this conversation - cross-referencing before mentioning someone, or checking context about a person someone else brought up - I call \`get_friend_note\`.
 4. \`memory_search\` — When I need to recall something I learned before - a topic comes up and I want to check what I know - I call \`memory_search\`.
+5. \`query_session\` — When I need grounded session history, especially for ad-hoc questions or older turns beyond my prompt, I call \`query_session\`. Use \`mode=status\` for self/inner progress and \`mode=search\` with a query for older history.
 
 ## what's already in my context
 - My active friend's notes are auto-loaded (I don't need \`get_friend_note\` for the person I'm talking to).

package/dist/repertoire/coding/context-pack.js

@@ -0,0 +1,254 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareCodingContextPack = prepareCodingContextPack;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const active_work_1 = require("../../heart/active-work");
+const identity_1 = require("../../heart/identity");
+const runtime_1 = require("../../nerves/runtime");
+const skills_1 = require("../skills");
+const CONTEXT_FILENAMES = ["AGENTS.md", "CLAUDE.md"];
+function defaultRunCommand(command, args, cwd) {
+    const result = (0, child_process_1.spawnSync)(command, args, {
+        cwd,
+        encoding: "utf-8",
+    });
+    return {
+        status: result.status ?? 1,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function stableContextKey(request) {
+    const payload = JSON.stringify({
+        runner: request.runner,
+        workdir: request.workdir,
+        taskRef: request.taskRef ?? "",
+        parentAgent: request.parentAgent ?? "",
+        obligationId: request.obligationId ?? "",
+        originSession: request.originSession ?? null,
+    });
+    return crypto.createHash("sha1").update(payload).digest("hex").slice(0, 12);
+}
+function collectProjectContextFiles(workdir, deps) {
+    const files = [];
+    const seen = new Set();
+    let current = path.resolve(workdir);
+    const root = path.parse(current).root;
+    while (true) {
+        for (const filename of CONTEXT_FILENAMES) {
+            const candidate = path.join(current, filename);
+            if (!deps.existsSync(candidate) || seen.has(candidate))
+                continue;
+            try {
+                const content = deps.readFileSync(candidate, "utf-8").trim();
+                if (content.length > 0) {
+                    files.unshift({ path: candidate, content });
+                    seen.add(candidate);
+                }
+            }
+            catch {
+                // Best-effort loading only.
+            }
+        }
+        if (current === root)
+            break;
+        current = path.dirname(current);
+    }
+    return files;
+}
+function captureRepoSnapshot(workdir, runCommand) {
+    const repoRoot = runCommand("git", ["rev-parse", "--show-toplevel"], workdir);
+    if (repoRoot.status !== 0) {
+        return {
+            available: false,
+            repoRoot: null,
+            branch: null,
+            head: null,
+            statusLines: [],
+        };
+    }
+    const branch = runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], workdir);
+    const head = runCommand("git", ["rev-parse", "--short", "HEAD"], workdir);
+    const status = runCommand("git", ["status", "--short"], workdir);
+    return {
+        available: true,
+        repoRoot: repoRoot.stdout.trim() || null,
+        branch: branch.status === 0 ? branch.stdout.trim() || null : null,
+        head: head.status === 0 ? head.stdout.trim() || null : null,
+        statusLines: status.status === 0
+            ? status.stdout.split(/\r?\n/).map((line) => line.trimEnd()).filter(Boolean)
+            : [],
+    };
+}
+function formatContextFiles(files) {
+    if (files.length === 0)
+        return "(none found)";
+    return files.map((file) => `### ${file.path}\n${file.content}`).join("\n\n");
+}
+function formatSkills(skills) {
+    return skills.length > 0 ? skills.join(", ") : "(none found)";
+}
+function formatExistingSessions(sessions) {
+    if (sessions.length === 0)
+        return "activeSessions: none";
+    return sessions
+        .map((session) => {
+        return [
+            `- ${session.id}`,
+            `status=${session.status}`,
+            `lastActivityAt=${session.lastActivityAt}`,
+            session.taskRef ? `taskRef=${session.taskRef}` : null,
+            session.checkpoint ? `checkpoint=${session.checkpoint}` : null,
+            session.artifactPath ? `artifact=${session.artifactPath}` : null,
+        ].filter(Boolean).join(" ");
+    })
+        .join("\n");
+}
+function formatOrigin(request) {
+    if (!request.originSession)
+        return "originSession: none";
+    return `originSession: ${request.originSession.channel}/${request.originSession.key} (${request.originSession.friendId})`;
+}
+function buildScopeContent(request, contextFiles, skills, agentName) {
+    return [
+        "# Coding Session Scope",
+        "",
+        "## Request",
+        `runner: ${request.runner}`,
+        `taskRef: ${request.taskRef ?? "unassigned"}`,
+        `parentAgent: ${request.parentAgent ?? agentName}`,
+        `workdir: ${request.workdir}`,
+        formatOrigin(request),
+        `obligationId: ${request.obligationId ?? "none"}`,
+        "",
+        "## Prompt",
+        request.prompt,
+        "",
+        "## Session Contract",
+        "- This is a focused coding lane opened by the parent Ouro agent.",
+        "- Execute the concrete prompt in the supplied workdir directly.",
+        "- Do not switch into planning/doing workflows or approval gates unless the prompt explicitly asks for them.",
+        "- Treat the current prompt, scope file, and live world-state checkpoint in the state file as the authoritative briefing for this lane.",
+        "",
+        "## Project Context Files",
+        formatContextFiles(contextFiles),
+        "",
+        "## Available Bundle Skills",
+        formatSkills(skills),
+    ].join("\n");
+}
+function buildStateContent(request, contextKey, generatedAt, snapshot, existingSessions, agentName, activeWorkFrame) {
+    const gitSection = snapshot.available
+        ? [
+            `repoRoot: ${snapshot.repoRoot ?? "unknown"}`,
+            `branch: ${snapshot.branch ?? "unknown"}`,
+            `head: ${snapshot.head ?? "unknown"}`,
+            "status:",
+            snapshot.statusLines.length > 0 ? snapshot.statusLines.join("\n") : "(clean)",
+        ].join("\n")
+        : "git: unavailable";
+    return [
+        "# Coding Session State",
+        `generatedAt: ${generatedAt}`,
+        `contextKey: ${contextKey}`,
+        `agent: ${request.parentAgent ?? agentName}`,
+        formatOrigin(request),
+        `obligationId: ${request.obligationId ?? "none"}`,
+        "",
+        "## Workspace Snapshot",
+        gitSection,
+        ...(activeWorkFrame ? ["", (0, active_work_1.formatLiveWorldStateCheckpoint)(activeWorkFrame)] : []),
+        "",
+        "## Related Coding Sessions",
+        formatExistingSessions(existingSessions),
+    ].join("\n");
+}
+function relatedSessions(request, existingSessions) {
+    return existingSessions.filter((session) => {
+        return session.runner === request.runner
+            && session.workdir === request.workdir
+            && session.taskRef === request.taskRef;
+    });
+}
+function prepareCodingContextPack(input, deps = {}) {
+    const agentRoot = deps.agentRoot ?? (0, identity_1.getAgentRoot)();
+    const agentName = deps.agentName ?? (0, identity_1.getAgentName)();
+    const nowIso = deps.nowIso ?? (() => new Date().toISOString());
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const readFileSync = deps.readFileSync ?? fs.readFileSync;
+    const writeFileSync = deps.writeFileSync ?? fs.writeFileSync;
+    const mkdirSync = deps.mkdirSync ?? fs.mkdirSync;
+    const listAvailableSkills = deps.listSkills ?? skills_1.listSkills;
+    const runCommand = deps.runCommand ?? defaultRunCommand;
+    const contextKey = stableContextKey(input.request);
+    const contextDir = path.join(agentRoot, "state", "coding", "context");
+    const scopeFile = path.join(contextDir, `${contextKey}-scope.md`);
+    const stateFile = path.join(contextDir, `${contextKey}-state.md`);
+    const contextFiles = collectProjectContextFiles(input.request.workdir, { existsSync, readFileSync });
+    const skills = listAvailableSkills();
+    const existingSessions = relatedSessions(input.request, input.existingSessions ?? []);
+    const snapshot = captureRepoSnapshot(input.request.workdir, runCommand);
+    const generatedAt = nowIso();
+    const scopeContent = buildScopeContent(input.request, contextFiles, skills, agentName);
+    const stateContent = buildStateContent(input.request, contextKey, generatedAt, snapshot, existingSessions, agentName, input.activeWorkFrame);
+    mkdirSync(contextDir, { recursive: true });
+    writeFileSync(scopeFile, `${scopeContent}\n`, "utf-8");
+    writeFileSync(stateFile, `${stateContent}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.coding_context_pack_written",
+        message: "prepared coding session context pack",
+        meta: {
+            contextKey,
+            workdir: input.request.workdir,
+            taskRef: input.request.taskRef ?? null,
+            contextFiles: contextFiles.length,
+            skills: skills.length,
+            relatedSessions: existingSessions.length,
+            gitAvailable: snapshot.available,
+        },
+    });
+    return {
+        contextKey,
+        scopeFile,
+        stateFile,
+        scopeContent,
+        stateContent,
+    };
+}

package/dist/repertoire/coding/feedback.js

@@ -131,10 +131,37 @@ function isSafeProgressSnippet(snippet) {
         && !/^parentAgent\b/i.test(normalized));
 }
 function pickUpdateSnippet(update) {
-    return (lastMeaningfulLine(update.text)
+    const checkpoint = update.session.checkpoint?.trim() || null;
+    return (checkpoint
+        ?? lastMeaningfulLine(update.text)
         ?? lastMeaningfulLine(update.session.stderrTail)
         ?? lastMeaningfulLine(update.session.stdoutTail));
 }
+function renderValue(text) {
+    const trimmed = text?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "(empty)";
+}
+function renderPath(text) {
+    return text && text.trim().length > 0 ? text : "(none)";
+}
+function formatCodingTail(session) {
+    const stdout = renderValue(session.stdoutTail);
+    const stderr = renderValue(session.stderrTail);
+    return [
+        `sessionId: ${session.id}`,
+        `runner: ${session.runner}`,
+        `status: ${session.status}`,
+        `checkpoint: ${renderValue(session.checkpoint ?? undefined)}`,
+        `artifactPath: ${renderPath(session.artifactPath)}`,
+        `workdir: ${session.workdir}`,
+        "",
+        "[stdout]",
+        stdout,
+        "",
+        "[stderr]",
+        stderr,
+    ].join("\n");
+}
 function formatUpdateMessage(update) {
     const label = formatSessionLabel(update.session);
     const snippet = pickUpdateSnippet(update);
@@ -233,22 +260,6 @@ async function wakeInnerDialogForObligation(update) {
         });
     }
 }
-function formatCodingTail(session) {
-    const stdout = session.stdoutTail.trim() || "(empty)";
-    const stderr = session.stderrTail.trim() || "(empty)";
-    return [
-        `sessionId: ${session.id}`,
-        `runner: ${session.runner}`,
-        `status: ${session.status}`,
-        `workdir: ${session.workdir}`,
-        "",
-        "[stdout]",
-        stdout,
-        "",
-        "[stderr]",
-        stderr,
-    ].join("\n");
-}
 function attachCodingSessionFeedback(manager, session, target) {
     let lastMessage = "";
     let closed = false;

package/dist/repertoire/coding/manager.js

@@ -50,6 +50,9 @@ function safeAgentName() {
 function defaultStateFilePath(agentName) {
     return path.join((0, identity_1.getAgentRoot)(agentName), "state", "coding", "sessions.json");
 }
+function defaultArtifactDirPath(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "coding", "sessions");
+}
 function isPidAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -63,6 +66,8 @@ function cloneSession(session) {
     return {
         ...session,
         originSession: session.originSession ? { ...session.originSession } : undefined,
+        checkpoint: session.checkpoint ?? null,
+        artifactPath: session.artifactPath,
         stdoutTail: session.stdoutTail,
         stderrTail: session.stderrTail,
         failure: session.failure
@@ -86,6 +91,46 @@ function appendTail(existing, nextChunk, maxLength = 2000) {
     const combined = `${existing}${nextChunk}`;
     return combined.length <= maxLength ? combined : combined.slice(combined.length - maxLength);
 }
+function compactText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function clipText(text, maxLength = 240) {
+    return text.length <= maxLength ? text : `${text.slice(0, maxLength - 3)}...`;
+}
+function latestMeaningfulLine(text) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => compactText(line))
+        .filter(Boolean);
+    if (lines.length === 0)
+        return null;
+    return clipText(lines.at(-1));
+}
+function fallbackCheckpoint(status, code, signal) {
+    switch (status) {
+        case "waiting_input":
+            return "needs input";
+        case "stalled":
+            return "no recent output";
+        case "completed":
+            return "completed";
+        case "failed":
+            if (code !== null)
+                return `exit code ${code}`;
+            if (signal)
+                return `terminated by ${signal}`;
+            return "failed";
+        case "killed":
+            return "terminated by parent agent";
+        default:
+            return null;
+    }
+}
+function deriveCheckpoint(session) {
+    return (latestMeaningfulLine(session.stderrTail)
+        ?? latestMeaningfulLine(session.stdoutTail)
+        ?? fallbackCheckpoint(session.status, session.lastExitCode, session.lastSignal));
+}
 function isSpawnCodingResult(value) {
     return typeof value === "object" && value !== null && "process" in value;
 }
@@ -123,6 +168,7 @@ class CodingSessionManager {
     maxRestarts;
     defaultStallThresholdMs;
     stateFilePath;
+    artifactDirPath;
     existsSync;
     readFileSync;
     writeFileSync;
@@ -142,6 +188,8 @@ class CodingSessionManager {
         this.pidAlive = options.pidAlive ?? isPidAlive;
         this.agentName = options.agentName ?? safeAgentName();
         this.stateFilePath = options.stateFilePath ?? defaultStateFilePath(this.agentName);
+        this.artifactDirPath = options.artifactDirPath
+            ?? (options.stateFilePath ? path.dirname(options.stateFilePath) : defaultArtifactDirPath(this.agentName));
         this.loadPersistedState();
     }
     async spawnSession(request) {
@@ -162,6 +210,8 @@ class CodingSessionManager {
             obligationId: normalizedRequest.obligationId,
             scopeFile: normalizedRequest.scopeFile,
             stateFile: normalizedRequest.stateFile,
+            checkpoint: null,
+            artifactPath: this.artifactPathFor(id),
             status: "spawning",
             stdoutTail: "",
             stderrTail: "",
@@ -248,6 +298,7 @@ class CodingSessionManager {
         record.process.kill("SIGTERM");
         record.process = null;
         record.session.status = "killed";
+        record.session.checkpoint = "terminated by parent agent";
         record.session.endedAt = this.nowIso();
         (0, runtime_1.emitNervesEvent)({
             component: "repertoire",
@@ -270,6 +321,7 @@ class CodingSessionManager {
                 continue;
             stalled += 1;
             record.session.status = "stalled";
+            record.session.checkpoint = deriveCheckpoint(record.session);
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
                 component: "repertoire",
@@ -295,6 +347,7 @@ class CodingSessionManager {
             record.process = null;
             if (record.session.status === "running" || record.session.status === "spawning") {
                 record.session.status = "killed";
+                record.session.checkpoint = "terminated during manager shutdown";
                 record.session.endedAt = this.nowIso();
             }
         }
@@ -339,6 +392,13 @@ class CodingSessionManager {
             record.session.endedAt = this.nowIso();
             updateKind = "completed";
         }
+        const checkpoint = latestMeaningfulLine(text);
+        if (checkpoint) {
+            record.session.checkpoint = checkpoint;
+        }
+        else if (!record.session.checkpoint) {
+            record.session.checkpoint = deriveCheckpoint(record.session);
+        }
         (0, runtime_1.emitNervesEvent)({
             component: "repertoire",
             event: "repertoire.coding_session_output",
@@ -362,12 +422,14 @@ class CodingSessionManager {
         record.session.lastSignal = signal;
         if (record.session.status === "killed" || record.session.status === "completed") {
             record.session.endedAt = this.nowIso();
+            record.session.checkpoint = deriveCheckpoint(record.session);
             this.persistState();
             return;
         }
         if (code === 0) {
             record.session.status = "completed";
             record.session.endedAt = this.nowIso();
+            record.session.checkpoint = deriveCheckpoint(record.session);
             this.persistState();
             this.notifyListeners(record.session.id, { kind: "completed", session: cloneSession(record.session) });
             return;
@@ -379,6 +441,7 @@ class CodingSessionManager {
         record.session.status = "failed";
         record.session.endedAt = this.nowIso();
         record.session.failure = defaultFailureDiagnostics(code, signal, record.command, record.args, record.stdoutTail, record.stderrTail);
+        record.session.checkpoint = deriveCheckpoint(record.session);
         (0, runtime_1.emitNervesEvent)({
             level: "error",
             component: "repertoire",
@@ -404,6 +467,7 @@ class CodingSessionManager {
         record.session.lastActivityAt = this.nowIso();
         record.session.endedAt = null;
         record.session.failure = null;
+        record.session.checkpoint = `restarted after ${reason}`;
         this.attachProcessListeners(record);
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
@@ -498,6 +562,8 @@ class CodingSessionManager {
                 failure: session.failure ?? null,
                 stdoutTail: session.stdoutTail ?? session.failure?.stdoutTail ?? "",
                 stderrTail: session.stderrTail ?? session.failure?.stderrTail ?? "",
+                checkpoint: typeof session.checkpoint === "string" ? session.checkpoint : null,
+                artifactPath: typeof session.artifactPath === "string" ? session.artifactPath : this.artifactPathFor(session.id),
             };
             if (typeof normalizedSession.pid === "number") {
                 const alive = this.pidAlive(normalizedSession.pid);
@@ -510,6 +576,7 @@ class CodingSessionManager {
                     normalizedSession.pid = null;
                 }
             }
+            normalizedSession.checkpoint = normalizedSession.checkpoint ?? deriveCheckpoint(normalizedSession);
             this.records.set(normalizedSession.id, {
                 request: normalizedRequest,
                 session: normalizedSession,
@@ -549,6 +616,80 @@ class CodingSessionManager {
                 meta: { path: this.stateFilePath, reason: error instanceof Error ? error.message : String(error) },
             });
         }
+        this.persistArtifacts();
+    }
+    artifactPathFor(sessionId) {
+        return path.join(this.artifactDirPath, `${sessionId}.md`);
+    }
+    renderArtifact(record) {
+        const { request, session } = record;
+        const stdout = session.stdoutTail.trim() || "(empty)";
+        const stderr = session.stderrTail.trim() || "(empty)";
+        const lines = [
+            "# Coding Session Artifact",
+            "",
+            "## Session",
+            `id: ${session.id}`,
+            `runner: ${session.runner}`,
+            `status: ${session.status}`,
+            `taskRef: ${session.taskRef ?? "unassigned"}`,
+            `workdir: ${session.workdir}`,
+            `startedAt: ${session.startedAt}`,
+            `lastActivityAt: ${session.lastActivityAt}`,
+            `endedAt: ${session.endedAt ?? "active"}`,
+            `pid: ${session.pid ?? "none"}`,
+            `restarts: ${session.restartCount}`,
+            `checkpoint: ${session.checkpoint ?? "none"}`,
+            `scopeFile: ${session.scopeFile ?? "none"}`,
+            `stateFile: ${session.stateFile ?? "none"}`,
+            "",
+            "## Request",
+            request.prompt,
+            "",
+            "## Stdout Tail",
+            stdout,
+            "",
+            "## Stderr Tail",
+            stderr,
+        ];
+        if (session.failure) {
+            lines.push("", "## Failure", `command: ${session.failure.command}`, `args: ${session.failure.args.join(" ") || "(none)"}`, `code: ${session.failure.code ?? "null"}`, `signal: ${session.failure.signal ?? "null"}`);
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    persistArtifacts() {
+        try {
+            this.mkdirSync(this.artifactDirPath, { recursive: true });
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "repertoire",
+                event: "repertoire.coding_artifact_persist_error",
+                message: "failed preparing coding artifact directory",
+                meta: { path: this.artifactDirPath, reason: error instanceof Error ? error.message : String(error) },
+            });
+            return;
+        }
+        for (const record of this.records.values()) {
+            try {
+                record.session.artifactPath = record.session.artifactPath ?? this.artifactPathFor(record.session.id);
+                this.writeFileSync(record.session.artifactPath, this.renderArtifact(record), "utf-8");
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.coding_artifact_persist_error",
+                    message: "failed writing coding session artifact",
+                    meta: {
+                        id: record.session.id,
+                        path: record.session.artifactPath ?? this.artifactPathFor(record.session.id),
+                        reason: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+        }
     }
 }
 exports.CodingSessionManager = CodingSessionManager;

package/dist/repertoire/coding/spawner.js

@@ -72,20 +72,32 @@ function buildSpawnEnv(baseEnv, homeDir) {
         PATH: pathEntries.join(path.delimiter),
     };
 }
+function appendFileSection(sections, label, filePath, deps) {
+    if (!filePath || !deps.existsSync(filePath))
+        return;
+    const content = deps.readFileSync(filePath, "utf-8").trim();
+    if (content.length === 0)
+        return;
+    sections.push(`${label} (${filePath}):\n${content}`);
+}
 function buildPrompt(request, deps) {
     const sections = [];
+    sections.push([
+        "Execution contract:",
+        "- You are a subordinate coding session launched by a parent Ouro agent.",
+        "- Execute the concrete request in the supplied workdir directly.",
+        "- Do not switch into planning/doing workflows, approval gates, or repo-management rituals unless the request explicitly asks for them.",
+        "- Treat the request, scope file, and state file as the authoritative briefing for this session.",
+        "- Prefer direct execution and verification over narration.",
+    ].join("\n"));
     sections.push([
         "Coding session metadata:",
         `sessionId: ${request.sessionId ?? "pending"}`,
         `parentAgent: ${request.parentAgent ?? "unknown"}`,
         `taskRef: ${request.taskRef ?? "unassigned"}`,
     ].join("\n"));
-    if (request.stateFile && deps.existsSync(request.stateFile)) {
-        const stateContent = deps.readFileSync(request.stateFile, "utf-8").trim();
-        if (stateContent.length > 0) {
-            sections.push(`State file (${request.stateFile}):\n${stateContent}`);
-        }
-    }
+    appendFileSection(sections, "Scope file", request.scopeFile, deps);
+    appendFileSection(sections, "State file", request.stateFile, deps);
     sections.push(request.prompt);
     return sections.join("\n\n---\n\n");
 }

package/dist/repertoire/coding/tools.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codingToolDefinitions = void 0;
 const index_1 = require("./index");
+const context_pack_1 = require("./context-pack");
 const identity_1 = require("../../heart/identity");
 const obligations_1 = require("../../heart/obligations");
 const runtime_1 = require("../../nerves/runtime");
@@ -42,11 +43,13 @@ function matchesReusableCodingSession(session, request) {
     if (session.status !== "spawning" && session.status !== "running" && session.status !== "waiting_input" && session.status !== "stalled") {
         return false;
     }
+    const scopeMatches = request.scopeFile ? session.scopeFile === request.scopeFile : true;
+    const stateMatches = request.stateFile ? session.stateFile === request.stateFile : true;
     return (session.runner === request.runner &&
         session.workdir === request.workdir &&
         session.taskRef === request.taskRef &&
-        session.scopeFile === request.scopeFile &&
-        session.stateFile === request.stateFile &&
+        scopeMatches &&
+        stateMatches &&
         session.obligationId === request.obligationId &&
         sameOriginSession(request.originSession, session.originSession));
 }
@@ -221,7 +224,8 @@ exports.codingToolDefinitions = [
             if (stateFile)
                 request.stateFile = stateFile;
             const manager = (0, index_1.getCodingSessionManager)();
-            const existingSession = findReusableCodingSession(manager.listSessions(), request);
+            const existingSessions = manager.listSessions();
+            const existingSession = findReusableCodingSession(existingSessions, request);
             if (existingSession) {
                 (0, runtime_1.emitNervesEvent)({
                     component: "repertoire",
@@ -241,6 +245,17 @@ exports.codingToolDefinitions = [
                 });
                 request.obligationId = created.id;
             }
+            if (!request.scopeFile || !request.stateFile) {
+                const generated = (0, context_pack_1.prepareCodingContextPack)({
+                    request: { ...request },
+                    existingSessions,
+                    activeWorkFrame: ctx?.activeWorkFrame,
+                });
+                if (!request.scopeFile)
+                    request.scopeFile = generated.scopeFile;
+                if (!request.stateFile)
+                    request.stateFile = generated.stateFile;
+            }
             const session = await manager.spawnSession(request);
             if (session.obligationId) {
                 (0, obligations_1.advanceObligation)((0, identity_1.getAgentRoot)(), session.obligationId, {

package/dist/repertoire/tools-base.js

@@ -116,6 +116,14 @@ async function recallSessionSafely(options) {
         return { kind: "missing" };
     }
 }
+async function searchSessionSafely(options) {
+    try {
+        return await (0, session_recall_1.searchSessionTranscript)(options);
+    }
+    catch {
+        return { kind: "missing" };
+    }
+}
 function normalizeProgressOutcome(text) {
     const trimmed = text.trim();
     /* v8 ignore next -- defensive: normalizeProgressOutcome null branch @preserve */
@@ -993,7 +1001,7 @@ exports.baseToolDefinitions = [
             type: "function",
             function: {
                 name: "query_session",
-                description: "read the last messages from another session. use this to check on a conversation with a friend or review your own inner dialog.",
+                description: "inspect another session. use transcript for recent context, status for self/inner progress, or search to find older history by query.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -1001,7 +1009,12 @@ exports.baseToolDefinitions = [
                         channel: { type: "string", description: "the channel: cli, teams, or inner" },
                         key: { type: "string", description: "session key (defaults to 'session')" },
                         messageCount: { type: "string", description: "how many recent messages to return (default 20)" },
-                        mode: { type: "string", enum: ["transcript", "status"], description: "transcript (default) or lightweight status for self/inner checks" },
+                        mode: {
+                            type: "string",
+                            enum: ["transcript", "status", "search"],
+                            description: "transcript (default), lightweight status for self/inner checks, or search for older history",
+                        },
+                        query: { type: "string", description: "required when mode=search; search term for older session history" },
                     },
                     required: ["friendId", "channel"],
                 },
@@ -1021,6 +1034,33 @@ exports.baseToolDefinitions = [
                 const pendingDir = (0, pending_1.getInnerDialogPendingDir)((0, identity_1.getAgentName)());
                 return renderInnerProgressStatus((0, thoughts_1.readInnerDialogStatus)(sessionPath, pendingDir));
             }
+            if (mode === "search") {
+                const query = (args.query || "").trim();
+                if (!query) {
+                    return "search mode requires a non-empty query.";
+                }
+                const search = await searchSessionSafely({
+                    sessionPath: (0, config_1.resolveSessionPath)(friendId, channel, key),
+                    friendId,
+                    channel,
+                    key,
+                    query,
+                });
+                if (search.kind === "missing") {
+                    return NO_SESSION_FOUND_MESSAGE;
+                }
+                if (search.kind === "empty") {
+                    return EMPTY_SESSION_MESSAGE;
+                }
+                if (search.kind === "no_match") {
+                    return `no matches for "${search.query}" in that session.\n\n${search.snapshot}`;
+                }
+                return [
+                    `history search: "${search.query}"`,
+                    search.snapshot,
+                    ...search.matches.map((match, index) => `match ${index + 1}\n${match}`),
+                ].join("\n\n");
+            }
             const sessFile = (0, config_1.resolveSessionPath)(friendId, channel, key);
             const recall = await recallSessionSafely({
                 sessionPath: sessFile,

package/dist/senses/bluebubbles.js

@@ -629,7 +629,13 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source) {
                 continuityIngressTexts: getBlueBubblesContinuityIngressTexts(event),
                 callbacks,
                 friendResolver: { resolve: () => Promise.resolve(context) },
-                sessionLoader: { loadOrCreate: () => Promise.resolve({ messages: sessionMessages, sessionPath: sessPath, state: existing?.state }) },
+                sessionLoader: {
+                    loadOrCreate: () => Promise.resolve({
+                        messages: sessionMessages,
+                        sessionPath: sessPath,
+                        state: existing?.state,
+                    }),
+                },
                 pendingDir,
                 friendStore: store,
                 provider: "imessage-handle",

package/dist/senses/cli.js

@@ -827,7 +827,13 @@ async function main(agentName, options) {
                     continuityIngressTexts: getCliContinuityIngressTexts(userInput),
                     callbacks,
                     friendResolver: { resolve: () => Promise.resolve(resolvedContext) },
-                    sessionLoader: { loadOrCreate: () => Promise.resolve({ messages, sessionPath: sessPath, state: sessionState }) },
+                    sessionLoader: {
+                        loadOrCreate: () => Promise.resolve({
+                            messages,
+                            sessionPath: sessPath,
+                            state: sessionState,
+                        }),
+                    },
                     pendingDir,
                     friendStore,
                     provider: "local",

package/dist/senses/inner-dialog.js

@@ -459,7 +459,10 @@ async function runInnerDialogTurn(options) {
         const sessionLoader = {
             loadOrCreate: async () => {
                 if (existingMessages.length > 0) {
-                    return { messages: existingMessages, sessionPath: sessionFilePath };
+                    return {
+                        messages: existingMessages,
+                        sessionPath: sessionFilePath,
+                    };
                 }
                 // Fresh session: build system prompt
                 const systemPrompt = await (0, prompt_1.buildSystem)("inner", { toolChoiceRequired: true, mcpManager });

package/dist/senses/teams.js

@@ -564,7 +564,11 @@ async function handleTeamsMessage(text, stream, conversationId, teamsContext, se
                         ? existing.messages
                         : [{ role: "system", content: await (0, prompt_1.buildSystem)("teams", { mcpManager }, resolvedContext) }];
                     (0, core_1.repairOrphanedToolCalls)(messages);
-                    return { messages, sessionPath: sessPath, state: existing?.state };
+                    return {
+                        messages,
+                        sessionPath: sessPath,
+                        state: existing?.state,
+                    };
                 },
             },
             pendingDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.109",
+  "version": "0.1.0-alpha.110",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",