Logging

An executing workflow records visited nodes and ports in one output directory, together with visit artifacts and failure tracebacks. In VS Code, use Verdog: Open Run Output to inspect a run's files. Preparation errors, such as invalid workflow input, can occur before a directory is allocated.

Run directory

Runs started from VS Code create a distinct directory below .verdog/runs/<workflow>/, where <workflow> is the selected local workflow ID:

.verdog/runs/main/20260901T102030Z-a1b2c3d4/

The directory name contains the UTC start time and a random suffix. When using the runtime API, pass an absent or empty path as output_dir:

from pathlib import Path

result = dispatcher.run(
    definition,
    input,
    output_dir=Path("artifacts/countdown"),
)

Verdog rejects a path that denotes a file or a non-empty directory. See the programmatic API to enable checkpointing.

Sensitive output

Run output may contain prompts, responses, authored diagnostics, and stack traces. Exclude .verdog/ and any custom output paths from version control, and review artifacts before sharing them.

Visit directories

The runtime creates a numbered directory for every node or control port reached. The root graph writes directly beneath the run directory:

<run>/
├── trace.log
├── enter/000001/
├── <node-id>/
│   ├── 000001/
│   └── 000002/
└── exit/000001/

Visit numbers are padded to six digits and advance independently for each node within its containing output directory. The first visit starts at 000001 when no previous output exists. Repeated visits, including retries after interruption, receive unused numbers and preserve earlier output.

Graph activation directories

A called graph writes its nodes directly beneath the call node's visit directory. Both Subroutine calls and Workflow calls use the same layout:

<run>/call_child/000001/
├── enter/000001/
├── <node-id>/000001/
├── call_grandchild/000001/
│   ├── enter/000001/
│   ├── <grandchild-node>/000001/
│   └── exit/000001/
└── exit/000001/

If an interrupted call must start its child again, it reuses the call's output scope. Each child node advances past its existing visit directories before writing output. For example, a repeated child entry gets enter/000002/:

<run>/call_child/000001/
└── enter/
    ├── 000001/
    └── 000002/

Resuming a child continues its recorded output directory and workflow state. Once the child's result is recorded, replay evaluates only the call adapter. Revisiting the call node in a later loop iteration creates a new numbered call visit, where child counters start at 000001 again. Child visits are recorded in the same run-level trace.log.

The generated config.md and statistics tables describe the latest execution within each scope. Numbered node outputs and trace events retain its history; previous versions of these summary reports are not archived separately.

The parent config.md and stats.md link to child reports. Paths grow with nesting depth and remain subject to operating-system path limits. Verdog preserves existing artifact paths during resume; see Run files for checkpoint compatibility and file rules.

Writing visit output

Every authored visit receives context.output_dir, an existing absolute pathlib.Path dedicated to that visit. Ordinary Python, Agent, and Feature visits may write logs and other artifacts beneath it:

(context.output_dir / "decision.txt").write_text(
    "accepted\n",
    encoding="utf-8",
)

The runtime does not change the process working directory around a visit, so a relative path does not implicitly resolve below context.output_dir. A Feature visit that initializes state receives the same output-directory access as any other visit.

A synchronous call adapter may be evaluated more than once while Verdog runs or resumes its journaled child invocation. It must therefore not write to output_dir or perform any other unjournaled side effect. Put that work in an ordinary node or in the child graph; their output directories remain durable and completed child work is not repeated by adapter replay.

Checkpointed files are durable outputs: after publication, do not edit or delete them. Later visits write their own numbered outputs. Checkpoints record references to those files rather than copies, while resume leaves files from uncommitted attempts in place.

An Agent node's workspace is a separate choice; Verdog does not select or automatically delete it. For a disposable workspace, use context.output_dir / ".verdog" / "workspace". Rebuild it from durable inputs before every invocation, including repairs and replay, then remove it in finally. Publish any resulting candidates or evidence needed later outside .verdog before returning. All .verdog directories are private and excluded from checkpoint artifact inventories, so their contents must not be carried as durable inputs to subsequent visits.

Runtime-generated files

Path	Contents
trace.log	Timestamped START and END events with run-relative visit paths. END includes status and duration; START alone does not imply successful completion. Older runs retain their trace filename.
<agent-visit>/invocations/000001/	One directory per agent invocation after request validation, numbered within its visit.
<invocation>/prompt.txt	The prompt passed to the agent.
<invocation>/response.txt	The successful text response.
<invocation>/metadata.json	Built-in provider, model, workspace, access mode, session, timing, and status metadata.
<invocation>/events.jsonl	Standard output from the built-in provider process.
<invocation>/stderr.txt	Standard error from the built-in provider process.
<invocation>/reasoning.txt	Reasoning text, when returned and extracted by the built-in invoker.
<failure-visit>/stacktrace.txt	The formatted Python traceback written when an exception reaches a graph's failure boundary.