agentsys 5.8.5 → 5.9.0

package/lib/state/workflow-state.js

@@ -116,216 +116,136 @@ function getTasksPath(projectPath = process.cwd()) {
   return tasksPath;
 }
 
+/**
+ * Build the canonical default tasks schema.
+ */
+function defaultTasksSchema() {
+  return { active: null, tasks: [], _version: 0 };
+}
+
+/**
+ * Normalize on-disk data to the canonical schema.
+ * Handles two legacy formats:
+ *   - { active } only (pre-v5.8.4)
+ *   - { version, tasks[] } (worktree-manager format)
+ */
+function normalizeTasksData(data) {
+  const out = Object.assign(defaultTasksSchema(), {});
+  // active field
+  if (Object.prototype.hasOwnProperty.call(data, 'active')) {
+    out.active = data.active;
+  }
+  // tasks array
+  if (Array.isArray(data.tasks)) {
+    out.tasks = data.tasks;
+  }
+  // _version
+  if (typeof data._version === 'number') {
+    out._version = data._version;
+  }
+  // _writerId (preserve if present)
+  if (typeof data._writerId === 'string') {
+    out._writerId = data._writerId;
+  }
+  return out;
+}
+
 /**
  * Read tasks.json from main project.
- *
- * Unified schema (v2):
- *   { active: null|Object, tasks: [], _version: number }
- *
- * - active: single active workflow entry (set by createFlow / cleared by completeWorkflow)
- * - tasks:  worktree claim registry (set by worktree-manager / cleared by ship or --abort)
- * - _version: monotonic counter for optimistic locking (managed by writeTasks)
- * - _writerId: per-write unique token used by updateTasks to detect concurrent wins
- *
- * Legacy formats are normalized on read — no migration script needed.
- * Throws on corruption so callers can decide whether to abort or recover,
- * rather than silently overwriting potentially recoverable data.
- *
- * @param {string} projectPath
- * @returns {{ active: null|Object, tasks: Array, _version: number, _writerId?: string }}
- * @throws {Error} If tasks.json exists but cannot be parsed
+ * Returns default schema when file does not exist.
+ * Throws on corrupted JSON to prevent silent data loss.
  */
 function readTasks(projectPath = process.cwd()) {
   const tasksPath = getTasksPath(projectPath);
   if (!fs.existsSync(tasksPath)) {
-    return { active: null, tasks: [], _version: 0 };
+    return defaultTasksSchema();
   }
-  const raw = fs.readFileSync(tasksPath, 'utf8');
   let data;
   try {
-    data = JSON.parse(raw);
+    data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
   } catch (e) {
-    throw new Error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}. File must be repaired or deleted manually before writes are allowed.`);
+    throw new Error(`Corrupted tasks.json at ${tasksPath}: ${e.message}`);
   }
-  // Normalize: ensure every field exists (handles legacy { active } and legacy { version, tasks[] })
-  return {
-    active: Object.prototype.hasOwnProperty.call(data, 'active') ? data.active : null,
-    tasks: Array.isArray(data.tasks) ? data.tasks : [],
-    _version: typeof data._version === 'number' ? data._version : 0,
-    _writerId: typeof data._writerId === 'string' ? data._writerId : undefined
-  };
+  return normalizeTasksData(data);
 }
 
 /**
- * Write tasks.json atomically.
- * Increments _version and stamps a unique _writerId per write.
- *
- * Both fields are used by updateTasks to verify it was the winning writer:
- * if two processes both read _version N, both write _version N+1 (last
- * renameSync wins), the loser re-reads and finds a _writerId that does not
- * match its own — it knows it lost and retries.
- *
- * @returns {string} The _writerId stamped into this write
+ * Write tasks.json to main project.
+ * Increments _version and stamps _writerId.
+ * Returns the writerId that was stamped (string).
  */
 function writeTasks(tasks, projectPath = process.cwd()) {
   ensureStateDir(projectPath);
-  const copy = structuredClone(tasks);
-  copy._version = (copy._version || 0) + 1;
-  copy._writerId = crypto.randomBytes(8).toString('hex');
   const tasksPath = getTasksPath(projectPath);
-  writeJsonAtomic(tasksPath, copy);
-  return copy._writerId;
+  const writerId = crypto.randomBytes(8).toString('hex');
+  const toWrite = Object.assign({}, tasks, {
+    _version: (tasks._version || 0) + 1,
+    _writerId: writerId
+  });
+  writeJsonAtomic(tasksPath, toWrite);
+  return writerId;
 }
 
 /**
  * Apply a mutation to tasks.json with optimistic locking.
+ * Retries up to 5 times on concurrent-writer conflict.
+ * Returns true on success, false if tasks.json is corrupted.
  *
- * Uses _version + _writerId to detect wins in concurrent-writer races:
- *   1. Read current state, snapshot _version
- *   2. Apply mutatorFn(clone) → new state; skip write if state unchanged
- *   3. Stamp a unique writerId, write atomically (increments _version)
- *   4. Re-read: if _version === initialVersion + 1 AND _writerId matches → we won
- *   5. Otherwise another writer raced us → back off with jitter, retry
- *
- * @param {function(Object): Object} mutatorFn - Pure function that receives a
- *   deep clone of current tasks state and returns the desired new state.
- *   Must not have side effects; may be called multiple times on retry.
- * @param {string} projectPath
- * @returns {boolean} true on success, false after MAX_RETRIES exhausted or on corruption
+ * @param {function(Object): Object} mutatorFn - Receives current tasks, must return updated tasks.
+ * @param {string} [projectPath]
+ * @returns {boolean}
  */
 function updateTasks(mutatorFn, projectPath = process.cwd()) {
   const MAX_RETRIES = 5;
-
-  let current;
-  try {
-    current = readTasks(projectPath);
-  } catch (e) {
-    console.error(`[ERROR] updateTasks: cannot read tasks.json — ${e.message}`);
-    return false;
-  }
-
   for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-    const initialVersion = current._version || 0;
-
-    let updated;
+    let current;
     try {
-      updated = mutatorFn(structuredClone(current));
+      current = readTasks(projectPath);
     } catch (e) {
-      console.error(`[ERROR] updateTasks: mutatorFn threw on attempt ${attempt + 1}: ${e.message}`);
+      // Corrupted — do not overwrite
       return false;
     }
-
-    // Skip write if mutatorFn made no changes — avoids spurious version bumps
-    if (JSON.stringify(updated) === JSON.stringify(current)) {
-      return true;
-    }
-
-    // Carry forward the pre-write version so writeTasks increments it by exactly 1
-    updated._version = initialVersion;
-
+    const updated = mutatorFn(Object.assign({}, current));
     const writerId = writeTasks(updated, projectPath);
-
-    // Verify we won: version must be exactly initialVersion + 1 AND writerId must match ours.
-    // If another process also wrote _version: initialVersion + 1, only one writerId survives.
+    // Verify our write won (optimistic lock check)
     let afterWrite;
     try {
       afterWrite = readTasks(projectPath);
     } catch (e) {
-      console.error(`[ERROR] updateTasks: tasks.json corrupted after write on attempt ${attempt + 1}: ${e.message}`);
       return false;
     }
-
-    if (afterWrite._version === initialVersion + 1 && afterWrite._writerId === writerId) {
+    if (afterWrite._writerId === writerId) {
       return true;
     }
-
-    // Lost the race — retry from the current on-disk state
-    if (attempt < MAX_RETRIES - 1) {
-      const delay = Math.floor(Math.random() * 50) + 10;
-      sleepForRetry(delay);
-      try {
-        current = readTasks(projectPath);
-      } catch (e) {
-        console.error(`[ERROR] updateTasks: tasks.json corrupted during retry ${attempt + 1}: ${e.message}`);
-        return false;
-      }
-    }
+    // Another writer won — retry with jitter
+    const jitter = Math.floor(Math.random() * 20);
+    const start = Date.now();
+    while (Date.now() - start < jitter) { /* busy-wait for short jitter */ }
   }
-
-  const tasksPath = getTasksPath(projectPath);
-  let lastVersion = '(unreadable)';
-  try { lastVersion = readTasks(projectPath)._version; } catch {}
-
-  // Final fallback: if a concurrent writer happened to apply the exact same
-  // mutation (idempotent operations like releaseTask on an already-absent entry),
-  // treat the outcome as a success rather than reporting a spurious failure.
-  let latest;
-  try { latest = readTasks(projectPath); } catch {}
-  if (latest) {
-    // Re-run the mutator on what's on disk; if the result is identical to
-    // what's already there, our desired state is already achieved.
-    try {
-      const wouldBe = mutatorFn(structuredClone(latest));
-      // Normalize _version/_writerId before comparing content
-      wouldBe._version = latest._version;
-      wouldBe._writerId = latest._writerId;
-      if (JSON.stringify(wouldBe) === JSON.stringify(latest)) {
-        return true;
-      }
-    } catch {}
-  }
-
-  console.error(
-    `[ERROR] updateTasks: all ${MAX_RETRIES} attempts failed due to concurrent writers on ${tasksPath}. ` +
-    `Another agent process is modifying the registry simultaneously. ` +
-    `Last known _version: ${lastVersion}. ` +
-    `Suggested recovery: wait for the competing process to finish, then retry the operation.`
-  );
   return false;
 }
 
 /**
- * Set active task in main project (uses optimistic locking)
- */
-function setActiveTask(task, projectPath = process.cwd()) {
-  return updateTasks(tasks => {
-    tasks.active = { ...task, startedAt: new Date().toISOString() };
-    return tasks;
-  }, projectPath);
-}
-
-/**
- * Clear active task (uses optimistic locking)
- */
-function clearActiveTask(projectPath = process.cwd()) {
-  return updateTasks(tasks => {
-    tasks.active = null;
-    return tasks;
-  }, projectPath);
-}
-
-/**
- * Claim a task in the registry (uses optimistic locking).
- * Used by worktree-manager; replaces the raw fs.writeFileSync inline in agent prompts.
+ * Claim (upsert) a task entry in tasks[].
+ * Entry must have an `id` field.
+ * Returns false if entry.id is missing.
  *
- * @param {Object} entry - { id, source, title, branch, worktreePath, claimedBy }
- * @param {string} projectPath
+ * @param {{ id: string, [key: string]: * }} entry
+ * @param {string} [projectPath]
+ * @returns {boolean}
  */
 function claimTask(entry, projectPath = process.cwd()) {
-  if (!entry || !entry.id) {
-    console.error('[ERROR] claimTask: entry.id is required');
+  if (!entry || typeof entry.id !== 'string' || entry.id.length === 0) {
     return false;
   }
   return updateTasks(tasks => {
-    const idx = tasks.tasks.findIndex(t => t.id === entry.id);
-    const record = {
-      ...entry,
+    const existing = tasks.tasks.findIndex(t => t.id === entry.id);
+    const record = Object.assign({}, entry, {
       status: 'claimed',
-      claimedAt: entry.claimedAt || new Date().toISOString(),
       lastActivityAt: new Date().toISOString()
-    };
-    if (idx >= 0) {
-      tasks.tasks[idx] = record;
+    });
+    if (existing >= 0) {
+      tasks.tasks[existing] = record;
     } else {
       tasks.tasks.push(record);
     }
@@ -334,31 +254,44 @@ function claimTask(entry, projectPath = process.cwd()) {
 }
 
 /**
- * Release a claimed task from the registry (uses optimistic locking).
- * Used by ship and --abort; replaces the raw fs.writeFileSync inline cleanup.
+ * Release (remove) a task from tasks[] by id.
+ * Idempotent — returns true even if task was not found.
  *
  * @param {string} taskId
- * @param {string} projectPath
+ * @param {string} [projectPath]
+ * @returns {boolean}
  */
 function releaseTask(taskId, projectPath = process.cwd()) {
-  if (!taskId) {
-    console.error('[ERROR] releaseTask: taskId is required');
-    return false;
-  }
   return updateTasks(tasks => {
-    const before = tasks.tasks.length;
     tasks.tasks = tasks.tasks.filter(t => t.id !== taskId);
-    if (tasks.tasks.length === before) {
-      // Not found — that's fine, idempotent
-      console.error(`[WARN] releaseTask: task ${taskId} was not found in tasks.json registry. It may have already been released or never claimed.`);
-    }
     return tasks;
   }, projectPath);
 }
 
 /**
- * Check if there's an active task.
- * Uses != null to catch both null and undefined (legacy format safety).
+ * Set active task in main project
+ */
+function setActiveTask(task, projectPath = process.cwd()) {
+  const tasks = readTasks(projectPath);
+  tasks.active = {
+    ...task,
+    startedAt: new Date().toISOString()
+  };
+  return writeTasks(tasks, projectPath);
+}
+
+/**
+ * Clear active task
+ */
+function clearActiveTask(projectPath = process.cwd()) {
+  const tasks = readTasks(projectPath);
+  tasks.active = null;
+  return writeTasks(tasks, projectPath);
+}
+
+/**
+ * Check if there's an active task
+ * Uses != null to catch both null and undefined (legacy format safety)
  */
 function hasActiveTask(projectPath = process.cwd()) {
   const tasks = readTasks(projectPath);
@@ -735,10 +668,10 @@ module.exports = {
   readTasks,
   writeTasks,
   updateTasks,
-  setActiveTask,
-  clearActiveTask,
   claimTask,
   releaseTask,
+  setActiveTask,
+  clearActiveTask,
   hasActiveTask,
 
   // Flow (worktree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.8.5",
+  "version": "5.9.0",
   "description": "A modular runtime and orchestration system for AI agents - works with Claude Code, OpenCode, and Codex CLI",
   "main": "lib/platform/detect-platform.js",
   "type": "commonjs",

package/scripts/generate-docs.js

@@ -373,20 +373,31 @@ function generateAgentNavTable(agents, plugins) {
 
 /**
  * Generate the agents count summary line for docs/reference/AGENTS.md.
+ *
+ * Uses static fallbacks when local discovery returns nothing — the agentsys
+ * monorepo no longer contains plugins/, so discovery is empty in CI. Static
+ * counts are derived from STATIC_PLUGIN_AGENT_COUNTS so they stay in sync as
+ * plugins are added.
  */
 function generateAgentCounts(agents, plugins) {
-  const fileBasedAgents = agents.length;
-  const totalAgents = fileBasedAgents + ROLE_BASED_AGENT_COUNT;
-
-  // Count plugins with agents (file-based or role-based)
-  const pluginsWithAgents = new Set();
-  for (const agent of agents) {
-    pluginsWithAgents.add(agent.plugin);
+  const totalAgents = agents.length > 0
+    ? agents.length + ROLE_BASED_AGENT_COUNT
+    : STATIC_AGENT_COUNT;
+  const totalPlugins = plugins.length > 0 ? plugins.length : STATIC_PLUGIN_COUNT;
+
+  let pluginsWithAgentsCount;
+  if (agents.length > 0) {
+    const pluginsWithAgents = new Set(agents.map(a => a.plugin));
+    pluginsWithAgents.add('audit-project'); // role-based
+    pluginsWithAgentsCount = pluginsWithAgents.size;
+  } else {
+    // Static fallback: file-based plugins (count > 0 in static map) plus
+    // audit-project (role-based, count is 0 in the map but still has agents).
+    const fileBasedPluginsWithAgents = Object.values(STATIC_PLUGIN_AGENT_COUNTS).filter(c => c > 0).length;
+    pluginsWithAgentsCount = fileBasedPluginsWithAgents + 1;
   }
-  pluginsWithAgents.add('audit-project'); // role-based
-  const pluginCount = pluginsWithAgents.size;
 
-  return `**TL;DR:** ${totalAgents} agents across ${plugins.length} plugins (${pluginCount} have agents). opus for reasoning, sonnet for patterns, haiku for execution. Each agent does one thing well. <!-- AGENT_COUNT_TOTAL: ${totalAgents} -->`;
+  return `**TL;DR:** ${totalAgents} agents across ${totalPlugins} plugins (${pluginsWithAgentsCount} have agents). opus for reasoning, sonnet for patterns, haiku for execution. Each agent does one thing well. <!-- AGENT_COUNT_TOTAL: ${totalAgents} -->`;
 }
 
 // ---------------------------------------------------------------------------
@@ -418,7 +429,8 @@ const STATIC_PLUGIN_AGENT_COUNTS = {
   'web-ctl': 1,
   'skillers': 2,
   'onboard': 1,
-  'can-i-help': 1
+  'can-i-help': 1,
+  'zig-lsp': 0
 };
 const STATIC_PLUGIN_COUNT = Object.keys(STATIC_PLUGIN_AGENT_COUNTS).length;
 const STATIC_FILE_BASED_AGENT_COUNT = Object.values(STATIC_PLUGIN_AGENT_COUNTS).reduce((sum, count) => sum + count, 0);

package/scripts/plugins.txt

@@ -17,3 +17,4 @@ ship
 skillers
 sync-docs
 web-ctl
+zig-lsp

package/site/content.json

@@ -1,11 +1,11 @@
 {
   "meta": {
     "title": "agentsys",
-    "description": "A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.",
+    "description": "A modular runtime and orchestration system for AI agents. 20 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.",
     "url": "https://agent-sh.github.io/agentsys",
     "repo": "https://github.com/agent-sh/agentsys",
     "npm": "https://www.npmjs.com/package/agentsys",
-    "version": "5.8.5",
+    "version": "5.9.0",
     "author": "Avi Fenesh",
     "author_url": "https://github.com/avifenesh"
   },
@@ -23,7 +23,7 @@
   },
   "stats": [
     {
-      "value": "19",
+      "value": "20",
       "label": "Plugins",
       "suffix": ""
     },

package/site/index.html

@@ -4,12 +4,12 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>AgentSys - Agent Runtime &amp; Orchestration System</title>
-  <meta name="description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
+  <meta name="description" content="A modular runtime and orchestration system for AI agents. 20 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
   <meta name="theme-color" content="#09090b">
 
   <!-- Open Graph -->
   <meta property="og:title" content="AgentSys">
-  <meta property="og:description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills.">
+  <meta property="og:description" content="A modular runtime and orchestration system for AI agents. 20 plugins, 49 agents, 41 skills.">
   <meta property="og:image" content="https://agent-sh.github.io/agentsys/assets/logo.png">
   <meta property="og:url" content="https://agent-sh.github.io/agentsys/">
   <meta property="og:type" content="website">
@@ -17,7 +17,7 @@
   <!-- Twitter Card -->
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="AgentSys">
-  <meta name="twitter:description" content="AI workflow automation. 19 plugins, 49 agents, 41 skills.">
+  <meta name="twitter:description" content="AI workflow automation. 20 plugins, 49 agents, 41 skills.">
   <meta name="twitter:image" content="https://agent-sh.github.io/agentsys/assets/logo.png">
 
   <!-- Content Security Policy -->
@@ -107,7 +107,7 @@
       <div class="hero__inner">
         <div class="hero__content">
           <div class="hero__badge anim-fade-in" data-delay="100">
-            19 plugins &middot; 49 agents &middot; 41 skills
+            20 plugins &middot; 49 agents &middot; 41 skills
           </div>
           <h1 class="hero__title anim-fade-up" id="hero-title" data-delay="200">
             A modular <span class="text-gradient">runtime and orchestration system</span><br>
@@ -156,7 +156,7 @@
     <section class="stats" id="stats" aria-label="Project statistics">
       <div class="stats__inner">
         <div class="stats__item">
-          <span class="stats__number" aria-live="polite" data-target="19">0</span>
+          <span class="stats__number" aria-live="polite" data-target="20">0</span>
           <span class="stats__label">Plugins</span>
         </div>
         <div class="stats__item">

package/site/ux-spec.md

@@ -94,7 +94,7 @@ Scroll order with rationale for each section. All sections are full-width, alter
 - **Single column on mobile:** Text above, terminal below. Stack with 48px gap.
 
 ### Left Column Content
-1. **Badge** (top, above title): Small pill showing version or "19 plugins . 49 agents . 41 skills"
+1. **Badge** (top, above title): Small pill showing version or "20 plugins . 49 agents . 41 skills"
    - Background: `rgba(99, 102, 241, 0.12)`, border: `1px solid rgba(99, 102, 241, 0.25)`, border-radius: 9999px
    - Font: 13px, font-weight 500, primary accent color
    - Padding: 4px 14px
@@ -104,7 +104,7 @@ Scroll order with rationale for each section. All sections are full-width, alter
    - Color: white
    - "entire dev workflow" portion highlighted with a subtle gradient text (primary-to-secondary accent via `background-clip: text`)
 
-3. **Subtitle:** "19 plugins, 49 agents, 41 skills. From task selection to merged PR. Works with Claude Code, OpenCode, Codex CLI, Cursor, and Kiro."
+3. **Subtitle:** "20 plugins, 49 agents, 41 skills. From task selection to merged PR. Works with Claude Code, OpenCode, Codex CLI, Cursor, and Kiro."
    - Font: 18px on desktop, 16px on mobile, font-weight 400, line-height 1.6
    - Color: `rgba(255, 255, 255, 0.6)`
    - Max-width: 520px
@@ -226,9 +226,9 @@ Done. Task to merged PR in 12 minutes.
 ### Stats (left to right)
 | Stat | Value | Label |
 |------|-------|-------|
-| 1 | 19 | Plugins |
+| 1 | 20 | Plugins |
 | 2 | 49 | Agents |
-| 3 | 40 | Skills |
+| 3 | 41 | Skills |
 | 4 | 3,507 | Tests Passing |
 
 ### Styling
@@ -650,13 +650,13 @@ This disables:
 ### Head Content
 ```html
 <title>AgentSys - Agent Runtime &amp; Orchestration System</title>
-<meta name="description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
+<meta name="description" content="A modular runtime and orchestration system for AI agents. 20 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="theme-color" content="#0a0a0f">
 
 <!-- Open Graph -->
 <meta property="og:title" content="AgentSys">
-<meta property="og:description" content="AI workflow automation. 19 plugins, 49 agents, 41 skills. Task to merged PR.">
+<meta property="og:description" content="AI workflow automation. 20 plugins, 49 agents, 41 skills. Task to merged PR.">
 <meta property="og:image" content="https://agent-sh.github.io/agentsys/assets/og-image.png">
 <meta property="og:url" content="https://agent-sh.github.io/agentsys/">
 <meta property="og:type" content="website">
@@ -664,7 +664,7 @@ This disables:
 <!-- Twitter Card -->
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="AgentSys">
-<meta name="twitter:description" content="AI workflow automation. 19 plugins, 49 agents, 41 skills.">
+<meta name="twitter:description" content="AI workflow automation. 20 plugins, 49 agents, 41 skills.">
 <meta name="twitter:image" content="https://agent-sh.github.io/agentsys/assets/og-image.png">
 ```