flowcollab 0.3.18 → 0.3.20

package/bin/_commands.mjs

@@ -0,0 +1,75 @@
+/* Single source of truth for the Flow CLI command catalog.
+ *
+ * Consumed by:
+ *   - bin/flow.mjs         → the `flow <cmd>` router + `flow --help` list
+ *   - routes/flow.js       → the "All CLI commands" block in GET /claudemd
+ *   - test/commands.test.js → drift guard (every command here has a bin file,
+ *                             a package.json bin entry, and a ui/docs.html card)
+ *
+ * Add a command in ONE place (here) and every surface stays in sync.
+ * Fields:
+ *   name    — the subcommand (`flow <name>` / `flow-<name>`)
+ *   file    — the bin module it dispatches to
+ *   summary — one line for `flow --help`
+ *   usage   — full signature + flags for the docs / CLAUDE.md reference
+ */
+export const CLI_COMMANDS = [
+  { name: 'login',        file: 'login.mjs',        summary: 'Authorize the CLI via browser (device flow)',
+    usage: 'flow-login [--server=<url>]                    — browser device-flow auth; writes ~/.flow/config.json' },
+  { name: 'pull',         file: 'pull.mjs',          summary: 'Fetch board snapshot + @mentions (start of day)',
+    usage: 'flow-pull [--focus] [--milestone=<name>] [--sync-md]  — board snapshot + mentions + handoffs; --sync-md rewrites CLAUDE.md' },
+  { name: 'claim',        file: 'claim.mjs',         summary: 'Claim a task and mark it in-progress',
+    usage: 'flow-claim <id> [--files=a,b] [--watch]        — self-assign; warns on file conflicts; --watch retries on 409' },
+  { name: 'comment',      file: 'comment.mjs',       summary: 'Post a comment (--commit[=<sha>] links a clickable diff)',
+    usage: 'flow-comment <id> "..." [--commit[=<sha>]]     — add a comment; --commit links a commit (or HEAD) → clickable diff' },
+  { name: 'close',        file: 'close.mjs',         summary: 'Mark a task done with a summary',
+    usage: 'flow-close <id> "summary"                      — mark task done' },
+  { name: 'create',       file: 'create.mjs',        summary: 'Create a new task',
+    usage: 'flow-create --title="..." [--type=] [--area=] [--priority=] [--due=] [--blocked-by=<uuid>] [--milestone=] [--from-issue=<num>] [--template=<id>]' },
+  { name: 'edit',         file: 'edit.mjs',          summary: 'Update task fields (title, priority, area, due…)',
+    usage: 'flow-edit <id> [--title=] [--priority=] [--area=] [--due=] [--milestone=] [--blocked-by=<uuid>|null]' },
+  { name: 'unblock',      file: 'unblock.mjs',       summary: "Clear a task's blocked-by dependency",
+    usage: 'flow-unblock <id>                              — clear blocked_by' },
+  { name: 'propose',      file: 'propose.mjs',       summary: 'Propose a sub-task for human approval',
+    usage: 'flow-propose --parent=<id> --title="..." --md="..."  — propose work for approval' },
+  { name: 'approve',      file: 'approve.mjs',       summary: 'Approve a pending proposal',
+    usage: 'flow-approve <id>                              — approve a proposal (owner only)' },
+  { name: 'reject',       file: 'reject.mjs',        summary: 'Reject a pending proposal with a reason',
+    usage: 'flow-reject <id> "reason"                      — reject a proposal (owner only)' },
+  { name: 'assign',       file: 'assign.mjs',        summary: 'Assign a task to another actor',
+    usage: 'flow-assign <id> <actor>                       — reassign (owner only)' },
+  { name: 'decisions',    file: 'decisions.mjs',     summary: 'List pending proposals (--watch <id> blocks until resolved)',
+    usage: 'flow-decisions [--watch <id>]                  — list pending; --watch blocks until <id> resolves (exit 0/1/2/3/4)' },
+  { name: 'handoff',      file: 'handoff.mjs',       summary: 'Hand off a task to another agent',
+    usage: 'flow-handoff --task=<id> --to=<actor> --context="..." [--branch=] [--questions="q1|q2"] [--next-step="..."]' },
+  { name: 'review',       file: 'review.mjs',        summary: 'Request code review; moves task to in-review',
+    usage: 'flow-review <id> [--pr=<num>] [--reviewer=<actor>] [--context="..."]' },
+  { name: 'search',       file: 'search.mjs',        summary: 'Search tasks by text, status, area, or assignee',
+    usage: 'flow-search "query" [--status=] [--area=] [--assignee=]' },
+  { name: 'status',       file: 'status.mjs',        summary: 'Quick board summary',
+    usage: 'flow-status                                    — board summary' },
+  { name: 'standup',      file: 'standup.mjs',       summary: 'Done/in-progress digest; --velocity for trend chart',
+    usage: 'flow-standup [--since=<hours>] [--velocity]     — activity digest; --velocity adds a week-over-week chart' },
+  { name: 'sync',         file: 'sync.mjs',          summary: 'Delta sync since N minutes (default 60)',
+    usage: 'flow-sync [--since=<minutes>]                  — delta update' },
+  { name: 'log',          file: 'log.mjs',           summary: 'Tail recent timeline events',
+    usage: 'flow-log [--task=<id>] [--limit=20]            — tail timeline events (board-wide without --task)' },
+  { name: 'heartbeat',    file: 'heartbeat.mjs',     summary: 'Send a presence ping (~60s while active)',
+    usage: 'flow-heartbeat [--task=<id>]                   — presence ping' },
+  { name: 'ping',         file: 'ping.mjs',          summary: 'Health check or send a direct agent message',
+    usage: 'flow-ping [<actor> "message"]                  — 0 args: health check; 2 args: message an actor' },
+  { name: 'pr',           file: 'pr.mjs',            summary: 'Record a PR link on a task timeline',
+    usage: 'flow-pr <id> <pr_url>                          — record a PR link on a task' },
+  { name: 'project',      file: 'project.mjs',       summary: 'List GitHub Projects v2 items',
+    usage: 'flow-project [--project=<node_id>]             — list GitHub Projects v2 items' },
+  { name: 'archive',      file: 'archive.mjs',       summary: 'Archive or unarchive a task (--undo to restore)',
+    usage: 'flow-archive <id> [--undo]                     — archive/unarchive a task (owner only)' },
+  { name: 'scan',         file: 'scan.mjs',          summary: 'Audit for TODOs, untracked Issues, unlinked PRs, security patterns',
+    usage: 'flow-scan [--todos] [--issues] [--prs] [--security]  — audit codebase for untracked work' },
+  { name: 'close-sprint', file: 'close-sprint.mjs',  summary: 'Close a sprint milestone (owner only)',
+    usage: 'flow-close-sprint --milestone=<name> [--archive-done]  — owner only' },
+  { name: 'whoami',       file: 'whoami.mjs',        summary: 'Verify token and show current identity',
+    usage: 'flow-whoami                                    — verify token + show identity' },
+  { name: 'completion',   file: 'completion.mjs',    summary: 'Print shell completion script (bash/zsh/fish)',
+    usage: 'flow-completion <bash|zsh|fish>                — print shell completion script' },
+];

package/bin/approve.mjs

@@ -5,7 +5,7 @@
      flow-approve <decision_id> --title="override" --assignee=...
 */
 
-import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, positional, arg, die, sanitizeText } from './_client.mjs';
 
 async function main() {
   const raw = positional(0);
@@ -21,7 +21,7 @@ async function main() {
   const r = await flowFetch(`/api/flow/decisions/${id}/approve`, {
     method: 'POST', body: overrides,
   });
-  process.stdout.write(`Promoted to task #${r.task.id.slice(0, 6)} — "${r.task.title}"\n`);
+  process.stdout.write(`Promoted to task #${r.task.id.slice(0, 6)} — "${sanitizeText(r.task.title, 80)}"\n`);
 }
 
 main().catch(e => die(e.message || e));

package/bin/archive.mjs

@@ -8,7 +8,7 @@
      flow-archive <task-id> --undo   # unarchive
 */
 
-import { flowFetch, RESOLVED_ACTOR } from './_client.mjs';
+import { flowFetch, RESOLVED_ACTOR, sanitizeText } from './_client.mjs';
 
 const [,, taskId, ...rest] = process.argv;
 const undo = rest.includes('--undo');
@@ -30,4 +30,4 @@ const res = await flowFetch(endpoint, { method: 'POST' }).catch(e => {
 const t = res.task;
 const ref = `#${t.issue_num ?? taskId.slice(0, 6)}`;
 const verb = undo ? 'Unarchived' : 'Archived';
-process.stdout.write(`${verb} ${ref}: ${t.title}\n`);
+process.stdout.write(`${verb} ${ref}: ${sanitizeText(t.title, 80)}\n`);

package/bin/assign.mjs

@@ -8,7 +8,7 @@
    Server-side: human-only (claude alone cannot push work onto humans).
 */
 
-import { flowFetch, resolveTaskId, positional, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, positional, die, sanitizeText } from './_client.mjs';
 
 async function main() {
   const raw = positional(0);
@@ -23,7 +23,7 @@ async function main() {
       method: 'POST',
       body: { assignee_id },
     });
-    process.stdout.write(`Assigned: ${r.task.title}\n`);
+    process.stdout.write(`Assigned: ${sanitizeText(r.task.title, 80)}\n`);
     process.stdout.write(`  Now assignee: ${r.task.assignee_id || '(unassigned)'}\n`);
   } catch (e) {
     if (e.status === 403) die('Assignment requires a human actor (FLOW_ACTING_VIA=self or no claude header).');

package/bin/claim.mjs

@@ -3,7 +3,7 @@
    Usage: flow-claim <task_id>
 */
 
-import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, positional, arg, die, sanitizeText } from './_client.mjs';
 
 async function main() {
   const raw = positional(0);
@@ -36,13 +36,13 @@ async function main() {
     r = await flowFetch('/api/flow/claim', { method: 'POST', body });
   }
   if (!r?.task?.id) throw new Error('Server returned no task. Check your connection and try again.');
-  process.stdout.write(`Claimed #${r.task.issue_num ?? r.task.id.slice(0, 6)} — "${r.task.title}"\n`);
+  process.stdout.write(`Claimed #${r.task.issue_num ?? r.task.id.slice(0, 6)} — "${sanitizeText(r.task.title, 80)}"\n`);
 
   // Warn on file conflicts
   if (r.conflict_warnings?.length) {
     process.stdout.write(`\n⚠  File conflict${r.conflict_warnings.length === 1 ? '' : 's'} detected:\n`);
     for (const w of r.conflict_warnings) {
-      process.stdout.write(`  #${w.task_ref}  "${w.title}"  (${w.claimed_by || 'unassigned'})\n`);
+      process.stdout.write(`  #${w.task_ref}  "${sanitizeText(w.title, 60)}"  (${w.claimed_by || 'unassigned'})\n`);
       process.stdout.write(`    overlapping files: ${w.overlapping_files.join(', ')}\n`);
     }
     process.stdout.write('Consider coordinating before editing these files.\n\n');

package/bin/close.mjs

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 /* flow:close — mark a task done.
-   Usage: flow-close <task_id> [--summary="..."]
+   Usage: flow-close <task_id> "<summary>"   (--summary="..." also accepted)
 */
 
-import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, positional, arg, die, sanitizeText } from './_client.mjs';
 
 async function main() {
   const raw = positional(0);
-  if (!raw) die('Usage: flow-close <task_id> [--summary="..."]');
+  if (!raw) die('Usage: flow-close <task_id> "<summary>"');
   const id = await resolveTaskId(raw);
-  const summary = arg('summary');
+  const summary = positional(1) || arg('summary');
 
   const r = await flowFetch('/api/flow/close', {
     method: 'POST',
@@ -17,7 +17,7 @@ async function main() {
   });
 
   const ref = r.task.issue_num != null ? r.task.issue_num : r.task.id.slice(0, 6);
-  process.stdout.write(`Closed #${ref} — "${r.task.title}"\n`);
+  process.stdout.write(`Closed #${ref} — "${sanitizeText(r.task.title, 80)}"\n`);
 }
 
 main().catch(e => die(e.message || e));

package/bin/create.mjs

@@ -21,7 +21,7 @@
 */
 
 import 'dotenv/config';
-import { flowFetch, resolveTaskId, arg, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, arg, die, sanitizeText } from './_client.mjs';
 import { githubHeaders, fetchProjectItem, labelsToType } from './_github.mjs';
 
 async function fetchGithubIssue(issueNum) {
@@ -113,7 +113,7 @@ async function main() {
     const r = await flowFetch('/api/flow/tasks', { method: 'POST', body });
     const t = r.task || r;
     if (!t?.id) throw new Error('Server returned no task. Check your connection and try again.');
-    process.stdout.write(`Created #${t.id.slice(0, 6)} — "${t.title}"\n`);
+    process.stdout.write(`Created #${t.id.slice(0, 6)} — "${sanitizeText(t.title, 80)}"\n`);
     process.stdout.write(`  id:       ${t.id}\n`);
     process.stdout.write(`  status:   ${t.status}\n`);
     process.stdout.write(`  priority: ${t.priority}  type: ${t.type}  area: ${t.area}\n`);

package/bin/edit.mjs

@@ -8,7 +8,7 @@
      flow-edit <id> --blocked-by=<uuid>
 */
 
-import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, positional, arg, die, sanitizeText } from './_client.mjs';
 
 // B16: the server enum is P0-now / P1-soon / P2-later. Accept p0/p1/p2 (and any case of the
 // canonical form) so the documented shorthand isn't rejected; pass anything else through for
@@ -47,7 +47,7 @@ async function main() {
   const res = await flowFetch(`/api/flow/tasks/${id}`, { method: 'PATCH', body: changes });
 
   const updated = res.task || res;
-  const label = updated.title || id.slice(0, 8);
+  const label = sanitizeText(updated.title, 80) || id.slice(0, 8);
   process.stdout.write(`Updated: ${label}\n`);
   for (const [k, v] of Object.entries(changes)) {
     const display = v === null || (Array.isArray(v) && v.length === 0) ? '(cleared)' : v;

package/bin/flow.mjs

@@ -6,8 +6,7 @@
 
 import { spawnSync } from 'child_process';
 import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { CLI_COMMANDS } from './_commands.mjs';
 
 // Mirror the _client.mjs TLS re-spawn so the child sees --use-system-ca.
 // FLOW_TLS_RESPAWNED is a belt-and-suspenders guard against an infinite loop
@@ -24,42 +23,8 @@ if (process.platform === 'win32'
   process.exit(r.status ?? 1);
 }
 
-const __dir = dirname(fileURLToPath(import.meta.url));
-
-// ── Command registry ────────────────────────────────────────────────────────
-const CMDS = [
-  ['login',        'login.mjs',        'Authorize the CLI via browser (device flow)'],
-  ['pull',         'pull.mjs',         'Fetch board snapshot + @mentions (start of day)'],
-  ['claim',        'claim.mjs',        'Claim a task and mark it in-progress'],
-  ['comment',      'comment.mjs',      'Post a comment (--commit[=<sha>] links a clickable diff)'],
-  ['close',        'close.mjs',        'Mark a task done with a summary'],
-  ['create',       'create.mjs',       'Create a new task'],
-  ['edit',         'edit.mjs',         'Update task fields (title, priority, area, due…)'],
-  ['unblock',      'unblock.mjs',      'Clear a task\'s blocked-by dependency'],
-  ['propose',      'propose.mjs',      'Propose a sub-task for human approval'],
-  ['approve',      'approve.mjs',      'Approve a pending proposal'],
-  ['reject',       'reject.mjs',       'Reject a pending proposal with a reason'],
-  ['assign',       'assign.mjs',       'Assign a task to another actor'],
-  ['decisions',    'decisions.mjs',    'List pending proposals (--watch <id> blocks until resolved)'],
-  ['handoff',      'handoff.mjs',      'Hand off a task to another agent'],
-  ['review',       'review.mjs',       'Request code review; moves task to in-review'],
-  ['search',       'search.mjs',       'Search tasks by text, status, area, or assignee'],
-  ['status',       'status.mjs',       'Quick board summary'],
-  ['standup',      'standup.mjs',      'Done/in-progress digest; --velocity for trend chart'],
-  ['sync',         'sync.mjs',         'Delta sync since N minutes (default 60)'],
-  ['log',          'log.mjs',          'Tail recent timeline events'],
-  ['heartbeat',    'heartbeat.mjs',    'Send a presence ping (~60s while active)'],
-  ['ping',         'ping.mjs',         'Health check or send a direct agent message'],
-  ['pr',           'pr.mjs',           'Record a PR link on a task timeline'],
-  ['project',      'project.mjs',      'List GitHub Projects v2 items'],
-  ['archive',      'archive.mjs',      'Archive or unarchive a task (--undo to restore)'],
-  ['scan',         'scan.mjs',         'Audit for TODOs, untracked Issues, unlinked PRs, security patterns'],
-  ['close-sprint', 'close-sprint.mjs', 'Close a sprint milestone (owner only)'],
-  ['whoami',       'whoami.mjs',       'Verify token and show current identity'],
-  ['completion',   'completion.mjs',   'Print shell completion script (bash/zsh/fish)'],
-];
-
-const CMD_MAP = new Map(CMDS.map(([name, file]) => [name, file]));
+// ── Command registry (single source of truth: bin/_commands.mjs) ─────────────
+const CMD_MAP = new Map(CLI_COMMANDS.map((c) => [c.name, c.file]));
 
 // ── Help ────────────────────────────────────────────────────────────────────
 function printHelp() {
@@ -72,16 +37,16 @@ function printHelp() {
   process.stdout.write(`flow${version} — FlowCollab CLI\n\n`);
   process.stdout.write(`Usage: flow <command> [options]\n\n`);
   process.stdout.write(`Commands:\n`);
-  const pad = Math.max(...CMDS.map(([n]) => n.length)) + 2;
-  for (const [name, , desc] of CMDS) {
-    process.stdout.write(`  ${name.padEnd(pad)}${desc}\n`);
+  const pad = Math.max(...CLI_COMMANDS.map((c) => c.name.length)) + 2;
+  for (const { name, summary } of CLI_COMMANDS) {
+    process.stdout.write(`  ${name.padEnd(pad)}${summary}\n`);
   }
   process.stdout.write(`\nRun 'flow <command> --help' for command-specific flags.\n`);
   process.stdout.write(`Hyphenated aliases (flow-login, flow-pull, …) remain supported.\n`);
 }
 
 // ── Dispatch ────────────────────────────────────────────────────────────────
-const [, , sub, ...rest] = process.argv;
+const [, , sub] = process.argv;
 
 if (!sub || sub === '--help' || sub === '-h') {
   printHelp();

package/bin/log.mjs

@@ -6,17 +6,7 @@
      flow-log --limit=50             # more events
 */
 
-import { flowFetch, resolveTaskId, arg, die } from './_client.mjs';
-
-function sanitize(s) {
-  if (!s || typeof s !== 'string') return '';
-  return s
-    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
-    .replace(/@to:\S+/g, '[mention]')
-    .replace(/\r?\n|\r/g, ' ')
-    .trim()
-    .slice(0, 120);
-}
+import { flowFetch, resolveTaskId, arg, die, sanitizeText } from './_client.mjs';
 
 function fmt(ts) {
   if (!ts) return '         ';
@@ -29,8 +19,10 @@ function pad(s, n) { return String(s ?? '').padEnd(n).slice(0, n); }
 
 function fmtEvent(e) {
   const p = e.payload || {};
-  if (p.comment) return sanitize(p.comment);
-  if (p.act) return `[${p.act}${p.summary ? ': ' + sanitize(p.summary, 80) : ''}]`;
+  // Wrap untrusted comment bodies in the fence marker (sanitize BEFORE wrapping so a
+  // crafted comment can't inject a closing tag) — matches pull.mjs.
+  if (p.comment) return `<comment_from_untrusted_user>${sanitizeText(p.comment)}</comment_from_untrusted_user>`;
+  if (p.act) return `[${p.act}${p.summary ? ': ' + sanitizeText(p.summary, 80) : ''}]`;
   return `[${e.kind || 'event'}]`;
 }
 
@@ -53,7 +45,7 @@ async function main() {
 
     if (events.length === 0) { process.stdout.write('No timeline events.\n'); return; }
 
-    process.stdout.write(`Timeline for #${task.issue_num ?? id.slice(0, 6)}: ${task.title}\n\n`);
+    process.stdout.write(`Timeline for #${task.issue_num ?? id.slice(0, 6)}: ${sanitizeText(task.title, 120)}\n\n`);
     for (const e of events) {
       const who = e.acting_as_id ? `${e.acting_as_id}(${e.actor_id})` : (e.actor_id || '?');
       process.stdout.write(`  ${fmt(e.ts)}  ${pad(who, 18)}  ${fmtEvent(e)}\n`);

package/bin/project.mjs

@@ -10,7 +10,7 @@
 */
 
 import 'dotenv/config';
-import { die } from './_client.mjs';
+import { die, sanitizeText } from './_client.mjs';
 import { fetchProjectItems, contentKind } from './_github.mjs';
 
 async function main() {
@@ -30,7 +30,7 @@ async function main() {
 
   const { title, items } = await fetchProjectItems(projectId);
 
-  process.stdout.write(`Project: ${title}\n`);
+  process.stdout.write(`Project: ${sanitizeText(title, 100)}\n`);
   process.stdout.write(`  ${items.length} item${items.length !== 1 ? 's' : ''}\n\n`);
 
   if (!items.length) {
@@ -41,7 +41,7 @@ async function main() {
   for (const { id, content } of items) {
     const kind = contentKind(content);
     const num = content.number ? ` #${content.number}` : '';
-    process.stdout.write(`  [${id}]  ${content.title}${num ? ` (${kind}${num})` : ` (${kind})`}\n`);
+    process.stdout.write(`  [${id}]  ${sanitizeText(content.title, 80)}${num ? ` (${kind}${num})` : ` (${kind})`}\n`);
   }
 
   process.stdout.write(`\nTo import an item:\n  flow-create --from-project-item=<id above>\n`);

package/bin/propose.mjs

@@ -19,7 +19,7 @@
    - Dedup on title (HTTP 409)
 */
 
-import { flowFetch, resolveTaskId, arg, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, arg, die, sanitizeText } from './_client.mjs';
 
 async function main() {
   const parent = arg('parent') ? await resolveTaskId(arg('parent')) : null;
@@ -42,7 +42,7 @@ async function main() {
   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(`  Title: ${sanitizeText(r.decision.proposal_title, 100)}\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');

package/bin/pull.mjs

@@ -45,14 +45,14 @@ 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 miTag = t.milestone ? ` [${sanitizeText(t.milestone, 40)}]` : '';
   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,
+    sanitizeText(t.title, 100) + miTag + prTag,
   ];
   return parts.join('  ');
 }

package/bin/reject.mjs

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 /* flow:reject — reject a pending decision.
-   Usage: flow-reject <decision_id> [--reason="..."]
+   Usage: flow-reject <decision_id> "<reason>"   (--reason="..." also accepted)
 */
 
 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="..."]');
+  if (!raw) die('Usage: flow-reject <decision_id> "<reason>"');
   const id = await resolveTaskId(raw);
-  const reason = arg('reason');
+  const reason = positional(1) || arg('reason');
   await flowFetch(`/api/flow/decisions/${id}/reject`, {
     method: 'POST', body: reason ? { reason } : {},
   });

package/bin/scan.mjs

@@ -10,7 +10,7 @@
 */
 
 import 'dotenv/config';
-import { flowFetch, arg, die } from './_client.mjs';
+import { flowFetch, arg, die, sanitizeText } from './_client.mjs';
 import { githubHeaders } from './_github.mjs';
 import { readFileSync, readdirSync } from 'node:fs';
 import { join, extname, relative } from 'node:path';
@@ -123,7 +123,7 @@ async function scanIssues(repo) {
     const labels = (i.labels || []).map(l => l.name.toLowerCase());
     const type = labels.includes('bug') ? 'bug' : labels.includes('documentation') ? 'docs' : 'feature';
     return {
-      label: `GitHub Issue #${i.number}: ${i.title}`,
+      label: `GitHub Issue #${i.number}: ${sanitizeText(i.title, 80)}`,
       detail: `  ${i.html_url}`,
       cmd: `flow-create --from-issue=${i.number} --type=${type}`,
     };
@@ -150,9 +150,9 @@ async function scanPRs(repo) {
   const trackedPRs = new Set(allTasks.filter(t => t.pr_num).map(t => t.pr_num));
   const unlinked = ghPRs.filter(pr => !trackedPRs.has(pr.number));
   return unlinked.slice(0, 10).map(pr => {
-    const title = pr.title.replace(/"/g, '\\"').slice(0, 55);
+    const title = sanitizeText(pr.title, 55).replace(/"/g, '\\"');
     return {
-      label: `Unlinked PR #${pr.number}: ${pr.title}`,
+      label: `Unlinked PR #${pr.number}: ${sanitizeText(pr.title, 80)}`,
       detail: `  ${pr.html_url}  (${pr.draft ? 'draft' : 'open'})`,
       cmd: `flow-create --title="Track PR #${pr.number}: ${title}" --type=chore --area=backend`,
     };

package/bin/search.mjs

@@ -6,7 +6,7 @@
      flow-search "ui" --area=frontend --assignee=nate
 */
 
-import { flowFetch, arg, positional } from './_client.mjs';
+import { flowFetch, arg, positional, sanitizeText } from './_client.mjs';
 
 function pad(s, n) { return String(s).padEnd(n).slice(0, n); }
 
@@ -40,7 +40,7 @@ async function main() {
     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`
+      `${pad(ref, 8)}  ${pad(t.status, 12)}  ${pad(t.priority || '-', 9)}  ${pad(t.assignee_id || '-', 14)}  ${sanitizeText(t.title, 60)}${due}\n`
     );
   }
 }

package/bin/status.mjs

@@ -3,7 +3,7 @@
    Usage: flow-status
 */
 
-import { flowFetch } from './_client.mjs';
+import { flowFetch, sanitizeText } from './_client.mjs';
 
 function pad(s, n) { return String(s).padEnd(n).slice(0, n); }
 
@@ -53,7 +53,7 @@ async function main() {
       for (const t of arr) {
         const stale = t.updated_at && (now - new Date(t.updated_at).getTime()) > STALE_HOURS * 3600000;
         const staleMark = stale ? '  ⚠ STALE' : '';
-        out.push(`    #${t.issue_num ?? t.id.slice(0, 6)}  ${pad(t.assignee_id || 'unassigned', 14)}  ${t.title.slice(0, 50)}${staleMark}`);
+        out.push(`    #${t.issue_num ?? t.id.slice(0, 6)}  ${pad(t.assignee_id || 'unassigned', 14)}  ${sanitizeText(t.title, 50)}${staleMark}`);
       }
     }
   }
@@ -74,7 +74,7 @@ async function main() {
       const heartbeatTask = a.task_id ? taskById.get(a.task_id) : null;
       const displayTask = heartbeatTask || myTasks[0];
       const taskPart = displayTask
-        ? `#${displayTask.issue_num ?? displayTask.id.slice(0, 6)} "${displayTask.title.slice(0, 38)}"`
+        ? `#${displayTask.issue_num ?? displayTask.id.slice(0, 6)} "${sanitizeText(displayTask.title, 38)}"`
         : 'idle';
       const extraCount = myTasks.length > 1 ? ` +${myTasks.length - 1} more` : '';
       out.push(`  ${pad(a.actor_id, 16)}  ${taskPart}${extraCount}  (${relAgo(a.last_seen_at)})`);
@@ -91,7 +91,7 @@ async function main() {
   out.push(`[decisions]  ${decisions.length} pending`);
   if (decisions.length) {
     for (const d of decisions.slice(0, 5)) {
-      out.push(`  #${d.id.slice(0, 6)}  [${d.confidence}]  ${d.proposal_title.slice(0, 65)}`);
+      out.push(`  #${d.id.slice(0, 6)}  [${d.confidence}]  ${sanitizeText(d.proposal_title, 65)}`);
     }
     if (decisions.length > 5) out.push(`  … and ${decisions.length - 5} more`);
   }

package/bin/unblock.mjs

@@ -3,7 +3,7 @@
    Usage: flow-unblock <task_id>
 */
 
-import { flowFetch, resolveTaskId, positional, die } from './_client.mjs';
+import { flowFetch, resolveTaskId, positional, die, sanitizeText } from './_client.mjs';
 
 async function main() {
   const raw = positional(0);
@@ -12,7 +12,7 @@ async function main() {
   const id = await resolveTaskId(raw);
   const res = await flowFetch(`/api/flow/tasks/${id}`, { method: 'PATCH', body: { blocked_by: [] } });
 
-  const title = res.task?.title || id.slice(0, 8);
+  const title = sanitizeText(res.task?.title, 80) || id.slice(0, 8);
   process.stdout.write(`Unblocked: ${title}\n`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowcollab",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "Multi-Claude coordination layer — shared task board + CLI for teams running Claude Code",
   "type": "module",
   "files": [