npm - create-walle - Versions diffs - 0.9.26 → 0.9.28 - Mend

create-walle 0.9.26 → 0.9.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

package/README.md +1 -0
package/package.json +1 -1
package/template/claude-task-manager/api-prompts.js +11 -6
package/template/claude-task-manager/docs/session-status-redesign.html +554 -0
package/template/claude-task-manager/docs/terminal-rendering-redesign.html +529 -0
package/template/claude-task-manager/lib/flush-redraw-markers.js +72 -0
package/template/claude-task-manager/lib/macos-capabilities.js +190 -0
package/template/claude-task-manager/lib/session-messages-projection.js +224 -3
package/template/claude-task-manager/lib/ttl-memo.js +61 -0
package/template/claude-task-manager/public/index.html +892 -11
package/template/claude-task-manager/public/js/activation-render-check.js +40 -2
package/template/claude-task-manager/public/js/session-phase.js +370 -0
package/template/claude-task-manager/public/js/setup.js +74 -1
package/template/claude-task-manager/public/js/stream-view.js +56 -2
package/template/claude-task-manager/server.js +643 -68
package/template/claude-task-manager/workers/read-pool-worker.js +10 -0
package/template/package.json +1 -1
package/template/wall-e/agent.js +130 -24
package/template/wall-e/api-walle.js +12 -1
package/template/wall-e/brain.js +290 -4
package/template/wall-e/chat.js +30 -25
package/template/wall-e/coding/session-plan.js +79 -0
package/template/wall-e/coding-orchestrator.js +9 -3
package/template/wall-e/coding-prompts.js +10 -3
package/template/wall-e/embeddings.js +192 -17
package/template/wall-e/http/model-admin.js +109 -0
package/template/wall-e/lib/event-loop-monitor.js +2 -2
package/template/wall-e/lib/scheduler-worker-jobs.js +156 -121
package/template/wall-e/lib/scheduler.js +226 -13
package/template/wall-e/lib/worker-thread-pool.js +58 -4
package/template/wall-e/llm/ollama-library.js +126 -0
package/template/wall-e/llm/ollama.js +13 -0
package/template/wall-e/llm/provider-backpressure.js +134 -0
package/template/wall-e/llm/provider-health-state.js +24 -0
package/template/wall-e/loops/backfill.js +43 -16
package/template/wall-e/loops/initiative.js +1 -0
package/template/wall-e/loops/think.js +38 -5
package/template/wall-e/mcp-server.js +20 -4
package/template/wall-e/skills/skill-fallback.js +34 -1
package/template/wall-e/skills/skill-planner.js +60 -2
package/template/wall-e/sources/jsonl-utils.js +84 -11
package/template/wall-e/telemetry.js +42 -7
package/template/wall-e/tools/local-tools.js +16 -0
package/template/wall-e/workers/runtime-worker.js +33 -1
package/template/website/index.html +5 -0

package/template/claude-task-manager/docs/terminal-rendering-redesign.html ADDED Viewed

@@ -0,0 +1,529 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CTM Terminal Rendering — Current Design &amp; Redesign</title>
+<style>
+  :root{
+    --bg:#0e1116; --panel:#161b22; --panel2:#1c2430; --ink:#e6edf3; --muted:#9aa7b4;
+    --line:#2a3441; --accent:#58a6ff; --good:#3fb950; --warn:#d29922; --bad:#f85149;
+    --violet:#bc8cff; --teal:#56d4c4; --code:#0b0f14;
+    --mono:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace;
+    --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  }
+  *{box-sizing:border-box}
+  html{scroll-behavior:smooth}
+  body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);line-height:1.6;font-size:16px}
+  .wrap{max-width:1080px;margin:0 auto;padding:0 24px 120px}
+  header.hero{padding:56px 24px 28px;border-bottom:1px solid var(--line);background:
+     radial-gradient(1200px 320px at 20% -10%, rgba(88,166,255,.14), transparent 60%),
+     radial-gradient(900px 300px at 90% -20%, rgba(188,140,255,.12), transparent 60%);}
+  .hero .wrap{padding-bottom:0}
+  h1{font-size:34px;line-height:1.15;margin:0 0 8px;letter-spacing:-.02em}
+  h1 .sub{display:block;font-size:16px;color:var(--muted);font-weight:500;margin-top:10px}
+  .tag{display:inline-block;font-family:var(--mono);font-size:12px;color:var(--accent);
+       border:1px solid var(--line);border-radius:999px;padding:3px 10px;margin-bottom:18px;background:#0d1320}
+  h2{font-size:24px;margin:56px 0 6px;letter-spacing:-.01em;padding-top:8px}
+  h2 .n{color:var(--accent);font-family:var(--mono);font-size:15px;margin-right:10px;opacity:.8}
+  h3{font-size:18px;margin:30px 0 6px;color:#cdd9e5}
+  p{margin:12px 0}
+  .lead{font-size:17px;color:#cdd9e5}
+  a{color:var(--accent);text-decoration:none}
+  a:hover{text-decoration:underline}
+  code{font-family:var(--mono);font-size:.86em;background:#0c1422;border:1px solid #1d2733;
+       border-radius:5px;padding:1px 6px;color:#cfe3ff}
+  .muted{color:var(--muted)}
+  .card{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:18px 20px;margin:18px 0}
+  .callout{border-left:4px solid var(--accent);background:linear-gradient(90deg,rgba(88,166,255,.08),transparent);
+           border-radius:8px;padding:14px 18px;margin:18px 0}
+  .callout.bad{border-color:var(--bad);background:linear-gradient(90deg,rgba(248,81,73,.10),transparent)}
+  .callout.good{border-color:var(--good);background:linear-gradient(90deg,rgba(63,185,80,.10),transparent)}
+  .callout.warn{border-color:var(--warn);background:linear-gradient(90deg,rgba(210,153,34,.10),transparent)}
+  .callout b{color:#fff}
+  .grid2{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+  @media(max-width:780px){.grid2{grid-template-columns:1fr}}
+  table{width:100%;border-collapse:collapse;margin:18px 0;font-size:14px;background:var(--panel);
+        border:1px solid var(--line);border-radius:10px;overflow:hidden}
+  th,td{text-align:left;padding:10px 12px;border-bottom:1px solid var(--line);vertical-align:top}
+  th{background:var(--panel2);color:#cdd9e5;font-weight:600;font-size:13px;text-transform:uppercase;letter-spacing:.04em}
+  tr:last-child td{border-bottom:none}
+  td code{font-size:.82em}
+  .pill{display:inline-block;font-family:var(--mono);font-size:11px;padding:2px 8px;border-radius:999px;font-weight:600}
+  .pill.codex{background:rgba(86,212,196,.14);color:var(--teal);border:1px solid rgba(86,212,196,.3)}
+  .pill.claude{background:rgba(210,153,34,.14);color:var(--warn);border:1px solid rgba(210,153,34,.3)}
+  .pill.both{background:rgba(188,140,255,.14);color:var(--violet);border:1px solid rgba(188,140,255,.3)}
+  .pill.ok{background:rgba(63,185,80,.14);color:var(--good);border:1px solid rgba(63,185,80,.3)}
+  .pill.fail{background:rgba(248,81,73,.14);color:var(--bad);border:1px solid rgba(248,81,73,.3)}
+  .ref{font-family:var(--mono);font-size:11px;color:#6f8196;white-space:nowrap}
+  figure{margin:22px 0;text-align:center}
+  figcaption{color:var(--muted);font-size:13px;margin-top:8px}
+  svg{max-width:100%;height:auto}
+  .scoreboard{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin:18px 0}
+  @media(max-width:780px){.scoreboard{grid-template-columns:repeat(2,1fr)}}
+  .metric{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:16px;text-align:center}
+  .metric .big{font-size:34px;font-weight:700;color:var(--bad);font-family:var(--mono);line-height:1}
+  .metric .lbl{font-size:12px;color:var(--muted);margin-top:8px;text-transform:uppercase;letter-spacing:.04em}
+  ul.tight{margin:10px 0;padding-left:22px}
+  ul.tight li{margin:6px 0}
+  .opt{border:1px solid var(--line);border-radius:12px;padding:0;margin:20px 0;overflow:hidden}
+  .opt .head{padding:14px 20px;display:flex;align-items:center;gap:12px;border-bottom:1px solid var(--line)}
+  .opt .head .badge{font-family:var(--mono);font-weight:700;font-size:15px;width:30px;height:30px;border-radius:8px;
+        display:grid;place-items:center}
+  .opt.A .head{background:linear-gradient(90deg,rgba(63,185,80,.12),transparent)}
+  .opt.A .badge{background:rgba(63,185,80,.18);color:var(--good)}
+  .opt.B .head{background:linear-gradient(90deg,rgba(188,140,255,.12),transparent)}
+  .opt.B .badge{background:rgba(188,140,255,.18);color:var(--violet)}
+  .opt.C .head{background:linear-gradient(90deg,rgba(88,166,255,.12),transparent)}
+  .opt.C .badge{background:rgba(88,166,255,.18);color:var(--accent)}
+  .opt .head h3{margin:0;font-size:18px}
+  .opt .head .rec{margin-left:auto;font-size:11px;font-weight:700;color:var(--good);
+        border:1px solid rgba(63,185,80,.4);border-radius:999px;padding:3px 10px;background:rgba(63,185,80,.08)}
+  .opt .body{padding:8px 20px 18px}
+  .kv{display:grid;grid-template-columns:120px 1fr;gap:6px 14px;margin:10px 0;font-size:14px}
+  .kv .k{color:var(--muted);font-size:13px}
+  .toc{position:sticky;top:0;background:rgba(14,17,22,.86);backdrop-filter:blur(8px);
+       border-bottom:1px solid var(--line);z-index:10;padding:10px 0;margin-bottom:0}
+  .toc .wrap{padding-top:0;padding-bottom:0;display:flex;gap:6px;flex-wrap:wrap;font-size:13px}
+  .toc a{color:var(--muted);padding:4px 9px;border-radius:6px;border:1px solid transparent}
+  .toc a:hover{color:var(--ink);border-color:var(--line);text-decoration:none;background:var(--panel)}
+  .legend{display:flex;gap:16px;flex-wrap:wrap;font-size:13px;color:var(--muted);margin:6px 0 0}
+  .legend span{display:inline-flex;align-items:center;gap:6px}
+  .dot{width:10px;height:10px;border-radius:3px;display:inline-block}
+  .del{color:var(--bad)} .keep{color:var(--good)}
+  .strike{text-decoration:line-through;color:#6f8196}
+  footer{margin-top:60px;padding-top:24px;border-top:1px solid var(--line);color:var(--muted);font-size:13px}
+  .src{font-size:13px}
+  .src li{margin:4px 0}
+  hr.soft{border:none;border-top:1px solid var(--line);margin:36px 0}
+</style>
+</head>
+<body>
+<header class="hero">
+  <div class="wrap">
+    <span class="tag">CTM · design review · 2026-06-17</span>
+    <h1>Terminal Rendering in CTM: Current Design &amp; a Systematic Redesign
+      <span class="sub">Why switching tabs leaves a stale frame — and why the fix is to delete the repair machinery, not add to it.</span>
+    </h1>
+  </div>
+</header>
+<nav class="toc">
+  <div class="wrap">
+    <a href="#tldr">TL;DR</a>
+    <a href="#diagnosis">1 · Diagnosis</a>
+    <a href="#current">2 · Current architecture</a>
+    <a href="#matrix">3 · Codex×Claude matrix</a>
+    <a href="#scoreboard">4 · Complexity scoreboard</a>
+    <a href="#should">5 · How it should work</a>
+    <a href="#options">6 · Redesign options</a>
+    <a href="#migration">7 · Migration</a>
+  </div>
+</nav>
+<div class="wrap">
+<!-- ============ TLDR ============ -->
+<section id="tldr">
+  <div class="callout">
+    <p style="margin-top:0"><b>TL;DR.</b> CTM keeps <b>two sources of truth</b> for the terminal: a <i>live raw-byte stream</i>
+    replayed into the browser (fast, but positioned for exactly one width) and a <i>server-side headless terminal mirror</i>
+    that holds the real state. Because the byte stream desyncs whenever width drifts, a tab is hidden, or a frame is huge,
+    a <b>second system</b> — fingerprint divergence detection + snapshot/reflow/reconcile pulls — is bolted on to
+    <i>detect and repair</i> the drift. Divergence becomes a steady state that must be continuously policed, so every
+    newly-discovered desync mode needs its own patch. Today that overlay is <b>~13 heal paths, 7+ timers, 2 status state
+    machines, and ~180 env knobs.</b> The reported bug (switching to an idle tab never heals the frame) is simply one
+    desync mode the overlay doesn't cover.</p>
+    <p style="margin-bottom:0"><b>The fix is structural:</b> CTM already owns the hard part — an authoritative headless
+    mirror per session. Make that mirror the <b>single source of truth</b> and continuously synchronize the client
+    <i>to</i> it (the model mosh and VS Code use), instead of replaying bytes and policing drift. That collapses the
+    repair zoo into one deterministic rule and makes "stranded fragment on switch" <b>structurally impossible.</b></p>
+  </div>
+</section>
+<!-- ============ 1 DIAGNOSIS ============ -->
+<section id="diagnosis">
+  <h2><span class="n">01</span>The diagnosis: two sources of truth</h2>
+  <p class="lead">A terminal frame is <i>absolute-positioned</i>: the bytes <code>\x1b[5;1H…</code> mean "row 5, col 1 —
+  at the width the program thinks it has." Replay those bytes into a viewport of a different width, or miss a resize while
+  a tab is hidden, and the screen shears. That single fact is the root of every rendering bug CTM has fought.</p>
+  <figure>
+  <svg viewBox="0 0 900 300" role="img" aria-label="Two sources of truth diagram">
+    <defs>
+      <marker id="arr" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+        <path d="M0,0 L8,3 L0,6 Z" fill="#6f8196"/>
+      </marker>
+      <marker id="arrb" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+        <path d="M0,0 L8,3 L0,6 Z" fill="#f85149"/>
+      </marker>
+    </defs>
+    <!-- PTY -->
+    <rect x="20" y="120" width="120" height="60" rx="10" fill="#1c2430" stroke="#2a3441"/>
+    <text x="80" y="146" text-anchor="middle" fill="#e6edf3" font-size="14" font-weight="700">PTY</text>
+    <text x="80" y="164" text-anchor="middle" fill="#9aa7b4" font-size="11">agent process</text>
+    <!-- raw bytes split -->
+    <line x1="140" y1="150" x2="250" y2="80" stroke="#6f8196" marker-end="url(#arr)"/>
+    <line x1="140" y1="150" x2="250" y2="220" stroke="#6f8196" marker-end="url(#arr)"/>
+    <text x="180" y="100" fill="#56d4c4" font-size="11" transform="rotate(-30 180 100)">raw bytes</text>
+    <text x="180" y="210" fill="#56d4c4" font-size="11" transform="rotate(30 180 205)">raw bytes</text>
+    <!-- headless mirror -->
+    <rect x="250" y="50" width="180" height="64" rx="10" fill="#13241b" stroke="#2f5e3c"/>
+    <text x="340" y="76" text-anchor="middle" fill="#3fb950" font-size="13" font-weight="700">Headless mirror</text>
+    <text x="340" y="94" text-anchor="middle" fill="#9aa7b4" font-size="11">@xterm/headless · authoritative</text>
+    <!-- byte stream to client -->
+    <rect x="250" y="190" width="180" height="64" rx="10" fill="#1c2430" stroke="#2a3441"/>
+    <text x="340" y="216" text-anchor="middle" fill="#e6edf3" font-size="13" font-weight="700">WS output stream</text>
+    <text x="340" y="234" text-anchor="middle" fill="#9aa7b4" font-size="11">ordered bytes · 1 width</text>
+    <!-- client -->
+    <rect x="540" y="190" width="170" height="64" rx="10" fill="#1c2430" stroke="#2a3441"/>
+    <text x="625" y="216" text-anchor="middle" fill="#e6edf3" font-size="13" font-weight="700">Browser xterm</text>
+    <text x="625" y="234" text-anchor="middle" fill="#9aa7b4" font-size="11">what the user sees</text>
+    <line x1="430" y1="222" x2="540" y2="222" stroke="#6f8196" marker-end="url(#arr)"/>
+    <!-- divergence -->
+    <line x1="625" y1="190" x2="430" y2="114" stroke="#f85149" stroke-dasharray="5 4" marker-end="url(#arrb)"/>
+    <text x="470" y="150" fill="#f85149" font-size="11">fingerprint compare →</text>
+    <text x="470" y="166" fill="#f85149" font-size="11">divergence? pull snapshot</text>
+    <!-- repair overlay box -->
+    <rect x="540" y="50" width="340" height="64" rx="10" fill="#2a160f" stroke="#5e2f1f"/>
+    <text x="710" y="74" text-anchor="middle" fill="#f0883e" font-size="13" font-weight="700">Repair overlay (the patches)</text>
+    <text x="710" y="92" text-anchor="middle" fill="#9aa7b4" font-size="11">~13 heals · 7+ timers · 2 status machines</text>
+    <line x1="710" y1="114" x2="640" y2="190" stroke="#5e2f1f" stroke-dasharray="3 3"/>
+  </svg>
+  <figcaption>Two sources of truth. The byte stream (bottom) is fast but width-fragile; the headless mirror (top) is
+  correct but only consulted reactively, through a growing repair overlay.</figcaption>
+  </figure>
+  <p>The server feeds <b>both</b> a headless <code>@xterm/headless</code> terminal (the authoritative full state,
+  serializable to any width) and a raw byte stream to the browser. The browser's xterm is driven by the byte stream for
+  latency; the headless mirror is only consulted <i>reactively</i> when a heuristic decides the browser has drifted.</p>
+  <div class="callout bad">
+    <p style="margin:0"><b>The reported bug, precisely.</b> When a session goes quiet, the server emits a
+    <code>heartbeat</code> fingerprint <b>twice, then stops</b> <span class="ref">server.js:1334–1377</span>. Every client
+    heal path compares the browser grid against that last-received fingerprint <code>s._serverFp</code>. Switch to an
+    <i>idle</i> tab whose quiet episode ended long ago and whose width changed while hidden: <code>s._serverFp</code> is
+    stale (or measured at the old width), and <b>no new heartbeat will ever arrive to refresh it</b>. The activation check
+    runs <span class="ref">index.html:34065</span> but every validator re-compares against the same stale truth → nothing
+    heals. The stranded <code>ctm-main-loop-hardening</code> fragment + detached <code>&gt;</code> composer in the
+    screenshot is exactly this.</p>
+  </div>
+</section>
+<!-- ============ 2 CURRENT ARCH ============ -->
+<section id="current">
+  <h2><span class="n">02</span>Current architecture, end to end</h2>
+  <h3>The live (running) path — raw byte streaming</h3>
+  <figure>
+  <svg viewBox="0 0 900 210" role="img" aria-label="Live streaming pipeline">
+    <defs><marker id="a2" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#58a6ff"/></marker></defs>
+    <g font-size="11" text-anchor="middle">
+      <rect x="10"  y="70" width="120" height="62" rx="9" fill="#1c2430" stroke="#2a3441"/>
+      <text x="70" y="94" fill="#e6edf3" font-weight="700">PTY onData</text>
+      <text x="70" y="110" fill="#9aa7b4">queue + drain</text>
+      <text x="70" y="124" fill="#56607a">24640 · 8ms budget</text>
+      <rect x="160" y="70" width="140" height="62" rx="9" fill="#1c2430" stroke="#2a3441"/>
+      <text x="230" y="90" fill="#e6edf3" font-weight="700">processPtyData</text>
+      <text x="230" y="106" fill="#9aa7b4">activity classifiers</text>
+      <text x="230" y="120" fill="#56607a">24451</text>
+      <rect x="330" y="58" width="170" height="86" rx="9" fill="#231a10" stroke="#5e4a1f"/>
+      <text x="415" y="78" fill="#f0c674" font-weight="700">flushOutput()</text>
+      <text x="415" y="94" fill="#9aa7b4">TUI redraw classifiers,</text>
+      <text x="415" y="108" fill="#9aa7b4">sync-frame holds, budget</text>
+      <text x="415" y="122" fill="#56607a">24222 · the hot path</text>
+      <rect x="530" y="70" width="140" height="62" rx="9" fill="#1c2430" stroke="#2a3441"/>
+      <text x="600" y="90" fill="#e6edf3" font-weight="700">WS 'output'</text>
+      <text x="600" y="106" fill="#9aa7b4">data + seq marker</text>
+      <text x="600" y="120" fill="#56607a">23281</text>
+      <rect x="700" y="58" width="180" height="86" rx="9" fill="#1c2430" stroke="#2a3441"/>
+      <text x="790" y="78" fill="#e6edf3" font-weight="700">client writer</text>
+      <text x="790" y="94" fill="#9aa7b4">onOutput → RAF queue</text>
+      <text x="790" y="108" fill="#9aa7b4">→ chunkedWrite → xterm</text>
+      <text x="790" y="122" fill="#56607a">33448 · 33162</text>
+    </g>
+    <line x1="130" y1="101" x2="160" y2="101" stroke="#58a6ff" marker-end="url(#a2)"/>
+    <line x1="300" y1="101" x2="330" y2="101" stroke="#58a6ff" marker-end="url(#a2)"/>
+    <line x1="500" y1="101" x2="530" y2="101" stroke="#58a6ff" marker-end="url(#a2)"/>
+    <line x1="670" y1="101" x2="700" y2="101" stroke="#58a6ff" marker-end="url(#a2)"/>
+  </svg>
+  <figcaption>The running pipeline. Each box adds latency-sensitive heuristics; <code>flushOutput()</code> alone runs the
+  Codex/Claude TUI-redraw classifiers, DEC-2026 synchronized-frame holds, a 64&nbsp;KB output budget, a 256&nbsp;KB bulk
+  fast-path, and flow-control watermarks.</figcaption>
+  </figure>
+  <div class="grid2">
+    <div class="card">
+      <h3 style="margin-top:0">Kept-worthy core (genuinely good)</h3>
+      <ul class="tight">
+        <li><b>Headless authoritative mirror</b> per session, serializable to any width <span class="ref">headless-term-service.js:54</span>.</li>
+        <li><b>Flush-delay classes</b> (1 / 8 / 32 ms) for snappy echo vs. coalesced frames <span class="ref">terminal-output-flush.js:47</span>.</li>
+        <li><b>Flow control</b> with PTY pause/resume at 128 KB/16 KB watermarks + 15 s watchdog <span class="ref">flow-control-policy.js:37</span>.</li>
+        <li><b>DEC-2026 synchronized-frame coalescing</b> (drop superseded full-clears) <span class="ref">coalesce-sync-frames.js</span>.</li>
+        <li><b>Primary/secondary viewer</b> width arbitration; secondaries get reflowed snapshots <span class="ref">server.js:26783</span>.</li>
+      </ul>
+    </div>
+    <div class="card">
+      <h3 style="margin-top:0">The reactive overlay (the problem)</h3>
+      <ul class="tight">
+        <li><b>Fingerprint divergence</b> — FNV-1a hash of the viewport, compared client vs. server <span class="ref">terminal-fingerprint.js:30</span>.</li>
+        <li><b>Pull repairs</b> — <code>snapshot</code> / <code>reflow</code> (SIGWINCH) / <code>reconcile</code> (re-serialize) <span class="ref">server.js:27315–27521</span>.</li>
+        <li><b>Heartbeat</b> — server emits fp twice per quiet episode, then silent <span class="ref">server.js:1334</span>.</li>
+        <li><b>Confirm gates</b> — divergence must persist 1 s; reflow cooldown 12 s → ×2ⁿ capped 5 min.</li>
+        <li><b>Heuristic garble detectors</b> — Claude stranded-right-fragment scans, stable-diverge while typing, flash-loop counters.</li>
+      </ul>
+    </div>
+  </div>
+</section>
+<!-- ============ 3 MATRIX ============ -->
+<section id="matrix">
+  <h2><span class="n">03</span>The Codex × Claude × running/stopped matrix</h2>
+  <p>What actually drives the frame in each state, and where it breaks. <span class="legend">
+    <span><span class="dot" style="background:#56d4c4"></span>Codex (ratatui, cursor-up repaints)</span>
+    <span><span class="dot" style="background:#d29922"></span>Claude (Ink, cursor-forward + truecolor)</span></span></p>
+  <table>
+    <thead><tr><th>State</th><th>What renders it</th><th>Failure mode</th><th>Current "fix"</th></tr></thead>
+    <tbody>
+      <tr>
+        <td><span class="pill codex">Codex</span> <span class="pill ok">running</span></td>
+        <td>Live byte stream; full-screen <code>\x1b[?2026h</code> synchronized repaints coalesced; "Working" busy-line keeps status <code>running</code> (15 s hold).</td>
+        <td>O(n²) SGR composer classifier &amp; sync-frame holds can stall the single event loop while typing; arrow keys vs. auto-approver race.</td>
+        <td><span class="pill both">patch</span> single-pass SGR boundaries + 32 KB ceiling + approver back-off <span class="ref">17efbb34</span></td>
+      </tr>
+      <tr>
+        <td><span class="pill codex">Codex</span> <span class="pill fail">stopped/idle</span></td>
+        <td>Last byte frame + heartbeat fp. Idle-frame divergence → <code>codexReconcileAction</code> drives a reflow with exponential backoff.</td>
+        <td>Giant session (12.5 k lines, ~800 KB/serialize) → serialize exceeds 3 s → server bridges a <i>dirty</i> cached frame → frame oscillates good↔bad.</td>
+        <td><span class="pill both">patch</span> refuse-to-bridge-stale-over-reflow + client backoff <span class="ref">ae4ac429</span></td>
+      </tr>
+      <tr>
+        <td><span class="pill claude">Claude</span> <span class="pill ok">running</span></td>
+        <td>Live byte stream; Ink redraws (<code>\x1b[?2026</code> or cursor-forward + truecolor); "Crunching"/"Working" busy-line.</td>
+        <td>Composer "wired state" garble mid-typing; width-reflow strands the status line into scrollback → false-idle.</td>
+        <td><span class="pill both">patch</span> stable-divergence draft-preserving SIGWINCH heal <span class="ref">ctm-composer-stable-diverge</span></td>
+      </tr>
+      <tr>
+        <td><span class="pill claude">Claude</span> <span class="pill fail">stopped/idle</span></td>
+        <td>Heartbeat fp; three garble detectors (viewport / scrollback / stable-diverge), each needing 2 sightings ≥1 s apart.</td>
+        <td><b>Switch to an idle tab at a stale width → no heartbeat → no 2nd sighting → never heals.</b> (The reported bug.)</td>
+        <td><span class="pill fail">none</span> — uncovered desync mode</td>
+      </tr>
+      <tr>
+        <td><span class="pill both">Both</span> <span class="pill ok">on tab switch</span></td>
+        <td><code>activateTab</code> → fit → <code>attach</code> (cached snapshot fast-path, else serialize at client dims) + 200 ms activation render check.</td>
+        <td>Idle tab: the one activation check compares vs. stale fp and bails; dims-reassert "so the next heartbeat is comparable" — but there is no next heartbeat.</td>
+        <td><span class="pill fail">gap</span> — activation grace exists but the signal to act on never arrives</td>
+      </tr>
+    </tbody>
+  </table>
+  <div class="callout warn"><p style="margin:0">Notice the pattern: <b>every cell's "fix" is a different mechanism</b> with
+  its own timers and provider conditionals. Four states × two providers have produced a fix surface that no longer fits in
+  one person's head — which is why the fifth gap (idle tab switch) went uncovered.</p></div>
+</section>
+<!-- ============ 4 SCOREBOARD ============ -->
+<section id="scoreboard">
+  <h2><span class="n">04</span>Complexity scoreboard — the "patch-on-patch" evidence</h2>
+  <div class="scoreboard">
+    <div class="metric"><div class="big">13</div><div class="lbl">distinct render-heal paths</div></div>
+    <div class="metric"><div class="big">7+</div><div class="lbl">independent timers / cooldowns</div></div>
+    <div class="metric"><div class="big">2</div><div class="lbl">status state machines (server + client)</div></div>
+    <div class="metric"><div class="big">~180</div><div class="lbl"><code>CTM_*</code> env knobs</div></div>
+  </div>
+  <h3>The 13 heal paths</h3>
+  <table>
+    <thead><tr><th>Heal</th><th>Trigger</th><th>Action</th><th>Scope</th><th>Window</th></tr></thead>
+    <tbody>
+      <tr><td>Heartbeat reconcile</td><td>output quiet 1 s</td><td>fp compare → maybe reconcile</td><td><span class="pill both">all</span></td><td>2 emits/episode</td></tr>
+      <tr><td>Settle-recheck</td><td>divergence armed</td><td>2nd sighting → confirm</td><td><span class="pill both">all</span></td><td>1.15 s</td></tr>
+      <tr><td>Activation render check</td><td>tab switch</td><td>run validators @200 ms</td><td><span class="pill both">all</span></td><td>200 ms + 1.5 s grace</td></tr>
+      <tr><td>Dims-reassert</td><td>fp dims ≠ grid</td><td>force resize</td><td><span class="pill both">all</span></td><td>2 s cooldown</td></tr>
+      <tr><td>Claude viewport garble</td><td>stranded right fragment</td><td>reflow (SIGWINCH)</td><td><span class="pill claude">claude</span></td><td>2 sightings, 12 s</td></tr>
+      <tr><td>Claude scrollback garble</td><td>fragment in scrollback</td><td>reconcile</td><td><span class="pill claude">claude</span></td><td>400-row scan, 12 s</td></tr>
+      <tr><td>Claude stable-diverge</td><td>stable fp mismatch while typing</td><td>draft-preserving reflow</td><td><span class="pill claude">claude</span></td><td>1.8 s</td></tr>
+      <tr><td>Codex idle-frame reflow</td><td>divergence on Codex</td><td>reflow + exp backoff</td><td><span class="pill codex">codex</span></td><td>12 s → ×2ⁿ ≤5 min</td></tr>
+      <tr><td>Flash-loop heal</td><td>3 reconciles/15 s</td><td>give-up memo or redraw</td><td><span class="pill both">split</span></td><td>30 s backoff</td></tr>
+      <tr><td>Giant-Codex oscillation guard</td><td>secondary reflow mismatch</td><td>restore headless to PTY dims</td><td><span class="pill codex">codex</span></td><td>per-serialize</td></tr>
+      <tr><td>Serialize-timeout bridge</td><td>serialize &gt; 3 s</td><td>serve cached frame (clean only for reflow)</td><td><span class="pill both">all</span></td><td>3 s</td></tr>
+      <tr><td>Lifecycle-adopt</td><td>pure lifecycle bump</td><td>adopt server seq</td><td><span class="pill both">all</span></td><td>per-heartbeat</td></tr>
+      <tr><td>3 s self-check loop</td><td>idle active tab</td><td>fp compare</td><td><span class="pill both">all</span></td><td>3 s</td></tr>
+    </tbody>
+  </table>
+  <p class="muted">Each row is individually defensible. Collectively they form a reactive controller with no single owner of
+  "is the frame correct?", overlapping cooldowns that interact in non-obvious ways (e.g. activation grace exists to punch
+  through the Codex 12 s reflow cooldown), and provider conditionals threaded through the hot path.</p>
+</section>
+<!-- ============ 5 SHOULD ============ -->
+<section id="should">
+  <h2><span class="n">05</span>How it should work — the established designs</h2>
+  <div class="grid2">
+    <div class="card">
+      <h3 style="margin-top:0">mosh — State Synchronization Protocol</h3>
+      <p style="margin-bottom:8px">mosh treats the remote terminal "more like a videoconference": the server runs the
+      authoritative emulator, and the protocol's <b>only</b> job is to <i>"fast-forward the client to the most recent
+      screen as efficiently as possible."</i> It synchronizes <b>screen-state objects (diffs)</b>, not byte streams, at a
+      controlled frame rate, and adds <b>predictive local echo</b> (≈70% of keystrokes shown in &lt;5 ms).</p>
+      <p style="margin-bottom:0" class="muted">Consequence: divergence <b>cannot persist</b> — every sync drives the
+      client toward truth. There is no "detect drift, then repair." There is only "render the current state."</p>
+    </div>
+    <div class="card">
+      <h3 style="margin-top:0">VS Code / @xterm/headless</h3>
+      <p style="margin-bottom:8px">VS Code runs a headless xterm server-side; <code>SerializeAddon.serialize()</code>
+      produces the full-state string that <b>is</b> the reconnect/revive path — applied <b>unconditionally</b> on attach
+      and reload, not as a divergence escape hatch.</p>
+      <p style="margin-bottom:0" class="muted">tmux and xterm.js agree: becoming visible / attaching triggers an
+      <b>unconditional</b> authoritative redraw (<code>server_redraw_client</code>; <code>clearTextureAtlas()</code> /
+      pause→resume → immediate catch-up). Never heuristic garble-sniffing.</p>
+    </div>
+  </div>
+  <div class="callout good">
+    <p style="margin:0"><b>The principle CTM is missing:</b> the client should be <b>continuously synchronized to the
+    server's authoritative screen state</b>, with "becoming visible / resizing / going quiet" as <i>unconditional</i> sync
+    triggers — not signals to <i>guess</i> whether a repair is needed. CTM already has the authoritative object (the
+    headless mirror). It just consults it reactively instead of treating it as the source of truth.</p>
+  </div>
+</section>
+<!-- ============ 6 OPTIONS ============ -->
+<section id="options">
+  <h2><span class="n">06</span>Redesign options</h2>
+  <div class="opt A">
+    <div class="head"><span class="badge">A</span><h3>"Keyframe on every boundary" — collapse the overlay into one rule</h3>
+    <span class="rec">RECOMMENDED · do now</span></div>
+    <div class="body">
+      <p>Keep the live byte stream for responsiveness (the <b>P-frames</b>), but <b>delete the entire detect-then-repair
+      zoo</b> and replace it with one deterministic rule: on every <b>activation / resize / output-quiet</b> boundary, the
+      server serializes the authoritative headless state <b>at the client's current dims</b> and the client renders it — an
+      unconditional <b>I-frame</b>. The keyframe is always truth at the right width, so a stale/stranded frame on switch is
+      structurally impossible.</p>
+      <figure>
+      <svg viewBox="0 0 860 96" role="img" aria-label="P-frames and I-frames timeline">
+        <g font-size="11" text-anchor="middle">
+          <line x1="20" y1="60" x2="840" y2="60" stroke="#2a3441"/>
+          <!-- P frames -->
+          <g fill="#58a6ff">
+            <rect x="60"  y="46" width="8" height="28" rx="2"/><rect x="90" y="46" width="8" height="28" rx="2"/>
+            <rect x="120" y="46" width="8" height="28" rx="2"/><rect x="150" y="46" width="8" height="28" rx="2"/>
+            <rect x="320" y="46" width="8" height="28" rx="2"/><rect x="350" y="46" width="8" height="28" rx="2"/>
+            <rect x="560" y="46" width="8" height="28" rx="2"/><rect x="590" y="46" width="8" height="28" rx="2"/>
+            <rect x="620" y="46" width="8" height="28" rx="2"/>
+          </g>
+          <!-- I frames -->
+          <g fill="#3fb950">
+            <rect x="200" y="34" width="14" height="40" rx="3"/>
+            <rect x="430" y="34" width="14" height="40" rx="3"/>
+            <rect x="700" y="34" width="14" height="40" rx="3"/>
+          </g>
+          <text x="207" y="26" fill="#3fb950">switch</text>
+          <text x="437" y="26" fill="#3fb950">resize</text>
+          <text x="707" y="26" fill="#3fb950">quiet</text>
+          <text x="110" y="92" fill="#58a6ff">live bytes (P)</text>
+          <text x="430" y="92" fill="#3fb950">authoritative keyframe (I)</text>
+        </g>
+      </svg>
+      <figcaption>Like video: cheap byte deltas between deterministic keyframes at every boundary.</figcaption>
+      </figure>
+      <div class="kv">
+        <div class="k">Deletes</div><div><span class="del">fingerprint divergence, settle-recheck, dims-reassert, Claude stale-width (×3 detectors), Codex idle-frame backoff, flash-loop heal, stable-diverge, 3 s self-check, heartbeat-as-repair-signal.</span></div>
+        <div class="k">Keeps</div><div><span class="keep">byte stream + flush classes, flow control, DEC-2026 coalescing, headless serialize, primary/secondary arbitration.</span></div>
+        <div class="k">Risk</div><div><b>Low–medium.</b> Keyframe cost on giant sessions (~800 KB serialize) is bounded by the existing 3 s timeout + cache; debounce quiet-keyframes; reuse the oscillation guard's "don't bridge stale over a keyframe" rule.</div>
+        <div class="k">Effort</div><div>Server: one keyframe emitter at dims. Client: render keyframe on boundary, delete ~13 heal paths + their timers. Net <b>large deletion</b>.</div>
+      </div>
+      <p class="muted" style="margin-bottom:0">Note: my earlier "fp-probe on activation" idea was ~1/13th of this — it
+      <i>added</i> a 14th mechanism. Option A <i>removes</i> the other 13 instead.</p>
+    </div>
+  </div>
+  <div class="opt B">
+    <div class="head"><span class="badge">B</span><h3>Full mosh-style state-sync — the north star</h3></div>
+    <div class="body">
+      <p>Go all the way: the client never treats raw bytes as authoritative. The server computes <b>screen-cell diffs</b>
+      against the client's last-acked frame and ships those at a controlled frame rate, plus predictive local echo for
+      keystrokes. Absolute-position fragility disappears entirely — a "stranded right fragment" is unrepresentable because
+      the client only ever holds whole, server-computed frames.</p>
+      <div class="kv">
+        <div class="k">Wins</div><div>Eliminates the entire desync class; natural roaming/reconnect; frame-rate control already solves giant-session flooding.</div>
+        <div class="k">Cost</div><div><b>High.</b> New diff protocol + applier; reworks the live path, not just the repair path; predictive echo is subtle. A multi-month effort.</div>
+        <div class="k">Verdict</div><div>Document as the target. Option A is a strict subset of this thinking and a stepping stone — its keyframes become B's periodic full-syncs.</div>
+      </div>
+    </div>
+  </div>
+  <div class="opt C">
+    <div class="head"><span class="badge">C</span><h3>Unify status — one server-authoritative state machine</h3></div>
+    <div class="body">
+      <p>Orthogonal but compounding: collapse the <b>two</b> status machines (server <code>_standupLiveStatusWithReason</code>
+      + client <code>getSessionStatus</code>, ~10 freshness TTLs) into <b>one</b> server-authoritative status pushed to the
+      client. Remove client-side spinner / busy-line re-derivation (the "Working"/"Crunching" scanning, Codex running-holds,
+      garbled-busy-line regexes).</p>
+      <div class="kv">
+        <div class="k">Why now</div><div>Status currently <i>gates</i> rendering (running ⇒ skip heal). Once A makes keyframes deterministic, the client no longer needs to <i>infer</i> running-ness to decide whether to repair — it just renders keyframes. Status becomes pure display.</div>
+        <div class="k">Risk</div><div>Low; mostly deletion. Server already computes the authoritative status; the client half is redundant inference.</div>
+      </div>
+    </div>
+  </div>
+  <div class="callout"><p style="margin:0"><b>Recommendation:</b> <b>A + C now.</b> Together they capture ~90% of the
+  benefit primarily by <i>deletion</i> — one keyframe rule, one status owner — and directly close the reported bug as a
+  structural impossibility rather than a 14th patch. Keep <b>B</b> on the roadmap as the eventual target if A's keyframe
+  cost on the largest sessions becomes the limiting factor.</p></div>
+</section>
+<!-- ============ 7 MIGRATION ============ -->
+<section id="migration">
+  <h2><span class="n">07</span>Migration sketch (A + C)</h2>
+  <table>
+    <thead><tr><th>Phase</th><th>Change</th><th>Reversible?</th></tr></thead>
+    <tbody>
+      <tr><td><b>1 · Keyframe emitter</b></td><td>Server: a single "serialize headless at client dims → send frame" used by attach, resize, and a debounced output-quiet boundary. (Generalizes today's <code>reconcile</code>/secondary-push.)</td><td>Behind <code>CTM_KEYFRAME_SYNC</code>, default off → on.</td></tr>
+      <tr><td><b>2 · Client renders boundaries</b></td><td>Client requests/applies a keyframe unconditionally on activation + resize; keeps applying P-frame bytes between keyframes.</td><td>Flag-gated; old path still present.</td></tr>
+      <tr><td><b>3 · Delete the overlay</b></td><td>Remove the 13 heal paths + their timers/constants once keyframes prove out in <code>/ctm-dev</code> + render tests. <span class="strike">fingerprint divergence, stale-width ×3, flash-loop, dims-reassert, …</span></td><td>Staged; each deletion behind green render tests.</td></tr>
+      <tr><td><b>4 · Unify status (C)</b></td><td>Push authoritative status from server; delete client busy-line inference + the second state machine.</td><td>Independent of 1–3.</td></tr>
+      <tr><td><b>5 · (optional) B</b></td><td>Promote keyframes to periodic cell-diffs + predictive echo when/if giant-session keyframe cost demands it.</td><td>Long-horizon.</td></tr>
+    </tbody>
+  </table>
+  <div class="callout good"><p style="margin:0"><b>Success criteria.</b> The Codex×Claude×running/stopped matrix has one
+  rendering rule per axis, not one per cell. The reported bug is closed by construction (switching renders a keyframe at
+  current dims). The heal-path count drops from 13 → ~1, timers from 7+ → ~1 (keyframe debounce), status machines from
+  2 → 1. Verified on an isolated <code>/ctm-dev</code> instance with the existing Playwright render suite — never the
+  primary.</p></div>
+</section>
+<hr class="soft">
+<section>
+  <h3>Sources</h3>
+  <ul class="src">
+    <li><a href="https://mosh.org/mosh-paper.pdf">Mosh: An Interactive Remote Shell for Mobile Clients</a> — the State Synchronization Protocol (screen-state objects, frame-rate control, predictive echo).</li>
+    <li><a href="https://mosh.org/">mosh.org</a> — "synchronizes only the visible state of the terminal."</li>
+    <li><a href="https://code.visualstudio.com/docs/terminal/advanced">VS Code — Terminal Advanced</a> — process reconnection &amp; revive via serialized headless state.</li>
+    <li><a href="https://github.com/xtermjs/xterm.js/issues/880">xterm.js #880</a> — pause/resume renderer &amp; force-redraw-on-resume for hidden terminals.</li>
+    <li><a href="https://man7.org/linux/man-pages/man1/tmux.1.html">tmux(1)</a> — server-driven redraw on attach/resize.</li>
+  </ul>
+  <p class="muted src">Every <code>path:line</code> anchor (e.g. <code>server.js:24222</code>, <code>index.html:33448</code>,
+  <code>headless-term-service.js:54</code>, <code>terminal-reconciler.js:169</code>) is traceable in the current
+  <code>ux</code> worktree and was gathered from four read-only code sweeps of the live tree on 2026-06-17.</p>
+</section>
+<footer>
+  CTM terminal-rendering design review · prepared 2026-06-17 · read-only analysis, no app code changed in this round.
+  Implementation of Options&nbsp;A/B/C is deferred until a direction is chosen.
+</footer>
+</div>
+</body>
+</html>

package/template/claude-task-manager/lib/flush-redraw-markers.js ADDED Viewed

@@ -0,0 +1,72 @@
+'use strict';
+// Pure marker predicates for the PTY flush "is this an interactive TUI redraw?"
+// classifiers (server.js _isRecentCodexNativeSkillRedraw / _isCodexSynchronizedTuiRedraw /
+// _isClaudeTuiRedraw). Extracted out of the per-session closures so they can be unit-tested
+// and so the expensive stripAnsi + alternation-regex work runs over the VISIBLE TAIL of the
+// batch instead of the whole coalesced batch.
+//
+// WHY THE TAIL: during heavy Codex/Claude repaint bursts a single flush batch can hold many
+// stacked full-screen frames (observed 132KB, [freeze-probe] flush:classify-detect blocked
+// 342ms). The classifiers only need to know whether the VISIBLE frame is an interactive redraw,
+// and the visible state is always at the END of the batch (later frames paint over earlier
+// ones). So we strip + regex-test only the last `tailBytes` of the batch. A marker that appears
+// ONLY in an earlier, superseded frame is by definition not visible, so bounding to the tail is
+// behavior-preserving for the on-screen result (and strictly cheaper). Set tailBytes<=0 to scan
+// the whole batch (the pre-extraction behavior).
+//
+// The regexes below are copied VERBATIM from the server.js closures so detection is byte-identical
+// on any batch whose markers fall within the tail window.
+// Default visible-tail window. A single rendered screen (even ~100 rows x ~300 cols with SGR)
+// strips to well under this; 64KB of raw tail is a comfortable margin. Tunable via
+// CTM_REDRAW_CLASSIFY_TAIL_BYTES (0 = scan whole batch).
+const DEFAULT_TAIL_BYTES = (() => {
+  const v = Number(process.env.CTM_REDRAW_CLASSIFY_TAIL_BYTES);
+  return Number.isFinite(v) && v >= 0 ? v : 65536;
+})();
+// Strip ANSI from only the visible tail of `batch` using the caller's (memoized) stripAnsi.
+// Passing the SAME stripAnsi keeps server.js's single-slot memo authoritative; equal-content
+// slices are === in JS so repeated calls within one flush hit the memo.
+function markerTailText(batch, stripAnsiFn, tailBytes = DEFAULT_TAIL_BYTES) {
+  const raw = String(batch == null ? '' : batch);
+  const tail = tailBytes > 0 && raw.length > tailBytes ? raw.slice(-tailBytes) : raw;
+  return stripAnsiFn(tail);
+}
+// --- Codex native $-skill picker / composer redraw (was _isRecentCodexNativeSkillRedraw tail) ---
+const _CODEX_DOLLAR_PROMPT_RE = /(?:^|\n)\s*[›>]\s*[^\n]*\$/m;
+const _CODEX_DOLLAR_INLINE_RE = /[›>]\s*[^\n\r]{0,240}\$[A-Za-z0-9_.:-]*/;
+const _CODEX_PICKER_RE = /\[Skill\]|Press enter to insert|esc to close|no matches/i;
+const _CODEX_MODEL_CONT_RE = /\b(?:gpt-[\w.-]+|o\d|claude|sonnet|opus|haiku|deepseek|gemini|qwen|llama|mistral|kimi|moonshot)\b[^\n]*(?:\b(?:x?high|medium|low|fast)\b|[~/]|[-·])/i;
+function hasCodexSkillRedrawMarkers(text) {
+  const hasPromptWithDollarTrigger =
+    _CODEX_DOLLAR_PROMPT_RE.test(text) || _CODEX_DOLLAR_INLINE_RE.test(text);
+  if (!hasPromptWithDollarTrigger) return false;
+  if (_CODEX_PICKER_RE.test(text)) return true;
+  return _CODEX_MODEL_CONT_RE.test(text);
+}
+// --- Codex synchronized full-screen TUI redraw (was _isCodexSynchronizedTuiRedraw tail) ---
+const _CODEX_SYNC_TUI_RE = /Working|esc to interrupt|Conversation interrupted|Explored|Ran|Read|Search|Use \/skills|\bgpt-[\w.-]+|\b(?:x?high|medium|low)\b.*(?:fast|[~/])/i;
+function hasCodexSyncTuiMarkers(text) {
+  return _CODEX_SYNC_TUI_RE.test(text);
+}
+// --- Claude Code Ink TUI redraw (was _isClaudeTuiRedraw tail) ---
+const _CLAUDE_TUI_RE = /Crunching|esc to interrupt|Esc to cancel|Do you want to|Bash(?:\(| command)?|Read\(|Edit\(|Write\(|Grep\(|Glob\(|TodoWrite|tokens|thought for|ctrl\+o to expand|⎿|Claude Code|Working|Cogitating|Forming|plan mode|accept edits|shift\+tab|for agents|running stop hooks|[❯⏵]/i;
+function hasClaudeTuiMarkers(text) {
+  return _CLAUDE_TUI_RE.test(text);
+}
+module.exports = {
+  DEFAULT_TAIL_BYTES,
+  markerTailText,
+  hasCodexSkillRedrawMarkers,
+  hasCodexSyncTuiMarkers,
+  hasClaudeTuiMarkers,
+};