@logicseek/hello-cc 0.1.4 → 0.1.6

package/lib/core/coordination/timeline.mjs

@@ -0,0 +1,187 @@
+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', '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.stopped',
+  'provider.session.merged',
+  'web.session.started',
+  'web.session.exited',
+  'tmux.session.attached',
+  'tmux.session.detached',
+  'tmux.session.exited',
+  '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,53 @@
+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 = {}) {
+  if (opts[key]) return { id: opts[key], auto: false };
+  if (observation.env?.HCC_PEER) return { id: observation.env.HCC_PEER, auto: false };
+  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;
+}

package/lib/core/peers/liveness.mjs

@@ -0,0 +1,90 @@
+const DEFAULT_ACTIVE_PEER_TTL = 600;
+
+function nowSec() {
+  return Math.floor(Date.now() / 1000);
+}
+
+export function taskRelatedLocks(task, locks) {
+  const taskId = Number(task?.id || 0);
+  const owner = task?.owner || '';
+  return (locks || []).filter((lock) => {
+    if (taskId && Number(lock.task_id || 0) === taskId) return true;
+    return Boolean(owner && lock.owner === owner);
+  });
+}
+
+export function taskOwnerLiveness(task, peers, locks, t = nowSec(), activePeerTtl = DEFAULT_ACTIVE_PEER_TTL) {
+  const owner = task?.owner || null;
+  const relatedLocks = taskRelatedLocks(task, locks);
+  if (!owner) {
+    return {
+      owner_known: false,
+      owner_active: null,
+      owner_stale: false,
+      owner_age_sec: null,
+      related_lock_count: relatedLocks.length,
+      takeover_ready: false
+    };
+  }
+  const ownerRow = (peers || []).find((row) => row.id === owner) || null;
+  const ownerAge = ownerRow
+    ? Number(ownerRow.age_sec ?? (t - Number(ownerRow.last_seen_at || 0)))
+    : null;
+  const ownerActive = Boolean(ownerRow && Number.isFinite(ownerAge) && ownerAge <= activePeerTtl);
+  const ownerStale = !ownerActive;
+  const takeoverStatus = ['claimed', 'running', 'review', 'blocked'].includes(task.status);
+  return {
+    owner_known: Boolean(ownerRow),
+    owner_active: ownerActive,
+    owner_stale: ownerStale,
+    owner_age_sec: Number.isFinite(ownerAge) ? ownerAge : null,
+    related_lock_count: relatedLocks.length,
+    takeover_ready: Boolean(takeoverStatus && ownerStale && relatedLocks.length === 0)
+  };
+}
+
+export function annotateTasksWithLiveness(tasks, peers, locks, t = nowSec(), activePeerTtl = DEFAULT_ACTIVE_PEER_TTL) {
+  return (tasks || []).map((task) => ({
+    ...task,
+    ...taskOwnerLiveness(task, peers, locks, t, activePeerTtl)
+  }));
+}
+
+export function taskOwnerStateText(task) {
+  if (!task?.owner) return '';
+  if (task.owner_stale) {
+    if (task.takeover_ready) return 'stale/no-lock';
+    const locks = Number(task.related_lock_count || 0);
+    return locks ? `stale/locks=${locks}` : 'stale';
+  }
+  if (task.owner_active) return 'active';
+  return '';
+}
+
+export function summarizeTask(task) {
+  if (!task) return null;
+  return {
+    id: task.id,
+    title: task.title,
+    status: task.status,
+    owner: task.owner || null,
+    assignee: task.assignee || null,
+    parent_id: task.parent_id || null,
+    team_role: task.team_role || null,
+    priority: task.priority,
+    owner_active: task.owner_active ?? null,
+    owner_stale: Boolean(task.owner_stale),
+    owner_age_sec: task.owner_age_sec ?? null,
+    related_lock_count: Number(task.related_lock_count || 0),
+    takeover_ready: Boolean(task.takeover_ready)
+  };
+}
+
+export function formatOpenTaskLine(task) {
+  const parts = [`#${task.id}`, task.status];
+  if (task.owner) parts.push(`owner=${task.owner}`);
+  if (task.assignee) parts.push(`assignee=${task.assignee}`);
+  const ownerState = taskOwnerStateText(task);
+  if (ownerState) parts.push(`owner_state=${ownerState}`);
+  return `${parts.join(' ')}: ${task.title}`;
+}

package/lib/core/peers/reconcile.mjs

@@ -0,0 +1,238 @@
+import path from 'node:path';
+import { providerSessionParts } from './session.mjs';
+import {
+  bindingHasProviderSession,
+  bindingProviderSessionValue
+} from './bindings.mjs';
+
+function defaultNow() {
+  return Math.floor(Date.now() / 1000);
+}
+
+function noopEvent() {}
+
+function normalizedRoot(root) {
+  return root ? path.resolve(root) : '';
+}
+
+function runtimePaneMatches(row, pane) {
+  return Boolean(row?.runtime_target && pane?.pane && row.runtime_target === pane.pane);
+}
+
+function runtimePidMatches(row, pane) {
+  return Boolean(row?.pid && pane?.pid && Number(row.pid) === Number(pane.pid));
+}
+
+function runtimeCwdMatches(root, row, pane) {
+  const paneCwd = normalizedRoot(pane?.cwd);
+  if (!paneCwd) return false;
+  const worktree = normalizedRoot(row?.worktree);
+  const projectRoot = normalizedRoot(root);
+  return Boolean((worktree && paneCwd === worktree) || (projectRoot && paneCwd === projectRoot));
+}
+
+function commandEvidence(row) {
+  const value = row?.resume_arg || null;
+  if (!value || value === '--last' || String(value).startsWith('%')) return null;
+  if (!['resume', 'session', 'detected', 'named'].includes(row?.resume_mode)) return null;
+  return {
+    provider: row.provider || row.kind || null,
+    value,
+    source: `binding.${row.resume_mode}`
+  };
+}
+
+function processEvidence(row, inspectProcess) {
+  if (typeof inspectProcess !== 'function' || !row?.pid) return null;
+  const info = inspectProcess(Number(row.pid), row.provider || row.kind || null);
+  if (!info?.provider_session) return null;
+  return {
+    provider: info.kind || row.provider || row.kind || null,
+    value: info.provider_session,
+    source: info.source || 'process'
+  };
+}
+
+function tmuxEvidence(row, pane, opts) {
+  const provider = row.provider || row.kind || null;
+  const byEvent = eventEvidence(row, opts);
+  if (byEvent) return byEvent;
+  const byProcess = processEvidence(row, opts.inspectProcess);
+  if (byProcess) return byProcess;
+  const byCommand = commandEvidence(row);
+  if (!byCommand) return null;
+  if (!runtimePaneMatches(row, pane) && !runtimePidMatches(row, pane)) return null;
+  return {
+    ...byCommand,
+    provider
+  };
+}
+
+function eventEvidence(row, opts) {
+  if (typeof opts.latestProviderSessionForPeer !== 'function') return null;
+  const value = opts.latestProviderSessionForPeer(row.peer, row.provider || row.kind || null);
+  if (!value) return null;
+  return {
+    provider: row.provider || row.kind || null,
+    value,
+    source: 'events.hook'
+  };
+}
+
+function existingProviderSessionConflict(db, row, session, provider = row?.provider) {
+  if (!session?.provider_session_id && !session?.provider_session_name) return null;
+  if (!provider) return null;
+  if (session.provider_session_id) {
+    return db.prepare(`
+      SELECT *
+      FROM peer_bindings
+      WHERE provider = ?
+        AND peer <> ?
+        AND provider_session_id = ?
+      LIMIT 1
+    `).get(provider, row.peer, session.provider_session_id) || null;
+  }
+  return db.prepare(`
+    SELECT *
+    FROM peer_bindings
+    WHERE provider = ?
+      AND peer <> ?
+      AND provider_session_name = ?
+    LIMIT 1
+  `).get(provider, row.peer, session.provider_session_name) || null;
+}
+
+function updatePeerProviderSession(db, row, candidate, opts) {
+  const t = opts.now();
+  const provider = candidate.provider || row.provider;
+  const session = providerSessionParts(candidate.value);
+  const conflict = existingProviderSessionConflict(db, row, session, provider);
+  if (conflict) {
+    return {
+      peer: row.peer,
+      provider,
+      action: 'skipped',
+      reason: 'provider_session_conflict',
+      conflict_peer: conflict.peer,
+      provider_session: bindingProviderSessionValue(session)
+    };
+  }
+
+  try {
+    db.prepare(`
+      UPDATE peer_bindings
+      SET provider = ?,
+          provider_session_id = ?,
+          provider_session_name = ?,
+          resume_mode = CASE
+            WHEN resume_mode IN ('unknown', 'attached', 'auto', 'command') THEN ?
+            ELSE resume_mode
+          END,
+          resume_arg = COALESCE(NULLIF(resume_arg, runtime_target), ?),
+          updated_at = ?
+      WHERE peer = ?
+    `).run(
+      provider,
+      session.provider_session_id || null,
+      session.provider_session_name || null,
+      candidate.source === 'binding.session' ? 'session' : 'detected',
+      candidate.value,
+      t,
+      row.peer
+    );
+  } catch (err) {
+    const text = `${err?.code || ''} ${err?.message || ''} ${err?.errstr || ''}`;
+    if (!/UNIQUE constraint failed/i.test(text)) throw err;
+    const conflict = existingProviderSessionConflict(db, row, session, provider);
+    return {
+      peer: row.peer,
+      provider,
+      action: 'skipped',
+      reason: 'provider_session_conflict',
+      conflict_peer: conflict?.peer || null,
+      provider_session: bindingProviderSessionValue(session)
+    };
+  }
+  opts.addEvent(db, 'provider.session.backfilled', row.peer, null, {
+    provider,
+    provider_session: candidate.value,
+    source: candidate.source,
+    runtime_target: row.runtime_target || null
+  });
+  return {
+    peer: row.peer,
+    provider,
+    action: 'backfilled',
+    source: candidate.source,
+    provider_session: candidate.value,
+    runtime_target: row.runtime_target || null
+  };
+}
+
+export function reconcileRunningPeerBindings(db, projectCtx = {}, options = {}) {
+  const opts = {
+    now: typeof options.now === 'function' ? options.now : defaultNow,
+    addEvent: typeof options.addEvent === 'function' ? options.addEvent : noopEvent,
+    inspectProcess: options.inspectProcess || null,
+    latestProviderSessionForPeer: options.latestProviderSessionForPeer || null,
+    panes: Array.isArray(options.panes) ? options.panes : []
+  };
+  const paneByTarget = new Map(opts.panes.filter((pane) => pane?.pane).map((pane) => [pane.pane, pane]));
+  const paneByPid = new Map();
+  for (const pane of opts.panes) {
+    if (pane?.pid && !paneByPid.has(Number(pane.pid))) paneByPid.set(Number(pane.pid), pane);
+  }
+
+  const rows = db.prepare(`
+    SELECT p.id AS peer, p.kind, p.status, p.worktree, p.pid, p.last_seen_at,
+           b.provider, b.provider_session_id, b.provider_session_name,
+           b.resume_mode, b.resume_arg, b.command, b.transport,
+           b.runtime_session_id, b.runtime_target, b.updated_at
+    FROM peer_bindings b
+    JOIN peers p ON p.id = b.peer
+    WHERE b.transport = 'tmux'
+      AND b.runtime_target IS NOT NULL
+      AND p.status IN ('running', 'working', 'busy')
+    ORDER BY p.last_seen_at DESC, b.updated_at DESC
+  `).all();
+
+  const results = [];
+  for (const row of rows) {
+    if (bindingHasProviderSession(row)) {
+      results.push({
+        peer: row.peer,
+        provider: row.provider,
+        action: 'skipped',
+        reason: 'provider_session_known',
+        provider_session: bindingProviderSessionValue(row)
+      });
+      continue;
+    }
+
+    const pane = paneByTarget.get(row.runtime_target) || paneByPid.get(Number(row.pid));
+    if (!pane) {
+      results.push({ peer: row.peer, provider: row.provider, action: 'skipped', reason: 'no_live_tmux_pane' });
+      continue;
+    }
+    if (!runtimePaneMatches(row, pane)) {
+      results.push({ peer: row.peer, provider: row.provider, action: 'skipped', reason: 'runtime_target_mismatch' });
+      continue;
+    }
+    if (!runtimePidMatches(row, pane) && !runtimeCwdMatches(projectCtx.root, row, pane)) {
+      results.push({ peer: row.peer, provider: row.provider, action: 'skipped', reason: 'weak_runtime_evidence' });
+      continue;
+    }
+
+    const candidate = tmuxEvidence(row, pane, opts);
+    if (!candidate?.value) {
+      results.push({ peer: row.peer, provider: row.provider, action: 'skipped', reason: 'no_strong_provider_evidence' });
+      continue;
+    }
+    results.push(updatePeerProviderSession(db, row, candidate, opts));
+  }
+  return {
+    checked: rows.length,
+    backfilled: results.filter((result) => result.action === 'backfilled').length,
+    results
+  };
+}

package/lib/core/peers/session.mjs

@@ -0,0 +1,14 @@
+import { sanitizePeerPart, shortHash } from './format.mjs';
+
+export function providerSessionPeerId(kind, providerId) {
+  return `${kind}-${sanitizePeerPart(String(providerId || '').slice(0, 8), shortHash(providerId))}`;
+}
+
+export function providerSessionParts(value) {
+  if (!value) return { provider_session_id: null, provider_session_name: null };
+  const text = String(value);
+  const uuidLike = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text);
+  return uuidLike
+    ? { provider_session_id: text, provider_session_name: null }
+    : { provider_session_id: null, provider_session_name: text };
+}