issue-flow 0.13.0 → 0.14.0

package/dist/{web-XVHLX62B.js.map → web-EA3KGNFN.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 { 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":[]}
+{"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,6 +1,6 @@
 {
   "name": "issue-flow",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Unified CLI for orchestrating the full issue-flow pipeline via Claude Code, Codex CLI, Cursor CLI or Antigravity CLI",
   "type": "module",
   "bin": {

package/web/AGENTS.md

@@ -36,8 +36,8 @@ do snapshot.
 
 ## Abas, Kanban e drawer
 
-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:
+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:
 
 - **Acesso a story sempre por `getStoryById()` / `getStories()`.** Elas são a
   camada de leitura: normalizam num lugar só o que pode faltar num
@@ -45,7 +45,7 @@ story. Três regras seguram esse conjunto:
   `acceptanceCriteria` → `[]`, `description` → `''`) e são o ponto onde uma
   futura camada de escrita entra. Nenhum consumidor varre `snapshot.stories`
   por conta própria, ou a normalização se espalha.
-- **Estado de UI vive em `state`** (`activeTab`, `selectedStoryId`), junto de
+- **Estado de UI vive em `state`** (`activeTab`, `selectedDetail`), junto de
   `logFilter`, nunca em variável solta ou em referência a nó do DOM. O drawer
   guarda o **id** da story, não o card: `render()` recria o Kanban a cada poll,
   então uma referência guardada na abertura apontaria para um nó fora do
@@ -66,14 +66,153 @@ 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`.
 
-## Escrita: o que ainda não existe
-
-A interface é somente leitura por contrato (`snapshot.readOnly === true`,
-`capabilities: []`), e o servidor não registra nenhuma rota de escrita — o
-comentário em `src/web/server.ts` reserva `POST /api/control/*` para isso. O
-Kanban e o drawer foram desenhados para que a escrita caiba depois sem
-redesenhar a interação: o drawer já é o lugar onde uma story é inspecionada por
-id, e `getStoryById()` já é o único ponto por onde ela é lida.
+## Paleta e tema
+
+As cores do `app.css` são **tokens nomeados por papel**, não por local de uso:
+superfície (`--surface-page`, `--surface`, `--surface-sunken`), texto (`--text`,
+`--text-muted`, `--text-subtle`), borda (`--border`, `--border-strong`), acento
+(`--accent`, `--accent-text`), estado (`--state-ok|run|warn|error` e o
+`--state-*-surface` que acompanha cada um) e `--focus-ring`. Um componente novo
+escolhe o papel que já existe em vez de inventar uma cor.
+
+**Regra dura: nunca defina uma cor só dentro de um `@media` ou de um
+`[data-theme]`.** `:root` carrega a paleta clara inteira; os blocos escuros
+apenas redefinem o que muda. Um token que só existe num deles some no outro
+tema, e o sintoma aparece longe da causa.
+
+O tema escuro vive em **dois blocos gêmeos** com a mesma lista de overrides:
+`@media (prefers-color-scheme: dark) { :root:not([data-theme='light']) { … } }`
+e `:root[data-theme='dark'] { … }`. Mexeu em um, mexa no outro. O guarda
+`:not([data-theme='light'])` é o que faz a escolha manual vencer o sistema nos
+dois sentidos. Cada bloco declara seu próprio `color-scheme` (e `:root`, o
+`light`): é ele — não um `<meta name="color-scheme">`, que foi removido do
+`index.html` justamente por isso — que faz `<select>`, `<progress>` e as barras
+de rolagem acompanharem o tema **efetivo** em vez do tema do SO.
+
+O antigo `--idle-bg` (badge inerte, contagem de coluna do Kanban, hover do
+fechar do drawer, trilha da barra de progresso) virou **`--surface-sunken`**, e
+não um `--state-neutral-surface`: metade dos usos não é badge de estado, e um
+recesso neutro é a mesma coisa nos dois casos. "Sem estado" não é um estado.
+
+O tema é aplicado **antes do primeiro paint** por um `<script>` inline no
+`<head>` do `index.html`, colocado antes do `<link>` do `app.css`: ele lê
+`issue-flow:theme` do `localStorage` e define `data-theme` na raiz. Fora dali
+o reload piscaria a paleta do SO até o `app.js` rodar. Ele é à prova de
+exceção (`try`/`catch`) e não referencia nada do `app.js` — que só carrega no
+fim do `<body>`. Por isso a leitura da chave é **duplicada** entre os dois, com
+comentário nos dois lugares; mudou o formato do valor, mude nos dois.
+
+O controle do tema é um `<select>` de três opções (Sistema/Claro/Escuro)
+**duplicado nos dois headers** (`theme-select` e `theme-select-dashboard`),
+como já acontece com o de intervalo — mudar num reflete no outro via
+`syncThemeSelects()`. As opções são estáticas no HTML (ao contrário de
+`fillRefreshSelect`, que monta as suas); o JS só sincroniza `.value`. A
+preferência vive em `state.theme`, nunca em variável solta, e `'system'`
+**remove** o `data-theme` da raiz em vez de gravar `'system'`: é a ausência do
+atributo que devolve a decisão ao `@media`.
+
+A escolha é persistida em `issue-flow:theme` (`'system' | 'light' | 'dark'`)
+por `readStoredTheme()` / `storeTheme()`, que copiam a forma de
+`readStoredRefresh()` / `storeRefresh()`: leitura e escrita em `try`/`catch`,
+valor ausente ou desconhecido caindo para `'system'`, e **nenhum wrapper
+genérico de storage** — duas chaves não justificam uma abstração. Com o
+armazenamento bloqueado o painel carrega no modo sistema e o `<select>`
+continua alternando o tema na sessão; só não sobrevive ao reload.
+
+No modo `'system'` — e **só** nele — um listener de
+`matchMedia('(prefers-color-scheme: dark)')` fica anexado, para a troca de tema
+do SO chegar ao painel sem reload; `setTheme()` o desanexa quando a escolha
+passa a ser forçada e o reanexa quando volta a `'system'`. O repaint das cores
+em si é do `@media`, que o navegador reavalia sozinho: o listener sincroniza o
+lado JS (raiz e o `.value` dos seletores).
+
+Consequência para o servidor: `baseHeaders()` em `src/web/server.ts` hoje não
+define `Content-Security-Policy`. Se um CSP for adicionado, ele precisa
+contemplar esse script inline (`'unsafe-inline'` em `script-src` ou, melhor, um
+hash/nonce), senão o painel volta a piscar — e um `script-src` estrito sem essa
+provisão quebra a aplicação do tema silenciosamente.
+
+### Contraste: os pares medidos
+
+Os valores abaixo são calculados (WCAG 2.x, luminância relativa), não estimados
+no olho. **Trocar qualquer um destes tokens exige recalcular a linha
+correspondente** — a maior parte da paleta clara passa com pouca folga.
+
+| Frente          | Fundo                   | Mínimo | Claro | Escuro |
+| --------------- | ----------------------- | ------ | ----- | ------ |
+| `--text`        | `--surface-page`        | 4,5:1  | 15,17 | 15,40  |
+| `--text`        | `--surface`             | 4,5:1  | 16,55 | 14,04  |
+| `--text`        | `--surface-sunken`      | 4,5:1  | 13,36 | 11,38  |
+| `--text-muted`  | `--surface-page`        | 4,5:1  | 6,93  | 7,21   |
+| `--text-muted`  | `--surface`             | 4,5:1  | 7,56  | 6,58   |
+| `--text-muted`  | `--surface-sunken`      | 4,5:1  | 6,10  | 5,33   |
+| `--text-subtle` | `--surface-page`        | 4,5:1  | 5,24  | 6,37   |
+| `--text-subtle` | `--surface`             | 4,5:1  | 5,72  | 5,81   |
+| `--text-subtle` | `--surface-sunken`      | 4,5:1  | 4,62  | 4,71   |
+| `--state-ok`    | `--state-ok-surface`    | 4,5:1  | 4,57  | 8,19   |
+| `--state-run`   | `--state-run-surface`   | 4,5:1  | 5,49  | 5,68   |
+| `--state-warn`  | `--state-warn-surface`  | 4,5:1  | 4,51  | 8,05   |
+| `--state-error` | `--state-error-surface` | 4,5:1  | 5,30  | 5,63   |
+| `--focus-ring`  | `--surface-page`        | 3:1    | 5,76  | 6,29   |
+| `--focus-ring`  | `--surface`             | 3:1    | 6,29  | 5,73   |
+| `--focus-ring`  | `--surface-sunken`      | 3:1    | 5,08  | 4,65   |
+| `--accent-text` | `--accent`              | 4,5:1  | 6,29  | 6,29   |
+| `--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
+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
+mais claro que ainda atende 4,5:1 sobre a superfície do próprio badge; `--state-ok`
+(4,57) e `--state-warn` (4,51) passam por pouco. No tema escuro os
+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.
+
+## Como verificar uma mudança aqui
+
+Nada nesta pasta é coberto por teste automatizado, então a verificação é um
+navegador com **dados de verdade**. `python3 -m http.server` dentro de
+`web/public/` basta para inspecionar o CSS, mas o painel fica no estado
+desconectado — não dá para exercitar alertas, Kanban, drawer nem métricas.
+
+Para isso, sirva o servidor real de um `ISSUE_FLOW_HOME` descartável:
+
+1. Escreva um ou mais `session.json` (o schema é `sessionSnapshotSchema` em
+   `src/schemas.ts`) em `<home>/projects/<projeto>/issues/<n>/session.json`,
+   com `events.jsonl` ao lado no formato `{ seq, event }` da aba Histórico.
+   **Duas** sessões abrem o dashboard; uma só abre direto no detalhe.
+2. `npm run build` e `ISSUE_FLOW_HOME=<home> node dist/cli.js web serve --port
+   <p> --host 127.0.0.1`. O servidor lê os assets de `web/public/` (não uma
+   cópia em `dist/`), então basta reiniciá-lo para pegar uma edição.
+3. Uma sessão some após **90s** sem heartbeat: `touch` periódico no
+   `session.json` a mantém viva pelo tempo da verificação.
+
+Os estados que só aparecem sob condição se forçam do console: o `.banner` de
+desconexão, substituindo `window.fetch` por um que rejeita (e restaurando
+depois); o armazenamento bloqueado, com um `Object.defineProperty(window,
+'localStorage', { get() { throw … } })` num script de inicialização; a troca de
+tema do SO, pela emulação de `prefers-color-scheme` do DevTools, que dispara o
+evento `change` real da media query.
+
+Para contraste, **meça na página** (ler os tokens com
+`getComputedStyle(document.documentElement)` e calcular a razão em JS), nunca a
+partir dos valores no arquivo: só assim a cascata resolvida aparece, incluindo
+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