larkin 0.4.20 → 0.4.22

package/dist/agent/agent-cli-capabilities.cjs

@@ -12,7 +12,7 @@ const internal_command_js_1 = require("../app/internal-command.cjs");
 exports.AGENT_CLI_CAPABILITIES = Object.freeze({
     version: 1,
     commands: Object.freeze({
-        inbox: Object.freeze(["check", "poll"]),
+        inbox: Object.freeze(["check", "poll", "audit"]),
         comment: Object.freeze(["reply"]),
         reminder: Object.freeze(["schedule", "list", "snooze", "update", "cancel", "log"]),
         interaction: Object.freeze(["callback-status", "callback-probe", "create", "get", "resolve"]),
@@ -31,7 +31,9 @@ function resolveAgentCliExecutable(cliPath, runtimeExecutable = node_process_1.d
 function agentCliPromptCapabilities(executable = "larkin") {
     const commands = Object.entries(exports.AGENT_CLI_CAPABILITIES.commands).flatMap(([group, operations]) => operations.map((operation) => ({
         command: `${group} ${operation}`,
-        purpose: group === "inbox" ? (operation === "check" ? "Read pending target summaries without consuming messages." : "Poll full messages and direct-ack the returned batch.") :
+        purpose: group === "inbox" ? (operation === "check" ? "Read pending target summaries without consuming messages."
+            : operation === "audit" ? "Read bounded observed group/topic audit targets and instructions."
+                : "Poll full messages and direct-ack the returned batch.") :
             group === "comment" ? "Reply once to the exact cloud-document comment bound by a polled Inbox message id." :
                 group === "reminder" ? "Manage this Agent's durable reminders." :
                     group === "interaction" ? "Create, inspect, or resolve a durable interactive card run." :

package/dist/agent/agent-cli-capabilities.mjs

@@ -4,7 +4,7 @@ import { INTERNAL_AGENT_CLI, internalCommandShell } from "../app/internal-comman
 export const AGENT_CLI_CAPABILITIES = Object.freeze({
     version: 1,
     commands: Object.freeze({
-        inbox: Object.freeze(["check", "poll"]),
+        inbox: Object.freeze(["check", "poll", "audit"]),
         comment: Object.freeze(["reply"]),
         reminder: Object.freeze(["schedule", "list", "snooze", "update", "cancel", "log"]),
         interaction: Object.freeze(["callback-status", "callback-probe", "create", "get", "resolve"]),
@@ -23,7 +23,9 @@ export function resolveAgentCliExecutable(cliPath, runtimeExecutable = process.e
 export function agentCliPromptCapabilities(executable = "larkin") {
     const commands = Object.entries(AGENT_CLI_CAPABILITIES.commands).flatMap(([group, operations]) => operations.map((operation) => ({
         command: `${group} ${operation}`,
-        purpose: group === "inbox" ? (operation === "check" ? "Read pending target summaries without consuming messages." : "Poll full messages and direct-ack the returned batch.") :
+        purpose: group === "inbox" ? (operation === "check" ? "Read pending target summaries without consuming messages."
+            : operation === "audit" ? "Read bounded observed group/topic audit targets and instructions."
+                : "Poll full messages and direct-ack the returned batch.") :
             group === "comment" ? "Reply once to the exact cloud-document comment bound by a polled Inbox message id." :
                 group === "reminder" ? "Manage this Agent's durable reminders." :
                     group === "interaction" ? "Create, inspect, or resolve a durable interactive card run." :

package/dist/agent/inbox-audit-heartbeat.cjs

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxAuditHeartbeat = exports.INBOX_AUDIT_CADENCE_MS = void 0;
+const inbox_projection_js_1 = require("./inbox-projection.cjs");
+exports.INBOX_AUDIT_CADENCE_MS = 15 * 60_000;
+/** One Host-owned timer fans a targetless internal wake to each active Agent. */
+class InboxAuditHeartbeat {
+    options;
+    timer = null;
+    running = false;
+    sequence = 0;
+    cadenceMs;
+    constructor(options) {
+        this.options = options;
+        this.cadenceMs = options.cadenceMs ?? exports.INBOX_AUDIT_CADENCE_MS;
+        if (!Number.isSafeInteger(this.cadenceMs) || this.cadenceMs < 1)
+            throw new Error("inbox audit cadence must be a positive integer");
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedule();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer)
+            (this.options.clearTimer ?? clearTimeout)(this.timer);
+        this.timer = null;
+    }
+    schedule() {
+        if (!this.running || this.timer)
+            return;
+        this.timer = (this.options.setTimer ?? setTimeout)(() => {
+            this.timer = null;
+            return this.fire().finally(() => { if (this.running)
+                this.schedule(); });
+        }, this.cadenceMs);
+        this.timer.unref?.();
+    }
+    async fire() {
+        const now = this.options.now ?? Date.now;
+        for (const agent of this.options.agents) {
+            const message_id = `rem_inbox_audit_${now()}_${++this.sequence}_${agent.agentId}`;
+            const envelope = {
+                kind: "reminder",
+                message_id,
+                target: inbox_projection_js_1.RUNTIME_REMINDER_TARGET,
+                wake: true,
+                content: "Internal inbox audit wake. Poll runtime:reminder, then run larkin inbox audit --json. No finding stays silent.",
+            };
+            try {
+                const appended = this.options.stateStore(agent).appendCanonicalInboxOnce(envelope);
+                if (appended.status === "appended")
+                    await this.options.runtimeHost.deliver(agent.agentId, appended.envelope);
+            }
+            catch (error) {
+                this.options.log?.(`inbox audit heartbeat failed agent=${agent.agentId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}
+exports.InboxAuditHeartbeat = InboxAuditHeartbeat;

package/dist/agent/inbox-audit-heartbeat.mjs

@@ -0,0 +1,59 @@
+import { RUNTIME_REMINDER_TARGET } from "./inbox-projection.mjs";
+export const INBOX_AUDIT_CADENCE_MS = 15 * 60_000;
+/** One Host-owned timer fans a targetless internal wake to each active Agent. */
+export class InboxAuditHeartbeat {
+    options;
+    timer = null;
+    running = false;
+    sequence = 0;
+    cadenceMs;
+    constructor(options) {
+        this.options = options;
+        this.cadenceMs = options.cadenceMs ?? INBOX_AUDIT_CADENCE_MS;
+        if (!Number.isSafeInteger(this.cadenceMs) || this.cadenceMs < 1)
+            throw new Error("inbox audit cadence must be a positive integer");
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedule();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer)
+            (this.options.clearTimer ?? clearTimeout)(this.timer);
+        this.timer = null;
+    }
+    schedule() {
+        if (!this.running || this.timer)
+            return;
+        this.timer = (this.options.setTimer ?? setTimeout)(() => {
+            this.timer = null;
+            return this.fire().finally(() => { if (this.running)
+                this.schedule(); });
+        }, this.cadenceMs);
+        this.timer.unref?.();
+    }
+    async fire() {
+        const now = this.options.now ?? Date.now;
+        for (const agent of this.options.agents) {
+            const message_id = `rem_inbox_audit_${now()}_${++this.sequence}_${agent.agentId}`;
+            const envelope = {
+                kind: "reminder",
+                message_id,
+                target: RUNTIME_REMINDER_TARGET,
+                wake: true,
+                content: "Internal inbox audit wake. Poll runtime:reminder, then run larkin inbox audit --json. No finding stays silent.",
+            };
+            try {
+                const appended = this.options.stateStore(agent).appendCanonicalInboxOnce(envelope);
+                if (appended.status === "appended")
+                    await this.options.runtimeHost.deliver(agent.agentId, appended.envelope);
+            }
+            catch (error) {
+                this.options.log?.(`inbox audit heartbeat failed agent=${agent.agentId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}

package/dist/agent/missed-outbound-scan.cjs

@@ -0,0 +1,133 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INBOX_AUDIT_TARGETS = exports.INBOX_AUDIT_LEGACY_MIGRATION_NON_GOAL = void 0;
+exports.inboxAuditRegistryFile = inboxAuditRegistryFile;
+exports.observeInboxAuditTarget = observeInboxAuditTarget;
+exports.readInboxAuditTargets = readInboxAuditTargets;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * #169's host-owned heartbeat no longer creates per-target missed-outbound loops.
+ * Pre-v0.4.21 records have no unique ownership marker and can collide exactly
+ * with user reminders, so existing indistinguishable loops are never migrated
+ * or deleted automatically.
+ */
+exports.INBOX_AUDIT_LEGACY_MIGRATION_NON_GOAL = "New versions no longer create missed-outbound loops; existing indistinguishable historical loops are not migrated or deleted automatically.";
+// Audits return every retained target. Storage remains bounded so a heartbeat
+// cannot accumulate an unbounded work list.
+exports.MAX_INBOX_AUDIT_TARGETS = 96;
+const MAX_STORED_TARGETS = exports.MAX_INBOX_AUDIT_TARGETS;
+const CHAT = /^oc_[A-Za-z0-9]+$/;
+const THREAD = /^omt_[A-Za-z0-9]+$/;
+const ANCHOR = /^om_[A-Za-z0-9_-]+$/;
+function inboxAuditRegistryFile(larkinHome) {
+    return path.join(larkinHome, "inbox-audit.json");
+}
+function parseTarget(event) {
+    const chatId = String(event.chat_id || "");
+    const threadId = event.thread_id ? String(event.thread_id) : "";
+    const anchor = String(event.message_id || "");
+    if (!CHAT.test(chatId) || !ANCHOR.test(anchor) || (threadId && !THREAD.test(threadId)))
+        return null;
+    return { target: threadId ? `thread:${chatId}:${threadId}` : `chat:${chatId}`, anchor };
+}
+function load(file) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { version: 1, targets: [] };
+        throw error;
+    }
+    if (value?.version !== 1 || !Array.isArray(value.targets))
+        return { version: 1, targets: [] };
+    return { version: 1, targets: value.targets.flatMap((row) => {
+            if (!row || typeof row !== "object")
+                return [];
+            const candidate = row;
+            if (typeof candidate.target !== "string" || typeof candidate.anchor !== "string")
+                return [];
+            const parsed = parseTarget({
+                chat_id: candidate.target.startsWith("chat:") ? candidate.target.slice(5) : candidate.target.split(":")[1],
+                thread_id: candidate.target.startsWith("thread:") ? candidate.target.split(":")[2] : null,
+                message_id: candidate.anchor,
+            });
+            return typeof candidate.agent_id === "string" && candidate.agent_id && parsed && candidate.target === parsed.target
+                && typeof candidate.observed_at === "string" && Number.isFinite(Date.parse(candidate.observed_at))
+                ? [{ agent_id: candidate.agent_id, ...parsed, observed_at: candidate.observed_at }] : [];
+        }) };
+}
+function save(file, registry) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(temporary, `${JSON.stringify(registry)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    fs.chmodSync(file, 0o600);
+}
+/** Record only an authoritative human group/topic source; DMs and bots are ignored. */
+function observeInboxAuditTarget(file, agentId, event, now = new Date()) {
+    if (event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
+        return false;
+    const parsed = parseTarget(event);
+    if (!parsed)
+        return false;
+    const registry = load(file);
+    const observed_at = now.toISOString();
+    registry.targets = registry.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
+    registry.targets.unshift({ agent_id: agentId, ...parsed, observed_at });
+    registry.targets = registry.targets.slice(0, MAX_STORED_TARGETS);
+    save(file, registry);
+    return true;
+}
+function instruction(target) {
+    const history = target.target.startsWith("thread:")
+        ? "Use larkin im +threads-messages-list for this exact thread."
+        : "Use larkin im +chat-messages-list for this exact chat.";
+    return `${history} If a real missed outbound finding requires a response, use the existing guarded larkin im reply path anchored at ${target.anchor}; otherwise stay silent.`;
+}
+/** Content-free, bounded audit work list consumed by the Agent CLI. */
+function readInboxAuditTargets(file, agentId) {
+    const rows = load(file).targets.filter((row) => row.agent_id === agentId)
+        .sort((left, right) => right.observed_at.localeCompare(left.observed_at));
+    return {
+        version: 1,
+        targets: rows.slice(0, exports.MAX_INBOX_AUDIT_TARGETS).map(({ agent_id: _agentId, ...target }) => ({ ...target, instruction: instruction(target) })),
+        has_more: rows.length > exports.MAX_INBOX_AUDIT_TARGETS,
+        no_finding: "stay_silent",
+    };
+}

package/dist/agent/missed-outbound-scan.mjs

@@ -0,0 +1,94 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * #169's host-owned heartbeat no longer creates per-target missed-outbound loops.
+ * Pre-v0.4.21 records have no unique ownership marker and can collide exactly
+ * with user reminders, so existing indistinguishable loops are never migrated
+ * or deleted automatically.
+ */
+export const INBOX_AUDIT_LEGACY_MIGRATION_NON_GOAL = "New versions no longer create missed-outbound loops; existing indistinguishable historical loops are not migrated or deleted automatically.";
+// Audits return every retained target. Storage remains bounded so a heartbeat
+// cannot accumulate an unbounded work list.
+export const MAX_INBOX_AUDIT_TARGETS = 96;
+const MAX_STORED_TARGETS = MAX_INBOX_AUDIT_TARGETS;
+const CHAT = /^oc_[A-Za-z0-9]+$/;
+const THREAD = /^omt_[A-Za-z0-9]+$/;
+const ANCHOR = /^om_[A-Za-z0-9_-]+$/;
+export function inboxAuditRegistryFile(larkinHome) {
+    return path.join(larkinHome, "inbox-audit.json");
+}
+function parseTarget(event) {
+    const chatId = String(event.chat_id || "");
+    const threadId = event.thread_id ? String(event.thread_id) : "";
+    const anchor = String(event.message_id || "");
+    if (!CHAT.test(chatId) || !ANCHOR.test(anchor) || (threadId && !THREAD.test(threadId)))
+        return null;
+    return { target: threadId ? `thread:${chatId}:${threadId}` : `chat:${chatId}`, anchor };
+}
+function load(file) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { version: 1, targets: [] };
+        throw error;
+    }
+    if (value?.version !== 1 || !Array.isArray(value.targets))
+        return { version: 1, targets: [] };
+    return { version: 1, targets: value.targets.flatMap((row) => {
+            if (!row || typeof row !== "object")
+                return [];
+            const candidate = row;
+            if (typeof candidate.target !== "string" || typeof candidate.anchor !== "string")
+                return [];
+            const parsed = parseTarget({
+                chat_id: candidate.target.startsWith("chat:") ? candidate.target.slice(5) : candidate.target.split(":")[1],
+                thread_id: candidate.target.startsWith("thread:") ? candidate.target.split(":")[2] : null,
+                message_id: candidate.anchor,
+            });
+            return typeof candidate.agent_id === "string" && candidate.agent_id && parsed && candidate.target === parsed.target
+                && typeof candidate.observed_at === "string" && Number.isFinite(Date.parse(candidate.observed_at))
+                ? [{ agent_id: candidate.agent_id, ...parsed, observed_at: candidate.observed_at }] : [];
+        }) };
+}
+function save(file, registry) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(temporary, `${JSON.stringify(registry)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    fs.chmodSync(file, 0o600);
+}
+/** Record only an authoritative human group/topic source; DMs and bots are ignored. */
+export function observeInboxAuditTarget(file, agentId, event, now = new Date()) {
+    if (event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
+        return false;
+    const parsed = parseTarget(event);
+    if (!parsed)
+        return false;
+    const registry = load(file);
+    const observed_at = now.toISOString();
+    registry.targets = registry.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
+    registry.targets.unshift({ agent_id: agentId, ...parsed, observed_at });
+    registry.targets = registry.targets.slice(0, MAX_STORED_TARGETS);
+    save(file, registry);
+    return true;
+}
+function instruction(target) {
+    const history = target.target.startsWith("thread:")
+        ? "Use larkin im +threads-messages-list for this exact thread."
+        : "Use larkin im +chat-messages-list for this exact chat.";
+    return `${history} If a real missed outbound finding requires a response, use the existing guarded larkin im reply path anchored at ${target.anchor}; otherwise stay silent.`;
+}
+/** Content-free, bounded audit work list consumed by the Agent CLI. */
+export function readInboxAuditTargets(file, agentId) {
+    const rows = load(file).targets.filter((row) => row.agent_id === agentId)
+        .sort((left, right) => right.observed_at.localeCompare(left.observed_at));
+    return {
+        version: 1,
+        targets: rows.slice(0, MAX_INBOX_AUDIT_TARGETS).map(({ agent_id: _agentId, ...target }) => ({ ...target, instruction: instruction(target) })),
+        has_more: rows.length > MAX_INBOX_AUDIT_TARGETS,
+        no_finding: "stay_silent",
+    };
+}

package/dist/app/agent-cli.mjs

@@ -7,6 +7,7 @@ import * as path from "node:path";
 import { createAgentStateStore } from "../agent/agent-state-store.mjs";
 import * as larkinConfig from "../platform/config.mjs";
 import { projectInboxCheck, projectInboxEvents } from "../agent/inbox-projection.mjs";
+import { inboxAuditRegistryFile, readInboxAuditTargets } from "../agent/missed-outbound-scan.mjs";
 import { createReminderRoutes } from "../agent/reminder-routes.mjs";
 import { InteractionStateMachine } from "../agent/interaction-state-machine.mjs";
 import { issueCallbackProbe, readCallbackCapability } from "../platform/callback-capability.mjs";
@@ -501,10 +502,17 @@ export function runAgentCli(argv, env = process.env, dependencies = {}) {
         const { config, agent } = requireAgent(env);
         const stateStore = dependencies.stateStore ?? createAgentStateStore(config.larkinHome, agent.agentId);
         if (group === "inbox") {
-            if (!["check", "poll"].includes(subcommand || "")) {
-                throw new Error("inbox 只支持 `larkin inbox check` 与 `larkin inbox poll`");
+            if (!["check", "poll", "audit"].includes(subcommand || "")) {
+                throw new Error("inbox 只支持 `larkin inbox check`、`larkin inbox poll` 与 `larkin inbox audit`");
             }
             const options = parseOptions(rest, new Set(["--json"]));
+            if (subcommand === "audit") {
+                if (options.positionals.length || options.values.size || options.booleans.size > 1) {
+                    throw new Error("inbox audit 只接受 --json");
+                }
+                emitJson(io, readInboxAuditTargets(inboxAuditRegistryFile(config.larkinHome), agent.agentId));
+                return 0;
+            }
             if (options.positionals.length || [...options.values.keys()].some((flag) => !["--target", "--limit"].includes(flag))) {
                 throw new Error(`inbox ${subcommand} 只接受 --target、${subcommand === "poll" ? "--limit、" : ""}--json`);
             }

package/dist/feishu/host-shell.cjs

@@ -51,6 +51,8 @@ const host_business_state_js_1 = require("./host-business-state.cjs");
 const host_processing_eye_js_1 = require("./host-processing-eye.cjs");
 const inbox_projection_js_1 = require("../agent/inbox-projection.cjs");
 const host_reminder_orchestrator_js_1 = require("../agent/host-reminder-orchestrator.cjs");
+const inbox_audit_heartbeat_js_1 = require("../agent/inbox-audit-heartbeat.cjs");
+const missed_outbound_scan_js_1 = require("../agent/missed-outbound-scan.cjs");
 const host_channel_business_js_1 = require("./host-channel-business.cjs");
 const interaction_orchestrator_js_1 = require("./interaction-orchestrator.cjs");
 const message_policy_js_1 = require("./message-policy.cjs");
@@ -339,6 +341,13 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
     for (const agent of agents)
         prepareAgentState(agent);
     const reminder = new host_reminder_orchestrator_js_1.HostReminderOrchestrator({ agents, stateStore, envelopeProjector, deliveryTarget: runtimeHost, log });
+    const inboxAudit = new inbox_audit_heartbeat_js_1.InboxAuditHeartbeat({
+        agents,
+        stateStore,
+        runtimeHost,
+        log,
+    });
+    const auditRegistry = (0, missed_outbound_scan_js_1.inboxAuditRegistryFile)(larkinHome);
     const seenEventIds = new Set();
     const inFlightEventIds = new Set();
     const onFeishuMessage = async (agent, event, options) => {
@@ -385,6 +394,12 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                 // append/dedupe decision is durable. Agent model-seen state is untouched.
                 if (event.event_id)
                     seenEventIds.add(eventKey);
+                try {
+                    (0, missed_outbound_scan_js_1.observeInboxAuditTarget)(auditRegistry, agent.agentId, event);
+                }
+                catch (error) {
+                    log(`inbox audit target 未持久化: ${error.message}`);
+                }
                 if (append.status === "duplicate_consumed")
                     return null;
                 const inboxEnvelope = append.envelope;
@@ -1336,6 +1351,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
             eventSourceStartTimer = null;
             await Promise.resolve(eventSourceStop());
             reminder.stopSync();
+            inboxAudit.stop();
             interaction.stopSync();
             await runtimeHost.shutdown(reason);
         })();
@@ -1550,6 +1566,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     sessionId: agentStates.get(agent.agentId)?.state.sessions[agent.runtime] || null,
                 })));
                 reminder.startSync();
+                inboxAudit.start();
                 interaction.startSync();
                 eventSourceStartTimer = setTimeout(() => { eventSourceStartTimer = null; startEventSource(); }, eventSourceStartDelayMs);
             }

package/dist/feishu/host-shell.mjs

@@ -11,6 +11,8 @@ import { HostEnvelopeProjector, HostStateProjection, SenderIdentityCache, projec
 import { ProcessingEyeOrchestrator } from "./host-processing-eye.mjs";
 import { projectInboxEnvelope, targetKeyOfInboxEnvelope } from "../agent/inbox-projection.mjs";
 import { HostReminderOrchestrator } from "../agent/host-reminder-orchestrator.mjs";
+import { InboxAuditHeartbeat } from "../agent/inbox-audit-heartbeat.mjs";
+import { inboxAuditRegistryFile, observeInboxAuditTarget } from "../agent/missed-outbound-scan.mjs";
 import { HostChannelBusiness } from "./host-channel-business.mjs";
 import { HostInteractionOrchestrator } from "./interaction-orchestrator.mjs";
 import { targetFor } from "./message-policy.mjs";
@@ -299,6 +301,13 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
     for (const agent of agents)
         prepareAgentState(agent);
     const reminder = new HostReminderOrchestrator({ agents, stateStore, envelopeProjector, deliveryTarget: runtimeHost, log });
+    const inboxAudit = new InboxAuditHeartbeat({
+        agents,
+        stateStore,
+        runtimeHost,
+        log,
+    });
+    const auditRegistry = inboxAuditRegistryFile(larkinHome);
     const seenEventIds = new Set();
     const inFlightEventIds = new Set();
     const onFeishuMessage = async (agent, event, options) => {
@@ -345,6 +354,12 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                 // append/dedupe decision is durable. Agent model-seen state is untouched.
                 if (event.event_id)
                     seenEventIds.add(eventKey);
+                try {
+                    observeInboxAuditTarget(auditRegistry, agent.agentId, event);
+                }
+                catch (error) {
+                    log(`inbox audit target 未持久化: ${error.message}`);
+                }
                 if (append.status === "duplicate_consumed")
                     return null;
                 const inboxEnvelope = append.envelope;
@@ -1296,6 +1311,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
             eventSourceStartTimer = null;
             await Promise.resolve(eventSourceStop());
             reminder.stopSync();
+            inboxAudit.stop();
             interaction.stopSync();
             await runtimeHost.shutdown(reason);
         })();
@@ -1510,6 +1526,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                     sessionId: agentStates.get(agent.agentId)?.state.sessions[agent.runtime] || null,
                 })));
                 reminder.startSync();
+                inboxAudit.start();
                 interaction.startSync();
                 eventSourceStartTimer = setTimeout(() => { eventSourceStartTimer = null; startEventSource(); }, eventSourceStartDelayMs);
             }

package/dist/feishu/message-policy.cjs

@@ -39,6 +39,8 @@ function normalizeChannelMessage(message) {
         _mentioned_bot: Boolean(message.mentionedBot || message.mentionAll),
         _mention_all: Boolean(message.mentionAll),
         _sender_is_bot: message.senderIsBot === true,
+        _scan_authority: typeof message.senderIsBot === "boolean"
+            && (message.chatType === "group" || message.chatMode === "topic"),
     };
 }
 function slug10(value) {

package/dist/feishu/message-policy.mjs

@@ -26,6 +26,8 @@ export function normalizeChannelMessage(message) {
         _mentioned_bot: Boolean(message.mentionedBot || message.mentionAll),
         _mention_all: Boolean(message.mentionAll),
         _sender_is_bot: message.senderIsBot === true,
+        _scan_authority: typeof message.senderIsBot === "boolean"
+            && (message.chatType === "group" || message.chatMode === "topic"),
     };
 }
 export function slug10(value) {

package/dist/setup/bot-register.mjs

@@ -19,6 +19,7 @@ import { beginBuiltinPiCredentialTransaction, createOfficialPiCredentialRuntime,
 import { documentCommentSubscriptionCapability, markDocumentCommentSubscriptionVerified, } from "../platform/callback-capability.mjs";
 import { openPlatformHost, parseLarkinTenant, registerAppAccountsHost, } from "../feishu/platform-hosts.mjs";
 import { authorizationUrlFailureMessage, presentAuthorizationUrl } from "./setup-authorization-url.mjs";
+import { missingGrantedTenantScopes } from "./tenant-scope-grant.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -28,6 +29,7 @@ const testFixture = process.env.LARKIN_TEST_BOT_REGISTER_MODULE
 const registerApp = testFixture?.registerApp ?? channelRegisterApp;
 const qrcode = testFixture?.qrcode ?? qrcodePackage;
 const spawnSync = testFixture?.spawnSync ?? systemSpawnSync;
+const spawnChild = testFixture?.spawn ?? systemSpawn;
 const synchronizeAgentProfile = testFixture?.syncAgentProfile ?? syncAgentProfile;
 const resolveOfficialCli = testFixture?.resolveOfficialLarkCli ?? resolveOfficialLarkCli;
 const wait = testFixture?.wait ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
@@ -306,7 +308,7 @@ async function runBindProcess(command, args) {
         return spawnSync(command, [...args], { env: process.env, stdio: "inherit" }).status;
     }
     return await new Promise((resolve, reject) => {
-        const child = systemSpawn(command, [...args], { env: process.env, stdio: "inherit" });
+        const child = spawnChild(command, [...args], { env: process.env, stdio: "inherit" });
         trackPendingChild(child);
         let killTimer = null;
         const abort = () => {
@@ -339,7 +341,7 @@ async function runBoundedCliProcess(command, args, env, label) {
         return { status: result.status, stdout: result.stdout || "", stderr: result.stderr || "" };
     }
     return await new Promise((resolve, reject) => {
-        const child = systemSpawn(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawnChild(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
         trackPendingChild(child);
         let stdout = "";
         let stderr = "";
@@ -641,12 +643,13 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         : commentSubscription === "none" || !priorSubscription
             ? { mode: "none", status: "safe-default", source: "setup-default", updatedAt: requestedAt }
             : priorSubscription;
-    if (!flag("--runtime") && (!testFixture || process.env.LARKIN_TEST_ENABLE_AGENT_CHOICE === "1")) {
+    const injectedAgentChoice = testFixture?.collectSetupAgentChoice;
+    if (!flag("--runtime") && (!testFixture || injectedAgentChoice || process.env.LARKIN_TEST_ENABLE_AGENT_CHOICE === "1")) {
         const existing = larkinConfig.loadConfig(process.env).config.agents[id];
         // The official resolver performs a synchronous login-shell probe. Resolve it
         // exactly once before the credential heartbeat lock becomes active.
         resolvedSetupOfficialCli = resolveOfficialCli({ env: process.env });
-        const questioner = terminalSetupQuestioner();
+        const questioner = injectedAgentChoice ? { ask: async () => "", secret: async () => "" } : terminalSetupQuestioner();
         // One setup-owned transaction starts before status/logout and remains active
         // through selection, login, bind, readiness, and the final setup commit.
         pendingPiAuthTransaction = beginBuiltinPiCredentialTransaction(CFG_DIR, id);
@@ -657,37 +660,43 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
             report: (message) => say(message),
         };
         try {
-            const requested = await collectSetupAgentChoice(questioner, existing, authServices);
-            const choice = await recoverUnavailableExternalPi(requested, questioner, () => probeNativeRuntimeReadiness({
-                runtime: "pi", agentId: id, cwd: path.join(CFG_DIR, "agents", id), env: process.env,
-            }), (message) => say(`! ${message}`), authServices);
+            const requested = injectedAgentChoice
+                ? await injectedAgentChoice()
+                : await collectSetupAgentChoice(questioner, existing, authServices);
+            const choice = injectedAgentChoice
+                ? requested
+                : await recoverUnavailableExternalPi(requested, questioner, () => probeNativeRuntimeReadiness({
+                    runtime: "pi", agentId: id, cwd: path.join(CFG_DIR, "agents", id), env: process.env,
+                }), (message) => say(`! ${message}`), authServices);
             if (choice) {
                 let serializedChoice = choice;
                 if (choice.runtime === "pi" && choice.distribution === "builtin") {
-                    const official = choice.preset === "official" ? choice : null;
-                    const configured = official ? null : configureBuiltinPiProviderModel(CFG_DIR, id, choice);
-                    const providerId = official?.providerId || configured.provider;
-                    const authType = official?.authType || "api_key";
-                    let piRuntime;
-                    try {
-                        say(`正在通过捆绑官方 Pi 登录 ${providerId}（${authType}）…`);
-                        piRuntime = await createOfficialPiModelRuntime(CFG_DIR, id);
-                        await runOfficialPiLogin(piRuntime, providerId, authType, createOfficialPiAuthInteraction({ questioner, report: (message) => say(message), openUrl: openBrowser }));
-                    }
-                    catch {
-                        pendingPiAuthTransaction.rollback();
-                        pendingPiAuthTransaction = null;
-                        throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
-                    }
-                    if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
-                        say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
+                    if (!injectedAgentChoice) {
+                        const official = choice.preset === "official" ? choice : null;
+                        const configured = official ? null : configureBuiltinPiProviderModel(CFG_DIR, id, choice);
+                        const providerId = official?.providerId || configured.provider;
+                        const authType = official?.authType || "api_key";
+                        let piRuntime;
                         try {
-                            await verifyOfficialPiProviderTurn(piRuntime, choice.model);
+                            say(`正在通过捆绑官方 Pi 登录 ${providerId}（${authType}）…`);
+                            piRuntime = await createOfficialPiModelRuntime(CFG_DIR, id);
+                            await runOfficialPiLogin(piRuntime, providerId, authType, createOfficialPiAuthInteraction({ questioner, report: (message) => say(message), openUrl: openBrowser }));
                         }
                         catch {
                             pendingPiAuthTransaction.rollback();
                             pendingPiAuthTransaction = null;
-                            throw new Error(`官方 Pi ${providerId} readiness 失败；credential/config 未修改`);
+                            throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
+                        }
+                        if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
+                            say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
+                            try {
+                                await verifyOfficialPiProviderTurn(piRuntime, choice.model);
+                            }
+                            catch {
+                                pendingPiAuthTransaction.rollback();
+                                pendingPiAuthTransaction = null;
+                                throw new Error(`官方 Pi ${providerId} readiness 失败；credential/config 未修改`);
+                            }
                         }
                     }
                     serializedChoice = { ...choice, authCompleted: true, readinessCompleted: true };
@@ -850,6 +859,21 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         }
         if (!verified)
             throw new Error("Bot identity verification failed");
+        const scopeResult = await runIdentityProcess(official.command, [...official.argsPrefix, "api", "GET", "/open-apis/application/v6/scopes"], cliEnv);
+        let scopePayload;
+        try {
+            scopePayload = JSON.parse(scopeResult.stdout || "");
+        }
+        catch {
+            scopePayload = null;
+        }
+        const missing = missingGrantedTenantScopes(scopePayload);
+        if (scopeResult.status !== 0 || missing.length > 0) {
+            const reason = scopeResult.status !== 0
+                ? `scopes API 失败 status=${scopeResult.status}`
+                : `缺 ${missing.join(", ")}`;
+            throw new Error(`Bot tenant scope 未就绪，${reason}；+chat-list 成功不能当作可发群消息。请在开发者后台开通后重跑 setup，不要重建 Agent。`);
+        }
         if (commentSubscription !== "preserve") {
             const reconciled = await applyDocumentCommentSubscription({
                 mode: commentSubscription,
@@ -901,6 +925,8 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
     }
     catch (error) {
         const diagnostic = errorMessage(error);
+        if (diagnostic.startsWith("Bot tenant scope 未就绪"))
+            die(diagnostic);
         if (diagnostic.startsWith("document comment application subscription")
             || diagnostic.startsWith("document comment local verified-state persistence"))
             say(`! ${diagnostic}`);

package/dist/setup/grant-scopes.mjs

@@ -10,6 +10,7 @@ import * as larkinConfig from "../platform/config.mjs";
 import { managedOfficialLarkCli } from "../app/agent-lark-cli-workspace.mjs";
 import { loadValidatedBotCredential } from "./run-credential-preflight.mjs";
 import { parseLarkinTenant, registerAppAccountsHost } from "../feishu/platform-hosts.mjs";
+import { presentAuthorizationUrl } from "./setup-authorization-url.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -108,18 +109,26 @@ export async function main() {
         },
         onQRCodeReady: (info) => {
             const minutes = Math.max(1, Math.round(info.expireIn / 60));
+            const official = resolveManagedOfficialCli(selected, process.env);
+            const presented = presentAuthorizationUrl(info.url, {
+                tenant: TENANT,
+                larkCliVersion: official.command.version,
+            });
+            if (TENANT === "lark" && /\/page\/launcher(?:\?|$)/.test(presented)) {
+                throw new Error("Lark 租户拒绝把 /page/launcher 交给浏览器");
+            }
             log("\n请用飞书（Lark）扫码或打开链接，确认给应用增补权限：\n");
-            qrcode.generate(info.url, { small: true });
-            log(`\n链接: ${info.url}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
+            qrcode.generate(presented, { small: true });
+            log(`\n链接: ${presented}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
             if (URL_FILE) {
                 try {
-                    fs.writeFileSync(URL_FILE, info.url);
+                    fs.writeFileSync(URL_FILE, presented);
                 }
                 catch (error) {
                     log(`[grant] 写 url-file 失败: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
-            sendUrlToChat(info.url, minutes);
+            sendUrlToChat(presented, minutes);
         },
         onStatusChange: (info) => log(`[grant] 状态: ${info.status}`),
         domain: registerAppAccountsHost(TENANT),

package/dist/setup/tenant-scope-grant.mjs

@@ -0,0 +1,16 @@
+/** Tenant scopes the freshness gate needs on the Bot application. */
+export const FRESHNESS_REQUIRED_TENANT_SCOPES = ["im:message.group_msg"];
+function asRows(payload) {
+    if (!payload || typeof payload !== "object")
+        return [];
+    const root = payload;
+    const raw = Array.isArray(root.data?.scopes) ? root.data.scopes
+        : Array.isArray(root.scopes) ? root.scopes
+            : [];
+    return raw.filter((row) => !!row && typeof row === "object");
+}
+/** grant_status 1 is granted on GET /open-apis/application/v6/scopes. */
+export function missingGrantedTenantScopes(payload, required = FRESHNESS_REQUIRED_TENANT_SCOPES) {
+    const rows = asRows(payload);
+    return required.filter((name) => !rows.some((row) => row.scope_name === name && row.grant_status === 1));
+}

package/package.json

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