@ai-workbench/connect 0.0.0-stage → 0.7.6

package/lib/startup.js

@@ -0,0 +1,211 @@
+import { randomUUID } from 'node:crypto';
+import { fail, need, ok } from "./needs.js";
+export function employeeMessage(code) {
+    if (code === 'ENROLLMENT_RESULT_UNKNOWN' || code === 'ENROLLMENT_REJECTED')
+        return need(code).message;
+    if (code === 'DEPENDENCY_REQUIRED')
+        return '远程主机连接尚未准备好，请联系管理员。';
+    if (code === 'ENROLLMENT_REQUIRED' || code === 'ENROLLMENT_INVALID' || code === 'NETWORK_KEY_INVALID')
+        return '我需要连接资料，请联系管理员发放。';
+    if (code === 'SETTINGS_REQUIRED')
+        return '远程主机连接还没有设置好，请联系管理员。';
+    if (code === 'LOGIN_FAILED')
+        return '登录没有完成。你可以再次请求登录，或稍后再试。';
+    if (code === 'POLICY_DENIED')
+        return '这个账号暂时不能使用，请联系公司账号管理员。';
+    return '远程主机暂时连不上，请联系管理员。';
+}
+export function createStartup(api, providers, emit = () => { }, result = () => { }, instanceId = randomUUID()) {
+    let disposed = false, revision = 0, serial = 0, generation = 0, checkSerial = 0, connectionPhase = 'unavailable', observedConnected = false;
+    let flight, authorization, authorizationId;
+    const pending = new Set(), listeners = new Set(), deferred = new Set();
+    let state = { instanceId, revision: 0, phase: 'checking', message: '正在连接远程主机…', logins: {}, checkingProviders: [], providerNeeds: {}, technicalDetails: {} };
+    const publish = (next) => { state = { ...next, instanceId, revision: ++revision }; emit(structuredClone(state)); for (const listener of listeners)
+        listener(structuredClone(state)); };
+    const track = (p) => { pending.add(p); void p.then(() => pending.delete(p), () => pending.delete(p)); return p; };
+    const close = (outcome, code) => { if (state.requestId && state.provider)
+        result({ requestId: state.requestId, provider: state.provider, outcome, ...(code ? { need: need(code) } : {}) }); };
+    const blocked = (code) => { close('invalidated', code); publish({ phase: 'blocked', message: employeeMessage(code), logins: {}, checkingProviders: [], providerNeeds: {}, technicalDetails: { ...state.technicalDetails, code } }); };
+    const snapshot = () => state.phase === 'disposed' ? fail('DISPOSED') : state.phase === 'blocked' ? fail(state.technicalDetails.code ?? 'AUTH_STATUS_INVALID') : ok(structuredClone(state));
+    const ask = () => {
+        const provider = state.requestId && state.provider && state.logins[state.provider] === false && !deferred.has(state.provider) ? state.provider : providers.find(p => state.logins[p] === false && !deferred.has(p));
+        const same = provider && state.provider === provider && state.requestId && state.phase === 'login-required';
+        publish({ ...state, phase: provider ? 'login-required' : 'idle', provider, requestId: provider ? (same ? state.requestId : 'login-' + instanceId + '-' + (++serial)) : undefined, message: provider ? '需要登录，请到设置 → 远程主机连接 点登录' : Object.keys(state.providerNeeds).length ? Object.keys(state.providerNeeds).map(p => p === 'claude' ? 'Claude' : 'Codex').join('、') + ' 登录状态无法确认，请联系管理员。' : '远程主机连接检查完成。' });
+    };
+    const check = () => {
+        if (disposed)
+            return Promise.resolve();
+        if (authorization)
+            return Promise.resolve();
+        if (flight)
+            return flight;
+        const mine = generation, checkMine = ++checkSerial;
+        const run = async () => {
+            try {
+                // Preserve an existing question while gathering fresh evidence, so duplicate requests keep its ticket.
+                publish({ ...state, ...(!state.requestId ? { phase: 'checking', message: '正在检查登录状态…' } : {}), checkingProviders: [] });
+                const connected = await api.connect();
+                if (disposed || mine !== generation || checkMine !== checkSerial)
+                    return;
+                if (!connected.ok) {
+                    blocked(connected.error.code);
+                    return;
+                }
+                const logins = { ...state.logins }, providerNeeds = { ...state.providerNeeds };
+                for (const provider of providers) {
+                    publish({ ...state, checkingProviders: [provider] });
+                    const status = await api.checkLogin(provider);
+                    if (disposed || mine !== generation || checkMine !== checkSerial)
+                        return;
+                    if (!status.ok) {
+                        if (status.error.layer !== 'auth' && !['AUTH_STATUS_INVALID', 'LOGIN_FAILED', 'POLICY_DENIED'].includes(status.error.code)) {
+                            blocked(status.error.code);
+                            return;
+                        }
+                        delete logins[provider];
+                        providerNeeds[provider] = status.error;
+                    }
+                    else {
+                        logins[provider] = status.value.loggedIn;
+                        delete providerNeeds[provider];
+                    }
+                    if (state.requestId && state.provider === provider && logins[provider] !== false) {
+                        close(logins[provider] === true ? 'logged-in' : 'invalidated', providerNeeds[provider]?.code);
+                        publish({ ...state, requestId: undefined, provider: undefined, phase: 'checking', message: '正在检查登录状态…' });
+                    }
+                    publish({ ...state, logins: { ...logins }, providerNeeds: { ...providerNeeds }, checkingProviders: state.checkingProviders.filter(p => p !== provider) });
+                }
+                if (state.requestId && state.provider && logins[state.provider] === true) {
+                    close('logged-in');
+                    publish({ ...state, requestId: undefined, provider: undefined, phase: 'checking', message: '正在检查登录状态…' });
+                }
+                publish({ ...state, logins, providerNeeds, checkingProviders: [], technicalDetails: connected.value.hostContext ? { hostContext: structuredClone(connected.value.hostContext) } : {} });
+                ask();
+            }
+            catch {
+                if (!disposed && mine === generation && checkMine === checkSerial)
+                    blocked('DEPENDENCY_REQUIRED');
+            }
+        };
+        const promise = track(run());
+        flight = promise;
+        void promise.then(() => { if (flight === promise)
+            flight = undefined; });
+        return promise;
+    };
+    const providerFailed = (provider, code, sourceNeed = need(code)) => {
+        const logins = { ...state.logins };
+        delete logins[provider];
+        publish({ ...state, phase: 'idle', requestId: undefined, provider: undefined, logins, checkingProviders: [], providerNeeds: { ...state.providerNeeds, [provider]: structuredClone(sourceNeed) } });
+        ask();
+    };
+    const respond = (requestId, action) => {
+        if (disposed)
+            return Promise.resolve(fail('DISPOSED'));
+        if (action === 'authorize' && authorization && authorizationId === requestId)
+            return authorization;
+        if (!requestId || state.requestId !== requestId || state.phase !== 'login-required' || !state.provider || !['authorize', 'defer'].includes(action))
+            return Promise.resolve(fail('LOGIN_PROMPT_INVALID'));
+        const provider = state.provider;
+        if (action === 'defer') {
+            close('deferred');
+            deferred.add(provider);
+            publish({ ...state, requestId: undefined, provider: undefined });
+            ask();
+            return Promise.resolve(snapshot());
+        }
+        if (authorization)
+            return Promise.resolve(fail('LOGIN_PROMPT_INVALID'));
+        const mine = generation;
+        checkSerial++;
+        authorizationId = requestId;
+        publish({ ...state, phase: 'authorizing', checkingProviders: [provider], message: '请在授权窗口完成本人登录。' });
+        const run = async () => {
+            try {
+                await flight;
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                const current = await api.checkLogin(provider);
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                const verified = current.ok && current.value.loggedIn ? current : current.ok ? await api.login(provider) : current;
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                if (!verified.ok || !verified.value.loggedIn) {
+                    const code = verified.ok ? 'LOGIN_FAILED' : verified.error.code;
+                    result({ requestId, provider, outcome: 'failed', need: need(code) });
+                    providerFailed(provider, code, verified.ok ? need(code) : verified.error);
+                    return verified.ok ? fail(code) : verified;
+                }
+                result({ requestId, provider, outcome: 'logged-in' });
+                deferred.delete(provider);
+                const providerNeeds = { ...state.providerNeeds };
+                delete providerNeeds[provider];
+                publish({ ...state, requestId: undefined, provider: undefined, logins: { ...state.logins, [provider]: true }, providerNeeds, checkingProviders: [], phase: 'idle' });
+                ask();
+                return snapshot();
+            }
+            catch {
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                result({ requestId, provider, outcome: 'failed', need: need('LOGIN_FAILED') });
+                providerFailed(provider, 'LOGIN_FAILED');
+                return fail('LOGIN_FAILED');
+            }
+        };
+        const promise = track(run());
+        authorization = promise;
+        void promise.then(() => { if (authorization === promise) {
+            authorization = undefined;
+            authorizationId = undefined;
+        } });
+        return promise;
+    };
+    return { getState: () => structuredClone(state), check,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        async request(provider, intent) {
+            if (!providers.includes(provider) || !['automatic', 'user'].includes(intent))
+                return fail('AUTH_STATUS_INVALID');
+            const mine = generation;
+            if (intent === 'user')
+                deferred.delete(provider);
+            if (authorization)
+                return state.providerNeeds[provider] ? { ok: false, error: structuredClone(state.providerNeeds[provider]) } : snapshot();
+            await check();
+            if (disposed || mine !== generation)
+                return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+            if (intent === 'user' && !authorization && state.logins[provider] === false && !state.providerNeeds[provider] && !state.checkingProviders.includes(provider) && state.phase !== 'blocked' && state.phase !== 'disposed' && state.provider !== provider) {
+                close('invalidated', 'LOGIN_PROMPT_INVALID');
+                publish({ ...state, phase: 'login-required', provider, requestId: 'login-' + instanceId + '-' + (++serial), message: '需要登录，请到设置 → 远程主机连接 点登录' });
+            }
+            return state.providerNeeds[provider] ? { ok: false, error: structuredClone(state.providerNeeds[provider]) } : snapshot();
+        }, respond,
+        // Internal compatibility facade. HTTP and public API must use ticketed responses.
+        defer(provider) { if (state.provider === provider && state.requestId)
+            void respond(state.requestId, 'defer'); },
+        async authorize(provider) { if (state.provider === provider && state.requestId)
+            await respond(state.requestId, 'authorize'); },
+        connectionChanged(next) {
+            if (disposed)
+                return;
+            const prior = connectionPhase;
+            connectionPhase = next.phase;
+            if (next.phase === 'unavailable' || next.phase === 'disposed') {
+                generation++;
+                flight = undefined;
+                blocked(next.need?.code ?? (next.phase === 'disposed' ? 'DISPOSED' : 'CONNECTION_LOST'));
+            }
+            else if (next.phase === 'connected' && prior !== 'connected') {
+                const restored = observedConnected;
+                observedConnected = true;
+                if (restored) {
+                    const mine = generation;
+                    queueMicrotask(() => { void Promise.resolve(authorization).then(() => { if (!disposed && mine === generation && connectionPhase === 'connected')
+                        void check(); }); });
+                }
+            }
+        },
+        stop() { if (disposed)
+            return; disposed = true; generation++; close('invalidated', 'DISPOSED'); publish({ phase: 'disposed', message: '远程主机连接已关闭。', logins: {}, checkingProviders: [], providerNeeds: {}, technicalDetails: { code: 'DISPOSED' } }); listeners.clear(); },
+        async dispose() { this.stop(); await Promise.allSettled([...pending]); }, };
+}

package/lib/workspace-bindings.d.ts

@@ -0,0 +1,32 @@
+import type { ConnectApi, SessionProjectTarget, Result, ConnectionState, WorkspaceBindingState, WorkspaceNoticeReceipt, WorkspaceUse } from './api.ts';
+export interface NativeWorkspace {
+    id: string;
+    path: string;
+    title: string;
+    sessionIds: string[];
+}
+export interface NativeWorkspaceRegistry {
+    get(id: string): NativeWorkspace | undefined;
+    list(): NativeWorkspace[];
+}
+export interface WorkspaceBindingOptions {
+    profileDir: string;
+    metadataMaxBytes: number;
+    api: Pick<ConnectApi, 'getConnectionState' | 'getSshTarget' | 'listProjects' | 'createProject' | 'ensureReady'>;
+    registry: NativeWorkspaceRegistry;
+    readHeader: (sessionId: string) => Promise<{
+        id: string;
+        cwd?: string;
+    } | undefined>;
+    nextRevision?: () => number;
+    onState?: (state: WorkspaceBindingState) => void;
+    diagnostic?: (error: unknown) => void;
+}
+export declare function createWorkspaceBindings(options: WorkspaceBindingOptions): {
+    observeConnection(state: ConnectionState): void;
+    dispose(): Promise<unknown>;
+    getWorkspaceBindingState: () => WorkspaceBindingState;
+    onWorkspaceBindingState(listener: (state: WorkspaceBindingState) => void): () => void;
+    acknowledgeWorkspaceNotice: (receipt: WorkspaceNoticeReceipt) => Promise<Result<void>>;
+    resolveSessionProject: (sessionId: string, use: WorkspaceUse) => Promise<Result<SessionProjectTarget>>;
+};

package/lib/workspace-bindings.js

@@ -0,0 +1,328 @@
+import { lstat, realpath, open, rename, rm } from 'node:fs/promises';
+import { join, isAbsolute, basename } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { privateDirectory, readPrivate } from "./private-files.js";
+import { isProjectName } from "./projects.js";
+import { ok, fail, NeedError, need } from "./needs.js";
+// All bindings belonging to one profile share reservation ordering, including reopened service instances.
+const queues = new Map();
+const hash = (v) => createHash('sha256').update(JSON.stringify(v)).digest('hex');
+const token = (v) => typeof v === 'string' && v.length > 0 && !/[\x00-\x1f\x7f]/.test(v);
+const integrity = (r) => hash([r.identity, r.workspaceId, r.localPath, r.localDev, r.localIno, r.project, r.bindingId, r.noticeId, r.sessionIds]);
+export function createWorkspaceBindings(options) {
+    const root = join(options.profileDir, 'ai-workbench-connect'), file = join(root, 'workspaces.json'), owner = randomUUID();
+    let revision = 0, disposed = false, tail = Promise.resolve(), snapshot = { instanceId: options.api.getConnectionState().instanceId, revision: 0, items: [] };
+    let latest = [];
+    const listeners = new Set(), statuses = new Map();
+    const same = (a) => { const b = options.api.getConnectionState(); return !disposed && b.phase === 'connected' && b.instanceId === a.instanceId && b.epoch === a.epoch; };
+    const stale = () => fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+    const diagnostic = (error) => options.diagnostic?.(error);
+    function publish(items) {
+        if (disposed)
+            return;
+        latest = items;
+        snapshot = { instanceId: options.api.getConnectionState().instanceId, revision: (revision = options.nextRevision?.() ?? revision + 1), items: items.map(r => ({ bindingId: r.bindingId, workspaceId: r.workspaceId, workspaceName: r.project.name, status: statuses.get(r.bindingId) ?? (r.phase === 'intent' ? 'pending' : 'unavailable'), notice: { noticeId: r.noticeId, settings: r.settings, provider: r.provider === 'claimed' && r.claim?.owner !== owner ? 'unknown' : r.provider } })) };
+        options.onState?.(structuredClone(snapshot));
+        for (const listener of listeners)
+            listener(structuredClone(snapshot));
+    }
+    async function prepare() {
+        if (!isAbsolute(options.profileDir) || await realpath(options.profileDir) !== options.profileDir)
+            throw Error('PROFILE_PATH_INVALID');
+        await privateDirectory(root);
+        if (await realpath(root) !== root)
+            throw Error('BINDING_PATH_INVALID');
+    }
+    async function records() {
+        let raw;
+        try {
+            raw = await readPrivate(file, options.metadataMaxBytes);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const value = JSON.parse(raw);
+        if (value.schemaVersion !== 2 || !Array.isArray(value.items))
+            throw Error('BINDING_INVALID');
+        const ids = new Set(), paths = new Set(), notices = new Set(), bindings = new Set(), sessions = new Set();
+        for (const r of value.items) {
+            if (!r || !token(r.bindingId) || !token(r.noticeId) || !token(r.workspaceId) || !(/^[a-f0-9]{64}$/.test(r.identity)) || !isAbsolute(r.localPath) || !Number.isSafeInteger(r.localDev) || !Number.isSafeInteger(r.localIno) || !isProjectName(r.project?.name) || typeof r.project.path !== 'string' || r.key !== integrity(r) || !['intent', 'bound'].includes(r.phase) || !['pending', 'displayed'].includes(r.settings) || !['pending', 'claimed', 'delivered', 'unknown'].includes(r.provider) || ids.has(r.workspaceId) || paths.has(r.identity + '\0' + r.project.path) || notices.has(r.noticeId) || bindings.has(r.bindingId) || !Array.isArray(r.sessionIds) || r.sessionIds.some(id => !token(id) || sessions.has(id)) || new Set(r.sessionIds).size !== r.sessionIds.length)
+                throw Error('BINDING_INVALID');
+            if (r.provider === 'pending' ? r.claim !== undefined : (!r.claim || !token(r.claim.id) || !token(r.claim.sessionId) || !['claude', 'codex'].includes(r.claim.provider) || !token(r.claim.owner) || (r.provider === 'delivered' && !token(r.claim.deliveryId))))
+                throw Error('BINDING_CLAIM_INVALID');
+            ids.add(r.workspaceId);
+            paths.add(r.identity + '\0' + r.project.path);
+            notices.add(r.noticeId);
+            bindings.add(r.bindingId);
+            for (const id of r.sessionIds)
+                sessions.add(id);
+        }
+        return value.items;
+    }
+    async function save(items) {
+        for (const r of items)
+            r.key = integrity(r);
+        const bytes = JSON.stringify({ schemaVersion: 2, items }) + '\n';
+        if (Buffer.byteLength(bytes) > options.metadataMaxBytes)
+            throw Error('BINDING_LIMIT');
+        const temp = join(root, '.workspaces-' + randomUUID());
+        try {
+            const h = await open(temp, 'wx', 0o600);
+            try {
+                await h.writeFile(bytes);
+                await h.sync();
+            }
+            finally {
+                await h.close();
+            }
+            await rename(temp, file);
+            const dir = await open(root, 'r');
+            try {
+                await dir.sync();
+            }
+            finally {
+                await dir.close();
+            }
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    }
+    function serialized(run) {
+        const prior = queues.get(file) ?? Promise.resolve();
+        const promise = prior.then(() => disposed ? fail('DISPOSED') : run());
+        const settled = promise.then(() => { }, () => { });
+        queues.set(file, settled);
+        tail = settled;
+        void settled.then(() => { if (queues.get(file) === settled)
+            queues.delete(file); });
+        return promise;
+    }
+    async function native(sessionId) {
+        const matches = options.registry.list().filter(w => Array.isArray(w.sessionIds) && w.sessionIds.includes(sessionId));
+        if (matches.length !== 1)
+            throw new NeedError(need('PROJECT_BINDING_REQUIRED'));
+        const workspace = matches[0], registered = options.registry.get(workspace.id), header = await options.readHeader(sessionId);
+        if (!registered || registered.path !== workspace.path || !registered.sessionIds.includes(sessionId) || !isAbsolute(workspace.path) || !header || header.id !== sessionId || !header.cwd || !isAbsolute(header.cwd))
+            throw new NeedError(need('PROJECT_BINDING_REQUIRED'));
+        const localPath = await realpath(workspace.path), cwd = await realpath(header.cwd), info = await lstat(localPath);
+        if (localPath !== cwd || !info.isDirectory() || info.isSymbolicLink())
+            throw new NeedError(need('PROJECT_BINDING_REQUIRED'));
+        return { workspaceId: workspace.id, localPath, localDev: info.dev, localIno: info.ino, name: basename(localPath) };
+    }
+    const sameNative = (a, b) => a.workspaceId === b.workspaceId && a.localPath === b.localPath && a.localDev === b.localDev && a.localIno === b.localIno;
+    function validList(list, projectRoot) { return Array.isArray(list.projects) && Array.isArray(list.unavailable) && list.projects.every(p => isProjectName(p.name) && p.path === projectRoot + '/' + p.name) && new Set(list.projects.map(p => p.path)).size === list.projects.length; }
+    function occupancy(list, name) {
+        const aliases = (n) => n.normalize('NFC').toLowerCase() === name.normalize('NFC').toLowerCase();
+        return list.unavailable.some(p => aliases(p.name)) || list.projects.some(p => p.name !== name && aliases(p.name));
+    }
+    async function resolve(sessionId, use) {
+        if (!token(sessionId) || !use || !['claude', 'codex'].includes(use.provider) || use.purpose !== 'user-turn')
+            return fail('PROJECT_BINDING_REQUIRED');
+        let stored, binding;
+        try {
+            await prepare();
+            stored = await records();
+            const before = options.api.getConnectionState();
+            const ready = await options.api.ensureReady(use.provider);
+            if (!same(before))
+                return stale();
+            if (!ready.ok)
+                return ready;
+            const targetResult = await options.api.getSshTarget();
+            if (!same(before))
+                return stale();
+            if (!targetResult.ok)
+                return targetResult;
+            const target = targetResult.value;
+            if (JSON.stringify(target) !== JSON.stringify(ready.value))
+                return fail('CONNECTION_LOST');
+            const trust = await readPrivate(target.knownHostsFile, options.metadataMaxBytes), identity = hash([target.host, target.username, target.port, target.projectRoot, target.session, trust]);
+            binding = stored.find(r => r.sessionIds.includes(sessionId));
+            let current;
+            try {
+                current = await native(sessionId);
+            }
+            catch (error) {
+                if (stored.some(r => r.sessionIds.includes(sessionId) || options.registry.get(r.workspaceId)?.sessionIds.includes(sessionId))) {
+                    diagnostic(error);
+                    throw new NeedError(need('PROJECT_BINDING_INVALID'));
+                }
+                throw error;
+            }
+            if (!isProjectName(current.name))
+                return fail('PROJECT_NAME_INVALID');
+            const localBinding = stored.find(r => r.workspaceId === current.workspaceId || r.localPath === current.localPath);
+            if (binding && binding !== localBinding)
+                throw new NeedError(need('PROJECT_BINDING_INVALID'));
+            binding = localBinding;
+            if (binding && (binding.identity !== identity || binding.workspaceId !== current.workspaceId || binding.localPath !== current.localPath || binding.localDev !== current.localDev || binding.localIno !== current.localIno || binding.project.name !== current.name || binding.project.path !== target.projectRoot + '/' + current.name))
+                throw new NeedError(need('PROJECT_BINDING_INVALID'));
+            const remotePath = target.projectRoot + '/' + current.name, collision = stored.find(r => r !== binding && r.identity === identity && r.project.path === remotePath);
+            if (collision) {
+                const result = fail(collision.phase === 'intent' ? 'PROJECT_BINDING_BUSY' : 'PROJECT_EXISTS');
+                if (!result.ok)
+                    result.error.message = `远程主机上的‘${current.name}’已被另一工作区使用/正在关联，请选择名称不同的本地文件夹或联系管理员`;
+                return result;
+            }
+            const listed = await options.api.listProjects();
+            if (!same(before))
+                return stale();
+            if (!listed.ok)
+                return listed;
+            if (!validList(listed.value, target.projectRoot))
+                return fail('PROJECT_PROTOCOL_INVALID');
+            let project = listed.value.projects.find(p => p.name === current.name && p.path === remotePath);
+            if (binding?.phase === 'bound' && !project)
+                throw new NeedError(need('PROJECT_BINDING_INVALID'));
+            if (occupancy(listed.value, current.name))
+                return fail(binding?.phase === 'intent' ? 'PROJECT_CREATE_UNKNOWN' : 'PROJECT_EXISTS');
+            if (!binding) {
+                binding = { key: '', identity, workspaceId: current.workspaceId, localPath: current.localPath, localDev: current.localDev, localIno: current.localIno, project: { name: current.name, path: remotePath }, bindingId: randomUUID(), noticeId: randomUUID(), sessionIds: [sessionId], phase: project ? 'bound' : 'intent', settings: 'pending', provider: 'pending' };
+                stored.push(binding);
+                await save(stored);
+                if (!same(before))
+                    return stale();
+                if (!project) {
+                    if (!sameNative(current, await native(sessionId)))
+                        throw new NeedError(need('PROJECT_BINDING_INVALID'));
+                    if (!same(before))
+                        return stale();
+                    let created;
+                    try {
+                        created = await options.api.createProject(current.name);
+                    }
+                    catch (error) {
+                        diagnostic(error);
+                        publish(stored);
+                        return fail('PROJECT_CREATE_UNKNOWN');
+                    }
+                    if (!same(before))
+                        return stale();
+                    if (!created.ok) {
+                        publish(stored);
+                        return created;
+                    }
+                    if (created.value.name !== current.name || created.value.path !== remotePath)
+                        return fail('PROJECT_PROTOCOL_INVALID');
+                    const verified = await options.api.listProjects();
+                    if (!same(before))
+                        return stale();
+                    if (!verified.ok || !validList(verified.value, target.projectRoot) || occupancy(verified.value, current.name))
+                        return fail('PROJECT_CREATE_UNKNOWN');
+                    project = verified.value.projects.find(p => p.name === current.name && p.path === remotePath);
+                    if (!project)
+                        return fail('PROJECT_CREATE_UNKNOWN');
+                }
+            }
+            else if (!project) {
+                publish(stored);
+                return fail('PROJECT_CREATE_UNKNOWN');
+            }
+            if (!sameNative(current, await native(sessionId)))
+                throw new NeedError(need('PROJECT_BINDING_INVALID'));
+            if (!same(before))
+                return stale();
+            binding.phase = 'bound';
+            if (!binding.sessionIds.includes(sessionId))
+                binding.sessionIds.push(sessionId);
+            statuses.set(binding.bindingId, 'ready');
+            if (binding.provider === 'unknown' || (binding.provider === 'claimed' && binding.claim?.owner !== owner)) {
+                binding.provider = 'unknown';
+                await save(stored);
+                publish(stored);
+                return fail('PROJECT_NOTICE_DELIVERY_UNKNOWN');
+            }
+            if (binding.provider === 'claimed' && (binding.claim?.sessionId !== sessionId || binding.claim.provider !== use.provider)) {
+                await save(stored);
+                publish(stored);
+                return fail('PROJECT_BINDING_BUSY');
+            }
+            if (binding.provider === 'pending') {
+                binding.provider = 'claimed';
+                binding.claim = { id: randomUUID(), sessionId, provider: use.provider, owner };
+            }
+            await save(stored);
+            if (!same(before))
+                return stale();
+            if (!sameNative(current, await native(sessionId)))
+                throw new NeedError(need('PROJECT_BINDING_INVALID'));
+            if (!same(before))
+                return stale();
+            publish(stored);
+            return ok({ instanceId: before.instanceId, epoch: before.epoch, bindingRevision: revision, bindingId: binding.bindingId, sessionId, workspaceId: current.workspaceId, project: structuredClone(binding.project), target, ...(binding.provider === 'claimed' ? { notice: { noticeId: binding.noticeId, claimId: binding.claim.id, workspaceName: binding.project.name, messageKey: 'remote-workspace-binding' } } : {}) });
+        }
+        catch (error) {
+            diagnostic(error);
+            if (binding)
+                statuses.set(binding.bindingId, 'invalid');
+            if (stored)
+                publish(stored);
+            return error instanceof NeedError ? { ok: false, error: error.need } : fail('PROJECT_BINDING_INVALID');
+        }
+    }
+    async function acknowledge(receipt) {
+        try {
+            await prepare();
+            const stored = await records();
+            if (!receipt || !token(receipt.noticeId))
+                return fail('PROJECT_BINDING_INVALID');
+            const binding = stored.find(r => r.noticeId === receipt.noticeId);
+            if (!binding || binding.phase !== 'bound')
+                return fail('PROJECT_BINDING_INVALID');
+            if (receipt.surface === 'settings') {
+                if (receipt.outcome !== 'displayed' || Object.keys(receipt).sort().join(',') !== 'noticeId,outcome,surface')
+                    return fail('PROJECT_BINDING_INVALID');
+                binding.settings = 'displayed';
+            }
+            else if (receipt.surface === 'provider') {
+                const claim = binding.claim, keys = receipt.outcome === 'delivered' ? 'claimId,deliveryId,noticeId,outcome,provider,sessionId,surface' : 'claimId,noticeId,outcome,provider,sessionId,surface';
+                if (!claim || !['claimed', 'unknown', 'delivered'].includes(binding.provider) || Object.keys(receipt).sort().join(',') !== keys || receipt.claimId !== claim.id || receipt.sessionId !== claim.sessionId || receipt.provider !== claim.provider || !['delivered', 'not-delivered', 'unknown'].includes(receipt.outcome) || (receipt.outcome === 'delivered' && !token(receipt.deliveryId)))
+                    return fail('PROJECT_BINDING_INVALID');
+                if (binding.provider === 'delivered') {
+                    return receipt.outcome === 'delivered' && receipt.deliveryId === claim.deliveryId ? ok(undefined) : fail('PROJECT_BINDING_INVALID');
+                }
+                if (receipt.outcome === 'not-delivered') {
+                    binding.provider = 'pending';
+                    delete binding.claim;
+                }
+                else if (receipt.outcome === 'unknown')
+                    binding.provider = 'unknown';
+                else if (receipt.outcome === 'delivered') {
+                    binding.provider = 'delivered';
+                    claim.deliveryId = receipt.deliveryId;
+                }
+            }
+            else
+                return fail('PROJECT_BINDING_INVALID');
+            await save(stored);
+            publish(stored);
+            return ok(undefined);
+        }
+        catch (error) {
+            diagnostic(error);
+            return fail('PROJECT_BINDING_INVALID');
+        }
+    }
+    // Loading metadata never resolves a remote project or creates either a local or remote directory.
+    void serialized(async () => { try {
+        await prepare();
+        publish(await records());
+    }
+    catch (error) {
+        diagnostic(error);
+    } });
+    return {
+        observeConnection(state) { if (disposed)
+            return; for (const [id, status] of statuses)
+            if (status === 'ready')
+                statuses.set(id, 'unavailable'); publish(latest); },
+        dispose() { disposed = true; listeners.clear(); return tail; },
+        getWorkspaceBindingState: () => structuredClone(snapshot),
+        onWorkspaceBindingState(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        acknowledgeWorkspaceNotice: (receipt) => serialized(() => acknowledge(receipt)),
+        resolveSessionProject: (sessionId, use) => serialized(() => resolve(sessionId, use)),
+    };
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Remote host connection",
+    "description": "View remote host connection status and manage Claude/Codex sign-in."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "远程主机连接",
+    "description": "查看远程主机连接状态并管理 Claude/Codex 登录。"
+  }
+}