@jaggerxtrm/specialists 3.3.0 → 3.3.2

package/config/skills/specialists-usage-workspace/iteration-1/eval-yaml-debug/with_skill/outputs/result.md

@@ -0,0 +1,150 @@
+# Debugging a Specialist YAML That Doesn't Appear in `specialists list`
+
+When a specialist YAML file you added doesn't show up in `specialists list`, work through these checks in order.
+
+---
+
+## 1. Verify the file is in a scanned directory
+
+The loader scans exactly these directories (in priority order):
+
+```
+<project-root>/specialists/
+<project-root>/.claude/specialists/
+<project-root>/.agent-forge/specialists/
+~/.agents/specialists/          (user scope)
+```
+
+Only directories that exist on disk are scanned. If your file is anywhere else — for example in `./agent-specs/` or `./config/specialists/` — it will never be found.
+
+**Fix**: Move the file into `<project-root>/specialists/`.
+
+---
+
+## 2. Verify the filename ends with `.specialist.yaml`
+
+The loader filters for files ending in exactly `.specialist.yaml`. Common mistakes:
+
+- `my-agent.yaml` — missing `.specialist` infix
+- `my-agent.specialist.yml` — wrong extension (`.yml` not `.yaml`)
+- `my-agent.Specialist.yaml` — wrong casing
+
+**Fix**: Rename to `<name>.specialist.yaml`.
+
+---
+
+## 3. Check stderr for a parse/validation error
+
+When a YAML file fails to parse, the loader silently skips it and writes a warning to stderr:
+
+```
+[specialists] skipping /path/to/file.specialist.yaml: <reason>
+```
+
+Run list and capture stderr explicitly:
+
+```bash
+specialists list 2>&1 | grep -i skipping
+```
+
+If your file appears there, the reason shown is the validation error to fix.
+
+---
+
+## 4. Validate required fields and their formats
+
+The schema enforces strict rules. Every specialist YAML must have:
+
+| Field | Requirement |
+|---|---|
+| `specialist.metadata.name` | **kebab-case** (`^[a-z][a-z0-9-]*$`) — no uppercase, no underscores |
+| `specialist.metadata.version` | **semver** (`1.0.0` format — three numeric parts) |
+| `specialist.metadata.description` | non-empty string |
+| `specialist.metadata.category` | non-empty string |
+| `specialist.execution.model` | non-empty string |
+| `specialist.execution.mode` | one of `tool`, `skill`, `auto` |
+| `specialist.execution.permission_required` | one of `READ_ONLY`, `LOW`, `MEDIUM`, `HIGH` |
+| `specialist.prompt.task_template` | non-empty string |
+
+Common errors that cause silent skipping:
+
+- `name: My_Agent` — fails kebab-case (`_` and uppercase not allowed)
+- `version: "1.0"` — fails semver (needs three parts: `1.0.0`)
+- Missing `execution.model` entirely
+- Missing `prompt.task_template` entirely
+- Top-level key is not `specialist:` (e.g. accidentally used `agent:`)
+
+---
+
+## 5. Validate your YAML syntax independently
+
+A YAML parse error (bad indentation, unquoted special characters, etc.) will also cause the file to be skipped. Validate with:
+
+```bash
+python3 -c "import yaml, sys; yaml.safe_load(open('specialists/my-agent.specialist.yaml'))" && echo OK
+# or
+npx js-yaml specialists/my-agent.specialist.yaml
+```
+
+---
+
+## 6. Check for a name collision
+
+If a specialist with the same `metadata.name` already exists in a higher-priority directory, the loader's deduplication (`seen` set, first-wins) will drop your file silently. Project-scope entries win over user-scope.
+
+```bash
+specialists list --json | python3 -c "import sys,json; [print(s['name'], s['filePath']) for s in json.load(sys.stdin)]"
+```
+
+If the name appears but points to a different file, rename your specialist.
+
+---
+
+## 7. Run `specialists doctor`
+
+```bash
+specialists doctor
+```
+
+This runs deeper checks — hook wiring, MCP registration, zombie jobs, and pi agent availability — and prints fix hints. It is the recommended first step for any unexplained `specialists` issue.
+
+---
+
+## 8. Minimal working example
+
+If unsure what a valid file looks like, create `specialists/debug-test.specialist.yaml` with this minimal content and confirm it appears in `specialists list`:
+
+```yaml
+specialist:
+  metadata:
+    name: debug-test
+    version: 1.0.0
+    description: Minimal test specialist
+    category: debug
+
+  execution:
+    mode: auto
+    model: anthropic/claude-haiku-4-5
+    permission_required: READ_ONLY
+
+  prompt:
+    task_template: |
+      $prompt
+```
+
+Then incrementally add fields from your actual YAML until it breaks — that isolates the bad field.
+
+---
+
+## Summary checklist
+
+- [ ] File is inside `specialists/`, `.claude/specialists/`, or `.agent-forge/specialists/` at the project root
+- [ ] Filename ends in `.specialist.yaml`
+- [ ] `specialists list 2>&1 | grep skipping` shows no entry for this file
+- [ ] `metadata.name` is kebab-case (lowercase letters, digits, hyphens only)
+- [ ] `metadata.version` is semver (`X.Y.Z`)
+- [ ] `execution.model` is present
+- [ ] `prompt.task_template` is present
+- [ ] YAML syntax is valid (no indentation errors)
+- [ ] No other specialist already uses the same `name`
+- [ ] `specialists doctor` reports no blocking errors

package/config/skills/specialists-usage-workspace/iteration-2/eval-bug-investigation/with_skill/outputs/result.md

@@ -0,0 +1,180 @@
+# Bug Investigation: Job Status Inconsistency Between `specialists feed` and `specialists result`
+
+## Approach: Skill Consultation + Delegation Attempt + Direct Investigation
+
+### Step 1: Read the Skill
+
+Read `/home/dawid/projects/specialists/skills/specialists-usage/SKILL.md`.
+
+The skill guidance is clear: for deep bug investigations that span multiple files, delegate to a specialist. This task matched the criteria:
+- It spans multiple files (feed.ts, result.ts, supervisor.ts, timeline-events.ts, timeline-query.ts, runner.ts, pi/session.ts)
+- It would take >5 minutes of focused work
+- A fresh perspective adds value
+
+Decision: **delegate to the `bug-hunt` specialist**.
+
+### Step 2: Delegation Attempt
+
+Created a bead for tracking:
+```
+bd create --title "Investigate: job status inconsistency between specialists feed and specialists result" --type task --priority 2
+# -> unitAI-s82l
+```
+
+Updated with description:
+```
+bd update unitAI-s82l --description "Intermittent failures: specialist jobs show status 'done' in 'specialists feed' output but 'specialists result' says they are still running..."
+```
+
+Discovered that `--prompt` and `--bead` cannot be combined (run exits with error). Used `--bead` only:
+```
+specialists run bug-hunt --bead unitAI-s82l --background
+# -> bcyvkirdh (background job ID in Claude Code's subagent system)
+```
+
+**Important observation**: The `--background` flag here refers to Claude Code's internal background subagent system, NOT the `Supervisor`-managed `.specialists/jobs/` system. The ID `bcyvkirdh` is a Claude Code task ID, not a Supervisor job ID. So `specialists result bcyvkirdh` correctly returned "No job found" — the job was never in `.specialists/jobs/`.
+
+The specialist timed out after 5 minutes (300000ms). Since the delegation did not produce results, I proceeded with direct investigation.
+
+### Step 3: Direct Source Code Investigation
+
+Read all relevant files:
+- `/home/dawid/projects/specialists/src/cli/feed.ts`
+- `/home/dawid/projects/specialists/src/cli/result.ts`
+- `/home/dawid/projects/specialists/src/cli/format-helpers.ts`
+- `/home/dawid/projects/specialists/src/specialist/supervisor.ts`
+- `/home/dawid/projects/specialists/src/specialist/timeline-events.ts`
+- `/home/dawid/projects/specialists/src/specialist/timeline-query.ts`
+- `/home/dawid/projects/specialists/src/specialist/runner.ts`
+- `/home/dawid/projects/specialists/src/pi/session.ts`
+
+---
+
+## Root Cause Analysis
+
+### The Two State Stores
+
+The job lifecycle uses two separate state stores:
+
+1. **`status.json`** — mutable snapshot, read by `specialists result` via `supervisor.readStatus()`
+2. **`events.jsonl`** — append-only timeline, read by `specialists feed` via `readAllJobEvents()`
+
+These are written independently and there is no atomicity guarantee between them.
+
+### The Normal Write Sequence (in `supervisor.run()`)
+
+```
+# After runner.run() completes:
+line 261: writeFileSync(result.txt, result.output)
+line 265-272: updateStatus(id, { status: 'done', ... })   ← status.json -> 'done'
+line 275-279: appendTimelineEvent(createRunCompleteEvent(...))  ← events.jsonl gets run_complete
+line 282: writeFileSync(ready marker)
+```
+
+In the normal path, `status.json` is set to `done` BEFORE `run_complete` is written to `events.jsonl`. This means `result` would work before `feed` shows done — no bug in the happy path.
+
+### The Race Condition (Root Cause)
+
+The bug is caused by a late-firing `onEvent` callback that **overwrites `status.json` back to `running` after it has been set to `done`**.
+
+In `supervisor.run()`, the `onEvent` callback is:
+
+```typescript
+(eventType) => {
+  const now = Date.now();
+  this.updateStatus(id, {
+    status: 'running',  // ← ALWAYS writes 'running', unconditionally
+    current_event: eventType,
+    last_event_at_ms: now,
+    elapsed_s: Math.round((now - startedAtMs) / 1000),
+  });
+  // ...map and append to events.jsonl...
+}
+```
+
+The `updateStatus` method does a read-modify-write:
+```typescript
+private updateStatus(id: string, updates: Partial<SupervisorStatus>): void {
+  const current = this.readStatus(id);
+  if (!current) return;
+  this.writeStatusFile(id, { ...current, ...updates });
+}
+```
+
+**The race sequence:**
+
+1. `runner.run()` resolves (all events have been observed)
+2. `supervisor.run()` calls `updateStatus({status: 'done'})` — status.json now says `done`
+3. `appendTimelineEvent(run_complete)` — events.jsonl now has `run_complete`
+4. A **late `onEvent` callback fires** (queued in the event loop before `await runner.run()` returned but dispatched after)
+5. The late callback calls `updateStatus({status: 'running'})`:
+   - `readStatus()` reads the current `done` status
+   - spreads `{ ...current, ...{ status: 'running' } }` — **overwrites `done` back to `running`**
+   - writes the overwritten status back to `status.json`
+
+**Result state after the race:**
+- `events.jsonl`: contains `run_complete` event → `feed` shows job as **done**
+- `status.json`: was overwritten to `running` → `result` reports job is **still running**
+
+### Why It's Intermittent
+
+This race depends on event loop scheduling. The `onEvent` callback is called synchronously from within `PiAgentSession`'s stdout data handler (`session.ts`). However:
+
+1. The `agent_end` event fires `_doneResolve?.()` which resolves the `_donePromise`
+2. `waitForDone()` in runner.ts awaits this promise
+3. Due to microtask/macrotask ordering, there can be pending `onEvent` callbacks from late `tool_execution_end` or `text_delta` events that were buffered in the same or following stdout chunk
+
+Additionally, the `close()` call in runner.ts (line 213) awaits `_donePromise` again after `waitForDone()`, and the process `close` event can fire additional event handlers.
+
+### Secondary Observation: `agent_end` Suppressed From events.jsonl
+
+In `mapCallbackEventToTimelineEvent`, the `agent_end` callback event is explicitly **suppressed** (returns `null`). So `events.jsonl` never contains `agent_end`. The `isCompletionEvent` function in feed.ts checks for `agent_end`, but this can never be true for events read from disk. This is correct behavior by design, but means the only completion signal in `events.jsonl` is `run_complete`.
+
+### Where to Fix
+
+The fix should be in `supervisor.ts`'s `onEvent` callback. It should not overwrite `status` back to `running` if the status has already been transitioned to `done` or `error`:
+
+```typescript
+// Proposed guard in the onEvent callback:
+(eventType) => {
+  const current = this.readStatus(id);
+  if (!current || current.status === 'done' || current.status === 'error') return; // guard
+  // ...rest of update logic...
+}
+```
+
+Alternatively, `updateStatus` could be made terminal-status-aware:
+
+```typescript
+private updateStatus(id: string, updates: Partial<SupervisorStatus>): void {
+  const current = this.readStatus(id);
+  if (!current) return;
+  // Don't overwrite terminal states unless explicitly transitioning to one
+  if ((current.status === 'done' || current.status === 'error') && !updates.status) return;
+  this.writeStatusFile(id, { ...current, ...updates });
+}
+```
+
+---
+
+## Summary
+
+| Aspect | Detail |
+|--------|--------|
+| **Bug type** | Race condition / state store inconsistency |
+| **Root cause** | Late-firing `onEvent` callbacks overwrite `status.json` from `done` back to `running` after the job has completed |
+| **Why intermittent** | Depends on event loop scheduling; only occurs when event callbacks are queued but not yet flushed at the time `runner.run()` returns |
+| **feed shows done because** | `events.jsonl` gets `run_complete` written before any late event can append (events.jsonl is append-only and `run_complete` is written after `status.json`) |
+| **result says running because** | `status.json` is read-modify-written by the late callback, which spreads `{status: 'running'}` over the already-written `{status: 'done'}` |
+| **Key files** | `src/specialist/supervisor.ts` (lines 226-245, 265-272), `src/cli/result.ts` (line 27), `src/cli/feed.ts` (line 170-172) |
+| **Fix location** | `supervisor.ts` `onEvent` callback — add guard to skip status update if terminal state already set |
+
+---
+
+## Delegation vs Direct Work Reflection
+
+The skill correctly guided delegation as the right approach for this multi-file investigation. The delegation attempt failed due to:
+1. Specialist timeout (300s) — the `bug-hunt` specialist did not start within the timeout window
+2. The background job ran in Claude Code's subagent system, not the Supervisor job system, so `specialists result <id>` correctly could not find it in `.specialists/jobs/`
+
+Since delegation failed, direct investigation was the fallback. The investigation required reading 8 source files and tracing the complete lifecycle across the `PiAgentSession` → `SpecialistRunner` → `Supervisor` → `feed/result CLI` stack.

package/config/skills/specialists-usage-workspace/iteration-2/eval-bug-investigation/with_skill/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 62637,
+  "duration_ms": 399598,
+  "total_duration_seconds": 399.6
+}

package/config/skills/specialists-usage-workspace/iteration-2/eval-bug-investigation/without_skill/outputs/result.md

@@ -0,0 +1,223 @@
+# Bug Investigation: Job Status Inconsistency Between `specialists feed` and `specialists result`
+
+## Summary
+
+The intermittent inconsistency where `specialists feed` shows a job as `done` while `specialists result` says it is still running has **two root causes** operating at different layers of the system:
+
+1. **Race condition between `events.jsonl` and `status.json` writes** — `feed` reads from `events.jsonl`, `result` reads from `status.json`, and these are updated in separate, non-atomic steps with no ordering guarantee between them.
+2. **Dual state storage with divergent update timing in the Supervisor** — the `run_complete` event is appended to `events.jsonl` *after* `status.json` is updated to `done`, but critically, the `result.txt` file is written *before* `status.json` is updated, creating a window where each data source can disagree with the others.
+
+---
+
+## Investigation Steps
+
+### 1. Identified the data sources for each command
+
+**`specialists feed`** (src/cli/feed.ts):
+- Reads `events.jsonl` from `.specialists/jobs/<id>/events.jsonl`
+- Determines "job complete" by looking for a `run_complete` event in the event stream (via `isRunCompleteEvent` in `timeline-events.ts`)
+- Does NOT read `status.json` for completion determination
+
+**`specialists result`** (src/cli/result.ts):
+- Reads `status.json` via `Supervisor.readStatus(jobId)`
+- Checks `status.status === 'running' || status.status === 'starting'` and exits with code 1 if true
+- If status is `done`, reads and prints `result.txt`
+
+### 2. Traced the write sequence in Supervisor.run() (src/specialist/supervisor.ts, lines 260-283)
+
+The completion path in `Supervisor.run()` executes these writes in sequence:
+
+```
+Step A: writeFileSync(resultPath, result.output)       // result.txt written
+Step B: updateStatus(id, { status: 'done', ... })      // status.json updated to 'done'
+Step C: appendTimelineEvent(createRunCompleteEvent(...)) // run_complete appended to events.jsonl
+Step D: writeFileSync(readyDir/id, '')                  // ready marker written
+```
+
+### 3. Identified the race window
+
+Between **Step C** (run_complete appended to events.jsonl) and **Step B** (status.json updated to 'done'), there is a real ordering problem in the opposite direction from what one might expect.
+
+More precisely, looking at the actual code order:
+
+- **Step B** (`status.json` → `done`) happens at line 265
+- **Step C** (`run_complete` event appended to `events.jsonl`) happens at line 275
+
+This means there is a window — however brief — where:
+- `status.json` says `done`
+- `events.jsonl` does NOT yet have `run_complete`
+
+But the reported symptom is the *inverse*: `feed` shows `done` while `result` says `still running`. This means there is also a window where:
+- `events.jsonl` has `run_complete`
+- `status.json` still says `running`
+
+**This can happen through a different path**: `updateStatus` (line 128) reads then writes `status.json`. It reads the current content, merges the patch, and writes via a temp file + rename. If this read-merge-write cycle is slow (e.g., filesystem contention), `events.jsonl` may have been appended with `run_complete` while the status.json rename hasn't completed yet.
+
+Specifically:
+```
+// supervisor.ts line 275 — run_complete appended AFTER status.json update
+appendTimelineEvent(createRunCompleteEvent('COMPLETE', elapsed, {...}));
+```
+
+Wait — looking again at the actual code order in lines 260–283:
+
+```typescript
+// line 261: result.txt written
+writeFileSync(this.resultPath(id), result.output, 'utf-8');
+
+// lines 265-272: status.json updated to 'done'
+this.updateStatus(id, {
+  status: 'done',
+  ...
+});
+
+// lines 275-279: run_complete appended to events.jsonl
+appendTimelineEvent(createRunCompleteEvent('COMPLETE', elapsed, {...}));
+
+// line 282: ready marker written
+writeFileSync(join(this.readyDir(), id), '', 'utf-8');
+```
+
+So the **correct ordering** is: `result.txt` → `status.json:done` → `events.jsonl:run_complete`.
+
+This means there is a window where:
+- `status.json` = `done`
+- `events.jsonl` does NOT yet have `run_complete`
+
+In this window, `specialists result` would succeed (status is done, result.txt exists), but `specialists feed` would NOT show the job as complete because the `run_complete` event hasn't been written yet.
+
+**For the inverse case (feed shows done, result says running):** This can happen if the `run_complete` event somehow appears in `events.jsonl` before `status.json` is updated. However, based on the code, this ordering is not directly possible within a single run.
+
+### 4. Identified a second scenario: the in-progress events.jsonl vs. delayed status.json update
+
+The `onEvent` callback fires during the run (line 224-244 of supervisor.ts):
+```typescript
+(eventType) => {
+  const now = Date.now();
+  this.updateStatus(id, {
+    status: 'running',
+    current_event: eventType,
+    ...
+  });
+  const timelineEvent = mapCallbackEventToTimelineEvent(eventType, {...});
+  if (timelineEvent) {
+    appendTimelineEvent(timelineEvent);
+  }
+}
+```
+
+Each `updateStatus` call does a read-modify-write of `status.json`. If the `run_complete` append to `events.jsonl` (line 275) races with a still-pending `updateStatus` call that was triggered by an earlier callback, the result could be:
+
+1. `run_complete` written to `events.jsonl` → `feed` shows "done"
+2. A queued `updateStatus` write sets status back to `running` (stale write arrives after the `done` update)
+3. `result` reads `status.json`, sees `running`, exits with code 1
+
+### 5. Identified the third scenario: `updateStatus` is not atomic end-to-end
+
+`updateStatus` in supervisor.ts:
+```typescript
+private updateStatus(id: string, updates: Partial<SupervisorStatus>): void {
+  const current = this.readStatus(id);    // read
+  if (!current) return;
+  this.writeStatusFile(id, { ...current, ...updates });  // merge + write
+}
+```
+
+`writeStatusFile` does use a temp-file + rename (atomic write), so partial writes are not the issue. However, the **read-then-write** is not protected by any mutex. If two `updateStatus` calls interleave:
+
+1. Call A reads status.json: `{ status: 'running', current_event: 'tool_execution_end' }`
+2. Call B reads status.json: `{ status: 'running', current_event: 'tool_execution_end' }`
+3. Call B writes: `{ status: 'done', ... }` (the final done update)
+4. Call A writes: `{ status: 'running', current_event: 'tool_execution_end' }` (stale — overwrites the done!)
+
+This is the classic read-modify-write race condition. Since JavaScript is single-threaded, this specific race cannot happen in the same process. However, because `runner.run()` callbacks can fire synchronously within the await chain, and `updateStatus` does a synchronous readFileSync → writeFileSync, there is no async interleaving possible here either.
+
+**Conclusion on this path**: In Node.js single-threaded execution, this race does not actually occur within one process.
+
+### 6. Re-examining the ordering: The real bug
+
+After careful analysis, the primary bug is the **write ordering** in `Supervisor.run()`:
+
+**Normal path (no race):**
+- `result.txt` written
+- `status.json` updated to `done`
+- `events.jsonl` gets `run_complete` appended
+
+**Window of inconsistency A** (status.json → done before events.jsonl → run_complete):
+- `status.json = done` ← `specialists result` would succeed here
+- `events.jsonl` missing `run_complete` ← `specialists feed` would NOT show done here
+
+This is the opposite of the reported bug.
+
+**The reported bug (feed shows done, result says running) points to a different scenario.** Looking at what `feed` considers "done": in follow mode, `isCompletionEvent` checks for `isRunCompleteEvent(event) || event.type === 'done' || event.type === 'agent_end'`.
+
+The `agent_end` and `done` legacy event types are listed as completion signals in `feed.ts` (line 170-172), but these are NOT written to `events.jsonl` in the new code path — `mapCallbackEventToTimelineEvent` returns `null` for `agent_end` and `done` (lines 254-259 of timeline-events.ts). However, **legacy jobs** may still have these events on disk.
+
+More importantly, in the **follow mode** polling loop (feed.ts lines 249-251):
+```typescript
+if (batch.events.some(isCompletionEvent)) {
+  completedJobs.add(batch.jobId);
+}
+```
+
+This runs on every poll tick. If a legacy `agent_end` event is in `events.jsonl` (written by an older version of the code), `feed` would mark the job complete, but if `status.json` was never updated to `done` (e.g., due to a crash after `events.jsonl` write but before `status.json` update), `result` would see `running` or `starting`.
+
+**This is the primary bug scenario**: A crash or error after `events.jsonl` write but before `status.json` update leaves the two sources permanently inconsistent. The crash recovery mechanism in `crashRecovery()` only fires on the next `Supervisor.run()` call (when a new job starts), not proactively. So until another job starts, the stale state persists.
+
+---
+
+## Root Causes Summary
+
+### Root Cause 1: Non-atomic dual-write between status.json and events.jsonl
+
+The completion state is written to two separate files in two sequential writes with no atomicity guarantee between them. A process crash, OS kill, or even a slow filesystem between these two writes leaves them in permanently divergent states.
+
+**Relevant code**: `supervisor.ts` lines 261-282 (the ordering: result.txt → status.json → events.jsonl)
+
+### Root Cause 2: Crash recovery is deferred (not proactive)
+
+`crashRecovery()` is only called at the start of `Supervisor.run()` (line 177). If the process that was running a job crashes after writing `events.jsonl:run_complete` but before updating `status.json:done`, the state remains inconsistent until the next job starts. During this window, `feed` shows done and `result` says running.
+
+**Relevant code**: `supervisor.ts` lines 149-167, 173-177
+
+### Root Cause 3: `result.ts` reads status.json; `feed` reads events.jsonl — no unified source of truth
+
+The two CLI commands consult different data sources with no reconciliation:
+- `specialists result` uses `Supervisor.readStatus()` → `status.json`
+- `specialists feed` uses `readJobEvents()` → `events.jsonl`
+
+`status.json` is the "live mutable state" per design comments (timeline-events.ts line 455), while `events.jsonl` is intended as source of truth for completed jobs. But `result.ts` uses `status.json` for both the completion gate AND the data source without checking `events.jsonl` for a `run_complete` event as a fallback.
+
+### Root Cause 4: Legacy event types create ambiguous completion detection
+
+`feed.ts` treats `agent_end` and `done` events (legacy) as completion signals (line 170-172). These can exist in older `events.jsonl` files even when `status.json` was not properly finalized, causing feed to conclude "done" while result rejects with "still running."
+
+---
+
+## Files Involved
+
+- `/home/dawid/projects/specialists/src/specialist/supervisor.ts` — dual-write ordering bug (lines 261-282), deferred crash recovery (lines 149-177)
+- `/home/dawid/projects/specialists/src/cli/result.ts` — reads only status.json, no fallback to events.jsonl
+- `/home/dawid/projects/specialists/src/cli/feed.ts` — reads only events.jsonl, no fallback to status.json; legacy completion events in isCompletionEvent (line 170-172)
+- `/home/dawid/projects/specialists/src/specialist/timeline-events.ts` — defines completion event types including legacy done/agent_end
+- `/home/dawid/projects/specialists/src/specialist/timeline-query.ts` — job reading utilities
+
+---
+
+## Recommended Fixes
+
+1. **Reverse the write order** in `Supervisor.run()`: write `events.jsonl:run_complete` first, then `status.json:done`. This ensures that if you see `done` in status.json, the timeline is already complete. The current order is backwards relative to what guarantees consistency for the reported symptom.
+
+2. **Add a fallback in `result.ts`**: If `status.json` says `running` but `events.jsonl` contains a `run_complete` event, treat the job as done and attempt to read `result.txt`. This handles the crash-recovery gap.
+
+3. **Make crash recovery proactive**: Call `crashRecovery()` in `readStatus()` or `Supervisor.constructor()`, not only on `run()`. A stale "running" status should be auto-corrected at read time, not only when a new job starts.
+
+4. **Reconcile on read in `readStatus()`**: Before returning a `running`/`starting` status, check if `events.jsonl` has a `run_complete` event. If it does, auto-correct `status.json` to `done` before returning.
+
+---
+
+## What Was NOT a Bug
+
+- The atomic write of `status.json` via temp-file + rename (`writeStatusFile`) correctly prevents partial/corrupt JSON.
+- The single-threaded Node.js execution model prevents the read-modify-write race within a single process.
+- The `events.jsonl` append-only writes are safe; the only issue is the ordering relationship with `status.json` updates.

package/config/skills/specialists-usage-workspace/iteration-2/eval-bug-investigation/without_skill/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 69075,
+  "duration_ms": 132071,
+  "total_duration_seconds": 132.1
+}

package/config/skills/specialists-usage-workspace/iteration-2/eval-code-review/with_skill/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 371,
+  "duration_ms": 790094,
+  "total_duration_seconds": 790.1
+}