larkin 0.5.2 → 0.5.4

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

@@ -1,22 +1,22 @@
+import * as crypto from "node:crypto";
 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.
- */
+import { acquireProcessLock } from "../platform/process-state.mjs";
+/** Historical reminder loops are deliberately unrelated to this bounded audit registry. */
 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;
+export const MAX_INBOX_AUDIT_REGISTRY_BYTES = 64 * 1024;
+export const MAX_INBOX_AUDIT_REGISTRY_ROWS = MAX_INBOX_AUDIT_TARGETS;
+const LOCK_WAIT_MS = 5_000;
+const LOCK_RETRY_MS = 25;
 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");
-}
+const GENERATION = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const OUTCOMES = new Set(["no-finding", "handled"]);
+export function inboxAuditRegistryFile(larkinHome) { return path.join(larkinHome, "inbox-audit.json"); }
+export function inboxAuditRetryFile(larkinHome) { return path.join(larkinHome, "inbox-audit-retry.json"); }
 function parseTarget(event) {
     const chatId = String(event.chat_id || "");
     const threadId = event.thread_id ? String(event.thread_id) : "";
@@ -25,70 +25,336 @@ function parseTarget(event) {
         return null;
     return { target: threadId ? `thread:${chatId}:${threadId}` : `chat:${chatId}`, anchor };
 }
+function emptyRegistry() { return { version: 4, targets: [] }; }
+function assertSafeExistingFile(file, label) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`${label} is not a regular file`);
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            throw new Error(`${label} is not owned by the current user`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function prepareRegistryDirectory(file) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("inbox audit registry directory is unsafe");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error("inbox audit registry directory is not owned by the current user");
+}
 function load(file) {
-    let value;
+    let fd;
+    let bytes;
     try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
+        assertSafeExistingFile(file, "inbox audit registry");
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error("inbox audit registry is not a regular file");
+        const buffer = Buffer.alloc(MAX_INBOX_AUDIT_REGISTRY_BYTES + 1);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const read = fs.readSync(fd, buffer, offset, buffer.length - offset, offset);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        if (offset > MAX_INBOX_AUDIT_REGISTRY_BYTES)
+            throw new Error("inbox audit registry exceeds the bounded byte limit");
+        bytes = buffer.subarray(0, offset);
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return { version: 1, targets: [] };
+            return emptyRegistry();
         throw error;
     }
-    if (value?.version !== 1 || !Array.isArray(value.targets))
-        return { version: 1, targets: [] };
-    return { version: 1, targets: value.targets.flatMap((row) => {
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+    const value = JSON.parse(bytes.toString("utf8"));
+    // v1 had no wake provenance; v2 had no durable observation generation.
+    // Neither can safely issue a completion receipt after this lifecycle upgrade.
+    if (value?.version !== 4 || !Array.isArray(value.targets))
+        return emptyRegistry();
+    if (value.targets.length > MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        throw new Error("inbox audit registry exceeds the bounded row limit");
+    return { version: 4, 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 parts = candidate.target.split(":");
             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,
+                chat_id: candidate.target.startsWith("chat:") ? candidate.target.slice(5) : parts[1],
+                thread_id: candidate.target.startsWith("thread:") ? parts[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 }] : [];
+            const status = candidate.status === "completed" ? "completed" : candidate.status === "pending" ? "pending" : null;
+            if (!status || typeof candidate.agent_id !== "string" || !candidate.agent_id || typeof candidate.generation !== "string" || !GENERATION.test(candidate.generation) || !parsed || candidate.target !== parsed.target
+                || !Number.isSafeInteger(candidate.source_seq) || Number(candidate.source_seq) < 1
+                || typeof candidate.observed_at !== "string" || !Number.isFinite(Date.parse(candidate.observed_at)))
+                return [];
+            const completed_at = typeof candidate.completed_at === "string" && Number.isFinite(Date.parse(candidate.completed_at)) ? candidate.completed_at : undefined;
+            const completed_anchor = typeof candidate.completed_anchor === "string" && ANCHOR.test(candidate.completed_anchor) ? candidate.completed_anchor : undefined;
+            const completed_outcome = OUTCOMES.has(String(candidate.completed_outcome)) ? candidate.completed_outcome : undefined;
+            return [{ agent_id: candidate.agent_id, generation: candidate.generation, ...parsed, source_seq: Number(candidate.source_seq), observed_at: candidate.observed_at, status,
+                    ...(completed_at ? { completed_at } : {}), ...(completed_anchor ? { completed_anchor } : {}),
+                    ...(completed_outcome ? { completed_outcome } : {}) }];
         }) };
 }
 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);
+    if (registry.targets.length > MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        throw new Error("inbox audit registry exceeds the bounded row limit");
+    const serialized = `${JSON.stringify(registry)}\n`;
+    if (Buffer.byteLength(serialized) > MAX_INBOX_AUDIT_REGISTRY_BYTES)
+        throw new Error("inbox audit registry exceeds the bounded byte limit");
+    prepareRegistryDirectory(file);
+    assertSafeExistingFile(file, "inbox audit registry");
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    try {
+        fs.writeFileSync(fd, serialized);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function emptyRetryJournal() { return { version: 2, targets: [] }; }
+function loadRetryJournal(file) {
+    let value;
+    try {
+        assertSafeExistingFile(file, "inbox audit retry journal");
+        const stat = fs.statSync(file);
+        if (stat.size > MAX_INBOX_AUDIT_REGISTRY_BYTES)
+            throw new Error("inbox audit retry journal exceeds the bounded byte limit");
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyRetryJournal();
+        throw error;
+    }
+    const raw = value;
+    if (raw.version !== 2 || !Array.isArray(raw.targets) || raw.targets.length > MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        return emptyRetryJournal();
+    return { version: 2, targets: raw.targets.flatMap((candidate) => {
+            if (!candidate || typeof candidate !== "object")
+                return [];
+            const row = candidate;
+            const parsed = parseTarget({ chat_id: row.chat_id, thread_id: row.thread_id, message_id: row.anchor });
+            if (typeof row.agent_id !== "string" || !row.agent_id || typeof row.target !== "string" || !parsed || parsed.target !== row.target
+                || typeof row.chat_id !== "string" || (row.thread_id !== null && typeof row.thread_id !== "string")
+                || !Number.isSafeInteger(row.source_seq) || Number(row.source_seq) < 1
+                || typeof row.queued_at !== "string" || !Number.isFinite(Date.parse(row.queued_at)))
+                return [];
+            return [{ agent_id: row.agent_id, target: row.target, anchor: parsed.anchor, chat_id: row.chat_id, thread_id: row.thread_id ?? null, source_seq: Number(row.source_seq), queued_at: row.queued_at }];
+        }) };
+}
+function saveRetryJournal(file, journal) {
+    if (journal.targets.length > MAX_INBOX_AUDIT_REGISTRY_ROWS)
+        throw new Error("inbox audit retry journal exceeds the bounded row limit");
+    const serialized = `${JSON.stringify(journal)}\n`;
+    if (Buffer.byteLength(serialized) > MAX_INBOX_AUDIT_REGISTRY_BYTES)
+        throw new Error("inbox audit retry journal exceeds the bounded byte limit");
+    prepareRegistryDirectory(file);
+    assertSafeExistingFile(file, "inbox audit retry journal");
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    try {
+        fs.writeFileSync(fd, serialized);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function sleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+/** Serialize Host observers and CLI completion without replacing a newer registry snapshot. */
+function withAuditLock(file, operation) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    const lockFile = `${file}.mutation-lock`;
+    prepareRegistryDirectory(file);
+    while (Date.now() <= deadline) {
+        let lock;
+        try {
+            assertSafeExistingFile(lockFile, "inbox audit mutation lock");
+            lock = acquireProcessLock(lockFile, path.basename(process.execPath), { malformedGraceMs: 1_000 });
+            return operation();
+        }
+        catch (error) {
+            if (lock || !/lock 已被|无法取得 lock|正在创建|暂不能接管|并发重试耗尽/.test(error instanceof Error ? error.message : String(error)))
+                throw error;
+            sleep(LOCK_RETRY_MS);
+        }
+        finally {
+            lock?.release();
+        }
+    }
+    throw new Error("inbox audit registry busy: bounded lock contention");
+}
+function mutate(file, operation) {
+    return withAuditLock(file, () => {
+        const registry = load(file);
+        const result = operation(registry);
+        save(file, registry);
+        return result;
+    });
+}
+function mutateRetryJournal(file, operation) {
+    return withAuditLock(file, () => {
+        const journal = loadRetryJournal(file);
+        const result = operation(journal);
+        saveRetryJournal(file, journal);
+        return result;
+    });
+}
+function revision(row) {
+    return `sha256:${crypto.createHash("sha256").update(JSON.stringify({
+        v: 2, agent_id: row.agent_id, target: row.target, anchor: row.anchor, generation: row.generation, status: row.status,
+    })).digest("hex")}`;
+}
+function receipt(row) {
+    const payload = { v: 1, agent_id: row.agent_id, target: row.target, anchor: row.anchor, revision: revision(row) };
+    return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function parseReceipt(value) {
+    try {
+        const raw = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        if (raw.v !== 1 || typeof raw.agent_id !== "string" || !raw.agent_id || typeof raw.target !== "string" || typeof raw.anchor !== "string"
+            || typeof raw.revision !== "string" || !raw.revision.startsWith("sha256:"))
+            return null;
+        const parts = raw.target.split(":");
+        const parsed = parseTarget({ chat_id: raw.target.startsWith("chat:") ? raw.target.slice(5) : parts[1], thread_id: raw.target.startsWith("thread:") ? parts[2] : null, message_id: raw.anchor });
+        return parsed?.target === raw.target ? raw : null;
+    }
+    catch {
+        return null;
+    }
 }
-/** 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")
+    if (event.wake !== true || event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
         return false;
     const parsed = parseTarget(event);
-    if (!parsed)
+    const sourceSeq = typeof event.source_seq === "number" ? event.source_seq : Number.NaN;
+    if (!parsed || !Number.isSafeInteger(sourceSeq) || sourceSeq < 1)
+        return false;
+    return mutate(file, (registry) => {
+        const existing = registry.targets.find((row) => row.agent_id === agentId && row.target === parsed.target);
+        if (existing && sourceSeq <= existing.source_seq)
+            return false;
+        registry.targets = registry.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
+        registry.targets.unshift({ agent_id: agentId, generation: crypto.randomUUID(), ...parsed, source_seq: sourceSeq, observed_at: now.toISOString(), status: "pending" });
+        registry.targets = registry.targets.slice(0, MAX_STORED_TARGETS);
+        return true;
+    });
+}
+/** Durable recovery intent, recorded only after the same original wake gate. */
+export function enqueueInboxAuditTargetRetry(file, agentId, event, now = new Date()) {
+    if (event.wake !== true || event._scan_authority !== true || event._sender_is_bot !== false || event.chat_type !== "group")
+        return false;
+    const parsed = parseTarget(event);
+    const sourceSeq = typeof event.source_seq === "number" ? event.source_seq : Number.NaN;
+    if (!parsed || !Number.isSafeInteger(sourceSeq) || sourceSeq < 1)
         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. */
+    return mutateRetryJournal(file, (journal) => {
+        const existing = journal.targets.find((row) => row.agent_id === agentId && row.target === parsed.target);
+        if (existing && sourceSeq <= existing.source_seq)
+            return false;
+        journal.targets = journal.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target);
+        journal.targets.unshift({ agent_id: agentId, ...parsed, source_seq: sourceSeq, chat_id: String(event.chat_id), thread_id: event.thread_id ? String(event.thread_id) : null, queued_at: now.toISOString() });
+        journal.targets = journal.targets.slice(0, MAX_STORED_TARGETS);
+        return true;
+    });
+}
+/** Remove only the exact recovered/newer target so a late retry cannot erase a new anchor. */
+export function discardInboxAuditTargetRetry(file, agentId, event) {
+    const parsed = parseTarget(event);
+    if (!parsed)
+        return;
+    mutateRetryJournal(file, (journal) => { journal.targets = journal.targets.filter((row) => row.agent_id !== agentId || row.target !== parsed.target || row.source_seq > Number(event.source_seq ?? 0)); });
+}
+/** Replay persisted, already-authorized observer intents. Failures remain durable for a later bounded retry/startup. */
+export function reconcileInboxAuditTargetRetries(registryFile, retryFile, agentId) {
+    const rows = loadRetryJournal(retryFile).targets.filter((row) => !agentId || row.agent_id === agentId);
+    let recovered = 0;
+    for (const row of rows) {
+        try {
+            observeInboxAuditTarget(registryFile, row.agent_id, { chat_id: row.chat_id, chat_type: "group", thread_id: row.thread_id, message_id: row.anchor, source_seq: row.source_seq, wake: true, _sender_is_bot: false, _scan_authority: true });
+            discardInboxAuditTargetRetry(retryFile, row.agent_id, { chat_id: row.chat_id, thread_id: row.thread_id, message_id: row.anchor, source_seq: row.source_seq });
+            recovered += 1;
+        }
+        catch {
+            break;
+        }
+    }
+    return { recovered, remaining: loadRetryJournal(retryFile).targets.filter((row) => !agentId || row.agent_id === agentId).length };
+}
+function instruction(target, receiptValue) {
+    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} Inspect first. When finished, run larkin inbox audit complete --receipt ${receiptValue} --outcome <no-finding|handled> --json. If a real finding needs a response, use the guarded reply path anchored at ${target.anchor}; otherwise stay silent.`;
+}
+function pendingRows(file, agentId) {
+    return load(file).targets.filter((row) => row.agent_id === agentId && row.status === "pending").sort((left, right) => right.observed_at.localeCompare(left.observed_at));
+}
+export function hasPendingInboxAuditTargets(file, agentId) { return pendingRows(file, agentId).length > 0; }
+/** Public read is intentionally completion-free: a caller crash leaves the target pending. */
 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",
-    };
+    const rows = pendingRows(file, agentId);
+    return { version: 4, targets: rows.slice(0, MAX_INBOX_AUDIT_TARGETS).map((row) => {
+            const target = { target: row.target, anchor: row.anchor, observed_at: row.observed_at, source_seq: row.source_seq };
+            const receiptValue = receipt(row);
+            return { ...target, revision: revision(row), receipt: receiptValue, instruction: instruction(target, receiptValue) };
+        }), has_more: rows.length > MAX_INBOX_AUDIT_TARGETS, no_finding: "stay_silent" };
+}
+export function completeInboxAuditTarget(file, agentId, receiptValue, outcome, now = new Date()) {
+    if (!OUTCOMES.has(outcome))
+        return { completed: false, reason: "invalid_outcome" };
+    const decoded = parseReceipt(receiptValue);
+    if (!decoded || decoded.agent_id !== agentId)
+        return { completed: false, reason: "invalid_receipt" };
+    return mutate(file, (registry) => {
+        const row = registry.targets.find((candidate) => candidate.agent_id === decoded.agent_id && candidate.target === decoded.target);
+        if (!row || row.anchor !== decoded.anchor)
+            return { completed: false, reason: "stale" };
+        if (row.status === "completed")
+            return { completed: false, reason: "already_completed" };
+        if (revision(row) !== decoded.revision)
+            return { completed: false, reason: "stale" };
+        row.status = "completed";
+        row.completed_at = now.toISOString();
+        row.completed_anchor = row.anchor;
+        row.completed_outcome = outcome;
+        return { completed: true, reason: "completed" };
+    });
 }

package/dist/app/agent-cli.mjs

@@ -7,7 +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 { completeInboxAuditTarget, 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";
@@ -142,7 +142,7 @@ function agentConfigRequest(argv, env, config, agent, dependencies) {
     const [operation = "show", ...rest] = argv;
     const authority = { kind: "agent", agentId: agent.agentId };
     const options = parseOptions(rest, new Set(["--json"]));
-    const unknownFlags = [...options.values.keys()].filter((flag) => !["--agent", "--chat", "--model"].includes(flag));
+    const unknownFlags = [...options.values.keys()].filter((flag) => !["--agent", "--chat", "--model", "--interval"].includes(flag));
     if (unknownFlags.length)
         throw new Error(`config 不支持参数：${unknownFlags.join(", ")}；运行 larkin config --help`);
     const assertOnlyFlags = (valueFlags, booleanFlags = []) => {
@@ -238,6 +238,24 @@ function agentConfigRequest(argv, env, config, agent, dependencies) {
         else
             throw new Error("用法: larkin config mention global <require|free> | mention agent <inherit|require|free> | mention chat <oc_id> <inherit|require|free> [--agent <App ID>]");
     }
+    else if (operation === "inbox-audit") {
+        const [scope, first] = options.positionals;
+        if (scope === "global")
+            assertOnlyFlags(["--interval"]);
+        else if (scope === "agent")
+            assertOnlyFlags(["--agent", "--interval"]);
+        else
+            assertOnlyFlags([]);
+        if (options.positionals.length !== 2) {
+            throw new Error("用法: larkin config inbox-audit global <on|off> [--interval <15m|1h>] | inbox-audit agent <inherit|on|off> [--agent <App ID>] [--interval <15m|inherit>]");
+        }
+        mutation = larkinConfig.inboxAuditMutationFromCli({
+            scope: scope || "",
+            enabled: first,
+            interval: options.values.get("--interval"),
+            agentId: targetId,
+        });
+    }
     else if (operation === "apply") {
         assertOnlyFlags(["--agent"]);
         if (options.positionals.length)
@@ -251,7 +269,7 @@ function agentConfigRequest(argv, env, config, agent, dependencies) {
         }).catch((error) => { throw new Error(`配置已保存但未应用：${error instanceof Error ? error.message : String(error)}`); });
     }
     else
-        throw new Error("config 只支持 show/runtime/model/effort/mention/apply；运行 larkin config --help");
+        throw new Error("config 只支持 show/runtime/model/effort/mention/inbox-audit/apply；运行 larkin config --help");
     const result = larkinConfig.mutateConfig(env, mutation, authority);
     return { ok: true, revision: result.revision, persisted: true, applyState: result.applyState, changedScope: result.changedScope };
 }
@@ -519,10 +537,23 @@ export function runAgentCli(argv, env = process.env, dependencies = {}) {
             }
             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");
+                const file = inboxAuditRegistryFile(config.larkinHome);
+                if (options.positionals[0] === "complete") {
+                    if (options.positionals.length !== 1 || options.booleans.size > 1 || [...options.values.keys()].some((key) => !["--receipt", "--outcome"].includes(key))) {
+                        throw new Error("用法: larkin inbox audit complete --receipt <receipt> --outcome <no-finding|handled> [--json]");
+                    }
+                    const receipt = options.values.get("--receipt");
+                    const outcome = options.values.get("--outcome");
+                    if (!receipt || !outcome)
+                        throw new Error("用法: larkin inbox audit complete --receipt <receipt> --outcome <no-finding|handled> [--json]");
+                    const completion = completeInboxAuditTarget(file, agent.agentId, receipt, outcome);
+                    emitJson(io, completion);
+                    return completion.reason === "invalid_receipt" || completion.reason === "invalid_outcome" ? 2 : 0;
                 }
-                emitJson(io, readInboxAuditTargets(inboxAuditRegistryFile(config.larkinHome), agent.agentId));
+                if (options.positionals.length || options.values.size || options.booleans.size > 1)
+                    throw new Error("inbox audit 只接受 --json；完成检查用 inbox audit complete");
+                const audit = readInboxAuditTargets(file, agent.agentId);
+                emitJson(io, audit);
                 return 0;
             }
             if (options.positionals.length || [...options.values.keys()].some((flag) => !["--target", "--limit"].includes(flag))) {

package/dist/app/agent-config.mjs

@@ -52,11 +52,11 @@ const die = (message) => {
     process.exit(1);
 };
 if (!kind || !["agents", "model", "runtime", "effort", "chats", "config"].includes(kind)) {
-    die("用法: larkin agents | larkin config <show|mention|apply> | larkin model [<id>] | larkin runtime [<id>] [--model <id>] | larkin effort [<level>|clear] | larkin chats [free|strict <oc_id>]");
+    die("用法: larkin agents | larkin config <show|mention|inbox-audit|apply> | larkin model [<id>] | larkin runtime [<id>] [--model <id>] | larkin effort [<level>|clear] | larkin chats [free|strict <oc_id>]");
 }
 const allowedValueFlags = {
     agents: new Set(), model: new Set(["--agent"]), runtime: new Set(["--agent", "--model"]),
-    effort: new Set(["--agent"]), chats: new Set(["--agent"]), config: new Set(["--agent", "--chat"]),
+    effort: new Set(["--agent"]), chats: new Set(["--agent"]), config: new Set(["--agent", "--chat", "--interval"]),
 };
 const allowedBooleanFlags = {
     agents: new Set(["--json"]), model: new Set(), runtime: new Set(), effort: new Set(), chats: new Set(), config: new Set(["--json"]),
@@ -92,6 +92,7 @@ for (let index = 0; index < rest.length; index += 1) {
 const flagAgent = parsedValues.get("--agent");
 const flagModel = parsedValues.get("--model");
 const flagChat = parsedValues.get("--chat");
+const flagInterval = parsedValues.get("--interval");
 const flagJson = parsedBooleans.has("--json");
 const value = positionals[0];
 function assertOnlyFlags(valueFlags, booleanFlags = []) {
@@ -151,13 +152,23 @@ else if (kind === "config") {
         if (positionals.length !== 4)
             die("用法: larkin config mention chat <oc_id> <inherit|require|free> [--agent <App ID>]");
     }
+    else if (operation === "inbox-audit" && scope === "global") {
+        assertOnlyFlags(["--interval"]);
+        if (positionals.length !== 3)
+            die("用法: larkin config inbox-audit global <on|off> [--interval <15m|1h>]");
+    }
+    else if (operation === "inbox-audit" && scope === "agent") {
+        assertOnlyFlags(["--agent", "--interval"]);
+        if (positionals.length !== 3)
+            die("用法: larkin config inbox-audit agent <inherit|on|off> [--agent <App ID>] [--interval <15m|inherit>]");
+    }
     else if (operation === "apply") {
         assertOnlyFlags(["--agent"]);
         if (positionals.length !== 1)
             die("用法: larkin config apply [--agent <App ID>]");
     }
     else {
-        die("config 只支持 show/mention/apply；运行 larkin config --help");
+        die("config 只支持 show/mention/inbox-audit/apply；运行 larkin config --help");
     }
 }
 const loaded = (() => {
@@ -339,12 +350,17 @@ if (kind === "config") {
             say(JSON.stringify(view, null, 2));
         else {
             say(`全局群消息策略=${String(view.mentionPolicy)}（free 会唤醒所有继承它的 Agent）`);
+            const inboxAudit = view.inboxAudit;
+            say(`全局 Inbox Audit=${inboxAudit?.enabled ? "on" : "off"} interval=${larkinConfig.formatInboxAuditInterval(Number(inboxAudit?.intervalMs || larkinConfig.DEFAULT_INBOX_AUDIT_INTERVAL_MS))}（默认关闭；未 @ 的 require 群消息不会进入审计）`);
             for (const item of view.agents) {
                 const mention = item.mention;
+                const agentAudit = item.inboxAudit;
                 const apply = item.apply;
-                say(`agent=${item.agentId} runtime=${item.runtime} model=${item.model} effort=${item.effort || "default"} mention=${mention.override} apply=${apply.applyState || "unknown"}`);
+                say(`agent=${item.agentId} runtime=${item.runtime} model=${item.model} effort=${item.effort || "default"} mention=${mention.override} inbox-audit=${agentAudit?.override?.enabled || "inherit"} apply=${apply.applyState || "unknown"}`);
                 if (mention.chat)
                     say(`  chat=${mention.chat.chatId} override=${mention.chat.override} effective=${mention.chat.effective} source=${mention.chat.source}`);
+                if (agentAudit?.effective)
+                    say(`  inbox-audit effective=${agentAudit.effective.enabled ? "on" : "off"} interval=${larkinConfig.formatInboxAuditInterval(Number(agentAudit.effective.intervalMs || larkinConfig.DEFAULT_INBOX_AUDIT_INTERVAL_MS))}`);
             }
         }
         process.exit(0);
@@ -374,6 +390,21 @@ if (kind === "config") {
         say(JSON.stringify({ ok: true, revision: result.revision, persisted: result.persisted, applyState: result.applyState, changedScope: result.changedScope }, null, 2));
         process.exit(0);
     }
+    if (operation === "inbox-audit") {
+        try {
+            const result = larkinConfig.mutateConfig(process.env, larkinConfig.inboxAuditMutationFromCli({
+                scope: scope || "",
+                enabled: first,
+                interval: flagInterval,
+                agentId: scope === "agent" ? requireTarget() : (selected || keys[0] || ""),
+            }), authority);
+            say(JSON.stringify({ ok: true, revision: result.revision, persisted: result.persisted, applyState: result.applyState, changedScope: result.changedScope }, null, 2));
+        }
+        catch (error) {
+            die(error instanceof Error ? error.message : String(error));
+        }
+        process.exit(0);
+    }
     if (operation === "apply") {
         const agentId = requireTarget();
         const expectedSignature = larkinConfig.runtimeConfigSignature(config, agentId);
@@ -393,7 +424,7 @@ if (kind === "config") {
         }
         process.exit(0);
     }
-    die("config 只支持 show/mention/apply");
+    die("config 只支持 show/mention/inbox-audit/apply");
 }
 let key = flagAgent;
 if (!key && runtimeAgentId)

package/dist/app/cli.mjs

@@ -73,6 +73,7 @@ Examples:
   larkin config show --agent cli_x --chat oc_x --json
   larkin config runtime pi --agent cli_x --model default
   larkin config mention chat oc_x free --agent cli_x
+  larkin config inbox-audit global on --interval 15m
 
 Credentials, internal paths, serverId, activeAgent, and raw config are never exposed here.`,
     session: `Usage: larkin session reset --agent <App ID> --json [--wait-ready <seconds>]

package/dist/dashboard/dashboard-config-controller.mjs

@@ -401,12 +401,27 @@ function dashboardMutation(value) {
         "set-global-mention": ["operation", "value"], "set-agent-mention": ["operation", "agentId", "value"],
         "set-chat-mention": ["operation", "agentId", "chatId", "value"], "set-agent-runtime": ["operation", "agentId", "runtime", "model"],
         "set-agent-model": ["operation", "agentId", "model"], "set-agent-effort": ["operation", "agentId", "effort"],
+        "set-global-inbox-audit": ["operation", "enabled", "intervalMs"], "set-agent-inbox-audit": ["operation", "agentId", "enabled", "intervalMs"],
     };
     if (!allowed[operation] || Object.keys(value).some((key) => !allowed[operation].includes(key)))
         throw new Error("unsupported operation");
     if (operation === "set-global-mention")
         return { kind: operation, value: String(value.value) };
+    if (operation === "set-global-inbox-audit") {
+        if (value.enabled !== undefined && typeof value.enabled !== "boolean")
+            throw new Error("invalid inbox-audit enabled");
+        if (value.intervalMs !== undefined && (typeof value.intervalMs !== "number" || !Number.isSafeInteger(value.intervalMs)))
+            throw new Error("invalid inbox-audit interval");
+        return { kind: operation, ...(value.enabled !== undefined ? { enabled: value.enabled } : {}), ...(value.intervalMs !== undefined ? { intervalMs: value.intervalMs } : {}) };
+    }
     const agentId = String(value.agentId || "");
+    if (operation === "set-agent-inbox-audit") {
+        if (value.enabled !== undefined && value.enabled !== "inherit" && typeof value.enabled !== "boolean")
+            throw new Error("invalid inbox-audit enabled");
+        if (value.intervalMs !== undefined && value.intervalMs !== "inherit" && (typeof value.intervalMs !== "number" || !Number.isSafeInteger(value.intervalMs)))
+            throw new Error("invalid inbox-audit interval");
+        return { kind: operation, agentId, ...(value.enabled !== undefined ? { enabled: value.enabled } : {}), ...(value.intervalMs !== undefined ? { intervalMs: value.intervalMs } : {}) };
+    }
     if (operation === "set-agent-mention")
         return { kind: operation, agentId, value: String(value.value) };
     if (operation === "set-chat-mention")