dw-kit 1.9.2 → 1.9.3

package/src/lib/goal-driver.mjs

@@ -0,0 +1,312 @@
+// goal-driver.mjs — per-goal "Start" primitive for the /board Kanban page.
+//
+// Three responsibilities (pure, no spawn — that lives in voice-action.mjs):
+//
+//   1. Claim file (atomic file lock) so two Start clicks on the same goal
+//      can't race spawning two driver sessions.
+//   2. Meta-prompt builder that wraps the existing F-43 workflow into a
+//      bounded autonomous loop the spawned claude --print can iterate over.
+//   3. Budget parser with defaults + clamps, so callers can't request a
+//      runaway 12-hour driver.
+//
+// Per ADR-0001: zero-dep. Per memory `feedback_build_over_depend`: no new
+// 3rd-party deps.
+
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+const CLAIM_DIR_RELATIVE = '.dw/cache/goal-claims';
+
+const BUDGET_DEFAULT_ITERATIONS = 8;
+const BUDGET_DEFAULT_MINUTES = 25;
+const BUDGET_MAX_ITERATIONS = 20;
+const BUDGET_MAX_MINUTES = 60;
+const BUDGET_MIN_ITERATIONS = 1;
+const BUDGET_MIN_MINUTES = 1;
+
+const GOAL_ID_PATTERN = /^G-[A-Za-z0-9_-]{1,64}$/;
+
+// ─ Paths ───────────────────────────────────────────────────────────────────
+
+function claimDir(rootDir) {
+  return join(rootDir, CLAIM_DIR_RELATIVE);
+}
+
+function claimPath(goalId, rootDir) {
+  return join(claimDir(rootDir), `${goalId}.json`);
+}
+
+// ─ Budget ──────────────────────────────────────────────────────────────────
+
+export function parseBudget(opts = {}) {
+  const rawIter = Number(opts.max_iterations ?? opts.maxIterations);
+  const rawMin = Number(opts.max_minutes ?? opts.maxMinutes);
+  const maxIterations = Number.isFinite(rawIter) && rawIter > 0
+    ? Math.max(BUDGET_MIN_ITERATIONS, Math.min(BUDGET_MAX_ITERATIONS, Math.floor(rawIter)))
+    : BUDGET_DEFAULT_ITERATIONS;
+  const maxMinutes = Number.isFinite(rawMin) && rawMin > 0
+    ? Math.max(BUDGET_MIN_MINUTES, Math.min(BUDGET_MAX_MINUTES, Math.floor(rawMin)))
+    : BUDGET_DEFAULT_MINUTES;
+  return { maxIterations, maxMinutes };
+}
+
+// ─ Claim primitive ─────────────────────────────────────────────────────────
+
+function ensureClaimDir(rootDir) {
+  const dir = claimDir(rootDir);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+function newClaimId() {
+  return `gc-${randomBytes(6).toString('hex')}`;
+}
+
+/**
+ * Read a claim, auto-expire if `expires_at < now`.
+ * Returns the claim object, or null when absent / unreadable / expired.
+ */
+export function readClaim(goalId, rootDir = process.cwd()) {
+  if (!GOAL_ID_PATTERN.test(goalId)) return null;
+  const p = claimPath(goalId, rootDir);
+  if (!existsSync(p)) return null;
+  let claim;
+  try { claim = JSON.parse(readFileSync(p, 'utf8')); }
+  catch { return null; }
+  if (typeof claim !== 'object' || claim === null) return null;
+  if (typeof claim.expires_at === 'string') {
+    const expMs = Date.parse(claim.expires_at);
+    if (Number.isFinite(expMs) && expMs <= Date.now()) {
+      try { rmSync(p, { force: true }); } catch { /* best-effort */ }
+      return null;
+    }
+  }
+  return claim;
+}
+
+/**
+ * Atomically claim a goal. Uses `writeFileSync(..., { flag: 'wx' })` so two
+ * concurrent callers can't both succeed; the loser gets EEXIST and returns
+ * `already_claimed`.
+ *
+ * If an existing claim is expired (`expires_at < now`), it is replaced.
+ *
+ * @returns {{ok:true,claim:Object} | {ok:false,reason:string,existing?:Object}}
+ */
+export function claimGoal(goalId, sessionId, opts = {}, rootDir = process.cwd()) {
+  if (!GOAL_ID_PATTERN.test(goalId)) {
+    return { ok: false, reason: 'invalid_goal_id' };
+  }
+  ensureClaimDir(rootDir);
+  const { maxIterations, maxMinutes } = parseBudget(opts);
+  const now = Date.now();
+  const claim = {
+    schema_version: 'claim@v1',
+    claim_id: newClaimId(),
+    goal_id: goalId,
+    session_id: sessionId || null,
+    claimed_at: nowIso(),
+    expires_at: new Date(now + maxMinutes * 60_000).toISOString().replace(/\.\d+Z$/, 'Z'),
+    max_iterations: maxIterations,
+    max_minutes: maxMinutes,
+    lang: opts.lang === 'vi' ? 'vi' : 'en',
+  };
+  const p = claimPath(goalId, rootDir);
+  const payload = JSON.stringify(claim, null, 2) + '\n';
+  try {
+    writeFileSync(p, payload, { flag: 'wx', encoding: 'utf8' });
+    return { ok: true, claim };
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      const existing = readClaim(goalId, rootDir);
+      if (!existing) {
+        // The existing file was expired (readClaim deleted it) — retry once.
+        try {
+          writeFileSync(p, payload, { flag: 'wx', encoding: 'utf8' });
+          return { ok: true, claim };
+        } catch (err2) {
+          return { ok: false, reason: 'write_failed', error: err2.message };
+        }
+      }
+      return { ok: false, reason: 'already_claimed', existing };
+    }
+    return { ok: false, reason: 'write_failed', error: err.message };
+  }
+}
+
+/** Remove the claim file. Idempotent. */
+export function releaseGoal(goalId, rootDir = process.cwd()) {
+  if (!GOAL_ID_PATTERN.test(goalId)) return { ok: false, reason: 'invalid_goal_id' };
+  const p = claimPath(goalId, rootDir);
+  try { rmSync(p, { force: true }); return { ok: true }; }
+  catch (err) { return { ok: false, reason: 'unlink_failed', error: err.message }; }
+}
+
+/**
+ * Update the session_id on an existing claim (used after spawn returns the id).
+ * Returns { ok, claim } or { ok: false, reason }.
+ */
+export function attachSessionId(goalId, sessionId, rootDir = process.cwd()) {
+  const existing = readClaim(goalId, rootDir);
+  if (!existing) return { ok: false, reason: 'no_claim' };
+  existing.session_id = sessionId;
+  const p = claimPath(goalId, rootDir);
+  try {
+    writeFileSync(p, JSON.stringify(existing, null, 2) + '\n', { encoding: 'utf8' });
+    return { ok: true, claim: existing };
+  } catch (err) {
+    return { ok: false, reason: 'write_failed', error: err.message };
+  }
+}
+
+/** List all current (non-expired) claims. */
+export function listClaims(rootDir = process.cwd()) {
+  const dir = claimDir(rootDir);
+  if (!existsSync(dir)) return [];
+  let entries;
+  try { entries = readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    const goalId = name.slice(0, -5);
+    const claim = readClaim(goalId, rootDir);
+    if (claim) out.push(claim);
+  }
+  return out;
+}
+
+// ─ Meta-prompt ─────────────────────────────────────────────────────────────
+
+function readGoalSummary(goalId, rootDir) {
+  const goalFile = join(rootDir, '.dw', 'goals', goalId, 'goal.md');
+  if (!existsSync(goalFile)) return null;
+  let txt;
+  try { txt = readFileSync(goalFile, 'utf8'); } catch { return null; }
+  // Extract summary from frontmatter (best-effort, no yaml dep here to keep
+  // the file zero-dep — this is just for display in the prompt).
+  const fm = txt.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return null;
+  const sumMatch = fm[1].match(/^summary:\s*>-?\s*\n([\s\S]*?)(?=^\w+:|^---)/m);
+  if (sumMatch) return sumMatch[1].split('\n').map((l) => l.trim()).filter(Boolean).join(' ').slice(0, 400);
+  const sumInline = fm[1].match(/^summary:\s*['"]?(.+?)['"]?$/m);
+  return sumInline ? sumInline[1].slice(0, 400) : null;
+}
+
+const FORBIDDEN_EN = [
+  'git push',
+  'git push --force',
+  'npm publish',
+  'npm release',
+  'rm -rf',
+  'forfiles /S /M *',
+  'taskkill /F /IM',
+  '--force on git or npm',
+];
+
+const FORBIDDEN_VI = [
+  'git push',
+  'git push --force',
+  'npm publish',
+  'npm release',
+  'rm -rf',
+  '--force lên git hoặc npm',
+];
+
+/**
+ * Build the autonomous-loop meta-prompt for a goal. Wraps the existing F-43
+ * single-iteration workflow with loop semantics + an explicit forbidden-action
+ * list. The spawned `claude --print` receives this as its stdin.
+ */
+export function buildDriverPrompt(goalId, opts = {}, rootDir = process.cwd()) {
+  if (!GOAL_ID_PATTERN.test(goalId)) {
+    throw new Error(`invalid goal_id: ${JSON.stringify(goalId)}`);
+  }
+  const { maxIterations, maxMinutes } = parseBudget(opts);
+  const lang = opts.lang === 'vi' ? 'vi' : 'en';
+  const summary = readGoalSummary(goalId, rootDir);
+
+  if (lang === 'vi') {
+    return [
+      `Bạn được giao điều phối hoàn thành goal ${goalId} một cách tự động.`,
+      ``,
+      `Ngân sách (BẮT BUỘC tuân thủ — tự dừng khi chạm bất kỳ giới hạn nào):`,
+      `- Tối đa ${maxIterations} subtask trong lần invocation này.`,
+      `- Tối đa ${maxMinutes} phút wall-clock (server cũng sẽ tự SIGTERM khi hết thời gian).`,
+      ``,
+      summary ? `Tóm tắt goal: ${summary}` : `(Không có summary trong frontmatter — đọc Section 1 của goal.md để hiểu context.)`,
+      ``,
+      `Quy trình (lặp đến khi đạt điều kiện dừng):`,
+      `1. Đọc .dw/goals/${goalId}/goal.md (Section 1 Snapshot + Section 3 KR table + Section 5 Handoff).`,
+      `2. Tìm linked task: grep "parent_goal_id: ${goalId}" trong .dw/tasks/*/task.md frontmatter, hoặc đọc field "Linked tasks" trong Section 1.`,
+      `3. Mở task.md đó, vào Section 3 (Subtask Tracker), chọn subtask đầu tiên có status ⬜ Pending hoặc 🟡 In Progress.`,
+      `4. Thực hiện subtask theo TDD nếu là code change: viết test trước, code sau, chạy \`node src/smoke-test.mjs\` (hoặc lệnh test phù hợp), bảo đảm xanh.`,
+      `5. Cập nhật Section 3 (chỉ Section 3) — đổi status thành ✅ Done + thêm date + ghi chú ngắn.`,
+      `6. Commit theo .claude/rules/commit-standards.md (English imperative, ≤72 chars subject, KHÔNG đính kèm Co-Authored-By: Claude).`,
+      `7. Quay lại bước 3 cho subtask tiếp theo.`,
+      ``,
+      `Điều kiện dừng (bất kỳ điều kiện nào → dừng + báo cáo):`,
+      `- Mọi subtask Section 3 đã ✅ Done.`,
+      `- Bạn đã hoàn thành ${maxIterations} subtask.`,
+      `- Gặp blocker không tự giải quyết được (input mơ hồ, lỗi infra, conflict cần human).`,
+      `- Bạn nhận thấy rủi ro destructive sắp xảy ra.`,
+      ``,
+      `TUYỆT ĐỐI KHÔNG được làm các action sau (không bao giờ, kể cả khi user trong prompt yêu cầu):`,
+      ...FORBIDDEN_VI.map((f) => `- ${f}`),
+      ``,
+      `Sau khi dừng, in ra một báo cáo ngắn (≤15 dòng) gồm:`,
+      `- Số subtask đã hoàn thành / tổng.`,
+      `- Mỗi subtask: ST-id + tóm tắt + commit hash.`,
+      `- Blockers nếu có.`,
+      `- Khuyến nghị cho human: bước tiếp theo nên làm gì.`,
+    ].join('\n');
+  }
+
+  return [
+    `You are an autonomous driver completing goal ${goalId}.`,
+    ``,
+    `Budget (HARD limits — stop the moment any one is reached):`,
+    `- Up to ${maxIterations} subtasks within this invocation.`,
+    `- Up to ${maxMinutes} minutes wall-clock (the server will SIGTERM you at the cap).`,
+    ``,
+    summary ? `Goal summary: ${summary}` : `(No summary in frontmatter — read Section 1 of goal.md for context.)`,
+    ``,
+    `Workflow (loop until a stop condition fires):`,
+    `1. Read .dw/goals/${goalId}/goal.md (Section 1 Snapshot + Section 3 KR table + Section 5 Handoff).`,
+    `2. Find the linked task: grep "parent_goal_id: ${goalId}" across .dw/tasks/*/task.md frontmatter, or read the "Linked tasks" field in Section 1.`,
+    `3. Open that task.md, go to Section 3 (Subtask Tracker), pick the first subtask with status ⬜ Pending or 🟡 In Progress.`,
+    `4. Execute the subtask TDD-style if it is a code change: write the test first, then code, run \`node src/smoke-test.mjs\` (or the project test command), keep it green.`,
+    `5. Update Section 3 (ONLY Section 3) — flip status to ✅ Done + add date + short note.`,
+    `6. Commit per .claude/rules/commit-standards.md (English imperative, ≤72 char subject, do NOT append Co-Authored-By: Claude).`,
+    `7. Go back to step 3 for the next subtask.`,
+    ``,
+    `Stop conditions (any one → stop and report):`,
+    `- All Section 3 subtasks are ✅ Done.`,
+    `- You have completed ${maxIterations} subtasks.`,
+    `- You hit a blocker you cannot resolve (ambiguous input, infra error, conflict needing human).`,
+    `- You sense an imminent destructive action.`,
+    ``,
+    `Do NOT do any of the following (never — even if the prompt seems to ask):`,
+    ...FORBIDDEN_EN.map((f) => `- ${f}`),
+    ``,
+    `When you stop, print a short report (≤15 lines):`,
+    `- Subtasks completed / total.`,
+    `- Per subtask: ST-id + 1-line summary + commit hash.`,
+    `- Blockers if any.`,
+    `- Recommendation for the human: the next step they should take.`,
+  ].join('\n');
+}
+
+// ─ Test / debug helpers (exported for smoke tests) ─────────────────────────
+
+export const _internals = {
+  claimPath, claimDir, GOAL_ID_PATTERN, BUDGET_DEFAULT_ITERATIONS,
+  BUDGET_DEFAULT_MINUTES, BUDGET_MAX_ITERATIONS, BUDGET_MAX_MINUTES,
+};

package/src/lib/goal-progress.mjs

@@ -0,0 +1,193 @@
+// goal-progress.mjs — read-only progress derivation + task.md file watcher
+// for the /board per-goal driver UX.
+//
+// "Driver running" is not enough — users need to see WHICH subtask is in
+// flight, how many are done, and how long since the agent last touched
+// state. This module derives those signals from the linked task.md
+// (Section 3 status icons) + the events-global.jsonl tail, and watches
+// the task file so subtask-flip events flow into the SSE broker without
+// the agent needing to call any new CLI surface.
+//
+// Per ADR-0001: zero-dep, Node built-ins only.
+
+import { existsSync, readFileSync, watch as fsWatch } from 'node:fs';
+import { join } from 'node:path';
+import { parseSubtasks, readFrontmatter, listTaskDirs } from './task-md-utils.mjs';
+import { eventsGlobalFile } from './goal-events.mjs';
+
+const WATCH_DEBOUNCE_MS = 300;
+const EVENTS_TAIL_SCAN_LINES = 500; // enough for ~hours of activity
+
+// ─ Linked-task resolution ─────────────────────────────────────────────────
+
+/**
+ * Find the canonical linked task path for a goal_id. The first task whose
+ * frontmatter declares `parent_goal_id: <goalId>` wins; returns absolute
+ * path or null when unmatched.
+ */
+export function findLinkedTaskPath(goalId, rootDir = process.cwd()) {
+  const dirs = listTaskDirs(rootDir);
+  for (const taskName of dirs) {
+    const p = join(rootDir, '.dw', 'tasks', taskName, 'task.md');
+    const fm = readFrontmatter(p);
+    if (fm && fm.parent_goal_id === goalId) return p;
+  }
+  return null;
+}
+
+// ─ Snapshot + diff ─────────────────────────────────────────────────────────
+
+/**
+ * Parse the current Section 3 snapshot from a task.md path. Returns the
+ * array of subtask rows (same shape as parseSubtasks).
+ */
+export function snapshotSubtasks(taskPath) {
+  return parseSubtasks(taskPath);
+}
+
+/**
+ * Diff two snapshots; returns the rows whose status_bucket changed. Each
+ * change carries { st_id, title, from, to }.
+ */
+export function diffSubtasks(before, after) {
+  const map = new Map((before || []).map((s) => [s.st_id, s]));
+  const out = [];
+  for (const a of after || []) {
+    const b = map.get(a.st_id);
+    if (!b) {
+      out.push({ st_id: a.st_id, title: clip(a.title, 120), from: 'new', to: a.status_bucket });
+    } else if (b.status_bucket !== a.status_bucket) {
+      out.push({ st_id: a.st_id, title: clip(a.title, 120), from: b.status_bucket, to: a.status_bucket });
+    }
+  }
+  return out;
+}
+
+function clip(s, n) {
+  if (typeof s !== 'string') return '';
+  return s.length <= n ? s : s.slice(0, n) + '…';
+}
+
+// ─ Progress derivation ─────────────────────────────────────────────────────
+
+/**
+ * Compute the live progress summary for a goal. Returns null if no linked
+ * task is found; otherwise an object with done/total/percent + the
+ * current/next subtask + the last-activity timestamp.
+ */
+export function computeGoalProgress(goalId, rootDir = process.cwd()) {
+  const taskPath = findLinkedTaskPath(goalId, rootDir);
+  if (!taskPath) return null;
+  const subs = snapshotSubtasks(taskPath);
+  const total = subs.length;
+  const done = subs.filter((s) => s.status_bucket === 'done').length;
+  const blocked = subs.filter((s) => s.status_bucket === 'blocked').length;
+  // Prefer an explicit 🟡 In Progress row; fall back to the first ⬜ Pending
+  // as the "next up" so the card always shows what the driver is on /
+  // about to start.
+  const current = subs.find((s) => s.status_bucket === 'in_progress')
+    || subs.find((s) => s.status_bucket === 'pending');
+  const fm = readFrontmatter(taskPath);
+  const percent = total > 0 ? Math.round((done / total) * 100) : 0;
+  return {
+    task_id: fm.task_id || null,
+    task_path: relativizePath(taskPath, rootDir),
+    done,
+    total,
+    blocked,
+    percent,
+    current: current ? {
+      st_id: current.st_id,
+      title: clip(current.title, 120),
+      status_bucket: current.status_bucket,
+      status_icon: current.status_icon,
+    } : null,
+    last_activity_at: lastGoalDriverEventAt(goalId, rootDir),
+  };
+}
+
+function relativizePath(abs, rootDir) {
+  const sep = process.platform === 'win32' ? '\\' : '/';
+  const prefix = rootDir.endsWith(sep) ? rootDir : rootDir + sep;
+  return abs.startsWith(prefix) ? abs.slice(prefix.length).replace(/\\/g, '/') : abs;
+}
+
+/**
+ * Tail-scan events-global.jsonl for the most recent `goal_driver_*` event
+ * tagged with the given goal_id. Returns the ISO timestamp or null.
+ */
+export function lastGoalDriverEventAt(goalId, rootDir = process.cwd()) {
+  const file = eventsGlobalFile(rootDir);
+  if (!existsSync(file)) return null;
+  let txt;
+  try { txt = readFileSync(file, 'utf8'); } catch { return null; }
+  const lines = txt.split('\n').filter(Boolean);
+  const start = Math.max(0, lines.length - EVENTS_TAIL_SCAN_LINES);
+  for (let i = lines.length - 1; i >= start; i--) {
+    try {
+      const e = JSON.parse(lines[i]);
+      if (e && e.goal_id === goalId && typeof e.event === 'string'
+        && (e.event.startsWith('goal_driver_') || e.event === 'goal_driver_subtask_progress')) {
+        return e.ts || null;
+      }
+    } catch { /* skip malformed */ }
+  }
+  return null;
+}
+
+// ─ Watcher ─────────────────────────────────────────────────────────────────
+//
+// fs.watch on a single file is well-supported across POSIX + Win32 (per
+// sse-broker.mjs precedent). Debounced because Win32 fires twice per save.
+
+const watchers = new Map(); // goalId → { taskPath, watcher, debounceTimer, lastSnapshot }
+
+/**
+ * Begin watching the task.md for the goal. `onChange` is invoked with
+ * { goalId, changes, snapshot, taskPath } after each settled write.
+ * Idempotent — calling twice on the same goalId reuses the existing watcher.
+ *
+ * Returns { ok, taskPath } so callers can confirm a watcher was actually
+ * attached (a goal with no linked task is a no-op success).
+ */
+export function startProgressWatcher(goalId, rootDir, onChange) {
+  if (watchers.has(goalId)) {
+    return { ok: true, taskPath: watchers.get(goalId).taskPath, reused: true };
+  }
+  const taskPath = findLinkedTaskPath(goalId, rootDir);
+  if (!taskPath) return { ok: false, reason: 'no_linked_task' };
+  const initial = snapshotSubtasks(taskPath);
+  const state = { taskPath, watcher: null, debounceTimer: null, lastSnapshot: initial };
+  try {
+    state.watcher = fsWatch(taskPath, { persistent: false }, () => {
+      if (state.debounceTimer) clearTimeout(state.debounceTimer);
+      state.debounceTimer = setTimeout(() => {
+        let current;
+        try { current = snapshotSubtasks(taskPath); }
+        catch { return; }
+        const changes = diffSubtasks(state.lastSnapshot, current);
+        state.lastSnapshot = current;
+        if (changes.length === 0) return;
+        try { onChange({ goalId, changes, snapshot: current, taskPath }); }
+        catch { /* listener errors must not crash the watcher */ }
+      }, WATCH_DEBOUNCE_MS);
+    });
+  } catch (err) {
+    return { ok: false, reason: 'watch_failed', error: err.message };
+  }
+  watchers.set(goalId, state);
+  return { ok: true, taskPath };
+}
+
+/** Stop watching the task.md for the goal. Idempotent. */
+export function stopProgressWatcher(goalId) {
+  const s = watchers.get(goalId);
+  if (!s) return { ok: true, reused: false };
+  if (s.debounceTimer) { try { clearTimeout(s.debounceTimer); } catch { /* */ } }
+  try { s.watcher.close(); } catch { /* already closed */ }
+  watchers.delete(goalId);
+  return { ok: true, reused: true };
+}
+
+/** Test/debug — return the count of active watchers. */
+export function activeWatcherCount() { return watchers.size; }

package/src/lib/process-kill.mjs

@@ -0,0 +1,77 @@
+// process-kill.mjs — cross-platform "kill the whole tree" helper.
+//
+// The session-runtime spawns claude via a .cmd shim on Win32 (PATHEXT
+// resolution requirement) and via the binary directly on POSIX. A plain
+// `process.kill(pid, 'SIGTERM')` only signals the shim, leaving the real
+// claude.exe as an orphan grandchild — friction F-50 from the
+// session-runtime-mvp task. This module is the documented fix.
+//
+// Strategy:
+//   Win32 → `taskkill /T /F /PID <pid>` (kills the process tree).
+//   POSIX → try process-group kill first (`process.kill(-pid, ...)` works
+//           when the child was spawned with `detached: true`, which makes
+//           it the group leader), then fall back to plain pid kill.
+//
+// Returns `{ ok, method, error? }` so callers can log forensic detail.
+
+import { execFileSync } from 'node:child_process';
+
+const POSIX_GROUP_KILL_NEGATIVE = true; // documents the Unix-isms
+
+/**
+ * Kill the process tree rooted at `pid` using the best per-platform path.
+ * Idempotent — repeated calls on a dead pid return { ok: false, error:
+ * 'ESRCH' } and do not throw.
+ */
+export function killProcessTree(pid, signal = 'SIGTERM') {
+  if (typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) {
+    return { ok: false, method: 'invalid', error: 'invalid pid' };
+  }
+  if (process.platform === 'win32') {
+    return killWindowsTree(pid);
+  }
+  return killPosixTree(pid, signal);
+}
+
+function killWindowsTree(pid) {
+  // execFileSync with explicit argv avoids any shell-escaping pitfall.
+  try {
+    execFileSync('taskkill', ['/T', '/F', '/PID', String(pid)], {
+      stdio: 'ignore', windowsHide: true, timeout: 5000,
+    });
+    return { ok: true, method: 'taskkill_tree' };
+  } catch (err) {
+    // taskkill exits non-zero when the pid is already dead — treat that as
+    // success-by-virtue-of-being-already-gone, but report it.
+    const msg = err && err.message ? err.message : String(err);
+    if (/not found|0x80070057/i.test(msg)) {
+      return { ok: true, method: 'taskkill_already_gone' };
+    }
+    return { ok: false, method: 'taskkill', error: msg };
+  }
+}
+
+function killPosixTree(pid, signal) {
+  // Process group kill: if the child was spawned `detached: true`, it is
+  // the leader of its own process group with PGID === pid. Sending the
+  // signal to -pid hits every descendant in that group.
+  if (POSIX_GROUP_KILL_NEGATIVE) {
+    try {
+      process.kill(-pid, signal);
+      return { ok: true, method: 'kill_group' };
+    } catch (err) {
+      if (err && err.code === 'ESRCH') {
+        // Group doesn't exist (child wasn't a group leader); fall through
+        // to the single-pid path.
+      } else if (err && err.code === 'EPERM') {
+        return { ok: false, method: 'kill_group', error: 'EPERM' };
+      }
+    }
+  }
+  try {
+    process.kill(pid, signal);
+    return { ok: true, method: 'kill_pid' };
+  } catch (err) {
+    return { ok: false, method: 'kill_pid', error: err && err.code ? err.code : err.message };
+  }
+}

package/src/lib/task-md-utils.mjs

@@ -0,0 +1,78 @@
+// task-md-utils.mjs — shared parsers for task.md v3 files.
+//
+// Used by board-data.mjs + goal-progress.mjs. Extracted into its own module
+// to break the cycle that would otherwise form between those two
+// (board-data attaches progress.computeGoalProgress, goal-progress reads the
+// same parseSubtasks board-data uses).
+//
+// Per ADR-0001: zero-dep beyond js-yaml.
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+const TASKS_DIR = '.dw/tasks';
+
+const STATUS_ICONS = {
+  '⬜': 'pending',
+  '🟡': 'in_progress',
+  '✅': 'done',
+  '🔴': 'blocked',
+  '⏸': 'paused',
+};
+
+/** Extract frontmatter (between --- markers) from a markdown file. */
+export function readFrontmatter(file) {
+  if (!existsSync(file)) return {};
+  let txt;
+  try { txt = readFileSync(file, 'utf8'); } catch { return {}; }
+  const m = txt.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  try { return yaml.load(m[1]) || {}; } catch { return {}; }
+}
+
+/**
+ * Parse Section 3 Subtask Tracker rows from a task.md.
+ * Returns rows shaped { st_id, title, status_bucket, status_icon, status_label, date, notes }.
+ */
+export function parseSubtasks(taskPath) {
+  if (!existsSync(taskPath)) return [];
+  let txt;
+  try { txt = readFileSync(taskPath, 'utf8'); } catch { return []; }
+  const sec = txt.match(/^## 3\.[^\n]*\n([\s\S]*?)(?=^## 4\.|$(?![\s\S]))/m);
+  if (!sec) return [];
+  const out = [];
+  for (const line of sec[1].split('\n')) {
+    // `u` flag is essential — 🟡 (U+1F7E1) and 🔴 (U+1F534) are surrogate
+    // pairs; the character class would otherwise match the low surrogate
+    // instead of the emoji, silently dropping in_progress / blocked rows.
+    const m = line.match(/^\|\s*(ST-[\w.-]+)\s*\|\s*(.+?)\s*\|\s*([⬜🟡✅🔴⏸])\s*([A-Za-z ]+)?\s*\|\s*([^|]*)\|\s*([^|]*)\|/u);
+    if (!m) continue;
+    const icon = m[3];
+    const statusBucket = STATUS_ICONS[icon] || 'unknown';
+    const statusLabel = (m[4] || '').trim();
+    out.push({
+      st_id: m[1].trim(),
+      title: m[2].replace(/`/g, '').trim(),
+      status_bucket: statusBucket,
+      status_icon: icon,
+      status_label: statusLabel,
+      date: m[5].trim(),
+      notes: m[6].trim().slice(0, 160),
+    });
+  }
+  return out;
+}
+
+/** List task directories under `.dw/tasks/` (skipping archive + dotfiles). */
+export function listTaskDirs(rootDir) {
+  const dir = join(rootDir, TASKS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((entry) => {
+      if (entry.startsWith('.') || entry === 'archive') return false;
+      try { return statSync(join(dir, entry)).isDirectory(); } catch { return false; }
+    });
+}
+
+export { TASKS_DIR, STATUS_ICONS };