@nanhara/hara 0.122.3 → 0.122.5

package/dist/agent/repeat-guard.js

@@ -18,34 +18,71 @@ function scopedSeen(scope) {
  *  so a space separator is unambiguous). */
 export function keyOf(name, input) {
     try {
-        return name + " " + JSON.stringify(input ?? {});
+        const seen = new WeakSet();
+        const canonical = (value) => {
+            if (!value || typeof value !== "object")
+                return value;
+            if (seen.has(value))
+                throw new TypeError("circular tool input");
+            seen.add(value);
+            try {
+                if (Array.isArray(value))
+                    return value.map(canonical);
+                const out = {};
+                for (const key of Object.keys(value).sort()) {
+                    const next = value[key];
+                    if (next !== undefined && typeof next !== "function" && typeof next !== "symbol")
+                        out[key] = canonical(next);
+                }
+                return out;
+            }
+            finally {
+                seen.delete(value);
+            }
+        };
+        return name + " " + JSON.stringify(canonical(input ?? {}));
     }
     catch {
         return name + " <unserializable>";
     }
 }
 /** Does a tool RESULT string look like a failure? hara tools report failures as ordinary strings
- *  (bash -> "Command failed: ...", file tools -> "Error: ...", net guard -> "Skipped without running: ..."),
- *  so the loop's isError flag alone misses them. Pure — exported for tests. */
-export function looksFailed(content) {
-    return /^\s*(Command failed|Error\b|Skipped without running)/.test(content);
+ *  (bash -> "Command failed: ...", file tools -> "Error: ...", safety gates -> "Blocked: ..."),
+ *  so the loop's isError flag alone misses them. Tool-specific shapes are intentionally keyed by `name`:
+ *  a read_file/web_fetch result can legitimately begin with prose such as "Search failed ..." and must not
+ *  be mistaken for the web_search tool's own diagnostic. Pure — exported for tests. */
+export function looksFailed(content, name) {
+    const text = content.trimStart();
+    if (/^(Command failed|Error:|Failed:|Blocked:|Skipped without running)/.test(text))
+        return true;
+    if (name === "web_search")
+        return /^Search failed across available providers\b/.test(text);
+    if (name === "external_agent") {
+        return /^(?:external_agent is disabled\b|Unknown backend\b|'[^'\r\n]+' CLI not found\b|\[[^\]\r\n]+\]\s+failed\b|\[[^\]\r\n]+\s+exit\s+(?!0\b)[^\]\r\n]+\])/.test(text);
+    }
+    if (name === "cronjob" || name === "cron")
+        return /^✗\s+\S+\s+failed\s*:/.test(text);
+    if (name === "computer") {
+        return /^(?:Refused:|Screen control is off\.|No apps allowlisted\b|Grounding needs a vision model\b|'[^'\r\n]+' needs a higher tier\b|(?:activate|find|click\/move) needs\b|⛔ Stopping screen control\b)/.test(text)
+            || /^Screenshot saved\b[\s\S]*\bConfigure a vision model\b/.test(text);
+    }
+    return false;
 }
 /** Record a completed call; returns a warning to APPEND to the tool result when the same call has now
  *  failed >=2x in a row (empty string otherwise). Pure aside from the session-scoped map. */
 export function recordCall(name, input, content, isError = false, scope) {
     const k = keyOf(name, input);
-    const failed = isError || looksFailed(content);
+    const failed = isError || looksFailed(content, name);
     const seen = scopedSeen(scope);
-    const s = seen.get(k) ?? { fails: 0 };
     if (!failed) {
-        seen.delete(k); // successes have no useful state; don't leak every unique tool call in a long-lived server
+        seen.clear(); // any success is progress; a later failure starts a fresh no-progress streak
         return "";
     }
+    const s = seen.get(k) ?? { fails: 0 };
     s.fails++;
-    seen.delete(k);
-    seen.set(k, s); // refresh insertion order for the bounded per-scope LRU
-    if (seen.size > 500)
-        seen.delete(seen.keys().next().value);
+    // "In a row" is literal: a different failed call is a changed attempt and breaks the old streak.
+    seen.clear();
+    seen.set(k, s);
     if (s.fails < 2)
         return "";
     return (`\n\n⟳ hara: this exact ${name} call has now FAILED ${s.fails}× with identical arguments — ` +

package/dist/checkpoints.js

@@ -10,6 +10,7 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { findProjectRoot } from "./context/agents-md.js";
+import { isHomeWorkspace } from "./context/workspace-scope.js";
 import { toolSubprocessEnv } from "./security/subprocess-env.js";
 import { sensitiveFileReason } from "./security/sensitive-files.js";
 import { redactSensitiveText } from "./security/secrets.js";
@@ -104,6 +105,10 @@ function dropSensitiveIndexEntries(root, gitDir) {
 }
 /** Snapshot the current working tree into the shadow repo. Returns the short sha, or null on failure. */
 export function checkpoint(cwd, label) {
+    // A shadow `git add -A` at ~/ would traverse the user's entire personal/control-data scope. Home is
+    // deliberately not an implicit project, including when reached through a symlink alias.
+    if (isHomeWorkspace(cwd))
+        return null;
     const root = findProjectRoot(cwd);
     const gitDir = shadowGitDir(root);
     if (!ensureRepo(root, gitDir))
@@ -133,6 +138,8 @@ export function checkpoint(cwd, label) {
 }
 /** Recent checkpoints, newest first. */
 export function listCheckpoints(cwd, n = 15) {
+    if (isHomeWorkspace(cwd))
+        return [];
     const root = findProjectRoot(cwd);
     const gitDir = shadowGitDir(root);
     if (!ensureRepo(root, gitDir) || !existsSync(join(gitDir, "HEAD")))
@@ -156,6 +163,8 @@ export function listCheckpoints(cwd, n = 15) {
 export function restoreCheckpoint(cwd, ref) {
     if (!/^[0-9a-f]{4,64}$/i.test(ref))
         return null; // checkpoint refs are hashes; reject option/ref injection
+    if (isHomeWorkspace(cwd))
+        return null;
     const root = findProjectRoot(cwd);
     const gitDir = shadowGitDir(root);
     if (!ensureRepo(root, gitDir) || !existsSync(join(gitDir, "HEAD")))

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Keep the runtime gate dependency-free and ahead of the main CLI import. Older Node releases must see an
 // actionable upgrade message even if a future dependency starts using syntax or APIs they cannot load.
-import { unsupportedNodeMessage } from "./runtime.js";
+import { applyPortableHomeEnv, unsupportedNodeMessage } from "./runtime.js";
 const runtimeError = unsupportedNodeMessage();
 if (runtimeError) {
     process.stderr.write(`${runtimeError}\n`);
     process.exitCode = 1;
 }
 else {
+    applyPortableHomeEnv();
     void import("./index.js").catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
         process.stderr.write(`hara: failed to start: ${message}\n`);

package/dist/config.js

@@ -1,9 +1,11 @@
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { agentMaxRounds, agentRunTimeoutMs } from "./agent/limits.js";
 import { ensurePrivateHaraState } from "./security/private-state.js";
 import { readVerifiedRegularFileSnapshotSync } from "./fs-read.js";
 import { projectRepositoryTrustedAtStartup } from "./security/project-trust.js";
+import { isHomeWorkspace } from "./context/workspace-scope.js";
 const PROVIDER_DEFAULTS = {
     anthropic: { model: "claude-opus-4-8", envKey: "ANTHROPIC_API_KEY" },
     qwen: {
@@ -33,7 +35,7 @@ const PROVIDER_DEFAULTS = {
     },
     "hara-gateway": { model: "", envKey: "HARA_GATEWAY_TOKEN" }, // B-end: enrolled device → token in ~/.hara/org.json, routed by the gateway
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high", "max"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -159,6 +161,10 @@ function readProjectConfig(cwd) {
         dir = resolve(cwd);
     }
     for (;;) {
+        // ~/.hara/config.json is the global control-plane file already loaded by loadConfig(). Never read it
+        // a second time as repository input, and never climb through Home into a parent repository.
+        if (isHomeWorkspace(dir))
+            break;
         const hara = join(dir, ".hara");
         const p = join(hara, "config.json");
         let haraInfo;
@@ -320,6 +326,8 @@ export function loadConfig(opts = {}) {
     const guardianRaw = process.env.HARA_GUARDIAN ?? merged.guardian;
     const guardian = guardianRaw === "0" || guardianRaw === "off" || guardianRaw === "false" ? "off" : "on";
     const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
+    const runTimeoutMs = agentRunTimeoutMs(process.env.HARA_RUN_TIMEOUT_MS ?? merged.runTimeoutMs);
+    const maxAgentRounds = agentMaxRounds(process.env.HARA_MAX_AGENT_ROUNDS ?? merged.maxAgentRounds);
     const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
     const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
@@ -332,7 +340,7 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high", "max"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/context/agents-md.js

@@ -3,6 +3,7 @@
 import { existsSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { readModelContextBytePrefixSync } from "../fs-read.js";
+import { homeWorkspaceGuidance, isHomeWorkspace } from "./workspace-scope.js";
 const FILENAMES = ["AGENTS.override.md", "AGENTS.md"];
 const ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
 const MAX_BYTES = 32 * 1024;
@@ -32,13 +33,23 @@ function markBudgetTruncation(value) {
     return utf8Prefix(value, MAX_BYTES - byteLength(TRUNCATED)) + TRUNCATED;
 }
 export function findProjectRoot(cwd) {
-    let dir = resolve(cwd);
+    const start = resolve(cwd);
+    // Home is a control/personal-data scope even when it happens to contain a package.json/.git marker.
+    // Resolve this before the marker check so `hara` launched at ~/ cannot inherit a parent repository
+    // through a symlinked/nested HOME used by managed development environments.
+    if (isHomeWorkspace(start))
+        return start;
+    let dir = start;
     for (;;) {
+        // A marker accidentally placed at ~/ (for example a personal package.json) must not make every
+        // unmarked child directory inherit the entire home as its project root. Explicit child scope stays local.
+        if (dir !== start && isHomeWorkspace(dir))
+            return start;
         if (ROOT_MARKERS.some((m) => existsSync(join(dir, m))))
             return dir;
         const parent = dirname(dir);
         if (parent === dir)
-            return resolve(cwd); // no marker found → treat cwd as root
+            return start; // no marker found → treat cwd as root
         dir = parent;
     }
 }
@@ -87,6 +98,14 @@ export function loadAgentsMd(cwd) {
     }
     return combined;
 }
+/** Model context is project AGENTS.md plus a built-in scope note when cwd is the user's home. Keeping the
+ *  built-in note separate from loadAgentsMd() preserves that function's file-loading semantics and lets the
+ *  UI accurately say whether an AGENTS.md file was actually loaded. */
+export function loadAgentContext(cwd) {
+    const guidance = homeWorkspaceGuidance(cwd);
+    const agents = loadAgentsMd(cwd);
+    return [guidance, agents].filter(Boolean).join("\n\n--- workspace-context ---\n\n");
+}
 export function hasAgentsMd(cwd) {
     const root = findProjectRoot(cwd);
     return FILENAMES.some((n) => existsSync(join(root, n)));

package/dist/context/mentions.js

@@ -2,11 +2,12 @@
 // and provide fuzzy file candidates for REPL tab-completion.
 import { existsSync, lstatSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
-import { listProjectFiles, dirPrefixes, walkFiles } from "../fs-walk.js";
+import { listProjectFiles, dirPrefixes, walkFiles, walkFilesAsync } from "../fs-walk.js";
 import { fuzzyRank } from "../fuzzy.js";
 import { mediaTypeFor } from "../images.js";
 import { readModelContextPrefixSync } from "../fs-read.js";
 import { sensitiveFileError } from "../security/sensitive-files.js";
+import { recursiveRootContainsHome, recursiveHomeSearchError } from "./workspace-scope.js";
 const MAX_FILE = 50_000;
 // @ at start-of-string or after whitespace; capture a path with no spaces/@ (avoids emails like a@b.com)
 const MENTION_RE = /(?:^|\s)@([^\s@]+)/g;
@@ -44,6 +45,86 @@ export function expandMentions(input, cwd) {
         return `${prefix}${block}`;
     });
 }
+/**
+ * Interruptible production variant. In particular, `@dir` uses the streaming async walker so mention
+ * expansion cannot block the event loop before an agent run's own deadline starts.
+ */
+export async function expandMentionsAsync(input, cwd, options = {}) {
+    const seen = new Set();
+    const mentionRe = new RegExp(MENTION_RE.source, MENTION_RE.flags);
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(0, Math.floor(options.timeoutMs)) : 2_000;
+    const startedAt = Date.now();
+    let output = "";
+    let copiedThrough = 0;
+    let match;
+    while ((match = mentionRe.exec(input)) !== null) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason instanceof Error ? options.signal.reason : new Error("mention expansion cancelled");
+        }
+        output += input.slice(copiedThrough, match.index);
+        copiedThrough = match.index + match[0].length;
+        const whole = match[0];
+        const ref = match[1];
+        const prefix = whole.slice(0, whole.length - ref.length - 1);
+        if (seen.has(ref)) {
+            output += whole;
+            continue;
+        }
+        const remainingMs = timeoutMs - (Date.now() - startedAt);
+        if (remainingMs <= 0) {
+            output += `${prefix}\nReferenced \`${ref}\` was not inserted because the ${timeoutMs}ms attachment budget was exhausted.\n`;
+            continue;
+        }
+        const block = await expandRefAsync(ref, cwd, {
+            ...options,
+            timeoutMs: remainingMs,
+            maxFiles: Math.min(options.maxFiles ?? 300, 300),
+        });
+        if (block === null)
+            output += whole;
+        else {
+            seen.add(ref);
+            output += `${prefix}${block}`;
+        }
+    }
+    return output + input.slice(copiedThrough);
+}
+async function expandRefAsync(ref, cwd, options) {
+    const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
+    const denied = sensitiveFileError(abs, "attach");
+    if (denied)
+        return `\nProtected file \`${ref}\` was not inserted into model context. ${denied}\n`;
+    try {
+        const st = lstatSync(abs);
+        if (st.isSymbolicLink())
+            return `Referenced \`${ref}\` is a symbolic link — it was not inserted into model context.`;
+        if (st.isFile()) {
+            if (mediaTypeFor(abs))
+                return `Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`;
+            const prefix = readModelContextPrefixSync(abs, MAX_FILE);
+            if (prefix.binary)
+                return `Referenced \`${ref}\` appears to be binary — it was not inserted into the model context.`;
+            const txt = prefix.text + (prefix.truncated ? "\n…[truncated]" : "");
+            return `\nReferenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\`\n`;
+        }
+        if (st.isDirectory()) {
+            if (recursiveRootContainsHome(abs))
+                return recursiveHomeSearchError("directory attachment");
+            const inventory = await walkFilesAsync(abs, options);
+            const bounded = inventory.truncated
+                ? `; listing stopped at its ${inventory.reason?.replace("_", " ") ?? "safety limit"}`
+                : "";
+            return `\nReferenced directory \`${ref}\` (${inventory.files.length} files${bounded}):\n\`\`\`\n${inventory.files.join("\n") || "(empty)"}\n\`\`\`\n`;
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason instanceof Error ? options.signal.reason : new Error("mention expansion cancelled");
+        }
+        /* ignore unreadable mention */
+    }
+    return null;
+}
 /** Render one mention as an inline block, or null if it isn't a readable file/dir. */
 function expandRef(ref, cwd) {
     const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
@@ -67,6 +148,8 @@ function expandRef(ref, cwd) {
             return `\nReferenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\`\n`;
         }
         if (st.isDirectory()) {
+            if (recursiveRootContainsHome(abs))
+                return recursiveHomeSearchError("directory attachment");
             // `@dir` loads a listing of the directory's files (the agent can then read specific ones)
             const files = walkFiles(abs, 300);
             return `\nReferenced directory \`${ref}\` (${files.length} files):\n\`\`\`\n${files.join("\n") || "(empty)"}\n\`\`\`\n`;

package/dist/context/workspace-scope.js

@@ -0,0 +1,49 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+/** Resolve existing paths through symlinks before comparing security/workspace scopes. Falling back to
+ *  resolve() keeps messages deterministic for a path that disappears during startup; normal cwd/home paths
+ *  exist and therefore take the realpath branch. */
+export function canonicalWorkspacePath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync.native(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** The user's home directory is a control/personal-data scope, not an implicit project workspace. */
+export function isHomeWorkspace(cwd, home = homedir()) {
+    return canonicalWorkspacePath(cwd) === canonicalWorkspacePath(home);
+}
+/** A recursive root is unsafe when it is Home itself OR an ancestor that would descend into Home. This
+ * closes `path: ".."`, filesystem-root, and symlink-alias bypasses while keeping an explicitly selected
+ * project child under Home usable. */
+export function recursiveRootContainsHome(root, home = homedir()) {
+    const canonicalRoot = canonicalWorkspacePath(root);
+    const canonicalHome = canonicalWorkspacePath(home);
+    const rel = relative(canonicalRoot, canonicalHome);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+export function homeWorkspaceActionError(action) {
+    return (`Refusing to ${action} from the home directory: it is not an implicit project workspace. ` +
+        "Run `cd /path/to/project` first.");
+}
+export function recursiveHomeSearchError(tool) {
+    return (`Error: ${tool} will not recursively scan the home directory. ` +
+        "Run Hara from a project (`cd /path/to/project`) or set `path` to a specific file/subdirectory. " +
+        "Non-recursive `ls` and explicit file reads remain available.");
+}
+/** Injected into model context when Hara was intentionally launched at ~/. Runtime checks enforce the same
+ *  policy, but guidance avoids wasting turns on calls that are guaranteed to be rejected. */
+export function homeWorkspaceGuidance(cwd) {
+    if (!isHomeWorkspace(cwd))
+        return "";
+    return ("# Home-directory workspace boundary\n" +
+        "The working directory resolves to the user's home directory, which is not an implicit project. " +
+        "Do not initialize a project, build a repository index, run shell/external executable tools, or recursively " +
+        "grep/glob/search the home root. " +
+        "Ask the user to run `cd /path/to/project` for project work. Non-recursive `ls`, explicitly named files, " +
+        "and explicitly named child directories remain available.");
+}

package/dist/cron/deliver.js

@@ -7,21 +7,36 @@
 //   weixin:<peerId>     (sends over stored ~/.hara/weixin creds — explicit peer required; guessing the
 //                        "owner" from a multi-DM context-token cache can deliver private results to the wrong person)
 // Adapters are imported LAZILY so the (heavy) SDKs never load unless a job actually delivers.
+import { outboundTransferTimeoutMs, withOutboundDeadline } from "../gateway/telegram.js";
 /** Parse a `--deliver` spec; error string on anything unsupported (listing what IS supported). */
 export function parseDeliver(spec) {
     const i = spec.indexOf(":");
     if (i <= 0)
-        return { error: `bad deliver spec "${spec}" — use telegram:<chatId>, feishu:<chatId>, weixin:<peerId>, or webhook:<url>` };
+        return { error: "bad deliver spec — use telegram:<chatId>, feishu:<chatId>, weixin:<peerId>, or webhook:<url>" };
     const platform = spec.slice(0, i).toLowerCase();
     const to = spec.slice(i + 1).trim();
     if (!to)
-        return { error: `deliver spec "${spec}" is missing a target after ":"` };
+        return { error: "deliver spec is missing a target after ':'" };
     if (platform === "weixin" && to.toLowerCase() === "owner") {
         return { error: "weixin:owner is ambiguous when several people have messaged the bot — use an explicit weixin:<peerId>" };
     }
     if (platform === "telegram" || platform === "feishu" || platform === "webhook" || platform === "weixin")
         return { platform, to };
-    return { error: `unsupported deliver platform "${platform}" — supported: telegram, feishu, weixin, webhook` };
+    return { error: "unsupported deliver platform — supported: telegram, feishu, weixin, webhook" };
+}
+function safeDeliveryError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const boundedLifecycle = /^(?:Gateway delivery|Webhook delivery|Telegram (?:send|upload)|Feishu (?:send|upload|recall)) (?:cancelled|timed out after \d+ms)$/u.exec(message);
+    if (boundedLifecycle)
+        return boundedLifecycle[0];
+    const telegramStatus = /^(Telegram [A-Za-z]+ failed: HTTP \d+)/u.exec(message);
+    if (telegramStatus)
+        return telegramStatus[1];
+    const controlledTransport = /^(?:Telegram [A-Za-z]+ transport failed|Feishu (?:auth transport failed|transport failed|auth failed: HTTP \d+(?: · code=\d+)?|request failed: HTTP \d+(?: · code=\d+)?))$/u.exec(message);
+    if (controlledTransport)
+        return controlledTransport[0];
+    // Opaque adapters and native fetch errors may contain the full target URL (including query credentials).
+    return "transport request failed";
 }
 /** Flatten markdown for plain-text chat surfaces (Feishu/WeChat/Telegram text messages render syntax
  *  literally): drop code fences/inline backticks/bold/headers, turn [text](url) into "text (url)". */
@@ -36,49 +51,57 @@ export function plainChat(text) {
         .replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
 }
 /** Send `text` to the target. Returns null on success, or an error string (never throws — cron
- *  delivery is best-effort and must not kill the tick). */
-export async function deliverResult(spec, text) {
+ * delivery is best-effort and must not kill the tick). `signal` ties one-shot adapters to their caller;
+ * the outer hard deadline also bounds adapters/SDKs that fail to cooperate with cancellation. */
+export async function deliverResult(spec, text, signal, idempotencyKey) {
     const t = parseDeliver(spec);
     if ("error" in t)
         return t.error;
     if (t.platform !== "webhook")
         text = plainChat(text); // chat surfaces are plain text; webhooks get raw payload
     try {
-        if (t.platform === "webhook") {
-            const r = await fetch(t.to, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({ source: "hara-cron", text }),
-                signal: AbortSignal.timeout(15_000),
-            });
-            return r.ok ? null : `webhook ${r.status}`;
-        }
-        if (t.platform === "telegram") {
-            const token = process.env.HARA_TELEGRAM_TOKEN;
-            if (!token)
-                return "HARA_TELEGRAM_TOKEN not set";
-            const { telegramAdapter } = await import("../gateway/telegram.js");
-            await telegramAdapter(token).send(t.to, text);
-            return null;
-        }
-        if (t.platform === "weixin") {
-            const { loadWeixinCreds, weixinAdapter } = await import("../gateway/weixin.js");
-            const creds = loadWeixinCreds();
-            if (!creds)
-                return "hara weixin not logged in (~/.hara/weixin/creds.json missing)";
-            await weixinAdapter(creds).send(t.to, text);
+        return await withOutboundDeadline("Gateway delivery", signal, outboundTransferTimeoutMs("text"), async (deliverySignal) => {
+            if (t.platform === "webhook") {
+                return withOutboundDeadline("Webhook delivery", deliverySignal, 15_000, async (webhookSignal) => {
+                    const r = await fetch(t.to, {
+                        method: "POST",
+                        headers: {
+                            "content-type": "application/json",
+                            ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+                        },
+                        body: JSON.stringify({ source: "hara-cron", text }),
+                        signal: webhookSignal,
+                    });
+                    return r.ok ? null : `webhook ${r.status}`;
+                });
+            }
+            if (t.platform === "telegram") {
+                const token = process.env.HARA_TELEGRAM_TOKEN;
+                if (!token)
+                    return "HARA_TELEGRAM_TOKEN not set";
+                const { telegramAdapter } = await import("../gateway/telegram.js");
+                await telegramAdapter(token).send(t.to, text, deliverySignal, idempotencyKey);
+                return null;
+            }
+            if (t.platform === "weixin") {
+                const { loadWeixinCreds, weixinAdapter } = await import("../gateway/weixin.js");
+                const creds = loadWeixinCreds();
+                if (!creds)
+                    return "hara weixin not logged in (~/.hara/weixin/creds.json missing)";
+                await weixinAdapter(creds).send(t.to, text, deliverySignal);
+                return null;
+            }
+            // feishu
+            const appId = process.env.HARA_FEISHU_APP_ID;
+            const appSecret = process.env.HARA_FEISHU_APP_SECRET;
+            if (!appId || !appSecret)
+                return "HARA_FEISHU_APP_ID / HARA_FEISHU_APP_SECRET not set";
+            const { feishuAdapter } = await import("../gateway/feishu.js");
+            await feishuAdapter(appId, appSecret).send(t.to, text, deliverySignal, idempotencyKey);
             return null;
-        }
-        // feishu
-        const appId = process.env.HARA_FEISHU_APP_ID;
-        const appSecret = process.env.HARA_FEISHU_APP_SECRET;
-        if (!appId || !appSecret)
-            return "HARA_FEISHU_APP_ID / HARA_FEISHU_APP_SECRET not set";
-        const { feishuAdapter } = await import("../gateway/feishu.js");
-        await feishuAdapter(appId, appSecret).send(t.to, text);
-        return null;
+        });
     }
     catch (e) {
-        return `delivery failed: ${e instanceof Error ? e.message : String(e)}`;
+        return `delivery failed: ${safeDeliveryError(e)}`;
     }
 }