larkin 0.5.16 → 0.5.17

package/dist/agent/context-prompt.cjs

@@ -12,11 +12,11 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 1. 明确目标与边界：每条规则写明“何时触发 / 做什么 / 禁止什么”，避免歧义与过度推断。
  * 2. 结构性信号优先于推断：能用来源/目标字段（如 thread target）做权威判定的，不要依赖模型从措辞推断。
  * 3. 精确 recipe：关键操作给完整命令模板 + 约束（如 exact literal、fail-closed、确定性 --jq 数据流）。
- * 4. 幂等与安全：idempotency、freshness 前置检查、不可重复提交、脱敏、失败可见（fail visibly）。
+ * 4. 幂等与安全：idempotency、非阻塞 freshness 提示、不可重复提交、脱敏、失败可见（fail visibly）。
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v33";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v34";
 /**
  * Pi 长命令引导的唯一来源。仅在当前工具列表出现 tmux-backed bash 时适用；
  * 不声明 tmux 一定可用，也不复述扩展的工具细节。
@@ -156,7 +156,7 @@ class ContextPromptBuilder {
             "Successful history response messages are always at `data.messages`. Never use a chat-wide fallback for a thread target, never merge stderr with `2>&1` before parsing JSON, and never truncate structured output before parsing it.",
             "If the scoped history read fails or its schema is invalid, fail visibly. Do not reuse remembered or hard-coded text to make the task appear successful.",
             "Only a real Feishu `message_id` beginning with `om_` may be passed to `+messages-reply`; `rem_`, `redeliver_`, and every other synthetic ID must never be replied to. Send with a confirmed `chat_id` and never guess a chat id from a display name.",
-            "Before every send/reply/card/recall write, Larkin probes the exact chat or thread history with the current Bot identity. A nonzero `freshness_conflict` includes bounded unseen context and direct-acks that cursor; reconsider it, then retry the ordinary command. Larkin never saves the blocked operation as a draft.",
+            "Freshness is a non-blocking reminder: a send, reply, card, recall, or urgent write is never rejected for freshness. After a successful write, stderr may contain a `larkin_notice` with `freshness`; the write already happened. Re-read the exact chat or thread with the Larkin command, and send a short follow-up only when newer context changes the answer. Never resend the same content merely because of this notice.",
             "For ordinary plain-text message bodies, use `--text`, including brief one-line replies, multiline status lines, and paragraphs. Use `--markdown` only when you intentionally need Markdown rendering, such as headings, lists, emphasis, blockquotes, fenced code, or Markdown links.",
             "When a URL must be visible, clickable, or openable by the recipient, include the complete bare `https://...` URL as visible text. Do not rely solely on `[label](URL)`, because Feishu client rendering is unreliable. A label may also be included, but the bare URL must remain present.",
             "Use native `--text` for ordinary plain text and for verbatim preservation, such as logs, literal code, or exact whitespace. Both `--markdown` and `--text` remain supported in the Larkin Runtime.",
@@ -166,7 +166,7 @@ class ContextPromptBuilder {
             `For a common exact send with a confirmed chat id, use the complete schematic recipe \`${executable} im +messages-send --chat-id <confirmed_chat_id> --text '<exact_body_as_one_literal_argument>' --json\`; replace each placeholder with the corresponding confirmed or exact literal value.`,
             `A reply's target is governed by the source's thread membership, a structural Inbox fact, not a guess. When the current Inbox event or poll identifies the source as a thread (\`thread:<chat_id>:<thread_id>\` target, or the polled message carries a \`thread_id\`), your reply MUST stay in that same thread: after the required poll use \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --reply-in-thread --json\`. For a chat-level source (no thread) with no explicit in-thread request, reply to the main timeline with the same recipe but omit \`--reply-in-thread\`; replace the placeholders only with the real \`om_\` id returned by that poll and the unchanged exact literal.`,
             `Use the \`--reply-in-thread\` recipe only when the source is a thread or the user or current Inbox event explicitly asks for a topic, in-thread, or thread reply. Never invent a topic request from ordinary reply wording or a bare source message id: the thread decision comes only from the source message's actual thread membership (\`thread:\` target or polled \`thread_id\`) or an explicit request, never from wording alone.`,
-            "This exact topic-reply recipe has exactly one post-poll model tool call and must not read or re-read a skill or reference, open help, or perform any other discovery. Without a `freshness_conflict` it uses two total model tool calls including the poll. If the first write instead returns a nonzero pre-commit, provider-not-reached `freshness_conflict`, reconsider its bounded context and, only if the exact operation remains unchanged, retry the identical command once; this is the only allowed extra call and produces exactly three total model tool calls including the poll.",
+            "This exact topic-reply recipe has exactly one post-poll model tool call and must not read or re-read a skill or reference, open help, or perform any other discovery. It uses two total model tool calls including the poll. A later freshness notice is advisory and must not cause a duplicate send.",
             "For tool-sourced exact or verbatim text from a Feishu result, do not copy or retype it into `--text`; you must use the deterministic native `--jq` to `--content` dataflow below.",
             "Choose exactly one source selector from the identifier the task starts with, and never switch selectors after reading. The inner read in the selected composite replaces any separate scoped history read; it must not follow a preview read.",
             "For a task that starts from a known thread and asks for its latest human content, after the required Inbox poll invoke the thread composite directly as the first and only post-poll model tool call. For this thread source, never preview or read the thread separately, extract a message id, switch to `+messages-mget`, or add a second source read.",
@@ -181,10 +181,10 @@ class ContextPromptBuilder {
             `The complete canonical exact send and reply paths above must not be preceded by \`${executable} im +messages-send --help\` or \`${executable} im +messages-reply --help\`; run these two known recipes directly.`,
             "For the known canonical Inbox poll, scoped chat/thread history, and exact send/reply recipes specified here, execute them directly; you must not read or re-read a skill file or reference merely to rediscover or confirm their command syntax.",
             `For a task that starts from an exact group name and asks for user and bot counts, after the required Inbox poll use this known canonical two-read recipe directly: first run \`${executable} im +chat-search --query '<exact_group_name>' --json\`, require one result with an exact name match and confirm its \`oc_\` chat id, then run \`${executable} im chats get --chat-id <confirmed_oc_chat_id> --json\` and answer from its \`user_count\` and \`bot_count\`. This group user/bot counts recipe uses exactly two post-poll business read calls; you must not read or re-read a skill or reference, open help or schema, invoke bare \`lark-cli\`, call \`chat.members\` or \`+chat-members-list\`, fall back to \`+chat-list\`, or add shell filters or output truncation. If the exact name is not a unique visible match, the chat id is not confirmed, or either count is missing, fail visibly without another discovery path or a guess.`,
-            "This narrow direct-recipe rule does not waive required skill safety gates, authorization, identity, freshness, or other safety checks. Unknown commands or high-risk operations still require the applicable skill/reference guidance or help.",
-            `To recall a message after the required explicit user approval, use \`${executable} im messages delete --message-id <bot-owned_om_id> --yes --json\`. Runtime verifies the original sender is this exact Bot, derives the exact chat/thread target, probes freshness before provider commit, and refuses cross-Agent or third-party messages. A \`committed=true\` or \`duplicate=true\` result must not be retried; an ambiguous result fails closed and requires user inspection. Never use generic API or bare \`lark-cli\` to bypass recall protection.`,
+            "This narrow direct-recipe rule does not waive required skill safety gates, authorization, identity, or other safety checks. Unknown commands or high-risk operations still require the applicable skill/reference guidance or help.",
+            `To recall a message after the required explicit user approval, use \`${executable} im messages delete --message-id <bot-owned_om_id> --yes --json\`. Runtime verifies the original sender is this exact Bot, derives the exact chat/thread target, and refuses cross-Agent or third-party messages. A \`committed=true\` or \`duplicate=true\` result must not be retried; an ambiguous result fails closed and requires user inspection. Never use generic API or bare \`lark-cli\` to bypass recall protection.`,
             "The Larkin wrapper derives the stable per-intent idempotency key; do not pass `--idempotency-key` in an ordinary send or reply recipe. A successful write result carrying `duplicate: true` means the provider returned the earlier delivery for the same derived key: the message was already delivered and no new message was created. Do not resend the same command after a `duplicate: true` result; treat the message as delivered. To deliberately send identical content again as a fresh intent (e.g., a new reminder), pass an explicit new `--idempotency-key`, which the wrapper respects instead of deriving its own.",
-            "Both `freshness_unavailable` and `freshness_conflict` are pre-commit, provider-not-reached results. If a retry is warranted for an unchanged exact operation, rerun the identical safe ordinary command: `--text` for a direct literal or the same deterministic `--content` dataflow for a tool source. The wrapper reuses its derived key. If the target or body changes after reconsideration, run the revised ordinary command and let the wrapper derive a new key. A result with `committed=true` must not be repeated; ambiguous termination follows the existing wrapper same-key recovery contract.",
+            "A `larkin_notice` freshness reminder is written to stderr only after the provider write has completed. Keep the successful write; re-read the target before any follow-up, and only send a revised follow-up if the new context materially changes the answer. A result with `committed=true` or `duplicate=true` must not be repeated; ambiguous termination follows the existing wrapper same-key recovery contract.",
             "For multiline `--markdown` or `--text` content in zsh or bash, prefer shell ANSI-C quoting so the command passes one argument with real newline characters: `--markdown $'First line\\nSecond line'` or `--text $'First line\\nSecond line'`. Putting `\"First line\\nSecond line\"` in ordinary double quotes is wrong: ordinary quotes do not decode `\\n`, so lark-cli and Feishu receive a backslash followed by the letter `n`. A literal multiline argument containing real newline characters is also valid. If ANSI-C-quoted content contains an apostrophe, use a safe shell single-quote splice or the literal-newline form; never use `eval`, `echo`, a temporary file, or unsafe variable interpolation to construct the body.",
             ...FEISHU_IM_COMMAND_GROUPS.map(([label, suffixes]) => `- ${label}: ${suffixes.map((suffix) => `\`${executable} ${suffix}\``).join(", ")}.`),
             `- Attachments: for an attachment-only send/reply, use its native attachment flag without a text body flag; download with \`${executable} im +messages-resources-download\`.`,

package/dist/agent/context-prompt.mjs

@@ -9,11 +9,11 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 1. 明确目标与边界：每条规则写明“何时触发 / 做什么 / 禁止什么”，避免歧义与过度推断。
  * 2. 结构性信号优先于推断：能用来源/目标字段（如 thread target）做权威判定的，不要依赖模型从措辞推断。
  * 3. 精确 recipe：关键操作给完整命令模板 + 约束（如 exact literal、fail-closed、确定性 --jq 数据流）。
- * 4. 幂等与安全：idempotency、freshness 前置检查、不可重复提交、脱敏、失败可见（fail visibly）。
+ * 4. 幂等与安全：idempotency、非阻塞 freshness 提示、不可重复提交、脱敏、失败可见（fail visibly）。
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v33";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v34";
 /**
  * Pi 长命令引导的唯一来源。仅在当前工具列表出现 tmux-backed bash 时适用；
  * 不声明 tmux 一定可用，也不复述扩展的工具细节。
@@ -153,7 +153,7 @@ export class ContextPromptBuilder {
             "Successful history response messages are always at `data.messages`. Never use a chat-wide fallback for a thread target, never merge stderr with `2>&1` before parsing JSON, and never truncate structured output before parsing it.",
             "If the scoped history read fails or its schema is invalid, fail visibly. Do not reuse remembered or hard-coded text to make the task appear successful.",
             "Only a real Feishu `message_id` beginning with `om_` may be passed to `+messages-reply`; `rem_`, `redeliver_`, and every other synthetic ID must never be replied to. Send with a confirmed `chat_id` and never guess a chat id from a display name.",
-            "Before every send/reply/card/recall write, Larkin probes the exact chat or thread history with the current Bot identity. A nonzero `freshness_conflict` includes bounded unseen context and direct-acks that cursor; reconsider it, then retry the ordinary command. Larkin never saves the blocked operation as a draft.",
+            "Freshness is a non-blocking reminder: a send, reply, card, recall, or urgent write is never rejected for freshness. After a successful write, stderr may contain a `larkin_notice` with `freshness`; the write already happened. Re-read the exact chat or thread with the Larkin command, and send a short follow-up only when newer context changes the answer. Never resend the same content merely because of this notice.",
             "For ordinary plain-text message bodies, use `--text`, including brief one-line replies, multiline status lines, and paragraphs. Use `--markdown` only when you intentionally need Markdown rendering, such as headings, lists, emphasis, blockquotes, fenced code, or Markdown links.",
             "When a URL must be visible, clickable, or openable by the recipient, include the complete bare `https://...` URL as visible text. Do not rely solely on `[label](URL)`, because Feishu client rendering is unreliable. A label may also be included, but the bare URL must remain present.",
             "Use native `--text` for ordinary plain text and for verbatim preservation, such as logs, literal code, or exact whitespace. Both `--markdown` and `--text` remain supported in the Larkin Runtime.",
@@ -163,7 +163,7 @@ export class ContextPromptBuilder {
             `For a common exact send with a confirmed chat id, use the complete schematic recipe \`${executable} im +messages-send --chat-id <confirmed_chat_id> --text '<exact_body_as_one_literal_argument>' --json\`; replace each placeholder with the corresponding confirmed or exact literal value.`,
             `A reply's target is governed by the source's thread membership, a structural Inbox fact, not a guess. When the current Inbox event or poll identifies the source as a thread (\`thread:<chat_id>:<thread_id>\` target, or the polled message carries a \`thread_id\`), your reply MUST stay in that same thread: after the required poll use \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --reply-in-thread --json\`. For a chat-level source (no thread) with no explicit in-thread request, reply to the main timeline with the same recipe but omit \`--reply-in-thread\`; replace the placeholders only with the real \`om_\` id returned by that poll and the unchanged exact literal.`,
             `Use the \`--reply-in-thread\` recipe only when the source is a thread or the user or current Inbox event explicitly asks for a topic, in-thread, or thread reply. Never invent a topic request from ordinary reply wording or a bare source message id: the thread decision comes only from the source message's actual thread membership (\`thread:\` target or polled \`thread_id\`) or an explicit request, never from wording alone.`,
-            "This exact topic-reply recipe has exactly one post-poll model tool call and must not read or re-read a skill or reference, open help, or perform any other discovery. Without a `freshness_conflict` it uses two total model tool calls including the poll. If the first write instead returns a nonzero pre-commit, provider-not-reached `freshness_conflict`, reconsider its bounded context and, only if the exact operation remains unchanged, retry the identical command once; this is the only allowed extra call and produces exactly three total model tool calls including the poll.",
+            "This exact topic-reply recipe has exactly one post-poll model tool call and must not read or re-read a skill or reference, open help, or perform any other discovery. It uses two total model tool calls including the poll. A later freshness notice is advisory and must not cause a duplicate send.",
             "For tool-sourced exact or verbatim text from a Feishu result, do not copy or retype it into `--text`; you must use the deterministic native `--jq` to `--content` dataflow below.",
             "Choose exactly one source selector from the identifier the task starts with, and never switch selectors after reading. The inner read in the selected composite replaces any separate scoped history read; it must not follow a preview read.",
             "For a task that starts from a known thread and asks for its latest human content, after the required Inbox poll invoke the thread composite directly as the first and only post-poll model tool call. For this thread source, never preview or read the thread separately, extract a message id, switch to `+messages-mget`, or add a second source read.",
@@ -178,10 +178,10 @@ export class ContextPromptBuilder {
             `The complete canonical exact send and reply paths above must not be preceded by \`${executable} im +messages-send --help\` or \`${executable} im +messages-reply --help\`; run these two known recipes directly.`,
             "For the known canonical Inbox poll, scoped chat/thread history, and exact send/reply recipes specified here, execute them directly; you must not read or re-read a skill file or reference merely to rediscover or confirm their command syntax.",
             `For a task that starts from an exact group name and asks for user and bot counts, after the required Inbox poll use this known canonical two-read recipe directly: first run \`${executable} im +chat-search --query '<exact_group_name>' --json\`, require one result with an exact name match and confirm its \`oc_\` chat id, then run \`${executable} im chats get --chat-id <confirmed_oc_chat_id> --json\` and answer from its \`user_count\` and \`bot_count\`. This group user/bot counts recipe uses exactly two post-poll business read calls; you must not read or re-read a skill or reference, open help or schema, invoke bare \`lark-cli\`, call \`chat.members\` or \`+chat-members-list\`, fall back to \`+chat-list\`, or add shell filters or output truncation. If the exact name is not a unique visible match, the chat id is not confirmed, or either count is missing, fail visibly without another discovery path or a guess.`,
-            "This narrow direct-recipe rule does not waive required skill safety gates, authorization, identity, freshness, or other safety checks. Unknown commands or high-risk operations still require the applicable skill/reference guidance or help.",
-            `To recall a message after the required explicit user approval, use \`${executable} im messages delete --message-id <bot-owned_om_id> --yes --json\`. Runtime verifies the original sender is this exact Bot, derives the exact chat/thread target, probes freshness before provider commit, and refuses cross-Agent or third-party messages. A \`committed=true\` or \`duplicate=true\` result must not be retried; an ambiguous result fails closed and requires user inspection. Never use generic API or bare \`lark-cli\` to bypass recall protection.`,
+            "This narrow direct-recipe rule does not waive required skill safety gates, authorization, identity, or other safety checks. Unknown commands or high-risk operations still require the applicable skill/reference guidance or help.",
+            `To recall a message after the required explicit user approval, use \`${executable} im messages delete --message-id <bot-owned_om_id> --yes --json\`. Runtime verifies the original sender is this exact Bot, derives the exact chat/thread target, and refuses cross-Agent or third-party messages. A \`committed=true\` or \`duplicate=true\` result must not be retried; an ambiguous result fails closed and requires user inspection. Never use generic API or bare \`lark-cli\` to bypass recall protection.`,
             "The Larkin wrapper derives the stable per-intent idempotency key; do not pass `--idempotency-key` in an ordinary send or reply recipe. A successful write result carrying `duplicate: true` means the provider returned the earlier delivery for the same derived key: the message was already delivered and no new message was created. Do not resend the same command after a `duplicate: true` result; treat the message as delivered. To deliberately send identical content again as a fresh intent (e.g., a new reminder), pass an explicit new `--idempotency-key`, which the wrapper respects instead of deriving its own.",
-            "Both `freshness_unavailable` and `freshness_conflict` are pre-commit, provider-not-reached results. If a retry is warranted for an unchanged exact operation, rerun the identical safe ordinary command: `--text` for a direct literal or the same deterministic `--content` dataflow for a tool source. The wrapper reuses its derived key. If the target or body changes after reconsideration, run the revised ordinary command and let the wrapper derive a new key. A result with `committed=true` must not be repeated; ambiguous termination follows the existing wrapper same-key recovery contract.",
+            "A `larkin_notice` freshness reminder is written to stderr only after the provider write has completed. Keep the successful write; re-read the target before any follow-up, and only send a revised follow-up if the new context materially changes the answer. A result with `committed=true` or `duplicate=true` must not be repeated; ambiguous termination follows the existing wrapper same-key recovery contract.",
             "For multiline `--markdown` or `--text` content in zsh or bash, prefer shell ANSI-C quoting so the command passes one argument with real newline characters: `--markdown $'First line\\nSecond line'` or `--text $'First line\\nSecond line'`. Putting `\"First line\\nSecond line\"` in ordinary double quotes is wrong: ordinary quotes do not decode `\\n`, so lark-cli and Feishu receive a backslash followed by the letter `n`. A literal multiline argument containing real newline characters is also valid. If ANSI-C-quoted content contains an apostrophe, use a safe shell single-quote splice or the literal-newline form; never use `eval`, `echo`, a temporary file, or unsafe variable interpolation to construct the body.",
             ...FEISHU_IM_COMMAND_GROUPS.map(([label, suffixes]) => `- ${label}: ${suffixes.map((suffix) => `\`${executable} ${suffix}\``).join(", ")}.`),
             `- Attachments: for an attachment-only send/reply, use its native attachment flag without a text body flag; download with \`${executable} im +messages-resources-download\`.`,

package/dist/app/agent-cli.mjs

@@ -119,7 +119,7 @@ function migrationError(group, subcommand) {
     if (group === "server")
         return "server 已移除；飞书（Lark）群与消息信息请通过 `larkin im ...` 查询。";
     if (group === "im")
-        return "请通过 `larkin im ...` 使用飞书（Lark）命令；Runtime 会自动绑定当前 Bot identity，并在写入前执行 freshness gate。可运行 `larkin im --help` 查看帮助。";
+        return "请通过 `larkin im ...` 使用飞书（Lark）命令；Runtime 会自动绑定当前 Bot identity，并在成功写入后给出非阻塞 freshness 提示。可运行 `larkin im --help` 查看帮助。";
     if (group === "profile" && subcommand !== "show") {
         return "profile 只保留只读的 `larkin profile show`；身份和凭证由 `larkin setup` 管理，不支持 update。";
     }

package/dist/app/cli.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { CONFIG_CLI_USAGE } from "../agent/config-cli-contract.mjs";
 import { internalCommandSpec } from "./internal-command.mjs";
 import { packageVersion } from "../platform/build-info.mjs";
+import { isLarkinRuntimeContext } from "./runtime-context.mjs";
 const command = process.argv[2] || "help";
 let rest = process.argv.slice(3);
 const PACKAGE_VERSION = packageVersion(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.."));
@@ -36,6 +37,18 @@ const routes = {
 };
 const runtimeAgentAuthority = typeof process.env.LARKIN_AGENT_ID === "string"
     && process.env.LARKIN_AGENT_ID.trim().length > 0;
+const runtimeContext = isLarkinRuntimeContext(process.env);
+// `config` deliberately remains a public operator surface: it supports global
+// and cross-Agent configuration, and it never falls through to `activeAgent`.
+const runtimeScopedCommands = new Set(["inbox", "reminder", "interaction", "profile", "comment"]);
+const missingRuntimeAuthority = (name) => {
+    console.error(`larkin: Runtime Agent authority is missing for "${command}" (LARKIN_AGENT_ID is required). `
+        + `Runtime context was detected (${name}); it will not fall back to the active Agent.`);
+    process.exit(2);
+};
+if (!runtimeAgentAuthority && runtimeScopedCommands.has(command)) {
+    missingRuntimeAuthority("agent-scoped command");
+}
 const runtimeAgentCommand = runtimeAgentAuthority
     && ["inbox", "reminder", "interaction", "profile", "config"].includes(command);
 if (runtimeAgentCommand)
@@ -107,6 +120,8 @@ const retiredPublicCommands = new Set(["pi-auth", "pi-distribution"]);
 const wantsHelp = command === "help" || command === "--help" || command === "-h"
     || (!runtimeAgentAuthority && command.startsWith("-"));
 if (!routes[command] && !wantsHelp && !retiredPublicCommands.has(command)) {
+    if (runtimeContext && !runtimeAgentAuthority)
+        missingRuntimeAuthority("Runtime marker");
     routes[command] = runtimeAgentAuthority ? ["lark-cli", command] : ["lark", command];
 }
 if (!routes[command]) {

package/dist/app/lark-cli.mjs

@@ -190,7 +190,7 @@ export function classifyLarkCliCommand(argv) {
         return { kind: "passthrough" };
     const protectedPaths = protectedOperations(argv);
     if (command === "larkin-draft")
-        return { kind: "denied", reason: "larkin-draft 已移除；freshness conflict 后请重新判断并执行普通写命令" };
+        return { kind: "denied", reason: "larkin-draft 已移除；请使用受 Runtime 身份与目标绑定保护的普通写命令" };
     if (exactPath(parsed.commandArgv, ["im", "+messages-send"]))
         return uniqueProtectedOperation(protectedPaths, "send")
             ? (parsed.flags.has("--thread-id")
@@ -223,21 +223,21 @@ export function classifyLarkCliCommand(argv) {
     if (exactPath(parsed.commandArgv, ["im", "messages", "create"]) || exactPath(parsed.commandArgv, ["im", "messages", "reply"])) {
         const expected = parsed.commandArgv[2] === "create" ? "raw-create" : "raw-reply";
         return uniqueProtectedOperation(protectedPaths, expected)
-            ? { kind: "denied", reason: "该原始 IM 写入口会旁路 target freshness；请使用 +messages-send/+messages-reply" }
+            ? { kind: "denied", reason: "该原始 IM 写入口会旁路 Runtime target binding；请使用 +messages-send/+messages-reply" }
             : noncanonicalProtectedDecision();
     }
     if (["forward", "merge_forward", "urgent_phone", "urgent_sms"]
         .some((operation) => exactPath(parsed.commandArgv, ["im", "messages", operation]))) {
         const expected = `raw-${parsed.commandArgv[2]}`;
         return uniqueProtectedOperation(protectedPaths, expected)
-            ? { kind: "denied", reason: "该 IM 写入口无法建立 target freshness；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
+            ? { kind: "denied", reason: "该 IM 写入口无法建立 Runtime target binding；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
             : noncanonicalProtectedDecision();
     }
     if (["forward", "merge_forward"]
         .some((operation) => exactPath(parsed.commandArgv, ["im", "threads", operation]))) {
         const expected = `thread-${parsed.commandArgv[2]}`;
         return uniqueProtectedOperation(protectedPaths, expected)
-            ? { kind: "denied", reason: "该 IM forwarding 入口无法建立 target freshness；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
+            ? { kind: "denied", reason: "该 IM forwarding 入口无法建立 Runtime target binding；请先用 larkin inbox poll 读取目标，再使用受保护的 +messages-send/+messages-reply" }
             : noncanonicalProtectedDecision();
     }
     if (command === "api")
@@ -347,8 +347,7 @@ function runCommentReply(argv, privateEnv, io, dependencies, store, agentId) {
     const target = targetKey ? parseDocumentCommentTarget(targetKey) : null;
     if (!target)
         throw new Error("comment reply 无法从当前 Agent Inbox 绑定文档评论 locator；先 poll 该消息且不得跨 Agent/评论回复");
-    if (!store.inboxTargetIsFresh(targetKey))
-        throw new Error("comment reply 需要先 poll 当前 document-comment target 的最新 Inbox 消息");
+    const staleCommentTarget = !store.inboxTargetIsFresh(targetKey);
     const digest = createHash("sha256").update(input.text).digest("hex");
     const ledgerKey = `${input.messageId}::${digest}`;
     const claim = store.mutateJson("freshnessState", { version: 1, cursors: {} }, (state) => {
@@ -421,6 +420,13 @@ function runCommentReply(argv, privateEnv, io, dependencies, store, agentId) {
         });
     }
     const committedWrite = !result.error && result.status === 0;
+    if (committedWrite && staleCommentTarget) {
+        io.stderr(`${JSON.stringify({
+            larkin_notice: "freshness",
+            target: targetKey,
+            hint: "Newer Inbox messages exist. Re-read the document comment context with larkin before sending a follow-up. Do not resend the same content.",
+        })}\n`);
+    }
     const currentReminder = committedWrite
         ? store.resolveCurrentReminders().filter((reminder) => reminder.deliveryTarget === targetKey).at(-1) ?? null
         : null;
@@ -464,9 +470,9 @@ function definitiveProviderRejection(result) {
     }
     return false;
 }
-function callNative(argv, env, io, dependencies) {
+function callNative(argv, env, io, dependencies, timeoutMs) {
     const native = dependencies.nativeCommand;
-    const result = (dependencies.spawn ?? spawnSync)(native?.command ?? resolveOfficialLarkCli({ spawn: dependencies.spawn, env }).command, [...(native?.argsPrefix ?? []), ...argv], { encoding: "utf8", env: { ...process.env, ...env } });
+    const result = (dependencies.spawn ?? spawnSync)(native?.command ?? resolveOfficialLarkCli({ spawn: dependencies.spawn, env }).command, [...(native?.argsPrefix ?? []), ...argv], { encoding: "utf8", env: { ...process.env, ...env }, ...(timeoutMs ? { timeout: timeoutMs } : {}) });
     return result;
 }
 function spawnNative(argv, env, io, dependencies) {
@@ -524,7 +530,7 @@ function guardedTarget(decision, argv, store) {
         const chatId = policyFlagValue(argv, "--chat-id");
         const userId = policyFlagValue(argv, "--user-id");
         if (!chatId || userId) {
-            throw new Error("Runtime +messages-send 必须只使用 Inbox 已确认的 --chat-id；--user-id 无法建立 freshness target");
+            throw new Error("Runtime +messages-send 必须使用已确认的 --chat-id；--user-id 无法建立受限 target binding");
         }
         return feishuImTarget(`chat:${chatId}`);
     }
@@ -533,7 +539,7 @@ function guardedTarget(decision, argv, store) {
         throw new Error(`${decision.operation} 写入缺少 --message-id`);
     const target = store.resolveInboxMessageTarget(messageId);
     if (!target)
-        throw new Error(`无法从 Inbox 状态确定 ${messageId} 的 target；先 poll 对应消息，禁止旁路 freshness`);
+        throw new Error(`无法从 Inbox 状态确定 ${messageId} 的 target；先 poll 对应消息，禁止旁路 target binding`);
     return feishuImTarget(target);
 }
 function recallLedgerEntry(store, messageId) {
@@ -889,22 +895,62 @@ function intentId(target, argv) {
         .update(JSON.stringify([target, argv])).digest("hex");
     return `larkin-${fingerprint.slice(0, 32)}`;
 }
-function emitFreshnessError(io, input) {
+function emitFreshnessNotice(io, input) {
     io.stderr(`${JSON.stringify({
-        ok: false,
-        identity: "bot",
-        error: { type: input.subtype === "freshness_conflict" ? "conflict" : "unavailable", subtype: input.subtype,
-            ...(input.reason ? { message: input.reason } : {}) },
+        larkin_notice: "freshness",
         target: input.target,
-        ...(input.current ? { current_cursor: input.current } : {}),
-        ...(input.messages ? { unseen_messages: input.messages } : {}),
-        next: "Reconsider the returned context, then retry the ordinary send/reply/card/recall command; history is probed again before every write.",
+        newer_messages: input.messages.length,
+        latest_message_ids: input.messages.map((message) => message.message_id),
+        hint: "Newer messages exist. Re-read this target with larkin and send a short follow-up only if they change your answer. Do not resend the same content.",
     })}\n`);
 }
 function freshnessGeneration(env) {
     return typeof env.LARKIN_RUNTIME_OBSERVATION_GENERATION === "string" && env.LARKIN_RUNTIME_OBSERVATION_GENERATION
         ? env.LARKIN_RUNTIME_OBSERVATION_GENERATION : "external";
 }
+// The post-write observation is advisory: cap it tightly so success is not
+// held hostage by a slow provider history response.
+const FRESHNESS_PROBE_TIMEOUT_MS = 500;
+function emitSoftFreshnessNotice(target, targetKey, seen, ownMessageId, env, io, dependencies, store) {
+    let timedOut = false;
+    try {
+        const gated = evaluateFreshness({
+            seen,
+            adapter: feishuImFreshnessAdapter,
+            probe: () => {
+                const result = callNative(probeArgv(target), env, io, dependencies, FRESHNESS_PROBE_TIMEOUT_MS);
+                const error = result.error;
+                timedOut = error?.code === "ETIMEDOUT"
+                    || error?.message.includes("ETIMEDOUT") === true
+                    || (result.status === null && result.signal === "SIGTERM");
+                return parseHistory(result, target, true);
+            },
+        });
+        if (gated.status === "unavailable") {
+            if (timedOut)
+                io.stderr(`lark-cli: freshness observation timed out after ${FRESHNESS_PROBE_TIMEOUT_MS}ms; no read position was recorded\n`);
+            return;
+        }
+        if (!seen && gated.status === "fresh" && gated.current) {
+            // A first authoritative observation establishes a quiet baseline from
+            // the provider's latest 20-message window, including messages that
+            // arrived while this write was in flight. This does not claim the Agent
+            // read those messages; it only enables change detection on later writes.
+            store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, freshnessGeneration(env));
+        }
+        if (gated.status !== "conflict")
+            return;
+        store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, freshnessGeneration(env));
+        const newer = gated.context.filter((message) => message.message_id !== ownMessageId);
+        if (newer.length)
+            emitFreshnessNotice(io, { target: targetKey, messages: newer });
+    }
+    catch {
+        // freshness 仅作提示：观察失败绝不能改变已完成写入的结果。
+        if (timedOut)
+            io.stderr(`lark-cli: freshness observation timed out after ${FRESHNESS_PROBE_TIMEOUT_MS}ms; no read position was recorded\n`);
+    }
+}
 function rawFlagValue(argv, flag) {
     const nativeArgv = nativeArgvBeforeBoundary(argv);
     const direct = nativeArgv.indexOf(flag);
@@ -1066,23 +1112,6 @@ function writeResponseMessage(result) {
         return null;
     }
 }
-function observeSuccessfulWrite(result, target, targetKey, store, generation) {
-    if (result.error || result.status !== 0)
-        return false;
-    try {
-        const candidate = writeResponseMessage(result);
-        if (!candidate)
-            return false;
-        const snapshot = parseHistory({ ...result, stdout: JSON.stringify({ ok: true, data: { messages: [candidate] } }) }, target);
-        const cursor = feishuImFreshnessAdapter.cursor(snapshot);
-        if (cursor)
-            store.mergeFreshnessCursor(targetKey, cursor, mergeFeishuImCursor, generation);
-        return cursor !== null;
-    }
-    catch {
-        return false;
-    }
-}
 function emitNativeResult(result, io) {
     if (result.stdout)
         io.stdout(result.stdout);
@@ -1125,35 +1154,6 @@ function emitDuplicatedRecall(io, messageId, target) {
     })}\n`);
     return 0;
 }
-function emitCommittedUnverified(result, io, input) {
-    let providerResponse;
-    try {
-        providerResponse = JSON.parse(result.stdout || "");
-    }
-    catch {
-        providerResponse = { raw_stdout: result.stdout || "" };
-    }
-    const providerDocument = providerResponse && typeof providerResponse === "object" && !Array.isArray(providerResponse)
-        ? providerResponse
-        : { provider_response: providerResponse };
-    io.stdout(`${JSON.stringify({
-        ...providerDocument,
-        ok: true,
-        committed: true,
-        verified: false,
-        cursor_advanced: false,
-        target: input.target,
-        verification: {
-            status: "unverified",
-            subtype: "post_write_unverified",
-            message: input.reason,
-            ...(input.current ? { current_cursor: input.current } : {}),
-            ...(input.messages ? { unseen_messages: input.messages } : {}),
-        },
-        ...(result.stderr ? { provider_stderr_present: true } : {}),
-    })}\n`);
-    return 0;
-}
 export function runLarkCli(argv, env = process.env, dependencies = {}) {
     const io = dependencies.io ?? defaultIo();
     let effectiveArgv = argv;
@@ -1235,20 +1235,6 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
         const targetKey = serializeFeishuImTarget(target);
         const generation = freshnessGeneration(privateEnv);
         const seen = store.readFreshnessCursor(targetKey, generation);
-        const gated = evaluateFreshness({
-            seen,
-            adapter: feishuImFreshnessAdapter,
-            probe: () => parseHistory(callNative(probeArgv(target), privateEnv, io, nativeDependencies), target, true),
-        });
-        if (gated.status === "unavailable") {
-            emitFreshnessError(io, { subtype: "freshness_unavailable", target: targetKey, reason: gated.reason });
-            return 3;
-        }
-        if (gated.status === "conflict") {
-            emitFreshnessError(io, { subtype: "freshness_conflict", target: targetKey, current: gated.current, messages: gated.context });
-            store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, generation);
-            return 3;
-        }
         if (decision.operation === "recall") {
             const claim = claimRecall(store, recallMessageId, targetKey);
             if (claim === "deleted")
@@ -1258,16 +1244,15 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
             }
             const recallWrite = callNative(botArgv(effectiveArgv, "", decision), privateEnv, io, nativeDependencies);
             if (!recallWrite.error && recallWrite.status === 0) {
-                const predictedSnapshot = {
-                    messages: gated.snapshot.messages.filter((message) => message.message_id !== recallMessageId),
-                };
-                const predictedCursor = feishuImFreshnessAdapter.cursor(predictedSnapshot);
-                finalizeSuccessfulRecall(store, recallMessageId, targetKey, predictedCursor, generation);
+                finalizeSuccessfulRecall(store, recallMessageId, targetKey, null, generation);
             }
             else if (definitiveProviderRejection(recallWrite)) {
                 finalizeFailedRecall(store, recallMessageId, targetKey);
             }
-            return emitNativeResult(recallWrite, io);
+            const code = emitNativeResult(recallWrite, io);
+            if (code === 0)
+                emitSoftFreshnessNotice(target, targetKey, seen, undefined, privateEnv, io, nativeDependencies, store);
+            return code;
         }
         if (decision.operation === "urgent-app") {
             const userIds = assertUrgentAppPreconditions(effectiveArgv, urgent.message, target, agent.feishuAppId);
@@ -1291,7 +1276,10 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
                 })}\n`);
                 return 2;
             }
-            return emitNativeResult(write, io);
+            const code = emitNativeResult(write, io);
+            if (code === 0)
+                emitSoftFreshnessNotice(target, targetKey, seen, writeResponseMessage(write)?.message_id, privateEnv, io, nativeDependencies, store);
+            return code;
         }
         const writeMessage = writeResponseMessage(write);
         const deliveryTarget = decision.operation === "send"
@@ -1331,40 +1319,10 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
             io.stderr(`lark-cli: reminder delivery audit failed: ${error instanceof Error ? error.message : String(error)}\n`);
         }
         const duplicate = memo.duplicate;
-        if (duplicate) {
-            observeSuccessfulWrite(write, target, targetKey, store, generation);
-            emitDuplicatedWrite(write, io, { target: targetKey });
-            return 0;
-        }
-        if (!write.error && write.status === 0 && !observeSuccessfulWrite(write, target, targetKey, store, generation)) {
-            const responseMessage = writeResponseMessage(write);
-            try {
-                const postSnapshot = parseHistory(callNative(probeArgv(target), privateEnv, io, nativeDependencies), target, true);
-                const postCursor = feishuImFreshnessAdapter.cursor(postSnapshot);
-                const unseenAfterWrite = feishuImFreshnessAdapter.unseen(gated.current, postSnapshot);
-                const confirmedOwnWrite = responseMessage && postCursor
-                    && unseenAfterWrite.some((message) => message.message_id === responseMessage.message_id)
-                    && unseenAfterWrite.every((message) => message.message_id === responseMessage.message_id);
-                if (!confirmedOwnWrite) {
-                    return emitCommittedUnverified(write, io, {
-                        target: targetKey,
-                        ...(postCursor ? { current: postCursor } : {}),
-                        messages: unseenAfterWrite,
-                        reason: responseMessage
-                            ? "provider write succeeded but bounded post-write probe found an additional concurrent update; cursor was not advanced"
-                            : "provider write succeeded without a message id/revision and bounded post-write probe could not identify the write; cursor was not advanced",
-                    });
-                }
-                store.mergeFreshnessCursor(targetKey, postCursor, mergeFeishuImCursor, generation);
-            }
-            catch {
-                return emitCommittedUnverified(write, io, {
-                    target: targetKey,
-                    reason: "provider write succeeded but bounded post-write confirmation was unavailable; cursor was not advanced",
-                });
-            }
-        }
-        return emitNativeResult(write, io);
+        const code = duplicate ? emitDuplicatedWrite(write, io, { target: targetKey }) : emitNativeResult(write, io);
+        if (code === 0)
+            emitSoftFreshnessNotice(target, targetKey, seen, writeMessage?.message_id, privateEnv, io, nativeDependencies, store);
+        return code;
     }
     catch (error) {
         io.stderr(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/app/lark.mjs

@@ -4,6 +4,20 @@ import { spawn } from "node:child_process";
 import * as larkinConfig from "../platform/config.mjs";
 import { assessPassthrough, PASSTHROUGH_USAGE } from "../feishu/lark-passthrough.mjs";
 import { managedOfficialLarkCli } from "./agent-lark-cli-workspace.mjs";
+import { isLarkinRuntimeContext } from "./runtime-context.mjs";
+const runtimeScopedCommands = new Set(["inbox", "reminder", "interaction", "profile", "comment"]);
+const requestedCommand = process.argv.slice(2).find((argument) => !argument.startsWith("-"));
+const runtimeContext = isLarkinRuntimeContext(process.env);
+if (!process.env.LARKIN_AGENT_ID && runtimeContext) {
+    console.error(`larkin: Runtime Agent authority is missing for "${requestedCommand ?? "lark-cli"}" (LARKIN_AGENT_ID is required). `
+        + "Runtime commands cannot fall back to the active Agent.");
+    process.exit(2);
+}
+if (!process.env.LARKIN_AGENT_ID && requestedCommand && runtimeScopedCommands.has(requestedCommand)) {
+    console.error(`larkin: Runtime Agent authority is missing for "${requestedCommand}" (LARKIN_AGENT_ID is required). `
+        + "Agent-scoped commands cannot fall back to the active Agent.");
+    process.exit(2);
+}
 const decision = assessPassthrough(process.argv.slice(2), process.env);
 if (!decision.ok) {
     console.error(`larkin: ${decision.reason}`);

package/dist/app/runtime-agent-config.mjs

@@ -240,18 +240,29 @@ function runOfficialLarkCliAsync(command, args, env, dependencies) {
         });
     });
 }
-function expectedRuntimeCommandShim() {
+function expectedRuntimeCommandShim(agent) {
     const standalone = process.env.LARKIN_STANDALONE === "1";
     const binaryEntry = fileURLToPath(new URL("./binary-entry.mjs", import.meta.url));
     const argumentsPrefix = standalone ? [] : [binaryEntry];
     const command = [process.execPath, ...argumentsPrefix].map(shellQuote).join(" ");
-    return `#!/bin/sh\nexec ${command} "$@"\n`;
+    const stateDir = path.resolve(agent.stateDir);
+    const configDir = path.resolve(stateDir, "../../..");
+    return [
+        "#!/bin/sh",
+        "export LARKIN_RUNTIME=1",
+        `export LARKIN_AGENT_ID=${shellQuote(agent.agentId)}`,
+        `export LARKIN_STATE_DIR=${shellQuote(stateDir)}`,
+        `export LARKIN_CONFIG_DIR=${shellQuote(configDir)}`,
+        `export LARKIN_HOME=${shellQuote(configDir)}`,
+        `exec ${command} "$@"`,
+        "",
+    ].join("\n");
 }
 export function installRuntimeCommandShims(agent) {
     const stateDir = path.resolve(agent.stateDir);
     const commandDir = path.join(stateDir, "runtime-bin");
     assertSecureRuntimeCommandDirectory(commandDir);
-    const fileContents = expectedRuntimeCommandShim();
+    const fileContents = expectedRuntimeCommandShim(agent);
     for (const name of ["larkin"]) {
         const file = path.join(commandDir, name);
         const temporary = path.join(commandDir, `.${name}.${process.pid}.${crypto.randomUUID()}.tmp`);
@@ -274,7 +285,7 @@ function validateRuntimeCommandShims(agent) {
         || (typeof process.getuid === "function" && stat.uid !== process.getuid())
         || (!exactMode(stat, 0o700) && !exactMode(stat, 0o500)))
         throw new Error("Runtime command shim 不安全");
-    if (fs.readFileSync(file, "utf8") !== expectedRuntimeCommandShim()) {
+    if (fs.readFileSync(file, "utf8") !== expectedRuntimeCommandShim(agent)) {
         throw new Error("Runtime command shim 内容无效");
     }
 }

package/dist/app/runtime-context.mjs

@@ -0,0 +1,17 @@
+function hasRuntimeBin(pathValue) {
+    if (!pathValue)
+        return false;
+    return pathValue.split(process.platform === "win32" ? ";" : ":")
+        .some((entry) => /(?:^|[\\/])runtime-bin$/.test(entry));
+}
+/**
+ * Runtime markers are deliberately independent of LARKIN_AGENT_ID. They keep a
+ * damaged Runtime environment from falling through to a terminal's activeAgent
+ * selection when its per-Agent identity has been stripped.
+ */
+export function isLarkinRuntimeContext(env = process.env) {
+    return env.LARKIN_RUNTIME === "1"
+        || Boolean(env.LARKIN_RUNTIME_OBSERVATION_GENERATION)
+        || Boolean(env.LARKIN_STATE_DIR)
+        || hasRuntimeBin(env.PATH);
+}

package/dist/feishu/im-freshness-adapter.cjs

@@ -60,7 +60,7 @@ exports.feishuImFreshnessAdapter = {
         if (!current)
             return seen ? "gap" : "fresh";
         if (!seen)
-            return "conflict";
+            return "fresh";
         const seenTime = integerMillis(seen.revisionTime);
         const currentTime = integerMillis(current.revisionTime);
         if (seen.schema !== 1 || seenTime === null || currentTime === null)
@@ -74,7 +74,7 @@ exports.feishuImFreshnessAdapter = {
     unseen(seen, snapshot) {
         const messages = normalizedMessages(snapshot);
         if (!seen)
-            return messages.map(({ revision: _revision, ...message }) => message);
+            return [];
         const seenTime = integerMillis(seen.revisionTime);
         if (seenTime === null)
             return messages.map(({ revision: _revision, ...message }) => message);

package/dist/feishu/im-freshness-adapter.mjs

@@ -53,7 +53,7 @@ export const feishuImFreshnessAdapter = {
         if (!current)
             return seen ? "gap" : "fresh";
         if (!seen)
-            return "conflict";
+            return "fresh";
         const seenTime = integerMillis(seen.revisionTime);
         const currentTime = integerMillis(current.revisionTime);
         if (seen.schema !== 1 || seenTime === null || currentTime === null)
@@ -67,7 +67,7 @@ export const feishuImFreshnessAdapter = {
     unseen(seen, snapshot) {
         const messages = normalizedMessages(snapshot);
         if (!seen)
-            return messages.map(({ revision: _revision, ...message }) => message);
+            return [];
         const seenTime = integerMillis(seen.revisionTime);
         if (seenTime === null)
             return messages.map(({ revision: _revision, ...message }) => message);

package/dist/runtime/runtime-host.cjs

@@ -308,6 +308,16 @@ function createRuntimeHost(options) {
         maxAttempts: options.retryPolicy?.maxAttempts ?? 6,
         stableWindowMs: options.retryPolicy?.stableWindowMs ?? 30_000,
     };
+    const turnEndRetryPolicy = {
+        baseDelayMs: options.turnEndRetryPolicy?.baseDelayMs ?? 1_000,
+        maxDelayMs: options.turnEndRetryPolicy?.maxDelayMs ?? 30_000,
+        maxAttempts: options.turnEndRetryPolicy?.maxAttempts ?? 3,
+    };
+    const turnEndRetryScheduler = options.turnEndRetryScheduler ?? {
+        now: Date.now,
+        setTimeout,
+        clearTimeout,
+    };
     const emit = (event) => {
         if (event.type === "delivery")
             telemetry?.delivery(event.agentId, event.messageId, event.status);
@@ -316,6 +326,7 @@ function createRuntimeHost(options) {
     };
     const runtimeEnv = (config, generation) => {
         const base = {
+            LARKIN_RUNTIME: "1",
             LARKIN_AGENT_ID: config.agentId,
             ...(generation ? {
                 LARKIN_RUNTIME_OBSERVATION_GENERATION: generation,
@@ -361,6 +372,8 @@ function createRuntimeHost(options) {
         record.updatedAt = now();
         agent.records.set(record.deliveryId, record);
         agent.byMessage.set(record.messageId, record.deliveryId);
+        if (status === "consumed" || status === "error")
+            clearPendingRetryTimerWhenIdle(agent);
         emitConsumed(agent, persist(agent));
         return agent.records.get(record.deliveryId) ?? record;
     };
@@ -466,8 +479,42 @@ function createRuntimeHost(options) {
                 emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: next.deliveryId, messageId: next.messageId, status: "consumed" });
             }
         }
+        clearPendingRetryTimerWhenIdle(agent);
     };
     const TURN_END_RETRY_REASON = "runtime turn ended before Inbox consumption was observed";
+    const turnEndRetryDelayMs = (attempt) => Math.min(turnEndRetryPolicy.maxDelayMs, turnEndRetryPolicy.baseDelayMs * 2 ** (attempt - 1));
+    const isRetryDue = (record) => !record.retryNotBefore || Number.isNaN(Date.parse(record.retryNotBefore))
+        || Date.parse(record.retryNotBefore) <= turnEndRetryScheduler.now();
+    const clearDeliveryRetryTimer = (agent) => {
+        if (!agent.deliveryRetryTimer)
+            return;
+        turnEndRetryScheduler.clearTimeout(agent.deliveryRetryTimer);
+        agent.deliveryRetryTimer = null;
+    };
+    function clearPendingRetryTimerWhenIdle(agent) {
+        if (!agent.deliveryRetryTimer)
+            return;
+        if ([...agent.records.values()].some((record) => record.status === "pending" && record.retryNotBefore))
+            return;
+        clearDeliveryRetryTimer(agent);
+    }
+    const schedulePendingRetry = (agent) => {
+        if (agent.stopped || agent.deliveryRetryTimer)
+            return;
+        const next = [...agent.records.values()]
+            .filter((record) => record.status === "pending" && record.retryNotBefore)
+            .map((record) => Date.parse(record.retryNotBefore))
+            .filter((at) => Number.isFinite(at))
+            .sort((left, right) => left - right)[0];
+        if (next === undefined)
+            return;
+        const delay = Math.max(0, next - turnEndRetryScheduler.now());
+        agent.deliveryRetryTimer = turnEndRetryScheduler.setTimeout(() => {
+            agent.deliveryRetryTimer = null;
+            void retryPending(agent);
+        }, delay);
+        agent.deliveryRetryTimer.unref?.();
+    };
     const INBOX_UPDATE_PROMOTE_REASON = "accepted inbox_update promoted after Agent became idle";
     const isInboxUpdateKind = (kind) => kind === "inbox_update" || kind === "inbox-update";
     const agentIsIdleForInboxScan = (agent) => !agent.stopped && !agent.busy && !agent.submitting && !agent.turnInProgress && !agent.starting && Boolean(agent.session);
@@ -495,13 +542,32 @@ function createRuntimeHost(options) {
             for (const record of agent.records.values()) {
                 if (record.status !== "accepted")
                     continue;
-                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
-                    messageId: record.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
-            }
+                const attempts = record.turnEndRetryAttempts ?? 0;
+                if (attempts >= turnEndRetryPolicy.maxAttempts) {
+                    record.reason = `turn-end redelivery exhausted after ${turnEndRetryPolicy.maxAttempts} attempts`;
+                    record.retryable = false;
+                    const terminal = setRecord(agent, record, "error");
+                    emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: terminal.deliveryId,
+                        messageId: terminal.messageId, status: "error", reason: terminal.reason });
+                    continue;
+                }
+                const attempt = attempts + 1;
+                const delay = turnEndRetryDelayMs(attempt);
+                record.turnEndRetryAttempts = attempt;
+                record.retryNotBefore = new Date(turnEndRetryScheduler.now() + delay).toISOString();
+                record.reason = TURN_END_RETRY_REASON;
+                record.retryable = true;
+                record.input = { ...record.input, attempt: (record.input.attempt ?? 0) + 1 };
+                const deferred = setRecord(agent, record, "pending");
+                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: deferred.deliveryId,
+                    messageId: deferred.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
+            }
+            schedulePendingRetry(agent);
             return;
         }
         const consumed = [];
         const deferred = [];
+        const exhausted = [];
         try {
             store.withInboxTransaction(() => {
                 const inboxIds = new Set(store.readNdjson("inbox").flatMap((row) => typeof row?.message_id === "string" ? [row.message_id] : []));
@@ -522,8 +588,31 @@ function createRuntimeHost(options) {
                     if (current.status !== "accepted" || candidate.status !== "accepted" || !inboxIds.has(candidate.messageId)) {
                         return candidate;
                     }
-                    const next = { ...candidate, status: "pending", updatedAt: now(),
-                        reason: TURN_END_RETRY_REASON, retryable: true };
+                    const attempts = candidate.turnEndRetryAttempts ?? 0;
+                    if (attempts >= turnEndRetryPolicy.maxAttempts) {
+                        const terminal = { ...candidate, status: "error", updatedAt: now(),
+                            reason: `turn-end redelivery exhausted after ${turnEndRetryPolicy.maxAttempts} attempts`,
+                            retryable: false };
+                        changed = true;
+                        pendingUpdates.push(terminal);
+                        return terminal;
+                    }
+                    const attempt = attempts + 1;
+                    const delay = turnEndRetryDelayMs(attempt);
+                    const staleInput = candidate.input && typeof candidate.input === "object" ? candidate.input : null;
+                    const next = {
+                        ...candidate,
+                        status: "pending",
+                        updatedAt: now(),
+                        reason: TURN_END_RETRY_REASON,
+                        retryable: true,
+                        turnEndRetryAttempts: attempt,
+                        retryNotBefore: new Date(turnEndRetryScheduler.now() + delay).toISOString(),
+                        input: {
+                            ...(staleInput ?? { inputId: candidate.deliveryId, deliveryId: candidate.deliveryId, kind: "wake", text: "" }),
+                            attempt: (Number.isSafeInteger(staleInput?.attempt) && Number(staleInput?.attempt) >= 0 ? Number(staleInput.attempt) : 0) + 1,
+                        },
+                    };
                     changed = true;
                     pendingUpdates.push(next);
                     return next;
@@ -532,7 +621,10 @@ function createRuntimeHost(options) {
                     store.writeJson("runtimeDeliveries", { ...disk, records });
                     for (const next of pendingUpdates) {
                         agent.records.set(next.deliveryId, next);
-                        deferred.push(next);
+                        if (next.status === "error")
+                            exhausted.push(next);
+                        else
+                            deferred.push(next);
                     }
                 }
             });
@@ -545,6 +637,11 @@ function createRuntimeHost(options) {
         for (const record of deferred)
             emit({ type: "delivery", agentId: agent.config.agentId,
                 deliveryId: record.deliveryId, messageId: record.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
+        for (const record of exhausted)
+            emit({ type: "delivery", agentId: agent.config.agentId,
+                deliveryId: record.deliveryId, messageId: record.messageId, status: "error", reason: record.reason });
+        if (deferred.length)
+            schedulePendingRetry(agent);
     };
     // Production callers persist the canonical Inbox before calling deliver(). If a
     // concurrent drain wins between that append and ledger creation, close only the
@@ -743,9 +840,11 @@ function createRuntimeHost(options) {
                 if (idleGate)
                     await idleGate;
             }
-            const record = [...agent.records.values()].find((candidate) => candidate.status === "pending" || candidate.status === "submitting");
+            const record = [...agent.records.values()].find((candidate) => (candidate.status === "pending" && isRetryDue(candidate)) || candidate.status === "submitting");
             if (record)
                 await submit(agent, record, false);
+            else
+                schedulePendingRetry(agent);
         })();
         agent.retryPendingInFlight = run;
         try {
@@ -1519,6 +1618,8 @@ function createRuntimeHost(options) {
                         clearInterval(previous.poller);
                     if (previous.retryTimer)
                         clearTimeout(previous.retryTimer);
+                    if (previous.deliveryRetryTimer)
+                        turnEndRetryScheduler.clearTimeout(previous.deliveryRetryTimer);
                     if (previous.stabilityTimer)
                         clearTimeout(previous.stabilityTimer);
                     const previousFailure = currentAuthFailure(previous);
@@ -1530,7 +1631,7 @@ function createRuntimeHost(options) {
                         }, previousFailure));
                     const candidate = {
                         ...previous, config, adapter, session, launchId: node_crypto_1.default.randomUUID(), busy: false, submitting: false,
-                        starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
+                        starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null, deliveryRetryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
                         disabledReason: null, configurationRecovery: null,
                         authFailureActive: scoped && previous.authFailureActive,
@@ -1623,6 +1724,7 @@ function createRuntimeHost(options) {
                 if (pendingAfterCreate > 0) {
                     throw new RuntimeSessionResetError("inbox_backlog", `Agent ${agentId} received Inbox backlog during reset`, pendingAfterCreate);
                 }
+                clearDeliveryRetryTimer(agent);
                 agent.generation += 1;
                 agent.launchId = node_crypto_1.default.randomUUID();
                 agent.config.sessionId = null;
@@ -1893,7 +1995,7 @@ function createRuntimeHost(options) {
                     retryPendingInFlight: null,
                     records: new Map(persisted.records.map((record) => [record.deliveryId, record])),
                     byMessage: new Map(persisted.records.map((record) => [record.messageId, record.deliveryId])),
-                    generation: 0, poller: null, retryTimer: null, recreateAttempts: 0,
+                    generation: 0, poller: null, retryTimer: null, deliveryRetryTimer: null, recreateAttempts: 0,
                     stabilityTimer: null, recreateReason: null, stopped: false, disabledReason: null,
                     configurationRecovery: null, stateStore,
                     compactionBreaker: config.runtime === "pi" && stateStore
@@ -2065,6 +2167,7 @@ function createRuntimeHost(options) {
                 clearInterval(agent.poller);
             if (agent.retryTimer)
                 clearTimeout(agent.retryTimer);
+            clearDeliveryRetryTimer(agent);
             if (agent.stabilityTimer)
                 clearTimeout(agent.stabilityTimer);
             if (agent.busy)

package/dist/runtime/runtime-host.mjs

@@ -299,6 +299,16 @@ export function createRuntimeHost(options) {
         maxAttempts: options.retryPolicy?.maxAttempts ?? 6,
         stableWindowMs: options.retryPolicy?.stableWindowMs ?? 30_000,
     };
+    const turnEndRetryPolicy = {
+        baseDelayMs: options.turnEndRetryPolicy?.baseDelayMs ?? 1_000,
+        maxDelayMs: options.turnEndRetryPolicy?.maxDelayMs ?? 30_000,
+        maxAttempts: options.turnEndRetryPolicy?.maxAttempts ?? 3,
+    };
+    const turnEndRetryScheduler = options.turnEndRetryScheduler ?? {
+        now: Date.now,
+        setTimeout,
+        clearTimeout,
+    };
     const emit = (event) => {
         if (event.type === "delivery")
             telemetry?.delivery(event.agentId, event.messageId, event.status);
@@ -307,6 +317,7 @@ export function createRuntimeHost(options) {
     };
     const runtimeEnv = (config, generation) => {
         const base = {
+            LARKIN_RUNTIME: "1",
             LARKIN_AGENT_ID: config.agentId,
             ...(generation ? {
                 LARKIN_RUNTIME_OBSERVATION_GENERATION: generation,
@@ -352,6 +363,8 @@ export function createRuntimeHost(options) {
         record.updatedAt = now();
         agent.records.set(record.deliveryId, record);
         agent.byMessage.set(record.messageId, record.deliveryId);
+        if (status === "consumed" || status === "error")
+            clearPendingRetryTimerWhenIdle(agent);
         emitConsumed(agent, persist(agent));
         return agent.records.get(record.deliveryId) ?? record;
     };
@@ -457,8 +470,42 @@ export function createRuntimeHost(options) {
                 emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: next.deliveryId, messageId: next.messageId, status: "consumed" });
             }
         }
+        clearPendingRetryTimerWhenIdle(agent);
     };
     const TURN_END_RETRY_REASON = "runtime turn ended before Inbox consumption was observed";
+    const turnEndRetryDelayMs = (attempt) => Math.min(turnEndRetryPolicy.maxDelayMs, turnEndRetryPolicy.baseDelayMs * 2 ** (attempt - 1));
+    const isRetryDue = (record) => !record.retryNotBefore || Number.isNaN(Date.parse(record.retryNotBefore))
+        || Date.parse(record.retryNotBefore) <= turnEndRetryScheduler.now();
+    const clearDeliveryRetryTimer = (agent) => {
+        if (!agent.deliveryRetryTimer)
+            return;
+        turnEndRetryScheduler.clearTimeout(agent.deliveryRetryTimer);
+        agent.deliveryRetryTimer = null;
+    };
+    function clearPendingRetryTimerWhenIdle(agent) {
+        if (!agent.deliveryRetryTimer)
+            return;
+        if ([...agent.records.values()].some((record) => record.status === "pending" && record.retryNotBefore))
+            return;
+        clearDeliveryRetryTimer(agent);
+    }
+    const schedulePendingRetry = (agent) => {
+        if (agent.stopped || agent.deliveryRetryTimer)
+            return;
+        const next = [...agent.records.values()]
+            .filter((record) => record.status === "pending" && record.retryNotBefore)
+            .map((record) => Date.parse(record.retryNotBefore))
+            .filter((at) => Number.isFinite(at))
+            .sort((left, right) => left - right)[0];
+        if (next === undefined)
+            return;
+        const delay = Math.max(0, next - turnEndRetryScheduler.now());
+        agent.deliveryRetryTimer = turnEndRetryScheduler.setTimeout(() => {
+            agent.deliveryRetryTimer = null;
+            void retryPending(agent);
+        }, delay);
+        agent.deliveryRetryTimer.unref?.();
+    };
     const INBOX_UPDATE_PROMOTE_REASON = "accepted inbox_update promoted after Agent became idle";
     const isInboxUpdateKind = (kind) => kind === "inbox_update" || kind === "inbox-update";
     const agentIsIdleForInboxScan = (agent) => !agent.stopped && !agent.busy && !agent.submitting && !agent.turnInProgress && !agent.starting && Boolean(agent.session);
@@ -486,13 +533,32 @@ export function createRuntimeHost(options) {
             for (const record of agent.records.values()) {
                 if (record.status !== "accepted")
                     continue;
-                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: record.deliveryId,
-                    messageId: record.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
-            }
+                const attempts = record.turnEndRetryAttempts ?? 0;
+                if (attempts >= turnEndRetryPolicy.maxAttempts) {
+                    record.reason = `turn-end redelivery exhausted after ${turnEndRetryPolicy.maxAttempts} attempts`;
+                    record.retryable = false;
+                    const terminal = setRecord(agent, record, "error");
+                    emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: terminal.deliveryId,
+                        messageId: terminal.messageId, status: "error", reason: terminal.reason });
+                    continue;
+                }
+                const attempt = attempts + 1;
+                const delay = turnEndRetryDelayMs(attempt);
+                record.turnEndRetryAttempts = attempt;
+                record.retryNotBefore = new Date(turnEndRetryScheduler.now() + delay).toISOString();
+                record.reason = TURN_END_RETRY_REASON;
+                record.retryable = true;
+                record.input = { ...record.input, attempt: (record.input.attempt ?? 0) + 1 };
+                const deferred = setRecord(agent, record, "pending");
+                emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: deferred.deliveryId,
+                    messageId: deferred.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
+            }
+            schedulePendingRetry(agent);
             return;
         }
         const consumed = [];
         const deferred = [];
+        const exhausted = [];
         try {
             store.withInboxTransaction(() => {
                 const inboxIds = new Set(store.readNdjson("inbox").flatMap((row) => typeof row?.message_id === "string" ? [row.message_id] : []));
@@ -513,8 +579,31 @@ export function createRuntimeHost(options) {
                     if (current.status !== "accepted" || candidate.status !== "accepted" || !inboxIds.has(candidate.messageId)) {
                         return candidate;
                     }
-                    const next = { ...candidate, status: "pending", updatedAt: now(),
-                        reason: TURN_END_RETRY_REASON, retryable: true };
+                    const attempts = candidate.turnEndRetryAttempts ?? 0;
+                    if (attempts >= turnEndRetryPolicy.maxAttempts) {
+                        const terminal = { ...candidate, status: "error", updatedAt: now(),
+                            reason: `turn-end redelivery exhausted after ${turnEndRetryPolicy.maxAttempts} attempts`,
+                            retryable: false };
+                        changed = true;
+                        pendingUpdates.push(terminal);
+                        return terminal;
+                    }
+                    const attempt = attempts + 1;
+                    const delay = turnEndRetryDelayMs(attempt);
+                    const staleInput = candidate.input && typeof candidate.input === "object" ? candidate.input : null;
+                    const next = {
+                        ...candidate,
+                        status: "pending",
+                        updatedAt: now(),
+                        reason: TURN_END_RETRY_REASON,
+                        retryable: true,
+                        turnEndRetryAttempts: attempt,
+                        retryNotBefore: new Date(turnEndRetryScheduler.now() + delay).toISOString(),
+                        input: {
+                            ...(staleInput ?? { inputId: candidate.deliveryId, deliveryId: candidate.deliveryId, kind: "wake", text: "" }),
+                            attempt: (Number.isSafeInteger(staleInput?.attempt) && Number(staleInput?.attempt) >= 0 ? Number(staleInput.attempt) : 0) + 1,
+                        },
+                    };
                     changed = true;
                     pendingUpdates.push(next);
                     return next;
@@ -523,7 +612,10 @@ export function createRuntimeHost(options) {
                     store.writeJson("runtimeDeliveries", { ...disk, records });
                     for (const next of pendingUpdates) {
                         agent.records.set(next.deliveryId, next);
-                        deferred.push(next);
+                        if (next.status === "error")
+                            exhausted.push(next);
+                        else
+                            deferred.push(next);
                     }
                 }
             });
@@ -536,6 +628,11 @@ export function createRuntimeHost(options) {
         for (const record of deferred)
             emit({ type: "delivery", agentId: agent.config.agentId,
                 deliveryId: record.deliveryId, messageId: record.messageId, status: "deferred", reason: TURN_END_RETRY_REASON });
+        for (const record of exhausted)
+            emit({ type: "delivery", agentId: agent.config.agentId,
+                deliveryId: record.deliveryId, messageId: record.messageId, status: "error", reason: record.reason });
+        if (deferred.length)
+            schedulePendingRetry(agent);
     };
     // Production callers persist the canonical Inbox before calling deliver(). If a
     // concurrent drain wins between that append and ledger creation, close only the
@@ -734,9 +831,11 @@ export function createRuntimeHost(options) {
                 if (idleGate)
                     await idleGate;
             }
-            const record = [...agent.records.values()].find((candidate) => candidate.status === "pending" || candidate.status === "submitting");
+            const record = [...agent.records.values()].find((candidate) => (candidate.status === "pending" && isRetryDue(candidate)) || candidate.status === "submitting");
             if (record)
                 await submit(agent, record, false);
+            else
+                schedulePendingRetry(agent);
         })();
         agent.retryPendingInFlight = run;
         try {
@@ -1510,6 +1609,8 @@ export function createRuntimeHost(options) {
                         clearInterval(previous.poller);
                     if (previous.retryTimer)
                         clearTimeout(previous.retryTimer);
+                    if (previous.deliveryRetryTimer)
+                        turnEndRetryScheduler.clearTimeout(previous.deliveryRetryTimer);
                     if (previous.stabilityTimer)
                         clearTimeout(previous.stabilityTimer);
                     const previousFailure = currentAuthFailure(previous);
@@ -1521,7 +1622,7 @@ export function createRuntimeHost(options) {
                         }, previousFailure));
                     const candidate = {
                         ...previous, config, adapter, session, launchId: crypto.randomUUID(), busy: false, submitting: false,
-                        starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
+                        starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null, deliveryRetryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
                         disabledReason: null, configurationRecovery: null,
                         authFailureActive: scoped && previous.authFailureActive,
@@ -1614,6 +1715,7 @@ export function createRuntimeHost(options) {
                 if (pendingAfterCreate > 0) {
                     throw new RuntimeSessionResetError("inbox_backlog", `Agent ${agentId} received Inbox backlog during reset`, pendingAfterCreate);
                 }
+                clearDeliveryRetryTimer(agent);
                 agent.generation += 1;
                 agent.launchId = crypto.randomUUID();
                 agent.config.sessionId = null;
@@ -1884,7 +1986,7 @@ export function createRuntimeHost(options) {
                     retryPendingInFlight: null,
                     records: new Map(persisted.records.map((record) => [record.deliveryId, record])),
                     byMessage: new Map(persisted.records.map((record) => [record.messageId, record.deliveryId])),
-                    generation: 0, poller: null, retryTimer: null, recreateAttempts: 0,
+                    generation: 0, poller: null, retryTimer: null, deliveryRetryTimer: null, recreateAttempts: 0,
                     stabilityTimer: null, recreateReason: null, stopped: false, disabledReason: null,
                     configurationRecovery: null, stateStore,
                     compactionBreaker: config.runtime === "pi" && stateStore
@@ -2056,6 +2158,7 @@ export function createRuntimeHost(options) {
                 clearInterval(agent.poller);
             if (agent.retryTimer)
                 clearTimeout(agent.retryTimer);
+            clearDeliveryRetryTimer(agent);
             if (agent.stabilityTimer)
                 clearTimeout(agent.stabilityTimer);
             if (agent.busy)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkin",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [