@logicseek/hello-cc 0.1.5 → 0.1.7

package/lib/cli-runtime.mjs

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { projectDbPath } from './runtime/paths.mjs';
+
+export function createContext(global = {}, deps = {}) {
+  const cwd = deps.cwd || process.cwd();
+  const detectRoot = deps.detectRoot;
+  if (typeof detectRoot !== 'function') throw new TypeError('createContext requires deps.detectRoot');
+  const root = detectRoot(cwd, global.root);
+  const envDb = global.root ? null : process.env.HCC_DB;
+  const dbPath = path.resolve(global.db || envDb || projectDbPath(root));
+  return { cwd, root, dbPath, json: global.json, explicitRoot: Boolean(global.root || process.env.HCC_ROOT) };
+}
+
+export function shellCommand(args, quoteArg) {
+  if (typeof quoteArg !== 'function') throw new TypeError('shellCommand requires quoteArg');
+  return args.map(quoteArg).join(' ');
+}
+
+export function tailFile(file, maxBytes = 12000) {
+  try {
+    const stat = fs.statSync(file);
+    const size = Math.min(stat.size, maxBytes);
+    const fd = fs.openSync(file, 'r');
+    try {
+      const buf = Buffer.alloc(size);
+      fs.readSync(fd, buf, 0, size, Math.max(0, stat.size - size));
+      return buf.toString('utf8').trim();
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return '';
+  }
+}
+
+export function commandPath(argv = process.argv) {
+  try { return fs.realpathSync(argv[1]); }
+  catch { return path.resolve(argv[1]); }
+}
+
+export function packageRoot(argv = process.argv) {
+  return path.resolve(path.dirname(commandPath(argv)), '..');
+}

package/lib/coordination-state.mjs

@@ -0,0 +1,218 @@
+import {
+  deriveAutomation,
+  renderAutomationContext
+} from './core/coordination/automation.mjs';
+import {
+  annotateTasksWithLiveness,
+  formatOpenTaskLine
+} from './core/peers/liveness.mjs';
+import { lockLabel } from './core/coordination/locks.mjs';
+import { timelineFromRows } from './core/coordination/timeline.mjs';
+
+const DEFAULT_ACTIVE_PEER_TTL = 600;
+const DEFAULT_LOCK_TTL = 900;
+const DEFAULT_CLI_NAME = 'hcc';
+
+function defaultNow() {
+  return Math.floor(Date.now() / 1000);
+}
+
+function requireFn(value, name) {
+  if (typeof value !== 'function') throw new TypeError(`createCoordinationState requires deps.${name}`);
+  return value;
+}
+
+export function createCoordinationState(deps = {}) {
+  const activePeerTtl = Number(deps.activePeerTtl ?? DEFAULT_ACTIVE_PEER_TTL);
+  const cliName = deps.cliName || DEFAULT_CLI_NAME;
+  const connect = requireFn(deps.connect, 'connect');
+  const defaultLockTtl = Number(deps.defaultLockTtl ?? DEFAULT_LOCK_TTL);
+  const now = typeof deps.now === 'function' ? deps.now : defaultNow;
+  const queryInbox = requireFn(deps.queryInbox, 'queryInbox');
+  const queryOpenTasks = requireFn(deps.queryOpenTasks, 'queryOpenTasks');
+  const queryTimelineMessages = requireFn(deps.queryTimelineMessages, 'queryTimelineMessages');
+  const touchCurrentPeer = typeof deps.touchCurrentPeer === 'function'
+    ? deps.touchCurrentPeer
+    : () => {};
+
+  function collectStateSnapshot(db, ctx, peer = null, opts = {}) {
+    const t = now();
+    const peers = db.prepare(`
+      SELECT id, kind, role, status, worktree, branch, pid, capabilities,
+             created_at, last_seen_at, (? - last_seen_at) AS age_sec
+      FROM peers
+      ORDER BY last_seen_at DESC, id ASC
+      LIMIT 200
+    `).all(t);
+    const taskRows = queryOpenTasks(db, 200);
+    const locks = db.prepare(`
+      SELECT resource, base_resource, scope, owner, task_id, reason, expires_at, created_at
+      FROM locks
+      WHERE expires_at > ?
+      ORDER BY resource ASC
+      LIMIT 200
+    `).all(t);
+    const tasks = annotateTasksWithLiveness(taskRows, peers, locks, t, activePeerTtl);
+    const messages = peer
+      ? queryInbox(db, peer, false, 50)
+      : db.prepare(`
+          SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
+          FROM messages
+          ORDER BY id DESC
+          LIMIT 50
+        `).all().reverse();
+    const timelineMessages = queryTimelineMessages(db, peer, 80);
+    const handoffs = db.prepare(`
+      SELECT id, task_id, from_peer, to_peer, summary, changed_files, tests, risks, created_at
+      FROM handoffs
+      ORDER BY id DESC
+      LIMIT 50
+    `).all().reverse();
+    const events = db.prepare(`
+      SELECT id, type, actor, task_id, payload, created_at
+      FROM events
+      ORDER BY id DESC
+      LIMIT 80
+    `).all().reverse();
+    const snapshot = {
+      root: ctx.root,
+      db: ctx.dbPath,
+      now: t,
+      active_peer_ttl: activePeerTtl,
+      peers,
+      tasks,
+      locks,
+      messages,
+      handoffs,
+      events
+    };
+    snapshot.timeline = timelineFromRows({ messages: timelineMessages, handoffs, tasks, locks, events }, peer);
+    snapshot.automation = deriveAutomation(snapshot, peer, opts, {
+      activePeerTtl,
+      defaultLockTtl,
+      cliName
+    });
+    return snapshot;
+  }
+
+  function buildHookCoordinationContext(db, ctx, peerId) {
+    const snapshot = collectStateSnapshot(db, ctx, peerId);
+    const openTasks = snapshot.tasks.slice(0, 8);
+    const unread = snapshot.messages.slice(0, 5);
+    const peers = snapshot.peers.slice(0, 8);
+    const parts = [
+      '[hello-cc coordination]',
+      `peer: ${peerId}`,
+      'This is live project coordination context injected by hello-cc.',
+      'You are not isolated for project coordination: hcc is the source of truth for other Claude/Codex/shell sessions in this project.',
+      'If the user asks what other sessions are doing, what tasks exist, or whether you can see other sessions, do not answer from generic model knowledge and do not say sessions are isolated. Run hcc status, hcc state, hcc peers, hcc task list, hcc msg inbox, and hcc lock list, then answer from those results.',
+      'Tasks are project work facts, not read/unread items. Open tasks stay relevant to every session until they are marked done or abandoned. Messages are the unread/ack notification channel.',
+      'If you already own a current task, continue that task until handoff/done/blocked; do not claim a different task just because a new prompt arrived.',
+      'When a hello-cc message asks for a response, reply with hcc msg reply --id <message-id> --body "<answer>" so the answer stays in the same thread.'
+    ];
+
+    if (peers.length > 0) {
+      parts.push('[hello-cc known peers]');
+      parts.push(...peers.map((peer) => {
+        const age = Math.max(0, snapshot.now - Number(peer.last_seen_at || 0));
+        const active = age <= activePeerTtl ? 'active' : 'stale';
+        return `- ${peer.id} ${peer.kind || 'other'} ${peer.status || 'idle'} ${active}`;
+      }));
+    } else {
+      parts.push('[hello-cc known peers]\n(none)');
+    }
+
+    if (snapshot.automation.current_task) {
+      const task = snapshot.automation.current_task;
+      parts.push('[hello-cc current task]');
+      parts.push(`#${task.id} ${task.status}: ${task.title}`);
+    }
+
+    if (openTasks.length > 0) {
+      parts.push('[hello-cc open tasks]');
+      parts.push(...openTasks.map((task) => `- ${formatOpenTaskLine(task)}`));
+    } else {
+      parts.push('[hello-cc open tasks]\n(none)');
+    }
+
+    if (unread.length > 0) {
+      parts.push('[hello-cc unread messages]');
+      parts.push(...unread.map((m) =>
+        `- #${m.id} from ${m.sender}${m.task_id ? ` task #${m.task_id}` : ''}${m.reply_to ? ` reply #${m.reply_to}` : ''}: ${m.body}`
+      ));
+    } else {
+      parts.push('[hello-cc unread messages]\n(none)');
+    }
+
+    if (snapshot.locks.length > 0) {
+      parts.push('[hello-cc active locks]');
+      parts.push(...snapshot.locks.slice(0, 8).map((lock) =>
+        `- ${lockLabel(lock)} owner=${lock.owner}${lock.task_id ? ` task #${lock.task_id}` : ''}`));
+    } else {
+      parts.push('[hello-cc active locks]\n(none)');
+    }
+
+    parts.push(renderAutomationContext(snapshot.automation));
+
+    return { text: parts.join('\n'), messages: unread };
+  }
+
+  function ackMessages(db, peerId, messages) {
+    if (!messages.length) return;
+    const t = now();
+    for (const m of messages) {
+      db.prepare(`
+        INSERT INTO message_reads(message_id, peer, read_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(message_id, peer) DO UPDATE SET read_at = excluded.read_at
+      `).run(m.id, peerId, t);
+    }
+  }
+
+  function statusSummary(ctx, peer = null, identity = null) {
+    const db = connect(ctx);
+    try {
+      if (identity) touchCurrentPeer(db, ctx, identity, null, 'shell');
+      const t = now();
+      const activePeers = db.prepare('SELECT COUNT(*) AS n FROM peers WHERE last_seen_at >= ?').get(t - activePeerTtl).n;
+      const stalePeers = db.prepare('SELECT COUNT(*) AS n FROM peers WHERE last_seen_at < ?').get(t - activePeerTtl).n;
+      const taskRows = db.prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status ORDER BY status').all();
+      const locks = db.prepare('SELECT COUNT(*) AS n FROM locks WHERE expires_at > ?').get(t).n;
+      const unread = peer ? queryInbox(db, peer, false, 1000).length : null;
+      const recent = db.prepare('SELECT * FROM events ORDER BY id DESC LIMIT 8').all().reverse();
+      return {
+        root: ctx.root,
+        db: ctx.dbPath,
+        active_peers: activePeers,
+        stale_peers: stalePeers,
+        tasks: taskRows,
+        active_locks: locks,
+        unread,
+        recent_events: recent
+      };
+    } finally {
+      db.close();
+    }
+  }
+
+  function statusSnapshot(ctx, peer = null, opts = {}) {
+    const db = connect(ctx);
+    try {
+      return collectStateSnapshot(db, ctx, peer, opts);
+    } finally {
+      try {
+        db.close();
+      } catch {
+        // Ignore close failures for short-lived snapshots.
+      }
+    }
+  }
+
+  return {
+    ackMessages,
+    buildHookCoordinationContext,
+    collectStateSnapshot,
+    statusSnapshot,
+    statusSummary
+  };
+}

package/lib/core/coordination/automation.mjs

@@ -0,0 +1,222 @@
+import { shellQuoteArg } from '../../format.mjs';
+import {
+  lockArgv,
+  lockBaseResource,
+  lockLabel,
+  lockScope,
+  locksConflict,
+  normalizeLockScope,
+  scopedLockResource
+} from './locks.mjs';
+import {
+  shouldHideTimelineMessage,
+  uniqueList
+} from './timeline.mjs';
+import { summarizeTask } from '../peers/liveness.mjs';
+
+const DEFAULT_CLI_NAME = 'hcc';
+const DEFAULT_ACTIVE_PEER_TTL = 600;
+const DEFAULT_LOCK_TTL = 900;
+
+function nowSec() {
+  return Math.floor(Date.now() / 1000);
+}
+
+export function actionCommand(argv, cliName = DEFAULT_CLI_NAME) {
+  if (!argv?.length) return '';
+  return [cliName, ...argv].map(shellQuoteArg).join(' ');
+}
+
+export function makeAction(kind, argv, reason, mutates = true, extra = {}, config = {}) {
+  return {
+    kind,
+    reason,
+    mutates,
+    argv,
+    command: actionCommand(argv, config.cliName || DEFAULT_CLI_NAME),
+    ...extra
+  };
+}
+
+export function looksLikeMultiTask(task) {
+  if (!task) return false;
+  const text = `${task.title || ''}\n${task.body || ''}`;
+  const bullets = text.split('\n').filter((line) => /^\s*(?:[-*]|\d+[.)])\s+\S+/.test(line)).length;
+  const separators = (text.match(/[,，;；、]/g) || []).length;
+  return bullets >= 2 || separators >= 3 || /多任务|并行|团队|分工|several tasks|multiple tasks|parallel|team/i.test(text);
+}
+
+export function selectCurrentTask(tasks, peerId) {
+  if (!peerId) return null;
+  const statusRank = { running: 0, claimed: 1, review: 2, blocked: 3 };
+  const openTasks = (tasks || []).filter((task) => !['done', 'abandoned'].includes(task.status));
+  const ownedTasks = openTasks
+    .filter((task) => task.owner === peerId)
+    .sort((a, b) =>
+      (statusRank[a.status] ?? 9) - (statusRank[b.status] ?? 9) ||
+      Number(a.priority || 0) - Number(b.priority || 0) ||
+      Number(a.id || 0) - Number(b.id || 0));
+  return ownedTasks.find((task) => ['running', 'claimed', 'review', 'blocked'].includes(task.status)) || ownedTasks[0] || null;
+}
+
+export function deriveAutomation(snapshot, peer = null, opts = {}, config = {}) {
+  const cliName = config.cliName || DEFAULT_CLI_NAME;
+  const activePeerTtl = Number(config.activePeerTtl ?? snapshot.active_peer_ttl ?? DEFAULT_ACTIVE_PEER_TTL);
+  const defaultLockTtl = Number(config.defaultLockTtl ?? DEFAULT_LOCK_TTL);
+  const makeAutomationAction = (kind, argv, reason, mutates = true, extra = {}) =>
+    makeAction(kind, argv, reason, mutates, extra, { cliName });
+
+  const peerId = peer || '';
+  const t = Number(snapshot.now || nowSec());
+  const peerRow = peerId ? snapshot.peers.find((row) => row.id === peerId) : null;
+  const openTasks = (snapshot.tasks || []).filter((task) => !['done', 'abandoned'].includes(task.status));
+  const assignedTasks = peerId ? openTasks.filter((task) => !task.owner && task.assignee === peerId) : [];
+  const availableTasks = openTasks.filter((task) => !task.owner && !task.assignee);
+  const ownedTask = selectCurrentTask(openTasks, peerId);
+  const takeoverReadyTasks = peerId
+    ? openTasks.filter((task) => task.owner && task.owner !== peerId && task.takeover_ready)
+    : [];
+  const intent = String(opts.intent || 'work').toLowerCase();
+  const scope = normalizeLockScope(opts.scope || opts.lock_scope);
+  const resources = uniqueList(Array.isArray(opts.resources) ? opts.resources : (opts.resource ? [opts.resource] : []));
+  const ownLocks = peerId ? (snapshot.locks || []).filter((lock) => lock.owner === peerId) : [];
+  const requestedLocks = resources.map((resource) => {
+    const requested = scopedLockResource(resource, scope);
+    const lock = (snapshot.locks || []).find((row) => Number(row.expires_at || 0) > t && locksConflict(row, requested));
+    const exact = (snapshot.locks || []).find((row) => Number(row.expires_at || 0) > t && lockBaseResource(row) === requested.base_resource && lockScope(row) === requested.scope);
+    return { ...requested, lock, exact };
+  });
+  const conflict = requestedLocks.find((entry) => entry.lock && entry.lock.owner !== peerId);
+  const missingLock = requestedLocks.find((entry) => !entry.lock);
+  const unread = peerId ? (snapshot.messages || []).filter((message) =>
+    message.read_at === null || message.read_at === undefined) : [];
+  const warnings = [];
+  if (peerId && !peerRow) warnings.push(`peer ${peerId} is not registered in this project`);
+  const lockActions = [];
+  const messageActions = [];
+  const taskActions = [];
+  const automation = {
+    schema_version: 1,
+    peer: peerId ? {
+      id: peerId,
+      known: Boolean(peerRow),
+      active: Boolean(peerRow && Number(peerRow.age_sec || 0) <= activePeerTtl),
+      age_sec: peerRow ? Number(peerRow.age_sec || 0) : null
+    } : null,
+    current_task: summarizeTask(ownedTask),
+    phase: 'idle',
+    next_action: makeAutomationAction('none', [], 'no immediate coordination action', false),
+    actions: [],
+    finish_actions: [],
+    warnings
+  };
+
+  const orderedUnread = unread
+    .filter((message) => message.sender !== peerId)
+    .filter((message) => !shouldHideTimelineMessage(message))
+    .sort((a, b) => (a.kind === 'task' ? 1 : 0) - (b.kind === 'task' ? 1 : 0) || a.id - b.id);
+  for (const message of orderedUnread) {
+    if (ownedTask && message.kind === 'task') continue;
+    const kind = message.kind === 'task' ? 'msg.inbox' : 'msg.reply';
+    const argv = kind === 'msg.reply'
+      ? ['msg', 'reply', '--from', peerId, '--id', String(message.id), '--body', '<answer>']
+      : ['msg', 'inbox', '--peer', peerId];
+    messageActions.push(makeAutomationAction(kind, argv, `unread message #${message.id} from ${message.sender}`, kind !== 'msg.inbox', {
+      message_id: message.id,
+      task_id: message.task_id || null
+    }));
+  }
+
+  if (!ownedTask && assignedTasks.length) {
+    const task = assignedTasks[0];
+    taskActions.push(makeAutomationAction('task.claim', ['task', 'claim', '--peer', peerId, '--id', String(task.id)], `assigned task #${task.id}`, true, { task_id: task.id }));
+  } else if (!ownedTask && takeoverReadyTasks.length) {
+    const task = takeoverReadyTasks[0];
+    taskActions.push(makeAutomationAction(
+      'task.takeover',
+      ['task', 'takeover', '--peer', peerId, '--id', String(task.id), '--reason', 'owner stale and no active related locks', '--policy', 'stale'],
+      `task #${task.id} owner ${task.owner} is stale and has no active related locks`,
+      true,
+      { task_id: task.id, owner: task.owner, owner_age_sec: task.owner_age_sec ?? null }
+    ));
+  } else if (!ownedTask && availableTasks.length) {
+    taskActions.push(makeAutomationAction('task.next', ['task', 'next', '--peer', peerId], 'available pending task exists', true));
+  }
+
+  if (ownedTask) {
+    const readOnlyIntent = ['read', 'review', 'inspect'].includes(intent);
+    if (readOnlyIntent && resources.length) {
+      warnings.push(`intent=${intent} is read-only; do not acquire file locks for snapshot inspection`);
+    } else if (conflict) {
+      const requestedLabel = lockLabel(conflict);
+      const heldLabel = lockLabel(conflict.lock);
+      lockActions.push(makeAutomationAction(
+        'msg.send',
+        ['msg', 'send', '--from', peerId, '--to', conflict.lock.owner, '--task', String(ownedTask.id), '--body', `Please coordinate ${requestedLabel}; ${heldLabel} is locked by ${conflict.lock.owner}. If our edits are separate, split to scoped locks before final tests/commit.`],
+        `${requestedLabel} conflicts with ${heldLabel} held by ${conflict.lock.owner}`,
+        true,
+        { task_id: ownedTask.id, resource: conflict.base_resource, scope: conflict.scope, lock_owner: conflict.lock.owner, lock_resource: conflict.lock.resource, lock_scope: lockScope(conflict.lock) }
+      ));
+    } else if (missingLock) {
+      lockActions.push(makeAutomationAction(
+        'lock.acquire',
+        ['lock', 'acquire', '--peer', peerId, '--task', String(ownedTask.id), ...lockArgv(missingLock.base_resource, missingLock.scope), '--ttl', String(defaultLockTtl), '--reason', '<work>'],
+        `task #${ownedTask.id} needs ${lockLabel(missingLock)} lock`,
+        true,
+        { task_id: ownedTask.id, resource: missingLock.base_resource, scope: missingLock.scope }
+      ));
+    }
+    if (ownedTask.status === 'claimed') {
+      taskActions.push(makeAutomationAction('task.update', ['task', 'update', '--peer', peerId, '--id', String(ownedTask.id), '--status', 'running', '--summary', '<started>'], `task #${ownedTask.id} is claimed but not running`, true, { task_id: ownedTask.id }));
+    }
+    if (!ownedTask.parent_id && looksLikeMultiTask(ownedTask)) {
+      const childCount = openTasks.filter((task) => task.parent_id === ownedTask.id && !['done', 'abandoned'].includes(task.status)).length;
+      if (!childCount) {
+        taskActions.push(makeAutomationAction('team.plan', ['team', 'plan', '--from-task', String(ownedTask.id)], `task #${ownedTask.id} looks splittable; plan explicit team subtasks`, false, { task_id: ownedTask.id }));
+      }
+    }
+    automation.finish_actions.push(makeAutomationAction('handoff.create', ['handoff', 'create', '--from', peerId, '--task', String(ownedTask.id), '--summary', '<summary>', '--tests', '<tests>', '--risks', '<risks>'], `handoff task #${ownedTask.id} before stopping`, true, { task_id: ownedTask.id }));
+    automation.finish_actions.push(makeAutomationAction('task.done', ['task', 'done', '--peer', peerId, '--id', String(ownedTask.id), '--summary', '<summary>'], `mark task #${ownedTask.id} done after handoff`, true, { task_id: ownedTask.id }));
+    for (const lock of ownLocks) {
+      automation.finish_actions.push(makeAutomationAction('lock.release', ['lock', 'release', '--peer', peerId, ...lockArgv(lockBaseResource(lock), lockScope(lock))], `release ${lockLabel(lock)}`, true, { task_id: lock.task_id || null, resource: lockBaseResource(lock), scope: lockScope(lock) }));
+    }
+  }
+  automation.actions.push(...lockActions, ...messageActions, ...taskActions);
+
+  if (opts.intent === 'finish' || opts.intent === 'stop') {
+    automation.phase = ownedTask ? 'handoff' : 'idle';
+    automation.next_action = automation.finish_actions[0] || automation.next_action;
+    return automation;
+  }
+  automation.next_action = automation.actions[0] || (ownedTask
+    ? makeAutomationAction('none', [], `continue task #${ownedTask.id}`, false, { task_id: ownedTask.id })
+    : automation.next_action);
+  if (automation.next_action.kind === 'msg.reply' || automation.next_action.kind === 'msg.inbox') automation.phase = 'reply_message';
+  else if (automation.next_action.kind === 'task.claim' || automation.next_action.kind === 'task.next') automation.phase = 'claim_task';
+  else if (automation.next_action.kind === 'task.takeover') automation.phase = 'takeover_task';
+  else if (automation.next_action.kind === 'lock.acquire') automation.phase = 'acquire_lock';
+  else if (automation.next_action.kind === 'msg.send') automation.phase = 'coordinate_lock';
+  else if (automation.next_action.kind === 'team.plan') automation.phase = 'team_plan';
+  else if (ownedTask) automation.phase = ownedTask.status === 'review' ? 'handoff' : 'work';
+  return automation;
+}
+
+export function renderAutomationContext(automation) {
+  if (!automation) return '';
+  const lines = [
+    '[hello-cc next action]',
+    `phase: ${automation.phase}`,
+    automation.current_task ? `current_task: #${automation.current_task.id} ${automation.current_task.status} ${automation.current_task.title}` : null,
+    `next: ${automation.next_action.command || automation.next_action.kind}`,
+    `why: ${automation.next_action.reason}`
+  ].filter(Boolean);
+  if (automation.finish_actions?.length) {
+    lines.push('finish:');
+    for (const action of automation.finish_actions.slice(0, 4)) lines.push(`- ${action.command}`);
+  }
+  if (automation.warnings?.length) {
+    lines.push('warnings:');
+    for (const warning of automation.warnings.slice(0, 4)) lines.push(`- ${warning}`);
+  }
+  return lines.join('\n');
+}

package/lib/core/coordination/locks.mjs

@@ -0,0 +1,46 @@
+import { CliError } from '../../shared/errors.mjs';
+
+export const WHOLE_LOCK_SCOPE = '*';
+
+export function normalizeLockScope(scope) {
+  const text = String(scope || '').trim();
+  return text || WHOLE_LOCK_SCOPE;
+}
+
+export function scopedLockResource(resource, scope = WHOLE_LOCK_SCOPE) {
+  const baseResource = String(resource || '').trim();
+  const normalizedScope = normalizeLockScope(scope);
+  if (!baseResource) throw new CliError('BAD_ARGS', 'Missing --resource');
+  return {
+    resource: normalizedScope === WHOLE_LOCK_SCOPE
+      ? baseResource
+      : `scoped:${Buffer.from(JSON.stringify([baseResource, normalizedScope]), 'utf8').toString('base64url')}`,
+    base_resource: baseResource,
+    scope: normalizedScope
+  };
+}
+
+export function lockBaseResource(lock) {
+  return lock?.base_resource || lock?.resource || '';
+}
+
+export function lockScope(lock) {
+  return normalizeLockScope(lock?.scope);
+}
+
+export function lockLabel(lock) {
+  const base = lockBaseResource(lock);
+  const scope = lockScope(lock);
+  return scope === WHOLE_LOCK_SCOPE ? base : `${base} [${scope}]`;
+}
+
+export function lockArgv(resource, scope) {
+  const argv = ['--resource', resource];
+  if (normalizeLockScope(scope) !== WHOLE_LOCK_SCOPE) argv.push('--scope', normalizeLockScope(scope));
+  return argv;
+}
+
+export function locksConflict(a, b) {
+  return lockBaseResource(a) === lockBaseResource(b) &&
+    (lockScope(a) === WHOLE_LOCK_SCOPE || lockScope(b) === WHOLE_LOCK_SCOPE || lockScope(a) === lockScope(b));
+}

package/lib/core/coordination/messages.mjs

@@ -0,0 +1,116 @@
+import { CliError } from '../../shared/errors.mjs';
+
+function defaultNow() {
+  return Math.floor(Date.now() / 1000);
+}
+
+function noopEvent() {}
+
+export function createMessageStore(deps = {}) {
+  const now = typeof deps.now === 'function' ? deps.now : defaultNow;
+  const addEvent = typeof deps.addEvent === 'function' ? deps.addEvent : noopEvent;
+
+  function sendMessage(db, sender, recipient, taskId, kind, body, meta = {}) {
+    const replyTo = meta.reply_to || null;
+    const threadId = meta.thread_id || null;
+    const info = db.prepare(`
+      INSERT INTO messages(sender, recipient, task_id, kind, body, reply_to, thread_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(sender, recipient || 'all', taskId || null, kind || 'note', body, replyTo, threadId, now());
+    const messageId = Number(info.lastInsertRowid);
+    if (!threadId) {
+      db.prepare('UPDATE messages SET thread_id = ? WHERE id = ?').run(messageId, messageId);
+    }
+    addEvent(db, 'message.sent', sender, taskId || null, {
+      message_id: messageId,
+      recipient: recipient || 'all',
+      kind: kind || 'note',
+      reply_to: replyTo,
+      thread_id: threadId || messageId
+    });
+    return messageId;
+  }
+
+  function queryInbox(db, peer, includeAll, limit) {
+    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)
+      ORDER BY m.id ASC
+      LIMIT ?
+    `).all(peer, peer, includeAll ? 1 : 0, limit);
+  }
+
+  function queryTimelineMessages(db, peer, limit) {
+    if (!peer) {
+      return db.prepare(`
+        SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
+        FROM messages
+        ORDER BY id DESC
+        LIMIT ?
+      `).all(limit).reverse();
+    }
+    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.sender = ?
+        OR m.recipient IS NULL
+        OR m.recipient = ''
+        OR m.recipient = 'all'
+        OR m.recipient = ?
+      ORDER BY m.id DESC
+      LIMIT ?
+    `).all(peer, peer, peer, limit).reverse();
+  }
+
+  function getMessage(db, id) {
+    return db.prepare(`
+      SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
+      FROM messages
+      WHERE id = ?
+    `).get(id);
+  }
+
+  function queryMessageThread(db, messageId, limit) {
+    const message = getMessage(db, messageId);
+    if (!message) throw new CliError('NOT_FOUND', `Message #${messageId} does not exist`);
+    const threadId = message.thread_id || message.id;
+    const rows = db.prepare(`
+      SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
+      FROM messages
+      WHERE id = ? OR thread_id = ?
+      ORDER BY id ASC
+      LIMIT ?
+    `).all(message.id, threadId, limit);
+    return { message, thread_id: threadId, messages: rows };
+  }
+
+  function ackMessage(db, peer, message) {
+    db.prepare(`
+      INSERT INTO message_reads(message_id, peer, read_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(message_id, peer) DO UPDATE SET read_at = excluded.read_at
+    `).run(message.id, peer, now());
+    addEvent(db, 'message.ack', peer, message.task_id || null, { message_id: message.id });
+  }
+
+  return {
+    ackMessage,
+    getMessage,
+    queryInbox,
+    queryMessageThread,
+    queryTimelineMessages,
+    sendMessage
+  };
+}