Downcity
ServicesTask Service

Run Artifacts and Debugging

run directory semantics, status interpretation, and practical troubleshooting steps

Run Artifacts and Debugging

Every task execution creates a run directory:

.downcity/task/<taskId>/<timestamp>/

Core artifacts

FilePurpose
input.mddefinition snapshot for this run
output.mdoutput body (agent: final task output text; script: script output)
result.mdhuman-readable summary
run.jsonfinal status payload
run-progress.jsonlive progress snapshot
dialogue.mdmulti-round summary (agent)
dialogue.jsonstructured round records (agent, including query / output / raw assistantMessage snapshots / feedback)
messages.jsonlexecution context message stream (including executor query / assistant reply)
user-simulator/messages.jsonluser-simulator context message stream (only when review=true, including simulator query / assistant reply)
error.mdfailure summary

run.json key fields

  • executionId
  • status
  • executionStatus
  • resultStatus
  • resultErrors
  • dialogueRounds
  • startedAt / endedAt

Common patterns

  • resultStatus=invalid

    • usually output too short
    • for review=true agent tasks, inspect dialogue.md / dialogue.json first for each round's:
      • executor query
      • executor output
      • user simulator query
      • user simulator output
      • raw assistantMessage snapshot
      • feedbackForNextRound
  • executionStatus=failure

    • usually script execution failure, agent process failure, failed chat_send delivery, or an agent run that only performed tool calls without producing any user-visible output
    • for ACP agents such as Claude ACP, task now normalizes known startup / hook / transport internal errors into a stable failure message first; if the same task keeps failing, inspect agent-server logs and hook configuration
  • Task skipped (already running)

    • overlap trigger skipped by per-task serial guard
  • one-shot when=time:... no longer auto-runs

    • expected behavior after execution: paused + @manual