@khorsheed/dsh-local-agent 0.1.0-rc.6

package/lib/types/member-bridge.js

@@ -0,0 +1,216 @@
+/**
+ * Member bridge: a minimal standalone MCP server (stdio, newline-delimited
+ * JSON-RPC) exposing member messaging and room coordination tools to the CLI
+ * member that spawned it. Each call is forwarded to the host's member-channel
+ * listener over the loopback socket named by `DSH_MEMBER_SOCKET`,
+ * authenticated by the per-run token in `DSH_MEMBER_TOKEN`; the host's
+ * receipt is the tool result verbatim.
+ *
+ * The process is dependency-free (node builtins only) because the CLI spawns
+ * it bare: `node <this file>`, with the socket path and token in its
+ * environment (written into the CLI's scoped MCP config by the provider).
+ * Covers the MCP handshake subset a client needs: `initialize`,
+ * `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
+ * @module @khorsheed/dsh-local-agent/member-bridge
+ */
+import { createInterface } from 'node:readline';
+import { connect } from 'node:net';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from './types.js';
+/** The one tool this server exposes. */
+export const MEMBER_MESSAGE_TOOL = 'member_message';
+const TOOL_DESCRIPTION = [
+    'Notify another CLI member of this room/session group (member-to-member message).',
+    '`to` is the target member\'s dsh child session id (or a member name when a room manages the group).',
+    'The delivery receipt is returned verbatim: sent / pending-confirm / busy / an error reason.',
+].join(' ');
+const TOOL_SCHEMA = {
+    type: 'object',
+    properties: {
+        to: { type: 'string', description: 'The target member\'s child session id (or room-roster name).' },
+        text: { type: 'string', description: 'The notification text, delivered with your provenance.' },
+    },
+    required: ['to', 'text'],
+    additionalProperties: false,
+};
+const ROOM_TOOLS = [
+    { name: 'room_plan', description: 'Manage a formal goal with stages, dependent tasks and evidence review. Read room_read for plan state and the command contract. Ordinary small work uses room_message. Workers may submit only their own current attempt.',
+        inputSchema: { type: 'object', properties: { command: { type: 'string', description: 'JSON command with action, requestId and expectedRevision; see room_read planCommands.' } }, required: ['command'], additionalProperties: false } },
+    { name: 'room_read', description: 'Read your room roster, coordinator, deliveries, recent outcomes and available harness providers. Identity comes from the host.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { name: 'room_invite', description: 'Coordinator only: invite a member. An optional firstTask starts in the background and returns its result to you automatically.',
+        inputSchema: { type: 'object', properties: {
+                provider: { type: 'string' }, name: { type: 'string' }, instructions: { type: 'string' },
+                cwd: { type: 'string' }, model: { type: 'string' }, firstTask: { type: 'string' },
+            }, required: ['provider', 'name'], additionalProperties: false } },
+    { name: 'room_message', description: 'Coordinator only: dispatch background work to a room member by name. Returns acceptance immediately; completion arrives as a correlated report. Do not poll.',
+        inputSchema: { type: 'object', properties: { member: { type: 'string' }, text: { type: 'string' } }, required: ['member', 'text'], additionalProperties: false } },
+];
+export async function callRoomCommand(env, name, args) {
+    if (env.socket === undefined || env.token === undefined)
+        return toolText('member channel is not configured for this run', true);
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return toolText('Room tool arguments must be an object', true);
+    try {
+        const outcome = await callHost(env.socket, { token: env.token, command: { name, arguments: args } });
+        return toolText(outcome.ok ? outcome.receipt ?? 'accepted' : outcome.error ?? 'Room command rejected', !outcome.ok);
+    }
+    catch (error) {
+        return toolText(`Room command unavailable: ${String(error)}`, true);
+    }
+}
+/** One socket round trip: send the request line, read the one-line response. */
+function callHost(socket, payload) {
+    return new Promise((resolve, reject) => {
+        const connection = connect(socket);
+        let buffer = '';
+        connection.on('connect', () => {
+            connection.write(`${JSON.stringify(payload)}\n`);
+        });
+        connection.on('data', (chunk) => {
+            buffer += chunk.toString();
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            connection.end();
+            try {
+                resolve(JSON.parse(buffer.slice(0, newline)));
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        connection.on('error', reject);
+    });
+}
+/** A successful MCP tool result carrying the receipt text. */
+function toolText(text, isError = false) {
+    return { content: [{ type: 'text', text }], isError };
+}
+/**
+ * Handle one `member_message` tool call: forward to the host listener and map
+ * the outcome to a tool result. Channel failures (missing env, unreachable
+ * listener, rejected token) are tool errors; delivery verdicts are text.
+ * @param env - the bridge's environment (socket, token).
+ * @param args - the tool arguments (`to`, `text`).
+ * @returns the MCP tool result object.
+ */
+export async function callMemberMessage(env, args) {
+    if (env.socket === undefined || env.token === undefined) {
+        return toolText('member channel is not configured for this run (missing socket/token environment)', true);
+    }
+    if (typeof args.to !== 'string' || typeof args.text !== 'string') {
+        return toolText('member_message requires string arguments `to` and `text`', true);
+    }
+    try {
+        const outcome = await callHost(env.socket, {
+            token: env.token,
+            to: args.to,
+            text: args.text,
+        });
+        if (outcome.ok)
+            return toolText(outcome.receipt ?? 'sent');
+        return toolText(outcome.error ?? 'member channel rejected the message', true);
+    }
+    catch (error) {
+        return toolText(`member channel unavailable: ${error instanceof Error ? error.message : String(error)}`, true);
+    }
+}
+/**
+ * Run the stdio JSON-RPC loop over the given streams (injectable for tests).
+ * Unknown methods with an id get a MethodNotFound error; notifications are
+ * ignored. Never throws — a malformed line is answered with a parse error and
+ * the loop continues.
+ * @param env - the bridge's environment.
+ * @param input - the stdin side.
+ * @param output - the stdout side.
+ */
+export function serveMemberBridge(env, input, output) {
+    const write = (message) => {
+        output.write(`${JSON.stringify(message)}\n`);
+    };
+    const lines = createInterface({ input, terminal: false });
+    lines.on('line', (line) => {
+        if (line.trim() === '')
+            return;
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+            return;
+        }
+        const id = request.id;
+        switch (request.method) {
+            case 'initialize': {
+                const params = request.params;
+                write({
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    result: {
+                        protocolVersion: params?.protocolVersion ?? '2024-11-05',
+                        capabilities: { tools: {} },
+                        serverInfo: { name: 'dsh-member-bridge', version: '0.1.0' },
+                    },
+                });
+                return;
+            }
+            case 'ping':
+                write({ jsonrpc: '2.0', id: id ?? null, result: {} });
+                return;
+            case 'tools/list':
+                write({
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    result: {
+                        tools: [{
+                                name: MEMBER_MESSAGE_TOOL,
+                                description: TOOL_DESCRIPTION,
+                                inputSchema: TOOL_SCHEMA,
+                            }, ...ROOM_TOOLS],
+                    },
+                });
+                return;
+            case 'tools/call': {
+                const params = request.params;
+                if (ROOM_TOOLS.some(tool => tool.name === params?.name)) {
+                    void callRoomCommand(env, params.name, params.arguments ?? {}).then(result => write({ jsonrpc: '2.0', id: id ?? null, result }));
+                    return;
+                }
+                if (params?.name !== MEMBER_MESSAGE_TOOL) {
+                    write({ jsonrpc: '2.0', id: id ?? null, error: { code: -32602, message: `unknown tool ${String(params?.name)}` } });
+                    return;
+                }
+                void callMemberMessage(env, params.arguments ?? {}).then((result) => {
+                    write({ jsonrpc: '2.0', id: id ?? null, result });
+                });
+                return;
+            }
+            default:
+                // Notifications (no id) — e.g. notifications/initialized — get no reply.
+                if (id !== undefined) {
+                    write({ jsonrpc: '2.0', id, error: { code: -32601, message: `method not found: ${String(request.method)}` } });
+                }
+        }
+    });
+}
+/** True when this file is the process entry (`node member-bridge.js`). */
+function isMain() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    serveMemberBridge({
+        socket: process.env[MEMBER_BRIDGE_SOCKET_ENV],
+        token: process.env[MEMBER_BRIDGE_TOKEN_ENV],
+    }, process.stdin, process.stdout);
+}

package/lib/types/member-channel.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Member channel, host side: the loopback listener the bridge MCP servers call
+ * back on, and the member-to-member delivery chain. One newline-delimited JSON
+ * request per line (`{ token, to, text }`), one response line
+ * (`{ ok: true, receipt } | { ok: false, error }`).
+ *
+ * Delivery chain for one `member_message` call:
+ *
+ * 1. token → the registered in-flight run (sender A's identity; never
+ *    self-reported). The per-run token is the SOLE credential (host 0.1.5
+ *    removed the child pid the parentage cross-check used): minted at run
+ *    start, delivered through the CLI's scoped MCP config (0700 scoped home),
+ *    invalidated the moment the run settles. The residual exposure — a
+ *    same-host same-user sibling CLI replaying a token it read — is
+ *    documented in the package README and tracked by the auth-hardening
+ *    proposal;
+ * 2. resolve B (`to` = a member's dsh child session id; member NAMES resolve
+ *    only through a claiming room's roster);
+ * 3. same-parent check: B's delegation must share A's parent session;
+ * 4. gate handoff: probe `ctx.get('room')` for the duck-typed
+ *    {@link RoomMemberMessageGate} (NO import of any room package — room
+ *    absent or declining is invisible); a claiming room owns the dispatch and
+ *    its receipt passes back verbatim;
+ * 5. room absent/declining → family direct-send: B's resume lock busy →
+ *    `busy`; else the facade `resume` with a provenance-tagged prompt.
+ * @module @khorsheed/dsh-local-agent/member-channel
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { LocalAgentRegistry } from './index.ts';
+import type { MemberRoomCommand, MemberMessageOutcome } from './types.ts';
+/** One bridge callback on the wire. */
+export interface MemberBridgeRequest {
+    /** The per-run token injected into the bridge's environment (the sole credential). */
+    token: string;
+    /** The raw `to` argument: a member child session id, or a room-roster name. */
+    to: string;
+    /** The notification text. */
+    text: string;
+}
+export interface MemberCommandBridgeRequest {
+    token: string;
+    command: MemberRoomCommand;
+}
+/**
+ * The member-channel host: owns the loopback unix-socket listener and the
+ * delivery chain. Mounted by the plugin's `apply` and disposed with its fiber.
+ */
+export declare class MemberChannel {
+    private readonly ctx;
+    private readonly registry;
+    private readonly socketPath;
+    private server;
+    constructor(ctx: Context, registry: LocalAgentRegistry, socketPath: string);
+    /**
+     * Start listening. A listener failure (e.g. a socket path beyond the
+     * platform limit) degrades the whole member channel to absent — the run
+     * itself is never at risk, so this warns instead of throwing.
+     */
+    start(): Promise<void>;
+    /** Close the listener and remove the socket file. */
+    dispose(): Promise<void>;
+    /** Serve one bridge connection: newline-delimited JSON request lines. */
+    private serve;
+    /** Handle one raw request line and write the one-line response. */
+    private answer;
+    /**
+     * The delivery chain documented in the module header. Exposed for tests and
+     * for the listener loop; never throws — every failure is a structured
+     * outcome.
+     * @param request - the bridge callback.
+     * @returns the delivery outcome.
+     */
+    handle(request: MemberBridgeRequest | MemberCommandBridgeRequest): Promise<MemberMessageOutcome>;
+    /** Probe the optional room gate without importing any room package. */
+    private probeRoom;
+    /**
+     * Offer the notification to the room gate. A returned receipt means room
+     * owns the dispatch (passed back verbatim); a THROW declines (the parent
+     * session is not a room this instance manages) and the family path
+     * continues. The message is the frozen contract: `from`/`to` as plain
+     * strings (the sender's child session id; room resolves roster names),
+     * the delegation view as provenance.
+     */
+    private handToGate;
+}
+//# sourceMappingURL=member-channel.d.ts.map

package/lib/types/member-channel.js

@@ -0,0 +1,232 @@
+/**
+ * Member channel, host side: the loopback listener the bridge MCP servers call
+ * back on, and the member-to-member delivery chain. One newline-delimited JSON
+ * request per line (`{ token, to, text }`), one response line
+ * (`{ ok: true, receipt } | { ok: false, error }`).
+ *
+ * Delivery chain for one `member_message` call:
+ *
+ * 1. token → the registered in-flight run (sender A's identity; never
+ *    self-reported). The per-run token is the SOLE credential (host 0.1.5
+ *    removed the child pid the parentage cross-check used): minted at run
+ *    start, delivered through the CLI's scoped MCP config (0700 scoped home),
+ *    invalidated the moment the run settles. The residual exposure — a
+ *    same-host same-user sibling CLI replaying a token it read — is
+ *    documented in the package README and tracked by the auth-hardening
+ *    proposal;
+ * 2. resolve B (`to` = a member's dsh child session id; member NAMES resolve
+ *    only through a claiming room's roster);
+ * 3. same-parent check: B's delegation must share A's parent session;
+ * 4. gate handoff: probe `ctx.get('room')` for the duck-typed
+ *    {@link RoomMemberMessageGate} (NO import of any room package — room
+ *    absent or declining is invisible); a claiming room owns the dispatch and
+ *    its receipt passes back verbatim;
+ * 5. room absent/declining → family direct-send: B's resume lock busy →
+ *    `busy`; else the facade `resume` with a provenance-tagged prompt.
+ * @module @khorsheed/dsh-local-agent/member-channel
+ */
+import { createServer } from 'node:net';
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * The member-channel host: owns the loopback unix-socket listener and the
+ * delivery chain. Mounted by the plugin's `apply` and disposed with its fiber.
+ */
+export class MemberChannel {
+    ctx;
+    registry;
+    socketPath;
+    server;
+    constructor(ctx, registry, socketPath) {
+        this.ctx = ctx;
+        this.registry = registry;
+        this.socketPath = socketPath;
+    }
+    /**
+     * Start listening. A listener failure (e.g. a socket path beyond the
+     * platform limit) degrades the whole member channel to absent — the run
+     * itself is never at risk, so this warns instead of throwing.
+     */
+    async start() {
+        try {
+            mkdirSync(dirname(this.socketPath), { recursive: true });
+            // A stale socket from a crashed host is safe to replace: the path is
+            // per-homes-root, and only this plugin instance binds it.
+            rmSync(this.socketPath, { force: true });
+            const server = createServer((socket) => { this.serve(socket); });
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(this.socketPath, () => { resolve(); });
+            });
+            server.removeAllListeners('error');
+            this.server = server;
+            this.registry.setMemberBridgeAvailable(true);
+        }
+        catch (error) {
+            this.ctx.logger.warn(`localAgent: member channel listener unavailable (${error instanceof Error ? error.message : String(error)}); member_message calls will fail`);
+        }
+    }
+    /** Close the listener and remove the socket file. */
+    async dispose() {
+        const server = this.server;
+        this.server = undefined;
+        this.registry.setMemberBridgeAvailable(false);
+        if (server === undefined)
+            return;
+        await new Promise((resolve) => { server.close(() => { resolve(); }); });
+        rmSync(this.socketPath, { force: true });
+    }
+    /** Serve one bridge connection: newline-delimited JSON request lines. */
+    serve(socket) {
+        let buffer = '';
+        socket.on('data', (chunk) => {
+            buffer += chunk.toString();
+            for (;;) {
+                const newline = buffer.indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                if (line.trim() === '')
+                    continue;
+                void this.answer(socket, line);
+            }
+        });
+        socket.on('error', () => { });
+    }
+    /** Handle one raw request line and write the one-line response. */
+    async answer(socket, line) {
+        let outcome;
+        try {
+            outcome = await this.handle(JSON.parse(line));
+        }
+        catch (error) {
+            outcome = { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        if (!socket.destroyed)
+            socket.end(`${JSON.stringify(outcome)}\n`);
+    }
+    /**
+     * The delivery chain documented in the module header. Exposed for tests and
+     * for the listener loop; never throws — every failure is a structured
+     * outcome.
+     * @param request - the bridge callback.
+     * @returns the delivery outcome.
+     */
+    async handle(request) {
+        if (request === null || typeof request !== 'object' || typeof request.token !== 'string')
+            return { ok: false, error: 'Malformed member bridge request' };
+        const run = this.registry.resolveMemberRun(request.token);
+        if (run === undefined) {
+            return { ok: false, error: 'localAgent: unknown or expired member token' };
+        }
+        if ('command' in request) {
+            const room = this.probeRoom();
+            if (room?.receiveMemberCommand === undefined)
+                return { ok: false, error: 'Room coordination tools are unavailable' };
+            try {
+                const round = this.registry.memberConfiguration(run.childSessionId).round;
+                if (round === undefined || round.id.startsWith('prepare:'))
+                    return { ok: false, error: 'Room commands require an active member turn' };
+                return await room.receiveMemberCommand(run, request.command);
+            }
+            catch (error) {
+                return { ok: false, error: String(error) };
+            }
+        }
+        if (typeof request.to !== 'string' || typeof request.text !== 'string' || request.text.trim() === '')
+            return { ok: false, error: 'member_message requires a target and non-empty text' };
+        const harness = this.registry.list()
+            .map(name => this.registry.get(name))
+            .find(candidate => candidate?.delegationProvider === run.provider);
+        const from = {
+            childSessionId: run.childSessionId,
+            provider: run.provider,
+            parentSessionId: run.parentSessionId,
+            ...harness === undefined ? {} : { harnessDisplayName: harness.displayName },
+        };
+        const room = this.probeRoom();
+        const target = this.registry.getDelegation(request.to);
+        if (target === undefined) {
+            // The family registry cannot resolve B — a member NAME resolves only
+            // through room's roster, so the gate gets the raw argument first.
+            if (room !== undefined) {
+                const handed = await this.handToGate(room, from, request);
+                if (handed !== undefined)
+                    return handed;
+            }
+            return { ok: false, error: `localAgent: unknown member ${JSON.stringify(request.to)} (room absent: pass the member's child session id)` };
+        }
+        if (target.parentSessionId !== run.parentSessionId) {
+            return { ok: false, error: `localAgent: member ${request.to} belongs to another parent session; cross-room notification is rejected` };
+        }
+        if (room !== undefined) {
+            const handed = await this.handToGate(room, from, request);
+            if (handed !== undefined)
+                return handed;
+        }
+        // Family direct-send: the resume lock doubles as the busy signal.
+        if (this.registry.isResumeLocked(target.childSessionId) && !this.registry.supportsMemberConfiguration(target.provider)) {
+            return { ok: true, receipt: 'busy' };
+        }
+        const label = from.harnessDisplayName ?? from.provider;
+        try {
+            await this.registry.resume(target.parentSessionId, target.provider, target.childSessionId, [{
+                    type: 'text',
+                    text: `成员 ${label}（会话 ${from.childSessionId}）转告：\n${request.text}\n\n（回复请调用 member_message 工具，to 填 "${from.childSessionId}"）`,
+                }]);
+        }
+        catch (error) {
+            return { ok: true, receipt: `error: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        return { ok: true, receipt: 'sent' };
+    }
+    /** Probe the optional room gate without importing any room package. */
+    probeRoom() {
+        const room = this.ctx.get.call(this.ctx, 'room');
+        if (typeof room !== 'object' || room === null)
+            return undefined;
+        const gate = room;
+        return typeof gate.receiveMemberMessage === 'function' ? gate : undefined;
+    }
+    /**
+     * Offer the notification to the room gate. A returned receipt means room
+     * owns the dispatch (passed back verbatim); a THROW declines (the parent
+     * session is not a room this instance manages) and the family path
+     * continues. The message is the frozen contract: `from`/`to` as plain
+     * strings (the sender's child session id; room resolves roster names),
+     * the delegation view as provenance.
+     */
+    async handToGate(room, from, request) {
+        const message = {
+            from: from.childSessionId,
+            to: request.to,
+            content: request.text,
+            parentSessionId: from.parentSessionId,
+            provenance: {
+                childSessionId: from.childSessionId,
+                provider: from.provider,
+                parentSessionId: from.parentSessionId,
+                ...from.harnessDisplayName === undefined ? {} : { harnessDisplayName: from.harnessDisplayName },
+            },
+        };
+        let ownsRoom = false;
+        try {
+            if (room.isRoom !== undefined) {
+                ownsRoom = true; // An unreadable ownership check also fails closed.
+                if (!await room.isRoom({ sessionId: from.parentSessionId }))
+                    return undefined;
+            }
+            const receipt = await room.receiveMemberMessage(message);
+            return { ok: true, receipt };
+        }
+        catch (error) {
+            if (ownsRoom)
+                return { ok: false, error: `Room rejected member message: ${String(error)}` };
+            // Legacy gates have no ownership probe; preserve their decline contract. The family
+            // direct-sends.
+            this.ctx.logger.warn(`localAgent: room gate declined (${error instanceof Error ? error.message : String(error)}); direct-sending the member message`);
+            return undefined;
+        }
+    }
+}

package/lib/types/member-control-storage.d.ts

@@ -0,0 +1,10 @@
+import type { MemberControlRecord, MemberControlStorage } from './member-control.ts';
+/** Per-member atomic files; acknowledgement requires a flushed file and rename. */
+export declare class FileMemberControlStorage implements MemberControlStorage {
+    private readonly directory;
+    constructor(directory: string);
+    private path;
+    read(memberId: string): MemberControlRecord | undefined;
+    write(memberId: string, record: MemberControlRecord): void;
+}
+//# sourceMappingURL=member-control-storage.d.ts.map

package/lib/types/member-control-storage.js

@@ -0,0 +1,100 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const revision = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const optionalString = (value) => value === undefined || typeof value === 'string';
+const choice = (value) => object(value) && (value['mode'] === 'inherit' || value['mode'] === 'default'
+    || (value['mode'] === 'value' && typeof value['value'] === 'string' && value['value'].trim() !== ''));
+const selection = (value) => object(value) && choice(value['model']) && choice(value['effort']);
+const resolved = (value) => object(value) && optionalString(value['model']) && optionalString(value['effort']);
+const applied = (value) => object(value) && revision(value['revision']) && selection(value['selection']) && resolved(value['resolved']);
+const pending = (value) => object(value) && revision(value['revision']) && typeof value['requestId'] === 'string'
+    && (value['kind'] === 'selection' || value['kind'] === 'cancel') && selection(value['selection']);
+const states = new Set(['idle', 'pending', 'applying', 'reconciling', 'failed']);
+const receipts = new Set(['pending', 'applying', 'applied', 'cancelled', 'failed', 'conflict', 'locked', 'unsupported']);
+/** Fail closed for malformed recovery state; never silently turn it into defaults. */
+function parseRecord(value) {
+    if (!object(value) || value['version'] !== 1 || !object(value['state']) || !object(value['requests']))
+        throw new Error('Invalid member control file');
+    const state = value['state'];
+    const operation = state['operation'];
+    const round = state['round'];
+    if (typeof state['memberId'] !== 'string' || !revision(state['revision']) || !applied(state['current'])
+        || (state['frozen'] !== undefined && (!applied(state['frozen']) || typeof state['lockedReason'] !== 'string'))
+        || (state['pending'] !== undefined && !pending(state['pending']))
+        || (operation !== undefined && (!object(operation) || !pending(operation) || !applied(operation['previous'])))
+        || (round !== undefined && (!object(round) || typeof round['id'] !== 'string' || !applied(round['configuration'])))
+        || typeof state['status'] !== 'string' || !states.has(state['status'])
+        || !optionalString(state['error']) || !optionalString(state['lockedReason']))
+        throw new Error('Invalid member control state');
+    for (const [id, request] of Object.entries(value['requests'])) {
+        if (!object(request) || typeof request['signature'] !== 'string' || !object(request['receipt']))
+            throw new Error('Invalid member control receipt');
+        const receipt = request['receipt'];
+        if (receipt['requestId'] !== id || !revision(receipt['revision']) || typeof receipt['status'] !== 'string'
+            || !receipts.has(receipt['status']) || !optionalString(receipt['error']))
+            throw new Error('Invalid member control receipt');
+    }
+    return { state, requests: value['requests'] };
+}
+/** Per-member atomic files; acknowledgement requires a flushed file and rename. */
+export class FileMemberControlStorage {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    path(memberId) { return join(this.directory, createHash('sha256').update(memberId).digest('hex') + '.json'); }
+    read(memberId) {
+        let text;
+        try {
+            text = readFileSync(this.path(memberId), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw new Error('Persisted member controls could not be read', { cause: error });
+        }
+        const record = parseRecord(JSON.parse(text));
+        const state = record.state;
+        if (state.memberId !== memberId || state.current.revision > state.revision
+            || (state.frozen !== undefined && state.frozen.revision > state.revision)
+            || (state.pending !== undefined && (state.pending.revision > state.revision || !Object.hasOwn(record.requests, state.pending.requestId)))
+            || (state.operation !== undefined && (state.operation.revision > state.revision || !Object.hasOwn(record.requests, state.operation.requestId)))
+            || (state.round !== undefined && state.round.configuration.revision > state.revision)) {
+            throw new Error('Persisted member controls are inconsistent; admission is blocked');
+        }
+        return { state, requests: record.requests };
+    }
+    write(memberId, record) {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const path = this.path(memberId);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        let fd;
+        try {
+            fd = openSync(temporary, 'wx', 0o600);
+            writeFileSync(fd, JSON.stringify({ version: 1, ...record }) + '\n', 'utf8');
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            renameSync(temporary, path);
+            // Windows does not expose directory fsync through this API. The file
+            // itself is flushed on every platform before the atomic replacement.
+            if (process.platform !== 'win32') {
+                fd = openSync(this.directory, 'r');
+                fsyncSync(fd);
+            }
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            try {
+                unlinkSync(temporary);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+}