ultra-builder-pro-cli 0.5.0

package/ultra-tools/commands/session.cjs

@@ -0,0 +1,180 @@
+'use strict';
+
+// CLI fallback for the session.* MCP tool family.
+// Phase 4.5.4/4.5.6 scope: list / admission / reap / get / heartbeat / close /
+// subscribe. session.spawn is intentionally not in the CLI layer — it
+// requires a long-lived parent process (the child's lifecycle tracks the
+// caller). orchestrator/session-runner.cjs is the proper entry for spawn.
+
+const path = require('node:path');
+const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const ops = require('../../mcp-server/lib/state-ops.cjs');
+
+const DEFAULT_DB_PATH = path.join('.ultra', 'state.db');
+
+const USAGE = `ultra-tools session <verb> [flags]
+
+VERBS:
+  list        --status running|completed|crashed|orphan  [--task-id <id>] [--limit <n>]
+  admission   --task-id <id>                             admission_check
+  reap        [--grace-seconds <n>]                      orphan sweeper (Phase 4.5.6)
+  get         --sid <sid>
+  heartbeat   --sid <sid>
+  close       --sid <sid> --status completed|crashed|orphan
+  subscribe   --since-id <n> [--sid <sid>] [--limit <n>]
+
+GLOBAL FLAGS:
+  --db <path>  path to state.db (default: .ultra/state.db)
+  -h, --help   show this message
+`;
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+function parseFlags(args) {
+  const flags = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--db':              flags.db = args[++i]; break;
+      case '--status':          flags.status = args[++i]; break;
+      case '--task-id':         flags.task_id = args[++i]; break;
+      case '--sid':             flags.sid = args[++i]; break;
+      case '--limit':           flags.limit = Number(args[++i]); break;
+      case '--since-id':        flags.since_id = Number(args[++i]); break;
+      case '--grace-seconds':   flags.grace_seconds = Number(args[++i]); break;
+      case '-h': case '--help': flags.help = true; break;
+      default:                  flags._.push(a);
+    }
+  }
+  return flags;
+}
+
+function withDb(flags, fn) {
+  const dbPath = path.resolve(flags.db || DEFAULT_DB_PATH);
+  const { db } = initStateDb(dbPath);
+  try { return fn(db); }
+  finally { try { closeStateDb(db); } catch (_) { /* ignore */ } }
+}
+
+function cmdList(flags) {
+  return withDb(flags, (db) => {
+    const status = flags.status || 'running';
+    let sessions;
+    if (status === 'running') {
+      sessions = ops.listActiveSessions(db, { task_id: flags.task_id });
+    } else {
+      sessions = db.prepare(
+        "SELECT * FROM sessions WHERE status = ? AND (? IS NULL OR task_id = ?) ORDER BY started_at ASC LIMIT ?",
+      ).all(status, flags.task_id || null, flags.task_id || null, Math.min(flags.limit || 100, 500));
+    }
+    const limit = Math.min(flags.limit || 100, 500);
+    const trimmed = sessions.slice(0, limit);
+    emit({ ok: true, data: { sessions: trimmed, count: trimmed.length } });
+    return 0;
+  });
+}
+
+function cmdAdmission(flags) {
+  if (!flags.task_id) { emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing --task-id' } }); return 1; }
+  return withDb(flags, (db) => {
+    try {
+      const v = ops.admissionCheck(db, flags.task_id);
+      emit({ ok: true, data: v });
+      return 0;
+    } catch (err) {
+      emit({ ok: false, error: { code: err.code || 'STATE_DB_ERROR', message: err.message, retriable: !!err.retriable } });
+      return err.code === 'TASK_NOT_FOUND' ? 1 : 2;
+    }
+  });
+}
+
+function cmdReap(flags) {
+  return withDb(flags, (db) => {
+    const grace = Number.isFinite(flags.grace_seconds) ? flags.grace_seconds : 300;
+    const r = ops.reapOrphanSessions(db, { graceSeconds: grace });
+    emit({ ok: true, data: r });
+    return 0;
+  });
+}
+
+function cmdGet(flags) {
+  if (!flags.sid) { emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing --sid' } }); return 1; }
+  return withDb(flags, (db) => {
+    const s = ops.readSession(db, flags.sid);
+    if (!s) { emit({ ok: false, error: { code: 'SESSION_NOT_FOUND', message: `sid ${flags.sid} not found` } }); return 1; }
+    emit({ ok: true, data: { session: s } });
+    return 0;
+  });
+}
+
+function cmdHeartbeat(flags) {
+  if (!flags.sid) { emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing --sid' } }); return 1; }
+  return withDb(flags, (db) => {
+    try {
+      const r = ops.heartbeatSession(db, flags.sid);
+      emit({ ok: true, data: r });
+      return 0;
+    } catch (err) {
+      emit({ ok: false, error: { code: err.code || 'STATE_DB_ERROR', message: err.message } });
+      return err.code === 'LEASE_EXPIRED' ? 3 : 2;
+    }
+  });
+}
+
+function cmdClose(flags) {
+  if (!flags.sid || !flags.status) { emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing --sid or --status' } }); return 1; }
+  return withDb(flags, (db) => {
+    try {
+      ops.updateSession(db, flags.sid, { status: flags.status });
+      emit({ ok: true, data: { sid: flags.sid, status: flags.status } });
+      return 0;
+    } catch (err) {
+      emit({ ok: false, error: { code: err.code || 'STATE_DB_ERROR', message: err.message } });
+      return 2;
+    }
+  });
+}
+
+function cmdSubscribe(flags) {
+  return withDb(flags, (db) => {
+    const r = ops.subscribeEventsSince(db, {
+      since_id: Number.isFinite(flags.since_id) ? flags.since_id : 0,
+      task_id: flags.sid ? undefined : undefined,
+      limit: flags.limit,
+    });
+    emit({ ok: true, data: r });
+    return 0;
+  });
+}
+
+function dispatch(args) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === '-h' || verb === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const flags = parseFlags(rest);
+  if (flags.help) { process.stdout.write(USAGE); return 0; }
+
+  switch (verb) {
+    case 'list':       return cmdList(flags);
+    case 'admission':  return cmdAdmission(flags);
+    case 'reap':       return cmdReap(flags);
+    case 'get':        return cmdGet(flags);
+    case 'heartbeat':  return cmdHeartbeat(flags);
+    case 'close':      return cmdClose(flags);
+    case 'subscribe':  return cmdSubscribe(flags);
+    case 'spawn': {
+      emit({ ok: false, error: { code: 'NOT_SUPPORTED', message: 'session spawn via CLI is not supported; use orchestrator/session-runner.cjs — CLI cannot own the child lifecycle' } });
+      return 1;
+    }
+    default: {
+      emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown session verb '${verb}'; see spec/cli-protocol.md for supported session CLI verbs` } });
+      return 1;
+    }
+  }
+}
+
+module.exports = { dispatch, USAGE };

package/ultra-tools/commands/status.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+// Phase 6.3 — ultra-tools status cost panel.
+//
+// Reads telemetry aggregations from state.db (Phase 6.2) and renders either
+// a human-readable table or a JSON envelope consumable by skills/ultra-status.
+// Does not modify state — read-only command.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ops = require('../../mcp-server/lib/state-ops.cjs');
+
+const USAGE = `ultra-tools status [flags]
+
+Reads telemetry from .ultra/state.db and prints a cost + activity summary.
+
+FLAGS:
+  --cost            include per-runtime + top-tasks cost panel (default on)
+  --json            emit machine-readable envelope on stdout
+  --since <period>  filter to last N (e.g. 7d, 24h) or ISO8601 cutoff
+  --limit <n>       top-N tasks (default 3)
+  -h, --help        show this message
+`;
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+function fail(code, message) {
+  emit({ ok: false, error: { code, message, retriable: false } });
+  return 2;
+}
+
+function parseSince(value, nowMs = Date.now()) {
+  if (value === null || value === undefined || value === '') return null;
+  const s = String(value).trim();
+  if (/^\d{4}-\d{2}-\d{2}T/.test(s)) return s;
+  const m = s.match(/^(\d+)([dhm])$/i);
+  if (!m) throw new Error(`invalid --since value: ${value} (expected 7d, 24h, 30m, or ISO-8601)`);
+  const n = Number(m[1]);
+  const unit = m[2].toLowerCase();
+  const ms = unit === 'd' ? n * 86400000 : unit === 'h' ? n * 3600000 : n * 60000;
+  return new Date(nowMs - ms).toISOString();
+}
+
+function parseFlags(args) {
+  const out = { cost: true, json: false, since: null, limit: 3 };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--cost':  out.cost = true; break;
+      case '--json':  out.json = true; break;
+      case '--since': out.since = args[++i]; break;
+      case '--limit': out.limit = Number(args[++i]); break;
+      case '-h': case '--help': return { help: true };
+      default:
+        if (a.startsWith('--since=')) out.since = a.split('=')[1];
+        else if (a.startsWith('--limit=')) out.limit = Number(a.split('=')[1]);
+        else throw new Error(`unknown flag: ${a}`);
+    }
+  }
+  if (Number.isNaN(out.limit) || out.limit <= 0) out.limit = 3;
+  return out;
+}
+
+function buildCostPanel(db, { since = null, limit = 3 } = {}) {
+  const by_runtime = ops.aggregateTelemetryByRuntime(db, { since });
+  const top_tasks = ops.aggregateTelemetryByTask(db, { since, limit });
+  const total_cost_usd = by_runtime.reduce((acc, r) => acc + (r.cost_usd || 0), 0);
+  return {
+    period: { since: since || 'all-time' },
+    by_runtime,
+    top_tasks,
+    total_cost_usd,
+  };
+}
+
+function formatCost(n) {
+  if (!n) return '$0.0000';
+  if (n < 0.01) return `$${n.toFixed(6)}`;
+  return `$${n.toFixed(4)}`;
+}
+
+function renderHuman(panel) {
+  const lines = [];
+  lines.push(`Period: ${panel.period.since}`);
+  lines.push(`Total cost: ${formatCost(panel.total_cost_usd)}`);
+  lines.push('');
+  lines.push('Cost by runtime:');
+  if (panel.by_runtime.length === 0) {
+    lines.push('  (no telemetry)');
+  } else {
+    lines.push('  runtime     calls   tokens_in  tokens_out   cost');
+    for (const r of panel.by_runtime) {
+      lines.push(
+        '  ' + r.runtime.padEnd(10) +
+        String(r.calls).padStart(6) +
+        String(r.tokens_in).padStart(12) +
+        String(r.tokens_out).padStart(12) +
+        '   ' + formatCost(r.cost_usd),
+      );
+    }
+  }
+  lines.push('');
+  lines.push('Top tasks by cost:');
+  if (panel.top_tasks.length === 0) {
+    lines.push('  (no task-scoped telemetry)');
+  } else {
+    for (const t of panel.top_tasks) {
+      lines.push(`  ${t.task_id.padEnd(24)}  calls=${t.calls}  cost=${formatCost(t.cost_usd)}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function resolveDbPath() {
+  if (process.env.UBP_DB_PATH) return path.resolve(process.env.UBP_DB_PATH);
+  return path.resolve('.ultra', 'state.db');
+}
+
+function dispatch(args) {
+  let flags;
+  try { flags = parseFlags(args); } catch (err) { return fail('USAGE_ERROR', err.message); }
+  if (flags.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const dbPath = resolveDbPath();
+  if (!fs.existsSync(dbPath)) {
+    return fail('STATE_DB_MISSING', `state.db not found at ${dbPath}`);
+  }
+  let since;
+  try { since = parseSince(flags.since); } catch (err) { return fail('USAGE_ERROR', err.message); }
+
+  const Database = require('better-sqlite3');
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const panel = buildCostPanel(db, { since, limit: flags.limit });
+    if (flags.json) {
+      emit({ ok: true, data: panel });
+    } else {
+      process.stdout.write(renderHuman(panel));
+    }
+    return 0;
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = {
+  USAGE,
+  dispatch,
+  buildCostPanel,
+  renderHuman,
+  parseSince,
+  parseFlags,
+};

package/ultra-tools/commands/task.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+// CLI dispatcher for the `task` family. Phase 3.1 implements `init-project`
+// as the fallback for /ultra-init when MCP is unreachable. Additional verbs
+// (create / update / list / ...) will be wired in Phase 3.3+ as each command
+// migrates — they share the same stdout envelope contract declared in
+// spec/cli-protocol.md §2.
+
+const { initProject, InitProjectError } = require('../../mcp-server/lib/init-project.cjs');
+
+const USAGE = `ultra-tools task <verb> [flags]
+
+VERBS:
+  init-project  Bootstrap a fresh .ultra/ skeleton (Phase 3.1)
+
+FLAGS (init-project):
+  --target-dir <path>       target project root (default: cwd)
+  --project-name <name>     project name (required)
+  --project-type <type>     web | api | cli | fullstack | other
+  --stack <stack>           tech stack descriptor (comma-separated ok)
+  --overwrite               replace existing .ultra/ (backup created)
+  --source-template <path>  override bundled template source
+  -h, --help                show this message
+`;
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+function parseInitFlags(args) {
+  const flags = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--target-dir':       flags.target_dir       = args[++i]; break;
+      case '--project-name':     flags.project_name     = args[++i]; break;
+      case '--project-type':     flags.project_type     = args[++i]; break;
+      case '--stack':            flags.stack            = args[++i]; break;
+      case '--source-template':  flags.source_template  = args[++i]; break;
+      case '--overwrite':        flags.overwrite        = true; break;
+      case '--no-overwrite':     flags.overwrite        = false; break;
+      case '-h': case '--help':  flags.help = true; break;
+      default:                   flags._.push(a);
+    }
+  }
+  return flags;
+}
+
+function dispatchInitProject(rawArgs) {
+  const flags = parseInitFlags(rawArgs);
+  if (flags.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (!flags.project_name) {
+    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing required flag: --project-name' } });
+    return 1;
+  }
+  const input = {
+    target_dir: flags.target_dir || process.cwd(),
+    project_name: flags.project_name,
+    project_type: flags.project_type,
+    stack: flags.stack,
+    overwrite: !!flags.overwrite,
+    source_template: flags.source_template,
+  };
+  try {
+    const data = initProject(input);
+    emit({ ok: true, data });
+    return 0;
+  } catch (err) {
+    if (err instanceof InitProjectError) {
+      emit({ ok: false, error: { code: err.code, message: err.message, retriable: !!err.retriable } });
+      return err.code === 'VALIDATION_ERROR' ? 1 : 2;
+    }
+    emit({ ok: false, error: { code: 'UNKNOWN', message: err.message, retriable: false } });
+    return 2;
+  }
+}
+
+function dispatch(args) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === '-h' || verb === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  switch (verb) {
+    case 'init-project': return dispatchInitProject(rest);
+    default:
+      emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown task verb '${verb}'; see spec/cli-protocol.md for supported task CLI verbs` } });
+      return 1;
+  }
+}
+
+module.exports = { dispatch, dispatchInitProject, USAGE };

package/ultra-tools/legacy-memory.test.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const Database = require('better-sqlite3');
+
+const legacy = require('./commands/legacy-memory.cjs');
+
+function fixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-legacy-memory-'));
+  const ultra = path.join(root, '.ultra');
+  fs.mkdirSync(path.join(ultra, 'memory'), { recursive: true });
+  fs.writeFileSync(path.join(ultra, 'memory', 'memory.db'), 'legacy-hook-store');
+  const db = new Database(path.join(ultra, 'state.db'));
+  db.exec(`
+    CREATE TABLE memory_entries (
+      id INTEGER PRIMARY KEY, kind TEXT, content TEXT, task_id TEXT,
+      session_id TEXT, tag TEXT, source TEXT, ts TEXT
+    );
+    INSERT INTO memory_entries
+      (kind, content, task_id, session_id, tag, source, ts)
+    VALUES ('decision', 'legacy decision', 't1', 's1', 'arch', 'test', '2026-01-01T00:00:00Z');
+  `);
+  db.close();
+  return root;
+}
+
+test('inspect reports both legacy stores without mutating them', () => {
+  const root = fixture();
+  try {
+    const result = legacy.inspectLegacy(root);
+    assert.equal(result.hook_memory_dir, true);
+    assert.equal(result.state_memory_table, true);
+    assert.equal(result.state_memory_entries, 1);
+    assert.ok(fs.existsSync(path.join(root, '.ultra', 'memory', 'memory.db')));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+test('archive exports legacy state rows and copies hook memory without deletion', () => {
+  const root = fixture();
+  try {
+    const result = legacy.archiveLegacy(root, { timestamp: '2026-07-15T00-00-00-000Z' });
+    assert.equal(result.archived, true);
+    assert.ok(fs.existsSync(path.join(result.archive_dir, 'hook-memory', 'memory.db')));
+    const exported = JSON.parse(fs.readFileSync(path.join(result.archive_dir, 'state-memory-entries.json'), 'utf8'));
+    assert.equal(exported.entries.length, 1);
+    assert.equal(exported.entries[0].content, 'legacy decision');
+    assert.ok(fs.existsSync(path.join(root, '.ultra', 'memory', 'memory.db')));
+    const db = new Database(path.join(root, '.ultra', 'state.db'), { readonly: true });
+    assert.ok(db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'memory_entries'").get());
+    db.close();
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('prune requires an exact confirmation and archives before deleting', () => {
+  const root = fixture();
+  try {
+    assert.throws(() => legacy.pruneLegacy(root, { confirm: 'yes' }), /DELETE_ULTRA_LEGACY_MEMORY/);
+    assert.ok(fs.existsSync(path.join(root, '.ultra', 'memory', 'memory.db')));
+
+    const result = legacy.pruneLegacy(root, {
+      confirm: 'DELETE_ULTRA_LEGACY_MEMORY',
+      timestamp: '2026-07-15T00-00-01-000Z',
+    });
+    assert.equal(result.pruned, true);
+    assert.ok(fs.existsSync(result.archive_dir));
+    assert.ok(!fs.existsSync(path.join(root, '.ultra', 'memory')));
+    const db = new Database(path.join(root, '.ultra', 'state.db'), { readonly: true });
+    assert.equal(db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'memory_entries'").get(), undefined);
+    db.close();
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/ultra-tools/status-command.test.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+// Phase 6.3 — ultra-tools status cost panel:
+//   • `ultra-tools status --cost --json` prints {period, by_runtime,
+//     top_tasks, total_cost_usd}.
+//   • Default human-readable mode renders a summary table.
+//   • --since 7d filters telemetry to the last 7 days.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('../mcp-server/lib/state-db.cjs');
+const ops = require('../mcp-server/lib/state-ops.cjs');
+const telemetry = require('../mcp-server/lib/telemetry.cjs');
+const statusCmd = require('./commands/status.cjs');
+
+function freshFixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-status-'));
+  const file = path.join(dir, '.ultra', 'state.db');
+  const init = initStateDb(file);
+  return { dir, db: init.db };
+}
+
+function teardown(dir, db) {
+  try { closeStateDb(db); } catch (_) { /* ignore */ }
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+function seedCalls(db, dir) {
+  ops.createTask(db, { id: 't-cheap', title: 'cheap', type: 'feature', priority: 'P2' });
+  ops.createTask(db, { id: 't-pricey', title: 'pricey', type: 'feature', priority: 'P1' });
+  ops.createSession(db, { sid: 's-x', task_id: 't-cheap', runtime: 'claude', worktree_path: `${dir}/w1`, artifact_dir: `${dir}/a1` });
+  ops.createSession(db, { sid: 's-y', task_id: 't-pricey', runtime: 'codex', worktree_path: `${dir}/w2`, artifact_dir: `${dir}/a2` });
+  telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 't', session_id: 's-x', runtime: 'claude', tokens_input: 500, tokens_output: 100, rootDir: dir, payload: { model: 'claude-haiku-4-5' } });
+  telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 't', session_id: 's-y', runtime: 'codex', tokens_input: 10000, tokens_output: 2000, rootDir: dir, payload: { model: 'gpt-5.4' } });
+  telemetry.appendTelemetry(db, { event_type: 'tool_call', tool_name: 'task.list', session_id: null, rootDir: dir });
+}
+
+test('status --json --cost returns by_runtime + top_tasks + total_cost', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedCalls(db, dir);
+    const out = statusCmd.buildCostPanel(db, { since: null, limit: 10 });
+    assert.ok(Array.isArray(out.by_runtime));
+    assert.ok(Array.isArray(out.top_tasks));
+    assert.ok(typeof out.total_cost_usd === 'number');
+    const byR = Object.fromEntries(out.by_runtime.map((r) => [r.runtime, r]));
+    assert.equal(byR.claude.calls, 1);
+    assert.equal(byR.codex.calls, 1);
+    assert.equal(byR.unknown.calls, 1); // CLI call with null session
+    assert.equal(out.top_tasks[0].task_id, 't-pricey');
+    assert.ok(out.total_cost_usd > 0);
+  } finally { teardown(dir, db); }
+});
+
+test('buildCostPanel: empty db → zero totals, empty arrays', () => {
+  const { dir, db } = freshFixture();
+  try {
+    const out = statusCmd.buildCostPanel(db, {});
+    assert.equal(out.total_cost_usd, 0);
+    assert.equal(out.by_runtime.length, 0);
+    assert.equal(out.top_tasks.length, 0);
+  } finally { teardown(dir, db); }
+});
+
+test('buildCostPanel: since cutoff in future → all filtered out', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedCalls(db, dir);
+    const future = new Date(Date.now() + 60 * 1000).toISOString();
+    const out = statusCmd.buildCostPanel(db, { since: future });
+    assert.equal(out.by_runtime.length, 0);
+    assert.equal(out.top_tasks.length, 0);
+  } finally { teardown(dir, db); }
+});
+
+test('parseSince: 7d / 24h / iso passthrough', () => {
+  const now = Date.parse('2026-04-17T12:00:00Z');
+  const sevenDaysAgo = statusCmd.parseSince('7d', now);
+  const expectedDayCutoff = new Date(now - 7 * 24 * 3600 * 1000).toISOString();
+  assert.equal(sevenDaysAgo, expectedDayCutoff);
+  assert.equal(statusCmd.parseSince('24h', now), new Date(now - 24 * 3600 * 1000).toISOString());
+  assert.equal(statusCmd.parseSince('2026-04-10T00:00:00Z'), '2026-04-10T00:00:00Z');
+  assert.equal(statusCmd.parseSince(null), null);
+});
+
+test('parseSince: invalid → throws', () => {
+  assert.throws(() => statusCmd.parseSince('bogus'), /since/i);
+});
+
+test('renderHuman: includes key section headers', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedCalls(db, dir);
+    const panel = statusCmd.buildCostPanel(db, {});
+    const text = statusCmd.renderHuman(panel);
+    assert.match(text, /Cost by runtime/i);
+    assert.match(text, /Top tasks/i);
+    assert.match(text, /claude/);
+    assert.match(text, /codex/);
+  } finally { teardown(dir, db); }
+});
+
+test('dispatch: --json echoes buildCostPanel output shape', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedCalls(db, dir);
+    closeStateDb(db);
+    const captured = [];
+    const origWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk) => { captured.push(String(chunk)); return true; };
+    const envBackup = process.env.UBP_DB_PATH;
+    process.env.UBP_DB_PATH = path.join(dir, '.ultra', 'state.db');
+    try {
+      const code = statusCmd.dispatch(['--cost', '--json']);
+      assert.equal(code, 0);
+    } finally {
+      process.stdout.write = origWrite;
+      if (envBackup === undefined) delete process.env.UBP_DB_PATH; else process.env.UBP_DB_PATH = envBackup;
+    }
+    const joined = captured.join('');
+    const parsed = JSON.parse(joined);
+    assert.ok(parsed.ok);
+    assert.ok(parsed.data.by_runtime);
+    assert.ok(parsed.data.top_tasks);
+  } finally {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+  }
+});