@jaggerxtrm/specialists 3.6.1 → 3.6.3

package/config/skills/using-specialists/SKILL.md

@@ -118,7 +118,7 @@ The specialists orchestration model uses three levels:
 | Term | Definition | Persisted? | Merge scope |
 |------|------------|:----------:|:-----------:|
 | **Job** | One specialist run (atomic execution unit) | Yes (SQLite + files) | — |
-| **Chain** | Worktree lineage: executor → reviewer → fix → re-review (seeded by edit-capable specialist) | Yes (`worktree_owner_job_id`) | `sp merge <chain-root>` |
+| **Chain** | Worktree lineage: all specialists sharing one workspace from first dispatch to merge (explorer → executor → reviewer → fix) | Yes (`worktree_owner_job_id`) | `sp merge <chain-root>` |
 | **Epic** | Top merge-gated identity that owns chains across stages | Yes (`epic_runs` table) | `sp epic merge <epic>` |
 | **Wave** | Human shorthand for dispatch batches ("Wave 1", "Wave 2b") — **speech only, NOT persisted** | No | — |
 
@@ -503,6 +503,47 @@ Only dispatch a new fix executor when the original specialist is dead (crashed,
 
 ---
 
+## Chain Lifecycle — Members Are Alive Until Merge
+
+A chain is not just a worktree — it is a **living group of specialists** sharing one workspace. All members of a chain are alive (running or waiting) until the chain is merged or abandoned. Treat chain members as a unit.
+
+### Rules
+
+1. **Never kill individual chain members prematurely.** A chain may include explorer, overthinker, executor, reviewer — all sharing one worktree via `--job`. Do not `sp stop` any member while the chain is active, unless the member has crashed or is context-exhausted (>80%).
+2. **The chain is alive until merge.** From first dispatch (even if it's a READ_ONLY explorer) through reviewer PASS and executor commit — the chain is one living unit. Members stay in `waiting` between turns.
+3. **Resume, don't re-dispatch.** When a chain member needs to act again (executor fixing reviewer findings, overthinker answering follow-ups), use `sp resume` on the existing member. Only dispatch a replacement if the original is dead.
+4. **Merge kills the chain.** When `sp merge` or `sp epic merge` publishes a chain's branch, all chain members become obsolete. *(Future: `sp merge` will auto-stop all chain members on successful merge — no manual cleanup needed.)*
+5. **Stop order matters (until auto-cleanup).** When manually stopping chain members after merge: stop dependents first (reviewer), then the chain owner (executor/explorer). This prevents race conditions with resume paths.
+
+### Chain member states
+
+| Member state | Meaning | Action |
+|-------------|---------|--------|
+| `running` | Actively working | Wait or steer |
+| `waiting` | Idle, retains full context | Resume when needed |
+| `done` | Finished its turn, output appended | Leave alone — chain may still need it |
+| `error` | Crashed or failed | May need replacement dispatch |
+
+### What "don't kill" means in practice
+
+```bash
+# BAD — killing executor before review cycle completes
+sp stop exec-job          # ✗ kills resume path, risks uncommitted work
+
+# BAD — killing overthinker before executor uses its output
+sp stop overthinker-job   # ✗ loses context if follow-up questions arise
+
+# GOOD — chain completes naturally
+sp resume exec-job "Reviewer PASS. Commit your changes."
+# verify commit...
+sp merge unitAI-impl      # publishes branch
+# THEN stop members (future: auto-stopped by merge)
+sp stop rev-job
+sp stop exec-job
+```
+
+---
+
 ## Merge Protocol — Epic Publication
 
 The orchestrator owns merge timing, but **no longer performs manual git merges**. Use `sp epic merge` or `sp merge` instead.

package/config/specialists/explorer.specialist.json

@@ -23,7 +23,7 @@
       "output_type": "analysis",
       "permission_required": "READ_ONLY",
       "max_retries": 0,
-      "interactive": false
+      "interactive": true
     },
     "prompt": {
       "system": "You are a codebase explorer specialist with access to the GitNexus knowledge graph.\nYour job is to analyze codebases deeply and provide clear, structured answers about\narchitecture, patterns, and code organization.\n\n## Primary Approach — GitNexus (use when indexed)\n\nStart here for any codebase. GitNexus gives you call chains, execution flows,\nand symbol relationships that grep/find cannot provide:\n\n1. Read `gitnexus://repo/{name}/context`\n   → Stats, staleness check. If stale, fall back to bash.\n2. `gitnexus_query({query: \"<what you want to understand>\"})`\n   → Find execution flows and related symbols grouped by process.\n3. `gitnexus_context({name: \"<symbol>\"})`\n   → 360-degree view: callers, callees, processes the symbol participates in.\n4. Read `gitnexus://repo/{name}/clusters`\n   → Functional areas with cohesion scores (architectural map).\n5. Read `gitnexus://repo/{name}/process/{name}`\n   → Step-by-step execution trace for a specific flow.\n\n## Fallback Approach — Bash/Grep\n\nUse when GitNexus is unavailable or index is stale:\n- `find`, `tree`, `grep -r` for structure discovery\n- Read key files: package.json, tsconfig.json, README.md, src/index.ts\n- Trace imports manually to understand layer dependencies\n\n## Output Format\n\nAlways provide:\n1. **Summary** (2-3 sentences)\n2. **Architecture overview** — layers, modules, key patterns\n3. **Execution flows** (GitNexus) or **Directory map** (fallback)\n4. **Key symbols** — entry points, central hubs, important interfaces\n5. **Answer** — direct response to the specific question\n\nSTRICT CONSTRAINTS:\n- You MUST NOT edit, write, or modify any files.\n- Read-only: bash (read-only commands), grep, find, ls, GitNexus tools only.\n- If you find something worth fixing, REPORT it — do not fix it.\nEFFICIENCY RULE: Stop using tools and write your final answer after at most 12 tool calls.\n",

package/dist/index.js

@@ -21248,6 +21248,26 @@ class SqliteClient {
       return events;
     }, "readEvents");
   }
+  readLatestToolEvent(jobId) {
+    return withRetry(() => {
+      const row = this.db.query(`
+        SELECT seq, event_json FROM specialist_events
+        WHERE job_id = ? AND type = 'tool'
+        ORDER BY seq DESC, id DESC
+        LIMIT 1;
+      `).get(jobId);
+      if (!row?.event_json)
+        return null;
+      try {
+        const parsed = JSON.parse(row.event_json);
+        if (parsed.type !== "tool")
+          return null;
+        return typeof parsed.seq === "number" ? parsed : { ...parsed, seq: row.seq };
+      } catch {
+        return null;
+      }
+    }, "readLatestToolEvent");
+  }
   readResult(jobId) {
     return withRetry(() => {
       const row = this.db.query("SELECT output FROM specialist_results WHERE job_id = ? LIMIT 1").get(jobId);
@@ -22580,8 +22600,14 @@ class Supervisor {
         });
         if (timelineEvent) {
           appendTimelineEvent(timelineEvent);
-          if (eventType === "tool_execution_end" && toolCallId) {
-            activeToolCalls.delete(toolCallId);
+          if (eventType === "tool_execution_end") {
+            if (toolCallId) {
+              activeToolCalls.delete(toolCallId);
+            } else {
+              latestUncorrelatedToolState = undefined;
+            }
+            const nextActiveTool = activeToolCalls.values().next().value?.tool;
+            setStatus({ current_tool: nextActiveTool });
           }
         } else if (eventType === "text" && !textLogged) {
           textLogged = true;
@@ -22734,6 +22760,7 @@ class Supervisor {
             }
           }
         }
+        setStatus({ current_tool: undefined });
       });
       latestOutput = result.output;
       mkdirSync3(this.jobDir(id), { recursive: true });
@@ -30582,6 +30609,49 @@ function readStatusesFromFiles(jobsDir) {
   }
   return statuses.sort((a, b) => b.started_at_ms - a.started_at_ms);
 }
+function readLastToolEventFromFile(jobsDir, jobId) {
+  const eventsPath = join20(jobsDir, jobId, "events.jsonl");
+  if (!existsSync18(eventsPath))
+    return;
+  try {
+    const lines = readFileSync14(eventsPath, "utf-8").split(`
+`);
+    for (let index = lines.length - 1;index >= 0; index -= 1) {
+      const line = lines[index]?.trim();
+      if (!line)
+        continue;
+      const parsed = parseTimelineEvent(line);
+      if (!parsed || parsed.type !== "tool")
+        continue;
+      return parsed;
+    }
+  } catch {
+    return;
+  }
+  return;
+}
+function resolveDerivedCurrentTool(status, jobsDir, sqliteClient) {
+  let lastToolEvent;
+  try {
+    lastToolEvent = sqliteClient?.readLatestToolEvent(status.id) ?? undefined;
+  } catch {
+    lastToolEvent = undefined;
+  }
+  if (!lastToolEvent) {
+    lastToolEvent = readLastToolEventFromFile(jobsDir, status.id);
+  }
+  if (!lastToolEvent)
+    return status.current_tool;
+  if (lastToolEvent.phase === "start")
+    return lastToolEvent.tool;
+  return;
+}
+function enrichStatusesWithDerivedCurrentTool(statuses, jobsDir, sqliteClient) {
+  return statuses.map((status) => ({
+    ...status,
+    current_tool: resolveDerivedCurrentTool(status, jobsDir, sqliteClient)
+  }));
+}
 function loadStatuses() {
   const sqliteClient = createObservabilitySqliteClient();
   const jobsDir = resolveJobsDir();
@@ -30589,10 +30659,7 @@ function loadStatuses() {
   try {
     const sqliteStatuses = sqliteClient?.listStatuses() ?? [];
     if (sqliteStatuses.length === 0) {
-      return fileStatuses;
-    }
-    if (fileStatuses.length === 0) {
-      return sqliteStatuses.sort((a, b) => b.started_at_ms - a.started_at_ms);
+      return enrichStatusesWithDerivedCurrentTool(fileStatuses, jobsDir, sqliteClient).sort((a, b) => b.started_at_ms - a.started_at_ms);
     }
     const merged = new Map;
     for (const status of fileStatuses)
@@ -30603,9 +30670,9 @@ function loadStatuses() {
         merged.set(status.id, status);
       }
     }
-    return [...merged.values()].sort((a, b) => b.started_at_ms - a.started_at_ms);
+    return enrichStatusesWithDerivedCurrentTool([...merged.values()], jobsDir, sqliteClient).sort((a, b) => b.started_at_ms - a.started_at_ms);
   } catch {
-    return fileStatuses;
+    return enrichStatusesWithDerivedCurrentTool(fileStatuses, jobsDir, sqliteClient).sort((a, b) => b.started_at_ms - a.started_at_ms);
   } finally {
     sqliteClient?.close();
   }
@@ -31284,6 +31351,7 @@ var init_ps = __esm(() => {
   init_supervisor();
   init_job_root();
   init_observability_sqlite();
+  init_timeline_events();
   init_node_resolve();
   init_epic_readiness();
   ACTIVE_STATES = ["starting", "running", "waiting"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.6.1",
+  "version": "3.6.3",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",