@poolzin/pool-bot 2026.1.39 → 2026.2.0

package/dist/agents/pi-embedded-runner/tool-result-truncation.js

@@ -0,0 +1,275 @@
+import { SessionManager } from "@mariozechner/pi-coding-agent";
+import { log } from "./logger.js";
+/**
+ * Maximum share of the context window a single tool result should occupy.
+ * This is intentionally conservative – a single tool result should not
+ * consume more than 30% of the context window even without other messages.
+ */
+const MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3;
+/**
+ * Hard character limit for a single tool result text block.
+ * Even for the largest context windows (~2M tokens), a single tool result
+ * should not exceed ~400K characters (~100K tokens).
+ * This acts as a safety net when we don't know the context window size.
+ */
+export const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
+/**
+ * Minimum characters to keep when truncating.
+ * We always keep at least the first portion so the model understands
+ * what was in the content.
+ */
+const MIN_KEEP_CHARS = 2_000;
+/**
+ * Suffix appended to truncated tool results.
+ */
+const TRUNCATION_SUFFIX = "\n\n⚠️ [Content truncated — original was too large for the model's context window. " +
+    "The content above is a partial view. If you need more, request specific sections or use " +
+    "offset/limit parameters to read smaller chunks.]";
+/**
+ * Truncate a single text string to fit within maxChars, preserving the beginning.
+ */
+export function truncateToolResultText(text, maxChars) {
+    if (text.length <= maxChars) {
+        return text;
+    }
+    const keepChars = Math.max(MIN_KEEP_CHARS, maxChars - TRUNCATION_SUFFIX.length);
+    // Try to break at a newline boundary to avoid cutting mid-line
+    let cutPoint = keepChars;
+    const lastNewline = text.lastIndexOf("\n", keepChars);
+    if (lastNewline > keepChars * 0.8) {
+        cutPoint = lastNewline;
+    }
+    return text.slice(0, cutPoint) + TRUNCATION_SUFFIX;
+}
+/**
+ * Calculate the maximum allowed characters for a single tool result
+ * based on the model's context window tokens.
+ *
+ * Uses a rough 4 chars ≈ 1 token heuristic (conservative for English text;
+ * actual ratio varies by tokenizer).
+ */
+export function calculateMaxToolResultChars(contextWindowTokens) {
+    const maxTokens = Math.floor(contextWindowTokens * MAX_TOOL_RESULT_CONTEXT_SHARE);
+    // Rough conversion: ~4 chars per token on average
+    const maxChars = maxTokens * 4;
+    return Math.min(maxChars, HARD_MAX_TOOL_RESULT_CHARS);
+}
+/**
+ * Get the total character count of text content blocks in a tool result message.
+ */
+function getToolResultTextLength(msg) {
+    if (!msg || msg.role !== "toolResult") {
+        return 0;
+    }
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+        return 0;
+    }
+    let totalLength = 0;
+    for (const block of content) {
+        if (block && typeof block === "object" && block.type === "text") {
+            const text = block.text;
+            if (typeof text === "string") {
+                totalLength += text.length;
+            }
+        }
+    }
+    return totalLength;
+}
+/**
+ * Truncate a tool result message's text content blocks to fit within maxChars.
+ * Returns a new message (does not mutate the original).
+ */
+function truncateToolResultMessage(msg, maxChars) {
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+        return msg;
+    }
+    // Calculate total text size
+    const totalTextChars = getToolResultTextLength(msg);
+    if (totalTextChars <= maxChars) {
+        return msg;
+    }
+    // Distribute the budget proportionally among text blocks
+    const newContent = content.map((block) => {
+        if (!block || typeof block !== "object" || block.type !== "text") {
+            return block; // Keep non-text blocks (images) as-is
+        }
+        const textBlock = block;
+        if (typeof textBlock.text !== "string") {
+            return block;
+        }
+        // Proportional budget for this block
+        const blockShare = textBlock.text.length / totalTextChars;
+        const blockBudget = Math.max(MIN_KEEP_CHARS, Math.floor(maxChars * blockShare));
+        return {
+            ...textBlock,
+            text: truncateToolResultText(textBlock.text, blockBudget),
+        };
+    });
+    return { ...msg, content: newContent };
+}
+/**
+ * Find oversized tool result entries in a session and truncate them.
+ *
+ * This operates on the session file by:
+ * 1. Opening the session manager
+ * 2. Walking the current branch to find oversized tool results
+ * 3. Branching from before the first oversized tool result
+ * 4. Re-appending all entries from that point with truncated tool results
+ *
+ * @returns Object indicating whether any truncation was performed
+ */
+export async function truncateOversizedToolResultsInSession(params) {
+    const { sessionFile, contextWindowTokens } = params;
+    const maxChars = calculateMaxToolResultChars(contextWindowTokens);
+    try {
+        const sessionManager = SessionManager.open(sessionFile);
+        const branch = sessionManager.getBranch();
+        if (branch.length === 0) {
+            return { truncated: false, truncatedCount: 0, reason: "empty session" };
+        }
+        // Find oversized tool result entries and their indices in the branch
+        const oversizedIndices = [];
+        for (let i = 0; i < branch.length; i++) {
+            const entry = branch[i];
+            if (entry.type !== "message") {
+                continue;
+            }
+            const msg = entry.message;
+            if (msg.role !== "toolResult") {
+                continue;
+            }
+            const textLength = getToolResultTextLength(msg);
+            if (textLength > maxChars) {
+                oversizedIndices.push(i);
+                log.info(`[tool-result-truncation] Found oversized tool result: ` +
+                    `entry=${entry.id} chars=${textLength} maxChars=${maxChars} ` +
+                    `sessionKey=${params.sessionKey ?? params.sessionId ?? "unknown"}`);
+            }
+        }
+        if (oversizedIndices.length === 0) {
+            return { truncated: false, truncatedCount: 0, reason: "no oversized tool results" };
+        }
+        // Branch from the parent of the first oversized entry
+        const firstOversizedIdx = oversizedIndices[0];
+        const firstOversizedEntry = branch[firstOversizedIdx];
+        const branchFromId = firstOversizedEntry.parentId;
+        if (!branchFromId) {
+            // The oversized entry is the root - very unusual but handle it
+            sessionManager.resetLeaf();
+        }
+        else {
+            sessionManager.branch(branchFromId);
+        }
+        // Re-append all entries from the first oversized one onwards,
+        // with truncated tool results
+        const oversizedSet = new Set(oversizedIndices);
+        let truncatedCount = 0;
+        for (let i = firstOversizedIdx; i < branch.length; i++) {
+            const entry = branch[i];
+            if (entry.type === "message") {
+                let message = entry.message;
+                if (oversizedSet.has(i)) {
+                    message = truncateToolResultMessage(message, maxChars);
+                    truncatedCount++;
+                    const newLength = getToolResultTextLength(message);
+                    log.info(`[tool-result-truncation] Truncated tool result: ` +
+                        `originalEntry=${entry.id} newChars=${newLength} ` +
+                        `sessionKey=${params.sessionKey ?? params.sessionId ?? "unknown"}`);
+                }
+                // appendMessage expects Message | CustomMessage | BashExecutionMessage
+                sessionManager.appendMessage(message);
+            }
+            else if (entry.type === "compaction") {
+                sessionManager.appendCompaction(entry.summary, entry.firstKeptEntryId, entry.tokensBefore, entry.details, entry.fromHook);
+            }
+            else if (entry.type === "thinking_level_change") {
+                sessionManager.appendThinkingLevelChange(entry.thinkingLevel);
+            }
+            else if (entry.type === "model_change") {
+                sessionManager.appendModelChange(entry.provider, entry.modelId);
+            }
+            else if (entry.type === "custom") {
+                sessionManager.appendCustomEntry(entry.customType, entry.data);
+            }
+            else if (entry.type === "custom_message") {
+                sessionManager.appendCustomMessageEntry(entry.customType, entry.content, entry.display, entry.details);
+            }
+            else if (entry.type === "branch_summary") {
+                // Branch summaries reference specific entry IDs - skip to avoid inconsistency
+                continue;
+            }
+            else if (entry.type === "label") {
+                // Labels reference specific entry IDs - skip to avoid inconsistency
+                continue;
+            }
+            else if (entry.type === "session_info") {
+                if (entry.name) {
+                    sessionManager.appendSessionInfo(entry.name);
+                }
+            }
+        }
+        log.info(`[tool-result-truncation] Truncated ${truncatedCount} tool result(s) in session ` +
+            `(contextWindow=${contextWindowTokens} maxChars=${maxChars}) ` +
+            `sessionKey=${params.sessionKey ?? params.sessionId ?? "unknown"}`);
+        return { truncated: true, truncatedCount };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log.warn(`[tool-result-truncation] Failed to truncate: ${errMsg}`);
+        return { truncated: false, truncatedCount: 0, reason: errMsg };
+    }
+}
+/**
+ * Truncate oversized tool results in an array of messages (in-memory).
+ * Returns a new array with truncated messages.
+ *
+ * This is used as a pre-emptive guard before sending messages to the LLM,
+ * without modifying the session file.
+ */
+export function truncateOversizedToolResultsInMessages(messages, contextWindowTokens) {
+    const maxChars = calculateMaxToolResultChars(contextWindowTokens);
+    let truncatedCount = 0;
+    const result = messages.map((msg) => {
+        if (msg.role !== "toolResult") {
+            return msg;
+        }
+        const textLength = getToolResultTextLength(msg);
+        if (textLength <= maxChars) {
+            return msg;
+        }
+        truncatedCount++;
+        return truncateToolResultMessage(msg, maxChars);
+    });
+    return { messages: result, truncatedCount };
+}
+/**
+ * Check if a tool result message exceeds the size limit for a given context window.
+ */
+export function isOversizedToolResult(msg, contextWindowTokens) {
+    if (msg.role !== "toolResult") {
+        return false;
+    }
+    const maxChars = calculateMaxToolResultChars(contextWindowTokens);
+    return getToolResultTextLength(msg) > maxChars;
+}
+/**
+ * Estimate whether the session likely has oversized tool results that caused
+ * a context overflow. Used as a heuristic to decide whether to attempt
+ * tool result truncation before giving up.
+ */
+export function sessionLikelyHasOversizedToolResults(params) {
+    const { messages, contextWindowTokens } = params;
+    const maxChars = calculateMaxToolResultChars(contextWindowTokens);
+    for (const msg of messages) {
+        if (msg.role !== "toolResult") {
+            continue;
+        }
+        const textLength = getToolResultTextLength(msg);
+        if (textLength > maxChars) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/agents/pi-embedded-runner/utils.js

@@ -1,5 +1,5 @@
 export function mapThinkingLevel(level) {
-    // pi-agent-core supports "xhigh"; Moltbot enables it for specific models.
+    // pi-agent-core supports "xhigh"; Poolbot enables it for specific models.
     if (!level)
         return "off";
     return level;

package/dist/agents/pi-model-discovery.js

@@ -0,0 +1,10 @@
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import path from "node:path";
+export { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+// Compatibility helpers for pi-coding-agent 0.50+ (discover* helpers removed).
+export function discoverAuthStorage(agentDir) {
+    return new AuthStorage(path.join(agentDir, "auth.json"));
+}
+export function discoverModels(authStorage, agentDir) {
+    return new ModelRegistry(authStorage, path.join(agentDir, "models.json"));
+}

package/dist/agents/pi-tool-definition-adapter.js

@@ -1,6 +1,16 @@
 import { logDebug, logError } from "../logger.js";
+import { isPlainObject } from "../utils.js";
+import { runBeforeToolCallHook } from "./pi-tools.before-tool-call.js";
 import { normalizeToolName } from "./tool-policy.js";
 import { jsonResult } from "./tools/common.js";
+function isAbortSignal(value) {
+    return typeof value === "object" && value !== null && "aborted" in value;
+}
+function isLegacyToolExecuteArgs(args) {
+    const third = args[2];
+    const fourth = args[3];
+    return isAbortSignal(third) || typeof fourth === "function";
+}
 function describeToolExecutionError(err) {
     if (err instanceof Error) {
         const message = err.message?.trim() ? err.message : String(err);
@@ -8,6 +18,24 @@ function describeToolExecutionError(err) {
     }
     return { message: String(err) };
 }
+function splitToolExecuteArgs(args) {
+    if (isLegacyToolExecuteArgs(args)) {
+        const [toolCallId, params, signal, onUpdate] = args;
+        return {
+            toolCallId,
+            params,
+            onUpdate,
+            signal,
+        };
+    }
+    const [toolCallId, params, onUpdate, _ctx, signal] = args;
+    return {
+        toolCallId,
+        params,
+        onUpdate,
+        signal,
+    };
+}
 export function toToolDefinitions(tools) {
     return tools.map((tool) => {
         const name = tool.name || "tool";
@@ -16,22 +44,22 @@ export function toToolDefinitions(tools) {
             name,
             label: tool.label ?? name,
             description: tool.description ?? "",
-            // biome-ignore lint/suspicious/noExplicitAny: TypeBox schema from pi-agent-core uses a different module instance.
             parameters: tool.parameters,
-            execute: async (toolCallId, params, onUpdate, _ctx, signal) => {
-                // KNOWN: pi-coding-agent `ToolDefinition.execute` has a different signature/order
-                // than pi-agent-core `AgentTool.execute`. This adapter keeps our existing tools intact.
+            execute: async (...args) => {
+                const { toolCallId, params, onUpdate, signal } = splitToolExecuteArgs(args);
                 try {
                     return await tool.execute(toolCallId, params, signal, onUpdate);
                 }
                 catch (err) {
-                    if (signal?.aborted)
+                    if (signal?.aborted) {
                         throw err;
+                    }
                     const name = err && typeof err === "object" && "name" in err
                         ? String(err.name)
                         : "";
-                    if (name === "AbortError")
+                    if (name === "AbortError") {
                         throw err;
+                    }
                     const described = describeToolExecutionError(err);
                     if (described.stack && described.stack !== described.message) {
                         logDebug(`tools: ${normalizedName} failed stack:\n${described.stack}`);
@@ -49,18 +77,31 @@ export function toToolDefinitions(tools) {
 }
 // Convert client tools (OpenResponses hosted tools) to ToolDefinition format
 // These tools are intercepted to return a "pending" result instead of executing
-export function toClientToolDefinitions(tools, onClientToolCall) {
+export function toClientToolDefinitions(tools, onClientToolCall, hookContext) {
     return tools.map((tool) => {
         const func = tool.function;
         return {
             name: func.name,
             label: func.name,
             description: func.description ?? "",
+            // oxlint-disable-next-line typescript/no-explicit-any
             parameters: func.parameters,
-            execute: async (toolCallId, params, _onUpdate, _ctx, _signal) => {
+            execute: async (...args) => {
+                const { toolCallId, params } = splitToolExecuteArgs(args);
+                const outcome = await runBeforeToolCallHook({
+                    toolName: func.name,
+                    params,
+                    toolCallId,
+                    ctx: hookContext,
+                });
+                if (outcome.blocked) {
+                    throw new Error(outcome.reason);
+                }
+                const adjustedParams = outcome.params;
+                const paramsRecord = isPlainObject(adjustedParams) ? adjustedParams : {};
                 // Notify handler that a client tool was called
                 if (onClientToolCall) {
-                    onClientToolCall(func.name, params);
+                    onClientToolCall(func.name, paramsRecord);
                 }
                 // Return a pending result - the client will execute this tool
                 return jsonResult({

package/dist/agents/pi-tools.before-tool-call.js

@@ -0,0 +1,67 @@
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
+import { isPlainObject } from "../utils.js";
+import { normalizeToolName } from "./tool-policy.js";
+const log = createSubsystemLogger("agents/tools");
+export async function runBeforeToolCallHook(args) {
+    const hookRunner = getGlobalHookRunner();
+    if (!hookRunner?.hasHooks("before_tool_call")) {
+        return { blocked: false, params: args.params };
+    }
+    const toolName = normalizeToolName(args.toolName || "tool");
+    const params = args.params;
+    try {
+        const normalizedParams = isPlainObject(params) ? params : {};
+        const hookResult = await hookRunner.runBeforeToolCall({
+            toolName,
+            params: normalizedParams,
+        }, {
+            toolName,
+            agentId: args.ctx?.agentId,
+            sessionKey: args.ctx?.sessionKey,
+        });
+        if (hookResult?.block) {
+            return {
+                blocked: true,
+                reason: hookResult.blockReason || "Tool call blocked by plugin hook",
+            };
+        }
+        if (hookResult?.params && isPlainObject(hookResult.params)) {
+            if (isPlainObject(params)) {
+                return { blocked: false, params: { ...params, ...hookResult.params } };
+            }
+            return { blocked: false, params: hookResult.params };
+        }
+    }
+    catch (err) {
+        const toolCallId = args.toolCallId ? ` toolCallId=${args.toolCallId}` : "";
+        log.warn(`before_tool_call hook failed: tool=${toolName}${toolCallId} error=${String(err)}`);
+    }
+    return { blocked: false, params };
+}
+export function wrapToolWithBeforeToolCallHook(tool, ctx) {
+    const execute = tool.execute;
+    if (!execute) {
+        return tool;
+    }
+    const toolName = tool.name || "tool";
+    return {
+        ...tool,
+        execute: async (toolCallId, params, signal, onUpdate) => {
+            const outcome = await runBeforeToolCallHook({
+                toolName,
+                params,
+                toolCallId,
+                ctx,
+            });
+            if (outcome.blocked) {
+                throw new Error(outcome.reason);
+            }
+            return await execute(toolCallId, outcome.params, signal, onUpdate);
+        },
+    };
+}
+export const __testing = {
+    runBeforeToolCallHook,
+    isPlainObject,
+};

package/dist/agents/pi-tools.js

@@ -6,8 +6,9 @@ import { createExecTool, createProcessTool, } from "./bash-tools.js";
 import { listChannelAgentTools } from "./channel-tools.js";
 import { createPoolBotTools } from "./poolbot-tools.js";
 import { wrapToolWithAbortSignal } from "./pi-tools.abort.js";
+import { wrapToolWithBeforeToolCallHook } from "./pi-tools.before-tool-call.js";
 import { filterToolsByPolicy, isToolAllowedByPolicies, resolveEffectiveToolPolicy, resolveGroupToolPolicy, resolveSubagentToolPolicy, } from "./pi-tools.policy.js";
-import { assertRequiredParams, CLAUDE_PARAM_GROUPS, createMoltbotReadTool, createSandboxedEditTool, createSandboxedReadTool, createSandboxedWriteTool, normalizeToolParams, patchToolSchemaForClaudeCompatibility, wrapToolParamNormalization, } from "./pi-tools.read.js";
+import { assertRequiredParams, CLAUDE_PARAM_GROUPS, createPoolbotReadTool, createSandboxedEditTool, createSandboxedReadTool, createSandboxedWriteTool, normalizeToolParams, patchToolSchemaForClaudeCompatibility, wrapToolParamNormalization, } from "./pi-tools.read.js";
 import { cleanToolSchemaForGemini, normalizeToolParameters } from "./pi-tools.schema.js";
 import { buildPluginToolGroups, collectExplicitAllowlist, expandPolicyWithPluginGroups, normalizeToolName, resolveToolProfilePolicy, stripPluginOnlyAllowlist, } from "./tool-policy.js";
 import { getPluginToolMeta } from "../plugins/tools.js";
@@ -59,7 +60,7 @@ export const __testing = {
     wrapToolParamNormalization,
     assertRequiredParams,
 };
-export function createMoltbotCodingTools(options) {
+export function createPoolbotCodingTools(options) {
     const execToolName = "exec";
     const sandbox = options?.sandbox?.enabled ? options.sandbox : undefined;
     const { agentId, globalPolicy, globalProviderPolicy, agentPolicy, agentProviderPolicy, profile, providerProfile, profileAlsoAllow, providerProfileAlsoAllow, } = resolveEffectiveToolPolicy({
@@ -124,7 +125,7 @@ export function createMoltbotCodingTools(options) {
                 return [createSandboxedReadTool(sandboxRoot)];
             }
             const freshReadTool = createReadTool(workspaceRoot);
-            return [createMoltbotReadTool(freshReadTool)];
+            return [createPoolbotReadTool(freshReadTool)];
         }
         if (tool.name === "bash" || tool.name === execToolName)
             return [];
@@ -287,9 +288,13 @@ export function createMoltbotCodingTools(options) {
     // Always normalize tool JSON Schemas before handing them to pi-agent/pi-ai.
     // Without this, some providers (notably OpenAI) will reject root-level union schemas.
     const normalized = subagentFiltered.map(normalizeToolParameters);
+    const withHooks = normalized.map((tool) => wrapToolWithBeforeToolCallHook(tool, {
+        agentId,
+        sessionKey: options?.sessionKey,
+    }));
     const withAbort = options?.abortSignal
-        ? normalized.map((tool) => wrapToolWithAbortSignal(tool, options.abortSignal))
-        : normalized;
+        ? withHooks.map((tool) => wrapToolWithAbortSignal(tool, options.abortSignal))
+        : withHooks;
     // NOTE: Keep canonical (lowercase) tool names here.
     // pi-ai's Anthropic OAuth transport remaps tool names to Claude Code-style names
     // on the wire and maps them back for tool dispatch.

package/dist/agents/pi-tools.read.js

@@ -199,7 +199,7 @@ function wrapSandboxPathGuard(tool, root) {
 }
 export function createSandboxedReadTool(root) {
     const base = createReadTool(root);
-    return wrapSandboxPathGuard(createMoltbotReadTool(base), root);
+    return wrapSandboxPathGuard(createPoolbotReadTool(base), root);
 }
 export function createSandboxedWriteTool(root) {
     const base = createWriteTool(root);
@@ -209,7 +209,7 @@ export function createSandboxedEditTool(root) {
     const base = createEditTool(root);
     return wrapSandboxPathGuard(wrapToolParamNormalization(base, CLAUDE_PARAM_GROUPS.edit), root);
 }
-export function createMoltbotReadTool(base) {
+export function createPoolbotReadTool(base) {
     const patched = patchToolSchemaForClaudeCompatibility(base);
     return {
         ...patched,

package/dist/agents/session-file-repair.js

@@ -0,0 +1,83 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+function isSessionHeader(entry) {
+    if (!entry || typeof entry !== "object") {
+        return false;
+    }
+    const record = entry;
+    return record.type === "session" && typeof record.id === "string" && record.id.length > 0;
+}
+export async function repairSessionFileIfNeeded(params) {
+    const sessionFile = params.sessionFile.trim();
+    if (!sessionFile) {
+        return { repaired: false, droppedLines: 0, reason: "missing session file" };
+    }
+    let content;
+    try {
+        content = await fs.readFile(sessionFile, "utf-8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            return { repaired: false, droppedLines: 0, reason: "missing session file" };
+        }
+        const reason = `failed to read session file: ${err instanceof Error ? err.message : "unknown error"}`;
+        params.warn?.(`session file repair skipped: ${reason} (${path.basename(sessionFile)})`);
+        return { repaired: false, droppedLines: 0, reason };
+    }
+    const lines = content.split(/\r?\n/);
+    const entries = [];
+    let droppedLines = 0;
+    for (const line of lines) {
+        if (!line.trim()) {
+            continue;
+        }
+        try {
+            const entry = JSON.parse(line);
+            entries.push(entry);
+        }
+        catch {
+            droppedLines += 1;
+        }
+    }
+    if (entries.length === 0) {
+        return { repaired: false, droppedLines, reason: "empty session file" };
+    }
+    if (!isSessionHeader(entries[0])) {
+        params.warn?.(`session file repair skipped: invalid session header (${path.basename(sessionFile)})`);
+        return { repaired: false, droppedLines, reason: "invalid session header" };
+    }
+    if (droppedLines === 0) {
+        return { repaired: false, droppedLines: 0 };
+    }
+    const cleaned = `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+    const backupPath = `${sessionFile}.bak-${process.pid}-${Date.now()}`;
+    const tmpPath = `${sessionFile}.repair-${process.pid}-${Date.now()}.tmp`;
+    try {
+        const stat = await fs.stat(sessionFile).catch(() => null);
+        await fs.writeFile(backupPath, content, "utf-8");
+        if (stat) {
+            await fs.chmod(backupPath, stat.mode);
+        }
+        await fs.writeFile(tmpPath, cleaned, "utf-8");
+        if (stat) {
+            await fs.chmod(tmpPath, stat.mode);
+        }
+        await fs.rename(tmpPath, sessionFile);
+    }
+    catch (err) {
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch (cleanupErr) {
+            params.warn?.(`session file repair cleanup failed: ${cleanupErr instanceof Error ? cleanupErr.message : "unknown error"} (${path.basename(tmpPath)})`);
+        }
+        return {
+            repaired: false,
+            droppedLines,
+            reason: `repair failed: ${err instanceof Error ? err.message : "unknown error"}`,
+        };
+    }
+    params.warn?.(`session file repaired: dropped ${droppedLines} malformed line(s) (${path.basename(sessionFile)})`);
+    return { repaired: true, droppedLines, backupPath };
+}