noteconnection 1.7.0 → 1.9.0

package/dist/src/server.port.fallback.contract.test.js

@@ -140,6 +140,46 @@ function loadStartServer() {
     const serverModule = require('./server');
     return serverModule.startServer;
 }
+function loadStartServerWithPathBridgeFallbackProbe() {
+    jest.resetModules();
+    jest.doMock('./index', () => ({
+        buildGraph: jest.fn().mockResolvedValue(undefined)
+    }));
+    jest.doMock('./core/PathBridge', () => {
+        class MockPathBridge {
+            constructor(options) {
+                const requestedPort = Number(options?.port || 9876);
+                if (requestedPort === 48765) {
+                    const error = new Error('permission denied');
+                    error.code = 'EACCES';
+                    throw error;
+                }
+                this.port = requestedPort;
+            }
+            getPort() {
+                return this.port;
+            }
+            getStatus() {
+                return { port: this.port };
+            }
+        }
+        return { PathBridge: MockPathBridge };
+    });
+    jest.doMock('./reader_renderer', () => ({
+        renderMathPng: jest.fn().mockResolvedValue({
+            pngBase64: 'math',
+            width: 1,
+            height: 1
+        }),
+        renderMermaidPng: jest.fn().mockResolvedValue({
+            pngBase64: 'mermaid',
+            width: 1,
+            height: 1
+        })
+    }));
+    const serverModule = require('./server');
+    return serverModule.startServer;
+}
 describe('server ephemeral port fallback policy contract', () => {
     let tempProject = null;
     let envRestorers = [];
@@ -163,6 +203,8 @@ describe('server ephemeral port fallback policy contract', () => {
             setEnv('NOTE_CONNECTION_KB_ROOT', kbRoot),
             setEnv('NOTE_CONNECTION_AUTH_TOKEN', undefined),
             setEnv('NOTE_CONNECTION_PORT', undefined),
+            setEnv('NOTE_CONNECTION_BRIDGE_PORT', undefined),
+            setEnv('NOTE_CONNECTION_ALLOW_EPHEMERAL_BRIDGE_PORT_FALLBACK', undefined),
             setEnv('PORT', undefined)
         ];
         originalArgv = [...process.argv];
@@ -219,4 +261,25 @@ describe('server ephemeral port fallback policy contract', () => {
             await closeServer(blocker);
         }
     });
+    test('falls back from an unavailable PathBridge port and publishes the effective bridge port', async () => {
+        if (!tempProject) {
+            throw new Error('missing temp project');
+        }
+        const projectRoot = path.join(tempProject.root, 'project');
+        const manifestPath = path.join(projectRoot, 'tmp', 'active-sidecar-runtime.json');
+        envRestorers.push(setEnv('NOTE_CONNECTION_BRIDGE_PORT', '48765'));
+        envRestorers.push(setEnv('NOTE_CONNECTION_ALLOW_EPHEMERAL_BRIDGE_PORT_FALLBACK', '1'));
+        const startServer = loadStartServerWithPathBridgeFallbackProbe();
+        let appServer = null;
+        try {
+            appServer = await startServer({ port: 0 });
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            expect(manifest.bridgePort).not.toBe(48765);
+            expect(manifest.bridgePort).toBeGreaterThan(0);
+            expect(manifest.bridgeWsUrl).toBe(`ws://127.0.0.1:${manifest.bridgePort}`);
+        }
+        finally {
+            await closeServer(appServer);
+        }
+    });
 });

package/dist/src/session/SessionStateStore.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStateStore = void 0;
+class SessionStateStore {
+    constructor(nextId) {
+        this.nextId = nextId;
+        this.sessionStates = new Map();
+    }
+    upsert(record) {
+        const existing = this.sessionStates.get(record.sessionId);
+        const nextRecord = {
+            sessionStateId: existing?.sessionStateId || this.nextId('session_state'),
+            sessionId: record.sessionId,
+            userId: record.userId,
+            workspaceId: record.workspaceId || null,
+            corpusId: record.corpusId || null,
+            mode: record.mode,
+            activeResourceIds: Array.from(new Set(record.activeResourceIds)).filter(Boolean),
+            activeProjectionIds: Array.from(new Set(record.activeProjectionIds)).filter(Boolean),
+            retrievalSettings: { ...record.retrievalSettings },
+            memorySettings: { ...record.memorySettings },
+            exportProfileId: record.exportProfileId || null,
+            panelState: { ...(record.panelState || {}) },
+            createdAt: existing?.createdAt || record.recordedAt,
+            updatedAt: record.recordedAt,
+        };
+        this.sessionStates.set(record.sessionId, nextRecord);
+        return nextRecord;
+    }
+    get(sessionId) {
+        return this.sessionStates.get(String(sessionId || '').trim()) || null;
+    }
+    listByWorkspace(workspaceId, userId) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim().toLowerCase();
+        const normalizedUserId = String(userId || '').trim();
+        if (!normalizedWorkspaceId) {
+            return [];
+        }
+        return Array.from(this.sessionStates.values())
+            .filter((state) => state.workspaceId === normalizedWorkspaceId)
+            .filter((state) => !normalizedUserId || state.userId === normalizedUserId)
+            .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+    }
+    listBySessionIds(sessionIds) {
+        const allowedIds = new Set(sessionIds
+            .map((sessionId) => String(sessionId || '').trim())
+            .filter(Boolean));
+        if (allowedIds.size <= 0) {
+            return [];
+        }
+        return Array.from(this.sessionStates.values())
+            .filter((state) => allowedIds.has(state.sessionId))
+            .sort((left, right) => left.sessionId.localeCompare(right.sessionId));
+    }
+    buildSnapshot() {
+        return {
+            sessionStates: Array.from(this.sessionStates.values()).map((state) => ({
+                ...state,
+                activeResourceIds: [...state.activeResourceIds],
+                activeProjectionIds: [...state.activeProjectionIds],
+                retrievalSettings: { ...state.retrievalSettings },
+                memorySettings: { ...state.memorySettings },
+                panelState: { ...state.panelState },
+            })),
+        };
+    }
+    restoreFromSnapshot(snapshot) {
+        this.sessionStates.clear();
+        (snapshot?.sessionStates || []).forEach((state) => {
+            this.sessionStates.set(state.sessionId, {
+                ...state,
+                activeResourceIds: [...state.activeResourceIds],
+                activeProjectionIds: [...state.activeProjectionIds],
+                retrievalSettings: { ...state.retrievalSettings },
+                memorySettings: { ...state.memorySettings },
+                panelState: { ...state.panelState },
+            });
+        });
+    }
+}
+exports.SessionStateStore = SessionStateStore;

package/dist/src/session/SessionStateStore.test.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SessionStateStore_1 = require("./SessionStateStore");
+describe('SessionStateStore', () => {
+    test('upserts session state and lists by workspace', () => {
+        let idCounter = 0;
+        const store = new SessionStateStore_1.SessionStateStore((prefix = 'session_state') => `${prefix}_${++idCounter}`);
+        const first = store.upsert({
+            sessionId: 'session_a',
+            userId: 'user_a',
+            workspaceId: 'optics',
+            corpusId: 'optics',
+            mode: 'grounded_conversation',
+            activeResourceIds: ['resource_1'],
+            activeProjectionIds: ['projection_1'],
+            retrievalSettings: {
+                topK: 6,
+                queryBackend: 'local_hybrid',
+                persistMemory: true,
+            },
+            memorySettings: {
+                namespace: 'conversation',
+                enabled: true,
+            },
+            exportProfileId: 'desktop-full',
+            panelState: {
+                lastGroundedAnswerAt: '2026-05-26T00:00:00.000Z',
+            },
+            recordedAt: '2026-05-26T00:00:00.000Z',
+        });
+        const second = store.upsert({
+            sessionId: 'session_a',
+            userId: 'user_a',
+            workspaceId: 'optics',
+            corpusId: 'optics',
+            mode: 'study_session',
+            activeResourceIds: ['resource_1', 'resource_2'],
+            activeProjectionIds: ['projection_1', 'projection_2'],
+            retrievalSettings: {
+                topK: 0,
+                queryBackend: null,
+                persistMemory: true,
+            },
+            memorySettings: {
+                namespace: null,
+                enabled: true,
+            },
+            exportProfileId: 'mobile-slim',
+            panelState: {
+                lastExecutionAt: '2026-05-26T00:05:00.000Z',
+            },
+            recordedAt: '2026-05-26T00:05:00.000Z',
+        });
+        expect(second.sessionStateId).toBe(first.sessionStateId);
+        expect(store.listByWorkspace('optics')).toHaveLength(1);
+        expect(store.listBySessionIds(['session_a'])[0]?.mode).toBe('study_session');
+    });
+});

package/dist/src/session/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/settings.runtime.contract.test.js

@@ -0,0 +1,50 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+describe('frontend settings runtime sync guard', () => {
+    const repoRoot = path.resolve(__dirname, '..');
+    const settingsPath = path.join(repoRoot, 'src', 'frontend', 'settings.js');
+    test('disables runtime hydration and persistence when the page is only a detached frontend preview', () => {
+        const source = fs.readFileSync(settingsPath, 'utf8');
+        expect(source).toContain('function shouldEnableRuntimeSync()');
+        expect(source).toContain('this.runtimeSyncEnabled = shouldEnableRuntimeSync();');
+        expect(source).toContain('if (!this.runtimeSyncEnabled) {');
+        expect(source).toContain('this.isHydrationComplete = true;');
+        expect(source).toContain('if (!this.runtimeSyncEnabled) {');
+        expect(source).toContain('return /^https?:\\/\\/(?:127\\.0\\.0\\.1|localhost):3000$/.test(origin);');
+    });
+});

package/dist/src/shared/types.contract.test.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Shared types contract test — validates shared type module integrity.
+ */
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+describe('shared types module', () => {
+    const sharedDir = path.resolve(__dirname);
+    const typesFile = path.join(sharedDir, 'types.ts');
+    test('shared types file exists on disk', () => {
+        expect(fs.existsSync(typesFile)).toBe(true);
+    });
+    test('shared types file is under 350 lines (contract boundary discipline, v2.9 expanded for CI contracts)', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        const lines = source.split('\n').length;
+        expect(lines).toBeLessThan(350);
+    });
+    test('shared types file contains canonical contract documentation', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('Shared contract types');
+        expect(source).toContain('single source of truth');
+        expect(source).toContain('API contract boundary');
+    });
+    test('shared types re-exports from learning/types', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain("from '../learning/types'");
+        // Verify key contract types are re-exported
+        expect(source).toContain('KnowledgeAtom');
+        expect(source).toContain('KnowledgeQueryRequest');
+        expect(source).toContain('KnowledgeQueryResponse');
+        expect(source).toContain('AgentConversationRequest');
+        expect(source).toContain('AgentConversationResponse');
+    });
+    test('shared types defines RuntimeCapabilityContract', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('RuntimeCapabilityContract');
+        expect(source).toContain('capabilityId');
+        expect(source).toContain('status');
+    });
+    test('shared types defines AgentWorkspaceContract', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('AgentWorkspaceContract');
+        expect(source).toContain('conversationId');
+        expect(source).toContain('activePaneId');
+    });
+    test('shared types defines Notemd CLI and workflow contracts', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('NotemdCliOperationContract');
+        expect(source).toContain('NotemdCliInvocationContract');
+        expect(source).toContain('NotemdWorkflowStageContract');
+        expect(source).toContain('NotemdWorkflowResultContract');
+    });
+    test('shared types defines Search and Diagram contracts', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('SearchResultItemContract');
+        expect(source).toContain('SearchResultContract');
+        expect(source).toContain('DiagramGenerationContract');
+        expect(source).toContain('NotemdSettingsContract');
+    });
+    test('shared types defines CI and Infrastructure contracts (GitNexus pattern)', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('CiGateStatusContract');
+        expect(source).toContain('CiDashboardContract');
+        expect(source).toContain('SnapshotStalenessContract');
+    });
+    test('SnapshotStalenessContract has staleness tracking fields', () => {
+        const source = fs.readFileSync(typesFile, 'utf8');
+        expect(source).toContain('lastSaveAt');
+        expect(source).toContain('staleSince');
+        expect(source).toContain('fileMtime');
+        expect(source).toContain('isStale');
+    });
+});

package/dist/src/shared/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * src/shared/types.ts — Shared contract types
+ *
+ * This module defines and re-exports the canonical types shared between
+ * the frontend (.mjs) and backend (.ts) code. These types constitute the
+ * API contract boundary and should be treated as the single source of truth
+ * for cross-cutting type definitions.
+ *
+ * === Usage ===
+ * - Backend (TypeScript):  import type { KnowledgeAtom, ... } from '../shared/types';
+ * - Frontend (JavaScript): @typedef {import('../shared/types').KnowledgeAtom} KnowledgeAtom
+ *
+ * === Design Principle ===
+ * Types defined here belong to the API contract, not to any single module.
+ * They are versioned with the project and must remain backward-compatible
+ * within a major version.
+ *
+ * @module shared/types
+ * @version 2.3.0 — added Notemd CLI, workflow, search, diagram contracts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/sidecar.build.lock.contract.test.js

@@ -0,0 +1,201 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+function runChild(script, args = []) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.execPath, ['-e', script, ...args], {
+            cwd: path.resolve(__dirname, '..'),
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let output = '';
+        child.stdout.on('data', (chunk) => { output += String(chunk); });
+        child.stderr.on('data', (chunk) => { output += String(chunk); });
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ code, output }));
+    });
+}
+function waitForOutput(childScript, args = []) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.execPath, ['-e', childScript, ...args], {
+            cwd: path.resolve(__dirname, '..'),
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let output = '';
+        let timer;
+        const onData = (chunk) => {
+            output += String(chunk);
+            if (output.includes('acquired')) {
+                clearTimeout(timer);
+                child.stdout.off('data', onData);
+                resolve({ child, output });
+            }
+        };
+        child.stdout.on('data', onData);
+        child.stderr.on('data', onData);
+        timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Timed out waiting for child lock acquisition. Output: ${output}`));
+        }, 2500);
+        child.once('close', (code) => {
+            if (!output.includes('acquired')) {
+                clearTimeout(timer);
+                reject(new Error(`Lock holder exited before acquisition (code=${String(code)}). Output: ${output}`));
+            }
+        });
+        child.once('error', reject);
+    });
+}
+function waitForChildClose(child) {
+    if (child.exitCode !== null) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => child.once('close', () => resolve()));
+}
+describe('sidecar build lock', () => {
+    test('rejects an empty lock path at the boundary', () => {
+        expect(() => {
+            const { acquireSidecarBuildLock } = require('../scripts/sidecar-build-lock.js');
+            acquireSidecarBuildLock('');
+        }).toThrow('A concrete sidecar build lock path is required.');
+    });
+    test('serializes independent ensure processes and releases the lock', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'noteconnection-sidecar-lock-'));
+        const lockPath = path.join(tempRoot, 'sidecar-build.lock');
+        const holderScript = `
+            const { acquireSidecarBuildLock } = require('./scripts/sidecar-build-lock.js');
+            const lock = acquireSidecarBuildLock(process.argv[1], { timeoutMs: 3000, staleMs: 30000, pollMs: 25 });
+            console.log('acquired');
+            setTimeout(() => { lock.release(); process.exit(0); }, 800);
+        `;
+        const waiterScript = `
+            const { acquireSidecarBuildLock } = require('./scripts/sidecar-build-lock.js');
+            const startedAt = Date.now();
+            const lock = acquireSidecarBuildLock(process.argv[1], { timeoutMs: 3000, staleMs: 30000, pollMs: 25 });
+            console.log(JSON.stringify({ acquired: true, waitedMs: Date.now() - startedAt }));
+            lock.release();
+        `;
+        try {
+            const holder = await waitForOutput(holderScript, [lockPath]);
+            const waiter = await runChild(waiterScript, [lockPath]);
+            expect(waiter.code).toBe(0);
+            expect(waiter.output).toContain('acquired');
+            const parsed = JSON.parse(waiter.output.match(/\{[^\n]+\}/)?.[0] || '{}');
+            expect(Number(parsed.waitedMs || 0)).toBeGreaterThanOrEqual(250);
+            await waitForChildClose(holder.child);
+            expect(fs.existsSync(lockPath)).toBe(false);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('reclaims an old lock whose owner process is no longer alive', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'noteconnection-sidecar-lock-stale-'));
+        const lockPath = path.join(tempRoot, 'sidecar-build.lock');
+        try {
+            fs.writeFileSync(lockPath, JSON.stringify({
+                pid: 2147483647,
+                hostname: 'stale-test',
+                startedAt: '2020-01-01T00:00:00.000Z',
+                token: 'stale-token',
+            }), 'utf8');
+            const result = await runChild(`
+                const { acquireSidecarBuildLock } = require('./scripts/sidecar-build-lock.js');
+                const lock = acquireSidecarBuildLock(process.argv[1], { timeoutMs: 500, staleMs: 1, pollMs: 10 });
+                console.log('acquired');
+                lock.release();
+            `, [lockPath]);
+            expect(result.code).toBe(0);
+            expect(result.output).toContain('acquired');
+            expect(fs.existsSync(lockPath)).toBe(false);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('reclaims an old lock owned by a different host without trusting a reused pid', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'noteconnection-sidecar-lock-host-'));
+        const lockPath = path.join(tempRoot, 'sidecar-build.lock');
+        try {
+            fs.writeFileSync(lockPath, JSON.stringify({
+                pid: process.pid,
+                hostname: 'different-host',
+                startedAt: '2020-01-01T00:00:00.000Z',
+                token: 'foreign-token',
+            }), 'utf8');
+            const result = await runChild(`
+                const { acquireSidecarBuildLock } = require('./scripts/sidecar-build-lock.js');
+                const lock = acquireSidecarBuildLock(process.argv[1], { timeoutMs: 500, staleMs: 1, pollMs: 10 });
+                console.log('acquired');
+                lock.release();
+            `, [lockPath]);
+            expect(result.code).toBe(0);
+            expect(result.output).toContain('acquired');
+            expect(fs.existsSync(lockPath)).toBe(false);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+    test('fails closed when a live owner holds the lock past the wait budget', async () => {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'noteconnection-sidecar-lock-timeout-'));
+        const lockPath = path.join(tempRoot, 'sidecar-build.lock');
+        const holderScript = `
+            const { acquireSidecarBuildLock } = require('./scripts/sidecar-build-lock.js');
+            const lock = acquireSidecarBuildLock(process.argv[1], { timeoutMs: 3000, staleMs: 30000, pollMs: 25 });
+            console.log('acquired');
+            setTimeout(() => { lock.release(); process.exit(0); }, 700);
+        `;
+        try {
+            const holder = await waitForOutput(holderScript, [lockPath]);
+            const result = await runChild(`
+                const { acquireSidecarBuildLock } = require('./scripts/sidecar-build-lock.js');
+                acquireSidecarBuildLock(process.argv[1], { timeoutMs: 100, staleMs: 30000, pollMs: 25 });
+            `, [lockPath]);
+            expect(result.code).not.toBe(0);
+            expect(result.output).toContain('Timed out waiting for sidecar build lock');
+            holder.child.kill();
+            await waitForChildClose(holder.child);
+        }
+        finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+});