@logicseek/hello-cc 1.1.0-rc.3 → 1.1.0-rc.5

package/lib/integrations/claude-app.mjs

@@ -0,0 +1,289 @@
+import http from 'node:http';
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliError } from '../shared/errors.mjs';
+import { captureSelectedCwdIdentity } from '../process/selected-cwd-identity.mjs';
+
+export const CLAUDE_APP_MIN_VERSION = '2.1.287';
+export const CLAUDE_APP_PROTOCOL = 1;
+const TERMINAL = new Set(['completed', 'aborted', 'uncertain', 'rejected']);
+const clone = value => structuredClone(value);
+const fail = (code, message) => new CliError(code, message);
+
+export function claudeAppCapability(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version || ''));
+  const parts = match?.slice(1).map(Number);
+  const supported = !!parts && (parts[0] > 2 || parts[0] === 2 &&
+    (parts[1] > 1 || parts[1] === 1 && parts[2] >= 287));
+  return { supported, version: version || null, minimumVersion: CLAUDE_APP_MIN_VERSION,
+    reason: supported ? null : 'CLAUDE_APP_ENGINE_UNSUPPORTED' };
+}
+
+function identifier(value, name) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(value)) {
+    throw fail('BAD_ARGS', `Invalid ${name}`);
+  }
+  return value;
+}
+
+function fields(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).some(key => !allowed.includes(key))) throw fail('BAD_ARGS', 'Unexpected bridge fields');
+}
+
+function reply(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+  res.end(JSON.stringify(data));
+}
+
+async function readBody(req) {
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 256 * 1024) throw fail('BAD_ARGS', 'Bridge body exceeds 256 KiB');
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw fail('BAD_ARGS', 'Expected a JSON object'); }
+}
+
+/** A local capability for ONE explicitly selected existing Desktop session.
+ * No Claude account credentials, transcript files, peer bindings or settings are read.
+ * The secret authorizes this HCC bridge only. Same-OS-user code that can read a
+ * generated plugin is inside this boundary; it is not provider attestation.
+ */
+export async function createClaudeAppBridge({ root, initialRootIdentity = null, sessionId, port = 0, pollMs = 1000,
+  leaseMs = 15000, maxRequests = 256, onConnected, onDisconnected, onStatus, onRequest } = {}) {
+  identifier(sessionId, 'sessionId');
+  if (!Number.isInteger(port) || port < 0 || port > 65535 ||
+      !Number.isInteger(pollMs) || pollMs < 100 || pollMs > 10000 ||
+      !Number.isInteger(leaseMs) || leaseMs < pollMs * 3 || leaseMs > 120000 ||
+      !Number.isInteger(maxRequests) || maxRequests < 1 || maxRequests > 4096) {
+    throw fail('BAD_ARGS', 'Invalid Claude bridge limits');
+  }
+  const cwdBinding = captureSelectedCwdIdentity(root, initialRootIdentity);
+  const secret = randomBytes(32).toString('base64url');
+  const requests = new Map();
+  const events = new Map();
+  const maxEvents = Math.max(256, maxRequests * 4);
+  let closed = false, connection = null, address;
+  const publicStatus = () => ({ sessionId, cwd: cwdBinding.canonical,
+    version: connection?.version || null, ready: Boolean(connection?.ready && !closed),
+    surfaces: connection?.surfaces || [], transport: 'claude-desktop-mod',
+    minimumVersion: CLAUDE_APP_MIN_VERSION, reason: connection?.reason || null });
+  function notify(callback, value) {
+    try { Promise.resolve(callback?.(clone(value))).catch(() => {}); } catch { /* observers cannot change delivery */ }
+  }
+  function publish(request) { notify(onRequest, request); return clone(request); }
+  function disconnect(reason) {
+    const wasReady = connection?.ready;
+    if (connection) { connection.ready = false; connection.reason = reason; }
+    for (const request of requests.values()) {
+      if (!TERMINAL.has(request.status)) {
+        request.status = 'uncertain'; request.reason = reason; publish(request);
+      }
+    }
+    if (wasReady) notify(onDisconnected, publicStatus());
+    notify(onStatus, publicStatus());
+  }
+  function check() {
+    if (closed) throw fail('CLAUDE_APP_CLOSED', 'Claude Desktop bridge is closed');
+    try { cwdBinding.assertUnchanged(); }
+    catch (error) { disconnect('PROJECT_PATH_CHANGED'); throw error; }
+    if (connection?.ready && Date.now() - connection.lastSeen > leaseMs) disconnect('CLAUDE_APP_CONNECTION_EXPIRED');
+  }
+  function assertIdentity(body, connected = true) {
+    if (body.sessionId !== sessionId || body.cwd !== cwdBinding.canonical) {
+      throw fail('CLAUDE_APP_IDENTITY_MISMATCH', 'The session or directory differs from this bridge');
+    }
+    if (connected && (!connection?.ready || body.connectionId !== connection.id)) {
+      throw fail('CLAUDE_APP_CONNECTION_STALE', 'This mod connection is no longer active');
+    }
+  }
+  function applyEvent(body) {
+    fields(body, ['sessionId', 'cwd', 'connectionId', 'eventId', 'requestId', 'type', 'turnId', 'answer', 'reason']);
+    assertIdentity(body);
+    identifier(body.eventId, 'eventId'); identifier(body.requestId, 'requestId');
+    const digest = createHash('sha256').update(JSON.stringify(body)).digest('hex');
+    if (events.has(body.eventId)) {
+      if (events.get(body.eventId) !== digest) throw fail('CLAUDE_APP_EVENT_CONFLICT', 'Event ID was reused with different content');
+      return { ok: true };
+    }
+    const request = requests.get(body.requestId);
+    if (!request || request.connectionId !== connection.id) throw fail('CLAUDE_APP_REQUEST_UNKNOWN', 'Request is not owned by this connection');
+    if (TERMINAL.has(request.status)) throw fail('CLAUDE_APP_REQUEST_SETTLED', 'Request already reached a final state');
+    if (body.type === 'accepted') {
+      if (request.status !== 'claimed' || request.accepted) throw fail('CLAUDE_APP_EVENT_ORDER', 'Only a newly polled request can be accepted');
+      request.accepted = true;
+    } else if (body.type === 'started') {
+      identifier(body.turnId, 'turnId');
+      if (!request.accepted || request.status !== 'claimed') throw fail('CLAUDE_APP_EVENT_ORDER', 'A start requires an accepted request');
+      request.status = 'started'; request.turnId = body.turnId;
+    } else if (body.type === 'completed' || body.type === 'aborted') {
+      if (request.status !== 'started' || body.turnId !== request.turnId) {
+        throw fail('CLAUDE_APP_TURN_MISMATCH', 'Only the request’s observed turn can complete it');
+      }
+      if (typeof body.answer !== 'string' || body.answer.length > 100000) throw fail('BAD_ARGS', 'Invalid final answer');
+      request.status = body.type; request.answer = body.answer; request.reason = body.reason || null;
+    } else if (body.type === 'uncertain' || body.type === 'rejected') {
+      if (!request.accepted) throw fail('CLAUDE_APP_EVENT_ORDER', 'A rejection requires an accepted request');
+      request.status = body.type; request.reason = String(body.reason || body.type).slice(0,500);
+    } else throw fail('BAD_ARGS', 'Unknown bridge event');
+    // Keep small receipt digests after request release: a lost HTTP response
+    // retries this exact event, even if its durable owner already released it.
+    events.set(body.eventId, digest);
+    if (events.size > maxEvents) events.delete(events.keys().next().value);
+    publish(request);
+    return { ok: true };
+  }
+  const server = http.createServer(async (req, res) => {
+    try {
+      // No browser origin can use this API, even with an accidentally disclosed token.
+      if (req.headers.origin || req.headers.host !== new URL(address).host || req.method !== 'POST') {
+        return reply(res, 403, { error: { code: 'CLAUDE_APP_FORBIDDEN' } });
+      }
+      const presented = Buffer.from(String(req.headers.authorization || ''));
+      const expected = Buffer.from(`Bearer ${secret}`);
+      if (presented.length !== expected.length || !timingSafeEqual(presented, expected)) {
+        return reply(res, 401, { error: { code: 'CLAUDE_APP_UNAUTHORIZED' } });
+      }
+      if (!['/connect', '/poll', '/event', '/disconnect'].includes(req.url)) return reply(res, 404, { error: { code: 'NOT_FOUND' } });
+      check();
+      const body = await readBody(req);
+      check();
+      if (req.url === '/connect') {
+        fields(body, ['sessionId', 'cwd', 'version', 'surfaces', 'instanceId']);
+        assertIdentity(body, false); identifier(body.instanceId, 'instanceId');
+        if (!claudeAppCapability(body.version).supported) throw fail('CLAUDE_APP_ENGINE_UNSUPPORTED', `Claude Code ${CLAUDE_APP_MIN_VERSION} or later is required`);
+        if (!Array.isArray(body.surfaces) || !body.surfaces.includes('desktop') || body.surfaces.some(x => typeof x !== 'string')) {
+          throw fail('CLAUDE_APP_DESKTOP_REQUIRED', 'The current session has no Desktop surface');
+        }
+        if (connection?.ready && connection.instanceId !== body.instanceId) throw fail('CLAUDE_APP_ALREADY_CONNECTED', 'A mod instance is already connected');
+        if (!connection?.ready) {
+          connection = { id: randomUUID(), instanceId: body.instanceId, version: body.version,
+            surfaces: body.surfaces.slice(), ready: true, lastSeen: Date.now(), reason: null };
+          notify(onConnected, publicStatus()); notify(onStatus, publicStatus());
+        }
+        connection.lastSeen = Date.now();
+        return reply(res, 200, { protocol: CLAUDE_APP_PROTOCOL, connectionId: connection.id });
+      }
+      assertIdentity(body);
+      connection.lastSeen = Date.now();
+      if (req.url === '/poll') {
+        fields(body, ['sessionId', 'cwd', 'connectionId']);
+        const request = [...requests.values()].find(x => x.connectionId === connection.id &&
+          (x.status === 'queued' || x.status === 'claimed') && !x.accepted);
+        if (request?.status === 'queued') { request.status = 'claimed'; publish(request); }
+        return reply(res, 200, { request: request ? { requestId: request.requestId, prompt: request.prompt } : null });
+      }
+      if (req.url === '/event') return reply(res, 200, applyEvent(body));
+      fields(body, ['sessionId', 'cwd', 'connectionId', 'reason']);
+      disconnect(String(body.reason || 'session_ended').slice(0,200));
+      return reply(res, 200, { ok: true });
+    } catch (error) {
+      if (!res.headersSent) reply(res, error?.code === 'BAD_ARGS' ? 400 : 409,
+        { error: { code: error?.code || 'CLAUDE_APP_ERROR', message: error?.message || 'Bridge error' } });
+    }
+  });
+  server.requestTimeout = 5000; server.headersTimeout = 5000;
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', () => { server.off('error', reject); resolve(); });
+    });
+  } catch (error) { cwdBinding.release(); throw error; }
+  address = `http://127.0.0.1:${server.address().port}`;
+  const sweep = setInterval(() => { try { check(); } catch {} }, pollMs);
+  sweep.unref();
+  const pluginConfig = Object.freeze({ protocol: CLAUDE_APP_PROTOCOL, endpoint: address, secret,
+    sessionId, cwd: cwdBinding.canonical, minVersion: CLAUDE_APP_MIN_VERSION, pollMs });
+  return {
+    address, pluginConfig,
+    list() { check(); return [clone(publicStatus())]; },
+    send(input) {
+      fields(input, ['sessionId', 'text', 'requestId']); check();
+      if (input.sessionId !== sessionId) throw fail('CLAUDE_APP_IDENTITY_MISMATCH', 'Target differs from the bound Desktop session');
+      identifier(input.requestId, 'requestId');
+      if (typeof input.text !== 'string' || !input.text.trim() || input.text.length > 64000) throw fail('BAD_ARGS', 'Message must contain 1–64000 characters');
+      const existing = requests.get(input.requestId);
+      if (existing) {
+        if (existing.text !== input.text) throw fail('CLAUDE_APP_REQUEST_CONFLICT', 'Request ID was reused with different content');
+        return clone(existing);
+      }
+      if (!connection?.ready) throw fail('CLAUDE_APP_NOT_CONNECTED', 'The selected Desktop session has not connected its mod');
+      if (requests.size >= maxRequests) throw fail('CLAUDE_APP_QUEUE_FULL', 'Bridge request capacity reached; persist and release terminal requests before sending more');
+      const request = { requestId: input.requestId, sessionId, cwd: cwdBinding.canonical,
+        text: input.text, prompt: `[HCC message ${randomUUID()}]\n${input.text}`,
+        connectionId: connection.id, status: 'queued', accepted: false, turnId: null,
+        answer: null, reason: null };
+      requests.set(request.requestId, request); return publish(request);
+    },
+    getRequest(id) { check(); return clone(requests.get(id) || null); },
+    // The caller must persist the terminal receipt and own request-id
+    // idempotency before releasing the in-memory body and its capacity.
+    releaseRequest(id) {
+      identifier(id, 'requestId'); check();
+      const request = requests.get(id);
+      if (!request) return false;
+      if (!TERMINAL.has(request.status)) throw fail('CLAUDE_APP_REQUEST_PENDING', 'Only terminal requests can be released');
+      return requests.delete(id);
+    },
+    async close() {
+      if (closed) return;
+      disconnect('CLAUDE_APP_CLOSED'); closed = true; clearInterval(sweep);
+      await new Promise(resolve => { server.close(resolve); server.closeAllConnections(); });
+      cwdBinding.release();
+    }
+  };
+}
+
+/** Generate a capability-bearing plugin in a NEW private directory. Never installs it. */
+export function writeClaudeAppPlugin({ directory, bridge } = {}) {
+  if (!bridge?.pluginConfig || bridge.pluginConfig.protocol !== CLAUDE_APP_PROTOCOL) throw fail('BAD_ARGS', 'A running Claude bridge is required');
+  let output;
+  if (directory) { output = path.resolve(directory); fs.mkdirSync(output, { mode: 0o700 }); }
+  else output = fs.mkdtempSync(path.join(os.tmpdir(), 'hcc-session-link-'));
+  const identity = fs.lstatSync(output);
+  function dispose() {
+    let current;
+    try { current = fs.lstatSync(output); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== identity.dev ||
+        current.ino !== identity.ino || current.birthtimeMs !== identity.birthtimeMs) {
+      throw fail('CLAUDE_APP_PLUGIN_PATH_CHANGED', 'Generated plugin directory was replaced; refusing to remove it');
+    }
+    // This catches replacement before cleanup. Same-user concurrent pathname
+    // races are not an atomic filesystem security boundary.
+    fs.rmSync(output, { recursive: true, force: true });
+  }
+  try {
+    fs.chmodSync(output, 0o700);
+    const runId = randomBytes(12).toString('hex');
+    const name = 'hcc-session-link', marketplace = `hcc-session-link-${runId}`, version = `0.1.0-bridge.${runId}`;
+    const pluginDirectory = path.join(output, 'plugin');
+    fs.mkdirSync(path.join(output, '.claude-plugin'), { mode: 0o700 });
+    fs.mkdirSync(pluginDirectory, { mode: 0o700 });
+    fs.mkdirSync(path.join(pluginDirectory, '.claude-plugin'), { mode: 0o700 });
+    fs.mkdirSync(path.join(pluginDirectory, 'hooks'), { mode: 0o700 });
+    const template = fs.readFileSync(fileURLToPath(new URL('./claude-mod/register.mjs', import.meta.url)), 'utf8');
+    const source = template.replace('const HCC_CONFIG = null;', `const HCC_CONFIG = ${JSON.stringify(bridge.pluginConfig)};`);
+    fs.writeFileSync(path.join(output, '.claude-plugin/marketplace.json'), JSON.stringify({
+      name: marketplace, description: 'Session-scoped hello-cc desktop collaboration bridge',
+      owner: { name: 'hello-cc' }, plugins: [{ name, source: './plugin', version,
+        description: 'Connect one explicitly selected existing Claude Desktop Code session' }]
+    }, null, 2), { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(path.join(pluginDirectory, '.claude-plugin/plugin.json'), JSON.stringify({ name, version, author: { name: 'hello-cc' },
+      description: 'Explicitly connect this existing Claude Desktop Code session to hello-cc' }, null, 2), { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(path.join(pluginDirectory, 'hooks/hooks.json'), JSON.stringify({ modules: ['./register.mjs'] }, null, 2), { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(path.join(pluginDirectory, 'hooks/register.mjs'), source, { flag: 'wx', mode: 0o600 });
+    return { directory: pluginDirectory, marketplaceDirectory: output, name, marketplace, version,
+      minimumVersion: CLAUDE_APP_MIN_VERSION, sessionId: bridge.pluginConfig.sessionId, dispose };
+  } catch (error) {
+    try { dispose(); } catch (cleanupError) { cleanupError.cause = error; throw cleanupError; }
+    throw error;
+  }
+}

package/lib/integrations/claude-mod/register.mjs

@@ -0,0 +1,141 @@
+// Generated plugins replace this constant with one session-scoped HCC capability.
+// Official contract: https://code.claude.com/docs/en/plugins/mods/api
+// Exact event fields: https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts
+// No Node imports, credentials, permission changes, other-session sends or transcript reads.
+const HCC_CONFIG = null;
+
+const config = HCC_CONFIG;
+let alive = false, busy = false, ticking = false, connectionId = null, pending = null;
+let timer = null, instanceId = '', eventSequence = 0;
+const outbox = [];
+const observed = new Set();
+
+function event(type, request, details = {}) {
+  outbox.push({ eventId: `${instanceId}:${++eventSequence}`, requestId: request.requestId, type, ...details });
+}
+async function identity($) {
+  return await $.session.id() === config.sessionId && await $.session.cwd() === config.cwd;
+}
+async function post($, route, body) {
+  const response = await $.http.fetch(config.endpoint + route, { method: 'POST',
+    headers: { Authorization: `Bearer ${config.secret}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sessionId: config.sessionId, cwd: config.cwd, ...body }) });
+  const value = JSON.parse(response.text);
+  if (!response.ok) throw new Error(value.error?.code || 'CLAUDE_APP_HTTP_ERROR');
+  return value;
+}
+async function flush($) {
+  while (outbox.length && alive && connectionId) {
+    await post($, '/event', { connectionId, ...outbox[0] });
+    outbox.shift();
+  }
+}
+async function tick($) {
+  if (!alive || ticking) return;
+  ticking = true;
+  try {
+    if (!await identity($)) { await stop($, 'CLAUDE_APP_IDENTITY_CHANGED'); return; }
+    if (!connectionId) {
+      const version = await $.session.version();
+      const surfaces = await $.session.surfaces();
+      const response = await post($, '/connect', { version: version.version, surfaces, instanceId });
+      if (!alive) return;
+      connectionId = response.connectionId;
+    }
+    await flush($);
+    if (!alive) return;
+    // Poll even while busy, so an approval dialog does not expire the lease.
+    const response = await post($, '/poll', { connectionId });
+    if (!alive || !await identity($)) return;
+    if (busy || pending?.invoking) return;
+    if (!pending) {
+      if (!response.request) return;
+      const request = response.request;
+      if (observed.has(request.requestId)) return; // never replay after an ambiguous receipt
+      observed.add(request.requestId);
+      pending = { ...request, turnId: null, invoking: false };
+      event('accepted', pending);
+    }
+    await flush($); // retry a lost receipt, never the actual model submission
+    if (!alive || !await identity($)) return;
+    const owned = pending;
+    owned.invoking = true;
+    // Do not await in the timer or a running turn. This call waits until idle.
+    // Keep the plugin's attribution; never use asUser or modify permission state.
+    Promise.resolve().then(() => $.prompt.submit({ text: owned.prompt })).then(result => {
+      if (!alive || pending !== owned) return;
+      if (result?.drop) { event('rejected', owned, { reason: String(result.drop).slice(0,500) }); pending = null; }
+      else if (!owned.turnId && typeof result?.text === 'string' && result.text !== owned.prompt) {
+        event('uncertain', owned, { reason: 'prompt_changed_by_another_hook' }); pending = null;
+      }
+      // Resolution alone is NOT evidence the model saw it. turn.start binds it.
+    }).catch(() => {
+      if (!alive || pending !== owned) return;
+      event('uncertain', owned, { reason: 'prompt_submit_failed' }); pending = null;
+    });
+  } catch (error) {
+    // A replacement/revocation is final. Transient I/O retains the outbox.
+    if (['CLAUDE_APP_CONNECTION_STALE', 'CLAUDE_APP_IDENTITY_MISMATCH', 'PROJECT_PATH_CHANGED'].includes(error?.message)) {
+      await stop($, error.message);
+    }
+  }
+  finally { ticking = false; }
+}
+async function stop($, reason) {
+  alive = false;
+  timer?.cancel(); timer = null;
+  const old = connectionId; connectionId = null; pending = null;
+  if (old) { try { await post($, '/disconnect', { connectionId: old, reason }); } catch {} }
+}
+export function register(on) {
+  if (!config) return;
+  on('session.start', async ($, e, next) => {
+    try {
+      if (!await identity($)) return next(e);
+      instanceId = `mod-${await $.clock.now()}-${Math.random().toString(36).slice(2)}`;
+      alive = true;
+      timer = $.clock.every(config.pollMs, () => { void tick($); });
+      void tick($);
+    } catch { /* a missing/denied Mod API must not interfere with the session */ }
+    return next(e);
+  });
+  on('prompt.submit', async ($, e, next) => {
+    if (e.origin?.kind === 'plugin' && e.origin.name === 'hcc-session-link') {
+      if (!alive || !pending?.invoking || e.text !== pending.prompt || !await identity($)) {
+        return { drop: 'hello-cc connection or session identity changed' };
+      }
+    }
+    return next(e);
+  });
+  on('turn.start', async ($, e, next) => {
+    try {
+      if (alive && !e.agentId) {
+        busy = true;
+        if (pending?.invoking && e.text === pending.prompt && await identity($)) {
+          pending.turnId = e.turnId;
+          event('started', pending, { turnId: e.turnId });
+        }
+      }
+    } catch { /* observation failure cannot rewrite or stop the original turn */ }
+    return next(e);
+  });
+  on('turn.complete', async ($, e, next) => {
+    try {
+      if (!e.agentId) {
+        busy = false;
+        if (alive && pending?.turnId === e.turnId) {
+          if (await identity($)) {
+            const type = e.isAborted || e.reason === 'aborted' ? 'aborted' : e.reason === 'answer' ? 'completed' : 'uncertain';
+            event(type, pending, { turnId: e.turnId, answer: String(e.answer || '').slice(0,100000), reason: e.reason || 'unknown_turn_result' });
+          }
+          pending = null;
+        }
+      }
+    } catch { /* original completion always continues */ }
+    return next(e);
+  });
+  on('session.end', async ($, e, next) => {
+    try { await stop($, e.reason || 'session_ended'); }
+    finally { return next(e); }
+  });
+}

package/lib/integrations/codex-app-probe.mjs

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import WebSocket from 'ws';
+import { CliError } from '../shared/errors.mjs';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value, limit) => typeof value === 'string' && value.length > 0 && value.length <= limit && !/[\x00-\x1f\x7f]/.test(value);
+const statuses = new Set(['notLoaded', 'idle', 'active', 'systemError']);
+const methods = new Set(['initialize', 'thread/read', 'thread/loaded/list']);
+const messages = Object.freeze({
+  DESKTOP_ENDPOINT_UNVERIFIED: 'The endpoint has not been verified as the server used by Codex Desktop.',
+  READ_ONLY_PROBE: 'This probe does not attach, resume, subscribe to, or send input to a thread.',
+  ENDPOINT_UNAVAILABLE: 'The explicitly selected Unix socket is unavailable.',
+  ENDPOINT_CHANGED: 'The selected Unix socket changed during connection setup.',
+  TRANSPORT_FAILED: 'The endpoint did not establish or retain the required WebSocket connection.',
+  PROBE_TIMEOUT: 'The bounded probe deadline expired.',
+  PROTOCOL_INVALID: 'The endpoint returned an invalid or unsupported protocol response.',
+  RESPONSE_LIMIT: 'The endpoint exceeded a probe response limit.',
+  METHOD_UNSUPPORTED: 'The endpoint does not support a required read-only method.',
+  REQUEST_REJECTED: 'The endpoint rejected a read-only probe request.',
+  THREAD_ID_MISMATCH: 'The returned thread identity did not match the requested thread.',
+  CWD_MISMATCH: 'The reported thread working directory did not match the expected absolute path.',
+  THREAD_NOT_LOADED: 'The target thread was not confirmed as loaded in this endpoint.',
+  THREAD_STATE_CHANGED: 'Thread metadata and the loaded-thread list did not agree.',
+  LOADED_LIST_INCOMPLETE: 'The loaded-thread list could not be completed within the page limit.',
+  SERVER_REQUEST_REJECTED: 'The endpoint requested an operation from the probe; the probe rejected it.',
+  DIRECT_INPUT_UNAVAILABLE: 'The endpoint did not advertise direct-input support for the target thread.'
+});
+const failure = code => Object.assign(new Error(code), { code });
+
+function validate(options) {
+  if (!object(options)) throw new CliError('BAD_ARGS', 'Codex probing requires explicit endpoint, thread, and working-directory options.');
+  for (const key of ['socketPath', 'expectedCwd']) {
+    if (!text(options[key], 4096) || !path.isAbsolute(options[key])) {
+      throw new CliError('BAD_ARGS', `${key} must be an explicit absolute path.`);
+    }
+  }
+  if (!text(options.threadId, 512)) throw new CliError('BAD_ARGS', 'threadId must be a nonempty bounded identifier.');
+  const limits = { timeoutMs: [5000, 10, 30000], pageSize: [100, 1, 100], maxPages: [10, 1, 100], maxPayloadBytes: [262144, 1024, 1048576] };
+  const result = { socketPath: options.socketPath, expectedCwd: options.expectedCwd, threadId: options.threadId };
+  for (const [key, [defaultValue, minimum, maximum]] of Object.entries(limits)) {
+    const value = options[key] ?? defaultValue;
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+      throw new CliError('BAD_ARGS', `${key} must be an integer between ${minimum} and ${maximum}.`);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+function socketIdentity(socketPath) {
+  try {
+    const stat = fs.lstatSync(socketPath);
+    if (!stat.isSocket()) throw failure('ENDPOINT_UNAVAILABLE');
+    return { dev: stat.dev, ino: stat.ino };
+  } catch { throw failure('ENDPOINT_UNAVAILABLE'); }
+}
+
+function connectProbe(options, identity, report, addCondition) {
+  let ws, timer, pending, openResolve, openReject, failed, disposed = false;
+  let nextId = 1, frameCount = 0, totalBytes = 0;
+  const byteLimit = Math.min(options.maxPayloadBytes * (options.maxPages + 4), 16 * 1024 * 1024);
+  const opened = new Promise((resolve, reject) => { openResolve = resolve; openReject = reject; });
+  function fail(code) {
+    if (failed || disposed) return;
+    failed = failure(code);
+    openReject(failed);
+    pending?.reject(failed);
+    pending = null;
+  }
+  function write(frame) {
+    if (failed) throw failed;
+    if (disposed || ws.readyState !== WebSocket.OPEN) throw failure('TRANSPORT_FAILED');
+    ws.send(JSON.stringify(frame), error => { if (error) fail('TRANSPORT_FAILED'); });
+  }
+  function onMessage(bytes, binary) {
+    if (failed || disposed) return;
+    totalBytes += bytes.length;
+    if (++frameCount > 1024 || totalBytes > byteLimit) return fail('RESPONSE_LIMIT');
+    if (binary) return fail('PROTOCOL_INVALID');
+    let frame;
+    try { frame = JSON.parse(bytes.toString('utf8')); } catch { return fail('PROTOCOL_INVALID'); }
+    if (!object(frame) || (frame.jsonrpc !== undefined && frame.jsonrpc !== '2.0')) return fail('PROTOCOL_INVALID');
+    if (Object.hasOwn(frame, 'method')) {
+      if (!text(frame.method, 256)) return fail('PROTOCOL_INVALID');
+      if (Object.hasOwn(frame, 'id')) {
+        if (!(Number.isSafeInteger(frame.id) || text(frame.id, 512))) return fail('PROTOCOL_INVALID');
+        addCondition('SERVER_REQUEST_REJECTED');
+        try { write({ id: frame.id, error: { code: -32601, message: 'Read-only probe does not execute server requests.' } }); }
+        catch { fail('TRANSPORT_FAILED'); }
+      }
+      return; // Notifications and their contents are never retained.
+    }
+    if (!pending || frame.id !== pending.id || Object.hasOwn(frame, 'result') === Object.hasOwn(frame, 'error')) return fail('PROTOCOL_INVALID');
+    const operation = pending;
+    pending = null;
+    if (Object.hasOwn(frame, 'error')) {
+      operation.reject(failure(object(frame.error) && frame.error.code === -32601 ? 'METHOD_UNSUPPORTED' : 'REQUEST_REJECTED'));
+    } else operation.resolve(frame.result);
+  }
+  try {
+    // The public UDS transport uses a WebSocket handshake, not stdio JSONL.
+    // No URL, ambient proxy, cookie, auth token, or default socket is accepted.
+    ws = new WebSocket('ws://localhost/', {
+      createConnection: () => net.createConnection({ path: options.socketPath }),
+      followRedirects: false, perMessageDeflate: false,
+      maxPayload: options.maxPayloadBytes, handshakeTimeout: options.timeoutMs
+    });
+    timer = setTimeout(() => fail('PROBE_TIMEOUT'), options.timeoutMs);
+    ws.on('open', () => {
+      if (failed || disposed) return;
+      try {
+        const current = socketIdentity(options.socketPath);
+        if (identity.dev !== current.dev || identity.ino !== current.ino) throw failure('ENDPOINT_CHANGED');
+      } catch { fail('ENDPOINT_CHANGED'); return; }
+      report.transportConnected = true;
+      openResolve();
+    });
+    ws.on('message', onMessage);
+    ws.on('error', error => fail(error.code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH' ? 'RESPONSE_LIMIT' : 'TRANSPORT_FAILED'));
+    ws.on('close', () => fail('TRANSPORT_FAILED'));
+  } catch { fail('TRANSPORT_FAILED'); }
+  return {
+    opened,
+    request(method, params) {
+      if (!methods.has(method) || pending) return Promise.reject(failure('PROTOCOL_INVALID'));
+      return new Promise((resolve, reject) => {
+        const id = nextId++;
+        pending = { id, resolve, reject };
+        try { write({ id, method, params }); }
+        catch (error) { pending = null; reject(error); }
+      });
+    },
+    initialized() { write({ method: 'initialized', params: {} }); },
+    async close() {
+      disposed = true;
+      clearTimeout(timer);
+      if (!ws || ws.readyState === WebSocket.CLOSED) return;
+      // Close this connection only. Never unsubscribe, stop a daemon, or signal
+      // any process. A bounded forced close affects only this probe's socket.
+      await new Promise(resolve => {
+        const closing = setTimeout(() => { ws.terminate(); resolve(); }, 100);
+        ws.once('close', () => { clearTimeout(closing); resolve(); });
+        if (ws.readyState === WebSocket.CONNECTING) ws.terminate();
+        else ws.close();
+      });
+    }
+  };
+}
+
+/** Inspect one explicitly selected public endpoint. This never creates an executor or resumes a thread. */
+export async function probeCodexEndpoint(input) {
+  const options = validate(input);
+  const report = {
+    transportConnected: false, initialized: false, threadMatched: false, cwdMatched: false,
+    loaded: null, status: null, directInputAdvertised: null,
+    checks: { threadRead: false, loadedList: false },
+    writable: false, desktopEndpointVerified: false, unmetConditions: []
+  };
+  const addCondition = code => {
+    if (!report.unmetConditions.some(item => item.code === code)) report.unmetConditions.push({ code, message: messages[code] });
+  };
+  addCondition('DESKTOP_ENDPOINT_UNVERIFIED');
+  addCondition('READ_ONLY_PROBE');
+  let connection;
+  try {
+    const identity = socketIdentity(options.socketPath);
+    connection = connectProbe(options, identity, report, addCondition);
+    await connection.opened;
+    const initialized = await connection.request('initialize', {
+      clientInfo: { name: 'hello_cc_read_only_probe', title: 'hello-cc read-only endpoint probe', version: '1' },
+      capabilities: { experimentalApi: false }
+    });
+    if (!object(initialized) || !text(initialized.userAgent, 1024)) throw failure('PROTOCOL_INVALID');
+    connection.initialized();
+    report.initialized = true;
+    const result = await connection.request('thread/read', { threadId: options.threadId, includeTurns: false });
+    const thread = result?.thread;
+    if (!object(thread) || !text(thread.id, 512)) throw failure('PROTOCOL_INVALID');
+    report.checks.threadRead = true;
+    report.threadMatched = thread.id === options.threadId;
+    if (!report.threadMatched) { addCondition('THREAD_ID_MISMATCH'); return report; }
+    if (!text(thread.cwd, 4096) || !path.isAbsolute(thread.cwd) || !object(thread.status) || !statuses.has(thread.status.type)) throw failure('PROTOCOL_INVALID');
+    report.cwdMatched = path.normalize(thread.cwd) === path.normalize(options.expectedCwd);
+    report.status = thread.status.type;
+    report.directInputAdvertised = typeof thread.canAcceptDirectInput === 'boolean' ? thread.canAcceptDirectInput : null;
+    if (!report.cwdMatched) addCondition('CWD_MISMATCH');
+    if (report.directInputAdvertised !== true) addCondition('DIRECT_INPUT_UNAVAILABLE');
+    let cursor, found = false, complete = false;
+    const cursors = new Set();
+    for (let page = 0; page < options.maxPages; page++) {
+      const list = await connection.request('thread/loaded/list', { limit: options.pageSize, ...(cursor ? { cursor } : {}) });
+      if (!object(list) || !Array.isArray(list.data) || list.data.length > options.pageSize ||
+          !list.data.every(id => text(id, 512)) || (list.nextCursor !== null && !text(list.nextCursor, 4096))) throw failure('PROTOCOL_INVALID');
+      report.checks.loadedList = true;
+      found = list.data.includes(options.threadId);
+      if (found || list.nextCursor === null) { complete = true; break; }
+      if (cursors.has(list.nextCursor)) throw failure('PROTOCOL_INVALID');
+      cursors.add(list.nextCursor);
+      cursor = list.nextCursor;
+    }
+    if (!complete) addCondition('LOADED_LIST_INCOMPLETE');
+    else {
+      report.loaded = found && report.status !== 'notLoaded';
+      if (!report.loaded) addCondition('THREAD_NOT_LOADED');
+      if (found !== (report.status !== 'notLoaded')) addCondition('THREAD_STATE_CHANGED');
+    }
+  } catch (error) {
+    addCondition(Object.hasOwn(messages, error?.code) ? error.code : 'PROTOCOL_INVALID');
+  } finally { await connection?.close(); }
+  return report;
+}