@platys/relay 0.0.0-stage → 0.8.0-alpha.11

package/out/node/cli.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, openSync, closeSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { hostname } from 'node:os';
+import { secret } from '../core/types.js';
+import { root, snapshot } from './git.js';
+import { loadConnection, saveConnection, stateDir, State } from './state.js';
+import { api, Remote, serverURL } from './client.js';
+import { install } from './install.js';
+import { handleHook } from './hooks.js';
+import { serveMcp, callRelayTool } from './tools.js';
+import { Connector } from './connector.js';
+import { nativeDelivery } from './adapters.js';
+import { diagnose, mcpProbe } from './diagnostics.js';
+import { accept } from './integration.js';
+import { backupProject, pruneArtifacts } from './maintenance.js';
+import { startHub } from './hub.js';
+import { clientBudget } from './request-budget.js';
+import { networkMain } from './network-cli.js';
+import { setupNetwork } from './network-setup.js';
+import { openSetupWeb } from './setup-web.js';
+import { setupRemote, useRemoteSetup } from './remote-setup.js';
+import { VERSION } from '../core/version.js';
+const cli = fileURLToPath(import.meta.url);
+const parsed = parseArgs({ allowPositionals: true, options: Object.fromEntries([
+        'repo', 'server', 'invite', 'name', 'provider', 'repository', 'session', 'from', 'to', 'message', 'query', 'dir', 'port', 'create-key', 'args', 'id', 'backup', 'days', 'member', 'role'
+    ].map(name => [name, { type: 'string' }]).concat([['version', { type: 'boolean' }], ['approve', { type: 'boolean' }], ['json', { type: 'boolean' }], ['no-install', { type: 'boolean' }], ['no-start', { type: 'boolean' }], ['help', { type: 'boolean' }], ['relay-hook-v1', { type: 'boolean' }], ['global', { type: 'boolean' }], ['all-workspaces', { type: 'boolean' }], ['relay-network-hook-v1', { type: 'boolean' }], ['web', { type: 'boolean' }], ['no-open', { type: 'boolean' }], ['terminal', { type: 'boolean' }], ['remote', { type: 'boolean' }], ['legacy-network', { type: 'boolean' }]])) });
+const values = parsed.values, positionals = parsed.positionals;
+const option = (name) => typeof values[name] === 'string' ? values[name] : undefined;
+const help = `Relay Next — shared context for your existing coding sessions
+
+  setup                   Open simple Relay setup in your browser
+  setup --web             Open the setup screen in your browser
+  setup --legacy-network  Configure the optional legacy network connector
+  setup --terminal --invite URL --name NAME  Install without opening a browser
+  setup --invite CODE     Join a friend; detect clients and configure all workspaces
+  connect                 Connect a Git repository; install its agent integration
+  connect --global        Install once; connect agents across shared workspaces
+  invite --global         Invite a friend to your agent network
+  share --global --repo PATH  Share sessions in a workspace and its subfolders
+  unshare --global --repo PATH  Hide sessions in that workspace
+  share --global --all-workspaces  Share sessions across all workspaces
+  discover --global --session ID --name PERSON --query TOPIC
+  connect --invite CODE   Join your teammate's project
+  invite                  Create a single-use project invitation (24 hours)
+  members                 List project members and roles
+  member-role --member ID --role admin|member  Owner changes a project role
+  status                  Show sessions, freshness, pending uploads and receipts
+  context --session ID    Inspect shared context and its code references
+  ask --from ID --to ID --message TEXT
+  run                     Run this repository's connector in the foreground
+  stop                    Stop only this repository's Relay connector
+  doctor                  Check connector, MCP startup, session registration and legacy conflicts
+  project                 Read accepted revision, tasks and current decisions
+  metrics                 Read payload sizes and operation counts
+  budget                  Read cached shared monthly budget and pause alerts (local only)
+  budget-refresh          Explicitly check whether the owner approved resuming this service
+  task --args JSON        Reserve/renew/handoff/release scopes
+  artifact --args JSON    Export/receive/read exact selected files
+  integration --args JSON Prepare or validate changes in an isolated worktree
+  accept --id ID --session ID --approve  Accept a validated integration
+  backup                  Export project evidence and artifacts to a local archive
+  prune --backup FILE --days 7 --approve  Prune archived, unreferenced artifacts
+  dev --port 7337         Start a local-only service for development
+
+Connection options: --repo PATH --server HTTPS_URL --provider codex|claude|both
+                    --name NAME --repository SHARED_ID --no-start --no-install
+Creating a hosted project requires RELAY_CREATE_KEY from the service operator.
+Use npm run demo for an isolated two-connector demonstration.
+`;
+async function prompt(question, fallback) {
+    if (!process.stdin.isTTY) {
+        if (fallback !== undefined)
+            return fallback;
+        throw new Error(`${question} Supply the corresponding command option in non-interactive mode.`);
+    }
+    const reader = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await reader.question(`${question}${fallback ? ` [${fallback}]` : ''}: `)).trim() || fallback || '';
+    }
+    finally {
+        reader.close();
+    }
+}
+async function startDaemon(repo) {
+    const dir = stateDir(repo), lock = join(dir, 'connector.lock');
+    if (existsSync(lock)) {
+        const old = JSON.parse(readFileSync(lock, 'utf8'));
+        let alive = false;
+        try {
+            process.kill(old.pid, 0);
+            alive = true;
+        }
+        catch { }
+        if (alive) {
+            if (old.version === VERSION && old.cli === cli)
+                return;
+            writeFileSync(join(dir, 'stop'), 'upgrade');
+            for (let i = 0; i < 50 && existsSync(lock); i++)
+                await new Promise(resolve => setTimeout(resolve, 100));
+            if (existsSync(lock))
+                throw new Error('Existing connector has not stopped for upgrade; retry after it exits. Coding sessions were not stopped.');
+        }
+    }
+    if (existsSync(join(dir, 'stop')))
+        unlinkSync(join(dir, 'stop'));
+    const fd = openSync(join(dir, 'connector.log'), 'a', 0o600);
+    const child = spawn(process.execPath, [cli, 'run', '--repo', repo], { cwd: repo, windowsHide: true, detached: true, stdio: ['ignore', fd, fd], env: { ...process.env, RELAY_CREATE_KEY: undefined } });
+    child.unref();
+    closeSync(fd);
+}
+async function connectProject(repo) {
+    const dir = stateDir(repo);
+    let config;
+    if (existsSync(join(dir, 'connection.json'))) {
+        if (option('server') || option('invite'))
+            throw new Error('This checkout is already connected. Use another checkout to connect a different project.');
+        config = loadConnection(dir);
+    }
+    else {
+        const git = snapshot(repo, option('repository')), name = option('name') ?? await prompt('Your display name', hostname());
+        let server = option('server') ?? process.env.RELAY_SERVER_URL, projectId = crypto.randomUUID();
+        if (option('invite')) {
+            const encoded = option('invite');
+            if (!encoded.startsWith('relay:v1:'))
+                throw new Error('Paste the complete Relay invitation');
+            const invite = JSON.parse(Buffer.from(encoded.slice(9), 'base64url').toString('utf8'));
+            if (invite.repository && invite.repository !== git.repository)
+                throw new Error(`Invitation is for ${invite.repository}; this checkout is ${git.repository}. Run connect from the matching checkout.`);
+            server = serverURL(invite.server);
+            projectId = invite.projectId;
+            const joined = await api(server, projectId, '', 'join', { code: invite.code, name, repository: git.repository });
+            config = { server, projectId, ...joined, repository: git.repository, name, repo };
+        }
+        else {
+            server = serverURL(server ?? await prompt('Relay service URL'));
+            let key = option('create-key') ?? process.env.RELAY_CREATE_KEY;
+            const local = join(dir, 'local-service.json');
+            if (!key && existsSync(local)) {
+                const dev = JSON.parse(readFileSync(local, 'utf8'));
+                if (dev.server === server)
+                    key = dev.key;
+            }
+            if (!key)
+                throw new Error('Set RELAY_CREATE_KEY to create a project, or join using your teammate’s invitation.');
+            const created = await api(server, projectId, key, 'create', { name: repo.split(/[\\/]/).pop(), ownerName: name, repository: git.repository });
+            config = { server, projectId, ...created, repository: git.repository, name, repo };
+        }
+        saveConnection(dir, config);
+    }
+    const state = new State(dir);
+    state.set('repo', repo);
+    state.close();
+    if (!values['no-install']) {
+        const provider = option('provider') ?? await prompt('Coding agent: codex, claude or both', 'both');
+        if (!['codex', 'claude', 'both'].includes(provider))
+            throw new Error('Provider must be codex, claude or both');
+        for (const p of provider === 'both' ? ['codex', 'claude'] : [provider])
+            install(repo, p, cli);
+    }
+    if (!values['no-start'])
+        await startDaemon(repo);
+    const mcpReady = values['no-install'] ? false : await mcpProbe(cli, repo);
+    console.log(`MCP executable startup: ${mcpReady ? 'passed' : 'not verified'}. This does not confirm the coding session has loaded it.`);
+    console.log(`Connected ${config.name} to ${config.repository}.\n${values['no-start'] ? 'Run relay-next run to synchronize.' : 'Connector started. Session registration begins only when the coding client loads Relay; run relay-next doctor.'}\nResume your coding session once to load Relay. Approve its tools/hooks in the coding client.\nUse relay-next invite to invite your teammate.`);
+}
+async function run(repo) {
+    const dir = stateDir(repo), config = loadConnection(dir), lock = join(dir, 'connector.lock');
+    if (existsSync(lock)) {
+        const existing = JSON.parse(readFileSync(lock, 'utf8'));
+        let alive = false;
+        try {
+            process.kill(existing.pid, 0);
+            alive = true;
+        }
+        catch { /* exited */ }
+        if (alive)
+            throw new Error('A Relay connector is already running for this repository');
+        unlinkSync(lock);
+    }
+    const fd = openSync(lock, 'wx', 0o600);
+    writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString(), version: VERSION, cli }));
+    closeSync(fd);
+    if (existsSync(join(dir, 'stop')))
+        unlinkSync(join(dir, 'stop'));
+    const state = new State(dir);
+    state.set('repo', repo);
+    const connector = new Connector(state, new Remote(config), nativeDelivery(repo));
+    connector.start();
+    console.log('Relay connector running. Ctrl+C stops Relay only.');
+    await new Promise(resolve => { const stop = () => { clearInterval(timer); resolve(); }; const timer = setInterval(() => { if (existsSync(join(dir, 'stop')))
+        stop(); }, 1000); process.once('SIGINT', stop); process.once('SIGTERM', stop); });
+    await connector.stop();
+    state.close();
+    if (existsSync(lock))
+        unlinkSync(lock);
+}
+async function main() {
+    if (values.version) {
+        console.log(VERSION);
+        return;
+    }
+    const cmd = positionals[0] ?? 'help';
+    if (cmd === 'help' || values.help) {
+        console.log(help);
+        return;
+    }
+    if (cmd === 'budget') {
+        console.log(JSON.stringify(clientBudget.status(), null, 2));
+        return;
+    }
+    if (cmd === 'setup') {
+        if (useRemoteSetup(values)) {
+            if (values.terminal) {
+                await setupRemote(values, cli);
+                console.log('Relay installed. Reopen Codex or use the Claude with Relay desktop shortcut.');
+            }
+            else
+                await openSetupWeb({ ...values, remote: true }, cli);
+            return;
+        }
+        if (values.web || (!values.terminal && process.stdin.isTTY && !option('invite') && !option('server')))
+            await openSetupWeb(values, cli);
+        else
+            await setupNetwork(values, cli);
+        return;
+    }
+    if (values.global) {
+        await networkMain(cmd, values, cli);
+        return;
+    }
+    const repo = cmd === 'hook' ? resolve(option('repo') ?? process.cwd()) : root(option('repo') ?? process.cwd());
+    if (cmd === 'hook') {
+        let data = '';
+        for await (const chunk of process.stdin) {
+            data += chunk;
+            if (data.length > 1_000_000)
+                throw new Error('Hook input too large');
+        }
+        try {
+            console.log(JSON.stringify(handleHook(repo, option('provider'), JSON.parse(data))));
+        }
+        catch (error) {
+            console.error(`Relay hook unavailable: ${error.message}`);
+            console.log('{}');
+        }
+        return;
+    }
+    if (cmd === 'connect') {
+        await connectProject(repo);
+        return;
+    }
+    if (cmd === 'run') {
+        await run(repo);
+        return;
+    }
+    if (cmd === 'budget-refresh') {
+        console.log(JSON.stringify(await new Remote(loadConnection(stateDir(repo))).refreshBudget(), null, 2));
+        return;
+    }
+    if (cmd === 'dev') {
+        const dir = stateDir(repo);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const key = secret(), hub = await startHub(option('dir') ?? join(dir, 'dev-hub'), key, Number(option('port') ?? 7337));
+        writeFileSync(join(dir, 'local-service.json'), JSON.stringify({ server: hub.url, key }), { mode: 0o600 });
+        console.log(`Local development service: ${hub.url}\nConnect this checkout with: relay-next connect --server ${hub.url}\nThis address is available only on this computer.`);
+        await new Promise(resolve => { process.once('SIGINT', resolve); process.once('SIGTERM', resolve); });
+        await hub.close();
+        return;
+    }
+    if (cmd === 'doctor') {
+        console.log(JSON.stringify({ ...await diagnose(repo), mcpStarts: existsSync(join(stateDir(repo), 'connection.json')) ? await mcpProbe(cli, repo) : false }, null, 2));
+        return;
+    }
+    const dir = stateDir(repo), config = loadConnection(dir);
+    if (cmd === 'stop') {
+        writeFileSync(join(dir, 'stop'), 'stop');
+        console.log('Requested this repository’s connector to stop. Coding agents continue running.');
+        return;
+    }
+    if (cmd === 'members') {
+        const shared = await new Remote(config).call('snapshot');
+        console.log(JSON.stringify(shared.members, null, 2));
+        return;
+    }
+    if (cmd === 'member-role') {
+        const memberId = option('member'), role = option('role');
+        if (!memberId || !['admin', 'member'].includes(role ?? ''))
+            throw new Error('Use --member ID --role admin|member');
+        console.log(JSON.stringify(await new Remote(config).call('members', { memberId, role }), null, 2));
+        return;
+    }
+    if (cmd === 'invite') {
+        const invitation = await new Remote(config).call('invite', {});
+        const code = 'relay:v1:' + Buffer.from(JSON.stringify({ server: config.server, projectId: config.projectId, repository: config.repository, code: invitation.code })).toString('base64url');
+        console.log(`Single-use invitation; expires ${new Date(invitation.expiresAt).toISOString()}:\n${code}\n\nTeammate: relay-next connect --invite ${code}`);
+        return;
+    }
+    const state = new State(dir);
+    state.set('repo', repo);
+    try {
+        if (cmd === 'mcp') {
+            await serveMcp(state);
+            return;
+        }
+        if (cmd === 'status' && !state.bindings().length) {
+            console.log(JSON.stringify(await diagnose(repo), null, 2));
+            return;
+        }
+        if (cmd === 'backup') {
+            console.log(JSON.stringify(await backupProject(state), null, 2));
+            return;
+        }
+        const sessionId = option('session') ?? option('from') ?? ((cmd === 'status' || state.bindings().length === 1) ? state.bindings()[0]?.id : undefined);
+        if (!sessionId)
+            throw new Error('Choose --session from these connected sessions:\n' + state.bindings().map(s => `${s.id}  ${s.name}`).join('\n'));
+        if (cmd === 'backup') {
+            console.log(JSON.stringify(await backupProject(state), null, 2));
+            return;
+        }
+        if (cmd === 'prune') {
+            if (!values.approve)
+                throw new Error('Pruning requires --approve and a verified backup');
+            console.log(JSON.stringify(await pruneArtifacts(state, sessionId, option('backup') ?? '', Number(option('days') ?? 7)), null, 2));
+            return;
+        }
+        if (cmd === 'accept') {
+            console.log(JSON.stringify(await accept(state, option('id') ?? '', sessionId, values.approve === true), null, 2));
+            return;
+        }
+        const tool = { status: 'relay_status', context: 'relay_context', ask: 'relay_ask', project: 'relay_project', metrics: 'relay_metrics', task: 'relay_task', artifact: 'relay_artifact', integration: 'relay_integration' }[cmd];
+        const args = { ...(option('args') ? JSON.parse(option('args')) : {}), session_id: sessionId, ...(cmd === 'context' ? { query: option('query') ?? '' } : {}), ...(cmd === 'ask' ? { target_session_id: option('to'), question: option('message') } : {}) };
+        const result = tool ? await callRelayTool(state, tool, args) : null;
+        if (result === null)
+            throw new Error('Unknown command. Run relay-next help.');
+        if (cmd === 'status' && !values.json) {
+            const status = result;
+            console.log(`Relay · ${config.repository}\n${status.syncError ? `Sync unavailable: ${status.syncError.message}` : `Last sync: ${status.lastSync ?? 'waiting'}`} · ${status.pendingUploads} pending uploads\n`);
+            for (const session of status.sessions)
+                console.log(`${session.name}  ${session.provider}  ${session.state}${session.freshActivity ? '' : ' (activity stale)'}\n  ${session.task || 'No task shared yet'}\n  ${session.git.branch ?? 'detached'} @ ${session.git.head?.slice(0, 8) ?? 'unborn'}${session.git.dirty ? ' + uncommitted changes' : ''}\n  ${session.id}\n`);
+            if (status.overlaps.length)
+                console.log('Overlapping work:', status.overlaps.map((c) => c.paths.join(', ')).join('; '));
+            if (status.rejectedUploads.length)
+                console.log('Uploads needing attention:', status.rejectedUploads);
+            console.log('Recent directed messages:', status.receipts.slice(0, 8).map((r) => `${r.eventId.slice(0, 8)} ${r.state}`).join(' · ') || 'none');
+        }
+        else
+            console.log(JSON.stringify(result, null, 2));
+    }
+    finally {
+        state.close();
+    }
+}
+main().catch(error => { console.error(`Relay: ${error.message}`); process.exitCode = 1; });

package/out/node/client.js

@@ -0,0 +1,80 @@
+import WebSocket from 'ws';
+import { clientBudget, observeBudgetHeader } from './request-budget.js';
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export function serverURL(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash)
+        throw new Error('Use a service URL without credentials, query parameters or fragments');
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+        throw new Error('Relay requires HTTPS except for a local development service');
+    return url.toString().replace(/\/$/, '');
+}
+export async function api(server, projectId, token, action, body, cache = clientBudget) {
+    serverURL(server);
+    cache.assertAllowed(server);
+    const response = await fetch(`${serverURL(server)}/projects/${encodeURIComponent(projectId)}/${action}`, {
+        method: body === undefined ? 'GET' : 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(10_000), redirect: 'error'
+    });
+    observeBudgetHeader(server, response.headers.get('X-Relay-Budget'), cache);
+    const result = await response.json().catch(() => null);
+    if (!response.ok)
+        throw new HttpError(response.status, typeof result?.error === 'string' ? result.error : `Relay returned HTTP ${response.status}`);
+    if (result === null)
+        throw new Error('Relay returned an invalid JSON response');
+    return result;
+}
+export class Remote {
+    connection;
+    budget;
+    constructor(connection, budget = clientBudget) {
+        this.connection = connection;
+        this.budget = budget;
+    }
+    call(action, body) { const c = this.connection; return api(c.server, c.projectId, c.token, action, body, this.budget); }
+    events(after) { return this.call(`events?after=${after}`); }
+    async refreshBudget() {
+        // Explicit operator/user command only. Normal reconnects never bypass a pause.
+        const c = this.connection;
+        const response = await fetch(`${serverURL(c.server)}/projects/${encodeURIComponent(c.projectId)}/budgetstatus`, { headers: { Authorization: `Bearer ${c.token}` }, signal: AbortSignal.timeout(10000), redirect: 'error' });
+        if (!response.ok)
+            throw new HttpError(response.status, 'Could not refresh shared budget status');
+        const status = await response.json();
+        this.budget.observe(c.server, status);
+        return status;
+    }
+    subscribe(changed, closed) {
+        const c = this.connection, url = new URL(`${serverURL(c.server)}/projects/${c.projectId}/stream`);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        this.budget.assertAllowed(c.server);
+        const ws = new WebSocket(url, { headers: { Authorization: `Bearer ${c.token}` }, handshakeTimeout: 10_000, maxPayload: 4096 });
+        ws.on('upgrade', response => { const header = response.headers['x-relay-budget']; if (typeof header === 'string')
+            observeBudgetHeader(c.server, header, this.budget); });
+        ws.on('unexpected-response', (_request, response) => { try {
+            const header = response.headers['x-relay-budget'];
+            if (typeof header === 'string')
+                observeBudgetHeader(c.server, header, this.budget);
+        }
+        finally {
+            response.resume();
+            ws.terminate();
+        } });
+        ws.on('message', data => { try {
+            const message = JSON.parse(data.toString());
+            if (message.type === 'budget_paused') {
+                this.budget.observe(c.server, message.budget);
+                ws.close();
+            }
+        }
+        catch { } changed(); });
+        ws.on('error', () => { });
+        ws.on('close', closed);
+        return ws;
+    }
+}

package/out/node/connector.js

@@ -0,0 +1,171 @@
+import { publicSession } from './state.js';
+import { HttpError } from './client.js';
+import { message } from './adapters.js';
+import { terminalStatus } from './terminal.js';
+export class Connector {
+    state;
+    remote;
+    deliver;
+    ticking = false;
+    stopped = false;
+    socket;
+    timer;
+    reconnect;
+    failures = 0;
+    dirty = true;
+    lastNetwork = 0;
+    protocol;
+    retryAfter = 0;
+    constructor(state, remote, deliver) {
+        this.state = state;
+        this.remote = remote;
+        this.deliver = deliver;
+    }
+    async tick(force = true) {
+        if (this.ticking || this.stopped || (!force && Date.now() < this.retryAfter))
+            return;
+        this.ticking = true;
+        try {
+            const pending = this.state.pending();
+            if (this.protocol === undefined) {
+                const info = await this.remote.call('snapshot');
+                this.protocol = info.protocol ?? 1;
+                this.state.set('serverProtocol', this.protocol);
+            }
+            if (this.protocol < 2 && pending.some(j => j.action === 'events' && (['artifact', 'integration'].includes(j.body.kind) || j.body.phase)))
+                throw new Error('Update the Relay service to protocol 2 before synchronizing collaboration events; outbox retained');
+            const bindings = this.state.bindings();
+            const changed = bindings.some(b => { const previous = this.state.get(`registered:${b.id}`); return !previous || (previous.json !== JSON.stringify(publicSession(b)) && Date.now() - previous.at >= 10_000); });
+            if (!force && !this.dirty && !pending.length && !changed && Date.now() - this.lastNetwork < 300_000)
+                return;
+            if (!force && this.lastNetwork && Date.now() - this.lastNetwork < 1000)
+                return;
+            this.dirty = false;
+            this.lastNetwork = Date.now();
+            // Register before draining events. Native credentials never leave this machine.
+            for (const binding of this.state.bindings()) {
+                const key = `registered:${binding.id}`, previous = this.state.get(key);
+                const session = publicSession(binding), json = JSON.stringify(session);
+                if (session.state === 'closed' && previous?.json === json)
+                    continue;
+                if (!previous || (previous.json !== json && (force || Date.now() - previous.at >= 10_000))) {
+                    await this.remote.call('sessions', session);
+                    this.state.set(key, { json, at: Date.now() });
+                }
+            }
+            for (const job of this.state.pending()) {
+                try {
+                    const result = await this.remote.call(job.action, job.body);
+                    this.state.remove(job.id);
+                    if (job.action === 'events' && result?.kind === 'reply' && result.phase !== 'progress')
+                        this.state.mark(result.replyTo, result.sessionId, 'answered', 'Reply stored remotely');
+                }
+                catch (error) {
+                    if (error instanceof HttpError && [400, 403, 404, 409, 413].includes(error.status)) {
+                        this.state.set(`rejected:${job.id}`, { action: job.action, error: error.message, at: new Date().toISOString() });
+                        this.state.remove(job.id);
+                    }
+                    else
+                        throw error;
+                }
+            }
+            // Persist pages and cursor in the same transaction. Reconnect resumes from it.
+            while (true) {
+                const page = await this.remote.events(this.state.get('cursor') ?? 0);
+                this.state.measure('network:events', JSON.stringify(page));
+                this.state.cache(page.events);
+                if (page.events.length < 200)
+                    break;
+            }
+            const snapshot = await this.remote.call('snapshot');
+            this.state.measure('network:snapshot', JSON.stringify(snapshot));
+            this.state.set('snapshot', snapshot);
+            this.state.set('lastSync', new Date().toISOString());
+            this.state.set('syncError', null);
+            this.failures = 0;
+            await this.updateTerminals('online');
+            for (const binding of this.state.bindings())
+                for (const event of this.state.messages(binding.id)) {
+                    const receipt = snapshot.receipts.find(r => r.eventId === event.id && r.sessionId === binding.id);
+                    if (receipt && ['answered', 'delivered'].includes(receipt.state)) {
+                        this.state.mark(event.id, binding.id, receipt.state);
+                        continue;
+                    }
+                    if (event.phase === 'progress' && !event.urgent) {
+                        continue;
+                    }
+                    const previous = this.state.delivery(event.id, binding.id);
+                    if (previous && previous.state !== 'held')
+                        continue;
+                    const heldKey = `held-binding:${event.id}:${binding.id}`;
+                    const readiness = JSON.stringify([binding.state, binding.hookSeenAt, binding.endpoint, Boolean(binding.inboxToken)]);
+                    if (previous?.state === 'held' && this.state.get(heldKey) === readiness)
+                        continue;
+                    // Persist before the side effect. A process crash here is ambiguous, so no blind replay.
+                    this.state.measure('native:' + event.kind, message(event));
+                    this.state.mark(event.id, binding.id, 'attempting', 'Native delivery in progress');
+                    let result;
+                    try {
+                        result = await this.deliver(binding, event);
+                    }
+                    catch {
+                        result = { state: 'uncertain', detail: 'Native delivery interrupted; use hook delivery or inspect the session' };
+                    }
+                    if (this.state.delivery(event.id, binding.id)?.state !== 'delivered') {
+                        this.state.mark(event.id, binding.id, result.state, result.detail);
+                        if (result.state === 'held')
+                            this.state.set(heldKey, readiness);
+                        if (previous?.state !== result.state || previous?.detail !== result.detail)
+                            this.state.enqueue('receipts', { eventId: event.id, sessionId: binding.id, ...result }, `receipt:${event.id}:${binding.id}`);
+                    }
+                }
+        }
+        catch (error) {
+            this.failures++;
+            this.retryAfter = Date.now() + Math.min(300_000, 1000 * 2 ** Math.min(this.failures, 9));
+            this.state.set('syncError', { message: error.message, at: new Date().toISOString() });
+            await this.updateTerminals('offline');
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    async updateTerminals(status) {
+        for (const binding of this.state.bindings()) {
+            if (!binding.terminal)
+                continue;
+            const key = `terminal:${binding.id}`, last = this.state.get(key);
+            if (last?.status === status && (last.ok || Date.now() - last.at < 30_000))
+                continue;
+            const ok = await terminalStatus(binding, status);
+            this.state.set(key, { status, at: Date.now(), ok });
+        }
+    }
+    start() {
+        for (const event of this.state.events())
+            if (event.targetSessionId && this.state.delivery(event.id, event.targetSessionId)?.state === 'attempting') {
+                this.state.mark(event.id, event.targetSessionId, 'uncertain', 'Connector restarted during native delivery; no automatic replay');
+                this.state.enqueue('receipts', { eventId: event.id, sessionId: event.targetSessionId, state: 'uncertain', detail: 'Connector restarted during native delivery' }, `receipt:${event.id}:${event.targetSessionId}`);
+            }
+        let reconnectFailures = 0;
+        const reconnect = () => { if (!this.stopped)
+            this.reconnect = setTimeout(connect, Math.min(300_000, 1000 * 2 ** Math.min(++reconnectFailures, 9))); };
+        const connect = () => {
+            if (this.stopped)
+                return;
+            try {
+                this.socket = this.remote.subscribe(() => { reconnectFailures = 0; this.dirty = true; void this.tick(false); }, reconnect);
+            }
+            catch (error) {
+                this.state.set('syncError', { message: error.message, at: new Date().toISOString() });
+                reconnect();
+            }
+        };
+        connect();
+        const loop = async () => { await this.tick(false); if (!this.stopped)
+            this.timer = setTimeout(loop, this.failures ? Math.min(30_000, 1000 * 2 ** Math.min(this.failures, 5)) : 1000); };
+        void loop();
+    }
+    async stop() { this.stopped = true; clearTimeout(this.timer); clearTimeout(this.reconnect); this.socket?.terminate(); while (this.ticking)
+        await new Promise(r => setTimeout(r, 10)); }
+}