@yemi33/squad 0.1.17 → 0.1.18

package/dashboard.html

@@ -151,7 +151,7 @@
   .prd-item-priority.low { background: rgba(139,148,158,0.15); color: var(--muted); }
   .prd-project-badge { font-size: 9px; padding: 1px 5px; border-radius: 6px; background: rgba(56,139,253,0.12); color: var(--blue); border: 1px solid rgba(56,139,253,0.25); white-space: nowrap; }
 
-  .notes-preview { max-height: 240px; overflow-y: auto; font-size: 12px; line-height: 1.6; color: var(--muted); font-family: Consolas, monospace; white-space: pre-wrap; word-wrap: break-word; background: var(--surface2); border: 1px solid var(--border); border-radius: 6px; padding: 12px 14px; cursor: pointer; transition: border-color 0.2s; }
+  .notes-preview { max-height: 400px; overflow-y: auto; font-size: 12px; line-height: 1.6; color: var(--muted); font-family: Consolas, monospace; white-space: pre-wrap; word-wrap: break-word; background: var(--surface2); border: 1px solid var(--border); border-radius: 6px; padding: 12px 14px; cursor: pointer; transition: border-color 0.2s; }
   .notes-preview:hover { border-color: var(--blue); }
   .inbox-item { background: var(--surface2); border: 1px solid var(--border); border-left: 3px solid var(--purple); border-radius: 4px; padding: 10px 12px; cursor: pointer; }
   .inbox-item:hover { border-color: var(--blue); border-left-color: var(--blue); }
@@ -553,7 +553,7 @@
   </section>
 
   <section>
-    <h2>Team Notes</h2>
+    <h2>Team Notes <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0" id="notes-updated"></span></h2>
     <div id="notes-list">Loading...</div>
   </section>
 
@@ -621,6 +621,9 @@
     <div class="modal-header">
       <h3 id="modal-title">—</h3>
       <div class="modal-header-actions">
+        <button class="modal-copy" id="modal-edit-btn" onclick="modalToggleEdit()" title="Edit" style="display:none"><svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor"><path d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25c.081-.286.235-.547.445-.758l8.61-8.61zM12.9 2.97L4.288 11.58l-.537 1.878 1.878-.537L14.242 4.31 12.9 2.97z"/></svg> Edit</button>
+        <button class="modal-copy" id="modal-save-btn" onclick="modalSaveEdit()" title="Save" style="display:none;color:var(--green);border-color:var(--green)"><svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor"><path d="M13.78 4.22a.75.75 0 010 1.06l-7.25 7.25a.75.75 0 01-1.06 0L2.22 9.28a.75.75 0 011.06-1.06L6 10.94l6.72-6.72a.75.75 0 011.06 0z"/></svg> Save</button>
+        <button class="modal-copy" id="modal-cancel-edit-btn" onclick="modalCancelEdit()" title="Cancel edit" style="display:none">Cancel</button>
         <button class="modal-copy" id="modal-copy-btn" onclick="copyModalContent()" title="Copy to clipboard"><svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 010 1.5h-1.5a.25.25 0 00-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 00.25-.25v-1.5a.75.75 0 011.5 0v1.5A1.75 1.75 0 019.25 16h-7.5A1.75 1.75 0 010 14.25z"/><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0114.25 11h-7.5A1.75 1.75 0 015 9.25zm1.75-.25a.25.25 0 00-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 00.25-.25v-7.5a.25.25 0 00-.25-.25z"/></svg> Copy</button>
         <button class="modal-close" onclick="closeModal()">X</button>
       </div>
@@ -938,20 +941,87 @@ async function openInboxInExplorer(name) {
 
 function renderNotes(notes) {
   const el = document.getElementById('notes-list');
-  if (!notes || !notes.trim()) { el.innerHTML = '<p class="empty">No team notes yet.</p>'; return; }
-  el.innerHTML = '<div class="notes-preview" onclick="openNotesModal()" title="Click to expand">' + escHtml(notes) + '</div>';
+  const content = typeof notes === 'object' ? notes.content : notes;
+  const updatedAt = typeof notes === 'object' ? notes.updatedAt : null;
+
+  // Show last updated timestamp
+  const updatedEl = document.getElementById('notes-updated');
+  if (updatedEl && updatedAt) {
+    const d = new Date(updatedAt);
+    updatedEl.textContent = 'updated ' + d.toLocaleDateString() + ' ' + d.toLocaleTimeString([], {hour:'2-digit',minute:'2-digit'});
+  }
+
+  if (!content || !content.trim()) { el.innerHTML = '<p class="empty">No team notes yet.</p>'; return; }
+  el.innerHTML = '<div class="notes-preview" onclick="openNotesModal()" title="Click to expand">' + escHtml(content) + '</div>';
 }
 
+let _modalEditable = null; // tracks which file is editable (e.g., 'notes.md')
+
 function openNotesModal() {
   const preview = document.querySelector('.notes-preview');
   if (!preview) return;
+  const content = preview.textContent;
   document.getElementById('modal-title').textContent = 'Team Notes';
-  document.getElementById('modal-body').textContent = preview.textContent;
+  document.getElementById('modal-body').textContent = content;
   document.getElementById('modal-body').style.fontFamily = 'Consolas, monospace';
   document.getElementById('modal-body').style.whiteSpace = 'pre-wrap';
+  _modalDocContext = { title: 'Team Notes', content, selection: '' };
+  _modalEditable = 'notes.md';
+  document.getElementById('modal-edit-btn').style.display = '';
   document.getElementById('modal').classList.add('open');
 }
 
+function modalToggleEdit() {
+  const body = document.getElementById('modal-body');
+  body.contentEditable = 'true';
+  body.style.border = '1px solid var(--blue)';
+  body.style.borderRadius = '4px';
+  body.style.padding = '12px';
+  body.style.outline = 'none';
+  body.focus();
+  document.getElementById('modal-edit-btn').style.display = 'none';
+  document.getElementById('modal-save-btn').style.display = '';
+  document.getElementById('modal-cancel-edit-btn').style.display = '';
+}
+
+async function modalSaveEdit() {
+  if (!_modalEditable) return;
+  const body = document.getElementById('modal-body');
+  const content = body.innerText;
+
+  try {
+    const res = await fetch('/api/notes-save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ file: _modalEditable, content }),
+    });
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || 'Save failed');
+
+    body.contentEditable = 'false';
+    body.style.border = '';
+    body.style.padding = '';
+    document.getElementById('modal-edit-btn').style.display = '';
+    document.getElementById('modal-save-btn').style.display = 'none';
+    document.getElementById('modal-cancel-edit-btn').style.display = 'none';
+    _modalDocContext.content = content;
+    showToast('cmd-toast', 'Team Notes saved', true);
+  } catch (e) {
+    showToast('cmd-toast', 'Error: ' + e.message, false);
+  }
+}
+
+function modalCancelEdit() {
+  const body = document.getElementById('modal-body');
+  body.contentEditable = 'false';
+  body.textContent = _modalDocContext.content; // revert
+  body.style.border = '';
+  body.style.padding = '';
+  document.getElementById('modal-edit-btn').style.display = '';
+  document.getElementById('modal-save-btn').style.display = 'none';
+  document.getElementById('modal-cancel-edit-btn').style.display = 'none';
+}
+
 function renderPrd(prd) {
   const section = document.getElementById('prd-content');
   const badge = document.getElementById('prd-badge');
@@ -1070,6 +1140,15 @@ function closeModal() {
   document.getElementById('modal-qa-input').placeholder = 'Ask about this document (or select text first)...';
   document.getElementById('modal-qa-pill').style.display = 'none';
   document.getElementById('ask-selection-btn').style.display = 'none';
+  // Clear edit state
+  _modalEditable = null;
+  const body = document.getElementById('modal-body');
+  body.contentEditable = 'false';
+  body.style.border = '';
+  body.style.padding = '';
+  document.getElementById('modal-edit-btn').style.display = 'none';
+  document.getElementById('modal-save-btn').style.display = 'none';
+  document.getElementById('modal-cancel-edit-btn').style.display = 'none';
 }
 
 document.addEventListener('keydown', e => {

package/dashboard.js

@@ -228,7 +228,12 @@ function getInbox() {
 }
 
 function getNotes() {
-  return safeRead(path.join(SQUAD_DIR, 'notes.md')) || '';
+  const notesPath = path.join(SQUAD_DIR, 'notes.md');
+  const content = safeRead(notesPath) || '';
+  try {
+    const stat = fs.statSync(notesPath);
+    return { content, updatedAt: stat.mtimeMs };
+  } catch { return { content, updatedAt: null }; }
 }
 
 function getPullRequests() {
@@ -844,6 +849,19 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  // POST /api/notes-save — save edited notes.md content
+  if (req.method === 'POST' && req.url === '/api/notes-save') {
+    try {
+      const body = await readBody(req);
+      if (!body.content && body.content !== '') return jsonReply(res, 400, { error: 'content required' });
+      const file = body.file || 'notes.md';
+      // Only allow saving notes.md (prevent arbitrary file writes)
+      if (file !== 'notes.md') return jsonReply(res, 400, { error: 'only notes.md can be edited' });
+      safeWrite(path.join(SQUAD_DIR, file), body.content);
+      return jsonReply(res, 200, { ok: true });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
   // GET /api/knowledge — list all knowledge base entries grouped by category
   if (req.method === 'GET' && req.url === '/api/knowledge') {
     const kbDir = path.join(SQUAD_DIR, 'knowledge');

package/docs/human-vs-automated.md

@@ -0,0 +1,107 @@
+# Human vs. Automated — What Requires You, What Doesn't
+
+## Quick Reference
+
+| Feature | Who starts it | Who runs it | Who decides | Who recovers |
+|---------|--------------|-------------|-------------|-------------|
+| Work items | You (dashboard) | Engine + agent | — | You (retry) |
+| Plans | You (dashboard) | Agent writes plan | You (approve/reject) | You (revise) |
+| PRD items | You (dashboard) | Engine dispatches | — | You (retry) |
+| PR creation | Agent (auto) | Agent | — | — |
+| PR review | Engine (auto-dispatch) | Agent reviewer | Human (vote to merge) | Human (comments → auto-fix) |
+| Build failures | Engine (auto-detect) | Agent (auto-fix) | — | — |
+| Notes | You (`/note`) or agent (findings) | Engine (consolidate) | You (promote to KB) | — |
+| Cleanup | Engine (every 5 min) | Engine | — | — |
+| Metrics | Engine (auto-collect) | Engine | You (view) | — |
+| Error recovery | Engine (detect) | — | You (retry/delete) | You |
+| Project linking | You (`squad add/scan`) | — | — | — |
+| MCP servers | You (`~/.claude.json`) | Inherited by agents | — | — |
+
+## The Two Human Gates
+
+Squad is designed around **two approval gates** where humans make decisions. Everything else is automated.
+
+### Gate 1: Plan Approval
+
+When you submit a `/plan`, an agent creates a structured plan file. The plan sits in `awaiting-approval` status until you:
+- **Approve** → engine auto-dispatches all plan items
+- **Reject** → plan is archived
+- **Revise** → feedback sent back to agent, plan is reworked
+
+This is the only point where you decide *what* gets built.
+
+### Gate 2: PR Review
+
+When agents create PRs, they need human review votes before merging. You can:
+- **Approve** → PR is merge-ready
+- **Comment** → engine detects `@squad` mentions, auto-dispatches a fix task
+- **Request changes** → same as comment, triggers auto-fix
+
+This is the only point where you decide if the *quality* is good enough.
+
+## Fully Automated (Zero Human Involvement)
+
+These run continuously without you:
+
+- **Work discovery** — engine scans all project queues every tick (~30s)
+- **Agent dispatch** — engine picks the right agent, builds the prompt, spawns Claude
+- **Worktree management** — create on dispatch, pull on shared-branch, clean after merge
+- **PR status polling** — checks ADO for build status, review votes, merge state every ~3 min
+- **Build failure detection** — auto-files fix tasks when CI fails
+- **Inbox consolidation** — LLM-powered dedup and categorization when inbox hits threshold
+- **Knowledge base classification** — auto-assigns category to consolidated notes
+- **Heartbeat monitoring** — detects hung/dead agents, marks them failed
+- **Blocking tool detection** — extends timeout when agent is in a long-running operation
+- **Metrics collection** — tracks tasks, errors, PRs, approvals per agent
+- **Dispatch priority** — fixes first, then reviews, then implementations
+- **Cooldown & backoff** — prevents re-dispatching recently failed items
+- **Zombie cleanup** — temp files, orphaned worktrees, stale processes every 5 min
+- **Post-merge hooks** — worktree cleanup, PRD status update, metrics update
+
+## Human-Triggered, Then Autonomous
+
+You kick these off, then they run without you:
+
+- **Work items** — type in dashboard, engine dispatches, agent executes, PR created
+- **PRD items** — `/prd` in dashboard, engine discovers and dispatches implement tasks
+- **Fan-out** — one task dispatched to all idle agents in parallel
+- **Retry** — click retry on failed item, engine re-dispatches fresh
+- **Notes** — `/note` in dashboard, flows through inbox → consolidation → team knowledge
+- **KB promotion** — click "Add to Knowledge Base", pick category, done
+- **Project linking** — `squad scan` or `squad add`, engine discovers work on next tick
+
+## Human-in-the-Loop
+
+These pause and wait for your input:
+
+- **Plan approval** — agent writes plan, waits for approve/reject/revise
+- **Plan discussion** — interactive Claude session where you refine the plan
+- **PR merge** — agents can't merge their own PRs, humans must vote
+- **PR feedback cycle** — human comments → auto-fix → human re-reviews (loop until approved)
+
+## Manual Only
+
+These are entirely on you:
+
+- **Project setup** — `squad init`, `squad scan`, `squad add`
+- **Agent customization** — edit `agents/*/charter.md`, `routing.md`
+- **Config changes** — edit `config.json` (engine settings, projects)
+- **MCP server setup** — add servers to `~/.claude.json`
+- **Dashboard access** — open browser to `http://localhost:7331`
+- **Engine start/stop** — `node engine.js start/stop`
+
+## What Happens When You Walk Away
+
+If you start the engine and dashboard, then leave:
+
+1. Engine ticks every 30 seconds
+2. Discovers pending work items, PRD gaps, PR reviews needed
+3. Dispatches agents (up to max concurrent)
+4. Agents create worktrees, write code, create PRs
+5. Engine monitors for completion, hung agents, build failures
+6. Successful work → PRs appear in your ADO/GitHub queue
+7. Failed work → marked failed, waiting for your retry
+8. Notes consolidated into team knowledge automatically
+9. Worktrees cleaned up after PRs merge
+
+**What blocks:** Plans waiting for approval. PRs waiting for your review vote. Failed tasks waiting for retry. Everything else keeps moving.

package/engine.js

@@ -820,9 +820,10 @@ function spawnAgent(dispatchItem, config) {
     // Update quality metrics
     updateMetrics(agentId, dispatchItem, code === 0 ? 'success' : 'error', taskUsage, prsCreatedCount);
 
-    // Cleanup temp files
+    // Cleanup temp files (including PID file now that dispatch is complete)
     try { fs.unlinkSync(sysPromptPath); } catch {}
     try { fs.unlinkSync(promptPath); } catch {}
+    try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch {}
 
     log('info', `Agent ${agentId} completed. Output saved to ${outputPath}`);
   });
@@ -857,6 +858,7 @@ function spawnAgent(dispatchItem, config) {
   }
 
   // Verify spawn after 5 seconds via PID file written by spawn-agent.js
+  // PID file is kept (not deleted) so engine can re-attach on restart
   setTimeout(() => {
     const pidFile = promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid');
     try {
@@ -864,12 +866,10 @@ function spawnAgent(dispatchItem, config) {
       if (pidStr) {
         log('info', `Agent ${agentId} verified via PID file: ${pidStr}`);
       }
-      try { fs.unlinkSync(pidFile); } catch {}
+      // Don't delete — keep for re-attachment on engine restart
     } catch {
-      // No PID file — check if live output exists (spawn-agent.js may have written it)
       if (!fs.existsSync(liveOutputPath) || fs.statSync(liveOutputPath).size <= 200) {
         log('error', `Agent ${agentId} (${id}) — no PID file and no output after 5s. Spawn likely failed.`);
-        // Don't mark as error yet — heartbeat will catch it at 5min
       }
     }
   }, 5000);
@@ -1046,10 +1046,7 @@ ${itemSummary}
 // a plan-to-prd task so Lambert converts it to structured PRD items.
 function chainPlanToPrd(dispatchItem, meta, config) {
   const planDir = path.join(SQUAD_DIR, 'plans');
-  if (!fs.existsSync(planDir)) {
-    log('warn', `Plan chaining: no plans/ directory found after plan task ${dispatchItem.id}`);
-    return;
-  }
+  if (!fs.existsSync(planDir)) fs.mkdirSync(planDir, { recursive: true });
 
   // Use the plan filename from dispatch meta (set during plan task creation)
   // Falls back to mtime-based detection if meta doesn't have it
@@ -3859,6 +3856,8 @@ function discoverCentralWorkItems(config) {
 
       // Inject plan-specific variables for the plan playbook
       if (workType === 'plan') {
+        // Ensure plans directory exists before agent tries to write
+        if (!fs.existsSync(PLANS_DIR)) fs.mkdirSync(PLANS_DIR, { recursive: true });
         const planFileName = `plan-${item.id.toLowerCase()}-${dateStamp()}.md`;
         vars.plan_content = item.title + (item.description ? '\n\n' + item.description : '');
         vars.plan_title = item.title;
@@ -4091,15 +4090,72 @@ const commands = {
     // Load persistent state
     loadCooldowns();
 
-    // Grace period for agents that survived a restart
+    // Re-attach to surviving agent processes from previous session
     const dispatch = getDispatch();
     const activeOnStart = (dispatch.active || []);
     if (activeOnStart.length > 0) {
-      const gracePeriod = config.engine?.restartGracePeriod || 1200000; // 20min default
-      engineRestartGraceUntil = Date.now() + gracePeriod;
-      console.log(`  ${activeOnStart.length} active dispatch(es) from previous session — ${gracePeriod / 60000}min grace period before orphan detection`);
+      let reattached = 0;
+      for (const item of activeOnStart) {
+        // Try to find the agent's PID: check status.json, or scan for live-output.log activity
+        const agentId = item.agent;
+        let agentPid = null;
+
+        // Method 1: Check PID file (if it wasn't cleaned up)
+        const pidFile = path.join(ENGINE_DIR, `pid-${item.id}.pid`);
+        try {
+          const pidStr = fs.readFileSync(pidFile, 'utf8').trim();
+          if (pidStr) agentPid = parseInt(pidStr);
+        } catch {}
+
+        // Method 2: Check agent status.json for dispatch_id match
+        if (!agentPid) {
+          const status = getAgentStatus(agentId);
+          if (status.dispatch_id === item.id) {
+            // Agent was working on this dispatch — check if any process is producing output
+            const liveLog = path.join(AGENTS_DIR, agentId, 'live-output.log');
+            try {
+              const stat = fs.statSync(liveLog);
+              const ageMs = Date.now() - stat.mtimeMs;
+              if (ageMs < 300000) { // live-output modified in last 5 min — agent likely alive
+                agentPid = -1; // sentinel: alive but unknown PID
+              }
+            } catch {}
+          }
+        }
+
+        // Verify PID is actually alive
+        if (agentPid && agentPid > 0) {
+          try {
+            if (process.platform === 'win32') {
+              const out = execSync(`tasklist /FI "PID eq ${agentPid}" /NH`, { encoding: 'utf8', timeout: 3000 });
+              if (!out.includes(String(agentPid))) agentPid = null;
+            } else {
+              process.kill(agentPid, 0);
+            }
+          } catch { agentPid = null; }
+        }
+
+        if (agentPid) {
+          // Re-attach: add sentinel to activeProcesses so orphan detector knows it's alive
+          activeProcesses.set(item.id, { proc: { pid: agentPid > 0 ? agentPid : null }, agentId, startedAt: item.created_at, reattached: true });
+          reattached++;
+          log('info', `Re-attached to ${agentId} (${item.id}) — PID ${agentPid > 0 ? agentPid : 'unknown (active output)'}`);
+        }
+      }
+
+      // Grace period only for dispatches we couldn't re-attach to
+      const unattached = activeOnStart.length - reattached;
+      if (unattached > 0) {
+        const gracePeriod = config.engine?.restartGracePeriod || 1200000; // 20min default
+        engineRestartGraceUntil = Date.now() + gracePeriod;
+        console.log(`  ${unattached} unattached dispatch(es) — ${gracePeriod / 60000}min grace period`);
+      }
+      if (reattached > 0) {
+        console.log(`  Re-attached to ${reattached} surviving agent(s)`);
+      }
       for (const item of activeOnStart) {
-        console.log(`    - ${item.agentName || item.agent}: ${(item.task || '').slice(0, 70)}`);
+        const attached = activeProcesses.has(item.id);
+        console.log(`    ${attached ? '✓' : '?'} ${item.agentName || item.agent}: ${(item.task || '').slice(0, 70)}`);
       }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/squad",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Multi-agent AI dev team that runs from ~/.squad/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "squad": "bin/squad.js"