@ai-workbench/remote-agent 0.8.2 → 0.8.10

package/dist/employee-endpoint.js

@@ -0,0 +1,141 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { sameTarget, unwrap } from "./provider.js";
+import { NeedError, shellQuote } from "./remote.js";
+const fail = (code = 'EMPLOYEE_CONTEXT_CHANGED') => new NeedError(code, '本机工作区或连接已改变，原工具已停止；没有改在主机执行。', '当前L本地绑定与N/S同代员工端点');
+const uuid = (value) => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
+function clean(value) { return typeof value === 'string' && !!value && !/[\x00-\x1f\x7f]/.test(value); }
+export function endpointArguments(target) {
+    return ['--settings', target.bridge.settingsPath, '--device', target.endpoint.deviceId, '--if-instance', target.bridge.bridgeInstanceId, '--if-generation', String(target.bridge.generation), '--if-endpoint', target.endpoint.endpointInstanceId, '--if-context', target.endpoint.executionContextId];
+}
+export function endpointCommand(target) { return [target.bridge.command, 'target', ...endpointArguments(target)].map(shellQuote).join(' '); }
+export function verifyEmployeeTarget(target, request, directory, host) {
+    if (target?.version !== 1 || !target.local || !target.endpoint || !target.bridge || target.local.instanceId !== request.instanceId || target.local.epoch !== request.epoch || target.local.workspaceId !== request.workspaceId || target.local.bindingId !== request.expectedBindingId || !isDeepStrictEqual(target.local.directory, directory))
+        throw fail();
+    const e = target.endpoint, b = target.bridge;
+    if (!/^[a-f0-9]{64}$/.test(e.deviceId) || ![e.endpointInstanceId, e.executionContextId, b.bridgeInstanceId].every(uuid) || !Number.isSafeInteger(b.generation) || b.generation < 1 || b.protocolVersion !== 1 || b.command !== '/usr/local/aw-host/bin/aw-employee-bridge' || b.settingsPath !== host.session.settingsPath || ![e.remoteUser, e.remoteHome, e.endpointCwd, e.endpointShell].every(clean) || !e.remoteHome.startsWith('/') || !e.endpointCwd.startsWith('/') || !e.endpointShell.startsWith('/') || e.remoteUid !== process.getuid?.() || process.getuid?.() !== process.geteuid?.() || e.remoteUid < 1)
+        throw fail('EMPLOYEE_TARGET_INVALID');
+}
+export function verifyBridgeTarget(value, expected) {
+    const raw = value;
+    if (!raw || raw.type !== 'target' || raw.protocolVersion !== 1 || !raw.endpoint || raw.endpoint.state !== 'online' || !Array.isArray(raw.sshArgs) || !raw.sshArgs.length || raw.sshArgs.some(x => typeof x !== 'string' || x.includes('\0')))
+        throw fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID');
+    const endpoint = raw.endpoint;
+    for (const [field, value] of Object.entries({ ...expected.endpoint, bridgeInstanceId: expected.bridge.bridgeInstanceId, generation: expected.bridge.generation })) {
+        // N's shell/cwd are confirmed by ready; all public identity and execution facts must match.
+        if (endpoint[field] !== value)
+            throw fail();
+    }
+    return { sshArgs: raw.sshArgs };
+}
+export async function openEmployeeLease(options, initialSignal) {
+    initialSignal?.throwIfAborted();
+    const api = options.getConnect(), network = options.getNetwork(), lifetime = new AbortController(), offs = [];
+    if (!api || api.getContractInfo().localWorkspaceContext !== 1 || api.getContractInfo().workspaceLocations !== 1 || !api.getLocalWorkspaceContext || !api.getWorkspaceLocationState || !api.onWorkspaceLocationState)
+        throw fail('EMPLOYEE_CONTEXT_UNAVAILABLE');
+    if (!network || typeof network.prepareEmployeeEndpoint !== 'function' || typeof network.onState !== 'function')
+        throw fail('EMPLOYEE_ENDPOINT_UNAVAILABLE');
+    const workspace = await options.readWorkspace(), connection = api.getConnectionState(), state = api.getWorkspaceLocationState();
+    const items = state.items.filter(x => x.workspaceId === workspace.workspaceId);
+    if (connection.phase !== 'connected' || state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch || items.length !== 1 || items[0].source !== 'local' || items[0].status !== 'selected' || !items[0].bindingId)
+        throw fail();
+    const request = { instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.workspaceId, expectedBindingId: items[0].bindingId };
+    let target, closed = false, diagnosticFailure;
+    const invalidate = (code) => { if (lifetime.signal.aborted)
+        return; try {
+        options.detail({ kind: 'session', severity: 'warning', code: 'CLAUDE_EMPLOYEE_REVOKED', summary: '本机旧绑定已停止派发，在途结果按实际确认；不会重放', payload: { reason: code, workspaceId: request.workspaceId, bindingId: request.expectedBindingId } });
+    }
+    catch (error) {
+        diagnosticFailure ??= error;
+    }
+    finally {
+        lifetime.abort(diagnosticFailure ?? fail(code));
+    } };
+    const current = () => {
+        if (options.getConnect() !== api || options.getNetwork() !== network)
+            throw fail();
+        const c = api.getConnectionState(), s = api.getWorkspaceLocationState(), matches = s.items.filter(x => x.workspaceId === request.workspaceId);
+        if (c.phase !== 'connected' || c.instanceId !== request.instanceId || c.epoch !== request.epoch || s.phase !== 'ready' || s.instanceId !== request.instanceId || s.epoch !== request.epoch || matches.length !== 1 || matches[0].source !== 'local' || matches[0].status !== 'selected' || matches[0].bindingId !== request.expectedBindingId || network.getState().phase !== 'online')
+            throw fail();
+        lifetime.signal.throwIfAborted();
+    };
+    const changed = () => { try {
+        current();
+    }
+    catch {
+        invalidate('EMPLOYEE_CONTEXT_CHANGED');
+    } };
+    offs.push(api.onConnectionState(changed), api.onWorkspaceLocationState(changed), network.onState(event => { if (event?.kind === 'lost' || network.getState().phase !== 'online')
+        invalidate('EMPLOYEE_ENDPOINT_UNAVAILABLE'); }));
+    async function validate(callerSignal) {
+        if (diagnosticFailure)
+            throw diagnosticFailure;
+        callerSignal?.throwIfAborted();
+        const signal = AbortSignal.any([lifetime.signal, ...callerSignal ? [callerSignal] : []]);
+        try {
+            current();
+            const now = await options.readWorkspace();
+            signal.throwIfAborted();
+            current();
+            const stat = await lstat(workspace.directory.path), canonical = await realpath(workspace.directory.path);
+            if (!isDeepStrictEqual(now, workspace) || !stat.isDirectory() || stat.isSymbolicLink() || canonical !== workspace.directory.path || stat.dev !== workspace.directory.device || stat.ino !== workspace.directory.inode)
+                throw fail();
+            const context = unwrap(await api.getLocalWorkspaceContext(request));
+            signal.throwIfAborted();
+            current();
+            if (context.version !== 1 || context.source !== 'local' || context.instanceId !== request.instanceId || context.epoch !== request.epoch || context.workspaceId !== request.workspaceId || context.bindingId !== request.expectedBindingId || !isDeepStrictEqual(context.directory, workspace.directory))
+                throw fail();
+            const prepared = await network.prepareEmployeeEndpoint({ ...request }, signal);
+            signal.throwIfAborted();
+            current();
+            if (!prepared.ok)
+                throw fail(/^[A-Z][A-Z0-9_]*$/.test(prepared.error.code) ? prepared.error.code : 'EMPLOYEE_ENDPOINT_UNAVAILABLE');
+            const next = structuredClone(prepared.value);
+            verifyEmployeeTarget(next, request, workspace.directory, options.host);
+            if (target && !isDeepStrictEqual(next, target))
+                throw fail();
+            const host = unwrap(await api.getSshTarget());
+            if (!sameTarget(host, options.host))
+                throw fail();
+            const raw = await options.control(host, endpointCommand(next), signal);
+            signal.throwIfAborted();
+            current();
+            let result;
+            try {
+                result = JSON.parse(raw);
+            }
+            catch {
+                throw fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID');
+            }
+            verifyBridgeTarget(result, next);
+            const final = await lstat(workspace.directory.path);
+            signal.throwIfAborted();
+            current();
+            if (final.dev !== workspace.directory.device || final.ino !== workspace.directory.inode)
+                throw fail();
+            target ??= next;
+            return structuredClone(target);
+        }
+        catch (error) {
+            if (!callerSignal?.aborted)
+                invalidate(error instanceof NeedError ? error.code : 'EMPLOYEE_CONTEXT_CHANGED');
+            throw error instanceof NeedError || callerSignal?.aborted ? error : fail();
+        }
+    }
+    try {
+        await validate(initialSignal);
+        return { target: structuredClone(target), request: Object.freeze({ ...request }), signal: lifetime.signal, validate, close: async () => { if (!closed) {
+                closed = true;
+                lifetime.abort(fail('EMPLOYEE_EXECUTOR_CLOSED'));
+                for (const off of offs)
+                    off();
+            } if (diagnosticFailure)
+                throw diagnosticFailure; } };
+    }
+    catch (error) {
+        for (const off of offs)
+            off();
+        lifetime.abort();
+        throw error;
+    }
+}

package/dist/employee-exec.d.ts

@@ -0,0 +1,53 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { NeedError } from './remote.ts';
+export type EmployeeMessage = Record<string, unknown>;
+export interface EmployeeExecutionTransport {
+    write(message: EmployeeMessage, signal?: AbortSignal): Promise<void>;
+    read(signal?: AbortSignal): Promise<EmployeeMessage | null>;
+    /** Closing a carrier never proves that an employee command completed. */
+    close(): void | Promise<void>;
+}
+export interface EmployeeExecutionOptions {
+    bindingId: string;
+    acpMaxMessageBytes: number;
+    /** Rechecks the current L CAS/directory/account and N/S five-tuple. No cached permit. */
+    validate(signal: AbortSignal): Promise<void>;
+    /** Once allocation starts, settle only after returning its executor or confirming aborted cleanup. */
+    transport(signal: AbortSignal): Promise<EmployeeExecutionTransport>;
+}
+export interface EmployeeExecutionResult {
+    version: 1;
+    executionId?: string;
+    messages?: EmployeeMessage[];
+    closed?: boolean;
+    result?: 'UNKNOWN';
+}
+/** One immutable workspace binding owns one executor. UNKNOWN is terminal, never replayed. */
+export declare class EmployeeExecution {
+    private readonly options;
+    private readonly lifetime;
+    private executionId?;
+    private io?;
+    private opening;
+    private ended;
+    private error?;
+    private pendingRead;
+    private writeTail;
+    private queuedWriteBytes;
+    private closing;
+    private factoryReceipt;
+    constructor(options: EmployeeExecutionOptions);
+    private parse;
+    private active;
+    private gate;
+    private stop;
+    private closeTransport;
+    invalidate(error?: NeedError): void;
+    private cleanup;
+    dispose(): Promise<void>;
+    handle(params: unknown, signal?: AbortSignal): Promise<EmployeeExecutionResult>;
+    private open;
+    private read;
+}
+/** NDJSON carrier with byte bounds and backpressure derived solely from acpMaxMessageBytes. */
+export declare function createEmployeeProcessTransport(child: ChildProcessWithoutNullStreams, acpMaxMessageBytes: number, stderrCodes?: readonly string[]): EmployeeExecutionTransport;

package/dist/employee-exec.js

@@ -0,0 +1,423 @@
+import { randomUUID } from 'node:crypto';
+import { NeedError } from "./remote.js";
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const need = (code) => new NeedError(code, code === 'ABORTED' ? '员工执行等待已取消，命令结果需另行确认' : '员工执行通道无法继续（' + code + '），未重放请求', '当前员工工作区绑定、N/S端点与实际命令状态');
+const failure = (error) => error instanceof NeedError ? error : need('EMPLOYEE_EXEC_UNKNOWN');
+function capacity(value) { if (!Number.isSafeInteger(value) || value < 1)
+    throw new NeedError('SETTINGS_REQUIRED', '我需要有效的 acpMaxMessageBytes', '管理员确认 acpMaxMessageBytes'); }
+function encoded(message, maxBytes) {
+    if (!object(message))
+        throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+    let json;
+    try {
+        json = JSON.stringify(message);
+    }
+    catch {
+        throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+    }
+    if (Buffer.byteLength(json) > maxBytes)
+        throw need('ACP_MESSAGE_TOO_LARGE');
+    // Freeze this operation's wire value before any async gate can yield.
+    const value = JSON.parse(json);
+    if (!object(value))
+        throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+    return { message: value, line: Buffer.from(json + '\n') };
+}
+function cancelled(signal) { if (signal?.aborted)
+    throw need('ABORTED'); }
+function waiting(operation, signal) {
+    if (signal.aborted) {
+        void operation.catch(() => { });
+        return Promise.reject(need('ABORTED'));
+    }
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener('abort', abort); reject(need('ABORTED')); };
+        signal.addEventListener('abort', abort, { once: true });
+        void operation.then(value => { signal.removeEventListener('abort', abort); resolve(value); }, error => { signal.removeEventListener('abort', abort); reject(error); });
+        if (signal.aborted)
+            abort();
+    });
+}
+/** One immutable workspace binding owns one executor. UNKNOWN is terminal, never replayed. */
+export class EmployeeExecution {
+    options;
+    lifetime = new AbortController();
+    executionId;
+    io;
+    opening = false;
+    ended = false;
+    error;
+    pendingRead = false;
+    writeTail = Promise.resolve();
+    queuedWriteBytes = 0;
+    closing = Promise.resolve();
+    factoryReceipt = Promise.resolve();
+    constructor(options) {
+        capacity(options.acpMaxMessageBytes);
+        if (typeof options.bindingId !== 'string' || !options.bindingId)
+            throw need('EMPLOYEE_EXEC_IDENTITY_MISMATCH');
+        this.options = options;
+    }
+    parse(params) {
+        if (!object(params) || Object.keys(params).some(key => !['version', 'bindingId', 'operation', 'executionId', 'message'].includes(key)) || params.version !== 1 || typeof params.bindingId !== 'string' || !['open', 'write', 'read', 'close'].includes(params.operation))
+            throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+        if (params.bindingId !== this.options.bindingId)
+            throw need('EMPLOYEE_EXEC_IDENTITY_MISMATCH');
+        if (params.operation === 'open') {
+            if (Object.hasOwn(params, 'executionId') || Object.hasOwn(params, 'message'))
+                throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+        }
+        else {
+            if (typeof params.executionId !== 'string' || !params.executionId)
+                throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+            if (params.executionId !== this.executionId)
+                throw need('EMPLOYEE_EXEC_IDENTITY_MISMATCH');
+            if (params.operation === 'write' ? !object(params.message) : Object.hasOwn(params, 'message'))
+                throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+        }
+        return params;
+    }
+    active() { if (this.ended)
+        throw this.error ?? need('EMPLOYEE_EXEC_CLOSED'); }
+    async gate(signal) { this.active(); cancelled(signal); await waiting(this.options.validate(signal), signal); this.active(); cancelled(signal); }
+    stop(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.error = error;
+        this.lifetime.abort();
+        const io = this.io;
+        this.io = undefined;
+        if (io)
+            this.closeTransport(io);
+    }
+    closeTransport(io) {
+        let closing;
+        try {
+            closing = Promise.resolve(io.close());
+        }
+        catch {
+            closing = Promise.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+        this.closing = Promise.all([this.closing, closing]).then(() => { }, () => { const unknown = need('EMPLOYEE_EXEC_UNKNOWN'); this.error ??= unknown; throw unknown; });
+        // Revocation starts cleanup without a caller waiting yet; retain rejection for close/dispose.
+        void this.closing.catch(() => { });
+    }
+    invalidate(error = need('EMPLOYEE_CONTEXT_CHANGED')) { this.stop(error); }
+    async cleanup() { await this.factoryReceipt; await this.closing; }
+    async dispose() { this.stop(); await this.cleanup(); }
+    async handle(params, signal) {
+        const request = this.parse(params);
+        cancelled(signal);
+        if (request.operation === 'close') {
+            this.stop();
+            await this.cleanup();
+            return { version: 1, closed: true, result: 'UNKNOWN' };
+        }
+        this.active();
+        const current = signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
+        if (request.operation === 'open')
+            return this.open(current);
+        if (request.operation === 'read')
+            return this.read(current);
+        const value = encoded(request.message, this.options.acpMaxMessageBytes);
+        const size = value.line.byteLength;
+        if (this.queuedWriteBytes + size > this.options.acpMaxMessageBytes) {
+            const error = need('ACP_MESSAGE_TOO_LARGE');
+            this.stop(error);
+            throw error;
+        }
+        this.queuedWriteBytes += size;
+        const operation = this.writeTail.then(async () => {
+            try {
+                await this.gate(current);
+                const io = this.io;
+                if (!io)
+                    throw need('EMPLOYEE_EXEC_CLOSED');
+                await waiting(io.write(value.message, current), current);
+                await this.gate(current);
+                return { version: 1 };
+            }
+            catch (error) {
+                const known = this.error ?? failure(error);
+                this.stop(known);
+                throw known;
+            }
+            finally {
+                this.queuedWriteBytes -= size;
+            }
+        });
+        this.writeTail = operation.catch(() => { });
+        return operation;
+    }
+    async open(signal) {
+        if (this.opening || this.executionId)
+            throw need('EMPLOYEE_EXEC_ALREADY_OPEN');
+        this.opening = true;
+        try {
+            await this.gate(signal);
+            // A factory may finish after revoke/abort. Its late executor belongs to this binding and must close.
+            const created = Promise.resolve().then(() => { cancelled(signal); return this.options.transport(signal); }).then(async (io) => { if (this.ended || signal.aborted) {
+                this.closeTransport(io);
+                await this.closing;
+                throw this.error ?? need('ABORTED');
+            } this.io = io; return io; });
+            // Open cancellation may return immediately; the runtime still owns the full allocation receipt.
+            this.factoryReceipt = created.then(() => { }, error => { if (failure(error).code === 'EMPLOYEE_EXEC_UNKNOWN') {
+                const unknown = need('EMPLOYEE_EXEC_UNKNOWN');
+                this.error ??= unknown;
+                throw unknown;
+            } });
+            void this.factoryReceipt.catch(() => { });
+            await waiting(created, signal);
+            await this.gate(signal);
+            this.executionId = randomUUID();
+            return { version: 1, executionId: this.executionId };
+        }
+        catch (error) {
+            const known = this.error ?? failure(error);
+            this.stop(known);
+            throw known;
+        }
+        finally {
+            this.opening = false;
+        }
+    }
+    async read(signal) {
+        if (this.pendingRead)
+            throw need('EMPLOYEE_EXEC_READ_BUSY');
+        this.pendingRead = true;
+        let consumed = false;
+        try {
+            await this.gate(signal);
+            const io = this.io;
+            if (!io)
+                throw need('EMPLOYEE_EXEC_CLOSED');
+            const message = await waiting(io.read(signal).then(message => { consumed = message !== null; return message; }), signal);
+            if (this.ended) {
+                if (this.error)
+                    throw this.error;
+                return { version: 1, messages: [], closed: true };
+            }
+            await this.gate(signal);
+            if (message === null) {
+                this.stop();
+                return { version: 1, messages: [], closed: true };
+            }
+            const value = encoded(message, this.options.acpMaxMessageBytes);
+            if (Buffer.byteLength(JSON.stringify({ version: 1, messages: [value.message], closed: false })) > this.options.acpMaxMessageBytes)
+                throw need('ACP_MESSAGE_TOO_LARGE');
+            return { version: 1, messages: [value.message], closed: false };
+        }
+        catch (error) {
+            if (this.error)
+                throw this.error;
+            if (signal.aborted && !this.ended) {
+                if (consumed) {
+                    const unknown = need('EMPLOYEE_EXEC_UNKNOWN');
+                    this.stop(unknown);
+                    throw unknown;
+                }
+                throw need('ABORTED');
+            }
+            if (this.ended && !this.error)
+                return { version: 1, messages: [], closed: true };
+            const known = failure(error);
+            this.stop(known);
+            throw known;
+        }
+        finally {
+            this.pendingRead = false;
+        }
+    }
+}
+/** NDJSON carrier with byte bounds and backpressure derived solely from acpMaxMessageBytes. */
+export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderrCodes = []) {
+    capacity(acpMaxMessageBytes);
+    let partial = Buffer.alloc(0), queuedBytes = 0, writingBytes = 0, closed = false, reason;
+    let processClosed = false, terminationRequested = false;
+    const receipt = Promise.withResolvers();
+    void receipt.promise.catch(() => { });
+    let sawOutput = false, diagnosticCode, stderrPosition = 0;
+    const knownCodes = stderrCodes.filter(code => /^[A-Z][A-Z0-9_]*$/.test(code));
+    let stderrCandidates = knownCodes;
+    const queue = [];
+    let pending;
+    const writes = new Set();
+    const settle = () => { if (!pending)
+        return; const reader = pending; pending = undefined; reader.clear(); reason ? reader.reject(reason) : reader.resolve(null); };
+    const terminate = () => {
+        if (processClosed || terminationRequested)
+            return;
+        terminationRequested = true;
+        try {
+            child.stdin.end();
+        }
+        catch {
+            receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+        // A paused output pipe must drain before Node can deliver the actual child close event.
+        child.stdout.resume();
+        child.stderr.resume();
+        try {
+            if (!child.kill('SIGTERM') && !processClosed)
+                receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+        catch {
+            receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+    };
+    const finish = (error, kill = false) => {
+        if (!closed) {
+            closed = true;
+            reason = error;
+            partial = Buffer.alloc(0);
+            if (error) {
+                queue.length = 0;
+                queuedBytes = 0;
+            }
+            settle();
+            for (const reject of writes)
+                reject(error ?? need('EMPLOYEE_EXEC_UNKNOWN'));
+            writes.clear();
+        }
+        if (kill)
+            terminate();
+    };
+    const output = (message, bytes) => {
+        if (pending) {
+            const reader = pending;
+            pending = undefined;
+            reader.clear();
+            reader.resolve(message);
+        }
+        else {
+            if (queuedBytes + bytes > acpMaxMessageBytes)
+                throw need('ACP_MESSAGE_TOO_LARGE');
+            queue.push({ message, bytes });
+            queuedBytes += bytes;
+            child.stdout.pause();
+        }
+    };
+    child.stdout.on('data', (chunk) => {
+        if (closed)
+            return;
+        sawOutput = true;
+        diagnosticCode = undefined;
+        try {
+            let start = 0;
+            while (start < chunk.length) {
+                const end = chunk.indexOf(10, start), last = end < 0 ? chunk.length : end;
+                const length = partial.length + last - start;
+                if (length > acpMaxMessageBytes || queuedBytes + length > acpMaxMessageBytes)
+                    throw need('ACP_MESSAGE_TOO_LARGE');
+                if (end < 0) {
+                    partial = Buffer.concat([partial, chunk.subarray(start)]);
+                    break;
+                }
+                const line = partial.length ? Buffer.concat([partial, chunk.subarray(start, end)]) : chunk.subarray(start, end);
+                partial = Buffer.alloc(0);
+                start = end + 1;
+                let value;
+                try {
+                    value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(line));
+                }
+                catch {
+                    throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+                }
+                if (!object(value))
+                    throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+                output(value, line.byteLength);
+            }
+        }
+        catch (error) {
+            finish(failure(error), true);
+        }
+    });
+    // Match fixed startup codes byte by byte. No arbitrary diagnostic bytes are retained.
+    child.stderr.on('data', (chunk) => {
+        if (sawOutput || closed || !knownCodes.length)
+            return;
+        for (const byte of chunk) {
+            if (byte === 10) {
+                const match = stderrCandidates.find(code => code.length === stderrPosition);
+                if (match)
+                    diagnosticCode = match;
+                stderrPosition = 0;
+                stderrCandidates = knownCodes;
+            }
+            else if (stderrCandidates.length) {
+                stderrCandidates = stderrCandidates.filter(code => code.charCodeAt(stderrPosition) === byte);
+                stderrPosition++;
+            }
+        }
+    });
+    child.stderr.resume();
+    child.stdin.on('error', () => finish(need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN'), true));
+    child.once('error', () => finish(need('EMPLOYEE_EXEC_UNKNOWN'), true));
+    child.once('close', (code, signal) => { processClosed = true; finish(partial.length ? need('EMPLOYEE_EXEC_PROTOCOL_INVALID') : code === 0 && !signal ? undefined : need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN')); receipt.resolve(); });
+    return {
+        write: async (message, signal) => {
+            cancelled(signal);
+            if (closed)
+                throw reason ?? need('EMPLOYEE_EXEC_UNKNOWN');
+            const value = encoded(message, acpMaxMessageBytes);
+            if (writingBytes + value.line.byteLength > acpMaxMessageBytes) {
+                const error = need('ACP_MESSAGE_TOO_LARGE');
+                finish(error, true);
+                throw error;
+            }
+            writingBytes += value.line.byteLength;
+            await new Promise((resolve, reject) => {
+                let done = false;
+                const cleanup = () => { if (done)
+                    return false; done = true; writingBytes -= value.line.byteLength; writes.delete(fail); signal?.removeEventListener('abort', abort); return true; };
+                const fail = (error) => { if (cleanup())
+                    reject(error); };
+                const abort = () => { const error = need('EMPLOYEE_EXEC_UNKNOWN'); finish(error, true); fail(error); };
+                writes.add(fail);
+                signal?.addEventListener('abort', abort, { once: true });
+                try {
+                    child.stdin.write(value.line, error => { if (error) {
+                        finish(need('EMPLOYEE_EXEC_UNKNOWN'), true);
+                        fail(need('EMPLOYEE_EXEC_UNKNOWN'));
+                    }
+                    else if (cleanup())
+                        resolve(); });
+                }
+                catch {
+                    finish(need('EMPLOYEE_EXEC_UNKNOWN'), true);
+                    fail(need('EMPLOYEE_EXEC_UNKNOWN'));
+                }
+                if (signal?.aborted)
+                    abort();
+            });
+        },
+        read: async (signal) => {
+            cancelled(signal);
+            if (reason)
+                throw reason;
+            if (pending)
+                throw need('EMPLOYEE_EXEC_READ_BUSY');
+            if (queue.length) {
+                const item = queue.shift();
+                queuedBytes -= item.bytes;
+                if (!queue.length && !closed)
+                    child.stdout.resume();
+                return item.message;
+            }
+            if (closed)
+                return null;
+            return new Promise((resolve, reject) => {
+                const abort = () => { if (pending?.resolve !== resolve)
+                    return; pending.clear(); pending = undefined; reject(need('ABORTED')); };
+                pending = { resolve, reject, clear: () => signal?.removeEventListener('abort', abort) };
+                signal?.addEventListener('abort', abort, { once: true });
+                child.stdout.resume();
+                if (signal?.aborted)
+                    abort();
+            });
+        },
+        close: () => { finish(undefined, true); queue.length = 0; queuedBytes = 0; return receipt.promise; }
+    };
+}

package/dist/employee-location.d.ts

@@ -0,0 +1,66 @@
+import type { EmployeeEndpointTarget, NetworkApi } from '@ai-workbench/network/api';
+export interface EmployeeLocationSource {
+    getWorkspaceLocationState(): {
+        instanceId: string;
+        epoch: number;
+        phase: string;
+        items: {
+            workspaceId: string;
+            bindingId: string | null;
+            source: string | null;
+            status: string;
+        }[];
+    };
+    getLocalWorkspaceContext(request: {
+        instanceId: string;
+        epoch: number;
+        workspaceId: string;
+        expectedBindingId: string;
+    }): Promise<{
+        ok: true;
+        value: {
+            version: 1;
+            instanceId: string;
+            epoch: number;
+            workspaceId: string;
+            bindingId: string;
+            source: 'local';
+            directory: {
+                path: string;
+                device: number;
+                inode: number;
+            };
+        };
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+            requires: string;
+        };
+    }>;
+}
+export type EmployeeEndpointSource = Pick<NetworkApi, 'prepareEmployeeEndpoint'>;
+export interface EmployeeLocationOptions {
+    api: EmployeeLocationSource;
+    network: EmployeeEndpointSource;
+    workspace: {
+        id: string;
+        path: string;
+    };
+    connection: {
+        instanceId: string;
+        epoch: number;
+    };
+    expectedLocal?: EmployeeEndpointTarget['local'];
+    settingsPath: string;
+    signal?: AbortSignal;
+}
+/** One admission binds source/canonical directory and real N/S execution identity. No host-path substitute. */
+export declare function admitEmployeeLocation(options: EmployeeLocationOptions): Promise<{
+    cwd: string;
+    bindingId: string;
+    workspaceId: string;
+    endpoint: EmployeeEndpointTarget;
+    validate: (signal: AbortSignal) => Promise<void>;
+}>;