@logicseek/hello-cc 0.1.5 → 0.1.7

package/lib/core/coordination/tasks.mjs

@@ -0,0 +1,240 @@
+import { tx } from '../../db/schema.mjs';
+import { CliError } from '../../shared/errors.mjs';
+
+const DEFAULT_ACTIVE_PEER_TTL = 600;
+
+function defaultNow() {
+  return Math.floor(Date.now() / 1000);
+}
+
+function noopEvent() {}
+
+function noopMessage() {
+  return null;
+}
+
+export function createTaskStore(deps = {}) {
+  const now = typeof deps.now === 'function' ? deps.now : defaultNow;
+  const addEvent = typeof deps.addEvent === 'function' ? deps.addEvent : noopEvent;
+  const sendMessage = typeof deps.sendMessage === 'function' ? deps.sendMessage : noopMessage;
+  const activePeerTtl = Number(deps.activePeerTtl || DEFAULT_ACTIVE_PEER_TTL);
+
+  function taskOwnedError(peer, row, action) {
+    return new CliError('TASK_OWNED', `Task #${row.id} is owned by ${row.owner}`, {
+      owner: row.owner,
+      task_id: row.id,
+      attempted_by: peer,
+      action,
+      notify_owner: true
+    });
+  }
+
+  function claimTaskRowsForPeer(db, peer, ids, { force = false, source = null } = {}) {
+    return tx(db, () => {
+      const tasks = [];
+      for (const id of ids) {
+        const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+        if (!row) throw new CliError('NOT_FOUND', `Task #${id} does not exist`);
+        if (row.owner && row.owner !== peer && !force) {
+          throw taskOwnedError(peer, row, 'claim');
+        }
+        if (row.assignee && row.assignee !== peer && !force) {
+          throw new CliError('TASK_ASSIGNED', `Task #${id} is assigned to ${row.assignee}`, { assignee: row.assignee });
+        }
+        if (!['pending', 'blocked', 'claimed', 'running'].includes(row.status) && !force) {
+          throw new CliError('BAD_STATE', `Task #${id} is ${row.status}`);
+        }
+        const t = now();
+        db.prepare(`
+          UPDATE tasks
+          SET owner = ?, status = 'claimed', claimed_at = COALESCE(claimed_at, ?), updated_at = ?
+          WHERE id = ?
+        `).run(peer, t, t, id);
+        addEvent(db, 'task.claimed', peer, id, {
+          previous_owner: row.owner,
+          force,
+          ...(source ? { source } : {})
+        });
+        tasks.push(db.prepare('SELECT * FROM tasks WHERE id = ?').get(id));
+      }
+      return tasks;
+    });
+  }
+
+  function takeoverPolicyDetails(db, row, peer, { policy = 'any', staleAfter = activePeerTtl } = {}) {
+    const normalized = String(policy || 'any').toLowerCase();
+    const allowed = new Set(['any', 'blocked', 'stale', 'blocked-or-stale']);
+    if (!allowed.has(normalized)) {
+      throw new CliError('BAD_ARGS', `Unsupported takeover policy: ${policy}`);
+    }
+    const previousOwner = row.owner || null;
+    const blocked = row.status === 'blocked';
+    const ownerRow = previousOwner ? db.prepare('SELECT id, last_seen_at FROM peers WHERE id = ?').get(previousOwner) : null;
+    const ownerAge = ownerRow ? now() - Number(ownerRow.last_seen_at || 0) : null;
+    const ownerStale = Boolean(previousOwner && previousOwner !== peer && (!ownerRow || ownerAge > staleAfter));
+    const alreadyOwner = previousOwner === peer;
+    const ok = alreadyOwner ||
+      normalized === 'any' ||
+      (normalized === 'blocked' && blocked) ||
+      (normalized === 'stale' && ownerStale) ||
+      (normalized === 'blocked-or-stale' && (blocked || ownerStale));
+    return { policy: normalized, blocked, owner_stale: ownerStale, owner_age_sec: ownerAge, stale_after_sec: staleAfter, ok };
+  }
+
+  function takeOverTaskForPeer(db, peer, id, { reason, policy = 'any', staleAfter = activePeerTtl, source = null } = {}) {
+    return tx(db, () => {
+      const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+      if (!row) throw new CliError('NOT_FOUND', `Task #${id} does not exist`);
+      if (['done', 'abandoned'].includes(row.status)) {
+        throw new CliError('BAD_STATE', `Task #${id} is ${row.status}`);
+      }
+      const policyDetails = takeoverPolicyDetails(db, row, peer, { policy, staleAfter });
+      if (!policyDetails.ok) {
+        throw new CliError('TAKEOVER_POLICY', `Task #${id} does not match takeover policy ${policyDetails.policy}`, {
+          task_id: id,
+          status: row.status,
+          owner: row.owner || null,
+          policy: policyDetails.policy,
+          owner_stale: policyDetails.owner_stale,
+          owner_age_sec: policyDetails.owner_age_sec,
+          stale_after_sec: policyDetails.stale_after_sec
+        });
+      }
+      const previousOwner = row.owner || null;
+      const previousAssignee = row.assignee || null;
+      const t = now();
+      db.prepare(`
+        UPDATE tasks
+        SET owner = ?, status = 'claimed', claimed_at = COALESCE(claimed_at, ?), updated_at = ?
+        WHERE id = ?
+      `).run(peer, t, t, id);
+      addEvent(db, 'task.takeover', peer, id, {
+        previous_owner: previousOwner,
+        previous_assignee: previousAssignee,
+        reason,
+        policy: policyDetails.policy,
+        owner_stale: policyDetails.owner_stale,
+        stale_after_sec: staleAfter,
+        ...(source ? { source } : {})
+      });
+      if (previousOwner && previousOwner !== peer) {
+        sendMessage(db, peer, previousOwner, id, 'task.takeover', `Task #${id} taken over by ${peer}: ${reason}`);
+      }
+      return db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+    });
+  }
+
+  function queryOpenTasks(db, limit, peer = null) {
+    const sql = `
+      SELECT * FROM tasks
+      WHERE status NOT IN ('done', 'abandoned')
+        ${peer ? 'AND (owner = ? OR assignee = ?)' : ''}
+      ORDER BY
+        CASE status
+          WHEN 'claimed' THEN 0
+          WHEN 'running' THEN 1
+          WHEN 'pending' THEN 2
+          WHEN 'blocked' THEN 3
+          WHEN 'review' THEN 4
+          ELSE 5
+        END,
+        priority ASC,
+        id ASC
+      LIMIT ?
+    `;
+    return peer
+      ? db.prepare(sql).all(peer, peer, limit)
+      : db.prepare(sql).all(limit);
+  }
+
+  function taskById(db, id) {
+    return db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+  }
+
+  function teamChildren(db, parentId) {
+    return db.prepare(`
+      SELECT *
+      FROM tasks
+      WHERE parent_id = ?
+      ORDER BY priority ASC, id ASC
+    `).all(parentId);
+  }
+
+  function teamSummary(db, parentId) {
+    const parent = taskById(db, parentId);
+    if (!parent) throw new CliError('NOT_FOUND', `Task #${parentId} does not exist`);
+    const children = teamChildren(db, parentId);
+    const handoffs = db.prepare(`
+      SELECT *
+      FROM handoffs
+      WHERE task_id = ? OR task_id IN (SELECT id FROM tasks WHERE parent_id = ?)
+      ORDER BY id ASC
+    `).all(parentId, parentId);
+    const counts = {};
+    for (const child of children) counts[child.status] = (counts[child.status] || 0) + 1;
+    return { parent, children, handoffs, counts };
+  }
+
+  function claimNextTasksForPeer(db, peer, { force = false, count = 1 } = {}) {
+    return tx(db, () => {
+      if (!force) {
+        const current = db.prepare(`
+          SELECT * FROM tasks
+          WHERE owner = ?
+            AND status IN ('claimed', 'running', 'review', 'blocked')
+          ORDER BY
+            CASE status
+              WHEN 'running' THEN 0
+              WHEN 'claimed' THEN 1
+              WHEN 'review' THEN 2
+              WHEN 'blocked' THEN 3
+              ELSE 4
+            END,
+            priority ASC,
+            id ASC
+          LIMIT 1
+        `).get(peer);
+        if (current) return { current: { ...current, current: true }, tasks: [] };
+      }
+      const rows = db.prepare(`
+        SELECT * FROM tasks
+        WHERE status = 'pending'
+          AND owner IS NULL
+          AND (assignee IS NULL OR assignee = ?)
+        ORDER BY CASE WHEN assignee = ? THEN 0 ELSE 1 END, priority ASC, id ASC
+        LIMIT ?
+      `).all(peer, peer, count);
+      if (!rows.length) return { current: null, tasks: [] };
+      const t = now();
+      const claimed = [];
+      for (const row of rows) {
+        const changes = db.prepare(`
+          UPDATE tasks
+          SET owner = ?, status = 'claimed', claimed_at = ?, updated_at = ?
+          WHERE id = ? AND owner IS NULL AND status = 'pending'
+        `).run(peer, t, t, row.id).changes;
+        if (!changes) continue;
+        addEvent(db, 'task.claimed', peer, row.id, { next: true, count });
+        claimed.push(db.prepare('SELECT * FROM tasks WHERE id = ?').get(row.id));
+      }
+      return { current: null, tasks: claimed };
+    });
+  }
+
+  function assertTaskOwnerForMutation(db, peer, row, action) {
+    if (!row.owner || row.owner === peer) return;
+    throw taskOwnedError(peer, row, action);
+  }
+
+  return {
+    assertTaskOwnerForMutation,
+    claimNextTasksForPeer,
+    claimTaskRowsForPeer,
+    queryOpenTasks,
+    takeOverTaskForPeer,
+    taskById,
+    teamChildren,
+    teamSummary,
+    takeoverPolicyDetails
+  };
+}

package/lib/core/coordination/teams.mjs

@@ -0,0 +1,73 @@
+import { CliError } from '../../shared/errors.mjs';
+import { sanitizePeerPart } from '../peers/format.mjs';
+
+function intTeamOpt(opts, key, fallback = null) {
+  if (opts[key] === undefined || opts[key] === null || opts[key] === '') return fallback;
+  const value = Number.parseInt(String(opts[key]), 10);
+  if (!Number.isFinite(value)) throw new CliError('BAD_ARGS', `--${key} must be an integer`);
+  return value;
+}
+
+export function splitCsvList(value) {
+  if (Array.isArray(value)) return value.flatMap((item) => splitCsvList(item));
+  return String(value || '').split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+export function parseTeamItems(opts) {
+  const rawItems = [
+    ...splitCsvList(opts.item || []),
+    ...splitCsvList(opts.items || [])
+  ];
+  return rawItems.map((raw, index) => {
+    const parts = String(raw).split(':').map((part) => part.trim());
+    let assignee = null;
+    let role = null;
+    let title = raw.trim();
+    if (parts.length >= 3) {
+      assignee = parts.shift() || null;
+      role = parts.shift() || null;
+      title = parts.join(':').trim();
+    } else if (parts.length === 2) {
+      role = parts[0] || null;
+      title = parts[1] || title;
+    }
+    if (!title) title = `subtask ${index + 1}`;
+    return { title, role: role || `worker-${index + 1}`, assignee };
+  });
+}
+
+export function inferTeamItems(task, opts) {
+  const explicit = parseTeamItems(opts);
+  if (explicit.length) return explicit;
+  const count = Math.max(1, intTeamOpt(opts, 'count', 3));
+  const baseTitle = task?.title || 'team task';
+  return Array.from({ length: count }, (_, index) => ({
+    title: `${baseTitle} / subtask ${index + 1}`,
+    role: `worker-${index + 1}`,
+    assignee: null
+  }));
+}
+
+export function expandTeamWorkers(workers, parentId) {
+  const expanded = [];
+  for (const token of splitCsvList(workers || [])) {
+    const match = token.match(/^([A-Za-z][A-Za-z0-9._-]*):([1-9][0-9]*)$/);
+    if (!match) {
+      expanded.push(token);
+      continue;
+    }
+    const kind = sanitizePeerPart(match[1], 'peer');
+    const count = Number.parseInt(match[2], 10);
+    for (let i = 1; i <= count; i += 1) expanded.push(`${kind}-team-${parentId}-${i}`);
+  }
+  return expanded;
+}
+
+export function assignTeamWorkers(items, workers, parentId) {
+  const workerList = expandTeamWorkers(workers, parentId);
+  if (!workerList.length) return items;
+  return items.map((item, index) => ({
+    ...item,
+    assignee: item.assignee || workerList[index % workerList.length]
+  }));
+}

package/lib/core/coordination/timeline.mjs

@@ -0,0 +1,196 @@
+import { compactText } from '../../format.mjs';
+import { lockLabel } from './locks.mjs';
+
+export function parseEventPayload(row) {
+  try {
+    return row?.payload ? JSON.parse(row.payload) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function uniqueList(values) {
+  return [...new Set(values.filter(Boolean).map(String))];
+}
+
+export function messageParticipants(message) {
+  const participants = [message.sender];
+  if (message.recipient && !['all', ''].includes(message.recipient)) participants.push(message.recipient);
+  return uniqueList(participants);
+}
+
+export function taskParticipants(task) {
+  return uniqueList([task.created_by, task.owner, task.assignee]);
+}
+
+export function payloadParticipants(payload) {
+  const values = [];
+  for (const key of ['peer', 'actor_peer', 'target_peer', 'from_peer', 'to_peer', 'assignee', 'owner', 'recipient', 'kept_peer', 'removed_peer', 'previous_owner']) {
+    if (payload?.[key] && payload[key] !== 'all') values.push(payload[key]);
+  }
+  return uniqueList(values);
+}
+
+export function peerMatchesTimelineItem(item, peer) {
+  if (!peer) return true;
+  if (item.broadcast) return true;
+  return (item.peers || []).includes(peer);
+}
+
+export function shouldHideTimelineMessage(message) {
+  if (message.kind === 'task' && /^Task #\d+ assigned: /.test(message.body || '')) return true;
+  if (message.kind === 'handoff' && /^Handoff #\d+: /.test(message.body || '')) return true;
+  return false;
+}
+
+const TIMELINE_EVENT_ALLOW = new Set([
+  'task.created',
+  'task.claimed',
+  'task.pending',
+  'task.running',
+  'task.review',
+  'task.blocked',
+  'task.done',
+  'task.abandoned',
+  'task.takeover',
+  'team.started',
+  'lock.acquired',
+  'lock.released',
+  'peer.registered',
+  'peer.joined',
+  'peer.auto_joined',
+  'peer.start.requested',
+  'peer.attach.requested',
+  'peer.stop.requested',
+  'peer.stopped',
+  'peer.restarted',
+  'provider.session.merged',
+  'provider.session.rebound',
+  'web.session.started',
+  'web.session.exited',
+  'web.session.stop_requested',
+  'tmux.session.attached',
+  'tmux.session.detached',
+  'tmux.session.exited',
+  'tmux.session.restarted',
+  'tmux.session.rebound',
+  'tmux.session.gc',
+  'run.session.started',
+  'run.session.exited'
+]);
+
+export function shouldHideTimelineEvent(event) {
+  if (['message.sent', 'message.ack', 'handoff.created', 'lock.renewed'].includes(event.type)) return true;
+  if (event.type && event.type.startsWith('hook.')) return true;
+  if (event.type && event.type.startsWith('web.session.input')) return true;
+  return !TIMELINE_EVENT_ALLOW.has(event.type);
+}
+
+export function timelineDirection(message, peer) {
+  if (!peer) return message.recipient === 'all' ? 'broadcast' : 'project';
+  if (message.sender === peer && message.recipient === peer) return 'self';
+  if (message.sender === peer) return 'out';
+  if (message.recipient === 'all') return 'broadcast';
+  if (message.recipient === peer) return 'in';
+  return 'project';
+}
+
+export function timelineFromRows({ messages = [], handoffs = [], tasks = [], locks = [], events = [] }, peer = null) {
+  const items = [];
+  for (const message of messages) {
+    if (shouldHideTimelineMessage(message)) continue;
+    const item = {
+      id: `message:${message.id}`,
+      source: 'message',
+      source_id: message.id,
+      ts: message.created_at,
+      actor: message.sender,
+      peers: messageParticipants(message),
+      task_id: message.task_id || null,
+      kind: message.kind || 'note',
+      title: `${message.sender} -> ${message.recipient || 'all'}`,
+      text: compactText(message.body),
+      unread: message.read_at === null || message.read_at === undefined,
+      direction: timelineDirection(message, peer),
+      thread_id: message.thread_id || message.id,
+      reply_to: message.reply_to || null,
+      broadcast: !message.recipient || message.recipient === 'all'
+    };
+    if (peerMatchesTimelineItem(item, peer)) items.push(item);
+  }
+  for (const handoff of handoffs) {
+    const item = {
+      id: `handoff:${handoff.id}`,
+      source: 'handoff',
+      source_id: handoff.id,
+      ts: handoff.created_at,
+      actor: handoff.from_peer,
+      peers: uniqueList([handoff.from_peer, handoff.to_peer]),
+      task_id: handoff.task_id || null,
+      kind: 'handoff',
+      title: `handoff ${handoff.from_peer}${handoff.to_peer ? ` -> ${handoff.to_peer}` : ''}`,
+      text: compactText(handoff.summary),
+      direction: 'project',
+      broadcast: !handoff.to_peer,
+      tests: handoff.tests || '',
+      risks: handoff.risks || ''
+    };
+    if (peerMatchesTimelineItem(item, peer)) items.push(item);
+  }
+  for (const task of tasks) {
+    const item = {
+      id: `task:${task.id}`,
+      source: 'task',
+      source_id: task.id,
+      ts: task.updated_at || task.created_at,
+      actor: task.owner || task.created_by || task.assignee || '',
+      peers: taskParticipants(task),
+      task_id: task.id,
+      kind: task.status,
+      title: `task #${task.id} ${task.status}${task.parent_id ? ` child of #${task.parent_id}` : ''}`,
+      text: compactText(task.title),
+      direction: 'project'
+    };
+    if (peerMatchesTimelineItem(item, peer)) items.push(item);
+  }
+  for (const lock of locks) {
+    const item = {
+      id: `lock:${lock.resource}`,
+      source: 'lock',
+      source_id: lock.resource,
+      ts: lock.created_at,
+      actor: lock.owner,
+      peers: uniqueList([lock.owner]),
+      task_id: lock.task_id || null,
+      kind: 'active',
+      title: `lock ${lockLabel(lock)}`,
+      text: compactText(lock.reason || `owner=${lock.owner}`),
+      direction: 'project'
+    };
+    if (peerMatchesTimelineItem(item, peer)) items.push(item);
+  }
+  for (const event of events) {
+    if (shouldHideTimelineEvent(event)) continue;
+    const payload = parseEventPayload(event);
+    const item = {
+      id: `event:${event.id}`,
+      source: 'event',
+      source_id: event.id,
+      ts: event.created_at,
+      actor: event.actor || '',
+      peers: uniqueList([event.actor, ...payloadParticipants(payload)]),
+      task_id: event.task_id || null,
+      kind: event.type,
+      title: event.type,
+      text: compactText(payload.summary || payload.reason || payload.title || payload.resource || payload.peer || ''),
+      direction: 'project'
+    };
+    if (peerMatchesTimelineItem(item, peer)) items.push(item);
+  }
+  const order = { message: 10, handoff: 20, task: 30, lock: 40, event: 50 };
+  items.sort((a, b) =>
+    (a.ts || 0) - (b.ts || 0) ||
+    (order[a.source] || 99) - (order[b.source] || 99) ||
+    String(a.source_id).localeCompare(String(b.source_id), undefined, { numeric: true }));
+  return items.slice(-120);
+}

package/lib/core/peers/bindings.mjs

@@ -0,0 +1,83 @@
+import { providerSessionParts } from './session.mjs';
+
+export function bindingFromDetected(peer, transport = 'detected') {
+  const provider = peer.kind || 'other';
+  const session = providerSessionParts(peer.resumeId || peer.sessionId || '');
+  return {
+    peer: peer.peerId || peer.id,
+    provider,
+    ...session,
+    resume_mode: peer.resumeId ? 'resume' : (peer.sessionId ? 'detected' : 'unknown'),
+    resume_arg: peer.resumeId || null,
+    command: peer.command || null,
+    transport,
+    runtime_session_id: peer.peerId || peer.id
+  };
+}
+
+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 (row?.transport === 'hcc-run') return 20;
+  if (row?.transport === 'hook') return 10;
+  if (row?.transport === 'detected') return 5;
+  return 0;
+}
+
+export function comparePeerBindings(a, b) {
+  return peerBindingRuntimeRank(b) - peerBindingRuntimeRank(a) ||
+    Number(b.updated_at || 0) - Number(a.updated_at || 0) ||
+    Number(b.created_at || 0) - Number(a.created_at || 0) ||
+    String(a.peer || '').localeCompare(String(b.peer || ''));
+}
+
+export function bindingHasProviderSession(binding) {
+  return Boolean(binding?.provider_session_id || binding?.provider_session_name);
+}
+
+export function bindingProviderSessionValue(binding) {
+  return binding?.provider_session_id || binding?.provider_session_name || null;
+}
+
+export function bindingHasRuntime(binding) {
+  return Boolean(binding?.runtime_target) || ['tmux', 'web-pty'].includes(binding?.transport);
+}
+
+export function mergeRuntimeBinding(existing, binding) {
+  if (!existing || !bindingHasRuntime(existing) || bindingHasRuntime(binding)) return binding;
+  return {
+    ...binding,
+    command: existing.command || binding.command || null,
+    transport: existing.transport,
+    runtime_session_id: existing.runtime_session_id || binding.runtime_session_id || binding.peer,
+    runtime_target: existing.runtime_target || null
+  };
+}
+
+function providerCompatible(existing, binding) {
+  if (!existing?.provider || !binding?.provider) return true;
+  return existing.provider === binding.provider;
+}
+
+function providerSessionResumeMode(mode) {
+  return new Set(['detected', 'resume', 'session', 'named']).has(mode);
+}
+
+export function mergePeerBinding(existing, binding) {
+  let next = mergeRuntimeBinding(existing, binding);
+  if (!existing || bindingHasProviderSession(next) || !bindingHasProviderSession(existing)) return next;
+  if (!providerCompatible(existing, next)) return next;
+
+  next = {
+    ...next,
+    provider: next.provider || existing.provider,
+    provider_session_id: existing.provider_session_id || null,
+    provider_session_name: existing.provider_session_name || null
+  };
+  if (providerSessionResumeMode(existing.resume_mode) && !providerSessionResumeMode(next.resume_mode)) {
+    next.resume_mode = existing.resume_mode;
+    next.resume_arg = existing.resume_arg || next.resume_arg || null;
+  }
+  return next;
+}

package/lib/core/peers/format.mjs

@@ -0,0 +1,13 @@
+import { createHash } from 'node:crypto';
+
+export function sanitizePeerPart(value, fallback = 'peer') {
+  const text = String(value || '').toLowerCase()
+    .replace(/[^a-z0-9._-]/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 32);
+  return text || fallback;
+}
+
+export function shortHash(value) {
+  return createHash('sha1').update(String(value)).digest('hex').slice(0, 8);
+}

package/lib/core/peers/identity.mjs

@@ -0,0 +1,61 @@
+import { sanitizePeerPart, shortHash } from './format.mjs';
+import { providerSessionPeerId } from './session.mjs';
+
+export { sanitizePeerPart, shortHash } from './format.mjs';
+
+export function autoPeerProviderSession(_kind, observation = {}) {
+  return {
+    sessionId: observation.sessionId || '',
+    resumeId: observation.resumeId || null,
+    ancestor: observation.ancestor || null
+  };
+}
+
+export function autoPeerSessionId(kind, observation = {}) {
+  return autoPeerProviderSession(kind, observation).sessionId;
+}
+
+export function autoPeerResumeId(kind, observation = {}) {
+  return autoPeerProviderSession(kind, observation).resumeId;
+}
+
+export function autoPeerKind(kindHint = 'shell', observation = {}) {
+  return observation.kind || kindHint || 'shell';
+}
+
+export function autoPeerBasis(kind = null, observation = {}) {
+  if (observation.basis) return observation.basis;
+  const ancestor = observation.ancestor || null;
+  if (ancestor && (!kind || ancestor.kind === kind)) return `cli:${ancestor.kind}:${ancestor.pid}`;
+  if (observation.tmuxPane) return `tmux:${observation.tmuxPane}`;
+  if (observation.tty) return `tty:${observation.tty}`;
+  return `ppid:${observation.ppid ?? 0}`;
+}
+
+export function autoPeerId(ctx, kindHint = 'shell', observation = {}) {
+  const kind = autoPeerKind(kindHint, observation);
+  const { sessionId, resumeId } = autoPeerProviderSession(kind, observation);
+  const providerId = resumeId || sessionId;
+  if (providerId) return providerSessionPeerId(kind, providerId);
+
+  const basis = autoPeerBasis(kind, observation);
+  return `${kind}-${shortHash(`${ctx.root}:${basis}`)}`;
+}
+
+export function resolveCurrentPeer(ctx, opts = {}, key = 'peer', kindHint = 'shell', observation = {}) {
+  const explicit = opts[key] || '';
+  const envPeer = observation.env?.HCC_PEER || '';
+  if (envPeer) {
+    return {
+      id: envPeer,
+      auto: false,
+      corrected_from: explicit && explicit !== envPeer ? explicit : null
+    };
+  }
+  if (explicit) return { id: explicit, auto: false, corrected_from: null };
+  return { id: autoPeerId(ctx, kindHint, observation), auto: true };
+}
+
+export function currentPeer(ctx, opts = {}, key = 'peer', kindHint = 'shell', observation = {}) {
+  return resolveCurrentPeer(ctx, opts, key, kindHint, observation).id;
+}