wogiflow 2.32.0 → 2.34.1

package/lib/workspace-channel-server.js

@@ -22,6 +22,21 @@ const http = require('node:http');
 const readline = require('node:readline');
 const { safeJsonParseContent } = require('./utils');
 
+// S5 (wf-ee87a24e): the version this long-lived server process loaded at boot.
+// Compared against the on-disk package.json to detect a mid-session
+// `npm i wogiflow@latest` that left this process running stale code.
+const SERVER_VERSION = (() => {
+  try { return require('../package.json').version || null; } catch (_err) { return null; }
+})();
+function readDiskVersion() {
+  try {
+    const fs = require('node:fs');
+    const pkgPath = require('node:path').join(__dirname, '..', 'package.json');
+    const raw = fs.readFileSync(pkgPath, 'utf-8'); // fresh read, bypasses require cache
+    return JSON.parse(raw).version || null;
+  } catch (_err) { return null; }
+}
+
 // ============================================================
 // Constants
 // ============================================================
@@ -129,8 +144,11 @@ When you receive a message:
 2. If it's a question or investigation request → do the work, then ALWAYS send results back
 3. If it's a status check → respond with your current task status
 
-CRITICAL — ALWAYS REPLY TO THE MANAGER:
-After completing ANY work triggered by a channel message, you MUST send results back using the workspace_send_message tool with to: "manager". The user only sees the manager terminal — if you don't reply, they never see your results.
+SUSTAINED EXECUTION — a task dispatch runs to COMPLETION across turns:
+A "/wogi-" dispatch (especially one you decompose into sub-tasks) is NOT a one-turn request. Work through ALL sub-tasks in the same session; the Stop hook's continuation gate will keep you going while the task is in-progress with work remaining. Do NOT stop to "report progress" mid-task — only reply when the task is COMPLETE or you are ESCALATING a blocker.
+
+CRITICAL — REPLY TO THE MANAGER WHEN THE TASK IS DONE OR BLOCKED:
+When the dispatched task is complete (or you must escalate), you MUST send results back using the workspace_send_message tool with to: "manager". The user only sees the manager terminal — if you don't reply, they never see your results.
 
 Example: workspace_send_message(to: "manager", message: "## Investigation Results\\n\\n1. Found the bug in X\\n2. Root cause: Y\\n3. Fix: Z")
 
@@ -466,18 +484,60 @@ function broadcastSSE(event) {
 
 const channelTracking = require('./workspace-channel-tracking');
 
+// S4 (wf-87611c5e): the channel server is the only process that sees every
+// inbound dispatch, so it owns the "ack-received" timestamp used by GET /status.
+let _lastInboundAt = 0;
+const STATUS_STALENESS_MS = (() => {
+  const raw = parseInt(process.env.WOGI_STATUS_STALENESS_MS || '', 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : 300000;
+})();
+
 // ============================================================
 // HTTP Server
 // ============================================================
 
 const server = http.createServer(async (req, res) => {
-  // Health check — minimal info, no topology exposure
+  // Health check — minimal info, no topology exposure. PURE liveness: "the
+  // server process is up." Says nothing about whether the agent is working —
+  // use /status for that (S4).
   if (req.method === 'GET' && req.url === '/health') {
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ status: 'ok', repo: REPO_NAME, port: PORT }));
     return;
   }
 
+  // Activity status (S4 / wf-87611c5e) — the real execution state, so a manager
+  // can never mistake a channel POST `ok` for "work happening". Derived from the
+  // worker's own state files + the last inbound dispatch this server saw.
+  if (req.method === 'GET' && req.url === '/status') {
+    let body;
+    try {
+      const path = require('node:path');
+      const stateDir = path.join(process.cwd(), '.workflow', 'state');
+      body = channelTracking.computeWorkerStatus({
+        stateDir,
+        repoName: REPO_NAME,
+        lastInboundAt: _lastInboundAt || undefined,
+        stalenessMs: STATUS_STALENESS_MS
+      });
+      body.port = PORT;
+      // S5: version-drift signal — if the on-disk wogiflow differs from what this
+      // long-lived server loaded, a `flow workspace restart` is required to load it.
+      const diskVersion = readDiskVersion();
+      body.serverVersion = SERVER_VERSION;
+      body.diskVersion = diskVersion;
+      body.versionDrift = Boolean(SERVER_VERSION && diskVersion && SERVER_VERSION !== diskVersion);
+      if (body.versionDrift) {
+        body.restartRequired = `Server is running ${SERVER_VERSION} but ${diskVersion} is on disk — run 'flow workspace restart ${REPO_NAME}'`;
+      }
+    } catch (_err) {
+      body = { repo: REPO_NAME, port: PORT, state: 'unknown' };
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+    return;
+  }
+
   // SSE endpoint for event subscriptions
   if (req.method === 'GET' && req.url?.startsWith('/events')) {
     const lastEventId = req.headers['last-event-id'] || '';
@@ -485,6 +545,44 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  // Manager-triggered restart (S5 / wf-ee87a24e). Writes the wogi-claude
+  // wrapper's restart flag and SIGTERMs this server's parent (the claude
+  // process). The wrapper relaunches claude with a FRESH require cache —
+  // reloading any upgraded wogiflow code, and claude respawns this MCP server.
+  // No PID tracking needed; reuses the proven task-boundary restart loop.
+  if (req.method === 'POST' && (req.url === '/restart' || req.url === '/control/restart')) {
+    const rawFrom = req.headers['x-wogi-from'] || '';
+    // localhost-bound already; additionally require the manager as sender.
+    if (rawFrom && rawFrom !== 'manager' && rawFrom !== 'workspace-manager') {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'restart may only be triggered by the manager' }));
+      return;
+    }
+    let scheduled = false;
+    try {
+      const fs = require('node:fs');
+      const nodePath = require('node:path');
+      const flagPath = process.env.WOGI_RESTART_FLAG ||
+        nodePath.join(process.cwd(), '.workflow', 'state', 'restart-requested');
+      fs.mkdirSync(nodePath.dirname(flagPath), { recursive: true });
+      fs.writeFileSync(flagPath, JSON.stringify({
+        version: 1, reason: 'manager-restart', repo: REPO_NAME,
+        triggeredAt: new Date().toISOString()
+      }, null, 2));
+      // Defer the SIGTERM briefly so the HTTP response flushes first.
+      const ppid = process.ppid;
+      setTimeout(() => { try { process.kill(ppid, 'SIGTERM'); } catch (_err) { /* parent gone */ } }, 150);
+      scheduled = true;
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: err.message }));
+      return;
+    }
+    res.writeHead(202, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, scheduled, repo: REPO_NAME, note: 'worker restarting; channel server will respawn with fresh code' }));
+    return;
+  }
+
   // Receive webhook (POST)
   if (req.method === 'POST') {
     const { body, truncated } = await collectBody(req, MAX_BODY_BYTES);
@@ -508,6 +606,11 @@ const server = http.createServer(async (req, res) => {
       cleanBody = body.substring(effortMatch[0].length);
     }
 
+    // S4: record when a dispatch arrived (ack-received signal for /status).
+    if (channelTracking.DISPATCH_BODY_PATTERN.test(cleanBody)) {
+      _lastInboundAt = Date.now();
+    }
+
     // Forward as channel notification to Claude Code
     const meta = {
       from,

package/lib/workspace-channel-tracking.js

@@ -115,11 +115,112 @@ function tryReconcileInboundCompletion(ctx, tracking) {
   }
 }
 
+// ============================================================
+// Worker activity status (epic-workspace-sustained-exec / S4, wf-87611c5e)
+// ============================================================
+
+const fsNode = require('node:fs');
+const pathNode = require('node:path');
+
+const ACTIVE_PHASES = new Set(['coding', 'validating']);
+const DEFAULT_STALENESS_MS = 300000; // 5 min
+
+function _safeRead(p) {
+  try { return JSON.parse(fsNode.readFileSync(p, 'utf-8')); } catch (_err) { return null; }
+}
+function _mtimeMs(p) {
+  try { return fsNode.statSync(p).mtimeMs; } catch (_err) { return 0; }
+}
+
+/**
+ * Derive the worker's real execution state for GET /status. Distinguishes
+ * ack-received / work-started / in-progress / complete / blocked / idle so the
+ * manager can never mistake a channel POST `ok` (or `/health` ok) for progress.
+ *
+ * Pure-ish (reads files from stateDir); injectable for tests.
+ *
+ * @param {Object} opts
+ * @param {string} opts.stateDir       worker .workflow/state dir
+ * @param {string} [opts.repoName]
+ * @param {number} [opts.lastInboundAt] ms epoch of the last dispatch POST the server saw
+ * @param {number} [opts.stalenessMs]  heartbeat freshness window
+ * @param {number} [opts.now]
+ * @returns {{repo, state, taskId, subtasks:{total,remaining}, lastHeartbeatAt, lastSha, phase}}
+ */
+function computeWorkerStatus(opts = {}) {
+  const stateDir = opts.stateDir;
+  const now = opts.now || Date.now();
+  const stalenessMs = Number.isFinite(opts.stalenessMs) ? opts.stalenessMs : DEFAULT_STALENESS_MS;
+  const out = {
+    repo: opts.repoName || null,
+    state: 'idle',
+    taskId: null,
+    subtasks: { total: 0, remaining: 0 },
+    lastHeartbeatAt: null,
+    lastSha: null,
+    phase: null
+  };
+  try {
+    if (!stateDir) return out;
+    const ready = _safeRead(pathNode.join(stateDir, 'ready.json')) || {};
+    const phaseData = _safeRead(pathNode.join(stateDir, 'workflow-phase.json')) || {};
+    const ledger = _safeRead(pathNode.join(stateDir, 'subtask-state.json'));
+    const counter = _safeRead(pathNode.join(stateDir, 'worker-continuation.json'));
+    const phase = typeof phaseData.phase === 'string' ? phaseData.phase : null;
+    out.phase = phase;
+
+    const inProgress = (ready.inProgress || [])[0] || null;
+
+    // Activity freshness: newest mtime of the files a working worker touches.
+    const lastActivityMs = Math.max(
+      _mtimeMs(pathNode.join(stateDir, 'workflow-phase.json')),
+      _mtimeMs(pathNode.join(stateDir, 'subtask-state.json')),
+      _mtimeMs(pathNode.join(stateDir, 'worker-continuation.json'))
+    );
+    if (lastActivityMs > 0) out.lastHeartbeatAt = new Date(lastActivityMs).toISOString();
+    const activityFresh = lastActivityMs > 0 && (now - lastActivityMs) < stalenessMs;
+
+    if (!inProgress) {
+      const recent = (ready.recentlyCompleted || [])[0] || null;
+      const completedTs = recent && recent.completedAt ? Date.parse(recent.completedAt) : NaN;
+      if (Number.isFinite(completedTs) && (now - completedTs) < stalenessMs) {
+        out.state = 'complete';
+        out.taskId = recent.id || null;
+      } else {
+        out.state = 'idle';
+      }
+      return out;
+    }
+
+    out.taskId = inProgress.id || null;
+    if (ledger && (!ledger.taskId || ledger.taskId === out.taskId) && Array.isArray(ledger.subtasks)) {
+      const open = ledger.subtasks.filter(s => s && (s.status === 'pending' || s.status === 'in_progress')).length;
+      out.subtasks = { total: ledger.subtasks.length, remaining: open };
+    }
+
+    const escalated = counter && counter.taskId === out.taskId && counter.escalated === true;
+    if (escalated) {
+      out.state = 'blocked';
+    } else if (ACTIVE_PHASES.has(phase)) {
+      out.state = activityFresh ? 'in-progress' : 'work-started';
+    } else {
+      // Picked up (in inProgress) but not yet in active-work phase.
+      out.state = 'ack-received';
+    }
+    return out;
+  } catch (_err) {
+    return out; // fail-open: never 500
+  }
+}
+
 module.exports = {
   TASK_ID_PATTERN,
   DISPATCH_BODY_PATTERN,
   QUESTION_BODY_PATTERN,
   COMPLETION_BODY_PATTERN,
   tryRecordInboundDispatch,
-  tryReconcileInboundCompletion
+  tryReconcileInboundCompletion,
+  computeWorkerStatus,
+  ACTIVE_PHASES,
+  DEFAULT_STALENESS_MS
 };

package/lib/workspace-dispatch-tracking.js

@@ -136,6 +136,33 @@ function reconcileDispatch(workspaceRoot, taskId, status, reason) {
   return null;
 }
 
+/**
+ * Refresh a pending dispatch's deadline on a worker-progress heartbeat
+ * (epic-workspace-sustained-exec / S3). A worker grinding through a decomposed
+ * task across many turns would otherwise blow past expectedDeadline and be
+ * misclassified as a silent-halt. Each heartbeat pushes the deadline out and
+ * records lastHeartbeatAt. Keeps status 'pending'. Returns the record or null.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} taskId
+ * @param {number} [extendMs=DEFAULT_DURATION_MS]
+ */
+function refreshDispatchDeadline(workspaceRoot, taskId, extendMs) {
+  const state = loadState(workspaceRoot);
+  const ms = Number.isFinite(extendMs) && extendMs > 0 ? extendMs : DEFAULT_DURATION_MS;
+  for (let i = state.dispatches.length - 1; i >= 0; i--) {
+    const r = state.dispatches[i];
+    if (r && r.taskId === taskId && r.status === 'pending') {
+      r.lastHeartbeatAt = new Date().toISOString();
+      r.expectedDeadline = new Date(Date.now() + ms).toISOString();
+      r.heartbeatCount = (r.heartbeatCount || 0) + 1;
+      saveState(workspaceRoot, state);
+      return r;
+    }
+  }
+  return null;
+}
+
 /**
  * Read all currently-active dispatch records (not archived).
  *
@@ -306,6 +333,7 @@ module.exports = {
   MAX_ACTIVE,
   recordDispatch,
   reconcileDispatch,
+  refreshDispatchDeadline,
   readDispatches,
   getOverdueDispatches,
   attachCompletionSummary,

package/lib/workspace-messages.js

@@ -25,6 +25,10 @@ const MESSAGE_TYPES = [
   'task-complete',    // "I finished my side of feature Z"
   'worker-stopped',   // Graceful Stop hook — worker session ending, not necessarily at task completion
   'worker-ready',     // Fresh worker session with empty queue — "got anything for me?" (wf-restart-handoff)
+  'worker-progress',  // Heartbeat on a forced continuation — work ongoing, NOT a stop (epic-workspace-sustained-exec S3)
+  'worker-blocked',   // Escalation: gate hit a cap / no-progress / validation failure — needs manager (S2/S3)
+  'worker-idle',      // Real terminal stop: nothing in progress and nothing queued (S3)
+  'worker-awaiting-approval', // Spec written, in spec_review — waiting on manager GO, NOT done (S3)
   'needs-help',       // "I'm stuck, can you check X on your side?"
   'heads-up',         // "I'm about to change Y, just FYI"
   'impact-query',     // Pre-dev: "I'm about to change X, will this break you?"
@@ -96,6 +100,32 @@ function createMessage({ from, to, type, subject, body, priority, diff, suggeste
 // Message Persistence (Criterion 2 — lifecycle)
 // ============================================================
 
+/**
+ * Atomically write a JSON file: tmp + fsync(file) + rename (+ best-effort dir
+ * fsync). Guarantees a concurrent reader sees old-or-new, never torn JSON, and
+ * survives the SIGTERM/relaunch boundary. (epic-workspace-sustained-exec / S3 —
+ * the manager was reading partial worker→manager messages off the bus.)
+ * @param {string} filePath
+ * @param {string} data
+ */
+function atomicWriteFile(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, data);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, filePath);
+  try {
+    const dfd = fs.openSync(dir, 'r');
+    try { fs.fsyncSync(dfd); } finally { fs.closeSync(dfd); }
+  } catch (_err) { /* directory fsync best-effort (not supported on all FS) */ }
+}
+
 /**
  * Save a message to the workspace message bus
  * @param {string} workspaceRoot
@@ -104,10 +134,8 @@ function createMessage({ from, to, type, subject, body, priority, diff, suggeste
  */
 function saveMessage(workspaceRoot, message) {
   const messagesDir = path.join(workspaceRoot, '.workspace', 'messages');
-  fs.mkdirSync(messagesDir, { recursive: true });
-
   const filePath = path.join(messagesDir, `${message.id}.json`);
-  fs.writeFileSync(filePath, JSON.stringify(message, null, 2));
+  atomicWriteFile(filePath, JSON.stringify(message, null, 2));
   return filePath;
 }
 
@@ -178,7 +206,7 @@ function updateMessageStatus(workspaceRoot, messageId, newStatus, extra = {}) {
         }
       }
     }
-    fs.writeFileSync(filePath, JSON.stringify(message, null, 2));
+    atomicWriteFile(filePath, JSON.stringify(message, null, 2));
     return message;
   } catch (_err) {
     return null;

package/lib/workspace-subtask-state.js

@@ -0,0 +1,215 @@
+'use strict';
+
+/**
+ * Wogi Flow — Durable Sub-task State (epic-workspace-sustained-exec / S1, wf-e72350bf)
+ *
+ * Sub-tasks of a decomposed task are normally tracked ONLY in Claude Code's
+ * in-context TodoWrite list, which is ephemeral: a Stop hook running in a fresh
+ * `node` process can't read it, and a session restart loses it entirely. That's
+ * the root cause behind workers re-executing completed sub-tasks after a restart
+ * and behind the continuation gate (S2) having no reliable "work remaining"
+ * signal.
+ *
+ * This module mirrors the decomposition to a durable, atomically-written ledger
+ * at `.workflow/state/subtask-state.json` so that:
+ *   - a fresh-process Stop hook can read "N of M sub-tasks remain" (S2),
+ *   - a restarted session can resume without redoing completed sub-tasks (S5).
+ *
+ * The ledger holds the CURRENT in-progress task's decomposition. There is one
+ * active task per worker at a time, so a single-task shape is sufficient and
+ * avoids stale cross-task contamination — read* helpers take an optional taskId
+ * and return empty when it doesn't match the ledger's task.
+ *
+ * Atomic write: tmp + fsync(file) + rename + fsync(dir), mirroring
+ * task-boundary-reset.js:writeCleanCompletionMarker so the ledger survives the
+ * SIGTERM/relaunch boundary and concurrent readers never see torn JSON.
+ *
+ * Fail-open throughout: any error degrades to "no durable state" (callers fall
+ * back to their prior behavior). Never throws.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { PATHS } = require('../scripts/flow-utils');
+const { safeJsonParse } = require('../scripts/flow-io');
+
+const LEDGER_FILE = 'subtask-state.json';
+const LEDGER_VERSION = 1;
+// Statuses that count as "still needs work" for remaining().
+const OPEN_STATUSES = new Set(['pending', 'in_progress']);
+const TERMINAL_STATUSES = new Set(['completed', 'blocked']);
+
+function getLedgerPath() {
+  return path.join(PATHS.state, LEDGER_FILE);
+}
+
+/**
+ * Normalize a free-form sub-task entry (TodoWrite item or plain object/string)
+ * into the ledger shape { id, title, status }.
+ */
+function normalizeSubtask(entry, index) {
+  if (entry == null) return null;
+  if (typeof entry === 'string') {
+    return { id: String(index + 1).padStart(2, '0'), title: entry.slice(0, 500), status: 'pending' };
+  }
+  if (typeof entry !== 'object') return null;
+  const rawStatus = typeof entry.status === 'string' ? entry.status.toLowerCase() : 'pending';
+  const status = OPEN_STATUSES.has(rawStatus) || TERMINAL_STATUSES.has(rawStatus) ? rawStatus : 'pending';
+  const title = entry.title || entry.content || entry.text || entry.description || entry.activeForm || `Sub-task ${index + 1}`;
+  const id = entry.id != null ? String(entry.id) : String(index + 1).padStart(2, '0');
+  return { id, title: String(title).slice(0, 500), status };
+}
+
+/**
+ * Map a Claude Code TodoWrite toolInput ({ todos: [{ content, status }] })
+ * into normalized sub-tasks. Returns [] for anything unparseable.
+ */
+function subtasksFromTodos(toolInput) {
+  try {
+    const todos = toolInput && Array.isArray(toolInput.todos) ? toolInput.todos : null;
+    if (!todos) return [];
+    return todos.map(normalizeSubtask).filter(Boolean);
+  } catch (_err) {
+    return [];
+  }
+}
+
+/**
+ * Read the full ledger object, or null if absent/unreadable.
+ * @returns {{version:number, taskId:string, updatedAt:string, subtasks:Array}|null}
+ */
+function readLedger() {
+  try {
+    const data = safeJsonParse(getLedgerPath(), null);
+    if (!data || typeof data !== 'object' || !Array.isArray(data.subtasks)) return null;
+    return data;
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Read the sub-tasks for a given task. When taskId is provided and doesn't match
+ * the ledger's task, returns [] (the ledger belongs to a different task).
+ * @param {string} [taskId]
+ * @returns {Array<{id:string,title:string,status:string}>}
+ */
+function read(taskId) {
+  const led = readLedger();
+  if (!led) return [];
+  if (taskId && led.taskId && led.taskId !== taskId) return [];
+  return led.subtasks;
+}
+
+/**
+ * Write/replace the ledger for taskId atomically.
+ * @param {string} taskId
+ * @param {Array} subtasks  raw or normalized entries
+ * @returns {{written:boolean, reason?:string, path?:string}}
+ */
+function write(taskId, subtasks) {
+  if (!taskId) return { written: false, reason: 'no-task-id' };
+  try {
+    const normalized = (Array.isArray(subtasks) ? subtasks : [])
+      .map(normalizeSubtask)
+      .filter(Boolean);
+    const payload = {
+      version: LEDGER_VERSION,
+      taskId,
+      updatedAt: new Date().toISOString(),
+      subtasks: normalized
+    };
+    const p = getLedgerPath();
+    const dir = path.dirname(p);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
+    const fd = fs.openSync(tmp, 'w');
+    try {
+      fs.writeSync(fd, JSON.stringify(payload, null, 2));
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, p);
+    try {
+      const dfd = fs.openSync(dir, 'r');
+      try { fs.fsyncSync(dfd); } finally { fs.closeSync(dfd); }
+    } catch (_err) { /* directory fsync best-effort (not supported on all FS) */ }
+    return { written: true, path: p };
+  } catch (err) {
+    return { written: false, reason: `write-failed: ${err.message}` };
+  }
+}
+
+/**
+ * Count sub-tasks still needing work (pending + in_progress) for taskId.
+ * blocked and completed do NOT count. Returns 0 when no matching ledger exists
+ * (no durable state ⇒ "nothing known to remain"; callers decide what that means).
+ * @param {string} [taskId]
+ * @returns {number}
+ */
+function remaining(taskId) {
+  const subs = read(taskId);
+  return subs.filter(s => OPEN_STATUSES.has(s.status)).length;
+}
+
+/**
+ * Summary counts for heartbeats / status (S3, S4).
+ * @param {string} [taskId]
+ * @returns {{total:number, remaining:number, completed:number, blocked:number}}
+ */
+function summary(taskId) {
+  const subs = read(taskId);
+  return {
+    total: subs.length,
+    remaining: subs.filter(s => OPEN_STATUSES.has(s.status)).length,
+    completed: subs.filter(s => s.status === 'completed').length,
+    blocked: subs.filter(s => s.status === 'blocked').length
+  };
+}
+
+/**
+ * Mark one sub-task's status, preserving the rest. No-op if the ledger task
+ * doesn't match. Returns the updated count.
+ * @param {string} taskId
+ * @param {string} subId
+ * @param {string} [status='completed']
+ */
+function markStatus(taskId, subId, status = 'completed') {
+  const led = readLedger();
+  if (!led || (taskId && led.taskId !== taskId)) return { written: false, reason: 'no-matching-ledger' };
+  const next = led.subtasks.map(s => (s.id === String(subId) ? { ...s, status } : s));
+  return write(led.taskId, next);
+}
+
+/**
+ * Clear the ledger (e.g. on task completion). Best-effort.
+ */
+function clear() {
+  try {
+    fs.unlinkSync(getLedgerPath());
+    return { cleared: true };
+  } catch (err) {
+    if (err && err.code !== 'ENOENT' && process.env.DEBUG) {
+      console.error(`[workspace-subtask-state] clear: ${err.code} ${err.message}`);
+    }
+    return { cleared: false };
+  }
+}
+
+module.exports = {
+  getLedgerPath,
+  normalizeSubtask,
+  subtasksFromTodos,
+  readLedger,
+  read,
+  write,
+  remaining,
+  summary,
+  markStatus,
+  clear,
+  LEDGER_FILE,
+  OPEN_STATUSES,
+  TERMINAL_STATUSES
+};