@jaggerxtrm/specialists 3.3.4 → 3.4.0

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

@@ -1,150 +0,0 @@
-# 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

@@ -1,180 +0,0 @@
-# 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

@@ -1,5 +0,0 @@
-{
-  "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

@@ -1,223 +0,0 @@
-# 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

@@ -1,5 +0,0 @@
-{
-  "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

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