job-forge 2.0.0

package/scripts/cursor-agent-loop.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# Re-exec under bash when invoked as `sh` (often dash on Linux). This script uses
+# bash-only syntax ([[, arrays, PIPESTATUS, BASH_SOURCE).
+if [ -z "${BASH_VERSION+x}" ]; then
+  exec /usr/bin/env bash "$0" "$@"
+fi
+
+# Drive Cursor Agent CLI in a loop (non-interactive). Each iteration is one agent
+# session that explores the repo, picks the next best improvement, implements it,
+# runs a small quality gate, commits, and optionally pushes.
+#
+# Task selection (humans/agents):
+#   - Read CONTRIBUTING.md ("What to Contribute") and docs/SETUP.md, docs/ARCHITECTURE.md,
+#     docs/CUSTOMIZATION.md for direction.
+#   - Search for open work (repo root): rg 'TODO|FIXME|HACK' . --glob '*.mjs' --glob '*.go' --glob '*.md' --glob '*.sh'
+#   - Improve modes/*.md, .mjs utilities, templates/, examples/, or dashboard/ (Go TUI)
+#     in one cohesive slice per iteration.
+#   - Do not commit personal artifacts (cv.md, config/profile.yml, data/applications.md,
+#     reports/, user portals.yml) — see CONTRIBUTING.md and .gitignore.
+#
+# Quality gate (repo root):
+#   npm run verify
+#   npm run build:dashboard   # same as (cd dashboard && go build .)
+#   verify-pipeline.mjs exits 0 when applications.md is missing (fresh clone); still
+#   run it. Dashboard build requires Go on PATH when touching dashboard/.
+#   Do not require npm run sync-check (cv-sync-check.mjs) in the gate: it expects
+#   personal cv.md and profile.yml and fails on a clean template checkout.
+#
+# Self-improve: when this script or its header comments are stale vs CONTRIBUTING.md
+# or real workflows, a minimal accurate edit here is fair game for an iteration.
+#
+# Prerequisites:
+#   - Cursor Agent CLI: https://cursor.com/install (`agent` on PATH)
+#   - Auth: `agent login` or CURSOR_API_KEY
+#   - Node.js for npm run verify
+#   - Go (when working on dashboard/)
+#   - For push: configured remote; new branches may need `git push -u origin HEAD` once
+#
+# Environment (optional):
+#   CURSOR_AGENT_ITERATIONS   Max agent runs (default: 100)
+#   CURSOR_AGENT_PUSH         If 1, git push after each iteration (default: 1). 0 = no push.
+#   CURSOR_AGENT_FORCE_SHELL  If 1, pass --force for agent shell (default: 1). Set 0 for prompts.
+#   CURSOR_AGENT_WORKSPACE    Repo root (default: git top-level from cwd)
+#   CURSOR_AGENT_MODEL        Passed as --model (default: composer-2)
+#   CURSOR_AGENT_EXTRA        Extra instructions appended to the built-in prompt
+#   CURSOR_AGENT_VERBOSE      If 1, stream agent progress via stream-json (default: 1). 0 = text only
+#   CURSOR_AGENT_GIT_AUTHOR_NAME   Git author/committer name (default: Charlie Greenman)
+#   CURSOR_AGENT_GIT_AUTHOR_EMAIL  Git author/committer email (default: GitHub noreply for this repo)
+#
+# Usage:
+#   ./scripts/cursor-agent-loop.sh
+#   CURSOR_AGENT_ITERATIONS=3 ./scripts/cursor-agent-loop.sh
+#   CURSOR_AGENT_PUSH=0 CURSOR_AGENT_VERBOSE=0 ./scripts/cursor-agent-loop.sh
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STREAM_FORMATTER="${SCRIPT_DIR}/cursor-agent-stream-format.py"
+
+ITERATIONS="${CURSOR_AGENT_ITERATIONS:-100}"
+PUSH="${CURSOR_AGENT_PUSH:-1}"
+FORCE_SHELL="${CURSOR_AGENT_FORCE_SHELL:-1}"
+VERBOSE="${CURSOR_AGENT_VERBOSE:-1}"
+WORKSPACE="${CURSOR_AGENT_WORKSPACE:-}"
+MODEL="${CURSOR_AGENT_MODEL:-composer-2}"
+EXTRA="${CURSOR_AGENT_EXTRA:-}"
+
+if ! command -v agent >/dev/null 2>&1; then
+  echo "error: 'agent' not found. Install Cursor Agent CLI: https://cursor.com/install" >&2
+  exit 1
+fi
+
+if [[ "$VERBOSE" == "1" ]]; then
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "warning: python3 not found; install Python 3 or set CURSOR_AGENT_VERBOSE=0" >&2
+    VERBOSE=0
+  elif [[ ! -f "$STREAM_FORMATTER" ]]; then
+    echo "warning: missing ${STREAM_FORMATTER}; set CURSOR_AGENT_VERBOSE=0" >&2
+    VERBOSE=0
+  fi
+fi
+
+if [[ -z "$WORKSPACE" ]]; then
+  WORKSPACE="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+    echo "error: not inside a git repository (set CURSOR_AGENT_WORKSPACE)" >&2
+    exit 1
+  }
+fi
+
+cd "$WORKSPACE"
+
+current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ "$PUSH" == "1" && "$current_branch" == "main" ]]; then
+  echo "warning: will push to main after each iteration; use a feature branch or CURSOR_AGENT_PUSH=0 if unintended." >&2
+fi
+
+case "$ITERATIONS" in
+'' | *[!0-9]*)
+  echo "error: CURSOR_AGENT_ITERATIONS must be a positive integer (got: ${ITERATIONS})" >&2
+  exit 1
+  ;;
+esac
+if [[ "$ITERATIONS" -lt 1 ]]; then
+  echo "error: CURSOR_AGENT_ITERATIONS must be >= 1" >&2
+  exit 1
+fi
+
+if [[ "$PUSH" == "1" ]]; then
+  PUSH_TEXT="After a successful commit, do not run git push; the host script runs git push immediately after this agent exits."
+else
+  PUSH_TEXT="Do not run git push."
+fi
+
+GIT_AUTHOR_NAME="${CURSOR_AGENT_GIT_AUTHOR_NAME:-Charlie Greenman}"
+GIT_AUTHOR_EMAIL="${CURSOR_AGENT_GIT_AUTHOR_EMAIL:-CharlieGreenman@users.noreply.github.com}"
+export GIT_AUTHOR_NAME GIT_AUTHOR_EMAIL
+export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
+export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
+
+build_prompt() {
+  cat <<EOF
+You are working on JobForge, an AI-powered job-search pipeline (Claude Code modes, Node utilities, optional Go dashboard). Respect CLAUDE.md, CONTRIBUTING.md, and .cursor rules if present.
+
+Single iteration — do exactly one cohesive, meaningful slice of work:
+
+1. Explore the repo. Read CLAUDE.md, CONTRIBUTING.md, and skim docs/ (SETUP, ARCHITECTURE, CUSTOMIZATION). Understand modes/, batch/, templates/, and dashboard/ when relevant.
+
+2. Decide what to work on. Priority order:
+   a) CONTRIBUTING.md "What to Contribute" and obvious gaps in docs or examples.
+   b) Search for concrete hooks: e.g. \`rg 'TODO|FIXME|HACK' . --glob '*.mjs' --glob '*.go' --glob '*.md' --glob '*.sh'\` (repo root; adjust as needed).
+   c) One subsystem per iteration: a mode file in modes/, a script (*.mjs), template/example polish, or dashboard (Go) — not a repo-wide refactor.
+   d) Self-improve this loop: if scripts/cursor-agent-loop.sh or its header is wrong or missing heuristics, fix it minimally when that is highest leverage.
+
+   Do NOT commit or "fix" user-specific files: cv.md, config/profile.yml, portals.yml with personal data, data/applications.md, reports/, or other private paths called out in CONTRIBUTING / .gitignore. Upstream improvements should stay generic.
+
+   Pick something concrete. Do NOT claim there is nothing to do.
+
+3. Implement with minimal scope. Match existing style (markdown tone, Node ESM, Go conventions in dashboard/). Scripts should handle missing files gracefully (see CONTRIBUTING).
+
+4. Run the quality gate from the repo root:
+   npm run verify
+   npm run build:dashboard
+   If you did not change dashboard/, the go build still must pass — fix any breakage you introduced. If Go is missing from the environment, say so clearly and stop rather than skipping silently.
+
+5. If you made real changes: git add only what belongs to this task, then commit with author and message rules:
+   - Author must be exactly: ${GIT_AUTHOR_NAME} <${GIT_AUTHOR_EMAIL}>
+     Use: git commit --author="${GIT_AUTHOR_NAME} <${GIT_AUTHOR_EMAIL}>" -m "type: short description"
+     (GIT_AUTHOR_*/GIT_COMMITTER_* may already be exported for this session; the result must still show that author.)
+   - Subject/body: conventional prefix (feat:/fix:/chore:/docs:/test:/refactor:). Describe the change only.
+   - Do not mention Cursor, Cursor Agent, ChatGPT, Claude, automation, bots, or "AI" / "generated" in the commit message.
+   ${PUSH_TEXT}
+
+6. Do not force-push. Do not rewrite published history.
+
+7. End your response with a final line: DONE
+
+${EXTRA}
+EOF
+}
+
+agent_cmd=(agent -p --trust --workspace "$WORKSPACE")
+if [[ "$VERBOSE" == "1" ]]; then
+  agent_cmd+=(--output-format stream-json --stream-partial-output)
+else
+  agent_cmd+=(--output-format text)
+fi
+if [[ "$FORCE_SHELL" == "1" ]]; then
+  agent_cmd+=(--force)
+fi
+agent_cmd+=(--model "$MODEL")
+
+i=1
+while true; do
+  if [[ "$i" -gt "$ITERATIONS" ]]; then
+    break
+  fi
+
+  echo "=== cursor-agent-loop: iteration $i of ${ITERATIONS} ===" >&2
+  prompt="$(build_prompt)"
+  agent_status=0
+  if [[ "$VERBOSE" == "1" ]]; then
+    set +e
+    "${agent_cmd[@]}" "$prompt" | python3 "$STREAM_FORMATTER"
+    pipe_statuses=("${PIPESTATUS[@]}")
+    set -e
+    agent_status=${pipe_statuses[0]}
+    fmt_status=${pipe_statuses[1]:-0}
+    if [[ "$fmt_status" -ne 0 ]]; then
+      echo "error: stream formatter exited non-zero ($fmt_status) on iteration $i" >&2
+      exit "$fmt_status"
+    fi
+  fi
+  if [[ "$VERBOSE" != "1" ]]; then
+    set +e
+    "${agent_cmd[@]}" "$prompt"
+    agent_status=$?
+    set -e
+  fi
+  if [[ "$agent_status" -ne 0 ]]; then
+    echo "error: agent exited non-zero ($agent_status) on iteration $i" >&2
+    exit "$agent_status"
+  fi
+
+  if [[ "$PUSH" == "1" ]]; then
+    git push
+  fi
+
+  i=$((i + 1))
+done
+
+echo "=== cursor-agent-loop: finished ${ITERATIONS} iteration(s) ===" >&2

package/scripts/cursor-agent-stream-format.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Pretty-print Cursor Agent CLI stream-json (NDJSON) for humans.
+
+Reads one JSON object per line from stdin; prints assistant text to stdout
+and progress (session, tools) to stderr. See:
+https://cursor.com/docs/cli/reference/output-format
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def _assistant_text(obj: dict) -> str:
+    parts: list[str] = []
+    for block in (obj.get("message") or {}).get("content") or []:
+        if isinstance(block, dict) and block.get("type") == "text":
+            parts.append(str(block.get("text") or ""))
+    return "".join(parts)
+
+
+def _describe_tool_call(tool_call: dict, *, completed: bool) -> str:
+    if not isinstance(tool_call, dict) or not tool_call:
+        return "?"
+
+    if "readToolCall" in tool_call:
+        inner = tool_call["readToolCall"]
+        args = inner.get("args") or {}
+        path = args.get("path", "?")
+        if completed:
+            res = inner.get("result") or {}
+            succ = (res.get("success") or {}) if isinstance(res, dict) else {}
+            lines = succ.get("totalLines")
+            if lines is not None:
+                return f"read {path} ({lines} lines)"
+            return f"read {path} (done)"
+        return f"read {path}"
+
+    if "writeToolCall" in tool_call:
+        inner = tool_call["writeToolCall"]
+        args = inner.get("args") or {}
+        path = args.get("path", "?")
+        if completed:
+            res = inner.get("result") or {}
+            succ = (res.get("success") or {}) if isinstance(res, dict) else {}
+            lines = succ.get("linesCreated")
+            if lines is not None:
+                return f"write {path} (+{lines} lines)"
+            return f"write {path} (done)"
+        return f"write {path}"
+
+    fn = tool_call.get("function")
+    if isinstance(fn, dict):
+        name = fn.get("name") or "function"
+        raw = fn.get("arguments")
+        if isinstance(raw, str):
+            arg_s = raw.replace("\n", " ").strip()
+            if len(arg_s) > 160:
+                arg_s = arg_s[:160] + "…"
+        else:
+            arg_s = json.dumps(raw, default=str) if raw is not None else ""
+            if len(arg_s) > 160:
+                arg_s = arg_s[:160] + "…"
+        return f"{name} {arg_s}".strip()
+
+    for key, inner in tool_call.items():
+        if isinstance(inner, dict) and key.endswith("ToolCall"):
+            label = key[: -len("ToolCall")] or key
+            args = inner.get("args")
+            if isinstance(args, dict):
+                return f"{label} {json.dumps(args, default=str)[:200]}"
+            return f"{label} …"
+
+    return json.dumps(tool_call, default=str)[:200]
+
+
+def main() -> None:
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            o = json.loads(line)
+        except json.JSONDecodeError:
+            print(line, file=sys.stderr, flush=True)
+            continue
+
+        t = o.get("type")
+        if t == "thinking":
+            continue
+        if t == "system":
+            sid = str(o.get("session_id") or "")
+            sid_short = (sid[:8] + "…") if len(sid) > 8 else sid
+            print(
+                f"\n[cursor-agent] session {sid_short}  model={o.get('model', '?')!s}  cwd={o.get('cwd', '')}",
+                file=sys.stderr,
+                flush=True,
+            )
+        elif t == "user":
+            txt = _assistant_text(o)
+            if len(txt) > 600:
+                txt = txt[:600] + "…"
+            print(f"\n[cursor-agent] --- prompt ({len(txt)} chars) ---\n{txt}\n", file=sys.stderr, flush=True)
+        elif t == "assistant":
+            sys.stdout.write(_assistant_text(o))
+            sys.stdout.flush()
+        elif t == "tool_call":
+            sub = o.get("subtype")
+            tc = o.get("tool_call") if isinstance(o.get("tool_call"), dict) else {}
+            desc = _describe_tool_call(tc, completed=(sub == "completed"))
+            if sub == "started":
+                print(f"\n[cursor-agent] tool ▶ {desc}", file=sys.stderr, flush=True)
+            elif sub == "completed":
+                print(f"[cursor-agent] tool ✓ {desc}", file=sys.stderr, flush=True)
+            else:
+                print(f"[cursor-agent] tool {sub!s} {desc}", file=sys.stderr, flush=True)
+        elif t == "result":
+            dur = o.get("duration_ms")
+            err = o.get("is_error")
+            sub = o.get("subtype")
+            print(
+                f"\n[cursor-agent] result  subtype={sub!s}  duration_ms={dur!s}  is_error={err!s}",
+                file=sys.stderr,
+                flush=True,
+            )
+        else:
+            # Forward-compatible: show unknown types lightly
+            print(f"[cursor-agent] event type={t!s}", file=sys.stderr, flush=True)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/next-num.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * next-num — print the next sequential report number (3-digit zero-padded).
+ *
+ * Reads reports/ and returns max(existing) + 1. Used by agents instead of
+ * having the model figure this out by listing + parsing filenames.
+ *
+ * Usage:
+ *   job-forge next-num              # prints e.g. "521"
+ *   job-forge next-num --padded     # prints e.g. "521" (default, already padded)
+ *   job-forge next-num --raw        # prints e.g. "521" without padding
+ */
+
+import { readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
+const REPORTS_DIR = join(PROJECT_DIR, 'reports');
+const RAW = process.argv.includes('--raw');
+
+let max = 0;
+if (existsSync(REPORTS_DIR)) {
+  for (const f of readdirSync(REPORTS_DIR)) {
+    if (!f.endsWith('.md')) continue;
+    const m = f.match(/^(\d+)-/);
+    if (!m) continue;
+    const n = parseInt(m[1], 10);
+    if (n > max) max = n;
+  }
+}
+
+const next = max + 1;
+console.log(RAW ? String(next) : String(next).padStart(3, '0'));

package/scripts/release/check-source.mjs

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const version = process.argv[2];
+
+if (!version) {
+  console.error('Usage: node scripts/release/check-source.mjs <version>');
+  process.exit(1);
+}
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const pkgPath = path.join(root, 'package.json');
+const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+
+if (pkg.version !== version) {
+  console.error(
+    `package.json version ${pkg.version ?? 'unknown'} does not match release tag ${version}. ` +
+      `Bump "version" in package.json, commit, and retag before publishing.`,
+  );
+  process.exit(1);
+}
+
+for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+  const deps = pkg[section];
+  if (!deps) continue;
+  for (const [name, spec] of Object.entries(deps)) {
+    if (typeof spec === 'string' && spec.startsWith('file:')) {
+      console.error(
+        `${section}["${name}"] is "${spec}" — file: deps are published verbatim and break consumers.`,
+      );
+      process.exit(1);
+    }
+  }
+}
+
+console.log(`${pkg.name}: ${pkg.version}`);

package/scripts/render-report-header.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * render-report-header — output the canonical report.md header + `## Score`
+ * section from a score JSON object. Saves the model from re-emitting the
+ * standard boilerplate (header fields, JSON fencing, section labels) on
+ * every evaluation.
+ *
+ * Typical usage from an agent:
+ *
+ *   # 1. Emit the score JSON per _shared.md
+ *   # 2. Save it to /tmp/score.json (or pipe via stdin)
+ *   # 3. Generate the header + score section:
+ *        node scripts/render-report-header.mjs < /tmp/score.json > /tmp/header.md
+ *   # 4. Append Blocks A-F + Extracted Keywords to /tmp/header.md
+ *   # 5. Write the final file to reports/{num}-{slug}-{date}.md
+ *
+ * Input: JSON on stdin (or --score-json <path>) matching the schema in
+ * `modes/_shared.md` → "Score Emission — EMIT-ONCE JSON".
+ *
+ * Output (to stdout): markdown starting with the `# Evaluation:` line and
+ * ending right before `## A) Role Summary` (which the caller appends).
+ */
+
+import { readFileSync } from 'fs';
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i < 0 || i + 1 >= process.argv.length) return null;
+  return process.argv[i + 1];
+}
+
+const scoreFile = arg('score-json');
+let raw;
+if (scoreFile) {
+  raw = readFileSync(scoreFile, 'utf-8');
+} else if (!process.stdin.isTTY) {
+  raw = readFileSync(0, 'utf-8');
+} else {
+  console.error('usage: render-report-header [--score-json <path>] (or pipe JSON via stdin)');
+  process.exit(2);
+}
+
+let score;
+try {
+  score = JSON.parse(raw);
+} catch (e) {
+  console.error(`invalid score JSON: ${e.message}`);
+  process.exit(2);
+}
+
+const required = ['report_num', 'company', 'role', 'archetype', 'url', 'date', 'weighted_total'];
+const missing = required.filter(k => score[k] === undefined);
+if (missing.length) {
+  console.error(`score JSON is missing required fields: ${missing.join(', ')}`);
+  process.exit(2);
+}
+
+const pdfNote = score.pdf_threshold_met ? 'pending' : 'below threshold — no PDF';
+
+process.stdout.write(`# Evaluation: ${score.company} — ${score.role}
+
+**Date:** ${score.date}
+**Archetype:** ${score.archetype}
+**Score:** ${Number(score.weighted_total).toFixed(1)}/5
+**URL:** ${score.url}
+**PDF:** ${pdfNote}
+
+---
+
+## Score
+
+\`\`\`json
+${JSON.stringify(score, null, 2)}
+\`\`\`
+
+---
+
+`);

package/scripts/session-report.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * session-report — print a token/cost summary for the most-recent session(s)
+ * and WARN if any session exceeded the cost budget.
+ *
+ * Ideal for a shell wrapper around `opencode`:
+ *   opencode "$@"
+ *   job-forge session-report --since-minutes 30
+ *
+ * Or at the end of a batch run (already wired into batch-runner.sh).
+ *
+ * Exits 0 always; prints warnings to stderr, summary to stdout.
+ *
+ * Usage:
+ *   job-forge session-report                     # last 1 day
+ *   job-forge session-report --since-minutes 30  # only sessions started in last 30 min
+ *   job-forge session-report --warn-at 1.00      # warn threshold in dollars (default 1.00)
+ *   job-forge session-report --log               # also append to data/token-usage.tsv
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, appendFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const PROJECT_DIR = process.env.JOB_FORGE_PROJECT || process.cwd();
+const OPENCODE = process.env.OPENCODE_BIN || '/Users/charlie/.opencode/bin/opencode';
+
+function arg(name, def = null) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i < 0 || i + 1 >= process.argv.length) return def;
+  return process.argv[i + 1];
+}
+
+const SINCE_MIN = parseInt(arg('since-minutes', '1440'), 10);  // default 24h
+const WARN_AT = parseFloat(arg('warn-at', '1.00'));
+const LOG = process.argv.includes('--log');
+
+const cutoffMs = Date.now() - SINCE_MIN * 60_000;
+
+function query(sql) {
+  const cmd = `cd "${PROJECT_DIR}" && "${OPENCODE}" db "${sql.replace(/"/g, '\\"')}" --format json 2>/dev/null`;
+  try {
+    const out = execSync(cmd, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }).trim();
+    return out ? JSON.parse(out) : [];
+  } catch { return []; }
+}
+
+function fmtNum(n) {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+  return String(n);
+}
+function fmtCost(n) { return `$${n.toFixed(4)}`; }
+
+const sessions = query(`
+  SELECT
+    s.id,
+    s.title,
+    s.time_created,
+    SUM(json_extract(m.data, '$.tokens.input')) as total_input,
+    SUM(json_extract(m.data, '$.tokens.output')) as total_output,
+    SUM(json_extract(m.data, '$.tokens.cache.read')) as total_cache_read,
+    SUM(json_extract(m.data, '$.cost')) as total_cost,
+    COUNT(CASE WHEN json_extract(m.data, '$.tokens.input') > 0 THEN 1 END) as msg_count
+  FROM session s
+  JOIN message m ON m.session_id = s.id
+  WHERE s.time_created >= ${cutoffMs}
+    AND json_extract(m.data, '$.role') = 'assistant'
+  GROUP BY s.id
+  ORDER BY s.time_created DESC
+`);
+
+if (!sessions.length) {
+  console.log(`No sessions in the last ${SINCE_MIN} minutes.`);
+  process.exit(0);
+}
+
+let totalCost = 0;
+let totalMsgs = 0;
+let warned = 0;
+const expensive = [];
+
+console.log(`\nSessions in the last ${SINCE_MIN} minutes (${sessions.length}):`);
+console.log('─'.repeat(80));
+for (const s of sessions) {
+  totalCost += s.total_cost || 0;
+  totalMsgs += s.msg_count || 0;
+  if ((s.total_cost || 0) > WARN_AT) {
+    warned++;
+    expensive.push(s);
+  }
+  const title = (s.title || '(untitled)').slice(0, 50);
+  console.log(
+    `  ${fmtCost(s.total_cost || 0).padStart(9)}  ${title.padEnd(52)}  ${fmtNum(s.total_input || 0).padStart(6)} in, ${fmtNum(s.total_cache_read || 0).padStart(6)} cache, ${String(s.msg_count || 0).padStart(3)} msgs`
+  );
+}
+console.log('─'.repeat(80));
+console.log(`  Total: ${fmtCost(totalCost)} across ${totalMsgs} messages\n`);
+
+if (warned) {
+  console.error(`⚠️  ${warned} session(s) exceeded $${WARN_AT.toFixed(2)} budget:`);
+  for (const s of expensive) {
+    console.error(`   ${fmtCost(s.total_cost || 0)}  ${(s.title || '(untitled)').slice(0, 60)}  (id: ${s.id})`);
+  }
+  console.error(`   Drill in with: npx job-forge tokens --session <id>`);
+  console.error(`   If a single session > $1 shows high cache_creation on most messages,`);
+  console.error(`   the orchestrator likely didn't delegate — tighten AGENTS.md routing.\n`);
+}
+
+if (LOG) {
+  const logFile = join(PROJECT_DIR, 'data', 'token-usage.tsv');
+  const header = 'date\ttime\tsession_id\ttitle\tmessages\tinput_tokens\tcache_read\tcost\n';
+  if (!existsSync(logFile)) writeFileSync(logFile, header, 'utf-8');
+  for (const s of sessions) {
+    const d = new Date(s.time_created);
+    const date = d.toISOString().slice(0, 10);
+    const time = d.toISOString().slice(11, 19);
+    const row = [
+      date, time, s.id,
+      (s.title || '').replace(/\t/g, ' '),
+      s.msg_count || 0,
+      s.total_input || 0,
+      s.total_cache_read || 0,
+      (s.total_cost || 0).toFixed(4),
+    ].join('\t') + '\n';
+    appendFileSync(logFile, row);
+  }
+  console.log(`Logged ${sessions.length} session(s) to ${logFile}`);
+}

package/scripts/slugify.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * slugify — convert a company/role name to a filename-safe slug.
+ *
+ * Rule: lowercase, strip non-alphanumerics (collapse to single hyphens),
+ * trim leading/trailing hyphens. Matches the convention used across
+ * reports/{num}-{slug}-{date}.md.
+ *
+ * Usage:
+ *   job-forge slugify "Anthropic, PBC"           # → anthropic-pbc
+ *   job-forge slugify "OpenAI Co. — Austin"      # → openai-co-austin
+ */
+
+const input = process.argv.slice(2).join(' ').trim();
+if (!input) {
+  console.error('usage: job-forge slugify <name>');
+  process.exit(2);
+}
+
+const slug = input
+  .toLowerCase()
+  .normalize('NFKD')
+  .replace(/[\u0300-\u036f]/g, '')
+  .replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '');
+
+console.log(slug);

package/scripts/today.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * today — print today's date in YYYY-MM-DD (local time).
+ *
+ * Useful because agents sometimes lose track of the current date during
+ * long sessions, or because the shell `date` command differs across
+ * macOS/Linux. This guarantees the exact format used in tracker day
+ * files and report filenames.
+ *
+ * Usage:
+ *   job-forge today            # → 2026-04-15
+ *   job-forge today --utc      # → 2026-04-15 (UTC day — useful for batch logs)
+ */
+
+const UTC = process.argv.includes('--utc');
+const now = new Date();
+const y = UTC ? now.getUTCFullYear()  : now.getFullYear();
+const m = (UTC ? now.getUTCMonth() : now.getMonth()) + 1;
+const d = UTC ? now.getUTCDate()      : now.getDate();
+console.log(`${y}-${String(m).padStart(2,'0')}-${String(d).padStart(2,'0')}`);