@fiale-plus/pi-rogue-bundle 0.1.17 → 0.1.19

package/node_modules/@fiale-plus/pi-core/src/context-broker.ts

@@ -91,11 +91,17 @@ export interface ContextBrokerOptions {
   briefBytes?: number;
 }
 
+export interface ContextPurgeOptions {
+  sessionId?: string;
+  keepPinned?: boolean;
+}
+
 export interface BoundedContextBroker {
   publish(input: ContextArtifactInput): ContextArtifact;
   lookup(query?: ContextLookupQuery): ContextArtifact[];
   pin(idOrHandle: string, pinned?: boolean): ContextArtifact | null;
   prune(now?: number): ContextBrokerStatus;
+  purge(options?: ContextPurgeOptions): ContextBrokerStatus;
   status(): ContextBrokerStatus;
   renderBrief(query?: ContextLookupQuery & { budgetBytes?: number }): string;
 }

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/extension.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -80,6 +80,7 @@ describe("context broker beta enablement", () => {
       "brief",
       "lookup",
       "pin",
+      "export",
       "prune",
     ]);
   });
@@ -120,6 +121,42 @@ describe("context broker beta enablement", () => {
     expect(notifications.at(-1)?.message).toContain("README.md");
   });
 
+  it("purges unpinned broker artifacts after session compaction", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi, { briefBytes: 1200 });
+    const { ctx, notifications } = createCtx();
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "scratch-call",
+      toolName: "bash",
+      input: { command: "echo scratch" },
+      content: [{ type: "text", text: "scratch payload" }],
+      isError: false,
+    }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "keep-call",
+      toolName: "bash",
+      input: { command: "echo keep" },
+      content: [{ type: "text", text: "keep payload" }],
+      isError: false,
+    }, ctx);
+    const keepCompletion = commands.get("context").getArgumentCompletions("pin ")?.find((item: any) => String(item.description).includes("echo keep"));
+    const keepHandle = keepCompletion?.value.replace(/^pin /, "");
+    expect(keepHandle).toBeTruthy();
+    await commands.get("context").handler(`pin ${keepHandle}`, ctx);
+
+    await runHandlers(handlers, "session_compact", { type: "session_compact", compactionEntry: { summary: "compact" }, fromExtension: false }, ctx);
+    await commands.get("context").handler("brief", ctx);
+
+    const brief = notifications.at(-1)?.message ?? "";
+    expect(brief).toContain("echo keep");
+    expect(brief).not.toContain("echo scratch");
+    expect(notifications.some((item) => item.message.includes("compact cleanup purged 1 unpinned artifact"))).toBe(true);
+  });
+
   it("is safe on malformed session branches", async () => {
     const { pi, handlers } = createPiMock();
     registerContextBrokerBeta(pi);
@@ -182,6 +219,38 @@ describe("context broker beta enablement", () => {
     expect(Buffer.byteLength(payload, "utf8")).toBeLessThanOrEqual(80);
   });
 
+  it("full payload export path writes the full artifact payload", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi, { lookupBytes: 80, searchBytes: 50 });
+    const { ctx, notifications } = createCtx();
+    const payload = "payload_" + "x".repeat(120) + "::END";
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "call-export",
+      toolName: "bash",
+      input: { command: "printf payload" },
+      content: [{ type: "text", text: payload }],
+      isError: false,
+    }, ctx);
+
+    const exportCompletion = commands.get("context").getArgumentCompletions("export ")?.[0];
+    expect(exportCompletion.value.startsWith("export ctx://")).toBe(true);
+    const exportHandle = exportCompletion.value.replace(/^export /, "");
+
+    await commands.get("context").handler(`export ${exportHandle}`, ctx);
+
+    const message = notifications.at(-1)?.message ?? "";
+    const exportPath = message.split(" to ").at(-1) ?? "";
+    expect(exportPath).toContain("pi-context-broker-export-");
+    expect(exportPath).toMatch(/\.txt$/);
+    const exportedPayload = readFileSync(exportPath, "utf8");
+    expect(exportedPayload).toContain("tool=bash");
+    expect(exportedPayload).toContain(payload);
+    rmSync(exportPath);
+  });
+
   it("text search lookup returns a smaller byte-clipped excerpt", async () => {
     const { pi, handlers, commands } = createPiMock();
     registerContextBrokerBeta(pi, { lookupBytes: 80, searchBytes: 50 });
@@ -204,6 +273,31 @@ describe("context broker beta enablement", () => {
     expect(Buffer.byteLength(payload, "utf8")).toBeLessThanOrEqual(50);
   });
 
+  it("sanitizes control characters in context command lookup output", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi);
+    const { ctx, notifications } = createCtx();
+    const rawPayload = `${"SAFE"}\u0000${"\x1B"}[31mBLOCK\u0000`;
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "call-control",
+      toolName: "bash",
+      input: { command: "echo control" },
+      content: [{ type: "text", text: rawPayload }],
+      isError: false,
+    }, ctx);
+
+    const completion = commands.get("context").getArgumentCompletions("lookup ")?.[0];
+    await commands.get("context").handler(completion?.value ?? "", ctx);
+
+    const message = notifications.at(-1)?.message ?? "";
+    expect(message).toContain("\\u0000");
+    expect(message).toContain("\\u001b");
+    expect(message).not.toContain(String.fromCharCode(0));
+  });
+
   it("context_lookup tool dereferences handles for exact evidence", async () => {
     const { pi, handlers, commands, tools } = createPiMock();
     registerContextBrokerBeta(pi, { lookupBytes: 500 });
@@ -225,6 +319,70 @@ describe("context broker beta enablement", () => {
     expect(result.content[0].text).toContain("exact evidence payload");
   });
 
+  it("does not broker context_lookup results recursively", async () => {
+    const { pi, handlers, commands, tools } = createPiMock();
+    registerContextBrokerBeta(pi, { lookupBytes: 500, rewriteThresholdBytes: 1 });
+    const { ctx, notifications } = createCtx();
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "call-source",
+      toolName: "bash",
+      input: { command: "echo source" },
+      content: [{ type: "text", text: "source evidence payload" }],
+      isError: false,
+    }, ctx);
+    const handle = commands.get("context").getArgumentCompletions("lookup ")?.[0].value.replace(/^lookup /, "");
+    const lookupResult = await tools.get("context_lookup").execute("lookup-call", { handle }, undefined, undefined, ctx);
+
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "lookup-call",
+      toolName: "context_lookup",
+      input: { handle },
+      content: lookupResult.content,
+      isError: false,
+    }, ctx);
+    const contextResult = await handlers.get("context")?.[0]({
+      type: "context",
+      messages: [{ role: "toolResult", toolCallId: "lookup-call", toolName: "context_lookup", content: lookupResult.content, isError: false }],
+    }, ctx);
+    await commands.get("context").handler("brief", ctx);
+
+    const rewrittenLookup = contextResult.messages[0].content[0].text;
+    const brief = notifications.at(-1)?.message ?? "";
+    expect(rewrittenLookup).toContain("Context lookup result omitted from prompt");
+    expect(rewrittenLookup).not.toContain("source evidence payload");
+    expect(rewrittenLookup).not.toContain("Context broker artifact: ctx://");
+    expect(brief).toContain("echo source");
+    expect(brief).not.toContain("completed context_lookup");
+  });
+
+  it("still brokers normal tool output that exactly matches broker marker text", async () => {
+    const { pi, handlers, commands } = createPiMock();
+    registerContextBrokerBeta(pi);
+    const { ctx, notifications } = createCtx();
+
+    await runHandlers(handlers, "session_start", { type: "session_start" }, ctx);
+    await runHandlers(handlers, "tool_result", {
+      type: "tool_result",
+      toolCallId: "grep-call",
+      toolName: "bash",
+      input: { command: "grep ctx session.log" },
+      content: [{ type: "text", text: [
+        "Context broker artifact: ctx://session/example",
+        "Summary: copied placeholder",
+        "Payload bytes: 10",
+        "Raw payload omitted from prompt. Use /context lookup <handle> if exact evidence is needed.",
+      ].join("\n") }],
+      isError: false,
+    }, ctx);
+    await commands.get("context").handler("brief", ctx);
+
+    expect(notifications.at(-1)?.message).toContain("grep ctx session.log");
+  });
+
   it("context_lookup refuses empty unfocused payload-dumping calls", async () => {
     const { pi, handlers, tools } = createPiMock();
     registerContextBrokerBeta(pi, { lookupBytes: 500 });

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/extension.ts

@@ -1,4 +1,7 @@
 import { createHash } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -69,6 +72,20 @@ function toText(value: unknown): string {
   }
 }
 
+function sanitizeForPrompt(text: string): string {
+  return String(text).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+
+function renderLookupOutput(item: ContextArtifact, payloadLimit: number): string {
+  return [
+    sanitizeForPrompt(item.handle),
+    `tier=${item.tier} kind=${item.kind} bytes=${item.bytes}`,
+    `summary=${sanitizeForPrompt(item.summary)}`,
+    "payload:",
+    truncateUtf8(sanitizeForPrompt(item.payload), payloadLimit),
+  ].join("\n");
+}
+
 function truncateUtf8(text: string, maxBytes: number): string {
   const limit = Math.max(0, Math.floor(maxBytes));
   const totalBytes = Buffer.byteLength(text, "utf8");
@@ -155,6 +172,14 @@ function brokerPlaceholder(artifact: ContextArtifact): string {
   ].join("\n");
 }
 
+function contextLookupHistoryPlaceholder(): string {
+  return [
+    "Context lookup result omitted from prompt.",
+    "Prior context_lookup evidence is terminal and is not re-brokered.",
+    "Run context_lookup again with a focused handle/filter only if exact evidence is still needed.",
+  ].join("\n");
+}
+
 function summarizeTool(event: { toolName: string; input?: any; isError?: boolean }, bytes: number): string {
   const command = event.toolName === "bash" ? event.input?.command : undefined;
   const path = event.input?.path;
@@ -162,6 +187,12 @@ function summarizeTool(event: { toolName: string; input?: any; isError?: boolean
   return `${event.isError ? "failed" : "completed"} ${event.toolName}${target}; payload=${bytes} bytes`;
 }
 
+const NON_BROKERED_TOOL_NAMES = new Set(["context_lookup"]);
+
+function shouldBrokerToolName(toolName: string): boolean {
+  return !NON_BROKERED_TOOL_NAMES.has(toolName);
+}
+
 function ttlFromNowFor(createdAt: number | undefined): number | undefined {
   if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) return undefined;
   return Math.max(DEFAULT_TTL_MS, Date.now() - createdAt + DEFAULT_TTL_MS);
@@ -212,6 +243,8 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
     createdAt?: number;
     ttlMs?: number;
   }): ContextArtifact | null {
+    if (!shouldBrokerToolName(event.toolName)) return null;
+
     if (event.sourceId) {
       const existingHandle = sourceHandles.get(event.sourceId);
       if (existingHandle) {
@@ -295,6 +328,7 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
             isError: Boolean(entry.message.isError),
             sourceId,
             createdAt,
+            ttlMs: ttlFromNowFor(createdAt),
           }) && !alreadySeen) added += 1;
         }
 
@@ -316,6 +350,7 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
             isError: typeof entry.message.exitCode === "number" ? entry.message.exitCode !== 0 : Boolean(entry.message.cancelled),
             sourceId,
             createdAt,
+            ttlMs: ttlFromNowFor(createdAt),
           }) && !alreadySeen) added += 1;
         }
       } catch {
@@ -331,10 +366,11 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
     { value: "brief", label: "brief", description: "Show the bounded broker brief" },
     { value: "lookup ", label: "lookup", description: "Lookup by ctx:// handle or current-session text" },
     { value: "pin ", label: "pin", description: "Pin an artifact by ctx:// handle or id" },
+    { value: "export ", label: "export", description: "Export full payload for a ctx:// handle or id" },
     { value: "prune", label: "prune", description: "Run TTL/cap pruning now" },
   ];
 
-  function artifactCompletions(action: "lookup" | "pin", query: string): AutocompleteItem[] {
+  function artifactCompletions(action: "lookup" | "pin" | "export", query: string): AutocompleteItem[] {
     const needle = query.trim().toLowerCase();
     return broker.lookup({ sessionId: activeSessionId, limit: 10 })
       .filter((artifact) => {
@@ -362,7 +398,7 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
       return items.length ? items : contextActions;
     }
 
-    if (action === "lookup" || action === "pin") {
+    if (action === "lookup" || action === "pin" || action === "export") {
       const items = artifactCompletions(action, restParts.join(" "));
       return items.length ? items : null;
     }
@@ -379,6 +415,16 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
     );
   });
 
+  pi.on("session_compact", async (_event, ctx) => {
+    activeSessionId = sessionIdFor(ctx);
+    const before = broker.status();
+    const after = broker.purge({ sessionId: activeSessionId, keepPinned: true });
+    seenSourceIds.clear();
+    sourceHandles.clear();
+    const removed = before.records - after.records;
+    if (removed > 0) ctx.ui.notify(`Context broker compact cleanup purged ${removed} unpinned artifact${removed === 1 ? "" : "s"}; pinned artifacts retained.`, "info");
+  });
+
   pi.on("tool_result", async (event: ToolResultEvent, ctx) => {
     activeSessionId = sessionIdFor(ctx);
     publishToolArtifact({ ...event, sourceId: event.toolCallId });
@@ -387,13 +433,17 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
   pi.on("context", async (event, ctx) => {
     activeSessionId = sessionIdFor(ctx);
     const toolInputs = collectToolInputs(event.messages);
-    const drafts = event.messages.map((message: any): { original: any; artifact?: ContextArtifact; rewrite?: (artifact: ContextArtifact) => any } => {
+    const drafts = event.messages.map((message: any): { original: any; replacement?: any; artifact?: ContextArtifact; rewrite?: (artifact: ContextArtifact) => any } => {
       if (message?.role === "toolResult") {
         const raw = contentText(message.content);
         if (Buffer.byteLength(raw, "utf8") <= rewriteThresholdBytes) return { original: message };
         const toolInput = typeof message.toolCallId === "string" ? toolInputs.get(message.toolCallId) : undefined;
+        const toolName = String(message.toolName ?? toolInput?.toolName ?? "tool");
+        if (!shouldBrokerToolName(toolName)) {
+          return { original: message, replacement: { ...message, content: [{ type: "text", text: contextLookupHistoryPlaceholder() }] } };
+        }
         const artifact = publishToolArtifact({
-          toolName: String(message.toolName ?? toolInput?.toolName ?? "tool"),
+          toolName,
           input: message.input ?? toolInput?.input,
           content: message.content,
           details: message.details,
@@ -436,6 +486,10 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
 
     let changed = false;
     const messages = drafts.map((draft) => {
+      if (draft.replacement) {
+        changed = true;
+        return draft.replacement;
+      }
       if (!draft.artifact || !draft.rewrite) return draft.original;
       const live = broker.lookup({ handle: draft.artifact.handle })[0];
       if (!live) {
@@ -498,18 +552,12 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
         limit: Math.min(10, Math.max(1, Math.floor(p.limit ?? (exact ? 1 : 5)))),
       });
       if (!results.length) return textResult("No context artifacts matched. Missing or expired handles should be reported explicitly.");
-      return textResult(results.map((item) => [
-        item.handle,
-        `tier=${item.tier} kind=${item.kind} bytes=${item.bytes}`,
-        `summary=${item.summary}`,
-        "payload:",
-        truncateUtf8(item.payload, exact ? lookupBytes : searchBytes),
-      ].join("\n")).join("\n\n---\n\n"));
+      return textResult(results.map((item) => renderLookupOutput(item, exact ? lookupBytes : searchBytes)).join("\n\n---\n\n"));
     },
   });
 
   pi.registerCommand("context", {
-    description: "Inspect the beta context broker: status | brief | lookup <handle-or-text> | pin <handle> | prune",
+    description: "Inspect the beta context broker: status | brief | lookup <handle-or-text> | pin <handle-or-id> | export <handle-or-id> | prune",
     getArgumentCompletions: contextArgumentCompletions,
     handler: async (args, ctx) => {
       activeSessionId = sessionIdFor(ctx);
@@ -537,13 +585,7 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
         }
         const exact = query.startsWith("ctx://");
         const results = broker.lookup(exact ? { handle: query } : { sessionId: activeSessionId, text: query, limit: 5 });
-        ctx.ui.notify(results.length ? results.map((item) => [
-          item.handle,
-          `kind=${item.kind} bytes=${item.bytes}`,
-          `summary=${item.summary}`,
-          "payload:",
-          truncateUtf8(item.payload, exact ? lookupBytes : searchBytes),
-        ].join("\n")).join("\n\n---\n\n") : "No context artifacts matched.", "info");
+        ctx.ui.notify(results.length ? results.map((item) => renderLookupOutput(item, exact ? lookupBytes : searchBytes)).join("\n\n---\n\n") : "No context artifacts matched.", "info");
         return;
       }
 
@@ -557,13 +599,33 @@ export function registerContextBrokerBeta(pi: ExtensionAPI, options: ContextBrok
         return;
       }
 
+      if (action === "export") {
+        if (!query) {
+          ctx.ui.notify("Usage: /context export <ctx://handle-or-id>", "warning");
+          return;
+        }
+
+        const exact = query.startsWith("ctx://");
+        const artifact = exact ? broker.lookup({ handle: query })[0] : broker.lookup({ id: query })[0];
+        if (!artifact) {
+          ctx.ui.notify("No artifact matched that handle/id.", "warning");
+          return;
+        }
+
+        const exportDir = mkdtempSync(join(tmpdir(), "pi-context-broker-export-"));
+        const exportPath = join(exportDir, `${artifact.id}.txt`);
+        writeFileSync(exportPath, artifact.payload, "utf8");
+        ctx.ui.notify(`Exported full payload for ${sanitizeForPrompt(artifact.handle)} (${artifact.bytes} bytes) to ${exportPath}`, "info");
+        return;
+      }
+
       if (action === "prune") {
         const status = broker.prune();
         ctx.ui.notify(`Pruned. ${status.records} records, ${status.bytes} bytes remain.`, "info");
         return;
       }
 
-      ctx.ui.notify("Usage: /context status | brief | lookup <handle-or-text> | pin <handle> | prune", "warning");
+      ctx.ui.notify("Usage: /context status | brief | lookup <handle-or-text> | pin <handle-or-id> | export <handle-or-id> | prune", "warning");
     },
   });
 }

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/file.ts

@@ -1,8 +1,8 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { safeName } from "@fiale-plus/pi-core";
-import type { BoundedContextBroker, ContextArtifact, ContextArtifactInput, ContextArtifactTier, ContextBrokerOptions, ContextBrokerStatus, ContextLookupQuery } from "@fiale-plus/pi-core";
+import type { BoundedContextBroker, ContextArtifact, ContextArtifactInput, ContextArtifactTier, ContextBrokerOptions, ContextBrokerStatus, ContextLookupQuery, ContextPurgeOptions } from "@fiale-plus/pi-core";
 import { createInMemoryContextBroker } from "./index.js";
 
 export interface FileContextBrokerOptions extends ContextBrokerOptions {
@@ -113,6 +113,16 @@ function persistArtifactSnapshot(dir: string, artifact: ContextArtifact): void {
   });
 }
 
+function removeUnreferencedBlobs(dir: string, keptSha256: Set<string>): void {
+  const blobsDir = join(dir, "blobs");
+  if (!existsSync(blobsDir)) return;
+  for (const entry of readdirSync(blobsDir)) {
+    if (!entry.endsWith(".txt")) continue;
+    const sha256 = entry.slice(0, -4);
+    if (!keptSha256.has(sha256)) unlinkSync(join(blobsDir, entry));
+  }
+}
+
 export function createFileContextBroker(options: FileContextBrokerOptions = {}): BoundedContextBroker {
   const dir = options.dir ?? process.env.PI_CONTEXT_BROKER_STORE_DIR ?? defaultStoreDir();
   ensureDir(join(dir, "blobs"));
@@ -155,6 +165,22 @@ export function createFileContextBroker(options: FileContextBrokerOptions = {}):
       return artifact;
     },
     prune(now?: number): ContextBrokerStatus { return broker.prune(now); },
+    purge(options?: ContextPurgeOptions): ContextBrokerStatus {
+      const status = broker.purge(options);
+      const remaining = broker.lookup({ limit: Number.MAX_SAFE_INTEGER });
+      persistedSources.clear();
+      handleAliases.clear();
+      writeFileSync(metadataFile(dir), "", "utf8");
+      const keptSha256 = new Set<string>();
+      for (const artifact of remaining) {
+        keptSha256.add(artifact.sha256);
+        for (const parentId of artifact.parentIds) persistedSources.set(parentId, artifact.handle);
+        handleAliases.set(artifact.handle, artifact.handle);
+        persistArtifactSnapshot(dir, artifact);
+      }
+      removeUnreferencedBlobs(dir, keptSha256);
+      return status;
+    },
     status(): ContextBrokerStatus { return broker.status(); },
     renderBrief(query?: ContextLookupQuery & { budgetBytes?: number }): string { return broker.renderBrief(query); },
   };

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/index.test.ts

@@ -273,4 +273,18 @@ describe("createInMemoryContextBroker", () => {
     expect(Buffer.byteLength(brief, "utf8")).toBeLessThanOrEqual(170);
     expect(brief).toContain("Context Broker");
   });
+
+  it("purges unpinned session artifacts while retaining pinned evidence", () => {
+    const broker = createInMemoryContextBroker();
+    const unpinned = broker.publish({ sessionId: "s", kind: "tool_output", payload: "scratch", summary: "scratch" });
+    const pinned = broker.publish({ sessionId: "s", kind: "tool_output", payload: "keep", summary: "keep", pinned: true });
+    const other = broker.publish({ sessionId: "other", kind: "tool_output", payload: "other", summary: "other" });
+
+    const status = broker.purge({ sessionId: "s", keepPinned: true });
+
+    expect(status.records).toBe(2);
+    expect(broker.lookup({ handle: unpinned.handle })).toEqual([]);
+    expect(broker.lookup({ handle: pinned.handle })[0]?.payload).toBe("keep");
+    expect(broker.lookup({ handle: other.handle })[0]?.payload).toBe("other");
+  });
 });

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/index.ts

@@ -9,6 +9,7 @@ import type {
   ContextBrokerOptions,
   ContextBrokerStatus,
   ContextLookupQuery,
+  ContextPurgeOptions,
 } from "@fiale-plus/pi-core";
 
 export type {
@@ -20,6 +21,7 @@ export type {
   ContextBrokerOptions,
   ContextBrokerStatus,
   ContextLookupQuery,
+  ContextPurgeOptions,
 } from "@fiale-plus/pi-core";
 
 const DEFAULT_MAX_RECORDS = 256;
@@ -222,6 +224,16 @@ export function createInMemoryContextBroker(options: ContextBrokerOptions = {}):
     return currentStatus();
   }
 
+  function purge(options: ContextPurgeOptions = {}): ContextBrokerStatus {
+    dropExpired();
+    const keepPinned = options.keepPinned ?? true;
+    artifacts = artifacts.filter((artifact) => {
+      if (options.sessionId && artifact.sessionId !== options.sessionId) return true;
+      return keepPinned && artifact.pinned;
+    });
+    return currentStatus();
+  }
+
   function publish(input: ContextArtifactInput): ContextArtifact {
     const now = input.createdAt ?? Date.now();
     const payload = payloadText(input.payload);
@@ -318,6 +330,7 @@ export function createInMemoryContextBroker(options: ContextBrokerOptions = {}):
     lookup,
     pin,
     prune,
+    purge,
     status,
     renderBrief,
   };

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/sqlite.test.ts

@@ -75,4 +75,24 @@ describe("createSqliteContextBroker", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("purges unpinned durable artifacts for a session", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-sqlite-test-"));
+    try {
+      const path = join(dir, "artifacts.sqlite");
+      let broker = createSqliteContextBroker({ path, defaultTtlMs: 0 });
+      const scratch = broker.publish({ sessionId: "s", kind: "tool_output", payload: "scratch" });
+      const pinned = broker.publish({ sessionId: "s", kind: "tool_output", payload: "keep", pinned: true });
+      const other = broker.publish({ sessionId: "other", kind: "tool_output", payload: "other" });
+
+      broker.purge({ sessionId: "s", keepPinned: true });
+      broker = createSqliteContextBroker({ path, defaultTtlMs: 0 });
+
+      expect(broker.lookup({ handle: scratch.handle })).toEqual([]);
+      expect(broker.lookup({ handle: pinned.handle })[0]?.payload).toBe("keep");
+      expect(broker.lookup({ handle: other.handle })[0]?.payload).toBe("other");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/node_modules/@fiale-plus/pi-rogue-context-broker/src/sqlite.ts

@@ -13,6 +13,7 @@ import type {
   ContextBrokerOptions,
   ContextBrokerStatus,
   ContextLookupQuery,
+  ContextPurgeOptions,
 } from "@fiale-plus/pi-core";
 
 export interface SqliteContextBrokerOptions extends ContextBrokerOptions {
@@ -321,6 +322,29 @@ export function createSqliteContextBroker(options: SqliteContextBrokerOptions =
     return currentStatus();
   }
 
+  function purge(options: ContextPurgeOptions = {}): ContextBrokerStatus {
+    dropExpired();
+    const keepPinned = options.keepPinned ?? true;
+    const clauses: string[] = [];
+    const params: Array<string | number> = [];
+    if (options.sessionId) {
+      clauses.push("sessionId = ?");
+      params.push(options.sessionId);
+    }
+    if (keepPinned) clauses.push("pinned = 0");
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(`SELECT id FROM artifacts ${where}`).all(...params);
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      for (const row of rows) deleteArtifact(String(row.id));
+      db.exec("COMMIT");
+    } catch (error) {
+      db.exec("ROLLBACK");
+      throw error;
+    }
+    return currentStatus();
+  }
+
   function publish(input: ContextArtifactInput): ContextArtifact {
     dropExpired();
     const source = stableSource(input);
@@ -492,7 +516,7 @@ export function createSqliteContextBroker(options: SqliteContextBrokerOptions =
     return truncateUtf8(lines.join("\n"), budget);
   }
 
-  return { publish, lookup, pin, prune, status, renderBrief };
+  return { publish, lookup, pin, prune, purge, status, renderBrief };
 }
 
 export function contextBrokerSqlitePathForSession(baseDir: string, sessionId: string): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiale-plus/pi-rogue-bundle",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Public Pi-Rogue bundle for advisor, orchestration, and beta context broker. Single consolidated artefact (leaf releases paused; private packages are bundled here).",
   "type": "module",
   "license": "MIT",