@gobing-ai/spur 0.3.9 → 0.3.10

package/spur.js

@@ -60765,6 +60765,41 @@ var init_system_event_tap = __esm(() => {
   init_event_names();
 });
 
+// ../../packages/app/src/services/system-event-emitter.ts
+class SystemEventEmitter {
+  dao;
+  logger;
+  constructor(dao2, logger3) {
+    this.dao = dao2;
+    this.logger = logger3;
+  }
+  async emit(event2) {
+    const entry = systemEventCatalogEntry(event2.event);
+    if (!entry)
+      return;
+    try {
+      await this.dao.insert({
+        id: createId("sev"),
+        event_name: entry.name,
+        occurred_at: event2.at,
+        actor: extractSystemEventActor(event2),
+        payload_json: safeStringify(normalizeSystemEventPayload(entry, event2))
+      });
+      await this.dao.prune(SYSTEM_EVENTS_CAP);
+    } catch (error51) {
+      this.logger.warn("system_events emitter: persist failed", {
+        event: event2.event,
+        error: error51 instanceof Error ? `${error51.name}: ${error51.message}` : String(error51)
+      });
+    }
+  }
+}
+var init_system_event_emitter = __esm(() => {
+  init_src2();
+  init_event_names();
+  init_system_event_tap();
+});
+
 // ../../packages/app/src/services/task-check.ts
 import { dirname as dirname9, join as join9 } from "path";
 function isPlaceholderBody(body) {
@@ -62482,11 +62517,282 @@ var init_team_service = __esm(() => {
   init_planning_folders();
 });
 
+// ../../packages/app/src/services/token-ledger-service.ts
+import { closeSync as closeSync2, existsSync as existsSync5, fstatSync, openSync as openSync2, readSync } from "fs";
+import { join as join11 } from "path";
+function isSparseToolActivity(events2) {
+  return events2.length === 0 || !events2.some((e) => TOOL_ACTIVITY_TYPES.has(e.type));
+}
+function clampToolUseLimit(raw) {
+  if (raw === undefined || !Number.isFinite(raw) || raw <= 0) {
+    return TOKEN_LEDGER_DEFAULT_LIMIT;
+  }
+  return Math.min(Math.floor(raw), TOKEN_LEDGER_MAX_LIMIT);
+}
+function parseLedgerLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed)
+    return null;
+  try {
+    const obj = JSON.parse(trimmed);
+    if (typeof obj.ts !== "string" || typeof obj.session !== "string" || typeof obj.type !== "string") {
+      return null;
+    }
+    const event2 = {
+      ts: obj.ts,
+      session: obj.session,
+      type: obj.type
+    };
+    if (typeof obj.file === "string")
+      event2.file = obj.file;
+    if (typeof obj.summary === "string")
+      event2.summary = obj.summary;
+    if (typeof obj.tokens === "number" && Number.isFinite(obj.tokens) && obj.tokens >= 0) {
+      event2.tokens = obj.tokens;
+    }
+    if (typeof obj.action === "string")
+      event2.action = obj.action;
+    if (typeof obj.sessionId === "string")
+      event2.sessionId = obj.sessionId;
+    if (typeof obj.agent === "string")
+      event2.agent = obj.agent;
+    if (typeof obj.model === "string")
+      event2.model = obj.model;
+    if (obj.totals !== null && typeof obj.totals === "object") {
+      const t = obj.totals;
+      if (typeof t.reads === "number" && typeof t.writes === "number" && typeof t.tokens === "number") {
+        event2.totals = { reads: t.reads, writes: t.writes, tokens: t.tokens };
+      }
+    }
+    return event2;
+  } catch {
+    return null;
+  }
+}
+function tailTokenLedgerFile(filePath, limit, chunkSize = DEFAULT_CHUNK, before) {
+  if (!existsSync5(filePath)) {
+    return { events: [], truncated: false };
+  }
+  const target = limit + 1;
+  const fd = openSync2(filePath, "r");
+  try {
+    const { size } = fstatSync(fd);
+    if (size === 0)
+      return { events: [], truncated: false };
+    let pos = size;
+    let carry = "";
+    const events2 = [];
+    while (pos > 0 && events2.length < target) {
+      const n2 = Math.min(chunkSize, pos);
+      pos -= n2;
+      const buf = Buffer.alloc(n2);
+      readSync(fd, buf, 0, n2, pos);
+      const text4 = buf.toString("utf8") + carry;
+      const parts = text4.split(`
+`);
+      if (pos > 0) {
+        carry = parts.shift() ?? "";
+      } else {
+        carry = "";
+      }
+      for (let i2 = parts.length - 1;i2 >= 0; i2--) {
+        const evt = parseLedgerLine(parts[i2] ?? "");
+        if (!evt)
+          continue;
+        if (before !== undefined && evt.ts >= before)
+          continue;
+        events2.push(evt);
+        if (events2.length >= target)
+          break;
+      }
+    }
+    const truncated = events2.length > limit;
+    return {
+      events: events2.slice(0, limit),
+      truncated
+    };
+  } finally {
+    closeSync2(fd);
+  }
+}
+
+class TokenLedgerService {
+  ledgerPath;
+  chunkSize;
+  constructor(options) {
+    this.ledgerPath = options.ledgerPath ?? join11(options.cwd, TOKEN_LEDGER_RELATIVE_PATH);
+    this.chunkSize = options.chunkSize ?? DEFAULT_CHUNK;
+  }
+  get path() {
+    return this.ledgerPath;
+  }
+  snapshot(limitRawOrOpts, maybeBefore) {
+    let limitRaw;
+    let before;
+    if (typeof limitRawOrOpts === "object" && limitRawOrOpts !== null) {
+      limitRaw = limitRawOrOpts.limit;
+      before = limitRawOrOpts.before;
+    } else {
+      limitRaw = limitRawOrOpts;
+      before = maybeBefore;
+    }
+    if (before !== undefined && (typeof before !== "string" || before.length === 0)) {
+      before = undefined;
+    }
+    const limit = clampToolUseLimit(limitRaw);
+    const capturedAt = new Date().toISOString();
+    const { events: raw, truncated } = tailTokenLedgerFile(this.ledgerPath, limit, this.chunkSize, before);
+    const events2 = raw.map((e, seq) => ({ ...e, seq }));
+    const sparseToolActivity = isSparseToolActivity(events2);
+    const oldest = events2.length > 0 ? events2[events2.length - 1] : undefined;
+    const nextBefore = truncated && oldest ? oldest.ts : null;
+    return {
+      events: events2,
+      count: events2.length,
+      limit,
+      truncated,
+      path: this.ledgerPath,
+      capturedAt,
+      sparseToolActivity,
+      nextBefore
+    };
+  }
+}
+var TOOL_ACTIVITY_TYPES, TOKEN_LEDGER_DEFAULT_LIMIT = 200, TOKEN_LEDGER_MAX_LIMIT = 1000, TOKEN_LEDGER_RELATIVE_PATH, DEFAULT_CHUNK;
+var init_token_ledger_service = __esm(() => {
+  TOOL_ACTIVITY_TYPES = new Set(["read", "write", "bash", "grep", "glob"]);
+  TOKEN_LEDGER_RELATIVE_PATH = join11(".spur", "context", "token-ledger.jsonl");
+  DEFAULT_CHUNK = 64 * 1024;
+});
+
+// ../../packages/app/src/services/token-ledger-watcher.ts
+import { closeSync as closeSync3, existsSync as existsSync6, fstatSync as fstatSync2, openSync as openSync3, readSync as readSync2, watch } from "fs";
+
+class TokenLedgerWatcher {
+  ledgerPath;
+  debounceMs;
+  listeners = new Set;
+  watcher;
+  offset = 0;
+  debounceTimer;
+  started = false;
+  carry = "";
+  constructor(options) {
+    this.ledgerPath = options.ledgerPath;
+    this.debounceMs = options.debounceMs ?? 50;
+  }
+  start() {
+    if (this.started)
+      return;
+    this.started = true;
+    this.offset = this.currentSize();
+    try {
+      const target = existsSync6(this.ledgerPath) ? this.ledgerPath : this.parentDir();
+      this.watcher = watch(target, () => this.schedulePoll());
+    } catch {
+      this.watcher = undefined;
+    }
+  }
+  stop() {
+    this.started = false;
+    if (this.debounceTimer)
+      clearTimeout(this.debounceTimer);
+    this.debounceTimer = undefined;
+    try {
+      this.watcher?.close();
+    } catch {}
+    this.watcher = undefined;
+    this.listeners.clear();
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    if (!this.started)
+      this.start();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0)
+        this.stop();
+    };
+  }
+  get subscriberCount() {
+    return this.listeners.size;
+  }
+  parentDir() {
+    const idx = Math.max(this.ledgerPath.lastIndexOf("/"), this.ledgerPath.lastIndexOf("\\"));
+    return idx > 0 ? this.ledgerPath.slice(0, idx) : ".";
+  }
+  currentSize() {
+    if (!existsSync6(this.ledgerPath))
+      return 0;
+    try {
+      const fd = openSync3(this.ledgerPath, "r");
+      try {
+        return fstatSync2(fd).size;
+      } finally {
+        closeSync3(fd);
+      }
+    } catch {
+      return 0;
+    }
+  }
+  schedulePoll() {
+    if (this.debounceTimer)
+      clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = undefined;
+      this.pollNewBytes();
+    }, this.debounceMs);
+  }
+  pollNewBytes() {
+    if (!existsSync6(this.ledgerPath)) {
+      this.offset = 0;
+      this.carry = "";
+      return;
+    }
+    let size;
+    try {
+      const fd = openSync3(this.ledgerPath, "r");
+      try {
+        size = fstatSync2(fd).size;
+        if (size < this.offset) {
+          this.offset = 0;
+          this.carry = "";
+        }
+        if (size === this.offset)
+          return;
+        const len = size - this.offset;
+        const buf = Buffer.alloc(len);
+        readSync2(fd, buf, 0, len, this.offset);
+        this.offset = size;
+        const text4 = this.carry + buf.toString("utf8");
+        const parts = text4.split(`
+`);
+        this.carry = parts.pop() ?? "";
+        for (const line of parts) {
+          const evt = parseLedgerLine(line);
+          if (!evt)
+            continue;
+          for (const listener of this.listeners) {
+            try {
+              listener(evt);
+            } catch {}
+          }
+        }
+      } finally {
+        closeSync3(fd);
+      }
+    } catch {}
+  }
+}
+var init_token_ledger_watcher = __esm(() => {
+  init_token_ledger_service();
+});
+
 // ../../packages/app/src/workflow/actions/agent-run.ts
 import { execFile } from "child_process";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import { mkdir, writeFile } from "fs/promises";
-import { dirname as dirname10, isAbsolute as isAbsolute2, join as join11 } from "path";
+import { dirname as dirname10, isAbsolute as isAbsolute2, join as join12 } from "path";
 import { promisify as promisify3 } from "util";
 
 class AgentRunActionRunner {
@@ -62540,13 +62846,13 @@ class AgentRunActionRunner {
       const { exitCode: exitCode2, answer } = captured;
       const ok2 = exitCode2 === 0;
       if (answerFile !== undefined) {
-        const target = isAbsolute2(answerFile) ? answerFile : join11(cwd, answerFile);
+        const target = isAbsolute2(answerFile) ? answerFile : join12(cwd, answerFile);
         await mkdir(dirname10(target), { recursive: true });
         await writeFile(target, answer, "utf8");
       }
       if (ok2 && expectFile !== undefined) {
-        const target = isAbsolute2(expectFile) ? expectFile : join11(cwd, expectFile);
-        if (!existsSync5(target)) {
+        const target = isAbsolute2(expectFile) ? expectFile : join12(cwd, expectFile);
+        if (!existsSync7(target)) {
           return {
             ok: false,
             data: { exitCode: exitCode2, agent: agentLabel, answer },
@@ -62567,8 +62873,8 @@ class AgentRunActionRunner {
     const exitCode = await this.agentService.run(input, flags);
     const ok = exitCode === 0;
     if (ok && expectFile !== undefined) {
-      const target = isAbsolute2(expectFile) ? expectFile : join11(cwd, expectFile);
-      if (!existsSync5(target)) {
+      const target = isAbsolute2(expectFile) ? expectFile : join12(cwd, expectFile);
+      if (!existsSync7(target)) {
         return {
           ok: false,
           data: { exitCode, agent: agentLabel },
@@ -62645,7 +62951,7 @@ async function writePartialWorkArtifact(context4, agentLabel, model, captured, c
       ""
     ].join(`
 `);
-    const target = join11(cwd, ".spur", "run", `${context4.runId}-${context4.stateOrNodeId}-partial.md`);
+    const target = join12(cwd, ".spur", "run", `${context4.runId}-${context4.stateOrNodeId}-partial.md`);
     await mkdir(dirname10(target), { recursive: true });
     await writeFile(target, body, "utf8");
   } catch {}
@@ -63309,7 +63615,7 @@ var now = () => new Date().toISOString();
 // ../../packages/app/src/services/workflow-service.ts
 import { access as access2, lstat, readdir as readdir3, readFile as readFile2, realpath } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { join as join12, resolve as resolve3 } from "path";
+import { join as join13, resolve as resolve3 } from "path";
 function signalSubprocess(pid) {
   try {
     process.kill(-pid, "SIGTERM");
@@ -63513,7 +63819,7 @@ class WorkflowAppService {
   }
   async list(workflowPaths = [".spur/workflows/"]) {
     const projectRoot = this.ctx.cwd;
-    const globalRoot = join12(homedir3(), ".config", "spur");
+    const globalRoot = join13(homedir3(), ".config", "spur");
     const layers = [];
     const entries = [];
     const scannedPaths = new Set;
@@ -63849,6 +64155,7 @@ var isActionStarted = (e) => ("kind" in e) && ("node" in e), isActionFinished =
 // ../../packages/app/src/index.ts
 var exports_src2 = {};
 __export(exports_src2, {
+  tailTokenLedgerFile: () => tailTokenLedgerFile,
   systemEventCatalogEntry: () => systemEventCatalogEntry,
   resolvePlanningFolders: () => resolvePlanningFolders,
   renderTesting: () => renderTesting,
@@ -63861,6 +64168,7 @@ __export(exports_src2, {
   readVerdict: () => readVerdict,
   parseVerdict: () => parseVerdict,
   parsePsOutput: () => parsePsOutput,
+  parseLedgerLine: () => parseLedgerLine,
   parseEtimeToSeconds: () => parseEtimeToSeconds,
   normalizeSystemEventPayload: () => normalizeSystemEventPayload,
   hitlConfirmDefault: () => hitlConfirmDefault,
@@ -63868,14 +64176,21 @@ __export(exports_src2, {
   extractSystemEventActor: () => extractSystemEventActor,
   deriveVerdict: () => deriveVerdict,
   createPsProcessInspector: () => createPsProcessInspector,
+  clampToolUseLimit: () => clampToolUseLimit,
   bridgeEventBus: () => bridgeEventBus,
   WorkflowAppService: () => WorkflowAppService,
   UnsupportedProcessPlatformError: () => UnsupportedProcessPlatformError,
+  TokenLedgerWatcher: () => TokenLedgerWatcher,
+  TokenLedgerService: () => TokenLedgerService,
   TeamService: () => TeamService,
   TaskService: () => TaskService,
   TaskCheckService: () => TaskCheckService,
+  TOKEN_LEDGER_RELATIVE_PATH: () => TOKEN_LEDGER_RELATIVE_PATH,
+  TOKEN_LEDGER_MAX_LIMIT: () => TOKEN_LEDGER_MAX_LIMIT,
+  TOKEN_LEDGER_DEFAULT_LIMIT: () => TOKEN_LEDGER_DEFAULT_LIMIT,
   TASK_LIFECYCLE_PROFILE: () => TASK_LIFECYCLE_PROFILE,
   TASK_ACTION_COMMANDS: () => TASK_ACTION_COMMANDS,
+  SystemEventEmitter: () => SystemEventEmitter,
   SupervisorService: () => SupervisorService,
   SYSTEM_EVENT_STREAMED_NAMES: () => SYSTEM_EVENT_STREAMED_NAMES,
   SYSTEM_EVENT_PREFIXES: () => SYSTEM_EVENT_PREFIXES,
@@ -63927,11 +64242,14 @@ var init_src3 = __esm(() => {
   init_process_inspector();
   init_process_inventory_service();
   init_rule_service();
+  init_system_event_emitter();
   init_system_event_tap();
   init_task_check();
   init_task_record();
   init_task_service();
   init_team_service();
+  init_token_ledger_service();
+  init_token_ledger_watcher();
   init_workflow_service();
   init_agent_run();
   init_file_exists();
@@ -71378,13 +71696,38 @@ ${prompt}`;
 // src/commands/feature.ts
 init_src3();
 
+// src/planning-emitter.ts
+init_src3();
+init_src2();
+function makeWarnLogger(context4) {
+  return {
+    warn: (msg, data) => {
+      context4.output.error(`${msg}${data ? ` ${JSON.stringify(data)}` : ""}`);
+    }
+  };
+}
+function makePlanningEmitter(context4) {
+  let cached2;
+  const logger3 = makeWarnLogger(context4);
+  return {
+    async emit(event2) {
+      try {
+        cached2 ??= new SystemEventEmitter(new SystemEventDao(await context4.getDb()), logger3);
+        await cached2.emit(event2);
+      } catch (error51) {
+        context4.output.error(`system_events emitter: ${error51 instanceof Error ? error51.message : String(error51)}`);
+      }
+    }
+  };
+}
+
 // src/workflow/make-lifecycle-adapter.ts
 init_src3();
 init_loader();
 init_src2();
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 import { homedir as homedir4 } from "os";
-import { join as join13, resolve as resolve4 } from "path";
+import { join as join14, resolve as resolve4 } from "path";
 
 // src/workflow/resolve-spur-bin.ts
 import { basename as basename2 } from "path";
@@ -71402,23 +71745,23 @@ function resolveSpurBin() {
 }
 
 // src/workflow/make-lifecycle-adapter.ts
-var GLOBAL_CONFIG_DIR = join13(".config", "spur");
+var GLOBAL_CONFIG_DIR = join14(".config", "spur");
 function globalConfigRoot(context4) {
   const override = context4.env.SPUR_GLOBAL_RULES_DIR;
-  return override !== undefined && override.length > 0 ? resolve4(context4.cwd, override) : join13(homedir4(), GLOBAL_CONFIG_DIR);
+  return override !== undefined && override.length > 0 ? resolve4(context4.cwd, override) : join14(homedir4(), GLOBAL_CONFIG_DIR);
 }
 function resolveWorkflowPath(context4, profile) {
   const bundledRoot = bundledConfigRoot();
   if (bundledRoot !== null) {
-    const bundledPath = join13(bundledRoot, "workflows", `${profile.workflowName}.yaml`);
-    if (existsSync6(bundledPath))
+    const bundledPath = join14(bundledRoot, "workflows", `${profile.workflowName}.yaml`);
+    if (existsSync8(bundledPath))
       return bundledPath;
   }
-  const projectPath = join13(context4.cwd, ".spur", "workflows", `${profile.workflowName}.yaml`);
-  if (existsSync6(projectPath))
+  const projectPath = join14(context4.cwd, ".spur", "workflows", `${profile.workflowName}.yaml`);
+  if (existsSync8(projectPath))
     return projectPath;
-  const globalPath = join13(globalConfigRoot(context4), "workflows", `${profile.workflowName}.yaml`);
-  if (existsSync6(globalPath))
+  const globalPath = join14(globalConfigRoot(context4), "workflows", `${profile.workflowName}.yaml`);
+  if (existsSync8(globalPath))
     return globalPath;
   return null;
 }
@@ -71701,7 +72044,8 @@ async function makeService(context4, folderOverride) {
   const lifecycle = makeLifecycleAdapter(context4, FEATURE_LIFECYCLE_PROFILE);
   const writeService = new PlanningWriteService({
     fs: context4.fs,
-    ...lifecycle ? { lifecycle } : {}
+    ...lifecycle ? { lifecycle } : {},
+    emitter: makePlanningEmitter(context4)
   });
   return new FeatureService({ fs: context4.fs, writeService, featuresDir, tasksDir });
 }
@@ -71771,13 +72115,13 @@ init_loader();
 init_src2();
 init_dist10();
 import { homedir as homedir5 } from "os";
-import { join as join14, resolve as resolve5 } from "path";
+import { join as join15, resolve as resolve5 } from "path";
 
 // src/config.ts
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.3.9",
+  binaryVersion: "0.3.10",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
@@ -71828,8 +72172,8 @@ var SCAFFOLD_MANIFEST = [
 ];
 
 // src/commands/init.ts
-var GLOBAL_CONFIG_DIR2 = join14(".config", "spur");
-var GLOBAL_RULES_DIR2 = join14(GLOBAL_CONFIG_DIR2, "rules");
+var GLOBAL_CONFIG_DIR2 = join15(".config", "spur");
+var GLOBAL_RULES_DIR2 = join15(GLOBAL_CONFIG_DIR2, "rules");
 var GLOBAL_CONFIG_EXAMPLE = "config.example.yaml";
 var GLOBAL_CONFIG_FILE2 = "config.yaml";
 var INDEXED_CONTEXT_MARKER = "## Indexed context";
@@ -71856,7 +72200,7 @@ If \`.spur/context/\` is absent, proceed normally. Never block work on its absen
 `;
 function globalRulesRoot(context4) {
   const override = context4.env.SPUR_GLOBAL_RULES_DIR;
-  return override !== undefined && override.length > 0 ? resolve5(context4.cwd, override) : join14(homedir5(), GLOBAL_RULES_DIR2);
+  return override !== undefined && override.length > 0 ? resolve5(context4.cwd, override) : join15(homedir5(), GLOBAL_RULES_DIR2);
 }
 async function writeIfNew(context4, path9, content, force, result) {
   if (!force && await context4.fs.exists(path9)) {
@@ -71873,11 +72217,11 @@ async function seedGlobalRules(context4) {
   const target = globalRulesRoot(context4);
   let written = 0;
   for (const relPath of await listBundledRuleFiles()) {
-    const destination = join14(target, relPath);
+    const destination = join15(target, relPath);
     if (await context4.fs.exists(destination))
       continue;
-    await context4.fs.ensureDir(join14(target, ...relPath.split("/").slice(0, -1)));
-    await context4.fs.writeFile(destination, await context4.fs.readFile(join14(source, relPath)));
+    await context4.fs.ensureDir(join15(target, ...relPath.split("/").slice(0, -1)));
+    await context4.fs.writeFile(destination, await context4.fs.readFile(join15(source, relPath)));
     written += 1;
   }
   return written;
@@ -71887,20 +72231,20 @@ async function seedGlobalConfig(context4) {
   if (source === null)
     return 0;
   const globalOverride = context4.env.SPUR_GLOBAL_RULES_DIR;
-  const target = globalOverride !== undefined && globalOverride.length > 0 ? resolve5(context4.cwd, globalOverride) : join14(homedir5(), GLOBAL_CONFIG_DIR2);
+  const target = globalOverride !== undefined && globalOverride.length > 0 ? resolve5(context4.cwd, globalOverride) : join15(homedir5(), GLOBAL_CONFIG_DIR2);
   let written = 0;
   for (const relPath of listBundledConfigFiles()) {
     if (relPath === GLOBAL_CONFIG_EXAMPLE)
       continue;
-    const destination = join14(target, relPath);
+    const destination = join15(target, relPath);
     if (await context4.fs.exists(destination))
       continue;
-    await context4.fs.ensureDir(join14(target, ...relPath.split("/").slice(0, -1)));
-    await context4.fs.writeFile(destination, await context4.fs.readFile(join14(source, relPath)));
+    await context4.fs.ensureDir(join15(target, ...relPath.split("/").slice(0, -1)));
+    await context4.fs.writeFile(destination, await context4.fs.readFile(join15(source, relPath)));
     written += 1;
   }
-  const examplePath = join14(source, GLOBAL_CONFIG_EXAMPLE);
-  const globalConfigPath = join14(target, GLOBAL_CONFIG_FILE2);
+  const examplePath = join15(source, GLOBAL_CONFIG_EXAMPLE);
+  const globalConfigPath = join15(target, GLOBAL_CONFIG_FILE2);
   if (await context4.fs.exists(examplePath) && !await context4.fs.exists(globalConfigPath)) {
     await context4.fs.ensureDir(target);
     await context4.fs.writeFile(globalConfigPath, await context4.fs.readFile(examplePath));
@@ -71914,7 +72258,7 @@ function registerInitCommand(program2, context4) {
     const force = options.force === true;
     const minimal = options.minimal === true;
     const projectName = options.name ?? "default";
-    const configPath = join14(context4.cwd, CLI_CONFIG.configFile);
+    const configPath = join15(context4.cwd, CLI_CONFIG.configFile);
     if (!force && await context4.fs.exists(configPath)) {
       const message = `Already initialized: ${CLI_CONFIG.configFile}. Use --force to overwrite.`;
       context4.output.write(json3 ? toJson2({ ok: false, reason: "already-initialized", config: CLI_CONFIG.configFile }) : message);
@@ -71949,13 +72293,13 @@ function registerInitCommand(program2, context4) {
     ].join(`
 `)}
 `;
-    await context4.fs.ensureDir(join14(context4.cwd, CLI_CONFIG.configDir));
+    await context4.fs.ensureDir(join15(context4.cwd, CLI_CONFIG.configDir));
     await context4.fs.writeFile(configPath, configYaml);
     result.created.push(configPath);
-    const agentsDir = join14(context4.cwd, CLI_CONFIG.configDir, "agents");
+    const agentsDir = join15(context4.cwd, CLI_CONFIG.configDir, "agents");
     await context4.fs.ensureDir(agentsDir);
-    await writeIfNew(context4, join14(agentsDir, ".gitkeep"), "", force, result);
-    const gitignorePath = join14(context4.cwd, ".gitignore");
+    await writeIfNew(context4, join15(agentsDir, ".gitkeep"), "", force, result);
+    const gitignorePath = join15(context4.cwd, ".gitignore");
     const contextEntry = ".spur/context/";
     if (await context4.fs.exists(gitignorePath)) {
       const existing = await context4.fs.readFile(gitignorePath);
@@ -71975,20 +72319,20 @@ ${contextEntry}
       const configRoot = bundledConfigRoot();
       if (configRoot !== null) {
         for (const relPath of listBundledProjectSeedFiles()) {
-          const sourcePath = join14(configRoot, relPath);
+          const sourcePath = join15(configRoot, relPath);
           if (!await context4.fs.exists(sourcePath))
             continue;
-          const targetPath = join14(context4.cwd, CLI_CONFIG.configDir, relPath);
-          await context4.fs.ensureDir(join14(targetPath, ".."));
+          const targetPath = join15(context4.cwd, CLI_CONFIG.configDir, relPath);
+          await context4.fs.ensureDir(join15(targetPath, ".."));
           await writeIfNew(context4, targetPath, await context4.fs.readFile(sourcePath), force, result);
         }
         for (const entry of SCAFFOLD_MANIFEST) {
-          const sourcePath = join14(configRoot, entry.source);
+          const sourcePath = join15(configRoot, entry.source);
           if (!await context4.fs.exists(sourcePath))
             continue;
-          const baseDir = entry.root === true ? context4.cwd : join14(context4.cwd, CLI_CONFIG.configDir);
-          const targetPath = join14(baseDir, entry.target);
-          await context4.fs.ensureDir(join14(targetPath, ".."));
+          const baseDir = entry.root === true ? context4.cwd : join15(context4.cwd, CLI_CONFIG.configDir);
+          const targetPath = join15(baseDir, entry.target);
+          await context4.fs.ensureDir(join15(targetPath, ".."));
           const entryForce = entry.preserve === true ? false : force;
           let body = await context4.fs.readFile(sourcePath);
           if (entry.target === "AGENTS.md") {
@@ -71998,7 +72342,7 @@ ${contextEntry}
         }
       }
     }
-    const agentsMdPath = join14(context4.cwd, "AGENTS.md");
+    const agentsMdPath = join15(context4.cwd, "AGENTS.md");
     if (await context4.fs.exists(agentsMdPath)) {
       const existing = await context4.fs.readFile(agentsMdPath);
       if (!existing.includes(INDEXED_CONTEXT_MARKER)) {
@@ -72176,10 +72520,10 @@ function parseInterval2(raw) {
 
 // src/commands/migrate.ts
 init_src2();
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 function registerMigrateCommand(program2, context4) {
   program2.command("migrate").summary("apply CLI-owned schema migrations").option("--json", "Output machine-readable JSON").action(async (options) => {
-    const migrations = await loadSqlMigrations(join15(context4.cwd, "drizzle")).catch(() => {
+    const migrations = await loadSqlMigrations(join16(context4.cwd, "drizzle")).catch(() => {
       return;
     });
     const applied = await applyCliMigrations(await context4.getDb(), migrations);
@@ -72431,7 +72775,7 @@ function formatTraceDetail(detail) {
 
 // src/commands/serve.ts
 init_src();
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 
 // ../server/src/index.ts
 init_src();
@@ -72441,11 +72785,11 @@ init_src3();
 init_src();
 init_loader();
 init_src2();
-import { dirname as dirname12, isAbsolute as isAbsolute3, join as join18 } from "path";
+import { dirname as dirname12, isAbsolute as isAbsolute3, join as join19 } from "path";
 init_dist5();
 
 // ../server/src/bootstrap.ts
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 
 // ../../node_modules/.bun/radash@12.1.1/node_modules/radash/dist/esm/async.mjs
 var guard = (func, shouldGuard) => {
@@ -78549,23 +78893,128 @@ function parseLimit(raw2, fallback) {
 
 // ../server/src/modules/observability/index.ts
 init_src3();
+var ledgerWatcher;
+var watcherPath;
+function getLedgerWatcher(path9) {
+  if (!ledgerWatcher || watcherPath !== path9) {
+    ledgerWatcher?.stop();
+    ledgerWatcher = new TokenLedgerWatcher({ ledgerPath: path9 });
+    watcherPath = path9;
+    ledgerWatcher.start();
+  }
+  return ledgerWatcher;
+}
+function toolUseSsePayload(event2) {
+  return {
+    type: "tool-use",
+    occurredAt: event2.ts,
+    event: event2
+  };
+}
+function handleProcesses(ctx) {
+  return async (c3) => {
+    try {
+      const snapshot = await ctx.processInventory().snapshot();
+      return c3.json(snapshot);
+    } catch (err) {
+      if (err instanceof UnsupportedProcessPlatformError) {
+        return c3.json({ error: err.message, code: err.code }, 501);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return c3.json({ error: message }, 500);
+    }
+  };
+}
+function handleToolUseGet(ctx) {
+  return (c3) => {
+    try {
+      const limitParam = c3.req.query("limit");
+      let limitRaw;
+      if (limitParam !== undefined) {
+        const parsed = Number.parseInt(limitParam, 10);
+        if (!Number.isNaN(parsed))
+          limitRaw = parsed;
+      }
+      const before = c3.req.query("before") ?? undefined;
+      const limit = clampToolUseLimit(limitRaw);
+      const snapshot = ctx.tokenLedger().snapshot({ limit, before });
+      return c3.json(snapshot);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return c3.json({ error: message }, 500);
+    }
+  };
+}
+function handleToolUseStream(ctx) {
+  return (c3) => {
+    const closed = { current: false };
+    let heartbeatInterval;
+    let unsubscribe;
+    const signal = c3.req.raw.signal;
+    let closeController = () => {};
+    const teardown = () => {
+      if (closed.current)
+        return;
+      closed.current = true;
+      if (heartbeatInterval)
+        clearInterval(heartbeatInterval);
+      try {
+        unsubscribe?.();
+      } catch {}
+      signal.removeEventListener("abort", teardown);
+      closeController();
+    };
+    const stream = new ReadableStream({
+      start(controller) {
+        const encoder = new TextEncoder;
+        closeController = () => {
+          try {
+            controller.close();
+          } catch {}
+        };
+        if (signal.aborted) {
+          teardown();
+          return;
+        }
+        signal.addEventListener("abort", teardown);
+        heartbeatInterval = setInterval(sendSseKeepalive, 15000, closed, controller, encoder);
+        enqueueSseFrame(closed, controller, encoder, {
+          type: "connected",
+          occurredAt: new Date().toISOString()
+        });
+        try {
+          const path9 = ctx.tokenLedger().path;
+          const watcher = getLedgerWatcher(path9);
+          unsubscribe = watcher.subscribe((event2) => {
+            if (!enqueueSseFrame(closed, controller, encoder, toolUseSsePayload(event2)))
+              teardown();
+          });
+        } catch {
+          enqueueSseFrame(closed, controller, encoder, {
+            type: "error",
+            error: "ledger watch unavailable",
+            occurredAt: new Date().toISOString()
+          });
+        }
+      },
+      cancel() {
+        teardown();
+      }
+    });
+    return c3.newResponse(stream, 200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache"
+    });
+  };
+}
 var observabilityModule = {
   name: "observability",
   mount(app, ctx) {
     if (!ctx)
       return;
-    app.get("/api/observability/processes", async (c3) => {
-      try {
-        const snapshot = await ctx.processInventory().snapshot();
-        return c3.json(snapshot);
-      } catch (err) {
-        if (err instanceof UnsupportedProcessPlatformError) {
-          return c3.json({ error: err.message, code: err.code }, 501);
-        }
-        const message = err instanceof Error ? err.message : String(err);
-        return c3.json({ error: message }, 500);
-      }
-    });
+    app.get("/api/observability/processes", handleProcesses(ctx));
+    app.get("/api/observability/tool-use", handleToolUseGet(ctx));
+    app.get("/api/observability/tool-use/stream", handleToolUseStream(ctx));
   }
 };
 
@@ -80803,7 +81252,7 @@ function createApp(appRt, opts) {
     app.use("*", async (c3, next) => {
       const pathname = c3.req.path === "/" ? "/index.html" : c3.req.path;
       try {
-        const file2 = Bun.file(join16(webDistPath, pathname));
+        const file2 = Bun.file(join17(webDistPath, pathname));
         if (await file2.exists()) {
           const headers = new Headers({ "content-type": file2.type });
           return new Response(file2.stream(), { headers });
@@ -80816,7 +81265,7 @@ function createApp(appRt, opts) {
         return c3.json({ error: "Not Found" }, 404);
       }
       try {
-        const indexFile = Bun.file(join16(webDistPath, "index.html"));
+        const indexFile = Bun.file(join17(webDistPath, "index.html"));
         if (await indexFile.exists()) {
           return new Response(indexFile.stream(), {
             headers: { "content-type": "text/html; charset=utf-8" }
@@ -80837,7 +81286,7 @@ init_src3();
 init_src();
 init_src2();
 init_dist5();
-import { dirname as dirname11, join as join17 } from "path";
+import { dirname as dirname11, join as join18 } from "path";
 var NOOP_OUTPUT = { write: (_s) => {}, error: (_s) => {} };
 
 class LazyPlanningEventEmitter {
@@ -80872,7 +81321,7 @@ class NotConfiguredError extends Error {
 function createServerContext(appRt, options) {
   const cwd = options.cwd;
   const fs3 = options.fs;
-  const dbUrl = options.dbUrl ?? join17(cwd, DEFAULT_DATABASE_URL);
+  const dbUrl = options.dbUrl ?? join18(cwd, DEFAULT_DATABASE_URL);
   const eventsBus = options.eventsBus ?? appRt.events;
   const jobQueueEnabled = options.jobQueueEnabled ?? false;
   const folders = options.folders ?? DEFAULT_PLANNING_FOLDERS;
@@ -80890,6 +81339,7 @@ function createServerContext(appRt, options) {
   let teamSvc;
   let supervisorSvc;
   let processInventorySvc;
+  let tokenLedgerSvc;
   let agentSvc;
   let ruleSvc;
   let workflowSvc;
@@ -80980,6 +81430,12 @@ function createServerContext(appRt, options) {
       }
       return processInventorySvc;
     },
+    tokenLedger() {
+      if (!tokenLedgerSvc) {
+        tokenLedgerSvc = new TokenLedgerService({ cwd });
+      }
+      return tokenLedgerSvc;
+    },
     agentService() {
       agentSvc ??= new AgentService({
         cwd,
@@ -81159,15 +81615,15 @@ async function runTaskActionJob(ctx, env, payload, createAgentService = createTa
   }
 }
 async function resolveWebDistPath(configuredPath) {
-  const candidates = configuredPath && configuredPath.trim() !== "" ? [isAbsolute3(configuredPath) ? configuredPath : join18(process.cwd(), configuredPath)] : [
-    join18(process.cwd(), "dist/web"),
-    join18(import.meta.dir, "web"),
-    join18(dirname12(process.execPath), "web"),
-    join18(dirname12(process.execPath), "../web"),
-    join18(import.meta.dir, "../../../dist/web")
+  const candidates = configuredPath && configuredPath.trim() !== "" ? [isAbsolute3(configuredPath) ? configuredPath : join19(process.cwd(), configuredPath)] : [
+    join19(process.cwd(), "dist/web"),
+    join19(import.meta.dir, "web"),
+    join19(dirname12(process.execPath), "web"),
+    join19(dirname12(process.execPath), "../web"),
+    join19(import.meta.dir, "../../../dist/web")
   ];
   for (const candidate of candidates) {
-    if (await Bun.file(join18(candidate, "index.html")).exists()) {
+    if (await Bun.file(join19(candidate, "index.html")).exists()) {
       return candidate;
     }
   }
@@ -81295,7 +81751,7 @@ if (false) {}
 
 // src/commands/serve.ts
 function resolveServeDbUrl(cwd, env, configuredUrl) {
-  return env.DATABASE_URL === undefined ? join19(cwd, DEFAULT_DATABASE_URL) : configuredUrl;
+  return env.DATABASE_URL === undefined ? join20(cwd, DEFAULT_DATABASE_URL) : configuredUrl;
 }
 function registerServeCommand(program2, context4) {
   program2.command("serve").summary("start the Spur web server (local fallback)").option("--port <n>", "Server port (env: PORT, default: 3000)", parseInt).option("--host <addr>", "Bind address (env: HOST, default: localhost)").option("--no-open", "Skip opening the browser").option("--cwd <path>", "Working directory", context4.cwd).option("--json", "Output { port, url, pid } and exit").action(async (options) => {
@@ -81334,7 +81790,7 @@ function registerServeCommand(program2, context4) {
 }
 
 // src/commands/status.ts
-import { join as join20 } from "path";
+import { join as join21 } from "path";
 
 // src/errors.ts
 class CommandError extends Error {
@@ -81405,8 +81861,8 @@ function registerStatusCommand(program2, context4) {
 }
 async function runStatusCore(path9, options, context4) {
   const [packageJsonExists, spurConfigExists, git, agentSpecs] = await Promise.all([
-    context4.fs.exists(join20(context4.cwd, "package.json")),
-    context4.fs.exists(join20(context4.cwd, ".spur", "config.yaml")),
+    context4.fs.exists(join21(context4.cwd, "package.json")),
+    context4.fs.exists(join21(context4.cwd, ".spur", "config.yaml")),
     gitContext(context4.cwd),
     listAgentSpecIds(context4)
   ]);
@@ -81434,14 +81890,14 @@ async function runStatusCore(path9, options, context4) {
   return status.ok ? 0 : 1;
 }
 async function listAgentSpecIds(context4) {
-  const dir = join20(context4.cwd, ".spur", "agents");
+  const dir = join21(context4.cwd, ".spur", "agents");
   if (!await context4.fs.exists(dir))
     return [];
   const entries = await context4.fs.readDir(dir);
   return entries.filter((entry) => entry.endsWith(".yaml") || entry.endsWith(".yml")).map((entry) => entry.replace(/\.ya?ml$/, "")).sort();
 }
 async function readTargetStatus(context4, targetPath) {
-  const resolved = join20(context4.cwd, targetPath);
+  const resolved = join21(context4.cwd, targetPath);
   const stat2 = await context4.fs.stat(resolved);
   if (stat2 === null)
     throw new CommandError(`status failed: path does not exist at ${resolved}`);
@@ -81452,8 +81908,8 @@ async function readTargetStatus(context4, targetPath) {
 init_src3();
 init_loader();
 init_src2();
-import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
-import { join as join21 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { join as join22 } from "path";
 // schemas/section-matrix.schema.json
 var section_matrix_schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
@@ -82308,7 +82764,8 @@ async function makeService2(context4, folderOverride, noLifecycle = false) {
   const lifecycle = noLifecycle ? undefined : makeLifecycleAdapter(context4, TASK_LIFECYCLE_PROFILE);
   const writeService = new PlanningWriteService({
     fs: context4.fs,
-    ...lifecycle ? { lifecycle } : {}
+    ...lifecycle ? { lifecycle } : {},
+    emitter: makePlanningEmitter(context4)
   });
   return new TaskService({
     fs: context4.fs,
@@ -82327,16 +82784,16 @@ function loadTemplateContent(projectRoot, variant) {
     return templateContentCache.get(variant);
   if (templateMissSet.has(variant))
     return;
-  const localPath = join21(projectRoot, ".spur", "tasks", "templates", `${variant}.md`);
-  if (existsSync7(localPath)) {
+  const localPath = join22(projectRoot, ".spur", "tasks", "templates", `${variant}.md`);
+  if (existsSync9(localPath)) {
     const content = readFileSync8(localPath, "utf8");
     templateContentCache.set(variant, content);
     return content;
   }
   const root = bundledConfigRoot();
   if (root !== null) {
-    const templatePath = join21(root, "templates", "task", `${variant}.md`);
-    if (existsSync7(templatePath)) {
+    const templatePath = join22(root, "templates", "task", `${variant}.md`);
+    if (existsSync9(templatePath)) {
       const content = readFileSync8(templatePath, "utf8");
       templateContentCache.set(variant, content);
       return content;
@@ -82351,14 +82808,14 @@ function loadTemplateBodies(projectRoot, variant) {
   if (cached2 !== undefined)
     return cached2;
   let bodies = {};
-  const localPath = join21(projectRoot, ".spur", "tasks", "templates", `${variant}.md`);
-  if (existsSync7(localPath)) {
+  const localPath = join22(projectRoot, ".spur", "tasks", "templates", `${variant}.md`);
+  if (existsSync9(localPath)) {
     bodies = extractTemplateBodies(readFileSync8(localPath, "utf8"));
   } else {
     const root = bundledConfigRoot();
     if (root !== null) {
-      const templatePath = join21(root, "templates", "task", `${variant}.md`);
-      if (existsSync7(templatePath)) {
+      const templatePath = join22(root, "templates", "task", `${variant}.md`);
+      if (existsSync9(templatePath)) {
         bodies = extractTemplateBodies(readFileSync8(templatePath, "utf8"));
       }
     }
@@ -82392,8 +82849,8 @@ async function loadSectionMatrix(projectRoot) {
   return promise2;
 }
 async function loadSectionMatrixUncached(projectRoot) {
-  const localPath = join21(projectRoot, ".spur", "tasks", "section-matrix.yaml");
-  if (existsSync7(localPath)) {
+  const localPath = join22(projectRoot, ".spur", "tasks", "section-matrix.yaml");
+  if (existsSync9(localPath)) {
     const data = await loadStructuredSpurConfig(localPath, {
       validateJsonSchema: true,
       embeddedSchemas: EMBEDDED_SPUR_SCHEMAS
@@ -82402,8 +82859,8 @@ async function loadSectionMatrixUncached(projectRoot) {
   }
   const root = bundledConfigRoot();
   if (root !== null) {
-    const matrixPath = join21(root, "tasks", "section-matrix.yaml");
-    if (existsSync7(matrixPath)) {
+    const matrixPath = join22(root, "tasks", "section-matrix.yaml");
+    if (existsSync9(matrixPath)) {
       const data = await loadStructuredSpurConfig(matrixPath, {
         validateJsonSchema: true,
         embeddedSchemas: EMBEDDED_SPUR_SCHEMAS
@@ -82848,7 +83305,7 @@ init_src3();
 init_src();
 init_src2();
 init_dist5();
-import { dirname as dirname13, join as join22, resolve as resolve7 } from "path";
+import { dirname as dirname13, join as join23, resolve as resolve7 } from "path";
 import { isatty as isatty4 } from "tty";
 
 // ../../node_modules/.bun/@clack+core@1.4.1/node_modules/@clack/core/dist/index.mjs
@@ -84262,7 +84719,7 @@ function createCliContext(options) {
 function noopSetExitCode(_code) {}
 async function createMigratedDbAdapter(cwd = process.cwd(), env = process.env, dbUrl) {
   const config4 = buildConfigFromEnv(env);
-  const configuredUrl = env.DATABASE_URL === undefined ? join22(cwd, DEFAULT_DATABASE_URL) : config4.database.url;
+  const configuredUrl = env.DATABASE_URL === undefined ? join23(cwd, DEFAULT_DATABASE_URL) : config4.database.url;
   const url2 = dbUrl ?? configuredUrl;
   if (url2 !== IN_MEMORY_DATABASE_URL) {
     await createNodeFileSystem3().ensureDir(dirname13(url2));