issue-flow 0.16.0 → 0.18.0

package/dist/run-2RXJCJKT.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import {
+  publishIssueDetails,
+  publishStorySeed,
+  runPipeline
+} from "./chunk-CWSQVHVV.js";
+import "./chunk-QJ44VG5G.js";
+import "./chunk-OODXFCQV.js";
+import "./chunk-LTH6XYZ3.js";
+import "./chunk-YUNBOUQH.js";
+import "./chunk-XUEMATVY.js";
+import "./chunk-EG2MGDP5.js";
+import "./chunk-7UMMFOL2.js";
+import "./chunk-PMLE7KAQ.js";
+import "./chunk-KRAGAUKD.js";
+import "./chunk-NEWNXZ65.js";
+import "./chunk-ECU7YO7S.js";
+import "./chunk-E4I6MMHD.js";
+import "./chunk-CRGIQFUQ.js";
+import "./chunk-L6HSKTQE.js";
+import "./chunk-45WZ6GMI.js";
+import "./chunk-HOAHMERN.js";
+import "./chunk-34OCSKOB.js";
+import "./chunk-V7QOIQYC.js";
+import "./chunk-SA6HXL4Y.js";
+import "./chunk-62GVVZQO.js";
+import "./chunk-KMMASOA6.js";
+import "./chunk-KMCS76ZW.js";
+import "./chunk-7F7LGMVO.js";
+import "./chunk-TZYINKCC.js";
+import "./chunk-WCCZJL7W.js";
+import "./chunk-DGRTJD5R.js";
+import "./chunk-ZVZMWNCG.js";
+import "./chunk-C5TL7T4V.js";
+import "./chunk-3D4A4B46.js";
+import "./chunk-LGHND47K.js";
+import "./chunk-QF7VEL3M.js";
+import "./chunk-LI35PIIS.js";
+import "./chunk-XZUEFTUP.js";
+import "./chunk-QPGEFLMY.js";
+import "./chunk-HAKDLR6N.js";
+import "./chunk-YVPZUN6X.js";
+import "./chunk-DUS5ZNKL.js";
+import "./chunk-6K2LCFG6.js";
+import "./chunk-PPZ3K4YM.js";
+import "./chunk-SOM4QA6C.js";
+import "./chunk-ICM463EO.js";
+import "./chunk-XEYH6ZZI.js";
+import "./chunk-P3LRUNC6.js";
+import "./chunk-3R27MJ5R.js";
+export {
+  publishIssueDetails,
+  publishStorySeed,
+  runPipeline
+};
+//# sourceMappingURL=run-2RXJCJKT.js.map

package/dist/{session-publisher-VVXOCJ2S.js → session-publisher-KAJQRHNZ.js}

@@ -2,10 +2,11 @@
 import {
   getSessionPublisher,
   setSessionPublisher
-} from "./chunk-ROIIEVZH.js";
+} from "./chunk-DUS5ZNKL.js";
 import "./chunk-P3LRUNC6.js";
+import "./chunk-3R27MJ5R.js";
 export {
   getSessionPublisher,
   setSessionPublisher
 };
-//# sourceMappingURL=session-publisher-VVXOCJ2S.js.map
+//# sourceMappingURL=session-publisher-KAJQRHNZ.js.map

package/dist/{state-manager-TIC73GQY.js → state-manager-UPHO2EA2.js}

@@ -14,9 +14,9 @@ import {
   selectActiveStory,
   setLastError,
   trimErrorMessage
-} from "./chunk-GVOZ6NDO.js";
-import "./chunk-QVLIIGBU.js";
-import "./chunk-7Z4Y3VKM.js";
+} from "./chunk-SOM4QA6C.js";
+import "./chunk-ICM463EO.js";
+import "./chunk-3R27MJ5R.js";
 export {
   allStoriesPass,
   applyStoryMetrics,
@@ -33,4 +33,4 @@ export {
   setLastError,
   trimErrorMessage
 };
-//# sourceMappingURL=state-manager-TIC73GQY.js.map
+//# sourceMappingURL=state-manager-UPHO2EA2.js.map

package/dist/state-manager-UPHO2EA2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{usage-WDDNSIHP.js → usage-KTMYXAPF.js}

@@ -5,28 +5,28 @@ import {
 } from "./chunk-CRGIQFUQ.js";
 import {
   resolveProjectPaths
-} from "./chunk-VTF4RWS5.js";
+} from "./chunk-LI35PIIS.js";
 import {
   printError,
   printInfo
-} from "./chunk-SVDEWOUD.js";
-import "./chunk-ROIIEVZH.js";
-import "./chunk-FKWYD44M.js";
+} from "./chunk-XZUEFTUP.js";
+import "./chunk-QPGEFLMY.js";
 import {
   getIssuePaths
 } from "./chunk-HAKDLR6N.js";
-import "./chunk-WNROH2YE.js";
+import "./chunk-YVPZUN6X.js";
+import "./chunk-DUS5ZNKL.js";
 import {
   discardedExecutionCount
-} from "./chunk-GPLP7EPL.js";
-import "./chunk-P3LRUNC6.js";
-import "./chunk-R42YHLDV.js";
+} from "./chunk-6K2LCFG6.js";
+import "./chunk-PPZ3K4YM.js";
 import {
   loadTaskPlan
-} from "./chunk-GVOZ6NDO.js";
-import "./chunk-QVLIIGBU.js";
-import "./chunk-7Z4Y3VKM.js";
+} from "./chunk-SOM4QA6C.js";
+import "./chunk-ICM463EO.js";
 import "./chunk-XEYH6ZZI.js";
+import "./chunk-P3LRUNC6.js";
+import "./chunk-3R27MJ5R.js";
 
 // src/commands/usage.ts
 import { readdir } from "fs/promises";
@@ -174,4 +174,4 @@ export {
   formatUsageReport,
   runUsage
 };
-//# sourceMappingURL=usage-WDDNSIHP.js.map
+//# sourceMappingURL=usage-KTMYXAPF.js.map

package/dist/{web-IPGY52AK.js → web-B5UPHHR5.js}

@@ -1,24 +1,25 @@
 #!/usr/bin/env node
 import {
   readSessionFile
-} from "./chunk-G5LACAXO.js";
+} from "./chunk-RYOUZ6EK.js";
 import {
   ensureSingleWebServer,
   stopWebMonitor
-} from "./chunk-YA6FWFYW.js";
-import "./chunk-PGN2VX4Y.js";
-import "./chunk-OGVWJO4S.js";
+} from "./chunk-NEWNXZ65.js";
+import "./chunk-45WZ6GMI.js";
+import "./chunk-HOAHMERN.js";
+import "./chunk-7F7LGMVO.js";
 import {
   parseJournal
-} from "./chunk-IAMIBZRF.js";
+} from "./chunk-WCCZJL7W.js";
+import "./chunk-ZVZMWNCG.js";
 import "./chunk-C5TL7T4V.js";
 import {
   loadWebConfig
-} from "./chunk-J2LJB2OH.js";
-import "./chunk-VTF4RWS5.js";
-import "./chunk-SVDEWOUD.js";
-import "./chunk-ROIIEVZH.js";
-import "./chunk-FKWYD44M.js";
+} from "./chunk-QF7VEL3M.js";
+import "./chunk-LI35PIIS.js";
+import "./chunk-XZUEFTUP.js";
+import "./chunk-QPGEFLMY.js";
 import {
   EVENTS_FILENAME,
   ISSUES_DIR_NAME,
@@ -27,14 +28,15 @@ import {
   SESSION_FILENAME,
   getGlobalRoot
 } from "./chunk-HAKDLR6N.js";
-import "./chunk-WNROH2YE.js";
-import "./chunk-GPLP7EPL.js";
-import "./chunk-P3LRUNC6.js";
-import "./chunk-R42YHLDV.js";
-import "./chunk-GVOZ6NDO.js";
-import "./chunk-QVLIIGBU.js";
-import "./chunk-7Z4Y3VKM.js";
+import "./chunk-YVPZUN6X.js";
+import "./chunk-DUS5ZNKL.js";
+import "./chunk-6K2LCFG6.js";
+import "./chunk-PPZ3K4YM.js";
+import "./chunk-SOM4QA6C.js";
+import "./chunk-ICM463EO.js";
 import "./chunk-XEYH6ZZI.js";
+import "./chunk-P3LRUNC6.js";
+import "./chunk-3R27MJ5R.js";
 
 // src/web/session-directory.ts
 import { readdir, readFile } from "fs/promises";
@@ -167,4 +169,4 @@ export {
   runWebServe,
   runWebStop
 };
-//# sourceMappingURL=web-IPGY52AK.js.map
+//# sourceMappingURL=web-B5UPHHR5.js.map

package/dist/{web-IPGY52AK.js.map → web-B5UPHHR5.js.map}

@@ -1 +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 { ensureSingleWebServer, stopWebMonitor } 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\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 webConfig = await loadWebConfig();\n  const result = await stopWebMonitor({ port: webConfig.port, host: webConfig.host });\n  return result === 'failed' || result === 'unowned' ? 1 : 0;\n}\n"],"mappings":"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","names":[]}
+{"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 { ensureSingleWebServer, stopWebMonitor } 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\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 webConfig = await loadWebConfig();\n  const result = await stopWebMonitor({ port: webConfig.port, host: webConfig.host });\n  return result === 'failed' || result === 'unowned' ? 1 : 0;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issue-flow",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Unified CLI for orchestrating the full issue-flow pipeline via Claude Code, Codex CLI, Cursor CLI or Antigravity CLI",
   "type": "module",
   "bin": {
@@ -14,10 +14,11 @@
     "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/",
-    "format": "biome format --write src/",
-    "check": "biome check --write src/ && tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "check": "biome check . && tsc --noEmit",
+    "fix": "biome check --write . && tsc --noEmit",
     "prepack": "npm run build",
     "prepublishOnly": "npm run lint && npm run typecheck && npm test",
     "preversion": "node scripts/git-version.mjs check",

package/web/AGENTS.md

@@ -46,7 +46,9 @@ do snapshot.
 ## Abas, Kanban e drawer
 
 O painel tem três abas ("Execução", "Kanban" e "Histórico") e um único drawer de detalhes
-para fases e stories (inclusive cards do Kanban). Três regras seguram esse conjunto:
+para fases e stories (inclusive cards do Kanban). As abas seguem o padrão ARIA de
+tablist: setas ←/→ movem o foco, Home/End vão às pontas, e só a aba ativa tem
+`tabindex="0"` (as demais `-1`). Três regras seguram esse conjunto:
 
 - **Acesso a story sempre por `getStoryById()` / `getStories()`.** Elas são a
   camada de leitura: normalizam num lugar só o que pode faltar num
@@ -75,6 +77,110 @@ grid`/`flex` da regra base vence o atributo `hidden`. E o overlay/drawer ficam
 em `z-index` 20/21 para cobrir o `.banner` de desconexão, que é `sticky` com
 `z-index: 10`.
 
+## Header: informação, não marca
+
+O `h1` das duas views **não** carrega o nome do produto — a marca vive só no
+`<title>` do documento, que `renderTitle()`/`renderDashboard()` mantêm no
+formato `<contexto> · issue-flow`. No detalhe o `h1` é a execução (`#N` como
+link para a issue, seguido do título dela); no dashboard é "Execuções ativas".
+Não devolva "issue-flow" para dentro do `h1`: a linha mais visível da tela é
+para o que está acontecendo.
+
+O resto da identidade da execução fica ao redor do `h1`: branch e chip de
+versão na `.header-meta` logo abaixo, status, tempo decorrido e estimativa no
+`.header-side`. O título da issue aparece **uma vez só** — por isso
+`renderIssueSummary()` não repete número nem título no bloco "Contexto",
+deixando ali estado, labels e descrição.
+
+Layout: `.header-main` é `flex: 1 1 320px` e o `.header-side` fica com o
+`flex` padrão (`0 1 auto`). O `.header-side` **precisa** poder encolher — os
+timers são largos e, fixados em `flex: 0 0 auto`, estouram a largura em 360px.
+O `h1` é fluxo inline (não flex), senão um título longo empurra o `#N` para
+uma linha sozinha.
+
+## Blocos da aba Execução
+
+A aba "Execução" tem **quatro** cartões, nesta ordem, e a ordem é a hierarquia:
+
+| Bloco | O que carrega |
+| --- | --- |
+| Estado agora | progresso, "Executando agora", "Resiliência" e a linha "Próximos passos" |
+| Contexto | issue, repositório e "Harnesses e configuração efetiva" |
+| Andamento | fases e user stories |
+| Saída | commits, pull requests e logs recentes |
+
+Cada assunto dentro de um bloco é uma `.block-part` com `<h3>` — **sem borda,
+sem fundo, sem sombra própria**: quem separa é o `gap` do grid de `.block`.
+Assunto novo entra como `.block-part` de um bloco existente; um cartão novo na
+aba só se justifica se não couber em nenhum dos quatro. Foi a proliferação de
+cartões de mesmo peso (doze deles) que a issue #98 desfez, e ela volta sozinha
+se cada mudança acrescentar "só mais um".
+
+"Estado agora" é o único bloco com um requisito de layout: precisa caber sem
+rolagem em 1440x900 **com o cartão de erros e avisos aberto**. Antes de
+acrescentar linha ali, meça (`getBoundingClientRect().bottom <= innerHeight`).
+
+A partir de 960px o `#panel-execution` vira um grid de duas colunas: Contexto
+fica ao lado de Estado agora / Andamento, e Saída ocupa a largura toda. Os
+dois breakpoints do painel são 640px (estreito) e 960px (largo) — um
+componente novo se encaixa nesses, não inventa o terceiro. `main` tem
+`max-width: 1200px`. Sem rolagem horizontal em 360, 768 e 1440.
+
+"Contexto" roda um degrau abaixo (`--font-size-md` em todo o bloco): é
+referência, não estado. "Próximos passos" é uma linha só — `renderNextSteps()`
+junta os passos com `·` num `<span>`, e o rótulo vem do HTML
+(`.next-steps-label`), não do JS.
+
+## Glossário
+
+Termos da interface — um por conceito, em todo `index.html` e `app.js` visível
+ao usuário. Comentários de código podem falar a língua do domínio (`session`,
+`story`); a tela não.
+
+| Conceito | Termo na UI | Não usar |
+| --- | --- | --- |
+| Uma corrida do pipeline | **execução** / **execuções** | sessão (exceto no identificador técnico, e mesmo aí o rótulo é "execução `<id>`") |
+| Item do plano | **user story** / **user stories** | story, stories, User Story misturado |
+| Estado da corrida | **aguardando / executando / concluído / falhou** | sinônimos soltos no badge |
+| Indicador de corrida ativa | **ao vivo** + `.live` | "live", segundo badge, ponto com uppercase |
+
+Travessão (`—`) fica só em placeholders de valor ausente (`#—`, timers). Em
+frase, use ponto ou vírgula: "Desconectado do servidor. Tentando reconectar…",
+"Execução falhou. Veja os erros acima."
+
+O título do drawer é o da user story (`US-00N · título`) ou `Fase · <nome>`,
+nunca "Detalhes da user story".
+
+## Escalas de tipografia, espaçamento e raio
+
+Ao lado das cores, `:root` declara três escalas **fechadas**. Um componente
+novo escolhe um degrau que já existe; não introduz um valor local.
+
+| Escala | Tokens |
+| --- | --- |
+| Tipografia | `--font-size-xs` 0.75rem · `sm` 0.8125 · `md` 0.875 · `base` 0.9375 · `lg` 1 · `xl` 1.25 |
+| Espaçamento | `--space-4` · `--space-8` · `--space-12` · `--space-16` · `--space-24` |
+| Raio | `--radius-small` 6px · `--radius-medium` 10px · `--radius-pill` 999px |
+
+`--font-size-base` é o tamanho do `body`; `xl` é o `h1` e `lg` o `h2`. O
+espaçamento cobre `gap`, `padding` e `margin` — os quatro valores de rem que
+existiam (`0.65rem`, `0.75rem`, `0.8rem`, `1rem`) foram arredondados para o
+degrau mais próximo, e é isso que se faz com qualquer valor novo. Raio:
+`medium` para superfícies com cara de cartão (`.card`, `.kanban-card`,
+`.kanban-column`, `.execution-entry`), `small` para linhas, controles e caixas
+internas, `pill` para badges, trilhas de progresso e pontos — inclusive no
+lugar do antigo `border-radius: 50%`.
+
+**Três exceções, e só elas**, cada uma com comentário no `app.css`: o
+`margin-bottom: -1px` das abas (compensa a borda, é alinhamento), o `gap: 1px`
+de `.config-phase-grid` (o fundo `--border` vazando pelo gap é a linha
+divisória) e o `calc(var(--space-12) - 3px)` de `.story-executing` (desconta a
+`box-shadow` interna para preservar o ritmo). Um valor solto sem um motivo
+dessa ordem é dívida — troque pelo degrau.
+
+Múltiplos são escritos como `calc()` sobre um token (`calc(var(--space-24) *
+2)` no rodapé do `main`), não como um sexto token de espaçamento.
+
 ## Paleta e tema
 
 As cores do `app.css` são **tokens nomeados por papel**, não por local de uso:
@@ -169,7 +275,7 @@ correspondente** — a maior parte da paleta clara passa com pouca folga.
 | `--accent-text` | `--state-error`         | 4,5:1  | 6,47  | 6,78   |
 
 O limiar dos badges de estado é **4,5:1 e não 3:1** porque `.badge` é
-`font-size: 0.78rem; font-weight: 600` — abaixo do que a WCAG chama de texto
+`font-size: var(--font-size-sm); font-weight: 600` — abaixo do que a WCAG chama de texto
 grande. Já `--focus-ring` é um componente gráfico, não texto: 3:1 basta.
 
 No tema claro as quatro cores de estado ficam no nível 700 da escala — é o tom
@@ -178,11 +284,13 @@ mais claro que ainda atende 4,5:1 sobre a superfície do próprio badge; `--stat
 preenchimentos sólidos são claros, então `--accent-text` inverte para
 `#0f1218`: era branco sobre `--state-error` no banner de desconexão, 2,98:1.
 
-Hover e foco por teclado precisam ser **distinguíveis um do outro**. Em
-`.dashboard-card` o hover só acende a borda (`--accent`); o foco desenha
-`outline: 2px solid var(--focus-ring)` com `outline-offset: 2px`, que continua
-visível em cima do hover. É a única regra do `app.css` que mexe em `outline` —
-antes ela o suprimia e dava a mesma aparência aos dois estados.
+Hover e foco por teclado precisam ser **distinguíveis um do outro**. Uma
+única regra `:focus-visible` compartilhada desenha `outline: 2px solid
+var(--focus-ring)` com `outline-offset: 2px` em todo interativo (abas, cards
+do dashboard e do Kanban, `<select>`s, fechar do drawer, "Todas as execuções",
+linhas de fase/story). O hover só muda cor, borda ou fundo — nunca o anel.
+Inclusive em `.dashboard-card.is-live`, que já tem `border-color` própria: o
+foco precisa do outline, não de outra troca de borda.
 
 ## Como verificar uma mudança aqui
 
@@ -217,17 +325,16 @@ o token que um tema herda do outro por engano.
 
 ## Escrita limitada a preferências futuras
 
-O estado de execução continua somente leitura (`snapshot.readOnly === true`). A
-única mutação é `POST /api/config/agent`, que salva preferência global para
-execuções **futuras**, aparece via capability e só funciona em loopback. Nunca
-inferir permissão pela versão: o client renderiza o formulário apenas quando
-`/api/health.capabilities` contém `config:agent:write`.
-
-Quando essa etapa chegar, o contrato esperado é: as rotas de escrita passam a
-ser anunciadas em `capabilities` (o client decide o que renderizar a partir
-disso, nunca da versão do servidor), `readOnly` passa a `false`, e cada
-mutação responde com o snapshot atualizado para que a UI não precise adivinhar
-o efeito nem esperar o próximo poll. Enquanto `capabilities` estiver vazio,
+O estado de execução continua somente leitura (`snapshot.readOnly === true`). As
+únicas mutações são `POST /api/config/agent` e `POST /api/config/routing`, que
+salvam preferências globais para execuções **futuras**, aparecem via capability
+e só funcionam em loopback. Nunca inferir permissão pela versão: o client
+renderiza os formulários apenas quando `/api/health.capabilities` anuncia as
+duas capacidades correspondentes.
+
+Cada mutação responde com `{ ok, file, appliesTo: 'future executions' }`; o
+client atualiza a preferência viva no próximo `GET /api/config`, sem jamais
+alterar o snapshot da execução. Enquanto as capabilities estiverem ausentes,
 nenhum controle de escrita deve aparecer na tela.
 
 ## Métricas (tokens e custo)