@logicseek/hello-cc 0.1.4 → 0.1.6

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

package/lib/core/coordination/tasks.mjs

@@ -0,0 +1,224 @@
+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 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 new CliError('TASK_OWNED', `Task #${id} is owned by ${row.owner}`, { owner: row.owner });
+        }
+        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 };
+    });
+  }
+
+  return {
+    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]
+  }));
+}