Add cache path, status, and node-ID clearing commands

[highbyte]

Problem

Wrighty stores installation-local data under its cache root, but there is currently no supported CLI way to discover that path, inspect the files and schemas stored there, or clear the regenerable GitHub Project node-ID cache.

wrighty config show is user-settings-oriented and currently exposes the host label. Cache inspection and maintenance are operational actions, not configuration mutation, and should not be added to wrighty config.

The cache root also contains data with very different safety properties:

• regenerable GitHub Project node and option IDs;
• the stable Wrighty installation identity;
• GitHub resumable-session, workspace, run-outcome, and deferred-dispatch records; and
• backend-neutral provider availability and probe-coordination state.

A generic “clear cache” operation would therefore be misleading and unsafe.

Desired command surface

Add a focused top-level command group:

wrighty cache path [--json]
wrighty cache status [--json]
wrighty cache clear node-ids [--json]

These commands should operate on the installation cache root and should not require a valid repository .wrighty.json, a particular current backend, network access, GitHub access, or a vendor CLI invocation.

Do not add cache clear all.

Backend relevance

The command output and documentation must make the following distinctions explicit.

Store	Relevant backend	Classification	Clearable here
nodes-v1.json	GitHub only	Regenerable Project field, option, repository, and other node IDs	Yes, through cache clear node-ids
identity-v1.json	Both backends	Stable installation identity used to derive Wrighty worker identity	No
sessions-v1.json	GitHub only	Recovery-critical session/workspace, last-run, and deferred-dispatch state	No
provider-availability-v1.json and its lock	Both backends when workers/providers are used	Operational provider circuit and probe-coordination state	No

For Local Markdown, authoritative claims and durable session records live in the tracker-root .runtime-state.json sidecar. That file is not part of the installation cache and must not be inspected, cleared, repaired, or otherwise treated as cache data by these commands. Clearing it would release local claims and lose resumable-session and retry information.

cache clear node-ids remains valid when invoked from a Local Markdown repository or outside a repository because the installation cache is shared. Its output should say that it affects only cached GitHub discovery metadata and has no effect on Local Markdown work items or runtime state.

wrighty cache path

Human output should print the canonical absolute effective cache-root path and whether it came from:

• the platform default; or
• the WRIGHTY_CACHE_DIR override.

JSON output should use a versioned envelope and expose at least the path and source without exposing unrelated environment values.

wrighty cache status

Report an installation-local inventory without mutating, creating, repairing, or remotely validating anything.

For the root and each known store, report as applicable:

• canonical path or file name;
• backend relevance;
• safety classification (regenerable, identity-critical, recovery-critical, or operational-coordination);
• whether the file exists;
• byte size and last-modified timestamp;
• expected and observed schema version;
• schema/structural health;
• record count or safe aggregate counts; and
• whether this command group permits clearing it.

Additional requirements:

• One missing or unhealthy store must not hide the status of the others.
• A present corrupt or unsupported store should be reported as unhealthy with an actionable diagnostic and a non-success overall status, while still returning the complete inventory.
• Missing files are normal and healthy empty state where the corresponding store supports that interpretation.
• Do not print the raw installation UUID, claim tokens, session IDs, workspace paths, deferred-dispatch contents, provider account data, or raw stored JSON.
• Do not create the cache directory merely by inspecting it.
• Human and versioned JSON output must carry the same semantic information.

wrighty cache clear node-ids

Clear only nodes-v1.json.

Required behavior:

• Treat a missing file as an idempotent successful no-op.
• Permit clearing malformed or unsupported node-cache data so the normal discovery path can rebuild it.
• Preserve identity-v1.json, sessions-v1.json, provider availability data, provider locks, temporary files belonging to active writers, and every Local Markdown file byte-for-byte.
• Explain that node IDs are rediscovered lazily and that an active Wrighty process may repopulate the file immediately.
• Require no worker restart; subsequent GitHub discovery should recover through the existing cache-miss path.
• Avoid partial/truncated state and remain correct if another process is reading or repopulating the regenerable cache concurrently.
• Return a structured result indicating whether a file was removed, was already absent, or had already been repopulated by concurrent activity if that can be observed reliably.

The explicit clear node-ids target is sufficient consent for this regenerable data; no generic force option should broaden its scope.

Out of scope

• Clearing or rotating the installation identity.
• Clearing or bulk-resetting GitHub session/recovery records.
• Clearing Local Markdown .runtime-state.json claims or sessions.
• Resetting provider capacity/circuit state; verified recovery continues through wrighty provider probe, with any future manual override designed under the provider command.
• Deleting retained worktrees or branches.
• Configuration mutation or adding these operations to wrighty config.
• Web UI controls; the future operations console may consume the same read-only status model separately.
• A generic cache repair or clear all command.

Acceptance criteria

• wrighty cache path works inside or outside a Wrighty repository and reports the effective default or overridden root in human and versioned JSON form.
• wrighty cache status performs no filesystem, GitHub, tracker, or vendor mutation and reports all known stores with backend relevance, classification, health, sizes, versions, and safe aggregate counts.
• Status distinguishes GitHub-only node/session stores, backend-neutral identity/provider stores, and Local Markdown runtime state that is explicitly outside cache scope.
• Status never exposes raw identity, session, workspace, claim, deferred-dispatch, or provider-account data.
• Corrupt and unsupported schemas are reported per store without preventing other inventory results.
• wrighty cache clear node-ids is idempotent, clears valid or corrupt node-cache data, and leaves every protected store unchanged.
• Clearing node IDs requires no restart and existing GitHub discovery repopulates them correctly.
• Tests cover absent roots, default/overridden paths, healthy/missing/corrupt/unsupported stores, record counts, privacy, Local Markdown invocation, invocation outside a repository, concurrent node-cache activity, and byte-for-byte preservation of protected files.
• CLI help and storage reference documentation explain the backend-specific behavior and why no clear all operation exists.
• Add a concise user-facing entry to the [Unreleased] changelog when implemented.