quadwork 1.3.0 → 1.5.0

package/server/routes.js

@@ -267,6 +267,18 @@ router.put("/api/loop-guard", async (req, res) => {
   if (!tomlPath || !fs.existsSync(tomlPath)) {
     return res.status(404).json({ error: "config.toml not found for project" });
   }
+  // Capture the previous value before rewriting so we can decide
+  // whether the /continue auto-resume should fire (only when the
+  // operator is RAISING the limit — lowering it means they want
+  // the runaway loop to stay paused).
+  let previousValue = null;
+  try {
+    const previousContent = fs.readFileSync(tomlPath, "utf-8");
+    const prevMatch = previousContent.match(/^\s*max_agent_hops\s*=\s*(\d+)/m);
+    if (prevMatch) previousValue = parseInt(prevMatch[1], 10);
+  } catch {
+    // fall through — previousValue stays null, auto-resume will skip
+  }
   try {
     let content = fs.readFileSync(tomlPath, "utf-8");
     if (/^\s*max_agent_hops\s*=/m.test(content)) {
@@ -289,14 +301,77 @@ router.put("/api/loop-guard", async (req, res) => {
   // /api/chat does (#230): re-sync the session token from AC and
   // retry once. Other failures stay non-fatal — the persisted value
   // still takes effect on next AC restart.
+  //
+  // #417 / quadwork#309: the update_settings ws event correctly
+  // updates router.max_hops in the running AC (verified in AC's
+  // app.py:1249), AND writes settings.json via _save_settings. But
+  // AC's router stays paused once it has tripped the guard — raising
+  // max_hops at runtime does NOT resurrect an already-paused channel
+  // (router.py:76-77 → `paused = True`). The operator typically
+  // raises the limit precisely BECAUSE the channel is stuck paused,
+  // so we immediately follow the update_settings event with a
+  // `/continue` chat message (the same path AC's own slash command
+  // handler uses at app.py:1106-1110) to resume routing. This is the
+  // whole fix: the previous version updated max_hops live but left
+  // the channel frozen, which made the widget look like a no-op.
   let live = false;
+  let autoResumed = false;
+  // Only auto-resume when ALL of:
+  //   (a) operator is RAISING the limit (lowering = "make it
+  //       stricter", must leave a paused runaway alone)
+  //   (b) the router is currently paused (AC's continue_routing
+  //       resets hop_count + paused + guard_emitted unconditionally,
+  //       so firing it on an actively-running chain would silently
+  //       extend the chain beyond the new limit — t2a finding)
+  //   (c) previousValue is known (null means we can't prove it's a
+  //       raise, so err on the side of not touching router state)
+  const isRaising = previousValue !== null && value > previousValue;
+  const ensureLive = async (sessionToken) => {
+    await sendWsEvent(base, sessionToken, { type: "update_settings", data: { max_agent_hops: value } });
+    if (isRaising) {
+      // Check AC's /api/status before firing /continue so we don't
+      // reset hop_count on a running (unpaused) chain. The endpoint
+      // exposes `paused: true` iff ANY channel currently paused.
+      let isPaused = false;
+      try {
+        // AC's security middleware (app.py:212-224) only accepts
+        // bearer auth for /api/messages, /api/send, and /api/rules/*.
+        // /api/status requires x-session-token header (or ?token=),
+        // so pass that instead — a bearer header silently 403s and
+        // leaves isPaused stuck at false, defeating the gate.
+        const statusUrl = `${base}/api/status`;
+        const statusRes = await fetch(statusUrl, {
+          headers: sessionToken ? { "x-session-token": sessionToken } : {},
+          signal: AbortSignal.timeout(5000),
+        });
+        if (statusRes.ok) {
+          const statusJson = await statusRes.json();
+          isPaused = !!(statusJson && statusJson.paused);
+        }
+      } catch {
+        // Status fetch failed — err toward "don't auto-resume". The
+        // operator can always type /continue manually.
+      }
+      if (isPaused) {
+        // Resume paused channels. /continue is routed by AC's ws
+        // message handler when the buffer starts with /continue;
+        // the handler calls router.continue_routing() which
+        // unpauses AND resets hop_count — which is why we gate on
+        // isPaused to avoid wiping the counter on a live chain.
+        await sendWsEvent(base, sessionToken, { type: "message", text: "/continue", channel: "general", sender: "user" });
+        autoResumed = true;
+      }
+    }
+    live = true;
+  };
+  let base = null;
   try {
-    const { url: base, token: sessionToken } = getChattrConfig(projectId);
+    const chattr = getChattrConfig(projectId);
+    base = chattr.url;
+    const sessionToken = chattr.token;
     if (base) {
-      const event = { type: "update_settings", data: { max_agent_hops: value } };
       try {
-        await sendWsEvent(base, sessionToken, event);
-        live = true;
+        await ensureLive(sessionToken);
       } catch (err) {
         if (err && err.code === "EAGENTCHATTR_401") {
           console.warn(`[loop-guard] ws auth failed for ${projectId}, re-syncing session token and retrying...`);
@@ -305,8 +380,7 @@ router.put("/api/loop-guard", async (req, res) => {
           const { token: refreshed } = getChattrConfig(projectId);
           if (refreshed && refreshed !== sessionToken) {
             try {
-              await sendWsEvent(base, refreshed, event);
-              live = true;
+              await ensureLive(refreshed);
             } catch (retryErr) {
               console.warn(`[loop-guard] retry after token resync failed: ${retryErr.message || retryErr}`);
             }
@@ -320,7 +394,7 @@ router.put("/api/loop-guard", async (req, res) => {
     console.warn(`[loop-guard] live update failed for ${projectId}: ${err.message || err}`);
   }
 
-  res.json({ ok: true, value, live });
+  res.json({ ok: true, value, live, previousValue, resumed: autoResumed });
 });
 
 // #412 / quadwork#279: project history export + import.
@@ -532,6 +606,214 @@ router.post("/api/project-history", async (req, res) => {
   res.json({ ok: errors.length === 0, imported, skipped, total: body.messages.length, errors });
 });
 
+// #424 / quadwork#304 Phase 4: list + restore auto-snapshots.
+// snapshotProjectHistory() in server/index.js writes envelope
+// files to ~/.quadwork/{id}/history-snapshots/{ISO}.json before
+// destructive restart/update operations. These endpoints let the
+// Project History widget surface them with a restore button so
+// the operator can roll back a bad /clear or botched update.
+router.get("/api/project-history/snapshots", (req, res) => {
+  const projectId = req.query.project;
+  if (!projectId) return res.status(400).json({ error: "Missing project" });
+  const snapDir = path.join(CONFIG_DIR, projectId, "history-snapshots");
+  if (!fs.existsSync(snapDir)) return res.json({ snapshots: [] });
+  try {
+    const entries = fs.readdirSync(snapDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => {
+        const st = fs.statSync(path.join(snapDir, f));
+        return { name: f, size: st.size, mtime: st.mtimeMs };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+    res.json({ snapshots: entries });
+  } catch (err) {
+    res.status(500).json({ error: "Failed to list snapshots", detail: err.message });
+  }
+});
+
+router.post("/api/project-history/restore", async (req, res) => {
+  const projectId = req.query.project;
+  const name = req.query.name || req.body?.name;
+  if (!projectId || !name) return res.status(400).json({ error: "Missing project or name" });
+  // Prevent path traversal — only allow basenames from the snapshot
+  // directory; reject anything with a separator or ".." segment.
+  if (name !== path.basename(name) || name.includes("..") || !name.endsWith(".json")) {
+    return res.status(400).json({ error: "Invalid snapshot name" });
+  }
+  const snapPath = path.join(CONFIG_DIR, projectId, "history-snapshots", name);
+  if (!fs.existsSync(snapPath)) {
+    return res.status(404).json({ error: "Snapshot not found" });
+  }
+  let body;
+  try {
+    const text = fs.readFileSync(snapPath, "utf-8");
+    body = JSON.parse(text);
+  } catch (err) {
+    return res.status(500).json({ error: "Failed to read snapshot", detail: err.message });
+  }
+  // Post the snapshot back through the existing import endpoint
+  // with both bypass flags — the snapshot contains real agent
+  // senders (so allow_agent_senders) and may match a previous
+  // restore's exported_at (so allow_duplicate). This is the
+  // legitimate disaster-recovery case the #297 denylist expected.
+  try {
+    const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+    const qwPort = cfg.port || 8400;
+    const r = await fetch(`http://127.0.0.1:${qwPort}/api/project-history?project=${encodeURIComponent(projectId)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ...body, allow_agent_senders: true, allow_duplicate: true }),
+    });
+    const data = await r.json().catch(() => null);
+    if (!r.ok) {
+      return res.status(r.status).json(data || { error: `import returned ${r.status}` });
+    }
+    res.json({ ok: true, ...(data || {}) });
+  } catch (err) {
+    res.status(502).json({ error: "Restore failed", detail: err.message });
+  }
+});
+
+// #430 / quadwork#312: AI team work-hours tracking.
+//
+// The frontend's TerminalGrid detects per-agent activity transitions
+// (idle → active, active → idle) via the existing activity ref and
+// POSTs them to /api/activity/log. We buffer `start` events in
+// memory keyed by `${project}/${agent}`; an `end` event looks up the
+// matching buffered start, computes the duration, and appends a
+// complete session row to ~/.quadwork/{project}/activity.jsonl.
+//
+// /api/activity/stats aggregates across all projects with a 30s
+// cache so the dashboard can poll it every minute without thrashing
+// the filesystem.
+
+const _activityStarts = new Map(); // `${project}/${agent}` → startTimestamp
+const _activityStatsCache = { ts: 0, data: null };
+const ACTIVITY_STATS_TTL_MS = 30000;
+
+function activityLogPath(projectId) {
+  return path.join(CONFIG_DIR, projectId, "activity.jsonl");
+}
+
+router.post("/api/activity/log", (req, res) => {
+  const { project, agent, type, timestamp } = req.body || {};
+  if (typeof project !== "string" || !project) return res.status(400).json({ error: "Missing project" });
+  if (typeof agent !== "string" || !agent) return res.status(400).json({ error: "Missing agent" });
+  if (type !== "start" && type !== "end") return res.status(400).json({ error: "type must be start|end" });
+  const ts = typeof timestamp === "number" && Number.isFinite(timestamp) ? timestamp : Date.now();
+  const key = `${project}/${agent}`;
+
+  if (type === "start") {
+    // Only remember the first start per session — duplicate starts
+    // are possible if the frontend re-mounts mid-stream; ignore
+    // them so the session duration reflects the original onset.
+    if (!_activityStarts.has(key)) _activityStarts.set(key, ts);
+    return res.json({ ok: true });
+  }
+
+  // type === "end"
+  const start = _activityStarts.get(key);
+  if (start === undefined) {
+    // Orphan end (missed start — probably happens on server
+    // restart while a session was live). Drop it silently so we
+    // don't write a row with an unknown start timestamp.
+    return res.json({ ok: true, dropped: "orphan" });
+  }
+  _activityStarts.delete(key);
+  const row = { agent, start, end: ts, duration_ms: Math.max(0, ts - start) };
+  try {
+    const p = activityLogPath(project);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(row) + "\n");
+    // Invalidate the stats cache so the next read sees the new row.
+    _activityStatsCache.ts = 0;
+  } catch (err) {
+    console.warn(`[activity] failed to append ${project}/${agent}: ${err.message || err}`);
+  }
+  res.json({ ok: true, duration_ms: row.duration_ms });
+});
+
+// Aggregate all activity.jsonl files under ~/.quadwork/*/activity.jsonl.
+// `today`, `week`, `month` boundaries use the operator's local
+// timezone rather than UTC — "this week" should mean the week the
+// operator is living in, not a UTC-offset week that starts at
+// 16:00 local time.
+function computeActivityStats() {
+  if (Date.now() - _activityStatsCache.ts < ACTIVITY_STATS_TTL_MS && _activityStatsCache.data) {
+    return _activityStatsCache.data;
+  }
+  const now = new Date();
+  const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+  // Start of this week = local Monday 00:00. JS: getDay() → 0-Sun..6-Sat.
+  const day = now.getDay();
+  const mondayOffset = day === 0 ? -6 : 1 - day; // Sun → -6, Mon → 0, Tue → -1, …
+  const startOfWeek = new Date(now.getFullYear(), now.getMonth(), now.getDate() + mondayOffset).getTime();
+  const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+
+  const totals = { today_ms: 0, week_ms: 0, month_ms: 0, total_ms: 0 };
+  const byProject = {};
+  // #430 / quadwork#312: only count projects registered in
+  // config.json, not every directory under ~/.quadwork/. Stray
+  // folders from deleted / unconfigured projects must not inflate
+  // the stats — that's explicit in #312's acceptance.
+  let projectIds = [];
+  try {
+    const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+    if (Array.isArray(cfg.projects)) {
+      projectIds = cfg.projects.map((p) => p && p.id).filter((id) => typeof id === "string" && id);
+    }
+  } catch {
+    // config unreadable → no projects → empty stats (safe fallback)
+  }
+  for (const projectId of projectIds) {
+    const p = activityLogPath(projectId);
+    if (!fs.existsSync(p)) continue;
+    const projectTotals = { today_ms: 0, week_ms: 0, month_ms: 0, total_ms: 0 };
+    let text;
+    try { text = fs.readFileSync(p, "utf-8"); } catch { continue; }
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      let row;
+      try { row = JSON.parse(line); } catch { continue; }
+      const d = row && typeof row.duration_ms === "number" ? row.duration_ms : 0;
+      const start = row && typeof row.start === "number" ? row.start : 0;
+      if (d <= 0 || !start) continue;
+      projectTotals.total_ms += d;
+      if (start >= startOfToday) projectTotals.today_ms += d;
+      if (start >= startOfWeek)  projectTotals.week_ms  += d;
+      if (start >= startOfMonth) projectTotals.month_ms += d;
+    }
+    byProject[projectId] = {
+      today: Math.round(projectTotals.today_ms / 3600) / 1000,
+      week:  Math.round(projectTotals.week_ms  / 3600) / 1000,
+      month: Math.round(projectTotals.month_ms / 3600) / 1000,
+      total: Math.round(projectTotals.total_ms / 3600) / 1000,
+    };
+    totals.today_ms += projectTotals.today_ms;
+    totals.week_ms  += projectTotals.week_ms;
+    totals.month_ms += projectTotals.month_ms;
+    totals.total_ms += projectTotals.total_ms;
+  }
+  const data = {
+    today: Math.round(totals.today_ms / 3600) / 1000,
+    week:  Math.round(totals.week_ms  / 3600) / 1000,
+    month: Math.round(totals.month_ms / 3600) / 1000,
+    total: Math.round(totals.total_ms / 3600) / 1000,
+    by_project: byProject,
+  };
+  _activityStatsCache.ts = Date.now();
+  _activityStatsCache.data = data;
+  return data;
+}
+
+router.get("/api/activity/stats", (_req, res) => {
+  try {
+    res.json(computeActivityStats());
+  } catch (err) {
+    res.status(500).json({ error: "Failed to compute activity stats", detail: err.message });
+  }
+});
+
 router.post("/api/chat", async (req, res) => {
   const projectId = req.query.project || req.body.project;
   const { url: base, token: sessionToken } = getChattrConfig(projectId);
@@ -836,15 +1118,128 @@ router.get("/api/github/merged-prs", (req, res) => {
 // deterministic from issue/PR state — no agent inference.
 //
 // Progress mapping (from upstream issue):
-//   queued    0%   issue exists, no linked PR
+//   queued    0%   issue OPEN, no linked PR
 //   in_review 20%  PR open, 0 approvals
 //   approved1 50%  PR open, 1 approval
 //   ready     80%  PR open, 2+ approvals
 //   merged   100%  PR merged AND issue closed
+//   closed   100%  issue CLOSED with no linked PR (superseded,
+//                  not planned, or runbook-only tasks) — #350
 //
 // Cached for 10s per project to avoid hammering gh on every poll.
 
 const _batchProgressCache = new Map(); // projectId -> { ts, data }
+
+// #429 / quadwork#316: persistent batch snapshot on disk so the
+// Batch Progress panel keeps showing merged items after Head moves
+// them from Active Batch to Done. The in-memory `_batchProgressCache`
+// above is a 10s TTL cache of the rendered rows; this new cache is
+// the *set of issue numbers* we currently consider "the active
+// batch", and it survives restarts + lives across polls.
+function batchSnapshotPath(projectId) {
+  return path.join(CONFIG_DIR, projectId, "batch-progress-cache.json");
+}
+function readBatchSnapshot(projectId) {
+  try {
+    return JSON.parse(fs.readFileSync(batchSnapshotPath(projectId), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeBatchSnapshot(projectId, snapshot) {
+  try {
+    const p = batchSnapshotPath(projectId);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(snapshot));
+  } catch {
+    // Non-fatal — panel still works from the live parse.
+  }
+}
+function deleteBatchSnapshot(projectId) {
+  try {
+    fs.unlinkSync(batchSnapshotPath(projectId));
+  } catch {
+    // Non-fatal — file may already be gone.
+  }
+}
+
+// #334: verify the snapshot's first issue number still exists on
+// GitHub before trusting the snapshot. A soft existence check is
+// enough — if the first issue genuinely 404s, treat the whole
+// snapshot as stale (most likely a leftover from a prior
+// project/repo that was purged) and let the caller drop it. One
+// gh call per cache miss, wrapped in the existing
+// BATCH_PROGRESS_TTL_MS cache upstream.
+//
+// Returns one of:
+//   "fresh"   — first issue resolved, snapshot is trustworthy
+//   "gone"    — first issue confirmed 404; snapshot should be dropped
+//   "unknown" — transient error (auth/network/timeout); leave
+//               snapshot alone and let the next cache miss retry
+async function checkBatchSnapshotFreshness(repo, snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.issueNumbers) || snapshot.issueNumbers.length === 0) {
+    return "gone";
+  }
+  const first = snapshot.issueNumbers[0];
+  try {
+    await ghJsonExecAsync([
+      "issue",
+      "view",
+      String(first),
+      "-R",
+      repo,
+      "--json",
+      "number",
+    ]);
+    return "fresh";
+  } catch (err) {
+    // gh surfaces a 404 via stderr text on a non-zero exit. Only
+    // the unambiguous "not found" / "could not resolve" shapes
+    // count as genuinely gone; anything else (network, auth,
+    // timeout) is transient and must NOT delete the snapshot.
+    const msg = String((err && (err.stderr || err.message)) || "").toLowerCase();
+    if (msg.includes("could not resolve") || msg.includes("not found") || msg.includes("no issue")) {
+      return "gone";
+    }
+    return "unknown";
+  }
+}
+
+// Decide which batch to render, combining the live parse of
+// OVERNIGHT-QUEUE.md with the persistent snapshot. The snapshot is
+// replaced whenever a new batch starts (explicit Batch: N bump OR
+// the live Active Batch contains items the snapshot doesn't); in
+// all other cases the snapshot wins, so items Head moved to Done
+// stay visible until the operator starts the next batch.
+function resolveDisplayedBatch(queueText, projectId, { queueReadOk = true } = {}) {
+  // Queue file deleted / unreadable → fall back to empty state per
+  // #316's edge case. Returning the snapshot here would "heal" a
+  // genuinely missing file into stale data the operator can't
+  // reconcile without nuking ~/.quadwork/{id}/batch-progress-cache.json
+  // manually.
+  if (!queueReadOk) return { batchNumber: null, issueNumbers: [] };
+  const current = parseActiveBatch(queueText);
+  const snapshot = readBatchSnapshot(projectId);
+  const hasExplicitBump =
+    current.batchNumber !== null &&
+    (!snapshot || snapshot.batchNumber === null || current.batchNumber > snapshot.batchNumber);
+  const hasNewItems =
+    current.issueNumbers.length > 0 &&
+    (!snapshot || current.issueNumbers.some((n) => !snapshot.issueNumbers.includes(n)));
+  let next;
+  if (hasExplicitBump || hasNewItems) {
+    next = { batchNumber: current.batchNumber, issueNumbers: current.issueNumbers.slice() };
+  } else if (snapshot && Array.isArray(snapshot.issueNumbers) && snapshot.issueNumbers.length > 0) {
+    next = {
+      batchNumber: snapshot.batchNumber ?? null,
+      issueNumbers: snapshot.issueNumbers.slice(),
+    };
+  } else {
+    next = { batchNumber: current.batchNumber, issueNumbers: current.issueNumbers.slice() };
+  }
+  if (next.issueNumbers.length > 0) writeBatchSnapshot(projectId, next);
+  return next;
+}
 const BATCH_PROGRESS_TTL_MS = 10000;
 
 function parseActiveBatch(queueText) {
@@ -860,10 +1255,11 @@ function parseActiveBatch(queueText) {
   const batchNumber = batchMatch ? parseInt(batchMatch[1], 10) : null;
   // Only collect issue numbers from lines that look like list-item
   // entries — i.e. lines whose first content token is either `#N`
-  // or `[#N]` after an optional list marker. This rejects prose
-  // like "Tracking umbrella: #293", "next after #294 merged", and
-  // similar dependency / commentary references that t2a flagged on
-  // realproject7/dropcast's queue.
+  // or `[#N]` after an optional list marker, and optionally after
+  // a GitHub-flavored markdown checkbox token `[ ]` / `[x]` / `[X]`.
+  // This rejects prose like "Tracking umbrella: #293", "next after
+  // #294 merged", and similar dependency / commentary references
+  // that t2a flagged on realproject7/dropcast's queue.
   //
   // Accepted line shapes:
   //   - #295 sub-A heartbeat
@@ -872,12 +1268,22 @@ function parseActiveBatch(queueText) {
   //   #295 sub-A heartbeat
   //   - [#295] sub-A heartbeat
   //   [#295] sub-A heartbeat
+  //   - [ ] #295 sub-A heartbeat      (#342/quadwork#341: GFM checkbox)
+  //   - [x] #295 sub-A heartbeat      (checked)
+  //   - [X] #295 sub-A heartbeat      (checked, uppercase)
   //
   // Rejected:
   //   Tracking umbrella: #293
   //   Assigned next after #294 merged.
   //   See #295 for context.
-  const ITEM_LINE_RE = /^\s*(?:[-*]\s+|\d+\.\s+)?\[?#(\d{1,6})\]?\b/;
+  //
+  // The previous regex permitted an optional `[` *immediately*
+  // before `#`, which happened to match `[#295]` but not `[ ] #295`
+  // (a space between `[` and `#`), so Head-generated queues that
+  // used GFM checkbox syntax produced zero issue numbers and the
+  // Current Batch panel showed empty. #341 adds an explicit optional
+  // checkbox token after the list marker.
+  const ITEM_LINE_RE = /^\s*(?:[-*]\s+|\d+\.\s+)?(?:\[[ xX]\]\s+)?\[?#(\d{1,6})\]?\b/;
   const seen = new Set();
   const issueNumbers = [];
   for (const line of section.split("\n")) {
@@ -909,6 +1315,32 @@ async function ghJsonExecAsync(args) {
   return JSON.parse(stdout);
 }
 
+// #350: pure helper for the "no linked PR" branch of
+// progressForItemAsync. Takes the issue JSON (shape: { number,
+// title, state, url, ... }) and returns the batch-progress row
+// for an item that has no closedByPullRequestsReferences. Exported
+// from module.exports below for unit tests — no other callers.
+function buildNoPrRow(issue) {
+  if (issue && issue.state === "CLOSED") {
+    return {
+      issue_number: issue.number,
+      title: issue.title,
+      url: issue.url,
+      status: "closed",
+      progress: 100,
+      label: "Closed (no PR) ✓",
+    };
+  }
+  return {
+    issue_number: issue.number,
+    title: issue.title,
+    url: issue.url,
+    status: "queued",
+    progress: 0,
+    label: "Issue · queued",
+  };
+}
+
 async function progressForItemAsync(repo, issueNumber) {
   // Pull issue state + linked PRs in one call. closedByPullRequestsReferences
   // is gh's serializer for the GraphQL `closedByPullRequestsReferences`
@@ -935,16 +1367,14 @@ async function progressForItemAsync(repo, issueNumber) {
   const pr = linked.length > 0
     ? linked.slice().sort((a, b) => (b.number || 0) - (a.number || 0))[0]
     : null;
-  // No linked PR yet — queued.
+  // No linked PR. #350: before falling into the "queued" bucket,
+  // honor the issue's own state — a CLOSED issue with no linked
+  // PR is fully done (superseded, not planned, runbook-only, etc.)
+  // and should render at 100% with a ✓ label instead of a
+  // misleading "0% · queued" row. Only truly OPEN issues with no
+  // linked PR are still queued.
   if (!pr) {
-    return {
-      issue_number: issue.number,
-      title: issue.title,
-      url: issue.url,
-      status: "queued",
-      progress: 0,
-      label: "Issue · queued",
-    };
+    return buildNoPrRow(issue);
   }
   // Re-fetch the PR to get reviewDecision + reviews + state, since
   // the issue's closedByPullRequestsReferences edge only carries
@@ -1048,15 +1478,23 @@ async function progressForItemAsync(repo, issueNumber) {
 }
 
 function summarizeItems(items) {
-  let merged = 0, ready = 0, approved1 = 0, inReview = 0, queued = 0;
+  // #350: "closed" (CLOSED issue with no linked PR — superseded,
+  // not planned, runbook-only) counts toward the complete tally
+  // alongside "merged". The panel tally now reads "X/N complete"
+  // when the batch mixes both kinds of completion, otherwise
+  // "X/N merged" for the classic all-via-PR case.
+  let merged = 0, closed = 0, ready = 0, approved1 = 0, inReview = 0, queued = 0;
   for (const it of items) {
     if (it.status === "merged") merged++;
+    else if (it.status === "closed") closed++;
     else if (it.status === "ready") ready++;
     else if (it.status === "approved1") approved1++;
     else if (it.status === "in_review") inReview++;
     else if (it.status === "queued") queued++;
   }
-  const parts = [`${merged}/${items.length} merged`];
+  const done = merged + closed;
+  const doneLabel = closed > 0 ? "complete" : "merged";
+  const parts = [`${done}/${items.length} ${doneLabel}`];
   if (ready > 0) parts.push(`${ready} ready to merge`);
   if (approved1 > 0) parts.push(`${approved1} needs 2nd approval`);
   if (inReview > 0) parts.push(`${inReview} in review`);
@@ -1078,10 +1516,41 @@ router.get("/api/batch-progress", async (req, res) => {
 
   const queuePath = path.join(CONFIG_DIR, projectId, "OVERNIGHT-QUEUE.md");
   let queueText = "";
-  try { queueText = fs.readFileSync(queuePath, "utf-8"); }
-  catch { /* missing file → empty active batch */ }
+  let queueReadOk = false;
+  try {
+    queueText = fs.readFileSync(queuePath, "utf-8");
+    queueReadOk = true;
+  } catch {
+    // Missing / unreadable file — pass queueReadOk=false so the
+    // resolver bypasses the snapshot and returns the empty state
+    // per #316's edge case.
+  }
+
+  // #334 / quadwork#334: validate the on-disk snapshot against
+  // GitHub before resolveDisplayedBatch can serve it. A snapshot
+  // whose first issue 404s is almost certainly a leftover from a
+  // prior project/repo that was purged; drop the file so the
+  // resolver falls through to the live queue parse (which will
+  // typically also be empty) instead of serving stale data
+  // indefinitely. We only run the check on cache-miss paths (this
+  // route already sits behind BATCH_PROGRESS_TTL_MS) and only
+  // when we'd actually rely on the snapshot — i.e. the live queue
+  // read succeeded, so the existing #316 bypass for unreadable
+  // queue files keeps precedence.
+  if (queueReadOk) {
+    const existing = readBatchSnapshot(projectId);
+    if (existing && Array.isArray(existing.issueNumbers) && existing.issueNumbers.length > 0) {
+      const freshness = await checkBatchSnapshotFreshness(repo, existing);
+      if (freshness === "gone") deleteBatchSnapshot(projectId);
+      // "unknown" → leave the file alone; transient failure will
+      // retry on the next cache miss.
+    }
+  }
 
-  const { batchNumber, issueNumbers } = parseActiveBatch(queueText);
+  // #429 / quadwork#316: resolve the displayed batch through the
+  // snapshot-aware helper so merged items stay visible after Head
+  // moves them from Active Batch to Done, until a new batch starts.
+  const { batchNumber, issueNumbers } = resolveDisplayedBatch(queueText, projectId, { queueReadOk });
   if (issueNumbers.length === 0) {
     const data = { batch_number: batchNumber, items: [], summary: "", complete: false };
     _batchProgressCache.set(projectId, { ts: Date.now(), data });
@@ -1109,7 +1578,10 @@ router.get("/api/batch-progress", async (req, res) => {
     };
   });
   const summary = summarizeItems(items);
-  const complete = items.length > 0 && items.every((it) => it.status === "merged");
+  // #350: treat CLOSED-without-PR items as complete alongside merged
+  // so batches that mix runbook/superseded closes with real PRs
+  // still flip to the COMPLETE state once everything is done.
+  const complete = items.length > 0 && items.every((it) => it.status === "merged" || it.status === "closed");
   const data = { batch_number: batchNumber, items, summary, complete };
   _batchProgressCache.set(projectId, { ts: Date.now(), data });
   res.json(data);
@@ -1602,6 +2074,12 @@ router.post("/api/setup", (req, res) => {
         return res.json({ ok: true, message: "Project already in config" });
       }
       // Match CLI wizard agent structure: { cwd, command, auto_approve, mcp_inject }
+      // #343: default Codex-backed agents to reasoning_effort="medium"
+      // instead of the upstream xhigh/high default. high/xhigh is the
+      // provider-side capacity-failure hot spot; medium is the
+      // safe-default for fresh installs so new projects don't hit
+      // "Selected model is at capacity" out of the box. Operators can
+      // bump individual agents back up via the Agent Models widget.
       const agents = {};
       for (const agentId of ["head", "reviewer1", "reviewer2", "dev"]) {
         const cmd = (backends && backends[agentId]) || "claude";
@@ -1612,6 +2090,7 @@ router.post("/api/setup", (req, res) => {
           command: cmd,
           auto_approve: autoApprove,
           mcp_inject: injectMode,
+          ...(cliBase === "codex" ? { reasoning_effort: "medium" } : {}),
         };
       }
       // Use pre-assigned ports/token from agentchattr-config step if provided,
@@ -1821,6 +2300,66 @@ function telegramConfigToml(projectId) {
   return path.join(CONFIG_DIR, `telegram-${projectId}.toml`);
 }
 
+// #353: per-project log file for the bridge subprocess. The start
+// handler redirects stdout + stderr here so crashes (ImportError,
+// config parse, auth failure) are recoverable instead of
+// /dev/null'd by `stdio: "ignore"`.
+function telegramBridgeLog(projectId) {
+  return path.join(CONFIG_DIR, `telegram-bridge-${projectId}.log`);
+}
+
+// Tail the last N lines of a file without reading the whole thing
+// into memory if it is huge. For the bridge log we care about the
+// final crash frame, not historical output.
+function readLastLines(filePath, n) {
+  try {
+    if (!fs.existsSync(filePath)) return "";
+    const stat = fs.statSync(filePath);
+    const readBytes = Math.min(stat.size, 64 * 1024);
+    if (readBytes === 0) return "";
+    const buf = Buffer.alloc(readBytes);
+    const fd = fs.openSync(filePath, "r");
+    try {
+      fs.readSync(fd, buf, 0, readBytes, Math.max(0, stat.size - readBytes));
+    } finally {
+      fs.closeSync(fd);
+    }
+    const text = buf.toString("utf-8");
+    const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
+    return lines.slice(-n).join("\n");
+  } catch {
+    return "";
+  }
+}
+
+// Verify that the bridge's Python runtime has its required modules
+// available. Cheap pre-flight so a missing `requests` install
+// produces a readable error instead of a silent Start → Stopped
+// flicker. Returns { ok: true } on success, { ok: false, error }
+// otherwise. Keep the import list small and close to what the
+// bridge actually needs; add modules here if the bridge gains new
+// hard deps.
+function checkTelegramBridgePythonDeps() {
+  try {
+    // Only check the third-party module the bridge actually needs
+    // at import time — `requests`. Toml parsing differs between
+    // Python versions (tomllib on 3.11+, tomli on 3.10-), and any
+    // genuine toml import failure will now be captured in the
+    // bridge log file on spawn, so this pre-flight stays narrow
+    // and avoids false negatives on older Python installs.
+    execFileSync("python3", ["-c", "import requests"], {
+      encoding: "utf-8",
+      timeout: 10000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true };
+  } catch (err) {
+    const stderr = (err && err.stderr && err.stderr.toString && err.stderr.toString()) || "";
+    const msg = stderr.trim() || (err && err.message) || "python3 import check failed";
+    return { ok: false, error: msg };
+  }
+}
+
 function isTelegramRunning(projectId) {
   const pf = telegramPidFile(projectId);
   if (!fs.existsSync(pf)) return false;
@@ -1919,12 +2458,29 @@ router.get("/api/telegram", async (req, res) => {
       }
     } catch { /* non-fatal — widget will just show no username */ }
   }
+  // #353: if the bridge is not running but a log file exists with
+  // content, tail it and expose it as `last_error` so the widget
+  // can surface runtime crashes (bad token mid-session, network
+  // failure, config parse error) that happen after the initial
+  // 500 ms post-spawn liveness check and would otherwise just
+  // revert the pill to Stopped with no explanation.
+  const running = isTelegramRunning(projectId);
+  let lastError = "";
+  if (!running) {
+    const logPath = telegramBridgeLog(projectId);
+    try {
+      if (fs.existsSync(logPath) && fs.statSync(logPath).size > 0) {
+        lastError = readLastLines(logPath, 20);
+      }
+    } catch {}
+  }
   res.json({
-    running: isTelegramRunning(projectId),
+    running,
     configured,
     chat_id: chatId,
     bot_username: botUsername,
     bridge_installed: bridgeInstalled,
+    last_error: lastError,
   });
 });
 
@@ -1947,15 +2503,39 @@ router.post("/api/telegram", async (req, res) => {
       }
     }
     case "install": {
+      // #353: pip3 can exit 0 on some systems (PEP 668 externally-
+      // managed environments, non-writable site-packages) even when
+      // the subsequent import still fails. After the pip step, run
+      // a post-install import check and surface both the pip output
+      // and the import error together if the check fails — that's
+      // the signal the operator needs to know whether to pick a
+      // virtualenv, use --user, or --break-system-packages.
+      let pipOutput = "";
       try {
         if (!fs.existsSync(BRIDGE_DIR)) {
           execFileSync("gh", ["repo", "clone", "realproject7/agentchattr-telegram", BRIDGE_DIR], { encoding: "utf-8", timeout: 30000 });
         }
-        execFileSync("pip3", ["install", "-r", path.join(BRIDGE_DIR, "requirements.txt")], { encoding: "utf-8", timeout: 30000 });
-        return res.json({ ok: true });
+        pipOutput = execFileSync(
+          "pip3",
+          ["install", "-r", path.join(BRIDGE_DIR, "requirements.txt")],
+          { encoding: "utf-8", timeout: 60000 },
+        );
       } catch (err) {
         return res.json({ ok: false, error: err.message || "Install failed" });
       }
+      const depCheck = checkTelegramBridgePythonDeps();
+      if (!depCheck.ok) {
+        return res.json({
+          ok: false,
+          error:
+            "pip3 reported success but the bridge's Python deps still fail to import. " +
+            "This usually means pip installed into a location python3 cannot see " +
+            "(externally-managed environment / PEP 668 / mismatched interpreter).\n\n" +
+            `Import error: ${depCheck.error}\n\n` +
+            `pip output tail:\n${pipOutput.split("\n").slice(-10).join("\n")}`,
+        });
+      }
+      return res.json({ ok: true });
     }
     case "start": {
       const projectId = body.project_id;
@@ -1969,14 +2549,75 @@ router.post("/api/telegram", async (req, res) => {
       const tomlContent = `[telegram]\nbot_token = "${tg.bot_token}"\nchat_id = "${tg.chat_id}"\n\n[agentchattr]\nurl = "${tg.agentchattr_url}"\n`;
       fs.writeFileSync(tomlPath, tomlContent, { mode: 0o600 });
       fs.chmodSync(tomlPath, 0o600);
+      // #353: pre-flight import check so a fresh install with no
+      // `requests` module produces a readable error instead of the
+      // Start → Running → Stopped flicker that the v1 code path
+      // produced with `stdio: "ignore"`.
+      const depCheck = checkTelegramBridgePythonDeps();
+      if (!depCheck.ok) {
+        return res.json({
+          ok: false,
+          error:
+            "Bridge Python dependencies not installed. Click \"Install Bridge\" to install them, " +
+            "or run: pip3 install -r " + path.join(BRIDGE_DIR, "requirements.txt") + "\n\n" +
+            `Import error: ${depCheck.error}`,
+        });
+      }
+      // #353: capture stdout + stderr to a per-project log file so
+      // bridge crashes (bad token, network failure, config parse
+      // error, etc.) are recoverable. The handle must be opened
+      // BEFORE spawn and passed through stdio so the detached
+      // child keeps writing after the parent unrefs it.
+      const logPath = telegramBridgeLog(projectId);
+      // #353 follow-up: truncate the log at the start of every
+      // spawn so the status endpoint's last_error tail only ever
+      // reflects the *current* session. Otherwise a previous
+      // crash's trace would linger forever and the widget would
+      // keep surfacing a stale error even after the operator
+      // fixed the underlying problem and restarted cleanly.
+      try { fs.writeFileSync(logPath, ""); } catch {}
+      let outFd, errFd;
+      try {
+        outFd = fs.openSync(logPath, "a");
+        errFd = fs.openSync(logPath, "a");
+      } catch (err) {
+        return res.json({ ok: false, error: `Could not open bridge log file: ${err.message}` });
+      }
+      let child;
       try {
-        const child = spawn("python3", [bridgeScript, "--config", tomlPath], { detached: true, stdio: "ignore" });
+        child = spawn("python3", [bridgeScript, "--config", tomlPath], {
+          detached: true,
+          stdio: ["ignore", outFd, errFd],
+        });
         child.unref();
         if (child.pid) fs.writeFileSync(telegramPidFile(projectId), String(child.pid));
-        return res.json({ ok: true, running: true, pid: child.pid });
       } catch (err) {
+        try { fs.closeSync(outFd); } catch {}
+        try { fs.closeSync(errFd); } catch {}
         return res.json({ ok: false, error: err.message || "Start failed" });
       }
+      // Close our copies of the fds in the parent now that the
+      // child has inherited them — otherwise the parent holds the
+      // log file open forever.
+      try { fs.closeSync(outFd); } catch {}
+      try { fs.closeSync(errFd); } catch {}
+      // #353: liveness check — wait 500ms, then verify the child
+      // is still running. If it already died, tail the log file
+      // and return those lines as the error.
+      await new Promise((r) => setTimeout(r, 500));
+      let alive = true;
+      try { process.kill(child.pid, 0); } catch { alive = false; }
+      if (!alive) {
+        const tail = readLastLines(logPath, 20);
+        try { fs.unlinkSync(telegramPidFile(projectId)); } catch {}
+        return res.json({
+          ok: false,
+          error:
+            "Bridge crashed on start (exited within 500ms).\n\n" +
+            `Last log lines (${logPath}):\n${tail || "(log empty)"}`,
+        });
+      }
+      return res.json({ ok: true, running: true, pid: child.pid });
     }
     case "stop": {
       const projectId = body.project_id;
@@ -2050,4 +2691,82 @@ router.post("/api/telegram", async (req, res) => {
   }
 });
 
+// #343: per-agent model + reasoning-effort settings endpoint.
+// GET returns the rows the dashboard Agent Models widget needs;
+// PUT persists a single row back to config.json. Kept narrow on
+// purpose — only `model` and `reasoning_effort` are writable
+// here, and codex is the only backend that accepts
+// reasoning_effort today. The launch-time wiring lives in
+// server/index.js buildAgentArgs; this endpoint is purely
+// config storage.
+const ALLOWED_REASONING_EFFORTS = new Set(["minimal", "low", "medium", "high"]);
+
+router.get("/api/project/:projectId/agent-models", (req, res) => {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+    const project = cfg.projects?.find((p) => p.id === req.params.projectId);
+    if (!project) return res.status(404).json({ error: "Unknown project" });
+    const rows = ["head", "reviewer1", "reviewer2", "dev"].map((agentId) => {
+      const a = project.agents?.[agentId] || {};
+      const command = a.command || "claude";
+      const cliBase = command.split("/").pop().split(" ")[0];
+      return {
+        agent_id: agentId,
+        backend: cliBase,
+        model: a.model || "",
+        reasoning_effort: a.reasoning_effort || "",
+        reasoning_supported: cliBase === "codex",
+      };
+    });
+    return res.json({ agents: rows });
+  } catch (err) {
+    return res.status(500).json({ error: err.message || "read failed" });
+  }
+});
+
+router.put("/api/project/:projectId/agent-models/:agentId", (req, res) => {
+  const { projectId, agentId } = req.params;
+  if (!["head", "reviewer1", "reviewer2", "dev"].includes(agentId)) {
+    return res.json({ ok: false, error: "Unknown agent" });
+  }
+  const body = req.body || {};
+  // Accept empty string as "clear override → fall back to CLI default".
+  const model = typeof body.model === "string" ? body.model.trim() : undefined;
+  const reasoning = typeof body.reasoning_effort === "string" ? body.reasoning_effort.trim() : undefined;
+  if (reasoning && reasoning !== "" && !ALLOWED_REASONING_EFFORTS.has(reasoning)) {
+    return res.json({ ok: false, error: `Invalid reasoning_effort: ${reasoning}` });
+  }
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
+    const cfg = JSON.parse(raw);
+    const project = cfg.projects?.find((p) => p.id === projectId);
+    if (!project) return res.status(404).json({ ok: false, error: "Unknown project" });
+    if (!project.agents) project.agents = {};
+    const a = project.agents[agentId] || {};
+    if (model !== undefined) {
+      if (model === "") delete a.model;
+      else a.model = model;
+    }
+    if (reasoning !== undefined) {
+      if (reasoning === "") delete a.reasoning_effort;
+      else a.reasoning_effort = reasoning;
+    }
+    project.agents[agentId] = a;
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+    return res.json({ ok: true, agent: { agent_id: agentId, model: a.model || "", reasoning_effort: a.reasoning_effort || "" } });
+  } catch (err) {
+    return res.json({ ok: false, error: err.message || "write failed" });
+  }
+});
+
 module.exports = router;
+// #341: export parseActiveBatch for unit tests. No production callers
+// outside this file; the export is strictly for the node:assert
+// script at server/routes.parseActiveBatch.test.js.
+module.exports.parseActiveBatch = parseActiveBatch;
+// #350: same pattern — expose the no-linked-PR row builder and
+// summarizeItems for the batch-progress fixture test.
+module.exports.buildNoPrRow = buildNoPrRow;
+module.exports.summarizeItems = summarizeItems;
+// #353: expose readLastLines for the telegram-bridge test.
+module.exports.readLastLines = readLastLines;