55 lines
3.1 KiB
Markdown
55 lines
3.1 KiB
Markdown
---
|
|
title: "Add Pod archive and fresh-start path"
|
|
state: 'closed'
|
|
created_at: "2026-06-07T23:45:30Z"
|
|
updated_at: '2026-06-10T09:29:55Z'
|
|
queued_by: "workspace-panel"
|
|
queued_at: "2026-06-08T03:48:46Z"
|
|
---
|
|
|
|
## Background
|
|
|
|
Panel Companion and Orchestrator lifecycle currently restore restorable Pods by name before spawning a missing Pod. This is correct for normal continuity, but after updating workflows/profiles/system guidance, a user may want to intentionally start a fresh same-name Pod instead of restoring old Pod metadata/history.
|
|
|
|
Currently there is no explicit Panel/CLI path to archive or reset a restorable Pod name before fresh creation. The practical workaround is to manually rename/archive the Pod metadata directory under the user data dir, e.g. `~/.yoi/pods/<pod-name>/`, which is unsafe and not discoverable.
|
|
|
|
Example:
|
|
|
|
- Workspace Companion name is `yoi`.
|
|
- `yoi panel` sees `yoi` as restorable and restores it.
|
|
- User wants a fresh `yoi` Companion after workflow/profile changes.
|
|
- There is no `fresh` / `archive` action in Panel or CLI, so manual metadata directory surgery is the only apparent route.
|
|
|
|
## Goal
|
|
|
|
Provide an explicit, safe Pod archive/reset/fresh-start path for same-name Pods so users do not need to manually edit `~/.yoi/pods` metadata.
|
|
|
|
## Requirements
|
|
|
|
- Add a user-facing way to archive or reset a stopped/restorable Pod name so the next same-name launch is fresh.
|
|
- Refuse to archive/reset a live reachable Pod unless it is explicitly stopped first.
|
|
- Preserve old metadata/history by default; prefer archive/rename over destructive delete.
|
|
- Make the archive location/name deterministic and collision-safe.
|
|
- Surface what will happen clearly:
|
|
- archived Pod metadata will no longer be restored by name;
|
|
- session logs/history are preserved where applicable;
|
|
- next launch with the same name will create a fresh Pod.
|
|
- Support the Panel Companion use case where the workspace Companion name is fixed to the workspace basename, e.g. `yoi`.
|
|
- Consider both CLI and Panel/TUI surfaces.
|
|
- CLI examples could be `yoi pod archive <name>` or `yoi pod reset <name>`.
|
|
- Panel could expose a bounded action/diagnostic path for `fresh Companion` if appropriate.
|
|
- Keep normal lifecycle behavior unchanged: live -> use, restorable -> restore, missing -> spawn.
|
|
- Do not silently bypass restore just because profiles/workflows changed; fresh must be explicit.
|
|
- Avoid manual modification of `~/.yoi/pods` in docs except as an emergency/debug note.
|
|
|
|
## Acceptance criteria
|
|
|
|
- A stopped/restorable Pod can be archived via an official command/action.
|
|
- After archive, the same Pod name is treated as missing for attach/panel lifecycle and can be spawned fresh.
|
|
- Live Pods are protected from archive/reset without an explicit stop path.
|
|
- Archive preserves enough metadata/history for later inspection or manual recovery.
|
|
- Panel Companion `yoi` can be refreshed without hand-renaming data-dir metadata.
|
|
- Tests cover archive refusal for live Pods, archive success for stopped/restorable Pods, and fresh same-name spawn after archive.
|
|
- Relevant docs/help text are updated.
|
|
- `cargo test` focused suites, `cargo fmt --check`, `git diff --check`, and `target/debug/yoi ticket doctor` pass.
|