@nurix/nustack 0.10.0-dev.10

package/dist/lib/lanes/supervisor.js

@@ -0,0 +1,247 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { ClaudeLane } from "./claudeAdapter.js";
+import { FRAME_VERSION, parseInboundFrame, serializeFrame, } from "./frames.js";
+import { createLaneWorktree, lanesHome } from "./worktree.js";
+function defaultProbeClaude(env) {
+    return new Promise((resolve) => {
+        execFile("claude", ["--version"], { env, timeout: 5_000 }, (error, stdout) => {
+            if (error)
+                resolve({ found: false, version: null });
+            else
+                resolve({ found: true, version: stdout.trim() });
+        });
+    });
+}
+export class LaneSupervisor {
+    options;
+    env;
+    lanes = new Map();
+    closingLanes = new Set();
+    shuttingDown = false;
+    resolveDone = null;
+    lines = null;
+    registryWrites = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+    }
+    emit(frame) {
+        this.options.output.write(serializeFrame(frame));
+    }
+    status(laneId, status, message = null) {
+        this.emit({ v: FRAME_VERSION, type: "lane.status", laneId, status, message });
+    }
+    error(laneId, code, message) {
+        this.emit({ v: FRAME_VERSION, type: "lane.error", laneId, code, message });
+    }
+    registryPath() {
+        return path.join(lanesHome(this.env), "registry.json");
+    }
+    async boundWorkspaceOf(projectPath) {
+        try {
+            const parsed = JSON.parse(await readFile(path.join(projectPath, ".nustack", "workspace.json"), "utf8"));
+            const id = parsed?.workspaceId;
+            return typeof id === "string" && id.trim() ? id.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async moveLaneSession(record, to) {
+        const client = this.options.sessions;
+        if (!client || !record.workspaceId)
+            return;
+        try {
+            await client.transitionSession(record.workspaceId, record.laneId, to);
+        }
+        catch {
+        }
+    }
+    async updateRegistry(mutate) {
+        const run = async () => {
+            const file = this.registryPath();
+            let lanes = [];
+            try {
+                const parsed = JSON.parse(await readFile(file, "utf8"));
+                if (typeof parsed === "object" && parsed !== null && Array.isArray(parsed.lanes)) {
+                    lanes = parsed.lanes;
+                }
+            }
+            catch {
+            }
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, JSON.stringify({ v: 1, lanes: mutate(lanes) }, null, 2) + "\n", "utf8");
+        };
+        this.registryWrites = this.registryWrites.then(run, run);
+        return this.registryWrites;
+    }
+    async run() {
+        const probe = this.options.probeClaude ?? (() => defaultProbeClaude(this.env));
+        const claude = await probe();
+        this.emit({ v: FRAME_VERSION, type: "engine.hello", engineVersion: this.options.engineVersion, claude });
+        const lines = createInterface({ input: this.options.input });
+        this.lines = lines;
+        lines.on("line", (line) => {
+            if (line.trim() === "")
+                return;
+            const parsed = parseInboundFrame(line);
+            if (!parsed.ok) {
+                this.error(null, parsed.error.code, parsed.error.message);
+                return;
+            }
+            void this.handle(parsed.frame);
+        });
+        await new Promise((resolve) => {
+            this.resolveDone = resolve;
+            lines.on("close", () => void this.shutdown());
+        });
+    }
+    async handle(frame) {
+        switch (frame.type) {
+            case "engine.shutdown":
+                await this.shutdown();
+                return;
+            case "lane.open":
+                await this.openLane(frame.laneId, frame.projectPath, frame.permissionMode, frame.isolated, frame.resumeSessionId);
+                return;
+            case "lane.turn": {
+                const lane = this.lanes.get(frame.laneId);
+                if (!lane)
+                    return this.error(frame.laneId, "LANE_UNKNOWN", `no open lane ${frame.laneId}`);
+                lane.adapter.sendTurn(frame.text);
+                this.status(frame.laneId, "running");
+                return;
+            }
+            case "lane.approval": {
+                const lane = this.lanes.get(frame.laneId);
+                if (!lane)
+                    return this.error(frame.laneId, "LANE_UNKNOWN", `no open lane ${frame.laneId}`);
+                lane.adapter.respondApproval(frame.requestId, frame.verdict);
+                return;
+            }
+            case "lane.interrupt": {
+                const lane = this.lanes.get(frame.laneId);
+                if (!lane)
+                    return this.error(frame.laneId, "LANE_UNKNOWN", `no open lane ${frame.laneId}`);
+                lane.adapter.interrupt();
+                return;
+            }
+            case "lane.close": {
+                const lane = this.lanes.get(frame.laneId);
+                if (!lane)
+                    return this.error(frame.laneId, "LANE_UNKNOWN", `no open lane ${frame.laneId}`);
+                this.closingLanes.add(frame.laneId);
+                lane.adapter.stop();
+                return;
+            }
+        }
+    }
+    async openLane(laneId, projectPath, permissionMode, isolated, resumeSessionId) {
+        if (this.lanes.has(laneId))
+            return this.error(laneId, "LANE_ALREADY_OPEN", `lane ${laneId} is already open`);
+        this.status(laneId, "starting");
+        const worktree = await createLaneWorktree(projectPath, laneId, this.env, isolated === true);
+        const record = {
+            laneId,
+            projectPath,
+            worktreePath: worktree.worktreePath,
+            branch: worktree.branch,
+            provider: "claude-code",
+            providerSessionId: null,
+            createdAt: new Date().toISOString(),
+            status: "open",
+            workspaceId: await this.boundWorkspaceOf(projectPath),
+        };
+        const adapterOptions = {
+            cwd: worktree.worktreePath,
+            permissionMode,
+            resumeSessionId,
+            env: this.env,
+            onEvent: (event) => {
+                this.emit({ v: FRAME_VERSION, type: "lane.event", laneId, event });
+                if (typeof event === "object" && event !== null && event.type === "result") {
+                    this.status(laneId, "ready");
+                }
+            },
+            onApprovalRequest: (request) => {
+                this.emit({
+                    v: FRAME_VERSION,
+                    type: "lane.approvalRequest",
+                    laneId,
+                    requestId: request.requestId,
+                    toolName: request.toolName,
+                    displayName: request.displayName,
+                    toolInput: request.toolInput,
+                    description: request.description,
+                });
+            },
+            onProtocolError: (code, message) => this.error(laneId, code, message),
+            onSessionId: (sessionId) => {
+                record.providerSessionId = sessionId;
+                void this.updateRegistry((lanes) => lanes.map((row) => (row.laneId === laneId ? { ...row, providerSessionId: sessionId } : row)));
+                const client = this.options.sessions;
+                if (client && record.workspaceId) {
+                    void client.setVendorSessionId(record.workspaceId, laneId, sessionId).catch(() => undefined);
+                }
+            },
+            onExit: (code) => {
+                const wasExpected = this.closingLanes.delete(laneId) || this.shuttingDown;
+                this.lanes.delete(laneId);
+                if (!wasExpected)
+                    this.error(laneId, "ADAPTER_FAILED", `claude exited unexpectedly (code ${String(code)})`);
+                this.emit({ v: FRAME_VERSION, type: "lane.closed", laneId });
+                void this.updateRegistry((lanes) => lanes.map((row) => (row.laneId === laneId ? { ...row, status: "closed" } : row)));
+                void this.moveLaneSession(record, wasExpected ? "done" : "failed");
+            },
+        };
+        const create = this.options.createAdapter ?? ((opts) => new ClaudeLane(opts));
+        let adapter;
+        try {
+            adapter = create(adapterOptions);
+        }
+        catch (error) {
+            return this.error(laneId, "ADAPTER_FAILED", error instanceof Error ? error.message : String(error));
+        }
+        this.lanes.set(laneId, { adapter, record });
+        await this.updateRegistry((lanes) => [...lanes.filter((row) => row.laneId !== laneId), record]);
+        if (this.options.sessions && record.workspaceId) {
+            try {
+                await this.options.sessions.createSession(record.workspaceId, {
+                    id: laneId,
+                    startedBy: "person",
+                    substrate: "device",
+                    mode: "synchronous",
+                    origin: "inside",
+                    vendor: "claude_code",
+                    renderer: "claude_transcript",
+                    status: "created",
+                });
+            }
+            catch {
+            }
+        }
+        this.emit({
+            v: FRAME_VERSION,
+            type: "lane.opened",
+            laneId,
+            projectPath,
+            worktreePath: worktree.worktreePath,
+            branch: worktree.branch,
+            isolated: worktree.isolated,
+        });
+        this.status(laneId, "ready");
+    }
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        for (const [, lane] of this.lanes)
+            lane.adapter.stop();
+        this.lanes.clear();
+        this.lines?.close();
+        this.resolveDone?.();
+    }
+}

package/dist/lib/lanes/worktree.js

@@ -0,0 +1,33 @@
+import { execFile } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const LANE_BRANCH_PREFIX = "nustack/lane-";
+export function lanesHome(env = process.env) {
+    const override = env.NUSTACK_LANES_HOME;
+    if (override && override !== "")
+        return override;
+    return path.join(os.homedir(), ".nustack", "lanes");
+}
+function git(args, cwd) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd, timeout: 15_000 }, (error, stdout) => {
+            resolve(error ? null : stdout.trim());
+        });
+    });
+}
+export async function createLaneWorktree(projectPath, laneId, env = process.env, isolate = false) {
+    const inPlace = { worktreePath: projectPath, branch: null, isolated: false };
+    if (!isolate)
+        return inPlace;
+    const isRepo = await git(["rev-parse", "--is-inside-work-tree"], projectPath);
+    if (isRepo !== "true")
+        return inPlace;
+    const branch = `${LANE_BRANCH_PREFIX}${laneId}`;
+    const worktreePath = path.join(lanesHome(env), "worktrees", laneId);
+    await mkdir(path.dirname(worktreePath), { recursive: true });
+    const added = await git(["worktree", "add", worktreePath, "-b", branch], projectPath);
+    if (added === null)
+        return inPlace;
+    return { worktreePath, branch, isolated: true };
+}

package/dist/lib/local_store/accepted_uploads.js

@@ -0,0 +1,49 @@
+function mapRow(row) {
+    return {
+        bindingId: row.binding_id,
+        commitId: row.commit_id,
+        handoffId: row.handoff_id,
+        workspaceSequence: row.workspace_sequence,
+        manifestSha256: row.manifest_sha256,
+        createdAtMs: row.created_at_ms,
+    };
+}
+export function recordAcceptedUpload(store, input) {
+    store.db
+        .prepare(`INSERT INTO local_accepted_uploads (
+                binding_id, commit_id, handoff_id, workspace_sequence, manifest_sha256, created_at_ms
+            ) VALUES (
+                :binding_id, :commit_id, :handoff_id, :workspace_sequence, :manifest_sha256, :created_at_ms
+            )
+            ON CONFLICT(binding_id, commit_id) DO NOTHING`)
+        .run({
+        binding_id: input.bindingId,
+        commit_id: input.commitId,
+        handoff_id: input.handoffId,
+        workspace_sequence: input.workspaceSequence,
+        manifest_sha256: input.manifestSha256,
+        created_at_ms: Date.now(),
+    });
+    return getAcceptedUpload(store, input.bindingId, input.commitId);
+}
+export function getAcceptedUpload(store, bindingId, commitId) {
+    const row = store.db
+        .prepare("SELECT * FROM local_accepted_uploads WHERE binding_id = :binding_id AND commit_id = :commit_id")
+        .get({ binding_id: bindingId, commit_id: commitId });
+    return row ? mapRow(row) : null;
+}
+export function getAcceptedUploadByHandoff(store, handoffId) {
+    const row = store.db
+        .prepare("SELECT * FROM local_accepted_uploads WHERE handoff_id = :handoff_id LIMIT 1")
+        .get({ handoff_id: handoffId });
+    return row ? mapRow(row) : null;
+}
+export function latestAcceptedUpload(store, bindingId) {
+    const row = store.db
+        .prepare(`SELECT * FROM local_accepted_uploads
+             WHERE binding_id = :binding_id
+             ORDER BY workspace_sequence DESC, created_at_ms DESC
+             LIMIT 1`)
+        .get({ binding_id: bindingId });
+    return row ? mapRow(row) : null;
+}

package/dist/lib/local_store/bindings.js

@@ -0,0 +1,163 @@
+import { withTransaction } from "./database.js";
+import { LIVE_BINDING_STATUSES } from "./sync_vocabulary.js";
+function mapRow(row) {
+    return {
+        id: row.id,
+        workspaceId: row.workspace_id,
+        organizationId: row.organization_id,
+        repositoryRoot: row.repository_root,
+        gitDir: row.git_dir,
+        gitCommonDir: row.git_common_dir,
+        repositoryFingerprint: row.repository_fingerprint,
+        boundBranch: row.bound_branch,
+        lastProcessedCommitId: row.last_processed_commit_id ?? null,
+        lastAppliedWorkspaceSequence: row.last_applied_workspace_sequence,
+        whitelistManifestId: row.whitelist_manifest_id ?? null,
+        whitelistManifestSha256: row.whitelist_manifest_sha256 ?? null,
+        whitelistCachePath: row.whitelist_cache_path ?? null,
+        etnaProfileJson: row.etna_profile_json ?? null,
+        status: row.status,
+        lastErrorCode: row.last_error_code ?? null,
+        lastErrorDetail: row.last_error_detail ?? null,
+        telemetryEnabled: row.telemetry_enabled !== 0,
+        createdAtMs: row.created_at_ms,
+        updatedAtMs: row.updated_at_ms,
+    };
+}
+export function insertBinding(store, input) {
+    const now = Date.now();
+    store.db
+        .prepare(`INSERT INTO local_bindings (
+                id, workspace_id, organization_id, repository_root, git_dir, git_common_dir,
+                repository_fingerprint, bound_branch, last_processed_commit_id,
+                last_applied_workspace_sequence, whitelist_manifest_id, whitelist_manifest_sha256,
+                whitelist_cache_path, etna_profile_json, status, last_error_code,
+                last_error_detail, created_at_ms, updated_at_ms
+            ) VALUES (
+                :id, :workspace_id, :organization_id, :repository_root, :git_dir, :git_common_dir,
+                :repository_fingerprint, :bound_branch, :last_processed_commit_id,
+                :last_applied_workspace_sequence, :whitelist_manifest_id, :whitelist_manifest_sha256,
+                :whitelist_cache_path, :etna_profile_json, :status, NULL,
+                NULL, :created_at_ms, :updated_at_ms
+            )`)
+        .run({
+        id: input.id,
+        workspace_id: input.workspaceId,
+        organization_id: input.organizationId,
+        repository_root: input.repositoryRoot,
+        git_dir: input.gitDir,
+        git_common_dir: input.gitCommonDir,
+        repository_fingerprint: input.repositoryFingerprint,
+        bound_branch: input.boundBranch,
+        last_processed_commit_id: input.lastProcessedCommitId ?? null,
+        last_applied_workspace_sequence: input.lastAppliedWorkspaceSequence ?? 0,
+        whitelist_manifest_id: input.whitelistManifestId ?? null,
+        whitelist_manifest_sha256: input.whitelistManifestSha256 ?? null,
+        whitelist_cache_path: input.whitelistCachePath ?? null,
+        etna_profile_json: input.etnaProfileJson ?? null,
+        status: input.status ?? "creating",
+        created_at_ms: now,
+        updated_at_ms: now,
+    });
+    return getBindingById(store, input.id);
+}
+export function getBindingById(store, bindingId) {
+    const row = store.db.prepare("SELECT * FROM local_bindings WHERE id = :id").get({
+        id: bindingId,
+    });
+    return row ? mapRow(row) : null;
+}
+export function getBindingByRepositoryRoot(store, repositoryRoot) {
+    const row = store.db
+        .prepare(`SELECT * FROM local_bindings
+             WHERE repository_root = :root
+               AND status IN ('creating','active','paused')`)
+        .get({ root: repositoryRoot });
+    return row ? mapRow(row) : null;
+}
+export function listBindings(store, statusFilter) {
+    if (statusFilter === undefined) {
+        const rows = store.db
+            .prepare("SELECT * FROM local_bindings ORDER BY created_at_ms ASC")
+            .all();
+        return rows.map(mapRow);
+    }
+    const statuses = Array.isArray(statusFilter) ? statusFilter : [statusFilter];
+    const placeholders = statuses.map((_, i) => `:s${i}`).join(", ");
+    const params = Object.fromEntries(statuses.map((s, i) => [`s${i}`, s]));
+    const rows = store.db
+        .prepare(`SELECT * FROM local_bindings WHERE status IN (${placeholders}) ORDER BY created_at_ms ASC`)
+        .all(params);
+    return rows.map(mapRow);
+}
+export function listActiveBindings(store) {
+    return listBindings(store, LIVE_BINDING_STATUSES);
+}
+export function updateBindingCursor(store, bindingId, patch) {
+    return withTransaction(store, () => {
+        const now = Date.now();
+        if (Object.prototype.hasOwnProperty.call(patch, "lastProcessedCommitId")) {
+            store.db
+                .prepare(`UPDATE local_bindings
+                     SET last_processed_commit_id = :commit, updated_at_ms = :now
+                     WHERE id = :id`)
+                .run({ commit: patch.lastProcessedCommitId ?? null, now, id: bindingId });
+        }
+        if (patch.lastAppliedWorkspaceSequence !== undefined) {
+            store.db
+                .prepare(`UPDATE local_bindings
+                     SET last_applied_workspace_sequence = :seq, updated_at_ms = :now
+                     WHERE id = :id`)
+                .run({ seq: patch.lastAppliedWorkspaceSequence, now, id: bindingId });
+        }
+        return getBindingById(store, bindingId);
+    });
+}
+export function updateBindingStatus(store, bindingId, status, error) {
+    store.db
+        .prepare(`UPDATE local_bindings
+             SET status = :status, last_error_code = :code, last_error_detail = :detail,
+                 updated_at_ms = :now
+             WHERE id = :id`)
+        .run({
+        status,
+        code: error?.code ?? null,
+        detail: error?.detail ?? null,
+        now: Date.now(),
+        id: bindingId,
+    });
+    return getBindingById(store, bindingId);
+}
+export function setBindingTelemetry(store, bindingId, enabled) {
+    store.db
+        .prepare(`UPDATE local_bindings
+             SET telemetry_enabled = :enabled, updated_at_ms = :now
+             WHERE id = :id`)
+        .run({ enabled: enabled ? 1 : 0, now: Date.now(), id: bindingId });
+    return getBindingById(store, bindingId);
+}
+export function updateBindingEtnaProfile(store, bindingId, etnaProfileJson) {
+    store.db
+        .prepare(`UPDATE local_bindings
+             SET etna_profile_json = :profile, updated_at_ms = :now
+             WHERE id = :id`)
+        .run({ profile: etnaProfileJson, now: Date.now(), id: bindingId });
+    return getBindingById(store, bindingId);
+}
+export function updateBindingWhitelistCache(store, bindingId, patch) {
+    store.db
+        .prepare(`UPDATE local_bindings
+             SET whitelist_manifest_id = :manifestId,
+                 whitelist_manifest_sha256 = :manifestSha,
+                 whitelist_cache_path = :cachePath,
+                 updated_at_ms = :now
+             WHERE id = :id`)
+        .run({
+        manifestId: patch.whitelistManifestId ?? null,
+        manifestSha: patch.whitelistManifestSha256 ?? null,
+        cachePath: patch.whitelistCachePath ?? null,
+        now: Date.now(),
+        id: bindingId,
+    });
+    return getBindingById(store, bindingId);
+}

package/dist/lib/local_store/commit_origins.js

@@ -0,0 +1,25 @@
+export function recordInboundCommit(store, input) {
+    store.db
+        .prepare(`INSERT INTO local_commit_origins (binding_id, commit_id, handoff_id, origin, created_at_ms)
+             VALUES (:binding_id, :commit_id, :handoff_id, 'cloud_handoff', :created_at_ms)
+             ON CONFLICT(binding_id, commit_id) DO NOTHING`)
+        .run({
+        binding_id: input.bindingId,
+        commit_id: input.commitId,
+        handoff_id: input.handoffId,
+        created_at_ms: Date.now(),
+    });
+}
+export function isCloudOriginCommit(store, bindingId, commitId) {
+    const row = store.db
+        .prepare(`SELECT 1 AS present FROM local_commit_origins
+             WHERE binding_id = :binding_id AND commit_id = :commit_id`)
+        .get({ binding_id: bindingId, commit_id: commitId });
+    return row !== undefined;
+}
+export function hasCloudOriginForHandoff(store, handoffId) {
+    const row = store.db
+        .prepare(`SELECT 1 AS present FROM local_commit_origins WHERE handoff_id = :handoff_id`)
+        .get({ handoff_id: handoffId });
+    return row !== undefined;
+}

package/dist/lib/local_store/database.js

@@ -0,0 +1,71 @@
+import { chmod } from "node:fs/promises";
+import path from "node:path";
+import { mkdirSecure } from "../secure_file.js";
+import { stateDbPath } from "./paths.js";
+import { migrateToLatest } from "./migrations.js";
+let sqliteModulePromise;
+async function loadSqlite() {
+    if (!sqliteModulePromise) {
+        sqliteModulePromise = importSqliteQuietly();
+    }
+    return sqliteModulePromise;
+}
+async function importSqliteQuietly() {
+    return withSuppressedSqliteWarning(() => import("node:sqlite"));
+}
+async function withSuppressedSqliteWarning(fn) {
+    const original = process.emitWarning;
+    const filtered = (warning, ...args) => {
+        const name = warning instanceof Error
+            ? warning.name
+            : typeof args[0] === "string"
+                ? args[0]
+                : args[0]?.type;
+        const message = warning instanceof Error ? warning.message : String(warning);
+        if (name === "ExperimentalWarning" && /sqlite/i.test(message))
+            return;
+        original(warning, ...args);
+    };
+    process.emitWarning = filtered;
+    try {
+        return await fn();
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
+export async function openLocalStore(options = {}) {
+    const dbFile = options.dbPath ?? stateDbPath();
+    await mkdirSecure(path.dirname(dbFile));
+    const db = await withSuppressedSqliteWarning(async () => {
+        const { DatabaseSync } = await loadSqlite();
+        return new DatabaseSync(dbFile);
+    });
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA foreign_keys = ON");
+    migrateToLatest(db);
+    await chmod(dbFile, 0o600).catch(() => { });
+    return {
+        db,
+        close() {
+            db.close();
+        },
+    };
+}
+export function withTransaction(store, fn) {
+    const { db } = store;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const result = fn(db);
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function bindNullable(value) {
+    return value ?? null;
+}

package/dist/lib/local_store/device_state.js

@@ -0,0 +1,72 @@
+import { LATEST_SCHEMA_VERSION } from "./migrations.js";
+import { withTransaction } from "./database.js";
+function mapRow(row) {
+    return {
+        deviceRef: row.device_ref ?? null,
+        apiBaseUrl: row.api_base_url ?? null,
+        activeUserId: row.active_user_id ?? null,
+        activeUserEmail: row.active_user_email ?? null,
+        activeOrganizationId: row.active_organization_id ?? null,
+        keychainService: row.keychain_service ?? null,
+        keychainAccount: row.keychain_account ?? null,
+        schemaVersion: row.schema_version,
+        lastAuthRefreshAtMs: row.last_auth_refresh_at_ms ?? null,
+        createdAtMs: row.created_at_ms,
+        updatedAtMs: row.updated_at_ms,
+    };
+}
+export function readDeviceState(store) {
+    const row = store.db.prepare("SELECT * FROM local_device_state WHERE id = 1").get();
+    return row ? mapRow(row) : null;
+}
+export function upsertDeviceState(store, patch) {
+    return withTransaction(store, (db) => {
+        const now = Date.now();
+        const current = readDeviceState(store);
+        const pick = (key, fallback) => Object.prototype.hasOwnProperty.call(patch, key) ? (patch[key] ?? null) : fallback;
+        const merged = {
+            deviceRef: pick("deviceRef", current?.deviceRef ?? null),
+            apiBaseUrl: pick("apiBaseUrl", current?.apiBaseUrl ?? null),
+            activeUserId: pick("activeUserId", current?.activeUserId ?? null),
+            activeUserEmail: pick("activeUserEmail", current?.activeUserEmail ?? null),
+            activeOrganizationId: pick("activeOrganizationId", current?.activeOrganizationId ?? null),
+            keychainService: pick("keychainService", current?.keychainService ?? null),
+            keychainAccount: pick("keychainAccount", current?.keychainAccount ?? null),
+            lastAuthRefreshAtMs: pick("lastAuthRefreshAtMs", current?.lastAuthRefreshAtMs ?? null),
+            createdAtMs: current?.createdAtMs ?? now,
+        };
+        db.prepare(`INSERT INTO local_device_state (
+                id, device_ref, api_base_url, active_user_id, active_user_email,
+                active_organization_id, keychain_service, keychain_account, schema_version,
+                last_auth_refresh_at_ms, created_at_ms, updated_at_ms
+            ) VALUES (
+                1, :device_ref, :api_base_url, :active_user_id, :active_user_email,
+                :active_organization_id, :keychain_service, :keychain_account, :schema_version,
+                :last_auth_refresh_at_ms, :created_at_ms, :updated_at_ms
+            )
+            ON CONFLICT(id) DO UPDATE SET
+                device_ref = excluded.device_ref,
+                api_base_url = excluded.api_base_url,
+                active_user_id = excluded.active_user_id,
+                active_user_email = excluded.active_user_email,
+                active_organization_id = excluded.active_organization_id,
+                keychain_service = excluded.keychain_service,
+                keychain_account = excluded.keychain_account,
+                schema_version = excluded.schema_version,
+                last_auth_refresh_at_ms = excluded.last_auth_refresh_at_ms,
+                updated_at_ms = excluded.updated_at_ms`).run({
+            device_ref: merged.deviceRef,
+            api_base_url: merged.apiBaseUrl,
+            active_user_id: merged.activeUserId,
+            active_user_email: merged.activeUserEmail,
+            active_organization_id: merged.activeOrganizationId,
+            keychain_service: merged.keychainService,
+            keychain_account: merged.keychainAccount,
+            schema_version: LATEST_SCHEMA_VERSION,
+            last_auth_refresh_at_ms: merged.lastAuthRefreshAtMs,
+            created_at_ms: merged.createdAtMs,
+            updated_at_ms: now,
+        });
+        return readDeviceState(store);
+    });
+}