pi-shadow-mind 0.1.14 → 0.1.16

package/dist/index.js

@@ -5,13 +5,128 @@ var __export = (target, all) => {
 };
 
 // src/runtime.ts
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import {
   buildSessionContext
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
+// src/final-response-queue.ts
+var FinalResponseQueue = class {
+  constructor(options) {
+    this.options = options;
+  }
+  pending = [];
+  enqueue(items) {
+    this.pending.push(...items);
+    this.pump();
+  }
+  slotAvailable() {
+    this.pump();
+  }
+  clear() {
+    this.pending.length = 0;
+  }
+  pump() {
+    while (this.options.activeCount() < this.options.maxParallel() && this.pending.length > 0) {
+      const epoch = this.options.currentEpoch();
+      const activeShadowIds = this.options.activeShadowIds();
+      const index = this.pending.findIndex(
+        (item2) => item2.epoch !== epoch || !activeShadowIds.has(item2.shadowId)
+      );
+      if (index < 0) return;
+      const [item] = this.pending.splice(index, 1);
+      if (!item || item.epoch !== epoch) continue;
+      this.options.launch(item);
+    }
+  }
+};
+
+// src/completion-review.ts
+var CompletionReview = class {
+  constructor(host) {
+    this.host = host;
+    this.queue = new FinalResponseQueue({
+      currentEpoch: () => this.host.currentEpoch(),
+      maxParallel: () => this.host.maxParallel(),
+      activeCount: () => this.host.activeCount(),
+      activeShadowIds: () => this.host.activeShadowIds(),
+      launch: ({ job, run }) => host.launch(job, run)
+    });
+  }
+  requestId = 0;
+  state;
+  requestByRun = /* @__PURE__ */ new WeakMap();
+  queue;
+  begin(epoch) {
+    this.invalidate();
+    return { id: this.requestId, epoch };
+  }
+  isCurrent(request) {
+    return request.id === this.requestId && request.epoch === this.host.currentEpoch();
+  }
+  schedule(request, jobs) {
+    if (!this.isCurrent(request) || this.state?.requestId === request.id || jobs.some((job) => job.epoch !== request.epoch)) {
+      return false;
+    }
+    if (jobs.length === 0) {
+      this.retire(request.id);
+      return true;
+    }
+    this.state = {
+      requestId: request.id,
+      epoch: request.epoch,
+      remaining: jobs.length,
+      reports: []
+    };
+    this.queue.enqueue(
+      jobs.map((job) => {
+        const run = {
+          accept: (report) => this.accept(request.id, report)
+        };
+        this.requestByRun.set(run, request.id);
+        return { epoch: job.epoch, shadowId: job.shadowId, job, run };
+      })
+    );
+    return true;
+  }
+  slotAvailable() {
+    this.queue.slotAvailable();
+  }
+  complete(run) {
+    if (!run) return;
+    const requestId = this.requestByRun.get(run);
+    this.requestByRun.delete(run);
+    if (requestId === void 0 || this.state?.requestId !== requestId) return;
+    this.state.remaining -= 1;
+    if (this.state.remaining > 0) return;
+    const reports = this.state.reports;
+    this.retire(requestId);
+    if (reports.length > 0) this.host.deliver(reports);
+  }
+  cancel(request) {
+    if (this.isCurrent(request)) this.retire(request.id);
+  }
+  invalidate() {
+    this.requestId += 1;
+    this.state = void 0;
+    this.queue.clear();
+  }
+  retire(requestId) {
+    if (requestId !== this.requestId) return;
+    this.requestId += 1;
+    this.state = void 0;
+    this.queue.clear();
+  }
+  accept(requestId, report) {
+    if (this.state?.requestId !== requestId || report.epoch !== this.state.epoch) {
+      return;
+    }
+    this.state.reports.push(report);
+  }
+};
+
 // src/config.ts
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -6760,6 +6875,12 @@ var browser_default = dist_exports;
 // src/registry.ts
 import { mkdir as mkdir2, readFile as readFile2, readdir, stat } from "node:fs/promises";
 import { basename, extname, join as join2 } from "node:path";
+
+// src/types.ts
+var DEFAULT_READ_TOOLS = ["read", "grep", "find", "ls"];
+var SHADOW_TRIGGERS = ["heartbeat", "final_response"];
+
+// src/registry.ts
 var ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
 var ShadowRegistry = class {
   directory;
@@ -6787,8 +6908,14 @@ var ShadowRegistry = class {
         continue;
       }
       try {
-        const definition = parseShadowMarkdown(await readFile2(filePath, "utf8"), filePath);
-        this.cache.set(filePath, { mtimeMs: fileStat.mtimeMs, shadow: definition });
+        const definition = parseShadowMarkdown(
+          await readFile2(filePath, "utf8"),
+          filePath
+        );
+        this.cache.set(filePath, {
+          mtimeMs: fileStat.mtimeMs,
+          shadow: definition
+        });
         shadows.push(definition);
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -6803,7 +6930,10 @@ var ShadowRegistry = class {
     const ids = /* @__PURE__ */ new Set();
     for (const shadow of shadows) {
       if (ids.has(shadow.id)) {
-        diagnostics.push({ filePath: shadow.filePath, message: `duplicate shadow id: ${shadow.id}` });
+        diagnostics.push({
+          filePath: shadow.filePath,
+          message: `duplicate shadow id: ${shadow.id}`
+        });
       } else {
         ids.add(shadow.id);
         unique.push(shadow);
@@ -6813,14 +6943,18 @@ var ShadowRegistry = class {
   }
 };
 function parseShadowMarkdown(source, filePath) {
-  const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)([\s\S]*)$/.exec(source);
+  const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)([\s\S]*)$/.exec(
+    source
+  );
   if (!match) throw new Error("missing YAML frontmatter");
   const meta = browser_default.parse(match[1]);
-  if (!meta || typeof meta !== "object" || Array.isArray(meta)) throw new Error("frontmatter must be an object");
+  if (!meta || typeof meta !== "object" || Array.isArray(meta))
+    throw new Error("frontmatter must be an object");
   const value = meta;
   const fallbackId = basename(filePath, extname(filePath));
   const id = stringValue(value.id, fallbackId, "id");
-  if (!ID_PATTERN.test(id)) throw new Error("id must match [a-z0-9][a-z0-9_-]*");
+  if (!ID_PATTERN.test(id))
+    throw new Error("id must match [a-z0-9][a-z0-9_-]*");
   const prompt = match[2].trim();
   if (!prompt) throw new Error("shadow prompt body is empty");
   return {
@@ -6828,11 +6962,23 @@ function parseShadowMarkdown(source, filePath) {
     name: stringValue(value.name, id, "name"),
     enabled: booleanValue(value.enabled, true, "enabled"),
     debug: booleanValue(value.debug, false, "debug"),
-    activationProbability: probabilityValue(value.activation_probability, 0.3, "activation_probability"),
-    activeForModels: stringArray(value.active_for_models, ["*"], "active_for_models"),
+    activationProbability: probabilityValue(
+      value.activation_probability,
+      0.3,
+      "activation_probability"
+    ),
+    trigger: triggerArray(value.trigger, ["heartbeat"], "trigger"),
+    activeForModels: stringArray(
+      value.active_for_models,
+      ["*"],
+      "active_for_models"
+    ),
     runWithModel: optionalString(value.run_with_model, "run_with_model"),
     thinkingLevel: optionalThinking(value.thinking_level),
-    timeoutSeconds: optionalPositiveNumber(value.timeout_seconds, "timeout_seconds"),
+    timeoutSeconds: optionalPositiveNumber(
+      value.timeout_seconds,
+      "timeout_seconds"
+    ),
     tools: stringArray(value.tools, [], "tools"),
     prompt,
     filePath
@@ -6840,7 +6986,8 @@ function parseShadowMarkdown(source, filePath) {
 }
 function stringValue(value, fallback, name) {
   if (value === void 0) return fallback;
-  if (!isNonEmptyString(value)) throw new Error(`${name} must be a non-empty string`);
+  if (!isNonEmptyString(value))
+    throw new Error(`${name} must be a non-empty string`);
   return value.trim();
 }
 function optionalString(value, name) {
@@ -6853,19 +7000,31 @@ function booleanValue(value, fallback, name) {
 }
 function probabilityValue(value, fallback, name) {
   if (value === void 0) return fallback;
-  if (!isFiniteNumber(value) || !inRange(value, 0, 1)) throw new Error(`${name} must be between 0 and 1`);
+  if (!isFiniteNumber(value) || !inRange(value, 0, 1))
+    throw new Error(`${name} must be between 0 and 1`);
   return value;
 }
 function optionalPositiveNumber(value, name) {
   if (value === void 0) return void 0;
-  if (!isFiniteNumber(value) || value <= 0) throw new Error(`${name} must be positive`);
+  if (!isFiniteNumber(value) || value <= 0)
+    throw new Error(`${name} must be positive`);
   return value;
 }
 function stringArray(value, fallback, name) {
   if (value === void 0) return [...fallback];
-  if (!isStringArray(value)) throw new Error(`${name} must be an array of non-empty strings`);
+  if (!isStringArray(value))
+    throw new Error(`${name} must be an array of non-empty strings`);
   return [...new Set(value.map((item) => item.trim()))];
 }
+function triggerArray(value, fallback, name) {
+  const values = typeof value === "string" ? [value] : value;
+  const items = stringArray(values, fallback, name);
+  const allowed = new Set(SHADOW_TRIGGERS);
+  const invalid = items.filter((item) => !allowed.has(item));
+  if (invalid.length)
+    throw new Error(`${name} contains invalid trigger: ${invalid.join(", ")}`);
+  return items;
+}
 function optionalThinking(value) {
   if (value === void 0) return void 0;
   if (!isThinkingLevel(value)) throw new Error("thinking_level is invalid");
@@ -6887,17 +7046,37 @@ var EntityStore = class {
     return shadow;
   }
   async create(draft) {
-    if ((await this.list()).some((shadow) => shadow.id === draft.id)) throw new Error(`shadow already exists: ${draft.id}`);
-    return this.writeParsed(join3(this.registry.directory, `${draft.id}.md`), draft, { overwrite: false });
+    if ((await this.list()).some((shadow) => shadow.id === draft.id))
+      throw new Error(`shadow already exists: ${draft.id}`);
+    return this.writeParsed(
+      join3(this.registry.directory, `${draft.id}.md`),
+      draft,
+      { overwrite: false }
+    );
   }
   async update(id, patch) {
     const current = await this.get(id);
-    return this.writeParsed(current.filePath, { ...current, ...definedOnly(patch), id, prompt: patch.prompt ?? current.prompt }, { overwrite: true });
+    return this.writeParsed(
+      current.filePath,
+      {
+        ...current,
+        ...definedOnly(patch),
+        id,
+        prompt: patch.prompt ?? current.prompt
+      },
+      { overwrite: true }
+    );
   }
   async writeParsed(filePath, draft, options) {
-    const source = serializeShadow({ ...draft, prompt: draft.prompt ?? "Describe this Shadow Mind's responsibility." });
+    const source = serializeShadow({
+      ...draft,
+      prompt: draft.prompt ?? "Describe this Shadow Mind's responsibility."
+    });
     const parsed = parseShadowMarkdown(source, filePath);
-    await writeFile2(filePath, source, { encoding: "utf8", ...options.overwrite ? {} : { flag: "wx" } });
+    await writeFile2(filePath, source, {
+      encoding: "utf8",
+      ...options.overwrite ? {} : { flag: "wx" }
+    });
     return parsed;
   }
   async setEnabled(id, enabled) {
@@ -6920,6 +7099,7 @@ function serializeShadow(shadow) {
     enabled: shadow.enabled ?? true,
     debug: shadow.debug ?? false,
     activation_probability: shadow.activationProbability ?? 0.3,
+    trigger: shadow.trigger ?? ["heartbeat"],
     active_for_models: shadow.activeForModels ?? ["*"],
     ...shadow.runWithModel ? { run_with_model: shadow.runWithModel } : {},
     ...shadow.thinkingLevel ? { thinking_level: shadow.thinkingLevel } : {},
@@ -6934,21 +7114,37 @@ ${(shadow.prompt ?? "").trim()}
 `;
 }
 function describeShadow(shadow) {
-  return `${shadow.enabled ? "enabled" : "disabled"} ${shadow.id} (${shadow.name}) p=${shadow.activationProbability} models=${shadow.activeForModels.join(",")} tools=${shadow.tools.join(",") || "default"} file=${basename2(shadow.filePath)}`;
+  return `${shadow.enabled ? "enabled" : "disabled"} ${shadow.id} (${shadow.name}) p=${shadow.activationProbability} trigger=${shadow.trigger.join(",")} models=${shadow.activeForModels.join(",")} tools=${shadow.tools.join(",") || "default"} file=${basename2(shadow.filePath)}`;
 }
 function definedOnly(value) {
-  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== void 0)
+  );
 }
 
 // src/management-tools.ts
 import { Type } from "typebox";
 var ID = Type.String({ pattern: "^[a-z0-9][a-z0-9_-]*$" });
-var THINKING = Type.Union([Type.Literal("minimal"), Type.Literal("low"), Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh"), Type.Literal("max")]);
+var THINKING = Type.Union([
+  Type.Literal("minimal"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("xhigh"),
+  Type.Literal("max")
+]);
+var TRIGGER = Type.Union([
+  Type.Literal("heartbeat"),
+  Type.Literal("final_response")
+]);
 var SHADOW_FIELDS = {
   name: Type.Optional(Type.String()),
   enabled: Type.Optional(Type.Boolean()),
   debug: Type.Optional(Type.Boolean()),
-  activation_probability: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+  activation_probability: Type.Optional(
+    Type.Number({ minimum: 0, maximum: 1 })
+  ),
+  trigger: Type.Optional(Type.Array(TRIGGER)),
   active_for_models: Type.Optional(Type.Array(Type.String())),
   run_with_model: Type.Optional(Type.String()),
   thinking_level: Type.Optional(THINKING),
@@ -6967,80 +7163,160 @@ function registerManagementTools(pi, store, getConfig) {
   pi.registerTool(configWriteTool(store, getConfig));
 }
 function listTool(store) {
-  return tool("list_shadows", "List Shadows", "List all valid globally configured Shadow Minds.", Type.Object({}), async () => {
-    const shadows = await store.list();
-    return textResult(shadows.length ? shadows.map(describeShadow).join("\n") : "No Shadow Minds configured.");
-  });
+  return tool(
+    "list_shadows",
+    "List Shadows",
+    "List all valid globally configured Shadow Minds.",
+    Type.Object({}),
+    async () => {
+      const shadows = await store.list();
+      return textResult(
+        shadows.length ? shadows.map(describeShadow).join("\n") : "No Shadow Minds configured."
+      );
+    }
+  );
 }
 function createTool(store) {
-  return tool("create_shadow", "Create Shadow", "Create a global Shadow Mind definition after user confirmation.", Type.Object({ id: ID, ...SHADOW_FIELDS, prompt: Type.String() }), async (_id, params, _signal, _update, ctx) => {
-    const raw = params;
-    if (!await confirm(ctx, "Create Shadow Mind", `Create ${String(raw.id)} in the global registry?`)) return textResult("Cancelled.");
-    const shadow = await store.create(toDraft(raw));
-    return textResult(`Created ${describeShadow(shadow)}`);
-  });
+  return tool(
+    "create_shadow",
+    "Create Shadow",
+    "Create a global Shadow Mind definition after user confirmation.",
+    Type.Object({ id: ID, ...SHADOW_FIELDS, prompt: Type.String() }),
+    async (_id, params, _signal, _update, ctx) => {
+      const raw = params;
+      if (!await confirm(
+        ctx,
+        "Create Shadow Mind",
+        `Create ${String(raw.id)} in the global registry?`
+      ))
+        return textResult("Cancelled.");
+      const shadow = await store.create(toDraft(raw));
+      return textResult(`Created ${describeShadow(shadow)}`);
+    }
+  );
 }
 function updateTool(store) {
-  return tool("update_shadow", "Update Shadow", "Update a global Shadow Mind definition after user confirmation. The id is immutable.", Type.Object({ id: ID, ...SHADOW_FIELDS }), async (_id, params, _signal, _update, ctx) => {
-    const raw = params;
-    if (!await confirm(ctx, "Update Shadow Mind", `Apply changes to ${String(raw.id)}?`)) return textResult("Cancelled.");
-    const shadow = await store.update(String(raw.id), toPatch(raw));
-    return textResult(`Updated ${describeShadow(shadow)}`);
-  });
+  return tool(
+    "update_shadow",
+    "Update Shadow",
+    "Update a global Shadow Mind definition after user confirmation. The id is immutable.",
+    Type.Object({ id: ID, ...SHADOW_FIELDS }),
+    async (_id, params, _signal, _update, ctx) => {
+      const raw = params;
+      if (!await confirm(
+        ctx,
+        "Update Shadow Mind",
+        `Apply changes to ${String(raw.id)}?`
+      ))
+        return textResult("Cancelled.");
+      const shadow = await store.update(String(raw.id), toPatch(raw));
+      return textResult(`Updated ${describeShadow(shadow)}`);
+    }
+  );
 }
 function toggleTool(store, enabled) {
   const action = enabled ? "enable" : "disable";
-  return tool(`${action}_shadow`, `${enabled ? "Enable" : "Disable"} Shadow`, `${enabled ? "Enable" : "Disable"} a global Shadow Mind after user confirmation.`, Type.Object({ id: ID }), async (_id, params, _signal, _update, ctx) => {
-    const id = String(params.id);
-    if (!await confirm(ctx, `${enabled ? "Enable" : "Disable"} Shadow Mind`, `${action} ${id}?`)) return textResult("Cancelled.");
-    return textResult(describeShadow(await store.setEnabled(id, enabled)));
-  });
+  return tool(
+    `${action}_shadow`,
+    `${enabled ? "Enable" : "Disable"} Shadow`,
+    `${enabled ? "Enable" : "Disable"} a global Shadow Mind after user confirmation.`,
+    Type.Object({ id: ID }),
+    async (_id, params, _signal, _update, ctx) => {
+      const id = String(params.id);
+      if (!await confirm(
+        ctx,
+        `${enabled ? "Enable" : "Disable"} Shadow Mind`,
+        `${action} ${id}?`
+      ))
+        return textResult("Cancelled.");
+      return textResult(describeShadow(await store.setEnabled(id, enabled)));
+    }
+  );
 }
 function deleteTool(store) {
-  return tool("delete_shadow", "Delete Shadow", "Delete a Shadow Mind definition after user confirmation. Debug logs are retained.", Type.Object({ id: ID }), async (_id, params, _signal, _update, ctx) => {
-    const id = String(params.id);
-    if (!await confirm(ctx, "Delete Shadow Mind", `Delete ${id}? Its debug logs will be kept.`)) return textResult("Cancelled.");
-    await store.delete(id);
-    return textResult(`Deleted ${id}; logs were retained.`);
-  });
+  return tool(
+    "delete_shadow",
+    "Delete Shadow",
+    "Delete a Shadow Mind definition after user confirmation. Debug logs are retained.",
+    Type.Object({ id: ID }),
+    async (_id, params, _signal, _update, ctx) => {
+      const id = String(params.id);
+      if (!await confirm(
+        ctx,
+        "Delete Shadow Mind",
+        `Delete ${id}? Its debug logs will be kept.`
+      ))
+        return textResult("Cancelled.");
+      await store.delete(id);
+      return textResult(`Deleted ${id}; logs were retained.`);
+    }
+  );
 }
 function configReadTool(store) {
-  return tool("get_shadow_config", "Get Shadow Config", "Read the global Shadow Mind runtime configuration.", Type.Object({}), async () => textResult(await store.readConfig()));
+  return tool(
+    "get_shadow_config",
+    "Get Shadow Config",
+    "Read the global Shadow Mind runtime configuration.",
+    Type.Object({}),
+    async () => textResult(await store.readConfig())
+  );
 }
 function configWriteTool(store, getConfig) {
-  return tool("update_shadow_config", "Update Shadow Config", "Update global Shadow Mind runtime configuration after user confirmation.", Type.Object({
-    heartbeat_probability: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
-    max_parallel_shadows: Type.Optional(Type.Integer({ minimum: 1 })),
-    default_shadow_timeout_seconds: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
-    headless_drain_timeout_seconds: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
-    result_batch_window_ms: Type.Optional(Type.Integer({ minimum: 0 })),
-    default_shadow_model: Type.Optional(Type.String()),
-    default_thinking_level: Type.Optional(THINKING),
-    random_seed: Type.Optional(Type.Integer({ minimum: 0, maximum: 4294967295 }))
-  }), async (_id, params, _signal, _update, ctx) => {
-    const current = getConfig();
-    const raw = params;
-    const next = parseConfig({
-      heartbeat_probability: raw.heartbeat_probability ?? current.heartbeatProbability,
-      max_parallel_shadows: raw.max_parallel_shadows ?? current.maxParallelShadows,
-      default_shadow_timeout_seconds: raw.default_shadow_timeout_seconds ?? current.defaultShadowTimeoutSeconds,
-      headless_drain_timeout_seconds: raw.headless_drain_timeout_seconds ?? current.headlessDrainTimeoutSeconds,
-      result_batch_window_ms: raw.result_batch_window_ms ?? current.resultBatchWindowMs,
-      default_shadow_model: raw.default_shadow_model ?? current.defaultShadowModel,
-      default_thinking_level: raw.default_thinking_level ?? current.defaultThinkingLevel,
-      random_seed: raw.random_seed ?? current.randomSeed
-    });
-    if (!await confirm(ctx, "Update Shadow Config", `Apply this config?
-${JSON.stringify(next, null, 2)}`)) return textResult("Cancelled.");
-    await store.writeConfig(next);
-    return textResult("Shadow Mind config updated.");
-  });
+  return tool(
+    "update_shadow_config",
+    "Update Shadow Config",
+    "Update global Shadow Mind runtime configuration after user confirmation.",
+    Type.Object({
+      heartbeat_probability: Type.Optional(
+        Type.Number({ minimum: 0, maximum: 1 })
+      ),
+      max_parallel_shadows: Type.Optional(Type.Integer({ minimum: 1 })),
+      default_shadow_timeout_seconds: Type.Optional(
+        Type.Number({ exclusiveMinimum: 0 })
+      ),
+      headless_drain_timeout_seconds: Type.Optional(
+        Type.Number({ exclusiveMinimum: 0 })
+      ),
+      result_batch_window_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+      default_shadow_model: Type.Optional(Type.String()),
+      default_thinking_level: Type.Optional(THINKING),
+      random_seed: Type.Optional(
+        Type.Integer({ minimum: 0, maximum: 4294967295 })
+      )
+    }),
+    async (_id, params, _signal, _update, ctx) => {
+      const current = getConfig();
+      const raw = params;
+      const next = parseConfig({
+        heartbeat_probability: raw.heartbeat_probability ?? current.heartbeatProbability,
+        max_parallel_shadows: raw.max_parallel_shadows ?? current.maxParallelShadows,
+        default_shadow_timeout_seconds: raw.default_shadow_timeout_seconds ?? current.defaultShadowTimeoutSeconds,
+        headless_drain_timeout_seconds: raw.headless_drain_timeout_seconds ?? current.headlessDrainTimeoutSeconds,
+        result_batch_window_ms: raw.result_batch_window_ms ?? current.resultBatchWindowMs,
+        default_shadow_model: raw.default_shadow_model ?? current.defaultShadowModel,
+        default_thinking_level: raw.default_thinking_level ?? current.defaultThinkingLevel,
+        random_seed: raw.random_seed ?? current.randomSeed
+      });
+      if (!await confirm(
+        ctx,
+        "Update Shadow Config",
+        `Apply this config?
+${JSON.stringify(next, null, 2)}`
+      ))
+        return textResult("Cancelled.");
+      await store.writeConfig(next);
+      return textResult("Shadow Mind config updated.");
+    }
+  );
 }
 function tool(name, label, description, parameters, execute) {
   return { name, label, description, parameters, execute };
 }
 async function confirm(ctx, title, message) {
-  if (!ctx.hasUI) throw new Error("This write requires a UI confirmation, but no dialog-capable UI is available.");
+  if (!ctx.hasUI)
+    throw new Error(
+      "This write requires a UI confirmation, but no dialog-capable UI is available."
+    );
   return ctx.ui.confirm(title, message);
 }
 function textResult(text) {
@@ -7055,6 +7331,7 @@ function toPatch(raw) {
     enabled: raw.enabled,
     debug: raw.debug,
     activationProbability: raw.activation_probability,
+    trigger: raw.trigger,
     activeForModels: raw.active_for_models,
     runWithModel: raw.run_with_model,
     thinkingLevel: raw.thinking_level,
@@ -7125,16 +7402,34 @@ function createRandom(seed) {
 function shouldEvaluateHeartbeat(toolResults) {
   return toolResults.length > 0;
 }
+function shouldEvaluateFinalResponse(messages) {
+  const message = messages.at(-1);
+  if (!message || typeof message !== "object" || message.role !== "assistant")
+    return false;
+  const content = message.content;
+  if (typeof content === "string") return content.trim().length > 0;
+  return Array.isArray(content) && content.some((block) => {
+    if (!block || typeof block !== "object") return false;
+    const value = block;
+    return value.type === "text" && typeof value.text === "string" && value.text.trim().length > 0;
+  });
+}
 function decideHeartbeat(options) {
   const random = options.random ?? Math.random;
   const heartbeatRoll = random();
   if (heartbeatRoll >= options.heartbeatProbability || options.availableSlots <= 0) {
-    return { heartbeatRoll, activated: [], candidates: [], modelFiltered: [], runningExcluded: [] };
+    return {
+      heartbeatRoll,
+      activated: [],
+      candidates: [],
+      modelFiltered: [],
+      runningExcluded: []
+    };
   }
   const modelFiltered = [];
   const runningExcluded = [];
   const rolls = options.shadows.filter((shadow) => {
-    if (!shadow.enabled) return false;
+    if (!shadow.enabled || !hasTrigger(shadow, "heartbeat")) return false;
     if (options.activeShadowIds.has(shadow.id)) {
       runningExcluded.push(shadow.id);
       return false;
@@ -7145,20 +7440,55 @@ function decideHeartbeat(options) {
     }
     return true;
   }).map((shadow) => ({ shadow, roll: random() }));
-  const hits = rolls.filter(({ shadow, roll }) => roll < shadow.activationProbability);
-  const selected = sample(hits, Math.min(options.availableSlots, hits.length), random);
+  const hits = rolls.filter(
+    ({ shadow, roll }) => roll < shadow.activationProbability
+  );
+  const selected = sample(
+    hits,
+    Math.min(options.availableSlots, hits.length),
+    random
+  );
   const selectedIds = new Set(selected.map(({ shadow }) => shadow.id));
   return {
     heartbeatRoll,
     activated: selected,
-    candidates: rolls.map(({ shadow, roll }) => ({ shadowId: shadow.id, roll, selected: selectedIds.has(shadow.id) })),
+    candidates: rolls.map(({ shadow, roll }) => ({
+      shadowId: shadow.id,
+      roll,
+      selected: selectedIds.has(shadow.id)
+    })),
     modelFiltered,
     runningExcluded
   };
 }
+function decideFinalResponse(options) {
+  const modelFiltered = [];
+  const candidates = options.shadows.filter((shadow) => {
+    if (!shadow.enabled || !hasTrigger(shadow, "final_response"))
+      return false;
+    if (!matchesModel(shadow, options.mainModelId)) {
+      modelFiltered.push(shadow.id);
+      return false;
+    }
+    return true;
+  }).map((shadow) => ({ shadow, roll: 0 }));
+  return {
+    activated: candidates,
+    candidates: candidates.map(({ shadow, roll }) => ({
+      shadowId: shadow.id,
+      roll,
+      selected: true
+    })),
+    modelFiltered,
+    runningExcluded: []
+  };
+}
 function matchesModel(shadow, fullModelId) {
   return shadow.activeForModels.includes("*") || shadow.activeForModels.includes(fullModelId);
 }
+function hasTrigger(shadow, trigger) {
+  return shadow.trigger.includes(trigger);
+}
 function sample(values, count, random) {
   const copy = [...values];
   for (let index = copy.length - 1; index > 0; index -= 1) {
@@ -7209,8 +7539,70 @@ import {
   createAgentSession
 } from "@earendil-works/pi-coding-agent";
 
-// src/types.ts
-var DEFAULT_READ_TOOLS = ["read", "grep", "find", "ls"];
+// src/usage.ts
+function zeroUsage() {
+  return {
+    requests: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      total: 0
+    }
+  };
+}
+function addUsage(left, right) {
+  return {
+    requests: left.requests + right.requests,
+    input: left.input + right.input,
+    output: left.output + right.output,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite: left.cacheWrite + right.cacheWrite,
+    totalTokens: left.totalTokens + right.totalTokens,
+    cost: {
+      input: left.cost.input + right.cost.input,
+      output: left.cost.output + right.cost.output,
+      cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+      cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+      total: left.cost.total + right.cost.total
+    }
+  };
+}
+function formatUsageTokens(tokens) {
+  if (tokens < 1e3) return tokens.toLocaleString("en-US");
+  if (tokens < 999950) return `${formatCompact(tokens / 1e3)}k`;
+  return `${formatCompact(tokens / 1e6)}m`;
+}
+function formatUsageCost(cost) {
+  if (cost === 0) return "$0";
+  if (cost >= 0.01) return `$${cost.toFixed(2)}`;
+  if (cost >= 1e-3) return `$${cost.toFixed(3)}`;
+  return `$${cost.toFixed(4)}`;
+}
+function formatUsageSummary(usage) {
+  return `${usage.requests} requests \xB7 ${formatUsageTokens(usage.totalTokens)} tokens \xB7 API ${formatUsageCost(usage.cost.total)}`;
+}
+function formatUsageDetail(scope, usage) {
+  return [
+    `usage ${scope}`,
+    `${usage.requests} requests`,
+    `${formatUsageTokens(usage.totalTokens)} total`,
+    `${formatUsageTokens(usage.input)} input`,
+    `${formatUsageTokens(usage.output)} output`,
+    `${formatUsageTokens(usage.cacheRead)} cache read`,
+    `${formatUsageTokens(usage.cacheWrite)} cache write`,
+    `API ${formatUsageCost(usage.cost.total)}`
+  ].join(" \xB7 ");
+}
+function formatCompact(value) {
+  return Number(value.toFixed(1)).toString();
+}
 
 // src/protocol.ts
 var RUNTIME_PROTOCOL = `You are a Shadow Mind running beside the main agent.
@@ -7374,6 +7766,7 @@ function buildRunResult(options) {
   const { reason, error, durationMs, session, baseMessageCount, missingTools, thinkingLevel } = options;
   const ownMessages = session ? session.messages.slice(baseMessageCount) : [];
   const metrics = toolMetrics(ownMessages);
+  const usage = usageMetrics(ownMessages);
   return {
     reason,
     ...error !== void 0 ? { error } : {},
@@ -7381,6 +7774,7 @@ function buildRunResult(options) {
     toolNames: session?.getActiveToolNames() ?? [],
     missingTools,
     ...metrics,
+    usage,
     ...thinkingLevel !== void 0 ? { thinkingLevel } : {},
     sessionFile: session?.sessionFile
   };
@@ -7455,6 +7849,7 @@ var ShadowRunner = class {
         extensions: base.extensions.filter((extension) => !isSelfExtension(extension.resolvedPath))
       })
     });
+    await resourceLoader.reload();
     const reportTool = createReportTool((content) => {
       if (state.reported || controller.signal.aborted) return;
       state.reported = true;
@@ -7501,11 +7896,33 @@ function toolMetrics(messages) {
   }
   const toolStats = [...stats.values()].sort((a, b) => b.calls - a.calls);
   return {
-    toolCalls: toolStats.reduce((sum, stat2) => sum + stat2.calls, 0),
-    toolFailures: toolStats.reduce((sum, stat2) => sum + stat2.failures, 0),
+    toolCalls: toolStats.reduce((sum, stat3) => sum + stat3.calls, 0),
+    toolFailures: toolStats.reduce((sum, stat3) => sum + stat3.failures, 0),
     toolStats
   };
 }
+function usageMetrics(messages) {
+  let aggregate = zeroUsage();
+  for (const message of messages) {
+    if (message.role !== "assistant" || !message.usage) continue;
+    aggregate = addUsage(aggregate, {
+      requests: 1,
+      input: message.usage.input,
+      output: message.usage.output,
+      cacheRead: message.usage.cacheRead,
+      cacheWrite: message.usage.cacheWrite,
+      totalTokens: message.usage.totalTokens,
+      cost: {
+        input: message.usage.cost.input,
+        output: message.usage.cost.output,
+        cacheRead: message.usage.cost.cacheRead,
+        cacheWrite: message.usage.cost.cacheWrite,
+        total: message.usage.cost.total
+      }
+    });
+  }
+  return aggregate;
+}
 function createReportTool(onReport) {
   return {
     name: "report_to_main",
@@ -7566,7 +7983,7 @@ async function waitForSettled(options) {
   const pollMs = options.pollMs ?? 25;
   const quietMs = options.quietMs ?? 50;
   const now = options.now ?? Date.now;
-  const delay = options.delay ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  const delay2 = options.delay ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
   const started = now();
   let settledSince;
   while (now() - started < options.timeoutMs) {
@@ -7577,24 +7994,402 @@ async function waitForSettled(options) {
       settledSince = void 0;
     }
     const remaining = options.timeoutMs - (now() - started);
-    await delay(Math.min(pollMs, Math.max(1, remaining)));
+    await delay2(Math.min(pollMs, Math.max(1, remaining)));
   }
   return { settled: false, durationMs: now() - started };
 }
 
+// src/usage-store.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { mkdir as mkdir5, readFile as readFile5, rename as rename2, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname3, join as join6 } from "node:path";
+
+// src/usage-file-lock.ts
+import { randomUUID } from "node:crypto";
+import { mkdir as mkdir4, readFile as readFile4, rename, rm, stat as stat2, utimes, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join5 } from "node:path";
+var USAGE_LOCK_OWNER_FILE = "owner";
+var USAGE_LOCK_OPERATION_DIRECTORY = ".operation";
+async function acquireUsageFileLock(usagePath, timing = {}) {
+  const resolved = resolveTiming(timing);
+  const lockPath = `${usagePath}.lock`;
+  const owner = { token: randomUUID(), pid: process.pid };
+  while (true) {
+    try {
+      await mkdir4(lockPath);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      await recoverStaleUsageLock(lockPath, resolved);
+      await delay(resolved.retryMs);
+      continue;
+    }
+    try {
+      await writeOwner(lockPath, owner);
+    } catch (error) {
+      await rm(lockPath, { recursive: true, force: true }).catch(() => void 0);
+      throw error;
+    }
+    return startLease(lockPath, owner, resolved);
+  }
+}
+function startLease(lockPath, owner, timing) {
+  let stopped = false;
+  let heartbeat = Promise.resolve();
+  const timer = setInterval(() => {
+    heartbeat = heartbeat.then(async () => {
+      if (stopped) return;
+      const current = await readUsageLockState(lockPath);
+      if (!current || current.owner?.token !== owner.token) {
+        stopped = true;
+        return;
+      }
+      const now = /* @__PURE__ */ new Date();
+      await utimes(join5(lockPath, USAGE_LOCK_OWNER_FILE), now, now);
+    }).catch(() => void 0);
+  }, timing.heartbeatMs);
+  timer.unref();
+  return async () => {
+    stopped = true;
+    clearInterval(timer);
+    await heartbeat;
+    await releaseUsageLock(lockPath, owner.token, timing);
+  };
+}
+async function recoverStaleUsageLock(lockPath, timing) {
+  const observed = await readUsageLockState(lockPath);
+  if (!observed || !isRecoverableUsageLock(observed, timing.staleMs)) return;
+  const operationPath = join5(lockPath, USAGE_LOCK_OPERATION_DIRECTORY);
+  if (!await claimUsageLockOperation(operationPath, timing)) return;
+  try {
+    const current = await readUsageLockState(lockPath);
+    if (!current || !sameUsageLock(current, observed) || !isRecoverableUsageLock(current, timing.staleMs)) return;
+    const abandonedPath = `${lockPath}.${randomUUID()}.stale`;
+    try {
+      await rename(lockPath, abandonedPath);
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+    await rm(abandonedPath, { recursive: true, force: true });
+  } finally {
+    await rm(operationPath, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
+async function releaseUsageLock(lockPath, token, timing) {
+  const operationPath = join5(lockPath, USAGE_LOCK_OPERATION_DIRECTORY);
+  while (true) {
+    const observed = await readUsageLockState(lockPath);
+    if (!observed || observed.owner?.token !== token) return;
+    if (!await claimUsageLockOperation(operationPath, timing)) {
+      await delay(timing.retryMs);
+      continue;
+    }
+    try {
+      const current = await readUsageLockState(lockPath);
+      if (!current || current.owner?.token !== token) return;
+      const releasedPath = `${lockPath}.${token}.released`;
+      try {
+        await rename(lockPath, releasedPath);
+      } catch (error) {
+        if (error.code === "ENOENT") continue;
+        throw error;
+      }
+      await rm(releasedPath, { recursive: true, force: true });
+      return;
+    } finally {
+      await rm(operationPath, { recursive: true, force: true }).catch(() => void 0);
+    }
+  }
+}
+async function claimUsageLockOperation(operationPath, timing) {
+  const owner = { token: randomUUID(), pid: process.pid };
+  try {
+    await mkdir4(operationPath);
+    try {
+      await writeOwner(operationPath, owner);
+    } catch (error) {
+      await rm(operationPath, { recursive: true, force: true }).catch(() => void 0);
+      throw error;
+    }
+    return true;
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+  const observed = await readUsageLockState(operationPath);
+  if (!observed || !isRecoverableUsageLock(observed, timing.staleMs)) return false;
+  const abandonedPath = `${operationPath}.${randomUUID()}.stale`;
+  try {
+    await rename(operationPath, abandonedPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+  await rm(abandonedPath, { recursive: true, force: true });
+  return false;
+}
+async function writeOwner(path, owner) {
+  await writeFile3(join5(path, USAGE_LOCK_OWNER_FILE), JSON.stringify(owner), {
+    encoding: "utf8",
+    flag: "wx"
+  });
+}
+async function readUsageLockState(lockPath) {
+  let lock;
+  try {
+    lock = await stat2(lockPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  try {
+    const ownerPath = join5(lockPath, USAGE_LOCK_OWNER_FILE);
+    const [raw, ownerFile] = await Promise.all([readFile4(ownerPath, "utf8"), stat2(ownerPath)]);
+    return {
+      owner: parseOwner(raw),
+      mtimeMs: ownerFile.mtimeMs,
+      dev: lock.dev,
+      ino: lock.ino
+    };
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return { mtimeMs: lock.mtimeMs, dev: lock.dev, ino: lock.ino };
+  }
+}
+function parseOwner(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value.token !== "string" || !value.token || !Number.isSafeInteger(value.pid) || value.pid <= 0) return void 0;
+    return { token: value.token, pid: value.pid };
+  } catch {
+    return void 0;
+  }
+}
+function isRecoverableUsageLock(lock, staleMs) {
+  return Date.now() - lock.mtimeMs >= staleMs && !isProcessAlive(lock.owner?.pid);
+}
+function isProcessAlive(pid) {
+  if (pid === void 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== "ESRCH";
+  }
+}
+function sameUsageLock(left, right) {
+  return left.owner !== void 0 && right.owner !== void 0 ? left.owner.token === right.owner.token : left.owner === right.owner && left.dev === right.dev && left.ino === right.ino;
+}
+function resolveTiming(timing) {
+  return {
+    retryMs: timing.retryMs ?? 25,
+    staleMs: timing.staleMs ?? 3e4,
+    heartbeatMs: timing.heartbeatMs ?? 1e4
+  };
+}
+function delay(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+
+// src/usage-store.ts
+var USAGE_DOCUMENT_VERSION = 1;
+var UsageStore = class {
+  usagePath;
+  lifetime = zeroUsage();
+  pendingUsage = zeroUsage();
+  lastError;
+  initialization;
+  pendingWrite = Promise.resolve();
+  constructor(agentDir) {
+    this.usagePath = join6(agentDir, "shadow-minds", "usage.json");
+  }
+  initialize() {
+    this.initialization ??= this.load();
+    return this.initialization;
+  }
+  get current() {
+    return {
+      ...this.lifetime,
+      cost: { ...this.lifetime.cost }
+    };
+  }
+  get error() {
+    return this.lastError;
+  }
+  add(usage) {
+    this.lifetime = addUsage(this.lifetime, usage);
+    this.pendingUsage = addUsage(this.pendingUsage, usage);
+    return this.enqueueWrite();
+  }
+  async flush() {
+    await this.pendingWrite;
+    if (!isZeroUsage(this.pendingUsage)) await this.enqueueWrite();
+  }
+  enqueueWrite() {
+    this.pendingWrite = this.pendingWrite.then(
+      () => this.writePending(),
+      () => this.writePending()
+    ).then(
+      () => {
+        this.lastError = void 0;
+      },
+      (error) => {
+        this.lastError = error instanceof Error ? error.message : String(error);
+      }
+    );
+    return this.pendingWrite;
+  }
+  async load() {
+    try {
+      const raw = await readFile5(this.usagePath, "utf8");
+      this.lifetime = parseUsageDocument(JSON.parse(raw)).lifetime;
+      this.lastError = void 0;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        this.lifetime = zeroUsage();
+        this.lastError = void 0;
+        return;
+      }
+      this.lifetime = zeroUsage();
+      this.lastError = error instanceof Error ? error.message : String(error);
+    }
+  }
+  async writePending() {
+    const delta = this.pendingUsage;
+    if (isZeroUsage(delta)) return;
+    await mkdir5(dirname3(this.usagePath), { recursive: true });
+    const releaseLock = await acquireUsageFileLock(this.usagePath);
+    try {
+      const committed = addUsage(await readUsageLifetime(this.usagePath), delta);
+      await writeUsageDocument(this.usagePath, committed);
+      this.pendingUsage = subtractUsage(this.pendingUsage, delta);
+      this.lifetime = addUsage(committed, this.pendingUsage);
+    } finally {
+      await releaseLock();
+    }
+  }
+};
+function subtractUsage(left, right) {
+  return {
+    requests: left.requests - right.requests,
+    input: left.input - right.input,
+    output: left.output - right.output,
+    cacheRead: left.cacheRead - right.cacheRead,
+    cacheWrite: left.cacheWrite - right.cacheWrite,
+    totalTokens: left.totalTokens - right.totalTokens,
+    cost: {
+      input: left.cost.input - right.cost.input,
+      output: left.cost.output - right.cost.output,
+      cacheRead: left.cost.cacheRead - right.cost.cacheRead,
+      cacheWrite: left.cost.cacheWrite - right.cost.cacheWrite,
+      total: left.cost.total - right.cost.total
+    }
+  };
+}
+function isZeroUsage(usage) {
+  return usage.requests === 0 && usage.input === 0 && usage.output === 0 && usage.cacheRead === 0 && usage.cacheWrite === 0 && usage.totalTokens === 0 && usage.cost.input === 0 && usage.cost.output === 0 && usage.cost.cacheRead === 0 && usage.cost.cacheWrite === 0 && usage.cost.total === 0;
+}
+async function readUsageLifetime(usagePath) {
+  try {
+    const raw = await readFile5(usagePath, "utf8");
+    return parseUsageDocument(JSON.parse(raw)).lifetime;
+  } catch (error) {
+    if (error.code === "ENOENT") return zeroUsage();
+    throw error;
+  }
+}
+async function writeUsageDocument(usagePath, lifetime) {
+  const temporaryPath = `${usagePath}.${randomUUID2()}.tmp`;
+  try {
+    const document = { version: USAGE_DOCUMENT_VERSION, lifetime };
+    await writeFile4(temporaryPath, `${JSON.stringify(document, null, 2)}
+`, "utf8");
+    await rename2(temporaryPath, usagePath);
+  } finally {
+    await rm2(temporaryPath, { force: true }).catch(() => void 0);
+  }
+}
+function parseUsageDocument(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("usage must be a JSON object");
+  }
+  const value = input;
+  if (value.version !== USAGE_DOCUMENT_VERSION) throw new Error("usage version is unsupported");
+  return { version: USAGE_DOCUMENT_VERSION, lifetime: parseUsage(value.lifetime, "lifetime") };
+}
+function parseUsage(input, name) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error(`${name} must be an object`);
+  }
+  const value = input;
+  const cost = value.cost;
+  if (cost === null || typeof cost !== "object" || Array.isArray(cost)) {
+    throw new Error(`${name}.cost must be an object`);
+  }
+  const costValue = cost;
+  return {
+    requests: nonNegativeInteger2(value.requests, `${name}.requests`),
+    input: nonNegativeNumber(value.input, `${name}.input`),
+    output: nonNegativeNumber(value.output, `${name}.output`),
+    cacheRead: nonNegativeNumber(value.cacheRead, `${name}.cacheRead`),
+    cacheWrite: nonNegativeNumber(value.cacheWrite, `${name}.cacheWrite`),
+    totalTokens: nonNegativeNumber(value.totalTokens, `${name}.totalTokens`),
+    cost: {
+      input: nonNegativeNumber(costValue.input, `${name}.cost.input`),
+      output: nonNegativeNumber(costValue.output, `${name}.cost.output`),
+      cacheRead: nonNegativeNumber(costValue.cacheRead, `${name}.cost.cacheRead`),
+      cacheWrite: nonNegativeNumber(costValue.cacheWrite, `${name}.cost.cacheWrite`),
+      total: nonNegativeNumber(costValue.total, `${name}.cost.total`)
+    }
+  };
+}
+function nonNegativeNumber(value, name) {
+  if (!isFiniteNumber(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative finite number`);
+  }
+  return value;
+}
+function nonNegativeInteger2(value, name) {
+  const number = nonNegativeNumber(value, name);
+  if (!Number.isSafeInteger(number)) throw new Error(`${name} must be a non-negative safe integer`);
+  return number;
+}
+
 // src/runtime.ts
+var SESSION_TEARDOWN_TIMEOUT_MS = 1e3;
 var ShadowMindRuntime = class {
   constructor(pi) {
     this.pi = pi;
-    this.batcher = new ReportBatcher(this.configStore.current.resultBatchWindowMs, (reports) => this.deliverReports(reports));
+    this.batcher = new ReportBatcher(
+      this.configStore.current.resultBatchWindowMs,
+      (reports) => {
+        this.completionReview.invalidate();
+        void this.deliverReports(reports);
+      }
+    );
   }
   agentDir = getAgentDir();
   configStore = new ConfigStore(this.agentDir);
   registry = new ShadowRegistry(this.agentDir);
-  entityStore = new EntityStore(this.registry, this.configStore.configPath);
+  entityStore = new EntityStore(
+    this.registry,
+    this.configStore.configPath
+  );
   runner = new ShadowRunner();
+  usageStore = new UsageStore(this.agentDir);
   active = /* @__PURE__ */ new Map();
+  completionReview = new CompletionReview({
+    currentEpoch: () => this.epoch,
+    maxParallel: () => this.configStore.current.maxParallelShadows,
+    activeCount: () => this.active.size,
+    activeShadowIds: () => new Set([...this.active.values()].map(({ shadow }) => shadow.id)),
+    launch: (pending, review) => this.launchShadow({ ...pending, completionReview: review }),
+    deliver: (reports) => void this.deliverReports(reports)
+  });
   recentEvents = [];
+  recentRuns = [];
   batcher;
   sessionLifetime = new SessionLifetime();
   epoch = 0;
@@ -7603,10 +8398,16 @@ var ShadowMindRuntime = class {
   panelVisible = false;
   latestContext;
   diagnostics = [];
+  sessionUsage = zeroUsage();
   shadowCount = 0;
+  completedWithFinalText = false;
   random = Math.random;
   register() {
-    registerManagementTools(this.pi, this.entityStore, () => this.configStore.current);
+    registerManagementTools(
+      this.pi,
+      this.entityStore,
+      () => this.configStore.current
+    );
     this.registerEvents();
     this.registerUi();
   }
@@ -7615,16 +8416,23 @@ var ShadowMindRuntime = class {
       this.sessionLifetime.activate();
       this.latestContext = ctx;
       this.modelCalls = 0;
+      this.completedWithFinalText = false;
+      this.sessionUsage = zeroUsage();
+      this.recentRuns.length = 0;
       await this.configStore.initialize();
+      await this.usageStore.initialize();
       this.random = createRandom(this.configStore.current.randomSeed);
       await this.registry.initialize();
       await this.refresh(ctx);
-      this.record("session-config", { randomSeed: this.configStore.current.randomSeed ?? "random" });
+      this.record("session-config", {
+        randomSeed: this.configStore.current.randomSeed ?? "random"
+      });
       this.updateStatus(ctx);
     });
     this.pi.on("input", (event, ctx) => {
       this.latestContext = ctx;
       if (event.source === "extension") return;
+      this.completedWithFinalText = false;
       this.epoch += 1;
       this.abortAll("new-user-input");
     });
@@ -7635,11 +8443,29 @@ var ShadowMindRuntime = class {
     this.pi.on("turn_end", async (event, ctx) => {
       this.latestContext = ctx;
       if (!shouldEvaluateHeartbeat(event.toolResults)) {
-        this.record("heartbeat-skipped", { reason: "no-tool-activity", modelCalls: this.modelCalls });
+        this.record("heartbeat-skipped", {
+          reason: "no-tool-activity",
+          modelCalls: this.modelCalls
+        });
         return;
       }
       await this.onHeartbeat(ctx);
     });
+    this.pi.on("agent_end", (event, ctx) => {
+      this.latestContext = ctx;
+      this.completedWithFinalText = shouldEvaluateFinalResponse(event.messages);
+    });
+    this.pi.on("agent_settled", async (_event, ctx) => {
+      this.latestContext = ctx;
+      if (!this.completedWithFinalText) {
+        this.record("final-response-skipped", {
+          reason: "no-final-assistant-text"
+        });
+        return;
+      }
+      this.completedWithFinalText = false;
+      await this.onFinalResponse(ctx);
+    });
     this.pi.on("session_shutdown", async (event, ctx) => {
       this.latestContext = ctx;
       if (event.reason === "quit" && (ctx.mode === "print" || ctx.mode === "json")) {
@@ -7647,6 +8473,14 @@ var ShadowMindRuntime = class {
       }
       this.epoch += 1;
       this.abortAll("session-shutdown");
+      if (this.active.size > 0) {
+        const result = await waitForSettled({
+          timeoutMs: SESSION_TEARDOWN_TIMEOUT_MS,
+          isSettled: () => this.active.size === 0
+        });
+        if (!result.settled) this.active.clear();
+      }
+      await this.usageStore.flush();
       ctx.ui.setStatus("shadow-mind", void 0);
       ctx.ui.setWidget("shadow-mind-panel", void 0);
       this.sessionLifetime.deactivate();
@@ -7672,7 +8506,10 @@ var ShadowMindRuntime = class {
         }
         if (command === "status") {
           await this.refresh(ctx);
-          ctx.ui.notify(this.statusLines().join("\n"), this.diagnostics.length ? "warning" : "info");
+          ctx.ui.notify(
+            this.statusLines().join("\n"),
+            this.diagnostics.length ? "warning" : "info"
+          );
         } else if (command === "hide") {
           this.panelVisible = false;
           ctx.ui.setWidget("shadow-mind-panel", void 0);
@@ -7690,25 +8527,35 @@ var ShadowMindRuntime = class {
         this.setPaused(!this.paused, ctx);
       }
     });
-    this.pi.registerMessageRenderer("shadow-report", (message, _options, theme) => {
-      const content = typeof message.content === "string" ? message.content : "Shadow report";
-      const prefix = theme.fg("accent", "\u{1F419} shadow \xB7 ");
-      return new Text(`${prefix}${content}`, 0, 0);
-    });
+    this.pi.registerMessageRenderer(
+      "shadow-report",
+      (message, _options, theme) => {
+        const content = typeof message.content === "string" ? message.content : "Shadow report";
+        const prefix = theme.fg("accent", "\u{1F419} shadow \xB7 ");
+        return new Text(`${prefix}${content}`, 0, 0);
+      }
+    );
   }
   async onHeartbeat(ctx) {
-    await this.refresh(ctx);
+    const snapshot = await this.refresh(ctx);
     if (this.paused || !ctx.model) {
-      this.record("heartbeat-skipped", { reason: this.paused ? "paused" : "no-model", modelCalls: this.modelCalls });
+      this.record("heartbeat-skipped", {
+        reason: this.paused ? "paused" : "no-model",
+        modelCalls: this.modelCalls
+      });
       return;
     }
-    const snapshot = await this.registry.load();
     const fullModelId = `${ctx.model.provider}/${ctx.model.id}`;
     const decision = decideHeartbeat({
       heartbeatProbability: this.configStore.current.heartbeatProbability,
-      availableSlots: Math.max(0, this.configStore.current.maxParallelShadows - this.active.size),
+      availableSlots: Math.max(
+        0,
+        this.configStore.current.maxParallelShadows - this.active.size
+      ),
       shadows: snapshot.shadows,
-      activeShadowIds: new Set([...this.active.values()].map(({ shadow }) => shadow.id)),
+      activeShadowIds: new Set(
+        [...this.active.values()].map(({ shadow }) => shadow.id)
+      ),
       mainModelId: fullModelId,
       random: this.random
     });
@@ -7716,22 +8563,99 @@ var ShadowMindRuntime = class {
       modelCalls: this.modelCalls,
       roll: decision.heartbeatRoll,
       candidates: decision.candidates,
-      activated: decision.activated.map(({ shadow, roll }) => ({ id: shadow.id, roll })),
+      activated: decision.activated.map(({ shadow, roll }) => ({
+        id: shadow.id,
+        roll
+      })),
       ...decision.modelFiltered.length ? { modelFiltered: decision.modelFiltered } : {},
       ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {}
     });
     if (!decision.activated.length) return;
-    const context = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
-    const availableTools = new Set(this.pi.getAllTools().map((tool2) => tool2.name));
+    const context = buildSessionContext(
+      ctx.sessionManager.getEntries(),
+      ctx.sessionManager.getLeafId()
+    );
+    const availableTools = new Set(
+      this.pi.getAllTools().map((tool2) => tool2.name)
+    );
     for (const { shadow } of decision.activated) {
-      this.launchShadow(ctx, shadow, ctx.model, fullModelId, context, availableTools);
+      this.launchShadow({
+        ctx,
+        shadow,
+        mainModel: ctx.model,
+        fullModelId,
+        context,
+        availableTools
+      });
     }
   }
-  launchShadow(ctx, shadow, mainModel, fullModelId, context, availableTools) {
-    const runId = randomUUID();
-    const runEpoch = this.epoch;
+  async onFinalResponse(ctx) {
+    const request = this.completionReview.begin(this.epoch);
+    const snapshot = await this.refresh(ctx);
+    if (!this.completionReview.isCurrent(request)) {
+      this.record("final-response-skipped", { reason: "superseded" });
+      return;
+    }
+    if (this.paused || !ctx.model) {
+      this.completionReview.cancel(request);
+      this.record("final-response-skipped", {
+        reason: this.paused ? "paused" : "no-model"
+      });
+      return;
+    }
+    const mainModel = ctx.model;
+    const fullModelId = `${mainModel.provider}/${mainModel.id}`;
+    const decision = decideFinalResponse({
+      shadows: snapshot.shadows,
+      mainModelId: fullModelId
+    });
+    this.record("final-response", {
+      candidates: decision.candidates,
+      activated: decision.activated.map(({ shadow }) => shadow.id),
+      ...decision.modelFiltered.length ? { modelFiltered: decision.modelFiltered } : {},
+      ...decision.runningExcluded.length ? { runningExcluded: decision.runningExcluded } : {}
+    });
+    if (!decision.activated.length) {
+      this.completionReview.schedule(request, []);
+      return;
+    }
+    const context = buildSessionContext(
+      ctx.sessionManager.getEntries(),
+      ctx.sessionManager.getLeafId()
+    );
+    const availableTools = new Set(
+      this.pi.getAllTools().map((tool2) => tool2.name)
+    );
+    this.completionReview.schedule(
+      request,
+      decision.activated.map(({ shadow }) => ({
+        epoch: request.epoch,
+        shadowId: shadow.id,
+        ctx,
+        shadow,
+        mainModel,
+        fullModelId,
+        context,
+        availableTools
+      }))
+    );
+  }
+  launchShadow(options) {
+    const {
+      ctx,
+      shadow,
+      mainModel,
+      fullModelId,
+      context,
+      availableTools,
+      completionReview
+    } = options;
+    const runId = randomUUID3();
+    const runEpoch = options.epoch ?? this.epoch;
     const { tools, missing } = resolveShadowTools(shadow.tools, availableTools);
-    this.active.set(runId, { shadow, epoch: runEpoch });
+    const activeRun = { shadow, epoch: runEpoch };
+    if (completionReview) activeRun.completionReview = completionReview;
+    this.active.set(runId, activeRun);
     this.record("run-start", {
       runId,
       shadowId: shadow.id,
@@ -7747,15 +8671,22 @@ var ShadowMindRuntime = class {
       cwd: ctx.cwd,
       agentDir: this.agentDir,
       mainSystemPrompt: ctx.getSystemPrompt(),
+      // SAFETY: buildSessionContext returns Pi messages; ShadowRunner treats them as read-only records.
       messages: context.messages,
       mainModel,
       tools,
       resolveModel: (id) => resolveModel(ctx, id),
       modelAuthOk: (model) => ctx.modelRegistry.hasConfiguredAuth(model) || ctx.modelRegistry.isUsingOAuth(model),
       mainThinkingLevel: ctx.thinkingLevel,
-      onReport: (report) => this.acceptReport(report)
+      onReport: (report) => {
+        if (completionReview) completionReview.accept(report);
+        else this.acceptReport(report);
+      }
     }).then((result) => this.handleRunEnd(runId, shadow, result)).catch((error) => {
+      const activeRun2 = this.active.get(runId);
       this.active.delete(runId);
+      this.completionReview.slotAvailable();
+      this.completionReview.complete(activeRun2?.completionReview);
       this.record("run-end", {
         runId,
         shadowId: shadow.id,
@@ -7765,9 +8696,29 @@ var ShadowMindRuntime = class {
     });
   }
   handleRunEnd(runId, shadow, result) {
+    const activeRun = this.active.get(runId);
     this.active.delete(runId);
+    this.completionReview.slotAvailable();
+    const persisted = this.usageStore.add(result.usage);
+    if (activeRun?.epoch !== this.epoch) {
+      this.completionReview.complete(activeRun?.completionReview);
+      return;
+    }
+    this.sessionUsage = addUsage(this.sessionUsage, result.usage);
+    this.recentRuns.push({
+      shadowName: shadow.name,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      result
+    });
+    if (this.recentRuns.length > 5) this.recentRuns.shift();
     this.record("run-end", { runId, shadowId: shadow.id, ...result });
-    if (this.latestContext && this.sessionLifetime.isActive) this.updateStatus(this.latestContext);
+    if (this.latestContext && this.sessionLifetime.isActive)
+      this.updateStatus(this.latestContext);
+    this.completionReview.complete(activeRun.completionReview);
+    void persisted.then(() => {
+      if (this.latestContext && this.sessionLifetime.isActive)
+        this.updateStatus(this.latestContext);
+    });
   }
   acceptReport(report) {
     if (report.epoch !== this.epoch) return;
@@ -7777,15 +8728,26 @@ var ShadowMindRuntime = class {
     const current = reports.filter((report) => report.epoch === this.epoch);
     if (!current.length) return;
     const content = formatReportBatch(current);
-    this.record("report-delivered", { runIds: current.map((report) => report.runId), count: current.length });
+    this.record("report-delivered", {
+      runIds: current.map((report) => report.runId),
+      count: current.length
+    });
     const idle = this.latestContext?.isIdle() ?? true;
     this.sessionLifetime.run(() => {
-      this.pi.sendMessage({
-        customType: "shadow-report",
-        content,
-        display: true,
-        details: { reports: current.map(({ shadowId, runId }) => ({ shadowId, runId })) }
-      }, { triggerTurn: true, deliverAs: idle ? "followUp" : "steer" });
+      this.pi.sendMessage(
+        {
+          customType: "shadow-report",
+          content,
+          display: true,
+          details: {
+            reports: current.map(({ shadowId, runId }) => ({
+              shadowId,
+              runId
+            }))
+          }
+        },
+        { triggerTurn: true, deliverAs: idle ? "followUp" : "steer" }
+      );
     });
   }
   async refresh(ctx) {
@@ -7795,57 +8757,94 @@ var ShadowMindRuntime = class {
     this.shadowCount = registry.shadows.length;
     this.diagnostics = [
       ...config.error ? [`config: ${config.error}`] : [],
-      ...registry.diagnostics.map((item) => `${item.filePath}: ${item.message}`)
+      ...registry.diagnostics.map(
+        (item) => `${item.filePath}: ${item.message}`
+      )
     ];
     this.updateStatus(ctx);
+    return registry;
   }
   abortAll(reason) {
     this.runner.abortAll();
+    this.completionReview.invalidate();
     this.batcher.clear();
     this.record("runs-aborted", { reason, count: this.active.size });
   }
   async drainHeadless(ctx) {
     if (this.active.size === 0 && !this.batcher.hasPending) return;
     const timeoutMs = this.configStore.current.headlessDrainTimeoutSeconds * 1e3;
-    this.record("headless-drain-start", { timeoutMs, active: this.active.size });
+    this.record("headless-drain-start", {
+      timeoutMs,
+      active: this.active.size
+    });
     const result = await waitForSettled({
       timeoutMs,
       isSettled: () => this.active.size === 0 && !this.batcher.hasPending && ctx.isIdle() && !ctx.hasPendingMessages()
     });
-    this.record(result.settled ? "headless-drain-complete" : "headless-drain-timeout", {
-      durationMs: result.durationMs,
-      active: this.active.size
-    });
+    this.record(
+      result.settled ? "headless-drain-complete" : "headless-drain-timeout",
+      {
+        durationMs: result.durationMs,
+        active: this.active.size
+      }
+    );
     if (!result.settled) this.abortAll("headless-drain-timeout");
   }
   record(kind, data) {
-    const event = { at: (/* @__PURE__ */ new Date()).toISOString(), kind, epoch: this.epoch, data };
+    const event = {
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      kind,
+      epoch: this.epoch,
+      data
+    };
     this.recentEvents.push(event);
     if (this.recentEvents.length > 20) this.recentEvents.shift();
-    this.sessionLifetime.run(() => this.pi.appendEntry("shadow-mind-event", event));
+    this.sessionLifetime.run(
+      () => this.pi.appendEntry("shadow-mind-event", event)
+    );
   }
   setPaused(paused, ctx) {
     this.paused = paused;
     if (paused) this.abortAll("paused");
-    ctx.ui.notify(paused ? "Shadow Mind paused" : "Shadow Mind resumed", "info");
+    ctx.ui.notify(
+      paused ? "Shadow Mind paused" : "Shadow Mind resumed",
+      "info"
+    );
     this.updateStatus(ctx);
   }
   updateStatus(ctx) {
     this.sessionLifetime.run(() => {
-      const warning = this.diagnostics.length || this.hasRecentRunErrors() ? " !" : "";
-      ctx.ui.setStatus("shadow-mind", this.paused ? `\u{1F419} Paused${warning}` : `\u{1F419} ${this.active.size}${warning}`);
-      if (this.panelVisible) ctx.ui.setWidget("shadow-mind-panel", this.statusLines(), { placement: "aboveEditor" });
+      const diagnostics = this.usageStore.error ? [...this.diagnostics, `usage: ${this.usageStore.error}`] : this.diagnostics;
+      const warning = diagnostics.length || this.hasRecentRunErrors() ? " !" : "";
+      const usage = `${formatUsageTokens(this.sessionUsage.totalTokens)} \xB7 ${formatUsageCost(this.sessionUsage.cost.total)}`;
+      ctx.ui.setStatus(
+        "shadow-mind",
+        this.paused ? `\u{1F419} Paused \xB7 ${usage}${warning}` : `\u{1F419} ${this.active.size} \xB7 ${usage}${warning}`
+      );
+      if (this.panelVisible)
+        ctx.ui.setWidget("shadow-mind-panel", this.statusLines(), {
+          placement: "aboveEditor"
+        });
     });
   }
   hasRecentRunErrors() {
-    return this.recentEvents.slice(-3).some((event) => event.kind === "run-end" && (event.data?.reason === "error" || event.data?.reason === "timeout"));
+    return this.recentEvents.slice(-3).some(
+      (event) => event.kind === "run-end" && (event.data?.reason === "error" || event.data?.reason === "timeout")
+    );
   }
   statusLines() {
     const config = this.configStore.current;
+    const diagnostics = this.usageStore.error ? [...this.diagnostics, `usage: ${this.usageStore.error}`] : this.diagnostics;
     return [
       `\u{1F419} Shadow Mind \xB7 ${this.paused ? "paused" : "active"} \xB7 running ${this.active.size}/${config.maxParallelShadows}`,
       `heartbeat ${formatNumber(config.heartbeatProbability)} \xB7 batch ${config.resultBatchWindowMs}ms \xB7 timeout ${config.defaultShadowTimeoutSeconds}s \xB7 drain ${config.headlessDrainTimeoutSeconds}s \xB7 thinking ${config.defaultThinkingLevel}`,
       `definitions: ${this.shadowCount} valid \xB7 ${this.diagnostics.length} invalid`,
+      formatUsageDetail("session", this.sessionUsage),
+      `usage lifetime \xB7 ${formatUsageSummary(this.usageStore.current)}`,
+      ...this.recentRuns.slice(-3).map(
+        ({ shadowName, completedAt, result }) => `recent run \xB7 ${formatCompletedAt(completedAt)} \xB7 ${shadowName} \xB7 ${result.reason} \xB7 ${formatUsageSummary(result.usage)}`
+      ),
+      ...diagnostics.map((diagnostic) => `diagnostic: ${diagnostic}`),
       ...this.recentEvents.slice(-5).map((event) => {
         const failed = event.kind === "run-end" && (event.data?.reason === "error" || event.data?.reason === "timeout");
         const detail = failed ? ` ${event.data?.error ?? event.data?.reason}` : "";
@@ -7858,11 +8857,22 @@ var ShadowMindRuntime = class {
 function resolveModel(ctx, fullId) {
   const separator = fullId.indexOf("/");
   if (separator <= 0 || separator === fullId.length - 1) return void 0;
-  return ctx.modelRegistry.find(fullId.slice(0, separator), fullId.slice(separator + 1));
+  return ctx.modelRegistry.find(
+    fullId.slice(0, separator),
+    fullId.slice(separator + 1)
+  );
 }
 function formatNumber(value) {
   return Number(value.toFixed(3)).toString();
 }
+function formatCompletedAt(completedAt) {
+  return new Date(completedAt).toLocaleTimeString("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23"
+  });
+}
 
 // src/index.ts
 function shadowMindExtension(pi) {