Skip to content

fix(kanban): preserve scratch workspace on completion, clean up on archive#38454

Closed
PINKIIILQWQ wants to merge 1 commit into
NousResearch:mainfrom
PINKIIILQWQ:feat/kanban-header-layout
Closed

fix(kanban): preserve scratch workspace on completion, clean up on archive#38454
PINKIIILQWQ wants to merge 1 commit into
NousResearch:mainfrom
PINKIIILQWQ:feat/kanban-header-layout

Conversation

@PINKIIILQWQ

@PINKIIILQWQ PINKIIILQWQ commented Jun 3, 2026

Copy link
Copy Markdown

This was the most confusing bug in kanban usage: I never specified a custom path, yet couldn't find my files at the default workspace location. After this fix, files are saved to the default workspace and never silently deleted — the right to delete stays with the user.


Problem

Scratch workspace files have two lifecycle bugs:

1. Silent deletion on kanban_complete
_cleanup_workspace() calls shutil.rmtree(wp) on the entire workspace directory, destroying all files the worker wrote to $HERMES_KANBAN_WORKSPACE with no recovery path. (#28818, #30151, #33774)

2. Stale workspace on archive
When a scratch task is archived, its workspace directory stays on disk indefinitely. New decomposed children inheriting the same workspace_path would write into a defunct folder, mixing old and new output.

Changes

Part A — Preserve scratch workspace on completion

File Change
hermes_cli/kanban_db.py Remove shutil.rmtree(wp) from _cleanup_workspace(). Tmux session cleanup preserved.
agent/prompt_builder.py KANBAN_GUIDANCE Step 2: document scratch vs dir workspace types. Files are permanent after completion.
hermes_cli/kanban.py Add kanban workspace path/ls/cp/link CLI subcommands for file access.
tests/hermes_cli/test_kanban_db.py Update 2 assertions (dir preserved after complete).
tests/tools/test_kanban_tools.py Update KANBAN_GUIDANCE size bound (4096 → 5000).

Part B — Clean up scratch workspace on archive

File Change
hermes_cli/kanban_db.py Add _cleanup_archive_workspace(): rmtree scratch dir + null out workspace_path in DB so future inheritors cannot pick up the stale path. Only scratch kind; dir/worktree preserved. Uses _is_managed_scratch_path() containment guard. Called from archive_task().

Behavior summary

  • scratch workspace: files are saved in the default workspace directory and never silently deleted — the user retains full control.
  • dir workspace: files are written directly to the specified path (e.g. the project repository).

Recommended usage

For project-based boards (e.g. building an app in a git repo), set the board's default_workdir and create tasks with --workspace dir:

hermes kanban boards set-default-workdir <board> /path/to/project
hermes kanban create "Build feature" --assignee dev --workspace dir

This makes $HERMES_KANBAN_WORKSPACE point directly to the project directory, so worker output lands in the repo without any extra file copying.

Backward compatibility

No schema changes. No new config. dir:/worktree workspaces unchanged. Path guard (#28818) still works.

@alt-glitch alt-glitch added comp/plugins Plugin system and bundled plugins type/bug Something isn't working P3 Low — cosmetic, nice to have labels Jun 3, 2026

@tonydwb tonydwb left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of PR #38454: fix(kanban): preserve scratch workspace files on task completion

Issues

  • Found secret pattern in diff; double-check.
  • Found debug pattern in diff; double-check.
  • Found todo pattern in diff; double-check.

Reviewed by Hermes Agent

@PINKIIILQWQ PINKIIILQWQ force-pushed the feat/kanban-header-layout branch from 62095b6 to 9574ba6 Compare June 4, 2026 10:27
@PINKIIILQWQ PINKIIILQWQ changed the title fix(kanban): preserve scratch workspace files on task completion fix(kanban): preserve scratch workspace on completion, clean up on archive Jun 4, 2026
@PINKIIILQWQ PINKIIILQWQ marked this pull request as draft June 4, 2026 10:30
…chive

Two complementary lifecycle fixes for kanban scratch workspaces:

Part A — Preserve scratch workspace on task completion
_cleanup_workspace() was silently deleting all worker output on
kanban_complete via shutil.rmtree. Remove the rmtree call so files
the worker wrote to $HERMES_KANBAN_WORKSPACE remain accessible.
- kanban_db.py: delete shutil.rmtree from _cleanup_workspace()
- kanban.py: add workspace path/ls/cp/link CLI subcommands
- prompt_builder.py: update KANBAN_GUIDANCE; document scratch
  vs dir workspace types
- test_kanban_db.py/test_kanban_tools.py: update assertions

Part B — Clean up scratch workspace on archive
When a scratch task was archived, its workspace directory stayed on
disk indefinitely. Add _cleanup_archive_workspace(): rmtree the
scratch dir + null out workspace_path in the DB.
- Only touches workspace_kind='scratch'. dir/worktree preserved.
- Uses _is_managed_scratch_path() containment guard.
- Called from archive_task() after DB txn + recompute_ready().

Closes NousResearch#33774
@PINKIIILQWQ PINKIIILQWQ force-pushed the feat/kanban-header-layout branch from 9574ba6 to fc8afd5 Compare June 4, 2026 13:03
@PINKIIILQWQ PINKIIILQWQ marked this pull request as ready for review June 4, 2026 13:39
@PINKIIILQWQ

Copy link
Copy Markdown
Author

Validation

Full test suite: 211/211 passed (test_kanban_db.py).

Also validated in production on a multi-task pipeline (hermes-android-mvp board):

  • kanban_complete preserves workspace files (no silent deletion)
  • archive_task cleans up scratch directory and nulls out workspace_path
  • dir workspace writes directly to project root — no extra file copying needed
  • ✅ Existing done tasks unaffected; dir/worktree workspaces unchanged

@teknium1

teknium1 commented Jun 7, 2026

Copy link
Copy Markdown
Contributor

Closing in favor of #41352, which fixes #33774 with a smaller, targeted change: scratch workspaces are deferred (not deleted) while linked children are active, then swept once all children are terminal. Your approach (never delete on completion, only on archive) changes the scratch lifecycle contract more broadly — the disk-growth tradeoff there is a separate product decision we'd rather handle on its own. Appreciate the thorough writeup on the silent-deletion problem; it helped frame the fix. Thanks!

@teknium1 teknium1 closed this Jun 7, 2026
@PINKIIILQWQ

Copy link
Copy Markdown
Author

Closing in favor of #41352, which fixes #33774 with a smaller, targeted change: scratch workspaces are deferred (not deleted) while linked children are active, then swept once all children are terminal. Your approach (never delete on completion, only on archive) changes the scratch lifecycle contract more broadly — the disk-growth tradeoff there is a separate product decision we'd rather handle on its own. Appreciate the thorough writeup on the silent-deletion problem; it helped frame the fix. Thanks!

Hey Teknium,

This isn't really about a specific PR.

Over the last week I've been experimenting with building a kanban-centric software development / issue-fixing workflow around Hermes. During that process I've gone through roughly 3B tokens,
screenshot 2026-06-08 04 38 58

contributed a handful of small PRs (mostly around usability, visibility, and workflow improvements), and spent a lot of time reading related issues and discussions.
sth like this.
Recording 2026-06-04 at 03-09-24

One thing I've started noticing is that several seemingly unrelated problems actually feel connected.

The scratch workspace discussion is what made me realize it.

After reading through #28818, #33774, #33916, #38454, #41352 and the related user reports, I think the engineering side of the problem is fairly clear. #41352 solves the parent-child handoff issue without changing the overall workspace lifecycle, which makes sense as a focused fix.

What I found more interesting was the user feedback.

The recurring theme wasn't really "I disagree with auto-deletion."

It was closer to:

"I didn't realize this workspace would be deleted."

That distinction feels important.

From an engineering perspective, "scratch" often implies temporary or disposable storage. But looking at the reports, many users seem to interpret it as "create a new workspace from scratch" rather than "create a workspace that will be automatically removed later."

The docs are clear. The tip exists.

Yet multiple users still independently arrive at the same misunderstanding.

To me, that's usually a sign that the issue is less about documentation and more about how information is surfaced during the workflow itself.

One other observation that might be relevant:

I suspect the Hermes audience today may be broader than many of us assume.

A growing number of users seem to be coming from AI-assisted development workflows rather than traditional software engineering backgrounds. Some are vibe coders, product builders, founders, designers, or people who learned programming through AI tools rather than through conventional engineering environments.

For those users, terms like "scratch" may not naturally imply disposable storage.

The more common interpretation is often simply:

"start from scratch"

— a fresh workspace, not a temporary one.

I also noticed that parts of the Kanban experience remain untranslated for non-English users. In those cases, users may see the raw term "scratch" without any additional context in their native language. That makes the mental-model gap even more understandable.
like German
截屏2026-06-08 04 48 58

What's interesting is that I've noticed a similar pattern elsewhere too.

Many of the usability improvements I've worked on recently weren't really about adding new capabilities.

They were about making existing system state more visible at the moment users make decisions.

That's why I no longer think the most interesting question here is whether scratch should auto-delete or not.

The more interesting question, at least to me, is whether users are building the same mental model of the system that Hermes expects them to have.

Anyway, I don't have a strong proposal here. I just wanted to share an observation from the perspective of a very heavy user who is trying to build real development workflows around Hermes.

For what it's worth, Hermes is one of the most interesting agent systems I've used, which is exactly why I've spent so much time thinking about these things.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/plugins Plugin system and bundled plugins P3 Low — cosmetic, nice to have type/bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants