Writer-lock timeout error names only the path, leaving an orphan lock unrecoverable in practice

[dustinmoon78]

What happened

A desktop host (a Tauri shell wrapping dsh web) was killed while writing a profile manifest. The withFileLock finally never ran, so ~/.dsh/profiles/web/package.json.lock survived holding a dead pid.

Every later writer then blocked for the full waitMs — the plugin manager passes 120s — and failed with:

atomic-write: timed out waiting for the writer lock at C:\Users\<user>\.dsh\profiles\web\package.json.lock

That message names the path and nothing else: not the pid the lock records, not what to do about it. withFileLock deliberately leaves orphan recovery to an operator, so the operator is exactly who needs those two facts — and the timeout error is the only place they are surfaced. In practice the failure reads as "installs and updates hang, then fail", with no route to the cause.

Why the lock is not recovered automatically

We agree with the current design: the recorded pid is not proof the owner is gone. On this machine the orphan lock's pid (2948) had already been reused by WindowsTerminal.exe before we looked, so any "pid is alive, keep the lock" check would have been wrong. File age has the same problem.

Suggested change

Keep the recovery decision manual, but make the timeout error carry the facts that decision needs:

• report the pid the lock records (omitted when the lock cannot be read);
• state that deleting the lock releases it when the recorded process is gone.

We could not open a pull request (the repository does not accept external ones at this stage), so the patch lives on a fork branch: https://github.com/dustinmoon78/deepseek-harness/tree/fix/atomic-write-lock-timeout (commit 6c6c829). It updates the package README and JSDoc and adds unit tests for the holder and unreadable-lock cases.