flowcollab 0.1.0

package/bin/propose.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/* flow:propose — Claude submits a successor decision.
+
+   Usage:
+     flow-propose \
+       --parent=<task_id> \
+       --title="..." \
+       --md="..." \
+       --assignee=<actor_id> \
+       --priority=P0-now|P1-soon|P2-later \
+       --type=bug|feature|chore|docs \
+       --area=<area_label> \
+       --refs="doc#section,doc2#sec" \
+       --confidence=low|medium|high
+
+   Server enforces:
+   - No hardbaked-example patterns (HTTP 422 on match)
+   - Hard cap 3 pending per parent (HTTP 429)
+   - Dedup on title (HTTP 409)
+*/
+
+import { flowFetch, resolveTaskId, arg, die } from './_client.mjs';
+
+async function main() {
+  const parent = arg('parent') ? await resolveTaskId(arg('parent')) : null;
+  const title = arg('title');
+  const md = arg('md');
+  if (!title || !md) die('Required: --title="..." --md="..."');
+
+  const body = {
+    parent_task_id: parent,
+    proposal_title: title,
+    proposal_md: md,
+    suggested_assignee_id: arg('assignee') || null,
+    suggested_priority: arg('priority') || null,
+    suggested_type: arg('type') || null,
+    suggested_area: arg('area') || null,
+    source_refs: (arg('refs') || '').split(',').map(s => s.trim()).filter(Boolean),
+    confidence: arg('confidence') || 'medium',
+  };
+
+  try {
+    const r = await flowFetch('/api/flow/propose', { method: 'POST', body });
+    process.stdout.write(`Proposal accepted: #${r.decision.id.slice(0, 6)}\n`);
+    process.stdout.write(`  Title: ${r.decision.proposal_title}\n`);
+    process.stdout.write(`  Suggested assignee: ${r.decision.suggested_assignee_id || '-'}\n`);
+    process.stdout.write(`  Source refs: ${(r.decision.source_refs || []).join(', ') || '-'}\n`);
+    process.stdout.write('\nThe user will see this in the "Awaiting Direction" column.\n');
+  } catch (e) {
+    if (e.status === 422) die(`Rejected — hardbaked pattern in proposal. ${e.body?.detail || ''}`);
+    if (e.status === 429) die('Rejected — hard cap of 3 pending decisions per parent already reached.');
+    if (e.status === 409) die('Rejected — duplicate of an existing pending decision.');
+    die(e.message || e);
+  }
+}
+
+main().catch(e => die(e.message || e));

package/bin/pull.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/* flow:pull — fetch tasks + decisions + recent timeline and print a Claude-ready summary.
+
+   Usage:
+     flow-pull                     # respects FLOW_DEFAULT_ASSIGNEE env
+     flow-pull --assignee=nate  # explicit filter
+     flow-pull --assignee=all   # unfiltered (full board)
+
+   The CLI surfaces three things Claude must scan on every pull:
+     1. *** MENTIONS *** banner: timeline comments addressed to you
+     2. Filtered board snapshot (your tasks only by default)
+     3. Recent timeline activity on YOUR tasks (last 5 per task)
+*/
+
+import { flowFetch, arg } from './_client.mjs';
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// Per-status age threshold (days) before pull flags a task as aging.
+// Override with FLOW_AGING_THRESHOLDS={"in_progress":3,"in_review":2} env var.
+const AGING = (() => {
+  try { return process.env.FLOW_AGING_THRESHOLDS ? JSON.parse(process.env.FLOW_AGING_THRESHOLDS) : null; }
+  catch { return null; }
+})() || { in_progress: 3, in_review: 2, todo: 7 };
+
+// Sanitize user-controlled text before printing to stdout.
+// Defends against prompt injection: a comment containing newlines, ANSI codes,
+// or @to: tokens can inject fake structured sections into pull output that
+// another Claude reads as trusted shell output.
+function sanitizeText(s, maxLen = 400) {
+  if (!s || typeof s !== 'string') return '';
+  return s
+    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')             // strip ANSI escape sequences
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')  // strip control chars (keep \t \n)
+    .replace(/@to:\S+/g, '[mention-stripped]')           // prevent nested @to: injection
+    .replace(/\r?\n|\r/g, ' ↵ ')                         // collapse newlines to visible marker
+    .trim()
+    .slice(0, maxLen);
+}
+
+function pad(s, n) { return String(s).padEnd(n).slice(0, n); }
+
+const PRIO_RANK = { 'P0-now': 0, 'P1-soon': 1, 'P2-later': 2 };
+const STATUS_RANK = { in_progress: 0, in_review: 1, todo: 2, backlog: 3, awaiting_direction: 4 };
+
+function fmtTask(t) {
+  const miTag = t.milestone ? ` [${t.milestone}]` : '';
+  const prTag = t.pr_num ? ` [PR #${t.pr_num}: ${t.pr_state || 'open'}]` : '';
+  const parts = [
+    pad(`#${t.issue_num ?? t.id.slice(0, 6)}`, 8),
+    pad(t.status, 12),
+    pad(t.priority || '-', 9),
+    pad(t.assignee_id || '(unassigned)', 14),
+    t.title + miTag + prTag,
+  ];
+  return parts.join('  ');
+}
+
+function fmtDecision(d) {
+  return `#${d.id.slice(0, 6)}  [${d.confidence}] ${sanitizeText(d.proposal_title, 120)}  (suggest: ${d.suggested_assignee_id || '-'}/${d.suggested_priority || '-'})  refs: ${(d.source_refs || []).join(', ') || '-'}`;
+}
+
+function extractBody(ev) {
+  const p = ev.payload || {};
+  if (p.comment) return sanitizeText(p.comment);
+  if (ev.kind === 'event') {
+    const act = p.act;
+    if (act === 'claimed') return '[claimed]';
+    if (act === 'closed') return `[closed${p.summary ? ': ' + sanitizeText(p.summary, 200) : ''}]`;
+    if (act === 'assigned') return `[assigned → ${p.assignee_id || 'unassigned'}]`;
+    if (act === 'promoted_from_decision') return '[promoted from awaiting-direction]';
+    return `[${act || 'event'}]`;
+  }
+  return `[${ev.kind}]`;
+}
+
+function fmtTimeline(ev, taskTitle) {
+  const ts = ev.ts ? new Date(ev.ts).toISOString().replace('T', ' ').slice(0, 16) : '?';
+  const who = ev.actor_id || '?';
+  const actingAs = ev.acting_as_id && ev.acting_as_id !== ev.actor_id ? `(as ${ev.acting_as_id})` : '';
+  const body = extractBody(ev);
+  // Wrap user-generated comments in XML markers so Claude distinguishes them
+  // from structured pull output and cannot be injected via timeline text.
+  const wrapped = ev.kind === 'comment'
+    ? `<comment_from_untrusted_user>${body}</comment_from_untrusted_user>`
+    : body;
+  return `  ${ts}  ${who}${actingAs}  on "${sanitizeText(taskTitle, 120)}": ${wrapped}`;
+}
+
+function mentionRegex(assignee) {
+  const a = assignee.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`@to:(?:${a}-claude|${a}|claude)(?=[\\s.,;:!?)\\]]|$)`, 'i');
+}
+
+async function main() {
+  const explicit = arg('assignee');
+  const envDefault = process.env.FLOW_DEFAULT_ASSIGNEE || '';
+  const filterAssignee = explicit === 'all' ? '' : (explicit || envDefault);
+  const focusMode = arg('focus') !== undefined;
+  const filterMilestone = arg('milestone') || '';
+
+  const [tasksRes, decRes, presenceRes] = await Promise.all([
+    flowFetch('/api/flow/tasks?limit=200'),
+    flowFetch('/api/flow/decisions'),
+    flowFetch('/api/flow/presence').catch(() => null),
+  ]);
+
+  const allTasks = tasksRes.tasks || [];
+  const allTimeline = tasksRes.timeline || [];
+  if (tasksRes.has_more) {
+    process.stderr.write(`⚠  Board has more than 200 tasks — snapshot truncated to most recently updated 200.\n`);
+  }
+  const taskById = new Map(allTasks.map(t => [t.id, t]));
+
+  let tasks = allTasks;
+  if (filterAssignee) tasks = tasks.filter(t => t.assignee_id === filterAssignee);
+  if (filterMilestone) tasks = tasks.filter(t => t.milestone === filterMilestone);
+  const myTaskIds = new Set(tasks.map(t => t.id));
+
+  const out = [];
+
+  // 0. Active agents — other agents heartbeating right now
+  if (presenceRes?.agents?.length) {
+    const myActorId = process.env.FLOW_TOKEN_OWNER_ACTOR || process.env.FLOW_TOKEN_CONTRIBUTOR_ACTOR || '';
+    const others = presenceRes.agents.filter(a => a.actor_id !== myActorId);
+    if (others.length) {
+      out.push(`[active agents — ${others.length} other${others.length === 1 ? '' : 's'} online]`);
+      for (const a of others) {
+        const task = a.task_id ? taskById.get(a.task_id) : null;
+        const taskRef = task
+          ? `working on #${task.issue_num ?? a.task_id.slice(0, 6)} "${sanitizeText(task.title, 60)}"`
+          : 'idle';
+        const ago = Math.round((Date.now() - new Date(a.last_seen_at).getTime()) / 60000);
+        out.push(`  ${a.actor_id}  ${taskRef}  (seen ${ago}m ago)`);
+      }
+      out.push('');
+    }
+  }
+
+  // 1. Mentions banner — scan ALL timeline for @to:me
+  if (filterAssignee) {
+    const re = mentionRegex(filterAssignee);
+    const mentions = allTimeline
+      .filter(ev => re.test(extractBody(ev)))
+      .sort((a, b) => (b.ts || '').localeCompare(a.ts || ''));
+    if (mentions.length) {
+      out.push('*** MENTIONS *** ' + mentions.length + ' comment' + (mentions.length === 1 ? '' : 's') + ' addressed to you (@to:' + filterAssignee + ' / -claude / claude):');
+      mentions.slice(0, 10).forEach(ev => {
+        const t = taskById.get(ev.task_id);
+        const title = t ? t.title : '(unknown task)';
+        const taskRef = t ? `#${t.issue_num ?? t.id.slice(0, 6)}` : `#${ev.task_id.slice(0, 6)}`;
+        const ts = ev.ts ? new Date(ev.ts).toISOString().replace('T', ' ').slice(0, 16) : '?';
+        out.push(`  ${taskRef}  ${title}  (${ts}, from ${ev.actor_id || '?'})`);
+        out.push(`    └─ <comment_from_untrusted_user>${extractBody(ev)}</comment_from_untrusted_user>`);
+      });
+      if (mentions.length > 10) out.push(`  … and ${mentions.length - 10} older mention${mentions.length - 10 === 1 ? '' : 's'} not shown`);
+      out.push('');
+      out.push('Respond to mentions before claiming new work.');
+      out.push('');
+    }
+  }
+
+  // 1b. Overdue tasks — past due_at and not done
+  const nowDate = new Date();
+  const overdueTasks = allTasks
+    .filter(t => t.due_at && new Date(t.due_at) < nowDate && t.status !== 'done')
+    .sort((a, b) => new Date(a.due_at) - new Date(b.due_at));
+  if (overdueTasks.length) {
+    out.push(`⚠  OVERDUE — ${overdueTasks.length} task${overdueTasks.length === 1 ? '' : 's'} past due date:`);
+    for (const t of overdueTasks) {
+      const daysAgo = Math.round((nowDate - new Date(t.due_at)) / 86400000);
+      const dueLabel = daysAgo < 1 ? 'today' : daysAgo === 1 ? '1 day ago' : `${daysAgo} days ago`;
+      out.push(`  #${t.issue_num ?? t.id.slice(0, 6)}  ${sanitizeText(t.title, 60)}  (due ${dueLabel}, ${t.assignee_id || 'unassigned'})`);
+    }
+    out.push('');
+  }
+
+  // 1c. Stale claim detection — in_progress tasks with no activity for >4h
+  const STALE_HOURS = 4;
+  const staleMs = STALE_HOURS * 60 * 60 * 1000;
+  const nowMs = Date.now();
+  const staleTasks = allTasks.filter(t =>
+    t.status === 'in_progress' && t.updated_at &&
+    (nowMs - new Date(t.updated_at).getTime()) > staleMs
+  );
+  if (staleTasks.length) {
+    out.push(`⚠  STALE CLAIMS — ${staleTasks.length} task${staleTasks.length === 1 ? '' : 's'} in_progress with no activity in ${STALE_HOURS}h+:`);
+    for (const t of staleTasks) {
+      const hrs = Math.round((nowMs - new Date(t.updated_at).getTime()) / 3600000);
+      out.push(`  #${t.issue_num ?? t.id.slice(0, 6)}  ${sanitizeText(t.title, 60)}  (${t.assignee_id || 'unassigned'}, idle ${hrs}h)`);
+    }
+    out.push('  Force-unclaim via the board UI (owner only).');
+    out.push('');
+  }
+
+  // 1c. Handoffs addressed to me
+  if (filterAssignee) {
+    const myHandoffs = allTimeline
+      .filter(ev => ev.kind === 'event' && ev.payload?.act === 'handoff' && ev.payload?.to === filterAssignee)
+      .sort((a, b) => (b.ts || '').localeCompare(a.ts || ''))
+      .slice(0, 5);
+    if (myHandoffs.length) {
+      out.push(`*** HANDOFFS *** ${myHandoffs.length} task${myHandoffs.length === 1 ? '' : 's'} handed off to you:`);
+      for (const ev of myHandoffs) {
+        const t = taskById.get(ev.task_id);
+        const ref = t ? `#${t.issue_num ?? t.id.slice(0, 6)}` : `#${ev.task_id.slice(0, 6)}`;
+        const title = t ? sanitizeText(t.title, 60) : '(unknown task)';
+        const ts = ev.ts ? new Date(ev.ts).toISOString().replace('T', ' ').slice(0, 16) : '?';
+        out.push(`  ${ref}  ${title}  (from ${ev.actor_id || '?'}, ${ts})`);
+        const hd = t?.handoff_data;
+        if (hd?.context || ev.payload?.context) {
+          out.push(`    context:   <comment_from_untrusted_user>${sanitizeText(hd?.context || ev.payload.context, 300)}</comment_from_untrusted_user>`);
+        }
+        if (hd?.branch || ev.payload?.branch) {
+          out.push(`    branch:    ${sanitizeText(hd?.branch || ev.payload.branch, 100)}`);
+        }
+        if (hd?.next_step) {
+          out.push(`    next step: ${sanitizeText(hd.next_step, 200)}`);
+        }
+        if (hd?.files?.length) {
+          out.push(`    files:     ${hd.files.slice(0, 8).join(', ')}${hd.files.length > 8 ? ` +${hd.files.length - 8} more` : ''}`);
+        }
+        if (hd?.questions?.length) {
+          out.push(`    open questions:`);
+          for (const q of hd.questions.slice(0, 5)) {
+            out.push(`      - <comment_from_untrusted_user>${sanitizeText(q, 200)}</comment_from_untrusted_user>`);
+          }
+        }
+      }
+      out.push('');
+      out.push('Claim and continue where they left off.');
+      out.push('');
+    }
+  }
+
+  // 1e. Blocked task warnings — in_progress tasks with unresolved dependencies
+  if (filterAssignee) {
+    const blockedActive = tasks.filter(t =>
+      t.status === 'in_progress' && t.blocked_by?.length &&
+      t.blocked_by.some(bid => {
+        const b = taskById.get(bid);
+        return !b || b.status !== 'done';
+      })
+    );
+    if (blockedActive.length) {
+      out.push(`⚠  BLOCKED — ${blockedActive.length} in_progress task${blockedActive.length === 1 ? '' : 's'} with unresolved dependencies:`);
+      for (const t of blockedActive) {
+        out.push(`  #${t.issue_num ?? t.id.slice(0, 6)}  ${sanitizeText(t.title, 60)}`);
+        for (const bid of t.blocked_by) {
+          const b = taskById.get(bid);
+          if (!b || b.status === 'done') continue;
+          out.push(`    ← blocked by: #${b.issue_num ?? b.id.slice(0, 6)} ${sanitizeText(b.title, 40)} [${b.status}]`);
+        }
+      }
+      out.push('');
+    }
+  }
+
+  // 1f. Aging warnings — tasks sitting in a status longer than the threshold
+  const agingWarn = [];
+  for (const [status, days] of Object.entries(AGING)) {
+    const threshMs = days * 86400000;
+    for (const t of allTasks.filter(t => t.status === status)) {
+      if (!t.updated_at) continue;
+      const ageMs = nowMs - new Date(t.updated_at).getTime();
+      if (ageMs > threshMs) {
+        agingWarn.push({ task: t, ageDays: Math.floor(ageMs / 86400000), status });
+      }
+    }
+  }
+  if (agingWarn.length) {
+    out.push(`⚠  AGING — ${agingWarn.length} task${agingWarn.length === 1 ? '' : 's'} overdue for movement:`);
+    for (const { task: t, ageDays, status } of agingWarn) {
+      out.push(`  #${t.issue_num ?? t.id.slice(0, 6)}  ${sanitizeText(t.title, 60)}  (${status} for ${ageDays}d, ${t.assignee_id || 'unassigned'})`);
+    }
+    out.push('');
+  }
+
+  // 2. Board snapshot (filtered)
+  // 2a. Milestone overview (when tasks use milestones)
+  const milestoneGroups = {};
+  for (const t of allTasks) {
+    if (!t.milestone) continue;
+    if (!milestoneGroups[t.milestone]) milestoneGroups[t.milestone] = { total: 0, done: 0 };
+    milestoneGroups[t.milestone].total++;
+    if (t.status === 'done') milestoneGroups[t.milestone].done++;
+  }
+  if (Object.keys(milestoneGroups).length) {
+    out.push('[milestones]');
+    for (const [name, s] of Object.entries(milestoneGroups)) {
+      const pct = Math.round((s.done / s.total) * 100);
+      const bar = '█'.repeat(Math.round(pct / 10)) + '░'.repeat(10 - Math.round(pct / 10));
+      out.push(`  ${name}  ${bar}  ${s.done}/${s.total} done (${pct}%)`);
+    }
+    out.push('');
+  }
+
+  const snapshotLabel = [
+    filterAssignee ? `assignee=${filterAssignee}` : null,
+    filterMilestone ? `milestone=${filterMilestone}` : null,
+    focusMode ? 'focus' : null,
+  ].filter(Boolean).join(', ') || 'unfiltered';
+
+  out.push(`=== Flow board snapshot (${snapshotLabel}) ===`);
+
+  if (focusMode) {
+    const open = tasks.filter(t => t.status !== 'done' && t.status !== 'awaiting_direction');
+    const top3 = [...open].sort((a, b) => {
+      const pr = (PRIO_RANK[a.priority] ?? 9) - (PRIO_RANK[b.priority] ?? 9);
+      if (pr !== 0) return pr;
+      return (STATUS_RANK[a.status] ?? 9) - (STATUS_RANK[b.status] ?? 9);
+    }).slice(0, 3);
+    if (top3.length) top3.forEach(t => out.push('  ' + fmtTask(t)));
+    else out.push('  (no open tasks)');
+  } else {
+    const byStatus = {
+      in_progress: tasks.filter(t => t.status === 'in_progress'),
+      in_review: tasks.filter(t => t.status === 'in_review'),
+      todo: tasks.filter(t => t.status === 'todo'),
+      backlog: tasks.filter(t => t.status === 'backlog').slice(0, 10),
+    };
+    let anyTasks = false;
+    for (const [col, arr] of Object.entries(byStatus)) {
+      if (!arr.length) continue;
+      anyTasks = true;
+      out.push(`\n[${col}]  ${arr.length} task${arr.length === 1 ? '' : 's'}`);
+      arr.forEach(t => out.push('  ' + fmtTask(t)));
+    }
+    if (!anyTasks) out.push('  (no tasks)');
+  }
+
+  // 3. Overlap watch
+  if (filterAssignee) {
+    const others = allTasks.filter(
+      t => t.status === 'in_progress' && t.assignee_id && t.assignee_id !== filterAssignee
+    );
+    if (others.length) {
+      out.push('\n[overlap watch — in-progress by others]');
+      others.forEach(t => out.push('  ' + fmtTask(t)));
+    }
+  }
+
+  // 4. Recent timeline on YOUR tasks (last 5 per task, newest first)
+  const activeTaskIds = new Set([...myTaskIds].filter(id => {
+    const t = taskById.get(id);
+    return t && t.status !== 'closed';
+  }));
+  if (activeTaskIds.size && allTimeline.length) {
+    const recentByTask = new Map();
+    const sortedTimeline = [...allTimeline].sort((a, b) => (b.ts || '').localeCompare(a.ts || ''));
+    for (const ev of sortedTimeline) {
+      if (!activeTaskIds.has(ev.task_id)) continue;
+      if (!recentByTask.has(ev.task_id)) recentByTask.set(ev.task_id, []);
+      const arr = recentByTask.get(ev.task_id);
+      if (arr.length < 5) arr.push(ev);
+    }
+    if (recentByTask.size) {
+      out.push('\n[recent activity on your tasks]');
+      for (const [tid, evs] of recentByTask) {
+        const t = taskById.get(tid);
+        const title = t ? t.title : tid;
+        evs.forEach(ev => out.push(fmtTimeline(ev, title)));
+      }
+    }
+  }
+
+  // 5. Decisions
+  const decisions = decRes.decisions || [];
+  out.push(`\n[awaiting direction]  ${decisions.length} pending`);
+  decisions.forEach(d => out.push('  ' + fmtDecision(d)));
+
+  out.push('\nTip: claim a task with `flow-claim <task_id>`');
+  out.push('     Add --focus for top-3 by priority · --milestone=<name> to filter by sprint · --assignee=all for full board');
+
+  process.stdout.write(out.join('\n') + '\n');
+
+  // --sync-md: fetch server-rendered CLAUDE.md and write to CWD
+  if (arg('sync-md') !== undefined) {
+    try {
+      const mdRes = await flowFetch('/api/flow/claudemd');
+      const mdText = mdRes.raw || (typeof mdRes === 'string' ? mdRes : null);
+      if (!mdText) throw new Error('empty response');
+      const dest = join(process.cwd(), 'CLAUDE.md');
+      writeFileSync(dest, mdText, 'utf8');
+      process.stdout.write(`\n✓ CLAUDE.md updated (${dest})\n`);
+    } catch (e) {
+      process.stderr.write(`flow-pull: --sync-md failed: ${e.message}\n`);
+    }
+  }
+}
+
+main().catch(e => { process.stderr.write('pull failed: ' + (e.message || e) + '\n'); process.exit(1); });

package/bin/reject.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/* flow:reject — reject a pending decision.
+   Usage: flow-reject <decision_id> [--reason="..."]
+*/
+
+import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+
+async function main() {
+  const raw = positional(0);
+  if (!raw) die('Usage: flow-reject <decision_id> [--reason="..."]');
+  const id = await resolveTaskId(raw);
+  const reason = arg('reason');
+  await flowFetch(`/api/flow/decisions/${id}/reject`, {
+    method: 'POST', body: reason ? { reason } : {},
+  });
+  process.stdout.write('Rejected.\n');
+}
+
+main().catch(e => die(e.message || e));

package/bin/review.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/* flow:review — request a code review for a task's PR.
+   Moves the task to in_review (if in_progress) and posts a standardised
+   review-request comment that appears in the timeline and triggers @mention
+   notifications. If --reviewer is given, also pings that actor's personal
+   webhook directly (bypasses the @mention comment path).
+
+   Usage:
+     flow-review <task-id> [--pr=<number>] [--reviewer=<actor-id>] [--context="notes"]
+
+   If the task already has a PR linked (pr_num set by the webhook), --pr is
+   optional. If neither is present the command aborts with a clear error.
+*/
+
+import 'dotenv/config';
+import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+
+async function main() {
+  const rawId = positional(0);
+  if (!rawId) die('Usage: flow-review <task-id> [--pr=<number>] [--reviewer=<actor>] [--context="..."]');
+
+  const prArg      = arg('pr');
+  const reviewerArg = arg('reviewer', '');
+  const context    = arg('context', '');
+
+  const taskId = await resolveTaskId(rawId);
+
+  // Fetch tasks + people in parallel.
+  const [{ tasks = [] }, { people = {} }] = await Promise.all([
+    flowFetch('/api/flow/tasks?limit=500'),
+    flowFetch('/api/flow/people'),
+  ]);
+
+  const task = tasks.find(t => t.id === taskId);
+  if (!task) die(`Task ${taskId} not found.`);
+
+  const prNum = prArg ? parseInt(prArg, 10) : (task.pr_num ?? null);
+  if (!prNum) {
+    die(
+      `No PR linked to task #${task.issue_num ?? taskId.slice(0, 6)}.\n` +
+      'Either open a PR (the webhook will link it automatically) or pass --pr=<number>.'
+    );
+  }
+
+  const repo = process.env.FLOW_GITHUB_REPO ?? '';
+  const prUrl = repo ? `https://github.com/${repo}/pull/${prNum}` : '';
+
+  // Compose the comment. Include @mention if reviewer specified so timeline
+  // notification routing fires for them automatically.
+  const mentionPart = reviewerArg ? `@to:${reviewerArg} ` : '';
+  const urlPart     = prUrl ? `\n${prUrl}` : '';
+  const ctxPart     = context ? `\n\n${context}` : '';
+  const body        = `${mentionPart}Review requested: PR #${prNum}${urlPart}${ctxPart}`;
+
+  await flowFetch('/api/flow/comment', { method: 'POST', body: { task_id: taskId, body } });
+
+  // If reviewer has a personal webhook, ping it directly too (fire-and-forget).
+  if (reviewerArg) {
+    const peopleArr = Array.isArray(people) ? people : Object.values(people);
+    const reviewer = peopleArr.find(p => p.id === reviewerArg);
+    const hook = reviewer?.notify_webhook || process.env.FLOW_NOTIFY_WEBHOOK;
+    if (hook) {
+      const ref = `#${task.issue_num ?? taskId.slice(0, 6)}`;
+      fetch(hook, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          text: `Review requested on ${ref} — PR #${prNum}${prUrl ? ' ' + prUrl : ''}${context ? '\n' + context : ''}`,
+        }),
+      }).catch(() => {});
+    }
+  }
+
+  // Move to in_review if currently in_progress.
+  if (task.status === 'in_progress') {
+    await flowFetch(`/api/flow/tasks/${taskId}`, { method: 'PATCH', body: { status: 'in_review' } });
+  }
+
+  const ref   = `#${task.issue_num ?? taskId.slice(0, 6)}`;
+  const moved = task.status === 'in_progress' ? '  (moved → in_review)' : '';
+  const pinged = reviewerArg ? `  (pinged ${reviewerArg})` : '';
+  process.stdout.write(`Review requested on ${ref} — PR #${prNum}${prUrl ? '  ' + prUrl : ''}${moved}${pinged}\n`);
+}
+
+main().catch(e => die(e.message || e));

package/bin/search.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/* flow:search — find tasks by keyword and optional filters.
+   Usage:
+     flow-search "auth bug"
+     flow-search "token" --status=in_progress
+     flow-search "ui" --area=frontend --assignee=nate
+*/
+
+import { flowFetch, arg, positional } from './_client.mjs';
+
+function pad(s, n) { return String(s).padEnd(n).slice(0, n); }
+
+async function main() {
+  const q = positional(0) || arg('q') || '';
+  const status   = arg('status');
+  const area     = arg('area');
+  const assignee = arg('assignee');
+
+  if (!q && !status && !area && !assignee) {
+    process.stderr.write('Usage: flow-search "query" [--status=] [--area=] [--assignee=]\n');
+    process.exit(1);
+  }
+
+  const params = new URLSearchParams();
+  if (q)        params.set('q', q);
+  if (status)   params.set('status', status);
+  if (area)     params.set('area', area);
+  if (assignee) params.set('assignee', assignee);
+
+  const r = await flowFetch(`/api/flow/search?${params}`);
+  const tasks = r.tasks || [];
+
+  if (!tasks.length) {
+    process.stdout.write('No tasks found.\n');
+    return;
+  }
+
+  process.stdout.write(`Found ${tasks.length} task${tasks.length === 1 ? '' : 's'}:\n\n`);
+  for (const t of tasks) {
+    const ref = `#${t.issue_num ?? t.id.slice(0, 6)}`;
+    const due = t.due_at ? `  due:${t.due_at.slice(0, 10)}` : '';
+    process.stdout.write(
+      `${pad(ref, 8)}  ${pad(t.status, 12)}  ${pad(t.priority || '-', 9)}  ${pad(t.assignee_id || '-', 14)}  ${t.title}${due}\n`
+    );
+  }
+}
+
+main().catch(e => { process.stderr.write('search failed: ' + (e.message || e) + '\n'); process.exit(1); });