@commonlyai/cli 0.1.214 → 0.1.216

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.214",
+  "version": "0.1.216",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/task.js

@@ -0,0 +1,278 @@
+/**
+ * commonly task <subcommand>
+ *
+ * list   — the pod's board, optionally narrowed by status, or to rows this identity holds
+ * create — a new row; --notes is a second request, because create does not take notes
+ * claim  — take the lease on a row
+ * update — change a row's fields, and/or append a history note
+ * close  — mark a row done, as its creator or its holder
+ *
+ * Identity and base URL come from ../lib/task.js. Every subcommand goes through
+ * connect() below, so none can grow its own fallback to the saved login. Flags are
+ * checked before the first request, so a refusal costs no network round trip.
+ */
+
+import { TOKEN_FILE_ENV } from '../lib/inbox.js';
+import {
+  TASK_PRIORITIES,
+  TASK_STATUSES,
+  TASK_TOKEN_ENV,
+  TaskRefusal,
+  UPDATE_STATUSES,
+  checkPriority,
+  checkStatusFilter,
+  checkTaskId,
+  checkUpdateStatus,
+  createTaskClient,
+  describeFailure,
+  formatTaskLine,
+  requireText,
+  resolveTaskBaseUrl,
+  resolveTaskToken,
+  taskPath,
+} from '../lib/task.js';
+
+export const TASK_TOKEN_HELP = `Agent token file (or ${TOKEN_FILE_ENV}, or ${TASK_TOKEN_ENV})`;
+
+const connect = (opts, env, fetchImpl) => createTaskClient({
+  baseUrl: resolveTaskBaseUrl(opts, env),
+  token: resolveTaskToken(opts, env),
+  fetchImpl,
+});
+
+const podOf = (opts) => requireText(opts.pod, '--pod');
+
+const report = (err, error) => {
+  error(err instanceof TaskRefusal ? `refusing: ${err.message}` : describeFailure(err));
+  return 1;
+};
+
+// A row goes out as JSON for agents, and as the line a person scans otherwise.
+const emitRow = (opts, log, task) => {
+  log(opts.json ? JSON.stringify(task, null, 2) : formatTaskLine(task));
+};
+
+export const runTaskList = async (opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const status = opts.status === undefined ? undefined : checkStatusFilter(opts.status);
+    const { tasks } = await connect(opts, env, fetchImpl).get(taskPath(pod), { status });
+    // The server marks each row claimedByMe for this identity, so --mine needs no second request.
+    const rows = opts.mine ? tasks.filter((task) => task.claimedByMe) : tasks;
+    if (opts.json) {
+      log(JSON.stringify(rows, null, 2));
+    } else if (rows.length === 0) {
+      log('(no tasks match)');
+    } else {
+      for (const task of rows) log(formatTaskLine(task));
+    }
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskCreate = async (opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const body = { title: requireText(opts.title, '--title') };
+    if (opts.priority !== undefined) body.priority = checkPriority(opts.priority);
+    if (opts.assignee !== undefined) body.assignee = requireText(opts.assignee, '--assignee');
+    if (opts.dep !== undefined) body.dep = checkTaskId(opts.dep);
+    const notes = opts.notes === undefined ? undefined : requireText(opts.notes, '--notes');
+    const client = connect(opts, env, fetchImpl);
+    const { task } = await client.post(taskPath(pod), body);
+    if (notes === undefined) {
+      emitRow(opts, log, task);
+      return 0;
+    }
+    // The row exists once the create returns. If the notes fail, say so, so nobody
+    // retries the create and makes a twin.
+    try {
+      const { task: noted } = await client.patch(taskPath(pod, task.taskId), { notes });
+      emitRow(opts, log, noted);
+      return 0;
+    } catch (err) {
+      error(`Created ${task.taskId}, but --notes did not save. ${describeFailure(err)}`);
+      return 1;
+    }
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskClaim = async (taskArg, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const taskId = checkTaskId(taskArg);
+    const body = opts.continueAnyway ? { continueAnyway: true } : {};
+    const { task } = await connect(opts, env, fetchImpl).post(`${taskPath(pod, taskId)}/claim`, body);
+    emitRow(opts, log, task);
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskUpdate = async (taskArg, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const taskId = checkTaskId(taskArg);
+    const fields = {};
+    if (opts.status !== undefined) fields.status = checkUpdateStatus(opts.status);
+    // An empty value unassigns. The server stores that as null, not as '', so the row
+    // reads as unassigned to the router.
+    if (opts.assignee !== undefined) fields.assignee = String(opts.assignee).trim();
+    if (opts.title !== undefined) fields.title = requireText(opts.title, '--title');
+    if (opts.priority !== undefined) fields.priority = checkPriority(opts.priority);
+    // "none" clears the dependency. Sending '' would store a dependency that names nothing.
+    if (opts.dep !== undefined) fields.dep = opts.dep === 'none' ? null : checkTaskId(opts.dep);
+    const note = opts.note === undefined ? undefined : requireText(opts.note, '--note');
+    if (Object.keys(fields).length === 0 && note === undefined) {
+      throw new TaskRefusal('nothing to change. Pass --status, --assignee, --title, --priority, --dep or --note.');
+    }
+    const client = connect(opts, env, fetchImpl);
+    const path = taskPath(pod, taskId);
+    let task = null;
+    if (Object.keys(fields).length > 0) ({ task } = await client.patch(path, fields));
+    if (note !== undefined) {
+      try {
+        const body = opts.continueAnyway ? { text: note, continueAnyway: true } : { text: note };
+        ({ task } = await client.post(`${path}/updates`, body));
+      } catch (err) {
+        // With no field change before it, a failed note is the whole failure.
+        if (task === null) throw err;
+        error(`Updated ${taskId}, but --note did not post. ${describeFailure(err)}`);
+        return 1;
+      }
+    }
+    emitRow(opts, log, task);
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskClose = async (taskArg, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const taskId = checkTaskId(taskArg);
+    const prUrl = opts.pr === undefined ? undefined : requireText(opts.pr, '--pr');
+    // No notes key here. /complete replaces the row's notes whenever one is sent.
+    const body = prUrl === undefined ? {} : { prUrl };
+    const { task } = await connect(opts, env, fetchImpl).post(`${taskPath(pod, taskId)}/complete`, body);
+    emitRow(opts, log, task);
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const registerTask = (program) => {
+  const task = program
+    .command('task')
+    .description('Read and write the task board as an agent (list, create, claim, update, close)');
+
+  task.addHelpText('after', `
+The board is read and written as the identity in a token file, and nowhere else:
+
+  $ commonly task list --pod <podId> --token-file <path>
+  $ COMMONLY_AGENT_TOKEN=<token> commonly task claim TASK-123 --pod <podId>
+
+The identity is --token-file, then COMMONLY_TOKEN_FILE, then COMMONLY_AGENT_TOKEN.
+The saved login and COMMONLY_TOKEN are never read: a write made under an
+operator's login lands on the row under that operator's name.
+
+Each verb does what it says. \`claim\` takes the lease. \`close\` stamps the
+completion time and the PR. \`update --status\` sets only pending or blocked, so it
+cannot claim or close a row. \`update --note\` appends a history line. The row's
+notes are set by \`create --notes\` and are not editable here.
+
+A claim or a note can refuse with unseen messages in the pod. Read them and retry,
+or pass --continue-anyway to go ahead without reading them.
+
+Examples:
+  $ commonly task list --pod <podId> --status pending,claimed
+  $ commonly task list --pod <podId> --mine --json
+  $ commonly task create --pod <podId> --title "Fix the board" --priority P1 --notes "Repro in staging"
+  $ commonly task claim TASK-123 --pod <podId>
+  $ commonly task update TASK-123 --pod <podId> --note "PR is up"
+  $ commonly task close TASK-123 --pod <podId> --pr https://github.com/Team-Commonly/commonly/pull/<n>
+`);
+
+  task
+    .command('list')
+    .description("List a pod's task board")
+    .requiredOption('--pod <podId>', 'Pod whose board to read')
+    .option('--status <list>', `Only these statuses, comma-separated (${TASK_STATUSES.join('|')})`)
+    .option('--mine', 'Only rows this identity holds a claim on')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the rows as JSON')
+    .action(async (opts) => { process.exit(await runTaskList(opts)); });
+
+  task
+    .command('create')
+    .description('Create a row, then set its --notes (create does not take notes)')
+    .requiredOption('--pod <podId>', 'Pod to create the row in')
+    .requiredOption('--title <text>', 'Row title')
+    .option('--notes <text>', 'Notes to set once the row exists')
+    .option('--priority <P>', `${TASK_PRIORITIES.join('|')} (default P2)`)
+    .option('--assignee <name>', 'Assign the row at creation')
+    .option('--dep <TASK-n>', 'Row this one waits on')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (opts) => { process.exit(await runTaskCreate(opts)); });
+
+  task
+    .command('claim <taskId>')
+    .description('Take the lease on a row (TASK-n)')
+    .requiredOption('--pod <podId>', 'Pod the row is in')
+    .option('--continue-anyway', 'Claim even with unseen messages in the pod')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (taskId, opts) => { process.exit(await runTaskClaim(taskId, opts)); });
+
+  task
+    .command('update <taskId>')
+    .description("Change a row's fields, and/or append a history note")
+    .requiredOption('--pod <podId>', 'Pod the row is in')
+    .option('--status <status>', `${UPDATE_STATUSES.join('|')} (claim and close have their own commands)`)
+    .option('--assignee <name>', 'Reassign the row; an empty value unassigns it')
+    .option('--title <text>', 'New title')
+    .option('--priority <P>', TASK_PRIORITIES.join('|'))
+    .option('--dep <TASK-n>', 'Row this one waits on; "none" clears it')
+    .option('--note <text>', 'Append a history note')
+    .option('--continue-anyway', 'Post the note even with unseen messages in the pod')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (taskId, opts) => { process.exit(await runTaskUpdate(taskId, opts)); });
+
+  task
+    .command('close <taskId>')
+    .description('Mark a row done, as its creator or its holder')
+    .requiredOption('--pod <podId>', 'Pod the row is in')
+    .option('--pr <url>', 'Pull request that delivered the row')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (taskId, opts) => { process.exit(await runTaskClose(taskId, opts)); });
+};

package/src/index.js

@@ -23,6 +23,7 @@ import { registerDev } from './commands/dev.js';
 import { registerVerify } from './commands/verify.js';
 import { registerDoctor } from './commands/doctor.js';
 import { registerMcp } from './commands/mcp.js';
+import { registerTask } from './commands/task.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
@@ -60,6 +61,9 @@ registerVerify(program);
 registerDoctor(program);
 registerMcp(program);
 
+// The task board as an agent: list, create, claim, update, close (TASK-703)
+registerTask(program);
+
 // Each subcommand owns its own `--instance <url>` flag; a program-level
 // duplicate shadowed the subcommand value on commander v12, causing
 // `commonly login --instance …` to silently fall back to the default URL.

package/src/lib/adapters/claude.js

@@ -494,10 +494,65 @@ const publicSkillPromptArgs = async (skillSources) => {
 
 // `ownGroup` is set only under the run supervisor, which kills the child's
 // whole group; unsupervised, the spawn options are exactly what they were.
+// Stream-json so each model event is a sign of life for the watchdog. The
+// partial messages put thinking deltas on the stream too, so a long think is
+// visible while it runs. A hung provider writes only `system` retry events,
+// and the watchdog does not count those.
+const STREAM_ARGS = ['--output-format', 'stream-json', '--verbose', '--include-partial-messages'];
+
+const parseEvent = (line) => {
+  try {
+    const event = JSON.parse(line);
+    return event && typeof event === 'object' ? event : null;
+  } catch {
+    return null;
+  }
+};
+
+// The reply is the `result` event's text. A turn that reaches no result event
+// (killed mid-stream, exit 0) gets the text of its assistant events, never the
+// raw NDJSON. Output with no JSON lines at all is plain text and returned as it
+// arrived. A result flagged `is_error` is a failed turn, whatever its exit code,
+// so it is raised here, outside the parse guard, and never returned as a reply.
+export const claudeResultText = (stdout, { credentials = [] } = {}) => {
+  const text = String(stdout || '');
+  const events = text.split('\n').map(parseEvent);
+  if (!events.some(Boolean)) return text.trim();
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    if (events[i]?.type !== 'result') continue;
+    const reply = String(events[i].result ?? '').trim();
+    if (events[i].is_error === true) throw adapterFailure('claude', reply, { credentials });
+    return reply;
+  }
+  return events
+    .filter((event) => event?.type === 'assistant')
+    .flatMap((event) => event.message?.content || [])
+    .filter((block) => block?.type === 'text')
+    .map((block) => block.text)
+    .join('')
+    .trim();
+};
+
+// The failure tail for a non-zero exit. Stream events are mostly system init
+// and status lines, which would push the terminal error past the 2000-char cut,
+// so keep the result text, or the lines that are not system or stream events.
+export const claudeFailureTail = (stdout) => {
+  const text = String(stdout || '');
+  const lines = text.split('\n');
+  const events = lines.map(parseEvent);
+  if (!events.some(Boolean)) return text.trim();
+  const result = [...events].reverse().find((event) => event?.type === 'result');
+  if (String(result?.result ?? '').trim()) return String(result.result).trim();
+  return lines
+    .filter((_, i) => !['system', 'stream_event'].includes(events[i]?.type))
+    .join('\n')
+    .trim();
+};
+
 const runClaude = ({
   cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false,
   transcriptPath = null, firstOutputMs = firstOutputWindowMs(), lockProbe, stallKillGraceMs = STALL_KILL_GRACE_MS,
-  processTable = readProcessTable, survivorIo,
+  processTable = readProcessTable, survivorIo, modelStream = true,
 }) => new Promise((resolve, reject) => {
   const proc = spawnInOwnGroup(spawnImpl, cmd, args, {
     cwd,
@@ -529,6 +584,7 @@ const runClaude = ({
     proc,
     windowMs: firstOutputMs,
     transcriptPath,
+    modelStream,
     lockProbe,
     onStall: (reason) => {
       stalled = spawnStalledError({ label: 'claude', windowMs: firstOutputMs, reason });
@@ -584,7 +640,7 @@ const runClaude = ({
       // reduced to one named field. The status, when the tail names one, is
       // attached as `error.status` so a refusal classifies by field rather than
       // by regex.
-      const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join(' | ');
+      const detail = [stderr.trim(), claudeFailureTail(stdout)].filter(Boolean).join(' | ');
       return reject(adapterFailure('claude', detail, {
         credentials,
         exitCode: code,
@@ -1161,7 +1217,7 @@ export default {
       ...(seatModel ? ['--model', seatModel] : []),
       ...(ctx.environment?.effort ? ['--effort', String(ctx.environment.effort)] : []),
     ];
-    const baseArgs = ['-p', fullPrompt, '--output-format', 'text', sessionFlag, sessionId, ...modelArgs];
+    const baseArgs = ['-p', fullPrompt, ...STREAM_ARGS, sessionFlag, sessionId, ...modelArgs];
 
     let mountedSkills = [];
     let skillMount = { mounted: [], conflicted: [] };
@@ -1274,7 +1330,7 @@ export default {
       const contextTokens = claudeContextTokens({
         cwd: physicalPath(ctx.cwd), sessionId, configDir: claudeConfigDirFor({ ...env, HOME: childHome || env?.HOME }),
       });
-      return { text: stdout.trim(), newSessionId: sessionId, contextTokens };
+      return { text: claudeResultText(stdout, { credentials: spawnCredentials(spawnCtx) }), newSessionId: sessionId, contextTokens };
     } catch (err) {
       // A public seat's refusal is not a session-store failure, whatever its
       // message happens to contain: it must reach the run loop, never the
@@ -1295,7 +1351,7 @@ export default {
           memoryWithheld: ctx.memoryWithheld === true,
         });
         const retryBase = ['-p', freshPrompt,
-        '--output-format', 'text', '--session-id', freshId, ...modelArgs];
+        ...STREAM_ARGS, '--session-id', freshId, ...modelArgs];
         const retryCtx = {
           ...ctx,
           mcpConfigPath: mcpConfig?.file || null,
@@ -1337,7 +1393,7 @@ export default {
           cwd: physicalPath(ctx.cwd), sessionId: freshId,
           configDir: claudeConfigDirFor({ ...retry.env, HOME: retry.childHome || retry.env?.HOME }),
         });
-        return { text: stdout.trim(), newSessionId: freshId, contextTokens };
+        return { text: claudeResultText(stdout, { credentials: spawnCredentials(retryCtx) }), newSessionId: freshId, contextTokens };
       }
       throw err;
     } finally {

package/src/lib/first-output-watchdog.js

@@ -16,6 +16,9 @@
  * A spawn that does neither inside the window is killed with a reason. When
  * the transcript is missing altogether, the path may simply be wrong, so the
  * spawn is killed only if the console is also locked.
+ *
+ * That is the rule for a plain-text spawn. A stream-json spawn (TASK-710) counts
+ * only model events on stdout; see `modelStream` on watchFirstOutput.
  */
 import { realpathSync, statSync } from 'fs';
 import { readProcess } from '@commonlyai/seats/process-group';
@@ -99,15 +102,35 @@ const sizeOf = (file) => {
   }
 };
 
+// A stream-json line is model progress when it is an event other than `system`.
+// The `system` events are `init` (written before any model call) and
+// `api_retry` (a provider failing and retrying). Counting either would keep a
+// hung provider looking alive until the run timeout.
+export const isModelProgressLine = (line) => {
+  try {
+    const event = JSON.parse(line);
+    return !!event && typeof event === 'object' && event.type !== 'system';
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Watch `proc` for its first sign of life. Returns `{ stop }`; call it when the
  * process closes. `onStall(reason)` fires at most once, after the caller should
  * kill the process.
+ *
+ * With `modelStream`, the spawn writes stream-json events. Only model output
+ * counts as life there. A transcript row does not, because claude writes its
+ * first row about a second after spawn, before any model reply. Stderr does
+ * not either: claude prints warnings at spawn (an unrecognised model, a
+ * connector notice) whatever the provider does next.
  */
 export const watchFirstOutput = ({
   proc,
   windowMs,
   transcriptPath = null,
+  modelStream = false,
   onStall,
   lockProbe = consoleLocked,
   setTimeoutImpl = setTimeout,
@@ -116,16 +139,32 @@ export const watchFirstOutput = ({
   if (!windowMs) return { stop: () => {} };
   let started = false;
   let stopped = false;
+  let partial = '';
   const markStarted = () => { started = true; };
-  proc.stdout?.on('data', markStarted);
-  proc.stderr?.on('data', markStarted);
+  if (modelStream) {
+    proc.stdout?.on('data', (chunk) => {
+      const lines = (partial + chunk.toString()).split('\n');
+      partial = lines.pop();
+      if (lines.some(isModelProgressLine)) markStarted();
+    });
+  } else {
+    proc.stdout?.on('data', markStarted);
+    proc.stderr?.on('data', markStarted);
+  }
   // A missing file counts as empty, so creating an empty one is not growth.
   const baseline = Math.max(0, sizeOf(transcriptPath));
   const timer = setTimeoutImpl(async () => {
     const size = sizeOf(transcriptPath);
-    if (started || size > baseline) return;
+    if (started || (!modelStream && size > baseline)) return;
     const locked = await lockProbe().catch(() => null);
-    if (stopped) return;
+    // Output can arrive while the probe runs (ps or ioreg may take a second).
+    if (stopped || started) return;
+    if (modelStream) {
+      // The model signal does not read the transcript, so a missing path cannot
+      // hide a hung provider here.
+      onStall(locked ? 'console locked' : 'stuck: no model output inside the window');
+      return;
+    }
     // No transcript where one was expected may only mean the path is wrong, so
     // that alone never kills a turn: it takes a locked console as well.
     if (size < 0 && locked !== true) return;

package/src/lib/task.js

@@ -0,0 +1,234 @@
+/**
+ * The task board from the CLI: identity, the request layer, and one-line
+ * rendering. The routes are the ones the commonly_* task tools call
+ * (backend/routes/tasksApi.ts), so the CLI and the MCP cannot disagree about
+ * what a write means.
+ *
+ * Identity is an explicit token and nothing else: --token-file, then
+ * COMMONLY_TOKEN_FILE, then COMMONLY_AGENT_TOKEN. The saved login and
+ * COMMONLY_TOKEN are never read. A write made under an operator's saved login
+ * lands on the row under that operator's name.
+ */
+
+import { readFileSync } from 'fs';
+import { DEFAULT_URL, resolveInstance } from './config.js';
+import { extractToken, resolveTokenFilePath, TOKEN_FILE_ENV } from './inbox.js';
+
+export const API_URL_ENV = 'COMMONLY_API_URL';
+export const TASK_TOKEN_ENV = 'COMMONLY_AGENT_TOKEN';
+export const TASK_STATUSES = ['pending', 'claimed', 'done', 'blocked'];
+// `update` writes only these. A claim writes the lease, which /claim owns, and a
+// close stamps completedAt and the PR, which PATCH does not.
+export const UPDATE_STATUSES = ['pending', 'blocked'];
+export const TASK_PRIORITIES = ['P0', 'P1', 'P2', 'P3'];
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** A refusal made before any request: a bad flag, or no identity to send. */
+export class TaskRefusal extends Error {}
+
+/** A failed call. `status` is 0 when the server was never reached. */
+export class TaskRequestError extends Error {
+  constructor(message, { status = 0, code = null, body = null } = {}) {
+    super(message);
+    this.name = 'TaskRequestError';
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+}
+
+export const requireText = (value, flag) => {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) throw new TaskRefusal(`${flag} needs a value.`);
+  return text;
+};
+
+export const checkPriority = (value) => {
+  const priority = String(value).trim().toUpperCase();
+  if (!TASK_PRIORITIES.includes(priority)) {
+    throw new TaskRefusal(`--priority must be ${TASK_PRIORITIES.join(', ')} (got '${value}').`);
+  }
+  return priority;
+};
+
+export const checkStatusFilter = (value) => {
+  const statuses = String(value).split(',').map((s) => s.trim()).filter(Boolean);
+  if (statuses.length === 0 || statuses.some((s) => !TASK_STATUSES.includes(s))) {
+    throw new TaskRefusal(`--status takes ${TASK_STATUSES.join(', ')}, comma-separated (got '${value}').`);
+  }
+  return statuses.join(',');
+};
+
+export const checkUpdateStatus = (value) => {
+  const status = String(value).trim().toLowerCase();
+  if (status === 'claimed') {
+    throw new TaskRefusal('--status claimed is refused: `commonly task claim` writes the lease, and a bare status does not.');
+  }
+  if (status === 'done') {
+    throw new TaskRefusal('--status done is refused: `commonly task close` stamps completedAt and the PR, and PATCH does not.');
+  }
+  if (!UPDATE_STATUSES.includes(status)) {
+    throw new TaskRefusal(`--status must be ${UPDATE_STATUSES.join(' or ')} (got '${value}').`);
+  }
+  return status;
+};
+
+/** TASK-669, task-669 and 669 name one row. Anything else is refused before a request. */
+export const checkTaskId = (value) => {
+  const match = String(value ?? '').trim().match(/^(?:task-)?(\d+)$/i);
+  if (!match) throw new TaskRefusal(`task id must look like TASK-123 (got '${value ?? ''}').`);
+  return `TASK-${String(Number(match[1])).padStart(3, '0')}`;
+};
+
+/**
+ * Resolve the token. A token file that exists but holds nothing is refused by
+ * its path. The message never suggests `commonly login`, because pointing back
+ * at the saved login is the thing this rule exists to prevent.
+ */
+export const resolveTaskToken = (opts = {}, env = process.env) => {
+  const tokenFile = resolveTokenFilePath(opts, env);
+  if (tokenFile) {
+    let raw;
+    try {
+      raw = readFileSync(tokenFile, 'utf8');
+    } catch (err) {
+      throw new TaskRefusal(`cannot read the token file ${tokenFile} (${err?.code || err?.message}).`);
+    }
+    const token = extractToken(raw);
+    if (!token) throw new TaskRefusal(`no token in ${tokenFile}. Expected a raw token, or JSON with a token field.`);
+    return token;
+  }
+  const fromEnv = extractToken(env[TASK_TOKEN_ENV]);
+  if (fromEnv) return fromEnv;
+  throw new TaskRefusal(`no token. Pass --token-file <path>, or set ${TOKEN_FILE_ENV} or ${TASK_TOKEN_ENV}.`);
+};
+
+/**
+ * --instance takes a URL or a saved key, and an unknown key is refused. Falling
+ * back to the default host would send this token to an instance it was not
+ * minted on.
+ */
+export const resolveTaskBaseUrl = (opts = {}, env = process.env) => {
+  if (opts.instance) {
+    const inst = resolveInstance(opts.instance);
+    if (!inst?.url) {
+      throw new TaskRefusal(`unknown instance '${opts.instance}'. Pass its URL, or a saved instance key.`);
+    }
+    return inst.url.replace(/\/$/, '');
+  }
+  const fromEnv = String(env[API_URL_ENV] || '').trim().replace(/\/$/, '');
+  return fromEnv || DEFAULT_URL;
+};
+
+/** `/api/v1/tasks/<pod>` for the board, and `…/<taskId>` for one row. */
+export const taskPath = (podId, taskId = null) => [
+  '/api/v1/tasks',
+  encodeURIComponent(podId),
+  ...(taskId === null ? [] : [encodeURIComponent(taskId)]),
+].join('/');
+
+const messageFor = (status, body, text) => {
+  if (body && typeof body.error === 'string' && body.error) return body.error;
+  if (body && typeof body.message === 'string' && body.message) return body.message;
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return `HTTP ${status}`;
+  if (/^<(?:!doctype|html)/i.test(trimmed)) {
+    const title = trimmed.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1];
+    return title ? title.replace(/\s+/g, ' ').trim() : 'HTML error page';
+  }
+  return trimmed.replace(/\s+/g, ' ').slice(0, 200);
+};
+
+/**
+ * One attempt per call. The writes here are POSTs, and a retried create or note
+ * lands twice, so a failure is reported and the caller decides what to do next.
+ */
+export const createTaskClient = ({ baseUrl, token, fetchImpl = fetch }) => {
+  const send = async (method, path, body) => {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (err) {
+      throw new TaskRequestError(`could not reach ${baseUrl} (${err?.message || err}).`);
+    }
+    const text = await res.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      parsed = null;
+    }
+    if (!res.ok) {
+      throw new TaskRequestError(messageFor(res.status, parsed, text), {
+        status: res.status,
+        code: parsed?.code || null,
+        body: parsed,
+      });
+    }
+    return parsed;
+  };
+
+  const get = (path, params = {}) => {
+    const query = new URLSearchParams(
+      Object.entries(params).filter(([, value]) => value !== undefined && value !== ''),
+    ).toString();
+    return send('GET', query ? `${path}?${query}` : path);
+  };
+
+  return {
+    get,
+    post: (path, body = {}) => send('POST', path, body),
+    patch: (path, body = {}) => send('PATCH', path, body),
+  };
+};
+
+const clockOf = (iso) => {
+  if (!iso) return null;
+  const at = new Date(iso);
+  return Number.isNaN(at.getTime()) ? null : `${at.toISOString().slice(11, 16)}Z`;
+};
+
+/** One row, as a human reads it. A claimed row also says whether its lease holds. */
+export const formatTaskLine = (task) => {
+  const line = [task.taskId, task.status, task.priority || '-', task.assignee || '-', task.title].join('  ');
+  if (task.status !== 'claimed') return line;
+  const at = clockOf(task.claimExpiresAt);
+  if (!at) return line;
+  const lapsed = new Date(task.claimExpiresAt).getTime() < Date.now();
+  return `${line} (${lapsed ? 'lease lapsed' : 'held until'} ${at})`;
+};
+
+/**
+ * One line for a failed call. The unseen-messages hold and a lease conflict get
+ * their own wording, because a seat acts on each differently. Everything else is
+ * the server's own text.
+ */
+export const describeFailure = (err) => {
+  if (!(err instanceof TaskRequestError)) return `Failed: ${err?.message || err}`;
+  if (err.status === 0) return `Failed: ${err.message}`;
+  const body = err.body || {};
+  let line;
+  if (err.code === 'unseen_messages') {
+    const count = Number(body.unseenCount) || 0;
+    line = `Failed (HTTP ${err.status}): ${count} unseen message${count === 1 ? '' : 's'} in this pod. `
+      + 'Read them and retry, or pass --continue-anyway to go ahead.';
+  } else {
+    const detail = [
+      body.claimedBy ? `held by ${body.claimedBy}` : null,
+      clockOf(body.claimExpiresAt) ? `lease until ${clockOf(body.claimExpiresAt)}` : null,
+    ].filter(Boolean).join(', ');
+    line = `Failed (HTTP ${err.status}): ${err.message}${detail ? ` (${detail})` : ''}`;
+    if (err.status === 401) {
+      line += '. Check the agent token: --token-file, COMMONLY_TOKEN_FILE or COMMONLY_AGENT_TOKEN.';
+    }
+  }
+  return line.replace(/\s+/g, ' ');
+};