@geravant/sinain 1.0.19 → 1.2.0

package/sinain-core/src/agent/loop.ts

@@ -0,0 +1,404 @@
+import { EventEmitter } from "node:events";
+import type { FeedBuffer } from "../buffers/feed-buffer.js";
+import type { SenseBuffer } from "../buffers/sense-buffer.js";
+import type { AgentConfig, AgentEntry, ContextWindow, EscalationMode, ContextRichness, RecorderStatus } from "../types.js";
+import type { Profiler } from "../profiler.js";
+import { buildContextWindow } from "./context-window.js";
+import { analyzeContext } from "./analyzer.js";
+import { writeSituationMd } from "./situation-writer.js";
+import { calculateEscalationScore } from "../escalation/scorer.js";
+import { log, warn, error, debug } from "../log.js";
+import type { TraitEngine, TraitSelection } from "./traits.js";
+import { writeTraitLog } from "./traits.js";
+
+const TAG = "agent";
+
+export interface AgentLoopDeps {
+  feedBuffer: FeedBuffer;
+  senseBuffer: SenseBuffer;
+  agentConfig: AgentConfig;
+  escalationMode: EscalationMode;
+  situationMdPath: string;
+  /** Called after analysis with digest + context for escalation check. */
+  onAnalysis: (entry: AgentEntry, contextWindow: ContextWindow) => void;
+  /** Called to broadcast HUD line to overlay. */
+  onHudUpdate: (text: string) => void;
+  /** Optional: tracer to record spans. */
+  onTraceStart?: (tickId: number) => TraceContext | null;
+  /** Optional: get current recorder status for prompt injection. */
+  getRecorderStatus?: () => RecorderStatus | null;
+  /** Optional: profiler for metrics collection. */
+  profiler?: Profiler;
+  /** Called after each successful SITUATION.md write with the content string. */
+  onSituationUpdate?: (content: string) => void;
+  /** Optional trait engine for personality voice selection. */
+  traitEngine?: TraitEngine;
+  /** Directory to write per-day trait log JSONL files. */
+  traitLogDir?: string;
+}
+
+export interface TraceContext {
+  startSpan(name: string): void;
+  endSpan(attrs?: Record<string, unknown>): void;
+  finish(metrics: Record<string, unknown>): void;
+}
+
+/** Map escalation mode to context richness. */
+function modeToRichness(mode: EscalationMode): ContextRichness {
+  switch (mode) {
+    case "selective": return "lean";
+    case "focus": return "standard";
+    case "rich": return "rich";
+    default: return "standard";
+  }
+}
+
+/**
+ * Event-driven agent analysis loop.
+ *
+ * Replaces relay's setInterval(agentTick, 30000) + debounce with:
+ *   - context:sense or context:audio event → debounce 3s → run analysis
+ *   - Max interval 30s (forced tick if no events)
+ *   - Cooldown 10s (don't re-analyze within 10s of last run)
+ *
+ * This cuts worst-case latency from ~60s to ~15s.
+ */
+export class AgentLoop extends EventEmitter {
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private maxIntervalTimer: ReturnType<typeof setInterval> | null = null;
+  private lastRunTs = 0;
+  private running = false;
+  private started = false;
+
+  private lastPushedHud = "";
+  private agentNextId = 1;
+  private agentBuffer: AgentEntry[] = [];
+  private latestDigest: AgentEntry | null = null;
+  private lastTickFeedVersion = 0;
+  private lastTickSenseVersion = 0;
+
+  private stats = {
+    totalCalls: 0,
+    totalTokensIn: 0,
+    totalTokensOut: 0,
+    lastAnalysisTs: 0,
+    idleSkips: 0,
+    parseSuccesses: 0,
+    parseFailures: 0,
+    consecutiveIdenticalHud: 0,
+    hudChanges: 0,
+  };
+
+  constructor(private deps: AgentLoopDeps) {
+    super();
+  }
+
+  /** Start the agent loop. */
+  start(): void {
+    if (this.started) return;
+    if (!this.deps.agentConfig.enabled || !this.deps.agentConfig.openrouterApiKey) {
+      if (this.deps.agentConfig.enabled) {
+        warn(TAG, "AGENT_ENABLED=true but OPENROUTER_API_KEY not set \u2014 agent disabled");
+      }
+      return;
+    }
+
+    this.started = true;
+    // Max interval: forced tick every maxIntervalMs even if no events
+    this.maxIntervalTimer = setInterval(() => {
+      if (!this.debounceTimer) {
+        this.run().catch(err => error(TAG, "max-interval tick error:", err.message));
+      }
+    }, this.deps.agentConfig.maxIntervalMs);
+
+    log(TAG, `loop started (debounce=${this.deps.agentConfig.debounceMs}ms, max=${this.deps.agentConfig.maxIntervalMs}ms, cooldown=${this.deps.agentConfig.cooldownMs}ms, model=${this.deps.agentConfig.model})`);
+  }
+
+  /** Stop the agent loop. */
+  stop(): void {
+    if (!this.started) return;
+    this.started = false;
+    if (this.debounceTimer) { clearTimeout(this.debounceTimer); this.debounceTimer = null; }
+    if (this.maxIntervalTimer) { clearInterval(this.maxIntervalTimer); this.maxIntervalTimer = null; }
+    log(TAG, "loop stopped");
+  }
+
+  /**
+   * Signal that new context is available.
+   * Called by sense POST handler and transcription callback.
+   * Triggers debounced analysis.
+   */
+  onNewContext(): void {
+    if (!this.started) return;
+
+    // Debounce: wait N ms after last event before running
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this.run().catch(err => error(TAG, "debounce tick error:", err.message));
+    }, this.deps.agentConfig.debounceMs);
+  }
+
+  /** Get agent results history (newest first). */
+  getHistory(limit = 10): AgentEntry[] {
+    return this.agentBuffer.slice(-limit).reverse();
+  }
+
+  /** Get latest digest. */
+  getDigest(): AgentEntry | null {
+    return this.latestDigest;
+  }
+
+  /** Get context window for debugging. */
+  getContext(): ContextWindow {
+    const richness = modeToRichness(this.deps.escalationMode);
+    return buildContextWindow(
+      this.deps.feedBuffer,
+      this.deps.senseBuffer,
+      richness,
+      this.deps.agentConfig.maxAgeMs,
+    );
+  }
+
+  /** Get config (safe — no API key). */
+  getConfig(): Record<string, unknown> {
+    const { openrouterApiKey, ...safe } = this.deps.agentConfig;
+    return { ...safe, hasApiKey: !!openrouterApiKey, escalationMode: this.deps.escalationMode };
+  }
+
+  /** Get stats for /health. */
+  getStats(): Record<string, unknown> {
+    const costPerToken = { in: 0.075 / 1_000_000, out: 0.3 / 1_000_000 };
+    const estimatedCost =
+      this.stats.totalTokensIn * costPerToken.in +
+      this.stats.totalTokensOut * costPerToken.out;
+
+    return {
+      enabled: this.deps.agentConfig.enabled,
+      lastAnalysis: this.stats.lastAnalysisTs || null,
+      lastDigest: this.latestDigest?.digest?.slice(0, 200) || null,
+      totalCalls: this.stats.totalCalls,
+      totalTokens: { in: this.stats.totalTokensIn, out: this.stats.totalTokensOut },
+      estimatedCost: Math.round(estimatedCost * 1000000) / 1000000,
+      model: this.deps.agentConfig.model,
+      idleSkips: this.stats.idleSkips,
+      parseSuccessRate: this.stats.parseSuccesses + this.stats.parseFailures > 0
+        ? Math.round((this.stats.parseSuccesses / (this.stats.parseSuccesses + this.stats.parseFailures)) * 100)
+        : null,
+      hudChangeRate: this.stats.hudChanges,
+      consecutiveIdenticalHud: this.stats.consecutiveIdenticalHud,
+      debounceMs: this.deps.agentConfig.debounceMs,
+      fallbackModels: this.deps.agentConfig.fallbackModels,
+    };
+  }
+
+  /** Update config at runtime. */
+  updateConfig(updates: Record<string, unknown>): void {
+    const c = this.deps.agentConfig;
+    if (updates.enabled !== undefined) c.enabled = !!updates.enabled;
+    if (updates.model !== undefined) c.model = String(updates.model);
+    if (updates.maxTokens !== undefined) c.maxTokens = Math.max(100, parseInt(String(updates.maxTokens)));
+    if (updates.temperature !== undefined) c.temperature = parseFloat(String(updates.temperature));
+    if (updates.pushToFeed !== undefined) c.pushToFeed = !!updates.pushToFeed;
+    if (updates.debounceMs !== undefined) c.debounceMs = Math.max(1000, parseInt(String(updates.debounceMs)));
+    if (updates.maxIntervalMs !== undefined) c.maxIntervalMs = Math.max(5000, parseInt(String(updates.maxIntervalMs)));
+    if (updates.cooldownMs !== undefined) c.cooldownMs = Math.max(3000, parseInt(String(updates.cooldownMs)));
+    if (updates.fallbackModels !== undefined) c.fallbackModels = Array.isArray(updates.fallbackModels) ? updates.fallbackModels : [];
+    if (updates.openrouterApiKey !== undefined) c.openrouterApiKey = String(updates.openrouterApiKey);
+
+    // Restart loop if needed
+    if (c.enabled && c.openrouterApiKey) {
+      if (!this.started) this.start();
+      else {
+        // Reset max interval timer with new config
+        this.stop();
+        this.start();
+      }
+    } else {
+      this.stop();
+    }
+  }
+
+  // ── Private: run a single analysis tick ──
+
+  private async run(): Promise<void> {
+    if (this.running) return;
+    if (!this.deps.agentConfig.openrouterApiKey) return;
+
+    // Cooldown: don't re-analyze within cooldownMs of last run
+    if (Date.now() - this.lastRunTs < this.deps.agentConfig.cooldownMs) return;
+
+    // Idle suppression: skip if no new events since last tick
+    const { feedBuffer, senseBuffer } = this.deps;
+    if (feedBuffer.version === this.lastTickFeedVersion &&
+        senseBuffer.version === this.lastTickSenseVersion) {
+      this.stats.idleSkips++;
+      return;
+    }
+    this.lastTickFeedVersion = feedBuffer.version;
+    this.lastTickSenseVersion = senseBuffer.version;
+
+    // Quick idle check BEFORE building context (saves ~20% context builds during idle)
+    const cutoff = Date.now() - this.deps.agentConfig.maxAgeMs;
+    const feedAudioCount = feedBuffer.queryBySource("audio", cutoff).length;
+    const screenCount = senseBuffer.queryByTime(cutoff).length;
+    if (feedAudioCount === 0 && screenCount === 0) {
+      this.stats.idleSkips++;
+      this.deps.profiler?.gauge("agent.idleSkips", this.stats.idleSkips);
+      return;
+    }
+
+    const richness = modeToRichness(this.deps.escalationMode);
+    const ctxStart = Date.now();
+    const contextWindow = buildContextWindow(
+      feedBuffer, senseBuffer, richness, this.deps.agentConfig.maxAgeMs,
+    );
+    this.deps.profiler?.timerRecord("agent.contextBuild", Date.now() - ctxStart);
+
+    this.running = true;
+    const traceCtx = this.deps.onTraceStart?.(this.agentNextId) ?? null;
+
+    try {
+      traceCtx?.startSpan("context-window");
+      traceCtx?.endSpan({ richness, screenEvents: contextWindow.screenCount, audioEntries: contextWindow.audioCount });
+
+      traceCtx?.startSpan("llm-call");
+      const recorderStatus = this.deps.getRecorderStatus?.() ?? null;
+
+      // Trait selection: pick the best personality voice for this tick
+      let traitSelection: TraitSelection | null = null;
+      if (this.deps.traitEngine?.enabled) {
+        const ocrText = contextWindow.screen.map(e => e.ocr ?? "").join(" ");
+        const audioText = contextWindow.audio.map(e => e.text).join(" ");
+        traitSelection = this.deps.traitEngine.selectTrait(ocrText, audioText);
+      }
+
+      const result = await analyzeContext(contextWindow, this.deps.agentConfig, recorderStatus);
+      this.deps.profiler?.timerRecord("agent.llmCall", result.latencyMs);
+      traceCtx?.endSpan({ model: result.model, tokensIn: result.tokensIn, tokensOut: result.tokensOut, latencyMs: result.latencyMs });
+
+      const { hud, digest, latencyMs, tokensIn, tokensOut, model: usedModel, parsedOk } = result;
+
+      // Track context freshness
+      const contextFreshness = contextWindow.newestEventTs
+        ? Date.now() - contextWindow.newestEventTs
+        : null;
+
+      // Track HUD staleness
+      if (hud === this.lastPushedHud) {
+        this.stats.consecutiveIdenticalHud++;
+      } else {
+        this.stats.consecutiveIdenticalHud = 0;
+        this.stats.hudChanges++;
+      }
+
+      // Update stats
+      this.stats.totalCalls++;
+      this.stats.totalTokensIn += tokensIn;
+      this.stats.totalTokensOut += tokensOut;
+      this.stats.lastAnalysisTs = Date.now();
+      this.deps.profiler?.gauge("agent.totalCalls", this.stats.totalCalls);
+      if (parsedOk) this.stats.parseSuccesses++;
+      else this.stats.parseFailures++;
+      this.deps.profiler?.gauge("agent.parseSuccesses", this.stats.parseSuccesses);
+      this.deps.profiler?.gauge("agent.parseFailures", this.stats.parseFailures);
+
+      // Build entry
+      const entry: AgentEntry = {
+        ...result,
+        id: this.agentNextId++,
+        ts: Date.now(),
+        pushed: false,
+        contextFreshnessMs: contextFreshness,
+        context: {
+          currentApp: contextWindow.currentApp,
+          appHistory: contextWindow.appHistory.map(a => a.app),
+          audioCount: contextWindow.audioCount,
+          screenCount: contextWindow.screenCount,
+        },
+      };
+      if (traitSelection) {
+        entry.voice = traitSelection.trait.name;
+        entry.voice_stat = traitSelection.stat;
+        entry.voice_confidence = traitSelection.confidence;
+      }
+      this.agentBuffer.push(entry);
+      const historyLimit = this.deps.agentConfig.historyLimit || 50;
+      if (this.agentBuffer.length > historyLimit) this.agentBuffer.shift();
+
+      const imageCount = contextWindow.images?.length || 0;
+      if (hud !== this.lastPushedHud) {
+        log(TAG, `#${entry.id} (${latencyMs}ms, ${tokensIn}in+${tokensOut}out tok, model=${usedModel}, richness=${richness}, images=${imageCount}) hud="${hud}"`);
+      } else {
+        debug(TAG, `#${entry.id} (${latencyMs}ms) hud unchanged`);
+      }
+
+      // Push HUD line to feed (suppress "—", "Idle", and all in focus mode)
+      if (this.deps.agentConfig.pushToFeed &&
+          this.deps.escalationMode !== "focus" &&
+          this.deps.escalationMode !== "rich" &&
+          hud !== "\u2014" && hud !== "Idle" && hud !== this.lastPushedHud) {
+        feedBuffer.push(`[\ud83e\udde0] ${hud}`, "normal", "agent", "stream");
+        this.deps.onHudUpdate(`[\ud83e\udde0] ${hud}`);
+        this.lastPushedHud = hud;
+        entry.pushed = true;
+      }
+
+      // Store digest
+      this.latestDigest = entry;
+
+      // Calculate escalation score for both SITUATION.md and escalation check
+      const escalationScore = calculateEscalationScore(digest, contextWindow);
+
+      // Write SITUATION.md (enhanced with escalation context and recorder status)
+      const situationContent = writeSituationMd(this.deps.situationMdPath, contextWindow, digest, entry, escalationScore, recorderStatus, traitSelection);
+      this.deps.onSituationUpdate?.(situationContent);
+
+      // Notify for escalation check
+      traceCtx?.startSpan("escalation-check");
+      this.deps.onAnalysis(entry, contextWindow);
+      traceCtx?.endSpan();
+
+      // Finish trace
+      const costPerToken = { in: 0.075 / 1_000_000, out: 0.3 / 1_000_000 };
+      traceCtx?.finish({
+        totalLatencyMs: Date.now() - entry.ts + latencyMs,
+        llmLatencyMs: latencyMs,
+        llmInputTokens: tokensIn,
+        llmOutputTokens: tokensOut,
+        llmCost: tokensIn * costPerToken.in + tokensOut * costPerToken.out,
+        escalated: false, // Updated by escalator
+        escalationScore: 0,
+        contextScreenEvents: contextWindow.screenCount,
+        contextAudioEntries: contextWindow.audioCount,
+        contextRichness: richness,
+        digestLength: digest.length,
+        hudChanged: entry.pushed,
+      });
+
+      // Fire-and-forget trait log
+      if (this.deps.traitEngine?.enabled && this.deps.traitLogDir) {
+        writeTraitLog(this.deps.traitLogDir, {
+          ts: new Date().toISOString(),
+          tickId: entry.id,
+          enabled: true,
+          voice: traitSelection?.trait.name ?? "none",
+          voice_stat: traitSelection?.stat ?? 0,
+          voice_confidence: traitSelection?.confidence ?? 0,
+          activation_scores: traitSelection?.allScores ?? {},
+          context_app: contextWindow.currentApp,
+          hud_length: entry.hud.length,
+          synthesis: false,
+        }).catch(() => {});
+      }
+
+    } catch (err: any) {
+      error(TAG, "tick error:", err.message || err);
+      traceCtx?.endSpan({ status: "error", error: err.message });
+      traceCtx?.finish({ totalLatencyMs: Date.now() - Date.now(), llmLatencyMs: 0, llmInputTokens: 0, llmOutputTokens: 0, llmCost: 0, escalated: false, escalationScore: 0, contextScreenEvents: 0, contextAudioEntries: 0, contextRichness: richness, digestLength: 0, hudChanged: false });
+    } finally {
+      this.running = false;
+      this.lastRunTs = Date.now();
+    }
+  }
+}

package/sinain-core/src/agent/situation-writer.ts

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ContextWindow, AgentEntry, RecorderStatus } from "../types.js";
+import type { EscalationScore } from "../escalation/scorer.js";
+import type { TraitSelection } from "./traits.js";
+import { normalizeAppName } from "./context-window.js";
+import { log, error } from "../log.js";
+
+const TAG = "situation";
+
+/**
+ * Error stack trace patterns for extraction.
+ */
+const ERROR_STACK_PATTERNS = [
+  /Error:.*\n(\s+at\s+.*\n)+/g,      // JavaScript stack traces
+  /Traceback.*:\n(\s+File.*\n)+/gi,  // Python tracebacks
+  /panic:.*\n(\s+goroutine.*\n)?/g,  // Go panics
+  /Exception.*:\n(\s+at\s+.*\n)+/g,  // Java exceptions
+];
+
+/**
+ * Extract error stack traces from text.
+ */
+function extractErrors(text: string): string[] {
+  const errors: string[] = [];
+  for (const pattern of ERROR_STACK_PATTERNS) {
+    const matches = text.match(pattern);
+    if (matches) errors.push(...matches.map(m => m.slice(0, 500)));
+  }
+  return errors;
+}
+
+/**
+ * Atomically write SITUATION.md for OpenClaw bootstrap.
+ * Ported from relay's writeSituationMd() — uses write-then-rename for atomicity.
+ *
+ * Enhanced with:
+ * - Escalation context (score and reasons)
+ * - Detected errors section
+ * - Active recording status
+ */
+export function writeSituationMd(
+  situationMdPath: string,
+  contextWindow: ContextWindow,
+  digest: string,
+  entry: AgentEntry,
+  escalationScore?: EscalationScore,
+  recorderStatus?: RecorderStatus | null,
+  traitSelection?: TraitSelection | null,
+): string {
+  const dir = path.dirname(situationMdPath);
+  const tmpPath = situationMdPath + ".tmp";
+
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err: any) {
+    if (err.code !== "EEXIST") {
+      error(TAG, "mkdir failed:", err.message);
+      return "";
+    }
+  }
+
+  const now = new Date();
+  const lines: string[] = [];
+
+  lines.push("# Situation");
+  lines.push("");
+  lines.push(`> Auto-updated by sinain-core at ${now.toISOString()}`);
+  lines.push(`> Tick #${entry.id} | Latency: ${entry.latencyMs}ms | Model: ${entry.model}`);
+  lines.push("");
+
+  lines.push("## Digest");
+  lines.push("");
+  lines.push(digest);
+  lines.push("");
+
+  const currentApp = normalizeAppName(contextWindow.currentApp);
+  lines.push("## Active Application");
+  lines.push("");
+  lines.push(currentApp);
+  lines.push("");
+
+  if (contextWindow.appHistory.length > 0) {
+    lines.push("## App History");
+    lines.push("");
+    const appChain = contextWindow.appHistory
+      .map(a => normalizeAppName(a.app))
+      .join(" -> ");
+    lines.push(appChain);
+    lines.push("");
+  }
+
+  if (contextWindow.screen.length > 0) {
+    lines.push("## Screen (OCR)");
+    lines.push("");
+    for (const e of contextWindow.screen) {
+      const app = normalizeAppName(e.meta.app);
+      const ago = Math.round((Date.now() - (e.ts || Date.now())) / 1000);
+      const ocr = e.ocr ? e.ocr.replace(/\n/g, " ").slice(0, 500) : "(no text)";
+      lines.push(`- [${ago}s ago] [${app}] ${ocr}`);
+    }
+    lines.push("");
+  }
+
+  if (contextWindow.audio.length > 0) {
+    lines.push("## Audio Transcripts");
+    lines.push("");
+    for (const e of contextWindow.audio) {
+      const ago = Math.round((Date.now() - (e.ts || Date.now())) / 1000);
+      lines.push(`- [${ago}s ago] ${e.text.slice(0, 500)}`);
+    }
+    lines.push("");
+  }
+
+  // Enhanced: Escalation context for richer understanding
+  if (escalationScore && escalationScore.total > 0) {
+    lines.push("## Escalation Context");
+    lines.push("");
+    lines.push(`- Score: ${escalationScore.total}`);
+    lines.push(`- Reasons: ${escalationScore.reasons.join(", ") || "none"}`);
+    lines.push("");
+  }
+
+  // Enhanced: Detected errors section
+  const allText = [
+    digest,
+    ...contextWindow.screen.map(e => e.ocr || ""),
+    ...contextWindow.audio.map(e => e.text || ""),
+  ].join("\n");
+  const detectedErrors = extractErrors(allText);
+  if (detectedErrors.length > 0) {
+    lines.push("## Detected Errors");
+    lines.push("");
+    for (const err of detectedErrors.slice(0, 3)) {
+      lines.push("```");
+      lines.push(err.trim());
+      lines.push("```");
+      lines.push("");
+    }
+  }
+
+  // Enhanced: Active recording status
+  if (recorderStatus?.recording) {
+    lines.push("## Active Recording");
+    lines.push("");
+    const label = recorderStatus.label || "Unnamed recording";
+    const durationSec = Math.round(recorderStatus.durationMs / 1000);
+    lines.push(`- Label: ${label}`);
+    lines.push(`- Duration: ${durationSec}s`);
+    lines.push(`- Segments: ${recorderStatus.segments}`);
+    lines.push("");
+  }
+
+  // Trait voice: frame downstream agent's perspective
+  if (traitSelection) {
+    const { trait, stat } = traitSelection;
+    const voiceFlavor = stat >= 7 ? trait.voice_high : stat <= 2 ? trait.voice_low : trait.description;
+    lines.push("## Active Voice");
+    lines.push("");
+    lines.push(`- Trait: ${trait.name} (stat ${stat}/10)`);
+    lines.push(`- Tagline: ${trait.tagline}`);
+    lines.push(`- Voice: "${voiceFlavor}"`);
+    lines.push("");
+    lines.push("> Frame your response through this lens naturally. Do not name the trait explicitly.");
+    lines.push("");
+  }
+
+  lines.push("## Metadata");
+  lines.push("");
+  lines.push(`- Screen events in window: ${contextWindow.screenCount}`);
+  lines.push(`- Audio events in window: ${contextWindow.audioCount}`);
+  lines.push(`- Context window: ${Math.round(contextWindow.windowMs / 1000)}s`);
+  lines.push(`- Parsed OK: ${entry.parsedOk}`);
+  lines.push("");
+
+  const content = lines.join("\n");
+
+  try {
+    fs.writeFileSync(tmpPath, content, "utf-8");
+    fs.renameSync(tmpPath, situationMdPath);
+  } catch (err: any) {
+    error(TAG, "write failed:", err.message);
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+
+  return content;
+}