@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/agents/workspace.js

@@ -1,16 +1,18 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { isSubagentSessionKey } from "../routing/session-key.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { runCommandWithTimeout } from "../process/exec.js";
+import { isCronSessionKey, isSubagentSessionKey } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
+import { resolveWorkspaceTemplateDir } from "./workspace-templates.js";
 export function resolveDefaultAgentWorkspaceDir(env = process.env, homedir = os.homedir) {
+    const home = resolveRequiredHomeDir(env, homedir);
     const profile = env.POOLBOT_PROFILE?.trim() || env.CLAWDBOT_PROFILE?.trim();
     if (profile && profile.toLowerCase() !== "default") {
-        return path.join(homedir(), `clawd-${profile}`);
+        return path.join(home, `clawd-${profile}`);
     }
-    return path.join(homedir(), "clawd");
+    return path.join(home, "clawd");
 }
 export const DEFAULT_AGENT_WORKSPACE_DIR = resolveDefaultAgentWorkspaceDir();
 export const DEFAULT_AGENTS_FILENAME = "AGENTS.md";
@@ -22,66 +24,203 @@ export const DEFAULT_HEARTBEAT_FILENAME = "HEARTBEAT.md";
 export const DEFAULT_BOOTSTRAP_FILENAME = "BOOTSTRAP.md";
 export const DEFAULT_MEMORY_FILENAME = "MEMORY.md";
 export const DEFAULT_MEMORY_ALT_FILENAME = "memory.md";
-const TEMPLATE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../docs/reference/templates");
+const WORKSPACE_STATE_DIRNAME = ".poolbot";
+const WORKSPACE_STATE_FILENAME = "workspace-state.json";
+const WORKSPACE_STATE_VERSION = 1;
+const workspaceTemplateCache = new Map();
+let gitAvailabilityPromise = null;
+// File content cache with mtime invalidation to avoid redundant reads
+const workspaceFileCache = new Map();
+/**
+ * Read file with caching based on mtime. Returns cached content if file
+ * hasn't changed, otherwise reads from disk and updates cache.
+ */
+async function readFileWithCache(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        const mtimeMs = stats.mtimeMs;
+        const cached = workspaceFileCache.get(filePath);
+        // Return cached content if mtime matches
+        if (cached && cached.mtimeMs === mtimeMs) {
+            return cached.content;
+        }
+        // Read from disk and update cache
+        const content = await fs.readFile(filePath, "utf-8");
+        workspaceFileCache.set(filePath, { content, mtimeMs });
+        return content;
+    }
+    catch (error) {
+        // Remove from cache if file doesn't exist or is unreadable
+        workspaceFileCache.delete(filePath);
+        throw error;
+    }
+}
 function stripFrontMatter(content) {
-    if (!content.startsWith("---"))
+    if (!content.startsWith("---")) {
         return content;
+    }
     const endIndex = content.indexOf("\n---", 3);
-    if (endIndex === -1)
+    if (endIndex === -1) {
         return content;
+    }
     const start = endIndex + "\n---".length;
     let trimmed = content.slice(start);
     trimmed = trimmed.replace(/^\s+/, "");
     return trimmed;
 }
 async function loadTemplate(name) {
-    const templatePath = path.join(TEMPLATE_DIR, name);
+    const cached = workspaceTemplateCache.get(name);
+    if (cached) {
+        return cached;
+    }
+    const pending = (async () => {
+        const templateDir = await resolveWorkspaceTemplateDir();
+        const templatePath = path.join(templateDir, name);
+        try {
+            const content = await fs.readFile(templatePath, "utf-8");
+            return stripFrontMatter(content);
+        }
+        catch {
+            throw new Error(`Missing workspace template: ${name} (${templatePath}). Ensure docs/reference/templates are packaged.`);
+        }
+    })();
+    workspaceTemplateCache.set(name, pending);
     try {
-        const content = await fs.readFile(templatePath, "utf-8");
-        return stripFrontMatter(content);
+        return await pending;
     }
-    catch {
-        throw new Error(`Missing workspace template: ${name} (${templatePath}). Ensure docs/reference/templates are packaged.`);
+    catch (error) {
+        workspaceTemplateCache.delete(name);
+        throw error;
     }
 }
+/** Set of recognized bootstrap filenames for runtime validation */
+const VALID_BOOTSTRAP_NAMES = new Set([
+    DEFAULT_AGENTS_FILENAME,
+    DEFAULT_SOUL_FILENAME,
+    DEFAULT_TOOLS_FILENAME,
+    DEFAULT_IDENTITY_FILENAME,
+    DEFAULT_USER_FILENAME,
+    DEFAULT_HEARTBEAT_FILENAME,
+    DEFAULT_BOOTSTRAP_FILENAME,
+    DEFAULT_MEMORY_FILENAME,
+    DEFAULT_MEMORY_ALT_FILENAME,
+]);
 async function writeFileIfMissing(filePath, content) {
     try {
         await fs.writeFile(filePath, content, {
             encoding: "utf-8",
             flag: "wx",
         });
+        return true;
     }
     catch (err) {
         const anyErr = err;
-        if (anyErr.code !== "EEXIST")
+        if (anyErr.code !== "EEXIST") {
             throw err;
+        }
+        return false;
     }
 }
-async function hasGitRepo(dir) {
+async function fileExists(filePath) {
     try {
-        await fs.stat(path.join(dir, ".git"));
+        await fs.access(filePath);
         return true;
     }
     catch {
         return false;
     }
 }
-async function isGitAvailable() {
+function resolveWorkspaceStatePath(dir) {
+    return path.join(dir, WORKSPACE_STATE_DIRNAME, WORKSPACE_STATE_FILENAME);
+}
+function parseWorkspaceOnboardingState(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object") {
+            return null;
+        }
+        return {
+            version: WORKSPACE_STATE_VERSION,
+            bootstrapSeededAt: typeof parsed.bootstrapSeededAt === "string" ? parsed.bootstrapSeededAt : undefined,
+            onboardingCompletedAt: typeof parsed.onboardingCompletedAt === "string" ? parsed.onboardingCompletedAt : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function readWorkspaceOnboardingState(statePath) {
+    try {
+        const raw = await fs.readFile(statePath, "utf-8");
+        return (parseWorkspaceOnboardingState(raw) ?? {
+            version: WORKSPACE_STATE_VERSION,
+        });
+    }
+    catch (err) {
+        const anyErr = err;
+        if (anyErr.code !== "ENOENT") {
+            throw err;
+        }
+        return {
+            version: WORKSPACE_STATE_VERSION,
+        };
+    }
+}
+async function readWorkspaceOnboardingStateForDir(dir) {
+    const statePath = resolveWorkspaceStatePath(resolveUserPath(dir));
+    return await readWorkspaceOnboardingState(statePath);
+}
+export async function isWorkspaceOnboardingCompleted(dir) {
+    const state = await readWorkspaceOnboardingStateForDir(dir);
+    return (typeof state.onboardingCompletedAt === "string" && state.onboardingCompletedAt.trim().length > 0);
+}
+async function writeWorkspaceOnboardingState(statePath, state) {
+    await fs.mkdir(path.dirname(statePath), { recursive: true });
+    const payload = `${JSON.stringify(state, null, 2)}\n`;
+    const tmpPath = `${statePath}.tmp-${process.pid}-${Date.now().toString(36)}`;
     try {
-        const result = await runCommandWithTimeout(["git", "--version"], { timeoutMs: 2_000 });
-        return result.code === 0;
+        await fs.writeFile(tmpPath, payload, { encoding: "utf-8" });
+        await fs.rename(tmpPath, statePath);
+    }
+    catch (err) {
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+async function hasGitRepo(dir) {
+    try {
+        await fs.stat(path.join(dir, ".git"));
+        return true;
     }
     catch {
         return false;
     }
 }
+async function isGitAvailable() {
+    if (gitAvailabilityPromise) {
+        return gitAvailabilityPromise;
+    }
+    gitAvailabilityPromise = (async () => {
+        try {
+            const result = await runCommandWithTimeout(["git", "--version"], { timeoutMs: 2_000 });
+            return result.code === 0;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return gitAvailabilityPromise;
+}
 async function ensureGitRepo(dir, isBrandNewWorkspace) {
-    if (!isBrandNewWorkspace)
+    if (!isBrandNewWorkspace) {
         return;
-    if (await hasGitRepo(dir))
+    }
+    if (await hasGitRepo(dir)) {
         return;
-    if (!(await isGitAvailable()))
+    }
+    if (!(await isGitAvailable())) {
         return;
+    }
     try {
         await runCommandWithTimeout(["git", "init"], { cwd: dir, timeoutMs: 10_000 });
     }
@@ -93,8 +232,9 @@ export async function ensureAgentWorkspace(params) {
     const rawDir = params?.dir?.trim() ? params.dir.trim() : DEFAULT_AGENT_WORKSPACE_DIR;
     const dir = resolveUserPath(rawDir);
     await fs.mkdir(dir, { recursive: true });
-    if (!params?.ensureBootstrapFiles)
+    if (!params?.ensureBootstrapFiles) {
         return { dir };
+    }
     const agentsPath = path.join(dir, DEFAULT_AGENTS_FILENAME);
     const soulPath = path.join(dir, DEFAULT_SOUL_FILENAME);
     const toolsPath = path.join(dir, DEFAULT_TOOLS_FILENAME);
@@ -102,6 +242,7 @@ export async function ensureAgentWorkspace(params) {
     const userPath = path.join(dir, DEFAULT_USER_FILENAME);
     const heartbeatPath = path.join(dir, DEFAULT_HEARTBEAT_FILENAME);
     const bootstrapPath = path.join(dir, DEFAULT_BOOTSTRAP_FILENAME);
+    const statePath = resolveWorkspaceStatePath(dir);
     const isBrandNewWorkspace = await (async () => {
         const paths = [agentsPath, soulPath, toolsPath, identityPath, userPath, heartbeatPath];
         const existing = await Promise.all(paths.map(async (p) => {
@@ -121,15 +262,53 @@ export async function ensureAgentWorkspace(params) {
     const identityTemplate = await loadTemplate(DEFAULT_IDENTITY_FILENAME);
     const userTemplate = await loadTemplate(DEFAULT_USER_FILENAME);
     const heartbeatTemplate = await loadTemplate(DEFAULT_HEARTBEAT_FILENAME);
-    const bootstrapTemplate = await loadTemplate(DEFAULT_BOOTSTRAP_FILENAME);
     await writeFileIfMissing(agentsPath, agentsTemplate);
     await writeFileIfMissing(soulPath, soulTemplate);
     await writeFileIfMissing(toolsPath, toolsTemplate);
     await writeFileIfMissing(identityPath, identityTemplate);
     await writeFileIfMissing(userPath, userTemplate);
     await writeFileIfMissing(heartbeatPath, heartbeatTemplate);
-    if (isBrandNewWorkspace) {
-        await writeFileIfMissing(bootstrapPath, bootstrapTemplate);
+    let state = await readWorkspaceOnboardingState(statePath);
+    let stateDirty = false;
+    const markState = (next) => {
+        state = { ...state, ...next };
+        stateDirty = true;
+    };
+    const nowIso = () => new Date().toISOString();
+    let bootstrapExists = await fileExists(bootstrapPath);
+    if (!state.bootstrapSeededAt && bootstrapExists) {
+        markState({ bootstrapSeededAt: nowIso() });
+    }
+    if (!state.onboardingCompletedAt && state.bootstrapSeededAt && !bootstrapExists) {
+        markState({ onboardingCompletedAt: nowIso() });
+    }
+    if (!state.bootstrapSeededAt && !state.onboardingCompletedAt && !bootstrapExists) {
+        // Legacy migration path: if USER/IDENTITY diverged from templates, treat onboarding as complete
+        // and avoid recreating BOOTSTRAP for already-onboarded workspaces.
+        const [identityContent, userContent] = await Promise.all([
+            fs.readFile(identityPath, "utf-8"),
+            fs.readFile(userPath, "utf-8"),
+        ]);
+        const legacyOnboardingCompleted = identityContent !== identityTemplate || userContent !== userTemplate;
+        if (legacyOnboardingCompleted) {
+            markState({ onboardingCompletedAt: nowIso() });
+        }
+        else {
+            const bootstrapTemplate = await loadTemplate(DEFAULT_BOOTSTRAP_FILENAME);
+            const wroteBootstrap = await writeFileIfMissing(bootstrapPath, bootstrapTemplate);
+            if (!wroteBootstrap) {
+                bootstrapExists = await fileExists(bootstrapPath);
+            }
+            else {
+                bootstrapExists = true;
+            }
+            if (bootstrapExists && !state.bootstrapSeededAt) {
+                markState({ bootstrapSeededAt: nowIso() });
+            }
+        }
+    }
+    if (stateDirty) {
+        await writeWorkspaceOnboardingState(statePath, state);
     }
     await ensureGitRepo(dir, isBrandNewWorkspace);
     return {
@@ -159,8 +338,9 @@ async function resolveMemoryBootstrapEntries(resolvedDir) {
             // optional
         }
     }
-    if (entries.length <= 1)
+    if (entries.length <= 1) {
         return entries;
+    }
     const seen = new Set();
     const deduped = [];
     for (const entry of entries) {
@@ -169,8 +349,9 @@ async function resolveMemoryBootstrapEntries(resolvedDir) {
             key = await fs.realpath(entry.filePath);
         }
         catch { }
-        if (seen.has(key))
+        if (seen.has(key)) {
             continue;
+        }
         seen.add(key);
         deduped.push(entry);
     }
@@ -212,7 +393,7 @@ export async function loadWorkspaceBootstrapFiles(dir) {
     const result = [];
     for (const entry of entries) {
         try {
-            const content = await fs.readFile(entry.filePath, "utf-8");
+            const content = await readFileWithCache(entry.filePath);
             result.push({
                 name: entry.name,
                 path: entry.filePath,
@@ -226,18 +407,13 @@ export async function loadWorkspaceBootstrapFiles(dir) {
     }
     return result;
 }
-const SUBAGENT_BOOTSTRAP_ALLOWLIST = new Set([DEFAULT_AGENTS_FILENAME, DEFAULT_TOOLS_FILENAME]);
-const VALID_BOOTSTRAP_NAMES = new Set([
-    DEFAULT_AGENTS_FILENAME,
-    DEFAULT_SOUL_FILENAME,
-    DEFAULT_TOOLS_FILENAME,
-    DEFAULT_IDENTITY_FILENAME,
-    DEFAULT_USER_FILENAME,
-    DEFAULT_HEARTBEAT_FILENAME,
-    DEFAULT_BOOTSTRAP_FILENAME,
-    DEFAULT_MEMORY_FILENAME,
-    DEFAULT_MEMORY_ALT_FILENAME,
-]);
+const MINIMAL_BOOTSTRAP_ALLOWLIST = new Set([DEFAULT_AGENTS_FILENAME, DEFAULT_TOOLS_FILENAME]);
+export function filterBootstrapFilesForSession(files, sessionKey) {
+    if (!sessionKey || (!isSubagentSessionKey(sessionKey) && !isCronSessionKey(sessionKey))) {
+        return files;
+    }
+    return files.filter((file) => MINIMAL_BOOTSTRAP_ALLOWLIST.has(file.name));
+}
 export async function loadExtraBootstrapFiles(dir, extraPatterns) {
     if (!extraPatterns.length) {
         return [];
@@ -250,6 +426,7 @@ export async function loadExtraBootstrapFiles(dir, extraPatterns) {
     catch {
         // Keep lexical root if realpath fails.
     }
+    // Resolve glob patterns into concrete file paths
     const resolvedPaths = new Set();
     for (const pattern of extraPatterns) {
         if (pattern.includes("*") || pattern.includes("?") || pattern.includes("{")) {
@@ -260,6 +437,7 @@ export async function loadExtraBootstrapFiles(dir, extraPatterns) {
                 }
             }
             catch {
+                // glob not available or pattern error — fall back to literal
                 resolvedPaths.add(pattern);
             }
         }
@@ -270,20 +448,23 @@ export async function loadExtraBootstrapFiles(dir, extraPatterns) {
     const result = [];
     for (const relPath of resolvedPaths) {
         const filePath = path.resolve(resolvedDir, relPath);
+        // Guard against path traversal — resolved path must stay within workspace
         if (!filePath.startsWith(resolvedDir + path.sep) && filePath !== resolvedDir) {
             continue;
         }
         try {
+            // Resolve symlinks and verify the real path is still within workspace
             const realFilePath = await fs.realpath(filePath);
             if (!realFilePath.startsWith(realResolvedDir + path.sep) &&
                 realFilePath !== realResolvedDir) {
                 continue;
             }
+            // Only load files whose basename is a recognized bootstrap filename
             const baseName = path.basename(relPath);
             if (!VALID_BOOTSTRAP_NAMES.has(baseName)) {
                 continue;
             }
-            const content = await fs.readFile(realFilePath, "utf-8");
+            const content = await readFileWithCache(realFilePath);
             result.push({
                 name: baseName,
                 path: filePath,
@@ -297,8 +478,3 @@ export async function loadExtraBootstrapFiles(dir, extraPatterns) {
     }
     return result;
 }
-export function filterBootstrapFilesForSession(files, sessionKey) {
-    if (!sessionKey || !isSubagentSessionKey(sessionKey))
-        return files;
-    return files.filter((file) => SUBAGENT_BOOTSTRAP_ALLOWLIST.has(file.name));
-}

package/dist/auto-reply/commands-registry.data.js

@@ -231,6 +231,28 @@ function buildChatCommands() {
             textAlias: "/whoami",
             category: "status",
         }),
+        defineChatCommand({
+            key: "session",
+            nativeName: "session",
+            description: "Manage session-level settings (for example /session ttl).",
+            textAlias: "/session",
+            category: "session",
+            args: [
+                {
+                    name: "action",
+                    description: "ttl",
+                    type: "string",
+                    choices: ["ttl"],
+                },
+                {
+                    name: "value",
+                    description: "Duration (24h, 90m) or off",
+                    type: "string",
+                    captureRemaining: true,
+                },
+            ],
+            argsMenu: "auto",
+        }),
         defineChatCommand({
             key: "subagents",
             nativeName: "subagents",
@@ -258,6 +280,35 @@ function buildChatCommands() {
             ],
             argsMenu: "auto",
         }),
+        defineChatCommand({
+            key: "focus",
+            nativeName: "focus",
+            description: "Bind this Discord thread (or a new one) to a session target.",
+            textAlias: "/focus",
+            category: "management",
+            args: [
+                {
+                    name: "target",
+                    description: "Subagent label/index or session key/id/label",
+                    type: "string",
+                    captureRemaining: true,
+                },
+            ],
+        }),
+        defineChatCommand({
+            key: "unfocus",
+            nativeName: "unfocus",
+            description: "Remove the current Discord thread binding.",
+            textAlias: "/unfocus",
+            category: "management",
+        }),
+        defineChatCommand({
+            key: "agents",
+            nativeName: "agents",
+            description: "List thread-bound agents for this session.",
+            textAlias: "/agents",
+            category: "management",
+        }),
         defineChatCommand({
             key: "kill",
             nativeName: "kill",

package/dist/auto-reply/commands-registry.js

@@ -1,6 +1,8 @@
-import { getChatCommands, getNativeCommandSurfaces } from "./commands-registry.data.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js";
 import { resolveConfiguredModelRef } from "../agents/model-selection.js";
+import { isCommandFlagEnabled } from "../config/commands.js";
+import { escapeRegExp } from "../utils.js";
+import { getChatCommands, getNativeCommandSurfaces } from "./commands-registry.data.js";
 let cachedTextAliasMap = null;
 let cachedTextAliasCommands = null;
 let cachedDetection;
@@ -29,9 +31,6 @@ function getTextAliasMap() {
     cachedTextAliasCommands = commands;
     return map;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function buildSkillCommandDefinitions(skillCommands) {
     if (!skillCommands || skillCommands.length === 0)
         return [];
@@ -53,11 +52,11 @@ export function listChatCommands(params) {
 }
 export function isCommandEnabled(cfg, commandKey) {
     if (commandKey === "config")
-        return cfg.commands?.config === true;
+        return isCommandFlagEnabled(cfg, "config");
     if (commandKey === "debug")
-        return cfg.commands?.debug === true;
+        return isCommandFlagEnabled(cfg, "debug");
     if (commandKey === "bash")
-        return cfg.commands?.bash === true;
+        return isCommandFlagEnabled(cfg, "bash");
     return true;
 }
 export function listChatCommandsForConfig(cfg, params) {
@@ -81,25 +80,24 @@ function resolveNativeName(command, provider) {
     }
     return command.nativeName;
 }
-export function listNativeCommandSpecs(params) {
-    return listChatCommands({ skillCommands: params?.skillCommands })
-        .filter((command) => command.scope !== "text" && command.nativeName)
-        .map((command) => ({
-        name: resolveNativeName(command, params?.provider) ?? command.key,
+function toNativeCommandSpec(command, provider) {
+    return {
+        name: resolveNativeName(command, provider) ?? command.key,
         description: command.description,
         acceptsArgs: Boolean(command.acceptsArgs),
         args: command.args,
-    }));
+    };
 }
-export function listNativeCommandSpecsForConfig(cfg, params) {
-    return listChatCommandsForConfig(cfg, params)
+function listNativeSpecsFromCommands(commands, provider) {
+    return commands
         .filter((command) => command.scope !== "text" && command.nativeName)
-        .map((command) => ({
-        name: resolveNativeName(command, params?.provider) ?? command.key,
-        description: command.description,
-        acceptsArgs: Boolean(command.acceptsArgs),
-        args: command.args,
-    }));
+        .map((command) => toNativeCommandSpec(command, provider));
+}
+export function listNativeCommandSpecs(params) {
+    return listNativeSpecsFromCommands(listChatCommands({ skillCommands: params?.skillCommands }), params?.provider);
+}
+export function listNativeCommandSpecsForConfig(cfg, params) {
+    return listNativeSpecsFromCommands(listChatCommandsForConfig(cfg, params), params?.provider);
 }
 export function findCommandByNativeName(name, provider) {
     const normalized = name.trim().toLowerCase();

package/dist/auto-reply/fallback-state.js

@@ -0,0 +1,114 @@
+import { formatProviderModelRef } from "./model-runtime.js";
+const FALLBACK_REASON_PART_MAX = 80;
+export function normalizeFallbackModelRef(value) {
+    const trimmed = String(value ?? "").trim();
+    return trimmed || undefined;
+}
+function truncateFallbackReasonPart(value, max = FALLBACK_REASON_PART_MAX) {
+    const text = String(value ?? "")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (text.length <= max) {
+        return text;
+    }
+    return `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+export function formatFallbackAttemptReason(attempt) {
+    const reason = attempt.reason?.trim();
+    if (reason) {
+        return reason.replace(/_/g, " ");
+    }
+    const code = attempt.code?.trim();
+    if (code) {
+        return code;
+    }
+    if (typeof attempt.status === "number") {
+        return `HTTP ${attempt.status}`;
+    }
+    return truncateFallbackReasonPart(attempt.error || "error");
+}
+function formatFallbackAttemptSummary(attempt) {
+    return `${formatProviderModelRef(attempt.provider, attempt.model)} ${formatFallbackAttemptReason(attempt)}`;
+}
+export function buildFallbackReasonSummary(attempts) {
+    const firstAttempt = attempts[0];
+    const firstReason = firstAttempt
+        ? formatFallbackAttemptReason(firstAttempt)
+        : "selected model unavailable";
+    const moreAttempts = attempts.length > 1 ? ` (+${attempts.length - 1} more attempts)` : "";
+    return `${truncateFallbackReasonPart(firstReason)}${moreAttempts}`;
+}
+export function buildFallbackAttemptSummaries(attempts) {
+    return attempts.map((attempt) => truncateFallbackReasonPart(formatFallbackAttemptSummary(attempt)));
+}
+export function buildFallbackNotice(params) {
+    const selected = formatProviderModelRef(params.selectedProvider, params.selectedModel);
+    const active = formatProviderModelRef(params.activeProvider, params.activeModel);
+    if (selected === active) {
+        return null;
+    }
+    const reasonSummary = buildFallbackReasonSummary(params.attempts);
+    return `↪️ Model Fallback: ${active} (selected ${selected}; ${reasonSummary})`;
+}
+export function buildFallbackClearedNotice(params) {
+    const selected = formatProviderModelRef(params.selectedProvider, params.selectedModel);
+    const previous = normalizeFallbackModelRef(params.previousActiveModel);
+    if (previous && previous !== selected) {
+        return `↪️ Model Fallback cleared: ${selected} (was ${previous})`;
+    }
+    return `↪️ Model Fallback cleared: ${selected}`;
+}
+export function resolveActiveFallbackState(params) {
+    const selected = normalizeFallbackModelRef(params.state?.fallbackNoticeSelectedModel);
+    const active = normalizeFallbackModelRef(params.state?.fallbackNoticeActiveModel);
+    const reason = normalizeFallbackModelRef(params.state?.fallbackNoticeReason);
+    const fallbackActive = params.selectedModelRef !== params.activeModelRef &&
+        selected === params.selectedModelRef &&
+        active === params.activeModelRef;
+    return {
+        active: fallbackActive,
+        reason: fallbackActive ? reason : undefined,
+    };
+}
+export function resolveFallbackTransition(params) {
+    const selectedModelRef = formatProviderModelRef(params.selectedProvider, params.selectedModel);
+    const activeModelRef = formatProviderModelRef(params.activeProvider, params.activeModel);
+    const previousState = {
+        selectedModel: normalizeFallbackModelRef(params.state?.fallbackNoticeSelectedModel),
+        activeModel: normalizeFallbackModelRef(params.state?.fallbackNoticeActiveModel),
+        reason: normalizeFallbackModelRef(params.state?.fallbackNoticeReason),
+    };
+    const fallbackActive = selectedModelRef !== activeModelRef;
+    const fallbackTransitioned = fallbackActive &&
+        (previousState.selectedModel !== selectedModelRef ||
+            previousState.activeModel !== activeModelRef);
+    const fallbackCleared = !fallbackActive && Boolean(previousState.selectedModel || previousState.activeModel);
+    const reasonSummary = buildFallbackReasonSummary(params.attempts);
+    const attemptSummaries = buildFallbackAttemptSummaries(params.attempts);
+    const nextState = fallbackActive
+        ? {
+            selectedModel: selectedModelRef,
+            activeModel: activeModelRef,
+            reason: reasonSummary,
+        }
+        : {
+            selectedModel: undefined,
+            activeModel: undefined,
+            reason: undefined,
+        };
+    const stateChanged = previousState.selectedModel !== nextState.selectedModel ||
+        previousState.activeModel !== nextState.activeModel ||
+        previousState.reason !== nextState.reason;
+    return {
+        selectedModelRef,
+        activeModelRef,
+        fallbackActive,
+        fallbackTransitioned,
+        fallbackCleared,
+        reasonSummary,
+        attemptSummaries,
+        previousState,
+        nextState,
+        stateChanged,
+    };
+}