[DISCUSS] Task lifecycle and storage: archiving, cleanup and retention for Desktop tasks

[liugddx]

Why this

A Desktop task (Session) stays exactly where it was left once it is created. Nothing archives it when it goes idle, nothing expires it, and nowhere in the product shows how much disk the accumulated tasks take. Tasks are also a heavy object: each one can accumulate artifacts, context-offload blobs, subagent worktrees and runtime events. Long-running users therefore collect a sidebar they have to prune by hand, and a workspace that only grows.

Before proposing any code, I wanted to (1) pin down exactly what Maka does today, and (2) look at how comparable products handle this. Some of the choices here delete user data, so I'd like agreement on direction first.

What Maka does today (upstream/main c9a176e10)

Already there

• States. Run state (active, running, waiting_for_user, blocked, aborted) is independent of archival (isArchived). "Pin" is isFlagged. The Host lifecycle is active | archived (protocol/session-retirement.ts).
• Sidebar. Single tasks can be pinned, renamed, archived or moved to a project. Multi-select supports archive and pin. Grouping is by time or by project.
• Settings › Activity › Archived tasks. Restore, delete one, search, and "Delete all archived" (scoped to the current search).
• Deleting a parent task first shows how its subagent tasks will be handled (Deleting a parent task gives no warning that its subtasks are kept and archived #3780). The subagent tasks are archived, not deleted.
• Delete is a real hard delete. A tombstone is committed first; then a background queue removes artifacts, context-offload references, subagent worktrees, runtime events and todos. Retirements left unfinished are completed at startup.
• Single-task export/import through .maka-session bundles.
• Scheduled tasks have active | paused | completed | expired. Work Board items have todo | in_progress | done plus an independent archived flag.

Gaps

	Gap
G1	No automatic policy of any kind: no archive after idle, no expiry of archived tasks, no retention setting. I found no issue asking for one.
G2	Deleting requires archiving first. The sidebar has no delete.
G3	Storage is invisible and not fully reclaimed. Nothing shows per-task or total size. runtime.sqlite is not vacuumed after deletes, so the file does not shrink. #5341 leaves artifact previews behind after deletion.
G4	No workspace-level or multi-task export or backup. Config export excludes tasks.
G5	The archived page can only filter by keyword. You cannot select by age or project and clean up in bulk.
G6	"Done" never tidies itself away. A done Work Board item stays unarchived, and a completed or expired scheduled task stays until deleted.

How comparable products handle it

I surveyed about 30 products: coding agents first, general assistants for reference. Defaults are from official docs where available; see the note on sources below.

Coding agents

Product	Manual actions	Automatic policy (default)	Disk usage shown
Claude Code CLI	purge per project; remove from agent view	cleanupPeriodDays: 30 days, hard delete of transcripts across all projects, run at startup	no
Claude Code Desktop	archive; archived filter to restore	transcripts kept indefinitely (desktopSessionCleanupPeriodDays = 0); opt-in auto-archive when the task's PR merges or closes (off by default)	no
Codex CLI	archive / unarchive / delete (delete removes descendants)	none per session; only history.max_bytes for input history	no
Codex app	archive / unarchive only	none documented	no. Users complain that there is no delete and no bulk archive.
Cursor	Agents window: archive only; editor: delete; "Delete Old Chats…" by age	none	no. Users complain that archive frees no disk.
VS Code agent sessions	pin, archive, delete, multi-select, mark group done	two-stage, off by default, suggested 15 days: auto-mark done N days after the PR merges, then delete N days later. It only deletes auto-marked sessions (manual archives are kept) and never force-deletes a worktree.	no
Gemini CLI	delete from the resume picker	sessionRetention on by default in recent versions: 30 days, with a 1-day minimum	no
Cline	delete one, multi-select, delete all; favourites protected	none	tokens and cost
Roo Code	bulk delete	none	per-task size
Kilo Code	"Run cleanup now"	opt-in auto-cleanup (30 days). It skips sessions written to in the last hour, compacts the database afterwards and reports freed space; favourites were never deleted in the legacy version.	freed space after cleanup
OpenCode	CLI delete	none; one report of a 12 GB database	no
Zed	archive, delete	none	no

General assistants (for reference)

• ChatGPT. Archive and delete, "archive all" and "delete all", no multi-select. Saved chats are kept forever; temporary chats for 30 days. Scheduled tasks can be active, paused, or auto-paused when inactive.
• Claude.ai. Multi-select and select-all delete. Projects can be archived (unarchive before deleting). Incognito chats last 30 days.
• Gemini. The only consumer product with user-facing auto-delete: 3 / 18 / 36 months or off, default 18.
• Perplexity, Microsoft Copilot, Manus, and Chinese assistants. Mostly delete one or delete all. Retention is either fixed (Copilot, 18 months) or absent. Bulk delete is a common gap that browser extensions fill.

What the survey suggests

1. Archive is the reversible default and delete is explicit. Every product treats archive as "put away, still searchable, restorable". Delete is confirmed and irreversible; I found no product with a trash bin. Maka already matches this.
2. Two failure modes to avoid.
   • Archive-only (Cursor Agents, Codex app) draws steady complaints, because archive does not free disk.
   • Silent default hard delete (Claude Code CLI, 30 days) generated many reports of lost history. The same vendor keeps Desktop transcripts forever by default.
3. The most careful automatic design is event-driven with a grace period (VS Code): mark done on a real signal (PR merged), delete only after a further delay, delete only what automation marked, and protect worktrees. It is off by default.
4. When auto-delete exists, it is opt-in with preset durations (Gemini, Kilo). Recurring guardrails:
   • a minimum retention period;
   • skip recently active sessions;
   • never delete pinned or favourite sessions;
   • never delete a worktree with unpushed work;
   • manual actions win over automatic ones.
5. Storage visibility is almost universally missing. Only Roo Code shows per-task size, and Kilo reports freed space. For a local agent app that accumulates artifacts and worktrees, this is a cheap and meaningful gap to close.

Proposed direction (for discussion)

In order of value versus risk:

1. Make storage visible and reclaimable (G3). The Data page shows total usage by kind (database, artifacts, context offload, worktrees). The archived list shows per-task size. Deletes are followed by an incremental vacuum. Fix fix(desktop): managed artifact previews outlive deletion and share one global quota #5341. This changes no data semantics, so I'd suggest it as the first step.
2. Scoped bulk cleanup on the archived page (G5, G2). Select by "archived more than N days ago" or by project. The delete confirmation spells out what goes with the task: artifacts, worktrees, subagent tasks.
3. Opt-in retention for archived tasks (G1). "Delete archived tasks after 30 / 90 / 180 days", off by default, with the guardrails above: never pinned, never with unmerged worktree changes, a minimum age, and a visible result.
4. Opt-in idle and event-driven archiving (G1, G6). Archive after N idle days (no running turn, no pending interaction). Archive when a Work Board item is marked done or a scheduled task completes or expires, and, if a task gains a PR link, when it merges or closes. If both 3 and 4 exist, only automatically archived tasks should ever be automatically deleted.

Questions for maintainers

1. Is task lifecycle and storage management in scope for Desktop now, and is step 1 (visibility and reclaim) acceptable as a first PR?
2. Should anything that deletes data automatically exist at all, or should Maka stay manual-only plus better bulk tools? If it exists, is "off by default, archived tasks only, preset durations" the right shape?
3. Where should the policy live? My assumption is the Runtime Host (next to session-retirement and storage-maintenance), exposed as runtime policy, so that it applies to every client of a Host rather than to one Desktop window.
4. Is a PR-merge signal something Maka should model for tasks, or should event-driven archiving stay limited to Work Board and scheduled tasks?

---

Note on sources: coding-agent defaults come from each product's docs (Claude Code settings reference, Codex CLI and config reference, the VS Code agent-sessions docs, the Gemini CLI session-management doc, the Kilo session-history and auto-cleanup docs). User pain points come from their public issue trackers and forums. General-assistant behaviour comes from official help centres. A few entries (Zed, Warp, Devin) rely on search summaries and are the least certain. I can post the full per-product notes with links if useful.

AI disclosure: Claude Code (Claude Opus) surveyed the codebase and the public documentation and drafted this post; liugddx reviewed it.

[me2seeks]

I support the proposed first step: make storage usage visible, finish reclaiming data after deletion, and improve scoped manual cleanup.

For the later automatic policies, I think the Runtime Host must own both the decision and the execution. Desktop should expose the settings and results, while the Host reuses its existing Session retirement path and busy-session checks. Automatic archiving and deletion of archived Sessions after a retention period should be separate, opt-in settings, both off by default. There is currently a Host archive command, but no general idle/completion/PR-driven auto-archive policy.

I would apply an enabled retention policy to all archived Sessions, including manually archived ones. Restoring a Session cancels its deletion deadline; archiving it again starts a new deadline. This needs a durable archivedAt timestamp. For already-archived Sessions without one, the clock should start no earlier than policy enablement, avoiding immediate deletion of old data. Deletion should recheck the current policy, archive state, retirement guards, and any protected worktree state immediately before committing.

The proposed archive triggers need different authoritative facts:

• Idle: durable activity can identify candidates, but the Host must recheck the whole Session family and all retirement guards before archiving. A completed Turn alone is not a completed task.
• Work completed: require an explicit work-item-to-Session relationship. Work Board state is currently owned by Desktop main, so its done transition is not yet a Host-owned fact that can drive a cross-client policy. A completed ScheduledTask also does not necessarily mean a session_resume Session is finished.
• PR merged/closed: require an explicit, durable Session-to-PR association and verify the PR state. Do not infer it from branch names or conversation text. Reconcile changes missed while the Host was offline; a failed check must leave the Session unchanged.

This suggests shipping storage visibility and manual cleanup first, then Host-owned idle archiving. Completion and PR triggers can follow once their fact sources and exact meanings are established. I would update the proposal's “only automatically archived tasks should ever be automatically deleted” sentence to reflect that opt-in retention also covers manual archives.

中文说明（点击展开）

我支持先做空间占用展示、删除后的空间回收，以及按范围手动清理。

后续的自动策略应由 Runtime Host 判断并执行；Desktop 负责展示设置和结果。自动归档与“已归档会话到期删除”是两个独立开关，默认都关闭。Host 已有归档命令，但目前没有按空闲、完成或 PR 状态自动归档普通会话的通用策略。

用户开启到期删除后，手动归档和自动归档的会话都适用。恢复会话即取消删除倒计时；再次归档则重新计时。需要持久化 archivedAt。对于启用策略前已经归档、但没有归档时间的旧会话，最早从启用当天开始计时，避免刚开启就立即删除。真正删除前还要重新核对策略、归档状态、退役条件及受保护的 worktree 状态。

三个归档触发条件分别需要可靠事实：空闲时间只能筛选候选，执行前仍要由 Host 检查整个会话版本族是否忙碌；Work Board 的 done 目前由 Desktop 主进程持有，不能直接充当 Host 跨客户端策略的权威事实，定时任务完成也不等于其 session_resume 会话完成；PR 触发则需要明确、持久的会话与 PR 关联及状态核验，不能根据分支名或对话文字猜测，Host 离线期间错过的变化应在恢复后重新核验。

因此建议先交付空间与手动清理，再加入 Host 的空闲归档；完成和 PR 触发等事实来源及语义确定后接入。原帖“只有自动归档的任务才能自动删除”应改为：用户主动开启保留期限后，手动归档的任务也适用。

[somewan820]

I agree with the proposed direction and would suggest treating it as a phased lifecycle and storage-management effort.

The priority order should be:

1. Storage visibility and manual reclamation
   Show total and per-task usage for the database, artifacts, context offload, and worktrees. Make reclamation explicit and observable, and address lifecycle issues such as fix(desktop): managed artifact previews outlive deletion and share one global quota #5341.

2. Bulk deletion for archived tasks
   Add filtering by archive age and project. Before deletion, show the number of affected tasks and the resources that will be removed.

3. Opt-in retention policy, disabled by default
   Apply it only to tasks archived automatically, with preset periods such as 30, 90, and 180 days. Pinned tasks, recently active tasks, and tasks with unpushed worktree changes should be protected.

4. Event-driven archiving later
   Work Board completion and scheduled-task completion/expiry seem better starting points than PR merge events. PR-based lifecycle actions should wait until Session-to-PR association and event authority are modeled explicitly.

A few safeguards seem essential:

• Worktree safety must be determined by the Host/worktree layer, not by the Desktop renderer.
• Automatic deletion must only apply to tasks explicitly marked as automatically archived; manual archives should remain protected.
• SQLite reclamation should run as bounded background maintenance after Host readiness, with failure reporting and visible reclaimed-space results.

I would support making storage visibility and safe manual reclamation the first concrete milestone, while keeping automatic retention and event-driven archiving for later phases.

中文翻译

我赞同这个方向，并建议把它作为一个分阶段的任务生命周期和存储管理工作来推进。

优先顺序可以是：

1. 存储可见性和手动回收
   展示数据库、artifact、context offload 和 worktree 的总量及单任务占用。回收操作应该由用户明确触发，并且结果可观察；同时处理 fix(desktop): managed artifact previews outlive deletion and share one global quota #5341 这类生命周期问题。

2. 已归档任务的批量删除
   支持按归档时间和项目筛选。删除前展示受影响的任务数量，以及将被删除的资源范围。

3. 默认关闭的可选保留策略
   只作用于自动归档的任务，提供 30、90、180 天等预设周期。应保护 pinned 任务、近期活跃任务，以及存在未推送 worktree 变更的任务。

4. 后续再做事件驱动归档
   Work Board 完成和 scheduled task 完成/过期似乎比 PR merge 更适合作为早期事件。基于 PR 的生命周期动作应等 Session 与 PR 的关联关系及事件权威来源明确后再做。

我认为以下保护措施是必要的：

• worktree 是否安全必须由 Host/worktree 层判断，不能依赖 Desktop renderer。
• 自动删除只能作用于明确标记为“自动归档”的任务，用户手动归档的任务应继续保留。
• SQLite 回收应在 Host ready 后作为有边界的后台维护执行，并报告失败情况和实际释放的空间。

我支持把“存储可见性 + 安全的手动回收”作为第一阶段的具体目标，把自动保留和事件驱动归档放到后续阶段。

[liugddx]

Thanks both. This settles the first step and sharpens the later ones.

Step 1 has agreement, and I'll start on it. As both of you said, the Host computes and executes, and Desktop presents. From a first pass over main, I plan three independently shippable PRs:

• M1, visibility (read-only).
  • A new Host query storage.usage.query reports totals by kind (database, transcripts, artifacts, context offload, worktrees, memory, retained usage history) and reclaimable free pages.
  • It also reports per-task sizes for a bounded page of sessions, computed on demand and cached. There are no write-path triggers, so no added write amplification.
  • The Data page and the Tasks page present the results.
• M2, reclamation.
  • context-offload.sqlite is already auto_vacuum=INCREMENTAL but is never vacuumed, so it gets a bounded incremental_vacuum lane in the existing storage maintenance loop.
  • runtime.sqlite is auto_vacuum=NONE. Converting it needs one full VACUUM, which I'd run only on explicit user request, before Host readiness on the next start, after a free-disk check.
• M3, scoped cleanup.
  • Add a durable archived_at. Sessions archived before this field existed show "archive time unknown" and are left out of age filters.
  • Add a batch session.remove.preview that reports tasks, child tasks, bytes and worktrees.
  • The Tasks page gets "archived more than N days" and project filters.

#5341 turned out to be an in-memory preview lease rather than disk residue, and #5394 already fixes it at the Host retirement hook, so step 1 will depend on that PR rather than redo it. I'll open a tracking issue with the details. Two questions for maintainers there: is the explicit-request, pre-Ready conversion of runtime.sqlite acceptable? And should archived_at land as a small standalone PR, since step 2 reuses it?

On retention scope, I'd like to adopt @me2seeks's model and withdraw my "only automatically archived tasks may be automatically deleted" line.

• What the setting applies to. Once a user explicitly enables "delete archived tasks after N days", the plain reading is "archived tasks", manual or automatic. Limiting it to automatic archives would leave users unable to tell which archived tasks the setting covers.
• The safeguards come from how the deadline is set.
  • A durable archivedAt.
  • For tasks archived before the policy existed, the clock starts no earlier than the day the policy is enabled, so enabling it never deletes a backlog at once.
  • Restoring a task cancels its deadline; archiving again starts a new one.
  • Right before deleting, the Host rechecks the policy, the archive state, the retirement guards and worktree protection.
• Pinned tasks stay excluded.
• @somewan820, does that address your concern about manual archives? The protection moves from "never" to "only after an explicit opt-in, with a fresh clock".

On automatic archive triggers, I agree with the ordering @me2seeks describes:

• Host-owned idle archiving first. Idle is only a candidate signal; the Host rechecks the whole Session family and the retirement guards before acting.
• Work Board completion later. It waits until its state is a Host-owned fact rather than Desktop-main state.
• PR merge/close later still. It needs an explicit, durable Session–PR association and verified PR state, reconciled after the Host has been offline.

Automatic archiving and retention stay two separate, opt-in settings, both off by default.

Revised plan

1. Storage visibility, reclamation and scoped manual cleanup.
2. Opt-in retention for archived tasks, with durable archivedAt and the start-no-earlier-than-enablement rule.
3. Opt-in, Host-owned idle archiving.
4. Completion- and PR-driven archiving, once their fact sources exist.

中文说明

感谢两位。第一步已有共识，我这边开始推进。 由 Host 计算和执行，Desktop 负责展示。计划拆成三个可独立交付的 PR：

• M1 占用可见（只读）
  • 新增 Host 查询 storage.usage.query：返回按类别的总量和可复用的空闲页。
  • 单个任务的大小：只对可见的一页按需计算并缓存，不加写入触发器。
• M2 空间回收
  • context-offload 库已经是增量模式，但从未执行过回收，所以在现有维护循环里加一条限量的回收车道。
  • runtime.sqlite 转成增量模式需要一次完整的 VACUUM：只在用户显式请求后、下次 Host 启动进入 Ready 之前执行，并先检查可用磁盘。
• M3 按范围清理
  • 新增持久化的 archived_at。旧的已归档任务显示"归档时间未知"，不参与按时长筛选。
  • 新增批量删除预览。
  • 任务页加"归档超过 N 天"和按项目的筛选。

#5341 实际是内存里的预览 lease 泄漏，不是磁盘残留，#5394 已经在修，所以第一步依赖它，不重复实现。细节会放在跟踪 issue 里。请维护者确认两点：runtime.sqlite 的转换方式是否可接受；archived_at 是否单独作为前置小 PR。

关于到期删除的范围，我采纳 @me2seeks 的方案，撤回原帖"只有自动归档的任务才能被自动删除"的说法。

• 用户主动开启"已归档 N 天后删除"后，自然理解是所有已归档任务都适用。
• 保护措施：
  • 持久化 archivedAt；
  • 开启前就已归档的任务，最早从开启当天开始计时；
  • 恢复即取消倒计时，再次归档重新计时；
  • 删除前再次核对策略、归档状态、退役条件和 worktree 保护；
  • 置顶的任务始终排除。
• @somewan820，这样能否打消你对手动归档的顾虑？

关于自动归档的触发条件，同意 @me2seeks 的顺序：

• 先做 Host 负责的闲置归档；
• Work Board 完成要等它的状态成为 Host 掌握的事实之后；
• PR 触发要等有了明确、持久的"会话↔PR"关联之后。

自动归档和到期删除是两个独立开关，都默认关闭。

[somewan820]

Thanks for incorporating the feedback. This revised plan works for me.

I agree with the Host/Desktop boundary and the proposed sequencing:

• M1 makes storage usage visible without adding write-path overhead.
• M2 provides explicit reclamation, with runtime.sqlite conversion only after a user request.
• M3 adds durable archived_at and scoped manual cleanup.
• archived_at is also a suitable foundation for the later retention policy.

The revised retention model addresses my concern about manual archives. Once the user explicitly enables “delete archived tasks after N days”, it is reasonable for the policy to cover both manually and automatically archived tasks. The start-no-earlier-than-enablement rule, reset-on-restore/re-archive behavior, pinned-task protection, and final Host-side recheck provide the necessary safeguards.

I also agree with the ordering for automatic archiving: Host-owned idle archiving first, Work Board completion after its state becomes Host-owned, and PR-driven archiving only after a durable Session–PR association and offline reconciliation are available.

I support proceeding with this revised plan.

中文翻译

感谢你吸收前面的反馈。这版计划对我来说是可接受的。

我认同 Host/Desktop 的职责边界和当前的分阶段顺序：

• M1 让用户看到空间占用，同时不增加写入路径的开销；
• M2 提供明确的空间回收，runtime.sqlite 的转换只在用户主动请求后执行；
• M3 增加持久化的 archived_at 和按范围手动清理；
• archived_at 也适合作为后续保留策略的基础。

新的保留策略解决了我对手动归档的顾虑。用户主动开启“已归档 N 天后删除”后，让它同时适用于手动归档和自动归档是合理的。最早从启用日开始计时、恢复/重新归档时重置计时、保护置顶任务，以及删除前由 Host 再次核对，这些保护措施已经足够明确。

我也认同自动归档的顺序：先做 Host 负责的闲置归档；等 Work Board 状态成为 Host 掌握的事实后，再接入完成触发；PR 触发则等持久化的 Session–PR 关联和离线恢复后的状态核验具备之后再做。

我支持按这版计划继续推进。