@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/backends/process-config-cascade.js

@@ -1,4 +1,5 @@
 import { DEFAULT_CLAUDE_HIGH_MODEL, DEFAULT_CLAUDE_LITE_MODEL, DEFAULT_CLAUDE_MEDIUM_MODEL, findRegisteredModel, getModelsForBackend, } from "./model-registry.js";
+import { applyBackendBudgetFactor } from "./plan-presets.js";
 /**
  * Process-config cascade-write helper (DOCS_QA_DESIGN.md §10.2 Q4 = option B).
  *
@@ -73,10 +74,24 @@ export function setProcessBackendConfig(db, write) {
         const inheritorFallbackModel = inheritorFallbackBackend
             ? resolveTierModel(db, inheritorFallbackBackend, rule.inheritorTier)
             : null;
-        const caps = INHERITOR_DEFAULTS[rule.inheritor] ?? {
+        // INHERITOR_DEFAULTS covers every entry in INHERITANCE_CASCADE_MAP
+        // today; the fallback object literal is forward-defensive for
+        // inheritors added to the map without a corresponding defaults entry.
+        /* c8 ignore start */
+        const rawCaps = INHERITOR_DEFAULTS[rule.inheritor] ?? {
             maxTurns: write.maxTurns,
             maxBudgetUsd: write.maxBudgetUsd,
         };
+        /* c8 ignore stop */
+        // INHERITOR_DEFAULTS holds Claude-baseline budgets. When the cascade
+        // is firing on a non-Claude main backend (e.g., operator pins
+        // message.dm to Codex), scale the inheritor's budget the same way
+        // resolveDefaultBindingFor does for top-level seeds, so post-hoc-
+        // enforced backends get the same headroom.
+        const caps = {
+            maxTurns: rawCaps.maxTurns,
+            maxBudgetUsd: applyBackendBudgetFactor(write.mainBackend, rule.inheritorTier, rawCaps.maxBudgetUsd),
+        };
         upsertRow(db, {
             processKey: rule.inheritor,
             mainBackend: write.mainBackend,
@@ -148,6 +163,14 @@ function resolveTierModel(db, backendId, tier) {
         }
     }
     const match = getModelsForBackend(backendId).find((m) => m.tier === tier && m.available);
+    /* c8 ignore start — every registered BackendId has at least one
+       available model per tier in MODEL_REGISTRY today, so `match` is
+       always defined when the defaults block falls through. The
+       `if (match)` falsy branch and the fallbacks below are
+       forward-defensive in case a backend ever drops a tier (e.g.,
+       Codex stops shipping lite). Neither can be reached via valid
+       BackendId values without module-mocking the registry, which ESM
+       blocks. */
     if (match)
         return match.modelId;
     if (backendId === "claude") {
@@ -162,6 +185,7 @@ function resolveTierModel(db, backendId, tier) {
     // best-effort mirror; the backend-router has its own resolution chain.
     const anyModel = getModelsForBackend(backendId)[0]?.modelId;
     return anyModel ?? "";
+    /* c8 ignore stop */
 }
 function readDefaults(db) {
     return (db
@@ -170,4 +194,13 @@ function readDefaults(db) {
           WHERE singleton = 1`)
         .get() ?? null);
 }
-//# sourceMappingURL=process-config-cascade.js.map
+/**
+ * Internal helpers exposed for unit testing. Production code should
+ * call `setProcessBackendConfig` instead — these are private to the
+ * cascade-write chokepoint.
+ */
+export const _internals = {
+    resolveTierModel,
+    readDefaults,
+    readUpdatedBy,
+};

package/dist/core/backends/prompt-utils.d.ts

@@ -4,4 +4,3 @@ export declare function buildSummaryPrompt(conversationText: string): string;
 export declare function sanitizeUntrustedTemplateValue(value: string): string;
 export declare function resolveTemplate(template: string, context: string, eventData: Record<string, string>): string;
 export declare function extractEventData(event: Event): Record<string, string>;
-//# sourceMappingURL=prompt-utils.d.ts.map

package/dist/core/backends/prompt-utils.js

@@ -50,8 +50,6 @@ export function buildSummaryPrompt(conversationText) {
  * they can be used to confuse the model with invisible directives and
  * have no legitimate place in chat content.
  */
-// eslint-disable-next-line no-control-regex -- C0 control-char strip is the
-// whole point of this rule.
 const CONTROL_CHARS = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
 export function sanitizeUntrustedTemplateValue(value) {
     // The type signature says `string`, but `extractEventData` can produce
@@ -134,4 +132,3 @@ export function extractEventData(event) {
     }
     return data;
 }
-//# sourceMappingURL=prompt-utils.js.map

package/dist/core/backends/proxy-model-registry.d.ts

@@ -107,4 +107,3 @@ export interface ProxyModelOption {
     usdPer1kOut: number | null;
 }
 export declare function listProxyModelOptions(backendId: BackendId): ProxyModelOption[];
-//# sourceMappingURL=proxy-model-registry.d.ts.map

package/dist/core/backends/proxy-model-registry.js

@@ -192,4 +192,3 @@ export function listProxyModelOptions(backendId) {
         /* c8 ignore stop */
     }));
 }
-//# sourceMappingURL=proxy-model-registry.js.map

package/dist/core/backends/quota-reset-hints.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic provider-agnostic quota reset-time parser, shared by Codex and
+ * Gemini cores. Claude has its own extractor (`extractClaudeCodeQuotaResetHint`
+ * in `claude-errors.ts`) tuned to the Anthropic SDK's `resets HH(:MM)? am/pm`
+ * phrasing; this helper covers the OpenAI- and Google-style strings that
+ * surface through the CLI subprocess.
+ *
+ * The output `BackendQuotaResetHint` is what the dashboard renders as
+ * "quota resets at HH:MM (TZ)". Returns null when no pattern matches; the
+ * caller falls back to the existing `null`-resetHint behaviour.
+ *
+ * Patterns supported (in priority order):
+ *  1. Relative offset — "try again in 26m11s" / "retry-after: 90s".
+ *     Resolved against `now()` and emitted in UTC.
+ *  2. ISO timestamp — "try again at 2026-05-15T03:00:00Z" /
+ *     "reset time 2026-05-15T03:00:00Z" / "retry-after: 2026-...".
+ *     Normalised to UTC.
+ *  3. Absolute clock time with optional am/pm and TZ —
+ *     "try again at 5pm (UTC)" / "resets at 04:00 PST".
+ *
+ * Only string-based heuristics — extracting more from the upstream JSON
+ * would require parsing each provider's error envelope, which is brittle
+ * and not worth the maintenance cost. False negatives are acceptable
+ * (caller falls back to `null` hint, matching today's behaviour); false
+ * positives are not (would mislead the operator).
+ */
+import type { BackendQuotaResetHint } from "../agent-core.js";
+/**
+ * Build a deterministic reset hint anchored on the next agent-day boundary.
+ * Used by Gemini's `daily_ceiling` quota error — the reset time is fully
+ * known (next `dayBoundaryHour:00` in the configured timezone), so we don't
+ * need to scan an upstream message.
+ *
+ * `timezone` arrives from `AgentConfig.timezone` which defaults to `""` —
+ * coerce empty/whitespace to `undefined` so the dashboard renders
+ * "resets at 04:00" rather than "resets at 04:00 ()".
+ */
+export declare function buildAgentDayBoundaryHint(dayBoundaryHour: number, timezone: string | undefined): BackendQuotaResetHint;
+/**
+ * Parse a free-form provider error message and return a structured hint when
+ * a reset time is detectable. Pure: callers may inject `now` for tests.
+ */
+export declare function extractGenericQuotaResetHint(message: string, now?: () => Date): BackendQuotaResetHint | null;

package/dist/core/backends/quota-reset-hints.js

@@ -0,0 +1,116 @@
+/**
+ * Generic provider-agnostic quota reset-time parser, shared by Codex and
+ * Gemini cores. Claude has its own extractor (`extractClaudeCodeQuotaResetHint`
+ * in `claude-errors.ts`) tuned to the Anthropic SDK's `resets HH(:MM)? am/pm`
+ * phrasing; this helper covers the OpenAI- and Google-style strings that
+ * surface through the CLI subprocess.
+ *
+ * The output `BackendQuotaResetHint` is what the dashboard renders as
+ * "quota resets at HH:MM (TZ)". Returns null when no pattern matches; the
+ * caller falls back to the existing `null`-resetHint behaviour.
+ *
+ * Patterns supported (in priority order):
+ *  1. Relative offset — "try again in 26m11s" / "retry-after: 90s".
+ *     Resolved against `now()` and emitted in UTC.
+ *  2. ISO timestamp — "try again at 2026-05-15T03:00:00Z" /
+ *     "reset time 2026-05-15T03:00:00Z" / "retry-after: 2026-...".
+ *     Normalised to UTC.
+ *  3. Absolute clock time with optional am/pm and TZ —
+ *     "try again at 5pm (UTC)" / "resets at 04:00 PST".
+ *
+ * Only string-based heuristics — extracting more from the upstream JSON
+ * would require parsing each provider's error envelope, which is brittle
+ * and not worth the maintenance cost. False negatives are acceptable
+ * (caller falls back to `null` hint, matching today's behaviour); false
+ * positives are not (would mislead the operator).
+ */
+/**
+ * Build a deterministic reset hint anchored on the next agent-day boundary.
+ * Used by Gemini's `daily_ceiling` quota error — the reset time is fully
+ * known (next `dayBoundaryHour:00` in the configured timezone), so we don't
+ * need to scan an upstream message.
+ *
+ * `timezone` arrives from `AgentConfig.timezone` which defaults to `""` —
+ * coerce empty/whitespace to `undefined` so the dashboard renders
+ * "resets at 04:00" rather than "resets at 04:00 ()".
+ */
+export function buildAgentDayBoundaryHint(dayBoundaryHour, timezone) {
+    const tz = timezone?.trim() ? timezone.trim() : undefined;
+    const hour = Math.max(0, Math.min(23, Math.trunc(dayBoundaryHour)));
+    return {
+        hour,
+        minute: 0,
+        ...(tz ? { timeZone: tz } : {}),
+        rawLabel: tz
+            ? `next agent-day boundary (${hour.toString().padStart(2, "0")}:00 ${tz})`
+            : `next agent-day boundary (${hour.toString().padStart(2, "0")}:00)`,
+    };
+}
+/**
+ * Parse a free-form provider error message and return a structured hint when
+ * a reset time is detectable. Pure: callers may inject `now` for tests.
+ */
+export function extractGenericQuotaResetHint(message, now = () => new Date()) {
+    if (!message)
+        return null;
+    // 1. Relative offset — "try again in (Xh)?(Ym)?(Zs)?" or
+    //    "retry-after: Ns" (HTTP 429 header surfaced verbatim).
+    const relative = /(?:try again in|retry[\s-]?after[:\s]+)\s*(?:(\d+)\s*h)?\s*(?:(\d+)\s*m)?\s*(?:(\d+)\s*s)?/i
+        .exec(message);
+    if (relative && (relative[1] || relative[2] || relative[3])) {
+        const h = Number(relative[1] ?? 0);
+        const m = Number(relative[2] ?? 0);
+        const s = Number(relative[3] ?? 0);
+        const offsetMs = ((h * 60 + m) * 60 + s) * 1000;
+        if (offsetMs > 0) {
+            const target = new Date(now().getTime() + offsetMs);
+            return {
+                hour: target.getUTCHours(),
+                minute: target.getUTCMinutes(),
+                timeZone: "UTC",
+                rawLabel: relative[0].trim(),
+            };
+        }
+    }
+    // 2. ISO 8601 timestamp — "try again at YYYY-MM-DDTHH:MM(:SS)?Z|±HH:MM".
+    const iso = /(?:try again at|reset(?:s|\s+time)?\s+(?:at\s+)?|retry[\s-]?after[:\s]+)\s*([0-9]{4}-[0-9]{2}-[0-9]{2}[T\s][0-9]{2}:[0-9]{2}(?::[0-9]{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)/i
+        .exec(message);
+    if (iso) {
+        // Normalise the date string: bare "YYYY-MM-DD HH:MM" without a TZ marker
+        // is interpreted by Date as local time, which is fine — but we always
+        // emit UTC fields to keep the contract uniform.
+        const date = new Date(iso[1].replace(" ", "T"));
+        if (!Number.isNaN(date.getTime())) {
+            return {
+                hour: date.getUTCHours(),
+                minute: date.getUTCMinutes(),
+                timeZone: "UTC",
+                rawLabel: iso[0].trim(),
+            };
+        }
+    }
+    // 3. Absolute clock time with optional am/pm and TZ. Anchored on
+    //    "try again at" / "resets (at)?" so plain numbers in error text
+    //    can't false-positive.
+    const absolute = /(?:try again at|resets?\s+(?:at\s+)?)\s*(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(?([A-Z]{2,5}|UTC[+-]\d+)\)?)?/i
+        .exec(message);
+    if (absolute) {
+        const rawHour = Number(absolute[1]);
+        const meridiem = absolute[3]?.toLowerCase();
+        let hour = rawHour;
+        if (meridiem) {
+            hour = rawHour % 12;
+            if (meridiem === "pm")
+                hour += 12;
+        }
+        if (hour >= 0 && hour < 24) {
+            return {
+                hour,
+                minute: absolute[2] ? Number(absolute[2]) : 0,
+                timeZone: absolute[4]?.trim(),
+                rawLabel: absolute[0].trim(),
+            };
+        }
+    }
+    return null;
+}

package/dist/core/backends/silent-api-error-detector.d.ts

@@ -28,4 +28,3 @@ export declare function logSilentApiErrors(log: Logger, errors: SilentApiError[]
     sessionId?: string | null;
     eventType?: string;
 }): void;
-//# sourceMappingURL=silent-api-error-detector.d.ts.map

package/dist/core/backends/silent-api-error-detector.js

@@ -41,4 +41,3 @@ export function logSilentApiErrors(log, errors, context) {
         }, "Daemon API returned error to agent (silent API error)");
     }
 }
-//# sourceMappingURL=silent-api-error-detector.js.map

package/dist/core/bang-commands/commands-checks.d.ts

@@ -0,0 +1,16 @@
+import type { BangCommand } from "./registry.js";
+interface ChecksRow {
+    urlPattern: string;
+    reloadCount: number;
+}
+/**
+ * Pure formatter — same shape as `formatCostAll`, kept exported so the
+ * test suite can pin output shape without standing up a DB.
+ *
+ * The "neutral observation, never recommendation" rule lives in
+ * §5.F4 (Explicit non-action). This formatter renders the count and
+ * nothing else: no "you should…", no "consider…", no rate per hour.
+ */
+export declare function formatChecks(date: string, rows: ChecksRow[]): string;
+export declare const checksCommand: BangCommand;
+export {};

package/dist/core/bang-commands/commands-checks.js

@@ -0,0 +1,58 @@
+import { getAgentDayDateStr } from "@aitne/shared";
+import { listReloadsForDate } from "../../db/browser-history-store.js";
+const DEFAULT_LIMIT = 10;
+function resolveTodayKey(config, nowMs) {
+    return getAgentDayDateStr(config.timezone && config.timezone.length > 0 ? config.timezone : undefined, config.dayBoundaryHour ?? 4, new Date(nowMs));
+}
+/**
+ * Pure formatter — same shape as `formatCostAll`, kept exported so the
+ * test suite can pin output shape without standing up a DB.
+ *
+ * The "neutral observation, never recommendation" rule lives in
+ * §5.F4 (Explicit non-action). This formatter renders the count and
+ * nothing else: no "you should…", no "consider…", no rate per hour.
+ */
+export function formatChecks(date, rows) {
+    const header = `[SYSTEM · !checks · ${date}]`;
+    if (rows.length === 0) {
+        return [
+            header,
+            "No reload patterns recorded for today's agent-day yet.",
+        ].join("\n");
+    }
+    const lines = [
+        header,
+        `Top reload patterns (${rows.length}):`,
+    ];
+    for (const row of rows) {
+        lines.push(`- ${row.urlPattern}: ${row.reloadCount}`);
+    }
+    return lines.join("\n");
+}
+function queryChecks(db, date) {
+    return listReloadsForDate(db, date, DEFAULT_LIMIT);
+}
+export const checksCommand = {
+    name: "!checks",
+    title: "Reload tally",
+    // describe kept tight so the !help mobile-reply budget (1500 chars)
+    // still has headroom for user-defined bang commands when the default
+    // registry already runs ~20 entries deep. Full F4 context belongs in
+    // `details:` below, not in the one-line describe.
+    describe: "Today's browser reload tally.",
+    details: [
+        "Returns today's top reload patterns per URL (domain + first path segment).",
+        "Day boundary is the daemon's `dayBoundaryHour` (default 04:00 local), not UTC midnight.",
+        "Does not invoke an LLM. Safe to call while paused.",
+    ],
+    // Pure DB read with no agent dispatch — same posture as `!cost` /
+    // `!report`. Critically, the user can still ask "what was I refreshing
+    // today?" with the agent paused, which is when a quiet self-check is
+    // most useful.
+    runsWhilePaused: true,
+    handler: async (ctx) => {
+        const date = resolveTodayKey(ctx.config, Date.now());
+        const rows = queryChecks(ctx.db, date);
+        await ctx.notify(formatChecks(date, rows));
+    },
+};

package/dist/core/bang-commands/commands-close.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `!close` — explicit DM session close. Replaces the bare-word
+ * `end` / `close` / `done` matcher that used to intercept owner DMs at
+ * `EventDispatcher.handleMessage` — that matcher would silently close
+ * the conversation any time the user typed the word "done" on its own
+ * (a frequent natural-English completion signal), with no way to
+ * disambiguate from a genuine close intent.
+ *
+ * Behaviour:
+ *   - With an active session for this DM tuple → records the `!close`
+ *     turn, closes the session (workdir cleanup is handled by the
+ *     session manager), and replies "Session closed."
+ *   - Without an active session → no-op DB-side; reply is honest
+ *     ("No active session to close.") rather than the old "Session
+ *     closed." lie.
+ *
+ * Pause semantics:
+ *   - `runsWhilePaused: true`. Closing a conversation is a state-only
+ *     operation (no LLM call, no autonomous work), so the pause gate
+ *     would only prevent the user from cleaning up state they own.
+ */
+import type { BangCommand } from "./registry.js";
+export declare const closeCommand: BangCommand;

package/dist/core/bang-commands/commands-close.js

@@ -0,0 +1,23 @@
+export const closeCommand = {
+    name: "!close",
+    title: "Close session",
+    describe: "End the current DM session. The next DM starts a fresh session.",
+    details: [
+        "Closes the active conversation session for this DM channel.",
+        "Workdir is cleaned up; the next DM starts fresh with no carried context.",
+        "No LLM call. Safe to use while the agent is paused.",
+    ],
+    runsWhilePaused: true,
+    handler: async (ctx) => {
+        if (!ctx.closeActiveDmSession) {
+            await ctx.notify("Session close is not available in this daemon process.");
+            return;
+        }
+        const result = await ctx.closeActiveDmSession();
+        if (result.closedId === null) {
+            await ctx.notify("No active session to close.");
+            return;
+        }
+        await ctx.notify("Session closed.");
+    },
+};

package/dist/core/bang-commands/commands-cost.d.ts

@@ -10,4 +10,3 @@ export declare function formatCostFiltered(backend: BackendId, rows: CostRow[]):
 export declare const costAllCommand: BangCommand;
 export declare const costBackendCommands: BangCommand[];
 export {};
-//# sourceMappingURL=commands-cost.d.ts.map

package/dist/core/bang-commands/commands-cost.js

@@ -67,11 +67,23 @@ export const costAllCommand = {
         "Groups total spend by backend.",
         "Does not invoke an LLM.",
     ],
+    runsWhilePaused: true,
     handler: async (ctx) => {
         const rows = queryCost(ctx.db);
         await ctx.notify(formatCostAll(rows));
     },
 };
+/**
+ * P2-21 — `!cost <backend>` is intentionally registered as one exact-match
+ * BangCommand per backend (see {@link costBackendCommands}). An unknown
+ * argument like `!cost notabackend` therefore falls through to the
+ * unknown-command path which lists the known set. If a future refactor
+ * flips this to a single `BangPrefixCommand` with `prefix: "!cost"`, add
+ * a `parseArgs` that validates against `RUNTIME_AVAILABLE_BACKEND_IDS`
+ * and throws `BangArgError("Unknown backend: <x>. Use claude, gemini,
+ * codex.")` — otherwise an unknown backend would silently render `$0.00`
+ * which reads as "no spend" rather than "you typed the wrong thing".
+ */
 function makeCostBackendCommand(backend) {
     return {
         name: `!cost ${backend}`,
@@ -81,6 +93,7 @@ function makeCostBackendCommand(backend) {
             `Reports trailing 7-day spend for ${backend}.`,
             "Does not invoke an LLM.",
         ],
+        runsWhilePaused: true,
         handler: async (ctx) => {
             const rows = queryCost(ctx.db);
             await ctx.notify(formatCostFiltered(backend, rows));
@@ -88,4 +101,3 @@ function makeCostBackendCommand(backend) {
     };
 }
 export const costBackendCommands = BACKEND_IDS.map(makeCostBackendCommand);
-//# sourceMappingURL=commands-cost.js.map

package/dist/core/bang-commands/commands-help.d.ts

@@ -2,4 +2,3 @@ import type { BangCommand, RegisteredBangCommand } from "./registry.js";
 import { type UserBangCommand } from "./user-commands.js";
 export declare function formatHelp(builtIns: RegisteredBangCommand[], userCommands: UserBangCommand[]): string;
 export declare const helpCommand: BangCommand;
-//# sourceMappingURL=commands-help.d.ts.map

package/dist/core/bang-commands/commands-help.js

@@ -25,21 +25,31 @@
  */
 import { getBangCommandName } from "./registry.js";
 import { listUserBangCommands, } from "./user-commands.js";
+import { MOBILE_REPLY_BUDGET } from "./format-utils.js";
 function renderEntry(name, describe) {
     return [name, `  ${describe.trim()}`];
 }
 export function formatHelp(builtIns, userCommands) {
-    const lines = ["[SYSTEM · !help]"];
+    const enabledUserCommands = userCommands
+        .filter((cmd) => cmd.enabled)
+        .sort((a, b) => a.command.localeCompare(b.command));
     const sortedBuiltIns = [...builtIns].sort((a, b) => getBangCommandName(a).localeCompare(getBangCommandName(b)));
+    const totalCommands = sortedBuiltIns.length + enabledUserCommands.length;
+    // Lead with the total count so the operator can detect at a glance
+    // whether truncation hid entries. The full body still renders below —
+    // `truncateForMobile` (via `makeNotify`) only cuts when the assembled
+    // text exceeds MOBILE_REPLY_BUDGET, and the count line survives
+    // because it precedes any truncation point.
+    const lines = [
+        "[SYSTEM · !help]",
+        `${totalCommands} command${totalCommands === 1 ? "" : "s"} total`,
+    ];
     if (sortedBuiltIns.length > 0) {
         lines.push("", "Built-in:");
         for (const cmd of sortedBuiltIns) {
             lines.push("", ...renderEntry(getBangCommandName(cmd), cmd.describe));
         }
     }
-    const enabledUserCommands = userCommands
-        .filter((cmd) => cmd.enabled)
-        .sort((a, b) => a.command.localeCompare(b.command));
     if (enabledUserCommands.length > 0) {
         lines.push("", "Custom:");
         for (const cmd of enabledUserCommands) {
@@ -49,7 +59,35 @@ export function formatHelp(builtIns, userCommands) {
             lines.push("", ...renderEntry(cmd.command, desc));
         }
     }
-    return lines.join("\n");
+    // When the body will overflow the mobile budget, append a
+    // dashboard-pointer footer BEFORE `truncateForMobile` snips the tail.
+    // The generic `… (truncated)` marker doesn't tell the operator that the
+    // dashboard has the rest; this footer does. `ensureSystemMarker` is a
+    // no-op here because the body already starts with `[SYSTEM · !help]`,
+    // so the exact-budget math below is safe — slicing to `BUDGET -
+    // FOOTER.length` and appending FOOTER lands the result at exactly
+    // MOBILE_REPLY_BUDGET, and `truncateForMobile` then short-circuits.
+    const body = lines.join("\n");
+    const FOOTER = "\n\nMore commands available — open the dashboard to browse the full list.";
+    if (body.length + FOOTER.length > MOBILE_REPLY_BUDGET) {
+        let room = MOBILE_REPLY_BUDGET - FOOTER.length;
+        if (room <= 0) {
+            // FOOTER alone would overflow — extremely unlikely (FOOTER ~75 chars
+            // vs. 1500-char budget) but guard so we never slice with a negative
+            // length. Drop to a truncated body without the dashboard hint and
+            // let truncateForMobile handle it.
+            return body;
+        }
+        // Avoid splitting a surrogate pair at the boundary, mirroring
+        // truncateForMobile.
+        if (room > 0
+            && body.charCodeAt(room - 1) >= 0xd800
+            && body.charCodeAt(room - 1) <= 0xdbff) {
+            room -= 1;
+        }
+        return `${body.slice(0, room)}${FOOTER}`;
+    }
+    return body;
 }
 export const helpCommand = {
     name: "!help",
@@ -60,10 +98,10 @@ export const helpCommand = {
         "Disabled user commands are hidden.",
         "Output is truncated at the mobile reply budget if very long.",
     ],
+    runsWhilePaused: true,
     handler: async (ctx) => {
         const builtIns = ctx.registry.list();
         const userCommands = listUserBangCommands(ctx.db);
         await ctx.notify(formatHelp(builtIns, userCommands));
     },
 };
-//# sourceMappingURL=commands-help.js.map

package/dist/core/bang-commands/commands-report.d.ts

@@ -15,4 +15,3 @@ export declare function formatReport(data: {
 }, config: AgentConfig): string;
 export declare const reportCommand: BangCommand;
 export {};
-//# sourceMappingURL=commands-report.d.ts.map

package/dist/core/bang-commands/commands-report.js

@@ -97,9 +97,9 @@ export const reportCommand = {
         "Samples are redacted before sending to messaging surfaces.",
         "Does not invoke an LLM.",
     ],
+    runsWhilePaused: true,
     handler: async (ctx) => {
         const data = queryReport(ctx.db);
         await ctx.notify(formatReport(data, ctx.config));
     },
 };
-//# sourceMappingURL=commands-report.js.map

package/dist/core/bang-commands/commands-research.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `!research` family — owner-facing bang commands for the browser
+ * history research cluster surface (BROWSER_HISTORY_INTEGRATION_PLAN
+ * §5.F1, P3 phasing).
+ *
+ * Subcommand grammar:
+ *   !research                            list active + dormant clusters
+ *   !research <slug>                     show cluster detail
+ *   !research accept <slug>              dispatch routine.research_dispatch
+ *   !research wiki <slug>                dispatch routine.research_wiki_summary
+ *   !research decline <slug>             silence offers for 14 days
+ *   !research mute <slug>                mark status=muted (offers off)
+ *   !research unmute <slug>              restore status=active
+ *   !research rename <slug> <new name>   rename display_name
+ *   !research conclude <slug>            mark status=concluded
+ *
+ * All dispatch paths route through the EventBus via
+ * `enqueueBrowserResearchEvent` on `BangCommandContext` so the bang
+ * handler stays narrow (parse → DB stamp → enqueue). The handler does
+ * NOT compose DM prose; the agent or the templated offer DM owns
+ * messaging.
+ */
+import type { BangPrefixCommand } from "./registry.js";
+type Subcommand = "list" | "show" | "accept" | "wiki" | "decline" | "mute" | "unmute" | "rename" | "conclude";
+type ResearchArgs = {
+    subcommand: "list";
+    slug: null;
+    payload: "";
+} | {
+    subcommand: Exclude<Subcommand, "list">;
+    slug: string;
+    payload: string;
+};
+export declare function parseResearchArgs(rest: string): ResearchArgs;
+export declare const researchCommand: BangPrefixCommand;
+export {};