@agentrhq/webcmd 0.3.2 → 0.3.4

package/dist/src/daemon/server.js

@@ -1,8 +1,37 @@
 import { createServer } from 'node:http';
 import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT } from '../constants.js';
 import { buildCommandTimeoutFailure, getResponseCorsHeaders } from '../daemon-utils.js';
+import { getSessionLeaseKey, isSessionLeaseCommand, SessionLeaseRegistry } from '../session-lease.js';
 const MAX_BODY = 1024 * 1024;
 const LOG_BUFFER_SIZE = 200;
+function commandTimeoutMs(command) {
+    return typeof command.deadlineAt === 'number' && command.deadlineAt > 0
+        ? Math.max(1000, command.deadlineAt - Date.now())
+        : (typeof command.timeout === 'number' && command.timeout > 0 ? command.timeout * 1000 : 120_000);
+}
+function waitForCommandResult(command, providerPromise) {
+    const timeoutMs = commandTimeoutMs(command);
+    let timeoutId;
+    const responsePromise = Promise.race([
+        providerPromise,
+        new Promise((resolve) => {
+            timeoutId = setTimeout(() => {
+                const failure = buildCommandTimeoutFailure(command.action, timeoutMs);
+                resolve({
+                    id: command.id,
+                    ok: false,
+                    errorCode: failure.errorCode,
+                    error: failure.message,
+                    errorHint: failure.errorHint,
+                });
+            }, timeoutMs);
+        }),
+    ]);
+    return responsePromise.finally(() => {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    });
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -37,6 +66,8 @@ export function createDaemonServer(provider, opts) {
     const host = opts.host ?? '127.0.0.1';
     const logBuffer = [];
     const pending = new Map();
+    const leases = new SessionLeaseRegistry();
+    const hasPendingWork = (runId) => [...pending.values()].some((entry) => entry.runId === runId);
     let shutdownStarted = false;
     function pushLog(level, msg) {
         logBuffer.push({ level, msg, ts: Date.now() });
@@ -82,6 +113,7 @@ export function createDaemonServer(provider, opts) {
                 daemonVersion: opts.version,
                 ...runtime,
                 pending: pending.size + runtime.pending,
+                sessionLeases: leases.list(hasPendingWork).map(({ runId: _runId, ...lease }) => lease),
                 memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
                 port,
             });
@@ -117,35 +149,44 @@ export function createDaemonServer(provider, opts) {
                 }
                 const existing = pending.get(body.id);
                 if (existing) {
-                    const result = await existing;
+                    const result = await waitForCommandResult(body, existing.promise);
                     jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);
                     return;
                 }
-                const timeoutMs = typeof body.deadlineAt === 'number' && body.deadlineAt > 0
-                    ? Math.max(1000, body.deadlineAt - Date.now())
-                    : (typeof body.timeout === 'number' && body.timeout > 0 ? body.timeout * 1000 : 120_000);
-                let timeoutId;
-                const commandPromise = Promise.race([
-                    provider.dispatch(body),
-                    new Promise((resolve) => {
-                        timeoutId = setTimeout(() => {
-                            const failure = buildCommandTimeoutFailure(body.action, timeoutMs);
-                            resolve({
-                                id: body.id,
-                                ok: false,
-                                errorCode: failure.errorCode,
-                                error: failure.message,
-                                errorHint: failure.errorHint,
-                            });
-                        }, timeoutMs);
-                    }),
-                ]).finally(() => {
-                    if (timeoutId)
-                        clearTimeout(timeoutId);
+                if (body.action === 'lease-release') {
+                    const released = typeof body.runId === 'string' ? leases.releaseByRunId(body.runId) : 0;
+                    jsonResponse(res, 200, { id: body.id, ok: true, data: { released } });
+                    return;
+                }
+                let leaseKey;
+                let runId;
+                if (isSessionLeaseCommand(body)) {
+                    const profileId = provider.resolveProfileId?.(body)
+                        ?? body.profileId
+                        ?? body.contextId
+                        ?? body.preferredContextId
+                        ?? 'default';
+                    leaseKey = getSessionLeaseKey(profileId, body.surface, body.session);
+                    runId = body.runId;
+                    const acquired = leases.acquire({
+                        key: leaseKey,
+                        runId,
+                        command: body.command ?? body.action,
+                        pid: body.pid,
+                    }, hasPendingWork);
+                    if (!acquired.acquired) {
+                        const { key: _key, runId: _runId, ...holder } = acquired.holder;
+                        jsonResponse(res, 409, { ok: false, code: 'session_busy', holder });
+                        return;
+                    }
+                }
+                const commandPromise = provider.dispatch(body).finally(() => {
+                    if (leaseKey && runId)
+                        leases.heartbeat(leaseKey, runId);
                     pending.delete(body.id);
                 });
-                pending.set(body.id, commandPromise);
-                const result = await commandPromise;
+                pending.set(body.id, { promise: commandPromise, runId, leaseKey });
+                const result = await waitForCommandResult(body, commandPromise);
                 if (!result.ok)
                     pushLog('warn', `Command ${body.id} failed: ${result.error ?? result.errorCode ?? 'unknown error'}`);
                 jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);

package/dist/src/daemon/server.test.js

@@ -5,6 +5,11 @@ class FakeProvider {
     commands = [];
     shutdownCalled = false;
     delayMs = 0;
+    dispatchImpl;
+    resolveProfileId;
+    result(command) {
+        return { id: command.id, ok: true, data: { action: command.action }, page: 'page-1' };
+    }
     async status() {
         return {
             runtimeConnected: true,
@@ -16,10 +21,12 @@ class FakeProvider {
         };
     }
     async dispatch(command) {
+        this.commands.push(command);
+        if (this.dispatchImpl)
+            return this.dispatchImpl(command);
         if (this.delayMs > 0)
             await new Promise((resolve) => setTimeout(resolve, this.delayMs));
-        this.commands.push(command);
-        return { id: command.id, ok: true, data: { action: command.action }, page: 'page-1' };
+        return this.result(command);
     }
     async shutdown() {
         this.shutdownCalled = true;
@@ -30,6 +37,7 @@ describe('createDaemonServer', () => {
     afterEach(async () => {
         while (servers.length)
             await servers.pop().close();
+        vi.useRealTimers();
     });
     async function start(provider = new FakeProvider()) {
         const daemon = createDaemonServer(provider, { port: 0, host: '127.0.0.1', version: 'test' });
@@ -38,6 +46,28 @@ describe('createDaemonServer', () => {
         const address = daemon.server.address();
         return { provider, baseUrl: `http://127.0.0.1:${address.port}` };
     }
+    function postCommand(baseUrl, body) {
+        return fetch(`${baseUrl}/command`, {
+            method: 'POST',
+            headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    function persistentWrite(id, runId, overrides = {}) {
+        return {
+            id,
+            action: 'exec',
+            code: '1',
+            surface: 'adapter',
+            siteSession: 'persistent',
+            access: 'write',
+            session: 'site:example',
+            runId,
+            command: 'example write',
+            pid: 4242,
+            ...overrides,
+        };
+    }
     it('returns runtime-named status fields without extension aliases', async () => {
         const { baseUrl } = await start();
         const res = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
@@ -145,6 +175,185 @@ describe('createDaemonServer', () => {
         await expect(second.json()).resolves.toMatchObject({ id: 'same-id', ok: true });
         expect(provider.commands).toHaveLength(1);
     });
+    it('rejects a second persistent adapter writer for the same resolved profile and session', async () => {
+        const provider = new FakeProvider();
+        provider.resolveProfileId = () => 'resolved-work';
+        const { baseUrl } = await start(provider);
+        const first = await postCommand(baseUrl, persistentWrite('first', 'run_100_1_1'));
+        expect(first.status).toBe(200);
+        const second = await postCommand(baseUrl, persistentWrite('second', 'run_200_2_2'));
+        expect(second.status).toBe(409);
+        await expect(second.json()).resolves.toMatchObject({
+            ok: false,
+            code: 'session_busy',
+            holder: {
+                command: 'example write',
+                pid: 4242,
+                acquiredAt: expect.any(Number),
+                heartbeatAt: expect.any(Number),
+            },
+        });
+        expect(provider.commands.map((command) => command.id)).toEqual(['first']);
+    });
+    it('lets one logical run issue multiple operations and heartbeat its lease', async () => {
+        let now = 1_000;
+        vi.spyOn(Date, 'now').mockImplementation(() => now);
+        const { provider, baseUrl } = await start();
+        expect((await postCommand(baseUrl, persistentWrite('first', 'run_100_1_1'))).status).toBe(200);
+        now = 20_000;
+        expect((await postCommand(baseUrl, persistentWrite('second', 'run_100_1_1'))).status).toBe(200);
+        const status = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+        await expect(status.json()).resolves.toMatchObject({
+            sessionLeases: [{
+                    key: 'default␟adapter␟site%3Aexample',
+                    command: 'example write',
+                    acquiredAt: 1_000,
+                    heartbeatAt: 20_000,
+                }],
+        });
+        expect(provider.commands.map((command) => command.id)).toEqual(['first', 'second']);
+    });
+    it.each([
+        ['read access', { access: 'read' }],
+        ['ephemeral sessions', { siteSession: 'ephemeral' }],
+        ['raw browser surface', { surface: 'browser' }],
+        ['different sites', { session: 'site:other' }],
+        ['different resolved profiles', { profileId: 'other' }],
+    ])('does not conflict across %s', async (_case, overrides) => {
+        const provider = new FakeProvider();
+        provider.resolveProfileId = (command) => command.profileId ?? 'default';
+        const { baseUrl } = await start(provider);
+        expect((await postCommand(baseUrl, persistentWrite('owner', 'run_100_1_1'))).status).toBe(200);
+        expect((await postCommand(baseUrl, persistentWrite('other', 'run_200_2_2', overrides))).status).toBe(200);
+        expect(provider.commands.map((command) => command.id)).toEqual(['owner', 'other']);
+    });
+    it('keeps pending holders live past the TTL and heartbeats them before pending removal', async () => {
+        let now = 1_000;
+        vi.spyOn(Date, 'now').mockImplementation(() => now);
+        let settle;
+        const provider = new FakeProvider();
+        provider.dispatchImpl = (command) => new Promise((resolve) => {
+            settle = () => resolve({ id: command.id, ok: true, data: 'done' });
+        });
+        const { baseUrl } = await start(provider);
+        const pending = postCommand(baseUrl, persistentWrite('pending', 'run_100_1_1'));
+        try {
+            await vi.waitFor(() => expect(provider.commands).toHaveLength(1));
+            now = 46_001;
+            const whilePending = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+            await expect(whilePending.json()).resolves.toMatchObject({
+                sessionLeases: [{ command: 'example write', heartbeatAt: 1_000 }],
+            });
+            const conflict = await postCommand(baseUrl, persistentWrite('conflict', 'run_200_2_2'));
+            expect(conflict.status).toBe(409);
+            expect(provider.commands).toHaveLength(1);
+            now = 50_000;
+            settle?.();
+            expect((await pending).status).toBe(200);
+            const afterSettle = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+            const statusBody = await afterSettle.json();
+            expect(statusBody.sessionLeases).toEqual([expect.objectContaining({ heartbeatAt: 50_000 })]);
+            expect(statusBody.sessionLeases[0]).not.toHaveProperty('runId');
+        }
+        finally {
+            settle?.();
+            await pending.catch(() => undefined);
+        }
+    });
+    it('keeps timed-out provider work pending until provider settlement', async () => {
+        let now = 1_000;
+        const dateNow = vi.spyOn(Date, 'now').mockImplementation(() => now);
+        let settleProvider;
+        let providerStarted;
+        const providerStartedPromise = new Promise((resolve) => {
+            providerStarted = resolve;
+        });
+        const provider = new FakeProvider();
+        provider.dispatchImpl = (command) => {
+            if (command.id !== 'timed-out') {
+                return Promise.resolve({ id: command.id, ok: true, data: 'done' });
+            }
+            if (provider.commands.filter(({ id }) => id === command.id).length > 1) {
+                return Promise.resolve({ id: command.id, ok: true, data: 'duplicate dispatch' });
+            }
+            providerStarted();
+            return new Promise((resolve) => {
+                settleProvider = () => resolve({ id: command.id, ok: true, data: 'done' });
+            });
+        };
+        const { baseUrl } = await start(provider);
+        const firstRequest = postCommand(baseUrl, persistentWrite('timed-out', 'run_100_1_1', { timeout: 0.01 }));
+        try {
+            await providerStartedPromise;
+            const timedOut = await firstRequest;
+            expect(timedOut.status).toBe(408);
+            await expect(timedOut.json()).resolves.toMatchObject({
+                id: 'timed-out',
+                ok: false,
+                errorCode: 'command_result_unknown',
+            });
+            now = 47_001;
+            const duplicateRequest = postCommand(baseUrl, persistentWrite('timed-out', 'run_100_1_1', { timeout: 120 }));
+            const whileProviderPending = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+            await expect(whileProviderPending.json()).resolves.toMatchObject({
+                pending: 1,
+                sessionLeases: [{ command: 'example write', heartbeatAt: 1_000 }],
+            });
+            expect(provider.commands.map((command) => command.id)).toEqual(['timed-out']);
+            const conflict = await postCommand(baseUrl, persistentWrite('conflict', 'run_200_2_2'));
+            expect(conflict.status).toBe(409);
+            expect(provider.commands.map((command) => command.id)).toEqual(['timed-out']);
+            settleProvider?.();
+            const duplicate = await duplicateRequest;
+            expect(duplicate.status).toBe(200);
+            await expect(duplicate.json()).resolves.toMatchObject({ data: 'done' });
+            const afterProviderSettle = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+            await expect(afterProviderSettle.json()).resolves.toMatchObject({
+                pending: 0,
+                sessionLeases: [{ command: 'example write', heartbeatAt: 47_001 }],
+            });
+            now = 92_002;
+            const reclaimed = await postCommand(baseUrl, persistentWrite('reclaimed', 'run_200_2_2'));
+            expect(reclaimed.status).toBe(200);
+            expect(provider.commands.map((command) => command.id)).toEqual(['timed-out', 'reclaimed']);
+        }
+        finally {
+            settleProvider?.();
+            await firstRequest.catch(() => undefined);
+            dateNow.mockRestore();
+        }
+    });
+    it('handles lease-release locally and permits a new owner', async () => {
+        const { provider, baseUrl } = await start();
+        expect((await postCommand(baseUrl, persistentWrite('owner', 'run_100_1_1'))).status).toBe(200);
+        const released = await postCommand(baseUrl, {
+            id: 'release',
+            action: 'lease-release',
+            runId: 'run_100_1_1',
+        });
+        expect(released.status).toBe(200);
+        await expect(released.json()).resolves.toMatchObject({
+            id: 'release',
+            ok: true,
+            data: { released: 1 },
+        });
+        expect(provider.commands.map((command) => command.id)).toEqual(['owner']);
+        expect((await postCommand(baseUrl, persistentWrite('next-owner', 'run_200_2_2'))).status).toBe(200);
+        expect(provider.commands.map((command) => command.id)).toEqual(['owner', 'next-owner']);
+    });
+    it('returns only sanitized current holders from status', async () => {
+        let now = 1_000;
+        vi.spyOn(Date, 'now').mockImplementation(() => now);
+        const { baseUrl } = await start();
+        expect((await postCommand(baseUrl, persistentWrite('owner', 'run_100_1_1'))).status).toBe(200);
+        const current = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+        const currentBody = await current.json();
+        expect(currentBody.sessionLeases).toHaveLength(1);
+        expect(currentBody.sessionLeases[0]).not.toHaveProperty('runId');
+        now = 46_001;
+        const expired = await fetch(`${baseUrl}/status`, { headers: { [DAEMON_HEADER_NAME]: '1' } });
+        await expect(expired.json()).resolves.toMatchObject({ sessionLeases: [] });
+    });
     it('requires X-Webcmd on non-ping endpoints', async () => {
         const { baseUrl } = await start();
         const res = await fetch(`${baseUrl}/status`);

package/dist/src/docs-sync-review-cli.test.js

@@ -310,7 +310,7 @@ describe('documentation sync workflow', () => {
             expect(workflow).toContain(event);
         }
         expect(workflow).toContain('contents: read');
-        expect(workflow).toContain('pull-requests: read');
+        expect(workflow).toContain('pull-requests: write');
         expect(workflow).toContain('issues: write');
         expect(workflow).toContain('ref: ${{ github.event.repository.default_branch }}');
         expect(workflow).toContain('GH_TOKEN: ${{ github.token }}');

package/dist/src/errors.d.ts

@@ -20,6 +20,7 @@
  * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
  */
 import type { ObservationTraceReceipt } from './observation/events.js';
+import { type SessionLeaseHolder } from './session-lease.js';
 export declare const EXIT_CODES: {
     readonly SUCCESS: 0;
     readonly GENERIC_ERROR: 1;
@@ -72,6 +73,10 @@ export declare class TimeoutError extends CliError {
 export declare class ArgumentError extends CliError {
     constructor(message: string, hint?: string);
 }
+/** A persistent write session is temporarily owned by another logical run. */
+export declare class SessionBusyError extends CliError {
+    constructor(holder: SessionLeaseHolder, platform?: string);
+}
 export declare class EmptyResultError extends CliError {
     constructor(command: string, hint?: string);
 }

package/dist/src/errors.js

@@ -1,3 +1,4 @@
+import { isActionablePid } from './session-lease.js';
 // ── Exit code table ──────────────────────────────────────────────────────────
 export const EXIT_CODES = {
     SUCCESS: 0,
@@ -81,6 +82,28 @@ export class ArgumentError extends CliError {
         super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
     }
 }
+function formatBusyMessage(holder) {
+    const owner = !isActionablePid(holder.pid)
+        ? holder.command
+        : `${holder.command} (pid ${holder.pid})`;
+    return `Session is busy: ${owner} is already driving it.`;
+}
+function formatBusyHint(holder, platform) {
+    if (platform === 'win32') {
+        return !isActionablePid(holder.pid)
+            ? 'Wait for it to finish, or use Task Manager to stop the owning process if it is stuck.'
+            : `Wait for it to finish, or run \`Stop-Process -Id ${holder.pid}\` in PowerShell if it is stuck.`;
+    }
+    return !isActionablePid(holder.pid)
+        ? 'Wait for it to finish, or stop the owning process if it is stuck.'
+        : `Wait for it to finish, or run \`kill ${holder.pid}\` if it is stuck.`;
+}
+/** A persistent write session is temporarily owned by another logical run. */
+export class SessionBusyError extends CliError {
+    constructor(holder, platform = process.platform) {
+        super('SESSION_BUSY', formatBusyMessage(holder), formatBusyHint(holder, platform), EXIT_CODES.TEMPFAIL);
+    }
+}
 export class EmptyResultError extends CliError {
     constructor(command, hint) {
         super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in', EXIT_CODES.EMPTY_RESULT);

package/dist/src/errors.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { CliError, BrowserConnectError, adapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, selectorError, attachTraceReceipt, toEnvelope, } from './errors.js';
+import { CliError, BrowserConnectError, adapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, selectorError, SessionBusyError, attachTraceReceipt, toEnvelope, } from './errors.js';
 describe('Error type hierarchy', () => {
     it('all error types extend CliError', () => {
         const errors = [
@@ -71,6 +71,23 @@ describe('toEnvelope', () => {
             },
         });
     });
+    it('serializes SessionBusyError with the public code and temporary-failure exit code', () => {
+        const err = new SessionBusyError({
+            command: 'chatgpt ask',
+            pid: 4242,
+            acquiredAt: 1_000,
+            heartbeatAt: 2_000,
+        });
+        expect(toEnvelope(err)).toEqual({
+            ok: false,
+            error: {
+                code: 'SESSION_BUSY',
+                message: expect.stringContaining('chatgpt ask'),
+                help: expect.any(String),
+                exitCode: 75,
+            },
+        });
+    });
     it('converts CliError without hint (omits help field)', () => {
         const err = new CommandExecutionError('Something broke');
         const envelope = toEnvelope(err);
@@ -120,3 +137,43 @@ describe('toEnvelope', () => {
         });
     });
 });
+describe('SessionBusyError platform hints', () => {
+    const holder = {
+        command: 'chatgpt ask',
+        pid: 4242,
+        acquiredAt: 1_000,
+        heartbeatAt: 2_000,
+    };
+    it('uses PowerShell process guidance on Windows when the holder pid is known', () => {
+        const err = new SessionBusyError(holder, 'win32');
+        expect(err.hint).toContain('Stop-Process -Id 4242');
+        expect(err.hint).not.toContain('kill 4242');
+    });
+    it('uses Task Manager guidance on Windows when the holder pid is unavailable', () => {
+        const err = new SessionBusyError({ ...holder, pid: undefined }, 'win32');
+        expect(err.hint).toMatch(/wait/i);
+        expect(err.hint).toContain('Task Manager');
+        expect(err.hint).not.toContain('Stop-Process');
+    });
+    it('uses kill guidance on POSIX when the holder pid is known', () => {
+        const err = new SessionBusyError(holder, 'linux');
+        expect(err.hint).toContain('kill 4242');
+        expect(err.hint).not.toContain('Stop-Process');
+    });
+    it.each([
+        0,
+        -1,
+        1.5,
+        Number.NaN,
+        Number.POSITIVE_INFINITY,
+        Number.MAX_SAFE_INTEGER + 1,
+    ])('does not expose non-actionable pid %s in process guidance', (pid) => {
+        const windowsError = new SessionBusyError({ ...holder, pid }, 'win32');
+        expect(windowsError.message).not.toContain(`pid ${pid}`);
+        expect(windowsError.hint).toContain('Task Manager');
+        expect(windowsError.hint).not.toContain('Stop-Process');
+        const posixError = new SessionBusyError({ ...holder, pid }, 'linux');
+        expect(posixError.message).not.toContain(`pid ${pid}`);
+        expect(posixError.hint).not.toContain('kill');
+    });
+});

package/dist/src/execution.js

@@ -15,11 +15,11 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { executePipeline } from './pipeline/index.js';
-import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
+import { adapterLoadError, ArgumentError, CommandExecutionError, TimeoutError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { profileRouteParams, resolveProfileSelection } from './browser/profile.js';
-import { setDaemonCommandTimeoutSeconds } from './browser/daemon-client.js';
+import { releaseSiteSessionLease, setDaemonCommandTimeoutSeconds } from './browser/daemon-client.js';
 import { emitHook } from './hooks.js';
 import { log } from './logger.js';
 import { isElectronApp } from './electron-apps.js';
@@ -27,10 +27,16 @@ import { probeCDP, resolveElectronEndpoint } from './launcher.js';
 import { ObservationSession, exportObservationSession } from './observation/index.js';
 import { resolveAdapterSourcePath } from './adapter-source.js';
 import { coerceCommandArguments, TRACE_MODES } from './command-surface.js';
+import { clearDaemonRunContext, generateRunId, isUnknownOutcomeError, runWithDaemonRunContext } from './session-lease.js';
 const _loadedModules = new Map();
 /** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
 const _moduleMtimes = new Map();
 const _userClisDir = `${os.homedir()}/.webcmd/clis/`;
+async function finalizeRun(runId, release) {
+    clearDaemonRunContext(runId);
+    if (release)
+        await releaseSiteSessionLease(runId).catch(() => undefined);
+}
 function normalizeTraceMode(raw) {
     if (raw === undefined || raw === null || raw === '' || raw === 'off')
         return 'off';
@@ -178,7 +184,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             const session = resolveAdapterBrowserSession(cmd, siteSession);
             const keepTab = resolveKeepTab(siteSession, opts.keepTab);
             const windowMode = resolveBrowserWindowMode(cmd.defaultWindowMode ?? 'background', opts.windowMode);
-            result = await browserSession(BrowserFactory, async (page) => {
+            const surface = 'adapter';
+            const canonicalCommand = fullName(cmd);
+            const leaseEligible = surface === 'adapter'
+                && siteSession === 'persistent'
+                && cmd.access === 'write';
+            const runId = leaseEligible ? generateRunId() : undefined;
+            let releaseRun = true;
+            let deferRunFinalization = false;
+            const executeAdapter = async (page) => {
                 const observation = traceMode === 'off'
                     ? null
                     : new ObservationSession({
@@ -223,6 +237,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         });
                     }
                     catch (err) {
+                        if (runId && isUnknownOutcomeError(err))
+                            releaseRun = false;
                         observation?.record({
                             stream: 'action',
                             name: 'pre_navigate',
@@ -244,13 +260,16 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw wrapped;
                     }
                 }
+                const adapterPromise = Promise.resolve(runCommand(cmd, page, kwargs, debug));
+                let adapterSettled = false;
+                void adapterPromise.then(() => { adapterSettled = true; }, () => { adapterSettled = true; });
                 try {
                     const browserTimeout = userTimeoutSec !== null
                         ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
                         : DEFAULT_BROWSER_COMMAND_TIMEOUT;
-                    const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                    const result = await runWithTimeout(adapterPromise, {
                         timeout: browserTimeout,
-                        label: fullName(cmd),
+                        label: canonicalCommand,
                     });
                     observation?.record({
                         stream: 'action',
@@ -269,6 +288,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     return result;
                 }
                 catch (err) {
+                    if (runId && isUnknownOutcomeError(err))
+                        releaseRun = false;
+                    if (runId && err instanceof TimeoutError && !adapterSettled) {
+                        releaseRun = false;
+                        deferRunFinalization = true;
+                        void adapterPromise
+                            .then(() => finalizeRun(runId, true), (lateError) => finalizeRun(runId, !isUnknownOutcomeError(lateError)))
+                            .catch(() => undefined);
+                    }
                     if (observation) {
                         observation.record({
                             stream: 'action',
@@ -293,7 +321,30 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession, freshPage: cmd.freshPage === true && siteSession === 'persistent' });
+            };
+            const executeBrowser = () => browserSession(BrowserFactory, executeAdapter, {
+                session,
+                cdpEndpoint,
+                ...profileRouting,
+                windowMode,
+                surface,
+                siteSession,
+                freshPage: cmd.freshPage === true && siteSession === 'persistent',
+            });
+            try {
+                result = runId
+                    ? await runWithDaemonRunContext({ runId, command: canonicalCommand, access: 'write' }, executeBrowser)
+                    : await executeBrowser();
+            }
+            catch (err) {
+                if (runId && isUnknownOutcomeError(err))
+                    releaseRun = false;
+                throw err;
+            }
+            finally {
+                if (runId && !deferRunFinalization)
+                    await finalizeRun(runId, releaseRun);
+            }
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes