@steerable/agent-shell 0.6.56 → 0.6.57

package/dist/local-backend/skill-install.js

@@ -5,6 +5,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { getUserDataDir } from '../runtime.js';
+import { fileLockPath } from '../storage/process-locks.js';
+import { acquireWriteLease } from '../storage/write-lease.js';
 import { getSkillsDir, getUserSkillsDir, listSkillRoots } from './skill-loader.js';
 export function resolveUserPath(inputPath) {
     const expanded = inputPath.startsWith('~')
@@ -36,8 +39,14 @@ export function installSkillFromDirectory(sourceDir) {
     }
     const skillName = parseSkillNameFromMarkdown(fs.readFileSync(skillMdPath, 'utf8'), path.basename(sourceDir));
     const dest = path.join(getUserSkillsDir(), skillName);
-    fs.mkdirSync(dest, { recursive: true });
-    fs.cpSync(sourceDir, dest, { recursive: true });
+    const lease = acquireWriteLease(fileLockPath(getUserDataDir(), 'user-skills'), 5_000);
+    try {
+        fs.mkdirSync(dest, { recursive: true });
+        fs.cpSync(sourceDir, dest, { recursive: true });
+    }
+    finally {
+        lease.release();
+    }
     return { name: skillName, dest };
 }
 function isInside(candidate, root) {

package/dist/log.d.ts

@@ -1,4 +1,17 @@
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/**
+ * 终端回显范围。`routine` 关掉 log/info/debug/warn，error 仍走 stderr；
+ * `all` 连 error 一起关掉，给占满整个终端的界面用。日志文件照写。
+ */
+export type LogConsoleSilence = 'routine' | 'all';
+/**
+ * 关掉宿主日志和 console 的终端回显，直到 {@link restoreLogConsole}。
+ * 命令行占用 stdout 输出结果或画界面时调用。
+ * @param scope 关掉的范围。
+ */
+export declare function silenceLogConsole(scope: LogConsoleSilence): void;
+/** 恢复调用 {@link silenceLogConsole} 之前的 console。 */
+export declare function restoreLogConsole(): void;
 export declare const log: {
     error: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;

package/dist/log.js

@@ -8,6 +8,27 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { getUserDataDir } from './runtime.js';
+const consoleMethods = ['log', 'info', 'debug', 'warn', 'error'];
+const routineMethods = ['log', 'info', 'debug', 'warn'];
+let saved = null;
+/**
+ * 关掉宿主日志和 console 的终端回显，直到 {@link restoreLogConsole}。
+ * 命令行占用 stdout 输出结果或画界面时调用。
+ * @param scope 关掉的范围。
+ */
+export function silenceLogConsole(scope) {
+    saved ??= Object.fromEntries(consoleMethods.map((name) => [name, console[name]]));
+    for (const name of scope === 'all' ? consoleMethods : routineMethods)
+        console[name] = () => { };
+}
+/** 恢复调用 {@link silenceLogConsole} 之前的 console。 */
+export function restoreLogConsole() {
+    if (!saved)
+        return;
+    for (const name of consoleMethods)
+        console[name] = saved[name];
+    saved = null;
+}
 function formatArg(part) {
     if (typeof part === 'string')
         return part;

package/dist/scenario/pack.d.ts

@@ -5,4 +5,4 @@
  *
  * 契约全文与设计约束见 packages/pack-sdk/types/index.d.ts 头注释。
  */
-export type { ScenarioId, ToolMode, ToolExposure, PackToolContext, PackToolHandler, ToolContribution, ServiceFactory, ServiceCreateContext, MigrationContribution, SkillContribution, AgentSeedIdentity, AgentSeed, HttpRouteContribution, HttpRouteRequest, MainContribution, ComponentRef, SettingsPanelContribution, RouteContribution, ChatSlotContribution, CardRendererContribution, RendererContribution, BrandSpec, PackagingSpec, ScenarioPack, PackBackendRouteResponse, PackBackendRouteRequest, PackBackendRoute, PackTurnObserver, PackTurnHooks, } from '@steerable/pack-sdk';
+export type { ScenarioId, ToolMode, ToolExposure, PackToolContext, PackToolHandler, ToolContribution, ServiceFactory, ServiceCreateContext, MigrationContribution, SkillContribution, AgentSeedIdentity, AgentSeed, HttpRouteContribution, HttpRouteRequest, MainContribution, ComponentRef, SettingsPanelContribution, RouteContribution, ChatSlotContribution, CardRendererContribution, RendererContribution, BrandSpec, PackagingSpec, CliCommandIO, CliCommandSpec, ScenarioPack, PackBackendRouteResponse, PackBackendRouteRequest, PackBackendRoute, PackTurnObserver, PackTurnHooks, } from '@steerable/pack-sdk';

package/dist/sidecar/reverse-spawn.js

@@ -75,9 +75,13 @@ export function createProcessSpawnHandler() {
 function runHelper(helperPath, spec) {
     return new Promise((resolve, reject) => {
         const child = spawn(helperPath, [], {
-            stdio: ['pipe', 'pipe', 'inherit'],
+            stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
         });
+        createInterface({ input: child.stderr }).on('line', (line) => {
+            if (line.trim())
+                log.warn('[host-spawn] helper', line);
+        });
         let stdout = '';
         let stderr = '';
         let truncated = false;

package/dist/storage/driver.d.ts

@@ -34,6 +34,8 @@ export interface StorageDriver {
     scoped(scope: TenantScope): ScopedStore;
     packAccess(scope: TenantScope): PackDbAccess;
     applyPackMigrations(): Promise<void>;
+    /** Notifies when another connection commits. Optional for non-sqlite drivers. */
+    watchChanges?(onChange: () => void): void;
     close(): Promise<void>;
 }
 export type StorageDriverFactory = () => StorageDriver | Promise<StorageDriver>;
@@ -53,5 +55,7 @@ export declare function initializeStorage(): Promise<StorageDriver>;
 export declare function getScopedStore(scope: TenantScope): ScopedStore;
 /** Returns scope-bound scenario-pack access after initialization. */
 export declare function getPackDbAccess(scope: TenantScope): PackDbAccess;
+/** Forwards another connection's commits to the host event bus. */
+export declare function watchStorageChanges(onChange: () => void): void;
 /** Closes the active driver. Mainly used by host shutdown and tests. */
 export declare function closeStorage(): Promise<void>;

package/dist/storage/driver.js

@@ -90,6 +90,10 @@ export function getPackDbAccess(scope) {
     }
     return activeDriver.packAccess(scope);
 }
+/** Forwards another connection's commits to the host event bus. */
+export function watchStorageChanges(onChange) {
+    activeDriver?.watchChanges?.(onChange);
+}
 /** Closes the active driver. Mainly used by host shutdown and tests. */
 export async function closeStorage() {
     const driver = activeDriver;

package/dist/storage/index.d.ts

@@ -301,9 +301,8 @@ export declare class SqliteScopedStore implements ScopedStore {
      */
     saveTaskProcess(taskId: string, processJson: string): Promise<void>;
     /**
-     * 启动清扫：running 任务只可能属于上一个已死的进程（任务流不跨进程
-     * 存活），全部落成 failed/interrupted——与 W7-1 turn_active 检测器同
-     * 理，残留 running 是崩溃签名，不是真相。
+     * 启动清扫：只把所属实例已经退出的 running / blocked 任务标成 failed。
+     * 没有 owner 的旧行视为已退出。仍被实例锁占住的任务保持原状态。
      */
     failRunningTasks(reason: string): Promise<number>;
     /**
@@ -343,6 +342,12 @@ export declare class SqliteScopedStore implements ScopedStore {
         kind?: InsightKind;
         limit?: number;
     }): Promise<InsightOutboxRow[]>;
+    /**
+     * Claims pending outbox rows for this process before upload.
+     * A row owned by a live instance is left alone. Without a bound instance
+     * this falls back to a plain list (single-process callers and tests).
+     */
+    claimInsightsForUpload(limit: number): Promise<InsightOutboxRow[]>;
     markInsightUploaded(id: string): Promise<void>;
     markInsightUploadError(id: string, error: string): Promise<void>;
     insightStats(): Promise<{

package/dist/storage/index.js

@@ -1,8 +1,10 @@
 import { randomUUID } from 'crypto';
+import path from 'node:path';
 import { ALL_ROUND_ASSISTANT_AGENT_ID, LOCAL_ASSISTANT_AGENT_ID, getBrand, } from '../brand.js';
 import { isShellBuiltinAgentEnabled } from '../product-config.js';
 import { DEFAULT_LLM_SETTINGS, llmSettingsCarryExpiredBakedKey, llmSettingsMatchOllamaDefaults, mergeLlmSettings, } from './llm-settings.js';
 import { MESSAGE_ORDER_DESC } from './message-order.js';
+import { currentStorageInstanceId, instanceOwnerIsLive, } from './process-locks.js';
 import { mergeTelemetrySettings, } from './telemetry-settings.js';
 import { mergeWebSearchSettings, } from './web-search-settings.js';
 import { mergeInsightsProfile, mergeInsightsSettings, } from './insights-settings.js';
@@ -325,6 +327,10 @@ export class SqliteScopedStore {
         this.ensureColumn('tasks', 'depends_on', 'TEXT');
         // 后台任务推理过程：流事件回写，不bump updated_at（见 saveTaskProcess）。
         this.ensureColumn('tasks', 'process_json', 'TEXT');
+        // 创建该任务的宿主实例。清扫只处理所属实例已经退出的任务。
+        this.ensureColumn('tasks', 'owner_instance_id', 'TEXT');
+        this.ensureColumn('insights_outbox', 'claimed_by', 'TEXT');
+        this.ensureColumn('insights_outbox', 'claimed_at', 'TEXT');
         // 智能体技能面（增量迁移）：load_all_skills = 无视触发条件全量加载。
         // 此前这个行为是 router 里 `chatAgentId === 'all-round-assistant'` 的
         // 硬编码，自建智能体拿不到；建列时一次性回填给内置「智能助手」，之后
@@ -1013,12 +1019,12 @@ export class SqliteScopedStore {
         tenant_id, user_id,
         id, chat_id, task, status, answer, error,
         worktree_path, worktree_branch, worktree_state, record_id, trace_id,
-        depends_on, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?, ?, ?, NULL, ?, ?, ?)
+        depends_on, owner_instance_id, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?, ?, ?, NULL, ?, ?, ?, ?)
     `).run(this.scope.tenantId, this.scope.userId, id, input.chatId, input.task, input.initialStatus ?? 'running', input.worktreePath ?? null, input.worktreeBranch ?? null, 
         // worktree 任务一创建就进入 pending（等待终态后合并/丢弃）；
         // 非 worktree 任务该列无意义，保持 NULL。
-        input.worktreePath ? 'pending' : null, input.recordId ?? null, input.dependsOn?.length ? JSON.stringify(input.dependsOn) : null, now, now);
+        input.worktreePath ? 'pending' : null, input.recordId ?? null, input.dependsOn?.length ? JSON.stringify(input.dependsOn) : null, currentStorageInstanceId(), now, now);
         const row = this.db.prepare(`SELECT * FROM tasks WHERE tenant_id = ? AND user_id = ? AND id = ?`).get(this.scope.tenantId, this.scope.userId, id);
         return this.mapTask(row);
     }
@@ -1071,29 +1077,31 @@ export class SqliteScopedStore {
             .run(processJson, this.scope.tenantId, this.scope.userId, taskId);
     }
     /**
-     * 启动清扫：running 任务只可能属于上一个已死的进程（任务流不跨进程
-     * 存活），全部落成 failed/interrupted——与 W7-1 turn_active 检测器同
-     * 理，残留 running 是崩溃签名，不是真相。
+     * 启动清扫：只把所属实例已经退出的 running / blocked 任务标成 failed。
+     * 没有 owner 的旧行视为已退出。仍被实例锁占住的任务保持原状态。
      */
     async failRunningTasks(reason) {
-        const info = this.db
-            .prepare(`UPDATE tasks SET status = 'failed', error = ?, updated_at = ?
-                WHERE tenant_id = ? AND user_id = ? AND status = 'running'`)
-            .run(reason, new Date().toISOString(), this.scope.tenantId, this.scope.userId);
-        // 级联：blocked 任务的点火能力在 TaskService（进程内），不跨进程存活；
-        // 重启后统一标 failed，模型经 task_status 看到原因后可重跑。
-        const blocked = this.db
-            .prepare(`SELECT id FROM tasks
-                WHERE tenant_id = ? AND user_id = ? AND status = 'blocked'`)
+        const rows = this.db
+            .prepare(`SELECT id, status, owner_instance_id AS owner
+                FROM tasks
+                WHERE tenant_id = ? AND user_id = ? AND status IN ('running', 'blocked')`)
             .all(this.scope.tenantId, this.scope.userId);
+        const dataDir = path.dirname(this.db.name);
         const now = new Date().toISOString();
-        for (const row of blocked) {
-            this.db
+        let swept = 0;
+        for (const row of rows) {
+            if (row.owner && instanceOwnerIsLive(dataDir, row.owner))
+                continue;
+            const error = row.status === 'blocked'
+                ? '进程重启中断了编排等待（依赖任务已随进程终止）；请重新 task_run。'
+                : reason;
+            const info = this.db
                 .prepare(`UPDATE tasks SET status = 'failed', error = ?, updated_at = ?
-                  WHERE tenant_id = ? AND user_id = ? AND id = ?`)
-                .run(`进程重启中断了编排等待（依赖任务已随进程终止）；请重新 task_run。`, now, this.scope.tenantId, this.scope.userId, row.id);
+                  WHERE tenant_id = ? AND user_id = ? AND id = ? AND status = ?`)
+                .run(error, now, this.scope.tenantId, this.scope.userId, row.id, row.status);
+            swept += info.changes;
         }
-        return info.changes + blocked.length;
+        return swept;
     }
     // ─── W6-9 用量与成本归因 ─────────────────────────────────────────────
     /**
@@ -1247,6 +1255,37 @@ export class SqliteScopedStore {
         const rows = this.db.prepare(sql).all(...params);
         return rows.map((row) => this.mapInsightOutbox(row));
     }
+    /**
+     * Claims pending outbox rows for this process before upload.
+     * A row owned by a live instance is left alone. Without a bound instance
+     * this falls back to a plain list (single-process callers and tests).
+     */
+    async claimInsightsForUpload(limit) {
+        const me = currentStorageInstanceId();
+        if (!me)
+            return this.listInsightOutbox({ uploaded: false, limit });
+        const capped = Math.max(1, Math.min(limit, 500));
+        const pending = this.db.prepare(`SELECT id, claimed_by AS claimedBy FROM insights_outbox
+       WHERE tenant_id = ? AND user_id = ? AND uploaded_at IS NULL
+       ORDER BY created_at ASC LIMIT ?`).all(this.scope.tenantId, this.scope.userId, capped);
+        const dataDir = path.dirname(this.db.name);
+        const now = new Date().toISOString();
+        const claimed = [];
+        for (const row of pending) {
+            if (row.claimedBy && row.claimedBy !== me && instanceOwnerIsLive(dataDir, row.claimedBy)) {
+                continue;
+            }
+            const info = this.db.prepare(`UPDATE insights_outbox SET claimed_by = ?, claimed_at = ?
+         WHERE tenant_id = ? AND user_id = ? AND id = ? AND uploaded_at IS NULL
+           AND (claimed_by IS NULL OR claimed_by = ? OR claimed_by IS ?)`).run(me, now, this.scope.tenantId, this.scope.userId, row.id, me, row.claimedBy);
+            if (info.changes !== 1)
+                continue;
+            const stored = this.db.prepare(`SELECT * FROM insights_outbox WHERE tenant_id = ? AND user_id = ? AND id = ?`).get(this.scope.tenantId, this.scope.userId, row.id);
+            if (stored)
+                claimed.push(this.mapInsightOutbox(stored));
+        }
+        return claimed;
+    }
     async markInsightUploaded(id) {
         this.db.prepare(`UPDATE insights_outbox SET uploaded_at = ?, upload_error = NULL
        WHERE tenant_id = ? AND user_id = ? AND id = ?`).run(new Date().toISOString(), this.scope.tenantId, this.scope.userId, id);

package/dist/storage/process-locks.d.ts

@@ -0,0 +1,32 @@
+import { type HeldWriteLease } from './write-lease.js';
+export declare const HOST_SCHEMA_VERSION = 1;
+/** How long a starting host waits for another host to finish migrating. */
+export declare const OPEN_LOCK_WAIT_MS = 15000;
+export declare class ChatBusyError extends Error {
+    readonly chatId: string;
+    readonly code = "chat_busy";
+    constructor(chatId: string);
+}
+export declare class StorageUpgradeBlockedError extends Error {
+    constructor(message: string);
+}
+/** Records which instance owns rows created by this process. */
+export declare function bindStorageInstance(instanceId: string | null): void;
+export declare function currentStorageInstanceId(): string | null;
+export declare function chatLockPath(userDataDir: string, chatId: string): string;
+export declare function instanceLockPath(userDataDir: string, instanceId: string): string;
+export declare function fileLockPath(userDataDir: string, name: string): string;
+export declare function openLockPath(dbPath: string): string;
+/** Exclusive lock for one chat. Fails immediately when another process holds it. */
+export declare function acquireChatWriteLock(userDataDir: string, chatId: string): HeldWriteLease;
+export interface InstanceLease {
+    readonly instanceId: string;
+    release(): void;
+}
+/** Held until this host process exits. A dead process's lock can be taken. */
+export declare function acquireInstanceLease(userDataDir: string): InstanceLease;
+/**
+ * True when `instanceId` still holds its lease.
+ * A missing or unlocked file means the owner is dead.
+ */
+export declare function instanceOwnerIsLive(userDataDir: string, instanceId: string): boolean;

package/dist/storage/process-locks.js

@@ -0,0 +1,99 @@
+/**
+ * Per-chat and per-process locks for one user-data directory.
+ *
+ * The host database itself is shared (WAL). These locks are the units that
+ * stay exclusive: one running turn per chat, and one live owner per task.
+ */
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { acquireWriteLease, StoreAlreadyOwnedError, } from './write-lease.js';
+export const HOST_SCHEMA_VERSION = 1;
+/** How long a starting host waits for another host to finish migrating. */
+export const OPEN_LOCK_WAIT_MS = 15_000;
+export class ChatBusyError extends Error {
+    chatId;
+    code = 'chat_busy';
+    constructor(chatId) {
+        super(`chat busy: ${chatId}`);
+        this.chatId = chatId;
+        this.name = 'ChatBusyError';
+    }
+}
+export class StorageUpgradeBlockedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StorageUpgradeBlockedError';
+    }
+}
+let boundInstanceId = null;
+/** Records which instance owns rows created by this process. */
+export function bindStorageInstance(instanceId) {
+    boundInstanceId = instanceId;
+}
+export function currentStorageInstanceId() {
+    return boundInstanceId;
+}
+function assertLockId(id) {
+    if (id.length === 0 || id.length > 200 || /[\\/\0]/.test(id)) {
+        throw new Error(`invalid lock id: ${id}`);
+    }
+}
+export function chatLockPath(userDataDir, chatId) {
+    assertLockId(chatId);
+    return path.join(userDataDir, 'locks', 'chat', `${chatId}.lock`);
+}
+export function instanceLockPath(userDataDir, instanceId) {
+    assertLockId(instanceId);
+    return path.join(userDataDir, 'locks', 'instance', `${instanceId}.lock`);
+}
+export function fileLockPath(userDataDir, name) {
+    assertLockId(name);
+    return path.join(userDataDir, 'locks', 'file', `${name}.lock`);
+}
+export function openLockPath(dbPath) {
+    const parsed = path.parse(path.resolve(dbPath));
+    return path.join(parsed.dir, `${parsed.name}.open.lock`);
+}
+/** Exclusive lock for one chat. Fails immediately when another process holds it. */
+export function acquireChatWriteLock(userDataDir, chatId) {
+    try {
+        return acquireWriteLease(chatLockPath(userDataDir, chatId));
+    }
+    catch (error) {
+        if (error instanceof StoreAlreadyOwnedError)
+            throw new ChatBusyError(chatId);
+        throw error;
+    }
+}
+/** Held until this host process exits. A dead process's lock can be taken. */
+export function acquireInstanceLease(userDataDir) {
+    const instanceId = randomUUID();
+    const lease = acquireWriteLease(instanceLockPath(userDataDir, instanceId));
+    return {
+        instanceId,
+        release: () => lease.release(),
+    };
+}
+/**
+ * True when `instanceId` still holds its lease.
+ * A missing or unlocked file means the owner is dead.
+ */
+export function instanceOwnerIsLive(userDataDir, instanceId) {
+    let lockPath;
+    try {
+        lockPath = instanceLockPath(userDataDir, instanceId);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const probe = acquireWriteLease(lockPath);
+        probe.release();
+        return false;
+    }
+    catch (error) {
+        if (error instanceof StoreAlreadyOwnedError)
+            return true;
+        throw error;
+    }
+}

package/dist/storage/scoped-store.d.ts

@@ -96,6 +96,7 @@ export interface ScopedStore {
         kind?: InsightKind;
         limit?: number;
     }): Promise<InsightOutboxRow[]>;
+    claimInsightsForUpload(limit: number): Promise<InsightOutboxRow[]>;
     markInsightUploaded(id: string): Promise<void>;
     markInsightUploadError(id: string, error: string): Promise<void>;
     insightStats(): Promise<{

package/dist/storage/sqlite-driver.d.ts

@@ -3,13 +3,15 @@ import type { ScopedStore } from './scoped-store.js';
 /** Default local SQLite storage driver. */
 export declare class SqliteStorageDriver implements StorageDriver {
     private db;
-    private writeLease;
+    private openLease;
+    private changeTimer;
     private localSqliteStore;
     private readonly stores;
     initialize(): Promise<void>;
     scoped(scope: TenantScope): ScopedStore;
     packAccess(scope: TenantScope): PackDbAccess;
     applyPackMigrations(): Promise<void>;
+    watchChanges(onChange: () => void): void;
     close(): Promise<void>;
     private requireDb;
     private scopeKey;

package/dist/storage/sqlite-driver.js

@@ -1,11 +1,14 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
 import { getProductConfig } from '../product-config.js';
 import { getUserDataDir } from '../runtime.js';
 import { LOCAL_SCOPE } from './driver.js';
 import { SqliteScopedStore } from './index.js';
-import { acquireWriteLease, lockPathForDb, } from './write-lease.js';
+import { HOST_SCHEMA_VERSION, OPEN_LOCK_WAIT_MS, StorageUpgradeBlockedError, openLockPath, } from './process-locks.js';
+import { acquireSharedLease, acquireWriteLease, lockPathForDb, StoreAlreadyOwnedError, } from './write-lease.js';
 import { acquireWriteLeaseOrExit } from './write-lease-error.js';
+const MAIN_DB_BUSY_TIMEOUT_MS = 5_000;
 function invokeStatement(statement, operation, params) {
     if (Array.isArray(params))
         return statement[operation](...params);
@@ -71,32 +74,92 @@ class SqlitePackDbAccess {
         }
     }
 }
+function readUserVersion(dbPath) {
+    if (!existsSync(dbPath))
+        return 0;
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true, timeout: 5_000 });
+    try {
+        return Number(db.pragma('user_version', { simple: true }));
+    }
+    finally {
+        db.close();
+    }
+}
+function blockUpgrade(message) {
+    console.error(`[bs] storage upgrade blocked: ${message}`);
+    queueMicrotask(() => process.exit(75));
+    throw new StorageUpgradeBlockedError(message);
+}
 /** Default local SQLite storage driver. */
 export class SqliteStorageDriver {
     db = null;
-    writeLease = null;
+    openLease = null;
+    changeTimer = null;
     localSqliteStore = null;
     stores = new Map();
     async initialize() {
         if (this.db)
             return;
         const dbPath = path.join(getUserDataDir(), getProductConfig().dbFileName ?? 'agent-shell.db');
-        this.writeLease = acquireWriteLeaseOrExit(() => acquireWriteLease(lockPathForDb(dbPath)));
+        // A previous build held this lock for the whole process. If it is still
+        // held, that process cannot share the database, so refuse to migrate
+        // or to open alongside it.
+        acquireWriteLeaseOrExit(() => {
+            const legacy = acquireWriteLease(lockPathForDb(dbPath));
+            legacy.release();
+        });
+        const gate = openLockPath(dbPath);
+        let version = readUserVersion(dbPath);
+        if (version > HOST_SCHEMA_VERSION) {
+            blockUpgrade(`本地数据库版本 ${version} 高于本程序支持的版本 ${HOST_SCHEMA_VERSION}。请升级后再打开。`);
+        }
+        let exclusive = null;
+        if (version === HOST_SCHEMA_VERSION) {
+            // Make sure the open-lock table exists, then register as a shared holder.
+            // A live shared holder rejects this exclusive probe immediately.
+            try {
+                acquireWriteLease(gate).release();
+            }
+            catch (error) {
+                if (!(error instanceof StoreAlreadyOwnedError))
+                    throw error;
+            }
+        }
+        else {
+            try {
+                exclusive = acquireWriteLease(gate, OPEN_LOCK_WAIT_MS);
+            }
+            catch (error) {
+                if (!(error instanceof StoreAlreadyOwnedError))
+                    throw error;
+                version = readUserVersion(dbPath);
+                if (version !== HOST_SCHEMA_VERSION) {
+                    blockUpgrade('本地数据库需要升级，但仍被另一个进程打开。请先关闭正在运行的应用及其命令行任务后再升级。');
+                }
+            }
+        }
         let db = null;
         try {
-            db = new Database(dbPath);
+            db = new Database(dbPath, { timeout: MAIN_DB_BUSY_TIMEOUT_MS });
+            db.pragma(`busy_timeout = ${MAIN_DB_BUSY_TIMEOUT_MS}`);
             db.pragma('journal_mode = WAL');
             db.pragma('foreign_keys = ON');
             this.db = db;
             const local = new SqliteScopedStore(db, LOCAL_SCOPE);
             await local.initialize();
+            db.pragma(`user_version = ${HOST_SCHEMA_VERSION}`);
             this.localSqliteStore = local;
             this.stores.set(this.scopeKey(LOCAL_SCOPE), local);
+            exclusive?.release();
+            exclusive = null;
+            this.openLease = acquireSharedLease(gate);
         }
         catch (error) {
+            exclusive?.release();
             db?.close();
-            this.writeLease.release();
-            this.writeLease = null;
+            this.db = null;
+            this.openLease?.release();
+            this.openLease = null;
             throw error;
         }
     }
@@ -116,13 +179,31 @@ export class SqliteStorageDriver {
     async applyPackMigrations() {
         this.localSqliteStore?.applyPackMigrations();
     }
+    watchChanges(onChange) {
+        const db = this.requireDb();
+        if (this.changeTimer)
+            return;
+        let version = Number(db.pragma('data_version', { simple: true }));
+        this.changeTimer = setInterval(() => {
+            const next = Number(db.pragma('data_version', { simple: true }));
+            if (next === version)
+                return;
+            version = next;
+            onChange();
+        }, 1_000);
+        this.changeTimer.unref?.();
+    }
     async close() {
+        if (this.changeTimer) {
+            clearInterval(this.changeTimer);
+            this.changeTimer = null;
+        }
         this.stores.clear();
         this.db?.close();
         this.db = null;
         this.localSqliteStore = null;
-        this.writeLease?.release();
-        this.writeLease = null;
+        this.openLease?.release();
+        this.openLease = null;
     }
     requireDb() {
         if (!this.db)

package/dist/storage/write-lease.d.ts

@@ -23,4 +23,10 @@ export interface HeldWriteLease {
     release(): void;
 }
 export declare function lockPathForDb(dbPath: string): string;
-export declare function acquireWriteLease(lockPath: string): HeldWriteLease;
+export declare function acquireWriteLease(lockPath: string, timeoutMs?: number): HeldWriteLease;
+/**
+ * Shared open registration. Many processes may hold this at once.
+ * An exclusive lease on the same file waits until every shared holder closes.
+ * The lock file must already contain the lease table (the exclusive opener creates it).
+ */
+export declare function acquireSharedLease(lockPath: string): HeldWriteLease;

package/dist/storage/write-lease.js

@@ -36,17 +36,18 @@ export function lockPathForDb(dbPath) {
     const parsed = path.parse(path.resolve(dbPath));
     return path.join(parsed.dir, `${parsed.name}.lock`);
 }
-export function acquireWriteLease(lockPath) {
+export function acquireWriteLease(lockPath, timeoutMs = 0) {
+    const waitMs = Number.isFinite(timeoutMs) ? Math.max(0, Math.trunc(timeoutMs)) : 0;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     // Loaded lazily so tests that only exercise lockPathForDb do not need
     // better-sqlite3's Electron ABI.
     const Database = require('better-sqlite3');
-    const db = new Database(lockPath, { timeout: 0 });
+    const db = new Database(lockPath, { timeout: waitMs });
     try {
         // Every statement here can hit the incumbent's lock, including the
         // journal_mode pragma — it rewrites the header and so needs the same
-        // write lock. busy_timeout 0 makes that immediate instead of a stall.
-        db.pragma('busy_timeout = 0');
+        // write lock. timeoutMs 0 makes that immediate instead of a stall.
+        db.pragma(`busy_timeout = ${waitMs}`);
         db.pragma('journal_mode = DELETE');
         db.exec('CREATE TABLE IF NOT EXISTS lease (id INTEGER PRIMARY KEY)');
         db.exec('BEGIN EXCLUSIVE');
@@ -72,3 +73,33 @@ export function acquireWriteLease(lockPath) {
         },
     };
 }
+/**
+ * Shared open registration. Many processes may hold this at once.
+ * An exclusive lease on the same file waits until every shared holder closes.
+ * The lock file must already contain the lease table (the exclusive opener creates it).
+ */
+export function acquireSharedLease(lockPath) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const Database = require('better-sqlite3');
+    const db = new Database(lockPath, { timeout: 5_000 });
+    try {
+        db.pragma('busy_timeout = 5000');
+        db.exec('BEGIN');
+        db.prepare('SELECT id FROM lease LIMIT 1').get();
+    }
+    catch (err) {
+        db.close();
+        if (isSqliteBusy(err))
+            throw new StoreAlreadyOwnedError(lockPath);
+        throw err;
+    }
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            db.close();
+        },
+    };
+}