@superdoc/sdk 2.19.0-next.9 → 2.19.1-next.1

package/dist/runtime/host.cjs

@@ -3,6 +3,7 @@
 var node_child_process = require('node:child_process');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
+var stateDirectory = require('./state-directory.cjs');
 var documentEvidence = require('./document-evidence.cjs');
 var contract = require('../generated/contract.cjs');
 var documentRpc = require('./document-rpc.cjs');
@@ -84,6 +85,8 @@ function resolveJsWatchdogTimeout(watchdogTimeoutMs, requestTimeoutMs, timeoutMs
 }
 /** Transport for the legacy CLI host or the structured document host. */
 class HostTransport {
+    stateDirectory;
+    stoppedChildren = new Map();
     hostBin;
     processMode;
     env;
@@ -112,6 +115,7 @@ class HostTransport {
     documentRpcMutationStates = new Map();
     indeterminateDiscardCloses = new Set();
     constructor(options) {
+        this.stateDirectory = new stateDirectory.SdkStateDirectory(options.stateDir);
         this.hostBin = options.hostBin;
         this.processMode = options.processMode ?? 'cli';
         this.env = options.env;
@@ -175,7 +179,11 @@ class HostTransport {
             return this.disposePromise;
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
-        if (!this.child && !this.connecting && this.activeCalls.size === 0)
+        if (!this.child &&
+            !this.connecting &&
+            this.activeCalls.size === 0 &&
+            !this.stateDirectory.ownsRoot &&
+            this.stoppedChildren.size === 0)
             return;
         this.stopping = true;
         const disposal = this.disposeAfterActiveCalls();
@@ -193,8 +201,11 @@ class HostTransport {
         await Promise.allSettled(Array.from(this.activeCalls));
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
-        if (!this.child)
+        if (!this.child) {
+            await this.waitForStoppedChildren();
+            await this.stateDirectory.dispose();
             return;
+        }
         try {
             await this.reconcileIndeterminateDiscardCloses();
             await this.persistDirtyDocumentRpcSessions();
@@ -212,17 +223,16 @@ class HostTransport {
         catch {
             // ignore and force shutdown below
         }
-        await new Promise((resolve) => {
-            const timer = setTimeout(() => {
-                child.kill('SIGKILL');
-                resolve();
-            }, this.shutdownTimeoutMs);
-            child.once('close', () => {
-                clearTimeout(timer);
-                resolve();
+        await this.waitForStoppedChildren(true);
+        if (child.exitCode !== 0) {
+            this.terminalDisposalError = new errors.SuperDocCliError('Host shutdown failed; its state directory has been retained.', {
+                code: 'HOST_SHUTDOWN_FAILED',
+                details: { path: this.stateDirectory.path, exitCode: child.exitCode, signal: child.signalCode },
             });
-        });
+            throw this.terminalDisposalError;
+        }
         this.cleanupProcess(null);
+        await this.stateDirectory.dispose();
     }
     async invoke(operation, params = {}, options = {}) {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
@@ -452,14 +462,15 @@ class HostTransport {
         const args = this.processMode === 'document'
             ? buildDocumentHostSpawnArgs(prefixArgs)
             : buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
+        await this.waitForStoppedChildren();
+        const env = { ...process.env, ...this.env };
+        env.SUPERDOC_CLI_STATE_DIR = await this.stateDirectory.prepare(env);
         const child = node_child_process.spawn(command, args, {
-            env: {
-                ...process.env,
-                ...this.env,
-            },
+            env,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         this.child = child;
+        this.stoppedChildren.set(child, new Promise((resolve) => child.once('close', () => resolve())));
         // JSON-RPC is framed by ASCII LF; Node 24 readline also splits on a raw
         // U+2028 inside otherwise valid JSON string data.
         child.stdout.setEncoding('utf8');
@@ -473,6 +484,8 @@ class HostTransport {
             process.stderr.write(`[superdoc-host] ${String(chunk)}`);
         });
         child.on('error', (error) => {
+            if (this.child !== child)
+                return;
             this.handleDisconnect(new errors.SuperDocCliError('Host process failed.', {
                 code: 'HOST_DISCONNECTED',
                 details: {
@@ -481,6 +494,8 @@ class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
+            if (this.child !== child)
+                return;
             if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
@@ -738,11 +753,11 @@ class HostTransport {
         const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
         const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
         if (cliCode) {
-            return new errors.SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
+            return this.stateDirectory.mapOperationError(new errors.SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
                 code: cliCode,
                 details: data?.details,
                 exitCode,
-            });
+            }));
         }
         if (domainCode) {
             return new errors.SuperDocCliError(error.message, {
@@ -765,6 +780,33 @@ class HostTransport {
             details: data,
         });
     }
+    async waitForStoppedChildren(forceAfterTimeout = false) {
+        for (const [child, stopped] of this.stoppedChildren) {
+            let timer;
+            try {
+                await new Promise((resolve, reject) => {
+                    const fail = () => reject(new errors.SuperDocCliError('Host process did not stop; state has been retained.', {
+                        code: 'HOST_DISCONNECTED',
+                        details: { pid: child.pid },
+                    }));
+                    timer = setTimeout(() => {
+                        if (!forceAfterTimeout) {
+                            fail();
+                            return;
+                        }
+                        child.kill('SIGKILL');
+                        timer = setTimeout(fail, this.shutdownTimeoutMs);
+                    }, this.shutdownTimeoutMs);
+                    void stopped.then(resolve, reject);
+                });
+                this.stoppedChildren.delete(child);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        }
+    }
     handleDisconnect(error) {
         this.cleanupProcess(error);
     }
@@ -784,8 +826,8 @@ class HostTransport {
         if (child) {
             if (this.stdoutDataListener)
                 child.stdout.off('data', this.stdoutDataListener);
-            child.removeAllListeners();
-            child.kill('SIGKILL');
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL');
         }
         this.child = null;
         this.stdoutBuffer = '';

package/dist/runtime/host.d.ts

@@ -31,6 +31,8 @@ export declare function buildDocumentHostSpawnArgs(prefixArgs: readonly string[]
 export declare function resolveJsWatchdogTimeout(watchdogTimeoutMs: number, requestTimeoutMs: number | undefined, timeoutMsOverride: number | undefined): number;
 /** Transport for the legacy CLI host or the structured document host. */
 export declare class HostTransport {
+    private readonly stateDirectory;
+    private readonly stoppedChildren;
     private readonly hostBin;
     private readonly processMode;
     private readonly env?;
@@ -87,6 +89,7 @@ export declare class HostTransport {
     private onStdoutLine;
     private onStdoutChunk;
     private mapJsonRpcError;
+    private waitForStoppedChildren;
     private handleDisconnect;
     private cleanupProcess;
 }

package/dist/runtime/host.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { buildOperationArgv, buildStructuredReadInput, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
+import { SdkStateDirectory } from './state-directory.js';
 import { registerMutationRevision } from './document-evidence.js';
 import { CONTRACT } from '../generated/contract.js';
 import { DOCUMENT_RPC_FEATURES, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, DOCUMENT_RPC_REPLACE_FILE_FEATURE, DOCUMENT_RPC_SOURCE_SAVE_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, mapDocumentReplaceFileResult, supportsDocumentRpc, } from './document-rpc.js';
@@ -81,6 +82,8 @@ export function resolveJsWatchdogTimeout(watchdogTimeoutMs, requestTimeoutMs, ti
 }
 /** Transport for the legacy CLI host or the structured document host. */
 export class HostTransport {
+    stateDirectory;
+    stoppedChildren = new Map();
     hostBin;
     processMode;
     env;
@@ -109,6 +112,7 @@ export class HostTransport {
     documentRpcMutationStates = new Map();
     indeterminateDiscardCloses = new Set();
     constructor(options) {
+        this.stateDirectory = new SdkStateDirectory(options.stateDir);
         this.hostBin = options.hostBin;
         this.processMode = options.processMode ?? 'cli';
         this.env = options.env;
@@ -172,7 +176,11 @@ export class HostTransport {
             return this.disposePromise;
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
-        if (!this.child && !this.connecting && this.activeCalls.size === 0)
+        if (!this.child &&
+            !this.connecting &&
+            this.activeCalls.size === 0 &&
+            !this.stateDirectory.ownsRoot &&
+            this.stoppedChildren.size === 0)
             return;
         this.stopping = true;
         const disposal = this.disposeAfterActiveCalls();
@@ -190,8 +198,11 @@ export class HostTransport {
         await Promise.allSettled(Array.from(this.activeCalls));
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
-        if (!this.child)
+        if (!this.child) {
+            await this.waitForStoppedChildren();
+            await this.stateDirectory.dispose();
             return;
+        }
         try {
             await this.reconcileIndeterminateDiscardCloses();
             await this.persistDirtyDocumentRpcSessions();
@@ -209,17 +220,16 @@ export class HostTransport {
         catch {
             // ignore and force shutdown below
         }
-        await new Promise((resolve) => {
-            const timer = setTimeout(() => {
-                child.kill('SIGKILL');
-                resolve();
-            }, this.shutdownTimeoutMs);
-            child.once('close', () => {
-                clearTimeout(timer);
-                resolve();
+        await this.waitForStoppedChildren(true);
+        if (child.exitCode !== 0) {
+            this.terminalDisposalError = new SuperDocCliError('Host shutdown failed; its state directory has been retained.', {
+                code: 'HOST_SHUTDOWN_FAILED',
+                details: { path: this.stateDirectory.path, exitCode: child.exitCode, signal: child.signalCode },
             });
-        });
+            throw this.terminalDisposalError;
+        }
         this.cleanupProcess(null);
+        await this.stateDirectory.dispose();
     }
     async invoke(operation, params = {}, options = {}) {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
@@ -449,14 +459,15 @@ export class HostTransport {
         const args = this.processMode === 'document'
             ? buildDocumentHostSpawnArgs(prefixArgs)
             : buildHostSpawnArgs(prefixArgs, { requestTimeoutMs: this.requestTimeoutMs });
+        await this.waitForStoppedChildren();
+        const env = { ...process.env, ...this.env };
+        env.SUPERDOC_CLI_STATE_DIR = await this.stateDirectory.prepare(env);
         const child = spawn(command, args, {
-            env: {
-                ...process.env,
-                ...this.env,
-            },
+            env,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         this.child = child;
+        this.stoppedChildren.set(child, new Promise((resolve) => child.once('close', () => resolve())));
         // JSON-RPC is framed by ASCII LF; Node 24 readline also splits on a raw
         // U+2028 inside otherwise valid JSON string data.
         child.stdout.setEncoding('utf8');
@@ -470,6 +481,8 @@ export class HostTransport {
             process.stderr.write(`[superdoc-host] ${String(chunk)}`);
         });
         child.on('error', (error) => {
+            if (this.child !== child)
+                return;
             this.handleDisconnect(new SuperDocCliError('Host process failed.', {
                 code: 'HOST_DISCONNECTED',
                 details: {
@@ -478,6 +491,8 @@ export class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
+            if (this.child !== child)
+                return;
             if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
@@ -735,11 +750,11 @@ export class HostTransport {
         const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
         const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
         if (cliCode) {
-            return new SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
+            return this.stateDirectory.mapOperationError(new SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
                 code: cliCode,
                 details: data?.details,
                 exitCode,
-            });
+            }));
         }
         if (domainCode) {
             return new SuperDocCliError(error.message, {
@@ -762,6 +777,33 @@ export class HostTransport {
             details: data,
         });
     }
+    async waitForStoppedChildren(forceAfterTimeout = false) {
+        for (const [child, stopped] of this.stoppedChildren) {
+            let timer;
+            try {
+                await new Promise((resolve, reject) => {
+                    const fail = () => reject(new SuperDocCliError('Host process did not stop; state has been retained.', {
+                        code: 'HOST_DISCONNECTED',
+                        details: { pid: child.pid },
+                    }));
+                    timer = setTimeout(() => {
+                        if (!forceAfterTimeout) {
+                            fail();
+                            return;
+                        }
+                        child.kill('SIGKILL');
+                        timer = setTimeout(fail, this.shutdownTimeoutMs);
+                    }, this.shutdownTimeoutMs);
+                    void stopped.then(resolve, reject);
+                });
+                this.stoppedChildren.delete(child);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        }
+    }
     handleDisconnect(error) {
         this.cleanupProcess(error);
     }
@@ -781,8 +823,8 @@ export class HostTransport {
         if (child) {
             if (this.stdoutDataListener)
                 child.stdout.off('data', this.stdoutDataListener);
-            child.removeAllListeners();
-            child.kill('SIGKILL');
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL');
         }
         this.child = null;
         this.stdoutBuffer = '';

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.19.0-next.9';
+const SDK_VERSION = '2.19.1-next.1';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.19.0-next.9";
+export declare const SDK_VERSION = "2.19.1-next.1";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.19.0-next.9';
+export const SDK_VERSION = '2.19.1-next.1';

package/dist/runtime/state-directory.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var os = require('node:os');
+var path = require('node:path');
+var node_crypto = require('node:crypto');
+var errors = require('./errors.cjs');
+
+const FILESYSTEM_CODES = new Set(['EACCES', 'EPERM', 'EROFS', 'ENOSPC', 'EDQUOT', 'ENOTDIR', 'ENOENT']);
+class SdkStateDirectory {
+    configured;
+    selection;
+    constructor(configured) {
+        this.configured = configured;
+    }
+    get path() {
+        return this.selection?.path;
+    }
+    get ownsRoot() {
+        return this.selection?.owned === true;
+    }
+    async prepare(env) {
+        if (this.configured !== undefined && (typeof this.configured !== 'string' || !this.configured.trim())) {
+            throw new errors.SuperDocCliError('stateDir must be a non-empty path.', { code: 'INVALID_ARGUMENT' });
+        }
+        if (this.selection) {
+            await this.check(this.selection);
+            return this.selection.path;
+        }
+        const explicit = this.configured ?? (env.SUPERDOC_CLI_STATE_DIR || undefined);
+        if (explicit !== undefined) {
+            const selection = {
+                path: path.resolve(explicit),
+                source: this.configured !== undefined ? 'stateDir' : 'SUPERDOC_CLI_STATE_DIR',
+                owned: false,
+            };
+            await this.check(selection);
+            this.selection = selection;
+            return selection.path;
+        }
+        let home = process.platform === 'win32' ? env.USERPROFILE : env.HOME;
+        if (!home) {
+            try {
+                home = os.userInfo().homedir;
+            }
+            catch {
+                /* A container UID need not have a passwd entry. */
+            }
+        }
+        if (home) {
+            const selection = { path: path.join(home, '.superdoc-cli', 'state', 'v1'), source: 'home', owned: false };
+            try {
+                if ((await promises.stat(home)).isDirectory()) {
+                    await this.probe(selection.path);
+                    this.selection = selection;
+                    return selection.path;
+                }
+            }
+            catch {
+                /* An unusable implicit home may use private temporary state. */
+            }
+        }
+        const temporary = process.platform === 'win32'
+            ? env.TEMP || env.TMP || (env.SystemRoot ? path.join(env.SystemRoot, 'temp') : os.tmpdir())
+            : env.TMPDIR || env.TMP || env.TEMP || '/tmp';
+        let allocated;
+        try {
+            allocated = await promises.mkdtemp(path.join(path.resolve(temporary), 'superdoc-sdk-state-'));
+            const selection = { path: allocated, source: 'temporary', owned: true };
+            await this.probe(allocated);
+            this.selection = selection;
+            return allocated;
+        }
+        catch (error) {
+            if (allocated)
+                await promises.rm(allocated, { recursive: true, force: true });
+            throw this.failure({ path: path.resolve(temporary), source: 'temporary', owned: false }, error);
+        }
+    }
+    async dispose() {
+        const selection = this.selection;
+        if (!selection)
+            return;
+        if (selection.owned)
+            await promises.rm(selection.path, { recursive: true, force: true });
+        this.selection = undefined;
+    }
+    mapOperationError(error) {
+        const selection = this.selection;
+        const code = error.message.match(/\b(E[A-Z]+)\b/)?.[1];
+        if (!selection || !code || !FILESYSTEM_CODES.has(code) || !error.message.includes(selection.path))
+            return error;
+        return this.failure(selection, { code });
+    }
+    async check(selection) {
+        try {
+            await this.probe(selection.path);
+        }
+        catch (error) {
+            throw this.failure(selection, error);
+        }
+    }
+    async probe(path$1) {
+        const contexts = path.join(path$1, 'contexts');
+        await promises.mkdir(contexts, { recursive: true, mode: 0o700 });
+        const probe = path.join(contexts, '.sdk-write-' + node_crypto.randomUUID());
+        const handle = await promises.open(probe, 'wx', 0o600);
+        try {
+            await handle.writeFile('state');
+        }
+        finally {
+            await handle.close();
+            await promises.rm(probe, { force: true });
+        }
+    }
+    failure(selection, error) {
+        const fsCode = error?.code;
+        return new errors.SuperDocCliError('SuperDoc state directory is not writable: ' +
+            selection.path +
+            '. Configure stateDir or SUPERDOC_CLI_STATE_DIR with a writable directory.', {
+            code: 'STATE_DIRECTORY_UNWRITABLE',
+            details: {
+                path: selection.path,
+                source: selection.source,
+                fsCode,
+                remediation: 'Configure stateDir or SUPERDOC_CLI_STATE_DIR with a writable directory.',
+            },
+        });
+    }
+}
+
+exports.SdkStateDirectory = SdkStateDirectory;

package/dist/runtime/state-directory.d.ts

@@ -0,0 +1,14 @@
+import { SuperDocCliError } from './errors.js';
+export declare class SdkStateDirectory {
+    private readonly configured;
+    private selection;
+    constructor(configured: string | undefined);
+    get path(): string | undefined;
+    get ownsRoot(): boolean;
+    prepare(env: NodeJS.ProcessEnv): Promise<string>;
+    dispose(): Promise<void>;
+    mapOperationError(error: SuperDocCliError): SuperDocCliError;
+    private check;
+    private probe;
+    private failure;
+}

package/dist/runtime/state-directory.js

@@ -0,0 +1,127 @@
+import { mkdir, mkdtemp, open, rm, stat } from 'node:fs/promises';
+import { tmpdir, userInfo } from 'node:os';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { SuperDocCliError } from './errors.js';
+const FILESYSTEM_CODES = new Set(['EACCES', 'EPERM', 'EROFS', 'ENOSPC', 'EDQUOT', 'ENOTDIR', 'ENOENT']);
+export class SdkStateDirectory {
+    configured;
+    selection;
+    constructor(configured) {
+        this.configured = configured;
+    }
+    get path() {
+        return this.selection?.path;
+    }
+    get ownsRoot() {
+        return this.selection?.owned === true;
+    }
+    async prepare(env) {
+        if (this.configured !== undefined && (typeof this.configured !== 'string' || !this.configured.trim())) {
+            throw new SuperDocCliError('stateDir must be a non-empty path.', { code: 'INVALID_ARGUMENT' });
+        }
+        if (this.selection) {
+            await this.check(this.selection);
+            return this.selection.path;
+        }
+        const explicit = this.configured ?? (env.SUPERDOC_CLI_STATE_DIR || undefined);
+        if (explicit !== undefined) {
+            const selection = {
+                path: resolve(explicit),
+                source: this.configured !== undefined ? 'stateDir' : 'SUPERDOC_CLI_STATE_DIR',
+                owned: false,
+            };
+            await this.check(selection);
+            this.selection = selection;
+            return selection.path;
+        }
+        let home = process.platform === 'win32' ? env.USERPROFILE : env.HOME;
+        if (!home) {
+            try {
+                home = userInfo().homedir;
+            }
+            catch {
+                /* A container UID need not have a passwd entry. */
+            }
+        }
+        if (home) {
+            const selection = { path: join(home, '.superdoc-cli', 'state', 'v1'), source: 'home', owned: false };
+            try {
+                if ((await stat(home)).isDirectory()) {
+                    await this.probe(selection.path);
+                    this.selection = selection;
+                    return selection.path;
+                }
+            }
+            catch {
+                /* An unusable implicit home may use private temporary state. */
+            }
+        }
+        const temporary = process.platform === 'win32'
+            ? env.TEMP || env.TMP || (env.SystemRoot ? join(env.SystemRoot, 'temp') : tmpdir())
+            : env.TMPDIR || env.TMP || env.TEMP || '/tmp';
+        let allocated;
+        try {
+            allocated = await mkdtemp(join(resolve(temporary), 'superdoc-sdk-state-'));
+            const selection = { path: allocated, source: 'temporary', owned: true };
+            await this.probe(allocated);
+            this.selection = selection;
+            return allocated;
+        }
+        catch (error) {
+            if (allocated)
+                await rm(allocated, { recursive: true, force: true });
+            throw this.failure({ path: resolve(temporary), source: 'temporary', owned: false }, error);
+        }
+    }
+    async dispose() {
+        const selection = this.selection;
+        if (!selection)
+            return;
+        if (selection.owned)
+            await rm(selection.path, { recursive: true, force: true });
+        this.selection = undefined;
+    }
+    mapOperationError(error) {
+        const selection = this.selection;
+        const code = error.message.match(/\b(E[A-Z]+)\b/)?.[1];
+        if (!selection || !code || !FILESYSTEM_CODES.has(code) || !error.message.includes(selection.path))
+            return error;
+        return this.failure(selection, { code });
+    }
+    async check(selection) {
+        try {
+            await this.probe(selection.path);
+        }
+        catch (error) {
+            throw this.failure(selection, error);
+        }
+    }
+    async probe(path) {
+        const contexts = join(path, 'contexts');
+        await mkdir(contexts, { recursive: true, mode: 0o700 });
+        const probe = join(contexts, '.sdk-write-' + randomUUID());
+        const handle = await open(probe, 'wx', 0o600);
+        try {
+            await handle.writeFile('state');
+        }
+        finally {
+            await handle.close();
+            await rm(probe, { force: true });
+        }
+    }
+    failure(selection, error) {
+        const fsCode = error?.code;
+        return new SuperDocCliError('SuperDoc state directory is not writable: ' +
+            selection.path +
+            '. Configure stateDir or SUPERDOC_CLI_STATE_DIR with a writable directory.', {
+            code: 'STATE_DIRECTORY_UNWRITABLE',
+            details: {
+                path: selection.path,
+                source: selection.source,
+                fsCode,
+                remediation: 'Configure stateDir or SUPERDOC_CLI_STATE_DIR with a writable directory.',
+            },
+        });
+    }
+}

package/dist/runtime/transport-common.d.ts

@@ -45,6 +45,8 @@ export interface UserIdentity {
     email?: string;
 }
 export interface SuperDocClientOptions {
+    /** Writable host state root. Takes precedence over SUPERDOC_CLI_STATE_DIR; persists after disposal. */
+    stateDir?: string;
     env?: Record<string, string | undefined>;
     /**
      * Standalone document-host entry to use instead of the embedded CLI.