dw-kit 1.4.0 → 1.7.0-rc.1

package/src/commands/task-watch.mjs

@@ -0,0 +1,868 @@
+import { existsSync, statSync, readdirSync, readFileSync, writeFileSync, watch as fsWatch } from 'node:fs';
+import { join } from 'node:path';
+import { createServer } from 'node:http';
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+import { taskViewCommand } from './task-view.mjs';
+import { renderGoalPortfolioHtml } from './goal-view.mjs';
+import { readGoalIndex, listGoalIds, syncIndexEntry, readGoal, updateGoalFrontmatter, findLinkedTaskIds, computeGoalProgress, todayIso, nowUtc } from '../lib/goal-store.mjs';
+import { ensureToken, isAuthorized, isWriteEndpoint } from '../lib/watch-auth.mjs';
+import { createSseBroker } from '../lib/sse-broker.mjs';
+import { logGoalEvent } from '../lib/goal-events.mjs';
+import { renderGoalSvg } from '../lib/goal-svg.mjs';
+import { createClaim, persistClaim, loadClaim, transitionClaim, nowIsoUtc } from '../lib/agent-claim.mjs';
+import { logAgentEvent } from '../lib/agent-events.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const VALID_STATUSES = new Set(['Draft', 'Active', 'Achieved', 'Abandoned', 'Pivoted']);
+const MAX_BODY_BYTES = 16 * 1024;
+const MAX_SUMMARY_CHARS = 1000;
+const SETTABLE_FIELDS = new Set(['icon', 'cycle', 'owner', 'target_date', 'parent_goal_id']);
+const FIELD_MAX = { icon: 8, cycle: 32, owner: 64, target_date: 16, parent_goal_id: 40 };
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    let aborted = false;
+    req.on('data', (chunk) => {
+      if (aborted) return;
+      buf += chunk;
+      if (buf.length > MAX_BODY_BYTES) {
+        aborted = true;
+        reject(new Error('body too large'));
+      }
+    });
+    req.on('end', () => {
+      if (aborted) return;
+      try { resolve(buf ? JSON.parse(buf) : {}); }
+      catch (e) { reject(new Error('invalid JSON: ' + e.message)); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+  res.end(JSON.stringify(body));
+}
+
+// ── Implicit Agent OS claim for browser editor (S-4) ───────────────────────
+// Server-side map: goalId → claim_id. One implicit human claim per goal
+// (single-editor assumption; multiple browser tabs editing same goal share
+// the same claim and refresh it via /keepalive). Map dies on server restart;
+// stale claims expire naturally via 5min lease.
+const browserClaims = new Map();
+const BROWSER_CLAIM_LEASE_SECONDS = 5 * 60; // 5 minutes (S-4 spec)
+
+function goalToTaskId(goalId) {
+  return ('goal-' + goalId).toLowerCase();
+}
+
+function ensureBrowserClaim(goalId, rootDir) {
+  const existing = browserClaims.get(goalId);
+  if (existing) {
+    try {
+      const claim = loadClaim(existing, rootDir);
+      if (claim && claim.status !== 'released' && claim.status !== 'expired' && claim.status !== 'invalidated') {
+        return existing;
+      }
+    } catch { /* fall through to create new */ }
+    browserClaims.delete(goalId);
+  }
+  const claim = createClaim({
+    taskId: goalToTaskId(goalId),
+    agent: { id: 'browser', vendor: 'human', role: 'worker' },
+    subtasks: ['ST-0'],
+    writeScope: [`.dw/goals/${goalId}/goal.md`],
+    readScope: [`.dw/goals/${goalId}/`],
+    leaseSeconds: BROWSER_CLAIM_LEASE_SECONDS,
+  }, rootDir);
+  persistClaim(claim, rootDir);
+  browserClaims.set(goalId, claim.claim_id);
+  logAgentEvent(goalToTaskId(goalId), {
+    event: 'claim_created',
+    claim_id: claim.claim_id,
+    agent: claim.agent,
+    subtasks: claim.subtasks,
+    write_scope: claim.write_scope,
+    via: 'browser_implicit',
+  }, rootDir);
+  return claim.claim_id;
+}
+
+function refreshBrowserClaim(goalId, rootDir) {
+  const claimId = browserClaims.get(goalId);
+  if (!claimId) return null;
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) { browserClaims.delete(goalId); return null; }
+  if (claim.status === 'released' || claim.status === 'expired' || claim.status === 'invalidated') {
+    browserClaims.delete(goalId);
+    return null;
+  }
+  // Extend lease: update lease_expires + lease_duration_seconds in-place
+  const newExpiry = new Date(Date.now() + BROWSER_CLAIM_LEASE_SECONDS * 1000).toISOString().replace(/\.\d+Z$/, 'Z');
+  claim.lease_expires = newExpiry;
+  claim.lease_duration_seconds = BROWSER_CLAIM_LEASE_SECONDS;
+  const file = join(rootDir, '.dw/cache/agents/claims', `${claim.claim_id}.json`);
+  writeFileSync(file, JSON.stringify(claim, null, 2) + '\n', 'utf8');
+  return claim.claim_id;
+}
+
+function releaseBrowserClaim(goalId, rootDir, reason = 'browser closed') {
+  const claimId = browserClaims.get(goalId);
+  if (!claimId) return null;
+  try {
+    transitionClaim(claimId, 'released', { reason }, rootDir);
+    logAgentEvent(goalToTaskId(goalId), {
+      event: 'claim_released',
+      claim_id: claimId,
+      reason,
+      via: 'browser_implicit',
+    }, rootDir);
+  } catch { /* claim already gone */ }
+  browserClaims.delete(goalId);
+  return claimId;
+}
+
+function escHtml(s) {
+  if (s == null) return '';
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function renderGoalEditorHtml(goalId, goal, token, claimId = null) {
+  const fm = goal.fm || {};
+  const statusOptions = ['Draft', 'Active', 'Achieved', 'Abandoned', 'Pivoted']
+    .map((s) => `<option value="${s}"${s === fm.status ? ' selected' : ''}>${s}</option>`)
+    .join('');
+  const icon = fm.icon || '🎯';
+  const cycle = fm.cycle || '';
+
+  return `<!doctype html>
+<html><head>
+<meta charset="utf-8">
+<title>edit ${escHtml(goalId)} — dw goal</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font: 14px/1.6 -apple-system, sans-serif; background: #0d1117; color: #c9d1d9; padding: 32px; max-width: 760px; margin: 0 auto; }
+@media (prefers-color-scheme: light) { body { background: #fff; color: #1f2328; } }
+nav { margin-bottom: 24px; display: flex; gap: 16px; justify-content: space-between; align-items: center; }
+nav a { color: #58a6ff; text-decoration: none; font-size: 13px; }
+nav a:hover { text-decoration: underline; }
+h1 { font-size: 22px; margin-bottom: 8px; font-family: ui-monospace, monospace; display: flex; align-items: center; gap: 12px; }
+h1 .icon-display { font-size: 28px; line-height: 1; }
+.meta { color: #6b7280; font-size: 12px; margin-bottom: 24px; }
+label { display: block; font-size: 12px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 6px; color: #8b949e; }
+@media (prefers-color-scheme: light) { label { color: #57606a; } }
+.field { margin-bottom: 24px; }
+.row { display: grid; grid-template-columns: 100px 1fr; gap: 16px; margin-bottom: 24px; }
+input, textarea, select { width: 100%; padding: 10px 12px; background: #161b22; color: inherit; border: 1px solid #30363d; border-radius: 6px; font-family: inherit; font-size: 14px; }
+@media (prefers-color-scheme: light) { input, textarea, select { background: #f6f8fa; border-color: #d0d7de; } }
+input:focus, textarea:focus, select:focus { outline: none; border-color: #58a6ff; }
+textarea { min-height: 120px; resize: vertical; }
+#icon { text-align: center; font-size: 22px; padding: 4px; }
+.counter { font-size: 11px; color: #6b7280; text-align: right; margin-top: 4px; }
+.counter.over { color: #ef4444; }
+.save-status { position: fixed; top: 12px; right: 16px; padding: 6px 14px; border-radius: 6px; font-size: 12px; font-weight: 600; z-index: 100; }
+.save-status.saved { background: rgba(16,185,129,0.18); color: #10b981; }
+.save-status.saving { background: rgba(245,158,11,0.18); color: #f59e0b; }
+.save-status.error { background: rgba(239,68,68,0.18); color: #ef4444; }
+.save-status.idle { background: rgba(107,114,128,0.18); color: #9ca3af; }
+.notice { padding: 12px; background: rgba(99,102,241,0.12); color: #818cf8; border-radius: 6px; font-size: 12px; margin-bottom: 24px; }
+.progress-block { padding: 14px 16px; background: #161b22; border: 1px solid #30363d; border-radius: 6px; margin-bottom: 24px; }
+@media (prefers-color-scheme: light) { .progress-block { background: #f6f8fa; border-color: #d0d7de; } }
+.progress-bar-outer { height: 10px; background: rgba(107,114,128,0.25); border-radius: 5px; overflow: hidden; margin: 8px 0; }
+.progress-bar-inner { height: 100%; background: #0ea5e9; transition: width 0.3s; }
+.progress-stats { display: flex; gap: 14px; font-size: 12px; color: #8b949e; flex-wrap: wrap; }
+.progress-stats span strong { color: #c9d1d9; font-weight: 600; }
+</style>
+</head><body>
+<div class="save-status idle" id="save-status">idle</div>
+<nav>
+  <a href="/goals/${escHtml(goalId)}">← view</a>
+  <a href="/goals">portfolio</a>
+</nav>
+<h1><span class="icon-display" id="icon-display">${escHtml(icon)}</span> ${escHtml(goalId)}</h1>
+<div class="meta">v${escHtml(fm.goal_version || 1)} · owner: ${escHtml(fm.owner || '?')} · target: ${escHtml(fm.target_date || 'TBD')} · last updated: ${escHtml(fm.last_updated || '?')}</div>
+
+<div class="progress-block" id="progress-block">
+  <label>Aggregated progress (from linked tasks)</label>
+  <div class="progress-bar-outer"><div class="progress-bar-inner" id="progress-fill" style="width:0%"></div></div>
+  <div class="progress-stats" id="progress-stats">computing…</div>
+</div>
+
+<div class="notice">
+  Icon + cycle + summary: auto-save 800ms debounce (no version bump) · Status: immediate save + auto-bumps goal_version + emits goal_status_changed
+</div>
+
+<div class="row">
+  <div>
+    <label for="icon">Icon</label>
+    <input id="icon" type="text" maxlength="8" value="${escHtml(icon)}">
+  </div>
+  <div>
+    <label for="cycle">Cycle (optional)</label>
+    <input id="cycle" type="text" maxlength="32" placeholder="e.g. Q2 2026 · v1.7-cycle · 2026 H1" value="${escHtml(cycle)}">
+  </div>
+</div>
+
+<div class="field">
+  <label for="status">Status</label>
+  <select id="status">${statusOptions}</select>
+</div>
+
+<div class="field">
+  <label for="summary">Summary (≤1000 chars)</label>
+  <textarea id="summary" maxlength="1000" placeholder="Short-form for portfolio cards + agent reaction. Mirrored to goals-index.json on save.">${escHtml(fm.summary || '')}</textarea>
+  <div class="counter" id="counter">${(fm.summary || '').length} / 1000</div>
+</div>
+
+<script>
+(function () {
+  var TOKEN = ${JSON.stringify(token)};
+  var GOAL_ID = ${JSON.stringify(goalId)};
+  var CLAIM_ID = ${JSON.stringify(claimId || '')};
+  var DEBOUNCE_MS = 800;
+  var KEEPALIVE_MS = 2 * 60 * 1000; // S-4: 2 minutes (lease is 5 min, so 60% safety window)
+
+  var summaryEl = document.getElementById('summary');
+  var statusEl = document.getElementById('status');
+  var iconEl = document.getElementById('icon');
+  var iconDisplay = document.getElementById('icon-display');
+  var cycleEl = document.getElementById('cycle');
+  var counterEl = document.getElementById('counter');
+  var statusBadge = document.getElementById('save-status');
+  var progressFill = document.getElementById('progress-fill');
+  var progressStats = document.getElementById('progress-stats');
+  var summaryTimer = null;
+  var iconTimer = null;
+  var cycleTimer = null;
+  var inflight = false;
+
+  function setBadge(state, text) {
+    statusBadge.className = 'save-status ' + state;
+    statusBadge.textContent = text;
+  }
+
+  function updateCounter() {
+    var len = summaryEl.value.length;
+    counterEl.textContent = len + ' / 1000';
+    counterEl.classList.toggle('over', len > 1000);
+  }
+
+  function commit(field, body) {
+    if (inflight) return;
+    inflight = true;
+    setBadge('saving', 'saving…');
+    fetch('/goals/' + GOAL_ID + '/' + field, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Watch-Token': TOKEN,
+      },
+      body: JSON.stringify(body),
+    }).then(function (r) {
+      if (!r.ok) return r.text().then(function (t) { throw new Error(r.status + ': ' + t); });
+      return r.json();
+    }).then(function () {
+      ownCommitAt = Date.now();
+      setBadge('saved', 'saved');
+    }).catch(function (e) {
+      setBadge('error', 'error');
+      console.error(e);
+    }).finally(function () {
+      inflight = false;
+    });
+  }
+
+  summaryEl.addEventListener('input', function () {
+    updateCounter();
+    if (summaryTimer) clearTimeout(summaryTimer);
+    summaryTimer = setTimeout(function () {
+      commit('summary', { summary: summaryEl.value });
+    }, DEBOUNCE_MS);
+  });
+
+  iconEl.addEventListener('input', function () {
+    iconDisplay.textContent = iconEl.value || '🎯';
+    if (iconTimer) clearTimeout(iconTimer);
+    iconTimer = setTimeout(function () {
+      commit('field', { field: 'icon', value: iconEl.value || null });
+    }, DEBOUNCE_MS);
+  });
+
+  cycleEl.addEventListener('input', function () {
+    if (cycleTimer) clearTimeout(cycleTimer);
+    cycleTimer = setTimeout(function () {
+      commit('field', { field: 'cycle', value: cycleEl.value || null });
+    }, DEBOUNCE_MS);
+  });
+
+  statusEl.addEventListener('change', function () {
+    commit('status', { status: statusEl.value });
+  });
+
+  // Fetch progress on load
+  function refreshProgress() {
+    fetch('/goals/' + GOAL_ID + '/progress', { headers: { 'X-Watch-Token': TOKEN } })
+      .then(function (r) { return r.json(); })
+      .then(function (p) {
+        progressFill.style.width = p.percent + '%';
+        if (p.total === 0) {
+          progressStats.textContent = '(no linked tasks yet — use: dw goal link ' + GOAL_ID + ' <task-id>)';
+        } else {
+          progressStats.innerHTML =
+            '<span><strong>' + p.percent + '%</strong> overall</span>' +
+            '<span><strong>' + p.done + '</strong> done</span>' +
+            '<span><strong>' + p.in_progress + '</strong> in progress</span>' +
+            '<span><strong>' + p.blocked + '</strong> blocked</span>' +
+            '<span><strong>' + p.pending + '</strong> pending</span>' +
+            '<span style="margin-left:auto;opacity:0.6">of ' + p.total + ' subtasks</span>';
+        }
+      })
+      .catch(function () { progressStats.textContent = 'progress unavailable'; });
+  }
+  refreshProgress();
+
+  // SSE — live update when other tabs/agents change this goal
+  // Bug fix (2026-05-23): track page-open timestamp + skip events from this tab's own commits
+  // to break the backfill-reload loop. Only react to events newer than page-open AND not authored
+  // by this browser tab.
+  var PAGE_OPENED_TS = new Date().toISOString();
+  var ownCommitAt = 0;
+  try {
+    var sse = new EventSource('/events.sse?token=' + encodeURIComponent(TOKEN));
+    sse.onmessage = function (ev) {
+      try {
+        var data = JSON.parse(ev.data);
+        if (!data || data.goal_id !== GOAL_ID) return;
+        // Skip events from before page open (initial 100-event backfill)
+        if (data.ts && data.ts <= PAGE_OPENED_TS) return;
+        // Skip events authored by this tab within last 2s (echoes of own commits)
+        if (data.changed_by === 'browser' && (Date.now() - ownCommitAt) < 2000) return;
+        // Genuine remote edit — soft refresh badge + reload after 500ms
+        setBadge('saved', 'remote update');
+        setTimeout(function () { window.location.reload(); }, 500);
+      } catch (e) { /* ignore parse errors */ }
+    };
+    sse.onerror = function () { setBadge('error', 'sse offline'); };
+  } catch (e) { /* SSE unsupported */ }
+
+  // S-4: keepalive ping for implicit Agent OS claim (5min lease, refresh every 2min)
+  function pingKeepalive() {
+    fetch('/goals/' + GOAL_ID + '/keepalive', {
+      method: 'POST',
+      headers: { 'X-Watch-Token': TOKEN, 'Content-Type': 'application/json' },
+      body: '{}',
+    }).catch(function () { /* network blip; next interval retries */ });
+  }
+  setInterval(pingKeepalive, KEEPALIVE_MS);
+
+  // S-4: best-effort claim release on tab close / navigation
+  window.addEventListener('beforeunload', function () {
+    var url = '/goals/' + GOAL_ID + '/claim/release';
+    // Use sendBeacon when available (survives navigation); fallback to keepalive fetch
+    if (navigator.sendBeacon) {
+      var blob = new Blob([JSON.stringify({ token: TOKEN })], { type: 'application/json' });
+      navigator.sendBeacon(url + '?token=' + encodeURIComponent(TOKEN), blob);
+    } else {
+      try {
+        fetch(url, {
+          method: 'POST',
+          headers: { 'X-Watch-Token': TOKEN, 'Content-Type': 'application/json' },
+          body: '{}',
+          keepalive: true,
+        });
+      } catch (e) { /* best effort */ }
+    }
+  });
+})();
+</script>
+</body></html>`;
+}
+
+const TASKS_DIR = '.dw/tasks';
+const CACHE_DIR = '.dw/cache/preview';
+const DEBOUNCE_MS = 800;
+const DEFAULT_PORT = 4181;
+const MAX_PORT_TRIES = 20;
+
+function findV3Tasks(rootDir) {
+  const tasksRoot = join(rootDir, TASKS_DIR);
+  if (!existsSync(tasksRoot)) return [];
+  return readdirSync(tasksRoot)
+    .filter((e) => e !== 'archive' && e !== 'ACTIVE.md')
+    .map((e) => ({ name: e, path: join(tasksRoot, e) }))
+    .filter((e) => {
+      try { return statSync(e.path).isDirectory() && existsSync(join(e.path, 'task.md')); }
+      catch { return false; }
+    });
+}
+
+function findAvailablePort(start) {
+  return new Promise((resolve, reject) => {
+    let port = start;
+    const tryPort = () => {
+      if (port - start > MAX_PORT_TRIES) {
+        reject(new Error(`Could not find available port in ${start}..${port - 1}`));
+        return;
+      }
+      const tester = createServer();
+      tester.once('error', () => {
+        tester.close();
+        port++;
+        tryPort();
+      });
+      tester.once('listening', () => {
+        tester.close(() => resolve(port));
+      });
+      tester.listen(port);
+    };
+    tryPort();
+  });
+}
+
+const HTML_SHELL = (taskName, port) => `<!doctype html>
+<html><head>
+<meta charset="utf-8"><title>dw task watch — ${taskName}</title>
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font: 13px -apple-system, sans-serif; background: #0d1117; color: #c9d1d9; }
+@media (prefers-color-scheme: light) { body { background: #fff; color: #1f2328; } }
+iframe { width: 100%; height: calc(100vh - 36px); border: 0; }
+.topbar { position: sticky; top: 0; display: flex; align-items: center; gap: 12px; padding: 8px 14px; background: #161b22; border-bottom: 1px solid #30363d; height: 36px; z-index: 50; }
+@media (prefers-color-scheme: light) { .topbar { background: #f6f8fa; border-bottom-color: #d0d7de; } }
+.topbar a { color: #58a6ff; text-decoration: none; font-size: 12px; padding: 3px 8px; border-radius: 4px; }
+.topbar a:hover { background: rgba(88, 166, 255, 0.12); }
+.topbar .ctx { margin-left: auto; color: #6b7280; font-size: 11px; font-family: ui-monospace, monospace; }
+.live { padding: 3px 10px; background: rgba(16, 185, 129, 0.18); color: #10b981; border-radius: 4px; font-size: 11px; letter-spacing: 0.5px; font-weight: 600; }
+.live.stale { background: rgba(245, 158, 11, 0.18); color: #f59e0b; }
+.live.error { background: rgba(220, 38, 38, 0.18); color: #ef4444; }
+</style>
+</head><body>
+<div class="topbar">
+  <a href="/preview" target="frame">📄 Task</a>
+  <a href="/goals" target="frame">🎯 Goals</a>
+  <span class="ctx">${taskName}</span>
+  <div class="live" id="status">● LIVE</div>
+</div>
+<iframe id="frame" name="frame" src="/preview"></iframe>
+<script>
+(function () {
+  var status = document.getElementById('status');
+  var frame = document.getElementById('frame');
+  var ws;
+  function setStatus(text, cls) { status.textContent = text; status.className = 'live ' + (cls || ''); }
+  function reload() {
+    setStatus('● RELOADING', 'stale');
+    var f = document.createElement('iframe');
+    f.id = 'frame';
+    f.src = '/preview?ts=' + Date.now();
+    f.onload = function () { setStatus('● LIVE', ''); };
+    frame.replaceWith(f);
+    frame = f;
+  }
+  function connect() {
+    try {
+      ws = new WebSocket('ws://localhost:${port}/_ws');
+    } catch (e) { setTimeout(connect, 1000); return; }
+    ws.onmessage = function (e) { if (e.data === 'reload') reload(); };
+    ws.onclose = function () { setStatus('● RECONNECTING', 'error'); setTimeout(connect, 1000); };
+    ws.onopen = function () { setStatus('● LIVE', ''); };
+  }
+  // No native WS without server upgrade — fall back to polling
+  var lastTs = 0;
+  function poll() {
+    fetch('/_ts').then(function (r) { return r.text(); }).then(function (ts) {
+      var n = Number(ts);
+      if (n > 0 && n > lastTs) {
+        if (lastTs > 0) reload();
+        lastTs = n;
+      }
+    }).catch(function () { setStatus('● OFFLINE', 'error'); });
+  }
+  poll();
+  setInterval(poll, 1000);
+})();
+</script>
+</body></html>
+`;
+
+function openInBrowser(url) {
+  const platform = process.platform;
+  try {
+    if (platform === 'win32') execSync(`start "" "${url}"`, { stdio: 'ignore', shell: true });
+    else if (platform === 'darwin') execSync(`open "${url}"`, { stdio: 'ignore' });
+    else execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+export async function taskWatchCommand(taskName, opts = {}) {
+  const rootDir = process.cwd();
+  let target;
+  if (taskName) {
+    const path = join(rootDir, TASKS_DIR, taskName);
+    if (!existsSync(join(path, 'task.md'))) {
+      console.error(chalk.red(`✗ No v3 task "${taskName}" with task.md`));
+      process.exit(1);
+    }
+    target = { name: taskName, path };
+  } else {
+    const all = findV3Tasks(rootDir);
+    if (all.length === 0) {
+      console.error(chalk.red('✗ No v3 tasks found.'));
+      process.exit(1);
+    }
+    all.sort((a, b) => statSync(b.path).mtimeMs - statSync(a.path).mtimeMs);
+    target = all[0];
+    console.log(chalk.dim(`  No task specified — watching most recent: ${target.name}`));
+  }
+
+  const timelineFile = join(target.path, 'task.md');
+  const previewFile = join(rootDir, CACHE_DIR, `${target.name}.html`);
+
+  await taskViewCommand(target.name, { noOpen: true, open: false });
+
+  let lastChangeTs = Date.now();
+  let debounceTimer = null;
+  let regenerating = false;
+
+  async function regenerate() {
+    if (regenerating) return;
+    regenerating = true;
+    try {
+      await taskViewCommand(target.name, { noOpen: true, open: false });
+      lastChangeTs = Date.now();
+    } catch (e) {
+      console.error(chalk.red(`  regenerate failed: ${e.message}`));
+    } finally {
+      regenerating = false;
+    }
+  }
+
+  const port = await findAvailablePort(opts.port || DEFAULT_PORT);
+  const watchToken = ensureToken(rootDir, { rotate: !!opts.rotateToken });
+  const sseBroker = createSseBroker(rootDir);
+
+  const server = createServer((req, res) => {
+    if (isWriteEndpoint(req) && !isAuthorized(req, watchToken)) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'unauthorized', detail: 'Missing or invalid X-Watch-Token header (C-3 auth)' }));
+      logEvent({ event: 'goal', action: 'auth.reject', method: req.method, url: req.url }, rootDir);
+      return;
+    }
+    if (req.url === '/events.sse' || req.url.startsWith('/events.sse?')) {
+      if (!isAuthorized(req, watchToken)) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'unauthorized', detail: 'SSE requires ?token= query or X-Watch-Token header' }));
+        return;
+      }
+      const ok = sseBroker.addClient(req, res);
+      logEvent({ event: 'goal', action: 'sse.connect', clients: sseBroker.clientCount(), accepted: ok }, rootDir);
+      return;
+    }
+    if (req.url === '/_ts') {
+      res.writeHead(200, { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' });
+      res.end(String(lastChangeTs));
+      return;
+    }
+    if (req.url === '/' || req.url.startsWith('/?')) {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(HTML_SHELL(target.name, port));
+      return;
+    }
+    if (req.url === '/preview' || req.url.startsWith('/preview?')) {
+      if (!existsSync(previewFile)) {
+        res.writeHead(404); res.end('preview not generated yet'); return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(readFileSync(previewFile, 'utf8'));
+      return;
+    }
+    if (req.url === '/goals' || req.url.startsWith('/goals?')) {
+      for (const id of listGoalIds(rootDir)) syncIndexEntry(id, rootDir);
+      const idx = readGoalIndex(rootDir);
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(renderGoalPortfolioHtml(idx));
+      logEvent({ event: 'goal', action: 'view.invoke', count: Object.keys(idx.goals || {}).length, via: 'watch' }, rootDir);
+      return;
+    }
+    const postKeepaliveMatch = req.method === 'POST' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/keepalive\/?$/);
+    if (postKeepaliveMatch) {
+      const goalId = postKeepaliveMatch[1];
+      const claimId = refreshBrowserClaim(goalId, rootDir) || ensureBrowserClaim(goalId, rootDir);
+      sendJson(res, 200, { ok: true, goal_id: goalId, claim_id: claimId, lease_seconds: BROWSER_CLAIM_LEASE_SECONDS });
+      return;
+    }
+
+    const postReleaseMatch = req.method === 'POST' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/claim\/release\/?$/);
+    if (postReleaseMatch) {
+      const goalId = postReleaseMatch[1];
+      const claimId = releaseBrowserClaim(goalId, rootDir, 'browser beforeunload');
+      sendJson(res, 200, { ok: true, goal_id: goalId, released_claim_id: claimId });
+      return;
+    }
+
+    const postSummaryMatch = req.method === 'POST' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/summary\/?$/);
+    if (postSummaryMatch) {
+      const goalId = postSummaryMatch[1];
+      ensureBrowserClaim(goalId, rootDir);
+      readJsonBody(req).then((body) => {
+        const goal = readGoal(goalId, rootDir);
+        if (!goal) { sendJson(res, 404, { error: 'not_found', goal_id: goalId }); return; }
+        const newSummary = typeof body.summary === 'string' ? body.summary : null;
+        if (newSummary && newSummary.length > MAX_SUMMARY_CHARS) {
+          sendJson(res, 400, { error: 'summary_too_long', max: MAX_SUMMARY_CHARS, got: newSummary.length });
+          return;
+        }
+        const oldSummary = goal.fm.summary || null;
+        updateGoalFrontmatter(goalId, (fm) => { fm.summary = newSummary; fm.last_updated = todayIso(); return fm; }, rootDir);
+        syncIndexEntry(goalId, rootDir);
+        logGoalEvent({
+          event: 'goal_field_updated',
+          goal_id: goalId,
+          field: 'summary',
+          old: oldSummary,
+          new: newSummary,
+          changed_by: 'browser',
+        }, rootDir);
+        logEvent({ event: 'goal', action: 'edit.commit', name: goalId, field: 'summary', via: 'http' }, rootDir);
+        sendJson(res, 200, { ok: true, goal_id: goalId, field: 'summary', length: (newSummary || '').length });
+      }).catch((e) => sendJson(res, 400, { error: 'bad_body', detail: e.message }));
+      return;
+    }
+
+    const getSvgMatch = req.method === 'GET' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/svg\/?$/);
+    if (getSvgMatch) {
+      const goalId = getSvgMatch[1];
+      const goal = readGoal(goalId, rootDir);
+      if (!goal) { res.writeHead(404, { 'Content-Type': 'text/plain' }); res.end(`Goal ${goalId} not found`); return; }
+      try {
+        const svg = renderGoalSvg(goalId, rootDir);
+        res.writeHead(200, { 'Content-Type': 'image/svg+xml', 'Cache-Control': 'no-store' });
+        res.end(svg);
+        logEvent({ event: 'goal', action: 'render.serve', name: goalId, via: 'http' }, rootDir);
+      } catch (e) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('render failed: ' + e.message);
+      }
+      return;
+    }
+
+    const getProgressMatch = req.method === 'GET' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/progress\/?$/);
+    if (getProgressMatch) {
+      const goalId = getProgressMatch[1];
+      const goal = readGoal(goalId, rootDir);
+      if (!goal) { sendJson(res, 404, { error: 'not_found', goal_id: goalId }); return; }
+      const p = computeGoalProgress(goalId, rootDir);
+      sendJson(res, 200, p);
+      return;
+    }
+
+    const postFieldMatch = req.method === 'POST' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/field\/?$/);
+    if (postFieldMatch) {
+      const goalId = postFieldMatch[1];
+      ensureBrowserClaim(goalId, rootDir);
+      readJsonBody(req).then((body) => {
+        const goal = readGoal(goalId, rootDir);
+        if (!goal) { sendJson(res, 404, { error: 'not_found', goal_id: goalId }); return; }
+        const field = String(body.field || '');
+        if (!SETTABLE_FIELDS.has(field)) {
+          sendJson(res, 400, { error: 'field_not_settable', field, allowed: [...SETTABLE_FIELDS] });
+          return;
+        }
+        const newValue = body.value === undefined ? null : body.value;
+        const limit = FIELD_MAX[field];
+        if (newValue && typeof newValue === 'string' && limit && newValue.length > limit) {
+          sendJson(res, 400, { error: 'value_too_long', field, max: limit, got: newValue.length });
+          return;
+        }
+        const oldValue = goal.fm[field] !== undefined ? goal.fm[field] : null;
+        updateGoalFrontmatter(goalId, (fm) => { fm[field] = newValue; fm.last_updated = todayIso(); return fm; }, rootDir);
+        syncIndexEntry(goalId, rootDir);
+        logGoalEvent({
+          event: 'goal_field_updated',
+          goal_id: goalId,
+          field,
+          old: oldValue,
+          new: newValue,
+          changed_by: 'browser',
+        }, rootDir);
+        logEvent({ event: 'goal', action: 'edit.commit', name: goalId, field, via: 'http' }, rootDir);
+        sendJson(res, 200, { ok: true, goal_id: goalId, field, value: newValue });
+      }).catch((e) => sendJson(res, 400, { error: 'bad_body', detail: e.message }));
+      return;
+    }
+
+    const postStatusMatch = req.method === 'POST' && req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/status\/?$/);
+    if (postStatusMatch) {
+      const goalId = postStatusMatch[1];
+      ensureBrowserClaim(goalId, rootDir);
+      readJsonBody(req).then((body) => {
+        const goal = readGoal(goalId, rootDir);
+        if (!goal) { sendJson(res, 404, { error: 'not_found', goal_id: goalId }); return; }
+        const newStatus = String(body.status || '');
+        if (!VALID_STATUSES.has(newStatus)) {
+          sendJson(res, 400, { error: 'invalid_status', allowed: [...VALID_STATUSES] });
+          return;
+        }
+        const oldStatus = goal.fm.status || 'Draft';
+        if (oldStatus === newStatus) {
+          sendJson(res, 200, { ok: true, noop: true, status: newStatus });
+          return;
+        }
+        const oldVersion = goal.fm.goal_version || 1;
+        const newVersion = oldVersion + 1;
+        updateGoalFrontmatter(goalId, (fm) => {
+          fm.status = newStatus;
+          fm.goal_version = newVersion;
+          fm.last_updated = todayIso();
+          if (newStatus === 'Abandoned' && !fm.archived_at) fm.archived_at = nowUtc();
+          if (newStatus !== 'Abandoned' && fm.archived_at) fm.archived_at = null;
+          return fm;
+        }, rootDir);
+        syncIndexEntry(goalId, rootDir);
+        logGoalEvent({
+          event: 'goal_status_changed',
+          goal_id: goalId,
+          from_status: oldStatus,
+          to_status: newStatus,
+          changed_by: 'browser',
+        }, rootDir);
+        logGoalEvent({
+          event: 'goal_pivoted',
+          goal_id: goalId,
+          from_version: oldVersion,
+          to_version: newVersion,
+          summary: `status: ${oldStatus} → ${newStatus}`,
+          changed_by: 'browser',
+        }, rootDir);
+        logEvent({ event: 'goal', action: 'edit.commit', name: goalId, field: 'status', via: 'http' }, rootDir);
+        sendJson(res, 200, { ok: true, goal_id: goalId, from_status: oldStatus, to_status: newStatus, goal_version: newVersion });
+      }).catch((e) => sendJson(res, 400, { error: 'bad_body', detail: e.message }));
+      return;
+    }
+
+    const goalEditMatch = req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/edit\/?$/);
+    if (goalEditMatch) {
+      const goalId = goalEditMatch[1];
+      const goal = readGoal(goalId, rootDir);
+      if (!goal) { res.writeHead(404); res.end(`Goal ${goalId} not found`); return; }
+      const claimId = ensureBrowserClaim(goalId, rootDir);
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+        'Set-Cookie': `dw_watch_token=${watchToken}; Path=/; SameSite=Strict; HttpOnly`,
+      });
+      res.end(renderGoalEditorHtml(goalId, goal, watchToken, claimId));
+      logEvent({ event: 'goal', action: 'edit.open', name: goalId, claim_id: claimId }, rootDir);
+      return;
+    }
+    const goalDetailMatch = req.url.match(/^\/goals\/(G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?)\/?$/);
+    if (goalDetailMatch) {
+      const goalId = goalDetailMatch[1];
+      const goal = readGoal(goalId, rootDir);
+      if (!goal) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end(`Goal ${goalId} not found`);
+        return;
+      }
+      const linked = findLinkedTaskIds(goalId, rootDir);
+      const icon = goal.fm.icon || '🎯';
+      const cycle = goal.fm.cycle || '';
+      const html = `<!doctype html><html><head><meta charset="utf-8"><title>${escHtml(icon)} ${escHtml(goalId)}</title>
+<style>
+body{font:14px/1.6 -apple-system,sans-serif;background:#0d1117;color:#c9d1d9;padding:32px;max-width:960px;margin:0 auto}
+@media(prefers-color-scheme:light){body{background:#fff;color:#1f2328}}
+h1{font-size:24px;margin-bottom:8px;display:flex;align-items:center;gap:12px}
+h1 .icon{font-size:32px;line-height:1}
+.meta{color:#6b7280;font-size:12px;margin-bottom:16px;display:flex;gap:10px;flex-wrap:wrap}
+.meta .cycle{padding:2px 8px;background:rgba(88,166,255,0.15);color:#58a6ff;border-radius:4px;letter-spacing:0.5px}
+.badge{display:inline-block;padding:3px 10px;border-radius:4px;font-size:11px;font-weight:600;color:#fff;background:#0ea5e9}
+.summary{padding:16px;background:#161b22;border-radius:6px;margin:16px 0;line-height:1.6}
+@media(prefers-color-scheme:light){.summary{background:#f6f8fa}}
+.svg-frame{background:#0d1117;border:1px solid #30363d;border-radius:8px;overflow:hidden;margin:24px 0}
+@media(prefers-color-scheme:light){.svg-frame{border-color:#d0d7de}}
+.svg-frame img{display:block;width:100%;height:auto}
+.linked{margin-top:24px}.linked ul{list-style:none;padding:0}.linked li{margin:4px 0;padding:6px 10px;background:#161b22;border-radius:4px;font-family:ui-monospace,monospace;font-size:13px}
+@media(prefers-color-scheme:light){.linked li{background:#f6f8fa}}
+a{color:#58a6ff;text-decoration:none}a:hover{text-decoration:underline}
+nav{margin-bottom:24px;display:flex;gap:16px;justify-content:space-between;align-items:center}
+.edit-btn{padding:6px 14px;background:#238636;color:#fff;border-radius:4px;font-size:12px;font-weight:600}
+.edit-btn:hover{background:#2ea043;text-decoration:none}
+</style></head><body>
+<nav><a href="/goals">← portfolio</a><a href="/goals/${escHtml(goalId)}/edit" class="edit-btn">edit ✎</a></nav>
+<h1><span class="icon">${escHtml(icon)}</span><span class="badge">${escHtml(goal.fm.status || 'Draft')}</span> ${escHtml(goalId)}</h1>
+<div class="meta">
+  <span>Owner: ${escHtml(goal.fm.owner || '?')}</span>
+  <span>·</span>
+  <span>Target: ${escHtml(goal.fm.target_date || 'TBD')}</span>
+  <span>·</span>
+  <span>v${escHtml(goal.fm.goal_version || 1)}</span>
+  ${cycle ? `<span>·</span><span class="cycle">${escHtml(cycle)}</span>` : ''}
+</div>
+${goal.fm.summary ? `<div class="summary">${escHtml(goal.fm.summary)}</div>` : '<div class="summary" style="color:#6b7280;font-style:italic">(no summary)</div>'}
+
+<div class="svg-frame">
+  <img src="/goals/${escHtml(goalId)}/svg" alt="Goal constellation map" loading="lazy">
+</div>
+
+<div class="linked"><h2>Linked tasks (${linked.length})</h2>
+${linked.length === 0 ? '<p style="color:#6b7280">none</p>' : '<ul>' + linked.map((t) => `<li>· ${escHtml(t)}</li>`).join('') + '</ul>'}
+</div>
+</body></html>`;
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(html);
+      return;
+    }
+    res.writeHead(404); res.end('not found');
+  });
+
+  await new Promise((resolve) => server.listen(port, '127.0.0.1', resolve));
+
+  const url = `http://localhost:${port}/`;
+
+  console.log();
+  console.log(chalk.green(`  ✓  watch server: ${url}`));
+  console.log(chalk.dim(`     watching:    ${timelineFile}`));
+  console.log(chalk.dim(`     preview:     ${previewFile}`));
+  console.log(chalk.dim(`     debounce:    ${DEBOUNCE_MS}ms · port: ${port}`));
+  console.log(chalk.dim(`     auth (C-3):  X-Watch-Token required for writes; token at .dw/cache/watch.token`));
+  console.log(chalk.dim(`     token:       ${watchToken.slice(0, 8)}…${watchToken.slice(-4)} (${watchToken.length} chars)`));
+  console.log(chalk.dim(`     Ctrl+C to stop`));
+  console.log();
+
+  const opened = openInBrowser(url);
+  if (!opened) {
+    console.log(chalk.yellow(`     (Browser did not auto-open — paste ${url} manually)`));
+  }
+
+  logEvent({ event: 'task', action: 'watch.start', name: target.name, port }, rootDir);
+
+  const watcher = fsWatch(target.path, { persistent: true }, (eventType, filename) => {
+    if (filename !== 'task.md') return;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      console.log(chalk.dim(`  · ${new Date().toLocaleTimeString()} task.md changed → regenerating`));
+      regenerate();
+    }, DEBOUNCE_MS);
+  });
+
+  const shutdown = () => {
+    console.log();
+    console.log(chalk.dim('  Shutting down watch server…'));
+    watcher.close();
+    sseBroker.shutdown();
+    server.close(() => {
+      logEvent({ event: 'task', action: 'watch.stop', name: target.name }, rootDir);
+      process.exit(0);
+    });
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}