@logicseek/hello-cc 1.0.1 → 1.0.2

package/lib/core/peers/bindings.mjs

@@ -18,9 +18,9 @@ export function bindingFromDetected(peer, transport = 'detected') {
 export function peerBindingRuntimeRank(row) {
   if (row?.runtime_target && row.transport === 'tmux') return 50;
   if (row?.runtime_target) return 40;
-  if (['tmux', 'web-pty'].includes(row?.transport)) return 30;
+  if (['tmux', 'web-pty', 'app-server'].includes(row?.transport)) return 30;
   if (row?.transport === 'hcc-run') return 20;
-  if (row?.transport === 'hook') return 10;
+  if (['hook', 'cordis'].includes(row?.transport)) return 10;
   if (row?.transport === 'detected') return 5;
   return 0;
 }
@@ -41,7 +41,13 @@ export function bindingProviderSessionValue(binding) {
 }
 
 export function bindingHasRuntime(binding) {
-  return Boolean(binding?.runtime_target) || ['tmux', 'web-pty'].includes(binding?.transport);
+  return Boolean(binding?.runtime_target) || ['tmux', 'web-pty', 'app-server'].includes(binding?.transport);
+}
+
+// A dsh runtime hosts independent agents. Its process/pane is evidence of
+// liveness, not an interactive terminal belonging to any one agent.
+export function isDshHookBinding(binding) {
+  return (binding?.provider || binding?.kind) === 'dsh' && ['hook', 'cordis'].includes(binding?.transport);
 }
 
 export function mergeRuntimeBinding(existing, binding) {

package/lib/diagnostics/codex.mjs

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop'];
+const INVOCATION_TYPES = ['hook.sessionstart', 'hook.userpromptsubmit', 'hook.pretooluse', 'hook.posttooluse', 'hook.stop'];
+const MAX_PROBE_BYTES = 64 * 1024;
+const MAX_HOOK_BYTES = 1024 * 1024;
+
+export function unknownCodexDiagnostics(reason = 'diagnostic_unavailable') {
+  return { installed: { status: 'unknown' }, version: { status: 'unknown', value: null, reason },
+    app_server: { status: 'unknown', startup_arguments: null, protocol_handshake: 'unknown', reason },
+    hooks: { configuration: { status: 'unknown', reason }, invocation: { status: 'unknown', evidence: null, reason },
+      stdout_delivery_receipt: { status: 'unknown', reason: 'no_explicit_stdout_delivery_receipt_is_recorded' },
+      provider_acceptance: 'unknown', trust: 'unknown' }, inference_called: false };
+}
+
+function probeFailure(result) {
+  if (result?.error?.code === 'ENOENT') return 'not_found';
+  if (result?.error?.code === 'ETIMEDOUT') return 'timed_out';
+  return 'probe_failed';
+}
+
+function runProbe(args, ctx, env, run) {
+  try {
+    return run('codex', args, { cwd: ctx.root,
+      env: { ...env, HCC_SHIM_NO_ATTACH: '1', HCC_SHIM_ENSURED: '1' },
+      encoding: 'utf8', timeout: 2000, killSignal: 'SIGKILL', maxBuffer: MAX_PROBE_BYTES,
+      shell: false, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return { status: null, error: { code: 'PROBE_FAILED' } };
+  }
+}
+
+function isolatedProbes(ctx, env, run) {
+  let directory;
+  try {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'hcc-codex-doctor-'));
+    const probeHome = path.join(directory, 'home');
+    const probeCodexHome = path.join(directory, 'codex-home');
+    fs.mkdirSync(probeHome); fs.mkdirSync(probeCodexHome);
+    // Even --version/--help can create Codex startup wrappers. Keep those
+    // writes away from the user's account/configuration directories.
+    const probeEnv = { ...env, HOME: probeHome, USERPROFILE: probeHome, CODEX_HOME: probeCodexHome };
+    return { version: runProbe(['--version'], ctx, probeEnv, run),
+      help: runProbe(['app-server', '--help'], ctx, probeEnv, run) };
+  } catch {
+    const unavailable = { status: null, error: { code: 'PROBE_FAILED' } };
+    return { version: unavailable, help: unavailable };
+  } finally {
+    if (directory) fs.rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+function hooksConfiguration(env, homedir) {
+  const directory = env.CODEX_HOME || path.join(homedir(), '.codex');
+  const file = path.resolve(directory, 'hooks.json');
+  const result = { status: 'unknown', path: file, matched_events: [], required_events: [...HOOK_EVENTS] };
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.size > MAX_HOOK_BYTES) return { ...result, reason: 'unreadable_configuration' };
+    // Only this hooks file is inspected. Commands and arbitrary configuration
+    // values never enter the diagnostic output or get executed.
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    for (const event of HOOK_EVENTS) {
+      const entries = value?.hooks?.[event];
+      if (Array.isArray(entries) && entries.some(entry => Array.isArray(entry?.hooks) &&
+          entry.hooks.some(hook => hook?.type === 'command' && typeof hook.command === 'string' &&
+            (/\bhcc\b.*\bhook\b/.test(hook.command) || /hello-cc.*hook/.test(hook.command))))) {
+        result.matched_events.push(event);
+      }
+    }
+    return { ...result, status: result.matched_events.length === HOOK_EVENTS.length ? 'present' : 'missing' };
+  } catch (error) {
+    return { ...result, status: error?.code === 'ENOENT' ? 'missing' : 'unknown',
+      reason: error?.code === 'ENOENT' ? 'file_not_found' : 'unreadable_configuration' };
+  }
+}
+
+function hookInvocation(db) {
+  const result = { status: 'unknown', evidence: null, provider_at_event: 'unknown',
+    scope: 'project events matched to the current Codex peer kind; historical provider identity is not verified' };
+  try {
+    const placeholders = INVOCATION_TYPES.map(() => '?').join(',');
+    const row = db.prepare(`SELECT e.id, e.type, e.created_at FROM events e
+      JOIN peers p ON p.id = e.actor WHERE p.kind = 'codex' AND e.type IN (${placeholders})
+      ORDER BY e.id DESC LIMIT 1`).get(...INVOCATION_TYPES);
+    return row ? { ...result, status: 'present', evidence: { event_id: row.id, type: row.type, created_at: row.created_at } }
+      : { ...result, reason: 'no_matching_invocation' };
+  } catch {
+    return { ...result, reason: 'events_unavailable' };
+  }
+}
+
+// Explicitly opt-in and read-only: no server/session is started, hooks are not
+// executed, and no account, auth.json, config.toml or trust state is inspected.
+export function diagnoseCodex(ctx, db, { env = process.env, run = spawnSync, homedir = os.homedir } = {}) {
+  const probes = isolatedProbes(ctx, env, run);
+  const versionProbe = probes.version;
+  const versionText = !versionProbe.error && versionProbe.status === 0 ? String(versionProbe.stdout || '').trim() : '';
+  const match = versionText.match(/^codex(?:-cli)?\s+(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)$/);
+  const version = match ? { status: 'known', value: match[1], evidence: 'codex --version' }
+    : { status: 'unknown', value: null, reason: versionText ? 'unexpected_output' : probeFailure(versionProbe) };
+  const helpProbe = probes.help;
+  const help = !helpProbe.error && helpProbe.status === 0 ? String(helpProbe.stdout || '') : '';
+  const advertised = /\bUsage:\s+codex\s+app-server(?:\s|$)/i.test(help);
+  const startup = /(?:^|\s)--listen(?=\s|[=,]|$)/m.test(help) && /stdio:\/\//.test(help)
+    ? ['--listen', 'stdio://'] : /(?:^|\s)--stdio(?=\s|[=,]|$)/m.test(help) ? ['--stdio'] : null;
+  const appServer = { status: advertised ? 'advertised' : 'unknown',
+    startup_arguments: advertised ? startup : null, protocol_handshake: 'unknown',
+    ...(advertised ? { evidence: 'codex app-server --help' }
+      : { reason: help ? 'unexpected_output' : probeFailure(helpProbe) }) };
+  return { installed: { status: match || advertised ? 'present'
+      : versionProbe.error?.code === 'ENOENT' && helpProbe.error?.code === 'ENOENT' ? 'missing' : 'unknown' },
+    version, app_server: appServer,
+    hooks: { configuration: hooksConfiguration(env, homedir), invocation: hookInvocation(db),
+      stdout_delivery_receipt: { status: 'unknown', reason: 'no_explicit_stdout_delivery_receipt_is_recorded' },
+      provider_acceptance: 'unknown', trust: 'unknown' },
+    inference_called: false };
+}

package/lib/integrations/codex-interactions.mjs

@@ -0,0 +1,114 @@
+// Shared validation for the official App Server command/file/permissions/input
+// server requests. Human responses may narrow a request, never widen it.
+export const CODEX_INTERACTION_METHODS = new Set([
+  'item/commandExecution/requestApproval', 'item/fileChange/requestApproval',
+  'item/permissions/requestApproval', 'item/tool/requestUserInput', 'mcpServer/elicitation/request'
+]);
+// These per-thread switches expose the model tools served by our responder.
+// They are experimental in Codex 0.144.6; they grant no permissions and never
+// write the caller's global config. Noninteractive adapters retain defaults.
+export function codexInteractiveConfig(config = {}, interactive = true) {
+  return { ...config, ...(interactive ? {
+    'features.default_mode_request_user_input': true,
+    'features.request_permissions_tool': true
+  } : {}) };
+}
+export function codexInteractionKind(method) {
+  return method === 'mcpServer/elicitation/request' ? 'mcp' : method === 'item/tool/requestUserInput' ? 'userInput'
+    : method === 'item/permissions/requestApproval' ? 'permissions' : 'approval';
+}
+export function cancelCodexInteraction(method) {
+  return method === 'mcpServer/elicitation/request' ? { action: 'cancel' } : method === 'item/tool/requestUserInput' ? { answers: {} }
+    : method === 'item/permissions/requestApproval' ? { permissions: {}, scope: 'turn' } : { decision: 'cancel' };
+}
+function fail(message) { throw Object.assign(new Error(message), { code: 'INTERACTION_RESPONSE_INVALID' }); }
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+function keys(value, allowed) {
+  if (!object(value) || Object.keys(value).some(key => !allowed.includes(key))) fail('Unexpected interaction response fields');
+}
+function same(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => same(v, b[i]));
+  if (object(a) || object(b)) return object(a) && object(b) && Object.keys(a).length === Object.keys(b).length && Object.keys(a).every(key => Object.hasOwn(b, key) && same(a[key], b[key]));
+  return a === b;
+}
+function subset(selected, requested) {
+  if (!Array.isArray(selected) || !Array.isArray(requested) || selected.length > requested.length ||
+      selected.some((entry, index) => !requested.some(value => same(entry, value)) || selected.slice(0, index).some(value => same(entry, value)))) {
+    fail('Granted permissions must be an exact subset of the requested permissions');
+  }
+}
+// Codex 0.144.6 hosts MCP tool approvals as an empty form elicitation.
+// Return the official action/content shape. Do not persist permission in _meta,
+// and do not pretend arbitrary form fields or URL authentication were answered.
+function mcpResponse(request, input) {
+  if (!['accept', 'decline', 'cancel'].includes(input.decision)) fail('An MCP approval decision is required');
+  if (input.decision !== 'accept') return { action: input.decision };
+  const params = request.params, schema = params?.requestedSchema;
+  if (params?.mode !== 'form' || params?._meta?.codex_approval_kind !== 'mcp_tool_call' ||
+      !object(schema) || schema.type !== 'object' || !object(schema.properties) ||
+      Object.keys(schema.properties).length || (schema.required?.length || 0) ||
+      Object.keys(schema).some(key => !['type', 'properties', 'required', 'additionalProperties'].includes(key))) {
+    fail('Only an explicit empty-form MCP tool approval is supported; decline or cancel other elicitations');
+  }
+  return { action: 'accept', content: {} };
+}
+
+function permissionsResponse(request, input) {
+  if (['decline', 'cancel'].includes(input.decision)) return { permissions: {}, scope: 'turn' };
+  if (input.decision !== 'accept') fail('A permission decision is required');
+  const requested = request.params.permissions;
+  keys(requested, ['fileSystem', 'network']);
+  const selected = input.permissions;
+  keys(selected, ['fileSystem', 'network']);
+  if (!['turn', 'session'].includes(input.scope)) fail('Choose an explicit turn or session permission scope');
+  if (selected.network != null) {
+    keys(selected.network, ['enabled']);
+    if (selected.network.enabled !== true || requested.network?.enabled !== true) fail('Network access was not requested');
+  }
+  if (selected.fileSystem != null) {
+    const fs = selected.fileSystem, wanted = requested.fileSystem;
+    keys(fs, ['read', 'write', 'entries', 'globScanMaxDepth']);
+    keys(wanted, ['read', 'write', 'entries', 'globScanMaxDepth']);
+    for (const field of ['read', 'write', 'entries']) {
+      if (fs[field] != null) subset(fs[field], wanted[field]);
+    }
+    // Deny entries constrain other granted paths; dropping them would widen access.
+    if ((wanted.entries || []).some(entry => entry.access === 'deny' && !(fs.entries || []).some(value => same(entry, value)))) {
+      fail('Requested filesystem deny entries must be retained');
+    }
+    if (fs.globScanMaxDepth != null && (!Number.isSafeInteger(fs.globScanMaxDepth) || fs.globScanMaxDepth < 1 || fs.globScanMaxDepth !== wanted.globScanMaxDepth)) {
+      fail('Filesystem scan depth must match the request');
+    }
+  }
+  return { permissions: structuredClone(selected), scope: input.scope };
+}
+function inputResponse(request, input) {
+  if (input.decision === 'cancel') return { answers: {} };
+  const questions = request.params.questions;
+  if (!Array.isArray(questions) || !questions.length || questions.length > 20) fail('Questions cannot be answered safely');
+  const ids = questions.map(q => q?.id);
+  if (ids.some(id => typeof id !== 'string' || !id || id.length > 512) || new Set(ids).size !== ids.length) fail('Question identities are invalid');
+  keys(input.answers, ids);
+  if (Object.keys(input.answers).length !== ids.length) fail('Answer every question explicitly');
+  const answers = Object.create(null);
+  for (const q of questions) {
+    const entry = input.answers[q.id];
+    keys(entry, ['answers']);
+    if (!Array.isArray(entry.answers) || entry.answers.length !== 1 || typeof entry.answers[0] !== 'string' ||
+        !entry.answers[0].trim() || entry.answers[0].length > 8192) fail('Each question needs one nonempty answer');
+    if (q.options?.length && !q.isOther && !q.options.some(option => option.label === entry.answers[0])) fail('Choose an offered answer');
+    answers[q.id] = { answers: [...entry.answers] };
+  }
+  return { answers };
+}
+export function codexInteractionResponse(request, input) {
+  const granting = request.kind === 'userInput' ? input.decision !== 'cancel' : input.decision === 'accept';
+  if (request.truncated && granting) throw Object.assign(new Error('Interaction details are truncated; cancel or decline this request'), { code: 'INTERACTION_TRUNCATED' });
+  if (request.method === 'mcpServer/elicitation/request') return mcpResponse(request, input);
+  if (request.kind === 'permissions') return permissionsResponse(request, input);
+  if (request.kind === 'userInput') return inputResponse(request, input);
+  if (!['accept', 'decline', 'cancel'].includes(input.decision)) fail('Approval decision is invalid');
+  if (input.decision === 'accept' && Array.isArray(request.params.availableDecisions) &&
+      !request.params.availableDecisions.includes('accept')) fail('This command did not offer approval');
+  return { decision: input.decision };
+}

package/lib/integrations/dsh-collaboration.mjs

@@ -0,0 +1,170 @@
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../shared/errors.mjs';
+import { redactSecrets } from '../shared/redact.mjs';
+import { tx } from '../db/schema.mjs';
+import { createConnectionHelpers } from '../db/connection.mjs';
+import { createEventHelpers } from '../db/events.mjs';
+import { createPeerBindingStore } from '../db/stores/peers.mjs';
+import { createPeerHelpers } from '../core/peers/peer-helpers.mjs';
+import { providerSessionPeerId } from '../core/peers/session.mjs';
+import { createMessageStore } from '../core/coordination/messages.mjs';
+import { createTaskStore } from '../core/coordination/tasks.mjs';
+import { createEvidenceRuntime } from '../core/peers/evidence-runtime.mjs';
+import { createCoordinationState } from '../coordination-state.mjs';
+import { createScopedMcpTools } from '../mcp/tools.mjs';
+import { resolveProjectDatabase } from '../runtime/project-path.mjs';
+import { registerProjectActivity } from '../runtime/projects.mjs';
+import { inspectProcessIdentity } from '../process/identity.mjs';
+
+const fail = (message) => { throw new CliError('DSH_COLLABORATION_CONFLICT', message); };
+
+function verifiedDeadOwner(peer) {
+  if (!Number.isSafeInteger(peer?.pid) || peer.pid <= 0 ||
+      typeof peer.pid_start_token !== 'string' || !peer.pid_start_token ||
+      typeof peer.pid_command_hash !== 'string' || !/^[a-f0-9]{64}$/.test(peer.pid_command_hash)) return false;
+  const observed = inspectProcessIdentity(peer.pid);
+  if (observed.state === 'dead') return true;
+  // A recycled PID has a different start token. A changed command alone does
+  // not prove the original process exited (a live process may change its title).
+  return observed.state === 'live' && observed.identity?.pid === peer.pid &&
+    typeof observed.identity.startToken === 'string' &&
+    typeof observed.identity.commandHash === 'string' && /^[a-f0-9]{64}$/.test(observed.identity.commandHash) &&
+    observed.identity.startToken !== peer.pid_start_token;
+}
+
+// One in-process authority per Agent. All mutations still go through the same
+// transactional business functions as the CLI and scoped MCP server.
+export function createDshCollaboration({ sessionId, cwd, maxContextChars = 16000, maxToolChars = 16000 }) {
+  if (typeof sessionId !== 'string' || !sessionId || sessionId.length > 1024 ||
+      sessionId.trim() !== sessionId || /[\u0000-\u001f\u007f]/.test(sessionId) ||
+      typeof cwd !== 'string' || !path.isAbsolute(cwd)) fail('Agent requires its real session ID and absolute cwd');
+  const project = resolveProjectDatabase({ root: cwd, createStateDir: true });
+  const ctx = { root: project.root, cwd: project.root, dbPath: project.db, json: true };
+  const peer = providerSessionPeerId('dsh', sessionId);
+  const owner = `cordis:${randomUUID()}`;
+  const now = () => Math.floor(Date.now() / 1000);
+  const { addEvent } = createEventHelpers({ now });
+  const bindings = createPeerBindingStore({ now, addEvent });
+  const { connect: baseConnect } = createConnectionHelpers({ now,
+    dedupePeerBindings: bindings.dedupePeerBindings, redactedLogText: text => redactSecrets(text) });
+  const connect = (context = ctx, options = {}) => baseConnect(context, { ...options, migrateRegistered: false });
+  const peers = createPeerHelpers({ now, addEvent });
+  const messages = createMessageStore({ now, addEvent });
+  const evidence = createEvidenceRuntime({ now });
+  const tasks = createTaskStore({ now, addEvent, sendMessage: messages.sendMessage,
+    activePeerTtl: 600, observeClockSafety: evidence.observeTaskTakeoverClockSafety });
+  const coordination = createCoordinationState({ connect, now, ...messages, ...tasks, ...evidence });
+  let disposed = false;
+  let retiring = false;
+  const identity = inspectProcessIdentity(process.pid).identity;
+  if (!identity) fail('Cannot establish the owning Harness process identity');
+
+  const db = connect();
+  try {
+    tx(db, () => {
+      const previous = db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(peer);
+      const previousPeer = db.prepare('SELECT * FROM peers WHERE id = ?').get(peer);
+      if (previous || previousPeer) {
+        // Retain the raw ID after disposal to detect hash collisions on resume.
+        if (!previous || previous.provider !== 'dsh' || previous.provider_session_id !== sessionId ||
+            previous.provider_session_name !== null || previous.transport !== 'cordis' ||
+            previous.runtime_session_id !== sessionId || !previousPeer ||
+            !((previous.runtime_target === null && previousPeer.status === 'exited') ||
+              (previous.runtime_target !== null && verifiedDeadOwner(previousPeer)))) {
+          fail('Session already has a hooks, native, or live Cordis owner; disable the other integration first');
+        }
+        const replaced = db.prepare(`UPDATE peer_bindings SET runtime_target = ?, updated_at = ?
+          WHERE peer = ? AND runtime_target IS ? AND provider = 'dsh' AND provider_session_id = ?
+            AND transport = 'cordis' AND runtime_session_id = ?
+            AND EXISTS (SELECT 1 FROM peers WHERE id = ? AND status = ? AND pid IS ?
+              AND pid_start_token IS ? AND pid_command_hash IS ?)`)
+          .run(owner, now(), peer, previous.runtime_target, sessionId, sessionId, peer,
+            previousPeer.status, previousPeer.pid, previousPeer.pid_start_token, previousPeer.pid_command_hash);
+        if (replaced.changes !== 1) fail('Cordis session ownership changed during recovery');
+      }
+      peers.upsertPeer(db, { id: peer, kind: 'dsh', role: 'peer', worktree: ctx.root,
+        pid: process.pid, processIdentity: identity, status: 'working', capabilities: 'dsh-cordis' });
+      bindings.upsertPeerBinding(db, { peer, provider: 'dsh', provider_session_id: sessionId,
+        provider_session_name: null, resume_mode: 'session', transport: 'cordis',
+        runtime_session_id: sessionId, runtime_target: owner });
+      peers.touchPeer(db, peer, 'idle');
+      addEvent(db, 'dsh.cordis.opened', peer, null, { session_id: sessionId });
+    });
+  } finally { db.close(); }
+  registerProjectActivity(ctx);
+
+  function assertOwnership(db, allowRetiring = false) {
+    if (disposed || (retiring && !allowRetiring)) fail('The Cordis Agent authority has been disposed');
+    const row = db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(peer);
+    if (!row || row.provider !== 'dsh' || row.transport !== 'cordis' || row.runtime_target !== owner ||
+        row.provider_session_id !== sessionId || row.runtime_session_id !== sessionId) fail('The Agent no longer owns this peer');
+  }
+  function owned(fn, transactional = true, allowRetiring = false) {
+    if (disposed || (retiring && !allowRetiring)) fail('The Cordis Agent authority has been disposed');
+    const db = connect(ctx, { create: false });
+    try {
+      const run = () => { assertOwnership(db, allowRetiring); return fn(db); };
+      return transactional ? tx(db, run) : run();
+    }
+    finally { db.close(); }
+  }
+  const authority = { scope: Object.freeze({ root: ctx.root, dbPath: ctx.dbPath, peer, executorId: owner }),
+    assertValid: () => { if (disposed || retiring) fail('The Cordis Agent authority has been disposed'); }, assertOwnership };
+  const service = createScopedMcpTools({ ctx, authority, connect, now, addEvent,
+    touchPeer: (db, id, status) => { assertOwnership(db); if (id !== peer) fail('Peer identity changed'); peers.touchPeer(db, id, status); } });
+  let queue = Promise.resolve();
+  function call(name, args, signal) {
+    const run = queue.then(async () => {
+      signal?.throwIfAborted();
+      const result = await service.call(name, args);
+      signal?.throwIfAborted();
+      const value = result.structuredContent;
+      const serialized = JSON.stringify(value);
+      return serialized.length <= maxToolChars ? JSON.parse(serialized) : {
+        ok: value.ok, peer, truncated: true,
+        notice: 'Result exceeds the configured bound. Use smaller limits; unread messages remain unread.',
+        preview: serialized.slice(0, Math.max(0, Math.floor((maxToolChars - 512) / 2)))
+      };
+    });
+    queue = run.catch(() => {});
+    return run;
+  }
+  function snapshot() {
+    return owned(db => {
+      const state = 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;
+      return { text: complete ? text : text.slice(0, maxContextChars - 160) +
+        '\n[Context truncated. Read hcc_inbox/hcc_state with smaller limits. Truncated messages have not been acknowledged.]',
+      messages: complete ? state.messages : [], hasUnread: state.messages.length > 0, complete };
+    }, false);
+  }
+  return {
+    peer, sessionId, ctx, list: service.list, call, snapshot,
+    ack: items => owned(db => coordination.ackMessages(db, peer, items)),
+    status: status => owned(db => peers.touchPeer(db, peer, status === 'running' ? 'working' : 'idle')),
+    activity: (event, tool) => owned(db => {
+      peers.touchPeer(db, peer, 'working');
+      addEvent(db, event, peer, null, { tool });
+    }),
+    dispose() {
+      if (disposed) return;
+      retiring = true;
+      try {
+        owned(db => {
+          peers.touchPeer(db, peer, 'exited');
+          db.prepare('UPDATE peer_bindings SET runtime_target = NULL, updated_at = ? WHERE peer = ? AND runtime_target = ?').run(now(), peer, owner);
+          addEvent(db, 'dsh.cordis.closed', peer, null, { session_id: sessionId });
+        }, true, true);
+        disposed = true;
+      } catch (error) {
+        // A lost generation cannot be retried; storage failures can be.
+        if (error?.code === 'DSH_COLLABORATION_CONFLICT') disposed = true;
+        throw error;
+      }
+    }
+  };
+}

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

@@ -0,0 +1,19 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+
+export interface DshCollaborationConfig {
+  /** Bounded model context, 2048-64000 characters. Default 16000. */
+  maxContextChars?: number;
+  /** Bounded lossless-JSON tool presentation, 2048-64000 characters. Default 16000. */
+  maxToolChars?: number;
+}
+export const name: 'hello-cc-dsh-collaboration';
+export const inject: readonly ['agents', 'tools', 'sessions'];
+export const DSH_CORDIS_VERSION: '0.2.0-rc.2';
+export function checkDshRuntime(anchor?: string): void;
+export function apply(ctx: Context, config?: DshCollaborationConfig): void;
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'hello-cc': { readonly kind: 'hello-cc' } & ContextFormed;
+  }
+}

package/lib/integrations/dsh-cordis.mjs

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { createDshCollaboration } from './dsh-collaboration.mjs';
+import { scopedMcpToolDefinitions } from '../mcp/tools.mjs';
+
+export const name = 'hello-cc-dsh-collaboration';
+export const inject = ['agents', 'tools', 'sessions'];
+export const DSH_CORDIS_VERSION = '0.2.0-rc.2';
+
+const failedRetirements = new Map();
+const disposedAgents = new WeakSet();
+
+function retire(agent, state, { agentDisposed = false, contextDisposed = false }, forget) {
+  let entry = failedRetirements.get(agent);
+  if (!entry) {
+    entry = { state, agentDisposed, contextDisposed, forget };
+    failedRetirements.set(agent, entry);
+  } else {
+    if (agentDisposed) entry.agentDisposed = true;
+    if (contextDisposed) entry.contextDisposed = true;
+  }
+  try {
+    entry.state.dispose();
+    entry.forget();
+    failedRetirements.delete(agent);
+  } catch (error) {
+    if (error?.code === 'DSH_COLLABORATION_CONFLICT') {
+      entry.forget();
+      failedRetirements.delete(agent);
+    }
+    throw error;
+  }
+}
+
+function retryRetirements(candidate) {
+  let root;
+  try { root = fs.realpathSync(candidate.session.header.cwd); } catch { return; }
+  for (const [agent, entry] of failedRetirements) {
+    if (!(entry.agentDisposed || (entry.contextDisposed && agent === candidate)) ||
+        entry.state.sessionId !== candidate.session.header.id || entry.state.ctx?.root !== root) continue;
+    try { retire(agent, entry.state, {}, entry.forget); } catch {}
+  }
+}
+
+export function checkDshRuntime(anchor = process.argv[1]) {
+  const require = createRequire(path.resolve(anchor));
+  for (const pkg of ['dsh-agent', 'dsh-agent-loop', 'dsh-tools', 'dsh-session']) {
+    let directory = path.dirname(require.resolve(`@deepseek-ai/${pkg}`));
+    let found = false;
+    while (path.dirname(directory) !== directory) {
+      const file = path.join(directory, 'package.json');
+      if (fs.existsSync(file)) {
+        const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (manifest.name === `@deepseek-ai/${pkg}`) {
+          if (manifest.version !== DSH_CORDIS_VERSION) throw new Error(`hello-cc Cordis requires ${pkg}@${DSH_CORDIS_VERSION}; found ${manifest.version}`);
+          found = true;
+          break;
+        }
+      }
+      directory = path.dirname(directory);
+    }
+    if (!found) throw new Error(`Cannot establish the ${pkg} runtime version`);
+  }
+}
+
+// Tools accepts a deliberately small JSON Schema subset. The shared service
+// validates numeric/string bounds even when the presentation cannot encode them.
+function toolSchema(value) {
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (['minimum', 'maximum', 'minLength', 'maxLength', 'maxItems'].includes(key)) continue;
+    if (key === 'properties') result[key] = Object.fromEntries(Object.entries(item).map(([k, v]) => [k, toolSchema(v)]));
+    else if (key === 'items') result[key] = toolSchema(item);
+    else result[key] = item;
+  }
+  return result;
+}
+function contextMessage(text) {
+  return Object.freeze({ id: randomUUID(), role: 'user',
+    source: Object.freeze({ kind: 'hello-cc', form: 'snapshot', sections: [Object.freeze({ name: 'coordination', text })] }),
+    content: Object.freeze([Object.freeze({ type: 'text', text })]) });
+}
+
+export function createDshCordisPlugin({ checkRuntime = checkDshRuntime, createCollaboration = createDshCollaboration } = {}) {
+  return function apply(ctx, config = {}) {
+    checkRuntime();
+    const bounds = {};
+    for (const key of ['maxContextChars', 'maxToolChars']) {
+      const value = config[key] ?? 16000;
+      if (!Number.isSafeInteger(value) || value < 2048 || value > 64000) throw new TypeError(`${key} must be an integer from 2048 to 64000`);
+      bounds[key] = value;
+    }
+    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');
+      if (!agent?.session?.header) throw new Error('hello-cc tools require an owning Agent');
+      if (disposedAgents.has(agent)) throw new Error('hello-cc Cordis Agent has been disposed');
+      retryRetirements(agent);
+      let state = states.get(agent);
+      if (!state) {
+        state = createCollaboration({ sessionId: agent.session.header.id, cwd: agent.session.header.cwd, ...bounds });
+        states.set(agent, state);
+      }
+      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 };
+    }
+    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);
+      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) => {
+      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] };
+    });
+    // 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('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);
+    });
+    ctx.on('tools/pre-execute', async (exec, next) => {
+      const decision = await next();
+      if (exec.agent && states.has(exec.agent)) states.get(exec.agent).activity('dsh.cordis.tool-observed', exec.name);
+      return decision;
+    });
+    // Registration is owned by this Cordis context, and is removed on disposal.
+    // Definitions are shared, but execution authority comes only from exec.agent.
+    const probe = scopedMcpToolDefinitions();
+    for (const tool of probe) ctx.tools.register({
+      name: tool.name, description: tool.description, parameters: toolSchema(tool.inputSchema),
+      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)); }
+      }
+    });
+  };
+}
+
+export const apply = createDshCordisPlugin();

package/lib/integrations/dsh.bundle.yml

@@ -0,0 +1,7 @@
+# Install this package as a dsh bundle, or use hcc dsh setup --mode cordis.
+- insert:
+    - id: hello-cc-dsh-cordis
+      name: '@logicseek/hello-cc/lib/integrations/dsh-cordis.mjs'
+      config:
+        maxContextChars: 16000
+        maxToolChars: 16000