@logicseek/hello-cc 1.1.0-rc.4 → 1.1.0-rc.6

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;
+}

package/lib/integrations/dsh-collaboration.mjs

@@ -55,6 +55,23 @@ export function createDshCollaboration({ sessionId, cwd, maxContextChars = 16000
   const tasks = createTaskStore({ now, addEvent, sendMessage: messages.sendMessage,
     activePeerTtl: 600, observeClockSafety: evidence.observeTaskTakeoverClockSafety });
   const coordination = createCoordinationState({ connect, now, ...messages, ...tasks, ...evidence });
+  // Idle delivery needs its own bounded snapshot. Exclude self-sent rows in
+  // SQL before LIMIT so a long self/broadcast backlog cannot hide new mail.
+  // Rendering and ACK candidates are derived together from this same query.
+  const externalCoordination = createCoordinationState({ connect, now, ...messages, ...tasks, ...evidence,
+    queryInbox(db, selectedPeer, includeAll, limit) {
+      if (selectedPeer !== peer) fail('The inbox peer identity changed');
+      return db.prepare(`
+        SELECT m.id, m.sender, m.recipient, m.task_id, m.kind, m.body,
+               m.reply_to, m.thread_id, m.created_at, r.read_at
+        FROM messages m
+        LEFT JOIN message_reads r ON r.message_id = m.id AND r.peer = ?
+        WHERE (m.recipient IS NULL OR m.recipient = '' OR m.recipient = 'all' OR m.recipient = ?)
+          AND (? = 1 OR r.read_at IS NULL) AND m.sender <> ?
+        ORDER BY m.id ASC LIMIT ?
+      `).all(peer, peer, includeAll ? 1 : 0, peer, limit);
+    }
+  });
   let disposed = false;
   let retiring = false;
   const identity = inspectProcessIdentity(process.pid).identity;
@@ -130,9 +147,9 @@ export function createDshCollaboration({ sessionId, cwd, maxContextChars = 16000
     queue = run.catch(() => {});
     return run;
   }
-  function snapshot() {
+  function snapshot({ externalOnly = false } = {}) {
     return owned(db => {
-      const state = coordination.buildHookCoordinationContext(db, ctx, peer);
+      const state = (externalOnly ? externalCoordination : coordination).buildHookCoordinationContext(db, ctx, peer);
       const prefix = '[hello-cc Cordis collaboration]\nUse the hcc_* tools for this Agent. They fix the project and peer; do not impersonate other sessions.\n';
       const text = prefix + redactSecrets(state.text);
       const complete = text.length <= maxContextChars;

package/lib/integrations/dsh-cordis.d.ts

@@ -6,6 +6,8 @@ export interface DshCollaborationConfig {
   maxContextChars?: number;
   /** Bounded lossless-JSON tool presentation, 2048-64000 characters. Default 16000. */
   maxToolChars?: number;
+  /** Idle inbox poll interval, 100-60000 ms. Default 1000; 0 disables automatic idle wakeup. */
+  inboxPollMs?: number;
 }
 export const name: 'hello-cc-dsh-collaboration';
 export const inject: readonly ['agents', 'tools', 'sessions'];

package/lib/integrations/dsh-cordis.mjs

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { createDshCollaboration } from './dsh-collaboration.mjs';
 import { scopedMcpToolDefinitions } from '../mcp/tools.mjs';
+import { createDshInbox } from './dsh-inbox.mjs';
 
 export const name = 'hello-cc-dsh-collaboration';
 export const inject = ['agents', 'tools', 'sessions'];
@@ -88,7 +89,8 @@ function contextMessage(text) {
     content: Object.freeze([Object.freeze({ type: 'text', text })]) });
 }
 
-export function createDshCordisPlugin({ checkRuntime = checkDshRuntime, createCollaboration = createDshCollaboration } = {}) {
+export function createDshCordisPlugin({ checkRuntime = checkDshRuntime, createCollaboration = createDshCollaboration,
+  createInbox = createDshInbox } = {}) {
   return function apply(ctx, config = {}) {
     checkRuntime();
     const bounds = {};
@@ -97,8 +99,11 @@ export function createDshCordisPlugin({ checkRuntime = checkDshRuntime, createCo
       if (!Number.isSafeInteger(value) || value < 2048 || value > 64000) throw new TypeError(`${key} must be an integer from 2048 to 64000`);
       bounds[key] = value;
     }
+    const inboxPollMs = config.inboxPollMs ?? 1000;
+    if (!Number.isSafeInteger(inboxPollMs) || (inboxPollMs !== 0 && (inboxPollMs < 100 || inboxPollMs > 60000))) {
+      throw new TypeError('inboxPollMs must be 0 or an integer from 100 to 60000');
+    }
     const states = new Map();
-    const pending = new Map();
     let disposed = false;
     function ensure(agent) {
       if (disposed) throw new Error('hello-cc Cordis plugin has been disposed');
@@ -112,47 +117,43 @@ export function createDshCordisPlugin({ checkRuntime = checkDshRuntime, createCo
       }
       return state;
     }
-    function context(agent) {
-      const state = ensure(agent);
-      for (const [id, entry] of pending) if (entry.session === agent.session) pending.delete(id);
-      const snapshot = state.snapshot();
-      const message = contextMessage(snapshot.text);
-      if (snapshot.messages.length) pending.set(message.id, { session: agent.session, state, messages: snapshot.messages });
-      return { message, snapshot };
-    }
+    const inbox = createInbox({ ctx, ensure, contextMessage, pollMs: inboxPollMs });
+    ctx.on('dispose', () => {
+      disposed = true;
+      inbox.dispose();
+      for (const [agent, state] of states) {
+        try { retire(agent, state, { contextDisposed: true }, () => states.delete(agent)); }
+        catch (error) { ctx.logger?.warn(String(error)); }
+      }
+    });
     function close(agent) {
       disposedAgents.add(agent);
       const state = states.get(agent) || failedRetirements.get(agent)?.state;
-      for (const [id, entry] of pending) if (entry.session === agent.session) pending.delete(id);
+      inbox.forget(agent);
       if (state) retire(agent, state, { agentDisposed: true }, () => states.delete(agent));
     }
     // Awaited serial event; no detached setup races with the first model turn.
     ctx.on('agent/created', async ({ agent, signal }) => { signal?.throwIfAborted(); ensure(agent); }, { prepend: true });
-    ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+    ctx.on('agent/pre-step', async ({ agent, signal, messages }, next) => {
       signal.throwIfAborted();
       ensure(agent);
       const decision = await next();
-      if (decision.kind !== 'enter') return decision;
       signal.throwIfAborted();
-      const { message } = context(agent);
-      return { ...decision, messages: [...decision.messages, message] };
+      return inbox.step(agent, decision, messages);
     });
     // ACK only after Harness commits the exact model-visible context. Rejected
     // admission, failed preparation and cancelled turns leave the inbox unread.
-    ctx.on('session/event', (session, event) => {
-      if (event.type !== 'user/message') return;
-      const entry = pending.get(event.data.id);
-      if (!entry || entry.session !== session) return;
-      pending.delete(event.data.id);
-      entry.state.ack(entry.messages);
+    ctx.on('session/event', (session, event) => inbox.commit(session, event));
+    ctx.on('agent/inbox/claimed', ({ agent, message }) => inbox.claimed(agent, message));
+    ctx.on('agent/inbox/discarded', ({ agent, message }) => inbox.discarded(agent, message));
+    ctx.on('agent/status', ({ agent, status }) => {
+      if (status === 'idle') inbox.idle(agent);
+      if (states.has(agent)) states.get(agent).status(status);
     });
-    ctx.on('agent/status', ({ agent, status }) => { if (states.has(agent)) states.get(agent).status(status); });
     ctx.on('agent/disposed', ({ agent }) => close(agent));
     ctx.on('agent/turn-stopping', ({ agent, signal }) => {
       signal.throwIfAborted();
-      const { message, snapshot } = context(agent);
-      if (snapshot.complete && snapshot.hasUnread) agent.steer(message);
-      else pending.delete(message.id);
+      inbox.steer(agent);
     });
     ctx.on('tools/pre-execute', async (exec, next) => {
       const decision = await next();
@@ -167,14 +168,6 @@ export function createDshCordisPlugin({ checkRuntime = checkDshRuntime, createCo
       output: { schema: {}, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] },
       execute: async (args, exec) => ensure(exec.agent).call(tool.name, args, exec.signal)
     });
-    ctx.on('dispose', () => {
-      disposed = true;
-      pending.clear();
-      for (const [agent, state] of states) {
-        try { retire(agent, state, { contextDisposed: true }, () => states.delete(agent)); }
-        catch (error) { ctx.logger?.warn(String(error)); }
-      }
-    });
   };
 }
 

package/lib/integrations/dsh-inbox.mjs

@@ -0,0 +1,251 @@
+// Official Agent inbox delivery. A queued wake is not a read receipt: only the
+// corresponding committed user/message can acknowledge coordination messages.
+const registryKey = Symbol.for('@logicseek/hello-cc/dsh-inbox/receipts/v1');
+if (!Object.hasOwn(globalThis, registryKey)) {
+  Object.defineProperty(globalThis, registryKey, { value: new WeakMap() });
+}
+const receipts = globalThis[registryKey];
+const handoffKey = Symbol.for('@logicseek/hello-cc/dsh-inbox/handoffs/v1');
+if (!Object.hasOwn(globalThis, handoffKey)) {
+  Object.defineProperty(globalThis, handoffKey, {
+    value: Object.freeze({ pending: new WeakMap(), blocked: new WeakMap() })
+  });
+}
+const handoffs = globalThis[handoffKey];
+const signature = messages => JSON.stringify(messages.map(message => message.id));
+const sameContents = (left, right) => isDeepStrictEqual(
+  [left.source, left.content], [right.source, right.content]);
+
+export function createDshInbox({ ctx, ensure, contextMessage, pollMs,
+  schedule = setTimeout, unschedule = clearTimeout }) {
+  const pending = new Map(), agents = new Map();
+  let stopped = false, polling = false, timer;
+
+  function entryFor(agent) {
+    let entry = agents.get(agent);
+    if (!entry) {
+      entry = { wake: null, blocked: handoffs.blocked.get(agent) || null, warned: false };
+      agents.set(agent, entry);
+    }
+    return entry;
+  }
+  function warn(agent) {
+    const entry = entryFor(agent);
+    if (entry.warned) return;
+    entry.warned = true;
+    // Runtime errors can contain user paths or configuration. Log no payload.
+    try { ctx.logger?.warn('hello-cc inbox delivery deferred; it will retry after the runtime recovers'); } catch {}
+  }
+  function acknowledge(agent) {
+    const saved = receipts.get(agent);
+    if (!saved?.size) return;
+    const state = ensure(agent);
+    for (const [id, receipt] of saved) {
+      if (receipt.session !== agent.session) throw new Error('Cordis receipt Session changed');
+      state.ack(receipt.messages);
+      saved.delete(id);
+    }
+    receipts.delete(agent);
+  }
+  function clearPending(agent, except = null) {
+    for (const [id, delivery] of pending) {
+      if (delivery.agent === agent && id !== except && !delivery.queued) pending.delete(id);
+    }
+  }
+  function prepare(agent, externalOnly = false) {
+    acknowledge(agent);
+    const state = ensure(agent);
+    const snapshot = state.snapshot({ externalOnly });
+    const message = contextMessage(snapshot.text);
+    const delivery = { agent, session: agent.session, message, messages: snapshot.messages,
+      signature: signature(snapshot.messages),
+      externalSignature: signature(snapshot.messages.filter(item => item.sender !== state.peer)),
+      queued: false, claimed: false };
+    if (snapshot.messages.length) pending.set(message.id, delivery);
+    return { state, message, snapshot, delivery };
+  }
+  function block(agent, delivery) {
+    if (!delivery) return;
+    const entry = entryFor(agent);
+    entry.blocked = { all: delivery.signature, external: delivery.externalSignature };
+    handoffs.blocked.set(agent, entry.blocked);
+    if (entry.wake === delivery) entry.wake = null;
+    pending.delete(delivery.message.id);
+  }
+  function queued(agent, id) {
+    return [...(agent.inbox?.nextTurn || []), ...(agent.inbox?.nextStep || [])].some(message => message.id === id);
+  }
+  function live(agent) {
+    return !stopped && ctx.agents?.get(agent.session.header.id) === agent;
+  }
+  function adopt(agent) {
+    const carried = handoffs.pending.get(agent);
+    if (!carried) return;
+    const entry = entryFor(agent);
+    for (const delivery of carried.values()) {
+      if (delivery.session !== agent.session) throw new Error('Cordis pending Session changed');
+      pending.set(delivery.message.id, delivery);
+      if (delivery.queued) entry.wake = delivery;
+      // A commit during the reload gap cannot be inferred from idle. Preserve
+      // unread data and suppress an automatic replay of that uncertain batch.
+      if (agent.status === 'idle' && !queued(agent, delivery.message.id)) block(agent, delivery);
+    }
+    handoffs.pending.delete(agent);
+  }
+  function enqueue(agent, method) {
+    adopt(agent);
+    const entry = entryFor(agent);
+    if (entry.wake) return;
+    clearPending(agent);
+    const prepared = prepare(agent, method === 'followup');
+    const { state, snapshot, delivery, message } = prepared;
+    const blocked = method === 'followup'
+      ? entry.blocked?.external === delivery.externalSignature
+      : entry.blocked?.all === delivery.signature;
+    if (!snapshot.complete || !snapshot.hasUnread || !snapshot.messages.length ||
+        (method === 'followup' && !snapshot.messages.some(item => item.sender !== state.peer)) ||
+        blocked) {
+      pending.delete(message.id);
+      return;
+    }
+    // Snapshot verifies the exact project/peer owner immediately before send.
+    if (!live(agent) || (method === 'followup' &&
+        (agent.status !== 'idle' || agent.inbox?.hasPending))) {
+      pending.delete(message.id);
+      return;
+    }
+    entry.wake = delivery;
+    delivery.queued = true;
+    try { agent[method](message); }
+    catch (error) {
+      // A runtime failure after insertion must not enqueue a second copy.
+      if (!queued(agent, message.id) && !delivery.claimed) {
+        pending.delete(message.id);
+        if (entry.wake === delivery) entry.wake = null;
+      }
+      throw error;
+    }
+  }
+  function arm() {
+    if (!stopped && pollMs > 0) {
+      timer = schedule(poll, pollMs);
+      timer?.unref?.();
+    }
+  }
+  function poll() {
+    if (stopped || polling) return;
+    polling = true;
+    try {
+      // Also discovers already-live Agents after profile hot reload. It never
+      // resumes cold sessions or creates a provider process.
+      for (const agent of ctx.agents?.list() || []) {
+        if (!live(agent)) continue;
+        try {
+          ensure(agent);
+          adopt(agent);
+          acknowledge(agent);
+          if (agent.status === 'idle' && !agent.inbox?.hasPending) enqueue(agent, 'followup');
+          entryFor(agent).warned = false;
+        } catch { warn(agent); }
+      }
+    } catch {
+      // Registry enumeration can fail during Host disposal; the next poll can
+      // recover without an uncaught timer exception or an overlapping scan.
+    } finally {
+      polling = false;
+      arm();
+    }
+  }
+  arm();
+  return {
+    step(agent, decision, proposed = []) {
+      adopt(agent);
+      const entry = entryFor(agent), wake = entry.wake;
+      ensure(agent);
+      if (decision.kind !== 'enter') {
+        if (wake && proposed.some(message => message.id === wake.message.id)) block(agent, wake);
+        return decision;
+      }
+      acknowledge(agent);
+      // Keep the exact queued context once. The downstream admission chain may
+      // remove it; do not put rejected content back or acknowledge altered text.
+      if (wake && proposed.some(message => message.id === wake.message.id)) {
+        const accepted = decision.messages.find(message => message.id === wake.message.id);
+        if (!accepted || !sameContents(accepted, wake.message)) block(agent, wake);
+        else ensure(agent).snapshot();
+        return decision;
+      }
+      clearPending(agent);
+      const { message } = prepare(agent);
+      return { ...decision, messages: [...decision.messages, message] };
+    },
+    commit(session, event) {
+      if (stopped || event.type !== 'user/message') return;
+      if (!pending.has(event.data.id)) {
+        const agent = ctx.agents?.get(session.header.id);
+        if (agent?.session === session) adopt(agent);
+      }
+      const delivery = pending.get(event.data.id);
+      if (!delivery || delivery.session !== session || !sameContents(event.data, delivery.message)) return;
+      pending.delete(event.data.id);
+      const entry = entryFor(delivery.agent);
+      if (entry.wake === delivery) entry.wake = null;
+      entry.blocked = null;
+      handoffs.blocked.delete(delivery.agent);
+      const saved = receipts.get(delivery.agent) || new Map();
+      saved.set(event.data.id, delivery);
+      receipts.set(delivery.agent, saved);
+      try { acknowledge(delivery.agent); } catch { warn(delivery.agent); }
+    },
+    claimed(agent, message) {
+      adopt(agent);
+      const delivery = pending.get(message.id);
+      if (delivery?.agent === agent) delivery.claimed = true;
+    },
+    discarded(agent, message) {
+      if (stopped) return;
+      adopt(agent);
+      const delivery = pending.get(message.id);
+      if (delivery?.agent === agent) block(agent, delivery);
+    },
+    idle(agent) {
+      adopt(agent);
+      // Failed preparation/cancellation after claim leaves unread input. Wait
+      // for explicit work or a different unread batch instead of a prompt loop.
+      for (const delivery of pending.values()) {
+        if (delivery.agent === agent && (delivery.claimed || !delivery.queued)) block(agent, delivery);
+      }
+    },
+    steer(agent) { enqueue(agent, 'steer'); },
+    forget(agent) {
+      const wake = agents.get(agent)?.wake;
+      if (wake && queued(agent, wake.message.id)) {
+        try { agent.inbox.remove(wake.message.id); } catch { warn(agent); }
+      }
+      for (const [id, delivery] of pending) if (delivery.agent === agent) pending.delete(id);
+      agents.delete(agent);
+      handoffs.pending.delete(agent);
+      handoffs.blocked.delete(agent);
+    },
+    dispose() {
+      stopped = true;
+      unschedule(timer);
+      for (const agent of [...agents.keys()]) {
+        const wake = agents.get(agent)?.wake;
+        if (wake && queued(agent, wake.message.id)) {
+          try {
+            if (agent.inbox.remove(wake.message.id)) pending.delete(wake.message.id);
+          } catch { warn(agent); }
+        }
+      }
+      for (const delivery of pending.values()) {
+        const carried = handoffs.pending.get(delivery.agent) || new Map();
+        carried.set(delivery.message.id, delivery);
+        handoffs.pending.set(delivery.agent, carried);
+      }
+      pending.clear();
+      agents.clear();
+    }
+  };
+}
+import { isDeepStrictEqual } from 'node:util';

package/lib/ui/help.mjs

@@ -16,6 +16,7 @@ Usage:
 Commands:
   web                          Start coordination, shims, tmux, and browser console
   dsh <setup|status|web>        Connect DeepSeek Harness through project-local hooks
+  app <claude|codex>           Bridge opt-in Desktop sessions or probe an explicit endpoint
   native <subcommand>           Run owned Codex/Claude/dsh workers through native protocols
   up                           Initialize local coordination only
   down                         Stop the running hello-cc web runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "1.1.0-rc.4",
+  "version": "1.1.0-rc.6",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {