Workflow Run Directories

Each workflow execution creates a run directory under the user's home directory. This directory holds the execution state, workflow file, and communication socket for that run.

Location

~/.drizti/hpcbox/runs/<runId>/

<runId> is a UUID generated at the start of each execution. Run directories are created with 700 permissions so only the owning user can access them.

Contents

File	Written by	Purpose
meta.json	Executor (at start and end)	Run identity, host, PID, start/end times, final status
status.json	Executor (on every step change)	Full snapshot of all step statuses
workflow.hpcbox	GUI (before spawning executor)	Copy of the workflow file used for this run
ipc.sock	Executor (at startup)	Unix domain socket for live GUI updates

meta.json

{
  "runId": "a3f8b2c1-...",
  "workflowId": "f7e6d5c4-...",
  "workflowFile": "/home/user/workflows/openfoam.hpcbox",
  "workflowName": "openfoam",
  "pid": 12345,
  "startedOn": "login01",
  "startedAt": "2026-06-05T14:23:00Z",
  "endedAt": "2026-06-05T16:10:00Z",
  "finalStatus": "success"
}

finalStatus is null while the run is in progress, then set to "success" or "failed" when the executor exits.

status.json

{
  "runId": "a3f8b2c1-...",
  "workflowId": "f7e6d5c4-...",
  "updatedAt": "2026-06-05T14:25:10Z",
  "steps": [
    { "name": "meshing",     "nodeId": "node-1", "status": "completed" },
    { "name": "simulation",  "nodeId": "node-2", "status": "running"   },
    { "name": "postprocess", "nodeId": "node-3", "status": "pending"   }
  ]
}

Step status values: pending, running, completed, failed, unknown.

Cleanup Policy

The GUI is solely responsible for removing run directories. The executor only writes finalStatus and exits — it never deletes files.

Outcome	Action
Completed successfully	GUI auto-deletes the run directory
User cancelled	GUI treats as success and auto-deletes
Failed (non-zero exit)	Directory kept; user sees it in the reconnect dialog
Executor crashed	Directory kept; user sees it in the reconnect dialog

In normal operation the runs/ directory stays empty. Run directories only accumulate when something goes wrong.

Disk Usage

Each run directory is small — meta.json and status.json together are typically a few kilobytes. The workflow.hpcbox copy is proportional to the size of the workflow definition, generally well under 1 MB.

Failed run directories should be cleaned up periodically. Users can do this from the GUI reconnect dialog. There is no automatic retention policy in the current release.

Multi Login-Node Clusters

The startedOn field in meta.json records the short hostname of the login node where the executor was started. When the GUI reconnects from a different login node, it reads this field and warns the user that live socket updates are not available — the Unix socket is only reachable from the node that created it.

Users should reconnect to running workflows from the same login node where they started them to get live status updates.