Cache & Daemon Lifecycle

LATdx keeps a long-lived helper process (the “daemon”) and a small set of on-disk caches under ~/.latdx/. This page explains what they do, how they’re scoped, and how to inspect or clean them.

Why the Daemon Exists

Org-mode test runs need a loaded org context: schema, package metadata, and a warm Salesforce connection. Cold-loading that takes several seconds. The daemon keeps it in memory and serves repeated latdx test run calls over a local socket, so the second and Nth runs in the same workspace skip the cold path entirely.

The daemon does not auto-shut-down on idle. It runs until you stop it explicitly, kill the process, or reboot.

Per-Workspace Isolation

Every git worktree gets its own daemon and cache namespace. Switching branches via git switch reuses the same workspace; running multiple branches in parallel via git worktree add gives each one a fully isolated daemon, socket, and cache.

The workspace identity is <sanitized-basename>-<8-char-sha256>, derived from the absolute path of the worktree root (or process.cwd() outside a git repo). Symlinks are resolved before hashing, so /tmp/foo and /private/tmp/foo collapse to the same identity.

LATDX_WORKSPACE_ID and LATDX_WORKSPACE_ROOT are set automatically when the daemon spawns; they exist so the child process rebuilds the same identity without re-walking the filesystem. Do not set them manually.

Cache Layout

~/.latdx/
├── config.json              user-global config (release channel)
├── update-check.json        24h-throttled upgrade-check cache
├── runner-access/
│   └── <orgId>.json         per-org permset grant cache (see Auth & Org Targeting)
└── workspaces/
    └── <id>/
        ├── daemon.pid       running daemon PID
        ├── daemon.sock      Unix socket (POSIX)
        ├── daemon.endpoint  sidecar pointing to the actual endpoint when sock path is too long
        ├── daemon.log       daemon stdout/stderr
        ├── cache/           per-workspace data cache (Apex source snapshots, deployed-source hash, etc.)
        └── tmp/             per-workspace temp dir

On Windows the IPC endpoint is a named pipe (\\.\pipe\latdx-daemon-<user-hash>-<workspace-hash>) instead of a Unix socket. On macOS, very long socket paths fall back to $TMPDIR/latdx-<hash>.sock because of the 104-byte sun_path limit; the actual path is recorded in daemon.endpoint.

Pre-upgrade builds wrote to ~/.latdx/cache/ and ~/.latdx/daemon.{sock,pid,log} directly. Those legacy paths are no longer used; clean them up with latdx cache clear --legacy.

Inspecting the Daemon

latdx daemon status                  # current workspace
latdx daemon status --all-workspaces # every workspace on the machine

The status output includes the PID and the IPC endpoint. If the daemon is not running, the status command says so without spawning anything.

tail -f ~/.latdx/workspaces/<id>/daemon.log

The log captures startup, RPC traffic at the configured log level, and crash output. When diagnosing a stuck daemon, run with -vv and watch the log; daemon-side log levels are inherited from the spawning CLI invocation.

Restarting or Stopping the Daemon

latdx daemon stop                    # SIGTERM the current workspace daemon
latdx daemon stop --all-workspaces   # all workspaces
latdx daemon restart                 # stop; next test run respawns

latdx cache clear --daemon does the same as latdx daemon stop for the current workspace, and is convenient when you also want to clear other state in one command.

The daemon will respawn the next time you run latdx test run in org mode. There is no manual latdx daemon start; spawning is implicit.

Cleaning Caches

latdx cache status                       # space + entries for the current workspace
latdx cache status --all-workspaces      # every workspace
 
latdx cache clear                        # workspace data cache only
latdx cache clear --daemon               # kill the workspace daemon (no cache delete)
latdx cache clear --temp                 # only ~/.latdx/workspaces/<id>/tmp + os.tmpdir() artifacts
latdx cache clear --all                  # cache + daemon + temp for current workspace
latdx cache clear --all-workspaces       # cache for every workspace
latdx cache clear --legacy               # remove pre-upgrade ~/.latdx/cache + daemon.* files
latdx cache clear -q                     # suppress per-step output (useful in scripts)

User-global state (config.json, update-check.json) is never touched by latdx cache clear, regardless of flags. Remove it manually if you want a full reset:

rm -rf ~/.latdx                          # nukes everything: config, caches, daemons, runner-access

Temp Files & Logs

Per-run temp directories live under os.tmpdir() (/tmp on Linux/macOS, $TEMP on Windows). They’re named latdx_temp_* or latdx-org-source, and are deleted automatically when the run finishes.

To keep them around for debugging:

Use them when filing a support ticket or inspecting a hard-to-reproduce failure, then unset to avoid filling disk.

LATDX_DEBUG Namespace Patterns

LATDX_DEBUG selectively enables internal trace channels. Output goes to stderr in the standard <namespace> <message> +<delta> format from the debug package.

Useful channels to start with:

• cli:upgrade — version check / install flow.
• daemon:ipc — RPC traffic between CLI and daemon.
• core:cache — per-workspace cache reads/writes.
• core:org — org context loading and schema queries.

Troubleshooting

For symptom-keyed troubleshooting beyond the daemon, see Troubleshooting.