adapter-openclaw: workspace state-dir resolution falls back to home-dir; gateway runtime APIs not exposed

[Jurij89]

Symptom

Every gateway start logs this warn from the dkg-adapter-openclaw plugin:

[plugins] [dkg] Could not resolve a workspace-scoped state dir
(api.runtime.state.resolveStateDir / OPENCLAW_STATE_DIR / api.workspaceDir all unavailable);
falling back to '/home/<user>/.openclaw'. Two workspaces on the same machine
will share chat-turn watermarks. Set OPENCLAW_STATE_DIR explicitly to silence this.

Tested on OpenClaw 2026.4.15 (041266a) running against feat/dkg-memory-integration (current state of PR #264). Reproduces on every cold start.

What's affected

The adapter's ChatTurnWriter writes a single small JSON file — <stateDir>/dkg-adapter/chat-turn-watermarks.json — that holds per-session pair-counter watermarks for delta-detection across gateway restarts. Without a workspace-scoped path, the file lands in the home-dir fallback ~/.openclaw/dkg-adapter/chat-turn-watermarks.json.

For single-workspace deployments (the common operator shape) this is harmless. For two workspaces on the same host, the watermark file is shared — a chat in workspace A will trip the delta-detection in workspace B and may cause re-persists or skipped turns.

The fallback is documented in the warn itself, but the warn is currently a permanent feature of every healthy startup, which dilutes the signal of real problems.

Where the resolution happens

packages/adapter-openclaw/src/DkgNodePlugin.ts:555-576 — the adapter tries three sources in order:

1. `(api as any)?.runtime?.state?.resolveStateDir?.()` — gateway-provided, workspace-scoped.
2. `process.env.OPENCLAW_STATE_DIR` — operator-controlled, opt-in.
3. `(api as any)?.workspaceDir` — gateway-provided, workspace-scoped derived path.

All three return `undefined` on the current gateway version, so the warn fires and the fallback engages.

Suggested fixes (any one — multiple acceptable)

1. Gateway-side: have the OpenClaw gateway populate `api.workspaceDir` (or expose `api.runtime.state.resolveStateDir`) for plugins so they can derive a per-workspace path without relying on operator env config. This is the cleanest fix because it removes a pointless warn from every healthy startup.

2. Adapter-side workaround (cheap): extend `DkgOpenClawConfig` with an explicit `stateDir` field (mirroring the `dkgHome` pattern we added in T42). Operators can set it once in `openclaw.json` and the warn never fires. This shifts the burden to the operator but is simple and immediate.

3. Adapter-side derivation (medium): derive a workspace-scoped path from another signal — e.g., `process.cwd()`, the openclaw config file's directory, or a hash of the gateway's port. Less reliable than (1) but eliminates the fallback warn.

Related context

PR #264 is the source of this code (the warn was introduced as part of the initial wiring). The fallback path itself was a deliberate choice for "ship now" operability — see the comment block at `DkgNodePlugin.ts:550-576`. This issue is the follow-up to make it a true error path again.

Reproduction

```bash
DKG_HOME=/home//.dkg-dev openclaw gateway run --force
```

Grep for `Could not resolve a workspace-scoped state dir` in the gateway log on any clean startup.

Workaround

Set `OPENCLAW_STATE_DIR` explicitly:

```bash
DKG_HOME=/home//.dkg-dev OPENCLAW_STATE_DIR=/home//.dkg-dev/openclaw-state openclaw gateway run --force
```

Watermark file lands at `$OPENCLAW_STATE_DIR/dkg-adapter/chat-turn-watermarks.json` and the warn is silenced.

[Jurij89]

Closed by merged PR #337 (f9fda58) into feat/dkg-memory-integration.