hermes - 💡(How to fix) Fix kanban_complete artifacts silently lost on scratch workspaces — file deleted before gateway notifier delivers

Summary

When a kanban worker calls kanban_complete(artifacts=[...]) on a scratch workspace task, the artifacts are always silently lost because _cleanup_workspace() deletes the workspace synchronously inside complete_task(), before the gateway notifier (running in a separate process) can read the files.

Sequence

Worker calls kanban_complete(artifacts=["/workspace/report.md"])
  │
  ├── 1. Event 'completed' appended to task_events DB (artifact paths in payload)
  ├── 2. _cleanup_workspace() → shutil.rmtree(workspace_path)  ← artifacts deleted
  └── 3. Returns to worker
               ...
               │ (0-5 seconds later)
               ▼
Gateway notifier polls, sees completed event
  → tries to upload /workspace/report.md
  → ❌ FILE NOT FOUND → silently skipped

Root cause

In hermes_cli/kanban_db.py, complete_task() calls _cleanup_workspace() synchronously at line 3254, after appending the completed event with artifact paths at line 3220. The gateway notifier polls task_events asynchronously (every 5 seconds in gateway/run.py:_kanban_notifier_watcher) and by the time it reads the artifact paths, the files are gone.

Impact

• Workers using scratch workspaces (the default) cannot successfully deliver artifacts via kanban_complete(artifacts=[...])
• The artifacts parameter silently does nothing for scratch workspace tasks
• Users expect artifacts to be delivered alongside completion notifications (per docs: "The gateway uploads each artifact as a native attachment")
• Workaround exists (use dir: workspace type), but scratch is the default

Relevant code

https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/kanban_db.py#L3220-L3254

• Line 3220-3224: event appended with artifact paths in payload
• Line 3254: workspace deleted

https://github.com/NousResearch/hermes-agent/blob/main/gateway/run.py#L4804-L4960

• The notifier polls asynchronously

Suggested fixes

1. Move cleanup to a background task — defer _cleanup_workspace to an async GC or have the notifier ack after delivery
2. Copy artifacts before cleanup — when metadata["artifacts"] is present, copy those files to a persistent location before deleting the scratch workspace
3. Document the limitation — at minimum, add a note that scratch workspaces lose artifacts and recommend dir: workspaces for tasks with deliverables

Environment

• Hermes Agent v0.15.2 (2026.5.29.2) — present on main branch
• Default scratch workspace
• Gateway notifier in separate process