@agentrhq/webcmd 0.3.1 → 0.3.3

package/dist/src/cli.js

@@ -18,7 +18,7 @@ import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
-import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
+import { addWebcmdSkills, listWebcmdSkills, removeWebcmdSkills, updateWebcmdSkill } from './skills.js';
 import { registerAllCommands } from './commanderAdapter.js';
 import { buildRootHelpPresentation, classifyAdapter, installCommanderNamespaceStructuredHelp, installRootPresentationHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError, ArgumentError } from './errors.js';
@@ -62,15 +62,15 @@ function parseDurationMs(raw, flagName) {
 function timestampFromRaw(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
 }
-function isInteractiveInstall(opts) {
+function isInteractiveSkillAdd(opts) {
     return !opts.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
-async function resolveSkillInstallOptions(opts) {
-    if (!isInteractiveInstall(opts))
+async function resolveSkillAddOptions(opts) {
+    if (!isInteractiveSkillAdd(opts))
         return opts;
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd install skills?', [
+        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd add skills?', [
             { key: '1', label: 'Global', value: 'user', aliases: ['global', 'user', 'g'] },
             { key: '2', label: 'Local project', value: 'project', aliases: ['local', 'project', 'l'] },
         ], '1');
@@ -126,6 +126,24 @@ async function handleSkillLinkCommand(action, json, verb) {
         process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
     }
 }
+function handleSkillRemoveCommand(customPath, json) {
+    try {
+        const result = removeWebcmdSkills({ customPath });
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Webcmd skill links removed: ${result.removed.length}`);
+        for (const linkPath of result.removed)
+            console.log(linkPath);
+    }
+    catch (err) {
+        console.error(`Error: ${getErrorMessage(err)}`);
+        if (err instanceof CliError && err.hint)
+            console.error(`Hint: ${err.hint}`);
+        process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
+    }
+}
 function toIsoTimestamp(timestamp) {
     if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0)
         return undefined;
@@ -706,7 +724,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     });
     const skillsCmd = program
         .command('skills')
-        .description('List, install, and update bundled Webcmd skills')
+        .description('List, add, update, and remove bundled Webcmd skills')
         .action(() => {
         const rows = listWebcmdSkills();
         renderOutput(rows, {
@@ -732,24 +750,24 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         });
     });
     skillsCmd
-        .command('install')
-        .description('Install bundled Webcmd skills into an agent skills folder')
+        .command('add')
+        .description('Add bundled Webcmd skills to an agent skills folder')
         .option('-p, --provider <provider>', 'Agent provider: agents, codex, claude')
-        .option('-s, --scope <scope>', 'Install scope: user/global or project/local')
+        .option('-s, --scope <scope>', 'Add scope: user/global or project/local')
         .option('--path <path>', 'Custom agent skills directory')
         .option('--json', 'Output a JSON envelope', false)
         .action(async (opts) => {
         await handleSkillLinkCommand(async () => {
-            const resolved = await resolveSkillInstallOptions(opts);
+            const resolved = await resolveSkillAddOptions(opts);
             if (resolved.provider === 'custom' && !resolved.path) {
                 throw new ArgumentError('Custom skill provider requires --path.', 'Pass --path <skills-dir> or run interactively.');
             }
-            return installWebcmdSkill({
+            return addWebcmdSkills({
                 provider: resolved.provider,
                 scope: resolved.scope,
                 customPath: resolved.path,
             });
-        }, opts.json, 'installed');
+        }, opts.json, 'added');
     });
     skillsCmd
         .command('update')
@@ -765,6 +783,12 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             customPath: opts.path,
         }), opts.json, 'updated');
     });
+    skillsCmd
+        .command('remove')
+        .description('Remove bundled Webcmd skill symlinks from supported locations')
+        .option('--path <path>', 'Also remove links from a custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action((opts) => handleSkillRemoveCommand(opts.path, opts.json));
     const authCmd = registerAuthCommands(program);
     program
         .command('convention-audit')

package/dist/src/cli.test.js

@@ -60,6 +60,11 @@ describe('createProgram root help descriptions', () => {
         expect(descriptionFor(program, 'daemon')).toBe('restart, status, stop');
         expect(descriptionFor(program, 'external')).toBe('install, list, register');
     });
+    it('exposes add and remove without an install command', () => {
+        const skills = createProgram('', '').commands.find((command) => command.name() === 'skills');
+        expect(skills.commands.map((command) => command.name())).toEqual(['list', 'add', 'update', 'remove']);
+        expect(skills.commands.find((command) => command.name() === 'add')?.aliases()).toEqual([]);
+    });
     it('renders auth namespace structured help', () => {
         const argv = process.argv;
         try {

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');
+    });
+});