@ravefox/space 0.2.1 → 0.4.0

package/src/lib/supervised-turn.js

@@ -1,352 +0,0 @@
-/**
- * One model turn of `commonly agent run`, on one of two paths. The supervised
- * path also writes one metadata line per turn (the turn log), once the
- * turn's outcome has reached the pod or failed to.
- *
- *   codex by default, or COMMONLY_SUPERVISE_RUNS=1 (superviseRunsByDefault in
- *     commands/agent.js; COMMONLY_SUPERVISE_RUNS=0 opts codex out)
- *     the turn runs under `superviseRun` from @commonlyai/seats: a stall
- *     window, a wall-clock backstop, and a guarantee the turn settles with a
- *     named failure. No provider relay: the CLI talks to its provider directly,
- *     exactly as on the plain path.
- *   anything else
- *     the plain path: `adapter.spawn(prompt, ctx)` with the caller's ctx object
- *     untouched, and nothing written: the flag-off run loop is main's.
- *
- * A turn is ok only when its outcome reached the pod: the reply was delivered
- * or the agent chose silence. The run loop names the outcome after delivery
- * settles (turn.finish); a spawn that threw is `failed` at once.
- *
- * NO RECORD WRITER. The supervisor needs a trace store. The one here
- * (createMetadataStore) is in memory, lives for one turn, and keeps event type
- * names, times and the recovery action word. It drops every event's data, so
- * no agent text, prompt, reply, failure detail or credential is kept, and
- * nothing is written to disk (a redaction review on #2701).
- *
- * Metrics: ~/.commonly/state/turns/<seat>.jsonl (COMMONLY_TURN_LOG_DIR
- * overrides the directory). Whitelisted fields only; see metricLine.
- */
-import { appendFileSync, mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
-import { superviseRun as defaultSuperviseRun } from '@commonlyai/seats/supervisor';
-import { isEventType } from '@commonlyai/seats/trace/events';
-import { failureKindOf } from '@commonlyai/seats/failures';
-import { classifySpawnFailure } from './spawn-retry.js';
-
-const MAX_TIMER_MS = 2_147_483_647;
-
-/**
- * Stall windows per adapter, in ms; 0 is off. Unlisted adapters: off.
- *
- * codex: `codex exec --json` writes a JSONL event per item, so its stdout is a
- *   real progress signal, and the quiet stretch is the longest single item (a
- *   reasoning step or one shell command). Measured 2026-10-25 from per-turn
- *   timestamp gaps in October codex rollouts on one host (~/.codex/sessions):
- *   9,703 turns, max quiet gap 162 s, p99 53 s; 9 turns would have tripped the
- *   package default of 120 s. 15 min is 5.5x the worst gap seen and still
- *   30 min inside the seats' 45 min turn budget.
- * claude: the adapter runs `claude -p --output-format text`, which writes
- *   nothing to stdout until the reply is done. A healthy 14-minute claude turn
- *   is 14 minutes of silence to the supervisor, so any window
- *   under the turn budget would be a turn-length cap, not a liveness check.
- *   Off; claude is guarded by the wall-clock backstop and the cancel ladder.
- */
-export const STALL_DEFAULTS_MS = Object.freeze({ codex: 15 * 60 * 1000, claude: 0 });
-// How long after the supervisor's abort before it SIGKILLs the child's tree
-// (process-group.js). The claude and codex adapters do not act on the abort,
-// so on a stall the child is alive at the kill and its whole tree goes with it:
-// a SIGTERM to the CLI alone would let it exit first and orphan the MCP
-// servers it started in groups of their own, which the tree kill then skips.
-// An adapter that honours ctx.signal gets this long to settle.
-export const CANCEL_GRACE_MS = 15_000;
-// The wall clock sits past the adapter's own timeout, so the adapter's timeout
-// (the same SIGTERM and error as on the plain path) fires first; the
-// supervisor's only settles a child that outlived it.
-export const WALL_BACKSTOP_MS = 60_000;
-// After a failed turn, how long to wait for the child's exit status before
-// writing the metric line anyway (the kill lands just before settle).
-const EXIT_WAIT_MS = 3_000;
-
-const envName = (prefix, adapterName) => `${prefix}_${String(adapterName || '').toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
-
-const envMs = (env, name, warnings) => {
-  const raw = env?.[name];
-  if (raw === undefined || raw === '') return undefined;
-  const value = Number(raw);
-  if (!Number.isInteger(value) || value < 0) {
-    warnings.push(`${name} ignored (want a non-negative integer of ms)`);
-    return undefined;
-  }
-  return Math.min(value, MAX_TIMER_MS);
-};
-
-/**
- * The supervisor policy for one adapter's turn. Env overrides, most specific
- * first: COMMONLY_SUPERVISE_STALL_MS_<ADAPTER>, COMMONLY_SUPERVISE_STALL_MS,
- * COMMONLY_SUPERVISE_CANCEL_GRACE_MS, COMMONLY_SUPERVISE_WALL_BACKSTOP_MS.
- * 0 turns a window off. No retries: the run loop keeps those.
- */
-export const supervisedRunPolicy = (turnTimeoutMs, { adapterName = null, env = process.env, warnings = [] } = {}) => {
-  const stallMs = envMs(env, envName('COMMONLY_SUPERVISE_STALL_MS', adapterName), warnings)
-    ?? envMs(env, 'COMMONLY_SUPERVISE_STALL_MS', warnings)
-    ?? STALL_DEFAULTS_MS[adapterName] ?? 0;
-  const cancelGraceMs = envMs(env, 'COMMONLY_SUPERVISE_CANCEL_GRACE_MS', warnings) ?? CANCEL_GRACE_MS;
-  const backstopMs = envMs(env, 'COMMONLY_SUPERVISE_WALL_BACKSTOP_MS', warnings) ?? WALL_BACKSTOP_MS;
-  return {
-    stallMs,
-    cancelGraceMs,
-    timeoutMs: Math.min(Number(turnTimeoutMs) + backstopMs, MAX_TIMER_MS),
-  };
-};
-
-/**
- * A trace store that keeps no agent text and writes nothing. superviseRun
- * calls startRun once per turn; each event keeps { type, at, action? }.
- */
-export const createMetadataStore = ({ now = Date.now } = {}) => {
-  let current = null;
-  let seq = 0;
-  return {
-    startRun({ runId } = {}) {
-      seq += 1;
-      const events = [];
-      let settled = false;
-      current = {
-        runId: runId || `turn-${now().toString(36)}-${seq}`,
-        emit(type, data) {
-          if (!isEventType(type)) throw new Error(`unknown trace event type: ${type}`);
-          if (settled) return null;
-          const entry = { type, at: now() };
-          if (type === 'liveness.recovery' && typeof data?.action === 'string') entry.action = data.action;
-          events.push(entry);
-          if (type === 'run.settled') settled = true;
-          return entry;
-        },
-        get settled() { return settled; },
-        events: () => events.map((entry) => ({ ...entry })),
-      };
-      return current;
-    },
-    lastRun: () => current,
-  };
-};
-
-export const metricsPathFor = (seat, env = process.env) => {
-  const dir = env?.COMMONLY_TURN_LOG_DIR || join(homedir(), '.commonly', 'state', 'turns');
-  const safe = String(seat || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64) || 'unknown';
-  return join(dir, `${safe}.jsonl`);
-};
-
-/** A failure's name, never its text. RunFailure kinds are the supervisor's words. */
-export const failureNameOf = (error) => {
-  const kind = failureKindOf(error) || (typeof error?.kind === 'string' && /^[a-z_]{1,40}$/.test(error.kind) ? error.kind : null);
-  if (kind) return { name: kind, source: 'supervisor' };
-  const message = String(error?.message ?? error ?? '');
-  if (/\btimed out after \d+ms\b/.test(message)) return { name: 'adapter_timeout', source: 'adapter' };
-  if (/\bexited with code\b/.test(message)) return { name: 'adapter_exit', source: 'adapter' };
-  return { name: 'adapter_error', source: 'adapter' };
-};
-
-const failureClassOf = (error) => {
-  try { return classifySpawnFailure(error); } catch { return null; }
-};
-
-// What happened to a turn, named by the run loop once delivery settles.
-export const TURN_OUTCOMES = Object.freeze([
-  'delivered', // the reply reached the pod (wrapper post, the agent's own post, or an ask response)
-  'silent', // NO_REPLY, a heartbeat control word, or empty output: nothing to post
-  'reply_lost', // the model answered and every delivery rung threw
-  'claim_lost', // the lease lapsed mid-turn and a peer owns the message; reply suppressed
-  'server_skipped', // the server answered and created nothing (a duplicate, a kept heartbeat)
-  'server_refused', // the server refused the post (a run cap)
-  'upstream_refused', // the model route refused; the CLI exited with nothing to say
-]);
-export const OK_OUTCOMES = Object.freeze(['delivered', 'silent']);
-
-const EVENT_TYPE_RE = /^[A-Za-z0-9._-]{1,40}$/;
-const iso = (ms) => new Date(ms).toISOString();
-const int = (value) => (Number.isInteger(value) ? value : null);
-
-/**
- * The metric line. Every field is listed here, each a number, boolean, null or
- * a short fixed word; nothing from the prompt, the reply, a failure's detail or
- * the environment can reach it.
- */
-export const metricLine = (f) => {
-  const failed = f.outcome === 'failed';
-  const outcome = failed || TURN_OUTCOMES.includes(f.outcome) ? f.outcome : 'unknown';
-  return {
-    v: 1,
-    ts: iso(f.settledMs ?? f.endMs),
-    seat: String(f.seat || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64),
-    adapter: String(f.adapter || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 32),
-    path: f.path === 'supervised' ? 'supervised' : 'legacy',
-    eventType: EVENT_TYPE_RE.test(String(f.eventType || '')) ? f.eventType : null,
-    turnStart: iso(f.startMs),
-    turnEnd: iso(f.endMs),
-    durationMs: Math.max(0, f.endMs - f.startMs),
-    outcome,
-    ok: OK_OUTCOMES.includes(outcome),
-    failure: failed ? (f.failureName || 'adapter_error') : null,
-    failureSource: failed ? (f.failureSource || null) : null,
-    failureClass: failed && typeof f.failureClass === 'string' ? f.failureClass : null,
-    stalled: !!f.stalled,
-    cancelled: !!f.cancelled,
-    killed: !!f.killed,
-    exitCode: int(f.exitCode),
-    signal: typeof f.signal === 'string' && /^SIG[A-Z0-9]+$/.test(f.signal) ? f.signal : null,
-    exitObserved: !!f.exitObserved,
-    childLeftRunning: typeof f.childLeftRunning === 'boolean' ? f.childLeftRunning : null,
-    attempts: int(f.attempts),
-    stallMs: int(f.policy?.stallMs),
-    cancelGraceMs: int(f.policy?.cancelGraceMs),
-    timeoutMs: int(f.policy?.timeoutMs),
-  };
-};
-
-const isChild = (value) => !!value && typeof value.once === 'function' && typeof value.kill === 'function';
-const isAlive = (child) => !!child && child.exitCode === null && child.signalCode === null;
-
-const waitForExit = (child, ms) => new Promise((resolve) => {
-  if (!isAlive(child)) { resolve(); return; }
-  const timer = setTimeout(resolve, ms);
-  timer.unref?.();
-  child.once('exit', () => { clearTimeout(timer); resolve(); });
-});
-
-/**
- * @param {object} args
- * @param {string} args.seat            agent name; names the metrics file
- * @param {number} args.turnTimeoutMs   the run loop's effective turn budget
- * @param {boolean} args.supervise      performRun's superviseRuns
- * @param {(line: string) => void} [args.log]
- * @param {object} [args.env]
- * @param {Function} [args.superviseRun]  injectable for tests
- */
-export const createTurnRunner = ({
-  seat,
-  turnTimeoutMs,
-  supervise = false,
-  log = () => {},
-  env = process.env,
-  now = Date.now,
-  superviseRun = defaultSuperviseRun,
-} = {}) => {
-  const metricsPath = metricsPathFor(seat, env);
-  let metricsWarned = false;
-
-  const record = (fields) => {
-    try {
-      mkdirSync(dirname(metricsPath), { recursive: true, mode: 0o700 });
-      appendFileSync(metricsPath, `${JSON.stringify(metricLine({ seat, ...fields }))}\n`, { mode: 0o600 });
-    } catch (error) {
-      // Metrics never fail a turn. Said once per process, not per turn.
-      if (!metricsWarned) {
-        metricsWarned = true;
-        log(`turn metrics not written (${error?.code || 'error'}); turns are unaffected`);
-      }
-    }
-  };
-
-  /** The boot line for the supervised path; the plain path logs nothing new. */
-  const describe = (adapterName) => {
-    const warnings = [];
-    const policy = supervisedRunPolicy(turnTimeoutMs, { adapterName, env, warnings });
-    return `supervised runs ON for ${adapterName}: stall=${policy.stallMs ? `${policy.stallMs}ms` : 'off'}, `
-      + `cancel grace=${policy.cancelGraceMs}ms, wall=${policy.timeoutMs}ms, `
-      + 'trace=memory (no record written); '
-      + `metrics → ${metricsPath}${warnings.length ? `; ${warnings.join('; ')}` : ''}`;
-  };
-
-  const runSupervised = async (adapter, prompt, ctx, eventType, hold) => {
-    const startMs = now();
-    const policy = supervisedRunPolicy(turnTimeoutMs, { adapterName: adapter?.name, env });
-    const store = createMetadataStore({ now });
-    let child = null;
-    let exit = null;
-    const callerOnSpawn = ctx?.onSpawn;
-    const onSpawn = (...args) => {
-      const proc = args.find(isChild);
-      if (proc) {
-        child = proc;
-        exit = null;
-        proc.once('exit', (code, signal) => { if (child === proc) exit = { code, signal }; });
-      }
-      return typeof callerOnSpawn === 'function' ? callerOnSpawn(...args) : undefined;
-    };
-
-    const supervised = await superviseRun({
-      adapter,
-      prompt,
-      ctx: { ...ctx, onSpawn },
-      store,
-      policy,
-      label: EVENT_TYPE_RE.test(String(eventType || '')) ? eventType : undefined,
-    });
-
-    const ok = !supervised.failure;
-    if (!ok) await waitForExit(child, EXIT_WAIT_MS);
-    const events = store.lastRun()?.events() || [];
-    const recovered = (action) => events.some((e) => e.type === 'liveness.recovery' && e.action === action);
-    const killed = recovered('kill');
-    const named = ok ? null : failureNameOf(supervised.failure);
-    const fields = {
-      adapter: adapter?.name,
-      path: 'supervised',
-      eventType,
-      startMs,
-      endMs: now(),
-      outcome: ok ? undefined : 'failed',
-      failureName: named?.name,
-      failureSource: named?.source,
-      failureClass: ok ? null : failureClassOf(supervised.failure),
-      stalled: events.some((e) => e.type === 'liveness.stalled'),
-      cancelled: recovered('cancel'),
-      killed,
-      exitCode: exit ? exit.code : null,
-      signal: exit ? exit.signal : null,
-      exitObserved: !!exit,
-      childLeftRunning: child ? isAlive(child) : null,
-      attempts: supervised.attempts,
-      policy,
-    };
-    // A spawn that resolved is not yet an ok turn: the line waits for the run
-    // loop to say what became of the reply.
-    if (ok) { hold(fields); return supervised.result; }
-    record(fields);
-    if (named.source === 'supervisor') {
-      // The name goes in the seat log. The throw takes the road a plain-path
-      // failure takes: unacked, the run loop's retry policy, onError.
-      log(`[${eventType}] supervised turn failed: ${named.name}${killed ? ' (child killed)' : ''}`
-        + `${isAlive(child) ? ' (child still running)' : ''}`);
-    }
-    throw supervised.failure;
-  };
-
-  return {
-    supervise,
-    metricsPath,
-    describe,
-    /**
-     * One model turn. `run` has adapter.spawn's contract; `finish(outcome)`
-     * writes the line once delivery has settled. Only the first finish counts,
-     * and a finish with no spawned turn behind it writes nothing.
-     */
-    begin({ eventType } = {}) {
-      let held = null;
-      let done = false;
-      return {
-        run(adapter, prompt, ctx) {
-          if (!supervise) return adapter.spawn(prompt, ctx);
-          return runSupervised(adapter, prompt, ctx, eventType, (fields) => { held = fields; });
-        },
-        finish(outcome) {
-          if (done || !held) return;
-          done = true;
-          record({ ...held, outcome, settledMs: now() });
-        },
-      };
-    },
-  };
-};

package/src/lib/task.js

@@ -1,235 +0,0 @@
-/**
- * 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';
-import { CLI } from './cli-hint.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: \`${CLI} task claim\` writes the lease, and a bare status does not.`);
-  }
-  if (status === 'done') {
-    throw new TaskRefusal(`--status done is refused: \`${CLI} 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, ' ');
-};