The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix(plan-canvas): deliver browser chat to the agent every time (#2739)
haelyraae303fb6c19e
diff --git a/.agents/skills/plan-canvas/SKILL.md b/.agents/skills/plan-canvas/SKILL.mdindex 72ea5aef6..8b77e1e26 100644--- a/.agents/skills/plan-canvas/SKILL.md+++ b/.agents/skills/plan-canvas/SKILL.md@@ -46,12 +46,31 @@ Codex — or just run the `ecc-plan-canvas` commands directly.# 1. Open the artifact in the user's browser (returns immediately)ecc-plan-canvas open .claude/plans/feature.plan.md-# 2. Block until the human responds. Leave running; re-run if interrupted —-# queued feedback is never lost. Run in the background if your harness-# time-limits foreground commands.+# 2. Block until the human responds. Leave running; re-run if interrupted:+# queued feedback is never lost.ecc-plan-canvas await .claude/plans/feature.plan.md```+### Stay listening, or the human talks to an empty chair++Feedback only reaches you while an `await` is actually parked on the session.+If your turn ends with nothing listening, the message sits in the queue and,+from the human's side of the glass, sending appears to do nothing at all.++So **run `await` as a background task** when your harness supports one (in+Claude Code, a Bash call with `run_in_background: true`). It exits the moment+feedback arrives and the harness hands you the JSON, which keeps the loop alive+across turns instead of dying with the foreground call. A foreground `await`+works too, but only until the harness time-limits it.++Two backstops exist, and neither is an excuse to skip the above:++- `ecc-plan-canvas pending` lists feedback queued with no listener. Check it+ whenever you are unsure whether you missed something.+- The `stop:plan-canvas-pending` hook blocks your turn from ending while canvas+ feedback is undelivered, and hands you the messages. If you are reading+ feedback from that hook, you stopped listening too early.+`await` prints JSON when the human acts:```json@@ -73,12 +92,31 @@ ecc-plan-canvas await .claude/plans/feature.plan.mdend the session, and start implementing. `request-changes` means revise theartifact (the canvas live-reloads it) and keep the loop going.-**3. Respond in the canvas**, then keep listening — one command does both:+**3. Always respond in the canvas**, then keep listening. One command does both:```bash-ecc-plan-canvas await <file> --reply "Split Phase 2 as requested — take a look."+ecc-plan-canvas await <file> --reply "Split Phase 2 as requested. Take a look."```+Every human message gets a reply in the canvas, even a one-liner like+"On it, rewriting the risk table now." Silence in the chat panel is+indistinguishable from a broken canvas, which is exactly the failure this loop+exists to prevent. Answer there, not only in the terminal.++While you work, keep the chat honest with the activity indicator:++```bash+# animated "agent is thinking..." bubble; refresh it during long work+ecc-plan-canvas typing <file> --state thinking+# switch to "agent is typing..." just before a reply lands+ecc-plan-canvas typing <file> --state typing+```++`await` sets `thinking` for you the moment it hands you a batch, and `--reply`+clears it. Both states self-expire, so a crashed agent decays to an honest+"queued" instead of leaving the human watching dots forever. Refresh `thinking`+if a revision takes more than a minute.+**4. End** when review concludes: `ecc-plan-canvas end <file>`.## Diagrams (Mermaid)@@ -143,8 +181,13 @@ ecc-plan-canvas await <file> --reply "Reworked the risk table."## Anti-Patterns-- Polling with `--timeout-ms` in a loop — it exists for tests. Leave the- plain `await` running instead.+- Polling with `--timeout-ms` in a loop. It exists for tests. Leave the plain+ `await` running instead.+- Ending your turn with no `await` listening while the review is still open.+ That is the one failure the human experiences as "I sent a message and+ nothing happened".+- Reading the feedback but answering only in the terminal. The human is looking+ at the canvas.- Reopening after a user-initiated end "just to show" something.- Pasting the whole plan into chat *and* opening a canvas — pick the canvasand keep the terminal summary to one line.diff --git a/hooks/hooks.json b/hooks/hooks.jsonindex 00ab4d0aa..2eb1ef3ea 100644--- a/hooks/hooks.json+++ b/hooks/hooks.json@@ -174,6 +174,17 @@}],"Stop": [+ {+ "matcher": "*",+ "hooks": [+ {+ "type": "command",+ "command": "node -e \"const fs=require('fs');const path=require('path');const {spawnSync}=require('child_process');const raw=fs.readFileSync(0,'utf8');const finish=(out,err,code)=>{let pending=1;const done=()=>{pending-=1;if(pending===0)process.exit(code);};if(out){pending+=1;process.stdout.write(out,done);}if(err){pending+=1;process.stderr.write(err,done);}process.nextTick(done);};const rel=path.join('scripts','hooks','run-with-flags.js');const root=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const script=path.join(root,rel);if(fs.existsSync(script)){const result=spawnSync(process.execPath,[script,'stop:plan-canvas-pending','scripts/hooks/plan-canvas-pending.js','minimal,standard,strict'],{input:raw,encoding:'utf8',env:process.env,cwd:process.cwd(),timeout:30000,maxBuffer:16*1024*1024});const failed=result.error||result.status===null||result.signal;const stdout=!failed&&typeof result.stdout==='string'?result.stdout:'';let stderr=typeof result.stderr==='string'?result.stderr:'';let code=Number.isInteger(result.status)?result.status:0;if(failed){const reason=result.error?result.error.message:(result.signal?'signal '+result.signal:'missing exit status');stderr+='[Stop] ERROR: hook runner failed: '+reason+String.fromCharCode(10);code=1;}finish(stdout,stderr,code);}else{finish(raw,'[Stop] WARNING: could not resolve ECC plugin root; skipping hook'+String.fromCharCode(10),0);}\""+ }+ ],+ "description": "Deliver undelivered Plan Canvas browser feedback before the agent stops",+ "id": "stop:plan-canvas-pending"+ },{"matcher": "*","hooks": [diff --git a/scripts/hooks/plan-canvas-pending.js b/scripts/hooks/plan-canvas-pending.jsnew file mode 100644index 000000000..9ba2a9207--- /dev/null+++ b/scripts/hooks/plan-canvas-pending.js@@ -0,0 +1,226 @@+#!/usr/bin/env node+/**+ * Plan Canvas undelivered-feedback guard (Stop)+ *+ * Cross-platform (Windows, macOS, Linux)+ *+ * Browser feedback only reaches an agent while that agent is parked inside+ * `ecc-plan-canvas await`. The moment a turn ends, nothing is listening, so+ * messages the human sends land in sessions.json and stay there: the canvas+ * looks alive, the agent never hears a word.+ *+ * This hook closes that gap. On Stop it drains any undelivered feedback for+ * the current project and blocks the stop, handing the messages to the agent+ * as its next input, so a canvas message is delivered even when no `await`+ * was running.+ *+ * Scope: sessions whose artifact lives under the hook's cwd, so parallel+ * agents in other repos cannot swallow a message meant for this one. Set+ * ECC_PLAN_CANVAS_STOP_SCOPE=all to consider every open session.+ *+ * Never blocks on failure: any error, unreachable server, or undrainable+ * queue exits 0 with stdin passed through.+ */++'use strict';++const fs = require('fs');+const http = require('http');+const os = require('os');+const path = require('path');++// Loopback only, and short: a Stop hook must not stall the turn if the canvas+// server is wedged. Falling back to the state file keeps delivery working.+const SERVER_TIMEOUT_MS = 1000;+const MAX_ITEMS_REPORTED = 20;++function stateDir() {+ const override = process.env.ECC_PLAN_CANVAS_STATE_DIR;+ if (override && override.trim()) return path.resolve(override.trim());+ return path.join(os.homedir(), '.claude', 'plan-canvas');+}++function readState() {+ try {+ const parsed = JSON.parse(fs.readFileSync(path.join(stateDir(), 'sessions.json'), 'utf8'));+ return parsed && typeof parsed === 'object' && parsed.sessions ? parsed : null;+ } catch {+ return null;+ }+}++function readServerPort() {+ try {+ const info = JSON.parse(fs.readFileSync(path.join(stateDir(), 'server.json'), 'utf8'));+ return Number.isInteger(info.port) ? info.port : null;+ } catch {+ return null;+ }+}++function isInside(dir, file) {+ if (!dir) return true;+ const base = path.resolve(dir);+ const target = path.resolve(file);+ return target === base || target.startsWith(base + path.sep);+}++/**+ * Sessions holding feedback the agent has never seen, oldest activity first.+ */+function pendingSessions(state, cwd, env = process.env) {+ const scopeAll = String(env.ECC_PLAN_CANVAS_STOP_SCOPE || '').trim().toLowerCase() === 'all';+ return Object.values((state && state.sessions) || {})+ .filter(session => session && session.status !== 'ended')+ .filter(session => Array.isArray(session.pendingFeedback) && session.pendingFeedback.length > 0)+ .filter(session => (scopeAll ? true : isInside(cwd, session.file)))+ .sort((a, b) => String(a.updatedAt || '').localeCompare(String(b.updatedAt || '')));+}++/**+ * Ask the running server to hand over the batch. The server owns sessions.json+ * while it is up, so this is the only race-free way to drain. timeoutMs=0+ * makes /api/await return immediately instead of long polling.+ */+function drainViaServer(port, key) {+ return new Promise(resolve => {+ const req = http.request(+ {+ host: '127.0.0.1',+ port,+ method: 'GET',+ path: `/api/await?key=${encodeURIComponent(key)}&timeoutMs=0`,+ agent: false+ },+ res => {+ let data = '';+ res.on('data', chunk => {+ data += chunk;+ });+ res.on('end', () => {+ try {+ const parsed = JSON.parse(data.trim() || '{}');+ resolve(parsed.status === 'feedback' && Array.isArray(parsed.items) ? parsed : null);+ } catch {+ resolve(null);+ }+ });+ }+ );+ req.setTimeout(SERVER_TIMEOUT_MS, () => {+ req.destroy();+ resolve(null);+ });+ req.on('error', () => resolve(null));+ req.end();+ });+}++/**+ * Drain straight from disk. Only safe when no server is listening, which is+ * exactly when this path runs: with the server down nothing else mutates the+ * file, and leaving the items queued would re-block on every future Stop.+ */+function drainViaFile(key) {+ const file = path.join(stateDir(), 'sessions.json');+ try {+ const state = JSON.parse(fs.readFileSync(file, 'utf8'));+ const session = state.sessions && state.sessions[key];+ if (!session || !Array.isArray(session.pendingFeedback) || session.pendingFeedback.length === 0) {+ return null;+ }+ const items = session.pendingFeedback;+ const sessionEnded = session.status === 'ended';+ session.pendingFeedback = [];+ if (!sessionEnded) session.status = 'open';+ session.updatedAt = new Date().toISOString();+ const tmp = `${file}.tmp`;+ fs.writeFileSync(tmp, JSON.stringify(state, null, 2));+ fs.renameSync(tmp, file);+ return { status: 'feedback', items, sessionEnded };+ } catch {+ return null;+ }+}++function describeItem(item) {+ if (!item || typeof item !== 'object') return null;+ if (item.kind === 'verdict') {+ const label = item.verdict === 'approve' ? 'APPROVED the plan' : 'REQUESTED CHANGES';+ return item.text ? `${label}: ${item.text}` : label;+ }+ if (item.kind === 'annotation') {+ const anchor = item.anchor || {};+ const where = anchor.snippet || anchor.selector || 'the artifact';+ return item.text ? `on "${where}": ${item.text}` : null;+ }+ return item.text || null;+}++function buildReason(delivered) {+ const lines = [+ 'Plan Canvas: the human sent feedback in the browser that was never delivered to you.',+ 'Handle it now instead of ending the turn.',+ ''+ ];+ for (const entry of delivered) {+ lines.push(`Artifact: ${entry.file}`);+ for (const text of entry.messages.slice(0, MAX_ITEMS_REPORTED)) lines.push(` - ${text}`);+ const extra = entry.messages.length - MAX_ITEMS_REPORTED;+ if (extra > 0) lines.push(` - (+${extra} more)`);+ if (entry.sessionEnded) {+ lines.push(' The user ended this review after sending. Address the feedback and report back in');+ lines.push(' your normal reply; do not reopen the canvas.');+ } else {+ lines.push(' Reply IN THE CANVAS so the human sees it, and keep listening, with one command:');+ lines.push(` ecc-plan-canvas await ${JSON.stringify(entry.file)} --reply "<what you did>"`);+ }+ lines.push('');+ }+ lines.push('Run that await in the background so the next message reaches you without another Stop.');+ return lines.join('\n');+}++async function collectDeliveries(sessions, port) {+ const delivered = [];+ for (const session of sessions) {+ const result = port ? await drainViaServer(port, session.key) : drainViaFile(session.key);+ // A failed drain is deliberately not reported: blocking on feedback that+ // is still queued would re-fire on every subsequent Stop.+ if (!result) continue;+ const messages = result.items.map(describeItem).filter(Boolean);+ if (messages.length === 0) continue;+ delivered.push({ file: session.file, messages, sessionEnded: Boolean(result.sessionEnded) });+ }+ return delivered;+}++async function run(rawInput) {+ const passThrough = { stdout: rawInput || '', exitCode: 0 };+ let payload = {};+ try {+ payload = JSON.parse(rawInput || '{}');+ } catch {+ return passThrough;+ }++ // The harness sets this once it has already resumed the agent from a Stop+ // hook. Blocking again from here is how a hook wedges a session.+ if (payload.stop_hook_active) return passThrough;++ const state = readState();+ if (!state) return passThrough;++ const sessions = pendingSessions(state, payload.cwd || process.cwd());+ if (sessions.length === 0) return passThrough;++ const delivered = await collectDeliveries(sessions, readServerPort());+ if (delivered.length === 0) return passThrough;++ return {+ stdout: JSON.stringify({ decision: 'block', reason: buildReason(delivered) }),+ exitCode: 0+ };+}++module.exports = { run, pendingSessions, describeItem, buildReason, drainViaFile };diff --git a/scripts/hooks/run-with-flags.js b/scripts/hooks/run-with-flags.jsindex a49bd4fa9..9f6de3722 100755--- a/scripts/hooks/run-with-flags.js+++ b/scripts/hooks/run-with-flags.js@@ -220,7 +220,11 @@ async function main() {if (hookModule && typeof hookModule.run === 'function') {try {- const output = hookModule.run(raw, {+ // Awaited so a hook may export `async run()`. Without this an async hook+ // hands back a pending Promise, which resolveHookResult reads as "no+ // opinion" and silently degrades to pass-through. Synchronous hooks are+ // unaffected: awaiting a plain value just costs a microtask.+ const output = await hookModule.run(raw, {hookId,pluginRoot,scriptPath,diff --git a/scripts/lib/plan-canvas/server.js b/scripts/lib/plan-canvas/server.jsindex 2c250c73e..11b44062a 100644--- a/scripts/lib/plan-canvas/server.js+++ b/scripts/lib/plan-canvas/server.js@@ -29,6 +29,14 @@ const DEFAULT_PORT = 4517;const DEFAULT_HOST = '127.0.0.1';const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;const MAX_BODY_BYTES = 1024 * 1024;+// How long the "agent is thinking" indicator survives without the agent+// checking back in, before presence decays to the honest queued/waiting.+const DEFAULT_THINKING_STALE_MS = 90 * 1000;+// An explicit typing signal expires faster: it means "a reply is seconds away".+const DEFAULT_TYPING_EXPIRY_MS = 30 * 1000;+// Presence is push-based, so expiring states need a tick to re-broadcast on.+const DEFAULT_PRESENCE_SWEEP_MS = 5 * 1000;+const TYPING_STATES = new Set(['thinking', 'typing', 'idle']);const CONTENT_TYPES = {'.css': 'text/css; charset=utf-8',@@ -109,6 +117,9 @@ function createPlanCanvasServer({version = '0.0.0',idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,heartbeatMs = 15000,+ thinkingStaleMs = DEFAULT_THINKING_STALE_MS,+ typingExpiryMs = DEFAULT_TYPING_EXPIRY_MS,+ presenceSweepMs = DEFAULT_PRESENCE_SWEEP_MS,onIdleShutdown = null,log = () => {}} = {}) {@@ -119,18 +130,40 @@ function createPlanCanvasServer({wake.setMaxListeners(0);const sseClients = new Map(); // key -> Set<res>const awaitCounts = new Map(); // key -> active long-poll count- const workingKeys = new Set(); // keys whose agent took feedback and is off working+ const workingKeys = new Map(); // key -> ms timestamp the agent took feedback+ const typingKeys = new Map(); // key -> ms timestamp the agent signalled composingconst watchers = new Map(); // key -> fs.FSWatcher+ const lastPresence = new Map(); // key -> last broadcast state, for sweep diffinglet idleTimer = null;+ let presenceSweep = null;let closed = false;// --- presence + SSE ---------------------------------------------------- function presenceFor(key) {+ /**+ * Presence never claims more than the server actually knows:+ *+ * ended session is closed+ * typing agent signalled it is composing a reply (self-expiring)+ * thinking agent took the feedback and is working on it (self-expiring)+ * listening an `await` long poll is parked on this session right now+ * queued feedback is sitting undelivered with nobody listening+ * waiting nothing queued, nobody listening+ *+ * `thinking` and `typing` expire on their own so a crashed or distracted+ * agent decays to an honest `queued`/`waiting` instead of spinning forever.+ * The old `working` pill had no expiry and no re-broadcast, so it stuck at+ * "agent working" while nothing at all was listening.+ */+ function presenceFor(key, now = Date.now()) {const session = store.get(key);if (!session || session.status === 'ended') return 'ended';+ const typingAt = typingKeys.get(key);+ if (typingAt !== undefined && now - typingAt < typingExpiryMs) return 'typing';+ const workingAt = workingKeys.get(key);+ if (workingAt !== undefined && now - workingAt < thinkingStaleMs) return 'thinking';if ((awaitCounts.get(key) || 0) > 0) return 'listening';- return workingKeys.has(key) ? 'working' : 'waiting';+ return session.pendingFeedback && session.pendingFeedback.length > 0 ? 'queued' : 'waiting';}function broadcast(key, event, payload) {@@ -141,7 +174,36 @@ function createPlanCanvasServer({}function broadcastPresence(key) {- broadcast(key, 'presence', { state: presenceFor(key) });+ const state = presenceFor(key);+ lastPresence.set(key, state);+ broadcast(key, 'presence', { state });+ }++ // Re-broadcast only where an expiry actually changed the answer, so an+ // untouched canvas sees the thinking bubble clear itself.+ function sweepPresence() {+ for (const key of sseClients.keys()) {+ const state = presenceFor(key);+ if (lastPresence.get(key) !== state) broadcastPresence(key);+ }+ }++ function startPresenceSweep() {+ if (presenceSweep || !presenceSweepMs) return;+ presenceSweep = setInterval(sweepPresence, presenceSweepMs);+ if (presenceSweep.unref) presenceSweep.unref();+ }++ // The agent is off working on this feedback batch; start the thinking clock.+ function markThinking(key) {+ workingKeys.set(key, Date.now());+ typingKeys.delete(key);+ }++ // A reply landed (or the agent picked the session back up): stop pretending.+ function clearAgentActivity(key) {+ workingKeys.delete(key);+ typingKeys.delete(key);}function connectionCount() {@@ -205,6 +267,7 @@ function createPlanCanvasServer({function endSession(key, endedBy) {const session = store.end(key, endedBy);if (!session) return null;+ clearAgentActivity(key);wake.emit(`wake:${key}`);broadcast(key, 'ended', { endedBy: session.endedBy });broadcastPresence(key);@@ -260,7 +323,7 @@ function createPlanCanvasServer({const first = store.takeFeedback(key);if (first.status !== 'waiting') {- if (first.status === 'feedback') workingKeys.add(key);+ if (first.status === 'feedback') markThinking(key);broadcastPresence(key);return sendJson(res, 200, first);}@@ -268,7 +331,7 @@ function createPlanCanvasServer({// Long poll: hold the request open until feedback or session end.noteConnectionOpened();awaitCounts.set(key, (awaitCounts.get(key) || 0) + 1);- workingKeys.delete(key);+ clearAgentActivity(key);broadcastPresence(key);let settled = false;@@ -279,7 +342,7 @@ function createPlanCanvasServer({settled = true;cleanup();if (payload) {- if (payload.status === 'feedback') workingKeys.add(key);+ if (payload.status === 'feedback') markThinking(key);res.end(JSON.stringify(payload));}broadcastPresence(key);@@ -328,7 +391,7 @@ function createPlanCanvasServer({return sendJson(res, 200, { status: 'ended', endedBy: 'agent' });}- const sessionMatch = pathname.match(/^\/api\/session\/([a-f0-9]{12})\/(feedback|end|reply)$/);+ const sessionMatch = pathname.match(/^\/api\/session\/([a-f0-9]{12})\/(feedback|end|reply|typing)$/);if (sessionMatch && req.method === 'POST') {const [, key, action] = sessionMatch;const session = store.get(key);@@ -341,7 +404,17 @@ function createPlanCanvasServer({wake.emit(`wake:${key}`);broadcast(key, 'chat-sync', { chat: store.get(key).chat });if (body.endSession) broadcast(key, 'ended', { endedBy: 'user' });- return sendJson(res, 200, { status: 'queued', accepted: result.accepted.length, pending: result.pending });+ // A parked `await` takes the batch synchronously on the wake above, so+ // presence is already `thinking` by now; with nobody listening it+ // reports `queued`. Either way the browser must be told, which the+ // original handler never did, leaving a stale pill on screen.+ broadcastPresence(key);+ return sendJson(res, 200, {+ status: 'queued',+ accepted: result.accepted.length,+ pending: result.pending,+ presence: presenceFor(key)+ });}if (action === 'end') {@@ -355,9 +428,26 @@ function createPlanCanvasServer({return sendJson(res, 400, { error: 'text is required' });}const entry = store.addAgentReply(key, body.text);+ clearAgentActivity(key);broadcast(key, 'chat-sync', { chat: store.get(key).chat });+ broadcastPresence(key);return sendJson(res, 200, { status: 'sent', at: entry.at });}++ // Agents drive the chat indicator explicitly: `thinking` while they work,+ // `typing` right before a reply lands, `idle` to take the bubble down.+ if (action === 'typing') {+ const body = await readJsonBody(req);+ const state = typeof body.state === 'string' ? body.state : 'typing';+ if (!TYPING_STATES.has(state)) {+ return sendJson(res, 400, { error: `state must be one of: ${[...TYPING_STATES].join(', ')}` });+ }+ if (state === 'idle') clearAgentActivity(key);+ else if (state === 'typing') typingKeys.set(key, Date.now());+ else markThinking(key);+ broadcastPresence(key);+ return sendJson(res, 200, { status: 'ok', presence: presenceFor(key) });+ }}return sendJson(res, 404, { error: 'not found' });@@ -376,6 +466,8 @@ function createPlanCanvasServer({res.write(`event: presence\ndata: ${JSON.stringify({ state: presenceFor(key) })}\n\n`);if (!sseClients.has(key)) sseClients.set(key, new Set());sseClients.get(key).add(res);+ lastPresence.set(key, presenceFor(key));+ startPresenceSweep();const ping = setInterval(() => res.write(': ping\n\n'), 25000);if (ping.unref) ping.unref();req.on('close', () => {@@ -383,7 +475,10 @@ function createPlanCanvasServer({const clients = sseClients.get(key);if (clients) {clients.delete(res);- if (clients.size === 0) sseClients.delete(key);+ if (clients.size === 0) {+ sseClients.delete(key);+ lastPresence.delete(key);+ }}noteConnectionClosed();});@@ -499,6 +594,9 @@ function createPlanCanvasServer({function close() {closed = true;clearTimeout(idleTimer);+ clearInterval(presenceSweep);+ presenceSweep = null;+ lastPresence.clear();for (const key of watchers.keys()) unwatchSession(key);for (const clients of sseClients.values()) {for (const client of clients) client.end();@@ -522,12 +620,14 @@ function createPlanCanvasServer({});}- return { server, listen, close, presenceFor, watchSession };+ return { server, listen, close, presenceFor, sweepPresence, watchSession };}module.exports = {DEFAULT_HOST,DEFAULT_PORT,+ DEFAULT_THINKING_STALE_MS,+ DEFAULT_TYPING_EXPIRY_MS,createPlanCanvasServer,resolveIdleTimeoutMs,resolvePortdiff --git a/scripts/lib/plan-canvas/ui.js b/scripts/lib/plan-canvas/ui.jsindex 0432282f6..a9815aa69 100644--- a/scripts/lib/plan-canvas/ui.js+++ b/scripts/lib/plan-canvas/ui.js@@ -103,7 +103,8 @@ function canvasCss() {.presence{display:flex;align-items:center;gap:6px;font-size:11px;font-weight:500;color:var(--text2);background:var(--bg3);border:1px solid var(--border);border-radius:99px;padding:3px 10px 3px 8px;white-space:nowrap}.presence .dot{width:7px;height:7px;border-radius:99px;background:var(--text3)}.presence[data-state="listening"] .dot{background:var(--green);box-shadow:0 0 0 3px var(--green-glow);animation:pulse 2s infinite}- .presence[data-state="working"] .dot{background:var(--orange);box-shadow:0 0 0 3px var(--orange-glow)}+ .presence[data-state="thinking"] .dot,.presence[data-state="typing"] .dot{background:var(--accent);box-shadow:0 0 0 3px var(--accent-glow);animation:pulse 1.2s infinite}+ .presence[data-state="queued"] .dot{background:var(--orange);box-shadow:0 0 0 3px var(--orange-glow)}@keyframes pulse{0%,100%{opacity:1}50%{opacity:.45}}.toggle{display:flex;align-items:center;gap:7px;font-size:11.5px;color:var(--text2);cursor:pointer;user-select:none}@@ -140,6 +141,23 @@ function canvasCss() {.msg.kind-verdict{border-left:2px solid var(--green)}.chat .empty{color:var(--text3);font-size:12px;text-align:center;margin-top:24px;line-height:1.6}+ /* iMessage-style activity bubble: dots while the agent thinks or types. */+ .typing{align-self:flex-start;display:none;align-items:center;gap:8px;background:var(--bg3);border:1px solid var(--border);border-bottom-left-radius:3px;border-radius:10px;padding:9px 12px}+ .typing.show{display:flex}+ .typing .dots{display:flex;align-items:center;gap:3px}+ .typing .dots i{width:6px;height:6px;border-radius:99px;background:var(--text2);animation:typing-bounce 1.4s infinite ease-in-out both}+ .typing .dots i:nth-child(1){animation-delay:-.32s}+ .typing .dots i:nth-child(2){animation-delay:-.16s}+ .typing .label{font-size:11px;color:var(--text3)}+ @keyframes typing-bounce{0%,80%,100%{transform:translateY(0);opacity:.4}40%{transform:translateY(-4px);opacity:1}}+ @media (prefers-reduced-motion:reduce){+ .typing .dots i{animation:none;opacity:.7}+ .presence .dot{animation:none}+ }+ /* A queued message nobody is listening for gets an explicit, honest note. */+ .stalled{align-self:flex-start;display:none;gap:8px;background:var(--orange-glow);border:1px solid color-mix(in srgb,var(--orange) 35%,transparent);border-radius:10px;padding:8px 11px;font-size:11.5px;color:var(--text2);line-height:1.5}+ .stalled.show{display:flex}+.queue{padding:8px 14px 0;display:flex;flex-direction:column;gap:6px;max-height:180px;overflow-y:auto}.pill{display:flex;align-items:flex-start;gap:8px;background:var(--bg3);border:1px solid var(--border);border-left:2px solid var(--teal);border-radius:6px;padding:6px 8px;font-size:11.5px}.pill.kind-chat{border-left-color:var(--accent)}@@ -267,27 +285,69 @@ function canvasClientJs() {}renderQueue();+ // --- activity indicators ---------------------------------------------+ // Built once and re-appended on every chat render so the animation never+ // restarts mid-thought.+ const typingEl = document.createElement('div');+ typingEl.className = 'typing';+ typingEl.setAttribute('role', 'status');+ typingEl.setAttribute('aria-live', 'polite');+ const dots = document.createElement('span');+ dots.className = 'dots';+ dots.append(document.createElement('i'), document.createElement('i'), document.createElement('i'));+ const typingLabel = document.createElement('span');+ typingLabel.className = 'label';+ typingEl.append(dots, typingLabel);++ const stalledEl = document.createElement('div');+ stalledEl.className = 'stalled';+ stalledEl.setAttribute('role', 'status');++ const TYPING_LABELS = { thinking: 'agent is thinking\\u2026', typing: 'agent is typing\\u2026' };++ function renderActivity(state) {+ const typingText = TYPING_LABELS[state];+ typingEl.classList.toggle('show', Boolean(typingText));+ if (typingText) typingLabel.textContent = typingText;+ const stalled = state === 'queued';+ stalledEl.classList.toggle('show', stalled);+ if (stalled) {+ stalledEl.textContent =+ 'Delivered to the queue. Your agent is not listening right now, so it picks this up the moment it checks in.';+ }+ if (typingText || stalled) scrollToEnd();+ }+// --- chat -----------------------------------------------------------+ function atBottom() {+ return chatLog.scrollHeight - chatLog.scrollTop - chatLog.clientHeight < 40;+ }+ function scrollToEnd() { chatLog.scrollTop = chatLog.scrollHeight; }+function renderChat(entries) {+ const pinned = atBottom();chatLog.innerHTML = '';if (!entries.length) {const empty = document.createElement('div');empty.className = 'empty';empty.textContent = 'Click anything in the plan to annotate it, or type below. Feedback goes straight to your agent.';chatLog.appendChild(empty);- return;- }- for (const entry of entries) {- const div = document.createElement('div');- div.className = 'msg ' + (entry.role === 'agent' ? 'agent' : 'user') + ' kind-' + (entry.kind || 'chat');- div.textContent = entry.text;- const meta = document.createElement('span');- meta.className = 'meta';- meta.textContent = (entry.role === 'agent' ? 'agent' : 'you') + ' \\u00B7 ' + new Date(entry.at).toLocaleTimeString();- div.appendChild(meta);- chatLog.appendChild(div);+ } else {+ for (const entry of entries) {+ const div = document.createElement('div');+ div.className = 'msg ' + (entry.role === 'agent' ? 'agent' : 'user') + ' kind-' + (entry.kind || 'chat');+ div.textContent = entry.text;+ const meta = document.createElement('span');+ meta.className = 'meta';+ meta.textContent = (entry.role === 'agent' ? 'agent' : 'you') + ' \\u00B7 ' + new Date(entry.at).toLocaleTimeString();+ div.appendChild(meta);+ chatLog.appendChild(div);+ }}- chatLog.scrollTop = chatLog.scrollHeight;+ // The indicators live at the tail of the log, so they survive re-render.+ chatLog.appendChild(typingEl);+ chatLog.appendChild(stalledEl);+ if (pinned) scrollToEnd();}renderChat(boot.chat || []);@@ -312,11 +372,17 @@ function canvasClientJs() {body: JSON.stringify({ items })});if (!res.ok) throw new Error('HTTP ' + res.status);+ const body = await res.json().catch(() => ({}));queue = [];persistQueue();renderQueue();input.value = '';- statusEl.textContent = 'Sent. Your agent picks this up on its next check-in.';+ // Say what actually happened: a parked agent takes the batch on the+ // spot, otherwise it sits in the queue until the agent checks in.+ statusEl.textContent = body.presence === 'thinking' || body.presence === 'typing'+ ? 'Delivered. Your agent has it.'+ : 'Queued. Your agent picks this up the moment it checks in.';+ if (body.presence) applyPresence(body.presence);} catch (err) {statusEl.textContent = 'Send failed (' + err.message + ') - is the canvas server still running?';} finally {@@ -345,6 +411,7 @@ function canvasClientJs() {ended = true;sendBtn.disabled = true;input.disabled = true;+ renderActivity('ended');presence.setAttribute('data-state', 'ended');presence.querySelector('.label').textContent = 'session ended';$('endedOverlay').classList.add('show');@@ -355,20 +422,28 @@ function canvasClientJs() {if (ended) markEnded(boot.endedBy);// --- server events ----------------------------------------------------- const PRESENCE_LABELS = { waiting: 'agent not connected', listening: 'agent listening', working: 'agent working\\u2026' };+ const PRESENCE_LABELS = {+ waiting: 'agent not connected',+ listening: 'agent listening',+ thinking: 'agent is thinking\\u2026',+ typing: 'agent is typing\\u2026',+ queued: 'queued for your agent'+ };+ function applyPresence(state) {+ if (ended) return;+ presence.setAttribute('data-state', state);+ presence.querySelector('.label').textContent = PRESENCE_LABELS[state] || state;+ renderActivity(state);+ }function connectEvents() {const es = new EventSource('/events/' + key);es.addEventListener('chat-sync', e => renderChat(JSON.parse(e.data).chat || []));- es.addEventListener('presence', e => {- const state = JSON.parse(e.data).state;- if (ended) return;- presence.setAttribute('data-state', state);- presence.querySelector('.label').textContent = PRESENCE_LABELS[state] || state;- });+ es.addEventListener('presence', e => applyPresence(JSON.parse(e.data).state));es.addEventListener('reload', reloadArtifact);es.addEventListener('ended', e => { markEnded(JSON.parse(e.data).endedBy); es.close(); });es.onerror = () => {if (ended) return;+ renderActivity('offline');presence.setAttribute('data-state', 'waiting');presence.querySelector('.label').textContent = 'canvas server offline';};diff --git a/scripts/plan-canvas.js b/scripts/plan-canvas.jsindex 5c26fb59a..816a0be7b 100755--- a/scripts/plan-canvas.js+++ b/scripts/plan-canvas.js@@ -45,7 +45,7 @@ const SAFE_REQUEST_PATHS = new Set(['/api/sessions','/api/end']);-const SESSION_REPLY_PATH = /^\/api\/session\/[a-f0-9]{12}\/reply$/;+const SESSION_REPLY_PATH = /^\/api\/session\/[a-f0-9]{12}\/(reply|typing)$/;function usage() {return [@@ -55,6 +55,8 @@ function usage() {' node scripts/plan-canvas.js Show server status and sessions',' node scripts/plan-canvas.js open <file> Open (or resume) a review session',' node scripts/plan-canvas.js await <file> Block until the human sends feedback',+ ' node scripts/plan-canvas.js pending Show feedback queued for no listener',+ ' node scripts/plan-canvas.js typing <file> Show a thinking/typing indicator in chat',' node scripts/plan-canvas.js end <file> End a session as the agent',' node scripts/plan-canvas.js stop Shut down the canvas server',' node scripts/plan-canvas.js server Run the server in the foreground',@@ -64,6 +66,7 @@ function usage() {' --reopen Reopen a session the user ended from the browser',' await: --reply <msg> Show an agent reply in the canvas chat before waiting',' --timeout-ms <n> Return {status:"waiting"} after n ms (tests/debug only)',+ ' typing: --state <thinking|typing|idle> Defaults to typing',' server: --port <n> --host <h>','','Environment: ECC_PLAN_CANVAS_PORT, ECC_PLAN_CANVAS_STATE_DIR, ECC_PLAN_CANVAS_IDLE_MS'@@ -293,6 +296,35 @@ async function cmdAwait(file, args, { stateDir, port }) {return result;}+// Show the human an activity indicator in the canvas chat. Cheap and+// fire-and-forget: a failed signal must never derail the actual work.+async function cmdTyping(file, args, { port }) {+ if (!file) throw new Error('typing requires a file path');+ const state = valueAfter(args, '--state') || 'typing';+ if (!(await healthCheck(port))) return { status: 'no-server' };+ const key = sessionKeyFor(canonicalizeArtifactPath(file));+ const res = await request(port, 'POST', `/api/session/${key}/typing`, { state });+ if (res.statusCode !== 200) throw new Error(res.body.error || `typing failed (HTTP ${res.statusCode})`);+ return { status: 'ok', state, presence: res.body.presence };+}++// Report feedback the human sent that no agent has picked up yet. Reads state+// directly so it answers even when the server has idled out.+function cmdPending({ stateDir }) {+ const store = createSessionStore({ stateDir });+ const waiting = store+ .list()+ .filter(session => session.status !== 'ended' && session.pending > 0)+ .map(session => ({ file: session.file, pending: session.pending, updatedAt: session.updatedAt }));+ return {+ status: waiting.length ? 'pending' : 'clear',+ sessions: waiting,+ next_step: waiting.length+ ? 'Run `ecc-plan-canvas await <file>` for each file above to receive the messages.'+ : 'No canvas feedback is waiting.'+ };+}+async function cmdEnd(file, { port }) {if (!file) throw new Error('end requires a file path');if (!(await healthCheck(port))) return { status: 'no-server' };@@ -359,6 +391,8 @@ async function main(argv = process.argv.slice(2)) {if (command === null) output(await cmdStatus(context));else if (command === 'open') output(await cmdOpen(args[0], args, context));else if (command === 'await') output(await cmdAwait(args[0], args, context));+ else if (command === 'pending') output(cmdPending(context));+ else if (command === 'typing') output(await cmdTyping(args[0], args, context));else if (command === 'end') output(await cmdEnd(args[0], context));else if (command === 'stop') output(await cmdStop(context));else if (command === 'server') await cmdServer(args, context);diff --git a/skills/plan-canvas/SKILL.md b/skills/plan-canvas/SKILL.mdindex 342033fde..fd45baf6f 100644--- a/skills/plan-canvas/SKILL.md+++ b/skills/plan-canvas/SKILL.md@@ -47,12 +47,31 @@ Codex — or just run the `ecc-plan-canvas` commands directly.# 1. Open the artifact in the user's browser (returns immediately)ecc-plan-canvas open .claude/plans/feature.plan.md-# 2. Block until the human responds. Leave running; re-run if interrupted —-# queued feedback is never lost. Run in the background if your harness-# time-limits foreground commands.+# 2. Block until the human responds. Leave running; re-run if interrupted:+# queued feedback is never lost.ecc-plan-canvas await .claude/plans/feature.plan.md```+### Stay listening, or the human talks to an empty chair++Feedback only reaches you while an `await` is actually parked on the session.+If your turn ends with nothing listening, the message sits in the queue and,+from the human's side of the glass, sending appears to do nothing at all.++So **run `await` as a background task** when your harness supports one (in+Claude Code, a Bash call with `run_in_background: true`). It exits the moment+feedback arrives and the harness hands you the JSON, which keeps the loop alive+across turns instead of dying with the foreground call. A foreground `await`+works too, but only until the harness time-limits it.++Two backstops exist, and neither is an excuse to skip the above:++- `ecc-plan-canvas pending` lists feedback queued with no listener. Check it+ whenever you are unsure whether you missed something.+- The `stop:plan-canvas-pending` hook blocks your turn from ending while canvas+ feedback is undelivered, and hands you the messages. If you are reading+ feedback from that hook, you stopped listening too early.+`await` prints JSON when the human acts:```json@@ -74,12 +93,31 @@ ecc-plan-canvas await .claude/plans/feature.plan.mdend the session, and start implementing. `request-changes` means revise theartifact (the canvas live-reloads it) and keep the loop going.-**3. Respond in the canvas**, then keep listening — one command does both:+**3. Always respond in the canvas**, then keep listening. One command does both:```bash-ecc-plan-canvas await <file> --reply "Split Phase 2 as requested — take a look."+ecc-plan-canvas await <file> --reply "Split Phase 2 as requested. Take a look."```+Every human message gets a reply in the canvas, even a one-liner like+"On it, rewriting the risk table now." Silence in the chat panel is+indistinguishable from a broken canvas, which is exactly the failure this loop+exists to prevent. Answer there, not only in the terminal.++While you work, keep the chat honest with the activity indicator:++```bash+# animated "agent is thinking..." bubble; refresh it during long work+ecc-plan-canvas typing <file> --state thinking+# switch to "agent is typing..." just before a reply lands+ecc-plan-canvas typing <file> --state typing+```++`await` sets `thinking` for you the moment it hands you a batch, and `--reply`+clears it. Both states self-expire, so a crashed agent decays to an honest+"queued" instead of leaving the human watching dots forever. Refresh `thinking`+if a revision takes more than a minute.+**4. End** when review concludes: `ecc-plan-canvas end <file>`.## Diagrams (Mermaid)@@ -144,8 +182,13 @@ ecc-plan-canvas await <file> --reply "Reworked the risk table."## Anti-Patterns-- Polling with `--timeout-ms` in a loop — it exists for tests. Leave the- plain `await` running instead.+- Polling with `--timeout-ms` in a loop. It exists for tests. Leave the plain+ `await` running instead.+- Ending your turn with no `await` listening while the review is still open.+ That is the one failure the human experiences as "I sent a message and+ nothing happened".+- Reading the feedback but answering only in the terminal. The human is looking+ at the canvas.- Reopening after a user-initiated end "just to show" something.- Pasting the whole plan into chat *and* opening a canvas — pick the canvasand keep the terminal summary to one line.diff --git a/tests/hooks/plan-canvas-pending-hook.test.js b/tests/hooks/plan-canvas-pending-hook.test.jsnew file mode 100644index 000000000..43545bc98--- /dev/null+++ b/tests/hooks/plan-canvas-pending-hook.test.js@@ -0,0 +1,194 @@+/**+ * Integration tests for scripts/hooks/plan-canvas-pending.js (Stop)+ *+ * The hook is the delivery guarantee for canvas chat: without it, feedback the+ * human sends while no `await` is parked simply never reaches the agent.+ *+ * Run with: node tests/hooks/plan-canvas-pending-hook.test.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');++const HOOK = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'plan-canvas-pending.js');++async function test(name, fn) {+ try {+ await fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++function freshStateDir() {+ return fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-pending-'));+}++function writeState(stateDir, sessions) {+ fs.mkdirSync(stateDir, { recursive: true });+ fs.writeFileSync(path.join(stateDir, 'sessions.json'), JSON.stringify({ sessions, feedbackCounter: 0 }, null, 2));+}++function sessionRecord(key, file, pendingFeedback, overrides = {}) {+ const at = '2026-01-01T00:00:00.000Z';+ return {+ key,+ file,+ status: pendingFeedback.length ? 'feedback' : 'open',+ chat: [],+ pendingFeedback,+ createdAt: at,+ updatedAt: at,+ ...overrides+ };+}++function readPending(stateDir, key) {+ const state = JSON.parse(fs.readFileSync(path.join(stateDir, 'sessions.json'), 'utf8'));+ return state.sessions[key].pendingFeedback;+}++// The hook resolves the state dir at call time, so the env var has to be set+// before each invocation; a fresh require keeps the cases independent.+function loadHook(stateDir) {+ delete require.cache[require.resolve(HOOK)];+ process.env.ECC_PLAN_CANVAS_STATE_DIR = stateDir;+ return require(HOOK);+}++async function runTests() {+ console.log('\n=== Testing plan-canvas-pending Stop hook ===\n');+ let passed = 0;+ let failed = 0;+ const originalStateDir = process.env.ECC_PLAN_CANVAS_STATE_DIR;++ if (await test('blocks the stop and hands over undelivered feedback', async () => {+ const stateDir = freshStateDir();+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-project-'));+ const artifact = path.join(projectDir, 'feature.plan.md');+ writeState(stateDir, {+ aaaaaaaaaaaa: sessionRecord('aaaaaaaaaaaa', artifact, [+ { id: 'fb-1', kind: 'chat', text: 'move phase 2 up', at: '2026-01-01T00:00:00.000Z' }+ ])+ });+ const hook = loadHook(stateDir);+ const result = await hook.run(JSON.stringify({ cwd: projectDir, stop_hook_active: false }));+ const decision = JSON.parse(result.stdout);+ assert.strictEqual(decision.decision, 'block');+ assert.ok(decision.reason.includes('move phase 2 up'), 'reason carries the message text');+ assert.ok(decision.reason.includes('--reply'), 'reason tells the agent to answer in the canvas');+ // Drained, so the next Stop does not block on the same message.+ assert.deepStrictEqual(readPending(stateDir, 'aaaaaaaaaaaa'), []);+ })) passed++; else failed++;++ if (await test('a drained queue does not block a second time', async () => {+ const stateDir = freshStateDir();+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-project-'));+ const artifact = path.join(projectDir, 'feature.plan.md');+ writeState(stateDir, {+ aaaaaaaaaaaa: sessionRecord('aaaaaaaaaaaa', artifact, [+ { id: 'fb-1', kind: 'chat', text: 'first', at: '2026-01-01T00:00:00.000Z' }+ ])+ });+ const hook = loadHook(stateDir);+ const input = JSON.stringify({ cwd: projectDir });+ const first = await hook.run(input);+ assert.strictEqual(JSON.parse(first.stdout).decision, 'block');+ const second = await hook.run(input);+ assert.strictEqual(second.stdout, input, 'second stop passes stdin through');+ })) passed++; else failed++;++ if (await test('never blocks twice in a row via stop_hook_active', async () => {+ const stateDir = freshStateDir();+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-project-'));+ writeState(stateDir, {+ aaaaaaaaaaaa: sessionRecord('aaaaaaaaaaaa', path.join(projectDir, 'a.plan.md'), [+ { id: 'fb-1', kind: 'chat', text: 'hello', at: '2026-01-01T00:00:00.000Z' }+ ])+ });+ const hook = loadHook(stateDir);+ const input = JSON.stringify({ cwd: projectDir, stop_hook_active: true });+ const result = await hook.run(input);+ assert.strictEqual(result.stdout, input);+ assert.strictEqual(readPending(stateDir, 'aaaaaaaaaaaa').length, 1, 'nothing drained');+ })) passed++; else failed++;++ if (await test('ignores sessions outside the project, unless scope=all', async () => {+ const stateDir = freshStateDir();+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-project-'));+ const otherDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-other-'));+ const state = {+ bbbbbbbbbbbb: sessionRecord('bbbbbbbbbbbb', path.join(otherDir, 'other.plan.md'), [+ { id: 'fb-1', kind: 'chat', text: 'not yours', at: '2026-01-01T00:00:00.000Z' }+ ])+ };+ writeState(stateDir, state);+ const hook = loadHook(stateDir);+ assert.strictEqual(hook.pendingSessions({ sessions: state }, projectDir, {}).length, 0);+ assert.strictEqual(+ hook.pendingSessions({ sessions: state }, projectDir, { ECC_PLAN_CANVAS_STOP_SCOPE: 'all' }).length,+ 1+ );+ })) passed++; else failed++;++ if (await test('ended sessions and empty queues are left alone', async () => {+ const stateDir = freshStateDir();+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-project-'));+ const state = {+ cccccccccccc: sessionRecord(+ 'cccccccccccc',+ path.join(projectDir, 'ended.plan.md'),+ [{ id: 'fb-1', kind: 'chat', text: 'stale', at: '2026-01-01T00:00:00.000Z' }],+ { status: 'ended', endedBy: 'user' }+ ),+ dddddddddddd: sessionRecord('dddddddddddd', path.join(projectDir, 'quiet.plan.md'), [])+ };+ writeState(stateDir, state);+ const hook = loadHook(stateDir);+ assert.strictEqual(hook.pendingSessions({ sessions: state }, projectDir, {}).length, 0);+ const input = JSON.stringify({ cwd: projectDir });+ assert.strictEqual((await hook.run(input)).stdout, input);+ })) passed++; else failed++;++ if (await test('renders annotations and verdicts readably', async () => {+ const hook = loadHook(freshStateDir());+ assert.strictEqual(+ hook.describeItem({ kind: 'annotation', text: 'split this', anchor: { snippet: 'Phase 2' } }),+ 'on "Phase 2": split this'+ );+ assert.strictEqual(hook.describeItem({ kind: 'verdict', verdict: 'approve' }), 'APPROVED the plan');+ assert.strictEqual(+ hook.describeItem({ kind: 'verdict', verdict: 'request-changes', text: 'too vague' }),+ 'REQUESTED CHANGES: too vague'+ );+ assert.strictEqual(hook.describeItem({ kind: 'chat', text: '' }), null);+ assert.strictEqual(hook.describeItem(null), null);+ })) passed++; else failed++;++ if (await test('malformed stdin and a missing state dir fail open', async () => {+ const hook = loadHook(path.join(os.tmpdir(), 'plan-canvas-does-not-exist-xyz'));+ assert.strictEqual((await hook.run('not json')).stdout, 'not json');+ assert.strictEqual((await hook.run('{}')).exitCode, 0);+ })) passed++; else failed++;++ if (originalStateDir === undefined) delete process.env.ECC_PLAN_CANVAS_STATE_DIR;+ else process.env.ECC_PLAN_CANVAS_STATE_DIR = originalStateDir;++ console.log('\n========================================');+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log('========================================\n');+ return failed === 0;+}++if (require.main === module) {+ runTests().then(ok => process.exit(ok ? 0 : 1));+}++module.exports = { runTests };diff --git a/tests/scripts/plan-canvas.test.js b/tests/scripts/plan-canvas.test.jsindex 7d164c999..5d1e8745f 100644--- a/tests/scripts/plan-canvas.test.js+++ b/tests/scripts/plan-canvas.test.js@@ -253,11 +253,120 @@ async function main() {assert.strictEqual(result.items[0].anchor.selector, 'h2:nth-of-type(1)');assert.strictEqual(result.items[1].verdict, 'request-changes');- await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'working'));+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'thinking'));await waitFor(() => sse.received.some(e => e.event === 'chat-sync' && e.data.chat.length === 2));sse.close();})) passed++; else failed++;+ // Regression: feedback sent with nobody parked on `await` used to leave the+ // pill claiming "agent working" while the message sat undelivered forever.+ if (await test('feedback with no listener reports queued, not working', async () => {+ const queuedArtifact = path.join(tmp, 'queued.plan.md');+ fs.writeFileSync(queuedArtifact, '# Plan: Queued\n');+ const opened = jsonBody(await request(port, 'POST', '/api/sessions', { body: { file: queuedArtifact } }));+ const sse = openSse(port, opened.key);+ await sse.ready;+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'waiting'));++ const post = await request(port, 'POST', `/api/session/${opened.key}/feedback`, {+ body: { items: [{ kind: 'chat', text: 'anyone there?' }] }+ });+ assert.strictEqual(jsonBody(post).presence, 'queued');+ assert.strictEqual(canvas.presenceFor(opened.key), 'queued');+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'queued'));++ // Draining it hands the batch over and flips the indicator to thinking.+ const drained = jsonBody(await request(port, 'GET', `/api/await?key=${opened.key}&timeoutMs=0`));+ assert.strictEqual(drained.status, 'feedback');+ assert.strictEqual(canvas.presenceFor(opened.key), 'thinking');+ sse.close();+ })) passed++; else failed++;++ if (await test('typing endpoint drives the indicator and reply clears it', async () => {+ const typingArtifact = path.join(tmp, 'typing.plan.md');+ fs.writeFileSync(typingArtifact, '# Plan: Typing\n');+ const opened = jsonBody(await request(port, 'POST', '/api/sessions', { body: { file: typingArtifact } }));+ const sse = openSse(port, opened.key);+ await sse.ready;++ const typing = await request(port, 'POST', `/api/session/${opened.key}/typing`, { body: { state: 'typing' } });+ assert.strictEqual(jsonBody(typing).presence, 'typing');+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'typing'));++ const thinking = await request(port, 'POST', `/api/session/${opened.key}/typing`, { body: { state: 'thinking' } });+ assert.strictEqual(jsonBody(thinking).presence, 'thinking');++ const bad = await request(port, 'POST', `/api/session/${opened.key}/typing`, { body: { state: 'dancing' } });+ assert.strictEqual(bad.statusCode, 400);++ // A landed reply must take the bubble down, not leave it spinning.+ await request(port, 'POST', `/api/session/${opened.key}/reply`, { body: { text: 'done' } });+ assert.strictEqual(canvas.presenceFor(opened.key), 'waiting');+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'waiting'));+ sse.close();+ })) passed++; else failed++;++ if (await test('thinking and typing states expire instead of sticking', async () => {+ const staleArtifact = path.join(tmp, 'stale.plan.md');+ fs.writeFileSync(staleArtifact, '# Plan: Stale\n');+ const staleStore = createSessionStore({ stateDir: path.join(tmp, 'stale-state') });+ const staleCanvas = createPlanCanvasServer({+ store: staleStore,+ version: '9.9.9-test',+ idleTimeoutMs: 0,+ thinkingStaleMs: 40,+ typingExpiryMs: 20,+ presenceSweepMs: 0+ });+ const bound = await staleCanvas.listen(0);+ const opened = jsonBody(await request(bound.port, 'POST', '/api/sessions', { body: { file: staleArtifact } }));++ await request(bound.port, 'POST', `/api/session/${opened.key}/typing`, { body: { state: 'typing' } });+ assert.strictEqual(staleCanvas.presenceFor(opened.key), 'typing');+ await new Promise(resolve => setTimeout(resolve, 60));+ assert.strictEqual(staleCanvas.presenceFor(opened.key), 'waiting');++ // An abandoned agent decays to queued so the human is never told a+ // stalled session is still being worked on.+ await request(bound.port, 'POST', `/api/session/${opened.key}/typing`, { body: { state: 'thinking' } });+ await request(bound.port, 'POST', `/api/session/${opened.key}/feedback`, {+ body: { items: [{ kind: 'chat', text: 'still there?' }] }+ });+ assert.strictEqual(staleCanvas.presenceFor(opened.key), 'thinking');+ await new Promise(resolve => setTimeout(resolve, 60));+ assert.strictEqual(staleCanvas.presenceFor(opened.key), 'queued');+ await staleCanvas.close();+ })) passed++; else failed++;++ // The stuck pill only self-heals if the decay is pushed to an idle browser+ // that is not making any requests of its own.+ if (await test('presence sweep pushes the decayed state to an idle browser', async () => {+ const sweepArtifact = path.join(tmp, 'sweep.plan.md');+ fs.writeFileSync(sweepArtifact, '# Plan: Sweep\n');+ const sweepStore = createSessionStore({ stateDir: path.join(tmp, 'sweep-state') });+ const sweepCanvas = createPlanCanvasServer({+ store: sweepStore,+ version: '9.9.9-test',+ idleTimeoutMs: 0,+ thinkingStaleMs: 50,+ presenceSweepMs: 20+ });+ const bound = await sweepCanvas.listen(0);+ const opened = jsonBody(await request(bound.port, 'POST', '/api/sessions', { body: { file: sweepArtifact } }));+ const sse = openSse(bound.port, opened.key);+ await sse.ready;++ await request(bound.port, 'POST', `/api/session/${opened.key}/typing`, { body: { state: 'thinking' } });+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'thinking'));++ const before = sse.received.length;+ await waitFor(() =>+ sse.received.slice(before).some(e => e.event === 'presence' && e.data.state === 'waiting')+ );+ sse.close();+ await sweepCanvas.close();+ })) passed++; else failed++;+if (await test('long-poll heartbeat whitespace arrives before the payload', async () => {const chunks = [];const done = new Promise((resolve, reject) => {