Skip to content
APEX

Session State Debugging

Diagnose and recover from session resume failures, stale locks, and corrupted state.

Session State Overview

Section titled “Session State Overview”

Every workflow run maintains its progress in agent-output/{project}/00-session-state.json. This file tracks:

  • Which steps are complete, in progress, or pending
  • Sub-step checkpoints within each step
  • Decisions made during the workflow

The schema version is declared in the schema_version field. New state files should use schema_version: "3.0" (the v2.0 lock/claim protocol was removed since VS Code Copilot executes agents serially). The authoritative schema definition is in tools/schemas/session-state.schema.json (managed by apex-recall CLI).

A human-readable companion file 00-handoff.md summarises the same state for manual inspection.

Diagnostic Flowchart

Section titled “Diagnostic Flowchart”

Use this decision tree when session resume is not working:

flowchart TD
    A["Session resume not working?"] --> B{"Does 00-session-state.json exist?"}
    B -- No --> C["Fresh start — file will be created automatically"]
    B -- Yes --> D{"Is the file valid JSON?"}
    D -- No --> E["Corrupted state — see Manual Recovery below"]
    D -- Yes --> J{"Check steps.N.status"}
    J --> K["pending → normal start"]
    J --> L["in_progress → resume from sub_step checkpoint"]
    J --> M["complete → step already done, move to next"]

Common Problems

Section titled “Common Problems”

Corrupted State File

Section titled “Corrupted State File”

Symptoms: JSON parse errors, missing required fields, validator failures.

Fix:

  1. Run the validator to identify the issue:

    Terminal window
    npm run validate:session-state

  2. If the file is unrecoverable, check for a backup:

    Terminal window
    ls agent-output/{project}/00-session-state.json.bak

    If a .bak file exists, restore it:

    Terminal window
    cp agent-output/{project}/00-session-state.json.bak agent-output/{project}/00-session-state.json

  3. If no backup exists, rename the corrupt file and restart:

    Terminal window
    cd agent-output/{project}
    mv 00-session-state.json 00-session-state.json.corrupt

    The Orchestrator creates a fresh v3.0 state file on the next run. All steps reset to pending.

Missing Steps

Section titled “Missing Steps”

Symptoms: Orchestrator skips a step or reports it as already complete when it was never run.

Fix:

  1. Inspect the step status:

    Terminal window
    jq '.steps' agent-output/{project}/00-session-state.json

  2. Reset the step to pending:

    Terminal window
    jq '.steps."4".status = "pending" | .steps."4".sub_step = null' \
      agent-output/{project}/00-session-state.json > tmp.json
    mv tmp.json agent-output/{project}/00-session-state.json

Schema Version Mismatch

Section titled “Schema Version Mismatch”

Symptoms: Validator warns about unknown fields or deprecated lock/claim structure.

The v3.0 schema removed the lock and claim fields (previously in v2.0). If you encounter a v1.0 or v2.0 state file, the Orchestrator will attempt to migrate it automatically. If it fails, create a fresh state file.

Decision Logging

Section titled “Decision Logging”

The decisions object in the session state tracks key choices made during the workflow:

{
  "decisions": {
    "iac_tool": "bicep",
    "primary_region": "swedencentral",
    "complexity": "standard"
  }
}

Write decisions at the moment they are made (Step 1 for iac_tool, Step 2 for architecture choices). The Orchestrator and downstream agents read these to route workflow steps correctly.

The decision_log array provides an append-only audit trail:

{
  "decision_log": [
    {
      "step": 1,
      "key": "iac_tool",
      "value": "bicep",
      "reason": "Team preference and existing Bicep expertise"
    }
  ]
}

Context Budget Strategy

Section titled “Context Budget Strategy”

Each step has a file load budget — a hard limit on how many files the agent loads at startup. This prevents context window exhaustion:

StepBudgetFiles Loaded
1 (Requirements)1-2 filesSession state only
2 (Architecture)2-3 filesRequirements + session state
4 (Plan)2-3 filesArchitecture + governance constraints
5 (Code)1-2 filesImplementation plan

Excess files are loaded on demand via progressive disclosure. If resume is slow, check whether context_files_used in the session state lists more files than the step’s budget allows.

Validators

Section titled “Validators”

Two validators check session state integrity:

Terminal window
# Validate JSON schema compliance
npm run validate:session-state


# Validate for deprecated lock/claim fields
npm run validate:session-state

Run these after manual edits to the state file to ensure consistency.

Section titled “Related”