@jmylchreest/aide-plugin 0.0.39 → 0.0.42

package/skills/swarm/SKILL.md

@@ -432,43 +432,90 @@ message_ack: message_id=42, agent_id="agent-auth"
 ./.aide/bin/aide memory add --category=discovery "User model needs email validation"
 ```
 
-**Memory** (shared discoveries):
+## OpenCode Mode
 
-```bash
-./.aide/bin/aide memory add --category=discovery "User model needs email validation"
-```
+OpenCode has native `todowrite`/`todoread` for per-agent progress tracking, and a `task` tool for spawning subagents. However, OpenCode's todos are **session-private** — they are NOT shared across agents. For multi-agent coordination, use **aide tasks** (MCP tools) as the shared task system.
 
-## OpenCode Mode
+### Task System Roles (OpenCode)
 
-OpenCode does not have native subagent support. For multi-agent swarms with OpenCode:
+| System                                                                          | Role                                                | Scope                      |
+| ------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------- |
+| **aide tasks** (MCP: `task_create`, `task_list`, `task_claim`, `task_complete`) | Shared coordination — all agents see the same board | Cross-session, persistent  |
+| **todowrite** (native)                                                          | Personal progress tracking within each agent        | Session-private, per-agent |
+| **aide messages** (MCP: `message_send`, `message_list`)                         | Real-time coordination, status broadcasts, blockers | Cross-session              |
 
-**Setup:**
+### Setup
 
 1. Create worktrees as normal (one per story)
 2. Launch separate OpenCode terminal sessions, one per story
 3. Each session works in its assigned worktree directory
 
-**Coordination:**
+### Orchestrator Workflow
 
-- **No TaskList** — OpenCode sessions don't share a task system
-- **Use aide messages** as the primary coordination mechanism:
-  - Each session uses `message_send` to report status, blockers, and completion
-  - Check `message_list` at each stage transition
-  - The orchestrator monitors all agents via `message_list` with their own agent_id
-- **Use aide state** for progress tracking:
-  ```bash
-  ./.aide/bin/aide state set "agent-auth:stage" "TEST"
-  ./.aide/bin/aide state set "agent-auth:status" "running"
-  ```
-- Monitor all agents: `mcp__plugin_aide_aide__state_list`
-
-**Orchestrator role (human or primary session):**
+The orchestrator (human or primary session):
 
 1. Decompose stories (use `/aide:plan-swarm` first)
 2. Create worktrees
-3. Launch terminal sessions with instructions
-4. Monitor via `message_list` and `state_list`
-5. When all sessions report `completion`, run `/aide:worktree-resolve`
+3. Create aide tasks for all SDLC stages upfront:
+   ```
+   task_create: title="[story-auth][DESIGN] Design auth module"
+   task_create: title="[story-auth][TEST] Write auth tests"
+   task_create: title="[story-auth][DEV] Implement auth"
+   task_create: title="[story-auth][VERIFY] Verify auth"
+   task_create: title="[story-auth][DOCS] Document auth"
+   ```
+4. Launch terminal sessions with instructions (include agent ID and story assignment)
+5. Monitor progress via `task_list` (MCP tool) or `./.aide/bin/aide task list` (CLI)
+6. When all tasks show `done`, run `/aide:worktree-resolve`
+
+### Story Agent Workflow (OpenCode)
+
+Each story agent follows the same SDLC pipeline. Use aide tasks for shared tracking and native `todowrite` for personal step-by-step progress:
+
+```
+## Per SDLC Stage:
+
+1. Claim the stage task:
+   task_claim: task_id=<id>, agent_id=agent-auth
+
+2. Use todowrite for personal tracking:
+   todowrite: [{"content": "Design interfaces for auth", "status": "in_progress", "priority": "high"}]
+
+3. Execute the stage (use appropriate /aide: skill)
+
+4. Complete the aide task:
+   task_complete: task_id=<id>, result="Designed JWT auth with refresh tokens"
+
+5. Send status message:
+   message_send: from="agent-auth", type="status", content="[DESIGN] complete"
+
+6. Check for messages from other agents:
+   message_list: agent_id="agent-auth"
+```
+
+**Note:** aide tasks do not have `blockedBy` dependency chaining like Claude Code native tasks. Stage ordering is enforced by the SDLC pipeline instructions — each agent processes stages sequentially (DESIGN → TEST → DEV → VERIFY → DOCS).
+
+### Coordination (OpenCode)
+
+```
+# Shared task board — all agents see the same tasks
+task_list                                          # View all tasks
+task_list: status="pending"                        # View unclaimed work
+
+# Messages — real-time coordination
+message_send: from="agent-auth", type="status", content="[DESIGN] complete, starting TEST"
+message_send: from="agent-auth", to="agent-payments", type="request", content="Need payment API schema"
+message_list: agent_id="agent-auth"
+message_ack: message_id=42, agent_id="agent-auth"
+
+# State — supplementary progress tracking
+./.aide/bin/aide state set "agent-auth:stage" "TEST"
+
+# Decisions and discoveries — shared knowledge
+mcp__plugin_aide_aide__decision_get with topic="auth-strategy"
+./.aide/bin/aide decision set "auth-strategy" "JWT with refresh tokens"
+./.aide/bin/aide memory add --category=discovery "User model needs email validation"
+```
 
 ## Completion (MANDATORY STEPS)
 
@@ -477,7 +524,11 @@ Swarm completion checklist - ALL REQUIRED:
 ### Step 1: Verify All Stories Complete
 
 ```
+# Claude Code:
 TaskList  # All story tasks must show [completed]
+
+# OpenCode:
+task_list  # All aide tasks must show [done]
 ```
 
 - Every story must have completed all 5 SDLC stages

package/src/cli/config.ts

@@ -51,7 +51,10 @@ export function readConfig(configPath: string): OpenCodeConfig {
   }
   try {
     const raw = readFileSync(configPath, "utf-8");
-    return JSON.parse(raw) as OpenCodeConfig;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return {};
+    return parsed as OpenCodeConfig;
   } catch {
     return {};
   }

package/src/core/aide-client.ts

@@ -8,7 +8,7 @@
  * platform-specific options instead of relying on CLAUDE_PLUGIN_ROOT.
  */
 
-import { execSync, execFileSync } from "child_process";
+import { execFileSync } from "child_process";
 import { existsSync, realpathSync } from "fs";
 import { join } from "path";
 import type { FindBinaryOptions } from "./types.js";
@@ -64,7 +64,10 @@ export function findAideBinary(opts: FindBinaryOptions = {}): string | null {
 
   // 4. PATH fallback
   try {
-    const result = execSync("which aide", { stdio: "pipe", timeout: 2000 })
+    const result = execFileSync("which", ["aide"], {
+      stdio: "pipe",
+      timeout: 2000,
+    })
       .toString()
       .trim();
     if (result) return result;
@@ -187,15 +190,15 @@ export function clearAgentState(
 }
 
 /**
- * Escape a string for safe shell usage (when shell is unavoidable)
+ * Sanitize a string for safe inclusion in log messages and CLI arguments.
+ *
+ * Strips control characters and limits length. This is NOT shell escaping —
+ * use execFileSync (which avoids shells entirely) for subprocess execution.
  */
-export function shellEscape(str: string): string {
-  return str
-    .replace(/\\/g, "\\\\")
-    .replace(/"/g, '\\"')
-    .replace(/\$/g, "\\$")
-    .replace(/`/g, "\\`")
-    .replace(/!/g, "\\!")
-    .replace(/\n/g, " ")
-    .slice(0, 1000);
+export function sanitizeForLog(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 1000);
 }
+
+/** @deprecated Use sanitizeForLog instead */
+export const shellEscape = sanitizeForLog;

package/src/core/mcp-sync.ts

@@ -157,10 +157,20 @@ function readAideConfig(path: string): Record<string, CanonicalMcpServer> {
   if (!existsSync(path)) return {};
 
   try {
-    const raw = JSON.parse(readFileSync(path, "utf-8")) as AideMcpConfig;
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return {};
+    const raw = parsed as AideMcpConfig;
+    const mcpServers = raw.mcpServers;
+    if (
+      typeof mcpServers !== "object" ||
+      mcpServers === null ||
+      Array.isArray(mcpServers)
+    )
+      return {};
     const servers: Record<string, CanonicalMcpServer> = {};
 
-    for (const [name, def] of Object.entries(raw.mcpServers || {})) {
+    for (const [name, def] of Object.entries(mcpServers)) {
       servers[name] = { name, ...def };
     }
 
@@ -444,7 +454,13 @@ function readJournal(path: string): McpSyncJournal {
   }
 
   try {
-    return JSON.parse(readFileSync(path, "utf-8")) as McpSyncJournal;
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return { entries: [], removed: [] };
+    const journal = parsed as McpSyncJournal;
+    if (!Array.isArray(journal.entries)) return { entries: [], removed: [] };
+    if (!Array.isArray(journal.removed)) journal.removed = [];
+    return journal;
   } catch {
     return { entries: [], removed: [] };
   }

package/src/core/partial-memory.ts

@@ -105,7 +105,7 @@ export function buildPartialTags(
 ): string[] {
   const tags = [
     "partial",
-    `session:${sessionId.slice(0, 8)}`,
+    `session:${sessionId.slice(0, 12)}`,
     `tool:${info.toolName.toLowerCase()}`,
   ];
   if (info.filePath) {
@@ -152,19 +152,28 @@ export function storePartialMemory(
   }
 }
 
+/** Shape returned by `aide memory list --format=json`. */
+interface PartialMemoryEntry {
+  id: string;
+  tags: string[];
+  content: string;
+}
+
 /**
- * Gather all partial memories for a session.
+ * Query session partials and map to a caller-chosen type.
  *
- * Uses `aide memory list` with tag filtering to find all partials.
- * Returns the raw output or null if none found.
+ * Runs `aide memory list --tags=partial --format=json`, filters to the
+ * given session, and maps each match through `mapFn`.
  */
-export function gatherPartials(
+function querySessionPartials<T>(
   binary: string,
   cwd: string,
   sessionId: string,
-): string[] {
+  mapFn: (m: PartialMemoryEntry) => T,
+  label: string,
+): T[] {
   try {
-    const sessionTag = `session:${sessionId.slice(0, 8)}`;
+    const sessionTag = `session:${sessionId.slice(0, 12)}`;
 
     const output = execFileSync(
       binary,
@@ -186,23 +195,34 @@ export function gatherPartials(
 
     if (!output || output === "[]") return [];
 
-    interface PartialMemory {
-      id: string;
-      tags: string[];
-      content: string;
-    }
-
-    const memories: PartialMemory[] = JSON.parse(output);
-    // Filter to this session's partials
-    return memories
-      .filter((m) => m.tags?.includes(sessionTag))
-      .map((m) => m.content);
+    const memories: PartialMemoryEntry[] = JSON.parse(output);
+    return memories.filter((m) => m.tags?.includes(sessionTag)).map(mapFn);
   } catch (err) {
-    debug(SOURCE, `Failed to gather partials: ${err}`);
+    debug(SOURCE, `Failed to gather ${label}: ${err}`);
     return [];
   }
 }
 
+/**
+ * Gather all partial memories for a session.
+ *
+ * Uses `aide memory list` with tag filtering to find all partials.
+ * Returns the content strings or an empty array if none found.
+ */
+export function gatherPartials(
+  binary: string,
+  cwd: string,
+  sessionId: string,
+): string[] {
+  return querySessionPartials(
+    binary,
+    cwd,
+    sessionId,
+    (m) => m.content,
+    "partials",
+  );
+}
+
 /**
  * Gather partial memory IDs for a session (for cleanup).
  */
@@ -211,42 +231,13 @@ export function gatherPartialIds(
   cwd: string,
   sessionId: string,
 ): string[] {
-  try {
-    const sessionTag = `session:${sessionId.slice(0, 8)}`;
-
-    const output = execFileSync(
-      binary,
-      [
-        "memory",
-        "list",
-        "--tags=partial",
-        "--all",
-        "--format=json",
-        "--limit=500",
-      ],
-      {
-        cwd,
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 5000,
-      },
-    ).trim();
-
-    if (!output || output === "[]") return [];
-
-    interface PartialMemory {
-      id: string;
-      tags: string[];
-    }
-
-    const memories: PartialMemory[] = JSON.parse(output);
-    return memories
-      .filter((m) => m.tags?.includes(sessionTag))
-      .map((m) => m.id);
-  } catch (err) {
-    debug(SOURCE, `Failed to gather partial IDs: ${err}`);
-    return [];
-  }
+  return querySessionPartials(
+    binary,
+    cwd,
+    sessionId,
+    (m) => m.id,
+    "partial IDs",
+  );
 }
 
 /**

package/src/core/persistence-logic.ts

@@ -74,17 +74,25 @@ export function buildReinforcement(
  * Returns null if stop is allowed, or { reason } if stop should be blocked.
  * When a persistence mode is active and todos exist, the reinforcement
  * message includes the specific incomplete tasks.
+ *
+ * When agentId is provided, only tasks claimed by that agent are considered
+ * for blocking. This prevents subagents from being blocked by tasks that
+ * belong to other agents. Global (unclaimed) tasks still count for all agents.
  */
 export function checkPersistence(
   binary: string,
   cwd: string,
+  agentId?: string,
 ): { reason: string } | null {
   const mode = getActiveMode(binary, cwd);
   if (!mode) return null;
 
-  // Get and increment iteration counter
+  // Get and increment iteration counter (guard against NaN from corrupted state).
+  // NOTE: read-then-write is not atomic, but concurrent Stop events are extremely
+  // rare in practice. The counter is a safety cap, not a precise meter.
   const iterStr = getState(binary, cwd, `${mode}_iterations`) || "0";
-  const iteration = parseInt(iterStr, 10) + 1;
+  const parsed = parseInt(iterStr, 10);
+  const iteration = (Number.isNaN(parsed) ? 0 : parsed) + 1;
   setState(binary, cwd, `${mode}_iterations`, String(iteration));
 
   if (iteration > MAX_PERSISTENCE_ITERATIONS) {
@@ -94,21 +102,37 @@ export function checkPersistence(
     return null;
   }
 
-  // Fetch todos and build a specific continuation message if incomplete tasks exist
+  // Fetch todos and build a specific continuation message if incomplete tasks exist.
+  // If all tasks are complete (or no tasks exist), auto-release: allow stop.
   let todoSummary: string | undefined;
+  let allTasksComplete = false;
   try {
     const todos = fetchTodosFromAide(binary, cwd);
-    const todoResult = checkTodos(todos);
+    const todoResult = checkTodos(todos, agentId);
     if (todoResult.hasIncomplete) {
       todoSummary = todoResult.message;
       debug(
         SOURCE,
         `Found ${todoResult.incompleteCount} incomplete todos for persistence reinforcement`,
       );
+    } else if (todoResult.totalCount > 0) {
+      // All tasks exist and are in terminal states — work is done
+      allTasksComplete = true;
+      debug(
+        SOURCE,
+        `All ${todoResult.totalCount} tasks complete — auto-releasing ${mode} mode`,
+      );
     }
   } catch (err) {
     debug(SOURCE, `Failed to fetch todos for persistence (non-fatal): ${err}`);
   }
 
+  // Auto-release: if tasks exist and all are complete, allow stop
+  if (allTasksComplete) {
+    setState(binary, cwd, "mode", "");
+    setState(binary, cwd, `${mode}_iterations`, "0");
+    return null;
+  }
+
   return { reason: buildReinforcement(mode, iteration, todoSummary) };
 }

package/src/core/session-init.ts

@@ -16,7 +16,7 @@ import {
   statSync,
 } from "fs";
 import { join } from "path";
-import { execSync, execFileSync } from "child_process";
+import { execFileSync } from "child_process";
 import { homedir } from "os";
 import type {
   AideConfig,
@@ -138,11 +138,15 @@ config/mcp-sync.journal.json
  */
 export function getProjectName(cwd: string): string {
   try {
-    const remoteUrl = execSync("git config --get remote.origin.url", {
-      cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 2000,
-    })
+    const remoteUrl = execFileSync(
+      "git",
+      ["config", "--get", "remote.origin.url"],
+      {
+        cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 2000,
+      },
+    )
       .toString()
       .trim();
 

package/src/core/session-summary-logic.ts

@@ -76,7 +76,14 @@ export function buildSessionSummary(
     const entries: TranscriptEntry[] = [];
     for (const line of lines) {
       try {
-        entries.push(JSON.parse(line) as TranscriptEntry);
+        const parsed: unknown = JSON.parse(line);
+        if (
+          typeof parsed === "object" &&
+          parsed !== null &&
+          !Array.isArray(parsed)
+        ) {
+          entries.push(parsed as TranscriptEntry);
+        }
       } catch {
         // Skip malformed
       }
@@ -214,7 +221,7 @@ export function storeSessionSummary(
   summary: string,
 ): boolean {
   try {
-    const tags = `session-summary,session:${sessionId.slice(0, 8)}`;
+    const tags = `session-summary,session:${sessionId.slice(0, 12)}`;
 
     execFileSync(
       binary,

package/src/core/todo-checker.ts

@@ -1,17 +1,18 @@
 /**
  * Todo continuation checker — platform-agnostic.
  *
- * Reads the agent's todo list and checks for incomplete items.
+ * Reads aide tasks (`aide task list`) and checks for incomplete items.
  * Used to enhance persistence-logic.ts with precise todo-aware blocking:
  * instead of a generic "verify your work is complete", we list the
- * specific incomplete todos.
+ * specific incomplete tasks.
  *
- * For Claude Code: reads todos from the transcript (TodoWrite tool outputs)
- *   or from aide task list.
- * For OpenCode: reads todos via client.session.todo() API.
+ * Only checks aide tasks (persistent, cross-session). Native todos
+ * (Claude Code TodoWrite, OpenCode todowrite) are session-scoped
+ * personal tracking and are intentionally not checked here — neither
+ * platform exposes an API for reading them from hooks.
  *
  * This module provides the platform-agnostic core. Platform hooks
- * call it with however they obtained the todo list.
+ * call it via persistence-logic.ts.
  */
 
 import { runAide } from "./aide-client.js";
@@ -19,10 +20,24 @@ import { debug } from "../lib/logger.js";
 
 const SOURCE = "todo-checker";
 
+/**
+ * Known terminal statuses — tasks in these states are considered "done".
+ * Any status NOT in this set is treated as incomplete (including unknown
+ * statuses from future aide versions), which is the safe default for
+ * persistence enforcement.
+ *
+ * Covers both aide backend statuses (done) and any legacy/alias statuses
+ * (completed, cancelled) for forward/backward compatibility.
+ */
+export const TERMINAL_STATUSES = new Set(["done", "completed", "cancelled"]);
+
 export interface TodoItem {
   id: string;
   content: string;
-  status: "pending" | "in_progress" | "completed" | "cancelled";
+  /** Raw status string from aide — may be any value, not just known ones. */
+  status: string;
+  /** Agent that claimed this task, if any. */
+  claimedBy?: string;
   priority?: string;
 }
 
@@ -41,8 +56,16 @@ export interface TodoCheckResult {
 
 /**
  * Check a list of todos for incomplete items and build a continuation message.
+ *
+ * When agentId is provided, only tasks relevant to this agent are considered:
+ * - Unclaimed tasks (pending, blocked) — everyone's responsibility
+ * - Tasks claimed by this agent — this agent's responsibility
+ * Tasks claimed by other agents are filtered out.
  */
-export function checkTodos(todos: TodoItem[]): TodoCheckResult {
+export function checkTodos(
+  todos: TodoItem[],
+  agentId?: string,
+): TodoCheckResult {
   if (!todos || todos.length === 0) {
     return {
       hasIncomplete: false,
@@ -53,29 +76,34 @@ export function checkTodos(todos: TodoItem[]): TodoCheckResult {
     };
   }
 
-  const incomplete = todos.filter(
-    (t) => t.status !== "completed" && t.status !== "cancelled",
-  );
+  // When scoped to a specific agent, filter out tasks claimed by other agents.
+  // Unclaimed tasks (no claimedBy) are considered everyone's responsibility.
+  const relevant = agentId
+    ? todos.filter((t) => !t.claimedBy || t.claimedBy === agentId)
+    : todos;
+
+  const incomplete = relevant.filter((t) => !TERMINAL_STATUSES.has(t.status));
 
   if (incomplete.length === 0) {
     return {
       hasIncomplete: false,
       incompleteCount: 0,
-      totalCount: todos.length,
+      totalCount: relevant.length,
       incompleteItems: [],
       message: "",
     };
   }
 
-  const completedCount = todos.length - incomplete.length;
+  const completedCount = relevant.length - incomplete.length;
   const lines: string[] = [
-    `**TODO CONTINUATION** — ${incomplete.length} of ${todos.length} tasks incomplete (${completedCount} done)`,
+    `**TODO CONTINUATION** — ${incomplete.length} of ${relevant.length} tasks incomplete (${completedCount} done)`,
     "",
     "Remaining tasks:",
   ];
 
   for (const item of incomplete) {
-    const statusIcon = item.status === "in_progress" ? ">" : " ";
+    const statusIcon =
+      item.status === "in_progress" || item.status === "claimed" ? ">" : " ";
     lines.push(`  [${statusIcon}] ${item.content}`);
   }
 
@@ -87,7 +115,7 @@ export function checkTodos(todos: TodoItem[]): TodoCheckResult {
   return {
     hasIncomplete: true,
     incompleteCount: incomplete.length,
-    totalCount: todos.length,
+    totalCount: relevant.length,
     incompleteItems: incomplete,
     message: lines.join("\n"),
   };
@@ -99,6 +127,12 @@ export function checkTodos(todos: TodoItem[]): TodoCheckResult {
  * Output format from `aide task list`:
  *   [status] id: content
  *   e.g.: [pending] abc123: Implement feature X
+ *         [claimed] task-def: Deploy service
+ *
+ * The regex accepts any alphanumeric/underscore status to handle
+ * current statuses (pending, claimed, done, blocked) and any future
+ * additions without code changes. Unknown statuses are treated as
+ * incomplete by checkTodos().
  */
 export function parseTodosFromAide(output: string): TodoItem[] {
   const todos: TodoItem[] = [];
@@ -106,13 +140,14 @@ export function parseTodosFromAide(output: string): TodoItem[] {
 
   for (const line of lines) {
     const match = line.match(
-      /\[(pending|in_progress|completed|cancelled)\]\s+(\S+):\s+(.+)/,
+      /\[(\w+)\]\s+(\S+):\s+(.+?)(?:\s+\(agent:(\S+)\))?$/,
     );
     if (match) {
       todos.push({
-        status: match[1] as TodoItem["status"],
+        status: match[1],
         id: match[2],
         content: match[3].trim(),
+        claimedBy: match[4] || undefined,
       });
     }
   }

package/src/core/tool-tracking.ts

@@ -95,11 +95,9 @@ export function updateToolStats(
     setState(binary, cwd, "startedAt", new Date().toISOString());
   }
 
-  // Track tool calls
-  const currentToolCalls = parseInt(
-    getState(binary, cwd, "toolCalls") || "0",
-    10,
-  );
+  // Track tool calls (guard against NaN from corrupted state)
+  const parsed = parseInt(getState(binary, cwd, "toolCalls") || "0", 10);
+  const currentToolCalls = Number.isNaN(parsed) ? 0 : parsed;
   setState(binary, cwd, "toolCalls", String(currentToolCalls + 1));
   setState(binary, cwd, "lastToolUse", new Date().toISOString());
   setState(binary, cwd, "lastTool", toolName);