@ganglion/xacpx 0.9.3 → 0.10.0

package/dist/commands/handlers/later-handler.d.ts

@@ -3,10 +3,10 @@ import type { ScheduledSessionMode } from "../../scheduled/scheduled-types";
 import type { HelpTopicMetadata } from "../help/help-types";
 export declare function laterHelp(): HelpTopicMetadata;
 export declare function handleLaterHelp(): RouterResponse;
-export declare function handleLaterCreate(tokens: string[], scheduled: ScheduledRouterOps, chatKey: string, currentSession: {
+export declare function handleLaterCreate(tokens: string[], tails: string[], scheduled: ScheduledRouterOps, chatKey: string, currentSession: {
     alias: string;
     agent: string;
     workspace: string;
 } | null, defaultMode: ScheduledSessionMode, accountId?: string, replyContextToken?: string): Promise<RouterResponse>;
-export declare function handleLaterList(scheduled: ScheduledRouterOps): RouterResponse;
-export declare function handleLaterCancel(id: string, scheduled: ScheduledRouterOps): Promise<RouterResponse>;
+export declare function handleLaterList(scheduled: ScheduledRouterOps, chatKey: string): RouterResponse;
+export declare function handleLaterCancel(id: string, scheduled: ScheduledRouterOps, chatKey: string): Promise<RouterResponse>;

package/dist/commands/parse-command.d.ts

@@ -162,6 +162,7 @@ export type ParsedCommand = {
 } | {
     kind: "later.create";
     tokens: string[];
+    tails: string[];
 } | {
     kind: "later.list";
 } | {

package/dist/commands/router-types.d.ts

@@ -41,7 +41,7 @@ export interface ActiveHumanQuestionPackageContext {
     }>;
     queuedCount: number;
 }
-export type WritableConfigStore = Pick<ConfigStore, "load" | "save" | "upsertWorkspace" | "removeWorkspace" | "upsertAgent" | "removeAgent" | "updateTransport" | "updateChannel">;
+export type WritableConfigStore = Pick<ConfigStore, "load" | "upsertWorkspace" | "removeWorkspace" | "upsertAgent" | "removeAgent" | "updateTransport" | "updateChannel" | "getRawValue" | "setRawValue" | "unsetRawValue">;
 export interface CommandRouterContext {
     sessions: SessionService;
     transport: SessionTransport;

package/dist/config/config-store.d.ts

@@ -1,13 +1,52 @@
-import type { AppConfig } from "./types";
+import type { AgentConfig, AppConfig, ChannelRuntimeConfig, PluginConfig } from "./types";
+/**
+ * Raw-patch config persistence.
+ *
+ * The parsed `AppConfig` is a READ model only: parsing drops unknown keys
+ * (e.g. `workspaces.*.allowed_agents`), expands `~` in workspace cwds, and
+ * materializes every default. Serializing it back would destroy a hand-edited
+ * config.json. Every mutation therefore patches the raw JSON document read
+ * straight from disk, touching only the targeted subtree, and never writes a
+ * parsed config object.
+ */
+export type RawConfigPathSegment = string | {
+    /** Addresses the entry of a JSON array whose `id` property equals this value. */
+    id: string;
+    /** When set, a missing entry is materialized from this template on writes. */
+    createWith?: Record<string, unknown>;
+};
+export type RawConfigPath = readonly RawConfigPathSegment[];
+export type RawConfigLookup = {
+    present: true;
+    value: unknown;
+} | {
+    present: false;
+};
 export declare class ConfigStore {
     private readonly path;
     constructor(path: string);
     load(): Promise<AppConfig>;
-    save(config: AppConfig): Promise<void>;
+    /** Reads the raw (unparsed) value at `path`, e.g. to capture it for a rollback. */
+    getRawValue(path: RawConfigPath): Promise<RawConfigLookup>;
+    setRawValue(path: RawConfigPath, value: unknown): Promise<AppConfig>;
+    unsetRawValue(path: RawConfigPath): Promise<AppConfig>;
     upsertWorkspace(name: string, cwd: string, description?: string): Promise<AppConfig>;
     removeWorkspace(name: string): Promise<AppConfig>;
-    upsertAgent(name: string, agent: AppConfig["agents"][string]): Promise<AppConfig>;
+    upsertAgent(name: string, agent: AgentConfig): Promise<AppConfig>;
     removeAgent(name: string): Promise<AppConfig>;
-    updateTransport(transport: Partial<AppConfig["transport"]>): Promise<AppConfig>;
-    updateChannel(channel: Partial<AppConfig["channel"]>): Promise<AppConfig>;
+    /** Sets only the given transport keys; a key explicitly set to `undefined` is removed. */
+    updateTransport(patch: Partial<AppConfig["transport"]>): Promise<AppConfig>;
+    /** Sets only the given channel keys; a key explicitly set to `undefined` is removed. */
+    updateChannel(patch: Partial<AppConfig["channel"]>): Promise<AppConfig>;
+    /** Replaces the tool-managed `plugins` array; everything else stays untouched. */
+    replacePlugins(plugins: PluginConfig[]): Promise<AppConfig>;
+    /** Replaces the tool-managed `channels` array; everything else stays untouched. */
+    replaceChannels(channels: ChannelRuntimeConfig[]): Promise<AppConfig>;
+    private patchRaw;
+    private readRaw;
 }
+export declare function serializeRawConfig(raw: Record<string, unknown>): string;
+export declare function readRawConfigValue(root: Record<string, unknown>, path: RawConfigPath): RawConfigLookup;
+export declare function setRawConfigValue(root: Record<string, unknown>, path: RawConfigPath, value: unknown): void;
+export declare function unsetRawConfigValue(root: Record<string, unknown>, path: RawConfigPath): void;
+export declare function assertSafeConfigKey(key: string): void;

package/dist/config/types.d.ts

@@ -7,6 +7,12 @@ export type WechatReplyMode = ReplyMode;
 export interface ChannelConfig {
     type: string;
     replyMode: ReplyMode;
+    /**
+     * Sender ids the operator trusts as channel owners. Group turns from these
+     * senders pass owner-gated command authorization even when the channel
+     * protocol carries no group-role information (e.g. WeChat).
+     */
+    ownerIds?: string[];
     options?: Record<string, unknown>;
 }
 /** @deprecated Legacy input shape only. Use ChannelConfig. */
@@ -67,6 +73,8 @@ export interface ChannelRuntimeConfig {
     type: string;
     enabled: boolean;
     replyMode?: ReplyMode;
+    /** See ChannelConfig.ownerIds — per-channel trusted owner sender ids. */
+    ownerIds?: string[];
     options?: Record<string, unknown>;
 }
 export interface PluginConfig {

package/dist/i18n/types.d.ts

@@ -11,6 +11,7 @@ export interface SessionMessages {
     currentLabel: string;
     sessionListItem: (alias: string, agent: string, workspace: string) => string;
     sessionCreated: (alias: string) => string;
+    sessionAlreadyExists: (alias: string, agent: string, workspace: string) => string;
     sessionAttachNotFound: (alias: string, agent: string, workspace: string) => string;
     sessionAttached: (alias: string) => string;
     switched: (alias: string, agent: string, workspace: string) => string;
@@ -43,6 +44,7 @@ export interface SessionMessages {
     sessionBlockedByTasksHint: string;
     sessionRemoved: (alias: string) => string;
     sessionRemovedWasActive: string;
+    sessionRemovedWasActivePromoted: (alias: string) => string;
     sessionTransportShared: (transportSession: string, count: number) => string;
     sessionOrchestrationPurgeFailed: (warning: string) => string;
     sessionTransportTeardownFailed: (warning: string) => string;
@@ -689,6 +691,8 @@ export interface PluginCliMessages {
     noPlugins: string;
     pluginListHeader: string;
     unrecognizedArgs: (args: string) => string;
+    pluginSpecHasDoubleQuote: (spec: string) => string;
+    pluginSpecHasPercentOnWindows: (spec: string) => string;
     pluginInstallFailed: (packageSpec: string, error: string) => string;
     pluginValidateFailed: (recordedName: string, error: string) => string;
     pluginInstalled: (recordedName: string) => string;
@@ -775,8 +779,6 @@ export interface WeixinMessages {
     debugEnabled: string;
     debugDisabled: string;
     sessionCleared: string;
-    noAccountsLoggedIn: string;
-    logoutSuccess: string;
     commandFailed: (detail: string) => string;
 }
 export interface MigrateMessages {
@@ -802,6 +804,7 @@ export interface MiscMessages {
     quotaHeadsUp: string;
     quotaOverflowSummary: (count: number) => string;
     finalHeadsUp: (total: number, sentSoFar: number, remaining: number) => string;
+    finalAllParked: (count: number) => string;
     quotedMessagePrefix: (parts: string) => string;
     scheduledTaskFailed: (message: string) => string;
     orchestrationTaskCompleted: (taskId: string, workerSession: string, result: string) => string;
@@ -824,6 +827,8 @@ export interface MiscMessages {
     delegateQPackageInstr3: string;
     commandAccessDeniedSuffix: string;
     commandAccessDeniedHint: string;
+    commandAccessDeniedChatTypeMissingSuffix: string;
+    commandAccessDeniedChatTypeMissingHint: string;
     commandLabelThisMessage: string;
     sessionResetNoCurrentSession: string;
     sessionResetFailed: (alias: string) => string;

package/dist/perf/perf-log-writer.d.ts

@@ -13,6 +13,7 @@ export interface CreatePerfLogWriterOptions {
     appendImpl?: (path: string, data: string) => Promise<void>;
     mkdirImpl?: (path: string, opts: {
         recursive: true;
+        mode?: number;
     }) => Promise<void>;
     now?: () => Date;
 }

package/dist/plugin-api.js

@@ -68,6 +68,11 @@ var init_session = __esm(() => {
     currentLabel: "[current]",
     sessionListItem: (alias, agent, workspace) => `- ${alias} (${agent} @ ${workspace})`,
     sessionCreated: (alias) => `Session "${alias}" created and switched.`,
+    sessionAlreadyExists: (alias, agent, workspace) => [
+      `Session "${alias}" already exists (${agent} @ ${workspace}).`,
+      `Switch to it with /use ${alias}, or remove it first with /session rm ${alias}.`
+    ].join(`
+`),
     sessionAttachNotFound: (alias, agent, workspace) => [
       "No existing session found to attach.",
       `Check the session name and retry: /session attach ${alias} --agent ${agent} --ws ${workspace} --name <session-name>`
@@ -104,6 +109,7 @@ var init_session = __esm(() => {
     sessionBlockedByTasksHint: "Use /tasks to list tasks, or /task cancel <id> to cancel one.",
     sessionRemoved: (alias) => `Session "${alias}" removed.`,
     sessionRemovedWasActive: "This was the active session. Its chat context has been cleared.",
+    sessionRemovedWasActivePromoted: (alias) => `This was the active session. Switched back to the previous session "${alias}".`,
     sessionTransportShared: (transportSession, count) => `Note: backend session "${transportSession}" is still referenced by ${count} other session(s) and was not closed.`,
     sessionOrchestrationPurgeFailed: (warning) => `Note: failed to purge orchestration references (${warning}). Run /tasks clean manually to clean up.`,
     sessionTransportTeardownFailed: (warning) => `Note: backend session could not be closed automatically (${warning}). Run acpx sessions close manually if needed.`,
@@ -397,7 +403,7 @@ var init_later = __esm(() => {
     helpNote2: "Time must be at least 10 seconds and at most 7 days away",
     helpNote3: "By default runs in a new temporary session that is destroyed after completion",
     helpNote4: "Use --bind to send to the session that was current when the task was created (configurable via later.defaultMode)",
-    helpNote5: "/lt list shows all pending tasks globally; in group chats only the owner can cancel",
+    helpNote5: "/lt list shows only this chat's pending tasks; in group chats only the owner can cancel",
     helpNote6: "Scheduling slash-prefixed xacpx commands is not supported",
     helpNote7: "Full time format reference: docs/later-command.md"
   };
@@ -890,6 +896,8 @@ var init_plugin_cli = __esm(() => {
     noPlugins: "No plugins installed yet.",
     pluginListHeader: "Plugins:",
     unrecognizedArgs: (args) => `Unrecognized arguments: ${args}`,
+    pluginSpecHasDoubleQuote: (spec) => `Invalid plugin spec ${spec}: double quotes (") are never valid in an npm package spec.`,
+    pluginSpecHasPercentOnWindows: (spec) => `Invalid plugin spec ${spec}: "%" would be mangled by cmd.exe on Windows. Install the package with npm directly instead.`,
     pluginInstallFailed: (packageSpec, error) => `Plugin ${packageSpec} install failed: ${error}`,
     pluginValidateFailed: (recordedName, error) => `Plugin ${recordedName} validation failed: ${error}`,
     pluginInstalled: (recordedName) => `Plugin ${recordedName} installed`,
@@ -1001,8 +1009,6 @@ var init_weixin = __esm(() => {
     debugEnabled: "Debug mode enabled",
     debugDisabled: "Debug mode disabled",
     sessionCleared: "✅ Session cleared. Starting a fresh conversation.",
-    noAccountsLoggedIn: "No accounts are currently logged in.",
-    logoutSuccess: "✅ Logged out. All account credentials cleared.",
     commandFailed: (detail) => `❌ Command failed: ${detail}`
   };
 });
@@ -1040,6 +1046,7 @@ var init_misc = __esm(() => {
     quotaOverflowSummary: (count) => `(${count} progress updates omitted due to message limit; see final result below)`,
     finalHeadsUp: (total, sentSoFar, remaining) => `—
 \uD83D\uDCC4 Result: ${total} parts total, ${sentSoFar} sent. Reply /jx to see the next ${remaining} parts.`,
+    finalAllParked: (count) => `\uD83D\uDCC4 Message limit reached: the result (${count} parts) is parked. Reply /jx to receive it.`,
     quotedMessagePrefix: (parts) => `[Quote: ${parts}]`,
     scheduledTaskFailed: (message) => `Scheduled task failed: ${message}`,
     orchestrationTaskCompleted: (taskId, workerSession, result) => `Delegation task "${taskId}" completed
@@ -1068,6 +1075,8 @@ var init_misc = __esm(() => {
     delegateQPackageInstr3: "Do not forward the human's exact words to the worker",
     commandAccessDeniedSuffix: " is restricted to group owner only.",
     commandAccessDeniedHint: "To perform control operations, have the owner send them in the group, or use a private chat.",
+    commandAccessDeniedChatTypeMissingSuffix: " was blocked: this channel did not report the chat type (direct or group), so control commands are disabled here.",
+    commandAccessDeniedChatTypeMissingHint: "Read-only commands and prompts still work. This is a channel metadata issue — update or report the channel plugin.",
     commandLabelThisMessage: "This message",
     sessionResetNoCurrentSession: "No session is currently selected. Run /session new ... or /use <alias> first.",
     sessionResetFailed: (alias) => `Session "${alias}" reset failed. The new backend session was not created, please try again later.`,
@@ -1138,6 +1147,11 @@ var init_session2 = __esm(() => {
     currentLabel: "[当前]",
     sessionListItem: (alias, agent2, workspace2) => `- ${alias} (${agent2} @ ${workspace2})`,
     sessionCreated: (alias) => `会话「${alias}」已创建并切换`,
+    sessionAlreadyExists: (alias, agent2, workspace2) => [
+      `会话「${alias}」已存在（${agent2} @ ${workspace2}）。`,
+      `发送 /use ${alias} 切换到它，或先执行 /session rm ${alias} 删除后再创建。`
+    ].join(`
+`),
     sessionAttachNotFound: (alias, agent2, workspace2) => [
       "没有找到可绑定的已有会话。",
       `请确认会话名是否正确，然后重新执行：/session attach ${alias} --agent ${agent2} --ws ${workspace2} --name <会话名>`
@@ -1174,6 +1188,7 @@ var init_session2 = __esm(() => {
     sessionBlockedByTasksHint: "使用 /tasks 查看任务列表，或 /task cancel <id> 取消任务。",
     sessionRemoved: (alias) => `已删除会话「${alias}」。`,
     sessionRemovedWasActive: "该会话是当前活跃会话，已自动清除相关聊天上下文。",
+    sessionRemovedWasActivePromoted: (alias) => `该会话是当前活跃会话，已切换回上一个会话「${alias}」。`,
     sessionTransportShared: (transportSession, count) => `提示：后端会话「${transportSession}」仍被其他 ${count} 个会话引用，未关闭。`,
     sessionOrchestrationPurgeFailed: (warning) => `提示：清理任务编排引用失败（${warning}），请稍后执行 /tasks clean 手动清理。`,
     sessionTransportTeardownFailed: (warning) => `提示：后端会话未能自动关闭（${warning}），如有残留请手动执行 acpx sessions close。`,
@@ -1467,7 +1482,7 @@ var init_later2 = __esm(() => {
     helpNote2: "时间必须在 10 秒之后、7 天之内",
     helpNote3: "默认在为本次任务新建的临时会话里执行，跑完即销毁",
     helpNote4: "加 --bind 改为发送到创建时绑定的当前会话（默认模式可用 later.defaultMode 配置）",
-    helpNote5: "/lt list 显示全局待执行任务；群聊中只有群主可取消",
+    helpNote5: "/lt list 只显示本聊天创建的待执行任务；群聊中只有群主可取消",
     helpNote6: "不支持延迟执行 / 开头的 xacpx 命令",
     helpNote7: "完整时间格式与说明见 docs/later-command.md"
   };
@@ -1960,6 +1975,8 @@ var init_plugin_cli2 = __esm(() => {
     noPlugins: "还没有安装插件。",
     pluginListHeader: "插件：",
     unrecognizedArgs: (args) => `未识别的参数：${args}`,
+    pluginSpecHasDoubleQuote: (spec) => `非法插件 spec ${spec}：npm 包 spec 不允许包含双引号 (")。`,
+    pluginSpecHasPercentOnWindows: (spec) => `非法插件 spec ${spec}：Windows 上 cmd.exe 会展开 %，无法安全传递。请改用 npm 直接安装该包。`,
     pluginInstallFailed: (packageSpec, error) => `插件 ${packageSpec} 安装失败：${error}`,
     pluginValidateFailed: (recordedName, error) => `插件 ${recordedName} 校验失败：${error}`,
     pluginInstalled: (recordedName) => `插件 ${recordedName} 已安装`,
@@ -2071,8 +2088,6 @@ var init_weixin2 = __esm(() => {
     debugEnabled: "Debug 模式已开启",
     debugDisabled: "Debug 模式已关闭",
     sessionCleared: "✅ 会话已清除，重新开始对话",
-    noAccountsLoggedIn: "当前没有已登录的账号",
-    logoutSuccess: "✅ 已退出登录，清除所有账号凭证",
     commandFailed: (detail) => `❌ 指令执行失败: ${detail}`
   };
 });
@@ -2110,6 +2125,7 @@ var init_misc2 = __esm(() => {
     quotaOverflowSummary: (count) => `（因消息次数限制省略 ${count} 条进度，请继续查看下方最终结果）`,
     finalHeadsUp: (total, sentSoFar, remaining) => `—
 \uD83D\uDCC4 结果共 ${total} 段，已发 ${sentSoFar} 段。回复 /jx 续看后 ${remaining} 段。`,
+    finalAllParked: (count) => `\uD83D\uDCC4 已达消息上限：结果共 ${count} 段已暂存。回复 /jx 接收。`,
     quotedMessagePrefix: (parts) => `[引用: ${parts}]`,
     scheduledTaskFailed: (message) => `定时任务执行失败：${message}`,
     orchestrationTaskCompleted: (taskId, workerSession, result) => `委派任务「${taskId}」已完成
@@ -2138,6 +2154,8 @@ var init_misc2 = __esm(() => {
     delegateQPackageInstr3: "不要直接把 human 原话转发给 worker",
     commandAccessDeniedSuffix: " 仅限群创建者/频道 owner 使用。",
     commandAccessDeniedHint: "如果需要执行控制类操作，请由 owner 在群内发送，或改用私聊。",
+    commandAccessDeniedChatTypeMissingSuffix: " 已被拦截：该频道未上报会话类型（直聊/群聊），控制类命令在此暂不可用。",
+    commandAccessDeniedChatTypeMissingHint: "只读命令与普通对话不受影响。这是频道元数据问题，请升级或反馈该频道插件。",
     commandLabelThisMessage: "该消息",
     sessionResetNoCurrentSession: "当前还没有选中的会话。请先执行 /session new ... 或 /use <alias>。",
     sessionResetFailed: (alias) => `会话「${alias}」重置失败。

package/dist/scheduled/scheduled-service.d.ts

@@ -28,8 +28,11 @@ export declare class ScheduledTaskService {
     private readonly claimedInThisSession;
     constructor(state: AppState, stateStore: Pick<StateStore, "save">, options?: ScheduledTaskServiceOptions);
     createTask(input: CreateScheduledTaskInput): Promise<ScheduledTaskRecord>;
-    listPending(): ScheduledTaskRecord[];
-    cancelPending(inputId: string): Promise<boolean>;
+    listPending(chatKey: string): ScheduledTaskRecord[];
+    listPendingAllChats(): ScheduledTaskRecord[];
+    cancelPending(inputId: string, chatKey: string): Promise<boolean>;
+    cancelPendingAnyChat(inputId: string): Promise<boolean>;
+    private cancelPendingWhere;
     markStartupMissed(): Promise<void>;
     claimDueTasks(): Promise<ScheduledTaskRecord[]>;
     markExecuted(id: string): Promise<void>;

package/dist/sessions/session-service.d.ts

@@ -67,9 +67,13 @@ export declare class SessionService {
     createSession(alias: string, agent: string, workspace: string): Promise<ResolvedSession>;
     /**
      * All currently-known logical sessions resolved to transport sessions, deduped by
-     * transport session. Sessions whose agent or workspace is no longer registered are
-     * skipped (toResolvedSession would throw). Used by shutdown cleanup to reap warm
-     * acpx queue owners; never throws.
+     * the composite identity acpx keys its session records on (agent + agent command +
+     * cwd + transport session name). Two aliases sharing a transport-session *name*
+     * but differing in agent/cwd (possible via /session attach) resolve to different
+     * acpx records with their own warm queue owners, so both must survive. Sessions
+     * whose agent or workspace is no longer registered are skipped (toResolvedSession
+     * would throw). Used by startup/shutdown cleanup to reap warm acpx queue owners;
+     * never throws.
      */
     listAllResolvedSessions(): ResolvedSession[];
     resolveSession(alias: string, agent: string, workspace: string, transportSession: string): ResolvedSession;

package/dist/state/state-store.d.ts

@@ -1,8 +1,75 @@
 import { type AppState } from "./types";
-export declare function parseState(raw: unknown, path: string): AppState;
+/**
+ * Format version written on every save. The parser tolerates files without it
+ * (older releases) and ignores it on load; no migration chain exists yet.
+ */
+export declare const STATE_FILE_VERSION = 1;
+/** A record or section that was skipped/repaired while loading state.json. */
+export interface StateLoadDroppedRecord {
+    section: string;
+    key: string;
+    reason: string;
+}
+export interface StateLoadReport {
+    dropped: StateLoadDroppedRecord[];
+    /** Backup copy of the original file, written because records were dropped. */
+    quarantinePath?: string;
+    /** Unreadable original renamed aside (whole-file JSON corruption). */
+    corruptPath?: string;
+    /** Best-effort backup/rename failure; load still returned the cleaned state. */
+    backupError?: string;
+}
+/**
+ * Lenient state parser: a malformed record (or wrong-typed section) is skipped
+ * and collected in `dropped` instead of throwing, so one bad record can never
+ * brick daemon startup. The per-record shape checks themselves stay strict — an
+ * invalid record is quarantined, it never flows into dispatch logic. Only a
+ * non-object top level still throws (StateStore.load treats that as a corrupt
+ * file and renames it aside).
+ */
+export declare function parseState(raw: unknown, path: string, dropped?: StateLoadDroppedRecord[]): AppState;
+export interface StateStoreOptions {
+    /** Injectable clock used for quarantine/corrupt backup file names. */
+    now?: () => Date;
+    /**
+     * Injectable backup writer (tests simulate backup failures). May return the
+     * path actually written when it differs from the requested one (the default
+     * writer suffix-retries instead of overwriting an existing backup).
+     */
+    writeBackup?: (targetPath: string, content: string) => Promise<string | void>;
+}
+/** Result of a side-effect-free {@link StateStore.inspect}. */
+export interface StateLoadInspection {
+    state: AppState;
+    /** Null when the file is fully valid (or missing/empty). */
+    report: StateLoadReport | null;
+}
 export declare class StateStore {
     private readonly path;
-    constructor(path: string);
+    private readonly options;
+    private loadReport;
+    constructor(path: string, options?: StateStoreOptions);
+    /**
+     * Report of the most recent load(): null when the file was fully valid (or
+     * missing/empty), otherwise the dropped/repaired records plus the quarantine
+     * or corrupt backup path. Callers log/print this so silent repair is visible.
+     */
+    get lastLoadReport(): StateLoadReport | null;
     load(): Promise<AppState>;
+    /**
+     * Side-effect-free variant of load() for diagnostic callers (doctor): parses
+     * and reports exactly what load() would drop/repair, but never writes a
+     * quarantine backup, never renames a corrupt file, and does not touch
+     * {@link lastLoadReport}.
+     */
+    inspect(): Promise<StateLoadInspection>;
+    private readAndParse;
     save(state: AppState): Promise<void>;
+    private fileTimestamp;
+    /**
+     * Whole-file corruption (JSON syntax error / non-object top level): rename
+     * the file aside — not copy — so the next save does not fight the corrupt
+     * bytes, then start from an empty state.
+     */
+    private recoverFromCorruptFile;
 }

package/dist/util/private-file.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Runs `fn` while holding the file's proper-lockfile lock, so a caller can make
+ * a whole read→modify→write span atomic with respect to other xacpx-aware
+ * processes (writePrivateFileAtomic alone only serializes the write).
+ *
+ * proper-lockfile is NOT reentrant: inside `fn`, write through the provided
+ * `writeLocked` (same atomic semantics, no re-lock) — never call
+ * writePrivateFileAtomic on the same path or it will deadlock until the lock
+ * goes stale. `realpath: false` keeps locking working for a not-yet-existing
+ * target file (the lock lives at `<path>.lock`).
+ */
+export declare function withPrivateFileLock<T>(path: string, fn: (writeLocked: (content: string) => Promise<void>) => Promise<T>): Promise<T>;
 export declare function writePrivateFileAtomic(path: string, content: string): Promise<void>;
 /**
  * Synchronous private-file write for hot-path callers that cannot await

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",