easy-coding-harness 0.1.7 → 0.1.8

package/templates/codex/agents/ec-fixer.toml

@@ -0,0 +1,25 @@
+[agent]
+name = "ec-fixer"
+model = "sonnet"
+description = "Easy Coding fix sub-agent. Applies targeted fixes to specific issues identified during review."
+sandbox = "workspace-write"
+
+[agent.instructions]
+text = """
+You are an Easy Coding fix sub-agent. You receive a fix card listing specific issues
+(with file:line locations) and apply the fixes. Your reply content IS the return value.
+
+Hard constraints:
+- Fix ONLY the issues listed in the fix card. No refactoring.
+- Modify ONLY the files listed in the fix card's scope.
+- Do not call any Skill tool.
+- Do not read .agents/skills/ or any .easy-coding/ file.
+- Make no workflow stage-transition decisions.
+- Preserve file encoding.
+
+Output structure (return as JSON):
+- changed_files: files you modified
+- fixes_applied: [{file, line, original_issue, fix_description}]
+- issues: problems preventing a fix (empty if none)
+- needs_attention: design decisions needing user escalation (empty if none)
+"""

package/templates/common/skills/ec-implementing/SKILL.md

@@ -31,13 +31,28 @@ Communicate with the user in the user's language.
 7. **Tests (soft rule).** Write tests for [must-test]/[should-test] items per
    test-strategy.md. Soft means: no project test infra → not forced; infra exists → required.
 
-## Sub-agent dispatch (mandatory when strategy = parallel)
+## Sub-agent dispatch
 
-Read the `plan` record. Then:
+Read the `plan` record's `strategy` field. Then:
 
 - `single` → main agent implements directly, no sub-agents.
 - `sequential` → main agent implements units one by one in dependency order.
-- `parallel` → you MUST use sub-agents, one per unit, batched by `parallel_groups` level.
+- `parallel` → sub-agents are MANDATORY (see gate below).
+
+<HARD-GATE>
+PARALLEL STRATEGY = MANDATORY SUB-AGENT DISPATCH. NO EXCEPTIONS.
+
+If the plan record says `"strategy":"parallel"`, you MUST dispatch sub-agents using
+{{sub_agent_dispatch}}. You are FORBIDDEN from implementing parallel units yourself.
+Doing the work inline instead of dispatching is a protocol violation equivalent to
+skipping WAITING_CONFIRM.
+
+Self-check before writing ANY implementation code:
+- Is strategy "parallel"? → Did I dispatch via {{sub_agent_dispatch}}? If no → STOP.
+- Am I working on a unit in a parallel level without dispatching? → STOP.
+
+The ONLY case where you implement code directly is strategy "single" or "sequential".
+</HARD-GATE>
 
 Parallel dispatch loop:
 1. Sort `parallel_groups` by level.
@@ -87,3 +102,11 @@ let sub-agents re-dispatch each other.
 
 All units done and self-audited → hand back to ec-workflow to advance to REVIEW. If you
 hit something that invalidates the plan, return to ANALYSIS instead of improvising.
+
+## Self-check gates (before handing back)
+
+- [ ] Strategy was "parallel" → ALL units dispatched via sub-agents? (VIOLATION if no)
+- [ ] Strategy was "sequential" → units implemented in dependency order?
+- [ ] Each dispatched unit has a `dispatch` record in execution.jsonl?
+- [ ] Each returned unit has a `result` record?
+- [ ] No files modified outside the change-scope table?

package/templates/common/skills/ec-memory/SKILL.md

@@ -32,27 +32,47 @@ result/verify records, not from a fuzzy memory of the conversation.}
 
 If the task was cross-repo, record the repo names involved and the collaboration reason.
 
-**Sliding window:** keep at most 10 short memories. When the count exceeds 10, keep the
-latest 5; the rest become long-term distillation candidates (do not delete them here — the
-MEMORY_LONG retirement check decides their fate).
+**Sliding window (informational):** The short memory directory has a soft cap defined by
+`memory.short_term_max` (default 10). MEMORY_SHORT only WRITES one entry per completed task
+— it never counts, trims, or triggers distillation. Trimming is exclusively MEMORY_LONG's
+responsibility and only runs when the threshold is exceeded.
 
-## MEMORY_LONG — distill durable knowledge
+## MEMORY_LONG — distill durable knowledge (CONDITIONAL)
+
+<HARD-GATE>
+MEMORY_LONG IS A NO-OP WHEN SHORT MEMORY COUNT <= threshold.
+
+Before performing ANY distillation work:
+1. Count `.md` files in `.easy-coding/memory/short/` (only files with schema-v2 frontmatter).
+2. Read `memory.short_term_max` from `.easy-coding/config.yaml` (default: 10).
+3. If count <= short_term_max: output "MEMORY_LONG: no-op (short memory count = {N},
+   threshold = {short_term_max})" and immediately hand back to ec-workflow to advance to
+   COMPLETE. Do NOT read long memory files, do NOT attempt distillation, do NOT modify any file.
+4. If count > short_term_max: proceed with distillation below.
+
+This gate is absolute. Even a single short memory entry below threshold does NOT trigger
+long-term compression regardless of any other signal.
+</HARD-GATE>
+
+### When count > threshold: distillation flow
 
 Three-file long memory:
 - `MEMORY.md` — index of all entries with status (active | deprecated | superseded | deleted).
 - `BUSINESS.md` — business rules, domain knowledge, product decisions.
 - `TECHNICAL.md` — architecture decisions, implementation patterns, gotchas.
 
-Distillation flow:
-1. Read the `target_long` of out-of-window short memories; route to business/technical.
-2. **Progressive loading** — read only the existing long entries matching this round's
+Distillation steps:
+1. Read `memory.short_term_keep` from config (default: 5). Keep the latest N entries;
+   the older entries become distillation candidates.
+2. Read the `target_long` of candidate short memories; route to business/technical.
+3. **Progressive loading** — read only the existing long entries matching this round's
    domain/tags/related_files. No unbounded whole-repo memory scan.
-3. **Conflict resolution** by priority: current code > latest user confirmation > this
+4. **Conflict resolution** by priority: current code > latest user confirmation > this
    round's candidate > older long memory. On conflict, explain it before consolidating —
    never silently pick a side.
-4. **Retirement check** (triggered when short memories >= 10): for older entries decide
-   delete (no value) / merge (semantic duplicate) / deprecate (was valid, now superseded).
-5. Update the `MEMORY.md` index to reflect every change.
+5. **Retirement check**: for older entries decide delete (no value) / merge (semantic
+   duplicate) / deprecate (was valid, now superseded).
+6. Update the `MEMORY.md` index to reflect every change.
 
 ## ABSTRACT backfill / update
 

package/templates/common/skills/ec-reviewing/SKILL.md

@@ -31,28 +31,57 @@ result. No finding without a location.
 ## Verdict (exactly one)
 
 - `accept` — all dimensions pass. Advance to VERIFICATION.
-- `fix` — problems found, fixable within the current plan. Emit a numbered fix list, return
-  to IMPLEMENT against that list.
+- `fix` — problems found, fixable within the current plan. Auto-fix via sub-agents (see below).
 - `replan` — the plan itself is flawed (wrong approach, missing design). Return to ANALYSIS.
 - `blocked` — external blocker (missing dependency, environment). Pause and report.
 
+## Auto-fix flow (on `fix` verdict)
+
+<HARD-GATE>
+Bug-level issues (correctness errors, compliance violations, missing edge-case handling)
+are fixed DIRECTLY by dispatching fix sub-agents. Do NOT ask the user for permission to
+fix bugs. The user confirmed the plan — bugs in that plan's execution are implementation
+defects, not design decisions.
+
+ONLY escalate to the user when:
+- The fix requires a DESIGN CHOICE (two equally valid approaches, ambiguous requirement)
+- The fix would change the public API contract beyond what the dev-spec specifies
+- The finding contradicts something the user explicitly stated during WAITING_CONFIRM
+</HARD-GATE>
+
+Fix dispatch flow:
+1. Collect all `fix`-worthy findings from review sub-agents.
+2. Group findings by file. For each group, build a fix task card:
+   - Files to fix (from the findings)
+   - The specific issues with file:line citations
+   - The suggested fix direction from the reviewer
+   - Relevant RULES sections
+3. Dispatch fix sub-agents (ec-fixer, one per file group) via {{sub_agent_dispatch}}.
+   Platform spawn rule: {{platform_spawn_instruction}}
+4. On return: merge results, append `result` records to execution.jsonl.
+5. Re-enter REVIEW (counts toward the fix-loop ceiling of 3).
+
 ## Fix-loop ceiling
 
-A `fix` verdict carries a concrete checklist; IMPLEMENT addresses it and re-enters REVIEW.
 Maximum 3 fix rounds. A 4th would mean the approach is wrong → auto-escalate to `replan`.
 
-## Sub-agent dispatch (conditional)
+## Sub-agent dispatch (ALWAYS)
+
+<HARD-GATE>
+REVIEW ALWAYS USES SUB-AGENTS regardless of the number of changed files. This prevents
+context pollution in the main agent's window. You MUST NOT review code inline — dispatch
+sub-agents for every review.
+</HARD-GATE>
 
-Count distinct `changed_files` across all `result` records. If >= 5, run multi-dimension
-review in parallel sub-agents:
+Dispatch two parallel review sub-agents:
 - R1: correctness — does the implementation match the dev-spec requirement?
 - R2: compliance — does the code obey RULES?
 
-Each sub-agent returns `{dimension, findings[], severity, suggestion}`. The MAIN agent merges
-and dedups findings and decides the verdict — sub-agents cannot trigger stage transitions.
-Platform spawn rule: {{platform_spawn_instruction}}
+Each sub-agent returns `{dimension, findings[], severity, suggestion}`. The MAIN agent
+merges and dedups findings and decides the verdict — sub-agents cannot trigger stage
+transitions.
 
-If < 5 changed files, the main agent reviews directly.
+Platform spawn rule: {{platform_spawn_instruction}}
 
 ## Output
 

package/templates/common/skills/ec-verification/SKILL.md

@@ -24,15 +24,20 @@ NO AUTO-ARCHIVE WITHOUT USER ACCEPTANCE
 - An unaccepted task's memory is dirty data.
 ```
 
-## 1. Run the gate (parallel)
+## 1. Run the gate (parallel, always sub-agents)
 
-Start these three concurrently — do not serialize:
-1. lint (eslint/biome/project linter)
-2. typecheck (`tsc --noEmit` or equivalent)
-3. test (project test command)
+<HARD-GATE>
+VERIFICATION ALWAYS USES SUB-AGENTS for each check. This prevents context pollution and
+ensures true parallelism. You MUST NOT run lint/typecheck/test inline in the main agent.
+</HARD-GATE>
 
-Use sub-agents or background commands; a verification sub-agent just runs a command and
-reports. Platform spawn rule: {{platform_spawn_instruction}}
+Dispatch three sub-agents concurrently (one per check):
+1. V1: lint (eslint/biome/project linter)
+2. V2: typecheck (`tsc --noEmit` or equivalent)
+3. V3: test (project test command)
+
+Each sub-agent runs its command and returns `{check, passed, failures[]}`.
+Platform spawn rule: {{platform_spawn_instruction}}
 
 Append one `verify` record per check:
 `{"type":"verify","check":"test","passed":true}` (add `"failures":[...]` on failure).

package/templates/common/skills/ec-workflow/SKILL.md

@@ -23,7 +23,8 @@ replies are English.
    - `.easy-coding/RULES.md` — coding rules; re-checked before every write.
    - Latest 5 entries in `.easy-coding/memory/short/` — recent task context.
    Do NOT bulk-read ABSTRACT.md or long memory here; ec-analysis loads them on demand.
-3. **State check + Intent routing.** Read `{{workflow_state_path}}`, then decide based on
+3. **State check + Intent routing.** Read the hook-injected breadcrumbs (`[current-task:X]`,
+   `[workflow-state:Y]`) to determine the active task and stage, then decide based on
    whether the user's message carries a task-related prompt beyond the bare skill trigger.
 
    **No prompt (bare trigger):**
@@ -86,11 +87,9 @@ any stage --[user abort via ec-task-close]--> CLOSED
 
 When the user confirms switching from task A to task B:
 1. Task A's status is already persisted in its `task.json` — nothing extra to save.
-2. Set `current_task` to task B's id in state.json.
-3. Set `current_stage` to task B's `status` (from task B's `task.json`).
-4. Append a `{stage, agent, entered_at}` entry to `stage_history`.
-5. Set `last_agent` to the current agent id.
-6. Resume task B's stage via the appropriate stage skill.
+2. Set `current_task` to task B's id in the session file (`.easy-coding/sessions/{ppid}.json`).
+3. Read task B's `task.json` to determine its current stage.
+4. Resume task B's stage via the appropriate stage skill.
 
 No data is lost — task A's dev-spec, execution.jsonl, and test-strategy.md stay intact on
 disk. To return to task A later, the same intent routing applies: the user mentions it,
@@ -105,9 +104,13 @@ routing matches, and switching happens again.
   analysis conclusion and the test strategy. Silence, enthusiasm, or a topic change is not
   confirmation. Sole exception: `behavior.auto_mode: true` in `.easy-coding/config.yaml`
   AND the user asked for autonomous execution.
-- **On every transition** update `{{workflow_state_path}}` immediately (not at turn end):
-  set `current_stage`, append `{stage, agent, entered_at}` to `stage_history`, set
+- **On every transition** update the active task's `task.json` immediately (not at turn end):
+  set `status` to the new stage, append `{stage, agent, entered_at}` to `stage_history`, set
   `last_agent` to the current agent id (`claude-code` / `codex` / `qoder`).
+- **Hook enforcement.** The `inject-workflow-state` hook validates every stage transition
+  against the state machine. If you see `[ILLEGAL-TRANSITION:...]` in the injected context,
+  you MUST revert the task's status to the previous valid stage and explain why the
+  transition was rejected. Do not proceed with an illegal stage.
 - **Repair loop sizing** (user acceptance window after VERIFICATION): a trivial tweak
   (one-line style fix, copy text) is fixed inside VERIFICATION and re-verified; a logic or
   structure change formally returns to IMPLEMENT and re-walks REVIEW → VERIFICATION.
@@ -118,8 +121,8 @@ routing matches, and switching happens again.
   task.json. Do not run memory flows for suspended tasks — only completed tasks get archived.
 - **Archive only after user acceptance.** VERIFICATION passing does not complete the task.
   After the user accepts, MEMORY_SHORT → MEMORY_LONG → COMPLETE run automatically.
-- **COMPLETE closeout:** set task.json `status:"COMPLETE"`, clear `current_task` in
-  state.json, output a summary (what was done, files changed, key decisions).
+- **COMPLETE closeout:** set task.json `status:"COMPLETE"`, clear `current_task` in the
+  session file, output a summary (what was done, files changed, key decisions).
 
 ## Resume and handoff
 
@@ -143,7 +146,7 @@ Offering handoff — at WAITING_CONFIRM, after presenting the plan, offer exactl
 3. Revise the plan
 On option 2: append a `handoff` record to `execution.jsonl` —
 `{"type":"handoff","from":"<agent>","stage":"<stage>","summary":"<dense context: plan shape, key decisions, user emphases>","timestamp":"<ISO>"}` —
-update state.json, then tell the user to open the target agent and run ec-workflow there.
+update the task's `last_agent` in task.json, then tell the user to open the target agent and run ec-workflow there.
 Handoff is also legal at any other stage boundary on user request. The harness never
 switches agents by itself.
 

package/templates/qoder/agents/ec-fixer.md

@@ -0,0 +1,36 @@
+---
+name: ec-fixer
+model: sonnet
+description: Easy Coding fix sub-agent. Applies targeted fixes to specific issues identified during review. Returns structured results with changed files.
+---
+
+You are an Easy Coding fix sub-agent. You receive a fix card listing specific issues
+(with file:line locations) and apply the fixes. Your reply content IS the return value,
+not a message to a human.
+
+## Hard constraints
+
+- Fix ONLY the issues listed in the fix card. Do not refactor or "improve" surrounding code.
+- Modify ONLY the files listed in the fix card's scope.
+- Do not call any Skill tool.
+- Do not read `.qoder/skills/`, `.agents/skills/`, or any `.easy-coding/` file.
+- Make no workflow stage-transition decisions.
+- Preserve file encoding.
+
+## Output (return exactly this structure)
+
+```json
+{
+  "changed_files": ["file1.ts", "file2.ts"],
+  "fixes_applied": [
+    {"file": "file1.ts", "line": 42, "original_issue": "...", "fix_description": "..."}
+  ],
+  "issues": [],
+  "needs_attention": []
+}
+```
+
+- `changed_files`: files you actually modified
+- `fixes_applied`: what you fixed with file:line reference
+- `issues`: problems you hit that prevented a fix (empty if none)
+- `needs_attention`: anything requiring a design decision that should escalate to the user

package/templates/shared-hooks/easy_coding_status.py

@@ -1,4 +1,5 @@
 import json
+import os
 from pathlib import Path
 
 
@@ -8,6 +9,20 @@ READY_LINE = (
 )
 WAITING_INIT_LINE = "> **Easy Coding** · Waiting init · Use `ec-init` to initialize"
 
+VALID_TRANSITIONS: dict[str, set[str]] = {
+    "idle": {"INIT"},
+    "INIT": {"ANALYSIS", "CLOSED"},
+    "ANALYSIS": {"WAITING_CONFIRM", "CLOSED"},
+    "WAITING_CONFIRM": {"IMPLEMENT", "ANALYSIS", "CLOSED"},
+    "IMPLEMENT": {"REVIEW", "ANALYSIS", "CLOSED"},
+    "REVIEW": {"VERIFICATION", "IMPLEMENT", "ANALYSIS", "CLOSED"},
+    "VERIFICATION": {"MEMORY_SHORT", "IMPLEMENT", "CLOSED"},
+    "MEMORY_SHORT": {"MEMORY_LONG", "CLOSED"},
+    "MEMORY_LONG": {"COMPLETE", "CLOSED"},
+    "COMPLETE": set(),
+    "CLOSED": set(),
+}
+
 
 def load_json(path: Path) -> dict | None:
     if not path.exists():
@@ -24,26 +39,42 @@ def load_task(root: Path, task_id: str | None) -> dict | None:
     return load_json(root / ".easy-coding" / "tasks" / task_id / "task.json")
 
 
+def load_session(root: Path) -> dict | None:
+    ppid = os.getppid()
+    return load_json(root / ".easy-coding" / "sessions" / f"{ppid}.json")
+
+
+def write_session(root: Path, session: dict) -> None:
+    ppid = os.getppid()
+    session_path = root / ".easy-coding" / "sessions" / f"{ppid}.json"
+    session_path.parent.mkdir(parents=True, exist_ok=True)
+    session_path.write_text(json.dumps(session, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
 def is_project_init_required(root: Path) -> bool:
     project_init = load_json(root / ".easy-coding" / "tasks" / "project-init" / "task.json")
     return bool(project_init and project_init.get("status") != "COMPLETE")
 
 
-def resolve_task_status(root: Path, state: dict, task_id: str | None) -> str:
-    task = load_task(root, task_id)
-    if task and task.get("status"):
-        return str(task["status"])
-    return str(state.get("current_stage") or "idle")
+def validate_transition(previous: str, current: str) -> str | None:
+    if previous == current:
+        return None
+    allowed = VALID_TRANSITIONS.get(previous, set())
+    if current in allowed:
+        return None
+    return f"ILLEGAL TRANSITION: {previous} -> {current}. Allowed from {previous}: {sorted(allowed) or 'NONE (terminal state)'}."
 
 
-def build_status_line(root: Path, state: dict, agent: str | None = None) -> str:
-    task_id = state.get("current_task")
+def build_status_line(root: Path, session: dict, agent: str | None = None) -> str:
+    task_id = session.get("current_task")
     if task_id:
-        status = resolve_task_status(root, state, str(task_id))
+        task = load_task(root, str(task_id))
+        status = str(task["status"]) if task and task.get("status") else "PENDING"
         line = f"> **Easy Coding** · `{task_id}` · `{status}`"
-        last_agent = state.get("last_agent")
-        if agent and last_agent and last_agent != agent:
-            line += f" · Handoff -> `{last_agent}`"
+        if task:
+            last_agent = task.get("last_agent")
+            if agent and last_agent and last_agent != agent:
+                line += f" · Handoff -> `{last_agent}`"
         return line
 
     if is_project_init_required(root):
@@ -52,22 +83,39 @@ def build_status_line(root: Path, state: dict, agent: str | None = None) -> str:
     return READY_LINE
 
 
-def build_machine_breadcrumbs(root: Path, state: dict, agent: str | None = None) -> list[str]:
-    stage = state.get("current_stage") or "idle"
-    task_id = state.get("current_task")
+def build_machine_breadcrumbs(root: Path, session: dict, agent: str | None = None) -> list[str]:
+    task_id = session.get("current_task")
+    task = load_task(root, str(task_id)) if task_id else None
+    stage = str(task["status"]) if task and task.get("status") else "idle"
     lines = [f"[workflow-state:{stage}]"]
 
     if task_id:
         lines.append(f"[current-task:{task_id}]")
-        last_agent = state.get("last_agent")
-        if agent and last_agent and last_agent != agent:
-            lines.append(f"[easy-coding:handoff-from:{last_agent}]")
+        if task:
+            last_agent = task.get("last_agent")
+            if agent and last_agent and last_agent != agent:
+                lines.append(f"[easy-coding:handoff-from:{last_agent}]")
 
     if is_project_init_required(root):
         lines.append("[easy-coding:init-required]")
 
+    # State machine validation
+    last_seen = session.get("last_seen_stage")
+    if last_seen and task and task.get("status"):
+        current_stage = str(task["status"])
+        violation = validate_transition(last_seen, current_stage)
+        if violation:
+            lines.append(f"[ILLEGAL-TRANSITION:{last_seen}->{current_stage}]")
+            lines.append(f"[easy-coding:transition-error:{violation}]")
+        if last_seen != current_stage:
+            session["last_seen_stage"] = current_stage
+            write_session(root, session)
+    elif task and task.get("status"):
+        session["last_seen_stage"] = str(task["status"])
+        write_session(root, session)
+
     return lines
 
 
-def build_status_context(root: Path, state: dict, agent: str | None = None) -> str:
-    return "\n".join([build_status_line(root, state, agent), *build_machine_breadcrumbs(root, state, agent)])
+def build_status_context(root: Path, session: dict, agent: str | None = None) -> str:
+    return "\n".join([build_status_line(root, session, agent), *build_machine_breadcrumbs(root, session, agent)])

package/templates/shared-hooks/inject-subagent-context.py

@@ -61,8 +61,8 @@ def main() -> int:
     if root is None:
         return 0
 
-    state = load_json(root / ".easy-coding" / "state.json") or {}
-    task_id = state.get("current_task")
+    session = load_json(root / ".easy-coding" / "sessions" / f"{os.getppid()}.json") or {}
+    task_id = session.get("current_task")
     context = [
         "[easy-coding:subagent-guard]",
         "Sub-agents must follow the task card, stay within the allowed file scope, and return structured results.",

package/templates/shared-hooks/inject-workflow-state.py

@@ -4,7 +4,7 @@ import os
 from pathlib import Path
 import sys
 
-from easy_coding_status import build_status_context
+from easy_coding_status import build_status_context, load_session
 
 
 def configure_stdio() -> None:
@@ -30,16 +30,6 @@ def find_ec_root(start: Path) -> Path | None:
         current = current.parent
 
 
-def load_state(root: Path) -> dict | None:
-    state_path = root / ".easy-coding" / "state.json"
-    if not state_path.exists():
-        return {"current_stage": "idle", "current_task": None}
-    try:
-        return json.loads(state_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-
-
 def detect_agent() -> str:
     if os.environ.get("CLAUDE_PROJECT_DIR"):
         return "claude-code"
@@ -79,12 +69,12 @@ def main() -> int:
     if root is None:
         return 0
 
-    state = load_state(root)
-    if state is None:
-        return 0
+    session = load_session(root)
+    if session is None:
+        session = {"current_task": None, "created_at": ""}
 
     event_name = payload.get("hook_event_name") or payload.get("hookEventName") or "UserPromptSubmit"
-    emit(event_name, build_status_context(root, state, detect_agent()))
+    emit(event_name, build_status_context(root, session, detect_agent()))
     return 0
 
 

package/templates/shared-hooks/session-start.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 import json
 import os
+from datetime import datetime, timezone
 from pathlib import Path
 import sys
 
-from easy_coding_status import build_status_context
+from easy_coding_status import build_status_context, load_session, write_session
 
 
 def configure_stdio() -> None:
@@ -59,16 +60,72 @@ def detect_agent() -> str:
     return "unknown"
 
 
-def default_state(agent: str) -> dict:
-    return {
-        "current_stage": "idle",
-        "current_task": None,
-        "last_agent": agent,
-        "stage_history": [],
-        "confirmed_by_user": False,
-        "test_strategy_confirmed": False,
-        "repo_paths": {},
-    }
+def is_process_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def clean_stale_sessions(root: Path) -> None:
+    sessions_dir = root / ".easy-coding" / "sessions"
+    if not sessions_dir.is_dir():
+        return
+
+    now = datetime.now(timezone.utc)
+    threshold_hours = 24
+
+    for entry in sessions_dir.iterdir():
+        if not entry.suffix == ".json":
+            continue
+        try:
+            data = json.loads(entry.read_text(encoding="utf-8"))
+            created = datetime.fromisoformat(data.get("created_at", ""))
+            if created.tzinfo is None:
+                created = created.replace(tzinfo=timezone.utc)
+            age_hours = (now - created).total_seconds() / 3600
+            if age_hours <= threshold_hours:
+                continue
+            pid = int(entry.stem)
+            if is_process_alive(pid):
+                continue
+            entry.unlink()
+        except (OSError, json.JSONDecodeError, ValueError, KeyError):
+            continue
+
+
+def migrate_legacy_state(root: Path, agent: str) -> dict | None:
+    """Migrate old-format state.json into session file + task.json. Returns session dict."""
+    state_path = root / ".easy-coding" / "state.json"
+    old_state = load_json(state_path)
+    if old_state is None:
+        return None
+
+    task_id = old_state.get("current_task")
+    if task_id:
+        task_path = root / ".easy-coding" / "tasks" / str(task_id) / "task.json"
+        task = load_json(task_path)
+        if task:
+            if "stage_history" not in task or not task["stage_history"]:
+                task["stage_history"] = old_state.get("stage_history", [])
+            if "last_agent" not in task or not task["last_agent"]:
+                task["last_agent"] = old_state.get("last_agent", agent)
+            if old_state.get("confirmed_by_user"):
+                task["confirmed_by_user"] = True
+            if old_state.get("test_strategy_confirmed"):
+                task["test_strategy_confirmed"] = True
+            if old_state.get("repo_paths"):
+                task["repo_paths"] = old_state["repo_paths"]
+            write_json(task_path, task)
+
+    # Remove legacy state.json
+    try:
+        state_path.unlink()
+    except OSError:
+        pass
+
+    return {"current_task": task_id, "created_at": datetime.now(timezone.utc).isoformat()}
 
 
 def emit(event_name: str, context: str) -> None:
@@ -97,13 +154,29 @@ def main() -> int:
 
     agent = detect_agent()
     event_name = payload.get("hook_event_name") or payload.get("hookEventName") or "SessionStart"
-    state_path = root / ".easy-coding" / "state.json"
-    state = load_json(state_path)
-    if state is None:
-        state = default_state(agent)
-        write_json(state_path, state)
 
-    emit(event_name, build_status_context(root, state, agent))
+    # Migrate legacy state.json if present
+    state_path = root / ".easy-coding" / "state.json"
+    migrated_session = None
+    if state_path.exists():
+        migrated_session = migrate_legacy_state(root, agent)
+
+    # Clean stale session files
+    clean_stale_sessions(root)
+
+    # Create/overwrite session file for this session
+    session = load_session(root)
+    if session is None:
+        if migrated_session:
+            session = migrated_session
+        else:
+            session = {"current_task": None, "created_at": datetime.now(timezone.utc).isoformat()}
+    else:
+        # Refresh created_at on session start (marks session as active)
+        session["created_at"] = datetime.now(timezone.utc).isoformat()
+
+    write_session(root, session)
+    emit(event_name, build_status_context(root, session, agent))
     return 0