issue-flow 0.12.0 → 0.13.0

package/dist/usage-VCFLDA5Y.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import {
+  groupBy,
+  summarize
+} from "./chunk-CRGIQFUQ.js";
+import {
+  resolveProjectPaths
+} from "./chunk-HQAHNIAR.js";
+import {
+  printError,
+  printInfo
+} from "./chunk-IYV6KNVF.js";
+import {
+  discardedExecutionCount
+} from "./chunk-6FDFRNXZ.js";
+import "./chunk-P3LRUNC6.js";
+import {
+  loadTaskPlan
+} from "./chunk-DIG5XKQQ.js";
+import "./chunk-NEZZ6KDR.js";
+import {
+  getIssuePaths
+} from "./chunk-TX5WIVYP.js";
+import "./chunk-KQHB7ZT3.js";
+import "./chunk-7Z4Y3VKM.js";
+import "./chunk-XEYH6ZZI.js";
+
+// src/commands/usage.ts
+import { readdir } from "fs/promises";
+var USAGE_GROUP_KEYS = [
+  "harness",
+  "provider",
+  "model",
+  "purpose",
+  "status"
+];
+function sinceCutoff(since) {
+  if (since === void 0 || since === "") return null;
+  const parsed = Date.parse(since);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function afterCutoff(records, cutoff) {
+  if (cutoff === null) return [...records];
+  return records.filter((record) => Date.parse(record.startedAt) >= cutoff);
+}
+function formatUsd(amount) {
+  return `$${amount.toFixed(2)}`;
+}
+function formatCost(summary) {
+  const parts = [];
+  if (summary.totalCost.reported > 0 || summary.totalCost.estimated === 0) {
+    if (summary.count > 0 && summary.totalCost.unknownExecutions < summary.count) {
+      parts.push(`${formatUsd(summary.totalCost.reported)} reportado`);
+    }
+  }
+  if (summary.totalCost.estimated > 0) {
+    parts.push(`${formatUsd(summary.totalCost.estimated)} estimado`);
+  }
+  if (summary.totalCost.unknownExecutions > 0) {
+    parts.push(`\u2014 desconhecido (${summary.totalCost.unknownExecutions})`);
+  }
+  return parts.length === 0 ? "\u2014" : parts.join(" \xB7 ");
+}
+function formatTokens(summary) {
+  const total = summary.usage.inputTokens + summary.usage.outputTokens;
+  if (total >= 1e6) return `${(total / 1e6).toFixed(1)}M`;
+  if (total >= 1e3) return `${(total / 1e3).toFixed(1)}k`;
+  return String(total);
+}
+function successRate(summary) {
+  if (summary.count === 0) return "\u2014";
+  const ok = summary.byStatus.completed ?? 0;
+  return `${(ok / summary.count * 100).toFixed(1)}%`;
+}
+async function loadPlans(issue) {
+  let project;
+  try {
+    project = await resolveProjectPaths();
+  } catch (err) {
+    printError(`Not inside a usable project: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  if (issue !== void 0) {
+    try {
+      const paths = getIssuePaths(project.projectId, issue);
+      return [{ id: issue, plan: await loadTaskPlan(paths.tasksFile) }];
+    } catch (err) {
+      printError(
+        `No telemetry for issue ${issue}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return null;
+    }
+  }
+  let ids;
+  try {
+    ids = await readdir(project.issuesDir);
+  } catch {
+    return [];
+  }
+  const loaded = [];
+  for (const id of ids) {
+    try {
+      loaded.push({
+        id,
+        plan: await loadTaskPlan(getIssuePaths(project.projectId, id).tasksFile)
+      });
+    } catch {
+    }
+  }
+  return loaded;
+}
+function buildUsageReport(plans, options, discarded = 0) {
+  const cutoff = sinceCutoff(options.since);
+  const records = plans.flatMap(({ plan }) => afterCutoff(plan.executions ?? [], cutoff));
+  const total = summarize(records, discarded);
+  const groups = options.by === void 0 ? [] : [...groupBy(records, options.by)].map(([key, summary]) => ({ key, summary }));
+  return {
+    issue: options.issue ?? (plans.length === 1 ? plans[0]?.id ?? null : null),
+    since: options.since ?? null,
+    by: options.by ?? null,
+    discarded,
+    total,
+    groups
+  };
+}
+function formatUsageReport(report) {
+  if (report.total.count === 0) {
+    return "No execution telemetry recorded yet.";
+  }
+  const header = [
+    report.issue === null ? "project" : `issue #${report.issue}`,
+    `${report.total.count} execu\xE7\xE3o${report.total.count === 1 ? "" : "\xF5es"}`,
+    formatCost(report.total)
+  ].join(" \xB7 ");
+  if (report.by === null || report.groups.length === 0) {
+    return header;
+  }
+  const rows = report.groups.map((group) => {
+    const name = group.key.padEnd(14);
+    const count = String(group.summary.count).padStart(10);
+    const success = successRate(group.summary).padStart(8);
+    const tokens = formatTokens(group.summary).padStart(8);
+    return `${name}${count}${success}${tokens.padStart(10)}  ${formatCost(group.summary)}`;
+  });
+  const columns = `${report.by.padEnd(14)}${"execu\xE7\xF5es".padStart(10)}${"sucesso".padStart(8)}${"tokens".padStart(10)}  custo`;
+  return [`${header}`, columns, ...rows].join("\n");
+}
+async function runUsage(issue, options = {}) {
+  const plans = await loadPlans(issue ?? options.issue);
+  if (plans === null) return 1;
+  if (options.since !== void 0 && sinceCutoff(options.since) === null) {
+    printError(`Invalid --since date: ${options.since}`);
+    return 1;
+  }
+  const report = buildUsageReport(plans, { ...options, issue: issue ?? options.issue });
+  if (plans.length === 0 || report.total.count === 0 && (issue ?? options.issue) !== void 0) {
+    printInfo("No execution telemetry recorded yet.");
+    return 0;
+  }
+  if (options.json === true) {
+    printInfo(JSON.stringify(report, null, 2));
+    return 0;
+  }
+  printInfo(formatUsageReport(report));
+  return 0;
+}
+export {
+  USAGE_GROUP_KEYS,
+  buildUsageReport,
+  discardedExecutionCount,
+  formatUsageReport,
+  runUsage
+};
+//# sourceMappingURL=usage-VCFLDA5Y.js.map

package/dist/usage-VCFLDA5Y.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/usage.ts"],"sourcesContent":["import { readdir } from 'node:fs/promises';\nimport { loadTaskPlan } from '../core/state-manager.js';\nimport { getIssuePaths } from '../storage/paths.js';\nimport { resolveProjectPaths } from '../storage/resolve.js';\nimport { type GroupKey, groupBy, summarize } from '../telemetry/aggregate.js';\nimport { discardedExecutionCount } from '../telemetry/recorder.js';\nimport type { ExecutionRecord, ExecutionSummary } from '../telemetry/types.js';\nimport type { TaskPlan } from '../types.js';\nimport { printError, printInfo } from '../ui/logger.js';\n\nexport const USAGE_GROUP_KEYS = [\n  'harness',\n  'provider',\n  'model',\n  'purpose',\n  'status',\n] as const satisfies readonly GroupKey[];\n\nexport type UsageGroupKey = (typeof USAGE_GROUP_KEYS)[number];\n\nexport interface UsageOptions {\n  issue?: string;\n  since?: string;\n  by?: UsageGroupKey;\n  json?: boolean;\n}\n\nexport interface UsageReport {\n  issue: string | null;\n  since: string | null;\n  by: UsageGroupKey | null;\n  discarded: number;\n  total: ExecutionSummary;\n  groups: Array<{ key: string; summary: ExecutionSummary }>;\n}\n\nfunction sinceCutoff(since: string | undefined): number | null {\n  if (since === undefined || since === '') return null;\n  const parsed = Date.parse(since);\n  return Number.isNaN(parsed) ? null : parsed;\n}\n\nfunction afterCutoff(\n  records: readonly ExecutionRecord[],\n  cutoff: number | null,\n): ExecutionRecord[] {\n  if (cutoff === null) return [...records];\n  return records.filter((record) => Date.parse(record.startedAt) >= cutoff);\n}\n\nfunction formatUsd(amount: number): string {\n  return `$${amount.toFixed(2)}`;\n}\n\nfunction formatCost(summary: ExecutionSummary): string {\n  const parts: string[] = [];\n  if (summary.totalCost.reported > 0 || summary.totalCost.estimated === 0) {\n    if (summary.count > 0 && summary.totalCost.unknownExecutions < summary.count) {\n      parts.push(`${formatUsd(summary.totalCost.reported)} reportado`);\n    }\n  }\n  if (summary.totalCost.estimated > 0) {\n    parts.push(`${formatUsd(summary.totalCost.estimated)} estimado`);\n  }\n  if (summary.totalCost.unknownExecutions > 0) {\n    parts.push(`— desconhecido (${summary.totalCost.unknownExecutions})`);\n  }\n  return parts.length === 0 ? '—' : parts.join(' · ');\n}\n\nfunction formatTokens(summary: ExecutionSummary): string {\n  const total = summary.usage.inputTokens + summary.usage.outputTokens;\n  if (total >= 1_000_000) return `${(total / 1_000_000).toFixed(1)}M`;\n  if (total >= 1_000) return `${(total / 1_000).toFixed(1)}k`;\n  return String(total);\n}\n\nfunction successRate(summary: ExecutionSummary): string {\n  if (summary.count === 0) return '—';\n  const ok = summary.byStatus.completed ?? 0;\n  return `${((ok / summary.count) * 100).toFixed(1)}%`;\n}\n\nasync function loadPlans(\n  issue: string | undefined,\n): Promise<{ id: string; plan: TaskPlan }[] | null> {\n  let project: Awaited<ReturnType<typeof resolveProjectPaths>>;\n  try {\n    project = await resolveProjectPaths();\n  } catch (err) {\n    printError(`Not inside a usable project: ${err instanceof Error ? err.message : String(err)}`);\n    return null;\n  }\n\n  if (issue !== undefined) {\n    try {\n      const paths = getIssuePaths(project.projectId, issue);\n      return [{ id: issue, plan: await loadTaskPlan(paths.tasksFile) }];\n    } catch (err) {\n      printError(\n        `No telemetry for issue ${issue}: ${err instanceof Error ? err.message : String(err)}`,\n      );\n      return null;\n    }\n  }\n\n  let ids: string[];\n  try {\n    ids = await readdir(project.issuesDir);\n  } catch {\n    return [];\n  }\n\n  const loaded: { id: string; plan: TaskPlan }[] = [];\n  for (const id of ids) {\n    try {\n      loaded.push({\n        id,\n        plan: await loadTaskPlan(getIssuePaths(project.projectId, id).tasksFile),\n      });\n    } catch {\n      // An issue without a readable plan is not telemetry.\n    }\n  }\n  return loaded;\n}\n\nexport function buildUsageReport(\n  plans: { id: string; plan: TaskPlan }[],\n  options: UsageOptions,\n  discarded = 0,\n): UsageReport {\n  const cutoff = sinceCutoff(options.since);\n  const records = plans.flatMap(({ plan }) => afterCutoff(plan.executions ?? [], cutoff));\n  const total = summarize(records, discarded);\n  const groups =\n    options.by === undefined\n      ? []\n      : [...groupBy(records, options.by)].map(([key, summary]) => ({ key, summary }));\n  return {\n    issue: options.issue ?? (plans.length === 1 ? (plans[0]?.id ?? null) : null),\n    since: options.since ?? null,\n    by: options.by ?? null,\n    discarded,\n    total,\n    groups,\n  };\n}\n\nexport function formatUsageReport(report: UsageReport): string {\n  if (report.total.count === 0) {\n    return 'No execution telemetry recorded yet.';\n  }\n\n  const header = [\n    report.issue === null ? 'project' : `issue #${report.issue}`,\n    `${report.total.count} execução${report.total.count === 1 ? '' : 'ões'}`,\n    formatCost(report.total),\n  ].join(' · ');\n\n  if (report.by === null || report.groups.length === 0) {\n    return header;\n  }\n\n  const rows = report.groups.map((group) => {\n    const name = group.key.padEnd(14);\n    const count = String(group.summary.count).padStart(10);\n    const success = successRate(group.summary).padStart(8);\n    const tokens = formatTokens(group.summary).padStart(8);\n    return `${name}${count}${success}${tokens.padStart(10)}  ${formatCost(group.summary)}`;\n  });\n  const columns = `${report.by.padEnd(14)}${'execuções'.padStart(10)}${'sucesso'.padStart(8)}${'tokens'.padStart(10)}  custo`;\n  return [`${header}`, columns, ...rows].join('\\n');\n}\n\nexport async function runUsage(\n  issue: string | undefined,\n  options: UsageOptions = {},\n): Promise<number> {\n  const plans = await loadPlans(issue ?? options.issue);\n  if (plans === null) return 1;\n\n  if (options.since !== undefined && sinceCutoff(options.since) === null) {\n    printError(`Invalid --since date: ${options.since}`);\n    return 1;\n  }\n\n  const report = buildUsageReport(plans, { ...options, issue: issue ?? options.issue });\n  if (plans.length === 0 || (report.total.count === 0 && (issue ?? options.issue) !== undefined)) {\n    printInfo('No execution telemetry recorded yet.');\n    return 0;\n  }\n\n  if (options.json === true) {\n    printInfo(JSON.stringify(report, null, 2));\n    return 0;\n  }\n\n  printInfo(formatUsageReport(report));\n  return 0;\n}\n\nexport { discardedExecutionCount };\n"],"mappings":"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","names":[]}

package/dist/{web-EF5WIIGG.js → web-XVHLX62B.js}

@@ -1,34 +1,47 @@
 #!/usr/bin/env node
+import {
+  readSessionFile
+} from "./chunk-SNTTOQAD.js";
 import {
   ensureSingleWebServer,
   getWebLockFile,
   readWebLock,
   removeWebLock
-} from "./chunk-FJP3UQGD.js";
-import "./chunk-BAUPQXPE.js";
-import "./chunk-LAFNLLQP.js";
+} from "./chunk-IHIEXUTC.js";
+import "./chunk-MIVHK5YI.js";
 import {
-  loadWebConfig
-} from "./chunk-42PJFMAR.js";
+  parseJournal
+} from "./chunk-QCXPNSEL.js";
 import {
-  ISSUES_DIR_NAME,
-  PROJECTS_DIR_NAME,
-  getGlobalRoot
-} from "./chunk-DIDUVL6O.js";
+  loadWebConfig
+} from "./chunk-CNBYCMSU.js";
+import "./chunk-HQAHNIAR.js";
 import {
   printError,
   printInfo,
   printWarning
-} from "./chunk-BYZDPR7N.js";
+} from "./chunk-IYV6KNVF.js";
+import "./chunk-6FDFRNXZ.js";
+import "./chunk-P3LRUNC6.js";
+import "./chunk-DIG5XKQQ.js";
+import "./chunk-NEZZ6KDR.js";
 import {
-  sessionSnapshotSchema
-} from "./chunk-CD5ULRVC.js";
+  EVENTS_FILENAME,
+  ISSUES_DIR_NAME,
+  PROJECTS_DIR_NAME,
+  ROTATED_EVENTS_FILENAME,
+  SESSION_FILENAME,
+  getGlobalRoot
+} from "./chunk-TX5WIVYP.js";
+import "./chunk-KQHB7ZT3.js";
+import "./chunk-7Z4Y3VKM.js";
+import "./chunk-XEYH6ZZI.js";
 
 // src/web/session-directory.ts
-import { readdir, readFile, stat as statFile } from "fs/promises";
+import { readdir, readFile } from "fs/promises";
 import { join } from "path";
 var DEFAULT_POLL_INTERVAL_MS = 3e3;
-var DEFAULT_STALE_AFTER_MS = 3e4;
+var DEFAULT_STALE_AFTER_MS = 9e4;
 async function listSubdirectories(dir) {
   try {
     const entries = await readdir(dir, { withFileTypes: true });
@@ -44,27 +57,16 @@ async function discoverSessionFiles(root) {
     projectIds.map(async (projectId) => {
       const issuesDir = join(projectsDir, projectId, ISSUES_DIR_NAME);
       const issueIds = await listSubdirectories(issuesDir);
-      return issueIds.map((issueId) => join(issuesDir, issueId, "session.json"));
+      return issueIds.map((issueId) => join(issuesDir, issueId, SESSION_FILENAME));
     })
   );
   return perProject.flat();
 }
-async function readSessionFile(filePath) {
-  let raw;
-  let mtimeMs;
-  try {
-    const [content, stat] = await Promise.all([readFile(filePath, "utf-8"), statFile(filePath)]);
-    raw = content;
-    mtimeMs = stat.mtimeMs;
-  } catch {
-    return null;
-  }
+async function readJournalFile(filePath) {
   try {
-    const parsed = sessionSnapshotSchema.safeParse(JSON.parse(raw));
-    if (!parsed.success || parsed.data.sessionId === null) return null;
-    return { snapshot: parsed.data, updatedAtMs: mtimeMs };
+    return parseJournal(await readFile(filePath, "utf-8"));
   } catch {
-    return null;
+    return [];
   }
 }
 function watchSessionDirectory(options = {}) {
@@ -109,6 +111,15 @@ function watchSessionDirectory(options = {}) {
   return {
     sessions: () => [...sessions.values()],
     getSession: (sessionId) => sessions.get(sessionId),
+    events: async (sessionId) => {
+      const session = sessions.get(sessionId);
+      if (session === void 0) return void 0;
+      const [rotated, current] = await Promise.all([
+        readJournalFile(join(session.issueDir, ROTATED_EVENTS_FILENAME)),
+        readJournalFile(join(session.issueDir, EVENTS_FILENAME))
+      ]);
+      return [...rotated, ...current];
+    },
     refresh: scan,
     close: () => clearInterval(timer)
   };
@@ -190,4 +201,4 @@ export {
   runWebServe,
   runWebStop
 };
-//# sourceMappingURL=web-EF5WIIGG.js.map
+//# sourceMappingURL=web-XVHLX62B.js.map

package/dist/web-XVHLX62B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/web/session-directory.ts","../src/commands/web.ts"],"sourcesContent":["import { readdir, readFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { type JournalEntry, parseJournal } from '../core/journal.js';\nimport type { ValidatedSessionSnapshot } from '../schemas.js';\nimport {\n  EVENTS_FILENAME,\n  type GetGlobalRootOptions,\n  getGlobalRoot,\n  ISSUES_DIR_NAME,\n  PROJECTS_DIR_NAME,\n  ROTATED_EVENTS_FILENAME,\n  SESSION_FILENAME,\n} from '../storage/paths.js';\nimport { readSessionFile } from '../storage/session-file.js';\n\n/**\n * Multi-session discovery for the web monitoring server (US-003).\n *\n * The single-instance server (`web/lock.ts`) runs decoupled from any one\n * pipeline invocation, so it cannot hold a `SessionPublisher` in memory for\n * \"the\" run being monitored — there may be zero, one or several running at\n * once, each in its own process. Instead this module polls every\n * `~/.issue-flow/projects/<project>/issues/<n>/session.json` on disk (the\n * same file `FilePublisher` already writes) and keeps an in-memory map of the\n * ones that are both well-formed and recently updated.\n *\n * Polling rather than `fs.watch` is a deliberate choice, not a placeholder:\n * `fs.watch`'s `recursive` option is only reliable on macOS and Windows (Linux\n * needs a manual per-directory watch tree, and the whole thing still degrades\n * to polling on network filesystems), while a `~/.issue-flow` tree is small\n * and local — a cheap poll of it is simpler and behaves identically on every\n * platform, which is what the US-003 acceptance criteria ask to validate.\n */\n\n/** How often the directory tree is rescanned, unless overridden. */\nexport const DEFAULT_POLL_INTERVAL_MS = 3000;\n\n/**\n * A session stops being reported once its file has gone this long without an\n * update. `FilePublisher` touches a live session every 10s without rewriting\n * its content. Three missed heartbeats plus ample scheduling/filesystem slack\n * avoid flapping while still removing an abruptly killed run promptly.\n */\nexport const DEFAULT_STALE_AFTER_MS = 90_000;\n\nexport interface ActiveSession {\n  /** Directory the session.json was read from, one level up from the file. */\n  issueDir: string;\n  filePath: string;\n  snapshot: ValidatedSessionSnapshot;\n  /** mtime of the file at the last successful read, in epoch ms. */\n  updatedAtMs: number;\n}\n\nexport interface SessionDirectoryOptions extends GetGlobalRootOptions {\n  /** Poll interval, in ms. Default {@link DEFAULT_POLL_INTERVAL_MS}. */\n  pollIntervalMs?: number;\n  /** Staleness threshold, in ms. Default {@link DEFAULT_STALE_AFTER_MS}. */\n  staleAfterMs?: number;\n  /** Invoked (at most once) when a poll fails unexpectedly. Best-effort logging only. */\n  onWarn?: (message: string) => void;\n}\n\nexport interface SessionDirectoryHandle {\n  /** Snapshot of every session currently considered active. */\n  sessions(): ActiveSession[];\n  /** A single active session by id, or undefined. */\n  getSession(sessionId: string): ActiveSession | undefined;\n  /** Journal entries for one active session, oldest generation first. */\n  events(sessionId: string): Promise<JournalEntry[] | undefined>;\n  /** Force an immediate rescan instead of waiting for the next tick. Never throws. */\n  refresh(): Promise<void>;\n  /** Stop polling. Idempotent. */\n  close(): void;\n}\n\nasync function listSubdirectories(dir: string): Promise<string[]> {\n  try {\n    const entries = await readdir(dir, { withFileTypes: true });\n    // Symlinks are skipped on purpose, same discipline as the storage\n    // migration walk: following one could pull session data from outside the\n    // global tree into the listing.\n    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);\n  } catch {\n    // Missing/unreadable projects (or issues) directory reads as \"none yet\" —\n    // this is routinely the case before the first --web run ever happens.\n    return [];\n  }\n}\n\n/** Every `session.json` path currently on disk, one per project/issue pair. */\nasync function discoverSessionFiles(root: string): Promise<string[]> {\n  const projectsDir = join(root, PROJECTS_DIR_NAME);\n  const projectIds = await listSubdirectories(projectsDir);\n\n  const perProject = await Promise.all(\n    projectIds.map(async (projectId) => {\n      const issuesDir = join(projectsDir, projectId, ISSUES_DIR_NAME);\n      const issueIds = await listSubdirectories(issuesDir);\n      return issueIds.map((issueId) => join(issuesDir, issueId, SESSION_FILENAME));\n    }),\n  );\n\n  return perProject.flat();\n}\n\nasync function readJournalFile(filePath: string): Promise<JournalEntry[]> {\n  try {\n    return parseJournal(await readFile(filePath, 'utf-8'));\n  } catch {\n    return [];\n  }\n}\n\n/**\n * Start polling the global storage tree for active sessions.\n *\n * Returns a handle immediately; the first scan happens synchronously in the\n * background and `sessions()` answers `[]` until it completes, same as \"no\n * sessions found yet\" — there is nothing to await here that would not also\n * delay the server's very first bind.\n */\nexport function watchSessionDirectory(\n  options: SessionDirectoryOptions = {},\n): SessionDirectoryHandle {\n  const root = getGlobalRoot(options);\n  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;\n  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;\n  const warn = options.onWarn;\n\n  // Keyed by sessionId, not by file path: a session's identity is the id\n  // inside its content, and that is what /api/status?session=<id> looks up.\n  let sessions = new Map<string, ActiveSession>();\n  let warned = false;\n\n  async function scan(): Promise<void> {\n    let files: string[];\n    try {\n      files = await discoverSessionFiles(root);\n    } catch (err) {\n      if (!warned) {\n        warned = true;\n        warn?.(\n          `issue-flow: web monitor could not scan the session directory (will keep retrying silently): ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        );\n      }\n      return;\n    }\n\n    const now = Date.now();\n    const next = new Map<string, ActiveSession>();\n    for (const filePath of files) {\n      const result = await readSessionFile(filePath);\n      if (result === null) continue;\n      if (now - result.updatedAtMs > staleAfterMs) continue; // stopped updating: not active\n      const sessionId = result.snapshot.sessionId as string;\n      next.set(sessionId, {\n        issueDir: join(filePath, '..'),\n        filePath,\n        snapshot: result.snapshot,\n        updatedAtMs: result.updatedAtMs,\n      });\n    }\n    sessions = next;\n  }\n\n  // The first scan runs immediately (not just after the first interval tick)\n  // so a server started right after a session begins does not report \"no\n  // sessions\" for a whole poll interval.\n  void scan();\n  const timer = setInterval(() => void scan(), pollIntervalMs);\n  timer.unref();\n\n  return {\n    sessions: () => [...sessions.values()],\n    getSession: (sessionId: string) => sessions.get(sessionId),\n    events: async (sessionId: string) => {\n      const session = sessions.get(sessionId);\n      if (session === undefined) return undefined;\n      const [rotated, current] = await Promise.all([\n        readJournalFile(join(session.issueDir, ROTATED_EVENTS_FILENAME)),\n        readJournalFile(join(session.issueDir, EVENTS_FILENAME)),\n      ]);\n      return [...rotated, ...current];\n    },\n    refresh: scan,\n    close: () => clearInterval(timer),\n  };\n}\n","import { loadWebConfig } from '../config.js';\nimport type { WebConfig } from '../schemas.js';\nimport { printError, printInfo, printWarning } from '../ui/logger.js';\nimport { ensureSingleWebServer, getWebLockFile, readWebLock, removeWebLock } from '../web/lock.js';\nimport { watchSessionDirectory } from '../web/session-directory.js';\n\n/**\n * `issue-flow web serve` / `issue-flow web stop` (US-002).\n *\n * `serve` is the process `ensureWebMonitor()` (`web/lock.ts`) spawns detached\n * — it is not meant to be run interactively, though nothing stops a user from\n * doing so to watch every session on the machine without going through a\n * pipeline command first. It never exits on its own: the server stays bound\n * (see `unref: false` in `web/server.ts`) until `stop` sends it `SIGTERM`, at\n * which point `startWebServer`'s own signal handler closes it (removing the\n * lock) and re-raises the signal for the default termination behavior.\n */\n\nconst STOP_POLL_INTERVAL_MS = 100;\nconst STOP_TIMEOUT_MS = 5000;\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport interface RunWebServeOptions {\n  port?: number;\n  host?: string;\n  refresh?: number;\n}\n\n/**\n * Bind (or defer to) the single web monitor instance and keep the process\n * alive for as long as it stays bound. Logging is intentionally silent on the\n * happy path: this process is spawned with `stdio: 'ignore'`, so anything\n * printed here goes nowhere — the caller (`ensureWebMonitor`) is the one that\n * tells the user the server is up.\n */\nexport async function runWebServe(options: RunWebServeOptions): Promise<number> {\n  // Built conditionally, not `{ port: options.port, ... }`: loadWebConfig()\n  // spreads this object directly over the lower-precedence layers, and an\n  // explicit `undefined` value would overwrite an env/.issue-flow.json\n  // setting instead of falling through to it (only an *absent* key does).\n  const cli: Partial<WebConfig> = {};\n  if (options.port !== undefined) cli.port = options.port;\n  if (options.host !== undefined) cli.host = options.host;\n  if (options.refresh !== undefined) cli.refreshSeconds = options.refresh;\n  const webConfig = await loadWebConfig({ cli });\n\n  const sessions = watchSessionDirectory();\n\n  const noop = (): void => {};\n  const handle = await ensureSingleWebServer({\n    sessions,\n    port: webConfig.port,\n    host: webConfig.host,\n    refreshSeconds: webConfig.refreshSeconds,\n    unref: false,\n    info: noop,\n    warn: noop,\n  });\n\n  if (handle === null) {\n    sessions.close();\n    return 1;\n  }\n\n  if (handle.server === undefined) {\n    // Another instance already won the race (or was already running by the\n    // time this process got here): nothing to serve, so it exits right away\n    // instead of idling as a redundant detached process.\n    sessions.close();\n    return 0;\n  }\n\n  const originalClose = handle.close;\n  handle.close = async () => {\n    await originalClose();\n    sessions.close();\n  };\n\n  return 0;\n}\n\n/** Stop the single running web monitor instance, if any. */\nexport async function runWebStop(): Promise<number> {\n  const lockFile = getWebLockFile();\n  const lock = await readWebLock(lockFile);\n  if (lock === null) {\n    printInfo('No web monitor is currently running.');\n    return 0;\n  }\n\n  try {\n    process.kill(lock.pid, 'SIGTERM');\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === 'ESRCH') {\n      printWarning(\n        'The web monitor lock referenced a process that is no longer running; removing it.',\n      );\n      await removeWebLock(lockFile);\n      return 0;\n    }\n    printError(\n      `Failed to stop the web monitor: ${err instanceof Error ? err.message : String(err)}`,\n    );\n    return 1;\n  }\n\n  const deadline = Date.now() + STOP_TIMEOUT_MS;\n  while (Date.now() < deadline) {\n    if ((await readWebLock(lockFile)) === null) {\n      printInfo(`Web monitor (pid ${lock.pid}) stopped.`);\n      return 0;\n    }\n    await sleep(STOP_POLL_INTERVAL_MS);\n  }\n\n  printWarning('Sent the stop signal, but the web monitor did not confirm shutdown in time.');\n  return 0;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "issue-flow",
-  "version": "0.12.0",
-  "description": "Unified CLI for orchestrating the full issue-flow pipeline via Claude Code Headless",
+  "version": "0.13.0",
+  "description": "Unified CLI for orchestrating the full issue-flow pipeline via Claude Code, Codex CLI, Cursor CLI or Antigravity CLI",
   "type": "module",
   "bin": {
     "issue-flow": "./dist/cli.js"
@@ -12,6 +12,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "smoke": "bash scripts/smoke-issue-providers.sh",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
@@ -34,6 +35,9 @@
     "ai",
     "agent",
     "claude",
+    "codex",
+    "cursor",
+    "antigravity",
     "automation",
     "cli",
     "pipeline",

package/prompts/execute.md

@@ -10,7 +10,7 @@ You are an autonomous coding agent working on a software project.
 4. Treat the issue as unresolved if **any** `userStories[].passes` is `false`, **or** if the PRD's top-level `lastReviewFindings` is non-null — that second condition holds even when every story already passes (see "Correction Findings from a Failed Review" below).
 5. If `lastReviewFindings` is non-null, address it first (see below); otherwise pick the **highest priority** user story where `passes: false`
 6. Implement that single user story
-7. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+7. Run the quality checks that cover the files you changed (typecheck/lint/test for those paths). The orchestrator runs the full suite at the end of execute and again in review.
 8. Update CLAUDE.md files if you discover reusable patterns (see below)
 9. If checks pass, commit ALL changes with message: `__COMMIT_MESSAGE__`
 10. Update the PRD to set `passes: true` for the completed story
@@ -35,14 +35,14 @@ APPEND to `__PROGRESS_FILE__` (never replace, always append):
 ## [Date/Time] - [Story ID]
 - What was implemented
 - Files changed
-- **Learnings for future iterations:**
+- **Learnings for future iterations:** (omit this block when the iteration discovered nothing reusable)
   - Patterns discovered (e.g., "this codebase uses X for Y")
   - Gotchas encountered (e.g., "don't forget to update Z when changing W")
   - Useful context (e.g., "the evaluation panel is in component X")
 ---
 ```
 
-The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+The learnings section is required only when the iteration discovered something reusable. Do not invent patterns.
 
 ## Consolidate Patterns
 
@@ -130,7 +130,7 @@ If you need to stop for user guidance or another non-transient blocker, record i
 
 ## Important
 
-- Work on ONE story per iteration
+- Work on ONE story per iteration unless `__STORIES_PER_ITERATION__` is greater than 1, in which case you may close that many related stories that touch the same files, in one session. The default is 1.
 - Commit frequently
 - Keep CI green
 - Read the Codebase Patterns section in `__PROGRESS_FILE__` before starting
@@ -157,8 +157,7 @@ a decision depends on what they say.
 
 This repository declares: __COMMIT_CONVENTION__
 
-`<type>` in the commit message above is for you to choose, and it must match the
-**nature of the change** — `fix` for a bug fix, `docs` for documentation, `test`,
-`refactor`, `chore`, `feat` for a new capability. Committing a bug fix as `feat`
-corrupts the changelog and any version bump computed from the history.
+The commit message above is already in the resolved format. If you must pick a
+`<type>` inside that format, choose from the repository's vocabulary and match
+the **nature of this commit** — never invent a type outside it.
 <!-- /if -->

package/prompts/plan.md

@@ -30,7 +30,7 @@ Create a tasks.json file at __TASKS_PATH__ with this exact structure:
   "project": "<repo-name>",
   "issueNumber": __ISSUE_NUMBER__,
   "issueUrl": "__ISSUE_URL__",
-  "branchName": "<branch, following __BRANCH_CONVENTION__ with N=__ISSUE_NUMBER__>",
+  "branchName": "__BRANCH_NAME__",
   "description": "<brief description>",
   "issueStatus": "pending",
   "completedAt": null,
@@ -71,7 +71,7 @@ Rules:
   and never derive it yourself
 - Get the repo name from the repository itself (package name, directory name)
 - If __ISSUE_NUMBER__ is not a number, keep it as a JSON string in issueNumber
-- The branchName should use a short kebab-case slug derived from the issue title
+- branchName is already resolved: use __BRANCH_NAME__ verbatim. Do not invent a branch.
 
 IMPORTANT: You MUST write the tasks.json to the file path above. Do not just output it.
 
@@ -94,6 +94,5 @@ a decision depends on what they say.
 
 ## Branch naming
 
-`branchName` must follow `__BRANCH_CONVENTION__`, where `{N}` is the issue number
-and `{slug}` a short kebab-case summary of the issue title. A repository that
-declares its own convention above overrides this one.
+`branchName` is `__BRANCH_NAME__`. Copy it exactly. The CLI computed it from the
+repository convention; do not slugify the title yourself.

package/prompts/pr.md

@@ -27,7 +27,7 @@ Steps:
 5. Create a well-structured PR using gh pr create
 
 The PR should:
-- Have a clear, concise title (under 70 characters)
+- Use this title verbatim: `__PR_TITLE_CONVENTION__`
 - Include a summary of changes
 - Include a test plan
 - Cite where the demand is described: the reference above (`__ISSUE_URL__`)
@@ -36,7 +36,7 @@ Issue reference line(s):
 - Include the lines below verbatim in the PR body, each entry on its own line,
   with no surrounding code fence or quoting — GitHub only auto-closes an issue
   when the `Closes #N` line is plain body text:
-__ISSUE_CLOSES__
+__ISSUE_REFERENCE__
 - When nothing follows the line above, the issue has no GitHub counterpart: do
   NOT invent a "Closes #" reference, and cite `__ISSUE_URL__` in the body instead
 

package/web/AGENTS.md

@@ -10,7 +10,7 @@ vitest. Toda verificação de mudança aqui é manual, no navegador.
 
 O painel consome `GET api/sessions` (lista enriquecida para o dashboard),
 `GET api/status` (o `SessionSnapshot` serializado, opcionalmente com
-`?session=<id>`) e `GET api/health`. Ele precisa renderizar **session.json de
+`?session=<id>`), `GET api/events?session=<id>` (journal) e `GET api/health`. Ele precisa renderizar **session.json de
 execuções antigas**, então todo campo pode chegar como `undefined` (não
 existia na versão que gravou o arquivo) além do `null` (existe, não
 informado). Os dois significam "não informado" e nunca podem virar `0`,
@@ -36,7 +36,7 @@ do snapshot.
 
 ## Abas, Kanban e drawer
 
-O painel tem duas abas ("Execução" e "Kanban") e um drawer de detalhes por
+O painel tem três abas ("Execução", "Kanban" e "Histórico") e um drawer de detalhes por
 story. Três regras seguram esse conjunto:
 
 - **Acesso a story sempre por `getStoryById()` / `getStories()`.** Elas são a
@@ -51,7 +51,7 @@ story. Três regras seguram esse conjunto:
   então uma referência guardada na abertura apontaria para um nó fora do
   documento. Pelo mesmo motivo o foco volta ao card via
   `[data-story-id="…"]` no momento de fechar.
-- **`renderKanban()` e `renderDrawer()` são chamadas incondicionalmente** dentro
+- **`renderKanban()`, `renderHistory()` e `renderDrawer()` são chamadas incondicionalmente** dentro
   de `render()`, não ao trocar de aba. Uma aba inativa não pode ficar defasada,
   e é o `renderDrawer()` de cada poll que mantém o drawer aberto em dia (e o
   fecha quando a story some do plano).

package/web/public/app.css

@@ -47,6 +47,10 @@
   box-sizing: border-box;
 }
 
+[hidden] {
+  display: none !important;
+}
+
 body {
   margin: 0;
   background: var(--bg);
@@ -454,6 +458,34 @@ progress {
   border-bottom: 1px solid var(--border);
 }
 
+.plain-list .history-entry {
+  align-items: flex-start;
+}
+
+.history-type {
+  flex: 0 0 9rem;
+  color: var(--muted);
+}
+
+.history-message {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+@media (max-width: 560px) {
+  .plain-list .history-entry {
+    flex-wrap: wrap;
+  }
+
+  .history-type {
+    flex-basis: auto;
+  }
+
+  .history-message {
+    flex-basis: 100%;
+  }
+}
+
 .plain-list li:last-child {
   border-bottom: none;
 }
@@ -904,6 +936,12 @@ progress {
   font: inherit;
   cursor: pointer;
   display: grid;
+  /* O grid externo estica os cards de uma linha para a mesma altura. Sem isto,
+     `align-content: stretch` distribui a sobra entre as faixas — inclusive a do
+     resumo — e a faixa fica mais alta que as 3 linhas do clamp, deixando vazar
+     uma 4ª linha cortada por baixo do reticente. Empacotar no topo manda a
+     sobra para o fim do card, que é onde ela não engana ninguém. */
+  align-content: start;
   gap: 10px;
   transition: border-color 0.15s ease, box-shadow 0.15s ease;
 }